MegaStorm Tile-based Engine. More...

Public Member Functions
int	AddCustomMapData (int layer, cMSTE_MapBase *map)
	Add a custom mapdata. More...

int	AllocateLayers (int iN)
	Set or get the number of layers. More...

int	DeleteCustomMapData (int layer)
	Delete the custom mapdata. The base mapdata is left without any modification. More...

int	ExportImage (int layer, SDL_Surface *&surface)
	Export a base mapdata to a surface. More...

int	ExportImage (int layer, char *filename)
	Export a base mapdata to an external image (BMP/PNG). More...

int	ExportTMX (char sTMXFilename, char sLevelname=NULL)
	Export current level to TMX 1.0 file format (Tiled Qt) More...

int	FreeLayer (int layer)
	Free a layer. More...

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

char *	GetCreationDate ()
	Get the level creation date (first save level date)

int	GetLayerAlpha (int layer)
	Get layer alpha value. More...

int	GetLayerAutoScroll (int layer, float &xspeed, float &yspeed)
	Get the layer AutoScroll speed (in pixels per seconds). More...

Uint32	GetLayerFlags (int layer)
	Get the layer flags. More...

cMSTE_MapBase *	GetLayerMapData (int layer)
	Get current mapdata on the layer. More...

char *	GetLayerName (int layer)
	Get the layer name. More...

TE_OnLayerEnd *	GetLayerOnRenderEnd (int layer)
	Get current OnRenderEnd event function if any. More...

TE_OnLayerEnd *	GetLayerOnUpdateEnd (int layer)
	Get current OnUpdateEnd event function if any. More...

float	GetLayerParallaxRatio (int layer)
	Get current layer parallax ratio. More...

int	GetLayerPosition (int layer, float &xpos, float &ypos)
	Get the current layer position (in pixels). More...

char	GetLayerResControl (int layer)
	Get layer resource control flag. More...

char *	GetModificationDate ()
	Get the level modification date (last save level date)

char *	GetName ()
	Get the level name. More...

SDL_Surface *	GetRenderTarget ()
	Get the current render target surface. More...

CRM32Pro_CTile *	GetTileset (int iTN)
	Get a pointer to the tileset. More...

char *	GetTilesetSource (int iTN)
	Get tileset source. More...

SDL_Rect *	GetViewport ()
	Get the current viewport. More...

int	ImportImage (int layer, char *fileimage, int tileSizeX, int tileSizeY, int accuracy=100, int colorkey=-1)
	Import an image file(BMP or PNG) into a base mapdata. More...

int	ImportTMX (char *sTMXFilename)
	Import a TMX 1.0 file (Tiled Qt) on current TileEngine instance. More...

void	InfoPrint (int layer=-1)
	Print to the ILogSystem information about the current engine state. More...

int	Init (int iNumLayers=3, char *levelname="")
	Initialize the engine. More...

int	LoadLevel (char sLevelFilename, char sDPF=NULL, char *sLevelname=NULL)
	Load a native format level. More...

int	LoadTileset (CRM32Pro_CTile *tiles, int iID=-1)
	Load a tileset. More...

int	LoadTileset (char sDPFfile, char sTileName, int iID=-1)
	Load a tileset. More...

int	LoadTileset (char sIMGfile, char sTileName, int iTileWidth, int iTileHeight, int iID=-1)
	Load a tileset. More...

void	LogVerbosity (int)
	Log verbosity control. More...

int	MoveLayer (int layer, float x, float y)
	Move the layer adding of subtracting the given X/Y values. More...

int	Quit ()
	Close the engine. More...

int	RegisterMapDataHandler (cMSTE_MapBase (createInstance)(int y, int x))
	Register a new mapdata type in our factory.

int	Render (int layer=-1)
	Render of visible layer cells. More...

int	SaveLevel (char sLevelFilename, char sDPF=NULL, char *sLevelname=NULL)
	Save current level on native format. More...

int	Screen2LayerAbsolute (int layer, int sx, int sy, int px, int py)
	Convert screen coordinates in to layer absolute values. More...

int	Screen2LayerCell (int layer, int sx, int sy, int cx, int cy)
	Convert screen coordinates in to layer cell values. More...

int	SetLayerAlpha (int layer, int alpha)
	Set layer alpha value. More...

int	SetLayerAutoScroll (int layer, float xspeed=TE_KEEP_VALUE, float yspeed=TE_KEEP_VALUE)
	Set the layer AutoScroll speed (in pixels per second). More...

int	SetLayerFlags (int layer, Uint32 iFlags, char iState=0)
	Set the layer flags. More...

int	SetLayerGridColor (int layer, Uint32 iColor)
	Set the grid color for the base mapdata. More...

int	SetLayerMapData (int layer, cMSTE_MapBase *map)
	Assign a mapdata to the given layer. More...

int	SetLayerName (int layer, char *name)
	Set a new layer name. More...

int	SetLayerOnRenderEnd (int layer, TE_OnLayerEnd myfunc)
	Set an event function(OnRenderEnd) to be called when the engine finishes to render the layer. More...

int	SetLayerOnUpdateEnd (int layer, TE_OnLayerEnd myfunc)
	Set an event function(OnUpdateEnd) to be called when the engine finishes to update the layer. More...

int	SetLayerParallaxRatio (int layer, float pratio)
	Set the layer parallax ratio. More...

int	SetLayerPosition (int layer, float xpos=TE_KEEP_VALUE, float ypos=TE_KEEP_VALUE)
	Set the layer absolute position (in pixels). More...

int	SetLayerResControl (int layer, char rescontrol)
	Set layer resource control flag. More...

void	SetName (char *levelname)
	Set a new level name. More...

int	SetRenderTarget (SDL_Surface *surf)
	Set the render target surface. More...

int	SetTilesetSource (int iTN, char *sSource)
	Set tileset source. More...

int	SetViewport (SDL_Rect *rect)
	Set the viewport. More...

int	UnloadTileset (int iTN)
	Unload a given tileset. More...

int	Update (int layer=-1)
	Update layer internals. More...

Friends
class	cMSTE_MapBase

Detailed Description

MegaStorm Tile-based Engine.

Main scroll engine interface.

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

Member Function Documentation

int cMSTE::AddCustomMapData	(	int	layer,
		cMSTE_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,NULL))
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 Failed; 1 Succeed

Examples:: Example04_Custom.cpp.

int cMSTE::AllocateLayers ( int iN )

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 Failed; 1 Succeed

int cMSTE::DeleteCustomMapData ( int 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 Failed; 1 Succeed

int cMSTE::ExportImage	(	int	layer,
		SDL_Surface *&	pSurf
	)

Export a base mapdata to a surface.

In case any tileset used by the base mapdata has alpha per-pixel enabled, the output will be a surface with alpha per-pixel (colorkey tilesets are automatically converted).

Parameters

layer	Layer to export, from 0 to number of allocated layers or -1 to export all layers. It requires a layer with TE_LAYERFLAG_RENDER flag and with alpha layer different to 0 (transparent)
pSurf	Surface pointer reference (must be NULL as the surface will be created by this method)

Returns: -1 Failed: TileEngine is not initialized; -2 Failed: wrong layer; -3 Failed: pSurf must be empty with a NULL value; 1 Succeed

Examples:: Example03_Load.cpp.

int cMSTE::ExportImage	(	int	layer,
		char *	filename
	)

Export a base mapdata to an external image (BMP/PNG).

In case any tileset used by the base mapdata has alpha per-pixel enabled, the output will be a surface with alpha per-pixel (colorkey tilesets are automatically converted).

Parameters

layer	Layer to export, from 0 to number of allocated layers or -1 to export all layers. It requires the layer has TE_LAYERFLAG_RENDER flag.
filename	Selected file name, the extension will set a BMP or PNG. Note that only PNG supports alpha blending information.

Returns: -1 Failed: bad parameters; -2 Failed: needed tilesets are not loaded; -3 Failed: layer has not a mapdata; -4 Failed: surface is not empty; -5 Failed: filename has not a .bmp or .png extension; 1 Succeed

int cMSTE::ExportTMX	(	char *	sTMXFilename,
		char *	sLevelname = `NULL`
	)

Export current level to TMX 1.0 file format (Tiled Qt)

We add special MSM properties.
It saves the whole level including mapdata and tilesets. If the level or tileset output files exist, they are overwritten but external images.

Parameters

sTMXFilename	Filename to save the level. The .tmx extension will be automatically added in case it was missing. It supports optional paths.
sLevelname	Optional parameter. String with the new level name overriding the existing level name.

Returns: -1 Failed: engine was not initialized.; -2 Failed: sTMXFilename is not valid.; -3 Failed: the level has not any valid layer.; -4 Failed: wrong tileset source value.; 1 Succeed

Examples:: Example05_Tiled.cpp.

int cMSTE::FreeLayer ( int 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 Failed; 1 Succeed

Examples:: Example05_Tiled.cpp.

int cMSTE::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 render target, viewport and the number of allocated layers.

Returns: 0 Failed; 1 Succeed

Examples:: Example05_Tiled.cpp.

int cMSTE::GetLayerAlpha ( int layer )

Get layer alpha value.

Parameters

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

Returns: -1 Failed; Any other value, the current alpha value from 0(transparent) to 255(opaque)

int cMSTE::GetLayerAutoScroll	(	int	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. NULL if you dont want to retrieve it.
yspeed	Pointer to float var to store the speed on Y axis. NULL if you dont want to retrieve it.

Returns: 0 Failed; 1 Succeed

Uint32 cMSTE::GetLayerFlags ( int layer )

Get the layer flags.

Parameters

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

Returns: -1 Failed; Any other number, the status flag. See TE_LAYERFLAG_xxx defines for further information

cMSTE_MapBase * cMSTE::GetLayerMapData ( int 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: NULL Failed; Any other value, a pointer to the cMSTE_MapBase or a derivated one

Examples:: Example04_Custom.cpp.

char * cMSTE::GetLayerName ( int layer )

Get the layer name.

Parameters

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

Returns: NULL Failed; Any other value, the string with its name

cMSTE::TE_OnLayerEnd * cMSTE::GetLayerOnRenderEnd ( int 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: NULL There is not any event function set.; Any other value, a pointer to current event function.

cMSTE::TE_OnLayerEnd * cMSTE::GetLayerOnUpdateEnd ( int 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: NULL There is not any event function set.; Any other value, a pointer to current event function.

float cMSTE::GetLayerParallaxRatio ( int layer )

Get current layer parallax ratio.

Parameters

layer Selected layer to get the parallax ratio (from 0 to number of allocated layers).

Returns: Current parallax ratio

int cMSTE::GetLayerPosition	(	int	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. NULL if you dont want to retrieve it.
ypos	Pointer to float var to store the position on Y axis. NULL if you dont want to retrieve it.

Returns: 0 Failed; 1 Succeed

char cMSTE::GetLayerResControl ( int 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: -1 Failed; Any other value, the current flag. See TE_RESCONTROL_xxx defines.

char * cMSTE::GetName ( )

Get the level name.

Returns: Pointer to the Level name

SDL_Surface * cMSTE::GetRenderTarget ( )

Get the current render target surface.

Returns: NULL Failed; Any other value, a pointer to current SDL_Surface

CRM32Pro_CTile * cMSTE::GetTileset ( int iTN )

Get a pointer to the tileset.

It can be used for modifying any tileset attributes

Parameters

iTN	Global ID or any tile of the tileset

Returns: NULL Failed; Pointer to CRM32Pro_CTile

char * cMSTE::GetTilesetSource ( int iTN )

Get tileset source.

The tileset source is used when saving the level

Parameters

iTN	Global ID or any tile of the tileset

Returns: NULL Failed; Pointer to char with: TE_TILESET_DEFAULT_SOURCE, a full path and filename of a DPF, PNG or BMP

SDL_Rect * cMSTE::GetViewport ( )

Get the current viewport.

Returns: NULL Failed; Any other value, a pointer to a SDL_Rect with the current viewport

int cMSTE::ImportImage	(	int	layer,
		char *	fileimage,
		int	tileSizeX,
		int	tileSizeY,
		int	accuracy = `100`,
		int	colorkey = `-1`
	)

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

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).
fileimage	Pointer to a string with path and filename of a BMP or PNG.
tileSizeX	Tile width size to divide the given image.
tileSizeY	Tile height size to divide the given image.
accuracy
colorkey	Transparent color for the given image. Useless if the surface uses alpha per pixel.

Returns: -1 Failed: bad parameters; -2 Failed: error loading image. 24bits color depth images are not supported.; -3 Failed: tileSizeX does not divide the given image; -4 Failed: tileSizeY does not divide the given image; -5 Failed: the tileset creation failed; -6 Failed: can not load the specified file image; 1 Succeed

int cMSTE::ImportTMX ( char * sTMXFilename )

Import a TMX 1.0 file (Tiled Qt) on current TileEngine instance.

We can import "raw" TMX files or with special MSM properties.
If the new layer or tileset IDs are already in use, they are not loaded, however, the viewport, creation/modification dates and the current level name are overwritten.

Parameters

sTMXFilename Filename to load the level. The .tmx extension will be automatically added in case it was missing. It supports optional paths.

Returns: -1 Failed: engine was not initialized.; -2 Failed: sTMXFilename is not valid.; -3 Failed: sTMXFilename could not be loaded.; -4 Failed: a 'map' node or main 'map' attributes were not found or were wrong.; 0 Warning: some tilesets and/or layers were not loaded. Check the log to further information.; 1 Succeed (all tilesets and layers found on the level loaded)

Examples:: Example05_Tiled.cpp.

void cMSTE::InfoPrint ( int layer = -1 )

Print to the ILogSystem information about the current engine state.

Parameters

layer Show information about given layer number(from 0 to number of allocated layers) or -1(default value) to show information about all layers.

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

int cMSTE::Init	(	int	iNumLayers = `3`,
		char *	str = `""`
	)

Initialize the engine.

Parameters

iNumLayers	Number of layers to be allocated. By default 3 layers. You can use at any time AllocateLayers() for increasing or decreasing dinamically it
str	Pointer to a string with the selected name for this level.

Returns: 0 Failed; 1 Succeed

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

int cMSTE::LoadLevel	(	char *	sLevelFilename,
		char *	sSrcDPF = `NULL`,
		char *	sLevelname = `NULL`
	)

Load a native format level.

It loads the level on current TileEngine instance.
If the new layer or tileset IDs are already in use, they are not loaded, however, the viewport, creation/modification dates and the current level name are overwritten.
It will only load the first valid base mapdata and custom mapdata (if any) found on the file.

Parameters

sLevelFilename	Filename of the level to be loaded (extension .msm). It supports optional paths.
sSrcDPF	Optional parameter. String with the DPF filename that contains sLevelFilename. It supports optional paths.
sLevelname	Optional parameter. Selected level name to load. By default it is set to NULL to load the first occurrence.

Returns: -1 Failed: engine was not initialized.; -2 Failed: sLevelFilename is not valid.; -3 Failed: sLevelFilename could not be loaded.; -4 Failed: a 'msse_level' node was not found.; -5 Failed: selected level name was not found.; -6 Failed: a 'name' node was not found.; 0 Warning: some tilesets and/or layers were not loaded. Check the log to further information.; 1 Succeed (all tilesets and layers found on the level loaded)

Examples:: Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

int cMSTE::LoadTileset	(	CRM32Pro_CTile *	tileset,
		int	iID = `-1`
	)

Load a tileset.

bResControl is set to TE_RESCONTROL_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 call ValidateMapBase().

Parameters

tileset	Pointer to a valid CRM32Pro_CTile.
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: -1 Failed; >=0 Succeed and the vTileset index where it was stored

Examples:: Example01_Init.cpp.

int cMSTE::LoadTileset	(	char *	sDPFfile,
		char *	sTileName,
		int	iID = `-1`
	)

Load a tileset.

bResControl is set to TE_RESCONTROL_AUTO: the tileset is automatically removed after usage
szSource is set to the DPF that contains the tileset
After loading the tileset, it'll call ValidateMapBase().

Parameters

sDPFfile	Pointer to DPF filename that contains the tileset.
sTileName	Pointer to 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: -1 Failed; >=0 Succeed and the vTileset index where it was stored

int cMSTE::LoadTileset	(	char *	sIMGfile,
		char *	sTileName,
		int	iTileWidth,
		int	iTileHeight,
		int	iID = `-1`
	)

Load a tileset.

bResControl is set to TE_RESCONTROL_AUTO: the tileset is automatically removed after usage
szSource is set to the external image
After loading the tileset, it'll call ValidateMapBase().

Parameters

sIMGfile	Pointer to PNG or BMP filename
sTileName	Pointer to the Tilename to be loaded
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: -1 Failed; >=0 Succeed and the vTileset index where it was stored

void cMSTE::LogVerbosity ( int iLevel )

Log verbosity control.

Parameters

iLevel 0 for disabling the log output, 1 for displaying only LOG_LOW messages, 2 for displaying LOG_LOW and LOG_NORMAL messages and 3 for displaying all levels

int cMSTE::MoveLayer	(	int	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 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.

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: -1 Failed; 0 Succeed but no change on the position done; 1 Succeed and the position changed

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

int cMSTE::Quit ( )

Close the engine.

In each layer with TE_RESCONTROL_USER flag, we dont free any tileset or mapdata. This have to be done at the developer preference time BUT always after call this method.
And with TE_RESCONTROL_AUTO flag, the engine will remove the tileset and mapdata.

Returns: 0 Failed; 1 Succeed

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

int cMSTE::Render ( int layer = -1 )

Render of visible layer cells.

Only layers with TE_LAYERFLAG_RENDER flag will be processed.
It takes 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.

Returns: 0 Failed; 1 Succeed

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

int cMSTE::SaveLevel	(	char *	sLevelFilename,
		char *	sDPF = `NULL`,
		char *	sLevelname = `NULL`
	)

Save current level on native format.

It saves the whole level including mapdata and tilesets. If the level or tileset output files exist, they are overwritten but external images.

Parameters

sLevelFilename	Filename to save the level. The .msm extension will be automatically added in case it was missing. It supports optional paths.
sDPF	Optional parameter. String with the DPF name to use as container for the level. It supports optional paths.
sLevelname	Optional parameter. String with the new level name overriding the existing level name.

Returns: -1 Failed: engine was not initialized.; -2 Failed: sLevelFilename is not valid.; -3 Failed: internal error.; 1 Succeed

Examples:: Example02_Import.cpp, Example03_Load.cpp, and Example04_Custom.cpp.

int cMSTE::Screen2LayerAbsolute	(	int	layer,
		int	sx,
		int	sy,
		int *	px,
		int *	py
	)

Convert screen coordinates in 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 Failed; 1 Succeed

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

int cMSTE::Screen2LayerCell	(	int	layer,
		int	sx,
		int	sy,
		int *	cx,
		int *	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 Failed; 1 Succeed

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

int cMSTE::SetLayerAlpha	(	int	layer,
		int	alpha
	)

Set layer alpha value.

Parameters

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

Returns: 0 Failed; 1 Succeed

int cMSTE::SetLayerAutoScroll	(	int	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 Failed; 1 Succeed

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

Examples:: Example03_Load.cpp.

int cMSTE::SetLayerFlags	(	int	layer,
		Uint32	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 Failed; 1 Succeed

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

int cMSTE::SetLayerGridColor	(	int	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.

Returns: 0 Failed; 1 Succeed

int cMSTE::SetLayerMapData	(	int	layer,
		cMSTE_MapBase *	map
	)

Assign a mapdata to the given layer.

If it success loading the mapdata, it'll call ValidateMapBase().
If the mapdata is already set, it will remove it following resource control policies (see TE_RESCONTROL_xxx)

Parameters

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

Returns: 0 Failed; 1 Succeed

Examples:: Example01_Init.cpp.

int cMSTE::SetLayerName	(	int	layer,
		char *	name
	)

Set a new layer name.

Parameters

layer	Selected layer to set its name (from 0 to number of allocated layers).
name	Pointer to the new name. Maximum of 32 characters.

Returns: 0 Failed; 1 Succeed

Examples:: Example01_Init.cpp.

int cMSTE::SetLayerOnRenderEnd	(	int	layer,
		TE_OnLayerEnd	myfunc
	)

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

Use NULL 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 Failed; 1 Succeed

int cMSTE::SetLayerOnUpdateEnd	(	int	layer,
		TE_OnLayerEnd	myfunc
	)

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

Use NULL 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 Failed; 1 Succeed

int cMSTE::SetLayerParallaxRatio	(	int	layer,
		float	pratio
	)

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).
pratio	Parallax ratio value. With 0, this layer is independent of the others. 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 Failed; 1 Succeed

Examples:: Example01_Init.cpp, and Example02_Import.cpp.

int cMSTE::SetLayerPosition	(	int	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.
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: -1 Failed; 0 Succeed but no change on the position done; 1 Succeed and the position changed

Examples:: Example01_Init.cpp.

int cMSTE::SetLayerResControl	(	int	layer,
		char	rescontrol
	)

Set layer resource control flag.

Parameters

layer	Selected layer to set the resource control flag (from 0 to number of allocated layers).
rescontrol	See TE_RESCONTROL_xxx defines.

Returns: 0 Failed; 1 Succeed

void cMSTE::SetName ( char * levelname )

Set a new level name.

Parameters

levelname Pointer to the new name. Maximum of 32 characters.

int cMSTE::SetRenderTarget ( SDL_Surface * surf )

Set the render target surface.

Note it will reset the current viewport.

Parameters

surf	A pointer to desired SDL_Surface to render all layers. It usually is CRM32Pro.screen.

Returns: 0 Failed; 1 Succeed

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

int cMSTE::SetTilesetSource	(	int	iTN,
		char *	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 DPF, PNG or BMP

Returns: 0 Failed; 1 Succeed

int cMSTE::SetViewport ( SDL_Rect * rect )

Set the viewport.

You can change the viewport at any time even while you are rendering your application.
By default, it uses the whole render target surface.

Parameters

rect	Pointer to SDL_Rect with the desired viewport. If the rect width or height is 0, it will expand up to the current CRM32Pro.screen

Returns: 0 Failed; 1 Succeed

int cMSTE::UnloadTileset ( int iTN )

Unload a given tileset.

If it success unloading the tileset, it'll call ValidateMapBase().

Parameters

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

Returns: 0 Failed; 1 Succeed

int cMSTE::Update ( int layer = -1 )

Update layer internals.

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 Failed; 1 Succeed

Examples:: Example01_Init.cpp, Example02_Import.cpp, Example03_Load.cpp, Example04_Custom.cpp, and Example05_Tiled.cpp.

The documentation for this class was generated from the following files:

MSTE.h
MSTE_Core.cpp
MSTE_IO_Image.cpp
MSTE_IO_Native.cpp
MSTE_IO_Tiled.cpp

Public Member Functions

Friends

Detailed Description

Member Function Documentation