Sprite engine. More...

#include "vdp_tile.h"
#include "vdp_spr.h"
#include "pal.h"

Classes
struct	BoxCollision
	Simple Box structure for collision. More...
struct	CircleCollision
	Simple Circle structure (can be used for collision detection) More...
struct	_collision
struct	FrameVDPSprite
	Single VDP sprite info structure for sprite animation frame. More...
struct	AnimationFrame
	Sprite animation frame structure. More...
struct	Animation
	Sprite animation structure. More...
struct	SpriteDefinition
	Sprite definition structure. More...
struct	Sprite
	Sprite structure used by the Sprite Engine to store state for a sprite. WARNING: always use the SPR_addSprite(..) method to allocate Sprite object. More...
Defines
#define	COLLISION_TYPE_NONE 0
	No collision type.
#define	COLLISION_TYPE_BOX 1
	Bouding box collision type (Box structure)
#define	COLLISION_TYPE_CIRCLE 2
	Round circle collision type (Circle structure)
#define	SPR_FLAG_INSERT_HEAD 0x4000
	Special flag to indicate that we want to add the sprite at position 0 (head) in the list instead of adding it in last position (default)
#define	SPR_FLAG_DISABLE_DELAYED_FRAME_UPDATE 0x2000
	Disable delaying of frame update when we are running out of DMA capacity. By default we delay the frame update when DMA is already full so the frame update happen as soon we have enough DMA capacity to do it. This flag forces frame update to always happen immediately but that may cause graphical glitches.
#define	SPR_FLAG_AUTO_VRAM_ALLOC 0x1000
	Enable automatic VRAM allocation.
#define	SPR_FLAG_AUTO_SPRITE_ALLOC 0x0800
	Enable automatic hardware sprite allocation.
#define	SPR_FLAG_AUTO_TILE_UPLOAD 0x0400
	Enable automatic upload of sprite tiles data into VRAM.
#define	SPR_FLAG_AUTO_VISIBILITY 0x0200
	Enable automatic visibility calculation.
#define	SPR_FLAG_FAST_AUTO_VISIBILITY 0x0100
	Enable fast visibility calculation (only meaningful if SPR_FLAG_AUTO_VISIBILITY is used). If you set this flag the automatic visibility calculation will be done globally for the (meta) sprite and not per internal hardware sprite. This result in faster visibility computation at the expense of some waste of hardware sprite.
#define	SPR_FLAG_MASK (SPR_FLAG_INSERT_HEAD \| SPR_FLAG_DISABLE_DELAYED_FRAME_UPDATE \| SPR_FLAG_AUTO_VRAM_ALLOC \| SPR_FLAG_AUTO_SPRITE_ALLOC \| SPR_FLAG_AUTO_TILE_UPLOAD \| SPR_FLAG_AUTO_VISIBILITY \| SPR_FLAG_FAST_AUTO_VISIBILITY)
	Mask for sprite flag.
#define	SPR_MIN_DEPTH (-0x8000)
	Minimum depth for a sprite (always above others sprites)
#define	SPR_MAX_DEPTH 0x7FFF
	Maximum depth for a sprite (always below others sprites)
Typedefs
typedef struct _collision	Collision
typedef struct Sprite	Sprite
	Sprite structure used by the Sprite Engine to store state for a sprite. WARNING: always use the SPR_addSprite(..) method to allocate Sprite object.
typedef void	FrameChangeCallback (Sprite *sprite)
	Sprite frame change event callback.
Enumerations
enum	SpriteVisibility { VISIBLE, HIDDEN, AUTO_FAST, AUTO_SLOW }
	Sprite visibility enumeration. More...
Functions
void	SPR_init ()
	Initialize the Sprite engine with default parameters.
void	SPR_initEx (u16 vramSize)
	Init the Sprite engine with specified advanced parameters (VRAM allocation size and decompression buffer size).
void	SPR_end ()
	End the Sprite engine.
bool	SPR_isInitialized ()
	FALSE if sprite cache engine is not initialized, TRUE otherwise.
void	SPR_reset ()
	Reset the Sprite engine.
Sprite *	SPR_addSpriteEx (const SpriteDefinition *spriteDef, s16 x, s16 y, u16 attribut, u16 spriteIndex, u16 flag)
	Adds a new sprite with specified parameters and returns it.
Sprite *	SPR_addSprite (const SpriteDefinition *spriteDef, s16 x, s16 y, u16 attribut)
	Adds a new sprite with auto resource allocation enabled and returns it.
Sprite *	SPR_addSpriteExSafe (const SpriteDefinition *spriteDef, s16 x, s16 y, u16 attribut, u16 spriteIndex, u16 flag)
	Adds a new sprite with specified parameters and returns it.
Sprite *	SPR_addSpriteSafe (const SpriteDefinition *spriteDef, s16 x, s16 y, u16 attribut)
	Adds a new sprite with auto resource allocation enabled and returns it.
void	SPR_releaseSprite (Sprite *sprite)
	Release the specified sprite (no more visible and release its resources).
u16	SPR_getNumActiveSprite ()
	Returns the number of active sprite (number of sprite added with SPR_addSprite(..) or SPR_addSpriteEx(..) methods).
void	SPR_defragVRAM ()
	Defragment allocated VRAM for sprites, that can help when sprite allocation fail (SPR_addSprite(..) or SPR_addSpriteEx(..) return NULL).
u16 **	SPR_loadAllFrames (const SpriteDefinition sprDef, u16 index, u16 totalNumTile)
	Load all frames of SpriteDefinition (using DMA) at specified VRAM tile index and return the indexes table. WARNING: This function should be call at init/loading time as it can be quite long (several frames)
bool	SPR_setDefinition (Sprite sprite, const SpriteDefinition spriteDef)
	Set the Sprite Definition.
s16	SPR_getPositionX (Sprite *sprite)
	Get sprite position X.
s16	SPR_getPositionY (Sprite *sprite)
	Get sprite position Y.
void	SPR_setPosition (Sprite *sprite, s16 x, s16 y)
	Set sprite position.
void	SPR_setHFlip (Sprite *sprite, u16 value)
	Set sprite Horizontal Flip attribut.
void	SPR_setVFlip (Sprite *sprite, u16 value)
	Set sprite Vertical Flip attribut.
void	SPR_setPalette (Sprite *sprite, u16 value)
	Set sprite Palette index to use.
void	SPR_setPriority (Sprite *sprite, u16 value)
	Set sprite Priority attribut.
void	SPR_setPriorityAttribut (Sprite *sprite, u16 value)
void	SPR_setDepth (Sprite *sprite, s16 value)
	Set sprite depth (for sprite display ordering)
void	SPR_setZ (Sprite *sprite, s16 value)
	Same as SPR_setDepth(..)
void	SPR_setAlwaysOnTop (Sprite *sprite, u16 value)
void	SPR_setAnimAndFrame (Sprite *sprite, s16 anim, s16 frame)
	Set current sprite animation and frame.
void	SPR_setAnim (Sprite *sprite, s16 anim)
	Set current sprite animation.
void	SPR_setFrame (Sprite *sprite, s16 frame)
	Set current sprite frame.
void	SPR_nextFrame (Sprite *sprite)
	Pass to the next sprite frame.
bool	SPR_setVRAMTileIndex (Sprite *sprite, s16 value)
	Set the VRAM tile position reserved for this sprite.
bool	SPR_setSpriteTableIndex (Sprite *sprite, s16 value)
	Set the VDP sprite index to use for this sprite.
void	SPR_setAutoTileUpload (Sprite *sprite, bool value)
	Enable/disable the automatic upload of sprite tiles data into VRAM.
void	SPR_setDelayedFrameUpdate (Sprite *sprite, bool value)
	Enable/disable the delayed frame update.
void	SPR_setFrameChangeCallback (Sprite sprite, FrameChangeCallback callback)
	Set the frame change event callback for this sprite.
SpriteVisibility	SPR_getVisibility (Sprite *sprite)
	Return the visibility state for this sprite. WARNING: this is different from SPR_isVisible(..) method, possible value are: SpriteVisibility.VISIBLE = sprite is visible SpriteVisibility.HIDDEN = sprite is not visible SpriteVisibility.AUTO_FAST = visibility is automatically computed - global visibility (only using sprite X position) SpriteVisibility.AUTO_SLOW = visibility is automatically computed - per hardware sprite visibility (only using sprite X position)
bool	SPR_isVisible (Sprite *sprite, bool recompute)
	Return the visible state for this sprite (meaningful only if AUTO visibility is enabled, see SPR_setVisibility(..) method).
void	SPR_setVisibility (Sprite *sprite, SpriteVisibility value)
	Set the visibility state for this sprite.
void	SPR_setAlwaysVisible (Sprite *sprite, u16 value)
void	SPR_setNeverVisible (Sprite *sprite, u16 value)
bool	SPR_computeVisibility (Sprite *sprite)
void	SPR_clear ()
	Clear all displayed sprites.
void	SPR_update ()
	Update and display the active list of sprite.
void	SPR_logProfil ()
	Log the profil informations (when enabled) in the KMod message window.
void	SPR_logSprites ()
	Log the sprites informations (when enabled) in the KMod message window.
Variables
Sprite *	spritesBank
Sprite *	firstSprite
Sprite *	lastSprite
u16	spriteVramSize

Detailed Description

Sprite engine.

Author:: Stephane Dallongeville

Date:: 10/2013

Sprite engine providing advanced sprites manipulation and operations.
This unit use both the vram memory manager (see vram.h file for more info)
and the Sega Genesis VDP sprite capabilities (see vdp_spr.h file for more info).

Typedef Documentation

typedef void FrameChangeCallback(Sprite *sprite)

Sprite frame change event callback.

Parameters:

sprite The sprite for which frame just changed.

This event occurs onframe change process during SPR_update() call (CAUTION: sprite->status field is not up to date at this point).
It let opportunity to the developer to apply special behavior or process when sprite frame just changed:
for instance we can disable animation looping by setting sprite->timer to 0 when we meet the last animation frame.

typedef struct Sprite Sprite

Sprite structure used by the Sprite Engine to store state for a sprite.
WARNING: always use the SPR_addSprite(..) method to allocate Sprite object.

Parameters:

status	Internal state and automatic allocation information (internal)
visibility	visibility information of current frame for each VDP sprite (max = 16)
spriteDef	Sprite definition pointer
onFrameChange	Custom callback on frame change event (see SPR_setFrameChangeCallback(..) method)
animation	Animation pointer cache (internal)
frame	AnimationFrame pointer cache (internal)
animInd	current animation index (internal)
frameInd	current frame animation index (internal)
timer	timer for current frame (internal)
x	current sprite X position on screen offseted by 0x80 (internal VDP position)
y	current sprite Y position on screen offseted by 0x80 (internal VDP position)
depth	current sprite depth (Z) position used for Z sorting
attribut	sprite specific attribut and allocated VRAM tile index (see TILE_ATTR_FULL() macro)
VDPSpriteIndex	index of first allocated VDP sprite (0 when no yet allocated) Number of allocated VDP sprite is defined by definition->maxNumSprite
lastVDPSprite	Pointer to last VDP sprite used by this Sprite (used internally to update link between sprite)
lastNumSprite	the number of VDP sprite used by the current frame (internal)
spriteToHide	internal
data	this is a free field for user data, use it for whatever you want (flags, pointer...)
prev	pointer on previous Sprite in list
next	pointer on next Sprite in list

Used to manage an active sprite in game condition.

Enumeration Type Documentation

enum SpriteVisibility

Sprite visibility enumeration.

Enumerator:

VISIBLE	Sprite is visible (no computation needed)
HIDDEN	Sprite is hidden (no computation needed)
AUTO_FAST	Automatic visibility calculation - FAST (computation made on global meta sprite)
AUTO_SLOW	Automatic visibility calculation - SLOW (computation made per hardware sprite)

Function Documentation

Sprite* SPR_addSprite	(	const SpriteDefinition *	spriteDef,
		s16	x,
		s16	y,
		u16	attribut
	)

Adds a new sprite with auto resource allocation enabled and returns it.

Parameters:

spriteDef	the SpriteDefinition data to assign to this sprite.
x	default X position.
y	default Y position.
attribut	sprite attribut (see TILE_ATTR() macro).

Returns:: the new sprite or NULL if the operation failed (some logs can be generated in the KMod console in this case)

By default the sprite uses automatic resources allocation (VRAM and hardware sprite) and visibility is set to ON.
You can change these defaults settings later by calling SPR_setVRAMTileIndex(..), SPR_setSpriteTableIndex(..), SPR_setAutoTileUpload(..) and SPR_setVisibility(..) methods.
You can release all sprite resources by using SPR_releaseSprite(..) or SPR_reset(..).
IMPORTANT NOTE: sprite allocation can fail (return NULL) because of automatic VRAM allocation even if there is enough VRAM available, this can happen because of the VRAM fragmentation.
You can use SPR_addSpriteSafe(..) method instead so it take care about VRAM fragmentation.

See also:: SPR_addSpriteEx(..); SPR_addSpriteSafe(..); SPR_releaseSprite(..)

Sprite* SPR_addSpriteEx	(	const SpriteDefinition *	spriteDef,
		s16	x,
		s16	y,
		u16	attribut,
		u16	spriteIndex,
		u16	flag
	)

Adds a new sprite with specified parameters and returns it.

Parameters:

spriteDef	the SpriteDefinition data to assign to this sprite.
x	default X position.
y	default Y position.
attribut	sprite attribut (see TILE_ATTR() macro).
spriteIndex	index of the first sprite in the VDP sprite table used to display this Sprite (should be in [1..79] range. IMPORTANT: this value is used only if you use manual VDP Sprite allocation (see the flags parameter).
flag	specific settings for this sprite: SPR_FLAG_DISABLE_DELAYED_FRAME_UPDATE = Disable delaying of frame update when we are running out of DMA capacity. If you set this flag then sprite frame update always happen immediately but may lead to some graphical glitches (tiles data and sprite table data not synchronized). You can use SPR_setDelayedFrameUpdate(..) method to change this setting. SPR_FLAG_AUTO_VISIBILITY = Enable automatic sprite visibility calculation (you can also use SPR_setVisibility(..) method). SPR_FLAG_FAST_AUTO_VISIBILITY = Enable fast computation for the automatic visibility calculation (disabled by default) If you set this flag the automatic visibility calculation will be done globally for the (meta) sprite and not per internal hardware sprite. This result in faster visibility computation at the expense of some waste of hardware sprite. You can set the automatic visibility computation by using SPR_setVisibility(..) method. SPR_FLAG_AUTO_VRAM_ALLOC = Enable automatic VRAM allocation (enabled by default) If you don't set this flag you will have to manually define VRAM tile index position for this sprite with the attribut parameter or by using the SPR_setVRAMTileIndex(..) method SPR_FLAG_AUTO_SPRITE_ALLOC = Enable automatic hardware/VDP sprite allocation (enabled by default) If you don't set this flag you will have to manually define the hardware sprite table index to reserve with the spriteIndex parameter or by using the SPR_setSpriteTableIndex(..) method SPR_FLAG_AUTO_TILE_UPLOAD = Enable automatic upload of sprite tiles data into VRAM (enabled by default) If you don't set this flag you will have to manually upload tiles data of sprite into the VRAM (you can change this setting using SPR_setAutoTileUpload(..) method). SPR_FLAG_INSERT_HEAD = Allow to insert the sprite at the start/head of the list. When you use this flag the sprite will be inserted at the head of the list making it top most (equivalent to SPR_setDepth(SPR_MIN_DEPTH)) while default insertion position is at the end of the list (equivalent to SPR_setDepth(SPR_MAX_DEPTH)) It's recommended to use the following default settings: SPR_FLAG_AUTO_VISIBILITY \| SPR_FLAG_AUTO_VRAM_ALLOC \| SPR_FLAG_AUTO_SPRITE_ALLOC \| SPR_FLAG_AUTO_TILE_UPLOAD

Returns:: the new sprite or NULL if the operation failed (some logs can be generated in the KMod console in this case)

By default the sprite uses the provided flag setting for automatic resources allocation and sprite visibility computation.
If auto visibility is not enabled then sprite is considered as not visible by default (see SPR_setVisibility(..) method).
You can release all sprite resources by using SPR_releaseSprite(..) or SPR_reset(..).
IMPORTANT NOTE: sprite allocation can fail (return NULL) when you are using auto VRAM allocation (SPR_FLAG_AUTO_VRAM_ALLOC) even if there is enough VRAM available,
this can happen because of the VRAM fragmentation. You can use SPR_addSpriteExSafe(..) method instead so it take care about VRAM fragmentation.

See also:: SPR_addSprite(..); SPR_addSpriteExSafe(..); SPR_releaseSprite(..)

Sprite* SPR_addSpriteExSafe	(	const SpriteDefinition *	spriteDef,
		s16	x,
		s16	y,
		u16	attribut,
		u16	spriteIndex,
		u16	flag
	)

Adds a new sprite with specified parameters and returns it.

Parameters:

spriteDef	the SpriteDefinition data to assign to this sprite.
x	default X position.
y	default Y position.
attribut	sprite attribut (see TILE_ATTR() macro).
spriteIndex	index of the first sprite in the VDP sprite table used to display this Sprite (should be > 0 and < 128). IMPORTANT: this value is used only if you use manual VDP Sprite allocation (see the flag parameter).
flag	specific settings for this sprite: SPR_FLAG_DISABLE_DELAYED_FRAME_UPDATE = Disable delaying of frame update when we are running out of DMA capacity. If you set this flag then sprite frame update always happen immediately but may lead to some graphical glitches (tiles data and sprite table data not synchronized). You can use SPR_setDelayedFrameUpdate(..) method to change this setting. SPR_FLAG_AUTO_VISIBILITY = Enable automatic sprite visibility calculation (you can also use SPR_setVisibility(..) method). SPR_FLAG_FAST_AUTO_VISIBILITY = Enable fast computation for the automatic visibility calculation (disabled by default) If you set this flag the automatic visibility calculation will be done globally for the (meta) sprite and not per internal hardware sprite. This result in faster visibility computation at the expense of some waste of hardware sprite (scanline limit). You can set the automatic visibility computation by using SPR_setVisibility(..) method. SPR_FLAG_AUTO_VRAM_ALLOC = Enable automatic VRAM allocation (enabled by default) If you don't set this flag you will have to manually define VRAM tile index position for this sprite with the attribut parameter or by using the SPR_setVRAMTileIndex(..) method SPR_FLAG_AUTO_SPRITE_ALLOC = Enable automatic hardware/VDP sprite allocation (enabled by default) If you don't set this flag you will have to manually define the hardware sprite table index to reserve with the spriteIndex parameter or by using the SPR_setSpriteTableIndex(..) method SPR_FLAG_AUTO_TILE_UPLOAD = Enable automatic upload of sprite tiles data into VRAM (enabled by default) If you don't set this flag you will have to manually upload tiles data of sprite into the VRAM (you can change this setting using SPR_setAutoTileUpload(..) method). SPR_FLAG_INSERT_HEAD = Allow to insert the sprite at the start/head of the list. When you use this flag the sprite will be inserted at the head of the list making it top most (equivalent to SPR_setDepth(SPR_MIN_DEPTH)) while default insertion position is at the end of the list (equivalent to SPR_setDepth(SPR_MAX_DEPTH)) It's recommended to use the following default settings: SPR_FLAG_AUTO_VISIBILITY \| SPR_FLAG_AUTO_VRAM_ALLOC \| SPR_FLAG_AUTO_SPRITE_ALLOC \| SPR_FLAG_AUTO_TILE_UPLOAD

Returns:: the new sprite or NULL if the operation failed (some logs can be generated in the KMod console in this case)

By default the sprite uses the provided flag setting for automatic resources allocation and sprite visibility computation.
If auto visibility is not enabled then sprite is considered as not visible by default (see SPR_setVisibility(..) method).
You can release all sprite resources by using SPR_releaseSprite(..) or SPR_reset(..).

See also:: SPR_addSpriteSafe(..); SPR_addSpriteEx(..); SPR_releaseSprite(..)

Sprite* SPR_addSpriteSafe	(	const SpriteDefinition *	spriteDef,
		s16	x,
		s16	y,
		u16	attribut
	)

Adds a new sprite with auto resource allocation enabled and returns it.

Parameters:

spriteDef	the SpriteDefinition data to assign to this sprite.
x	default X position.
y	default Y position.
attribut	sprite attribut (see TILE_ATTR() macro).

Returns:: the new sprite or NULL if the operation failed (some logs can be generated in the KMod console in this case)

By default the sprite uses automatic resources allocation (VRAM and hardware sprite) and visibility is set to ON.
You can change these defaults settings later by calling SPR_setVRAMTileIndex(..), SPR_setSpriteTableIndex(..), SPR_setAutoTileUpload(..) and SPR_setVisibility(..) methods.
You can release all sprite resources by using SPR_releaseSprite(..) or SPR_reset(..).<

See also:: SPR_addSpriteSafeEx(..); SPR_addSprite(..); SPR_releaseSprite(..)

void SPR_clear ( )

Clear all displayed sprites.

This method allow to quickly hide all sprites (without releasing their resources).
Sprites can be displayed again just by calling SPR_update().

bool SPR_computeVisibility ( Sprite * sprite )

Deprecated:: Use SPR_isVisible(..) instead.

void SPR_end ( )

End the Sprite engine.

End the sprite engine and release attached resources.
This releases the allocated VRAM region and hardware sprites.

SpriteVisibility SPR_getVisibility ( Sprite * sprite )

Return the visibility state for this sprite.
WARNING: this is different from SPR_isVisible(..) method, possible value are:
SpriteVisibility.VISIBLE = sprite is visible
SpriteVisibility.HIDDEN = sprite is not visible
SpriteVisibility.AUTO_FAST = visibility is automatically computed - global visibility (only using sprite X position)
SpriteVisibility.AUTO_SLOW = visibility is automatically computed - per hardware sprite visibility (only using sprite X position)

Parameters:

sprite Sprite to return visibility state

Returns:: the visibility state for this sprite.

See also:: SPR_isVisible(...); SPR_setVisibility(...)

void SPR_init ( )

Initialize the Sprite engine with default parameters.

Initialize the sprite engine using default parameters (420 reserved tiles in VRAM).
This also initialize the hardware sprite allocation system.

See also:: SPR_initEx(); SPR_end()

void SPR_initEx ( u16 vramSize )

Init the Sprite engine with specified advanced parameters (VRAM allocation size and decompression buffer size).

Parameters:

vramSize size (in tile) of the VRAM region for the automatic VRAM tile allocation.
If set to 0 the default size is used (420 tiles)

Initialize the sprite engine.
This allocates a VRAM region for sprite tiles and initialize hardware sprite allocation system.

See also:: SPR_init(); SPR_end()

bool SPR_isVisible	(	Sprite *	sprite,
		bool	recompute
	)

Return the visible state for this sprite (meaningful only if AUTO visibility is enabled, see SPR_setVisibility(..) method).

Parameters:

sprite	Sprite to return visible state
recompute	Force visibility computation. Only required if SPR_update() wasn't called since last sprite position change (note that can force the frame update processing).

Note that only the sprite X position is used to determine if it's visible (see SPR_setVisibility(..) method for more information)

Returns:: the visible state for this sprite.

See also:: SPR_setVisibility(...)

u16** SPR_loadAllFrames	(	const SpriteDefinition *	sprDef,
		u16	index,
		u16 *	totalNumTile
	)

Load all frames of SpriteDefinition (using DMA) at specified VRAM tile index and return the indexes table.
WARNING: This function should be call at init/loading time as it can be quite long (several frames)

Parameters:

sprDef	the SpriteDefinition we want to load frame data in VRAM.
index	the tile position in VRAM where we will upload all sprite frame tiles data.
totalNumTile	if not NULL then the function will store here the total number of tile used to load all animation frames.

Load all frames of spriteDef (using DMA) at specified VRAM tile index and return the indexes table.
The returned index table is a dynamically allocated 2D table[anim][frame] so you need to release it using MEM_free(..) when you don't need the table anymore.
You can use the frame change callback (see SPR_setFrameChangeCallback(..)) to automatically update the VRAM index using the indexes table:
frameIndexes = SPR_loadAllFrames(sprite->definition, ind); SPR_setFrameChangeCallback(sprite, &frameChanged); .... void frameChanged(Sprite* sprite) { u16 tileIndex = frameIndexes[sprite->animInd][sprite->frameInd]; SPR_setVRAMTileIndex(sprite, tileIndex); }

Returns:: the 2D indexes table or NULL if there is not enough memory to allocate the table.

See also:: SPR_setFrameChangeCallback(...);

void SPR_nextFrame ( Sprite * sprite )

Pass to the next sprite frame.

Parameters:

sprite Sprite to pass to next frame for

void SPR_releaseSprite ( Sprite * sprite )

Release the specified sprite (no more visible and release its resources).

Parameters:

sprite Sprite to release

This method release resources for the specified Sprite object and remove it from the screen at next SPR_update() call.

See also:: SPR_releasesSprite(..)

void SPR_reset ( )

Reset the Sprite engine.

This method releases all allocated sprites and their resources.

void SPR_setAlwaysOnTop	(	Sprite *	sprite,
		u16	value
	)

Deprecated:: Use SPR_setDepth(SPR_MIN_DEPTH) instead

void SPR_setAlwaysVisible	(	Sprite *	sprite,
		u16	value
	)

Deprecated:: Use SPR_setVisibility(..) method instead.

void SPR_setAnim	(	Sprite *	sprite,
		s16	anim
	)

Set current sprite animation.

Parameters:

sprite	Sprite to set animation for
anim	animation index to set.

void SPR_setAnimAndFrame	(	Sprite *	sprite,
		s16	anim,
		s16	frame
	)

Set current sprite animation and frame.

Parameters:

sprite	Sprite to set animation and frame for
anim	animation index to set
frame	frame index to set

void SPR_setAutoTileUpload	(	Sprite *	sprite,
		bool	value
	)

Enable/disable the automatic upload of sprite tiles data into VRAM.

Parameters:

sprite	Sprite we want to enable/disable auto tile upload for
value	TRUE to enable the automatic upload of sprite tiles data into VRAM. FALSE to disable it (mean you have to handle that on your own).

bool SPR_setDefinition	(	Sprite *	sprite,
		const SpriteDefinition *	spriteDef
	)

Set the Sprite Definition.

Parameters:

sprite	Sprite to set definition for.
spriteDef	the SpriteDefinition data to assign to this sprite.

Set the Sprite Definition for this sprite.
By default the first frame of the first animation from Sprite Definition is loaded.

Returns:: FALSE if auto resource allocation failed, TRUE otherwise.

void SPR_setDelayedFrameUpdate	(	Sprite *	sprite,
		bool	value
	)

Enable/disable the delayed frame update.

Parameters:

sprite	Sprite we want to enable/disable delayed frame update
value	TRUE to enable the delayed frame update when DMA is running out of transfert capacity (default). FALSE to disable it. In which case sprite frame is always updated immediately but that may cause graphical glitches (update during active display).

See also:: SPR_FLAG_DISABLE_DELAYED_FRAME_UPDATE

void SPR_setDepth	(	Sprite *	sprite,
		s16	value
	)

Set sprite depth (for sprite display ordering)

Parameters:

sprite	Sprite to set depth for
value	The depth value (SPR_MIN_DEPTH to set always on top)

Sprite having lower depth are display in front of sprite with higher depth.
The sprite is *immediately* sorted when its depth value is changed.

void SPR_setFrame	(	Sprite *	sprite,
		s16	frame
	)

Set current sprite frame.

Parameters:

sprite	Sprite to set frame for
frame	frame index to set.

void SPR_setFrameChangeCallback	(	Sprite *	sprite,
		FrameChangeCallback *	callback
	)

Set the frame change event callback for this sprite.

Parameters:

sprite	Sprite we want to set the frame change callback
callback	the callback (function pointer) to call when we just changed the animation frame for this sprite.

The callback (if not NULL) will be called on frame change process during SPR_update() call (CAUTION: sprite->status field is not up to date at this point).
It let opportunity to the developer to apply special behavior or process when sprite frame just changed:
for instance we can disable animation looping by setting sprite->timer to 0 when we meet the last animation frame.

See also:: FrameChangeCallback

void SPR_setHFlip	(	Sprite *	sprite,
		u16	value
	)

Set sprite Horizontal Flip attribut.

Parameters:

sprite	Sprite to set attribut for
value	The horizontal flip attribut value (TRUE or FALSE)

void SPR_setNeverVisible	(	Sprite *	sprite,
		u16	value
	)

Deprecated:: Use SPR_setVisibility(..) method instead.

void SPR_setPalette	(	Sprite *	sprite,
		u16	value
	)

Set sprite Palette index to use.

Parameters:

sprite	Sprite to set attribut for
value	The palette index to use for this sprite (PAL0, PAL1, PAL2 or PAL3)

void SPR_setPosition	(	Sprite *	sprite,
		s16	x,
		s16	y
	)

Set sprite position.

Parameters:

sprite	Sprite to set position for
x	X position
y	Y position

void SPR_setPriority	(	Sprite *	sprite,
		u16	value
	)

Set sprite Priority attribut.

Parameters:

sprite	Sprite to set attribut for
value	The priority attribut value (TRUE or FALSE)

void SPR_setPriorityAttribut	(	Sprite *	sprite,
		u16	value
	)

Deprecated:: Use SPR_setPriority(..) instead

bool SPR_setSpriteTableIndex	(	Sprite *	sprite,
		s16	value
	)

Set the VDP sprite index to use for this sprite.

Parameters:

sprite	Sprite to set the VDP Sprite index for
value	the index of the first sprite in the VDP sprite table used to display this Sprite (should be > 0 and < 128). Use -1 for auto allocation.

Returns:: FALSE if auto allocation failed (can happen only if sprite is currently active), TRUE otherwise

By default the Sprite Engine auto allocate VDP sprite but you can force manual allocation and fix the index of the first VDP sprite to use with this method.
If you set the index manually you need to ensure you have enough available contiguous VDP sprites at this index so it can fit the current sprite requirement in VDP sprite. WARNING: you cannot use sprite 0 as it is internally reserved.

void SPR_setVFlip	(	Sprite *	sprite,
		u16	value
	)

Set sprite Vertical Flip attribut.

Parameters:

sprite	Sprite to set attribut for
value	The vertical flip attribut value (TRUE or FALSE)

void SPR_setVisibility	(	Sprite *	sprite,
		SpriteVisibility	value
	)

Set the visibility state for this sprite.

Parameters:

sprite	Sprite to set the visibility information
value	Visibility value to set. SpriteVisibility.VISIBLE = sprite is visible SpriteVisibility.HIDDEN = sprite is not visible SpriteVisibility.AUTO_FAST = visibility is automatically computed - global visibility (only using sprite X position) SpriteVisibility.AUTO_SLOW = visibility is automatically computed - per hardware sprite visibility (only using sprite X position)

The only interest in having a sprite hidden / not visible is to avoid having it consuming scanline sprite budget:
The VDP is limited to a maximum of 20 sprites or 320 pixels of sprite per scanline (16 sprites/256 px in H32 mode).
If we reach this limit, following sprites won't be renderer so it's important to try to optimize the number of sprites on a single scanline.
When a sprite is set to not visible (automatically or manually), its position is set offscreen *vertically* so it won't eat anymore the scanline sprite rendering budget, only X position test is required for that so a sprite is determined not visible only using its X coordinate.

See also:: SPR_computeVisibility(...); SPR_getVisibility(...); SPR_isVisible(...)

bool SPR_setVRAMTileIndex	(	Sprite *	sprite,
		s16	value
	)

Set the VRAM tile position reserved for this sprite.

Parameters:

sprite	Sprite to set the VRAM tile position for
value	the tile position in VRAM where we will upload the sprite tiles data. Use -1 for auto allocation.

Returns:: FALSE if auto allocation failed (can happen only if sprite is currently active), TRUE otherwise

By default the Sprite Engine auto allocate VRAM for sprites tiles but you can force manual allocation and fix the sprite tiles position in VRAM with this method.

void SPR_update ( )

Update and display the active list of sprite.

This actually updates all internal active sprites states and prepare the sprite list cache to send it to the hardware (VDP) at Vint.