three-rs 0.2.0

A port of three.js core and its WebGPURenderer to Rust on wgpu, graded against three.js's own end-to-end pixel comparison.
Documentation
//! Port of `three.js/src/loaders/TextureLoader.js` (+ the PNG, JPEG, GIF and
//! WebP decodes that `ImageLoader` / `createImageBitmap` get from the
//! browser).
//!
//! AVIF is the one format a page's `createImageBitmap` decodes that the port
//! does not: there is no pure-Rust AV1 decoder yet that both builds for wasm32
//! and decodes every AVIF image in the three.js examples (issue #179 has the
//! evaluation). An AVIF image is refused with an error that says so, rather
//! than handed to the JPEG decoder to fail on.
//!
//! The page's load is asynchronous, but the harness fires its single RAF only
//! once the network is idle, so the image is always present for the graded
//! frame; here it is decoded synchronously.

use std::path::Path;

use crate::error::Error;
use crate::textures::Texture;

/// three.js' `TextureLoader`.
pub struct TextureLoader;

impl Default for TextureLoader {
    fn default() -> Self {
        Self::new()
    }
}

impl TextureLoader {
    /// A loader with no state — `new TextureLoader()`.
    pub fn new() -> Self {
        Self
    }

    /// `new TextureLoader().load( url )`. The loader leaves every `Texture`
    /// default in place — `flipY` true, `generateMipmaps` true,
    /// `LinearFilter` / `LinearMipmapLinearFilter`, `ClampToEdgeWrapping`,
    /// anisotropy 1, `NoColorSpace` (the example never sets `colorSpace`, so
    /// `uv_grid_opengl.jpg` is sampled as raw bytes and no sRGB decode
    /// happens in the shader).
    pub fn load<P: AsRef<Path>>(&self, url: P) -> Result<Texture, Error> {
        let path = url.as_ref();
        let bytes = crate::io::read(path)?;
        // `ImageLoader` gives the bytes to the browser, which picks the decoder
        // from the sniffed type and not from the extension.
        let image = decode_image(path, &bytes)?;
        Ok(Texture::new(image.width, image.height, Some(image.data)))
    }

    /// The bytes of an image the loader never sees as a file: a glTF image
    /// stored in the BIN chunk or a data URI. `ImageBitmapLoader` /
    /// `createImageBitmap` in the browser; here the decode is picked by the
    /// glTF `mimeType` when there is one and by the file's magic otherwise,
    /// because `images[ i ].mimeType` is only required for a `bufferView`
    /// source.
    ///
    /// The `Texture` comes back with the same defaults `load()` gives one;
    /// `GLTFLoader` is what sets `flipY`, the wrapping and the colour space.
    pub fn from_bytes(&self, bytes: &[u8], mime_type: Option<&str>) -> Result<Texture, Error> {
        let path = Path::new("<glTF image>");
        let image = match mime_type {
            Some("image/png") => decode_png(path, bytes)?,
            Some("image/jpeg") => decode_jpeg_bytes(path, bytes)?,
            Some("image/webp") => decode_webp(path, bytes)?,
            _ => decode_image(path, bytes)?,
        };

        Ok(Texture::new(image.width, image.height, Some(image.data)))
    }
}

/// `ImageLoader` gives the bytes to the browser, which picks the decoder from
/// the sniffed type and not from the extension. Four magic numbers cover
/// everything the ladder loads, and anything else is taken for a JPEG. Shared
/// with [`CubeTextureLoader`], whose six
/// faces are PNG in `webgpu_materials_basic` and JPEG in
/// `webgpu_pmrem_scene`.
///
/// [`CubeTextureLoader`]: super::CubeTextureLoader
pub(crate) fn decode_image(path: &Path, bytes: &[u8]) -> Result<crate::textures::Image, Error> {
    if bytes.starts_with(b"GIF") {
        super::gif::decode(path, bytes)
    } else if bytes.starts_with(&[0x89, b'P', b'N', b'G']) {
        decode_png(path, bytes)
    } else if is_webp(bytes) {
        decode_webp(path, bytes)
    } else if is_avif(bytes) {
        Err(Error::image(
            path,
            "AVIF is not decoded: no pure-Rust AV1 decoder is fit yet (issue #179)",
        ))
    } else {
        decode_jpeg_bytes(path, bytes)
    }
}

/// `createImageBitmap` on a PNG: 8-bit RGBA, top-down, with every source
/// format expanded to it (palette and grey both reach the GPU as RGBA8 in the
/// browser too). Unlike the JPEG path this is exact — PNG is lossless and the
/// decoders agree byte for byte.
pub(crate) fn decode_png(path: &Path, bytes: &[u8]) -> Result<crate::textures::Image, Error> {
    let mut decoder = png::Decoder::new(std::io::Cursor::new(bytes));
    // `EXPAND` takes palette, grey and `tRNS` up to 8-bit RGB/RGBA, so the only
    // cases left below are the four 8-bit ones (and 16-bit, which is stripped).
    decoder.set_transformations(png::Transformations::EXPAND | png::Transformations::STRIP_16);

    let mut reader = decoder
        .read_info()
        .map_err(|e| Error::image(path, e.to_string()))?;
    let mut buffer = vec![0; reader.output_buffer_size()];
    let info = reader
        .next_frame(&mut buffer)
        .map_err(|e| Error::image(path, e.to_string()))?;
    buffer.truncate(info.buffer_size());

    let pixels = (info.width as usize) * (info.height as usize);
    let data = match info.color_type {
        png::ColorType::Rgba => buffer,
        png::ColorType::Rgb => {
            let mut out = Vec::with_capacity(pixels * 4);
            for pixel in buffer.as_chunks::<3>().0 {
                out.extend_from_slice(pixel);
                out.push(255);
            }
            out
        }
        png::ColorType::Grayscale => {
            let mut out = Vec::with_capacity(pixels * 4);
            for &value in &buffer {
                out.extend_from_slice(&[value, value, value, 255]);
            }
            out
        }
        png::ColorType::GrayscaleAlpha => {
            let mut out = Vec::with_capacity(pixels * 4);
            for pixel in buffer.as_chunks::<2>().0 {
                out.extend_from_slice(&[pixel[0], pixel[0], pixel[0], pixel[1]]);
            }
            out
        }
        png::ColorType::Indexed => {
            return Err(Error::image(path, "the PNG palette was not expanded"));
        }
    };

    Ok(crate::textures::Image {
        width: info.width,
        height: info.height,
        data,
    })
}

/// What the browser hands `copyExternalImageToTexture`: 8-bit RGBA, top-down,
/// opaque.
///
/// Chromium decodes through libjpeg-turbo and this goes through `zune-jpeg`,
/// so individual samples can differ by the rounding of the inverse DCT; the
/// PNG and GIF paths beside it are exact.
pub(crate) fn decode_jpeg_bytes(
    path: &Path,
    bytes: &[u8],
) -> Result<crate::textures::Image, Error> {
    let options = zune_jpeg::zune_core::options::DecoderOptions::default()
        .jpeg_set_out_colorspace(zune_jpeg::zune_core::colorspace::ColorSpace::RGBA);

    let mut decoder =
        zune_jpeg::JpegDecoder::new_with_options(std::io::Cursor::new(bytes), options);

    let data = decoder
        .decode()
        .map_err(|e| Error::image(path, e.to_string()))?;
    let (width, height) = decoder
        .dimensions()
        .ok_or_else(|| Error::image(path, "the JPEG has no dimensions"))?;

    Ok(crate::textures::Image {
        width: width as u32,
        height: height as u32,
        data,
    })
}

/// A RIFF container whose form type is `WEBP` — the WHATWG mime-sniffing
/// signature `createImageBitmap` goes by.
fn is_webp(bytes: &[u8]) -> bool {
    bytes.len() >= 12 && bytes.starts_with(b"RIFF") && &bytes[8..12] == b"WEBP"
}

/// An ISO-BMFF `ftyp` box whose major brand is `avif` or `avis`.
fn is_avif(bytes: &[u8]) -> bool {
    bytes.len() >= 12 && &bytes[4..8] == b"ftyp" && matches!(&bytes[8..12], b"avif" | b"avis")
}

/// `createImageBitmap` on a WebP: 8-bit RGBA, top-down, lossy (VP8, with or
/// without an `ALPH` plane) or lossless (VP8L).
///
/// Exact, not merely close: `image-webp` upsamples the lossy chroma with the
/// same "fancy" filter and fixed-point YUV→RGB as libwebp, which is what
/// Chromium decodes with, and `tests/loaders_webp.rs` checks every WebP image
/// in the three.js examples against Chromium's own decode byte for byte. An
/// animated WebP gives its first frame, as `createImageBitmap` does; no
/// three.js asset is animated, so that case is untested.
pub(crate) fn decode_webp(path: &Path, bytes: &[u8]) -> Result<crate::textures::Image, Error> {
    let mut decoder = image_webp::WebPDecoder::new(std::io::Cursor::new(bytes))
        .map_err(|e| Error::image(path, e.to_string()))?;
    let (width, height) = decoder.dimensions();
    let size = decoder
        .output_buffer_size()
        .ok_or_else(|| Error::image(path, "the WebP is too large to decode"))?;
    let mut buffer = vec![0; size];
    decoder
        .read_image(&mut buffer)
        .map_err(|e| Error::image(path, e.to_string()))?;

    // `read_image` writes RGB when the image has no alpha, RGBA when it has.
    let data = if decoder.has_alpha() {
        buffer
    } else {
        let mut out = Vec::with_capacity(buffer.len() / 3 * 4);
        for pixel in buffer.as_chunks::<3>().0 {
            out.extend_from_slice(pixel);
            out.push(255);
        }
        out
    };

    Ok(crate::textures::Image {
        width,
        height,
        data,
    })
}

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

    /// A 1×1 lossless WebP of opaque (255, 0, 0), as libwebp writes it.
    const RED_LOSSLESS: [u8; 36] = [
        0x52, 0x49, 0x46, 0x46, 0x1c, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50, 0x56, 0x50, 0x38,
        0x4c, 0x0f, 0x00, 0x00, 0x00, 0x2f, 0x00, 0x00, 0x00, 0x00, 0x07, 0x10, 0xfd, 0x8f, 0xfe,
        0x07, 0x22, 0xa2, 0xff, 0x01, 0x00,
    ];

    #[test]
    fn webp_is_sniffed_and_decoded() {
        assert!(is_webp(&RED_LOSSLESS));
        for texture in [
            TextureLoader::new().from_bytes(&RED_LOSSLESS, Some("image/webp")),
            TextureLoader::new().from_bytes(&RED_LOSSLESS, None),
        ] {
            let texture = texture.unwrap();
            assert_eq!(texture.size(), (1, 1));
            assert_eq!(
                texture.borrow().data.as_deref(),
                Some(&[255, 0, 0, 255][..])
            );
        }
    }

    #[test]
    fn avif_is_refused_by_name() {
        let header = b"\0\0\0\x1cftypavif\0\0\0\0avifmif1miaf";
        assert!(is_avif(header));
        let error = TextureLoader::new()
            .from_bytes(header, Some("image/avif"))
            .err()
            .unwrap()
            .to_string();
        assert!(error.contains("AVIF"), "{error}");
    }
}