Magnum::GL::AbstractTexture class

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.

Pixel storage mode defined by PixelStorage and CompressedPixelStorage is applied either right before doing image upload (such as various setImage(), setSubImage(), setCompressedImage() or setCompressedSubImage() functions) using glPixelStore() with GL_UNPACK_* parameters or right before doing image download (such as various image(), subImage(), compressedImage(), or compressedSubImage() functions) using glPixelStore() with GL_PACK_*. The engine tracks currently used pixel pack/unpack parameters to avoid unnecessary calls to glPixelStore(). See also Context::resetState() and Context::State::PixelStorage.

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