sgl-3d 0.4.2

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
//! Decals: the images decals project, kept as texels and packed into the
//! decal atlas in each way a decal samples them (`decal_atlas`), and each
//! decal's description and its record in the scene's decal buffer, which
//! group 0 binds with the atlas, with the `Scene` operations that add, read,
//! change and remove them. A removed decal's record stays until its index is
//! reused; no view lists it, and the atlas keeps its images until it next
//! packs.
//!
//! As Godot marks its decal atlas dirty and packs it once per frame
//! (`TextureStorage::update_decal_atlas`), a decal that brings in an image
//! the atlas lacks only places the new layout, so the addition refuses an
//! atlas the device cannot hold; the frame's prepare (or a probe capture)
//! then uploads its texels and rewrites every record once.
use super::decal_atlas::{AtlasKey, AtlasLayout, DecalAtlas, Sampling};
use super::slots::Slots;
use super::{Scene, SceneError};
use crate::asset::Image;
use crate::content::decal::Decal;
use crate::content::identity::{DecalId, DecalImageId, Identity};
use crate::shading::decals::{DecalRecord, DecalRects};

const RECORD: u64 = std::mem::size_of::<DecalRecord>() as u64;

/// An image decals project, and how many decals use it.
struct DecalImage {
    texels: image::RgbaImage,
    users: usize,
}

pub(crate) struct Decals {
    images: Slots<DecalImageId, DecalImage>,
    pub slots: Slots<DecalId, Decal>,
    buffer: wgpu::Buffer,
    pub atlas: DecalAtlas,
    /// The layout the atlas takes at the next upload, placed when a decal
    /// brought in an image the atlas lacks (Godot's `decal_atlas.dirty`).
    pending: Option<AtlasLayout>,
    /// Every record is rewritten at the next upload: the layout or the
    /// buffer changed since they were written.
    stale: bool,
    /// Filters the atlas: trilinear and clamped, Godot's default decal
    /// filter (`rendering/textures/decals/filter`, linear with mipmaps).
    pub sampler: wgpu::Sampler,
}

/// The images `decal` projects, each in the way it samples it.
fn keys(decal: &Decal) -> impl Iterator<Item = AtlasKey> {
    [
        Some((decal.base_color, Sampling::Color)),
        decal.normal.map(|image| (image, Sampling::Data)),
        decal
            .metallic_roughness
            .map(|image| (image, Sampling::Data)),
    ]
    .into_iter()
    .flatten()
}

impl Decals {
    pub fn new(device: &wgpu::Device, queue: &wgpu::Queue) -> Self {
        Self {
            images: Slots::default(),
            slots: Slots::default(),
            buffer: decal_buffer(device, 1),
            atlas: DecalAtlas::empty(device, queue),
            pending: None,
            stale: false,
            // Lit group 0's one trilinear clamp-to-edge sampler, which the
            // blended draws' transmission also filters the transparent
            // stage's copy of the frame through (transmission_extended.wgsl):
            // keep it trilinear and clamped to the edge.
            sampler: device.create_sampler(&wgpu::SamplerDescriptor {
                label: Some("decal atlas"),
                mag_filter: wgpu::FilterMode::Linear,
                min_filter: wgpu::FilterMode::Linear,
                mipmap_filter: wgpu::MipmapFilterMode::Linear,
                ..Default::default()
            }),
        }
    }

    /// The records, as group 0 binds them.
    pub fn buffer(&self) -> &wgpu::Buffer {
        &self.buffer
    }

    pub fn get(&self, id: DecalId) -> Result<&Decal, SceneError> {
        self.slots.get(id).ok_or(SceneError::UnknownDecal)
    }

    /// Whether the scene holds no decal: the lit pipelines apply decals only
    /// while it holds one.
    pub fn is_empty(&self) -> bool {
        self.slots.is_empty()
    }

    /// Every decal, in index order: the ones every view lists.
    pub fn iter(&self) -> impl Iterator<Item = (DecalId, &Decal)> {
        self.slots.iter()
    }

    /// Whether the atlas waits for its next upload.
    #[cfg(all(test, not(target_arch = "wasm32")))]
    pub fn packing(&self) -> bool {
        self.pending.is_some()
    }

    /// The layout records name: the one waiting for its upload, else the
    /// atlas's.
    fn layout(&self) -> &AtlasLayout {
        self.pending.as_ref().unwrap_or(&self.atlas.layout)
    }

    fn record(&self, decal: &Decal) -> DecalRecord {
        let rect = |key| {
            self.layout()
                .rect(key)
                .expect("the layout holds every live decal's images")
        };
        DecalRecord::new(
            decal,
            DecalRects {
                base_color: rect((decal.base_color, Sampling::Color)),
                normal: decal.normal.map(|image| rect((image, Sampling::Data))),
                metallic_roughness: decal
                    .metallic_roughness
                    .map(|image| rect((image, Sampling::Data))),
            },
        )
    }

    /// Writes `decal`'s record now, unless every record waits for the next
    /// upload.
    fn write(&self, queue: &wgpu::Queue, index: usize, decal: &Decal) {
        if !self.stale {
            crate::counters::write_buffer(
                queue,
                &self.buffer,
                index as u64 * RECORD,
                bytemuck::bytes_of(&self.record(decal)),
            );
        }
    }

    /// The records a buffer with room for `count` would hold, when the
    /// buffer has none; `DeviceLimit` when the device cannot bind it.
    fn room(&self, device: &wgpu::Device, count: usize) -> Result<Option<u64>, SceneError> {
        let capacity = self.buffer.size() / RECORD;
        if count as u64 <= capacity {
            return Ok(None);
        }
        let limits = device.limits();
        let limit = limits
            .max_storage_buffer_binding_size
            .min(limits.max_buffer_size)
            / RECORD;
        if count as u64 > limit {
            return Err(SceneError::DeviceLimit);
        }
        Ok(Some((count as u64).max(capacity * 2).min(limit)))
    }

    /// A new layout when `decal` brings in an image the current one lacks:
    /// the images `decal` and the live decals other than `replacing` use;
    /// `DeviceLimit` when the device cannot hold it.
    fn place_for(
        &self,
        device: &wgpu::Device,
        decal: &Decal,
        replacing: Option<DecalId>,
    ) -> Result<Option<AtlasLayout>, SceneError> {
        if keys(decal).all(|key| self.layout().rect(key).is_some()) {
            return Ok(None);
        }
        let mut used: Vec<AtlasKey> = self
            .slots
            .iter()
            .filter(|(id, _)| Some(*id) != replacing)
            .flat_map(|(_, decal)| keys(decal))
            .chain(keys(decal))
            .collect();
        used.sort_by_key(|(image, sampling)| (image.index(), *sampling == Sampling::Data));
        used.dedup();
        let images: Vec<(AtlasKey, [u32; 2])> = used
            .into_iter()
            .map(|key| {
                let texels = &self.images.get(key.0).unwrap().texels;
                (key, [texels.width(), texels.height()])
            })
            .collect();
        AtlasLayout::place(&images, device.limits().max_texture_dimension_2d).map(Some)
    }

    /// Takes `layout` for the next upload, which rewrites every record.
    fn repack(&mut self, layout: Option<AtlasLayout>) {
        if let Some(layout) = layout {
            self.pending = Some(layout);
            self.stale = true;
        }
    }

    /// Uploads the pending atlas and rewrites every record when either
    /// waits: once per frame. Returns whether the atlas was replaced.
    fn upload(&mut self, device: &wgpu::Device, queue: &wgpu::Queue) -> bool {
        let packed = if let Some(layout) = self.pending.take() {
            let images = &self.images;
            self.atlas = DecalAtlas::fill(device, queue, layout, |(image, _)| {
                images.get(image).map(|image| &image.texels)
            });
            true
        } else {
            false
        };
        if std::mem::take(&mut self.stale) {
            for (id, decal) in self.slots.iter() {
                self.write(queue, id.index(), decal);
            }
        }
        packed
    }

    /// Moves the render origin by `by` (`Scene::move_origin`): each decal's
    /// position, whose record the next upload rewrites with every other.
    pub fn move_origin(&mut self, by: glam::Vec3) {
        for (_, decal) in self.slots.iter_mut() {
            decal.position -= by;
        }
        self.stale |= !self.slots.is_empty();
    }

    /// Counts `decal`'s images as used once more, or once less.
    fn count_users(&mut self, decal: &Decal, more: bool) {
        let mut images = vec![decal.base_color];
        images.extend(decal.normal);
        images.extend(decal.metallic_roughness);
        images.sort_by_key(|image| image.index());
        images.dedup();
        for image in images {
            let users = &mut self.images.get_mut(image).unwrap().users;
            if more {
                *users += 1;
            } else {
                *users -= 1;
            }
        }
    }

    /// `decal` is valid and its images are in the scene.
    fn validate(&self, decal: &Decal) -> Result<(), SceneError> {
        if !valid(decal) {
            return Err(SceneError::InvalidDecal);
        }
        if keys(decal).any(|(image, _)| self.images.get(image).is_none()) {
            return Err(SceneError::UnknownDecalImage);
        }
        Ok(())
    }
}

fn decal_buffer(device: &wgpu::Device, records: u64) -> wgpu::Buffer {
    crate::counters::buffer(
        device,
        &wgpu::BufferDescriptor {
            label: Some("scene decals"),
            size: records * RECORD,
            usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        },
    )
}

/// A decal a record can hold: a finite position, a finite rotation of
/// nonzero length, a positive finite size, colour, mix and normal fade in
/// their ranges and nonnegative finite fades.
fn valid(decal: &Decal) -> bool {
    let unit = |value: f32| (0. ..=1.).contains(&value);
    let fade = |value: f32| value.is_finite() && value >= 0.;
    decal.position.is_finite()
        && decal.rotation.is_finite()
        && decal.rotation.length_squared() > 0.
        && decal.rotation.normalize().is_finite()
        && decal.size.is_finite()
        && decal.size.min_element() > 0.
        && decal.color.iter().all(|&channel| unit(channel))
        && unit(decal.base_color_mix)
        && fade(decal.upper_fade)
        && fade(decal.lower_fade)
        && (0. ..1.).contains(&decal.normal_fade)
}

impl Scene {
    /// Adds an image for decals to project; a compressed image's level 0 is
    /// decoded. Decals sample it as sRGB colour or linear data by the map
    /// that names it.
    pub fn add_decal_image(&mut self, image: Image) -> Result<DecalImageId, SceneError> {
        self.edited();
        if let Image::Compressed(compressed) = &image
            && !compressed.is_valid()
        {
            return Err(SceneError::InvalidCompressedImage);
        }
        let [width, height] = image.size();
        if width == 0 || height == 0 {
            return Err(SceneError::EmptyImage);
        }
        let texels = match image {
            Image::Rgba8(texels) => texels,
            compressed => compressed.texels().into_owned(),
        };
        Ok(self.decals.images.insert(DecalImage { texels, users: 0 }))
    }

    /// Removes a decal image no decal uses.
    pub fn remove_decal_image(&mut self, id: DecalImageId) -> Result<(), SceneError> {
        self.edited();
        let image = self
            .decals
            .images
            .get(id)
            .ok_or(SceneError::UnknownDecalImage)?;
        if image.users > 0 {
            return Err(SceneError::DecalImageInUse);
        }
        self.decals.images.remove(id);
        Ok(())
    }

    /// Adds a decal. One that projects an image, in a way, that the scene's
    /// decals did not yet project packs the decal atlas anew before the next
    /// frame.
    pub fn add_decal(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        decal: Decal,
    ) -> Result<DecalId, SceneError> {
        self.edited();
        let decals = &mut self.decals;
        decals.validate(&decal)?;
        let room = decals.room(device, decals.slots.next_index() + 1)?;
        let layout = decals.place_for(device, &decal, None)?;
        if let Some(records) = room {
            decals.buffer = decal_buffer(device, records);
            decals.stale = true;
            self.resources = super::next_generation();
        }
        decals.repack(layout);
        let id = decals.slots.insert(decal);
        decals.count_users(&decal, true);
        decals.write(queue, id.index(), &decal);
        Ok(id)
    }

    /// A decal's current description.
    pub fn decal(&self, id: DecalId) -> Result<&Decal, SceneError> {
        self.decals.get(id)
    }

    /// Replaces a decal's description. One that projects an image, in a
    /// way, that the scene's decals did not yet project packs the decal
    /// atlas anew before the next frame.
    pub fn set_decal(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        id: DecalId,
        decal: Decal,
    ) -> Result<(), SceneError> {
        if *self.decals.get(id)? != decal {
            self.edited();
        }
        let decals = &mut self.decals;
        let old = *decals.get(id)?;
        decals.validate(&decal)?;
        let layout = decals.place_for(device, &decal, Some(id))?;
        decals.repack(layout);
        decals.count_users(&old, false);
        decals.count_users(&decal, true);
        *decals.slots.get_mut(id).unwrap() = decal;
        decals.write(queue, id.index(), &decal);
        Ok(())
    }

    /// Removes a decal. Its index is reused under a new identity.
    pub fn remove_decal(&mut self, id: DecalId) -> Result<(), SceneError> {
        self.edited();
        let decal = self
            .decals
            .slots
            .remove(id)
            .ok_or(SceneError::UnknownDecal)?;
        self.decals.count_users(&decal, false);
        Ok(())
    }

    /// Uploads a decal atlas packed since the last frame and rewrites the
    /// records it moved, through the queue: before a frame or a probe
    /// capture draws.
    pub(crate) fn upload_decals(&mut self, device: &wgpu::Device, queue: &wgpu::Queue) {
        if self.decals.upload(device, queue) {
            self.resources = super::next_generation();
        }
    }
}

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