Render3D. InstancedMesh3D

InstancedMesh3D - Many copies of one mesh drawn as one call, with their transforms kept on the GPU

  • For big sets that mostly stay put: an instance costs nothing per frame until it changes, so a hundred thousand trees cost what one tree does; objects and drawMesh batch by themselves too, but rebuild their batch every frame
  • setMatrixAt and setColorAt change one instance, and only the changed range uploads before the next draw
  • The instances are in world space; the object's own pos3D, rotation3D and scale3D do not move them
  • The whole set is culled by one bounding sphere around the origin, and casts and receives shadows like any object
  • The object's flags cover the whole set, one emissive, one tileInfo, one shader; only the colors are per instance
  • A mirrored instance, one with a negative scale, shows its inside unless the mesh is doubleSided
  • A transparent set draws in one go in the transparent stage, its instances are not sorted against each other

Constructor

new InstancedMesh3D(mesh, count, tileInfoopt, coloropt)

Create a set of instances of a mesh, each at the origin in the object's color until it is set

Parameters:
NameTypeAttributesDescription
meshMesh
countnumber

How many instances there is room for, all of them draw until count is lowered

tileInfoTileInfo | TextureInfo<optional>

Texture for all of them

colorColor<optional>

The color they start with

Source
Example
const forest = new InstancedMesh3D(treeMesh, 1000);
for (let i = 0; i < 1000; ++i)
    forest.setMatrixAt(i, buildMatrix(randomGroundPos(), vec3(0, rand(2*PI), 0)));

Extends

  • EngineObject3D

Members

count

Properties
TypeDescription
number

How many instances draw, the first ones, up to the count it was made with

Source

dirtyEnd

Properties
TypeDescription
number

One past the last instance to upload, so nothing uploads when it is not past dirtyStart

Source

dirtyStart

Properties
TypeDescription
number

First instance to upload before the next draw

Source

instanceData

Properties
TypeDescription
Float32Array

The per instance values the shader reads, 24 floats each: the matrix, the color and the uv rect; edit it directly and call markDirty for the instances changed

Source

maxCount

Properties
TypeDescription
number

How many instances it was made with

Source

radius

Properties
TypeDescription
number

Radius of the sphere around the origin that holds every instance set so far, for culling

Source

Methods

destroy(immediateopt)

Destroy the set and free its GPU buffer

Parameters:
NameTypeAttributesDescription
immediateboolean<optional>
Source

getMatrixAt(i) → {Matrix4}

The matrix of an instance

Parameters:
NameTypeDescription
inumber
Source
Returns:
Type: 
Matrix4

markDirty(i)

Note that an instance changed, so it uploads before the next draw; setMatrixAt and setColorAt call this

Parameters:
NameTypeDescription
inumber
Source

render3D()

Draws every instance as one call, uploading the ones that changed first

Source

setColorAt(i, color)

Color an instance

Parameters:
NameTypeDescription
inumber
colorColor
Source

setMatrixAt(i, matrix)

Place an instance, in world space

Parameters:
NameTypeDescription
inumber
matrixMatrix4
Source