#include <Magnum/Image.h>
template<UnsignedInt dimensions>
Magnum::CompressedImage class

Compressed image.

Stores multi-dimensional compressed image data together with layout and compressed block format description. See CompressedImageView for a non-owning alternative.

This class can act as a drop-in replacement for CompressedImageView and Trade::ImageData APIs and is implicitly convertible to CompressedImageView. Particular graphics API wrappers provide additional image classes, for example GL::CompressedBufferImage. See also Image for equivalent functionality targeted on non-compressed image formats.

Basic usage

The image takes ownership of a passed Containers::Array, together with a CompressedPixelFormat and size in pixels:

CompressedImage2D image{CompressedPixelFormat::Bc1RGBUnorm,
    {512, 256}, Containers::Array<char>{ValueInit, …}};

It's also possible to create just an image placeholder, storing only the image properties without data or size. That is useful for example to specify desired format of image queries in graphics APIs:

GL::Texture2D texture;
CompressedImage2D image = texture.compressedImage(0, CompressedImage2D{});

As with CompressedImageView, this class supports extra storage parameters and implementation-specific compressed pixel format specification. See its documentation for more information.

Public types

enum (anonymous): UnsignedInt { Dimensions = dimensions }

Constructors, destructors, conversion operators

CompressedImage(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept
Constructor.
CompressedImage(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept
Constructor.
CompressedImage(CompressedPixelStorage storage, UnsignedInt format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept new in Git master
Construct a compressed image with an implementation-specific pixel format.
CompressedImage(CompressedPixelStorage storage, CompressedPixelFormat format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept new in Git master
template<class T>
CompressedImage(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept
Construct a compressed image with implementation-specific format.
template<class T>
CompressedImage(T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept
Construct a compressed image with implementation-specific format.
CompressedImage(CompressedPixelStorage storage) noexcept
Construct an image placeholder.
CompressedImage() noexcept
Construct an image placeholder.
CompressedImage(const CompressedImage<dimensions>&) deleted
Copying is not allowed.
CompressedImage(CompressedImage<dimensions>&& other) noexcept
Move constructor.
operator BasicCompressedImageView<dimensions>() const
Conversion to a view.
operator BasicMutableCompressedImageView<dimensions>() new in 2019.10
Conversion to a mutable view.

Public functions

auto operator=(const CompressedImage<dimensions>&) -> CompressedImage<dimensions>& deleted
Copying is not allowed.
auto operator=(CompressedImage<dimensions>&& other) -> CompressedImage<dimensions>& noexcept
Move assignment.
auto flags() const -> ImageFlags<dimensions> new in Git master
Layout flags.
auto data() & -> Containers::ArrayView<char>
Raw image data.
auto data() const & -> Containers::ArrayView<const char>
auto data() && -> Containers::Array<char> new in 2019.10
Raw image data from a r-value.
auto data() const && -> Containers::Array<char> deleted new in 2019.10
auto storage() const -> CompressedPixelStorage
Storage of compressed pixel data.
auto format() const -> CompressedPixelFormat
Format of compressed pixel data.
auto blockSize() const -> Vector3i new in Git master
Size of a compressed block in pixels.
auto blockDataSize() const -> UnsignedInt new in Git master
Size of a compressed block in bytes.
auto size() const -> const VectorTypeFor<dimensions, Int>&
Image size in pixels.
auto dataProperties() const -> std::pair<VectorTypeFor<dimensions, std::size_t>, VectorTypeFor<dimensions, std::size_t>>
Compressed image data properties.
auto release() -> Containers::Array<char>
Release data storage.

Enum documentation

template<UnsignedInt dimensions>
enum Magnum::CompressedImage<dimensions>::(anonymous): UnsignedInt

Enumerators
Dimensions

Image dimension count

Function documentation

template<UnsignedInt dimensions>
Magnum::CompressedImage<dimensions>::CompressedImage(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept

Constructor.

Parameters
storage Storage of compressed pixel data
format Format of compressed pixel data
size Image size
data Image data
flags Image layout flags

The data array is expected to be of proper size for given parameters. For a 3D image, if flags contain ImageFlag3D::CubeMap, the size is expected to match its restrictions.

The format is expected to not be implementation-specific, use the CompressedImage(CompressedPixelStorage, CompressedPixelFormat, const Vector3i&, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>) overload to explicitly pass pass an implementation-specific CompressedPixelFormat along with its block properties, or the CompressedImage(CompressedPixelStorage, T, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>) overload with the original implementation-specific enum type to have the pixel size determined implicitly.

CompressedPixelStorage::compressedBlockSize() and compressedBlockDataSize() in storage are expected to be either both zero or exactly matching properties of given format.

template<UnsignedInt dimensions>
Magnum::CompressedImage<dimensions>::CompressedImage(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept

Constructor.

Parameters
format Format of compressed pixel data
size Image size
data Image data
flags Image layout flags

Equivalent to calling CompressedImage(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>) with default-constructed CompressedPixelStorage.

template<UnsignedInt dimensions>
Magnum::CompressedImage<dimensions>::CompressedImage(CompressedPixelStorage storage, UnsignedInt format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept new in Git master

Construct a compressed image with an implementation-specific pixel format.

Parameters
storage Storage of compressed pixel data
format Format of compressed pixel data
blockSize Size of a compressed block in given format, in pixels
blockDataSize Size of a compressed block in given format, in bytes
size Image size, in pixels
data Image data
flags Image layout flags

Unlike with CompressedImage(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>), where block size is determined automatically compressedPixelFormatBlockSize() and compressedPixelFormatBlockDataSize(), this allows you to specify an implementation-specific pixel format and block properties directly. Uses compressedPixelFormatWrap() internally to wrap format in CompressedPixelFormat. The blockSize and blockDataSize is expected to be greater than 0 and less than 256. Note that the blocks can be 3D even for 2D images and 2D or 3D even for 1D images, in which case only the first slice in the extra dimensions is used.

CompressedPixelStorage::compressedBlockSize() and compressedBlockDataSize() in storage are expected to be either both zero or exactly matching blockSize and blockDataSize.

The data array is expected to be of proper size for given parameters. For a 3D image, if flags contain ImageFlag3D::CubeMap, the size is expected to match its restrictions.

template<UnsignedInt dimensions>
Magnum::CompressedImage<dimensions>::CompressedImage(CompressedPixelStorage storage, CompressedPixelFormat format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept new in Git master

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Equivalent to the above for format already wrapped with compressedPixelFormatWrap().

template<UnsignedInt dimensions> template<class T>
Magnum::CompressedImage<dimensions>::CompressedImage(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept

Construct a compressed image with implementation-specific format.

Parameters
storage Storage of compressed pixel data
format Format of compressed pixel data
size Image size
data Image data
flags Image layout flags

Uses ADL to find a corresponding compressedPixelFormatBlockSize(T) and compressedPixelFormatBlockDataSize(T) overloads, then calls CompressedImage(CompressedPixelStorage, UnsignedInt, const Vector3i&, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>) with determined block size properties.

template<UnsignedInt dimensions> template<class T>
Magnum::CompressedImage<dimensions>::CompressedImage(T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}) explicit noexcept

Construct a compressed image with implementation-specific format.

Parameters
format Format of compressed pixel data
size Image size
data Image data
flags Image layout flags

Equivalent to calling CompressedImage(CompressedPixelStorage, T, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>) with default-constructed CompressedPixelStorage.

template<UnsignedInt dimensions>
Magnum::CompressedImage<dimensions>::CompressedImage(CompressedPixelStorage storage) noexcept

Construct an image placeholder.

Parameters
storage Storage of compressed pixel data

Format and block properties are undefined, size is zero, data is nullptr and data layout flags are empty. Move over a non-empty instance to make it useful.

CompressedPixelStorage::compressedBlockSize() and compressedBlockDataSize() in storage are expected to be both zero.

template<UnsignedInt dimensions>
Magnum::CompressedImage<dimensions>::CompressedImage() noexcept

Construct an image placeholder.

Equivalent to calling CompressedImage(CompressedPixelStorage) with default-constructed CompressedPixelStorage.

template<UnsignedInt dimensions>
Containers::ArrayView<char> Magnum::CompressedImage<dimensions>::data() &

Raw image data.

template<UnsignedInt dimensions>
Containers::ArrayView<const char> Magnum::CompressedImage<dimensions>::data() const &

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions>
Containers::Array<char> Magnum::CompressedImage<dimensions>::data() && new in 2019.10

Raw image data from a r-value.

Unlike data(), which returns a view, this is equivalent to release() to avoid a dangling view when the temporary instance goes out of scope.

template<UnsignedInt dimensions>
Containers::Array<char> Magnum::CompressedImage<dimensions>::data() const && deleted new in 2019.10

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions>
CompressedPixelFormat Magnum::CompressedImage<dimensions>::format() const

Format of compressed pixel data.

Returns either a defined value from the CompressedPixelFormat enum or a wrapped implementation-specific value. Use isCompressedPixelFormatImplementationSpecific() to distinguish the case and compressedPixelFormatUnwrap() to extract an implementation-specific value, if needed.

template<UnsignedInt dimensions>
Vector3i Magnum::CompressedImage<dimensions>::blockSize() const new in Git master

Size of a compressed block in pixels.

Note that the blocks can be 3D even for 2D images and 2D or 3D even for 1D images, in which case only the first slice in the extra dimensions is used.

template<UnsignedInt dimensions>
UnsignedInt Magnum::CompressedImage<dimensions>::blockDataSize() const new in Git master

Size of a compressed block in bytes.

template<UnsignedInt dimensions>
const VectorTypeFor<dimensions, Int>& Magnum::CompressedImage<dimensions>::size() const

Image size in pixels.

If the size isn't divisible by blockSize(), the edge blocks are still present in full but used only partially.

template<UnsignedInt dimensions>
std::pair<VectorTypeFor<dimensions, std::size_t>, VectorTypeFor<dimensions, std::size_t>> Magnum::CompressedImage<dimensions>::dataProperties() const

Compressed image data properties.

See CompressedPixelStorage::dataProperties() for more information.

template<UnsignedInt dimensions>
Containers::Array<char> Magnum::CompressedImage<dimensions>::release()

Release data storage.

Releases the ownership of the data array and resets size() to zero. The state afterwards is equivalent to moved-from state.