sgdk: sprite_eng.h File Reference

sgdk

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Classes | Defines | Typedefs | Enumerations | Functions | Variables
sprite_eng.h File Reference

Sprite engine. More...

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

Go to the source code of this file.

## 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. FALSE to disable it (sprite frame is always updated immediately but that may cause graphical glitches).

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.

See also:
  SPR_addSprite(..)

## Variable Documentation

Sprite* firstSprite

First allocated sprite (NULL if no sprite allocated)

Sprite* lastSprite

Last allocated sprite (NULL if no sprite allocated)

Sprite* spritesBank

Sprites bank for the sprite engine

u16 spriteVramSize

Allocated VRAM (in tile) for Sprite Engine

All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines