threers 0.1.0

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
//! Volumes on the CPU ([`Data3DTexture`]) and on the GPU ([`GpuVolume`]).

use crate::marks::gpu;

/// How a volume's texels are stored.
///
/// The integer formats are for labels, where a value is an identity rather
/// than an intensity and must come back exactly: a segmentation, an atlas, a
/// material map. `Rg32Uint` holds a 64-bit label as low and high words.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum VolumeFormat {
    R8Unorm,
    Rgba8Unorm,
    R16Float,
    R32Float,
    R8Uint,
    R16Uint,
    R32Uint,
    /// A `u64` per texel, little-endian: `.r` is the low word, `.g` the high.
    Rg32Uint,
}

/// What a shader reads back from a volume: floats or unsigned integers.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum VolumeSample {
    /// `texture_3d<f32>`, read with `textureLoad` as `vec4<f32>`.
    Float,
    /// `texture_3d<u32>`, read with `textureLoad` as `vec4<u32>`.
    Uint,
}

impl VolumeFormat {
    pub fn bytes_per_texel(self) -> u32 {
        match self {
            VolumeFormat::R8Unorm | VolumeFormat::R8Uint => 1,
            VolumeFormat::R16Float | VolumeFormat::R16Uint => 2,
            VolumeFormat::Rgba8Unorm | VolumeFormat::R32Float | VolumeFormat::R32Uint => 4,
            VolumeFormat::Rg32Uint => 8,
        }
    }

    pub fn sample(self) -> VolumeSample {
        match self {
            VolumeFormat::R8Unorm
            | VolumeFormat::Rgba8Unorm
            | VolumeFormat::R16Float
            | VolumeFormat::R32Float => VolumeSample::Float,
            VolumeFormat::R8Uint
            | VolumeFormat::R16Uint
            | VolumeFormat::R32Uint
            | VolumeFormat::Rg32Uint => VolumeSample::Uint,
        }
    }

    pub fn wgpu(self) -> wgpu::TextureFormat {
        match self {
            VolumeFormat::R8Unorm => wgpu::TextureFormat::R8Unorm,
            VolumeFormat::Rgba8Unorm => wgpu::TextureFormat::Rgba8Unorm,
            VolumeFormat::R16Float => wgpu::TextureFormat::R16Float,
            VolumeFormat::R32Float => wgpu::TextureFormat::R32Float,
            VolumeFormat::R8Uint => wgpu::TextureFormat::R8Uint,
            VolumeFormat::R16Uint => wgpu::TextureFormat::R16Uint,
            VolumeFormat::R32Uint => wgpu::TextureFormat::R32Uint,
            VolumeFormat::Rg32Uint => wgpu::TextureFormat::Rg32Uint,
        }
    }
}

/// three.js `Data3DTexture`: a `width × height × depth` block of texels,
/// x fastest, then y, then z (`x + y·width + z·width·height`).
///
/// This is the CPU side; [`GpuVolume::from_texture`] uploads it.
#[derive(Clone, Debug, PartialEq)]
pub struct Data3DTexture {
    pub data: Vec<u8>,
    pub width: u32,
    pub height: u32,
    pub depth: u32,
    pub format: VolumeFormat,
}

impl Data3DTexture {
    /// # Panics
    ///
    /// If `data` is not exactly `width · height · depth` texels long.
    pub fn new(width: u32, height: u32, depth: u32, format: VolumeFormat, data: Vec<u8>) -> Self {
        let expected =
            width as usize * height as usize * depth as usize * format.bytes_per_texel() as usize;
        assert_eq!(
            data.len(),
            expected,
            "Data3DTexture {width}x{height}x{depth} {format:?} needs {expected} bytes"
        );
        Self {
            data,
            width,
            height,
            depth,
            format,
        }
    }

    /// An `R32Float` volume from `f32` values.
    pub fn from_f32(width: u32, height: u32, depth: u32, values: &[f32]) -> Self {
        Self::new(
            width,
            height,
            depth,
            VolumeFormat::R32Float,
            bytemuck::cast_slice(values).to_vec(),
        )
    }

    /// An `Rg32Uint` volume from `u64` labels.
    pub fn from_u64(width: u32, height: u32, depth: u32, labels: &[u64]) -> Self {
        let data = labels.iter().flat_map(|l| l.to_le_bytes()).collect();
        Self::new(width, height, depth, VolumeFormat::Rg32Uint, data)
    }

    pub fn size(&self) -> [u32; 3] {
        [self.width, self.height, self.depth]
    }
}

/// A volume in a 3D texture on the device.
///
/// Made whole from a [`Data3DTexture`], or empty and then filled a region at a
/// time with [`write_region`](Self::write_region) — which is how a volume too
/// large to load at once is streamed in as its chunks arrive.
///
/// On wgpu or the native Metal backend, as [`marks`](crate::marks) are: the
/// texture is a [`gpu::Texture`]. `view.wgpu()` is the `wgpu::TextureView` a
/// [`ShaderMaterial`](crate::ShaderMaterial)'s `volumes` take.
pub struct GpuVolume {
    pub texture: gpu::Texture,
    pub view: gpu::TextureView,
    pub size: [u32; 3],
    pub format: VolumeFormat,
}

/// The volumes a renderer uploaded for a
/// [`ShaderMaterial`](crate::ShaderMaterial)'s `volume_maps`: each [`Data3DTexture`] once, on
/// first use, kept while some material still holds it. A new `Arc` is new
/// contents; the same `Arc` is never uploaded twice.
#[derive(Default)]
pub struct VolumeMaps {
    uploaded: std::collections::HashMap<usize, (std::sync::Arc<Data3DTexture>, GpuVolume)>,
}

impl VolumeMaps {
    fn key(t: &std::sync::Arc<Data3DTexture>) -> usize {
        std::sync::Arc::as_ptr(t) as usize
    }

    /// Upload `t` on `gpu` unless it is; whether it was.
    pub fn ensure(&mut self, gpu: &gpu::Gpu, t: &std::sync::Arc<Data3DTexture>) -> bool {
        let k = Self::key(t);
        if self.uploaded.contains_key(&k) {
            return false;
        }
        self.uploaded
            .insert(k, (t.clone(), GpuVolume::from_texture_on(gpu, t)));
        true
    }

    /// `t` as uploaded.
    pub fn get(&self, t: &std::sync::Arc<Data3DTexture>) -> Option<&GpuVolume> {
        self.uploaded.get(&Self::key(t)).map(|(_, v)| v)
    }

    /// Let go of the volumes nothing but this holds any more.
    pub fn evict(&mut self) {
        self.uploaded
            .retain(|_, (t, _)| std::sync::Arc::strong_count(t) > 1);
    }
}

impl GpuVolume {
    /// An uninitialized volume (texels read as zero until written), on a
    /// `wgpu::Device` or a [`gpu::Gpu`].
    pub fn new(device: impl Into<gpu::Gpu>, size: [u32; 3], format: VolumeFormat) -> Self {
        let [w, h, d] = size.map(|n| n.max(1));
        let texture = device.into().create_texture(&wgpu::TextureDescriptor {
            label: Some("threers volume"),
            size: wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: d,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D3,
            format: format.wgpu(),
            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
        Self {
            texture,
            view,
            size: [w, h, d],
            format,
        }
    }

    pub fn from_texture(
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        texture: &Data3DTexture,
    ) -> Self {
        Self::from_texture_on(&gpu::Gpu::from((device, queue)), texture)
    }

    /// [`from_texture`](Self::from_texture) on either backend.
    pub fn from_texture_on(gpu: &gpu::Gpu, texture: &Data3DTexture) -> Self {
        let volume = Self::new(gpu, texture.size(), texture.format);
        volume.write_region_on(gpu, [0, 0, 0], texture.size(), &texture.data);
        volume
    }

    /// Replaces the box `origin .. origin + size` with `bytes`, laid out like a
    /// [`Data3DTexture`] of that size and this volume's format.
    ///
    /// No row alignment is needed: this is `Queue::write_texture`, not a
    /// buffer copy.
    ///
    /// # Panics
    ///
    /// If the box is not inside the volume or `bytes` is the wrong length, or
    /// the volume is on Metal (use [`write_region_on`](Self::write_region_on)).
    pub fn write_region(
        &self,
        queue: &wgpu::Queue,
        origin: [u32; 3],
        size: [u32; 3],
        bytes: &[u8],
    ) {
        if let Some((copy, layout, extent)) = self.region(origin, size, bytes) {
            queue.write_texture(
                wgpu::TexelCopyTextureInfo {
                    texture: self.texture.wgpu(),
                    mip_level: copy.mip_level,
                    origin: copy.origin,
                    aspect: copy.aspect,
                },
                bytes,
                layout,
                extent,
            );
        }
    }

    /// [`write_region`](Self::write_region) on either backend.
    pub fn write_region_on(&self, gpu: &gpu::Gpu, origin: [u32; 3], size: [u32; 3], bytes: &[u8]) {
        if let Some((copy, layout, extent)) = self.region(origin, size, bytes) {
            gpu.write_texture(copy, bytes, layout, extent);
        }
    }

    /// The copy for a region, checked; `None` when it is empty.
    fn region(
        &self,
        origin: [u32; 3],
        size: [u32; 3],
        bytes: &[u8],
    ) -> Option<(
        gpu::TexelCopyTextureInfo<'_>,
        wgpu::TexelCopyBufferLayout,
        wgpu::Extent3d,
    )> {
        for axis in 0..3 {
            assert!(
                origin[axis] + size[axis] <= self.size[axis],
                "region {origin:?}+{size:?} is outside the {:?} volume",
                self.size
            );
        }
        let bpt = self.format.bytes_per_texel();
        let [w, h, d] = size;
        assert_eq!(
            bytes.len(),
            (w * h * d * bpt) as usize,
            "region {size:?} of {:?} needs {} bytes",
            self.format,
            w * h * d * bpt
        );
        if w == 0 || h == 0 || d == 0 {
            return None;
        }
        Some((
            gpu::TexelCopyTextureInfo {
                texture: &self.texture,
                mip_level: 0,
                origin: wgpu::Origin3d {
                    x: origin[0],
                    y: origin[1],
                    z: origin[2],
                },
                aspect: wgpu::TextureAspect::All,
            },
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(w * bpt),
                rows_per_image: Some(h),
            },
            wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: d,
            },
        ))
    }
}

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

    #[test]
    fn u64_labels_are_little_endian_word_pairs() {
        let t = Data3DTexture::from_u64(1, 1, 1, &[0x0000_0002_0000_0001]);
        assert_eq!(t.data, [1, 0, 0, 0, 2, 0, 0, 0]);
        assert_eq!(t.format.sample(), VolumeSample::Uint);
    }

    #[test]
    #[should_panic(expected = "needs 24 bytes")]
    fn wrong_length_is_rejected() {
        Data3DTexture::new(2, 3, 1, VolumeFormat::R32Float, vec![0; 20]);
    }
}