SFML - Simple and Fast Multimedia Library

SFML 3.0.1

- Main Page
- Topics
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Loading...
Searching...
No Matches
Public Member Functions | List of all members
sf::Image Class Reference
Graphics module

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;
sf::Color
Utility class for manipulating RGBA colors.
Definition Color.hpp:40
sf::Color::a
std::uint8_t a
Alpha (opacity) component.
Definition Color.hpp:99
sf::Color::Black
static const Color Black
Black predefined color.
Definition Color.hpp:82
sf::Image
Class for loading, manipulating and saving images.
Definition Image.hpp:55

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