Functions
Windowing

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

Description

Functions

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

Function Documentation

TLNAPI bool TLN_CreateWindow ( const char *  overlay,
TLN_WindowFlags  flags 
)
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()
TLNAPI bool TLN_CreateWindowThread ( const char *  overlay,
TLN_WindowFlags  flags 
)
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()
TLNAPI void TLN_SetWindowTitle ( const char *  title)
Parameters
titleText with the title to set
TLNAPI bool TLN_ProcessWindow ( void  )
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()
TLNAPI bool TLN_IsWindowActive ( void  )
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()
TLNAPI bool TLN_GetInput ( TLN_Input  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()
TLNAPI void TLN_EnableInput ( TLN_Player  player,
bool  enable 
)
Parameters
playerPlayer number to enable (PLAYER1 - PLAYER4)
enableSet true to enable, false to disable
TLNAPI void TLN_AssignInputJoystick ( TLN_Player  player,
int  index 
)
Parameters
playerPlayer number to configure (PLAYER1 - PLAYER4)
indexJoystick index to assign, 0-based index. -1 = disable
TLNAPI void TLN_DefineInputKey ( TLN_Player  player,
TLN_Input  input,
uint32_t  keycode 
)
Parameters
playerPlayer number to configure (PLAYER1 - PLAYER4)
inputInput to associate to the given key
keycodeASCII key value or scancode as defined in SDL.h
TLNAPI void TLN_DefineInputButton ( TLN_Player  player,
TLN_Input  input,
uint8_t  joybutton 
)
Parameters
playerPlayer number to configure (PLAYER1 - PLAYER4)
inputInput to associate to the given button
joybuttonButton index
TLNAPI void TLN_DrawFrame ( int  time)
Parameters
timeTimestamp (same value as in TLN_UpdateFrame())

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()
TLNAPI void TLN_WaitRedraw ( void  )
TLNAPI void TLN_DeleteWindow ( void  )
TLNAPI void TLN_EnableBlur ( bool  mode)
Parameters
modeEnable or disable effect
TLNAPI 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 
)
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()
TLNAPI void TLN_DisableCRTEffect ( void  )
TLNAPI void TLN_SetSDLCallback ( TLN_SDLCallback  callback)
Parameters
callbackpointer to user funcion with signature void (SDL_Event*)
TLNAPI void TLN_Delay ( uint32_t  time)
Parameters
timeNumber of milliseconds to wait
TLNAPI void TLN_BeginWindowFrame ( int  time)
Parameters
timeTimestamp (same value as in TLN_UpdateFrame())
Remarks
Use this function instead of TLN_BeginFrame() when using the built-in window
See also
TLN_CreateWindow(), TLN_EndWindowFrame(), TLN_DrawNextScanline()
TLNAPI void TLN_EndWindowFrame ( void  )