Contexts¶

Context parameters¶

struct TCOD_ContextParams¶

A struct of parameters used to create a new context with TCOD_context_new.

Added in version 1.19.

Public Members

int tcod_version¶

Compiled libtcod version for ABI compatiblity with older versions of libtcod.

Deprecated:: Deprecated since 2.0.

You must no longer assign anything to this.

int window_x¶

window_x and window_y are the starting position of the window.

These are SDL parameters so values like SDL_WINDOWPOS_UNDEFINED and SDL_WINDOWPOS_CENTERED are acceptable.

Values of zero will be converted to SDL_WINDOWPOS_UNDEFINED unless window_xy_defined is true.

int window_y¶

int pixel_width¶

pixel_width and pixel_height are the desired size of the window in pixels.

If these are zero then they’ll be derived from columns, rows, and the tileset.

int pixel_height¶

int columns¶

columns and rows are the desired size of the terminal window.

Usually you’ll set either these or the pixel resolution.

If you are setting these values from a TCOD_Console then you should set the console attribute instead.

int rows¶

int renderer_type¶: renderer_type is one of the TCOD_renderer_t values.

TCOD_Tileset *tileset¶

tileset is an optional pointer to a tileset object.

If this is NULL then a platform specific fallback tileset will be used. This fallback is known to be unreliable, but it should work well enough for prototyping code.

int vsync¶

If vsync is true, then vertical sync will be enabled whenever possible.

A value of true is recommended.

int sdl_window_flags¶

sdl_window_flags is a bitfield of SDL_WindowFlags flags.

For a window, a value of SDL_WINDOW_RESIZABLE is recommended. For fullscreen, a value of SDL_WINDOW_RESIZABLE | SDL_WINDOW_FULLSCREEN_DESKTOP is recommended. You should avoid the SDL_WINDOW_FULLSCREEN flag whenever possible.

const char *window_title¶

window_title will be the title of the opened window.

If not set then argv[0] will be used if available.

int argc¶: The number of items in argv.

const char *const *argv¶

argc and argv are optional CLI parameters.

You can pass 0 and NULL respectfully to ignore them. If unsure then you should pass the argc and argv arguments from your main function.

void (*cli_output)(void *userdata, const char *output)¶

If user attention is required for the given CLI parameters then cli_output will be called with cli_userdata and an error or help message.

If cli_output is NULL then it will print the message to stdout and terminate the program. If cli_output returns normally then TCOD_E_REQUIRES_ATTENTION will be returned from TCOD_context_new.

void *cli_userdata¶: This is passed to the userdata parameter of cli_output if called.

bool window_xy_defined¶: If this is false then window_x/window_y parameters of zero are assumed to be undefined and will be changed to SDL_WINDOWPOS_UNDEFINED.

TCOD_Console *console¶

A console to be used as a reference for the desired window size.

This can set as an alternative to the columns and rows attributes.

Added in version 1.19.

C++ API¶

Warning

doxygenclass: Cannot find class “tcod::Context” in doxygen xml output for project “libtcod” from directory: doxyxml/

inline auto tcod::new_context(const TCOD_ContextParams &params, TCOD_Error &out_code) -> ContextPtr ¶

Initialize and return a new libtcod context.

Also returns an error code for non-critical issues.

For critical issues an exception is thrown as usual. Non-critical issues are things such as being unable to create a desired renderer and using to a fallback instead.

Added in version 1.19.

Parameters:

params – Options to configure the new context with.
out_code – Will be set to an error code on non-critical issues.

Returns:

ContextPtr A pointer to the new context.

inline auto tcod::new_context(const TCOD_ContextParams &params) -> ContextPtr ¶

Initialize and return a new libtcod context.

Parameters:

params – Options to configure the new context with.

Returns:

ContextPtr A pointer to the new context.

Added in version 1.19.

C API¶

struct TCOD_Context¶

A rendering context for libtcod.

Added in version 1.16.

TCOD_Error TCOD_context_new(const TCOD_ContextParams *params, TCOD_Context **out)¶

Create a new context with the given parameters.

params is a non-NULL pointer to a TCOD_ContextParams struct. See its documentation for info on the parameters.

out is the output for the TCOD_Context, must not be NULL.

Added in version 1.16.

TCOD_Error TCOD_context_present(struct TCOD_Context *context, const struct TCOD_Console *console, const struct TCOD_ViewportOptions *viewport)¶

Present a console to the screen, using a rendering context.

console is the console to present, the console can be any size.

viewport is the optional viewport options to use. This will affect the scaling of the console with the current context. This can be NULL to use the default options, which are to stretch the console to fit the screen.

Added in version 1.16.

TCOD_Error TCOD_context_recommended_console_size(struct TCOD_Context *context, float magnification, int *columns, int *rows)¶

Set columns and rows to the recommended console size for this context.

magnification determines the apparent size of the tiles on the output. Values of 0.0f or lower will default to 1.0f.

Added in version 1.16.

TCOD_Error TCOD_context_change_tileset(struct TCOD_Context *self, TCOD_Tileset *tileset)¶

Change the active tileset for this context.

Added in version 1.16.

int TCOD_context_get_renderer_type(struct TCOD_Context *context)¶

Return the TCOD_renderer_t renderer type for this context.

Returns a negative number on error, such as context being NULL.

Added in version 1.16.

TCOD_Error TCOD_context_screen_pixel_to_tile_d(struct TCOD_Context *context, double *x, double *y)¶

Convert the screen coordinates to tile coordinates for this context.

x and y are the pointers to the screen coordinates, these will be converted to tile coordinates after the call to this function.

The parameters given to the last call to TCOD_context_present will determine where the tiles are for this call.

Added in version 1.16.

TCOD_Error TCOD_context_screen_pixel_to_tile_i(struct TCOD_Context *context, int *x, int *y)¶

Convert the screen coordinates to integer tile coordinates for this context.

Save as TCOD_context_screen_pixel_to_tile but the inputs and results are integers. This is useful if you don’t need sub-tile coordinates.

Added in version 1.16.

TCOD_Error TCOD_context_convert_event_coordinates(struct TCOD_Context *context, union SDL_Event *event)¶

Convert the pixel coordinates of SDL mouse events to the tile coordinates of the current context.

Added in version 1.19.

TCOD_Error TCOD_context_save_screenshot(struct TCOD_Context *context, const char *filename)¶

Save the last presented console to a PNG file.

Added in version 1.16.

struct SDL_Window *TCOD_context_get_sdl_window(struct TCOD_Context *context)¶

Return a pointer the SDL_Window for this context if it uses one.

Added in version 1.16.

struct SDL_Renderer *TCOD_context_get_sdl_renderer(struct TCOD_Context *context)¶

Return a pointer the SDL_Renderer for this context if it uses one.

Added in version 1.16.