Occlusion culling: the source
Open the live demo · Read the guide · View on GitHub
Regions the guide quotes: wall (line 79), crates (line 94), lookout (line 116), probe (line 150), settings (line 171), check (line 199).
1/// A wall marked as an occluder, a yard of crates behind it, and a lookout in
2/// front: the crates the lookout cannot see are the ones occlusion culling
3/// leaves out.
4///
5/// Quoted by `occlusion_culling.md` and shown whole in the Source tab.
6library;
8import 'dart:math' as math;
10import 'package:flutter3d/flutter3d.dart';
11import 'package:flutter3d_showcase/src/demo/demo.dart';
13/// The `occlusion-culling` page: a wall in front of a yard of crates, seen
14/// from a lookout. Its check is that the wall reached the occlusion buffer
15/// and hid some crates from the lookout but not all.
16final class OcclusionCullingDemo extends ShowcaseDemo {
17 /// The wall's x, in metres, -2.5 to 2.5: sliding it changes which crates it
18 /// hides.
19 double wallX = 0.0;
21 /// Whether the wall is marked an occluder; off, it hides nothing from the
22 /// culling.
23 bool wallOccludes = true;
25 /// How this view culls: 0 none, 1 software, 2 hiZ.
26 int mode = 1;
28 static const List<OcclusionMode> _modes = <OcclusionMode>[
29 OcclusionMode.none,
30 OcclusionMode.software,
31 OcclusionMode.hiZ,
32 ];
34 /// The lookout's picture is wider than it is tall, like the 256 by 128
35 /// buffer the software test draws into.
36 static const double _lookoutAspect = 2.0;
38 late final MeshNode _wall;
39 late final List<MeshNode> _crates;
40 late final CameraNode _lookout;
41 late final RenderMaterial _seen;
42 late final RenderMaterial _hidden;
44 final SoftwareOcclusion _probe = SoftwareOcclusion();
45 int _hiddenCount = 0;
48 void configureView(DemoContext context) {
49 context.orbit
50 ..distance = 11.0
51 ..pitch = 0.75
52 ..yaw = 0.35;
53 }
56 Scene build(DemoContext context) {
57 final Scene scene = Scene()
58 ..ambientColor = LinearColor(0.42, 0.48, 0.6)
59 ..ambientIntensity = 0.18 * LightNode.legacyUnit
60 ..add(
61 MeshNode(
62 DeviceMesh.upload(
63 context.device,
64 const PlaneShape(width: 10, depth: 10).build(),
65 ),
66 RenderMaterial(
67 name: 'yard',
68 baseColor: LinearColor.fromSrgb(0.5, 0.5, 0.48, 1.0),
69 roughness: 0.9,
70 ),
71 name: 'ground',
72 )..setPosition(0.0, 0.0, -0.5),
73 )
74 ..add(
75 LightNode(name: 'sun', intensity: 3.0 * LightNode.legacyUnit)
76 ..setLocalForward(Vector3(-0.4, -0.8, -0.45)),
77 );
79 _wall = MeshNode(
80 DeviceMesh.upload(
81 context.device,
82 CuboidShape(size: Vector3(2.6, 1.6, 0.15)).build(),
83 ),
84 RenderMaterial(
85 name: 'wall',
86 baseColor: LinearColor.fromSrgb(0.36, 0.42, 0.5, 1.0),
87 roughness: 0.8,
88 ),
89 name: 'wall',
90 )..setPosition(0.0, 0.8, 1.5);
91 _wall.occluder = true;
92 scene.add(_wall);
94 _seen = RenderMaterial(
95 name: 'seen',
96 baseColor: LinearColor.fromSrgb(0.92, 0.55, 0.2, 1.0),
97 roughness: 0.6,
98 );
99 _hidden = RenderMaterial(
100 name: 'hidden',
101 baseColor: LinearColor.fromSrgb(0.22, 0.22, 0.24, 1.0),
102 roughness: 0.6,
103 );
104 final DeviceMesh crate = DeviceMesh.upload(
105 context.device,
106 CuboidShape(size: Vector3.all(0.5)).build(),
107 );
108 _crates = <MeshNode>[
109 for (var row = 0; row < 3; row++)
110 for (var column = 0; column < 5; column++)
111 MeshNode(crate, _seen, name: 'crate $row.$column')
112 ..setPosition((column - 2) * 1.2, 0.25, -0.5 - row * 1.0),
113 ];
114 _crates.forEach(scene.add);
116 _lookout =
117 CameraNode(
118 name: 'lookout',
119 projection: const PerspectiveProjection(
120 fieldOfView: 60 * math.pi / 180,
121 near: 0.1,
122 far: 30.0,
123 ),
124 )
125 ..setPosition(0.0, 1.0, 4.0)
126 ..lookAt(Vector3(0.0, 0.6, -1.0));
127 scene.add(
128 MeshNode(
129 DeviceMesh.upload(
130 context.device,
131 SphereShape(radius: 0.15, segments: 16, rings: 8).build(),
132 ),
133 RenderMaterial(
134 name: 'lookout marker',
135 baseColor: LinearColor.fromSrgb(0.3, 0.8, 0.95, 1.0),
136 roughness: 0.4,
137 ),
138 name: 'lookout marker',
139 )..setPosition(0.0, 1.0, 4.0),
140 );
141 return scene;
142 }
145 void update(DemoContext context, double dt) {
146 _wall
147 ..setPosition(wallX, 0.8, 1.5)
148 ..occluder = wallOccludes;
150 final Matrix4 viewProjection = _lookout.viewProjection(_lookoutAspect);
151 final OcclusionTest test = _probe.prepare(
152 meshes: <MeshNode>[_wall, ..._crates],
153 viewProjection: viewProjection,
154 frustum: Frustum.matrix(viewProjection),
155 eye: _lookout.readScenePosition(),
156 layerMask: RenderLayers.all,
157 );
158 var hidden = 0;
159 for (final MeshNode crate in _crates) {
160 final bool visible = test.mayBeVisible(
161 OcclusionQueryContext(bounds: crate.sceneBounds),
162 );
163 crate.material = visible ? _seen : _hidden;
164 if (!visible) hidden++;
165 }
166 _hiddenCount = hidden;
167 }
170 RenderSettings settings(DemoContext context) => RenderSettings(
171 occlusion: _modes[mode],
172 );
175 List<DemoControl> controls(DemoContext context) => <DemoControl>[
176 SliderControl(
177 'Wall position',
178 min: -2.5,
179 max: 2.5,
180 value: () => wallX,
181 onChanged: (double v) => wallX = v,
182 format: (double v) => '${v.toStringAsFixed(2)} m',
183 ),
184 ToggleControl(
185 'Wall is an occluder',
186 value: () => wallOccludes,
187 onChanged: (bool v) => wallOccludes = v,
188 ),
189 ChoiceControl(
190 'This view culls with',
191 options: const <String>['none', 'software', 'hiZ'],
192 index: () => mode,
193 onChanged: (int i) => mode = i,
194 ),
195 ];
198 void verify(Scene scene, FrameResult frame) {
199 if (_probe.occluders != 1) {
200 throw StateError('the wall was not drawn into the occlusion buffer');
201 }
202 if (_hiddenCount == 0 || _hiddenCount == _crates.length) {
203 throw StateError(
204 'the wall should hide some crates from the lookout and not all of '
205 'them; it hid $_hiddenCount of ${_crates.length}',
206 );
207 }
208 if (frame.drawCalls < 1) {
209 throw StateError('the yard did not reach the frame');
210 }
211 }
212}