template<UnsignedInt dimensions>
Magnum::CompressedImageView class

Compressed image view.

Contents

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

Usually, the view is created on some pre-existing data array in order to describe its layout, with pixel format being one of the values from the generic CompressedPixelFormat:

CompressedImageView2D image{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 image{
    CompressedPixelStorage{}
        .setRowLength(64)
        .setCompressedBlockSize({4, 4, 1})
        .setCompressedBlockDataSize(8)
        .setSkip({32, 32, 0}),
    CompressedPixelFormat::Bc1RGBUnorm, {32, 32}, data};

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 image{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>(image.format());

Public types

enum (anonymous): UnsignedInt { Dimensions = dimensions }

Constructors, destructors, conversion operators

CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data) explicit noexcept
Constructor.
CompressedImageView(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data) explicit noexcept
Constructor.
CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size) explicit noexcept
Construct an empty view.
CompressedImageView(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size) explicit noexcept
Construct an empty view.
template<class T>
CompressedImageView(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data) explicit noexcept
Construct an image view with implementation-specific format.
template<class T>
CompressedImageView(T format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data) explicit noexcept
Construct an image view with implementation-specific format.
template<class T>
CompressedImageView(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size) explicit noexcept
Construct an empty view with implementation-specific format.
template<class T>
CompressedImageView(T format, const VectorTypeFor<dimensions, Int>& size) explicit noexcept
Construct an empty view with implementation-specific format.

Public functions

auto storage() const -> CompressedPixelStorage
Storage of compressed pixel data.
auto format() const -> CompressedPixelFormat
Format of compressed pixel data.
auto size() const -> VectorTypeFor<dimensions, Int> constexpr
Image size.
auto dataProperties() const -> std::pair<VectorTypeFor<dimensions, std::size_t>, VectorTypeFor<dimensions, std::size_t>>
Compressed image data properties.
auto data() const -> Containers::ArrayView<const char>
Image data.
template<class T>
auto data() const -> const T*
void setData(Containers::ArrayView<const void> data)
Set image data.

Enum documentation

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

Enumerators
Dimensions

Image dimension count

Function documentation

template<UnsignedInt dimensions>
Magnum::CompressedImageView<dimensions>::CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data) explicit noexcept

Constructor.

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

template<UnsignedInt dimensions>
Magnum::CompressedImageView<dimensions>::CompressedImageView(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data) explicit noexcept

Constructor.

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

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

template<UnsignedInt dimensions>
Magnum::CompressedImageView<dimensions>::CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size) explicit noexcept

Construct an empty view.

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

Data pointer is set to nullptr, call setData() to assign a memory view to the image.

template<UnsignedInt dimensions>
Magnum::CompressedImageView<dimensions>::CompressedImageView(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size) explicit noexcept

Construct an empty view.

Parameters
format Format of compressed pixel data
size Image size

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

template<UnsignedInt dimensions> template<class T>
Magnum::CompressedImageView<dimensions>::CompressedImageView(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data) 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

Uses compressedPixelFormatWrap() internally to convert format to CompressedPixelFormat.

template<UnsignedInt dimensions> template<class T>
Magnum::CompressedImageView<dimensions>::CompressedImageView(T format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data) explicit noexcept

Construct an image view with implementation-specific format.

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

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

template<UnsignedInt dimensions> template<class T>
Magnum::CompressedImageView<dimensions>::CompressedImageView(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size) 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

Uses compressedPixelFormatWrap() internally to convert format to CompressedPixelFormat. Data pointer is set to nullptr, call setData() to assign a memory view to the image.

template<UnsignedInt dimensions> template<class T>
Magnum::CompressedImageView<dimensions>::CompressedImageView(T format, const VectorTypeFor<dimensions, Int>& size) explicit noexcept

Construct an empty view with implementation-specific format.

Parameters
format Format of compressed pixel data
size Image size

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

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

Compressed image data properties.

See CompressedPixelStorage::dataProperties() for more information.

template<UnsignedInt dimensions> template<class T>
const T* Magnum::CompressedImageView<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>
void Magnum::CompressedImageView<dimensions>::setData(Containers::ArrayView<const void> data)

Set image data.

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