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  

SoSprite

To represent single sprites. More...

Files

file  SoSprite.c
file  SoSprite.h

Data Structures

struct  SoSprite
 Structure representing a single sprite. More...


Functions

void SoSpriteDisable (SoSprite *a_This)
 Disables rendering of this sprite.

void SoSpriteFlipHorizontal (SoSprite *a_This)
 Flips the sprite horizontally.

void SoSpriteFlipVertical (SoSprite *a_This)
 Flips the sprite vertically.

u32 SoSpriteGetWidth (SoSprite *a_This)
 Returns the width of the sprite.

u32 SoSpriteGetHeight (SoSprite *a_This)
 Returns the height of the sprite.

void SoSpriteSetTranslate (SoSprite *a_This, s32 a_X, s32 a_Y)
 Sets the screen position of the top left corner of the sprite.

void SoSpriteSetMosaicEnable (SoSprite *a_This, bool a_Enable)
 Enabs the mosaic for this sprite.

void SoSpriteSetSizeDoubleEnable (SoSprite *a_This, bool a_Enable)
 Enables double size for the sprite.

void SoSpriteSetRotationAndScaleEnable (SoSprite *a_This, bool a_Enable)
 Enables sprite rotation and scaling.

void SoSpriteSetRotationAndScaleIndex (SoSprite *a_This, u32 a_Index)
 Sets the index used for sprite scale and rotation settings.

void SoSpriteSet256ColorMode (SoSprite *a_This, bool a_Enable)
 Sets the sprite to 256 color palette mode instead of 16 color palettes.

void SoSpriteSetAnimationIndex (SoSprite *a_This, u32 a_Index)
 Sets the animation (character-data) this sprite should use.

u32 SoSpriteGetAnimationIndex (SoSprite *a_This)
 Returns the animation index the sprite is using.

void SoSpriteSetSize (SoSprite *a_This, u32 a_Width, u32 a_Height)
 Sets the size of the sprite.

void SoSpriteSetPriority (SoSprite *a_This, u32 a_Priority)
 changes the display priority for a particular sprite

void SoSpriteCopyPropertiesFromAnimation (SoSprite *a_This, const SoSpriteAnimation *a_Animation)
 Copies the size and color attributes from a certain animation.

void SoSpriteSet16ColorPaletteIndex (SoSprite *a_This, u16 a_Index)
 set the sprite to use one of the 16 palettes available in 16 color mode

Detailed Description

To represent single sprites.

This module contains all single sprite functionality. It works together with the SoSpriteManager and SoSpriteMemManager to create a complete sprite system. So before you start using SoSprite objects read about these other two modules too.

One other thing. Sometimes sprites are referred to as objects or OBJ's. This is all the same.

Function Documentation

void SoSpriteCopyPropertiesFromAnimation (  SoSprite *    a_This,
const SoSpriteAnimation *    a_Animation
) 
 

Copies the size and color attributes from a certain animation.

Parameters:
a_This  This pointer.
a_Animation  Animation the sprite uses.
This copies the size and the color (256 or 16) properties from the animation into the sprite. The complete code for loading a sprite then becomes: 

        // Include the animation data;
        #include "someAnimation.data";      

        // Request a location in OAM;
        SoSprite* sprite = SoSpriteManagerRequestSprite();          
        
        // Load the animation and assign it to the sprite;
        SoSpriteSetAnimationIndex( someSprite, SoSpriteMemManagerLoad( someAnimation ) );

        // Copy the animation's properties.
        SoSpriteCopyPropertiesFromAnimation( someSprite, someAnimation );

void SoSpriteDisable (  SoSprite *    a_This ) 
 

Disables rendering of this sprite.

Parameters:
a_This  This pointer.

void SoSpriteFlipHorizontal (  SoSprite *    a_This ) 
 

Flips the sprite horizontally.

Parameters:
a_This  This pointer.
Call twice to bring back to the original setting.

void SoSpriteFlipVertical (  SoSprite *    a_This ) 
 

Flips the sprite vertically.

Parameters:
a_This  This pointer.
Call twice to bring back to the original setting.

u32 SoSpriteGetAnimationIndex (  SoSprite *    a_This ) 
 

Returns the animation index the sprite is using.

Parameters:
a_This  This pointer.

u32 SoSpriteGetHeight (  SoSprite *    a_This ) 
 

Returns the height of the sprite.

Parameters:
a_This  This pointer.

u32 SoSpriteGetWidth (  SoSprite *    a_This ) 
 

Returns the width of the sprite.

Parameters:
a_This  This pointer.

void SoSpriteSet16ColorPaletteIndex (  SoSprite *    a_This,
u16    a_Index
) 
 

set the sprite to use one of the 16 palettes available in 16 color mode

Parameters:
a_This  Sprite's 'this' pointer
a_Index  which 16 color palette (out of 16 avail) to use
This function sets the index to the 16 color palette that the sprite will use. In 16 color mode, the GBA has 16 different 16-Color palettes available for the sprites to use.

void SoSpriteSet256ColorMode (  SoSprite *    a_This,
bool    a_Enable
) 
 

Sets the sprite to 256 color palette mode instead of 16 color palettes.

Parameters:
a_This  This pointer.
a_Enable  True if the sprite is 256 colors, false if 16 colors.
Note that you will rarely use this function, cause you can deduce this values from the animation you want the sprite to use. So when you've loaded an animation, and you have a certain sprite, you can do the following: 

        SoSpriteCopyPropertiesFromAnimation( someSprite, someAnimation );

And the sprite will have the correct color mode.

void SoSpriteSetAnimationIndex (  SoSprite *    a_This,
u32    a_Index
) 
 

Sets the animation (character-data) this sprite should use.

Parameters:
a_This  This pointer.
a_Index  Index of the animation data as loaded by the sprite memory manager.
Often used like this: 
        SoSprite* sprite = SoSpriteManagerRequestSprite();
        SoSpriteSetAnimationIndex( someSprite, SoSpriteMemManagerLoad( someAnimation ) );

See the SoSpriteMemManagerLoad function for more information. But basically it loads a certain animation data in sprite character memory and returns the index in sprite character memory.

If this is not clear, mail me. I'll update the docs.

void SoSpriteSetMosaicEnable (  SoSprite *    a_This,
bool    a_Enable
) 
 

Enabs the mosaic for this sprite.

Parameters:
a_This  This pointer.
a_Enable  True if you want mosaic enabled.
Ofcourse you have to set the SO_REG_DISP_MOSAIC register with some values to use mosaic for sprites.

void SoSpriteSetPriority (  SoSprite *    a_This,
u32    a_Priority
) 
 

changes the display priority for a particular sprite

Parameters:
a_This  Sprite's 'this' pointer
a_Priority  Display priority for the sprite (0 to 3)
This function updates the display priority for a given sprite. Sprites with lower priority are displayed in front of sprites or backgrounds with highter priority.

When the priority of two sprites is the same, the sprite with the lower index number is displayed on top. When the priority of a sprite is the same as the priority of a background, the sprite is displayed on top.

void SoSpriteSetRotationAndScaleEnable (  SoSprite *    a_This,
bool    a_Enable
) 
 

Enables sprite rotation and scaling.

Parameters:
a_This  This pointer.
a_Enable  True if you want to enable it. False if you want to disable it.

void SoSpriteSetRotationAndScaleIndex (  SoSprite *    a_This,
u32    a_Index
) 
 

Sets the index used for sprite scale and rotation settings.

Parameters:
a_This  This pointer.
a_Index  Index of the sprite scale and rotation settings (range [0..31]).
You can set the sprite scale and rotation values with the SoSpriteManagerSetRotationAndScale function. Use the same index as you use for this one and the sprite will use it.

void SoSpriteSetSize (  SoSprite *    a_This,
u32    a_Width,
u32    a_Height
) 
 

Sets the size of the sprite.

Parameters:
a_This  This pointer.
a_Width  Width of the sprite.
a_Height  Height of the sprite.
Not all widths and heights combinations are valid. The following can be used...

8x8 16x16 32x32 64x64 8x16 8x32 16x32 32x64 16x8 32x8 32x16 64x32

In debug mode these values are asserted. Note that you will rarely use this function, cause you can deduce these values from the animation you want the sprite to use. So when you've loaded an animation, and you have a certain sprite, you can do the following: 

        SoSpriteCopyPropertiesFromAnimation( someSprite, someAnimation );

And the sprite will have the correct size.

void SoSpriteSetSizeDoubleEnable (  SoSprite *    a_This,
bool    a_Enable
) 
 

Enables double size for the sprite.

Parameters:
a_This  This pointer.
a_Enable  True if you want the sprite to double in size (of the canvas).
Usefull for rotating sprites. Cause a rotating sprite will exceed its canvas when rotated 45 degrees (for example). With this enabled it won't.

void SoSpriteSetTranslate (  SoSprite *    a_This,
s32    a_X,
s32    a_Y
) 
 

Sets the screen position of the top left corner of the sprite.

Parameters:
a_This  This pointer.
a_X  Integer horizontal screen coordinate in the range [-sprite width .. 240]
a_Y  Integer horizontal screen coordinate in the range [-sprite height .. 120]
This positions the sprite on the correct location on screen. Takes care of sprite clipping (negative coords) and sprite double sizing. So don't worry....

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