zenpixels/

descriptor.rs

//! Pixel format descriptor types.
//!
//! These types describe the format of pixel data: channel type, layout,
//! alpha handling, transfer function, color primaries, and signal range.
//!
//! Standalone definitions — no dependency on zencodec.

use core::fmt;

// ---------------------------------------------------------------------------
// Channel type
// ---------------------------------------------------------------------------

/// Channel storage type.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum ChannelType {
    /// 8-bit unsigned integer (1 byte per channel).
    U8 = 1,
    /// 16-bit unsigned integer (2 bytes per channel).
    U16 = 2,
    /// 32-bit floating point (4 bytes per channel).
    F32 = 4,
    /// IEEE 754 half-precision float (2 bytes per channel).
    F16 = 5,
}

impl ChannelType {
    /// Byte size of a single channel value.
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn byte_size(self) -> usize {
        match self {
            Self::U8 => 1,
            Self::U16 | Self::F16 => 2,
            Self::F32 => 4,
            _ => 0,
        }
    }

    /// Whether this is [`U8`](Self::U8).
    #[inline]
    pub const fn is_u8(self) -> bool {
        matches!(self, Self::U8)
    }

    /// Whether this is [`U16`](Self::U16).
    #[inline]
    pub const fn is_u16(self) -> bool {
        matches!(self, Self::U16)
    }

    /// Whether this is [`F32`](Self::F32).
    #[inline]
    pub const fn is_f32(self) -> bool {
        matches!(self, Self::F32)
    }

    /// Whether this is [`F16`](Self::F16).
    #[inline]
    pub const fn is_f16(self) -> bool {
        matches!(self, Self::F16)
    }

    /// Whether this is an integer type.
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn is_integer(self) -> bool {
        matches!(self, Self::U8 | Self::U16)
    }

    /// Whether this is a floating-point type.
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn is_float(self) -> bool {
        matches!(self, Self::F32 | Self::F16)
    }
}

impl fmt::Display for ChannelType {
    #[allow(unreachable_patterns)]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::U8 => f.write_str("U8"),
            Self::U16 => f.write_str("U16"),
            Self::F32 => f.write_str("F32"),
            Self::F16 => f.write_str("F16"),
            _ => write!(f, "ChannelType({})", *self as u8),
        }
    }
}

// ---------------------------------------------------------------------------
// Channel layout
// ---------------------------------------------------------------------------

/// Channel layout (number and meaning of channels).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum ChannelLayout {
    /// Single luminance channel.
    Gray = 1,
    /// Luminance + alpha.
    GrayAlpha = 2,
    /// Red, green, blue.
    Rgb = 3,
    /// Red, green, blue, alpha.
    Rgba = 4,
    /// Blue, green, red, alpha (Windows/DirectX byte order).
    Bgra = 5,
    /// Oklab perceptual color: L, a, b.
    Oklab = 6,
    /// Oklab perceptual color with alpha: L, a, b, alpha.
    OklabA = 7,
    /// C, M, Y, K channel order.
    Cmyk = 8,
}

impl ChannelLayout {
    /// Number of channels in this layout.
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn channels(self) -> usize {
        match self {
            Self::Gray => 1,
            Self::GrayAlpha => 2,
            Self::Rgb | Self::Oklab => 3,
            Self::Rgba | Self::Bgra | Self::OklabA | Self::Cmyk => 4,
            _ => 0,
        }
    }

    /// Whether this layout includes an alpha channel.
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn has_alpha(self) -> bool {
        matches!(
            self,
            Self::GrayAlpha | Self::Rgba | Self::Bgra | Self::OklabA
        )
    }
}

impl fmt::Display for ChannelLayout {
    #[allow(unreachable_patterns)]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Gray => f.write_str("Gray"),
            Self::GrayAlpha => f.write_str("GrayAlpha"),
            Self::Rgb => f.write_str("RGB"),
            Self::Rgba => f.write_str("RGBA"),
            Self::Bgra => f.write_str("BGRA"),
            Self::Oklab => f.write_str("Oklab"),
            Self::OklabA => f.write_str("OklabA"),
            Self::Cmyk => f.write_str("CMYK"),
            _ => write!(f, "ChannelLayout({})", *self as u8),
        }
    }
}

// ---------------------------------------------------------------------------
// Alpha mode
// ---------------------------------------------------------------------------

/// Alpha channel interpretation.
///
/// Wrapped in `Option<AlphaMode>` on [`PixelDescriptor`]: `None` means no
/// alpha channel exists, while `Some(AlphaMode::Straight)` etc. describe
/// the semantics of a present alpha channel.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum AlphaMode {
    /// Alpha bytes exist but values are undefined padding (RGBX, BGRX).
    Undefined = 1,
    /// Straight (unassociated) alpha.
    Straight = 2,
    /// Premultiplied (associated) alpha.
    Premultiplied = 3,
    /// Alpha channel present, all values fully opaque.
    Opaque = 4,
}

impl AlphaMode {
    /// Whether this mode represents a real alpha channel (not Undefined padding).
    #[inline]
    pub const fn has_alpha(self) -> bool {
        matches!(self, Self::Straight | Self::Premultiplied | Self::Opaque)
    }
}

impl fmt::Display for AlphaMode {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Undefined => f.write_str("undefined"),
            Self::Straight => f.write_str("straight"),
            Self::Premultiplied => f.write_str("premultiplied"),
            Self::Opaque => f.write_str("opaque"),
        }
    }
}

// ---------------------------------------------------------------------------
// Transfer function
// ---------------------------------------------------------------------------

/// Encoding transfer function (OETF).
///
/// Describes how scene-linear light was encoded into the pixel values.
/// For still image codecs, this is unambiguous: "sRGB" means the IEC 61966-2-1
/// curve, "PQ" means SMPTE ST 2084, etc. Video pipelines that need to
/// distinguish OETF from EOTF should use CICP codes directly.
///
/// Discriminant values are internal — use [`from_cicp()`](Self::from_cicp) /
/// [`to_cicp()`](Self::to_cicp) for CICP mapping.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum TransferFunction {
    /// Linear light (gamma 1.0).
    Linear = 0,
    /// sRGB transfer curve (IEC 61966-2-1).
    Srgb = 1,
    /// BT.709 transfer curve.
    Bt709 = 2,
    /// Perceptual Quantizer (SMPTE ST 2084, HDR10).
    Pq = 3,
    /// Pure power-law gamma 2.2. Used for Adobe RGB (1998).
    ///
    /// The Adobe RGB 1998 encoding spec (§4.3.4.2) defines pure gamma
    /// 2.19921875 with no linear segment near black. About 85% of real-world
    /// Adobe RGB ICC profiles (Adobe CS4, Windows ClayRGB1998 / AdobeRGB1998,
    /// macOS AdobeRGB1998, Linux `AdobeRGB1998`/`compatibleWithAdobeRGB1998`,
    /// Nikon, etc.) encode the TRC as `curv count=1` (pure gamma) or
    /// equivalent `paraType funcType=0`.
    ///
    /// A minority of profiles (saucecontrol's Compact-ICC AdobeCompat-v4,
    /// some lcms2-generated variants) encode `paraType funcType=3` with a
    /// linear toe (slope `c=1/32`, break `d=0.05568`). Those profiles are
    /// deliberately NOT normalized to this variant — they fall through to
    /// full CMS so their exact encoded curve is honored. See
    /// `scripts/icc-gen/src/main.rs` for the identification policy.
    Gamma22 = 5,
    /// Hybrid Log-Gamma (CICP 18, ARIB STD-B67). BT.2100 HDR.
    Hlg = 4,
    // ── DO NOT REMOVE THESE COMMENTS ────────────────────────────────
    // Deferred / removed transfer functions — not yet added or
    // deliberately excluded. Profiles using these fall through to a
    // full CMS via the Unknown path.
    //
    // Gamma18 — pure power-law gamma 1.8.
    //   Used by Apple RGB, ColorMatch RGB, ECI-RGB v2, and some legacy
    //   workflows. All primaries that required it (AppleRgb, ColorMatch,
    //   EciRgbV2) were removed — no remaining ColorPrimaries variant
    //   pairs with this transfer. ICC profiles using gamma 1.8 fall
    //   through to a full CMS.
    //
    // Gamma24 — pure power-law gamma 2.4.
    //   BT.1886 display model, ACES display encoding. Niche — only 3
    //   profiles in the ICC hash table referenced it (Rec2020-g24-v4,
    //   bt 2020, ITU-RBT709ReferenceDisplay). Fall through to CMS.
    //
    // Gamma26 — pure power-law gamma 2.6.
    //   DCI-P3 theatrical projection (ST 428-1). Only 3 profiles in
    //   the ICC hash table (DCI-P3-v4, system DCI(P3) RGB, SMPTE431
    //   P3.icm). Theatrical projection uses the DCI white point, not
    //   D65 — images use DisplayP3 with sRGB transfer, not DCI-P3
    //   with gamma 2.6. Fall through to CMS.
    //
    // AcesCct — quasi-logarithmic with linear toe (SMPTE ST 2065-1).
    //   Niche VFX/grading transfer. No consumer image format embeds it.
    //   Add if we ever support ACES interchange workflows.
    //
    // Variants are only added when we can back them with correct,
    // tested conversion math. An enum variant without math is worse
    // than Unknown — it gives callers false confidence.
    // ────────────────────────────────────────────────────────────────
    /// Transfer function is not known.
    Unknown = 255,
}

impl TransferFunction {
    /// Map CICP `transfer_characteristics` code to a [`TransferFunction`].
    #[inline]
    pub const fn from_cicp(tc: u8) -> Option<Self> {
        match tc {
            1 => Some(Self::Bt709),
            // SMPTE 170M (6) and SMPTE 240M (7) use the BT.709 curve —
            // per BT.601/SMPTE 170M spec, the OETF is identical to BT.709.
            6 | 7 => Some(Self::Bt709),
            8 => Some(Self::Linear),
            13 => Some(Self::Srgb),
            16 => Some(Self::Pq),
            18 => Some(Self::Hlg),
            _ => None,
        }
    }

    /// Convert to the CICP `transfer_characteristics` code.
    #[allow(unreachable_patterns)]
    #[inline]
    pub const fn to_cicp(self) -> Option<u8> {
        match self {
            Self::Bt709 => Some(1),
            Self::Linear => Some(8),
            Self::Srgb => Some(13),
            Self::Pq => Some(16),
            Self::Hlg => Some(18),
            Self::Unknown => None,
            _ => None,
        }
    }

    /// Reference white luminance in nits.
    ///
    /// - SDR (sRGB, BT.709, Linear, Unknown): `1.0` (relative/scene-referred)
    /// - PQ: `203.0` (ITU-R BT.2408 reference white)
    /// - HLG: `1.0` (scene-referred)
    #[allow(unreachable_patterns)]
    pub fn reference_white_nits(&self) -> f32 {
        match self {
            Self::Pq => 203.0,
            _ => 1.0,
        }
    }
}

impl fmt::Display for TransferFunction {
    #[allow(unreachable_patterns)]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Linear => f.write_str("linear"),
            Self::Srgb => f.write_str("sRGB"),
            Self::Bt709 => f.write_str("BT.709"),
            Self::Pq => f.write_str("PQ"),
            Self::Gamma22 => f.write_str("gamma 2.2"),
            Self::Hlg => f.write_str("HLG"),
            Self::Unknown => f.write_str("unknown"),
            _ => f.write_str("TransferFunction(?)"),
        }
    }
}

// ---------------------------------------------------------------------------
// Color primaries
// ---------------------------------------------------------------------------

/// Color primaries (CIE xy chromaticities of R, G, B) and white point.
///
/// Each variant is a complete "named recipe" — primaries and white point
/// are an inseparable pair (following CICP convention). Use
/// [`from_cicp()`](Self::from_cicp) / [`to_cicp()`](Self::to_cicp) for
/// CICP mapping. Discriminant values are internal.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum ColorPrimaries {
    /// BT.709 / sRGB (CICP 1). White point: D65.
    #[default]
    Bt709 = 1,
    /// BT.2020 / BT.2100 (CICP 9). Wide gamut for HDR. White point: D65.
    Bt2020 = 9,
    /// Display P3 (CICP 12, SMPTE EG 432-1). Apple ecosystem.
    /// Same RGB primaries as DCI-P3, white point: D65.
    DisplayP3 = 12,
    /// Adobe RGB (1998). Wide gamut. White point: D65.
    AdobeRgb = 13,
    // ── DO NOT REMOVE THESE COMMENTS ────────────────────────────────
    // Deferred / removed primaries — not yet added or deliberately
    // excluded. ICC profiles using these fall through to a full CMS.
    //
    // DciP3 (CICP 11, SMPTE RP 431-2) — theatrical projection white point.
    //   Same RGB primaries as DisplayP3: R(0.680, 0.320) G(0.265, 0.690) B(0.150, 0.060).
    //   White point: DCI (0.314, 0.351), NOT D65. Images use DisplayP3
    //   (D65), not DCI — DCI is for theatrical projection only. Removed
    //   because no still-image workflow embeds DCI-P3 with the DCI white.
    //
    // Smpte170m (CICP 6) — SMPTE 170M / BT.601-7 525-line, NTSC SD broadcast.
    //   Chromaticities: R(0.630, 0.340) G(0.310, 0.595) B(0.155, 0.070). White: D65.
    //   Video-only, never embedded in still images.
    //
    // Bt470Bg (CICP 5) — BT.470-6 System B/G / BT.601-7 625-line, PAL/SECAM SD.
    //   Chromaticities: R(0.64, 0.33) G(0.29, 0.60) B(0.15, 0.06). White: D65.
    //   Video-only, never embedded in still images.
    //
    // AppleRgb — pre-ColorSync Mac default (~2003), essentially extinct.
    //   Chromaticities: R(0.625, 0.340) G(0.280, 0.595) B(0.155, 0.070). White: D65.
    //   Paired with Gamma18 transfer (also removed).
    //
    // ColorMatch — Radius print workflow from the '90s, dead.
    //   Chromaticities: R(0.630, 0.340) G(0.295, 0.605) B(0.150, 0.075). White: D50 (0.3457, 0.3585).
    //   Paired with Gamma18 transfer (also removed).
    //
    // WideGamut — Adobe Wide Gamut RGB, working space almost never embedded in output images.
    //   Chromaticities: R(0.735, 0.265) G(0.115, 0.826) B(0.157, 0.018). White: D50 (0.3457, 0.3585).
    //   Paired with Gamma22 transfer.
    //
    // EciRgbV2 — European Color Initiative prepress working space, never in consumer images.
    //   Chromaticities: R(0.670, 0.330) G(0.210, 0.710) B(0.140, 0.080). White: D50 (0.3457, 0.3585).
    //   Paired with Gamma18 transfer (also removed).
    //
    // ProPhoto (ROMM RGB) — ultra-wide gamut, D50 white (0.3457, 0.3585).
    //   Chromaticities: R(0.7347, 0.2653) G(0.1596, 0.8404) B(0.0366, 0.0001).
    //   Deliberately excluded: real-world ProPhoto ICC profiles are
    //   fragmented across pure gamma 1.8, paraType funcType=3 with
    //   varying linear-toe parameters (ISO 22028-2 d=1/32 vs Apple
    //   d=1/512), and even LUT-based v4 profiles. No single canonical
    //   TRC dominates, so all ProPhoto profiles fall through to a full
    //   CMS. Add when we can handle the TRC variants reliably.
    //
    // AcesAp0 (SMPTE ST 2065-1) — entire visible gamut, ACES D60 white.
    //   Chromaticities: R(0.7347, 0.2653) G(0.0, 1.0) B(0.0001, -0.077).
    //   Archival/interchange. No consumer image format embeds it.
    //
    // AcesAp1 (ACEScg) — rendering/grading gamut, ACES D60 white.
    //   Chromaticities: R(0.713, 0.293) G(0.165, 0.830) B(0.128, 0.044).
    //   Same situation as AcesAp0.
    //
    // Variants are only added when we can back them with correct,
    // tested conversion math. An enum variant without math is worse
    // than Unknown — it gives callers false confidence.
    // ────────────────────────────────────────────────────────────────
    /// Primaries not known.
    Unknown = 255,
}

impl ColorPrimaries {
    /// D65 white point (BT.709, BT.2020, Display P3, Adobe RGB).
    pub const WHITE_D65: (f32, f32) = (0.3127, 0.3290);
    // D50 white point value preserved for reference: (0.3457, 0.3585).
    // No remaining ColorPrimaries variants use D50. Was used by
    // ColorMatch, WideGamut, EciRgbV2 (all removed).
    /// DCI white point (theatrical projection, SMPTE RP 431-2).
    #[allow(dead_code)] // kept for future DCI-P3 theatrical support
    pub(crate) const WHITE_DCI: (f32, f32) = (0.314, 0.351);

    /// CIE 1931 xy chromaticity coordinates of the RGB primaries.
    ///
    /// Returns `((rx, ry), (gx, gy), (bx, by))` or `None` for `Unknown`.
    /// These are the canonical coordinates from the relevant standards
    /// (ITU-R BT.709, BT.2020, SMPTE EG 432-1, etc.).
    #[allow(unreachable_patterns, clippy::type_complexity)]
    pub const fn chromaticity(self) -> Option<((f32, f32), (f32, f32), (f32, f32))> {
        match self {
            Self::Bt709 => Some(((0.64, 0.33), (0.30, 0.60), (0.15, 0.06))),
            Self::DisplayP3 => Some(((0.680, 0.320), (0.265, 0.690), (0.150, 0.060))),
            Self::Bt2020 => Some(((0.708, 0.292), (0.170, 0.797), (0.131, 0.046))),
            Self::AdobeRgb => Some(((0.64, 0.33), (0.21, 0.71), (0.15, 0.06))),
            Self::Unknown => None,
            _ => None,
        }
    }

    /// Map a CICP `color_primaries` code to a [`ColorPrimaries`].
    #[inline]
    pub const fn from_cicp(code: u8) -> Option<Self> {
        match code {
            1 => Some(Self::Bt709),
            9 => Some(Self::Bt2020),
            12 => Some(Self::DisplayP3),
            _ => None,
        }
    }

    /// Convert to the CICP `color_primaries` code.
    #[allow(unreachable_patterns)]
    #[inline]
    pub const fn to_cicp(self) -> Option<u8> {
        match self {
            Self::Bt709 => Some(1),
            Self::Bt2020 => Some(9),
            Self::DisplayP3 => Some(12),
            Self::Unknown => None,
            _ => None,
        }
    }

    /// CIE 1931 xy chromaticity of this color space's white point.
    #[allow(unreachable_patterns)]
    #[inline]
    pub const fn white_point(self) -> (f32, f32) {
        match self {
            Self::Bt709 | Self::Bt2020 | Self::DisplayP3 | Self::AdobeRgb => Self::WHITE_D65,
            Self::Unknown => Self::WHITE_D65,
            _ => Self::WHITE_D65,
        }
    }

    /// Whether converting between `self` and `other` requires chromatic
    /// adaptation (different white points).
    #[inline]
    pub(crate) const fn needs_chromatic_adaptation(self, other: Self) -> bool {
        let (sx, sy) = self.white_point();
        let (ox, oy) = other.white_point();
        sx.to_bits() != ox.to_bits() || sy.to_bits() != oy.to_bits()
    }

    /// Compute the 3×3 linear RGB gamut conversion matrix from `self` to `dst`.
    ///
    /// Bradford chromatic adaptation is applied automatically when white points
    /// differ (e.g., DCI-P3 D50 → sRGB D65). Returns `None` for `Unknown`
    /// primaries. Identity conversions (same primaries) return the identity matrix.
    ///
    /// The matrix operates in linear light — apply EOTF before, OETF after.
    ///
    /// ```
    /// # use zenpixels::ColorPrimaries;
    /// let m = ColorPrimaries::DisplayP3.gamut_matrix_to(ColorPrimaries::Bt709).unwrap();
    /// // White maps to white
    /// let r = m[0][0] + m[0][1] + m[0][2];
    /// assert!((r - 1.0).abs() < 1e-4);
    /// ```
    pub const fn gamut_matrix_to(self, dst: Self) -> Option<[[f32; 3]; 3]> {
        crate::registry::gamut_matrix(self, dst)
    }

    /// Whether `self` fully contains the gamut of `other`.
    ///
    /// Returns `false` when white points differ (cross-adapted containment
    /// is not defined without a chromatic adaptation transform).
    /// D65 hierarchy: BT.2020 > Display P3 > Adobe RGB ≈ BT.709.
    #[inline]
    pub const fn contains(self, other: Self) -> bool {
        !self.needs_chromatic_adaptation(other)
            && self.gamut_width() >= other.gamut_width()
            && !matches!(self, Self::Unknown)
            && !matches!(other, Self::Unknown)
    }

    #[allow(unreachable_patterns)]
    const fn gamut_width(self) -> u8 {
        match self {
            Self::Bt709 => 1,
            Self::AdobeRgb => 2,
            Self::DisplayP3 => 3,
            Self::Bt2020 => 4,
            Self::Unknown => 0,
            _ => 0,
        }
    }
}

impl fmt::Display for ColorPrimaries {
    #[allow(unreachable_patterns)]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Bt709 => f.write_str("BT.709"),
            Self::Bt2020 => f.write_str("BT.2020"),
            Self::DisplayP3 => f.write_str("Display P3"),
            Self::AdobeRgb => f.write_str("Adobe RGB"),
            Self::Unknown => f.write_str("unknown"),
            _ => f.write_str("ColorPrimaries(?)"),
        }
    }
}

// ---------------------------------------------------------------------------
// Signal range
// ---------------------------------------------------------------------------

/// Signal range for pixel values.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum SignalRange {
    /// Full range: 0-2^N-1 (e.g. 0-255 for 8-bit).
    #[default]
    Full = 0,
    /// Narrow (limited/studio) range: 16-235 luma, 16-240 chroma (for 8-bit).
    Narrow = 1,
}

impl fmt::Display for SignalRange {
    #[allow(unreachable_patterns)]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Full => f.write_str("full"),
            Self::Narrow => f.write_str("narrow"),
            _ => write!(f, "SignalRange({})", *self as u8),
        }
    }
}

// ---------------------------------------------------------------------------
// PixelDescriptor
// ---------------------------------------------------------------------------

/// Compact pixel format descriptor.
///
/// Combines a [`PixelFormat`] (physical pixel layout) with transfer function,
/// alpha mode, color primaries, and signal range.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
pub struct PixelDescriptor {
    /// Physical pixel format (channel type + layout as a flat enum).
    pub format: PixelFormat,
    /// Electro-optical transfer function.
    pub transfer: TransferFunction,
    /// Alpha interpretation. `None` = no alpha channel.
    pub alpha: Option<AlphaMode>,
    /// Color primaries (gamut). Defaults to BT.709/sRGB.
    pub primaries: ColorPrimaries,
    /// Signal range (full vs narrow/limited).
    pub signal_range: SignalRange,
}

impl PixelDescriptor {
    // -- Forwarding accessors -------------------------------------------------

    /// The pixel format variant (layout + depth, no transfer or alpha semantics).
    #[inline]
    pub const fn pixel_format(&self) -> PixelFormat {
        self.format
    }

    /// Channel storage type.
    #[inline]
    pub const fn channel_type(&self) -> ChannelType {
        self.format.channel_type()
    }

    /// Alpha interpretation. `None` = no alpha channel.
    #[inline]
    pub const fn alpha(&self) -> Option<AlphaMode> {
        self.alpha
    }

    /// Transfer function.
    #[inline]
    pub const fn transfer(&self) -> TransferFunction {
        self.transfer
    }

    /// Extract the color encoding as a [`crate::ColorProfileSource::PrimariesTransferPair`].
    #[inline]
    pub const fn color_profile_source(&self) -> crate::ColorProfileSource<'static> {
        crate::ColorProfileSource::PrimariesTransferPair {
            primaries: self.primaries,
            transfer: self.transfer,
        }
    }

    /// Byte order.
    #[inline]
    pub const fn byte_order(&self) -> ByteOrder {
        self.format.byte_order()
    }

    /// Color model.
    #[inline]
    pub const fn color_model(&self) -> ColorModel {
        self.format.color_model()
    }

    /// Channel layout (derived from the [`PixelFormat`] variant).
    #[inline]
    pub const fn layout(&self) -> ChannelLayout {
        self.format.layout()
    }

    // -- Constructors ---------------------------------------------------------

    /// Create a descriptor with default primaries (BT.709) and full range.
    ///
    /// # See also
    ///
    /// * [`new_full`](Self::new_full) — same constructor with an explicit
    ///   [`ColorPrimaries`] argument, for anything that isn't BT.709/sRGB
    ///   gamut (BT.2020 HDR, Display P3, …).
    /// * The HDR presets [`RGB16_BT2100_PQ`](Self::RGB16_BT2100_PQ) /
    ///   [`RGB16_BT2100_HLG`](Self::RGB16_BT2100_HLG) — common BT.2100
    ///   combinations without spelling out the enums.
    ///
    /// # Panics
    ///
    /// Panics if the `(channel_type, layout, alpha)` combination has no
    /// corresponding [`PixelFormat`] variant (e.g. `(U16, Bgra, _)`).
    #[inline]
    pub const fn new(
        channel_type: ChannelType,
        layout: ChannelLayout,
        alpha: Option<AlphaMode>,
        transfer: TransferFunction,
    ) -> Self {
        let format = match PixelFormat::from_parts(channel_type, layout, alpha) {
            Some(f) => f,
            None => panic!("unsupported PixelFormat combination"),
        };
        Self {
            format,
            transfer,
            alpha,
            primaries: ColorPrimaries::Bt709,
            signal_range: SignalRange::Full,
        }
    }

    /// Create a descriptor with explicit primaries.
    ///
    /// # See also
    ///
    /// * [`new`](Self::new) — the four-argument form when BT.709/sRGB
    ///   primaries (the default) are what you want.
    /// * [`RGB16_BT2100_PQ`](Self::RGB16_BT2100_PQ) /
    ///   [`RGB16_BT2100_HLG`](Self::RGB16_BT2100_HLG) — ready-made BT.2100
    ///   HDR presets built on this constructor.
    ///
    /// # Panics
    ///
    /// Panics if the `(channel_type, layout, alpha)` combination has no
    /// corresponding [`PixelFormat`] variant.
    #[inline]
    pub const fn new_full(
        channel_type: ChannelType,
        layout: ChannelLayout,
        alpha: Option<AlphaMode>,
        transfer: TransferFunction,
        primaries: ColorPrimaries,
    ) -> Self {
        let format = match PixelFormat::from_parts(channel_type, layout, alpha) {
            Some(f) => f,
            None => panic!("unsupported PixelFormat combination"),
        };
        Self {
            format,
            transfer,
            alpha,
            primaries,
            signal_range: SignalRange::Full,
        }
    }

    /// Create from a [`PixelFormat`] with default alpha, unknown transfer,
    /// BT.709 primaries, and full range.
    #[inline]
    pub const fn from_pixel_format(format: PixelFormat) -> Self {
        Self {
            format,
            transfer: TransferFunction::Unknown,
            alpha: format.default_alpha(),
            primaries: ColorPrimaries::Bt709,
            signal_range: SignalRange::Full,
        }
    }

    // -- sRGB constants -------------------------------------------------------

    /// 8-bit sRGB RGB.
    pub const RGB8_SRGB: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Rgb,
        None,
        TransferFunction::Srgb,
    );
    /// 8-bit sRGB RGBA with straight alpha.
    pub const RGBA8_SRGB: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Rgba,
        Some(AlphaMode::Straight),
        TransferFunction::Srgb,
    );
    /// 16-bit sRGB RGB.
    pub const RGB16_SRGB: Self = Self::new(
        ChannelType::U16,
        ChannelLayout::Rgb,
        None,
        TransferFunction::Srgb,
    );
    /// 16-bit sRGB RGBA with straight alpha.
    pub const RGBA16_SRGB: Self = Self::new(
        ChannelType::U16,
        ChannelLayout::Rgba,
        Some(AlphaMode::Straight),
        TransferFunction::Srgb,
    );
    /// Linear-light f32 RGB.
    pub const RGBF32_LINEAR: Self = Self::new(
        ChannelType::F32,
        ChannelLayout::Rgb,
        None,
        TransferFunction::Linear,
    );
    /// Linear-light f32 RGBA with straight alpha.
    pub const RGBAF32_LINEAR: Self = Self::new(
        ChannelType::F32,
        ChannelLayout::Rgba,
        Some(AlphaMode::Straight),
        TransferFunction::Linear,
    );
    /// 8-bit sRGB grayscale.
    pub const GRAY8_SRGB: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Gray,
        None,
        TransferFunction::Srgb,
    );
    /// 16-bit sRGB grayscale.
    pub const GRAY16_SRGB: Self = Self::new(
        ChannelType::U16,
        ChannelLayout::Gray,
        None,
        TransferFunction::Srgb,
    );
    /// Linear-light f32 grayscale.
    pub const GRAYF32_LINEAR: Self = Self::new(
        ChannelType::F32,
        ChannelLayout::Gray,
        None,
        TransferFunction::Linear,
    );
    /// 8-bit sRGB grayscale with straight alpha.
    pub const GRAYA8_SRGB: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::GrayAlpha,
        Some(AlphaMode::Straight),
        TransferFunction::Srgb,
    );
    /// 16-bit sRGB grayscale with straight alpha.
    pub const GRAYA16_SRGB: Self = Self::new(
        ChannelType::U16,
        ChannelLayout::GrayAlpha,
        Some(AlphaMode::Straight),
        TransferFunction::Srgb,
    );
    /// Linear-light f32 grayscale with straight alpha.
    pub const GRAYAF32_LINEAR: Self = Self::new(
        ChannelType::F32,
        ChannelLayout::GrayAlpha,
        Some(AlphaMode::Straight),
        TransferFunction::Linear,
    );
    /// 8-bit sRGB BGRA with straight alpha.
    pub const BGRA8_SRGB: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Bgra,
        Some(AlphaMode::Straight),
        TransferFunction::Srgb,
    );
    /// 8-bit sRGB RGBX (padding byte, not alpha).
    pub const RGBX8_SRGB: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Rgba,
        Some(AlphaMode::Undefined),
        TransferFunction::Srgb,
    );
    /// 8-bit sRGB BGRX (padding byte, not alpha).
    pub const BGRX8_SRGB: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Bgra,
        Some(AlphaMode::Undefined),
        TransferFunction::Srgb,
    );

    // -- HDR (BT.2100) constants ------------------------------------------------

    /// 16-bit BT.2100 PQ RGB (BT.2020 primaries, PQ transfer, full range) —
    /// CICP `(9, 16, 0, full)`. The common interchange form for HDR10-style
    /// stills decoded to u16.
    ///
    /// Use [`new_full`](Self::new_full) for other channel types or layouts in
    /// this color space.
    pub const RGB16_BT2100_PQ: Self = Self::new_full(
        ChannelType::U16,
        ChannelLayout::Rgb,
        None,
        TransferFunction::Pq,
        ColorPrimaries::Bt2020,
    );
    /// 16-bit BT.2100 HLG RGB (BT.2020 primaries, HLG transfer, full range) —
    /// CICP `(9, 18, 0, full)`.
    ///
    /// Use [`new_full`](Self::new_full) for other channel types or layouts in
    /// this color space.
    pub const RGB16_BT2100_HLG: Self = Self::new_full(
        ChannelType::U16,
        ChannelLayout::Rgb,
        None,
        TransferFunction::Hlg,
        ColorPrimaries::Bt2020,
    );

    // -- Transfer-agnostic constants ------------------------------------------

    /// 8-bit RGB, transfer unknown.
    pub const RGB8: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Rgb,
        None,
        TransferFunction::Unknown,
    );
    /// 8-bit RGBA, transfer unknown.
    pub const RGBA8: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Rgba,
        Some(AlphaMode::Straight),
        TransferFunction::Unknown,
    );
    /// 16-bit RGB, transfer unknown.
    pub const RGB16: Self = Self::new(
        ChannelType::U16,
        ChannelLayout::Rgb,
        None,
        TransferFunction::Unknown,
    );
    /// 16-bit RGBA, transfer unknown.
    pub const RGBA16: Self = Self::new(
        ChannelType::U16,
        ChannelLayout::Rgba,
        Some(AlphaMode::Straight),
        TransferFunction::Unknown,
    );
    /// f32 RGB, transfer unknown.
    pub const RGBF32: Self = Self::new(
        ChannelType::F32,
        ChannelLayout::Rgb,
        None,
        TransferFunction::Unknown,
    );
    /// f32 RGBA, transfer unknown.
    pub const RGBAF32: Self = Self::new(
        ChannelType::F32,
        ChannelLayout::Rgba,
        Some(AlphaMode::Straight),
        TransferFunction::Unknown,
    );
    /// 8-bit grayscale, transfer unknown.
    pub const GRAY8: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Gray,
        None,
        TransferFunction::Unknown,
    );
    /// 16-bit grayscale, transfer unknown.
    pub const GRAY16: Self = Self::new(
        ChannelType::U16,
        ChannelLayout::Gray,
        None,
        TransferFunction::Unknown,
    );
    /// f32 grayscale, transfer unknown.
    pub const GRAYF32: Self = Self::new(
        ChannelType::F32,
        ChannelLayout::Gray,
        None,
        TransferFunction::Unknown,
    );
    /// 8-bit grayscale with alpha, transfer unknown.
    pub const GRAYA8: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::GrayAlpha,
        Some(AlphaMode::Straight),
        TransferFunction::Unknown,
    );
    /// 16-bit grayscale with alpha, transfer unknown.
    pub const GRAYA16: Self = Self::new(
        ChannelType::U16,
        ChannelLayout::GrayAlpha,
        Some(AlphaMode::Straight),
        TransferFunction::Unknown,
    );
    /// f32 grayscale with alpha, transfer unknown.
    pub const GRAYAF32: Self = Self::new(
        ChannelType::F32,
        ChannelLayout::GrayAlpha,
        Some(AlphaMode::Straight),
        TransferFunction::Unknown,
    );

    // -- F16 constants (pub(crate) — internal use by PixelFormat::descriptor()
    //    mapping. Tests construct via PixelDescriptor::new(). Linear-TF
    //    F16 variants would be added if an external codec consumer needs
    //    them — none today.) -----------------------------------------------

    pub(crate) const RGBF16: Self = Self::new(
        ChannelType::F16,
        ChannelLayout::Rgb,
        None,
        TransferFunction::Unknown,
    );
    pub(crate) const RGBAF16: Self = Self::new(
        ChannelType::F16,
        ChannelLayout::Rgba,
        Some(AlphaMode::Straight),
        TransferFunction::Unknown,
    );
    pub(crate) const GRAYF16: Self = Self::new(
        ChannelType::F16,
        ChannelLayout::Gray,
        None,
        TransferFunction::Unknown,
    );
    pub(crate) const GRAYAF16: Self = Self::new(
        ChannelType::F16,
        ChannelLayout::GrayAlpha,
        Some(AlphaMode::Straight),
        TransferFunction::Unknown,
    );
    /// 8-bit BGRA, transfer unknown.
    pub const BGRA8: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Bgra,
        Some(AlphaMode::Straight),
        TransferFunction::Unknown,
    );
    /// 8-bit RGBX, transfer unknown.
    pub const RGBX8: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Rgba,
        Some(AlphaMode::Undefined),
        TransferFunction::Unknown,
    );
    /// 8-bit BGRX, transfer unknown.
    pub const BGRX8: Self = Self::new(
        ChannelType::U8,
        ChannelLayout::Bgra,
        Some(AlphaMode::Undefined),
        TransferFunction::Unknown,
    );

    // -- Oklab constants ------------------------------------------------------

    /// Oklab f32 (L, a, b), transfer unknown.
    pub const OKLABF32: Self = Self {
        format: PixelFormat::OklabF32,
        transfer: TransferFunction::Unknown,
        alpha: None,
        primaries: ColorPrimaries::Bt709,
        signal_range: SignalRange::Full,
    };
    /// Oklab+alpha f32 (L, a, b, alpha), transfer unknown.
    pub const OKLABAF32: Self = Self {
        format: PixelFormat::OklabaF32,
        transfer: TransferFunction::Unknown,
        alpha: Some(AlphaMode::Straight),
        primaries: ColorPrimaries::Bt709,
        signal_range: SignalRange::Full,
    };

    // -- CMYK constants --------------------------------------------------------

    /// 8-bit CMYK, no transfer function or primaries.
    pub const CMYK8: Self = Self::from_pixel_format(PixelFormat::Cmyk8);

    // -- Methods --------------------------------------------------------------

    /// Number of channels.
    #[inline]
    pub const fn channels(self) -> usize {
        self.format.channels()
    }

    /// Bytes per pixel.
    #[inline]
    pub const fn bytes_per_pixel(self) -> usize {
        self.format.bytes_per_pixel()
    }

    /// Bytes per channel (1 for U8, 2 for U16/F16, 4 for F32).
    ///
    /// Shorthand for `self.channel_type().byte_size()` — the per-sample
    /// width, as opposed to [`bytes_per_pixel`](Self::bytes_per_pixel)
    /// (all channels of one pixel). The usual "do I need a
    /// high-bit-depth path?" check is `bytes_per_channel() > 1`.
    #[inline]
    pub const fn bytes_per_channel(self) -> usize {
        self.channel_type().byte_size()
    }

    /// Whether this descriptor has meaningful alpha data.
    #[inline]
    pub const fn has_alpha(self) -> bool {
        matches!(
            self.alpha,
            Some(AlphaMode::Straight) | Some(AlphaMode::Premultiplied) | Some(AlphaMode::Opaque)
        )
    }

    /// Whether this descriptor is grayscale.
    #[inline]
    pub const fn is_grayscale(self) -> bool {
        self.format.is_grayscale()
    }

    /// Whether this descriptor uses BGR byte order.
    #[inline]
    pub const fn is_bgr(self) -> bool {
        matches!(self.format.byte_order(), ByteOrder::Bgr)
    }

    /// Return a copy of this descriptor **relabeled** with a different
    /// transfer function. Does not touch any pixel bytes.
    ///
    /// Use when the source data was mistagged (e.g., a codec decoded a
    /// profile-less image and you know its true TF from another source)
    /// or when you want to assert a particular TF for downstream planning
    /// without round-tripping through EOTF/OETF kernels.
    ///
    /// **This is metadata-only.** To actually re-encode pixel bytes from
    /// one transfer function into another, pass a source buffer and a
    /// destination descriptor with the new TF into [`RowConverter::new`]
    /// — that builds a plan with the appropriate EOTF/OETF kernels.
    ///
    /// [`RowConverter::new`]: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/struct.RowConverter.html#method.new
    #[inline]
    #[must_use]
    pub const fn with_transfer(self, transfer: TransferFunction) -> Self {
        Self { transfer, ..self }
    }

    /// Return a copy of this descriptor **relabeled** with different
    /// primaries. Does not touch any pixel bytes or apply a gamut matrix.
    ///
    /// Use when you know the true primaries of the source data independent
    /// of whatever upstream tagging said, or to assert a particular primary
    /// set for downstream planning.
    ///
    /// **This is metadata-only.** To actually apply a gamut conversion
    /// (e.g., BT.709 → Display P3), pass the new descriptor as the
    /// destination to [`RowConverter::new`] — that inserts the appropriate
    /// gamut matrix in linear light.
    ///
    /// [`RowConverter::new`]: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/struct.RowConverter.html#method.new
    #[inline]
    #[must_use]
    pub const fn with_primaries(self, primaries: ColorPrimaries) -> Self {
        Self { primaries, ..self }
    }

    /// Return a copy of this descriptor **relabeled** with a different
    /// alpha mode. Does not touch any pixel bytes or apply (un)premultiply.
    ///
    /// Use when the source alpha mode was mistagged or when you want to
    /// assert straight/premultiplied without round-tripping through the
    /// premul kernels.
    ///
    /// **This is metadata-only.** To actually premultiply or un-premultiply
    /// pixel values, pass the new descriptor as the destination to
    /// [`RowConverter::new`] — that inserts a `StraightToPremul` or
    /// `PremulToStraight` step. (Note: the built-in premul kernels operate
    /// in the source byte space — "encoded premul", per Canvas 2D
    /// semantics — not in linear light.)
    ///
    /// [`RowConverter::new`]: https://docs.rs/zenpixels-convert/latest/zenpixels_convert/struct.RowConverter.html#method.new
    #[inline]
    #[must_use]
    pub const fn with_alpha(self, alpha: Option<AlphaMode>) -> Self {
        Self { alpha, ..self }
    }

    /// Alias for [`with_alpha`](Self::with_alpha).
    #[inline]
    #[must_use]
    pub const fn with_alpha_mode(self, alpha: Option<AlphaMode>) -> Self {
        self.with_alpha(alpha)
    }

    /// Return a copy with a different signal range.
    #[inline]
    #[must_use]
    pub const fn with_signal_range(self, signal_range: SignalRange) -> Self {
        Self {
            signal_range,
            ..self
        }
    }

    /// Whether this format is fully opaque (no transparency possible).
    ///
    /// Returns `true` when there is no alpha channel (`None`), the alpha
    /// bytes are undefined padding (`Undefined`), or alpha is all-255 (`Opaque`).
    #[inline]
    pub const fn is_opaque(self) -> bool {
        matches!(
            self.alpha,
            None | Some(AlphaMode::Undefined | AlphaMode::Opaque)
        )
    }

    /// Whether this format may contain transparent pixels.
    ///
    /// Returns `true` for [`Straight`](AlphaMode::Straight) and
    /// [`Premultiplied`](AlphaMode::Premultiplied).
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn may_have_transparency(self) -> bool {
        matches!(
            self.alpha,
            Some(AlphaMode::Straight | AlphaMode::Premultiplied)
        )
    }

    /// Whether the transfer function is [`Linear`](TransferFunction::Linear).
    #[inline]
    pub const fn is_linear(self) -> bool {
        matches!(self.transfer, TransferFunction::Linear)
    }

    /// Whether the transfer function is [`Unknown`](TransferFunction::Unknown).
    #[inline]
    pub const fn is_unknown_transfer(self) -> bool {
        matches!(self.transfer, TransferFunction::Unknown)
    }

    /// Minimum byte alignment required for the channel type (1, 2, or 4).
    #[inline]
    pub const fn min_alignment(self) -> usize {
        self.format.channel_type().byte_size()
    }

    /// Tightly-packed byte stride for a given width.
    #[inline]
    pub const fn aligned_stride(self, width: u32) -> usize {
        width as usize * self.bytes_per_pixel()
    }

    /// SIMD-friendly byte stride for a given width.
    ///
    /// The stride is a multiple of `lcm(bytes_per_pixel, simd_align)`,
    /// ensuring every row start is both pixel-aligned and SIMD-aligned.
    /// `simd_align` must be a power of 2.
    #[inline]
    pub const fn simd_aligned_stride(self, width: u32, simd_align: usize) -> usize {
        let bpp = self.bytes_per_pixel();
        let raw = width as usize * bpp;
        let align = lcm(bpp, simd_align);
        align_up_general(raw, align)
    }

    /// Whether this descriptor's channel type and layout are compatible with `other`.
    ///
    /// "Compatible" means the raw bytes can be reinterpreted as `other`
    /// without any pixel transformation — same channel type, same layout.
    #[inline]
    pub const fn layout_compatible(self, other: Self) -> bool {
        self.format.channel_type() as u8 == other.format.channel_type() as u8
            && self.layout() as u8 == other.layout() as u8
    }
}

// Alignment helpers.

const fn gcd(mut a: usize, mut b: usize) -> usize {
    while b != 0 {
        let t = b;
        b = a % b;
        a = t;
    }
    a
}

const fn lcm(a: usize, b: usize) -> usize {
    if a == 0 || b == 0 {
        0
    } else {
        a / gcd(a, b) * b
    }
}

const fn align_up_general(value: usize, align: usize) -> usize {
    if align == 0 {
        return value;
    }
    let rem = value % align;
    if rem == 0 { value } else { value + align - rem }
}

impl fmt::Display for PixelDescriptor {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{} {} {}",
            self.format,
            self.format.channel_type(),
            self.transfer
        )?;
        if let Some(alpha) = self.alpha {
            if alpha.has_alpha() {
                write!(f, " alpha={alpha}")?;
            }
        }
        Ok(())
    }
}

// ---------------------------------------------------------------------------
// Color model — what the channels represent
// ---------------------------------------------------------------------------

/// What the channels represent, independent of channel count or byte order.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum ColorModel {
    /// Single grayscale channel.
    Gray = 0,
    /// Red, green, blue (or BGR when [`ByteOrder::Bgr`]).
    Rgb = 1,
    /// Luma + chroma (Y, Cb, Cr).
    YCbCr = 2,
    /// Oklab perceptual color space (L, a, b).
    Oklab = 3,
    /// Cyan, magenta, yellow, key (black). Device-dependent printing color space.
    /// RGB primaries and transfer functions do not apply to CMYK data.
    /// Use a CMS with an ICC profile for CMYK↔RGB conversion.
    Cmyk = 4,
}

impl ColorModel {
    /// Number of color channels (excluding alpha).
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn color_channels(self) -> u8 {
        match self {
            Self::Gray => 1,
            Self::Cmyk => 4,
            _ => 3,
        }
    }
}

impl fmt::Display for ColorModel {
    #[allow(unreachable_patterns)]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Gray => f.write_str("Gray"),
            Self::Rgb => f.write_str("RGB"),
            Self::YCbCr => f.write_str("YCbCr"),
            Self::Oklab => f.write_str("Oklab"),
            Self::Cmyk => f.write_str("CMYK"),
            _ => write!(f, "ColorModel({})", *self as u8),
        }
    }
}

// ---------------------------------------------------------------------------
// Byte order
// ---------------------------------------------------------------------------

/// RGB-family byte order. Only meaningful when color model is RGB.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
#[non_exhaustive]
#[repr(u8)]
pub enum ByteOrder {
    /// Standard order: R, G, B (+ A if present).
    #[default]
    Native = 0,
    /// Windows/DirectX order: B, G, R (+ A if present).
    Bgr = 1,
}

impl fmt::Display for ByteOrder {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Native => f.write_str("native"),
            Self::Bgr => f.write_str("BGR"),
        }
    }
}

// ---------------------------------------------------------------------------
// PixelFormat — flat enum for physical pixel layout
// ---------------------------------------------------------------------------

/// Physical pixel layout for match-based format dispatch.
///
/// Each variant encodes the channel type (U8/U16/F32) and layout (RGB/RGBA/
/// Gray/etc.) in one discriminant. Transfer function and alpha mode live on
/// [`PixelDescriptor`], not here.
///
/// Use this enum when you need exhaustive `match` dispatch over known
/// pixel layouts.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum PixelFormat {
    Rgb8 = 1,
    Rgba8 = 2,
    Rgb16 = 3,
    Rgba16 = 4,
    RgbF32 = 5,
    RgbaF32 = 6,
    Gray8 = 7,
    Gray16 = 8,
    GrayF32 = 9,
    GrayA8 = 10,
    GrayA16 = 11,
    GrayAF32 = 12,
    Bgra8 = 13,
    Rgbx8 = 14,
    Bgrx8 = 15,
    OklabF32 = 16,
    OklabaF32 = 17,
    /// 8-bit CMYK (4 bytes per pixel, no transfer function).
    Cmyk8 = 18,
    /// f16 (IEEE 754 half-precision) RGB.
    RgbF16 = 19,
    /// f16 (IEEE 754 half-precision) RGBA.
    RgbaF16 = 20,
    /// f16 (IEEE 754 half-precision) grayscale.
    GrayF16 = 21,
    /// f16 (IEEE 754 half-precision) grayscale with alpha.
    GrayAF16 = 22,
}

impl PixelFormat {
    /// Channel storage type.
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn channel_type(self) -> ChannelType {
        match self {
            Self::Rgb8
            | Self::Rgba8
            | Self::Gray8
            | Self::GrayA8
            | Self::Bgra8
            | Self::Rgbx8
            | Self::Bgrx8
            | Self::Cmyk8 => ChannelType::U8,
            Self::Rgb16 | Self::Rgba16 | Self::Gray16 | Self::GrayA16 => ChannelType::U16,
            Self::RgbF32
            | Self::RgbaF32
            | Self::GrayF32
            | Self::GrayAF32
            | Self::OklabF32
            | Self::OklabaF32 => ChannelType::F32,
            Self::RgbF16 | Self::RgbaF16 | Self::GrayF16 | Self::GrayAF16 => ChannelType::F16,
            _ => ChannelType::U8,
        }
    }

    /// Channel layout.
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn layout(self) -> ChannelLayout {
        match self {
            Self::Rgb8 | Self::Rgb16 | Self::RgbF32 | Self::RgbF16 => ChannelLayout::Rgb,
            Self::Rgba8 | Self::Rgba16 | Self::RgbaF32 | Self::RgbaF16 | Self::Rgbx8 => {
                ChannelLayout::Rgba
            }
            Self::Gray8 | Self::Gray16 | Self::GrayF32 | Self::GrayF16 => ChannelLayout::Gray,
            Self::GrayA8 | Self::GrayA16 | Self::GrayAF32 | Self::GrayAF16 => {
                ChannelLayout::GrayAlpha
            }
            Self::Bgra8 | Self::Bgrx8 => ChannelLayout::Bgra,
            Self::OklabF32 => ChannelLayout::Oklab,
            Self::OklabaF32 => ChannelLayout::OklabA,
            Self::Cmyk8 => ChannelLayout::Cmyk,
            _ => ChannelLayout::Rgb,
        }
    }

    /// Color model (what the channels represent).
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn color_model(self) -> ColorModel {
        match self {
            Self::Gray8
            | Self::Gray16
            | Self::GrayF32
            | Self::GrayF16
            | Self::GrayA8
            | Self::GrayA16
            | Self::GrayAF32
            | Self::GrayAF16 => ColorModel::Gray,
            Self::OklabF32 | Self::OklabaF32 => ColorModel::Oklab,
            Self::Cmyk8 => ColorModel::Cmyk,
            _ => ColorModel::Rgb,
        }
    }

    /// Byte order (Native or BGR).
    #[inline]
    #[allow(unreachable_patterns)]
    pub const fn byte_order(self) -> ByteOrder {
        match self {
            Self::Bgra8 | Self::Bgrx8 => ByteOrder::Bgr,
            _ => ByteOrder::Native,
        }
    }

    /// Number of channels (including alpha/padding if present).
    #[inline]
    pub const fn channels(self) -> usize {
        self.layout().channels()
    }

    /// Bytes per pixel.
    #[inline]
    pub const fn bytes_per_pixel(self) -> usize {
        self.channels() * self.channel_type().byte_size()
    }

    /// Whether this format has alpha or padding bytes (4th channel).
    #[inline]
    pub const fn has_alpha_bytes(self) -> bool {
        self.layout().has_alpha()
    }

    /// Whether this format is grayscale.
    #[inline]
    pub const fn is_grayscale(self) -> bool {
        matches!(self.color_model(), ColorModel::Gray)
    }

    /// Default alpha mode for this format.
    ///
    /// - Formats with no alpha bytes → `None`
    /// - Formats with padding (Rgbx8, Bgrx8) → `Some(AlphaMode::Undefined)`
    /// - Formats with alpha → `Some(AlphaMode::Straight)`
    #[allow(unreachable_patterns)]
    #[inline]
    pub const fn default_alpha(self) -> Option<AlphaMode> {
        match self {
            Self::Rgb8
            | Self::Rgb16
            | Self::RgbF32
            | Self::RgbF16
            | Self::Gray8
            | Self::Gray16
            | Self::GrayF32
            | Self::GrayF16
            | Self::OklabF32
            | Self::Cmyk8 => None,
            Self::Rgbx8 | Self::Bgrx8 => Some(AlphaMode::Undefined),
            _ => Some(AlphaMode::Straight),
        }
    }

    /// Short human-readable name.
    #[allow(unreachable_patterns)]
    #[inline]
    pub const fn name(self) -> &'static str {
        match self {
            Self::Rgb8 => "RGB8",
            Self::Rgba8 => "RGBA8",
            Self::Rgb16 => "RGB16",
            Self::Rgba16 => "RGBA16",
            Self::RgbF32 => "RgbF32",
            Self::RgbaF32 => "RgbaF32",
            Self::Gray8 => "Gray8",
            Self::Gray16 => "Gray16",
            Self::GrayF32 => "GrayF32",
            Self::GrayA8 => "GrayA8",
            Self::GrayA16 => "GrayA16",
            Self::GrayAF32 => "GrayAF32",
            Self::Bgra8 => "BGRA8",
            Self::Rgbx8 => "RGBX8",
            Self::Bgrx8 => "BGRX8",
            Self::OklabF32 => "OklabF32",
            Self::OklabaF32 => "OklabaF32",
            Self::Cmyk8 => "CMYK8",
            Self::RgbF16 => "RgbF16",
            Self::RgbaF16 => "RgbaF16",
            Self::GrayF16 => "GrayF16",
            Self::GrayAF16 => "GrayAF16",
            _ => "Unknown",
        }
    }

    /// Resolve a format from channel type, layout, and alpha presence.
    ///
    /// Returns `None` for combinations that have no `PixelFormat` variant
    /// (e.g. `(U16, Bgra, _)`).
    #[inline]
    pub const fn from_parts(
        channel_type: ChannelType,
        layout: ChannelLayout,
        alpha: Option<AlphaMode>,
    ) -> Option<Self> {
        let is_padding = matches!(alpha, Some(AlphaMode::Undefined));
        match (channel_type, layout, is_padding) {
            (ChannelType::U8, ChannelLayout::Rgb, _) => Some(Self::Rgb8),
            (ChannelType::U16, ChannelLayout::Rgb, _) => Some(Self::Rgb16),
            (ChannelType::F32, ChannelLayout::Rgb, _) => Some(Self::RgbF32),
            (ChannelType::F16, ChannelLayout::Rgb, _) => Some(Self::RgbF16),

            (ChannelType::U8, ChannelLayout::Rgba, true) => Some(Self::Rgbx8),
            (ChannelType::U8, ChannelLayout::Rgba, false) => Some(Self::Rgba8),
            (ChannelType::U16, ChannelLayout::Rgba, _) => Some(Self::Rgba16),
            (ChannelType::F32, ChannelLayout::Rgba, _) => Some(Self::RgbaF32),
            (ChannelType::F16, ChannelLayout::Rgba, _) => Some(Self::RgbaF16),

            (ChannelType::U8, ChannelLayout::Gray, _) => Some(Self::Gray8),
            (ChannelType::U16, ChannelLayout::Gray, _) => Some(Self::Gray16),
            (ChannelType::F32, ChannelLayout::Gray, _) => Some(Self::GrayF32),
            (ChannelType::F16, ChannelLayout::Gray, _) => Some(Self::GrayF16),

            (ChannelType::U8, ChannelLayout::GrayAlpha, _) => Some(Self::GrayA8),
            (ChannelType::U16, ChannelLayout::GrayAlpha, _) => Some(Self::GrayA16),
            (ChannelType::F32, ChannelLayout::GrayAlpha, _) => Some(Self::GrayAF32),
            (ChannelType::F16, ChannelLayout::GrayAlpha, _) => Some(Self::GrayAF16),

            (ChannelType::U8, ChannelLayout::Bgra, true) => Some(Self::Bgrx8),
            (ChannelType::U8, ChannelLayout::Bgra, false) => Some(Self::Bgra8),

            (ChannelType::F32, ChannelLayout::Oklab, _) => Some(Self::OklabF32),
            (ChannelType::F32, ChannelLayout::OklabA, _) => Some(Self::OklabaF32),

            (ChannelType::U8, ChannelLayout::Cmyk, _) => Some(Self::Cmyk8),

            _ => None,
        }
    }

    /// Base descriptor with `Unknown` transfer and BT.709 primaries.
    #[allow(unreachable_patterns)]
    #[inline]
    pub const fn descriptor(self) -> PixelDescriptor {
        match self {
            Self::Rgb8 => PixelDescriptor::RGB8,
            Self::Rgba8 => PixelDescriptor::RGBA8,
            Self::Rgb16 => PixelDescriptor::RGB16,
            Self::Rgba16 => PixelDescriptor::RGBA16,
            Self::RgbF32 => PixelDescriptor::RGBF32,
            Self::RgbaF32 => PixelDescriptor::RGBAF32,
            Self::Gray8 => PixelDescriptor::GRAY8,
            Self::Gray16 => PixelDescriptor::GRAY16,
            Self::GrayF32 => PixelDescriptor::GRAYF32,
            Self::GrayA8 => PixelDescriptor::GRAYA8,
            Self::GrayA16 => PixelDescriptor::GRAYA16,
            Self::GrayAF32 => PixelDescriptor::GRAYAF32,
            Self::Bgra8 => PixelDescriptor::BGRA8,
            Self::Rgbx8 => PixelDescriptor::RGBX8,
            Self::Bgrx8 => PixelDescriptor::BGRX8,
            Self::OklabF32 => PixelDescriptor::OKLABF32,
            Self::OklabaF32 => PixelDescriptor::OKLABAF32,
            Self::Cmyk8 => PixelDescriptor::CMYK8,
            Self::RgbF16 => PixelDescriptor::RGBF16,
            Self::RgbaF16 => PixelDescriptor::RGBAF16,
            Self::GrayF16 => PixelDescriptor::GRAYF16,
            Self::GrayAF16 => PixelDescriptor::GRAYAF16,
            _ => PixelDescriptor::RGB8,
        }
    }
}

impl fmt::Display for PixelFormat {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.name())
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use alloc::format;
    use core::mem::size_of;

    use super::*;

    #[test]
    fn channel_type_byte_size() {
        assert_eq!(ChannelType::U8.byte_size(), 1);
        assert_eq!(ChannelType::U16.byte_size(), 2);
        assert_eq!(ChannelType::F16.byte_size(), 2);
        assert_eq!(ChannelType::F32.byte_size(), 4);
    }

    #[test]
    fn descriptor_bytes_per_pixel() {
        assert_eq!(PixelDescriptor::RGB8.bytes_per_pixel(), 3);
        assert_eq!(PixelDescriptor::RGBA8.bytes_per_pixel(), 4);
        assert_eq!(PixelDescriptor::GRAY8.bytes_per_pixel(), 1);
        assert_eq!(PixelDescriptor::RGBAF32.bytes_per_pixel(), 16);
        assert_eq!(PixelDescriptor::GRAYA8.bytes_per_pixel(), 2);
    }

    #[test]
    fn descriptor_bytes_per_channel() {
        assert_eq!(PixelDescriptor::RGB8.bytes_per_channel(), 1);
        assert_eq!(PixelDescriptor::RGB16_SRGB.bytes_per_channel(), 2);
        assert_eq!(PixelDescriptor::RGBAF32.bytes_per_channel(), 4);
        // The distinction this accessor exists for: per-sample width vs
        // all channels of a pixel.
        assert_ne!(
            PixelDescriptor::RGBA8.bytes_per_channel(),
            PixelDescriptor::RGBA8.bytes_per_pixel()
        );
    }

    #[test]
    fn bt2100_presets_carry_hdr_signaling() {
        let pq = PixelDescriptor::RGB16_BT2100_PQ;
        assert_eq!(pq.format, PixelFormat::Rgb16);
        assert_eq!(pq.transfer, TransferFunction::Pq);
        assert_eq!(pq.primaries, ColorPrimaries::Bt2020);
        assert_eq!(pq.signal_range, SignalRange::Full);

        let hlg = PixelDescriptor::RGB16_BT2100_HLG;
        assert_eq!(hlg.format, PixelFormat::Rgb16);
        assert_eq!(hlg.transfer, TransferFunction::Hlg);
        assert_eq!(hlg.primaries, ColorPrimaries::Bt2020);
        assert_eq!(hlg.signal_range, SignalRange::Full);

        // The presets must agree with spelling it out via new_full.
        assert_eq!(
            pq,
            PixelDescriptor::new_full(
                ChannelType::U16,
                ChannelLayout::Rgb,
                None,
                TransferFunction::Pq,
                ColorPrimaries::Bt2020,
            )
        );
    }

    #[test]
    fn descriptor_has_alpha() {
        assert!(!PixelDescriptor::RGB8.has_alpha());
        assert!(PixelDescriptor::RGBA8.has_alpha());
        assert!(!PixelDescriptor::RGBX8.has_alpha());
        assert!(PixelDescriptor::GRAYA8.has_alpha());
    }

    #[test]
    fn descriptor_is_grayscale() {
        assert!(PixelDescriptor::GRAY8.is_grayscale());
        assert!(PixelDescriptor::GRAYA8.is_grayscale());
        assert!(!PixelDescriptor::RGB8.is_grayscale());
    }

    #[test]
    fn layout_compatible() {
        assert!(PixelDescriptor::RGB8_SRGB.layout_compatible(PixelDescriptor::RGB8));
        assert!(!PixelDescriptor::RGB8.layout_compatible(PixelDescriptor::RGBA8));
    }

    #[test]
    fn pixel_format_descriptor_roundtrip() {
        let desc = PixelFormat::Rgba8.descriptor();
        assert_eq!(desc.layout(), ChannelLayout::Rgba);
        assert_eq!(desc.channel_type(), ChannelType::U8);
    }

    #[test]
    fn pixel_format_enum_basics() {
        assert_eq!(PixelFormat::Rgb8.channels(), 3);
        assert_eq!(PixelFormat::Rgba8.channels(), 4);
        assert!(PixelFormat::Rgba8.has_alpha_bytes());
        assert!(!PixelFormat::Rgb8.has_alpha_bytes());
        assert_eq!(PixelFormat::RgbF32.bytes_per_pixel(), 12);
        assert_eq!(PixelFormat::RgbaF32.bytes_per_pixel(), 16);
        assert_eq!(PixelFormat::Gray8.channels(), 1);
        assert!(PixelFormat::Gray8.is_grayscale());
        assert!(!PixelFormat::Rgb8.is_grayscale());
        assert_eq!(PixelFormat::Bgra8.byte_order(), ByteOrder::Bgr);
        assert_eq!(PixelFormat::Rgb8.byte_order(), ByteOrder::Native);
    }

    #[test]
    fn pixel_format_enum_size() {
        // Single-byte discriminant — much smaller than old 5-field struct.
        assert!(size_of::<PixelFormat>() <= 2);
    }

    #[test]
    fn pixel_format_from_parts_roundtrip() {
        let fmt = PixelFormat::Rgba8;
        let rebuilt =
            PixelFormat::from_parts(fmt.channel_type(), fmt.layout(), fmt.default_alpha());
        assert_eq!(rebuilt, Some(fmt));

        let fmt2 = PixelFormat::Bgra8;
        let rebuilt2 =
            PixelFormat::from_parts(fmt2.channel_type(), fmt2.layout(), fmt2.default_alpha());
        assert_eq!(rebuilt2, Some(fmt2));

        let fmt3 = PixelFormat::Gray8;
        let rebuilt3 =
            PixelFormat::from_parts(fmt3.channel_type(), fmt3.layout(), fmt3.default_alpha());
        assert_eq!(rebuilt3, Some(fmt3));
    }

    #[test]
    fn alpha_mode_semantics() {
        // None (Option) = no alpha channel
        assert!(!PixelDescriptor::RGB8.has_alpha());
        // Undefined = padding bytes, not real alpha
        assert!(!AlphaMode::Undefined.has_alpha());
        // Straight and Premultiplied = real alpha
        assert!(AlphaMode::Straight.has_alpha());
        assert!(AlphaMode::Premultiplied.has_alpha());
        assert!(AlphaMode::Opaque.has_alpha());
    }

    #[test]
    fn color_primaries_containment() {
        assert!(ColorPrimaries::Bt2020.contains(ColorPrimaries::DisplayP3));
        assert!(ColorPrimaries::Bt2020.contains(ColorPrimaries::Bt709));
        assert!(ColorPrimaries::DisplayP3.contains(ColorPrimaries::Bt709));
        assert!(!ColorPrimaries::Bt709.contains(ColorPrimaries::DisplayP3));
        assert!(!ColorPrimaries::Unknown.contains(ColorPrimaries::Bt709));
    }

    #[test]
    fn descriptor_size() {
        // PixelFormat (1 byte enum) + transfer (1) + alpha (2) + primaries (1) + signal_range (1) = ~6
        assert!(size_of::<PixelDescriptor>() <= 8);
    }

    #[test]
    fn color_model_channels() {
        assert_eq!(ColorModel::Gray.color_channels(), 1);
        assert_eq!(ColorModel::Rgb.color_channels(), 3);
        assert_eq!(ColorModel::YCbCr.color_channels(), 3);
        assert_eq!(ColorModel::Oklab.color_channels(), 3);
        assert_eq!(ColorModel::Cmyk.color_channels(), 4);
    }

    // --- PlaneSemantic tests ---

    // --- PlaneDescriptor tests ---

    // --- PlaneMask tests ---

    // --- PlaneLayout tests ---

    // --- MultiPlaneImage tests ---

    // --- PlaneRelationship tests ---

    #[test]
    fn reference_white_nits_values() {
        assert_eq!(TransferFunction::Pq.reference_white_nits(), 203.0);
        assert_eq!(TransferFunction::Srgb.reference_white_nits(), 1.0);
        assert_eq!(TransferFunction::Linear.reference_white_nits(), 1.0);
        assert_eq!(TransferFunction::Unknown.reference_white_nits(), 1.0);
    }

    // --- PlaneLayout mask tests ---

    // --- Display impl tests ---

    #[test]
    fn channel_type_display() {
        assert_eq!(format!("{}", ChannelType::U8), "U8");
        assert_eq!(format!("{}", ChannelType::U16), "U16");
        assert_eq!(format!("{}", ChannelType::F32), "F32");
        assert_eq!(format!("{}", ChannelType::F16), "F16");
    }

    #[test]
    fn channel_layout_display() {
        assert_eq!(format!("{}", ChannelLayout::Gray), "Gray");
        assert_eq!(format!("{}", ChannelLayout::GrayAlpha), "GrayAlpha");
        assert_eq!(format!("{}", ChannelLayout::Rgb), "RGB");
        assert_eq!(format!("{}", ChannelLayout::Rgba), "RGBA");
        assert_eq!(format!("{}", ChannelLayout::Bgra), "BGRA");
        assert_eq!(format!("{}", ChannelLayout::Oklab), "Oklab");
        assert_eq!(format!("{}", ChannelLayout::OklabA), "OklabA");
    }

    #[test]
    fn alpha_mode_display() {
        assert_eq!(format!("{}", AlphaMode::Undefined), "undefined");
        assert_eq!(format!("{}", AlphaMode::Straight), "straight");
        assert_eq!(format!("{}", AlphaMode::Premultiplied), "premultiplied");
        assert_eq!(format!("{}", AlphaMode::Opaque), "opaque");
    }

    #[test]
    fn transfer_function_display() {
        assert_eq!(format!("{}", TransferFunction::Linear), "linear");
        assert_eq!(format!("{}", TransferFunction::Srgb), "sRGB");
        assert_eq!(format!("{}", TransferFunction::Bt709), "BT.709");
        assert_eq!(format!("{}", TransferFunction::Pq), "PQ");
        assert_eq!(format!("{}", TransferFunction::Unknown), "unknown");
    }

    #[test]
    fn color_primaries_display() {
        assert_eq!(format!("{}", ColorPrimaries::Bt709), "BT.709");
        assert_eq!(format!("{}", ColorPrimaries::Bt2020), "BT.2020");
        assert_eq!(format!("{}", ColorPrimaries::DisplayP3), "Display P3");
        assert_eq!(format!("{}", ColorPrimaries::Unknown), "unknown");
    }

    #[test]
    fn signal_range_display() {
        assert_eq!(format!("{}", SignalRange::Full), "full");
        assert_eq!(format!("{}", SignalRange::Narrow), "narrow");
    }

    #[test]
    fn pixel_descriptor_display() {
        let s = format!("{}", PixelDescriptor::RGB8_SRGB);
        assert!(s.contains("U8"), "expected U8 in: {s}");
        assert!(s.contains("sRGB"), "expected sRGB in: {s}");

        let s = format!("{}", PixelDescriptor::RGBA8_SRGB);
        assert!(s.contains("alpha=straight"), "expected alpha in: {s}");
    }

    #[test]
    fn pixel_format_display() {
        let s = format!("{}", PixelFormat::Rgb8);
        assert!(s.contains("RGB8"));
        let s = format!("{}", PixelFormat::Bgra8);
        assert!(s.contains("BGRA8"));
    }

    // --- from_cicp / to_cicp tests ---

    #[test]
    fn transfer_function_from_cicp() {
        assert_eq!(
            TransferFunction::from_cicp(1),
            Some(TransferFunction::Bt709)
        );
        assert_eq!(
            TransferFunction::from_cicp(8),
            Some(TransferFunction::Linear)
        );
        assert_eq!(
            TransferFunction::from_cicp(13),
            Some(TransferFunction::Srgb)
        );
        assert_eq!(TransferFunction::from_cicp(16), Some(TransferFunction::Pq));
        assert_eq!(TransferFunction::from_cicp(18), Some(TransferFunction::Hlg));
        assert_eq!(TransferFunction::from_cicp(99), None);
    }

    #[test]
    fn transfer_function_to_cicp() {
        assert_eq!(TransferFunction::Bt709.to_cicp(), Some(1));
        assert_eq!(TransferFunction::Linear.to_cicp(), Some(8));
        assert_eq!(TransferFunction::Srgb.to_cicp(), Some(13));
        assert_eq!(TransferFunction::Pq.to_cicp(), Some(16));
        assert_eq!(TransferFunction::Hlg.to_cicp(), Some(18));
        assert_eq!(TransferFunction::Unknown.to_cicp(), None);
    }

    #[test]
    fn transfer_function_cicp_roundtrip() {
        for tf in [
            TransferFunction::Bt709,
            TransferFunction::Linear,
            TransferFunction::Srgb,
            TransferFunction::Pq,
        ] {
            let code = tf.to_cicp().unwrap();
            assert_eq!(TransferFunction::from_cicp(code), Some(tf));
        }
    }

    #[test]
    fn color_primaries_from_cicp() {
        assert_eq!(ColorPrimaries::from_cicp(1), Some(ColorPrimaries::Bt709));
        assert_eq!(ColorPrimaries::from_cicp(9), Some(ColorPrimaries::Bt2020));
        assert_eq!(
            ColorPrimaries::from_cicp(12),
            Some(ColorPrimaries::DisplayP3)
        );
        assert_eq!(ColorPrimaries::from_cicp(99), None);
    }

    #[test]
    fn color_primaries_to_cicp() {
        assert_eq!(ColorPrimaries::Bt709.to_cicp(), Some(1));
        assert_eq!(ColorPrimaries::Bt2020.to_cicp(), Some(9));
        assert_eq!(ColorPrimaries::DisplayP3.to_cicp(), Some(12));
        assert_eq!(ColorPrimaries::Unknown.to_cicp(), None);
    }

    // --- ChannelType helpers ---

    #[test]
    fn channel_type_helpers() {
        assert!(ChannelType::U8.is_u8());
        assert!(!ChannelType::U8.is_u16());
        assert!(ChannelType::U16.is_u16());
        assert!(ChannelType::F32.is_f32());
        assert!(ChannelType::F16.is_f16());
        assert!(ChannelType::U8.is_integer());
        assert!(ChannelType::U16.is_integer());
        assert!(!ChannelType::F32.is_integer());
        assert!(ChannelType::F32.is_float());
        assert!(ChannelType::F16.is_float());
        assert!(!ChannelType::U8.is_float());
    }

    // --- ChannelLayout helpers ---

    #[test]
    fn channel_layout_channels() {
        assert_eq!(ChannelLayout::Gray.channels(), 1);
        assert_eq!(ChannelLayout::GrayAlpha.channels(), 2);
        assert_eq!(ChannelLayout::Rgb.channels(), 3);
        assert_eq!(ChannelLayout::Rgba.channels(), 4);
        assert_eq!(ChannelLayout::Bgra.channels(), 4);
        assert_eq!(ChannelLayout::Oklab.channels(), 3);
        assert_eq!(ChannelLayout::OklabA.channels(), 4);
    }

    #[test]
    fn channel_layout_has_alpha() {
        assert!(!ChannelLayout::Gray.has_alpha());
        assert!(ChannelLayout::GrayAlpha.has_alpha());
        assert!(!ChannelLayout::Rgb.has_alpha());
        assert!(ChannelLayout::Rgba.has_alpha());
        assert!(ChannelLayout::Bgra.has_alpha());
        assert!(!ChannelLayout::Oklab.has_alpha());
        assert!(ChannelLayout::OklabA.has_alpha());
    }

    // --- PixelDescriptor builder methods ---

    #[test]
    fn with_transfer() {
        let desc = PixelDescriptor::RGB8_SRGB.with_transfer(TransferFunction::Linear);
        assert_eq!(desc.transfer(), TransferFunction::Linear);
        assert_eq!(desc.layout(), ChannelLayout::Rgb);
    }

    #[test]
    fn with_primaries() {
        let desc = PixelDescriptor::RGB8_SRGB.with_primaries(ColorPrimaries::DisplayP3);
        assert_eq!(desc.primaries, ColorPrimaries::DisplayP3);
    }

    #[test]
    fn with_signal_range() {
        let desc = PixelDescriptor::RGB8_SRGB.with_signal_range(SignalRange::Narrow);
        assert_eq!(desc.signal_range, SignalRange::Narrow);
    }

    #[test]
    fn with_alpha_mode() {
        let desc = PixelDescriptor::RGBA8_SRGB.with_alpha(Some(AlphaMode::Premultiplied));
        assert_eq!(desc.alpha(), Some(AlphaMode::Premultiplied));
    }

    // --- PixelDescriptor predicates ---

    #[test]
    fn is_opaque_and_may_have_transparency() {
        assert!(PixelDescriptor::RGB8_SRGB.is_opaque());
        assert!(!PixelDescriptor::RGB8_SRGB.may_have_transparency());
        assert!(!PixelDescriptor::RGBA8_SRGB.is_opaque());
        assert!(PixelDescriptor::RGBA8_SRGB.may_have_transparency());

        let rgbx = PixelDescriptor::new(
            ChannelType::U8,
            ChannelLayout::Rgba,
            Some(AlphaMode::Undefined),
            TransferFunction::Srgb,
        );
        assert!(rgbx.is_opaque());
        assert!(!rgbx.may_have_transparency());
    }

    #[test]
    fn is_linear_and_is_unknown_transfer() {
        assert!(!PixelDescriptor::RGB8_SRGB.is_linear());
        assert!(PixelDescriptor::RGBF32_LINEAR.is_linear());
        assert!(!PixelDescriptor::RGB8_SRGB.is_unknown_transfer());
        let desc = PixelDescriptor::RGB8_SRGB.with_transfer(TransferFunction::Unknown);
        assert!(desc.is_unknown_transfer());
    }

    #[test]
    fn min_alignment() {
        assert_eq!(PixelDescriptor::RGB8_SRGB.min_alignment(), 1);
        assert_eq!(PixelDescriptor::RGBF32_LINEAR.min_alignment(), 4);
    }

    #[test]
    fn aligned_stride() {
        assert_eq!(PixelDescriptor::RGB8_SRGB.aligned_stride(100), 300);
        assert_eq!(PixelDescriptor::RGBA8_SRGB.aligned_stride(100), 400);
        assert_eq!(PixelDescriptor::RGBF32_LINEAR.aligned_stride(10), 120);
    }

    #[test]
    fn simd_aligned_stride() {
        let stride = PixelDescriptor::RGB8_SRGB.simd_aligned_stride(100, 16);
        assert!(stride >= 300);
        assert_eq!(stride % 16, 0);
        assert_eq!(stride % 3, 0); // pixel-aligned
    }

    // --- new_full and from_pixel_format ---

    #[test]
    fn new_full_constructor() {
        let desc = PixelDescriptor::new_full(
            ChannelType::U8,
            ChannelLayout::Rgb,
            None,
            TransferFunction::Srgb,
            ColorPrimaries::DisplayP3,
        );
        assert_eq!(desc.primaries, ColorPrimaries::DisplayP3);
        assert_eq!(desc.transfer(), TransferFunction::Srgb);
    }

    #[test]
    fn from_pixel_format_constructor() {
        let desc = PixelDescriptor::from_pixel_format(PixelFormat::Rgba8);
        assert_eq!(desc.layout(), ChannelLayout::Rgba);
        assert_eq!(desc.transfer(), TransferFunction::Unknown);
        assert_eq!(desc.primaries, ColorPrimaries::Bt709);
        assert_eq!(desc.signal_range, SignalRange::Full);
    }

    // --- PixelFormat::name ---

    #[test]
    fn pixel_format_name() {
        assert_eq!(PixelFormat::Rgb8.name(), "RGB8");
        assert_eq!(PixelFormat::Bgra8.name(), "BGRA8");
        assert_eq!(PixelFormat::Gray8.name(), "Gray8");
    }

    // --- ColorModel ---

    #[test]
    fn color_model_display() {
        assert_eq!(format!("{}", ColorModel::Gray), "Gray");
        assert_eq!(format!("{}", ColorModel::Rgb), "RGB");
        assert_eq!(format!("{}", ColorModel::YCbCr), "YCbCr");
        assert_eq!(format!("{}", ColorModel::Oklab), "Oklab");
        assert_eq!(format!("{}", ColorModel::Cmyk), "CMYK");
    }

    // --- SignalRange default ---

    #[test]
    fn signal_range_default() {
        assert_eq!(SignalRange::default(), SignalRange::Full);
    }

    // --- ColorPrimaries default ---

    #[test]
    fn color_primaries_default() {
        assert_eq!(ColorPrimaries::default(), ColorPrimaries::Bt709);
    }

    // --- CMYK tests ---

    #[test]
    fn cmyk8_descriptor() {
        let d = PixelDescriptor::CMYK8;
        assert_eq!(d.color_model(), ColorModel::Cmyk);
        assert_eq!(d.channels(), 4);
        assert_eq!(d.bytes_per_pixel(), 4);
        assert_eq!(d.layout(), ChannelLayout::Cmyk);
        assert_eq!(d.channel_type(), ChannelType::U8);
        assert_eq!(d.transfer(), TransferFunction::Unknown);
        assert_eq!(d.primaries, ColorPrimaries::Bt709);
        assert!(!d.has_alpha());
        assert!(d.is_opaque());
    }

    #[test]
    fn cmyk8_pixel_format() {
        let fmt = PixelFormat::Cmyk8;
        assert_eq!(fmt.channels(), 4);
        assert_eq!(fmt.bytes_per_pixel(), 4);
        assert_eq!(fmt.channel_type(), ChannelType::U8);
        assert_eq!(fmt.layout(), ChannelLayout::Cmyk);
        assert_eq!(fmt.color_model(), ColorModel::Cmyk);
        assert!(!fmt.has_alpha_bytes());
        assert!(!fmt.is_grayscale());
        assert_eq!(fmt.name(), "CMYK8");
        assert_eq!(fmt.default_alpha(), None);
    }

    #[test]
    fn cmyk8_from_parts_roundtrip() {
        let fmt = PixelFormat::Cmyk8;
        let rebuilt =
            PixelFormat::from_parts(fmt.channel_type(), fmt.layout(), fmt.default_alpha());
        assert_eq!(rebuilt, Some(fmt));
    }

    #[test]
    fn cmyk8_descriptor_roundtrip() {
        let desc = PixelFormat::Cmyk8.descriptor();
        assert_eq!(desc, PixelDescriptor::CMYK8);
    }

    #[test]
    fn cmyk_channel_layout_display() {
        assert_eq!(format!("{}", ChannelLayout::Cmyk), "CMYK");
    }

    #[test]
    fn cmyk_channel_layout_no_alpha() {
        assert!(!ChannelLayout::Cmyk.has_alpha());
    }
}