CRM32Pro_CSprite Class Reference
[MODULE 12: CSprite v4.21, sprite engine class.]

CSprite. More...

---

Detailed Description

CSprite.

Sprite engine class.

Examples:

Example08_SpriteCollision.cpp, Example09_LogicRenderRates.cpp, SpacePong.cpp, and SpacePong.h.

List of all members.

Public Member Functions
void	AutoRestore (char value)
	Enable or disable auto background restore.
void	Clean ()
	Clean and reset the content of current sprite.
int	Clone (CRM32Pro_CSprite *pSpr)
	Create a new slave sprite from the given master sprite.
int	Collision (SDL_Surface *surf, SDL_Rect *rect, short this_x=-1, short this_y=-1, unsigned char debug=0)
	Check collision with a given surface.
int	Collision (CRM32Pro_CSprite *spr, short spr_x=-1, short spr_y=-1, short this_x=-1, short this_y=-1, unsigned char debug=0)
	Check collision with another sprite.
int	Create (SDL_Surface *surf, char *namespr, int OffX, int OffY)
	Create a master sprite from a surface.
int	Create (char *spritebmp, char *namespr, int OffX, int OffY)
	Create a master sprite from an external image file(BMP/PNG).
int	Draw (SDL_Surface *dump=NULL)
	Draw sprite (current frame of current animation with the selected special effect).
int	GetAlpha ()
	Get alpha blending information.
int	GetAnim ()
	Get current animation state.
void	GetAnimProperties (int which, unsigned short *type=NULL, unsigned short *status=NULL, unsigned short *frames=NULL, signed short *hotx=NULL, signed short *hoty=NULL, unsigned short *startframe=NULL, unsigned short *endframe=NULL)
	Get the properties of an animation.
int	GetCollisionMethod ()
	Get current collision method of this sprite.
int	GetColorKey ()
	Get the current color key.
int	GetFrame ()
	Get current frame number.
void	GetFrameProperties (int iAnim, int iFrame, unsigned int *ms=NULL)
	Get the frame properties.
char *	GetName ()
	Get the sprite name.
void	GetOffset (int *, int *)
	Get X(width) and/or Y(height) size for each frame.
int	GetPosX ()
	Get X position of the sprite.
int	GetPosY ()
	Get Y position of the sprite.
SDL_Surface *	GetSurface ()
	Get sprite surface.
void	Info ()
	Print a lot of useful sprite information. Very useful for debugging purposes.
unsigned char	IsFinished ()
	Has finished the animation?
int	Load (int idDPF, char *namespr, char *typeblock="SPR2")
	Load a master sprite from a DPF(using an idDPF).
int	Load (char *fileDPF, char *namespr, char *typeblock="SPR2")
	Load a master sprite from a DPF(using a filename).
void	Pause ()
	Pause the current animation.
void	Resume ()
	Resume previous paused animation.
int	Save (int idDPF, char *typeblock="SPR2")
	Save this sprite to a DPF(using an idDPF).
int	Save (char *fileDPF, char *typeblock="SPR2")
	Save this sprite to a DPF(using a filename).
unsigned char	SelectAnim (int status)
	Select an animation state.
unsigned char	SelectFrame (int iFrame)
	Select a frame as current one.
void	SetAlpha (int shade)
	Set the alpha per-surface.
void	SetAnimFactor (float fRs)
	Set animation factor speed.
unsigned char	SetAnimProperties (int iAnim, unsigned short iType=SPRANIM_KEEP_PROPERTIES, unsigned short iStatus=SPRANIM_KEEP_PROPERTIES, signed short iHotX=SPRANIM_KEEP_PROPERTIES, signed short iHotY=SPRANIM_KEEP_PROPERTIES, unsigned short iStartFrame=SPRANIM_KEEP_PROPERTIES, unsigned short iEndFrame=SPRANIM_KEEP_PROPERTIES)
	Set the animation properties.
void	SetCollisionMethod (int mode)
	Set collision method only for this sprite.
void	SetColorKey (int CKey)
	Set a colorkey using a packed integer.
void	SetColorKey (int r, int g, int b)
	Set a colorkey using RGB values.
void	SetEffect (int effect, int smooth=0, double dParam1=0.0, double dParam2=0.0)
	Set a special effect.
unsigned char	SetFrameProperties (int iAnim, int iFrame, unsigned int iMs)
	Set frame properties.
void	SetName (char *name)
	Set a new name for the sprite.
void	SetPosition (int x, int y, int smooth=0)
	Set the sprite position.

---

Member Function Documentation

void CRM32Pro_CSprite::AutoRestore

(

char

value

)

Enable or disable auto background restore.

This setting will override previous auto restore value.
If you used ACCEL_HARDSMOOTH(which will try to set a double-buffer) acceleration mode, it is disabled by default.
On other modes, is enabled by default.
So, if you are blitting and updating *all* your graphics stuff, you should disable the auto restore to avoid non-desidered effects and to help to improve the performance a little bit. OpenGL modes will disable this feature and avoid to enable it.

Parameters:

value

0 to disable auto restore, any value to enable it.

Examples:

Example08_SpriteCollision.cpp, and Example09_LogicRenderRates.cpp.

void CRM32Pro_CSprite::Clean

(

)

Clean and reset the content of current sprite.

Useful to reuse the sprite object with another one without use 'delete' and 'new' memory operators.

int CRM32Pro_CSprite::Clone

(

CRM32Pro_CSprite *

pSpr

)

Create a new slave sprite from the given master sprite.

These values will inherit from the given master:

• Animation factor speed
• Sprite name
• Auto restore
• Screen position
• Status: playing or paused
• Alpha value
• Colorkey value
• All animations properties with all its frames

Once the slave sprite is created, you can modify all these values to customize the new created sprite without affect to the master one.
The only thing the slave and the master will share is the surface which contains all the animations and frames.
This is the advantage of cloned sprites, they do not waste memory (RAM or VideoRAM) duplicating the same surface.
Due to this, a slave sprite can not work if its father was removed or cleaned, so do not remove or clean a master sprite if it has slaves ones.

Parameters:

pSpr

pointer to a master sprite to create a clone of it

Returns:

0 Failed

any other value, new sprite created successfully and it returns the number of animations

Examples:

Example09_LogicRenderRates.cpp.

int CRM32Pro_CSprite::Collision	(	SDL_Surface *	surf,
		SDL_Rect *	rect,
		short	this_spr_x = -1,
		short	this_spr_y = -1,
		unsigned char	debug = 0
	)

Check collision with a given surface.

Parameters:

	surf	Pointer to a surface
	rect	pointer to a rect with absolute (x,y) position(on screen and/or on your own coordinates system) and size of the surface
	this_spr_x	by default is -1 to use current screen X position for this sprite. Other value, only means your absolute X position on your own system coordinates
	this_spr_y	by default is -1 to use current screen Y position for this sprite. Other value, only means your absolute Y position on your own system coordinates
	debug	0(by default) won't render any debug information. Otherwise, will show collision bounding boxes.

Returns:

0 There was not a surface collision

1 There was a surface collision

int CRM32Pro_CSprite::Collision	(	CRM32Pro_CSprite *	spr,
		short	spr_x = -1,
		short	spr_y = -1,
		short	this_spr_x = -1,
		short	this_spr_y = -1,
		unsigned char	debug = 0
	)

Check collision with another sprite.

It will use the method selected by SetCollisionMethod()

Parameters:

	spr	Pointer to another sprite
	spr_x	by default is -1 to use current screen X position for the sprite 'spr'. Other value, only means your absolute X position on your own system coordinates
	spr_y	by default is -1 to use current screen Y position for the sprite 'spr'. Other value, only means your absolute Y position on your own system coordinates
	this_spr_x	by default is -1 to use current screen X position for this sprite. Other value, only means your absolute X position on your own system coordinates
	this_spr_y	by default is -1 to use current screen Y position for this sprite. Other value, only means your absolute Y position on your own system coordinates
	debug	by default is 0 and it won't render any debug information. Otherwise, it will show bounding box and so on

Returns:

0 There was not a surface collision

1 There was a surface collision

Examples:

Example08_SpriteCollision.cpp.

int CRM32Pro_CSprite::Create	(	SDL_Surface *	sprSurface,
		char *	namespr,
		int	OffX,
		int	OffY
	)

Create a master sprite from a surface.

It holds the alpha blending information (per-pixel or per-surface) and the colorkey of the given surface.
Note that all frames must have the same size.

Parameters:

	sprSurface	pointer to SDL_Surface with a valid surface for the sprite
	namespr	sprite name
	OffX	size X for each frame
	OffY	size Y for each frame

Returns:

0 Failed

any other value, Ok and number of animations

int CRM32Pro_CSprite::Create	(	char *	filename,
		char *	namespr,
		int	OffX,
		int	OffY
	)

Create a master sprite from an external image file(BMP/PNG).

By default, alpha per surface and colorkey are disabled. If you want to use it, you must set it after the sprite creation.
But if your PNG already has alpha per-pixel information, it will be automatically used. Note that all frames must have the same size.

Parameters:

	filename	Image file name, with its full path, containing the sprite
	namespr	Desired sprite name
	OffX	size X for each frame
	OffY	size Y for each frame

Returns:

0 Failed

any other value, Ok and number of animations

int CRM32Pro_CSprite::Draw

(

SDL_Surface *

dumpto = NULL

)

Draw sprite (current frame of current animation with the selected special effect).

Parameters:

dumpto

by default, draw to 'CRM32Pro.screen' surface

Returns:

0 if failed

1 if a new frame was drawn

2 if the same frame was drawn

3 if the sprite is paused

Examples:

Example08_SpriteCollision.cpp, and Example09_LogicRenderRates.cpp.

int CRM32Pro_CSprite::GetAlpha

(

)

Get alpha blending information.

To extend the information about the alpha blending, you can read How SDL Alpha works (based on SDL documentation).

Returns:

-1 Failed

From 0(transparent) to 254(almost full opaque) and alpha per-surface enabled

255 Alpha per-surface disabled

256 Alpha per-pixel enabled

int CRM32Pro_CSprite::GetAnim

(

)

Get current animation state.

You can use GetSpriteHighState() and GetSpriteLowState() macros to get separate high-state and low-state.

Returns:

-1 Failed

Any other positive value, the current animation state containing high-state and low-state

void CRM32Pro_CSprite::GetAnimProperties	(	int	which,
		unsigned short *	type = NULL,
		unsigned short *	status = NULL,
		unsigned short *	frames = NULL,
		signed short *	hotx = NULL,
		signed short *	hoty = NULL,
		unsigned short *	startframe = NULL,
		unsigned short *	endframe = NULL
	)

Get the properties of an animation.

If the pointer to store a property is NULL

Parameters:

	which	the desired animation (from 1 to number of animations)
	type	pointer to an integer to get the animation type. By default, this parameter is NULL to don't get anything.
	status	pointer to an integer to get the animation state. By default, this parameter is NULL to don't get anything.
	frames	pointer to an integer to get total number of frames. By default, this parameter is NULL to don't get anything.
	hotx	pointer to an integer to get the X hotspot. By default, this parameter is NULL to don't get anything.
	hoty	pointer to an integer to get the Y hotspot. By default, this parameter is NULL to don't get anything.
	startframe	pointer to an integer to get the start frame. By default, this parameter is NULL to don't get anything.
	endframe	pointer to an integer to get the end frame. By default, this parameter is NULL to don't get anything.

int CRM32Pro_CSprite::GetCollisionMethod

(

)

Get current collision method of this sprite.

Returns:

Current collision method

int CRM32Pro_CSprite::GetColorKey

(

)

Get the current color key.

To unpack the returned value to independent RGB values, you can use SDL_GetRGB().

Returns:

-1 Colorkey disabled

Any other positive or 0 value, packed colorkey on an integer.

int CRM32Pro_CSprite::GetFrame

(

)

Get current frame number.

Returns:

-1 Failed

Any other positive value, the current frame number of current animation

void CRM32Pro_CSprite::GetFrameProperties	(	int	iAnim,
		int	iFrame,
		unsigned int *	ms = NULL
	)

Get the frame properties.

Parameters:

	iAnim	animation that contains the desired frame (from 1 to number of animations)
	iFrame	the desired frame to set its properties (from 1 to number of frames)
	ms	pointer to an integer to get the milliseconds of the desired frame. By default, this parameter is NULL to don't get anything.

char * CRM32Pro_CSprite::GetName

(

)

Get the sprite name.

Returns:

a pointer to sprite name

void CRM32Pro_CSprite::GetOffset	(	int *	x,
		int *	y
	)

Get X(width) and/or Y(height) size for each frame.

Parameters:

	x	pointer to an integer to store the width for each frame. NULL if you do not want to query it.
	y	pointer to an integer to store the height for each frame. NULL if you do not want to query it

Examples:

Example09_LogicRenderRates.cpp.

int CRM32Pro_CSprite::GetPosX

(

)

Get X position of the sprite.

Returns:

x position of the sprite.

int CRM32Pro_CSprite::GetPosY

(

)

Get Y position of the sprite.

Returns:

y position of the sprite..

SDL_Surface * CRM32Pro_CSprite::GetSurface

(

)

Get sprite surface.

A slave sprite will return the father's surface.

Returns:

pointer to SDL_Surface of sprite

unsigned char CRM32Pro_CSprite::IsFinished

(

)

Has finished the animation?

Note that this function only has sense with OneShot type animation. In case you want to start it again, you can use SelectFrame(0).

Returns:

0 The animation is running

1 The animation is over

int CRM32Pro_CSprite::Load	(	int	idDPF,
		char *	namespr,
		char *	typeblock = "SPR2"
	)

Load a master sprite from a DPF(using an idDPF).

Parameters:

	idDPF	ID of the opened DPF
	namespr	sprite name
	typeblock	by default is "SPR2", don't change it unless you know what you are doing

Returns:

0 if failed

any other integer, ok and number of animations

int CRM32Pro_CSprite::Load	(	char *	fileDPF,
		char *	namespr,
		char *	typeblock = "SPR2"
	)

Load a master sprite from a DPF(using a filename).

Parameters:

	fileDPF	name and optional path of a DPF that contains the sprite
	namespr	sprite name
	typeblock	by default is "SPR2", don't change it unless you know what you are doing

Returns:

0 if failed

any other integer, ok and number of animations

Examples:

Example08_SpriteCollision.cpp, and Example09_LogicRenderRates.cpp.

int CRM32Pro_CSprite::Save	(	int	idDPF,
		char *	typeblock = "SPR2"
	)

Save this sprite to a DPF(using an idDPF).

Parameters:

	idDPF	ID of the opened DPF
	typeblock	by default is "SPR2", don't change it unless you know what you are doing

Returns:

-1 Sprite already exists.

0 Failed.

any other positive value, Ok and packed size of the added sprite

int CRM32Pro_CSprite::Save	(	char *	fileDPF,
		char *	typeblock = "SPR2"
	)

Save this sprite to a DPF(using a filename).

Parameters:

	fileDPF	name and optional path of a DPF to store this sprite
	typeblock	by default is "SPR2", don't change it unless you know what you are doing

Returns:

-1 Sprite already exists.

0 Failed.

any other positive value, Ok and packed size of the added sprite

unsigned char CRM32Pro_CSprite::SelectAnim

(

int

state

)

Select an animation state.

Use the high-state(see definition of SPRSTATE_xx) together with your own low-state to select an animation state.

Parameters:

state

integer with desired animation state. For example, SPRSTATE_NORMAL + 1.

Returns:

0 Failed

1 Ok

unsigned char CRM32Pro_CSprite::SelectFrame

(

int

iFrame

)

Select a frame as current one.

In animation with SPRANIM_ONESHOT type, you can restart the animation selecting again your start frame number. Note there is a valid interval: from startFrame to endFrame. The selected frame number will be adapted to that interval.

Parameters:

iFrame

integer with the frame number

Returns:

0 if failed or 1 if Ok

void CRM32Pro_CSprite::SetAlpha

(

int

shade

)

Set the alpha per-surface.

A surface with enabled alpha blending(per-pixel or per-surface) will be never created on video memory if alpha blending is not supported by the hardware. Right now, only glSDL supports it.
With per-pixel alpha, per-surface alpha is useless, so any attempt to activate it will be ignored.

Note that enabling and disabling the alpha blending on the execution time could slowdown your graphic performance.
To extend the information about the alpha blending, you can read How SDL Alpha works (based on SDL documentation).

Parameters:

shade

integer from 0(transparent) to 254(almost full opaque) to enable the per-surface alpha or 255(full opaque) to disable it.

void CRM32Pro_CSprite::SetAnimFactor

(

float

fRs

)

Set animation factor speed.

Parameters:

fRs

float number setting the relative animation speed,ex: 0.5 will be 50% slower.

unsigned char CRM32Pro_CSprite::SetAnimProperties	(	int	iAnim,
		unsigned short	iType = SPRANIM_KEEP_PROPERTIES,
		unsigned short	iStatus = SPRANIM_KEEP_PROPERTIES,
		signed short	iHotX = SPRANIM_KEEP_PROPERTIES,
		signed short	iHotY = SPRANIM_KEEP_PROPERTIES,
		unsigned short	iStartF = SPRANIM_KEEP_PROPERTIES,
		unsigned short	iEndF = SPRANIM_KEEP_PROPERTIES
	)

Set the animation properties.

Parameters:

	iAnim	animation to set properties (from 1 to number of animations)
	iType	set animation type. See definition of SPRANIM_LOOP,SPRANIM_PINGPONG and SPRANIM_ONESHOT. Use SPRANIM_KEEP_PROPERTIES to maintain current setting (it's also the value by default).
	iStatus	set the animation state. Use high-state only as the low-state is automatically generated. Use SPRANIM_KEEP_PROPERTIES to maintain current setting (it's also the value by default).
	iHotX	set the X hotspot for this animation. Use SPRANIM_KEEP_PROPERTIES to maintain current setting (it's also the value by default).
	iHotY	set the Y hotspot for this animation. Use SPRANIM_KEEP_PROPERTIES to maintain current setting (it's also the value by default).
	iStartF	set the start frame for this animation. Use SPRANIM_KEEP_PROPERTIES to maintain current setting (it's also the value by default).
	iEndF	set the end frame for this animation. Use SPRANIM_KEEP_PROPERTIES to maintain current setting (it's also the value by default).

Returns:

0 Failed

1 Ok

void CRM32Pro_CSprite::SetCollisionMethod

(

int

mode

)

Set collision method only for this sprite.

Using this method you could adjust the kind of accuracy Vs speed only for this sprite
By default, the mode is set to -1 to use the same method of the IPrimitives system.

Parameters:

mode

-1 to use the same method of the IPrimitives system. 0 to set a very fast boundingbox(less acurrate but extremley fast) 1 to set a perfect pixel collision(100% accurate but the slowest method) 2, 3, 4, .. to set the collision check each 2, 3, 4, ... pixels.

void CRM32Pro_CSprite::SetColorKey

(

int

CKey

)

Set a colorkey using a packed integer.

To pack the integer with RGB values, you can use SDL_MapRGB().
With alpha per pixel, colorkey is useless.
In OpenGL mode (glSDL), changing the colorkey after loading/creating the sprite could slowdown your graphic performance.

Parameters:

CKey

packed integer with colorkey. You can also use -1 to disable colorkey.

void CRM32Pro_CSprite::SetColorKey	(	int	r,
		int	g,
		int	b
	)

Set a colorkey using RGB values.

With alpha per pixel, colorkey is useless.
In OpenGL mode (glSDL), changing the colorkey after loading/creating the sprite could slowdown your graphic performance.

Parameters:

	r	red component (0-255). -1 to disable colorkey.
	g	green component (0-255). -1 to disable colorkey.
	b	blue component (0-255). -1 to disable colorkey.

void CRM32Pro_CSprite::SetEffect	(	int	effect,
		int	smooth = 0,
		double	dParam1 = 0.0,
		double	dParam2 = 0.0
	)

Set a special effect.

Parameters:

	effect	See SPREFFECT_xx definitions
	smooth	0 to do nothing. 1 to perform anti-aliasing filter(best quality and slower). It has no sense on 8bits surfaces.
	dParam1	With SPREFFECT_RESIZE, the resize factor in X axis. With SPREFFECT_ROTATE and SPREFFECT_ROTATERESIZE, the rotation in degrees.
	dParam2	With SPREFFECT_RESIZE, the resize factor in Y axis. With SPREFFECT_ROTATERESIZE, the resize factor on X/Y axes.

unsigned char CRM32Pro_CSprite::SetFrameProperties	(	int	iAnim,
		int	iFrame,
		unsigned int	iMs
	)

Set frame properties.

Parameters:

	iAnim	animation that contains the desired frame (from 1 to number of animations)
	iFrame	the desired frame to set its properties (from 1 to number of frames)
	iMs	duration in ms of the desired frame

Returns:

0 if failed or 1 if Ok

void CRM32Pro_CSprite::SetName

(

char *

name

)

Set a new name for the sprite.

Parameters:

name

pointer to the new name. Maximum of 31 characters.

void CRM32Pro_CSprite::SetPosition	(	int	x,
		int	y,
		int	smooth = 0
	)

Set the sprite position.

Although you are using the smooth movement, the first position on a fixed screen or each time your scroll does a movement, set the position with instant effect to avoid a wrong smooth movement.

Parameters:

	x	desired new X coordinate
	y	desired new Y coordinate
	smooth	0 or negative value, set the position with instant effect on the next Render Frame update. This is the value by default. Any other positive value, set the position with progressive effect on next Render Frames update causing a very smooth movement. In addition, to get this smooth movement you will have to use CRM32Pro_Main::SetRenderCallback()

Examples:

Example08_SpriteCollision.cpp, and Example09_LogicRenderRates.cpp.

---

The documentation for this class was generated from the following files:

• CRM32Pro.h
• 12_SpriteEngine.cpp