Overlay Layers

Description

The display of the image by the PicoVGA library is performed by the PIO processor controller. PIO0 is used. The other controller, PIO1, is unused and can be used for other purposes. PIO0 contains a 4 state machines, SM0 to SM3. All PIO0 state machines use a common program of 32 instructions. Each state machine serves 1 overlay layer. SM0 services base layer 0, along with servicing the synchronization signal. The base layer service program consists of 15 instructions, starting at offset 17. This part of the program is immutable and is always used. However, the other 3 layers, 1 to 3, SM1 to SM3, use the other part of the program memory, 17 instructions starting at address 0. This part may change, depending on the mode of the overlay layers. All 3 overlay layers use a common program and must therefore operate in the same display mode. Some overlay modes use the same program and can be shared - see the table below for details.

Note

Only base layer 0 can contain segments in different formats. Overlay layers 1 to 3 are independent of the base layer format, sharing only the total display area with the base layer, but using their own image format, for which only the coordinates and dimensions are specified.

Overlay layers can use one of the following programs:

• LAYERPROG_BASE - The base layer 0 program. Cannot be used for overlay layers. Using the parameter for an overlay layer means that the layer is inactive (not using the program).
• LAYERPROG_KEY - Layer with key color. The specified color is replaced by transparency.
• LAYERPROG_BLACK - Transparency with black color. Black is replaced by transparency. Compared to the previous mode, the advantage is less demanding on processor speed.
• LAYERPROG_WHITE - transparency with white colour. It is faster like the previous function and is suitable for use where black needs to be preserved but white can be omitted. When preparing the image, the image is not copied from Flash to RAM with the memcpy function, but the CopyWhiteImg() function is used. The function ensures that the pixels of the copied image are incremented by 1. This changes the white color (with a value of 255) to black (with a value of 0). From this point on, the image is treated as if it had transparency with black - e.g. the black color is specified for the sprite rendering function. Only when the image enters the program in PIO0, the program makes the pixel transparent as in the case of black, but at the same time decrements the pixel value. This reverts the colors back to the original value, the black color becomes black and the white color has been used as transparency.
• LAYERPROG_MONO - This programme includes 2 sub-programmes. The first is the display of a monochrome image. For each bit of image data, either the selected image color is displayed or the corresponding pixel is transparent. This mode is used in the Oscilloscope example to display a grid across the oscilloscope screen. The second subroutine is to display a color image without transparency. The color pixels are displayed as they are, with no transparency option, but the dimensions of the image rectangle and its coordinate on the display can be defined. Thus, a sort of analogy of a single rectangular sprite without transparency.
• LAYERPROG_RLE - RLE compression mode. RLE compression is not a universally valid format. It means that the data contains segment length information. In this case, the image data of PicoVGA library contain directly instructions for the PIO program. More specifically, the image data is interleaved with the jump addresses inside the program. The image is prepared using the RaspPicoRle program and is strongly coupled to the layer program used. If, for example, the instructions in the program were shifted, the RLE compression format would stop working. This is also why the program for base layer 0 is placed at the end of the program memory and the overlay layer programs at the beginning - to reduce the chance that changes in the program will change the location of the program in memory, at which point RLE compression would stop working. After modifying the RLE program in PIO, the conversion program must also be updated.

The desired mode of each overlay layer is specified in the video mode definition using the VgaCfg() function. The layer mode is used to derive the program and function used to operate the layer rendering. Multiple layer modes can share the same program type. Layer modes have different state machine timing requirements. The configuration function takes this into account and adjusts the processor frequency accordingly.

Modes of overlay layers:

*WHITE modes using white transparent color require image preparation using CopyWhiteImg() as specified for LAYERPROG_WHITE.

• LAYERMODE_BASE - Indicates base layer mode 0. Cannot be used for an overlay layer, but is used to indicate an inactive disabled overlay layer.
• LAYERMODE_KEY - The layer with the specified key color.
• LAYERMODE_BLACK - Layer with black key color.
• LAYERMODE_WHITE - Layer with white key color.
• LAYERMODE_MONO - Monochromatic image.
• LAYERMODE_COLOR - Colour image (without transparency).
• LAYERMODE_RLE - Image with RLE compression.
• LAYERMODE_SPRITEKEY - Sprays with the specified key color.
• LAYERMODE_SPRITEBLACK - Sprays with black key color.
• LAYERMODE_SPRITEWHITE - Sprays with white key color.
• LAYERMODE_FASTSPRITEKEY - Fast sprites with the specified key colour.
• LAYERMODE_FASTSPRITEBLACK - Fast sprites with black key colour.
• LAYERMODE_FASTSPRITEWHITE - Fast sprites with white key colour.
• LAYERMODE_PERSPKEY - Image with transformation matrix with specified key color.
• LAYERMODE_PERSPBLACK - Image with transformation matrix with black key color.
• LAYERMODE_PERSPWHITE - Image with transformation matrix with white key color.
• LAYERMODE_PERSP2KEY - Image with transformation matrix with specified key color and doubled width.
• LAYERMODE_PERSP2BLACK - Image with transformation matrix with black key color and doubled width.
• LAYERMODE_PERSP2WHITE - Image with transformation matrix with white key color and doubled width.

Shared overlay modes

Layer modes can only be combined together if they use the same program. CPP is the minimum required number of SMx clock cycles per pixel.

	PROG_BASE	PROG_KEY	PROG_BLACK	PROG_WHITE	PROG_MONO	PROG_RLE	CPP
LAYERMODE_BASE	X						2
LAYERMODE_KEY		X					6
LAYERMODE_BLACK			X				4
LAYERMODE_WHITE				X			4
LAYERMODE_MONO					X		4
LAYERMODE_COLOR					X		2
LAYERMODE_RLE						X	3
LAYERMODE_SPRITEKEY		X					6
LAYERMODE_SPRITEBLACK			X				4
LAYERMODE_SPRITEWHITE				X			4
LAYERMODE_FASTSPRITEKEY		X					6
LAYERMODE_FASTSPRITEBLACK			X				4
LAYERMODE_FASTSPRITEWHITE				X			4
LAYERMODE_PERSPKEY		X					6
LAYERMODE_PERSPBLACK			X				4
LAYERMODE_PERSPWHITE				X			4
LAYERMODE_PERSP2KEY		X					6
LAYERMODE_PERSP2BLACK			X				4
LAYERMODE_PERSP2WHITE				X			4

Selection of write planes

By default, the image is output from the layers to all output pins. This can be changed by redefining the LayerFirstPin and LayerNumPin fields (in vga_layer.cpp). It is possible to specify for each layer separately which output pins will be written to. This can create a kind of pseudo-transparency. For example, one layer will render curves in red, another layer in green, and the colors will blend independently. When redefining the pins, however, you must take into account that the offset of the pin mapping will shift. The output will always start from the lowest bits of the pixel.

Configure overlay layers

The first step for setting up the overlay layer is to specify the layer mode for the VgaCfg() initialization function. The function detects the required program and the required timing. It does not check if the correct layer modes are combined together.

The second step is to initialize the layer descriptor - the sLayer structure in the LayerScreen field. It is convenient to use the LayerSetup() initialization function for this.

Data Structures
struct	sLayer
	Layer screen descriptor (on change update SLAYER_* in define.h) More...
struct	sSprite
	Sprite (on change update SSPRITE_* in define.h) More...

Macros
#define	BASE_OFFSET   17
	Offset of base layer PIO program.
#define	LAYER_OFFSET   0
	Offset of overlapped layer PIO program.
#define	LAYERPROG_BASE   0
	Program of base layer (overlapped layers are OFF)
#define	LAYERPROG_KEY   1
	Layer with key color.
#define	LAYERPROG_BLACK   2
	Layer with black key color.
#define	LAYERPROG_WHITE   3
	Layer with white key color.
#define	LAYERPROG_MONO   4
	Layer with mono pattern or simple color.
#define	LAYERPROG_RLE   5
	Layer with RLE compression.
#define	LAYERPROG_NUM   6
	Number of layer programs.
#define	LAYERMODE_BASE   0
	Base layer.
#define	LAYERMODE_KEY   1
	Layer with key color.
#define	LAYERMODE_BLACK   2
	layer with black key color
#define	LAYERMODE_WHITE   3
	Layer with white key color.
#define	LAYERMODE_MONO   4
	Layer with mono pattern.
#define	LAYERMODE_COLOR   5
	layer with simple color
#define	LAYERMODE_RLE   6
	Layer with RLE compression.
#define	LAYERMODE_SPRITEKEY   7
	Layer with sprites with key color.
#define	LAYERMODE_SPRITEBLACK   8
	Layer with sprites with black key color.
#define	LAYERMODE_SPRITEWHITE   9
	Layer with sprites with white key color.
#define	LAYERMODE_FASTSPRITEKEY   10
	Layer with fast sprites with key color.
#define	LAYERMODE_FASTSPRITEBLACK   11
	Layer with fast sprites with black key color.
#define	LAYERMODE_FASTSPRITEWHITE   12
	Layer with fast sprites with white key color.
#define	LAYERMODE_PERSPKEY   13
	Layer with key color and image with transformation matrix.
#define	LAYERMODE_PERSPBLACK   14
	Layer with black key color and image with transformation matrix.
#define	LAYERMODE_PERSPWHITE   15
	Layer with white key color and image with transformation matrix.
#define	LAYERMODE_PERSP2KEY   16
	Layer with key color and double-pixel image with transformation matrix.
#define	LAYERMODE_PERSP2BLACK   17
	Layer with black key color and double-pixel image with transformation matrix.
#define	LAYERMODE_PERSP2WHITE   18
	Layer with white key color and double-pixel image with transformation matrix.
#define	LAYERMODE_NUM   19
	Number of overlapped layer modes.

Functions
void	LayerOn (u8 inx)
	Set overlapped layer 1..3 ON. More...
void	LayerOff (u8 inx)
	Set overlapped layer 1..3 OFF. More...
void	LayerSetX (u8 inx, s16 x)
	Set coordinate X of overlapped layer. More...
void	LayerSetY (u8 inx, s16 y)
	Set coordinate Y of overlapped layer. More...
void	LayerSetW (u8 inx, u16 w)
	Set width of image of overlapped layer. More...
void	LayerSetH (u8 inx, u16 h)
	Set height of image of overlapped layer. More...
void	LayerSetup (u8 inx, const u8 *img, const sVmode *vmode, u16 w, u16 h, u8 col=0, const void *par=NULL)
	Setup overlapped layer 1..3 (not for sprites or perspective mode) More...
void	LayerPerspSetup (u8 inx, const u8 *img, const sVmode *vmode, u16 w, u16 h, u8 xbits, u8 ybits, s8 horiz, const int *mat, u8 col=0)
	Setup overlapped layer 1..3 for LAYERMODE_PERSP* modes. More...

Variables
sLayer	LayerScreen [LAYERS]
	Current layer screens.
u8	LayerFirstPin [LAYERS_MAX]
	Index of first pin of layer (base layer should stay VGA_GPIO_FIRST)
u8	LayerNumPin [LAYERS_MAX]
	Number of pins of overlapped layer (base layer should stay VGA_GPIO_OUTNUM)

Function Documentation

LayerOn()

void LayerOn

(

u8

inx

)

Set overlapped layer 1..3 ON.

Parameters

inx	Layer index

LayerOff()

void LayerOff

(

u8

inx

)

Set overlapped layer 1..3 OFF.

Parameters

inx	Layer index

LayerSetX()

void LayerSetX	(	u8	inx,
		s16	x
	)

Set coordinate X of overlapped layer.

Parameters

inx	Layer index
x	X coordinate

LayerSetY()

void LayerSetY	(	u8	inx,
		s16	y
	)

Set coordinate Y of overlapped layer.

Parameters

inx	Layer index
y	Y coordinate

LayerSetW()

void LayerSetW	(	u8	inx,
		u16	w
	)

Set width of image of overlapped layer.

Note

Uses auto pitch wb (full line). Set custom wb after calling this function.

Parameters

inx	Layer index
w	Width

LayerSetH()

void LayerSetH	(	u8	inx,
		u16	h
	)

Set height of image of overlapped layer.

Parameters

inx	Layer index
h	Height

LayerSetup()

void LayerSetup	(	u8	inx,
		const u8 *	img,
		const sVmode *	vmode,
		u16	w,
		u16	h,
		u8	col = 0,
		const void *	par = NULL
	)

Setup overlapped layer 1..3 (not for sprites or perspective mode)

The function sets the dimensions of the image and its address. The coordinates are cleared. The position of the image on the screen can be set by the LayetSetX() and LayerSetY() functions. The coordinates do not depend on the graphic modes of the base layer and refer to the upper left corner of the active screen area. After initialization, the layer remains disabled. Layer visibility must be turned on by calling the LayerOn() function.

Parameters

inx	Layer index 1..3
img	Pointer to image data
vmode	Pointer to initialized video configuration
w	Image width in pixels (must be multiple of 4)
h	Image height
col	Key color (Needed for LAYERMODE_KEY and LAYERMODE_MONO. For both *BLACK and *WHITE modes, specify COL_BLACK or 0)
par	Additional data (RLE index table, integer transformation matrix)

LayerPerspSetup()

void LayerPerspSetup	(	u8	inx,
		const u8 *	img,
		const sVmode *	vmode,
		u16	w,
		u16	h,
		u8	xbits,
		u8	ybits,
		s8	horiz,
		const int *	mat,
		u8	col = 0
	)

Setup overlapped layer 1..3 for LAYERMODE_PERSP* modes.

In contrast to the LayerSetup() function, the dimensions of the source image in number of bits (the image dimensions must be a power of 2), the height of the horizon/4 (for a negative value the floor turns into a ceiling, for zero the perspective transformation is not applied) and the pointer to the transformation matrix in integer form are also specified.

Parameters

inx	Layer index 1..3
img	Pointer to source image data (image width and height must be power of 2)
vmode	Pointer to initialized video configuration
w	Destination image width in pixels (must be multiple of 4)
h	Destination image height
xbits	Number of bits of width of source image
ybits	Number of bits of height of source image
horiz	Horizon of perspective projection/4 (0=no perspecitve, <0 ceilling)
mat	Integer transformation matrix
col	Key color (needed for LAYERMODE_PERSPKEY layer mode)