zenpixels-convert 0.2.14

//! Runtime decode path for the bundled, transfer-grouped CICP→ICC blob.
//!
//! The blob ([`CICP_BUNDLE_LZ4`]) is 16 independent LZ4 blocks — one per
//! H.273 transfer-characteristics code — concatenated into one committed asset
//! and embedded via `include_bytes!`. The companion [`BUNDLE_GROUPS`] /
//! [`BUNDLE_PROFILES`] tables (generated by `icc-gen`'s `cicp_bundle_gen`
//! binary) say where each group lives in the blob and where each profile lives
//! inside its group's *decoded* bytes.
//!
//! On a lookup we binary-search [`BUNDLE_PROFILES`] for the requested
//! `(primaries, transfer)`; on a hit we decode **only that group** (lazily,
//! once, into a per-group [`OnceBox`] cache) and slice the profile out. Only the
//! groups actually touched stay resident — there's no permanent ~600 KiB
//! allocation of the whole decoded set. The decoded group lives in a `'static`
//! `OnceBox`, so the sliced profile is returned as a zero-copy
//! `Cow::Borrowed(&'static [u8])`.
//!
//! Each group's decoded bytes pack the **GRAY-class** profiles for the
//! transfer first (64 unique across the bundle after white-point dedup —
//! backing [`bundled_gray_profile_for_cicp`] and
//! `synthesize_gray_icc_for_cicp`), then the RGB ones. Sharing groups is
//! what makes gray coverage nearly free to ship: a gray profile's `kTRC`
//! payload is byte-identical to the RGB profiles' TRC payload for the same
//! transfer, so LZ4 collapses it (gray-first ordering keeps the match
//! distance inside lz4_flex's effective search range; the whole gray side
//! adds ~7.6 KB to the committed asset instead of a ~24 KB second blob).
//! One decoded group serves both lookup tables from one cache slot.
//!
//! Decode uses `lz4_flex`'s `safe-decode` (pure-Rust, `no_std`), so the whole
//! path stays within `#![forbid(unsafe_code)]`.

use alloc::borrow::Cow;
use alloc::boxed::Box;
use alloc::vec;
use alloc::vec::Vec;

use once_cell::race::OnceBox;

use super::cicp_bundle_index::{
    BUNDLE_GROUPS, BUNDLE_PROFILES, CICP_BUNDLE_LZ4, GRAY_BUNDLE_PROFILES, NUM_GROUPS,
};

/// Per-group decode cache. Each slot lazily holds one group's decoded bytes;
/// only groups that are actually requested are ever populated. A `static`
/// `OnceBox` yields a `&'static` reference from `get_or_init`, which is what
/// lets the public lookup hand back a borrowed (zero-copy) profile.
///
/// `OnceBox<T>` requires `T: Sized`, so the decoded bytes live in a `Vec<u8>`
/// (boxed by the cell) rather than a bare `[u8]`.
static GROUP_CACHE: [OnceBox<Vec<u8>>; NUM_GROUPS] = [const { OnceBox::new() }; NUM_GROUPS];

/// Decode group `group_index` (idempotent; cached for the program's lifetime).
///
/// Returns the group's full decoded bytes. `decompress_into` writes into an
/// exactly-sized buffer (the decompressed length is known from the index), so
/// there's no size-prefix parsing and no reallocation.
fn decode_group(group_index: usize) -> &'static [u8] {
    GROUP_CACHE[group_index].get_or_init(|| {
        let g = &BUNDLE_GROUPS[group_index];
        let block = &CICP_BUNDLE_LZ4[g.blob_offset..g.blob_offset + g.compressed_len];
        let mut out = vec![0u8; g.decompressed_len];
        let written = lz4_flex::block::decompress_into(block, &mut out)
            .expect("bundled CICP ICC group failed to LZ4-decode (corrupt committed asset)");
        debug_assert_eq!(
            written, g.decompressed_len,
            "decoded length disagrees with the index — regenerate the bundle"
        );
        Box::new(out)
    })
}

/// Look up a bundled ICC profile for a raw CICP `(primaries, transfer)` pair.
///
/// Returns the profile bytes if the combination is in the bundle, decoding (and
/// caching) the owning transfer group on first touch. The slice borrows the
/// `'static` group cache, so it's a zero-copy `Cow::Borrowed`.
///
/// Returns `None` for combinations not in the bundle (the sRGB / BT.709 default
/// pair handled upstream as `NotNeeded`, and any combo moxcms couldn't represent
/// at generation time).
pub(crate) fn bundled_profile_for_cicp(primaries: u8, transfer: u8) -> Option<Cow<'static, [u8]>> {
    let idx = BUNDLE_PROFILES
        .binary_search_by(|p| (p.primaries, p.transfer).cmp(&(primaries, transfer)))
        .ok()?;
    let p = &BUNDLE_PROFILES[idx];
    // Consistency: the profile's owning group must be the one that covers its
    // transfer. Cheap guard against an index/blob desync after a regen.
    debug_assert_eq!(
        BUNDLE_GROUPS[p.group_index].transfer, p.transfer,
        "profile→group transfer mismatch in the generated index"
    );
    let group = decode_group(p.group_index);
    let bytes = &group[p.offset_in_group..p.offset_in_group + p.len];
    Some(Cow::Borrowed(bytes))
}

/// Look up a bundled **GRAY-class** ICC profile for a raw CICP
/// `(primaries, transfer)` pair — the single-channel sibling of
/// [`bundled_profile_for_cicp`], served from the same groups and cache.
///
/// Returns `None` for combinations not in the bundle (the sRGB / BT.709
/// default pair handled upstream as `NotNeeded`, and any combo moxcms
/// couldn't represent at generation time).
pub(crate) fn bundled_gray_profile_for_cicp(
    primaries: u8,
    transfer: u8,
) -> Option<Cow<'static, [u8]>> {
    let idx = GRAY_BUNDLE_PROFILES
        .binary_search_by(|p| (p.primaries, p.transfer).cmp(&(primaries, transfer)))
        .ok()?;
    let p = &GRAY_BUNDLE_PROFILES[idx];
    debug_assert_eq!(
        BUNDLE_GROUPS[p.group_index].transfer, p.transfer,
        "gray profile→group transfer mismatch in the generated index"
    );
    let group = decode_group(p.group_index);
    let bytes = &group[p.offset_in_group..p.offset_in_group + p.len];
    Some(Cow::Borrowed(bytes))
}

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

    #[test]
    fn blob_offsets_and_lengths_are_consistent() {
        // The concatenated groups must exactly tile the blob with no gaps or
        // overruns, in group order.
        let mut expected_offset = 0usize;
        for g in &BUNDLE_GROUPS {
            assert_eq!(
                g.blob_offset, expected_offset,
                "group blob offsets must be contiguous"
            );
            expected_offset += g.compressed_len;
        }
        assert_eq!(
            expected_offset,
            CICP_BUNDLE_LZ4.len(),
            "groups must exactly cover the blob"
        );
    }

    #[test]
    fn every_group_decodes_to_its_declared_length() {
        for (i, g) in BUNDLE_GROUPS.iter().enumerate() {
            let decoded = decode_group(i);
            assert_eq!(
                decoded.len(),
                g.decompressed_len,
                "group {i} decoded length mismatch"
            );
        }
    }

    #[test]
    fn every_profile_slice_is_in_bounds_and_is_a_valid_icc() {
        for p in &BUNDLE_PROFILES {
            let got = bundled_profile_for_cicp(p.primaries, p.transfer)
                .expect("indexed profile must resolve");
            assert_eq!(got.len(), p.len, "profile length mismatch");
            // Minimal ICC structural sanity: 'acsp' signature at byte 36.
            assert!(got.len() >= 40, "profile too short to be an ICC");
            assert_eq!(
                &got[36..40],
                b"acsp",
                "({}, {}) is not a valid ICC profile (missing 'acsp')",
                p.primaries,
                p.transfer
            );
        }
    }

    #[test]
    fn miss_returns_none() {
        // primaries=2 (Unspecified) is never in the bundle.
        assert!(bundled_profile_for_cicp(2, 13).is_none());
        // The sRGB-default pair is handled upstream as NotNeeded and excluded.
        assert!(bundled_profile_for_cicp(1, 13).is_none());
        assert!(bundled_profile_for_cicp(1, 1).is_none());
    }

    #[test]
    fn every_gray_profile_is_a_valid_gray_class_icc() {
        for p in &GRAY_BUNDLE_PROFILES {
            let got = bundled_gray_profile_for_cicp(p.primaries, p.transfer)
                .expect("indexed gray profile must resolve");
            assert_eq!(got.len(), p.len, "gray profile length mismatch");
            assert!(got.len() >= 132, "gray profile too short to be an ICC");
            assert_eq!(
                &got[36..40],
                b"acsp",
                "gray ({}, {}) missing 'acsp' signature",
                p.primaries,
                p.transfer
            );
            // The whole point of the gray table: data colour space must be
            // GRAY (header offset 16..20), the field libpng checks against
            // the image's colour type.
            assert_eq!(
                &got[16..20],
                b"GRAY",
                "({}, {}) is not a GRAY-class profile",
                p.primaries,
                p.transfer
            );
            assert_eq!(
                &got[12..16],
                b"mntr",
                "gray ({}, {}) expected 'mntr' profile class",
                p.primaries,
                p.transfer
            );
        }
    }

    #[test]
    fn gray_primaries_sharing_a_white_point_share_bytes() {
        // BT.709 (1) and P3-D65 (12) are both D65-white: their gray profiles
        // for the same transfer must be the *same* bytes (dedup worked and
        // the profile carries no gamut). BT.470M (4, Illuminant C) must NOT
        // share them.
        let bt709 = bundled_gray_profile_for_cicp(1, 4).expect("(1, 4) in bundle");
        let p3d65 = bundled_gray_profile_for_cicp(12, 4).expect("(12, 4) in bundle");
        let ill_c = bundled_gray_profile_for_cicp(4, 4).expect("(4, 4) in bundle");
        assert_eq!(
            bt709.as_ref(),
            p3d65.as_ref(),
            "D65-white primaries must dedup to identical gray bytes"
        );
        assert_ne!(
            bt709.as_ref(),
            ill_c.as_ref(),
            "Illuminant-C white must differ from D65"
        );
    }

    #[test]
    fn gray_miss_returns_none() {
        assert!(bundled_gray_profile_for_cicp(2, 13).is_none());
        assert!(bundled_gray_profile_for_cicp(1, 13).is_none());
        assert!(bundled_gray_profile_for_cicp(1, 1).is_none());
    }

    /// ZERO-TOLERANCE roundtrip for the gray side: every GRAY profile
    /// decoded from the blob must be byte-identical to a fresh
    /// moxcms-based synthesis for the same CICP, modulo the masked
    /// creation-timestamp field. Pins the generator and runtime gray
    /// recipes together.
    #[cfg(feature = "cms-moxcms")]
    #[test]
    fn gray_blob_decodes_byte_identical_to_moxcms() {
        use crate::Cicp;
        fn mask_timestamp(bytes: &[u8]) -> alloc::vec::Vec<u8> {
            let mut v = bytes.to_vec();
            if v.len() >= 36 {
                v[24..36].fill(0);
            }
            v
        }

        let mut checked = 0usize;
        for p in &GRAY_BUNDLE_PROFILES {
            let from_blob = bundled_gray_profile_for_cicp(p.primaries, p.transfer)
                .expect("indexed gray profile must resolve");
            let from_moxcms = crate::cms_moxcms::gray_icc_bytes_for_cicp(&Cicp::new(
                p.primaries,
                p.transfer,
                0,
                true,
            ))
            .unwrap_or_else(|| {
                panic!(
                    "moxcms could not regenerate gray ({}, {}) — index/grid desync",
                    p.primaries, p.transfer
                )
            });
            assert_eq!(
                from_blob.as_ref(),
                mask_timestamp(&from_moxcms).as_slice(),
                "gray blob bytes for ({}, {}) diverge from a fresh moxcms generation",
                p.primaries,
                p.transfer
            );
            checked += 1;
        }
        assert_eq!(checked, 174, "expected to roundtrip all 174 gray combos");
    }

    /// Round-trip recognition guard for **every** profile this crate
    /// embeds. RGB bundle profiles must carry an exact, recoverable CICP
    /// description via `zenpixels::icc::extract_cicp`; GRAY profiles
    /// (which ICC.1 forbids from carrying a cicp tag) must be covered by
    /// the normalized-hash identification tables exactly per the pinned
    /// transfer sets. When the embedded profiles change — regeneration,
    /// recipe edits, moxcms bumps — this is the gate that flags any
    /// profile that silently became unrecognizable to the ecosystem.
    #[test]
    fn every_bundled_profile_roundtrips_through_extract_cicp() {
        for p in &BUNDLE_PROFILES {
            let icc = bundled_profile_for_cicp(p.primaries, p.transfer)
                .expect("indexed profile must resolve");
            let got = zenpixels::icc::extract_cicp(&icc).unwrap_or_else(|| {
                panic!(
                    "RGB profile ({}, {}) has no recoverable cicp tag",
                    p.primaries, p.transfer
                )
            });
            assert_eq!(
                (got.color_primaries, got.transfer_characteristics),
                (p.primaries, p.transfer),
                "RGB profile cicp tag drifted from its identity"
            );
        }

        // GRAY profiles cannot carry a cicp tag — ICC.1 restricts the
        // tag to RGB / YCbCr / XYZ data colour spaces — so their
        // recognition rides the normalized-hash tables instead
        // (regenerated by `just icc-gen`, which ingests this committed
        // bundle). Pin the coverage in BOTH directions: a regeneration
        // that gains or loses a transfer must flip one of these
        // assertions and force a conscious update.
        //
        // Recognized: every white point of these transfers hash-matches
        // a reference curve within the table tolerance.
        const GRAY_HASH_RECOGNIZED_TC: &[u8] = &[1, 4, 6, 8, 11, 12, 13, 14, 15, 16];
        // Gaps: Gamma28 (5), SMPTE 240M (7), Log100/Log316 (9/10),
        // ST 428 (17), and HLG (18 — its curv-LUT encoding exceeds the
        // ±56/65535 identification tolerance vs the analytic reference).
        const GRAY_HASH_GAP_TC: &[u8] = &[5, 7, 9, 10, 17, 18];

        for p in &GRAY_BUNDLE_PROFILES {
            let icc = bundled_gray_profile_for_cicp(p.primaries, p.transfer)
                .expect("indexed gray profile must resolve");
            assert!(
                zenpixels::icc::extract_cicp(&icc).is_none(),
                "GRAY profiles must not carry a cicp tag (ICC.1 forbids it \
                 outside RGB/YCbCr/XYZ); ({}, {}) has one",
                p.primaries,
                p.transfer
            );
            let identified = zenpixels::icc::identify_common(&icc);
            if GRAY_HASH_RECOGNIZED_TC.contains(&p.transfer) {
                assert!(
                    identified.is_some(),
                    "GRAY ({}, {}) fell out of the identification table — \
                     regenerate with `just icc-gen` or update the pinned sets",
                    p.primaries,
                    p.transfer
                );
            } else {
                assert!(
                    GRAY_HASH_GAP_TC.contains(&p.transfer),
                    "transfer {} missing from both pinned sets",
                    p.transfer
                );
                assert!(
                    identified.is_none(),
                    "GRAY ({}, {}) became hash-identifiable — move its \
                     transfer into GRAY_HASH_RECOGNIZED_TC",
                    p.primaries,
                    p.transfer
                );
            }
        }
    }

    /// The curated `&'static` consts must stay recognizable by the
    /// normalized-hash identification tables in `zenpixels::icc` — if a
    /// profile swap or a table regeneration drops one, downstream
    /// CMS-bypass and the gray-collapse identification path lose it.
    #[test]
    fn bundled_consts_are_hash_identified() {
        for (bytes, name) in [
            (crate::icc_profiles::DISPLAY_P3_V4, "DisplayP3Compat v4"),
            (crate::icc_profiles::DISPLAY_P3_V2, "DisplayP3Compat v2"),
            (crate::icc_profiles::ADOBE_RGB, "AdobeCompat v2"),
            (crate::icc_profiles::REC2020_V4, "Rec2020Compat v4"),
        ] {
            assert!(
                zenpixels::icc::identify_common(bytes).is_some(),
                "{name} fell out of the zenpixels identification table"
            );
        }
    }

    /// Golden pin of the committed blob's sha256. If this fails, the blob was
    /// regenerated (or corrupted) — review the diff and, if intended, update
    /// this constant alongside the new blob. Catches an *accidental* regen
    /// landing in a commit.
    #[test]
    fn golden_blob_sha256_is_pinned() {
        use sha2::{Digest, Sha256};
        const EXPECTED: &str = "b4a8f12c039f8b904844136e09cc37147f3b869f5b52bce56630872d4a9d3264";
        let digest = Sha256::digest(CICP_BUNDLE_LZ4);
        let hex: alloc::string::String = digest.iter().map(|b| alloc::format!("{b:02x}")).collect();
        assert_eq!(
            hex,
            EXPECTED,
            "committed cicp_bundle.lz4 sha256 changed — was the blob regenerated? \
             (len = {})",
            CICP_BUNDLE_LZ4.len()
        );
    }

    /// ZERO-TOLERANCE roundtrip: every profile decoded from the blob must be
    /// **byte-identical** to what moxcms generates for the same CICP, modulo the
    /// non-colorimetric creation-timestamp field (bytes 24..36) that moxcms
    /// stamps with the current wall-clock time. The generator zeroes that field
    /// for a reproducible blob; here we zero it on the fresh moxcms bytes too so
    /// the comparison measures only colour-defining content. Everything else —
    /// colorants, TRC/LUT, chad, CICP tag — must match exactly: no silent drift,
    /// no precision loss. Also catches a moxcms version bump that would shift the
    /// canonical bytes (the committed blob would then no longer match).
    #[cfg(feature = "cms-moxcms")]
    #[test]
    fn blob_decodes_byte_identical_to_moxcms() {
        use crate::Cicp;
        // The header creation date/time (bytes 24..36) is wall-clock and not
        // part of the colour description — masked on both sides.
        fn mask_timestamp(bytes: &[u8]) -> alloc::vec::Vec<u8> {
            let mut v = bytes.to_vec();
            if v.len() >= 36 {
                v[24..36].fill(0);
            }
            v
        }

        let mut checked = 0usize;
        for p in &BUNDLE_PROFILES {
            let from_blob = bundled_profile_for_cicp(p.primaries, p.transfer)
                .expect("indexed profile must resolve");
            let from_moxcms =
                crate::cms_moxcms::icc_bytes_for_cicp(&Cicp::new(p.primaries, p.transfer, 0, true))
                    .unwrap_or_else(|| {
                        panic!(
                            "moxcms could not regenerate ({}, {}) — index/grid desync",
                            p.primaries, p.transfer
                        )
                    });
            assert_eq!(
                from_blob.as_ref(),
                mask_timestamp(&from_moxcms).as_slice(),
                "blob bytes for ({}, {}) diverge from a fresh moxcms generation \
                 (moxcms version bump or generator drift)",
                p.primaries,
                p.transfer
            );
            checked += 1;
        }
        assert_eq!(
            checked, 174,
            "expected to roundtrip all 174 bundled profiles"
        );
    }
}