Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -2776,6 +2776,35 @@ in-place tests' world, rows given back; two models in a shared pose posed again
(tests/render/data/arm.glb, a skinned strip of two materials); `geometry/emitter-model-live` (a model's emitting
section that is not its first, the model a unit under software traversal).

**A posed skinned model is posed in place under software traversal (2026-11-22).** Under software traversal a mesh
that deforms was written out into the still scene's tree, so every pose rebuilt the scene. Now it is a unit as any
mesh. Its tree has the shape of a tree built once over its model's bind pose, one shape for every placement of the
model (the pass's corners and each such mesh's triangles are in that tree's order), and the boxes of its pose. A new
pose places the model's corners on the CPU, takes the boxes again (`units::refit`), writes the nodes where they lie
and gives the top tree the unit's new bounds; the skinning pass writes the triangles and attributes as under
hardware traversal, without the BLAS input. Hidden, shown and removed, it goes as any unit.
Why the boxes alone: a tree made again for a pose costs sixty times as much (a character of 13,744 triangles, one
core: 3.0 ms against 0.05) and walks 4 to 11 % shorter by its nodes' areas; the clip's first pose is no better a
shape than the bind pose.
Still a rebuild under software traversal: a skinned model added (its triangles and its tree need room, which a
scene has there only with geometry of its own to edit, and which does not grow there).
Measured, software traversal. A game with a character posed every frame: every frame rebuilt the scene, 30.6 ms of
CPU; now none does, 3.2 ms. A crowd of 150 walkers: 2.0 s a frame; now no rebuild, 7.6 ms of commit. What a frame's
trace pays, nothing moving, at 1280 x 720: four characters filling the view, 4.67 ms before and 5.20 now (+11 %),
of which 6.5 % is the scene having units at all (its kernel had no unit walk) and 4.9 % the kept shape (the same
units with trees built for the pose: 4.97); the crowd standing in a street, 85 ms either way.
What a pose costs the CPU there: the corners' positions (0.2 ms a character of 13,744 triangles, one core) and the
boxes (0.05). The crowd's commit is 7.6 ms, against 3.3 under hardware traversal, whose BLASes the GPU builds.
Tests, under both traversals: four models of two files, each mesh's triangles, attributes and previous vertices on
the GPU against the CPU skin; under software traversal each mesh's tree read back (its model's links, a leaf's box
its triangles', an interior node's its children's), its bounds its root's, its unit's leaf of the top tree; the
motion vectors of a pose no longer than the furthest a corner went; one hidden, posed while hidden, shown; one
removed. A unit test of the boxes taken again (corners that are not finite too).
22 mutations of the new logic: 20 fail a test under software traversal, one natively (the pass bound again when the
scene's buffers grow, which they do under hardware traversal alone), and one is equivalent (the pass writing the
BLAS input under software traversal: the writes fall in a spare word no one reads; the constant saves the work).
Three lines that told the traversals apart where no test could were taken out: the pose path is one for both.

**A posed skinned model is added and removed in place (2026-11-21).** A character that comes or goes while the game
runs rebuilt the scene. Now one of a model the scene has is added as the build makes one: a mesh of its own in the
room for edits, its triangles skinned on the CPU once for the pose it comes in, a job of the skinning pass for its
Expand Down
19 changes: 13 additions & 6 deletions docs/RUNTIME.md
Original file line number Diff line number Diff line change
Expand Up @@ -1175,10 +1175,16 @@ procedural objects (`trace_procs`: the ray into the object's space, a tree of it
as vertex colours are; gpu.rs `KernelVariant::flags`): the file's walk, a call at the end of the still walk, and the still
walk's stack declaration taken out ("The stack"). A scene without units has none of it; hardware traversal's
kernel never does.
- Still flattened, as before: meshes that deform (a posed skinned model's), every instance of a scene with more
of them than a top tree holds (2^18), and every instance of an offline render (`prepare`; a live session's scene
goes through `prepare_live`), unless `THREERT_UNITS=1`. `THREERT_UNITS=0` flattens everything, as before this
step (the A/B).
- **A mesh that deforms** (a posed skinned model's) is a unit too. Its tree has the shape of a tree built once over
its model's bind pose, one shape for every placement of the model (the skinning pass's corners and each such
mesh's triangles are in that tree's order), and the boxes of its pose. A new pose places the model's corners on
the CPU, takes the boxes again (`units::refit`: a leaf's from its triangles, an interior node's from its
children), and writes the nodes where they lie; the pass writes the triangles. Made again for a pose, a tree
costs sixty times as much (a character of 13,744 triangles, one core: 3.0 ms against 0.05) and walks 4 to 11 %
shorter by its nodes' areas.
- Still flattened, as before: every instance of a scene with more of them than a top tree holds (2^18), and every
instance of an offline render (`prepare`; a live session's scene goes through `prepare_live`), unless
`THREERT_UNITS=1`. `THREERT_UNITS=0` flattens everything, as before this step (the A/B).

**Edits in place.** The edits that hardware traversal makes in place go through one type (`gpu::Top`: the TLAS and
its BLASes, or the units), so the engine's path is the same under both traversals (`live/edits.rs` `move_instances`,
Expand All @@ -1191,11 +1197,12 @@ its BLASes, or the units), so the engine's path is the same under both traversal
| a mesh of its own is added (a new chunk, a new box) | its triangles and attributes into the edit room in its tree's order, its tree into the mesh range, a record, the top tree |
| a mesh of its own changes (a voxel edit: the chunks it touched) | those meshes' trees made again (the old tree's nodes given back and filled), their records; no other unit is read |
| a mesh is removed | its record cleared, its tree given back and filled, the top tree |
| a skinned model takes a new pose | its mesh's tree's boxes written where they lie (the shape kept), its triangles by the skinning pass, the top tree |
| a skinned model is hidden, shown or removed | its record, the top tree (shown: skinned as it is posed then) |

The scene is rebuilt, as before this step, by: the first instanced mesh of a scene that has none (its kernel has no
unit walk: one rebuild, as hardware traversal's first instance is); an edit of a procedural object; a skinned
model's pose (its triangles are in the still tree; a rigid group's parts are units, posed in place); an instance of
a mesh that deforms; **room that is
model added (hardware traversal adds it in place); **room that is
full** (the edit room and the tree ranges are sized at the build, a quarter of the scene and at least 65,536
triangles and 1,024 records, and do not grow under software traversal: under hardware traversal they do; what an
edit replaces stays behind until the next rebuild, under both; a scene with units and no geometry of its own to
Expand Down
6 changes: 6 additions & 0 deletions renderer/shaders/skin.wgsl
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,9 @@ const CORNER_NORMAL: u32 = 1u;
const CORNER_TANGENT: u32 = 2u;
// Workgroups a row of the dispatch (a dimension holds 65,535).
const ROW: u32 = 32768u;
// Whether the BLASes' input is written too: hardware traversal. Software traversal has none (its meshes' trees take
// their boxes on the CPU), and binds a word there.
override BLAS: bool = true;

@group(0) @binding(0) var<uniform> PP: Params;
// (mesh, its first triangle of the block)
Expand Down Expand Up @@ -166,6 +169,9 @@ fn main(@builtin(workgroup_id) wg: vec3<u32>, @builtin(local_invocation_index) l
verts[k * 3u] = vec4<f32>(c0.p, bitcast<f32>(TRI_DYNAMIC));
verts[k * 3u + 1u] = vec4<f32>(e1, 0.0);
verts[k * 3u + 2u] = vec4<f32>(e2, 0.0);
if !BLAS {
return;
}
// The BLAS's vertices: a triangle that is not finite has no size there.
var q0 = c0.p;
var q1 = c1.p;
Expand Down
44 changes: 31 additions & 13 deletions renderer/src/gpu.rs
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,8 @@ pub struct TopBuild {
pub instances: bool,
/// The dynamic groups' BLASes: their triangles were re-transformed.
pub dynamic: bool,
/// Instanced meshes' BLASes: new meshes, a skinned model's new pose.
/// Instanced meshes' BLASes: new meshes, a skinned model's new pose. (Software traversal: their trees are written
/// by then; the top tree is made over their bounds.)
pub meshes: Vec<u32>,
/// Procedural BLASes an edit made.
pub procs: Vec<PendingProc>,
Expand Down Expand Up @@ -765,6 +766,8 @@ pub struct SkinGpu {
/// Each source's first triangle among the corners (`Scene::skin_sources`), and the palette's matrices in use.
source_first: Vec<u32>,
palette_end: u32,
/// Software traversal: what stands at the BLAS input's binding (the pass writes none there).
no_blas: Option<wgpu::Buffer>,
}

impl SkinGpu {
Expand Down Expand Up @@ -2363,7 +2366,8 @@ impl Gpu {
timings.push(("vcolor_mb".into(), if scene.gpu_vcolors.is_empty() { 0.0 } else { (scene.gpu_vcolors.len() * 4 + room.tris * 12) as f64 / (1 << 20) as f64 }));
let b_attrs = buf_room("attrs", bytemuck::cast_slice(&scene.attrs), room.tris * std::mem::size_of::<crate::scene::GpuTriAttr>(), edit);
// (With units, edits write trees into it: units.rs.)
let b_nodes = buf("nodes", nodes, if scene.units.is_some() { st | wgpu::BufferUsages::COPY_DST } else { st });
// (COPY_SRC: read back by the test that holds a refit tree to its triangles.)
let b_nodes = buf("nodes", nodes, if scene.units.is_some() { st | wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::COPY_SRC } else { st });
// What the triangles hold on the GPU besides their BLASes: vertices (a, e1, e2), attributes, the software BVH's nodes
// (ROADMAP § 6 step 2's table: a meshed representation against voxel data).
timings.push(("tri_data_mb".into(), (std::mem::size_of_val(tri_verts) + std::mem::size_of_val(&scene.attrs[..]) + nodes.len()) as f64 / (1 << 20) as f64));
Expand Down Expand Up @@ -2760,9 +2764,12 @@ impl Gpu {
}
_ => None,
};
// The skinning pass (hardware RT: it writes the BLASes' input), a job each mesh that deforms.
let skin = match &accel {
Some(a) if !scene.retained.skinned.is_empty() => Some(self.skin_pass(scene, a.pool_first, &b_verts, &b_attrs, &a.verts)),
// The skinning pass, a job each mesh that deforms: under hardware traversal (it writes the BLASes' input too),
// and under software traversal where such a mesh is a unit.
let skin = match (&accel, &scene.units) {
_ if scene.retained.skinned.is_empty() => None,
(Some(a), _) => Some(self.skin_pass(scene, a.pool_first, &b_verts, &b_attrs, Some(&a.verts))),
(None, Some(_)) => Some(self.skin_pass(scene, groups.iter().sum(), &b_verts, &b_attrs, None)),
_ => None,
};
self.queue.submit([]);
Expand Down Expand Up @@ -3439,11 +3446,17 @@ impl Gpu {
}

/// The bind groups that hold the scene's buffers again, from `up`'s as they are now (one that grew: the tables,
/// live/edits.rs): the kernel's, the light list's fills' and the particle passes'.
/// live/edits.rs): the kernel's, the light list's fills', the skinning pass's and the particle passes'.
pub fn rebind_scene(&self, up: &mut Uploaded) {
for f in [&mut up.fills.moved, &mut up.fills.particles].into_iter().flatten() {
f.bg = self.emitter_fill_bind_group(&f.runs, &up.verts, &up.heap);
}
if let Some(k) = &mut up.skin {
// (The BLASes' input, or what stands there under software traversal.)
if let Some(blas) = up.accel.as_ref().map(|a| &a.verts).or(k.no_blas.as_ref()) {
k.bg = skin_bind_group(&self.device, &k.pipeline, [&k.params, &k.blocks, &k.table, &k.corners, &k.palette], &up.verts, &up.attrs, blas);
}
}
up.bg = self.scene_bind_group(&SceneBuffers { params: &up.params, verts: &up.verts, attrs: &up.attrs, heap: &up.heap, words: &up.words, prev_verts: &up.prev_verts, accum: &up.accum, parts: &up.bg_parts, accel: up.accel.as_ref(), uniform: up.uniform.as_ref() });
let Some(a) = &up.accel else { return };
let written = ParticleTargets { verts: &up.verts, prev_verts: &up.prev_verts, blas_verts: &a.verts, heap: &up.heap, attrs: &up.attrs };
Expand All @@ -3453,17 +3466,17 @@ impl Gpu {
if let Some(p) = &mut up.gpu_particles {
p.bg = particle_bind_group(&self.device, &p.pipeline, "gpu particles", &[(0, &p.params), (1, &p.table), (7, &p.last), (8, &p.state), (9, &p.spawns), (10, &p.grid)], &written);
}
if let Some(k) = &mut up.skin {
k.bg = skin_bind_group(&self.device, &k.pipeline, [&k.params, &k.blocks, &k.table, &k.corners, &k.palette], &up.verts, &up.attrs, &a.verts);
}
}

/// The skinning pass of `scene`: its pipeline, the models' corners, a job each skinned model, and room for a frame's
/// work and every job's palette.
fn skin_pass(&self, scene: &Scene, pool_first: usize, verts: &wgpu::Buffer, attrs: &wgpu::Buffer, blas_verts: &wgpu::Buffer) -> SkinGpu {
fn skin_pass(&self, scene: &Scene, pool_first: usize, verts: &wgpu::Buffer, attrs: &wgpu::Buffer, blas_verts: Option<&wgpu::Buffer>) -> SkinGpu {
let d = &self.device;
let module = d.create_shader_module(wgpu::ShaderModuleDescriptor { label: Some("skin"), source: wgpu::ShaderSource::Wgsl(include_str!("../shaders/skin.wgsl").into()) });
let pipeline = d.create_compute_pipeline(&wgpu::ComputePipelineDescriptor { label: Some("skin"), layout: None, module: &module, entry_point: Some("main"), compilation_options: Default::default(), cache: self.cache() });
let blas = [("BLAS", if blas_verts.is_some() { 1.0 } else { 0.0 })];
let pipeline = d.create_compute_pipeline(&wgpu::ComputePipelineDescriptor { label: Some("skin"), layout: None, module: &module, entry_point: Some("main"), compilation_options: wgpu::PipelineCompilationOptions { constants: &blas, ..Default::default() }, cache: self.cache() });
let no_blas = blas_verts.is_none().then(|| d.create_buffer(&wgpu::BufferDescriptor { label: Some("skin no blas"), size: 64, usage: wgpu::BufferUsages::STORAGE, mapped_at_creation: false }));
let blas_verts = blas_verts.or(no_blas.as_ref()).unwrap();
let mut source_first = vec![];
let mut at = 0u32;
for source in &scene.skin_sources {
Expand All @@ -3486,7 +3499,7 @@ impl Gpu {
let params = room("skin params", 16, wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST);
let (b_blocks, palette) = (room("skin blocks", blocks as u64 * 8, storage), room("skin palette", matrices as u64 * 48, storage));
let bg = skin_bind_group(d, &pipeline, [&params, &b_blocks, &b_table, &b_corners, &palette], verts, attrs, blas_verts);
SkinGpu { pipeline, bg, params, blocks: b_blocks, table: b_table, corners: b_corners, palette, jobs, source_first, palette_end: matrices }
SkinGpu { pipeline, bg, params, blocks: b_blocks, table: b_table, corners: b_corners, palette, jobs, source_first, palette_end: matrices, no_blas }
}

/// Skins the meshes of `work` (a job and its pose's palette each) on the GPU: their triangles, shading attributes
Expand Down Expand Up @@ -3576,7 +3589,12 @@ impl Gpu {

/// A mesh tree's nodes into the node buffer at its root (`Units::add_tree` placed it).
pub fn write_tree(&self, nodes: &wgpu::Buffer, root: u32, tree: &crate::units::MeshTree) {
self.queue.write_buffer(nodes, root as u64 * 32, bytemuck::cast_slice(&tree.nodes));
self.write_nodes(nodes, root, &tree.nodes);
}

/// A tree's nodes written again where they lie (its boxes taken again, `units::refit`: as many, the same shape).
pub fn write_nodes(&self, nodes: &wgpu::Buffer, root: u32, tree: &[crate::bvh::GpuNode]) {
self.queue.write_buffer(nodes, root as u64 * 32, bytemuck::cast_slice(tree));
}

/// A freed mesh tree's nodes (`Units::drop_tree`: its root and length) are room again: leaves that end a walk
Expand Down
Loading