Inspecting a running frame: the source
Open the live demo · Read the guide · View on GitHub
Regions the guide quotes: look (line 90), probe (line 111), report (line 150), check (line 183).
1/// What a tool attached to a running game sees of its frame: the passes,
2/// the draws, one pixel, the totals, and which node drew the pixel under a
3/// point — worked out of one captured frame by the plain functions the VM
4/// service extensions answer with.
5///
6/// Quoted by `render_inspection.md` and shown whole in the Source tab.
7library;
9import 'package:flutter3d/flutter3d.dart';
10import 'package:flutter3d_app/flutter3d_app.dart';
11import 'package:flutter3d_showcase/src/demo/demo.dart';
13/// What one look at a frame found.
14final class _Look {
15 const _Look(this.capture, this.node, this.x, this.y);
17 final FrameCapture capture;
19 /// The node drawn at ([x], [y]), or null for the clear colour.
20 final MeshNode? node;
21 final int x;
22 final int y;
23}
25/// The `render-inspection` page: a captured frame read by the functions the
26/// VM service extensions answer with. Its check is that the middle pixel
27/// picks the crate, a draw is the crate's, and the pixel reads back.
28final class RenderInspectionDemo extends ShowcaseDemo {
29 late final Scene _scene;
31 /// The probe frame [verify] reads, taken before the page is shown.
32 late final _Look _probe;
34 /// The latest look at the page's own frames, refreshed while it runs.
35 _Look? _live;
36 bool _looking = false;
37 double _sinceLook = 0.0;
39 static const int _probeWidth = 96;
40 static const int _probeHeight = 64;
43 void configureView(DemoContext context) {
44 context.orbit
45 ..distance = 5.0
46 ..pitch = 0.35
47 ..yaw = 0.0;
48 }
50 Scene _build(GraphicsDevice device) {
51 MeshNode mesh(String name, MeshData data, Vector4 color) => MeshNode(
52 DeviceMesh.upload(device, data),
53 RenderMaterial(
54 name: '$name paint',
55 baseColor: _fromSrgb(color),
56 roughness: 0.6,
57 ),
58 name: name,
59 );
60 return Scene()
61 ..ambientColor = LinearColor(0.5, 0.55, 0.65)
62 ..ambientIntensity = 0.25 * LightNode.legacyUnit
63 ..add(
64 LightNode(name: 'sun', intensity: 2.5 * LightNode.legacyUnit)
65 ..setLocalForward(Vector3(-0.3, -0.8, -0.4)),
66 )
67 ..add(
68 mesh(
69 'floor',
70 CuboidShape(size: Vector3(5.0, 0.2, 3.0)).build(),
71 Vector4(0.4, 0.42, 0.45, 1.0),
72 )..setPosition(0.0, -0.6, 0.0),
73 )
74 ..add(
75 mesh(
76 'crate',
77 CuboidShape(size: Vector3.all(1.0)).build(),
78 Vector4(0.85, 0.45, 0.15, 1.0),
79 ),
80 )
81 ..add(
82 mesh(
83 'barrel',
84 SphereShape(radius: 0.45, segments: 32, rings: 16).build(),
85 Vector4(0.2, 0.45, 0.85, 1.0),
86 )..setPosition(1.5, -0.05, 0.3),
87 );
88 }
90 /// Asks the renderer for the next frame twice over: its passes and its
91 /// draws, journaled, and the node drawn at ([u], [v]), fractions of the
92 /// frame from the top left. Both are answered by the same frame, so a draw
93 /// index means the frame the pixel is from.
94 static Future<_Look> _lookAt(Renderer renderer, double u, double v) async {
95 final Future<FrameCapture> captured = renderer.captureNextFrame(
96 draws: true,
97 );
98 final Future<MeshNode?> node = renderer.pickPixel(u, v);
99 final FrameCapture capture = await captured;
100 return _Look(
101 capture,
102 await node,
103 (u * capture.width).floor(),
104 (v * capture.height).floor(),
105 );
106 }
109 Future<void> prepare(DemoContext context) async {
110 _scene = _build(context.device);
111 final CameraNode eye =
112 CameraNode(projection: const PerspectiveProjection(fieldOfView: 0.8))
113 ..setPosition(0.0, 0.8, 4.0)
114 ..lookAt(Vector3.zero());
115 _scene.add(eye);
116 // The middle of the pixel in the middle, so the pick and the pixel read
117 // are the same one.
118 final Future<_Look> look = _lookAt(
119 context.renderer,
120 (_probeWidth ~/ 2 + 0.5) / _probeWidth,
121 (_probeHeight ~/ 2 + 0.5) / _probeHeight,
122 );
123 context.renderer.render(
124 width: _probeWidth,
125 height: _probeHeight,
126 scene: _scene,
127 views: <CameraView>[CameraView(camera: eye)],
128 );
129 _probe = await look;
130 eye.removeFromParent();
131 }
134 Scene build(DemoContext context) => _scene;
137 void update(DemoContext context, double dt) {
138 // Once a second, ask about the frame the viewport is about to draw, at
139 // its middle.
140 _sinceLook += dt;
141 if (_looking || _sinceLook < 1.0) return;
142 _looking = true;
143 _sinceLook = 0.0;
144 _lookAt(context.renderer, 0.5, 0.5).then((_Look look) {
145 _live = look;
146 _looking = false;
147 });
148 }
150 /// What an agent reads back: the passes in order with their draw counts,
151 /// and the node under the middle with the draws it made.
152 static String _report(_Look look) {
153 final List<Object?> passes =
154 renderPasses(look.capture)['passes']! as List<Object?>;
155 final String ran = <String>[
156 for (final Object? pass in passes)
157 if (pass case {'name': final String name, 'drawCalls': final int n})
158 '$name ($n)',
159 ].join(', ');
160 final Map<String, Object?> picked = renderPicked(
161 look.capture,
162 look.node,
163 x: look.x,
164 y: look.y,
165 );
166 final Map<String, Object?> stats = renderStats(look.capture);
167 return 'passes: $ran. Under the middle: ${picked['node'] ?? 'nothing'}, '
168 'draws ${picked['draws']}. ${stats['drawCalls']} draws, '
169 '${stats['triangles']} triangles in all';
170 }
173 List<DemoControl> controls(DemoContext context) => <DemoControl>[
174 ToggleControl(
175 _report(_live ?? _probe),
176 value: () => false,
177 onChanged: (bool v) => _sinceLook = 1.0,
178 ),
179 ];
182 void verify(Scene scene, FrameResult frame) {
183 final FrameCapture capture = _probe.capture;
184 final Map<String, Object?> picked = renderPicked(
185 capture,
186 _probe.node,
187 x: _probe.x,
188 y: _probe.y,
189 );
190 if (picked['node'] != 'crate') {
191 throw StateError('the middle of the frame is ${picked['node']}');
192 }
193 final List<int> draws = (picked['draws']! as List<Object?>).cast<int>();
194 if (draws.isEmpty) throw StateError('the crate made no draw that frame');
195 // The draw it made, opened as a tool opens one, names the crate and the
196 // pass it ran in; that pass's output, read at the same pixel, is the
197 // crate's orange and not the barrel's blue.
198 final Map<String, Object?> draw = renderDraw(capture, <String, String>{
199 'index': '${draws.first}',
200 });
201 if (isRefusal(draw) || draw['mesh'] != 'crate') {
202 throw StateError('draw ${draws.first} is not the crate: $draw');
203 }
204 final Map<String, Object?> pixel = renderReadPixel(
205 capture,
206 <String, String>{
207 'pass': '${draw['pass']}',
208 'x': '${_probe.x}',
209 'y': '${_probe.y}',
210 },
211 );
212 final List<Object?>? value =
213 (pixel['float'] ?? pixel['unorm']) as List<Object?>?;
214 if (isRefusal(pixel) || value == null) {
215 throw StateError('the pixel could not be read: $pixel');
216 }
217 final double red = (value[0]! as num).toDouble();
218 final double blue = (value[2]! as num).toDouble();
219 if (red <= blue) {
220 throw StateError('the pixel the crate drew reads $value');
221 }
222 if ((renderStats(capture)['describedDraws']! as int) < 3) {
223 throw StateError('the journal missed some of the three meshes');
224 }
225 if (frame.drawCalls < 1) throw StateError('nothing reached the frame');
226 }
227}
229/// A `Vector4` holding a colour sRGB-encoded, as the linear colour it names.
230LinearColor _fromSrgb(Vector4 c) => LinearColor.fromSrgb(c.x, c.y, c.z, c.w);