Skip to main content

vrm_runtime/
render.rs

1use glam::{Mat4, Vec3};
2
3use crate::primitive::{PrimitiveTopology, RenderPrimitive};
4use crate::runtime::SkinningPalette;
5use crate::{Avatar, MaterialId, NodeId, PrimitiveId};
6
7/// A single primitive with every CPU-side transform already applied: morph
8/// weights accumulated, skinned primitives deformed by their joint matrices
9/// and non-skinned ones placed by their node's world transform.
10///
11/// A renderer can upload these buffers directly without a morph or skinning
12/// shader. For valid assets, the result follows the same morphing and skinning
13/// semantics as the corresponding GPU path.
14#[derive(Debug, Clone)]
15pub struct CpuMesh {
16    /// Stable identifier of the source primitive.
17    pub primitive_id: PrimitiveId,
18    /// Typed identifier of the source node.
19    pub node_id: NodeId,
20    /// Material selected by the source primitive.
21    pub material_id: Option<MaterialId>,
22    /// Final vertex positions (world space).
23    pub positions: Vec<[f32; 3]>,
24    /// Final normals, normalized after transformation.
25    pub normals: Vec<[f32; 3]>,
26    /// Final tangents (xyz normalized, w handedness preserved).
27    pub tangents: Vec<[f32; 4]>,
28    /// Triangle/line/point indices into the vertex attributes.
29    pub indices: Vec<u32>,
30    /// Consecutive `TEXCOORD_n` buffers.
31    pub texcoord_sets: Vec<Vec<[f32; 2]>>,
32    /// Vertex colors (RGBA).
33    pub colors: Vec<[f32; 4]>,
34    /// Draw topology.
35    pub topology: PrimitiveTopology,
36}
37
38/// Bakes the dynamic state of one evaluated frame into CPU vertex buffers.
39pub(crate) fn bake_frame(
40    asset: &Avatar,
41    world_matrices: &[Mat4],
42    skinning_palettes: &[SkinningPalette],
43    morph_weights: &[Vec<f32>],
44) -> Vec<CpuMesh> {
45    asset
46        .primitives()
47        .iter()
48        .enumerate()
49        .map(|(index, primitive)| {
50            let world = world_matrices
51                .get(primitive.node_index() as usize)
52                .copied()
53                .unwrap_or(Mat4::IDENTITY);
54            render_primitive(
55                PrimitiveId::from_index(index),
56                primitive,
57                morph_weights.get(index).map(Vec::as_slice).unwrap_or(&[]),
58                world,
59                skinning_palettes,
60            )
61        })
62        .collect()
63}
64
65/// Transforms one vertex by `transform`, treating it as a point for
66/// positions (`w = 1`) and as a direction for normals/tangents (`w = 0`).
67fn transform_vertex(
68    transform: Mat4,
69    position: [f32; 3],
70    normal: [f32; 3],
71    tangent: [f32; 4],
72) -> ([f32; 3], [f32; 3], [f32; 4]) {
73    let position = transform
74        .transform_point3(Vec3::from_array(position))
75        .to_array();
76    let normal = transform
77        .transform_vector3(Vec3::from_array(normal))
78        .normalize_or_zero()
79        .to_array();
80    let tangent_xyz = transform
81        .transform_vector3(Vec3::from_array([tangent[0], tangent[1], tangent[2]]))
82        .normalize_or_zero();
83    (
84        position,
85        normal,
86        [tangent_xyz.x, tangent_xyz.y, tangent_xyz.z, tangent[3]],
87    )
88}
89
90fn render_primitive(
91    primitive_id: PrimitiveId,
92    primitive: &RenderPrimitive,
93    morph_weights: &[f32],
94    world_transform: Mat4,
95    skinning_palettes: &[SkinningPalette],
96) -> CpuMesh {
97    let morphed = primitive.morphed_vertices_with_weights(morph_weights);
98    let vertex_count = morphed.positions.len();
99
100    let mut positions = morphed.positions;
101    let mut normals = morphed.normals;
102    let mut tangents = morphed.tangents;
103
104    match primitive.skin_index() {
105        Some(skin_index) => {
106            let joint_matrices = skinning_palettes
107                .iter()
108                .find(|palette| palette.skin_id.index() == skin_index)
109                .map(|palette| palette.joint_matrices.as_slice())
110                .unwrap_or(&[]);
111            for i in 0..vertex_count {
112                // Unweighted vertices stay at their rest position, matching
113                // the consuming renderer's vertex shader.
114                let weight_sum: f32 = primitive
115                    .skinning_sets()
116                    .iter()
117                    .flat_map(|set| set.weights()[i])
118                    .sum();
119                if weight_sum == 0.0 || joint_matrices.is_empty() {
120                    continue;
121                }
122                let mut skin_mat = Mat4::ZERO;
123                let mut valid_palette = true;
124                'sets: for set in primitive.skinning_sets() {
125                    for (&joint, &weight) in set.joints()[i].iter().zip(&set.weights()[i]) {
126                        if weight > 0.0 {
127                            let Some(joint_matrix) = joint_matrices.get(joint as usize) else {
128                                valid_palette = false;
129                                break 'sets;
130                            };
131                            skin_mat += *joint_matrix * weight;
132                        }
133                    }
134                }
135                if !valid_palette {
136                    continue;
137                }
138                let (position, normal, tangent) =
139                    transform_vertex(skin_mat, positions[i], normals[i], tangents[i]);
140                positions[i] = position;
141                normals[i] = normal;
142                tangents[i] = tangent;
143            }
144        }
145        None => {
146            for i in 0..vertex_count {
147                let (position, normal, tangent) =
148                    transform_vertex(world_transform, positions[i], normals[i], tangents[i]);
149                positions[i] = position;
150                normals[i] = normal;
151                tangents[i] = tangent;
152            }
153        }
154    }
155
156    CpuMesh {
157        primitive_id,
158        node_id: NodeId::from_index(primitive.node_index() as usize),
159        material_id: primitive.material_index().map(MaterialId::from_index),
160        positions,
161        normals,
162        tangents,
163        indices: primitive.indices().to_vec(),
164        texcoord_sets: primitive.texcoord_sets().to_vec(),
165        colors: primitive.colors().to_vec(),
166        topology: primitive.topology(),
167    }
168}
169
170#[cfg(test)]
171mod tests {
172    use super::*;
173    use crate::morph_target::MorphTarget;
174    use crate::primitive::RenderPrimitive;
175    use crate::runtime::SkinningPalette;
176    use crate::{SkinId, Transform};
177
178    fn build_primitive(
179        world_transform: Transform,
180        skin_index: Option<usize>,
181        weights: Vec<[f32; 4]>,
182        morph_targets: Vec<MorphTarget>,
183        morph_weights: Vec<f32>,
184    ) -> RenderPrimitive {
185        RenderPrimitive::new(
186            3,
187            world_transform,
188            vec![[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]],
189            vec![[0.0, 0.0, 1.0], [0.0, 0.0, 1.0]],
190            vec![0, 1],
191            vec![[0, 1, 0, 0], [0, 1, 0, 0]],
192            weights,
193            morph_targets,
194            vec![[0.0, 0.0], [1.0, 0.0]],
195            vec![[1.0, 0.0, 0.0, 1.0], [1.0, 0.0, 0.0, 1.0]],
196            vec![[1.0, 1.0, 1.0, 1.0]; 2],
197            vec![[0.0, 0.0]; 2],
198            None,
199            None,
200            PrimitiveTopology::Lines,
201            morph_weights,
202            false,
203            skin_index,
204            0,
205        )
206    }
207
208    fn plain() -> RenderPrimitive {
209        build_primitive(
210            Transform::IDENTITY,
211            None,
212            vec![[0.0; 4]; 2],
213            Vec::new(),
214            Vec::new(),
215        )
216    }
217
218    fn render_for_test(primitive: &RenderPrimitive, palettes: &[SkinningPalette]) -> CpuMesh {
219        render_primitive(
220            PrimitiveId::from_index(0),
221            primitive,
222            primitive.morph_weights(),
223            primitive.world_transform().to_mat4(),
224            palettes,
225        )
226    }
227
228    #[test]
229    fn non_skinned_uses_world_transform() {
230        let transform = Transform::from_translation(glam::Vec3::new(5.0, 0.0, 0.0));
231        let primitive = build_primitive(transform, None, vec![[0.0; 4]; 2], Vec::new(), Vec::new());
232        let mesh = render_for_test(&primitive, &[]);
233
234        assert_eq!(mesh.positions[0], [5.0, 0.0, 0.0]);
235        assert_eq!(mesh.positions[1], [6.0, 0.0, 0.0]);
236        assert_eq!(mesh.normals[0], [0.0, 0.0, 1.0]);
237        assert_eq!(mesh.indices, vec![0, 1]);
238        assert_eq!(mesh.node_id, NodeId::from_index(3));
239    }
240
241    #[test]
242    fn skinned_primitive_moves_by_joint_matrix() {
243        let primitive = build_primitive(
244            Transform::IDENTITY,
245            Some(0),
246            vec![[1.0, 0.0, 0.0, 0.0]; 2],
247            Vec::new(),
248            Vec::new(),
249        );
250        let palette = SkinningPalette {
251            skin_id: SkinId::from_index(0),
252            // Vertex 0 binds joint 0, vertex 1 binds joint 1.
253            joint_matrices: vec![
254                Mat4::from_translation(glam::Vec3::new(1.0, 0.0, 0.0)),
255                Mat4::from_translation(glam::Vec3::new(2.0, 0.0, 0.0)),
256            ],
257        };
258        let mesh = render_for_test(&primitive, &[palette]);
259
260        assert_eq!(mesh.positions[0], [1.0, 0.0, 0.0]);
261        assert_eq!(mesh.positions[1], [2.0, 0.0, 0.0]);
262    }
263
264    #[test]
265    fn skinned_vertex_with_zero_weight_stays_put() {
266        let primitive = build_primitive(
267            Transform::IDENTITY,
268            Some(0),
269            vec![[0.0; 4]; 2],
270            Vec::new(),
271            Vec::new(),
272        );
273        let palette = SkinningPalette {
274            skin_id: SkinId::from_index(0),
275            joint_matrices: vec![Mat4::from_translation(glam::Vec3::new(9.0, 0.0, 0.0))],
276        };
277        let mesh = render_for_test(&primitive, &[palette]);
278
279        // Unweighted vertices keep their rest position.
280        assert_eq!(mesh.positions[0], [0.0, 0.0, 0.0]);
281        assert_eq!(mesh.positions[1], [1.0, 0.0, 0.0]);
282    }
283
284    #[test]
285    fn skinned_vertex_with_missing_palette_stays_put() {
286        let primitive = build_primitive(
287            Transform::IDENTITY,
288            Some(3),
289            vec![[1.0, 0.0, 0.0, 0.0]; 2],
290            Vec::new(),
291            Vec::new(),
292        );
293        let mesh = render_for_test(&primitive, &[]);
294
295        assert_eq!(mesh.positions[0], [0.0, 0.0, 0.0]);
296    }
297
298    #[test]
299    fn malformed_runtime_palette_does_not_panic_or_partially_skin() {
300        let primitive = build_primitive(
301            Transform::IDENTITY,
302            Some(0),
303            vec![[0.0, 1.0, 0.0, 0.0]; 2],
304            Vec::new(),
305            Vec::new(),
306        );
307        let palette = SkinningPalette {
308            skin_id: SkinId::from_index(0),
309            // The private test constructor can bypass asset validation, so
310            // this intentionally omits the weighted joint at palette index 1.
311            joint_matrices: vec![Mat4::IDENTITY],
312        };
313
314        let mesh = render_for_test(&primitive, &[palette]);
315
316        assert_eq!(mesh.positions[0], [0.0, 0.0, 0.0]);
317        assert_eq!(mesh.positions[1], [1.0, 0.0, 0.0]);
318    }
319
320    #[test]
321    fn tangent_handedness_is_preserved() {
322        let mesh = render_for_test(&plain(), &[]);
323        assert_eq!(mesh.tangents[0], [1.0, 0.0, 0.0, 1.0]);
324    }
325
326    #[test]
327    fn morph_weights_are_applied() {
328        let target = MorphTarget::new(vec![[2.0, 0.0, 0.0], [0.0, 3.0, 0.0]], None, None);
329        let primitive = build_primitive(
330            Transform::IDENTITY,
331            None,
332            vec![[0.0; 4]; 2],
333            vec![target],
334            vec![0.5],
335        );
336        let mesh = render_for_test(&primitive, &[]);
337
338        // base + 0.5 * delta
339        assert_eq!(mesh.positions[0], [1.0, 0.0, 0.0]);
340        assert_eq!(mesh.positions[1], [1.0, 1.5, 0.0]);
341    }
342}