Struct LossyConfig 

pub struct LossyConfig { /* private fields */ }

Lossy (VarDCT) encoding configuration.

No Default — distance/quality is a required choice.

Implementations

impl LossyConfig

pub fn new(distance: f32) -> Self

Create with butteraugli distance (1.0 = high quality). Default effort 7.

pub fn from_quality(quality: Quality) -> Result<Self, EncodeError>

Create from a Quality specification.

pub fn with_effort(self, effort: u8) -> Self

Set effort level (1–10). Higher effort = slower, better compression.

This adjusts all effort-dependent defaults:

• e1–3: DCT8 only, Huffman, no gaborish/patches/butteraugli
• e4: + ANS entropy coding, custom coefficient orders
• e5: + gaborish, pixel-domain loss, AC strategy search, AdjustQuantBlockAC
• e6: + DCT4x8/AFV strategies, non-aligned eval, EPF dynamic sharpness
• e7: + patches, error diffusion, CfL two-pass, LZ77 RLE, DCT64 strategies
• e8: + butteraugli loop (2 iters), LZ77 greedy, WP param search (2 modes)
• e9–10: + LZ77 optimal (Viterbi DP), 4 butteraugli iters, WP search (5 modes)

Individual with_*() calls after with_effort() override these defaults.

pub fn with_mode(self, mode: EncoderMode) -> Self

Set encoder mode (default: EncoderMode::Reference).

Reference matches libjxl’s algorithm choices for comparable output. Experimental enables encoder-specific improvements.

pub fn mode(&self) -> EncoderMode

Current encoder mode.

pub fn with_ans(self, enable: bool) -> Self

Enable/disable ANS entropy coding (default: true).

pub fn with_gaborish(self, enable: bool) -> Self

Enable/disable gaborish inverse pre-filter (default: true).

pub fn with_noise(self, enable: bool) -> Self

Enable/disable noise synthesis (default: false).

pub fn with_denoise(self, enable: bool) -> Self

Enable/disable Wiener denoising pre-filter (default: false). Implies noise.

pub fn with_error_diffusion(self, enable: bool) -> Self

Enable/disable error diffusion in AC quantization (default: false).

Error diffusion propagates 1/4 of the quantization error to the next coefficient in zigzag order. Note: libjxl’s QuantizeBlockAC accepts this parameter but never references it — the feature is effectively a no-op in the reference encoder. Our implementation actually performs the diffusion, which can hurt quality on certain content (bright features in dark regions), especially when combined with gaborish.

pub fn with_pixel_domain_loss(self, enable: bool) -> Self

Enable/disable pixel-domain loss in strategy selection (default: true).

pub fn with_lz77(self, enable: bool) -> Self

Enable/disable LZ77 backward references (default: false).

pub fn with_lz77_method(self, method: Lz77Method) -> Self

Set LZ77 method (default: Greedy).

pub fn with_force_strategy(self, strategy: Option<u8>) -> Self

Force a specific AC strategy for all blocks. None for auto-selection.

pub fn with_max_strategy_size(self, size: Option<u8>) -> Self

Limit the maximum AC strategy transform size.

Controls the largest DCT transform the encoder will consider:

• 8: Only 8×8-class transforms (DCT8, DCT4x4, DCT4x8, AFV, IDENTITY, DCT2x2)
• 16: Up to 16×16 (adds DCT16x16, DCT16x8, DCT8x16)
• 32: Up to 32×32 (adds DCT32x32, DCT32x16, DCT16x32)
• 64: No restriction (adds DCT64x64, DCT64x32, DCT32x64) — the default

None means no restriction (same as 64). Values are clamped to the nearest valid size.

pub fn with_patches(self, enable: bool) -> Self

Enable/disable patches (dictionary-based repeated pattern detection). Default: true. Huge wins on screenshots, zero cost on photos.

pub fn with_splines(self, splines: Vec<Spline>) -> Self

Set manual splines to overlay on the image.

Splines are Gaussian-blurred parametric curves overlaid additively. They encode thin features (power lines, horizons) efficiently. The encoder subtracts splines from XYB before VarDCT; the decoder adds them back after reconstruction. Default: None.

pub fn with_progressive(self, mode: ProgressiveMode) -> Self

Set progressive encoding mode (default: Single = no progressive).

Progressive encoding splits AC coefficients across multiple passes, allowing decoders to render coarse previews before the full file is received.

pub fn with_lf_frame(self, enable: bool) -> Self

Enable LfFrame (separate DC frame).

When true, DC coefficients are encoded as a separate modular frame before the main VarDCT frame, matching libjxl’s progressive_dc >= 1.

pub fn with_butteraugli_iters(self, n: u32) -> Self

Set butteraugli quantization loop iterations explicitly.

Overrides the automatic effort-based default (effort 7: 0, effort 8: 2, effort 9+: 4). Requires the butteraugli-loop feature.

pub fn with_threads(self, threads: usize) -> Self

Set thread count for parallel encoding.

• 0 (default): use the ambient rayon pool. The caller can control thread count by wrapping the encode call in pool.install(|| ...).
• 1: force sequential encoding (no rayon).
• N >= 2: create a dedicated N-thread pool for this encode.

Requires the parallel feature. When parallel is not enabled, this value is ignored and encoding is always sequential.

pub fn distance(&self) -> f32

Current butteraugli distance.

pub fn effort(&self) -> u8

Current effort level.

pub fn ans(&self) -> bool

Whether ANS entropy coding is enabled.

pub fn gaborish(&self) -> bool

Whether gaborish inverse pre-filter is enabled.

pub fn noise(&self) -> bool

Whether noise synthesis is enabled.

pub fn denoise(&self) -> bool

Whether Wiener denoising pre-filter is enabled.

pub fn error_diffusion(&self) -> bool

Whether error diffusion in AC quantization is enabled.

pub fn pixel_domain_loss(&self) -> bool

Whether pixel-domain loss is enabled.

pub fn lz77(&self) -> bool

Whether LZ77 backward references are enabled.

pub fn lz77_method(&self) -> Lz77Method

Current LZ77 method.

pub fn force_strategy(&self) -> Option<u8>

Forced AC strategy, if any.

pub fn max_strategy_size(&self) -> Option<u8>

Maximum AC strategy transform size, if set.

pub fn progressive(&self) -> ProgressiveMode

Current progressive mode.

pub fn lf_frame(&self) -> bool

Whether LfFrame (separate DC frame) is enabled.

pub fn butteraugli_iters(&self) -> u32

Butteraugli quantization loop iterations.

pub fn threads(&self) -> usize

Thread count (0 = auto, 1 = sequential).

pub fn encode_request( &self, width: u32, height: u32, layout: PixelLayout, ) -> EncodeRequest<'_>

Create an encode request for an image with this config.

Use this when you need to attach metadata, limits, or cancellation.

pub fn encode( &self, pixels: &[u8], width: u32, height: u32, layout: PixelLayout, ) -> Result<Vec<u8>>

Encode pixels directly with this config. Shortcut for simple cases.

let jxl = jxl_encoder::LossyConfig::new(1.0)
    .encode(&pixels, 100, 100, jxl_encoder::PixelLayout::Rgb8)?;

pub fn encode_into( &self, pixels: &[u8], width: u32, height: u32, layout: PixelLayout, out: &mut Vec<u8>, ) -> Result<()>

Encode pixels, appending to an existing buffer.

pub fn encode_animation( &self, width: u32, height: u32, layout: PixelLayout, animation: &AnimationParams, frames: &[AnimationFrame<'_>], ) -> Result<Vec<u8>>

Encode a multi-frame animation as a lossy JXL.

Each frame must have the same dimensions and pixel layout. Returns the complete JXL codestream bytes.

impl LossyConfig

pub fn encoder( &self, width: u32, height: u32, layout: PixelLayout, ) -> Result<LossyEncoder>

Create a streaming encoder for incremental row input.

Pixels are converted to the internal format as rows are pushed via LossyEncoder::push_rows, allowing callers to free source buffers incrementally rather than materializing the entire image.

impl LossyConfig

pub fn validate(&self) -> Result<(), ValidationError>

Validate that every parameter on this config is within the encoder’s supported range.

LossyConfig setters intentionally accept and clamp out-of-range values for backwards-compat — with_distance(50.0).with_effort(15) returns a config the encoder happily runs (clamped to 25.0 / 10). Batch-job callers who want a fail-fast escape can call this method before invoking the encoder.

Returns the first violation encountered; ordering of the checks is an implementation detail.

When __expert is enabled and a profile_override has been applied via [Self::with_internal_params], the resolved profile’s fields are also checked against the same ranges [crate::effort::LossyInternalParams::validate] would enforce.

Trait Implementations

impl Clone for LossyConfig

fn clone(&self) -> LossyConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LossyConfig

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

Formats the value using the given formatter.