flutter3d
Showcase Changelog 62 packages API reference

Reconciling an orthographic camera and a Flame viewfinder: the source

since 0.7.0 The Flame bridge

Regions the guide quotes: live (line 141), drive (line 191), cameras (line 222), scene-to-flame (line 229), flame-to-scene (line 241).

1/// `CameraSyncController` reconciling an orthographic flutter3d `CameraNode`
2/// and a Flame `Viewfinder`, in both `SyncDirection`s.
3///
4/// Quoted by `flame_camera_bridge.md` and shown whole in the Source tab.
5library;
6
7import 'dart:math' as math;
8
9import 'package:flame/camera.dart';
10import 'package:flame/components.dart' show Anchor, CircleComponent, Component;
11import 'package:flame_flutter3d/flame_flutter3d.dart';
12import 'package:flutter/widgets.dart';
13import 'package:flutter3d/flutter3d.dart';
14import 'package:flutter3d_showcase/src/demo/demo.dart';
15import 'package:flutter3d_showcase/src/demo/flame_layer.dart';
17/// The `flame-camera-bridge` page: an orthographic lens over a floor of
18/// pillars, synced with a Flame viewfinder. Its check drives the sync both
19/// ways: the viewfinder follows the camera to x = 3 with zoom 1 / height, and
20/// the camera follows the viewfinder to x = 1 with height 1 / zoom.
21final class FlameCameraBridgeDemo extends ShowcaseDemo {
22 late final String _report;
23 late final double _viewfinderX;
24 late final double _viewfinderZoom;
25 late final double _cameraX;
26 late final double _orthoHeight;
28 /// Which side leads on the page: 0 the flutter3d camera, 1 the viewfinder.
29 int _leader = 0;
31 late final CameraNode _lens;
32 late final CameraView _view;
33 late final Scene _scene;
34 late final TransparentFlameGame _game;
35 late final CameraSyncController _sceneLeads;
36 late final CameraSyncController _flameLeads;
37 late final DemoContext _context;
38 late final Widget _body = Flutter3dFlameWidget(
39 game: _game,
40 camera: _lens,
41 existing: BorrowedRenderer(
42 device: _context.device,
43 renderer: _context.renderer,
44 ),
45 buildScene: (GraphicsDevice device) => _scene,
46 );
47 double _clock = 0.0;
49 /// Where the pillars stand, on the ground, in metres.
50 static const List<(double, double)> _pillars = <(double, double)>[
51 (-3.0, -3.0),
52 (0.0, -3.0),
53 (3.0, -3.0),
54 (-3.0, 0.0),
55 (0.0, 0.0),
56 (3.0, 0.0),
57 (-3.0, 3.0),
58 (0.0, 3.0),
59 (3.0, 3.0),
60 ];
62 /// Where the camera stands above the ground.
63 static const double _eyeHeight = 6.0;
65 @override
66 List<CameraView> views(DemoContext context) => <CameraView>[_view];
68 @override
69 Scene build(DemoContext context) {
70 _context = context;
71 final (
72 String report,
73 double viewfinderX,
74 double viewfinderZoom,
75 double cameraX,
76 double orthoHeight,
77 ) = _run();
78 _report = report;
79 _viewfinderX = viewfinderX;
80 _viewfinderZoom = viewfinderZoom;
81 _cameraX = cameraX;
82 _orthoHeight = orthoHeight;
84 _lens =
85 CameraNode(
86 name: 'bridged-lens',
87 projection: const OrthographicProjection(height: 9.0),
88 )
89 ..setPosition(0.0, _eyeHeight, 0.0)
90 // Straight down, with -z at the top of the picture: Flame's y grows
91 // downwards and the plane maps it to z, so the two agree on which way
92 // is up.
93 ..lookAt(Vector3.zero(), up: Vector3(0.0, 0.0, -1.0));
94 _view = CameraView(
95 camera: _lens,
96 clearColor: LinearColor.fromSrgb(0.05, 0.05, 0.07, 1.0),
97 );
99 _scene = Scene()
100 ..ambientColor = LinearColor(0.5, 0.55, 0.65)
101 ..ambientIntensity = 0.35 * LightNode.legacyUnit
102 ..add(_lens)
103 ..add(
104 MeshNode(
105 DeviceMesh.upload(
106 context.device,
107 CuboidShape(size: Vector3(40.0, 0.1, 40.0)).build(),
108 ),
109 RenderMaterial(
110 name: 'floor',
111 baseColor: LinearColor.fromSrgb(0.3, 0.33, 0.32, 1.0),
112 ),
113 name: 'floor',
114 )..setPosition(0.0, -0.05, 0.0),
115 )
116 ..add(
117 LightNode(name: 'sun', intensity: 2.5 * LightNode.legacyUnit)
118 ..setLocalForward(Vector3(-0.3, -1.0, -0.4)),
119 );
120 for (final (int i, (double, double) at) in _pillars.indexed) {
121 _scene.add(
122 MeshNode(
123 DeviceMesh.upload(
124 context.device,
125 CuboidShape(size: Vector3(0.6, 0.4 + 0.15 * (i % 4), 0.6)).build(),
126 ),
127 RenderMaterial(
128 name: 'pillar $i',
129 baseColor: LinearColor.fromSrgb(
130 0.55 + 0.4 * math.sin(i * 0.9),
131 0.5 + 0.3 * math.sin(i * 1.7 + 1.0),
132 0.4 + 0.3 * math.sin(i * 2.3 + 2.0),
133 1.0,
134 ),
135 ),
136 name: 'pillar $i',
137 )..setPosition(at.$1, 0.2 + 0.075 * (i % 4), at.$2),
138 );
139 }
141 // One plane for both, at the camera's own height: the controller writes
142 // the camera's position through it when Flame leads, and a plane at zero
143 // would put the lens on the floor.
144 final BridgePlane plane = BridgePlane.ground(height: _eyeHeight);
145 _game = TransparentFlameGame();
146 final Viewfinder viewfinder = _game.camera.viewfinder;
147 _sceneLeads = CameraSyncController(
148 camera: _lens,
149 viewfinder: viewfinder,
150 plane: plane,
151 );
152 _flameLeads = CameraSyncController(
153 camera: _lens,
154 viewfinder: viewfinder,
155 plane: plane,
156 direction: SyncDirection.flameToScene,
157 );
158 // Flame's own picture of the same ground: a ring round every pillar, in
159 // metres, seen through the viewfinder the controller is keeping in step.
160 for (final (double, double) at in _pillars) {
161 _game.world.add(
162 CircleComponent(
163 radius: 0.55,
164 position: Vector2(at.$1, at.$2),
165 anchor: Anchor.center,
166 paint: Paint()
167 ..color = const Color(0xFFFFD866)
168 ..style = PaintingStyle.stroke
169 ..strokeWidth = 0.05,
170 ),
171 );
172 }
173 _game
174 ..add(_Drive(this))
175 ..add(
176 flameCaption('yellow rings: Flame\'s world, through its viewfinder'),
177 )
178 ..add(flameCaption(_report, at: Vector2(16.0, 40.0)));
179 return _scene;
180 }
182 /// The half of the frame a page's own logic owns: whichever side leads
183 /// moves, then the controller carries it over, then the Flame zoom is
184 /// scaled from "one over the height" to pixels to the metre.
185 void _drive(double dt) {
186 _clock += dt;
187 final double x = 1.8 * math.sin(_clock * 0.5);
188 final double z = 1.2 * math.sin(_clock * 0.9);
189 final double height = 9.0 + 2.0 * math.sin(_clock * 0.7);
190 final Viewfinder viewfinder = _game.camera.viewfinder;
191 if (_leader == 0) {
192 // flutter3d leads: the camera moves and the viewfinder is told.
193 _lens
194 ..setPosition(x, _eyeHeight, z)
195 ..projection = OrthographicProjection(height: height);
196 _sceneLeads.update(dt);
197 } else {
198 // Flame leads: the viewfinder moves and the camera is told.
199 viewfinder
200 ..position = Vector2(x, z)
201 ..zoom = 1.0 / height;
202 _flameLeads.update(dt);
203 }
204 // The controller's zoom is one over the height, which is not a size on
205 // screen. Turning it into pixels to the metre is the caller's step: the
206 // game is as many pixels high as the picture under it.
207 final double pixelsHigh = _game.size.y;
208 if (pixelsHigh > 0.0) viewfinder.zoom = pixelsHigh * viewfinder.zoom;
209 }
211 @override
212 List<DemoControl> controls(DemoContext context) => <DemoControl>[
213 ChoiceControl(
214 'Who leads',
215 options: const <String>['flutter3d camera', 'Flame viewfinder'],
216 index: () => _leader,
217 onChanged: (int i) => _leader = i,
218 ),
219 ];
221 static (String, double, double, double, double) _run() {
222 final camera = CameraNode(
223 name: 'bridged-camera',
224 projection: const OrthographicProjection(height: 4.0),
225 );
226 final viewfinder = Viewfinder();
227 final plane = BridgePlane.ground();
229 // The flutter3d camera is authoritative; `advance` copies its position
230 // and its orthographic height onto the Flame viewfinder.
231 final sceneToFlame = CameraSyncController(
232 camera: camera,
233 viewfinder: viewfinder,
234 plane: plane,
235 );
236 camera.setPosition(3.0, 0.0, 2.0);
237 sceneToFlame.update(1 / 60);
238 final double viewfinderX = viewfinder.position.x;
239 final double viewfinderZoom = viewfinder.zoom;
241 // The Flame viewfinder is authoritative instead; `advance` copies its
242 // position and its zoom onto the flutter3d camera's projection.
243 final flameToScene = CameraSyncController(
244 camera: camera,
245 viewfinder: viewfinder,
246 plane: plane,
247 direction: SyncDirection.flameToScene,
248 );
249 viewfinder.position = Vector2(1.0, -1.0);
250 viewfinder.zoom = 0.5;
251 flameToScene.update(1 / 60);
252 final double cameraX = camera.readPosition().x;
253 final double orthoHeight =
254 (camera.projection as OrthographicProjection).height;
256 return (
257 'flutter3d led: Flame position=($viewfinderX, _), zoom=$viewfinderZoom; '
258 'Flame led: flutter3d x=$cameraX, height=$orthoHeight',
259 viewfinderX,
260 viewfinderZoom,
261 cameraX,
262 orthoHeight,
263 );
264 }
266 /// The Flame game the page runs, for a test that steps it without a window.
267 @visibleForTesting
268 TransparentFlameGame get game => _game;
270 @override
271 Widget? customBody(BuildContext buildContext, DemoContext context) => _body;
273 @override
274 void verify(Scene scene, FrameResult frame) {
275 if (frame.drawCalls < 1) {
276 throw StateError('the marker was not drawn');
277 }
278 // Compared as numbers, not read back out of `_report`: see
279 // `sim_audio_xr/actors.dart` for why.
280 if (_viewfinderX != 3.0) {
281 throw StateError(
282 'the viewfinder should have followed the camera to x=3, got '
283 '$_viewfinderX',
284 );
285 }
286 if (_viewfinderZoom != 0.25) {
287 throw StateError(
288 'zoom = 1 / height should read 0.25 for a height-4 lens, got '
289 '$_viewfinderZoom',
290 );
291 }
292 if (_cameraX != 1.0) {
293 throw StateError(
294 'the flutter3d camera should have followed the viewfinder to x=1, '
295 'got $_cameraX',
296 );
297 }
298 if (_orthoHeight != 2.0) {
299 throw StateError(
300 'height = 1 / zoom should read 2.0 for zoom 0.5, got $_orthoHeight',
301 );
302 }
303 }
306/// Calls the page's own step once a Flame frame, before the bridge clock.
307final class _Drive extends Component {
308 _Drive(this._page);
310 final FlameCameraBridgeDemo _page;
312 @override
313 void update(double dt) {
314 super.update(dt);
315 _page._drive(dt);
316 }