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::ITileMgr()

Note: The Tile Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::ITileMgr() 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.
Uint32	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, const double dAngle=0.0, const SDL_FPoint *poCenter=nullptr, const 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 (const 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.
bool	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 handler.
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 (const 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 (const Sint32 idCDC, const string &sName)
	Remove a tile stored in a CDC file.
bool	CRM64Pro::TileMgr::exist (const Sint32 idCDC, const string &sName)
	Check if a tile is stored in a CDC file.
bool	CRM64Pro::TileMgr::exist (const string &sCDCFile, const string &sName)
	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 unused for the time being.

Returns: true on success, or false on failure.

◆ getName()

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

override

Get the name.

Returns: The object name.

◆ getID()

Uint32 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, 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 and 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,
		const double	dAngle = 0.0,
		const SDL_FPoint *	poCenter = nullptr,
		const 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.
poCenter	SDL_FPoint pointer indicating rotation center. Default nullptr rotates around rDst.w/2 and rDst.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 or greater 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	(	const 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 or greater 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 information to the default log.

Parameters

iMode -1 to display only manager information. 0 (default) to display manager and all objects. Specific object ID to display manager 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. 'myTile'). Must be unique, max 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()

bool 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, can not as they have at least one dependency (a child).

Returns: true on success or false 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. 'myTile'). Must be unique, max 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 handler.

Parameters

idTile Tile id.

Returns: nullptr if tile not found.; A pointer to the tile object.

◆ 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 (max 64 characters). If already exists, creates a child instead.

Returns: 0 or greater on success (the Tile id) or a negative error code on failure.

◆ load() [2/2]

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

Load a tile stored in a CDC file.

Parameters

idCDC	CDC id.
sName	string with the tile name (max 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 (max 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: 0 or greater on success (the Tile id) or a negative error code on failure.

◆ remove()

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

Remove a tile stored in a CDC file.

Parameters

idCDC	CDC id.
sName	string with the tile name (maximum size of 64 characters).

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

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

◆ exist() [1/2]

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

Check if a tile is stored in a CDC file.

Parameters

idCDC	CDC id.
sName	string with the tile name (maximum size of 64 characters).

Returns: true on success (it exists) or false on failure (it does not exist).

◆ exist() [2/2]

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

Check if a tile is stored in a CDC file.

Parameters

sCDCFile	Path to the CDC archive file.
sName	string with the tile name (maximum size of 64 characters).

Returns: true on success (it exists) or false on failure (it does not exist).

Description

Overview

Key features

Tile operations

Storage layer

Manager type

Naming security

Best practices

Classes

Functions

Function Documentation

◆ info() [1/2]

◆ getName()

◆ getID()

◆ assignImage()

◆ getImage()

◆ setOffset()

◆ getOffset()

◆ setPosition()

◆ getX()

◆ getY()

◆ getTileCount()

◆ render()

◆ renderEx()

◆ save() [1/2]

◆ save() [2/2]

◆ info() [2/2]

◆ create()

◆ close()

◆ getCount()

◆ setName()

◆ get()

◆ child()

◆ load() [1/2]

◆ load() [2/2]

◆ loadFromBuffer()

◆ remove()

◆ exist() [1/2]

◆ exist() [2/2]