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(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.
-
~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 astd::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.
-
inline Console()¶
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.
-
inline auto begin() noexcept -> TCOD_ConsoleTile*¶
-
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.
-
int ch¶
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¶
-
enumerator TCOD_RENDERER_GLSL¶
-
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 theTCOD_RENDERER
orTCOD_VSYNC
environment variables.Valid case-sensitive options for
TCOD_RENDERER
are:sdl
opengl
glsl
sdl2
opengl2
Valid options for
TCOD_VSYNC
are0
or1
.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.
-
enumerator TCOD_FONT_LAYOUT_ASCII_INCOL¶
-
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 ofx
,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 ofx
,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:If0 1 2 3 4 5 6 7 8
fg
orbg
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¶
-
enumerator TCOD_BKGND_NONE¶
String printing alignment¶
-
enum TCOD_alignment_t¶
Print justification options.
Values:
-
enumerator TCOD_LEFT¶
-
enumerator TCOD_RIGHT¶
-
enumerator TCOD_CENTER¶
-
enumerator TCOD_LEFT¶
-
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 normallyTCOD_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 normallyTCOD_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 normallyTCOD_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 normallyTCOD_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 beTCODK_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¶
-
enumerator TCOD_KEY_PRESSED¶
-
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, orfalse
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)¶