InstancedMesh

A mesh node that renders many instances of the same geometry efficiently.

InstancedMesh draws multiple copies of a single geometry-material pair using per‑instance transforms and optional per‑instance colors. This is ideal for large numbers of similar objects (e.g., vegetation, crowds, particles) with different positions or tints while keeping draw calls low.

Each instance can have:a transform matrix (model matrix)a color (for material tinting)

Instances are addressed by zero‑based index in the range [0, Count()).

const auto geometry = BoxGeometry::Create({1.0f, 1.0f, 1.0f});
const auto material = PhongMaterial::Create(0xFFFFFF);

auto boxes = vglx::InstancedMesh::Create(geometry, material, 2500);

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

scene->Add(boxes);

INFO

Derives from Mesh and inherits all public properties and methods.

Construction

Constructors

InstancedMesh()

Constructs an instanced mesh.

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

Parameter	Description
geometry	Shared pointer to a geometry for all instances.
material	Shared pointer to a material for all instances.
count	Number of instances to allocate.

Factories preferred

InstancedMesh::Create() auto

Creates a shared pointer to an InstancedMesh object.

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

Parameter	Description
geometry	Shared pointer to a geometry for all instances.
material	Shared pointer to a material for all instances.
count	Number of instances to allocate.

Functions

BoundingBox() Box3

Returns the instanced mesh cluster bounding box.

Box3 InstancedMesh::BoundingBox() override;

BoundingSphere() Sphere

Returns the instanced mesh cluster bounding sphere.

Sphere InstancedMesh::BoundingSphere() override;

Count() auto

Returns the number of instances in this mesh.

auto InstancedMesh::Count();

GetColorAt() constColor

Returns the color assigned to a specific instance.

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

Parameter	Description
idx	Instance index in [0, Count()).

GetNodeType() Node::Type

Returns node type.

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

GetTransformAt() constMatrix4

Returns the transform assigned to a specific instance.

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

Parameter	Description
idx	Instance index in [0, Count()).

SetColorAt() void

Sets the color for a specific instance.

This color typically multiplies or tints the base material color.

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

Parameter	Description
idx	Instance index in [0, Count()).
color	Color to assign.

SetTransformAt() void

Sets the model transform for a specific instance.

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

Parameter	Description
idx	Instance index in [0, Count()).
matrix	Transform matrix to assign.

SetTransformAt() void

Sets the model transform for a specific instance from a Transform3.

Convenience overload that extracts the matrix from a Transform3.

void InstancedMesh::SetTransformAt(std::size_t idx, Transform3& transform);

Parameter	Description
idx	Instance index in [0, Count()).
transform	Transform providing the model matrix.