sgl-3d 0.7.0

Caller-driven 3D rendering for SGL games, native and in the browser (WebGPU)
Documentation
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
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
//! The ray source: the scene's geometry and materials for shader ray queries,
//! through portable BVHs that need no hardware ray-tracing features. Each
//! texture, material and model owns ranges of the source buffer (its level
//! 0; its record; its mesh records, section tables, vertices, indices and
//! BVH (`model`); a deforming
//! model's influences and morph targets), and each deforming instance its
//! joint matrices, morph weights and deformed vertices
//! (`scene::deformation`), written when it is added or replaced and freed
//! for reuse when it is removed; the buffer grows when they do not fit.
//! Pulled raster passes read vertices from it too, so it is always current,
//! and shadow casters read a deforming instance's positions from it as a
//! vertex buffer. Above the model BVHs, the instances' entries and the
//! instance BVHs built over them are `instances`'; the hardware path's
//! acceleration structures, built over the same geometry and entries where
//! the device traces rays in hardware, are `acceleration`'s.
use std::ops::Range;

use super::ranges::Ranges;
use super::{RayData, SceneError};
use crate::asset::{CompressedFormat, Image};
use crate::shading::material::MaterialUniform;
use crate::shading::packed_vertex::PackedVertex;

pub(crate) mod acceleration;
mod bvh;
mod charts;
#[cfg(all(test, not(target_arch = "wasm32")))]
mod hardware_tests;
pub(crate) mod instances;
#[cfg(test)]
mod layout;
mod model;
#[cfg(test)]
pub(crate) use layout::{constants, mirrors};
pub(crate) use model::{PreparedRayModel, RayMesh, prepare_model};
#[cfg(test)]
mod query;
#[cfg(all(test, not(target_arch = "wasm32")))]
pub(crate) use query::{Function, Query};
#[cfg(test)]
pub(crate) use query::{QUERY, SCENE_INTERSECT_ENTRY};

/// What a ray instance reads of its model.
#[derive(Clone, Copy)]
pub(crate) struct RayModel {
    /// The model's first mesh record.
    pub mesh_word: u32,
    /// Its BVH root node, zero when it has no triangles.
    pub bvh_root: u32,
}

/// A model's words in the source: what rays read, its range, and where each
/// mesh's vertices and indices lie.
pub(crate) struct RayModelWords {
    pub ray: RayModel,
    pub range: Range<u32>,
    pub meshes: Vec<RayMeshWords>,
}

/// Where a mesh's packed vertices and its indices lie in the source, which a
/// BLAS reads: its first vertex record, at a multiple of `VERTEX_WORDS`, and
/// its first index, with their counts.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct RayMeshWords {
    pub vertices: u32,
    pub vertex_count: u32,
    pub indices: u32,
    pub index_count: u32,
}

/// A packed vertex's words (`shading::packed_vertex`): the stride a BLAS
/// reads a model's positions at in whole strides, so each mesh's vertex
/// block, and the model's range, starts at a multiple of it
/// (`BlasTriangleGeometry::first_vertex` counts strides).
pub(crate) const VERTEX_WORDS: u32 = (std::mem::size_of::<PackedVertex>() / 4) as u32;

impl RayModel {
    /// Mesh `mesh`'s record, which pulled raster passes read.
    pub fn mesh_word(&self, mesh: usize) -> u32 {
        self.mesh_word + (mesh * model::MESH_WORDS) as u32
    }
}

/// The source's first words. Word 0 starts no record, so a zero image or BVH
/// root word means none.
#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct SourceHeader {
    /// The enabled material visibility groups.
    visibility_mask: u32,
    /// The static and moving instance BVHs' roots (`instances`), zero when
    /// one bounds nothing.
    static_root: u32,
    moving_root: u32,
    padding: u32,
}

/// An image's record in the source, followed by its level 0 row by row:
/// RGBA8 texels, or a BC7 image's blocks as stored, which rays decode texel
/// by texel.
#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct ImageHeader {
    width: u32,
    height: u32,
    /// `IMAGE_RGBA8` or `IMAGE_BC7`.
    format: u32,
}

/// `ImageHeader::format` of RGBA8 texels.
const IMAGE_RGBA8: u32 = 0;
/// `ImageHeader::format` of BC7 blocks.
const IMAGE_BC7: u32 = 1;

/// A material's record in the source: its values, its textures, their wrap
/// modes and whether lightmap charts light it.
#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct MaterialRecord {
    material: MaterialUniform,
    textures: MaterialTextures,
    wrap: [u32; 2],
    baked: u32,
}

/// Each texture's image word, zero when absent.
#[repr(C)]
#[derive(Clone, Copy, Default, bytemuck::Pod, bytemuck::Zeroable)]
pub(crate) struct MaterialTextures {
    pub base: u32,
    pub metallic_roughness: u32,
    pub emission: u32,
    pub normal: u32,
    pub bump: u32,
    pub anisotropy: u32,
    pub clearcoat: u32,
    pub coat_roughness: u32,
    pub coat_normal: u32,
    pub iridescence: u32,
    pub iridescence_thickness: u32,
    pub sheen_color: u32,
    pub sheen_roughness: u32,
    pub diffuse_transmission: u32,
    pub diffuse_transmission_color: u32,
    /// The volume's thickness map, which a ray hit's transmitted lobe takes.
    pub thickness: u32,
}

/// Words of `T`.
fn words<T>() -> usize {
    std::mem::size_of::<T>() / 4
}

pub(crate) struct SceneRays {
    ray_data: RayData,
    source: wgpu::Buffer,
    words: Ranges,
    /// The largest source the device binds, in words.
    word_limit: u64,
    visibility_mask: u32,
}

impl SceneRays {
    /// A shared source holding only its header, with immutable ray capability.
    pub fn with_ray_data(device: &wgpu::Device, ray_data: RayData) -> Self {
        let limits = device.limits();
        let header = words::<SourceHeader>();
        Self {
            ray_data,
            source: source_buffer(device, header as u64, ray_data),
            words: Ranges::new(header as u32),
            word_limit: limits
                .max_storage_buffer_binding_size
                .min(limits.max_buffer_size)
                / 4,
            visibility_mask: 0,
        }
    }

    pub fn ray_data(&self) -> RayData {
        self.ray_data
    }

    /// The source buffer, which group 1 binds and the deform stage writes.
    pub fn source(&self) -> &wgpu::Buffer {
        &self.source
    }

    /// `len` words, growing the source to hold them. Content already written
    /// keeps its words.
    pub fn allocate(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        len: usize,
    ) -> Result<Range<u32>, SceneError> {
        self.allocate_aligned(device, queue, len, 1)
    }

    /// `allocate`, starting at a multiple of `align` words.
    pub fn allocate_aligned(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        len: usize,
        align: u32,
    ) -> Result<Range<u32>, SceneError> {
        let len = u32::try_from(len).map_err(|_| SceneError::DeviceLimit)?;
        let range = self
            .words
            .allocate_aligned(len, align)
            .ok_or(SceneError::DeviceLimit)?;
        let needed = u64::from(self.words.end());
        if needed > self.word_limit {
            self.words.free(range);
            return Err(SceneError::DeviceLimit);
        }
        let capacity = self.source.size() / 4;
        if needed > capacity {
            crate::counters::ray_source_growth();
            let grown = source_buffer(
                device,
                needed.max(capacity * 2).min(self.word_limit),
                self.ray_data,
            );
            // Through the queue, never a frame's encoder: an abandoned frame
            // loses no content.
            let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
                label: Some("grow scene ray source"),
            });
            encoder.copy_buffer_to_buffer(&self.source, 0, &grown, 0, self.source.size());
            queue.submit([encoder.finish()]);
            self.source = grown;
        }
        Ok(range)
    }

    /// The words up to the last one content holds, and the words content
    /// holds.
    #[cfg(any(test, feature = "diagnostics"))]
    pub fn words_in_use(&self) -> (u64, u64) {
        let end = u64::from(self.words.end());
        (end, end - self.words.free_units())
    }

    /// Frees words for reuse.
    pub fn free(&mut self, range: Range<u32>) {
        self.words.free(range);
    }

    /// Writes `values` at `word`.
    pub fn write(&self, queue: &wgpu::Queue, word: u32, values: &[u32]) {
        if !values.is_empty() {
            crate::counters::write_buffer(
                queue,
                &self.source,
                u64::from(word) * 4,
                bytemuck::cast_slice(values),
            );
        }
    }

    /// An image's record and level 0, as stored; its word starts the range.
    pub fn add_image(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        image: &Image,
    ) -> Result<Range<u32>, SceneError> {
        if self.ray_data == RayData::Disabled {
            return Ok(0..0);
        }
        let [width, height] = image.size();
        let texels;
        let (format, bytes) = match image {
            Image::Rgba8(image) => (IMAGE_RGBA8, image.as_raw().as_slice()),
            Image::Rgba8Mips(image) => (IMAGE_RGBA8, image.levels(false)[0].as_raw().as_slice()),
            Image::Compressed(image) => match image.format {
                CompressedFormat::Bc7 => (IMAGE_BC7, image.levels[0].as_slice()),
                CompressedFormat::Etc2Rgba8 | CompressedFormat::Astc4x4 => {
                    texels = image
                        .decoded_level_0
                        .as_ref()
                        .ok_or(SceneError::MissingDecodedImage)?;
                    (IMAGE_RGBA8, texels.as_raw().as_slice())
                }
            },
        };
        let header = ImageHeader {
            width,
            height,
            format,
        };
        let range = self.allocate(device, queue, words::<ImageHeader>() + bytes.len() / 4)?;
        let mut record = Vec::with_capacity(range.len());
        record.extend_from_slice(bytemuck::cast_slice(&[header]));
        record.extend(
            bytes
                .chunks_exact(4)
                .map(|p| u32::from_le_bytes([p[0], p[1], p[2], p[3]])),
        );
        self.write(queue, range.start, &record);
        Ok(range)
    }

    /// A material's record, which lightmap charts do not light; its word
    /// starts the range.
    pub fn add_material(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        values: &MaterialUniform,
        textures: MaterialTextures,
        wrap: [gltf::texture::WrappingMode; 2],
    ) -> Result<Range<u32>, SceneError> {
        let record = MaterialRecord {
            material: *values,
            textures,
            wrap: wrap.map(|w| match w {
                gltf::texture::WrappingMode::Repeat => 0,
                gltf::texture::WrappingMode::MirroredRepeat => 1,
                gltf::texture::WrappingMode::ClampToEdge => 2,
            }),
            baked: 0,
        };
        let range = self.allocate(device, queue, words::<MaterialRecord>())?;
        self.write(queue, range.start, bytemuck::cast_slice(&[record]));
        Ok(range)
    }

    /// Replaces the values of the material record at `word`.
    pub fn write_material(&self, queue: &wgpu::Queue, word: u32, values: &MaterialUniform) {
        let field = std::mem::offset_of!(MaterialRecord, material) / 4;
        self.write(queue, word + field as u32, bytemuck::cast_slice(&[*values]));
    }

    /// Whether lightmap charts light the material whose record is at `word`.
    pub fn write_baked(&self, queue: &wgpu::Queue, word: u32, baked: bool) {
        let field = std::mem::offset_of!(MaterialRecord, baked) / 4;
        self.write(queue, word + field as u32, &[u32::from(baked)]);
    }

    /// Places prepared `model`: allocates its range at a multiple of
    /// `VERTEX_WORDS`, so its vertex blocks keep theirs, names each mesh's
    /// material record (`materials`, in mesh order) and adds the range's
    /// start to every word that addresses the source, so its words are
    /// ready to write at the range's start.
    pub fn place_model(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        model: &mut PreparedRayModel,
        materials: &[u32],
    ) -> Result<RayModelWords, SceneError> {
        let range = self.allocate_aligned(device, queue, model.len(), VERTEX_WORDS)?;
        let (ray, meshes) = model.rebase(range.start, materials);
        Ok(RayModelWords { ray, range, meshes })
    }

    /// Names the static and moving instance BVHs' roots in the header.
    pub fn set_instance_roots(&self, queue: &wgpu::Queue, roots: [u32; 2]) {
        crate::counters::write_buffer(
            queue,
            &self.source,
            std::mem::offset_of!(SourceHeader, static_root) as u64,
            bytemuck::cast_slice(&roots),
        );
    }

    /// Set the enabled material visibility groups before tracing this frame.
    pub fn set_visibility_mask(&mut self, queue: &wgpu::Queue, mask: u32) {
        if self.visibility_mask != mask {
            crate::counters::write_buffer(
                queue,
                &self.source,
                std::mem::offset_of!(SourceHeader, visibility_mask) as u64,
                bytemuck::bytes_of(&mask),
            );
            self.visibility_mask = mask;
        }
    }
}

/// A source of `words`. Where the device traces rays in hardware, BLASes
/// read their positions and indices from it (`BLAS_INPUT`).
fn source_buffer(device: &wgpu::Device, words: u64, ray_data: RayData) -> wgpu::Buffer {
    let blas_input = if ray_data == RayData::Enabled && acceleration::supported(device) {
        wgpu::BufferUsages::BLAS_INPUT
    } else {
        wgpu::BufferUsages::empty()
    };
    crate::counters::buffer(
        device,
        &wgpu::BufferDescriptor {
            label: Some("scene ray source geometry and materials"),
            size: words * 4,
            usage: wgpu::BufferUsages::STORAGE
                | wgpu::BufferUsages::VERTEX
                | wgpu::BufferUsages::COPY_DST
                | wgpu::BufferUsages::COPY_SRC
                | blas_input,
            mapped_at_creation: false,
        },
    )
}

#[cfg(all(test, not(target_arch = "wasm32")))]
mod tests;

#[cfg(all(test, not(target_arch = "wasm32")))]
mod portable_tests;

#[cfg(all(test, not(target_arch = "wasm32")))]
mod secondary_normal_tests;

#[cfg(all(test, not(target_arch = "wasm32")))]
mod instance_tests;

#[cfg(all(test, not(target_arch = "wasm32")))]
mod lod_receiver_tests;