Represents the VGA controller. More...

#include <vgacontroller.h>

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...

uint8_t	createRawPixel (RGB rgb)
	Creates a raw pixel to use with VGAControllerClass.setRawPixel. 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...

uint8_t *	getScanline (int y)
	Gets a raw scanline pointer. 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 VGAControllerClass is on double buffered mode. More...

void	moveScreen (int offsetX, int offsetY)
	Moves screen by specified horizontal and vertical offset. More...

void	processPrimitives ()
	Draws immediately all primitives in the queue. More...

void	readScreen (Rect const &rect, RGB *destBuf)
	Reads pixels inside the specified rectangle. 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 const *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	setRawPixel (int x, int y, uint8_t rgb)
	Sets a raw pixel prepared using VGAControllerClass.createRawPixel. 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...

void	writeScreen (Rect const &rect, RGB *srcBuf)
	Writes pixels inside the specified rectangle. More...

Detailed Description

Represents the VGA controller.

Use this class to set screen resolution and to associate VGA signals to ESP32 GPIO outputs.

This example initializes VGA Controller with 8 colors (5 GPIOs used) and 640x350 resolution:

// Assign GPIO22 to Red, GPIO21 to Green, GPIO19 to Blue, GPIO18 to HSync and GPIO5 to VSync
VGAController.begin(GPIO_NUM_22, GPIO_NUM_21, GPIO_NUM_19, GPIO_NUM_18, GPIO_NUM_5);

// Set 640x350@70Hz resolution
VGAController.setResolution(VGA_640x350_70Hz);

This example initializes VGA Controller with 64 colors (8 GPIOs used) and 640x350 resolution:

// Assign GPIO22 and GPIO_NUM_21 to Red, GPIO_NUM_19 and GPIO_NUM_18 to Green, GPIO_NUM_5 and GPIO_NUM_4 to Blue, GPIO_NUM_23 to HSync and GPIO_NUM_15 to 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);

// Set 640x350@70Hz resolution
VGAController.setResolution(VGA_640x350_70Hz);

Member Function Documentation

◆ begin() [1/3]

void fabgl::VGAControllerClass::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

redGPIO	GPIO to use for red channel.
greenGPIO	GPIO to use for green channel.
blueGPIO	GPIO to use for blue channel.
HSyncGPIO	GPIO to use for horizontal sync signal.
VSyncGPIO	GPIO 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:: Altair8800/Altair8800.ino, AnsiTerminal/AnsiTerminal.ino, Audio/Audio.ino, CollisionDetection/CollisionDetection.ino, DoubleBuffer/DoubleBuffer.ino, GraphicalUserInterface/GraphicalUserInterface.ino, LoopbackTerminal/LoopbackTerminal.ino, ModelineStudio/ModelineStudio.ino, MouseOnScreen/MouseOnScreen.ino, NetworkTerminal/NetworkTerminal.ino, SimpleTerminalOut/SimpleTerminalOut.ino, SpaceInvaders/SpaceInvaders.ino, and VIC20/VIC20.ino.

◆ begin() [2/3]

void fabgl::VGAControllerClass::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

red1GPIO	GPIO to use for red channel, MSB bit.
red0GPIO	GPIO to use for red channel, LSB bit.
green1GPIO	GPIO to use for green channel, MSB bit.
green0GPIO	GPIO to use for green channel, LSB bit.
blue1GPIO	GPIO to use for blue channel, MSB bit.
blue0GPIO	GPIO to use for blue channel, LSB bit.
HSyncGPIO	GPIO to use for horizontal sync signal.
VSyncGPIO	GPIO 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::VGAControllerClass::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();

◆ createRawPixel()

uint8_t fabgl::VGAControllerClass::createRawPixel ( RGB rgb )

inline

Creates a raw pixel to use with VGAControllerClass.setRawPixel.

A raw pixel (or raw color) is a byte (uint8_t) that contains color information and synchronization signals.

Parameters

rgb	Pixel RGB color

Example:

// Set color of pixel at 100, 100
VGAController.setRawPixel(100, 100, VGAController.createRawPixel(RGB(3, 0, 0));

◆ enableBackgroundPrimitiveExecution()

void fabgl::VGAControllerClass::enableBackgroundPrimitiveExecution ( bool value )

Enables or disables drawings inside vertical retracing time.

When vertical retracing occurs (on Vertical Sync) an interrupt is trigged. Inside this interrupt primitives like line, circles, glyphs, etc.. are painted.
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.

Parameters

value When true drawings are done during vertical retracing, when false drawings are executed instantly.

Examples:: Altair8800/Altair8800.ino, AnsiTerminal/AnsiTerminal.ino, NetworkTerminal/NetworkTerminal.ino, and SimpleTerminalOut/SimpleTerminalOut.ino.

◆ enableBackgroundPrimitiveTimeout()

void fabgl::VGAControllerClass::enableBackgroundPrimitiveTimeout ( bool value )

inline

Enables or disables execution time limitation inside vertical retracing interrupt.

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

Parameters

value True enables timeout (default), False disables timeout

Examples:: VIC20/VIC20.ino.

◆ getBitsPerChannel()

uint8_t fabgl::VGAControllerClass::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).

◆ getScanline()

uint8_t* fabgl::VGAControllerClass::getScanline ( int y )

inline

Gets a raw scanline pointer.

A raw scanline must be filled with raw pixel colors. Use VGAControllerClass.createRawPixel to create raw pixel colors. A raw pixel (or raw color) is a byte (uint8_t) that contains color information and synchronization signals. Pixels are arranged in 32 bit packes as follows: pixel 0 = byte 2, pixel 1 = byte 3, pixel 2 = byte 0, pixel 3 = byte 1 : pixel : 0 1 2 3 4 5 6 7 8 9 10 11 ...etc... byte : 2 3 0 1 6 7 4 5 10 11 8 9 ...etc... dword : 0 1 2 ...etc...

Parameters

y	Vertical scanline position (0 = top row)

◆ getScreenHeight()

int fabgl::VGAControllerClass::getScreenHeight ( )

inline

Determines the screen height in pixels.

Returns: Screen height in pixels.

Examples:: AnsiTerminal/AnsiTerminal.ino, LoopbackTerminal/LoopbackTerminal.ino, ModelineStudio/ModelineStudio.ino, NetworkTerminal/NetworkTerminal.ino, and SimpleTerminalOut/SimpleTerminalOut.ino.

◆ getScreenWidth()

int fabgl::VGAControllerClass::getScreenWidth ( )

inline

Determines the screen width in pixels.

Returns: Screen width in pixels.

Examples:: AnsiTerminal/AnsiTerminal.ino, LoopbackTerminal/LoopbackTerminal.ino, ModelineStudio/ModelineStudio.ino, NetworkTerminal/NetworkTerminal.ino, and SimpleTerminalOut/SimpleTerminalOut.ino.

◆ getViewPortCol()

int fabgl::VGAControllerClass::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::VGAControllerClass::getViewPortHeight ( )

inline

Determines vertical size of the viewport.

Returns: Vertical size of the viewport.

◆ getViewPortRow()

int fabgl::VGAControllerClass::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::VGAControllerClass::getViewPortWidth ( )

inline

Determines horizontal size of the viewport.

Returns: Horizontal size of the viewport.

◆ isDoubleBuffered()

bool fabgl::VGAControllerClass::isDoubleBuffered ( )

inline

Determines whether VGAControllerClass is on double buffered mode.

Returns: True if VGAControllerClass is on double buffered mode.

◆ moveScreen()

void fabgl::VGAControllerClass::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

offsetX	Horizontal offset in pixels. < 0 goes left, > 0 goes right.
offsetY	Vertical offset in pixels. < 0 goes up, > 0 goes down.

Example:

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

Examples:: Audio/Audio.ino, CollisionDetection/CollisionDetection.ino, ModelineStudio/ModelineStudio.ino, and SpaceInvaders/SpaceInvaders.ino.

◆ processPrimitives()

void IRAM_ATTR fabgl::VGAControllerClass::processPrimitives ( )

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.

◆ readScreen()

void fabgl::VGAControllerClass::readScreen	(	Rect const &	rect,
		RGB *	destBuf
	)

Reads pixels inside the specified rectangle.

Screen reading may occur while other drawings are in progress, so the result may be not updated.

Parameters

rect	Screen rectangle to read. To improve performance rectangle is not checked.
destBuf	Destination buffer. Buffer size must be at least rect.width() * rect.height.

Example:

// paint a red rectangle
Canvas.setBrushColor(RGB(3, 0, 0));
Rect rect = Rect(10, 10, 100, 100);
Canvas.fillRectangle(rect);

// wait for vsync (hence actual drawing)
VGAController.processPrimitives();

// read rectangle pixels into "buf"
auto buf = new RGB[rect.width() * rect.height()];
VGAController.readScreen(rect, buf);

// write buf 110 pixels to the reight
VGAController.writeScreen(rect.translate(110, 0), buf);
delete buf;

◆ refreshSprites()

void fabgl::VGAControllerClass::refreshSprites ( )

Forces the sprites to be updated.

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

Examples:: CollisionDetection/CollisionDetection.ino, and SpaceInvaders/SpaceInvaders.ino.

◆ removeSprites()

void fabgl::VGAControllerClass::removeSprites ( )

inline

Empties the list of active sprites.

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

◆ resumeBackgroundPrimitiveExecution()

void fabgl::VGAControllerClass::resumeBackgroundPrimitiveExecution ( )

Resumes drawings after suspendBackgroundPrimitiveExecution().

Resumes drawings enabling vertical sync interrupt.

◆ setMouseCursor() [1/2]

void fabgl::VGAControllerClass::setMouseCursor ( Cursor const * cursor )

Sets mouse cursor and make it visible.

Parameters

cursor Cursor to use when mouse pointer need to be painted. nullptr = disable mouse pointer.

Examples:: MouseOnScreen/MouseOnScreen.ino.

◆ setMouseCursor() [2/2]

void fabgl::VGAControllerClass::setMouseCursor ( CursorName cursorName )

Sets mouse cursor from a set of predefined cursors.

Parameters

cursorName Name (enum) of predefined cursor.

Example:

VGAController.setMouseCursor(CursorName::CursorPointerShadowed);

◆ setMouseCursorPos()

void fabgl::VGAControllerClass::setMouseCursorPos	(	int	X,
		int	Y
	)

Sets mouse cursor position.

Parameters

X	Mouse cursor horizontal position.
Y	Mouse cursor vertical position.

◆ setRawPixel()

void fabgl::VGAControllerClass::setRawPixel	(	int	x,
		int	y,
		uint8_t	rgb
	)

inline

Sets a raw pixel prepared using VGAControllerClass.createRawPixel.

A raw pixel (or raw color) is a byte (uint8_t) that contains color information and synchronization signals.

Parameters

x	Horizontal pixel position
y	Vertical pixel position
rgb	Raw pixel color

Example:

// Set color of pixel at 100, 100
VGAController.setRawPixel(100, 100, VGAController.createRawPixel(RGB(3, 0, 0));

◆ setResolution()

void fabgl::VGAControllerClass::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] [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

modeline	Linux-like modeline as specified above.
viewPortWidth	Horizontal viewport size in pixels. If less than zero (-1) it is sized to modeline visible area width.
viewPortHeight	Vertical viewport size in pixels. If less then zero (-1) it is sized to maximum allocable.
doubleBuffered	if 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:: Altair8800/Altair8800.ino, AnsiTerminal/AnsiTerminal.ino, Audio/Audio.ino, CollisionDetection/CollisionDetection.ino, DoubleBuffer/DoubleBuffer.ino, GraphicalUserInterface/GraphicalUserInterface.ino, LoopbackTerminal/LoopbackTerminal.ino, ModelineStudio/ModelineStudio.ino, MouseOnScreen/MouseOnScreen.ino, NetworkTerminal/NetworkTerminal.ino, SimpleTerminalOut/SimpleTerminalOut.ino, SpaceInvaders/SpaceInvaders.ino, and VIC20/VIC20.ino.

◆ setSprites()

template<typename T >

void fabgl::VGAControllerClass::setSprites	(	T *	sprites,
		int	count
	)

inline

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 VGAControllerClass.removeSprites().

Parameters

sprites	The list of sprites to make currently active.
count	Number 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:: CollisionDetection/CollisionDetection.ino, and SpaceInvaders/SpaceInvaders.ino.

◆ shrinkScreen()

void fabgl::VGAControllerClass::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

shrinkX	Horizontal offset in pixels. > 0 shrinks, < 0 expands.
shrinkY	Vertical 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);

Examples:: ModelineStudio/ModelineStudio.ino.

◆ suspendBackgroundPrimitiveExecution()

void fabgl::VGAControllerClass::suspendBackgroundPrimitiveExecution ( )

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.

◆ writeScreen()

void fabgl::VGAControllerClass::writeScreen	(	Rect const &	rect,
		RGB *	srcBuf
	)

Writes pixels inside the specified rectangle.

Screen writing may occur while other drawings are in progress, so written pixels may be overlapped or mixed.

Parameters

rect	Screen rectangle to write. To improve performance rectangle is not checked.
srcBuf	Source buffer. Buffer size must be at least rect.width() * rect.height.

Example:

// paint a red rectangle
Canvas.setBrushColor(RGB(3, 0, 0));
Rect rect = Rect(10, 10, 100, 100);
Canvas.fillRectangle(rect);

// wait for vsync (hence actual drawing)
VGAController.processPrimitives();

// read rectangle pixels into "buf"
auto buf = new RGB[rect.width() * rect.height()];
VGAController.readScreen(rect, buf);

// write buf 110 pixels to the reight
VGAController.writeScreen(rect.translate(110, 0), buf);
delete buf;

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

vgacontroller.h
vgacontroller.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ begin() [1/3]

◆ begin() [2/3]

◆ begin() [3/3]

◆ createRawPixel()

◆ enableBackgroundPrimitiveExecution()

◆ enableBackgroundPrimitiveTimeout()

◆ getBitsPerChannel()

◆ getScanline()

◆ getScreenHeight()

◆ getScreenWidth()

◆ getViewPortCol()

◆ getViewPortHeight()

◆ getViewPortRow()

◆ getViewPortWidth()

◆ isDoubleBuffered()

◆ moveScreen()

◆ processPrimitives()

◆ readScreen()

◆ refreshSprites()

◆ removeSprites()

◆ resumeBackgroundPrimitiveExecution()

◆ setMouseCursor() [1/2]

◆ setMouseCursor() [2/2]

◆ setMouseCursorPos()

◆ setRawPixel()

◆ setResolution()

◆ setSprites()

◆ shrinkScreen()

◆ suspendBackgroundPrimitiveExecution()

◆ writeScreen()