InstancedMesh

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

[InstancedMesh](/reference/nodes/instanced_mesh) 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()](/reference/nodes/instanced_mesh#function-count-ee94d500)).

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()

vglx::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.

Constructs an instanced mesh.

Factories preferred

InstancedMesh::Create() auto

static auto vglx::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.

Creates a shared pointer to an InstancedMesh object.

Functions

BoundingBox() Box3

Box3 vglx::InstancedMesh::BoundingBox() override

Returns the instanced mesh cluster bounding box.

BoundingSphere() Sphere

Sphere vglx::InstancedMesh::BoundingSphere() override

Returns the instanced mesh cluster bounding sphere.

Count() auto

auto vglx::InstancedMesh::Count()

Returns the number of instances in this mesh.

GetColorAt() constColor

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

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

Returns the color assigned to a specific instance.

GetNodeType() Node::Type

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

Returns node type.

GetTransformAt() constMatrix4

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

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

Returns the transform assigned to a specific instance.

SetColorAt() void

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

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

Sets the color for a specific instance. This color typically multiplies or tints the base material color.

SetTransformAt() void

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

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

Sets the model transform for a specific instance.

SetTransformAt() void

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

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

Sets the model transform for a specific instance from a Transform3. Convenience overload that extracts the matrix from a Transform3.