Enum GainMapRender 

#[non_exhaustive]
pub enum GainMapRender {
    BaseOnly,
    ReconstructHdr {
        target_headroom: Option<f32>,
    },
    Components,
}

How a decoder should render a gain-map (HDR) image — the caller’s intent for what decode() produces.

A gain-map file (AVIF tmap, JXL jhgm, JPEG UltraHDR) carries an SDR base image plus a gain map that reconstructs HDR on capable displays. This selects which rendition the decode output holds. Set it on the decode job via DecodeJob::with_gain_map_render.

zencodec carries no HDR math: Components (extract + surface, no compositing) is the cheap codec-only path that a transcode wants, and ReconstructHdr (apply the gain map → HDR) is honored only by codecs that advertise DecodeCapabilities::reconstructs_hdr. When a codec can’t reconstruct, the apply math lives one layer up — apply the DecodedGainMap from Components via ultrahdr-core.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

BaseOnly

Decode only the SDR base image; ignore the gain map. Default — an SDR consumer gets a normal SDR image (and an SDR-sized buffer), no surprise HDR.

ReconstructHdr

Reconstruct HDR by applying the gain map to the base, rendered for the display’s HDR headroom. Output is an HDR pixel format (negotiated through the normal ranked-descriptor preference). Honored only when the decoder’s reconstructs_hdr capability is set; a decoder without it surfaces Components or reports UnsupportedOperation — never silently SDR-labeled-as-HDR.

Envelope obligation. The reconstructed PixelBuffer carries the HDR signal (its descriptor’s transfer/primaries/range), but not the luminance envelope. A codec honoring this must populate the envelope on the output ImageInfo’s SourceColor — mastering_display (from the gain map’s alternate-image capacity) and content_light_level — so a downstream full native-HDR encode is complete. MaxCLL/MaxFALL are measured, so the encoder recomputes them from the actual reconstructed pixels; what the decoder carries is the derived peak and the (invariant) mastering display. Without this the envelope is silently lost on a gain-map → native-HDR transcode.

Fields

target_headroom: Option<f32>

Target display HDR headroom (linear multiple of SDR white). None = the gain map’s encoded maximum (full reconstruction). Transcoding to native HDR uses None; Some(h) renders for a specific display or HDR class. (Transcoding to another gain map doesn’t reconstruct at all — that’s Components.)

Canonical None boost (normative): resolve the f32 boost as (params.linear_alternate_headroom() as f32).max(1.0) — f64 exp2 of the log2 headroom, rounded to f32 once. Implementations applying via ultrahdr-core should use its full_reconstruction_boost helper. Double-rounding routes (2f32.powf(stops as f32)) can land 1 ULP away and break bit-identical reconstruction across codecs (imazen/heic#20).

No-gain-map input: decoders return the base rendition (the image is the image) rather than erroring; the error path is for gain-map signal that is present but unusable.

Components

Decode the SDR base and surface the gain map (a DecodedGainMap in the decode output’s extras) without compositing — for transcoding or custom HDR processing. Equivalent to the older with_extract_gain_map(true).

Trait Implementations

impl Clone for GainMapRender

fn clone(&self) -> GainMapRender

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for GainMapRender

impl Debug for GainMapRender

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

Formats the value using the given formatter.

impl Default for GainMapRender

fn default() -> GainMapRender

Returns the “default value” for a type.

impl PartialEq for GainMapRender

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for GainMapRender