diff --git a/docs/morph-targets.md b/docs/morph-targets.md new file mode 100644 index 00000000..6d0a8f26 --- /dev/null +++ b/docs/morph-targets.md @@ -0,0 +1,145 @@ +# Morph targets (blend shapes) + +glTF morph targets on skinned characters, for facial animation (lip sync, blinks, gaze, expressions) +and anything else a rig drives by shapes. EN-074 in `tickets.md`. + +## The API (`@bloomengine/engine/models`) + +```ts +modelMorphCount(model: Model): number // distinct target names of the model +modelMorphIndex(model: Model, name: string): number // slot of a name, -1 if absent (load time only) +animSetMorphWeight(handle: number, index: number, weight: number): void +animSetMorphWeights(handle: number, first: number, weights: number[]): void // consecutive slots +animClearMorphs(handle: number): void // drop the weights set by the game +animMorphWeight(handle: number, index: number): number // the weight drawn (clips + set, clamped) +``` + +A frame of a talking face: + +```ts +// at load +const face = loadModel("assets/jonah.glb"); +const anim = instantiateAnimation(loadModelAnimation("assets/jonah.glb")); +const JAW = modelMorphIndex(face, "jawOpen"); +const BLINK_L = modelMorphIndex(face, "eyeBlinkLeft"); +// per frame, BEFORE animUpdate +animSetMorphWeight(anim, JAW, jaw); +animSetMorphWeight(anim, BLINK_L, blink); +animUpdate(anim, dt, scale, x, y, z, yaw); +drawModel(face, pos, scale, WHITE); +``` + +- **Slots are model-level, by name.** A model's slots are the distinct target names + (`mesh.extras.targetNames`, as Blender writes them) over all its meshes and primitives, in the + order they first appear in the file. A character whose body mesh and five face primitives (skin, + mouth, teeth, eyes, lashes) all carry `jawOpen` has ONE `jawOpen` slot, and its weight moves all + six. An unnamed target is called `"#"`. At most 1024 slots. +- **Weights belong to the animation instance** (`instantiateAnimation`), like its pose: N + characters sharing one model each have their own face. They are drawn with the pose of the next + `animUpdate` / `animUpdateMatrix` / `updateModelAnimation` (and ragdoll update), so set them before + it. A weight set stays until set again or `animClearMorphs`. +- **Clips can carry weights too.** glTF `weights` animation channels are read into the clips + (LINEAR and STEP; CUBICSPLINE through its key values) and the mixer blends them exactly like + joints: the crossfade from the previous clip, blend partners at the base clip's phase, the masked + layer by its weight (a layer changes only the slots it animates). A slot a clip does not animate + counts as 0 there. +- **What is drawn is `clamp(clip + set, -1, 1)`**: the game's weights ADD to the clips' (a lip-sync + curve over an authored expression clip). `animMorphWeight` returns that. +- **Only skinned models morph** (the weights travel with the pose; a model without a skin logs one + warning and draws its rest shape). The immediate-mode mesh path and custom-material draws + (`drawModelWithMaterial`) do not morph. +- The model and its animation should come from the same file (or files with the same target names + in the same order): clip tracks are numbered by the animation file's name table. + +## Loading + +All three glTF loaders (`load_gltf_with_textures`, `load_gltf_staged_impl`, `load_gltf`) read every +primitive's POSITION, NORMAL and TANGENT deltas (`models_gltf_morph.rs`). Accessors go through the +gltf crate's iterators, which resolve **sparse accessors** (Blender's `export_try_sparse_sk`), with +or without a base buffer view. Skinned vertices' deltas are scaled by the loader's armature +compensation (`skin_vertex_scale`) as their positions are; deltas on rigid vertices of a skinned +primitive are baked through the node transform (`models_gltf_bake.rs`) as those vertices are. + +Deltas whose components are all below 1e-6 are dropped, so a target that moves nothing on a +primitive (an exporter writes every target on every primitive) costs nothing there. + +Export normals with the shape keys (Blender: *Shape Key Normals*): without normal deltas a moving +mouth keeps its rest normals. Tangent deltas are used when present. + +## Data layout (`morph_targets.rs`) + +`MeshData::morph: Option>`, shared by every placement and instance of the mesh: + +- `ranges`: per vertex, its range of entries (CSR, `vertex_count + 1` u32). An untouched vertex costs + 4 bytes. +- `entries`: one target's delta on one vertex, 24 bytes: the slot (u32) and position, normal and + tangent deltas as half floats. Positions are divided by the mesh's largest position delta + component (`pos_scale`) so they always lie in [-1, 1]: no overflow in any unit, and a precision + of 2^-11 of the largest delta (10 µm on a 2 cm shape). +- `bound_growth`: per axis, the most any vertex can move with every weight in [-1, 1]. The cached + mesh's rest bounds grow by it, so culling and shadow casting never lose an open jaw. + +A face mesh of 50k vertices with 12k touched by 56 targets (about 20 targets per touched vertex) is +about 200k entries: 5 MB on the CPU and 5 MB on the GPU, against about 30 MB for dense f32 deltas. + +## On the GPU (`renderer/morph_pass.rs`) + +A skinned cached model keeps one bind-pose vertex buffer shared by all its instances. An instance +whose weights are not all zero gets its **own vertex buffer per morphed mesh**, which a compute pass +rewrites each frame it is drawn: bind pose + Σ wᵢ·Δᵢ for positions; normals and tangents get their +deltas and are renormalised (a zero "no tangent" sentinel stays zero). One thread per vertex; the +entries of each block of 64 vertices are re-laid lane-interleaved at upload (entry k of lane i at +`first + 64k + i`, padded to the block's busiest vertex) so a wave reads them coalesced. Untouched +vertices are copied once, when the buffer is made. Entries whose weight is zero now and was zero +last frame are skipped. + +That buffer replaces the shared one as the draw's vertex buffer at every site that draws cached +model commands (`MorphPass::morph_vertex`: main and depth passes, shadows, transmitted shadows, +layered-PBR SSR, refraction, sorted transparency) and as the source of the ray scene's compute skin +(`pt_dynamic_skin.rs`). The vertex shaders' current-position paths are unchanged. + +**Motion vectors.** The pass knows last frame's weights (kept per animation handle, like the joint +palettes), so it also writes `previous − current` morphed position of every vertex of the mesh into +one frame-wide Rgba32Float texture, the *morph arena*, bound at `@group(3) @binding(2)` in every +joint bind group. A morphed draw's uniform `misc.w` is `1 + its first texel`; the skinned branch of +`vs_main_scene` adds the displacement to the position it feeds the previous palette. TAA and TSR get +the real velocity of a moving lip (`golden_render/morph_targets.rs` checks that a morph alone +writes velocity and leaves no trail, and that without the history it would not). `misc.w = 0` (every +other draw) reads nothing. + +**Pose plumbing.** The morph state travels with the pose: `set_joint_matrices_*` opens a slot in a +queue that runs in step with `pending_skin_groups`, `stage_morph_weights` (called by every posing +FFI right after it) fills it, and `take_staged_skin_offset` pops it for the draw. A draw finds its +morphed buffers by its joint offset, which is unique per posed instance in a frame. + +**Costs nothing when unused:** no buffer, job or texel for models without morphs or instances at +zero. The frame an instance returns to zero is morphed once more (its velocity is not zero that +frame); then it draws from the shared buffer again. Its own buffers are freed after 240 frames +unused, or when the model is unloaded. + +**Without compute** (the WebGL2 baseline tier) the same is done on the CPU from the cached +bind-pose vertices: the instance buffer and the arena are uploaded each frame. `BLOOM_MORPH_CPU=1` +or `Renderer::set_morph_cpu_fallback(true)` forces it; the golden test compares the two. + +## Cost + +Measured with `bench_morph_pass_eight_faces` (`cargo test --release --test golden_render +bench_morph -- --ignored --nocapture`, timestamp queries around the pass): 8 characters of 50,176 +vertices, 12,000 touched by 56 targets (20 per touched vertex), every weight non-zero and changing +each frame, M1 Max: **0.59 ms GPU for all eight** (0.07 ms a face). With one target per touched +vertex 0.27 ms; with nothing touched 0.13 ms (the arena texels of 400k vertices). Real lip sync +has far fewer non-zero weights than the bench, and zero entries are skipped. + +Memory per morphed instance: one vertex buffer of the morphed mesh (96 B a vertex: 4.8 MB for 50k +vertices) and 16 B a vertex of arena while drawn. + +## Limits + +- Skinned models only (see above); no morphs on immediate meshes or custom-material draws. +- Cooked scenes (`.bscene`) do not hold morphs: `bloom-cook` refuses a source with morph targets + rather than drop them. `bloom-cook glb-compress` keeps them (it only re-encodes images). +- Two draws of the same animation instance in one frame share its morphed buffers (the last + weights staged win). +- At most 16M morphed vertices in a frame (`misc.w` is an f32), 1024 slots per model. +- Rigid (unweighted) vertices of a morphed skinned mesh get morph velocity through `u.model`; + their position comes from the morphed buffer like any other. diff --git a/docs/skeletal-animation.md b/docs/skeletal-animation.md index bff1ea64..a7196d64 100644 --- a/docs/skeletal-animation.md +++ b/docs/skeletal-animation.md @@ -9,6 +9,7 @@ Bloom Engine supports GPU-accelerated skeletal animation via glTF/GLB models wit - [TypeScript API](#typescript-api) - [Blender Export Pipeline](#blender-export-pipeline) - [Common Pitfalls](#common-pitfalls) +- [Morph targets](#morph-targets) - [Key Engine Files](#key-engine-files) - [Debugging](#debugging) @@ -119,7 +120,7 @@ The 3D pipeline uses four bind groups: | 0 | Transform | MVP matrix (4x4 uniform) | | 1 | Lighting | Ambient + directional light uniforms | | 2 | Texture | 2D texture + sampler | -| 3 | Joints | 1024 x mat4x4 uniform buffer (+ `joints_prev` at binding 1) | +| 3 | Joints | 1024 x mat4x4 uniform buffer (+ `joints_prev` at binding 1, the morph arena texture at binding 2) | ### Flush Timing @@ -404,6 +405,17 @@ See `scripts/export_mixamo_glb.py` for full documentation. --- +## Morph targets + +Skinned models can carry glTF morph targets (blend shapes); their weights belong to the +animation instance and are drawn with its pose. `modelMorphIndex(model, "jawOpen")` once at +load, `animSetMorphWeight(anim, index, w)` before `animUpdate`; glTF `weights` channels in the +clips are blended by the mixer like joints, and the game's weights add on top. Joint rotation +slots (`animSetJointRotation`) are 0..31 since the same change (24 before). The whole design, +the data layout, motion vectors and costs: [`morph-targets.md`](morph-targets.md). + +--- + ## Key Engine Files ### Rust (native layer) diff --git a/docs/tickets.md b/docs/tickets.md index 77b6838e..183dcc24 100644 --- a/docs/tickets.md +++ b/docs/tickets.md @@ -2233,7 +2233,7 @@ Shipped, all per-instance state in `AnimMixer::rig`, applied inside - `animSetBlend(h, slot 0..2, clip, weight)`: partner clips mixed into the base clip by weight, sampled at the base clip's phase. This is also the two-clip locomotion blend EN-028 promised and never built. -- `animSetJointRotation(h, slot 0..23, joint, ax, ay, az, angle)`: a +- `animSetJointRotation(h, slot 0..31, joint, ax, ay, az, angle)`: a model-space axis-angle turn of one joint and its subtree, applied in slot order after the masked layer. - `animSetIK(h, slot 0..1, endJoint, tx, ty, tz, weight, keepEndRotation)` @@ -2739,3 +2739,32 @@ yet; no rain, lightning, shelter or water): `docs/weather.md`. and `@bloomengine/engine/weather`, a TypeScript module on the material system: weather eased over time, wetness that builds with rain and dries, rain streaks slanted by the wind, lightning. Still open: shelter (rain and wetness know no roof), splashes, lightning on the clouds, water. + +## EN-074 — Morph targets (blend shapes) on skinned characters ✅ *(2026-11-21, branch feat/morph-targets)* + +Asked for by The Deep (Jonah: lip sync for every speaking character, `docs/FACES.md` there). +glTF morph targets were silently dropped by all three loaders, and `weights` channels by the +animation loader. Now: + +- **Loading** (`models_gltf_morph.rs`): POSITION/NORMAL/TANGENT deltas of every primitive, + sparse accessors included, scaled and baked like their vertices; stored sparse per vertex + (`morph_targets.rs`, half floats, 24 B an entry). Slots are the model's distinct target names + over all its meshes, so one `jawOpen` weight drives face, teeth and tongue. `weights` channels + become clip tracks the mixer blends like joints. +- **API**: `modelMorphCount`, `modelMorphIndex`, `animSetMorphWeight`, `animSetMorphWeights`, + `animClearMorphs`, `animMorphWeight` (manifest, every platform, web, watchOS stubs). Drawn weight + = clamp(clip + set, -1, 1). +- **GPU** (`renderer/morph_pass.rs`): a compute pass writes a per-instance morphed vertex buffer for + instances with non-zero weights; every cached-draw site and the ray scene's skin pass draw from + it, so vertex shaders keep their current-position paths. Previous-minus-current displacement goes + to a frame-wide texture at `@group(3) @binding(2)`; the scene VS feeds it to the previous palette, + so TAA/TSR see a moving mouth. Rest bounds grow by what the targets can move. CPU fallback + without compute. 0.59 ms GPU for eight 50k-vertex faces with 12k vertices under 56 targets, all + weights moving (M1 Max). +- Joint rotation slots raised from 24 to 32 (head, neck and look-at on top of grips and fingers). +- `bloom-cook` refuses to cook a scene with morphs (`.bscene` cannot hold them); `glb-compress` + keeps them (tested). + +Tests: loader (dense + sparse accessors, shared names, all loaders agree, weight channels), sparse +storage, mixer blending, golden renders at weights 0 and 1, CPU vs GPU, culling bounds, morph-only +motion vectors with a no-history control, 32 slots. Design and limits: `docs/morph-targets.md`. diff --git a/native/shared/src/anim_mixer.rs b/native/shared/src/anim_mixer.rs index 66917d1d..15151d3c 100644 --- a/native/shared/src/anim_mixer.rs +++ b/native/shared/src/anim_mixer.rs @@ -47,6 +47,8 @@ pub struct AnimMixer { /// EN-064 — blend partners, joint rotations and IK applied over the /// sampled pose. Empty by default, which costs nothing. pub rig: crate::anim_rig::AnimRig, + /// Morph weights: the clips' and the game's (`anim_morph.rs`). + pub morph: crate::anim_morph::MorphState, } impl Default for AnimMixer { @@ -73,6 +75,7 @@ impl Default for AnimMixer { finished: false, started: false, rig: crate::anim_rig::AnimRig::default(), + morph: Default::default(), } } } @@ -174,6 +177,7 @@ mod tests { }], duration: 2.0, name: "slide".into(), + morph_tracks: vec![], } } diff --git a/native/shared/src/anim_morph.rs b/native/shared/src/anim_morph.rs new file mode 100644 index 00000000..0d2392fc --- /dev/null +++ b/native/shared/src/anim_morph.rs @@ -0,0 +1,421 @@ +//! Morph weights of an animation instance: what clips author (glTF +//! `weights` channels), what the game sets, and how the two combine. +//! +//! Slots are model-level (see `morph_targets.rs`): `modelMorphIndex` finds a +//! slot by name once at load, and a frame then sets weights by index. +//! +//! Each `animUpdate` the mixer samples the clips' weight tracks exactly as +//! it blends their joints (base clip, crossfade from the previous clip, +//! blend partners at the base clip's phase, the masked layer by its +//! weight; a slot a clip does not animate counts as 0 there, except in the +//! layer, where it keeps the base's value). The weight drawn is +//! `clamp(clip + explicit, -1, 1)`: the game's weights ADD to the clips' +//! (a lip-sync curve over an authored expression clip), and `animClearMorphs` +//! drops the game's. + +use crate::models::{AnimationData, ModelManager}; + +/// One glTF `weights` channel: the weights of one mesh's targets over time. +#[derive(Clone, Debug, Default)] +pub struct MorphTrack { + /// Model-level slot of each of the mesh's targets. + pub slots: Vec, + pub times: Vec, + /// `times.len() * slots.len()` values, key-major. + pub values: Vec, + /// STEP interpolation (LINEAR otherwise; CUBICSPLINE is read as LINEAR + /// through its key values). + pub step: bool, +} + +impl MorphTrack { + /// Add this track's weights at `t` into `out` (indexed by slot), and + /// mark the slots it animates in `touched`. + fn sample_into(&self, t: f32, out: &mut [f32], touched: &mut [bool]) { + let n = self.slots.len(); + let keys = self.times.len(); + if n == 0 || keys == 0 || self.values.len() < keys * n { + return; + } + let (a, b, f) = if t <= self.times[0] { + (0, 0, 0.0) + } else if t >= self.times[keys - 1] { + (keys - 1, keys - 1, 0.0) + } else { + let hi = self.times.partition_point(|&k| k <= t).min(keys - 1); + let lo = hi - 1; + let span = self.times[hi] - self.times[lo]; + let f = if span > 0.0 { + (t - self.times[lo]) / span + } else { + 0.0 + }; + if self.step { + (lo, lo, 0.0) + } else { + (lo, hi, f) + } + }; + for (i, &slot) in self.slots.iter().enumerate() { + let s = slot as usize; + if s >= out.len() { + continue; + } + let va = self.values[a * n + i]; + let vb = self.values[b * n + i]; + out[s] = va + (vb - va) * f; + touched[s] = true; + } + } +} + +/// Per-instance morph weight state (lives in the `AnimMixer`). +#[derive(Clone, Debug, Default)] +pub struct MorphState { + /// Weights the game set (`animSetMorphWeight`), by slot. + pub explicit: Vec, + /// Weights the clips gave at the last update, by slot. + pub clip: Vec, + /// `clamp(clip + explicit)`, what is drawn; rebuilt by `effective()`. + pub effective: Vec, +} + +impl MorphState { + /// The weights to draw: the clips' plus the game's, clamped to [-1, 1]. + /// Empty when nothing has ever been set or animated. + pub fn effective(&mut self) -> &[f32] { + let n = self.clip.len().max(self.explicit.len()); + self.effective.clear(); + self.effective.resize(n, 0.0); + for (i, w) in self.effective.iter_mut().enumerate() { + let c = self.clip.get(i).copied().unwrap_or(0.0); + let e = self.explicit.get(i).copied().unwrap_or(0.0); + *w = (c + e).clamp(-1.0, 1.0); + } + &self.effective + } +} + +fn slot_count(clips: &[&AnimationData]) -> usize { + clips + .iter() + .flat_map(|c| c.morph_tracks.iter()) + .flat_map(|t| t.slots.iter()) + .map(|&s| s as usize) + .filter(|&s| s < crate::morph_targets::MAX_MORPH_SLOTS) + .map(|s| s + 1) + .max() + .unwrap_or(0) + .min(crate::morph_targets::MAX_MORPH_SLOTS) +} + +fn sample_clip(clip: &AnimationData, t: f32, n: usize) -> (Vec, Vec) { + let mut out = vec![0.0; n]; + let mut touched = vec![false; n]; + for track in &clip.morph_tracks { + track.sample_into(t, &mut out, &mut touched); + } + (out, touched) +} + +/// Sample the mixer's clips' weight tracks into `mixer.morph.clip`, blended +/// the way `advance_and_update` blends their joints. Cheap when no clip has +/// weight tracks (the usual case): one scan, nothing allocated. +pub fn evaluate_mixer(animations: &[AnimationData], mixer: &mut crate::models::AnimMixer) { + if !animations.iter().any(|a| !a.morph_tracks.is_empty()) { + mixer.morph.clip.clear(); + return; + } + let Some(cur) = animations.get(mixer.cur_clip) else { + return; + }; + let mut used: Vec<&AnimationData> = vec![cur]; + let prev = (mixer.fade_dur > 0.0) + .then(|| animations.get(mixer.prev_clip)) + .flatten(); + used.extend(prev); + let partners: Vec<(&AnimationData, f32)> = mixer + .rig + .blends + .iter() + .filter(|b| b.clip >= 0 && b.weight > 0.0) + .filter_map(|b| animations.get(b.clip as usize).map(|c| (c, b.weight))) + .collect(); + used.extend(partners.iter().map(|(c, _)| *c)); + let layer = (mixer.layer_clip >= 0 && mixer.layer_weight > 0.0) + .then(|| animations.get(mixer.layer_clip as usize)) + .flatten(); + used.extend(layer); + let n = slot_count(&used); + + let (mut out, _) = sample_clip(cur, mixer.cur_time, n); + if let Some(prev) = prev { + let w = (mixer.fade_t / mixer.fade_dur).clamp(0.0, 1.0); + let w = w * w * (3.0 - 2.0 * w); + let (p, _) = sample_clip(prev, mixer.prev_time, n); + for (o, p) in out.iter_mut().zip(p) { + *o += (p - *o) * (1.0 - w); + } + } + if !partners.is_empty() { + let cur_dur = cur.duration; + let phase = if cur_dur > 0.0 { + mixer.cur_time / cur_dur + } else { + 0.0 + }; + let mut total = 1.0f32; + for b in mixer.rig.blends.iter() { + total -= b.weight.max(0.0) * ((b.clip >= 0) as i32 as f32); + } + let mut total = total.max(0.0); + for (clip, weight) in &partners { + let (p, _) = sample_clip(clip, phase * clip.duration, n); + total += weight; + let f = weight / total; + for (o, p) in out.iter_mut().zip(p) { + *o += (p - *o) * f; + } + } + } + if let Some(layer) = layer { + let (l, touched) = sample_clip(layer, mixer.layer_time, n); + let w = mixer.layer_weight; + for i in 0..n { + if touched[i] { + out[i] += (l[i] - out[i]) * w; + } + } + } + mixer.morph.clip = out; +} + +/// `evaluate_mixer` for the single-clip `updateModelAnimation`. +pub fn evaluate_single(clip: &AnimationData, time: f32, mixer: &mut crate::models::AnimMixer) { + if clip.morph_tracks.is_empty() { + mixer.morph.clip.clear(); + return; + } + let n = slot_count(&[clip]); + mixer.morph.clip = sample_clip(clip, time, n).0; +} + +/// After an animation update has staged the instance's pose: stage its +/// morph weights with it (`Renderer::stage_morph_weights`). Every FFI that +/// poses an instance calls this right after `set_joint_matrices_*`. +pub fn stage_weights( + models: &mut ModelManager, + renderer: &mut crate::renderer::Renderer, + anim: f64, +) { + if let Some(a) = models.animations.get_mut(anim) { + renderer.stage_morph_weights(anim.to_bits(), a.mixer.morph.effective()); + } +} + +/// The morph API over model and animation handles. +impl ModelManager { + /// The model's slot names (`None` for a model without morph targets). + pub fn model_morph_names(&self, model: f64) -> Option>> { + self.get(model)? + .meshes + .iter() + .find_map(|m| m.morph.as_ref().map(|t| t.names.clone())) + } + + /// Number of morph slots of a model (0 without morph targets). + pub fn model_morph_count(&self, model: f64) -> usize { + self.model_morph_names(model).map_or(0, |n| n.len()) + } + + /// Slot of the target called `name`, or -1. A load-time call: it + /// compares strings. + pub fn model_morph_index(&self, model: f64, name: &str) -> i32 { + self.model_morph_names(model) + .and_then(|names| names.iter().position(|n| n == name)) + .map_or(-1, |i| i as i32) + } + + /// Set the game's weight of one slot (added to the clips' at draw). + /// Out-of-range slots and non-finite weights are ignored. + pub fn anim_set_morph_weight(&mut self, anim: f64, slot: usize, weight: f32) { + self.anim_set_morph_weights(anim, slot, &[weight]); + } + + /// Set consecutive slots from `first`. + pub fn anim_set_morph_weights(&mut self, anim: f64, first: usize, weights: &[f32]) { + let Some(a) = self.animations.get_mut(anim) else { + return; + }; + let explicit = &mut a.mixer.morph.explicit; + for (i, &w) in weights.iter().enumerate() { + let slot = first + i; + if slot >= crate::morph_targets::MAX_MORPH_SLOTS || !w.is_finite() { + continue; + } + if explicit.len() <= slot { + if w == 0.0 { + continue; + } + explicit.resize(slot + 1, 0.0); + } + explicit[slot] = w.clamp(-1.0, 1.0); + } + } + + /// Drop every weight the game set (the clips' stay). + pub fn anim_clear_morphs(&mut self, anim: f64) { + if let Some(a) = self.animations.get_mut(anim) { + a.mixer.morph.explicit.clear(); + } + } + + /// The weight a slot is drawn with: clips plus the game's, clamped, as of + /// the last update (and the game's weights set since). + pub fn anim_morph_weight(&mut self, anim: f64, slot: usize) -> f32 { + let Some(a) = self.animations.get_mut(anim) else { + return 0.0; + }; + a.mixer.morph.effective().get(slot).copied().unwrap_or(0.0) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::models::{AnimationData, ModelAnimation}; + use std::sync::Arc; + + fn clip(name: &str, track: MorphTrack, duration: f32) -> AnimationData { + AnimationData { + channels: vec![], + duration, + name: name.into(), + morph_tracks: vec![track], + } + } + + fn ramp(slots: Vec, from: f32, to: f32) -> MorphTrack { + let n = slots.len(); + let mut values = vec![from; n]; + values.extend(std::iter::repeat_n(to, n)); + MorphTrack { + slots, + times: vec![0.0, 1.0], + values, + step: false, + } + } + + fn manager(clips: Vec) -> (ModelManager, f64) { + let mut m = ModelManager::new(); + let skel = crate::models::SkeletonData { + joints: vec![crate::models::JointData { + inverse_bind: [ + [1.0, 0.0, 0.0, 0.0], + [0.0, 1.0, 0.0, 0.0], + [0.0, 0.0, 1.0, 0.0], + [0.0, 0.0, 0.0, 1.0], + ], + children: vec![], + name: "root".into(), + rest_translation: [0.0; 3], + rest_rotation: [0.0, 0.0, 0.0, 1.0], + rest_scale: [1.0; 3], + }], + root_joints: vec![0], + }; + let h = m.animations.alloc(ModelAnimation { + skeleton: Some(Arc::new(skel)), + animations: Arc::new(clips), + ref_rest_rotations: None, + joint_matrices: vec![], + mixer: Default::default(), + joint_world: vec![], + mask_weights: vec![], + mask_cached_root: -1, + }); + (m, h) + } + + #[test] + fn linear_and_step_tracks_sample_between_keys() { + let lin = ramp(vec![2], 0.0, 1.0); + let mut out = vec![0.0; 3]; + let mut touched = vec![false; 3]; + lin.sample_into(0.25, &mut out, &mut touched); + assert!((out[2] - 0.25).abs() < 1e-6); + assert_eq!(touched, vec![false, false, true]); + let mut step = ramp(vec![0], 0.0, 1.0); + step.step = true; + step.sample_into(0.99, &mut out, &mut touched); + assert_eq!(out[0], 0.0); + step.sample_into(1.5, &mut out, &mut touched); + assert_eq!(out[0], 1.0); + } + + #[test] + fn clip_weights_follow_the_mixer_and_explicit_weights_add() { + let (mut m, h) = manager(vec![ + clip("open", ramp(vec![0, 1], 0.0, 1.0), 1.0), + clip("shut", ramp(vec![0], 0.0, 0.0), 1.0), + ]); + m.anim_play(h, 0, 0.0, 1.0, false); + m.advance_and_update(h, 0.5); + assert!((m.anim_morph_weight(h, 0) - 0.5).abs() < 1e-5); + assert!((m.anim_morph_weight(h, 1) - 0.5).abs() < 1e-5); + // the game's weight adds and the sum is clamped + m.anim_set_morph_weight(h, 1, 0.75); + assert!((m.anim_morph_weight(h, 1) - 1.0).abs() < 1e-6); + m.anim_set_morph_weights(h, 3, &[0.25, -2.0]); + assert!((m.anim_morph_weight(h, 3) - 0.25).abs() < 1e-6); + assert!((m.anim_morph_weight(h, 4) + 1.0).abs() < 1e-6); + m.anim_clear_morphs(h); + assert!((m.anim_morph_weight(h, 1) - 0.5).abs() < 1e-5); + assert_eq!(m.anim_morph_weight(h, 3), 0.0); + // a crossfade blends the weights like the joints (smoothstepped) + m.anim_play(h, 1, 1.0, 1.0, false); + m.advance_and_update(h, 0.5); + // prev clip at t=1.0 (weight 1), new clip 0; fade w=0.5 -> 0.5 + assert!((m.anim_morph_weight(h, 0) - 0.5).abs() < 1e-4); + // slot 1 is animated only by the clip fading out: it fades too + assert!((m.anim_morph_weight(h, 1) - 0.5).abs() < 1e-4); + m.advance_and_update(h, 0.6); + assert!(m.anim_morph_weight(h, 0).abs() < 1e-6); + } + + #[test] + fn a_layer_overrides_only_the_slots_it_animates() { + let (mut m, h) = manager(vec![ + clip("base", ramp(vec![0, 1], 0.5, 0.5), 1.0), + clip("blink", ramp(vec![1], 1.0, 1.0), 1.0), + ]); + m.anim_play(h, 0, 0.0, 1.0, true); + m.anim_set_layer(h, 1, 0.5, 0, 1.0, true); + m.advance_and_update(h, 0.1); + assert!((m.anim_morph_weight(h, 0) - 0.5).abs() < 1e-5); + assert!((m.anim_morph_weight(h, 1) - 0.75).abs() < 1e-5); + } + + #[test] + fn no_tracks_and_bad_input_cost_nothing() { + let (mut m, h) = manager(vec![AnimationData { + channels: vec![], + duration: 1.0, + name: "idle".into(), + morph_tracks: vec![], + }]); + m.advance_and_update(h, 0.1); + assert!(m.get_animation(h).unwrap().mixer.morph.clip.is_empty()); + m.anim_set_morph_weight(h, 5, f32::NAN); + m.anim_set_morph_weight(h, 5, 0.0); + m.anim_set_morph_weight(h, crate::morph_targets::MAX_MORPH_SLOTS, 1.0); + assert!(m.get_animation(h).unwrap().mixer.morph.explicit.is_empty()); + assert_eq!(m.anim_morph_weight(h, 0), 0.0); + assert_eq!(m.anim_morph_weight(-1.0, 0), 0.0); + m.anim_set_morph_weight(-1.0, 0, 1.0); + m.anim_clear_morphs(-1.0); + assert_eq!(m.model_morph_count(-1.0), 0); + assert_eq!(m.model_morph_index(-1.0, "jawOpen"), -1); + } +} diff --git a/native/shared/src/anim_rig.rs b/native/shared/src/anim_rig.rs index 5e8c0988..5aec72e9 100644 --- a/native/shared/src/anim_rig.rs +++ b/native/shared/src/anim_rig.rs @@ -19,8 +19,9 @@ //! `models3d` and can be unit-tested without a GLB. pub const BLEND_SLOTS: usize = 3; -// (24: a hand closing on what it holds is two joints of four fingers, on top of spine and limb offsets.) -pub const ROT_SLOTS: usize = 24; +// (24 for a hand closing on what it holds: two joints of four fingers, on top of spine and limb +// offsets; 32 since the face work: neck, head and look-at on top of that.) +pub const ROT_SLOTS: usize = 32; pub const IK_SLOTS: usize = 2; #[derive(Clone, Copy)] @@ -489,6 +490,28 @@ mod tests { (pos[j], rot[j]) } + #[test] + fn thirty_two_rotation_slots_and_no_more() { + assert_eq!(ROT_SLOTS, 32); + let mut m = crate::models::ModelManager::new(); + let h = m.animations.alloc(crate::models::ModelAnimation { + skeleton: None, + animations: std::sync::Arc::new(vec![]), + ref_rest_rotations: None, + joint_matrices: vec![], + mixer: Default::default(), + joint_world: vec![], + mask_weights: vec![], + mask_cached_root: -1, + }); + m.anim_set_joint_rotation(h, 31, 7, [0.0, 1.0, 0.0], 0.5); + m.anim_set_joint_rotation(h, 32, 9, [0.0, 1.0, 0.0], 0.5); + let rig = &m.get_animation(h).unwrap().mixer.rig; + assert_eq!(rig.rots[31].joint, 7); + assert!(rig.rots[..31].iter().all(|r| r.joint < 0)); + assert!(rig.has_post()); + } + #[test] fn topology_is_parents_first() { let (topo, ..) = arm(); diff --git a/native/shared/src/ffi_core/models.rs b/native/shared/src/ffi_core/models.rs index 24bb6463..a8da8957 100644 --- a/native/shared/src/ffi_core/models.rs +++ b/native/shared/src/ffi_core/models.rs @@ -692,6 +692,7 @@ macro_rules! __bloom_ffi_models { // PT-7: the anim handle keys the prev-palette // pairing for skinned motion vectors. eng.renderer.set_joint_matrices_scaled(handle.to_bits(), &anim.joint_matrices, scale as f32, [px as f32, py as f32, pz as f32], rot_sin, rot_cos); + $crate::anim_morph::stage_weights(&mut eng.models, &mut eng.renderer, handle); } } }) @@ -1276,6 +1277,7 @@ macro_rules! __bloom_ffi_models { eng.renderer.set_joint_matrices_scaled( handle.to_bits(), &anim.joint_matrices, scale as f32, [px as f32, py as f32, pz as f32], rot_sin, rot_cos); + $crate::anim_morph::stage_weights(&mut eng.models, &mut eng.renderer, handle); } } }) @@ -1307,6 +1309,7 @@ macro_rules! __bloom_ffi_models { if !anim.joint_matrices.is_empty() { eng.renderer.set_joint_matrices_transformed( handle.to_bits(), &anim.joint_matrices, model); + $crate::anim_morph::stage_weights(&mut eng.models, &mut eng.renderer, handle); } } }) @@ -1477,6 +1480,101 @@ macro_rules! __bloom_ffi_models { #[no_mangle] pub extern "C" fn bloom_model_find_joint(_h: f64, _n: *const u8) -> f64 { -1.0 } + // ---- Morph targets (docs/morph-targets.md) ----------------------- + // Slots are model-level, by target name across all meshes; the + // weights are per animation instance and staged with its pose by + // bloom_anim_update (and the other posing calls). + + // bloom_model_morph_count [gated: models3d] + #[cfg(feature = "models3d")] + #[no_mangle] + pub extern "C" fn bloom_model_morph_count(model: f64) -> f64 { + $crate::ffi::guard("bloom_model_morph_count", move || { + engine().models.model_morph_count(model) as f64 + }) + } + #[cfg(not(feature = "models3d"))] + #[no_mangle] + pub extern "C" fn bloom_model_morph_count(_m: f64) -> f64 { 0.0 } + + // bloom_model_morph_index [gated: models3d] + // Load-time only (it compares strings): cache the index. + #[cfg(feature = "models3d")] + #[no_mangle] + pub extern "C" fn bloom_model_morph_index(model: f64, name_ptr: *const u8) -> f64 { + $crate::ffi::guard("bloom_model_morph_index", move || { + let name = $crate::string_header::str_from_header(name_ptr); + engine().models.model_morph_index(model, &name) as f64 + }) + } + #[cfg(not(feature = "models3d"))] + #[no_mangle] + pub extern "C" fn bloom_model_morph_index(_m: f64, _n: *const u8) -> f64 { -1.0 } + + // bloom_anim_set_morph_weight [gated: models3d] + #[cfg(feature = "models3d")] + #[no_mangle] + pub extern "C" fn bloom_anim_set_morph_weight(handle: f64, index: f64, weight: f64) { + $crate::ffi::guard("bloom_anim_set_morph_weight", move || { + if index >= 0.0 { + engine().models.anim_set_morph_weight(handle, index as usize, weight as f32); + } + }) + } + #[cfg(not(feature = "models3d"))] + #[no_mangle] + pub extern "C" fn bloom_anim_set_morph_weight(_h: f64, _i: f64, _w: f64) { + $crate::ffi::feature_off_warn_once("bloom_anim_set_morph_weight", "models3d"); + } + + // bloom_anim_set_morph_weights [gated: models3d] + // Up to five consecutive slots from `first` in one call (8 scalar + // arguments: the most Perry passes safely on ARM64). + #[cfg(feature = "models3d")] + #[no_mangle] + pub extern "C" fn bloom_anim_set_morph_weights(handle: f64, first: f64, count: f64, w0: f64, w1: f64, w2: f64, w3: f64, w4: f64) { + $crate::ffi::guard("bloom_anim_set_morph_weights", move || { + if first >= 0.0 { + let all = [w0 as f32, w1 as f32, w2 as f32, w3 as f32, w4 as f32]; + let n = (count.max(0.0) as usize).min(5); + engine().models.anim_set_morph_weights(handle, first as usize, &all[..n]); + } + }) + } + #[cfg(not(feature = "models3d"))] + #[no_mangle] + pub extern "C" fn bloom_anim_set_morph_weights(_h: f64, _f: f64, _c: f64, _w0: f64, _w1: f64, _w2: f64, _w3: f64, _w4: f64) { + $crate::ffi::feature_off_warn_once("bloom_anim_set_morph_weights", "models3d"); + } + + // bloom_anim_clear_morphs [gated: models3d] + #[cfg(feature = "models3d")] + #[no_mangle] + pub extern "C" fn bloom_anim_clear_morphs(handle: f64) { + $crate::ffi::guard("bloom_anim_clear_morphs", move || { + engine().models.anim_clear_morphs(handle); + }) + } + #[cfg(not(feature = "models3d"))] + #[no_mangle] + pub extern "C" fn bloom_anim_clear_morphs(_h: f64) { + $crate::ffi::feature_off_warn_once("bloom_anim_clear_morphs", "models3d"); + } + + // bloom_anim_morph_weight [gated: models3d] + // The weight a slot is drawn with: clips plus the game's, clamped. + #[cfg(feature = "models3d")] + #[no_mangle] + pub extern "C" fn bloom_anim_morph_weight(handle: f64, index: f64) -> f64 { + $crate::ffi::guard("bloom_anim_morph_weight", move || { + if index < 0.0 { return 0.0; } + engine().models.anim_morph_weight(handle, index as usize) as f64 + }) + } + #[cfg(not(feature = "models3d"))] + #[no_mangle] + pub extern "C" fn bloom_anim_morph_weight(_h: f64, _i: f64) -> f64 { 0.0 } + // bloom_model_joint_world [gated: models3d] // Model-space 4x4 of a joint, column-major, component 0..15. // Translation is components 12/13/14. The caller applies the same diff --git a/native/shared/src/ffi_core/ragdoll_ffi.rs b/native/shared/src/ffi_core/ragdoll_ffi.rs index aa43ab04..1baf5aa9 100644 --- a/native/shared/src/ffi_core/ragdoll_ffi.rs +++ b/native/shared/src/ffi_core/ragdoll_ffi.rs @@ -298,6 +298,7 @@ macro_rules! __bloom_ffi_ragdoll { s, c, ); + $crate::anim_morph::stage_weights(&mut eng.models, &mut eng.renderer, anim); } } age as f64 diff --git a/native/shared/src/lib.rs b/native/shared/src/lib.rs index 84a206a9..06ebaaf7 100644 --- a/native/shared/src/lib.rs +++ b/native/shared/src/lib.rs @@ -31,12 +31,14 @@ pub mod virtual_geometry; // ModelAnimation (always compiled); only the gltf/image_dds LOADERS are // behind the feature, in models_gltf.rs (EN-063). pub mod anim_mixer; +pub mod anim_morph; pub mod anim_rig; pub mod custom_shaders; pub mod decals; pub mod frame_callbacks; pub mod geometry; pub mod models; +pub mod morph_targets; pub mod particles; pub mod picking; pub mod postfx; diff --git a/native/shared/src/models.rs b/native/shared/src/models.rs index b4aba4ff..d5afb17a 100644 --- a/native/shared/src/models.rs +++ b/native/shared/src/models.rs @@ -478,6 +478,8 @@ pub struct MeshData { /// Scalar and texture metadata is retained before any renderer /// specialization is selected. pub layered_pbr: MaterialLayeredPbr, + /// Sparse morph-target deltas (`morph_targets.rs`); `None` for most meshes. + pub morph: Option>, } #[path = "models_metadata.rs"] @@ -532,6 +534,7 @@ pub struct AnimationData { pub channels: Vec, pub duration: f32, pub name: String, + pub morph_tracks: Vec, } pub struct SkeletonData { @@ -855,6 +858,7 @@ impl ModelManager { double_sided: false, transmission: MaterialTransmission::default(), layered_pbr: MaterialLayeredPbr::default(), + morph: None, })], mesh_transforms: vec![crate::renderer::IDENTITY_MAT4], mesh_cast_shadows: vec![true], @@ -978,6 +982,7 @@ impl ModelManager { double_sided: false, transmission: MaterialTransmission::default(), layered_pbr: MaterialLayeredPbr::default(), + morph: None, })], mesh_transforms: vec![crate::renderer::IDENTITY_MAT4], mesh_cast_shadows: vec![true], @@ -1050,6 +1055,7 @@ impl ModelManager { double_sided: false, transmission: MaterialTransmission::default(), layered_pbr: MaterialLayeredPbr::default(), + morph: None, })], mesh_transforms: vec![crate::renderer::IDENTITY_MAT4], mesh_cast_shadows: vec![true], @@ -1184,6 +1190,7 @@ impl ModelManager { double_sided: false, transmission: MaterialTransmission::default(), layered_pbr: MaterialLayeredPbr::default(), + morph: None, })], mesh_transforms: vec![crate::renderer::IDENTITY_MAT4], mesh_cast_shadows: vec![true], @@ -1239,6 +1246,11 @@ impl ModelManager { let joint_count = skeleton.joints.len(); let pose = sample_local_pose(skeleton, &model_anim.animations[anim_index], time, true); + crate::anim_morph::evaluate_single( + &model_anim.animations[anim_index], + time, + &mut model_anim.mixer, + ); model_anim.apply_pose(&pose); #[cfg(debug_assertions)] @@ -1563,7 +1575,7 @@ impl ModelManager { let topo = crate::anim_rig::topology(&children, &skel.root_joints); crate::anim_rig::apply_post(&ma.mixer.rig, &topo, &pose.0, &mut pose.1, &pose.2); } - + crate::anim_morph::evaluate_mixer(&ma.animations, &mut ma.mixer); ma.apply_pose(&pose); } } @@ -1946,51 +1958,6 @@ fn compute_joint_transforms( } } -// ---- Catmull-Rom spline helpers (Q9) ---- - -fn catmull_rom_point(points: &[f32], n: usize, segment: usize, t: f32) -> [f32; 3] { - // Indices: p0 = segment - 1, p1 = segment, p2 = segment + 1, p3 = segment + 2. - // Clamp at boundaries. - let i0 = if segment > 0 { segment - 1 } else { 0 }; - let i1 = segment; - let i2 = if segment + 1 < n { segment + 1 } else { n - 1 }; - let i3 = if segment + 2 < n { segment + 2 } else { n - 1 }; - - let p0 = [points[i0 * 3], points[i0 * 3 + 1], points[i0 * 3 + 2]]; - let p1 = [points[i1 * 3], points[i1 * 3 + 1], points[i1 * 3 + 2]]; - let p2 = [points[i2 * 3], points[i2 * 3 + 1], points[i2 * 3 + 2]]; - let p3 = [points[i3 * 3], points[i3 * 3 + 1], points[i3 * 3 + 2]]; - - let t2 = t * t; - let t3 = t2 * t; - let mut out = [0.0f32; 3]; - for k in 0..3 { - out[k] = 0.5 - * ((2.0 * p1[k]) - + (-p0[k] + p2[k]) * t - + (2.0 * p0[k] - 5.0 * p1[k] + 4.0 * p2[k] - p3[k]) * t2 - + (-p0[k] + 3.0 * p1[k] - 3.0 * p2[k] + p3[k]) * t3); - } - out -} - -fn update_bounds(bmin: &mut [f32; 3], bmax: &mut [f32; 3], x: f32, y: f32, z: f32) { - if x < bmin[0] { - bmin[0] = x; - } - if y < bmin[1] { - bmin[1] = y; - } - if z < bmin[2] { - bmin[2] = z; - } - if x > bmax[0] { - bmax[0] = x; - } - if y > bmax[1] { - bmax[1] = y; - } - if z > bmax[2] { - bmax[2] = z; - } -} +#[path = "models_spline.rs"] +mod spline; +use spline::{catmull_rom_point, update_bounds}; diff --git a/native/shared/src/models_cooked_scene.rs b/native/shared/src/models_cooked_scene.rs index 14c50bf6..e9888e7f 100644 --- a/native/shared/src/models_cooked_scene.rs +++ b/native/shared/src/models_cooked_scene.rs @@ -140,6 +140,7 @@ fn convert_primitive( double_sided: material.double_sided, transmission: convert_transmission(material.transmission, texture_handles)?, layered_pbr: convert_layered(material.layered_pbr, texture_handles)?, + morph: None, }) } @@ -297,6 +298,7 @@ fn convert_animation(value: format::AnimationArchive) -> ModelAnimation { .collect(), duration: clip.duration, name: clip.name, + morph_tracks: vec![], }) .collect(), ); diff --git a/native/shared/src/models_gltf.rs b/native/shared/src/models_gltf.rs index 5a800281..0d4f476a 100644 --- a/native/shared/src/models_gltf.rs +++ b/native/shared/src/models_gltf.rs @@ -24,6 +24,8 @@ use material_import::{ }; #[path = "models_gltf_bake.rs"] mod bake; +#[path = "models_gltf_morph.rs"] +mod morph; pub use bake::require_source_geometry_hash; #[path = "models_gltf_texture_io.rs"] mod texture_io; @@ -269,8 +271,10 @@ pub fn load_gltf_animation(data: &[u8]) -> Option { // Parse animations let mut animations = Vec::new(); + let morph_slots = morph::morph_slots(&gltf); for anim in gltf.animations() { let mut channels = Vec::new(); + let mut morph_tracks = Vec::new(); let mut duration: f32 = 0.0; // Build node-to-joint mapping for channel resolution @@ -323,6 +327,12 @@ pub fn load_gltf_animation(data: &[u8]) -> Option { } } for channel in anim.channels() { + let buffers = |b: gltf::Buffer| buffer_data.get(b.index()).map(|d| d.as_slice()); + if let Some(track) = morph::read_weight_channel(&channel, buffers, &morph_slots) { + duration = duration.max(track.times.last().copied().unwrap_or(0.0)); + morph_tracks.push(track); + continue; + } let target_node = channel.target().node().index(); let joint_index = match node_to_joint.get(&target_node) { Some(&ji) => { @@ -420,6 +430,7 @@ pub fn load_gltf_animation(data: &[u8]) -> Option { channels, duration, name, + morph_tracks, }); } @@ -738,6 +749,7 @@ pub(super) fn load_gltf_with_textures( } } + let morph_slots = morph::morph_slots(&gltf); for mesh in gltf.meshes() { let instances = mesh_instances[mesh.index()].clone(); // Meshes reachable from no scene node would have no instances; @@ -976,6 +988,7 @@ pub(super) fn load_gltf_with_textures( Some(iter) => iter.into_u32().collect(), None => (0..positions.len() as u32).collect(), }; + let morph = morph_slots.read(&reader, &vertices, skin_vertex_scale, mesh.index()); let source = Arc::new(MeshData { vertices, secondary_tex_coords, @@ -995,6 +1008,7 @@ pub(super) fn load_gltf_with_textures( double_sided: mat.double_sided(), transmission, layered_pbr, + morph, }); primitive_cache[primitive_index] = Some(Arc::clone(&source)); let (instance, transform) = shared_or_owned_instance(&source, instance_transform); @@ -1217,6 +1231,7 @@ fn load_gltf_staged_impl( let mut source_meshes: Vec> = (0..gltf.meshes().count()).map(|_| Vec::new()).collect(); + let morph_slots = morph::morph_slots(&gltf); for mesh in gltf.meshes() { for primitive in mesh.primitives() { let reader = primitive.reader(|buf| buffer_data.get(buf.index()).map(|d| d.as_slice())); @@ -1411,6 +1426,7 @@ fn load_gltf_staged_impl( Some(iter) => iter.into_u32().collect(), None => (0..positions.len() as u32).collect(), }; + let morph = morph_slots.read(&reader, &vertices, skin_vertex_scale, mesh.index()); source_meshes[mesh.index()].push(( primitive.index() as u32, MeshData { @@ -1432,6 +1448,7 @@ fn load_gltf_staged_impl( double_sided: mat.double_sided(), transmission, layered_pbr, + morph, }, )); } @@ -1532,6 +1549,7 @@ pub(super) fn load_gltf(data: &[u8]) -> Option { let mut source_meshes: Vec> = (0..gltf.meshes().count()).map(|_| Vec::new()).collect(); + let morph_slots = morph::morph_slots(&gltf); for mesh in gltf.meshes() { for primitive in mesh.primitives() { let reader = primitive.reader(|buf| buffer_data.get(buf.index()).map(|d| d.as_slice())); @@ -1621,6 +1639,7 @@ pub(super) fn load_gltf(data: &[u8]) -> Option { None => (0..positions.len() as u32).collect(), }; + let morph = morph_slots.read(&reader, &vertices, 1.0, mesh.index()); source_meshes[mesh.index()].push(( primitive.index() as u32, MeshData { @@ -1642,6 +1661,7 @@ pub(super) fn load_gltf(data: &[u8]) -> Option { double_sided: mat.double_sided(), transmission, layered_pbr, + morph, }, )); } diff --git a/native/shared/src/models_gltf_bake.rs b/native/shared/src/models_gltf_bake.rs index 2ee3aea6..daa70ecb 100644 --- a/native/shared/src/models_gltf_bake.rs +++ b/native/shared/src/models_gltf_bake.rs @@ -97,6 +97,27 @@ fn bake_owned_mesh_instance(mut instance: MeshData, world: &[[f32; 4]; 4]) -> Me if !has_skinning { instance.transmission.baked_thickness_scale *= mat4_mean_scale(world); } + // Morph deltas of the rigid vertices just baked move with them: through + // the node's linear part (positions, tangents) and its inverse + // transpose (normals). Skinned vertices' deltas stay in bind space. + if let Some(morph) = instance.morph.as_ref() { + let rigid: Vec = instance + .vertices + .iter() + .map(|v| !vertex_is_skinned(v)) + .collect(); + if rigid.iter().any(|r| *r) { + instance.morph = morph + .mapped(|v, d| { + rigid[v].then(|| crate::morph_targets::MorphDelta { + position: mat4_transform_direction(world, &d.position), + normal: mat3_transform_vec(&normal_transform, &d.normal), + tangent: mat4_transform_direction(world, &d.tangent), + }) + }) + .map(Arc::new); + } + } instance } @@ -232,6 +253,7 @@ mod tests { double_sided: false, transmission: crate::models::MaterialTransmission::default(), layered_pbr: crate::models::MaterialLayeredPbr::default(), + morph: None, } } diff --git a/native/shared/src/models_gltf_morph.rs b/native/shared/src/models_gltf_morph.rs new file mode 100644 index 00000000..fddcc5bf --- /dev/null +++ b/native/shared/src/models_gltf_morph.rs @@ -0,0 +1,185 @@ +//! glTF morph targets into `MorphTargets` (see `morph_targets.rs`), and +//! `weights` animation channels into `MorphTrack`s (see `anim_morph.rs`). +//! +//! Every loader calls the same two functions, so the three model paths and +//! the animation path agree on the slot numbering: slots are the distinct +//! target NAMES of the file (`mesh.extras.targetNames`), in the order they +//! first appear over the meshes in file order. A character whose body mesh +//! and five face primitives all carry "jawOpen" has one "jawOpen" slot, and +//! its weight drives all six. Unnamed targets are `"#n"`. +//! +//! Accessors are read through the gltf crate's iterators, which resolve +//! sparse accessors (Blender writes shape keys sparse), with or without a +//! base buffer view. Deltas below `MORPH_DELTA_EPSILON` are dropped, so a +//! target that moves nothing on a primitive costs nothing there. + +use super::*; +use crate::morph_targets::{MorphTargetsBuilder, MAX_MORPH_SLOTS}; + +/// The file's slot names and, per glTF mesh, the slot of each target. +pub(super) struct MorphSlots { + pub names: Arc>, + pub per_mesh: Vec>, +} + +fn target_names(mesh: &gltf::Mesh<'_>) -> Vec { + let count = mesh + .primitives() + .map(|p| p.morph_targets().count()) + .max() + .unwrap_or(0); + let authored: Vec = mesh + .extras() + .as_ref() + .and_then(|raw| serde_json::from_str::(raw.get()).ok()) + .and_then(|extras| { + extras.get("targetNames").and_then(|names| { + names.as_array().map(|a| { + a.iter() + .map(|n| n.as_str().unwrap_or("").to_string()) + .collect() + }) + }) + }) + .unwrap_or_default(); + let mesh_label = mesh + .name() + .map(str::to_string) + .unwrap_or_else(|| mesh.index().to_string()); + (0..count) + .map(|i| match authored.get(i) { + Some(name) if !name.is_empty() => name.clone(), + _ => format!("{mesh_label}#{i}"), + }) + .collect() +} + +pub(super) fn morph_slots(gltf: &gltf::Gltf) -> MorphSlots { + let mut names: Vec = Vec::new(); + let mut per_mesh = Vec::new(); + for mesh in gltf.meshes() { + let mut slots = Vec::new(); + for name in target_names(&mesh) { + let slot = match names.iter().position(|n| *n == name) { + Some(i) => i, + None if names.len() < MAX_MORPH_SLOTS => { + names.push(name); + names.len() - 1 + } + None => { + log::warn!("bloom: more than {MAX_MORPH_SLOTS} morph target names; '{name}' is ignored"); + usize::MAX + } + }; + slots.push(slot.min(u32::MAX as usize) as u32); + } + per_mesh.push(slots); + } + MorphSlots { + names: Arc::new(names), + per_mesh, + } +} + +impl MorphSlots { + /// Read one primitive's targets. `vertices` are the loader's finished + /// vertices (to tell skinned from rigid ones); skinned deltas are scaled by + /// `skin_vertex_scale` exactly as the loader scaled their positions. + pub(super) fn read<'a, 's, F>( + &self, + reader: &gltf::mesh::Reader<'a, 's, F>, + vertices: &[Vertex3D], + skin_vertex_scale: f32, + mesh_index: usize, + ) -> Option> + where + F: Clone + Fn(gltf::Buffer<'a>) -> Option<&'s [u8]>, + { + let slots = self; + let mesh_slots = slots.per_mesh.get(mesh_index)?; + let scale_skinned = (skin_vertex_scale - 1.0).abs() > 0.01; + let mut builder = MorphTargetsBuilder::new(vertices.len()); + let mut any = false; + for (target, (positions, normals, tangents)) in reader.read_morph_targets().enumerate() { + let Some(&slot) = mesh_slots.get(target) else { + continue; + }; + if slot == u32::MAX { + continue; + } + let positions: Option> = positions.map(|i| i.collect()); + let normals: Option> = normals.map(|i| i.collect()); + let tangents: Option> = tangents.map(|i| i.collect()); + any = true; + builder.add_target( + slot, + positions.as_deref(), + normals.as_deref(), + tangents.as_deref(), + |v, mut d| { + let w = vertices[v].weights; + if scale_skinned && w[0] + w[1] + w[2] + w[3] > 0.01 { + for c in &mut d[0..3] { + *c *= skin_vertex_scale; + } + } + d + }, + ); + } + if !any { + return None; + } + builder.build(slots.names.clone()).map(Arc::new) + } +} + +/// A `weights` channel of an animation, as a track over model slots. +/// `None` when the channel is not a weights channel or its node has no mesh. +pub(super) fn read_weight_channel<'a, 's, F>( + channel: &gltf::animation::Channel<'a>, + get_buffer_data: F, + slots: &MorphSlots, +) -> Option +where + F: Clone + Fn(gltf::Buffer<'a>) -> Option<&'s [u8]>, +{ + use gltf::animation::util::ReadOutputs; + if channel.target().property() != gltf::animation::Property::MorphTargetWeights { + return None; + } + let mesh = channel.target().node().mesh()?; + let mesh_slots = slots.per_mesh.get(mesh.index())?; + let n = mesh_slots.len(); + if n == 0 { + return None; + } + let reader = channel.reader(get_buffer_data); + let times: Vec = reader.read_inputs()?.collect(); + let raw: Vec = match reader.read_outputs()? { + ReadOutputs::MorphTargetWeights(w) => w.into_f32().collect(), + _ => return None, + }; + let interpolation = channel.sampler().interpolation(); + let values = if interpolation == gltf::animation::Interpolation::CubicSpline { + // in-tangent, value, out-tangent per key: keep the values. + raw.chunks(n * 3) + .flat_map(|key| key[n..(2 * n).min(key.len())].iter().copied()) + .collect() + } else { + raw + }; + if values.len() < times.len() * n { + return None; + } + Some(crate::anim_morph::MorphTrack { + slots: mesh_slots.clone(), + times, + values, + step: interpolation == gltf::animation::Interpolation::Step, + }) +} + +#[cfg(test)] +#[path = "models_gltf_morph_tests.rs"] +mod tests; diff --git a/native/shared/src/models_gltf_morph_tests.rs b/native/shared/src/models_gltf_morph_tests.rs new file mode 100644 index 00000000..c9ae09ad --- /dev/null +++ b/native/shared/src/models_gltf_morph_tests.rs @@ -0,0 +1,252 @@ +use super::super::*; + +/// Binary chunk under construction: each push is one buffer view. +#[derive(Default)] +struct Bin { + data: Vec, + views: Vec, +} + +impl Bin { + fn push(&mut self, bytes: &[u8]) -> usize { + while self.data.len() % 4 != 0 { + self.data.push(0); + } + let offset = self.data.len(); + self.data.extend_from_slice(bytes); + self.views.push(format!( + r#"{{"buffer":0,"byteOffset":{offset},"byteLength":{}}}"#, + bytes.len() + )); + self.views.len() - 1 + } + fn f32s(&mut self, values: &[f32]) -> usize { + let bytes: Vec = values.iter().flat_map(|v| v.to_le_bytes()).collect(); + self.push(&bytes) + } + fn u16s(&mut self, values: &[u16]) -> usize { + let bytes: Vec = values.iter().flat_map(|v| v.to_le_bytes()).collect(); + self.push(&bytes) + } +} + +fn glb(json: &str, bin: &[u8]) -> Vec { + let mut json = json.as_bytes().to_vec(); + while json.len() % 4 != 0 { + json.push(b' '); + } + let mut bin = bin.to_vec(); + while bin.len() % 4 != 0 { + bin.push(0); + } + let total = 12 + 8 + json.len() + 8 + bin.len(); + let mut out = Vec::with_capacity(total); + out.extend_from_slice(b"glTF"); + out.extend_from_slice(&2u32.to_le_bytes()); + out.extend_from_slice(&(total as u32).to_le_bytes()); + out.extend_from_slice(&(json.len() as u32).to_le_bytes()); + out.extend_from_slice(b"JSON"); + out.extend_from_slice(&json); + out.extend_from_slice(&(bin.len() as u32).to_le_bytes()); + out.extend_from_slice(b"BIN\0"); + out.extend_from_slice(&bin); + out +} + +/// A skinned face quad with "jawOpen" (dense accessor) and "smile" (a +/// SPARSE accessor without a buffer view, as Blender writes shape keys), +/// and an unskinned teeth triangle with "jawOpen" and an all-zero +/// "tongueOut". One animation drives the face's two weights. +fn face_glb() -> Vec { + let mut b = Bin::default(); + let mut acc: Vec = Vec::new(); + let mut accessor = |view: usize, ty: &str, ct: u32, count: usize, extra: &str| { + acc.push(format!( + r#"{{"bufferView":{view},"componentType":{ct},"count":{count},"type":"{ty}"{extra}}}"# + )); + acc.len() - 1 + }; + let face_pos = b.f32s(&[0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 0.0, 1.0, 0.0]); + let face_joints = b.u16s(&[0; 16]); + let face_weights = b.f32s(&[ + 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, + ]); + let face_idx = b.u16s(&[0, 1, 2, 0, 2, 3]); + let jaw_pos = b.f32s(&[0.0, -0.25, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]); + let smile_nrm = b.f32s(&[0.0; 12]); + let smile_idx = b.u16s(&[2]); + let smile_val = b.f32s(&[0.125, 0.0, 0.0]); + let teeth_pos = b.f32s(&[0.0, 0.0, 0.1, 1.0, 0.0, 0.1, 0.5, 0.5, 0.1]); + let teeth_idx = b.u16s(&[0, 1, 2]); + let teeth_jaw = b.f32s(&[0.0, -0.2, 0.0, 0.0, -0.2, 0.0, 0.0, 0.0, 0.0]); + let teeth_tongue = b.f32s(&[0.0; 9]); + let times = b.f32s(&[0.0, 1.0]); + let weights = b.f32s(&[0.0, 0.0, 1.0, 0.5]); + let ibm = b.f32s(&[ + 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, + ]); + + let a_face_pos = accessor(face_pos, "VEC3", 5126, 4, r#","min":[0,0,0],"max":[1,1,0]"#); + let a_face_j = accessor(face_joints, "VEC4", 5123, 4, ""); + let a_face_w = accessor(face_weights, "VEC4", 5126, 4, ""); + let a_face_i = accessor(face_idx, "SCALAR", 5123, 6, ""); + let a_jaw = accessor( + jaw_pos, + "VEC3", + 5126, + 4, + r#","min":[0,-0.25,0],"max":[0,0,0]"#, + ); + let a_smile_n = accessor(smile_nrm, "VEC3", 5126, 4, ""); + // Sparse, no bufferView: zeros with one substituted element. + acc.push(format!( + r#"{{"componentType":5126,"count":4,"type":"VEC3","min":[0,0,0],"max":[0.125,0,0], + "sparse":{{"count":1,"indices":{{"bufferView":{smile_idx},"componentType":5123}}, + "values":{{"bufferView":{smile_val}}}}}}}"# + )); + let a_smile_p = acc.len() - 1; + let mut accessor = |view: usize, ty: &str, ct: u32, count: usize, extra: &str| { + acc.push(format!( + r#"{{"bufferView":{view},"componentType":{ct},"count":{count},"type":"{ty}"{extra}}}"# + )); + acc.len() - 1 + }; + let a_teeth_pos = accessor( + teeth_pos, + "VEC3", + 5126, + 3, + r#","min":[0,0,0.1],"max":[1,0.5,0.1]"#, + ); + let a_teeth_i = accessor(teeth_idx, "SCALAR", 5123, 3, ""); + let a_teeth_jaw = accessor( + teeth_jaw, + "VEC3", + 5126, + 3, + r#","min":[0,-0.2,0],"max":[0,0,0]"#, + ); + let a_tongue = accessor( + teeth_tongue, + "VEC3", + 5126, + 3, + r#","min":[0,0,0],"max":[0,0,0]"#, + ); + let a_times = accessor(times, "SCALAR", 5126, 2, r#","min":[0],"max":[1]"#); + let a_weights = accessor(weights, "SCALAR", 5126, 4, ""); + let a_ibm = accessor(ibm, "MAT4", 5126, 1, ""); + + let json = format!( + r#"{{ + "asset":{{"version":"2.0"}}, + "scene":0, + "scenes":[{{"nodes":[0,1,2]}}], + "nodes":[ + {{"name":"Face","mesh":0,"skin":0}}, + {{"name":"Teeth","mesh":1}}, + {{"name":"Head"}} + ], + "skins":[{{"joints":[2],"inverseBindMatrices":{a_ibm}}}], + "meshes":[ + {{"name":"Face","extras":{{"targetNames":["jawOpen","smile"]}}, + "primitives":[{{"attributes":{{"POSITION":{a_face_pos},"JOINTS_0":{a_face_j},"WEIGHTS_0":{a_face_w}}}, + "indices":{a_face_i}, + "targets":[{{"POSITION":{a_jaw}}},{{"POSITION":{a_smile_p},"NORMAL":{a_smile_n}}}]}}]}}, + {{"name":"Teeth","extras":{{"targetNames":["jawOpen","tongueOut"]}}, + "primitives":[{{"attributes":{{"POSITION":{a_teeth_pos}}},"indices":{a_teeth_i}, + "targets":[{{"POSITION":{a_teeth_jaw}}},{{"POSITION":{a_tongue}}}]}}]}} + ], + "animations":[{{"name":"talk", + "samplers":[{{"input":{a_times},"output":{a_weights},"interpolation":"LINEAR"}}], + "channels":[{{"sampler":0,"target":{{"node":0,"path":"weights"}}}}]}}], + "buffers":[{{"byteLength":{len}}}], + "bufferViews":[{views}], + "accessors":[{accessors}] +}}"#, + len = b.data.len(), + views = b.views.join(","), + accessors = acc.join(","), + ); + glb(&json, &b.data) +} + +#[test] +fn targets_share_slots_by_name_and_sparse_accessors_are_read() { + let data = face_glb(); + let model = load_gltf(&data).expect("synthetic morph GLB loads"); + let face = model + .meshes + .iter() + .find(|m| m.vertices.len() == 4) + .expect("face"); + let teeth = model + .meshes + .iter() + .find(|m| m.vertices.len() == 3) + .expect("teeth"); + let fm = face.morph.as_ref().expect("face has morphs"); + let tm = teeth.morph.as_ref().expect("teeth have morphs"); + // One name table for the model: jawOpen, smile, tongueOut. + assert_eq!( + fm.names.as_slice(), + &["jawOpen".to_string(), "smile".into(), "tongueOut".into()] + ); + assert!(Arc::ptr_eq(&fm.names, &tm.names)); + // jawOpen moves face vertex 0; the sparse smile moves vertex 2 only. + assert_eq!(fm.ranges, vec![0, 1, 1, 2, 2]); + assert_eq!(fm.vertex_entries(0)[0].slot, 0); + assert_eq!(fm.vertex_entries(2)[0].slot, 1); + let jaw = fm.position_offset(0, &[1.0, 0.0, 0.0]); + assert!((jaw[1] + 0.25).abs() < 1e-3, "{jaw:?}"); + let smile = fm.position_offset(2, &[0.0, 1.0, 0.0]); + assert!((smile[0] - 0.125).abs() < 1e-3, "{smile:?}"); + // The teeth's jawOpen is slot 0 too; the all-zero tongueOut costs no entry. + assert_eq!(tm.entries.len(), 2); + assert!(tm.entries.iter().all(|e| e.slot == 0)); + let teeth_jaw = tm.position_offset(1, &[0.5]); + assert!((teeth_jaw[1] + 0.1).abs() < 1e-3); + assert!(!fm.has_tangents && fm.has_normals); +} + +#[test] +fn every_loader_reads_the_same_targets() { + let data = face_glb(); + let plain = load_gltf(&data).unwrap(); + let staged = load_gltf_staged(&data).unwrap().model; + let count = |m: &ModelData| -> Vec { + m.meshes + .iter() + .map(|mesh| mesh.morph.as_ref().map_or(0, |t| t.entries.len())) + .collect() + }; + assert_eq!(count(&plain), count(&staged)); + assert_eq!(count(&plain).iter().sum::(), 4); +} + +#[test] +fn weights_channels_become_tracks_over_model_slots() { + let data = face_glb(); + let anim = load_gltf_animation(&data).expect("animation loads"); + let clip = &anim.animations[0]; + assert_eq!(clip.morph_tracks.len(), 1); + let track = &clip.morph_tracks[0]; + assert_eq!(track.slots, vec![0, 1]); + assert_eq!(track.times, vec![0.0, 1.0]); + assert_eq!(track.values, vec![0.0, 0.0, 1.0, 0.5]); + assert!((clip.duration - 1.0).abs() < 1e-6); + + // Through the mixer, by name, with an explicit weight on top. + let mut manager = ModelManager::new(); + let model = manager.models.alloc(load_gltf(&data).unwrap()); + let h = manager.animations.alloc(anim); + assert_eq!(manager.model_morph_count(model), 3); + assert_eq!(manager.model_morph_index(model, "smile"), 1); + assert_eq!(manager.model_morph_index(model, "frown"), -1); + manager.anim_play(h, 0, 0.0, 1.0, false); + manager.advance_and_update(h, 0.5); + assert!((manager.anim_morph_weight(h, 0) - 0.5).abs() < 1e-5); + assert!((manager.anim_morph_weight(h, 1) - 0.25).abs() < 1e-5); + manager.anim_set_morph_weight(h, 2, 0.4); + assert!((manager.anim_morph_weight(h, 2) - 0.4).abs() < 1e-6); +} diff --git a/native/shared/src/models_spline.rs b/native/shared/src/models_spline.rs new file mode 100644 index 00000000..887d7025 --- /dev/null +++ b/native/shared/src/models_spline.rs @@ -0,0 +1,50 @@ +//! Catmull-Rom spline helpers of `gen_mesh_spline_ribbon` (split from models.rs). + +// ---- Catmull-Rom spline helpers (Q9) ---- + +pub(super) fn catmull_rom_point(points: &[f32], n: usize, segment: usize, t: f32) -> [f32; 3] { + // Indices: p0 = segment - 1, p1 = segment, p2 = segment + 1, p3 = segment + 2. + // Clamp at boundaries. + let i0 = if segment > 0 { segment - 1 } else { 0 }; + let i1 = segment; + let i2 = if segment + 1 < n { segment + 1 } else { n - 1 }; + let i3 = if segment + 2 < n { segment + 2 } else { n - 1 }; + + let p0 = [points[i0 * 3], points[i0 * 3 + 1], points[i0 * 3 + 2]]; + let p1 = [points[i1 * 3], points[i1 * 3 + 1], points[i1 * 3 + 2]]; + let p2 = [points[i2 * 3], points[i2 * 3 + 1], points[i2 * 3 + 2]]; + let p3 = [points[i3 * 3], points[i3 * 3 + 1], points[i3 * 3 + 2]]; + + let t2 = t * t; + let t3 = t2 * t; + let mut out = [0.0f32; 3]; + for k in 0..3 { + out[k] = 0.5 + * ((2.0 * p1[k]) + + (-p0[k] + p2[k]) * t + + (2.0 * p0[k] - 5.0 * p1[k] + 4.0 * p2[k] - p3[k]) * t2 + + (-p0[k] + 3.0 * p1[k] - 3.0 * p2[k] + p3[k]) * t3); + } + out +} + +pub(super) fn update_bounds(bmin: &mut [f32; 3], bmax: &mut [f32; 3], x: f32, y: f32, z: f32) { + if x < bmin[0] { + bmin[0] = x; + } + if y < bmin[1] { + bmin[1] = y; + } + if z < bmin[2] { + bmin[2] = z; + } + if x > bmax[0] { + bmax[0] = x; + } + if y > bmax[1] { + bmax[1] = y; + } + if z > bmax[2] { + bmax[2] = z; + } +} diff --git a/native/shared/src/models_virtual_geometry.rs b/native/shared/src/models_virtual_geometry.rs index bb4bb2c1..60f69c01 100644 --- a/native/shared/src/models_virtual_geometry.rs +++ b/native/shared/src/models_virtual_geometry.rs @@ -346,6 +346,7 @@ mod tests { double_sided: false, transmission: MaterialTransmission::default(), layered_pbr: MaterialLayeredPbr::default(), + morph: None, }) } diff --git a/native/shared/src/morph_targets.rs b/native/shared/src/morph_targets.rs new file mode 100644 index 00000000..8b1bf2dd --- /dev/null +++ b/native/shared/src/morph_targets.rs @@ -0,0 +1,535 @@ +//! Morph targets (glTF blend shapes): the data a mesh keeps, and the CPU +//! reference of what the GPU pass computes. `docs/morph-targets.md` is the +//! overview. +//! +//! A face rig moves a few thousand of a character's vertices with each of +//! its ~50 shapes; most of the mesh (the body, the clothes) is touched by +//! none. So the deltas are stored sparse, as a per-vertex list (CSR): +//! +//! - `ranges[v]..ranges[v + 1]` are vertex `v`'s entries in `entries`, so an +//! untouched vertex costs one `u32` and a touched one its entries only; +//! - an entry is one target's delta on one vertex: the model-level morph +//! slot it belongs to and the position, normal and tangent deltas as half +//! floats (24 bytes). Positions are stored divided by `pos_scale` (the +//! largest position delta component of the mesh) so the halves always lie +//! in [-1, 1]: no overflow whatever the units, and the precision is a +//! fixed fraction (2^-11) of the largest delta. +//! +//! The per-vertex layout is what the GPU wants: one thread per vertex sums +//! its own entries, no atomics, no scatter. Entries of a vertex are sorted +//! by slot. +//! +//! Slots are model-level: every mesh of a model numbers its targets by the +//! model's name table, so "jawOpen" on the face, the teeth and the tongue is +//! one slot and one weight drives all three. + +use crate::renderer::Vertex3D; +use std::sync::Arc; + +/// Below this a delta component counts as zero (an exporter writes the +/// whole mesh for every target, untouched vertices included). +pub const MORPH_DELTA_EPSILON: f32 = 1e-6; + +/// Most slots a model or an animation instance may have. +pub const MAX_MORPH_SLOTS: usize = 1024; + +/// One target's delta on one vertex, as the GPU reads it (6 x u32). +#[repr(C)] +#[derive(Clone, Copy, Debug, PartialEq, Eq, bytemuck::Pod, bytemuck::Zeroable)] +pub struct MorphEntry { + /// Model-level morph slot. + pub slot: u32, + /// Half floats, low half first (WGSL `unpack2x16float` order): + /// [pos.x pos.y] [pos.z nrm.x] [nrm.y nrm.z] [tan.x tan.y] [tan.z 0]. + /// Positions are divided by `MorphTargets::pos_scale`. + pub packed: [u32; 5], +} + +/// Sparse morph deltas of one primitive. Immutable after load and shared +/// (via `Arc`) between every placement and every instance of the mesh; +/// the weights are per animation instance. +#[derive(Debug)] +pub struct MorphTargets { + /// The model's slot names (`targetNames`), the same `Arc` on every + /// mesh of one load. Unnamed targets are called `"#"`. + pub names: Arc>, + pub vertex_count: u32, + /// `vertex_count + 1` offsets into `entries`. + pub ranges: Vec, + pub entries: Vec, + pub pos_scale: f32, + /// Per axis, the most any vertex can move with every weight in [-1, 1]: + /// max over vertices of the sum of |position delta|. Bounds grow by it. + pub bound_growth: [f32; 3], + /// Vertices with at least one entry. + pub touched_vertices: u32, + pub has_normals: bool, + pub has_tangents: bool, +} + +/// Decoded delta of one entry: position (already times `pos_scale`), normal, +/// tangent. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct MorphDelta { + pub position: [f32; 3], + pub normal: [f32; 3], + pub tangent: [f32; 3], +} + +fn half_bits(value: f32) -> u32 { + u32::from(half::f16::from_f32(value).to_bits()) +} + +fn half_value(bits: u32) -> f32 { + half::f16::from_bits((bits & 0xffff) as u16).to_f32() +} + +fn pack2(lo: f32, hi: f32) -> u32 { + half_bits(lo) | (half_bits(hi) << 16) +} + +fn unpack2(word: u32) -> (f32, f32) { + (half_value(word), half_value(word >> 16)) +} + +/// Collects targets of one primitive, then packs them. +pub struct MorphTargetsBuilder { + vertex_count: usize, + /// Per vertex: (slot, position, normal, tangent) in f32. + per_vertex: Vec>, + has_normals: bool, + has_tangents: bool, +} + +impl MorphTargetsBuilder { + pub fn new(vertex_count: usize) -> Self { + Self { + vertex_count, + per_vertex: vec![Vec::new(); vertex_count], + has_normals: false, + has_tangents: false, + } + } + + /// Add one target. Each stream is per vertex (missing = no delta); + /// a stream of the wrong length is ignored. `transform` maps a vertex's + /// delta (position, normal, tangent as 9 floats) into the space the + /// loader put the vertex in (skin scale, baked node transform). + pub fn add_target( + &mut self, + slot: u32, + positions: Option<&[[f32; 3]]>, + normals: Option<&[[f32; 3]]>, + tangents: Option<&[[f32; 3]]>, + transform: impl Fn(usize, [f32; 9]) -> [f32; 9], + ) { + let n = self.vertex_count; + let positions = positions.filter(|s| s.len() == n); + let normals = normals.filter(|s| s.len() == n); + let tangents = tangents.filter(|s| s.len() == n); + self.has_normals |= normals.is_some(); + self.has_tangents |= tangents.is_some(); + for v in 0..n { + let mut delta = [0.0f32; 9]; + if let Some(p) = positions { + delta[0..3].copy_from_slice(&p[v]); + } + if let Some(nr) = normals { + delta[3..6].copy_from_slice(&nr[v]); + } + if let Some(t) = tangents { + delta[6..9].copy_from_slice(&t[v]); + } + if delta + .iter() + .all(|c| c.abs() < MORPH_DELTA_EPSILON || !c.is_finite()) + { + continue; + } + let mut delta = transform(v, delta); + for c in delta.iter_mut() { + if !c.is_finite() || c.abs() < MORPH_DELTA_EPSILON { + *c = 0.0; + } + } + if delta.iter().all(|c| *c == 0.0) { + continue; + } + let list = &mut self.per_vertex[v]; + // Two targets of one primitive with the same name share a slot: + // their deltas add, as two shapes at the same weight would. + if let Some(existing) = list.iter_mut().find(|(s, _)| *s == slot) { + for (a, b) in existing.1.iter_mut().zip(delta) { + *a += b; + } + } else { + list.push((slot, delta)); + } + } + } + + /// Pack. `None` when no target moved any vertex. + pub fn build(mut self, names: Arc>) -> Option { + let mut pos_scale = 0.0f32; + let mut count = 0usize; + for list in &mut self.per_vertex { + list.sort_by_key(|(slot, _)| *slot); + count += list.len(); + for (_, d) in list.iter() { + for c in &d[0..3] { + pos_scale = pos_scale.max(c.abs()); + } + } + } + if count == 0 { + return None; + } + if pos_scale <= 0.0 { + pos_scale = 1.0; + } + // Normal and tangent deltas of unit vectors lie in [-2, 2]; anything + // past the half range is broken data, clamped rather than packed as + // infinity. + let clamp_dir = |c: f32| c.clamp(-60000.0, 60000.0); + let mut ranges = Vec::with_capacity(self.vertex_count + 1); + let mut entries = Vec::with_capacity(count); + let mut bound_growth = [0.0f32; 3]; + let mut touched = 0u32; + for list in &self.per_vertex { + ranges.push(entries.len() as u32); + if !list.is_empty() { + touched += 1; + } + let mut sum = [0.0f32; 3]; + for (slot, d) in list { + let p = [d[0] / pos_scale, d[1] / pos_scale, d[2] / pos_scale]; + let entry = MorphEntry { + slot: *slot, + packed: [ + pack2(p[0], p[1]), + pack2(p[2], clamp_dir(d[3])), + pack2(clamp_dir(d[4]), clamp_dir(d[5])), + pack2(clamp_dir(d[6]), clamp_dir(d[7])), + pack2(clamp_dir(d[8]), 0.0), + ], + }; + let decoded = decode_entry(&entry, pos_scale); + for a in 0..3 { + sum[a] += decoded.position[a].abs(); + } + entries.push(entry); + } + for a in 0..3 { + bound_growth[a] = bound_growth[a].max(sum[a]); + } + } + ranges.push(entries.len() as u32); + Some(MorphTargets { + names, + vertex_count: self.vertex_count as u32, + ranges, + entries, + pos_scale, + bound_growth, + touched_vertices: touched, + has_normals: self.has_normals, + has_tangents: self.has_tangents, + }) + } +} + +/// Decode one entry. +pub fn decode_entry(entry: &MorphEntry, pos_scale: f32) -> MorphDelta { + let (px, py) = unpack2(entry.packed[0]); + let (pz, nx) = unpack2(entry.packed[1]); + let (ny, nz) = unpack2(entry.packed[2]); + let (tx, ty) = unpack2(entry.packed[3]); + let (tz, _) = unpack2(entry.packed[4]); + MorphDelta { + position: [px * pos_scale, py * pos_scale, pz * pos_scale], + normal: [nx, ny, nz], + tangent: [tx, ty, tz], + } +} + +fn normalize_or(v: [f32; 3], fallback: [f32; 3]) -> [f32; 3] { + let len = (v[0] * v[0] + v[1] * v[1] + v[2] * v[2]).sqrt(); + if len > 1e-12 { + [v[0] / len, v[1] / len, v[2] / len] + } else { + fallback + } +} + +impl MorphTargets { + /// Entries of vertex `v`. + pub fn vertex_entries(&self, v: usize) -> &[MorphEntry] { + let lo = self.ranges[v] as usize; + let hi = self.ranges[v + 1] as usize; + &self.entries[lo..hi] + } + + /// Bytes this mesh's deltas take (CPU copy; the GPU copy is the same). + pub fn byte_size(&self) -> usize { + self.ranges.len() * 4 + self.entries.len() * std::mem::size_of::() + } + + /// The morphed vertex `v` of `base` at `weights` (indexed by slot, + /// missing slots are 0): exactly what the GPU pass writes. Position adds + /// the weighted deltas; normal and tangent add theirs and are + /// renormalised (a tangent that was the zero "no tangent" sentinel stays + /// zero; the tangent's handedness `w` is kept). + pub fn morph_vertex(&self, base: &Vertex3D, v: usize, weights: &[f32]) -> Vertex3D { + let mut out = *base; + let (dp, dn, dt) = self.weighted(v, weights); + for a in 0..3 { + out.position[a] += dp[a]; + } + if self.has_normals { + let n = [ + base.normal[0] + dn[0], + base.normal[1] + dn[1], + base.normal[2] + dn[2], + ]; + out.normal = normalize_or(n, base.normal); + } + let bt = [base.tangent[0], base.tangent[1], base.tangent[2]]; + if self.has_tangents && bt.iter().any(|c| *c != 0.0) { + let t = normalize_or([bt[0] + dt[0], bt[1] + dt[1], bt[2] + dt[2]], bt); + out.tangent = [t[0], t[1], t[2], base.tangent[3]]; + } + out + } + + /// The weighted position delta of vertex `v`. + pub fn position_offset(&self, v: usize, weights: &[f32]) -> [f32; 3] { + self.weighted(v, weights).0 + } + + fn weighted(&self, v: usize, weights: &[f32]) -> ([f32; 3], [f32; 3], [f32; 3]) { + let mut dp = [0.0f32; 3]; + let mut dn = [0.0f32; 3]; + let mut dt = [0.0f32; 3]; + for entry in self.vertex_entries(v) { + let w = weights.get(entry.slot as usize).copied().unwrap_or(0.0); + if w == 0.0 { + continue; + } + let d = decode_entry(entry, self.pos_scale); + for a in 0..3 { + dp[a] += w * d.position[a]; + dn[a] += w * d.normal[a]; + dt[a] += w * d.tangent[a]; + } + } + (dp, dn, dt) + } + + /// Grow an AABB of the rest mesh so it holds every pose the targets can + /// make with weights in [-1, 1]. + pub fn grow_bounds(&self, min: &mut [f32; 3], max: &mut [f32; 3]) { + if min[0] > max[0] { + return; + } + for a in 0..3 { + min[a] -= self.bound_growth[a]; + max[a] += self.bound_growth[a]; + } + } + + /// A copy with the deltas of some vertices mapped by `transform` (the + /// loader's bake of a node transform into rigid vertices). + pub fn mapped( + &self, + mut transform: impl FnMut(usize, MorphDelta) -> Option, + ) -> Option { + let mut builder = MorphTargetsBuilder::new(self.vertex_count as usize); + builder.has_normals = self.has_normals; + builder.has_tangents = self.has_tangents; + for v in 0..self.vertex_count as usize { + for entry in self.vertex_entries(v) { + let d = decode_entry(entry, self.pos_scale); + let d = transform(v, d).unwrap_or(d); + let mut packed = [0.0f32; 9]; + packed[0..3].copy_from_slice(&d.position); + packed[3..6].copy_from_slice(&d.normal); + packed[6..9].copy_from_slice(&d.tangent); + builder.per_vertex[v].push((entry.slot, packed)); + } + } + builder.build(self.names.clone()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn vertex(position: [f32; 3]) -> Vertex3D { + Vertex3D { + position, + normal: [0.0, 0.0, 1.0], + color: [1.0; 4], + uv: [0.0; 2], + joints: [0.0; 4], + weights: [1.0, 0.0, 0.0, 0.0], + tangent: [1.0, 0.0, 0.0, 1.0], + } + } + + fn names(n: usize) -> Arc> { + Arc::new((0..n).map(|i| format!("t{i}")).collect()) + } + + #[test] + fn untouched_vertices_cost_no_entries_and_entries_sort_by_slot() { + let mut b = MorphTargetsBuilder::new(5); + // Target 1 touches vertices 1 and 3; target 0 only vertex 3. The + // exporter wrote every vertex: the zeros must be dropped. + let t1 = [ + [0.0; 3], + [0.0, 0.25, 0.0], + [0.0; 3], + [0.5, 0.0, 0.0], + [1e-8, 0.0, 0.0], + ]; + let t0 = [[0.0; 3], [0.0; 3], [0.0; 3], [0.0, 0.0, -0.125], [0.0; 3]]; + b.add_target(1, Some(&t1), None, None, |_, d| d); + b.add_target(0, Some(&t0), None, None, |_, d| d); + let m = b.build(names(2)).expect("targets moved vertices"); + assert_eq!(m.ranges, vec![0, 0, 1, 1, 3, 3]); + assert_eq!(m.touched_vertices, 2); + assert_eq!(m.entries.len(), 3); + let slots: Vec = m.vertex_entries(3).iter().map(|e| e.slot).collect(); + assert_eq!(slots, vec![0, 1]); + assert_eq!(m.pos_scale, 0.5); + // 24 B an entry, 4 B a vertex. + assert_eq!(m.byte_size(), 6 * 4 + 3 * 24); + } + + #[test] + fn nothing_moved_builds_nothing() { + let mut b = MorphTargetsBuilder::new(3); + b.add_target( + 0, + Some(&[[0.0; 3]; 3]), + Some(&[[0.0; 3]; 3]), + None, + |_, d| d, + ); + assert!(b.build(names(1)).is_none()); + } + + #[test] + fn half_packing_keeps_a_fixed_fraction_of_the_largest_delta() { + // Centimetre-scale units (deltas of tens) and metre-scale (hundredths) + // must both survive: positions are normalised before packing. + for scale in [0.01f32, 1.0, 100.0, 30000.0] { + let mut b = MorphTargetsBuilder::new(2); + let p = [ + [0.3 * scale, -0.7 * scale, 0.0123 * scale], + [scale, 0.0, 0.0], + ]; + b.add_target(0, Some(&p), None, None, |_, d| d); + let m = b.build(names(1)).unwrap(); + let d = decode_entry(&m.vertex_entries(0)[0], m.pos_scale); + for a in 0..3 { + let err = (d.position[a] - p[0][a]).abs(); + assert!(err <= scale * 1.0 / 2048.0, "scale {scale} axis {a}: {err}"); + } + } + } + + #[test] + fn cpu_morph_adds_weighted_deltas_and_renormalises() { + let mut b = MorphTargetsBuilder::new(1); + b.add_target( + 0, + Some(&[[0.0, 1.0, 0.0]]), + Some(&[[0.0, 1.0, -1.0]]), + None, + |_, d| d, + ); + b.add_target(2, Some(&[[0.5, 0.0, 0.0]]), None, None, |_, d| d); + let m = b.build(names(3)).unwrap(); + let base = vertex([1.0, 2.0, 3.0]); + let out = m.morph_vertex(&base, 0, &[0.5, 9.0, 1.0]); + assert!((out.position[0] - 1.5).abs() < 1e-3); + assert!((out.position[1] - 2.5).abs() < 1e-3); + assert!((out.position[2] - 3.0).abs() < 1e-6); + // normal (0,0,1) + 0.5*(0,1,-1) = (0,0.5,0.5) -> normalised + let r = std::f32::consts::FRAC_1_SQRT_2; + assert!((out.normal[1] - r).abs() < 1e-3 && (out.normal[2] - r).abs() < 1e-3); + // no tangent stream: tangent untouched + assert_eq!(out.tangent, base.tangent); + // all weights zero: the bind pose exactly + let rest = m.morph_vertex(&base, 0, &[0.0; 3]); + assert_eq!(rest.position, base.position); + assert_eq!(rest.normal, base.normal); + // slots past the weights are 0 + assert_eq!(m.morph_vertex(&base, 0, &[]).position, base.position); + } + + #[test] + fn bounds_grow_by_the_most_any_vertex_can_move() { + let mut b = MorphTargetsBuilder::new(2); + b.add_target( + 0, + Some(&[[0.1, 0.0, 0.0], [0.0, 0.2, 0.0]]), + None, + None, + |_, d| d, + ); + b.add_target( + 1, + Some(&[[-0.3, 0.0, 0.0], [0.0, 0.2, 0.05]]), + None, + None, + |_, d| d, + ); + let m = b.build(names(2)).unwrap(); + let g = m.bound_growth; + assert!((g[0] - 0.4).abs() < 1e-3, "{g:?}"); + assert!((g[1] - 0.4).abs() < 1e-3, "{g:?}"); + assert!((g[2] - 0.05).abs() < 1e-3, "{g:?}"); + let (mut lo, mut hi) = ([0.0; 3], [1.0; 3]); + m.grow_bounds(&mut lo, &mut hi); + assert!(lo[0] < -0.39 && hi[0] > 1.39); + // the empty-AABB sentinel stays empty + let (mut lo, mut hi) = ([1.0; 3], [-1.0; 3]); + m.grow_bounds(&mut lo, &mut hi); + assert!(lo[0] > hi[0]); + } + + #[test] + fn a_transform_maps_the_deltas_of_the_vertices_it_names() { + let mut b = MorphTargetsBuilder::new(2); + b.add_target( + 0, + Some(&[[1.0, 0.0, 0.0], [1.0, 0.0, 0.0]]), + None, + None, + |v, mut d| { + if v == 1 { + for c in &mut d[0..3] { + *c *= 100.0; + } + } + d + }, + ); + let m = b.build(names(1)).unwrap(); + assert!((m.position_offset(0, &[1.0])[0] - 1.0).abs() < 0.05); + assert!((m.position_offset(1, &[1.0])[0] - 100.0).abs() < 0.05); + let swapped = m + .mapped(|v, d| { + (v == 0).then_some(MorphDelta { + position: [0.0, d.position[0], 0.0], + ..d + }) + }) + .unwrap(); + assert!((swapped.position_offset(0, &[1.0])[1] - 1.0).abs() < 0.05); + assert!((swapped.position_offset(1, &[1.0])[0] - 100.0).abs() < 0.05); + } +} diff --git a/native/shared/src/renderer/joint_pages.rs b/native/shared/src/renderer/joint_pages.rs index be36b3c3..405040d4 100644 --- a/native/shared/src/renderer/joint_pages.rs +++ b/native/shared/src/renderer/joint_pages.rs @@ -83,6 +83,68 @@ pub(super) fn joint_offset_in_page(joint_offset: f32) -> f32 { (joint_offset.max(0.0) as usize % JOINTS_PER_PAGE) as f32 } +/// The joint bind group layout: this frame's palette (binding 0), the +/// previous frame's (1), both uniform blocks, and the morph arena (2: per +/// vertex previous-minus-current morph displacement, `morph_pass.rs`), all +/// read by vertex shaders only. A shader may use any subset. +pub(super) fn create_joint_layout(device: &wgpu::Device) -> wgpu::BindGroupLayout { + let palette = |binding| wgpu::BindGroupLayoutEntry { + binding, + visibility: wgpu::ShaderStages::VERTEX, + ty: wgpu::BindingType::Buffer { + ty: wgpu::BufferBindingType::Uniform, + has_dynamic_offset: false, + min_binding_size: None, + }, + count: None, + }; + device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor { + label: Some("joint_layout"), + entries: &[ + palette(0), + palette(1), + wgpu::BindGroupLayoutEntry { + binding: 2, + visibility: wgpu::ShaderStages::VERTEX, + ty: wgpu::BindingType::Texture { + sample_type: wgpu::TextureSampleType::Float { filterable: false }, + view_dimension: wgpu::TextureViewDimension::D2, + multisampled: false, + }, + count: None, + }, + ], + }) +} + +/// A bind group of `create_joint_layout`. +pub(super) fn joint_bind_group( + device: &wgpu::Device, + layout: &wgpu::BindGroupLayout, + palette: &wgpu::Buffer, + prev_palette: &wgpu::Buffer, + morph_arena: &wgpu::TextureView, +) -> wgpu::BindGroup { + device.create_bind_group(&wgpu::BindGroupDescriptor { + label: Some("joint_bg"), + layout, + entries: &[ + wgpu::BindGroupEntry { + binding: 0, + resource: palette.as_entire_binding(), + }, + wgpu::BindGroupEntry { + binding: 1, + resource: prev_palette.as_entire_binding(), + }, + wgpu::BindGroupEntry { + binding: 2, + resource: wgpu::BindingResource::TextureView(morph_arena), + }, + ], + }) +} + const IDENTITY_JOINT: [[f32; 4]; 4] = [ [1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], @@ -196,6 +258,9 @@ impl Renderer { /// Upload the frame's palette, page by page, and reset the staging state. pub(super) fn flush_joint_matrices(&mut self) { + // Morph jobs of the draws recorded this frame run first: the passes + // below draw from their buffers. + self.encode_morph_pass(); // Accumulator = all skinned poses staged by skinned drawModel // calls this frame, packed consecutively. Each draw carries the // offset of its group, so a flat upload per page is all the GPU needs. @@ -248,6 +313,7 @@ impl Renderer { // Any leftover staged poses are stale (no draw consumed them). self.pending_skin_groups.clear(); self.pending_skin_groups_prev.clear(); + self.morph.clear_pending(); } fn create_joint_page(&self) -> JointPage { @@ -262,20 +328,13 @@ impl Renderer { }; let buffer = make("joint_page_buffer"); let prev_buffer = make("joint_page_prev_buffer"); - let bind_group = self.device.create_bind_group(&wgpu::BindGroupDescriptor { - label: Some("joint_page_bg"), - layout: &self.joint_layout, - entries: &[ - wgpu::BindGroupEntry { - binding: 0, - resource: buffer.as_entire_binding(), - }, - wgpu::BindGroupEntry { - binding: 1, - resource: prev_buffer.as_entire_binding(), - }, - ], - }); + let bind_group = joint_bind_group( + &self.device, + &self.joint_layout, + &buffer, + &prev_buffer, + self.morph.arena_view(), + ); JointPage { buffer, prev_buffer, @@ -283,6 +342,26 @@ impl Renderer { } } + /// The morph arena was remade (it grew): every joint bind group shows it. + pub(super) fn rebuild_joint_bind_groups(&mut self) { + self.joint_bind_group = joint_bind_group( + &self.device, + &self.joint_layout, + &self.joint_buffer, + &self.joint_prev_buffer, + self.morph.arena_view(), + ); + for page in &mut self.joint_extra_pages { + page.bind_group = joint_bind_group( + &self.device, + &self.joint_layout, + &page.buffer, + &page.prev_buffer, + self.morph.arena_view(), + ); + } + } + /// Pages in existence (1 until a frame needed more). For tests and stats. pub fn joint_page_count(&self) -> usize { 1 + self.joint_extra_pages.len() diff --git a/native/shared/src/renderer/layered_pbr_ssr.rs b/native/shared/src/renderer/layered_pbr_ssr.rs index 4abca43c..1bd49362 100644 --- a/native/shared/src/renderer/layered_pbr_ssr.rs +++ b/native/shared/src/renderer/layered_pbr_ssr.rs @@ -446,6 +446,12 @@ impl Renderer { 0, ) }; + let mesh_draw = self.morph.morph_vertex( + mesh_draw, + command.skinned, + command.joint_offset, + command.mesh_idx, + ); out.push(ImportedIridescenceDrawRef { uniforms: &self.model_uniform_bind_groups[command.uniform_slot], material, diff --git a/native/shared/src/renderer/mod.rs b/native/shared/src/renderer/mod.rs index d48a45bc..a6f638a0 100644 --- a/native/shared/src/renderer/mod.rs +++ b/native/shared/src/renderer/mod.rs @@ -127,6 +127,8 @@ mod texture_store; pub(crate) mod texture_streaming; mod tonemap_lut; pub use color_grade::write_neutral as write_color_grade_neutral; +mod morph_pass; +pub use morph_pass::MorphFrameStats; mod transmitted_shadows; mod transparent_gi; #[cfg(feature = "models3d")] @@ -568,6 +570,7 @@ pub struct Renderer { joint_bind_group: wgpu::BindGroup, /// Palette pages past the first 1024 joints (`joint_pages.rs`). joint_extra_pages: Vec, + morph: morph_pass::MorphPass, // False until the material system's per-view bind group has been // rebuilt with the LIVE env/BRDF/shadow resources. The group is @@ -2464,37 +2467,10 @@ impl Renderer { ..Default::default() }); - // Joint-matrix bind group layout for GPU skinning. Created here (ahead - // of its buffer/bind group below) because the shadow map's skinned - // caster pipeline needs this layout at construction time. - let joint_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor { - label: Some("joint_layout"), - entries: &[ - wgpu::BindGroupLayoutEntry { - binding: 0, - visibility: wgpu::ShaderStages::VERTEX, - ty: wgpu::BindingType::Buffer { - ty: wgpu::BufferBindingType::Uniform, - has_dynamic_offset: false, - min_binding_size: None, - }, - count: None, - }, - // PT-7 — previous frame's palette (same offsets). Only - // the scene VS reads it; the shadow shader ignores the - // binding, which wgpu permits. - wgpu::BindGroupLayoutEntry { - binding: 1, - visibility: wgpu::ShaderStages::VERTEX, - ty: wgpu::BindingType::Buffer { - ty: wgpu::BufferBindingType::Uniform, - has_dynamic_offset: false, - min_binding_size: None, - }, - count: None, - }, - ], - }); + // Joint bind group layout (palettes + morph arena, `joint_pages.rs`), + // ahead of the shadow map, whose skinned caster pipeline needs it. + let joint_layout = joint_pages::create_joint_layout(&device); + let morph = morph_pass::MorphPass::new(&device); // Shadow map needs to be created before the lighting bind // group since the bind group binds the shadow depth view. @@ -2725,20 +2701,13 @@ impl Renderer { contents: &joint_data, usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST, }); - let joint_bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor { - label: Some("joint_bg"), - layout: &joint_layout, - entries: &[ - wgpu::BindGroupEntry { - binding: 0, - resource: joint_buffer.as_entire_binding(), - }, - wgpu::BindGroupEntry { - binding: 1, - resource: joint_prev_buffer.as_entire_binding(), - }, - ], - }); + let joint_bind_group = joint_pages::joint_bind_group( + &device, + &joint_layout, + &joint_buffer, + &joint_prev_buffer, + morph.arena_view(), + ); // Initialize with identity matrices { let mut identity_data = vec![0u8; 65536]; @@ -8236,6 +8205,7 @@ impl Renderer { joint_layout, joint_bind_group, joint_extra_pages: Vec::new(), + morph, material_per_view_bg_live: false, texture_bind_group_layout, texture_bind_groups, @@ -13057,6 +13027,12 @@ impl Renderer { if cmd.mesh_idx < meshes.len() { let mesh = &meshes[cmd.mesh_idx]; let draw = self.gpu_driven.mesh_draw(&mesh.geometry, mesh.index_count); + let draw = self.morph.morph_vertex( + draw, + cmd.skinned, + cmd.joint_offset, + cmd.mesh_idx, + ); self.bind_joint_page(&mut pass, 3, cmd.joint_offset, &mut joint_page); pass.set_bind_group( 0, @@ -14550,6 +14526,7 @@ impl Renderer { .collect(); self.model_gpu_cache.insert(handle_bits, Some(gpu_meshes)); + self.register_model_morphs(handle_bits, &meshes); true } diff --git a/native/shared/src/renderer/model_draw.rs b/native/shared/src/renderer/model_draw.rs index 8e57b799..6eb4372a 100644 --- a/native/shared/src/renderer/model_draw.rs +++ b/native/shared/src/renderer/model_draw.rs @@ -77,6 +77,7 @@ impl Renderer { self.skin_unkeyed_previous_count = 0; self.skin_unkeyed_slot = 0; self.skin_prev_palettes.clear(); + self.morph.reset_history(); } #[cfg(not(target_arch = "wasm32"))] @@ -150,6 +151,7 @@ impl Renderer { } self.pending_skin_groups_prev.push(previous); self.pending_skin_groups.push(matrices.to_vec()); + self.morph.note_group(); } pub fn set_model_skin_scale(&mut self, scale: f32) { @@ -201,6 +203,7 @@ impl Renderer { self.skin_prev_palettes .insert(key, (self.skin_motion_epoch, scaled.clone())); self.pending_skin_groups.push(scaled); + self.morph.note_group(); } /// `set_joint_matrices_scaled` for a character carried by something that @@ -239,6 +242,7 @@ impl Renderer { self.skin_prev_palettes .insert(key, (self.skin_motion_epoch, placed.clone())); self.pending_skin_groups.push(placed); + self.morph.note_group(); } /// Pair an ordinary cached instance with the same submission slot from the @@ -757,6 +761,8 @@ impl Renderer { // with another model's pose. StagedSkin::Dropped => return, }; + // Morphed meshes of this instance: misc.w = 1 + arena texel (0 = none). + let morph_bases = self.morph_draw(handle_bits, joint_offset, mesh_count); // Model matrix places the rare rigid (weightless) verts; weighted // verts get their world placement from the joint matrices. @@ -819,7 +825,7 @@ impl Renderer { joint_pages::joint_offset_in_page(joint_offset), 1.0, 0.0, - 0.0, + morph_bases.get(mesh_idx).copied().unwrap_or(0.0), ], }, ); @@ -964,6 +970,8 @@ impl Renderer { /// buffer — the player's — rendering as a giant mangled blob glued to /// the player's position. pub(super) fn take_staged_skin_offset(&mut self) -> StagedSkin { + // The morph state staged with this pose (none when nothing is staged). + self.morph.pop_group(); if self.pending_skin_groups.is_empty() { return StagedSkin::Nothing; } diff --git a/native/shared/src/renderer/morph_pass.rs b/native/shared/src/renderer/morph_pass.rs new file mode 100644 index 00000000..0149fd12 --- /dev/null +++ b/native/shared/src/renderer/morph_pass.rs @@ -0,0 +1,1024 @@ +//! Morph targets on the GPU: the per-instance morph pass, and what the +//! draws read from it. `docs/morph-targets.md` is the overview. +//! +//! A skinned cached model keeps one bind-pose vertex buffer shared by every +//! instance. An instance whose morph weights are not all zero gets its OWN +//! vertex buffer per morphed mesh, which a compute pass rewrites each frame +//! it is drawn: bind pose + sum of weight x delta for position, normal and +//! tangent (normal and tangent renormalised), one thread per vertex reading +//! its own sparse entries (`morph_targets.rs`, re-laid lane-interleaved per +//! block of 64 vertices so a wave reads them coalesced). Untouched vertices are +//! copied once, when the buffer is made, and never again. +//! +//! That buffer then simply replaces the shared one as the draw's vertex +//! buffer in every pass (`morph_vertex()` at each cached-draw site) and as +//! the source of the ray scene's compute skin, so no vertex shader changes +//! for the CURRENT position: skinning, shadows, transmitted shadows, custom +//! passes, the visibility buffer and GI all see the morphed mesh. +//! +//! Motion vectors need the PREVIOUS position too. The pass knows last +//! frame's weights (kept per animation handle, as the joint palettes are), +//! so it also writes `previous - current` displacement of every vertex of +//! the mesh into one frame-wide texture, the "morph arena" (bound at +//! `@group(3) @binding(2)`, next to the joint palettes, in every joint bind +//! group). A morphed draw's uniform `misc.w` is `1 + its first texel`; the +//! scene vertex shader's skinned branch adds the displacement to the +//! position it feeds the previous palette, so TAA and TSR get the real +//! velocity of a moving lip. `misc.w = 0` (every other draw) reads nothing. +//! +//! Costs nothing for models without morphs or instances at zero: no buffer, +//! no job, no texel. The frame an instance's weights return to zero it is +//! morphed once more (its velocity is not zero that frame), then it draws +//! from the shared buffer again; its own buffer is freed after +//! `IDLE_FRAMES` frames unused. +//! +//! Without compute (the WebGL2 baseline tier) the same is done on the CPU: +//! the instance buffer and the arena are uploaded from CPU copies. + +use super::*; +use crate::morph_targets::{MorphEntry, MorphTargets}; +use std::collections::HashMap; +use std::sync::Arc; + +/// Texels per arena row (any texture limit allows 2048). +const ARENA_WIDTH: u32 = 2048; +/// Frames an instance buffer survives unused. +const IDLE_FRAMES: u64 = 240; +/// Uniform stride of a job's parameters. +const PARAMS_STRIDE: u64 = 256; +const WORKGROUP: u32 = 64; +const MAX_GROUPS_X: u32 = 65535; + +const MORPH_WGSL: &str = r#" +struct MorphParams { + vertex_count: u32, + arena_base: u32, + weights_offset: u32, + slot_count: u32, + full_copy: u32, + flags: u32, // bit 0 normals, bit 1 tangents + pos_scale: f32, + row_groups: u32, // workgroups in x +}; +@group(0) @binding(0) var p: MorphParams; +// Vertex3D as six vec4: [pos.xyz nrm.x] [nrm.yz col.rg] [col.ba uv] +// [joints] [weights] [tangent]. +@group(0) @binding(1) var src: array>; +@group(0) @binding(2) var dst: array>; +// Per block of 64 vertices: (first entry, entries per vertex). A block's +// entries are lane-interleaved: entry k of lane i is at first + k * 64 + i +// (padding slot 0xffffffff), so a wave reads them coalesced. +@group(0) @binding(3) var blocks: array>; +// One entry is three vec2: [slot, pos.xy] [pos.z|nrm.x, nrm.yz] [tan.xy, tan.z|0]. +@group(0) @binding(4) var entries: array>; +@group(0) @binding(5) var weights: array; +@group(0) @binding(6) var prev_disp: texture_storage_2d; + +@compute @workgroup_size(64) +fn cs_morph( + @builtin(global_invocation_id) gid: vec3, + @builtin(local_invocation_index) lane: u32, +) { + let v = gid.x + gid.y * p.row_groups * 64u; + if (v >= p.vertex_count) { + return; + } + let texel = p.arena_base + v; + let width = textureDimensions(prev_disp).x; + let tc = vec2(texel % width, texel / width); + let b = v * 6u; + let block = blocks[v / 64u]; + if (p.full_copy != 0u) { + for (var k = 0u; k < 6u; k = k + 1u) { + dst[b + k] = src[b + k]; + } + } + if (block.y == 0u) { + textureStore(prev_disp, tc, vec4(0.0)); + return; + } + var dp = vec3(0.0); + var dpp = vec3(0.0); + var dn = vec3(0.0); + var dt = vec3(0.0); + let tangents = (p.flags & 2u) != 0u; + for (var k = 0u; k < block.y; k = k + 1u) { + let o = (block.x + k * 64u + lane) * 3u; + let e0 = entries[o]; + let slot = e0.x; + if (slot >= p.slot_count) { + continue; + } + let w = weights[p.weights_offset + slot]; + let wp = weights[p.weights_offset + p.slot_count + slot]; + if (w == 0.0 && wp == 0.0) { + continue; + } + let e1 = entries[o + 1u]; + let a = unpack2x16float(e0.y); + let c = unpack2x16float(e1.x); + let d = unpack2x16float(e1.y); + let pos = vec3(a.x, a.y, c.x) * p.pos_scale; + dp = dp + w * pos; + dpp = dpp + wp * pos; + dn = dn + w * vec3(c.y, d.x, d.y); + if (tangents) { + let e2 = entries[o + 2u]; + let f = unpack2x16float(e2.x); + let g = unpack2x16float(e2.y); + dt = dt + w * vec3(f.x, f.y, g.x); + } + } + let s0 = src[b]; + let s1 = src[b + 1u]; + var o0 = vec4(s0.xyz + dp, s0.w); + if ((p.flags & 1u) != 0u) { + let sn = vec3(s0.w, s1.x, s1.y); + let n = sn + dn; + let l = length(n); + let nn = select(sn, n / l, l > 1e-12); + o0.w = nn.x; + dst[b + 1u] = vec4(nn.y, nn.z, s1.z, s1.w); + } + dst[b] = o0; + if (tangents) { + let st = src[b + 5u]; + if (dot(st.xyz, st.xyz) > 0.0) { + let t = st.xyz + dt; + let l = length(t); + dst[b + 5u] = vec4(select(st.xyz, t / l, l > 1e-12), st.w); + } + } + textureStore(prev_disp, tc, vec4(dpp - dp, 0.0)); +} +"#; + +/// One mesh's deltas on the GPU (shared by every instance). +pub(super) struct MorphMeshGpu { + targets: Arc, + /// `None` on the CPU path. Blocks and lane-interleaved entries + /// (`interleave_blocks`). + blocks: Option, + entries: Option, +} + +struct MorphInstance { + vertex: wgpu::Buffer, + initialized: bool, + last_frame: u64, + /// CPU path: the instance's current vertices. + cpu: Option>, +} + +#[derive(Clone, Copy, Debug)] +pub(super) struct StagedMorph { + /// The animation handle (keys the instance's own buffers). + key: u64, + weights_offset: u32, + slots: u32, +} + +struct Job { + key: (u64, u64, usize), + arena_base: u32, + staged: StagedMorph, +} + +/// What the morph pass did in the last frame (tests, stats, benches). +#[derive(Clone, Copy, Debug, Default, PartialEq)] +pub struct MorphFrameStats { + pub jobs: u32, + pub vertices: u32, + pub instances: u32, + pub arena_texels: u32, + pub gpu: bool, + /// GPU time of the morph pass in milliseconds, measured only while + /// `set_morph_gpu_timing(true)` (blocking; for benches), else 0. + pub gpu_ms: f64, +} + +pub(super) struct MorphPass { + meshes: HashMap>>, + instances: HashMap<(u64, u64, usize), MorphInstance>, + /// In lockstep with `pending_skin_groups`: the morph state staged with + /// each pose (`None` for a pose without morphs). + pending: Vec>, + /// The last staged pose has not had its weights yet. + pose_open: bool, + /// The morph state of the pose `take_staged_skin_offset` just popped. + current: Option, + /// Last weights per animation handle, with the frame they were staged. + prev: HashMap)>, + /// This frame's weights: per staged instance, current then previous. + weights: Vec, + jobs: Vec, + arena_cursor: u32, + /// Morphed vertex buffers by (absolute joint offset, mesh index): those + /// recorded for the coming frame, and those of the frame being drawn. + pending_overrides: HashMap<(u32, usize), wgpu::Buffer>, + overrides: HashMap<(u32, usize), wgpu::Buffer>, + arena: wgpu::Texture, + arena_view: wgpu::TextureView, + arena_rows: u32, + compute: bool, + pipeline: Option<(wgpu::ComputePipeline, wgpu::BindGroupLayout)>, + weights_buffer: Option<(wgpu::Buffer, u64)>, + params_buffer: Option<(wgpu::Buffer, u64)>, + cpu_arena: Vec<[f32; 4]>, + /// Timestamp queries around the pass (benches): set, resolve, readback. + timing: Option<(wgpu::QuerySet, wgpu::Buffer, wgpu::Buffer)>, + frame: u64, + stats: MorphFrameStats, +} + +fn create_arena( + device: &wgpu::Device, + rows: u32, + compute: bool, +) -> (wgpu::Texture, wgpu::TextureView) { + let mut usage = wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST; + if compute { + usage |= wgpu::TextureUsages::STORAGE_BINDING; + } + let texture = device.create_texture(&wgpu::TextureDescriptor { + label: Some("morph_prev_displacement"), + size: wgpu::Extent3d { + width: ARENA_WIDTH, + height: rows.max(1), + depth_or_array_layers: 1, + }, + mip_level_count: 1, + sample_count: 1, + dimension: wgpu::TextureDimension::D2, + format: wgpu::TextureFormat::Rgba32Float, + usage, + view_formats: &[], + }); + let view = texture.create_view(&wgpu::TextureViewDescriptor::default()); + (texture, view) +} + +/// Whether this device can run the morph compute pass. +fn device_has_compute(device: &wgpu::Device) -> bool { + let l = device.limits(); + l.max_compute_invocations_per_workgroup >= WORKGROUP + && l.max_compute_workgroup_size_x >= WORKGROUP + && l.max_storage_buffers_per_shader_stage >= 5 + && l.max_storage_textures_per_shader_stage >= 1 +} + +/// The GPU layout of a mesh's entries: per block of `WORKGROUP` vertices +/// (one workgroup), `(first entry, entries per vertex)`, and the block's +/// entries lane-interleaved and padded to its busiest vertex. Neighbouring +/// threads then read neighbouring entries. A block of untouched vertices +/// has none. Never empty (a storage binding may not be). +pub(super) fn interleave_blocks(targets: &MorphTargets) -> (Vec<[u32; 2]>, Vec) { + let n = targets.vertex_count as usize; + let lanes = WORKGROUP as usize; + let pad = MorphEntry { + slot: u32::MAX, + packed: [0; 5], + }; + let mut blocks = Vec::with_capacity(n.div_ceil(lanes).max(1)); + let mut entries = Vec::with_capacity(targets.entries.len()); + for first in (0..n).step_by(lanes) { + let last = (first + lanes).min(n); + let most = (first..last) + .map(|v| targets.vertex_entries(v).len()) + .max() + .unwrap_or(0); + blocks.push([entries.len() as u32, most as u32]); + for k in 0..most { + for lane in 0..lanes { + let v = first + lane; + let e = if v < last { + targets.vertex_entries(v).get(k).copied() + } else { + None + }; + entries.push(e.unwrap_or(pad)); + } + } + } + if blocks.is_empty() { + blocks.push([0, 0]); + } + if entries.is_empty() { + entries.push(pad); + } + (blocks, entries) +} + +impl MorphPass { + pub(super) fn new(device: &wgpu::Device) -> Self { + let compute = device_has_compute(device) && std::env::var_os("BLOOM_MORPH_CPU").is_none(); + let (arena, arena_view) = create_arena(device, 1, device_has_compute(device)); + Self { + meshes: HashMap::new(), + instances: HashMap::new(), + pending: Vec::new(), + pose_open: false, + current: None, + prev: HashMap::new(), + weights: Vec::new(), + jobs: Vec::new(), + arena_cursor: 0, + pending_overrides: HashMap::new(), + overrides: HashMap::new(), + arena, + arena_view, + arena_rows: 1, + compute, + pipeline: None, + weights_buffer: None, + params_buffer: None, + cpu_arena: Vec::new(), + timing: None, + frame: 1, + stats: MorphFrameStats::default(), + } + } + + /// The previous-position displacement texture, bound at group 3 + /// binding 2 of every joint bind group. + pub(super) fn arena_view(&self) -> &wgpu::TextureView { + &self.arena_view + } + + /// A pose was staged (`pending_skin_groups.push`): keep step with it. + #[inline] + pub(super) fn note_group(&mut self) { + self.pending.push(None); + self.pose_open = true; + } + + /// A pose was popped (`pending_skin_groups.remove(0)`): its morph state + /// becomes the current one, for the draw that popped it. + #[inline] + pub(super) fn pop_group(&mut self) { + self.current = if self.pending.is_empty() { + None + } else { + self.pending.remove(0) + }; + } + + pub(super) fn clear_pending(&mut self) { + self.pending.clear(); + self.pose_open = false; + self.current = None; + } + + pub(super) fn reset_history(&mut self) { + self.prev.clear(); + } + + /// The draw's vertex buffer: the morphed one of this instance's mesh if + /// it was morphed this frame, else `draw` as it is. + #[inline] + pub(super) fn morph_vertex<'a>( + &'a self, + mut draw: MeshDrawRef<'a>, + skinned: bool, + joint_offset: f32, + mesh_idx: usize, + ) -> MeshDrawRef<'a> { + if skinned && !self.overrides.is_empty() { + if let Some(vb) = self.vertex_buffer(joint_offset, mesh_idx) { + draw.vertex = vb; + } + } + draw + } + + /// The morphed vertex buffer of the draw at this joint offset and mesh. + #[inline] + pub(super) fn vertex_buffer( + &self, + joint_offset: f32, + mesh_idx: usize, + ) -> Option<&wgpu::Buffer> { + if self.overrides.is_empty() { + return None; + } + self.overrides + .get(&(joint_offset.max(0.0) as u32, mesh_idx)) + } + + pub(super) fn forget_model(&mut self, cache_handle: u64) { + self.meshes.remove(&cache_handle); + self.instances.retain(|k, _| k.1 != cache_handle); + } + + pub(super) fn stats(&self) -> MorphFrameStats { + self.stats + } +} + +impl Renderer { + /// Upload a just-cached model's morph deltas and grow its meshes' rest + /// bounds by what the targets can move (so an open jaw is never culled). + /// Only skinned models morph: weights travel with the pose. + #[cfg(feature = "models3d")] + pub(super) fn register_model_morphs( + &mut self, + handle: u64, + meshes: &[&crate::models::MeshData], + ) { + if meshes.iter().all(|m| m.morph.is_none()) { + return; + } + if !self.model_skinned.contains(&handle) { + static WARNED: std::sync::atomic::AtomicBool = + std::sync::atomic::AtomicBool::new(false); + if !WARNED.swap(true, std::sync::atomic::Ordering::Relaxed) { + log::warn!("bloom: a model with morph targets has no skin; morphs are applied to skinned models only (drawn through an animation instance)"); + } + return; + } + let compute = self.morph.compute; + let mut gpu = Vec::with_capacity(meshes.len()); + for (i, mesh) in meshes.iter().enumerate() { + let Some(targets) = mesh + .morph + .as_ref() + .filter(|t| t.vertex_count as usize == mesh.vertices.len()) + else { + gpu.push(None); + continue; + }; + if let Some(Some(cached)) = self.model_gpu_cache.get_mut(&handle) { + if let Some(c) = cached.get_mut(i) { + targets.grow_bounds(&mut c.local_min, &mut c.local_max); + } + } + let upload = |label, contents: &[u8]| { + self.device + .create_buffer_init(&wgpu::util::BufferInitDescriptor { + label: Some(label), + contents, + usage: wgpu::BufferUsages::STORAGE, + }) + }; + let (blocks, entries) = if compute { + let (blocks, entries) = interleave_blocks(targets); + ( + Some(upload("morph_blocks", bytemuck::cast_slice(&blocks))), + Some(upload("morph_entries", bytemuck::cast_slice(&entries))), + ) + } else { + (None, None) + }; + gpu.push(Some(MorphMeshGpu { + targets: targets.clone(), + blocks, + entries, + })); + } + self.morph.meshes.insert(handle, gpu); + } + + /// Stage an animation instance's morph weights with the pose just staged + /// by `set_joint_matrices_*` (call right after it; once). `key` is the + /// same animation handle that keys the joint palettes. Ignored when no + /// pose was just staged. + pub fn stage_morph_weights(&mut self, key: u64, weights: &[f32]) { + let m = &mut self.morph; + if !std::mem::replace(&mut m.pose_open, false) { + return; + } + if weights.is_empty() && !m.prev.contains_key(&key) { + return; + } + let frame = m.frame; + let nonzero = weights.iter().any(|w| *w != 0.0); + let prev = m + .prev + .get(&key) + .filter(|(f, _)| f.wrapping_add(1) == frame) + .map(|(_, w)| w.as_slice()); + let prev_nonzero = prev.is_some_and(|p| p.iter().any(|w| *w != 0.0)); + if nonzero || prev_nonzero { + let n = weights.len().max(prev.map_or(0, |p| p.len())); + let offset = m.weights.len(); + m.weights.extend_from_slice(weights); + m.weights.resize(offset + n, 0.0); + match prev { + Some(p) => m.weights.extend_from_slice(p), + // First frame seen: no motion of its own. + None => m.weights.extend_from_slice(weights), + } + m.weights.resize(offset + 2 * n, 0.0); + if let Some(last) = m.pending.last_mut() { + *last = Some(StagedMorph { + key, + weights_offset: offset as u32, + slots: n as u32, + }); + } + } + let entry = m.prev.entry(key).or_default(); + entry.0 = frame; + entry.1.clear(); + entry.1.extend_from_slice(weights); + } + + /// The draw of a skinned cached model with the pose just popped: if that + /// pose carries morph weights, give each morphed mesh its instance buffer + /// and arena range for this frame. Returns `misc.w` per mesh (0 = not + /// morphed). + pub(super) fn morph_draw( + &mut self, + handle: u64, + joint_offset: f32, + mesh_count: usize, + ) -> Vec { + let Some(staged) = self.morph.current.take() else { + return Vec::new(); + }; + let MorphPass { + meshes, + instances, + jobs, + arena_cursor, + pending_overrides, + frame, + .. + } = &mut self.morph; + let Some(gpu) = meshes.get(&handle) else { + return Vec::new(); + }; + let mut out = vec![0.0f32; mesh_count]; + for (i, mesh) in gpu.iter().enumerate().take(mesh_count) { + let Some(mesh) = mesh else { + continue; + }; + let vc = mesh.targets.vertex_count; + if (*arena_cursor as u64 + vc as u64) >= (1u64 << 24) { + // misc.w is an f32: past 16M texels the base is not exact. + break; + } + let key = (staged.key, handle, i); + let device = &self.device; + let instance = instances.entry(key).or_insert_with(|| MorphInstance { + vertex: device.create_buffer(&wgpu::BufferDescriptor { + label: Some("morph_instance_vb"), + size: (vc as u64 * std::mem::size_of::() as u64).max(4), + usage: wgpu::BufferUsages::VERTEX + | wgpu::BufferUsages::STORAGE + | wgpu::BufferUsages::COPY_DST, + mapped_at_creation: false, + }), + initialized: false, + last_frame: 0, + cpu: None, + }); + instance.last_frame = *frame; + let base = *arena_cursor; + *arena_cursor += vc; + pending_overrides.insert((joint_offset.max(0.0) as u32, i), instance.vertex.clone()); + jobs.push(Job { + key, + arena_base: base, + staged, + }); + out[i] = (base + 1) as f32; + } + out + } + + /// Run this frame's morph jobs (called where the joint palettes are + /// uploaded, before any pass that draws): GPU compute in its own submit, + /// or the CPU path. Hands the morphed buffers to the coming passes. + pub(super) fn encode_morph_pass(&mut self) { + let jobs = std::mem::take(&mut self.morph.jobs); + self.morph.overrides = std::mem::take(&mut self.morph.pending_overrides); + let frame = self.morph.frame; + self.morph.frame += 1; + if frame.is_multiple_of(64) { + self.morph + .instances + .retain(|_, inst| frame.saturating_sub(inst.last_frame) <= IDLE_FRAMES); + self.morph + .prev + .retain(|_, (f, _)| frame.saturating_sub(*f) <= 2); + } + let used = self.morph.arena_cursor; + self.morph.stats = MorphFrameStats { + jobs: jobs.len() as u32, + vertices: used, + instances: self.morph.instances.len() as u32, + arena_texels: self.morph.arena_rows * ARENA_WIDTH, + gpu: self.morph.compute, + gpu_ms: 0.0, + }; + if jobs.is_empty() { + self.morph.weights.clear(); + self.morph.arena_cursor = 0; + return; + } + let rows = used.div_ceil(ARENA_WIDTH).max(1); + if rows > self.morph.arena_rows { + let rows = rows.next_power_of_two(); + let (arena, view) = create_arena(&self.device, rows, device_has_compute(&self.device)); + self.morph.arena = arena; + self.morph.arena_view = view; + self.morph.arena_rows = rows; + self.rebuild_joint_bind_groups(); + self.morph.stats.arena_texels = rows * ARENA_WIDTH; + } + if self.morph.compute { + self.encode_morph_gpu(&jobs); + } else { + self.morph_cpu(&jobs, used); + } + self.morph.weights.clear(); + self.morph.arena_cursor = 0; + } + + fn ensure_morph_buffer( + device: &wgpu::Device, + slot: &mut Option<(wgpu::Buffer, u64)>, + bytes: u64, + usage: wgpu::BufferUsages, + label: &'static str, + ) { + if slot.as_ref().is_none_or(|(_, size)| *size < bytes) { + let size = bytes.next_power_of_two().max(256); + *slot = Some(( + device.create_buffer(&wgpu::BufferDescriptor { + label: Some(label), + size, + usage: usage | wgpu::BufferUsages::COPY_DST, + mapped_at_creation: false, + }), + size, + )); + } + } + + fn morph_pipeline(&mut self) { + if self.morph.pipeline.is_some() { + return; + } + let storage = |binding, read_only| wgpu::BindGroupLayoutEntry { + binding, + visibility: wgpu::ShaderStages::COMPUTE, + ty: wgpu::BindingType::Buffer { + ty: wgpu::BufferBindingType::Storage { read_only }, + has_dynamic_offset: false, + min_binding_size: None, + }, + count: None, + }; + let layout = self + .device + .create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor { + label: Some("morph_layout"), + entries: &[ + wgpu::BindGroupLayoutEntry { + binding: 0, + visibility: wgpu::ShaderStages::COMPUTE, + ty: wgpu::BindingType::Buffer { + ty: wgpu::BufferBindingType::Uniform, + has_dynamic_offset: false, + min_binding_size: None, + }, + count: None, + }, + storage(1, true), + storage(2, false), + storage(3, true), + storage(4, true), + storage(5, true), + wgpu::BindGroupLayoutEntry { + binding: 6, + visibility: wgpu::ShaderStages::COMPUTE, + ty: wgpu::BindingType::StorageTexture { + access: wgpu::StorageTextureAccess::WriteOnly, + format: wgpu::TextureFormat::Rgba32Float, + view_dimension: wgpu::TextureViewDimension::D2, + }, + count: None, + }, + ], + }); + let shader = self + .device + .create_shader_module(wgpu::ShaderModuleDescriptor { + label: Some("morph_shader"), + source: wgpu::ShaderSource::Wgsl(MORPH_WGSL.into()), + }); + let pl = self + .device + .create_pipeline_layout(&wgpu::PipelineLayoutDescriptor { + label: Some("morph_pl"), + bind_group_layouts: &[Some(&layout)], + immediate_size: 0, + }); + let pipeline = self + .device + .create_compute_pipeline(&wgpu::ComputePipelineDescriptor { + label: Some("morph_pipeline"), + layout: Some(&pl), + module: &shader, + entry_point: Some("cs_morph"), + compilation_options: Default::default(), + cache: None, + }); + self.created_pipelines(1); + self.morph.pipeline = Some((pipeline, layout)); + } + + fn encode_morph_gpu(&mut self, jobs: &[Job]) { + self.morph_pipeline(); + let weights_bytes = (self.morph.weights.len().max(1) * 4) as u64; + Self::ensure_morph_buffer( + &self.device, + &mut self.morph.weights_buffer, + weights_bytes, + wgpu::BufferUsages::STORAGE, + "morph_weights", + ); + Self::ensure_morph_buffer( + &self.device, + &mut self.morph.params_buffer, + jobs.len() as u64 * PARAMS_STRIDE, + wgpu::BufferUsages::UNIFORM, + "morph_params", + ); + if !self.morph.weights.is_empty() { + self.queue.write_buffer( + &self.morph.weights_buffer.as_ref().unwrap().0, + 0, + bytemuck::cast_slice(&self.morph.weights), + ); + } + let mut params = vec![0u8; jobs.len() * PARAMS_STRIDE as usize]; + let mut dispatches: Vec<(wgpu::BindGroup, u32, u32)> = Vec::with_capacity(jobs.len()); + for (j, job) in jobs.iter().enumerate() { + let (_, cache, mesh_idx) = job.key; + let Some(mesh) = self + .morph + .meshes + .get(&cache) + .and_then(|m| m.get(mesh_idx)) + .and_then(|m| m.as_ref()) + else { + continue; + }; + let Some(src) = self + .model_gpu_cache + .get(&cache) + .and_then(|m| m.as_ref()) + .and_then(|m| m.get(mesh_idx)) + .and_then(|m| match &m.geometry { + gpu_driven::MeshGeometry::Dedicated { vertex, .. } => Some(vertex), + gpu_driven::MeshGeometry::Shared(_) => None, + }) + else { + continue; + }; + let Some(instance) = self.morph.instances.get_mut(&job.key) else { + continue; + }; + let t = &mesh.targets; + let groups = t.vertex_count.div_ceil(WORKGROUP).max(1); + let gx = groups.min(MAX_GROUPS_X); + let gy = groups.div_ceil(gx); + let flags = (t.has_normals as u32) | ((t.has_tangents as u32) << 1); + let words: [u32; 8] = [ + t.vertex_count, + job.arena_base, + job.staged.weights_offset, + job.staged.slots, + (!instance.initialized) as u32, + flags, + t.pos_scale.to_bits(), + gx, + ]; + instance.initialized = true; + let at = j * PARAMS_STRIDE as usize; + params[at..at + 32].copy_from_slice(bytemuck::cast_slice(&words)); + let (layout, weights, params_buffer) = ( + &self.morph.pipeline.as_ref().unwrap().1, + &self.morph.weights_buffer.as_ref().unwrap().0, + &self.morph.params_buffer.as_ref().unwrap().0, + ); + let bg = self.device.create_bind_group(&wgpu::BindGroupDescriptor { + label: Some("morph_bg"), + layout, + entries: &[ + wgpu::BindGroupEntry { + binding: 0, + resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding { + buffer: params_buffer, + offset: at as u64, + size: std::num::NonZeroU64::new(32), + }), + }, + wgpu::BindGroupEntry { + binding: 1, + resource: src.as_entire_binding(), + }, + wgpu::BindGroupEntry { + binding: 2, + resource: instance.vertex.as_entire_binding(), + }, + wgpu::BindGroupEntry { + binding: 3, + resource: mesh.blocks.as_ref().unwrap().as_entire_binding(), + }, + wgpu::BindGroupEntry { + binding: 4, + resource: mesh.entries.as_ref().unwrap().as_entire_binding(), + }, + wgpu::BindGroupEntry { + binding: 5, + resource: weights.as_entire_binding(), + }, + wgpu::BindGroupEntry { + binding: 6, + resource: wgpu::BindingResource::TextureView(&self.morph.arena_view), + }, + ], + }); + dispatches.push((bg, gx, gy)); + } + self.queue + .write_buffer(&self.morph.params_buffer.as_ref().unwrap().0, 0, ¶ms); + let mut encoder = self + .device + .create_command_encoder(&wgpu::CommandEncoderDescriptor { + label: Some("morph_encoder"), + }); + { + let timestamp_writes = + self.morph + .timing + .as_ref() + .map(|(set, _, _)| wgpu::ComputePassTimestampWrites { + query_set: set, + beginning_of_pass_write_index: Some(0), + end_of_pass_write_index: Some(1), + }); + let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor { + label: Some("morph"), + timestamp_writes, + }); + pass.set_pipeline(&self.morph.pipeline.as_ref().unwrap().0); + for (bg, gx, gy) in &dispatches { + pass.set_bind_group(0, bg, &[]); + pass.dispatch_workgroups(*gx, *gy, 1); + } + } + if let Some((set, resolve, readback)) = self.morph.timing.as_ref() { + encoder.resolve_query_set(set, 0..2, resolve, 0); + encoder.copy_buffer_to_buffer(resolve, 0, readback, 0, 16); + } + self.queue.submit(std::iter::once(encoder.finish())); + if let Some((_, _, readback)) = self.morph.timing.as_ref() { + let slice = readback.slice(..); + let (tx, rx) = std::sync::mpsc::channel(); + slice.map_async(wgpu::MapMode::Read, move |r| { + let _ = tx.send(r); + }); + let _ = self.device.poll(wgpu::PollType::Wait { + submission_index: None, + timeout: None, + }); + if let Ok(Ok(())) = rx.recv() { + let ticks: [u64; 2] = { + let data = slice.get_mapped_range(); + bytemuck::pod_read_unaligned(&data[..16]) + }; + readback.unmap(); + let period = self.queue.get_timestamp_period() as f64; + self.morph.stats.gpu_ms = ticks[1].saturating_sub(ticks[0]) as f64 * period / 1e6; + } + } + } + + /// The same as the compute pass, on the CPU (no compute on the device). + fn morph_cpu(&mut self, jobs: &[Job], used: u32) { + let mut arena = std::mem::take(&mut self.morph.cpu_arena); + arena.clear(); + arena.resize(used as usize, [0.0; 4]); + for job in jobs { + let (_, cache, mesh_idx) = job.key; + let Some(mesh) = self + .morph + .meshes + .get(&cache) + .and_then(|m| m.get(mesh_idx)) + .and_then(|m| m.as_ref()) + else { + continue; + }; + let Some(base) = self + .model_gpu_cache + .get(&cache) + .and_then(|m| m.as_ref()) + .and_then(|m| m.get(mesh_idx)) + .and_then(|m| m.cpu_vertices.as_ref()) + else { + continue; + }; + let Some(instance) = self.morph.instances.get_mut(&job.key) else { + continue; + }; + let t = &mesh.targets; + if base.len() != t.vertex_count as usize { + continue; + } + let at = job.staged.weights_offset as usize; + let n = job.staged.slots as usize; + let cur = &self.morph.weights[at..at + n]; + let prev = &self.morph.weights[at + n..at + 2 * n]; + let out = instance.cpu.get_or_insert_with(|| base.clone()); + for v in 0..base.len() { + if t.ranges[v] == t.ranges[v + 1] { + continue; + } + out[v] = t.morph_vertex(&base[v], v, cur); + let pc = t.position_offset(v, prev); + let cc = t.position_offset(v, cur); + arena[job.arena_base as usize + v] = + [pc[0] - cc[0], pc[1] - cc[1], pc[2] - cc[2], 0.0]; + } + instance.initialized = true; + self.queue + .write_buffer(&instance.vertex, 0, bytemuck::cast_slice(out)); + } + let rows = used.div_ceil(ARENA_WIDTH); + arena.resize((rows * ARENA_WIDTH) as usize, [0.0; 4]); + self.queue.write_texture( + wgpu::TexelCopyTextureInfo { + texture: &self.morph.arena, + mip_level: 0, + origin: wgpu::Origin3d::ZERO, + aspect: wgpu::TextureAspect::All, + }, + bytemuck::cast_slice(&arena), + wgpu::TexelCopyBufferLayout { + offset: 0, + bytes_per_row: Some(ARENA_WIDTH * 16), + rows_per_image: Some(rows), + }, + wgpu::Extent3d { + width: ARENA_WIDTH, + height: rows, + depth_or_array_layers: 1, + }, + ); + self.morph.cpu_arena = arena; + } + + /// What the morph pass did last frame. + pub fn morph_frame_stats(&self) -> MorphFrameStats { + self.morph.stats() + } + + /// Measure the morph pass's GPU time into `morph_frame_stats().gpu_ms` + /// (timestamp queries, read back with a blocking wait each frame: for + /// benches only). Returns false when the device has no timestamps. + pub fn set_morph_gpu_timing(&mut self, on: bool) -> bool { + if !on + || !self + .device + .features() + .contains(wgpu::Features::TIMESTAMP_QUERY) + { + self.morph.timing = None; + return false; + } + if self.morph.timing.is_none() { + let set = self.device.create_query_set(&wgpu::QuerySetDescriptor { + label: Some("morph_timing"), + ty: wgpu::QueryType::Timestamp, + count: 2, + }); + let buffer = |usage| { + self.device.create_buffer(&wgpu::BufferDescriptor { + label: Some("morph_timing"), + size: 16, + usage, + mapped_at_creation: false, + }) + }; + let resolve = buffer(wgpu::BufferUsages::QUERY_RESOLVE | wgpu::BufferUsages::COPY_SRC); + let readback = buffer(wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST); + self.morph.timing = Some((set, resolve, readback)); + } + true + } + + /// Force the CPU path (the one used without compute) on a device that + /// has compute, or go back to the GPU pass. For tests and comparison; + /// a device without compute stays on the CPU. Returns whether the GPU + /// pass is now used. + pub fn set_morph_cpu_fallback(&mut self, cpu: bool) -> bool { + self.morph.compute = !cpu && device_has_compute(&self.device); + self.morph.compute + } +} diff --git a/native/shared/src/renderer/pt_dynamic_skin.rs b/native/shared/src/renderer/pt_dynamic_skin.rs index 622741c1..849553fb 100644 --- a/native/shared/src/renderer/pt_dynamic_skin.rs +++ b/native/shared/src/renderer/pt_dynamic_skin.rs @@ -227,6 +227,11 @@ impl Renderer { }, _ => continue, }; + // A morphed instance skins from its own morphed vertices. + let src_vb = self + .morph + .vertex_buffer(w.joint_offset, w.mesh_idx) + .unwrap_or(src_vb); bind_groups.push( self.device.create_bind_group(&wgpu::BindGroupDescriptor { label: Some("pt_skin_bg"), diff --git a/native/shared/src/renderer/scene_pass.rs b/native/shared/src/renderer/scene_pass.rs index cc10e669..f683feb2 100644 --- a/native/shared/src/renderer/scene_pass.rs +++ b/native/shared/src/renderer/scene_pass.rs @@ -260,6 +260,12 @@ impl Renderer { } let draw = self.gpu_driven.mesh_draw(&mesh.geometry, mesh.index_count); + let draw = self.morph.morph_vertex( + draw, + cmd.skinned, + cmd.joint_offset, + cmd.mesh_idx, + ); self.bind_joint_page( &mut pass, 3, @@ -688,6 +694,12 @@ impl Renderer { 0, ) }; + let draw = self.morph.morph_vertex( + draw, + cmd.skinned, + cmd.joint_offset, + cmd.mesh_idx, + ); self.bind_joint_page( &mut pass, 3, @@ -932,6 +944,12 @@ impl Renderer { 0, ) }; + let mesh_draw = self.morph.morph_vertex( + mesh_draw, + command.skinned, + command.joint_offset, + command.mesh_idx, + ); draws.push(ImportedRefractiveDrawRef { view_depth: pivot[3], stable_id, diff --git a/native/shared/src/renderer/shaders/core.rs b/native/shared/src/renderer/shaders/core.rs index 17d94960..efcd59c7 100644 --- a/native/shared/src/renderer/shaders/core.rs +++ b/native/shared/src/renderer/shaders/core.rs @@ -17,7 +17,9 @@ struct Uniforms3D { prev_mvp: mat4x4, model_tint: vec4, // x = joint-buffer offset for this draw, y = 1.0 for skinned cached - // draws (vs_main_scene then skins in the VS), zw unused. + // draws (vs_main_scene then skins in the VS). Skinned draws: w = 1 + + // the first morph-arena texel of a morphed draw (0 = not morphed). + // Static draws: z = foliage amount. misc: vec4, }; @@ -73,6 +75,8 @@ fn material_uv_delta(delta: vec2, row_0: vec4, row_1: vec4) -> ve } struct VertexInputScene { + // Morphed draws read their previous-position texel by vertex. + @builtin(vertex_index) vertex_index: u32, @location(0) position: vec3, @location(1) normal: vec3, @location(2) color: vec4, @@ -128,6 +132,9 @@ struct VertexOutputScene { // reconstruct last frame's world position from it, giving skeletal // motion a REAL velocity (it was exactly zero before). @group(3) @binding(1) var joints_prev: JointMatrices; +// Morph targets: per vertex, last frame's morphed position minus this +// frame's, for morphed skinned draws (renderer/morph_pass.rs). +@group(3) @binding(2) var morph_prev_disp: texture_2d; const PI: f32 = 3.14159265; @@ -186,6 +193,15 @@ fn vs_main_scene(in: VertexInputScene) -> VertexOutputScene { var nrm4: vec4; var tan4: vec4; let pos4l = vec4(in.position, 1.0); + // A morphed vertex was elsewhere last frame: the morph pass wrote + // the displacement, so its velocity includes the morph's motion. + var prev_pos4l = pos4l; + if (u.misc.w > 0.5) { + let morph_texel = u32(u.misc.w) - 1u + in.vertex_index; + let morph_width = textureDimensions(morph_prev_disp).x; + let morph_at = vec2(morph_texel % morph_width, morph_texel / morph_width); + prev_pos4l = vec4(in.position + textureLoad(morph_prev_disp, morph_at, 0).xyz, 1.0); + } let nrm4l = vec4(in.normal, 0.0); let tan4l = vec4(in.tangent.xyz, 0.0); if (total_weight > 0.01) { @@ -200,10 +216,10 @@ fn vs_main_scene(in: VertexInputScene) -> VertexOutputScene { // PT-7 — where this vertex WAS: previous palette, same // slots. Feeds the velocity MRT so TAA/TSR and the path // tracer can reproject skeletal motion. - prev_world4 = joints_prev.matrices[j0] * pos4l * in.weights.x - + joints_prev.matrices[j1] * pos4l * in.weights.y - + joints_prev.matrices[j2] * pos4l * in.weights.z - + joints_prev.matrices[j3] * pos4l * in.weights.w; + prev_world4 = joints_prev.matrices[j0] * prev_pos4l * in.weights.x + + joints_prev.matrices[j1] * prev_pos4l * in.weights.y + + joints_prev.matrices[j2] * prev_pos4l * in.weights.z + + joints_prev.matrices[j3] * prev_pos4l * in.weights.w; nrm4 = joints.matrices[j0] * nrm4l * in.weights.x + joints.matrices[j1] * nrm4l * in.weights.y + joints.matrices[j2] * nrm4l * in.weights.z @@ -214,7 +230,7 @@ fn vs_main_scene(in: VertexInputScene) -> VertexOutputScene { + joints.matrices[j3] * tan4l * in.weights.w; } else { world4 = u.model * pos4l; - prev_world4 = world4; + prev_world4 = u.model * prev_pos4l; nrm4 = u.model * nrm4l; tan4 = u.model * tan4l; } diff --git a/native/shared/src/renderer/shadow_pass.rs b/native/shared/src/renderer/shadow_pass.rs index b69bb6bf..b51b083b 100644 --- a/native/shared/src/renderer/shadow_pass.rs +++ b/native/shared/src/renderer/shadow_pass.rs @@ -430,6 +430,12 @@ impl Renderer { continue; } let draw = self.gpu_driven.mesh_draw(&mesh.geometry, mesh.index_count); + let draw = self.morph.morph_vertex( + draw, + cmd.skinned, + cmd.joint_offset, + cmd.mesh_idx, + ); let vb_idx = shadow_vbs.len(); shadow_vbs.push(draw.vertex); shadow_ibs.push(draw.index); diff --git a/native/shared/src/renderer/sorted_transparency.rs b/native/shared/src/renderer/sorted_transparency.rs index 64881d11..3d087767 100644 --- a/native/shared/src/renderer/sorted_transparency.rs +++ b/native/shared/src/renderer/sorted_transparency.rs @@ -222,6 +222,12 @@ impl Renderer { 0, ) }; + let mesh_draw = self.morph.morph_vertex( + mesh_draw, + command.skinned, + command.joint_offset, + command.mesh_idx, + ); draws.push(ImportedTransparentDrawRef { view_depth: pivot[3], stable_id, diff --git a/native/shared/src/renderer/texture_store.rs b/native/shared/src/renderer/texture_store.rs index 9392580c..f5247f06 100644 --- a/native/shared/src/renderer/texture_store.rs +++ b/native/shared/src/renderer/texture_store.rs @@ -613,6 +613,7 @@ impl Renderer { /// the buffers leak — and a future model whose handle reuses the slot /// would render the stale cached geometry. pub fn evict_model_cache(&mut self, handle_bits: u64) { + self.morph.forget_model(handle_bits); if let Some(Some(meshes)) = self.model_gpu_cache.remove(&handle_bits) { let mut seen_slices = std::collections::HashSet::new(); let shared_slices: Vec<_> = meshes diff --git a/native/shared/src/renderer/transmitted_shadows.rs b/native/shared/src/renderer/transmitted_shadows.rs index 65de57a4..6256417b 100644 --- a/native/shared/src/renderer/transmitted_shadows.rs +++ b/native/shared/src/renderer/transmitted_shadows.rs @@ -1181,6 +1181,12 @@ impl Renderer { 0, ) }; + let geometry = self.morph.morph_vertex( + geometry, + command.skinned, + command.joint_offset, + command.mesh_idx, + ); let (bounds_min, bounds_max) = command .bounds_override .unwrap_or_else(|| transform_aabb(&command.model, mesh.local_min, mesh.local_max)); diff --git a/native/shared/src/scene/shared_mesh.rs b/native/shared/src/scene/shared_mesh.rs index c3e48c17..2ef94ca4 100644 --- a/native/shared/src/scene/shared_mesh.rs +++ b/native/shared/src/scene/shared_mesh.rs @@ -124,6 +124,7 @@ mod tests { double_sided: false, transmission: crate::models::MaterialTransmission::default(), layered_pbr: crate::models::MaterialLayeredPbr::default(), + morph: None, }) } diff --git a/native/shared/tests/golden/morph_targets_w0.png b/native/shared/tests/golden/morph_targets_w0.png new file mode 100644 index 00000000..068d247e Binary files /dev/null and b/native/shared/tests/golden/morph_targets_w0.png differ diff --git a/native/shared/tests/golden/morph_targets_w1.png b/native/shared/tests/golden/morph_targets_w1.png new file mode 100644 index 00000000..836fcb84 Binary files /dev/null and b/native/shared/tests/golden/morph_targets_w1.png differ diff --git a/native/shared/tests/golden_render.rs b/native/shared/tests/golden_render.rs index 6fd0cc4d..4c41bb9c 100644 --- a/native/shared/tests/golden_render.rs +++ b/native/shared/tests/golden_render.rs @@ -38,6 +38,8 @@ mod layered_pbr_parity; mod lighting_upload; #[path = "golden_render/local_light_shadows.rs"] mod local_light_shadows; +#[path = "golden_render/morph_targets.rs"] +mod morph_targets; #[path = "golden_render/motion_producer_audit.rs"] mod motion_producer_audit; #[path = "golden_render/quality_presets.rs"] @@ -703,6 +705,7 @@ fn gltf_blend_is_fractional_and_not_cutout_or_opaque() { double_sided: false, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }; const OPAQUE_HANDLE: u64 = 0xA1FA_0001; const BLEND_HANDLE: u64 = 0xA1FA_0002; @@ -835,6 +838,7 @@ fn mask_coverage_mips_preserve_subpixel_silhouette_area() { double_sided: true, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }; const ORDINARY_HANDLE: u64 = 0xA1FA_C001; const COVERAGE_HANDLE: u64 = 0xA1FA_C002; @@ -973,6 +977,7 @@ fn gltf_transmission_uses_physical_retained_and_cached_paths() { double_sided: false, transmission, layered_pbr: Default::default(), + morph: None, }] )); let (_, _, cached) = render(&mut eng, 2, |eng| { @@ -1090,6 +1095,7 @@ fn physical_texcoord_1_matches_between_retained_cached_shadow_and_reactive_paths double_sided: false, transmission, layered_pbr: Default::default(), + morph: None, }; assert!(eng .renderer diff --git a/native/shared/tests/golden_render/fractional_dynamic.rs b/native/shared/tests/golden_render/fractional_dynamic.rs index 51d0fa47..2c1a791f 100644 --- a/native/shared/tests/golden_render/fractional_dynamic.rs +++ b/native/shared/tests/golden_render/fractional_dynamic.rs @@ -348,6 +348,7 @@ fn fractional_skinned_motion_tracks_native_and_fresh_recovery() { double_sided: false, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }] )); assert!(eng.renderer.is_model_skinned(HANDLE)); @@ -478,6 +479,7 @@ fn fractional_alpha_tested_motion_tracks_native_and_fresh_recovery() { double_sided: true, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }] )); @@ -814,6 +816,7 @@ fn fractional_procedural_foliage_tracks_native_at_fixed_time() { double_sided: true, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }] )); eng.renderer.set_wind(1.0, 0.3, 0.55, 1.35); diff --git a/native/shared/tests/golden_render/joint_pages.rs b/native/shared/tests/golden_render/joint_pages.rs index cca1c00e..cda74d86 100644 --- a/native/shared/tests/golden_render/joint_pages.rs +++ b/native/shared/tests/golden_render/joint_pages.rs @@ -136,6 +136,7 @@ fn cache_square(eng: &mut EngineState, handle: u64, joints: usize, half_size: f3 double_sided: true, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }] )); assert!(eng.renderer.is_model_skinned(handle)); diff --git a/native/shared/tests/golden_render/morph_targets.rs b/native/shared/tests/golden_render/morph_targets.rs new file mode 100644 index 00000000..74ffd4ac --- /dev/null +++ b/native/shared/tests/golden_render/morph_targets.rs @@ -0,0 +1,405 @@ +//! Morph targets: a morphed skinned mesh at weights 0 and 1 (golden), the +//! CPU path against the GPU pass, culling bounds that hold every pose, the +//! cost of an instance at zero, and motion vectors of a morph alone. + +use super::temporal_history::{configure_taa_motion_corpus, evaluate_motion_recovery}; +#[allow(unused_imports)] +use super::*; +use bloom_shared::morph_targets::{MorphTargets, MorphTargetsBuilder}; +use std::sync::Arc; + +const IDENTITY: [[f32; 4]; 4] = [ + [1.0, 0.0, 0.0, 0.0], + [0.0, 1.0, 0.0, 0.0], + [0.0, 0.0, 1.0, 0.0], + [0.0, 0.0, 0.0, 1.0], +]; +const GRID: usize = 24; + +fn mesh(vertices: Vec, indices: Vec, morph: Option>) -> MeshData { + MeshData { + vertices, + secondary_tex_coords: None, + indices, + texture_idx: None, + normal_texture_idx: None, + metallic_roughness_texture_idx: None, + specular_glossiness_factor: None, + emissive_texture_idx: None, + occlusion_texture_idx: None, + metallic_factor: 0.0, + roughness_factor: 0.55, + emissive_factor: [0.0; 3], + alpha_mode: MaterialAlphaMode::Opaque, + alpha_cutoff: 0.0, + alpha_coverage_mips: false, + double_sided: true, + transmission: Default::default(), + layered_pbr: Default::default(), + morph, + } +} + +/// A skinned 2 x 2 m sheet facing the camera (GRID x GRID quads), and two +/// targets: "bulge" pushes a dome out of its middle (with the dome's normal +/// deltas), "shift" slides its top band sideways. +fn sheet() -> (Vec, Vec, Arc) { + let n = GRID + 1; + let mut vertices = Vec::with_capacity(n * n); + for j in 0..n { + for i in 0..n { + let x = i as f32 / GRID as f32 * 2.0 - 1.0; + let y = j as f32 / GRID as f32 * 2.0; + vertices.push(Vertex3D { + position: [x, y, 0.0], + normal: [0.0, 0.0, 1.0], + color: [0.92, 0.55, 0.32, 1.0], + uv: [0.0; 2], + joints: [0.0; 4], + weights: [1.0, 0.0, 0.0, 0.0], + tangent: [1.0, 0.0, 0.0, 1.0], + }); + } + } + let mut indices = Vec::new(); + for j in 0..GRID { + for i in 0..GRID { + let a = (j * n + i) as u32; + let b = a + 1; + let c = a + n as u32; + let d = c + 1; + indices.extend_from_slice(&[a, b, d, a, d, c]); + } + } + let mut bulge_p = vec![[0.0f32; 3]; n * n]; + let mut bulge_n = vec![[0.0f32; 3]; n * n]; + let mut shift = vec![[0.0f32; 3]; n * n]; + for (k, v) in vertices.iter().enumerate() { + let (x, y) = (v.position[0], v.position[1] - 1.0); + let r2 = (x * x + y * y) / 0.36; + if r2 < 1.0 { + let h = 0.55 * (1.0 - r2).powi(2); + // dh/dx, dh/dy of h = 0.55 (1 - r2)^2 + let dhdx = 0.55 * 2.0 * (1.0 - r2) * (-2.0 * x / 0.36); + let dhdy = 0.55 * 2.0 * (1.0 - r2) * (-2.0 * y / 0.36); + let nrm = [-dhdx, -dhdy, 1.0]; + let l = (nrm[0] * nrm[0] + nrm[1] * nrm[1] + 1.0).sqrt(); + bulge_p[k] = [0.0, 0.0, h]; + bulge_n[k] = [nrm[0] / l, nrm[1] / l, 1.0 / l - 1.0]; + } + if v.position[1] > 1.5 { + shift[k] = [0.35 * (v.position[1] - 1.5) * 2.0, 0.0, 0.0]; + } + } + let mut b = MorphTargetsBuilder::new(n * n); + b.add_target(0, Some(&bulge_p), Some(&bulge_n), None, |_, d| d); + b.add_target(1, Some(&shift), None, None, |_, d| d); + let names = Arc::new(vec!["bulge".to_string(), "shift".to_string()]); + let morph = Arc::new(b.build(names).expect("targets move vertices")); + (vertices, indices, morph) +} + +fn scene(eng: &mut EngineState) { + let r = &mut eng.renderer; + r.set_clear_color(18.0, 22.0, 30.0, 255.0); + r.begin_mode_3d(1.6, 1.6, 4.4, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0, 42.0, 0.0); + r.add_directional_light(-0.5, -0.6, -0.8, 1.0, 0.96, 0.9, 2.6); + r.draw_plane(0.0, 0.0, 0.0, 8.0, 8.0, 40.0, 44.0, 52.0, 255.0); +} + +fn draw_morphed(eng: &mut EngineState, handle: u64, key: u64, weights: &[f32], x: f32) { + eng.renderer + .set_joint_matrices_scaled(key, &[IDENTITY], 1.0, [x, 0.0, 0.0], 0.0, 1.0); + eng.renderer.stage_morph_weights(key, weights); + eng.renderer + .draw_model_cached_skinned(handle, [0.0; 3], 1.0, [1.0; 4]); +} + +fn differing_pixels(a: &[u8], b: &[u8]) -> usize { + a.chunks_exact(4) + .zip(b.chunks_exact(4)) + .filter(|(p, q)| (0..3).any(|c| (p[c] as i32 - q[c] as i32).abs() > 24)) + .count() +} + +#[test] +fn morphed_skinned_mesh_at_zero_and_one_and_the_cpu_path_agrees() { + const HANDLE: u64 = 0x3044_0001; + const PLAIN: u64 = 0x3044_0002; + const KEY: u64 = 0x3044_1001; + let Some(mut eng) = try_engine() else { + eprintln!("skip: no GPU adapter"); + return; + }; + let (vertices, indices, morph) = sheet(); + assert!(eng.renderer.cache_model_if_static( + HANDLE, + &[mesh(vertices.clone(), indices.clone(), Some(morph))] + )); + assert!(eng + .renderer + .cache_model_if_static(PLAIN, &[mesh(vertices, indices, None)])); + + let shot = |eng: &mut EngineState, handle: u64, w: &[f32]| { + render(eng, 3, |eng| { + scene(eng); + draw_morphed(eng, handle, KEY, w, 0.0); + }) + }; + let (w, h, rest) = shot(&mut eng, HANDLE, &[0.0, 0.0]); + // At zero (after the frame that returns to zero) nothing is morphed. + assert_eq!(eng.renderer.morph_frame_stats().jobs, 0); + let (_, _, plain) = shot(&mut eng, PLAIN, &[0.0, 0.0]); + assert_eq!( + differing_pixels(&rest, &plain), + 0, + "weights 0 must draw the bind pose exactly" + ); + compare_or_update("morph_targets_w0", w, h, &rest); + + let (_, _, open) = shot(&mut eng, HANDLE, &[1.0, 1.0]); + let stats = eng.renderer.morph_frame_stats(); + assert_eq!(stats.jobs, 1, "{stats:?}"); + assert!(stats.vertices as usize >= (GRID + 1) * (GRID + 1)); + let moved = differing_pixels(&rest, &open); + eprintln!("morph: {moved} pixels differ between weights 0 and 1 ({stats:?})"); + assert!(moved > 800, "the morph did not change the picture: {moved}"); + compare_or_update("morph_targets_w1", w, h, &open); + + // The CPU path (WebGL2 tier) draws the same. + if eng.renderer.morph_frame_stats().gpu { + eng.renderer.set_morph_cpu_fallback(true); + let (_, _, cpu) = shot(&mut eng, HANDLE, &[1.0, 1.0]); + assert!(!eng.renderer.morph_frame_stats().gpu); + let metrics = calculate_diff_metrics(&open, &cpu, w, h); + assert!( + metrics.mean_rgb < 0.5 && metrics.outlier_pixel_fraction < 0.001, + "CPU morph differs from the GPU pass: {metrics:?}" + ); + eng.renderer.set_morph_cpu_fallback(false); + } + + // Back to zero: the instance falls back to the shared buffer. + let (_, _, back) = shot(&mut eng, HANDLE, &[0.0, 0.0]); + assert_eq!(differing_pixels(&rest, &back), 0); + assert_eq!(eng.renderer.morph_frame_stats().jobs, 0); +} + +#[test] +fn bounds_hold_every_pose_a_morph_can_reach() { + const HANDLE: u64 = 0x3044_0003; + const KEY: u64 = 0x3044_1003; + let Some(mut eng) = try_engine() else { + eprintln!("skip: no GPU adapter"); + return; + }; + // A cube far left of the view; its one target slides it into the + // middle. Culling by the rest bounds would drop it. + let (mut vertices, indices) = cube_verts(0.45, [0.2, 0.85, 0.35, 1.0]); + for v in &mut vertices { + v.position[0] -= 9.0; + v.position[1] += 0.8; + v.weights = [1.0, 0.0, 0.0, 0.0]; + } + let slide = vec![[9.0f32, 0.0, 0.0]; vertices.len()]; + let mut b = MorphTargetsBuilder::new(vertices.len()); + b.add_target(0, Some(&slide), None, None, |_, d| d); + let morph = Arc::new(b.build(Arc::new(vec!["slide".into()])).unwrap()); + assert!(eng + .renderer + .cache_model_if_static(HANDLE, &[mesh(vertices, indices, Some(morph))])); + let shot = |eng: &mut EngineState, w: f32| { + render(eng, 3, |eng| { + scene(eng); + draw_morphed(eng, HANDLE, KEY, &[w], 0.0); + }) + .2 + }; + let away = shot(&mut eng, 0.0); + let here = shot(&mut eng, 1.0); + let visible = differing_pixels(&away, &here); + assert!( + visible > 300, + "the morphed cube was culled: {visible} pixels" + ); +} + +#[test] +fn a_morph_alone_writes_velocity_and_leaves_no_trail() { + const HANDLE: u64 = 0x3044_0004; + let Some(mut eng) = try_engine() else { + eprintln!("skip: no GPU adapter"); + return; + }; + configure_taa_motion_corpus(&mut eng.renderer); + // A block that a morph (no joint, no model motion) moves 1.6 m sideways. + let (mut vertices, indices) = cube_verts(0.7, [0.95, 0.12, 0.035, 1.0]); + for v in &mut vertices { + v.position[0] -= 0.8; + v.position[1] += 1.0; + v.weights = [1.0, 0.0, 0.0, 0.0]; + } + let slide = vec![[1.6f32, 0.0, 0.0]; vertices.len()]; + let mut b = MorphTargetsBuilder::new(vertices.len()); + b.add_target(0, Some(&slide), None, None, |_, d| d); + let morph = Arc::new(b.build(Arc::new(vec!["slide".into()])).unwrap()); + assert!(eng + .renderer + .cache_model_if_static(HANDLE, &[mesh(vertices, indices, Some(morph))])); + + let draw_scene = |eng: &mut EngineState| { + let r = &mut eng.renderer; + r.set_clear_color(7.0, 10.0, 20.0, 255.0); + r.begin_mode_3d(0.0, 2.2, 6.5, 0.0, 0.8, 0.0, 0.0, 1.0, 0.0, 48.0, 0.0); + r.add_directional_light(-0.4, -1.0, -0.25, 1.0, 0.95, 0.88, 2.2); + r.draw_plane(0.0, 0.0, 0.0, 12.0, 12.0, 30.0, 38.0, 52.0, 255.0); + r.draw_cube(0.0, 1.1, -1.8, 5.0, 3.2, 0.35, 30.0, 170.0, 235.0, 255.0); + }; + // `key_of(frame)`: the same key every frame is one instance whose last + // weights are known; a new key every frame is a control with no history. + let mut run = |label: &str, keyed: bool| -> usize { + let mut frame = 0u64; + let mut capture = |eng: &mut EngineState, w: f32| { + frame += 1; + let key = if keyed { + 0x3044_2000 + } else { + 0x3044_3000 + frame + }; + render(eng, 1, |eng| { + draw_scene(eng); + draw_morphed(eng, HANDLE, key, &[w], 0.0); + }) + .2 + }; + eng.renderer.reset_temporal_history(); + for _ in 0..8 { + capture(&mut eng, 0.05); + } + let old_pose = capture(&mut eng, 0.05); + let directory = + std::env::temp_dir().join(format!("bloom-morph-{label}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&directory); + eng.renderer.pending_quality_capture_dir = Some(directory.to_string_lossy().into_owned()); + let mut frames = Vec::new(); + for _ in 0..24 { + frames.push(capture(&mut eng, 1.0)); + } + let motion = image::open(directory.join("taa-motion.png")) + .expect("morph capture did not emit the TAA velocity map") + .to_rgb8(); + let moving = motion.pixels().filter(|p| p[2] > 8).count(); + eprintln!("temporal-corpus morph-{label} moving_pixels={moving}"); + if keyed { + evaluate_motion_recovery("morph-only", &old_pose, &frames); + } + let _ = std::fs::remove_dir_all(&directory); + moving + }; + let keyed = run("keyed", true); + let control = run("unkeyed", false); + assert!( + keyed >= 250, + "a morph's motion wrote no meaningful velocity: {keyed} pixels" + ); + assert!( + control * 4 < keyed, + "the velocity did not come from the morph history (control {control}, keyed {keyed})" + ); +} + +/// Cost of the morph pass: 8 characters of 50,176 vertices, 12,000 of them +/// touched by a face rig of 56 targets (20 targets on each touched vertex), +/// every weight non-zero and changing each frame. Prints the median GPU time +/// of the pass. `cargo test --release --test golden_render bench_morph -- --ignored --nocapture` +#[test] +#[ignore] +fn bench_morph_pass_eight_faces() { + const SIDE: usize = 224; + let touched_env = std::env::var("MB_TOUCHED") + .ok() + .and_then(|v| v.parse().ok()); + let TOUCHED: usize = touched_env.unwrap_or(12_000); + const TARGETS: usize = 56; + let PER_VERTEX: usize = std::env::var("MB_PER") + .ok() + .and_then(|v| v.parse().ok()) + .unwrap_or(20); + let Some(mut eng) = try_engine() else { + eprintln!("skip: no GPU adapter"); + return; + }; + if !eng.renderer.set_morph_gpu_timing(true) { + eprintln!("skip: no timestamp queries"); + return; + } + let n = SIDE * SIDE; + let vertices: Vec = (0..n) + .map(|i| Vertex3D { + position: [(i % SIDE) as f32 * 0.01, (i / SIDE) as f32 * 0.01, 0.0], + normal: [0.0, 0.0, 1.0], + color: [1.0; 4], + uv: [0.0; 2], + joints: [0.0; 4], + weights: [1.0, 0.0, 0.0, 0.0], + tangent: [1.0, 0.0, 0.0, 1.0], + }) + .collect(); + let mut seed = 0x2545_f491_u32; + let mut rand = move || { + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + seed + }; + let mut targets = vec![(vec![[0.0f32; 3]; n], vec![[0.0f32; 3]; n]); TARGETS]; + for v in 0..TOUCHED { + for _ in 0..PER_VERTEX { + let t = rand() as usize % TARGETS; + let d = (rand() % 1000) as f32 * 1e-5 + 1e-4; + targets[t].0[v] = [d, -d, d * 0.5]; + targets[t].1[v] = [0.0, d, -d]; + } + } + let mut b = MorphTargetsBuilder::new(n); + for (slot, (p, nr)) in targets.iter().enumerate() { + b.add_target(slot as u32, Some(p), Some(nr), Some(nr), |_, d| d); + } + let names = Arc::new((0..TARGETS).map(|i| format!("t{i}")).collect::>()); + let morph = Arc::new(b.build(names).unwrap()); + eprintln!( + "bench mesh: {n} vertices, {} touched, {} entries, {:.1} MB of deltas", + morph.touched_vertices, + morph.entries.len(), + morph.byte_size() as f64 / 1e6 + ); + const HANDLE: u64 = 0x3044_0B00; + assert!(eng.renderer.cache_model_if_static( + HANDLE, + &[mesh(vertices, vec![0, 1, SIDE as u32], Some(morph))] + )); + let mut times = Vec::new(); + for frame in 0..90 { + let weights: Vec = (0..TARGETS) + .map(|t| 0.5 + 0.5 * ((frame + t) as f32 * 0.3).sin()) + .collect(); + render(&mut eng, 1, |eng| { + scene(eng); + for c in 0..8u64 { + draw_morphed(eng, HANDLE, 0x3044_0C00 + c, &weights, c as f32 * 0.1); + } + }); + let stats = eng.renderer.morph_frame_stats(); + assert_eq!(stats.jobs, 8); + if frame >= 10 { + times.push(stats.gpu_ms); + } + } + times.sort_by(|a, b| a.partial_cmp(b).unwrap()); + eprintln!( + "bench morph pass, 8 x {n} vertices: median {:.3} ms, min {:.3} ms, p90 {:.3} ms (GPU)", + times[times.len() / 2], + times[0], + times[times.len() * 9 / 10] + ); +} diff --git a/native/shared/tests/golden_render/motion_producer_audit.rs b/native/shared/tests/golden_render/motion_producer_audit.rs index f52cf646..7f16169d 100644 --- a/native/shared/tests/golden_render/motion_producer_audit.rs +++ b/native/shared/tests/golden_render/motion_producer_audit.rs @@ -38,6 +38,7 @@ fn untextured_mesh(vertices: Vec, alpha_mode: MaterialAlphaMode) -> Me double_sided: true, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, } } diff --git a/native/shared/tests/golden_render/quality_presets.rs b/native/shared/tests/golden_render/quality_presets.rs index b40ab46d..42d7b11e 100644 --- a/native/shared/tests/golden_render/quality_presets.rs +++ b/native/shared/tests/golden_render/quality_presets.rs @@ -170,6 +170,7 @@ fn install_glossy_detail_fixture(eng: &mut EngineState) { double_sided: false, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }] )); } diff --git a/native/shared/tests/golden_render/temporal_history_skinned.rs b/native/shared/tests/golden_render/temporal_history_skinned.rs index 72aad3f4..c8f950cd 100644 --- a/native/shared/tests/golden_render/temporal_history_skinned.rs +++ b/native/shared/tests/golden_render/temporal_history_skinned.rs @@ -102,6 +102,7 @@ fn fs_reactive(in: VsOut) -> ReactiveTranslucentOut { double_sided: true, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }] )); @@ -351,6 +352,7 @@ fn cached_skinned_motion_sequence_bounds_animation_trails() { double_sided: false, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }] )); assert!( @@ -466,6 +468,7 @@ fn cached_alpha_tested_card_motion_writes_velocity_and_bounds_trails() { double_sided: true, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }] )); diff --git a/native/shared/tests/golden_render/transparency.rs b/native/shared/tests/golden_render/transparency.rs index f0b7435b..05930c9a 100644 --- a/native/shared/tests/golden_render/transparency.rs +++ b/native/shared/tests/golden_render/transparency.rs @@ -67,6 +67,7 @@ fn layered_pbr_runs_on_opaque_sorted_reactive_and_weighted_paths() { double_sided: false, transmission: Default::default(), layered_pbr: layered, + morph: None, }] )); let (_, _, cached_opaque) = render(&mut eng, 2, |eng| { @@ -164,6 +165,7 @@ fn layered_pbr_runs_on_opaque_sorted_reactive_and_weighted_paths() { double_sided: false, transmission, layered_pbr: layered, + morph: None, }] )); let (_, _, cached_refractive) = render(&mut eng, 3, |eng| { @@ -247,6 +249,7 @@ fn layered_pbr_runs_on_opaque_sorted_reactive_and_weighted_paths() { double_sided: false, transmission, layered_pbr: layered_uv1, + morph: None, }] )); let (_, _, cached_refractive_uv1) = render(&mut eng, 3, |eng| { @@ -472,6 +475,7 @@ fn weighted_transparency_is_order_independent_for_intersecting_imported_blend() double_sided: false, transmission: Default::default(), layered_pbr: Default::default(), + morph: None, }; const RED_HANDLE: u64 = 0x0170_0001; const BLUE_HANDLE: u64 = 0x0170_0002; diff --git a/native/shared/tests/visibility_buffer_shading_runtime.rs b/native/shared/tests/visibility_buffer_shading_runtime.rs index 7d2f3a86..86ab2a71 100644 --- a/native/shared/tests/visibility_buffer_shading_runtime.rs +++ b/native/shared/tests/visibility_buffer_shading_runtime.rs @@ -301,6 +301,7 @@ fn opt_in_visibility_shading_replaces_eligible_forward_pixels() { double_sided: true, transmission: MaterialTransmission::default(), layered_pbr: MaterialLayeredPbr::default(), + morph: None, })], mesh_transforms: vec![bloom_shared::renderer::IDENTITY_MAT4], mesh_cast_shadows: vec![true], @@ -425,6 +426,7 @@ fn opt_in_visibility_shading_replaces_eligible_forward_pixels() { double_sided: true, transmission: MaterialTransmission::default(), layered_pbr: MaterialLayeredPbr::default(), + morph: None, }); let placement = |x: f32, z: f32| { [ @@ -589,6 +591,7 @@ fn opt_in_visibility_shading_replaces_eligible_forward_pixels() { double_sided: true, transmission: MaterialTransmission::default(), layered_pbr: MaterialLayeredPbr::default(), + morph: None, }); let skinned_model = ModelData { meshes: vec![Arc::clone(&material_model.meshes[0]), skinned_mesh], diff --git a/native/watchos/src/ffi_stubs.rs b/native/watchos/src/ffi_stubs.rs index 72788546..f4275a28 100644 --- a/native/watchos/src/ffi_stubs.rs +++ b/native/watchos/src/ffi_stubs.rs @@ -280,6 +280,21 @@ #[no_mangle] pub extern "C" fn bloom_model_find_joint(_p0: f64, _p1: i64) -> f64 { 0.0 } +#[no_mangle] pub extern "C" fn bloom_model_morph_count(_p0: f64) -> f64 { + 0.0 +} +#[no_mangle] pub extern "C" fn bloom_model_morph_index(_p0: f64, _p1: i64) -> f64 { + 0.0 +} +#[no_mangle] pub extern "C" fn bloom_anim_set_morph_weight(_p0: f64, _p1: f64, _p2: f64) { +} +#[no_mangle] pub extern "C" fn bloom_anim_set_morph_weights(_p0: f64, _p1: f64, _p2: f64, _p3: f64, _p4: f64, _p5: f64, _p6: f64, _p7: f64) { +} +#[no_mangle] pub extern "C" fn bloom_anim_clear_morphs(_p0: f64) { +} +#[no_mangle] pub extern "C" fn bloom_anim_morph_weight(_p0: f64, _p1: f64) -> f64 { + 0.0 +} #[no_mangle] pub extern "C" fn bloom_model_joint_world(_p0: f64, _p1: f64, _p2: f64) -> f64 { 0.0 } diff --git a/native/web/src/material_ffi.rs b/native/web/src/material_ffi.rs index 173c8b11..47b29382 100644 --- a/native/web/src/material_ffi.rs +++ b/native/web/src/material_ffi.rs @@ -642,6 +642,7 @@ pub fn bloom_anim_update_matrix( if !anim.joint_matrices.is_empty() { eng.renderer .set_joint_matrices_transformed(handle.to_bits(), &anim.joint_matrices, model); + bloom_shared::anim_morph::stage_weights(&mut eng.models, &mut eng.renderer, handle); } } } @@ -666,6 +667,7 @@ pub fn bloom_anim_update(handle: f64, dt: f64, scale: f64, px: f64, py: f64, pz: rot_y_f.sin(), rot_y_f.cos(), ); + bloom_shared::anim_morph::stage_weights(&mut eng.models, &mut eng.renderer, handle); } } } @@ -774,6 +776,61 @@ pub fn bloom_model_find_joint(handle: f64, name: String) -> f64 { engine().models.find_joint(handle, &name) as f64 } +// ---- Morph targets (docs/morph-targets.md) ---- + +#[wasm_bindgen] +pub fn bloom_model_morph_count(model: f64) -> f64 { + engine().models.model_morph_count(model) as f64 +} + +#[wasm_bindgen] +pub fn bloom_model_morph_index(model: f64, name: String) -> f64 { + engine().models.model_morph_index(model, &name) as f64 +} + +#[wasm_bindgen] +pub fn bloom_anim_set_morph_weight(handle: f64, index: f64, weight: f64) { + if index >= 0.0 { + engine() + .models + .anim_set_morph_weight(handle, index as usize, weight as f32); + } +} + +#[wasm_bindgen] +#[allow(clippy::too_many_arguments)] +pub fn bloom_anim_set_morph_weights( + handle: f64, + first: f64, + count: f64, + w0: f64, + w1: f64, + w2: f64, + w3: f64, + w4: f64, +) { + if first >= 0.0 { + let all = [w0 as f32, w1 as f32, w2 as f32, w3 as f32, w4 as f32]; + let n = (count.max(0.0) as usize).min(5); + engine() + .models + .anim_set_morph_weights(handle, first as usize, &all[..n]); + } +} + +#[wasm_bindgen] +pub fn bloom_anim_clear_morphs(handle: f64) { + engine().models.anim_clear_morphs(handle); +} + +#[wasm_bindgen] +pub fn bloom_anim_morph_weight(handle: f64, index: f64) -> f64 { + if index < 0.0 { + return 0.0; + } + engine().models.anim_morph_weight(handle, index as usize) as f64 +} + #[wasm_bindgen] pub fn bloom_model_joint_world(handle: f64, joint: f64, comp: f64) -> f64 { let j = joint as i64; diff --git a/package.json b/package.json index 6c5343d9..e9fae9b4 100644 --- a/package.json +++ b/package.json @@ -1665,6 +1665,59 @@ ], "returns": "f64" }, + { + "name": "bloom_model_morph_count", + "params": [ + "f64" + ], + "returns": "f64" + }, + { + "name": "bloom_model_morph_index", + "params": [ + "f64", + "string" + ], + "returns": "f64" + }, + { + "name": "bloom_anim_set_morph_weight", + "params": [ + "f64", + "f64", + "f64" + ], + "returns": "void" + }, + { + "name": "bloom_anim_set_morph_weights", + "params": [ + "f64", + "f64", + "f64", + "f64", + "f64", + "f64", + "f64", + "f64" + ], + "returns": "void" + }, + { + "name": "bloom_anim_clear_morphs", + "params": [ + "f64" + ], + "returns": "void" + }, + { + "name": "bloom_anim_morph_weight", + "params": [ + "f64", + "f64" + ], + "returns": "f64" + }, { "name": "bloom_model_joint_world", "params": [ diff --git a/src/models/index.ts b/src/models/index.ts index 3e26fa23..af44211e 100644 --- a/src/models/index.ts +++ b/src/models/index.ts @@ -1123,7 +1123,7 @@ export function animSetBlend(handle: number, slot: number, clip: number, weight: } /// Turn one joint, and with it everything below it, by `angle` radians about -/// a model-space axis, after the clips are sampled. `slot` is 0..23 and slots +/// a model-space axis, after the clips are sampled. `slot` is 0..31 and slots /// apply in order, so list a chain root first (spine, spine1, spine2 for an /// aim offset). `joint = -1` frees the slot. export function animSetJointRotation(handle: number, slot: number, joint: number, ax: number, ay: number, az: number, angle: number): void { @@ -1193,6 +1193,72 @@ export function jointWorld(handle: number, joint: number, comp: number): number return bloom_model_joint_world(handle, joint, comp); } +// ---- Morph targets (blend shapes) ------------------------------------------- +// docs/morph-targets.md. A model's morph SLOTS are its distinct target names +// over all its meshes (glTF `targetNames`): "jawOpen" on the face, the teeth +// and the tongue is one slot, and one weight drives all three. Weights belong +// to an animation instance and are drawn with its next `animUpdate` (set them +// before it). What is drawn is clamp(clip weights + these, -1, 1): authored +// `weights` channels in the clips play through the mixer like joints, and the +// weights set here add on top. Only skinned models morph. + +declare function bloom_model_morph_count(model: number): number; +declare function bloom_model_morph_index(model: number, name: number): number; +declare function bloom_anim_set_morph_weight(handle: number, index: number, weight: number): void; +declare function bloom_anim_set_morph_weights(handle: number, first: number, count: number, w0: number, w1: number, w2: number, w3: number, w4: number): void; +declare function bloom_anim_clear_morphs(handle: number): void; +declare function bloom_anim_morph_weight(handle: number, index: number): number; + +/// Number of morph slots (distinct target names) of a model; 0 without. +export function modelMorphCount(model: Model): number { + return bloom_model_morph_count(model.handle); +} + +/// Slot of the target called `name`, or -1. It compares strings: call it +/// once at load and keep the index (perry-quirks #5). +export function modelMorphIndex(model: Model, name: string): number { + return bloom_model_morph_index(model.handle, name as any); +} + +/// Set one slot's weight on an animation instance (-1..1, kept until changed +/// or cleared). +export function animSetMorphWeight(handle: number, index: number, weight: number): void { + bloom_anim_set_morph_weight(handle, index, weight); +} + +/// Set `weights.length` consecutive slots from `first`, five per native +/// call (a face of 60 shapes is 12 calls). +export function animSetMorphWeights(handle: number, first: number, weights: number[]): void { + const n = weights.length; + let i = 0; + while (i < n) { + let count = n - i; + if (count > 5) { + count = 5; + } + let w1 = 0; + let w2 = 0; + let w3 = 0; + let w4 = 0; + if (count > 1) { w1 = weights[i + 1]; } + if (count > 2) { w2 = weights[i + 2]; } + if (count > 3) { w3 = weights[i + 3]; } + if (count > 4) { w4 = weights[i + 4]; } + bloom_anim_set_morph_weights(handle, first + i, count, weights[i], w1, w2, w3, w4); + i = i + count; + } +} + +/// Drop every weight set on this instance (the clips' weights stay). +export function animClearMorphs(handle: number): void { + bloom_anim_clear_morphs(handle); +} + +/// The weight a slot is drawn with: clips plus the set weights, clamped. +export function animMorphWeight(handle: number, index: number): number { + return bloom_anim_morph_weight(handle, index); +} + // Upload a mesh via the scratch buffer (array-free). Perry 0.5.1171 rejects // passing a `number[]` to a native `i64` pointer param (strict safe-integer // check), so we push each vertex float + index scalar through the all-f64 diff --git a/tools/bloom-cook/glb_compress.rs b/tools/bloom-cook/glb_compress.rs index 7b286e69..23e4850f 100644 --- a/tools/bloom-cook/glb_compress.rs +++ b/tools/bloom-cook/glb_compress.rs @@ -626,6 +626,101 @@ mod tests { assert!(!normal.srgb); } + /// `sample_glb` plus two morph targets on its triangle: "jawOpen" + /// dense, "smile" a sparse accessor without a buffer view (as Blender + /// writes shape keys). + fn morph_glb() -> Vec { + let source = sample_glb("OPAQUE"); + let (mut root, bin, _) = split_glb(&source).unwrap(); + let mut bin = bin.to_vec(); + let mut push = |bytes: &[u8]| { + bin.resize(bin.len().next_multiple_of(4), 0); + let at = bin.len(); + bin.extend_from_slice(bytes); + (at, bytes.len()) + }; + let jaw: Vec = [0f32, -0.25, 0., 0., 0., 0., 0., 0., 0.] + .iter() + .flat_map(|v| v.to_le_bytes()) + .collect(); + let (jaw_at, jaw_len) = push(&jaw); + let (idx_at, idx_len) = push(&1u16.to_le_bytes()); + let smile: Vec = [0.125f32, 0., 0.] + .iter() + .flat_map(|v| v.to_le_bytes()) + .collect(); + let (smile_at, smile_len) = push(&smile); + bin.resize(bin.len().next_multiple_of(4), 0); + let views = root["bufferViews"].as_array_mut().unwrap(); + let first = views.len(); + for (at, len) in [(jaw_at, jaw_len), (idx_at, idx_len), (smile_at, smile_len)] { + views.push(serde_json::json!({"buffer": 0, "byteOffset": at, "byteLength": len})); + } + let accessors = root["accessors"].as_array_mut().unwrap(); + let jaw_accessor = accessors.len(); + accessors.push(serde_json::json!({ + "bufferView": first, "componentType": 5126, "count": 3, "type": "VEC3", + "min": [0.0, -0.25, 0.0], "max": [0.0, 0.0, 0.0] + })); + accessors.push(serde_json::json!({ + "componentType": 5126, "count": 3, "type": "VEC3", + "min": [0.0, 0.0, 0.0], "max": [0.125, 0.0, 0.0], + "sparse": {"count": 1, + "indices": {"bufferView": first + 1, "componentType": 5123}, + "values": {"bufferView": first + 2}} + })); + root["meshes"][0]["extras"] = serde_json::json!({"targetNames": ["jawOpen", "smile"]}); + root["meshes"][0]["primitives"][0]["targets"] = + serde_json::json!([{"POSITION": jaw_accessor}, {"POSITION": jaw_accessor + 1}]); + root["buffers"][0]["byteLength"] = serde_json::json!(bin.len()); + let mut json = serde_json::to_vec(&root).unwrap(); + json.resize(json.len().next_multiple_of(4), b' '); + let total = 28 + json.len() + bin.len(); + let mut out = Vec::new(); + for value in [GLB_MAGIC, 2, total as u32, json.len() as u32, CHUNK_JSON] { + out.extend_from_slice(&value.to_le_bytes()); + } + out.extend_from_slice(&json); + out.extend_from_slice(&(bin.len() as u32).to_le_bytes()); + out.extend_from_slice(&CHUNK_BIN.to_le_bytes()); + out.extend_from_slice(&bin); + out + } + + #[test] + fn morph_targets_survive_compression() { + let source = morph_glb(); + let (out, report) = compress_glb(&source, &["--astc".into(), "6x6".into()]).unwrap(); + assert!(report.starts_with("2 image(s) compressed"), "{report}"); + let (root, _, _) = split_glb(&out).unwrap(); + assert_eq!( + root["meshes"][0]["primitives"][0]["targets"] + .as_array() + .unwrap() + .len(), + 2 + ); + assert_eq!(root["meshes"][0]["extras"]["targetNames"][1], "smile"); + // The engine reads both targets back out of the compressed file. + for data in [&source, &out] { + let model = bloom_shared::models::load_gltf_staged(data) + .expect("morph GLB loads") + .model; + let morph = model.meshes[0] + .morph + .as_ref() + .expect("morph targets survive"); + assert_eq!( + morph.names.as_slice(), + &["jawOpen".to_string(), "smile".into()] + ); + let jaw = morph.position_offset(0, &[1.0, 0.0]); + let smile = morph.position_offset(1, &[0.0, 1.0]); + assert!((jaw[1] + 0.25).abs() < 1e-3, "{jaw:?}"); + assert!((smile[0] - 0.125).abs() < 1e-3, "{smile:?}"); + } + } + #[test] fn flat_normal_map_keeps_direction_and_zero_variance() { let (out, _) = compress_glb(&sample_glb("OPAQUE"), &[]).unwrap(); diff --git a/tools/bloom-cook/scene_cook.rs b/tools/bloom-cook/scene_cook.rs index 5fe4a7f2..97bdf707 100644 --- a/tools/bloom-cook/scene_cook.rs +++ b/tools/bloom-cook/scene_cook.rs @@ -42,6 +42,21 @@ fn convert_scene( logical_id: &str, ) -> Result { let StagedModel { model, textures } = staged; + // A cooked scene has no place for morph targets or weight tracks; + // dropping them would silently freeze every face. Characters with + // morphs load from their .glb. + if model.meshes.iter().any(|mesh| mesh.morph.is_some()) + || animation.as_ref().is_some_and(|animation| { + animation + .animations + .iter() + .any(|clip| !clip.morph_tracks.is_empty()) + }) + { + return Err(format!( + "{logical_id}: the source has morph targets, which cooked scenes cannot hold; load the .glb instead" + )); + } let mut prepared_textures = Vec::with_capacity(textures.len()); let mut texture_dependencies = Vec::with_capacity(textures.len()); for (index, texture) in textures.into_iter().enumerate() {