Detailed Description

v2.00 (30 Jun 2023)
The TileEngine Core module includes the TileEngine Manager and TileEngine Objects for handling all operations with the TileEngine.


Developed from scratch but based on the old MSTE for CRM32Pro, the TileEngine is a 2D graphics engine that enables you to create tile-based games on a very easy and powerful way.

Features:

	Level (the top level entity created by 1 or more layers):
	Orthogonal view.
	Any number of layers. It can also be modified at runtime.
	Viewport and render screen can be modified at runtime.
	Layers can be independent or group fixed supporting standard scroll or parallax scroll.
	Auto-scrolling capabilities.

	Layer (contains the tile-based data among other features):
	Can have any width and/or height (number of cells).
	Can have any cell size.
	Can use any number of tilesets and each one can be of any size. Larger tiles than cell size will extend at the top and right.
	Alpha modulation attribute ranging from 0 (full transparent) to 255 (full opaque).
	onUpdateEnd event raised at the end of each layer update.
	onRenderEnd event raised at the end of each layer render.
	Optional Smooth scroll rendering for getting a very smooth scroll effect
	Adding your custom maps for managing any kind of data is done using C++ inheritance class
	For debugging purposes, the cell limits can be rendered showing the cell grid.

	Tilesets (contains the tiles for the layers):
	They are CRM64Pro::Tile objects. They can be stored on external files or in a CDC.

	Supported formats:
	Native XML-based file format (TEL). The TEL can be an external file or stored in a CDC.
	Import a BMP/PNG image into a layer or export a layer to a BMP/PNG external image.
	Full support for TMX files from Tiled 0.18 or greater

This is a standard manager: objects are not shared and must be unique using its name as the key, in other words, you can not create an object with the same name of another one already created.

Only a single instance of the TileEngine Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::ITileEngineMgr() method.

Note: The TileEngine 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::TileEngine
	TileEngine Object class. More...

class	CRM64Pro::TileEngineMgr
	TileEngine Manager class. More...

Functions
Sint32	CRM64Pro::TileEngine::info (Sint32 iMode=-1)
	Request TileEngine object information.

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

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

Sint32	CRM64Pro::TileEngine::allocateLayers (Sint32 iN=-1)
	Set or get the number of layers.

Sint32	CRM64Pro::TileEngine::freeLayer (Sint32 layer)
	Free a layer.

Sint32	CRM64Pro::TileEngine::freeLevel ()
	Free all resources of current level(layer maps and tilesets).

Sint32	CRM64Pro::TileEngine::logVerbosity (Sint32)
	Log verbosity control.

Sint32	CRM64Pro::TileEngine::setViewport (SDL_Rect *rect)
	Set the desired viewport.

SDL_Rect *	CRM64Pro::TileEngine::getViewport ()
	Get the current viewport.

Sint32	CRM64Pro::TileEngine::setBackgroundColor (Uint32 iRGBA)
	Set background color.

Uint32	CRM64Pro::TileEngine::getBackgroundColor ()
	Get background color.

Sint32	CRM64Pro::TileEngine::getModificationDate (string &sDate)
	Get the level modification date (last save level date).

Sint32	CRM64Pro::TileEngine::getCreationDate (string &sDate)
	Get the level creation date (first save level date).

Sint32	CRM64Pro::TileEngine::registerMapDataHandler (TE_MapBase (createInstance)(Sint32 y, Sint32 x))
	Register a new mapdata type in our factory.

Sint32	CRM64Pro::TileEngine::addCustomMapData (Sint32 layer, TE_MapBase *map)
	Add a custom mapdata.

Sint32	CRM64Pro::TileEngine::deleteCustomMapData (Sint32 layer)
	Delete the custom mapdata. The base mapdata is left without any modification.

Sint32	CRM64Pro::TileEngine::loadTileset (Sint32 tileID, Sint32 iID=-1)
	Load a tileset.

Sint32	CRM64Pro::TileEngine::loadTileset (const string &sCDCfile, const string &sTileName, Sint32 iID=-1)
	Load a tileset.

Sint32	CRM64Pro::TileEngine::loadTileset (const string &sIMGfile, const string &sTileName, Sint32 iTileWidth, Sint32 iTileHeight, Sint32 iID=-1)
	Load a tileset.

Sint32	CRM64Pro::TileEngine::unloadTileset (Sint32 iTN)
	Unload a given tileset.

Sint32	CRM64Pro::TileEngine::getTileset (Sint32 iTN)
	Get the tileset id.

Sint32	CRM64Pro::TileEngine::getTilesetSource (Sint32 iTN, string &sName)
	Get tileset source.

Sint32	CRM64Pro::TileEngine::setTilesetSource (Sint32 iTN, const string &sSource)
	Set tileset source.

Sint32	CRM64Pro::TileEngine::setLayerFlags (Sint32 layer, Sint32 iFlags, char iState=0)
	Set the layer flags.

Sint32	CRM64Pro::TileEngine::getLayerFlags (Sint32 layer)
	Get the layer flags.

Sint32	CRM64Pro::TileEngine::setLayerResControl (Sint32 layer, eTileEngineResCtrl rescontrol)
	Set layer resource control flag.

Sint32	CRM64Pro::TileEngine::getLayerResControl (Sint32 layer)
	Get layer resource control flag.

Sint32	CRM64Pro::TileEngine::setLayerAlphaMod (Sint32 layer, Sint32 alpha)
	Set layer alpha modulation used for rendering this layer.

Sint32	CRM64Pro::TileEngine::getLayerAlphaMod (Sint32 layer)
	Get layer alpha modulation.

Sint32	CRM64Pro::TileEngine::setLayerParallaxRatio (Sint32 layer, float fPRX, float fPRY)
	Set the layer parallax ratio.

Sint32	CRM64Pro::TileEngine::getLayerParallaxRatio (Sint32 layer, float fPRX, float fPRY)
	Get current layer parallax ratio.

Sint32	CRM64Pro::TileEngine::setLayerPosition (Sint32 layer, float xpos=TE_KEEP_VALUE, float ypos=TE_KEEP_VALUE)
	Set the layer absolute position (in pixels).

Sint32	CRM64Pro::TileEngine::getLayerPosition (Sint32 layer, float xpos, float ypos)
	Get the current layer position (in pixels).

Sint32	CRM64Pro::TileEngine::setLayerAutoScroll (Sint32 layer, float xspeed=TE_KEEP_VALUE, float yspeed=TE_KEEP_VALUE)
	Set the layer AutoScroll speed (in pixels per second).

Sint32	CRM64Pro::TileEngine::getLayerAutoScroll (Sint32 layer, float xspeed, float yspeed)
	Get the layer AutoScroll speed (in pixels per seconds).

Sint32	CRM64Pro::TileEngine::setLayerMapData (Sint32 layer, TE_MapBase *map)
	Assign a mapdata to the given layer.

TE_MapBase *	CRM64Pro::TileEngine::getLayerMapData (Sint32 layer)
	Get current mapdata on the layer.

Sint32	CRM64Pro::TileEngine::setLayerOnUpdateEnd (Sint32 layer, TE_OnLayerEnd myfunc)
	Set an event function(onUpdateEnd) to be called when the engine finishes to update the layer.

TE_OnLayerEnd *	CRM64Pro::TileEngine::getLayerOnUpdateEnd (Sint32 layer)
	Get current onUpdateEnd event function if any.

Sint32	CRM64Pro::TileEngine::setLayerOnRenderEnd (Sint32 layer, TE_OnLayerEnd myfunc)
	Set an event function(onRenderEnd) to be called when the engine finishes to render the layer.

TE_OnLayerEnd *	CRM64Pro::TileEngine::getLayerOnRenderEnd (Sint32 layer)
	Get current onRenderEnd event function if any.

Sint32	CRM64Pro::TileEngine::getLayerName (Sint32 layer, string &sName)
	Get the layer name.

Sint32	CRM64Pro::TileEngine::setLayerName (Sint32 layer, const string &sName)
	Set a new layer name.

Sint32	CRM64Pro::TileEngine::setLayerGridColor (Sint32 layer, Uint32 iColor)
	Set the grid color for the base mapdata.

Sint32	CRM64Pro::TileEngine::screen2LayerCell (Sint32 layer, Sint32 sx, Sint32 sy, Sint32 cx, Sint32 cy)
	Convert screen coordinates in to layer cell values.

Sint32	CRM64Pro::TileEngine::screen2LayerAbsolute (Sint32 layer, Sint32 sx, Sint32 sy, Sint32 px, Sint32 py)
	Convert screen coordinates to layer absolute values.

Sint32	CRM64Pro::TileEngine::moveLayer (Sint32 layer, float x, float y)
	Move the layer adding of subtracting the given X/Y values.

Sint32	CRM64Pro::TileEngine::update (Sint32 layer=-1)
	Update status of TileEngine.

Sint32	CRM64Pro::TileEngine::render (Sint32 layer=-1, Sint32 idRes=0)
	Render of visible layers.

Sint32	CRM64Pro::TileEngineMgr::info (Sint32 iMode=0)
	Request TileEngine Manager information.

Sint32	CRM64Pro::TileEngineMgr::create (const string &sName, Uint32 iNumLayers=3)
	Create a new TileEngine.

Sint32	CRM64Pro::TileEngineMgr::close (Sint32 idTE)
	Close and destroy a TileEngine.

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

Sint32	CRM64Pro::TileEngineMgr::setName (Sint32 idTE, const string &sName)
	Change the object name.

TileEngine *	CRM64Pro::TileEngineMgr::get (Sint32 idTE=0)
	Get a pointer to the TileEngine using its handler.

Sint32	CRM64Pro::TileEngine::importLayerFromFile (Sint32 layer, const string &sFile, Sint32 tileSizeX, Sint32 tileSizeY, float maxDevPercentage=100.0, Sint32 iCK=-1)
	Import an image file(BMP or PNG) into a layer.

Sint32	CRM64Pro::TileEngine::importLayerFromImage (Sint32 layer, Sint32 idImg, Sint32 tileSizeX, Sint32 tileSizeY, float maxDevPercentage=100.0, Sint32 iCK=-1)
	Import an image into a layer.

Sint32	CRM64Pro::TileEngine::exportLayerToFile (Sint32 layer, const string &sFile)
	Export a layer to an external PNG image.

Sint32	CRM64Pro::TileEngine::exportLayerToImage (Sint32 layer, Sint32 idImg)
	Export a layer to an image.

Sint32	CRM64Pro::TileEngineMgr::loadLevel (const string &sLevelFile, const string &sLevelName="", const string &sCDCFile="")
	Load a native format level (TileEngine Level or TEL file).

Sint32	CRM64Pro::TileEngine::saveLevel (const string &sLevelFile, const string &sLevelName="", const string &sCDCFile="")
	Save level on native format (TileEngine Level or TEL file).

Sint32	CRM64Pro::TileEngineMgr::importTMX (const string &sTMXFile)
	Import a Tiled map (TMX).

Sint32	CRM64Pro::TileEngine::exportTMX (const string &sTMXFile, const string &sLevelName="")
	Export level to a Tiled map (TMX).

Function Documentation

◆ info() [1/2]

Sint32 CRM64Pro::TileEngine::info ( Sint32 iMode = -1 )

Request TileEngine object information.

For displaying the information, it uses the default log.

Parameters

iMode -1 for displaying information of all layers or equal/greater than 0 for displaying only information of the give layer id.

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

◆ getName()

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

Get the name.

Parameters

sName a string containing the TileEngine name.

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

◆ getID()

Uint32 CRM64Pro::TileEngine::getID ( )

Get the ID.

Returns: the object ID.

◆ allocateLayers()

Sint32 CRM64Pro::TileEngine::allocateLayers ( Sint32 iN = -1 )

Set or get the number of layers.

Parameters

iN	number of layers to be allocated. With -1, returns the current number of allocated layers. If the number of current layers is lesser than iN, this method will allocate empty new layers. Otherwise it will remove needed layers using freeLayer() method.

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

◆ freeLayer()

Sint32 CRM64Pro::TileEngine::freeLayer ( Sint32 layer )

Free a layer.

If the layer has TE_RESCONTROL_USER flag, we dont free the mapdata. This have to be done at the developer preference time BUT always after call this method.
And with TE_RESCONTROL_AUTO flag, this method will remove the mapdata of the given layer.
It also reset all the layer settings and this layer slot is ready to be used. We dont remove the layer slot, use AllocateLayers() for doing that.

Parameters

layer Selected layer to free(from 0 to number of allocated layers)

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

◆ freeLevel()

Sint32 CRM64Pro::TileEngine::freeLevel ( )

Free all resources of current level(layer maps and tilesets).

It does a reset of the current level. All layers are reset but the layer slots are kept.
It holds the viewport, the level name and the number of allocated layers.

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

◆ logVerbosity()

Sint32 CRM64Pro::TileEngine::logVerbosity ( Sint32 iLevel )

Log verbosity control.

Parameters

iLevel 0 for disabling the log output, 1 for displaying only LML_CRITICAL, 2 for displaying LML_CRITICAL and LML_NORMAL, 3 for displaying all levels.

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

◆ setViewport()

Sint32 CRM64Pro::TileEngine::setViewport ( SDL_Rect * rect )

Set the desired viewport.

You can change the viewport at any time even while you are rendering your application. The width and height of the viewport can not be greater than values of the smallest layer (excluding the ones with looping flags), otherwise, it will be automatically adjusted.

Parameters

rect	Pointer to SDL_Rect with the desired viewport. If the rect width or height is 0, it will use the whole target (a valid screen or image handle).

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

◆ getViewport()

SDL_Rect * CRM64Pro::TileEngine::getViewport ( )

Get the current viewport.

Returns: Pointer to a SDL_Rect with the current viewport

◆ setBackgroundColor()

Sint32 CRM64Pro::TileEngine::setBackgroundColor ( Uint32 iRGBA )

Set background color.

Parameters

iRGBA background color to set in the format RGBA. When A is 0 (totally transparent), the background color is disabled.

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

◆ getBackgroundColor()

Uint32 CRM64Pro::TileEngine::getBackgroundColor ( )

Get background color.

Returns: the background color in format RGBA. When A is 0 (totally transparent, the background color is disabled)

◆ getModificationDate()

Sint32 CRM64Pro::TileEngine::getModificationDate ( string & sDate )

Get the level modification date (last save level date).

Parameters

sDate a string containing the date.

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

◆ getCreationDate()

Sint32 CRM64Pro::TileEngine::getCreationDate ( string & sDate )

Get the level creation date (first save level date).

Parameters

sDate a string containing the date.

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

◆ registerMapDataHandler()

Sint32 CRM64Pro::TileEngine::registerMapDataHandler ( TE_MapBase *(*)(Sint32 y, Sint32 x) createInstance )

Register a new mapdata type in our factory.

Parameters

createInstance A pointer to the static method createInstance(int,int) of a new mapdata type.

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

◆ addCustomMapData()

Sint32 CRM64Pro::TileEngine::addCustomMapData	(	Sint32	layer,
		TE_MapBase *	map
	)

Add a custom mapdata.

There are three working ways:

selected layer has not a mapdata assigned: we will call setLayerMapData()
selected layer has a mapdata: it will be migrated to the new custom mapdata.
If you want to use the new custom mapdata, you have first to remove the previous mapdata (setLayerMapdata(layer,nullptr))
selected layer has a custom mapdata: we do nothing as only support one custom mapadata per layer

Note that the added custom mapdata will use the resource control flag which currently is set on this layer.

Parameters

layer	Selected layer to try to add the custom mapdata (from 0 to number of allocated layers).
map	Pointer to the custom mapdata to be added.

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

◆ deleteCustomMapData()

Sint32 CRM64Pro::TileEngine::deleteCustomMapData ( Sint32 layer )

Delete the custom mapdata. The base mapdata is left without any modification.

Parameters

layer Selected layer to try to delete the custom mapdata (from 0 to number of allocated layers).

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

◆ loadTileset() [1/3]

Sint32 CRM64Pro::TileEngine::loadTileset	(	Sint32	tileID,
		Sint32	iID = `-1`
	)

Load a tileset.

When eTERC is set to TERC_USER: the user must remove this resource after usage
szSource is set to TE_TILESET_DEFAULT_SOURCE: if the level is saved, this tileset will be saved in the same place as the level
After loading the tileset, it'll be validated.

Parameters

tileID	tile ID.
iID	Global ID for this tileset. By default -1 to try to find a valid gID. A value of 0 is not allowed (minimum iD = 1).

Returns: greater than or equal to 0 on success(the tileset index where it was stored) or a negative error code on failure.

◆ loadTileset() [2/3]

Sint32 CRM64Pro::TileEngine::loadTileset	(	const string &	sCDCfile,
		const string &	sTileName,
		Sint32	iID = `-1`
	)

Load a tileset.

When eTERC is set to TERC_AUTO: the tileset is automatically removed after usage
szSource is set to the CDC that contains the tileset
After loading the tileset, it'll be validated.

Parameters

sCDCfile	string with CDC filename that contains the tileset.
sTileName	string with the tilename to be loaded.
iID	Global ID for this tileset. By default -1 to try to find a valid gID. A value of 0 is not allowed (minimum iD = 1).

Returns: greater than or equal to 0 on success(the tileset index where it was stored) or a negative error code on failure.

◆ loadTileset() [3/3]

Sint32 CRM64Pro::TileEngine::loadTileset	(	const string &	sIMGfile,
		const string &	sTileName,
		Sint32	iTileWidth,
		Sint32	iTileHeight,
		Sint32	iID = `-1`
	)

Load a tileset.

When eTERC is set to TERC_AUTO: the tileset is automatically removed after usage
szSource is set to the external image
After loading the tileset, it'll be validated.

Parameters

sIMGfile	string with the PNG or BMP filename.
sTileName	string with the desired tilename.
iTileWidth	integer with the tile width.
iTileHeight	integer with the tile height.
iID	Global ID for this tileset. By default -1 to try to find a valid gID. A value of 0 is not allowed (minimum iD = 1).

Returns: greater than or equal to 0 on success(the tileset index where it was stored) or a negative error code on failure.

◆ unloadTileset()

Sint32 CRM64Pro::TileEngine::unloadTileset ( Sint32 iTN )

Unload a given tileset.

The affected layers (the ones that use any tile of this tileset) will be disabled.

Parameters

iTN	Global ID or any tile of the tileset to be removed.

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

◆ getTileset()

Sint32 CRM64Pro::TileEngine::getTileset ( Sint32 iTN )

Get the tileset id.

It can be used for modifying any tileset attributes.

Parameters

iTN	Global ID or any tile of the tileset.

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

◆ getTilesetSource()

Sint32 CRM64Pro::TileEngine::getTilesetSource	(	Sint32	iTN,
		string &	sName
	)

Get tileset source.

The tileset source is used when saving the level.

Parameters

iTN	Global ID or any tile of the tileset.
sName	a string containing the tile source.

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

◆ setTilesetSource()

Sint32 CRM64Pro::TileEngine::setTilesetSource	(	Sint32	iTN,
		const string &	sSource
	)

Set tileset source.

The tileset source is used when saving the level.

Parameters

iTN	Global ID or any tile of the tileset.
sSource	New source: TE_TILESET_DEFAULT_SOURCE, a full path and filename of a CDC, PNG or BMP.

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

◆ setLayerFlags()

Sint32 CRM64Pro::TileEngine::setLayerFlags	(	Sint32	layer,
		Sint32	iFlags,
		char	iState = `0`
	)

Set the layer flags.

Parameters

layer	Number of layer(from 0 to number of allocated layers)
iFlags	See TE_LAYERFLAG_xxx defines for further information. They can be OR'ed
iState	<=0 for disabling the given bFlags or >1 for enabling it. With TE_LAYERFLAG_DISABLE it does not have sense.

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

Note: TE_LAYERFLAG_SHOWGRID only works with layers with mapdata, layers with an image are not working.

◆ getLayerFlags()

Sint32 CRM64Pro::TileEngine::getLayerFlags ( Sint32 layer )

Get the layer flags.

Parameters

layer Number of layer(from 0 to number of allocated layers)

Returns: the status flags (see TE_LAYERFLAG_xxx defines for further information) or a negative error code on failure.

◆ setLayerResControl()

Sint32 CRM64Pro::TileEngine::setLayerResControl	(	Sint32	layer,
		eTileEngineResCtrl	rescontrol
	)

Set layer resource control flag.

Parameters

layer	Selected layer to set the resource control flag (from 0 to number of allocated layers).
rescontrol	resource control. Check eTileEngineResCtrl for further information.

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

◆ getLayerResControl()

Sint32 CRM64Pro::TileEngine::getLayerResControl ( Sint32 layer )

Get layer resource control flag.

Parameters

layer Selected layer to get the current resource control flag (from 0 to number of allocated layers)

Returns: resource control (check eTileEngineResCtrl for further information) or a negative error code on failure.

◆ setLayerAlphaMod()

Sint32 CRM64Pro::TileEngine::setLayerAlphaMod	(	Sint32	layer,
		Sint32	alpha
	)

Set layer alpha modulation used for rendering this layer.

Parameters

layer	Selected layer to set the alpha value (from 0 to number of allocated layers).
alpha	It ranges from 255 (opaque) to 0 (fully transparent).

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

◆ getLayerAlphaMod()

Sint32 CRM64Pro::TileEngine::getLayerAlphaMod ( Sint32 layer )

Get layer alpha modulation.

Parameters

layer Selected layer to get the alpha value (from 0 to number of allocated layers)

Returns: It ranges from 255 (opaque) to 0 (fully transparent) or a negative error code on failure.

◆ setLayerParallaxRatio()

Sint32 CRM64Pro::TileEngine::setLayerParallaxRatio	(	Sint32	layer,
		float	fPRX,
		float	fPRY
	)

Set the layer parallax ratio.

This is the way to change the real speed of any layer without to affect the rest ones.

Parameters

layer	Selected layer to set the parallax ratio (from 0 to number of allocated layers).
fPRX	Parallax ratio on X axis. With a value of 0, this layer is independent of the others on X axis. Any other value and the layer is linked.
fPRY	Parallax ratio on Y axis. With a value of 0, this layer is independent of the others on Y axis. Any other value and the layer is linked. If any of the linked layers move, it will affect to the others using this parallax ratio as base.

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

◆ getLayerParallaxRatio()

Sint32 CRM64Pro::TileEngine::getLayerParallaxRatio	(	Sint32	layer,
		float *	fPRX,
		float *	fPRY
	)

Get current layer parallax ratio.

Parameters

layer	Selected layer to get the parallax ratio (from 0 to number of allocated layers).
fPRX	a float pointer filled in with parallax ratio on X axis. If nullptr is passed, the method ignores the retrieving of this value.
fPRY	a float pointer filled in with parallax ratio on Y axis. If nullptr is passed, the method ignores the retrieving of this value.

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

◆ setLayerPosition()

Sint32 CRM64Pro::TileEngine::setLayerPosition	(	Sint32	layer,
		float	xpos = `TE_KEEP_VALUE`,
		float	ypos = `TE_KEEP_VALUE`
	)

Set the layer absolute position (in pixels).

Changing the position of a layer will modify the position for the rest of linked ones according to each parallax ratio value and holding the "global" position.
Remember that a layer with a parallax ratio of 0.0 is independent from the others.
Requires a valid base mapdata or an image set.
There are some special flags:

TE_KEEP_VALUE: do not modify this axis value
TE_LAYERPOSITION_BEGINNING: move this layer to the beginning. In this case, the smoothing system is not used if presents.
TE_LAYERPOSITION_MIDDLE will: move this layer to the middle. In this case, the smoothing system is not used if presents.
TE_LAYERPOSITION_END: move this layer to the end. In this case, the smoothing system is not used if presents.
TE_LAYERPOSITION_CENTER: added to a position for centering it depending on current viewport

Parameters

layer	Selected layer to try to set a new position (from 0 to number of allocated layers).
xpos	Any supported flag or other value to try to move the current position on X axis.
ypos	Any supported flag or other value to try to move the current position on Y axis.

Returns: 0 on success (no change on the position), 1 on success (position changed) or a negative error code on failure.

◆ getLayerPosition()

Sint32 CRM64Pro::TileEngine::getLayerPosition	(	Sint32	layer,
		float *	xpos,
		float *	ypos
	)

Get the current layer position (in pixels).

Parameters

layer	Selected layer to get its current position (from 0 to number of allocated layers).
xpos	Pointer to float var to store the position on X axis. nullptr if you dont want to retrieve it.
ypos	Pointer to float var to store the position on Y axis. nullptr if you dont want to retrieve it.

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

◆ setLayerAutoScroll()

Sint32 CRM64Pro::TileEngine::setLayerAutoScroll	(	Sint32	layer,
		float	xspeed = `TE_KEEP_VALUE`,
		float	yspeed = `TE_KEEP_VALUE`
	)

Set the layer AutoScroll speed (in pixels per second).

Changing the AutoScroll speed of a layer will modify the same value for the rest of linked ones according to each parallax ratio value and holding the "global" position.

Parameters

layer	Selected layer to try to set the autoscroll speed (from 0 to number of allocated layers).
xspeed	TE_KEEP_VALUE will keep the current X speed. Any other value, will try to set it as current X speed.
yspeed	TE_KEEP_VALUE will keep the current Y speed. Any other value, will try to set it as current Y speed.

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

Changing speed of others layers. With ratio=0, independent layer.

◆ getLayerAutoScroll()

Sint32 CRM64Pro::TileEngine::getLayerAutoScroll	(	Sint32	layer,
		float *	xspeed,
		float *	yspeed
	)

Get the layer AutoScroll speed (in pixels per seconds).

Parameters

layer	Selected layer to get its current AutoScroll speed (from 0 to number of allocated layers).
xspeed	Pointer to float var to store the speed on X axis. nullptr if you dont want to retrieve it.
yspeed	Pointer to float var to store the speed on Y axis. nullptr if you dont want to retrieve it.

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

◆ setLayerMapData()

Sint32 CRM64Pro::TileEngine::setLayerMapData	(	Sint32	layer,
		TE_MapBase *	map
	)

Assign a mapdata to the given layer.

If the mapdata is already set, it will remove it following resource control policies (see eTileEngineResCtrl for further information)

Parameters

layer	Selected layer to try to set a new mapdata (from 0 to number of allocated layers)
map	Pointer to a valid mapdata: TE_MapBase or a derivated one. nullptr to try to remove the existing mapdata.

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

◆ getLayerMapData()

TE_MapBase * CRM64Pro::TileEngine::getLayerMapData ( Sint32 layer )

Get current mapdata on the layer.

Parameters

layer Selected layer to try to get its mapdata (from 0 to number of allocated layers).

Returns: a pointer to the TE_MapBase/derivated one or nullptr if there is not any assigned.

◆ setLayerOnUpdateEnd()

Sint32 CRM64Pro::TileEngine::setLayerOnUpdateEnd	(	Sint32	layer,
		TE_OnLayerEnd	myfunc
	)

Set an event function(onUpdateEnd) to be called when the engine finishes to update the layer.

Use nullptr if you want to remove a previous onUpdateEnd event function.

Parameters

layer	Number of layer to try to set your onUpdateEnd event function (from 0 to number of allocated layers).
myfunc	pointer to your custom event function.

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

◆ getLayerOnUpdateEnd()

TileEngine::TE_OnLayerEnd * CRM64Pro::TileEngine::getLayerOnUpdateEnd ( Sint32 layer )

Get current onUpdateEnd event function if any.

Parameters

layer Selected layer to get current onUpdateEnd event function (from 0 to number of allocated layers).

Returns: a pointer to current event function or nullptr if there is not any assigned.

◆ setLayerOnRenderEnd()

Sint32 CRM64Pro::TileEngine::setLayerOnRenderEnd	(	Sint32	layer,
		TE_OnLayerEnd	myfunc
	)

Set an event function(onRenderEnd) to be called when the engine finishes to render the layer.

Use nullptr if you want to remove a previous onRenderEnd event function.

Parameters

layer	Number of layer to try to set your onRenderEnd event function (from 0 to number of allocated layers).
myfunc	pointer to your custom event function.

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

◆ getLayerOnRenderEnd()

TileEngine::TE_OnLayerEnd * CRM64Pro::TileEngine::getLayerOnRenderEnd ( Sint32 layer )

Get current onRenderEnd event function if any.

Parameters

layer Selected layer to get current onRenderEnd event function (from 0 to number of allocated layers).

Returns: a pointer to current event function or nullptr if there is not any assigned.

◆ getLayerName()

Sint32 CRM64Pro::TileEngine::getLayerName	(	Sint32	layer,
		string &	sName
	)

Get the layer name.

Parameters

layer	Selected layer to get its name (from 0 to number of allocated layers).
sName	a string containing the layer name.

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

◆ setLayerName()

Sint32 CRM64Pro::TileEngine::setLayerName	(	Sint32	layer,
		const string &	sName
	)

Set a new layer name.

Parameters

layer	Selected layer to set its name (from 0 to number of allocated layers).
sName	The name to give to the layer e.g. 'layer0'.

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

◆ setLayerGridColor()

Sint32 CRM64Pro::TileEngine::setLayerGridColor	(	Sint32	layer,
		Uint32	iColor
	)

Set the grid color for the base mapdata.

It is used for debugging purposes

Parameters

layer	Selected layer to set the grid color (from 0 to number of allocated layers).
iColor	packed unsigned int with the color value (RGBA).

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

◆ screen2LayerCell()

Sint32 CRM64Pro::TileEngine::screen2LayerCell	(	Sint32	layer,
		Sint32	sx,
		Sint32	sy,
		Sint32 *	cx,
		Sint32 *	cy
	)

Convert screen coordinates in to layer cell values.

Parameters

layer	Selected layer (from 0 to number of allocated layers).
sx	Screen X coordinate (mouse position, etc.).
sy	Screen Y coordinate (mouse position, etc.).
cx	Point to integer where the Cell X position will be returned if this method call succeed.
cy	Point to integer where the Cell Y position will be returned if this method call succeed.

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

◆ screen2LayerAbsolute()

Sint32 CRM64Pro::TileEngine::screen2LayerAbsolute	(	Sint32	layer,
		Sint32	sx,
		Sint32	sy,
		Sint32 *	px,
		Sint32 *	py
	)

Convert screen coordinates to layer absolute values.

Parameters

layer	Selected layer (from 0 to number of allocated layers).
sx	Screen X coordinate (mouse position, etc.).
sy	Screen Y coordinate (mouse position, etc.).
px	Point to integer where the absolute X position will be returned if this method call succeed.
py	Point to integer where the absolute Y position will be returned if this method call succeed.

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

◆ moveLayer()

Sint32 CRM64Pro::TileEngine::moveLayer	(	Sint32	layer,
		float	x,
		float	y
	)

Move the layer adding of subtracting the given X/Y values.

Changing the position of a layer will modify the position of the linked ones according to each parallax ratio value and holding the "global" position.
Remember that a layer with a parallax ratio of 0.0 is independent from the others.

Parameters

layer	Selected layer to be moved (from 0 to number of allocated layers).
x	Float X value, positive or negative. 0 to do nothing.
y	Float Y value, positive or negative. 0 to do nothing.

Returns: 0 on success (no change on the position), 1 on success (position changed) or a negative error code on failure.

◆ update()

Sint32 CRM64Pro::TileEngine::update ( Sint32 layer = -1 )

Update status of TileEngine.

Only layers with TE_LAYERFLAG_UPDATE or TE_LAYERFLAG_UPDATECELLS flags will be processed.
It calculates the autoscroll if applies and some pre-calculations for the rendering of the layers.
With TE_LAYERFLAG_UPDATECELLS it will call CellUpdate() method for each visible cell.
This method should be called as part of the logic code.
Optionally, you can select the update layer order calling this method with individual layers.
At the end of each layer update, it will call to onUpdateEnd event function if exists.

Parameters

layer By default it is -1 for updating all layers from 0(background) to the number of allocated layers(foreground). Any other value for updating the given layer.

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

◆ render()

Sint32 CRM64Pro::TileEngine::render	(	Sint32	layer = `-1`,
		Sint32	idRes = `0`
	)

Render of visible layers.

Only layers with TE_LAYERFLAG_RENDER flag will be processed.
Uses the positions calculated by update() in order to render the cells.
This method should be called as part of the graphic update code.
You can select the rendering order calling this function with a selected layer.
At the end of each layer render, it will call to onRenderEnd event function if exists.
If the layer has TE_LAYERFLAG_SMOOTHSCROLL enabled, this method will interpolate values to perform a smooth scrolling movement.

Parameters

layer	By default it is -1 which means all layers will be processed. Any other value from 0(background) to number of allocated layers(foreground) will only process the given layer.
idRes	a valid screen. By default it tries to use the default screen. It does not support rendering to an image.

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

◆ info() [2/2]

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

Request TileEngine 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.
idTE for displaying Manager and given TE id information.

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

◆ create()

Sint32 CRM64Pro::TileEngineMgr::create	(	const string &	sLevelName,
		Uint32	iNumLayers = `3`
	)

Create a new TileEngine.

By default, the viewport is set to 320x200 starting at (0,0).

Parameters

sLevelName	The name to give to the the level (e.g. 'myLevel'). It is also used to set the TileEngine object name. The object name must be unique and with a maximum size of 64 characters or will be truncated.
iNumLayers	number of layers to be allocated. By default it uses 3 layers. You can use at any time allocateLayers() for dinamically increasing or decreasing this value.

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

◆ close()

Sint32 CRM64Pro::TileEngineMgr::close ( Sint32 idTE )

Close and destroy a TileEngine.

Parameters

idTE	0 for closing all TileEngine objects or the TileEngine id.

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

Note: If you forget to close a TileEngine, it will be automatically closed once the GDK is terminated.
Tileset and mapdata in layers with resouce control set to TERC_USER, are not freed by this method, they must be freed at your preference but always after calling this method.

◆ getNum()

Sint32 CRM64Pro::TileEngineMgr::getNum ( )

Get number of loaded objects.

Returns: the number of TileEngine objects.

◆ setName()

Sint32 CRM64Pro::TileEngineMgr::setName	(	Sint32	idTE,
		const string &	sName
	)

Change the object name.

Parameters

idTE	TileEngine id.
sName	The name to give to the TileEngine object (e.g. 'myTE'). 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.

◆ get()

TileEngine * CRM64Pro::TileEngineMgr::get ( Sint32 idTE = 0 )

Get a pointer to the TileEngine using its handler.

Parameters

idTE	TileEngine id. By default it returns the first TileEngine.

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

◆ importLayerFromFile()

Sint32 CRM64Pro::TileEngine::importLayerFromFile	(	Sint32	layer,
		const string &	sFile,
		Sint32	tileSizeX,
		Sint32	tileSizeY,
		float	maxDevPercentage = `100.0`,
		Sint32	iCK = `-1`
	)

Import an image file(BMP or PNG) into a layer.

It will create a new base mapdata and tileset.
The selected layer must be empty (no mapdata present).
The level name will be used for generating the layer and tileset names.

Parameters

layer	Selected layer ID (from 0 to number of allocated layers).
sFile	string containing the [directory]+filename+[BMP or PNG extension]. Directory separators '\' and '/' are supported.
tileSizeX	Tile width size to divide the given image.
tileSizeY	Tile height size to divide the given image.
maxDevPercentage	Percentage of pixels than can be different before setting an individual tile unique with respect to the others. By default it is 100% so it gets only identical tiles.
iCK	For images without alpha channel, we can select this color as the transparent one (in RGB format). By default, it is disabled (value -1).

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

Note: The new tileset created will have the same proportion size as tile sizes. There is not maximum size but when it is greater than 4096, there is a warning message as some render backend will not support these sizes.

◆ importLayerFromImage()

Sint32 CRM64Pro::TileEngine::importLayerFromImage	(	Sint32	layer,
		Sint32	idImg,
		Sint32	tileSizeX,
		Sint32	tileSizeY,
		float	maxDevPercentage = `100.0`,
		Sint32	iCK = `-1`
	)

Import an image into a layer.

It will create a new base mapdata and a new tileset.
The selected layer must be empty (no mapdata present).
The level name will be used for generating the layer and tileset names.

Parameters

layer	Selected layer ID (from 0 to number of allocated layers).
idImg	Image ID to be imported
tileSizeX	Tile width size to divide the given image.
tileSizeY	Tile height size to divide the given image.
maxDevPercentage	Percentage of pixels than can be different before setting an individual tile unique with respect to the others. By default it is 100% so it gets only identical tiles.
iCK	For images without alpha channel, we can select this color as the transparent one (in RGB format). By default, it is disabled (value -1).

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

Note: The new tileset created will have the same proportion size as tile sizes. There is not maximum size but when it is greater than 4096, there is a warning message as some render backend will not support these sizes.

◆ exportLayerToFile()

Sint32 CRM64Pro::TileEngine::exportLayerToFile	(	Sint32	layer,
		const string &	sFile
	)

Export a layer to an external PNG image.

Parameters

layer	Layer to export, from 0 to number of allocated layers or -1 to export all layers. The layer must has TE_LAYERFLAG_RENDER flag.
sFile	string containing the [directory]+filename+[extension].

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

◆ exportLayerToImage()

Sint32 CRM64Pro::TileEngine::exportLayerToImage	(	Sint32	layer,
		Sint32	idImg
	)

Export a layer to an image.

Parameters

layer	Layer to export, from 0 to number of allocated layers or -1 to export all layers. The layer must has TE_LAYERFLAG_RENDER flag.
idImg	Image ID. The image should not have assigned any surface.

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

◆ loadLevel()

Sint32 CRM64Pro::TileEngineMgr::loadLevel	(	const string &	sLevelFile,
		const string &	sLevelName = `""`,
		const string &	sCDCFile = `""`
	)

Load a native format level (TileEngine Level or TEL file).

Exiting layers and tilesets are kept, it only loads layers and tileset that are not present.
However, viewport, creation/modification dates and level name are overwritten.
It will only load the first valid base mapdata and custom mapdata (if any) found on the file.

Parameters

sLevelFile	string containing the [directory]+filename+[extension] of the TEL file. Directory separators '\' and '/' are supported.
sLevelName	string containing the level name to load as the TEL file could have more than one level. By default it loads the first level found.
sCDCFile	string containing the [directory]+filename+[extension] of a CDC file that contains the TEL file. Directory separators '\' and '/' are supported. This parameter is optional.

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

◆ saveLevel()

Sint32 CRM64Pro::TileEngine::saveLevel	(	const string &	sLevelFile,
		const string &	sLevelName = `""`,
		const string &	sCDCFile = `""`
	)

Save level on native format (TileEngine Level or TEL file).

It saves the whole level including mapdata and tilesets. If the level or tilesets exist, they are overwritten.

Parameters

sLevelFile	string containing the [directory]+filename+[extension] of the TEL file. Directory separators '\' and '/' are supported. The .tel extension will be automatically added if missing.
sLevelName	string containing the level name to be saved on TEL overwritten the current level name. By default uses the level name.
sCDCFile	string containing the [directory]+filename+[extension] of a CDC file where the TEL file will be saved to. Directory separators '\' and '/' are supported. This parameter is optional.

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

◆ importTMX()

Sint32 CRM64Pro::TileEngineMgr::importTMX ( const string & sTMXFile )

Import a Tiled map (TMX).

Supports TMX v1.10 files, orthogonal view and optional TEL properties.
It can load tileset with spacing!=0 and/or margin!=0 as internally are converted to a tileset with spacing=0 and margin=0.

Parameters

sTMXFile string containing the [directory]+filename+[extension] of the TMX file.
Directory separators '\' and '/' are supported.

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

◆ exportTMX()

Sint32 CRM64Pro::TileEngine::exportTMX	(	const string &	sTMXFile,
		const string &	sLevelName = `""`
	)

Export level to a Tiled map (TMX).

Supports TMX v1.10 files, orthogonal view and optional TEL properties.

Parameters

sTMXFile	string containing the [directory]+filename+[extension] of the TMX file. Directory separators '\' and '/' are supported.
sLevelName	string containing the level name to be saved on the TMX overwritten the current level name. By default uses the level name.

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

Detailed Description

Classes

Functions

Function Documentation

◆ info() [1/2]

◆ getName()

◆ getID()

◆ allocateLayers()

◆ freeLayer()

◆ freeLevel()

◆ logVerbosity()

◆ setViewport()

◆ getViewport()

◆ setBackgroundColor()

◆ getBackgroundColor()

◆ getModificationDate()

◆ getCreationDate()

◆ registerMapDataHandler()

◆ addCustomMapData()

◆ deleteCustomMapData()

◆ loadTileset() [1/3]

◆ loadTileset() [2/3]

◆ loadTileset() [3/3]

◆ unloadTileset()

◆ getTileset()

◆ getTilesetSource()

◆ setTilesetSource()

◆ setLayerFlags()

◆ getLayerFlags()

◆ setLayerResControl()

◆ getLayerResControl()

◆ setLayerAlphaMod()

◆ getLayerAlphaMod()

◆ setLayerParallaxRatio()

◆ getLayerParallaxRatio()

◆ setLayerPosition()

◆ getLayerPosition()

◆ setLayerAutoScroll()

◆ getLayerAutoScroll()

◆ setLayerMapData()

◆ getLayerMapData()

◆ setLayerOnUpdateEnd()

◆ getLayerOnUpdateEnd()

◆ setLayerOnRenderEnd()

◆ getLayerOnRenderEnd()

◆ getLayerName()

◆ setLayerName()

◆ setLayerGridColor()

◆ screen2LayerCell()

◆ screen2LayerAbsolute()

◆ moveLayer()

◆ update()

◆ render()

◆ info() [2/2]

◆ create()

◆ close()

◆ getNum()

◆ setName()

◆ get()

◆ importLayerFromFile()

◆ importLayerFromImage()

◆ exportLayerToFile()

◆ exportLayerToImage()

◆ loadLevel()

◆ saveLevel()

◆ importTMX()

◆ exportTMX()