GBDK 2020 Docs  4.1.1
API Documentation for GBDK 2020
metasprites.h File Reference
#include <sms/hardware.h>
#include <types.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures

struct  metasprite_t
 

Macros

#define metasprite_end   -128
 
#define METASPR_ITEM(dy, dx, dt, a)   {(dy),(dx),(dt)}
 
#define METASPR_TERM   {metasprite_end}
 

Typedefs

typedef struct metasprite_t metasprite_t
 

Functions

void hide_sprites_range (UINT8 from, UINT8 to) Z88DK_CALLEE PRESERVES_REGS(iyh
 
uint8_t move_metasprite_ex (const metasprite_t *metasprite, uint8_t base_tile, uint8_t base_prop, uint8_t base_sprite, uint8_t x, uint8_t y)
 
uint8_t move_metasprite (const metasprite_t *metasprite, uint8_t base_tile, uint8_t base_sprite, uint8_t x, uint8_t y)
 
uint8_t move_metasprite_flipx (const metasprite_t *metasprite, uint8_t base_tile, uint8_t base_prop, uint8_t base_sprite, uint8_t x, uint8_t y)
 
uint8_t move_metasprite_flipy (const metasprite_t *metasprite, uint8_t base_tile, uint8_t base_prop, uint8_t base_sprite, uint8_t x, uint8_t y)
 
uint8_t move_metasprite_flipxy (const metasprite_t *metasprite, uint8_t base_tile, uint8_t base_prop, uint8_t base_sprite, uint8_t x, uint8_t y)
 
void hide_metasprite (const metasprite_t *metasprite, uint8_t base_sprite)
 

Variables

const void * __current_metasprite
 
uint8_t __current_base_tile
 
uint8_t __render_shadow_OAM
 
static uint8_t iyl
 

Detailed Description

Metasprite support

A metasprite is a larger sprite made up from a collection of smaller individual hardware sprites. Different frames of the same metasprites can share tile data.

The api supports metasprites in both SPRITES_8x8 and SPRITES_8x16 mode. If 8x16 mode is used then the height of the metasprite must be a multiple of 16.

The origin (pivot) for the metasprite is not required to be in the upper left-hand corner as with regular hardware sprites.

Use the utility_png2asset tool to convert single or multiple frames of graphics into metasprite structured data for use with the ...metasprite...() functions.

Metasprites composed of variable numbers of sprites

When using png2asset, it's common for the output of different frames to be composed of different numbers of hardware sprites (since it's trying to create each frame as efficiently as possible). Due to that, it's good practice to clear out (hide) unused sprites in the shadow_OAM that have been set by previous frames.

Metasprite support

A metasprite is a larger sprite made up from a collection of smaller individual hardware sprites. Different frames of the same metasprites can share tile data.

The api supports metasprites in both SPRITES_8x8 and SPRITES_8x16 mode. If 8x16 mode is used then the height of the metasprite must be a multiple of 16.

The origin (pivot) for the metasprite is not required to be in the upper left-hand corner as with regular hardware sprites.

Use the utility_png2asset tool to convert single or multiple frames of graphics into metasprite structured data for use with the ...metasprite...() functions.

Metasprites composed of variable numbers of sprites

When using png2asset, it's common for the output of different frames to be composed of different numbers of hardware sprites (since it's trying to create each frame as efficiently as possible). Due to that, it's good practice to clear out (hide) unused sprites in the shadow_OAM that have been set by previous frames.

Macro Definition Documentation

◆ metasprite_end

#define metasprite_end   -128

◆ METASPR_ITEM

#define METASPR_ITEM (   dy,
  dx,
  dt,
 
)    {(dy),(dx),(dt)}

◆ METASPR_TERM

#define METASPR_TERM   {metasprite_end}

Typedef Documentation

◆ metasprite_t

typedef struct metasprite_t metasprite_t

Metasprite sub-item structure

Parameters
dy(int8_t) Y coordinate of the sprite relative to the metasprite origin (pivot)
dx(int8_t) X coordinate of the sprite relative to the metasprite origin (pivot)
dtile(uint8_t) Start tile relative to the metasprites own set of tiles

Metasprites are built from multiple metasprite_t items (one for each sub-sprite) and a pool of tiles they reference. If a metasprite has multiple frames then each frame will be built from some number of metasprite_t items (which may vary based on how many sprites are required for that particular frame).

A metasprite frame is terminated with a {metasprite_end} entry.

Function Documentation

◆ hide_sprites_range()

void hide_sprites_range ( UINT8  from,
UINT8  to 
)

Hides all hardware sprites in range from <= X < to

Parameters
fromstart OAM index
tofinish OAM index

◆ move_metasprite_ex()

uint8_t move_metasprite_ex ( const metasprite_t metasprite,
uint8_t  base_tile,
uint8_t  base_prop,
uint8_t  base_sprite,
uint8_t  x,
uint8_t  y 
)
inline

Moves metasprite to the absolute position x and y

Parameters
metaspritePointer to the first struct of the metasprite (for the desired frame)
base_tileNumber of the first tile where the metasprite's tiles start
base_propBase sprite property flags (unused on this platform)
base_spriteNumber of the first hardware sprite to be used by the metasprite
xAbsolute x coordinate of the sprite
yAbsolute y coordinate of the sprite

Moves metasprite to the absolute position x and y (with no flip on the X or Y axis). Hardware sprites are allocated starting from base_sprite, using tiles starting from base_tile.

Sets:

  • __current_metasprite = metasprite;
  • __current_base_tile = base_tile;
Returns
Number of hardware sprites used to draw this metasprite

◆ move_metasprite()

uint8_t move_metasprite ( const metasprite_t metasprite,
uint8_t  base_tile,
uint8_t  base_sprite,
uint8_t  x,
uint8_t  y 
)
inline

Obsolete. This function has been replaced by move_metasprite_ex()

◆ move_metasprite_flipx()

uint8_t move_metasprite_flipx ( const metasprite_t metasprite,
uint8_t  base_tile,
uint8_t  base_prop,
uint8_t  base_sprite,
uint8_t  x,
uint8_t  y 
)
inline

Moves metasprite to the absolute position x and y, flipped by X (horizontally)

Parameters
metaspritePointer to the first struct of the metasprite (for the desired frame)
base_tileNumber of the first tile where the metasprite's tiles start
base_propBase sprite property flags (unused on this platform)
base_spriteNumber of the first hardware sprite to be used by the metasprite
xAbsolute x coordinate of the sprite
yAbsolute y coordinate of the sprite

Same as move_metasprite(), but with the metasprite flipped by X (horizontally).

Sets:

  • __current_metasprite = metasprite;
  • __current_base_tile = base_tile;

Note: Overwrites OAM sprite properties (such as palette), see Metasprites and sprite properties.

Returns
Number of hardware sprites used to draw this metasprite
See also
move_metasprite()

◆ move_metasprite_flipy()

uint8_t move_metasprite_flipy ( const metasprite_t metasprite,
uint8_t  base_tile,
uint8_t  base_prop,
uint8_t  base_sprite,
uint8_t  x,
uint8_t  y 
)
inline

Moves metasprite to the absolute position x and y, flipped by Y (vertically)

Parameters
metaspritePointer to the first struct of the metasprite (for the desired frame)
base_tileNumber of the first tile where the metasprite's tiles start
base_propBase sprite property flags (unused on this platform)
base_spriteNumber of the first hardware sprite to be used by the metasprite
xAbsolute x coordinate of the sprite
yAbsolute y coordinate of the sprite

Same as move_metasprite(), but with the metasprite flipped by Y (vertically).

Sets:

  • __current_metasprite = metasprite;
  • __current_base_tile = base_tile;

Note: Overwrites OAM sprite properties (such as palette), see Metasprites and sprite properties.

Returns
Number of hardware sprites used to draw this metasprite
See also
move_metasprite()

◆ move_metasprite_flipxy()

uint8_t move_metasprite_flipxy ( const metasprite_t metasprite,
uint8_t  base_tile,
uint8_t  base_prop,
uint8_t  base_sprite,
uint8_t  x,
uint8_t  y 
)
inline

Moves metasprite to the absolute position x and y, flipped by X and Y (horizontally and vertically)

Parameters
metaspritePointer to the first struct of the metasprite (for the desired frame)
base_tileNumber of the first tile where the metasprite's tiles start
base_propBase sprite property flags (unused on this platform)
base_spriteNumber of the first hardware sprite to be used by the metasprite
xAbsolute x coordinate of the sprite
yAbsolute y coordinate of the sprite

Same as move_metasprite(), but with the metasprite flipped by X and Y (horizontally and vertically).

Sets:

  • __current_metasprite = metasprite;
  • __current_base_tile = base_tile;

Note: Overwrites OAM sprite properties (such as palette), see Metasprites and sprite properties.

Returns
Number of hardware sprites used to draw this metasprite
See also
move_metasprite()

◆ hide_metasprite()

void hide_metasprite ( const metasprite_t metasprite,
uint8_t  base_sprite 
)
inline

Hides a metasprite from the screen

Parameters
metaspritePointer to first struct of the desired metasprite frame
base_spriteNumber of hardware sprite to start with

Sets:

  • __current_metasprite = metasprite;

Variable Documentation

◆ __current_metasprite

const void* __current_metasprite
extern

◆ __current_base_tile

uint8_t __current_base_tile
extern

◆ __render_shadow_OAM

uint8_t __render_shadow_OAM
extern

◆ iyl

void iyl