InstanceData

The GPU buffer behind an entity's mesh instances, for handing to a compute kernel.

Reached via entity.instances once setInstances(...) has run; null before that, or where instancing is unavailable. Vends .read and .write tokens exactly as a splat attribute does, so a kernel can move thousands of instances per frame without rebuilding the transform list in JavaScript.

• Warning: a .write token hands the kernel an uninitialised buffer, not last frame's contents. Whatever the kernel does not write is undefined. To move part of the set, bind .read as an input in the same dispatch and copy the rest across.

• Note: the bounds setInstances(...) computed do not follow a kernel that moves instances outside them. Instances beyond the original extent are culled and lose shadows.

Example:

entity.setInstances(Instances.transforms(spots));
const instances = entity.instances;
const THREADS = 64;
kernel.run({
    uniforms: new Float32Array([scene.time, instances.count]),
    inputBuffers:  { src: instances.read },
    outputBuffers: { dst: instances.write },
    threadGroups: [Math.ceil(instances.count / THREADS), 1, 1],
    threadsPerThreadgroup: [THREADS, 1, 1]
});

Properties

count

• Type: number
• How many instances the entity draws. Size a dispatch from this, and guard on it in the kernel: a thread past the end writes into memory the renderer is using.

localToMesh

• Type: Array<any>
• Converts a distance or position from metres into the buffer's units. Multiply an offset in metres by its scale, element 0, before adding it to an instance's translation. The inverse of meshToLocal, same 16-number column-major layout.

meshToLocal

• Type: Array<any>
• Converts a distance or position from the buffer's units into metres, as 16 numbers in column-major order, ready to hand a kernel as uniforms. Its scale, element 0, is the conversion factor on its own.

read

• Type: EngineBufferBinding
• Token tagged as "read into kernel". Returns the transforms as the renderer last saw them.

write

• Type: EngineBufferBinding
• Token tagged as "write from kernel". The buffer arrives uninitialised, so the kernel has to write every element it is dispatched over. One float4x4 per instance, column-major, so column 3 is the translation, in the instanced mesh's own space rather than the space rep.setInstances(...) accepts.