2.9.4
Windowing

The built-in window in tilengine provides a basic, easy to setup environment for quick test and evaluation. It's a very simple environment to ease prototyping but is not intended to be used in production environment.

Features

  • Runs windowed or full-screen
  • User input with keyboard or gamepad
  • CRT post-processing emulation filter
  • Single thread or multi-threaded

Single threaded window

The single threaded window runs inside the main thread and must be handled inside the game loop for each frame. The window is created with TLN_CreateWindow. With default parameters it creates a window with an integer scaling as large as possible for the desktop resolution, and with CRT emulation effect enabled:

TLN_CreateWindow (NULL, 0);

Supported creation flags are as follows:

Flag value Effect
CWF_FULLSCREEN create a full-screen window
CWF_VSYNC sync frame updates with vertical retrace
CWF_Sn force integer upscale factor (n is 1-5)
CWF_NEAREST start with CRT/RF effect disabled

The following key combinations are used to control the window:

Key Effect
Alt + Enter Toggle windowed/full-screen mode
Backspace Toggle CRT/RF effect or on off
Escape Close the window

Once the window is created, it must be processed calling TLN_ProcessWindow for each frame. This function returns true while the window is alive, or false when the user has requested to terminate it. Draw the frames with TLN_DrawFrame. This function takes an optional integer value, that represents a frame counter used by the animation engine.

This basic sample show how to initialize the engine, create the window and do the window loop until the user requests to exit:

TLN_Init (400,240, 2,8,0); /* init the engine */
TLN_CreateWindow (NULL, 0); /* create the window */
while (TLN_ProcessWindow()) /* the window loop */
TLN_DrawFrame (0); /* draw next frame */
TLN_Deinit (); /* release resources */

Multi-threaded window

The multi-threaded window spans its own thread and runs in parallel, without a window loop. It's mainly used for interactive use within an editor as in python. The multi-threaded window is created with TLN_CreateWindowThread and doesn't require continuous calls to TLN_ProcessWindow or TLN_DrawFrame. Instead you query its active state with TLN_IsWindowActive, and optionally you can sync to it with TLN_WaitRedraw.

This is the same sample with the multi-threaded window:

TLN_Init (400,240, 2,8,0); /* init the engine */
TLN_CreateWindowThread (NULL, 0); /* create the window */
while (TLN_IsWindowActive()) /* check window state */
TLN_WaitRedraw (); /* optionally sync to window drawing for fps control */
TLN_Deinit (); /* release resources */

User input

User input in tilengine simulates a basic arcade setup, with 4-way directions, 6 action buttons and a Start button, and up to 4 simultaneous players. It can be controlled with keyboard or joystick/gamepad. By default, only the first 4 buttons of player 1 are assigned as follows:

Player 1 Input Assigned to...
4-way direction keyboard cursors or gamepad D-Pad
Buttons 1-4 Z,X,C,V or gamepad buttons 1-4.
Start button Enter or gamepad button 5.

To check the state of an input, call TLN_GetInput with one of the possible TLN_Input values:

Input name Meaning
INPUT_UP up direction
INPUT_DOWN down direction
INPUT_LEFT left direction
INPUT_RIGHT right direction
INPUT_BUTTONn action button (n is 1-6)
INPUT_START Start button

For example, to check if player 1 left arrow is pushed do this:

{
/* do your treatment */
}

Redefining inputs

To define new key and joystick bindings to inputs, use the functions TLN_AssignInputJoystick, TLN_DefineInputKey and TLN_DefineInputButton. The code identifiers for key bindings are the same used inside the SDL2 library, so you'll need to include SDL.h header. For example, to assign the Space key to player 2 start button:

#include <SDL2/SDL.h>
...
TLN_DefineInputKey (PLAYER2, INPUT_START, SDLK_SPACE);

Local multiplayer

By default only player 1 input is enabled. To enable or disable input processing for a given player, call TLN_EnableInput with the desired player PLAYER1 to PLAYER4. For example to enable player 2 input:

To request input for a specific player, combine the name of the input with the modifier INPUT_Pn, where n is the player number (1 to 4). For example, to check if player 2 has pushed start:

{
/* do your treatment */
}

Enhanced input with SDL2

If the built-in input layout of tilengine is not enough, because your game needs mouse input, analog sticks, more keys, etc. Tilengine can catch the events delivered by the underlying SDL2 library and pass them to your own input handling. This is done by a user callback, that can be registered with TLN_SetSDLCallback function. The user callback must have the format void sdl_callback(SDL_Event*);. For example, to check mouse click:

#include <SDL2/SDL.h>
...
/* user callback: check mouse click event and put sprite 0 at clicked coordinates */
void my_mouse_callback(SDL_Event* sdl_event)
{
if (sdl_event->type == SDL_MOUSEBUTTONDOWN)
{
SDL_MouseButtonEvent* mouse = (SDL_MouseButtonEvent*)sdl_event;
TLN_SetSpritePosition (0, mosue->x, mouse->y);
}
}
/* register the callback */
TLN_SetSDLCallback (my_mouse_callback);

For extended info about SDL input handling, please check this link: https://wiki.libsdl.org/SDL_Event

Time & delay

Tilengine window provides some basic timing functions. TLN_GetTicks returns the number of milliseconds elapsed since system started, and TLN_Delay pauses execution for the given amount of milliseconds.

The CRT effect

All low resolution, pixel art games were played on CRT displays that provided its unique texture and feel. Trying to watch this type of games in crystal-clear, big square pixels, is just wrong. The CRT effect simulates more or less faithfully the characteristics of a CRT display: visible RGB strips, horizontal blur, bright pixel bloom...

Plain output without CRT:
CRT disabled

The same output but with default CRT enabled:
CRT enabled

By default the CRT effect is enabled when the window is created, but it can be disabled with the TLN_DisableCRTEffect function. It can be toggled pressing the Escape key, too.

The effect is highly configurable with the TLN_EnableCRTEffect function. It takes many parameters to customize its appearance and strength. The default parameters are:

TLN_EnableCRTEffect (TLN_OVERLAY_APERTURE, 128, 192, 0,64, 64,128, false, 255);

Summary

This is a quick reference of related functions in this chapter:

Function Quick description
TLN_CreateWindow Creates a SDL2 window for rendering
TLN_CreateWindowThread Creates a multi-threaded SDL2 window for rendering
TLN_SetWindowTitle Sets the window title
TLN_ProcessWindow Process user input events
TLN_IsWindowActive Checks if the window is still active
TLN_GetInput Checks the state of a given input
TLN_EnableInput Enables input for given player
TLN_AssignInputJoystick Binds a joystick to a given player
TLN_DefineInputKey Binds a key to a given player input
TLN_DefineInputButton Binds a joystick button to a given player input
TLN_DrawFrame Renders a new frame to the window
TLN_WaitRedraw Syncs to redraw in multi-threaded window
TLN_DeleteWindow Destroys the window
TLN_EnableCRTEffect Configures the CRT/RF video effect
TLN_DisableCRTEffect Disables the CRT/RF video effect
TLN_SetSDLCallback Sets function to call when SDL input events happen
TLN_Delay Waits for the specified amount of milliseconds
TLN_GetTicks Returns the number of milliseconds since window creation
TLN_CreateWindow
bool TLN_CreateWindow(const char *overlay, int flags)
Creates a window for rendering.
Definition: Window.c:398
TLN_EnableInput
void TLN_EnableInput(TLN_Player player, bool enable)
Enables or disables input for specified player.
Definition: Window.c:919
INPUT_LEFT
@ INPUT_LEFT
Definition: Tilengine.h:295
TLN_IsWindowActive
bool TLN_IsWindowActive(void)
Checks window state.
Definition: Window.c:721
TLN_Deinit
void TLN_Deinit(void)
Deinitialises current engine context and frees used resources.
Definition: Tilengine.c:206
TLN_SetSpritePosition
bool TLN_SetSpritePosition(int nsprite, int x, int y)
Sets the sprite position in screen space.
Definition: Sprite.c:171
TLN_OVERLAY_APERTURE
@ TLN_OVERLAY_APERTURE
Definition: Tilengine.h:222
TLN_WaitRedraw
void TLN_WaitRedraw(void)
Thread synchronization for multithreaded window. Waits until the current frame has ended rendering.
Definition: Window.c:734
TLN_Init
TLN_Engine TLN_Init(int hres, int vres, int numlayers, int numsprites, int numanimations)
Initializes the graphic engine.
Definition: Tilengine.c:56
TLN_DrawFrame
void TLN_DrawFrame(int frame)
Draws a frame to the window.
Definition: Window.c:1062
PLAYER2
@ PLAYER2
Definition: Tilengine.h:283
TLN_SetSDLCallback
void TLN_SetSDLCallback(TLN_SDLCallback)
Registers a user-defined callback to capture internal SDL2 events.
Definition: Window.c:1111
TLN_GetInput
bool TLN_GetInput(TLN_Input id)
Returns the state of a given input.
Definition: Window.c:900
TLN_CreateWindowThread
bool TLN_CreateWindowThread(const char *overlay, int flags)
Creates a multithreaded window for rendering.
Definition: Window.c:454
TLN_EnableCRTEffect
void TLN_EnableCRTEffect(TLN_Overlay overlay, uint8_t overlay_factor, uint8_t threshold, uint8_t v0, uint8_t v1, uint8_t v2, uint8_t v3, bool blur, uint8_t glow_factor)
Enables CRT simulation post-processing effect to give true retro appeareance.
Definition: Window.c:797
INPUT_START
@ INPUT_START
Definition: Tilengine.h:303
INPUT_P2
@ INPUT_P2
Definition: Tilengine.h:310
TLN_ProcessWindow
bool TLN_ProcessWindow(void)
Does basic window housekeeping in signgle-threaded window.
Definition: Window.c:617