The SGADE Documentation

the SGADE The Socrates Gameboy Advance Development Engine

The SGADE is a development library for the Nintendo Gameboy Advance. It's free for all uses and is distributed without guarantees. For more information visit the SGADE page.

Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

SoSpriteMemManager

Handles sprite character memory. More...

Files

file  SoSpriteMemManager.c
file  SoSpriteMemManager.h

Functions

void SoSpriteMemManagerInitialize (void)
 Initializes the sprite memory manager.

void SoSpriteMemManagerSetInBitmappedMode (bool a_Enable)
 Use when you are in mode 3, 4, or 5 when using sprites.

void SoSpriteMemManagerCopyFromImage (u32 a_Index, SoImage *a_Image)
 Copies an image in sprite memory.

u32 SoSpriteMemManagerLoadFromImage (SoImage *a_Image)
 Loads an image in sprite memory and returns the index in sprite memory.

u32 SoSpriteMemManagerLoad (const SoSpriteAnimation *a_Animation)
 Loads a animation in sprite memory and returns the index in sprite memory.

u32 SoSpriteMemManagerLoadFrame (u16 a_Frame, const SoSpriteAnimation *a_Animation)
 Load an individual animation frame into memory.

void SoSpriteMemManagerCopyFrame (u32 a_Index, u16 a_Frame, const SoSpriteAnimation *a_Animation)
 Copy an individual animation frame into memory.

void SoSpriteMemManagerRelease (u32 a_Index)
 Releases a given tileset index from memory.

Detailed Description

Handles sprite character memory.

Singleton.

This module handles the character data for sprites. It uses the SoSpriteAnimation struct to load animations (tiles, characters, whatever you name it) into sprite memory. This is distinct from OAM (object attribute memory) which is about sprite attributes. We have the SoSpriteManager for that. This module works together with the SoSpriteManager and SoSprite instances to create a complete sprite system. So before you start using this module read about these other two modules too.

Most of the ideas behind this implementation came from Rafael Baptista's excellent article on GBA resource management that was originally posted on http://www.gamasutra.com Unfortunately the article was removed from the site due to legal reasons.

Todo:
Implement a ref-count for sprite animations, so sprites can share animations.

Function Documentation

void SoSpriteMemManagerCopyFrame (  u32    a_Index,
u16    a_Frame,
const SoSpriteAnimation *    a_Animation
) 
 

Copy an individual animation frame into memory.

This works the same as SoSpriteMemManagerLoadFrame() except that instead of loading the frame to a free slot, it overwrites the slot pointed to by a_Index

Parameters:
a_Index  The slot to overwrite with the animation frame. This normally refers to the base sprite index
a_Frame  The zero-based index of the frame to copy from.
a_Animation  The animation form which to obtain the frame to copy.
Used together with SoSpriteMemManagerLoadFrame(), DMA animation method can be used. for example: 
    // load the first frame and get the base sprite index
    g_BaseSprite = SoSpriteMemManagerLoadFrame(0, &myAnimation);
    
    // more code below ....
    
    // ... when you require to switch to the next animation frame
    nextFrame++;
    SoSpriteMemManagerCopyFrame(g_BaseSprite, nextFrame, &myAnimation);

void SoSpriteMemManagerCopyFromImage (  u32    a_Index,
SoImage *    a_Image
) 
 

Copies an image in sprite memory.

Parameters:
a_Index  Index in sprite memory to load data to.
a_Image  Image you want to load.
Note that image should be palettized (256 color palette mode) and its dimensions should be sprite-compatible.

void SoSpriteMemManagerInitialize (  void    ) 
 

Initializes the sprite memory manager.

This should be the first function you call before using any other functions of SoSpriteMemManager.

u32 SoSpriteMemManagerLoad (  const SoSpriteAnimation *    a_Animation ) 
 

Loads a animation in sprite memory and returns the index in sprite memory.

Parameters:
a_Animation  Animation you want to load.
You can use the returned index as an index for a sprite object, and the sprite object will automatically use the given tileset. Like this: 
        SoSprite* sprite = SoSpriteManagerRequestSprite();
        SoSpriteSetAnimationIndex( someSprite, SoSpriteMemManagerLoad( someAnimation ) );

This function will never fail. If there is no more room in sprite memory, an assertion will be fired in debug mode and you should rearrange your animations, or lower the game requirements. In release mode this function will not load the tileset, and just return zero as an index. But since release mode is functionality-wise the same as debug mode this should never happen, cause you've made it work in debug mode first, right?

Mhwuahuhahaha

u32 SoSpriteMemManagerLoadFrame (  u16    a_Frame,
const SoSpriteAnimation *    a_Animation
) 
 

Load an individual animation frame into memory.

This works the same as SoSpriteMemManagerLoad() except that only one frame is loaded into memory.

Parameters:
a_Frame  The zero-based index of the frame to load.
a_Animation  Animation you want to load from
Returns :
The sprite block index.

u32 SoSpriteMemManagerLoadFromImage (  SoImage *    a_Image ) 
 

Loads an image in sprite memory and returns the index in sprite memory.

Parameters:
a_Image  Image you want to load.
You can use the returned index as an index for a sprite object, just like the SoSpriteMemManagerLoad method, please refer to its documentation for further help.

Note that image should be palettized (256 color palette mode) and its dimensions should be sprite-compatible.

void SoSpriteMemManagerRelease (  u32    a_Index ) 
 

Releases a given tileset index from memory.

Parameters:
a_Index  Index of the animation (range is [0..1024]).
Often when you no longer need a sprite and its animation data, you will use it like this: 

        SoSpriteMemManagerRelease( SoSpriteGetAnimationIndex( someSprite ) );
        SoSpriteManagerRelease( someSprite );

Do not use the index after releasing it, cause no garantuees are made about its contents.

void SoSpriteMemManagerSetInBitmappedMode (  bool    a_Enable ) 
 

Use when you are in mode 3, 4, or 5 when using sprites.

Call this method if you're in bitmapped mode, to tell this manager that only half of the sprite memory is available. Call it before you request any tilesets. Forgetting to call this will result in sprites not showing up on the real thing and most emulators.

Copyright 2002 by the SGADE authors. See SoLicense.h or Visit the SGADE page for more information.