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

Buffer image.

Stores multi-dimensional image data in GPU memory together with layout and pixel format description. See Image for the client memory counterpart.

This class can act as a drop-in replacement for Image, ImageView and Trade::ImageData APIs. See also CompressedBufferImage for equivalent functionality targeted on compressed image formats.

Basic usage

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

GL::BufferImage2D image{GL::PixelFormat::RGBA, GL::PixelType::UnsignedByte,
    {512, 256}, data, GL::BufferUsage::StaticDraw};

It's also possible to pass the generic Magnum::PixelFormat to it, however the format() and type() queries will always return the GL-specific value. On construction, the image internally calculates pixel size corresponding to given pixel format using either GL::pixelFormatSize() or Magnum::pixelFormatSize(). This value is needed to check that the passed data are large enough and also required by most of image manipulation operations.

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::BufferImage2D image{GL::PixelFormat::RGBA, GL::PixelType::UnsignedByte,
    {512, 256}, std::move(buffer), 524288};

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::BufferImage2D image = texture.image(0, {GL::PixelFormat::RGBA,
    GL::PixelType::UnsignedByte}, GL::BufferUsage::StaticRead);

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

Unlike Image, ImageView 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

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

Public functions

auto operator=(const BufferImage<dimensions>&) -> BufferImage<dimensions>& deleted
Copying is not allowed.
auto operator=(BufferImage<dimensions>&& other) -> BufferImage<dimensions>& noexcept
Move assignment.
auto storage() const -> PixelStorage
Storage of pixel data.
auto format() const -> PixelFormat
Format of pixel data.
auto type() const -> PixelType
Data type of pixel data.
auto pixelSize() const -> UnsignedInt
Size of a pixel 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>>
Image data properties.
auto dataSize() const -> std::size_t
Currently allocated data size.
auto buffer() -> Buffer&
Image buffer.
void setData(PixelStorage storage, PixelFormat format, PixelType type, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)
Set image data.
void setData(PixelFormat format, PixelType type, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)
void setData(PixelStorage storage, Magnum::PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)
Set image data.
void setData(Magnum::PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)
Set image data.
auto release() -> Buffer
Release the image buffer.

Enum documentation

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

Enumerators
Dimensions

Image dimension count

Function documentation

template<UnsignedInt dimensions>
Magnum::GL::BufferImage<dimensions>::BufferImage(PixelStorage storage, PixelFormat format, PixelType type, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage) explicit

Constructor.

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

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

Constructor.

Parameters
format Format of pixel data
type Data type of pixel data
size Image size
data Image data
usage Image buffer usage

Equivalent to calling BufferImage(PixelStorage, PixelFormat, PixelType, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<const void>, BufferUsage) with default-constructed PixelStorage.

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

Constructor.

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

Converts Magnum::PixelFormat to GL-specific values using pixelFormat() and pixelType() and then calls BufferImage(PixelStorage, PixelFormat, PixelType, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<const void>, BufferUsage).

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

Constructor.

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

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

template<UnsignedInt dimensions>
Magnum::GL::BufferImage<dimensions>::BufferImage(PixelStorage storage, PixelFormat format, PixelType type, const VectorTypeFor<dimensions, Int>& size, Buffer&& buffer, std::size_t dataSize) explicit noexcept

Construct from existing buffer.

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

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

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

Construct from existing buffer.

Parameters
format Format of pixel data
type Data type of pixel data
size Image size
buffer Buffer
dataSize Buffer data size

Equivalent to calling BufferImage(PixelStorage, PixelFormat, PixelType, const VectorTypeFor<dimensions, Int>&, Buffer&&, std::size_t) with default-constructed PixelStorage.

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

Construct from existing buffer.

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

Converts Magnum::PixelFormat to GL-specific values using pixelFormat() and pixelType() and then calls BufferImage(PixelStorage, PixelFormat, PixelType, const VectorTypeFor<dimensions, Int>&, Buffer&&, std::size_t).

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

Construct from existing buffer.

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

Equivalent to calling BufferImage(PixelStorage, Magnum::PixelFormat, const VectorTypeFor<dimensions, Int>&, Buffer&&, std::size_t) with default-constructed PixelStorage.

template<UnsignedInt dimensions>
Magnum::GL::BufferImage<dimensions>::BufferImage(PixelStorage storage, PixelFormat format, PixelType type)

Construct an image placeholder.

Parameters
storage Storage of pixel data
format Format of pixel data
type Data type of pixel data

Size is zero and buffer are empty, call setData() to fill the image with data.

template<UnsignedInt dimensions>
Magnum::GL::BufferImage<dimensions>::BufferImage(PixelFormat format, PixelType type)

Construct an image placeholder.

Parameters
format Format of pixel data
type Data type of pixel data

Equivalent to calling BufferImage(PixelStorage, PixelFormat, PixelType) with default-constructed PixelStorage.

template<UnsignedInt dimensions>
Magnum::GL::BufferImage<dimensions>::BufferImage(PixelStorage storage, Magnum::PixelFormat format)

Construct an image placeholder.

Parameters
storage Storage of pixel data
format Format of pixel data

Converts Magnum::PixelFormat to GL-specific values using pixelFormat() and pixelType() and then calls BufferImage(PixelStorage, PixelFormat, PixelType).

template<UnsignedInt dimensions>
Magnum::GL::BufferImage<dimensions>::BufferImage(Magnum::PixelFormat format)

Construct an image placeholder.

Parameters
format Format of pixel data

Equivalent to calling BufferImage(PixelStorage, Magnum::PixelFormat) with default-constructed PixelStorage.

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

Construct without creating the underlying OpenGL object.

The constructed instance is equivalent to moved-from state with PixelFormat::RGBA and PixelType::UnsignedByte. 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>
UnsignedInt Magnum::GL::BufferImage<dimensions>::pixelSize() const

Size of a pixel in bytes.

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

Image data properties.

See PixelStorage::dataProperties() for more information.

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

Image buffer.

template<UnsignedInt dimensions>
void Magnum::GL::BufferImage<dimensions>::setData(PixelStorage storage, PixelFormat format, PixelType type, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)

Set image data.

Parameters
storage Storage of pixel data
format Format of pixel data
type Data type of 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::BufferImage<dimensions>::setData(PixelFormat format, PixelType type, const VectorTypeFor<dimensions, Int>& size, Containers::ArrayView<const void> data, BufferUsage usage)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Similar to the above, but uses default PixelStorage parameters.

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

Set image data.

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

Converts Magnum::PixelFormat to GL-specific values using pixelFormat() and pixelType() and then calls setData(PixelStorage, PixelFormat, PixelType, const VectorTypeFor<dimensions, Int>&, Containers::ArrayView<const void>, BufferUsage).

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

Set image data.

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

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

template<UnsignedInt dimensions>
Buffer Magnum::GL::BufferImage<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.