#include <Magnum/ImageView.h>
template<UnsignedInt dimensions, class T>
Magnum::CompressedImageView class

Compressed image view.

Non-owning view on multi-dimensional compressed image data together with layout and compressed block format description. Unlike CompressedImage, this class doesn't take ownership of the data, so it is targeted for wrapping data that is either stored in stack/constant memory (and shouldn't be deleted) or is managed by something else.

This class can act as drop-in replacement for CompressedImage or Trade::ImageData, these two are additionally implicitly convertible to it. Particular graphics API wrappers provide additional image classes, for example GL::CompressedBufferImage. See also ImageView for equivalent functionality targeted on non-compressed image formats.

Basic usage

The view is created from a CompressedPixelFormat, size in pixels and a data view:

CompressedImageView2D view{CompressedPixelFormat::Bc1RGBUnorm,
    {512, 256}, data};

It's also possible to create an empty view and assign the memory later. That is useful for example in case of multi-buffered video streaming, where each frame has the same properties but a different memory location:

CompressedImageView2D frame{CompressedPixelFormat::Bc1RGBUnorm, {512, 256}};

frame.setData(evenFrameData);
// Use even frame data ...

frame.setData(oddFrameData);
// Use odd frame data ...

It's possible to have views on image sub-rectangles, 3D texture slices or images with over-aligned rows by passing a particular CompressedPixelStorage as first parameter. In the following snippet, the view is the bottom-right 32x32 sub-rectangle of a 64x64 image:

CompressedImageView2D view{
    CompressedPixelStorage{}
        .setRowLength(64)
        .setCompressedBlockSize({4, 4, 1})
        .setCompressedBlockDataSize(8)
        .setSkip({32, 32, 0}),
    CompressedPixelFormat::Bc1RGBUnorm, {32, 32}, data};

Data mutability

When using types derived from BasicCompressedImageView (e.g. CompressedImageView2D), the viewed data are immutable. This is the most common use case. In order to be able to mutate the underlying data (for example in order to read into a pre-allocated memory), use BasicMutableCompressedImageView (e.g. MutableCompressedImageView2D) instead. CompressedImage and Trade::ImageData are convertible to either of these. Similarly to Corrade::Containers::ArrayView etc., a mutable view is also implicitly convertible to a const one.

Implementation-specific formats

For known graphics APIs, there's a set of utility functions converting from CompressedPixelFormat to implementation-specific format identifiers and such conversion is done implicitly when passing the view to a particular API. See the enum documentation and documentation of its values for more information.

In some cases, for example when there's no corresponding generic format available, it's desirable to specify the pixel format using implementation-specific identifiers directly. In case of OpenGL that would be GL::CompressedPixelFormat:

CompressedImageView2D view{GL::CompressedPixelFormat::SignedRGRgtc2,
    {512, 256}, data};

In such cases, the implementation-specific format is wrapped in CompressedPixelFormat using compressedPixelFormatWrap() and format() returns the wrapped value. In order to distinguish if the format is wrapped, use isCompressedPixelFormatImplementationSpecific() and then extract the implementation-specific identifier using compressedPixelFormatUnwrap():

auto format = compressedPixelFormatUnwrap<GLenum>(view.format());

Public types

enum (anonymous): UnsignedInt { Dimensions = dimensions }
using Type = T
Raw data type.
using ErasedType = std::conditional<std::is_const<T>::value, const void, void>::type
Erased data type.

Constructors, destructors, conversion operators

CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept
Constructor.
CompressedImageView(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept
Constructor.
CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view.
CompressedImageView(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view.
CompressedImageView(CompressedPixelStorage storage, UnsignedInt format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept new in Git master
Construct a view with an implementation-specific pixel format.
CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept
CompressedImageView(CompressedPixelStorage storage, UnsignedInt format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept new in Git master
Construct an empty view with an implementation-specific pixel format.
CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept new in Git master
template<class U>
CompressedImageView(CompressedPixelStorage storage, U format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an image view with implementation-specific format.
template<class U>
CompressedImageView(U format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an image view with implementation-specific format.
template<class U>
CompressedImageView(CompressedPixelStorage storage, U format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view with implementation-specific format.
template<class U>
CompressedImageView(U format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view with implementation-specific format.
template<UnsignedInt otherDimensions>
CompressedImageView(const CompressedImageView<otherDimensions, T>& other, ImageFlags<dimensions> flags = {}) noexcept new in 2019.10
Construct from a view of lower dimension count.
template<class U>
CompressedImageView(const CompressedImageView<dimensions, U>& other) noexcept new in 2019.10
Convert a mutable view to a const one.

Public functions

auto flags() const -> ImageFlags<dimensions> new in Git master
Layout flags.
auto data() const -> Containers::ArrayView<Type>
Raw image data.
void setData(Containers::ArrayView<ErasedType> data)
Set image data.
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.

Enum documentation

template<UnsignedInt dimensions, class T>
enum Magnum::CompressedImageView<dimensions, T>::(anonymous): UnsignedInt

Enumerators
Dimensions

Image dimension count

Typedef documentation

template<UnsignedInt dimensions, class T>
typedef T Magnum::CompressedImageView<dimensions, T>::Type

Raw data type.

const char for CompressedImageView1D / CompressedImageView2D / CompressedImageView3D and char for MutableCompressedImageView1D / MutableCompressedImageView2D / MutableCompressedImageView3D. See also ErasedType.

template<UnsignedInt dimensions, class T>
typedef std::conditional<std::is_const<T>::value, const void, void>::type Magnum::CompressedImageView<dimensions, T>::ErasedType

Erased data type.

const void for CompressedImageView1D / CompressedImageView2D / CompressedImageView3D and const void for MutableCompressedImageView1D / MutableCompressedImageView2D / MutableCompressedImageView3D. See also Type.

Function documentation

template<UnsignedInt dimensions, class T>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> 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 CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const Vector3i&, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<ErasedType>, ImageFlags<dimensions>) overload to explicitly pass pass an implementation-specific CompressedPixelFormat along with its block properties, or the CompressedImageView(CompressedPixelStorage, U, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<ErasedType>, 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, class T>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> 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 CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<ErasedType>, ImageFlags<dimensions>) with default-constructed CompressedPixelStorage.

template<UnsignedInt dimensions, class T>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept

Construct an empty view.

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

Data pointer is set to nullptr, call setData() to assign a memory view to the image. 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 CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const Vector3i&, UnsignedInt, const VectorTypeFor<dimensions, Int>&, ImageFlags<dimensions>) overload to explicitly pass pass an implementation-specific CompressedPixelFormat along with its block properties, or the CompressedImageView(CompressedPixelStorage, U, const VectorTypeFor<dimensions, Int>&, 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, class T>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept

Construct an empty view.

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

Equivalent to calling CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, ImageFlags<dimensions>) with default-constructed CompressedPixelStorage.

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

Construct a view 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 CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<ErasedType>, 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, class T>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept

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, class T>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(CompressedPixelStorage storage, UnsignedInt format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept new in Git master

Construct an empty view 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
flags Image layout flags

Unlike with CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, 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 that 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.

Data pointer is set to nullptr, call setData() to assign a memory view to the image. For a 3D image, if flags contain ImageFlag3D::CubeMap, the size is expected to match its restrictions.

template<UnsignedInt dimensions, class T>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const Vector3i& blockSize, UnsignedInt blockDataSize, const VectorTypeFor<dimensions, Int>& size, 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, class T> template<class U>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(CompressedPixelStorage storage, U format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept

Construct an image view 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(U) and compressedPixelFormatBlockDataSize(U) overloads, then calls CompressedImageView(CompressedPixelStorage, UnsignedInt, const Vector3i&, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<ErasedType>, ImageFlags<dimensions>) with determined block size properties.

template<UnsignedInt dimensions, class T> template<class U>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(U format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept

Construct an image view with implementation-specific format.

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

Equivalent to calling CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<ErasedType>, ImageFlags<dimensions>) with default-constructed CompressedPixelStorage.

template<UnsignedInt dimensions, class T> template<class U>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(CompressedPixelStorage storage, U format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept

Construct an empty view with implementation-specific format.

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

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

template<UnsignedInt dimensions, class T> template<class U>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(U format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept

Construct an empty view with implementation-specific format.

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

Equivalent to calling CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, ImageFlags<dimensions>) with default-constructed CompressedPixelStorage.

template<UnsignedInt dimensions, class T> template<UnsignedInt otherDimensions>
Magnum::CompressedImageView<dimensions, T>::CompressedImageView(const CompressedImageView<otherDimensions, T>& other, ImageFlags<dimensions> flags = {}) noexcept new in 2019.10

Construct from a view of lower dimension count.

Size in the new dimension(s) is set to 1. Original image flags are preserved, except for ImageFlag2D::Array when constructing a 3D image from a 2D image (i.e., a 1D array image), as there's no concept of 2D arrays of 1D images. Use the flags parameter to add arbitrary other flags.

template<UnsignedInt dimensions, class T>
Containers::ArrayView<Type> Magnum::CompressedImageView<dimensions, T>::data() const

Raw image data.

template<UnsignedInt dimensions, class T>
void Magnum::CompressedImageView<dimensions, T>::setData(Containers::ArrayView<ErasedType> data)

Set image data.

The data array is expected to be of proper size for parameters specified in the constructor.

template<UnsignedInt dimensions, class T>
CompressedPixelFormat Magnum::CompressedImageView<dimensions, T>::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, class T>
Vector3i Magnum::CompressedImageView<dimensions, T>::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, class T>
UnsignedInt Magnum::CompressedImageView<dimensions, T>::blockDataSize() const new in Git master

Size of a compressed block in bytes.

template<UnsignedInt dimensions, class T>
const VectorTypeFor<dimensions, Int>& Magnum::CompressedImageView<dimensions, T>::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, class T>
std::pair<VectorTypeFor<dimensions, std::size_t>, VectorTypeFor<dimensions, std::size_t>> Magnum::CompressedImageView<dimensions, T>::dataProperties() const

Compressed image data properties.

See CompressedPixelStorage::dataProperties() for more information.