GBDK 2020 Docs
4.1.1
API Documentation for GBDK 2020
|
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),(a)} |
#define | METASPR_TERM {metasprite_end} |
Typedefs | |
typedef struct metasprite_t | metasprite_t |
Functions | |
void | hide_sprites_range (UINT8 from, UINT8 to) OLDCALL PRESERVES_REGS(b |
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_vflip (const metasprite_t *metasprite, uint8_t base_tile, uint8_t base_sprite, uint8_t x, uint8_t y) |
uint8_t | move_metasprite_hflip (const metasprite_t *metasprite, uint8_t base_tile, uint8_t base_sprite, uint8_t x, uint8_t y) |
uint8_t | move_metasprite_hvflip (const metasprite_t *metasprite, uint8_t base_tile, 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 |
void | c |
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.
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.
When the move_metasprite_*() functions are called they update all properties for the affected sprites in the Shadow OAM. This means any existing property flags set for a sprite (CGB palette, BG/WIN priority, Tile VRAM Bank) will get overwritten.
How to use sprite property flags with metasprites:
-sp <props>
in the png2asset tool).The following functions are only available for Game Boy and related clone consoles due to lack of hardware support for sprite flipping in other consoles. See docs_consoles_supported_list
#define metasprite_end -128 |
#define METASPR_ITEM | ( | dy, | |
dx, | |||
dt, | |||
a | |||
) | {(dy),(dx),(dt),(a)} |
#define METASPR_TERM {metasprite_end} |
typedef struct metasprite_t metasprite_t |
Metasprite sub-item structure
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 |
props | (uint8_t) Property Flags |
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.
Hides all hardware sprites in range from <= X < to
from | start OAM index |
to | finish OAM index |
|
inline |
Moves metasprite to the absolute position x and y
metasprite | Pointer to the first struct of the metasprite (for the desired frame) |
base_tile | Number of the first tile where the metasprite's tiles start |
base_sprite | Number of the first hardware sprite to be used by the metasprite |
x | Absolute x coordinate of the sprite |
y | Absolute 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:
Note: Overwrites OAM sprite properties (such as CGB Palette), see Metasprites and sprite properties.
|
inline |
Moves metasprite to the absolute position x and y, flipped on the Y axis
metasprite | Pointer to the first struct of the metasprite (for the desired frame) |
base_tile | Number of the first tile where the metasprite's tiles start |
base_sprite | Number of the first hardware sprite to be used by the metasprite |
x | Absolute x coordinate of the sprite |
y | Absolute y coordinate of the sprite |
Same as move_metasprite(), but with the metasprite flipped on the Y axis only.
Sets:
Note: Overwrites OAM sprite properties (such as CGB palette), see Metasprites and sprite properties.
This function is only available on Game Boy and related clone consoles.
|
inline |
Moves metasprite to the absolute position x and y, flipped on the X axis
metasprite | Pointer to the first struct of the metasprite (for the desired frame) |
base_tile | Number of the first tile where the metasprite's tiles start |
base_sprite | Number of the first hardware sprite to be used by the metasprite |
x | Absolute x coordinate of the sprite |
y | Absolute y coordinate of the sprite |
Same as move_metasprite(), but with the metasprite flipped on the X axis only.
Sets:
Note: Overwrites OAM sprite properties (such as CGB palette), see Metasprites and sprite properties.
This function is only available on Game Boy and related clone consoles.
|
inline |
Moves metasprite to the absolute position x and y, flipped on the X and Y axis
metasprite | Pointer to the first struct of the metasprite (for the desired frame) |
base_tile | Number of the first tile where the metasprite's tiles start |
base_sprite | Number of the first hardware sprite to be used by the metasprite |
x | Absolute x coordinate of the sprite |
y | Absolute y coordinate of the sprite |
Same as move_metasprite(), but with the metasprite flipped on both the X and Y axis.
Sets:
Note: Overwrites OAM sprite properties (such as CGB palette), see Metasprites and sprite properties.
This function is only available on Game Boy and related clone consoles.
|
inline |
Hides a metasprite from the screen
metasprite | Pointer to first struct of the desired metasprite frame |
base_sprite | Number of hardware sprite to start with |
Sets:
const void* __current_metasprite |
uint8_t __current_base_tile |
uint8_t __render_shadow_OAM |
void c |