OpenGL resource abstractions

Met.3D provides several abstractions over common OpenGL resource types. These abstractions implement MAbstractGPUDataItem and can therefore be stored and lifetime-managed by OpenGL Resource management. This page describes the currently available resource abstractions. Each abstraction owns its corresponding OpenGL object. The object is created during construction and automatically destroyed when the wrapper is deleted. The implementations can be found in src/gxfw/gl.

Overview:

Resource	Wrapper	Purpose
Textures	MTexture	Textures objects
Vertex buffers	MTypedVertexBuffer	Vertex attributes
Index buffers	MIndexBuffer	Element indices
Uniform buffers	MUniformBufferObject	Uniform block data
Shader storage buffers	MShaderStorageBufferObject	Large read / write GPU buffers

Textures

OpenGL textures are implemented in GL::MTexture. It allows you to create a texture of a certain size and format. Though the constructor only creates the texture object, it does not yet allocate any memory. The dimensions are only stored for resource management purposes until storage is allocated.

The texture can be bound to a texture unit for rendering via bindToTextureUnit(GLuint). Additionally, bindToLastTextureUnit() can be used to bind to the last valid texture unit.

Image uploads, texture parameter configuration, and mipmap generation are performed using the standard OpenGL API.

A typical texture creation looks like the following:

Listing 16 Typical creation of MTexture.

GLint width = 128;
GLint height = 128;
MTexture *texture = new MTexture("request_key", GL_TEXTURE_2D, GL_RGB8, width, height);

// Register texture with resource management
// ...

// Configure texture parameters
texture->bindToLastTextureUnit();

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_REPEAT);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);

// Upload texture data
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB, width, height,
             0, GL_RGB, GL_UNSIGNED_BYTE, imgData);

Vertex buffers

Vertex buffers are a type of buffer that store vertex attributes, such as positions. They are implemented as MVertexBuffer and MTypedVertexBuffer<Data, Type, Num> and its typedefs. Data is the C++ data type that is stored in the vertex buffer, while Type is the OpenGL primitive type that it maps to. Meanwhile, Num specifies how many values of OpenGL type Type are stored in one Data element. Several typedefs are provided for common vertex buffer types, such as a MVector3DVertexBuffer for QVector3D.

While MVertexBuffer is the abstract base class for vertex buffers, providing ways to bind the vertex buffer, the MTypedVertexBuffer<T> provides typed methods to reallocate, upload and update the vertex buffer. It also provides information to the resource manager about the size of the vertex buffer.

When the number of vertices changes, call reallocate(...). If only the contents change, while the size stays constant, call upload(...). To only update a part of the buffer instead of the whole range, call update(...).

Generally prefer to use the typed vertex buffer implementation when storing references to vertex buffers you create. The abstract base class can be used when you do not know what kind of vertex buffer will be referenced by it.

The typed vertex buffer is typically used as follows:

Listing 17 Typical creation and use of the typed vertex buffer.

GLint numVertices = ...;
auto *vbo = new MFloatVertexBuffer("request_key", numVertices); // Typedef for float typed vertex buffers

// Register vbo with resource management
// ...

// Upload data
QVector<float> vertexData = ...;
vbo->upload(vertexData);

// ...

// Bind vbo before rendering at attribute location 0
vbo->attachToVertexAttribute(0);

// Draw
// ...

Index buffers

Index buffers are used to store indices into vertex attributes to optimize drawing. They are implemented as MIndexBuffer, which currently only allows storing of indices of type GLuint. Index buffers only provide an upload() method. Calling it always reallocates the buffer, before uploading the supplied indices. The amount of indices stored can be queried via count().

To bind the index buffer before drawing, call bindToElementArrayBuffer().

Listing 18 Typical creation and use of the index buffer.

GLint numIndices = ...;
auto *ibo = new MIndexBuffer("request_key", numIndices);

// Register ibo with resource management
// ...

// Upload indices
QVector<GLuint> indices = ...;
ibo->upload(indices);

// ...

// Bind index buffer before rendering
ibo->bindToElementArrayBuffer();

// Draw index buffer
// ...
glDrawElements(GL_TRIANGLES, ibo->count(), GL_UNSIGNED_INT, nullptr);

Uniform buffers

Uniform buffer objects are implemented as MUniformBufferObject<T>. Uniform buffer objects allow related uniforms to be stored in a single buffer and updated with one upload operation. It is templated based on the type that represents the structure of the uniform buffer. Typically, you would define a struct on the C++ side that mirrors the byte layout of the GLSL side.

Use uploadData(...) to upload an instance of T to the uniform buffer. To only update single members, use updateSubData<M>(...) where M is the type of the struct member.

Once ready for rendering, bind the uniform buffer via bind(GLuint). A uniform buffer stays bound to the same binding location until another uniform buffer is bound to it in the same OpenGL context. That makes them especially useful for global uniforms, like the scenes MVP matrix. Typically, lower bindings are changed less frequently and are used for global data such as scene related uniforms.

When declaring a struct backing the uniform buffer, ensure that the C++ struct matches the shaders std140 layout rules. More information can be found in the OpenGL 4.3 core specification on page 124.

Listing 19 Typical creation and use of a uniform buffer.

struct Buffer
{
    alignas(4) float someData; // alignas() is used to align the members according to the OpenGL specification.
    alignas(16) float mvpMatrix[16];
};

// ...

auto *ubo = new MUniformBufferObject<Buffer>("request_key");

// Register ubo with resource management
// ...

// Create data to upload
Buffer data;
// ...

ubo->uploadData(data, GL_STATIC_DRAW);

// ...

// Bind ubo before rendering
ubo->bind(0);

// Draw
// ...

Listing 20 The GLSL definition of the Buffer uniform block used in the previous snippet.

#version 430

// Buffer uses memory layout std140, with row-major matrices and bind location 0.
layout (std140, row_major, binding=0) uniform Buffer
{
    float someData;
    mat4 mvpMatrix;
} buffer;

Shader storage buffers

Shader storage buffers are also buffer-backed objects in OpenGL, similar to uniform buffers. They are implemented in MShaderStorageBufferObject.

Unlike uniform buffers, shader storage buffers are treated as raw byte storage and therefore only require an element size and element count.

If the amount of items in the shader storage buffer changes, you can call updateSize(GLuint) with the new element count. To upload data, call upload(...).

To bind the buffer, use bindToIndex(GLuint) with the binding location of the shader storage buffer.

Note

Both uniform buffers and shader storage buffers are bound to certain binding locations. These are not shared between both buffer types, meaning a uniform buffer bound to 0 will not overwrite a shader storage buffer also bound to 0.

Listing 21 Typical creation and use of a shader storage buffer.

// Create an SSBO with 100 floating point values.
auto *ssbo = new MShaderStorageBufferObject("request_key", sizeof(float), 100);

// Register SSBO with resource management
// ...

float data[100] = ...;
ssbo->upload(data, GL_STATIC_DRAW);

// ...

// Bind SSBO before rendering
ssbo->bindToIndex(0);

// Draw
// ...

Listing 22 GLSL definition of the previous examples’ shader storage buffer.

// Data uses memory layout 430 and shader storage buffer binding location 0
layout (std430, binding=0) buffer Data
{
    float data[];
};

Shader effects

Shader effects wrap one compiled GLFX effect file and exposes its shader programs. They do map to basic OpenGL shader progams under the hood. They are implemented in MShaderEffect.

See Shaders in Met.3D for writing and compiling shader effects.