Class TCODImage

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 :doxyxml/subcell_comp.png

Pyromancer ! screenshot, making full usage of subcell resolution :doxyxml/subcell_pyro.png
doxyxml/subcell.png

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}

Friends

friend class TCODSystem
friend class TCODZip