1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
//! Rust mirrors of light_records.wgsl: a scene light's record and a light's
//! shadow in the local-light shadow atlas.
use crate::content::light::{Light, LightCookie, LightShape};
use glam::Vec3;
/// One scene light as shading reads it (`Light` in light_records.wgsl), at
/// its identity's index in the scene's light buffer.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, bytemuck::Pod, bytemuck::Zeroable)]
pub(crate) struct LightRecord {
pub position: [f32; 3],
pub inverse_square_range: f32,
/// Linear RGB times intensity: per steradian for a point or spot light,
/// a rectangle's luminance (its intensity over its area).
pub color: [f32; 3],
pub specular: f32,
/// A spot light's unit direction, or a rectangle's unit normal; zero for
/// a point light.
pub direction: [f32; 3],
pub range: f32,
pub spot_scale: f32,
pub spot_offset: f32,
/// `LIGHT_PUNCTUAL` or `LIGHT_RECT`.
pub shape: u32,
/// The scale of its light in the volumetric fog.
pub fog_energy: f32,
/// A rectangle's half width along its width's axis; zero for a point or
/// spot light.
pub half_width: [f32; 3],
/// Half a rectangle's height, along its width's axis crossed with its
/// normal; zero for a point or spot light.
pub half_height: f32,
/// How dark its shadow is (`Light::shadow_opacity`).
pub shadow_opacity: f32,
/// `LIGHT_*` bits.
pub flags: u32,
/// A point or spot light's radius in metres, which sizes its highlights
/// and its rays' ends (`LightShape`); zero for a rectangle.
pub radius: f32,
/// WGSL aligns `cookie_rect` to 16 bytes.
pub padding: f32,
/// A spot's cookie's place in the decal atlas, in atlas UV (offset in
/// xy, size in zw); all zero for a light without one.
pub cookie_rect: [f32; 4],
/// A cookied spot's unit right axis: its direction crossed with the
/// cookie's up (`LightCookie::up`); zero without a cookie.
pub cookie_right: [f32; 3],
/// A cookied spot's outer cone's cotangent, which scales its projector
/// square to the cone; zero without a cookie.
pub cookie_cotangent: f32,
}
/// `LightRecord::shape`: a point or spot light.
pub(crate) const LIGHT_PUNCTUAL: u32 = 0;
/// `LightRecord::shape`: a rectangle.
pub(crate) const LIGHT_RECT: u32 = 1;
/// `LightRecord::flags`: the light casts a shadow (`Light::casts_shadow`).
pub(crate) const LIGHT_CASTS_SHADOW: u32 = 1;
/// The shadow opacity at or below which a light's shadow is not looked up
/// (`SHADOW_OPACITY_CUTOFF` in shadow_sampling.wgsl, Godot's).
pub(crate) const SHADOW_OPACITY_CUTOFF: f32 = 0.001;
impl LightRecord {
/// `light`'s record, valid as `Scene::add_light` accepts it. A spot's
/// cone is Bevy's spot scale and offset (`prepare_lights`), which
/// Filament's `getAngleAttenuation` takes; a point light's and a
/// rectangle's leave it whole. A rectangle's luminance is its intensity
/// over its area, as Bevy's `extract_lights` divides its flux by its
/// area and π. `cookie_rect` is the place of its cookie's image in the
/// decal atlas the record is read with; it is ignored for a light
/// without a cookie.
pub fn new(light: &Light, cookie_rect: [f32; 4]) -> Self {
let mut color = light.color.map(|channel| channel * light.intensity);
let (shape, direction, half_width, half_height, spot_scale, spot_offset) = match light.shape
{
LightShape::Point { .. } => (LIGHT_PUNCTUAL, [0.; 3], [0.; 3], 0., 0., 1.),
LightShape::Spot {
direction,
inner_angle,
outer_angle,
..
} => {
let cos_outer = outer_angle.cos();
let scale = 1. / (inner_angle.cos() - cos_outer).max(1e-4);
(
LIGHT_PUNCTUAL,
direction.normalize().to_array(),
[0.; 3],
0.,
scale,
-cos_outer * scale,
)
}
LightShape::Rect {
direction,
width_axis,
width,
height,
} => {
let normal = direction.normalize();
let across = width_axis.reject_from_normalized(normal).normalize();
color = color.map(|channel| channel / (width * height));
(
LIGHT_RECT,
normal.to_array(),
(across * (0.5 * width)).to_array(),
0.5 * height,
0.,
1.,
)
}
};
Self {
position: light.position.to_array(),
inverse_square_range: 1. / (light.range * light.range),
color,
specular: light.specular,
direction,
range: light.range,
spot_scale,
spot_offset,
shape,
fog_energy: light.fog_energy,
half_width,
half_height,
shadow_opacity: light.shadow_opacity,
flags: if light.casts_shadow {
LIGHT_CASTS_SHADOW
} else {
0
},
radius: match light.shape {
LightShape::Point { radius } | LightShape::Spot { radius, .. } => radius,
LightShape::Rect { .. } => 0.,
},
padding: 0.,
..cookie(light, cookie_rect)
}
}
}
/// A cookie's frame on a light of `shape`: its unit right axis and its
/// outer cone's cotangent, which fit its projector square to the cone
/// (`light_cookie.wgsl`); none unless the light is a spot whose outer
/// angle and the part of the cookie's `up` across its direction give
/// finite ones. The right axis is the spot's direction crossed with up, as
/// Bevy 9d12036 projects a spot's texture through the light's transform
/// (`extract_spot_light_textures`, crates/bevy_pbr/src/decal/clustered.rs
/// 346–372), whose +X is its up crossed with its back.
pub(crate) fn cookie_frame(cookie: &LightCookie, shape: &LightShape) -> Option<(Vec3, f32)> {
let LightShape::Spot {
direction,
outer_angle,
..
} = *shape
else {
return None;
};
let direction = direction.normalize();
let right = direction
.cross(cookie.up.reject_from_normalized(direction))
.normalize();
let cotangent = 1. / outer_angle.tan();
(outer_angle > 0. && right.is_finite() && cotangent.is_finite()).then_some((right, cotangent))
}
/// The record's cookie rows: its image's place in the atlas and its frame
/// (`cookie_frame`), or zero without a cookie.
fn cookie(light: &Light, rect: [f32; 4]) -> LightRecord {
let zeroed = bytemuck::Zeroable::zeroed();
let Some((right, cotangent)) = light
.cookie
.and_then(|cookie| cookie_frame(&cookie, &light.shape))
else {
return zeroed;
};
LightRecord {
cookie_rect: rect,
cookie_right: right.to_array(),
cookie_cotangent: cotangent,
..zeroed
}
}
/// `LocalShadow::kind`: the light has no shadow.
pub(crate) const LOCAL_SHADOW_NONE: u32 = 0;
/// `LocalShadow::kind`: six cube faces around the light.
pub(crate) const LOCAL_SHADOW_CUBE: u32 = 1;
/// `LocalShadow::kind`: one spot face.
pub(crate) const LOCAL_SHADOW_SPOT: u32 = 2;
/// A scene light's shadow in the local-light shadow atlas (`LocalShadow` in
/// light_records.wgsl), at its identity's index in group 0's
/// `local_shadows`.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, bytemuck::Pod, bytemuck::Zeroable)]
pub(crate) struct LocalShadowRecord {
/// A spot face's reversed-Z projection from the world.
pub clip_from_world: [[f32; 4]; 4],
/// Each face's top-left corner in atlas UV: face 2i in xy, 2i+1 in zw.
pub corners: [[f32; 4]; 3],
/// A face's size in atlas UV.
pub size: f32,
/// The near plane of the faces' projections.
pub near: f32,
/// World metres per atlas texel at a metre along a face's axis.
pub texel_scale: f32,
/// `LOCAL_SHADOW_*`.
pub kind: u32,
/// 1 while its static layers hold its static casters.
pub layers: u32,
pub padding: [u32; 3],
}
impl LocalShadowRecord {
/// A light without a shadow.
pub const NONE: Self = Self {
clip_from_world: [[0.; 4]; 4],
corners: [[0.; 4]; 3],
size: 0.,
near: 0.,
texel_scale: 0.,
kind: LOCAL_SHADOW_NONE,
layers: 0,
padding: [0; 3],
};
}
#[cfg(test)]
pub(crate) fn constants() -> [crate::shading::layout_tests::Constant; 7] {
use crate::shading::layout_tests::Constant;
use naga::Literal::U32;
[
Constant::new("geometry", "LIGHT_PUNCTUAL", U32(LIGHT_PUNCTUAL)),
Constant::new("geometry", "LIGHT_RECT", U32(LIGHT_RECT)),
Constant::new("geometry", "LIGHT_CASTS_SHADOW", U32(LIGHT_CASTS_SHADOW)),
Constant::new(
"geometry",
"SHADOW_OPACITY_CUTOFF",
naga::Literal::F32(SHADOW_OPACITY_CUTOFF),
),
Constant::new("geometry", "LOCAL_SHADOW_NONE", U32(LOCAL_SHADOW_NONE)),
Constant::new("geometry", "LOCAL_SHADOW_CUBE", U32(LOCAL_SHADOW_CUBE)),
Constant::new("geometry", "LOCAL_SHADOW_SPOT", U32(LOCAL_SHADOW_SPOT)),
]
}
#[cfg(test)]
pub(crate) fn mirrors() -> [crate::shading::layout_tests::Mirror; 2] {
use crate::shading::layout_tests::mirror;
[
mirror!(
"geometry",
"Light",
LightRecord,
[
position,
inverse_square_range,
color,
specular,
direction,
range,
spot_scale,
spot_offset,
shape,
fog_energy,
half_width,
half_height,
shadow_opacity,
flags,
radius,
cookie_rect,
cookie_right,
cookie_cotangent,
]
),
mirror!(
"geometry",
"LocalShadow",
LocalShadowRecord,
[
clip_from_world,
corners,
size,
near,
texel_scale,
kind,
layers,
padding
]
),
]
}