Image utility functions to classify and convert image data.

Functions
LLGL_EXPORT std::size_t	LLGL::ConvertImageBuffer (const ImageView &srcImageView, const MutableImageView &dstImageView, const Extent3D &extent, unsigned threadCount=0, bool copyUnchangedImage=false, std::uint32_t depthMask=~0u, std::uint32_t stencilMask=~0u)
	Converts the image format and data type of the source image (only uncompressed color formats).
LLGL_EXPORT std::size_t	LLGL::ConvertImageBuffer (const ImageView &srcImageView, const MutableImageView &dstImageView, unsigned threadCount=0, bool copyUnchangedImage=false)
	Converts the image format and data type of the source image (only uncompressed color formats).
LLGL_EXPORT DynamicByteArray	LLGL::ConvertImageBuffer (const ImageView &srcImageView, ImageFormat dstFormat, DataType dstDataType, const Extent3D &extent, unsigned threadCount=0)
	Converts the image format and data type of the source image (only uncompressed color formats) and returns the new generated image buffer.
LLGL_EXPORT DynamicByteArray	LLGL::ConvertImageBuffer (const ImageView &srcImageView, ImageFormat dstFormat, DataType dstDataType, unsigned threadCount=0)
	Converts the image format and data type of the source image (only uncompressed color formats) and returns the new generated image buffer.
LLGL_EXPORT DynamicByteArray	LLGL::DecompressImageBufferToRGBA8UNorm (Format compressedFormat, const ImageView &srcImageView, const Extent2D &extent, unsigned threadCount=0)
	Decompresses the specified image buffer to RGBA format with 8-bit unsigned normalized integers.
LLGL_EXPORT void	LLGL::CopyImageBufferRegion (const MutableImageView &dstImageView, const Offset3D &dstOffset, std::uint32_t dstRowStride, std::uint32_t dstLayerStride, const ImageView &srcImageView, const Offset3D &srcOffset, std::uint32_t srcRowStride, std::uint32_t srcLayerStride, const Extent3D &extent)
	Copies an image buffer region from the source buffer to the destination buffer.
LLGL_EXPORT DynamicByteArray	LLGL::GenerateImageBuffer (ImageFormat format, DataType dataType, std::size_t imageSize, const float fillColor[4])
	Generates an image buffer with the specified fill data for each pixel.

Detailed Description

Function Documentation

ConvertImageBuffer() [1/4]

LLGL_EXPORT std::size_t LLGL::ConvertImageBuffer	(	const ImageView &	srcImageView,
		const MutableImageView &	dstImageView,
		const Extent3D &	extent,
		unsigned	threadCount = 0,
		bool	copyUnchangedImage = false,
		std::uint32_t	depthMask = ~0u,
		std::uint32_t	stencilMask = ~0u )

Converts the image format and data type of the source image (only uncompressed color formats).

Parameters

[in]	srcImageView	Specifies the source image view.
[out]	dstImageView	Specifies the destination image view.
[in]	extent	Specifies the extent of the image. This is required.
[in]	threadCount	Specifies the number of threads to use for conversion. If this is less than 2, no multi-threading is used. If this is equal to LLGL_MAX_THREAD_COUNT, the number of threads will be determined by the workload and the available CPU cores the system supports (e.g. 4 on a quad-core processor). Note that this does not guarantee the maximum number of threads the system supports if the workload does not demand it. By default 0.
[in]	copyUnchangedImage	Specifies whether to copy the source buffer into the destination buffer if no conversion was necessary. By default false.
[in]	depthMask	Specifies a bitmask for the depth components. This determines what depth bits will be overridden in the destination buffer. By default 0xFFFFFFFF.
[in]	stencilMask	Specifies a bitmask for the stencil components. This determines what stencil bits will be overridden in the destination buffer. By default 0xFFFFFFFF.

Returns

Number of bytes that have been written to the destination buffer. If this is 0, no conversion was necessary and the destination buffer is not modified.

Note

Compressed images and depth-stencil images cannot be converted with this function.

Exceptions

std::invalid_argument	If a compressed image format is specified either as source or destination.
std::invalid_argument	If a depth-stencil format is specified either as source or destination.
std::invalid_argument	If the source buffer size is not a multiple of the source data type size times the image format size.
std::invalid_argument	If the source buffer is a null pointer.
std::invalid_argument	If the destination buffer size does not match the required output buffer size.
std::invalid_argument	If the destination buffer is a null pointer.

See also

LLGL_MAX_THREAD_COUNT

GetMemoryFootprint

ConvertImageBuffer() [2/4]

LLGL_EXPORT std::size_t LLGL::ConvertImageBuffer	(	const ImageView &	srcImageView,
		const MutableImageView &	dstImageView,
		unsigned	threadCount = 0,
		bool	copyUnchangedImage = false )

Converts the image format and data type of the source image (only uncompressed color formats).

Remarks

Same as the primary version of ConvertImageBuffer where the extent parameter is implied as 1-dimensional size. This must only be used for tightly packed image buffer, i.e. with a row stride of zero.

See also

ConvertImageBuffer(const ImageView&, const MutableImageView&, const Extent3D&, unsigned, bool)

ConvertImageBuffer() [3/4]

LLGL_EXPORT DynamicByteArray LLGL::ConvertImageBuffer	(	const ImageView &	srcImageView,
		ImageFormat	dstFormat,
		DataType	dstDataType,
		const Extent3D &	extent,
		unsigned	threadCount = 0 )

Converts the image format and data type of the source image (only uncompressed color formats) and returns the new generated image buffer.

Parameters

[in]	srcImageView	Specifies the source image view.
[in]	dstFormat	Specifies the destination image format.
[in]	dstDataType	Specifies the destination image data type.
[in]	extent	Specifies the extent of the image. This is required.
[in]	threadCount	Specifies the number of threads to use for conversion. If this is less than 2, no multi-threading is used. If this is equal to LLGL_MAX_THREAD_COUNT, the number of threads will be determined by the workload and the available CPU cores the system supports (e.g. 4 on a quad-core processor). Note that this does not guarantee the maximum number of threads the system supports if the workload does not demand it. By default 0.

Returns

Byte buffer with the converted image data or null if no conversion is necessary. This can be casted to the respective target data type (e.g. unsigned char, int, float etc.).

Note

Compressed images and depth-stencil images cannot be converted.

Exceptions

std::invalid_argument	If a compressed image format is specified either as source or destination.
std::invalid_argument	If a depth-stencil format is specified either as source or destination.
std::invalid_argument	If the source buffer size is not a multiple of the source data type size times the image format size.
std::invalid_argument	If the source buffer is a null pointer.

See also

LLGL_MAX_THREAD_COUNT

GetMemoryFootprint

ConvertImageBuffer() [4/4]

LLGL_EXPORT DynamicByteArray LLGL::ConvertImageBuffer	(	const ImageView &	srcImageView,
		ImageFormat	dstFormat,
		DataType	dstDataType,
		unsigned	threadCount = 0 )

Converts the image format and data type of the source image (only uncompressed color formats) and returns the new generated image buffer.

Remarks

Same as the primary version of ConvertImageBuffer where the extent parameter is implied as 1-dimensional size. This must only be used for tightly packed image buffer, i.e. with a row stride of zero.

See also

ConvertImageBuffer(const ImageView&, ImageFormat, DataType, const Extent3D&, unsigned)

CopyImageBufferRegion()

LLGL_EXPORT void LLGL::CopyImageBufferRegion	(	const MutableImageView &	dstImageView,
		const Offset3D &	dstOffset,
		std::uint32_t	dstRowStride,
		std::uint32_t	dstLayerStride,
		const ImageView &	srcImageView,
		const Offset3D &	srcOffset,
		std::uint32_t	srcRowStride,
		std::uint32_t	srcLayerStride,
		const Extent3D &	extent )

Copies an image buffer region from the source buffer to the destination buffer.

Parameters

[out]	dstImageView	Specifies the destination image view.
[in]	dstOffset	Specifies the 3D offset of the destination image.
[in]	dstRowStride	Specifies the number of pixels for each row in the destination image.
[in]	dstLayerStride	Specifies the number of pixels for each slice in the destination image.
[in]	srcImageView	Specifies the source image view.
[in]	srcOffset	Specifies the 3D offset of the source image.
[in]	srcRowStride	Specifies the number of pixels for each row in the source image.
[in]	srcLayerStride	Specifies the number of pixels for each slice in the source image.
[in]	extent	Specifies the region extent to be copied.

Remarks

Only performs a bitwise copy. No blending or other operation is performed.

Exceptions

std::invalid_argument	If the destination buffer is a null pointer.
std::invalid_argument	If the destination buffer size does not match the required output buffer size.
std::invalid_argument	If the source buffer is a null pointer.
std::invalid_argument	If the source buffer size is not a multiple of the source data type size times the image format size.
std::invalid_argument	If source and destination image descriptors do not have the same format and data type.
std::out_of_range	If srcOffset plus extent is outside the boundary of the source image.
std::out_of_range	If dstOffset plus extent is outside the boundary of the destination image.

DecompressImageBufferToRGBA8UNorm()

LLGL_EXPORT DynamicByteArray LLGL::DecompressImageBufferToRGBA8UNorm	(	Format	compressedFormat,
		const ImageView &	srcImageView,
		const Extent2D &	extent,
		unsigned	threadCount = 0 )

Decompresses the specified image buffer to RGBA format with 8-bit unsigned normalized integers.

Parameters

[in]	compressedFormat	Specifies the compressed hardware format that is meant to be decompressed.
[in]	srcImageView	Specifies the source image image.
[in]	extent	Specifies the image extent. This is required as most compression formats work in block sizes.
[in]	threadCount	Specifies the number of threads to use for decompression. If this is less than 2, no multi-threading is used. If this is equal to LLGL_MAX_THREAD_COUNT, the number of threads will be determined by the workload and the available CPU cores the system supports (e.g. 4 on a quad-core processor). Note that this does not guarantee the maximum number of threads the system supports if the workload does not demand it. By default 0.

Returns

Byte buffer with the decompressed image data or null if the compression format is not supported for decompression.

GenerateImageBuffer()

LLGL_EXPORT DynamicByteArray LLGL::GenerateImageBuffer	(	ImageFormat	format,
		DataType	dataType,
		std::size_t	imageSize,
		const float	fillColor[4] )

Generates an image buffer with the specified fill data for each pixel.

Parameters

[in]	format	Specifies the image format of each pixel in the output image.
[in]	dataType	Specifies the data type of each component of each pixel in the output image.
[in]	imageSize	Specifies the 1-Dimensional size (in pixels) of the output image. For a 2D image, this can be width times height for instance.
[in]	fillColor	Specifies the color to fill the image for each pixel.

Returns

The new allocated and initialized byte buffer.

Remarks

This can be used to generate a single-colored n-Dimensional image. Usage example for a 2D image:

// Generate 2D image of size 512 x 512 with a half-transparent yellow color
const float fillColor[4] = { 1.0f, 1.0f, 0.0f, 0.5f };
auto imageBuffer = LLGL::GenerateImageBuffer(
    LLGL::ImageFormat::RGBA,
    LLGL::DataType::UInt8,
    512 * 512,
    fillColor
);