Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
3eca03a
A model's corners and palette: what a skinning pass reads, and an aut…
yujiaxu-ops Nov 20, 2026
fc99143
Meshes that deform are skinned on the GPU
yujiaxu-ops Nov 21, 2026
f61a459
Docs: meshes that deform are skinned on the GPU
yujiaxu-ops Nov 21, 2026
a6a8f9a
Merge remote-tracking branch 'origin/main' into gpu-skinning
yujiaxu-ops Nov 21, 2026
e047b92
Every posed skinned model is a mesh of its own
yujiaxu-ops Nov 21, 2026
9d5d282
Comments: a posed skinned model's mesh is its own
yujiaxu-ops Nov 21, 2026
8ba3d42
Docs: a posed skinned model is a mesh of its own
yujiaxu-ops Nov 21, 2026
8211911
A posed model's move is a move, and the skinning test made to see more
yujiaxu-ops Nov 21, 2026
622bf0f
The skinning test's scene made less regular: two mutants it did not see
yujiaxu-ops Nov 21, 2026
446ef92
Merge branch 'gpu-skinning' into skinned-own-mesh
yujiaxu-ops Nov 21, 2026
797f019
A posed skinned model hidden under software traversal: the test of th…
yujiaxu-ops Nov 21, 2026
1f98689
Docs: the own-mesh step's tests and mutations
yujiaxu-ops Nov 21, 2026
54cde25
Merge remote-tracking branch 'origin/main' into skinned-own-mesh
yujiaxu-ops Nov 21, 2026
ef6b9e7
A posed skinned model is removed in place
yujiaxu-ops Nov 21, 2026
7512c77
Merge remote-tracking branch 'origin/main' into skinned-add-remove
yujiaxu-ops Nov 21, 2026
e97e9fb
A deforming mesh's previous vertices are found through its instance
yujiaxu-ops Nov 21, 2026
d402234
A posed skinned model is added in place
yujiaxu-ops Nov 21, 2026
b615c59
Docs: a posed skinned model is added and removed in place
yujiaxu-ops Nov 21, 2026
9c841e6
The add test made to see eight mutants
yujiaxu-ops Nov 21, 2026
8062e9d
The kernel's read of a deforming mesh's previous vertices is a featur…
yujiaxu-ops Nov 21, 2026
fd86e92
A skinned model added beside particle systems: the test of the rebuild
yujiaxu-ops Nov 21, 2026
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
35 changes: 35 additions & 0 deletions docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -2776,6 +2776,41 @@ 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 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
next poses (the pass's table grows), skinned from the model's one copy of its corners. Removed, its instance is out
(the build's or an edit's); one an edit placed gives back its triangles, its record and rows, its previous vertices
and its job's slot, and the next one placed takes them.
A mesh that deforms has its previous frame's vertices where its instance says (`scene::Instance::prev`, in its
record): the kernel found them by the triangle's place among the dynamic triangles, which a mesh in the room does
not have. Their buffer grows as the triangles' does. The kernel's read is a feature of its own (`F_DEFORM`: a scene
with a mesh that deforms): in every kernel, a scene without one paid 0.6 % of its GPU frame for it (a flight over a
city, five pairs of five).
A fault found on the way: what a batch changed of an object (a pose, a move, its visibility) stayed when the same
batch removed it, and the renderer rebuilt for an object it could not find. It goes with the object now.
Still a rebuild: a skinned model the scene has not (its materials and textures load with one), one whose pose
mirrors other primitives than the scene's, one added hidden and shown later, one added in a scene with particle
systems (the rooms for edits do not grow there, for any edit: the particle passes hold the scene's buffers), and
any under software traversal.
Measured, hardware traversal, a game that spawns a character every half second and takes the oldest away (twelve
at most): each spawn and each despawn rebuilt the scene, 31 times in 16 s, 46 ms each (the longest frame 79 ms);
now none does, a frame that spawns or despawns commits in 3.5 ms (4.9 at most) and the longest frame is 21 ms. The
frame between is the same: eight spawned and then none, at 1280 x 720, the GPU's frame is 10.6 ms either way (the
trace 3.5, the BLAS builds 0.58).
Tests: one added against the CPU skin (triangles, attributes, BLAS input, previous vertices) and a build's picture;
its motion vectors at a new pose against a built one's, none longer than the furthest a corner went; moved, hidden,
shown; 40 added at once (every room grows), posed on, half of them hidden and shown; 24 more in a commit that
grows the pass's buffers alone; previous vertices kept mesh by mesh (a model removed before a frame is drawn, two
whose triangles are neighbours and whose previous vertices are not, one posed twice between frames); one removed
and the next added in what it had; a built one removed (shown, hidden, posed in the same batch); the three that
rebuild. The pictures are compared with the build's frames counted from the live view's (a frame's samples go by
its number: at another count a picture of many thin models is two thirds of a step from itself).
36 mutations of the new logic: 33 fail a test natively, two under software traversal, and one is equivalent (the
CPU's copy of an added model's triangles: a fallback no path reads while the model loads). Eight did not at first:
the scenes had no moving triangles before the meshes, motion vectors were compared with a build's alone (wrong
alike in both), other rooms grew in every commit that grew the pass's, and no frame was skipped between two edits.

**A posed skinned model is a mesh of its own (2026-11-21).** Models in the same pose (the same clip and time) shared
one mesh, found by the build; one of them taking another pose had to leave it, and that rebuilt the scene (and a
rebuild grouped whichever models then happened to be in one pose). A model alone in its pose was no mesh at all:
Expand Down
13 changes: 11 additions & 2 deletions renderer/shaders/pathtrace.wgsl
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ const F_BACKGROUND: u32 = 2097152u; // scene.background (`sky_mis`)
const F_VCOLOR: u32 = 4194304u; // vertex colours (`vcolor`)
const F_GRID: u32 = 33554432u; // density grids (`vgrid`)
const F_IFUNC: u32 = 268435456u; // a material function on an instanced mesh: `mat_in_at` places the triangle by its instance
const F_DEFORM: u32 = 1073741824u; // a mesh that deforms among the instances: its previous vertices by its record (the first hit's motion)
const F_IGLASS: u32 = 536870912u; // glass among an instance's other sections: a shadow ray steps through it by its row (trace_hw.wgsl), a unit's walk skips it
const F_LISTS: u32 = 134217728u; // light tiles (`lt_list_start`): a scene whose shadow-casting local lights are resampled
fn has(f: u32) -> bool { return (FEAT & f) != 0u; }
Expand Down Expand Up @@ -3804,7 +3805,8 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
let ti = hit.tri;
// The first dynamic triangle is the first of traversal group 4 (a u32: an index carried as f32 bits would be a
// denormal below 2^23, which a driver may flush to zero).
// Dynamic triangles (and deforming instanced meshes, in model space) keep their previous vertices.
// Dynamic triangles keep their previous vertices, as they lie from the first dynamic one (`kp`); a deforming
// instanced mesh keeps its own in model space, where its instance's record says.
let deforms = LIVE && P.motion.x > 0.5 && !is_proc(hit) && ti >= P.group_first[1].x && (bitcast<u32>(tri_verts[ti * 3u].w) & TRI_DYNAMIC) != 0u;
let kp = (ti - P.group_first[1].x) * 3u;
if (LIVE && P.motion.x > 0.5 && is_proc(hit)) {
Expand All @@ -3820,7 +3822,14 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
let r = instance_at(hit.inst);
if (deforms || any(r.p0 != r.m0) || any(r.p1 != r.m1) || any(r.p2 != r.m2)) {
var lp = vec4<f32>(tri_verts[ti * 3u].xyz + tri_verts[ti * 3u + 1u].xyz * hit.u + tri_verts[ti * 3u + 2u].xyz * hit.v, 1.0);
if (deforms) { lp = vec4<f32>(prev_verts[kp].xyz + prev_verts[kp + 1u].xyz * hit.u + prev_verts[kp + 2u].xyz * hit.v, 1.0); }
// (A deforming mesh's previous vertices are where its record says, n2.w, in its triangles' order:
// a mesh an edit placed has them elsewhere than its triangles lie. F_DEFORM: a scene with such a
// mesh; elsewhere nothing here deforms, and the read is as the dynamic triangles'.)
if (deforms) {
var kq = kp;
if (has(F_DEFORM)) { kq = (bitcast<u32>(r.n2.w) + ti - r.info.x) * 3u; }
lp = vec4<f32>(prev_verts[kq].xyz + prev_verts[kq + 1u].xyz * hit.u + prev_verts[kq + 2u].xyz * hit.v, 1.0);
}
mv = vec4<f32>(vec3<f32>(dot(r.p0, lp), dot(r.p1, lp), dot(r.p2, lp)) - s.p, 1.0);
}
} else if (deforms) {
Expand Down
64 changes: 61 additions & 3 deletions renderer/src/gpu.rs
Original file line number Diff line number Diff line change
Expand Up @@ -762,6 +762,58 @@ pub struct SkinGpu {
palette: wgpu::Buffer,
/// Per job, and how many matrices its palette is.
jobs: Vec<(SkinJob, u32)>,
/// 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,
}

impl SkinGpu {
/// (Tests: the bytes of the jobs' table, the palettes' and the blocks' buffers.)
#[cfg(test)]
pub fn rooms(&self) -> [u64; 3] {
[self.table.size(), self.palette.size(), self.blocks.size()]
}

/// The job of a mesh an edit placed, at `slot` (a new one, or one whose mesh is gone): its triangles from `first`
/// in the scene's, skinned from `source`'s corners by a palette of `palette_len` matrices. The pass's buffers
/// grow with it (the table written again whole; the palette's and the blocks' contents are a dispatch's, and
/// need no copy). True where one was made again: the pass's bind group is then to be (`Gpu::rebind_scene`).
pub fn set_job(&mut self, d: &wgpu::Device, q: &wgpu::Queue, slot: usize, first: u32, count: u32, source: u32, palette_len: u32) -> bool {
let room = |label: &str, size: u64| d.create_buffer(&wgpu::BufferDescriptor { label: Some(label), size, usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST, mapped_at_creation: false });
let mut grew = false;
// Its palette: the slot's own where that is as long, else new room at the end.
let palette = match self.jobs.get(slot) {
Some((j, len)) if *len == palette_len => j.palette,
_ => {
self.palette_end += palette_len;
self.palette_end - palette_len
}
};
let job = SkinJob { first, count, source: self.source_first[source as usize], palette };
if slot < self.jobs.len() {
self.jobs[slot] = (job, palette_len);
} else {
self.jobs.push((job, palette_len));
}
if self.jobs.len() as u64 * 16 > self.table.size() {
self.table = room("skin jobs", self.jobs.len() as u64 * 32);
let table: Vec<SkinJob> = self.jobs.iter().map(|j| j.0).collect();
q.write_buffer(&self.table, 0, bytemuck::cast_slice(&table));
grew = true;
} else {
q.write_buffer(&self.table, slot as u64 * 16, bytemuck::bytes_of(&job));
}
if self.palette_end as u64 * 48 > self.palette.size() {
self.palette = room("skin palette", self.palette_end as u64 * 96);
grew = true;
}
let blocks: u64 = self.jobs.iter().map(|j| j.0.count.div_ceil(SKIN_BLOCK) as u64).sum();
if blocks * 8 > self.blocks.size() {
self.blocks = room("skin blocks", blocks * 16);
grew = true;
}
grew
}
}

fn skin_bind_group(d: &wgpu::Device, pipeline: &wgpu::ComputePipeline, own: [&wgpu::Buffer; 5], verts: &wgpu::Buffer, attrs: &wgpu::Buffer, blas_verts: &wgpu::Buffer) -> wgpu::BindGroup {
Expand Down Expand Up @@ -1722,6 +1774,10 @@ pub const F_IFUNC: u32 = 1 << 28;
/// software traversal skips such a triangle of a unit). Compiled out where no instance mixes the two: one that is all
/// glass is out of a shadow ray's way by its mask (`scene::rows_cast`).
pub const F_IGLASS: u32 = 1 << 29;
/// A mesh that deforms among the instances (a posed skinned model's): the first hit's motion takes its previous
/// frame's vertices from where its instance's record says. Compiled out where no mesh deforms: with the read in every
/// kernel a scene without one paid for it (a flight over a city: frame GPU +0.6 %, five pairs of five).
pub const F_DEFORM: u32 = 1 << 30;
/// Whether a scene with more such lights has the light tiles (`F_LISTS`): `THREERT_LIGHT_TILES=1|0`, else everywhere
/// but Android. On Adreno 740 they took OpenStrikeRT's Foundry from 31 to 48 ms a frame (249 x 140, one bounce):
/// there the lights are resampled as in a scene of fewer, unguided (docs/RUNTIME.md "Android").
Expand Down Expand Up @@ -1786,7 +1842,7 @@ pub fn environment_features(fog: Option<&crate::desc::Fog>, background: bool, ae
/// Kernel features of the scene's structure, which parameter edits do not change: F_INST and F_MASKED for the
/// instanced meshes (cutout triangles among them), F_MEDIA for participating media (F_HMEDIA for homogeneous ones),
/// F_PEMIT for opaque particles, F_PROC for procedural geometry, F_TINT for instance colours, F_IFUNC for a material
/// function on an instanced mesh, F_IGLASS for glass on one.
/// function on an instanced mesh, F_IGLASS for glass on one, F_DEFORM for a mesh that deforms.
pub fn instance_features(scene: &Scene) -> u32 {
// (F_GRID also for a volume function that calls `vgrid` on a node without a grid: it reads zeros.)
let grid = !scene.grids.is_empty() || (!scene.media.is_empty() && scene.volume_fns.iter().any(|(_, code, helpers)| code.contains("vgrid(") || helpers.contains("vgrid(")));
Expand All @@ -1803,7 +1859,8 @@ pub fn instance_features(scene: &Scene) -> u32 {
let ifunc = if scene.rows.iter().any(|r| function(crate::scene::row_material(r))) { F_IFUNC } else { 0 };
let iglass = if mixed_glass { F_IGLASS } else { 0 };
let masked = any_row(crate::scene::ROW_CUTOUT);
media | particles | ifunc | iglass | F_INST | if masked { F_MASKED } else { 0 } | if scene.units.is_some() { F_UNITS } else { 0 }
let deform = if scene.meshes.iter().any(|m| m.deforms) { F_DEFORM } else { 0 };
media | particles | ifunc | iglass | deform | F_INST | if masked { F_MASKED } else { 0 } | if scene.units.is_some() { F_UNITS } else { 0 }
}

/// `features` from the parts parameter edits change (the materials; `environment`: `environment_features`), and the
Expand Down Expand Up @@ -3429,7 +3486,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 }
SkinGpu { pipeline, bg, params, blocks: b_blocks, table: b_table, corners: b_corners, palette, jobs, source_first, palette_end: matrices }
}

/// Skins the meshes of `work` (a job and its pose's palette each) on the GPU: their triangles, shading attributes
Expand Down Expand Up @@ -3786,6 +3843,7 @@ mod tests {
("F_GLASS", F_GLASS), ("F_COAT", F_COAT), ("F_HUGE", F_HUGE), ("F_INST", F_INST), ("F_MEDIA", F_MEDIA), ("F_PEMIT", F_PEMIT),
("F_HMEDIA", F_HMEDIA), ("F_PROC", F_PROC), ("F_TINT", F_TINT), ("F_UNLIT", F_UNLIT), ("F_BACKGROUND", F_BACKGROUND),
("F_VCOLOR", F_VCOLOR), ("F_AERIAL", F_AERIAL), ("F_GRID", F_GRID), ("F_LISTS", F_LISTS), ("F_IFUNC", F_IFUNC), ("F_IGLASS", F_IGLASS),
("F_DEFORM", F_DEFORM),
];
let mut seen = 0u32;
for (name, bit) in all {
Expand Down
7 changes: 7 additions & 0 deletions renderer/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -601,6 +601,13 @@ pub fn prepare_as(hwrt: bool, units: bool, sc: &mut scene::Scene, timings: &mut
tri_verts.push([e2.x, e2.y, e2.z, 0.0]);
attrs.push(*a);
}
// (A deforming mesh's previous vertices lie as its triangles do, counted from the first dynamic triangle: what
// gpu.rs `prev_verts` holds at the build. Its instance's record says where.)
let first_dynamic: usize = groups[..4].iter().sum();
for i in &mut sc.instances {
let m = &sc.meshes[i.mesh as usize];
i.prev = if m.deforms { (pool_first - first_dynamic) as u32 + m.first } else { 0 };
}
sc.gpu_instances = sc.instances.iter().map(|i| i.gpu(pool_first as u32 + sc.meshes[i.mesh as usize].first)).collect();
// A row's section starts here in the triangles' table (hardware traversal: a hit's geometry is its section, its
// primitive counts from there).
Expand Down
Loading