Skinned meshes: the source
Open the live demo · Read the guide · View on GitHub
Regions the guide quotes: rig (line 43), weights (line 55), mesh (line 62), live (line 112).
1/// A banner bent by two joints: `Skeleton` moves it on the device, `SkinBlend`
2/// mirrors the same arithmetic on the CPU so this page can check its own claim.
3///
4/// Quoted by `skinning.md` and shown whole in the Source tab.
5library;
7import 'dart:typed_data';
9import 'package:flutter3d/flutter3d.dart';
10import 'package:flutter3d_showcase/src/demo/demo.dart';
12/// The `skinning` page: a banner bound to two joints and bent by the tip one.
13/// Its check skins the same vertices on the CPU with `SkinBlend` and fails if
14/// the drawn banner did not follow the tip.
15final class SkinningDemo extends ShowcaseDemo {
16 /// How far the tip joint bends, from 0 to 1, where 1 is 1.4 radians, a little
17 /// under a right angle. The "Bend" slider writes it, and the check expects
18 /// the banner to have left its bind pose by as much.
19 double bend = 0.5;
21 static const double _depth = 2.4;
22 static const double _maxAngle = 1.4; // a little under a right angle
24 late final SceneNode _base;
25 late final SceneNode _tip;
26 late final Skeleton _skeleton;
27 late final MeshData _cpuMesh;
29 /// The vertex whose bind position sits halfway along the banner, where the
30 /// blend of the two joints moves it the most — see `skinning.md`.
31 late int _midVertex;
34 void configureView(DemoContext context) {
35 context.orbit
36 ..distance = 4.0
37 ..pitch = 0.15
38 ..yaw = 0.5;
39 }
42 Scene build(DemoContext context) {
43 _base = SceneNode(name: 'base')..setPosition(0.0, 0.0, -_depth / 2);
44 _tip = SceneNode(name: 'tip')..setPosition(0.0, 0.0, _depth);
45 _base.add(_tip);
47 final Matrix4 inverseBindBase = Matrix4.copy(_base.sceneMatrix)..invert();
48 final Matrix4 inverseBindTip = Matrix4.copy(_tip.sceneMatrix)..invert();
49 _skeleton = Skeleton(
50 joints: <SceneNode>[_base, _tip],
51 inverseBindMatrices: <Matrix4>[inverseBindBase, inverseBindTip],
52 name: 'flagpole',
53 );
55 _cpuMesh = const PlaneShape(
56 width: 0.7,
57 depth: _depth,
58 depthSegments: 8,
59 ).build().convertedTo(VertexLayout.skinned);
60 _paintWeights(_cpuMesh);
62 final RenderMaterial fabric = RenderMaterial(
63 name: 'banner',
64 baseColor: LinearColor.fromSrgb(0.82, 0.24, 0.2, 1.0),
65 roughness: 0.7,
66 doubleSided: true,
67 );
68 final MeshNode banner = MeshNode(
69 DeviceMesh.upload(context.device, _cpuMesh),
70 fabric,
71 name: 'banner',
72 )..skeleton = _skeleton;
74 return Scene()
75 ..add(banner)
76 ..add(
77 LightNode(name: 'sun', intensity: 3.0 * LightNode.legacyUnit)
78 ..setLocalForward(Vector3(-0.3, -0.6, -0.7)),
79 );
80 }
82 /// Every vertex leans on the base joint near `z = -depth/2` and on the tip
83 /// joint near `z = +depth/2`, blending linearly between the two — the
84 /// ordinary two-joint paint a rope or a flagpole gets.
85 void _paintWeights(MeshData mesh) {
86 final VertexLayout layout = mesh.layout;
87 final int stride = layout.floatsPerVertex;
88 final int positionAt = layout.floatOffsetOf(VertexLayout.position.name);
89 final int jointsAt = layout.floatOffsetOf(VertexLayout.joints.name);
90 final int weightsAt = layout.floatOffsetOf(VertexLayout.weights.name);
91 final Float32List vertices = mesh.vertices;
92 var closestToMiddle = double.infinity;
94 for (var v = 0; v < mesh.vertexCount; v++) {
95 final int at = v * stride;
96 final double z = vertices[at + positionAt + 2];
97 final double t = ((z + _depth / 2) / _depth).clamp(0.0, 1.0);
98 vertices[at + jointsAt] = 0.0;
99 vertices[at + jointsAt + 1] = 1.0;
100 vertices[at + weightsAt] = 1.0 - t;
101 vertices[at + weightsAt + 1] = t;
103 if (z.abs() < closestToMiddle) {
104 closestToMiddle = z.abs();
105 _midVertex = v;
106 }
107 }
108 }
111 void update(DemoContext context, double dt) {
112 _tip.setRotation(
113 Quaternion.axisAngle(Vector3(1.0, 0.0, 0.0), bend * _maxAngle),
114 );
115 }
118 List<DemoControl> controls(DemoContext context) => <DemoControl>[
119 SliderControl(
120 'Bend',
121 min: 0,
122 max: 1,
123 value: () => bend,
124 onChanged: (double v) => bend = v,
125 ),
126 ];
129 void verify(Scene scene, FrameResult frame) {
130 if (frame.skinnedDraws < 1) {
131 throw StateError('the banner was not drawn through the skinned stage');
132 }
133 // The device already posed `_skeleton.matrices` for this frame; blending
134 // them again on the CPU is `SkinBlend`'s own job, and the tip of the
135 // banner should have left its bind position by as much as `bend` asked.
136 final SkinBlend blend = SkinBlend(_cpuMesh);
137 if (!blend.blend(_skeleton.matrices)) {
138 throw StateError('SkinBlend saw no change from the bind pose');
139 }
140 final int stride = _cpuMesh.layout.floatsPerVertex;
141 final int positionAt = _cpuMesh.layout.floatOffsetOf(
142 VertexLayout.position.name,
143 );
144 final double skinnedY =
145 blend.vertices[_midVertex * stride + positionAt + 1];
146 if (skinnedY.abs() < 1e-3) {
147 throw StateError('the banner did not follow the tip joint');
148 }
149 }
150}