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¶

class Context¶

A C++ managed tcod context.

See Getting Started for complete examples of how to setup libtcod projects.

// The absolute minimum needed to create a new context in C++.
int main(int argc, char* argv[]) {
  auto params = TCOD_ContextParams{};
  params.tcod_version = TCOD_COMPILEDVERSION;
  auto context = tcod::Context(params);
}

New in version 1.21.

Public Functions

inline explicit Context(const TCOD_ContextParams &params)¶

Construct a new Context object using the provided parameters.

Requires SDL support enabled, otherwise this will throw.

inline explicit Context(ContextPtr &&ptr)¶: Take ownsership of a smart pointer to TCOD_Context.

inline explicit Context(TCOD_Context *ptr)¶: Take ownsership of a raw TCOD_Context pointer.

inline auto get_renderer_type() noexcept -> TCOD_renderer_t ¶: Return the TCOD_renderer_t value of this context which may be different than the one requested.

inline void present(const TCOD_Console &console, const TCOD_ViewportOptions &viewport)¶

Present a console to the display with the provided viewport options.

// tcod::Context context;
while (1) {
  auto console = context.new_console();  // This can be done as an alternative to clearing the console.
  tcod::print(console, {0, 0}, "Hello world", nullptr, nullptr);
  auto viewport_options = TCOD_ViewportOptions{}
  viewport_options.tcod_version = TCOD_COMPILEDVERSION;
  viewport_options.keep_aspect = true;  // Adds letterboxing to keep aspect.
  viewport_options.integer_scaling = true;  // Prevent scaling artifacts with pixelated or low-res glyphs.
  viewport_options.clear_color = {0, 0, 0, 255};
  viewport_options.align_x = 0.5f;
  viewport_options.align_y = 0.5f;
  context.present(console, viewport_options);
  SDL_Event event;
  while (SDL_PollEvent(&event)) {
    if (event.type == SDL_QUIT) std::exit(EXIT_SUCCESS);
  }
}

Parameters

console – The TCOD_Console to render. This console can be any size.
viewport – The viewport options, which can change the way the console is scaled.

inline void present(const TCOD_Console &console)¶

Present a console to the display.

Parameters: console – The TCOD_Console to render. This console can be any size and will be stretched to fit the window.

inline auto get_sdl_window() noexcept -> struct SDL_Window*¶

Return a non-owning pointer to the SDL_Window used by this context.

// tcod::Context context;
if (SDL_Window* sdl_window = context.get_sdl_window(); sdl_window) {
  // Do anything with an SDL window, for example:
  uint32_t flags = SDL_GetWindowFlags(sdl_window);
}

Returns: A struct SDL_Window* pointer. This will be nullptr if this context does not use an SDL window.

inline auto get_sdl_renderer() noexcept -> struct SDL_Renderer*¶

Return a non-owning pointer to the SDL_Renderer used by this context.

// tcod::Context context;
if (SDL_Renderer* sdl_renderer = context.get_sdl_renderer(); sdl_renderer) {
  // Do anything with an SDL renderer, for example:
  SDL_SetRenderDrawColor(sdl_renderer, 0, 0, 0, 255);
  SDL_RenderClear(sdl_renderer);
  SDL_RenderPresent(sdl_renderer);
}

Returns: A struct SDL_Renderer* pointer. This will be nullptr if this context does not use SDL’s renderer.

inline auto pixel_to_tile_coordinates(const std::array<int, 2> &xy) -> std::array<int, 2>¶: Convert pixel coordinates to this contexts integer tile coordinates.

inline auto pixel_to_tile_coordinates(const std::array<double, 2> &xy) -> std::array<double, 2>¶: Convert pixel coordinates to this contexts sub-tile coordinates.

inline void convert_event_coordinates(SDL_Event &event)¶

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

// tcod::Context context;
while (1) {
  SDL_Event event;
  while (SDL_PollEvent(&event)) {
    SDL_Event event_tile = event;  // A copy of `event` using tile coordinates.
    context.convert_event_coordinates(event_tile);
    switch (event.type) {
      case SDL_QUIT:
        std::exit(EXIT_SUCCESS);
      case SDL_MOUSEMOTION:
        event.motion.xrel; // Relative motion in pixels.
        event_tile.motion.xrel; // Relative motion in tiles.
        break;
    }
  }
}

New in version 1.19.

Parameters: event – Any SDL_Event event. If the event type is compatible then its coordinates will be converted into tile coordinates.

inline void save_screenshot(const std::filesystem::path &path)¶

Save a screenshot to path.

Parameters: path – The file path to save the screenshot to.

inline void save_screenshot()¶: Save a screenshot with a unique filename in the working directly.

inline auto new_console(int min_columns = 1, int min_rows = 1, float magnification = 1.0f) -> tcod::Console ¶

Return a new console with a size automatically determined by the context.

// tcod::Context context;
while (1) {
  auto console = context.new_console();  // Can be an alternative to clearing the console.
  tcod::print(console, {0, 0}, "Hello world", std::nullopt, std::nullopt);
  context.present(console);
  SDL_Event event;
  while (SDL_PollEvent(&event)) {  // SDL_PollEvent may resize the window.
    if (event.type == SDL_QUIT) std::exit(EXIT_SUCCESS);
  }
}

Parameters

min_columns – The minimum width to use for the new console, in tiles.
min_rows – The minimum height to use for the new console, in tiles.
magnification – Determines the apparent size of the tiles that will be rendered by a console created with the output values. A magnification larger then 1.0f will output smaller console parameters, which will show as larger tiles when presented. Only values larger than zero are allowed.

Returns

Returns a tcod::Console of a dynamic size.

inline auto change_tileset(tcod::Tileset &new_tileset) -> void¶: Replace this contexts tileset with a different one.

inline auto get_ptr() noexcept -> ContextPtr&¶

Access the context pointer.

Modifying this pointer may make the class invalid.

inline auto get_ptr() const noexcept -> const ContextPtr&¶: Access the const context pointer.

inline auto close() -> void¶

Close and delete the objects managed by this context.

This object will no longer be valid unless reset.

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.