#include <Magnum/GL/BufferImage.h>
template<UnsignedInt dimensions>
Magnum::GL::CompressedBufferImage class

Compressed buffer image.

Stores multi-dimensional compressed image data in GPU memory together with layout and compressed block description. See CompressedImage for the client memory counterpart.

This class can act as a drop-in replacement for CompressedImage, CompressedImageView and Trade::ImageData APIs. See also BufferImage for equivalent functionality targeted on non-compressed image formats.

Basic usage

The image creates a Buffer instance and fills it with passed data, storing corresponding image size and compression format properties. Because this is a GL-centric class, it's common to specify the format using GL::CompressedPixelFormat:

GL::CompressedBufferImage2D image{GL::CompressedPixelFormat::RGBS3tcDxt1,
    {512, 256}, data, GL::BufferUsage::StaticDraw};

It's also possible to pass the generic Magnum::CompressedPixelFormat to it, however the format() query will always return the GL-specific value.

Besides creating and owning the buffer, you can also pass existing buffer to it, for example to use buffer storage and other advanced functionality. The image will take an ownership of the buffer, you can use Buffer::wrap() to make a non-owning copy.

GL::Buffer buffer;
GL::CompressedBufferImage2D image{GL::CompressedPixelFormat::RGBS3tcDxt1,
    {512, 256}, std::move(buffer), 65536};

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;
GL::CompressedBufferImage2D image = texture.compressedImage(0, {},
    GL::BufferUsage::StaticRead);

Similarly to CompressedImageView, this class supports extra storage parameters. See Basic usage for more information.

Unlike CompressedImage, CompressedImageView and Trade::ImageData, this class doesn't support setting ImageFlags. In those, image flags are used mainly to distinguish between various image layouts when interfacing with file formats and external conversion libraries. The buffer image, however, usually acts as a temporary storage for data transfer following OpenGL constraints, and as such the annotations aren't as essential.

Public types

enum (anonymous): UnsignedInt { Dimensions = dimensions }

Constructors, destructors, conversion operators

CompressedBufferImage(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage) explicit
Constructor.
CompressedBufferImage(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage) explicit
Constructor.
CompressedBufferImage(CompressedPixelStorage storage, Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage) explicit
Constructor.
CompressedBufferImage(Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage) explicit
Constructor.
CompressedBufferImage(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Buffer&& buffer, std::size_t dataSize) explicit noexcept
Constructor.
CompressedBufferImage(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Buffer&& buffer, std::size_t dataSize) explicit noexcept
Construct from existing buffer.
CompressedBufferImage(CompressedPixelStorage storage, Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Buffer&& buffer, std::size_t dataSize) explicit noexcept
Construct from existing buffer.
CompressedBufferImage(Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Buffer&& buffer, std::size_t dataSize) explicit noexcept
Construct from existing buffer.
CompressedBufferImage(CompressedPixelStorage storage)
Construct an image placeholder.
CompressedBufferImage()
Construct an image placeholder.
CompressedBufferImage(NoCreateT) explicit noexcept
Construct without creating the underlying OpenGL object.
CompressedBufferImage(const CompressedBufferImage<dimensions>&) deleted
Copying is not allowed.
CompressedBufferImage(CompressedBufferImage<dimensions>&& other) noexcept
Move constructor.

Public functions

auto operator=(const CompressedBufferImage<dimensions>&) -> CompressedBufferImage<dimensions>& deleted
Copying is not allowed.
auto operator=(CompressedBufferImage<dimensions>&& other) -> CompressedBufferImage<dimensions>& noexcept
Move assignment.
auto buffer() -> Buffer&
Image buffer.
auto dataSize() const -> std::size_t
Raw data size.
void setData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)
Set image data.
void setData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)
Set image data.
void setData(CompressedPixelStorage storage, Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)
Set image data.
void setData(Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)
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 -> 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() -> Buffer
Release the image buffer.

Enum documentation

template<UnsignedInt dimensions>
enum Magnum::GL::CompressedBufferImage<dimensions>::(anonymous): UnsignedInt

Enumerators
Dimensions

Image dimension count

Function documentation

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

Constructor.

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

The data array is expected to be of proper size for given parameters. CompressedPixelStorage::compressedBlockSize() and compressedBlockDataSize() in storage are expected to be either both zero or exactly matching properties of given format.

template<UnsignedInt dimensions>
Magnum::GL::CompressedBufferImage<dimensions>::CompressedBufferImage(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage) explicit

Constructor.

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

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

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

Constructor.

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

Converts Magnum::CompressedPixelFormat to a GL-specific value using compressedPixelFormat() and and then calls CompressedBufferImage(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<const void>, BufferUsage).

template<UnsignedInt dimensions>
Magnum::GL::CompressedBufferImage<dimensions>::CompressedBufferImage(Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage) explicit

Constructor.

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

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

template<UnsignedInt dimensions>
Magnum::GL::CompressedBufferImage<dimensions>::CompressedBufferImage(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Buffer&& buffer, std::size_t dataSize) explicit noexcept

Constructor.

Parameters
storage Storage of compressed pixel data
format Format of compressed pixel data
size Image size
buffer Buffer
dataSize Buffer data size

The dataSize is expected to be of proper size for given parameters. CompressedPixelStorage::compressedBlockSize() and compressedBlockDataSize() in storage are expected to be either both zero or exactly matching properties of given format.

If dataSize is 0, the buffer is unconditionally reallocated on the first call to setData().

template<UnsignedInt dimensions>
Magnum::GL::CompressedBufferImage<dimensions>::CompressedBufferImage(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Buffer&& buffer, std::size_t dataSize) explicit noexcept

Construct from existing buffer.

Parameters
format Format of compressed pixel data
size Image size
buffer Buffer
dataSize Buffer data size

Equivalent to calling CompressedBufferImage(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Buffer&&, std::size_t) with default-constructed CompressedPixelStorage.

template<UnsignedInt dimensions>
Magnum::GL::CompressedBufferImage<dimensions>::CompressedBufferImage(CompressedPixelStorage storage, Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Buffer&& buffer, std::size_t dataSize) explicit noexcept

Construct from existing buffer.

Parameters
storage Storage of compressed pixel data
format Format of compressed pixel data
size Image size
buffer Buffer
dataSize Buffer data size

Converts Magnum::CompressedPixelFormat to a GL-specific value using compressedPixelFormat() and and then calls CompressedBufferImage(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Buffer&&, std::size_t).

template<UnsignedInt dimensions>
Magnum::GL::CompressedBufferImage<dimensions>::CompressedBufferImage(Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Buffer&& buffer, std::size_t dataSize) explicit noexcept

Construct from existing buffer.

Parameters
format Format of compressed pixel data
size Image size
buffer Buffer
dataSize Buffer data size

Equivalent to calling CompressedBufferImage(CompressedPixelStorage, Magnum::CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Buffer&&, std::size_t) with default-constructed CompressedPixelStorage.

template<UnsignedInt dimensions>
Magnum::GL::CompressedBufferImage<dimensions>::CompressedBufferImage(CompressedPixelStorage storage)

Construct an image placeholder.

Parameters
storage Storage of compressed pixel data

Format and block properties are undefined, size is zero and buffer is empty. Call setData() to fill the image with data.

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

template<UnsignedInt dimensions>
Magnum::GL::CompressedBufferImage<dimensions>::CompressedBufferImage()

Construct an image placeholder.

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

template<UnsignedInt dimensions>
Magnum::GL::CompressedBufferImage<dimensions>::CompressedBufferImage(NoCreateT) explicit noexcept

Construct without creating the underlying OpenGL object.

The constructed instance is equivalent to moved-from state. Useful in cases where you will overwrite the instance later anyway. Move another object over it to make it useful.

This function can be safely used for constructing (and later destructing) objects even without any OpenGL context being active. However note that this is a low-level and a potentially dangerous API, see the documentation of NoCreate for alternatives.

template<UnsignedInt dimensions>
Buffer& Magnum::GL::CompressedBufferImage<dimensions>::buffer()

Image buffer.

template<UnsignedInt dimensions>
void Magnum::GL::CompressedBufferImage<dimensions>::setData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)

Set image data.

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

Updates the image buffer with given data. Passing nullptr zero-sized data will not reallocate current storage, but expects that current data size is large enough for the new parameters.

template<UnsignedInt dimensions>
void Magnum::GL::CompressedBufferImage<dimensions>::setData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)

Set image data.

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

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

template<UnsignedInt dimensions>
void Magnum::GL::CompressedBufferImage<dimensions>::setData(CompressedPixelStorage storage, Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)

Set image data.

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

Converts Magnum::CompressedPixelFormat to a GL-specific value using compressedPixelFormat() and and then calls setData(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<const void>, BufferUsage).

template<UnsignedInt dimensions>
void Magnum::GL::CompressedBufferImage<dimensions>::setData(Magnum::CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)

Set image data.

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

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

template<UnsignedInt dimensions>
Vector3i Magnum::GL::CompressedBufferImage<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::GL::CompressedBufferImage<dimensions>::blockDataSize() const new in Git master

Size of a compressed block in bytes.

template<UnsignedInt dimensions>
VectorTypeFor<Dimensions, Int> Magnum::GL::CompressedBufferImage<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::GL::CompressedBufferImage<dimensions>::dataProperties() const

Compressed image data properties.

See CompressedPixelStorage::dataProperties() for more information.

template<UnsignedInt dimensions>
Buffer Magnum::GL::CompressedBufferImage<dimensions>::release()

Release the image buffer.

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