2.9.4
Functions
Windowing

Built-in window and input management. More...

Description

Built-in window and input management.

Functions

bool TLN_CreateWindow (const char *overlay, int flags)
 Creates a window for rendering. More...
 
bool TLN_CreateWindowThread (const char *overlay, int flags)
 Creates a multithreaded window for rendering. More...
 
void TLN_SetWindowTitle (const char *title)
 Sets window title. More...
 
bool TLN_ProcessWindow (void)
 Does basic window housekeeping in signgle-threaded window. More...
 
bool TLN_IsWindowActive (void)
 Checks window state. More...
 
bool TLN_GetInput (TLN_Input id)
 Returns the state of a given input. More...
 
void TLN_EnableInput (TLN_Player player, bool enable)
 Enables or disables input for specified player. More...
 
void TLN_AssignInputJoystick (TLN_Player player, int index)
 Assigns a joystick index to the specified player. More...
 
void TLN_DefineInputKey (TLN_Player player, TLN_Input input, uint32_t keycode)
 Assigns a keyboard input to a player. More...
 
void TLN_DefineInputButton (TLN_Player player, TLN_Input input, uint8_t joybutton)
 Assigns a button joystick input to a player. More...
 
void TLN_DrawFrame (int frame)
 Draws a frame to the window. More...
 
void TLN_WaitRedraw (void)
 Thread synchronization for multithreaded window. Waits until the current frame has ended rendering. More...
 
void TLN_DeleteWindow (void)
 Deletes the window previoulsy created with TLN_CreateWindow() or TLN_CreateWindowThread() More...
 
void TLN_EnableBlur (bool mode)
 Removed in release 1.12, use TLN_EnableCRTEffect() instead. More...
 
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. More...
 
void TLN_DisableCRTEffect (void)
 Disables the CRT post-processing effect. More...
 
void TLN_SetSDLCallback (TLN_SDLCallback)
 Registers a user-defined callback to capture internal SDL2 events. More...
 
void TLN_Delay (uint32_t msecs)
 Suspends execition for a fixed time. More...
 
uint32_t TLN_GetTicks (void)
 Returns the number of milliseconds since application start.
 
int TLN_GetWindowWidth (void)
 Returns horizontal dimension of window after scaling.
 
int TLN_GetWindowHeight (void)
 Returns vertical dimension of window after scaling.
 

Function Documentation

◆ TLN_CreateWindow()

bool TLN_CreateWindow ( const char *  overlay,
int  flags 
)

Creates a window for rendering.

Parameters
overlayOptional path of a bmp file to overlay (for emulating RGB mask, scanlines, etc)
flagsMask of the possible creation flags: CWF_FULLSCREEN, CWF_VSYNC, CWF_S1 - CWF_S5 (scaling factor, none = auto max)
Returns
True if window was created or false if error

Creates a host window with basic user input for tilengine. If fullscreen, it uses the desktop resolution and stretches the output resolution with aspect correction, letterboxing or pillarboxing as needed. If windowed, it creates a centered window that is the maximum possible integer multiply of the resolution configured at TLN_Init()

Remarks
Using this feature is optional, Tilengine is designed to output its rendering to a user-provided surface so it can be used as a backend renderer of an already existing framework. But it is provided for convenience, so it isn't needed to provide external components to run the examples or do engine tests.
See also
TLN_DeleteWindow(), TLN_ProcessWindow(), TLN_GetInput(), TLN_DrawFrame()

◆ TLN_CreateWindowThread()

bool TLN_CreateWindowThread ( const char *  overlay,
int  flags 
)

Creates a multithreaded window for rendering.

Parameters
overlayOptional path of a bmp file to overlay (for emulating RGB mask, scanlines, etc)
flagsMask of the possible creation flags: CWF_FULLSCREEN, CWF_VSYNC, CWF_S1 - CWF_S5 (scaling factor, none = auto max)
Returns
True if window was created or false if error

Creates a host window with basic user input for tilengine. If fullscreen, it uses the desktop resolution and stretches the output resolution with aspect correction, letterboxing or pillarboxing as needed. If windowed, it creates a centered window that is the maximum possible integer multiply of the resolution configured at TLN_Init()

Remarks
Unlike TLN_CreateWindow, This window runs in its own thread
See also
TLN_DeleteWindow(), TLN_IsWindowActive(), TLN_GetInput(), TLN_UpdateFrame()

◆ TLN_SetWindowTitle()

void TLN_SetWindowTitle ( const char *  title)

Sets window title.

Parameters
titleText with the title to set

◆ TLN_ProcessWindow()

bool TLN_ProcessWindow ( void  )

Does basic window housekeeping in signgle-threaded window.

Returns
True if window is active or false if the user has requested to end the application (by pressing Esc key or clicking the close button)

If a window has been created with TLN_CreateWindow, this function must be called periodically (call it inside the main loop so it gets called regularly). If the window was created with TLN_CreateWindowThread, do not use it

See also
TLN_CreateWindow()

◆ TLN_IsWindowActive()

bool TLN_IsWindowActive ( void  )

Checks window state.

Returns
True if window is active or false if the user has requested to end the application (by pressing Esc key or clicking the close button)
See also
TLN_CreateWindow(), TLN_CreateWindowThread()

◆ TLN_GetInput()

bool TLN_GetInput ( TLN_Input  input)

Returns the state of a given input.

Parameters
inputInput to check state. It can be one of the following values:
  • INPUT_UP
  • INPUT_DOWN
  • INPUT_LEFT
  • INPUT_RIGHT
  • INPUT_BUTTON1 - INPUT_BUTTON6,
  • INPUT_START
  • Optionally combine with INPUT_P1 to INPUT_P4 to request input for specific player
Returns
True if that input is pressed or false if not

If a window has been created with TLN_CreateWindow, it provides basic user input. It simulates a classic arcade setup, with 4 directional buttons (INPUT_UP to INPUT_RIGHT), 6 action buttons (INPUT_BUTTON1 to INPUT_BUTTON6) and a start button (INPUT_START). By default directional buttons are mapped to keyboard cursors and joystick 1 D-PAD, and the first four action buttons are the keys Z,X,C,V and joystick buttons 1 to 4.

See also
TLN_CreateWindow(), TLN_DefineInputKey(), TLN_DefineInputButton()

◆ TLN_EnableInput()

void TLN_EnableInput ( TLN_Player  player,
bool  enable 
)

Enables or disables input for specified player.

Parameters
playerPlayer number to enable (PLAYER1 - PLAYER4)
enableSet true to enable, false to disable

◆ TLN_AssignInputJoystick()

void TLN_AssignInputJoystick ( TLN_Player  player,
int  index 
)

Assigns a joystick index to the specified player.

Parameters
playerPlayer number to configure (PLAYER1 - PLAYER4)
indexJoystick index to assign, 0-based index. -1 = disable

◆ TLN_DefineInputKey()

void TLN_DefineInputKey ( TLN_Player  player,
TLN_Input  input,
uint32_t  keycode 
)

Assigns a keyboard input to a player.

Parameters
playerPlayer number to configure (PLAYER1 - PLAYER4)
inputInput to associate to the given key
keycodeASCII key value or scancode as defined in SDL.h

◆ TLN_DefineInputButton()

void TLN_DefineInputButton ( TLN_Player  player,
TLN_Input  input,
uint8_t  joybutton 
)

Assigns a button joystick input to a player.

Parameters
playerPlayer number to configure (PLAYER1 - PLAYER4)
inputInput to associate to the given button
joybuttonButton index

◆ TLN_DrawFrame()

void TLN_DrawFrame ( int  frame)

Draws a frame to the window.

Parameters
frameOptional frame number. Set to 0 to autoincrement from previous value

Draws a frame to the window

Remarks
If a window has been created with TLN_CreateWindow(), it renders the frame to it. This function is a wrapper to TLN_UpdateFrame which also automatically sets the render target for the window, so when calling this function it is not needed to call TLN_UpdateFrame() too.
See also
TLN_CreateWindow(), TLN_UpdateFrame()

◆ TLN_WaitRedraw()

void TLN_WaitRedraw ( void  )

Thread synchronization for multithreaded window. Waits until the current frame has ended rendering.

See also
TLN_CreateWindowThread()

◆ TLN_DeleteWindow()

void TLN_DeleteWindow ( void  )

Deletes the window previoulsy created with TLN_CreateWindow() or TLN_CreateWindowThread()

See also
TLN_CreateWindow()

◆ TLN_EnableBlur()

void TLN_EnableBlur ( bool  mode)

Removed in release 1.12, use TLN_EnableCRTEffect() instead.

Parameters
modeEnable or disable effect

◆ 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.

Parameters
overlayOne of the enumerated TLN_Overlay types. Choosing TLN_OVERLAY_CUSTOM selects the image passed when calling TLN_CreateWindow
overlay_factorBlend factor for overlay image. 0 is full transparent (no effect), 255 is full blending
thresholdMiddle point of the brightness mapping function
v0output brightness for input brightness = 0
v1output brightness for input brightness = threshold
v2output brightness for input brightness = threshold
v3output brightness for input brightness = 255
bluradds gaussian blur to brightness overlay, softens image
glow_factorblend addition factor for brightness overlay. 0 is not addition, 255 is full addition

This function combines various effects to simulate the output of a CRT monitor with low CPU/GPU usage. A small horizontal blur is added to the frame, simulating the continuous output of a RF modulator where adjacent pixels got mixed. Many graphic designers use this feature where alternating vertical lines are used to create the illusion of more colors or blending. An secondary image is created with overbright pixels. In a real CRT, brighter colors bleed into surrounding area: the pixel size depends somewhat on its brightness. The threshold and v0 to v3 parametes define a two-segment linear mapping between source and destination brightness for the overlay. Optionally the overlay can be softened more using a slight gaussian blur filter te create a kind of "bloom" effect, and finally it is added on top of the frame with the glow_factor value.

See also
TLN_CreateWindow(),TLN_DisableCRTEffect()

◆ TLN_DisableCRTEffect()

void TLN_DisableCRTEffect ( void  )

Disables the CRT post-processing effect.

See also
TLN_EnableCRTEffect()

◆ TLN_SetSDLCallback()

void TLN_SetSDLCallback ( TLN_SDLCallback  callback)

Registers a user-defined callback to capture internal SDL2 events.

Parameters
callbackpointer to user funcion with signature void (SDL_Event*)

◆ TLN_Delay()

void TLN_Delay ( uint32_t  time)

Suspends execition for a fixed time.

Parameters
timeNumber of milliseconds to wait