flutter3d
Showcase Changelog 62 packages API reference

A material of your own: the source

since 1.0.0-rc.1 Shading and materials

Regions the guide quotes: source (line 25), compile (line 85), bind (line 110), instances (line 168), uniform (line 204), check (line 234).

1/// A material written by the game in the engine's language: a `uniform` the
2/// game sets, a `light` block that cuts the light into bands, and four
3/// numbers per copy read as `instance`, drawn on three spheres of one
4/// instanced batch.
5///
6/// Quoted by `user_materials.md` and shown whole in the Source tab.
7library;
8
9import 'dart:typed_data';
11import 'package:flutter/services.dart' show rootBundle;
12import 'package:flutter3d/flutter3d.dart';
13import 'package:flutter3d_app/software.dart' show materialLanguageCompiler;
14import 'package:flutter3d_cpu/flutter3d_cpu.dart'
15 show CpuDevice, CpuLoadedShaderLibrary;
16import 'package:flutter3d_hardware/flutter3d_hardware.dart'
17 show decodeMaterialSection;
18import 'package:flutter3d_showcase/src/demo/demo.dart';
20/// The `user-materials` page: three toon spheres of one instanced batch
21/// drawn by a material in the engine's language. Its check is that the bundle
22/// came from the page's source, each copy reads its own colour, and the
23/// shading falls into at most five shades.
24final class UserMaterialsDemo extends ShowcaseDemo {
25 /// The `.f3dmat` this page draws. `user_materials.f3dshaders` beside this
26 /// file is what `compileMaterial` makes of it, and carries this text in it;
27 /// built, not committed.
28 static const String source = '''
29material ToonInstances {
30 param float bands = 3.0;
31 uniform vec3 paint = vec3(1.0, 1.0, 1.0);
33 light {
34 let banded = floor(nDotL * bands + 0.5) / bands;
35 return albedo * paint * banded / max(nDotL, 0.001);
36 }
38 fragment {
39 let rim = pow(1.0 - clamp(nDotV, 0.0, 1.0), 4.0) * instance.w;
40 return vec4(lit * instance.rgb + vec3(rim), 1.0);
41 }
43''';
45 static const String _name = 'ToonInstances';
47 /// Where the bundle compiled from [source] sits, as an asset key: built,
48 /// not committed (see `user_materials.md`).
49 static const String bundlePath =
50 'lib/pages/shading/user_materials.f3dshaders';
52 /// Each copy's own four numbers: a colour, and how strongly its rim glows.
53 static const List<(double, double, double, double)> _numbers =
54 <(double, double, double, double)>[
55 (0.95, 0.3, 0.2, 0.0),
56 (0.3, 0.85, 0.35, 0.6),
57 (0.3, 0.5, 0.95, 1.2),
58 ];
60 static const int _probeWidth = 160;
61 static const int _probeHeight = 80;
63 late final ByteData _bytes;
64 late final RenderMaterial _toon;
66 /// How the stage reached this device, or why it did not.
67 String _how = '';
68 bool _drawn = false;
70 /// The probe frame [verify] reads, and where each copy's centre is in it.
71 late final Uint8List _probe;
72 late final List<(int, int)> _centers;
73 late final int _radius;
75 double _warmth = 0.0;
77 @override
78 void configureView(DemoContext context) {
79 context.orbit
80 ..distance = 5.0
81 ..pitch = 0.15
82 ..yaw = 0.0;
83 }
85 /// The bundle on [device]: the GPU sections where there is a GPU, and the
86 /// source compiled into a Dart stage on the software rasteriser.
87 Future<LoadedShaderLibrary> _load(GraphicsDevice device) async {
88 try {
89 final LoadedShaderLibrary library = await device.loadShaders(_bytes);
90 _how = 'loaded from the bundle';
91 return library;
92 } on ShaderBundleException {
93 // A software device opened without a material compiler refuses the
94 // source; this one is given the compiler `openDevice` would give it.
95 if (device case final CpuDevice cpu when cpu.materialCompiler == null) {
96 _how = 'compiled from the source on the software rasteriser';
97 return CpuLoadedShaderLibrary.load(
98 cpu.shaders,
99 _bytes,
100 compiler: materialLanguageCompiler,
101 );
102 }
103 rethrow;
104 }
105 }
107 @override
108 Future<void> prepare(DemoContext context) async {
109 _bytes = await rootBundle.load(bundlePath);
110 final BundledMaterials materials = BundledMaterials.read(_bytes);
111 _toon = RenderMaterial(
112 name: 'toon',
113 lighting: materials[_name],
114 // `paint` at its default, in a list of the material's own.
115 parameters: materials.parameters(_name),
116 );
117 try {
118 context.renderer.renderSteps.addMaterials(await _load(context.device));
119 _drawn = true;
120 } on ShaderBundleException catch (refusal) {
121 _how = 'not drawn here: ${refusal.reason}';
122 _toon.lighting = LightingModel.toon;
123 }
125 final CameraNode eye =
126 CameraNode(projection: const PerspectiveProjection(fieldOfView: 0.7))
127 ..setPosition(0.0, 0.0, 5.0)
128 ..lookAt(Vector3.zero());
129 final Scene probe = _scene(context.device)..add(eye);
130 final FrameResult frame = context.renderer.render(
131 width: _probeWidth,
132 height: _probeHeight,
133 scene: probe,
134 views: <CameraView>[
135 CameraView(
136 camera: eye,
137 clearColor: LinearColor.fromSrgb(0.0, 0.0, 0.0, 1.0),
138 ),
139 ],
140 // No dither and no bloom, so a band is one value from edge to edge.
141 settings: const RenderSettings(
142 bloom: BloomSettings(enabled: false),
143 look: LookSettings(dither: 0.0),
144 ),
145 );
146 final ByteData read = await context.device.readback(frame.frame);
147 _probe = read.buffer.asUint8List(read.offsetInBytes, read.lengthInBytes);
148 final Matrix4 vp = eye.viewProjection(_probeWidth / _probeHeight);
149 _centers = <(int, int)>[
150 for (var i = 0; i < _numbers.length; i++)
151 _pixelOf(vp, Vector3(_x(i), 0, 0)),
152 ];
153 _radius = _pixelOf(vp, Vector3(_x(0) + 0.5, 0, 0)).$1 - _centers[0].$1;
154 }
156 static double _x(int i) => (i - 1) * 1.3;
158 static (int, int) _pixelOf(Matrix4 vp, Vector3 world) {
159 final Vector4 clip = vp.transformed(
160 Vector4(world.x, world.y, world.z, 1.0),
161 );
162 return (
163 ((clip.x / clip.w + 1.0) * 0.5 * _probeWidth).floor(),
164 ((1.0 - clip.y / clip.w) * 0.5 * _probeHeight).floor(),
165 );
166 }
168 /// One batch, one draw: the copies differ only in the numbers given each.
169 InstancedMeshNode _batch(GraphicsDevice device) {
170 final InstancedMeshNode batch = InstancedMeshNode(
171 DeviceMesh.upload(
172 device,
173 SphereShape(radius: 0.5, segments: 48, rings: 24).build(),
174 ),
175 _toon,
176 capacity: _numbers.length,
177 name: 'copies',
178 );
179 for (final (int i, (double r, double g, double b, double rim))
180 in _numbers.indexed) {
181 batch.addInstance(
182 Matrix4.translationValues(_x(i), 0.0, 0.0),
183 data: Vector4(r, g, b, rim),
184 );
185 }
186 return batch;
187 }
189 Scene _scene(GraphicsDevice device) => Scene()
190 ..ambientColor = LinearColor(0.6, 0.65, 0.8)
191 ..ambientIntensity = 0.08 * LightNode.legacyUnit
192 ..add(_batch(device))
193 ..add(
194 LightNode(
195 name: 'sun',
196 intensity: 1.4 * LightNode.legacyUnit,
197 castsShadow: false,
198 )..setLocalForward(Vector3(0.55, -0.45, -0.7)),
199 );
201 @override
202 Scene build(DemoContext context) => _scene(context.device);
204 /// Warmer paint, written into the list `RenderMaterial.parameters` holds; the
205 /// renderer binds it every frame, so nothing is rebuilt.
206 void _setWarmth(double warmth) {
207 _warmth = warmth;
208 _toon.parameters['paint']!.setAll(0, <double>[
209 1.0,
210 1.0 - 0.35 * warmth,
211 1.0 - 0.7 * warmth,
212 ]);
213 }
215 @override
216 List<DemoControl> controls(DemoContext context) => <DemoControl>[
217 SliderControl(
218 'Paint warmth (a uniform) — $_how',
219 min: 0.0,
220 max: 1.0,
221 value: () => _warmth,
222 onChanged: _setWarmth,
223 ),
224 ];
226 /// The red byte of the probe at ([x], [y]), and its three channels.
227 List<int> _rgb(int x, int y) {
228 final int at = (y * _probeWidth + x) * 4;
229 return <int>[_probe[at], _probe[at + 1], _probe[at + 2]];
230 }
232 @override
233 void verify(Scene scene, FrameResult frame) {
234 final String? carried = decodeMaterialSection(
235 ShaderBundle.decode(_bytes),
236 )[_name];
237 if (carried?.trim() != source.trim()) {
238 throw StateError('the bundle was not built from the source on the page');
239 }
240 if (!_drawn || _probe.isEmpty) throw StateError('not drawn: $_how');
241 // Each copy is painted by its own numbers: its strongest channel is the
242 // one its own colour says.
243 for (final (int i, (double r, double g, double b, _)) in _numbers.indexed) {
244 final (int x, int y) = _centers[i];
245 final List<int> got = _rgb(x, y);
246 final List<double> want = <double>[r, g, b];
247 final int wanted = want.indexOf(want.reduce((a, b) => a > b ? a : b));
248 final int strongest = got.indexOf(got.reduce((a, b) => a > b ? a : b));
249 if (strongest != wanted) {
250 throw StateError('copy $i reads $got, not its own colour $want');
251 }
252 }
253 // The light comes in bands: across the first copy, which has no rim,
254 // the shade takes a handful of values where n·l alone would give one
255 // for nearly every pixel.
256 final (int cx, int cy) = _centers[0];
257 final int reach = (_radius * 0.85).floor();
258 final Set<int> shades = <int>{
259 for (int x = cx - reach; x <= cx + reach; x++) _rgb(x, cy)[0],
260 };
261 if (shades.length < 2 || shades.length > 5) {
262 throw StateError(
263 '${2 * reach + 1} pixels across the sphere take ${shades.length} '
264 'shades; three bands and the unlit side are at most five',
265 );
266 }
267 if (frame.drawCalls < 1) throw StateError('nothing reached the frame');
268 }