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 optional colors. This dramatically improves performance when drawing large numbers of identical objects by reducing CPU overhead and state changes.

Each instance is addressed by a zero-based index in the range . Transforms and colors can be queried or updated individually.

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

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) {
    Transform3 t {};
    t.SetPosition({i * 2.0f - 49.0f, j * 2.0f - 49.0f, 0.0f});
    boxes->SetTransformAt(j * 50 + i, t);
  }
}

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.

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

BoundingBox() Box3

Computes a bounding box that encloses all instances.

Box3 InstancedMesh::BoundingBox() override;

BoundingSphere() Sphere

Computes a bounding sphere that encloses all instances.

Sphere InstancedMesh::BoundingSphere() override;

Count() size_t

Returns the number of allocated instances.

size_t InstancedMesh::Count();

GetColorAt() constColor

Returns the per-instance color at the given index.

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

Parameter	Description
idx	Instance index.

GetNodeType() Node::Type

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

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

GetTransformAt() constMatrix4

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

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

Parameter	Description
idx	Instance index.

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.

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.

SetTransformAt() void

Convenience overload that accepts a Transform3.

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

Parameter	Description
idx	Instance index.
transform	World-space transform object to assign.