flutter3d
Showcase Changelog 62 packages API reference

A crowd from a baked clip: the source

since 0.7.0 or earlier Animation

Regions the guide quotes: rig (line 42), bake (line 58), read (line 153).

1/// A crowd that plays clips baked into a table, not a skeleton apiece.
2///
3/// A skinned draw hands the GPU one array of joint matrices, and that array
4/// is the same for every instance of the draw. A thousand copies would all
5/// stand in the same pose. `BakedPoses` samples every clip once into a table
6/// instead, so each instance only needs which clip and how far into it, the
7/// two numbers instancing already carries. This page fakes the "read a row of
8/// the table" step on the CPU, since no draw path in this engine samples the
9/// table on the GPU yet, but the table itself, and what a row of it means, are
10/// exactly what a real one would read.
11///
12/// Quoted by `baked_crowd.md` and shown whole in the Source tab.
13library;
15import 'dart:typed_data';
17import 'package:flutter3d/flutter3d.dart';
18import 'package:flutter3d_showcase/src/demo/demo.dart';
20/// The `baked-crowd` page: six figures reading their arm's pose out of one
21/// `BakedPoses` table of two clips, 32 frames each, each figure at its own clip
22/// and phase.
23final class BakedCrowdDemo extends ShowcaseDemo {
24 double _time = 0.0;
25 static const int _framesPerClip = 32;
26 static const int _people = 6;
28 late final BakedPoses _table;
29 late final List<double> _phase;
30 late final List<int> _clip;
31 late final List<SceneNode> _arms;
33 @override
34 void configureView(DemoContext context) {
35 context.orbit
36 ..distance = 6.0
37 ..pitch = 0.3;
38 }
40 @override
41 Scene build(DemoContext context) {
42 // The rig every clip is baked against: a shoulder with an arm hanging off
43 // it. `BakedPoses` samples it once per clip and needs no scene of its own
44 // afterwards.
45 final Scene rig = Scene();
46 final SceneNode shoulder = rig.add(SceneNode(name: 'shoulder'));
47 final SceneNode arm = SceneNode(name: 'arm')..setPosition(0.0, -0.8, 0.0);
48 shoulder.add(arm);
49 final Skeleton skeleton = Skeleton(
50 name: 'wave',
51 joints: <SceneNode>[shoulder, arm],
52 inverseBindMatrices: <Matrix4>[
53 Matrix4.copy(shoulder.sceneMatrix)..invert(),
54 Matrix4.copy(arm.sceneMatrix)..invert(),
55 ],
56 );
58 // Two clips, a slow wave and a fast one, baked into one table. A crowd
59 // wearing both is one sampler, not two.
60 final AnimationPlayer player = AnimationPlayer(
61 clips: <AnimationClip>[_wave(seconds: 1.6), _wave(seconds: 0.5)],
62 targets: <AnimationTarget?>[shoulder, null],
63 );
64 _table = BakedPoses.of(
65 player,
66 skeleton: skeleton,
67 meshToScene: Matrix4.identity(),
68 framesPerClip: _framesPerClip,
69 );
71 // A capsule-and-sphere silhouette rather than bare boxes — still a rigid
72 // part per joint, which is what lets the table drive a whole mesh with
73 // one matrix (see `{{code read}}`), but one a crowd actually reads as
74 // people rather than furniture.
75 final Scene scene = Scene();
76 final RenderMaterial torso = RenderMaterial(
77 name: 'torso',
78 baseColor: LinearColor.fromSrgb(0.55, 0.6, 0.68, 1.0),
79 );
80 final RenderMaterial limb = RenderMaterial(
81 name: 'arm',
82 baseColor: LinearColor.fromSrgb(0.85, 0.5, 0.3, 1.0),
83 );
84 final RenderMaterial skin = RenderMaterial(
85 name: 'head',
86 baseColor: LinearColor.fromSrgb(0.85, 0.68, 0.55, 1.0),
87 );
88 final DeviceMesh torsoMesh = DeviceMesh.upload(
89 context.device,
90 CapsuleShape(radius: 0.22, height: 0.6).build(),
91 );
92 final DeviceMesh headMesh = DeviceMesh.upload(
93 context.device,
94 SphereShape(radius: 0.18, segments: 16, rings: 12).build(),
95 );
96 final DeviceMesh armMesh = DeviceMesh.upload(
97 context.device,
98 CapsuleShape(radius: 0.09, height: 0.5).build(),
99 );
101 _phase = <double>[];
102 _clip = <int>[];
103 _arms = <SceneNode>[];
104 for (var i = 0; i < _people; i++) {
105 final int clip = i.isEven ? 0 : 1;
106 _clip.add(clip);
107 _phase.add(i / _people);
108 final double x = (i - (_people - 1) / 2) * 1.1;
109 scene.add(
110 MeshNode(torsoMesh, torso, name: 'person $i')..setPosition(x, 0.0, 0.0),
111 );
112 scene.add(
113 MeshNode(headMesh, skin, name: 'head $i')..setPosition(x, 0.68, 0.0),
114 );
115 final SceneNode shoulderNode = SceneNode(name: 'shoulder $i')
116 ..setPosition(x, 0.55, 0.0);
117 final SceneNode armNode = MeshNode(armMesh, limb, name: 'arm $i')
118 ..setPosition(0.0, -0.4, 0.0);
119 shoulderNode.add(armNode);
120 scene.add(shoulderNode);
121 _arms.add(armNode);
122 }
123 return scene;
124 }
126 AnimationClip _wave({required double seconds}) => AnimationClip(
127 name: 'wave $seconds',
128 tracks: <AnimationTrack>[
129 AnimationTrack(
130 nodeIndex: 0,
131 path: AnimationPath.rotation,
132 interpolation: AnimationInterpolation.linear,
133 times: Float32List.fromList(<double>[0.0, seconds / 2, seconds]),
134 values: Float32List.fromList(<double>[
135 0.0, 0.0, 0.0, 1.0, //
136 ..._quarterZ(0.6),
137 0.0, 0.0, 0.0, 1.0,
138 ]),
139 componentCount: 4,
140 ),
141 ],
142 );
144 static List<double> _quarterZ(double radians) {
145 final Quaternion q = Quaternion.axisAngle(Vector3(0.0, 0.0, 1.0), radians)
146 ..normalize();
147 return <double>[q.x, q.y, q.z, q.w];
148 }
150 @override
151 void update(DemoContext context, double dt) {
152 _time += dt;
153 // What a shader would do per instance: pick a clip's rows, blend the two
154 // the current time falls between, and use the joint matrix that came out.
155 // Nothing here touches a skeleton; the table already has the answer.
156 //
157 // A joint matrix is a delta from rest, not a place in the world — the
158 // shoulder is joint 0, and its matrix is identity when the shoulder has
159 // not turned. Composing it with the arm's own rest offset turns that
160 // delta back into "where the arm hangs now, relative to its shoulder".
161 for (var i = 0; i < _people; i++) {
162 final int clip = _clip[i];
163 final double duration = _table.durations[clip];
164 final double t = ((_time + _phase[i] * duration) % duration) / duration;
165 final double row = t * _framesPerClip;
166 final int a = row.floor() % _framesPerClip;
167 final int b = (a + 1) % _framesPerClip;
168 final double f = row - row.floor();
169 final Matrix4 ma = _table.matrixAt(clip, a, 0);
170 final Matrix4 mb = _table.matrixAt(clip, b, 0);
171 final Matrix4 shoulderDelta = Matrix4.zero();
172 for (var e = 0; e < 16; e++) {
173 shoulderDelta.storage[e] = ma.storage[e] * (1 - f) + mb.storage[e] * f;
174 }
175 _arms[i].setLocalMatrix(
176 shoulderDelta.multiplied(Matrix4.translation(Vector3(0.0, -0.4, 0.0))),
177 );
178 }
179 }
181 @override
182 void verify(Scene scene, FrameResult frame) {
183 if (_table.clips != 2) throw StateError('two clips were baked');
184 if (_table.frames != _framesPerClip) {
185 throw StateError('the table samples $_framesPerClip frames a clip');
186 }
187 // A joint matrix is sceneMatrix * inverseBindMatrix: at the shoulder's own
188 // rest pose the two cancel, so row 0 of every clip has to read back as the
189 // identity, or a crowd reading the table wears the wrong pose from frame
190 // one.
191 final Matrix4 rest = _table.matrixAt(0, 0, 0);
192 if ((rest.clone()..sub(Matrix4.identity())).storage.any(
193 (double v) => v.abs() > 0.01,
194 )) {
195 throw StateError('frame 0 is not the shoulder at rest');
196 }
197 if (frame.drawCalls < 1) throw StateError('the crowd was not drawn');
198 }