Functions
Tilengine.c File Reference

Functions

bool TLN_Init (int hres, int vres, int numlayers, int numsprites, int numanimations)
 Initializes the graphic engine in 32 bpp pixel format. More...
 
bool TLN_InitBPP (int hres, int vres, int bpp, int numlayers, int numsprites, int numanimations)
 As of version 1.12.1, this feature has been removed. Only 32 bpp is supported. The function call has been left for backwards binary compatibility but it defaults to TLN_Init() with 32 bpp.
 
void TLN_Deinit (void)
 Deinitialises engine and frees used resources.
 
uint32_t TLN_GetVersion (void)
 Retrieves Tilengine dll version. More...
 
int TLN_GetWidth (void)
 Returns the width in pixels of the framebuffer. More...
 
int TLN_GetHeight (void)
 Returns the height in pixels of the framebuffer. More...
 
int TLN_GetBPP (void)
 Returns the pixel format of the framebuffer. More...
 
void TLN_SetRenderTarget (uint8_t *data, int pitch)
 Sets the output surface for rendering. More...
 
uint8_t * TLN_GetRenderTarget (void)
 Gets the location of the currently set render target. More...
 
int TLN_GetRenderTargetPitch (void)
 Gets the pitch (bytes per scanline) of the currently set render target. More...
 
void TLN_UpdateFrame (int time)
 Draws the frame to the previously specified render target. More...
 
void TLN_BeginFrame (int time)
 Starts active rendering of the current frame. More...
 
int TLN_GetNumLayers (void)
 Returns the number of layers specified during initialisation. More...
 
int TLN_GetNumSprites (void)
 Returns the number of sprites specified during initialisation. More...
 
void TLN_SetRasterCallback (void(*callback)(int))
 Specifies the address of the funcion to call for each drawn scanline. More...
 
void TLN_SetBGColor (uint8_t r, uint8_t g, uint8_t b)
 Sets the background color. More...
 
bool TLN_SetBGColorFromTilemap (TLN_Tilemap tilemap)
 Sets the background color from a Tilemap defined color. More...
 
void TLN_DisableBGColor (void)
 Disales background color rendering. If you know that the last background layer will always cover the entire screen, you can disable it to gain some performance. More...
 
bool TLN_SetBGBitmap (TLN_Bitmap bitmap)
 Sets a static bitmap as background. More...
 
bool TLN_SetBGPalette (TLN_Palette palette)
 Changes the palette for the background bitmap. More...
 
void TLN_SetCustomBlendFunction (uint8_t(*blend_function)(uint8_t src, uint8_t dst))
 Sets custom blend function to use when BLEND_CUSTOM mode is selected. More...
 
uint32_t TLN_GetNumObjects (void)
 Returns the number of objets used by the engine so far. More...
 
uint32_t TLN_GetUsedMemory (void)
 Returns the total amount of memory used by the objects. More...
 
void TLN_SetLastError (TLN_Error error)
 Sets the global error code of tilengine. Useful for custom loaders that need to set the error state. More...
 
TLN_Error TLN_GetLastError (void)
 Returns the last error after an invalid operation. More...
 
const char * TLN_GetErrorString (TLN_Error error)
 Returns the string description of the specified error code. More...
 

Detailed Description

Main module

Function Documentation

bool TLN_Init ( int  hres,
int  vres,
int  numlayers,
int  numsprites,
int  numanimations 
)

Initializes the graphic engine in 32 bpp pixel format.

Parameters
hreshorizontal resolution in pixels
vresvertical resolution in pixels
numlayersnumber of layers
numspritesnumber of sprites
numanimationsnumber of animations

Performs initialisation of the main engine, creates the viewport with the specified dimensions and allocates the number of layers, sprites and animation slots

uint32_t TLN_GetVersion ( void  )

Retrieves Tilengine dll version.

Returns
Returns a 32-bit integer containing three packed numbers: bits 23:16 -> major version bits 15: 8 -> minor version bits 7: 0 -> bugfix revision
Remarks
Compare this number with the TILENGINE_HEADER_VERSION macro to check that both versions match!
int TLN_GetWidth ( void  )

Returns the width in pixels of the framebuffer.

See also
TLN_Init(), TLN_GetHeight()
int TLN_GetHeight ( void  )

Returns the height in pixels of the framebuffer.

See also
TLN_Init(), TLN_GetWidth()
int TLN_GetBPP ( void  )

Returns the pixel format of the framebuffer.

See also
TLN_InitBPP()
void TLN_SetRenderTarget ( uint8_t *  data,
int  pitch 
)

Sets the output surface for rendering.

Parameters
dataPointer to the start of the target framebuffer
pitchNumber of bytes per each scanline of the framebuffer

Sets the output surface for rendering. Tilengine doesn't provide a windowing or hardware video access. The application is responsible of allocating and maintaining the surface where tilengine does the rendering. It can be a SDL surface, a locked DirectX surface, an OpenGL texture, or whatever the application has access to.

Remarks
The render target pixel format must be 32 bits RGBA
See also
TLN_UpdateFrame()
uint8_t* TLN_GetRenderTarget ( void  )

Gets the location of the currently set render target.

See also
TLN_SetRenderTarget()
int TLN_GetRenderTargetPitch ( void  )

Gets the pitch (bytes per scanline) of the currently set render target.

See also
TLN_SetRenderTarget()
void TLN_UpdateFrame ( int  time)

Draws the frame to the previously specified render target.

Parameters
timetimestamp for animation control
Remarks
the timestamp value meaning is application defined, but its units must match the same used in the sequences xml file. It usually is the frame number or millisecond count
See also
TLN_SetRenderTarget()
void TLN_BeginFrame ( int  time)

Starts active rendering of the current frame.

Parameters
timeTimestamp value
See also
TLN_DrawNextScanline(), TLN_BeginWindowFrame(), TLN_EndWindowFrame()
int TLN_GetNumLayers ( void  )

Returns the number of layers specified during initialisation.

See also
TLN_Init()
int TLN_GetNumSprites ( void  )

Returns the number of sprites specified during initialisation.

See also
TLN_Init()
void TLN_SetRasterCallback ( void(*)(int)  callback)

Specifies the address of the funcion to call for each drawn scanline.

Parameters
callbackAddress of the function to call

Tilengine renders its output line by line, just as the 2D graphics chips did. The raster callback is a way to simulate the "horizontal blanking interrupt" of those systems, where many parameters of the rendering can be modified per line.

Remarks
Setting a raster callback is optional, but much of the fun of using Tilengine comes from the use of raster effects
void TLN_SetBGColor ( uint8_t  r,
uint8_t  g,
uint8_t  b 
)

Sets the background color.

Parameters
rred component (0-255)
ggreen component (0-255)
bblue component (0-255)

The background color is the color of the pixel when there isn't any layer or sprite at that position.

Remarks
This funcion can be called during a raster callback to create gradient backgrounds
bool TLN_SetBGColorFromTilemap ( TLN_Tilemap  tilemap)

Sets the background color from a Tilemap defined color.

Parameters
tilemapReference to the tilemap with the background color to set
void TLN_DisableBGColor ( void  )

Disales background color rendering. If you know that the last background layer will always cover the entire screen, you can disable it to gain some performance.

See also
TLN_SetBGColor()
bool TLN_SetBGBitmap ( TLN_Bitmap  bitmap)

Sets a static bitmap as background.

Parameters
bitmapReference to bitmap for the background. Set NULL to disable

Sets an optional bitmap instead of a solid color where there is no layer or sprite. Unlike tilemaps or sprites, this bitmap cannot be moved and has no transparency

See also
TLN_SetBGPalette()
bool TLN_SetBGPalette ( TLN_Palette  palette)

Changes the palette for the background bitmap.

Parameters
paletteReference to palette
See also
TLN_SetBGBitmap()
void TLN_SetCustomBlendFunction ( uint8_t(*)(uint8_t src, uint8_t dst)  blend_function)

Sets custom blend function to use when BLEND_CUSTOM mode is selected.

Parameters
blend_functionpointer to a user-provided function that takes two parameters: source component intensity, destination component intensity, and returns the desired intensity. This function is called for each RGB component when blending is enabled
Remarks
This function is not called in realtime, but its result is precomputed into a look-up table when TLN_SetCustomBlendFunction() is called, so the performance impact is minimal, just as low as the other built-in blending modes
See also
TLN_SetSpriteBlendMode()|TLN_SetLayerBlendMode()
uint32_t TLN_GetNumObjects ( void  )

Returns the number of objets used by the engine so far.

Remarks
The objects is the total amount of tilesets, tilemaps, spritesets, palettes or sequences combined
See also
TLN_GetUsedMemory()
uint32_t TLN_GetUsedMemory ( void  )

Returns the total amount of memory used by the objects.

See also
TLN_GetNumObjects()
void TLN_SetLastError ( TLN_Error  error)

Sets the global error code of tilengine. Useful for custom loaders that need to set the error state.

Parameters
errorError code to set
See also
TLN_GetLastError()
TLN_Error TLN_GetLastError ( void  )

Returns the last error after an invalid operation.

See also
TLN_Error
const char* TLN_GetErrorString ( TLN_Error  error)

Returns the string description of the specified error code.

Parameters
errorError code to get description
See also
TLN_GetLastError()