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
andwindow_y
are the starting position of the window.These are SDL parameters so values like
SDL_WINDOWPOS_UNDEFINED
andSDL_WINDOWPOS_CENTERED
are acceptable.Values of zero will be converted to
SDL_WINDOWPOS_UNDEFINED
unlesswindow_xy_defined
is true.
-
int window_y¶
-
int pixel_width¶
pixel_width
andpixel_height
are the desired size of the window in pixels.If these are zero then they’ll be derived from
columns
,rows
, and thetileset
.
-
int pixel_height¶
-
int columns¶
columns
androws
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 theTCOD_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 ofSDL_WINDOW_RESIZABLE | SDL_WINDOW_FULLSCREEN_DESKTOP
is recommended. You should avoid theSDL_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
andargv
are optional CLI parameters.You can pass
0
andNULL
respectfully to ignore them. If unsure then you should pass theargc
andargv
arguments from yourmain
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 withcli_userdata
and an error or help message.If
cli_output
is NULL then it will print the message to stdout and terminate the program. Ifcli_output
returns normally then TCOD_E_REQUIRES_ATTENTION will be returned fromTCOD_context_new
.
-
void *cli_userdata¶
This is passed to the
userdata
parameter ofcli_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 toSDL_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.
-
int tcod_version¶
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 ¶ms, 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 ¶ms) -> 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 theTCOD_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
androws
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
andy
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.