sgdk
vdp_bg.h File Reference

VDP background plane support. More...

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

Go to the source code of 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_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_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 ()
 Returns the plane used to display text.
u16 VDP_getTextPalette ()
 Returns the palette number used to display text.
u16 VDP_getTextPriority ()
 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_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_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.
u16 VDP_drawBitmap (VDPPlane plane, const Bitmap *bitmap, u16 x, u16 y)
 Draw Bitmap in specified background plane and at given position.
u16 VDP_drawBitmapEx (VDPPlane plane, const Bitmap *bitmap, u16 basetile, u16 x, u16 y, u16 loadpal)
 Draw Bitmap in specified background plane and at given position.
u16 VDP_drawImage (VDPPlane plane, const Image *image, u16 x, u16 y)
 Draw Image (using DMA) in specified background plane and at given position.
u16 VDP_drawImageEx (VDPPlane plane, const Image *image, u16 basetile, u16 x, u16 y, u16 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

void VDP_clearPlane ( VDPPlane  plane,
bool  wait 
)

Clear specified plane (using DMA).

Parameters:
planePlane we want to clear.
Accepted values are:
  • BG_A
  • BG_B
  • WINDOW
waitWait 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.
void VDP_clearText ( u16  x,
u16  y,
u16  w 
)

Clear a single line portion of text.

Parameters:
xX position (in tile).
yy position (in tile).
wwidth to clear (in tile).
See also:
VDP_drawText(..)
VDP_clearTextArea(..)
VDP_clearTextLine(..)
void VDP_clearTextArea ( u16  x,
u16  y,
u16  w,
u16  h 
)

Clear a specific area of text.

Parameters:
xX position (in tile).
yy position (in tile).
wwidth to clear (in tile).
hheigth to clear (in tile).
See also:
VDP_drawText(..)
VDP_clearText(..)
VDP_clearTextLine(..)
void VDP_clearTextAreaBG ( VDPPlane  plane,
u16  x,
u16  y,
u16  w,
u16  h 
)

Clear a specific area of text.

Parameters:
planePlane where we want to clear text.
Accepted values are:
  • BG_A
  • BG_B
  • WINDOW
xX position (in tile).
yy position (in tile).
wwidth to clear (in tile).
hheigth to clear (in tile).
See also:
VDP_drawText(..)
VDP_clearText(..)
VDP_clearTextLine(..)
void VDP_clearTextBG ( VDPPlane  plane,
u16  x,
u16  y,
u16  w 
)

Clear a single line portion of text.

Parameters:
planePlane where we want to clear text.
Accepted values are:
  • BG_A
  • BG_B
  • WINDOW
xX position (in tile).
yy position (in tile).
wwidth to clear (in tile).
See also:
VDP_drawText(..)
VDP_clearTextArea(..)
VDP_clearTextLine(..)
void VDP_clearTextLine ( u16  y)

Clear a complete line of text.

Parameters:
yy position (in tile).
See also:
VDP_drawText(..)
VDP_clearText(..)
VDP_clearTextArea(..)
void VDP_clearTextLineBG ( VDPPlane  plane,
u16  y 
)

Clear a complete line of text.

Parameters:
planePlane where we want to clear text.
Accepted values are:
  • BG_A
  • BG_B
  • WINDOW
yy position (in tile).
See also:
VDP_drawText(..)
VDP_clearText(..)
VDP_clearTextArea(..)
u16 VDP_drawBitmap ( VDPPlane  plane,
const Bitmap bitmap,
u16  x,
u16  y 
)

Draw Bitmap in specified background plane and at given position.

Parameters:
planePlane where we want to draw the bitmap.
Accepted values are:
  • BG_A
  • BG_B
  • WINDOW
bitmapGenesis bitmap (the width and height should be aligned to 8).
The Bitmap is unpacked "on the fly" if needed (require some memory).
xPlane X position (in tile).
yPlane 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()
u16 VDP_drawBitmapEx ( VDPPlane  plane,
const Bitmap bitmap,
u16  basetile,
u16  x,
u16  y,
u16  loadpal 
)

Draw Bitmap in specified background plane and at given position.

Parameters:
planePlane where we want to draw the bitmap.
Accepted values are:
  • BG_A
  • BG_B
  • WINDOW
bitmapGenesis bitmap (the width and height should be aligned to 8).
The Bitmap is unpacked "on the fly" if needed (require some memory).
basetileBase tile attributes data (see TILE_ATTR_FULL() macro).
xPlane X position (in tile).
yPlane Y position (in tile).
loadpalLoad the bitmap palette information when non zero.
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()
u16 VDP_drawImage ( VDPPlane  plane,
const Image image,
u16  x,
u16  y 
)

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

Parameters:
planePlane where we want to draw the tilemap.
Accepted values are:
  • BG_A
  • BG_B
  • WINDOW
imageImage structure to draw.
The Image is unpacked "on the fly" if needed (require some memory).
xPlane X position (in tile).
yPlane 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()
u16 VDP_drawImageEx ( VDPPlane  plane,
const Image image,
u16  basetile,
u16  x,
u16  y,
u16  loadpal,
bool  dma 
)

Draw Image in specified background plane and at given position.

Parameters:
planePlane where we want to load tilemap.
Accepted values are:
  • BG_A
  • BG_B
  • WINDOW
imageImage structure to draw.
The Image is unpacked "on the fly" if needed (require some memory).
basetileBase tile attributes data (see TILE_ATTR_FULL() macro).
xPlane X position (in tile).
yPlane Y position (in tile).
loadpalLoad the bitmap palette information when non zero (can be TRUE or FALSE)
dmause 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()
void VDP_drawText ( const char *  str,
u16  x,
u16  y 
)

Draw text.

Parameters:
strString to draw.
xX position (in tile).
yy position (in tile).
See also:
VDP_clearText(..)
VDP_setTextPalette(..)
VDP_setTextPriority(..)
VDP_setTextPlane(..)
void VDP_drawTextBG ( VDPPlane  plane,
const char *  str,
u16  x,
u16  y 
)

Draw text in specified plane.

Parameters:
planePlane where we want to draw text.
Accepted values are:
  • BG_A
  • BG_B
  • WINDOW
strString to draw.
xX position (in tile).
yy position (in tile).
See also:
VDP_clearText(..)
VDP_setTextPalette(..)
VDP_setTextPriority(..)
VDP_setTextPlane(..)
u16 VDP_getTextPalette ( )

Returns the palette number used to display text.

See also:
VDP_drawText(..)
VDP_clearText(..)
VDPPlane VDP_getTextPlane ( )

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(..)
u16 VDP_getTextPriority ( )

Returns the priority used to display text.

See also:
VDP_drawText(..)
VDP_clearText(..)
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:
planePlane we want to set the horizontal scroll.
Accepted values are:
  • BG_A
  • BG_B
valueH 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.
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:
planePlane we want to set the horizontal scroll.
Accepted values are:
  • BG_A
  • BG_B
lineFirst line we want to set the horizontal scroll.
valuesH scroll offsets.
Negative values will move the plane to the left while positive values will move it to the right.
lenNumber of line to set.
tmTransfer method.
Accepted values are:
  • CPU
  • DMA
  • DMA_QUEUE
  • DMA_QUEUE_COPY
See also:
VDP_setScrollingMode()
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:
planePlane we want to set the horizontal scroll.
Accepted values are:
  • BG_A
  • BG_B
tileFirst tile we want to set the horizontal scroll.
valuesH scroll offsets.
Negative values will move the plane to the left while positive values will move it to the right.
lenNumber of tile to set.
tmTransfer method.
Accepted values are:
  • CPU
  • DMA
  • DMA_QUEUE
  • DMA_QUEUE_COPY
See also:
VDP_setScrollingMode() function to change scroll mode.
void VDP_setTextPalette ( u16  palette)

Define the palette to use to display text.

Parameters:
palettePalette number.
See also:
VDP_drawText(..)
VDP_clearText(..)
void VDP_setTextPlane ( VDPPlane  plane)

Define the plane to use to display text.

Parameters:
planePlane where to display text.
Accepted values are:
  • BG_A
  • BG_B
  • WINDOW
See also:
VDP_drawText(..)
VDP_clearText(..)
void VDP_setTextPriority ( u16  prio)

Define the priority to use to display text.

Parameters:
prioPriority:
1 = HIGH PRIORITY TILE.
0 = LOW PRIORITY TILE.
See also:
VDP_drawText(..)
VDP_clearText(..)
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:
planePlane we want to set the vertical scroll.
Accepted values are:
  • BG_A
  • BG_B
valueV scroll offset.
Negative value will move the plane down while positive value will move it up.
See also:
VDP_setScrollingMode()
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:
planePlane we want to set the vertical scroll.
Accepted values are:
  • BG_A
  • BG_B
tileFirst tile we want to set the vertical scroll.
valuesV scroll offsets.
Negative values will move the plane down while positive values will move it up.
lenNumber of tile to set.
tmTransfer method.
Accepted values are:
  • CPU
  • DMA
  • DMA_QUEUE
  • DMA_QUEUE_COPY
See also:
VDP_setScrollingMode()

Variable Documentation

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

See also:
VDP_drawBitmap()
VDP_drawImage()
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines