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

Loading...
Searching...
No Matches
Tile
Graphics modules

## Description

Tile Manager and Tile objects for handling tiles and tilesets [v26.02.0].

### Overview

The Tile module provides management for tiles and tilesets. Tiles are smaller images of uniform, rectangular size that can be combined into larger "image maps", allowing the creation of huge game maps while saving significant memory. A collection of tiles is called a tileset, where tile dimensions are defined by X and Y offsets.

Tileset image with 12 tiles

### Key features

- Memory efficient: Combine small uniform tiles into large game maps
- Flexible tile size: Configurable tile dimensions via X and Y offsets
- Image access: Direct access to underlying Image object for advanced manipulation
- CDC storage: Load and save tilesets using CDC v1.x specification
- Cloning support: Automatic child tile creation for shared resources

### Tile operations

Tileset management | Create, load, save and manage complete tilesets
Tile access | Access individual tiles by index within a tileset
Image integration | Get Image ID to access the underlying Image object (export, alpha modulation, etc.)

### Storage layer

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

### Manager type

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

### 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

- Leverage the cloning feature to efficiently share tileset resources across multiple game objects
- Access the underlying Image object via its ID when you need to export or modify tile properties
- Use CDC archives for organized storage of multiple tilesets
- Consider tile dimensions carefully: smaller tiles offer more flexibility but require more indices
- Access the manager exclusively through Main::tileMgr()

Note
  The Tile Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::tileMgr() method.
  The Tile 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::Tile
| Tile Object class. More...
class | CRM64Pro::TileMgr
| Tile Manager class. More...

## Functions
bool | CRM64Pro::Tile::info (Sint32 iMode=0) override
| Request Tile object information.
const string & | CRM64Pro::Tile::getName () const override
| Get the name.
Sint32 | CRM64Pro::Tile::getID () const override
| Get the ID.
Sint32 | CRM64Pro::Tile::assignImage (Sint32 idImage, Sint32 iOwnership=0)
| Assign an Image to this tile.
Sint32 | CRM64Pro::Tile::getImage () const
| Get the assigned Image of this tile.
bool | CRM64Pro::Tile::setOffset (Sint32 iTSMode, Sint32 iX, Sint32 iY)
| Set tileset mode and offset.
bool | CRM64Pro::Tile::getOffset (Sint32 *iX, Sint32 *iY) const
| Get the tile offsets (tileset attributes).
bool | CRM64Pro::Tile::setPosition (float fX, float fY)
| Set the tile position.
float | CRM64Pro::Tile::getX () const
| Get the tile X position.
float | CRM64Pro::Tile::getY () const
| Get the tile Y position.
Sint32 | CRM64Pro::Tile::getTileCount (Sint32 *iX=nullptr, Sint32 *iY=nullptr) const
| Get the number of tiles.
Sint32 | CRM64Pro::Tile::render (Sint32 iTS=1, Sint32 idRes=0)
| Render the tile.
Sint32 | CRM64Pro::Tile::renderEx (Sint32 iTS=1, 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 tile with extended attributes.
Sint32 | CRM64Pro::Tile::save (const string &sCDCFile, const string &sResourceName="")
| Save the tile to a CDC file.
Sint32 | CRM64Pro::Tile::save (Sint32 idCDC, const string &sResourceName="")
| Save the tile to a CDC file.
bool | CRM64Pro::TileMgr::info (Sint32 iMode=0) override
| Request Tile Manager information.
Sint32 | CRM64Pro::TileMgr::create (const string &sName, Uint32 iVersion=10) override
| Create a new tile.
Sint32 | CRM64Pro::TileMgr::close (Sint32 idTile) override
| Close and destroy a tile.
Sint32 | CRM64Pro::TileMgr::getCount () const override
| Get number of loaded objects.
Sint32 | CRM64Pro::TileMgr::setName (Sint32 idTile, const string &sName) override
| Change the object name.
Tile * | CRM64Pro::TileMgr::get (Sint32 idTile)
| Get a pointer to the tile using its handle.
Sint32 | CRM64Pro::TileMgr::child (Sint32 idTile)
| Create a child tile dependent on the provided one (the parent).
Sint32 | CRM64Pro::TileMgr::load (const string &sCDCFile, const string &sName)
| Load a tile stored in a CDC file.
Sint32 | CRM64Pro::TileMgr::load (Sint32 idCDC, const string &sName)
| Load a tile stored in a CDC file.
Sint32 | CRM64Pro::TileMgr::loadFromBuffer (const void *pBuffer, Sint32 iSize, const string &sName, Uint32 iW=0, Uint32 iH=0)
| Load a tileset from an image memory buffer.
Sint32 | CRM64Pro::TileMgr::remove (Sint32 idCDC, const string &sName)
| Remove a tile stored in a CDC file.
bool | CRM64Pro::TileMgr::exists (Sint32 idCDC, const string &sName) const
| Check if a tile is stored in a CDC file.
bool | CRM64Pro::TileMgr::exists (const string &sCDCFile, const string &sName) const
| Check if a tile is stored in a CDC file.

## Function Documentation

## ◆ info() [1/2]

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

Request Tile object information.

Writes information to the default log.

Parameters

  iMode | Reserved for future use. Pass 0.

Returns
  true on success, or false on failure.

## ◆ getName()

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

Get the name.

Returns
  The object name.

## ◆ getID()

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

Get the ID.

Returns
  Object ID.

## ◆ assignImage()

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

Assign an Image to this tile.

Used for loading an Image when the tile is created with TileMgr::create().

Parameters

  idImage | Image id.
  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::Tile::getImage | ( |  | ) | const

Get the assigned Image of this tile.

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

## ◆ setOffset()

bool CRM64Pro::Tile::setOffset | ( | Sint32 | iTSMode,
|  | Sint32 | iX,
|  | Sint32 | iY )

Set tileset mode and offset.

In tileset mode, the image is divided by iX on X axis and by iY on Y axis. Non-exact divisions are allowed; remainder parts are unused.

Parameters

  iTSMode | 0 for disable tileset mode or 1 for enable it.
  iX | tileset offset X.
  iY | tileset offset Y.

Returns
  true on success, or false on failure.

## ◆ getOffset()

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

Get the tile offsets (tileset attributes).

Parameters

  iX | an integer pointer filled in with tileset offset X. If nullptr is passed, the method ignores the retrieving of this value.
  iY | an integer pointer filled in with tileset offset Y. If nullptr is passed, the method ignores the retrieving of this value.

Returns
  true when tileset mode is enabled, or false otherwise.

## ◆ setPosition()

bool CRM64Pro::Tile::setPosition | ( | float | fX,
|  | float | fY )

Set the tile position.

Parameters

  fX | tile X position.
  fY | tile Y position.

Returns
  true on success, or false on failure.

## ◆ getX()

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

Get the tile X position.

Returns
  The tile X position.

## ◆ getY()

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

Get the tile Y position.

Returns
  The tile Y position.

## ◆ getTileCount()

Sint32 CRM64Pro::Tile::getTileCount | ( | Sint32 * | iX = nullptr,
|  | Sint32 * | iY = nullptr ) const

Get the number of tiles.

Parameters

  iX | an integer pointer filled in with the tiles on the X axis. If nullptr is passed (default value), the method ignores the retrieving of this value.
  iY | an integer pointer filled in with the tiles on the Y axis. If nullptr is passed (default value), the method ignores the retrieving of this value.

Returns
  The total number of tiles [0, n).

## ◆ render()

Sint32 CRM64Pro::Tile::render | ( | Sint32 | iTS = 1,
|  | Sint32 | idRes = 0 )

Render the tile.

Parameters

  iTS | tile id from the current tileset. From 1 to number of tiles.
  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::Tile::renderEx | ( | Sint32 | iTS = 1,
|  | 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 tile with extended attributes.

Parameters

  iTS | tile id from the current tileset. From 1 to number of tiles.
  fScaleX | X scaling factor.
  fScaleY | Y scaling factor.
  dAngle | angle in degrees for rotation.
  pCenter | SDL_FPoint pointer indicating rotation center. Default nullptr rotates around pDst->w/2 and pDst->h/2.
  rf | "SDL_FlipMode" value for flipping actions.
  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::Tile::save | ( | const string & | sCDCFile,
|  | const string & | sResourceName = "" )

Save the tile 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 Tile object's internal name.

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

Note
  Existing tile is overwritten. Cannot save child tiles.

## ◆ save() [2/2]

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

Save the tile 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 Tile object's internal name.

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

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

## ◆ info() [2/2]

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

Request Tile 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::TileMgr::create | ( | const string & | sName,
|  | Uint32 | iVersion = 10 )
| override

Create a new tile.

Creates an empty tile (no image). Use Tile::assignImage() to assign an image.

Parameters

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

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

Note
  Returns error if name already exists.

## ◆ close()

Sint32 CRM64Pro::TileMgr::close | ( | Sint32 | idTile | ) |
| override

Close and destroy a tile.

Parameters

  idTile | 0 for closing all tiles or the Tile id. Stand-alone and child tiles can be closed but parent ones cannot as they have at least one dependency (a child).

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

Note
  If you forget to close a Tile, it will be automatically closed once the GDK is terminated.

## ◆ getCount()

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

Get number of loaded objects.

Returns
  the number of tiles.

## ◆ setName()

Sint32 CRM64Pro::TileMgr::setName | ( | Sint32 | idTile,
|  | const string & | sName )
| override

Change the object name.

Parameters

  idTile | Tile id.
  sName | The tile name (e.g. 'demoTile'). Must be unique and shorter than 64 characters.

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

## ◆ get()

Tile * CRM64Pro::TileMgr::get | ( | Sint32 | idTile | ) |

Get a pointer to the tile using its handle.

Parameters

  idTile | Tile id.

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

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

## ◆ child()

Sint32 CRM64Pro::TileMgr::child | ( | Sint32 | idTile | ) |

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

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

Parameters

  idTile | parent Tile id. If the provided tile is a child, the request is redirected to its parent.

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

Note
  The child uses the parent's name.

## ◆ load() [1/2]

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

Load a tile stored in a CDC file.

Parameters

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

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

## ◆ load() [2/2]

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

Load a tile stored in a CDC file.

Parameters

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

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

## ◆ loadFromBuffer()

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

Load a tileset from an image 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 tileset name (shorter than 64 characters).
  iW | Tile width. If 0 (default), it takes the full image width.
  iH | Tile height. If 0 (default), it takes the full image height.

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

## ◆ remove()

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

Remove a tile stored in a CDC file.

Parameters

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

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

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

## ◆ exists() [1/2]

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

Check if a tile is stored in a CDC file.

Parameters

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

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

## ◆ exists() [2/2]

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

Check if a tile is stored in a CDC file.

Parameters

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

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