Public Member Functions
	TCODImage () noexcept=default
	Default constructs an image. This will be in a partially invalid state until assigned a real image.
	TCODImage (int width, int height)
	You can create an image of any size, filled with black with this function.
	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).
	TCODImage (const TCODConsole *console)
	You can create an image from any console (either the root console or an offscreen console).
	TCODImage (tcod::ImagePtr image) noexcept
	Take ownership of an image pointer.
	TCODImage (const TCODImage &)=delete
TCODImage &	operator= (const TCODImage &)=delete
	TCODImage (TCODImage &&rhs) noexcept
TCODImage &	operator= (TCODImage &&rhs) noexcept
	TCODImage (const tcod::Matrix< TCOD_ColorRGB, 2 > &pixels)
	Construct a new TCODImage object from a Matrix of 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.
void	getSize (int w, int h) const
	You can read the size of an image in pixels with this function.
auto	getSize () const noexcept -> std::array< int, 2 >
	Get the {width, height} of this image.
TCODColor	getPixel (int x, int y) const
	You can read the colors from an image with this function.
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.
bool	isPixelTransparent (int x, int y) const
	You can use this simpler version (for images with alpha layer, returns true only if alpha == 0) :
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.
void	clear (const TCODColor col)
	You can fill the whole image with a color with :
void	putPixel (int x, int y, const TCODColor col)
void	scale (int new_w, int new_h)
	You can resize an image and scale its content.
void	hflip ()
void	vflip ()
void	rotate90 (int numRotations=1)
	Rotate the image clockwise by increment of 90 degrees.
void	invert ()
void	save (const char *filename) const
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.
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	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.
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 :
void	blit2x (TCOD_Console &dest, int dx, int dy, int sx=0, int sy=0, int w=-1, int h=-1) const
TCOD_Image *	get_data () noexcept
	Return the pointer to this objects TCOD_Image data.
const TCOD_Image *	get_data () const noexcept
	Return the const pointer to this objects TCOD_Image data.
	TCODImage (TCOD_image_t img)
	operator TCOD_Image & ()
	Allow implicit conversions to TCOD_Image&.
	operator const TCOD_Image & () const
	Allow implicit conversions to const TCOD_Image&.

Protected Attributes
struct TCOD_Image *	data {nullptr}
bool	deleteData {false}

Constructor & Destructor Documentation

◆ TCODImage() [1/6]

TCODImage::TCODImage ( )

defaultnoexcept

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() [2/6]

TCODImage::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() [3/6]

TCODImage::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() [4/6]

TCODImage::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.

◆ TCODImage() [5/6]

TCODImage::TCODImage ( tcod::ImagePtr image )

inlinenoexcept

Take ownership of an image pointer.

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

◆ TCODImage() [6/6]

TCODImage::TCODImage ( const tcod::Matrix< TCOD_ColorRGB, 2 > & pixels )

inlineexplicit

Construct a new TCODImage object from a Matrix of pixels.

This constructor is provisional.

Parameters

pixels A 2D matrix of RGB pixels.

Member Function Documentation

◆ blit()

void TCODImage::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.

◆ blit2x()

void TCODImage::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.

◆ blitRect()

void TCODImage::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.

◆ clear()

void TCODImage::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.

◆ get_data() [1/2]

const TCOD_Image * TCODImage::get_data ( ) const

inlinenoexcept

Return the const pointer to this objects TCOD_Image data.

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

◆ get_data() [2/2]

TCOD_Image * TCODImage::get_data ( )

inlinenoexcept

Return the pointer to this objects TCOD_Image data.

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

◆ getAlpha()

int TCODImage::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

◆ getMipmapPixel()

TCODColor TCODImage::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.

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

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)

◆ getPixel()

TCODColor TCODImage::getPixel	(	int	x,
		int	y ) const

You can read the colors from an image with this function.

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

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)

◆ getSize() [1/2]

auto TCODImage::getSize ( ) const->std::array< int, 2 >

inlinenodiscardnoexcept

Get the {width, height} of this image.

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

◆ getSize() [2/2]

void TCODImage::getSize	(	int *	w,
		int *	h ) const

You can read the size of an image in pixels with this function.

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.

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

◆ hflip()

void TCODImage::hflip ( )

Parameters

image In the C and Python version, the image handler, obtained with the load function.

◆ invert()

void TCODImage::invert ( )

Parameters

image In the C and Python version, the image handler, obtained with the load function.

◆ isPixelTransparent()

bool TCODImage::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

◆ operator const TCOD_Image &()

TCODImage::operator const TCOD_Image & ( ) const

inlinenodiscard

Allow implicit conversions to const TCOD_Image&.

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

◆ operator TCOD_Image &()

TCODImage::operator TCOD_Image & ( )

inlinenodiscard

Allow implicit conversions to TCOD_Image&.

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

◆ putPixel()

void TCODImage::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.

◆ refreshConsole()

void TCODImage::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).

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.

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)

◆ rotate90()

void TCODImage::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.

◆ save()

void TCODImage::save ( const char * filename ) const

You can save an image to a 24 bits .bmp or .png file.

Parameters

image	In the C version, the image handler, obtained with any image creation function.
filename	Name of the .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")

◆ scale()

void TCODImage::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.

◆ setKeyColor()

void TCODImage::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.

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.

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)

◆ vflip()

void TCODImage::vflip ( )

Parameters

image In the C and Python version, the image handler, obtained with the load function.

The documentation for this class was generated from the following file:

C:/Users/4b796/Projects/libtcod/src/libtcod/image.hpp

Public Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ TCODImage() [1/6]

◆ TCODImage() [2/6]

◆ TCODImage() [3/6]

◆ TCODImage() [4/6]

◆ TCODImage() [5/6]

◆ TCODImage() [6/6]

Member Function Documentation

◆ blit()

◆ blit2x()

◆ blitRect()

◆ clear()

◆ get_data() [1/2]

◆ get_data() [2/2]

◆ getAlpha()

◆ getMipmapPixel()

◆ getPixel()

◆ getSize() [1/2]

◆ getSize() [2/2]

w = 80, h = 50

◆ hflip()

◆ invert()

◆ isPixelTransparent()

◆ operator const TCOD_Image &()

◆ operator TCOD_Image &()

◆ putPixel()

◆ refreshConsole()

... modify the console ..

◆ rotate90()

◆ save()

◆ scale()

◆ setKeyColor()

◆ vflip()