#include <Magnum/Trade/ImageData.h>
template<UnsignedInt dimensions>
Magnum::Trade::ImageData class

Image data.

Provides access to both uncompressed and compressed image data together with information about data layout, image size and pixel format. Populated instances of this class are returned from AbstractImporter::image1D(), image2D(), image3D(), can be passed to AbstractImageConverter::convert(), AbstractSceneConverter::add(const ImageData2D&, Containers::StringView) and related APIs, as well as used in various TextureTools algorithms. Like with other Trade types, the internal representation is fixed upon construction and allows only optional in-place modification of the data itself, but not of the overall structure.

This class can act as a drop-in replacement for Image or CompressedImage, ImageView or CompressedImageView and is implicitly convertible to either ImageView or CompressedImageView. Particular graphics API wrappers provide additional image classes, for example GL::BufferImage or GL::CompressedBufferImage.

Basic usage

Based on whether the ImageData has an uncompressed or compressed pixel format, it behaves either like an Image / ImageView or like a CompressedImage / CompressedImageView. It can be distinguished using isCompressed(); uncompressed image properties are then available through storage(), format(), formatExtra() and pixelSize(), compressed properties through compressedStorage() and compressedFormat(). Example of uploading the image to a GL::Texture:

Trade::ImageData2D image = …;

GL::Texture2D texture;
…
texture.setStorage(1, GL::textureFormat(image.format()), image.size());
if(!image.isCompressed())
    texture.setSubImage(0, {}, image);
else
    texture.setCompressedSubImage(0, {}, image);

Uncompressed image data instances provide pixel data access via pixels() in the same way as the Image class. See its documentation for more information.

Mutable data access

The interfaces implicitly provide const views on the contained pixel data through the data() and pixels() accessors. This is done because in general case the data can also refer to a memory-mapped file or constant memory. In cases when it's desirable to modify the data in-place, there's the mutableData() and mutablePixels() set of functions. To use these, you need to check that the data are mutable using dataFlags() first. The following snippet flips the R and B channels of the imported image:

if(data.isCompressed() ||
   data.format() != PixelFormat::RGB8Unorm ||
   !(data.dataFlags() & Trade::DataFlag::Mutable))
    Fatal{} << ":(";

for(auto&& row: data.mutablePixels<Color3ub>())
    for(Color3ub& pixel: row)
        pixel = Math::gather<'b', 'g', 'r'>(pixel);

Populating an instance

An ImageData instance by default takes over the ownership of an Containers::Array containing the pixel data together with size and either PixelFormat or CompressedPixelFormat, similarly to the Image and CompressedImage classes:

Containers::Array<char> uncompressedData = …;
Trade::ImageData2D uncompressed{PixelFormat::RGB8Unorm,
    {32, 32}, std::move(uncompressedData)};

Containers::Array<char> compressedData = …;
Trade::ImageData2D compressed{CompressedPixelFormat::Bc1RGBUnorm,
    {32, 32}, std::move(compressedData)};

The constructor internally checks that the passed array is large enough and as with other image classes, care must be taken in presence of non-four-byte-aligned rows. This often closely depends on behavior of the code or library that operates with the image data and the recommended way is to pad the row data to satisfy the alignment:

PixelFormat format = …;
Vector2i size = …;
std::size_t rowStride = 4*((size.x()*pixelFormatSize(format) + 3)/4);
Containers::Array<char> data{ValueInit, std::size_t(size.y()*rowStride)};
…

Trade::ImageData2D image{format, size, std::move(data)};

Alternatively, if padding is not possible or desirable, you can pass a PixelStorage instance with the alignment overriden to 1:

PixelFormat format = …;
Vector2i size = …;
std::size_t rowLength = size.x()*pixelFormatSize(format);
Containers::Array<char> data{ValueInit, std::size_t(size.y()*rowLength)};
…

Trade::ImageData2D image{
    PixelStorage{}.setAlignment(rowLength % 4 == 0 ? 4 : 1),
    format, size, std::move(data)};

As with Image / ImageView, this class supports extra storage parameters and implementation-specific format specification, if the importer has a need for that. See the ImageView documentation for more information.

Non-owned instances

In some cases you may want the ImageData instance to only refer to external data without taking ownership, for example with a memory-mapped file, global data etc. For that, instead of moving in an Containers::Array, pass DataFlags describing data mutability and ownership together with an Containers::ArrayView:

Color3ub uncompressedData[]{…};
Trade::ImageData2D uncompressed{PixelFormat::RGB8Unorm,
    {32, 32}, Trade::DataFlag::Mutable, uncompressedData};

Containers::ArrayView<const char> compressedData = …;
Trade::ImageData2D compressed{CompressedPixelFormat::Bc1RGBUnorm,
    {32, 32}, Trade::DataFlags{}, compressedData};

Public types

enum (anonymous): UnsignedInt { Dimensions = dimensions }

Constructors, destructors, conversion operators

ImageData(PixelStorage storage, PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct an uncompressed image data.
ImageData(PixelStorage storage, PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) deprecated in Git master explicit noexcept
Construct an uncompressed image data.
ImageData(PixelStorage storage, PixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a non-owned uncompressed image data.
ImageData(PixelStorage storage, PixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) deprecated in Git master explicit noexcept
Construct a non-owned uncompressed image data.
ImageData(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct an uncompressed image data.
ImageData(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) deprecated in Git master explicit noexcept
Construct an uncompressed image data.
ImageData(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a non-owned uncompressed image data.
ImageData(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) deprecated in Git master explicit noexcept
Construct a non-owned uncompressed image data.
ImageData(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct an uncompressed image data with implementation-specific pixel format.
ImageData(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
ImageData(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) deprecated in Git master explicit noexcept
Construct an uncompressed image data with implementation-specific pixel format.
ImageData(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) deprecated in Git master explicit noexcept
ImageData(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a non-owned uncompressed image data with implementation-specific pixel format.
ImageData(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
ImageData(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) deprecated in Git master explicit noexcept
Construct a non-owned uncompressed image data with implementation-specific pixel format.
ImageData(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) deprecated in Git master explicit noexcept
template<class T, class U>
ImageData(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct an uncompressed image data with implementation-specific pixel format.
template<class T, class U>
ImageData(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) deprecated in Git master explicit noexcept
Construct an uncompressed image data with implementation-specific pixel format.
template<class T, class U>
ImageData(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a non-owned uncompressed image data with implementation-specific pixel format.
template<class T, class U>
ImageData(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) deprecated in Git master explicit noexcept
Construct a non-owned uncompressed image data with implementation-specific pixel format.
template<class T>
ImageData(PixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct an uncompressed image data with implementation-specific pixel format.
template<class T>
ImageData(PixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) deprecated in Git master explicit noexcept
Construct an uncompressed image data with implementation-specific pixel format.
template<class T>
ImageData(PixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a non-owned uncompressed image data with implementation-specific pixel format.
template<class T>
ImageData(PixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) deprecated in Git master explicit noexcept
Construct a non-owned uncompressed image data with implementation-specific pixel format.
ImageData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a compressed image data.
ImageData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) deprecated in Git master explicit noexcept
Construct a compressed image data.
ImageData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a non-owned compressed image data.
ImageData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) deprecated in Git master explicit noexcept
Construct a non-owned compressed image data.
ImageData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a compressed image data.
ImageData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) deprecated in Git master explicit noexcept
Construct a compressed image data.
ImageData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a non-owned compressed image data.
ImageData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) deprecated in Git master explicit noexcept
Construct a non-owned compressed image data.
template<class T>
ImageData(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a compressed image data.
template<class T>
ImageData(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) deprecated in Git master explicit noexcept
Construct a compressed image data.
template<class T>
ImageData(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master
Construct a non-owned compressed image data.
template<class T>
ImageData(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) deprecated in Git master explicit noexcept
Construct a non-owned compressed image data.
ImageData(ImageData<dimensions>&& other, const void* importerState) explicit noexcept
Construct from existing data with attached importer state.
ImageData(const ImageData<dimensions>&) deleted
Copying is not allowed.
ImageData(ImageData<dimensions>&& other) noexcept
Move constructor.
operator BasicImageView<dimensions>() const
Conversion to a view.
operator BasicMutableImageView<dimensions>() new in 2019.10
Conversion to a mutable view.
operator BasicCompressedImageView<dimensions>() const
Conversion to a compressed view.
operator BasicMutableCompressedImageView<dimensions>() new in 2019.10
Conversion to a mutable compressed view.

Public functions

auto operator=(const ImageData<dimensions>&) -> ImageData<dimensions>& deleted
Copying is not allowed.
auto operator=(ImageData<dimensions>&& other) -> ImageData<dimensions>& noexcept
Move assignment.
auto dataFlags() const -> DataFlags new in 2020.06
Data flags.
auto isCompressed() const -> bool
Whether the image is compressed.
auto flags() const -> ImageFlags<dimensions> new in Git master
Layout flags.
auto storage() const -> PixelStorage
Storage of pixel data.
auto format() const -> PixelFormat
Format of pixel data.
auto formatExtra() const -> UnsignedInt
Additional pixel format specifier.
auto compressedStorage() const -> CompressedPixelStorage
Storage of compressed pixel data.
auto compressedFormat() const -> CompressedPixelFormat
Format of compressed pixel data.
auto pixelSize() const -> UnsignedInt
Size of a pixel 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>>
Uncompressed image data properties.
auto data() const & -> Containers::ArrayView<const char>
Raw image data.
auto data() && -> Containers::Array<char> new in 2019.10
Image data from a r-value.
auto data() const && -> Containers::Array<char> deleted new in 2019.10
auto mutableData() & -> Containers::ArrayView<char> new in 2020.06
Mutable image data.
template<class T>
auto data() -> T* deprecated in 2019.10
Image data in a particular type.
template<class T>
auto data() const -> const T* deprecated in 2019.10
Image data in a particular type.
auto pixels() const -> Containers::StridedArrayView<dimensions+1, const char> new in 2019.10
Pixel data.
auto mutablePixels() -> Containers::StridedArrayView<dimensions+1, char> new in 2020.06
Mutable pixel data.
template<class T>
auto pixels() const -> Containers::StridedArrayView<dimensions, const T> new in 2019.10
View on pixel data with a concrete pixel type.
template<class T>
auto mutablePixels() -> Containers::StridedArrayView<dimensions, T> new in 2019.10
Mutable view on pixel data with a concrete pixel type.
auto release() -> Containers::Array<char>
Release data storage.
auto importerState() const -> const void*
Importer-specific state.

Enum documentation

template<UnsignedInt dimensions>
enum Magnum::Trade::ImageData<dimensions>::(anonymous): UnsignedInt

Enumerators
Dimensions

Image dimension count

Function documentation

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct an uncompressed image data.

Parameters
storage Storage of pixel data
format Format of pixel data
size Image size
data Image data
flags Image layout flags
importerState Importer-specific state

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 dataFlags() are implicitly set to a combination of DataFlag::Owned and DataFlag::Mutable. For non-owned data use the ImageData(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, DataFlags, Containers::ArrayView<const void>, ImageFlags<dimensions>, const void*) constructor instead.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) explicit noexcept

Construct an uncompressed image data.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, PixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a non-owned uncompressed image data.

Parameters
storage Storage of pixel data
format Format of pixel data
size Image size
dataFlags Data flags
data View on image data
flags Image layout flags
importerState Importer-specific state

Compared to ImageData(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) creates an instance that doesn't own the passed data. The dataFlags parameter can contain DataFlag::Mutable to indicate the external data can be modified, and is expected to not have DataFlag::Owned set.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, PixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) explicit noexcept

Construct a non-owned uncompressed image data.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct an uncompressed image data.

Parameters
format Format of pixel data
size Image size
data Image data
flags Image layout flags
importerState Importer-specific state

Equivalent to calling ImageData(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) with default-constructed PixelStorage.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) explicit noexcept

Construct an uncompressed image data.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a non-owned uncompressed image data.

Parameters
format Format of pixel data
size Image size
dataFlags Data flags
data View on image data
flags Image layout flags
importerState Importer-specific state

Compared to ImageData(PixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) creates an instance that doesn't own the passed data. The dataFlags parameter can contain DataFlag::Mutable to indicate the external data can be modified, and is expected to not have DataFlag::Owned set.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) explicit noexcept

Construct a non-owned uncompressed image data.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct an uncompressed image data with implementation-specific pixel format.

Parameters
storage Storage of pixel data
format Format of pixel data
formatExtra Additional pixel format specifier
pixelSize Size of a pixel in given format, in bytes
size Image size, in pixels
data Image data
flags Image layout flags
importerState Importer-specific state

Unlike with ImageData(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*), where pixel size is calculated automatically using pixelFormatSize(), this allows you to specify an implementation-specific pixel format and pixel size directly. Uses pixelFormatWrap() internally to wrap format in PixelFormat.

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 dataFlags() are implicitly set to a combination of DataFlag::Owned and DataFlag::Mutable. For non-owned data use the ImageData(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt, const VectorTypeFor<dimensions, Int>&, DataFlags, Containers::ArrayView<const void>, ImageFlags<dimensions>, const void*) constructor instead.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) 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 pixelFormatWrap().

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) explicit noexcept

Construct an uncompressed image data with implementation-specific pixel format.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) explicit noexcept

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>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a non-owned uncompressed image data with implementation-specific pixel format.

Parameters
storage Storage of pixel data
format Format of pixel data
formatExtra Additional pixel format specifier
pixelSize Size of a pixel in given format, in bytes
size Image size, in pixels
dataFlags Data flags
data View on image data
flags Image layout flags
importerState Importer-specific state

Compared to ImageData(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) creates an instance that doesn't own the passed data. The dataFlags parameter can contain DataFlag::Mutable to indicate the external data can be modified, and is expected to not have DataFlag::Owned set.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) 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 pixelFormatWrap().

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) explicit noexcept

Construct a non-owned uncompressed image data with implementation-specific pixel format.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) explicit noexcept

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> template<class T, class U>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct an uncompressed image data with implementation-specific pixel format.

Parameters
storage Storage of pixel data
format Format of pixel data
formatExtra Additional pixel format specifier
size Image size
data Image data
flags Image layout flags
importerState Importer-specific state

Uses ADL to find a corresponding pixelFormatSize(T, U) overload, then calls ImageData(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) with calculated pixel size.

template<UnsignedInt dimensions> template<class T, class U>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) explicit noexcept

Construct an uncompressed image data with implementation-specific pixel format.

template<UnsignedInt dimensions> template<class T, class U>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a non-owned uncompressed image data with implementation-specific pixel format.

Parameters
storage Storage of pixel data
format Format of pixel data
formatExtra Additional pixel format specifier
size Image size
dataFlags Data flags
data View on image data
flags Image layout flags
importerState Importer-specific state

Compared to ImageData(PixelStorage, T, U, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) creates an instance that doesn't own the passed data. The dataFlags parameter can contain DataFlag::Mutable to indicate the external data can be modified, and is expected to not have DataFlag::Owned set.

template<UnsignedInt dimensions> template<class T, class U>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) explicit noexcept

Construct a non-owned uncompressed image data with implementation-specific pixel format.

template<UnsignedInt dimensions> template<class T>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct an uncompressed image data with implementation-specific pixel format.

Parameters
storage Storage of pixel data
format Format of pixel data
size Image size
data Image data
flags Image layout flags
importerState Importer-specific state

Uses ADL to find a corresponding pixelFormatSize(T) overload, then calls ImageData(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) with calculated pixel size and formatExtra set to 0.

template<UnsignedInt dimensions> template<class T>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) explicit noexcept

Construct an uncompressed image data with implementation-specific pixel format.

template<UnsignedInt dimensions> template<class T>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a non-owned uncompressed image data with implementation-specific pixel format.

Parameters
storage Storage of pixel data
format Format of pixel data
size Image size
dataFlags Data flags
data view on image data
flags Image layout flags
importerState Importer-specific state

Compared to ImageData(PixelStorage, T, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) creates an instance that doesn't own the passed data. The dataFlags parameter can contain DataFlag::Mutable to indicate the external data can be modified, and is expected to not have DataFlag::Owned set.

template<UnsignedInt dimensions> template<class T>
Magnum::Trade::ImageData<dimensions>::ImageData(PixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) explicit noexcept

Construct a non-owned uncompressed image data with implementation-specific pixel format.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a compressed image data.

Parameters
storage Storage of compressed pixel data
format Format of compressed pixel data
size Image size
data Image data
flags Image layout flags
importerState Importer-specific state

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) explicit noexcept

Construct a compressed image data.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a non-owned compressed image data.

Parameters
storage Storage of compressed pixel data
format Format of compressed pixel data
size Image size
dataFlags Data flags
data View on image data
flags Image layout flags
importerState Importer-specific state

Compared to ImageData(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) creates an instance that doesn't own the passed data. The dataFlags parameter can contain DataFlag::Mutable to indicate the external data can be modified, and is expected to not have DataFlag::Owned set.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) explicit noexcept

Construct a non-owned compressed image data.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a compressed image data.

Parameters
format Format of compressed pixel data
size Image size
data Image data
flags Image layout flags
importerState Importer-specific state

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

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) explicit noexcept

Construct a compressed image data.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a non-owned compressed image data.

Parameters
format Format of compressed pixel data
size Image size
dataFlags Data flags
data View on image data
flags Image layout flags
importerState Importer-specific state

Compared to ImageData(CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) creates an instance that doesn't own the passed data. The dataFlags parameter can contain DataFlag::Mutable to indicate the external data can be modified, and is expected to not have DataFlag::Owned set.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) explicit noexcept

Construct a non-owned compressed image data.

template<UnsignedInt dimensions> template<class T>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a compressed image data.

Parameters
storage Storage of compressed pixel data
format Format of compressed pixel data
size Image size
data Image data
flags Image layout flags
importerState Importer-specific state

Uses compressedPixelFormatWrap() internally to convert format to CompressedPixelFormat.

For a 3D image, if flags contain ImageFlag3D::CubeMap, the size is expected to match its restrictions.

template<UnsignedInt dimensions> template<class T>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState) explicit noexcept

Construct a compressed image data.

template<UnsignedInt dimensions> template<class T>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, ImageFlags<dimensions> flags = {}, const void* importerState = nullptr) explicit noexcept new in Git master

Construct a non-owned compressed image data.

Parameters
storage Storage of compressed pixel data
format Format of compressed pixel data
size Image size
dataFlags Data flags
data View on image data
flags Image layout flags
importerState Importer-specific state

Compared to ImageData(CompressedPixelStorage, T, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, ImageFlags<dimensions>, const void*) creates an instance that doesn't own the passed data. The dataFlags parameter can contain DataFlag::Mutable to indicate the external data can be modified, and is expected to not have DataFlag::Owned set.

template<UnsignedInt dimensions> template<class T>
Magnum::Trade::ImageData<dimensions>::ImageData(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, DataFlags dataFlags, Containers::ArrayView<const void> data, const void* importerState) explicit noexcept

Construct a non-owned compressed image data.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::ImageData(ImageData<dimensions>&& other, const void* importerState) explicit noexcept

Construct from existing data with attached importer state.

Useful in cases where importer plugins proxy image loading through other importers but want to attach its own importer state to the imported data. Importer state from the other object is replaced with importerState, data ownership is transferred and everything else stays the same.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::operator BasicImageView<dimensions>() const

Conversion to a view.

The image is expected to be uncompressed.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::operator BasicMutableImageView<dimensions>() new in 2019.10

Conversion to a mutable view.

The image is expected to be uncompressed and mutable.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::operator BasicCompressedImageView<dimensions>() const

Conversion to a compressed view.

The image is expected to be compressed.

template<UnsignedInt dimensions>
Magnum::Trade::ImageData<dimensions>::operator BasicMutableCompressedImageView<dimensions>() new in 2019.10

Conversion to a mutable compressed view.

The image is expected to be compressed and mutable.

template<UnsignedInt dimensions>
PixelStorage Magnum::Trade::ImageData<dimensions>::storage() const

Storage of pixel data.

The image is expected to be uncompressed.

template<UnsignedInt dimensions>
PixelFormat Magnum::Trade::ImageData<dimensions>::format() const

Format of pixel data.

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

The image is expected to be uncompressed.

template<UnsignedInt dimensions>
UnsignedInt Magnum::Trade::ImageData<dimensions>::formatExtra() const

Additional pixel format specifier.

Some implementations (such as OpenGL) define a pixel format using two values. This field contains the second implementation-specific value verbatim, if any. See format() for more information.

The image is expected to be uncompressed.

template<UnsignedInt dimensions>
CompressedPixelStorage Magnum::Trade::ImageData<dimensions>::compressedStorage() const

Storage of compressed pixel data.

The image is expected to be compressed.

template<UnsignedInt dimensions>
CompressedPixelFormat Magnum::Trade::ImageData<dimensions>::compressedFormat() 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.

The image is expected to be compressed.

template<UnsignedInt dimensions>
UnsignedInt Magnum::Trade::ImageData<dimensions>::pixelSize() const

Size of a pixel in bytes.

The image is expected to be uncompressed.

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

Uncompressed image data properties.

The image is expected to be uncompressed. See PixelStorage::dataProperties() for more information.

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

Raw image data.

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

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. Note that the returned array has a custom no-op deleter when the data are not owned by the image, and while the returned array type is mutable, the actual memory might be not.

template<UnsignedInt dimensions>
Containers::Array<char> Magnum::Trade::ImageData<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>
Containers::ArrayView<char> Magnum::Trade::ImageData<dimensions>::mutableData() & new in 2020.06

Mutable image data.

Like data(), but returns a non-const view. Expects that the image is mutable.

template<UnsignedInt dimensions> template<class T>
T* Magnum::Trade::ImageData<dimensions>::data()

Image data in a particular type.

template<UnsignedInt dimensions> template<class T>
const T* Magnum::Trade::ImageData<dimensions>::data() const

Image data in a particular type.

template<UnsignedInt dimensions>
Containers::StridedArrayView<dimensions+1, const char> Magnum::Trade::ImageData<dimensions>::pixels() const new in 2019.10

Pixel data.

Provides direct and easy-to-use access to image pixels. Expects that the image is not compressed. The last dimension represents the actual data type (its size is equal to type size) and is guaranteed to be contiguous. Use the templated overload below to get pixels in a concrete type. See Pixel data access for more information.

template<UnsignedInt dimensions>
Containers::StridedArrayView<dimensions+1, char> Magnum::Trade::ImageData<dimensions>::mutablePixels() new in 2020.06

Mutable pixel data.

Like pixels() const, but returns a non-const view. Expects that the image is mutable. See also Pixel data access for more information.

template<UnsignedInt dimensions> template<class T>
Containers::StridedArrayView<dimensions, const T> Magnum::Trade::ImageData<dimensions>::pixels() const new in 2019.10

View on pixel data with a concrete pixel type.

Compared to non-templated pixels() in addition casts the pixel data to a specified type. The user is responsible for choosing correct type for given format() — checking it on the library side is not possible for the general case. See also Pixel data access for more information.

template<UnsignedInt dimensions> template<class T>
Containers::StridedArrayView<dimensions, T> Magnum::Trade::ImageData<dimensions>::mutablePixels() new in 2019.10

Mutable view on pixel data with a concrete pixel type.

Like pixels() const, but returns a non-const view. Expects that the image is mutable.

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

Release data storage.

Releases the ownership of the data array and resets internal state to default. The image then behaves like it's empty. Note that the returned array has a custom no-op deleter when the data are not owned by the image, and while the returned array type is mutable, the actual memory might be not.

template<UnsignedInt dimensions>
const void* Magnum::Trade::ImageData<dimensions>::importerState() const

Importer-specific state.

See AbstractImporter::importerState() for more information.