Struct ConvertOptions 

#[non_exhaustive]
pub struct ConvertOptions {
    pub gray_expand: GrayExpand,
    pub alpha_policy: AlphaPolicy,
    pub depth_policy: DepthPolicy,
    pub luma: Option<LumaCoefficients>,
    pub clip_out_of_gamut: bool,
}

Explicit options for pixel format conversion. All lossy operations require a policy choice — no silent defaults.

Construct via struct literal for full control, or use the convenience constructors and with_* builders for common patterns:

use zenpixels::{ConvertOptions, AlphaPolicy, DepthPolicy};

// Forbid all lossy operations (safe default)
let strict = ConvertOptions::forbid_lossy();

// Allow common lossy operations with sensible defaults
let permissive = ConvertOptions::permissive();

// Customize from a preset
let custom = ConvertOptions::permissive()
    .with_alpha_policy(AlphaPolicy::CompositeOnto { r: 255, g: 255, b: 255 })
    .with_depth_policy(DepthPolicy::Truncate);

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.

gray_expand: GrayExpand

How to expand grayscale to RGB.

alpha_policy: AlphaPolicy

How to handle alpha removal.

depth_policy: DepthPolicy

How to handle depth reduction.

luma: Option<LumaCoefficients>

Luma coefficients for RGB→Gray conversion. None means RGB→Gray is forbidden (returns ConvertError::RgbToGray).

clip_out_of_gamut: bool

Whether to clamp out-of-gamut values to [0, 1] during f32 transfer function conversions.

• true (default): clamp sRGB/BT.709/PQ/HLG transfers to [0, 1]. Matches display expectations; safe for standard workflows.
• false: use sign-preserving extended-range transfer functions. Preserves out-of-gamut (negative, > 1.0) values through the f32 pipeline for HDR and wide-gamut workflows where tone mapping or gamut mapping happens later in the pipeline.

Only affects f32 intermediate conversions. u8/u16 outputs always clip since those formats can’t represent out-of-gamut values.

Implementations

impl ConvertOptions

pub const fn forbid_lossy() -> ConvertOptions

Forbid all lossy operations.

• Alpha removal: forbidden (returns error)
• Depth reduction: forbidden (returns error)
• RGB→Gray: forbidden (returns error)
• Gray→RGB: broadcast (lossless)

Use this as a starting point when you want to ensure no data loss, then selectively relax with with_* methods.

pub const fn permissive() -> ConvertOptions

Allow common lossy operations with sensible defaults.

• Alpha removal: discard only if all pixels are opaque
• Depth reduction: round to nearest
• RGB→Gray: BT.709 luma coefficients
• Gray→RGB: broadcast (lossless)

pub const fn with_alpha_policy(self, policy: AlphaPolicy) -> ConvertOptions

Set the alpha removal policy.

pub const fn with_depth_policy(self, policy: DepthPolicy) -> ConvertOptions

Set the depth reduction policy.

pub const fn with_gray_expand(self, expand: GrayExpand) -> ConvertOptions

Set the grayscale expansion method.

pub const fn with_clip_out_of_gamut(self, clip: bool) -> ConvertOptions

Set whether f32 transfer conversions clamp to [0, 1] (true, default) or preserve extended-range values via sign-preserving transfers (false). u8/u16 outputs always clip.

pub const fn with_luma(self, luma: Option<LumaCoefficients>) -> ConvertOptions

Set the luma coefficients for RGB→Gray conversion.

Pass None to forbid RGB→Gray conversion.

Trait Implementations

impl Clone for ConvertOptions

fn clone(&self) -> ConvertOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ConvertOptions

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

Formats the value using the given formatter.

impl Hash for ConvertOptions

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for ConvertOptions

fn eq(&self, other: &ConvertOptions) -> 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 ConvertOptions

impl Eq for ConvertOptions

impl StructuralPartialEq for ConvertOptions