sgdk: vdp_bg.h File Reference

sgdk

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Classes | Functions | Variables
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_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 ()
| 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:

  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.

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

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

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_drawText(..)
  VDP_clearText(..)
  VDP_clearTextLine(..)

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_drawText(..)
  VDP_clearTextArea(..)
  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(..)

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

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

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:

  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.

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:

  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()

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:

  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()

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

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_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:

  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()

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()

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.

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()

void VDP_setTextPalette | ( | u16 | palette | ) |

Define the palette to use to display text.

Parameters:

  palette | Palette number.

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

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

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

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()

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()

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

u16 curTileInd

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