API Reference · Scene and camera

MeshInstance

Namespace: Ava3D

public readonly record struct MeshInstance

One copy of a mesh, and what makes it different from the others.

Why this type exists. Forty crates in a room used to be forty MeshNodes, which is forty draw calls — and a draw call costs between two and ten thousand triangles on the renderers here, measured on both the Metal and the OpenGL paths. The alternative was to merge the forty into one mesh, which costs forty copies of the vertex data and leaves nothing that can be moved, hidden or told apart afterwards. This is the third answer and the one every engine settles on: one mesh, one material, one draw, and a small block of numbers per copy.

Deliberately small, and deliberately not a node. A Node has a name, a parent, children, visibility and a transform that composes — all of which is what makes a scene graph worth having and all of which costs memory and a walk. An instance has none of it. If a copy needs to be found by name, clicked on or lit differently, it wants to be a node; if it is one of four hundred bolts, it wants to be one of these.

The set of fields here is the per-instance parameter block, and it is expected to grow — a texture transform is the next one, so that a repeated crate can wear a different corner of the same map. It grows here rather than by a second mechanism appearing beside it.

Properties

MemberDescription
Vector4 Tint { get; set; }

Linear RGBA multiplied into the material's base colour for this copy alone. White is no change.

The cheapest variation there is and the one that stops forty of a thing reading as one thing drawn forty times. It multiplies rather than replaces so that a material's own colour, its base-colour map and the mesh's vertex colours all still mean what they meant.

Alpha multiplies too, so an instance can fade out without the material knowing.

Matrix4x4 Transform { get; set; }

Where this copy is, relative to the node that carries it.

Methods

MemberDescription
static MeshInstance At(Vector3 position)

A copy at a position, unturned and untinted.

static MeshInstance At(Vector3 position, Quaternion rotation, float scale = 1.0f)

A copy at a position, turned, and scaled evenly.

See also