LLGL::Image Class Reference

Utility class to manage the storage and attributes of an image. More...

#include <Image.h>

Public Member Functions
	Image ()=default
	Image (const Extent3D &extent, const ImageFormat format, const DataType dataType)
	Constructor to initialize the image with a format, data type, and extent.
	Image (const Extent3D &extent, const ImageFormat format, const DataType dataType, const ColorRGBAf &fillColor)
	Constructor to initialize the image with a format, data type, and extent. The image buffer will be filled with the specified color.
	Image (const Extent3D &extent, const ImageFormat format, const DataType dataType, DynamicByteArray &&data)
	Constructor to initialize the image with all attributes, including the image buffer specified by the 'data' parameter.
	Image (const Image &rhs)
	Copy constructor which copies the entire image buffer from the specified source image.
	Image (Image &&rhs) noexcept
	Move constructor which takes the ownership of the specified source image.
Image &	operator= (const Image &rhs)
	Copy operator which copies the entire image buffer and attributes.
Image &	operator= (Image &&rhs)
	Move operator which takes the ownership of the image buffer.
void	Convert (const ImageFormat format, const DataType dataType, unsigned threadCount=0)
	Converts the image format and data type.
void	Resize (const Extent3D &extent)
	Resizes the image and resets the image buffer.
void	Resize (const Extent3D &extent, const ColorRGBAf &fillColor)
	Resizes the image and initializes the new pixels with the specified color.
void	Resize (const Extent3D &extent, const ColorRGBAf &fillColor, const Offset3D &offset)
	Resizes the image, moves the previous pixels by an offset, and initializes the new pixels outside the previous extent with the specified color.
void	Swap (Image &rhs)
	Swaps all attributes with the specified image.
void	Reset ()
	Resets all image attributes to its default values.
void	Reset (const Extent3D &extent, const ImageFormat format, const DataType dataType, DynamicByteArray &&data)
	Resets all image attributes to the specified values.
DynamicByteArray	Release ()
	Releases the ownership of the image buffer and resets all attributes.
void	Blit (Offset3D dstRegionOffset, const Image &srcImage, Offset3D srcRegionOffset, Extent3D srcRegionExtent)
	Copies a region of the specified source image into this image.
void	ReadPixels (const Offset3D &offset, const Extent3D &extent, const MutableImageView &imageView, unsigned threadCount=0) const
	Reads a region of pixels from this image into the destination image buffer specified by imageView.
void	WritePixels (const Offset3D &offset, const Extent3D &extent, const ImageView &imageView, unsigned threadCount=0)
	Writes a region of pixels to this image from the source image buffer specified by imageView.
ImageView	GetView () const
	Returns a source image descriptor for this image with read-only access to the image data.
MutableImageView	GetMutableView ()
	Returns a destination image descriptor for this image with read/write access to the image data.
const Extent3D &	GetExtent () const
	Returns the extent of the image as 3D vector.
ImageFormat	GetFormat () const
	Returns the format for each pixel. By default ImageFormat::RGBA.
DataType	GetDataType () const
	Returns the data type for each pixel component. By default DataType::UInt8.
const void *	GetData () const
	Returns the image data buffer as constant raw pointer.
void *	GetData ()
	Returns the image data buffer as raw pointer.
std::uint32_t	GetBytesPerPixel () const
	Returns the size (in bytes) for each pixel.
std::uint32_t	GetRowStride () const
	Returns the stride (in bytes) for each row.
std::uint32_t	GetDepthStride () const
	Returns the stride (in bytes) for each depth slice.
std::uint32_t	GetNumPixels () const
	Returns the number of pixels this image has.
std::uint32_t	GetDataSize () const
	Returns the size (in bytes) of the image buffer.
bool	IsRegionInside (const Offset3D &offset, const Extent3D &extent) const
	Returns true if the specified sub-image region is inside the image.

Detailed Description

Utility class to manage the storage and attributes of an image.

This class is not required for any interaction with the render system. It can be used as utility to handle 2D and 3D image data before passing it to a hardware texture.

Remarks

This class holds the ownership of an image buffer and its attributes. The primary functions are implemented as global functions like GenerateImageBuffer for instance.

Note

All image operations of this class do NOT make use of hardware acceleration.

See also

GenerateImageBuffer

ConvertImageBuffer

Constructor & Destructor Documentation

Image() [1/6]

LLGL::Image::Image ( )

default

Image() [2/6]

LLGL::Image::Image	(	const Extent3D &	extent,
		const ImageFormat	format,
		const DataType	dataType )

Constructor to initialize the image with a format, data type, and extent.

Note

The image buffer will be uninitialized!

See also

Fill

Image() [3/6]

LLGL::Image::Image	(	const Extent3D &	extent,
		const ImageFormat	format,
		const DataType	dataType,
		const ColorRGBAf &	fillColor )

Constructor to initialize the image with a format, data type, and extent. The image buffer will be filled with the specified color.

See also

GenerateImageBuffer

Image() [4/6]

LLGL::Image::Image	(	const Extent3D &	extent,
		const ImageFormat	format,
		const DataType	dataType,
		DynamicByteArray &&	data )

Constructor to initialize the image with all attributes, including the image buffer specified by the 'data' parameter.

Note

If the specified data does not manage an image buffer of the specified extent and format, the behavior is undefined.

See also

Reset(const Extent3D&, const ImageFormat, const DataType, DynamicByteArray&&)

Image() [5/6]

LLGL::Image::Image

(

const Image &

rhs

)

Copy constructor which copies the entire image buffer from the specified source image.

Image() [6/6]

LLGL::Image::Image ( Image && rhs )

noexcept

Move constructor which takes the ownership of the specified source image.

Member Function Documentation

Blit()

void LLGL::Image::Blit	(	Offset3D	dstRegionOffset,
		const Image &	srcImage,
		Offset3D	srcRegionOffset,
		Extent3D	srcRegionExtent )

Copies a region of the specified source image into this image.

Parameters

[in]	dstRegionOffset	Specifies the offset within the destination image (i.e. this Image instance). This can also be outside of the image area.
[in]	srcImage	Specifies the source image whose region is to be copied. This must have the same format and data type as this image. If the source image is the same object as this image and the destination and source regions overlap, an internal temporary copy is allocated for reading the data.
[in]	srcRegionOffset	Specifies the offset within the source image. This will be clamped if it exceeds the source image area.
[in]	srcRegionExtent	Specifies the extent of the region to copy. This will be clamped if it exceeds the source or destination image area.

Remarks

If one of the region offsets is clamped, the region extent will be adjusted respectively. If the source image has a different format or data type compared to this image, the function has no effect.

See also

ConvertImageBuffer

Convert()

void LLGL::Image::Convert	(	const ImageFormat	format,
		const DataType	dataType,
		unsigned	threadCount = 0 )

Converts the image format and data type.

See also

ConvertImageBuffer

GetBytesPerPixel()

std::uint32_t LLGL::Image::GetBytesPerPixel

(

)

const

Returns the size (in bytes) for each pixel.

See also

GetFormat

GetDataType

GetMemoryFootprint

GetData() [1/2]

void * LLGL::Image::GetData ( )

inline

Returns the image data buffer as raw pointer.

GetData() [2/2]

const void * LLGL::Image::GetData ( ) const

inline

Returns the image data buffer as constant raw pointer.

GetDataSize()

std::uint32_t LLGL::Image::GetDataSize

(

)

const

Returns the size (in bytes) of the image buffer.

See also

GetBytesPerPixel

GetNumPixels

GetDataType()

DataType LLGL::Image::GetDataType ( ) const

inline

Returns the data type for each pixel component. By default DataType::UInt8.

GetDepthStride()

std::uint32_t LLGL::Image::GetDepthStride

(

)

const

Returns the stride (in bytes) for each depth slice.

GetExtent()

const Extent3D & LLGL::Image::GetExtent ( ) const

inline

Returns the extent of the image as 3D vector.

GetFormat()

ImageFormat LLGL::Image::GetFormat ( ) const

inline

Returns the format for each pixel. By default ImageFormat::RGBA.

GetMutableView()

MutableImageView LLGL::Image::GetMutableView

(

)

Returns a destination image descriptor for this image with read/write access to the image data.

GetNumPixels()

std::uint32_t LLGL::Image::GetNumPixels

(

)

const

Returns the number of pixels this image has.

Remarks

This is equivalent to the following code example:

const auto& extent = myImage.GetExtent();
return extent.width * extent.height * extent.depth;

See also

GetExtent

GetRowStride()

std::uint32_t LLGL::Image::GetRowStride

(

)

const

Returns the stride (in bytes) for each row.

GetView()

ImageView LLGL::Image::GetView

(

)

const

Returns a source image descriptor for this image with read-only access to the image data.

IsRegionInside()

bool LLGL::Image::IsRegionInside	(	const Offset3D &	offset,
		const Extent3D &	extent ) const

Returns true if the specified sub-image region is inside the image.

operator=() [1/2]

Image & LLGL::Image::operator=

(

const Image &

rhs

)

Copy operator which copies the entire image buffer and attributes.

operator=() [2/2]

Image & LLGL::Image::operator=

(

Image &&

rhs

)

Move operator which takes the ownership of the image buffer.

ReadPixels()

void LLGL::Image::ReadPixels	(	const Offset3D &	offset,
		const Extent3D &	extent,
		const MutableImageView &	imageView,
		unsigned	threadCount = 0 ) const

Reads a region of pixels from this image into the destination image buffer specified by imageView.

Parameters

[in]	offset	Specifies the region offset within this image to read from.
[in]	extent	Specifies the region extent within this image to read from.
[in]	imageView	Specifies the destination image view to write the region to. If the 'data' member of this descriptor is null or if the sub-image region is not inside the image, this function has no effect.
[in]	threadCount	Specifies the number of threads to use if the data needs to be converted (see ConvertImageBuffer for more details). By default 0.

Remarks

To read a single pixel, use the following code example:

LLGL::ColorRGBAub ReadSinglePixelRGBAub(const LLGL::Image& image, const LLGL::Offset3D& position) {
    LLGL::ColorRGBAub pixelColor;
    const MutableImageView imageView{ LLGL::ImageFormat::RGBA, LLGL::DataType::UInt8, &pixelColor, sizeof(pixelColor) };
    image.ReadPixels(position, { 1, 1, 1 }, imageView);
    return pixelColor;
}

Exceptions

std::invalid_argument

If the data member of the image descriptor is non-null, the sub-image region is inside the image, but the dataSize member of the image descriptor is too small.

See also

IsRegionInside

ConvertImageBuffer

Release()

DynamicByteArray LLGL::Image::Release

(

)

Releases the ownership of the image buffer and resets all attributes.

Reset() [1/2]

void LLGL::Image::Reset

(

)

Resets all image attributes to its default values.

Reset() [2/2]

void LLGL::Image::Reset	(	const Extent3D &	extent,
		const ImageFormat	format,
		const DataType	dataType,
		DynamicByteArray &&	data )

Resets all image attributes to the specified values.

Note

If the specified data does not manage an image buffer of the specified extent and format, the behavior is undefined.

See also

GenerateImageBuffer

Resize() [1/3]

void LLGL::Image::Resize

(

const Extent3D &

extent

)

Resizes the image and resets the image buffer.

Parameters

[in]

extent

Specifies the new image size.

Note

The new image buffer will be uninitialized!

Resize() [2/3]

void LLGL::Image::Resize	(	const Extent3D &	extent,
		const ColorRGBAf &	fillColor )

Resizes the image and initializes the new pixels with the specified color.

Parameters

[in]	extent	Specifies the new image size.
[in]	fillColor	Specifies the color to fill the pixels with.

See also

GenerateImageBuffer

Resize() [3/3]

void LLGL::Image::Resize	(	const Extent3D &	extent,
		const ColorRGBAf &	fillColor,
		const Offset3D &	offset )

Resizes the image, moves the previous pixels by an offset, and initializes the new pixels outside the previous extent with the specified color.

Parameters

[in]	extent	Specifies the new image size.
[in]	fillColor	Specifies the color to fill the pixels with that are outside the previous extent.
[in]	offset	Specifies the offset to move the previous pixels to. This will be clamped if it exceeds the image area.

See also

GenerateImageBuffer

Swap()

void LLGL::Image::Swap

(

Image &

rhs

)

Swaps all attributes with the specified image.

WritePixels()

void LLGL::Image::WritePixels	(	const Offset3D &	offset,
		const Extent3D &	extent,
		const ImageView &	imageView,
		unsigned	threadCount = 0 )

Writes a region of pixels to this image from the source image buffer specified by imageView.

Parameters

[in]	offset	Specifies the region offset within this image to write to.
[in]	extent	Specifies the region extent within this image to write to.
[in]	imageView	Specifies the source image view to read the region from. If the data member of this descriptor is null or if the sub-image region is not inside the image, this function has no effect.
[in]	threadCount	Specifies the number of threads to use if the data needs to be converted (see ConvertImageBuffer for more details). By default 0.

See also

IsRegionInside

ConvertImageBuffer

---

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

• Image.h