Contexts¶

Context parameters¶

struct TCOD_ContextParams¶

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

New in version 1.19.

Public Members

int tcod_version¶: Must be TCOD_COMPILEDVERSION.

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.

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

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

New in version 1.19.

C API¶

struct TCOD_Context¶

A rendering context for libtcod.

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

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

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

New in version 1.16.

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

Change the active tileset for this context.

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

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

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

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

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

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

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

New in version 1.16.