metasprites.h File Reference

#include <gb/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),(a)}
#define	METASPR_TERM   {metasprite_end}

Typedefs
typedef struct metasprite_t	metasprite_t

Functions
void	hide_sprites_range (uint8_t from, uint8_t to)
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_vflip (const metasprite_t *metasprite, uint8_t base_tile, 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_hflip (const metasprite_t *metasprite, uint8_t base_tile, 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)
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	__current_base_prop
uint8_t	__render_shadow_OAM

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.

// Example:
// Hide rest of the hardware sprites, because amount
// of sprites differ between animation frames.
// (where hiwater == last hardware sprite used + 1)
hide_sprites_range(hiwater, MAX_HARDWARE_SPRITES);

Metasprites and sprite properties (including cgb palette)

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:

• Primary method: Use the base_prop parameter for the move_metasprite_*() functions.
  • For more details about the properties on the Game Boy see: https://gbdev.io/pandocs/OAM.html#byte-3–attributesflags
  • This can be left at zero for defaults
  • Various OAMF_* flags can be used depending on the platform:
    • OAMF_BANK0, OAMF_BANK1
    • OAMF_CGB_PAL0, OAMF_CGB_PAL1, OAMF_CGB_PAL2, OAMF_CGB_PAL3, OAMF_CGB_PAL4, OAMF_CGB_PAL5, OAMF_CGB_PAL6, OAMF_CGB_PAL7,
    • OAMF_PAL0, OAMF_PAL1,
    • OAMF_PALMASK, OAMF_PRI, OAMF_XFLIP, OAMF_YFLIP
• Alternate method: The metasprite structures can have the property flags modified before compilation (such as with -sp <props> in the png2asset tool).

The following functions only support hardware sprite flipping on the Game Boy / Mega Duck and NES. For other consoles which do not have hardware sprite flipping see the cross-platform metasprite example for a workaround (with some performance penalty).

• move_metasprite_flipx()
• move_metasprite_flipy()
• move_metasprite_flipxy()

To test for hardware support see HARDWARE_SPRITE_CAN_FLIP_X and HARDWARE_SPRITE_CAN_FLIP_Y. Also see docs_consoles_supported_list for a brief summary of console capabilities.

Macro Definition Documentation

metasprite_end

#define metasprite_end   -128

METASPR_ITEM

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

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

Function Documentation

hide_sprites_range()

void hide_sprites_range	(	uint8_t	from,
		uint8_t	to
	)

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

Parameters

from	start OAM index
to	finish OAM index (must be <= MAX_HARDWARE_SPRITES)

See also

hide_sprite, MAX_HARDWARE_SPRITES

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

Parameters

from	start OAM index
to	finish 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

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_prop	Base sprite property flags (can be used to set palette, etc)
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:

• __current_metasprite = metasprite;
• __current_base_tile = base_tile;

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

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

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_prop	Base sprite property flags (can be used to set palette, etc)
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 by X (horizontally).

Sets:

• __current_metasprite = metasprite;
• __current_base_tile = base_tile;

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.

Returns

Number of hardware sprites used to draw this metasprite

See also

move_metasprite()

move_metasprite_vflip()

uint8_t move_metasprite_vflip ( 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_flipx()

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

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_prop	Base sprite property flags (can be used to set palette, etc)
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 by Y (vertically).

Sets:

• __current_metasprite = metasprite;
• __current_base_tile = base_tile;

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.

Returns

Number of hardware sprites used to draw this metasprite

See also

move_metasprite()

move_metasprite_hflip()

uint8_t move_metasprite_hflip ( 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_flipy()

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

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_prop	Base sprite property flags (can be used to set palette, etc)
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 by X and Y (horizontally and vertically).

Sets:

• __current_metasprite = metasprite;
• __current_base_tile = base_tile;

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.

Returns

Number of hardware sprites used to draw this metasprite

See also

move_metasprite()

move_metasprite_hvflip()

uint8_t move_metasprite_hvflip ( 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_flipxy()

hide_metasprite()

void hide_metasprite ( const metasprite_t *  metasprite, uint8_t  base_sprite  )

inline

Hides a metasprite from the screen

Parameters

metasprite	Pointer to first struct of the desired metasprite frame
base_sprite	Number 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

__current_base_prop

uint8_t __current_base_prop

extern

__render_shadow_OAM

uint8_t __render_shadow_OAM

extern