Struct IccCache 

pub struct IccCache { /* private fields */ }

ICC color profile cache and transform manager.

Implementations

impl IccCache

pub fn new() -> Self

Create an empty ICC cache with default options (BPC Auto, no pre-supplied source CMYK profile).

pub fn new_with_options(opts: IccCacheOptions) -> Self

Create an ICC cache with the given options.

When opts.source_cmyk_profile is Some, the bytes are registered as the system CMYK profile (overriding any later Self::search_system_cmyk_profile call). Otherwise the cache starts empty and the caller is expected to supply a profile separately.

Examples found in repository

examples/icc_probe.rs (line 92)

fn main() {
    let path = std::env::args()
        .nth(1)
        .expect("usage: icc_probe <profile.icc>");
    let bytes = std::fs::read(&path).expect("read profile");
    dump_profile_shape(&bytes);
    let cases: &[(f64, f64, f64, f64)] = &[
        (0.15, 1.0, 1.0, 0.0),
        (0.0, 0.6, 1.0, 0.0),
        (0.0, 0.5, 0.9, 0.0),
        (0.0, 0.7, 1.0, 0.0),
        (0.15, 0.7, 1.0, 0.0),
        (0.0, 1.0, 1.0, 0.0),
        (0.0, 0.0, 0.0, 1.0),
        (0.0, 0.0, 0.0, 0.0),
        // Medium-light green range — covers the 0001056.pdf glove regression.
        (0.15, 0.05, 0.30, 0.0),
        (0.25, 0.10, 0.40, 0.0),
        (0.40, 0.15, 0.50, 0.0),
        (0.40, 0.0, 1.0, 0.0),
        (0.60, 0.0, 0.80, 0.0),
        (0.20, 0.20, 0.20, 0.0),
        // Process primaries — likely out of sRGB gamut.
        (1.0, 0.0, 0.0, 0.0),
        (0.0, 1.0, 0.0, 0.0),
        (0.0, 0.0, 1.0, 0.0),
        (1.0, 1.0, 0.0, 0.0),
    ];
    for mode in [BpcMode::Off, BpcMode::On] {
        println!("\n== BPC {:?} ==", mode);
        let opts = IccCacheOptions {
            bpc_mode: mode,
            source_cmyk_profile: Some(bytes.clone()),
        };
        let cache = IccCache::new_with_options(opts);
        for &(c, m, y, k) in cases {
            let rgb = cache.convert_cmyk_readonly(c, m, y, k).expect("convert");
            println!(
                "  CMYK({:.2},{:.2},{:.2},{:.2}) -> ({}, {}, {})",
                c,
                m,
                y,
                k,
                (rgb.0 * 255.0).round() as u8,
                (rgb.1 * 255.0).round() as u8,
                (rgb.2 * 255.0).round() as u8,
            );
        }
    }
}

pub fn bpc_mode(&self) -> BpcMode

Current Black Point Compensation mode.

pub fn hash_profile(bytes: &[u8]) -> ProfileHash

Compute the SHA-256 hash of an ICC profile without registering it.

pub fn register_profile(&mut self, bytes: &[u8]) -> Option<ProfileHash>

Register an ICC profile from raw bytes. Returns the SHA-256 hash on success.

pub fn register_profile_with_n( &mut self, bytes: &[u8], expected_n: Option<u32>, ) -> Option<ProfileHash>

Register an ICC profile, validating that its color space matches the expected component count expected_n. When the profile’s actual color space has a different number of components (e.g. an RGB profile stored with PDF /N 1), the profile is rejected so the caller can fall back to the alternate color space.

pub fn convert_color( &mut self, hash: &ProfileHash, components: &[f64], ) -> Option<(f64, f64, f64)>

Convert a single color through an ICC profile to sRGB. Returns (r, g, b) in [0, 1] range.

pub fn convert_color_readonly( &self, hash: &ProfileHash, components: &[f64], ) -> Option<(f64, f64, f64)>

Convert a single color through an ICC profile (read-only, no caching).

Same as convert_color but takes &self instead of &mut self, suitable for use from immutable contexts like rendering.

pub fn convert_image_8bit( &self, hash: &ProfileHash, samples: &[u8], pixel_count: usize, ) -> Option<Vec<u8>>

Bulk-convert 8-bit image samples through an ICC profile to RGB. Input: packed samples (Gray/RGB/CMYK depending on profile). Output: packed RGB bytes (3 bytes per pixel).

pub fn search_system_cmyk_profile(&mut self)

Search system paths for a CMYK ICC profile and register it.

pub fn load_cmyk_profile_bytes(&mut self, bytes: &[u8])

Load a CMYK ICC profile from raw bytes (for environments without filesystem access).

pub fn default_cmyk_hash(&self) -> Option<&ProfileHash>

Get the default CMYK profile hash, if a system CMYK profile was found.

pub fn has_profile(&self, hash: &ProfileHash) -> bool

Check if a profile hash has been registered.

pub fn get_profile_bytes(&self, hash: &ProfileHash) -> Option<Arc<Vec<u8>>>

Get the raw bytes of a registered ICC profile (for PDF embedding).

pub fn system_cmyk_bytes(&self) -> Option<&Arc<Vec<u8>>>

Get the raw bytes of the system CMYK profile (for re-registration in render threads).

pub fn set_system_cmyk(&mut self, bytes: &[u8], hash: ProfileHash)

Set the system CMYK profile from pre-loaded bytes and hash.

Used by --output-profile to substitute the auto-detected system CMYK profile with a user-specified one.

pub fn set_default_cmyk_hash(&mut self, hash: ProfileHash)

Set the default CMYK profile hash (used when building render-thread caches).

pub fn suspend_default_cmyk(&mut self) -> Option<ProfileHash>

Temporarily remove the default CMYK hash, returning the old value. Used to disable ICC CMYK conversion inside soft mask form rendering, where PLRM formulas produce correct luminosity values (ICC profiles map 100% K to non-zero RGB, breaking luminosity soft masks).

pub fn restore_default_cmyk(&mut self, hash: Option<ProfileHash>)

Restore a previously suspended default CMYK hash.

pub fn convert_cmyk( &mut self, c: f64, m: f64, y: f64, k: f64, ) -> Option<(f64, f64, f64)>

Convert CMYK to (r, g, b) using the default system CMYK profile. Returns None if no system CMYK profile is loaded.

pub fn convert_cmyk_readonly( &self, c: f64, m: f64, y: f64, k: f64, ) -> Option<(f64, f64, f64)>

Convert CMYK to (r, g, b) using the default system CMYK profile (read-only, no caching). Used by band renderers that only have &self access.

Examples found in repository

examples/icc_probe.rs (line 94)

fn main() {
    let path = std::env::args()
        .nth(1)
        .expect("usage: icc_probe <profile.icc>");
    let bytes = std::fs::read(&path).expect("read profile");
    dump_profile_shape(&bytes);
    let cases: &[(f64, f64, f64, f64)] = &[
        (0.15, 1.0, 1.0, 0.0),
        (0.0, 0.6, 1.0, 0.0),
        (0.0, 0.5, 0.9, 0.0),
        (0.0, 0.7, 1.0, 0.0),
        (0.15, 0.7, 1.0, 0.0),
        (0.0, 1.0, 1.0, 0.0),
        (0.0, 0.0, 0.0, 1.0),
        (0.0, 0.0, 0.0, 0.0),
        // Medium-light green range — covers the 0001056.pdf glove regression.
        (0.15, 0.05, 0.30, 0.0),
        (0.25, 0.10, 0.40, 0.0),
        (0.40, 0.15, 0.50, 0.0),
        (0.40, 0.0, 1.0, 0.0),
        (0.60, 0.0, 0.80, 0.0),
        (0.20, 0.20, 0.20, 0.0),
        // Process primaries — likely out of sRGB gamut.
        (1.0, 0.0, 0.0, 0.0),
        (0.0, 1.0, 0.0, 0.0),
        (0.0, 0.0, 1.0, 0.0),
        (1.0, 1.0, 0.0, 0.0),
    ];
    for mode in [BpcMode::Off, BpcMode::On] {
        println!("\n== BPC {:?} ==", mode);
        let opts = IccCacheOptions {
            bpc_mode: mode,
            source_cmyk_profile: Some(bytes.clone()),
        };
        let cache = IccCache::new_with_options(opts);
        for &(c, m, y, k) in cases {
            let rgb = cache.convert_cmyk_readonly(c, m, y, k).expect("convert");
            println!(
                "  CMYK({:.2},{:.2},{:.2},{:.2}) -> ({}, {}, {})",
                c,
                m,
                y,
                k,
                (rgb.0 * 255.0).round() as u8,
                (rgb.1 * 255.0).round() as u8,
                (rgb.2 * 255.0).round() as u8,
            );
        }
    }
}

pub fn prepare_reverse_cmyk(&mut self)

Pre-warm the lazy sRGB→CMYK reverse transform. Should be called once on the build thread that owns &mut IccCache, after the system CMYK profile has been registered, so that band renderers (which only hold &IccCache) can use Self::convert_rgb_to_cmyk_readonly without having to mutate state.

pub fn convert_rgb_to_cmyk_readonly( &self, r: f64, g: f64, b: f64, ) -> Option<[f64; 4]>

Convert an sRGB color to CMYK using the system CMYK profile, without mutating any state. Returns None when the reverse transform has not been pre-built (call Self::prepare_reverse_cmyk first) or when no system CMYK profile is registered.

The returned components are clamped to [0, 1].

pub fn round_trip_rgb_via_cmyk( &mut self, r: f64, g: f64, b: f64, ) -> Option<(f64, f64, f64)>

Round-trip an RGB color through the system CMYK profile: sRGB→CMYK→sRGB. Used when compositing in a DeviceCMYK page group — saturated RGB colors become more muted after passing through the CMYK gamut. Returns None if no CMYK profile is loaded.

pub fn disable(&mut self)

Disable all ICC color management — clears all profiles, transforms, and caches. Equivalent to the CLI’s --no-icc flag.

Trait Implementations

impl Clone for IccCache

fn clone(&self) -> IccCache

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for IccCache

fn default() -> Self

Returns the “default value” for a type.