Console

Note

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

tcod::Console

class Console

A managed libtcod console containing a grid of tiles with {ch, fg, bg} information.

Note that all tile references are to TCOD_ConsoleTile structs and will include an alpha channel.

auto console = tcod::Console{80, 50};
console.at({1, 1}).ch = '@';  // Bounds-checked references to a tile.
console[{1, 1}].bg = {0, 0, 255, 255};  // Access a tile without bounds checking, colors are RGBA.
if (console.in_bounds({100, 100})) {}  // Test if an index is in bounds.
for (auto& tile : console) tile.fg = {255, 255, 0, 255};  // Iterate over all tiles on a console.
for (auto& tile : console) tile = {0x20, {255, 255, 255, 255}, {0, 0, 0, 255}};  // Same as clearing all tiles.
for (int y = 0; y < console.get_height(); ++y) {
  for (int x = 0; x < console.get_width(); ++x) {
    auto& tile = console.at({x, y});  // Iterate over the coordinates of a console.
  }
}

New in version 1.19.

Public Functions

inline Console()

Default initializer.

inline explicit Console(int width, int height)

Create a new Console with the given size.

Parameters
  • width – The number of columns in the new console.

  • height – The number of rows in the new console.

inline explicit Console(const std::array<int, 2> &size)

Create a new Console with the given size.

Parameters

size – The new console size of {width, height}.

inline explicit Console(const Console &other)

Clone the shape and tile data of a Console.

inline explicit Console(ConsolePtr ptr)

Pass ownership of a ConsolePtr to a new Console.

Parameters

ptr – A tcod::ConsolePtr, must not be nullptr.

inline explicit Console(TCOD_Console *ptr)

Takes ownership of a raw TCOD_Console pointer.

Parameters

ptr – A pointer which will now be managed by this Console object. Must not be nullptr.

inline Console &operator=(const Console &rhs)

Copy the shape and tile data of another console.

Console(Console&&) noexcept = default

Standard move constructor.

inline Console &operator=(Console &&rhs) noexcept

Standard move assignment.

~Console() noexcept = default

Standard destructor.

inline operator TCOD_Console&()

Allow implicit conversions to a TCOD_Console reference.

inline operator const TCOD_Console&() const

Allow implicit conversions to a const TCOD_Console reference.

inline auto get() noexcept -> TCOD_Console*

Return a pointer to the internal TCOD_Console struct.

inline auto get() const noexcept -> const TCOD_Console*

Return a const pointer to the internal TCOD_Console struct.

inline auto release() noexcept -> TCOD_Console*

Release ownership of this Console’s TCOD_Console* and return the pointer.

Using this Console afterwards is undefined.

inline auto begin() noexcept -> TCOD_ConsoleTile*

Return a pointer to the beginning of this consoles tile data.

inline auto begin() const noexcept -> const TCOD_ConsoleTile*

Return a const pointer to the beginning of this consoles tile data.

inline auto end() noexcept -> TCOD_ConsoleTile*

Return a pointer to the end of this consoles tile data.

inline auto end() const noexcept -> const TCOD_ConsoleTile*

Return a const pointer to the end of this consoles tile data.

inline auto get_width() const noexcept -> int

Return the width of this console.

inline auto get_height() const noexcept -> int

Return the height of this console.

inline auto get_shape() const noexcept -> std::array<int, 2>

Return the {width, height} shape of this console as a std::array<int, 2>.

auto console = tcod::Console{80, 50};
auto same_size = tcod::Console{console.get_shape()}  // New console with the same shape of the previous one.
inline void clear(const TCOD_ConsoleTile &tile = {0x20, {255, 255, 255, 255}, {0, 0, 0, 255}}) noexcept

Clear a console by setting all tiles to the provided TCOD_ConsoleTile object.

// New consoles start already cleared with the space character, a white foreground, and a black background.
auto console = tcod::Console{80, 50};
console.clear()  // Clear with the above mentioned defaults.
console.clear({0x20, {255, 255, 255, 255}, {0, 0, 0, 255}});  // Same as the above.
console.clear({0x20, tcod::ColorRGB{255, 255, 255}, tcod::ColorRGB{0, 0, 0}})  // Also same as the above.

Parameters

tile – A TCOD_ConsoleTile reference which will be used to clear the console.

inline auto operator[](const std::array<int, 2> &xy) noexcept -> TCOD_ConsoleTile&

Return a reference to the tile at xy.

inline auto operator[](const std::array<int, 2> &xy) const noexcept -> const TCOD_ConsoleTile&

Return a constant reference to the tile at xy.

inline auto at(const std::array<int, 2> &xy) -> TCOD_ConsoleTile&

Return a reference to the tile at xy.

Throws

std::out_of_range – if the index is out-of-bounds

inline auto at(const std::array<int, 2> &xy) const -> const TCOD_ConsoleTile&

Return a constant reference to the tile at xy.

Throws

std::out_of_range – if the index is out-of-bounds

inline auto at(int x, int y) -> TCOD_ConsoleTile&

Return a reference to the tile at x,y.

Throws

std::out_of_range – if the index is out-of-bounds

inline auto at(int x, int y) const -> const TCOD_ConsoleTile&

Return a constant reference to the tile at x,y.

Throws

std::out_of_range – if the index is out-of-bounds

inline bool in_bounds(const std::array<int, 2> &xy) const noexcept

Return true if xy are within the bounds of this console.

Friends

inline friend void swap(Console &lhs, Console &rhs) noexcept

Swap two console objects.

TCOD_Console

struct TCOD_Console

A libtcod console containing a grid of tiles with {ch, fg, bg} information.

In C++ this struct has several convience methods to make working with consoles easier. Note that all tile references are to TCOD_ConsoleTile structs and will include an alpha channel.

For C++ code examples see tcod::Console.

New in version 1.19.

Public Functions

inline auto begin() noexcept -> TCOD_ConsoleTile*

Return a pointer to the beginning of this consoles tile data.

inline auto begin() const noexcept -> const TCOD_ConsoleTile*

Return a const pointer to the beginning of this consoles tile data.

inline auto end() noexcept -> TCOD_ConsoleTile*

Return a pointer to the end of this consoles tile data.

inline auto end() const noexcept -> const TCOD_ConsoleTile*

Return a const pointer to the end of this consoles tile data.

inline void clear(const TCOD_ConsoleTile &tile = {0x20, {255, 255, 255, 255}, {0, 0, 0, 255}}) noexcept

Clear a console by setting all tiles to the provided TCOD_ConsoleTile object.

Parameters

tile – A TCOD_ConsoleTile reference which will be used to clear the console.

inline auto operator[](const std::array<int, 2> &xy) noexcept -> TCOD_ConsoleTile&

Return a reference to the tile at xy.

inline auto operator[](const std::array<int, 2> &xy) const noexcept -> const TCOD_ConsoleTile&

Return a constant reference to the tile at xy.

inline auto at(const std::array<int, 2> &xy) -> TCOD_ConsoleTile&

Return a reference to the tile at xy.

Throws

std::out_of_range – if the index is out-of-bounds

inline auto at(const std::array<int, 2> &xy) const -> const TCOD_ConsoleTile&

Return a constant reference to the tile at xy.

Throws

std::out_of_range – if the index is out-of-bounds

inline auto at(int x, int y) -> TCOD_ConsoleTile&

Return a reference to the tile at x,y.

Throws

std::out_of_range – if the index is out-of-bounds

inline auto at(int x, int y) const -> const TCOD_ConsoleTile&

Return a constant reference to the tile at x,y.

Throws

std::out_of_range – if the index is out-of-bounds

inline int get_index(const std::array<int, 2> &xy) const noexcept

Convert xy into a 1-dimensional index.

Out-of-bounds indexes are undefined.

This index is normally used to index the tiles attribute.

inline bool in_bounds(const std::array<int, 2> &xy) const noexcept

Return true if xy are within the bounds of this console.

Public Members

int w

Console width and height in tiles.

int h
TCOD_ConsoleTile *tiles

A contiguous array of console tiles.

TCOD_bkgnd_flag_t bkgnd_flag

Default background operator for print & print_rect functions.

TCOD_alignment_t alignment

Default alignment for print & print_rect functions.

TCOD_color_t fore

Foreground (text) and background colors.

TCOD_color_t back
bool has_key_color

True if a key color is being used.

TCOD_color_t key_color

The current key color for this console.

int elements

The total length of the tiles array.

Same as w * h.

New in version 1.16.

void *userdata

A userdata attribute which can be repurposed.

New in version 1.16.

void (*on_delete)(struct TCOD_Console *self)

Internal use.

typedef std::unique_ptr<struct TCOD_Console, ConsoleDeleter> tcod::ConsolePtr

A unique pointer to a TCOD_Console.

New in version 1.19.

struct TCOD_ConsoleTile

The raw data for a single TCOD_Console tile.

New in version 1.19.

Public Members

int ch

The Unicode codepoint for this tile.

TCOD_ColorRGBA fg

The tile glyph color, rendered on top of the background.

TCOD_ColorRGBA bg

The tile background color, rendered behind the glyph.

Initializing the console

Creating the game window

enum TCOD_renderer_t

Libtcod rendering modes.

Values:

enumerator TCOD_RENDERER_GLSL

Alias for TCOD_RENDERER_OPENGL2.

enumerator TCOD_RENDERER_OPENGL

An OpenGL 1.1 implementation.

Performs worse than TCOD_RENDERER_GLSL without many benefits.

Deprecated since version 1.23: This renderer has been removed.

enumerator TCOD_RENDERER_SDL

A software based renderer.

The font file is loaded into RAM instead of VRAM in this implementation.

Deprecated since version 1.23: This renderer has been removed.

enumerator TCOD_RENDERER_SDL2

A new SDL2 renderer.

Allows the window to be resized.

You may set SDL_HINT_RENDER_SCALE_QUALITY to determine the tileset upscaling filter. Either nearest or linear. The hint will only take effect if it’s set before this renderer is created.

New in version 1.8.

enumerator TCOD_RENDERER_OPENGL2

A new OpenGL 2.0 core renderer.

Allows the window to be resized.

You may set SDL_HINT_RENDER_SCALE_QUALITY to determine the tileset upscaling filter. Either nearest or linear. The hint will take effect on the next frame.

New in version 1.9.

Changed in version 1.11: This renderer now uses OpenGL 2.0 instead of 2.1.

Changed in version 1.16: Now checks the SDL_HINT_RENDER_SCALE_QUALITY hint.

Deprecated since version 1.23: This renderer has been removed.

enumerator TCOD_RENDERER_XTERM

A renderer targeting modern XTerm terminals with 24-bit color support.

This is an experimental renderer with partial support for XTerm and SSH. This will work best on those terminals.

Terminal inputs and events will be passed to SDL’s event system.

There is poor support for ANSI escapes on Windows 10. It is not recommended to use this renderer on Windows.

New in version 1.20.

enumerator TCOD_NB_RENDERERS
TCOD_Error TCOD_console_init_root(int w, int h, const char *title, bool fullscreen, TCOD_renderer_t renderer)

Initialize the libtcod graphical engine.

You may want to call TCOD_console_set_custom_font BEFORE calling this function. By default this function loads libtcod’s terminal.png image from the working directory.

Afterwards TCOD_quit must be called before the program exits.

Returns 0 on success, or -1 on an error, you can check the error with TCOD_sys_get_error()

renderer and vsync settings can be overridden by the TCOD_RENDERER or TCOD_VSYNC environment variables.

Valid case-sensitive options for TCOD_RENDERER are:

  • sdl

  • opengl

  • glsl

  • sdl2

  • opengl2

Valid options for TCOD_VSYNC are 0 or 1.

Changed in version 1.12: Now returns -1 on error instead of crashing.

Changed in version 1.13: Added the TCOD_RENDERER and TCOD_VSYNC overrides.

Parameters
  • w – The width in tiles.

  • h – The height in tiles.

  • title – The title for the window.

  • fullscreen – Fullscreen option.

  • renderer – Which renderer to use when rendering the console.

void TCOD_quit(void)

Shutdown libtcod.

This must be called before your program exits.

New in version 1.8.

Using a custom bitmap font

enum TCOD_font_flags_t

These font flags can be OR’d together into a bit-field and passed to TCOD_console_set_custom_font.

Values:

enumerator TCOD_FONT_LAYOUT_ASCII_INCOL

Tiles are arranged in column-major order.

   0 3 6
   1 4 7
   2 5 8
enumerator TCOD_FONT_LAYOUT_ASCII_INROW

Tiles are arranged in row-major order.

   0 1 2
   3 4 5
   6 7 8
enumerator TCOD_FONT_TYPE_GREYSCALE

Converts all tiles into a monochrome gradient.

enumerator TCOD_FONT_TYPE_GRAYSCALE
enumerator TCOD_FONT_LAYOUT_TCOD

A unique layout used by some of libtcod’s fonts.

enumerator TCOD_FONT_LAYOUT_CP437

Decode a code page 437 tileset into Unicode code-points.

New in version 1.10.

TCOD_Error TCOD_console_set_custom_font(const char *fontFile, int flags, int nb_char_horiz, int nb_char_vertic)

Using custom characters mapping

void TCOD_console_map_ascii_code_to_font(int asciiCode, int fontCharX, int fontCharY)
void TCOD_console_map_ascii_codes_to_font(int asciiCode, int nbCodes, int fontCharX, int fontCharY)
void TCOD_console_map_string_to_font(const char *s, int fontCharX, int fontCharY)

Fullscreen mode

void TCOD_console_set_fullscreen(bool fullscreen)

Set the display to be full-screen or windowed.

Parameters

fullscreen – If true the display will go full-screen.

bool TCOD_console_is_fullscreen(void)

Return true if the display is full-screen.

Communicate with the window manager

bool TCOD_console_is_active(void)

Return true if the window has keyboard focus.

bool TCOD_console_has_mouse_focus(void)

Return true if the window has mouse focus.

bool TCOD_console_is_window_closed(void)

Return true if the window is closing.

void TCOD_console_set_window_title(const char *title)

Change the title string of the active window.

Parameters

title – A utf8 string.

libtcod’s Credits

void TCOD_console_credits(void)
void TCOD_console_credits_reset(void)
bool TCOD_console_credits_render(int x, int y, bool alpha)
bool TCOD_console_credits_render_ex(TCOD_Console *console, int x, int y, bool alpha, float delta_time)

Render a libtcod credit animation to a console.

New in version 1.19.

Parameters
  • console – The console to render to.

  • x

  • y

  • alpha

  • delta_time – Delta time in seconds.

Returns

Returns true once the credits animation has ended.

Drawing on the console

Basic drawing functions

void TCOD_console_set_default_foreground(TCOD_Console *con, TCOD_color_t col)
void TCOD_console_set_default_background(TCOD_Console *con, TCOD_color_t col)
void TCOD_console_set_background_flag(TCOD_Console *con, TCOD_bkgnd_flag_t flag)

Set a consoles default background flag.

Parameters
  • con – A console pointer.

  • flag – One of TCOD_bkgnd_flag_t.

void TCOD_console_clear(TCOD_Console *con)

Clear a console to its default colors and the space character code.

void TCOD_console_put_char(TCOD_Console *con, int x, int y, int c, TCOD_bkgnd_flag_t flag)

Draw a character on a console using the default colors.

Parameters
  • con – A console pointer.

  • x – The X coordinate, the left-most position being 0.

  • y – The Y coordinate, the top-most position being 0.

  • c – The character code to place.

  • flag – A TCOD_bkgnd_flag_t flag.

void TCOD_console_put_char_ex(TCOD_Console *con, int x, int y, int c, TCOD_color_t fore, TCOD_color_t back)

Draw a character on the console with the given colors.

Parameters
  • con – A console pointer.

  • x – The X coordinate, the left-most position being 0.

  • y – The Y coordinate, the top-most position being 0.

  • c – The character code to place.

  • fore – The foreground color.

  • back – The background color. This color will not be blended.

void TCOD_console_set_char(TCOD_Console *con, int x, int y, int c)

Change a character on a console tile, without changing its colors.

Parameters
  • con – A console pointer.

  • x – The X coordinate, the left-most position being 0.

  • y – The Y coordinate, the top-most position being 0.

  • c – The character code to set.

void TCOD_console_set_char_foreground(TCOD_Console *con, int x, int y, TCOD_color_t col)

Change the foreground color of a console tile.

Parameters
  • con – A console pointer.

  • x – The X coordinate, the left-most position being 0.

  • y – The Y coordinate, the top-most position being 0.

  • col – The foreground color to set.

void TCOD_console_set_char_background(TCOD_Console *con, int x, int y, TCOD_color_t col, TCOD_bkgnd_flag_t flag)

Blend a background color onto a console tile.

Parameters
  • con – A console pointer.

  • x – The X coordinate, the left-most position being 0.

  • y – The Y coordinate, the top-most position being 0.

  • col – The background color to blend.

  • flag – The blend mode to use.

void TCOD_console_rect(TCOD_Console *con, int x, int y, int rw, int rh, bool clear, TCOD_bkgnd_flag_t flag)

Draw a rectangle onto a console.

Parameters
  • con – A console pointer.

  • x – The starting region, the left-most position being 0.

  • y – The starting region, the top-most position being 0.

  • rw – The width of the rectangle.

  • rh – The height of the rectangle.

  • clear – If true the drawing region will be filled with spaces.

  • flag – The blending flag to use.

TCOD_Error TCOD_console_draw_rect_rgb(TCOD_Console *console, int x, int y, int width, int height, int ch, const TCOD_color_t *fg, const TCOD_color_t *bg, TCOD_bkgnd_flag_t flag)

Draw a rectangle on a console with a shape of x,y,width,height.

If ch is 0 then the character code will not be updated.

If fg,bg is NULL then their respective colors will not be updated.

TCOD_Error TCOD_console_draw_frame_rgb(struct TCOD_Console *con, int x, int y, int width, int height, const int *decoration, const TCOD_ColorRGB *fg, const TCOD_ColorRGB *bg, TCOD_bkgnd_flag_t flag, bool clear)

Draw a decorated frame onto console with the shape of x, y, width, height.

decoration[9] is an optional array of Unicode codepoints. If left as NULL then a single-pipe decoration is used by default.

If decoration[9] is given the codepoints are used for the edges, corners, and fill of the frame in this order:

0 1 2
3 4 5
6 7 8
If fg or bg is NULL then their respective colors will not be updated.

If clear is true then the inner area of the frame is filled with the inner decoration, which is typically space.

New in version 1.19.

void TCOD_console_hline(TCOD_Console *con, int x, int y, int l, TCOD_bkgnd_flag_t flag)

Draw a horizontal line using the default colors.

This function makes assumptions about the fonts character encoding. It will fail if the font encoding is not cp437.

Parameters
  • con – A console pointer.

  • x – The starting X coordinate, the left-most position being 0.

  • y – The starting Y coordinate, the top-most position being 0.

  • l – The width of the line.

  • flag – The blending flag.

void TCOD_console_vline(TCOD_Console *con, int x, int y, int l, TCOD_bkgnd_flag_t flag)

Draw a vertical line using the default colors.

This function makes assumptions about the fonts character encoding. It will fail if the font encoding is not cp437.

Parameters
  • con – A console pointer.

  • x – The starting X coordinate, the left-most position being 0.

  • y – The starting Y coordinate, the top-most position being 0.

  • l – The height of the line.

  • flag – The blending flag.

Drawing functions (C++)

inline void tcod::draw_rect(TCOD_Console &console, const std::array<int, 4> &rect, int ch, std::optional<TCOD_ColorRGB> fg, std::optional<TCOD_ColorRGB> bg, TCOD_bkgnd_flag_t flag = TCOD_BKGND_SET)

Fill a region with the given graphic.

auto console = tcod::Console{80, 50};
// Draw a red background without replacing any foreground glyphs/colors.
tcod::draw_rect(console, {2, 2, 24, 24}, 0, std::nullopt, tcod::ColorRGB{255, 0, 0});
// Draw a horizontal bar.
tcod::draw_rect(console, {8, 8, 16, 1}, '-', {{255, 255, 255}}, std::nullopt);

New in version 1.19.

Parameters
  • console – A reference to a TCOD_Console.

  • rect – An {x, y, width, height} rectangle, starting from the upper-left-most tile as zero.

  • ch – The character to draw. If zero then the characters in the drawing region will not be changed.

  • fg – The foreground color. The printed text is set to this color. If std::nullopt then the foreground will be left unchanged, inheriting the previous value of the tile.

  • bg – The background color. The background tile under the printed text is set to this color. If std::nullopt then the background will be left unchanged.

  • flag – The background blending flag.

inline void tcod::draw_frame(TCOD_Console &console, const std::array<int, 4> &rect, const std::array<int, 9> &decoration, std::optional<TCOD_ColorRGB> fg, std::optional<TCOD_ColorRGB> bg, TCOD_bkgnd_flag_t flag = TCOD_BKGND_SET, bool clear = true)

Draw a decorative frame.

decoration is given the codepoints to be used for the edges, corners, and fill of the frame in this order:

0 1 2
3 4 5
6 7 8
auto console = tcod::Console{80, 50};
static constexpr std::array<int, 9> LEGEND = {'0', '1', '2', '3', '4', '5', '6', '7', '8'};
tcod::draw_frame(console, {0, 0, 3, 3}, LEGEND, {{255, 255, 255}}, {{0, 0, 0}});

New in version 1.19.

Parameters
  • console – A reference to a TCOD_Console.

  • rect – An {x, y, width, height} rectangle, starting from the upper-left-most tile as zero.

  • decoration – The codepoints to use for the frame in row-major order.

  • fg – The foreground color. The printed text is set to this color. If std::nullopt then the foreground will be left unchanged, inheriting the previous value of the tile.

  • bg – The background color. The background tile under the printed text is set to this color. If std::nullopt then the background will be left unchanged.

  • flag – The background blending flag.

  • clear – If true then the center area will be cleared with the center decoration.

Background effect flags

enum TCOD_bkgnd_flag_t

Background color blend modes.

Values:

enumerator TCOD_BKGND_NONE
enumerator TCOD_BKGND_SET
enumerator TCOD_BKGND_MULTIPLY
enumerator TCOD_BKGND_LIGHTEN
enumerator TCOD_BKGND_DARKEN
enumerator TCOD_BKGND_SCREEN
enumerator TCOD_BKGND_COLOR_DODGE
enumerator TCOD_BKGND_COLOR_BURN
enumerator TCOD_BKGND_ADD
enumerator TCOD_BKGND_ADDA
enumerator TCOD_BKGND_BURN
enumerator TCOD_BKGND_OVERLAY
enumerator TCOD_BKGND_ALPH
enumerator TCOD_BKGND_DEFAULT

String printing alignment

enum TCOD_alignment_t

Print justification options.

Values:

enumerator TCOD_LEFT
enumerator TCOD_RIGHT
enumerator TCOD_CENTER
void TCOD_console_set_alignment(TCOD_Console *con, TCOD_alignment_t alignment)

Set a consoles default alignment.

Parameters
  • con – A console pointer.

  • alignment – One of TCOD_alignment_t

TCOD_alignment_t TCOD_console_get_alignment(TCOD_Console *con)

Return a consoles default alignment.

Reading the content of the console

int TCOD_console_get_width(const TCOD_Console *con)

Return the width of a console.

int TCOD_console_get_height(const TCOD_Console *con)

Return the height of a console.

int TCOD_console_get_char(const TCOD_Console *con, int x, int y)

Return a character code of a console at x,y.

Parameters
  • con – A console pointer.

  • x – The X coordinate, the left-most position being 0.

  • y – The Y coordinate, the top-most position being 0.

Returns

The character code.

TCOD_color_t TCOD_console_get_char_foreground(const TCOD_Console *con, int x, int y)

Return the foreground color of a console at x,y.

Parameters
  • con – A console pointer.

  • x – The X coordinate, the left-most position being 0.

  • y – The Y coordinate, the top-most position being 0.

Returns

A TCOD_color_t struct with a copy of the foreground color.

TCOD_color_t TCOD_console_get_char_background(const TCOD_Console *con, int x, int y)

Return the background color of a console at x,y.

Parameters
  • con – A console pointer.

  • x – The X coordinate, the left-most position being 0.

  • y – The Y coordinate, the top-most position being 0.

Returns

A TCOD_color_t struct with a copy of the background color.

TCOD_color_t TCOD_console_get_default_foreground(TCOD_Console *con)
TCOD_color_t TCOD_console_get_default_background(TCOD_Console *con)
TCOD_bkgnd_flag_t TCOD_console_get_background_flag(TCOD_Console *con)

Return a consoles default background flag.

Screen fading functions

void TCOD_console_set_fade(uint8_t val, TCOD_color_t fade_color)

Fade the color of the display.

Parameters
  • val – Where at 255 colors are normal and at 0 colors are completely faded.

  • fade_color – Color to fade towards.

    Deprecated since version 1.19: This function will not work with libtcod contexts.

uint8_t TCOD_console_get_fade(void)

Return the fade value.

Returns

At 255 colors are normal and at 0 colors are completely faded.

TCOD_color_t TCOD_console_get_fading_color(void)

Return the fade color.

Returns

The current fading color.

ASCII constants

enum TCOD_chars_t

Non-standard special character codes.

Deprecated:

Modern libtcod programs should always uses the Unicode codepoint of special characters and never this enum.

Values:

Printing to the console

Printing functions using UTF-8

TCOD_Error TCOD_console_printf(TCOD_Console *con, int x, int y, const char *fmt, ...)

Format and print a UTF-8 string to a console.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

TCOD_Error TCOD_console_printf_ex(TCOD_Console *con, int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, ...)

Format and print a UTF-8 string to a console.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

int TCOD_console_printf_rect(TCOD_Console *con, int x, int y, int w, int h, const char *fmt, ...)

Format and print a UTF-8 string to a console.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

int TCOD_console_printf_rect_ex(TCOD_Console *con, int x, int y, int w, int h, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, ...)

Format and print a UTF-8 string to a console.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

int TCOD_console_get_height_rect_fmt(TCOD_Console *con, int x, int y, int w, int h, const char *fmt, ...)

Return the number of lines that would be printed by this formatted string.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

TCOD_Error TCOD_console_printf_frame(TCOD_Console *con, int x, int y, int w, int h, int empty, TCOD_bkgnd_flag_t flag, const char *fmt, ...)

Print a framed and optionally titled region to a console, using default colors and alignment.

This function uses Unicode box-drawing characters and a UTF-8 formatted string.

New in version 1.8.

Changed in version 1.16: Now returns a negative error code on failure.

TCOD_Error TCOD_console_printn(TCOD_Console *console, int x, int y, size_t n, const char *str, const TCOD_ColorRGB *fg, const TCOD_ColorRGB *bg, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment)

Print a string of a specified length to a console.

New in version 1.19.

Parameters
  • console – A pointer to a TCOD_Console.

  • x – The starting X position, starting from the left-most tile as zero.

  • y – The starting Y position, starting from the upper-most tile as zero.

  • n – The length of the string buffer str[n] in bytes.

  • str – The text to print. This string can contain libtcod color codes.

  • fg – The foreground color. The printed text is set to this color. If NULL then the foreground will be left unchanged, inheriting the previous value of the tile.

  • bg – The background color. The background tile under the printed text is set to this color. If NULL then the background will be left unchanged.

  • flag – The background blending flag. If unsure then use TCOD_BKGND_SET.

  • alignment – The text justification. This is one of TCOD_alignment_t and is normally TCOD_LEFT.

Returns

TCOD_Error Any problems such as malformed UTF-8 will return a negative error code.

int TCOD_console_printn_rect(TCOD_Console *console, int x, int y, int width, int height, size_t n, const char *str, const TCOD_ColorRGB *fg, const TCOD_ColorRGB *bg, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment)

Print a string of a specified length in a bounding box to a console.

New in version 1.19.

Parameters
  • console – A pointer to a TCOD_Console.

  • x – The starting X position, starting from the left-most tile as zero.

  • y – The starting Y position, starting from the upper-most tile as zero.

  • width – The maximum width of the bounding region in tiles.

  • height – The maximum height of the bounding region in tiles.

  • n – The length of the string buffer str[n] in bytes.

  • str – The text to print. This string can contain libtcod color codes.

  • fg – The foreground color. The printed text is set to this color. If NULL then the foreground will be left unchanged, inheriting the previous value of the tile.

  • bg – The background color. The background tile under the printed text is set to this color. If NULL then the background will be left unchanged.

  • flag – The background blending flag. If unsure then use TCOD_BKGND_SET.

  • alignment – The text justification. This is one of TCOD_alignment_t and is normally TCOD_LEFT.

Returns

int The height of the printed text, or a negative error code on failure.

TCOD_Error TCOD_console_vprintf(TCOD_Console *console, int x, int y, const TCOD_color_t *fg, const TCOD_color_t *bg, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, va_list args)

Print a formatted string using a va_list.

New in version 1.19.

Parameters
  • console – A pointer to a TCOD_Console.

  • x – The starting X position, starting from the left-most tile as zero.

  • y – The starting Y position, starting from the upper-most tile as zero.

  • fg – The foreground color. The printed text is set to this color. If NULL then the foreground will be left unchanged, inheriting the previous value of the tile.

  • bg – The background color. The background tile under the printed text is set to this color. If NULL then the background will be left unchanged.

  • flag – The background blending flag. If unsure then use TCOD_BKGND_SET.

  • alignment – The text justification. This is one of TCOD_alignment_t and is normally TCOD_LEFT.

  • fmt – The format string for a vprintf-like function.

  • args – The arguments for the formatted string.

Returns

TCOD_Error Any problems such as malformed UTF-8 will return a negative error code.

int TCOD_console_vprintf_rect(TCOD_Console *console, int x, int y, int width, int height, const TCOD_color_t *fg, const TCOD_color_t *bg, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, va_list args)

Print a formatted string using a va_list within a bounding box.

New in version 1.19.

Parameters
  • console – A pointer to a TCOD_Console.

  • x – The starting X position, starting from the left-most tile as zero.

  • y – The starting Y position, starting from the upper-most tile as zero.

  • width – The maximum width of the bounding region in tiles.

  • height – The maximum height of the bounding region in tiles.

  • fg – The foreground color. The printed text is set to this color. If NULL then the foreground will be left unchanged, inheriting the previous value of the tile.

  • bg – The background color. The background tile under the printed text is set to this color. If NULL then the background will be left unchanged.

  • flag – The background blending flag. If unsure then use TCOD_BKGND_SET.

  • alignment – The text justification. This is one of TCOD_alignment_t and is normally TCOD_LEFT.

  • fmt – The format string for a vprintf-like function.

  • args – The arguments for the formatted string.

Returns

TCOD_PUBLIC

int TCOD_console_get_height_rect_n(TCOD_Console *console, int x, int y, int width, int height, size_t n, const char *str)

Return the height of the word-wrapped text with the given parameters.

New in version 1.19.

Parameters
  • console – A pointer to a TCOD_Console.

  • x – The starting X position, starting from the left-most tile as zero.

  • y – The starting Y position, starting from the upper-most tile as zero.

  • width – The maximum width of the bounding region in tiles.

  • height – The maximum height of the bounding region in tiles.

  • n – The length of the string buffer str[n] in bytes.

  • str – The text to print. This string can contain libtcod color codes.

Returns

int The height of the word-wrapped text as if it were printed, or a negative error code on failure.

int TCOD_console_get_height_rect_wn(int width, size_t n, const char *str)

Return the height of the word-wrapped text with the given width.

New in version 1.19.

Parameters
  • width – The maximum width of the bounding region in tiles.

  • n – The length of the string buffer str[n] in bytes.

  • str – The text to print. This string can contain libtcod color codes.

Returns

int The height of the word-wrapped text as if it were printed, or a negative error code on failure.

Printing functions using UTF-8 (C++)

inline void tcod::print(TCOD_Console &console, const std::array<int, 2> &xy, std::string_view str, std::optional<TCOD_ColorRGB> fg, std::optional<TCOD_ColorRGB> bg, TCOD_alignment_t alignment = TCOD_LEFT, TCOD_bkgnd_flag_t flag = TCOD_BKGND_SET)

Print a string to a console.

auto console = tcod::Console{80, 50};
tcod::print(console, {0, 0}, "Hello World", {{255, 255, 255}}, {{0, 0, 0}});

New in version 1.19.

Parameters
  • console – A reference to a TCOD_Console.

  • xy – The starting {x, y} position, starting from the upper-left-most tile as zero.

  • str – The text to print. This string can contain libtcod color codes.

  • fg – The foreground color. The printed text is set to this color. If std::nullopt then the foreground will be left unchanged, inheriting the previous value of the tile.

  • bg – The background color. The background tile under the printed text is set to this color. If std::nullopt then the background will be left unchanged.

  • alignment – The text justification.

  • flag – The background blending flag.

inline int tcod::print_rect(TCOD_Console &console, const std::array<int, 4> &rect, std::string_view str, std::optional<TCOD_ColorRGB> fg, std::optional<TCOD_ColorRGB> bg, TCOD_alignment_t alignment = TCOD_LEFT, TCOD_bkgnd_flag_t flag = TCOD_BKGND_SET)

Print a string to a console constrained to a bounding box.

auto console = tcod::Console{80, 50};
static constexpr auto TEAL = tcod::ColorRGB{0, 255, 255};
// Print "Hello World" centered along the top row, ignoring the background color.
tcod::print(console, {0, 0, console->w, 1}, "Hello World", TEAL, std::nullopt, TCOD_CENTER);

New in version 1.19.

Parameters
  • console – A reference to a TCOD_Console.

  • rect – An {x, y, width, height} rectangle, starting from the upper-left-most tile as zero. A width or height of zero will leave that axis unconstrained.

  • str – The text to print. This string can contain libtcod color codes.

  • fg – The foreground color. The printed text is set to this color. If std::nullopt then the foreground will be left unchanged, inheriting the previous value of the tile.

  • bg – The background color. The background tile under the printed text is set to this color. If std::nullopt then the background will be left unchanged.

  • alignment – The text justification.

  • flag – The background blending flag.

Returns

int The height of the printed output.

inline int tcod::get_height_rect(int width, std::string_view str)

Return the height of the word-wrapped text with the given width.

auto console = tcod::Console{80, 50};
int y = console->h; // Start Y at the bottom of this console.
const int width = 6;
y -= tcod::get_height_rect("Long text example", width); // Move y up by the height of this text.
tcod::print(console, {0, y, width, 0}, "Long text example", std::nullopt, std::nullopt);

New in version 1.19.

Parameters
  • width – The maximum width of the bounding region in tiles.

  • str – The text to print. This string can contain libtcod color codes.

Returns

int The height of the text as if it were printed.

template<typename ...T>
inline std::string tcod::stringf(const char *format, T... args)

Return a formatted string as a std::string object.

This is a convience function for code using printf-like formatted strings. Newer more modern code might want to use the fmt library instead.

fmt::sprintf is a faster and safer alternative to this function.

auto console = tcod::Console{80, 50};
// Use tcod::stringf to encapsulate printf-like parameters.
tcod::print(console, {0, 0}, tcod::stringf("%s %s", "Hello", "World"), nullptr, nullptr);

New in version 1.19.

Template Parameters

T – Parameter packed arguments.

Parameters
  • format – A printf-like format string.

  • args – Any printf-like arguments.

Returns

A std::string object with the resulting output.

Printing functions using 8-bit encodings (deprecated)

Note

These functions use EASCII encoded strings which are not compatible with Unicode. They are deprecated for this reason.

void TCOD_console_print(TCOD_Console *con, int x, int y, const char *fmt, ...)

Print a string on a console, using default colors and alignment.

Parameters
  • con – A console pointer.

  • x – The starting X coordinate, the left-most position being 0.

  • y – The starting Y coordinate, the top-most position being 0.

  • fmt – A format string as if passed to printf.

  • ... – Variadic arguments as if passed to printf.

void TCOD_console_print_ex(TCOD_Console *con, int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, ...)

Print an EASCII string on a console, using default colors.

Parameters
  • con – A console pointer.

  • x – The starting X coordinate, the left-most position being 0.

  • y – The starting Y coordinate, the top-most position being 0.

  • flag – The blending flag.

  • alignment – The font alignment to use.

  • fmt – A format string as if passed to printf.

  • ... – Variadic arguments as if passed to printf.

int TCOD_console_print_rect(TCOD_Console *con, int x, int y, int w, int h, const char *fmt, ...)

Print an EASCII string on a console constrained to a rectangle, using default colors and alignment.

Parameters
  • con – A console pointer.

  • x – The starting X coordinate, the left-most position being 0.

  • y – The starting Y coordinate, the top-most position being 0.

  • w – The width of the region. If 0 then the maximum width will be used.

  • h – The height of the region. If 0 then the maximum height will be used.

  • fmt – A format string as if passed to printf.

  • ... – Variadic arguments as if passed to printf.

Returns

The number of lines actually printed.

int TCOD_console_print_rect_ex(TCOD_Console *con, int x, int y, int w, int h, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char *fmt, ...)

Print an EASCII string on a console constrained to a rectangle, using default colors.

Parameters
  • con – A console pointer.

  • x – The starting X coordinate, the left-most position being 0.

  • y – The starting Y coordinate, the top-most position being 0.

  • w – The width of the region. If 0 then the maximum width will be used.

  • h – The height of the region. If 0 then the maximum height will be used.

  • flag – The blending flag.

  • alignment – The font alignment to use.

  • fmt – A format string as if passed to printf.

  • ... – Variadic arguments as if passed to printf.

Returns

The number of lines actually printed.

void TCOD_console_print_frame(TCOD_console_t con, int x, int y, int w, int h, bool empty, TCOD_bkgnd_flag_t flag, const char *fmt, ...)

Print a titled, framed region on a console, using default colors and alignment.

This function makes assumptions about the fonts character encoding and may draw garbage with some tilesets.

Deprecated since version 1.19: This function is not using Unicode frame characters and has been deprecated.

Parameters
  • con – A console pointer.

  • x – The starting X coordinate, the left-most position being 0.

  • y – The starting Y coordinate, the top-most position being 0.

  • w – The width of the frame.

  • h – The height of the frame.

  • empty – If true the characters inside of the frame will be cleared with spaces.

  • flag – The blending flag.

  • fmt – A format string as if passed to printf.

  • ... – Variadic arguments as if passed to printf.

int TCOD_console_get_height_rect(TCOD_Console *con, int x, int y, int w, int h, const char *fmt, ...)

Return the number of lines that would be printed by an EASCII string.

Parameters
  • con – A console pointer.

  • x – The starting X coordinate, the left-most position being 0.

  • y – The starting Y coordinate, the top-most position being 0.

  • w – The width of the region. If 0 then the maximum width will be used.

  • h – The height of the region. If 0 then the maximum height will be used.

  • fmt – A format string as if passed to printf.

  • ... – Variadic arguments as if passed to printf.

Returns

The number of lines that would have been printed.

Printing functions using wchar_t (deprecated)

Note

These functions say they are UTF, however they will behave as UCS2 or UCS4 depending on the platform. They are deprecated for this reason.

void TCOD_console_print_utf(TCOD_Console *con, int x, int y, const wchar_t *fmt, ...)

Deprecated since version 1.8: Use TCOD_console_printf() instead.

void TCOD_console_print_ex_utf(TCOD_Console *con, int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const wchar_t *fmt, ...)

Deprecated since version 1.8: Use TCOD_console_printf_ex() instead.

int TCOD_console_print_rect_utf(TCOD_Console *con, int x, int y, int w, int h, const wchar_t *fmt, ...)

Deprecated since version 1.8: Use TCOD_console_printf_rect() instead.

int TCOD_console_print_rect_ex_utf(TCOD_Console *con, int x, int y, int w, int h, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const wchar_t *fmt, ...)

Deprecated since version 1.8: Use TCOD_console_printf_rect_ex() instead.

int TCOD_console_get_height_rect_utf(TCOD_Console *con, int x, int y, int w, int h, const wchar_t *fmt, ...)

Deprecated since version 1.8.

Flushing the root console

TCOD_Error TCOD_console_flush(void)

Render and present the root console to the active display.

int TCOD_sys_accumulate_console(const TCOD_Console *console)

Render a console over the display.

console can be any size, the active render will try to scale it to fit the screen.

The function will only work for the SDL2/OPENGL2 renderers.

Unlike TCOD_console_flush() this will not present the display. You will need to do that manually, likely with the SDL API.

Returns 0 on success, or a negative number on a failure such as the incorrect renderer being active.

New in version 1.11.

Handling user input

Blocking user input

TCOD_key_t TCOD_console_wait_for_keypress(bool flush)

Wait for a key press event, then return it.

Do not solve input lag issues by arbitrarily dropping events!

Parameters

flush – If 1 then the event queue will be cleared before waiting for the next event. This should always be 0.

Returns

A TCOD_key_t struct with the most recent key data.

TCOD_event_t TCOD_sys_wait_for_event(int eventMask, TCOD_key_t *key, TCOD_mouse_t *mouse, bool flush)

Non blocking user input

TCOD_key_t TCOD_console_check_for_keypress(int flags)

Return immediately with a recently pressed key.

Parameters

flags – A TCOD_event_t bit-field, for example: TCOD_EVENT_KEY_PRESS

Returns

A TCOD_key_t struct with a recently pressed key. If no event exists then the vk attribute will be TCODK_NONE

bool TCOD_console_is_key_pressed(TCOD_keycode_t key)

Return True if the libtcod keycode is held.

Deprecated since version 1.16: You should instead use SDL_GetKeyboardState to check if keys are held.

TCOD_event_t TCOD_sys_check_for_event(int eventMask, TCOD_key_t *key, TCOD_mouse_t *mouse)
TCOD_mouse_t TCOD_mouse_get_status(void)

Keyboard event structure

enum TCOD_key_status_t

Bitwise flags used for functions such as TCOD_console_check_for_keypress() This was replaced by the equivalent values of TCOD_event_t.

Values:

enumerator TCOD_KEY_PRESSED
enumerator TCOD_KEY_RELEASED
struct TCOD_key_t

Libtcod key event data, as a keycode or text character.

Deprecated:

The libtcod keyboard state has several known issues such as missing or broken functionality. In its current state it exists only for backwards compatibility. These issues should be resolved by using SDL directly for keyboard events.

Key codes

enum TCOD_keycode_t

Libtcod specific codes representing keys on the keyboard.

When no key was pressed (see checkForEvent) : TCOD_NONE (NoKey)

Special keys:

  • TCODK_ESCAPE (Escape)

  • TCODK_BACKSPACE (Backspace)

  • TCODK_TAB (Tab)

  • TCODK_ENTER (Enter)

  • TCODK_SHIFT (Shift)

  • TCODK_CONTROL (Control)

  • TCODK_ALT (Alt)

  • TCODK_PAUSE (Pause)

  • TCODK_CAPSLOCK (CapsLock)

  • TCODK_PAGEUP (PageUp)

  • TCODK_PAGEDOWN (PageDown)

  • TCODK_END (End)

  • TCODK_HOME (Home)

  • TCODK_UP (Up)

  • TCODK_LEFT (Left)

  • TCODK_RIGHT (Right)

  • TCODK_DOWN (Down)

  • TCODK_PRINTSCREEN (Printscreen)

  • TCODK_INSERT (Insert)

  • TCODK_DELETE (Delete)

  • TCODK_LWIN (Lwin)

  • TCODK_RWIN (Rwin)

  • TCODK_APPS (Apps)

  • TCODK_KPADD (KeypadAdd)

  • TCODK_KPSUB (KeypadSubtract)

  • TCODK_KPDIV (KeypadDivide)

  • TCODK_KPMUL (KeypadMultiply)

  • TCODK_KPDEC (KeypadDecimal)

  • TCODK_KPENTER (KeypadEnter)

  • TCODK_F1 (F1)

  • TCODK_F2 (F2)

  • TCODK_F3 (F3)

  • TCODK_F4 (F4)

  • TCODK_F5 (F5)

  • TCODK_F6 (F6)

  • TCODK_F7 (F7)

  • TCODK_F8 (F8)

  • TCODK_F9 (F9)

  • TCODK_F10 (F10)

  • TCODK_F11 (F11)

  • TCODK_F12 (F12)

  • TCODK_NUMLOCK (Numlock)

  • TCODK_SCROLLLOCK (Scrolllock)

  • TCODK_SPACE (Space)

Numeric keys:

  • TCODK_0 (Zero)

  • TCODK_1 (One)

  • TCODK_2 (Two)

  • TCODK_3 (Three)

  • TCODK_4 (Four)

  • TCODK_5 (Five)

  • TCODK_6 (Six)

  • TCODK_7 (Seven)

  • TCODK_8 (Eight)

  • TCODK_9 (Nine)

  • TCODK_KP0 (KeypadZero)

  • TCODK_KP1 (KeypadOne)

  • TCODK_KP2 (KeypadTwo)

  • TCODK_KP3 (KeypadThree)

  • TCODK_KP4 (KeypadFour)

  • TCODK_KP5 (KeypadFive)

  • TCODK_KP6 (KeypadSix)

  • TCODK_KP7 (KeypadSeven)

  • TCODK_KP8 (KeypadEight)

  • TCODK_KP9 (KeypadNine)

Any other (printable) key:

  • TCODK_CHAR (Char)

  • TCODK_TEXT (SDL_TEXTINPUT)

Codes starting with TCODK_KP represents keys on the numeric keypad (if available).

Deprecated:

Using libtcod for events means only a limited set of keys are available. Use SDL for events to access a complete range of keys.

Values:

enumerator TCODK_NONE
enumerator TCODK_ESCAPE
enumerator TCODK_BACKSPACE
enumerator TCODK_TAB
enumerator TCODK_ENTER
enumerator TCODK_SHIFT
enumerator TCODK_CONTROL
enumerator TCODK_ALT
enumerator TCODK_PAUSE
enumerator TCODK_CAPSLOCK
enumerator TCODK_PAGEUP
enumerator TCODK_PAGEDOWN
enumerator TCODK_END
enumerator TCODK_HOME
enumerator TCODK_UP
enumerator TCODK_LEFT
enumerator TCODK_RIGHT
enumerator TCODK_DOWN
enumerator TCODK_PRINTSCREEN
enumerator TCODK_INSERT
enumerator TCODK_DELETE
enumerator TCODK_LWIN
enumerator TCODK_RWIN
enumerator TCODK_APPS
enumerator TCODK_0
enumerator TCODK_1
enumerator TCODK_2
enumerator TCODK_3
enumerator TCODK_4
enumerator TCODK_5
enumerator TCODK_6
enumerator TCODK_7
enumerator TCODK_8
enumerator TCODK_9
enumerator TCODK_KP0
enumerator TCODK_KP1
enumerator TCODK_KP2
enumerator TCODK_KP3
enumerator TCODK_KP4
enumerator TCODK_KP5
enumerator TCODK_KP6
enumerator TCODK_KP7
enumerator TCODK_KP8
enumerator TCODK_KP9
enumerator TCODK_KPADD
enumerator TCODK_KPSUB
enumerator TCODK_KPDIV
enumerator TCODK_KPMUL
enumerator TCODK_KPDEC
enumerator TCODK_KPENTER
enumerator TCODK_F1
enumerator TCODK_F2
enumerator TCODK_F3
enumerator TCODK_F4
enumerator TCODK_F5
enumerator TCODK_F6
enumerator TCODK_F7
enumerator TCODK_F8
enumerator TCODK_F9
enumerator TCODK_F10
enumerator TCODK_F11
enumerator TCODK_F12
enumerator TCODK_NUMLOCK
enumerator TCODK_SCROLLLOCK
enumerator TCODK_SPACE
enumerator TCODK_CHAR
enumerator TCODK_TEXT

Mouse event structure

struct TCOD_mouse_t

Mouse state provided by the libtcod event system.

This may be a moved, pressed, or released event.

Deprecated:

The libtcod mouse state has several known issues such as missing or broken functionality. In its current state it exists only for backwards compatibility. These issues should be resolved by using SDL directly for mouse and keyboard events.

Events from SDL2

TCOD_event_t tcod::sdl2::process_event(const union SDL_Event &in, TCOD_key_t &out) noexcept

Parse an SDL_Event into a key event and return the relevant TCOD_event_t.

Returns TCOD_EVENT_NONE if the event wasn’t keyboard related.

New in version 1.11.

TCOD_event_t tcod::sdl2::process_event(const union SDL_Event &in, TCOD_mouse_t &out) noexcept

Parse an SDL_Event into a mouse event and return the relevant TCOD_event_t.

Returns TCOD_EVENT_NONE if the event wasn’t mouse related.

New in version 1.11.

TCOD_event_t TCOD_sys_process_key_event(const union SDL_Event *in, TCOD_key_t *out)

Parse an SDL_Event into a key event and return the relevant TCOD_event_t.

Returns TCOD_EVENT_NONE if the event wasn’t keyboard related.

New in version 1.11.

TCOD_event_t TCOD_sys_process_mouse_event(const union SDL_Event *in, TCOD_mouse_t *out)

Parse an SDL_Event into a mouse event and return the relevant TCOD_event_t.

Returns TCOD_EVENT_NONE if the event wasn’t mouse related.

New in version 1.11.

Using off-screen consoles

Creating and deleting off-screen consoles

TCOD_Console *TCOD_console_new(int w, int h)

Return a new console with a specific number of columns and rows.

Parameters
  • w – Number of columns.

  • h – Number of columns.

Returns

A pointer to the new console, or NULL on error.

void TCOD_console_delete(TCOD_Console *console)

Delete a console.

If the console being deleted is the root console, then the display will be uninitialized.

Parameters

console – A console pointer.

Creating an off-screen console from any .asc/.apf/.xp file

TCOD_console_t TCOD_console_from_file(const char *filename)

Loading an offscreen console from a .asc file

bool TCOD_console_load_asc(TCOD_console_t con, const char *filename)

Loading an offscreen console from a .apf file

bool TCOD_console_load_apf(TCOD_console_t con, const char *filename)

Saving a console to a .asc file

bool TCOD_console_save_asc(TCOD_console_t con, const char *filename)

Saving a console to a .apf file

bool TCOD_console_save_apf(TCOD_console_t con, const char *filename)

Working with REXPaint .xp files

REXPaint gives special treatment to tiles with a magic pink {255, 0, 255} background color. You can processes this effect manually or by setting TCOD_console_set_key_color() to TCOD_fuchsia.

libtcodpy.console_from_xp(filename)
TCOD_console_t TCOD_console_from_xp(const char *filename)

Return a new console loaded from a REXPaint .xp file.

Parameters

filename[in] A path to the REXPaint file.

Returns

A new TCOD_console_t object. New consoles will need to be deleted with a call to :any:TCOD_console_delete. Returns NULL on an error.

libtcodpy.console_load_xp(con, filename)
bool TCODConsole::loadXp(const char *filename)
bool TCOD_console_load_xp(TCOD_Console *con, const char *filename)

Update a console from a REXPaint .xp file.

In C++, you can pass the filepath directly to the :any:TCODConsole constructor to load a REXPaint file.

Parameters
  • con[out] A console instance to update from the REXPaint file.

  • filename[in] A path to the REXPaint file.

libtcodpy.console_save_xp(con, filename, compress_level=- 1)
bool TCODConsole::saveXp(const char *filename, int compress_level)
bool TCOD_console_save_xp(const TCOD_Console *con, const char *filename, int compress_level)

Save a console as a REXPaint .xp file.

The REXPaint format can support a 1:1 copy of a libtcod console.

Parameters
  • con[in] The console instance to save.

  • filename[in] The filepath to save to.

  • compress_level[in] A zlib compression level, from 0 to 9. 1=fast, 6=balanced, 9=slowest, 0=uncompressed.

Returns

true when the file is saved successfully, or false when an issue is detected.

libtcodpy.console_list_from_xp(filename)
TCOD_list_t TCOD_console_list_from_xp(const char *filename)

Return a list of consoles from a REXPaint file.

This function can load a REXPaint file with variable layer shapes, which would cause issues for a function like TCOD_console_list_from_xp.

Deprecated since version 1.20: TCOD_list_t is deprecated, use TCOD_load_xp instead.

Parameters

filename[in] A path to the REXPaint file.

Returns

Returns a TCOD_list_t of TCOD_console_t objects. Or NULL on an error. You will need to delete this list and each console individually.

libtcodpy.console_list_save_xp(console_list, filename, compress_level)
bool TCOD_console_list_save_xp(TCOD_list_t console_list, const char *filename, int compress_level)

Save a list of consoles to a REXPaint file.

This function can save any number of layers with multiple different sizes.

The REXPaint tool only supports files with up to 9 layers where all layers are the same size.

Deprecated since version 1.20: TCOD_list_t is deprecated, use TCOD_save_xp instead.

Parameters
  • console_list[in] A TCOD_list_t of TCOD_console_t objects.

  • filename[in] Path to save to.

  • compress_level[in] zlib compression level.

Returns

true on success, false on a failure such as not being able to write to the path provided.

Blitting a console on another one

void TCOD_console_blit(const TCOD_Console *src, int xSrc, int ySrc, int wSrc, int hSrc, TCOD_Console *dst, int xDst, int yDst, float foreground_alpha, float background_alpha)

Blit from one console to another.

If the source console has a key color, this function will use it.

Changed in version 1.16: Blits can now handle per-cell alpha transparency.

Parameters
  • src – Pointer to the source console.

  • xSrc – The left region of the source console to blit from.

  • ySrc – The top region of the source console to blit from.

  • wSrc – The width of the region to blit from. If 0 then it will fill to the maximum width.

  • hSrc – The height of the region to blit from. If 0 then it will fill to the maximum height.

  • dst – Pointer to the destination console.

  • xDst – The left corner to blit onto the destination console.

  • yDst – The top corner to blit onto the destination console.

  • foreground_alpha – Foreground blending alpha.

  • background_alpha – Background blending alpha.

Define a blit-transparent color

void TCOD_console_set_key_color(TCOD_Console *con, TCOD_color_t col)