template<UnsignedInt dimensions>
Magnum::Image class

Image.

Stores multi-dimensional image data together with layout and pixel format description. See ImageView for a non-owning alternative.

This class can act as a drop-in replacement for ImageView and Trade::ImageData APIs and is implicitly convertible to ImageView. Particular graphics API wrappers provide additional image classes, for example GL::BufferImage. See also CompressedImage for equivalent functionality targeted on compressed image formats.

Basic usage

The image takes ownership of a passed Corrade::Containers::Array, together with storing image size and one of the generic PixelFormat values:

Containers::Array<char> data;
Image2D image{PixelFormat::RGBA8Unorm, {512, 256}, std::move(data)};

On construction, the image internally calculates pixel size corresponding to given pixel format using pixelSize(). This value is needed to check that the passed data array is large enough and is also required by most image manipulation operations.

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;
Image2D image = texture.image(0, {GL::PixelFormat::DepthComponent,
                                  GL::PixelType::UnsignedInt});

As with ImageView, this class supports extra storage parameters and implementation-specific pixel format specification. See the ImageView documentation for more information.

Obtaining a view on pixel data

While the raw image data are available through data(), for correct pixel addressing it's required to incorporate all storage() parameters such as row alignment, row length, skip offset and such. This is very error-prone to do by hand even with the help of dataProperties().

The pixels() accessor returns a multi-dimensional Corrade::Containers::StridedArrayView describing layout of the data and providing easy access to particular rows, pixels and pixel channels. The non-templated version returns a view that has one dimension more than the actual image, with the last dimension being bytes in a particular pixels. The second-to-last dimension is always pixels in a row, the one before (if the image is at least 2D) is rows in an image, and for 3D images the very first dimension describes image slices. Desired usage is casting to a concrete type based on format() first, either using the templated pixels<T>() or using Corrade::Containers::arrayCast() and then operating on the concretely typed array. The following example brightens the center 32x32 area of an image:

Image2D image{PixelFormat::RGB8Unorm, {128, 128}, data};

Containers::StridedArrayView2D<Color3ub> pixels = image.pixels<Color3ub>();
for(auto row: pixels.slice({48, 48}, {80, 80})) {
    for(Color3ub& pixel: row) pixel *= 1.1f;
}

This operation is available also on ImageView and non-compressed Trade::ImageData. See Corrade::Containers::StridedArrayView docs for more information about transforming, slicing and converting the view further.

Public types

enum (anonymous): UnsignedInt { Dimensions = dimensions }

Constructors, destructors, conversion operators

Image(PixelStorage storage, PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept
Constructor.
Image(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept
Constructor.
Image(PixelStorage storage, PixelFormat format) noexcept
Construct an image placeholder.
Image(PixelFormat format) noexcept
Construct an image placeholder.
Image(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept
Construct an image with implementation-specific pixel format.
Image(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept
Image(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize) explicit noexcept
Construct an image placeholder with implementation-specific pixel format.
Image(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize) explicit noexcept
template<class T, class U>
Image(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept
Construct an image with implementation-specific pixel format.
template<class T>
Image(PixelStorage storage, T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept
Construct an image with implementation-specific pixel format.
template<class T, class U>
Image(T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept
Construct an image with implementation-specific pixel format.
template<class T>
Image(T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept
Construct an image with implementation-specific pixel format.
template<class T, class U>
Image(PixelStorage storage, T format, U formatExtra) noexcept
Construct an image placeholder with implementation-specific pixel format.
template<class T, class U>
Image(T format, U formatExtra) noexcept
Construct an image placeholder with implementation-specific pixel format.
template<class T>
Image(PixelStorage storage, T format) noexcept
Construct an image placeholder with implementation-specific pixel format.
template<class T>
Image(T format) noexcept
Construct an image placeholder with implementation-specific pixel format.
Image(const Image<dimensions>&) deleted
Copying is not allowed.
Image(Image<dimensions>&& other) noexcept
Move constructor.
operator BasicMutableImageView<dimensions>()
Conversion to view.
operator BasicImageView<dimensions>() const

Public functions

auto operator=(const Image<dimensions>&) -> Image<dimensions>& deleted
Copying is not allowed.
auto operator=(Image<dimensions>&& other) -> Image<dimensions>& noexcept
Move assignment.
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 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>>
Image data properties.
auto data() & -> Containers::ArrayView<char>
Image data.
auto data() const & -> Containers::ArrayView<const char>
auto data() && -> Containers::Array<char>
Image data from a r-value.
auto data() const && -> Containers::Array<char> deleted
template<class T>
auto data() -> T* deprecated
Image data in a particular type.
template<class T>
auto data() const -> const T* deprecated
Image data in a particular type.
auto pixels() -> Containers::StridedArrayView<dimensions+1, char>
View on pixel data.
auto pixels() const -> Containers::StridedArrayView<dimensions+1, const char>
template<class T>
auto pixels() -> Containers::StridedArrayView<dimensions, T>
View on pixel data with a concrete pixel type.
template<class T>
auto pixels() const -> Containers::StridedArrayView<dimensions, const T>
auto release() -> Containers::Array<char>
Release data storage.

Enum documentation

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

Enumerators
Dimensions

Image dimension count

Function documentation

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

Constructor.

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

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

template<UnsignedInt dimensions>
Magnum::Image<dimensions>::Image(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept

Constructor.

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

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

template<UnsignedInt dimensions>
Magnum::Image<dimensions>::Image(PixelStorage storage, PixelFormat format) noexcept

Construct an image placeholder.

Parameters
storage Storage of pixel data
format Format of pixel data

Size is set to zero and data pointer to nullptr. Move over a non-empty instance to make it useful.

template<UnsignedInt dimensions>
Magnum::Image<dimensions>::Image(PixelFormat format) noexcept

Construct an image placeholder.

Parameters
format Format of pixel data

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

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

Construct an image 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

Unlike with Image(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&), 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::Image<dimensions>::Image(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) 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>
Magnum::Image<dimensions>::Image(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize) explicit noexcept

Construct an image placeholder 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

Unlike with Image(PixelStorage, PixelFormat), 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.

template<UnsignedInt dimensions>
Magnum::Image<dimensions>::Image(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize) 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::Image<dimensions>::Image(PixelStorage storage, T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept

Construct an image 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

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

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

Construct an image with implementation-specific pixel format.

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

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

template<UnsignedInt dimensions> template<class T, class U>
Magnum::Image<dimensions>::Image(T format, U formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept

Construct an image with implementation-specific pixel format.

Parameters
format Format of pixel data
formatExtra Additional pixel format specifier
size Image size
data Image data

Equivalent to calling Image(PixelStorage, T, U, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&) with default-constructed PixelStorage.

template<UnsignedInt dimensions> template<class T>
Magnum::Image<dimensions>::Image(T format, const VectorTypeFor<dimensions, Int>& size, Containers::Array<char>&& data) explicit noexcept

Construct an image with implementation-specific pixel format.

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

Equivalent to calling Image(PixelStorage, T, const VectorTypeFor<dimensions, Int>&, Containers::Array<char>&&) with default-constructed PixelStorage.

template<UnsignedInt dimensions> template<class T, class U>
Magnum::Image<dimensions>::Image(PixelStorage storage, T format, U formatExtra) noexcept

Construct an image placeholder with implementation-specific pixel format.

Parameters
storage Storage of pixel data
format Format of pixel data
formatExtra Additional pixel format specifier

Uses ADL to find a corresponding pixelSize(T, U) overload, then calls Image(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt) with calculated pixel size.

template<UnsignedInt dimensions> template<class T, class U>
Magnum::Image<dimensions>::Image(T format, U formatExtra) noexcept

Construct an image placeholder with implementation-specific pixel format.

Parameters
format Format of pixel data
formatExtra Additional pixel format specifier

Equivalent to calling Image(PixelStorage, T, U) with default-constructed PixelStorage.

template<UnsignedInt dimensions> template<class T>
Magnum::Image<dimensions>::Image(PixelStorage storage, T format) noexcept

Construct an image placeholder with implementation-specific pixel format.

Parameters
storage Storage of pixel data
format Format of pixel data

Uses ADL to find a corresponding pixelSize(T) overload, then calls Image(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt) with calculated pixel size and formatExtra set to 0.

template<UnsignedInt dimensions> template<class T>
Magnum::Image<dimensions>::Image(T format) noexcept

Construct an image placeholder with implementation-specific pixel format.

Parameters
format Format of pixel data

Equivalent to calling Image(PixelStorage, T) with default-constructed PixelStorage.

template<UnsignedInt dimensions>
Magnum::Image<dimensions>::operator BasicImageView<dimensions>() 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>
PixelFormat Magnum::Image<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.

template<UnsignedInt dimensions>
UnsignedInt Magnum::Image<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.

template<UnsignedInt dimensions>
UnsignedInt Magnum::Image<dimensions>::pixelSize() const

Pixel size (in bytes)

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

Image data properties.

See PixelStorage::dataProperties() for more information.

template<UnsignedInt dimensions>
Containers::ArrayView<char> Magnum::Image<dimensions>::data() &

Image data.

template<UnsignedInt dimensions>
Containers::ArrayView<const char> Magnum::Image<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::Image<dimensions>::data() &&

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.

template<UnsignedInt dimensions>
Containers::Array<char> Magnum::Image<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::Image<dimensions>::data()

Image data in a particular type.

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

Image data in a particular type.

template<UnsignedInt dimensions>
Containers::StridedArrayView<dimensions+1, char> Magnum::Image<dimensions>::pixels()

View on pixel data.

Provides direct and easy-to-use access to image pixels. See Obtaining a view on pixel data for more information.

template<UnsignedInt dimensions>
Containers::StridedArrayView<dimensions+1, const char> Magnum::Image<dimensions>::pixels() 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> template<class T>
Containers::StridedArrayView<dimensions, T> Magnum::Image<dimensions>::pixels()

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.

template<UnsignedInt dimensions> template<class T>
Containers::StridedArrayView<dimensions, const T> Magnum::Image<dimensions>::pixels() 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::Image<dimensions>::release()

Release data storage.

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