threers 0.0.7

Drop-in three.js replacement for Rust and WebAssembly (wgpu) — THREE.* API, scene graph, PBR, post-fx, mesh BVH, CSG, an OpenSCAD front end with a watertight exact-CSG kernel, headless render, and native media codecs
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
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
//! Getting pixels back off the device, and the two things that always go wrong.
//!
//! **Row padding.** `copy_texture_to_buffer` requires each row to start on a
//! 256-byte boundary, so the buffer that comes back is wider than the image
//! unless the width happens to divide. Forgetting that produces a picture that
//! shears progressively to one side — recognisable once you have seen it, and
//! mystifying the first time.
//!
//! **Half floats.** Every float target in this crate is `*16Float`, and
//! nothing in `std` decodes one. Eight separate copies of a `half_to_f32`
//! grew in this crate before this module existed; they are now all [`f16_to_f32`].
//!
//! ```no_run
//! use threers::renderer::readback;
//! # fn demo(device: &wgpu::Device, queue: &wgpu::Queue, texture: &wgpu::Texture) {
//! let rgba = readback::texture_bytes(device, queue, texture);   // native only
//! # let _ = rgba;
//! # }
//! ```
//!
//! On the web there is no blocking variant and there cannot be: mapping
//! completes on the event loop, so a wait that does not yield starves the
//! callback it is waiting for. Use [`copy_texture_to_buffer`] and drive the
//! mapping yourself from an async context.

/// One IEEE 754 binary16 as an `f32`.
///
/// Exact for every input, subnormals and infinities included — a `bits >> 10`
/// shortcut gets the normals right and silently flattens the subnormals to
/// zero, which is most of the interesting range when the values being read
/// back are small.
pub fn f16_to_f32(bits: u16) -> f32 {
    let sign = if bits & 0x8000 != 0 { -1.0f32 } else { 1.0 };
    let exponent = ((bits >> 10) & 0x1f) as i32;
    let mantissa = (bits & 0x3ff) as u32;
    match exponent {
        // Subnormal (and zero): no implicit leading one, and a fixed exponent
        // of 2^-24. Writing it as a multiply rather than by renormalising into
        // float32 bits is both shorter and the version that is obviously right.
        0 => sign * mantissa as f32 * 5.960_464_5e-8,
        0x1f => {
            if mantissa == 0 {
                sign * f32::INFINITY
            } else {
                f32::NAN
            }
        }
        _ => {
            let s = u32::from(bits & 0x8000 != 0) << 31;
            f32::from_bits(s | (((exponent + 127 - 15) as u32) << 23) | (mantissa << 13))
        }
    }
}

/// An `f32` as the nearest IEEE 754 binary16, round-to-nearest-even.
///
/// The inverse of [`f16_to_f32`], for writing a float texture from the CPU.
pub fn f32_to_f16(value: f32) -> u16 {
    let bits = value.to_bits();
    let sign = ((bits >> 16) & 0x8000) as u16;
    let exp = ((bits >> 23) & 0xff) as i32 - 127 + 15;
    let mantissa = bits & 0x7f_ffff;
    if exp >= 0x1f {
        // Overflow, infinity, or NaN. A NaN must stay a NaN rather than
        // becoming an infinity, so keep a mantissa bit set.
        let payload = if ((bits >> 23) & 0xff) == 0xff && mantissa != 0 {
            0x200
        } else {
            0
        };
        return sign | 0x7c00 | payload;
    }
    if exp <= 0 {
        // Subnormal or zero in half precision.
        if exp < -10 {
            return sign;
        }
        let m = mantissa | 0x80_0000;
        let shift = (14 - exp) as u32;
        let half = (m >> shift) as u16;
        let round = (m >> (shift - 1)) & 1;
        return sign | (half + round as u16);
    }
    let half = ((exp as u32) << 10) as u16 | (mantissa >> 13) as u16;
    // Round to nearest, ties to even.
    let round = (mantissa >> 12) & 1;
    let sticky = (mantissa & 0xfff != 0) as u32;
    let up = round & (sticky | (half as u32 & 1));
    sign | (half + up as u16)
}

/// The padded row stride a buffer copy of `width` texels of `format` needs.
pub fn padded_bytes_per_row(width: u32, format: wgpu::TextureFormat) -> u32 {
    let unpadded = width * bytes_per_texel(format);
    let align = wgpu::COPY_BYTES_PER_ROW_ALIGNMENT;
    unpadded.div_ceil(align) * align
}

/// Bytes one texel occupies, for the uncompressed formats this crate reads
/// back. Panics on a block-compressed format, which cannot be read this way.
pub fn bytes_per_texel(format: wgpu::TextureFormat) -> u32 {
    // `block_copy_size`, not `target_pixel_byte_cost`. The latter is what a
    // texel costs as a *render attachment*, which is padded — it reports 8 for
    // `Rgba8Unorm`, and a readback sized from it reads every row at twice the
    // stride and shears the image.
    format
        .block_copy_size(None)
        .unwrap_or_else(|| panic!("{format:?} has no fixed texel size"))
}

/// Record a copy of `texture` into `buffer`, with the row padding a buffer
/// copy requires.
///
/// The buffer must be at least `padded_bytes_per_row(w, format) * h` bytes and
/// carry `COPY_DST | MAP_READ`. Use [`unpad`] on the mapped bytes.
pub fn copy_texture_to_buffer(
    encoder: &mut wgpu::CommandEncoder,
    texture: &wgpu::Texture,
    buffer: &wgpu::Buffer,
) {
    let (width, height) = (texture.width(), texture.height());
    encoder.copy_texture_to_buffer(
        wgpu::TexelCopyTextureInfo {
            texture,
            mip_level: 0,
            origin: wgpu::Origin3d::ZERO,
            aspect: wgpu::TextureAspect::All,
        },
        wgpu::TexelCopyBufferInfo {
            buffer,
            layout: wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(padded_bytes_per_row(width, texture.format())),
                rows_per_image: Some(height),
            },
        },
        wgpu::Extent3d {
            width,
            height,
            depth_or_array_layers: 1,
        },
    );
}

/// A buffer sized for [`copy_texture_to_buffer`] from `texture`.
pub fn staging_buffer(device: &wgpu::Device, texture: &wgpu::Texture) -> wgpu::Buffer {
    let size =
        padded_bytes_per_row(texture.width(), texture.format()) as u64 * texture.height() as u64;
    device.create_buffer(&wgpu::BufferDescriptor {
        label: Some("threers readback"),
        size,
        usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
        mapped_at_creation: false,
    })
}

/// Drop the row padding, leaving a tightly packed image.
pub fn unpad(padded: &[u8], width: u32, height: u32, format: wgpu::TextureFormat) -> Vec<u8> {
    let row = (width * bytes_per_texel(format)) as usize;
    let stride = padded_bytes_per_row(width, format) as usize;
    let mut out = Vec::with_capacity(row * height as usize);
    for y in 0..height as usize {
        out.extend_from_slice(&padded[y * stride..y * stride + row]);
    }
    out
}

/// Copy a texture into host memory and wait for it. **Native only.**
///
/// Returns tightly packed bytes in the texture's own format — four per texel
/// for `Rgba8Unorm`, eight for `Rgba16Float`. Use [`as_f32`] to decode a float
/// format.
#[cfg(not(target_arch = "wasm32"))]
pub fn texture_bytes(
    device: &wgpu::Device,
    queue: &wgpu::Queue,
    texture: &wgpu::Texture,
) -> Vec<u8> {
    let buffer = staging_buffer(device, texture);
    let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
        label: Some("threers readback copy"),
    });
    copy_texture_to_buffer(&mut encoder, texture, &buffer);
    queue.submit([encoder.finish()]);

    let slice = buffer.slice(..);
    slice.map_async(wgpu::MapMode::Read, |_| {});
    let _ = device.poll(wgpu::PollType::wait_indefinitely());
    let mapped = slice
        .get_mapped_range()
        .expect("buffer range is mapped after a blocking poll");
    let out = unpad(&mapped, texture.width(), texture.height(), texture.format());
    drop(mapped);
    buffer.unmap();
    out
}

/// Decode `*16Float` bytes into `f32`, one entry per channel.
///
/// `channels` is how many the format has: 1 for `R16Float`, 2 for `Rg16Float`,
/// 4 for `Rgba16Float`.
pub fn as_f32(bytes: &[u8]) -> Vec<f32> {
    bytes
        .chunks_exact(2)
        .map(|c| f16_to_f32(u16::from_le_bytes([c[0], c[1]])))
        .collect()
}

/// One channel of a `*16Float` texture, read back as `f32`. **Native only.**
///
/// What a test wants nine times out of ten: the divergence field, the red
/// channel of the dye, a depth buffer's one plane.
#[cfg(not(target_arch = "wasm32"))]
pub fn texture_channel_f32(
    device: &wgpu::Device,
    queue: &wgpu::Queue,
    texture: &wgpu::Texture,
    channel: usize,
) -> Vec<f32> {
    let bytes = texture_bytes(device, queue, texture);
    if texture.format() == wgpu::TextureFormat::Rg11b10Ufloat {
        assert!(channel < 3, "channel {channel} of a 3-channel format");
        return bytes
            .chunks_exact(4)
            .map(|t| {
                let word = u32::from_le_bytes([t[0], t[1], t[2], t[3]]);
                packed_float_to_f32(word, channel)
            })
            .collect();
    }
    let channels = (bytes_per_texel(texture.format()) / 2) as usize;
    assert!(
        channel < channels,
        "channel {channel} of a {channels}-channel format"
    );
    bytes
        .chunks_exact(channels * 2)
        .map(|texel| {
            let at = channel * 2;
            f16_to_f32(u16::from_le_bytes([texel[at], texel[at + 1]]))
        })
        .collect()
}

/// One channel of an `rg11b10ufloat` word.
///
/// Three unsigned floats in thirty-two bits: r and g are 5 bits of exponent
/// and 6 of mantissa, b is 5 and 5. No sign bit and no infinities worth
/// honouring, but the *bias is the same 15 as a half*, so each one widens to
/// a half's bit pattern by shifting the mantissa up — which is why this is a
/// shift and a reuse rather than a second decoder.
pub fn packed_float_to_f32(word: u32, channel: usize) -> f32 {
    let (bits, mantissa_bits) = match channel {
        0 => (word & 0x7ff, 6),
        1 => ((word >> 11) & 0x7ff, 6),
        _ => ((word >> 22) & 0x3ff, 5),
    };
    let exponent = bits >> mantissa_bits;
    let mantissa = bits & ((1 << mantissa_bits) - 1);
    let half = (exponent << 10) | (mantissa << (10 - mantissa_bits));
    f16_to_f32(half as u16)
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The packed three-channel float, against values it can hold exactly.
    ///
    /// Its exponent bias is a half's, so the decode is a shift — and a shift
    /// in the wrong direction still gives plausible-looking small numbers,
    /// which is why this checks the two channel widths separately.
    #[test]
    fn packed_floats_decode_exactly() {
        // 1.0 is exponent 15, mantissa 0 in every one of the three.
        let one = 15u32 << 6 | (15u32 << 6) << 11 | (15u32 << 5) << 22;
        for c in 0..3 {
            assert_eq!(packed_float_to_f32(one, c), 1.0, "channel {c}");
        }
        // Zero everywhere, and the largest mantissa step at exponent 15:
        // 1 + 1/64 in the 6-bit channels, 1 + 1/32 in the 5-bit one.
        assert_eq!(packed_float_to_f32(0, 0), 0.0);
        let step = (15u32 << 6 | 1) | ((15u32 << 5 | 1) << 22);
        assert_eq!(packed_float_to_f32(step, 0), 1.0 + 1.0 / 64.0);
        assert_eq!(packed_float_to_f32(step, 2), 1.0 + 1.0 / 32.0);
        // And the channels do not bleed into one another.
        assert_eq!(packed_float_to_f32(step, 1), 0.0);
    }

    /// Spot values, including the ones the copies this module replaced got
    /// wrong.
    ///
    /// Of the eight separate `half_to_f32` implementations that predated this
    /// module, **three decoded subnormals at a half or a quarter of their
    /// value** — a renormalising loop whose exponent bookkeeping started one or
    /// two steps off. One of the eight carried a comment recording that the bug
    /// had been found and fixed *there*, which is the clearest possible
    /// argument for there being one copy. Subnormal halves are everything below
    /// 6.1e-5: the deep shadow end of an EXR, and the almost-but-not-quite
    /// black of a float texture.
    #[test]
    fn half_floats_decode_exactly() {
        // Bit patterns with known values, including the two the shortcut
        // implementations get wrong.
        let cases: &[(u16, f32)] = &[
            (0x0000, 0.0),
            (0x8000, -0.0),
            (0x3c00, 1.0),
            (0xbc00, -1.0),
            (0x3555, 0.333_251_95),
            (0x7bff, 65504.0),        // the largest finite half
            (0x0400, 6.103_515_6e-5), // the smallest normal
            (0x0001, 5.960_464_5e-8), // the smallest subnormal
            (0x03ff, 6.097_555e-5),   // the largest subnormal
        ];
        for &(bits, expected) in cases {
            let got = f16_to_f32(bits);
            assert!(
                (got - expected).abs() <= expected.abs() * 1e-6,
                "{bits:#06x}: {got} != {expected}"
            );
        }
        assert!(f16_to_f32(0x7c00).is_infinite());
        assert!(f16_to_f32(0xfc00).is_infinite() && f16_to_f32(0xfc00) < 0.0);
        assert!(f16_to_f32(0x7e00).is_nan());
    }

    /// Every half float, through f32 and back. A decoder that is merely
    /// plausible passes a handful of spot checks; this is all 65 536 of them.
    #[test]
    fn every_half_float_round_trips() {
        for bits in 0..=u16::MAX {
            let v = f16_to_f32(bits);
            if v.is_nan() {
                assert!(nan_half(f32_to_f16(v)), "{bits:#06x} lost its NaN");
                continue;
            }
            let back = f32_to_f16(v);
            assert_eq!(back, bits, "{bits:#06x} -> {v} -> {back:#06x}");
        }
    }

    /// Is this half-float bit pattern a NaN? Free function rather than a
    /// method, because `is_*` taking `self` by value reads as a conversion.
    fn nan_half(bits: u16) -> bool {
        (bits & 0x7c00) == 0x7c00 && (bits & 0x3ff) != 0
    }

    #[test]
    fn rows_are_padded_to_the_alignment_and_unpadded_back() {
        let fmt = wgpu::TextureFormat::Rgba8Unorm;
        // 100 texels is 400 bytes, which is not a multiple of 256.
        assert_eq!(padded_bytes_per_row(100, fmt), 512);
        // 64 texels is exactly 256.
        assert_eq!(padded_bytes_per_row(64, fmt), 256);

        let (w, h) = (100u32, 3u32);
        let stride = padded_bytes_per_row(w, fmt) as usize;
        let mut padded = vec![0u8; stride * h as usize];
        for y in 0..h as usize {
            for x in 0..(w * 4) as usize {
                padded[y * stride + x] = (y * 7 + x) as u8;
            }
        }
        let tight = unpad(&padded, w, h, fmt);
        assert_eq!(tight.len(), (w * 4 * h) as usize);
        for y in 0..h as usize {
            for x in 0..(w * 4) as usize {
                assert_eq!(tight[y * (w * 4) as usize + x], (y * 7 + x) as u8);
            }
        }
    }

    #[test]
    fn texel_sizes_cover_what_gets_read_back() {
        use wgpu::TextureFormat as F;
        assert_eq!(bytes_per_texel(F::R8Unorm), 1);
        assert_eq!(bytes_per_texel(F::Rgba8Unorm), 4);
        assert_eq!(bytes_per_texel(F::Rgba8UnormSrgb), 4);
        assert_eq!(bytes_per_texel(F::R16Float), 2);
        assert_eq!(bytes_per_texel(F::Rg16Float), 4);
        assert_eq!(bytes_per_texel(F::Rgba16Float), 8);
        assert_eq!(bytes_per_texel(F::Rgba32Float), 16);
    }
}

/// A buffer being read back without blocking, on native and the web alike:
/// copy into [`AsyncReadback::buffer`] (as a `COPY_DST`), submit, call
/// [`map`](Self::map), then [`read`](Self::read) on later frames until it
/// gives the bytes. `wake` lets a redraw-on-demand loop know when to look
/// (natively the mapping completes as the device is polled, so poll it,
/// `wgpu::PollType::Poll`, while one is pending).
///
/// ```no_run
/// use threers::renderer::readback::AsyncReadback;
/// # fn demo(device: &wgpu::Device, queue: &wgpu::Queue, src: &wgpu::Buffer) {
/// let readback = AsyncReadback::new(device, 256, "my values");
/// let mut encoder = device.create_command_encoder(&Default::default());
/// encoder.copy_buffer_to_buffer(src, 0, readback.buffer(), 0, 256);
/// queue.submit([encoder.finish()]);
/// readback.map(std::sync::Arc::new(|| { /* request a redraw */ }));
/// // … each frame:
/// if let Some(bytes) = readback.read() { let _ = bytes; }
/// # }
/// ```
pub struct AsyncReadback {
    buffer: wgpu::Buffer,
    ready: std::sync::Arc<std::sync::atomic::AtomicBool>,
}

impl AsyncReadback {
    /// A `MAP_READ | COPY_DST` buffer of `size` bytes.
    pub fn new(device: &wgpu::Device, size: u64, label: &str) -> Self {
        let buffer = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some(label),
            size,
            usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        Self { buffer, ready: Default::default() }
    }

    /// The buffer to copy into.
    pub fn buffer(&self) -> &wgpu::Buffer {
        &self.buffer
    }

    /// Once the copy is submitted: maps the buffer, `wake` called when it
    /// can be read (or failed to map).
    pub fn map(&self, wake: std::sync::Arc<dyn Fn() + Send + Sync>) {
        let ready = self.ready.clone();
        self.buffer.slice(..).map_async(wgpu::MapMode::Read, move |r| {
            if r.is_ok() {
                ready.store(true, std::sync::atomic::Ordering::Release);
            }
            wake();
        });
    }

    /// Whether [`read`](Self::read) would give the bytes now.
    pub fn is_ready(&self) -> bool {
        self.ready.load(std::sync::atomic::Ordering::Acquire)
    }

    /// The bytes, once mapped (`None` before); the buffer is unmapped, so
    /// this gives them once.
    pub fn read(&self) -> Option<Vec<u8>> {
        if !self.ready.swap(false, std::sync::atomic::Ordering::AcqRel) {
            return None;
        }
        let bytes = self.buffer.slice(..).get_mapped_range().ok()?.to_vec();
        self.buffer.unmap();
        Some(bytes)
    }
}