template<UnsignedInt dimensions>
Magnum::GL::Texture class

Texture.

Contents

Template class for one- to three-dimensional textures. See also AbstractTexture documentation for more information.

Usage

Common usage is to fully configure all texture parameters and then set the data from e.g. Image. Example configuration of high quality texture with trilinear anisotropic filtering, i.e. the best you can ask for:

ImageView2D image(PixelFormat::RGBA8Unorm, {4096, 4096}, data);

GL::Texture2D texture;
texture.setMagnificationFilter(GL::SamplerFilter::Linear)
    .setMinificationFilter(GL::SamplerFilter::Linear, GL::SamplerMipmap::Linear)
    .setWrapping(GL::SamplerWrapping::ClampToEdge)
    .setMaxAnisotropy(GL::Sampler::maxMaxAnisotropy())
    .setStorage(Math::log2(4096)+1, GL::TextureFormat::RGBA8, {4096, 4096})
    .setSubImage(0, {}, image)
    .generateMipmap();

In shader, the texture is used via sampler1D / sampler2D / sampler3D, sampler1DShadow / sampler2DShadow / sampler3DShadow, isampler1D / isampler2D / isampler3D or usampler1D / usampler2D / usampler3D. See AbstractShaderProgram documentation for more information about usage in shaders.

Base classes

class AbstractTexture
Base for textures.

Public types

enum (anonymous): UnsignedInt { Dimensions = dimensions }

Public static functions

static auto maxSize() -> VectorTypeFor<dimensions, Int>
Max supported texture size.
static auto compressedBlockSize(TextureFormat format) -> VectorTypeFor<dimensions, Int>
Compressed block size.
static auto compressedBlockDataSize(TextureFormat format) -> Int
Compressed block data size.
static auto wrap(GLuint id, ObjectFlags flags = {}) -> Texture<dimensions>
Wrap existing OpenGL texture object.

Constructors, destructors, conversion operators

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

Public functions

void bindImage(Int imageUnit, Int level, ImageAccess access, ImageFormat format)
Bind level of texture to given image unit.
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) -> Texture<dimensions>&
Set base mip level.
auto setMaxLevel(Int level) -> Texture<dimensions>&
Set max mip level.
auto setMinificationFilter(SamplerFilter filter, SamplerMipmap mipmap = SamplerMipmap::Base) -> Texture<dimensions>&
Set minification filter.
auto setMinificationFilter(Magnum::SamplerFilter filter, Magnum::SamplerMipmap mipmap = Magnum::SamplerMipmap::Base) -> Texture<dimensions>&
auto setMagnificationFilter(SamplerFilter filter) -> Texture<dimensions>&
Set magnification filter.
auto setMagnificationFilter(Magnum::SamplerFilter filter) -> Texture<dimensions>&
auto setMinLod(Float lod) -> Texture<dimensions>&
Set minimum level-of-detail parameter.
auto setMaxLod(Float lod) -> Texture<dimensions>&
Set maximum level-of-detail parameter.
auto setLodBias(Float bias) -> Texture<dimensions>&
Set level-of-detail bias.
auto setWrapping(const Array<dimensions, SamplerWrapping>& wrapping) -> Texture<dimensions>&
Set wrapping.
auto setWrapping(const Array<dimensions, Magnum::SamplerWrapping>& wrapping) -> Texture<dimensions>&
auto setBorderColor(const Color4& color) -> Texture<dimensions>&
Set border color.
auto setBorderColor(const Vector4ui& color) -> Texture<dimensions>&
Set border color for integer texture.
auto setBorderColor(const Vector4i& color) -> Texture<dimensions>&
auto setMaxAnisotropy(Float anisotropy) -> Texture<dimensions>&
Set max anisotropy.
auto setSRGBDecode(bool decode) -> Texture<dimensions>&
Set sRGB decoding.
template<char r, char g, char b, char a>
auto setSwizzle() -> Texture<dimensions>&
Set component swizzle.
auto setCompareMode(SamplerCompareMode mode) -> Texture<dimensions>&
Set depth texture comparison mode.
auto setCompareFunction(SamplerCompareFunction function) -> Texture<dimensions>&
Set depth texture comparison function.
auto setDepthStencilMode(SamplerDepthStencilMode mode) -> Texture<dimensions>&
Set depth/stencil texture mode.
auto setStorage(Int levels, TextureFormat internalFormat, const VectorTypeFor<dimensions, Int>& size) -> Texture<dimensions>&
Set storage.
auto imageSize(Int level) -> VectorTypeFor<dimensions, Int>
Image size in given mip level.
void image(Int level, Image<dimensions>& image)
Read given mip level of texture to image.
auto image(Int level, Image<dimensions>&& image) -> Image<dimensions>
void image(Int level, BufferImage<dimensions>& image, BufferUsage usage)
Read given mip level of texture to buffer image.
auto image(Int level, BufferImage<dimensions>&& image, BufferUsage usage) -> BufferImage<dimensions>
void compressedImage(Int level, CompressedImage<dimensions>& image)
Read given mip level of compressed texture to image.
auto compressedImage(Int level, CompressedImage<dimensions>&& image) -> CompressedImage<dimensions>
void compressedImage(Int level, CompressedBufferImage<dimensions>& image, BufferUsage usage)
Read given mip level of compressed texture to buffer image.
auto compressedImage(Int level, CompressedBufferImage<dimensions>&& image, BufferUsage usage) -> CompressedBufferImage<dimensions>
void subImage(Int level, const RangeTypeFor<dimensions, Int>& range, Image<dimensions>& image)
Read range of given texture mip level to image.
auto subImage(Int level, const RangeTypeFor<dimensions, Int>& range, Image<dimensions>&& image) -> Image<dimensions>
void subImage(Int level, const RangeTypeFor<dimensions, Int>& range, BufferImage<dimensions>& image, BufferUsage usage)
Read range of given texture mip level to buffer image.
auto subImage(Int level, const RangeTypeFor<dimensions, Int>& range, BufferImage<dimensions>&& image, BufferUsage usage) -> BufferImage<dimensions>
void compressedSubImage(Int level, const RangeTypeFor<dimensions, Int>& range, CompressedImage<dimensions>& image)
Read range of given compressed texture mip level to image.
auto compressedSubImage(Int level, const RangeTypeFor<dimensions, Int>& range, CompressedImage<dimensions>&& image) -> CompressedImage<dimensions>
void compressedSubImage(Int level, const RangeTypeFor<dimensions, Int>& range, CompressedBufferImage<dimensions>& image, BufferUsage usage)
Read range of given compressed texture mip level to buffer image.
auto compressedSubImage(Int level, const RangeTypeFor<dimensions, Int>& range, CompressedBufferImage<dimensions>&& image, BufferUsage usage) -> CompressedBufferImage<dimensions>
auto setImage(Int level, TextureFormat internalFormat, const ImageView<dimensions>& image) -> Texture<dimensions>&
Set image data.
auto setImage(Int level, TextureFormat internalFormat, BufferImage<dimensions>& image) -> Texture<dimensions>&
auto setImage(Int level, TextureFormat internalFormat, BufferImage<dimensions>&& image) -> Texture<dimensions>&
auto setCompressedImage(Int level, const CompressedImageView<dimensions>& image) -> Texture<dimensions>&
Set compressed image data.
auto setCompressedImage(Int level, CompressedBufferImage<dimensions>& image) -> Texture<dimensions>&
auto setCompressedImage(Int level, CompressedBufferImage<dimensions>&& image) -> Texture<dimensions>&
auto setSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, const ImageView<dimensions>& image) -> Texture<dimensions>&
Set image subdata.
auto setSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, BufferImage<dimensions>& image) -> Texture<dimensions>&
auto setSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, BufferImage<dimensions>&& image) -> Texture<dimensions>&
auto setCompressedSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, const CompressedImageView<dimensions>& image) -> Texture<dimensions>&
Set compressed image subdata.
auto setCompressedSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, CompressedBufferImage<dimensions>& image) -> Texture<dimensions>&
auto setCompressedSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, CompressedBufferImage<dimensions>&& image) -> Texture<dimensions>&
auto generateMipmap() -> Texture<dimensions>&
Generate mipmap.
void invalidateImage(Int level)
Invalidate texture image.
void invalidateSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, const VectorTypeFor<dimensions, Int>& size)
Invalidate texture subimage.

Enum documentation

template<UnsignedInt dimensions>
enum Magnum::GL::Texture<dimensions>::(anonymous): UnsignedInt

Enumerators
Dimensions

Texture dimension count

Function documentation

template<UnsignedInt dimensions>
static VectorTypeFor<dimensions, Int> Magnum::GL::Texture<dimensions>::maxSize()

Max supported texture size.

The result is cached, repeated queries don't result in repeated OpenGL calls. For 3D textures in OpenGL ES 2.0, if OES_texture_3D extension is not available, returns zero vector.

template<UnsignedInt dimensions>
static VectorTypeFor<dimensions, Int> Magnum::GL::Texture<dimensions>::compressedBlockSize(TextureFormat format)

Compressed block size.

If format is compressed, returns compressed block size (in pixels). For uncompressed formats returns zero vector.

template<UnsignedInt dimensions>
static Int Magnum::GL::Texture<dimensions>::compressedBlockDataSize(TextureFormat format)

Compressed block data size.

If format is compressed, returns compressed block data size (in bytes). For uncompressed formats returns zero.

template<UnsignedInt dimensions>
static Texture<dimensions> Magnum::GL::Texture<dimensions>::wrap(GLuint id, ObjectFlags flags = {})

Wrap existing OpenGL texture object.

Parameters
id OpenGL texture ID
flags Object creation flags

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

template<UnsignedInt dimensions>
Magnum::GL::Texture<dimensions>::Texture() 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.

template<UnsignedInt dimensions>
Magnum::GL::Texture<dimensions>::Texture(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.

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::bindImage(Int imageUnit, Int level, ImageAccess access, ImageFormat format)

Bind level of texture to given image unit.

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

Available only on 1D and 2D textures.

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::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

Available only on 3D textures.

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::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

Available only on 3D textures.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setBaseLevel(Int level)

Set base mip level.

Returns Reference to self (for method chaining)

Taken into account when generating mipmap using generateMipmap() and when considering texture completeness when using mipmap filtering. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is 0.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setMaxLevel(Int level)

Set max mip level.

Returns Reference to self (for method chaining)

Taken into account when generating mipmap using generateMipmap() and when considering texture completeness when using mipmap filtering. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is 1000, which is clamped to count of levels specified when using setStorage().

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setMinificationFilter(SamplerFilter filter, SamplerMipmap mipmap = SamplerMipmap::Base)

Set minification filter.

Parameters
filter Filter
mipmap Mipmap filtering. If set to anything else than SamplerMipmap::Base, make sure textures for all mip levels are set or call generateMipmap().
Returns Reference to self (for method chaining)

Sets filter used when the object pixel size is smaller than the texture size. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is {SamplerFilter::Nearest, SamplerMipmap::Linear}.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setMinificationFilter(Magnum::SamplerFilter filter, Magnum::SamplerMipmap mipmap = Magnum::SamplerMipmap::Base)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setMagnificationFilter(SamplerFilter filter)

Set magnification filter.

Parameters
filter Filter
Returns Reference to self (for method chaining)

Sets filter used when the object pixel size is larger than largest texture size. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is SamplerFilter::Linear.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setMagnificationFilter(Magnum::SamplerFilter filter)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setMinLod(Float lod)

Set minimum level-of-detail parameter.

Returns Reference to self (for method chaining)

Limits selection of highest resolution mipmap. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is -1000.0f.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setMaxLod(Float lod)

Set maximum level-of-detail parameter.

Returns Reference to self (for method chaining)

Limits selection of lowest resolution mipmap. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is 1000.0f.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setLodBias(Float bias)

Set level-of-detail bias.

Returns Reference to self (for method chaining)

Fixed bias value that is added to the level-of-detail parameter. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access is available, the texture is bound before the operation (if not already). Initial value is 0.0f.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setWrapping(const Array<dimensions, SamplerWrapping>& wrapping)

Set wrapping.

Parameters
wrapping Wrapping type for all texture dimensions
Returns Reference to self (for method chaining)

Sets wrapping type for coordinates out of range $ [ 0.0, 1.0 ] $ . If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is SamplerWrapping::Repeat.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setWrapping(const Array<dimensions, Magnum::SamplerWrapping>& wrapping)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setBorderColor(const Color4& color)

Set border color.

Returns Reference to self (for method chaining)

Border color when wrapping is set to SamplerWrapping::ClampToBorder. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access is available, the texture is bound before the operation (if not already). Initial value is 0x00000000_rgbaf.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setBorderColor(const Vector4ui& color)

Set border color for integer texture.

Returns Reference to self (for method chaining)

Border color for integer textures when wrapping is set to SamplerWrapping::ClampToBorder. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access is available, the texture is bound before the operation (if not already). Initial value is {0, 0, 0, 0}.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::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.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setMaxAnisotropy(Float anisotropy)

Set max anisotropy.

Returns Reference to self (for method chaining)

Default value is 1.0f, which means no anisotropy. Set to value greater than 1.0f for anisotropic filtering. If extension EXT_texture_filter_anisotropic (desktop or ES) is not available, this function does nothing. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already).

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setSRGBDecode(bool decode)

Set sRGB decoding.

Returns Reference to self (for method chaining)

Disables or reenables decoding of sRGB values. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is true.

template<UnsignedInt dimensions> template<char r, char g, char b, char a>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setSwizzle()

Set component swizzle.

Returns Reference to self (for method chaining)

You can use letters 'r', 'g', 'b', 'a' for addressing components or letters '0' and '1' for zero and one, similarly as in the Math::swizzle() function. Example usage:

texture.setSwizzle<'b', 'g', 'r', '0'>();

If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is 'r', 'g', 'b', 'a'.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setCompareMode(SamplerCompareMode mode)

Set depth texture comparison mode.

Returns Reference to self (for method chaining)

If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is SamplerCompareMode::None.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setCompareFunction(SamplerCompareFunction function)

Set depth texture comparison function.

Returns Reference to self (for method chaining)

Comparison operator used when comparison mode is set to SamplerCompareMode::CompareRefToTexture. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). Initial value is SamplerCompareFunction::LessOrEqual.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setDepthStencilMode(SamplerDepthStencilMode mode)

Set depth/stencil texture mode.

Returns Reference to self (for method chaining)

Selects which component of packed depth/stencil texture is used for texturing. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access is available, the texture is bound before the operation (if not already). Initial value is SamplerDepthStencilMode::DepthComponent.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setStorage(Int levels, TextureFormat internalFormat, const VectorTypeFor<dimensions, Int>& size)

Set storage.

Parameters
levels Mip level count
internalFormat Internal format
size Size of largest mip level
Returns Reference to self (for method chaining)

After calling this function the texture is immutable and calling setStorage() or setImage() is not allowed.

If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already). If neither ARB_texture_storage (part of OpenGL 4.2), OpenGL ES 3.0 nor EXT_texture_storage in OpenGL ES 2.0 is available, the feature is emulated with sequence of setImage() calls.

template<UnsignedInt dimensions>
VectorTypeFor<dimensions, Int> Magnum::GL::Texture<dimensions>::imageSize(Int level)

Image size in given mip level.

The result is not cached in any way. If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already).

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::image(Int level, Image<dimensions>& image)

Read given mip level of texture to image.

Parameters
level Mip level
image Image where to put the data

Image parameters like format and type of pixel data are taken from given image, image size is taken from the texture using imageSize(). The storage is not reallocated if it is large enough to contain the new data.

If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access is available, the texture is bound before the operation (if not already). If either ARB_direct_state_access or ARB_robustness is available, the operation is protected from buffer overflow. However, if ARB_direct_state_access is not available and both EXT_direct_state_access and ARB_robustness are available, the robust operation is preferred over DSA.

template<UnsignedInt dimensions>
Image<dimensions> Magnum::GL::Texture<dimensions>::image(Int level, Image<dimensions>&& 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:

Image2D image = texture.image(0, {PixelFormat::RGBA8Unorm});

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::image(Int level, BufferImage<dimensions>& image, BufferUsage usage)

Read given mip level of texture to buffer image.

Parameters
level Mip level
image Buffer image where to put the data
usage Buffer usage

See image(Int, Image&) for more information. The storage is not reallocated if it is large enough to contain the new data, which means that usage might get ignored.

template<UnsignedInt dimensions>
BufferImage<dimensions> Magnum::GL::Texture<dimensions>::image(Int level, BufferImage<dimensions>&& 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:

GL::BufferImage2D image = texture.image(0,
    {PixelFormat::RGBA8Unorm}, GL::BufferUsage::StaticRead);

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::compressedImage(Int level, CompressedImage<dimensions>& image)

Read given mip level of compressed texture to image.

Parameters
level Mip level
image Image where to put the compressed data

Compression format and data size are taken from the texture, image size is taken using imageSize(). The storage is not reallocated if it is large enough to contain the new data.

If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access is available, the texture is bound before the operation (if not already). If either ARB_direct_state_access or ARB_robustness is available, the operation is protected from buffer overflow. However, if ARB_direct_state_access is not available and both EXT_direct_state_access and ARB_robustness are available, the robust operation is preferred over DSA.

template<UnsignedInt dimensions>
CompressedImage<dimensions> Magnum::GL::Texture<dimensions>::compressedImage(Int level, CompressedImage<dimensions>&& 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:

CompressedImage2D image = texture.compressedImage(0, {});

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::compressedImage(Int level, CompressedBufferImage<dimensions>& image, BufferUsage usage)

Read given mip level of compressed texture to buffer image.

Parameters
level Mip level
image Buffer image where to put the compressed data
usage Buffer usage

See compressedImage(Int, CompressedImage&) for more information. The storage is not reallocated if it is large enough to contain the new data, which means that usage might get ignored.

template<UnsignedInt dimensions>
CompressedBufferImage<dimensions> Magnum::GL::Texture<dimensions>::compressedImage(Int level, CompressedBufferImage<dimensions>&& 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:

GL::CompressedBufferImage2D image = texture.compressedImage(0, {},
    GL::BufferUsage::StaticRead);

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::subImage(Int level, const RangeTypeFor<dimensions, Int>& range, Image<dimensions>& image)

Read range of given texture mip level to image.

Parameters
level Mip level
range Range to read
image Image where to put the data

Image parameters like format and type of pixel data are taken from given image. The storage is not reallocated if it is large enough to contain the new data.

The operation is protected from buffer overflow.

template<UnsignedInt dimensions>
Image<dimensions> Magnum::GL::Texture<dimensions>::subImage(Int level, const RangeTypeFor<dimensions, Int>& range, Image<dimensions>&& 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:

Image2D image = texture.subImage(0, range, {PixelFormat::RGBA8Unorm});

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::subImage(Int level, const RangeTypeFor<dimensions, Int>& range, BufferImage<dimensions>& image, BufferUsage usage)

Read range of given texture mip level to buffer image.

Parameters
level Mip level
range Range to read
image Buffer image where to put the data
usage Buffer usage

See subImage(Int, const RangeTypeFor<dimensions, Int>&, Image&) for more information. The storage is not reallocated if it is large enough to contain the new data, which means that usage might get ignored.

template<UnsignedInt dimensions>
BufferImage<dimensions> Magnum::GL::Texture<dimensions>::subImage(Int level, const RangeTypeFor<dimensions, Int>& range, BufferImage<dimensions>&& 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:

GL::BufferImage2D image = texture.subImage(0, range,
    {PixelFormat::RGBA8Unorm}, GL::BufferUsage::StaticRead);

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::compressedSubImage(Int level, const RangeTypeFor<dimensions, Int>& range, CompressedImage<dimensions>& image)

Read range of given compressed texture mip level to image.

Parameters
level Mip level
range Range to read
image Image where to put the compressed data

Compression format and data size are taken from the texture.

template<UnsignedInt dimensions>
CompressedImage<dimensions> Magnum::GL::Texture<dimensions>::compressedSubImage(Int level, const RangeTypeFor<dimensions, Int>& range, CompressedImage<dimensions>&& 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:

CompressedImage2D image = texture.compressedSubImage(0, range, {});

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::compressedSubImage(Int level, const RangeTypeFor<dimensions, Int>& range, CompressedBufferImage<dimensions>& image, BufferUsage usage)

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

Parameters
level Mip level
range Range to read
image Buffer image where to put the compressed data
usage Buffer usage

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

template<UnsignedInt dimensions>
CompressedBufferImage<dimensions> Magnum::GL::Texture<dimensions>::compressedSubImage(Int level, const RangeTypeFor<dimensions, Int>& range, CompressedBufferImage<dimensions>&& 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:

GL::CompressedBufferImage2D image = texture.compressedSubImage(0, range, {},
    GL::BufferUsage::StaticRead);

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setImage(Int level, TextureFormat internalFormat, const ImageView<dimensions>& image)

Set image data.

Parameters
level Mip level
internalFormat Internal format
image Image, ImageView or Trade::ImageData of the same dimension count
Returns Reference to self (for method chaining)

On platforms that support it prefer to use setStorage() and setSubImage() instead, as it avoids unnecessary reallocations and has better performance characteristics. This call also has no equivalent in ARB_direct_state_access, thus the texture needs to be bound to some texture unit before the operation.

On OpenGL ES 2.0 and WebGL 1.0, if PixelStorage::skip() is set, the functionality is emulated by adjusting the data pointer.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setImage(Int level, TextureFormat internalFormat, BufferImage<dimensions>& image)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setImage(Int level, TextureFormat internalFormat, BufferImage<dimensions>&& image)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setCompressedImage(Int level, const CompressedImageView<dimensions>& image)

Set compressed image data.

Parameters
level Mip level
image CompressedImage, CompressedImageView or compressed Trade::ImageData of the same dimension count
Returns Reference to self (for method chaining)

On platforms that support it prefer to use setStorage() and setCompressedSubImage() instead, as it avoids unnecessary reallocations and has better performance characteristics. This call also has no equivalent in ARB_direct_state_access, thus the texture needs to be bound to some texture unit before the operation.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setCompressedImage(Int level, CompressedBufferImage<dimensions>& image)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setCompressedImage(Int level, CompressedBufferImage<dimensions>&& image)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, const ImageView<dimensions>& image)

Set image subdata.

Parameters
level Mip level
offset Offset where to put data in the texture
image Image, ImageView or Trade::ImageData of the same dimension count
Returns Reference to self (for method chaining)

If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already).

On OpenGL ES 2.0 and WebGL 1.0, if PixelStorage::skip() is set, the functionality is emulated by adjusting the data pointer.

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, BufferImage<dimensions>& image)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, BufferImage<dimensions>&& image)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setCompressedSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, const CompressedImageView<dimensions>& image)

Set compressed image subdata.

Parameters
level Mip level
offset Offset where to put data in the texture
image CompressedImage, CompressedImageView or compressed Trade::ImageData of the same dimension count
Returns Reference to self (for method chaining)

If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already).

template<UnsignedInt dimensions>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setCompressedSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, CompressedBufferImage<dimensions>& image)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::setCompressedSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, CompressedBufferImage<dimensions>&& image)

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>
Texture<dimensions>& Magnum::GL::Texture<dimensions>::generateMipmap()

Generate mipmap.

Returns Reference to self (for method chaining)

If neither ARB_direct_state_access (part of OpenGL 4.5) nor EXT_direct_state_access desktop extension is available, the texture is bound before the operation (if not already).

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::invalidateImage(Int level)

Invalidate texture image.

Parameters
level Mip level

If running on OpenGL ES or extension ARB_invalidate_subdata (part of OpenGL 4.3) is not available, this function does nothing.

template<UnsignedInt dimensions>
void Magnum::GL::Texture<dimensions>::invalidateSubImage(Int level, const VectorTypeFor<dimensions, Int>& offset, const VectorTypeFor<dimensions, Int>& size)

Invalidate texture subimage.

Parameters
level Mip level
offset Offset into the texture
size Size of invalidated data

If running on OpenGL ES or extension ARB_invalidate_subdata (part of OpenGL 4.3) is not available, this function does nothing.