BufferAttribute

Represents a named stream of per-vertex or per-instance data.

BufferAttribute is the basic unit of mesh data. It owns a flat array of floats along with the metadata needed to interpret it: a name that matches the attribute's name in shader code, a format describing the number of components per element, and a rate that determines whether the data advances per vertex or per instance.

Attributes are added to a Geometry (vertex rate) or an instanced mesh (instance rate) and may be shared by multiple geometries. The renderer uploads attribute data to the GPU on first use and re-uploads it whenever the data changes, using an internal version that SetData and Write increment.

auto positions = vglx::BufferAttribute::Create({
  .name = vglx::BufferAttribute::kPosition,
  .format = vglx::BufferAttribute::Format::Float32x3,
  .rate = vglx::BufferAttribute::Rate::Vertex
}, {
  0.5f, -0.5f, 0.0f,
  0.0f,  0.5f, 0.0f,
 -0.5f, -0.5f, 0.0f,
});

geometry->AddAttribute(positions);

Note that attributes are non-interleaved: each attribute holds a tightly packed array of its own values and is uploaded to its own GPU buffer rather than sharing an interleaved buffer with other attributes.

Construction

Constructors

BufferAttribute()

Constructs a buffer attribute.

The data size must be divisible by the number of components implied by the format. Invalid parameters are reported and leave the attribute in an invalid state.

BufferAttribute::BufferAttribute(const Params& params, std::vector<float> data);

Parameter	Description
params	Attribute parameters.
data	Flat array of floats containing the attribute data.

Factories preferred

BufferAttribute::Create() std::shared_ptr<BufferAttribute>

Creates a shared instance of BufferAttribute.

static std::shared_ptr<BufferAttribute> BufferAttribute::Create(const Params& params, std::vector<float> data);

Parameter	Description
params	Attribute parameters.
data	Flat array of floats containing the attribute data.

Types

BufferAttribute::Format enum

Enumerates supported attribute data formats.

Describes the number of 32-bit float components that make up a single element.

Value	Description
Float32x1	One float per element (scalar).
Float32x2	Two floats per element (vec2).
Float32x3	Three floats per element (vec3).
Float32x4	Four floats per element (vec4).
Float32x16	Sixteen floats per element (mat4).

BufferAttribute::Rate enum

Determines how the attribute advances during rendering.

Value	Description
Vertex	One element per vertex.
Instance	One element per instance.

BufferAttribute::Params struct

Parameters for constructing a buffer attribute.

Parameter	Description
name std::string_view	Attribute name matching its name in shader code.
format Format	Number of components per element.
rate Rate	Per-vertex or per-instance rate.

Properties

Known attribute names

Attributes created with these names are picked up automatically by the built-in shaders using the formats listed below. Attributes with any other name are custom: they require a matching declaration in the shader code of a ShaderMaterial. Prefer these constants over spelling the strings out to avoid silent name mismatches.

Constant	Description
kPosition	Vertex position in object space (Float32x3).
kNormal	Vertex normal in object space (Float32x3).
kTexCoord	Texture coordinates (Float32x2).
kColor	Per-vertex color (Float32x3).
kTangent	Tangent with handedness in w for normal mapping (Float32x4).
kInstanceTransform	Per-instance transform matrix (Float32x16, instance rate).
kInstanceColor	Per-instance color (Float32x3, instance rate).

format const Format

Number of float components per element.

const Format format {Format::Float32x1};

name const std::string

Attribute name matching its name in shader code.

const std::string name {};

rate const Rate

Determines whether the data advances per vertex or per instance.

const Rate rate {Rate::Vertex};

Functions

Components() uint32_t

Returns the number of float components per element.

uint32_t BufferAttribute::Components() const;

ElementCount() uint32_t

Returns the number of elements stored in the attribute.

The element count is derived from the data size and the number of components.

uint32_t BufferAttribute::ElementCount() const;

GetData() const std::vector<float>&

Returns a read-only reference to the attribute data.

const std::vector<float>& BufferAttribute::GetData() const;

GetVersion() uint32_t

Returns the data version, incremented on every update.

The renderer compares versions to decide when the attribute needs to be re-uploaded.

uint32_t BufferAttribute::GetVersion() const;

IsValid() bool

Checks whether the attribute has a name and data.

bool BufferAttribute::IsValid() const;

SetData() void

Replaces the attribute data.

The new data must contain the same number of elements as the existing data. Attributes cannot be resized after construction. To change the element count, create a new attribute instead. Data must also be divisible by the number of components implied by the format, otherwise the update is rejected. A successful update marks the attribute for re-upload.

void BufferAttribute::SetData(std::vector<float> data);

Parameter	Description
data	Flat array of floats containing the new attribute data.

Write() void

Overwrites a range of the attribute data in place.

The range [offset, offset + values.size()) must fit within the existing data, otherwise the write is rejected. A successful write marks the attribute for re-upload.

void BufferAttribute::Write(std::size_t offset, std::span<const float> values);

Parameter	Description
offset	Position of the first float to overwrite.
values	Values to copy into the attribute data.