Classes
struct	TCOD_ConsoleTile
	The raw data for a single TCOD_Console tile. More...
struct	TCOD_Console
	A libtcod console containing a grid of tiles with {ch, fg, bg} information. More...

Typedefs
typedef enum TCOD_bkgnd_flag_t	TCOD_bkgnd_flag_t
typedef enum TCOD_alignment_t	TCOD_alignment_t
typedef struct TCOD_ConsoleTile	TCOD_ConsoleTile
	The raw data for a single TCOD_Console tile.
typedef struct TCOD_Console	TCOD_Console
typedef struct TCOD_Console *	TCOD_console_t

Enumerations
enum	TCOD_bkgnd_flag_t { TCOD_BKGND_NONE , TCOD_BKGND_SET , TCOD_BKGND_MULTIPLY , TCOD_BKGND_LIGHTEN , TCOD_BKGND_DARKEN , TCOD_BKGND_SCREEN , TCOD_BKGND_COLOR_DODGE , TCOD_BKGND_COLOR_BURN , TCOD_BKGND_ADD , TCOD_BKGND_ADDA , TCOD_BKGND_BURN , TCOD_BKGND_OVERLAY , TCOD_BKGND_ALPH , TCOD_BKGND_DEFAULT }
	Background color blend modes.
enum	TCOD_alignment_t { TCOD_LEFT , TCOD_RIGHT , TCOD_CENTER }
	Print justification options.

Functions
TCOD_Console *	TCOD_console_new (int w, int h)
	Return a new console with a specific number of columns and rows.
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.
void	TCOD_console_set_key_color (TCOD_Console *con, TCOD_color_t col)
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.
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)
void	TCOD_console_delete (TCOD_Console *console)
	Delete a console.
void	TCOD_console_set_default_background (TCOD_Console *con, TCOD_color_t col)
void	TCOD_console_set_default_foreground (TCOD_Console *con, TCOD_color_t col)
void	TCOD_console_clear (TCOD_Console *con)
	Clear a console to its default colors and the space character code.
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.
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.
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.
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.
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.
void	TCOD_console_set_background_flag (TCOD_Console *con, TCOD_bkgnd_flag_t flag)
	Set a consoles default background flag.
TCOD_bkgnd_flag_t	TCOD_console_get_background_flag (TCOD_Console *con)
	Return a consoles default background flag.
void	TCOD_console_set_alignment (TCOD_Console *con, TCOD_alignment_t alignment)
	Set a consoles default alignment.
TCOD_alignment_t	TCOD_console_get_alignment (TCOD_Console *con)
	Return a consoles default alignment.
TCOD_color_t	TCOD_console_get_default_background (TCOD_Console *con)
TCOD_color_t	TCOD_console_get_default_foreground (TCOD_Console *con)
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.
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.
int	TCOD_console_get_char (const TCOD_Console *con, int x, int y)
	Return a character code of a console at x,y.
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.
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.
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.
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.
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.
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.
TCOD_Console *	TCOD_console_from_xp (const char *filename)
	Return a new console loaded from a REXPaint .xp file.
bool	TCOD_console_load_xp (TCOD_Console con, const char filename)
	Update a console from a REXPaint .xp file.
bool	TCOD_console_save_xp (const TCOD_Console con, const char filename, int compress_level)
	Save a console as a REXPaint .xp file.
TCOD_list_t	TCOD_console_list_from_xp (const char *filename)
	Return a list of consoles from a REXPaint file.
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.
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.
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.
int	TCOD_load_xp (const char path, int n, TCOD_Console *out)
	Load an array of consoles from a REXPaint file.
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.

Detailed Description

Typedef Documentation

◆ TCOD_ConsoleTile

typedef struct TCOD_ConsoleTile TCOD_ConsoleTile

The raw data for a single TCOD_Console tile.

embed:rst:leading-asterisk 
.. versionadded:: 1.19

Function Documentation

◆ TCOD_console_blit()

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.

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.

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

embed:rst:leading-asterisk 
*  .. versionchanged:: 1.16
*      Blits can now handle per-cell alpha transparency.
*

◆ TCOD_console_delete()

void TCOD_console_delete ( TCOD_Console * console )

Delete a console.

Parameters

console A console pointer.

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

◆ TCOD_console_draw_frame_rgb()

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.

embed:rst:leading-asterisk 
.. versionadded:: 1.19

◆ TCOD_console_draw_rect_rgb()

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_console_from_xp()

TCOD_Console * 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* object. New consoles will need to be deleted with a call to TCOD_console_delete. Returns NULL on an error.

◆ TCOD_console_get_char()

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_console_get_char_background()

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_console_get_char_foreground()

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_console_hline()

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.

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.

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

◆ TCOD_console_list_from_xp()

TCOD_list_t TCOD_console_list_from_xp ( const char * filename )

Return a list of consoles from a REXPaint file.

Parameters

[in] filename A path to the REXPaint file.

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

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

embed:rst:leading-asterisk 
.. deprecated:: 1.20
    TCOD_list_t is deprecated, use TCOD_load_xp instead.

◆ TCOD_console_list_save_xp()

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.

Parameters

[in]	console_list	A TCOD_list_t of TCOD_Console* 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.

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.

embed:rst:leading-asterisk 
.. deprecated:: 1.20
    TCOD_list_t is deprecated, use TCOD_save_xp instead.

◆ TCOD_console_load_xp()

bool TCOD_console_load_xp	(	TCOD_Console *	con,
		const char *	filename )

Update a console from a REXPaint .xp file.

Parameters

[out]	con	A console instance to update from the REXPaint file.
[in]	filename	A path to the REXPaint file.

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

◆ TCOD_console_new()

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.

◆ TCOD_console_put_char()

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.

◆ TCOD_console_put_char_ex()

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.

◆ TCOD_console_put_rgb()

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.

◆ TCOD_console_rect()

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_console_save_xp()

bool TCOD_console_save_xp	(	const TCOD_Console *	con,
		const char *	filename,
		int	compress_level )

Save a console as a REXPaint .xp file.

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, or false when an issue is detected.

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

◆ TCOD_console_set_alignment()

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_console_set_background_flag()

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.

◆ TCOD_console_set_char()

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.

◆ TCOD_console_set_char_background()

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.

◆ TCOD_console_set_char_foreground()

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.

◆ TCOD_console_vline()

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.

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.

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

◆ TCOD_load_xp()

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

Load an array of consoles from a REXPaint file.

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.

embed:rst:leading-asterisk 
.. versionadded:: 1.18

◆ TCOD_load_xp_from_memory()

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.

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.

embed:rst:leading-asterisk 
.. versionadded:: 1.18

◆ TCOD_save_xp()

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.

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.

embed:rst:leading-asterisk 
.. versionadded:: 1.18

◆ TCOD_save_xp_to_memory()

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.

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.

embed:rst:leading-asterisk 
.. versionadded:: 1.18

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ TCOD_ConsoleTile

Function Documentation

◆ TCOD_console_blit()

◆ TCOD_console_delete()

◆ TCOD_console_draw_frame_rgb()

◆ TCOD_console_draw_rect_rgb()

◆ TCOD_console_from_xp()

◆ TCOD_console_get_char()

◆ TCOD_console_get_char_background()

◆ TCOD_console_get_char_foreground()

◆ TCOD_console_hline()

◆ TCOD_console_list_from_xp()

◆ TCOD_console_list_save_xp()

◆ TCOD_console_load_xp()

◆ TCOD_console_new()

◆ TCOD_console_put_char()

◆ TCOD_console_put_char_ex()

◆ TCOD_console_put_rgb()

◆ TCOD_console_rect()

◆ TCOD_console_save_xp()

◆ TCOD_console_set_alignment()

◆ TCOD_console_set_background_flag()

◆ TCOD_console_set_char()

◆ TCOD_console_set_char_background()

◆ TCOD_console_set_char_foreground()

◆ TCOD_console_vline()

◆ TCOD_load_xp()

◆ TCOD_load_xp_from_memory()

◆ TCOD_save_xp()

◆ TCOD_save_xp_to_memory()