GBDK libraries documentation
PrevChapter 5. LibrariesNext

Graphics/Tile functions

GBDK graphic primitives allow the host to manage tiles, background, window, and sprites. Some of these primitives depend on the contents of the LCDC register, which specify the addresses in the VRAM at which graphics data are located. Therefore, the LCDC register must be set prior to using these primitives.

By default, the background and window TDT is located at addresses 0x8800-0x97FF, the sprite TDT at addresses 0x8000-0x8FFF, the BTM at addresses 0x9800-0x9BFF, and the WTM at addresses 0x9C00-0x9FFF. It is possible to modify these addresses (except the sprite TDT) using the LCDC register.

Functions

set_xxx_data / get_xxx_data

void
set_bkg_data(UBYTE first_tile,
             UBYTE nb_tiles,
             unsigned char *data);

void
set_win_data(UBYTE first_tile,
             UBYTE nb_tiles,
             unsigned char *data);

void
set_sprite_data(UBYTE first_tile,
                UBYTE nb_tiles,
                unsigned char *data);

void
set_data(unsigned char *vram_addr,
         unsigned char *data,
         UWORD len);

void
get_bkg_data(UBYTE first_tile,
             UBYTE nb_tiles,
             unsigned char *data);

void
get_win_data(UBYTE first_tile,
             UBYTE nb_tiles,
             unsigned char *data);

void
get_sprite_data(UBYTE first_tile,
                UBYTE nb_tiles,
                unsigned char *data);

void
get_data(unsigned char *data,
         unsigned char *vram_addr,
         UWORD len);
					 	

Description

The set_bkg_data(), set_win_data(), and set_sprite_data() functions copy tile data to the background, window, or sprite TDT in VRAM. The get_bkg_data(), get_win_data(), and get_sprite_data() functions copy data from VRAM to an address specified by the user. The address of data in VRAM depends of the contents of the LCDC register.

The set_data() function copies data to any address in VRAM. The get_data() function copies data from any address in VRAM.

The operations that read data can be used to save the current state of the screen (for instance for displaying a dialog box, and restoring the screen afterwards).

Paramenters

first_tile: number of the first tile in VRAM (between 0 and 255).

nb_tiles: number of tiles to copy (0 for copying 256 tiles).

data: pointer to the user tile data.

vram_addr: address in VRAM.

len: number of bytes to copy.

Returns

Nothing.

set_xxx_tiles / get_xxx_tiles

void
set_bkg_tiles(UBYTE x,
              UBYTE y,
              UBYTE w,
              UBYTE h,
              unsigned char *tiles);

void
set_win_tiles(UBYTE x,
              UBYTE y,
              UBYTE w,
              UBYTE h,
              unsigned char *tiles);

void
set_tiles(UBYTE x,
          UBYTE y,
          UBYTE w,
          UBYTE h,
          unsigned char *vram_addr,
          unsigned char *tiles);

set_sprite_tile(UBYTE nb,
                UBYTE tile);

void
get_bkg_tiles(UBYTE x,
              UBYTE y,
              UBYTE w,
              UBYTE h,
              unsigned char *tiles);

void
get_win_tiles(UBYTE x,
              UBYTE y,
              UBYTE w,
              UBYTE h,
              unsigned char *tiles);

void
get_tiles(UBYTE x,
          UBYTE y,
          UBYTE w,
          UBYTE h,
          unsigned char *tiles,
          unsigned char *vram_addr);

UBYTE get_sprite_tile(UBYTE nb);
						

Description

The set_bkg_tiles() and set_win_tiles() functions copy a rectangular area of background or window tile numbers to the BTM in VRAM. The get_bkg_tiles() and get_win_tiles() functions copy data from VRAM to an address specified by the user. The address of tile numbers in VRAM depends of the contents of the LCDC register.

The set_tiles() function copies a rectangular area of tile numbers to any address in VRAM (this address will be generally 0x8000 or 0x8800). The get_tiles() function copies data from VRAM to an address specified by the user.

The set_sprite_tiles() function set the tile number of a specific sprite. The get_sprite_tiles() function returns the tile number of a sprite. These functions do not directly access the VRAM.

The operations that read data can be used to save the current state of the screen (for instance for displaying a dialog box, and restoring the screen afterwards).

Parameters

x: horizontal coordinate of the top-left corner of the rectangular area in VRAM.

y: vertical coordinate of the top-left corner of the rectangular area in VRAM.

w: width of the the rectangular area in VRAM.

h: height of the the rectangular area in VRAM.

tiles: pointer to the user tile numbers. The size of the tile numbers should be w*h.

vram_addr: address in VRAM.

nb: index of the sprite to access (between 0 and 39).

tile: tile number of the sprite.

Returns

The get_sprite_tiles() function returns the tile number of the sprite.

move_xxx

void
move_bkg(UBYTE x,
         UBYTE y);

void
move_win(UBYTE x,
         UBYTE y);

void
move_sprite(UBYTE nb,
            UBYTE x,
            UBYTE y);
						

Description

The move_bkg() and move_win() functions modify the position of the background or window display. These functions expect the absolute value of the new position. Note that these functions should preferably not be used during screen redraw. To avoid unwanted visual distortions, it is better to call these functions upon VBL.

The move_sprite() function modifies the position of a specific sprite. This function expects the absolute value of the new position. It does not directly access the VRAM.

Parameters

x: horizontal coordinate of the new display position. y: vertical coordinate of the new display position. nb: index of the sprite to access (between 0 and 39).

Returns

Nothing.

scroll_xxx

void
scroll_bkg(BYTE x,
           BYTE y);

void
scroll_win(BYTE x,
           BYTE y);

void
scroll_sprite(UBYTE nb,
              BYTE x,
              BYTE y);
						

Description

The scroll_bkg() and scroll_win() functions modify the position of the background or window display. These functions expect a relative displacement relative to the current position. Note that these functions should preferably not be used during screen redraw. To avoid unwanted visual distortions, it is better to call these functions upon VBL. The scroll_sprite() function modifies the position of a specific sprite. This function expects a relative displacement relative to the current position. It does not directly access the VRAM.

Parameters

x: horizontal displacement relative to the current display position.

y: vertical displacement relative to the current display position.

nb: index of the sprite to access (between 0 and 39).

Returns

Nothing.

set_sprite_prop / get_sprite_prop

/* Sprite properties bits */

#define S_PALETTE    0x10U
#define S_FLIPX      0x20U
#define S_FLIPY      0x40U
#define S_PRIORITY   0x80U

void
set_sprite_prop(UBYTE nb,
                UBYTE prop);

UBYTE
get_sprite_prop(UBYTE nb);
						

Description

The set_sprite_prop() function modifies the attributed of a specific sprite. The get_sprite_prop() function returns the attributed of a sprite. These functions do not directly access the VRAM.

Paramters

nb: index of the sprite to access (between 0 and 39).

prop: new value of the sprite attributes.

Returns

The get_sprite_prop() returns the attributes of the sprite.


PrevHomeNext
Full screen graphics - drawing.hUpJoypad - gb.h