Magnum::GL::BufferTexture class
#include <Magnum/GL/BufferTexture.h>

Buffer texture.

This texture is, unlike classic textures such as Texture, used as simple data source, without any unnecessary interpolation and wrapping methods.

Usage

Texture data are stored in buffer and after binding the buffer to the texture using setBuffer(), you can fill the buffer at any time using data setting functions in Buffer itself.

Note that the buffer is not managed (e.g. deleted on destruction) by the texture, so you have to manage it on your own and ensure that it is available for whole texture lifetime. On the other hand it allows you to use one buffer for more textures or store more than one data in it.

Example usage:

GL::Buffer buffer;
GL::BufferTexture texture;
texture.setBuffer(GL::BufferTextureFormat::RGB32F, buffer);

Vector3 data[200]{
    // ...
};
buffer.setData(data, GL::BufferUsage::StaticDraw);

In shader, the texture is used via samplerBuffer, isamplerBuffer or usamplerBuffer. Unlike in classic textures, coordinates for buffer textures are integer coordinates passed to texelFetch(). See AbstractShaderProgram documentation for more information about usage in shaders.

Performance optimizations

If ARB_direct_state_access (part of OpenGL 4.5) is available, setBuffer() functions use DSA to avoid unnecessary calls to glActiveTexture() and glBindTexture(). See relevant section in AbstractTexture documentation and respective function documentation for more information.

Base classes

class AbstractTexture: Base for textures.

Public static functions

static auto maxSize() -> Int: Max supported buffer texture size.
static auto offsetAlignment() -> Int: Minimum required alignment for texture buffer offsets.
static auto wrap(GLuint id, ObjectFlags flags = {}) -> BufferTexture: Wrap existing OpenGL buffer texture object.

Constructors, destructors, conversion operators

BufferTexture() explicit: Constructor.
BufferTexture(NoCreateT) explicit noexcept: Construct without creating the underlying OpenGL object.
BufferTexture(const BufferTexture&) deleted: Copying is not allowed.
BufferTexture(BufferTexture&&) defaulted noexcept: Move constructor.

Public functions

auto operator=(const BufferTexture&) -> BufferTexture& deleted: Copying is not allowed.
auto operator=(BufferTexture&&) -> BufferTexture& defaulted noexcept: Move assignment.
auto size() -> Int new in 2019.10: Texture size.
void bindImage(Int imageUnit, ImageAccess access, ImageFormat format): Bind texture to given image unit.
auto setBuffer(BufferTextureFormat internalFormat, Buffer& buffer) -> BufferTexture&: Set texture buffer.
auto setBuffer(BufferTextureFormat internalFormat, Buffer& buffer, GLintptr offset, GLsizeiptr size) -> BufferTexture&: Set texture buffer.
auto resetBuffer() -> BufferTexture& new in 2020.06: Remove existing buffer from the texture.

Function documentation

static Int Magnum::GL::BufferTexture::maxSize()

Max supported buffer texture size.

The result is cached, repeated queries don't result in repeated OpenGL calls. If ARB_texture_buffer_object (part of OpenGL 3.1) is not available, returns 0.

static Int Magnum::GL::BufferTexture::offsetAlignment()

Minimum required alignment for texture buffer offsets.

The result is cached, repeated queries don't result in repeated OpenGL calls. If extension ARB_texture_buffer_range (part of OpenGL 4.3) is not available, returns 1.

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

Wrap existing OpenGL buffer texture object.

Parameters
id	OpenGL buffer texture ID
flags	Object creation flags

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

Magnum::GL::BufferTexture::BufferTexture() 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::GL::BufferTexture::BufferTexture(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. However note that this is a low-level and a potentially dangerous API, see the documentation of NoCreate for alternatives.

Int Magnum::GL::BufferTexture::size() new in 2019.10

Texture size.

Equivalent to size of the buffer attached to setBuffer() divided by size of a particular BufferTextureFormat. The result is not cached in any way. If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is bound before the operation (if not already).

void Magnum::GL::BufferTexture::bindImage(Int imageUnit, ImageAccess access, ImageFormat format)

Bind texture to given image unit.

Parameters
imageUnit	Image unit
access	Image access
format	Image format

BufferTexture& Magnum::GL::BufferTexture::setBuffer(BufferTextureFormat internalFormat, Buffer& buffer)

Set texture buffer.

Parameters
internalFormat	Internal format
buffer	Buffer with data
Returns	Reference to self (for method chaining)

Binds given buffer to this texture. The buffer itself can be then filled with data of proper format at any time using Buffer's own data setting functions. If ARB_direct_state_access (part of OpenGL 4.5) is not available, the texture is bound before the operation (if not already).

BufferTexture& Magnum::GL::BufferTexture::setBuffer(BufferTextureFormat internalFormat, Buffer& buffer, GLintptr offset, GLsizeiptr size)