Feature Library

CPU culling for instanced batches

Not measured yet
A still of the CPU culling for instanced batches demo
Still
The live demo starts when it’s in view.Toggle culling to compare submitted plants · drag to pause the camera · Next viewpoint works with reduced motion

Cull spatial batches with one enclosing sphere, test individual instances only at the view edge, and pack visible rows in stable source order.

Unchanged selections skip copies and uploads; empty batches can skip draws entirely. Matrices, colours and other Float32 instance attributes share the same selection.

What it costs a frame

Not measured yet.

What it needs

Renders with
WebGPU or WebGLWebGPU where there is one, WebGL2 where there is not.
Your browser
Runs hereNo WebGPU needed
Depends on
three.js 0.187.0No other packages
With an agent
install("instance-cull")Your coding agent reads its pitfalls and installs it through the library’s MCP server. Set it up

What it’s for

  1. Draw only the visible plants in a resident landscape
  2. Compact several instance attributes without losing row identity
  3. Avoid buffer uploads when the visible set is unchanged
  4. Skip entire off-screen instance batches without compute dispatches

Pitfalls, in brief

  1. CullSet sphere centres/radii and extracted planes are world-space.
  2. Keep immutable source-order arrays separate from all destination attributes.
  3. Call invalidate() after source rows, sphere positions/radii or set.count change.
  4. InstanceCullBatch accepts dedicated non-interleaved Float32 InstancedBufferAttributes with meshPerAttribute = 1.
  5. Apply count and visibility yourself: mesh.count = Math.max(1, batch.count), mesh.visible = batch.count > 0.
6 more in brief
  1. Disable built-in mesh frustum culling or maintain a conservative bound over every possible source row.
  2. Do not use a main-camera selection for shadows, reflections or a second camera: off-screen instances can affect those views.
  3. viewPlanes updates the camera and its parents; updateProjectionMatrix() remains the host responsibility after FOV, aspect or clipping edits. viewChanged/viewNow compare world poses.
  4. A batch sphere shortcut is useful for spatially coherent groups.
  5. The CPU approach avoids per-group dispatch overhead and empty indirect draws, but still spends time scanning boundary groups, copying changed rows and retaining a source copy.
  6. The demo has 10,000 plants at high, 6,400 at medium and 2,500 at low, all in 25 batches.
11 pitfalls in full, the hook-up guide, the module source and its tests come with the part.

Where it comes from

From HaTac. Adapted from published work, named below.

Hannes Andersson: Source sphere culling, stable batch compaction and the CPU-versus-compute profiling rationale.

instancingcullingfrustumCPUcompactionplantsbatchesuploadsperformance

Near it in the frame