System layer

Note

These docs are incomplete. Several functions and features are better documented by the older 1.6.4 docs which you can find here.

Time functions

Deprecated C functions

Note

These are deprecated because they are not compatible with libtcod contexts or are straight ports of SDL calls. You should use the SDL timing API or tcod::Timer to track time.

uint32_t TCOD_sys_elapsed_milli(void)

Alias for SDL_GetTicks.

Deprecated since version 1.19: You should call SDL_GetTicks directly.

float TCOD_sys_elapsed_seconds(void)

Returns the number of seconds since the start of the program.

Deprecated since version 1.19: Use SDL_GetTicks and convert the result into seconds instead of using this function.

void TCOD_sys_sleep_milli(uint32_t val)

Alias for SDL_Delay.

Deprecated since version 1.19: You should call SDL_Delay directly.

void TCOD_sys_set_fps(int val)

Set the desired framerate.

Deprecated since version 1.19: This function will not affect libtcod contexts. Set the framerate with tcod::Timer instead.

int TCOD_sys_get_fps(void)

Get the current framerate.

Deprecated since version 1.19: This function will not work with libtcod contexts. Use tcod::Timer instead.

float TCOD_sys_get_last_frame_length(void)

Get the delta time between the last two frames.

Deprecated since version 1.19: This function will not work with libtcod contexts. Use tcod::Timer instead.

Timer class

class Timer

A timing class based on SDL’s high performance time counter.

Used to track delta time or set a framerate.

This class is based on using SDL_GetPerformanceCounter to track the time. The time taken between calls to sync() is tracked. This is used to determine the real framerate if requested.

You must add #include <libtcod/timer.hpp> to include ths class.

int desired_fps = 30;
auto timer = tcod::Timer();
while (1) {
  float delta_time = timer.sync(desired_fps);  // desired_fps is optional.
  // ...

New in version 1.19.

Public Functions

inline Timer()

Construct a new Timer object.

inline float sync(int desired_fps = 0)

Sync the time to a given framerate (if provided) and return the delta time compared to the previous call.

If desired_fps is non-zero then this function will block until the desired framerate is reached.

Timing starts once the Timer is constructed.

Parameters

desired_fps – The desired framerate in frames-per-second, or zero to disable framerate limiting.

Returns

The delta time in seconds since the last call to sync is returned as a float.

inline float get_mean_fps() const noexcept

Return the mean framerate.

This is the average of all samples combined.

inline float get_last_fps() const noexcept

Return the framerate of the last call to sync().

inline float get_min_fps() const noexcept

Return the lowest framerate recently sampled.

inline float get_max_fps() const noexcept

Return the highest framerate recently sampled.

inline float get_median_fps() const noexcept

Return the median framerate.

This is the framerate of the middle sample when all samples are sorted.

Easy screenshots

void TCOD_sys_save_screenshot(const char *filename)

Miscellaneous utilities

struct SDL_Window *TCOD_sys_get_sdl_window(void)

Return an SDL_Window pointer if one is in use, returns NULL otherwise.

New in version 1.11.

struct SDL_Renderer *TCOD_sys_get_sdl_renderer(void)

Return an SDL_Renderer pointer if one is in use, returns NULL otherwise.

New in version 1.11.

TCOD_Context *TCOD_sys_get_internal_context(void)

Return the context being used internally by the old API.

This function can be useful to progressively upgrade older code to use the newer API.

New in version 1.19.

Returns

A TCOD_Context pointer, or NULL if the global internals were not initialzed.

TCOD_Console *TCOD_sys_get_internal_console(void)

Return a pointer to the “root console” used internally by the old API.

This is useful for functions which take a console parameter but won’t accept NULL.

New in version 1.19.

Returns

A pointer to TCOD_Console, or NULL if it doesn’t exist.