Skip to main content

three_rs/loaders/
texture_loader.rs

1//! Port of `three.js/src/loaders/TextureLoader.js` (+ the PNG, JPEG, GIF and
2//! WebP decodes that `ImageLoader` / `createImageBitmap` get from the
3//! browser).
4//!
5//! AVIF is the one format a page's `createImageBitmap` decodes that the port
6//! does not: there is no pure-Rust AV1 decoder yet that both builds for wasm32
7//! and decodes every AVIF image in the three.js examples (issue #179 has the
8//! evaluation). An AVIF image is refused with an error that says so, rather
9//! than handed to the JPEG decoder to fail on.
10//!
11//! The page's load is asynchronous, but the harness fires its single RAF only
12//! once the network is idle, so the image is always present for the graded
13//! frame; here it is decoded synchronously.
14
15use std::path::Path;
16
17use crate::error::Error;
18use crate::textures::Texture;
19
20/// three.js' `TextureLoader`.
21pub struct TextureLoader;
22
23impl Default for TextureLoader {
24    fn default() -> Self {
25        Self::new()
26    }
27}
28
29impl TextureLoader {
30    /// A loader with no state — `new TextureLoader()`.
31    pub fn new() -> Self {
32        Self
33    }
34
35    /// `new TextureLoader().load( url )`. The loader leaves every `Texture`
36    /// default in place — `flipY` true, `generateMipmaps` true,
37    /// `LinearFilter` / `LinearMipmapLinearFilter`, `ClampToEdgeWrapping`,
38    /// anisotropy 1, `NoColorSpace` (the example never sets `colorSpace`, so
39    /// `uv_grid_opengl.jpg` is sampled as raw bytes and no sRGB decode
40    /// happens in the shader).
41    pub fn load<P: AsRef<Path>>(&self, url: P) -> Result<Texture, Error> {
42        let path = url.as_ref();
43        let bytes = crate::io::read(path)?;
44        // `ImageLoader` gives the bytes to the browser, which picks the decoder
45        // from the sniffed type and not from the extension.
46        let image = decode_image(path, &bytes)?;
47        Ok(Texture::new(image.width, image.height, Some(image.data)))
48    }
49
50    /// The bytes of an image the loader never sees as a file: a glTF image
51    /// stored in the BIN chunk or a data URI. `ImageBitmapLoader` /
52    /// `createImageBitmap` in the browser; here the decode is picked by the
53    /// glTF `mimeType` when there is one and by the file's magic otherwise,
54    /// because `images[ i ].mimeType` is only required for a `bufferView`
55    /// source.
56    ///
57    /// The `Texture` comes back with the same defaults `load()` gives one;
58    /// `GLTFLoader` is what sets `flipY`, the wrapping and the colour space.
59    pub fn from_bytes(&self, bytes: &[u8], mime_type: Option<&str>) -> Result<Texture, Error> {
60        let path = Path::new("<glTF image>");
61        let image = match mime_type {
62            Some("image/png") => decode_png(path, bytes)?,
63            Some("image/jpeg") => decode_jpeg_bytes(path, bytes)?,
64            Some("image/webp") => decode_webp(path, bytes)?,
65            _ => decode_image(path, bytes)?,
66        };
67
68        Ok(Texture::new(image.width, image.height, Some(image.data)))
69    }
70}
71
72/// `ImageLoader` gives the bytes to the browser, which picks the decoder from
73/// the sniffed type and not from the extension. Four magic numbers cover
74/// everything the ladder loads, and anything else is taken for a JPEG. Shared
75/// with [`CubeTextureLoader`], whose six
76/// faces are PNG in `webgpu_materials_basic` and JPEG in
77/// `webgpu_pmrem_scene`.
78///
79/// [`CubeTextureLoader`]: super::CubeTextureLoader
80pub(crate) fn decode_image(path: &Path, bytes: &[u8]) -> Result<crate::textures::Image, Error> {
81    if bytes.starts_with(b"GIF") {
82        super::gif::decode(path, bytes)
83    } else if bytes.starts_with(&[0x89, b'P', b'N', b'G']) {
84        decode_png(path, bytes)
85    } else if is_webp(bytes) {
86        decode_webp(path, bytes)
87    } else if is_avif(bytes) {
88        Err(Error::image(
89            path,
90            "AVIF is not decoded: no pure-Rust AV1 decoder is fit yet (issue #179)",
91        ))
92    } else {
93        decode_jpeg_bytes(path, bytes)
94    }
95}
96
97/// `createImageBitmap` on a PNG: 8-bit RGBA, top-down, with every source
98/// format expanded to it (palette and grey both reach the GPU as RGBA8 in the
99/// browser too). Unlike the JPEG path this is exact — PNG is lossless and the
100/// decoders agree byte for byte.
101pub(crate) fn decode_png(path: &Path, bytes: &[u8]) -> Result<crate::textures::Image, Error> {
102    let mut decoder = png::Decoder::new(std::io::Cursor::new(bytes));
103    // `EXPAND` takes palette, grey and `tRNS` up to 8-bit RGB/RGBA, so the only
104    // cases left below are the four 8-bit ones (and 16-bit, which is stripped).
105    decoder.set_transformations(png::Transformations::EXPAND | png::Transformations::STRIP_16);
106
107    let mut reader = decoder
108        .read_info()
109        .map_err(|e| Error::image(path, e.to_string()))?;
110    // `output_buffer_size()` is `None` when the dimensions overflow `usize`.
111    let size = reader
112        .output_buffer_size()
113        .ok_or_else(|| Error::image(path, "PNG dimensions overflow".to_string()))?;
114    let mut buffer = vec![0; size];
115    let info = reader
116        .next_frame(&mut buffer)
117        .map_err(|e| Error::image(path, e.to_string()))?;
118    buffer.truncate(info.buffer_size());
119
120    let pixels = (info.width as usize) * (info.height as usize);
121    let data = match info.color_type {
122        png::ColorType::Rgba => buffer,
123        png::ColorType::Rgb => {
124            let mut out = Vec::with_capacity(pixels * 4);
125            for pixel in buffer.as_chunks::<3>().0 {
126                out.extend_from_slice(pixel);
127                out.push(255);
128            }
129            out
130        }
131        png::ColorType::Grayscale => {
132            let mut out = Vec::with_capacity(pixels * 4);
133            for &value in &buffer {
134                out.extend_from_slice(&[value, value, value, 255]);
135            }
136            out
137        }
138        png::ColorType::GrayscaleAlpha => {
139            let mut out = Vec::with_capacity(pixels * 4);
140            for pixel in buffer.as_chunks::<2>().0 {
141                out.extend_from_slice(&[pixel[0], pixel[0], pixel[0], pixel[1]]);
142            }
143            out
144        }
145        png::ColorType::Indexed => {
146            return Err(Error::image(path, "the PNG palette was not expanded"));
147        }
148    };
149
150    Ok(crate::textures::Image {
151        width: info.width,
152        height: info.height,
153        data,
154    })
155}
156
157/// What the browser hands `copyExternalImageToTexture`: 8-bit RGBA, top-down,
158/// opaque.
159///
160/// Chromium decodes through libjpeg-turbo and this goes through `zune-jpeg`,
161/// so individual samples can differ by the rounding of the inverse DCT; the
162/// PNG and GIF paths beside it are exact.
163pub(crate) fn decode_jpeg_bytes(
164    path: &Path,
165    bytes: &[u8],
166) -> Result<crate::textures::Image, Error> {
167    let options = zune_jpeg::zune_core::options::DecoderOptions::default()
168        .jpeg_set_out_colorspace(zune_jpeg::zune_core::colorspace::ColorSpace::RGBA);
169
170    let mut decoder =
171        zune_jpeg::JpegDecoder::new_with_options(std::io::Cursor::new(bytes), options);
172
173    let data = decoder
174        .decode()
175        .map_err(|e| Error::image(path, e.to_string()))?;
176    let (width, height) = decoder
177        .dimensions()
178        .ok_or_else(|| Error::image(path, "the JPEG has no dimensions"))?;
179
180    Ok(crate::textures::Image {
181        width: width as u32,
182        height: height as u32,
183        data,
184    })
185}
186
187/// A RIFF container whose form type is `WEBP` — the WHATWG mime-sniffing
188/// signature `createImageBitmap` goes by.
189fn is_webp(bytes: &[u8]) -> bool {
190    bytes.len() >= 12 && bytes.starts_with(b"RIFF") && &bytes[8..12] == b"WEBP"
191}
192
193/// An ISO-BMFF `ftyp` box whose major brand is `avif` or `avis`.
194fn is_avif(bytes: &[u8]) -> bool {
195    bytes.len() >= 12 && &bytes[4..8] == b"ftyp" && matches!(&bytes[8..12], b"avif" | b"avis")
196}
197
198/// `createImageBitmap` on a WebP: 8-bit RGBA, top-down, lossy (VP8, with or
199/// without an `ALPH` plane) or lossless (VP8L).
200///
201/// Exact, not merely close: `image-webp` upsamples the lossy chroma with the
202/// same "fancy" filter and fixed-point YUV→RGB as libwebp, which is what
203/// Chromium decodes with, and `tests/loaders_webp.rs` checks every WebP image
204/// in the three.js examples against Chromium's own decode byte for byte. An
205/// animated WebP gives its first frame, as `createImageBitmap` does; no
206/// three.js asset is animated, so that case is untested.
207pub(crate) fn decode_webp(path: &Path, bytes: &[u8]) -> Result<crate::textures::Image, Error> {
208    let mut decoder = image_webp::WebPDecoder::new(std::io::Cursor::new(bytes))
209        .map_err(|e| Error::image(path, e.to_string()))?;
210    let (width, height) = decoder.dimensions();
211    let size = decoder
212        .output_buffer_size()
213        .ok_or_else(|| Error::image(path, "the WebP is too large to decode"))?;
214    let mut buffer = vec![0; size];
215    decoder
216        .read_image(&mut buffer)
217        .map_err(|e| Error::image(path, e.to_string()))?;
218
219    // `read_image` writes RGB when the image has no alpha, RGBA when it has.
220    let data = if decoder.has_alpha() {
221        buffer
222    } else {
223        let mut out = Vec::with_capacity(buffer.len() / 3 * 4);
224        for pixel in buffer.as_chunks::<3>().0 {
225            out.extend_from_slice(pixel);
226            out.push(255);
227        }
228        out
229    };
230
231    Ok(crate::textures::Image {
232        width,
233        height,
234        data,
235    })
236}
237
238#[cfg(test)]
239mod tests {
240    use super::*;
241
242    /// A 1×1 lossless WebP of opaque (255, 0, 0), as libwebp writes it.
243    const RED_LOSSLESS: [u8; 36] = [
244        0x52, 0x49, 0x46, 0x46, 0x1c, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50, 0x56, 0x50, 0x38,
245        0x4c, 0x0f, 0x00, 0x00, 0x00, 0x2f, 0x00, 0x00, 0x00, 0x00, 0x07, 0x10, 0xfd, 0x8f, 0xfe,
246        0x07, 0x22, 0xa2, 0xff, 0x01, 0x00,
247    ];
248
249    #[test]
250    fn webp_is_sniffed_and_decoded() {
251        assert!(is_webp(&RED_LOSSLESS));
252        for texture in [
253            TextureLoader::new().from_bytes(&RED_LOSSLESS, Some("image/webp")),
254            TextureLoader::new().from_bytes(&RED_LOSSLESS, None),
255        ] {
256            let texture = texture.unwrap();
257            assert_eq!(texture.size(), (1, 1));
258            assert_eq!(
259                texture.borrow().data.as_deref(),
260                Some(&[255, 0, 0, 255][..])
261            );
262        }
263    }
264
265    #[test]
266    fn avif_is_refused_by_name() {
267        let header = b"\0\0\0\x1cftypavif\0\0\0\0avifmif1miaf";
268        assert!(is_avif(header));
269        let error = TextureLoader::new()
270            .from_bytes(header, Some("image/avif"))
271            .err()
272            .unwrap()
273            .to_string();
274        assert!(error.contains("AVIF"), "{error}");
275    }
276}