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::AbstractTexture class

Base for textures.

Encapsulates one OpenGL texture object. See Texture, TextureArray, CubeMapTexture, CubeMapTextureArray, RectangleTexture, BufferTexture and MultisampleTexture documentation for more information and usage examples.

WebGL restrictions

WebGL puts some restrictions on type of data submitted to *Texture::setSubImage(), see its documentation for details.

Performance optimizations and security

The engine tracks currently bound textures and images in all available texture units to avoid unnecessary calls to glActiveTexture(), glBindTexture() and glBindImageTexture(). Texture configuration functions use dedicated highest available texture unit to not affect active bindings in user units. Texture limits and implementation-defined values (such as maxColorSamples()) are cached, so repeated queries don't result in repeated glGet() calls. See also Context::resetState() and Context::State::Textures.

If ARB_direct_state_access (part of OpenGL 4.5) is available, bind(Int) and unbind(Int) use glBindTextureUnit(). Otherwise, if ARB_multi_bind (part of OpenGL 4.4) is available, bind(Int) and unbind() uses glBindTextures(). Lastly, if EXT_direct_state_access desktop extension is available, glBindNamedTextureEXT() function is used to avoid unnecessary calls to glActiveTexture().

In addition, if either ARB_direct_state_access (part of OpenGL 4.5) or EXT_direct_state_access desktop extension is available, also all texture configuration and data updating functions use DSA functions to avoid unnecessary calls to glActiveTexture() and glBindTexture(). See respective function documentation for more information.

If ARB_multi_bind (part of OpenGL 4.5) is available, bind(Int, std::initializer_list<AbstractTexture*>) and unbind(Int, std::size_t) use glBindTextures() to avoid unnecessary calls to glActiveTexture(). Otherwise the feature is emulated with sequence of bind(Int)/unbind(Int) calls.

If either ARB_direct_state_access (part of OpenGL 4.5) or ARB_robustness desktop extension is available, image reading operations (such as Texture::image()) are 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 version is preferred over DSA.

To achieve least state changes, fully configure each texture in one run – method chaining comes in handy – and try to have often used textures in dedicated units, not occupied by other textures. First configure the texture and then set the data, so OpenGL can optimize them to match the settings. To avoid redundant consistency checks and memory reallocations when updating texture data, set texture storage at once using setStorage() and then set data using setSubImage().

Function setStorage() creates immutable texture storage, removing the need for additional consistency checks and memory reallocations when updating the data later. If OpenGL 4.2, ARB_texture_storage, OpenGL ES 3.0 or EXT_texture_storage in OpenGL ES 2.0 is not available, the feature is emulated with sequence of setImage() calls.

You can use functions invalidateImage() and invalidateSubImage() if you don't need texture data anymore to avoid unnecessary memory operations performed by OpenGL in order to preserve the data. If running on OpenGL ES or extension ARB_invalidate_subdata (part of OpenGL 4.3) is not available, these functions do nothing.

Base classes

class AbstractObject
Base for all OpenGL objects.

Derived classes

class BufferTexture
Buffer texture.
class CubeMapTexture
Cube map texture.
class CubeMapTextureArray
Cube map texture array.
template<UnsignedInt dimensions>
class MultisampleTexture
Mulitsample texture.
class RectangleTexture
Rectangle texture.
template<UnsignedInt dimensions>
class Texture
Texture.
template<UnsignedInt dimensions>
class TextureArray
Texture array.
template<UnsignedInt dimensions>
class Texture
Texture.

Public static functions

static auto maxLodBias() -> Float
Max level-of-detail bias.
static auto maxColorSamples() -> Int
Max supported color sample count.
static auto maxDepthSamples() -> Int
Max supported depth sample count.
static auto maxIntegerSamples() -> Int
Max supported integer sample count.
static void unbind(Int textureUnit)
Unbind any texture from given texture unit.
static void unbind(Int firstTextureUnit, std::size_t count)
Unbind textures in given range of texture units.
static void bind(Int firstTextureUnit, std::initializer_list<AbstractTexture*> textures)
Bind textures to given range of texture units.
static void unbindImage(Int imageUnit)
Unbind any image from given image unit.
static void unbindImages(Int firstImageUnit, std::size_t count)
Unbind images in given range of image units.
static void bindImages(Int firstImageUnit, std::initializer_list<AbstractTexture*> textures)
Bind textures to given range of texture units.

Constructors, destructors, conversion operators

AbstractTexture(const AbstractTexture&) deleted
Copying is not allowed.
AbstractTexture(AbstractTexture&& other) noexcept
Move constructor.
~AbstractTexture()
Destructor.

Public functions

auto operator=(const AbstractTexture&) -> AbstractTexture& deleted
Copying is not allowed.
auto operator=(AbstractTexture&& other) -> AbstractTexture& noexcept
Move assignment.
auto id() const -> GLuint
OpenGL texture ID.
auto release() -> GLuint
Release OpenGL object.
auto label() -> std::string
Texture label.
auto setLabel(const std::string& label) -> AbstractTexture&
Set texture label.
template<std::size_t size>
auto setLabel(const char(&label)[size]) -> AbstractTexture&
void bind(Int textureUnit)
Bind texture to given texture unit.

Function documentation

static Float Magnum::AbstractTexture::maxLodBias()

Max level-of-detail bias.

The result is cached, repeated queries don't result in repeated OpenGL calls.

static Int Magnum::AbstractTexture::maxColorSamples()

Max supported color sample count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_texture_multisample (part of OpenGL 3.2) nor OpenGL ES 3.1 is available, returns 0.

static Int Magnum::AbstractTexture::maxDepthSamples()

Max supported depth sample count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_texture_multisample (part of OpenGL 3.2) nor OpenGL ES 3.1 is available, returns 0.

static Int Magnum::AbstractTexture::maxIntegerSamples()

Max supported integer sample count.

The result is cached, repeated queries don't result in repeated OpenGL calls. If neither extension ARB_texture_multisample (part of OpenGL 3.2) nor OpenGL ES 3.1 is available, returns 0.

static void Magnum::AbstractTexture::unbind(Int textureUnit)

Unbind any texture from given texture unit.

If neither ARB_direct_state_access (part of OpenGL 4.5), ARB_multi_bind (part of OpenGL 4.4) nor EXT_direct_state_access desktop extension is available, the texture unit is made active before unbinding the texture.

static void Magnum::AbstractTexture::unbind(Int firstTextureUnit, std::size_t count)

Unbind textures in given range of texture units.

Unbinds all textures in the range LaTeX Math $ [ firstTextureUnit ; firstTextureUnit + count ) $ . If ARB_multi_bind (part of OpenGL 4.4) is not available, the feature is emulated with sequence of unbind(Int) calls.

static void Magnum::AbstractTexture::bind(Int firstTextureUnit, std::initializer_list<AbstractTexture*> textures)

Bind textures to given range of texture units.

Binds first texture in the list to firstTextureUnit, second to firstTextureUnit + 1 etc. If any texture is nullptr, given texture unit is unbound. If ARB_multi_bind (part of OpenGL 4.4) is not available, the feature is emulated with sequence of bind(Int) / unbind(Int) calls.

static void Magnum::AbstractTexture::unbindImage(Int imageUnit)

Unbind any image from given image unit.

static void Magnum::AbstractTexture::unbindImages(Int firstImageUnit, std::size_t count)

Unbind images in given range of image units.

Unbinds all texture in the range LaTeX Math $ [ firstImageUnit ; firstImageUnit + count ) $ .

static void Magnum::AbstractTexture::bindImages(Int firstImageUnit, std::initializer_list<AbstractTexture*> textures)

Bind textures to given range of texture units.

Binds first level of given texture in the list to firstImageUnit, second to firstTextureUnit + 1 etc. 3D, cube map and array textures are bound as layered targets. If any texture is nullptr, given image unit is unbound.

GLuint Magnum::AbstractTexture::release()

Release OpenGL object.

Releases ownership of OpenGL texture object and returns its ID so it is not deleted on destruction. The internal state is then equivalent to moved-from state.

std::string Magnum::AbstractTexture::label()

Texture label.

The result is not cached, repeated queries will result in repeated OpenGL calls. If OpenGL 4.3 is not supported and neither KHR_debug (covered also by ANDROID_extension_pack_es31a) nor EXT_debug_label desktop or ES extension is available, this function returns empty string.

AbstractTexture& Magnum::AbstractTexture::setLabel(const std::string& label)

Set texture label.

Returns Reference to self (for method chaining)

Default is empty string. If OpenGL 4.3 is not supported and neither KHR_debug (covered also by ANDROID_extension_pack_es31a) nor EXT_debug_label desktop or ES extension is available, this function does nothing.

template<std::size_t size>
AbstractTexture& Magnum::AbstractTexture::setLabel(const char(&label)[size])

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

void Magnum::AbstractTexture::bind(Int textureUnit)

Bind texture to given texture unit.

If neither ARB_direct_state_access (part of OpenGL 4.5), ARB_multi_bind (part of OpenGL 4.4) nor EXT_direct_state_access desktop extension is available, the texture unit is made active before binding the texture.