| CRM64Pro GDK v0.18.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Sprite
Graphics modules

## Description

Sprite Manager and Sprite objects for handling animated sprite sheets [v26.02.0].

### Overview

The Sprite module provides management for sprites and sprite animations. Sprites are collections of smaller images of uniform, rectangular size contained on an image sprite sheet that can be animated. Each sprite sheet has associated logic that represents different animation states, types and frames with time durations.

Sprite state and animations

### Key features

- Image access: Direct access to underlying Image object for advanced manipulation
- CDC storage: Load and save sprites using CDC v1.x specification
- Cloning support: Automatic child sprite creation for shared resources

### Sprite v1.0 specification

Currently, there is one version of the Sprite Object (v1.0) with the following capabilities:

Animation states | 9 high-states with up to 255 low-states each (total: 2295 animations)
Animation types | Loop, ping-pong and one-shot
Hotspots | Configurable per animation
Frames per animation | Up to 123 frames
Frame duration | 0 to 65536 milliseconds (up to 65 seconds)

### Animation types

Loop | Animation cycles continuously from first to last frame, then restarts
Ping-pong | Animation plays forward then backward, repeating indefinitely
One-shot | Animation plays once and stops on the last frame

### Sprite operations

Sprite management | Create, load, save and manage sprite objects
Animation control | Configure states, types, frames and timing
Image integration | Get Image ID to access the underlying Image object (export, alpha modulation, etc.)

### Storage layer

Format | CDC v1.x specification
load() | Load sprite from CDC archive
save() | Save sprite to CDC archive

### Manager type

This is an advanced "cloning" manager: when loading a sprite from a CDC file that is already loaded or created (using the name as the key), it will create a new child sprite. Child sprites share base data with the parent while allowing independent animation state and playback.

### Naming security

Resource names are restricted to prevent collisions with system assets. The characters '#' and '@' are reserved for internal engine use. Any attempt to create or rename a resource starting with these characters will be rejected (returning a negative error code).

### Best practices

- Use loop type for continuous animations like walking or idle states
- Use one-shot type for actions that should play once, like attacks or death animations
- Use ping-pong type for symmetrical animations like breathing or swaying
- Set appropriate hotspots for each animation to ensure correct positioning during gameplay
- Leverage the cloning feature to efficiently share sprite resources across multiple game entities
- Access the underlying Image object via its ID when you need to export or modify sprite sheet properties
- Access the manager exclusively through Main::spriteMgr()

Note
  The Sprite Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::spriteMgr() method.
  The Sprite Manager is automatically released when Main::terminate() is called. At this time, any resource still loaded will be released, avoiding resource leaks.

## Classes
class | CRM64Pro::Sprite
| Sprite Object class. More...
class | CRM64Pro::SpriteMgr
| Sprite Manager class. More...

## Macros
#define | SPR_STATE_NORMAL 0x0000
#define | SPR_STATE_UP 0x0100
#define | SPR_STATE_DOWN 0x0200
#define | SPR_STATE_LEFT 0x0300
#define | SPR_STATE_RIGHT 0x0400
#define | SPR_STATE_UPLEFT 0x0500
#define | SPR_STATE_UPRIGHT 0x0600
#define | SPR_STATE_DOWNLEFT 0x0700
#define | SPR_STATE_DOWNRIGHT 0x0800
#define | SPR_GET_HIGHSTATE(x)
#define | SPR_GET_LOWSTATE(x)

## Enumerations
enum | CRM64Pro::eSpriteType : Uint8 { CRM64Pro::ST_LOOP = 1 , CRM64Pro::ST_PINGPONG = 2 , CRM64Pro::ST_ONESHOT = 4 , CRM64Pro::ST_ONESHOT_REVERSE = 8 , CRM64Pro::ST_RANDOM = 16 }

## Functions
bool | CRM64Pro::Sprite::info (Sint32 iMode=0) override
| Request Sprite object information.
const string & | CRM64Pro::Sprite::getName () const override
| Get the name.
Sint32 | CRM64Pro::Sprite::getID () const override
| Get the ID.
Sint32 | CRM64Pro::Sprite::assignImage (Sint32 idImage, Sint32 iOwnership=0)
| Assign an Image to this sprite.
Sint32 | CRM64Pro::Sprite::getImage () const
| Get the assigned Image of this sprite.
bool | CRM64Pro::Sprite::setOffset (Sint32 iX, Sint32 iY)
| Set the sprite offsets for creating the animations and frames.
bool | CRM64Pro::Sprite::getOffset (Sint32 *iX, Sint32 *iY) const
| Get the sprite offsets (frames and animations).
bool | CRM64Pro::Sprite::pause ()
| Pause the sprite animation.
bool | CRM64Pro::Sprite::resume ()
| Resume from a previous paused sprite animation.
eGeneralStatus | CRM64Pro::Sprite::status () const
| Get the sprite status.
bool | CRM64Pro::Sprite::setSpeed (float fSpeed)
| Set the sprite speed.
Sint32 | CRM64Pro::Sprite::getAnimCount () const
| Get number of animations.
Sint32 | CRM64Pro::Sprite::getAnimCurrent () const
| Get current animation state.
Sint32 | CRM64Pro::Sprite::getAnimCurrentIndex () const
| Get current animation index.
bool | CRM64Pro::Sprite::selectAnim (Uint16 iState)
| Select an animation by state.
bool | CRM64Pro::Sprite::selectAnimIndex (Sint32 iIndex)
| Select an animation by index.
bool | CRM64Pro::Sprite::setAnimType (Uint16 iState, eSpriteType eType)
| Set the animation type by state.
bool | CRM64Pro::Sprite::setAnimTypeIndex (Sint32 iIndex, eSpriteType eType)
| Set the animation type by index.
Sint32 | CRM64Pro::Sprite::getAnimType (Uint16 iState, eSpriteType *pType) const
| Get the animation type by state.
Sint32 | CRM64Pro::Sprite::getAnimTypeIndex (Sint32 iIndex, eSpriteType *pType) const
| Get the animation type by index.
bool | CRM64Pro::Sprite::setAnimStateIndex (Sint32 iIndex, Uint16 iState)
| Set the animation state by index.
Sint32 | CRM64Pro::Sprite::getAnimStateIndex (Sint32 iIndex, Uint16 *iState) const
| Get the animation state by index.
bool | CRM64Pro::Sprite::orderAnimState (Sint32 iState=-1)
| Sequentially re-indexes the low-state IDs for animations to ensure a contiguous sequence.
bool | CRM64Pro::Sprite::setAnimHotSpot (Uint16 iState, Sint32 iHotX, Sint32 iHotY)
| Set the animation hotspot by state.
bool | CRM64Pro::Sprite::setAnimHotSpotIndex (Sint32 iIndex, Sint32 iHotX, Sint32 iHotY)
| Set the animation hotspot by index.
Sint32 | CRM64Pro::Sprite::getAnimHotSpot (Uint16 iState, Sint32 *iHotX, Sint32 *iHotY) const
| Get the animation hotspot by state.
Sint32 | CRM64Pro::Sprite::getAnimHotSpotIndex (Sint32 iIndex, Sint32 *iHotX, Sint32 *iHotY) const
| Get the animation hotspot by index.
bool | CRM64Pro::Sprite::setAnimRange (Uint16 iState, Sint32 iFrameStart, Sint32 iFrameEnd)
| Set the animation frame range by state.
bool | CRM64Pro::Sprite::setAnimRangeIndex (Sint32 iIndex, Sint32 iFrameStart, Sint32 iFrameEnd)
| Set the animation frame range by index.
Sint32 | CRM64Pro::Sprite::getAnimRange (Uint16 iState, Sint32 *iFrameStart, Sint32 *iFrameEnd) const
| Get the animation frame range by state.
Sint32 | CRM64Pro::Sprite::getAnimRangeIndex (Sint32 iIndex, Sint32 *iFrameStart, Sint32 *iFrameEnd) const
| Get the animation frame range by index.
Sint32 | CRM64Pro::Sprite::getFrameCount (Uint16 iState) const
| Get number of frames for the given animation by state.
Sint32 | CRM64Pro::Sprite::getFrameCountIndex (Sint32 iIndex) const
| Get number of frames for the given animation by index.
Sint32 | CRM64Pro::Sprite::getFrameCurrent () const
| Get current frame number for the given animation.
bool | CRM64Pro::Sprite::selectFrame (Uint16 iState, Sint32 iFrame)
| Select a frame for the given animation by state.
bool | CRM64Pro::Sprite::selectFrameIndex (Sint32 iIndex, Sint32 iFrame)
| Select a frame for the given animation by index.
bool | CRM64Pro::Sprite::setFrameTime (Uint16 iState, Sint32 iFrame, Uint16 iTime)
| Set the frame time duration by state.
bool | CRM64Pro::Sprite::setFrameTimeIndex (Sint32 iIndex, Sint32 iFrame, Uint16 iTime)
| Set the frame time duration by index.
Sint32 | CRM64Pro::Sprite::getFrameTime (Uint16 iState, Sint32 iFrame, Uint16 *iTime) const
| Get the frame time duration by state.
Sint32 | CRM64Pro::Sprite::getFrameTimeIndex (Sint32 iIndex, Sint32 iFrame, Uint16 *iTime) const
| Get the frame time duration by index.
bool | CRM64Pro::Sprite::setPosition (float fX, float fY, bool bInterpolate=false)
| Set the sprite position.
float | CRM64Pro::Sprite::getX () const
| Get the sprite X position.
float | CRM64Pro::Sprite::getY () const
| Get the sprite Y position.
Sint32 | CRM64Pro::Sprite::render (Sint32 idRes=0)
| Render the sprite.
Sint32 | CRM64Pro::Sprite::renderEx (float fScaleX=1.0f, float fScaleY=1.0f, double dAngle=0.0, const SDL_FPoint *pCenter=nullptr, SDL_FlipMode rf=SDL_FLIP_NONE, Sint32 idRes=0)
| Render the sprite with extended options.
Sint32 | CRM64Pro::Sprite::save (const string &sCDCFile, const string &sResourceName="")
| Save the sprite to a CDC file.
Sint32 | CRM64Pro::Sprite::save (Sint32 idCDC, const string &sResourceName="")
| Save the sprite to a CDC file.
bool | CRM64Pro::SpriteMgr::info (Sint32 iMode=0) override
| Request Sprite Manager information.
Sint32 | CRM64Pro::SpriteMgr::create (const string &sName, Uint32 iVersion=10) override
| Create a new sprite.
Sint32 | CRM64Pro::SpriteMgr::close (Sint32 idSprite) override
| Close and destroy a sprite.
Sint32 | CRM64Pro::SpriteMgr::getCount () const override
| Get number of loaded objects.
Sint32 | CRM64Pro::SpriteMgr::setName (Sint32 idSprite, const string &sName) override
| Change the object name.
Sprite * | CRM64Pro::SpriteMgr::get (Sint32 idSprite)
| Get a pointer to the sprite using its handle.
Sint32 | CRM64Pro::SpriteMgr::child (Sint32 idSprite)
| Create a child sprite dependent on the provided one (the parent).
Sint32 | CRM64Pro::SpriteMgr::load (const string &sCDCFile, const string &sName)
| Load a sprite stored in a CDC file.
Sint32 | CRM64Pro::SpriteMgr::load (Sint32 idCDC, const string &sName)
| Load a sprite stored in a CDC file.
Sint32 | CRM64Pro::SpriteMgr::loadFromBuffer (const void *pBuffer, Sint32 iSize, const string &sName, Uint32 iW=0, Uint32 iH=0)
| Load a sprite and its image from a memory buffer.
Sint32 | CRM64Pro::SpriteMgr::remove (Sint32 idCDC, const string &sName)
| Remove a sprite stored in a CDC file.
bool | CRM64Pro::SpriteMgr::exists (Sint32 idCDC, const string &sName) const
| Check if a sprite is stored in a CDC file.
bool | CRM64Pro::SpriteMgr::exists (const string &sCDCFile, const string &sName) const
| Check if a sprite is stored in a CDC file.

## Macro Definition Documentation

## ◆ SPR_STATE_NORMAL

#define SPR_STATE_NORMAL 0x0000

Sprite animation high-state code: normal.

## ◆ SPR_STATE_UP

#define SPR_STATE_UP 0x0100

Sprite animation high-state code: up.

## ◆ SPR_STATE_DOWN

#define SPR_STATE_DOWN 0x0200

Sprite animation high-state code: down.

## ◆ SPR_STATE_LEFT

#define SPR_STATE_LEFT 0x0300

Sprite animation high-state code: left.

## ◆ SPR_STATE_RIGHT

#define SPR_STATE_RIGHT 0x0400

Sprite animation high-state code: right.

## ◆ SPR_STATE_UPLEFT

#define SPR_STATE_UPLEFT 0x0500

Sprite animation high-state code: up-left.

## ◆ SPR_STATE_UPRIGHT

#define SPR_STATE_UPRIGHT 0x0600

Sprite animation high-state code: up-right.

## ◆ SPR_STATE_DOWNLEFT

#define SPR_STATE_DOWNLEFT 0x0700

Sprite animation high-state code: down-left.

## ◆ SPR_STATE_DOWNRIGHT

#define SPR_STATE_DOWNRIGHT 0x0800

Sprite animation high-state code: down-right.

## ◆ SPR_GET_HIGHSTATE

#define SPR_GET_HIGHSTATE | ( |  | x | ) |

Value:
((x) & 0xFF00)

Each state is a 16-bit value; the high byte sets the high-state defined by the GDK. Use this macro to get the sprite animation high-state. See SPR_STATE_xx above.

## ◆ SPR_GET_LOWSTATE

#define SPR_GET_LOWSTATE | ( |  | x | ) |

Value:
((x) & 0x00FF)

Each state is a 16-bit value; the low byte sets the low-state [0, 255] which can be user-defined. Use this macro to get the sprite animation low-state.

## Enumeration Type Documentation

## ◆ eSpriteType

enum CRM64Pro::eSpriteType : Uint8

Sprite animation type. One value must be selected; values are not bitmask flags.

Enumerator
ST_LOOP | Plays continuously in a loop.
ST_PINGPONG | Plays continuously forward then backward.
ST_ONESHOT | Plays once and holds on the final frame.
ST_ONESHOT_REVERSE | Plays once in reverse and holds on the first frame.
ST_RANDOM | Plays continuously showing random frames.

## Function Documentation

## ◆ info() [1/2]

bool CRM64Pro::Sprite::info | ( | Sint32 | iMode = 0 | ) |
| override

Request Sprite object information.

Writes information to the default log.

Parameters

  iMode | 0 for standard output and 1 for extended output including frame times.

Returns
  true on success, or false on failure.

## ◆ getName()

const string & CRM64Pro::Sprite::getName | ( |  | ) | const
| override

Get the name.

Returns
  The object name.

## ◆ getID()

Sint32 CRM64Pro::Sprite::getID | ( |  | ) | const
| override

Get the ID.

Returns
  Object ID.

## ◆ assignImage()

Sint32 CRM64Pro::Sprite::assignImage | ( | Sint32 | idImage,
|  | Sint32 | iOwnership = 0 )

Assign an Image to this sprite.

Used for loading an Image when the sprite is created with SpriteMgr::create().

Parameters

  idImage | Image id containing the sprite sheet.
  iOwnership | 0 (default) creates a copy; any other value takes ownership (image cannot be owned by another item).

Returns
  0 on success, or a negative error code on failure.

Note
  Re-assigning closes the old image.

## ◆ getImage()

Sint32 CRM64Pro::Sprite::getImage | ( |  | ) | const

Get the assigned Image of this sprite.

Returns
  Greater than 0 on success (the Image id), or a negative error code on failure.

## ◆ setOffset()

bool CRM64Pro::Sprite::setOffset | ( | Sint32 | iX,
|  | Sint32 | iY )

Set the sprite offsets for creating the animations and frames.

Non-exact offset division is allowed; remainder parts are unused.

Parameters

  iX | offset X for creating frames. Image width is divided by this value. A scanning process detects empty frames (colorkey or alpha) to set animation end.
  iY | offset Y for creating animations and setting frame height. Image height is divided by this value.

Returns
  true on success, or false on failure.

Note
  Works on stand-alone and parent sprites; children cannot change this attribute. Start and end frames for each animation are recreated by this method.

## ◆ getOffset()

bool CRM64Pro::Sprite::getOffset | ( | Sint32 * | iX,
|  | Sint32 * | iY ) const

Get the sprite offsets (frames and animations).

Parameters

  iX | an integer pointer filled in with sprite offset X (width of each frame). If nullptr is passed, the method ignores the retrieving of this value.
  iY | an integer pointer filled in with sprite offset Y (height of each frame). If nullptr is passed, the method ignores the retrieving of this value.

Returns
  true on success, or false on failure.

## ◆ pause()

bool CRM64Pro::Sprite::pause | ( |  | ) |

Pause the sprite animation.

Returns
  true on success, or false on failure.

## ◆ resume()

bool CRM64Pro::Sprite::resume | ( |  | ) |

Resume from a previous paused sprite animation.

Returns
  true on success, or false on failure.

## ◆ status()

eGeneralStatus CRM64Pro::Sprite::status | ( |  | ) | const

Get the sprite status.

Returns
  ::GS_ENABLED when animation is enabled, ::GS_PAUSED when animation is paused, or ::GS_END when a ::ST_ONESHOT or ::ST_ONESHOT_REVERSE animation has ended.

## ◆ setSpeed()

bool CRM64Pro::Sprite::setSpeed | ( | float | fSpeed | ) |

Set the sprite speed.

Parameters

  fSpeed | float number setting the relative speed (e.g. 0.5 = 50% slower). Default 1.0.

Returns
  true on success, or false on failure.

## ◆ getAnimCount()

Sint32 CRM64Pro::Sprite::getAnimCount | ( |  | ) | const

Get number of animations.

Returns
  number of animations for this sprite.

## ◆ getAnimCurrent()

Sint32 CRM64Pro::Sprite::getAnimCurrent | ( |  | ) | const

Get current animation state.

Returns
  current animation state (high-state + low-state) or a negative error code on failure.

## ◆ getAnimCurrentIndex()

Sint32 CRM64Pro::Sprite::getAnimCurrentIndex | ( |  | ) | const

Get current animation index.

Returns
  current animation index in the [0, getAnimCount() - 1] range or a negative error code on failure.

## ◆ selectAnim()

bool CRM64Pro::Sprite::selectAnim | ( | Uint16 | iState | ) |

Select an animation by state.

Parameters

  iState | Animation state (high-state + low-state).

Returns
  true on success, or false on failure.

Note
  When a new animation is selected, it tries to keep the current frame number.

## ◆ selectAnimIndex()

bool CRM64Pro::Sprite::selectAnimIndex | ( | Sint32 | iIndex | ) |

Select an animation by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range.

Returns
  true on success, or false on failure.

Note
  When a new animation is selected, it tries to keep the current frame number.

## ◆ setAnimType()

bool CRM64Pro::Sprite::setAnimType | ( | Uint16 | iState,
|  | eSpriteType | eType )

Set the animation type by state.

Parameters

  iState | Animation state (high-state + low-state).
  eType | Animation type. See ::eSpriteType.

Returns
  true on success, or false on failure.

Note
  Works on stand-alone and parent sprites, children cannot change this attribute.

## ◆ setAnimTypeIndex()

bool CRM64Pro::Sprite::setAnimTypeIndex | ( | Sint32 | iIndex,
|  | eSpriteType | eType )

Set the animation type by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range.
  eType | Animation type. See ::eSpriteType.

Returns
  true on success, or false on failure.

Note
  Works on stand-alone and parent sprites, children cannot change this attribute.

## ◆ getAnimType()

Sint32 CRM64Pro::Sprite::getAnimType | ( | Uint16 | iState,
|  | eSpriteType * | pType ) const

Get the animation type by state.

Parameters

  iState | Animation state (high-state + low-state).
  pType | Pointer filled with the animation type. See ::eSpriteType. If nullptr is passed, this value is not retrieved.

Returns
  0 on success, or a negative error code on failure.

## ◆ getAnimTypeIndex()

Sint32 CRM64Pro::Sprite::getAnimTypeIndex | ( | Sint32 | iIndex,
|  | eSpriteType * | pType ) const

Get the animation type by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range. Use -1 for current animation.
  pType | Pointer filled with the animation type. See ::eSpriteType. If nullptr is passed, this value is not retrieved.

Returns
  0 on success, or a negative error code on failure.

## ◆ setAnimStateIndex()

bool CRM64Pro::Sprite::setAnimStateIndex | ( | Sint32 | iIndex,
|  | Uint16 | iState )

Set the animation state by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range.
  iState | Animation state (high-state + low-state). Each high-state should have unique low-state values; otherwise only the first match is used. Use orderAnimState() to reorder low-state values.

Returns
  true on success, or false on failure.

Note
  Works on stand-alone and parent sprites; children cannot change this attribute.

## ◆ getAnimStateIndex()

Sint32 CRM64Pro::Sprite::getAnimStateIndex | ( | Sint32 | iIndex,
|  | Uint16 * | iState ) const

Get the animation state by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range. Use -1 for current animation.
  iState | pointer filled with animation state (high-state + low-state).

Returns
  0 on success, or a negative error code on failure.

## ◆ orderAnimState()

bool CRM64Pro::Sprite::orderAnimState | ( | Sint32 | iState = -1 | ) |

Sequentially re-indexes the low-state IDs for animations to ensure a contiguous sequence.

This is useful for eliminating gaps in low-state IDs after removing animations or when programmatically generating animation sets.

Parameters

  iState | Animation state (high-state + low-state) for ordering. Default -1 orders all states. Assigns values 0 to n as they appear (from animation 0 to number of animations).

Returns
  true on success, or false on failure.

Note
  Works on stand-alone and parent sprites; children cannot change this attribute.

## ◆ setAnimHotSpot()

bool CRM64Pro::Sprite::setAnimHotSpot | ( | Uint16 | iState,
|  | Sint32 | iHotX,
|  | Sint32 | iHotY )

Set the animation hotspot by state.

Parameters

  iState | Animation state (high-state + low-state).
  iHotX | the x hotspot position of the animation. You can set any absolute value or a helper-packed ::PH_CENTER / ::PH_SIZE value with optional offset.
  iHotY | the y hotspot position of the animation. You can set any absolute value or a helper-packed ::PH_CENTER / ::PH_SIZE value with optional offset.

Returns
  true on success, or false on failure.

Note
  Works on stand-alone and parent sprites, children cannot change this attribute.
  Helper-packed hotspots are persisted semantically and resolved to absolute pixel hotspots internally at runtime only.

## ◆ setAnimHotSpotIndex()

bool CRM64Pro::Sprite::setAnimHotSpotIndex | ( | Sint32 | iIndex,
|  | Sint32 | iHotX,
|  | Sint32 | iHotY )

Set the animation hotspot by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range.
  iHotX | the x hotspot position of the animation. You can set any absolute value or a helper-packed ::PH_CENTER / ::PH_SIZE value with optional offset.
  iHotY | the y hotspot position of the animation. You can set any absolute value or a helper-packed ::PH_CENTER / ::PH_SIZE value with optional offset.

Returns
  true on success, or false on failure.

Note
  Works on stand-alone and parent sprites, children cannot change this attribute.
  Helper-packed hotspots are persisted semantically and resolved to absolute pixel hotspots internally at runtime only.

## ◆ getAnimHotSpot()

Sint32 CRM64Pro::Sprite::getAnimHotSpot | ( | Uint16 | iState,
|  | Sint32 * | iHotX,
|  | Sint32 * | iHotY ) const

Get the animation hotspot by state.

Parameters

  iState | Animation state (high-state + low-state).
  iHotX | pointer filled with X hotspot position. If nullptr, value is not retrieved.
  iHotY | pointer filled with Y hotspot position. If nullptr, value is not retrieved.

Returns
  0 on success, or a negative error code on failure.

## ◆ getAnimHotSpotIndex()

Sint32 CRM64Pro::Sprite::getAnimHotSpotIndex | ( | Sint32 | iIndex,
|  | Sint32 * | iHotX,
|  | Sint32 * | iHotY ) const

Get the animation hotspot by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range. Use -1 for current animation.
  iHotX | pointer filled with X hotspot position. If nullptr, value is not retrieved.
  iHotY | pointer filled with Y hotspot position. If nullptr, value is not retrieved.

Returns
  0 on success, or a negative error code on failure.

## ◆ setAnimRange()

bool CRM64Pro::Sprite::setAnimRange | ( | Uint16 | iState,
|  | Sint32 | iFrameStart,
|  | Sint32 | iFrameEnd )

Set the animation frame range by state.

Parameters

  iState | Animation state (high-state + low-state).
  iFrameStart | Start frame index in the [0, getFrameCount(iState) - 1] range. If -1 is passed, the method ignores this value.
  iFrameEnd | End frame index in the [0, getFrameCount(iState) - 1] range. If -1 is passed, the method ignores this value.

Returns
  true on success, or false on failure.

## ◆ setAnimRangeIndex()

bool CRM64Pro::Sprite::setAnimRangeIndex | ( | Sint32 | iIndex,
|  | Sint32 | iFrameStart,
|  | Sint32 | iFrameEnd )

Set the animation frame range by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range.
  iFrameStart | Start frame index in the [0, getFrameCountIndex(iIndex) - 1] range. If -1 is passed, the method ignores this value.
  iFrameEnd | End frame index in the [0, getFrameCountIndex(iIndex) - 1] range. If -1 is passed, the method ignores this value.

Returns
  true on success, or false on failure.

## ◆ getAnimRange()

Sint32 CRM64Pro::Sprite::getAnimRange | ( | Uint16 | iState,
|  | Sint32 * | iFrameStart,
|  | Sint32 * | iFrameEnd ) const

Get the animation frame range by state.

Parameters

  iState | Animation state (high-state + low-state).
  iFrameStart | Pointer filled with the start frame index, or nullptr to skip.
  iFrameEnd | Pointer filled with the end frame index, or nullptr to skip.

Returns
  0 on success, or a negative error code on failure.

## ◆ getAnimRangeIndex()

Sint32 CRM64Pro::Sprite::getAnimRangeIndex | ( | Sint32 | iIndex,
|  | Sint32 * | iFrameStart,
|  | Sint32 * | iFrameEnd ) const

Get the animation frame range by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range. Use -1 for current animation.
  iFrameStart | Pointer filled with the start frame index, or nullptr to skip.
  iFrameEnd | Pointer filled with the end frame index, or nullptr to skip.

Returns
  0 on success, or a negative error code on failure.

## ◆ getFrameCount()

Sint32 CRM64Pro::Sprite::getFrameCount | ( | Uint16 | iState | ) | const

Get number of frames for the given animation by state.

Parameters

  iState | Animation state (high-state + low-state).

Returns
  number of frames for the given animation.

## ◆ getFrameCountIndex()

Sint32 CRM64Pro::Sprite::getFrameCountIndex | ( | Sint32 | iIndex | ) | const

Get number of frames for the given animation by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range. Use -1 for current animation.

Returns
  number of frames for the given animation.

## ◆ getFrameCurrent()

Sint32 CRM64Pro::Sprite::getFrameCurrent | ( |  | ) | const

Get current frame number for the given animation.

Returns
  current frame or a negative error code on failure.

## ◆ selectFrame()

bool CRM64Pro::Sprite::selectFrame | ( | Uint16 | iState,
|  | Sint32 | iFrame )

Select a frame for the given animation by state.

Parameters

  iState | Animation state (high-state + low-state).
  iFrame | Frame index in the [0, getFrameCount(iState) - 1] range.

Returns
  true on success, or false on failure.

## ◆ selectFrameIndex()

bool CRM64Pro::Sprite::selectFrameIndex | ( | Sint32 | iIndex,
|  | Sint32 | iFrame )

Select a frame for the given animation by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range.
  iFrame | Frame index in the [0, getFrameCountIndex(iIndex) - 1] range.

Returns
  true on success, or false on failure.

## ◆ setFrameTime()

bool CRM64Pro::Sprite::setFrameTime | ( | Uint16 | iState,
|  | Sint32 | iFrame,
|  | Uint16 | iTime )

Set the frame time duration by state.

Parameters

  iState | Animation state (high-state + low-state).
  iFrame | Frame index in the [0, getFrameCount(iState) - 1] range. With -1, iTime is applied to all frames.
  iTime | duration in millisecond of this frame.

Returns
  true on success, or false on failure.

Note
  Works on stand-alone and parent sprites, children cannot change this attribute.

## ◆ setFrameTimeIndex()

bool CRM64Pro::Sprite::setFrameTimeIndex | ( | Sint32 | iIndex,
|  | Sint32 | iFrame,
|  | Uint16 | iTime )

Set the frame time duration by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range.
  iFrame | Frame index in the [0, getFrameCountIndex(iIndex) - 1] range. With -1, iTime is applied to all frames.
  iTime | duration in millisecond of this frame.

Returns
  true on success, or false on failure.

Note
  Works on stand-alone and parent sprites, children cannot change this attribute.

## ◆ getFrameTime()

Sint32 CRM64Pro::Sprite::getFrameTime | ( | Uint16 | iState,
|  | Sint32 | iFrame,
|  | Uint16 * | iTime ) const

Get the frame time duration by state.

Parameters

  iState | Animation state (high-state + low-state).
  iFrame | Frame index in the [0, getFrameCount(iState) - 1] range. Use -1 for current frame.
  iTime | duration in milliseconds of this frame.

Returns
  0 on success, or a negative error code on failure.

## ◆ getFrameTimeIndex()

Sint32 CRM64Pro::Sprite::getFrameTimeIndex | ( | Sint32 | iIndex,
|  | Sint32 | iFrame,
|  | Uint16 * | iTime ) const

Get the frame time duration by index.

Parameters

  iIndex | Animation index in the [0, getAnimCount() - 1] range. Use -1 for current animation.
  iFrame | Frame index in the [0, getFrameCountIndex(iIndex) - 1] range. Use -1 for current frame.
  iTime | duration in milliseconds of this frame.

Returns
  0 on success, or a negative error code on failure.

## ◆ setPosition()

bool CRM64Pro::Sprite::setPosition | ( | float | fX,
|  | float | fY,
|  | bool | bInterpolate = false )

Set the sprite position.

Parameters

  fX | sprite X position.
  fY | sprite Y position.
  bInterpolate | true to interpolate progressively toward the new position, false to set the position immediately on next render().

Returns
  true on success, or false on failure.

Note
  Due to interpolation nature, some graphics issues may occur. First position call should be without interpolation.

## ◆ getX()

float CRM64Pro::Sprite::getX | ( |  | ) | const

Get the sprite X position.

Returns
  The sprite X position.

## ◆ getY()

float CRM64Pro::Sprite::getY | ( |  | ) | const

Get the sprite Y position.

Returns
  The sprite Y position.

## ◆ render()

Sint32 CRM64Pro::Sprite::render | ( | Sint32 | idRes = 0 | ) |

Render the sprite.

Parameters

  idRes | a valid screen or image handle. Default uses the default screen.

Returns
  0 on success, or a negative error code on failure.

## ◆ renderEx()

Sint32 CRM64Pro::Sprite::renderEx | ( | float | fScaleX = 1.0f,
|  | float | fScaleY = 1.0f,
|  | double | dAngle = 0.0,
|  | const SDL_FPoint * | pCenter = nullptr,
|  | SDL_FlipMode | rf = SDL_FLIP_NONE,
|  | Sint32 | idRes = 0 )

Render the sprite with extended options.

Parameters

  fScaleX | X scaling factor (default 1.0f).
  fScaleY | Y scaling factor (default 1.0f).
  dAngle | angle in degrees (default 0.0).
  pCenter | rotation center (default nullptr).
  rf | flip mode (default SDL_FLIP_NONE).
  idRes | a valid screen or image handle. Default uses the default screen.

Returns
  0 on success, or a negative error code on failure.

## ◆ save() [1/2]

Sint32 CRM64Pro::Sprite::save | ( | const string & | sCDCFile,
|  | const string & | sResourceName = "" )

Save the sprite to a CDC file.

The associated image will also be saved to the same CDC file.

Parameters

  sCDCFile | string containing [directory]+filename+[extension]. Directory separators '\' and '/' are supported.
  sResourceName | Optional resource name to use in the CDC. If empty (default), uses the Sprite object's internal name.

Returns
  0 on success, or a negative error code on failure.

Note
  Existing sprite is overwritten. Cannot save child sprites.

## ◆ save() [2/2]

Sint32 CRM64Pro::Sprite::save | ( | Sint32 | idCDC,
|  | const string & | sResourceName = "" )

Save the sprite to a CDC file.

The associated image will also be saved to the same CDC file.

Parameters

  idCDC | CDC id.
  sResourceName | Optional resource name to use in the CDC. If empty (default), uses the Sprite object's internal name.

Returns
  0 on success, or a negative error code on failure.

Note
  Existing sprite is overwritten. If a child, calls parent's save method.

## ◆ info() [2/2]

bool CRM64Pro::SpriteMgr::info | ( | Sint32 | iMode = 0 | ) |
| override

Request Sprite Manager information.

Writes manager information to the default log.

Parameters

  iMode | -1 to display only manager information. 0 (default) to display manager and all objects. A specific object ID displays manager information and only that object.

Returns
  true on success, or false on failure.

## ◆ create()

Sint32 CRM64Pro::SpriteMgr::create | ( | const string & | sName,
|  | Uint32 | iVersion = 10 )
| override

Create a new sprite.

Creates an empty sprite (no image). Use Sprite::assignImage() to assign an image.

Parameters

  sName | The sprite name (e.g. 'demoSprite'). Must be unique and shorter than 64 characters.
  iVersion | Sprite version. 10 means v1.0 (only version supported). Default v1.0.

Returns
  Greater than 0 on success (the Sprite id), or a negative error code on failure.

Note
  Returns error if name already exists.

## ◆ close()

Sint32 CRM64Pro::SpriteMgr::close | ( | Sint32 | idSprite | ) |
| override

Close and destroy a sprite.

Parameters

  idSprite | 0 for closing all sprites, or specific Sprite id. Stand-alone and child sprites can be closed; parent sprites cannot while they have children.

Returns
  0 on success, or a negative error code on failure.

Note
  Unclosed sprites are automatically closed when the GDK terminates.

## ◆ getCount()

Sint32 CRM64Pro::SpriteMgr::getCount | ( |  | ) | const
| override

Get number of loaded objects.

Returns
  the number of sprites.

## ◆ setName()

Sint32 CRM64Pro::SpriteMgr::setName | ( | Sint32 | idSprite,
|  | const string & | sName )
| override

Change the object name.

Parameters

  idSprite | Sprite id.
  sName | The sprite name (e.g. 'demoSprite'). Must be unique and shorter than 64 characters.

Returns
  0 on success, or a negative error code on failure.

## ◆ get()

Sprite * CRM64Pro::SpriteMgr::get | ( | Sint32 | idSprite | ) |

Get a pointer to the sprite using its handle.

Parameters

  idSprite | Sprite id.

Returns
  Borrowed pointer to the Sprite object, or nullptr if not found.

Note
  The returned pointer must not be deleted. It remains valid until the Sprite is closed or SpriteMgr is reset or terminated.

## ◆ child()

Sint32 CRM64Pro::SpriteMgr::child | ( | Sint32 | idSprite | ) |

Create a child sprite dependent on the provided one (the parent).

A child sprite uses parent's attributes and creates a child image for different attributes.

Parameters

  idSprite | parent Sprite id. If the provided sprite is a child, the request is redirected to its parent.

Returns
  Greater than 0 on success (the Sprite id), or a negative error code on failure.

Note
  The child uses the parent's name.

## ◆ load() [1/2]

Sint32 CRM64Pro::SpriteMgr::load | ( | const string & | sCDCFile,
|  | const string & | sName )

Load a sprite stored in a CDC file.

Parameters

  sCDCFile | string containing [directory]+filename. Directory separators '\' and '/' are supported.
  sName | string with the sprite name (shorter than 64 characters). If already exists, creates a child instead.

Returns
  Greater than 0 on success (the Sprite id), or a negative error code on failure.

## ◆ load() [2/2]

Sint32 CRM64Pro::SpriteMgr::load | ( | Sint32 | idCDC,
|  | const string & | sName )

Load a sprite stored in a CDC file.

Parameters

  idCDC | CDC id.
  sName | string with the sprite name (shorter than 64 characters). If already exists, creates a child instead.

Returns
  Greater than 0 on success (the Sprite id), or a negative error code on failure.

## ◆ loadFromBuffer()

Sint32 CRM64Pro::SpriteMgr::loadFromBuffer | ( | const void * | pBuffer,
|  | Sint32 | iSize,
|  | const string & | sName,
|  | Uint32 | iW = 0,
|  | Uint32 | iH = 0 )

Load a sprite and its image from a memory buffer.

Parameters

  pBuffer | Pointer to the memory buffer containing the image (BMP or PNG).
  iSize | Size of the buffer in bytes.
  sName | string with the sprite name (shorter than 64 characters).
  iW | Frame width. If 0 (default), it takes the full image width.
  iH | Frame height. If 0 (default), it takes the full image height.

Returns
  Greater than 0 on success (the Sprite id), or a negative error code on failure.

## ◆ remove()

Sint32 CRM64Pro::SpriteMgr::remove | ( | Sint32 | idCDC,
|  | const string & | sName )

Remove a sprite stored in a CDC file.

Parameters

  idCDC | CDC id.
  sName | string with the sprite name (shorter than 64 characters).

Returns
  0 on success, or a negative error code on failure.

Note
  The sprite must be closed before trying to remove it from the CDC.

## ◆ exists() [1/2]

bool CRM64Pro::SpriteMgr::exists | ( | Sint32 | idCDC,
|  | const string & | sName ) const

Check if a sprite is stored in a CDC file.

Parameters

  idCDC | CDC id.
  sName | string with the sprite name (shorter than 64 characters).

Returns
  true if the resource is stored in the CDC file, or false otherwise. No error is reported.

Note
  It is normally used for checking whether a sprite is present without throwing any error.

## ◆ exists() [2/2]

bool CRM64Pro::SpriteMgr::exists | ( | const string & | sCDCFile,
|  | const string & | sName ) const

Check if a sprite is stored in a CDC file.

Parameters

  sCDCFile | Path to the CDC archive file.
  sName | string with the sprite name (shorter than 64 characters).

Returns
  true if the resource is stored in the CDC file, or false otherwise. No error is reported.

Note
  It is normally used for checking whether a sprite is present without throwing any error.