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  

SoSpriteManager

Manages sprite objects. More...

Files

file  SoSpriteManager.c
file  SoSpriteManager.h

Functions

void SoSpriteManagerInitialize (void)
 Initializes the sprite manager.

void SoSpriteManagerUpdate (void)
 Updates the sprite attributes in real object attribute memory.

void SoSpriteManagerEnableSprites (void)
 Enables sprite rendering.

void SoSpriteManagerDisableSprites (void)
 Disables sprites rendering.

SoSprite * SoSpriteManagerRequestSprite (void)
 Returns a pointer to an available sprite.

void SoSpriteManagerRelease (SoSprite *a_Sprite)
 Releases a sprite.

void SoSpriteManagerSetMosaic (u32 a_HorizontalSize, u32 a_VerticalSize)
 Sets the sprite mosaic values.

u32 SoSpriteManagerGetHorizontalMosaic (void)
 Returns the horizontal sprite mosaic value;.

u32 SoSpriteManagerGetVerticalMosaic (void)
 Returns the vertical sprite mosaic value;.

void SoSpriteManagerSetRotationAndScale (u32 a_Index, s32 a_Angle, u32 a_FixedScaleX, u32 a_FixedScaleY)
 Sets the rotation and scale values for the given index.

Detailed Description

Manages sprite objects.

Singleton

This module manages all sprites.

It handles the GBA's object attribute memory. This module does NOT manage the actual sprite memory (where characters are located). The SoSpriteMemManager module is for that. Of course these two modules do interact in some way. Upon studying this module, I suggest you take a look at the SoSprite and SoSpriteMemManager 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.

Note that this module uses the interrupt manager. If the interrupt manager is not already initialized, it will initialize it in its own initialize routine.

This module does more than just manage OAM; it also handles sprite mosaic values, rotation and scale settings, etc. etc. In short everything sprite related that doesn't belong to a particular sprite instance (because then it would be in SoSprite).

Function Documentation

void SoSpriteManagerDisableSprites (  void    ) 
 

Disables sprites rendering.

Disables the visibility of all sprites and deinstalls the shadow-to-real-oam copy routine during VBlank.

void SoSpriteManagerEnableSprites (  void    ) 
 

Enables sprite rendering.

Ofcourse you have to have a sprite and some character data the sprite uses, in order to see a sprite, but without this routine the sprites would all be invisible.

This also enables the shadow-to-real-oam copy routine in VBlank.

u32 SoSpriteManagerGetHorizontalMosaic (  void    ) 
 

Returns the horizontal sprite mosaic value;.

Returns :
The horizontal sprite mosaic value (Range is [0, 15]).

u32 SoSpriteManagerGetVerticalMosaic (  void    ) 
 

Returns the vertical sprite mosaic value;.

Returns :
The vertical sprite mosaic value (Range is [0, 15]).

void SoSpriteManagerInitialize (  void    ) 
 

Initializes the sprite manager.

Should be the first function you call before you call any other SoSpriteManager function.

Make sure you have already called SoDisplayInitialize too.

void SoSpriteManagerRelease (  SoSprite *    a_Sprite ) 
 

Releases a sprite.

Parameters:
a_Sprite  Sprite you wish to release.
Use this routine when you no longer need a certain sprite. The sprite manager reclaims it and after this it can be used for new sprite purposes.

Warning:
Do not use the sprite after you have released it. There are no garantuees on what will happen. Well, your GBA probably won't explode, but you never know, eh :)....

SoSprite* SoSpriteManagerRequestSprite (  void    ) 
 

Returns a pointer to an available sprite.

This is the only way to obtain a sprite. You can instantiate a sprite structure yourself but it will be useless. You have to ask the sprite manager for a sprite by using this function.

This routine will never fail. In debug mode an assertion will be triggered when there are no more sprites available. Because of the fixed memory environment you can safely assume that if it works in debug, it'll work in release.

void SoSpriteManagerSetMosaic (  u32    a_HorizontalSize,
u32    a_VerticalSize
) 
 

Sets the sprite mosaic values.

Parameters:
a_HorizontalSize  Horizontal Mosaic value, 0 is no mosaic value, 15 is maximum value.
a_VerticalSize  Vertical Mosaic value, 0 is no mosaic value, 15 is maximum value.
Sets the global horizontal / vertical mosiac values for sprites. These values are used in the rendering of all sprites which have mosaic mode enabled.

void SoSpriteManagerSetRotationAndScale (  u32    a_Index,
s32    a_Angle,
u32    a_FixedScaleX,
u32    a_FixedScaleY
) 
 

Sets the rotation and scale values for the given index.

Parameters:
a_Index  Index of the rotation and scale setting; [0..31] inclusive.
a_Angle  Angle of the rotation, (256 is a full circle).
a_FixedScaleX  Horizontal scale value in the SGADE fixed (17.15) format. Smaller value decrease the size of the sprite, 1.0 does nothing, and bigger values largen the sprite.
a_FixedScaleY  Vertical scale value in the SGADE fixed (17.15) format.
The GBA's sprite rotation and scale system is a bit weird. Not every sprite has his own rotation and scale values. Instead there are several rotation and scale settings, and a sprite can refer to one of these settings and use it.

With this method you can set the rotation and scale for the given index. After that, tell a sprite to use this index, and he'll rotate and scale accordingly (if you have sprite rotation and scaling enabled for that sprite).

See the Pern Project (http://www.thepernproject.com) or other Nintendo references for more information on this system.

void SoSpriteManagerUpdate (  void    ) 
 

Updates the sprite attributes in real object attribute memory.

This function copied the shadow object attribute memory to the real object attribute memory. Without calling this function you won't ever see your sprites.

Warning:
Call this only during VBlank. You can either call it in a VBlank interrupt, or right after a SoDisplayWaitForVBlankStart call.
Warning:
If in the future we are going to do multiplayer stuff, we have to be carefull about DMA transfers cause they block interrupts. We might therefore consider using a CPUCopy for this function instead;

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