This is a snapshot of a work-in-progress documentation theme. If you feel lost, miss something, or want to see the original Doxygen docs instead, head over to the archived version of this documentation page.

Magnum::CubeMapTextureArray class

Cube map texture array.

See CubeMapTexture documentation for introduction.

Usage

See Texture documentation for introduction.

Common usage is to specify each layer and face separately using setSubImage(). You have to allocate the memory for all layers and faces first by calling setStorage(). Example: array with 4 layers of cube maps, each cube map consisting of six 64x64 images, i.e. 24 layers total:

CubeMapTextureArray texture;
texture.setMagnificationFilter(Sampler::Filter::Linear)
    // ...
    .setStorage(Math::log2(64)+1, TextureFormat::RGBA8, {64, 64, 24});

for(std::size_t i = 0; i != 4; i += 6) {
    Image3D imagePositiveX(PixelFormat::RGBA, PixelType::UnsignedByte, {64, 64, 1}, data);
    // ...
    texture.setSubImage(0, Vector3i::zAxis(i+0), imagePositiveX);
    texture.setSubImage(0, Vector3i::zAxis(i+1), imageNegativeX);
    texture.setSubImage(0, Vector3i::zAxis(i+2), imagePositiveY);
    // ...
}

texture.generateMipmap();

In shader, the texture is used via samplerCubeArray, samplerCubeArrayShadow, isamplerCubeArray or usamplerCubeArray. Unlike in classic textures, coordinates for cube map texture arrays is signed four-part vector. First three parts define vector from the center of the cube which intersects with one of the six sides of the cube map, fourth part is layer in the array. See AbstractShaderProgram for more information about usage in shaders.

Base classes

class AbstractTexture
Base for textures.

Public static functions

static auto maxSize() -> Vector3i
Max supported size of one side of cube map texture array.
static auto compressedBlockSize(TextureFormat format) -> Vector2i
static auto compressedBlockDataSize(TextureFormat format) -> Int
static auto wrap(GLuint id, ObjectFlags flags = {}) -> CubeMapTextureArray
Wrap existing OpenGL cube map array texture object.

Constructors, destructors, conversion operators

CubeMapTextureArray() explicit
Constructor.
CubeMapTextureArray(NoCreateT) explicit noexcept
Construct without creating the underlying OpenGL object.

Public functions

void bindImage(Int imageUnit, Int level, Int layer, ImageAccess access, ImageFormat format)
Bind level of given texture layer to given image unit.
void bindImageLayered(Int imageUnit, Int level, ImageAccess access, ImageFormat format)
Bind level of layered texture to given image unit.
auto setBaseLevel(Int level) -> CubeMapTextureArray&
auto setMaxLevel(Int level) -> CubeMapTextureArray&
auto setMinificationFilter(Sampler::Filter filter, Sampler::Mipmap mipmap = Sampler::Mipmap::Base) -> CubeMapTextureArray&
auto setMagnificationFilter(Sampler::Filter filter) -> CubeMapTextureArray&
auto setMinLod(Float lod) -> CubeMapTextureArray&
auto setMaxLod(Float lod) -> CubeMapTextureArray&
auto setLodBias(Float bias) -> CubeMapTextureArray&
auto setWrapping(const Array2D<Sampler::Wrapping>& wrapping) -> CubeMapTextureArray&
auto setBorderColor(const Color4& color) -> CubeMapTextureArray&
auto setBorderColor(const Vector4ui& color) -> CubeMapTextureArray&
auto setBorderColor(const Vector4i& color) -> CubeMapTextureArray&
auto setMaxAnisotropy(Float anisotropy) -> CubeMapTextureArray&
auto setSRGBDecode(bool decode) -> CubeMapTextureArray&
template<char r, char g, char b, char a>
auto setSwizzle() -> CubeMapTextureArray&
auto setCompareMode(Sampler::CompareMode mode) -> CubeMapTextureArray&
auto setCompareFunction(Sampler::CompareFunction function) -> CubeMapTextureArray&
auto setDepthStencilMode(Sampler::DepthStencilMode mode) -> CubeMapTextureArray&
auto setStorage(Int levels, TextureFormat internalFormat, const Vector3i& size) -> CubeMapTextureArray&
auto imageSize(Int level) -> Vector3i
void image(Int level, Image3D& image)
auto image(Int level, Image3D&& image) -> Image3D
void image(Int level, BufferImage3D& image, BufferUsage usage)
auto image(Int level, BufferImage3D&& image, BufferUsage usage) -> BufferImage3D
void compressedImage(Int level, CompressedImage3D& image)
auto compressedImage(Int level, CompressedImage3D&& image) -> CompressedImage3D
void compressedImage(Int level, CompressedBufferImage3D& image, BufferUsage usage)
auto compressedImage(Int level, CompressedBufferImage3D&& image, BufferUsage usage) -> CompressedBufferImage3D
void subImage(Int level, const Range3Di& range, Image3D& image)
auto subImage(Int level, const Range3Di& range, Image3D&& image) -> Image3D
void subImage(Int level, const Range3Di& range, BufferImage3D& image, BufferUsage usage)
auto subImage(Int level, const Range3Di& range, BufferImage3D&& image, BufferUsage usage) -> BufferImage3D
void compressedSubImage(Int level, const Range3Di& range, CompressedImage3D& image)
auto compressedSubImage(Int level, const Range3Di& range, CompressedImage3D&& image) -> CompressedImage3D
void compressedSubImage(Int level, const Range3Di& range, CompressedBufferImage3D& image, BufferUsage usage)
auto compressedSubImage(Int level, const Range3Di& range, CompressedBufferImage3D&& image, BufferUsage usage) -> CompressedBufferImage3D
auto setImage(Int level, TextureFormat internalFormat, const ImageView3D& image) -> CubeMapTextureArray&
auto setImage(Int level, TextureFormat internalFormat, BufferImage3D& image) -> CubeMapTextureArray&
auto setImage(Int level, TextureFormat internalFormat, BufferImage3D&& image) -> CubeMapTextureArray&
auto setCompressedImage(Int level, const CompressedImageView3D& image) -> CubeMapTextureArray&
auto setCompressedImage(Int level, CompressedBufferImage3D& image) -> CubeMapTextureArray&
auto setCompressedImage(Int level, CompressedBufferImage3D&& image) -> CubeMapTextureArray&
auto setSubImage(Int level, const Vector3i& offset, const ImageView3D& image) -> CubeMapTextureArray&
auto setSubImage(Int level, const Vector3i& offset, BufferImage3D& image) -> CubeMapTextureArray&
auto setSubImage(Int level, const Vector3i& offset, BufferImage3D&& image) -> CubeMapTextureArray&
auto setCompressedSubImage(Int level, const Vector3i& offset, const CompressedImageView3D& image) -> CubeMapTextureArray&
auto setCompressedSubImage(Int level, const Vector3i& offset, CompressedBufferImage3D& image) -> CubeMapTextureArray&
auto setCompressedSubImage(Int level, const Vector3i& offset, CompressedBufferImage3D&& image) -> CubeMapTextureArray&
auto generateMipmap() -> CubeMapTextureArray&
void invalidateImage(Int level)
void invalidateSubImage(Int level, const Vector3i& offset, const Vector3i& size)

Function documentation

static Vector3i Magnum::CubeMapTextureArray::maxSize()

Max supported size of one side of cube map texture array.

The result is cached, repeated queries don't result in repeated OpenGL calls. If ARB_texture_cube_map_array (part of OpenGL 4.0) is not available, returns zero vector.

static Vector2i Magnum::CubeMapTextureArray::compressedBlockSize(TextureFormat format)

Compressed block size.

See Texture::compressedBlockSize() for more information.

static Int Magnum::CubeMapTextureArray::compressedBlockDataSize(TextureFormat format)

Compressed block data size.

See Texture::compressedBlockDataSize() for more information.

static CubeMapTextureArray Magnum::CubeMapTextureArray::wrap(GLuint id, ObjectFlags flags = {})

Wrap existing OpenGL cube map array texture object.

Parameters
id OpenGL cube map array texture ID
flags Object creation flags

The id is expected to be of an existing OpenGL texture object with target GL_TEXTURE_CUBE_MAP_ARRAY. Unlike texture created using constructor, the OpenGL object is by default not deleted on destruction, use flags for different behavior.

Magnum::CubeMapTextureArray::CubeMapTextureArray() explicit

Constructor.

Creates new OpenGL texture object. If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is created on first use.

Magnum::CubeMapTextureArray::CubeMapTextureArray(NoCreateT) explicit noexcept

Construct without creating the underlying OpenGL object.

The constructed instance is equivalent to moved-from state. Useful in cases where you will overwrite the instance later anyway. Move another object over it to make it useful.

This function can be safely used for constructing (and later destructing) objects even without any OpenGL context being active.

void Magnum::CubeMapTextureArray::bindImage(Int imageUnit, Int level, Int layer, ImageAccess access, ImageFormat format)

Bind level of given texture layer to given image unit.

Parameters
imageUnit Image unit
level Texture level
layer Texture layer
access Image access
format Image format

Layer is equivalent to layer * 6 + number of texture face, i.e. +X is 0 and so on, in order of (+X, -X, +Y, -Y, +Z, -Z).

void Magnum::CubeMapTextureArray::bindImageLayered(Int imageUnit, Int level, ImageAccess access, ImageFormat format)

Bind level of layered texture to given image unit.

Parameters
imageUnit Image unit
level Texture level
access Image access
format Image format

CubeMapTextureArray& Magnum::CubeMapTextureArray::setBaseLevel(Int level)

Returns Reference to self (for method chaining)

Set base mip level. See Texture::setBaseLevel() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setMaxLevel(Int level)

Returns Reference to self (for method chaining)

Set max mip level. See Texture::setMaxLevel() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setMinificationFilter(Sampler::Filter filter, Sampler::Mipmap mipmap = Sampler::Mipmap::Base)

Returns Reference to self (for method chaining)

Set minification filter. See Texture::setMinificationFilter() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setMagnificationFilter(Sampler::Filter filter)

Returns Reference to self (for method chaining)

Set magnification filter. See Texture::setMagnificationFilter() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setMinLod(Float lod)

Returns Reference to self (for method chaining)

Set minimum level-of-detail parameter. See Texture::setMinLod() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setMaxLod(Float lod)

Returns Reference to self (for method chaining)

Set maximum level-of-detail parameter. See Texture::setMaxLod() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setLodBias(Float bias)

Returns Reference to self (for method chaining)

Set level-of-detail bias. See Texture::setLodBias() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setWrapping(const Array2D<Sampler::Wrapping>& wrapping)

Returns Reference to self (for method chaining)

Set wrapping. See Texture::setWrapping() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setBorderColor(const Color4& color)

Returns Reference to self (for method chaining)

Set border color. See Texture::setBorderColor(const Color4&) for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setBorderColor(const Vector4ui& color)

Returns Reference to self (for method chaining)

Set border color for integer texture. See Texture::setBorderColor(const Vector4ui&) for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setBorderColor(const Vector4i& color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setMaxAnisotropy(Float anisotropy)

Returns Reference to self (for method chaining)

Set max anisotropy. See Texture::setMaxAnisotropy() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setSRGBDecode(bool decode)

Returns Reference to self (for method chaining)

Set sRGB decoding. See Texture::setSRGBDecode() for more information.

template<char r, char g, char b, char a>
CubeMapTextureArray& Magnum::CubeMapTextureArray::setSwizzle()

Returns Reference to self (for method chaining)

Set component swizzle. See Texture::setSwizzle() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setCompareMode(Sampler::CompareMode mode)

Returns Reference to self (for method chaining)

Set depth texture comparison mode. See Texture::setCompareMode() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setCompareFunction(Sampler::CompareFunction function)

Returns Reference to self (for method chaining)

Set depth texture comparison function. See Texture::setCompareFunction() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setDepthStencilMode(Sampler::DepthStencilMode mode)

Returns Reference to self (for method chaining)

Set depth/stencil texture mode. See Texture::setDepthStencilMode() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setStorage(Int levels, TextureFormat internalFormat, const Vector3i& size)

Returns Reference to self (for method chaining)

Set storage. Z coordinate of size must be multiple of 6.

See Texture::setStorage() for more information.

Vector3i Magnum::CubeMapTextureArray::imageSize(Int level)

Image size in given mip level.

See Texture::imageSize() for more information.

void Magnum::CubeMapTextureArray::image(Int level, Image3D& image)

Read given mip level of texture to image.

See Texture::image(Int, Image&) for more information.

Image3D Magnum::CubeMapTextureArray::image(Int level, Image3D&& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Convenience alternative to the above, example usage: Image3D image = texture.image(0, {PixelFormat::RGBA, PixelType::UnsignedByte});

void Magnum::CubeMapTextureArray::image(Int level, BufferImage3D& image, BufferUsage usage)

Read given mip level of texture to buffer image.

See Texture::image(Int, BufferImage&, BufferUsage) for more information.

BufferImage3D Magnum::CubeMapTextureArray::image(Int level, BufferImage3D&& image, BufferUsage usage)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Convenience alternative to the above, example usage: BufferImage3D image = texture.image(0, {PixelFormat::RGBA, PixelType::UnsignedByte}, BufferUsage::StaticRead);

void Magnum::CubeMapTextureArray::compressedImage(Int level, CompressedImage3D& image)

Read given mip level of compressed texture to image.

See Texture::compressedImage(Int, CompressedImage&) for more information.

CompressedImage3D Magnum::CubeMapTextureArray::compressedImage(Int level, CompressedImage3D&& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Convenience alternative to the above, example usage: CompressedImage3D image = texture.compressedImage(0, {});

void Magnum::CubeMapTextureArray::compressedImage(Int level, CompressedBufferImage3D& image, BufferUsage usage)

Read given mip level of compressed texture to buffer image.

See Texture::compressedImage(Int, CompressedBufferImage&, BufferUsage) for more information.

CompressedBufferImage3D Magnum::CubeMapTextureArray::compressedImage(Int level, CompressedBufferImage3D&& image, BufferUsage usage)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Convenience alternative to the above, example usage: CompressedBufferImage3D image = texture.compressedImage(0, {}, BufferUsage::StaticRead);

void Magnum::CubeMapTextureArray::subImage(Int level, const Range3Di& range, Image3D& image)

Read range of given texture mip level to image.

See Texture::subImage(Int, const RangeTypeFor<dimensions, Int>&, Image&) for more information.

Image3D Magnum::CubeMapTextureArray::subImage(Int level, const Range3Di& range, Image3D&& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Convenience alternative to the above, example usage: Image3D image = texture.subImage(0, range, {PixelFormat::RGBA, PixelType::UnsignedByte});

void Magnum::CubeMapTextureArray::subImage(Int level, const Range3Di& range, BufferImage3D& image, BufferUsage usage)

Read range of given texture mip level to buffer image.

See Texture::subImage(Int, const RangeTypeFor<dimensions, Int>&, BufferImage&, BufferUsage) for more information.

BufferImage3D Magnum::CubeMapTextureArray::subImage(Int level, const Range3Di& range, BufferImage3D&& image, BufferUsage usage)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Convenience alternative to the above, example usage: BufferImage3D image = texture.subImage(0, range, {PixelFormat::RGBA, PixelType::UnsignedByte}, BufferUsage::StaticRead);

void Magnum::CubeMapTextureArray::compressedSubImage(Int level, const Range3Di& range, CompressedImage3D& image)

Read range of given compressed texture mip level to image.

See Texture::compressedSubImage(Int, const RangeTypeFor<dimensions, Int>&, CompressedImage&) for more information.

CompressedImage3D Magnum::CubeMapTextureArray::compressedSubImage(Int level, const Range3Di& range, CompressedImage3D&& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Convenience alternative to the above, example usage: CompressedImage3D image = texture.compressedSubImage(0, range, {});

void Magnum::CubeMapTextureArray::compressedSubImage(Int level, const Range3Di& range, CompressedBufferImage3D& image, BufferUsage usage)

Read range of given compressed texture mip level to buffer image.

See Texture::compressedSubImage(Int, const RangeTypeFor<dimensions, Int>&, CompressedBufferImage&, BufferUsage) for more information.

CompressedBufferImage3D Magnum::CubeMapTextureArray::compressedSubImage(Int level, const Range3Di& range, CompressedBufferImage3D&& image, BufferUsage usage)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Convenience alternative to the above, example usage: CompressedBufferImage3D image = texture.compressedSubImage(0, range, {}, BufferUsage::StaticRead);

CubeMapTextureArray& Magnum::CubeMapTextureArray::setImage(Int level, TextureFormat internalFormat, const ImageView3D& image)

Returns Reference to self (for method chaining)

Set image data. Sets texture image data from three-dimensional image for all cube faces for all layers. Each group of 6 2D images is one cube map layer, thus Z coordinate of image size must be multiple of 6. The images are in order of (+X, -X, +Y, -Y, +Z, -Z).

See Texture::setImage() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setImage(Int level, TextureFormat internalFormat, BufferImage3D& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setImage(Int level, TextureFormat internalFormat, BufferImage3D&& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setCompressedImage(Int level, const CompressedImageView3D& image)

Returns Reference to self (for method chaining)

Set compressed image data. Sets texture image data from three-dimensional image for all cube faces for all layers. Each group of 6 2D images is one cube map layer, thus Z coordinate of image size must be multiple of 6. The images are in order of (+X, -X, +Y, -Y, +Z, -Z).

See Texture::setCompressedImage() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setCompressedImage(Int level, CompressedBufferImage3D& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setCompressedImage(Int level, CompressedBufferImage3D&& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setSubImage(Int level, const Vector3i& offset, const ImageView3D& image)

Returns Reference to self (for method chaining)

Set image subdata. Z coordinate is equivalent to layer * 6 + number of texture face, i.e. +X is 0 and so on, in order of (+X, -X, +Y, -Y, +Z, -Z).

See Texture::setSubImage() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setSubImage(Int level, const Vector3i& offset, BufferImage3D& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setSubImage(Int level, const Vector3i& offset, BufferImage3D&& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setCompressedSubImage(Int level, const Vector3i& offset, const CompressedImageView3D& image)

Returns Reference to self (for method chaining)

Set compressed image subdata. Z coordinate is equivalent to layer * 6 + number of texture face, i.e. +X is 0 and so on, in order of (+X, -X, +Y, -Y, +Z, -Z).

See Texture::setCompressedSubImage() for more information.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setCompressedSubImage(Int level, const Vector3i& offset, CompressedBufferImage3D& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CubeMapTextureArray& Magnum::CubeMapTextureArray::setCompressedSubImage(Int level, const Vector3i& offset, CompressedBufferImage3D&& image)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CubeMapTextureArray& Magnum::CubeMapTextureArray::generateMipmap()

Returns Reference to self (for method chaining)

Generate mipmap. See Texture::generateMipmap() for more information.

void Magnum::CubeMapTextureArray::invalidateImage(Int level)

Invalidate texture image.

See Texture::invalidateImage() for more information.

void Magnum::CubeMapTextureArray::invalidateSubImage(Int level, const Vector3i& offset, const Vector3i& size)

Invalidate texture subimage.

Z coordinate is equivalent to layer * 6 + number of texture face, i.e. +X is 0 and so on, in order of (+X, -X, +Y, -Y, +Z, -Z).

See Texture::invalidateSubImage() for more information.