Functions
Window.c File Reference

Built-in window and user input using libSDL2 https://www.libsdl.org/. More...

Functions

void TLN_SetWindowTitle (const char *title)
 Sets window title. More...
 
bool TLN_CreateWindow (const char *overlay, TLN_WindowFlags flags)
 Creates a window for rendering. More...
 
bool TLN_CreateWindowThread (const char *overlay, TLN_WindowFlags flags)
 Creates a multithreaded window for rendering. More...
 
void TLN_DeleteWindow (void)
 Deletes the window previoulsy created with TLN_CreateWindow() or TLN_CreateWindowThread() More...
 
bool TLN_ProcessWindow (void)
 Does basic window housekeeping in signgle-threaded window. More...
 
bool TLN_IsWindowActive (void)
 Checks window state. More...
 
void TLN_WaitRedraw (void)
 Thread synchronization for multithreaded window. Waits until the current frame has ended rendering. More...
 
void TLN_EnableBlur (bool mode)
 Enables or disables a simple horizontal blur effect to emulate noisy composite video. 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...
 
bool TLN_GetInput (TLN_Input input)
 Returns the state of a given input. More...
 
int TLN_GetLastInput (void)
 Returns the last pressed input button. More...
 
void TLN_BeginWindowFrame (int time)
 Begins active rendering frame in built-in window. More...
 
void TLN_EndWindowFrame (void)
 Finishes rendering the current frame and updates the built-in window. More...
 
void TLN_DrawFrame (int time)
 Draws a frame to the window. More...
 
uint32_t TLN_GetTicks (void)
 Returns the number of milliseconds since application start.
 
void TLN_Delay (uint32_t time)
 Suspends execition for a fixed time. More...
 

Detailed Description

Built-in window and user input using libSDL2 https://www.libsdl.org/.

Author
Megamarc
Date
20 sep 2015

Public Tilengine source code http://www.tilengine.org

Function Documentation

void TLN_SetWindowTitle ( const char *  title)

Sets window title.

Parameters
titleText with the title to set
bool TLN_CreateWindow ( const char *  overlay,
TLN_WindowFlags  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()
bool TLN_CreateWindowThread ( const char *  overlay,
TLN_WindowFlags  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()
void TLN_DeleteWindow ( void  )

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

See also
TLN_CreateWindow()
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()
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()
void TLN_WaitRedraw ( void  )

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

See also
TLN_CreateWindowThread()
void TLN_EnableBlur ( bool  mode)

Enables or disables a simple horizontal blur effect to emulate noisy composite video.

Parameters
modeEnable or disable effect
Remarks
As of release 1.12, this function has been deprecated and doesn't have effect anymore. It has been left only for ABI compatibility. Use the new TLN_EnableCRTEffect instead.
See also
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()
void TLN_DisableCRTEffect ( void  )

Disables the CRT post-processing effect.

See also
TLN_EnableCRTEffect()
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_A
  • INPUT_B
  • INPUT_C
  • INPUT_D
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 four directional buttons (INPUT_UP to INPUT_RIGHT) and four action buttons (INPUT_A to INPUT_D). Directional buttons are mapped to keyboard cursors or joystick D-PAD, and the four action buttons are the keys Z,X,C,V or joystick buttons 1 to 4.

See also
TLN_CreateWindow()
int TLN_GetLastInput ( void  )

Returns the last pressed input button.

See also
TLN_GetInput()
void TLN_BeginWindowFrame ( int  time)

Begins active rendering frame in built-in window.

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()
void TLN_EndWindowFrame ( void  )

Finishes rendering the current frame and updates the built-in window.

See also
TLN_CreateWindow(), TLN_BeginWindowFrame(), TLN_DrawNextScanline()
void TLN_DrawFrame ( int  time)

Draws a frame to the window.

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()
void TLN_Delay ( uint32_t  time)

Suspends execition for a fixed time.

Parameters
timeNumber of milliseconds to wait