Vertex buffers

Vertex buffers

Geometry data is defined by VertexBuffer objects, which hold a number of vertices of a certain vertex format. For rendering, the data is uploaded to the GPU, but optionally a shadow copy of the vertex data can exist in CPU memory, see SetShadowed() to allow e.g. raycasts into the geometry without having to lock and read GPU memory.

The vertex format can be defined in two ways by two overloads of SetSize():

1) With a bitmask representing hardcoded vertex element semantics and datatypes. Each of the following elements may or may not be present, but the order or datatypes may not change. The order is defined by the LegacyVertexElement enum in GraphicsDefs.h, while bitmask defines exist as MASK_POSITION, MASK_NORMAL etc.

  • Position (Vector3)
  • Normal (Vector3)
  • Color (unsigned char[4], normalized)
  • Texcoord1 (Vector2)
  • Texcoord2 (Vector2)
  • Cubetexcoord1 (Vector3)
  • Cubetexcoord2 (Vector3)
  • Tangent (Vector4)
  • Blendweights (float[4])
  • Blendindices (unsigned char[4])
  • Instancematrix1-3 (Vector4)
  • Object index (int, not supported on D3D9)

Note that the texcoord numbers are misleading as the actual texcoord inputs in shaders are zero-based. Instancematrix1-3 are reserved to be used by the engine for instancing and map to shader texcoord inputs 4-6.

2) By defining VertexElement structures, which tell the data type, semantic, and zero-based semantic index (for e.g. multiple texcoords), and whether the data is per-vertex or per-instance data. This allows to freely define the order and meaning of the elements. However for 3D objects, the first element should always be "Position" and use the Vector3 type to ensure e.g. raycasts and occlusion rendering work properly.

The third parameter of SetSize() is whether to create the buffer as static or dynamic. This is a hint to the underlying graphics API how to allocate the buffer data. Dynamic will suit frequent (every frame) modification better, while static has likely better overall performance for world geometry rendering.

After the size and format are defined, the vertex data can be set either by calling SetData() / SetDataRange() or locking the vertex buffer for access, writing the data to the memory space returned from the lock, then unlocking when done.

Multiple vertex buffers

Multiple vertex buffers can be set to the Graphics subsystem at once, or defined into a drawable's Geometry definition for rendering.

In case the buffers both contain the same semantic, for example position, a higher index buffer overrides a lower buffer index. This is used by the AnimatedModel component to apply vertex morphs: it creates a separate clone vertex buffer which overrides the original model's position, normal and tangent data, and assigns it on index 1 while index 0 is the original model's vertex buffer.

A vertex buffer should either only contain per-vertex data, or per-instance data. Instancing in the high-level rendering (Renderer & View classes) works by momentarily appending the instance vertex buffer to the geometry being rendered in an instanced fashion.

Index buffers

A vertex buffer is often accompanied by an index buffer (IndexBuffer class) to allow indexed rendering which avoids repeating the same vertices over and over. Its API is similar to vertex buffers, but an index buffer only needs to define the number of indices, whether the indices are 16- or 32-bit (largeIndices flag) and whether the buffer is dynamic.