Welcome to the libtcod C/C++ documentation!

Note

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

Colors

Note

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

libtcod uses 32-bit color, therefore your OS desktop must also use 32-bit color. A color is defined by its red, green and blue component between 0 and 255.

You can use the following predefined colors (hover over a color to see its full name and R,G,B values):

INSERT COLOUR TABLE IN A PAINLESS MANNER

Create your own colors

You can create your own colours using a set of constructors, both for RGB and HSV values.

/* RGB */
TCOD_color_t my_color= { 24, 64, 255 };
TCOD_color_t my_other_color = TCOD_color_RGB(24, 64, 255);
/* HSV */
TCOD_color_t my_yet_another_color = TCOD_color_HSV(321.0f, 0.7f, 1.0f);

// RGB
TCODColor myColor(24, 64, 255);
// HSV
TCODColor myOtherColor(321.0f, 0.7f, 1.0f);

struct ColorRGB : public TCOD_ColorRGB

A C++ RGB color, used to handle conversions between color types.

New in version 1.19.

Public Functions

inline constexpr ColorRGB() noexcept

Default construct a black ColorRGB object.

RGB values are zero.

inline constexpr ColorRGB(uint8_t red, uint8_t green, uint8_t blue) noexcept

Construct a ColorRGB object with the provided color.

inline explicit constexpr ColorRGB(const TCOD_ColorRGB &rhs) noexcept

Construct a ColorRGB object from an TCOD_ColorRGB struct.

inline explicit constexpr ColorRGB(const TCOD_ColorRGBA &rhs) noexcept

Construct a ColorRGB object from an RGBA color, truncating the alpha.

inline constexpr operator const TCOD_ColorRGBA() const noexcept

Allow implicit casts to RGBA colors, where alpha=255 is implied.

inline explicit constexpr operator TCOD_ColorRGB*() noexcept

Allow explicit casts to a TCOD_ColorRGB pointer.

inline explicit constexpr operator const TCOD_ColorRGB*() const noexcept

Allow explicit casts to a const TCOD_ColorRGB pointer.

struct ColorRGBA : public TCOD_ColorRGBA

A C++ RGBA color, used to handle conversions between color types.

New in version 1.19.

Public Functions

inline constexpr ColorRGBA() noexcept

Default construct a black ColorRGBA object.

RGB values are zero, alpha is 255.

inline constexpr ColorRGBA(uint8_t red, uint8_t green, uint8_t blue, uint8_t alpha = 255) noexcept

Construct a ColorRGBA object with the provided color and alpha.

inline explicit constexpr ColorRGBA(const TCOD_ColorRGB &rhs, uint8_t alpha = 255) noexcept

Construct a ColorRGBA object by adding an alpha channel to an RGB object.

inline explicit constexpr ColorRGBA(const TCOD_ColorRGBA &rhs) noexcept

Construct a ColorRGBA object from an TCOD_ColorRGBA struct.

inline explicit constexpr operator TCOD_ColorRGB() const noexcept

Allow explicit conversions to a TCOD_ColorRGB struct.

inline explicit constexpr operator TCOD_ColorRGBA*() noexcept

Allow explicit conversions to a TCOD_ColorRGBA pointer.

inline explicit constexpr operator const TCOD_ColorRGBA*() const noexcept

Allow explicit conversions to a const TCOD_ColorRGBA pointer.

Compare two colors

bool TCOD_color_equals(TCOD_color_t c1, TCOD_color_t c2)

Add and subtract Colors

TCOD_color_t TCOD_color_add(TCOD_color_t c1, TCOD_color_t c2)

TCOD_color_t TCOD_color_subtract(TCOD_color_t c1, TCOD_color_t c2)

Multiply Colors together

TCOD_color_t TCOD_color_multiply(TCOD_color_t c1, TCOD_color_t c2)

TCOD_color_t TCOD_color_multiply_scalar(TCOD_color_t c1, float value)

Interpolate between two colors

TCOD_color_t TCOD_color_lerp(TCOD_color_t c1, TCOD_color_t c2, float coef)

Define a color by its hue, saturation and value

After this function is called, the r,g,b fields of the color are calculated according to the h,s,v parameters.

void TCOD_color_set_HSV(TCOD_color_t *color, float hue, float saturation, float value)

These functions set only a single component in the HSV color space.

void TCOD_color_set_hue(TCOD_color_t *color, float hue)

void TCOD_color_set_saturation(TCOD_color_t *color, float saturation)

void TCOD_color_set_value(TCOD_color_t *color, float value)

Get a color hue, saturation and value components

void TCOD_color_get_HSV(TCOD_color_t color, float *hue, float *saturation, float *value)

Should you need to extract only one of the HSV components, these functions are what you should call. Note that if you need all three values, it’s way less burdensome for the CPU to call TCODColor::getHSV().

float TCOD_color_get_hue(TCOD_color_t color)

float TCOD_color_get_saturation(TCOD_color_t color)

float TCOD_color_get_value(TCOD_color_t color)

Shift a color’s hue up or down

The hue shift value is the number of grades the color’s hue will be shifted. The value can be negative for shift left, or positive for shift right. Resulting values H < 0 and H >= 360 are handled automatically.

void TCOD_color_shift_hue(TCOD_color_t *color, float shift)

Scale a color’s saturation and value

void TCOD_color_scale_HSV(TCOD_color_t *color, float saturation_coef, float value_coef)

Generate a smooth color map

You can define a color map from an array of color keys. Colors will be interpolated between the keys. 0 -> black 4 -> red 8 -> white Result:

INSERT TABLE.

void TCOD_color_gen_map(TCOD_color_t *map, int nb_key, const TCOD_color_t *key_color, const int *key_index)

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.

See also

TCOD_sys_get_sdl_window() TCOD_sys_get_sdl_renderer()

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)

System layer

Note

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

Time functions

Deprecated C functions

Note

These are deprecated because they are not compatible with libtcod contexts or are straight ports of SDL calls. You should use the SDL timing API or tcod::Timer to track time.

uint32_t TCOD_sys_elapsed_milli(void)

Alias for SDL_GetTicks.

Deprecated since version 1.19: You should call SDL_GetTicks directly.

float TCOD_sys_elapsed_seconds(void)

Returns the number of seconds since the start of the program.

Deprecated since version 1.19: Use SDL_GetTicks and convert the result into seconds instead of using this function.

void TCOD_sys_sleep_milli(uint32_t val)

Alias for SDL_Delay.

Deprecated since version 1.19: You should call SDL_Delay directly.

void TCOD_sys_set_fps(int val)

Set the desired framerate.

Deprecated since version 1.19: This function will not affect libtcod contexts. Set the framerate with tcod::Timer instead.

int TCOD_sys_get_fps(void)

Get the current framerate.

Deprecated since version 1.19: This function will not work with libtcod contexts. Use tcod::Timer instead.

float TCOD_sys_get_last_frame_length(void)

Get the delta time between the last two frames.

Deprecated since version 1.19: This function will not work with libtcod contexts. Use tcod::Timer instead.

Timer class

class Timer

A timing class based on SDL’s high performance time counter.

Used to track delta time or set a framerate.

This class is based on using SDL_GetPerformanceCounter to track the time. The time taken between calls to sync() is tracked. This is used to determine the real framerate if requested.

You must add #include <libtcod/timer.hpp> to include ths class.

int desired_fps = 30;
auto timer = tcod::Timer();
while (1) {
  float delta_time = timer.sync(desired_fps);  // desired_fps is optional.
  // ...

New in version 1.19.

Public Functions

inline Timer()

Construct a new Timer object.

inline float sync(int desired_fps = 0)

Sync the time to a given framerate (if provided) and return the delta time compared to the previous call.

If desired_fps is non-zero then this function will block until the desired framerate is reached.

Timing starts once the Timer is constructed.

Parameters:

desired_fps – The desired framerate in frames-per-second, or zero to disable framerate limiting.

Returns:

The delta time in seconds since the last call to sync is returned as a float.

inline float get_mean_fps() const noexcept

Return the mean framerate.

This is the average of all samples combined.

inline float get_last_fps() const noexcept

Return the framerate of the last call to sync().

inline float get_min_fps() const noexcept

Return the lowest framerate recently sampled.

inline float get_max_fps() const noexcept

Return the highest framerate recently sampled.

inline float get_median_fps() const noexcept

Return the median framerate.

This is the framerate of the middle sample when all samples are sorted.

Easy screenshots

void TCOD_sys_save_screenshot(const char *filename)

Miscellaneous utilities

struct SDL_Window *TCOD_sys_get_sdl_window(void)

Return an SDL_Window pointer if one is in use, returns NULL otherwise.

New in version 1.11.

struct SDL_Renderer *TCOD_sys_get_sdl_renderer(void)

Return an SDL_Renderer pointer if one is in use, returns NULL otherwise.

New in version 1.11.

TCOD_Context *TCOD_sys_get_internal_context(void)

Return the context being used internally by the old API.

This function can be useful to progressively upgrade older code to use the newer API.

New in version 1.19.

Returns:

A TCOD_Context pointer, or NULL if the global internals were not initialzed.

TCOD_Console *TCOD_sys_get_internal_console(void)

Return a pointer to the “root console” used internally by the old API.

This is useful for functions which take a console parameter but won’t accept NULL.

New in version 1.19.

Returns:

A pointer to TCOD_Console, or NULL if it doesn’t exist.

Line Drawing Toolkit

Iterator-based line drawing

#include <libtcod.h>

void main() {
  TCOD_bresenham_data_t bresenham_data;
  int x=5, y=8;
  TCOD_line_init_mt(x, y, 13, 14, &bresenham_data);
  do {
    printf("%d %d\n", x, y);
  } while (!TCOD_line_step_mt(&x, &y, &bresenham_data));
}

struct TCOD_bresenham_data_t

A struct used for computing a bresenham line.

void TCOD_line_init_mt(int xFrom, int yFrom, int xTo, int yTo, TCOD_bresenham_data_t *data)

bool TCOD_line_step_mt(int *xCur, int *yCur, TCOD_bresenham_data_t *data)

Callback-based line drawing

#include <libtcod.h>

void main() {
  bool my_listener(int x,int y) {
    printf("%d %d\n", x, y);
    return true;
  }
  TCOD_line(5, 8, 13, 4, my_listener);
}

typedef bool (*TCOD_line_listener_t)(int x, int y)

A callback to be passed to TCOD_line.

The points given to the callback include both the starting and ending positions.

Param x:

Param y:

Return:

As long as this callback returns true it will be called with the next x,y point on the line.

bool TCOD_line(int xFrom, int yFrom, int xTo, int yTo, TCOD_line_listener_t listener)

class BresenhamLine

Encapsulates a Bresenham line drawing algorithm.

New in version 1.17.

Public Functions

inline explicit BresenhamLine(Point2 begin, Point2 end) noexcept

Construct a new Bresenham line from begin to end.

Iterating over this instance will include both endpoints.

inline explicit BresenhamLine(Point2 begin, Point2 end, int error) noexcept

Construct a new Bresenham line with a manually given error value.

inline value_type operator[](int index) noexcept

Return the world position of the Bresenham at the index relative to the current index.

BresenhamLine is not restricted by any bounds so you can freely give a index past the end or before zero.

The internal state must always seek to the position being indexed, this will affect performance depending on if successive indexes are close together or far apart.

inline value_type operator*() noexcept

Return the world position of the Bresenham at the current index.

inline BresenhamLine adjust_range(int shift_begin, int shift_end) const noexcept

  Return a new version of this BresenhamLine with an adjusted range.

  `shift_begin` and `shift_end` change the beginning and ending of the line
  when iterators over.

  Example::

Remove the endpoints of a bresenham line. auto line = tcod::BresenhamLine(from, to).adjust_range(1, -1);

inline BresenhamLine without_start() const noexcept

  Remove the staring endpoint of a line.

  Example::

    for (auto&& [x, y] : tcod::BresenhamLine(from, to).without_start()) {

All positions excluding from. }

inline BresenhamLine without_end() const noexcept

  Remove the final endpoint of a line.

  Example::

    for (auto&& [x, y] : tcod::BresenhamLine(from, to).without_end()) {

All positions excluding to. }

inline BresenhamLine without_endpoints() const noexcept

  Remove both endpoints of a line.

  Example::

    for (auto&& [x, y] : tcod::BresenhamLine(from, to).without_endpoints()) {

All positions between and excluding from and to. }

inline BresenhamLine begin() const noexcept

Return the beginning iterator, which is a copy of the current object.

inline BresenhamLine end() const noexcept

Return the past-the-end iterator.

Deprecated functions

bool TCOD_line_mt(int xFrom, int yFrom, int xTo, int yTo, TCOD_line_listener_t listener, TCOD_bresenham_data_t *data)

void TCOD_line_init(int xFrom, int yFrom, int xTo, int yTo)

bool TCOD_line_step(int *xCur, int *yCur)

advance one step.

returns true if we reach destination

Contexts

Context parameters

struct TCOD_ContextParams

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

New in version 1.19.

Public Members

int tcod_version

Must be TCOD_COMPILEDVERSION.

int window_x

window_x and window_y are the starting position of the window.

These are SDL parameters so values like SDL_WINDOWPOS_UNDEFINED and SDL_WINDOWPOS_CENTERED are acceptable.

Values of zero will be converted to SDL_WINDOWPOS_UNDEFINED unless window_xy_defined is true.

int window_y

int pixel_width

pixel_width and pixel_height are the desired size of the window in pixels.

If these are zero then they’ll be derived from columns, rows, and the tileset.

int pixel_height

int columns

columns and rows are the desired size of the terminal window.

Usually you’ll set either these or the pixel resolution.

If you are setting these values from a TCOD_Console then you should set the console attribute instead.

int rows

int renderer_type

renderer_type is one of the TCOD_renderer_t values.

TCOD_Tileset *tileset

tileset is an optional pointer to a tileset object.

If this is NULL then a platform specific fallback tileset will be used. This fallback is known to be unreliable, but it should work well enough for prototyping code.

int vsync

If vsync is true, then vertical sync will be enabled whenever possible.

A value of true is recommended.

int sdl_window_flags

sdl_window_flags is a bitfield of SDL_WindowFlags flags.

For a window, a value of SDL_WINDOW_RESIZABLE is recommended. For fullscreen, a value of SDL_WINDOW_RESIZABLE | SDL_WINDOW_FULLSCREEN_DESKTOP is recommended. You should avoid the SDL_WINDOW_FULLSCREEN flag whenever possible.

const char *window_title

window_title will be the title of the opened window.

If not set then argv[0] will be used if available.

int argc

The number of items in argv.

const char *const *argv

argc and argv are optional CLI parameters.

You can pass 0 and NULL respectfully to ignore them. If unsure then you should pass the argc and argv arguments from your main function.

void (*cli_output)(void *userdata, const char *output)

If user attention is required for the given CLI parameters then cli_output will be called with cli_userdata and an error or help message.

If cli_output is NULL then it will print the message to stdout and terminate the program. If cli_output returns normally then TCOD_E_REQUIRES_ATTENTION will be returned from TCOD_context_new.

void *cli_userdata

This is passed to the userdata parameter of cli_output if called.

bool window_xy_defined

If this is false then window_x/window_y parameters of zero are assumed to be undefined and will be changed to SDL_WINDOWPOS_UNDEFINED.

TCOD_Console *console

A console to be used as a reference for the desired window size.

This can set as an alternative to the columns and rows attributes.

New in version 1.19.

C++ API

Warning

doxygenclass: Cannot find class “tcod::Context” in doxygen xml output for project “libtcod” from directory: doxyxml/

inline auto tcod::new_context(const TCOD_ContextParams &params, TCOD_Error &out_code) -> ContextPtr

Initialize and return a new libtcod context.

Also returns an error code for non-critical issues.

For critical issues an exception is thrown as usual. Non-critical issues are things such as being unable to create a desired renderer and using to a fallback instead.

New in version 1.19.

Parameters:

• params – Options to configure the new context with.

• out_code – Will be set to an error code on non-critical issues.

Returns:

ContextPtr A pointer to the new context.

inline auto tcod::new_context(const TCOD_ContextParams &params) -> ContextPtr

Initialize and return a new libtcod context.

Parameters:

params – Options to configure the new context with.

Returns:

ContextPtr A pointer to the new context.

New in version 1.19.

C API

struct TCOD_Context

A rendering context for libtcod.

New in version 1.16.

TCOD_Error TCOD_context_new(const TCOD_ContextParams *params, TCOD_Context **out)

Create a new context with the given parameters.

params is a non-NULL pointer to a TCOD_ContextParams struct. See its documentation for info on the parameters.

out is the output for the TCOD_Context, must not be NULL.

New in version 1.16.

TCOD_Error TCOD_context_present(struct TCOD_Context *context, const struct TCOD_Console *console, const struct TCOD_ViewportOptions *viewport)

Present a console to the screen, using a rendering context.

console is the console to present, the console can be any size.

viewport is the optional viewport options to use. This will affect the scaling of the console with the current context. This can be NULL to use the default options, which are to stretch the console to fit the screen.

New in version 1.16.

TCOD_Error TCOD_context_recommended_console_size(struct TCOD_Context *context, float magnification, int *columns, int *rows)

Set columns and rows to the recommended console size for this context.

magnification determines the apparent size of the tiles on the output. Values of 0.0f or lower will default to 1.0f.

New in version 1.16.

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

Change the active tileset for this context.

New in version 1.16.

int TCOD_context_get_renderer_type(struct TCOD_Context *context)

Return the TCOD_renderer_t renderer type for this context.

Returns a negative number on error, such as context being NULL.

New in version 1.16.

TCOD_Error TCOD_context_screen_pixel_to_tile_d(struct TCOD_Context *context, double *x, double *y)

Convert the screen coordinates to tile coordinates for this context.

x and y are the pointers to the screen coordinates, these will be converted to tile coordinates after the call to this function.

The parameters given to the last call to TCOD_context_present will determine where the tiles are for this call.

New in version 1.16.

TCOD_Error TCOD_context_screen_pixel_to_tile_i(struct TCOD_Context *context, int *x, int *y)

Convert the screen coordinates to integer tile coordinates for this context.

Save as TCOD_context_screen_pixel_to_tile but the inputs and results are integers. This is useful if you don’t need sub-tile coordinates.

New in version 1.16.

TCOD_Error TCOD_context_convert_event_coordinates(struct TCOD_Context *context, union SDL_Event *event)

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

New in version 1.19.

TCOD_Error TCOD_context_save_screenshot(struct TCOD_Context *context, const char *filename)

Save the last presented console to a PNG file.

New in version 1.16.

struct SDL_Window *TCOD_context_get_sdl_window(struct TCOD_Context *context)

Return a pointer the SDL_Window for this context if it uses one.

New in version 1.16.

struct SDL_Renderer *TCOD_context_get_sdl_renderer(struct TCOD_Context *context)

Return a pointer the SDL_Renderer for this context if it uses one.

New in version 1.16.

REXPaint Files

These functions allow the saving and loading of REXPaint files.

Keep in mind that REXPaint files are typically encoded as Code Page 437 which will need to be converted into Unicode to be understood by libtcod.

C++ API

inline std::vector<tcod::ConsolePtr> tcod::load_xp(const std::filesystem::path &path)

Load an array of consoles from a REXPaint file.

New in version 1.18.

Parameters:

path – The path to the REXPaint file to load.

Returns:

Returns a vector of consoles.

inline void tcod::save_xp(const std::vector<const TCOD_Console*> &consoles, const std::filesystem::path &path, int compress_level = 9)

Save an array of consoles to a REXPaint file.

New in version 1.18.

Parameters:

• consoles – A vector of consoles to save.

• path – The path to write the REXPaint file to.

• compress_level – A compression level for the zlib library.

C API

int TCOD_load_xp(const char *path, int n, TCOD_Console **out)

Load an array of consoles from a REXPaint file.

New in version 1.18.

Parameters:

• path – The path to the REXPaint file, can not be NULL.

• n – The size of the out array. Can be zero.

• out – The array to fill with loaded consoles.

Returns:

Returns the number of consoles held by the file. Returns a negative error code on error.

TCOD_Error TCOD_save_xp(int n, const TCOD_Console *const *consoles, const char *path, int compress_level)

Save an array of consoles to a REXPaint file.

Partially initialized consoles are released on failures.

New in version 1.18.

Parameters:

• n – The number of consoles in the consoles array.

• consoles – An array of consoles.

• path – The path write the REXPaint file, can not be NULL.

• compress_level – A compression level for the zlib library.

Returns:

Returns an error code on failure.

int TCOD_load_xp_from_memory(int n_data, const unsigned char *data, int n_out, TCOD_Console **out)

Load an array of consoles from a REXPaint file in memory.

You can call this function with n_out=0 and out=NULL to get the number of consoles in the file.

New in version 1.18.

Parameters:

• n_data – The length of the input data buffer.

• data – The buffer where the REXPaint file is held.

• n_out – The length of the output console out array. Can be zero.

• out – The array to fill with loaded consoles.

Returns:

Returns the number of consoles held by the file. Returns a negative error code on error.

int TCOD_save_xp_to_memory(int n_consoles, const TCOD_Console *const *consoles, int n_out, unsigned char *out, int compression_level)

Save an array of consoles to a REXPaint file in memory.

Partially initialized consoles are released on failures.

New in version 1.18.

Parameters:

• n_consoles – The length of the input consoles array.

• consoles – An array of tcod consoles, can not be NULL.

• n_out – The size of the out buffer, if this is zero then upper bound to be returned.

• out – A pointer to an output buffer, can be NULL.

• compression_level – A compression level for the zlib library.

Returns:

If out=NULL then returns the upper bound of the buffer size needed. Otherwise this returns the number of bytes actually filled. On an error a negative error code is returned.

Tilesets

struct TCOD_Tileset

A container for libtcod tileset graphics.

New in version 1.19.

class Tileset

A C++ Tileset container.

New in version 1.19.

Public Functions

Tileset() = default

Construct a new Tileset object.

inline explicit Tileset(int tile_width, int tile_height)

Construct a new Tileset object with tiles of the given size.

The tileset will be empty.

Parameters:

• tile_width – The width of the tiles of this object in pixels.

• tile_height – The width of the tiles of this object in pixels.

inline explicit Tileset(const std::array<int, 2> &tile_shape)

Construct a new Tileset object with tiles of the given size.

The tileset will be empty.

Parameters:

tile_shape – The {width, height} of the tiles in pixels.

inline explicit Tileset(TilesetPtr ptr)

Pass ownership of a TilesetPtr to a new Tileset.

Parameters:

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

inline explicit Tileset(TCOD_Tileset *ptr)

Takes ownership of a raw TCOD_Tileset pointer.

Parameters:

ptr – A pointer which will now be managed by this object.

inline auto get_tile_width() const noexcept -> int

Get the width of tiles in this Tileset.

Returns:

int The total width of tiles in pixels.

inline auto get_tile_height() const noexcept -> int

Get the height of tiles in this Tileset.

Returns:

int The total height of tiles in pixels.

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

Get the {width, height} shape of tiles in this Tileset.

Returns:

std::array<int, 2> The {width, height} of tiles in this Tileset in pixels.

inline auto get() noexcept -> TCOD_Tileset*

Return a non-owning pointer to this objects TCOD_Tileset.

Returns:

TCOD_Tileset

inline auto get() const noexcept -> TCOD_Tileset*

Return a non-owning pointer to this objects TCOD_Tileset.

Returns:

TCOD_Tileset

inline auto release() noexcept -> TCOD_Tileset*

Release ownership of this Tileset’s TCOD_Tileset* and return the pointer.

Using this Tileset afterwards is undefined.

inline operator TCOD_Tileset&()

Allow implicit conversions to a TCOD_Console reference.

inline operator const TCOD_Tileset&() const

Allow implicit conversions to a const TCOD_Console reference.

typedef std::unique_ptr<TCOD_Tileset, TilesetDeleter> tcod::TilesetPtr

A unique pointer to a TCOD_Tileset.

New in version 1.19.

Tilesheets

static constexpr std::array<int, 256> tcod::CHARMAP_CP437 = {0x0000, 0x263A, 0x263B, 0x2665, 0x2666, 0x2663, 0x2660, 0x2022, 0x25D8, 0x25CB, 0x25D9, 0x2642, 0x2640, 0x266A, 0x266B, 0x263C, 0x25BA, 0x25C4, 0x2195, 0x203C, 0x00B6, 0x00A7, 0x25AC, 0x21A8, 0x2191, 0x2193, 0x2192, 0x2190, 0x221F, 0x2194, 0x25B2, 0x25BC, 0x0020, 0x0021, 0x0022, 0x0023, 0x0024, 0x0025, 0x0026, 0x0027, 0x0028, 0x0029, 0x002A, 0x002B, 0x002C, 0x002D, 0x002E, 0x002F, 0x0030, 0x0031, 0x0032, 0x0033, 0x0034, 0x0035, 0x0036, 0x0037, 0x0038, 0x0039, 0x003A, 0x003B, 0x003C, 0x003D, 0x003E, 0x003F, 0x0040, 0x0041, 0x0042, 0x0043, 0x0044, 0x0045, 0x0046, 0x0047, 0x0048, 0x0049, 0x004A, 0x004B, 0x004C, 0x004D, 0x004E, 0x004F, 0x0050, 0x0051, 0x0052, 0x0053, 0x0054, 0x0055, 0x0056, 0x0057, 0x0058, 0x0059, 0x005A, 0x005B, 0x005C, 0x005D, 0x005E, 0x005F, 0x0060, 0x0061, 0x0062, 0x0063, 0x0064, 0x0065, 0x0066, 0x0067, 0x0068, 0x0069, 0x006A, 0x006B, 0x006C, 0x006D, 0x006E, 0x006F, 0x0070, 0x0071, 0x0072, 0x0073, 0x0074, 0x0075, 0x0076, 0x0077, 0x0078, 0x0079, 0x007A, 0x007B, 0x007C, 0x007D, 0x007E, 0x2302, 0x00C7, 0x00FC, 0x00E9, 0x00E2, 0x00E4, 0x00E0, 0x00E5, 0x00E7, 0x00EA, 0x00EB, 0x00E8, 0x00EF, 0x00EE, 0x00EC, 0x00C4, 0x00C5, 0x00C9, 0x00E6, 0x00C6, 0x00F4, 0x00F6, 0x00F2, 0x00FB, 0x00F9, 0x00FF, 0x00D6, 0x00DC, 0x00A2, 0x00A3, 0x00A5, 0x20A7, 0x0192, 0x00E1, 0x00ED, 0x00F3, 0x00FA, 0x00F1, 0x00D1, 0x00AA, 0x00BA, 0x00BF, 0x2310, 0x00AC, 0x00BD, 0x00BC, 0x00A1, 0x00AB, 0x00BB, 0x2591, 0x2592, 0x2593, 0x2502, 0x2524, 0x2561, 0x2562, 0x2556, 0x2555, 0x2563, 0x2551, 0x2557, 0x255D, 0x255C, 0x255B, 0x2510, 0x2514, 0x2534, 0x252C, 0x251C, 0x2500, 0x253C, 0x255E, 0x255F, 0x255A, 0x2554, 0x2569, 0x2566, 0x2560, 0x2550, 0x256C, 0x2567, 0x2568, 0x2564, 0x2565, 0x2559, 0x2558, 0x2552, 0x2553, 0x256B, 0x256A, 0x2518, 0x250C, 0x2588, 0x2584, 0x258C, 0x2590, 0x2580, 0x03B1, 0x00DF, 0x0393, 0x03C0, 0x03A3, 0x03C3, 0x00B5, 0x03C4, 0x03A6, 0x0398, 0x03A9, 0x03B4, 0x221E, 0x03C6, 0x03B5, 0x2229, 0x2261, 0x00B1, 0x2265, 0x2264, 0x2320, 0x2321, 0x00F7, 0x2248, 0x00B0, 0x2219, 0x00B7, 0x221A, 0x207F, 0x00B2, 0x25A0, 0x00A0,}

A character mapping of a Code Page 437 tileset to Unicode.

New in version 1.19.

static constexpr std::array<int, 256> tcod::CHARMAP_TCOD = {0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2A, 0x2B, 0x2C, 0x2D, 0x2E, 0x2F, 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x3B, 0x3C, 0x3D, 0x3E, 0x3F, 0x40, 0x5B, 0x5C, 0x5D, 0x5E, 0x5F, 0x60, 0x7B, 0x7C, 0x7D, 0x7E, 0x2591, 0x2592, 0x2593, 0x2502, 0x2500, 0x253C, 0x2524, 0x2534, 0x251C, 0x252C, 0x2514, 0x250C, 0x2510, 0x2518, 0x2598, 0x259D, 0x2580, 0x2596, 0x259A, 0x2590, 0x2597, 0x2191, 0x2193, 0x2190, 0x2192, 0x25B2, 0x25BC, 0x25C4, 0x25BA, 0x2195, 0x2194, 0x2610, 0x2611, 0x25CB, 0x25C9, 0x2551, 0x2550, 0x256C, 0x2563, 0x2569, 0x2560, 0x2566, 0x255A, 0x2554, 0x2557, 0x255D, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A, 0x4B, 0x4C, 0x4D, 0x4E, 0x4F, 0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5A, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x6B, 0x6C, 0x6D, 0x6E, 0x6F, 0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,}

A character mapping of a deprecated TCOD tileset to Unicode.

New in version 1.19.

template<typename ArrayType>
inline auto tcod::load_tilesheet(const std::filesystem::path &path, const std::array<int, 2> &columns_rows, const ArrayType &charmap) -> Tileset

Load a tilesheet from a PNG file.

An exception will be thrown if the file is missing or corrupt.

Tiles are indexed in row-major order and should be assigned to Unicode codepoints.

New in version 1.19.

Template Parameters:

ArrayType – Must be a std::vector or std::array like type. With size() and data() methods.

Parameters:

• path – The file path to the PNG tilesheet image.

• columns_rows – The shape of the grid on the tileset as {columns, rows}.

• charmap – An array of characters where charmap[tile_index] = codepoint. tcod::CHARMAP_CP437 or tcod::CHARMAP_TCOD are typical values for this argument.

Returns:

TilesetPtr A unique pointer to a TCOD_Tileset.

BDF

TCOD_Tileset *TCOD_load_bdf(const char *path)

Load a BDF font from a file path.

For the best results, you should use a BDF font with a cell-based monospace alignment.

May return NULL on failure. See TCOD_get_error for the error message.

New in version 1.16.

TCOD_Tileset *TCOD_load_bdf_memory(int size, const unsigned char *buffer)

Load a BDF font from memory.

size is the byte length of buffer. buffer is the BDF data to load.

May return NULL on failure. See TCOD_get_error for the error message.

New in version 1.16.

inline auto load_bdf(const std::filesystem::path &path) -> TilesetPtr

Load a Tileset from a BDF font file.

Will throw an exception on a missing or corrupt file.

New in version 1.19.

C API

TCOD_Tileset *TCOD_tileset_new(int tile_width, int tile_height)

Create a new tile-set with the given tile size.

New in version 1.19.

void TCOD_tileset_delete(TCOD_Tileset *tileset)

Delete a tile-set.

New in version 1.19.

static const int TCOD_CHARMAP_CP437[256] = {0x0000, 0x263A, 0x263B, 0x2665, 0x2666, 0x2663, 0x2660, 0x2022, 0x25D8, 0x25CB, 0x25D9, 0x2642, 0x2640, 0x266A, 0x266B, 0x263C, 0x25BA, 0x25C4, 0x2195, 0x203C, 0x00B6, 0x00A7, 0x25AC, 0x21A8, 0x2191, 0x2193, 0x2192, 0x2190, 0x221F, 0x2194, 0x25B2, 0x25BC, 0x0020, 0x0021, 0x0022, 0x0023, 0x0024, 0x0025, 0x0026, 0x0027, 0x0028, 0x0029, 0x002A, 0x002B, 0x002C, 0x002D, 0x002E, 0x002F, 0x0030, 0x0031, 0x0032, 0x0033, 0x0034, 0x0035, 0x0036, 0x0037, 0x0038, 0x0039, 0x003A, 0x003B, 0x003C, 0x003D, 0x003E, 0x003F, 0x0040, 0x0041, 0x0042, 0x0043, 0x0044, 0x0045, 0x0046, 0x0047, 0x0048, 0x0049, 0x004A, 0x004B, 0x004C, 0x004D, 0x004E, 0x004F, 0x0050, 0x0051, 0x0052, 0x0053, 0x0054, 0x0055, 0x0056, 0x0057, 0x0058, 0x0059, 0x005A, 0x005B, 0x005C, 0x005D, 0x005E, 0x005F, 0x0060, 0x0061, 0x0062, 0x0063, 0x0064, 0x0065, 0x0066, 0x0067, 0x0068, 0x0069, 0x006A, 0x006B, 0x006C, 0x006D, 0x006E, 0x006F, 0x0070, 0x0071, 0x0072, 0x0073, 0x0074, 0x0075, 0x0076, 0x0077, 0x0078, 0x0079, 0x007A, 0x007B, 0x007C, 0x007D, 0x007E, 0x2302, 0x00C7, 0x00FC, 0x00E9, 0x00E2, 0x00E4, 0x00E0, 0x00E5, 0x00E7, 0x00EA, 0x00EB, 0x00E8, 0x00EF, 0x00EE, 0x00EC, 0x00C4, 0x00C5, 0x00C9, 0x00E6, 0x00C6, 0x00F4, 0x00F6, 0x00F2, 0x00FB, 0x00F9, 0x00FF, 0x00D6, 0x00DC, 0x00A2, 0x00A3, 0x00A5, 0x20A7, 0x0192, 0x00E1, 0x00ED, 0x00F3, 0x00FA, 0x00F1, 0x00D1, 0x00AA, 0x00BA, 0x00BF, 0x2310, 0x00AC, 0x00BD, 0x00BC, 0x00A1, 0x00AB, 0x00BB, 0x2591, 0x2592, 0x2593, 0x2502, 0x2524, 0x2561, 0x2562, 0x2556, 0x2555, 0x2563, 0x2551, 0x2557, 0x255D, 0x255C, 0x255B, 0x2510, 0x2514, 0x2534, 0x252C, 0x251C, 0x2500, 0x253C, 0x255E, 0x255F, 0x255A, 0x2554, 0x2569, 0x2566, 0x2560, 0x2550, 0x256C, 0x2567, 0x2568, 0x2564, 0x2565, 0x2559, 0x2558, 0x2552, 0x2553, 0x256B, 0x256A, 0x2518, 0x250C, 0x2588, 0x2584, 0x258C, 0x2590, 0x2580, 0x03B1, 0x00DF, 0x0393, 0x03C0, 0x03A3, 0x03C3, 0x00B5, 0x03C4, 0x03A6, 0x0398, 0x03A9, 0x03B4, 0x221E, 0x03C6, 0x03B5, 0x2229, 0x2261, 0x00B1, 0x2265, 0x2264, 0x2320, 0x2321, 0x00F7, 0x2248, 0x00B0, 0x2219, 0x00B7, 0x221A, 0x207F, 0x00B2, 0x25A0, 0x00A0,}

A character mapping of a Code Page 437 tileset to Unicode.

New in version 1.19.

static const int TCOD_CHARMAP_TCOD[256] = {0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2A, 0x2B, 0x2C, 0x2D, 0x2E, 0x2F, 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x3B, 0x3C, 0x3D, 0x3E, 0x3F, 0x40, 0x5B, 0x5C, 0x5D, 0x5E, 0x5F, 0x60, 0x7B, 0x7C, 0x7D, 0x7E, 0x2591, 0x2592, 0x2593, 0x2502, 0x2500, 0x253C, 0x2524, 0x2534, 0x251C, 0x252C, 0x2514, 0x250C, 0x2510, 0x2518, 0x2598, 0x259D, 0x2580, 0x2596, 0x259A, 0x2590, 0x2597, 0x2191, 0x2193, 0x2190, 0x2192, 0x25B2, 0x25BC, 0x25C4, 0x25BA, 0x2195, 0x2194, 0x2610, 0x2611, 0x25CB, 0x25C9, 0x2551, 0x2550, 0x256C, 0x2563, 0x2569, 0x2560, 0x2566, 0x255A, 0x2554, 0x2557, 0x255D, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A, 0x4B, 0x4C, 0x4D, 0x4E, 0x4F, 0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5A, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x6B, 0x6C, 0x6D, 0x6E, 0x6F, 0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,}

A character mapping of a deprecated TCOD tileset to Unicode.

New in version 1.19.

TCOD_Tileset *TCOD_tileset_load(const char *filename, int columns, int rows, int n, const int *charmap)

Load a PNG font as a tilesheet and return a TCOD_Tileset.

filename is the path to a PNG file.

columns and rows are the shape of the tileset in the image. The tile size will be derived from these parameters and the size of the image.

charmap[n] is an array of which codepoints to assign to which tiles. Tiles are assigned in row-major order. TCOD_CHARMAP_CP437 or TCOD_CHARMAP_TCOD could be used here.

New in version 1.19.

TCOD_Tileset *TCOD_tileset_load_mem(size_t buffer_length, const unsigned char *buffer, int columns, int rows, int n, const int *charmap)

Load a PNG font from memory and return a TCOD_Tileset.

buffer[buffer_length] is the PNG data to load.

The remaining parameters are the same as TCOD_tileset_load.

New in version 1.19.

TCOD_Tileset *TCOD_tileset_load_raw(int width, int height, const struct TCOD_ColorRGBA *pixels, int columns, int rows, int n, const int *charmap)

Load raw RGBA data and return a TCOD_Tileset.

pixels[width*height] is a row-major RGBA-ordered byte array.

The remaining parameters are the same as TCOD_tileset_load.

New in version 1.19.

TCOD_Error TCOD_tileset_render_to_surface(const TCOD_Tileset *tileset, const TCOD_Console *console, TCOD_Console **cache, struct SDL_Surface **surface_out)

Render a console to a SDL_Surface with a software renderer.

tileset is the tiles to render with, must not be NULL.

console is the console to render, must not be NULL.

cache is an optional pointer to a consoled used as a cache. The console at *cache will be created or modified. The cache will be used to skip drawing already drawn tiles on any subsequent calls.

surface_out is a pointer to where to put the surface will be managed. The surface at *surface_out will be created or modified and will change to match the size of console and tileset. The pixel format will be SDL_PIXELFORMAT_RGBA32.

Returns a negative value on error, see TCOD_get_error.

New in version 1.16.

TCOD_Tileset *TCOD_get_default_tileset(void)

Return the default tileset, may be NULL.

A non-NULL return value is a new reference to the global tileset. When you are done you will need to call TCOD_tileset_delete on this pointer.

This function is provisional, the API may change in the future.

New in version 1.19.

void TCOD_set_default_tileset(TCOD_Tileset *tileset)

Set the default tileset and update the default display to use it.

This will keep alive a reference to the given tileset. If you no longer need the pointer then you should call TCOD_tileset_delete on it after this function.

This function is provisional, the API may change in the future.

New in version 1.19.

Upgrading

Porting to 1.19

Any new project should use the Getting Started guide so that they can start using contexts right way. Older projects will have to convert to contexts over a series of steps.

The old way of initializing a global state with TCOD_console_init_root() or TCODConsole::initRoot has been deprecated. These have been replaced with a public context object.

New tileset API

You can switch away from TCOD_console_set_custom_font() before using contexts by using the TCOD_set_default_tileset() function.

// The old way to load tilesets:
// TCOD_console_set_custom_font("terminal8x8_gs_tc.png", TCOD_FONT_LAYOUT_TCOD, 32, 8);

// You can update old code to use this new method of loading tilesets before using contexts properly.
auto tileset = tcod::load_tilesheet("terminal8x8_gs_tc.png", {32, 8}, tcod::CHARMAP_TCOD);
TCOD_set_default_tileset(tileset.get());

// This is deprecated, but will work with the above tileset.
TCOD_console_init_root(80, 25, "Window title", true, TCOD_RENDERER_OPENGL2);

Later when you upgrade to contexts you will replace TCOD_set_default_tileset() with TCOD_ContextParams.

auto params = TCOD_ContextParams{};
params.tcod_version = TCOD_COMPILEDVERSION;  // This is required.
params.columns = 80;
params.rows = 25;
params.tileset = tileset.get();
params.vsync = 1;
params.sdl_window_flags = SDL_WINDOW_RESIZABLE;
params.window_title = "Window title";

auto context = tcod::new_context(params);

Using the new console functions

There is less state with the new functions. Instead of setting colors before calling the print functions you now pass the colors and flags needed for each print call.

static constexpr auto WHITE = tcod::ColorRGB{255, 255, 255};

TCODConsole* console = new TCODConsole(80, 25);  // Deprecated.

tcod::print(
  *console,  // Should be a tcod::Console reference, but a TCODConsole reference can be used for these functions.
  {0, 0},  // Coordinates are passed together.
  tcod::stringf("%s %s", "Hello", "world"),  // Printf-like strings are encapsulated in tcod::stringf.
  WHITE,  // Color parameters are std::optional.
  std::nullopt,  // Passing std::nullopt here leaves the background color unchanged.
)

tcod::ColorRGB bg = TCOD_console_get_char_background(TCODConsole::root->get_data());
tcod::draw_rect(
  *TCODConsole::root,  // TCODConsole::root is deprecated, but can still be passed as a parameter if it's initialized.
  {0, 0, 20, 1},  // {left, top, width, height}
  0x2500,  // "─" BOX DRAWINGS LIGHT HORIZONTAL.  Unicode is expected for character codes.
  WHITE,
  bg,
)

Adapting to contexts and a rootless console

Before initializing a context properly you can access both the context and the root console. This lets you use context methods like TCOD_Context::present() easily in older code. This also lets you use the root console on functions which can’t accept nullptr.

TCOD_console_init_root(80, 25, "Window title", true, TCOD_RENDERER_OPENGL2);  // Deprecated.

// Get a temporary non-owning pointer to the context made by TCOD_console_init_root or TCODConsole::initRoot.
TCOD_Context* context = TCOD_sys_get_internal_context();

// Get a temporary non-owning reference to the root console made by TCOD_console_init_root or TCODConsole::initRoot.
TCOD_Console& root_console = *TCOD_sys_get_internal_console();
// From now on use root_console instead of NULL, make this global if you have to.

// Using the root console with the context is similar to calling TCOD_console_flush() with some exceptions.
context->present(root_console);  // Or in C: TCOD_context_present(context, root_console, NULL)

Using the context present function like this will break some functions which say they’re not compatible with contexts. Most importantly any timing-related functions will need to be updated. See Timing below.

The next step is to actually replace TCOD_console_init_root() with contexts.

auto root_console = tcod::Console{80, 25};  // TCOD_Console& can be replaced with tcod::Console.

auto params = TCOD_ContextParams{};
params.tcod_version = TCOD_COMPILEDVERSION;
params.vsync = 1;
params.sdl_window_flags = SDL_WINDOW_RESIZABLE;
params.window_title = "Window title";
params.console = root_console.get();  // Set the window size from the console size.

auto context = tcod::new_context(params);

context->present(root_console);

Window manipulation

With the temporary context from the previous step or with TCOD_sys_get_sdl_window() you can access the SDL_Window pointer. You use this to replace several window-related functions such as TCOD_console_set_fullscreen(), TCOD_console_is_active() or TCOD_console_set_window_title(). See the SDL2 window documentation for what you can do with the SDL_Window pointer.

TCOD_console_init_root(80, 25, "Window title", false, TCOD_RENDERER_OPENGL2);  // Deprecated.
TCOD_Context* context = TCOD_sys_get_internal_context();
SDL_Window* sdl_window = context->get_sdl_window();

if (sdl_window) {
  SDL_SetWindowTitle(sdl_window, "New title");
  if (SDL_GetWindowFlags(sdl_window) & SDL_WINDOW_INPUT_FOCUS) {}
}

Event systems

Libtcod’s event systems have been deprecated in favor of using SDL2 directly for events. TCOD_Context::convert_event_coordinates() is the recommended way to convert pixel coordinates to tiles. tcod::sdl2::process_event() might work better for converting old code to use the new system.

// tcod::ContextPtr context = tcod::new_context(...);  // For code using contexts.
// TCOD_Context* context = TCOD_sys_get_internal_context();  // For code still using the old API.

while (true) {
  SDL_Event event;
  while (SDL_PollEvent(&event)) {
    // context->convert_event_coordinates(event);  // Optional, converts mouse pixel coordinates into tile coordinates.
    switch (event.type) {
      case SDL_QUIT:
        std::exit(EXIT_SUCCESS);
        break;
      case SDL_KEYDOWN: {
        TCOD_mouse_t key;
        tcod::sdl2::process_event(event, key);  // Convert a SDL key to a libtcod key event, to help port older code.
        switch (event.key.keysym.sym) {
          case SDLK_EQUALS: // equals/plus key symbol.
            if (event.key.keysym.mod & KMOD_SHIFT) {
              // Handle plus key.
            }
            break;
          default:
            break;
        }
      } break;
      case SDL_MOUSEBUTTONDOWN: {
        TCOD_mouse_t mouse;
        tcod::sdl2::process_event(event, mouse);  // Convert SDL into a libtcod mouse event, to help port older code.
        // The above expects pixel coordinates.  So you can't use convert_event_coordinates before process_event.
        context->convert_event_coordinates(event);
      } break;
      default:
        break;
    }
  }
}

Timing

All of the libtcod timing functions have been deprecated. Many will stop working once you switch to using contexts. Instead you should use tcod::Timer and SDL2’s timing functions. Remember that you have to add #include <libtcod/timer.hpp> to access tcod::Timer, this also requires the SDL2 headers.

int desired_fps = 30;
auto timer = tcod::Timer();

while (1) {
  uint32_t current_time_ms = SDL_GetTicks();
  float current_time = static_cast<float>(current_time_ms) / 1000.f;
  float delta_time = timer.sync(desired_fps);
  // ...
}

Switching to contexts

With all the above done you can now switch away from TCOD_console_init_root() and start using TCOD_ContextParams and tcod::new_context().

#include <libtcod.hpp>
#include <SDL.h>

int main(int argc, char* argv[]) {
  auto root_console = tcod::Console{80, 25};
  auto tileset = tcod::load_tilesheet("terminal8x8_gs_tc.png", {32, 8}, tcod::CHARMAP_TCOD);

  TCOD_ContextParams params{};
  params.tcod_version = TCOD_COMPILEDVERSION;
  params.console = root_console.get();
  params.window_title = "Window title";
  params.sdl_window_flags = SDL_WINDOW_RESIZABLE;
  params.vsync = true;
  params.argc = argc;
  params.argv = argv;
  params.tileset = tileset.get();

  auto context = tcod::new_context(params);

  while (1) {
    context->present(root_console);

    SDL_Event event;
    while (SDL_PollEvent(&event)){
      switch (event.type) {
        case SDL_QUIT:
          return 0;  // Exit.
      }
    }
  }
}

Porting to 1.6

The largest and most influential change to libtcod, between versions 1.5.2 and 1.6.0, was the move to replace SDL with SDL2. SDL2 made many extensive changes to concepts used in SDL. Only one of these changes, the separation of text and key events, required a change in the libtcod API requiring users to update their code in the process of updating the version of libtcod they use.

When a user presses a key, they may be pressing SHIFT and =. On some keyboards, depending on the user’s language and location, this may show + on the screen. On other user’s keyboards, who knows what it may show on screen. SDL2 changes the way “the text which is displayed on the user’s screen” is sent in key events. This means that the key event for SHIFT and = will be what happens for presses of both + and = (for user’s with applicable keyboards), and there will be a new text event that happens with the displayed +.

In libtcod 1.5.x

SDL would when sending key events, provide the unicode character for the key event, ready for use. This meant that if the user happened to be using a British keyboard (or any that are similarly laid out), and pressed SHIFT and =, the event would be for the character +.

C / C++

if (key->c == '+') {
    /* Handle any key that displays a plus. */
}

In libtcod 1.6.x

With SDL2, the raw key-presses still occur, but they are fundamentally linked to the keyboard of the user. Now there will still be an event where it says SHIFT and = are pressed, but the event will always be for the unmodified character =. The unicode text arrives in a new kind of event, and getting it requires explicitly checking that the event is the new text event, and then looking for the value in the relevant text field for the language being used.

C / C++

if (key->vk == TCODK_TEXT)
    if (key.text[0] == '+') {
        ; /* Handle any key that displays a plus. */
    }

Still confused?

Run your code from a terminal or DOS window and print out the event attributes/fields and look at what is going on. Have your code print out the modifiers, the keycode, the character, the text, and then run it and try pressing some keys. It will be much faster than posting “I don’t understand” or “Can someone explain” somewhere and waiting for a response.

Getting Started

This guide sets up a portable project which will work for all platforms (Windows/Mac/Linux) as long as these instructions are followed closely. If you are unsure about anything then you can refer to the libtcod template project for a known working example. The template project includes Emscripten support which will not be covered by this getting started example.

This guide will show how to setup a Libtcod project with a CMake/Vcpkg build system. You will need Git, CMake, and a compiler. For Windows Visual Studio Community will be used for the compiler.

Here is a simple example of setting up a libtcod context in C++ without using deprecated functions. Put this code at ./src/main.cpp:

#include <SDL.h>
#include <libtcod.hpp>

int main(int argc, char* argv[]) {
  auto console = tcod::Console{80, 25};  // Main console.

  // Configure the context.
  auto params = TCOD_ContextParams{};
  params.tcod_version = TCOD_COMPILEDVERSION;  // This is required.
  params.console = console.get();  // Derive the window size from the console size.
  params.window_title = "Libtcod Project";
  params.sdl_window_flags = SDL_WINDOW_RESIZABLE;
  params.vsync = true;
  params.argc = argc;  // This allows some user-control of the context.
  params.argv = argv;

  // Tileset example using a Code Page 437 font.
  // "terminal8x8_gs_ro.png" must be in the working directory.
  // auto tileset = tcod::load_tilesheet("terminal8x8_gs_ro.png", {16, 16}, tcod::CHARMAP_CP437);
  // params.tileset = tileset.get();

  auto context = tcod::Context(params);

  while (1) {  // Game loop.
    TCOD_console_clear(console.get());
    tcod::print(console, {0, 0}, "Hello World", std::nullopt, std::nullopt);
    context.present(console);  // Updates the visible display.

    SDL_Event event;
    SDL_WaitEvent(nullptr);  // Optional, sleep until events are available.
    while (SDL_PollEvent(&event)) {
      context.convert_event_coordinates(event);  // Optional, converts pixel coordinates into tile coordinates.
      switch (event.type) {
        case SDL_QUIT:
          return 0;  // Exit.
      }
    }
  }
}

This source file assumes that an environment with SDL2 and libtcod is setup correctly. To setup this environment CMake will be used to invoke Vcpkg to include those libraries.

This is done with a ./CMakeLists.txt script:

cmake_minimum_required (VERSION 3.21)

# Set the default toolchain to use a Vcpkg submodule.
if(NOT DEFINED CMAKE_TOOLCHAIN_FILE)
    set(CMAKE_TOOLCHAIN_FILE
        "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
        CACHE STRING "Vcpkg toolchain file")
endif()

project(
    libtcod-getting-started  # Project name, change this as needed.
    LANGUAGES C CXX
)

set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/bin")  # Save all runtime files to this directory.

file(
    GLOB_RECURSE SOURCE_FILES
    CONFIGURE_DEPENDS  # Automatically reconfigure if source files are added/removed.
    ${PROJECT_SOURCE_DIR}/src/*.cpp
    ${PROJECT_SOURCE_DIR}/src/*.hpp
)
add_executable(${PROJECT_NAME} ${SOURCE_FILES})

# Ensure the C++17 standard is available.
target_compile_features(${PROJECT_NAME} PRIVATE cxx_std_17)

# Enforce UTF-8 encoding on MSVC.
if (MSVC)
    target_compile_options(${PROJECT_NAME} PRIVATE /utf-8)
endif()

# Enable warnings recommended for new projects.
if (MSVC)
    target_compile_options(${PROJECT_NAME} PRIVATE /W4)
else()
    target_compile_options(${PROJECT_NAME} PRIVATE -Wall -Wextra)
endif()

find_package(SDL2 CONFIG REQUIRED)
find_package(libtcod CONFIG REQUIRED)
target_link_libraries(${PROJECT_NAME} PRIVATE SDL2::SDL2 SDL2::SDL2main libtcod::libtcod)

Since this CMake script is configured to use a Vcpkg submodule we will set that up now.

Open a terminal to the project directory. If the project is opened in an IDE then you should have a “terminal” tab which will be opened to the project root directory. Most platforms will let you open a terminal by right-clicking on the folder from its file explorer. On Windows after you’ve installed Git for Windows then you should have a “Git Bash Here” as an easy option to open a terminal.

With the terminal run git init to turn the folder into a Git repo, then run git submodule add https://github.com/microsoft/vcpkg.git to add the Vcpkg submodule. You should have a new folder at ./vcpkg with the Vcpkg repo.

While SDL2 and libtcod could be manually installed with Vcpkg, they can also be automatically managed with Vcpkg’s Manifest Mode. In Manifest Mode CMake will invoke Vcpkg which will automatically download and compile any libraries listed in the manifest.

Create a ./vcpkg.json manifest:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg/master/scripts/vcpkg.schema.json",
  "name": "getting-started",
  "version-semver": "0.0.0",
  "dependencies": [
    "libtcod",
    "sdl2",
    {
      "name": "sdl2",
      "default-features": false,
      "features": [
        "x11"
      ],
      "platform": "linux"
    }
  ]
}

The build system is fully setup. You can compile and run the program with CMake or any IDE which integrates with CMake. Visual Studio Community is one of those IDE’s, you can open the project folder and then pick libtcod-getting-started as the target to run when asked. VScode with the CMake Tools plugin can also build CMake projects, when asked pick the Visual Studio Community toolkit matching the compiler you installed and then pick libtcod-getting-started as the launch target. VSCode works on all platforms and can be told to use whichever compiler is available locally. Most other IDE’s should have CMake integration if you look them up.

If you are stuck then try getting the libtcod template project to run since it is a known working example. If you are still stuck then you can open a discussion on GitHub.

Library API

Page Hierarchy

• • Deprecated List

File Hierarchy

• • File bresenham.h
  • File bresenham.hpp
  • File bsp.h
  • File bsp.hpp
  • File color.h
  • File color.hpp
  • File config.h
  • File console.h
  • File console.hpp
  • File console_drawing.h
  • File console_etc.h
  • File console_init.h
  • File console_printing.h
  • File console_printing.hpp
  • File console_rexpaint.h
  • File console_rexpaint.hpp
  • File console_types.h
  • File console_types.hpp
  • File context.h
  • File context.hpp
  • File context_init.h
  • File context_viewport.h
  • File error.h
  • File error.hpp
  • File event.h
  • File fov.h
  • File fov.hpp
  • File fov_types.h
  • File globals.h
  • File heapq.h
  • File heightmap.h
  • File heightmap.hpp
  • File image.h
  • File image.hpp
  • File lex.h
  • File lex.hpp
  • File libtcod.h
  • File libtcod.h
  • File libtcod.hpp
  • File libtcod.hpp
  • File list.h
  • File list.hpp
  • File logging.h
  • File matrix.hpp
  • File mersenne.h
  • File mersenne.hpp
  • File mersenne_types.h
  • File mouse.h
  • File mouse.hpp
  • File mouse_types.h
  • File namegen.h
  • File namegen.hpp
  • File noise.h
  • File noise.hpp
  • File noise_defaults.h
  • File parser.h
  • File parser.hpp
  • File path.h
  • File path.hpp
  • File pathfinder.h
  • File pathfinder_frontier.h
  • File portability.h
  • File random.h
  • File renderer_sdl2.h
  • File renderer_xterm.h
  • File sys.h
  • File sys.hpp
  • File tileset.h
  • File tileset.hpp
  • File tileset_bdf.h
  • File tileset_bdf.hpp
  • File tileset_fallback.h
  • File tileset_fallback.hpp
  • File tileset_render.h
  • File tileset_truetype.h
  • File timer.h
  • File timer.hpp
  • File tree.h
  • File tree.hpp
  • File txtfield.h
  • File txtfield.hpp
  • File utility.h
  • File version.h
  • File wrappers.h
  • File zip.h
  • File zip.hpp

Full API

Namespaces

Namespace tcod

Namespaces

• Namespace tcod::console

• Namespace tcod::sdl2

• Namespace tcod::tileset

Classes

• Struct BresenhamLine::Matrix

• Struct ColorRGB

• Struct ColorRGBA

• Struct ConsoleDeleter

• Struct ContextDeleter

• Struct ImageDeleter

• Struct TilesetDeleter

• Class BresenhamLine

• Class Console

• Template Class Matrix

• Template Class MatrixView

• Class Tileset

• Class Timer

Functions

• Function tcod::blit

• Function tcod::check_path

• Function tcod::check_throw_error(TCOD_Error)

• Function tcod::check_throw_error(int)

• Function tcod::draw_frame

• Function tcod::draw_quartergraphics

• Function tcod::draw_rect

• Function tcod::get_height_rect

• Function tcod::load_bdf

• Template Function tcod::load_tilesheet

• Function tcod::load_xp

• Function tcod::new_context(const TCOD_ContextParams&)

• Function tcod::new_context(const TCOD_ContextParams&, TCOD_Error&)

• Function tcod::print

• Function tcod::print_frame

• Function tcod::print_rect

• Function tcod::save_xp

• Function tcod::set_error(const std::string&)

• Function tcod::set_error(const std::exception&)

• Template Function tcod::stringf

Typedefs

• Typedef tcod::ConsolePtr

• Typedef tcod::ContextPtr

• Typedef tcod::ContextSharedPtr

• Typedef tcod::ImagePtr

• Typedef tcod::TilesetPtr

Variables

• Variable tcod::CHARMAP_CP437

• Variable tcod::CHARMAP_TCOD

Namespace tcod::console

Functions

• Function tcod::console::init_root(int, int, const std::string&, bool, TCOD_renderer_t, bool)

• Function tcod::console::init_root(int, int, const std::string&, bool, TCOD_renderer_t)

Namespace tcod::sdl2

Functions

• Function tcod::sdl2::process_event(const union SDL_Event&, TCOD_key_t&)

• Function tcod::sdl2::process_event(const union SDL_Event&, TCOD_mouse_t&)

Namespace tcod::tileset

Functions

• Function tcod::tileset::new_fallback_tileset

Classes and Structs

Struct BresenhamLine::Matrix

• Defined in File bresenham.hpp

Nested Relationships

This struct is a nested type of Class BresenhamLine.

Struct Documentation

struct Matrix

Transform matrix to convert from normalized state cursor to the real world coordinates.

Public Functions

inline Point2 transform(const Point2 &cursor) const noexcept

Convert a state cursor vector to the a world vector.

Public Members

int ax

int ay

int_fast8_t xx

int_fast8_t xy

int_fast8_t yx

int_fast8_t yy

Struct ColorRGB

• Defined in File color.hpp

Inheritance Relationships

Base Type

• public TCOD_ColorRGB (Struct TCOD_ColorRGB)

Struct Documentation

struct ColorRGB : public TCOD_ColorRGB

A C++ RGB color, used to handle conversions between color types.

New in version 1.19.

Public Functions

inline constexpr ColorRGB() noexcept

Default construct a black ColorRGB object.

RGB values are zero.

inline constexpr ColorRGB(uint8_t red, uint8_t green, uint8_t blue) noexcept

Construct a ColorRGB object with the provided color.

inline explicit constexpr ColorRGB(const TCOD_ColorRGB &rhs) noexcept

Construct a ColorRGB object from an TCOD_ColorRGB struct.

inline explicit constexpr ColorRGB(const TCOD_ColorRGBA &rhs) noexcept

Construct a ColorRGB object from an RGBA color, truncating the alpha.

inline constexpr operator const TCOD_ColorRGBA() const noexcept

Allow implicit casts to RGBA colors, where alpha=255 is implied.

inline explicit constexpr operator TCOD_ColorRGB*() noexcept

Allow explicit casts to a TCOD_ColorRGB pointer.

inline explicit constexpr operator const TCOD_ColorRGB*() const noexcept

Allow explicit casts to a const TCOD_ColorRGB pointer.

Struct ColorRGBA

• Defined in File color.hpp

Inheritance Relationships

Base Type

• public TCOD_ColorRGBA (Struct TCOD_ColorRGBA)

Struct Documentation

struct ColorRGBA : public TCOD_ColorRGBA

A C++ RGBA color, used to handle conversions between color types.

New in version 1.19.

Public Functions

inline constexpr ColorRGBA() noexcept

Default construct a black ColorRGBA object.

RGB values are zero, alpha is 255.

inline constexpr ColorRGBA(uint8_t red, uint8_t green, uint8_t blue, uint8_t alpha = 255) noexcept

Construct a ColorRGBA object with the provided color and alpha.

inline explicit constexpr ColorRGBA(const TCOD_ColorRGB &rhs, uint8_t alpha = 255) noexcept

Construct a ColorRGBA object by adding an alpha channel to an RGB object.

inline explicit constexpr ColorRGBA(const TCOD_ColorRGBA &rhs) noexcept

Construct a ColorRGBA object from an TCOD_ColorRGBA struct.

inline explicit constexpr operator TCOD_ColorRGB() const noexcept

Allow explicit conversions to a TCOD_ColorRGB struct.

inline explicit constexpr operator TCOD_ColorRGBA*() noexcept

Allow explicit conversions to a TCOD_ColorRGBA pointer.

inline explicit constexpr operator const TCOD_ColorRGBA*() const noexcept

Allow explicit conversions to a const TCOD_ColorRGBA pointer.

Struct ConsoleDeleter

• Defined in File console_types.hpp

Struct Documentation

struct ConsoleDeleter

Public Functions

inline void operator()(TCOD_Console *console) const

Struct ContextDeleter

• Defined in File context.h

Struct Documentation

struct ContextDeleter

Public Functions

inline void operator()(TCOD_Context *console) const

Struct ImageDeleter

• Defined in File image.hpp

Struct Documentation

struct ImageDeleter

Public Functions

inline void operator()(TCOD_Image *image) const

Struct TilesetDeleter

• Defined in File tileset.hpp

Struct Documentation

struct TilesetDeleter

Public Functions

inline void operator()(TCOD_Tileset *tileset) const

Struct TCOD_ArrayData

• Defined in File pathfinder.h

Struct Documentation

struct TCOD_ArrayData

Public Members

int8_t ndim

int int_type

size_t shape[TCOD_PATHFINDER_MAX_DIMENSIONS + 1]

size_t strides[TCOD_PATHFINDER_MAX_DIMENSIONS + 1]

unsigned char *data

Struct TCOD_BasicGraph2D

• Defined in File pathfinder.h

Struct Documentation

struct TCOD_BasicGraph2D

Public Members

struct TCOD_ArrayData cost

int cardinal

int diagonal

Struct TCOD_bresenham_data_t

• Defined in File bresenham.h

Struct Documentation

struct TCOD_bresenham_data_t

A struct used for computing a bresenham line.

Public Members

int stepx

int stepy

int e

int deltax

int deltay

int origx

int origy

int destx

int desty

Struct TCOD_bsp_t

• Defined in File bsp.h

Struct Documentation

struct TCOD_bsp_t

Public Members

TCOD_tree_t tree

int x

int y

int w

int h

int position

uint8_t level

bool horizontal

Struct TCOD_ColorRGB

• Defined in File color.h

Inheritance Relationships

Derived Type

• public tcod::ColorRGB (Struct ColorRGB)

Struct Documentation

struct TCOD_ColorRGB

A 3-channel RGB color struct.

Subclassed by tcod::ColorRGB

Public Functions

inline constexpr bool operator==(const TCOD_ColorRGB &rhs) const noexcept

inline constexpr bool operator!=(const TCOD_ColorRGB &rhs) const noexcept

template<class Archive>
inline void serialize(Archive &archive)

Public Members

uint8_t r

uint8_t g

uint8_t b

Friends

inline friend std::ostream &operator<<(std::ostream &out, const TCOD_ColorRGB &rgb)

inline friend std::istream &operator>>(std::istream &in, TCOD_ColorRGB &rgb)

Struct TCOD_ColorRGBA

• Defined in File color.h

Inheritance Relationships

Derived Type

• public tcod::ColorRGBA (Struct ColorRGBA)

Struct Documentation

struct TCOD_ColorRGBA

A 4-channel RGBA color struct.

Subclassed by tcod::ColorRGBA

Public Functions

inline constexpr bool operator==(const TCOD_ColorRGBA &rhs) const noexcept

inline constexpr bool operator!=(const TCOD_ColorRGBA &rhs) const noexcept

inline constexpr TCOD_ColorRGBA &operator=(const TCOD_ColorRGB &rhs)

template<class Archive>
inline void serialize(Archive &archive)

Public Members

uint8_t r

uint8_t g

uint8_t b

uint8_t a

Friends

inline friend std::ostream &operator<<(std::ostream &out, const TCOD_ColorRGBA &rgba)

inline friend std::istream &operator>>(std::istream &in, TCOD_ColorRGBA &rgba)

Struct TCOD_Console

• Defined in File console.h

Struct Documentation

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.

Struct TCOD_ConsoleTile

• Defined in File console.h

Struct Documentation

struct TCOD_ConsoleTile

The raw data for a single TCOD_Console tile.

New in version 1.19.

Public Functions

inline bool operator==(const TCOD_ConsoleTile &rhs) const noexcept

inline bool operator!=(const TCOD_ConsoleTile &rhs) const noexcept

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.

Struct TCOD_Context

• Defined in File context.h

Struct Documentation

struct TCOD_Context

A rendering context for libtcod.

New in version 1.16.

Public Functions

inline auto get_renderer_type() noexcept -> int

Return the TCOD_renderer_t value of this context which may be different than the one requested.

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

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

Parameters:

• console – The TCOD_Console to render. This console can be any size.

• viewport – The viewport options, which can change the way the console is scaled.

  Deprecated since version 1.21: Replace tcod::new_console(params) with tcod::Context(params) to get a C++ context.

inline void present(const TCOD_Console &console)

Present a console to the display.

Parameters:

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

Deprecated since version 1.21: Replace tcod::new_console(params) with tcod::Context(params) to get a C++ context.

inline auto get_sdl_window() noexcept -> struct SDL_Window*

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

Returns:

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

Deprecated since version 1.21: Replace tcod::new_console(params) with tcod::Context(params) to get a C++ context.

inline auto get_sdl_renderer() noexcept -> struct SDL_Renderer*

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

Returns:

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

Deprecated since version 1.21: Replace tcod::new_console(params) with tcod::Context(params) to get a C++ context.

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

Convert pixel coordinates to this contexts integer tile coordinates.

Deprecated since version 1.21: Replace tcod::new_console(params) with tcod::Context(params) to get a C++ context.

inline auto pixel_to_tile_coordinates(const std::array<double, 2> &xy) -> std::array<double, 2>

Convert pixel coordinates to this contexts sub-tile coordinates.

Deprecated since version 1.21: Replace tcod::new_console(params) with tcod::Context(params) to get a C++ context.

inline void convert_event_coordinates(SDL_Event &event)

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

New in version 1.19.

Deprecated since version 1.21: Replace tcod::new_console(params) with tcod::Context(params) to get a C++ context.

Parameters:

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

inline void save_screenshot(const char *filepath)

Save a screenshot to filepath.

Parameters:

filepath – The file path to save the screenshot at. If nullptr then a unique file name will be generated.

Deprecated since version 1.21: Replace tcod::new_console(params) with tcod::Context(params) to get a C++ context.

inline void save_screenshot(const std::string &filepath)

Save a screenshot to filepath.

Parameters:

filepath – The file path to save the screenshot at.

Deprecated since version 1.21: Replace tcod::new_console(params) with tcod::Context(params) to get a C++ context.

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

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

Parameters:

• min_columns – The minimum width to use for the new console, in tiles.

• min_rows – The minimum height to use for the new console, in tiles.

• magnification – Determines the apparent size of the tiles that will be rendered by a console created with the output values. A magnification larger then 1.0f will output smaller console parameters, which will show as larger tiles when presented. Only values larger than zero are allowed.

Returns:

Returns a tcod::Console of a dynamic size.

Deprecated since version 1.21: Replace tcod::new_console(params) with tcod::Context(params) to get a C++ context.

Public Members

int type

The TCOD_renderer_t value of this context.

Struct TCOD_ContextParams

• Defined in File context.h

Struct Documentation

struct TCOD_ContextParams

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

New in version 1.19.

Public Members

int tcod_version

Must be TCOD_COMPILEDVERSION.

int window_x

window_x and window_y are the starting position of the window.

These are SDL parameters so values like SDL_WINDOWPOS_UNDEFINED and SDL_WINDOWPOS_CENTERED are acceptable.

Values of zero will be converted to SDL_WINDOWPOS_UNDEFINED unless window_xy_defined is true.

int window_y

int pixel_width

pixel_width and pixel_height are the desired size of the window in pixels.

If these are zero then they’ll be derived from columns, rows, and the tileset.

int pixel_height

int columns

columns and rows are the desired size of the terminal window.

Usually you’ll set either these or the pixel resolution.

If you are setting these values from a TCOD_Console then you should set the console attribute instead.

int rows

int renderer_type

renderer_type is one of the TCOD_renderer_t values.

TCOD_Tileset *tileset

tileset is an optional pointer to a tileset object.

If this is NULL then a platform specific fallback tileset will be used. This fallback is known to be unreliable, but it should work well enough for prototyping code.

int vsync

If vsync is true, then vertical sync will be enabled whenever possible.

A value of true is recommended.

int sdl_window_flags

sdl_window_flags is a bitfield of SDL_WindowFlags flags.

For a window, a value of SDL_WINDOW_RESIZABLE is recommended. For fullscreen, a value of SDL_WINDOW_RESIZABLE | SDL_WINDOW_FULLSCREEN_DESKTOP is recommended. You should avoid the SDL_WINDOW_FULLSCREEN flag whenever possible.

const char *window_title

window_title will be the title of the opened window.

If not set then argv[0] will be used if available.

int argc

The number of items in argv.

const char *const *argv

argc and argv are optional CLI parameters.

You can pass 0 and NULL respectfully to ignore them. If unsure then you should pass the argc and argv arguments from your main function.

void (*cli_output)(void *userdata, const char *output)

If user attention is required for the given CLI parameters then cli_output will be called with cli_userdata and an error or help message.

If cli_output is NULL then it will print the message to stdout and terminate the program. If cli_output returns normally then TCOD_E_REQUIRES_ATTENTION will be returned from TCOD_context_new.

void *cli_userdata

This is passed to the userdata parameter of cli_output if called.

bool window_xy_defined

If this is false then window_x/window_y parameters of zero are assumed to be undefined and will be changed to SDL_WINDOWPOS_UNDEFINED.

TCOD_Console *console

A console to be used as a reference for the desired window size.

This can set as an alternative to the columns and rows attributes.

New in version 1.19.

Struct TCOD_dice_t

• Defined in File mersenne_types.h

Struct Documentation

struct TCOD_dice_t

Public Members

int nb_rolls

int nb_faces

float multiplier

float addsub

Struct TCOD_Dijkstra

• Defined in File path.h

Struct Documentation

struct TCOD_Dijkstra

Dijkstra data structure.

All attributes are considered private.

Public Members

int diagonal_cost

int width

int height

int nodes_max

TCOD_map_t map

TCOD_path_func_t func

void *user_data

unsigned int *distances

unsigned int *nodes

TCOD_list_t path

Struct TCOD_Frontier

• Defined in File pathfinder_frontier.h

Struct Documentation

struct TCOD_Frontier

Public Members

int8_t ndim

int active_dist

int active_index[TCOD_PATHFINDER_MAX_DIMENSIONS]

struct TCOD_Heap heap

Struct TCOD_Heap

• Defined in File heapq.h

Struct Documentation

struct TCOD_Heap

Public Members

unsigned char *heap

int size

int capacity

size_t node_size

size_t data_size

size_t data_offset

int priority_type

Struct TCOD_heightmap_t

• Defined in File heightmap.h

Struct Documentation

struct TCOD_heightmap_t

Public Members

int w

int h

float *values

Struct TCOD_Image

• Defined in File image.h

Struct Documentation

struct TCOD_Image

Public Members

int nb_mipmaps

struct TCOD_mipmap_ *mipmaps

TCOD_ColorRGB key_color

bool has_key_color

Struct TCOD_key_t

• Defined in File console_types.h

Struct Documentation

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.

Public Members

TCOD_keycode_t vk

The TCOD_keycode_t enum of the current key.

char c

The printable character of a keycode if vk == TCODK_CHAR, else 0.

Libtcod 1.6 switched form SDL1 to SDL2 which changed the values returned by this attribute.

Before 1.6 this value could be affected by modifiers such as the shift key.

After 1.6 the SDL key symbol is always returned, which will be the same no matter which modifiers are held.

Deprecated:

The nature of this attribute makes it unsuitable for both printable keys and standard key inputs. Use SDL events instead to differentiate between keycodes, symbols, printable characters.

char text[TCOD_KEY_TEXT_SIZE]

The UTF-8 text of a key when vk == TCODK_TEXT.

Otherwise this will always be \0’`.

TCODK_TEXT is always derived from an SDL_TEXTINPUT event.

bool pressed

True if is this key was pressed.

False if it was released.

bool lalt

True if left alt was held during this event.

bool lctrl

True if left control was held during this event.

bool lmeta

True if the left meta key was held during this event.

bool ralt

True if right alt was held during this event.

bool rctrl

True if right control was held during this event.

bool rmeta

True if the right meta key was held during this event.

bool shift

True if shift was held during this event.

Struct TCOD_LogMessage

• Defined in File logging.h

Struct Documentation

struct TCOD_LogMessage

Information being logged, this is a temporary object which doesn’t last longer than the logging callbacks.

This struct will not contain NULL character pointers.

New in version 1.19.

Public Members

const char *message

int level

const char *source

int lineno

Struct TCOD_Map

• Defined in File fov_types.h

Struct Documentation

struct TCOD_Map

Private map struct.

Public Members

int width

int height

int nbcells

struct TCOD_MapCell *cells

Struct TCOD_MapCell

• Defined in File fov_types.h

Struct Documentation

struct TCOD_MapCell

Private map cell struct.

Public Members

bool transparent

bool walkable

bool fov

Struct TCOD_mouse_t

• Defined in File mouse_types.h

Struct Documentation

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.

Public Members

int x

The mouse absolute pixel position, according to SDL.

int y

int dx

The mouse relative pixel motion, according to SDL.

int dy

int cx

The mouse cell coordinates for the root console or the last presented console.

int cy

int dcx

The mouse cell movement for the root console or the last presented console.

int dcy

bool lbutton

True when the Left mouse button is held.

bool rbutton

True when the right mouse button is held.

bool mbutton

True when the middle mouse button is held.

bool lbutton_pressed

True when the left mouse button has just been released.

bool rbutton_pressed

True when the right mouse button has just been released.

bool mbutton_pressed

True when the middle mouse button has just been released.

bool wheel_up

True when the mouse wheel was rolled up.

Multiple scroll events per frame are lost.

bool wheel_down

True when the mouse wheel was rolled down.

Multiple scroll events per frame are lost.

Struct TCOD_MouseTransform

• Defined in File mouse_types.h

Struct Documentation

struct TCOD_MouseTransform

Info needed to convert between mouse pixel and tile coordinates.

Internal use only.

double pixel_x, pixel_y, tile_x, tile_y;
TCOD_MouseTransform transform;
// Convert pixel coordinates to tile coordinates.
tile_x = (pixel_x - transform.offset_x) * transform.scale_x;
tile_y = (pixel_y - transform.offset_y) * transform.scale_y;
// Convert tile coordinates to pixel coordinates.
pixel_x = tile_x / transform.scale_x + transform.offset_x;
pixel_y = tile_y / transform.scale_y + transform.offset_y;

New in version 1.24.

Public Members

double offset_x

double offset_y

double scale_x

double scale_y

Struct TCOD_Noise

• Defined in File noise.h

Struct Documentation

struct TCOD_Noise

Public Members

int ndim

unsigned char map[256]

Randomized map of indexes into buffer.

float buffer[256][TCOD_NOISE_MAX_DIMENSIONS]

Random 256 x ndim buffer.

float H

float lacunarity

float exponent[TCOD_NOISE_MAX_OCTAVES]

float *waveletTileData

TCOD_Random *rand

TCOD_noise_type_t noise_type

Struct TCOD_Parser

• Defined in File parser.h

Struct Documentation

struct TCOD_Parser

Parser, member variables are for internal use.

Public Members

TCOD_list_t structs

TCOD_parser_custom_t customs[16]

bool fatal

TCOD_list_t props

Struct TCOD_parser_listener_t

• Defined in File parser.h

Struct Documentation

struct TCOD_parser_listener_t

Public Members

bool (*new_struct)(TCOD_ParserStruct *str, const char *name)

bool (*new_flag)(const char *name)

bool (*new_property)(const char *propname, TCOD_value_type_t type, TCOD_value_t value)

bool (*end_struct)(TCOD_ParserStruct *str, const char *name)

void (*error)(const char *msg)

Struct TCOD_ParserStruct

• Defined in File parser.h

Struct Documentation

struct TCOD_ParserStruct

Parser struct, member variables are for internal use.

Public Members

char *name

TCOD_list_t flags

TCOD_list_t props

TCOD_list_t lists

TCOD_list_t structs

Struct TCOD_Pathfinder

• Defined in File pathfinder.h

Struct Documentation

struct TCOD_Pathfinder

Public Members

int8_t ndim

size_t shape[TCOD_PATHFINDER_MAX_DIMENSIONS]

bool owns_distance

bool owns_graph

bool owns_traversal

struct TCOD_ArrayData distance

struct TCOD_BasicGraph2D graph

struct TCOD_ArrayData traversal

struct TCOD_Heap heap

Struct TCOD_PrintParamsRGB

• Defined in File console_printing.h

Struct Documentation

struct TCOD_PrintParamsRGB

Information about a string to be printed.

Public Members

int x

int y

int width

int height

const TCOD_ColorRGB *fg

const TCOD_ColorRGB *bg

TCOD_bkgnd_flag_t flag

TCOD_alignment_t alignment

Struct TCOD_Random_MT_CMWC

• Defined in File mersenne_types.h

Struct Documentation

struct TCOD_Random_MT_CMWC

Public Members

TCOD_random_algo_t algorithm

TCOD_distribution_t distribution

uint32_t mt[624]

int cur_mt

uint32_t Q[4096]

uint32_t c

int cur

Struct TCOD_RendererSDL2

• Defined in File renderer_sdl2.h

Struct Documentation

struct TCOD_RendererSDL2

The renderer data for an SDL2 rendering context.

Internal use only.

Public Members

struct SDL_Window *window

struct SDL_Renderer *renderer

struct TCOD_TilesetAtlasSDL2 *atlas

struct TCOD_Console *cache_console

struct SDL_Texture *cache_texture

uint32_t sdl_subsystems

TCOD_MouseTransform cursor_transform

Struct TCOD_Tileset

• Defined in File tileset.h

Struct Documentation

struct TCOD_Tileset

A container for libtcod tileset graphics.

New in version 1.19.

Public Members

int tile_width

int tile_height

int tile_length

int tiles_capacity

int tiles_count

struct TCOD_ColorRGBA *pixels

int character_map_length

int *character_map

struct TCOD_TilesetObserver *observer_list

int virtual_columns

int ref_count

Struct TCOD_TilesetAtlasSDL2

• Defined in File renderer_sdl2.h

Struct Documentation

struct TCOD_TilesetAtlasSDL2

An SDL2 tileset atlas.

This prepares a tileset for use with SDL2.

New in version 1.16.

Public Members

struct SDL_Renderer *renderer

The renderer used to create this atlas.

Non-owning.

struct SDL_Texture *texture

The atlas texture.

struct TCOD_Tileset *tileset

The tileset used to create this atlas.

Internal use only.

struct TCOD_TilesetObserver *observer

Internal use only.

int texture_columns

Internal use only.

Struct TCOD_TilesetObserver

• Defined in File tileset.h

Struct Documentation

struct TCOD_TilesetObserver

Public Members

struct TCOD_Tileset *tileset

struct TCOD_TilesetObserver *next

void *userdata

void (*on_observer_delete)(struct TCOD_TilesetObserver *observer)

int (*on_tile_changed)(struct TCOD_TilesetObserver *observer, int tile_id)

Struct TCOD_tree_t

• Defined in File tree.h

Struct Documentation

struct TCOD_tree_t

Public Members

struct TCOD_tree_t *next

struct TCOD_tree_t *father

struct TCOD_tree_t *sons

Struct TCOD_ViewportOptions

• Defined in File context_viewport.h

Struct Documentation

struct TCOD_ViewportOptions

Viewport options for the rendering context.

New in version 1.16.

Public Members

int tcod_version

Must be set to TCOD_COMPILEDVERSION.

bool keep_aspect

If true then the aspect ratio will be kept square when the console is scaled.

The view will be letter-boxed.

If false the console will be stretched to fill the screen.

Set this is true if your tileset is deigned for square pixels.

bool integer_scaling

If true then console scaling will be fixed to integer increments.

Has no effect if the console must be scaled down.

TCOD_ColorRGBA clear_color

The color to clear the screen with before rendering the console.

float align_x

Alignment of the console when it is letter-boxed: 0.0f renders the console in the upper-left corner, and 1.0f in the lower-right.

Values of 0.5f will center the console. Values outside of the range 0.0f to 1.0f are clamped.

float align_y

Struct TCODDijkstra::WrapperData

• Defined in File path.hpp

Nested Relationships

This struct is a nested type of Class TCODDijkstra.

Struct Documentation

struct WrapperData

Public Members

void *userData

const ITCODPathCallback *listener

Struct TCODPath::WrapperData

• Defined in File path.hpp

Nested Relationships

This struct is a nested type of Class TCODPath.

Struct Documentation

struct WrapperData

Public Members

void *userData

const ITCODPathCallback *listener

Class ITCODBspCallback

• Defined in File bsp.hpp

Class Documentation

class ITCODBspCallback

Public Functions

inline virtual ~ITCODBspCallback()

virtual bool visitNode(TCODBsp *node, void *userData) = 0

Class ITCODParserListener

• Defined in File parser.hpp

Class Documentation

class ITCODParserListener

For basic config files, you don’t have to write a listener.

Instead, use the default listener. The parser uses a SAX-like approach during the parsing of the file. This means that the whole file is not stored in memory in a tree structure. Instead, it works like a stream parser and raises events. Each event has an associated callback that is provided by a listener :

class ITCODParserListener { public : virtual bool parserNewStruct(TCODParser *parser,const TCODParserStruct *str,const char *name)=0; virtual bool parserFlag(TCODParser *parser,const char *name)=0; virtual bool parserProperty(TCODParser *parser,const char *name, TCOD_value_type_t type, TCOD_value_t value)=0; virtual bool parserEndStruct(TCODParser *parser,const TCODParserStruct *str, const char *name)=0; virtual void error(const char *msg) = 0; };

typedef struct { bool (*new_struct)(TCOD_parser_struct_t str,const char *name); bool (*new_flag)(const char *name); bool (*new_property)(const char *name, TCOD_value_type_t type, TCOD_value_t value); bool (*end_struct)(TCOD_parser_struct_t str, const char *name); void (*error)(const char *msg); } TCOD_parser_listener_t;

class ParserListener : def new_struct(str,name) : … def new_flag(name) : … def new_property(name,type,value) : … def end_struct(self, struct, name) : … def error(msg) : …

Before running the parser, you have to build a listener :

class MyListener : public ITCODParserListener { bool parserNewStruct(TCODParser *parser,const TCODParserStruct *str,const char *name) { printf (“new structure type ‘%s’ with name ‘%s’\n”,str->getname(),name ? name : “NULL”); return true; } bool parserFlag(TCODParser *parser,const char *name) { printf (“found new flag ‘%s’\n”,name); return true; } bool parserProperty(TCODParser *parser,const char *name, TCOD_value_type_t type, TCOD_value_t value) { printf (“found new property ‘%s’\n”,name); return true; } bool parserEndStruct(TCODParser *parser,const TCODParserStruct *str,const char *name) { printf (“end of structure type ‘%s’\n”,name); return true; } void error(char *msg) { fprintf(stderr,msg); exit(1); } };

bool my_parser_new_struct(TCOD_parser_struct_t str, const char *name) { printf (“new structure type ‘%s’ with name ‘%s’\n”,TCOD_struct_get_name(str),name ? name : “NULL”); return true; } bool my_parser_flag(const char *name) { printf (“found new flag ‘%s’\n”,name); return true; } bool my_parser_property(const char *name, TCOD_value_type_t type, TCOD_value_t value) { printf (“found new property ‘%s’\n”,name); return true; } bool my_parser_end_struct(TCOD_parser_struct_t str, const char *name) { printf (“end of structure type ‘%s’\n”,name); return true; } void my_parser_error(const char *msg) { fprintf(stderr,msg); exit(1); } TCOD_parser_listener_t my_listener = { my_parser_new_struct, my_parser_flag, my_parser_property, my_parser_end_struct, my_parser_error };

class MyListener: def new_struct(self, struct, name): print ‘new structure type’, libtcod.struct_get_name(struct), ‘ named ‘, name return True def new_flag(self, name): print ‘new flag named ‘, name return True def new_property(self,name, typ, value): type_names = [‘NONE’, ‘BOOL’, ‘CHAR’, ‘INT’, ‘FLOAT’, ‘STRING’, ‘COLOR’, ‘DICE’] if typ == libtcod.TYPE_COLOR : print ‘new property named ‘, name,’ type ‘,type_names[typ], ‘ value ‘, value.r, value.g, value.b elif typ == libtcod.TYPE_DICE : print ‘new property named ‘, name,’ type ‘,type_names[typ], ‘ value ‘, value.nb_rolls, value.nb_faces, value.multiplier, value.addsub else: print ‘new property named ‘, name,’ type ‘,type_names[typ], ‘ value ‘, value return True def end_struct(self, struct, name): print ‘end structure type’, libtcod.struct_get_name(struct), ‘ named ‘, name return True def error(self,msg): print ‘error : ‘, msg return True

Public Functions

inline virtual ~ITCODParserListener()

virtual bool parserNewStruct(TCODParser *parser, const TCODParserStruct *str, const char *name) = 0

This callback is called each time the parser find a new structure declaration in the file.

Example : It must return true if everything is right, false if there is an error and the parser must exit.

Parameters:

• parser – In the C++ version, the parser object, returned by TCODParser constructor. It’s used for error handling.

• str – The structure type. Can be used to retrieve the type’s name with getName. In the example above, this would be “item_type”.

• name – The name of the structure or NULL if no name is present in the file. In the example above, this would be “blade”.

virtual bool parserFlag(TCODParser *parser, const char *name) = 0

This callback is called each time the parser find a new flag in the file.

Example : It must return true if everything is right, false if there is an error and the parser must exit.

Parameters:

• parser – In the C++ version, the parser object, returned by TCODParser constructor. It’s used for error handling.

• name – The name of the flag. In the example, this would be “abstract”.

virtual bool parserProperty(TCODParser *parser, const char *propname, TCOD_value_type_t type, TCOD_value_t value) = 0

This callback is called each time the parser find a new property in the file.

Example : It must return true if everything is right, false if there is an error and the parser must exit.

Parameters:

• parser – In the C++ version, the parser object, returned by TCODParser constructor. It’s used for error handling.

• name – The name of the property. In the example, this would be “cost”.

• type – The type of the property as defined when you called addProperty or addValueList. In the example, this would be TCOD_TYPE_INT.

• value – The value of the property, stored in a generic value structure. In the example, we would have value.i == 300. In the case of a value-list property, the type would reflect the list id (between TCOD_TYPE_VALUELIST00 and TCOD_TYPE_VALUELIST15) and value.s would contain the actual string.

virtual bool parserEndStruct(TCODParser *parser, const TCODParserStruct *str, const char *name) = 0

This callback is called each time the parser find the end of a structure declaration in the file.

Example : It must return true if everything is right, false if there is an error and the parser must exit.

Parameters:

• parser – In the C++ version, the parser object, returned by TCODParser constructor. It’s used for error handling.

• str – The structure type. Can be used to retrieve the type’s name with getName. In the example above, this would be “item_type”.

• name – The name of the structure or NULL if no name is present in the file. In the example above, this would be “blade”.

virtual void error(const char *msg) = 0

There are two kind of errors : Errors that are detected by the parser itself (malformed file, bad value syntax for a property, missing mandatory property in a structure, …).

Errors that you detect in your callbacks. When the parser finds an error in the file, it will call the error callback and stop :

If you find an error in your callback, you have to call the parser error function. It will add the file name and line number to your error message, and then call your error callback : The code in the example below will result in your error callback called with the following string : “error in &lt;filename&gt; line &lt;line_number&gt; : Bad cost value %d. Cost must be between 0 and 1000”

Parameters:

• msg – The error message from the parser with the file name and the line number.

• msg – printf-like format string for your error message.

Class ITCODPathCallback

• Defined in File path.hpp

Class Documentation

class ITCODPathCallback

Public Functions

inline virtual ~ITCODPathCallback()

virtual float getWalkCost(int xFrom, int yFrom, int xTo, int yTo, void *userData) const = 0

Class ITCODSDLRenderer

• Defined in File sys.hpp

Class Documentation

class ITCODSDLRenderer

This toolkit contains some system specific miscellaneous utilities. Use them is you want your code to be easily portable.

Public Functions

inline virtual ~ITCODSDLRenderer()

virtual void render(void *sdlSurface) = 0

Class BresenhamLine

• Defined in File bresenham.hpp

Nested Relationships

Nested Types

• Struct BresenhamLine::Matrix

Class Documentation

class BresenhamLine

Encapsulates a Bresenham line drawing algorithm.

New in version 1.17.

Public Types

using Point2 = std::array<int, 2>

using iterator_category = std::random_access_iterator_tag

using value_type = Point2

using difference_type = int

using pointer = void

using reference = value_type

Public Functions

inline explicit BresenhamLine(Point2 begin, Point2 end) noexcept

Construct a new Bresenham line from begin to end.

Iterating over this instance will include both endpoints.

inline explicit BresenhamLine(Point2 begin, Point2 end, int error) noexcept

Construct a new Bresenham line with a manually given error value.

inline BresenhamLine &operator++() noexcept

inline BresenhamLine operator++(int) noexcept

inline BresenhamLine &operator--() noexcept

inline BresenhamLine operator--(int) noexcept

inline value_type operator[](int index) noexcept

Return the world position of the Bresenham at the index relative to the current index.

BresenhamLine is not restricted by any bounds so you can freely give a index past the end or before zero.

The internal state must always seek to the position being indexed, this will affect performance depending on if successive indexes are close together or far apart.

inline value_type operator*() noexcept

Return the world position of the Bresenham at the current index.

inline constexpr bool operator==(const BresenhamLine &rhs) const noexcept

inline constexpr bool operator!=(const BresenhamLine &rhs) const noexcept

inline constexpr difference_type operator-(const BresenhamLine &rhs) const noexcept

inline BresenhamLine adjust_range(int shift_begin, int shift_end) const noexcept

  Return a new version of this BresenhamLine with an adjusted range.

  `shift_begin` and `shift_end` change the beginning and ending of the line
  when iterators over.

  Example::

Remove the endpoints of a bresenham line. auto line = tcod::BresenhamLine(from, to).adjust_range(1, -1);

inline BresenhamLine without_start() const noexcept

  Remove the staring endpoint of a line.

  Example::

    for (auto&& [x, y] : tcod::BresenhamLine(from, to).without_start()) {

All positions excluding from. }

inline BresenhamLine without_end() const noexcept

  Remove the final endpoint of a line.

  Example::

    for (auto&& [x, y] : tcod::BresenhamLine(from, to).without_end()) {

All positions excluding to. }

inline BresenhamLine without_endpoints() const noexcept

  Remove both endpoints of a line.

  Example::

    for (auto&& [x, y] : tcod::BresenhamLine(from, to).without_endpoints()) {

All positions between and excluding from and to. }

inline BresenhamLine begin() const noexcept

Return the beginning iterator, which is a copy of the current object.

inline BresenhamLine end() const noexcept

Return the past-the-end iterator.

Class Console

• Defined in File console_types.hpp

Class Documentation

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.

Template Class Matrix

• Defined in File matrix.hpp

Class Documentation

template<typename T, size_t Dimensions, typename Container = std::vector<T>>
class Matrix

A template container for holding a multi-dimensional array of items.

This class is a work-in-progress.

Template Parameters:

• T – The type of value contained by this matrix.

• Dimensions – The number of dimensions of this matrix type.

• Container – The std::vector-like container used for this matrix.

Public Types

using size_type = int

using shape_type = std::array<size_type, Dimensions>

using index_type = std::array<size_type, Dimensions>

using reference = typename Container::reference

using const_reference = typename Container::const_reference

Public Functions

constexpr Matrix() = default

Default constructor.

inline explicit constexpr Matrix(const shape_type &shape)

Create a matrix of the given shape.

inline constexpr Matrix(const shape_type &shape, const T &fill_value)

Create a matrix of the given shape filled with a default value.

inline constexpr auto begin() noexcept

Return the iterator beginning.

inline constexpr auto begin() const noexcept

Return the iterator beginning.

inline constexpr auto end() noexcept

Return the iterator end.

inline constexpr auto end() const noexcept

Return the iterator end.

inline constexpr reference operator[](const index_type &index) noexcept

Get the item at index.

inline constexpr const_reference operator[](const index_type &index) const noexcept

Get the const item at index.

inline constexpr reference at(const index_type &index)

Get the item at index, checking bounds.

inline constexpr const_reference at(const index_type &index) const

Get the const item at index, checking bounds.

inline constexpr const shape_type &get_shape() const noexcept

Return the shape of this matrix.

inline constexpr bool in_bounds(const index_type &index) const noexcept

Return true if index is within the bounds of this matrix.

inline constexpr operator MatrixView<T, Dimensions>() noexcept

Implicit cast to a view of this matrix.

inline constexpr operator MatrixView<const T, Dimensions>() const noexcept

Implicit cast to a const view of this matrix.

inline constexpr Container &get_container() noexcept

Get the flat container for this matrix.

inline constexpr const Container &get_container() const noexcept

Get the const flat container for this matrix.

template<class Archive>
inline void serialize(Archive &archive)

Template Class MatrixView

• Defined in File matrix.hpp

Class Documentation

template<typename T, size_t Dimensions>
class MatrixView

A view into a strided multi-dimensional array.

This class is a work-in-progress.

Template Parameters:

• T – The type viewed by this object.

• Dimensions – The number of dimensions of the view.

Public Types

using size_type = int

using shape_type = std::array<size_type, Dimensions>

using stride_type = std::array<size_type, Dimensions>

using index_type = std::array<size_type, Dimensions>

using reference = T&

using const_reference = const T&

Public Functions

constexpr MatrixView() = default

Default constructor.

inline constexpr MatrixView(const shape_type &shape_xy, const stride_type &strides_xy, T *data) noexcept

Create a new multi-dimensional view.

inline constexpr reference operator[](const index_type &index) noexcept

Get the item at index.

inline constexpr const_reference operator[](const index_type &index) const noexcept

Get the const item at index.

inline constexpr reference at(const index_type &index)

Get the item at index, checking bounds.

inline constexpr const_reference at(const index_type &index) const

Get the const item at index, checking bounds.

inline constexpr bool in_bounds(const index_type &index) const noexcept

Return true if index is within the bounds of this matrix.

Class Tileset

• Defined in File tileset.hpp

Class Documentation

class Tileset

A C++ Tileset container.

New in version 1.19.

Public Functions

Tileset() = default

Construct a new Tileset object.

inline explicit Tileset(int tile_width, int tile_height)

Construct a new Tileset object with tiles of the given size.

The tileset will be empty.

Parameters:

• tile_width – The width of the tiles of this object in pixels.

• tile_height – The width of the tiles of this object in pixels.

inline explicit Tileset(const std::array<int, 2> &tile_shape)

Construct a new Tileset object with tiles of the given size.

The tileset will be empty.

Parameters:

tile_shape – The {width, height} of the tiles in pixels.

inline explicit Tileset(TilesetPtr ptr)

Pass ownership of a TilesetPtr to a new Tileset.

Parameters:

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

inline explicit Tileset(TCOD_Tileset *ptr)

Takes ownership of a raw TCOD_Tileset pointer.

Parameters:

ptr – A pointer which will now be managed by this object.

inline auto get_tile_width() const noexcept -> int

Get the width of tiles in this Tileset.

Returns:

int The total width of tiles in pixels.

inline auto get_tile_height() const noexcept -> int

Get the height of tiles in this Tileset.

Returns:

int The total height of tiles in pixels.

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

Get the {width, height} shape of tiles in this Tileset.

Returns:

std::array<int, 2> The {width, height} of tiles in this Tileset in pixels.

inline auto get() noexcept -> TCOD_Tileset*

Return a non-owning pointer to this objects TCOD_Tileset.

Returns:

TCOD_Tileset

inline auto get() const noexcept -> TCOD_Tileset*

Return a non-owning pointer to this objects TCOD_Tileset.

Returns:

TCOD_Tileset

inline auto release() noexcept -> TCOD_Tileset*

Release ownership of this Tileset’s TCOD_Tileset* and return the pointer.

Using this Tileset afterwards is undefined.

inline operator TCOD_Tileset&()

Allow implicit conversions to a TCOD_Console reference.

inline operator const TCOD_Tileset&() const

Allow implicit conversions to a const TCOD_Console reference.

Class Timer

• Defined in File timer.hpp

Class Documentation

class Timer

A timing class based on SDL’s high performance time counter.

Used to track delta time or set a framerate.

This class is based on using SDL_GetPerformanceCounter to track the time. The time taken between calls to sync() is tracked. This is used to determine the real framerate if requested.

You must add #include <libtcod/timer.hpp> to include ths class.

int desired_fps = 30;
auto timer = tcod::Timer();
while (1) {
  float delta_time = timer.sync(desired_fps);  // desired_fps is optional.
  // ...

New in version 1.19.

Public Functions

inline Timer()

Construct a new Timer object.

inline float sync(int desired_fps = 0)

Sync the time to a given framerate (if provided) and return the delta time compared to the previous call.

If desired_fps is non-zero then this function will block until the desired framerate is reached.

Timing starts once the Timer is constructed.

Parameters:

desired_fps – The desired framerate in frames-per-second, or zero to disable framerate limiting.

Returns:

The delta time in seconds since the last call to sync is returned as a float.

inline float get_mean_fps() const noexcept

Return the mean framerate.

This is the average of all samples combined.

inline float get_last_fps() const noexcept

Return the framerate of the last call to sync().

inline float get_min_fps() const noexcept

Return the lowest framerate recently sampled.

inline float get_max_fps() const noexcept

Return the highest framerate recently sampled.

inline float get_median_fps() const noexcept

Return the median framerate.

This is the framerate of the middle sample when all samples are sorted.

Class TCODColor

• Defined in File color.hpp

Class Documentation

class TCODColor

The Doryen library uses 32bits colors. Thus, your OS desktop must use 32bits colors. A color is defined by its red, green and blue component between 0 and 255. You can use the following predefined colors (hover over a color to see its full name and R,G,B values):

TCODColor::desaturatedRed TCODColor::lightestRed TCODColor::lighterRed TCODColor::lightRed TCODColor::red TCODColor::darkRed TCODColor::darkerRed TCODColor::darkestRed

TCOD_desaturated_red TCOD_lightest_red TCOD_lighter_red TCOD_light_red TCOD_red TCOD_dark_red TCOD_darker_red TCOD_darkest_red

libtcod.desaturated_red libtcod.lightest_red libtcod.lighter_red libtcod.light_red libtcod.red libtcod.dark_red libtcod.darker_red libtcod.darkest_red

TCODColor::desaturatedRed TCODColor::lightestRed TCODColor::lighterRed TCODColor::lightRed TCODColor::red TCODColor::darkRed TCODColor::darkerRed TCODColor::darkestRed

tcod.color.desaturatedRed tcod.color.lightestRed tcod.color.lighterRed tcod.color.lightRed tcod.color.red tcod.color.darkRed tcod.color.darkerRed tcod.color.darkestRed

Public Functions

constexpr TCODColor() noexcept = default

inline constexpr TCODColor(uint8_t r_, uint8_t g_, uint8_t b_) noexcept

You can create your own colours using a set of constructors, both for RGB and HSV values.

TCODColor myColor(24,64,255); //RGB TCODColor myOtherColor(321.0f,0.7f,1.0f); //HSV

TCOD_color_t my_color={24,64,255}; /* RGB */ TCOD_color_t my_other_color = TCOD_color_RGB(24,64,255); /* RGB too */ TCOD_color_t my_yet_another_color = TCOD_color_HSV(321.0f,0.7f,1.0f); /* HSV */

TCODColor myColor = new TCODColor(321.0f,0.7f,1.0f); //HSV

inline constexpr TCODColor(int r_, int g_, int b_) noexcept

inline constexpr TCODColor(const TCOD_color_t &col) noexcept

TCODColor(float h, float s, float v) noexcept

inline constexpr bool operator==(const TCODColor &c) const noexcept

if (myColor == TCODColor::yellow) { …

} if (myColor != TCODColor::white) { … }

if (TCOD_color_equals(my_color,TCOD_yellow)) { … } if (!TCOD_color_equals(my_color,TCOD_white)) { … }

if my_color == libtcod.yellow : … if my_color != libtcod.white : …

if (myColor.Equal(TCODColor.yellow)) { … } if (myColor.NotEqual(TCODColor.white)) { … }

if myColor == tcod.color.yellow then … end

inline constexpr bool operator!=(const TCODColor &c) const noexcept

inline constexpr TCODColor operator*(const TCODColor &rhs) const noexcept

c1 = c2 * c3 => c1.r = c2.r * c3.r / 255 c1.g = c2.g * c3.g / 255 c1.b = c2.b * c3.b / 255 darkishRed = darkGrey * red

inline constexpr TCODColor operator*(float value) const noexcept

c1 = c2 * v => c1.r = CLAMP(0, 255, c2.r * v) c1.g = CLAMP(0, 255, c2.g * v) c1.b = CLAMP(0, 255, c2.b * v) darkishRed = red * 0.5

</tbody>

inline constexpr TCODColor operator+(const TCODColor &rhs) const noexcept

c1 = c1 + c2 => c1.r = MIN(255, c1.r + c2.r) c1.g = MIN(255, c1.g + c2.g) c1.b = MIN(255, c1.b + c2.b) lightishRed = red + darkGrey

inline constexpr TCODColor operator-(const TCODColor &rhs) const noexcept

c1 = c1 - c2 => c1.r = MAX(0, c1.r - c2.r) c1.g = MAX(0, c1.g - c2.g) c1.b = MAX(0, c1.b - c2.b) redish = red - darkGrey

void setHSV(float h, float s, float v) noexcept

After this function is called, the r,g,b fields of the color are calculated according to the h,s,v parameters.

Parameters:

• c – In the C and Python versions, the color to modify

• h, s, v – Color components in the HSV space 0.0 <= h < 360.0 0.0 <= s <= 1.0 0.0 <= v <= 1.0

void setHue(float h) noexcept

These functions set only a single component in the HSV color space.

void TCODColor::setHue (float h) void TCODColor::setSaturation (float s) void TCODColor::setValue (float v)

void TCOD_color_set_hue (TCOD_color_t *c, float h) void TCOD_color_set_saturation (TCOD_color_t *c, float s) void TCOD_color_set_value (TCOD_color_t *c, float v)

Color:setHue(h) Color:setSaturation(s) Color:setValue(v)

Parameters:

• h, s, v – Color components in the HSV space

• c – In the C and Python versions, the color to modify

void setSaturation(float s) noexcept

void setValue(float v) noexcept

void getHSV(float *h, float *s, float *v) const noexcept

Parameters:

• c – In the C and Python versions, the TCOD_color_t from which to read.

• h, s, v – Color components in the HSV space 0.0 <= h < 360.0 0.0 <= s <= 1.0 0.0 <= v <= 1.0

float getHue() noexcept

Should you need to extract only one of the HSV components, these functions are what you should call.

Note that if you need all three values, it’s way less burdensome for the CPU to call TCODColor::getHSV().

float TCODColor::getHue () float TCODColor::getSaturation () float TCODColor::getValue ()

float TCOD_color_get_hue (TCOD_color_t c) float TCOD_color_get_saturation (TCOD_color_t c) float TCOD_color_get_value (TCOD_color_t c)

Color:getHue() Color:getSaturation() Color:getValue()

float TCODColor::getHue() float TCODColor::getSaturation() float TCODColor::getValue()

Parameters:

c – the TCOD_color_t from which to read

float getSaturation() noexcept

float getValue() noexcept

void shiftHue(float hshift) noexcept

The hue shift value is the number of grades the color’s hue will be shifted.

The value can be negative for shift left, or positive for shift right. Resulting values H < 0 and H >= 360 are handled automatically.

Parameters:

• c – The color to modify

• hshift – The hue shift value

void scaleHSV(float sscale, float vscale) noexcept

Parameters:

• c – The color to modify

• sscale – saturation multiplier (1.0f for no change)

• vscale – value multiplier (1.0f for no change)

inline explicit constexpr operator TCOD_ColorRGB() const noexcept

Allow explicit conversions to TCOD_ColorRGB.

New in version 1.19.

inline explicit constexpr operator TCOD_ColorRGBA() const noexcept

Allow explicit conversions to TCOD_ColorRGBA.

New in version 1.19.

inline explicit constexpr operator tcod::ColorRGB() const noexcept

Allow explicit conversions to tcod::ColorRGB.

New in version 1.19.

inline explicit constexpr operator tcod::ColorRGBA() const noexcept

Allow explicit conversions to tcod::ColorRGBA.

New in version 1.19.

Public Members

uint8_t r = {}

uint8_t g = {}

uint8_t b = {}

Public Static Functions

static inline constexpr TCODColor lerp(const TCODColor &c1, const TCODColor &c2, float coef) noexcept

c1 = lerp (c2, c3, coef) => c1.r = c2.r + (c3.r - c2.r ) * coef c1.g = c2.g + (c3.g - c2.g ) * coef c1.b = c2.b + (c3.b - c2.b ) * coef coef should be between 0.0 and 1.0 but you can as well use other values

coef == 0.0f
coef == 0.25f
coef == 0.5f
coef == 0.75f
coef == 1.0f

static void genMap(TCODColor *map, int nbKey, TCODColor const *keyColor, int const *keyIndex)

You can define a color map from an array of color keys.

Colors will be interpolated between the keys. 0 -> black 4 -> red 8 -> white Result :

black

red

white </tbody>

int idx[] = { 0, 4, 8 }; // indexes of the keys TCODColor col[] = { TCODColor( 0,0,0 ), TCODColor(255,0,0), TCODColor(255,255,255) }; // colors : black, red, white TCODColor map[9]; TCODColor::genMap(map,3,col,idx);

int idx[] = { 0, 4, 8 }; // indexes of the keys TCOD_color_t col[] = { { 0,0,0 }, {255,0,0}, {255,255,255} }; // colors : black, red, white TCOD_color_t map[9]; TCOD_color_gen_map(map,3,col,idx);

idx = [ 0, 4, 8 ] # indexes of the keys col = [ libtcod.Color( 0,0,0 ), libtcod.Color( 255,0,0 ), libtcod.Color(255,255,255) ] # colors : black, red, white map=libtcod.color_gen_map(col,idx)

Parameters:

• map – An array of colors to be filled by the function.

• nbKey – Number of color keys

• keyColor – Array of nbKey colors containing the color of each key

• keyIndex – Array of nbKey integers containing the index of each key. If you want to fill the map array, keyIndex[0] must be 0 and keyIndex[nbKey-1] is the number of elements in map minus 1 but you can also use the function to fill only a part of the map array.

template<int OutSize, typename KeyColors, typename KeyIndexes>
static inline constexpr auto genMap(const KeyColors &key_colors, const KeyIndexes &key_indexes) -> std::array<tcod::ColorRGB, OutSize>

Generate a gradient of colors.

// Generate an array of 16 colors, with black=0, red=8, white=15.
static constexpr auto gradient = TCODColor::genMap<16>(
    std::array{tcod::ColorRGB{0, 0, 0}, tcod::ColorRGB{255, 0, 0}, tcod::ColorRGB{255, 255, 255}},
    std::array{0, 8, 15});

New in version 1.24.

Template Parameters:

• OutSize – The size of the output array.

• KeyColors – A key color container of tcod::ColorRGB-like objects.

• KeyIndexes – The key index container of integers.

Parameters:

• key_colors – An array of which colors belong in sequence.

• key_indexes – An ascending array of indexes of the output to map the respective color from key_colors. First index must always be 0, last index must always be KeyColors - 1.

Returns:

std::array<tcod::ColorRGB, OutSize>

Throws:

std::invalid_argument – Issues with the key arrays will throw an error.

Friends

inline friend TCODLIB_API_INLINE_EXPORT friend TCODColor operator* (float value, const TCODColor &color) noexcept

Class TCODConsole

• Defined in File console.hpp

Class Documentation

class TCODConsole

Classic turn by turn game loop:

TCODConsole::initRoot(80,50,”my game”,false); while (!endGame && !TCODConsole::isWindowClosed()) { …

The console emulator handles the rendering of the game screen and the keyboard input. Classic real time game loop:

TCODConsole::initRoot(80,50,”my game”,false); TCODSystem::setFps(25); // limit framerate to 25 frames per second while (!endGame && !TCODConsole::isWindowClosed()) { TCOD_key_t key; TCODSystem::checkForEvent(TCOD_EVENT_KEY_PRESS,&key,NULL); updateWorld (key, TCODSystem::getLastFrameLength()); updateWorld(TCOD_key_t key, float elapsed) (using key if key.vk != TCODK_NONE) use elapsed to scale any update that is time dependent. … draw world+GUI on TCODConsole::root TCODConsole::flush(); }

tcod.console.initRoot(80,50,”my game”, false) root=libtcod.TCODConsole_root tcod.system.setFps(25) while not tcod.console.isWindowClosed() do &#8212; … draw on root tcod.console.flush() key=tcod.console.checkForKeypress() &#8212; … update world, using key and tcod.system.getLastFrameLength end draw on TCODConsole::root TCODConsole::flush(); TCOD_key_t key; TCODConsole::waitForEvent(TCOD_EVENT_KEY_PRESS,&key,NULL,true); … update world, using key }

Public Functions

TCODConsole() = default

Default constructor.

New in version 1.24.

void setDefaultBackground(TCODColor back)

This function changes the default background color for a console.

The default background color is used by several drawing functions like clear, putChar, …

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• back – the new default background color for this console

void setDefaultForeground(TCODColor fore)

This function changes the default foreground color for a console.

The default foreground color is used by several drawing functions like clear, putChar, …

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• fore – the new default foreground color for this console

void clear()

This function modifies all cells of a console : set the cell’s background color to the console default background color set the cell’s foreground color to the console default foreground color set the cell’s ASCII code to 32 (space)

Parameters:

con – in the C and Python versions, the offscreen console handler or NULL for the root console

void setCharBackground(int x, int y, const TCODColor &col, TCOD_bkgnd_flag_t flag = TCOD_BKGND_SET)

This function modifies the background color of a cell, leaving other properties (foreground color and ASCII code) unchanged.

void TCODConsole::setCharBackground(int x, int y, TCODColor col) void TCODConsole::setCharBackground(int x, int y, TCODColor col, TCODBackgroundFlag flag)

Console:setCharBackground(x, y, col) Console:setCharBackground(x, y, col, flag)

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinates of the cell in the console. 0 <= x < console width 0 <= y < console height

• col – the background color to use. You can use color constants

• flag – this flag defines how the cell’s background color is modified. See TCOD_bkgnd_flag_t

void setCharForeground(int x, int y, const TCODColor &col)

This function modifies the foreground color of a cell, leaving other properties (background color and ASCII code) unchanged.

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinates of the cell in the console. 0 <= x < console width 0 <= y < console height

• col – the foreground color to use. You can use color constants

void setChar(int x, int y, int c)

This function modifies the ASCII code of a cell, leaving other properties (background and foreground colors) unchanged.

Note that since a clear console has both background and foreground colors set to black for every cell, using setChar will produce black characters on black background. Use putchar instead.

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinates of the cell in the console. 0 <= x < console width 0 <= y < console height

• c – the new ASCII code for the cell. You can use ASCII constants

void putChar(int x, int y, int c, TCOD_bkgnd_flag_t flag = TCOD_BKGND_DEFAULT)

This function modifies every property of a cell : update the cell’s background color according to the console default background color (see TCOD_bkgnd_flag_t).

set the cell’s foreground color to the console default foreground color set the cell’s ASCII code to c

void TCODConsole::putChar(int x, int y, int c) void TCODConsole::putChar(int x, int y, int c, TCODBackgroundFlag flag)

Console:putChar(x, y, c) Console:putChar(x, y, c, flag)

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinates of the cell in the console. 0 <= x < console width 0 <= y < console height

• c – the new ASCII code for the cell. You can use ASCII constants

• flag – this flag defines how the cell’s background color is modified. See TCOD_bkgnd_flag_t

void putCharEx(int x, int y, int c, const TCODColor &fore, const TCODColor &back)

This function modifies every property of a cell : set the cell’s background color to back.

set the cell’s foreground color to fore. set the cell’s ASCII code to c.

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinates of the cell in the console. 0 <= x < console width 0 <= y < console height

• c – the new ASCII code for the cell. You can use ASCII constants

• fore, back – new foreground and background colors for this cell

void setBackgroundFlag(TCOD_bkgnd_flag_t flag)

This function defines the background mode (see TCOD_bkgnd_flag_t) for the console.

This flag is used by most functions that modify a cell background color. It defines how the console’s current background color is used to modify the cell’s existing background color : TCOD_BKGND_NONE : the cell’s background color is not modified. TCOD_BKGND_SET : the cell’s background color is replaced by the console’s default background color : newbk = curbk. TCOD_BKGND_MULTIPLY : the cell’s background color is multiplied by the console’s default background color : newbk = oldbk * curbk TCOD_BKGND_LIGHTEN : newbk = MAX(oldbk,curbk) TCOD_BKGND_DARKEN : newbk = MIN(oldbk,curbk) TCOD_BKGND_SCREEN : newbk = white - (white - oldbk) * (white - curbk) // inverse of multiply : (1-newbk) = (1-oldbk)*(1-curbk) TCOD_BKGND_COLOR_DODGE : newbk = curbk / (white - oldbk) TCOD_BKGND_COLOR_BURN : newbk = white - (white - oldbk) / curbk TCOD_BKGND_ADD : newbk = oldbk + curbk TCOD_BKGND_ADDALPHA(alpha) : newbk = oldbk + alpha*curbk TCOD_BKGND_BURN : newbk = oldbk + curbk - white TCOD_BKGND_OVERLAY : newbk = curbk.x <= 0.5 ? 2*curbk*oldbk : white - 2*(white-curbk)*(white-oldbk) TCOD_BKGND_ALPHA(alpha) : newbk = (1.0f-alpha)*oldbk + alpha*(curbk-oldbk) TCOD_BKGND_DEFAULT : use the console’s default background flag Note that TCOD_BKGND_ALPHA and TCOD_BKGND_ADDALPHA are MACROS that needs a float parameter between (0.0 and 1.0). TCOD_BKGND_ALPH and TCOD_BKGND_ADDA should not be used directly (else they will have the same effect as TCOD_BKGND_NONE). For Python, remove TCOD_ : libtcod.BKGND_NONE For C# : None, Set, Multiply, Lighten, Darken, Screen, ColorDodge, ColorBurn, Add, Burn Overlay, Default With lua, use tcod.None, …, tcod.Default, BUT tcod.console.Alpha(value) and tcod.console.AddAlpha(value) This default mode is used by several functions (print, printRect, …)

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• flag – this flag defines how the cell’s background color is modified. See TCOD_bkgnd_flag_t

TCOD_bkgnd_flag_t getBackgroundFlag() const

This function returns the background mode (see TCOD_bkgnd_flag_t) for the console.

This default mode is used by several functions (print, printRect, …)

Parameters:

con – in the C and Python versions, the offscreen console handler or NULL for the root console

void setAlignment(TCOD_alignment_t alignment)

This function defines the default alignment (see TCOD_alignment_t) for the console.

This default alignment is used by several functions (print, printRect, …). Values for alignment : TCOD_LEFT, TCOD_CENTER, TCOD_RIGHT (in Python, remove TCOD_ : libtcod.LEFT). For C# and Lua : LeftAlignment, RightAlignment, CenterAlignment

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• alignment – defines how the strings are printed on screen.

TCOD_alignment_t getAlignment() const

This function returns the default alignment (see TCOD_alignment_t) for the console.

This default mode is used by several functions (print, printRect, …). Values for alignment : TCOD_LEFT, TCOD_CENTER, TCOD_RIGHT (in Python, remove TCOD_ : libtcod.LEFT). For C# and Lua : LeftAlignment, RightAlignment, CenterAlignment

Parameters:

con – in the C and Python versions, the offscreen console handler or NULL for the root console

void print(int x, int y, const char *fmt, ...)

Print an EASCII formatted string to the console.

Deprecated since version 1.8: EASCII is being phased out. Use TCODConsole::printf or one of the UTF-8 overloads.

void print(int x, int y, const std::string &str)

Print an EASCII encoded string to the console.

This method will use this consoles default alignment, blend mode, and colors.

New in version 1.8.

void print(int x, int y, const std::string &str, TCOD_alignment_t alignment, TCOD_bkgnd_flag_t flag)

Print a UTF-8 string to the console with specific alignment and blend mode.

New in version 1.8.

void printf(int x, int y, const char *fmt, ...)

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

This method will use this consoles default alignment, blend mode, and colors.

New in version 1.8.

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

Format and print a UTF-8 string to the console with specific alignment and blend mode.

New in version 1.8.

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

Print an EASCII formatted string to the console.

Deprecated since version 1.8: Use TCODConsole::print or TCODConsole::printf. These functions have overloads for specifying flag and alignment.

int printRect(int x, int y, int w, int h, const char *fmt, ...)

This function draws a string in a rectangle inside the console, using default colors, alignment and background mode.

If the string reaches the borders of the rectangle, carriage returns are inserted. If h > 0 and the bottom of the rectangle is reached, the string is truncated. If h = 0, the string is only truncated if it reaches the bottom of the console. The function returns the height (number of console lines) of the printed string.

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinate of the character in the console, depending on the alignment : TCOD_LEFT : leftmost character of the string TCOD_CENTER : center character of the string TCOD_RIGHT : rightmost character of the string

• w, h – size of the rectangle x <= x+w < console width y <= y+h < console height

• fmt – printf-like format string, eventually followed by parameters. You can use control codes to change the colors inside the string, except in C#.

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

This function draws a string in a rectangle inside the console, using default colors, but specific alignment and background mode.

If the string reaches the borders of the rectangle, carriage returns are inserted. If h > 0 and the bottom of the rectangle is reached, the string is truncated. If h = 0, the string is only truncated if it reaches the bottom of the console. The function returns the height (number of console lines) of the printed string.

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinate of the character in the console, depending on the alignment : TCOD_LEFT : leftmost character of the string TCOD_CENTER : center character of the string TCOD_RIGHT : rightmost character of the string

• w, h – size of the rectangle x <= x+w < console width y <= y+h < console height

• flag – this flag defines how the cell’s background color is modified. See TCOD_bkgnd_flag_t

• alignment – defines how the strings are printed on screen.

• fmt – printf-like format string, eventually followed by parameters. You can use control codes to change the colors inside the string, except in C#.

int getHeightRect(int x, int y, int w, int h, const char *fmt, ...)

This function returns the expected height of an auto-wrapped string without actually printing the string with printRect or printRectEx.

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinate of the rectangle upper-left corner in the console

• w, h – size of the rectangle x <= x+w < console width y <= y+h < console height

• fmt – printf-like format string, eventually followed by parameters. You can use control codes to change the colors inside the string, except in C#.

void print(int x, int y, const wchar_t *fmt, ...)

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

int printRect(int x, int y, int w, int h, const wchar_t *fmt, ...)

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

int getHeightRect(int x, int y, int w, int h, const wchar_t *fmt, ...)

void rect(int x, int y, int w, int h, bool clear, TCOD_bkgnd_flag_t flag = TCOD_BKGND_DEFAULT)

Fill a rectangle inside a console.

For each cell in the rectangle : set the cell’s background color to the console default background color if clear is true, set the cell’s ASCII code to 32 (space)

void TCODConsole::rect(int x, int y, int w, int h, bool clear) void TCODConsole::rect(int x, int y, int w, int h, bool clear, TCODBackgroundFlag flag)

Console:rect(x, y, w, h, clear) Console:rect(x, y, w, h, clear, flag)

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinates of rectangle upper-left corner in the console. 0 <= x < console width 0 <= y < console height

• w, h – size of the rectangle in the console. x <= x+w < console width y <= y+h < console height

• clear – if true, all characters inside the rectangle are set to ASCII code 32 (space). If false, only the background color is modified

• flag – this flag defines how the cell’s background color is modified. See TCOD_bkgnd_flag_t

void hline(int x, int y, int l, TCOD_bkgnd_flag_t flag = TCOD_BKGND_DEFAULT)

Draws an horizontal line in the console, using ASCII code TCOD_CHAR_HLINE (196), and the console’s default background/foreground colors.

void TCODConsole::hline(int x,int y, int l) void TCODConsole::hline(int x,int y, int l, TCODBackgroundFlag flag)

Console:hline(x,y, l) Console:hline(x,y, l, flag)

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – Coordinates of the line’s left end in the console. 0 <= x < console width 0 <= y < console height

• l – The length of the line in cells 1 <= l <= console width - x

• flag – this flag defines how the cell’s background color is modified. See TCOD_bkgnd_flag_t

void vline(int x, int y, int l, TCOD_bkgnd_flag_t flag = TCOD_BKGND_DEFAULT)

Draws an vertical line in the console, using ASCII code TCOD_CHAR_VLINE (179), and the console’s default background/foreground colors.

void TCODConsole::vline(int x,int y, int l) void TCODConsole::vline(int x,int y, int l, TCODBackgroundFlag flag)

Console:vline(x,y, l) Console:vline(x,y, l, flag)

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – Coordinates of the line’s upper end in the console. 0 <= x < console width 0 <= y < console height

• l – The length of the line in cells 1 <= l <= console height - y

• flag – this flag defines how the cell’s background color is modified. See TCOD_bkgnd_flag_t

void printFrame(int x, int y, int w, int h, bool clear = true, TCOD_bkgnd_flag_t flag = TCOD_BKGND_DEFAULT, const char *fmt = NULL, ...)

This function calls the rect function using the supplied background mode flag, then draws a rectangle with the console’s default foreground color.

If fmt is not NULL, it is printed on the top of the rectangle, using inverted colors.

void TCODConsole::printFrame(int x,int y, int w,int h) void TCODConsole::printFrame(int x,int y, int w,int h, bool clear) void TCODConsole::printFrame(int x,int y, int w,int h, bool clear, TCODBackgroundFlag flag) void TCODConsole::printFrame(int x,int y, int w,int h, bool clear, TCODBackgroundFlag flag, string fmt)

Console:printFrame(x,y, w,h) Console:printFrame(x,y, w,h, clear) Console:printFrame(x,y, w,h, clear, flag) Console:printFrame(x,y, w,h, clear, flag, fmt)

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – Coordinates of the rectangle’s upper-left corner in the console. 0 <= x < console width 0 <= y < console height

• w, h – size of the rectangle in the console. x <= x+w < console width y <= y+h < console height

• clear – if true, all characters inside the rectangle are set to ASCII code 32 (space). If false, only the background color is modified

• flag – this flag defines how the cell’s background color is modified. See TCOD_bkgnd_flag_t

• fmt – if NULL, the function only draws a rectangle. Else, printf-like format string, eventually followed by parameters. You can use control codes to change the colors inside the string.

int getWidth() const

This function returns the width of a console (either the root console or an offscreen console)

Parameters:

con – in the C and Python versions, the offscreen console handler or NULL for the root console

int getHeight() const

This function returns the height of a console (either the root console or an offscreen console)

Parameters:

con – in the C and Python versions, the offscreen console handler or NULL for the root console

TCODColor getDefaultBackground() const

This function returns the default background color of a console.

Parameters:

con – in the C and Python versions, the offscreen console handler or NULL for the root console

TCODColor getDefaultForeground() const

This function returns the default foreground color of a console.

Parameters:

con – in the C and Python versions, the offscreen console handler or NULL for the root console

TCODColor getCharBackground(int x, int y) const

This function returns the background color of a cell.

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinates of the cell in the console. 0 <= x < console width 0 <= y < console height

TCODColor getCharForeground(int x, int y) const

This function returns the foreground color of a cell.

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinates of the cell in the console. 0 <= x < console width 0 <= y < console height

int getChar(int x, int y) const

This function returns the ASCII code of a cell.

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• x, y – coordinates of the cell in the console. 0 <= x < console width 0 <= y < console height

TCODConsole(int w, int h)

You can create as many off-screen consoles as you want by using this function. You can draw on them as you would do with the root console, but you cannot flush them to the screen. Else, you can blit them on other consoles, including the root console. See blit. The C version of this function returns a console handler that you can use in most console drawing functions.

The offscreen consoles allow you to draw on secondary consoles as you would do with the root console. You can then blit those secondary consoles on the root console. This allows you to use local coordinate space while rendering a portion of the final screen, and easily move components of the screen without modifying the rendering functions.

Creating a 40x20 offscreen console, filling it with red and blitting it on the root console at position 5,5 TCODConsole *offscreenConsole = new TCODConsole(40,20); offscreenConsole->setDefaultBackground(TCODColor::red); offscreenConsole->clear(); TCODConsole::blit(offscreenConsole,0,0,40,20,TCODConsole::root,5,5,255);

TCOD_console_t offscreen_console = TCOD_console_new(40,20); TCOD_console_set_default_background(offscreen_console,TCOD_red); TCOD_console_clear(offscreen_console); TCOD_console_blit(offscreen_console,0,0,40,20,NULL,5,5,255);

offscreen_console = libtcod.console_new(40,20) libtcod.console_set_background_color(offscreen_console,libtcod.red) libtcod.console_clear(offscreen_console) libtcod.console_blit(offscreen_console,0,0,40,20,0,5,5,255)

&#8212; Creating a 40x20 offscreen console, filling it with red and blitting it on the root console at position 5,5 offscreenConsole = tcod.Console(40,20) offscreenConsole:setBackgroundColor(tcod.color.red) offscreenConsole:clear() tcod.console.blit(offscreenConsole,0,0,40,20,libtcod.TCODConsole_root,5,5,255)

Parameters:

w, h – the console size. 0 < w 0 < h

TCODConsole(const char *filename)

You can create an offscreen console from a file created with Ascii Paint with this constructor.

Creating an offscreen console, filling it with data from the .asc file TCODConsole *offscreenConsole = new TCODConsole(“myfile.asc”);

TCOD_console_t offscreen_console = TCOD_console_from_file(“myfile.apf”);

Parameters:

filename – path to the .asc or .apf file created with Ascii Paint

bool loadAsc(const char *filename)

You can load data from a file created with Ascii Paint with this function.

When needed, the console will be resized to fit the file size. The function returns false if it couldn’t read the file.

Creating a 40x20 offscreen console TCODConsole *offscreenConsole = new TCODConsole(40,20); possibly resizing it and filling it with data from the .asc file offscreenConsole->loadAsc(“myfile.asc”);

TCOD_console_t offscreen_console = TCOD_console_new(40,20); TCOD_console_load_asc(offscreen_console,”myfile.asc”);

Parameters:

• con – in the C and Python versions, the offscreen console handler

• filename – path to the .asc file created with Ascii Paint

bool loadApf(const char *filename)

You can load data from a file created with Ascii Paint with this function.

When needed, the console will be resized to fit the file size. The function returns false if it couldn’t read the file.

Creating a 40x20 offscreen console TCODConsole *offscreenConsole = new TCODConsole(40,20); possibly resizing it and filling it with data from the .apf file offscreenConsole->loadApf(“myfile.apf”);

TCOD_console_t offscreen_console = TCOD_console_new(40,20); TCOD_console_load_apf(offscreen_console,”myfile.asc”);

Parameters:

• con – in the C and Python versions, the offscreen console handler

• filename – path to the .apf file created with Ascii Paint

bool saveAsc(const char *filename) const

You can save data from a console to Ascii Paint format with this function.

The function returns false if it couldn’t write the file. This is the only ASC function that works also with the root console !

console->saveAsc(“myfile.asc”);

TCOD_console_save_asc(console,”myfile.asc”);

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• filename – path to the .asc file to be created

bool saveApf(const char *filename) const

You can save data from a console to Ascii Paint format with this function.

The function returns false if it couldn’t write the file. This is the only ASC function that works also with the root console !

console->saveApf(“myfile.apf”);

TCOD_console_save_apf(console,”myfile.apf”);

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• filename – path to the .apf file to be created

inline bool loadXp(const char *filename)

inline bool saveXp(const char *filename, int compress_level)

void setKeyColor(const TCODColor &col)

This function defines a transparent background color for an offscreen console.

All cells with this background color are ignored by the blit operation. You can use it to blit only some parts of the console.

Parameters:

• con – in the C and Python versions, the offscreen console handler or NULL for the root console

• col – the transparent background color

void setDirty(int x, int y, int w, int h)

inline TCODConsole(TCOD_Console *console)

inline explicit TCODConsole(tcod::ConsolePtr console)

Construct a new TCODConsole object from a tcod::ConsolePtr.

New in version 1.19.

inline auto get_data() noexcept -> TCOD_Console*

Return a pointer to the underlying TCOD_Console struct.

New in version 1.14.

Changed in version 1.19: This now returns a non-NULL pointer to the root console.

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

inline auto get() noexcept -> TCOD_Console*

Return a pointer to the underlying TCOD_Console struct.

Returns:

TCOD_Console*

New in version 1.19.

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

inline operator TCOD_Console&()

Allow implicit conversions into a TCOD_Console reference.

New in version 1.19.

inline operator const TCOD_Console&() const

Allow implicit conversions into a const TCOD_Console reference.

New in version 1.19.

inline explicit operator TCOD_Console*() noexcept

Allow explicit conversions into a TCOD_Console pointer.

Same as calling get_data.

New in version 1.19.

inline explicit operator const TCOD_Console*() const noexcept

Allow explicit conversions into a const TCOD_Console pointer.

Same as calling get_data.

New in version 1.19.

Public Static Functions

static void initRoot(int w, int h, const char *title, bool fullscreen = false, TCOD_renderer_t renderer = TCOD_RENDERER_SDL)

static void TCODConsole::initRoot(int w, int h, string title) static void TCODConsole::initRoot(int w, int h, string title, bool fullscreen) static void TCODConsole::initRoot(int w, int h, string title, bool fullscreen, TCODRendererType renderer)

tcod.console.initRoot(w,h,title) &#8212; fullscreen = false, renderer = SDL tcod.console.initRoot(w,h,title,fullscreen) &#8212; renderer = SDL tcod.console.initRoot(w,h,title,fullscreen,renderer) &#8212; renderers : tcod.GLSL, tcod.OpenGL, tcod.SDL

Parameters:

• w, h – size of the console(in characters). The default font in libtcod (./terminal.png) uses 8x8 pixels characters. You can change the font by calling TCODConsole::setCustomFont before calling initRoot.

• title – title of the window. It’s not visible when you are in fullscreen. Note 1 : you can dynamically change the window title with TCODConsole::setWindowTitle

• fullscreen – whether you start in windowed or fullscreen mode. Note 1 : you can dynamically change this mode with TCODConsole::setFullscreen Note 2 : you can get current mode with TCODConsole::isFullscreen

• renderer – which renderer to use. Possible values are : TCOD_RENDERER_GLSL : works only on video cards with pixel shaders TCOD_RENDERER_OPENGL : works on all video cards supporting OpenGL 1.4 TCOD_RENDERER_SDL : should work everywhere! Note 1: if you select a renderer that is not supported by the player’s machine, libtcod scan the lower renderers until it finds a working one. Note 2: on recent video cards, GLSL results in up to 900% increase of framerates in the true color sample compared to SDL renderer. Note 3: whatever renderer you use, it can always be overridden by the player through the libtcod.cfg file. Note 4: you can dynamically change the renderer after calling initRoot with TCODSystem::setRenderer. Note 5: you can get current renderer with TCODSystem::getRenderer. It might be different from the one you set in initRoot in case it’s not supported on the player’s computer.

static void setCustomFont(const char *fontFile, int flags = TCOD_FONT_LAYOUT_ASCII_INCOL, int nbCharHoriz = 0, int nbCharVertic = 0)

This function allows you to use a bitmap font (png or bmp) with custom character size or layout.

It should be called before initializing the root console with initRoot. Once this function is called, you can define your own custom mappings using mapping functions Different font layouts

ASCII_INROW	ASCII_INCOL	TCOD

• ascii, in columns : characters 0 to 15 are in the first column. The space character is at coordinates 2,0.

• ascii, in rows : characters 0 to 15 are in the first row. The space character is at coordinates 0,2.

• tcod : special mapping. Not all ascii values are mapped. The space character is at coordinates 0,0.

Different font types

standard (non antialiased)	antialiased (32 bits PNG)	antialiased (greyscale)

• standard : transparency is given by a key color automatically detected by looking at the color of the space character

• 32 bits : transparency is given by the png alpha layer. The font color does not matter but it must be desaturated

• greyscale : transparency is given by the pixel value. You can use white characters on black background or black characters on white background. The background color is automatically detected by looking at the color of the space character

Examples of fonts can be found in libtcod’s fonts directory. Check the Readme file there.

static void TCODConsole::setCustomFont(string fontFile) static void TCODConsole::setCustomFont(string fontFile, int flags) static void TCODConsole::setCustomFont(string fontFile, int flags, int nbCharHoriz) static void TCODConsole::setCustomFont(string fontFile, int flags, int nbCharHoriz, int nbCharVertic)

tcod.console.setCustomFont(fontFile) tcod.console.setCustomFont(fontFile, flags) tcod.console.setCustomFont(fontFile, nbCharHoriz) tcod.console.setCustomFont(fontFile, flags, nbCharHoriz, nbCharVertic) &#8212; flags : tcod.LayoutAsciiInColumn, tcod.LayoutAsciiInRow, tcod.LayoutTCOD, tcod.Greyscale TCODConsole::setCustomFont(“standard_8x8_ascii_in_col_font.bmp”,TCOD_FONT_LAYOUT_ASCII_INCOL); TCODConsole::setCustomFont(“32bits_8x8_ascii_in_row_font.png”,TCOD_FONT_LAYOUT_ASCII_INROW); TCODConsole::setCustomFont(“greyscale_8x8_tcod_font.png”,TCOD_FONT_LAYOUT_TCOD | TCOD_FONT_TYPE_GREYSCALE);

TCOD_console_set_custom_font(“standard_8x8_ascii_in_col_font.bmp”,TCOD_FONT_LAYOUT_ASCII_INCOL,16,16); TCOD_console_set_custom_font(“32bits_8x8_ascii_in_row_font.png”,TCOD_FONT_LAYOUT_ASCII_INROW,32,8); TCOD_console_set_custom_font(“greyscale_8x8_tcod_font.png”,TCOD_FONT_LAYOUT_TCOD | TCOD_FONT_TYPE_GREYSCALE,32,8);

libtcod.console_set_custom_font(“standard_8x8_ascii_in_col_font.bmp”,libtcod.FONT_LAYOUT_ASCII_INCOL) libtcod.console_set_custom_font(“32bits_8x8_ascii_in_row_font.png”,libtcod.FONT_LAYOUT_ASCII_INROW) libtcod.console_set_custom_font(“greyscale_8x8_tcod_font.png”,libtcod.FONT_LAYOUT_TCOD | libtcod.FONT_TYPE_GREYSCALE)

tcod.console.setCustomFont(“standard_8x8_ascii_in_col_font.bmp”,tcod.LayoutAsciiInColumn); tcod.console.setCustomFont(“32bits_8x8_ascii_in_row_font.png”,tcod.LayoutAsciiInRow); tcod.console.setCustomFont(“greyscale_8x8_tcod_font.png”,tcod.LayoutTCOD + tcod.Greyscale);

Parameters:

• fontFile – Name of a .bmp or .png file containing the font.

• flags – Used to define the characters layout in the bitmap and the font type : TCOD_FONT_LAYOUT_ASCII_INCOL : characters in ASCII order, code 0-15 in the first column TCOD_FONT_LAYOUT_ASCII_INROW : characters in ASCII order, code 0-15 in the first row TCOD_FONT_LAYOUT_TCOD : simplified layout. See examples below. TCOD_FONT_TYPE_GREYSCALE : create an anti-aliased font from a greyscale bitmap For Python, remove TCOD _ : libtcod.FONT_LAYOUT_ASCII_INCOL

• nbCharHoriz, nbCharVertic – Number of characters in the font. Should be 16x16 for ASCII layouts, 32x8 for TCOD layout. But you can use any other layout. If set to 0, there are deduced from the font layout flag.

static void mapAsciiCodeToFont(int asciiCode, int fontCharX, int fontCharY)

These functions allow you to map characters in the bitmap font to ASCII codes. They should be called after initializing the root console with initRoot. You can dynamically change the characters mapping at any time, allowing to use several fonts in the same screen.

Parameters:

• asciiCode – ASCII code to map.

• fontCharX, fontCharY – Coordinate of the character in the bitmap font (in characters, not pixels).

static void mapAsciiCodesToFont(int firstAsciiCode, int nbCodes, int fontCharX, int fontCharY)

Parameters:

• firstAsciiCode – first ASCII code to map

• nbCodes – number of consecutive ASCII codes to map

• fontCharX, fontCharY – coordinate of the character in the bitmap font (in characters, not pixels) corresponding to the first ASCII code

static void mapStringToFont(const char *s, int fontCharX, int fontCharY)

Parameters:

• s – string containing the ASCII codes to map

• fontCharX, fontCharY – coordinate of the character in the bitmap font (in characters, not pixels) corresponding to the first ASCII code in the string

static bool isFullscreen()

This function returns true if the current mode is fullscreen.

static void setFullscreen(bool fullscreen)

This function switches the root console to fullscreen or windowed mode.

Note that there is no predefined key combination to switch to/from fullscreen. You have to do this in your own code.

TCOD_key_t key; TCODConsole::checkForEvent(TCOD_EVENT_KEY_PRESS,&key,NULL); if ( key.vk == TCODK_ENTER && key.lalt ) TCODConsole::setFullscreen(!TCODConsole::isFullscreen());

TCOD_key_t key; TCOD_console_check_for_event(TCOD_EVENT_KEY_PRESS,&key,NULL); if ( key.vk == TCODK_ENTER && key.lalt ) TCOD_console_set_fullscreen(!TCOD_console_is_fullscreen());

key=Key() libtcod.console_check_for_event(libtcod.EVENT_KEY_PRESS,key,0) if key.vk == libtcod.KEY_ENTER and key.lalt : libtcod.console_set_fullscreen(not libtcod.console_is_fullscreen())

key=tcod.console.checkForKeypress() if key.KeyCode == tcod.Enter and key.LeftAlt then tcod.console.setFullscreen(not tcod.console.isFullscreen()) end

Parameters:

fullscreen – true to switch to fullscreen mode. false to switch to windowed mode.

static void setWindowTitle(const char *title)

This function dynamically changes the title of the game window.

Note that the window title is not visible while in fullscreen.

Parameters:

title – New title of the game window

static bool isWindowClosed()

When you start the program, this returns false.

Once a “close window” event has been sent by the window manager, it will always return true. You’re supposed to exit cleanly the game.

static bool hasMouseFocus()

Returns true if the mouse cursor is inside the game window area and the game window is the active application.

static bool isActive()

Returns false if the game window is not the active window or is iconified.

static void credits()

You can print a “Powered by libtcod x.y.z” screen during your game startup simply by calling this function after initRoot. The credits screen can be skipped by pressing any key.

Use these functions to display credits, as seen in the samples.

static bool renderCredits(int x, int y, bool alpha)

You can also print the credits on one of your game screens (your main menu for example) by calling this function in your main loop.

This function returns true when the credits screen is finished, indicating that you no longer need to call it.

TCODConsole::initRoot(80,50,”The Chronicles Of Doryen v0.1”,false); // initialize the root console bool endCredits=false; while ( ! TCODConsole::isWindowClosed() ) { // your game loop your game rendering here… render transparent credits near the center of the screen if (! endCredits ) endCredits=TCODConsole::renderCredits(35,25,true); TCODConsole::flush(); }

TCOD_console_init_root(80,50,”The Chronicles Of Doryen v0.1”,false); bool end_credits=false; while ( ! TCOD_console_is_window_closed() ) { your game rendering here… render transparent credits near the center of the screen if (! end_credits ) end_credits=TCOD_console_credits_render(35,25,true); TCOD_console_flush(); }

libtcod.console_init_root(80,50,”The Chronicles Of Doryen v0.1”,False) end_credits=False while not libtcod.console_is_window_closed() : your game rendering here… render transparent credits near the center of the screen if (not end_credits ) : end_credits=libtcod.console_credits_render(35,25,True) libtcod.console_flush()

tcod.console.initRoot(80,50,”The Chronicles Of Doryen v0.1”) &#8212; initialize the root console endCredits=false while not tcod.console.isWindowClosed() do &#8212; your game loop &#8212; your game rendering here… &#8212; render transparent credits near the center of the screen if not endCredits then endCredits=tcod.console.renderCredits(35,25,true) end tcod.console.flush() end

Parameters:

• x, y – Position of the credits text in your root console

• alpha – If true, credits are transparently added on top of the existing screen. For this to work, this function must be placed between your screen rendering code and the console flush.

static void resetCredits()

When using renderCredits, you can restart the credits animation from the beginning before it’s finished by calling this function.

static void setColorControl(TCOD_colctrl_t con, const TCODColor &fore, const TCODColor &back)

If you want to draw a string using different colors for each word, the basic solution is to call a string printing function several times, changing the default colors between each call.

The TCOD library offers a simpler way to do this, allowing you to draw a string using different colors in a single call. For this, you have to insert color control codes in your string. A color control code is associated with a color set (a foreground color and a background color). If you insert this code in your string, the next characters will use the colors associated with the color control code. There are 5 predefined color control codes : For Python, remove TCOD_ : libtcod.COLCTRL_1 TCOD_COLCTRL_1 TCOD_COLCTRL_2 TCOD_COLCTRL_3 TCOD_COLCTRL_4 TCOD_COLCTRL_5 To associate a color with a code, use setColorControl. To go back to the console’s default colors, insert in your string the color stop control code : TCOD_COLCTRL_STOP

You can also use any color without assigning it to a control code, using the generic control codes : TCOD_COLCTRL_FORE_RGB TCOD_COLCTRL_BACK_RGB

Those controls respectively change the foreground and background color used to print the string characters. In the string, you must insert the r,g,b components of the color (between 1 and 255. The value 0 is forbidden because it represents the end of the string in C/C++) immediately after this code.

A string with a red over black word, using predefined color control codes TCODConsole::setColorControl(TCOD_COLCTRL_1,TCODColor::red,TCODColor::black); TCODConsole::root->print(1,1,”String with a %cred%c word.”,TCOD_COLCTRL_1,TCOD_COLCTRL_STOP); A string with a red over black word, using generic color control codes TCODConsole::root->print(1,1,”String with a %c%c%c%c%c%c%c%cred%c word.”, TCOD_COLCTRL_FORE_RGB,255,1,1,TCOD_COLCTRL_BACK_RGB,1,1,1,TCOD_COLCTRL_STOP); A string with a red over black word, using generic color control codes TCODConsole::root->print(1,1,”String with a %c%c%c%c%c%c%c%cred%c word.”, TCOD_COLCTRL_FORE_RGB,255,1,1,TCOD_COLCTRL_BACK_RGB,1,1,1,TCOD_COLCTRL_STOP);

A string with a red over black word, using predefined color control codes TCOD_console_set_color_control(TCOD_COLCTRL_1,red,black); TCOD_console_print(NULL,1,1,”String with a %cred%c word.”,TCOD_COLCTRL_1,TCOD_COLCTRL_STOP); A string with a red word (over default background color), using generic color control codes TCOD_console_print(NULL,1,1,”String with a %c%c%c%cred%c word.”, TCOD_COLCTRL_FORE_RGB,255,1,1,TCOD_COLCTRL_STOP); A string with a red over black word, using generic color control codes TCOD_console_print(NULL,1,1,”String with a %c%c%c%c%c%c%c%cred%c word.”, TCOD_COLCTRL_FORE_RGB,255,1,1,TCOD_COLCTRL_BACK_RGB,1,1,1,TCOD_COLCTRL_STOP);

A string with a red over black word, using predefined color control codes

libtcod.console_set_color_control(libtcod.COLCTRL_1,libtcod.red,libtcod.black) libtcod.console_print(0,1,1,”String with a %cred%c word.”%(libtcod.COLCTRL_1,libtcod.COLCTRL_STOP)) A string with a red word (over default background color), using generic color control codes

libtcod.console_print(0,1,1,”String with a %c%c%c%cred%c word.”%(libtcod.COLCTRL_FORE_RGB,255,1,1,libtcod.COLCTRL_STOP)) A string with a red over black word, using generic color control codes

libtcod.console_print(0,1,1,”String with a %c%c%c%c%c%c%c%cred%c word.”% (libtcod.COLCTRL_FORE_RGB,255,1,1,libtcod.COLCTRL_BACK_RGB,1,1,1,libtcod.COLCTRL_STOP))

TCODConsole.root.print(1,1,String.Format(“String with a {0}red{1} word.”, TCODConsole.getRGBColorControlString(ColorControlForeground,TCODColor.red), TCODConsole.getColorControlString(ColorControlStop));

Parameters:

• con – the color control TCOD_COLCTRL_x, 1<=x<=5

• fore – foreground color when this control is activated

• back – background color when this control is activated

static void mapStringToFont(const wchar_t *s, int fontCharX, int fontCharY)

those functions are similar to their ASCII equivalent, but work with unicode strings (wchar_t in C/C++).

Note that unicode is not supported in the Python wrapper.

static void setFade(uint8_t fade, const TCODColor &fadingColor)

This function defines the fading parameters, allowing to easily fade the game screen to/from a color. Once they are defined, the fading parameters are valid for ever. You don’t have to call setFade for each rendered frame (unless you change the fading parameters).

Use these functions to easily fade to/from a color

for (int fade=255; fade >= 0; fade &#8212;) { TCODConsole::setFade(fade,TCODColor::black); TCODConsole::flush(); }

int fade; for (fade=255; fade >= 0; fade &#8212;) { TCOD_console_setFade(fade,TCOD_black); TCOD_console_flush(); }

for fade in range(255,0) : libtcod.console_setFade(fade,libtcod.black) libtcod.console_flush()

for fade=255,0,-1 do tcod.console.setFade(fade,tcod.color.black) tcod.console.flush() end

Parameters:

• fade – the fading amount. 0 => the screen is filled with the fading color. 255 => no fading effect

• fadingColor – the color to use during the console flushing operation

static uint8_t getFade()

This function returns the current fade amount, previously defined by setFade.

static TCODColor getFadingColor()

This function returns the current fading color, previously defined by setFade.

static void flush()

Once the root console is initialized, you can use one of the printing functions to change the background colors, the foreground colors or the ASCII characters on the console.

Once you’ve finished rendering the root console, you have to actually apply the updates to the screen with this function.

static TCOD_key_t waitForKeypress(bool flush)

Some useful graphic characters in the terminal.bmp font.

For the Python version, remove TCOD_ from the constants. C# and Lua is in parenthesis : Single line walls: TCOD_CHAR_HLINE=196 (HorzLine) TCOD_CHAR_VLINE=179 (VertLine) TCOD_CHAR_NE=191 (NE) TCOD_CHAR_NW=218 (NW) TCOD_CHAR_SE=217 (SE) TCOD_CHAR_SW=192 (SW)

Double lines walls: TCOD_CHAR_DHLINE=205 (DoubleHorzLine) TCOD_CHAR_DVLINE=186 (DoubleVertLine) TCOD_CHAR_DNE=187 (DoubleNE) TCOD_CHAR_DNW=201 (DoubleNW) TCOD_CHAR_DSE=188 (DoubleSE) TCOD_CHAR_DSW=200 (DoubleSW)

Single line vertical/horizontal junctions (T junctions): TCOD_CHAR_TEEW=180 (TeeWest) TCOD_CHAR_TEEE=195 (TeeEast) TCOD_CHAR_TEEN=193 (TeeNorth) TCOD_CHAR_TEES=194 (TeeSouth)

Double line vertical/horizontal junctions (T junctions): TCOD_CHAR_DTEEW=185 (DoubleTeeWest) TCOD_CHAR_DTEEE=204 (DoubleTeeEast) TCOD_CHAR_DTEEN=202 (DoubleTeeNorth) TCOD_CHAR_DTEES=203 (DoubleTeeSouth)

Block characters: TCOD_CHAR_BLOCK1=176 (Block1) TCOD_CHAR_BLOCK2=177 (Block2) TCOD_CHAR_BLOCK3=178 (Block3)

Cross-junction between two single line walls: TCOD_CHAR_CROSS=197 (Cross)

Arrows: TCOD_CHAR_ARROW_N=24 (ArrowNorth) TCOD_CHAR_ARROW_S=25 (ArrowSouth) TCOD_CHAR_ARROW_E=26 (ArrowEast) TCOD_CHAR_ARROW_W=27 (ArrowWest)

Arrows without tail: TCOD_CHAR_ARROW2_N=30 (ArrowNorthNoTail) TCOD_CHAR_ARROW2_S=31 (ArrowSouthNoTail) TCOD_CHAR_ARROW2_E=16 (ArrowEastNoTail) TCOD_CHAR_ARROW2_W=17 (ArrowWestNoTail)

Double arrows: TCOD_CHAR_DARROW_H=29 (DoubleArrowHorz) TCOD_CHAR_ARROW_V=18 (DoubleArrowVert)

GUI stuff: TCOD_CHAR_CHECKBOX_UNSET=224 TCOD_CHAR_CHECKBOX_SET=225 TCOD_CHAR_RADIO_UNSET=9 TCOD_CHAR_RADIO_SET=10

Sub-pixel resolution kit: TCOD_CHAR_SUBP_NW=226 (SubpixelNorthWest) TCOD_CHAR_SUBP_NE=227 (SubpixelNorthEast) TCOD_CHAR_SUBP_N=228 (SubpixelNorth) TCOD_CHAR_SUBP_SE=229 (SubpixelSouthEast) TCOD_CHAR_SUBP_DIAG=230 (SubpixelDiagonal) TCOD_CHAR_SUBP_E=231 (SubpixelEast) TCOD_CHAR_SUBP_SW=232 (SubpixelSouthWest)

Miscellaneous characters: TCOD_CHAR_SMILY = 1 (Smilie) TCOD_CHAR_SMILY_INV = 2 (SmilieInv) TCOD_CHAR_HEART = 3 (Heart) TCOD_CHAR_DIAMOND = 4 (Diamond) TCOD_CHAR_CLUB = 5 (Club) TCOD_CHAR_SPADE = 6 (Spade) TCOD_CHAR_BULLET = 7 (Bullet) TCOD_CHAR_BULLET_INV = 8 (BulletInv) TCOD_CHAR_MALE = 11 (Male) TCOD_CHAR_FEMALE = 12 (Female) TCOD_CHAR_NOTE = 13 (Note) TCOD_CHAR_NOTE_DOUBLE = 14 (NoteDouble) TCOD_CHAR_LIGHT = 15 (Light) TCOD_CHAR_EXCLAM_DOUBLE = 19 (ExclamationDouble) TCOD_CHAR_PILCROW = 20 (Pilcrow) TCOD_CHAR_SECTION = 21 (Section) TCOD_CHAR_POUND = 156 (Pound) TCOD_CHAR_MULTIPLICATION = 158 (Multiplication) TCOD_CHAR_FUNCTION = 159 (Function) TCOD_CHAR_RESERVED = 169 (Reserved) TCOD_CHAR_HALF = 171 (Half) TCOD_CHAR_ONE_QUARTER = 172 (OneQuarter) TCOD_CHAR_COPYRIGHT = 184 (Copyright) TCOD_CHAR_CENT = 189 (Cent) TCOD_CHAR_YEN = 190 (Yen) TCOD_CHAR_CURRENCY = 207 (Currency) TCOD_CHAR_THREE_QUARTERS = 243 (ThreeQuarters) TCOD_CHAR_DIVISION = 246 (Division) TCOD_CHAR_GRADE = 248 (Grade) TCOD_CHAR_UMLAUT = 249 (Umlaut) TCOD_CHAR_POW1 = 251 (Pow1) TCOD_CHAR_POW3 = 252 (Pow2) TCOD_CHAR_POW2 = 253 (Pow3) TCOD_CHAR_BULLET_SQUARE = 254 (BulletSquare)

The user handling functions allow you to get keyboard and mouse input from the user, either for turn by turn games (the function wait until the user press a key or a mouse button), or real time games (non blocking function). WARNING : those functions also handle screen redraw event, so TCODConsole::flush function won’t redraw screen if no user input function is called !

static TCOD_key_t checkForKeypress(int flags = TCOD_KEY_RELEASED)

static bool isKeyPressed(TCOD_keycode_t key)

The preferred way to check for user input is to use checkForEvent below, but you can also get the status of any special key at any time with :

This function stops the application until an event occurs.

Parameters:

key – Any key code defined in keycode_t except TCODK_CHAR (Char) and TCODK_NONE (NoKey)

static void blit(const TCODConsole *src, int xSrc, int ySrc, int wSrc, int hSrc, TCODConsole *dst, int xDst, int yDst, float foreground_alpha = 1.0f, float background_alpha = 1.0f)

This function allows you to blit a rectangular area of the source console at a specific position on a destination console.

It can also simulate alpha transparency with the fade parameter.

static void TCODConsole::blit(TCODConsole src, int xSrc, int ySrc, int wSrc, int hSrc, TCODConsole dst, int xDst, int yDst) static void TCODConsole::blit(TCODConsole src, int xSrc, int ySrc, int wSrc, int hSrc, TCODConsole dst, int xDst, int yDst, float foreground_alpha) static void TCODConsole::blit(TCODConsole src, int xSrc, int ySrc, int wSrc, int hSrc, TCODConsole dst, int xDst, int yDst, float foreground_alpha, float background_alpha)

tcod.console.blit(src, xSrc, ySrc, wSrc, hSrc, dst, xDst, yDst) tcod.console.blit(src, xSrc, ySrc, wSrc, hSrc, dst, xDst, yDst, foreground_alpha) tcod.console.blit(src, xSrc, ySrc, wSrc, hSrc, dst, xDst, yDst, foreground_alpha, background_alpha)

Cross-fading between two offscreen consoles. We use two offscreen consoles with the same size as the root console. We render a different screen on each offscreen console. When the user hits a key, we do a cross-fading from the first screen to the second screen.

TCODConsole *off1 = new TCODConsole(80,50); TCODConsole *off2 = new TCODConsole(80,50); … print screen1 on off1 … print screen2 of off2 render screen1 in the game window TCODConsole::blit(off1,0,0,80,50,TCODConsole::root,0,0); TCODConsole::flush(); wait or a keypress TCODConsole::waitForKeypress(true); do a cross-fading from off1 to off2 for (int i=1; i <= 255; i++) { TCODConsole::blit(off1,0,0,80,50,TCODConsole::root,0,0); // renders the first screen (opaque) TCODConsole::blit(off2,0,0,80,50,TCODConsole::root,0,0,i/255.0,i/255.0); // renders the second screen (transparent) TCODConsole::flush(); }

TCOD_console_t off1 = TCOD_console_new(80,50); TCOD_console_t off2 = TCOD_console_new(80,50); int i; … print screen1 on off1 … print screen2 of off2 render screen1 in the game window TCOD_console_blit(off1,0,0,80,50,NULL,0,0,1.0,1.0); TCOD_console_flush(); wait or a keypress TCOD_console_wait_for_keypress(true); do a cross-fading from off1 to off2 for (i=1; i <= 255; i++) { TCOD_console_blit(off1,0,0,80,50,NULL,0,0,1.0,1.0); // renders the first screen (opaque) TCOD_console_blit(off2,0,0,80,50,NULL,0,0,i/255.0,i/255.0); // renders the second screen (transparent) TCOD_console_flush(); }

off1 = libtcod.console_new(80,50) off2 = libtcod.console_new(80,50) … print screen1 on off1 … print screen2 of off2 render screen1 in the game window

libtcod.console_blit(off1,0,0,80,50,0,0,0) libtcod.console_flush() wait or a keypress

libtcod.console_wait_for_keypress(True) do a cross-fading from off1 to off2

for i in range(1,256) : libtcod.console_blit(off1,0,0,80,50,0,0,0) # renders the first screen (opaque) libtcod.console_blit(off2,0,0,80,50,0,0,0,i/255.0,i/255.0) # renders the second screen (transparent) libtcod.console_flush()

&#8212; Cross-fading between two offscreen consoles. We use two offscreen consoles with the same size as the root console. We render a different screen on each offscreen console. When the user hits a key, we do a cross-fading from the first screen to the second screen. off1 = tcod.Console(80,50) off2 = tcod.Console(80,50) … print screen1 on off1 … print screen2 of off2 &#8212; render screen1 in the game window root=libtcod.TCODConsole_root tcod.console.blit(off1,0,0,80,50,root,0,0) tcod.console.flush() &#8212; wait or a keypress tcod.console.waitForKeypress(true) &#8212; do a cross-fading from off1 to off2 for i=1,255,1 do tcod.console.blit(off1,0,0,80,50,root,0,0) &#8212; renders the first screen (opaque) tcod.console.blit(off2,0,0,80,50,root,0,0,i/255,i/255) &#8212; renders the second screen (transparent) tcod.console.flush() end

Parameters:

• src – The source console that must be blitted on another one.

• xSrc, ySrc, wSrc, hSrc – The rectangular area of the source console that will be blitted. If wSrc and/or hSrc == 0, the source console width/height are used

• dst – The destination console.

• xDst, yDst – Where to blit the upper-left corner of the source area in the destination console.

• foregroundAlpha, backgroundAlpha – Alpha transparency of the blitted console. 0.0 => The source console is completely transparent. This function does nothing. 1.0 => The source console is opaque. Its cells replace the destination cells. 0 < fade < 1.0 => The source console is partially blitted, simulating real transparency.

static void setKeyboardRepeat(int initialDelay, int interval)

Use this function to destroy an offscreen console and release any resources allocated.

Don’t use it on the root console.

TCODConsole *off1 = new TCODConsole(80,50); … use off1 delete off1; // destroy the offscreen console

TCOD_console_t off1 = TCOD_console_new(80,50); … use off1 TCOD_console_delete(off1); // destroy the offscreen console

off1 = libtcod.console_new(80,50) … use off1 libtcod.console_delete(off1) # destroy the offscreen console

off1 = tcod.Console(80,50) … use off1 off1=nil &#8212; release the reference

Parameters:

con – in the C and Python versions, the offscreen console handler

static void disableKeyboardRepeat()

static const char *getColorControlString(TCOD_colctrl_t ctrl)

static const char *getRGBColorControlString(TCOD_colctrl_t ctrl, const TCODColor &col)

Public Static Attributes

static TCODConsole *root

Class TCODDijkstra

• Defined in File path.hpp

Nested Relationships

Nested Types

• Struct TCODDijkstra::WrapperData

Class Documentation

class TCODDijkstra

Public Functions

TCODDijkstra(TCODMap *map, float diagonalCost = 1.41f)

TCODDijkstra(int width, int height, const ITCODPathCallback *listener, void *userData, float diagonalCost = 1.41f)

TCODDijkstra(const TCODDijkstra&) = delete

TCODDijkstra &operator=(const TCODDijkstra&) = delete

inline TCODDijkstra(TCODDijkstra &&rhs) noexcept

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

~TCODDijkstra(void)

void compute(int rootX, int rootY)

In case of Dijkstra, this works in a slightly different way. In order to be able to compute a path, Dijkstra must first analyze the distances from the selected root (origin) node to all other nodes:

@noop path_compute

Parameters:

• dijkstra – In the C version, the path handler returned by a creation function.

• root_x, root_y – Coordinates of the root node (origin) of the path. The coordinates should be inside the map, at a walkable position. Otherwise, the function’s behaviour will be undefined.

bool setPath(int toX, int toY)

After the map is analyzed and all the distances from the root node are known, an unlimited number of paths can be set, all originating at the root node, using: The path setting function will return true if there’s a path from the root node to the destination node. Otherwise, it will return false.

@noop path_compute

TCODMap *myMap = new TCODMap(50,50); TCODDijkstra *dijkstra = new TCODDijkstra(myMap); // allocate the path dijkstra->compute(25,25); // calculate distance from 25,25 to all other nodes dijkstra->setPath(5,5); // calculate a path to node 5,5 dijkstra->setPath(45,45); //calculate another path from the same origin

TCOD_map_t my_map=TCOD_map_new(50,50); TCOD_dijkstra_t dijkstra = TCOD_dijkstra_new(my_map); TCOD_dijkstra_compute(dijkstra,25,25); TCOD_dijkstra_path_set(dijkstra,5,5); TCOD_dijkstra_path_set(dijkstra,45,45);

my_map=libtcod.map_new(50,50) dijkstra = libtcod.dijkstra_new(my_map) libtcod.dijkstra_compute(dijkstra,25,25) libtcod.dijkstra_path_set(dijkstra,5,5) libtcod.dijkstra_path_set(dijkstra,45,45)

Parameters:

• dijkstra – In the C version, the path handler returned by a creation function.

• to_x, to_y – Coordinates of the destination node of the path.

float getDistance(int x, int y)

You can get the distance of any set of coordinates from the root node: Note that if the coordinates x,y are outside of the map or are a non-walkable position, the function will return -1.0f. This functionality is only available for Dijkstra’s algorithm.

@noop path_read

Parameters:

• dijkstra – In the C version, the path handler returned by a creation function.

• x, y – The coordinates whose distance from the root node are to be checked

bool walk(int *x, int *y)

bool isEmpty() const

void reverse()

int size() const

void get(int index, int *x, int *y) const

Class TCODHeightMap

• Defined in File heightmap.hpp

Class Documentation

class TCODHeightMap

This toolkit allows one to create a 2D grid of float values using various algorithms.

The code using the heightmap toolkit can be automatically generated with the heightmap tool (hmtool) included in the libtcod package.

Public Functions

TCODHeightMap(int width, int height)

As with other modules, you have to create a heightmap object first : Note that whereas most other modules use opaque structs, the TCOD_heightmap_t fields can be freely accessed.

Thus, the TCOD_heightmap_new function returns a TCOD_heightmap_t pointer, not a TCOD_heightmap_t. The w and h fields should not be modified after the heightmap creation. The newly created heightmap is filled with 0.0 values.

typedef struct { int w,h; float *values; } TCOD_heightmap_t; TCOD_heightmap_t *TCOD_heightmap_new(int w,int h)

map=libtcod.heightmap_new(50,50) print map.w, map.h

Parameters:

w, h – The width and height of the heightmap.

virtual ~TCODHeightMap()

To release the resources used by a heightmap, destroy it with :

Parameters:

hm – In the C version, the address of the heightmap struct returned by the creation function.

inline void setValue(int x, int y, float v)

Once the heightmap has been created, you can do some basic operations on the values inside it. You can set a single value :

Those are simple operations applied either on a single map cell or on every map cell.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• x, y – Coordinates of the cells to modify inside the map. 0 <= x < map width 0 <= y < map height

• value – The new value of the map cell.

void add(float f)

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• value – Value to add to every cell.

void scale(float f)

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• value – Every cell’s value is multiplied by this value.

void clear()

Parameters:

hm – In the C version, the address of the heightmap struct returned by the creation function.

void clamp(float min, float max)

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• min, max – Every cell value is clamped between min and max. min < max

void copy(const TCODHeightMap *source)

Parameters:

• source – Each cell value from the source heightmap is copied in the destination (this for C++) heightmap. The source and destination heightmap must have the same width and height.

• dest – In the C and Python versions, the address of the destination heightmap.

void normalize(float newMin = 0.0f, float newMax = 1.0f)

void TCODHeightMap::normalize() void TCODHeightMap::normalize(float min) void TCODHeightMap::normalize(float min, float max)

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• min, max – The whole heightmap is translated and scaled so that the lowest cell value becomes min and the highest cell value becomes max min < max

void lerp(const TCODHeightMap *a, const TCODHeightMap *b, float coef)

Parameters:

• a – First heightmap in the lerp operation.

• b – Second heightmap in the lerp operation.

• coef – lerp coefficient. For each cell in the destination map (this for C++), value = a.value + (b.value - a.value) * coef

• res – In the C and Python versions, the address of the destination heightmap.

void add(const TCODHeightMap *a, const TCODHeightMap *b)

Parameters:

• a – First heightmap.

• b – Second heightmap. For each cell in the destination map (this for C++), value = a.value + b.value

• res – In the C and Python versions, the address of the destination heightmap.

void multiply(const TCODHeightMap *a, const TCODHeightMap *b)

Parameters:

• a – First heightmap.

• b – Second heightmap. For each cell in the destination map (this for C++), value = a.value * b.value

• res – In the C and Python versions, the address of the destination heightmap.

void addHill(float x, float y, float radius, float height)

This function adds a hill (a half spheroid) at given position.

Those are advanced operations involving several or all map cells.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• x, y – Coordinates of the center of the hill. 0 <= x < map width 0 <= y < map height

• radius – The hill radius.

• height – The hill height. If height == radius or -radius, the hill is a half-sphere.

void digHill(float hx, float hy, float h_radius, float height)

This function takes the highest value (if height > 0) or the lowest (if height < 0) between the map and the hill.

It’s main goal is to carve things in maps (like rivers) by digging hills along a curve.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• x, y – Coordinates of the center of the hill. 0 <= x < map width 0 <= y < map height

• radius – The hill radius.

• height – The hill height. Can be < 0 or > 0

void rainErosion(int nbDrops, float erosionCoef, float sedimentationCoef, TCODRandom *rnd)

This function simulates the effect of rain drops on the terrain, resulting in erosion patterns.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• nbDrops – Number of rain drops to simulate. Should be at least width * height.

• erosionCoef – Amount of ground eroded on the drop’s path.

• sedimentationCoef – Amount of ground deposited when the drops stops to flow

• rnd – RNG to use, NULL for default generator.

void kernelTransform(int kernelSize, const int *dx, const int *dy, const float *weight, float minLevel, float maxLevel)

This function allows you to apply a generic transformation on the map, so that each resulting cell value is the weighted sum of several neighbour cells.

This can be used to smooth/sharpen the map. See examples below for a simple horizontal smoothing kernel : replace value(x,y) with 0.33*value(x-1,y) + 0.33*value(x,y) + 0.33*value(x+1,y).To do this, you need a kernel of size 3 (the sum involves 3 surrounding cells). The dx,dy array will contain : dx=-1,dy = 0 for cell x-1,y dx=1,dy=0 for cell x+1,y dx=0,dy=0 for current cell (x,y) The weight array will contain 0.33 for each cell.

int dx [] = {-1,1,0}; int dy[] = {0,0,0}; float weight[] = {0.33f,0.33f,0.33f}; TCOD_heightMap_kernel_transform(heightmap,3,dx,dy,weight,0.0f,1.0f);

int dx [] = {-1,1,0}; int dy[] = {0,0,0}; float weight[] = {0.33f,0.33f,0.33f}; heightmap->kernelTransform(heightmap,3,dx,dy,weight,0.0f,1.0f);

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function. kernelSize Number of neighbour cells involved.

• dx, dy – Array of kernelSize cells coordinates. The coordinates are relative to the current cell (0,0) is current cell, (-1,0) is west cell, (0,-1) is north cell, (1,0) is east cell, (0,1) is south cell, …

• weight – Array of kernelSize cells weight. The value of each neighbour cell is scaled by its corresponding weight

• minLevel – The transformation is only applied to cells which value is >= minLevel.

• maxLevel – The transformation is only applied to cells which value is <= maxLevel.

void addVoronoi(int nbPoints, int nbCoef, const float *coef, TCODRandom *rnd)

This function adds values from a Voronoi diagram to the map.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• nbPoints – Number of Voronoi sites.

• nbCoef – The diagram value is calculated from the nbCoef closest sites.

• coef – The distance to each site is scaled by the corresponding coef. Closest site : coef[0], second closest site : coef[1], …

• rnd – RNG to use, NULL for default generator.

void addFbm(TCODNoise *noise, float mul_x, float mul_y, float add_x, float add_y, float octaves, float delta, float scale)

This function adds values from a simplex fbm function to the map.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• noise – The 2D noise to use.

• mul_x, mul_y – / add_x, add_y The noise coordinate for map cell (x,y) are (x + add_x)*mul_x / width , (y + add_y)*mul_y / height. Those values allow you to scale and translate the noise function over the heightmap.

• octaves – Number of octaves in the fbm sum.

• delta – / scale The value added to the heightmap is delta + noise * scale.

• noise – is between -1.0 and 1.0

void scaleFbm(TCODNoise *noise, float mul_x, float mul_y, float add_x, float add_y, float octaves, float delta, float scale)

This function works exactly as the previous one, but it multiplies the resulting value instead of adding it to the heightmap.

void digBezier(int px[4], int py[4], float startRadius, float startDepth, float endRadius, float endDepth)

This function carve a path along a cubic Bezier curve using the digHill function.

Could be used for roads/rivers/… Both radius and depth can vary linearly along the path.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• px, py – The coordinates of the 4 Bezier control points.

• startRadius – The path radius in map cells at point P0. Might be < 1.0

• startDepth – The path depth at point P0.

• endRadius – The path radius in map cells at point P3. Might be < 1.0

• endDepth – The path depth at point P3.

inline float getValue(int x, int y) const

This function returns the height value of a map cell.

Those functions return raw or computed information about the heightmap.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• x, y – Coordinates of the map cell. 0 <= x < map width 0 <= y < map height

float getInterpolatedValue(float x, float y) const

This function returns the interpolated height at non integer coordinates.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• x, y – Coordinates of the map cell. 0 <= x < map width 0 <= y < map height

float getSlope(int x, int y) const

This function returns the slope between 0 and PI/2 at given coordinates.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• x, y – Coordinates of the map cell. 0 <= x < map width 0 <= y < map height

void getNormal(float x, float y, float n[3], float waterLevel = 0.0f) const

This function returns the map normal at given coordinates.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• x, y – Coordinates of the map cell. 0 <= x < map width 0 <= y < map height

• n – The function stores the normalized normal vector in this array.

• waterLevel – The map height is clamped at waterLevel so that the sea is flat.

int countCells(float min, float max) const

This function returns the number of map cells which value is between min and max.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• min, max – Only cells which value is >=min and <= max are counted.

bool hasLandOnBorder(float waterLevel) const

This function checks if the cells on the map border are below a certain height.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• waterLevel – Return true only if no border cell is > waterLevel.

void getMinMax(float *min, float *max) const

This function calculates the min and max of all values inside the map.

Parameters:

• hm – In the C version, the address of the heightmap struct returned by the creation function.

• min, max – The min and max values are returned in these variables.

void midPointDisplacement(TCODRandom *rnd = NULL, float roughness = 0.45f)

This algorithm generates a realistic fractal heightmap using the diamond-square (or random midpoint displacement) algorithm.

The roughness range should be comprised between 0.4 and 0.6. The image below show the same map with roughness varying from 0.4 to 0.6.

It’s also a good habit to normalize the map after using this algorithm to avoid unexpected heights.

Parameters:

• hm – In the C and Python version, the address of the heightmap struct returned by the creation function.

• rng – Random number generation to use, or NULL/0 to use the default one.

• roughness – Map roughness.

void islandify(float seaLevel, TCODRandom *rnd)

Public Members

int w

int h

float *values

Class TCODImage

• Defined in File image.hpp

Class Documentation

class TCODImage

Public Functions

TCODImage() noexcept = default

Default constructs an image. This will be in a partially invalid state until assigned a real image.

This toolkit contains some image manipulation utilities.

TCODImage(int width, int height)

You can create an image of any size, filled with black with this function.

Parameters:

width, height – Size of the image in pixels.

TCODImage(const char *filename)

You can read data from a .bmp or .png file (for example to draw an image using the background color of the console cells).

Note that only 24bits and 32bits PNG files are currently supported.

Parameters:

filename – Name of the .bmp or .png file to load.

TCODImage(const TCODConsole *console)

You can create an image from any console (either the root console or an offscreen console).

The image size will depend on the console size and the font characters size. You can then save the image to a file with the save function.

Parameters:

console – The console to convert. In the C version, use NULL for the root console.

inline TCODImage(tcod::ImagePtr image) noexcept

Take ownership of an image pointer.

New in version 1.24.

TCODImage(const TCODImage&) = delete

TCODImage &operator=(const TCODImage&) = delete

inline TCODImage(TCODImage &&rhs) noexcept

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

inline explicit TCODImage(const tcod::Matrix<TCOD_ColorRGB, 2> &pixels)

Construct a new TCODImage object from a Matrix of pixels.

This constructor is provisional.

Parameters:

pixels – A 2D matrix of RGB pixels.

void refreshConsole(const TCODConsole *console)

If you need to refresh the image with the console’s new content, you don’t have to delete it and create another one.

Instead, use this function. Note that you must use the same console that was used in the TCOD_image_from_console call (or at least a console with the same size).

TCODImage *pix = new TCODImage(TCODConsole::root); // create an image from the root console … modify the console pix->refreshConsole(TCODConsole::root); // update the image with the console’s new content

TCOD_image_t pix = TCOD_image_from_console(NULL); … modify the console .. TCOD_image_refresh_console(pix,NULL);

pix = libtcod.image_from_console(0) … modify the console ..

libtcod.image_refresh_console(pix,0)

Parameters:

• image – In the C version, the image created with TCOD_image_from_console.

• console – The console to capture. In the C version, use NULL for the root console.

void getSize(int *w, int *h) const

You can read the size of an image in pixels with this function.

TCODImage *pix = new TCODImage(80,50); int w,h; pix->getSize(&w,&h); // w = 80, h = 50

TCOD_image_t pix = TCOD_image_new(80,50); int w,h; TCOD_image_get_size(pix,&w,&h); // w = 80, h = 50

pix = libtcod.image_new(80,50) w,h=libtcod.image_get_size(pix) w = 80, h = 50

Parameters:

• image – In the C version, the image handler, obtained with the load function.

• w, h – When the function returns, those variables contain the size of the image.

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

Get the {width, height} of this image.

New in version 1.24.

TCODColor getPixel(int x, int y) const

You can read the colors from an image with this function.

TCODImage *pix = new TCODImage(80,50); TCODColor col=pix->getPixel(40,25);

TCOD_image_t pix = TCOD_image_new(80,50); TCOD_color_t col=TCOD_image_get_pixel(pix,40,25);

pix = libtcod.image_new(80,50) col=libtcod.image_get_pixel(pix,40,25)

Parameters:

• image – In the C and Python version, the image handler, obtained with the load function.

• x, y – The pixel coordinates inside the image. 0 <= x < width 0 <= y < height

int getAlpha(int x, int y) const

If you have set a key color for this image with setKeyColor, or if this image was created from a 32 bits PNG file (with alpha layer), you can get the pixel transparency with this function.

This function returns a value between 0 (transparent pixel) and 255 (opaque pixel).

Parameters:

• image – In the C and Python version, the image handler, obtained with the load function.

• x, y – The pixel coordinates inside the image. 0 <= x < width 0 <= y < height

bool isPixelTransparent(int x, int y) const

You can use this simpler version (for images with alpha layer, returns true only if alpha == 0) :

Parameters:

• image – In the C and Python version, the image handler, obtained with the load function.

• x, y – The pixel coordinates inside the image. 0 <= x < width 0 <= y < height

TCODColor getMipmapPixel(float x0, float y0, float x1, float y1)

This method uses mipmaps to get the average color of an arbitrary rectangular region of the image.

It can be used to draw a scaled-down version of the image. It’s used by libtcod’s blitting functions.

Get the average color of a 5x5 “superpixel” in the center of the image. TCODImage *pix = new TCODImage(80,50); TCODColor col=pix->getMipMapPixel(37.5f, 22.5f, 42.5f, 28.5f);

TCOD_image_t pix = TCOD_image_new(80,50); TCOD_color_t col=TCOD_image_get_mipmap_pixel(pix,37.5f, 22.5f, 42.5f, 28.5f);

pix = libtcod.image_new(80,50) col=libtcod.image_get_mipmap_pixel(pix,37.5, 22.5, 42.5, 28.5)

Parameters:

• image – In the C version, the image handler, obtained with the load function.

• x0, y0 – Coordinates in pixels of the upper-left corner of the region. 0.0 <= x0 < x1 0.0 <= y0 < y1

• x1, y1 – Coordinates in pixels of the lower-right corner of the region. x0 < x1 < width y0 < y1 < height

void clear(const TCODColor col)

You can fill the whole image with a color with :

Parameters:

• image – In the C and Python version, the image to fill.

• color – The color to use.

void putPixel(int x, int y, const TCODColor col)

Parameters:

• image – In the C version, the image handler, obtained with the load function.

• x, y – The pixel coordinates inside the image. 0 <= x < width 0 <= y < height

• col – The new color of the pixel.

void scale(int new_w, int new_h)

You can resize an image and scale its content.

If new_w < old_w or new_h < old_h, supersampling is used to scale down the image. Else the image is scaled up using nearest neighbor.

Parameters:

• image – In the C and Python version, the image handler, obtained with the load function.

• new_w, new_h – The new size of the image.

void hflip()

Parameters:

image – In the C and Python version, the image handler, obtained with the load function.

void vflip()

Parameters:

image – In the C and Python version, the image handler, obtained with the load function.

void rotate90(int numRotations = 1)

Rotate the image clockwise by increment of 90 degrees.

Parameters:

• image – In the C and Python version, the image handler, obtained with the load function.

• numRotations – Number of 90 degrees rotations. Should be between 1 and 3.

void invert()

Parameters:

image – In the C and Python version, the image handler, obtained with the load function.

void save(const char *filename) const

You can save an image to a 24 bits .bmp or .png file.

TCODImage *pix = new TCODImage(10,10); pix->save(“mypic.bmp”);

TCOD_image_t pix = TCOD_image_from_console(my_offscreen_console); TCOD_image_save(pix,”mypic.bmp”);

pix = libtcod.image_from_console(my_offscreen_console) libtcod.image_save(pix,”mypic.bmp”)

Parameters:

• image – In the C version, the image handler, obtained with any image creation function.

• filename – Name of the .bmp or .png file.

void blitRect(TCODConsole *console, int x, int y, int w = -1, int h = -1, TCOD_bkgnd_flag_t bkgnd_flag = TCOD_BKGND_SET) const

This function blits a rectangular part of the image on a console without scaling it or rotating it.

Each pixel of the image fills a console cell.

void TCODImage::blitRect(TCODConsole console, int x, int y) void TCODImage::blitRect(TCODConsole console, int x, int y, int w) void TCODImage::blitRect(TCODConsole console, int x, int y, int w, int h) void TCODImage::blitRect(TCODConsole console, int x, int y, int w, int h, TCODBackgroundFlag bkgnd_flag)

Parameters:

• image – In the C version, the image handler, obtained with the load function.

• console – The console on which the image will be drawn. In the C version, use NULL for the root console.

• x, y – Coordinates in the console of the upper-left corner of the image.

• w, h – Dimension of the image on the console. Use -1,-1 to use the image size.

• flag – This flag defines how the cell’s background color is modified. See TCOD_bkgnd_flag_t.

inline void blitRect(TCOD_Console &console, int x, int y, int w = -1, int h = -1, TCOD_bkgnd_flag_t bkgnd_flag = TCOD_BKGND_SET) const

void blit(TCODConsole *console, float x, float y, TCOD_bkgnd_flag_t bkgnd_flag = TCOD_BKGND_SET, float scale_x = 1.0f, float scale_y = 1.0f, float angle = 0.0f) const

This function allows you to specify the floating point coordinates of the center of the image, its scale and its rotation angle.

void TCODImage::blit(TCODConsole console, float x, float y) void TCODImage::blit(TCODConsole console, float x, float y, TCODBackgroundFlag bkgnd_flag) void TCODImage::blit(TCODConsole console, float x, float y, TCODBackgroundFlag bkgnd_flag, float scale_x) void TCODImage::blit(TCODConsole console, float x, float y, TCODBackgroundFlag bkgnd_flag, float scale_x, float scale_y) void TCODImage::blit(TCODConsole console, float x, float y, TCODBackgroundFlag bkgnd_flag, float scale_x, float scale_y, float angle)

Parameters:

• image – In the C version, the image handler, obtained with the load function.

• console – The console on which the image will be drawn. In the C version, use NULL for the root console.

• x, y – Coordinates in the console of the center of the image.

• flag – This flag defines how the cell’s background color is modified. See TCOD_bkgnd_flag_t.

• scale_x, scale_y – Scale coefficient. Must be > 0.0.

• angle – Rotation angle in radians.

inline void blit(TCOD_Console &console, float x, float y, TCOD_bkgnd_flag_t bkgnd_flag = TCOD_BKGND_SET, float scale_x = 1.0f, float scale_y = 1.0f, float angle = 0.0f) const

void setKeyColor(const TCODColor keyColor)

When blitting an image, you can define a key color that will be ignored by the blitting function.

This makes it possible to blit non rectangular images or images with transparent pixels.

TCODImage *pix = TCODImage(“mypix.bmp”); pix->setKeyColor(TCODColor::red); blitting the image, omitting red pixels pix->blitRect(TCODConsole::root,40,25);

TCOD_image_t pix = TCOD_image_new(10,10); TCOD_image_set_key_color(pix,TCOD_red); TCOD_image_blit_rect(pix,NULL,40,25,5,5,TCOD_BKGND_SET);

pix = libtcod.image_new(10,10) libtcod.image_set_key_color(pix,libtcod.red) libtcod.image_blit_rect(pix,0,40,25,5,5,libtcod.BKGND_SET)

Parameters:

• image – In the C and Python version, the image handler, obtained with the load function.

• color – Pixels with this color will be skipped by blitting functions.

void blit2x(TCODConsole *dest, int dx, int dy, int sx = 0, int sy = 0, int w = -1, int h = -1) const

Eventually, you can use some special characters in the libtcod fonts :

to double the console resolution using this blitting function.

Comparison before/after subcell resolution in TCOD :

Pyromancer ! screenshot, making full usage of subcell resolution :

void TCODImage::blit2x(TCODConsole dest, int dx, int dy); void TCODImage::blit2x(TCODConsole dest, int dx, int dy, int sx); void TCODImage::blit2x(TCODConsole dest, int dx, int dy, int sx, int sy); void TCODImage::blit2x(TCODConsole dest, int dx, int dy, int sx, int sy, int w); void TCODImage::blit2x(TCODConsole dest, int dx, int dy, int sx, int sy, int w, int h);

Parameters:

• image – In the C and Python version, the image handler, obtained with the load function.

• dest – The console of which the image will be blitted. Foreground, background and character data will be overwritten.

• dx, dy – Coordinate of the console cell where the upper left corner of the blitted image will be.

• sx, sy, w, h – Part of the image to blit. Use -1 in w and h to blit the whole image.

inline void blit2x(TCOD_Console &dest, int dx, int dy, int sx = 0, int sy = 0, int w = -1, int h = -1) const

inline TCOD_Image *get_data() noexcept

Return the pointer to this objects TCOD_Image data.

New in version 1.17.

inline const TCOD_Image *get_data() const noexcept

Return the const pointer to this objects TCOD_Image data.

New in version 1.17.

inline TCODImage(TCOD_image_t img)

virtual ~TCODImage()

inline operator TCOD_Image&()

Allow implicit conversions to TCOD_Image&.

New in version 1.19.

inline operator const TCOD_Image&() const

Allow implicit conversions to const TCOD_Image&.

New in version 1.19.

Protected Attributes

struct TCOD_Image *data = {nullptr}

bool deleteData = {false}

Class TCODLine

• Defined in File bresenham.hpp

Class Documentation

class TCODLine

Public Static Functions

static void init(int xFrom, int yFrom, int xTo, int yTo)

First, you have to initialize the toolkit with your starting and ending coordinates.

This toolkit is a very simple and lightweight implementation of the bresenham line drawing algorithm. It allows you to follow straight paths on your map very easily.

Parameters:

• xFrom, yFrom – Coordinates of the line’s starting point.

• xTo, yTo – Coordinates of the line’s ending point.

static bool step(int *xCur, int *yCur)

You can then step through each cell with this function.

It returns true when you reach the line’s ending point.

Going from point 5,8 to point 13,4 int x = 5, y = 8; TCODLine::init(x,y,13,4); do { update cell x,y } while (!TCODLine::step(&x,&y));

int x = 5, y = 8; TCOD_line_init(x,y,13,4); do { update cell x,y } while (!TCOD_line_step(&x,&y));

libtcod.line_init(5,8,13,4) update cell 5,8

x,y=libtcod.line_step() while (not x is None) : update cell x,y

x,y=libtcod.line_step()

x=5 y=8 tcod.line.init(x,y,13,4) repeat &#8212; update cell x,y lineEnd,x,y = tcod.line.step(x,y) until lineEnd

Parameters:

xCur, yCur – the coordinates of the next cell on the line are stored here when the function returns

static bool line(int xFrom, int yFrom, int xTo, int yTo, TCODLineListener *listener)

The function returns false if the line has been interrupted by the callback (it returned false before the last point).

class TCODLIB_API TCODLineListener { virtual bool putPoint (int x, int y) = 0; }; static bool TCODLine::line (int xFrom, int yFrom, int xTo, int yTo, TCODLineListener * listener)

typedef bool (*TCOD_line_listener_t) (int x, int y); bool TCOD_line(int xFrom, int yFrom, int xTo, int yTo, TCOD_line_listener_t listener)

def line_listener(x,y) : # … line(xFrom, yFrom, xTo, yTo, listener)

class MyLineListener : public TCODLineListener { public: bool putPoint (int x,int y) { printf (“%d %d\n”,x,y); return true; } }; MyLineListener myListener; TCODLine::line(5,8,13,4,&myListener);

printf (“%d %d\n”,x,y); return true; } TCOD_line_line(5,8,13,4,my_listener);

print x,y return True libtcod.line_line(5,8,13,4,my_listener)

Parameters:

• xFrom, yFrom – Coordinates of the line’s starting point.

• xTo, yTo – Coordinates of the line’s ending point.

• listener – Callback called for each line’s point. The function stops if the callback returns false.

Class TCODLineListener

• Defined in File bresenham.hpp

Class Documentation

class TCODLineListener

Public Functions

virtual bool putPoint(int x, int y) = 0

inline virtual ~TCODLineListener()

Template Class TCODList

• Defined in File list.hpp

Class Documentation

template<class T>
class TCODList

This is a fast, lightweight and generic container, that provides array, list and stack paradigms. Note that this module has no Python wrapper. Use Python built-in containers instead.

Public Functions

TCODList() = default

You can create an empty list with the default constructor.

The C version returns a handler on the list.

TCODList<int> intList; TCODList<float> *floatList = new TCODList<float>();

TCOD_list_t intList = TCOD_list_new(); TCOD_list_t floatList = TCOD_list_new();

inline TCODList(const TCOD_list_t l)

You can create a list by duplicating an existing list.

TCODList<int> intList; intList.push(3); intList.push(5); TCODList<int> intList2(intList); // intList2 contains two elements : 3 and 5

TCOD_list_t intList = TCOD_list_new(); TCOD_list_push(intList,(const void *)3); TCOD_list_push(intList,(const void *)5); TCOD_list_t intList2 = TCOD_list_duplicate(intList); // intList2 contains two elements : 3 and 5

Parameters:

l – Existing list to duplicate.

inline TCODList(const TCODList<T> &rhs)

inline TCODList<T> &operator=(const TCODList<T> &rhs)

inline TCODList(TCODList &&rhs) noexcept

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

inline virtual ~TCODList()

You can delete a list, freeing any allocated resources.

Note that deleting the list does not delete it’s elements. You have to use clearAndDelete before deleting the list if you want to destroy the elements too.

TCODList<int> *intList = new TCODList<int>(); // allocate a new empty list intList->push(5); // the list contains 1 element at position 0, value = 5 delete intList; // destroy the list

TCOD_list_t intList = TCOD_list_new(); TCOD_list_push(intList,(const void *)5); TCOD_list_delete(intList);

Parameters:

l – In the C version, the list handler, returned by a constructor.

inline TCODList(int nbElements)

You can also create an empty list and pre-allocate memory for elements.

Use this if you know the list size and want the memory to fit it perfectly.

Parameters:

nbElements – Allocate memory for nbElements.

inline void set(const T elt, int idx)

You can assign a value with set.

If needed, the array will allocate new elements up to idx.

TCODList<int> intList; // the array is empty (contains 0 elements) intList.set(5,0); // the array contains 1 element at position 0, value = 5 intList.set(7,2); // the array contains 3 elements : 5, 0, 7

TCOD_list_t intList = TCOD_list_new(); TCOD_list_set(intList,(const void *)5,0); TCOD_list_set(intList,(const void *)7,2);

Parameters:

• elt – Element to put in the array.

• idx – Index of the element. 0 <= idx

• l – In the C version, the handler, returned by a constructor.

inline T get(int idx) const

You can retrieve a value with get.

TCODList<int> intList; intList.set(5,0); int val = intList.get(0); // val == 5

TCOD_list_t intList = TCOD_list_new(); TCOD_list_set(intList,(const void *)5,0); int val = (int)TCOD_list_get(intList,0); // val == 5

Parameters:

• idx – Index of the element. 0 <= idx < size of the array

• l – In the C version, the handler, returned by a constructor.

inline bool isEmpty() const

TCODList<int> intList; bool empty=intList.isEmpty(); // empty == true intList.set(3,0); empty=intList.isEmpty(); // empty == false

TCOD_list_t intList = TCOD_list_new(); bool empty=TCOD_list_is_empty(intList); // empty == true TCOD_list_set(intList,(const void *)5,0); empty=TCOD_list_is_empty(intList); // empty == false

Parameters:

l – In the C version, the handler, returned by a constructor.

inline int size() const

TCODList<int> intList; int size=intList.size(); // size == 0 intList.set(3,0); size=intList.size(); // size == 1

TCOD_list_t intList = TCOD_list_new(); int size=TCOD_list_size(intList); // size == 0 TCOD_list_set(intList,(const void *)5,0); size=TCOD_list_size(intList); // size == 1

Parameters:

l – In the C version, the handler, returned by a constructor.

inline bool contains(const T elt) const

TCODList<int> intList; intList.set(3,0); bool has3 = intList.contains(3); // has3 == true bool has4 = intList.contains(4); // has4 == false

TCOD_list_t intList = TCOD_list_new(); TCOD_list_set(intList,(const void *)3,0); bool has3 = TCOD_list_contains(intList,(const void *)3); // has3 == true bool has4 = TCOD_list_contains(intList,(const void *)4); // has4 == false

Parameters:

• elt – The element.

• l – In the C version, the handler, returned by a constructor.

inline T *insertBefore(const T elt, int before)

TCODList<int> intList; // the list is empty (contains 0 elements) intList.set(0,5); // the list contains 1 element at position 0, value = 5 intList.insertBefore(2,0); // the list contains 2 elements : 2,5

TCOD_list_t intList = TCOD_list_new(); TCOD_list_set(intList,0,(const void *)5); TCOD_list_insert_before(intList,(const void *)2,0);

Parameters:

• elt – Element to insert in the list.

• idx – Index of the element after the insertion. 0 <= idx < list size

• l – In the C version, the list handler, returned by a constructor.

inline void remove(const T elt)

The _fast versions replace the element to remove with the last element of the list.

They’re faster, but do not preserve the list order.

template <class T> void TCODList::remove(const T elt) template <class T> void TCODList::removeFast(const T elt)

void TCOD_list_remove(TCOD_list_t l, const void * elt) void TCOD_list_remove_fast(TCOD_list_t l, const void * elt)

TCODList<int> intList; // the list is empty (contains 0 elements) intList.set(0,5); // the list contains 1 element at position 0, value = 5 intList.remove(5); // the list is empty

TCOD_list_t intList = TCOD_list_new(); TCOD_list_set(intList,0,(const void *)5); TCOD_list_remove(intList,(const void *)5);

Parameters:

• elt – The element to remove

• l – In the C version, the list handler, returned by a constructor.

inline void removeFast(const T elt)

inline void addAll(const TCODList<T> &l2)

You can concatenate two lists.

Every element of l2 will be added to current list (or l in the C version) :

TCODList<int> intList; intList.set(1,3); // intList contains 2 elements : 0, 3 TCODList<int> intList2; // intList2 is empty intList2.set(0,1); // intList2 contains 1 element : 1 intList2.addAll(intList); // intList2 contains 3 elements : 1, 0, 3

TCOD_list_t intList = TCOD_list_new(); TCOD_list_set(intList,1,(const void *)3); TCOD_list_t intList2 = TCOD_list_new(); TCOD_list_set(intList2,0,(const void *)1); TCOD_list_add_all(intList2,intList);

Parameters:

• l – The list inside which elements will be added.

• l2 – the list handler containing elements to insert.

inline void clear()

TCODList<int> intList; intList.set(0,3); // intList contains 1 element intList.clear(); // intList is empty

TCOD_list_t intList = TCOD_list_new(); TCOD_list_set(intList,0,(const void *)5); TCOD_list_clear(intList);

Parameters:

l – In the C version, the list handler, returned by a constructor.

inline void clearAndDelete()

For lists containing pointers, you can clear the list and delete (or free for C) the elements :

TCODList<MyClass *> intList; MyClass * cl=new MyClass(); // new instance of MyClass allocated here intList.set(0,cl); intList.clear(); // the list is empty. cl is always valid intList.set(0,cl); intList.clearAndDelete(); // the list is empty. delete cl has been called. The address cl is no longer valid.

TCOD_list_t intList = TCOD_list_new(); void *data=calloc(10,1); // some memory allocation here TCOD_list_set(intList,0,(const void *)data); TCOD_list_clear(intList); // the list is empty, but data is always valid TCOD_list_set(intList,0,(const void *)data); TCOD_list_clear_and_delete(intList); // the list is empty, free(data) has been called. The address data is no longer valid

Parameters:

l – In the C version, the list handler, returned by a constructor.

inline void reverse()

This function reverses the order of the elements in the list.

void TCODList::reverse()

void TCOD_list_reverse(TCOD_list_t l)

TCODList<int> intList; // the list is empty (contains 0 elements) intList.push(5); // the list contains 1 element at position 0, value = 5 intList.push(2); // the list contains 2 elements : 5,2 intList.reverse(); // now order is 2,5

TCOD_list_t intList = TCOD_list_new(); TCOD_list_push(intList,(const void *)5); TCOD_list_push(intList,(const void *)2); TCOD_list_reverse();

Parameters:

l – In the C version, the list handler, returned by a constructor.

inline void push(const T elt)

You can push an element on the stack (append it to the end of the list) :

TCODList<int> intList; // the list is empty (contains 0 elements) intList.push(5); // the list contains 1 element at position 0, value = 5 intList.push(2); // the list contains 2 elements : 5,2

TCOD_list_t intList = TCOD_list_new(); TCOD_list_push(intList,(const void *)5); TCOD_list_push(intList,(const void *)2);

Parameters:

• elt – Element to append to the list.

• l – In the C version, the list handler, returned by a constructor.

inline T pop()

You can pop an element from the stack (remove the last element of the list).

TCODList<int> intList; // the list is empty (contains 0 elements) intList.push(5); // the list contains 1 element at position 0, value = 5 intList.push(2); // the list contains 2 elements : 5,2 int val = intList.pop(); // val == 2, the list contains 1 element : 5 val = intList.pop(); // val == 5, the list is empty

TCOD_list_t intList = TCOD_list_new(); TCOD_list_push(intList,(const void *)5); TCOD_list_push(intList,(const void *)2); int val = (int)TCOD_list_pop(intList); val = (int)TCOD_list_pop(intList);

Parameters:

l – In the C version, the list handler, returned by a constructor.

inline T peek() const

You can read the last element of the stack without removing it :

TCODList<int> intList; intList.push(3); // intList contains 1 elements : 3 int val = intList.peek(); // val == 3, inList contains 1 elements : 3 intList.push(2); // intList contains 2 elements : 3, 2 val = intList.peek(); // val == 2, inList contains 2 elements : 3, 2

TCOD_list_t intList = TCOD_list_new(); TCOD_list_push(intList,(const void *)3); int val = (int)TCOD_list_peek(intList); TCOD_list_push(intList,(const void *)2); val = (int)TCOD_list_peek(intList);

Parameters:

l – In the C version, the list handler, returned by a constructor.

inline T *begin() const

You can iterate through the elements of the list using an iterator.

begin() returns the address of the first element of the list. You go to the next element using the increment operator ++. When the iterators value is equal to end(), you’ve gone through all the elements. Warning ! You cannot insert elements in the list while iterating through it. Inserting elements can result in reallocation of the list and your iterator will not longer be valid.

template <class T> T * TCODList::begin() const template <class T> T * TCODList::end() const

void ** TCOD_list_begin(TCOD_list_t l) void ** TCOD_list_end(TCOD_list_t l)

TCODList<int> intList; // the list is empty (contains 0 elements) intList.push(5); // the list contains 1 element at position 0, value = 5 intList.push(2); // the list contains 2 elements : 5,2 for ( int * iterator = intList.begin(); iterator != intList.end(); iterator ++ ) { int currentValue=*iterator; printf(“value : %d\n”, currentValue ); }

TCOD_list_t intList = TCOD_list_new(); TCOD_list_push(intList,(const void *)5); TCOD_list_push(intList,(const void *)2); for ( int * iterator = (int *)TCOD_list_begin(intList); iterator != (int *)TCOD_list_end(intList); iterator ++ ) { int currentValue=*iterator; printf(“value : %d\n”, currentValue ); }

Parameters:

l – In the C version, the list handler, returned by a constructor.

inline T *end() const

inline T *remove(T *elt)

You can remove an element from the list while iterating.

The element at the iterator position will be removed. The function returns the new iterator. The _fast versions replace the element to remove with the last element of the list. They’re faster, but do not preserve the list order.

template <class T> T *TCODList::remove(T *iterator) template <class T> T *TCODList::removeFast(T *iterator)

void **TCOD_list_remove_iterator(TCOD_list_t l, void **iterator) void **TCOD_list_remove_iterator_fast(TCOD_list_t l, void **iterator)

TCODList<int> intList; // the list is empty (contains 0 elements) intList.push(5); // the list contains 1 element at position 0, value = 5 intList.push(2); // the list contains 2 elements : 5,2 intList.push(3); // the list contains 3 elements : 5,2,3 for ( int * iterator = intList.begin(); iterator != intList.end(); iterator ++ ) { int currentValue=*iterator; if ( currentValue == 2 ) { remove this value from the list and keep iterating on next element (value == 3) iterator = intList.remove(iterator); } printf(“value : %d\n”, currentValue ); // all 3 values will be printed : 5,2,3 } now the list contains only two elements : 5,3

TCOD_list_t intList = TCOD_list_new(); TCOD_list_push(intList,(const void *)5); TCOD_list_push(intList,(const void *)2); TCOD_list_push(intList,(const void *)3); for ( int * iterator = (int *)TCOD_list_begin(intList); iterator != (int *)TCOD_list_end(intList); iterator ++ ) { int currentValue=*iterator; if ( currentValue == 2 ) { iterator = (int *)TCOD_list_remove_iterator(intList,(void **)iterator); } printf(“value : %d\n”, currentValue ); }

Parameters:

• iterator – The list iterator.

• l – In the C version, the list handler, returned by a constructor.

inline T *removeFast(T *elt)

Protected Functions

inline void allocate()

Friends

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

Class TCODMap

• Defined in File fov.hpp

Class Documentation

class TCODMap

This toolkit allows one to easily calculate the potential visible set of map cells from the player position. A cell is potentially visible if the line of sight from the player to the cell in unobstructed.

Public Functions

TCODMap(int width, int height)

First, you have to allocate a map of the same size as your dungeon.

Parameters:

width, height – The size of the map (in map cells).

TCODMap(const TCODMap&) = delete

TCODMap &operator=(const TCODMap&) = delete

inline TCODMap(TCODMap &&rhs) noexcept

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

void setProperties(int x, int y, bool isTransparent, bool isWalkable)

Then, build your dungeon by defining which cells let the light pass (by default, all cells block the light) and which cells are walkable (by default, all cells are not-walkable).

Parameters:

• map – In the C version, the map handler returned by the TCOD_map_new function.

• x, y – Coordinate of the cell that we want to update.

• isTransparent – If true, this cell will let the light pass else it will block the light.

• isWalkable – If true, creatures can walk true this cell (it is not a wall).

void clear(bool transparent = false, bool walkable = false)

You can clear an existing map (setting all cells to the chosen walkable/transparent values) with:

void TCODMap::clear() void TCODMap::clear(bool transparent) void TCODMap::clear(bool transparent, bool walkable)

Parameters:

• map – In the C version, the map handler returned by the TCOD_map_new function.

• walkable – Whether the cells should be walkable.

• transparent – Whether the cells should be transparent.

void copy(const TCODMap *source)

You can copy an existing map into another.

You have to allocate the destination map first.

TCODMap * map = new TCODMap(50,50); // allocate the map map->setProperties(10,10,true,true); // set a cell as ‘empty’ TCODMap * map2 = new TCODMap(10,10); // allocate another map map2->copy(map); // copy map data into map2, reallocating it to 50x50

TCOD_map_t map = TCOD_map_new(50,50); TCOD_map_t map2 = TCOD_map_new(10,10); TCOD_map_set_properties(map,10,10,true,true); TCOD_map_copy(map,map2);

map = libtcod.map_new(50,50) map2 = libtcod.map_new(10,10) libtcod.map_set_properties(map,10,10,True,True) libtcod.map_copy(map,map2)

Parameters:

• source – The map containing the source data.

• dest – In C and Python version, the map where data is copied.

void computeFov(int playerX, int playerY, int maxRadius = 0, bool light_walls = true, TCOD_fov_algorithm_t algo = FOV_BASIC)

Once your map is allocated and empty cells have been defined, you can calculate the field of view with :

FOV_BASIC : classic libtcod fov algorithm (ray casted from the player to all the cells on the submap perimeter) FOV_DIAMOND : based on this algorithm FOV_SHADOW : based on this algorithm FOV_PERMISSIVE_x : based on this algorithm Permissive has a variable permissiveness parameter. You can either use the constants FOV_PERMISSIVE_x, x between 0 (the less permissive) and 8 (the more permissive), or using the macro FOV_PERMISSIVE(x). FOV_RESTRICTIVE : Mingos’ Restrictive Precise Angle Shadowcasting (MRPAS). Original implementation here. Comparison of the algorithms : Check this.

void TCODMap::computeFov(int playerX, int playerY) void TCODMap::computeFov(int playerX, int playerY, int maxRadius) void TCODMap::computeFov(int playerX, int playerY, int maxRadius,bool light_walls) void TCODMap::computeFov(int playerX, int playerY, int maxRadius,bool light_walls, TCODFOVTypes algo) TCODMap *map = new TCODMap(50,50); // allocate the map map->setProperties(10,10,true,true); // set a cell as ‘empty’ map->computeFov(10,10); // calculate fov from the cell 10x10 (basic raycasting, unlimited range, walls lighting on)

TCOD_map_t map = TCOD_map_new(50,50); TCOD_map_set_properties(map,10,10,true,true); TCOD_map_compute_fov(map,10,10,0,true,FOV_SHADOW); // using shadow casting

map = libtcod.map_new(50,50) libtcod.map_set_properties(map,10,10,True,True) libtcod.map_compute_fov(map,10,10,0,True,libtcod.FOV_PERMISSIVE(2))

Parameters:

• map – In the C version, the map handler returned by the TCOD_map_new function.

• player_x, player_y – Position of the player in the map. 0 <= player_x < map width. 0 <= player_y < map height.

• maxRadius – If > 0, the fov is only computed up to maxRadius cells away from the player. Else, the range is unlimited.

• light_walls – Whether the wall cells near ground cells in fov must be in fov too.

• algo – FOV algorithm to use.

bool isInFov(int x, int y) const

Once your computed the field of view, you can know if a cell is visible with :

TCODMap *map = new TCODMap(50,50); // allocate the map map->setProperties(10,10,true,true); // set a cell as ‘empty’ map->computeFov(10,10); // calculate fov from the cell 10x10 bool visible=map->isInFov(10,10); // is the cell 10x10 visible ?

TCOD_map_t map = TCOD_map_new(50,50); TCOD_map_set_properties(map,10,10,true,true); TCOD_map_compute_fov(map,10,10); bool visible = TCOD_map_is_in_fov(map,10,10);

map = libtcod.map_new(50,50) libtcod.map_set_properties(map,10,10,True,True) libtcod.map_compute_fov(map,10,10) visible = libtcod.map_is_in_fov(map,10,10)

Parameters:

• map – In the C version, the map handler returned by the TCOD_map_new function.

• x, y – Coordinates of the cell we want to check. 0 <= x < map width. 0 <= y < map height.

bool isTransparent(int x, int y) const

You can also retrieve transparent/walkable information with :

bool TCODMap::isTransparent(int x, int y) const bool TCODMap::isWalkable(int x, int y) const

bool TCOD_map_is_transparent(TCOD_map_t map, int x, int y) bool TCOD_map_is_walkable(TCOD_map_t map, int x, int y)

map_is_transparent(map, x, y) map_is_walkable(map, x, y)

bool TCODMap::isTransparent(int x, int y) bool TCODMap::isWalkable(int x, int y)

Parameters:

• map – In the C version, the map handler returned by the TCOD_map_new function.

• x, y – Coordinates of the cell we want to check. 0 <= x < map width. 0 <= y < map height.

bool isWalkable(int x, int y) const

int getWidth() const

You can retrieve the map size with :

int TCODMap::getWidth() const int TCODMap::getHeight() const

int TCOD_map_get_width(TCOD_map_t map) int TCOD_map_get_height(TCOD_map_t map)

map_get_width(map) map_get_height(map)

int TCODMap::getWidth() int TCODMap::getHeight()

Parameters:

map – In the C version, the map handler returned by the TCOD_map_new function.

int getHeight() const

virtual ~TCODMap()

void setInFov(int x, int y, bool fov)

int getNbCells() const

Public Members

TCOD_map_t data

Friends

friend class TCODPath

friend class TCODDijkstra

Class TCODMouse

• Defined in File mouse.hpp

Class Documentation

class TCODMouse

Public Static Functions

static void showCursor(bool visible)

static bool isCursorVisible()

static void move(int x, int y)

static TCOD_mouse_t getStatus()

Class TCODNamegen

• Defined in File namegen.hpp

Class Documentation

class TCODNamegen

This tool allows one to generate random names out of custom made syllable sets.

Public Static Functions

static void parse(const char *filename, TCODRandom *random = NULL)

In order to be able to generate names, the name generator needs to be fed proper data.

It will then be ready to generate random names defined in the file(s) it is fed. Syllable set parsing is achieved via the following. Note 1: Each file will be parsed once only. If, for some reason, you would like to parse the same file twice, you will need to destroy the generator first, which will empty the list of parsed files along with erasing all the data retrieved from those files.

Note 2: The generator can be fed data multiple times if you have it in separate files. Just make sure the structure names in them aren’t duplicated, otherwise they will be silently ignored.

Note 3: In the C++ version, you are not obliged to specify the random number generator. If you skip it in the function call, the generator will assume you would like to use an instance of the default generator.

static void TCODNameGenerator::parse(string filename) static void TCODNameGenerator::parse(string filename, TCODRandom random) TCODNamegen::parse(“data/names.txt”,TCODRandom::getInstance()); TCODNamegen::parse(“data/names2.txt”);

Parameters:

• filename – The file where the desired syllable set is saved, along with its relative path, for instance, “data/names.txt”.

• random – A random number generator object. Use NULL for the default random number generator

static void destroy(void)

To release the resources used by a name generator, you may call: This will free all memory used by the generator.

In order to generate a name again, you have to parse a file again.

static char *generate(char *name, bool allocate = false)

The following will output a random name generated using one of the generation rules specified in the syllable set: Should you choose to allocate memory for the output, you need to remember to deallocate it once you don’t need the name anymore using the free() function.

This applies to C++ as well (delete won’t work - you have to use free()).

On the other hand, should you choose not to allocate memory, be aware that subsequent calls will overwrite the previously returned pointer, so make sure to copy the output using strcpy(), strdup() or other means of your choosing.

The name you specify needs to be in one of the files the generator has previously parsed (see Creating a generator). If such a name doesn’t exist, a warning will be displayed and NULL will be returned.

TCODNamegen::parse(“data/names.txt”,TCODRandom::getInstance()); char * myName = TCODNamegen::generate(“fantasy female”);

TCOD_namegen_parse(“data/names.txt”,TCOD_random_get_instance()); char * my_name = TCOD_namegen_generate(“Celtic male”,false);

libtcod.namegen_parse(‘data/names.txt’) name = libtcod.namegen_generate(‘Nordic female’)

Parameters:

• name – The structure name you wish to refer to, for instance, “celtic female”. For more about how structure names work, please refer to those chapters.

• allocate – Whether memory should be allocated for the output or not.

static std::string generate(const char *name, bool allocate = false)

static char *generateCustom(char *name, char *rule, bool allocate = false)

It is also possible to generate a name using custom generation rules.

This overrides the random choice of a generation rule from the syllable set. Please refer to chapter 16.5 to learn about the name generation rules syntax.

TCODNamegen::parse(“data/names.txt”,TCODRandom::getInstance()); char * myName = TCODNamegen::generateCustom(“Nordic male”,”$s$e”);

TCOD_namegen_parse(“data/names.txt”,TCOD_random_get_instance()); char * my_name = TCOD_namegen_generate_custom(“Mesopotamian female”,”$s$e”,false);

libtcod.namegen_parse(‘data/names.txt’) name = libtcod.namegen_generate_custom(‘Nordic female’,’$s$e’)

Parameters:

• name – The structure name you wish to refer to, for instance, “celtic female”. For more about how structure names work, please refer to those chapters.

• rule – The name generation rule. See this chapter for more details.

• allocate – Whether memory should be allocated for the output or not.

static std::string generateCustom(const char *name, const char *rule, bool allocate = false)

static TCOD_list_t getSets(void)

If you wish to check the syllable set names that are currently available, you may call: This will create a list with all the available syllable set names.

Remember to delete that list after you don’t need it anymore!

Class TCODNoise

• Defined in File noise.hpp

Class Documentation

class TCODNoise

Usage example: 1D noise : the variation of a torch intensity 2D fbm : heightfield generation or clouds 3D fbm : animated smoke If you don’t know what is Perlin noise and derived functions, or what is the influence of the different fractal parameters, check the Perlin noise sample included with the library.

This toolkit provides several functions to generate Perlin noise and other derived noises. It can handle noise functions from 1 to 4 dimensions.

Simplex noise, fbm, turbulence
Perlin noise, fbm, turbulence
Wavelet noise, fbm, turbulence

Noise functions relative times

For example, in 4D, Perlin noise is 17 times slower than simplex noise.

	1D	2D	3D	4D
simplex	1	1	1	1
Perlin	1.3	4	5	17
wavelet	53	32	14	X

Public Functions

TCODNoise(int dimensions, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)

@noop noise_init
@noop noise
@noop Creating a noise generator
@brief Those functions initialize a noise generator from a number of dimensions (from 1 to 4), some fractal parameters and a random number generator.
  The C++ version provides several constructors. When the hurst and lacunarity parameters are omitted, default values (TCOD_NOISE_DEFAULT_HURST = 0.5f and TCOD_NOISE_DEFAULT_LACUNARITY = 2.0f) are used.
@noop
  TCODNoise::TCODNoise(int dimensions, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
  TCODNoise::TCODNoise(int dimensions, TCODRandom *random, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
  TCODNoise::TCODNoise(int dimensions, float hurst, float lacunarity, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
  TCODNoise::TCODNoise(int dimensions, float hurst, float lacunarity, TCODRandom *random, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
@noop TCOD_noise_t TCOD_noise_new(int dimensions, float hurst, float lacunarity, TCOD_random_t random)
@noop noise_new(dimensions, hurst=TCOD_NOISE_DEFAULT_HURST, lacunarity=TCOD_NOISE_DEFAULT_LACUNARITY, random=0)
@noop#
  TCODNoise::TCODNoise(int dimensions)
  TCODNoise::TCODNoise(int dimensions, TCODRandom random)
  TCODNoise::TCODNoise(int dimensions, float hurst, float lacunarity)
  TCODNoise::TCODNoise(int dimensions, float hurst, float lacunarity, TCODRandom random)
@param dimensions From 1 to 4.
@param hurst  For fractional brownian motion and turbulence, the fractal Hurst exponent. You can use the default value TCOD_NOISE_DEFAULT_HURST = 0.5f.
@param lacunarity For fractional brownian motion and turbulence, the fractal lacunarity. You can use the default value TCOD_NOISE_DEFAULT_LACUNARITY = 2.0f.
@param random A random number generator obtained with the Mersenne twister toolkit or NULL to use the default random number generator.
@noop

1 dimension generator TCODNoise * noise1d = new TCODNoise(1); 2D noise with a predefined random number generator TCODRandom *myRandom = new TCODRandom(); TCODNoise *noise2d = new TCODNoise(2,myRandom); a 3D noise generator with a specific fractal parameters TCODNoise *noise3d = new TCODNoise(3,0.7f,1.4f);

1 dimension generator TCOD_noise_t noise1d = TCOD_noise_new(1,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL); 2D noise with a predefined random number generator TCOD_random_t my_random = TCOD_random_new(); TCOD_noise_t noise2d = TCOD_noise_new(2,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,my_random); a 3D noise generator with a specific fractal parameters TCOD_noise_t noise3d = TCOD_noise_new(3,0.7f, 1.4f,NULL);

1 dimension generator

noise1d = libtcod.noise_new(1) 2D noise with a predefined random number generator

my_random = libtcod.random_new(); noise2d = libtcod.noise_new(2,libtcod.NOISE_DEFAULT_HURST, libtcod.NOISE_DEFAULT_LACUNARITY,my_random) a 3D noise generator with a specific fractal parameters

noise3d = libtcod.noise_new(3, 0.7, 1.4)

TCODNoise(int dimensions, TCODRandom *random, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)

TCODNoise(int dimensions, float hurst, float lacunarity, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)

TCODNoise(int dimensions, float hurst, float lacunarity, TCODRandom *random, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)

TCODNoise(const TCODNoise&) = delete

TCODNoise &operator=(const TCODNoise&) = delete

inline TCODNoise(TCODNoise &&rhs) noexcept

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

virtual ~TCODNoise()

@noop noise_init
@brief To release resources used by a generator, use those functions :
@noop TCODNoise::~TCODNoise()
@noop void TCOD_noise_delete(TCOD_noise_t noise)
@noop noise_delete(noise)
@noop# void TCODNoise::Dispose()
@param noise  In the C and Python versions, the generator handler, returned by the initialization function.
@noop

create a generator TCODNoise *noise = new TCODNoise(2); use it … destroy it delete noise;

create a generator TCOD_noise_t noise = TCOD_noise_new(2,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY, NULL); use it … destroy it TCOD_noise_delete(noise);

create a generator

noise = libtcod.noise_new(2,libtcod.NOISE_DEFAULT_HURST, libtcod.NOISE_DEFAULT_LACUNARITY, 0) use it

… destroy it

libtcod.noise_delete(noise)

void setType(TCOD_noise_type_t type)

Use this function to define the default algorithm used by the noise functions.

The default algorithm is simplex. It’s much faster than Perlin, especially in 4 dimensions. It has a better contrast too.

TCODNoise * noise1d = new TCODNoise(1); noise1d->setType(TCOD_NOISE_PERLIN);

TCOD_noise_t noise1d = TCOD_noise_new(1,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL); TCOD_noise_set_type(noise1d,TCOD_NOISE_PERLIN);

noise1d = libtcod.noise_new(1) libtcod.noise_set_type(noise1d,libtcod.NOISE_PERLIN)

Parameters:

• noise – In the C version, the generator handler, returned by the initialization function.

• type – The algorithm to use, either TCOD_NOISE_SIMPLEX, TCOD_NOISE_PERLIN or TCOD_NOISE_WAVELET.

float get(float *f, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)

  @noop noise_get
@noop noise
@noop Getting flat noise
@brief This function returns the noise function value between -1.0 and 1.0 at given coordinates.
@noop float TCODNoise::get(float *f, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
@noop float TCOD_noise_get(TCOD_noise_t noise, float *f)

float TCOD_noise_get_ex(TCOD_noise_t noise, float *f, TCOD_noise_type_t type)

1d noise TCODNoise * noise1d = new TCODNoise(1); float p=0.5f; get a 1d simplex value float value = noise1d->get(&p); 2d noise TCODNoise * noise2d = new TCODNoise(2); float p[2]={0.5f,0.7f}; get a 2D Perlin value float value = noise2d->get(p, TCOD_NOISE_PERLIN);

1d noise TCOD_noise_t noise1d = TCOD_noise_new(1,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL); float p=0.5f; get a 1d simplex value float value = TCOD_noise_get(noise1d,&p); 2d noise TCOD_noise_t noise2d = TCOD_noise_new(2,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL); float p[2]={0.5f,0.7f}; get a 2d perlin value float value = TCOD_noise_get_ex(noise2d,p,TCOD_NOISE_PERLIN);

1d noise

noise1d = libtcod.noise_new(1) get a 1d simplex value

value = libtcod.noise_get(noise1d,[0.5]) 2d noise

noise2d = libtcod.noise_new(2) get a 2d perlin value

value = libtcod.noise_get(noise2d,[0.5,0.7], libtcod.NOISE_PERLIN)

Parameters:

• noise – In the C version, the generator handler, returned by the initialization function.

• f – An array of coordinates, depending on the generator dimensions (between 1 and 4). The same array of coordinates will always return the same value.

• type – The algorithm to use. If not defined, use the default one (set with setType or simplex if not set)

float get(const float *f, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)

float getFbm(float *f, float octaves, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)

@noop noise_get_fbm
@noop noise
@noop Getting fbm noise
@brief This function returns the fbm function value between -1.0 and 1.0 at given coordinates, using fractal hurst and lacunarity defined when the generator has been created.
@noop float TCODNoise::getFbm(float *f, float octaves, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
@noop float TCOD_noise_get_fbm(TCOD_noise_t noise, float *f, float octaves)

float TCOD_noise_get_fbm(TCOD_noise_t noise, float *f, float octaves, TCOD_noise_type_t type)

1d fbm TCODNoise * noise1d = new TCODNoise(1); float p=0.5f; get a 1d simplex fbm float value = noise1d->getFbm(&p,32.0f); 2d fbm TCODNoise * noise2d = new TCODNoise(2); float p[2]={0.5f,0.7f}; get a 2d perlin fbm float value = noise2d->getFbm(p,32.0f, TCOD_NOISE_PERLIN);

1d fbm TCOD_noise_t noise1d = TCOD_noise_new(1,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL); float p=0.5f; get a 1d simplex fbm float value = TCOD_noise_get_fbm(noise1d,&p,32.0f); 2d fbm TCOD_noise_t noise2d = TCOD_noise_new(2,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL); float p[2]={0.5f,0.7f}; get a 2d perlin fbm float value = TCOD_noise_get_fbm_ex(noise2d,p,32.0f,TCOD_NOISE_PERLIN);

1d noise

noise1d = libtcod.noise_new(1) 1d simplex fbm

value = libtcod.noise_get_fbm(noise1d,[0.5],32.0) 2d noise

noise2d = libtcod.noise_new(2) 2d perlin fbm

value = libtcod.noise_get_fbm(noise2d,[0.5,0.7],32.0, libtcod.NOISE_PERLIN)

Parameters:

• noise – In the C version, the generator handler, returned by the initialization function.

• f – An array of coordinates, depending on the generator dimensions (between 1 and 4). The same array of coordinates will always return the same value.

• octaves – Number of iterations. Must be < TCOD_NOISE_MAX_OCTAVES = 128

• type – The algorithm to use. If not defined, use the default one (set with setType or simplex if not set)

float getFbm(const float *f, float octaves, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)

float getTurbulence(float *f, float octaves, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)

@noop noise_get_turbulence
@noop noise
@noop Getting turbulence
@brief This function returns the turbulence function value between -1.0 and 1.0 at given coordinates, using fractal hurst and lacunarity defined when the generator has been created.
@noop float TCODNoise::getTurbulence(float *f, float octaves, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
@noop float TCOD_noise_get_turbulence(TCOD_noise_t noise, float *f, float octaves)

float TCOD_noise_get_turbulence_ex(TCOD_noise_t noise, float *f, float octaves, TCOD_noise_type_t)

1d fbm TCODNoise * noise1d = new TCODNoise(1); float p=0.5f; a 1d simplex turbulence float value = noise1d->getTurbulence(&p,32.0f); 2d fbm TCODNoise * noise2d = new TCODNoise(2); float p[2]={0.5f,0.7f}; a 2d perlin turbulence float value = noise2d->getTurbulence(p,32.0f, TCOD_NOISE_PERLIN);

1d fbm TCOD_noise_t noise1d = TCOD_noise_new(1,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL); float p=0.5f; a 1d simplex turbulence float value = TCOD_noise_get_turbulence(noise1d,&p,32.0f); 2d fbm TCOD_noise_t noise2d = TCOD_noise_new(2,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL); float p[2]={0.5f,0.7f}; a 2d perlin turbulence float value = TCOD_noise_get_turbulence_ex(noise2d,p,32.0f, TCOD_NOISE_PERLIN);

1d noise

noise1d = libtcod.noise_new(1) 1d simplex turbulence

value = libtcod.noise_get_turbulence(noise1d,[0.5],32.0) 2d noise

noise2d = libtcod.noise_new(2) 2d perlin turbulence

value = libtcod.noise_get_turbulence(noise2d,[0.5,0.7],32.0,libtcod.NOISE_PERLIN)

Parameters:

• noise – In the C version, the generator handler, returned by the initialization function.

• f – An array of coordinates, depending on the generator dimensions (between 1 and 4). The same array of coordinates will always return the same value.

• octaves – Number of iterations. Must be < TCOD_NOISE_MAX_OCTAVES = 128

float getTurbulence(const float *f, float octaves, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)

Protected Attributes

TCOD_noise_t data

Friends

friend class TCODHeightMap

Class TCODParser

• Defined in File parser.hpp

Class Documentation

class TCODParser

Public Functions

TCODParser()

Use this function to create a generic parser.

Then you’ll specialize this parser by defining the structures it can read.

TCODParser(const TCODParser&) = delete

TCODParser &operator=(const TCODParser&) = delete

TCODParser(TCODParser&&) = default

TCODParser &operator=(TCODParser&&) = default

TCODParserStruct *newStructure(const char *name)

TCODParser parser(); TCODParserStruct *itemTypeStruct = parser.newStructure(“item_type”);

TCOD_parser_t parser = TCOD_parser_new(); TCOD_parser_struct_t item_type_struct = TCOD_parser_new_struct(parser, “item_type”);

parser=libtcod.parser_new() item_type_struct = libtcod.parser_new_struct(parser, “item_type”)

Parameters:

• parser – In the C version, the parser handler, returned by TCOD_parser_new.

• name – The name of the structure type (in the example, this would be “item_type”).

TCOD_value_type_t newCustomType(TCOD_parser_custom_t custom_type_parser)

void run(const char *filename, ITCODParserListener *listener = NULL)

Once you defined all the structure types and created your listener, you can start the actual parsing of the file :

Parameters:

• parser – In the C version, the parser handler, returned by TCOD_parser_new.

• filename – The name of the text file to parse, absolute or relative to current directory.

• listener – The listener containing the callbacks. Use NULL for the default listener

~TCODParser()

Once you’ve done with the file parsing, you can release the resources used by the parser :

Parameters:

parser – In the C version, the parser handler, returned by TCOD_parser_new.

void error(const char *msg, ...)

bool hasProperty(const char *name) const

bool getBoolProperty(const char *name) const

int getIntProperty(const char *name) const

int getCharProperty(const char *name) const

float getFloatProperty(const char *name) const

TCODColor getColorProperty(const char *name) const

TCOD_dice_t getDiceProperty(const char *name) const

const char *getStringProperty(const char *name) const

void *getCustomProperty(const char *name) const

TCOD_list_t getListProperty(const char *name, TCOD_value_type_t type) const

Class TCODParserStruct

• Defined in File parser.hpp

Class Documentation

class TCODParserStruct

Public Functions

TCODParserStruct *addFlag(const char *propname)

Use this function to add a flag property to a structure type.

A flag is a simplified boolean property. It cannot be mandatory: either it’s present and it’s true, or it’s absent and it’s false.

Note that in the C++ version, the function returns its parent object, allowing for chaining.

Parameters:

• str – In the C version, the structure handler, returned by TCOD_parser_new_struct.

• name – The name of the flag (in the example, this would be “abstract”).

TCODParserStruct *addProperty(const char *propname, TCOD_value_type_t type, bool mandatory)

Use this function to add a standard property to a structure type.

Check standard property types here.

Note that in the C++ version, the function returns its parent object, allowing for chaining.

itemTypeStruct->addProperty(“cost”,TCOD_TYPE_INT,true) ->addProperty(“weight”,TCOD_TYPE_FLOAT,true) ->addProperty(“deal_damage”,TCOD_TYPE_BOOL,true) ->addProperty(“damaged_color”,TCOD_TYPE_COLOR,true);

TCOD_struct_add_property(item_type_struct, “cost”, TCOD_TYPE_INT, true); TCOD_struct_add_property(item_type_struct, “damages”, TCOD_TYPE_DICE, true); TCOD_struct_add_property(item_type_struct, “color”, TCOD_TYPE_COLOR, true); TCOD_struct_add_property(item_type_struct, “damaged_color”, TCOD_TYPE_COLOR, true);

libtcod.struct_add_property(item_type_struct, “cost”, libtcod.TYPE_INT, True) libtcod.struct_add_property(item_type_struct, “damages”, libtcod.TYPE_DICE, True) libtcod.struct_add_property(item_type_struct, “color”, libtcod.TYPE_COLOR, True) libtcod.struct_add_property(item_type_struct, “damaged_color”, libtcod.TYPE_COLOR, True)

Parameters:

• str – In the C version, the structure handler, returned by TCOD_parser_new_struct.

• name – The name of the property (in the example, this would be “cost” or “damage” or …).

• type – The type of the property. It can be a standard type (see this).

• mandatory – Is this property mandatory? If true and the property is not defined in the file, the parser will raise an error.

TCODParserStruct *addValueList(const char *propname, const char **value_list, bool mandatory)

A value-list property is a string property for which we define the list of allowed values.

The parser will raise an error if the file contains an unauthorized value for this property. The first value-list property that you add to a structure type will have the TCOD_TYPE_VALUELIST00 type. The next TCOD_TYPE_VALUELIST01. You can define up to 16 value list property for each structure type. The last one has the type TCOD_TYPE_VALUELIST15. You must provide a value list as a NULL terminated array of strings.

Note that in the C++ version, the function returns its parent object, allowing for chaining.

static const char *damageTypes[] = { “slash”, “pierce”, “bludgeon”, NULL }; // note the ending NULL itemTypeStruct->addValueList(“damage_type”, damageTypes, true);

static const char *damage_types[] = { “slash”, “pierce”, “bludgeon”, NULL }; TCOD_struct_add_value_list(item_type_struct, “damage_type”, damage_types, true);

damage_types = [ “slash”, “pierce”, “bludgeon” ] libtcod.struct_add_value_list(item_type_struct, “damage_type”, damage_types, True)

Parameters:

• str – In the C version, the structure handler, returned by TCOD_parser_new_struct.

• name – The name of the property (in the example, this would be “damage_type”).

• value_list – The list of allowed strings.

• mandatory – Is this property mandatory ? If true and the property is not defined in the file, the parser will raise an error.

TCODParserStruct *addListProperty(const char *propname, TCOD_value_type_t type, bool mandatory)

Use this function to add a list property to a structure type.

Note that in the C++ version, the function returns its parent object, allowing for chaining.

itemTypeStruct->addListProperty(“intList”,TCOD_TYPE_INT,true) ->addListProperty(“floatList”,TCOD_TYPE_FLOAT,true) ->addListProperty(“stringList”,TCOD_TYPE_STRING,true);

TCOD_struct_add_list_property(item_type_struct, “intList”, TCOD_TYPE_INT, true); TCOD_struct_add_list_property(item_type_struct, “floatList”, TCOD_TYPE_FLOAT, true); TCOD_struct_add_list_property(item_type_struct, “stringList”, TCOD_TYPE_STRING, true);

libtcod.struct_add_list_property(item_type_struct, “intList”, libtcod.TYPE_INT, True) libtcod.struct_add_list_property(item_type_struct, “floatList”, libtcod.TYPE_FLOAT, True) libtcod.struct_add_list_property(item_type_struct, “stringList”, libtcod.TYPE_STRING, True)

Parameters:

• str – In the C version, the structure handler, returned by TCOD_parser_new_struct.

• name – The name of the property (in the example, this would be “cost” or “damages” or …).

• type – The type of the list elements. It must be a standard type (see this). It cannot be TCOD_TYPE_LIST.

• mandatory – Is this property mandatory ? If true and the property is not defined in the file, the parser will raise an error.

TCODParserStruct *addStructure(TCODParserStruct *sub_entity)

A structure can contain others structures.

You can tell the parser which structures are allowed inside one structure type with this function.

Note that in the C++ version, the function returns its parent object, allowing for chaining.

The item_type structure can contain itself itemTypeStruct->addStructure(itemTypeStruct);

Parameters:

• str – In the C version, the structure handler, returned by TCOD_parser_new_struct.

• sub_structure – The structure type that can be embedded.

const char *getName() const

You can retrieve the name of the structure type with these functions.

Warning ! Do not confuse the structure type’s name with the structure’s name :

item_type “sword” { … }

Here, the structure type’s name is “item_type”, the structure name is “sword”. Obviously, the structure name cannot be retrieved from the TCODParserStruct object because it’s only known at “runtime” (while parsing the file).

Parameters:

str – In the C version, the structure handler, returned by TCOD_parser_new_struct.

bool isPropertyMandatory(const char *propname) const

You can know if a property is mandatory :

Parameters:

• str – In the C version, the structure handler, returned by TCOD_parser_new_struct.

• name – The name of the property, as defined when you called addProperty or addValueList or addListProperty.

TCOD_value_type_t getPropertyType(const char *propname) const

You get the type of a property : In the case of a list property, the value returned is a bitwise or of TCOD_TYPE_LIST and the list element’s type.

For example, for a list of int, it will return TCOD_TYPE_LIST | TCOD_TYPE_INT.

TCOD_value_type_t costType = itemTypeStruct->getPropertyType(“cost”); // returns TCOD_TYPE_INT TCOD_value_type_t intListType = itemTypeStruct->getPropertyType(“intList”); // returns TCOD_TYPE_LIST|TCOD_TYPE_INT

Parameters:

• str – In the C version, the structure handler, returned by TCOD_parser_new_struct.

• name – The name of the property, as defined when you called addProperty or addValueList or addListProperty.

Public Members

TCOD_parser_struct_t data

Class TCODPath

• Defined in File path.hpp

Nested Relationships

Nested Types

• Struct TCODPath::WrapperData

Class Documentation

class TCODPath

This toolkit allows one to easily calculate the optimal path between two points in your dungeon by using either the A* algorithm or Dijkstra’s algorithm. Please note that the paths generated with the two algorithms may differ slightly. Due to how they’re implemented, A* will usually prefer diagonal moves over orthogonal, while Dijkstra will have the opposite preference. In other words, paths from point X to point Y will look like this:

Public Functions

TCODPath(const TCODMap *map, float diagonalCost = 1.41f)

First, you have to allocate a path using a map from the Field of view module.

TCODPath::TCODPath(const TCODMap *map, float diagonalCost=1.41f) TCODDijkstra::TCODDijkstra(const TCODMap *map, float diagonalCost=1.41f)

TCOD_path_t TCOD_path_new_using_map(TCOD_map_t map, float diagonalCost) TCOD_dijkstra_t TCOD_dijkstra_new(TCOD_map_t map, float diagonalCost)

path_new_using_map(map, diagonalCost=1.41) dijkstra_new(map, diagonalCost=1.41)

TCODPath(TCODMap map, float diagonalCost) TCODPath(TCODMap map) TCODDijkstra(TCODMap map, float diagonalCost) TCODDijkstra(TCODMap map) A* : TCODMap *myMap = new TCODMap(50,50); TCODPath *path = new TCODPath(myMap); // allocate the path Dijkstra: TCODMap *myMap = new TCODMap(50,50); TCODDijkstra *dijkstra = new TCODDijkstra(myMap); // allocate the path

A* : TCOD_map_t my_map=TCOD_map_new(50,50,true); TCOD_path_t path = TCOD_path_new_using_map(my_map,1.41f); Dijkstra : TCOD_map_t my_map=TCOD_map_new(50,50,true); TCOD_dijkstra_t dijkstra = TCOD_dijkstra_new(my_map,1.41f);

A* :

my_map=libtcod.map_new(50,50,True) path = libtcod.path_new_using_map(my_map) Dijkstra

my_map=libtcod.map_new(50,50,True) dijkstra = libtcod.dijkstra_new(my_map)

Parameters:

• map – The map. The path finder will use the ‘walkable’ property of the cells to find a path.

• diagonalCost – Cost of a diagonal movement compared to an horizontal or vertical movement. On a standard cartesian map, it should be sqrt(2) (1.41f). It you want the same cost for all movements, use 1.0f. If you don’t want the path finder to use diagonal movements, use 0.0f.

TCODPath(int width, int height, const ITCODPathCallback *listener, void *userData, float diagonalCost = 1.41f)

Since the walkable status of a cell may depend on a lot of parameters (the creature type, the weather, the terrain type…), you can also create a path by providing a function rather than relying on a TCODMap.

Callback : class ITCODPathCallback { public: virtual float getWalkCost( int xFrom, int yFrom, int xTo, int yTo, void <em>userData ) const = 0; }; A constructor: TCODPath::TCODPath(int width, int height, const ITCODPathCallback *callback, void *userData, float diagonalCost=1.41f) Dijkstra constructor TCODDijkstra::TCODDijkstra(int width, int height, const ITCODPathCallback *callback, void *userData, float diagonalCost=1.41f)

typedef float (*TCOD_path_func_t)( int xFrom, int yFrom, int xTo, int yTo, void *user_data ) TCOD_path_t TCOD_path_new_using_function(int width, int height, TCOD_path_func_t callback, void *user_data, float diagonalCost) TCOD_dijkstra_t TCOD_dijkstra_new_using_function(int width, int height, TCOD_path_func_t callback, void *user_data, float diagonalCost)

def path_func(xFrom,yFrom,xTo,yTo,userData) : … path_new_using_function(width, height, path_func, user_data=0, diagonalCost=1.41) dijkstra_new_using_function(width, height, path_func, user_data=0, diagonalCost=1.41)

TCODPath(int width, int height, ITCODPathCallback listener, float diagonalCost) TCODPath(int width, int height, ITCODPathCallback listener) TCODDijkstra(int width, int height, ITCODPathCallback listener, float diagonalCost) TCODDijkstra(int width, int height, ITCODPathCallback listener) class MyCallback : public ITCODPathCallback { public : float getWalkCost(int xFrom, int yFrom, int xTo, int yTo, void *userData ) const { … } }; TCODPath *path = new TCODPath(50,50,new MyCallback(),NULL); // allocate the path TCODDijkstra *dijkstra = new TCODDijkstra(50,50,new MyCallback(),NULL); // allocate Dijkstra

float my_func(int xFrom, int yFrom, int xTo, int yTo, void *user_data) { … } TCOD_path_t path = TCOD_path_new_using_function(50,50,my_func,NULL,1.41f); TCOD_dijkstra_t dijkstra = TCOD_dijkstra_new_using_function(50,50,my_func,NULL,1.41f);

def my_func(xFrom, yFrom, xTo, yTo, user_data) : return a float cost for this movement

return 1.0 path = libtcod.path_new_using_function(50,50,my_func) dijkstra = libtcod.dijkstra_new_using_function(50,50,my_func)

Parameters:

• width, height – The size of the map (in map cells).

• callback – A custom function that must return the walk cost from coordinates xFrom,yFrom to coordinates xTo,yTo. The cost must be > 0.0f if the cell xTo,yTo is walkable. It must be equal to 0.0f if it’s not. You must not take additional cost due to diagonal movements into account as it’s already done by the pathfinder.

• userData – Custom data that will be passed to the function.

• diagonalCost – Cost of a diagonal movement compared to an horizontal or vertical movement. On a standard cartesian map, it should be sqrt(2) (1.41f). It you want the same cost for all movements, use 1.0f. If you don’t want the path finder to use diagonal movements, use 0.0f.

TCODPath(const TCODPath&) = delete

TCODPath &operator=(const TCODPath&) = delete

inline TCODPath(TCODPath &&rhs) noexcept

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

virtual ~TCODPath()

To release the resources used by a path, destroy it with :

TCODPath::~TCODPath() TCODDijkstra::~TCODDijkstra()

void TCOD_path_delete(TCOD_path_t path) void TCOD_dijkstra_delete(TCOD_dijkstra_t dijkstra)

path_delete(path) dijkstra_delete(dijkstra)

void TCODPath::Dispose() void TCODDijkstra::Dispose()

TCODPath *path = new TCODPath(myMap); // allocate the path use the path… delete path; // destroy the path

TCODDijkstra *dijkstra = new TCODDijkstra(myMap); // allocate the path use the path… delete dijkstra; // destroy the path

TCOD_path_t path = TCOD_path_new_using_map(my_map); use the path … TCOD_path_delete(path);

TCOD_dijkstra_t dijkstra = TCOD_dijkstra_new(my_map); use the path … TCOD_dijkstra_delete(dijkstra);

path = libtcod.path_new_using_map(my_map) use the path …

libtcod.path_delete(path)

dijkstra = libtcod.dijkstra_new(my_map) use the path …

libtcod.dijkstra_delete(dijkstra)

Parameters:

• path – In the C version, the path handler returned by one of the TCOD_path_new_* function.

• dijkstra – In the C version, the path handler returned by one of the TCOD_dijkstra_new* function.

bool compute(int ox, int oy, int dx, int dy)

Once you created a TCODPath object, you can compute the path between two points:

TCODMap *myMap = new TCODMap(50,50); TCODPath *path = new TCODPath(myMap); // allocate the path path->compute(5,5,25,25); // calculate path from 5,5 to 25,25

TCOD_map_t my_map=TCOD_map_new(50,50); TCOD_path_t path = TCOD_path_new_using_map(my_map); TCOD_path_compute(path,5,5,25,25);

my_map=libtcod.map_new(50,50) path = libtcod.path_new_using_map(my_map) libtcod.path_compute(path,5,5,25,25)

Parameters:

• path – In the C version, the path handler returned by a creation function.

• ox, oy – Coordinates of the origin of the path.

• dx, dy – Coordinates of the destination of the path. Both points should be inside the map, and at a walkable position. The function returns false if there is no possible path.

void reverse()

Once you computed a path, you can exchange origin and destination :

void TCODPath::reverse() void TCODDijkstra::reverse()

void TCOD_path_reverse(TCOD_path_t path) void TCOD_dijkstra_reverse(TCOD_dijkstra_t dijkstra)

path_reverse(path) dijkstra_reverse(dijkstra)

void TCODPath::reverse() void TCODDijkstra::reverse()

TCODMap *myMap = new TCODMap(50,50); TCODPath *path = new TCODPath(myMap); // allocate the path path->compute(5,5,25,25); // calculate path from 5,5 to 25,25 path->reverse(); // now the path goes from 25,25 to 5,5

TCOD_map_t my_map=TCOD_map_new(50,50); TCOD_path_t path = TCOD_path_new_using_map(my_map); TCOD_path_compute(path,5,5,25,25); // calculate path from 5,5 to 25,25 TCOD_path_reverse(path); // now the path goes from 25,25 to 5,5

my_map=libtcod.map_new(50,50) path = libtcod.path_new_using_map(my_map) libtcod.path_compute(path,5,5,25,25) # calculate path from 5,5 to 25,25 libtcod.path_reverse(path) # now the path goes from 25,25 to 5,5

Parameters:

path – In the C version, the path handler returned by a creation function.

void getOrigin(int *x, int *y) const

You can read the current origin and destination cells with getOrigin/getDestination. Note that when you walk the path, the origin changes at each step.

void TCODPath::getOrigin(int *x,int *y) const void TCODPath::getDestination(int *x,int *y) const

void TCOD_path_get_origin(TCOD_path_t path, int *x, int *y) void TCOD_path_get_destination(TCOD_path_t path, int *x, int *y)

path_get_origin(path) # returns x,y path_get_destination(path) # returns x,y

void TCODPath::getOrigin(out int x, out int y) void TCODPath::getDestination(out int x, out int y)

Once the path has been computed, you can get information about it using of one those functions.

Parameters:

• path – In the C version, the path handler returned by a creation function.

• x, y – The function returns the cell coordinates in these variables

void getDestination(int *x, int *y) const

int size() const

You can get the number of steps needed to reach destination :

int TCODPath::size() const int TCODDijkstra::size() const

int TCOD_path_size(TCOD_path_t path) int TCOD_dijkstra_size(TCOD_dijkstra_t dijkstra)

path_size(path) dijkstra_size(dijkstra)

int TCODPath::size() int TCODDijkstra::size()

Parameters:

path, dijkstra – In the C version, the path handler returned by a creation function.

void get(int index, int *x, int *y) const

You can get the coordinates of each point along the path :

void TCODPath::get(int index, int *x, int *y) const void TCODDijkstra::get(int index, int *x, int *y) const

void TCOD_path_get(TCOD_path_t path, int index, int *x, int *y) void TCOD_dijkstra_get(TCOD_dijkstra_t dijkstra, int index, int *x, int *y)

path_get(path, index) # returns x,y dijkstra_get(dijkstra, index) # returns x,y

int TCODPath::size() int TCODDijkstra::size()

for (int i=0; i < path->size(); i++ ) { int x,y; path->get(i,&x,&y); printf (“Astar coord : %d %d\n”, x,y ); } for (int i=0; i < dijkstra->size(); i++ ) { int x,y; dijkstra->get(i,&x,&y); printf (“Dijkstra coord : %d %d\n”, x,y ); }

int i; for (i=0; i < TCOD_path_size(path); i++ ) { int x,y; TCOD_path_get(path,i,&x,&y); printf (“Astar coord : %d %d\n”, x,y ); } for (i=0; i < TCOD_dijkstra_size(dijkstra); i++ ) { int x,y; TCOD_dijkstra_get(dijkstra,i,&x,&y); printf (“Dijkstra coord : %d %d\n”, x,y ); }

for i in range (libtcod.path_size(path)) : x,y=libtcod.path_get(path,i) print ‘Astar coord : ‘,x,y for i in range (libtcod.dijkstra_size(dijkstra)) : x,y=libtcod.dijkstra_get(dijkstra,i) print ‘Dijkstra coord : ‘,x,y

Parameters:

• path, dijkstra – In the C version, the path handler returned by a creation function.

• index – Step number. 0 <= index < path size

• x, y – Address of the variables receiving the coordinates of the point.

bool isEmpty() const

If you want a creature to follow the path, a more convenient way is to walk the path : You know when you reached destination when the path is empty :

bool TCODPath::isEmpty() const bool TCODDijkstra::isEmpty() const

bool TCOD_path_is_empty(TCOD_path_t path) bool TCOD_dijkstra_is_empty(TCOD_dijkstra_t dijkstra)

path_is_empty(path) dijkstra_is_empty(dijkstra)

bool TCODPath::isEmpty() bool TCODDijkstra::isEmpty()

Parameters:

path, dijkstra – In the C version, the path handler returned by a creation function.

bool walk(int *x, int *y, bool recalculateWhenNeeded)

You can walk the path and go to the next step with : Note that walking the path consume one step (and decrease the path size by one).

The function returns false if recalculateWhenNeeded is false and the next cell on the path is no longer walkable, or if recalculateWhenNeeded is true, the next cell on the path is no longer walkable and no other path has been found. Also note that recalculateWhenNeeded only applies to A*.

bool TCODPath::walk(int *x, int *y, bool recalculateWhenNeeded) bool TCODDijkstra::walk(int *x, int *y)

bool TCOD_path_walk(TCOD_path_t path, int *x, int *y, bool recalculate_when_needed) bool TCOD_dijkstra_walk(TCOD_dijkstra_t dijkstra, int *x, int *y)

path_walk(TCOD_path_t path, recalculate_when_needed) # returns x,y or None,None if no path dijkstra_walk(TCOD_dijkstra_t dijkstra)

bool TCODPath::walk(ref int x, ref int y, bool recalculateWhenNeeded) bool TCODDijkstra::walk(ref int x, ref int y)

while (! path->

isEmpty()) { int x,y; if (path->walk(&x,&y,true)) { printf (“Astar coord: %d %d\n”,x,y ); } else { printf (“I’m stuck!\n” ); break; } } while (! dijkstra->isEmpty()) { int x,y; if (dijkstra->walk(&x,&y)) { printf (“Dijkstra coord: %d %d\n”,x,y ); } else { printf (“I’m stuck!\n” ); break; } }

while (! TCOD_path_is_empty(path)) { int x,y; if (TCOD_path_walk(path,&x,&y,true)) { printf (“Astar coord: %d %d\n”,x,y ); } else { printf (“I’m stuck!\n” ); break; } } while (! TCOD_dijkstra_is_empty(dijkstra)) { int x,y; if (TCOD_dijkstra_walk(dijkstra,&x,&y)) { printf (“Dijkstra coord: %d %d\n”,x,y ); } else { printf (“I’m stuck!\n” ); break; } }

while not libtcod.path_is_empty(path)) : x,y=libtcod.path_walk(path,True) if not x is None : print ‘Astar coord: ‘,x,y else : print “I’m stuck!” break while not libtcod.dijkstra_is_empty(dijkstra)) : x,y=libtcod.dijkstra_walk(dijkstra,True) if not x is None : print ‘Dijkstra coord: ‘,x,y else : print “I’m stuck!” break

Parameters:

• path, dijkstra – In the C version, the path handler returned by a creation function.

• x, y – Address of the variables receiving the coordinates of the next point.

• recalculateWhenNeeded – If the next point is no longer walkable (another creature may be in the way), recalculate a new path and walk it.

Protected Attributes

TCOD_path_t data

struct TCODPath::WrapperData cppData

Friends

friend float TCOD_path_func(int xFrom, int yFrom, int xTo, int yTo, void *data)

struct WrapperData

Public Members

void *userData

const ITCODPathCallback *listener

Class TCODRandom

• Defined in File mersenne.hpp

Class Documentation

class TCODRandom

This toolkit is an implementation of two fast and high quality pseudorandom number generators: a Mersenne twister generator, a Complementary-Multiply-With-Carry generator. CMWC is faster than MT (see table below) and has a much better period (1039460 vs. 106001). It is the default algo since libtcod 1.5.0.

Relative performances in two independent tests (lower is better) :

Algorithm	Numbers generated	Perf (1)	Perf (2)
MT	integer	62	50
MT	float	54	45
CMWC	integer	21	34
CMWC	float	32	27

For Python users:

Python already has great builtin random generators. But some parts of the Doryen library (noise, heightmap, …) uses RNG as parameters. If you intend to use those functions, you must provide a RNG created with the library.

For C# users:

.NET already has great builtin random generators. But some parts of the Doryen library (noise, heightmap, …) uses RNG as parameters. If you intend to use those functions, you must provide a RNG created with the library.

Public Functions

TCODRandom(TCOD_random_algo_t algo = TCOD_RNG_CMWC, bool allocate = true)

You can also create as many generators as you want with a random seed (the number of seconds since Jan 1 1970 at the time the constructor is called).

Warning ! If you call this function several times in the same second, it will return the same generator.

TCODRandom::TCODRandom() // Defaults to ComplementaryMultiplyWithCarry TCODRandom::TCODRandom(TCODRandomType algo)

Parameters:

algo – The PRNG algorithm the generator should be using.

TCODRandom(uint32_t seed, TCOD_random_algo_t algo = TCOD_RNG_CMWC)

@noop random_init
@noop Generators with user defined seeds
@brief Finally, you can create generators with a specific seed. Those allow you to get a reproducible set of random numbers. You can for example save a dungeon in a file by saving only the seed used for its generation (provided you have a determinist generation algorithm)
@noop TCODRandom::TCODRandom (uint32_t seed, TCOD_random_algo_t algo = TCOD_RNG_CMWC);
@noop TCOD_random_t TCOD_random_new_from_seed (TCOD_random_algo_t algo, uint32_t seed);
@noop random_new_from_seed(seed, algo=RNG_CMWC)
@noop#
  TCODRandom::TCODRandom(uint32_t seed) // Defaults to ComplementaryMultiplyWithCarry
  TCODRandom::TCODRandom(uint32_t seed, TCODRandomType algo)
@param seed The 32 bits seed used to initialize the generator. Two generators created with the same seed will generate the same set of pseudorandom numbers.
@param algo The PRNG algorithm the generator should be using.
@noop

default generator TCODRandom * default = TCODRandom::getInstance(); another random generator TCODRandom * myRandom = new TCODRandom(); a random generator with a specific seed TCODRandom * myDeterministRandom = new TCODRandom(0xdeadbeef);

default generator TCOD_random_t default = TCOD_random_get_instance(); another random generator TCOD_random_t my_random = TCOD_random_new(TCOD_RNG_CMWC); a random generator with a specific seed TCOD_random_t my_determinist_random = TCOD_random_new_from_seed(TCOD_RNG_CMWC,0xdeadbeef);

default generator

default = libtcod.random_get_instance() another random generator

my_random = libtcod.random_new() a random generator with a specific seed

my_determinist_random = libtcod.random_new_from_seed(0xdeadbeef)

inline explicit TCODRandom(TCOD_Random *mersenne)

Take ownership of a TCOD_Random* pointer.

New in version 1.16.

TCODRandom(const TCODRandom&) = delete

TCODRandom &operator=(const TCODRandom&) = delete

inline TCODRandom(TCODRandom &&rhs)

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

virtual ~TCODRandom()

@noop random_init
@noop Destroying a RNG
@brief To release resources used by a generator, use those functions :
  NB : do not delete the default random generator !
@noop TCODRandom::~TCODRandom()
@noop void TCOD_random_delete(TCOD_random_t mersenne)
@noop random_delete(mersenne)
@noop# void TCODRandom::Dispose()
@param mersenne In the C and Python versions, the generator handler, returned by the initialization functions.
@noop

create a generator TCODRandom *rnd = new TCODRandom(); use it … destroy it delete rnd;

create a generator TCOD_random_t rnd = TCOD_random_new(); use it … destroy it TCOD_random_delete(rnd);

create a generator

rnd = libtcod.random_new() use it

… destroy it

libtcod.random_delete(rnd)

inline void setDistribution(TCOD_distribution_t distribution)

@noop random_distro
@noop random
@noop Using a generator
@noop Setting the default RNG distribution
@brief Random numbers can be obtained using several different distributions. Linear is default, but if you wish to use one of the available Gaussian distributions, you can use this function to tell libtcod which is your preferred distribution. All random number getters will then use that distribution automatically to fetch your random numbers.

The distributions available are as follows:

1. TCOD_DISTRIBUTION_LINEAR This is the default distribution. It will return a number from a range min-max. The numbers will be evenly distributed, ie, each number from the range has the exact same chance of being selected.

2. TCOD_DISTRIBUTION_GAUSSIAN This distribution does not have minimum and maximum values. Instead, a mean and a standard deviation are used. The mean is the central value. It will appear with the greatest frequency. The farther away from the mean, the less the probability of appearing the possible results have. Although extreme values are possible, 99.7% of the results will be within the radius of 3 standard deviations from the mean. So, if the mean is 0 and the standard deviation is 5, the numbers will mostly fall in the (-15,15) range.

3. TCOD_DISTRIBUTION_GAUSSIAN_RANGE This one takes minimum and maximum values. Under the hood, it computes the mean (which falls right between the minimum and maximum) and the standard deviation and applies a standard Gaussian distribution to the values. The difference is that the result is always guaranteed to be in the min-max range.

4. TCOD_DISTRIBUTION_GAUSSIAN_INVERSE Essentially, this is the same as TCOD_DISTRIBUTION_GAUSSIAN. The difference is that the values near +3 and -3 standard deviations from the mean have the highest possibility of appearing, while the mean has the lowest.

5. TCOD_DISTRIBUTION_GAUSSIAN_RANGE_INVERSE Essentially, this is the same as TCOD_DISTRIBUTION_GAUSSIAN_RANGE, but the min and max values have the greatest probability of appearing, while the values between them, the lowest.

There exist functions to also specify both a min-max range AND a custom mean, which can be any value (possibly either min or max, but it can even be outside that range). In case such a function is used, the distributions will trigger a slightly different behaviour: TCOD_DISTRIBUTION_LINEAR TCOD_DISTRIBUTION_GAUSSIAN TCOD_DISTRIBUTION_GAUSSIAN_RANGE In these cases, the selected mean will have the highest probability of appearing.

TCOD_DISTRIBUTION_GAUSSIAN_INVERSE TCOD_DISTRIBUTION_GAUSSIAN_RANGE_INVERSE In these cases, the selected mean will appear with the lowest frequency.

Parameters:

• mersenne – In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used..

• distribution – The distribution constant from the available set:

  • TCOD_DISTRIBUTION_LINEAR

  • TCOD_DISTRIBUTION_GAUSSIAN

  • TCOD_DISTRIBUTION_GAUSSIAN_RANGE

  • TCOD_DISTRIBUTION_GAUSSIAN_INVERSE

  • TCOD_DISTRIBUTION_GAUSSIAN_RANGE_INVERSE

inline int getInt(int min, int max, int mean = 0)

@noop random_use
@noop random
@noop Using a generator
@noop Getting an integer
@brief Once you obtained a generator (using one of those methods), you can get random numbers using the following functions, using either the explicit or simplified API where applicable:
@noop

explicit API: int TCODRandom::getInt(int min, int max, int mean = 0)

simplified API: int TCODRandom::get(int min, int max, int mean = 0)

int TCOD_random_get_int(TCOD_random_t mersenne, int min, int max) int TCOD_random_get_int_mean(TCOD_random_t mersenne, int min, int max, int mean)

Parameters:

• mersenne – In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used..

• min, max – Range of values returned. Each time you call this function, you get a number between (including) min and max

• mean – This is used to set a custom mean, ie, not min+((max-min)/2). It can even be outside of the min-max range. Using a mean will force the use of a weighted (Gaussian) distribution, even if linear is set.

inline int get(int min, int max, int mean = 0)

inline float getFloat(float min, float max, float mean = 0.0f)

@noop random_use
@noop Getting a float
@brief To get a random floating point number, using either the explicit or simplified API where applicable
@noop

explicit API: float TCODRandom::getFloat(float min, float max, float mean = 0.0f)

simplified API: float TCODRandom::get(float min, float max, float mean = 0.0f)

float TCOD_random_get_float(TCOD_random_t mersenne, float min, float max) float TCOD_random_get_float_mean(TCOD_random_t mersenne, float min, float max, float mean)

default generator TCODRandom * default = TCODRandom::getInstance(); int aRandomIntBetween0And1000 = default->getInt(0,1000); int anotherRandomInt = default->get(0,1000); another random generator TCODRandom *myRandom = new TCODRandom(); float aRandomFloatBetween0And1000 = myRandom->getFloat(0.0f,1000.0f); float anotherRandomFloat = myRandom->get(0.0f,1000.0f);

default generator int a_random_int_between_0_and_1000 = TCOD_random_get_float(NULL,0,1000); another random generator TCOD_random_t my_random = TCOD_random_new(); float a_random_float_between_0_and_1000 = TCOD_random_get_float(my_random,0.0f,1000.0f);

default generator

a_random_int_between_0_and_1000 = libtcod.random_get_float(0,0,1000) another random generator

my_random = libtcod.random_new() a_random_float_between_0_and_1000 = libtcod.random_get_float(my_random,0.0,1000.0)

Parameters:

• mersenne – In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.

• min, max – Range of values returned. Each time you call this function, you get a number between (including) min and max

• mean – This is used to set a custom mean, ie, not min+((max-min)/2). It can even be outside of the min-max range. Using a mean will force the use of a weighted (Gaussian) distribution, even if linear is set.

inline float get(float min, float max, float mean = 0.0f)

inline double getDouble(double min, double max, double mean = 0.0)

@noop random_use
@noop Getting a double
@brief To get a random double precision floating point number, using either the explicit or simplified API where applicable
@noop

explicit API: double TCODRandom::getDouble(double min, double max, double mean = 0.0f)

simplified API: double TCODRandom::get(double min, double max, double mean = 0.0f)

double TCOD_random_get_double(TCOD_random_t mersenne, double min, double max) double TCOD_random_get_double_mean(TCOD_random_t mersenne, double min, double max, double mean)

default generator TCODRandom * default = TCODRandom::getInstance(); int aRandomIntBetween0And1000 = default->getInt(0,1000); int anotherRandomInt = default->get(0,1000); another random generator TCODRandom *myRandom = new TCODRandom(); float aRandomFloatBetween0And1000 = myRandom->getFloat(0.0f,1000.0f); float anotherRandomFloat = myRandom->get(0.0f,1000.0f);

default generator int a_random_int_between_0_and_1000 = TCOD_random_get_float(NULL,0,1000); another random generator TCOD_random_t my_random = TCOD_random_new(); float a_random_float_between_0_and_1000 = TCOD_random_get_float(my_random,0.0f,1000.0f);

default generator

a_random_int_between_0_and_1000 = libtcod.random_get_float(0,0,1000) another random generator

my_random = libtcod.random_new() a_random_float_between_0_and_1000 = libtcod.random_get_float(my_random,0.0,1000.0)

Parameters:

• mersenne – In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.

• min, max – Range of values returned. Each time you call this function, you get a number between (including) min and max

• mean – This is used to set a custom mean, ie, not min+((max-min)/2). It can even be outside of the min-max range. Using a mean will force the use of a weighted (Gaussian) distribution, even if linear is set.

inline double get(double min, double max, double mean = 0.0f)

TCODRandom *save() const

You can save the state of a generator with :

Parameters:

mersenne – In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.

void restore(const TCODRandom *backup)

@noop random_use
@noop Restoring a saved state
@brief And restore it later. This makes it possible to get the same series of number several times with a single generator.
@noop void TCODRandom::restore(const TCODRandom *backup)
@noop void TCOD_random_restore(TCOD_random_t mersenne, TCOD_random_t backup)
@noop random_restore(mersenne, backup)
@noop# void TCODRandom::restore(TCODRandom backup)
@param mersenne In the C and Python versions, the generator handler, returned by the initialization functions. If NULL, the default generator is used.
@noop

default generator TCODRandom * default = TCODRandom::getInstance(); save the state TCODRandom *backup=default->save(); get a random number (or several) int number1 = default->getInt(0,1000); restore the state default->restore(backup); get a random number int number2 = default->getInt(0,1000); => number1 == number2

save default generator state TCOD_random_t backup=TCOD_random_save(NULL); get a random number int number1 = TCOD_random_get_float(NULL,0,1000); restore the state TCOD_random_restore(NULL,backup); get a random number int number2 = TCOD_random_get_float(NULL,0,1000); number1 == number2

save default generator state

backup=libtcod.random_save(0) get a random number

number1 = libtcod.random_get_float(0,0,1000) restore the state

libtcod.random_restore(0,backup) get a random number

number2 = libtcod.random_get_float(0,0,1000) number1 == number2

inline TCOD_dice_t dice(const char *s)

inline int diceRoll(TCOD_dice_t dice)

inline int diceRoll(const char *s)

inline TCOD_Random *get_data() noexcept

Return this objects TCOD_Random* pointer.

New in version 1.16.

inline const TCOD_Random *get_data() const noexcept

Public Static Functions

static TCODRandom *getInstance(void)

The simplest way to get random number is to use the default generator.

The first time you get this generator, it is initialized by calling TCOD_random_new. Then, on successive calls, this function returns the same generator (singleton pattern).

Parameters:

algo – The PRNG algorithm the generator should be using. Possible values are: TCOD_RNG_MT for Mersenne Twister, TCOD_RNG_CMWC for Complementary Multiply-With-Carry.

Protected Attributes

TCOD_Random *data = {}

Friends

friend class TCODNoise

friend class TCODHeightMap

friend class TCODNamegen

friend class TCODNameGenerator

Class TCODSystem

• Defined in File sys.hpp

Class Documentation

class TCODSystem

Public Static Functions

static void setFps(int val)

The setFps function allows you to limit the number of frames per second. If a frame is rendered faster than expected, the TCOD_console_flush function will wait so that the frame rate never exceed this value. You can call this function during your game initialization. You can dynamically change the frame rate. Just call this function once again. You should always limit the frame rate, except during benchmarks, else your game will use 100% of the CPU power

These are functions specifically aimed at real time game development.

Parameters:

val – Maximum number of frames per second. 0 means unlimited frame rate.

static int getFps()

The value returned by this function is updated every second.

static float getLastFrameLength()

This function returns the length in seconds of the last rendered frame.

You can use this value to update every time dependent object in the world.

moving an objet at 5 console cells per second float x=0,y=0; // object coordinates x += 5 * TCODSystem::getLastFrameLength(); TCODConsole::root->putChar((int)(x),(int)(y),’X’);

float x=0,y=0; x += 5 * TCOD_sys_get_last_frame_length(); TCOD_console_put_char(NULL,(int)(x),(int)(y),’X’);

x=0.0 y=0.0 x += 5 * libtcod.sys_get_last_frame_length() libtcod.console_put_char(0,int(x),int(y),’X’)

&#8212; moving an objet at 5 console cells per second x=0 y=0 &#8212; object coordinates x = x + 5 * tcod.system.getLastFrameLength() libtcod.TCODConsole_root:putChar(x,y,’X’)

static void sleepMilli(uint32_t val)

Use this function to stop the program execution for a specified number of milliseconds.

Parameters:

val – number of milliseconds before the function returns

static uint32_t getElapsedMilli()

This function returns the number of milliseconds since the program has started.

static float getElapsedSeconds()

This function returns the number of seconds since the program has started.

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

This function waits for an event from the user.

The eventMask shows what events we’re waiting for. The return value indicate what event was actually triggered. Values in key and mouse structures are updated accordingly. If flush is false, the function waits only if there are no pending events, else it returns the first event in the buffer.

TCOD_EVENT_NONE=0, TCOD_EVENT_KEY_PRESS=1, TCOD_EVENT_KEY_RELEASE=2, TCOD_EVENT_KEY=TCOD_EVENT_KEY_PRESS|TCOD_EVENT_KEY_RELEASE, TCOD_EVENT_MOUSE_MOVE=4, TCOD_EVENT_MOUSE_PRESS=8, TCOD_EVENT_MOUSE_RELEASE=16, TCOD_EVENT_MOUSE=TCOD_EVENT_MOUSE_MOVE|TCOD_EVENT_MOUSE_PRESS|TCOD_EVENT_MOUSE_RELEASE, TCOD_EVENT_ANY=TCOD_EVENT_KEY|TCOD_EVENT_MOUSE, } TCOD_event_t; static TCOD_event_t TCODSystem::waitForEvent(int eventMask, TCOD_key_t *key, TCOD_mouse_t *mouse, bool flush)

TCOD_key_t key; TCOD_mouse_t mouse; TCOD_event_t ev = TCODSystem::waitForEvent(TCOD_EVENT_ANY,&key,&mouse,true); if ( ev == TCOD_EVENT_KEY_PRESS && key.c == ‘i’ ) { … open inventory … }

TCOD_key_t key; TCOD_mouse_t mouse; TCOD_event_t ev = TCOD_sys_wait_for_event(TCOD_EVENT_ANY,&key,&mouse,true); if ( ev == TCOD_EVENT_KEY_PRESS && key.c == ‘i’ ) { … open inventory … }

Parameters:

• eventMask – event types to wait for (other types are discarded)

• key – updated in case of a key event. Can be null if eventMask contains no key event type

• mouse – updated in case of a mouse event. Can be null if eventMask contains no mouse event type

• flush – if true, all pending events are flushed from the buffer. Else, return the first available event

static TCOD_event_t checkForEvent(int eventMask, TCOD_key_t *key, TCOD_mouse_t *mouse)

This function checks if an event from the user is in the buffer.

The eventMask shows what events we’re waiting for. The return value indicate what event was actually found. Values in key and mouse structures are updated accordingly.

TCOD_EVENT_KEY_PRESS=1, TCOD_EVENT_KEY_RELEASE=2, TCOD_EVENT_KEY=TCOD_EVENT_KEY_PRESS|TCOD_EVENT_KEY_RELEASE, TCOD_EVENT_MOUSE_MOVE=4, TCOD_EVENT_MOUSE_PRESS=8, TCOD_EVENT_MOUSE_RELEASE=16, TCOD_EVENT_MOUSE=TCOD_EVENT_MOUSE_MOVE|TCOD_EVENT_MOUSE_PRESS|TCOD_EVENT_MOUSE_RELEASE, TCOD_EVENT_ANY=TCOD_EVENT_KEY|TCOD_EVENT_MOUSE, } TCOD_event_t; static TCOD_event_t TCODSystem::checkForEvent(int eventMask, TCOD_key_t *key, TCOD_mouse_t *mouse)

TCOD_key_t key; TCOD_mouse_t mouse; TCOD_event_t ev = TCODSystem::checkForEvent(TCOD_EVENT_ANY,&key,&mouse); if ( ev == TCOD_EVENT_KEY_PRESS && key.c == ‘i’ ) { … open inventory … }

TCOD_key_t key; TCOD_mouse_t mouse; TCOD_event_t ev = TCOD_sys_check_for_event(TCOD_EVENT_ANY,&key,&mouse); if ( ev == TCOD_EVENT_KEY_PRESS && key.c == ‘i’ ) { … open inventory … }

Parameters:

• eventMask – event types to wait for (other types are discarded)

• key – updated in case of a key event. Can be null if eventMask contains no key event type

• mouse – updated in case of a mouse event. Can be null if eventMask contains no mouse event type

static void saveScreenshot(const char *filename)

This function allows you to save the current game screen in a png file, or possibly a bmp file if you provide a filename ending with .bmp.

Parameters:

filename – Name of the file. If NULL, a filename is automatically generated with the form “./screenshotNNN.png”, NNN being the first free number (if a file named screenshot000.png already exist, screenshot001.png will be used, and so on…).

static bool createDirectory(const char *path)

Those are a few function that cannot be easily implemented in a portable way in C/C++. They have no Python wrapper since Python provides its own builtin functions. All those functions return false if an error occurred.

Parameters:

path – Directory path. The immediate father directory (<path>/..) must exist and be writable.

static bool deleteDirectory(const char *path)

Parameters:

path – directory path. This directory must exist, be writable and empty

static bool deleteFile(const char *path)

Parameters:

path – File path. This file must exist and be writable.

static bool isDirectory(const char *path)

Parameters:

path – a path to check

static TCOD_list_t getDirectoryContent(const char *path, const char *pattern)

To get the list of entries in a directory (including sub-directories, except .

and ..). The returned list is allocated by the function and must be deleted by you. All the const char * inside must be also freed with TCODList::clearAndDelete.

Parameters:

• path – a directory

• pattern – If NULL or empty, returns all directory entries. Else returns only entries matching the pattern. The pattern is NOT a regular expression. It can only handle one ‘*’ wildcard. Examples : *.png, saveGame*, font*.png

static bool fileExists(const char *filename, ...)

In order to check whether a given file exists in the filesystem.

Useful for detecting errors caused by missing files.

if (!TCODSystem::fileExists(“myfile.%s”,”txt”)) { fprintf(stderr,”no such file!”); }

if (!TCOD_sys_file_exists(“myfile.%s”,”txt”)) { fprintf(stderr,”no such file!”); }

Parameters:

• filename – the file name, using printf-like formatting

• ... – optional arguments for filename formatting

static bool readFile(const char *filename, unsigned char **buf, size_t *size)

This is a portable function to read the content of a file from disk or from the application apk (android).

buf must be freed with free(buf).

unsigned char *buf; uint32_t size; if (TCODSystem::readFile(“myfile.dat”,&buf,&size)) { do something with buf free(buf); }

if (TCOD_sys_read_file(“myfile.dat”,&buf,&size)) { do something with buf free(buf); }

Parameters:

• filename – the file name

• buf – a buffer to be allocated and filled with the file content

• size – the size of the allocated buffer.

static bool writeFile(const char *filename, unsigned char *buf, uint32_t size)

This is a portable function to write some data to a file.

TCODSystem::writeFile(“myfile.dat”,buf,size));

TCOD_sys_write_file(“myfile.dat”,buf,size));

Parameters:

• filename – the file name

• buf – a buffer containing the data to write

• size – the number of bytes to write.

static void registerSDLRenderer(ITCODSDLRenderer *renderer)

To disable the custom renderer, call the same method with a NULL parameter. Note that to keep libtcod from requiring the SDL headers, the callback parameter is a void pointer. You have to include SDL headers and cast it to SDL_Surface in your code.

class TCODLIB_API ITCODSDLRenderer { public : virtual void render(void *sdlSurface) = 0; }; static void TCODSystem::registerSDLRenderer(ITCODSDLRenderer *callback);

typedef void (*SDL_renderer_t) (void *sdl_surface); void TCOD_sys_register_SDL_renderer(SDL_renderer_t callback)

def renderer ( sdl_surface ) : … TCOD_sys_register_SDL_renderer( callback )

You can register a callback that will be called after the libtcod rendering phase, but before the screen buffer is swapped. This callback receives the screen SDL_Surface reference. This makes it possible to use any SDL drawing functions (including openGL) on top of the libtcod console.

class MyRenderer : public ITCODSDLRenderer { public : void render(void *sdlSurface) { SDL_Surface *s = (SDL_Surface *)sdlSurface; … draw something on s } }; TCODSystem::registerSDLRenderer(new MyRenderer());

void my_renderer( void *sdl_surface ) { SDL_Surface *s = (SDL_Surface *)sdl_surface; … draw something on s } TCOD_sys_register_SDL_renderer(my_renderer);

def my_renderer(sdl_surface) : … draw something on sdl_surface using pygame libtcod.sys_register_SDL_renderer(my_renderer)

Parameters:

callback – The renderer to call before swapping the screen buffer. If NULL, custom rendering is disabled

static void forceFullscreenResolution(int width, int height)

libtcod is not aware of the part of the screen your SDL renderer has updated.

If no change occurred in the console, it won’t redraw them except if you tell him to do so with this function

This function allows you to force the use of a specific resolution in fullscreen mode. The default resolution depends on the root console size and the font character size.

TCODSystem::forceFullscreenResolution(800,600); // use 800x600 in fullscreen instead of 640x400 TCODConsole::initRoot(80,50,””,true); // 80x50 console with 8x8 char => 640x400 default resolution

TCOD_sys_force_fullscreen_resolution(800,600); TCOD_console_init_root(80,50,””,true);

libtcod.sys_force_fullscreen_resolution(800,600) libtcod.console_init_root(80,50,””,True)

tcod.system.forceFullscreenResolution(800,600) &#8212; use 800x600 in fullscreen instead of 640x400 tcod.console.initRoot(80,50,””,true) &#8212; 80x50 console with 8x8 char => 640x400 default resolution

Parameters:

• x, y, w, h – Part of the root console you want to redraw even if nothing has changed in the console back/fore/char.

• width, height – Resolution to use when switching to fullscreen. Will use the smallest available resolution so that : resolution width >= width and resolution width >= root console width * font char width resolution width >= height and resolution height >= root console height * font char height

static void getCurrentResolution(int *width, int *height)

You can get the current screen resolution with getCurrentResolution.

You can use it for example to get the desktop resolution before initializing the root console.

Parameters:

width, height – contains current resolution when the function returns

static void getFullscreenOffsets(int *offset_x, int *offset_y)

If the fullscreen resolution does not matches the console size in pixels, black borders are added.

This function returns the position in pixels of the console top left corner in the screen.

Parameters:

offset_x, offset_y – contains the position of the console on the screen when using fullscreen mode.

static void getCharSize(int *w, int *h)

You can get the size of the characters in the font.

Parameters:

width, height – contains a character size when the function returns

static void updateChar(int asciiCode, int font_x, int font_y, const TCODImage *img, int x, int y)

You can dynamically change the bitmap of a character in the font.

All cells using this ascii code will be updated at next flush call.

Parameters:

• asciiCode – ascii code corresponding to the character to update

• font_x, font_y – coordinate of the character in the bitmap font (in characters, not pixels)

• img – image containing the new character bitmap

• x, y – position in pixels of the top-left corner of the character in the image

static void setRenderer(TCOD_renderer_t renderer)

As of 1.5.1, libtcod contains 3 different renderers : SDL : historic libtcod renderer.

Should work and be pretty fast everywhere OpenGL : requires OpenGL compatible video card. Might be much faster or much slower than SDL, depending on the drivers GLSDL : requires OpenGL 1.4 compatible video card with GL_ARB_shader_objects extension. Blazing fast if you have the proper hardware and drivers. This function switches the current renderer dynamically.

Parameters:

renderer – Either TCOD_RENDERER_GLSL, TCOD_RENDERER_OPENGL or TCOD_RENDERER_SDL

static TCOD_renderer_t getRenderer()

static bool setClipboard(const char *value)

Takes UTF-8 text and copies it into the system clipboard. On Linux, because an application cannot access the system clipboard unless a window is open, if no window is open the call will do nothing.

With these functions, you can copy data in your operating system’s clipboard from the game or retrieve data from the clipboard.

Parameters:

value – UTF-8 text to copy into the clipboard

static char *getClipboard()

Returns the UTF-8 text currently in the system clipboard.

On Linux, because an application cannot access the system clipboard unless a window is open, if no window is open an empty string will be returned. For C and C++, note that the pointer is borrowed, and libtcod will take care of freeing the memory.

static int getNumCores()

static TCOD_thread_t newThread(int (*func)(void*), void *data)

static void deleteThread(TCOD_thread_t th)

static void waitThread(TCOD_thread_t th)

static TCOD_mutex_t newMutex()

static void mutexIn(TCOD_mutex_t mut)

static void mutexOut(TCOD_mutex_t mut)

static void deleteMutex(TCOD_mutex_t mut)

static TCOD_semaphore_t newSemaphore(int initVal)

static void lockSemaphore(TCOD_semaphore_t sem)

static void unlockSemaphore(TCOD_semaphore_t sem)

static void deleteSemaphore(TCOD_semaphore_t sem)

static TCOD_cond_t newCondition()

static void signalCondition(TCOD_cond_t sem)

static void broadcastCondition(TCOD_cond_t sem)

static void waitCondition(TCOD_cond_t sem, TCOD_mutex_t mut)

static void deleteCondition(TCOD_cond_t sem)

Class TCODText

• Defined in File txtfield.hpp

Class Documentation

class TCODText

Public Functions

TCODText(int x, int y, int w, int h, int max_chars)

TCODText(int w, int h, int max_chars)

~TCODText()

void setProperties(int cursor_char, int blink_interval, const char *prompt, int tab_size)

void setColors(TCODColor fore, TCODColor back, float back_transparency)

void setPos(int x, int y)

bool update(TCOD_key_t key)

void render(TCODConsole *con)

const char *getText()

void reset()

Protected Attributes

TCOD_text_t data

Class TCODTree

• Defined in File tree.hpp

Class Documentation

class TCODTree

Public Functions

TCODTree() = default

TCODTree(const TCODTree&) = delete

TCODTree &operator=(const TCODTree&) = delete

inline TCODTree(TCODTree &&rhs) noexcept

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

inline void addSon(TCODTree *data)

Public Members

TCODTree *next = {}

TCODTree *father = {}

TCODTree *sons = {}

Friends

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

Class TCODZip

• Defined in File zip.hpp

Class Documentation

class TCODZip

This toolkit provides functions to save or read compressed data from a file. While the module is named Zip, it has nothing to do with the .zip format as it uses zlib compression (.gz format). Note that this modules has no Python wrapper. Use Python built-in zip module instead.

You can use the compression buffer in two modes: put data in the buffer, then save it to a file, load a file into the buffer, then get data from it.

Public Functions

TCODZip()

This function initializes a compression buffer.

~TCODZip()

Once you don’t need the buffer anymore, you can release resources.

Note that the addresses returned by the getString function are no longer valid once the buffer has been destroyed.

TCODZip *zip = new TCODZip(); zip->loadFromFile(“myCompressedFile.gz”); char c=zip->getChar(); int i=zip->getInt(); float f= zip->getFloat(); const char *s=strdup(zip->getString()); // we duplicate the string to be able to use it after the buffer deletion zip->getData(nbBytes, dataPtr); delete zip;

TCOD_zip_t zip=TCOD_zip_new(); TCOD_zip_load_from_file(zip,”myCompressedFile.gz”); char c=TCOD_zip_get_char(zip); int i=TCOD_zip_get_int(zip); float f=TCOD_zip_get_float(zip); const char *s=strdup(TCOD_zip_get_string(zip)); TCOD_zip_get_data(zip,nbBytes, dataPtr); TCOD_zip_delete(zip);

Parameters:

zip – In the C version, the buffer handler, returned by the constructor.

void putChar(char val)

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• val – A 8 bits value to store in the buffer

void putInt(int val)

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• val – An integer value to store in the buffer

void putFloat(float val)

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• val – A float value to store in the buffer

void putString(const char *val)

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• val – A string to store in the buffer

void putColor(const TCODColor *val)

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• val – A color to store in the buffer

void putImage(const TCODImage *val)

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• val – An image to store in the buffer

void putConsole(const TCODConsole *val)

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• val – A console to store in the buffer

void putRandom(const TCODRandom *val)

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• val – An RNG state to store in the buffer

void putData(int nbBytes, const void *data)

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• nbBytes – Number of bytes to store in the buffer

• val – Address of the data to store in the buffer

uint32_t getCurrentBytes() const

Parameters:

zip – In the C version, the buffer handler, returned by the constructor.

int saveToFile(const char *filename)

Once you have finished adding data in the buffer, you can compress it and save it in a file.

The function returns the number of (uncompressed) bytes saved.

TCODZip zip; zip.putChar(‘A’); zip.putInt(1764); zip.putFloat(3.14f); zip.putString(“A string”); zip.putData(nbBytes, dataPtr); zip.saveToFile(“myCompressedFile.gz”);

TCOD_zip_t zip=TCOD_zip_new(); TCOD_zip_put_char(zip,’A’); TCOD_zip_put_int(zip,1764); TCOD_zip_put_float(zip,3.14f); TCOD_zip_put_string(zip,”A string”); TCOD_zip_put_data(zip,nbBytes, dataPtr); TCOD_zip_save_to_file(zip,”myCompressedFile.gz”);

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• filename – Name of the file

inline void saveToFile(const std::filesystem::path &path)

Save this objects buffered objects to the file at path.

New in version 1.24.

Parameters:

path – The file to write.

int loadFromFile(const char *filename)

You can read data from a file (compressed or not) into the buffer.

The function returns the number of (uncompressed) bytes read or 0 if an error occurred.

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• filename – Name of the file

inline void loadFromFile(const std::filesystem::path &path)

Load objects from the file at path.

New in version 1.24.

Parameters:

path – The file to read. Must exist and be valid.

Throws:

std::runtime_error – on any failure to load the file.

char getChar()

Parameters:

zip – In the C version, the buffer handler, returned by the constructor

int getInt()

Parameters:

zip – In the C version, the buffer handler, returned by the constructor.

float getFloat()

Parameters:

zip – In the C version, the buffer handler, returned by the constructor.

const char *getString()

The address returned is in the buffer.

It is valid as long as you don’t destroy the buffer.

Parameters:

zip – In the C version, the buffer handler, returned by the constructor.

TCODColor getColor()

Parameters:

zip – In the C version, the buffer handler, returned by the constructor.

TCODImage *getImage()

Parameters:

zip – In the C version, the buffer handler, returned by the constructor.

TCODConsole *getConsole()

Parameters:

zip – In the C version, the buffer handler, returned by the constructor.

TCODRandom *getRandom()

Parameters:

zip – In the C version, the buffer handler, returned by the constructor.

int getData(int nbBytes, void *data)

Note that the getData length must match the length of the data when the file was created (with putData).

The function returns the number of bytes that were stored in the file by the putData call. If more than nbBytes were stored, the function read only nbBytes and skip the rest of them.

TCODZip zip; zip.loadFromFile(“myCompressedFile.gz”); char c=zip.getChar(); int i=zip.getInt(); float f= zip.getFloat(); const char *s=zip.getString(); zip.getData(nbBytes, dataPtr);

TCOD_zip_t zip=TCOD_zip_new(); TCOD_zip_load_from_file(zip,”myCompressedFile.gz”); char c=TCOD_zip_get_char(zip); int i=TCOD_zip_get_int(zip); float f=TCOD_zip_get_float(zip); const char *s=TCOD_zip_get_string(zip); TCOD_zip_get_data(zip,nbBytes, dataPtr);

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• nbBytes – Number of bytes to read

• data – Address of a pre-allocated buffer (at least nbBytes bytes)

uint32_t getRemainingBytes() const

Parameters:

zip – In the C version, the buffer handler, returned by the constructor.

void skipBytes(uint32_t nbBytes)

Parameters:

• zip – In the C version, the buffer handler, returned by the constructor.

• nbBytes – number of uncompressed bytes to skip

inline void put(char value)

Save a char to this zip.

New in version 1.24.

inline void put(int value)

Save an int to this zip.

New in version 1.24.

inline void put(float value)

Save a float to this zip.

New in version 1.24.

inline void put(const char *value)

Save a string to this zip.

Can be nullptr.

New in version 1.24.

inline void put(const std::string &value)

Save a string to this zip.

New in version 1.24.

inline void put(const std::optional<std::string> &value)

Save an optional string to this zip.

New in version 1.24.

inline void put(const tcod::ColorRGB &value)

Save a color to this zip.

New in version 1.24.

inline void put(const TCODColor &value)

Save a color to this zip.

New in version 1.24.

inline void put(const TCODImage &value)

Save an image to this zip.

New in version 1.24.

inline TCODLIB_BEGIN_IGNORE_DEPRECATIONS void put (const TCODConsole &value)

Save a console to this zip.

New in version 1.24.

inline void put(const tcod::Console &value)

Save a console to this zip.

New in version 1.24.

inline TCODLIB_END_IGNORE_DEPRECATIONS void put (const TCODRandom &value)

Save an RNG state to this zip.

New in version 1.24.

template<typename T>
inline T get()

Return a value of T from this zip object.

New in version 1.24.

Template Parameters:

T – A type which must match one of the get(T) overloads.

Returns:

T

inline void get(char &out)

Extract a char to out.

New in version 1.24.

inline void get(int &out)

Extract an int to out.

New in version 1.24.

inline void get(float &out)

Extract a float to out.

New in version 1.24.

inline void get(std::optional<std::string> &out)

Extract an optional string to out.

New in version 1.24.

inline void get(std::string &out)

Extract a string to out.

Will throw if nullptr was put.

New in version 1.24.

inline void get(tcod::ColorRGB &out)

Extract a color to out.

New in version 1.24.

inline void get(TCODColor &out)

Extract a color to out.

New in version 1.24.

inline void get(tcod::ImagePtr &out)

Extract an image pointer to out.

New in version 1.24.

inline void get(TCODImage &out)

Extract an image to out.

New in version 1.24.

inline void get(tcod::ConsolePtr &out)

Extract a console pointer to out.

New in version 1.24.

inline void get(tcod::Console &out)

Extract a console to out.

New in version 1.24.

inline void get(TCODConsole &out)

Extract a console to out.

New in version 1.24.

inline void get(TCODRandom &out)

Extract an RNG state to out.

New in version 1.24.

Protected Attributes

TCOD_zip_t data = {}

Enums

Enum TCOD_alignment_t

• Defined in File console.h

Enum Documentation

enum TCOD_alignment_t

Print justification options.

Values:

enumerator TCOD_LEFT

enumerator TCOD_RIGHT

enumerator TCOD_CENTER

Enum TCOD_bkgnd_flag_t

• Defined in File console.h

Enum Documentation

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

Enum TCOD_chars_t

• Defined in File console_types.h

Enum Documentation

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:

Enum TCOD_colctrl_t

• Defined in File console_printing.h

Enum Documentation

enum TCOD_colctrl_t

Values:

enumerator TCOD_COLCTRL_1

enumerator TCOD_COLCTRL_2

enumerator TCOD_COLCTRL_3

enumerator TCOD_COLCTRL_4

enumerator TCOD_COLCTRL_5

enumerator TCOD_COLCTRL_NUMBER

enumerator TCOD_COLCTRL_FORE_RGB

enumerator TCOD_COLCTRL_BACK_RGB

enumerator TCOD_COLCTRL_STOP

Enum TCOD_distribution_t

• Defined in File mersenne_types.h

Enum Documentation

enum TCOD_distribution_t

Values:

enumerator TCOD_DISTRIBUTION_LINEAR

enumerator TCOD_DISTRIBUTION_GAUSSIAN

enumerator TCOD_DISTRIBUTION_GAUSSIAN_RANGE

enumerator TCOD_DISTRIBUTION_GAUSSIAN_INVERSE

enumerator TCOD_DISTRIBUTION_GAUSSIAN_RANGE_INVERSE

Enum TCOD_Error

• Defined in File error.h

Enum Documentation

enum TCOD_Error

An enum of libtcod error codes.

On values other than TCOD_E_OK you can use TCOD_get_error() to learn more information.

New in version 1.16.

Values:

enumerator TCOD_E_OK

The function completed successfully without issues.

A function is successful when (err >= 0). Positive values may be used for warnings, or for other outputs.

enumerator TCOD_E_ERROR

The error code for generic runtime errors.

The returned code my be changed in the future to something more specific. Use (err < 0) to check if the value is an error.

enumerator TCOD_E_INVALID_ARGUMENT

The function failed because a given input argument was invalid.

enumerator TCOD_E_OUT_OF_MEMORY

The function failed because it was unable to allocate enough memory.

enumerator TCOD_E_REQUIRES_ATTENTION

This function needs additional attention, but is otherwise functioning correctly.

See its documentation.

New in version 1.16.

enumerator TCOD_E_WARN

The function completed, but a minor issue was detected.

Enum TCOD_event_t

• Defined in File sys.h

Enum Documentation

enum TCOD_event_t

Values:

enumerator TCOD_EVENT_NONE

enumerator TCOD_EVENT_KEY_PRESS

enumerator TCOD_EVENT_KEY_RELEASE

enumerator TCOD_EVENT_KEY

enumerator TCOD_EVENT_MOUSE_MOVE

enumerator TCOD_EVENT_MOUSE_PRESS

enumerator TCOD_EVENT_MOUSE_RELEASE

enumerator TCOD_EVENT_MOUSE

enumerator TCOD_EVENT_FINGER_MOVE

enumerator TCOD_EVENT_FINGER_PRESS

enumerator TCOD_EVENT_FINGER_RELEASE

enumerator TCOD_EVENT_FINGER

enumerator TCOD_EVENT_ANY

Enum TCOD_font_flags_t

• Defined in File console_types.h

Enum Documentation

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.

Enum TCOD_fov_algorithm_t

• Defined in File fov_types.h

Enum Documentation

enum TCOD_fov_algorithm_t

Field-of-view options for TCOD_map_compute_fov().

Values:

enumerator FOV_BASIC

Trace multiple Bresenham lines along the perimeter.

Based on: http://www.roguebasin.com/index.php?title=Ray_casting

enumerator FOV_DIAMOND

Cast Bresenham line shadows on a per-tile basis.

Based on: http://www.oocities.org/temerra/los_rays.html

enumerator FOV_SHADOW

Recursive Shadowcast.

Based on: http://www.roguebasin.com/index.php?title=FOV_using_recursive_shadowcasting

enumerator FOV_PERMISSIVE_0

Precise Permissive Field of View.

Based on: http://www.roguebasin.com/index.php?title=Precise_Permissive_Field_of_View

enumerator FOV_PERMISSIVE_1

enumerator FOV_PERMISSIVE_2

enumerator FOV_PERMISSIVE_3

enumerator FOV_PERMISSIVE_4

enumerator FOV_PERMISSIVE_5

enumerator FOV_PERMISSIVE_6

enumerator FOV_PERMISSIVE_7

enumerator FOV_PERMISSIVE_8

enumerator FOV_RESTRICTIVE

Mingos’ Restrictive Precise Angle Shadowcasting (contribution by Mingos)

Based on: http://www.roguebasin.com/index.php?title=Restrictive_Precise_Angle_Shadowcasting

enumerator FOV_SYMMETRIC_SHADOWCAST

Symmetric Shadowcast.

Based on: https://www.albertford.com/shadowcasting/

New in version 1.16.

enumerator NB_FOV_ALGORITHMS

Enum TCOD_key_status_t

• Defined in File console_types.h

Enum Documentation

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

Enum TCOD_keycode_t

• Defined in File console_types.h

Enum Documentation

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

Enum TCOD_LogLevel

• Defined in File logging.h

Enum Documentation

enum TCOD_LogLevel

Values:

enumerator TCOD_LOG_DEBUG

enumerator TCOD_LOG_INFO

enumerator TCOD_LOG_WARNING

enumerator TCOD_LOG_ERROR

enumerator TCOD_LOG_CRITICAL

Enum TCOD_noise_type_t

• Defined in File noise.h

Enum Documentation

enum TCOD_noise_type_t

Values:

enumerator TCOD_NOISE_PERLIN

enumerator TCOD_NOISE_SIMPLEX

enumerator TCOD_NOISE_WAVELET

enumerator TCOD_NOISE_DEFAULT

Enum TCOD_random_algo_t

• Defined in File mersenne_types.h

Enum Documentation

enum TCOD_random_algo_t

Values:

enumerator TCOD_RNG_MT

Mersenne Twister implementation.

enumerator TCOD_RNG_CMWC

Complementary-Multiply-With-Carry implementation.

Enum TCOD_renderer_t

• Defined in File console_types.h

Enum Documentation

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

Enum TCOD_value_type_t

• Defined in File parser.h

Enum Documentation

enum TCOD_value_type_t

Values:

enumerator TCOD_TYPE_NONE

enumerator TCOD_TYPE_BOOL

enumerator TCOD_TYPE_CHAR

enumerator TCOD_TYPE_INT

enumerator TCOD_TYPE_FLOAT

enumerator TCOD_TYPE_STRING

enumerator TCOD_TYPE_COLOR

enumerator TCOD_TYPE_DICE

enumerator TCOD_TYPE_VALUELIST00

enumerator TCOD_TYPE_VALUELIST01

enumerator TCOD_TYPE_VALUELIST02

enumerator TCOD_TYPE_VALUELIST03

enumerator TCOD_TYPE_VALUELIST04

enumerator TCOD_TYPE_VALUELIST05

enumerator TCOD_TYPE_VALUELIST06

enumerator TCOD_TYPE_VALUELIST07

enumerator TCOD_TYPE_VALUELIST08

enumerator TCOD_TYPE_VALUELIST09

enumerator TCOD_TYPE_VALUELIST10

enumerator TCOD_TYPE_VALUELIST11

enumerator TCOD_TYPE_VALUELIST12

enumerator TCOD_TYPE_VALUELIST13

enumerator TCOD_TYPE_VALUELIST14

enumerator TCOD_TYPE_VALUELIST15

enumerator TCOD_TYPE_CUSTOM00

enumerator TCOD_TYPE_CUSTOM01

enumerator TCOD_TYPE_CUSTOM02

enumerator TCOD_TYPE_CUSTOM03

enumerator TCOD_TYPE_CUSTOM04

enumerator TCOD_TYPE_CUSTOM05

enumerator TCOD_TYPE_CUSTOM06

enumerator TCOD_TYPE_CUSTOM07

enumerator TCOD_TYPE_CUSTOM08

enumerator TCOD_TYPE_CUSTOM09

enumerator TCOD_TYPE_CUSTOM10

enumerator TCOD_TYPE_CUSTOM11

enumerator TCOD_TYPE_CUSTOM12

enumerator TCOD_TYPE_CUSTOM13

enumerator TCOD_TYPE_CUSTOM14

enumerator TCOD_TYPE_CUSTOM15

enumerator TCOD_TYPE_LIST

Unions

Union TCOD_Random

• Defined in File mersenne_types.h

Union Documentation

union TCOD_Random

#include <mersenne_types.h>

Pseudorandom number generator toolkit, all attributes are private.

Public Members

TCOD_random_algo_t algorithm

struct TCOD_Random_MT_CMWC mt_cmwc

Union TCOD_value_t

• Defined in File parser.h

Union Documentation

union TCOD_value_t

Public Members

bool b

char c

int32_t i

float f

char *s

TCOD_color_t col

TCOD_dice_t dice

TCOD_list_t list

void *custom

Functions

Function tcod::blit

• Defined in File console.hpp

Function Documentation

inline void tcod::blit(TCOD_Console &dest, const TCOD_Console &source, const std::array<int, 2> &dest_xy = {0, 0}, std::array<int, 4> source_rect = {0, 0, 0, 0}, float foreground_alpha = 1.0f, float background_alpha = 1.0f)

Blit a region of tiles from one console to another.

Parameters:

• dest – The destination console.

• source – The source console to blit from.

• dest_xy – The upper-left position of the destination console to blit to.

• source_rect – The source region {left, top, width, height} to blit from. A width or height of zero will use the entire console.

• foreground_alpha –

• background_alpha –

Function tcod::check_path

• Defined in File error.hpp

Function Documentation

inline void tcod::check_path(const std::filesystem::path &path)

Throw an exception if the given path does not exist.

Used internally.

Function tcod::check_throw_error(int)

• Defined in File error.hpp

Function Documentation

inline int tcod::check_throw_error(int error)

Check and throw error messages.

Used internally.

Function tcod::check_throw_error(TCOD_Error)

• Defined in File error.hpp

Function Documentation

inline TCOD_Error tcod::check_throw_error(TCOD_Error error)

Function tcod::console::init_root(int, int, const std::string&, bool, TCOD_renderer_t)

• Defined in File console_init.h

Function Documentation

void tcod::console::init_root(int w, int h, const std::string &title, bool fullscreen, TCOD_renderer_t renderer)

Function tcod::console::init_root(int, int, const std::string&, bool, TCOD_renderer_t, bool)

• Defined in File console_init.h

Function Documentation

void tcod::console::init_root(int w, int h, const std::string &title, bool fullscreen, TCOD_renderer_t renderer, bool vsync)

Function tcod::draw_frame

• Defined in File console_drawing.h

Function Documentation

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.

Function tcod::draw_quartergraphics

• Defined in File image.hpp

Function Documentation

inline void tcod::draw_quartergraphics(TCOD_Console &dest, const TCOD_Image &source, const std::array<int, 2> &dest_xy = {0, 0}, const std::array<int, 4> &src_rect = {0, 0, -1, -1})

Draw a double resolution image on a console using quadrant character glyphs.

auto console = tcod::Console{80, 50};
TCODImage* image = new TCODImage(console.get_width() * 2, console.get_height() * 2);
tcod::draw_quartergraphics(console, image);

New in version 1.19.

Parameters:

• dest – The console to draw to.

• source – The source image which will be rendered.

• dest_xy – The upper-left position to where the source will be drawn.

• source_rect – The {left, top, width, height} region of the source image to draw. A width or height of -1 will use the full size of the image.

Function tcod::draw_rect

• Defined in File console_drawing.h

Function Documentation

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.

Function tcod::get_height_rect

• Defined in File console_printing.hpp

Function Documentation

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.

Function tcod::load_bdf

• Defined in File tileset_bdf.hpp

Function Documentation

inline auto tcod::load_bdf(const std::filesystem::path &path) -> TilesetPtr

Load a Tileset from a BDF font file.

Will throw an exception on a missing or corrupt file.

New in version 1.19.

Template Function tcod::load_tilesheet

• Defined in File tileset.hpp

Function Documentation

template<typename ArrayType>
inline auto tcod::load_tilesheet(const std::filesystem::path &path, const std::array<int, 2> &columns_rows, const ArrayType &charmap) -> Tileset

Load a tilesheet from a PNG file.

An exception will be thrown if the file is missing or corrupt.

Tiles are indexed in row-major order and should be assigned to Unicode codepoints.

New in version 1.19.

Template Parameters:

ArrayType – Must be a std::vector or std::array like type. With size() and data() methods.

Parameters:

• path – The file path to the PNG tilesheet image.

• columns_rows – The shape of the grid on the tileset as {columns, rows}.

• charmap – An array of characters where charmap[tile_index] = codepoint. tcod::CHARMAP_CP437 or tcod::CHARMAP_TCOD are typical values for this argument.

Returns:

TilesetPtr A unique pointer to a TCOD_Tileset.

Function tcod::load_xp

• Defined in File console_rexpaint.hpp

Function Documentation

inline std::vector<tcod::ConsolePtr> tcod::load_xp(const std::filesystem::path &path)

Load an array of consoles from a REXPaint file.

New in version 1.18.

Parameters:

path – The path to the REXPaint file to load.

Returns:

Returns a vector of consoles.

Function tcod::new_context(const TCOD_ContextParams&, TCOD_Error&)

• Defined in File context_init.h

Function Documentation

inline auto tcod::new_context(const TCOD_ContextParams &params, TCOD_Error &out_code) -> ContextPtr

Initialize and return a new libtcod context.

Also returns an error code for non-critical issues.

For critical issues an exception is thrown as usual. Non-critical issues are things such as being unable to create a desired renderer and using to a fallback instead.

New in version 1.19.

Parameters:

• params – Options to configure the new context with.

• out_code – Will be set to an error code on non-critical issues.

Returns:

ContextPtr A pointer to the new context.

Function tcod::new_context(const TCOD_ContextParams&)

• Defined in File context_init.h

Function Documentation

inline auto tcod::new_context(const TCOD_ContextParams &params) -> ContextPtr

Initialize and return a new libtcod context.

Parameters:

params – Options to configure the new context with.

Returns:

ContextPtr A pointer to the new context.

New in version 1.19.

Function tcod::print

• Defined in File console_printing.hpp

Function Documentation

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.

Function tcod::print_frame

• Defined in File console_printing.hpp

Function Documentation

inline void tcod::print_frame(struct TCOD_Console &console, const std::array<int, 4> &rect, std::string_view title, const TCOD_ColorRGB *fg, const TCOD_ColorRGB *bg, TCOD_bkgnd_flag_t flag = TCOD_BKGND_SET, bool clear = true)

Function tcod::print_rect

• Defined in File console_printing.hpp

Function Documentation

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.

Function tcod::save_xp

• Defined in File console_rexpaint.hpp

Function Documentation

inline void tcod::save_xp(const std::vector<const TCOD_Console*> &consoles, const std::filesystem::path &path, int compress_level = 9)

Save an array of consoles to a REXPaint file.

New in version 1.18.

Parameters:

• consoles – A vector of consoles to save.

• path – The path to write the REXPaint file to.

• compress_level – A compression level for the zlib library.

Function tcod::sdl2::process_event(const union SDL_Event&, TCOD_key_t&)

• Defined in File event.h

Function Documentation

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.

Function tcod::sdl2::process_event(const union SDL_Event&, TCOD_mouse_t&)

• Defined in File event.h

Function Documentation

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.

Function tcod::set_error(const std::string&)

• Defined in File error.hpp

Function Documentation

inline TCOD_Error tcod::set_error(const std::string &msg)

Set an error message and return a relevant error code, usually -1.

Used internally.

Function tcod::set_error(const std::exception&)

• Defined in File error.hpp

Function Documentation

inline TCOD_Error tcod::set_error(const std::exception &e)

Template Function tcod::stringf

• Defined in File console_printing.hpp

Function Documentation

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.

Function tcod::tileset::new_fallback_tileset

• Defined in File tileset_fallback.hpp

Function Documentation

inline auto tcod::tileset::new_fallback_tileset(const std::array<int, 2> &tile_size = {0, 12}) -> TilesetPtr

Function TCOD_bsp_contains

• Defined in File bsp.h

Function Documentation

bool TCOD_bsp_contains(TCOD_bsp_t *node, int x, int y)

Function TCOD_bsp_delete

• Defined in File bsp.h

Function Documentation

void TCOD_bsp_delete(TCOD_bsp_t *node)

Function TCOD_bsp_father

• Defined in File bsp.h

Function Documentation

TCOD_bsp_t *TCOD_bsp_father(TCOD_bsp_t *node)

Function TCOD_bsp_find_node

• Defined in File bsp.h

Function Documentation

TCOD_bsp_t *TCOD_bsp_find_node(TCOD_bsp_t *node, int x, int y)

Function TCOD_bsp_is_leaf

• Defined in File bsp.h

Function Documentation

bool TCOD_bsp_is_leaf(TCOD_bsp_t *node)

Function TCOD_bsp_left

• Defined in File bsp.h

Function Documentation

TCOD_bsp_t *TCOD_bsp_left(TCOD_bsp_t *node)

Function TCOD_bsp_new

• Defined in File bsp.h

Function Documentation

TCOD_bsp_t *TCOD_bsp_new(void)

Function TCOD_bsp_new_with_size

• Defined in File bsp.h

Function Documentation

TCOD_bsp_t *TCOD_bsp_new_with_size(int x, int y, int w, int h)

Function TCOD_bsp_remove_sons

• Defined in File bsp.h

Function Documentation

void TCOD_bsp_remove_sons(TCOD_bsp_t *node)

Function TCOD_bsp_resize

• Defined in File bsp.h

Function Documentation

void TCOD_bsp_resize(TCOD_bsp_t *node, int x, int y, int w, int h)

Function TCOD_bsp_right

• Defined in File bsp.h

Function Documentation

TCOD_bsp_t *TCOD_bsp_right(TCOD_bsp_t *node)

Function TCOD_bsp_split_once

• Defined in File bsp.h

Function Documentation

void TCOD_bsp_split_once(TCOD_bsp_t *node, bool horizontal, int position)

Function TCOD_bsp_split_recursive

• Defined in File bsp.h

Function Documentation

void TCOD_bsp_split_recursive(TCOD_bsp_t *node, TCOD_Random *randomizer, int nb, int minHSize, int minVSize, float maxHRatio, float maxVRatio)

Function TCOD_bsp_traverse_in_order

• Defined in File bsp.h

Function Documentation

bool TCOD_bsp_traverse_in_order(TCOD_bsp_t *node, TCOD_bsp_callback_t listener, void *userData)

Function TCOD_bsp_traverse_inverted_level_order

• Defined in File bsp.h

Function Documentation

bool TCOD_bsp_traverse_inverted_level_order(TCOD_bsp_t *node, TCOD_bsp_callback_t listener, void *userData)

Function TCOD_bsp_traverse_level_order

• Defined in File bsp.h

Function Documentation

bool TCOD_bsp_traverse_level_order(TCOD_bsp_t *node, TCOD_bsp_callback_t listener, void *userData)

Function TCOD_bsp_traverse_post_order

• Defined in File bsp.h

Function Documentation

bool TCOD_bsp_traverse_post_order(TCOD_bsp_t *node, TCOD_bsp_callback_t listener, void *userData)

Function TCOD_bsp_traverse_pre_order

• Defined in File bsp.h

Function Documentation

bool TCOD_bsp_traverse_pre_order(TCOD_bsp_t *node, TCOD_bsp_callback_t listener, void *userData)

Function TCOD_clear_error

• Defined in File error.h

Function Documentation

void TCOD_clear_error(void)

Clear a current existing error message.

New in version 1.16.

Function TCOD_close_library

• Defined in File sys.h

Function Documentation

void TCOD_close_library(TCOD_library_t)

Function TCOD_color_add

• Defined in File color.h

Function Documentation

TCOD_color_t TCOD_color_add(TCOD_color_t c1, TCOD_color_t c2)

Function TCOD_color_add_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_color_add_wrapper(colornum_t c1, colornum_t c2)

Function TCOD_color_alpha_blend

• Defined in File color.h

Function Documentation

void TCOD_color_alpha_blend(TCOD_ColorRGBA *dst, const TCOD_ColorRGBA *src)

Blend src into dst as an alpha blending operation.

New in version 1.16.

Function TCOD_color_equals

• Defined in File color.h

Function Documentation

bool TCOD_color_equals(TCOD_color_t c1, TCOD_color_t c2)

Function TCOD_color_equals_wrapper

• Defined in File wrappers.h

Function Documentation

bool TCOD_color_equals_wrapper(colornum_t c1, colornum_t c2)

Function TCOD_color_gen_map

• Defined in File color.h

Function Documentation

void TCOD_color_gen_map(TCOD_color_t *map, int nb_key, const TCOD_color_t *key_color, const int *key_index)

Function TCOD_color_get_HSV

• Defined in File color.h

Function Documentation

void TCOD_color_get_HSV(TCOD_color_t color, float *hue, float *saturation, float *value)

Function TCOD_color_get_HSV_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_color_get_HSV_wrapper(colornum_t c, float *h, float *s, float *v)

Function TCOD_color_get_hue

• Defined in File color.h

Function Documentation

float TCOD_color_get_hue(TCOD_color_t color)

Function TCOD_color_get_hue_wrapper

• Defined in File wrappers.h

Function Documentation

float TCOD_color_get_hue_wrapper(colornum_t c)

Function TCOD_color_get_saturation

• Defined in File color.h

Function Documentation

float TCOD_color_get_saturation(TCOD_color_t color)

Function TCOD_color_get_saturation_wrapper

• Defined in File wrappers.h

Function Documentation

float TCOD_color_get_saturation_wrapper(colornum_t c)

Function TCOD_color_get_value

• Defined in File color.h

Function Documentation

float TCOD_color_get_value(TCOD_color_t color)

Function TCOD_color_get_value_wrapper

• Defined in File wrappers.h

Function Documentation

float TCOD_color_get_value_wrapper(colornum_t c)

Function TCOD_color_HSV

• Defined in File color.h

Function Documentation

TCOD_color_t TCOD_color_HSV(float hue, float saturation, float value)

Function TCOD_color_lerp

• Defined in File color.h

Function Documentation

TCOD_color_t TCOD_color_lerp(TCOD_color_t c1, TCOD_color_t c2, float coef)

Function TCOD_color_lerp_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_color_lerp_wrapper(colornum_t c1, colornum_t c2, float coef)

Function TCOD_color_multiply

• Defined in File color.h

Function Documentation

TCOD_color_t TCOD_color_multiply(TCOD_color_t c1, TCOD_color_t c2)

Function TCOD_color_multiply_scalar

• Defined in File color.h

Function Documentation

TCOD_color_t TCOD_color_multiply_scalar(TCOD_color_t c1, float value)

Function TCOD_color_multiply_scalar_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_color_multiply_scalar_wrapper(colornum_t c1, float value)

Function TCOD_color_multiply_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_color_multiply_wrapper(colornum_t c1, colornum_t c2)

Function TCOD_color_RGB

• Defined in File color.h

Function Documentation

TCOD_color_t TCOD_color_RGB(uint8_t r, uint8_t g, uint8_t b)

Function TCOD_color_scale_HSV

• Defined in File color.h

Function Documentation

void TCOD_color_scale_HSV(TCOD_color_t *color, float saturation_coef, float value_coef)

Function TCOD_color_set_HSV

• Defined in File color.h

Function Documentation

void TCOD_color_set_HSV(TCOD_color_t *color, float hue, float saturation, float value)

Function TCOD_color_set_hue

• Defined in File color.h

Function Documentation

void TCOD_color_set_hue(TCOD_color_t *color, float hue)

Function TCOD_color_set_saturation

• Defined in File color.h

Function Documentation

void TCOD_color_set_saturation(TCOD_color_t *color, float saturation)

Function TCOD_color_set_value

• Defined in File color.h

Function Documentation

void TCOD_color_set_value(TCOD_color_t *color, float value)

Function TCOD_color_shift_hue

• Defined in File color.h

Function Documentation

void TCOD_color_shift_hue(TCOD_color_t *color, float shift)

Function TCOD_color_subtract

• Defined in File color.h

Function Documentation

TCOD_color_t TCOD_color_subtract(TCOD_color_t c1, TCOD_color_t c2)

Function TCOD_color_subtract_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_color_subtract_wrapper(colornum_t c1, colornum_t c2)

Function TCOD_condition_broadcast

• Defined in File sys.h

Function Documentation

void TCOD_condition_broadcast(TCOD_cond_t sem)

Function TCOD_condition_delete

• Defined in File sys.h

Function Documentation

void TCOD_condition_delete(TCOD_cond_t sem)

Function TCOD_condition_new

• Defined in File sys.h

Function Documentation

TCOD_cond_t TCOD_condition_new(void)

Function TCOD_condition_signal

• Defined in File sys.h

Function Documentation

void TCOD_condition_signal(TCOD_cond_t sem)

Function TCOD_condition_wait

• Defined in File sys.h

Function Documentation

void TCOD_condition_wait(TCOD_cond_t sem, TCOD_mutex_t mut)

Function TCOD_console_blit

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_blit_key_color

• Defined in File console.h

Function Documentation

void TCOD_console_blit_key_color(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, const TCOD_color_t *key_color)

Function TCOD_console_check_for_keypress

• Defined in File console_etc.h

Function Documentation

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

Function TCOD_console_check_for_keypress_wrapper

• Defined in File wrappers.h

Function Documentation

bool TCOD_console_check_for_keypress_wrapper(TCOD_key_t *holder, int flags)

Function TCOD_console_clear

• Defined in File console.h

Function Documentation

void TCOD_console_clear(TCOD_Console *con)

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

Function TCOD_console_credits

• Defined in File console_etc.h

Function Documentation

void TCOD_console_credits(void)

Function TCOD_console_credits_render

• Defined in File console_etc.h

Function Documentation

bool TCOD_console_credits_render(int x, int y, bool alpha)

Function TCOD_console_credits_render_ex

• Defined in File console_etc.h

Function Documentation

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.

Function TCOD_console_credits_reset

• Defined in File console_etc.h

Function Documentation

void TCOD_console_credits_reset(void)

Function TCOD_console_delete

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_disable_keyboard_repeat

• Defined in File console_etc.h

Function Documentation

void TCOD_console_disable_keyboard_repeat(void)

Function TCOD_console_double_hline

• Defined in File wrappers.h

Function Documentation

void TCOD_console_double_hline(TCOD_console_t con, int x, int y, int l, TCOD_bkgnd_flag_t flag)

Function TCOD_console_double_vline

• Defined in File wrappers.h

Function Documentation

void TCOD_console_double_vline(TCOD_console_t con, int x, int y, int l, TCOD_bkgnd_flag_t flag)

Function TCOD_console_draw_frame_rgb

• Defined in File console_drawing.h

Function Documentation

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.

Function TCOD_console_draw_rect_rgb

• Defined in File console_drawing.h

Function Documentation

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.

Function TCOD_console_fill_background

• Defined in File wrappers.h

Function Documentation

void TCOD_console_fill_background(TCOD_console_t con, int *r, int *g, int *b)

Function TCOD_console_fill_char

• Defined in File wrappers.h

Function Documentation

void TCOD_console_fill_char(TCOD_console_t con, int *arr)

Function TCOD_console_fill_foreground

• Defined in File wrappers.h

Function Documentation

void TCOD_console_fill_foreground(TCOD_console_t con, int *r, int *g, int *b)

Function TCOD_console_flush

• Defined in File console_etc.h

Function Documentation

TCOD_Error TCOD_console_flush(void)

Render and present the root console to the active display.

Function TCOD_console_flush_ex

• Defined in File console_etc.h

Function Documentation

TCOD_Error TCOD_console_flush_ex(TCOD_Console *console, struct TCOD_ViewportOptions *viewport)

Render and present a console with optional viewport options.

console is the console to render.

viewport is optional.

Returns a negative values on error. See TCOD_get_error.

New in version 1.16.

Function TCOD_console_from_file

• Defined in File console_etc.h

Function Documentation

TCOD_console_t TCOD_console_from_file(const char *filename)

Function TCOD_console_from_xp

• Defined in File console_rexpaint.h

Function Documentation

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.

Function TCOD_console_get_alignment

• Defined in File console.h

Function Documentation

TCOD_alignment_t TCOD_console_get_alignment(TCOD_Console *con)

Return a consoles default alignment.

Function TCOD_console_get_background_flag

• Defined in File console.h

Function Documentation

TCOD_bkgnd_flag_t TCOD_console_get_background_flag(TCOD_Console *con)

Return a consoles default background flag.

Function TCOD_console_get_char

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_get_char_background

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_get_char_background_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_console_get_char_background_wrapper(TCOD_console_t con, int x, int y)

Function TCOD_console_get_char_foreground

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_get_char_foreground_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_console_get_char_foreground_wrapper(TCOD_console_t con, int x, int y)

Function TCOD_console_get_default_background

• Defined in File console.h

Function Documentation

TCOD_color_t TCOD_console_get_default_background(TCOD_Console *con)

Function TCOD_console_get_default_background_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_console_get_default_background_wrapper(TCOD_console_t con)

Function TCOD_console_get_default_foreground

• Defined in File console.h

Function Documentation

TCOD_color_t TCOD_console_get_default_foreground(TCOD_Console *con)

Function TCOD_console_get_default_foreground_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_console_get_default_foreground_wrapper(TCOD_console_t con)

Function TCOD_console_get_fade

• Defined in File console.h

Function Documentation

uint8_t TCOD_console_get_fade(void)

Return the fade value.

Returns:

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

Function TCOD_console_get_fading_color

• Defined in File console.h

Function Documentation

TCOD_color_t TCOD_console_get_fading_color(void)

Return the fade color.

Returns:

The current fading color.

Function TCOD_console_get_fading_color_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_console_get_fading_color_wrapper(void)

Function TCOD_console_get_height

• Defined in File console.h

Function Documentation

int TCOD_console_get_height(const TCOD_Console *con)

Return the height of a console.

Function TCOD_console_get_height_rect

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_get_height_rect_fmt

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_get_height_rect_n

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_get_height_rect_utf

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_get_height_rect_wn

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_get_width

• Defined in File console.h

Function Documentation

int TCOD_console_get_width(const TCOD_Console *con)

Return the width of a console.

Function TCOD_console_has_mouse_focus

• Defined in File console_init.h

Function Documentation

bool TCOD_console_has_mouse_focus(void)

Return true if the window has mouse focus.

Function TCOD_console_hline

• Defined in File console_drawing.h

Function Documentation

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.

Function TCOD_console_init_root

• Defined in File console_init.h

Function Documentation

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.

Function TCOD_console_is_active

• Defined in File console_init.h

Function Documentation

bool TCOD_console_is_active(void)

Return true if the window has keyboard focus.

Function TCOD_console_is_fullscreen

• Defined in File console_init.h

Function Documentation

bool TCOD_console_is_fullscreen(void)

Return true if the display is full-screen.

Function TCOD_console_is_key_pressed

• Defined in File console_etc.h

Function Documentation

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.

Function TCOD_console_is_window_closed

• Defined in File console_init.h

Function Documentation

bool TCOD_console_is_window_closed(void)

Return true if the window is closing.

Function TCOD_console_list_from_xp

• Defined in File console_rexpaint.h

Function Documentation

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.

Function TCOD_console_list_save_xp

• Defined in File console_rexpaint.h

Function Documentation

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.

Function TCOD_console_load_apf

• Defined in File console_etc.h

Function Documentation

bool TCOD_console_load_apf(TCOD_console_t con, const char *filename)

Function TCOD_console_load_asc

• Defined in File console_etc.h

Function Documentation

bool TCOD_console_load_asc(TCOD_console_t con, const char *filename)

Function TCOD_console_load_xp

• Defined in File console_rexpaint.h

Function Documentation

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.

Function TCOD_console_map_ascii_code_to_font

• Defined in File console_etc.h

Function Documentation

void TCOD_console_map_ascii_code_to_font(int asciiCode, int fontCharX, int fontCharY)

Function TCOD_console_map_ascii_codes_to_font

• Defined in File console_etc.h

Function Documentation

void TCOD_console_map_ascii_codes_to_font(int asciiCode, int nbCodes, int fontCharX, int fontCharY)

Function TCOD_console_map_string_to_font

• Defined in File console_etc.h

Function Documentation

void TCOD_console_map_string_to_font(const char *s, int fontCharX, int fontCharY)

Function TCOD_console_map_string_to_font_utf

• Defined in File console_etc.h

Function Documentation

void TCOD_console_map_string_to_font_utf(const wchar_t *s, int fontCharX, int fontCharY)

Function TCOD_console_new

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_print

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_print_double_frame

• Defined in File wrappers.h

Function Documentation

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

Function TCOD_console_print_ex

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_print_ex_utf

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_print_frame

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_print_rect

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_print_rect_ex

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_print_rect_ex_utf

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_print_rect_utf

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_print_return_string

• Defined in File wrappers.h

Function Documentation

char *TCOD_console_print_return_string(TCOD_console_t con, int x, int y, int rw, int rh, TCOD_bkgnd_flag_t flag, TCOD_alignment_t align, char *msg, bool can_split, bool count_only)

Function TCOD_console_print_utf

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_printf

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_printf_ex

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_printf_frame

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_printf_rect

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_printf_rect_ex

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_printn

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_printn_frame

• Defined in File console_printing.h

Function Documentation

TCOD_Error TCOD_console_printn_frame(TCOD_Console *console, int x, int y, int width, int height, size_t n, const char *title, const TCOD_ColorRGB *fg, const TCOD_ColorRGB *bg, TCOD_bkgnd_flag_t flag, bool clear)

Function TCOD_console_printn_rect

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_put_char

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_put_char_ex

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_put_char_ex_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_console_put_char_ex_wrapper(TCOD_console_t con, int x, int y, int c, colornum_t fore, colornum_t back)

Function TCOD_console_put_rgb

• Defined in File console_drawing.h

Function Documentation

void TCOD_console_put_rgb(TCOD_Console *console, int x, int y, int ch, const TCOD_color_t *fg, const TCOD_color_t *bg, TCOD_bkgnd_flag_t flag)

Place a single tile on a console at x,y.

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.

Function TCOD_console_rect

• Defined in File console_drawing.h

Function Documentation

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.

Function TCOD_console_save_apf

• Defined in File console_etc.h

Function Documentation

bool TCOD_console_save_apf(TCOD_console_t con, const char *filename)

Function TCOD_console_save_asc

• Defined in File console_etc.h

Function Documentation

bool TCOD_console_save_asc(TCOD_console_t con, const char *filename)

Function TCOD_console_save_xp

• Defined in File console_rexpaint.h

Function Documentation

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.

Function TCOD_console_set_alignment

• Defined in File console.h

Function Documentation

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

Function TCOD_console_set_background_flag

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_set_char

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_set_char_background

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_set_char_background_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_console_set_char_background_wrapper(TCOD_console_t con, int x, int y, colornum_t col, TCOD_bkgnd_flag_t flag)

Function TCOD_console_set_char_foreground

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_set_char_foreground_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_console_set_char_foreground_wrapper(TCOD_console_t con, int x, int y, colornum_t col)

Function TCOD_console_set_color_control

• Defined in File console_printing.h

Function Documentation

void TCOD_console_set_color_control(TCOD_colctrl_t con, TCOD_color_t fore, TCOD_color_t back)

Function TCOD_console_set_color_control_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_console_set_color_control_wrapper(TCOD_colctrl_t con, colornum_t fore, colornum_t back)

Function TCOD_console_set_custom_font

• Defined in File console_etc.h

Function Documentation

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

Function TCOD_console_set_default_background

• Defined in File console.h

Function Documentation

void TCOD_console_set_default_background(TCOD_Console *con, TCOD_color_t col)

Function TCOD_console_set_default_background_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_console_set_default_background_wrapper(TCOD_console_t con, colornum_t col)

Function TCOD_console_set_default_foreground

• Defined in File console.h

Function Documentation

void TCOD_console_set_default_foreground(TCOD_Console *con, TCOD_color_t col)

Function TCOD_console_set_default_foreground_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_console_set_default_foreground_wrapper(TCOD_console_t con, colornum_t col)

Function TCOD_console_set_dirty

• Defined in File console_etc.h

Function Documentation

void TCOD_console_set_dirty(int x, int y, int w, int h)

Function TCOD_console_set_fade

• Defined in File console.h

Function Documentation

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.

Function TCOD_console_set_fade_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_console_set_fade_wrapper(uint8_t val, colornum_t fade)

Function TCOD_console_set_fullscreen

• Defined in File console_init.h

Function Documentation

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.

Function TCOD_console_set_key_color

• Defined in File console.h

Function Documentation

void TCOD_console_set_key_color(TCOD_Console *con, TCOD_color_t col)

Function TCOD_console_set_key_color_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_console_set_key_color_wrapper(TCOD_console_t con, colornum_t c)

Function TCOD_console_set_keyboard_repeat

• Defined in File console_etc.h

Function Documentation

void TCOD_console_set_keyboard_repeat(int initial_delay, int interval)

Function TCOD_console_set_window_title

• Defined in File console_init.h

Function Documentation

void TCOD_console_set_window_title(const char *title)

Change the title string of the active window.

Parameters:

title – A utf8 string.

Function TCOD_console_vline

• Defined in File console_drawing.h

Function Documentation

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.

Function TCOD_console_vprintf

• Defined in File console_printing.h

Function Documentation

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.

Function TCOD_console_vprintf_rect

• Defined in File console_printing.h

Function Documentation

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

Function TCOD_console_wait_for_keypress

• Defined in File console_etc.h

Function Documentation

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.

Function TCOD_console_wait_for_keypress_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_console_wait_for_keypress_wrapper(TCOD_key_t *holder, bool flush)

Function TCOD_context_change_tileset

• Defined in File context.h

Function Documentation

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

Change the active tileset for this context.

New in version 1.16.

Function TCOD_context_convert_event_coordinates

• Defined in File context.h

Function Documentation

TCOD_Error TCOD_context_convert_event_coordinates(struct TCOD_Context *context, union SDL_Event *event)

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

New in version 1.19.

Function TCOD_context_delete

• Defined in File context.h

Function Documentation

void TCOD_context_delete(struct TCOD_Context *renderer)

Delete a rendering context.

New in version 1.16.

Function TCOD_context_get_renderer_type

• Defined in File context.h

Function Documentation

int TCOD_context_get_renderer_type(struct TCOD_Context *context)

Return the TCOD_renderer_t renderer type for this context.

Returns a negative number on error, such as context being NULL.

New in version 1.16.

Function TCOD_context_get_sdl_renderer

• Defined in File context.h

Function Documentation

struct SDL_Renderer *TCOD_context_get_sdl_renderer(struct TCOD_Context *context)

Return a pointer the SDL_Renderer for this context if it uses one.

New in version 1.16.

Function TCOD_context_get_sdl_window

• Defined in File context.h

Function Documentation

struct SDL_Window *TCOD_context_get_sdl_window(struct TCOD_Context *context)

Return a pointer the SDL_Window for this context if it uses one.

New in version 1.16.

Function TCOD_context_new

• Defined in File context_init.h

Function Documentation

TCOD_Error TCOD_context_new(const TCOD_ContextParams *params, TCOD_Context **out)

Create a new context with the given parameters.

params is a non-NULL pointer to a TCOD_ContextParams struct. See its documentation for info on the parameters.

out is the output for the TCOD_Context, must not be NULL.

New in version 1.16.

Function TCOD_context_present

• Defined in File context.h

Function Documentation

TCOD_Error TCOD_context_present(struct TCOD_Context *context, const struct TCOD_Console *console, const struct TCOD_ViewportOptions *viewport)

Present a console to the screen, using a rendering context.

console is the console to present, the console can be any size.

viewport is the optional viewport options to use. This will affect the scaling of the console with the current context. This can be NULL to use the default options, which are to stretch the console to fit the screen.

New in version 1.16.

Function TCOD_context_recommended_console_size

• Defined in File context.h

Function Documentation

TCOD_Error TCOD_context_recommended_console_size(struct TCOD_Context *context, float magnification, int *columns, int *rows)

Set columns and rows to the recommended console size for this context.

magnification determines the apparent size of the tiles on the output. Values of 0.0f or lower will default to 1.0f.

New in version 1.16.

Function TCOD_context_save_screenshot

• Defined in File context.h

Function Documentation

TCOD_Error TCOD_context_save_screenshot(struct TCOD_Context *context, const char *filename)

Save the last presented console to a PNG file.

New in version 1.16.

Function TCOD_context_screen_capture

• Defined in File context.h

Function Documentation

TCOD_Error TCOD_context_screen_capture(struct TCOD_Context *context, TCOD_ColorRGBA *out_pixels, int *width, int *height)

Fill out_pixels with a screen capture.

New in version 1.22.

Parameters:

• context – A non-NULL TCOD_Context object.

• out_pixels – If NULL then width and height are filled with the output dimensions. If not NULL then width and height are verified and the capture will be written out.

• width – Pointer to fill with the expected image width.

• height – Pointer to fill with the expected image height.

Returns:

A negative error value is returned on errors, otherwise returns TCOD_E_OK.

Function TCOD_context_screen_capture_alloc

• Defined in File context.h

Function Documentation

TCOD_ColorRGBA *TCOD_context_screen_capture_alloc(struct TCOD_Context *context, int *width, int *height)

Allocate and return a screen capture.

The returned array must be freed with free().

New in version 1.22.

Parameters:

• context – A non-NULL TCOD_Context object.

• width – Pointer to fill with the allocated image width.

• height – Pointer to fill with the allocated image height.

Returns:

An allocated array of RGBA pixels which must be manually freed.

Function TCOD_context_screen_pixel_to_tile_d

• Defined in File context.h

Function Documentation

TCOD_Error TCOD_context_screen_pixel_to_tile_d(struct TCOD_Context *context, double *x, double *y)

Convert the screen coordinates to tile coordinates for this context.

x and y are the pointers to the screen coordinates, these will be converted to tile coordinates after the call to this function.

The parameters given to the last call to TCOD_context_present will determine where the tiles are for this call.

New in version 1.16.

Function TCOD_context_screen_pixel_to_tile_i

• Defined in File context.h

Function Documentation

TCOD_Error TCOD_context_screen_pixel_to_tile_i(struct TCOD_Context *context, int *x, int *y)

Convert the screen coordinates to integer tile coordinates for this context.

Save as TCOD_context_screen_pixel_to_tile but the inputs and results are integers. This is useful if you don’t need sub-tile coordinates.

New in version 1.16.

Function TCOD_context_set_mouse_transform

• Defined in File context.h

Function Documentation

TCOD_Error TCOD_context_set_mouse_transform(struct TCOD_Context *context, const TCOD_MouseTransform *transform)

Manually set the pixel-to-tile mouse position transformation.

New in version 1.24.

Parameters:

• context – A non-NULL TCOD_Context object.

• transform – The transform to assign to the context.

Returns:

A negative error value is returned on errors, otherwise returns TCOD_E_OK.

Function TCOD_dijkstra_compute

• Defined in File path.h

Function Documentation

void TCOD_dijkstra_compute(TCOD_dijkstra_t dijkstra, int root_x, int root_y)

Function TCOD_dijkstra_delete

• Defined in File path.h

Function Documentation

void TCOD_dijkstra_delete(TCOD_dijkstra_t dijkstra)

Function TCOD_dijkstra_get

• Defined in File path.h

Function Documentation

void TCOD_dijkstra_get(TCOD_dijkstra_t path, int index, int *x, int *y)

Function TCOD_dijkstra_get_distance

• Defined in File path.h

Function Documentation

float TCOD_dijkstra_get_distance(TCOD_dijkstra_t dijkstra, int x, int y)

Function TCOD_dijkstra_is_empty

• Defined in File path.h

Function Documentation

bool TCOD_dijkstra_is_empty(TCOD_dijkstra_t path)

Function TCOD_dijkstra_new

• Defined in File path.h

Function Documentation

TCOD_dijkstra_t TCOD_dijkstra_new(TCOD_map_t map, float diagonalCost)

Function TCOD_dijkstra_new_using_function

• Defined in File path.h

Function Documentation

TCOD_dijkstra_t TCOD_dijkstra_new_using_function(int map_width, int map_height, TCOD_path_func_t func, void *user_data, float diagonalCost)

Function TCOD_dijkstra_path_set

• Defined in File path.h

Function Documentation

bool TCOD_dijkstra_path_set(TCOD_dijkstra_t dijkstra, int x, int y)

Function TCOD_dijkstra_path_walk

• Defined in File path.h

Function Documentation

bool TCOD_dijkstra_path_walk(TCOD_dijkstra_t dijkstra, int *x, int *y)

Function TCOD_dijkstra_reverse

• Defined in File path.h

Function Documentation

void TCOD_dijkstra_reverse(TCOD_dijkstra_t path)

Function TCOD_dijkstra_size

• Defined in File path.h

Function Documentation

int TCOD_dijkstra_size(TCOD_dijkstra_t path)

Function TCOD_frontier_clear

• Defined in File pathfinder_frontier.h

Function Documentation

TCOD_Error TCOD_frontier_clear(struct TCOD_Frontier *frontier)

Remove all nodes from this frontier.

Function TCOD_frontier_delete

• Defined in File pathfinder_frontier.h

Function Documentation

void TCOD_frontier_delete(struct TCOD_Frontier *frontier)

Delete a pathfinder frontier.

Function TCOD_frontier_new

• Defined in File pathfinder_frontier.h

Function Documentation

struct TCOD_Frontier *TCOD_frontier_new(int ndim)

Create a new pathfinder frontier.

ndim is the number of dimensions. Must be in the range 1 <= n <= 4.

Function TCOD_frontier_pop

• Defined in File pathfinder_frontier.h

Function Documentation

TCOD_Error TCOD_frontier_pop(struct TCOD_Frontier *frontier)

Pop the next node from this frontier.

The popped node variables will placed in the active_dist and active_index attributes.

Function TCOD_frontier_push

• Defined in File pathfinder_frontier.h

Function Documentation

TCOD_Error TCOD_frontier_push(struct TCOD_Frontier *frontier, const int *index, int dist, int heuristic)

Add a node to this frontier.

index[frontier->ndim] is the position of the node to add to the frontier.

dist is the total distance of the node. This should be a low number like 0, but can also be a negative number such as INT_MIN. When adding a node as an edge then dist is frontier->active_dist plus the cost of the edge.

heuristic is the true priority of the node, used to affect node order. For Dijkstra-like algorithms this should be the same as dist. For A* this should be dist plus the maximum possible distance to the goal.

Function TCOD_frontier_size

• Defined in File pathfinder_frontier.h

Function Documentation

int TCOD_frontier_size(const struct TCOD_Frontier *frontier)

Return the current number of nodes in this frontier.

Function TCOD_get_default_tileset

• Defined in File globals.h

Function Documentation

TCOD_Tileset *TCOD_get_default_tileset(void)

Return the default tileset, may be NULL.

A non-NULL return value is a new reference to the global tileset. When you are done you will need to call TCOD_tileset_delete on this pointer.

This function is provisional, the API may change in the future.

New in version 1.19.

Function TCOD_get_error

• Defined in File error.h

Function Documentation

const char *TCOD_get_error(void)

Return the last error message.

If there is no error then the string will have a length of zero.

New in version 1.12.

Function TCOD_get_function_address

• Defined in File sys.h

Function Documentation

void *TCOD_get_function_address(TCOD_library_t library, const char *function_name)

Function TCOD_heap_clear

• Defined in File heapq.h

Function Documentation

void TCOD_heap_clear(struct TCOD_Heap *heap)

Function TCOD_heap_init

• Defined in File heapq.h

Function Documentation

int TCOD_heap_init(struct TCOD_Heap *heap, size_t data_size)

Function TCOD_heap_uninit

• Defined in File heapq.h

Function Documentation

void TCOD_heap_uninit(struct TCOD_Heap *heap)

Function TCOD_heightmap_add

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_add(TCOD_heightmap_t *hm, float value)

Function TCOD_heightmap_add_fbm

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_add_fbm(TCOD_heightmap_t *hm, TCOD_noise_t noise, float mul_x, float mul_y, float add_x, float add_y, float octaves, float delta, float scale)

Function TCOD_heightmap_add_hill

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_add_hill(TCOD_heightmap_t *hm, float hx, float hy, float h_radius, float h_height)

Function TCOD_heightmap_add_hm

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_add_hm(const TCOD_heightmap_t *hm1, const TCOD_heightmap_t *hm2, TCOD_heightmap_t *out)

Function TCOD_heightmap_add_voronoi

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_add_voronoi(TCOD_heightmap_t *hm, int nbPoints, int nbCoef, const float *coef, TCOD_Random *rnd)

Function TCOD_heightmap_clamp

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_clamp(TCOD_heightmap_t *hm, float min, float max)

Function TCOD_heightmap_clear

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_clear(TCOD_heightmap_t *hm)

Function TCOD_heightmap_copy

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_copy(const TCOD_heightmap_t *hm_source, TCOD_heightmap_t *hm_dest)

Function TCOD_heightmap_count_cells

• Defined in File heightmap.h

Function Documentation

int TCOD_heightmap_count_cells(const TCOD_heightmap_t *hm, float min, float max)

Function TCOD_heightmap_delete

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_delete(TCOD_heightmap_t *hm)

Function TCOD_heightmap_dig_bezier

• Defined in File heightmap.h

Function Documentation

Warning

doxygenfunction: Unable to resolve function “TCOD_heightmap_dig_bezier” with arguments (TCOD_heightmap_t*, int, int, float, float, float, float) in doxygen xml output for project “libtcod” from directory: doxyxml/. Potential matches:

- void TCOD_heightmap_dig_bezier(TCOD_heightmap_t *hm, int px[4], int py[4], float startRadius, float startDepth, float endRadius, float endDepth)

Function TCOD_heightmap_dig_hill

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_dig_hill(TCOD_heightmap_t *hm, float hx, float hy, float h_radius, float h_height)

Function TCOD_heightmap_get_interpolated_value

• Defined in File heightmap.h

Function Documentation

float TCOD_heightmap_get_interpolated_value(const TCOD_heightmap_t *hm, float x, float y)

Function TCOD_heightmap_get_minmax

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_get_minmax(const TCOD_heightmap_t *hm, float *min, float *max)

Function TCOD_heightmap_get_normal

• Defined in File heightmap.h

Function Documentation

Warning

doxygenfunction: Unable to resolve function “TCOD_heightmap_get_normal” with arguments (const TCOD_heightmap_t*, float, float, float, float) in doxygen xml output for project “libtcod” from directory: doxyxml/. Potential matches:

- void TCOD_heightmap_get_normal(const TCOD_heightmap_t *hm, float x, float y, float n[3], float waterLevel)

Function TCOD_heightmap_get_slope

• Defined in File heightmap.h

Function Documentation

float TCOD_heightmap_get_slope(const TCOD_heightmap_t *hm, int x, int y)

Function TCOD_heightmap_get_value

• Defined in File heightmap.h

Function Documentation

float TCOD_heightmap_get_value(const TCOD_heightmap_t *hm, int x, int y)

Function TCOD_heightmap_has_land_on_border

• Defined in File heightmap.h

Function Documentation

bool TCOD_heightmap_has_land_on_border(const TCOD_heightmap_t *hm, float waterLevel)

Function TCOD_heightmap_islandify

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_islandify(TCOD_heightmap_t *hm, float seaLevel, TCOD_Random *rnd)

Function TCOD_heightmap_kernel_transform

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_kernel_transform(TCOD_heightmap_t *hm, int kernel_size, const int *dx, const int *dy, const float *weight, float minLevel, float maxLevel)

Function TCOD_heightmap_lerp_hm

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_lerp_hm(const TCOD_heightmap_t *hm1, const TCOD_heightmap_t *hm2, TCOD_heightmap_t *out, float coef)

Function TCOD_heightmap_mid_point_displacement

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_mid_point_displacement(TCOD_heightmap_t *hm, TCOD_Random *rnd, float roughness)

Function TCOD_heightmap_multiply_hm

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_multiply_hm(const TCOD_heightmap_t *hm1, const TCOD_heightmap_t *hm2, TCOD_heightmap_t *out)

Function TCOD_heightmap_new

• Defined in File heightmap.h

Function Documentation

TCOD_heightmap_t *TCOD_heightmap_new(int w, int h)

Function TCOD_heightmap_normalize

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_normalize(TCOD_heightmap_t *hm, float min, float max)

Function TCOD_heightmap_rain_erosion

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_rain_erosion(TCOD_heightmap_t *hm, int nbDrops, float erosionCoef, float sedimentationCoef, TCOD_Random *rnd)

Function TCOD_heightmap_scale

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_scale(TCOD_heightmap_t *hm, float value)

Function TCOD_heightmap_scale_fbm

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_scale_fbm(TCOD_heightmap_t *hm, TCOD_noise_t noise, float mul_x, float mul_y, float add_x, float add_y, float octaves, float delta, float scale)

Function TCOD_heightmap_set_value

• Defined in File heightmap.h

Function Documentation

void TCOD_heightmap_set_value(TCOD_heightmap_t *hm, int x, int y, float value)

Function TCOD_image_blit

• Defined in File image.h

Function Documentation

void TCOD_image_blit(TCOD_Image *image, TCOD_console_t console, float x, float y, TCOD_bkgnd_flag_t bkgnd_flag, float scale_x, float scale_y, float angle)

Function TCOD_image_blit_2x

• Defined in File image.h

Function Documentation

void TCOD_image_blit_2x(const TCOD_Image *image, TCOD_Console *dest, int dx, int dy, int sx, int sy, int w, int h)

Function TCOD_image_blit_rect

• Defined in File image.h

Function Documentation

void TCOD_image_blit_rect(TCOD_Image *image, TCOD_console_t console, int x, int y, int w, int h, TCOD_bkgnd_flag_t bkgnd_flag)

Function TCOD_image_clear

• Defined in File image.h

Function Documentation

void TCOD_image_clear(TCOD_Image *image, TCOD_color_t color)

Function TCOD_image_clear_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_image_clear_wrapper(TCOD_image_t image, colornum_t color)

Function TCOD_image_delete

• Defined in File image.h

Function Documentation

void TCOD_image_delete(TCOD_Image *image)

Function TCOD_image_from_console

• Defined in File image.h

Function Documentation

TCOD_Image *TCOD_image_from_console(const TCOD_Console *console)

Return a new image rendered from a console.

This effectively returns a screenshot of the console.

Function TCOD_image_get_alpha

• Defined in File image.h

Function Documentation

int TCOD_image_get_alpha(const TCOD_Image *image, int x, int y)

Function TCOD_image_get_mipmap_pixel

• Defined in File image.h

Function Documentation

TCOD_color_t TCOD_image_get_mipmap_pixel(TCOD_Image *image, float x0, float y0, float x1, float y1)

Return a mipmapped pixel of image.

Mipmaps are updated when you call this, so it can’t be called from multiple threads.

Function TCOD_image_get_mipmap_pixel_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_image_get_mipmap_pixel_wrapper(TCOD_image_t image, float x0, float y0, float x1, float y1)

Function TCOD_image_get_pixel

• Defined in File image.h

Function Documentation

TCOD_color_t TCOD_image_get_pixel(const TCOD_Image *image, int x, int y)

Function TCOD_image_get_pixel_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_image_get_pixel_wrapper(TCOD_image_t image, int x, int y)

Function TCOD_image_get_size

• Defined in File image.h

Function Documentation

void TCOD_image_get_size(const TCOD_Image *image, int *w, int *h)

Function TCOD_image_hflip

• Defined in File image.h

Function Documentation

void TCOD_image_hflip(TCOD_Image *image)

Function TCOD_image_invert

• Defined in File image.h

Function Documentation

void TCOD_image_invert(TCOD_Image *image)

Function TCOD_image_is_pixel_transparent

• Defined in File image.h

Function Documentation

bool TCOD_image_is_pixel_transparent(const TCOD_Image *image, int x, int y)

Function TCOD_image_load

• Defined in File image.h

Function Documentation

TCOD_Image *TCOD_image_load(const char *filename)

Function TCOD_image_new

• Defined in File image.h

Function Documentation

TCOD_Image *TCOD_image_new(int width, int height)

Function TCOD_image_put_pixel

• Defined in File image.h

Function Documentation

void TCOD_image_put_pixel(TCOD_Image *image, int x, int y, TCOD_color_t col)

Function TCOD_image_put_pixel_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_image_put_pixel_wrapper(TCOD_image_t image, int x, int y, colornum_t col)

Function TCOD_image_refresh_console

• Defined in File image.h

Function Documentation

void TCOD_image_refresh_console(TCOD_Image *image, const TCOD_Console *console)

Same as TCOD_image_from_console, but with an existing image.

Function TCOD_image_rotate90

• Defined in File image.h

Function Documentation

void TCOD_image_rotate90(TCOD_Image *image, int numRotations)

Function TCOD_image_save

• Defined in File image.h

Function Documentation

TCOD_Error TCOD_image_save(const TCOD_Image *image, const char *filename)

Save an image to a PNG or BMP file.

Returns a negative error code on failure. Check TCOD_get_error for details.

Changed in version 1.16: Now returns TCOD_Error.

Function TCOD_image_scale

• Defined in File image.h

Function Documentation

void TCOD_image_scale(TCOD_Image *image, int new_w, int new_h)

Function TCOD_image_set_key_color

• Defined in File image.h

Function Documentation

void TCOD_image_set_key_color(TCOD_Image *image, TCOD_color_t key_color)

Function TCOD_image_set_key_color_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_image_set_key_color_wrapper(TCOD_image_t image, colornum_t key_color)

Function TCOD_image_vflip

• Defined in File image.h

Function Documentation

void TCOD_image_vflip(TCOD_Image *image)

Function TCOD_line

• Defined in File bresenham.h

Function Documentation

bool TCOD_line(int xFrom, int yFrom, int xTo, int yTo, TCOD_line_listener_t listener)

Function TCOD_line_init

• Defined in File bresenham.h

Function Documentation

void TCOD_line_init(int xFrom, int yFrom, int xTo, int yTo)

Function TCOD_line_init_mt

• Defined in File bresenham.h

Function Documentation

void TCOD_line_init_mt(int xFrom, int yFrom, int xTo, int yTo, TCOD_bresenham_data_t *data)

Function TCOD_line_mt

• Defined in File bresenham.h

Function Documentation

bool TCOD_line_mt(int xFrom, int yFrom, int xTo, int yTo, TCOD_line_listener_t listener, TCOD_bresenham_data_t *data)

Function TCOD_line_step

• Defined in File bresenham.h

Function Documentation

bool TCOD_line_step(int *xCur, int *yCur)

advance one step.

returns true if we reach destination

Function TCOD_line_step_mt

• Defined in File bresenham.h

Function Documentation

bool TCOD_line_step_mt(int *xCur, int *yCur, TCOD_bresenham_data_t *data)

Function TCOD_list_add_all

• Defined in File list.h

Function Documentation

void TCOD_list_add_all(TCOD_list_t l, TCOD_list_t l2)

Function TCOD_list_allocate

• Defined in File list.h

Function Documentation

TCOD_list_t TCOD_list_allocate(int nb_elements)

Function TCOD_list_begin

• Defined in File list.h

Function Documentation

void **TCOD_list_begin(TCOD_list_t l)

Function TCOD_list_clear

• Defined in File list.h

Function Documentation

void TCOD_list_clear(TCOD_list_t l)

Function TCOD_list_clear_and_delete

• Defined in File list.h

Function Documentation

void TCOD_list_clear_and_delete(TCOD_list_t l)

Function TCOD_list_contains

• Defined in File list.h

Function Documentation

bool TCOD_list_contains(TCOD_list_t l, const void *elt)

Function TCOD_list_delete

• Defined in File list.h

Function Documentation

void TCOD_list_delete(TCOD_list_t l)

Function TCOD_list_duplicate

• Defined in File list.h

Function Documentation

TCOD_list_t TCOD_list_duplicate(TCOD_list_t l)

Function TCOD_list_end

• Defined in File list.h

Function Documentation

void **TCOD_list_end(TCOD_list_t l)

Function TCOD_list_get

• Defined in File list.h

Function Documentation

void *TCOD_list_get(TCOD_list_t l, int idx)

Function TCOD_list_insert_before

• Defined in File list.h

Function Documentation

void **TCOD_list_insert_before(TCOD_list_t l, const void *elt, int before)

Function TCOD_list_is_empty

• Defined in File list.h

Function Documentation

bool TCOD_list_is_empty(TCOD_list_t l)

Function TCOD_list_new

• Defined in File list.h

Function Documentation

TCOD_list_t TCOD_list_new(void)

Function TCOD_list_peek

• Defined in File list.h

Function Documentation

void *TCOD_list_peek(TCOD_list_t l)

Function TCOD_list_pop

• Defined in File list.h

Function Documentation

void *TCOD_list_pop(TCOD_list_t l)

Function TCOD_list_push

• Defined in File list.h

Function Documentation

void TCOD_list_push(TCOD_list_t l, const void *elt)

Function TCOD_list_remove

• Defined in File list.h

Function Documentation

void TCOD_list_remove(TCOD_list_t l, const void *elt)

Function TCOD_list_remove_fast

• Defined in File list.h

Function Documentation

void TCOD_list_remove_fast(TCOD_list_t l, const void *elt)

Function TCOD_list_remove_iterator

• Defined in File list.h

Function Documentation

void **TCOD_list_remove_iterator(TCOD_list_t l, void **elt)

Function TCOD_list_remove_iterator_fast

• Defined in File list.h

Function Documentation

void **TCOD_list_remove_iterator_fast(TCOD_list_t l, void **elt)

Function TCOD_list_reverse

• Defined in File list.h

Function Documentation

void TCOD_list_reverse(TCOD_list_t l)

Function TCOD_list_set

• Defined in File list.h

Function Documentation

void TCOD_list_set(TCOD_list_t l, const void *elt, int idx)

Function TCOD_list_size

• Defined in File list.h

Function Documentation

int TCOD_list_size(TCOD_list_t l)

Function TCOD_load_bdf

• Defined in File tileset_bdf.h

Function Documentation

TCOD_Tileset *TCOD_load_bdf(const char *path)

Load a BDF font from a file path.

For the best results, you should use a BDF font with a cell-based monospace alignment.

May return NULL on failure. See TCOD_get_error for the error message.

New in version 1.16.

Function TCOD_load_bdf_memory

• Defined in File tileset_bdf.h

Function Documentation

TCOD_Tileset *TCOD_load_bdf_memory(int size, const unsigned char *buffer)

Load a BDF font from memory.

size is the byte length of buffer. buffer is the BDF data to load.

May return NULL on failure. See TCOD_get_error for the error message.

New in version 1.16.

Function TCOD_load_library

• Defined in File sys.h

Function Documentation

TCOD_library_t TCOD_load_library(const char *path)

Function TCOD_load_xp

• Defined in File console_rexpaint.h

Function Documentation

int TCOD_load_xp(const char *path, int n, TCOD_Console **out)

Load an array of consoles from a REXPaint file.

New in version 1.18.

Parameters:

• path – The path to the REXPaint file, can not be NULL.

• n – The size of the out array. Can be zero.

• out – The array to fill with loaded consoles.

Returns:

Returns the number of consoles held by the file. Returns a negative error code on error.

Function TCOD_load_xp_from_memory

• Defined in File console_rexpaint.h

Function Documentation

int TCOD_load_xp_from_memory(int n_data, const unsigned char *data, int n_out, TCOD_Console **out)

Load an array of consoles from a REXPaint file in memory.

You can call this function with n_out=0 and out=NULL to get the number of consoles in the file.

New in version 1.18.

Parameters:

• n_data – The length of the input data buffer.

• data – The buffer where the REXPaint file is held.

• n_out – The length of the output console out array. Can be zero.

• out – The array to fill with loaded consoles.

Returns:

Returns the number of consoles held by the file. Returns a negative error code on error.

Function TCOD_map_clear

• Defined in File fov.h

Function Documentation

void TCOD_map_clear(TCOD_Map *map, bool transparent, bool walkable)

Set all cell values on map to the given parameters.

This call also zeroes out the field-of-view attribute.

Function TCOD_map_compute_fov

• Defined in File fov.h

Function Documentation

TCOD_Error TCOD_map_compute_fov(TCOD_Map *map, int pov_x, int pov_y, int max_radius, bool light_walls, TCOD_fov_algorithm_t algo)

Calculate the field-of-view.

pov_x and pov_y are the used as the field-of-view source. These coordinates must be within the map.

max_radius is the maximum distance for the field-of-view algorithm.

If light_walls is false then only transparent cells will be touched by the field-of-view.

algo is one of the TCOD_fov_algorithm_t algorithms.

After this call you may check if a cell is within the field-of-view by calling TCOD_map_is_in_fov().

Returns an error code on failure. See TCOD_get_error() for details.

Function TCOD_map_copy

• Defined in File fov.h

Function Documentation

TCOD_Error TCOD_map_copy(const TCOD_Map *source, TCOD_Map *dest)

Clone map data from source to dest.

dest will be resized to match source if necessary.

Function TCOD_map_delete

• Defined in File fov.h

Function Documentation

void TCOD_map_delete(TCOD_Map *map)

Free a TCOD_Map object.

Function TCOD_map_get_height

• Defined in File fov.h

Function Documentation

int TCOD_map_get_height(const TCOD_Map *map)

Return the height of map.

Function TCOD_map_get_nb_cells

• Defined in File fov.h

Function Documentation

int TCOD_map_get_nb_cells(const TCOD_Map *map)

Return the total number of cells in map.

Function TCOD_map_get_width

• Defined in File fov.h

Function Documentation

int TCOD_map_get_width(const TCOD_Map *map)

Return the width of map.

Function TCOD_map_is_in_fov

• Defined in File fov.h

Function Documentation

bool TCOD_map_is_in_fov(const TCOD_Map *map, int x, int y)

Return true if this cell was touched by the current field-of-view.

Function TCOD_map_is_transparent

• Defined in File fov.h

Function Documentation

bool TCOD_map_is_transparent(const TCOD_Map *map, int x, int y)

Return true if this cell is transparent.

Function TCOD_map_is_walkable

• Defined in File fov.h

Function Documentation

bool TCOD_map_is_walkable(TCOD_Map *map, int x, int y)

Return true if this cell is walkable.

Function TCOD_map_new

• Defined in File fov.h

Function Documentation

TCOD_Map *TCOD_map_new(int width, int height)

Return a new TCOD_Map with width and height.

Function TCOD_map_set_in_fov

• Defined in File fov.h

Function Documentation

void TCOD_map_set_in_fov(TCOD_Map *map, int x, int y, bool fov)

Set the fov flag on a specific cell.

Function TCOD_map_set_properties

• Defined in File fov.h

Function Documentation

void TCOD_map_set_properties(TCOD_Map *map, int x, int y, bool is_transparent, bool is_walkable)

Change the properties of a single cell.

Function TCOD_minheap_heapify

• Defined in File heapq.h

Function Documentation

void TCOD_minheap_heapify(struct TCOD_Heap *minheap)

Function TCOD_minheap_pop

• Defined in File heapq.h

Function Documentation

void TCOD_minheap_pop(struct TCOD_Heap *minheap, void *out)

Function TCOD_minheap_push

• Defined in File heapq.h

Function Documentation

int TCOD_minheap_push(struct TCOD_Heap *minheap, int priority, const void *data)

Function TCOD_mouse_get_status

• Defined in File mouse.h

Function Documentation

TCOD_mouse_t TCOD_mouse_get_status(void)

Function TCOD_mouse_get_status_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_mouse_get_status_wrapper(TCOD_mouse_t *holder)

Function TCOD_mouse_includes_touch

• Defined in File mouse.h

Function Documentation

void TCOD_mouse_includes_touch(bool enable)

Function TCOD_mouse_is_cursor_visible

• Defined in File mouse.h

Function Documentation

bool TCOD_mouse_is_cursor_visible(void)

Function TCOD_mouse_move

• Defined in File mouse.h

Function Documentation

void TCOD_mouse_move(int x, int y)

Function TCOD_mouse_show_cursor

• Defined in File mouse.h

Function Documentation

void TCOD_mouse_show_cursor(bool visible)

Function TCOD_mutex_delete

• Defined in File sys.h

Function Documentation

void TCOD_mutex_delete(TCOD_mutex_t mut)

Function TCOD_mutex_in

• Defined in File sys.h

Function Documentation

void TCOD_mutex_in(TCOD_mutex_t mut)

Function TCOD_mutex_new

• Defined in File sys.h

Function Documentation

TCOD_mutex_t TCOD_mutex_new(void)

Function TCOD_mutex_out

• Defined in File sys.h

Function Documentation

void TCOD_mutex_out(TCOD_mutex_t mut)

Function TCOD_namegen_destroy

• Defined in File namegen.h

Function Documentation

void TCOD_namegen_destroy(void)

Function TCOD_namegen_generate

• Defined in File namegen.h

Function Documentation

char *TCOD_namegen_generate(const char *name, bool allocate)

Function TCOD_namegen_generate_custom

• Defined in File namegen.h

Function Documentation

char *TCOD_namegen_generate_custom(const char *name, const char *rule, bool allocate)

Function TCOD_namegen_get_nb_sets_wrapper

• Defined in File wrappers.h

Function Documentation

int TCOD_namegen_get_nb_sets_wrapper(void)

Function TCOD_namegen_get_sets

• Defined in File namegen.h

Function Documentation

TCOD_list_t TCOD_namegen_get_sets(void)

Function TCOD_namegen_get_sets_wrapper

• Defined in File wrappers.h

Function Documentation

void TCOD_namegen_get_sets_wrapper(char **sets)

Function TCOD_namegen_parse

• Defined in File namegen.h

Function Documentation

void TCOD_namegen_parse(const char *filename, TCOD_Random *random)

Function TCOD_noise_delete

• Defined in File noise.h

Function Documentation

void TCOD_noise_delete(TCOD_Noise *noise)

Function TCOD_noise_get

• Defined in File noise.h

Function Documentation

float TCOD_noise_get(TCOD_Noise *noise, const float *f)

Function TCOD_noise_get_ex

• Defined in File noise.h

Function Documentation

float TCOD_noise_get_ex(TCOD_Noise *noise, const float *f, TCOD_noise_type_t type)

Function TCOD_noise_get_fbm

• Defined in File noise.h

Function Documentation

float TCOD_noise_get_fbm(TCOD_Noise *noise, const float *f, float octaves)

Function TCOD_noise_get_fbm_ex

• Defined in File noise.h

Function Documentation

float TCOD_noise_get_fbm_ex(TCOD_Noise *noise, const float *f, float octaves, TCOD_noise_type_t type)

Function TCOD_noise_get_fbm_vectorized

• Defined in File noise.h

Function Documentation

void TCOD_noise_get_fbm_vectorized(TCOD_Noise *noise, TCOD_noise_type_t type, float octaves, int n, float *x, float *y, float *z, float *w, float *out)

Generate noise as a vectorized operation with fractional Brownian motion.

octaves are the number of samples to take.

The remaining parameters are the same as TCOD_noise_get_vectorized.

New in version 1.16.

Function TCOD_noise_get_turbulence

• Defined in File noise.h

Function Documentation

float TCOD_noise_get_turbulence(TCOD_Noise *noise, const float *f, float octaves)

Function TCOD_noise_get_turbulence_ex

• Defined in File noise.h

Function Documentation

float TCOD_noise_get_turbulence_ex(TCOD_Noise *noise, const float *f, float octaves, TCOD_noise_type_t type)

Function TCOD_noise_get_turbulence_vectorized

• Defined in File noise.h

Function Documentation

void TCOD_noise_get_turbulence_vectorized(TCOD_Noise *noise, TCOD_noise_type_t type, float octaves, int n, float *x, float *y, float *z, float *w, float *out)

Generate noise as a vectorized operation with turbulence.

octaves are the number of samples to take.

The remaining parameters are the same as TCOD_noise_get_vectorized.

New in version 1.16.

Function TCOD_noise_get_vectorized

• Defined in File noise.h

Function Documentation

void TCOD_noise_get_vectorized(TCOD_Noise *noise, TCOD_noise_type_t type, int n, float *x, float *y, float *z, float *w, float *out)

Generate noise as a vectorized operation.

noise is the TCOD_Noise object to be used. Its dimensions will determine how many input arrays are required.

type is which noise generator should be used. Can be TCOD_NOISE_DEFAULT to use the type set by the TCOD_Noise object.

n is the length of the input and output arrays.

x[n], y[n], z[n], w[n] are the input coordinates for the noise generator. For a 2D generator you’d provide the x[n] and y[n] arrays and leave the remaining arrays as NULL.

out[n] is the output array, which will receive the noise values.

New in version 1.16.

Function TCOD_noise_new

• Defined in File noise.h

Function Documentation

TCOD_Noise *TCOD_noise_new(int dimensions, float hurst, float lacunarity, TCOD_Random *random)

Function TCOD_noise_set_type

• Defined in File noise.h

Function Documentation

void TCOD_noise_set_type(TCOD_Noise *noise, TCOD_noise_type_t type)

Function TCOD_parse_bool_value

• Defined in File parser.h

Function Documentation

TCOD_value_t TCOD_parse_bool_value(void)

Function TCOD_parse_char_value

• Defined in File parser.h

Function Documentation

TCOD_value_t TCOD_parse_char_value(void)

Function TCOD_parse_color_value

• Defined in File parser.h

Function Documentation

TCOD_value_t TCOD_parse_color_value(void)

Function TCOD_parse_dice_value

• Defined in File parser.h

Function Documentation

TCOD_value_t TCOD_parse_dice_value(void)

Function TCOD_parse_float_value

• Defined in File parser.h

Function Documentation

TCOD_value_t TCOD_parse_float_value(void)

Function TCOD_parse_integer_value

• Defined in File parser.h

Function Documentation

TCOD_value_t TCOD_parse_integer_value(void)

Function TCOD_parse_property_value

• Defined in File parser.h

Function Documentation

TCOD_value_t TCOD_parse_property_value(TCOD_Parser *parser, TCOD_ParserStruct *def, char *propname, bool list)

Function TCOD_parse_string_value

• Defined in File parser.h

Function Documentation

TCOD_value_t TCOD_parse_string_value(void)

Function TCOD_parse_value_list_value

• Defined in File parser.h

Function Documentation

TCOD_value_t TCOD_parse_value_list_value(TCOD_ParserStruct *def, int list_num)

Function TCOD_parser_delete

• Defined in File parser.h

Function Documentation

void TCOD_parser_delete(TCOD_Parser *parser)

Function TCOD_parser_error

• Defined in File parser.h

Function Documentation

void TCOD_parser_error(const char *msg, ...)

Function TCOD_parser_get_bool_property

• Defined in File parser.h

Function Documentation

bool TCOD_parser_get_bool_property(TCOD_Parser *parser, const char *name)

Function TCOD_parser_get_char_property

• Defined in File parser.h

Function Documentation

int TCOD_parser_get_char_property(TCOD_Parser *parser, const char *name)

Function TCOD_parser_get_color_property

• Defined in File parser.h

Function Documentation

TCOD_color_t TCOD_parser_get_color_property(TCOD_Parser *parser, const char *name)

Function TCOD_parser_get_color_property_wrapper

• Defined in File wrappers.h

Function Documentation

colornum_t TCOD_parser_get_color_property_wrapper(TCOD_parser_t parser, const char *name)

Function TCOD_parser_get_custom_property

• Defined in File parser.h

Function Documentation

void *TCOD_parser_get_custom_property(TCOD_Parser *parser, const char *name)

Function TCOD_parser_get_dice_property

• Defined in File parser.h

Function Documentation

TCOD_dice_t TCOD_parser_get_dice_property(TCOD_Parser *parser, const char *name)

Function TCOD_parser_get_dice_property_py

• Defined in File parser.h

Function Documentation

void TCOD_parser_get_dice_property_py(TCOD_Parser *parser, const char *name, TCOD_dice_t *dice)

Function TCOD_parser_get_float_property

• Defined in File parser.h

Function Documentation

float TCOD_parser_get_float_property(TCOD_Parser *parser, const char *name)

Function TCOD_parser_get_int_property

• Defined in File parser.h

Function Documentation

int TCOD_parser_get_int_property(TCOD_Parser *parser, const char *name)

Function TCOD_parser_get_list_property

• Defined in File parser.h

Function Documentation

TCOD_list_t TCOD_parser_get_list_property(TCOD_Parser *parser, const char *name, TCOD_value_type_t type)

Function TCOD_parser_get_string_property

• Defined in File parser.h

Function Documentation

const char *TCOD_parser_get_string_property(TCOD_Parser *parser, const char *name)

Function TCOD_parser_has_property

• Defined in File parser.h

Function Documentation

bool TCOD_parser_has_property(TCOD_Parser *parser, const char *name)

Function TCOD_parser_new

• Defined in File parser.h

Function Documentation

TCOD_Parser *TCOD_parser_new(void)

Function TCOD_parser_new_custom_type

• Defined in File parser.h

Function Documentation

TCOD_value_type_t TCOD_parser_new_custom_type(TCOD_Parser *parser, TCOD_parser_custom_t custom_type_parser)

Function TCOD_parser_new_struct

• Defined in File parser.h

Function Documentation

TCOD_ParserStruct *TCOD_parser_new_struct(TCOD_Parser *parser, const char *name)

Function TCOD_parser_run

• Defined in File parser.h

Function Documentation

void TCOD_parser_run(TCOD_Parser *parser, const char *filename, TCOD_parser_listener_t *listener)

Function TCOD_path_compute

• Defined in File path.h

Function Documentation

bool TCOD_path_compute(TCOD_path_t path, int ox, int oy, int dx, int dy)

Function TCOD_path_delete

• Defined in File path.h

Function Documentation

void TCOD_path_delete(TCOD_path_t path)

Function TCOD_path_get

• Defined in File path.h

Function Documentation

void TCOD_path_get(TCOD_path_t path, int index, int *x, int *y)

Function TCOD_path_get_destination

• Defined in File path.h

Function Documentation

void TCOD_path_get_destination(TCOD_path_t path, int *x, int *y)

Function TCOD_path_get_origin

• Defined in File path.h

Function Documentation

void TCOD_path_get_origin(TCOD_path_t path, int *x, int *y)

Function TCOD_path_is_empty

• Defined in File path.h

Function Documentation

bool TCOD_path_is_empty(TCOD_path_t path)

Function TCOD_path_new_using_function

• Defined in File path.h

Function Documentation

TCOD_path_t TCOD_path_new_using_function(int map_width, int map_height, TCOD_path_func_t func, void *user_data, float diagonalCost)

Function TCOD_path_new_using_map

• Defined in File path.h

Function Documentation

TCOD_path_t TCOD_path_new_using_map(TCOD_map_t map, float diagonalCost)

Function TCOD_path_reverse

• Defined in File path.h

Function Documentation

void TCOD_path_reverse(TCOD_path_t path)

Function TCOD_path_size

• Defined in File path.h

Function Documentation

int TCOD_path_size(TCOD_path_t path)

Function TCOD_path_walk

• Defined in File path.h

Function Documentation

bool TCOD_path_walk(TCOD_path_t path, int *x, int *y, bool recalculate_when_needed)

Function TCOD_pf_compute

• Defined in File pathfinder.h

Function Documentation

int TCOD_pf_compute(struct TCOD_Pathfinder *path)

Function TCOD_pf_compute_step

• Defined in File pathfinder.h

Function Documentation

int TCOD_pf_compute_step(struct TCOD_Pathfinder *path)

Function TCOD_pf_delete

• Defined in File pathfinder.h

Function Documentation

void TCOD_pf_delete(struct TCOD_Pathfinder *path)

Function TCOD_pf_new

• Defined in File pathfinder.h

Function Documentation

struct TCOD_Pathfinder *TCOD_pf_new(int ndim, const size_t *shape)

Function TCOD_pf_recompile

• Defined in File pathfinder.h

Function Documentation

int TCOD_pf_recompile(struct TCOD_Pathfinder *path)

Function TCOD_pf_set_distance_pointer

• Defined in File pathfinder.h

Function Documentation

void TCOD_pf_set_distance_pointer(struct TCOD_Pathfinder *path, void *data, int int_type, const size_t *strides)

Function TCOD_pf_set_graph2d_pointer

• Defined in File pathfinder.h

Function Documentation

void TCOD_pf_set_graph2d_pointer(struct TCOD_Pathfinder *path, void *data, int int_type, const size_t *strides, int cardinal, int diagonal)

Function TCOD_pf_set_traversal_pointer

• Defined in File pathfinder.h

Function Documentation

void TCOD_pf_set_traversal_pointer(struct TCOD_Pathfinder *path, void *data, int int_type, const size_t *strides)

Function TCOD_printf_rgb

• Defined in File console_printing.h

Function Documentation

int TCOD_printf_rgb(TCOD_Console *console, TCOD_PrintParamsRGB params, const char *fmt, ...)

Prints a formatted string to the console.

Parameters:

• console – A pointer to a TCOD_Console.

• params – Information about how the string should be printed

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

• args – The arguments for the formatted string.

Returns:

An error code if less than 0

New in version 1.23.

Function TCOD_printn_rgb

• Defined in File console_printing.h

Function Documentation

int TCOD_printn_rgb(TCOD_Console *console, TCOD_PrintParamsRGB params, int n, const char *str)

Prints n-bytes of a string string to the console.

Parameters:

• console – A pointer to a TCOD_Console.

• params – Information about how the string should be printed

• str – The string to be read from.

• n – Length of string in bytes

Returns:

An error code if less than 0

New in version 1.23.

Function TCOD_quit

• Defined in File console_init.h

Function Documentation

void TCOD_quit(void)

Shutdown libtcod.

This must be called before your program exits.

New in version 1.8.

Function TCOD_random_delete

• Defined in File mersenne.h

Function Documentation

void TCOD_random_delete(TCOD_Random *mersenne)

Function TCOD_random_dice_new

• Defined in File mersenne.h

Function Documentation

TCOD_dice_t TCOD_random_dice_new(const char *s)

Function TCOD_random_dice_roll

• Defined in File mersenne.h

Function Documentation

int TCOD_random_dice_roll(TCOD_Random *mersenne, TCOD_dice_t dice)

Function TCOD_random_dice_roll_s

• Defined in File mersenne.h

Function Documentation

int TCOD_random_dice_roll_s(TCOD_Random *mersenne, const char *s)

Function TCOD_random_get_double

• Defined in File mersenne.h

Function Documentation

double TCOD_random_get_double(TCOD_Random *mersenne, double min, double max)

Function TCOD_random_get_double_mean

• Defined in File mersenne.h

Function Documentation

double TCOD_random_get_double_mean(TCOD_Random *mersenne, double min, double max, double mean)

Function TCOD_random_get_float

• Defined in File mersenne.h

Function Documentation

float TCOD_random_get_float(TCOD_Random *mersenne, float min, float max)

Function TCOD_random_get_float_mean

• Defined in File mersenne.h

Function Documentation

float TCOD_random_get_float_mean(TCOD_Random *mersenne, float min, float max, float mean)

Function TCOD_random_get_instance

• Defined in File mersenne.h

Function Documentation

TCOD_Random *TCOD_random_get_instance(void)

Function TCOD_random_get_int

• Defined in File mersenne.h

Function Documentation

int TCOD_random_get_int(TCOD_Random *mersenne, int min, int max)

Function TCOD_random_get_int_mean

• Defined in File mersenne.h

Function Documentation

int TCOD_random_get_int_mean(TCOD_Random *mersenne, int min, int max, int mean)

Function TCOD_random_new

• Defined in File mersenne.h

Function Documentation

TCOD_Random *TCOD_random_new(TCOD_random_algo_t algo)

Function TCOD_random_new_from_seed

• Defined in File mersenne.h

Function Documentation

TCOD_Random *TCOD_random_new_from_seed(TCOD_random_algo_t algo, uint32_t seed)

Function TCOD_random_restore

• Defined in File mersenne.h

Function Documentation

void TCOD_random_restore(TCOD_Random *mersenne, TCOD_Random *backup)

Function TCOD_random_save

• Defined in File mersenne.h

Function Documentation

TCOD_Random *TCOD_random_save(TCOD_Random *mersenne)

Function TCOD_random_set_distribution

• Defined in File mersenne.h

Function Documentation

void TCOD_random_set_distribution(TCOD_Random *mersenne, TCOD_distribution_t distribution)

Function TCOD_renderer_init_sdl2

• Defined in File renderer_sdl2.h

Function Documentation

struct TCOD_Context *TCOD_renderer_init_sdl2(int x, int y, int width, int height, const char *title, int window_flags, int renderer_flags, struct TCOD_Tileset *tileset)

Return a libtcod rendering context using an SDL2 renderer.

Function TCOD_renderer_init_xterm

• Defined in File renderer_xterm.h

Function Documentation

TCOD_Context *TCOD_renderer_init_xterm(int window_x, int window_y, int pixel_width, int pixel_height, int columns, int rows, const char *window_title)

Function TCOD_rng_splitmix64_next

• Defined in File random.h

Function Documentation

static inline uint64_t TCOD_rng_splitmix64_next(uint64_t *state)

Return the next random uint64_t from a SplitMix64 generator.

state[1] is a non-NULL pointer to the internal state of the generator. There is no initializer function because the first value of state[1] is itself the seed which can start at any value. state[1] will be updated by this call.

This function is provisional and may change.

Function TCOD_save_xp

• Defined in File console_rexpaint.h

Function Documentation

TCOD_Error TCOD_save_xp(int n, const TCOD_Console *const *consoles, const char *path, int compress_level)

Save an array of consoles to a REXPaint file.

Partially initialized consoles are released on failures.

New in version 1.18.

Parameters:

• n – The number of consoles in the consoles array.

• consoles – An array of consoles.

• path – The path write the REXPaint file, can not be NULL.

• compress_level – A compression level for the zlib library.

Returns:

Returns an error code on failure.

Function TCOD_save_xp_to_memory

• Defined in File console_rexpaint.h

Function Documentation

int TCOD_save_xp_to_memory(int n_consoles, const TCOD_Console *const *consoles, int n_out, unsigned char *out, int compression_level)

Save an array of consoles to a REXPaint file in memory.

Partially initialized consoles are released on failures.

New in version 1.18.

Parameters:

• n_consoles – The length of the input consoles array.

• consoles – An array of tcod consoles, can not be NULL.

• n_out – The size of the out buffer, if this is zero then upper bound to be returned.

• out – A pointer to an output buffer, can be NULL.

• compression_level – A compression level for the zlib library.

Returns:

If out=NULL then returns the upper bound of the buffer size needed. Otherwise this returns the number of bytes actually filled. On an error a negative error code is returned.

Function TCOD_sdl2_atlas_delete

• Defined in File renderer_sdl2.h

Function Documentation

void TCOD_sdl2_atlas_delete(struct TCOD_TilesetAtlasSDL2 *atlas)

Delete an SDL2 tileset atlas.

Function TCOD_sdl2_atlas_new

• Defined in File renderer_sdl2.h

Function Documentation

struct TCOD_TilesetAtlasSDL2 *TCOD_sdl2_atlas_new(struct SDL_Renderer *renderer, struct TCOD_Tileset *tileset)

Return a new SDL2 atlas created from a tileset for an SDL2 renderer.

You may delete the tileset if you no longer have use for it.

Will return NULL on an error, you can check the error with TCOD_get_error.

Function TCOD_sdl2_render_texture

• Defined in File renderer_sdl2.h

Function Documentation

TCOD_Error TCOD_sdl2_render_texture(const struct TCOD_TilesetAtlasSDL2 *atlas, const struct TCOD_Console *console, struct TCOD_Console *cache, struct SDL_Texture *target)

Render a console onto a managed target texture.

This function assumes that cache and target are valid. You can use TCOD_sdl2_render_texture_setup to automatically prepare these objects for use with this function.

atlas is an SDL2 atlas created with TCOD_sdl2_atlas_new. The renderer used to make this atlas must support SDL_RENDERER_TARGETTEXTURE, unless target is NULL.

console is a non-NULL pointer to the libtcod console you want to render.

cache can be NULL, or point to a console the same size as console.

target can be NULL, or be pointer an SDL2 texture used as the output. If target is not NULL then it should be the size of the console times the size of the individual tiles to fit the entire output.

If target is NULL then the current render target is used instead, the drawn area will not be scaled to fit the render target.

If SDL2 ever provides a SDL_RENDER_TARGETS_RESET event then the console at cache must be cleared, or else the next render will only partially update the texture of target.

Returns a negative value on an error, check TCOD_get_error.

New in version 1.16.

Function TCOD_sdl2_render_texture_setup

• Defined in File renderer_sdl2.h

Function Documentation

TCOD_Error TCOD_sdl2_render_texture_setup(const struct TCOD_TilesetAtlasSDL2 *atlas, const struct TCOD_Console *console, struct TCOD_Console **cache, struct SDL_Texture **target)

Setup a cache and target texture for rendering.

atlas is an SDL2 atlas created with TCOD_sdl2_atlas_new. The renderer used to make this atlas must support SDL_RENDERER_TARGETTEXTURE.

console is a non-NULL pointer to the libtcod console you want to render.

cache can be NULL, or be pointer to a console pointer. If *cache is NULL then a console will be created. If *cache isn’t NULL then the console pointed to might be deleted or recreated if it does not match the size of console.

target must be a pointer to where you want the output texture to be placed. The texture at *target may be deleted or recreated. When this function is successful then the texture at *target will be non-NULL and will be exactly fitted to the size of console and the tile size of atlas.

If SDL2 ever provides a SDL_RENDER_TARGETS_RESET event then the console at *cache must be deleted and set to NULL, or else the next render will only partially update the texture at *target.

Returns a negative value on an error, check TCOD_get_error.

New in version 1.16.

Function TCOD_semaphore_delete

• Defined in File sys.h

Function Documentation

void TCOD_semaphore_delete(TCOD_semaphore_t sem)

Function TCOD_semaphore_lock

• Defined in File sys.h

Function Documentation

void TCOD_semaphore_lock(TCOD_semaphore_t sem)

Function TCOD_semaphore_new

• Defined in File sys.h

Function Documentation

TCOD_semaphore_t TCOD_semaphore_new(int initVal)

Function TCOD_semaphore_unlock

• Defined in File sys.h

Function Documentation

void TCOD_semaphore_unlock(TCOD_semaphore_t sem)

Function TCOD_set_default_tileset

• Defined in File globals.h

Function Documentation

void TCOD_set_default_tileset(TCOD_Tileset *tileset)

Set the default tileset and update the default display to use it.

This will keep alive a reference to the given tileset. If you no longer need the pointer then you should call TCOD_tileset_delete on it after this function.

This function is provisional, the API may change in the future.

New in version 1.19.

Function TCOD_set_error

• Defined in File error.h

Function Documentation

TCOD_Error TCOD_set_error(const char *msg)

Set an error message and return TCOD_E_ERROR.

New in version 1.12.

Function TCOD_set_errorf

• Defined in File error.h

Function Documentation

TCOD_Error TCOD_set_errorf(const char *fmt, ...)

Set an error message and return TCOD_E_ERROR.

New in version 1.16.

Function TCOD_set_log_callback

• Defined in File logging.h

Function Documentation

void TCOD_set_log_callback(TCOD_LoggingCallback callback, void *userdata)

Sets a callback for libtcod’s logged output.

New in version 1.19.

Parameters:

• callback – A TCOD_LoggingCallback function which processes TCOD_LogMessage* parameters. Can be NULL to disable logging.

• userdata – Userdata to be passed to the log function.

Function TCOD_set_log_level

• Defined in File logging.h

Function Documentation

void TCOD_set_log_level(int level)

Set the level of messages being logged.

New in version 1.19.

Parameters:

level – Should be one of the levels from TCOD_LogLevel.

Function TCOD_strcasecmp

• Defined in File portability.h

Function Documentation

int TCOD_strcasecmp(const char *s1, const char *s2)

Compare two ASCII strings ignoring case.

Returns 0 if the strings are equal.

Function TCOD_strdup

• Defined in File portability.h

Function Documentation

char *TCOD_strdup(const char *s)

Allocate and return a duplicate of string s.

The returned memory must be freed manually.

Function TCOD_strncasecmp

• Defined in File portability.h

Function Documentation

int TCOD_strncasecmp(const char *s1, const char *s2, size_t n)

Compare two ASCII strings ignoring case.

Returns 0 if the strings are equal.

Function TCOD_struct_add_flag

• Defined in File parser.h

Function Documentation

void TCOD_struct_add_flag(TCOD_ParserStruct *def, const char *propname)

Function TCOD_struct_add_list_property

• Defined in File parser.h

Function Documentation

void TCOD_struct_add_list_property(TCOD_ParserStruct *def, const char *name, TCOD_value_type_t type, bool mandatory)

Function TCOD_struct_add_property

• Defined in File parser.h

Function Documentation

void TCOD_struct_add_property(TCOD_ParserStruct *def, const char *name, TCOD_value_type_t type, bool mandatory)

Function TCOD_struct_add_structure

• Defined in File parser.h

Function Documentation

void TCOD_struct_add_structure(TCOD_ParserStruct *def, const TCOD_ParserStruct *sub_structure)

Function TCOD_struct_add_value_list

• Defined in File parser.h

Function Documentation

void TCOD_struct_add_value_list(TCOD_ParserStruct *def, const char *name, const char *const *value_list, bool mandatory)

Function TCOD_struct_add_value_list_sized

• Defined in File parser.h

Function Documentation

void TCOD_struct_add_value_list_sized(TCOD_ParserStruct *def, const char *name, const char *const *value_list, int size, bool mandatory)

Function TCOD_struct_get_name

• Defined in File parser.h

Function Documentation

const char *TCOD_struct_get_name(const TCOD_ParserStruct *def)

Function TCOD_struct_get_type

• Defined in File parser.h

Function Documentation

TCOD_value_type_t TCOD_struct_get_type(const TCOD_ParserStruct *def, const char *propname)

Function TCOD_struct_is_mandatory

• Defined in File parser.h

Function Documentation

bool TCOD_struct_is_mandatory(TCOD_ParserStruct *def, const char *propname)

Function TCOD_sys_accumulate_console

• Defined in File console_init.h

Function Documentation

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.

See also

TCOD_sys_get_sdl_window() TCOD_sys_get_sdl_renderer()

Function TCOD_sys_check_for_event

• Defined in File sys.h

Function Documentation

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

Function TCOD_sys_clipboard_get

• Defined in File sys.h

Function Documentation

char *TCOD_sys_clipboard_get(void)

Function TCOD_sys_clipboard_set

• Defined in File sys.h

Function Documentation

bool TCOD_sys_clipboard_set(const char *value)

Function TCOD_sys_create_directory

• Defined in File sys.h

Function Documentation

bool TCOD_sys_create_directory(const char *path)

Function TCOD_sys_delete_directory

• Defined in File sys.h

Function Documentation

bool TCOD_sys_delete_directory(const char *path)

Function TCOD_sys_delete_file

• Defined in File sys.h

Function Documentation

bool TCOD_sys_delete_file(const char *path)

Function TCOD_sys_elapsed_milli

• Defined in File sys.h

Function Documentation

uint32_t TCOD_sys_elapsed_milli(void)

Alias for SDL_GetTicks.

Deprecated since version 1.19: You should call SDL_GetTicks directly.

Function TCOD_sys_elapsed_seconds

• Defined in File sys.h

Function Documentation

float TCOD_sys_elapsed_seconds(void)

Returns the number of seconds since the start of the program.

Deprecated since version 1.19: Use SDL_GetTicks and convert the result into seconds instead of using this function.

Function TCOD_sys_file_exists

• Defined in File sys.h

Function Documentation

bool TCOD_sys_file_exists(const char *filename, ...)

Function TCOD_sys_force_fullscreen_resolution

• Defined in File sys.h

Function Documentation

void TCOD_sys_force_fullscreen_resolution(int width, int height)

Function TCOD_sys_get_char_size

• Defined in File sys.h

Function Documentation

void TCOD_sys_get_char_size(int *w, int *h)

Function TCOD_sys_get_current_resolution

• Defined in File sys.h

Function Documentation

TCOD_Error TCOD_sys_get_current_resolution(int *w, int *h)

Return the resolution of the current monitor.

Function TCOD_sys_get_current_resolution_x

• Defined in File wrappers.h

Function Documentation

int TCOD_sys_get_current_resolution_x(void)

Function TCOD_sys_get_current_resolution_y

• Defined in File wrappers.h

Function Documentation

int TCOD_sys_get_current_resolution_y(void)

Function TCOD_sys_get_directory_content

• Defined in File sys.h

Function Documentation

TCOD_list_t TCOD_sys_get_directory_content(const char *path, const char *pattern)

Function TCOD_sys_get_fps

• Defined in File sys.h

Function Documentation

int TCOD_sys_get_fps(void)

Get the current framerate.

Deprecated since version 1.19: This function will not work with libtcod contexts. Use tcod::Timer instead.

Function TCOD_sys_get_fullscreen_offsets

• Defined in File sys.h

Function Documentation

void TCOD_sys_get_fullscreen_offsets(int *offset_x, int *offset_y)

Function TCOD_sys_get_internal_console

• Defined in File console_init.h

Function Documentation

TCOD_Console *TCOD_sys_get_internal_console(void)

Return a pointer to the “root console” used internally by the old API.

This is useful for functions which take a console parameter but won’t accept NULL.

New in version 1.19.

Returns:

A pointer to TCOD_Console, or NULL if it doesn’t exist.

Function TCOD_sys_get_internal_context

• Defined in File console_init.h

Function Documentation

TCOD_Context *TCOD_sys_get_internal_context(void)

Return the context being used internally by the old API.

This function can be useful to progressively upgrade older code to use the newer API.

New in version 1.19.

Returns:

A TCOD_Context pointer, or NULL if the global internals were not initialzed.

Function TCOD_sys_get_last_frame_length

• Defined in File sys.h

Function Documentation

float TCOD_sys_get_last_frame_length(void)

Get the delta time between the last two frames.

Deprecated since version 1.19: This function will not work with libtcod contexts. Use tcod::Timer instead.

Function TCOD_sys_get_num_cores

• Defined in File sys.h

Function Documentation

int TCOD_sys_get_num_cores(void)

Function TCOD_sys_get_renderer

• Defined in File sys.h

Function Documentation

TCOD_renderer_t TCOD_sys_get_renderer(void)

Function TCOD_sys_get_sdl_renderer

• Defined in File console_init.h

Function Documentation

struct SDL_Renderer *TCOD_sys_get_sdl_renderer(void)

Return an SDL_Renderer pointer if one is in use, returns NULL otherwise.

New in version 1.11.

Function TCOD_sys_get_SDL_renderer

• Defined in File sys.h

Function Documentation

struct SDL_Renderer *TCOD_sys_get_SDL_renderer(void)

Function TCOD_sys_get_sdl_window

• Defined in File console_init.h

Function Documentation

struct SDL_Window *TCOD_sys_get_sdl_window(void)

Return an SDL_Window pointer if one is in use, returns NULL otherwise.

New in version 1.11.

Function TCOD_sys_get_SDL_window

• Defined in File sys.h

Function Documentation

struct SDL_Window *TCOD_sys_get_SDL_window(void)

Function TCOD_sys_is_directory

• Defined in File sys.h

Function Documentation

bool TCOD_sys_is_directory(const char *path)

Function TCOD_sys_process_key_event

• Defined in File event.h

Function Documentation

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.

Function TCOD_sys_process_mouse_event

• Defined in File event.h

Function Documentation

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.

Function TCOD_sys_read_file

• Defined in File sys.h

Function Documentation

bool TCOD_sys_read_file(const char *filename, unsigned char **buf, size_t *size)

Function TCOD_sys_register_SDL_renderer

• Defined in File sys.h

Function Documentation

void TCOD_sys_register_SDL_renderer(SDL_renderer_t renderer)

Function TCOD_sys_save_screenshot

• Defined in File sys.h

Function Documentation

void TCOD_sys_save_screenshot(const char *filename)

Function TCOD_sys_set_fps

• Defined in File sys.h

Function Documentation

void TCOD_sys_set_fps(int val)

Set the desired framerate.

Deprecated since version 1.19: This function will not affect libtcod contexts. Set the framerate with tcod::Timer instead.

Function TCOD_sys_set_renderer

• Defined in File sys.h

Function Documentation

int TCOD_sys_set_renderer(TCOD_renderer_t renderer)

Function TCOD_sys_shutdown

• Defined in File sys.h

Function Documentation

void TCOD_sys_shutdown(void)

Function TCOD_sys_sleep_milli

• Defined in File sys.h

Function Documentation

void TCOD_sys_sleep_milli(uint32_t val)

Alias for SDL_Delay.

Deprecated since version 1.19: You should call SDL_Delay directly.

Function TCOD_sys_startup

• Defined in File sys.h

Function Documentation

void TCOD_sys_startup(void)

Function TCOD_sys_update_char

• Defined in File sys.h

Function Documentation

void TCOD_sys_update_char(int asciiCode, int font_x, int font_y, const TCOD_Image *img, int x, int y)

Upload a tile to the active tileset.

asciiCode is the Unicode codepoint for this tile.

font_x and font_y are the tile-coordinates on the active tilemap.

img is the tile to upload.

x and y are the upper-left pixel-coordinates of the tile on the img.

Function TCOD_sys_wait_for_event

• Defined in File sys.h

Function Documentation

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

Function TCOD_sys_write_file

• Defined in File sys.h

Function Documentation

bool TCOD_sys_write_file(const char *filename, unsigned char *buf, uint32_t size)

Function TCOD_text_delete

• Defined in File txtfield.h

Function Documentation

void TCOD_text_delete(TCOD_text_t txt)

Function TCOD_text_get

• Defined in File txtfield.h

Function Documentation

const char *TCOD_text_get(TCOD_text_t txt)

Function TCOD_text_init

• Defined in File txtfield.h

Function Documentation

TCOD_text_t TCOD_text_init(int x, int y, int w, int h, int max_chars)

Function TCOD_text_init2

• Defined in File txtfield.h

Function Documentation

TCOD_text_t TCOD_text_init2(int w, int h, int max_chars)

Function TCOD_text_render

• Defined in File txtfield.h

Function Documentation

void TCOD_text_render(TCOD_text_t txt, TCOD_console_t con)

Function TCOD_text_reset

• Defined in File txtfield.h

Function Documentation

void TCOD_text_reset(TCOD_text_t txt)

Function TCOD_text_set_colors

• Defined in File txtfield.h

Function Documentation

void TCOD_text_set_colors(TCOD_text_t txt, TCOD_color_t fore, TCOD_color_t back, float back_transparency)

Function TCOD_text_set_pos

• Defined in File txtfield.h

Function Documentation

void TCOD_text_set_pos(TCOD_text_t txt, int x, int y)

Function TCOD_text_set_properties

• Defined in File txtfield.h

Function Documentation

void TCOD_text_set_properties(TCOD_text_t txt, int cursor_char, int blink_interval, const char *prompt, int tab_size)

Function TCOD_text_update

• Defined in File txtfield.h

Function Documentation

bool TCOD_text_update(TCOD_text_t txt, TCOD_key_t key)

Function TCOD_thread_delete

• Defined in File sys.h

Function Documentation

void TCOD_thread_delete(TCOD_thread_t th)

Function TCOD_thread_new

• Defined in File sys.h

Function Documentation

TCOD_thread_t TCOD_thread_new(int (*func)(void*), void *data)

Function TCOD_thread_wait

• Defined in File sys.h

Function Documentation

void TCOD_thread_wait(TCOD_thread_t th)

Function TCOD_tileset_assign_tile

• Defined in File tileset.h

Function Documentation

int TCOD_tileset_assign_tile(struct TCOD_Tileset *tileset, int tile_id, int codepoint)

Assign a codepoint to an existing tile based on its tile ID.

Parameters:

• tileset – A TCOD_Tileset pointer, must not be NULL.

• tile_id – The index of the tile.

• codepoint – The Unicode codepoint to associate with tile_id.

Returns:

Returns a negative value on error.

Function TCOD_tileset_delete

• Defined in File tileset.h

Function Documentation

void TCOD_tileset_delete(TCOD_Tileset *tileset)

Delete a tile-set.

New in version 1.19.

Function TCOD_tileset_get_tile

• Defined in File tileset.h

Function Documentation

const struct TCOD_ColorRGBA *TCOD_tileset_get_tile(const TCOD_Tileset *tileset, int codepoint)

Return a pointer to the tile for codepoint.

Returns NULL if no tile exists for codepoint.

Function TCOD_tileset_load

• Defined in File tileset.h

Function Documentation

TCOD_Tileset *TCOD_tileset_load(const char *filename, int columns, int rows, int n, const int *charmap)

Load a PNG font as a tilesheet and return a TCOD_Tileset.

filename is the path to a PNG file.

columns and rows are the shape of the tileset in the image. The tile size will be derived from these parameters and the size of the image.

charmap[n] is an array of which codepoints to assign to which tiles. Tiles are assigned in row-major order. TCOD_CHARMAP_CP437 or TCOD_CHARMAP_TCOD could be used here.

New in version 1.19.

Function TCOD_tileset_load_mem

• Defined in File tileset.h

Function Documentation

TCOD_Tileset *TCOD_tileset_load_mem(size_t buffer_length, const unsigned char *buffer, int columns, int rows, int n, const int *charmap)

Load a PNG font from memory and return a TCOD_Tileset.

buffer[buffer_length] is the PNG data to load.

The remaining parameters are the same as TCOD_tileset_load.

New in version 1.19.

Function TCOD_tileset_load_raw

• Defined in File tileset.h

Function Documentation

TCOD_Tileset *TCOD_tileset_load_raw(int width, int height, const struct TCOD_ColorRGBA *pixels, int columns, int rows, int n, const int *charmap)

Load raw RGBA data and return a TCOD_Tileset.

pixels[width*height] is a row-major RGBA-ordered byte array.

The remaining parameters are the same as TCOD_tileset_load.

New in version 1.19.

Function TCOD_tileset_new

• Defined in File tileset.h

Function Documentation

TCOD_Tileset *TCOD_tileset_new(int tile_width, int tile_height)

Create a new tile-set with the given tile size.

New in version 1.19.

Function TCOD_tileset_notify_tile_changed

• Defined in File tileset.h

Function Documentation

void TCOD_tileset_notify_tile_changed(TCOD_Tileset *tileset, int tile_id)

Called to notify any observers that a tile has been changed.

This may cause running atlases to update or mark cache consoles as dirty.

For internal use.

Function TCOD_tileset_observer_delete

• Defined in File tileset.h

Function Documentation

void TCOD_tileset_observer_delete(struct TCOD_TilesetObserver *observer)

Delete an existing observer.

Will call this observers on_observer_delete callback.

For internal use.

Function TCOD_tileset_observer_new

• Defined in File tileset.h

Function Documentation

struct TCOD_TilesetObserver *TCOD_tileset_observer_new(struct TCOD_Tileset *tileset)

Return a new observer to this tileset.

For internal use.

Function TCOD_tileset_render_to_surface

• Defined in File tileset_render.h

Function Documentation

TCOD_Error TCOD_tileset_render_to_surface(const TCOD_Tileset *tileset, const TCOD_Console *console, TCOD_Console **cache, struct SDL_Surface **surface_out)

Render a console to a SDL_Surface with a software renderer.

tileset is the tiles to render with, must not be NULL.

console is the console to render, must not be NULL.

cache is an optional pointer to a consoled used as a cache. The console at *cache will be created or modified. The cache will be used to skip drawing already drawn tiles on any subsequent calls.

surface_out is a pointer to where to put the surface will be managed. The surface at *surface_out will be created or modified and will change to match the size of console and tileset. The pixel format will be SDL_PIXELFORMAT_RGBA32.

Returns a negative value on error, see TCOD_get_error.

New in version 1.16.

Function TCOD_tileset_reserve

• Defined in File tileset.h

Function Documentation

TCOD_Error TCOD_tileset_reserve(TCOD_Tileset *tileset, int desired)

Reserve memory for a specific amount of tiles.

For internal use.

Function TCOD_tree_add_son

• Defined in File tree.h

Function Documentation

void TCOD_tree_add_son(TCOD_tree_t *node, TCOD_tree_t *son)

Function TCOD_tree_new

• Defined in File tree.h

Function Documentation

TCOD_tree_t *TCOD_tree_new(void)

Function TCOD_viewport_delete

• Defined in File context_viewport.h

Function Documentation

void TCOD_viewport_delete(TCOD_ViewportOptions *viewport)

Delete a viewport.

New in version 1.16.

Function TCOD_viewport_new

• Defined in File context_viewport.h

Function Documentation

TCOD_ViewportOptions *TCOD_viewport_new(void)

Allocate a new viewport options struct.

You should not allocate this struct manually since the size of it may change between versions.

New in version 1.16.

Function TCOD_vprintf_rgb

• Defined in File console_printing.h

Function Documentation

int TCOD_vprintf_rgb(TCOD_Console *console, TCOD_PrintParamsRGB params, const char *fmt, va_list args)

Prints a formatted string using va_list.

Parameters:

• console – A pointer to a TCOD_Console.

• params – Information about how the string should be printed

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

• args – The arguments for the format string

Returns:

An error code if less than 0

New in version 1.23.

Function TCOD_zip_delete

• Defined in File zip.h

Function Documentation

void TCOD_zip_delete(TCOD_zip_t zip)

Function TCOD_zip_get_char

• Defined in File zip.h

Function Documentation

char TCOD_zip_get_char(TCOD_zip_t zip)

Function TCOD_zip_get_color

• Defined in File zip.h

Function Documentation

TCOD_color_t TCOD_zip_get_color(TCOD_zip_t zip)

Function TCOD_zip_get_console

• Defined in File zip.h

Function Documentation

TCOD_console_t TCOD_zip_get_console(TCOD_zip_t zip)

Function TCOD_zip_get_current_bytes

• Defined in File zip.h

Function Documentation

uint32_t TCOD_zip_get_current_bytes(TCOD_zip_t zip)

Function TCOD_zip_get_data

• Defined in File zip.h

Function Documentation

int TCOD_zip_get_data(TCOD_zip_t zip, int nbBytes, void *data)

Function TCOD_zip_get_float

• Defined in File zip.h

Function Documentation

float TCOD_zip_get_float(TCOD_zip_t zip)

Function TCOD_zip_get_image

• Defined in File zip.h

Function Documentation

TCOD_Image *TCOD_zip_get_image(TCOD_zip_t zip)

Function TCOD_zip_get_int

• Defined in File zip.h

Function Documentation

int TCOD_zip_get_int(TCOD_zip_t zip)

Function TCOD_zip_get_random

• Defined in File zip.h

Function Documentation

TCOD_Random *TCOD_zip_get_random(TCOD_zip_t zip)

Read a TCOD_Random* object.

New in version 1.16.

Function TCOD_zip_get_remaining_bytes

• Defined in File zip.h

Function Documentation

uint32_t TCOD_zip_get_remaining_bytes(TCOD_zip_t zip)

Function TCOD_zip_get_string

• Defined in File zip.h

Function Documentation

const char *TCOD_zip_get_string(TCOD_zip_t zip)

Function TCOD_zip_load_from_file

• Defined in File zip.h

Function Documentation

int TCOD_zip_load_from_file(TCOD_zip_t zip, const char *filename)

Function TCOD_zip_new

• Defined in File zip.h

Function Documentation

TCOD_zip_t TCOD_zip_new(void)

Function TCOD_zip_put_char

• Defined in File zip.h

Function Documentation

void TCOD_zip_put_char(TCOD_zip_t zip, char val)

Function TCOD_zip_put_color

• Defined in File zip.h

Function Documentation

void TCOD_zip_put_color(TCOD_zip_t zip, const TCOD_color_t val)

Function TCOD_zip_put_console

• Defined in File zip.h

Function Documentation

void TCOD_zip_put_console(TCOD_zip_t zip, const TCOD_Console *val)

Function TCOD_zip_put_data

• Defined in File zip.h

Function Documentation

void TCOD_zip_put_data(TCOD_zip_t zip, int nbBytes, const void *data)

Function TCOD_zip_put_float

• Defined in File zip.h

Function Documentation

void TCOD_zip_put_float(TCOD_zip_t zip, float val)

Function TCOD_zip_put_image

• Defined in File zip.h

Function Documentation

void TCOD_zip_put_image(TCOD_zip_t zip, const TCOD_Image *val)

Function TCOD_zip_put_int

• Defined in File zip.h

Function Documentation

void TCOD_zip_put_int(TCOD_zip_t zip, int val)

Function TCOD_zip_put_random

• Defined in File zip.h

Function Documentation

void TCOD_zip_put_random(TCOD_zip_t zip, const TCOD_Random *val)

Write a TCOD_Random* object.

New in version 1.16.

Function TCOD_zip_put_string

• Defined in File zip.h

Function Documentation

void TCOD_zip_put_string(TCOD_zip_t zip, const char *val)

Function TCOD_zip_save_to_file

• Defined in File zip.h

Function Documentation

int TCOD_zip_save_to_file(TCOD_zip_t zip, const char *filename)

Function TCOD_zip_skip_bytes

• Defined in File zip.h

Function Documentation

void TCOD_zip_skip_bytes(TCOD_zip_t zip, uint32_t nbBytes)

Defines

Define ABS

• Defined in File utility.h

Define Documentation

ABS(a)

Define CLAMP

• Defined in File utility.h

Define Documentation

CLAMP(a, b, x)

Define FOV_PERMISSIVE

• Defined in File fov_types.h

Define Documentation

FOV_PERMISSIVE(x)

Define LERP

• Defined in File utility.h

Define Documentation

LERP(a, b, x)

Define MAX

• Defined in File utility.h

Define Documentation

MAX(a, b)

utility macros

Define MIN

• Defined in File utility.h

Define Documentation

MIN(a, b)

Define TCOD_BKGND_ADDALPHA

• Defined in File console_etc.h

Define Documentation

TCOD_BKGND_ADDALPHA(alpha)

Define TCOD_BKGND_ALPHA

• Defined in File console_etc.h

Define Documentation

TCOD_BKGND_ALPHA(alpha)

Define TCOD_COMPILEDVERSION

• Defined in File version.h

Define Documentation

TCOD_COMPILEDVERSION

The version of libtcod currently being compiled.

New in version 1.16.

Define TCOD_DEPRECATED

• Defined in File config.h

Define Documentation

TCOD_DEPRECATED(msg)

Define TCOD_DEPRECATED_ENUM

• Defined in File config.h

Define Documentation

TCOD_DEPRECATED_ENUM

Define TCOD_DEPRECATED_NOMESSAGE

• Defined in File config.h

Define Documentation

TCOD_DEPRECATED_NOMESSAGE

Define TCOD_FALLBACK_FONT_SIZE

• Defined in File config.h

Define Documentation

TCOD_FALLBACK_FONT_SIZE

Define TCOD_HEXVERSION

• Defined in File version.h

Define Documentation

TCOD_HEXVERSION

Deprecated since version 1.16.

Define TCOD_KEY_TEXT_SIZE

• Defined in File console_types.h

Define Documentation

TCOD_KEY_TEXT_SIZE

Define TCOD_log_critical

• Defined in File logging.h

Define Documentation

TCOD_log_critical(msg)

Define TCOD_log_critical_f

• Defined in File logging.h

Define Documentation

TCOD_log_critical_f(fmt, ...)

Define TCOD_log_debug

• Defined in File logging.h

Define Documentation

TCOD_log_debug(msg)

Define TCOD_log_debug_f

• Defined in File logging.h

Define Documentation

TCOD_log_debug_f(fmt, ...)

Define TCOD_log_error

• Defined in File logging.h

Define Documentation

TCOD_log_error(msg)

Define TCOD_log_error_f

• Defined in File logging.h

Define Documentation

TCOD_log_error_f(fmt, ...)

Define TCOD_log_info

• Defined in File logging.h

Define Documentation

TCOD_log_info(msg)

Define TCOD_log_info_f

• Defined in File logging.h

Define Documentation

TCOD_log_info_f(fmt, ...)

Define TCOD_log_warning

• Defined in File logging.h

Define Documentation

TCOD_log_warning(msg)

Define TCOD_log_warning_f

• Defined in File logging.h

Define Documentation

TCOD_log_warning_f(fmt, ...)

Define TCOD_MAJOR_VERSION

• Defined in File version.h

Define Documentation

TCOD_MAJOR_VERSION

Define TCOD_MINOR_VERSION

• Defined in File version.h

Define Documentation

TCOD_MINOR_VERSION

Define TCOD_NODISCARD

• Defined in File config.h

Define Documentation

TCOD_NODISCARD

Define TCOD_NOISE_DEFAULT_HURST

• Defined in File noise_defaults.h

Define Documentation

TCOD_NOISE_DEFAULT_HURST

Define TCOD_NOISE_DEFAULT_LACUNARITY

• Defined in File noise_defaults.h

Define Documentation

TCOD_NOISE_DEFAULT_LACUNARITY

Define TCOD_NOISE_MAX_DIMENSIONS

• Defined in File noise_defaults.h

Define Documentation

TCOD_NOISE_MAX_DIMENSIONS

Define TCOD_NOISE_MAX_OCTAVES

• Defined in File noise_defaults.h

Define Documentation

TCOD_NOISE_MAX_OCTAVES

Define TCOD_PATCHLEVEL

• Defined in File version.h

Define Documentation

TCOD_PATCHLEVEL

Define TCOD_PATHFINDER_MAX_DIMENSIONS

• Defined in File pathfinder.h

Define Documentation

TCOD_PATHFINDER_MAX_DIMENSIONS

Define TCOD_PATHFINDER_MAX_DIMENSIONS

• Defined in File pathfinder_frontier.h

Define Documentation

TCOD_PATHFINDER_MAX_DIMENSIONS

Define TCOD_PRIVATE

• Defined in File config.h

Define Documentation

TCOD_PRIVATE

Define TCOD_PUBLIC

• Defined in File config.h

Define Documentation

TCOD_PUBLIC

Define TCOD_set_errorv

• Defined in File error.h

Define Documentation

TCOD_set_errorv(msg)

Set an error with version, file, and line info added to the output.

Used internally.

Define TCOD_set_errorvf

• Defined in File error.h

Define Documentation

TCOD_set_errorvf(fmt, ...)

Format an error with version, file, and line info added to the output.

Used internally.

Define TCOD_STRVERSION

• Defined in File version.h

Define Documentation

TCOD_STRVERSION

Define TCOD_STRVERSIONNAME

• Defined in File version.h

Define Documentation

TCOD_STRVERSIONNAME

Deprecated since version 1.16.

Define TCOD_TECHVERSION

• Defined in File version.h

Define Documentation

TCOD_TECHVERSION

Deprecated since version 1.16.

Define TCOD_VERSION_ATLEAST

• Defined in File version.h

Define Documentation

TCOD_VERSION_ATLEAST(major, minor)

Returns true if the compiled version of libtcod is at least (major, minor).

New in version 1.19.

Define TCOD_VERSIONNUM

• Defined in File version.h

Define Documentation

TCOD_VERSIONNUM(major, minor, patch)

Converts version numbers into a numeric value.

(1, 2, 3) -> 0x10203

New in version 1.16.

Define TCODLIB_API_INLINE_EXPORT

• Defined in File config.h

Define Documentation

TCODLIB_API_INLINE_EXPORT

Define TCODLIB_BEGIN_IGNORE_DEPRECATIONS

• Defined in File config.h

Define Documentation

TCODLIB_BEGIN_IGNORE_DEPRECATIONS

Define TCODLIB_END_IGNORE_DEPRECATIONS

• Defined in File config.h

Define Documentation

TCODLIB_END_IGNORE_DEPRECATIONS

Define TCODLIB_FORMAT

• Defined in File config.h

Define Documentation

TCODLIB_FORMAT

Define TCODLIB_PRINTF

• Defined in File config.h

Define Documentation

TCODLIB_PRINTF(str_index, first_arg)

Typedefs

Typedef colornum_t

• Defined in File wrappers.h

Typedef Documentation

typedef unsigned int colornum_t

Typedef SDL_renderer_t

• Defined in File sys.h

Typedef Documentation

typedef void (*SDL_renderer_t)(struct SDL_Surface *sdl_renderer)

Typedef tcod::ConsolePtr

• Defined in File console_types.hpp

Typedef Documentation

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

A unique pointer to a TCOD_Console.

New in version 1.19.

Typedef tcod::ContextPtr

• Defined in File context.h

Typedef Documentation

typedef std::unique_ptr<TCOD_Context, ContextDeleter> tcod::ContextPtr

Typedef tcod::ContextSharedPtr

• Defined in File context.h

Typedef Documentation

typedef std::shared_ptr<TCOD_Context> tcod::ContextSharedPtr

Typedef tcod::ImagePtr

• Defined in File image.hpp

Typedef Documentation

typedef std::unique_ptr<TCOD_Image, ImageDeleter> tcod::ImagePtr

A unique pointer to a TCOD_Image.

New in version 1.24.

Typedef tcod::TilesetPtr

• Defined in File tileset.hpp

Typedef Documentation

typedef std::unique_ptr<TCOD_Tileset, TilesetDeleter> tcod::TilesetPtr

A unique pointer to a TCOD_Tileset.

New in version 1.19.

Typedef TCOD_bsp_callback_t

• Defined in File bsp.h

Typedef Documentation

typedef bool (*TCOD_bsp_callback_t)(TCOD_bsp_t *node, void *userData)

Typedef TCOD_color_t

• Defined in File color.h

Typedef Documentation

typedef struct TCOD_ColorRGB TCOD_color_t

Typedef TCOD_ColorRGB

• Defined in File color.h

Typedef Documentation

typedef struct TCOD_ColorRGB TCOD_ColorRGB

Typedef TCOD_ColorRGBA

• Defined in File color.h

Typedef Documentation

typedef struct TCOD_ColorRGBA TCOD_ColorRGBA

Typedef TCOD_cond_t

• Defined in File sys.h

Typedef Documentation

typedef void *TCOD_cond_t

Typedef TCOD_Console

• Defined in File console.h

Typedef Documentation

typedef struct TCOD_Console TCOD_Console

Typedef TCOD_console_t

• Defined in File console.h

Typedef Documentation

typedef struct TCOD_Console *TCOD_console_t

Typedef TCOD_ConsoleTile

• Defined in File console.h

Typedef Documentation

typedef struct TCOD_ConsoleTile TCOD_ConsoleTile

The raw data for a single TCOD_Console tile.

New in version 1.19.

Typedef TCOD_Context

• Defined in File context.h

Typedef Documentation

typedef struct TCOD_Context TCOD_Context

Typedef TCOD_ContextParams

• Defined in File context.h

Typedef Documentation

typedef struct TCOD_ContextParams TCOD_ContextParams

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

New in version 1.19.

Typedef TCOD_DEPRECATED_ENUM

• Defined in File console_types.h

Typedef Documentation

typedef enum TCOD_chars_t TCOD_DEPRECATED_ENUM

Non-standard special character codes.

Deprecated:

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

Typedef TCOD_Dijkstra

• Defined in File path.h

Typedef Documentation

typedef struct TCOD_Dijkstra TCOD_Dijkstra

Dijkstra data structure.

All attributes are considered private.

Typedef TCOD_dijkstra_t

• Defined in File path.h

Typedef Documentation

typedef struct TCOD_Dijkstra *TCOD_dijkstra_t

Typedef TCOD_Error

• Defined in File error.h

Typedef Documentation

typedef enum TCOD_Error TCOD_Error

An enum of libtcod error codes.

On values other than TCOD_E_OK you can use TCOD_get_error() to learn more information.

New in version 1.16.

Typedef TCOD_Image

• Defined in File image.h

Typedef Documentation

typedef struct TCOD_Image TCOD_Image

Typedef TCOD_image_t

• Defined in File image.h

Typedef Documentation

typedef TCOD_Image *TCOD_image_t

Typedef TCOD_key_t

• Defined in File console_types.h

Typedef Documentation

typedef struct TCOD_key_t 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.

Typedef TCOD_keycode_t

• Defined in File console_types.h

Typedef Documentation

typedef enum TCOD_keycode_t 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.

Typedef TCOD_library_t

• Defined in File sys.h

Typedef Documentation

typedef void *TCOD_library_t

Typedef TCOD_line_listener_t

• Defined in File bresenham.h

Typedef Documentation

typedef bool (*TCOD_line_listener_t)(int x, int y)

A callback to be passed to TCOD_line.

The points given to the callback include both the starting and ending positions.

Param x:

Param y:

Return:

As long as this callback returns true it will be called with the next x,y point on the line.

Typedef TCOD_list_t

• Defined in File list.h

Typedef Documentation

typedef struct TCOD_List *TCOD_list_t

Typedef TCOD_LoggingCallback

• Defined in File logging.h

Typedef Documentation

typedef void (*TCOD_LoggingCallback)(const TCOD_LogMessage *message, void *userdata)

A callback for logger listeners.

Typedef TCOD_LogLevel

• Defined in File logging.h

Typedef Documentation

typedef enum TCOD_LogLevel TCOD_LogLevel

Typedef TCOD_LogMessage

• Defined in File logging.h

Typedef Documentation

typedef struct TCOD_LogMessage TCOD_LogMessage

Information being logged, this is a temporary object which doesn’t last longer than the logging callbacks.

This struct will not contain NULL character pointers.

New in version 1.19.

Typedef TCOD_Map

• Defined in File fov_types.h

Typedef Documentation

typedef struct TCOD_Map TCOD_Map

Private map struct.

Typedef TCOD_map_t

• Defined in File fov_types.h

Typedef Documentation

typedef TCOD_Map *TCOD_map_t

Typedef TCOD_mouse_t

• Defined in File mouse_types.h

Typedef Documentation

typedef struct TCOD_mouse_t 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.

Typedef TCOD_MouseTransform

• Defined in File mouse_types.h

Typedef Documentation

typedef struct TCOD_MouseTransform TCOD_MouseTransform

Info needed to convert between mouse pixel and tile coordinates.

Internal use only.

double pixel_x, pixel_y, tile_x, tile_y;
TCOD_MouseTransform transform;
// Convert pixel coordinates to tile coordinates.
tile_x = (pixel_x - transform.offset_x) * transform.scale_x;
tile_y = (pixel_y - transform.offset_y) * transform.scale_y;
// Convert tile coordinates to pixel coordinates.
pixel_x = tile_x / transform.scale_x + transform.offset_x;
pixel_y = tile_y / transform.scale_y + transform.offset_y;

New in version 1.24.

Typedef TCOD_mutex_t

• Defined in File sys.h

Typedef Documentation

typedef void *TCOD_mutex_t

Typedef TCOD_namegen_t

• Defined in File namegen.h

Typedef Documentation

typedef struct TCOD_NameGen *TCOD_namegen_t

Typedef TCOD_Noise

• Defined in File noise.h

Typedef Documentation

typedef struct TCOD_Noise TCOD_Noise

Typedef TCOD_noise_t

• Defined in File noise.h

Typedef Documentation

typedef TCOD_Noise *TCOD_noise_t

Typedef TCOD_Parser

• Defined in File parser.h

Typedef Documentation

typedef struct TCOD_Parser TCOD_Parser

Parser, member variables are for internal use.

Typedef TCOD_parser_custom_t

• Defined in File parser.h

Typedef Documentation

typedef TCOD_value_t (*TCOD_parser_custom_t)(TCOD_lex_t *lex, struct TCOD_parser_listener_t *listener, struct TCOD_ParserStruct *str, char *propname)

Typedef TCOD_parser_int_t

• Defined in File parser.h

Typedef Documentation

typedef struct TCOD_Parser TCOD_parser_int_t

Typedef TCOD_parser_listener_t

• Defined in File parser.h

Typedef Documentation

typedef struct TCOD_parser_listener_t TCOD_parser_listener_t

Typedef TCOD_parser_struct_t

• Defined in File parser.h

Typedef Documentation

typedef struct TCOD_ParserStruct *TCOD_parser_struct_t

Typedef TCOD_parser_t

• Defined in File parser.h

Typedef Documentation

typedef struct TCOD_Parser *TCOD_parser_t

Typedef TCOD_ParserStruct

• Defined in File parser.h

Typedef Documentation

typedef struct TCOD_ParserStruct TCOD_ParserStruct

Parser struct, member variables are for internal use.

Typedef TCOD_path_func_t

• Defined in File path.h

Typedef Documentation

typedef float (*TCOD_path_func_t)(int xFrom, int yFrom, int xTo, int yTo, void *user_data)

Typedef TCOD_path_t

• Defined in File path.h

Typedef Documentation

typedef struct TCOD_Path *TCOD_path_t

Typedef TCOD_PrintParamsRGB

• Defined in File console_printing.h

Typedef Documentation

typedef struct TCOD_PrintParamsRGB TCOD_PrintParamsRGB

Information about a string to be printed.

Typedef TCOD_Random

• Defined in File mersenne_types.h

Typedef Documentation

typedef union TCOD_Random TCOD_Random

Pseudorandom number generator toolkit, all attributes are private.

Typedef TCOD_random_t

• Defined in File mersenne_types.h

Typedef Documentation

typedef union TCOD_Random *TCOD_random_t

Typedef TCOD_renderer_t

• Defined in File console_types.h

Typedef Documentation

typedef enum TCOD_renderer_t TCOD_renderer_t

Libtcod rendering modes.

Typedef TCOD_semaphore_t

• Defined in File sys.h

Typedef Documentation

typedef void *TCOD_semaphore_t

Typedef TCOD_struct_int_t

• Defined in File parser.h

Typedef Documentation

typedef struct TCOD_ParserStruct TCOD_struct_int_t

Typedef TCOD_text_t

• Defined in File txtfield.h

Typedef Documentation

typedef struct TCOD_Text *TCOD_text_t

Typedef TCOD_thread_t

• Defined in File sys.h

Typedef Documentation

typedef void *TCOD_thread_t

Typedef TCOD_Tileset

• Defined in File tileset.h

Typedef Documentation

typedef struct TCOD_Tileset TCOD_Tileset

Typedef TCOD_TilesetAtlasSDL2

• Defined in File renderer_sdl2.h

Typedef Documentation

typedef struct TCOD_TilesetAtlasSDL2 TCOD_TilesetAtlasSDL2

An SDL2 tileset atlas.

This prepares a tileset for use with SDL2.

New in version 1.16.

Typedef TCOD_tree_t

• Defined in File tree.h

Typedef Documentation

typedef struct TCOD_tree_t TCOD_tree_t

Typedef TCOD_ViewportOptions

• Defined in File context_viewport.h

Typedef Documentation

typedef struct TCOD_ViewportOptions TCOD_ViewportOptions

Typedef TCOD_zip_t

• Defined in File zip.h

Typedef Documentation

typedef struct TCOD_Zip *TCOD_zip_t