Struct Provenance 

#[non_exhaustive]
pub struct Provenance {
    pub origin_depth: ChannelType,
    pub origin_primaries: ColorPrimaries,
}

Tracks where pixel data came from, so the cost model can distinguish “f32 that was widened from u8 JPEG” (lossless round-trip back to u8) from “f32 that was decoded from a 16-bit EXR” (lossy truncation to u8).

Without provenance, depth_cost(f32 → u8) always reports high loss. With provenance, it can see that the data’s true precision is u8, so the round-trip is lossless.

Gamut provenance

origin_primaries tracks the gamut of the original source, enabling lossless round-trip detection for gamut conversions. For example, sRGB data placed in BT.2020 for processing can round-trip back to sRGB losslessly — but only if no operations expanded the actual color usage (e.g., saturation boost filling the wider gamut). When an operation does expand gamut usage, the caller must update provenance via invalidate_primaries to reflect that the data now genuinely uses the wider gamut.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

origin_depth: ChannelType

The channel depth of the original source data.

For a JPEG (u8 sRGB) decoded into f32 for resize, this is U8. For an EXR (f32) loaded directly, this is F32. For a 16-bit PNG, this is U16.

origin_primaries: ColorPrimaries

The color primaries of the original source data.

For a standard sRGB JPEG, this is Bt709. For a Display P3 image, this is DisplayP3. Used to detect when converting to a narrower gamut is lossless (the source fits entirely within the target).

Important: If an operation expands the data’s gamut usage (e.g., saturation boost in BT.2020 that pushes colors outside the original sRGB gamut), call invalidate_primaries to update this to the current working primaries. Otherwise the cost model will incorrectly report the gamut narrowing as lossless.

Implementations

impl Provenance

pub fn from_source(desc: PixelDescriptor) -> Self

Assume the descriptor’s properties are the true origin characteristics.

This is the conservative default: if you don’t know the data’s history, assume its current format is its true origin.

pub const fn with_origin_depth(origin_depth: ChannelType) -> Self

Create provenance with an explicit origin depth. Primaries default to BT.709.

Use this when the data has been widened from a known source depth. For example, a JPEG (u8) decoded into f32 for resize:

let provenance = Provenance::with_origin_depth(ChannelType::U8);

pub const fn with_origin( origin_depth: ChannelType, origin_primaries: ColorPrimaries, ) -> Self

Create provenance with explicit origin depth and primaries.

pub fn with_origin_primaries( desc: PixelDescriptor, primaries: ColorPrimaries, ) -> Self

Create provenance with an explicit origin primaries. Depth defaults to the descriptor’s current channel type.

pub fn invalidate_primaries(&mut self, current: ColorPrimaries)

Mark the gamut provenance as invalid (matches current format).

Call this after any operation that expands the data’s color usage beyond the original gamut. For example, if sRGB data is converted to BT.2020 and then saturation is boosted to fill the wider gamut, the origin is no longer sRGB — the data genuinely uses BT.2020.

After this call, converting to a narrower gamut (e.g., back to sRGB) will correctly report gamut clipping loss.

Trait Implementations

impl Clone for Provenance

fn clone(&self) -> Provenance

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Provenance

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Provenance

fn eq(&self, other: &Provenance) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Provenance

impl Eq for Provenance

impl StructuralPartialEq for Provenance