#include <Magnum/ImageView.h>
template<UnsignedInt dimensions, class T>
ImageView class
Image view.
Non-owning view on multi-dimensional image data together with layout and pixel format description. Unlike Image, this class doesn't take ownership of the data, so it is targeted for wrapping data that is either stored in stack/constant memory (and shouldn't be deleted) or is managed by something else.
This class can act as drop-in replacement for Image or Trade::
Basic usage
The view is created from a PixelFormat, size in pixels and a data view:
ImageView2D view{PixelFormat::RGBA8Unorm, {512, 256}, data};
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. While the recommended way is to pad the row data to satisfy the alignment similarly as shown in Image usage docs, but with views it's more likely that you have to adapt to a layout of an existing data array by passing a PixelStorage instance with the alignment value overriden if needed:
PixelFormat format = …; Vector2i size = …; std::size_t rowLength = size.x()*pixelFormatSize(format); ImageView2D view{ PixelStorage{}.setAlignment(rowLength % 4 == 0 ? 4 : 1), format, size, tightlyPackedData};
It's also possible to create an empty view and assign the memory later. That is useful for example in case of multi-buffered video streaming, where each frame has the same properties but a different memory location:
ImageView2D frame{PixelFormat::RGBA8Unorm, {512, 256}}; frame.setData(evenFrameData); // Use even frame data ... frame.setData(oddFrameData); // Use odd frame data ...
The PixelStorage also allows for specifying arbitrary image slices by passing appropriate row length, image height and skip parameters. In the following snippet, the view is the center 25x25 sub-rectangle of a 75x75 8-bit RGB image (with tightly packed rows again):
ImageView2D view{ PixelStorage{} .setAlignment(1) .setRowLength(75) .setSkip({25, 25, 0}), PixelFormat::RGBA8Unorm, {25, 25}, data};
Image views provides pixel data access via pixels() in the same way as the Image class. See its documentation for more information.
Data mutability
The ImageView2D type and related one- and three-dimensional variants only provide immutable access to the referenced data, as that's the most common use case. In order to be able to modify the data (for example in order to read into a pre-allocated memory), use MutableImageView2D and friends instead. Image and Trade::
Implementation-specific formats
For known graphics APIs, there's a set of utility functions converting from PixelFormat to implementation-specific format identifiers and such conversion is done implicitly when passing the view to a particular API. See the enum documentation and documentation of its values for more information.
In some cases, for example when there's no corresponding generic format available, it's desirable to specify the pixel format using implementation-specific identifiers directly. In case of OpenGL that would be the GL::
ImageView2D view{GL::PixelFormat::DepthComponent, GL::PixelType::UnsignedInt, {512, 256}, data};
In such cases, pixel size is calculated using either pixelFormatSize(T, U)
or pixelFormatSize(T)
that is found using ADL, with T
and U
corresponding to types of passed arguments. The implementation-specific format is wrapped in PixelFormat using pixelFormatWrap() and format() returns the wrapped value. In order to distinguish if the format is wrapped, use isPixelFormatImplementationSpecific() and then extract the implementation-specific identifier using pixelFormatUnwrap(). For APIs that have an additional format specifier (such as OpenGL), the second value is stored verbatim in formatExtra():
auto format = pixelFormatUnwrap<GLenum>(view.format()); auto type = GLenum(view.formatExtra());
As a final fallback, types for which the pixelFormatSize()
overload is not available can be specified directly together with pixel size. In particular, pixel size of 0
will cause the image to be treated as fully opaque data, disabling all slicing operations. The following shows a image view using Metal-specific format identifier:
/* Default pixel storage, 8-bit sRGB + alpha, four bytes per pixel */ ImageView2D view{{}, MTLPixelFormatRGBA8Unorm_sRGB, {}, 4, {256, 256}, data};
Public types
- enum (anonymous): UnsignedInt { Dimensions = dimensions }
- using Type = T
- Raw data type.
-
using ErasedType = std::
conditional<std:: is_const<T>::value, const void, void>::type - Erased data type.
Constructors, destructors, conversion operators
-
ImageView(PixelStorage storage,
PixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Constructor.
-
ImageView(PixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Constructor.
- ImageView(PixelStorage storage, PixelFormat format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view.
- ImageView(PixelFormat format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view.
-
ImageView(PixelStorage storage,
UnsignedInt format,
UnsignedInt formatExtra,
UnsignedInt pixelSize,
const VectorTypeFor<dimensions, Int>& size,
Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Construct an image view with implementation-specific pixel format.
-
ImageView(PixelStorage storage,
PixelFormat format,
UnsignedInt formatExtra,
UnsignedInt pixelSize,
const VectorTypeFor<dimensions, Int>& size,
Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - ImageView(PixelStorage storage, UnsignedInt format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view with implementation-specific pixel format.
- ImageView(PixelStorage storage, PixelFormat format, UnsignedInt formatExtra, UnsignedInt pixelSize, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
-
template<class U, class V>ImageView(PixelStorage storage, U format, V formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Construct an image view with implementation-specific pixel format.
-
template<class U>ImageView(PixelStorage storage, U format, const VectorTypeFor<dimensions, Int>& size, Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Construct an image view with implementation-specific pixel format.
-
template<class U, class V>ImageView(U format, V formatExtra, const VectorTypeFor<dimensions, Int>& size, Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Construct an image view with implementation-specific pixel format.
-
template<class U>ImageView(U format, const VectorTypeFor<dimensions, Int>& size, Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Construct an image view with implementation-specific pixel format.
-
template<class U, class V>ImageView(PixelStorage storage, U format, V formatExtra, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view with implementation-specific pixel format.
-
template<class U>ImageView(PixelStorage storage, U format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view with implementation-specific pixel format.
-
template<class U, class V>ImageView(U format, V formatExtra, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view with implementation-specific pixel format.
-
template<class U>ImageView(U format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view with implementation-specific pixel format.
-
template<UnsignedInt otherDimensions, class = typename std::ImageView(const ImageView<otherDimensions, T>& other, ImageFlags<dimensions> flags = {}) noexcept new in 2019.10
enable_if<(otherDimensions <dimensions)>::type> - Construct from a view of lower dimension count.
-
template<class U, class = typename std::ImageView(const ImageView<dimensions, U>& other) noexcept new in 2019.10
enable_if<std:: is_const<T>::value&& !std:: is_const<U>::value>::type> - Convert a mutable view to a const one.
Public functions
- 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>& constexpr
- Image size in pixels.
-
auto dataProperties() const -> std::
pair<VectorTypeFor<dimensions, std:: size_t>, VectorTypeFor<dimensions, std:: size_t>> - Image data properties.
-
auto data() const -> Containers::
ArrayView<Type> - Raw image data.
-
template<class U>auto data() const -> const U* deprecated in 2019.10
- Image data in a particular type.
-
void setData(Containers::
ArrayView<ErasedType> data) - Set image data.
-
auto pixels() const -> Containers::
StridedArrayView<dimensions+1, Type> new in 2019.10 - Pixel data.
-
template<class U>auto pixels() const -> Containers::
StridedArrayView<dimensions, typename std:: conditional<std:: is_const<Type>::value, typename std:: add_const<U>::type, U>::type> new in 2019.10 - Pixel data in a concrete type.
Enum documentation
template<UnsignedInt dimensions, class T>
enum Magnum:: ImageView<dimensions, T>:: (anonymous): UnsignedInt
Enumerators | |
---|---|
Dimensions |
Image dimension count |
Typedef documentation
template<UnsignedInt dimensions, class T>
typedef T Magnum:: ImageView<dimensions, T>:: Type
Raw data type.
const char
for BasicImageView and char
for BasicMutableImageView. See also ErasedType.
template<UnsignedInt dimensions, class T>
typedef std:: conditional<std:: is_const<T>::value, const void, void>::type Magnum:: ImageView<dimensions, T>:: ErasedType
Erased data type.
const void
for BasicImageView and const void
for BasicMutableImageView. See also Type.
Function documentation
template<UnsignedInt dimensions, class T>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelStorage storage,
PixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> 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, class T>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> 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 ImageView(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::
template<UnsignedInt dimensions, class T>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelStorage storage,
PixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view.
Parameters | |
---|---|
storage | Storage of pixel data |
format | Format of pixel data |
size | Image size |
flags | Image layout flags |
Data pointer is set to nullptr
, call setData() to assign a memory view to the image. For a 3D image, if flags
contain ImageFlag3D::size
is expected to match its restrictions.
template<UnsignedInt dimensions, class T>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view.
Parameters | |
---|---|
format | Format of pixel data |
size | Image size |
flags | Image layout flags |
Equivalent to calling ImageView(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, ImageFlags<dimensions>) with default-constructed PixelStorage.
template<UnsignedInt dimensions, class T>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelStorage storage,
UnsignedInt format,
UnsignedInt formatExtra,
UnsignedInt pixelSize,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an image view 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 ImageView(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, class T>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelStorage storage,
PixelFormat format,
UnsignedInt formatExtra,
UnsignedInt pixelSize,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> 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, class T>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelStorage storage,
UnsignedInt format,
UnsignedInt formatExtra,
UnsignedInt pixelSize,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view 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 |
flags | Image layout flags |
Unlike with ImageView(PixelStorage, PixelFormat, const VectorTypeFor<dimensions, Int>&, ImageFlags<dimensions>), 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.
Data pointer is set to nullptr
, call setData() to assign a memory view to the image. For a 3D image, if flags
contain ImageFlag3D::size
is expected to match its restrictions.
template<UnsignedInt dimensions, class T>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelStorage storage,
PixelFormat format,
UnsignedInt formatExtra,
UnsignedInt pixelSize,
const VectorTypeFor<dimensions, Int>& size,
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, class T>
template<class U, class V>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelStorage storage,
U format,
V formatExtra,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an image view 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 ImageView(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::
template<UnsignedInt dimensions, class T>
template<class U>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelStorage storage,
U format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an image view 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 ImageView(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt, const VectorTypeFor<dimensions, Int>&, Containers::formatExtra
set to 0
.
template<UnsignedInt dimensions, class T>
template<class U, class V>
Magnum:: ImageView<dimensions, T>:: ImageView(U format,
V formatExtra,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an image view 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 ImageView(PixelStorage, U, V, const VectorTypeFor<dimensions, Int>&, Containers::
template<UnsignedInt dimensions, class T>
template<class U>
Magnum:: ImageView<dimensions, T>:: ImageView(U format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an image view with implementation-specific pixel format.
Parameters | |
---|---|
format | Format of pixel data |
size | Image size |
data | Image data |
flags | Image layout flags |
Equivalent to calling ImageView(PixelStorage, U, const VectorTypeFor<dimensions, Int>&, Containers::
template<UnsignedInt dimensions, class T>
template<class U, class V>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelStorage storage,
U format,
V formatExtra,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view with implementation-specific pixel format.
Parameters | |
---|---|
storage | Storage of pixel data |
format | Format of pixel data |
formatExtra | Additional pixel format specifier |
size | Image size |
flags | Image layout flags |
Uses ADL to find a corresponding pixelFormatSize(T, U)
overload, then calls ImageView(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt, const VectorTypeFor<dimensions, Int>&, ImageFlags<dimensions>) with calculated pixel size.
Data pointer is set to nullptr
, call setData() to assign a memory view to the image.
template<UnsignedInt dimensions, class T>
template<class U>
Magnum:: ImageView<dimensions, T>:: ImageView(PixelStorage storage,
U format,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view with implementation-specific pixel format.
Parameters | |
---|---|
storage | Storage of pixel data |
format | Format of pixel data |
size | Image size |
flags | Image layout flags |
Uses ADL to find a corresponding pixelFormatSize(T)
overload, then calls ImageView(PixelStorage, UnsignedInt, UnsignedInt, UnsignedInt, const VectorTypeFor<dimensions, Int>&, ImageFlags<dimensions>) with calculated pixel size and formatExtra
set to 0
.
Data pointer is set to nullptr
, call setData() to assign a memory view to the image.
template<UnsignedInt dimensions, class T>
template<class U, class V>
Magnum:: ImageView<dimensions, T>:: ImageView(U format,
V formatExtra,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view with implementation-specific pixel format.
Parameters | |
---|---|
format | Format of pixel data |
formatExtra | Additional pixel format specifier |
size | Image size |
flags | Image layout flags |
Equivalent to calling ImageView(PixelStorage, U, V, const VectorTypeFor<dimensions, Int>&, Containers::
template<UnsignedInt dimensions, class T>
template<class U>
Magnum:: ImageView<dimensions, T>:: ImageView(U format,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view with implementation-specific pixel format.
Parameters | |
---|---|
format | Format of pixel data |
size | Image size |
flags | Image layout flags |
Equivalent to calling ImageView(PixelStorage, U, const VectorTypeFor<dimensions, Int>&, ImageFlags<dimensions>) with default-constructed PixelStorage.
template<UnsignedInt dimensions, class T>
template<UnsignedInt otherDimensions, class = typename std:: enable_if<(otherDimensions <dimensions)>::type>
Magnum:: ImageView<dimensions, T>:: ImageView(const ImageView<otherDimensions, T>& other,
ImageFlags<dimensions> flags = {}) noexcept new in 2019.10
Construct from a view of lower dimension count.
Size in the new dimension(s) is set to 1
. Original image flags are preserved, except for ImageFlag2D::flags
parameter to add arbitrary other flags.
template<UnsignedInt dimensions, class T>
PixelFormat Magnum:: ImageView<dimensions, T>:: 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, class T>
UnsignedInt Magnum:: ImageView<dimensions, T>:: 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, class T>
UnsignedInt Magnum:: ImageView<dimensions, T>:: pixelSize() const
Size of a pixel in bytes.
template<UnsignedInt dimensions, class T>
std:: pair<VectorTypeFor<dimensions, std:: size_t>, VectorTypeFor<dimensions, std:: size_t>> Magnum:: ImageView<dimensions, T>:: dataProperties() const
Image data properties.
See PixelStorage::
template<UnsignedInt dimensions, class T>
Containers:: ArrayView<Type> Magnum:: ImageView<dimensions, T>:: data() const
Raw image data.
template<UnsignedInt dimensions, class T>
template<class U>
const U* Magnum:: ImageView<dimensions, T>:: data() const
Image data in a particular type.
template<UnsignedInt dimensions, class T>
void Magnum:: ImageView<dimensions, T>:: setData(Containers:: ArrayView<ErasedType> data)
Set image data.
The data array is expected to be of proper size for parameters specified in the constructor.
template<UnsignedInt dimensions, class T>
Containers:: StridedArrayView<dimensions+1, Type> Magnum:: ImageView<dimensions, T>:: pixels() const new in 2019.10
Pixel data.
Provides direct and easy-to-use access to image pixels. See Pixel data access for more information. If the view is empty (with data() being nullptr
), returns nullptr
as well.
template<UnsignedInt dimensions, class T>
template<class U>
Containers:: StridedArrayView<dimensions, typename std:: conditional<std:: is_const<Type>::value, typename std:: add_const<U>::type, U>::type> Magnum:: ImageView<dimensions, T>:: pixels() const 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. If the view is empty (with data() being nullptr
), returns nullptr
as well. See also Pixel data access for more information.