#include <Magnum/ImageView.h>
template<UnsignedInt dimensions, class T>
CompressedImageView class
Compressed image view.
Non-owning view on multi-dimensional compressed image data together with layout and compressed block format description. Unlike CompressedImage, 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 CompressedImage or Trade::
Basic usage
The view is created from a CompressedPixelFormat, size in pixels and a data view:
CompressedImageView2D view{CompressedPixelFormat::Bc1RGBUnorm, {512, 256}, data};
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:
CompressedImageView2D frame{CompressedPixelFormat::Bc1RGBUnorm, {512, 256}}; frame.setData(evenFrameData); // Use even frame data ... frame.setData(oddFrameData); // Use odd frame data ...
It's possible to have views on image sub-rectangles, 3D texture slices or images with over-aligned rows by passing a particular CompressedPixelStorage as first parameter. In the following snippet, the view is the bottom-right 32x32 sub-rectangle of a 64x64 image:
CompressedImageView2D view{ CompressedPixelStorage{} .setRowLength(64) .setCompressedBlockSize({4, 4, 1}) .setCompressedBlockDataSize(8) .setSkip({32, 32, 0}), CompressedPixelFormat::Bc1RGBUnorm, {32, 32}, data};
Data mutability
When using types derived from BasicCompressedImageView (e.g. CompressedImageView2D), the viewed data are immutable. This is the most common use case. In order to be able to mutate the underlying data (for example in order to read into a pre-allocated memory), use BasicMutableCompressedImageView (e.g. MutableCompressedImageView2D) instead. CompressedImage and Trade::
Implementation-specific formats
For known graphics APIs, there's a set of utility functions converting from CompressedPixelFormat 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 GL::
CompressedImageView2D view{GL::CompressedPixelFormat::SignedRGRgtc2, {512, 256}, data};
In such cases, the implementation-specific format is wrapped in CompressedPixelFormat using compressedPixelFormatWrap() and format() returns the wrapped value. In order to distinguish if the format is wrapped, use isCompressedPixelFormatImplementationSpecific() and then extract the implementation-specific identifier using compressedPixelFormatUnwrap():
auto format = compressedPixelFormatUnwrap<GLenum>(view.format());
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
-
CompressedImageView(CompressedPixelStorage storage,
CompressedPixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Constructor.
-
CompressedImageView(CompressedPixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Constructor.
- CompressedImageView(CompressedPixelStorage storage, CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view.
- CompressedImageView(CompressedPixelFormat format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view.
-
template<class U>CompressedImageView(CompressedPixelStorage storage, U format, const VectorTypeFor<dimensions, Int>& size, Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Construct an image view with implementation-specific format.
-
template<class U>CompressedImageView(U format, const VectorTypeFor<dimensions, Int>& size, Containers::
ArrayView<ErasedType> data, ImageFlags<dimensions> flags = {}) explicit noexcept - Construct an image view with implementation-specific format.
-
template<class U>CompressedImageView(CompressedPixelStorage storage, U format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view with implementation-specific format.
-
template<class U>CompressedImageView(U format, const VectorTypeFor<dimensions, Int>& size, ImageFlags<dimensions> flags = {}) explicit noexcept
- Construct an empty view with implementation-specific format.
-
template<UnsignedInt otherDimensions, class = typename std::CompressedImageView(const CompressedImageView<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::CompressedImageView(const CompressedImageView<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 -> CompressedPixelStorage
- Storage of compressed pixel data.
- auto format() const -> CompressedPixelFormat
- Format of compressed pixel data.
- 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>> - Compressed 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.
Enum documentation
template<UnsignedInt dimensions, class T>
enum Magnum:: CompressedImageView<dimensions, T>:: (anonymous): UnsignedInt
Enumerators | |
---|---|
Dimensions |
Image dimension count |
Typedef documentation
template<UnsignedInt dimensions, class T>
typedef T Magnum:: CompressedImageView<dimensions, T>:: Type
Raw data type.
const char
for CompressedImageView1D / CompressedImageView2D / CompressedImageView3D and char
for MutableCompressedImageView1D / MutableCompressedImageView2D / MutableCompressedImageView3D. See also ErasedType.
template<UnsignedInt dimensions, class T>
typedef std:: conditional<std:: is_const<T>::value, const void, void>::type Magnum:: CompressedImageView<dimensions, T>:: ErasedType
Erased data type.
const void
for CompressedImageView1D / CompressedImageView2D / CompressedImageView3D and const void
for MutableCompressedImageView1D / MutableCompressedImageView2D / MutableCompressedImageView3D. See also Type.
Function documentation
template<UnsignedInt dimensions, class T>
Magnum:: CompressedImageView<dimensions, T>:: CompressedImageView(CompressedPixelStorage storage,
CompressedPixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Constructor.
Parameters | |
---|---|
storage | Storage of compressed pixel data |
format | Format of compressed pixel data |
size | Image size |
data | Image data |
flags | Image layout flags |
For a 3D image, if flags
contain ImageFlag3D::size
is expected to match its restrictions.
template<UnsignedInt dimensions, class T>
Magnum:: CompressedImageView<dimensions, T>:: CompressedImageView(CompressedPixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Constructor.
Parameters | |
---|---|
format | Format of compressed pixel data |
size | Image size |
data | Image data |
flags | Image layout flags |
Equivalent to calling CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::
template<UnsignedInt dimensions, class T>
Magnum:: CompressedImageView<dimensions, T>:: CompressedImageView(CompressedPixelStorage storage,
CompressedPixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view.
Parameters | |
---|---|
storage | Storage of compressed pixel data |
format | Format of compressed 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:: CompressedImageView<dimensions, T>:: CompressedImageView(CompressedPixelFormat format,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view.
Parameters | |
---|---|
format | Format of compressed pixel data |
size | Image size |
flags | Image layout flags |
Equivalent to calling CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, ImageFlags<dimensions>) with default-constructed CompressedPixelStorage.
template<UnsignedInt dimensions, class T>
template<class U>
Magnum:: CompressedImageView<dimensions, T>:: CompressedImageView(CompressedPixelStorage storage,
U format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an image view with implementation-specific format.
Parameters | |
---|---|
storage | Storage of compressed pixel data |
format | Format of compressed pixel data |
size | Image size |
data | Image data |
flags | Image layout flags |
Uses compressedPixelFormatWrap() internally to convert format
to CompressedPixelFormat.
For a 3D image, if flags
contain ImageFlag3D::size
is expected to match its restrictions.
template<UnsignedInt dimensions, class T>
template<class U>
Magnum:: CompressedImageView<dimensions, T>:: CompressedImageView(U format,
const VectorTypeFor<dimensions, Int>& size,
Containers:: ArrayView<ErasedType> data,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an image view with implementation-specific format.
Parameters | |
---|---|
format | Format of compressed pixel data |
size | Image size |
data | Image data |
flags | Image layout flags |
Equivalent to calling CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, Containers::
template<UnsignedInt dimensions, class T>
template<class U>
Magnum:: CompressedImageView<dimensions, T>:: CompressedImageView(CompressedPixelStorage storage,
U format,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view with implementation-specific format.
Parameters | |
---|---|
storage | Storage of compressed pixel data |
format | Format of compressed pixel data |
size | Image size |
flags | Image layout flags |
Uses compressedPixelFormatWrap() internally to convert format
to CompressedPixelFormat.
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>
template<class U>
Magnum:: CompressedImageView<dimensions, T>:: CompressedImageView(U format,
const VectorTypeFor<dimensions, Int>& size,
ImageFlags<dimensions> flags = {}) explicit noexcept
Construct an empty view with implementation-specific format.
Parameters | |
---|---|
format | Format of compressed pixel data |
size | Image size |
flags | Image layout flags |
Equivalent to calling CompressedImageView(CompressedPixelStorage, CompressedPixelFormat, const VectorTypeFor<dimensions, Int>&, ImageFlags<dimensions>) with default-constructed CompressedPixelStorage.
template<UnsignedInt dimensions, class T>
template<UnsignedInt otherDimensions, class = typename std:: enable_if<(otherDimensions <dimensions)>::type>
Magnum:: CompressedImageView<dimensions, T>:: CompressedImageView(const CompressedImageView<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>
CompressedPixelFormat Magnum:: CompressedImageView<dimensions, T>:: format() 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.
template<UnsignedInt dimensions, class T>
std:: pair<VectorTypeFor<dimensions, std:: size_t>, VectorTypeFor<dimensions, std:: size_t>> Magnum:: CompressedImageView<dimensions, T>:: dataProperties() const
Compressed image data properties.
See CompressedPixelStorage::
template<UnsignedInt dimensions, class T>
template<class U>
const U* Magnum:: CompressedImageView<dimensions, T>:: data() const
Image data in a particular type.
template<UnsignedInt dimensions, class T>
void Magnum:: CompressedImageView<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.