Description

Defining the layout of the display.

When displaying screen image, the default pointer is pScreen for the library. It points to the sScreen structure that describes the contents of the display. The Raspberry Pico has a limited RAM size and cannot accommodate a high resolution image. Therefore, the image must be composed of smaller segments to minimize the memory-intensive parts.

Note: The following descriptions of the image format only apply to the base image layer 0. It is the only one that can contain segments in different formats. Overlay layers 1 through 3 are independent of the base layer format, sharing only the total screen area with the base layer but using their own image format.

Data Structures
struct	sSegm
	Video segment (on change update SSEGM_* in define.h) More...

struct	sStrip
	Video strip (on change update SSTRIP_* in define.h) More...

struct	sScreen
	Video screen (on change update SSCREEN_* in define.h) More...

Functions
void	ScreenClear (sScreen *s)
	Clear screen (set 0 strips, does not modify sprites) More...

sStrip *	ScreenAddStrip (sScreen *s, int height)
	Add empty strip to the screen. More...

sSegm *	ScreenAddSegm (sStrip *strip, int width)
	Add empty segment to video strip; returns pointer to the segment and initialises it to defaults. More...

void	ScreenSegmColor (sSegm *segm, u32 col1, u32 col2)
	Set video segment to simple color format GF_COLOR. More...

void	ScreenSegmGrad1 (sSegm segm, const void data, int wb)
	Set video segment to gradient with 1 line. More...

void	ScreenSegmGrad2 (sSegm segm, const void data, int wb)
	Set video segment to gradient with 2 lines. More...

void	ScreenSegmGraph8 (sSegm segm, const void data, int wb)
	Set video segment to native 8-bit graphics (R3G3B2) More...

void	GenPal16Trans (u16 trans, const u8 pal)
	Generate 16-color palette translation table. More...

void	ScreenSegmGraph4 (sSegm segm, const void data, const void *trans, int wb)
	Set video segment to 4-bit palette graphics. More...

void	GenPal4Trans (u32 trans, const u8 pal)
	Generate palette 4 translation table for function. More...

void	ScreenSegmGraph2 (sSegm segm, const void data, const void *trans, int wb)
	Set video segment to 2-bit palette graphics. More...

void	ScreenSegmGraph1 (sSegm segm, const void data, u8 bg, u8 fg, int wb)
	Set video segment to 1-bit palette graphics. More...

void	ScreenSegmMText (sSegm segm, const void data, const void *font, u16 fontheight, u8 bg, u8 fg, int wb)
	Set video segment to 8-pixel mono text. More...

void	ScreenSegmAText (sSegm segm, const void data, const void font, u16 fontheight, const void pal, int wb)
	Set video segment to 8-pixel attribute text. More...

void	ScreenSegmFText (sSegm segm, const void data, const void *font, u16 fontheight, u8 bg, int wb)
	Set video segment to 8-pixel foreground color text. More...

void	ScreenSegmCText (sSegm segm, const void data, const void *font, u16 fontheight, int wb)
	Set video segment to 8-pixel color text. More...

void	ScreenSegmGText (sSegm segm, const void data, const void font, u8 fontheight, u8 bg, const void grad, int wb)
	Set video segment to 8-pixel gradient color text. More...

void	ScreenSegmDText (sSegm segm, const void data, const void font, u8 fontheight, u8 bg, const void grad, int wb)
	Set video segment to 8-pixel double gradient color text. More...

void	ScreenSegmTile (sSegm segm, const void data, const void *tiles, int w, int h, int wb)
	Set video segment to tiles. More...

void	ScreenSegmTile2 (sSegm segm, const void data, const void *tiles, int w, int h, int tilewb, int wb)
	Set video segment to alternate tiles. More...

void	ScreenSegmLevel (sSegm segm, const void data, u8 zero, u8 bg, u8 fg)
	Set video segment to level graph GF_LEVEL. More...

void	ScreenSegmLevelGrad (sSegm segm, const void data, const void sample1, const void sample2)
	Set video segment to leve gradient graph GF_LEVELGRAD. More...

void	ScreenSegmOscil (sSegm segm, const void data, u8 bg, u8 fg, int pixh)
	Set video segment to oscilloscope 1-pixel graph GF_OSCIL. More...

void	ScreenSegmOscLine (sSegm segm, const void data, u8 bg, u8 fg)
	Set video segment to oscilloscope line graph GF_OSCLIN. More...

void	GenPal4Plane (u32 trans, const u8 pal)
	Generate palette 4-color translation table for function ScreenSegmPlane2() More...

void	ScreenSegmPlane2 (sSegm segm, const void data, int plane, const void *trans, int wb)
	Set video segment to 4-color on 2-planes graphics. More...

void	ScreenSegmAttrib8 (sSegm segm, const void data, const void attr, const u8 pal, int wb)
	Set video segment to 2x4 bit color attribute per 8x8 pixel sample graphics. More...

void	ScreenSegmProgress (sSegm segm, const void data, const void sample1, const void sample2)
	Set video segment to horizontal progress indicator GF_PROGRESS. More...

void	ScreenSegmGraph8Mat (sSegm segm, const void data, const int *mat, u16 xbits, u16 ybits)
	Set video segment to 8-bit graphics with 2D matrix transformation. More...

void	ScreenSegmGraph8Persp (sSegm segm, const void data, const int *mat, u16 xbits, u16 ybits, u16 horiz)
	Set video segment to 8-bit graphics with perspective projection. More...

void	ScreenSegmTilePersp (sSegm segm, const u8 map, const u8 tiles, const int mat, u8 mapwbits, u8 maphbits, u8 tilebits, s8 horizon)
	Set video segment to tiles with perspective. More...

void	ScreenSegmTilePersp15 (sSegm segm, const u8 map, const u8 tiles, const int mat, u8 mapwbits, u8 maphbits, u8 tilebits, s8 horizon)
	Set video segment to tiles with perspective, 1.5 pixels. More...

void	ScreenSegmTilePersp2 (sSegm segm, const u8 map, const u8 tiles, const int mat, u8 mapwbits, u8 maphbits, u8 tilebits, s8 horizon)
	Set video segment to tiles with perspective, double pixels. More...

void	ScreenSegmTilePersp3 (sSegm segm, const u8 map, const u8 tiles, const int mat, u8 mapwbits, u8 maphbits, u8 tilebits, s8 horizon)
	Set video segment to tiles with perspective, triple pixels. More...

void	ScreenSegmTilePersp4 (sSegm segm, const u8 map, const u8 tiles, const int mat, u8 mapwbits, u8 maphbits, u8 tilebits, s8 horizon)
	Set video segment to tiles with perspective, quadruple pixels. More...

Variables
sScreen	Screen
	Default video screen.

sScreen *	pScreen
	Pointer to current video screen.

Function Documentation

◆ ScreenClear()

void ScreenClear ( sScreen * s )

Clear screen (set 0 strips, does not modify sprites)

Resets the display handler structures, clearing the display. At a minimum, this function should be called before initializing the videmode. It initializes the display content descriptor structure pointed to by pScreen (usually the default structure Screen of the library) by setting the number of segments to 0. The screen will be black until we fill it with content descriptors

Parameters

s	Pointer to screen to clear

◆ ScreenAddStrip()

sStrip* ScreenAddStrip	(	sScreen *	s,
		int	height
	)

Add empty strip to the screen.

This function adds a new horizontal bar of the specified number of video lines to the end of the screen definition. The maximum number of stripes is specified by the STRIPMAX constant (8 by default) in the vga_config.h file. Without added segments, the bar is empty (black).

Parameters

s	The screen to add strip
height	The number of video lines in the strip

Returns: Pointer to the new strip

◆ ScreenAddSegm()

sSegm* ScreenAddSegm	(	sStrip *	strip,
		int	width
	)

Add empty segment to video strip; returns pointer to the segment and initialises it to defaults.

This function adds a new image segment of the specified width to the end of the strip. The segment will contain one image format. For the vast majority of formats, the width must be a multiple of 4 (a multiple of 4 pixels).

Parameters

strip	The strip to add the segment to
width	The width of the segment in pixels (for many formats must be a multiple of 4)

Returns: Pointer to new segment initialized to defaults

◆ ScreenSegmColor()

void ScreenSegmColor	(	sSegm *	segm,
		u32	col1,
		u32	col2
	)

Set video segment to simple color format GF_COLOR.

Parameters

segm	Segment to configure
col1	Color pattern 4-pixels even line (use macro MULTICOL)
col2	Color pattern 4-pixels odd line (use macro MULTICOL)

◆ ScreenSegmGrad1()

void ScreenSegmGrad1	(	sSegm *	segm,
		const void *	data,
		int	wb
	)

Set video segment to gradient with 1 line.

The segment will be filled with a color gradient (GF_GRAD1). The gradient is 1 line of 8-bit pixels.

Note: The gradient can be scrolled horizontally with the offx parameter.

Parameters

segm	Segment to configure
data	Pointer to data buffer with gradient
wb	Length of buffer

◆ ScreenSegmGrad2()

void ScreenSegmGrad2	(	sSegm *	segm,
		const void *	data,
		int	wb
	)

Set video segment to gradient with 2 lines.

Gradient with 2 lines, even and odd (GF_GRAD2).

Note: To scroll gradient, set virtual dimension wrapx, then shift offx

Parameters

segm	Segment to configure
data	Pointer to data buffer with gradient
wb	Length of buffer

◆ ScreenSegmGraph8()

void ScreenSegmGraph8	(	sSegm *	segm,
		const void *	data,
		int	wb
	)

Set video segment to native 8-bit graphics (R3G3B2)

8-bit graphics 256 colors (GF_GRAPH8). Each pixel is 1 byte. This mode is one of the fastest, the data is simply sent from the frame buffer to the PIO controller using a DMA transfer. However, it is also one of the most memory intensive. Really, the memory can hold a maximum image resolution of 512x400 pixels (EGA video mode).

Note: To scroll image, set virtual dimension wrapx and wrapy, then shift offx and offy.

Parameters

segm	Segment to configure
data	Pointer to data buffer
wb	Line length in bytes

◆ GenPal16Trans()

void GenPal16Trans	(	u16 *	trans,
		const u8 *	pal
	)

Generate 16-color palette translation table.

Generates a palette translation table for the ScreenSegmGraph4() function. The translation table is 256 entries of 16 bits, so it takes 512 bytes in memory. The table is used during display for internal purposes, must be aligned to 4 bytes, and must be available for the entire time the segment is displayed. The input to the function is the palette table, which is 16 color entries of 1 byte.

Parameters

trans	Pointer to destination palette translation table (u16 trans[256])
pal	Pointer to source palette of 16 colors (u8 pal[16])

◆ ScreenSegmGraph4()

void ScreenSegmGraph4	(	sSegm *	segm,
		const void *	data,
		const void *	trans,
		int	wb
	)

Set video segment to 4-bit palette graphics.

4-bit palette graphics 16 colors (GF_GRAPH4). There are 2 pixels in 1 byte (the first pixel is in the higher 4 bits of the byte). The function requires a palette translation table.

Note: To scroll image, set virtual dimension wrapx and wrapy, then shift offx and offy.

Parameters

segm	Segment to configure
data	Pointer to data buffer
trans	Pointer to 16-color palette translation table (generated with GenPal16Trans function)
wb	The line length in bytes

◆ GenPal4Trans()

void GenPal4Trans	(	u32 *	trans,
		const u8 *	pal
	)

Generate palette 4 translation table for function.

Generate a palette translation table for the ScreenSegmGraph2() function. The translation table is 256 entries with a size of 32 bits, so it takes 1024 bytes in memory. The table is used during display for internal purposes, must be aligned to 4 bytes, and must be available for the entire time the segment is displayed. The input to the function is the palette table, which is 4 color entries of 1 byte.

Parameters

trans	Pointer to destination palette translation table (u32 trans[256])
pal	Pointer to source palette of 4 colors (u8 pal[4])

◆ ScreenSegmGraph2()

void ScreenSegmGraph2	(	sSegm *	segm,
		const void *	data,
		const void *	trans,
		int	wb
	)

Set video segment to 2-bit palette graphics.

Note: To scroll image, set virtual dimension wrapx and wrapy, then shift offx and offy.

Parameters

segm	Segment to configure
data	Pointer to data buffer
trans	Pointer to 4-color palette translation table (generated with GenPal4Trans function)
wb	The line length in bytes

◆ ScreenSegmGraph1()

void ScreenSegmGraph1	(	sSegm *	segm,
		const void *	data,
		u8	bg,
		u8	fg,
		int	wb
	)

Set video segment to 1-bit palette graphics.

1-bit mono graphics 2 colors (GF_GRAPH1). There are 8 pixels in 1 byte (first pixel in the highest bit). The function requires background color and foreground color.

Note: To scroll image, set virtual dimension wrapx and wrapy, then shift offx and offy.

Parameters

segm	Segment to configure
data	Pointer to data buffer
bg	Background color
fg	Foreground color
wb	The line length in bytes

◆ ScreenSegmMText()

void ScreenSegmMText	(	sSegm *	segm,
		const void *	data,
		const void *	font,
		u16	fontheight,
		u8	bg,
		u8	fg,
		int	wb
	)

Set video segment to 8-pixel mono text.

Mono text (GF_MTEXT). For mono text, the foreground and background color is valid for the entire segment. In the display memory there are single characters, 1 byte is one character.

Parameters

segm	Segment to configure
data	Pointer to text buffer
font	Pointer to 1-bit font of 256 characters of width 8 (total width of image 2048 pixels)
fontheight	Font height
bg	Background color
fg	Foregound color
wb	The line length in bytes

◆ ScreenSegmAText()

void ScreenSegmAText	(	sSegm *	segm,
		const void *	data,
		const void *	font,
		u16	fontheight,
		const void *	pal,
		int	wb
	)

Set video segment to 8-pixel attribute text.

Attribute text (GF_ATEXT). In attribute text, each character is a pair of bytes. The first byte is the ASCII value of the character, the second byte is the color attribute. The higher 4 bits of the attribute represent the background color, the lower 4 bits of the attribute represent the foreground color. The colors are translated from a palette table of 16 colors.

Parameters

segm	Segment to configure
data	Pointer to text buffer (character + 2x4 bit attributes)
font	Pointer to 1-bit font of 256 characters of width 8 (total width of image 2048 pixels)
fontheight	Font height
pal	Pointer to palette of 16 colors
wb	The line length in bytes

◆ ScreenSegmFText()

void ScreenSegmFText	(	sSegm *	segm,
		const void *	data,
		const void *	font,
		u16	fontheight,
		u8	bg,
		int	wb
	)

Set video segment to 8-pixel foreground color text.

Text with foreground color (GF_FTEXT). In text with foreground, each character is represented by a pair of bytes. The first byte is ASCII value of the character, the second byte is foreground color. The background color is common, specified by the 'bg' parameter.

Note: Library's default fonts include an inverted lower half of the font in the upper half (bit 7 set) - this can provide a character with an optional background color.

Parameters

segm	Segment to configure
data	Pointer to text buffer (character + foreground color)
font	Pointer to 1-bit font of 256 characters of width 8 (total width of image 2048 pixels)
fontheight	Font height
bg	Background color
wb	The line length in bytes

◆ ScreenSegmCText()

void ScreenSegmCText	(	sSegm *	segm,
		const void *	data,
		const void *	font,
		u16	fontheight,
		int	wb
	)

Set video segment to 8-pixel color text.

Text with color (GF_CTEXT). For text with color, each character occupies 3 bytes. The first byte is the ASCII value of the character, the second byte is the background color, and the third byte is the foreground color.

Parameters

segm	Segment to configure
data	Pointer to text buffer (character + background color + foreground color)
font	Pointer to 1-bit font of 256 characters of width 8 (total width of image 2048 pixels)
fontheight	Font height
wb	The line length in bytes

◆ ScreenSegmGText()

void ScreenSegmGText	(	sSegm *	segm,
		const void *	data,
		const void *	font,
		u8	fontheight,
		u8	bg,
		const void *	grad,
		int	wb
	)

Set video segment to 8-pixel gradient color text.

Text with gradient (GF_GTEXT). In this mode, each character is represented by 1 byte in memory and the background color is specified by the 'bg' parameter, similar to the mono text. Instead of the foreground color, there is a parameter 'grad', which is a pointer to a color gradient of length equal to the graphic length of the line of text (e.g. for 40 characters, the gradient is 320 bytes). The foreground color for each pixel of the character is taken from the gradient table.

Parameters

segm	Segment to configure
data	Pointer to text buffer (character + foreground color)
font	Pointer to 1-bit font of 256 characters of width 8 (total width of image 2048 pixels)
fontheight	Font height
bg	Background color
grad	Pointer to array of gradient colors
wb	The line length in bytes

◆ ScreenSegmDText()

void ScreenSegmDText	(	sSegm *	segm,
		const void *	data,
		const void *	font,
		u8	fontheight,
		u8	bg,
		const void *	grad,
		int	wb
	)

Set video segment to 8-pixel double gradient color text.

Double gradient text (GF_DTEXT). The function is identical to the previous function, except that each character pixel is generated as 2 image pixels. Thus, the character has twice the width. It is the only text mode that allows displaying characters with double width. The color gradient works similarly here, but 1 byte of the gradient represents 1 pixel of the character (as in the previous function), not 1 pixel displayed. Thus a line of 40 characters again requires a gradient of 320 bytes.

Parameters

segm	Segment to configure
data	Pointer to text buffer (character + foreground color)
font	Pointer to 1-bit font of 256 characters of width 8 (total width of image 2048 pixels)
fontheight	Font height
bg	Background color
grad	Pointer to array of gradient colors
wb	The line length in bytes

◆ ScreenSegmTile()

void ScreenSegmTile	(	sSegm *	segm,
		const void *	data,
		const void *	tiles,
		int	w,
		int	h,
		int	wb
	)

Set video segment to tiles.

Tiles in column (GF_TILE). Tiles are image segments of the specified size (tile width and height are 'w' and 'h'). The tile patterns are arranged in a single image. In this case, into a column of width 1 tile. The 'tiles' parameter is a pointer to the image of the tile column. The 'data' parameter is a pointer to an array of bytes, where each byte represents number of displayed tile. Thus, there can be a maximum of 256 tiles. The 'wb' parameter refers to the length of the row of the index array (not the length of the tile image). The width of a tile must be a multiple of 4, at least 8. Tiles allow efficient display of image information by allowing the image to repeat. Thus, high image resolution can be achieved with low memory requirements.

Parameters

segm	Segment to configure
data	Pointer to tile map buffer (with tile indices)
tiles	Pointer to 1 column of tiles, 1 pixel = 8 bits
w	tile width (must be multiple of 4)
h	tile height
wb	Number of bytes between tile map rows

◆ ScreenSegmTile2()

void ScreenSegmTile2	(	sSegm *	segm,
		const void *	data,
		const void *	tiles,
		int	w,
		int	h,
		int	tilewb,
		int	wb
	)

Set video segment to alternate tiles.

Tiles in a row (GF_TILE2). This function is an alternative to ScreenSegmTile(), except that the tile patterns are arranged in a single row in the image. This may be more convenient when creating a tile image, however, you must additionally specify the parameter 'tilewb' representing the line length of the tile image. Usually tilewb = number of tiles * tile width.

Parameters

segm	Segment to configure
data	Pointer to tile map buffer (with tile indices)
tiles	Pointer to 1 row of tiles, 1 pixel = 8 bits
w	tile width (must be multiple of 4)
h	tile height
tilewb	Tile width bytes (usually tile width * number of tiles)
wb	Number of bytes between tile map rows

◆ ScreenSegmLevel()

void ScreenSegmLevel	(	sSegm *	segm,
		const void *	data,
		u8	zero,
		u8	bg,
		u8	fg
	)

Set video segment to level graph GF_LEVEL.

Level display segment (GF_LEVEL). This segment is used to display graphs. The input is an array of 'data' bytes of length corresponding to the width of the array in pixels. The byte value represents the height of the graph at the given X coordinate. The display will show a foreground or background color depending on whether the displayed pixel lies above or below the value from the data array. The 'zero' parameter specifies the height of the reference zero. Zero does not imply negative numbers in the data, the numbers are still given as unsigned (with zero at the bottom). Starting from reference zero, the background and foreground colour is swapped. This results in the graph looking visually symmetrical around the reference zero. You can see the appearance of the segment in the Oscilloscope sample program (lower curve).

Parameters

segm	Segment to configure
data	Pointer to buffer with line samples 0..255
zero	Y zero level
bg	Background color
fg	Foregound color

◆ ScreenSegmLevelGrad()

void ScreenSegmLevelGrad	(	sSegm *	segm,
		const void *	data,
		const void *	sample1,
		const void *	sample2
	)

Set video segment to leve gradient graph GF_LEVELGRAD.

Level display segment with gradient (GF_LEVELGRAD). This segment is used to display graphs, similar to the previous function. It differs in that the color is given as a vertical gradient with a height corresponding to the height of the segment. If a pixel lies below the data value, the color from the first gradient is used. Otherwise, the second gradient is used. An example use case can be seen in the Level Meter sample program, to display the spectrum.

Parameters

segm	Segment to configure
data	Pointer to buffer with values 0..255 of 4-pixels in rows
sample1	Scanline sample < data
sample2	Scanline sample >= data

◆ ScreenSegmOscil()

void ScreenSegmOscil	(	sSegm *	segm,
		const void *	data,
		u8	bg,
		u8	fg,
		int	pixh
	)

Set video segment to oscilloscope 1-pixel graph GF_OSCIL.

Oscilloscope waveform display segment (GF_OSCIL). The segment is similar in function to the level display segment. It differs in that the curve is displayed as a line of 'pixh' pixel thickness. This function is already more demanding and may not be able to service the full width of the image.

Parameters

segm	Segment to configure
data	Pointer to buffer with line samples 0..255
bg	Background color
fg	Foregound color
pixh	Height of pixels - 1

◆ ScreenSegmOscLine()

void ScreenSegmOscLine	(	sSegm *	segm,
		const void *	data,
		u8	bg,
		u8	fg
	)

Set video segment to oscilloscope line graph GF_OSCLIN.

Oscilloscope continuous waveform segment (GF_OSCLINE). The curve is displayed as a continuous line with a thickness of 1 pixel. This mode is already very demanding to render and is therefore accelerated by halving the horizontal resolution (renders points 2 pixels wide).

Parameters

segm	Segment to configure
data	Pointer to buffer with line samples 0..255
bg	Background color
fg	Foregound color

◆ GenPal4Plane()

void GenPal4Plane	(	u32 *	trans,
		const u8 *	pal
	)

Generate palette 4-color translation table for function ScreenSegmPlane2()

Generate a palette translation table for the ScreenSegmPlane2() function. The translation table is 256 entries of 32 bits, so it takes 1024 bytes in memory. The table is used during display for internal purposes, must be aligned to 4 bytes, and must be available for the entire time the segment is displayed. The input to the function is the palette table, which is 4 color entries of 1 byte. Although there is no program in the PicoVGA library utilities that prepares an image in 2-plane mode, there is an internal function Plane2Conv that converts a 4-color image to 2-plane mode. Thus, the image is attached to the program as a 4-color image, and the conversion function is used to prepare a copy in RAM.

Parameters

trans	Pointer to destination palette translation table (u32 trans[256])
pal	Pointer to source palette of 4 colors (u8 pal[4])

◆ ScreenSegmPlane2()

void ScreenSegmPlane2	(	sSegm *	segm,
		const void *	data,
		int	plane,
		const void *	trans,
		int	wb
	)

Set video segment to 4-color on 2-planes graphics.

2-bit palette graphics 4 colors in 2 planes (GF_PLANE2). The mode is functionally similar to the 2-bit color graphics mode, but the individual pixel bits are stored in 2 separate color planes. This mode is similar to the CGA graphics mode of PC computers. The individual planes correspond to two separate monochrome graphics modes. Each byte of the plane contains 8 pixels (the first pixel in the highest bit). The parameter 'plane' is the relative offset of the second plane from the first plane, given by the parameter 'data'. The function requires a palette translation table, which is generated by the GenPal4Plane() function.

Note: To scroll image, set virtual dimension wrapx and wrapy, then shift offx and offy.

Parameters

segm	Segment to configure
data	Pointer to data buffer
plane	Offset of 2nd graphics plane (in bytes), size of one graphics plane
trans	Pointer to 4-color palette translation table (generated with GenPal4Plane function)
wb	Number of bytes between lines

◆ ScreenSegmAttrib8()

void ScreenSegmAttrib8	(	sSegm *	segm,
		const void *	data,
		const void *	attr,
		const u8 *	pal,
		int	wb
	)

Set video segment to 2x4 bit color attribute per 8x8 pixel sample graphics.

Graphical mode with attributes (GF_ATTRIB8). This mode is known from ZX Spectrum computers. The 'data' parameter is a pointer to the pixel data. This corresponds to the monochrome display mode, where each bit distinguishes whether foreground or background color is used. The 'attr' parameter is a pointer to an array of color attributes. The color attribute is a byte, where the lower 4 bits represent the foreground color and the upper 4 bits the background color. The attribute is converted to a colored pixel using the palette table 'pal', which is an array of 16 bytes of colors. Each attribute specifies the foreground and background colors for a group of 8 x 8 pixels. Thus, for every 8 bytes of pixels, there is 1 byte of color attributes. The 'wb' parameter here specifies the line width in bytes for both the pixel array and the attribute array. The difference is that the address in the attributes array is not incremented after each line, but after 8 lines.

Although there is no program in the PicoVGA library utilities that prepares an image in attribute mode, there is an internal function Attr8Conv that converts an image in 16 colors to attribute mode. Thus, the image is attached to the program as a 16-color image, and the conversion function is used to prepare a copy in RAM.

Note: To scroll image, set virtual dimension wrapx and wrapy, then shift offx and offy.

Parameters

segm	Segment to configure
data	Pointer to data buffer with mono pixels
attr	Pointer to color attributes
pal	Pointer to 16-color palette table
wb	Number of bytes between lines

◆ ScreenSegmProgress()

void ScreenSegmProgress	(	sSegm *	segm,
		const void *	data,
		const void *	sample1,
		const void *	sample2
	)

Set video segment to horizontal progress indicator GF_PROGRESS.

Progress indicator (GF_PROGRESS). Progress indicator is a horizontal indicator. The parameter 'data' is an array of bytes of length corresponding to the height of the segment. The byte value indicates the line length in multiples of 4 pixels. Thus, a value of 0 to 255 represents an indicator length of 0 to 1020 pixels. For the first part of the indicator (< data) the colour gradient 'sample1' is displayed, for the second part (>= data) 'sample2' is displayed.

Parameters

segm	Segment to configure
data	Pointer to buffer with values 0..255 of 4-pixels in rows
sample1	Scanline sample < data
sample2	Scanline sample >= data

◆ ScreenSegmGraph8Mat()

void ScreenSegmGraph8Mat	(	sSegm *	segm,
		const void *	data,
		const int *	mat,
		u16	xbits,
		u16	ybits
	)

Set video segment to 8-bit graphics with 2D matrix transformation.

8-bit graphics with 2D matrix transformation. This segment displays an 8-bit image with transformations - rotate, scale, skew and shift. The image must have width and height as a power of 2. The width and height of the image are specified using the xbits and ybits parameters as the number of bits of the dimension. For example, for a 512 x 256 pixel image, xbits = 9, ybits = 8. The 'mat' parameter is a pointer to an array of 6 integer transformation matrix parameters - see the Transformation matrix section. The segment does not support parameters for image shifting and wrapping, they must be left at default values.

Note: Use default settings of parameters: offx = 0, offy = 0, wrapx = segment width, wrapy = segment height

Parameters

segm	Segment to configure
data	Pointer to image data (width and height of image must be power of 2)
mat	Pointer to array of 6 matrix integer parameters m11, m12...m23 (exported with ExportInt function)
xbits	Number of bits of image width (image width must be power of 2 and must be = pitch width bytes)
ybits	Number of bits of image height (image height must be power of 2)

◆ ScreenSegmGraph8Persp()

void ScreenSegmGraph8Persp	(	sSegm *	segm,
		const void *	data,
		const int *	mat,
		u16	xbits,
		u16	ybits,
		u16	horiz
	)

Set video segment to 8-bit graphics with perspective projection.

Note: Use default settings of parameters: offx = 0, offy = 0, wrapx = segment width, wrapy = segment height

Parameters

segm	Segment to configure
data	Pointer to image data (width and height of image must be power of 2)
mat	Pointer to array of 6 matrix integer parameters m11, m12...m23 (exported with ExportInt function)
xbits	Number of bits of image width (image width must be power of 2 and must be = pitch width bytes)
ybits	Number of bits of image height (image height must be power of 2)
horiz	Horizon offset

◆ ScreenSegmTilePersp()

void ScreenSegmTilePersp	(	sSegm *	segm,
		const u8 *	map,
		const u8 *	tiles,
		const int *	mat,
		u8	mapwbits,
		u8	maphbits,
		u8	tilebits,
		s8	horizon
	)

Set video segment to tiles with perspective.

Tile graphics with 3D perspective. Similar to the previous function, it is used to display terrain with 3D projection. It uses tile definition instead of 8-bit graphics. This allows the display of very large terrains. The 'map' parameter is a pointer to a map of tiles - tile indices 0 to 255. The width and height of the map must be powers of 2 and are specified as the number of mapwbits and maphbits. Tiles must have a square dimension, which must also be a power of 2. The tile dimension is specified by the tilebits parameter as the number of dimension bits. The 'tiles' parameter is a pointer to an image with a pattern of tiles arranged in 1 column of tiles. The 'horizon' parameter specifies the horizon offset over the segment boundary / 4. A positive number represents the horizon offset, a negative number will invert the perspective (can be used to display the sky). A zero value turns off the perspective - in this case the function is similar to the function for displaying an image with a transformation matrix (the array of tiles can be rotated, skewed, etc).

Note: Use default settings of parameters: offx = 0, offy = 0, wrapx = segment width, wrapy = segment height

Parameters

segm	Segment to configure
map	Pointer to tile map with tile indices (width and height must be power of 2)
tiles	Pointer to 1 column of square tiles, 1 pixel = 8 bits (width and height must be power of 2)
mat	Pointer to array of 6 matrix integer parameters m11, m12...m23 (exported with ExportInt function)
mapwbits	Number of bits of tile map width
maphbits	Number of bits of tile map height
tilebits	Number of bits of tile width and height
horizon	Horizon offset/4 (0=do not use perspective projection, <0=vertical flip to display ceiling)

◆ ScreenSegmTilePersp15()

void ScreenSegmTilePersp15	(	sSegm *	segm,
		const u8 *	map,
		const u8 *	tiles,
		const int *	mat,
		u8	mapwbits,
		u8	maphbits,
		u8	tilebits,
		s8	horizon
	)

Set video segment to tiles with perspective, 1.5 pixels.

Similar to ScreenSegmTilePersp(), but the pixels are rendered 1.5 pixels wide. This function can be used if the previous function does not keep up with the rendering speed.

Note: Use default settings of parameters: offx = 0, offy = 0, wrapx = segment width, wrapy = segment height

Parameters

segm	Segment to configure
map	Pointer to tile map with tile indices (width and height must be power of 2)
tiles	Pointer to 1 column of square tiles, 1 pixel = 8 bits (width and height must be power of 2)
mat	Pointer to array of 6 matrix integer parameters m11, m12...m23 (exported with ExportInt function)
mapwbits	Number of bits of tile map width
maphbits	Number of bits of tile map height
tilebits	Number of bits of tile width and height
horizon	Horizon offset/4 (0=do not use perspective projection, <0=vertical flip to display ceiling)

◆ ScreenSegmTilePersp2()

void ScreenSegmTilePersp2	(	sSegm *	segm,
		const u8 *	map,
		const u8 *	tiles,
		const int *	mat,
		u8	mapwbits,
		u8	maphbits,
		u8	tilebits,
		s8	horizon
	)

Set video segment to tiles with perspective, double pixels.

Similar to ScreenSegmTilePersp(), but the pixels are rendered 2 pixels wide. This function can be used if the previous function does not keep up with the rendering speed.

Note: Use default settings of parameters: offx = 0, offy = 0, wrapx = segment width, wrapy = segment height

Parameters

segm	Segment to configure
map	Pointer to tile map with tile indices (width and height must be power of 2)
tiles	Pointer to 1 column of square tiles, 1 pixel = 8 bits (width and height must be power of 2)
mat	Pointer to array of 6 matrix integer parameters m11, m12...m23 (exported with ExportInt function)
mapwbits	Number of bits of tile map width
maphbits	Number of bits of tile map height
tilebits	Number of bits of tile width and height
horizon	Horizon offset/4 (0=do not use perspective projection, <0=vertical flip to display ceiling)

◆ ScreenSegmTilePersp3()

void ScreenSegmTilePersp3	(	sSegm *	segm,
		const u8 *	map,
		const u8 *	tiles,
		const int *	mat,
		u8	mapwbits,
		u8	maphbits,
		u8	tilebits,
		s8	horizon
	)

Set video segment to tiles with perspective, triple pixels.

Similar to ScreenSegmTilePersp(), but the pixels are rendered 3 pixels wide. This function can be used if the previous function does not keep up with the rendering speed.

Note: Use default settings of parameters: offx = 0, offy = 0, wrapx = segment width, wrapy = segment height

Parameters

segm	Segment to configure
map	Pointer to tile map with tile indices (width and height must be power of 2)
tiles	Pointer to 1 column of square tiles, 1 pixel = 8 bits (width and height must be power of 2)
mat	Pointer to array of 6 matrix integer parameters m11, m12...m23 (exported with ExportInt function)
mapwbits	Number of bits of tile map width
maphbits	Number of bits of tile map height
tilebits	Number of bits of tile width and height
horizon	Horizon offset/4 (0=do not use perspective projection, <0=vertical flip to display ceiling)

◆ ScreenSegmTilePersp4()

void ScreenSegmTilePersp4	(	sSegm *	segm,
		const u8 *	map,
		const u8 *	tiles,
		const int *	mat,
		u8	mapwbits,
		u8	maphbits,
		u8	tilebits,
		s8	horizon
	)

Set video segment to tiles with perspective, quadruple pixels.

Similar to ScreenSegmTilePersp(), but the pixels are rendered 4 pixels wide. This function can be used if the previous function does not keep up with the rendering speed.

Note: Use default settings of parameters: offx = 0, offy = 0, wrapx = segment width, wrapy = segment height

Parameters

segm	Segment to configure
map	Pointer to tile map with tile indices (width and height must be power of 2)
tiles	Pointer to 1 column of square tiles, 1 pixel = 8 bits (width and height must be power of 2)
mat	Pointer to array of 6 matrix integer parameters m11, m12...m23 (exported with ExportInt function)
mapwbits	Number of bits of tile map width
maphbits	Number of bits of tile map height
tilebits	Number of bits of tile width and height
horizon	Horizon offset/4 (0=do not use perspective projection, <0=vertical flip to display ceiling)

Description

Data Structures

Functions

Variables

Function Documentation

◆ ScreenClear()

◆ ScreenAddStrip()

◆ ScreenAddSegm()

◆ ScreenSegmColor()

◆ ScreenSegmGrad1()

◆ ScreenSegmGrad2()

◆ ScreenSegmGraph8()

◆ GenPal16Trans()

◆ ScreenSegmGraph4()

◆ GenPal4Trans()

◆ ScreenSegmGraph2()

◆ ScreenSegmGraph1()

◆ ScreenSegmMText()

◆ ScreenSegmAText()

◆ ScreenSegmFText()

◆ ScreenSegmCText()

◆ ScreenSegmGText()

◆ ScreenSegmDText()

◆ ScreenSegmTile()

◆ ScreenSegmTile2()

◆ ScreenSegmLevel()

◆ ScreenSegmLevelGrad()

◆ ScreenSegmOscil()

◆ ScreenSegmOscLine()

◆ GenPal4Plane()

◆ ScreenSegmPlane2()

◆ ScreenSegmAttrib8()

◆ ScreenSegmProgress()

◆ ScreenSegmGraph8Mat()

◆ ScreenSegmGraph8Persp()

◆ ScreenSegmTilePersp()

◆ ScreenSegmTilePersp15()

◆ ScreenSegmTilePersp2()

◆ ScreenSegmTilePersp3()

◆ ScreenSegmTilePersp4()