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:

• 8 bits modes:
  Transparancy not allowed for the moment with SetColorKey(R, G, B), you must use SetColorKey()
  Look at the sprite methods for the difference between the two functions...
• Using shadow:
  If the sprite's shadow goes out of the display, the sprite himself disapear and only its shadow remains. I don't understand where this problem comes from... If you find please E-Mail me :)

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.

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)

        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

Constructors/Destructors:

SDLSprite() ;

Default constructor.

SDLSprite(SDLSprite* pTile ) ;

Creates a sprite object from a pointer to a SDLSprite object holding the sprite's bitmap data.

SDLSprite(const char* Filename ,int w ,int h ,int num ) ;

Creates the sprite object. Requires a pointer to the name of the bitmap in which the sprite is stored. The w and h parameters refer to the width and height of a single frame of the sprite and the num parameter refers to the total number of frames in the bitmap file.

virtual ~SDLSprite() ;

Destroys the surface and frees the memory.

void Draw(SDLSurface* lpSDLS ,DWORD ScrnWorldX ,DWORD ScrnWorldY ) ;

Staging area for all blit types.

 

void SetAlphaValue(WORD Shade ) ;

Set the sprites' Alpha value (0 totaly opaque and 255 totaly transparent).

 

void SetColorKey(void) ;

The transparancy color key is the color of the top-left pixel of the BMP sprites' picture.

 

void SetColorKey(Uint8 R, Uint8 G, Uint8 B ) ;

 Set the transparancy color key.

 

void SetDelay(int Delay ) ;

 Set the delay between  two animation frames of a sprite in ms.

 

void SetFrame(int Frame ) ;

 Set the current sprite's frame.

 

void SetPos(int pX ,int pY ) ;

 Set the sprite's X/Y pixels position.

 

void SetState(int State ) ;

 Set the sprite's user defined state (jumping, walking, ...)

 

void SetType(int Type ) ;

 Set the sprite's user defined type (monster, health, ...)

 

void SetVel(int vX ,int vY ) ;

 Set the X/Y pixels/frame sprite's velocity.

 

BOOL SpriteHit(SDLSprite* pSprite ) ;

Checks for collisions between sprites. Returns TRUE if any part of Sprite overlaps with any part of the source sprite.

 

BOOL SpriteHitPixel(SDLSprite* pSprite ) ;

Checks for collisions between sprites. Returns TRUE if any non-colorkey part of Sprite overlaps with non-colorkey part of the source sprite.

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.

Public:

float  m_Angle  - The sprite's angle of rotation (in radian).
int m_Delay  - Used for game timing, the time till the next frame.
Uint32 m_DelayStart - Begining of the sprite's animation timing (take a look at SDLSprite_Example4)
int m_Frame  - The current frame.
int m_NbFrame - Number frames for an animation (for a mouvement or action or what you want).

int m_NbTotFrame - Total number of different frames for this sprite
SDLSprite* m_Next  - A SDLSprite pointer to the next sprite in a SDLSpriteList.
SDLSprite* m_Prev  - A SDLSprite pointer to the previous sprite in a SDLSpriteList.
float m_PosX  - The sprite's X position.
float m_PosY  - The sprite's Y position.
float m_PosZ  - The sprite's Z position.
int m_State - User defined state.   Walking,   jumping, etc.
int m_Type - User defined type.  Monster, Health, etc.
SDL_Surface* m_Surface - A SDL_Surface pointer to the sprite's bitmap data.
BOOL m_TileCreated
int m_Type  - User defined type. Health, weapon, etc.
float m_VelX- The sprite's X velocity (in pixels/sec).
float m_VelY  - The sprite's Y velocity (in pixels/sec).
float m_VelR  - The sprite's Radial velocity (in pixels/sec).

          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