flutter3d
Showcase Changelog 62 packages API reference

Photo mode: the source

since 1.0.0-rc.1 Views, picking and input

Regions the guide quotes: room (line 23), fly (line 172), capture (line 217), whole (line 236), pause (line 276), check (line 344).

1/// Photo mode: the world paused, a free camera held inside the level, a
2/// filter over the game's own look, and a picture of any size drawn in tiles
3/// on the renderer the game already has.
4///
5/// Saving the picture is `savePhoto` and a `PhotoShelf` in `flutter3d_app`,
6/// which write a file; this page keeps the picture in memory and checks it
7/// instead.
8///
9/// Quoted by `photo_mode.md` and shown whole in the Source tab.
10library;
12import 'dart:math' as math;
13import 'dart:typed_data';
15import 'package:flutter/foundation.dart' show visibleForTesting;
16import 'package:flutter3d/flutter3d.dart';
17import 'package:flutter3d_camera/flutter3d_camera.dart' show PhotoCamera;
18import 'package:flutter3d_physics/flutter3d_physics.dart';
19import 'package:flutter3d_showcase/src/demo/demo.dart';
20import 'package:flutter3d_showcase/src/demo/scene_kit.dart';
21import 'package:flutter3d_sim/flutter3d_sim.dart';
23/// A room eight metres square and three high, closed on every side, with a
24/// pillar and a crate in it. The boxes are kept as well as handed to the
25/// collision world, so the check can ask whether a point is inside one
26/// without going through the camera it is checking.
27({CollisionWorld world, List<Aabb3> solids, Aabb3 bounds}) _room() {
28 final world = CollisionWorld();
29 final solids = <Aabb3>[];
30 void box(Vector3 center, Vector3 size) {
31 world.addBox(center, size);
32 solids.add(Aabb3.centerAndHalfExtents(center, size / 2.0));
33 }
35 box(Vector3(0.0, -0.25, 0.0), Vector3(9.0, 0.5, 9.0)); // floor
36 box(Vector3(0.0, 3.25, 0.0), Vector3(9.0, 0.5, 9.0)); // ceiling
37 box(Vector3(4.25, 1.5, 0.0), Vector3(0.5, 3.0, 9.0));
38 box(Vector3(-4.25, 1.5, 0.0), Vector3(0.5, 3.0, 9.0));
39 box(Vector3(0.0, 1.5, 4.25), Vector3(9.0, 3.0, 0.5));
40 box(Vector3(0.0, 1.5, -4.25), Vector3(9.0, 3.0, 0.5));
41 box(Vector3(1.5, 1.5, -1.0), Vector3(1.0, 3.0, 1.0)); // pillar
42 box(Vector3(-1.5, 0.4, 1.0), Vector3.all(0.8)); // crate
43 world.update();
44 return (
45 world: world,
46 solids: solids,
47 bounds: Aabb3.minMax(Vector3(-4.0, 0.0, -4.0), Vector3(4.0, 3.0, 4.0)),
48 );
51/// What the page measured before its first frame.
52final class PhotoReport {
53 /// How many of the 600 random flights the camera made.
54 int moves = 0;
56 /// How many flights ended outside the room or inside a solid; the check
57 /// wants none.
58 int escapes = 0;
60 /// The furthest the camera got from the player, in metres; the check wants
61 /// it within the 5 m reach.
62 double furthest = 0.0;
64 /// The z the photo camera began at, pulled inside the room from the game
65 /// camera behind the far wall.
66 double startZ = 0.0;
68 /// How many tiles across the 640 by 360 picture was drawn in.
69 int tilesX = 0;
71 /// How many tiles down the picture was drawn in.
72 int tilesY = 0;
74 /// How many pixels of the tiled picture were compared with a single render.
75 int pixels = 0;
77 /// How many pixels away from the seams differ from the single render by more
78 /// than 2; the check wants none.
79 int awayFromSeams = 0;
81 /// How many pixels within two of a seam differ by more than 2.
82 int atSeams = 0;
84 /// The largest difference in any channel between the tiled picture and the
85 /// single render, 0 to 255.
86 int worst = 0;
89/// The `photo-mode` page: a photo camera flown inside a room and a picture
90/// drawn in tiles. Its check reads [report].
91final class PhotoModeDemo extends ShowcaseDemo {
92 /// What the page measured before its first frame, read by its check.
93 final PhotoReport report = PhotoReport();
95 final ({CollisionWorld world, List<Aabb3> solids, Aabb3 bounds}) _level =
96 _room();
97 late final Scene _scene;
98 late final MeshNode _spinner;
99 final CameraNode _lens = CameraNode(
100 name: 'photo lens',
101 projection: const PerspectiveProjection(fieldOfView: 0.9),
102 );
104 /// Whether photo mode is on in the viewport.
105 bool photoMode = false;
106 PhotoCamera? _flying;
107 double _clock = 0.0;
108 int _filter = 0;
110 static const RenderSettings _noBloom = RenderSettings(
111 bloom: BloomSettings(enabled: false),
112 );
113 static LinearColor get _clear => LinearColor.fromSrgb(0.05, 0.05, 0.07);
115 @override
116 void configureView(DemoContext context) {
117 context.orbit
118 ..distance = 11.0
119 ..pitch = 0.6
120 ..yaw = 0.5;
121 context.orbit.target.setValues(0.0, 1.0, 0.0);
122 }
124 @override
125 Future<void> prepare(DemoContext context) async {
126 _scene = _build(context);
127 _wander();
128 await _capture(context.renderer);
129 }
131 Scene _build(DemoContext context) {
132 _spinner = blockNode(
133 context,
134 'crate',
135 Vector3.all(0.8),
136 Vector4(0.8, 0.3, 0.2, 1),
137 at: Vector3(-1.5, 0.4, 1.0),
138 );
139 return sceneOf(<SceneNode>[
140 floorNode(context, width: 8.0, depth: 8.0),
141 blockNode(
142 context,
143 'pillar',
144 Vector3(1.0, 3.0, 1.0),
145 Vector4(0.7, 0.62, 0.5, 1),
146 at: Vector3(1.5, 1.5, -1.0),
147 ),
148 _spinner,
149 // The walls are drawn low so the orbit camera can see in; the
150 // collision world has them full height, with a ceiling.
151 for (final (double x, double z, double w, double d)
152 in <(double, double, double, double)>[
153 (4.1, 0.0, 0.2, 8.4),
154 (-4.1, 0.0, 0.2, 8.4),
155 (0.0, 4.1, 8.4, 0.2),
156 (0.0, -4.1, 8.4, 0.2),
157 ])
158 blockNode(
159 context,
160 'wall',
161 Vector3(w, 0.4, d),
162 Vector4(0.55, 0.57, 0.6, 1),
163 at: Vector3(x, 0.2, z),
164 ),
165 _lens,
166 ]);
167 }
169 /// Six hundred random flights from a start whose game camera was left
170 /// outside the room, and how many ended inside a solid or out of bounds.
171 void _wander() {
172 final camera = PhotoCamera(
173 world: _level.world,
174 bounds: _level.bounds,
175 reach: 5.0,
176 );
177 // The game's camera is behind the far wall; the player is inside.
178 camera.begin(
179 eye: Vector3(0.3, 1.5, 9.0),
180 target: Vector3(0.0, 1.0, 0.0),
181 anchor: Vector3(0.0, 1.2, 2.0),
182 );
183 report.startZ = camera.eye.z;
184 final dice = GameRandom(5);
185 for (var i = 0; i < 600; i++) {
186 camera
187 ..look((dice.nextDouble() - 0.5) * 0.6, (dice.nextDouble() - 0.5) * 0.3)
188 ..fly(
189 Vector3(
190 dice.nextDouble() * 6.0 - 3.0,
191 dice.nextDouble() * 6.0 - 3.0,
192 dice.nextDouble() * 6.0 - 3.0,
193 ),
194 0.25,
195 );
196 final Vector3 eye = camera.eye;
197 if (!_level.bounds.containsVector3(eye) ||
198 _level.solids.any((Aabb3 box) => box.containsVector3(eye))) {
199 report.escapes++;
200 }
201 report.moves += 1;
202 report.furthest = math.max(
203 report.furthest,
204 eye.distanceTo(camera.anchor),
205 );
206 }
207 }
209 /// A picture twice the test viewport, in four tiles, against the same
210 /// picture drawn as one frame.
211 Future<void> _capture(Renderer renderer) async {
212 _lens
213 ..setPosition(0.3, 1.5, 3.2)
214 ..lookAt(Vector3(0.0, 1.0, 0.0));
215 const int width = 640;
216 const int height = 360;
217 final picture = Uint8List(width * height * 4);
218 final PhotoCaptureReport made = await capturePhoto(
219 renderer: renderer,
220 scene: _scene,
221 camera: _lens,
222 width: width,
223 height: height,
224 settings: _noBloom,
225 clearColor: _clear,
226 tileWidth: 320,
227 tileHeight: 180,
228 margin: 16,
229 // A row of tiles at a time: a PNG writer would take it from here.
230 onRows: (PhotoRows rows) => picture.setRange(
231 rows.top * width * 4,
232 (rows.top + rows.count) * width * 4,
233 rows.bytes,
234 ),
235 );
236 // The reference: the same picture as one frame, with the settings the
237 // capture says it drew its tiles with.
238 final FrameResult whole = renderer.render(
239 width: width,
240 height: height,
241 scene: _scene,
242 views: <CameraView>[CameraView(camera: _lens, clearColor: _clear)],
243 settings: photoSettings(_noBloom, PhotoFilter.none, made.exposure).tile,
244 );
245 final ByteBuffer read = (await renderer.device.readback(
246 whole.frame,
247 )).buffer;
248 report
249 ..tilesX = made.tilesX
250 ..tilesY = made.tilesY;
251 final Uint8List reference = read.asUint8List();
252 for (var y = 0; y < height; y++) {
253 for (var x = 0; x < width; x++) {
254 var d = 0;
255 for (var c = 0; c < 3; c++) {
256 final int i = (y * width + x) * 4 + c;
257 d = math.max(d, (picture[i] - reference[i]).abs());
258 }
259 report.pixels += 1;
260 report.worst = math.max(report.worst, d);
261 if (d <= 2) continue;
262 if ((x - 320).abs() <= 2 || (y - 180).abs() <= 2) {
263 report.atSeams++;
264 } else {
265 report.awayFromSeams++;
266 }
267 }
268 }
269 }
271 @override
272 Scene build(DemoContext context) => _scene;
274 @override
275 void update(DemoContext context, double dt) {
276 // Photo mode pauses the world whatever the pointer and the pad say,
277 // since both are flying the camera.
278 final bool paused = shouldPause(
279 ready: true,
280 menuOpen: false,
281 pointerIsTheGate: false,
282 pointerHeld: false,
283 padConnected: false,
284 photoMode: photoMode,
285 );
286 if (!paused) {
287 _clock += dt;
288 _spinner.setRotation(Quaternion.axisAngle(Vector3(0, 1, 0), _clock));
289 }
290 final PhotoCamera? camera = _flying;
291 if (!photoMode || camera == null) return;
292 // A slow loop that keeps pushing into the walls, to show it stopping.
293 camera
294 ..look(0.25 * dt, 0.0)
295 ..fly(Vector3(0.0, 0.3 * math.sin(_clock * 0.5), 1.0), dt);
296 context.camera
297 ..setPositionFrom(camera.eye)
298 ..lookAt(camera.target, up: camera.up);
299 }
301 void _enter(DemoContext context, bool on) {
302 photoMode = on;
303 if (!on) {
304 _flying = null;
305 context.orbit.apply();
306 return;
307 }
308 // Started from wherever the orbit camera is, which is outside the room:
309 // the sweep out from the anchor stops it at the wall.
310 _flying =
311 PhotoCamera(world: _level.world, bounds: _level.bounds, reach: 5.0)
312 ..begin(
313 eye: context.camera.readScenePosition(),
314 target: context.orbit.target,
315 anchor: Vector3(0.0, 1.2, 0.0),
316 );
317 }
319 @override
320 RenderSettings settings(DemoContext context) => photoMode
321 ? RenderSettings(
322 look: PhotoFilter.all[_filter].applyTo(const LookSettings()),
323 )
324 : const RenderSettings();
326 @override
327 List<DemoControl> controls(DemoContext context) => <DemoControl>[
328 ToggleControl(
329 'Photo mode',
330 value: () => photoMode,
331 onChanged: (bool v) => _enter(context, v),
332 ),
333 ChoiceControl(
334 'Filter',
335 options: <String>[for (final PhotoFilter f in PhotoFilter.all) f.name],
336 index: () => _filter,
337 onChanged: (int i) => _filter = i,
338 ),
339 ];
341 /// The page's claim, as the first thing that is not so, or null.
342 @visibleForTesting
343 String? wrong() {
344 if (report.moves != 600 || report.escapes != 0) {
345 return '${report.escapes} of ${report.moves} flights left the room';
346 }
347 if (report.furthest > 5.0 + 1e-3) {
348 return 'the camera got ${report.furthest} m from the player on a 5 m '
349 'tether';
350 }
351 // Begun from behind the wall at z = 4.25: the start is in front of it.
352 if (report.startZ > 4.0) return 'the photo began at z ${report.startZ}';
353 if (report.tilesX != 2 || report.tilesY != 2) {
354 return 'the capture drew ${report.tilesX} by ${report.tilesY} tiles';
355 }
356 // Every pixel more than two steps off the single frame has to sit on a
357 // seam between tiles; away from the seams the picture is the frame.
358 if (report.pixels != 640 * 360 || report.awayFromSeams != 0) {
359 return '${report.awayFromSeams} pixels away from the seams differ';
360 }
361 return null;
362 }
364 @override
365 void verify(Scene scene, FrameResult frame) {
366 if (frame.drawCalls < 1) throw StateError('nothing reached the frame');
367 final String? problem = wrong();
368 if (problem != null) throw StateError(problem);
369 }