Layer.c File Reference

Background layers manipulation. More...

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_SetLayerBitmap (int nlayer, TLN_Bitmap bitmap)
 Configures a background layer with the specified full bitmap. 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...
 
bool TLN_SetLayerBlendMode (int nlayer, TLN_Blend mode, uint8_t factor)
 Sets the blending mode (transparency effect) More...
 
bool TLN_SetLayerPalette (int nlayer, TLN_Palette palette)
 Sets the color palette to the layer. More...
 
TLN_Palette TLN_GetLayerPalette (int nlayer)
 Gets the attached palette of a 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_GetLayerTile (int nlayer, int x, int y, TLN_TileInfo *info)
 Gets info about the tile located in tilemap space. More...
 
bool TLN_SetLayerColumnOffset (int nlayer, int *offset)
 Enables column offset mode for this layer. More...
 
bool TLN_DisableLayer (int nlayer)
 Disables the specified layer so it is not drawn. 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_SetLayerScaling (int nlayer, float sx, float sy)
 Sets simple scaling. More...
 
bool TLN_SetLayerPixelMapping (int nlayer, TLN_PixelMap *table)
 Sets the table for pixel mapping render mode. More...
 
bool TLN_ResetLayerMode (int nlayer)
 Disables scaling or affine transform for the 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...
 

Detailed Description

Background layers manipulation.

Function Documentation

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

Configures a background layer with the specified tileset and tilemap.

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()
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_DisableLayer()
int TLN_GetLayerWidth ( int  nlayer)

Returns the layer width in pixels.

Parameters
nlayerLayer index [0, num_layers - 1]
See also
TLN_SetLayer(), 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()
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
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_Palette TLN_GetLayerPalette ( int  nlayer)

Gets the attached palette of a layer.

Parameters
nlayerLayer index [0, num_layers - 1]
Returns
Reference of the palette assigned to the layer
See also
TLN_SetLayerPalette()
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.
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
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
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()
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()
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()
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()
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()
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()
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()
bool TLN_DisableLayerClip ( int  nlayer)

Disables clipping rectangle on selected layer.

Parameters
nlayerLayer index [0, num_layers - 1]
See also
TLN_SetLayerClip()
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()
bool TLN_DisableLayerMosaic ( int  nlayer)

Disables mosaic effect for selected layer.

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