Container for a 2D image. More...

#include <donut/graphics/Image.hpp>

Public Member Functions
	Image () noexcept=default
	Construct an empty image without a value.

	Image (std::size_t width, std::size_t height, PixelFormat pixelFormat, PixelComponentType pixelComponentType, const void *pixels)
	Construct an image copied from a contiguous 2D range of pixels.

	Image (const ImageView &image)
	Construct an image copied from an image view.

	Image (const Filesystem &filesystem, const char *filepath, const ImageOptions &options={})
	Load an image from a virtual file.

	operator bool () const noexcept
	Check if this image has a value.

	operator ImageView () const noexcept
	Get a view over this image.

void	reset () noexcept
	Remove the value from this image and reset it to an empty image.

std::size_t	getWidth () const noexcept
	Get the width of the image.

std::size_t	getHeight () const noexcept
	Get the height of the image.

PixelFormat	getPixelFormat () const noexcept
	Get the pixel format of the image.

PixelComponentType	getPixelComponentType () const noexcept
	Get the pixel component type of the image.

void *	getPixels () noexcept
	Get the pixel data of this image.

const void *	getPixels () const noexcept
	Get the pixel data of this image.

std::size_t	getChannelCount () const noexcept
	Get the number of component channels in the pixel format of this image.

std::size_t	getPixelComponentSize () const noexcept
	Get the size in bytes of a single component of a pixel in this image.

std::size_t	getPixelStride () const noexcept
	Get the stride in bytes of the pixels in this image.

std::size_t	getSizeInBytes () const noexcept
	Get the size in bytes of this image.

Static Public Member Functions
static void	savePNG (const ImageView &image, Filesystem &filesystem, const char *filepath, const ImageSavePNGOptions &options={})
	Save an 8-bit-per-channel image to a PNG file.

static void	saveBMP (const ImageView &image, Filesystem &filesystem, const char *filepath, const ImageSaveBMPOptions &options={})
	Save an 8-bit-per-channel image to a Windows Bitmap file.

static void	saveTGA (const ImageView &image, Filesystem &filesystem, const char *filepath, const ImageSaveTGAOptions &options={})
	Save an 8-bit-per-channel image to a Truevision TARGA file.

static void	saveJPG (const ImageView &image, Filesystem &filesystem, const char *filepath, const ImageSaveJPGOptions &options={})
	Save an 8-bit-per-channel image to a JPEG file.

static void	saveHDR (const ImageView &image, Filesystem &filesystem, const char *filepath, const ImageSaveHDROptions &options={})
	Save a floating-point 32-bit-per-channel image to a Radiance HDR RGBE file.

static void	save (const ImageView &image, Filesystem &filesystem, const char *filepath, const ImageSaveOptions &options={})
	Save an image to a file.

Detailed Description

Container for a 2D image.

See also: ImageView

Examples: example_game.cpp.

Constructor & Destructor Documentation

◆ Image() [1/4]

donut::graphics::Image::Image ( )

defaultnoexcept

Construct an empty image without a value.

◆ Image() [2/4]

donut::graphics::Image::Image	(	std::size_t	width,
		std::size_t	height,
		PixelFormat	pixelFormat,
		PixelComponentType	pixelComponentType,
		const void *	pixels
	)

Construct an image copied from a contiguous 2D range of pixels.

Parameters

width	width of the image, in pixels. Must be 0 if pixels is nullptr.
height	height of the image, in pixels. Must be 0 if pixels is nullptr.
pixelFormat	pixel format of the image. Must be PixelFormat::R if pixels is nullptr.
pixelComponentType	pixel component data type of the image. Must be PixelComponentType::U8 if pixels is nullptr.
pixels	read-only non-owning pointer to the pixel data to copy, or nullptr to create an empty image without a value.

Exceptions

std::bad_alloc on allocation failure.

Warning: If pixels is not nullptr and does not point to a readable contiguous region of memory containing image data of the specified size, format and type, the result is undefined.

◆ Image() [3/4]

donut::graphics::Image::Image ( const ImageView & image )

explicit

Construct an image copied from an image view.

Parameters

image read-only view over the image to copy.

Exceptions

std::bad_alloc on allocation failure.

◆ Image() [4/4]

donut::graphics::Image::Image	(	const Filesystem &	filesystem,
		const char *	filepath,
		const ImageOptions &	options = `{}`
	)

explicit

Load an image from a virtual file.

The supported file formats are:

JPEG (.jpg/.jpeg)
PNG (.png)
Truevision TARGA (.tga)
Windows Bitmap (.bmp)
Photoshop Document (.psd)
GIF (.gif)
Radiance HDR RGBE (.hdr)
Softimage PIC (.pic)
PPM (.ppm)
PGM (.pgm)

Parameters

filesystem	virtual filesystem to load the file from.
filepath	virtual filepath of the image file to load.
options	image options, see ImageOptions.

Exceptions

File::Error	on failure to open the file.
graphics::Error	on failure to load an image from the file.
std::bad_alloc	on allocation failure.

Note: The file format is determined entirely from the file contents; the filename extension is not taken into account.; The component type of the image is determined by the ImageOptions::highDynamicRange option.; For JPEG files, 12 bits per component and arithmetic coding are not supported.; PNG files support 1, 2, 4, 8 and 16 bits per channel.; For BMP files, 1 bit per component and run-length encoding are not supported.; PSD files support 8 and 16 bits per pixel.; For PSD files, only composited view is supported, with no extra channels.; For GIF files, animation is not supported, and the reported number of channels is always 4.; For PPM and PGM files, only binary format is supported.

Member Function Documentation

◆ savePNG()

static void donut::graphics::Image::savePNG	(	const ImageView &	image,
		Filesystem &	filesystem,
		const char *	filepath,
		const ImageSavePNGOptions &	options = `{}`
	)

static

Save an 8-bit-per-channel image to a PNG file.

Parameters

image	view over the image to save.
filesystem	virtual filesystem to save the file to.
filepath	virtual filepath at which to save the image.
options	saving options, see ImageSavePNGOptions.

Note: This function will fail if the image does not have pixel component type PixelComponentType::U8.

Exceptions

File::Error	on failure to create the file.
graphics::Error	on failure to write the image to the file.
std::bad_alloc	on allocation failure.

◆ saveBMP()

static void donut::graphics::Image::saveBMP	(	const ImageView &	image,
		Filesystem &	filesystem,
		const char *	filepath,
		const ImageSaveBMPOptions &	options = `{}`
	)

static

Save an 8-bit-per-channel image to a Windows Bitmap file.

Parameters

image	view over the image to save.
filesystem	virtual filesystem to save the file to.
filepath	virtual filepath at which to save the image.
options	saving options, see ImageSaveBMPOptions.

Note: This function will fail if the image does not have pixel component type PixelComponentType::U8.

Exceptions

File::Error	on failure to create the file.
graphics::Error	on failure to write the image to the file.
std::bad_alloc	on allocation failure.

◆ saveTGA()

static void donut::graphics::Image::saveTGA	(	const ImageView &	image,
		Filesystem &	filesystem,
		const char *	filepath,
		const ImageSaveTGAOptions &	options = `{}`
	)

static

Save an 8-bit-per-channel image to a Truevision TARGA file.

Parameters

image	view over the image to save.
filesystem	virtual filesystem to save the file to.
filepath	virtual filepath at which to save the image.
options	saving options, see ImageSaveTGAOptions.

Note: This function will fail if the image does not have pixel component type PixelComponentType::U8.

Exceptions

File::Error	on failure to create the file.
graphics::Error	on failure to write the image to the file.
std::bad_alloc	on allocation failure.

◆ saveJPG()

static void donut::graphics::Image::saveJPG	(	const ImageView &	image,
		Filesystem &	filesystem,
		const char *	filepath,
		const ImageSaveJPGOptions &	options = `{}`
	)

static

Save an 8-bit-per-channel image to a JPEG file.

Parameters

image	view over the image to save.
filesystem	virtual filesystem to save the file to.
filepath	virtual filepath at which to save the image.
options	saving options, see ImageSaveJPGOptions.

Note: This function will fail if the image does not have pixel component type PixelComponentType::U8.

Exceptions

File::Error	on failure to create the file.
graphics::Error	on failure to write the image to the file.
std::bad_alloc	on allocation failure.

◆ saveHDR()

static void donut::graphics::Image::saveHDR	(	const ImageView &	image,
		Filesystem &	filesystem,
		const char *	filepath,
		const ImageSaveHDROptions &	options = `{}`
	)

static

Save a floating-point 32-bit-per-channel image to a Radiance HDR RGBE file.

Parameters

image	view over the image to save.
filesystem	virtual filesystem to save the file to.
filepath	virtual filepath at which to save the image.
options	saving options, see ImageSaveHDROptions.

Note: This function will fail if the image does not have pixel component type PixelComponentType::F32.

Exceptions

File::Error	on failure to create the file.
graphics::Error	on failure to write the image to the file.
std::bad_alloc	on allocation failure.

◆ save()

static void donut::graphics::Image::save	(	const ImageView &	image,
		Filesystem &	filesystem,
		const char *	filepath,
		const ImageSaveOptions &	options = `{}`
	)

static

Save an image to a file.

Parameters

image	view over the image to save.
filesystem	virtual filesystem to save the file to.
filepath	virtual filepath at which to save the image.
options	saving options, see ImageSaveOptions.

Note: This function will try to choose a suitable format to save the image to depending on its pixel component type.

Exceptions

File::Error	on failure to create the file.
graphics::Error	on failure to write the image to the file.
std::bad_alloc	on allocation failure.

◆ operator bool()

donut::graphics::Image::operator bool ( ) const

inlineexplicitnoexcept

Check if this image has a value.

Returns: true if the image has a value, false otherwise.

◆ operator ImageView()

donut::graphics::Image::operator ImageView ( ) const

inlinenoexcept

Get a view over this image.

Returns: if the image has a value, returns a read-only non-owning view over it. Otherwise, returns a view that doesn't reference an image.

◆ reset()

void donut::graphics::Image::reset ( )

inlinenoexcept

Remove the value from this image and reset it to an empty image.

◆ getWidth()

std::size_t donut::graphics::Image::getWidth ( ) const

inlinenoexcept

Get the width of the image.

Returns: the width of the image, in pixels, or 0 if the image does not have a value.

See also: getHeight(); getSizeInBytes()

◆ getHeight()

std::size_t donut::graphics::Image::getHeight ( ) const

inlinenoexcept

Get the height of the image.

Returns: the height of the image, in pixels, or 0 if the image does not have a value.

See also: getWidth(); getSizeInBytes()

◆ getPixelFormat()

PixelFormat donut::graphics::Image::getPixelFormat ( ) const

inlinenoexcept

Get the pixel format of the image.

Returns: the pixel format, or PixelFormat::R if the image does not have a value.

See also: getChannelCount()

◆ getPixelComponentType()

PixelComponentType donut::graphics::Image::getPixelComponentType ( ) const

inlinenoexcept

Get the pixel component type of the image.

Returns: the pixel component type, or PixelComponentType::U8 if the image does not have a value.

See also: getPixelComponentSize()

◆ getPixels() [1/2]

void * donut::graphics::Image::getPixels ( )

inlinenoexcept

Get the pixel data of this image.

The pixel data is tightly packed and fully contiguous, and the pixels are stored in row-major order, starting at the bottom left of the image (unless the image is flipped).

Returns: a non-owning pointer to the pixel data, or nullptr if the image does not have a value.

See also: getWidth(); getHeight(); getPixelFormat(); getPixelComponentType()

◆ getPixels() [2/2]

const void * donut::graphics::Image::getPixels ( ) const

inlinenoexcept

Get the pixel data of this image.

The pixel data is tightly packed and fully contiguous, and the pixels are stored in row-major order, starting at the bottom left of the image (unless the image is flipped).

Returns: a read-only non-owning pointer to the pixel data, or nullptr if the image does not have a value.

See also: getWidth(); getHeight(); getPixelFormat(); getPixelComponentType()

◆ getChannelCount()

std::size_t donut::graphics::Image::getChannelCount ( ) const

inlinenoexcept

Get the number of component channels in the pixel format of this image.

Returns: the number of channels, or 0 if the image does not have a value.

See also: getPixelFormat(); getPixelStride()

◆ getPixelComponentSize()

std::size_t donut::graphics::Image::getPixelComponentSize ( ) const

inlinenoexcept

Get the size in bytes of a single component of a pixel in this image.

Returns: the size of the pixel component type, or 0 if the image does not have a value.

See also: getPixelComponentType(); getPixelStride()

◆ getPixelStride()

std::size_t donut::graphics::Image::getPixelStride ( ) const

inlinenoexcept

Get the stride in bytes of the pixels in this image.

Returns: the number of bytes to advance to get from one pixel to the next, or 0 if the image does not have a value.

See also: getChannelCount(); getPixelComponentSize(); getSizeInBytes()

◆ getSizeInBytes()

std::size_t donut::graphics::Image::getSizeInBytes ( ) const

inlinenoexcept

Get the size in bytes of this image.

Returns: the total size of the image, or 0 if the image does not have a value.

See also: getWidth(); getHeight(); getPixelStride()

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

include/donut/graphics/Image.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Image() [1/4]

◆ Image() [2/4]

◆ Image() [3/4]

◆ Image() [4/4]

Member Function Documentation

◆ savePNG()

◆ saveBMP()

◆ saveTGA()

◆ saveJPG()

◆ saveHDR()

◆ save()

◆ operator bool()

◆ operator ImageView()

◆ reset()

◆ getWidth()

◆ getHeight()

◆ getPixelFormat()

◆ getPixelComponentType()

◆ getPixels() [1/2]

◆ getPixels() [2/2]

◆ getChannelCount()

◆ getPixelComponentSize()

◆ getPixelStride()

◆ getSizeInBytes()