SDLSprite 1.2
This is the documentation for the SDLSprite class, designed
for SDL.
It is based on original documentation of CDXSprite.
1.0 : Initial library.
1.1 : Sprite's shadow handling with InitShadow, SetShadowOffset, SetShadowValue. It's
automaticaly drawn by Draw.
1.2 : * Position and velocity variables are now float type (in order to use velocity
in pixel/sec rather than pixel/frame in the main program).
* Add m_DelayStart var
This class contains the data and functions required to display animated sprites. A SDLSprite object is created from a pointer to a SDL_Surface object which is used to store the bitmap data for the sprite. All the sprite's frames must be the same width and height and stored in the same bitmap file.
SDLSprite is based on original sources from CDX and ported and modified for SDL by Regis Quercioli.
Known problems:
Tutorial
Here is a little code tutorial on how to use SDLSprite in your projects:
Initializing
First of all you have to create your SDLSprite object by loading the sprites' BMP picture:
SDLSprite * sprite = new SDLSprite ( "sprites.bmp", 32, 32, 16);
new SDLPrite wants to have the filename of the BMP picture, the sprites dimensions (width/height) and the number of sprites.
sprite->SetColorKey(0, 0, 0);
SetColorKey wants the R/G/B composants (from 0 to 255) of the transparancy color .
sprite->SetAlphaValue(160);
SetAlphaValue wants the apha value (0 totaly opaque and 255 totaly transparent)
sprite->m_NbFrame = 5;
sprite->m_DelayStart =
SDL_GetTicks();
The first one sets the total number of frames for a mouvement to 5. (Animations are not handled automaticaly, you must handle it by yourself using SetDelay, SetFrame, m_NbFrame, m_NbTotFrame...) and the other one sets sprite's animation timing to the actual system tick.
sprite->InitShadow(6, 6, 125, 70);
Where 6,6 are the shadow offset in the relation to the sprite, 125 is the shadow color ((0=black, 255=white) and 70 is the alpha value of the shodow (0=opaque, 255=totaly transparent)
Drawing
Here are the functions needed to draw the sprites.
You can move the sprite at the desired pixel position: sprite->SetPos( 155, 250 );
You can set is X/Y velocity: sprite->SetVel( 8, 8); (velocity is given in pixels/frame)
You can set a
new shadow offset: sprite->SetShadowOffset( 8, 8);
You can set a new shadow color and alpha
values: sprite->SetShadowValue(color, alpha);
You can set many other variables, for example: sprite->SetFrame (4);
Then, you can draw the sprite:
sprite->Draw (screen, 10, 30); (shadow is draw automaticaly)
Where screen is the SDL_Surface where you want to put the sprite, and 10, 30 is the offset of the map scrolling (if no scrolling is made just put 0, 0)
Sprite Methods
Operations:
SDL_bool InitShadow(int OffX, int OffY,
Uint8 Shade, Uint32 Alpha);
Init the sprite's shadow offsets,
color and alpha value.
void SetShadowOffset(int dx, int dy);
Change the sprite's shadow offsets.
void SetShadowValue(Uint8 Shade, Uint32 Alpha);
Change the sprite's shadow color
and alpha value.
void SetObjective(int ObjX, int ObjY)
;
(used for a mouse-click based mouvement)
Sets the
sprite's point to reach.
float F_Direction(void)
; (used for
a mouse-click based mouvement)
Calculates
the sprite's facing in function of its position and objective.
void Orientation(float Dir, short int NbPos)
; (used for
a mouse-click based mouvement)
Calculates
the sprite's frame to use for a certain facing (frame 0 is top facing, and then rotate to
right). NbPos is the numbers of pisitions for the sprite's orientation.
void Mvt(short int NbPos = 0)
; (used for
a mouse-click based mouvement)
Moves the
sprite (with its own velocity) toward its objective. NbPos is the numbers of
pisitions for the sprite's orientation.
SDL_bool End_Mvt(SDLSprite* Sprite)
; (used for
a mouse-click based mouvement)
Checks if
the sprite's arrived to its destination. Returns TRUE if sprite's arrived.
Data Members:
int m_ShadowOffsetX
- Shadow offset from sprite
int m_ShadowOffsetY
- Shadow offset from sprite
Uint32 m_ShadowValue
- Shadow value (0=black, 255=white)
Uint32 m_ShadowAlpha
- Shadow alpha value (0=opaque, 255=totaly transparent)
Uint32 m_AlphaValue
- Sprite Alpha value (0=opaque, 255=totaly transparent)
Uint32 m_ColorKey
- Transparent color key
SDL_Surface* m_Surface
- the surface holding the sprite's bitmap picture
SDL_Surface* m_Shadow
- the surface holding the sprite's shadow picture (created by InitShadow)
int m_PixelWidth -
Width of the bitmap picture
int m_PixelHeight
- Height of the bitmap picture
int m_BlockWidth -
The width of one sprite tile, in pixels
int m_BlockHeight
- The height of one sprite tile, in pixels
int m_BlockNum -
The number of sprite tiles in the bitmap file