VDP background plane support. More...

#include "bmp.h"
#include "vdp.h"
#include "vdp_tile.h"

Include dependency graph for vdp_bg.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	Image
	Image structure which contains all data to define an image in a background plane. Use the unpackImage() method to unpack if compression is enabled in TileSet or TileMap structure. More...

Functions
void	VDP_setHorizontalScroll (VDPPlane plane, s16 value)
	Set plane horizontal scroll (plain scroll mode). 3 horizontal scroll modes are supported:

void	VDP_setHorizontalScrollVSync (VDPPlane plane, s16 value)
	Same as VDP_setHorizontalScroll(..) except that it will delay scroll update on VSync.

void	VDP_setHorizontalScrollTile (VDPPlane plane, u16 tile, s16 *values, u16 len, TransferMethod tm)
	Set plane horizontal scroll (tile scroll mode). 3 horizontal scroll modes are supported:

void	VDP_setHorizontalScrollLine (VDPPlane plane, u16 line, s16 *values, u16 len, TransferMethod tm)
	Set plane horizontal scroll (line scroll mode). 3 horizontal scroll modes are supported:

void	VDP_setVerticalScroll (VDPPlane plane, s16 value)
	Set plane vertical scroll (plain scroll mode). 2 vertical scroll modes are supported:

void	VDP_setVerticalScrollVSync (VDPPlane plane, s16 value)
	Same as VDP_setVerticalScroll(..) except that it will delay scroll update on VSync.

void	VDP_setVerticalScrollTile (VDPPlane plane, u16 tile, s16 *values, u16 len, TransferMethod tm)
	Set plane vertical scroll (2-Tiles scroll mode). 2 vertical scroll modes are supported:

void	VDP_clearPlane (VDPPlane plane, bool wait)
	Clear specified plane (using DMA).

VDPPlane	VDP_getTextPlane (void)
	Returns the plane used to display text.

u16	VDP_getTextPalette (void)
	Returns the palette number used to display text.

u16	VDP_getTextPriority (void)
	Returns the priority used to display text.

void	VDP_setTextPlane (VDPPlane plane)
	Define the plane to use to display text.

void	VDP_setTextPalette (u16 palette)
	Define the palette to use to display text.

void	VDP_setTextPriority (u16 prio)
	Define the priority to use to display text.

void	VDP_drawTextEx (VDPPlane plane, const char *str, u16 basetile, u16 x, u16 y, TransferMethod tm)
	Draw text in specified plane (advanced method).

void	VDP_clearTextEx (VDPPlane plane, u16 basetile, u16 x, u16 y, u16 w, TransferMethod tm)
	Clear a single line portion of text (advanced method).

void	VDP_clearTextAreaEx (VDPPlane plane, u16 basetile, u16 x, u16 y, u16 w, u16 h, TransferMethod tm)
	Clear a specific area of text (advanced method).

void	VDP_drawTextBG (VDPPlane plane, const char *str, u16 x, u16 y)
	Draw text in specified plane.

void	VDP_clearTextBG (VDPPlane plane, u16 x, u16 y, u16 w)
	Clear a single line portion of text.

void	VDP_clearTextAreaBG (VDPPlane plane, u16 x, u16 y, u16 w, u16 h)
	Clear a specific area of text.

void	VDP_clearTextLineBG (VDPPlane plane, u16 y)
	Clear a complete line of text.

void	VDP_drawText (const char *str, u16 x, u16 y)
	Draw text.

void	VDP_drawTextBGFill (VDPPlane plane, const char *str, u16 x, u16 y, u16 len)
	Draw text in specified plane and clear remaining unused space. If the new line is shorter than the one previously drawn in this place, the old characters will be removed. This function works significantly faster than calling VDP_clearText() and then VDP_drawText(). It is suitable when a lot of updating information needs to be displayed on the screen.

void	VDP_drawTextFill (const char *str, u16 x, u16 y, u16 len)
	Draw text and clear remaining unused space. If the new line is shorter than the one previously drawn in this place, the old characters will be removed. This function works significantly faster than calling VDP_clearText() and then VDP_drawText(). It is suitable when a lot of updating information needs to be displayed on the screen.

void	VDP_clearText (u16 x, u16 y, u16 w)
	Clear a single line portion of text.

void	VDP_clearTextArea (u16 x, u16 y, u16 w, u16 h)
	Clear a specific area of text.

void	VDP_clearTextLine (u16 y)
	Clear a complete line of text.

bool	VDP_drawBitmap (VDPPlane plane, const Bitmap *bitmap, u16 x, u16 y)
	Draw Bitmap in specified background plane and at given position.

bool	VDP_drawBitmapEx (VDPPlane plane, const Bitmap *bitmap, u16 basetile, u16 x, u16 y, bool loadpal)
	Draw Bitmap in specified background plane and at given position.

bool	VDP_drawImage (VDPPlane plane, const Image *image, u16 x, u16 y)
	Draw Image (using DMA) in specified background plane and at given position.

bool	VDP_drawImageEx (VDPPlane plane, const Image *image, u16 basetile, u16 x, u16 y, bool loadpal, bool dma)
	Draw Image in specified background plane and at given position.

Variables
u16	curTileInd

Detailed Description

VDP background plane support.

Author: Stephane Dallongeville

Date: 08/2011

This unit provides plane A & plane B facilities :

set scrolling
clear plane
draw text in plane

Function Documentation

◆ VDP_clearPlane()

void VDP_clearPlane	(	VDPPlane	plane,
		bool	wait )

Clear specified plane (using DMA).

Parameters

plane	Plane we want to clear. Accepted values are: BG_A BG_B WINDOW
wait	Wait the operation to complete when set to TRUE otherwise it returns immediately but then you will require to wait for DMA completion (DMA_waitCompletion()) before accessing the VDP.

◆ VDP_clearText()

void VDP_clearText	(	u16	x,
		u16	y,
		u16	w )

Clear a single line portion of text.

Parameters

x	X position (in tile).
y	y position (in tile).
w	width to clear (in tile).

See also: VDP_drawText(..); VDP_clearTextArea(..); VDP_clearTextLine(..)

◆ VDP_clearTextArea()

void VDP_clearTextArea	(	u16	x,
		u16	y,
		u16	w,
		u16	h )

Clear a specific area of text.

Parameters

x	X position (in tile).
y	y position (in tile).
w	width to clear (in tile).
h	heigth to clear (in tile).

See also: VDP_drawText(..); VDP_clearText(..); VDP_clearTextLine(..)

◆ VDP_clearTextAreaBG()

void VDP_clearTextAreaBG	(	VDPPlane	plane,
		u16	x,
		u16	y,
		u16	w,
		u16	h )

Clear a specific area of text.

Parameters

plane	Plane where we want to clear text. Accepted values are: BG_A BG_B WINDOW
x	X position (in tile).
y	y position (in tile).
w	width to clear (in tile).
h	heigth to clear (in tile).

See also: VDP_clearTextAreaEx(..); VDP_drawText(..); VDP_clearText(..); VDP_clearTextLine(..)

◆ VDP_clearTextAreaEx()

void VDP_clearTextAreaEx	(	VDPPlane	plane,
		u16	basetile,
		u16	x,
		u16	y,
		u16	w,
		u16	h,
		TransferMethod	tm )

Clear a specific area of text (advanced method).

Parameters

plane	Plane where we want to clear text. Accepted values are: BG_A BG_B WINDOW
basetile	Base tile attributes data (see TILE_ATTR() macro).
x	X position (in tile).
y	y position (in tile).
w	width to clear (in tile).
h	heigth to clear (in tile).
tm	Transfer method, using DMA_QUEUE or DMA_QUEUE_COPY ensure that it will be executed during VBlank. Accepted values are: CPU DMA DMA_QUEUE DMA_QUEUE_COPY

See also: VDP_drawText(..); VDP_clearText(..)

Here is the call graph for this function:

◆ VDP_clearTextBG()

void VDP_clearTextBG	(	VDPPlane	plane,
		u16	x,
		u16	y,
		u16	w )

Clear a single line portion of text.

Parameters

plane	Plane where we want to clear text. Accepted values are: BG_A BG_B WINDOW
x	X position (in tile).
y	y position (in tile).
w	width to clear (in tile).

See also: VDP_clearTextEx(..); VDP_drawText(..); VDP_clearTextArea(..); VDP_clearTextLine(..)

◆ VDP_clearTextEx()

void VDP_clearTextEx	(	VDPPlane	plane,
		u16	basetile,
		u16	x,
		u16	y,
		u16	w,
		TransferMethod	tm )

Clear a single line portion of text (advanced method).

Parameters

plane	Plane where we want to clear text. Accepted values are: BG_A BG_B WINDOW
basetile	Base tile attributes data (see TILE_ATTR() macro).
x	X position (in tile).
y	y position (in tile).
w	width to clear (in tile).
tm	Transfer method, using DMA_QUEUE or DMA_QUEUE_COPY ensure that it will be executed during VBlank. Accepted values are: CPU DMA DMA_QUEUE DMA_QUEUE_COPY

See also: VDP_drawText(..); VDP_clearTextArea(..); VDP_clearTextLine(..)

Here is the call graph for this function:

◆ VDP_clearTextLine()

void VDP_clearTextLine ( u16 y )

Clear a complete line of text.

Parameters

y	y position (in tile).

See also: VDP_drawText(..); VDP_clearText(..); VDP_clearTextArea(..)

◆ VDP_clearTextLineBG()

void VDP_clearTextLineBG	(	VDPPlane	plane,
		u16	y )

Clear a complete line of text.

Parameters

plane	Plane where we want to clear text. Accepted values are: BG_A BG_B WINDOW
y	y position (in tile).

See also: VDP_drawText(..); VDP_clearText(..); VDP_clearTextArea(..)

◆ VDP_drawBitmap()

bool VDP_drawBitmap	(	VDPPlane	plane,
		const Bitmap *	bitmap,
		u16	x,
		u16	y )

Draw Bitmap in specified background plane and at given position.

Parameters

plane	Plane where we want to draw the bitmap. Accepted values are: BG_A BG_B WINDOW
bitmap	Genesis bitmap (the width and height should be aligned to 8). The Bitmap is unpacked "on the fly" if needed (require some memory).
x	Plane X position (in tile).
y	Plane Y position (in tile).

Returns: FALSE if there is not enough memory to unpack the specified Bitmap (only if compression was enabled).

This function does "on the fly" 4bpp bitmap conversion to tile data and transfert them to VRAM.
It's very helpful when you use bitmap images but the conversion eats sometime so you should use it only for static screen only.
For "in-game" condition you should use VDP_loadTileData() method with prepared tile data.

See also: VDP_loadBMPTileData()

◆ VDP_drawBitmapEx()

bool VDP_drawBitmapEx	(	VDPPlane	plane,
		const Bitmap *	bitmap,
		u16	basetile,
		u16	x,
		u16	y,
		bool	loadpal )

Draw Bitmap in specified background plane and at given position.

Parameters

plane	Plane where we want to draw the bitmap. Accepted values are: BG_A BG_B WINDOW
bitmap	Genesis bitmap (the width and height should be aligned to 8). The Bitmap is unpacked "on the fly" if needed (require some memory).
basetile	Base tile attributes data (see TILE_ATTR_FULL() macro).
x	Plane X position (in tile).
y	Plane Y position (in tile).
loadpal	Load the bitmap palette information when non zero (can be TRUE or FALSE)

Returns: FALSE if there is not enough memory to unpack the specified Bitmap (only if compression was enabled).

This function does "on the fly" 4bpp bitmap conversion to tile data and transfert them to VRAM.
It's very helpful when you use bitmap images but the conversion eats sometime so you should use it only for static screen only.
For "in-game" condition you should use VDP_loadTileData() method with prepared tile data.

See also: VDP_loadBMPTileData()

Here is the call graph for this function:

◆ VDP_drawImage()

bool VDP_drawImage	(	VDPPlane	plane,
		const Image *	image,
		u16	x,
		u16	y )

Draw Image (using DMA) in specified background plane and at given position.

Parameters

plane	Plane where we want to draw the tilemap. Accepted values are: BG_A BG_B WINDOW
image	Image structure to draw. The Image is unpacked "on the fly" if needed (require some memory).
x	Plane X position (in tile).
y	Plane Y position (in tile).

Returns: FALSE if there is not enough memory to unpack the specified Image (only if compression was enabled).

Load the image tiles data in VRAM and display it at specified plane position.

See also: VDP_drawImageEx()

◆ VDP_drawImageEx()

bool VDP_drawImageEx	(	VDPPlane	plane,
		const Image *	image,
		u16	basetile,
		u16	x,
		u16	y,
		bool	loadpal,
		bool	dma )

Draw Image in specified background plane and at given position.

Parameters

plane	Plane where we want to load tilemap. Accepted values are: BG_A BG_B WINDOW
image	Image structure to draw. The Image is unpacked "on the fly" if needed (require some memory).
basetile	Base tile attributes data (see TILE_ATTR_FULL() macro).
x	Plane X position (in tile).
y	Plane Y position (in tile).
loadpal	Load the bitmap palette information when non zero (can be TRUE or FALSE)
dma	use DMA

Returns: FALSE if there is not enough memory to unpack the specified Image (only if image was packed).

Load the image tiles data in VRAM and display it at specified plane position.

See also: VDP_drawImage()

◆ VDP_drawText()

void VDP_drawText	(	const char *	str,
		u16	x,
		u16	y )

Draw text.

Parameters

str	String to draw.
x	X position (in tile).
y	y position (in tile).

See also: VDP_clearText(..); VDP_setTextPalette(..); VDP_setTextPriority(..); VDP_setTextPlane(..)

◆ VDP_drawTextBG()

void VDP_drawTextBG	(	VDPPlane	plane,
		const char *	str,
		u16	x,
		u16	y )

Draw text in specified plane.

Parameters

plane	Plane where we want to draw text. Accepted values are: BG_A BG_B WINDOW
str	String to draw.
x	X position (in tile).
y	y position (in tile).

See also: VDP_drawTextEx(..); VDP_clearText(..); VDP_setTextPalette(..); VDP_setTextPriority(..); VDP_setTextPlane(..)

◆ VDP_drawTextBGFill()

void VDP_drawTextBGFill	(	VDPPlane	plane,
		const char *	str,
		u16	x,
		u16	y,
		u16	len )

Draw text in specified plane and clear remaining unused space.
If the new line is shorter than the one previously drawn in this place, the old characters will be removed.
This function works significantly faster than calling VDP_clearText() and then VDP_drawText(). It is suitable when a lot of updating information needs to be displayed on the screen.

Parameters

plane	Plane where we want to draw text. Accepted values are: BG_A BG_B WINDOW
str	String to draw. For correct operation, it must not exceed 40 characters.
x	X position (in tile).
y	y position (in tile).
len	Fixed string length. For correct operation, it must not exceed 40 characters.

See also: VDP_drawText(..); VDP_clearText(..); VDP_setTextPalette(..); VDP_setTextPriority(..); VDP_setTextPlane(..)

◆ VDP_drawTextEx()

void VDP_drawTextEx	(	VDPPlane	plane,
		const char *	str,
		u16	basetile,
		u16	x,
		u16	y,
		TransferMethod	tm )

Draw text in specified plane (advanced method).

Parameters

plane	Plane where we want to draw text. Accepted values are: BG_A BG_B WINDOW
str	String to draw.
basetile	Base tile attributes data (see TILE_ATTR() macro).
x	X position (in tile).
y	y position (in tile).
tm	Transfer method, using DMA_QUEUE or DMA_QUEUE_COPY ensure that it will be executed during VBlank. Accepted values are: CPU DMA DMA_QUEUE DMA_QUEUE_COPY

See also: VDP_clearText(..); VDP_setTextPalette(..); VDP_setTextPriority(..); VDP_setTextPlane(..)

◆ VDP_drawTextFill()

void VDP_drawTextFill	(	const char *	str,
		u16	x,
		u16	y,
		u16	len )

Draw text and clear remaining unused space.
If the new line is shorter than the one previously drawn in this place, the old characters will be removed.
This function works significantly faster than calling VDP_clearText() and then VDP_drawText(). It is suitable when a lot of updating information needs to be displayed on the screen.

Parameters

str	String to draw. For correct operation, it must not exceed 40 characters.
x	X position (in tile).
y	y position (in tile).
len	Fixed string length. For correct operation, it must not exceed 40 characters.

See also: VDP_drawText(..); VDP_clearText(..); VDP_setTextPalette(..); VDP_setTextPriority(..); VDP_setTextPlane(..)

◆ VDP_getTextPalette()

u16 VDP_getTextPalette ( void )

Returns the palette number used to display text.

See also: VDP_drawText(..); VDP_clearText(..)

◆ VDP_getTextPlane()

VDPPlane VDP_getTextPlane ( void )

Returns the plane used to display text.

Returned value should be either equals to BG_A, BG_B or WINDOW.

See also: VDP_drawText(..); VDP_clearText(..)

◆ VDP_getTextPriority()

u16 VDP_getTextPriority ( void )

Returns the priority used to display text.

See also: VDP_drawText(..); VDP_clearText(..)

◆ VDP_setHorizontalScroll()

void VDP_setHorizontalScroll	(	VDPPlane	plane,
		s16	value )

Set plane horizontal scroll (plain scroll mode).
3 horizontal scroll modes are supported:

Plain (whole plane)
Tile (8 pixels bloc)
Line (per pixel scroll)

Parameters

plane	Plane we want to set the horizontal scroll. Accepted values are: BG_A BG_B
value	H scroll offset. Negative value will move the plane to the left while positive value will move it to the right.

See also: VDP_setScrollingMode() function to change scroll mode.; VDP_setHorizontalScrollVSync()

◆ VDP_setHorizontalScrollLine()

void VDP_setHorizontalScrollLine	(	VDPPlane	plane,
		u16	line,
		s16 *	values,
		u16	len,
		TransferMethod	tm )

Set plane horizontal scroll (line scroll mode).
3 horizontal scroll modes are supported:

Plain (whole plane)
Tile (8 pixels bloc)
Line (per pixel scroll)

Parameters

plane	Plane we want to set the horizontal scroll. Accepted values are: BG_A BG_B
line	First line we want to set the horizontal scroll.
values	H scroll offsets. Negative values will move the plane to the left while positive values will move it to the right.
len	Number of line to set.
tm	Transfer method, it's recommended to use DMA_QUEUE so it will be executed as fast as possible during VBlank. Accepted values are: CPU DMA DMA_QUEUE DMA_QUEUE_COPY

See also: VDP_setScrollingMode()

◆ VDP_setHorizontalScrollTile()

void VDP_setHorizontalScrollTile	(	VDPPlane	plane,
		u16	tile,
		s16 *	values,
		u16	len,
		TransferMethod	tm )

Set plane horizontal scroll (tile scroll mode).
3 horizontal scroll modes are supported:

Plain (whole plane)
Tile (8 pixels bloc)
Line (per pixel scroll)

Parameters

plane	Plane we want to set the horizontal scroll. Accepted values are: BG_A BG_B
tile	First tile we want to set the horizontal scroll.
values	H scroll offsets. Negative values will move the plane to the left while positive values will move it to the right.
len	Number of tile to set.
tm	Transfer method, it's recommended to use DMA_QUEUE so it will be executed as fast as possible during VBlank. Accepted values are: CPU DMA DMA_QUEUE DMA_QUEUE_COPY

See also: VDP_setScrollingMode() function to change scroll mode.

◆ VDP_setHorizontalScrollVSync()

void VDP_setHorizontalScrollVSync	(	VDPPlane	plane,
		s16	value )

Same as VDP_setHorizontalScroll(..) except that it will delay scroll update on VSync.

Parameters

plane	Plane we want to set the horizontal scroll. Accepted values are: BG_A BG_B
value	H scroll offset. Negative value will move the plane to the left while positive value will move it to the right.

See also: VDP_setHorizontalScroll()

◆ VDP_setTextPalette()

void VDP_setTextPalette ( u16 palette )

Define the palette to use to display text.

Parameters

palette Palette number.

See also: VDP_drawText(..); VDP_clearText(..)

◆ VDP_setTextPlane()

void VDP_setTextPlane ( VDPPlane plane )

Define the plane to use to display text.

Parameters

plane

Plane where to display text.
Accepted values are:

BG_A
BG_B
WINDOW

See also: VDP_drawText(..); VDP_clearText(..)

◆ VDP_setTextPriority()

void VDP_setTextPriority ( u16 prio )

Define the priority to use to display text.

Parameters

prio	Priority: 1 = HIGH PRIORITY TILE. 0 = LOW PRIORITY TILE.

See also: VDP_drawText(..); VDP_clearText(..)

◆ VDP_setVerticalScroll()

void VDP_setVerticalScroll	(	VDPPlane	plane,
		s16	value )

Set plane vertical scroll (plain scroll mode). 2 vertical scroll modes are supported:

Plain (whole plane)
2-Tiles (16 pixels bloc)

Parameters

plane	Plane we want to set the vertical scroll. Accepted values are: BG_A BG_B
value	V scroll offset. Negative value will move the plane down while positive value will move it up.

See also: VDP_setScrollingMode()

◆ VDP_setVerticalScrollTile()

void VDP_setVerticalScrollTile	(	VDPPlane	plane,
		u16	tile,
		s16 *	values,
		u16	len,
		TransferMethod	tm )

Set plane vertical scroll (2-Tiles scroll mode). 2 vertical scroll modes are supported:

Plain (whole plane)
2-Tiles (16 pixels bloc)

Parameters

plane	Plane we want to set the vertical scroll. Accepted values are: BG_A BG_B
tile	First tile we want to set the vertical scroll.
values	V scroll offsets. Negative values will move the plane down while positive values will move it up.
len	Number of tile to set.
tm	Transfer method, it's recommended to use DMA_QUEUE so it will be executed as fast as possible during VBlank. Accepted values are: CPU DMA DMA_QUEUE DMA_QUEUE_COPY

See also: VDP_setScrollingMode()

◆ VDP_setVerticalScrollVSync()

void VDP_setVerticalScrollVSync	(	VDPPlane	plane,
		s16	value )

Same as VDP_setVerticalScroll(..) except that it will delay scroll update on VSync.

Parameters

plane	Plane we want to set the vertical scroll. Accepted values are: BG_A BG_B
value	V scroll offset. Negative value will move the plane down while positive value will move it up.

See also: VDP_setHorizontalScroll()

Variable Documentation

◆ curTileInd

u16 curTileInd

extern

Contains current VRAM tile position where we will upload next tile data.

See also: VDP_drawBitmap(); VDP_drawImage()

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ VDP_clearPlane()

◆ VDP_clearText()

◆ VDP_clearTextArea()

◆ VDP_clearTextAreaBG()

◆ VDP_clearTextAreaEx()

◆ VDP_clearTextBG()

◆ VDP_clearTextEx()

◆ VDP_clearTextLine()

◆ VDP_clearTextLineBG()

◆ VDP_drawBitmap()

◆ VDP_drawBitmapEx()

◆ VDP_drawImage()

◆ VDP_drawImageEx()

◆ VDP_drawText()

◆ VDP_drawTextBG()

◆ VDP_drawTextBGFill()

◆ VDP_drawTextEx()

◆ VDP_drawTextFill()

◆ VDP_getTextPalette()

◆ VDP_getTextPlane()

◆ VDP_getTextPriority()

◆ VDP_setHorizontalScroll()

◆ VDP_setHorizontalScrollLine()

◆ VDP_setHorizontalScrollTile()

◆ VDP_setHorizontalScrollVSync()

◆ VDP_setTextPalette()

◆ VDP_setTextPlane()

◆ VDP_setTextPriority()

◆ VDP_setVerticalScroll()

◆ VDP_setVerticalScrollTile()

◆ VDP_setVerticalScrollVSync()

Variable Documentation

◆ curTileInd