InstancedMesh

Renderable node that draws many copies of the same mesh efficiently.

InstancedMesh stores a single geometry/material pair and renders it multiple times in a single draw call using per-instance transforms and colors. This dramatically improves performance when drawing large numbers of identical objects by reducing CPU overhead and state changes.

Per-instance data is stored in instance-rate buffer attributes. Transforms default to identity and colors to white. Each instance is addressed by a zero-based index. Updates through SetTransformAt and SetColorAt mark the underlying attribute for re-upload.

Custom per-instance data can be added with AddInstanceAttribute and consumed by declaring a matching attribute in the shader code of a ShaderMaterial. The built-in materials only use the instance transform and color attributes.

const auto geometry = vglx::BoxGeometry::Create({1.0f, 1.0f, 1.0f});
const auto material = vglx::PhongMaterial::Create({.color = 0xFFFFFFu});

auto boxes = my_scene->Add(vglx::InstancedMesh::Create(
  geometry, material, 2500
));

for (auto i = 0; i < 50; ++i) {
  for (auto j = 0; j < 50; ++j) {
    vglx::Transform3 t {};
    t.SetPosition({i * 2.0f - 49.0f, j * 2.0f - 49.0f, 0.0f});
    boxes->SetTransformAt(j * 50 + i, t.Get());
  }
}

Out-of-range indices are invalid and result in undefined behavior. Culling is performed using a single bounding volume that determines visibility of the instance set as a whole.

INFO

Derives from Mesh and inherits all public properties and methods.

Construction

Constructors

InstancedMesh()

Constructs an instanced mesh.

Instance transforms are initialized to identity and instance colors to white.

InstancedMesh::InstancedMesh(std::shared_ptr<Geometry> geometry, std::shared_ptr<Material> material, std::size_t count);

Parameter	Description
geometry	Shared geometry used for every instance.
material	Shared material used for every instance.
count	Number of instances to allocate.

Factories preferred

InstancedMesh::Create() std::unique_ptr<InstancedMesh>

Creates an instance of InstancedMesh.

static std::unique_ptr<InstancedMesh> InstancedMesh::Create(std::shared_ptr<Geometry> geometry, std::shared_ptr<Material> material, std::size_t count);

Parameter	Description
geometry	Shared geometry used across all instances.
material	Shared material used across all instances.
count	Number of instances to allocate.

Functions

AddInstanceAttribute() void

Adds a custom per-instance attribute to this mesh.

The attribute must have an instance rate, a unique name within the mesh and an element count that matches the instance count. Attributes that violate these constraints are reported and rejected.

void InstancedMesh::AddInstanceAttribute(std::shared_ptr<BufferAttribute> attribute);

Parameter	Description
attribute	Buffer attribute to add.

BoundingBox() Box3 virtual

Computes a bounding box that encloses all instances.

Box3 InstancedMesh::BoundingBox() override;

BoundingSphere() Sphere virtual

Computes a bounding sphere that encloses all instances.

Sphere InstancedMesh::BoundingSphere() override;

ColorAt() Color

Returns the per-instance color at the given index.

Color InstancedMesh::ColorAt(std::size_t idx) const;

Parameter	Description
idx	Instance index.

GetCount() size_t

Returns the number of allocated instances.

size_t InstancedMesh::GetCount() const;

GetDrawCount() size_t

Returns the number of instances to draw.

size_t InstancedMesh::GetDrawCount() const;

GetInstanceAttribute() std::shared_ptr<BufferAttribute>

Returns the instance attribute with the given name.

std::shared_ptr<BufferAttribute> InstancedMesh::GetInstanceAttribute(std::string_view name) const;

Parameter	Description
name	Attribute name to look up.

GetInstanceAttributes() const std::vector<std::shared_ptr< BufferAttribute> >&

Returns the list of instance attributes stored on this mesh.

const std::vector<std::shared_ptr< BufferAttribute> >& InstancedMesh::GetInstanceAttributes() const;

GetNodeType() Node::Type virtual

Identifies this node as Node::Type::InstancedMesh.

Type vglx::InstancedMesh::GetNodeType() const override;

SetColorAt() void

Sets the per-instance color at the given index.

void InstancedMesh::SetColorAt(std::size_t idx, const Color& color);

Parameter	Description
idx	Instance index.
color	New color for the instance.

SetDrawCount() void

Sets the number of instances to draw.

void InstancedMesh::SetDrawCount(std::size_t draw_count);

Parameter	Description
draw_count	Number of instances. Must not exceed the initial allocation.

SetTransformAt() void

Sets the per-instance transform at the given index.

void InstancedMesh::SetTransformAt(std::size_t idx, const Matrix4& matrix);

Parameter	Description
idx	Instance index.
matrix	A world-space transform matrix for the instance.

TransformAt() Matrix4

Returns the per-instance transform matrix at the given index.

Matrix4 InstancedMesh::TransformAt(std::size_t idx) const;

Parameter	Description
idx	Instance index.