teksilo-canvas 0.16.0

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! Raster decoding: PNG, JPEG and static WebP → RGBA pixel data.
//!
//! Three formats, one output contract: straight-alpha (non-premultiplied) RGBA8,
//! row-major, `width * height * 4` bytes. Callers downstream — the texture
//! atlas, the mip builder, the alpha-mask path — all assume that shape, so each
//! decoder normalises into it rather than exposing its format's native layout.
//!
//! [`RasterIcon::decode`] sniffs the format from the leading magic bytes and
//! dispatches. Prefer it over the per-format entry points for anything the user
//! supplied: a file's extension is a claim, not evidence, and a `.png` that is
//! really a JPEG is common enough to be worth being immune to.

use std::sync::Arc;

use crate::exif::{apply_orientation, orientation_from_exif};

/// Error type for image decoding failures.
#[derive(Debug, Clone, PartialEq, thiserror::Error)]
pub enum ImageDecodeError {
    /// The image data is malformed or unsupported.
    #[error("image decode error: {0}")]
    InvalidData(String),
    /// The image has zero dimensions.
    #[error("image has zero dimensions")]
    EmptyImage,
    /// The leading bytes match no format this crate can decode.
    #[error("unsupported image format (supported: PNG, JPEG, WebP)")]
    UnsupportedFormat,
}

/// A raster format this crate can decode, as identified from magic bytes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ImageFormat {
    /// PNG, including palette and 16-bit variants.
    Png,
    /// Baseline or progressive JPEG.
    Jpeg,
    /// Static WebP. Animated WebP is [`crate::AnimatedIcon`]'s job.
    Webp,
}

impl ImageFormat {
    /// The IANA media type, for callers that must record or transmit one.
    pub fn mime_type(self) -> &'static str {
        match self {
            Self::Png => "image/png",
            Self::Jpeg => "image/jpeg",
            Self::Webp => "image/webp",
        }
    }

    /// The conventional lowercase file extension, without a dot.
    pub fn extension(self) -> &'static str {
        match self {
            Self::Png => "png",
            Self::Jpeg => "jpg",
            Self::Webp => "webp",
        }
    }

    /// Identify the format from leading magic bytes, ignoring any filename.
    pub fn sniff(data: &[u8]) -> Option<Self> {
        if data.starts_with(&[0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a]) {
            return Some(Self::Png);
        }
        // Every JPEG variant opens with SOI (FFD8) followed by a marker.
        if data.starts_with(&[0xff, 0xd8, 0xff]) {
            return Some(Self::Jpeg);
        }
        // RIFF container whose form type is WEBP: bytes 0..4 and 8..12.
        if data.len() >= 12 && data.starts_with(b"RIFF") && &data[8..12] == b"WEBP" {
            return Some(Self::Webp);
        }
        None
    }
}

/// A decoded raster icon: RGBA pixel data at a fixed size.
///
/// The pixels are reference-counted, so a clone shares them rather than
/// copying them.
#[derive(Debug, Clone)]
pub struct RasterIcon {
    pixels: Arc<[u8]>,
    width: u32,
    height: u32,
    /// Process-unique identity of these pixels, assigned by every
    /// constructor and copied by `Clone`. The fields are private and there
    /// is no mutator, so equal keys always mean equal pixels.
    texture_key: u64,
}

impl RasterIcon {
    /// The one place a `RasterIcon` is assembled, so every constructor
    /// assigns a fresh texture key.
    fn with_pixels(pixels: Vec<u8>, width: u32, height: u32) -> Self {
        static NEXT_TEXTURE_KEY: std::sync::atomic::AtomicU64 =
            std::sync::atomic::AtomicU64::new(1);
        Self {
            pixels: pixels.into(),
            width,
            height,
            texture_key: NEXT_TEXTURE_KEY.fetch_add(1, std::sync::atomic::Ordering::Relaxed),
        }
    }

    /// Process-unique identity of these pixels, for naming the texture they
    /// are uploaded to.
    ///
    /// Two icons decoded from the same bytes get different keys, and a clone
    /// keeps its original's key. A texture name built from it can therefore
    /// never show another icon's pixels, which a name built from the icon's
    /// address could once a new icon was allocated where a dropped one lived.
    #[doc(hidden)]
    pub fn texture_key(&self) -> u64 {
        self.texture_key
    }

    /// Decode an image, identifying the format from its magic bytes.
    ///
    /// This is the entry point for user-supplied data. It never consults a
    /// filename: extensions are frequently wrong, and a mislabelled file should
    /// open rather than fail. An unrecognised format yields
    /// [`ImageDecodeError::UnsupportedFormat`], whose message names what *is*
    /// supported so the error can be shown to a user unchanged.
    ///
    /// Every call returns a new image identity. `ImageWidget::new` and
    /// `IconWidget::from_raster` name their GPU texture after it, and that
    /// texture, with its mip chain, stays for the life of each window that
    /// drew it: it is never freed. Clones of the returned icon share its
    /// pixels and its texture; decoding the same bytes again gives a new
    /// identity and a new texture. Keep decoded images in an application cache
    /// and clone them, rather than decoding per widget or per realization: in
    /// a virtualized grid of runtime images such as album covers, a cover
    /// decoded each time its tile scrolls into view leaves one more texture
    /// behind each time.
    pub fn decode(data: &[u8]) -> Result<Self, ImageDecodeError> {
        match ImageFormat::sniff(data).ok_or(ImageDecodeError::UnsupportedFormat)? {
            ImageFormat::Png => Self::decode_png(data),
            ImageFormat::Jpeg => Self::decode_jpeg(data),
            ImageFormat::Webp => Self::decode_webp(data),
        }
    }

    /// Decode a PNG image from raw bytes.
    ///
    /// Palette, grayscale, `tRNS`-keyed and 16-bit PNGs are all normalised to
    /// 8-bit colour before the channel expansion below, so the match on
    /// `color_type` only ever sees the four direct forms.
    pub fn decode_png(data: &[u8]) -> Result<Self, ImageDecodeError> {
        let mut decoder = png::Decoder::new(std::io::Cursor::new(data));
        // Palette PNGs are extremely common (every screenshot tool and every
        // "save for web" path emits them) and 16-bit ones are not rare either.
        // Without this the former was rejected outright and the latter decoded
        // as if it were 8-bit, silently halving the image and shredding it.
        decoder.set_transformations(png::Transformations::normalize_to_color8());
        let mut reader = decoder
            .read_info()
            .map_err(|e| ImageDecodeError::InvalidData(e.to_string()))?;
        let buffer_size = reader.output_buffer_size().ok_or_else(|| {
            ImageDecodeError::InvalidData("PNG output buffer size unavailable".into())
        })?;
        let mut buf = vec![0u8; buffer_size];
        let info = reader
            .next_frame(&mut buf)
            .map_err(|e| ImageDecodeError::InvalidData(e.to_string()))?;
        buf.truncate(info.buffer_size());
        let width = info.width;
        let height = info.height;
        if width == 0 || height == 0 {
            return Err(ImageDecodeError::EmptyImage);
        }
        // Convert to RGBA if needed
        let rgba = match info.color_type {
            png::ColorType::Rgba => buf,
            png::ColorType::Rgb => {
                let mut rgba = Vec::with_capacity((width * height * 4) as usize);
                for chunk in buf.chunks(3) {
                    rgba.extend_from_slice(chunk);
                    rgba.push(255);
                }
                rgba
            }
            png::ColorType::GrayscaleAlpha => {
                let mut rgba = Vec::with_capacity((width * height * 4) as usize);
                for chunk in buf.chunks(2) {
                    let g = chunk[0];
                    let a = chunk[1];
                    rgba.extend_from_slice(&[g, g, g, a]);
                }
                rgba
            }
            png::ColorType::Grayscale => {
                let mut rgba = Vec::with_capacity((width * height * 4) as usize);
                for &g in &buf {
                    rgba.extend_from_slice(&[g, g, g, 255]);
                }
                rgba
            }
            // `normalize_to_color8` expands the palette before we get here, so
            // this arm is unreachable in practice; treat it as malformed rather
            // than panicking if a future png release changes that.
            png::ColorType::Indexed => {
                return Err(ImageDecodeError::InvalidData(
                    "palette PNG was not expanded by the decoder".into(),
                ));
            }
        };
        Ok(Self::with_pixels(rgba, width, height))
    }

    /// Decode a JPEG image from raw bytes, honouring its EXIF orientation.
    ///
    /// JPEG has no alpha channel, so every pixel comes back fully opaque. The
    /// orientation tag *is* applied here rather than being reported to the
    /// caller: a decoded buffer that still needs an out-of-band rotation is a
    /// trap, since every consumer would have to remember to ask.
    pub fn decode_jpeg(data: &[u8]) -> Result<Self, ImageDecodeError> {
        use zune_core::bytestream::ZCursor;
        use zune_core::colorspace::ColorSpace;
        use zune_core::options::DecoderOptions;

        let options = DecoderOptions::default().jpeg_set_out_colorspace(ColorSpace::RGBA);
        let mut decoder = zune_jpeg::JpegDecoder::new_with_options(ZCursor::new(data), options);
        let mut pixels = decoder
            .decode()
            .map_err(|e| ImageDecodeError::InvalidData(e.to_string()))?;
        // JPEG has no alpha channel, so the fourth byte is ours to define and
        // must be fully opaque. This is not belt-and-braces: for a 4-component
        // (CMYK/YCCK) JPEG — what Adobe and most print workflows emit — the
        // decoder's RGBA path leaves a colour channel sitting in the alpha
        // slot, and the photo composites semi-transparently over the page.
        for px in pixels.as_chunks_mut::<4>().0 {
            px[3] = 255;
        }
        let info = decoder
            .info()
            .ok_or_else(|| ImageDecodeError::InvalidData("JPEG headers not decoded".into()))?;

        let width = u32::from(info.width);
        let height = u32::from(info.height);
        if width == 0 || height == 0 {
            return Err(ImageDecodeError::EmptyImage);
        }
        if pixels.len() < (width as usize) * (height as usize) * 4 {
            return Err(ImageDecodeError::InvalidData(
                "JPEG decoded to fewer pixels than its declared size".into(),
            ));
        }

        let orientation = info
            .exif_data
            .as_deref()
            .map(orientation_from_exif)
            .unwrap_or_default();
        let (pixels, width, height) = apply_orientation(pixels, width, height, orientation);

        Ok(Self::with_pixels(pixels, width, height))
    }

    /// Decode a static WebP image from raw bytes.
    pub fn decode_webp(data: &[u8]) -> Result<Self, ImageDecodeError> {
        let decoder = image_webp::WebPDecoder::new(std::io::Cursor::new(data))
            .map_err(|e| ImageDecodeError::InvalidData(e.to_string()))?;

        let (width, height) = decoder.dimensions();
        if width == 0 || height == 0 {
            return Err(ImageDecodeError::EmptyImage);
        }

        let buf_size = decoder
            .output_buffer_size()
            .unwrap_or((width * height * 4) as usize);
        let mut buf = vec![0u8; buf_size];
        let mut decoder = decoder;
        decoder
            .read_image(&mut buf)
            .map_err(|e| ImageDecodeError::InvalidData(e.to_string()))?;

        // The output is always RGBA when output_buffer_size indicates 4 bytes/pixel.
        // If the buffer is smaller (RGB), expand to RGBA.
        let expected_rgba = (width * height * 4) as usize;
        if buf.len() < expected_rgba {
            let mut rgba = Vec::with_capacity(expected_rgba);
            for chunk in buf.chunks(3) {
                rgba.extend_from_slice(chunk);
                rgba.push(255);
            }
            buf = rgba;
        }

        Ok(Self::with_pixels(buf, width, height))
    }

    /// Convert to an alpha mask for tintable rendering.
    /// The alpha channel is computed from luminance: `alpha = lum * original_alpha`.
    /// RGB is set to white (255, 255, 255) so the shader's monochrome
    /// path (`vertex.rgb * tex.a`) produces the tint color correctly.
    pub fn to_alpha_mask(&self) -> Self {
        let mut mask = Vec::with_capacity(self.pixels.len());
        for chunk in self.pixels.chunks(4) {
            let r = chunk[0] as f32 / 255.0;
            let g = chunk[1] as f32 / 255.0;
            let b = chunk[2] as f32 / 255.0;
            let a = chunk[3] as f32 / 255.0;
            // sRGB luminance
            let lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
            let alpha = (lum * a * 255.0) as u8;
            mask.extend_from_slice(&[255, 255, 255, alpha]);
        }
        Self::with_pixels(mask, self.width, self.height)
    }

    /// Scale down so neither side exceeds `max_edge`, preserving aspect ratio.
    ///
    /// Returns `None` when the image already fits, so a caller can keep the
    /// original buffer without copying it. Upscaling is never performed: this
    /// exists to bound work and memory, and enlarging would do the opposite.
    ///
    /// The reduction runs as repeated halving down to within 2× of the target,
    /// then one area-average step to the exact size. Halving first is a large
    /// constant-factor win on big photographs — each pass reads a quarter of
    /// the pixels of the one before — and the final area step is what allows an
    /// arbitrary, non-power-of-two result.
    pub fn downsample_to_max(&self, max_edge: u32) -> Option<Self> {
        let (target_w, target_h) = crate::resample::fit_within(self.width, self.height, max_edge)?;

        let mut pixels = self.pixels.to_vec();
        let mut w = self.width;
        let mut h = self.height;
        // Halve while the next halving would still not undershoot the target.
        while w / 2 >= target_w && h / 2 >= target_h && w > 1 && h > 1 {
            let (nw, nh, next) = crate::resample::downsample_half(&pixels, w, h);
            pixels = next;
            w = nw;
            h = nh;
        }
        if (w, h) != (target_w, target_h) {
            pixels = crate::resample::resample_area(&pixels, w, h, target_w, target_h);
        }

        Some(Self::with_pixels(pixels, target_w, target_h))
    }

    /// Create from pre-decoded RGBA pixel data.
    ///
    /// Every call returns a new image identity, with the same GPU cost as
    /// [`decode`](Self::decode): once drawn, it keeps a texture, with its mip
    /// chain, for the life of each window that drew it, and the texture is
    /// never freed. Clones share the pixels and the texture; another
    /// `from_raw` with the same bytes gets a texture of its own. Build each
    /// image once, keep it in an application cache, and clone it where it is
    /// shown.
    pub fn from_raw(pixels: Vec<u8>, width: u32, height: u32) -> Self {
        Self::with_pixels(pixels, width, height)
    }

    /// Image width in pixels.
    pub fn width(&self) -> u32 {
        self.width
    }

    /// Image height in pixels.
    pub fn height(&self) -> u32 {
        self.height
    }

    /// Raw RGBA pixel data.
    pub fn pixels(&self) -> &[u8] {
        &self.pixels
    }

    /// The RGBA pixel data as the shared buffer this icon holds.
    ///
    /// Cloning the returned `Arc` copies no pixels, which is what lets a
    /// widget queue them on every paint through
    /// [`Canvas::ensure_shared_image_registered`](crate::Canvas::ensure_shared_image_registered).
    pub fn shared_pixels(&self) -> &Arc<[u8]> {
        &self.pixels
    }
}

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

    /// Minimal valid 1x1 white RGBA PNG (generated from spec).
    fn minimal_png_rgba() -> Vec<u8> {
        // Create a 1x1 white RGBA PNG in memory using the png crate
        let mut buf = Vec::new();
        {
            let mut encoder = png::Encoder::new(&mut buf, 1, 1);
            encoder.set_color(png::ColorType::Rgba);
            encoder.set_depth(png::BitDepth::Eight);
            let mut writer = encoder.write_header().unwrap();
            writer.write_image_data(&[255, 255, 255, 255]).unwrap();
        }
        buf
    }

    /// Minimal 2x2 RGBA PNG with varying alpha.
    fn test_png_2x2() -> Vec<u8> {
        let mut buf = Vec::new();
        {
            let mut encoder = png::Encoder::new(&mut buf, 2, 2);
            encoder.set_color(png::ColorType::Rgba);
            encoder.set_depth(png::BitDepth::Eight);
            let mut writer = encoder.write_header().unwrap();
            #[rustfmt::skip]
            writer.write_image_data(&[
                255, 0, 0, 255,    // red, opaque
                0, 255, 0, 128,    // green, half-transparent
                0, 0, 255, 255,    // blue, opaque
                0, 0, 0, 0,        // black, transparent
            ]).unwrap();
        }
        buf
    }

    #[test]
    fn decode_png_1x1() {
        let data = minimal_png_rgba();
        let icon = RasterIcon::decode_png(&data).unwrap();
        assert_eq!(icon.width(), 1);
        assert_eq!(icon.height(), 1);
        assert_eq!(icon.pixels(), &[255, 255, 255, 255]);
    }

    #[test]
    fn decode_png_2x2() {
        let data = test_png_2x2();
        let icon = RasterIcon::decode_png(&data).unwrap();
        assert_eq!(icon.width(), 2);
        assert_eq!(icon.height(), 2);
        assert_eq!(icon.pixels().len(), 16);
    }

    #[test]
    fn decode_png_invalid() {
        let result = RasterIcon::decode_png(b"not a png");
        assert!(result.is_err());
    }

    #[test]
    fn to_alpha_mask_white_stays_opaque() {
        let icon = RasterIcon::with_pixels(vec![255, 255, 255, 255], 1, 1);
        let mask = icon.to_alpha_mask();
        // White pixel → lum=1.0, alpha=255 → mask alpha=255
        assert_eq!(mask.pixels()[0], 255); // R = white
        assert_eq!(mask.pixels()[3], 255); // A = full
    }

    #[test]
    fn to_alpha_mask_black_becomes_transparent() {
        let icon = RasterIcon::with_pixels(vec![0, 0, 0, 255], 1, 1);
        let mask = icon.to_alpha_mask();
        // Black pixel → lum=0, alpha=0
        assert_eq!(mask.pixels()[3], 0);
    }

    #[test]
    fn to_alpha_mask_preserves_dimensions() {
        let data = test_png_2x2();
        let icon = RasterIcon::decode_png(&data).unwrap();
        let mask = icon.to_alpha_mask();
        assert_eq!(mask.width(), 2);
        assert_eq!(mask.height(), 2);
        assert_eq!(mask.pixels().len(), 16);
    }

    #[test]
    fn every_constructor_assigns_a_distinct_texture_key() {
        let data = test_png_2x2();
        let a = RasterIcon::decode_png(&data).unwrap();
        let b = RasterIcon::decode_png(&data).unwrap();
        let raw = RasterIcon::from_raw(vec![0; 4], 1, 1);
        let mask = a.to_alpha_mask();
        let keys = [
            a.texture_key(),
            b.texture_key(),
            raw.texture_key(),
            mask.texture_key(),
        ];
        for (i, k) in keys.iter().enumerate() {
            assert!(
                keys[i + 1..].iter().all(|other| other != k),
                "keys must be pairwise distinct: {keys:?}"
            );
        }
    }

    #[test]
    fn a_clone_keeps_its_texture_key() {
        let icon = RasterIcon::from_raw(vec![1, 2, 3, 4], 1, 1);
        assert_eq!(icon.clone().texture_key(), icon.texture_key());
    }

    #[test]
    fn a_clone_shares_its_pixels() {
        let icon = RasterIcon::from_raw(vec![1, 2, 3, 4], 1, 1);
        let clone = icon.clone();
        assert!(Arc::ptr_eq(icon.shared_pixels(), clone.shared_pixels()));
    }

    #[test]
    fn an_icon_allocated_where_a_dropped_one_lived_gets_a_new_key() {
        // The allocator usually hands the freed slot straight back, which is
        // exactly the case an address-based name got wrong.
        let first = Box::new(RasterIcon::from_raw(vec![255; 4], 1, 1));
        let first_key = first.texture_key();
        drop(first);
        let second = Box::new(RasterIcon::from_raw(vec![0; 4], 1, 1));
        assert_ne!(second.texture_key(), first_key);
    }
}