Struct HdrConfig 

#[non_exhaustive]
pub struct HdrConfig {
    pub source_peak_nits: f32,
    pub target_peak_nits: f32,
    pub gamut_knee: f32,
}

HDR→SDR tone-mapping configuration for ConvertPlan::new_with_hdr_config.

Bundles the source-peak luminance (mandatory — the curve is parameterized by it), target-peak luminance (typically 100 cd/m² for SDR), and the OKLch soft chroma-compression knee (production default 0.96).

Construct via for_source_peak and refine with the with_* builders — the struct is #[non_exhaustive] so future knobs can land additively without a breaking release. The existing fields stay pub for reading (and in-place mutation).

Both peak fields must be positive and finite; ConvertPlan::new_with_hdr_config rejects anything else (including the unset Default value) with ConvertError::HdrSourceRequiresPeak instead of silently tone-mapping through a degenerate curve.

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.

source_peak_nits: f32

HDR source peak luminance in cd/m². The BT.2446-A curve treats 1.0 source-normalized as this peak. Typical values: 1000 (HDR10, Apple HDR), 4000 (HDR10+ reference), 10000 (PQ peak).

target_peak_nits: f32

SDR target peak luminance in cd/m². Typical value: 100 (BT.709 / sRGB diffuse-white peak; BT.1886 reference).

gamut_knee: f32

Fraction of max chroma where OKLch soft compression kicks in (0.0–1.0). 0.96 (the default) compresses only the outermost 4 % of the gamut; lower values bring the compression in earlier. Ignored when the target primaries are BT.2020 (wide-gamut output mode emits no SoftCompressOklch step).

The default was calibrated against the 76-sample imazen-26 gain-mapped corpus on 2026-06-23: 0.96 is the largest knee (least desaturation) where the corpus-p90 fraction of pre-clamp out-of-gamut pixels stays under 0.1 %. Findings: zentone/benchmarks/softcompress_knee_findings_2026-06-23.md.

Implementations

impl HdrConfig

pub fn for_source_peak(source_peak_nits: f32) -> Self

Config for an HDR source with the given peak luminance in cd/m², keeping the calibrated defaults for everything else (target_peak_nits = 100.0, gamut_knee = 0.96).

Typical source_peak_nits values: 1000 (HDR10, Apple HDR), 4000 (HDR10+ reference), 10000 (PQ peak) — or better, the measured MaxCLL of the actual content (CllMeasure::measure_max).

pub fn with_target_peak_nits(self, nits: f32) -> Self

Set the SDR target peak luminance in cd/m² (default 100.0).

pub fn with_gamut_knee(self, knee: f32) -> Self

Set the OKLch soft-compression knee (default 0.96; meaningful range 0.0..=1.0 — values outside it are not validated and produce under-/over-compression rather than an error).

Trait Implementations

impl Clone for HdrConfig

fn clone(&self) -> HdrConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for HdrConfig

impl Debug for HdrConfig

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

Formats the value using the given formatter.

impl Default for HdrConfig

Available on crate feature hdr-experimental only.

fn default() -> Self

Pipeline defaults: target_peak_nits = 100.0 (SDR reference white) and gamut_knee = 0.96 (empirically calibrated against the imazen-26 gain-mapped HDR corpus, 2026-06-23). source_peak_nits has no default — it returns 0.0 (“unset”), which ConvertPlan::new_with_hdr_config rejects with ConvertError::HdrSourceRequiresPeak. Start from HdrConfig::for_source_peak instead.

impl PartialEq for HdrConfig

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for HdrConfig