flutter3d
Showcase Changelog 62 packages API reference

Impostors: the source

since 0.8.0 Scene and geometry

Regions the guide quotes: tree (line 44), mesh (line 66), upload (line 88), asset (line 102), row (line 161), sun (line 168), light (line 175), mark (line 179), check (line 212), bake (line 225).

1/// A row of trees whose far ones are drawn as octahedral impostors: one card
2/// each, turned to the eye and painted from views baked in advance.
3///
4/// Quoted by `impostors.md` and shown whole in the Source tab.
5library;
6
7import 'dart:math' as math;
8import 'dart:typed_data';
9
10import 'package:flutter3d/flutter3d.dart';
11import 'package:flutter3d_showcase/src/demo/demo.dart';
13/// A ball of the tree: where it is, how big, and its colour as a paint
14/// program shows it.
15typedef _Ball = ({Vector3 center, double radius, Vector3 color});
17/// What a ray met first: how far along it, the surface normal there and the
18/// colour of the part it hit.
19typedef _Hit = ({double t, Vector3 normal, Vector3 color});
21/// The `impostors` page: a row of trees on grass, the near ones meshes and
22/// the far ones octahedral cards. Its check is that the row starts in meshes
23/// and ends in cards.
24final class ImpostorsDemo extends ShowcaseDemo {
25 /// Whether the cards are tinted blue, to show where the meshes end.
26 bool markCards = false;
28 /// The sun's direction around the vertical, in radians, -π to π.
29 double sunYaw = 0.6;
31 late final Scene _scene;
32 late final LightNode _sun;
34 /// Texels along each side of one baked view.
35 static const int _cell = 32;
37 /// How many trees stand in the row.
38 static const int _count = 5;
40 static Vector3 get _bark => Vector3(0.45, 0.3, 0.18);
41 static Vector3 get _leaves => Vector3(0.25, 0.6, 0.2);
42 static Vector3 get _fruit => Vector3(0.85, 0.15, 0.1);
44 static Aabb3 get _trunk =>
45 Aabb3.minMax(Vector3(-0.12, 0.0, -0.12), Vector3(0.12, 1.2, 0.12));
46 static List<_Ball> get _balls => <_Ball>[
47 (center: Vector3(0.0, 1.75, 0.0), radius: 0.75, color: _leaves),
48 (center: Vector3(0.0, 2.4, 0.0), radius: 0.45, color: _leaves),
49 // One fruit on the +X side, so the tree looks different from each side.
50 (center: Vector3(0.8, 1.45, 0.0), radius: 0.25, color: _fruit),
51 ];
53 @override
54 void configureView(DemoContext context) {
55 context.orbit
56 ..target.setValues(0.0, 1.3, -10.0)
57 ..distance = 11.0
58 ..pitch = 0.12
59 ..yaw = 0.25;
60 }
62 @override
63 Scene build(DemoContext context) {
64 final GraphicsDevice device = context.device;
66 final MeshData tree = MeshData.merge(<MeshData>[
67 _painted(
68 CuboidShape(
69 size: _trunk.max - _trunk.min,
70 ).build().transformed(Matrix4.translation(_trunk.center)),
71 _bark,
72 ),
73 for (final _Ball ball in _balls)
74 _painted(
75 SphereShape(
76 radius: ball.radius,
77 segments: 24,
78 rings: 12,
79 ).build().transformed(Matrix4.translation(ball.center)),
80 ball.color,
81 ),
82 ]);
83 final Vector3 center = tree.computeBounds().center;
84 // A little over the furthest vertex: a ball's true edge can lie between
85 // the vertices of its mesh.
86 final double radius = _radiusAround(tree, center) * 1.02;
88 final ({Uint8List albedo, Uint8List normalDepth}) atlas = _bake(
89 center,
90 radius,
91 );
92 const int side = _cell * impostorGrid;
93 TextureHandle upload(Uint8List rgba) => device.createTextureFromPixels(
94 width: side,
95 height: side,
96 format: TextureFormat.r8g8b8a8UNormInt,
97 pixels: ByteData.sublistView(rgba),
98 );
99 final TextureHandle albedo = upload(atlas.albedo);
100 final TextureHandle normalDepth = upload(atlas.normalDepth);
102 final ModelImpostor impostor = ModelImpostor(
103 // Indices into a file's images. Nothing is read through them here: the
104 // textures are handed over below.
105 albedoImage: 0,
106 normalDepthImage: 1,
107 grid: impostorGrid,
108 center: center,
109 radius: radius,
110 );
111 final ModelAsset asset = ModelAsset(
112 name: 'tree',
113 parts: <ModelPart>[
114 ModelPart(
115 mesh: DeviceMesh.upload(device, tree),
116 material: RenderMaterial(name: 'tree', roughness: 0.8),
117 name: 'tree',
118 ),
119 ],
120 nodes: <ModelNode>[
121 ModelNode(
122 name: 'tree',
123 surfaces: const <int>[0],
124 lods: <ModelLod>[
125 ModelLod.impostor(impostor: impostor, maxScreenFraction: 0.25),
126 ],
127 ),
128 ],
129 roots: const <int>[0],
130 localBounds: tree.computeBounds(),
131 impostors: <ModelImpostor, ImpostorPart>{
132 impostor: ImpostorPart(
133 card: DeviceMesh.upload(
134 device,
135 impostorCard(center: center, radius: radius),
136 ),
137 albedo: albedo,
138 normalDepth: normalDepth,
139 ),
140 },
141 );
143 _scene = Scene()
144 ..ambientColor = LinearColor(0.5, 0.6, 0.75)
145 ..ambientIntensity = 0.25 * LightNode.legacyUnit
146 ..add(
147 MeshNode(
148 DeviceMesh.upload(
149 device,
150 const PlaneShape(width: 24, depth: 40).build(),
151 ),
152 RenderMaterial(
153 name: 'grass',
154 baseColor: LinearColor.fromSrgb(0.42, 0.5, 0.32, 1.0),
155 roughness: 0.95,
156 ),
157 name: 'ground',
158 )..setPosition(0.0, 0.0, -12.0),
159 );
161 for (var i = 0; i < _count; i++) {
162 asset
163 .instantiate(_scene, name: 'tree $i')
164 .root
165 .setPosition(i.isEven ? -1.5 : 1.5, 0.0, -2.0 - 6.0 * i);
166 }
168 _sun = LightNode(name: 'sun', intensity: 3.0 * LightNode.legacyUnit)
169 ..castsShadow = true;
170 return _scene..add(_sun);
171 }
173 @override
174 void update(DemoContext context, double dt) {
175 _sun.setLocalForward(
176 Vector3(math.sin(sunYaw), -0.9, math.cos(sunYaw))..normalize(),
177 );
179 for (final LodGroup group in _scene.lodGroups) {
180 for (final LodLevel level in group.levels) {
181 if (level.node is ImpostorNode) {
182 level.node.material.baseColor = LinearColor.fromSrgb(
183 markCards ? 0.55 : 1.0,
184 markCards ? 0.75 : 1.0,
185 1.0,
186 1.0,
187 );
188 }
189 }
190 }
191 }
193 @override
194 List<DemoControl> controls(DemoContext context) => <DemoControl>[
195 ToggleControl(
196 'Tint the cards blue',
197 value: () => markCards,
198 onChanged: (bool v) => markCards = v,
199 ),
200 SliderControl(
201 'Sun direction',
202 min: -math.pi,
203 max: math.pi,
204 value: () => sunYaw,
205 onChanged: (double v) => sunYaw = v,
206 format: (double v) => '${(v * 180 / math.pi).round()} deg',
207 ),
208 ];
210 @override
211 void verify(Scene scene, FrameResult frame) {
212 final List<LodGroup> groups = scene.lodGroups;
213 bool showsCard(LodGroup g) =>
214 g.levels[g.activeLevel].node is ImpostorNode &&
215 g.levels[g.activeLevel].node.isVisible;
216 if (groups.length != _count ||
217 !groups.any(showsCard) ||
218 !groups.any((LodGroup g) => g.activeLevel == 0) ||
219 frame.drawCalls < 1) {
220 throw StateError('the row should end in cards and start in meshes');
221 }
222 }
225/// Both atlases, [impostorGrid] by [impostorGrid] views of [ImpostorsDemo._cell]
226/// texels, found by casting one ray a texel at the tree's own shapes.
227///
228/// Each view looks back along [impostorViewDirection] at the sphere of
229/// [radius] around [center], with [impostorRight] to its right, and the top
230/// row of a view is the side its up axis points to: the layout the impostor
231/// shader reads.
232({Uint8List albedo, Uint8List normalDepth}) _bake(
233 Vector3 center,
234 double radius,
235) {
236 const int cell = ImpostorsDemo._cell;
237 const int side = cell * impostorGrid;
238 final Uint8List albedo = Uint8List(side * side * 4);
239 final Uint8List normalDepth = Uint8List(side * side * 4);
240 int byte(double v) => (v.clamp(0.0, 1.0) * 255.0).round();
241 final List<_Ball> balls = ImpostorsDemo._balls;
242 final Aabb3 trunk = ImpostorsDemo._trunk;
243 final Vector3 bark = ImpostorsDemo._bark;
244 final Vector3 empty = ImpostorsDemo._leaves;
246 for (var row = 0; row < impostorGrid; row++) {
247 for (var column = 0; column < impostorGrid; column++) {
248 final Vector3 d = impostorViewDirection(column, row);
249 final Vector3 right = impostorRight(d);
250 final Vector3 up = d.cross(right);
251 for (var y = 0; y < cell; y++) {
252 for (var x = 0; x < cell; x++) {
253 final Vector3 origin =
254 center +
255 right.scaled(((x + 0.5) / cell * 2.0 - 1.0) * radius) +
256 up.scaled((1.0 - (y + 0.5) / cell * 2.0) * radius) +
257 d.scaled(2.0 * radius);
258 final _Hit? hit = _cast(origin, -d, balls, trunk, bark);
259 final int to = ((row * cell + y) * side + column * cell + x) * 4;
260 // An empty texel still gets a leaf colour, with no coverage, so a
261 // filtered read at the edge of the tree does not mix in black.
262 final Vector3 color = hit?.color ?? empty;
263 albedo
264 ..[to] = byte(color.x)
265 ..[to + 1] = byte(color.y)
266 ..[to + 2] = byte(color.z)
267 ..[to + 3] = hit == null ? 0 : 255;
268 if (hit == null) continue;
269 final Vector3 point = origin + (-d).scaled(hit.t);
270 // How far along the view the surface is: 0 at the near side of the
271 // sphere, 1 at the far side.
272 final double depth = 0.5 - (point - center).dot(d) / (2.0 * radius);
273 normalDepth
274 ..[to] = byte(hit.normal.x * 0.5 + 0.5)
275 ..[to + 1] = byte(hit.normal.y * 0.5 + 0.5)
276 ..[to + 2] = byte(hit.normal.z * 0.5 + 0.5)
277 ..[to + 3] = byte(depth);
278 }
279 }
280 }
281 }
282 return (albedo: albedo, normalDepth: normalDepth);
285/// The nearest of the trunk and the balls along the ray from [origin] in
286/// [direction], or null when it misses them all.
287_Hit? _cast(
288 Vector3 origin,
289 Vector3 direction,
290 List<_Ball> balls,
291 Aabb3 box,
292 Vector3 bark,
293) {
294 _Hit? nearest;
295 for (final _Ball ball in balls) {
296 final Vector3 oc = origin - ball.center;
297 final double b = oc.dot(direction);
298 final double disc = b * b - (oc.dot(oc) - ball.radius * ball.radius);
299 if (disc < 0.0) continue;
300 final double t = -b - math.sqrt(disc);
301 if (t < 0.0 || (nearest != null && t >= nearest.t)) continue;
302 final Vector3 at = origin + direction.scaled(t);
303 nearest = (
304 t: t,
305 normal: (at - ball.center)..scale(1.0 / ball.radius),
306 color: ball.color,
307 );
308 }
310 // The trunk, by the slab test: the ray enters the box where it has
311 // crossed the near face of all three pairs of faces.
312 var enter = double.negativeInfinity;
313 var leave = double.infinity;
314 var axis = -1;
315 for (var i = 0; i < 3; i++) {
316 if (direction[i].abs() < 1e-9) {
317 if (origin[i] < box.min[i] || origin[i] > box.max[i]) return nearest;
318 continue;
319 }
320 final double a = (box.min[i] - origin[i]) / direction[i];
321 final double b = (box.max[i] - origin[i]) / direction[i];
322 final double near = math.min(a, b);
323 if (near > enter) {
324 enter = near;
325 axis = i;
326 }
327 leave = math.min(leave, math.max(a, b));
328 }
329 if (axis < 0 || enter > leave || enter < 0.0) return nearest;
330 if (nearest != null && enter >= nearest.t) return nearest;
331 final Vector3 normal = Vector3.zero()
332 ..[axis] = direction[axis] > 0.0 ? -1.0 : 1.0;
333 return (t: enter, normal: normal, color: bark);
336/// [mesh] with every vertex colour set to [srgb], converted to the linear
337/// value a vertex colour is authored in.
338MeshData _painted(MeshData mesh, Vector3 srgb) {
339 double linear(double c) =>
340 c <= 0.04045 ? c / 12.92 : math.pow((c + 0.055) / 1.055, 2.4).toDouble();
341 final int stride = mesh.layout.floatsPerVertex;
342 final int at = mesh.layout.floatOffsetOf(VertexLayout.color.name);
343 final Float32List vertices = Float32List.fromList(mesh.vertices);
344 for (var v = 0; v < mesh.vertexCount; v++) {
345 vertices[v * stride + at] = linear(srgb.x);
346 vertices[v * stride + at + 1] = linear(srgb.y);
347 vertices[v * stride + at + 2] = linear(srgb.z);
348 }
349 return MeshData(
350 layout: mesh.layout,
351 vertices: vertices,
352 indices: mesh.indices,
353 );
356/// The furthest any vertex of [mesh] is from [center].
357double _radiusAround(MeshData mesh, Vector3 center) {
358 final int stride = mesh.layout.floatsPerVertex;
359 final int at = mesh.layout.floatOffsetOf(VertexLayout.position.name);
360 return Iterable<int>.generate(mesh.vertexCount).fold(0.0, (
361 double furthest,
362 int v,
363 ) {
364 final int o = v * stride + at;
365 return math.max(
366 furthest,
367 Vector3(
368 mesh.vertices[o] - center.x,
369 mesh.vertices[o + 1] - center.y,
370 mesh.vertices[o + 2] - center.z,
371 ).length,
372 );
373 });