FabGL
ESP32 Display Controller and Graphics Library
fabgl::VGA16Controller Class Reference

Represents the VGA 16 colors bitmapped controller. More...

#include <vga16controller.h>

Inherits fabgl::GenericBitmappedDisplayController.

Public Member Functions

void begin (gpio_num_t redGPIO, gpio_num_t greenGPIO, gpio_num_t blueGPIO, gpio_num_t HSyncGPIO, gpio_num_t VSyncGPIO)
 This is the 8 colors (5 GPIOs) initializer. More...
 
void begin (gpio_num_t red1GPIO, gpio_num_t red0GPIO, gpio_num_t green1GPIO, gpio_num_t green0GPIO, gpio_num_t blue1GPIO, gpio_num_t blue0GPIO, gpio_num_t HSyncGPIO, gpio_num_t VSyncGPIO)
 This is the 64 colors (8 GPIOs) initializer. More...
 
void begin ()
 This is the 64 colors (8 GPIOs) initializer using default pinout. More...
 
DisplayControllerType controllerType ()
 Determines the display controller type. More...
 
void enableBackgroundPrimitiveExecution (bool value)
 Enables or disables drawings inside vertical retracing time. More...
 
void enableBackgroundPrimitiveTimeout (bool value)
 Enables or disables execution time limitation inside vertical retracing interrupt. More...
 
uint8_t getBitsPerChannel ()
 Gets number of bits allocated for each channel. More...
 
int getScreenHeight ()
 Determines the screen height in pixels. More...
 
int getScreenWidth ()
 Determines the screen width in pixels. More...
 
int getViewPortCol ()
 Determines horizontal position of the viewport. More...
 
int getViewPortHeight ()
 Determines vertical size of the viewport. More...
 
int getViewPortRow ()
 Determines vertical position of the viewport. More...
 
int getViewPortWidth ()
 Determines horizontal size of the viewport. More...
 
bool isDoubleBuffered ()
 Determines whether BitmappedDisplayController is on double buffered mode. More...
 
void moveScreen (int offsetX, int offsetY)
 Moves screen by specified horizontal and vertical offset. More...
 
NativePixelFormat nativePixelFormat ()
 Represents the native pixel format used by this display. More...
 
void processPrimitives ()
 Draws immediately all primitives in the queue. More...
 
void refreshSprites ()
 Forces the sprites to be updated. More...
 
void removeSprites ()
 Empties the list of active sprites. More...
 
void resumeBackgroundPrimitiveExecution ()
 Resumes drawings after suspendBackgroundPrimitiveExecution(). More...
 
void setMouseCursor (Cursor *cursor)
 Sets mouse cursor and make it visible. More...
 
void setMouseCursor (CursorName cursorName)
 Sets mouse cursor from a set of predefined cursors. More...
 
void setMouseCursorPos (int X, int Y)
 Sets mouse cursor position. More...
 
void setPaletteItem (int index, RGB888 const &color)
 Determines color of specified palette item. More...
 
void setProcessPrimitivesOnBlank (bool value)
 Determines the maximum time allowed to process primitives. More...
 
void setResolution (char const *modeline, int viewPortWidth=-1, int viewPortHeight=-1, bool doubleBuffered=false)
 Sets current resolution using linux-like modeline. More...
 
template<typename T >
void setSprites (T *sprites, int count)
 Sets the list of active sprites. More...
 
void shrinkScreen (int shrinkX, int shrinkY)
 Reduces or expands screen size by the specified horizontal and vertical offset. More...
 
void suspendBackgroundPrimitiveExecution ()
 Suspends drawings. More...
 

Static Public Member Functions

static VGA16Controllerinstance ()
 Returns the singleton instance of VGA16Controller class. More...
 

Static Public Attributes

static int queueSize = FABGLIB_DEFAULT_DISPLAYCONTROLLER_QUEUE_SIZE
 Size of display controller primitives queue. More...
 

Detailed Description

Represents the VGA 16 colors bitmapped controller.

This VGA controller allows just 16 colors, but requires less (1/2) RAM than VGAController, at the same resolution. Each pixel is represented by 4 bits, which is an index to a palette of 64 colors. Each byte of the frame buffer contains two pixels. For example, a frame buffer of 640x480 requires about 153K of RAM.

VGA16Controller output is very CPU intensive process and consumes up to 30% of one CPU core. Anyway this allows to have more RAM free for your application.

This example initializes VGA Controller with 64 colors (16 visible at the same time) at 640x480:

fabgl::VGA16Controller displayController;
// the default assigns GPIO22 and GPIO21 to Red, GPIO19 and GPIO18 to Green, GPIO5 and GPIO4 to Blue, GPIO23 to HSync and GPIO15 to VSync
displayController.begin();
displayController.setResolution(VGA_640x480_60Hz);
Examples:
VGA/AnsiTerminal/AnsiTerminal.ino, and VGA/SimpleTerminalOut/SimpleTerminalOut.ino.

Member Function Documentation

◆ begin() [1/3]

void fabgl::VGA16Controller::begin ( gpio_num_t  redGPIO,
gpio_num_t  greenGPIO,
gpio_num_t  blueGPIO,
gpio_num_t  HSyncGPIO,
gpio_num_t  VSyncGPIO 
)

This is the 8 colors (5 GPIOs) initializer.

One GPIO per channel, plus horizontal and vertical sync signals.

Parameters
redGPIOGPIO to use for red channel.
greenGPIOGPIO to use for green channel.
blueGPIOGPIO to use for blue channel.
HSyncGPIOGPIO to use for horizontal sync signal.
VSyncGPIOGPIO to use for vertical sync signal.

Example:

// Use GPIO 22 for red, GPIO 21 for green, GPIO 19 for blue, GPIO 18 for HSync and GPIO 5 for VSync
VGAController.begin(GPIO_NUM_22, GPIO_NUM_21, GPIO_NUM_19, GPIO_NUM_18, GPIO_NUM_5);
Examples:
VGA/AnsiTerminal/AnsiTerminal.ino, and VGA/SimpleTerminalOut/SimpleTerminalOut.ino.

◆ begin() [2/3]

void fabgl::VGA16Controller::begin ( gpio_num_t  red1GPIO,
gpio_num_t  red0GPIO,
gpio_num_t  green1GPIO,
gpio_num_t  green0GPIO,
gpio_num_t  blue1GPIO,
gpio_num_t  blue0GPIO,
gpio_num_t  HSyncGPIO,
gpio_num_t  VSyncGPIO 
)

This is the 64 colors (8 GPIOs) initializer.

Two GPIOs per channel, plus horizontal and vertical sync signals.

Parameters
red1GPIOGPIO to use for red channel, MSB bit.
red0GPIOGPIO to use for red channel, LSB bit.
green1GPIOGPIO to use for green channel, MSB bit.
green0GPIOGPIO to use for green channel, LSB bit.
blue1GPIOGPIO to use for blue channel, MSB bit.
blue0GPIOGPIO to use for blue channel, LSB bit.
HSyncGPIOGPIO to use for horizontal sync signal.
VSyncGPIOGPIO to use for vertical sync signal.

Example:

// Use GPIO 22-21 for red, GPIO 19-18 for green, GPIO 5-4 for blue, GPIO 23 for HSync and GPIO 15 for VSync
VGAController.begin(GPIO_NUM_22, GPIO_NUM_21, GPIO_NUM_19, GPIO_NUM_18, GPIO_NUM_5, GPIO_NUM_4, GPIO_NUM_23, GPIO_NUM_15);

◆ begin() [3/3]

void fabgl::VGA16Controller::begin ( )

This is the 64 colors (8 GPIOs) initializer using default pinout.

Two GPIOs per channel, plus horizontal and vertical sync signals. Use GPIO 22-21 for red, GPIO 19-18 for green, GPIO 5-4 for blue, GPIO 23 for HSync and GPIO 15 for VSync

Example:

VGAController.begin();

◆ controllerType()

DisplayControllerType fabgl::BitmappedDisplayController::controllerType ( )
inlinevirtualinherited

Determines the display controller type.

Returns
Display controller type.

Implements fabgl::BaseDisplayController.

◆ enableBackgroundPrimitiveExecution()

void fabgl::BitmappedDisplayController::enableBackgroundPrimitiveExecution ( bool  value)
inherited

Enables or disables drawings inside vertical retracing time.

Primitives are processed in background (for example in vertical retracing for VGA or in a separated task for SPI/I2C displays). This method can disable (or reenable) this behavior, making drawing instantaneous. Flickering may occur when drawings are executed out of retracing time.
When background executing is disabled the queue is emptied executing all pending primitives. Some displays (SPI/I2C) may be not updated at all when enableBackgroundPrimitiveExecution is False.

Parameters
valueWhen true drawings are done on background, when false drawings are executed instantly.

◆ enableBackgroundPrimitiveTimeout()

void fabgl::BitmappedDisplayController::enableBackgroundPrimitiveTimeout ( bool  value)
inlineinherited

Enables or disables execution time limitation inside vertical retracing interrupt.

Disabling interrupt execution timeout may generate flickering but speedup drawing operations.

Parameters
valueTrue enables timeout (default), False disables timeout

◆ getBitsPerChannel()

uint8_t fabgl::VGA16Controller::getBitsPerChannel ( )
inline

Gets number of bits allocated for each channel.

Number of bits depends by which begin() initializer has been called.

Returns
1 (8 colors) or 2 (64 colors).

◆ getScreenHeight()

int fabgl::VGA16Controller::getScreenHeight ( )
inlinevirtual

Determines the screen height in pixels.

Returns
Screen height in pixels.

Implements fabgl::BaseDisplayController.

Examples:
VGA/SimpleTerminalOut/SimpleTerminalOut.ino.

◆ getScreenWidth()

int fabgl::VGA16Controller::getScreenWidth ( )
inlinevirtual

Determines the screen width in pixels.

Returns
Screen width in pixels.

Implements fabgl::BaseDisplayController.

Examples:
VGA/SimpleTerminalOut/SimpleTerminalOut.ino.

◆ getViewPortCol()

int fabgl::VGA16Controller::getViewPortCol ( )
inline

Determines horizontal position of the viewport.

Returns
Horizontal position of the viewport (in case viewport width is less than screen width).

◆ getViewPortHeight()

int fabgl::VGA16Controller::getViewPortHeight ( )
inlinevirtual

Determines vertical size of the viewport.

Returns
Vertical size of the viewport.

Implements fabgl::BitmappedDisplayController.

◆ getViewPortRow()

int fabgl::VGA16Controller::getViewPortRow ( )
inline

Determines vertical position of the viewport.

Returns
Vertical position of the viewport (in case viewport height is less than screen height).

◆ getViewPortWidth()

int fabgl::VGA16Controller::getViewPortWidth ( )
inlinevirtual

Determines horizontal size of the viewport.

Returns
Horizontal size of the viewport.

Implements fabgl::BitmappedDisplayController.

◆ instance()

static VGA16Controller* fabgl::VGA16Controller::instance ( )
inlinestatic

Returns the singleton instance of VGA16Controller class.

Returns
A pointer to VGA16Controller singleton object

◆ isDoubleBuffered()

bool fabgl::BitmappedDisplayController::isDoubleBuffered ( )
inlineinherited

Determines whether BitmappedDisplayController is on double buffered mode.

Returns
True if BitmappedDisplayController is on double buffered mode.

◆ moveScreen()

void fabgl::VGA16Controller::moveScreen ( int  offsetX,
int  offsetY 
)

Moves screen by specified horizontal and vertical offset.

Screen moving is performed moving horizontal and vertical Front and Back porchs.

Parameters
offsetXHorizontal offset in pixels. < 0 goes left, > 0 goes right.
offsetYVertical offset in pixels. < 0 goes up, > 0 goes down.

Example:

// Move screen 4 pixels right, 1 pixel left
VGAController.moveScreen(4, -1);

◆ nativePixelFormat()

NativePixelFormat fabgl::VGA16Controller::nativePixelFormat ( )
inlinevirtual

Represents the native pixel format used by this display.

Returns
Display native pixel format

Implements fabgl::BitmappedDisplayController.

◆ processPrimitives()

void IRAM_ATTR fabgl::BitmappedDisplayController::processPrimitives ( )
inherited

Draws immediately all primitives in the queue.

Draws all primitives before they are processed in the vertical sync interrupt.
May generate flickering because don't care of vertical sync.

◆ refreshSprites()

void fabgl::BitmappedDisplayController::refreshSprites ( )
inherited

Forces the sprites to be updated.

Screen is automatically updated whenever a primitive is painted (look at Canvas).
When a sprite updates its image or its position (or any other property) it is required to force a refresh using this method.
BitmappedDisplayController.refreshSprites() is required also when using the double buffered mode, to paint sprites.

Examples:
SSD1306_OLED/128x32/CollisionDetection/CollisionDetection.ino, SSD1306_OLED/128x64/CollisionDetection/CollisionDetection.ino, VGA/CollisionDetection/CollisionDetection.ino, VGA/SpaceInvaders/SpaceInvaders.ino, and VGA/Sprites/Sprites.ino.

◆ removeSprites()

void fabgl::BitmappedDisplayController::removeSprites ( )
inlineinherited

Empties the list of active sprites.

Call this method when you don't need active sprites anymore.

Examples:
VGA/SpaceInvaders/SpaceInvaders.ino.

◆ resumeBackgroundPrimitiveExecution()

void fabgl::VGA16Controller::resumeBackgroundPrimitiveExecution ( )
virtual

Resumes drawings after suspendBackgroundPrimitiveExecution().

Resumes drawings enabling vertical sync interrupt.

Implements fabgl::BitmappedDisplayController.

◆ setMouseCursor() [1/2]

void fabgl::BitmappedDisplayController::setMouseCursor ( Cursor cursor)
inherited

Sets mouse cursor and make it visible.

Parameters
cursorCursor to use when mouse pointer need to be painted. nullptr = disable mouse pointer.
Examples:
VGA/MouseOnScreen/MouseOnScreen.ino.

◆ setMouseCursor() [2/2]

void fabgl::BitmappedDisplayController::setMouseCursor ( CursorName  cursorName)
inherited

Sets mouse cursor from a set of predefined cursors.

Parameters
cursorNameName (enum) of predefined cursor.

Example:

VGAController.setMouseCursor(CursorName::CursorPointerShadowed);

◆ setMouseCursorPos()

void fabgl::BitmappedDisplayController::setMouseCursorPos ( int  X,
int  Y 
)
inherited

Sets mouse cursor position.

Parameters
XMouse cursor horizontal position.
YMouse cursor vertical position.

◆ setPaletteItem()

void fabgl::VGA16Controller::setPaletteItem ( int  index,
RGB888 const &  color 
)

Determines color of specified palette item.

Parameters
indexPalette item (0..15)
colorColor to assign to this item

Example:

// Color item 0 is pure Red
displayController.setPaletteItem(0, RGB(255, 0, 0));

◆ setProcessPrimitivesOnBlank()

void fabgl::VGA16Controller::setProcessPrimitivesOnBlank ( bool  value)
inline

Determines the maximum time allowed to process primitives.

Primitives processing is always started at the beginning of vertical blank. Unfortunately this time is limited and not all primitive may be processed, so processing all primitives may required more frames. This method expands the allowed time to half of a frame. This increase drawing speed but may show some flickering.

The default is False (fast drawings, possible flickering).

Parameters
valueTrue = allowed time to process primitives is limited to the vertical blank. Slow, but avoid flickering. False = allowed time is the half of an entire frame. Fast, but may flick.

◆ setResolution()

void fabgl::VGA16Controller::setResolution ( char const *  modeline,
int  viewPortWidth = -1,
int  viewPortHeight = -1,
bool  doubleBuffered = false 
)

Sets current resolution using linux-like modeline.

Modeline must have following syntax (non case sensitive):

"label" clock_mhz hdisp hsyncstart hsyncend htotal vdisp vsyncstart vsyncend vtotal (+HSync | -HSync) (+VSync | -VSync) [DoubleScan | QuadScan] [FrontPorchBegins | SyncBegins | BackPorchBegins | VisibleBegins] [MultiScanBlank]

In fabglconf.h there are macros with some predefined modelines for common resolutions. When MultiScanBlank and DoubleScan is specified then additional rows are not repeated, but just filled with blank lines.

Parameters
modelineLinux-like modeline as specified above.
viewPortWidthHorizontal viewport size in pixels. If less than zero (-1) it is sized to modeline visible area width.
viewPortHeightVertical viewport size in pixels. If less then zero (-1) it is sized to maximum allocable.
doubleBufferedif True allocates another viewport of the same size to use as back buffer. Make sure there is enough free memory.

Example:

// Use predefined modeline for 640x480@60Hz
VGAController.setResolution(VGA_640x480_60Hz);

// The same of above using modeline string
VGAController.setResolution("\"640x480@60Hz\" 25.175 640 656 752 800 480 490 492 525 -HSync -VSync");

// Set 640x382@60Hz but limit the viewport to 640x350
VGAController.setResolution(VGA_640x382_60Hz, 640, 350);
Examples:
VGA/AnsiTerminal/AnsiTerminal.ino, and VGA/SimpleTerminalOut/SimpleTerminalOut.ino.

◆ setSprites()

template<typename T >
void fabgl::BitmappedDisplayController::setSprites ( T *  sprites,
int  count 
)
inlineinherited

Sets the list of active sprites.

A sprite is an image that keeps background unchanged.
There is no limit to the number of active sprites, but flickering and slow refresh happens when a lot of sprites (or large sprites) are visible.
To empty the list of active sprites call BitmappedDisplayController.removeSprites().

Parameters
spritesThe list of sprites to make currently active.
countNumber of sprites in the list.

Example:

// define a sprite with user data (velX and velY)
struct MySprite : Sprite {
  int  velX;
  int  velY;
};

static MySprite sprites[10];

VGAController.setSprites(sprites, 10);
Examples:
SSD1306_OLED/128x32/CollisionDetection/CollisionDetection.ino, SSD1306_OLED/128x64/CollisionDetection/CollisionDetection.ino, VGA/CollisionDetection/CollisionDetection.ino, VGA/SpaceInvaders/SpaceInvaders.ino, and VGA/Sprites/Sprites.ino.

◆ shrinkScreen()

void fabgl::VGA16Controller::shrinkScreen ( int  shrinkX,
int  shrinkY 
)

Reduces or expands screen size by the specified horizontal and vertical offset.

Screen shrinking is performed changing horizontal and vertical Front and Back porchs.

Parameters
shrinkXHorizontal offset in pixels. > 0 shrinks, < 0 expands.
shrinkYVertical offset in pixels. > 0 shrinks, < 0 expands.

Example:

// Shrink screen by 8 pixels and move by 8 pixels to the left
VGAController.shrinkScreen(8, 0);
VGAController.moveScreen(8, 0);

◆ suspendBackgroundPrimitiveExecution()

void fabgl::VGA16Controller::suspendBackgroundPrimitiveExecution ( )
virtual

Suspends drawings.

Suspends drawings disabling vertical sync interrupt.
After call to suspendBackgroundPrimitiveExecution() adding new primitives may cause a deadlock.
To avoid it a call to "processPrimitives()" should be performed very often.
This method maintains a counter so can be nested.

Implements fabgl::BitmappedDisplayController.

Member Data Documentation

◆ queueSize

int fabgl::BitmappedDisplayController::queueSize = FABGLIB_DEFAULT_DISPLAYCONTROLLER_QUEUE_SIZE
staticinherited

Size of display controller primitives queue.

Application should change before begin() method.

Default value is FABGLIB_DEFAULT_DISPLAYCONTROLLER_QUEUE_SIZE (defined in fabglconf.h)

Examples:
VGA/MultitaskingCPM/MultitaskingCPM.ino.

The documentation for this class was generated from the following files: