GPU-driven frustum and LOD culling for massive instanced rendering.

Architecture

• Runs entirely on GPU via compute shaders (TSL)
• Tests each instance against camera frustum and distance
• Compacts visible instances into packed survivor buffer
• Writes indirect draw args (instanceCount) atomically
• Optional depth sorting for transparent objects

Culling Modes

• Frustum Culling: Excludes instances outside camera view
• LOD Sampling: Continuous distance-based sampling (reduces far instances)

LOD System

• Purpose: Reduce draw density smoothly with distance by keeping each instance with probability pKeep.
• Near/Far: lodNear defines where LOD begins. lodFar defines where range mode reaches full falloff.
• Modes (lodMode):
  • Disabled (LOD_MODE_DISABLED): LOD sampling is off.
  • Range (LOD_MODE_RANGE): Smoothstep falloff between lodNear and lodFar. pKeep = 1 - smoothstep( lodNear, lodFar, d )
  • Exp (LOD_MODE_EXP): Exponential density falloff starting at lodNear. pKeep = exp( -density^2 * (d - lodNear)^2 ) Note: lodNear shifts the start of the exp curve; increasing it delays the falloff.
• Density Parameter: lodDensity acts as exp density (smaller = slower decay).
• Sampling: Each instance is kept if hash(instanceId) < pKeep, giving stable stochastic thinning.
• Compatibility: Internally computes stepF = sqrt(1 / max(pKeep, eps)) for legacy outputs.

Performance

• O(N) GPU parallel culling vs O(N) CPU serial testing
• Zero CPU overhead after setup
• Indirect draw eliminates CPU→GPU instance data sync
• Typical 10-100x performance gain for large instance counts

import { ComputeInstanceCulling, instanceCullingIndex as index } from '@three-blocks/core';

// Create instanced mesh
const instancedMesh = new THREE.InstancedMesh(
  new THREE.BoxGeometry(),
  new THREE.MeshBasicNodeMaterial(),
  count
);

// Create culler
const culler = new ComputeInstanceCulling(instancedMesh, renderer);

// Use culling index instead of instanceIndex
material.positionNode = rotate(positionLocal, angle.add(hash(index(culler))))

Example: Custom positionNode with TSL

When using positionNode with GPU culling, the instanceCulling transform is applied automatically after your positionNode. Use instanceCullingIndex to access per-instance data like random seeds or animation offsets:

import { ComputeInstanceCulling, instanceCullingIndex } from '@three-blocks/core';
import { time, hash, rotate, positionLocal, normalLocal, transformNormalToView } from 'three/tsl';

const count = 10000;
const instancedMesh = new THREE.InstancedMesh(
  new THREE.BoxGeometry(),
  new THREE.MeshNormalNodeMaterial(),
  count
);

// Setup GPU culling
const culler = new ComputeInstanceCulling(instancedMesh, renderer);

// Access the culled instance index for per-instance variation
const culledIndex = instanceCullingIndex(culler);

// Compute per-instance rotation angle based on time and instance hash
const angle = time.mul(0.6).add(hash(culledIndex).mul(Math.PI * 2));

// Apply rotation to position (runs BEFORE instance matrix transform)
instancedMesh.material.positionNode = rotate(positionLocal, angle);

// Transform normals to match the rotation
instancedMesh.material.normalNode = transformNormalToView(
  rotate(normalLocal, angle)
).normalize();

Example: Advanced culling with custom visibility logic

For advanced use cases, you can access the culler's internal buffers directly:

import { ComputeInstanceCulling } from '@three-blocks/core';
import { storage, instanceIndex, If, uint } from 'three/tsl';

const culler = new ComputeInstanceCulling(instancedMesh, renderer, {
  enabled: true,
  sortObjects: true  // Enable depth sorting for transparency
});

// Access culling parameters
culler.lodNear.value = 50;         // LOD near radius
culler.lodFar.value = 400;         // LOD far radius (range mode)
culler.lodMode.value = LOD_MODE_RANGE;
culler.lodDensity.value = 0.00025; // Exp density (exp mode)

// Read back survivor count for debugging
const args = await culler.readIndirectArgs();
console.log(`Visible instances: ${args[1]} / ${count}`);