Detailed Description

v1.10 (1 May 2023)
The Tile module includes the Tile Manager and Tile for handling all the operations with tiles and tilesets.

Tiles are smaller images of uniform and rectangular size which can be combined into a larger "image map" allowing the creation of huge game maps and saving a lot of memory.
A collection of these tiles is called tileset. The tiles size are set by the offsets X and Y.

Tileset image with 12 tiles

With this manager, you can manage all common operations done in a tile set.

There is a method for getting the Image id in order to get access to the Image object, for example, you can export the tile image to an external file or modify the alpha modulation.

The storage layer(load() and save() methods) are using the CDC v1.x specification.

This is an advance "cloning" manager: when loading from a CDC file a tile which is already loaded/created (using the name as the key), it will create a new child tile.
Only a single instance of the Tile Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::ITileMgr() method.

Note: The Tile Manager is automatically released when Main::Terminate() is called.
At this time, any resource still loaded, will be released avoding resource leaks.

Classes
class	CRM64Pro::Tile
	Tile Object class. More...

class	CRM64Pro::TileMgr
	Tile Manager class. More...

Functions
Sint32	CRM64Pro::Tile::info (Sint32 iMode=0)
	Request Tile object information.

Sint32	CRM64Pro::Tile::getName (string &sName)
	Get the name.

Uint32	CRM64Pro::Tile::getID ()
	Get the ID.

Sint32	CRM64Pro::Tile::assignImage (Sint32 idImage, Sint32 iOwnership=0)
	Assign an Image to this tile.

Sint32	CRM64Pro::Tile::getImage ()
	Get the assigned Image of this tile.

Sint32	CRM64Pro::Tile::setOffset (Sint32 iTSMode, Sint32 iX, Sint32 iY)
	Set the tile offsets for creating a tileset (also enable/disable tileset mode).

Sint32	CRM64Pro::Tile::getOffset (Sint32 iX, Sint32 iY)
	Get the tile offsets (tileset attributes).

Sint32	CRM64Pro::Tile::setPosition (Sint32 iX, Sint32 iY)
	Set the tile position.

Sint32	CRM64Pro::Tile::getPosition (Sint32 iX, Sint32 iY)
	Get the tile position.

Sint32	CRM64Pro::Tile::getNumTiles (Sint32 iX=nullptr, Sint32 iY=nullptr)
	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, const double dAngle=0.0, const SDL_Point *poCenter=nullptr, const SDL_FlipMode rf=SDL_FLIP_NONE, Sint32 idRes=0)
	Render the tile.

Sint32	CRM64Pro::Tile::save (const string &sFileCDC)
	Save the tile to a CDC file.

Sint32	CRM64Pro::Tile::save (Sint32 idCDC)
	Save the tile to a CDC file.

Sint32	CRM64Pro::TileMgr::info (Sint32 iMode=0)
	Request Tile Manager information.

Sint32	CRM64Pro::TileMgr::create (const string &sName, Uint32 iVersion=10)
	Create a new tile.

Sint32	CRM64Pro::TileMgr::close (Sint32 idTile)
	Close and destroy a tile.

Sint32	CRM64Pro::TileMgr::getNum ()
	Get number of loaded objects.

Sint32	CRM64Pro::TileMgr::setName (Sint32 idTile, const string &sName)
	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 dependant on the provided one(the parent).

Sint32	CRM64Pro::TileMgr::load (const string &sFileCDC, 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::remove (const Sint32 idCDC, const string &sName)
	Remove a tile stored in a CDC file.

Function Documentation

◆ info() [1/2]

Sint32 CRM64Pro::Tile::info ( Sint32 iMode = 0 )

Request Tile object information.

For displaying the information, it uses the default log.

Parameters

iMode unused for the time being.

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

◆ getName()

Sint32 CRM64Pro::Tile::getName ( string & sName )

Get the name.

Parameters

sName a string containing the tile name.

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

◆ getID()

Uint32 CRM64Pro::Tile::getID ( )

Get the ID.

Returns: the object ID.

◆ assignImage()

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

Assign an Image to this tile.

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

Parameters

idImage	Image id.
iOwnership	0 for creating our own copy of the image or any other integer for taking the ownership of the image, in this case, the image can not be already owned by other item. By default it is set to 0.

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

Note: The image name associated to this tile will be internally modified: starts with the reserved character '#' + an internal code + the tile name.
When re-assigning a new image, the old one will be closed.

◆ getImage()

Sint32 CRM64Pro::Tile::getImage ( )

Get the assigned Image of this tile.

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

◆ setOffset()

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

Set the tile offsets for creating a tileset (also enable/disable tileset mode).

When enabling the tileset mode, the image will be divided by iX on the X axis and by iY on the Y axis.
The conversion allows to have non-exact offset division, the remainder parts of the image will not be used.

Parameters

iTSMode	0 for disabling the tileset mode or any other value for enabling it.
iX	an integer with the tileset offset X.
iY	an integer with the tileset offset Y.

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

◆ getOffset()

Sint32 CRM64Pro::Tile::getOffset	(	Sint32 *	iX,
		Sint32 *	iY
	)

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: 0 tileset mode is not enabled or 1 when it is enabled.

◆ setPosition()

Sint32 CRM64Pro::Tile::setPosition	(	Sint32	iX,
		Sint32	iY
	)

Set the tile position.

Parameters

iX	an integer with the tile X position.
iY	an integer with the tile Y position.

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

◆ getPosition()

Sint32 CRM64Pro::Tile::getPosition	(	Sint32 *	iX,
		Sint32 *	iY
	)

Get the tile position.

Parameters

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

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

◆ getNumTiles()

Sint32 CRM64Pro::Tile::getNumTiles	(	Sint32 *	iX = `nullptr`,
		Sint32 *	iY = `nullptr`
	)

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	iTile = `1`,
		Sint32	idRes = `0`
	)

Render the tile.

Parameters

iTile	tile id from the current tileset. From 1 to number of tiles.
idRes	a valid screen or image handle. By default it tries to use the default screen.

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

◆ renderEx()

Sint32 CRM64Pro::Tile::renderEx	(	Sint32	iTile = `1`,
		const double	dAngle = `0.0`,
		const SDL_Point *	poCenter = `nullptr`,
		const SDL_FlipMode	rf = `SDL_FLIP_NONE`,
		Sint32	idRes = `0`
	)

Render the tile.

Parameters

iTile	tile id from the current tileset. From 1 to number of tiles.
dAngle	an angle in degrees that indicates the rotation that will be applied.
poCenter	SDL_Point pointer indicating the point around which the tile will be rotated. By default, it is set to nullptr and the rotation will be done around rDst.w/2 and rDst.h/2.
rf	SDL_FlipMode value stating which flipping actions should be performed.
idRes	a valid screen or image handle. By default it tries to use the default screen.

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

◆ save() [1/2]

Sint32 CRM64Pro::Tile::save ( const string & sFileCDC )

Save the tile to a CDC file.

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

Parameters

sFileCDC string containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.

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

Note: If the tile already exists, it will be overwritten.
Can not save child tiles.

◆ save() [2/2]

Sint32 CRM64Pro::Tile::save ( Sint32 idCDC )

Save the tile to a CDC file.

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

Parameters

idCDC CDC id.

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

Note: If the tile already exists, it will be overwritten.
If the image is a child, it will call the save method of its parent.

◆ info() [2/2]

Sint32 CRM64Pro::TileMgr::info ( Sint32 iMode = 0 )

Request Tile Manager information.

For displaying the information, it uses the default log.

Parameters

iMode -1 for displaying only Manager information.
0 for displaying Manager and all Objects information. This is the default value.
idTile for displaying Manager and given Tile id information.

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

◆ create()

Sint32 CRM64Pro::TileMgr::create	(	const string &	sName,
		Uint32	iVersion = `10`
	)

Create a new tile.

This method will create an empty tile (no image assigned), use Tile::assignImage() method for assigning the image.

Parameters

sName	The name to give to the tile e.g. 'myTile'. The object name must be unique and with a maximum size of 64 characters or will be truncated.
iVersion	Tile version. 10 means 1.0 which is the only version supported (as of now). v1.0 is set by default.

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

Note: If the provided name already exists, it does nothing and return an error code.

◆ close()

Sint32 CRM64Pro::TileMgr::close ( Sint32 idCur )

Close and destroy a tile.

Parameters

idCur 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: 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.

◆ getNum()

Sint32 CRM64Pro::TileMgr::getNum ( )

Get number of loaded objects.

Returns: the number of tiles.

◆ setName()

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

Change the object name.

Parameters

idTile	Tile id.
sName	The name to give to the tile e.g. 'myTile'. The object name must be unique and with a maximum size of 64 characters or will be truncated.

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

Note: The image name associated to this tile will be internally modified: starts with the reserved character '#' + an internal code + the tile name.

◆ get()

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

Get a pointer to the tile using its handler.

Parameters

idTile Tile id.

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

◆ child()

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

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

A child tile uses the attributes of the parent and creates also a parent child image for having different attributes.

Parameters

idTile parent Tile id.
If the provided tile is a child, internally it will redirect this request to the parent in order to create the new child.

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

Note: The child use the parent's name.

◆ load() [1/2]

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

Load a tile stored in a CDC file.

Parameters

sFileCDC	string containing the [directory]+filename. Directory separators '\' and '/' are supported.
sName	string with the tile name (maximum size of 64 characters). If the tile is already created, this method will call child() for creating a child.

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 (maximum size of 64 characters). If the tile is already created, this method will call child() for creating a child.

Returns: greater than 0 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.

Detailed Description

Classes

Functions

Function Documentation

◆ info() [1/2]

◆ getName()

◆ getID()

◆ assignImage()

◆ getImage()

◆ setOffset()

◆ getOffset()

◆ setPosition()

◆ getPosition()

◆ getNumTiles()

◆ render()

◆ renderEx()

◆ save() [1/2]

◆ save() [2/2]

◆ info() [2/2]

◆ create()

◆ close()

◆ getNum()

◆ setName()

◆ get()

◆ child()

◆ load() [1/2]

◆ load() [2/2]

◆ remove()