Class for loading, manipulating and saving images. More...

#include <SFML/Graphics/Image.hpp>

Public Member Functions
	Image ()=default
	Default constructor.

	Image (Vector2u size, Color color=Color::Black)
	Construct the image and fill it with a unique color.

	Image (Vector2u size, const std::uint8_t *pixels)
	Construct the image from an array of pixels.

	Image (const std::filesystem::path &filename)
	Construct the image from a file on disk.

	Image (const void *data, std::size_t size)
	Construct the image from a file in memory.

	Image (InputStream &stream)
	Construct the image from a custom stream.

void	resize (Vector2u size, Color color=Color::Black)
	Resize the image and fill it with a unique color.

void	resize (Vector2u size, const std::uint8_t *pixels)
	Resize the image from an array of pixels.

bool	loadFromFile (const std::filesystem::path &filename)
	Load the image from a file on disk.

bool	loadFromMemory (const void *data, std::size_t size)
	Load the image from a file in memory.

bool	loadFromStream (InputStream &stream)
	Load the image from a custom stream.

bool	saveToFile (const std::filesystem::path &filename) const
	Save the image to a file on disk.

std::optional< std::vector< std::uint8_t > >	saveToMemory (std::string_view format) const
	Save the image to a buffer in memory.

Vector2u	getSize () const
	Return the size (width and height) of the image.

void	createMaskFromColor (Color color, std::uint8_t alpha=0)
	Create a transparency mask from a specified color-key.

bool	copy (const Image &source, Vector2u dest, const IntRect &sourceRect={}, bool applyAlpha=false)
	Copy pixels from another image onto this one.

void	setPixel (Vector2u coords, Color color)
	Change the color of a pixel.

Color	getPixel (Vector2u coords) const
	Get the color of a pixel.

const std::uint8_t *	getPixelsPtr () const
	Get a read-only pointer to the array of pixels.

void	flipHorizontally ()
	Flip the image horizontally (left <-> right)

void	flipVertically ()
	Flip the image vertically (top <-> bottom)

Detailed Description

Class for loading, manipulating and saving images.

sf::Image is an abstraction to manipulate images as bi-dimensional arrays of pixels.

The class provides functions to load, read, write and save pixels, as well as many other useful functions.

sf::Image can handle a unique internal representation of pixels, which is RGBA 32 bits. This means that a pixel must be composed of 8 bit red, green, blue and alpha channels – just like a sf::Color. All the functions that return an array of pixels follow this rule, and all parameters that you pass to sf::Image functions (such as loadFromMemory) must use this representation as well.

A sf::Image can be copied, but it is a heavy resource and if possible you should always use [const] references to pass or return them to avoid useless copies.

Usage example:

// Load an image file from a file
const sf::Image background("background.jpg");
 
// Create a 20x20 image filled with black color
sf::Image image({20, 20}, sf::Color::Black);
 
// Copy background on image at position (10, 10)
if (!image.copy(background, {10, 10}))
    return -1;
 
// Make the top-left pixel transparent
sf::Color color = image.getPixel({0, 0});
color.a = 0;
image.setPixel({0, 0}, color);
 
// Save the image to a file
if (!image.saveToFile("result.png"))
    return -1;

See also: sf::Texture

Definition at line 54 of file Image.hpp.

Constructor & Destructor Documentation

◆ Image() [1/6]

sf::Image::Image ( )

default

Default constructor.

Constructs an image with width 0 and height 0.

See also: resize

◆ Image() [2/6]

sf::Image::Image	(	Vector2u	size,
		Color	color = Color::Black )

explicit

Construct the image and fill it with a unique color.

Parameters

size	Width and height of the image
color	Fill color

◆ Image() [3/6]

sf::Image::Image	(	Vector2u	size,
		const std::uint8_t *	pixels )

Construct the image from an array of pixels.

The pixel array is assumed to contain 32-bits RGBA pixels, and have the given size. If not, this is an undefined behavior. If pixels is nullptr, an empty image is created.

Parameters

size	Width and height of the image
pixels	Array of pixels to copy to the image

◆ Image() [4/6]

sf::Image::Image ( const std::filesystem::path & filename )

explicit

Construct the image from a file on disk.

The supported image formats are bmp, png, tga, jpg, gif, psd, hdr, pic and pnm. Some format options are not supported, like jpeg with arithmetic coding or ASCII pnm.

Parameters

filename Path of the image file to load

Exceptions

`sf::Exception` if loading was unsuccessful

See also: loadFromFile, loadFromMemory, loadFromStream

◆ Image() [5/6]

sf::Image::Image	(	const void *	data,
		std::size_t	size )

Construct the image from a file in memory.

The supported image formats are bmp, png, tga, jpg, gif, psd, hdr, pic and pnm. Some format options are not supported, like jpeg with arithmetic coding or ASCII pnm.

Parameters

data	Pointer to the file data in memory
size	Size of the data to load, in bytes

Exceptions

`sf::Exception` if loading was unsuccessful

See also: loadFromFile, loadFromMemory, loadFromStream

◆ Image() [6/6]

sf::Image::Image ( InputStream & stream )

explicit

Construct the image from a custom stream.

The supported image formats are bmp, png, tga, jpg, gif, psd, hdr, pic and pnm. Some format options are not supported, like jpeg with arithmetic coding or ASCII pnm.

Parameters

stream Source stream to read from

Exceptions

`sf::Exception` if loading was unsuccessful

See also: loadFromFile, loadFromMemory, loadFromStream

Member Function Documentation

◆ copy()

bool sf::Image::copy	(	const Image &	source,
		Vector2u	dest,
		const IntRect &	sourceRect = {},
		bool	applyAlpha = false )

nodiscard

Copy pixels from another image onto this one.

This function does a slow pixel copy and should not be used intensively. It can be used to prepare a complex static image from several others, but if you need this kind of feature in real-time you'd better use sf::RenderTexture.

If sourceRect is empty, the whole image is copied. If applyAlpha is set to true, alpha blending is applied from the source pixels to the destination pixels using the over operator. If it is false, the source pixels are copied unchanged with their alpha value.

See https://en.wikipedia.org/wiki/Alpha_compositing for details on the over operator.

Note that this function can fail if either image is invalid (i.e. zero-sized width or height), or if sourceRect is not within the boundaries of the source parameter, or if the destination area is out of the boundaries of this image.

On failure, the destination image is left unchanged.

Parameters

source	Source image to copy
dest	Coordinates of the destination position
sourceRect	Sub-rectangle of the source image to copy
applyAlpha	Should the copy take into account the source transparency?

Returns: true if the operation was successful, false otherwise

◆ createMaskFromColor()

void sf::Image::createMaskFromColor	(	Color	color,
		std::uint8_t	alpha = 0 )

Create a transparency mask from a specified color-key.

This function sets the alpha value of every pixel matching the given color to alpha (0 by default), so that they become transparent.

Parameters

color	Color to make transparent
alpha	Alpha value to assign to transparent pixels

◆ flipHorizontally()

void sf::Image::flipHorizontally ( )

Flip the image horizontally (left <-> right)

◆ flipVertically()

void sf::Image::flipVertically ( )

Flip the image vertically (top <-> bottom)

◆ getPixel()

Color sf::Image::getPixel ( Vector2u coords ) const

nodiscard

Get the color of a pixel.

This function doesn't check the validity of the pixel coordinates, using out-of-range values will result in an undefined behavior.

Parameters

coords Coordinates of pixel to change

Returns: Color of the pixel at given coordinates

See also: setPixel

◆ getPixelsPtr()

const std::uint8_t * sf::Image::getPixelsPtr ( ) const

nodiscard

Get a read-only pointer to the array of pixels.

The returned value points to an array of RGBA pixels made of 8 bit integer components. The size of the array is width * height * 4 (getSize().x * getSize().y * 4). Warning: the returned pointer may become invalid if you modify the image, so you should never store it for too long. If the image is empty, a null pointer is returned.

Returns: Read-only pointer to the array of pixels

◆ getSize()

Vector2u sf::Image::getSize ( ) const

nodiscard

Return the size (width and height) of the image.

Returns: Size of the image, in pixels

◆ loadFromFile()

bool sf::Image::loadFromFile ( const std::filesystem::path & filename )

nodiscard

Load the image from a file on disk.

The supported image formats are bmp, png, tga, jpg, gif, psd, hdr, pic and pnm. Some format options are not supported, like jpeg with arithmetic coding or ASCII pnm. If this function fails, the image is left unchanged.

Parameters

filename Path of the image file to load

Returns: true if loading was successful

See also: loadFromMemory, loadFromStream, saveToFile

◆ loadFromMemory()

bool sf::Image::loadFromMemory	(	const void *	data,
		std::size_t	size )

nodiscard

Load the image from a file in memory.

The supported image formats are bmp, png, tga, jpg, gif, psd, hdr, pic and pnm. Some format options are not supported, like jpeg with arithmetic coding or ASCII pnm. If this function fails, the image is left unchanged.

Parameters

data	Pointer to the file data in memory
size	Size of the data to load, in bytes

Returns: true if loading was successful

See also: loadFromFile, loadFromStream, saveToMemory

◆ loadFromStream()

bool sf::Image::loadFromStream ( InputStream & stream )

nodiscard

Load the image from a custom stream.

The supported image formats are bmp, png, tga, jpg, gif, psd, hdr, pic and pnm. Some format options are not supported, like jpeg with arithmetic coding or ASCII pnm. If this function fails, the image is left unchanged.

Parameters

stream Source stream to read from

Returns: true if loading was successful

See also: loadFromFile, loadFromMemory

◆ resize() [1/2]

void sf::Image::resize	(	Vector2u	size,
		Color	color = Color::Black )

Resize the image and fill it with a unique color.

Parameters

size	Width and height of the image
color	Fill color

◆ resize() [2/2]

void sf::Image::resize	(	Vector2u	size,
		const std::uint8_t *	pixels )

Resize the image from an array of pixels.

The pixel array is assumed to contain 32-bits RGBA pixels, and have the given size. If not, this is an undefined behavior. If pixels is nullptr, an empty image is created.

Parameters

size	Width and height of the image
pixels	Array of pixels to copy to the image

◆ saveToFile()

bool sf::Image::saveToFile ( const std::filesystem::path & filename ) const

nodiscard

Save the image to a file on disk.

The format of the image is automatically deduced from the extension. The supported image formats are bmp, png, tga and jpg. The destination file is overwritten if it already exists. This function fails if the image is empty.

Parameters

filename Path of the file to save

Returns: true if saving was successful

See also: saveToMemory, loadFromFile

◆ saveToMemory()

std::optional< std::vector< std::uint8_t > > sf::Image::saveToMemory ( std::string_view format ) const

nodiscard

Save the image to a buffer in memory.

The format of the image must be specified. The supported image formats are bmp, png, tga and jpg. This function fails if the image is empty, or if the format was invalid.

Parameters

format Encoding format to use

Returns: Buffer with encoded data if saving was successful, otherwise std::nullopt

See also: saveToFile, loadFromMemory

◆ setPixel()

void sf::Image::setPixel	(	Vector2u	coords,
		Color	color )

Change the color of a pixel.

This function doesn't check the validity of the pixel coordinates, using out-of-range values will result in an undefined behavior.

Parameters

coords	Coordinates of pixel to change
color	New color of the pixel

See also: getPixel

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

Image.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Image() [1/6]

◆ Image() [2/6]

◆ Image() [3/6]

◆ Image() [4/6]

◆ Image() [5/6]

◆ Image() [6/6]

Member Function Documentation

◆ copy()

◆ createMaskFromColor()

◆ flipHorizontally()

◆ flipVertically()

◆ getPixel()

◆ getPixelsPtr()

◆ getSize()

◆ loadFromFile()

◆ loadFromMemory()

◆ loadFromStream()

◆ resize() [1/2]

◆ resize() [2/2]

◆ saveToFile()

◆ saveToMemory()

◆ setPixel()