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.
Initializing the console¶
Creating the game window¶
-
enum
TCOD_renderer_t
¶ The available renderers.
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.
-
enumerator
TCOD_RENDERER_SDL
¶ A software based renderer.
The font file is loaded into RAM instead of VRAM in this implementation.
-
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.
-
enumerator
TCOD_NB_RENDERERS
¶
-
enumerator
-
TCOD_Error
TCOD_console_init_root
(int w, int h, const char *title, bool fullscreen, TCOD_renderer_t renderer)¶ Initialize the libtcod graphical engine.
You may want to call TCOD_console_set_custom_font BEFORE calling this function. By default this function loads libtcod’s
terminal.png
image from the working directory.Afterwards TCOD_quit must be called before the program exits.
Returns 0 on success, or -1 on an error, you can check the error with TCOD_sys_get_error()
renderer
and vsync settings can be overridden by theTCOD_RENDERER
orTCOD_VSYNC
environment variables.Valid case-sensitive options for
TCOD_RENDERER
are:sdl
opengl
glsl
sdl2
opengl2
Valid options for
TCOD_VSYNC
are0
or1
.Changed in version 1.12: Now returns -1 on error instead of crashing.
Changed in version 1.13: Added the TCOD_RENDERER and TCOD_VSYNC overrides.
- Parameters
w – The width in tiles.
h – The height in tiles.
title – The title for the window.
fullscreen – Fullscreen option.
renderer – Which renderer to use when rendering the console.
-
void
TCOD_quit
(void)¶ Shutdown libtcod.
This must be called before your program exits.
New in version 1.8.
Using a custom bitmap font¶
-
enum
TCOD_font_flags_t
¶ These font flags can be OR’d together into a bit-field and passed to TCOD_console_set_custom_font.
Values:
-
enumerator
TCOD_FONT_LAYOUT_ASCII_INCOL
¶ Tiles are arranged in column-major order.
0 3 6 1 4 7 2 5 8
-
enumerator
TCOD_FONT_LAYOUT_ASCII_INROW
¶ Tiles are arranged in row-major order.
0 1 2 3 4 5 6 7 8
-
enumerator
TCOD_FONT_TYPE_GREYSCALE
¶ Converts all tiles into a monochrome gradient.
-
enumerator
TCOD_FONT_TYPE_GRAYSCALE
¶
-
enumerator
TCOD_FONT_LAYOUT_TCOD
¶ A unique layout used by some of libtcod’s fonts.
-
enumerator
TCOD_FONT_LAYOUT_CP437
¶ Decode a code page 437 tileset into Unicode code-points.
New in version 1.10.
-
enumerator
-
TCOD_Error
TCOD_console_set_custom_font
(const char *fontFile, int flags, int nb_char_horiz, int nb_char_vertic)¶ Set a font image to be loaded during initialization.
fontFile
will be case-sensitive depending on the platform.Returns 0 on success, or -1 on an error, you can check the error with TCOD_sys_get_error()
Changed in version 1.12: Now returns -1 on error instead of crashing.
- Parameters
fontFile – The path to a font image.
flags – A TCOD_font_flags_t bit-field describing the font image contents.
nb_char_horiz – The number of columns in the font image.
nb_char_vertic – The number of rows in the font image.
Using custom characters mapping¶
-
void
TCOD_console_map_ascii_code_to_font
(int asciiCode, int fontCharX, int fontCharY)¶ Remap a character code to a tile.
X,Y parameters are the coordinate of the tile, not pixel-coordinates.
- Parameters
asciiCode – Character code to modify.
fontCharX – X tile-coordinate, starting from the left at zero.
fontCharY – Y tile-coordinate, starting from the top at zero.
-
void
TCOD_console_map_ascii_codes_to_font
(int asciiCode, int nbCodes, int fontCharX, int fontCharY)¶ Remap a series of character codes to a row of tiles.
This function always assigns tiles in row-major order, even if the TCOD_FONT_LAYOUT_ASCII_INCOL flag was set.
- Parameters
asciiCode – The starting character code.
nbCodes – Number of character codes to assign.
fontCharX – First X tile-coordinate, starting from the left at zero.
fontCharY – First Y tile-coordinate, starting from the top at zero.
-
void
TCOD_console_map_string_to_font
(const char *s, int fontCharX, int fontCharY)¶ Remap a string of character codes to a row of tiles.
This function always assigns tiles in row-major order, even if the TCOD_FONT_LAYOUT_ASCII_INCOL flag was set.
- Parameters
s – A null-terminated string.
fontCharX – First X tile-coordinate, starting from the left at zero.
fontCharY – First Y tile-coordinate, starting from the top at zero.
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.
Drawing on the root console¶
Basic printing 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 w, int h, 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.
-
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.
-
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, ...)¶
Background effect flags¶
-
enum
TCOD_bkgnd_flag_t
¶ Background color blend modes.
Values:
-
enumerator
TCOD_BKGND_NONE
¶
-
enumerator
TCOD_BKGND_SET
¶
-
enumerator
TCOD_BKGND_MULTIPLY
¶
-
enumerator
TCOD_BKGND_LIGHTEN
¶
-
enumerator
TCOD_BKGND_DARKEN
¶
-
enumerator
TCOD_BKGND_SCREEN
¶
-
enumerator
TCOD_BKGND_COLOR_DODGE
¶
-
enumerator
TCOD_BKGND_COLOR_BURN
¶
-
enumerator
TCOD_BKGND_ADD
¶
-
enumerator
TCOD_BKGND_ADDA
¶
-
enumerator
TCOD_BKGND_BURN
¶
-
enumerator
TCOD_BKGND_OVERLAY
¶
-
enumerator
TCOD_BKGND_ALPH
¶
-
enumerator
TCOD_BKGND_DEFAULT
¶
-
enumerator
String printing alignment¶
-
enum
TCOD_alignment_t
¶ Print justification options.
Values:
-
enumerator
TCOD_LEFT
¶
-
enumerator
TCOD_RIGHT
¶
-
enumerator
TCOD_CENTER
¶
-
enumerator
-
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.
Printing functions using 8-bit encodings¶
-
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 a 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 a 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 a 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.
-
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 the.
- 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 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
(struct 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
(struct 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.
Printing functions using wchar_t¶
Note
These functions say they are UTF, however they will behave as UCS2 or UCS4 depending on the platform.
-
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, ...)¶
-
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.
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)¶ Fade the color of the display.
- Parameters
val – Where at 255 colors are normal and at 0 colors are completely faded.
fadecol – Color to fade towards.
-
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
¶ Values:
-
enumerator
TCOD_CHAR_HLINE
¶
-
enumerator
TCOD_CHAR_VLINE
¶
-
enumerator
TCOD_CHAR_NE
¶
-
enumerator
TCOD_CHAR_NW
¶
-
enumerator
TCOD_CHAR_SE
¶
-
enumerator
TCOD_CHAR_SW
¶
-
enumerator
TCOD_CHAR_TEEW
¶
-
enumerator
TCOD_CHAR_TEEE
¶
-
enumerator
TCOD_CHAR_TEEN
¶
-
enumerator
TCOD_CHAR_TEES
¶
-
enumerator
TCOD_CHAR_CROSS
¶
-
enumerator
TCOD_CHAR_DHLINE
¶
-
enumerator
TCOD_CHAR_DVLINE
¶
-
enumerator
TCOD_CHAR_DNE
¶
-
enumerator
TCOD_CHAR_DNW
¶
-
enumerator
TCOD_CHAR_DSE
¶
-
enumerator
TCOD_CHAR_DSW
¶
-
enumerator
TCOD_CHAR_DTEEW
¶
-
enumerator
TCOD_CHAR_DTEEE
¶
-
enumerator
TCOD_CHAR_DTEEN
¶
-
enumerator
TCOD_CHAR_DTEES
¶
-
enumerator
TCOD_CHAR_DCROSS
¶
-
enumerator
TCOD_CHAR_BLOCK1
¶
-
enumerator
TCOD_CHAR_BLOCK2
¶
-
enumerator
TCOD_CHAR_BLOCK3
¶
-
enumerator
TCOD_CHAR_ARROW_N
¶
-
enumerator
TCOD_CHAR_ARROW_S
¶
-
enumerator
TCOD_CHAR_ARROW_E
¶
-
enumerator
TCOD_CHAR_ARROW_W
¶
-
enumerator
TCOD_CHAR_ARROW2_N
¶
-
enumerator
TCOD_CHAR_ARROW2_S
¶
-
enumerator
TCOD_CHAR_ARROW2_E
¶
-
enumerator
TCOD_CHAR_ARROW2_W
¶
-
enumerator
TCOD_CHAR_DARROW_H
¶
-
enumerator
TCOD_CHAR_DARROW_V
¶
-
enumerator
TCOD_CHAR_CHECKBOX_UNSET
¶
-
enumerator
TCOD_CHAR_CHECKBOX_SET
¶
-
enumerator
TCOD_CHAR_RADIO_UNSET
¶
-
enumerator
TCOD_CHAR_RADIO_SET
¶
-
enumerator
TCOD_CHAR_SUBP_NW
¶
-
enumerator
TCOD_CHAR_SUBP_NE
¶
-
enumerator
TCOD_CHAR_SUBP_N
¶
-
enumerator
TCOD_CHAR_SUBP_SE
¶
-
enumerator
TCOD_CHAR_SUBP_DIAG
¶
-
enumerator
TCOD_CHAR_SUBP_E
¶
-
enumerator
TCOD_CHAR_SUBP_SW
¶
-
enumerator
TCOD_CHAR_SMILIE
¶
-
enumerator
TCOD_CHAR_SMILIE_INV
¶
-
enumerator
TCOD_CHAR_HEART
¶
-
enumerator
TCOD_CHAR_DIAMOND
¶
-
enumerator
TCOD_CHAR_CLUB
¶
-
enumerator
TCOD_CHAR_SPADE
¶
-
enumerator
TCOD_CHAR_BULLET
¶
-
enumerator
TCOD_CHAR_BULLET_INV
¶
-
enumerator
TCOD_CHAR_MALE
¶
-
enumerator
TCOD_CHAR_FEMALE
¶
-
enumerator
TCOD_CHAR_NOTE
¶
-
enumerator
TCOD_CHAR_NOTE_DOUBLE
¶
-
enumerator
TCOD_CHAR_LIGHT
¶
-
enumerator
TCOD_CHAR_EXCLAM_DOUBLE
¶
-
enumerator
TCOD_CHAR_PILCROW
¶
-
enumerator
TCOD_CHAR_SECTION
¶
-
enumerator
TCOD_CHAR_POUND
¶
-
enumerator
TCOD_CHAR_MULTIPLICATION
¶
-
enumerator
TCOD_CHAR_FUNCTION
¶
-
enumerator
TCOD_CHAR_RESERVED
¶
-
enumerator
TCOD_CHAR_HALF
¶
-
enumerator
TCOD_CHAR_ONE_QUARTER
¶
-
enumerator
TCOD_CHAR_COPYRIGHT
¶
-
enumerator
TCOD_CHAR_CENT
¶
-
enumerator
TCOD_CHAR_YEN
¶
-
enumerator
TCOD_CHAR_CURRENCY
¶
-
enumerator
TCOD_CHAR_THREE_QUARTERS
¶
-
enumerator
TCOD_CHAR_DIVISION
¶
-
enumerator
TCOD_CHAR_GRADE
¶
-
enumerator
TCOD_CHAR_UMLAUT
¶
-
enumerator
TCOD_CHAR_POW1
¶
-
enumerator
TCOD_CHAR_POW3
¶
-
enumerator
TCOD_CHAR_POW2
¶
-
enumerator
TCOD_CHAR_BULLET_SQUARE
¶
-
enumerator
Flushing the root console¶
-
TCOD_Error
TCOD_console_flush
(void)¶ Render and present the root console to the active display.
-
int
TCOD_sys_accumulate_console
(const TCOD_Console *console)¶ Render a console over the display.
console can be any size, the active render will try to scale it to fit the screen.
The function will only work for the SDL2/OPENGL2 renderers.
Unlike
TCOD_console_flush()
this will not present the display. You will need to do that manually, likely with the SDL API.Returns 0 on success, or a negative number on a failure such as the incorrect renderer being active.
New in version 1.11.
Handling user input¶
Blocking user input¶
-
TCOD_key_t
TCOD_console_wait_for_keypress
(bool flush)¶ Wait for a key press event, then return it.
Do not solve input lag issues by arbitrarily dropping events!
- Parameters
flush – If 1 then the event queue will be cleared before waiting for the next event. This should always be 0.
- Returns
A TCOD_key_t struct with the most recent key data.
-
TCOD_event_t
TCOD_sys_wait_for_event
(int eventMask, TCOD_key_t *key, TCOD_mouse_t *mouse, bool flush)¶ Wait for a specific type of event.
This function also returns when the SDL window is being closed.
- Parameters
eventMask – A bit-mask of TCOD_event_t flags.
key – Optional pointer to a TCOD_key_t struct.
mouse – Optional pointer to a TCOD_mouse_t struct.
flush – This should always be false.
- Returns
A TCOD_event_t flag showing which event was actually processed.
Non blocking user input¶
-
TCOD_key_t
TCOD_console_check_for_keypress
(int flags)¶ Return immediately with a recently pressed key.
- Parameters
flags – A TCOD_event_t bit-field, for example:
TCOD_EVENT_KEY_PRESS
- Returns
A TCOD_key_t struct with a recently pressed key. If no event exists then the
vk
attribute will beTCODK_NONE
-
bool
TCOD_console_is_key_pressed
(TCOD_keycode_t key)¶ Return True if the libtcod keycode is held.
Deprecated since version 1.16: You should instead use SDL_GetKeyboardState to check if keys are held.
-
TCOD_event_t
TCOD_sys_check_for_event
(int eventMask, TCOD_key_t *key, TCOD_mouse_t *mouse)¶ Check for a specific type of event.
- Parameters
eventMask – A bit-mask of TCOD_event_t flags.
key – Optional pointer to a TCOD_key_t struct.
mouse – Optional pointer to a TCOD_mouse_t struct.
flush – This should always be false.
- Returns
A TCOD_event_t flag showing which event was actually processed.
-
TCOD_mouse_t
TCOD_mouse_get_status
(void)¶ Return a copy of the current mouse state.
Key codes¶
-
enum
TCOD_keycode_t
¶ 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
¶
-
enumerator
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_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::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_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
con – 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
[in] filename – 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)¶
-
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
[in] con – The console instance to save.
[in] filename – The filepath to save to.
[in] compress_level – A zlib compression level, from 0 to 9. 1=fast, 6=balanced, 9=slowest, 0=uncompressed.
- Returns
true
when the file is saved successfully, orfalse
when an issue is detected.
-
libtcodpy.
console_list_from_xp
(filename)¶
-
TCOD_list_t
TCOD_console_list_from_xp
(const char *filename)¶ Return a list of consoles from a REXPaint file.
This function can load a REXPaint file with variable layer shapes, which would cause issues for a function like TCOD_console_list_from_xp.
- Parameters
[in] filename – 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.
- Parameters
[in] console_list – A TCOD_list_t of TCOD_console_t objects.
[in] filename – Path to save to.
[in] compress_level – 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
srcCon – 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.
dstCon – 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.