2.10.0
Functions
Layer

Background layers management. More...

Description

Background layers management.

Functions

bool TLN_SetLayer (int nlayer, TLN_Tileset tileset, TLN_Tilemap tilemap)
 Configures a background layer with the specified tileset and tilemap. More...
 
bool TLN_SetLayerTilemap (int nlayer, TLN_Tilemap tilemap)
 Configures a tiled background layer with the specified tilemap. More...
 
bool TLN_SetLayerBitmap (int nlayer, TLN_Bitmap bitmap)
 Configures a background layer with the specified full bitmap. More...
 
bool TLN_SetLayerPalette (int nlayer, TLN_Palette palette)
 Sets the color palette to the layer. More...
 
bool TLN_SetLayerPosition (int nlayer, int hstart, int vstart)
 Sets the position of the tileset that corresponds to the upper left corner. More...
 
bool TLN_SetLayerScaling (int nlayer, float xfactor, float yfactor)
 Sets simple scaling. More...
 
bool TLN_SetLayerAffineTransform (int nlayer, TLN_Affine *affine)
 Sets affine transform matrix to enable rotating and scaling of this layer. More...
 
bool TLN_SetLayerTransform (int layer, float angle, float dx, float dy, float sx, float sy)
 Sets affine transform matrix to enable rotating and scaling of this layer. More...
 
bool TLN_SetLayerPixelMapping (int nlayer, TLN_PixelMap *table)
 Sets the table for pixel mapping render mode. More...
 
bool TLN_SetLayerBlendMode (int nlayer, TLN_Blend mode, uint8_t factor)
 Sets the blending mode (transparency effect) More...
 
bool TLN_SetLayerColumnOffset (int nlayer, int *offset)
 Enables column offset mode for this layer. More...
 
bool TLN_SetLayerClip (int nlayer, int x1, int y1, int x2, int y2)
 Enables clipping rectangle on selected layer. More...
 
bool TLN_DisableLayerClip (int nlayer)
 Disables clipping rectangle on selected layer. More...
 
bool TLN_SetLayerMosaic (int nlayer, int width, int height)
 Enables mosaic effect (pixelation) for selected layer. More...
 
bool TLN_DisableLayerMosaic (int nlayer)
 Disables mosaic effect for selected layer. More...
 
bool TLN_ResetLayerMode (int nlayer)
 Disables scaling or affine transform for the layer. More...
 
bool TLN_SetLayerObjects (int nlayer, TLN_ObjectList objects, TLN_Tileset tileset)
 Configures a background layer with a object list and an image-based tileset. More...
 
bool TLN_SetLayerPriority (int nlayer, bool enable)
 Sets full layer priority, appearing in front of sprites. More...
 
bool TLN_DisableLayer (int nlayer)
 Disables the specified layer so it is not drawn. More...
 
bool TLN_EnableLayer (int nlayer)
 Enables a layer previously disabled with TLN_DisableLayer. More...
 
TLN_LayerType TLN_GetLayerType (int nlayer)
 Returns the type of the layer. More...
 
TLN_Palette TLN_GetLayerPalette (int nlayer)
 Returns the active palette of a layer. More...
 
TLN_Tileset TLN_GetLayerTileset (int nlayer)
 Returns the active tileset on a LAYER_TILE or LAYER_OBJECT layer type. More...
 
TLN_Tilemap TLN_GetLayerTilemap (int nlayer)
 Returns the active tilemap on a LAYER_TILE layer type. More...
 
TLN_Bitmap TLN_GetLayerBitmap (int nlayer)
 Returns the active bitmap on a LAYER_BITMAP layer type. More...
 
TLN_ObjectList TLN_GetLayerObjects (int nlayer)
 Returns the active object list on a LAYER_OBJECT layer type. More...
 
bool TLN_GetLayerTile (int nlayer, int x, int y, TLN_TileInfo *info)
 Gets info about the tile located in tilemap space. More...
 
int TLN_GetLayerWidth (int nlayer)
 Returns the layer width in pixels. More...
 
int TLN_GetLayerHeight (int nlayer)
 Returns the layer height in pixels. More...
 

Function Documentation

◆ TLN_SetLayer()

bool TLN_SetLayer ( int  nlayer,
TLN_Tileset  tileset,
TLN_Tilemap  tilemap 
)

Configures a background layer with the specified tileset and tilemap.

Deprecated:
Use TLN_SetLayerTilemap instead
Parameters
nlayerLayer index [0, num_layers - 1]
tilesetOptional reference to the tileset to assign. If the tilemap has a reference to its own tileset, passing NULL will assign the default tileset.
tilemapReference to the tilemap to assign
Remarks
This function doesn't modify the current position nor the blend mode, but assigns the palette of the specified tileset
See also
TLN_DisableLayer()

◆ TLN_SetLayerTilemap()

bool TLN_SetLayerTilemap ( int  nlayer,
TLN_Tilemap  tilemap 
)

Configures a tiled background layer with the specified tilemap.

Parameters
nlayerLayer index [0, num_layers - 1]
tilemapReference to the tilemap to assign
Returns
true if success or false if error
See also
TLN_LoadTilemap()

◆ TLN_SetLayerBitmap()

bool TLN_SetLayerBitmap ( int  nlayer,
TLN_Bitmap  bitmap 
)

Configures a background layer with the specified full bitmap.

Parameters
nlayerLayer index [0, num_layers - 1]
bitmapReference to the bitmap to assign
Remarks
This function doesn't modify the current position nor the blend mode, but assigns the palette of the specified bitmap
See also
TLN_LoadBitmap() TLN_DisableLayer()

◆ TLN_SetLayerPalette()

bool TLN_SetLayerPalette ( int  nlayer,
TLN_Palette  palette 
)

Sets the color palette to the layer.

Parameters
nlayerLayer index [0, num_layers - 1]
paletteReference to the palette to assign to the layer

When a layer is assigned with a tileset with the function TLN_SetLayer(), it automatically sets the palette of the assigned tileset to the layer. Use this function to override it and set another palette

Remarks
Call this function inside a raster callback to change the palette in the middle of the frame to get raster effect colors, like and "underwater" palette below the water line in a partially submerged background, or a gradient palette in an area at the top of the screen to simulate a "depth fog effect" in a pseudo 3d background

◆ TLN_SetLayerPosition()

bool TLN_SetLayerPosition ( int  nlayer,
int  hstart,
int  vstart 
)

Sets the position of the tileset that corresponds to the upper left corner.

Parameters
nlayerLayer index [0, num_layers - 1]
hstartHorizontal offset in the tileset on the left side
vstartVertical offset in the tileset on the top side

The tileset usually spans an area much bigger than the viewport. Use this function to move the viewport insde the tileset. Change this value progressively for each frame to get a scrolling effect

Remarks
Call this function inside a raster callback to get a raster scrolling effect. Use this to create horizontal strips of the same layer that move at different speeds to simulate depth. The extreme case of this effect, where the position is changed in each scanline, is called "line scroll" and was the technique used by games such as Street Fighter II to simualte a pseudo 3d floor, or many racing games to simulate a 3D road.

◆ TLN_SetLayerScaling()

bool TLN_SetLayerScaling ( int  nlayer,
float  sx,
float  sy 
)

Sets simple scaling.

Parameters
nlayerLayer index [0, num_layers - 1]
sxHorizontal scale factor
syVertical scale factor

By default the scaling factor of a given layer is 1.0f, 1.0f, which means no scaling. Use values below 1.0 to downscale (shrink) and above 1.0 to upscale (enlarge). Call TLN_ResetLayerMode() to disable scaling

Write detailed description for TLN_SetLayerScaling here.

See also
TLN_ResetLayerMode()

◆ TLN_SetLayerAffineTransform()

bool TLN_SetLayerAffineTransform ( int  nlayer,
TLN_Affine affine 
)

Sets affine transform matrix to enable rotating and scaling of this layer.

Parameters
nlayerLayer index [0, num_layers - 1]
affinePointer to an TLN_Affine matrix, or NULL to disable it

Enable the transformation matrix to give the layer the capabilities of the famous Super Nintendo / Famicom Mode 7. Beware that the rendering of a transformed layer uses more CPU than a regular layer. Unlike the original Mode 7, that could only transform the single layer available, Tilengine can transform all the layers at the same time. The only limitation is the available CPU power.

Remarks
Call this function inside a raster callback to set the transformation matrix in the middle of the frame. Setting it for each scanline is the trick used by many Super Nintendo games to fake a 3D perspective projection.
See also
TLN_SetLayerTransform()

◆ TLN_SetLayerTransform()

bool TLN_SetLayerTransform ( int  layer,
float  angle,
float  dx,
float  dy,
float  sx,
float  sy 
)

Sets affine transform matrix to enable rotating and scaling of this layer.

Parameters
layerLayer index [0, num_layers - 1]
angleRotation angle in degrees
dxHorizontal displacement
dyVertical displacement
sxHorizontal scaling
syVertical scaling
Remarks
This function is a simple wrapper to TLN_SetLayerAffineTransform() without using the TLN_Affine struct
See also
TLN_SetLayerAffineTransform()

◆ TLN_SetLayerPixelMapping()

bool TLN_SetLayerPixelMapping ( int  nlayer,
TLN_PixelMap table 
)

Sets the table for pixel mapping render mode.

Parameters
nlayerLayer index [0, num_layers - 1]
tableUser-provided array of hres*vres sized TLN_PixelMap items
See also
TLN_SetLayerScaling(), TLN_SetLayerAffineTransform()

◆ TLN_SetLayerBlendMode()

bool TLN_SetLayerBlendMode ( int  nlayer,
TLN_Blend  mode,
uint8_t  factor 
)

Sets the blending mode (transparency effect)

Parameters
nlayerLayer index [0, num_layers - 1]
modeMember of the TLN_Blend enumeration
factorDeprecated as of 1.12, left for backwards compatibility but doesn't have effect.
See also
Blending

◆ TLN_SetLayerColumnOffset()

bool TLN_SetLayerColumnOffset ( int  nlayer,
int *  offset 
)

Enables column offset mode for this layer.

Parameters
nlayerLayer index [0, num_layers - 1]
offsetArray of offsets to set. Set NULL to disable column offset mode

Column offset is a value that is added or substracted (depeinding on the sign) to the vertical position for that layer (see TLN_SetLayerPosition) for each column in the tilemap assigned to that layer.

Remarks
This feature is tipically used to simulate vertical strips moving at different speeds, or combined with a line scroll effect, to fake rotations where the angle is small. The Sega Genesis games Puggsy and Chuck Rock II used this trick to simulate partially rotating backgrounds

◆ TLN_SetLayerClip()

bool TLN_SetLayerClip ( int  nlayer,
int  x1,
int  y1,
int  x2,
int  y2 
)

Enables clipping rectangle on selected layer.

Parameters
nlayerLayer index [0, num_layers - 1]
x1left coordinate
y1top coordinate
x2right coordinate
y2bottom coordinate
See also
TLN_DisableLayerClip()

◆ TLN_DisableLayerClip()

bool TLN_DisableLayerClip ( int  nlayer)

Disables clipping rectangle on selected layer.

Parameters
nlayerLayer index [0, num_layers - 1]
See also
TLN_SetLayerClip()

◆ TLN_SetLayerMosaic()

bool TLN_SetLayerMosaic ( int  nlayer,
int  width,
int  height 
)

Enables mosaic effect (pixelation) for selected layer.

Parameters
nlayerLayer index [0, num_layers - 1]
widthhorizontal pixel size
heightvertical pixel size
See also
TLN_DisableLayerMosaic()

◆ TLN_DisableLayerMosaic()

bool TLN_DisableLayerMosaic ( int  nlayer)

Disables mosaic effect for selected layer.

Parameters
nlayerLayer index [0, num_layers - 1]
See also
TLN_SetLayerMosaic()

◆ TLN_ResetLayerMode()

bool TLN_ResetLayerMode ( int  nlayer)

Disables scaling or affine transform for the layer.

Parameters
nlayerLayer index [0, num_layers - 1]

Write detailed description for TLN_ResetLayerMode here.

See also
TLN_SetLayerScaling(), TLN_SetLayerAffineTransform()

◆ TLN_SetLayerObjects()

bool TLN_SetLayerObjects ( int  nlayer,
TLN_ObjectList  objects,
TLN_Tileset  tileset 
)

Configures a background layer with a object list and an image-based tileset.

Parameters
nlayerLayer index [0, num_layers - 1]
objectsReference to the TLN_ObjectList to attach
tilesetoptional reference to the image-based tileset object. If NULL, object list must have an attached tileset
See also
TLN_LoadObjectList()

◆ TLN_SetLayerPriority()

bool TLN_SetLayerPriority ( int  nlayer,
bool  enable 
)

Sets full layer priority, appearing in front of sprites.

Parameters
nlayerLayer index [0, num_layers - 1]
enableEnable (true) or dsiable (false) full priority

◆ TLN_DisableLayer()

bool TLN_DisableLayer ( int  nlayer)

Disables the specified layer so it is not drawn.

Parameters
nlayerLayer index [0, num_layers - 1]
Remarks
A layer configured with an invalid tileset, tilemap or palette is automatically disabled
See also
TLN_SetLayer()

◆ TLN_EnableLayer()

bool TLN_EnableLayer ( int  nlayer)

Enables a layer previously disabled with TLN_DisableLayer.

Parameters
nlayerLayer index [0, num_layers - 1]
Remarks
The layer must have been previously configured. A layer without a prior configuration can't be enabled

◆ TLN_GetLayerType()

TLN_LayerType TLN_GetLayerType ( int  nlayer)

Returns the type of the layer.

Parameters
nlayerLayer index [0, num_layers - 1]
Returns
TLN_LayerType enumeration
See also
TLN_SetLayerTilemap(), TLN_SetLayerObjects(), TLN_SetLayerBitmap()

◆ TLN_GetLayerPalette()

TLN_Palette TLN_GetLayerPalette ( int  nlayer)

Returns the active palette of a layer.

Parameters
nlayerLayer index [0, num_layers - 1]
Returns
Reference of the palette assigned to the layer
See also
TLN_SetLayerPalette()

◆ TLN_GetLayerTileset()

TLN_Tileset TLN_GetLayerTileset ( int  nlayer)

Returns the active tileset on a LAYER_TILE or LAYER_OBJECT layer type.

Parameters
nlayerLayer index [0, num_layers - 1]
Returns
Reference to the active tileset
See also
TLN_SetLayerTilemap(), TLN_SetLayerObjects()

◆ TLN_GetLayerTilemap()

TLN_Tilemap TLN_GetLayerTilemap ( int  nlayer)

Returns the active tilemap on a LAYER_TILE layer type.

Parameters
nlayerLayer index [0, num_layers - 1]
Returns
Reference to the active tilemap
See also
TLN_SetLayerTilemap()

◆ TLN_GetLayerBitmap()

TLN_Bitmap TLN_GetLayerBitmap ( int  nlayer)

Returns the active bitmap on a LAYER_BITMAP layer type.

Parameters
nlayerLayer index [0, num_layers - 1]
Returns
Reference to the active bitmap
See also
TLN_SetLayerBitmap()

◆ TLN_GetLayerObjects()

TLN_ObjectList TLN_GetLayerObjects ( int  nlayer)

Returns the active object list on a LAYER_OBJECT layer type.

Parameters
nlayerLayer index [0, num_layers - 1]
Returns
Reference to the active objects list
See also
TLN_SetLayerObjects(), TLN_GetListObject()

◆ TLN_GetLayerTile()

bool TLN_GetLayerTile ( int  nlayer,
int  x,
int  y,
TLN_TileInfo info 
)

Gets info about the tile located in tilemap space.

Parameters
nlayerId of the layer to query [0, num_layers - 1]
xx position
yy position
infoPointer to an application-allocated TLN_TileInfo struct that will get the data
Returns
true if success or false if error
Remarks
Use this function to implement collision detection between sprites and the main background layer.
See also
TLN_TileInfo

◆ TLN_GetLayerWidth()

int TLN_GetLayerWidth ( int  nlayer)

Returns the layer width in pixels.

Parameters
nlayerLayer index [0, num_layers - 1]
See also
TLN_SetLayer(), TLN_GetLayerHeight()

◆ TLN_GetLayerHeight()

int TLN_GetLayerHeight ( int  nlayer)

Returns the layer height in pixels.

Parameters
nlayerLayer index [0, num_layers - 1]
See also
TLN_SetLayer(), TLN_GetLayerWidth()