#include <Magnum/Image.h>
template<UnsignedInt dimensions>
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::
Basic usage
The image takes ownership of a passed Containers::
Vector2i size{512, 256}; PixelFormat format = PixelFormat::RGBA8Unorm; Image2D image{format, size, Containers::Array<char>{ValueInit, std::size_t(size.product()*pixelFormatSize(format))}};
The constructor internally checks that the passed array is large enough. For performance reasons it by default expects rows aligned to four bytes, which you need to account for if using odd image sizes in combination with one-, two- or three-component formats. The recommended way is to pad the row data to satisfy the alignment:
PixelFormat format = PixelFormat::RGB8Unorm; Vector2i size{173, 232}; std::size_t rowStride = 4*((size.x()*pixelFormatSize(format) + 3)/4); Image2D image{format, size, Containers::Array<char>{ValueInit, std::size_t(size.y()*rowStride)}};
Alternatively, if padding is not possible or desirable, you can pass a PixelStorage instance with the alignment overriden to 1
:
Vector2i size{173, 232}; PixelFormat format = PixelFormat::RGB8Unorm; std::size_t rowLength = size.x()*pixelFormatSize(format); Image2D image{ PixelStorage{}.setAlignment(rowLength % 4 == 0 ? 4 : 1), format, size, Containers::Array<char>{ValueInit, std::size_t(size.y()*rowLength)}};
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 such as GL::
GL::Texture2D texture; Image2D image = texture.image(0, Image2D{PixelFormat::Depth32F});
As with ImageView, this class supports extra storage parameters and implementation-specific pixel format specification. See the ImageView documentation for more information.
Pixel data access
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 Containers::
Image2D image{PixelFormat::RGB8Unorm, {128, 128}, data}; Containers::StridedArrayView2D<Color3ub> pixels = image.pixels<Color3ub>(); for(auto row: pixels.sliceSize({48, 48}, {32, 32})) { for(Color3ub& pixel: row) pixel *= 1.1f; }
This operation is available also on a ImageView, and non-compressed Trade::
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, ImageFlags<dimensions> flags = {}) explicit noexcept - Constructor.
-
Image(PixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
Containers::
Array<char>&& data, ImageFlags<dimensions> flags = {}) 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, ImageFlags<dimensions> flags = {}) 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, ImageFlags<dimensions> flags = {}) 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, ImageFlags<dimensions> flags = {}) 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, ImageFlags<dimensions> flags = {}) 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, ImageFlags<dimensions> flags = {}) 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, ImageFlags<dimensions> flags = {}) 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 BasicImageView<dimensions>() const
- Conversion to a view.
- operator BasicMutableImageView<dimensions>() new in 2019.10
- Conversion to a mutable view.
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 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 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>> - Image data properties.
-
auto data() & -> Containers::
ArrayView<char> - Raw image data.
-
auto data() const & -> Containers::
ArrayView<const char> -
auto data() && -> Containers::
Array<char> new in 2019.10 - Raw image data from a r-value.
-
auto data() const && -> Containers::
Array<char> deleted new in 2019.10 -
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() -> Containers::
StridedArrayView<dimensions+1, char> new in 2019.10 - Pixel data.
-
auto pixels() const -> Containers::
StridedArrayView<dimensions+1, const char> -
template<class T>auto pixels() -> Containers::
StridedArrayView<dimensions, T> new in 2019.10 - Pixel data in a concrete type.
-
template<class T>auto pixels() const -> Containers::
StridedArrayView<dimensions, const T> new in 2019.10 -
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,
ImageFlags<dimensions> flags = {}) explicit noexcept
Constructor.
Parameters | |
---|---|
storage | Storage of pixel data |
format | Format of pixel data |
size | Image size |
data | Image data |
flags | Image layout flags |
The data
array is expected to be of proper size for given parameters. For a 3D image, if flags
contain ImageFlag3D::size
is expected to match its restrictions.
template<UnsignedInt dimensions>
Magnum:: Image<dimensions>:: Image(PixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: Array<char>&& data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Constructor.
Parameters | |
---|---|
format | Format of pixel data |
size | Image size |
data | Image data |
flags | Image layout flags |
Equivalent to calling Image(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::
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, data pointer to nullptr
and data layout flags are empty. 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,
ImageFlags<dimensions> flags = {}) 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, in bytes |
size | Image size, in pixels |
data | Image data |
flags | Image layout flags |
Unlike with Image(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::format
in PixelFormat.
The data
array is expected to be of proper size for given parameters. For a 3D image, if flags
contain ImageFlag3D::size
is expected to match its restrictions.
template<UnsignedInt dimensions>
Magnum:: Image<dimensions>:: Image(PixelStorage storage,
PixelFormat format,
UnsignedInt formatExtra,
UnsignedInt pixelSize,
const VectorTypeFor<dimensions, Int>& size,
Containers:: Array<char>&& data,
ImageFlags<dimensions> flags = {}) 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, in bytes |
Unlike with Image(PixelStorage, PixelFormat), 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.
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,
ImageFlags<dimensions> flags = {}) 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 |
flags | Image layout flags |
Uses ADL to find a corresponding pixelFormatSize(T, U)
overload, then calls Image(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::
template<UnsignedInt dimensions>
template<class T>
Magnum:: Image<dimensions>:: Image(PixelStorage storage,
T format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: Array<char>&& data,
ImageFlags<dimensions> flags = {}) 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 |
flags | Image layout flags |
Uses ADL to find a corresponding pixelFormatSize(T)
overload, then calls Image(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::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,
ImageFlags<dimensions> flags = {}) 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 |
flags | Image layout flags |
Equivalent to calling Image(PixelStorage, T, U, const VectorTypeFor<dimensions, Int>&, Containers::
template<UnsignedInt dimensions>
template<class T>
Magnum:: Image<dimensions>:: Image(T format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: Array<char>&& data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an image with implementation-specific pixel format.
Parameters | |
---|---|
format | Format of pixel data |
size | Image size |
data | Image data |
flags | Image layout flags |
Equivalent to calling Image(PixelStorage, T, const VectorTypeFor<dimensions, Int>&, Containers::
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 pixelFormatSize(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 pixelFormatSize(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>
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
Size of a pixel 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::
template<UnsignedInt dimensions>
Containers:: ArrayView<char> Magnum:: Image<dimensions>:: data() &
Raw 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() && new in 2019.10
Raw 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 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>
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() new in 2019.10
Pixel data.
Provides direct and easy-to-use access to image pixels. See Pixel data access 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() new in 2019.10
Pixel data in a concrete 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, const T> Magnum:: Image<dimensions>:: pixels() const 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:: 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.