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
//! The scene's ray queries: the WGSL modules that trace the scene, through
//! the portable walk or the hardware path's query of the device's form, and
//! the root a tracing pipeline composes.
use super::{
BC7, BIND_SCENE, DEFORMATION, FINITE, MATERIAL, Module, PACKED_VERTEX, SCENE_SOURCE, SRGB,
};
/// The scene's geometry and materials for ray queries, at group 1, and the
/// object records a hit reads its instance's pose, flags and ambient cube
/// from.
pub(crate) static SCENE_RAYS: Module = Module {
name: "scene_rays",
source: include_str!("scene_rays.wgsl"),
deps: &[
&MATERIAL,
&SCENE_SOURCE,
&SRGB,
&PACKED_VERTEX,
&BIND_SCENE,
&BC7,
&DEFORMATION,
],
};
/// The one acceptance predicate of every scene ray, the ray's validity test
/// and the side policies (`SCENE_SIDES_*`), which every trace composes.
pub(crate) static SCENE_RAYS_PREDICATE: Module = Module {
name: "scene_rays_predicate",
source: include_str!("scene_rays_predicate.wgsl"),
deps: &[&SCENE_RAYS, &FINITE],
};
/// The portable walk: the BVH traversal over the source header's roots,
/// which the portable function set and the hardware module both compose.
pub(crate) static SCENE_RAYS_WALK: Module = Module {
name: "scene_rays_walk",
source: include_str!("scene_rays_walk.wgsl"),
deps: &[&SCENE_RAYS_PREDICATE],
};
/// The scene ray function set through the portable walk alone: a tracing
/// pipeline's root where the hardware path is not in effect
/// (`ray_trace_root`).
pub(crate) static SCENE_RAYS_PORTABLE: Module = Module {
name: "scene_rays_portable",
source: include_str!("scene_rays_portable.wgsl"),
deps: &[&SCENE_RAYS_WALK],
};
/// The hardware path's shared module: the TLAS binding, the re-trace, the
/// composition with the portable walk, the per-ray budget and the scene ray
/// function set. It calls the query of the form in effect, whose module is
/// the root that composes it, never a dependency of it: `compose` recurses
/// forever on a cycle.
pub(crate) static SCENE_RAYS_HARDWARE: Module = Module {
name: "scene_rays_hardware",
source: include_str!("scene_rays_hardware.wgsl"),
deps: &[&SCENE_RAYS_WALK],
};
/// The baseline form's query (`RayQueryForm::Baseline`), the root of a
/// hardware-traced pipeline on Vulkan and DX12 (`LOWERED_FORM`) and on a
/// device that fell back from the candidate form.
pub(crate) static SCENE_RAYS_QUERY_OPAQUE: Module = Module {
name: "scene_rays_query_opaque",
source: include_str!("scene_rays_query_opaque.wgsl"),
deps: &[&SCENE_RAYS_HARDWARE],
};
/// The candidate form's query (`RayQueryForm::Candidates`), the root of a
/// hardware-traced pipeline on a backend that runs the candidate form
/// (`RayQueryForm::of_backend`: Metal).
pub(crate) static SCENE_RAYS_QUERY_CANDIDATES: Module = Module {
name: "scene_rays_query_candidates",
source: include_str!("scene_rays_query_candidates.wgsl"),
deps: &[&SCENE_RAYS_HARDWARE],
};
/// The form of the hardware path's ray queries (the architecture's Hardware
/// ray tracing, *Two forms, one stage*), a capability of the device's
/// backend: it selects the query module a tracing pipeline composes and the
/// geometry flags the scene builds its BLASes with; nothing else branches
/// on it.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub(crate) enum RayQueryForm {
/// Every BLAS geometry opaque, one query per look and a re-trace past
/// a committed hit the shared predicate rejects; masked models'
/// instances are traced by the portable walk.
Baseline,
/// A masked mesh's geometry not opaque, its instances in the TLAS, and
/// a candidate loop that runs the shared predicate on each of its
/// triangles a ray crosses, confirming those it accepts.
Candidates,
}
/// The form Vulkan and DX12 run (`RayQueryForm::of_backend`): the baseline
/// until the candidate form's benefit is measured on their hardware (RD-6),
/// a recorded decision and never a setting (AR-3). The candidate form has
/// not run on Vulkan or DX12 hardware yet (#23): the owner has none that
/// traces rays, and MoltenVK offers no ray query.
pub(crate) const LOWERED_FORM: RayQueryForm = RayQueryForm::Baseline;
/// The form Metal runs (`RayQueryForm::of_backend`): the candidate form, a
/// recorded decision and never a setting (AR-3), the owner's choice on
/// these measurements on an Apple M5 (#211; release builds, median GPU ms
/// of the passes that trace, candidates against the baseline). Where
/// masked content is traced, the candidate loop replaces the portable
/// walk, or a deforming instance's re-traces: among 266 static hedges of
/// cut-out cards at 1920×1080 the frame took 19.2 against 22.6 (dynamic
/// GI rays 0.31 against 0.79, ray-traced shadow rays 1.11 against 2.15,
/// world reflection rays 3.37 against 5.23), and among a crowd's masked
/// hair cards at 960×540 dynamic GI rays took 0.25 against 0.36. Where
/// nothing is masked it costs its larger program: 2–3 % of the streaming
/// example's ray-traced shadow rays on its walk and fly (about 0.02),
/// nothing measurable on the dynamic GI example or the world reflection
/// rays, and 14 % of the ray-traced shadow rays over a thousand opaque
/// props under nine shadowed lights (1.00 against 0.88, 0.12–0.13 more;
/// the frame 0.06–0.10 more), of which forcing opacity recovers a
/// quarter, so most is the loop's code, not its traversal. Revisit if naga
/// sets `assume_geometry_type(triangle)` in its MSL lowering (#221): with
/// that hint the baseline cost 0.09 of world reflection rays against the
/// candidate form's 0.20, and 0.59/0.47 of ray-traced shadow rays against
/// 0.77/0.69, on the streaming example's walk and fly, where nothing is
/// masked.
pub(crate) const METAL_FORM: RayQueryForm = RayQueryForm::Candidates;
impl RayQueryForm {
/// Whether `backend` may run a candidate loop: Vulkan, DX12 and Metal,
/// whose naga 30 SPIR-V, HLSL and MSL writers lower it (the MSL writer
/// through Metal's `intersection_query`, `back/msl/ray.rs` 363–495,
/// validated on an Apple M5 by #211). No other backend has ray queries.
pub fn lowered(backend: wgpu::Backend) -> bool {
matches!(
backend,
wgpu::Backend::Vulkan | wgpu::Backend::Dx12 | wgpu::Backend::Metal
)
}
/// The form a device of `backend` runs: the form recorded for it
/// (`METAL_FORM`, else `LOWERED_FORM`) where it may run the candidate
/// form, else the baseline.
pub fn of_backend(backend: wgpu::Backend) -> Self {
let recorded = match backend {
wgpu::Backend::Metal => METAL_FORM,
_ => LOWERED_FORM,
};
Self::gated(backend, recorded)
}
/// `form` where `backend` may run the candidate form, else the
/// baseline.
fn gated(backend: wgpu::Backend, form: Self) -> Self {
if Self::lowered(backend) {
form
} else {
Self::Baseline
}
}
}
/// The root a tracing pipeline composes after its own modules: the hardware
/// path's query module for the form in effect, else the portable function
/// set. Each defines the scene ray function set once in the program.
pub(crate) fn ray_trace_root(form: Option<RayQueryForm>) -> &'static Module {
match form {
None => &SCENE_RAYS_PORTABLE,
Some(RayQueryForm::Baseline) => &SCENE_RAYS_QUERY_OPAQUE,
Some(RayQueryForm::Candidates) => &SCENE_RAYS_QUERY_CANDIDATES,
}
}
#[cfg(test)]
mod form_tests {
use super::RayQueryForm;
use wasm_bindgen_test::wasm_bindgen_test;
// Plausible defects: a backend given another backend's recorded form
// (the match in `of_backend` wrong), or a backend whose shader writer
// cannot lower the candidate loop given the candidate form once a
// recorded choice becomes it (the gate bypassed or dropped). The oracle
// is what the architecture records: Metal runs the candidate form
// (#211), Vulkan and DX12 the baseline until it is measured there, and
// no other backend has ray queries.
#[wasm_bindgen_test(unsupported = test)]
fn each_backend_runs_its_recorded_form() {
use RayQueryForm::{Baseline, Candidates};
use wgpu::Backend::{BrowserWebGpu, Dx12, Gl, Metal, Noop, Vulkan};
for (backend, form) in [
(Vulkan, Baseline),
(Dx12, Baseline),
(Metal, Candidates),
(Gl, Baseline),
(BrowserWebGpu, Baseline),
(Noop, Baseline),
] {
assert_eq!(RayQueryForm::of_backend(backend), form, "{backend:?}");
}
for backend in [Gl, BrowserWebGpu, Noop] {
assert_eq!(
RayQueryForm::gated(backend, Candidates),
Baseline,
"{backend:?}"
);
}
}
}