2.15.1
2.15.1
First of all, you have to include the header at the top of the file:
To initialize the engine, use the function TLN_Init to set the framebuffer resolution, and the number of layers, sprites, and animators. Once set, these values are immutable and cannot be changed. For example, to set a 400x240 framebuffer with 2 layers, 80 sprites and no animations -Sega Genesis setup- you should do:
The background is what is shown when there isn't any layer or sprite at a given location. Tilengine supports two types of backgrounds: solid color and static bitmap. By default the background is black color.
To set a solid color there is the function TLN_SetBGColor that takes the three components of a RGB color, between 0 and 255. For example to set a dark blue background you can do:
It is also possible to set the background color defined inside a tilemap object with the TLN_SetBGColorFromTilemap function. Tilemaps may specify a default background color that can be used here. To see how to load and manipulate tilemaps, please refer to Tilemaps section. For now, to load a tilemap called "tilemap.tmx" and use its default background color, you have to do the following:
To set a bitmap, there is the function TLN_SetBGBitmap that takes the TLN_Bitmap reference of a loaded bitmap. To see how to load an manipulate bitmaps, please refer to Bitmaps section. For now, to load a bitmap called "Background.png" and set it as the background, you have to do the following:
It's possible to change the default palette provided by the bitmap. To do so, use the TLN_SetBGPalette function that takes a TLN_Palette object. To see how to load and manipulate palettes, please refer to Palettes section. Assuming you have an alternative palette file called "Background.act", do the following to set it:
It is possible to disable background at all if you know that the last layer covers the entire screen without holes, to gain some performance:
By default tilengine loads all graphic assets in the same directory where the executable is. If you want to set your assets in a structured tree of folders -which is recommended-, you can set it with the TLN_SetLoadPath function. It accepts relative or absolute paths, and interprets slash and backslash as path separator on any platform. For example:
Most functions in tilengine return either a reference to a requested object, or a boolean value signaling if the operation was successful or not. When an operation fails you can get an specific error code with the TLN_GetLastError, whereas the TLN_GetErrorString returns a string with a description about the requested error code:
Tilengine keeps track about the memory being used, the number of assets, the framebuffer size, etc:
Tilengine does sanity check on each parameter and silently ignores a function call when there are some mistakes on the parameters (indexes out of range, wrong object types, etc). Each function that can fail returns a false boolean that can be further examinated with TLN_GetLastError and TLN_GetErrorString. However this approach requires much work and manual test when something isn't working as expected. To ease the debugging of your program, Tilengine supports writing messages to the standard output. This behavior is selected with TLN_SetLogLevel, with three possible values:
| Value | Effect |
|---|---|
| TLN_LOG_NONE | Doesn't output anything (default value) |
| TLN_LOG_ERRORS | Print only wrong function calls |
| TLN_LOG_VERBOSE | Print wrong function calls and every asset creation/destruction |
Once done, you should explicitly close tilengine to release memory and resources:
Since release 2.0.0, Tilengine supports multiple instances using a global context mechanism. The TLN_Init function returns a handler to a newly created context (a TLN_Engine object), that is selected as active by default. To change the active context use the TLN_SetContext function, passing the handler of the desired context. To delete a context, use TLN_DeleteContext.
This is a quick reference of related functions in this chapter:
| Function | Quick description |
|---|---|
| TLN_GetVersion | Returns library version |
| TLN_Init | Creates a Tilengine rendering context |
| TLN_Deinit | Destroys the current rendering context |
| TLN_SetContext | Selects the active context |
| TLN_GetContext | Returns the active context |
| TLN_DeleteContext | Destroys the specified context |
| TLN_SetLoadPath | Sets defautl load path for asset loading |
| TLN_GetWidth | Returns the width of the created framebuffer |
| TLN_GetHeight | Returns the height of the created framebuffer |
| TLN_GetNumObjects | Returns the number of runtime assets |
| TLN_GetUsedMemory | Returns the amount of memory used by runtime assets |
| TLN_GetNumLayers | Returns the number of requested layers |
| TLN_GetNumSprites | Returns the number of requested sprites |
| TLN_SetBGColor | Sets the default background color |
| TLN_SetBGColorFromTilemap | Sets the background color as defined in a given tilemap |
| TLN_DisableBGColor | Disables use of background color |
| TLN_SetBGBitmap | Sets a static background bitmap |
| TLN_SetBGPalette | Sets the palette of the static background bitmap |
| TLN_SetLogLevel | Sets the verbosity of debug messages |
| TLN_GetLastError | Returns the code of last error |
| TLN_GetErrorString | Returns the string value of a given error code |
Last update on Tue Aug 29 2023 for Tilengine 2.15.1