//! Image decoding and encoding utilities, wrapping the `image` crate

//! with Azul's FFI-compatible types (`RawImage`, `RawImageFormat`).

//!

//! - [`decode`]: Decodes image bytes in any supported format into a [`RawImage`].

//! - [`encode`]: Encodes a [`RawImage`] into various output formats (PNG, JPEG, BMP, etc.).

#[cfg(feature = "std")]

pub mod decode {

    use core::fmt;

    use azul_core::resources::{RawImage, RawImageFormat};

    use azul_css::{impl_result, impl_result_inner, U8Vec};

    use image::{

        error::{ImageError, LimitError, LimitErrorKind},

        DynamicImage,

    };

    /// Errors that can occur when decoding an image from raw bytes.

    #[derive(Debug, Copy, Clone, PartialEq, PartialOrd, Ord, Eq, Hash)]

    #[repr(C)]

    pub enum DecodeImageError {

        InsufficientMemory,

        DimensionError,

        UnsupportedImageFormat,

        Unknown,

    }

    impl fmt::Display for DecodeImageError {

                ),

                Self::DimensionError => {

                }

                Self::UnsupportedImageFormat => {

                }

            }

    }

            },

        }

    impl_result!(

        RawImage,

        DecodeImageError,

        ResultRawImageDecodeImageError,

        copy = false,

        [Debug, Clone]

    );

    /// Decodes image bytes in any supported format into a [`RawImage`].

    ///

    /// The image format is guessed from the byte contents. Returns the decoded

    /// pixel data along with dimensions and format information.

        use azul_core::resources::RawImageData;

            }

        };

            }

        };

            _ => {

            }

        };

    #[cfg(test)]

    mod autotest_generated {

        use std::collections::BTreeSet;

        use image::error::{

            DecodingError, ImageFormatHint, ParameterError, ParameterErrorKind, UnsupportedError,

            UnsupportedErrorKind,

        };

        use super::*;

        const ALL_ERRORS: [DecodeImageError; 4] = [

            DecodeImageError::InsufficientMemory,

            DecodeImageError::DimensionError,

            DecodeImageError::UnsupportedImageFormat,

            DecodeImageError::Unknown,

        ];

        fn err_of(r: &ResultRawImageDecodeImageError) -> DecodeImageError {

            match r.as_result() {

                Ok(_) => panic!("expected Err, got Ok"),

                Err(e) => *e,

            }

        }

        // --- DecodeImageError::fmt (serializer) ---------------------------------

        #[test]

        fn display_every_variant_is_non_empty_and_unique() {

            let rendered = ALL_ERRORS.iter().map(|e| e.to_string()).collect::<Vec<_>>();

            for (e, s) in ALL_ERRORS.iter().zip(rendered.iter()) {

                assert!(!s.is_empty(), "empty Display for {e:?}");

                assert!(

                    s.starts_with("Error decoding image: "),

                    "unexpected Display prefix for {e:?}: {s}"

                );

            }

            let unique = rendered.iter().collect::<BTreeSet<_>>();

            assert_eq!(unique.len(), ALL_ERRORS.len(), "Display collides: {rendered:?}");

        }

        #[test]

        fn display_text_is_stable() {

            assert_eq!(

                DecodeImageError::DimensionError.to_string(),

                "Error decoding image: Wrong dimensions"

            );

            assert_eq!(

                DecodeImageError::UnsupportedImageFormat.to_string(),

                "Error decoding image: Invalid data format"

            );

            assert_eq!(

                DecodeImageError::Unknown.to_string(),

                "Error decoding image: Unknown error"

            );

            // NOTE: the InsufficientMemory arm says "encoding operation" inside a *decode*

            // error. Pinned here because it is user-visible text, not because it is right.

            assert_eq!(

                DecodeImageError::InsufficientMemory.to_string(),

                "Error decoding image: Not enough memory available to perform encoding operation"

            );

        }

        #[test]

        fn display_ignores_width_and_precision_specs_without_panicking() {

            for e in ALL_ERRORS {

                // The impl writes straight to the formatter, so padding/precision are no-ops.

                let plain = format!("{e}");

                assert_eq!(format!("{e:>200}"), plain);

                assert_eq!(format!("{e:.1}"), plain);

                assert_eq!(format!("{e:^0}"), plain);

                assert!(!format!("{e:?}").is_empty());

            }

        }

        #[test]

        fn derived_ord_is_total_and_matches_declaration_order() {

            for (i, a) in ALL_ERRORS.iter().enumerate() {

                for (j, b) in ALL_ERRORS.iter().enumerate() {

                    assert_eq!(a.cmp(b), i.cmp(&j), "Ord disagrees for {a:?} vs {b:?}");

                    assert_eq!(a.partial_cmp(b), Some(a.cmp(b)));

                    assert_eq!(a == b, i == j);

                }

            }

        }

        // --- translate_image_error_decode (other) -------------------------------

        #[test]

        fn translate_maps_limit_kinds() {

            assert_eq!(

                translate_image_error_decode(ImageError::Limits(LimitError::from_kind(

                    LimitErrorKind::InsufficientMemory

                ))),

                DecodeImageError::InsufficientMemory

            );

            assert_eq!(

                translate_image_error_decode(ImageError::Limits(LimitError::from_kind(

                    LimitErrorKind::DimensionError

                ))),

                DecodeImageError::DimensionError

            );

            // The catch-all arm of the (non_exhaustive) LimitErrorKind match.

            assert_eq!(

                translate_image_error_decode(ImageError::Limits(LimitError::from_kind(

                    LimitErrorKind::Unsupported {

                        limits: image::Limits::default(),

                        supported: image::LimitSupport::default(),

                    }

                ))),

                DecodeImageError::Unknown

            );

        }

        #[test]

        fn translate_maps_every_other_variant_to_unknown() {

            let cases = vec![

                ImageError::IoError(std::io::Error::other("boom")),

                ImageError::Decoding(DecodingError::new(ImageFormatHint::Unknown, "bad chunk")),

                ImageError::Unsupported(UnsupportedError::from_format_and_kind(

                    ImageFormatHint::Unknown,

                    UnsupportedErrorKind::Format(ImageFormatHint::Unknown),

                )),

                // NOTE: a *parameter* dimension mismatch is NOT mapped to DimensionError --

                // only `Limits` errors are inspected. Pinning the lossy mapping.

                ImageError::Parameter(ParameterError::from_kind(

                    ParameterErrorKind::DimensionMismatch,

                )),

                ImageError::Parameter(ParameterError::from_kind(ParameterErrorKind::NoMoreData)),

            ];

            for c in cases {

                let debug = format!("{c:?}");

                assert_eq!(

                    translate_image_error_decode(c),

                    DecodeImageError::Unknown,

                    "unexpected mapping for {debug}"

                );

            }

        }

        // --- decode_raw_image_from_any_bytes (other / parser-ish) ---------------

        #[test]

        fn decode_empty_input_errors_without_panicking() {

            let r = decode_raw_image_from_any_bytes(&[]);

            assert!(r.is_err());

            assert_eq!(err_of(&r), DecodeImageError::Unknown);

        }

        #[test]

        fn decode_whitespace_and_text_bytes_error() {

            for input in [

                &b"   "[..],

                &b"\t\n\r\n"[..],

                &b"not an image at all"[..],

                "\u{1F600} combining a\u{0301}\u{0308}".as_bytes(),

                "\u{FEFF}\u{202E}\u{0000}".as_bytes(),

            ] {

                let r = decode_raw_image_from_any_bytes(input);

                assert!(r.is_err(), "unexpectedly decoded {input:?}");

                assert_eq!(err_of(&r), DecodeImageError::Unknown);

            }

        }

        #[test]

        fn decode_invalid_utf8_and_garbage_bytes_error() {

            for input in [

                &[0xFF, 0xFE, 0x00][..],

                &[0xFF][..],

                &[0x00, 0x00, 0x00, 0x00][..],

                &[0xC0, 0x80, 0xED, 0xA0, 0x80][..],

            ] {

                let r = decode_raw_image_from_any_bytes(input);

                assert!(r.is_err(), "unexpectedly decoded {input:?}");

                assert_eq!(err_of(&r), DecodeImageError::Unknown);

            }

        }

        #[test]

        fn decode_every_single_byte_input_errors() {

            for b in 0u8..=255 {

                let r = decode_raw_image_from_any_bytes(&[b]);

                assert!(r.is_err(), "single byte {b:#04X} decoded to an image");

            }

        }

        #[test]

        fn decode_extremely_long_garbage_does_not_hang_or_panic() {

            let huge = vec![0xAAu8; 1_000_000];

            let r = decode_raw_image_from_any_bytes(&huge);

            assert!(r.is_err());

            assert_eq!(err_of(&r), DecodeImageError::Unknown);

        }

        /// Valid magic bytes with a truncated / missing body: `guess_format` succeeds,

        /// the actual decode must then fail cleanly (never panic), regardless of which

        /// codec features are compiled in.

        #[test]

        fn decode_valid_magic_with_no_payload_errors() {

            let png_magic = b"\x89PNG\r\n\x1a\n";

            let gif_magic = b"GIF89a";

            let bmp_magic = b"BM";

            let jpeg_magic = b"\xFF\xD8\xFF";

            for magic in [&png_magic[..], &gif_magic[..], &bmp_magic[..], &jpeg_magic[..]] {

                let mut bytes = magic.to_vec();

                let r = decode_raw_image_from_any_bytes(&bytes);

                assert!(r.is_err(), "header-only input decoded: {magic:?}");

                // ... and with a garbage payload appended.

                bytes.extend(core::iter::repeat_n(0x7Fu8, 512));

                let r = decode_raw_image_from_any_bytes(&bytes);

                assert!(r.is_err(), "header + garbage decoded: {magic:?}");

            }

        }

        #[cfg(feature = "png")]

        fn png_of_2x2_rgba8(fill: u8) -> Vec<u8> {

            use azul_core::resources::RawImageData;

            let img = RawImage {

                pixels: RawImageData::U8(vec![fill; 16].into()),

                width: 2,

                height: 2,

                premultiplied_alpha: false,

                data_format: RawImageFormat::RGBA8,

                tag: Vec::<u8>::new().into(),

            };

            crate::image::encode::encode_png(&img)

                .into_result()

                .expect("png encode of a well-formed 2x2 RGBA8 image failed")

                .as_slice()

                .to_vec()

        }

        #[cfg(feature = "png")]

        #[test]

        fn decode_of_every_truncation_of_a_real_png_never_panics() {

            let bytes = png_of_2x2_rgba8(1);

            assert!(bytes.len() > 33, "PNG shorter than signature + IHDR");

            for len in 0..bytes.len() {

                let r = decode_raw_image_from_any_bytes(&bytes[..len]);

                match r.as_result() {

                    // A truncation that still decodes (the trailing IEND chunk is not load

                    // bearing for every decoder) must at least not invent geometry or pixels.

                    Ok(img) => {

                        assert_eq!(

                            (img.width, img.height),

                            (2, 2),

                            "truncation to {len} bytes resized the image"

                        );

                        assert_eq!(img.pixels.get_u8_vec_ref().expect("8-bit data").len(), 16);

                    }

                    // Anything cut off before the header is complete cannot possibly decode.

                    Err(e) => {

                        assert_eq!(*e, DecodeImageError::Unknown, "truncation to {len} bytes");

                    }

                }

                if len <= 33 {

                    assert!(r.is_err(), "a {len}-byte PNG prefix decoded to an image");

                }

            }

        }

        #[cfg(feature = "png")]

        #[test]

        fn decode_of_a_corrupted_png_never_panics_or_invents_geometry() {

            let bytes = png_of_2x2_rgba8(9);

            // Flip every byte of the stream in turn: CRC/zlib checks must reject, not panic.

            for i in 0..bytes.len() {

                let mut corrupted = bytes.clone();

                corrupted[i] ^= 0xFF;

                let r = decode_raw_image_from_any_bytes(&corrupted);

                // Ok is acceptable in principle (e.g. a flipped byte in a padding field),

                // the invariant under test is "no panic, and dimensions stay sane".

                if let Ok(img) = r.as_result() {

                    assert!(img.width <= 2 && img.height <= 2, "corrupt byte {i} grew the image");

                }

            }

        }

    }

}

#[cfg(feature = "std")]

pub mod encode {

    use alloc::vec::Vec;

    use core::fmt;

    use std::io::Cursor;

    use azul_core::resources::{RawImage, RawImageFormat};

    use azul_css::{impl_result, impl_result_inner, U8Vec};

    #[cfg(feature = "bmp")]

    use image::codecs::bmp::BmpEncoder;

    #[cfg(feature = "gif")]

    use image::codecs::gif::GifEncoder;

#[cfg(feature = "jpeg")]

    use image::codecs::jpeg::JpegEncoder;

    #[cfg(feature = "png")]

    use image::codecs::png::PngEncoder;

    #[cfg(feature = "pnm")]

    use image::codecs::pnm::PnmEncoder;

    #[cfg(feature = "tga")]

    use image::codecs::tga::TgaEncoder;

    #[cfg(feature = "tiff")]

    use image::codecs::tiff::TiffEncoder;

    use image::error::{ImageError, LimitError, LimitErrorKind};

    /// Errors that can occur when encoding a [`RawImage`] into a specific format.

    #[derive(Debug, Copy, Clone, PartialEq, PartialOrd, Ord, Eq, Hash)]

    #[repr(C)]

    pub enum EncodeImageError {

        /// Crate was not compiled with the given encoder flags

        EncoderNotAvailable,

        InsufficientMemory,

        DimensionError,

        InvalidData,

        Unknown,

    }

    impl fmt::Display for EncodeImageError {

            use self::EncodeImageError::{EncoderNotAvailable, InsufficientMemory, DimensionError, InvalidData, Unknown};

                ),

                ),

            }

    }

        }

            RawImageFormat::BGR8 => {

            }

            RawImageFormat::BGRA8 => {

            }

        }

            },

        }

    impl_result!(

        U8Vec,

        EncodeImageError,

        ResultU8VecEncodeImageError,

        copy = false,

        [Debug, Clone]

    );

    macro_rules! encode_func {

        ($func:ident, $encoder:ident, $feature:expr) => {

            #[cfg(feature = $feature)]

            pub fn $func(image: &RawImage) -> ResultU8VecEncodeImageError {

                let width = match u32::try_from(image.width) {

                    Ok(w) => w,

                    Err(_) => return ResultU8VecEncodeImageError::Err(EncodeImageError::DimensionError),

                };

                let height = match u32::try_from(image.height) {

                    Ok(h) => h,

                    Err(_) => return ResultU8VecEncodeImageError::Err(EncodeImageError::DimensionError),

                };

                let mut result = Vec::<u8>::new();

                {

                    let mut cursor = Cursor::new(&mut result);

                    let mut encoder = $encoder::new(&mut cursor);

                    let pixels = match image.pixels.get_u8_vec_ref() {

                        Some(s) => s,

                        None => {

                            return ResultU8VecEncodeImageError::Err(EncodeImageError::InvalidData);

                        }

                    };

                    let swapped = bgr_to_rgb_swap(pixels.as_ref(), image.data_format);

                    let pixel_bytes = swapped.as_deref().unwrap_or(pixels.as_ref());

                    if let Err(e) = encoder.encode(

                        pixel_bytes,

                        width,

                        height,

                        translate_rawimage_colortype(image.data_format).into(),

                    ) {

                        return ResultU8VecEncodeImageError::Err(translate_image_error_encode(e));

                    }

                }

                ResultU8VecEncodeImageError::Ok(result.into())

            }

            #[cfg(not(feature = $feature))]

        };

    }

    encode_func!(encode_bmp, BmpEncoder, "bmp");

    encode_func!(encode_tga, TgaEncoder, "tga");

    encode_func!(encode_tiff, TiffEncoder, "tiff");

    encode_func!(encode_gif, GifEncoder, "gif");

    encode_func!(encode_pnm, PnmEncoder, "pnm");

    #[cfg(feature = "png")]

    pub fn encode_png(image: &RawImage) -> ResultU8VecEncodeImageError {

        use image::ImageEncoder;

        let width = match u32::try_from(image.width) {

            Ok(w) => w,

            Err(_) => return ResultU8VecEncodeImageError::Err(EncodeImageError::DimensionError),

        };

        let height = match u32::try_from(image.height) {

            Ok(h) => h,

            Err(_) => return ResultU8VecEncodeImageError::Err(EncodeImageError::DimensionError),

        };

        let mut result = Vec::<u8>::new();

        {

            let mut cursor = Cursor::new(&mut result);

            let mut encoder = PngEncoder::new_with_quality(

                &mut cursor,

                image::codecs::png::CompressionType::Best,

                image::codecs::png::FilterType::Adaptive,

            );

            let pixels = match image.pixels.get_u8_vec_ref() {

                Some(s) => s,

                None => {

                    return ResultU8VecEncodeImageError::Err(EncodeImageError::InvalidData);

                }

            };

            let swapped = bgr_to_rgb_swap(pixels.as_ref(), image.data_format);

            let pixel_bytes = swapped.as_deref().unwrap_or(pixels.as_ref());

            if let Err(e) = encoder.write_image(

                pixel_bytes,

                width,

                height,

                translate_rawimage_colortype(image.data_format).into(),

            ) {

                return ResultU8VecEncodeImageError::Err(translate_image_error_encode(e));

            }

        }

        ResultU8VecEncodeImageError::Ok(result.into())

    }

    #[cfg(not(feature = "png"))]

    #[cfg(feature = "jpeg")]

    pub fn encode_jpeg(image: &RawImage, quality: u8) -> ResultU8VecEncodeImageError {

        let width = match u32::try_from(image.width) {

            Ok(w) => w,

            Err(_) => return ResultU8VecEncodeImageError::Err(EncodeImageError::DimensionError),

        };

        let height = match u32::try_from(image.height) {

            Ok(h) => h,

            Err(_) => return ResultU8VecEncodeImageError::Err(EncodeImageError::DimensionError),

        };

        let mut result = Vec::<u8>::new();

        {

            let mut cursor = Cursor::new(&mut result);

            let mut encoder = JpegEncoder::new_with_quality(&mut cursor, quality);

            let pixels = match image.pixels.get_u8_vec_ref() {

                Some(s) => s,

                None => {

                    return ResultU8VecEncodeImageError::Err(EncodeImageError::InvalidData);

                }

            };

            let swapped = bgr_to_rgb_swap(pixels.as_ref(), image.data_format);

            let pixel_bytes = swapped.as_deref().unwrap_or(pixels.as_ref());

            if let Err(e) = encoder.encode(

                pixel_bytes,

                width,

                height,

                translate_rawimage_colortype(image.data_format).into(),

            ) {

                return ResultU8VecEncodeImageError::Err(translate_image_error_encode(e));

            }

        }

        ResultU8VecEncodeImageError::Ok(result.into())

    }

    #[cfg(not(feature = "jpeg"))]

    #[cfg(test)]

    mod autotest_generated {

        use std::collections::BTreeSet;

        use azul_core::resources::RawImageData;

        use image::error::{

            DecodingError, EncodingError, ImageFormatHint, ParameterError, ParameterErrorKind,

            UnsupportedError, UnsupportedErrorKind,

        };

        use super::*;

        const ALL_ERRORS: [EncodeImageError; 5] = [

            EncodeImageError::EncoderNotAvailable,

            EncodeImageError::InsufficientMemory,

            EncodeImageError::DimensionError,

            EncodeImageError::InvalidData,

            EncodeImageError::Unknown,

        ];

        const ALL_FORMATS: [RawImageFormat; 12] = [

            RawImageFormat::R8,

            RawImageFormat::RG8,

            RawImageFormat::RGB8,

            RawImageFormat::RGBA8,

            RawImageFormat::R16,

            RawImageFormat::RG16,

            RawImageFormat::RGB16,

            RawImageFormat::RGBA16,

            RawImageFormat::BGR8,

            RawImageFormat::BGRA8,

            RawImageFormat::RGBF32,

            RawImageFormat::RGBAF32,

        ];

        fn raw_u8(

            width: usize,

            height: usize,

            data_format: RawImageFormat,

            pixels: Vec<u8>,

        ) -> RawImage {

            RawImage {

                pixels: RawImageData::U8(pixels.into()),

                width,

                height,

                premultiplied_alpha: false,

                data_format,

                tag: Vec::<u8>::new().into(),

            }

        }

        #[allow(dead_code)]

        fn err_of(r: &ResultU8VecEncodeImageError) -> EncodeImageError {

            match r.as_result() {

                Ok(_) => panic!("expected Err, got Ok"),

                Err(e) => *e,

            }

        }

        // --- EncodeImageError::fmt (serializer) ---------------------------------

        #[test]

        fn display_every_variant_is_non_empty_and_unique() {

            let rendered = ALL_ERRORS.iter().map(|e| e.to_string()).collect::<Vec<_>>();

            for (e, s) in ALL_ERRORS.iter().zip(rendered.iter()) {

                assert!(!s.is_empty(), "empty Display for {e:?}");

            }

            let unique = rendered.iter().collect::<BTreeSet<_>>();

            assert_eq!(unique.len(), ALL_ERRORS.len(), "Display collides: {rendered:?}");

        }

        #[test]

        fn display_text_is_stable() {

            // The odd one out: no "Error encoding image" prefix.

            assert_eq!(

                EncodeImageError::EncoderNotAvailable.to_string(),

                "Missing encoder (library was not compiled with given codec)"

            );

            assert_eq!(

                EncodeImageError::InsufficientMemory.to_string(),

                "Error encoding image: Not enough memory available to perform encoding operation"

            );

            assert_eq!(

                EncodeImageError::DimensionError.to_string(),

                "Error encoding image: Wrong dimensions"

            );

            assert_eq!(

                EncodeImageError::InvalidData.to_string(),

                "Error encoding image: Invalid data format"

            );

            assert_eq!(

                EncodeImageError::Unknown.to_string(),

                "Error encoding image: Unknown error"

            );

        }

        #[test]

        fn display_ignores_width_and_precision_specs_without_panicking() {

            for e in ALL_ERRORS {

                let plain = format!("{e}");

                assert_eq!(format!("{e:>512}"), plain);

                assert_eq!(format!("{e:.0}"), plain);

                assert!(!format!("{e:?}").is_empty());

            }

        }

        #[test]

        fn derived_ord_is_total_and_matches_declaration_order() {

            for (i, a) in ALL_ERRORS.iter().enumerate() {

                for (j, b) in ALL_ERRORS.iter().enumerate() {

                    assert_eq!(a.cmp(b), i.cmp(&j), "Ord disagrees for {a:?} vs {b:?}");

                    assert_eq!(a.partial_cmp(b), Some(a.cmp(b)));

                }

            }

        }

        // --- translate_rawimage_colortype (other) -------------------------------

        #[test]

        fn colortype_mapping_is_exhaustive_and_stable() {

            use image::ColorType::{L16, L8, La16, La8, Rgb16, Rgb32F, Rgb8, Rgba16, Rgba32F, Rgba8};

            let expected = [

                (RawImageFormat::R8, L8),

                (RawImageFormat::RG8, La8),

                (RawImageFormat::RGB8, Rgb8),

                (RawImageFormat::RGBA8, Rgba8),

                (RawImageFormat::R16, L16),

                (RawImageFormat::RG16, La16),

                (RawImageFormat::RGB16, Rgb16),

                (RawImageFormat::RGBA16, Rgba16),

                (RawImageFormat::BGR8, Rgb8),

                (RawImageFormat::BGRA8, Rgba8),

                (RawImageFormat::RGBF32, Rgb32F),

                (RawImageFormat::RGBAF32, Rgba32F),

            ];

            assert_eq!(expected.len(), ALL_FORMATS.len(), "a RawImageFormat variant is untested");

            for (format, want) in expected {

                assert_eq!(

                    translate_rawimage_colortype(format),

                    want,

                    "wrong ColorType for {format:?}"

                );

            }

        }

        #[test]

        fn colortype_maps_bgr_onto_its_rgb_counterpart() {

            // The BGR formats intentionally alias their RGB counterparts; the byte swap is

            // handled separately by `bgr_to_rgb_swap`.

            assert_eq!(

                translate_rawimage_colortype(RawImageFormat::BGR8),

                translate_rawimage_colortype(RawImageFormat::RGB8)

            );

            assert_eq!(

                translate_rawimage_colortype(RawImageFormat::BGRA8),

                translate_rawimage_colortype(RawImageFormat::RGBA8)

            );

        }

        #[test]

        fn colortype_is_usable_in_const_context() {

            const C: image::ColorType = translate_rawimage_colortype(RawImageFormat::RGBA16);

            assert_eq!(C, image::ColorType::Rgba16);

        }

        #[test]

        fn colortype_channel_count_matches_the_source_format() {

            for f in ALL_FORMATS {

                let channels = translate_rawimage_colortype(f).channel_count();

                let want = match f {

                    RawImageFormat::R8 | RawImageFormat::R16 => 1,

                    RawImageFormat::RG8 | RawImageFormat::RG16 => 2,

                    RawImageFormat::RGB8

                    | RawImageFormat::BGR8

                    | RawImageFormat::RGB16

                    | RawImageFormat::RGBF32 => 3,

                    RawImageFormat::RGBA8

                    | RawImageFormat::BGRA8

                    | RawImageFormat::RGBA16

                    | RawImageFormat::RGBAF32 => 4,

                };

                assert_eq!(channels, want, "channel count mismatch for {f:?}");

            }

        }

        // --- bgr_to_rgb_swap (parser) -------------------------------------------

        #[test]

        fn swap_returns_none_for_every_non_bgr_format() {

            for f in ALL_FORMATS {

                if matches!(f, RawImageFormat::BGR8 | RawImageFormat::BGRA8) {

                    continue;

                }

                assert_eq!(bgr_to_rgb_swap(&[1, 2, 3, 4, 5, 6], f), None, "{f:?} should not swap");

                assert_eq!(bgr_to_rgb_swap(&[], f), None, "{f:?} should not swap (empty)");

            }

        }

        #[test]

        fn swap_of_empty_input_is_some_empty_not_none() {

            // Empty input is *not* an error here: the format decides Some/None.

            assert_eq!(bgr_to_rgb_swap(&[], RawImageFormat::BGR8), Some(Vec::new()));

            assert_eq!(bgr_to_rgb_swap(&[], RawImageFormat::BGRA8), Some(Vec::new()));

        }

        #[test]

        fn swap_bgr8_swaps_red_and_blue_only() {

            assert_eq!(

                bgr_to_rgb_swap(&[1, 2, 3, 4, 5, 6], RawImageFormat::BGR8),

                Some(vec![3, 2, 1, 6, 5, 4])

            );

        }

        #[test]

        fn swap_bgra8_preserves_the_alpha_channel() {

            assert_eq!(

                bgr_to_rgb_swap(&[1, 2, 3, 200, 4, 5, 6, 201], RawImageFormat::BGRA8),

                Some(vec![3, 2, 1, 200, 6, 5, 4, 201])

            );

        }

        /// A pixel buffer whose length is not a whole number of pixels: `chunks_exact_mut`

        /// silently drops the remainder, so the trailing bytes pass through unswapped.

        #[test]

        fn swap_leaves_a_trailing_partial_pixel_untouched() {

            assert_eq!(bgr_to_rgb_swap(&[1], RawImageFormat::BGR8), Some(vec![1]));

            assert_eq!(bgr_to_rgb_swap(&[1, 2], RawImageFormat::BGR8), Some(vec![1, 2]));

            assert_eq!(

                bgr_to_rgb_swap(&[1, 2, 3, 4], RawImageFormat::BGR8),

                Some(vec![3, 2, 1, 4])

            );

            for len in 0..4usize {

                let input = (0..len as u8).collect::<Vec<_>>();

                assert_eq!(

                    bgr_to_rgb_swap(&input, RawImageFormat::BGRA8),

                    Some(input.clone()),

                    "a partial BGRA8 pixel of {len} byte(s) must pass through unchanged"

                );

            }

            assert_eq!(

                bgr_to_rgb_swap(&[1, 2, 3, 4, 5, 6, 7], RawImageFormat::BGRA8),

                Some(vec![3, 2, 1, 4, 5, 6, 7])

            );

        }

        #[test]

        fn swap_never_changes_the_length_and_is_its_own_inverse() {

            for (format, stride) in [(RawImageFormat::BGR8, 3usize), (RawImageFormat::BGRA8, 4)] {

                for len in 0..64usize {

                    let input = (0..len).map(|i| (i % 251) as u8).collect::<Vec<_>>();

                    let once = bgr_to_rgb_swap(&input, format).expect("BGR format must swap");

                    assert_eq!(once.len(), input.len(), "length changed for {format:?}, len {len}");

                    let twice = bgr_to_rgb_swap(&once, format).expect("BGR format must swap");

                    assert_eq!(twice, input, "swap is not an involution for {format:?}, len {len}");

                    // Only whole pixels move; the tail is untouched.

                    let tail = len - (len / stride) * stride;

                    assert_eq!(once[len - tail..], input[len - tail..]);

                }

            }

        }

        #[test]

        fn swap_handles_arbitrary_non_utf8_and_unicode_bytes() {

            assert_eq!(

                bgr_to_rgb_swap(&[0xFF, 0xFE, 0x00], RawImageFormat::BGR8),

                Some(vec![0x00, 0xFE, 0xFF])

            );

            // Bytes of "\u{1F600}" (F0 9F 98 80) reinterpreted as one BGRA8 pixel.

            assert_eq!(

                bgr_to_rgb_swap("\u{1F600}".as_bytes(), RawImageFormat::BGRA8),

                Some(vec![0x98, 0x9F, 0xF0, 0x80])

            );

            assert_eq!(

                bgr_to_rgb_swap(b"   \t\n", RawImageFormat::BGR8),

                Some(vec![b' ', b' ', b' ', b'\t', b'\n'])

            );

            assert_eq!(

                bgr_to_rgb_swap(&[0, 0, 0, 255, 255, 255], RawImageFormat::BGR8),

                Some(vec![0, 0, 0, 255, 255, 255])

            );

        }

        #[test]

        fn swap_of_a_very_large_buffer_does_not_hang() {

            const LEN: usize = 3 * 333_333 + 2; // ~1 MB, deliberately not pixel-aligned

            let input = (0..LEN).map(|i| (i % 256) as u8).collect::<Vec<_>>();

            let out = bgr_to_rgb_swap(&input, RawImageFormat::BGR8).expect("BGR8 must swap");

            assert_eq!(out.len(), LEN);

            assert_eq!(out[0], input[2]);

            assert_eq!(out[2], input[0]);

            assert_eq!(out[LEN - 1], input[LEN - 1]); // partial trailing pixel kept as-is

            assert_eq!(out[LEN - 2], input[LEN - 2]);

        }

        // --- translate_image_error_encode (other) --------------------------------

        #[test]

        fn translate_maps_limit_kinds() {

            assert_eq!(

                translate_image_error_encode(ImageError::Limits(LimitError::from_kind(

                    LimitErrorKind::InsufficientMemory

                ))),

                EncodeImageError::InsufficientMemory

            );

            assert_eq!(

                translate_image_error_encode(ImageError::Limits(LimitError::from_kind(

                    LimitErrorKind::DimensionError

                ))),

                EncodeImageError::DimensionError

            );

            assert_eq!(

                translate_image_error_encode(ImageError::Limits(LimitError::from_kind(

                    LimitErrorKind::Unsupported {

                        limits: image::Limits::default(),

                        supported: image::LimitSupport::default(),

                    }

                ))),

                EncodeImageError::Unknown

            );

        }

        #[test]

        fn translate_maps_every_other_variant_to_unknown() {

            let cases = vec![

                ImageError::IoError(std::io::Error::other("boom")),

                ImageError::Encoding(EncodingError::new(ImageFormatHint::Unknown, "bad pixel")),

                ImageError::Decoding(DecodingError::new(ImageFormatHint::Unknown, "bad chunk")),

                // An unsupported *color type* (what the JPEG encoder returns for RGBA8) is

                // flattened to `Unknown`, never to `InvalidData`.

                ImageError::Unsupported(UnsupportedError::from_format_and_kind(

                    ImageFormatHint::Unknown,

                    UnsupportedErrorKind::Format(ImageFormatHint::Unknown),

                )),

                // ... and a parameter dimension mismatch is NOT mapped to DimensionError.

                ImageError::Parameter(ParameterError::from_kind(

                    ParameterErrorKind::DimensionMismatch,

                )),

            ];

            for c in cases {

                let debug = format!("{c:?}");

                assert_eq!(

                    translate_image_error_encode(c),

                    EncodeImageError::Unknown,

                    "unexpected mapping for {debug}"

                );

            }

        }

        // --- encode_png ----------------------------------------------------------

        #[cfg(feature = "png")]

        #[test]

        fn encode_png_round_trips_through_the_decoder() {

            use crate::image::decode::decode_raw_image_from_any_bytes;

            for (format, bpp) in [

                (RawImageFormat::R8, 1usize),

                (RawImageFormat::RGB8, 3),

                (RawImageFormat::RGBA8, 4),

            ] {

                let pixels = (0..(2 * 2 * bpp)).map(|i| (i * 7 + 1) as u8).collect::<Vec<_>>();

                let encoded = encode_png(&raw_u8(2, 2, format, pixels.clone()))

                    .into_result()

                    .unwrap_or_else(|e| panic!("encode_png({format:?}) failed: {e}"));

                let bytes = encoded.as_slice();

                assert_eq!(&bytes[..8], b"\x89PNG\r\n\x1a\n", "missing PNG signature");

                let decoded = decode_raw_image_from_any_bytes(bytes)

                    .into_result()

                    .unwrap_or_else(|e| panic!("decode of our own PNG ({format:?}) failed: {e}"));

                assert_eq!(decoded.width, 2);

                assert_eq!(decoded.height, 2);

                assert_eq!(decoded.data_format, format, "format changed across the round trip");

                assert!(!decoded.premultiplied_alpha);

                assert_eq!(

                    decoded.pixels.get_u8_vec_ref().expect("8-bit data").as_slice(),

                    pixels.as_slice(),

                    "pixels changed across the round trip ({format:?})"

                );

            }

        }

        /// BGR input must come back out of the decoder as RGB with the channels swapped

        /// (PNG has no BGR color type -- `bgr_to_rgb_swap` is what makes this correct).

        #[cfg(feature = "png")]

        #[test]

        fn encode_png_swaps_bgr_channels_before_writing() {

            use crate::image::decode::decode_raw_image_from_any_bytes;

            let bgra = vec![10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160];

            let encoded = encode_png(&raw_u8(2, 2, RawImageFormat::BGRA8, bgra.clone()))

                .into_result()

                .expect("encode_png(BGRA8) failed");

            let decoded = decode_raw_image_from_any_bytes(encoded.as_slice())

                .into_result()

                .expect("decode of our own BGRA8 PNG failed");

            assert_eq!(decoded.data_format, RawImageFormat::RGBA8);

            let want = bgr_to_rgb_swap(&bgra, RawImageFormat::BGRA8).expect("BGRA8 must swap");

            assert_eq!(

                decoded.pixels.get_u8_vec_ref().expect("8-bit data").as_slice(),

                want.as_slice()

            );

            let bgr = vec![10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120];

            let encoded = encode_png(&raw_u8(2, 2, RawImageFormat::BGR8, bgr.clone()))

                .into_result()

                .expect("encode_png(BGR8) failed");

            let decoded = decode_raw_image_from_any_bytes(encoded.as_slice())

                .into_result()

                .expect("decode of our own BGR8 PNG failed");

            assert_eq!(decoded.data_format, RawImageFormat::RGB8);

            let want = bgr_to_rgb_swap(&bgr, RawImageFormat::BGR8).expect("BGR8 must swap");

            assert_eq!(

                decoded.pixels.get_u8_vec_ref().expect("8-bit data").as_slice(),

                want.as_slice()

            );

        }

        /// Non-8-bit payloads have no `get_u8_vec_ref()`, so they must be rejected as

        /// `InvalidData` -- even though `translate_rawimage_colortype` happily maps them.

        #[cfg(feature = "png")]

        #[test]

        fn encode_png_rejects_16_bit_and_float_payloads() {

            let u16_img = RawImage {

                pixels: RawImageData::U16(vec![0u16; 4].into()),

                width: 2,

                height: 2,

                premultiplied_alpha: false,

                data_format: RawImageFormat::R16,

                tag: Vec::<u8>::new().into(),

            };

            assert_eq!(err_of(&encode_png(&u16_img)), EncodeImageError::InvalidData);

            let f32_img = RawImage {

                pixels: RawImageData::F32(vec![0.0f32, f32::NAN, f32::INFINITY, f32::MIN].into()),

                width: 2,

                height: 2,

                premultiplied_alpha: false,

                data_format: RawImageFormat::RGBAF32,

                tag: Vec::<u8>::new().into(),

            };

            assert_eq!(err_of(&encode_png(&f32_img)), EncodeImageError::InvalidData);

        }

        #[cfg(all(feature = "png", target_pointer_width = "64"))]

        #[test]

        fn encode_png_rejects_dimensions_that_overflow_u32() {

            let too_wide = raw_u8(usize::MAX, 1, RawImageFormat::RGBA8, vec![0; 4]);

            assert_eq!(err_of(&encode_png(&too_wide)), EncodeImageError::DimensionError);

            let too_tall = raw_u8(1, (u32::MAX as usize) + 1, RawImageFormat::RGBA8, vec![0; 4]);

            assert_eq!(err_of(&encode_png(&too_tall)), EncodeImageError::DimensionError);

        }

        #[cfg(feature = "png")]

        #[test]

        fn encode_png_rejects_zero_dimensions() {

            let zero = raw_u8(0, 0, RawImageFormat::RGBA8, Vec::new());

            assert!(encode_png(&zero).is_err(), "a 0x0 PNG is not a valid image");

            let zero_width = raw_u8(0, 4, RawImageFormat::RGBA8, Vec::new());

            assert!(encode_png(&zero_width).is_err());

        }

        /// ADVERSARIAL: `image`'s `PngEncoder::write_image` *asserts* that the buffer length

        /// matches `width * height * bpp`, and `encode_png` forwards an unvalidated buffer.

        /// A short/long `RawImage` therefore aborts the process instead of returning `Err`.

        /// The invariant asserted here is the weaker one that always holds: it must never

        /// report success. See the report for the underlying bug.

        #[cfg(feature = "png")]

        #[test]

        fn encode_png_never_succeeds_on_a_buffer_of_the_wrong_length() {

            for (w, h, format, len) in [

                (4usize, 4usize, RawImageFormat::RGBA8, 3usize), // far too short

                (2, 2, RawImageFormat::RGBA8, 15),               // one byte short

                (2, 2, RawImageFormat::RGBA8, 17),               // one byte long

                (2, 2, RawImageFormat::R8, 0),                   // empty, non-zero dimensions

            ] {

                let outcome = std::panic::catch_unwind(move || {

                    encode_png(&raw_u8(w, h, format, vec![0u8; len])).is_ok()

                });

                assert!(

                    !matches!(outcome, Ok(true)),

                    "encode_png claimed success for {w}x{h} {format:?} with {len} byte(s)"

                );

            }

        }

        #[cfg(not(feature = "png"))]

        #[test]

        fn encode_png_without_the_feature_always_reports_encoder_not_available() {

            for img in [

                raw_u8(2, 2, RawImageFormat::RGBA8, vec![0; 16]),

                raw_u8(0, 0, RawImageFormat::RGBA8, Vec::new()),

                raw_u8(usize::MAX, usize::MAX, RawImageFormat::BGRA8, vec![0; 3]),

            ] {

                assert_eq!(err_of(&encode_png(&img)), EncodeImageError::EncoderNotAvailable);

            }

        }

        // --- encode_jpeg (numeric: `quality`) ------------------------------------

        /// `JpegEncoder::new_with_quality` clamps the quality to 1..=100 internally, so the

        /// out-of-range ends must not panic and must be indistinguishable from the clamped value.

        #[cfg(feature = "jpeg")]

        #[test]

        fn encode_jpeg_clamps_quality_at_both_ends() {

            let pixels = (0..(4 * 4 * 3)).map(|i| (i * 5) as u8).collect::<Vec<_>>();

            let at = |q: u8| {

                encode_jpeg(&raw_u8(4, 4, RawImageFormat::RGB8, pixels.clone()), q)

                    .into_result()

                    .unwrap_or_else(|e| panic!("encode_jpeg(quality = {q}) failed: {e}"))

                    .as_slice()

                    .to_vec()

            };

            assert_eq!(at(u8::MIN), at(1), "quality 0 must clamp to 1");

            assert_eq!(at(u8::MAX), at(100), "quality 255 must clamp to 100");

            assert_ne!(at(1), at(100), "quality must actually affect the output");

            for q in [0u8, 1, 50, 100, 101, 254, 255] {

                let bytes = at(q);

                assert_eq!(&bytes[..2], &[0xFF, 0xD8], "missing JPEG SOI marker (quality {q})");

                assert_eq!(

                    &bytes[bytes.len() - 2..],

                    &[0xFF, 0xD9],

                    "missing JPEG EOI marker (quality {q})"

                );

            }

        }

        #[cfg(feature = "jpeg")]

        #[test]

        fn encode_jpeg_round_trips_dimensions_through_the_decoder() {

            use crate::image::decode::decode_raw_image_from_any_bytes;

            let pixels = (0..(8 * 8 * 3)).map(|i| (i % 256) as u8).collect::<Vec<_>>();

            let encoded = encode_jpeg(&raw_u8(8, 8, RawImageFormat::RGB8, pixels), 90)

                .into_result()

                .expect("encode_jpeg(RGB8) failed");

            // JPEG is lossy, so only the geometry/format survives -- not the exact pixels.

            let decoded = decode_raw_image_from_any_bytes(encoded.as_slice())

                .into_result()

                .expect("decode of our own JPEG failed");

            assert_eq!(decoded.width, 8);

            assert_eq!(decoded.height, 8);

            assert_eq!(decoded.data_format, RawImageFormat::RGB8);

            assert_eq!(decoded.pixels.get_u8_vec_ref().expect("8-bit data").len(), 8 * 8 * 3);

        }

        /// The JPEG encoder only supports L8 and Rgb8. Everything else comes back as an

        /// `Unsupported` image error, which the wrapper flattens to `Unknown`.

        #[cfg(feature = "jpeg")]

        #[test]

        fn encode_jpeg_rejects_color_types_it_cannot_write() {

            for (format, bpp) in [

                (RawImageFormat::RGBA8, 4usize),

                (RawImageFormat::BGRA8, 4),

                (RawImageFormat::RG8, 2),

            ] {

                let img = raw_u8(2, 2, format, vec![7u8; 2 * 2 * bpp]);

                assert_eq!(

                    err_of(&encode_jpeg(&img, 80)),

                    EncodeImageError::Unknown,

                    "unexpected error for {format:?}"

                );

            }

            // ... while the two supported ones do encode.

            assert!(encode_jpeg(&raw_u8(2, 2, RawImageFormat::R8, vec![1; 4]), 80).is_ok());

            assert!(encode_jpeg(&raw_u8(2, 2, RawImageFormat::RGB8, vec![1; 12]), 80).is_ok());

        }

        #[cfg(feature = "jpeg")]

        #[test]

        fn encode_jpeg_rejects_zero_and_u16_max_plus_one_dimensions() {

            // JPEG dimensions are u16 in the frame header: 0 and > 65535 must both fail,

            // and must fail as an error rather than a panic.

            assert!(encode_jpeg(&raw_u8(0, 0, RawImageFormat::RGB8, Vec::new()), 75).is_err());

            assert!(encode_jpeg(&raw_u8(0, 4, RawImageFormat::RGB8, Vec::new()), 75).is_err());

            let too_wide = raw_u8(65_536, 1, RawImageFormat::RGB8, vec![0u8; 65_536 * 3]);

            // NOTE: reported as `Unknown`, not `DimensionError` -- the wrapper only maps

            // `ImageError::Limits`, and the JPEG encoder raises an encoding error instead.

            assert_eq!(err_of(&encode_jpeg(&too_wide, 75)), EncodeImageError::Unknown);

        }

        #[cfg(all(feature = "jpeg", target_pointer_width = "64"))]

        #[test]

        fn encode_jpeg_rejects_dimensions_that_overflow_u32() {

            let too_wide = raw_u8(usize::MAX, 1, RawImageFormat::RGB8, vec![0; 3]);

            assert_eq!(err_of(&encode_jpeg(&too_wide, 75)), EncodeImageError::DimensionError);

            let too_tall = raw_u8(1, (u32::MAX as usize) + 1, RawImageFormat::RGB8, vec![0; 3]);

            assert_eq!(err_of(&encode_jpeg(&too_tall, 0)), EncodeImageError::DimensionError);

        }

        #[cfg(feature = "jpeg")]

        #[test]

        fn encode_jpeg_rejects_16_bit_payloads_before_looking_at_quality() {

            let u16_img = RawImage {

                pixels: RawImageData::U16(vec![u16::MAX; 12].into()),

                width: 2,

                height: 2,

                premultiplied_alpha: false,

                data_format: RawImageFormat::RGB16,

                tag: Vec::<u8>::new().into(),

            };

            for q in [0u8, 50, 255] {

                assert_eq!(err_of(&encode_jpeg(&u16_img, q)), EncodeImageError::InvalidData);

            }

        }

        /// Same unvalidated-buffer hazard as `encode_png`, at every quality boundary.

        #[cfg(feature = "jpeg")]

        #[test]

        fn encode_jpeg_never_succeeds_on_a_buffer_of_the_wrong_length() {

            for q in [0u8, 1, 100, 255] {

                for (w, h, len) in [(4usize, 4usize, 3usize), (2, 2, 11), (2, 2, 13)] {

                    let outcome = std::panic::catch_unwind(move || {

                        encode_jpeg(&raw_u8(w, h, RawImageFormat::RGB8, vec![0u8; len]), q).is_ok()

                    });

                    assert!(

                        !matches!(outcome, Ok(true)),

                        "encode_jpeg claimed success for {w}x{h} RGB8, {len} byte(s), quality {q}"

                    );

                }

            }

        }

        #[cfg(not(feature = "jpeg"))]

        #[test]

        fn encode_jpeg_without_the_feature_always_reports_encoder_not_available() {

            // Every quality boundary, including the ones the real encoder would clamp.

            for q in [u8::MIN, 1, 50, 100, 101, 254, u8::MAX] {

                let img = raw_u8(2, 2, RawImageFormat::RGB8, vec![0; 12]);

                assert_eq!(err_of(&encode_jpeg(&img, q)), EncodeImageError::EncoderNotAvailable);

            }

            // ... and for images that the real encoder would reject outright.

            let broken = raw_u8(usize::MAX, 0, RawImageFormat::RGBAF32, Vec::new());

            assert_eq!(err_of(&encode_jpeg(&broken, 0)), EncodeImageError::EncoderNotAvailable);