Rendering#

Three classes draw splats. A SplatObject is one thing to draw. A SplatCollection lists the objects drawn together. A SplatRenderer is the THREE.Mesh that draws a collection: add it to a scene and render from any camera. An app that targets only WebGPU needs only these three. Views (Views and CPU orders) are for drawing a viewpoint with different settings, and for the WebGL2 path.

Code: src/render/SplatCollection.ts and SplatRenderer.ts. The reasons for this design: Multi-splat design.

const model = new THREE.Object3D();
scene.add(model);

const collection = new SplatCollection([
  SplatCollection.arrays(splats, { matrixWorld: model.matrixWorld }),
]);
const splatRenderer = new SplatRenderer({
  renderer,
  collection,
  method: "raygs",
});
scene.add(splatRenderer);

renderer.render(scene, camera);
// Projected and sorted again for this camera
renderer.render(scene, otherCamera);

What a render does#

In each render, the renderer's onBeforeRender:

1. Projects the collection for the render's camera: every object, one dispatch each, into the renderer's projected arrays. Each splat is generated (read from arrays, or computed), transformed by its object's matrixWorld into head space, run through the renderer's modifier if there is one, and projected into a few words plus a sort key (Projection). An XR ArrayCamera's two eyes share one projection.
2. Orders the splats back to front (Sorting):
   • sortMode: "gpu" (WebGPU's default): WgpuSplatSorter compacts and sorts them in the same frame, and the draw is indirect. Nothing is read back, so a new collection or camera draws in the same render.
   • sortMode: "cpu" (WebGL2, or chosen on WebGPU): the applied order of the render's view, which draws the collection that order was sorted for. Nothing is drawn until an order is applied; autoSort sorts and applies orders by itself (Views and CPU orders).
3. Draws every visible splat as a quad, in one draw call (Projection). Colors are clamped at 0 there: stored colors may be negative (LoD merges and spherical harmonics leave them so), and a negative one would decode to NaN or darken a float target.

With the GPU sort nothing depends on the camera between renders, so one renderer draws any number of cameras, viewports, and render targets. Changes take effect at the next render: set collection to change what is drawn, and the settings to change how.

SplatObject#

One thing to draw: count splats of a generator, placed in the world by matrixWorld.

A collection locks generator, data, and count on the object itself (they become read-only properties). matrixWorld, params, and release stay live and can be reassigned at any time. When the same thing is drawn in several collections, views, or renderers, list the same object in each.

Matrices made of a rotation and a uniform scale take the fast path. Any other matrix (a non-uniform scale, a shear, a mirror) is applied to each splat's covariance, without compiling anything new (Generators and modifiers).

SplatCollection#

An immutable, ordered list of objects: which splats to draw.

const collection = new SplatCollection([
  // Stored splats
  SplatCollection.arrays(fileA, { matrixWorld: a.matrixWorld }),
  SplatCollection.arrays(fileB, {
    matrixWorld: b.matrixWorld,
    params: { blurAmount: 0 },
  }),
  // Splats made in a shader
  { generator: ring, count: 4000, matrixWorld: ringObject.matrixWorld },
]);

A collection object is a version. A change in which objects it lists, their order, or their counts needs a new collection. Matrices and params are not part of it: moving an object never needs a new collection. On the CPU sort an order indexes the projected splats of one exact collection, which is why collections are immutable (Multi-splat design).

Types: SplatObject<Data>, AnySplatObject (an object of any data), and MappedObject.

SplatRenderer#

const splatRenderer = new SplatRenderer({
  renderer,
  collection,
  method: "ewa",
  objectParams: { blurAmount: 0.2 },
});

The settings a render uses resolve field by field: the view's when it sets one, else the renderer's (Views and CPU orders). method and sortMode belong to the renderer only, because the method decides the projected arrays and the draw material. Drawing with two methods takes two renderers.

Several renderers#

Two renderers drawn in one render each keep their own projected splats and sorter, because a frame's compute runs before its draws: shared buffers would draw the second renderer's results twice. The quad index buffer, the param uniforms, and the program cache are shared. Splats of different renderers are not sorted together, so use one renderer for everything that overlaps.

Gotchas#

• Each renderer sorts only its own splats: objects that overlap must be in the same renderer's collection to blend correctly.
• A collection made per frame is fine on WebGPU, but on the CPU sort each new collection needs a new sort before it shows. Make a new collection only when the set of objects changes.
• frustumCulled is off: the projection culls splats itself.
• Splats are depth tested against what is drawn before them (opaque meshes) but write no depth. Each quad sits at its splat center's depth, so a splat crossing a mesh is hidden or shown whole. That depth is stored in steps of 1.5e-5 to 3e-5 of the distance (Projection), and works the same with a logarithmic depth buffer (createRenderer({ logarithmicDepthBuffer: true })).
• dispose() renderers you no longer need. A renderer that is garbage-collected undisposed logs a warning, and its objects are released at that point.

Source: docs/rendering.md