Decals: the source
Open the live demo · Read the guide · View on GitHub
Regions the guide quotes: room (line 58), floor (line 98), wall (line 118), order (line 135), angle (line 139), switch (line 148), check (line 183).
1/// Projected box decals: a box that paints a colour onto whatever geometry
2/// stands inside it, a stain on a floor or a sign on a wall, without a
3/// polygon of its own.
4///
5/// Quoted by `decals.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 `decals` page: a red stain and a blue puddle on a floor and a sign on
14/// a wall, all box decals. Its check is that the scene holds three decals and
15/// the decal pass ran.
16final class DecalsDemo extends ShowcaseDemo {
17 /// Whether the decal pass runs.
18 bool decals = true;
20 /// Whether the blue puddle is drawn over the red stain where they overlap,
21 /// by giving it the higher `order`.
22 bool blueOnTop = true;
24 /// The alpha of the stain and the puddle, 0 to 1.
25 double opacity = 0.9;
27 /// The stain's angle limit in degrees, 10 to 110: a surface turned further
28 /// than this from the decal's projection is left unpainted.
29 double angleLimitDegrees = 75.0;
31 late final DecalNode _stain;
32 late final DecalNode _puddle;
33 late final DecalNode _sign;
36 void configureView(DemoContext context) {
37 context.orbit
38 ..distance = 7.0
39 ..pitch = 0.6
40 ..yaw = 0.5;
41 context.orbit.target.setValues(0.0, 0.6, 0.0);
42 }
44 MeshNode _slab(
45 DemoContext context,
46 String name,
47 Vector3 size,
48 Vector3 at,
49 Vector4 color,
50 ) => MeshNode(
51 DeviceMesh.upload(context.device, CuboidShape(size: size).build()),
52 RenderMaterial(name: name, baseColor: _fromSrgb(color), roughness: 0.8),
53 name: name,
54 )..setPositionFrom(at);
57 Scene build(DemoContext context) {
58 final Scene scene = Scene()
59 ..ambientColor = LinearColor(0.55, 0.6, 0.7)
60 ..ambientIntensity = 0.35 * LightNode.legacyUnit
61 ..add(
62 _slab(
63 context,
64 'floor',
65 Vector3(6.0, 0.1, 6.0),
66 Vector3(0.0, -0.05, 0.0),
67 Vector4(0.8, 0.8, 0.78, 1.0),
68 ),
69 )
70 ..add(
71 _slab(
72 context,
73 'wall',
74 Vector3(6.0, 3.0, 0.1),
75 Vector3(0.0, 1.5, -2.0),
76 Vector4(0.82, 0.8, 0.76, 1.0),
77 ),
78 )
79 ..add(
80 // A crate standing in the stain's box: its top takes the stain, and
81 // its sides only as far as the angle limit lets them.
82 _slab(
83 context,
84 'crate',
85 Vector3(0.6, 0.6, 0.6),
86 Vector3(0.5, 0.3, 0.4),
87 Vector4(0.7, 0.62, 0.5, 1.0),
88 ),
89 )
90 ..add(
91 LightNode(
92 name: 'sun',
93 intensity: 2.0 * LightNode.legacyUnit,
94 castsShadow: true,
95 )..setLocalForward(Vector3(-0.4, -0.8, -0.35)),
96 );
98 // With no rotation a decal's box lies flat and stamps down its own y
99 // axis: x and z are the size of the picture, y how deep it reaches.
100 _stain =
101 DecalNode(
102 name: 'stain',
103 color: LinearColor.fromSrgb(0.85, 0.2, 0.1, opacity),
104 )
105 ..setPosition(0.3, 0.0, 0.3)
106 ..setScale(2.0, 1.4, 2.0);
107 _puddle =
108 DecalNode(
109 name: 'puddle',
110 color: LinearColor.fromSrgb(0.15, 0.3, 0.9, opacity),
111 )
112 ..setPosition(-0.6, 0.0, 0.6)
113 ..setScale(1.8, 0.4, 1.4);
114 scene
115 ..add(_stain)
116 ..add(_puddle);
118 // On a wall the box is turned until its up points out of the wall.
119 _sign =
120 DecalNode(
121 name: 'sign',
122 color: LinearColor.fromSrgb(0.95, 0.8, 0.1, 1.0),
123 )
124 ..setPosition(-1.2, 1.6, -1.95)
125 ..setScale(1.4, 0.3, 0.8);
126 _sign.setRotation(
127 Quaternion.axisAngle(Vector3(1.0, 0.0, 0.0), math.pi / 2),
128 );
129 scene.add(_sign);
130 return scene;
131 }
134 void update(DemoContext context, double dt) {
135 // Where the two floor decals overlap, the higher order is painted over
136 // the lower one.
137 _puddle.order = blueOnTop ? 1 : 0;
138 _stain.order = blueOnTop ? 0 : 1;
139 // The crate's sides turn ninety degrees from the stain's up: a limit
140 // under ninety keeps the stain off them, one past it paints them too.
141 _stain.angleLimit = angleLimitDegrees * math.pi / 180.0;
142 _stain.color = _stain.color.withAlpha(opacity);
143 _puddle.color = _puddle.color.withAlpha(opacity);
144 }
147 RenderSettings settings(DemoContext context) => RenderSettings(
148 decals: DecalSettings(enabled: decals),
149 );
152 List<DemoControl> controls(DemoContext context) => <DemoControl>[
153 ToggleControl(
154 'Decals',
155 value: () => decals,
156 onChanged: (bool v) => decals = v,
157 ),
158 ToggleControl(
159 'Blue over red',
160 value: () => blueOnTop,
161 onChanged: (bool v) => blueOnTop = v,
162 ),
163 SliderControl(
164 'Opacity',
165 min: 0,
166 max: 1,
167 value: () => opacity,
168 onChanged: (double v) => opacity = v,
169 format: (double v) => v.toStringAsFixed(2),
170 ),
171 SliderControl(
172 'Angle limit',
173 min: 10,
174 max: 110,
175 value: () => angleLimitDegrees,
176 onChanged: (double v) => angleLimitDegrees = v,
177 format: (double v) => '${v.round()}°',
178 ),
179 ];
182 void verify(Scene scene, FrameResult frame) {
183 // Three decals in the scene and the switch on: the pass that paints them
184 // has to have run, not been culled or skipped.
185 if (scene.decals.length != 3) {
186 throw StateError('the scene holds ${scene.decals.length} decals, not 3');
187 }
188 final PassSkip? skipped = frame.skipReasonOf('decals');
189 if (skipped != null) {
190 throw StateError('the decal pass was skipped: $skipped');
191 }
192 if (!frame.passes.any((FramePass p) => p.name == 'decals')) {
193 throw StateError('the decal pass did not run');
194 }
195 }
196}
198/// A `Vector4` holding a colour sRGB-encoded, as the linear colour it names.
199LinearColor _fromSrgb(Vector4 c) => LinearColor.fromSrgb(c.x, c.y, c.z, c.w);