template<UnsignedInt dimensions>
Magnum::Trade::ImageData class

Image data.

Contents

Used mainly by AbstractImporter classes to store either compressed or non-compressed multi-dimensional image data together with layout and pixel format description.

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

The image usually comes out of AbstractImporter::image1D(), image2D() or image3D() and, based on what format the particular imported data is in, it stores either compressed or uncompressed data.

Containers::Array<char> data;
Trade::ImageData2D image{PixelFormat::RGB8Unorm, {32, 32}, std::move(data)};
Containers::Array<char> data;
Trade::ImageData2D image{CompressedPixelFormat::Bc1RGBUnorm,
    {32, 32}, 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.

When using the image, its compression status can be distinguished using isCompressed(). Uncompressed image properties are available through storage(), format(), formatExtra() and pixelSize(); compressed properties through compressedStorage() and compressedFormat(). Example of uploading the image to GL::Texture:

std::unique_ptr<Trade::AbstractImporter> importer;
Containers::Optional<Trade::ImageData2D> image = importer->image2D(0);
if(!image) Fatal{} << "Oopsie!";

GL::Texture2D texture;
// ...
if(!image->isCompressed())
    texture.setSubImage(0, {}, *image);
else
    texture.setCompressedSubImage(0, {}, *image);

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, const void* importerState = nullptr) explicit noexcept
Construct uncompressed image data.
ImageData(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState = nullptr) explicit noexcept
Construct uncompressed image data.
ImageData(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState = nullptr) explicit noexcept
Construct 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 = nullptr) explicit noexcept
template<class T, class U>
ImageData(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState = nullptr) explicit noexcept
Construct 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 = nullptr) explicit noexcept
Construct uncompressed image data with implementation-specific pixel format.
template<class = void>
ImageData(PixelFormat format, GL::PixelType type, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState = nullptr) deprecated explicit noexcept
Construct uncompressed image data.
ImageData(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState = nullptr) explicit noexcept
Construct compressed image data.
ImageData(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState = nullptr) explicit noexcept
Construct compressed image data.
template<class T>
ImageData(CompressedPixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data, const void* importerState = nullptr) explicit noexcept
Construct compressed image data.
ImageData(const ImageData<dimensions>&) deleted
Copying is not allowed.
ImageData(ImageData<dimensions>&& other) noexcept
Move constructor.
operator ImageView<dimensions>() const
Conversion to view.
operator CompressedImageView<dimensions>() const
Conversion to 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 isCompressed() const -> bool
Whether the image is compressed.
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 type() const -> GL::PixelType deprecated
Data type of pixel data.
auto compressedStorage() const -> CompressedPixelStorage
Storage of compressed pixel data.
auto compressedFormat() const -> CompressedPixelFormat
Format of compressed pixel data.
auto pixelSize() const -> UnsignedInt
Pixel size (in bytes)
auto size() const -> VectorTypeFor<dimensions, Int>
Image size.
auto dataProperties() const -> std::pair<VectorTypeFor<dimensions, std::size_t>, VectorTypeFor<dimensions, std::size_t>>
Uncompressed image data properties.
auto data() & -> Containers::ArrayView<char>
Raw data.
auto data() && -> Containers::ArrayView<char> deleted
auto data() const & -> Containers::ArrayView<const char>
auto data() const && -> Containers::ArrayView<const char> deleted
template<class T>
auto data() -> T*
template<class T>
auto data() const -> const T*
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, const void* importerState = nullptr) explicit noexcept

Construct uncompressed image data.

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

The data array is expected to be of proper size for given parameters.

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

Construct uncompressed image data.

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

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

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 = nullptr) explicit noexcept

Construct 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
size Image size
data Image data
importerState Importer-specific state

Unlike with ImageData(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&, const void*), where pixel size is calculated automatically using pixelSize(PixelFormat), 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.

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 = nullptr) 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 pixelFormatWrap().

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 = nullptr) explicit noexcept

Construct 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
importerState Importer-specific state

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

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 = nullptr) explicit noexcept

Construct 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
importerState Importer-specific state

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

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

Construct uncompressed image data.

Parameters
format Format of pixel data
type Data type of pixel data
size Image size
data Image data
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 = nullptr) explicit noexcept

Construct compressed image data.

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

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

Construct compressed image data.

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

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

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 = nullptr) explicit noexcept

Construct compressed image data.

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

Uses compressedPixelFormatWrap() internally to convert format to CompressedPixelFormat.

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

Conversion to view.

The image is expected to be uncompressed.

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

Conversion to compressed view.

The image is expected to be compressed.

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>
GL::PixelType Magnum::Trade::ImageData<dimensions>::type() const

Data type of pixel data.

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

Pixel size (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<char> Magnum::Trade::ImageData<dimensions>::data() &

Raw data.

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

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<const char> Magnum::Trade::ImageData<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>
Containers::ArrayView<const char> Magnum::Trade::ImageData<dimensions>::data() const && deleted

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>
T* Magnum::Trade::ImageData<dimensions>::data()

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>
const T* Magnum::Trade::ImageData<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>
Containers::Array<char> Magnum::Trade::ImageData<dimensions>::release()

Release data storage.

Releases the ownership of the data array and resets internal state to default.

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

Importer-specific state.

See AbstractImporter::importerState() for more information.