Struct EncoderConfig 

pub struct EncoderConfig { /* private fields */ }

JPEG encoder configuration. Dimension-independent, reusable across images.

Implementations

impl EncoderConfig

pub fn new(quality: impl Into<Quality>, subsampling: ChromaSubsampling) -> Self

Create a new encoder configuration with required quality and chroma subsampling.

Arguments

• quality: Quality level (0-100 for jpegli scale, or use Quality::* variants)
• subsampling: Chroma subsampling mode
  • ChromaSubsampling::Quarter (4:2:0) - good compression, smaller files
  • ChromaSubsampling::None (4:4:4) - best quality, larger files

Example

use jpegli::encoder::{EncoderConfig, ChromaSubsampling};

let config = EncoderConfig::new(85.0, ChromaSubsampling::Quarter)
    .progressive(true);

pub fn quality(self, q: impl Into<Quality>) -> Self

Override the quality level.

Accepts any type that converts to Quality:

• f32 or u8 for ApproxJpegli scale
• Quality::ApproxMozjpeg(u8) for mozjpeg-like quality
• Quality::ApproxSsim2(f32) for SSIMULACRA2 target
• Quality::ApproxButteraugli(f32) for Butteraugli target

pub fn quant_tables(self, config: QuantTableConfig) -> Self

Set custom quantization tables.

pub fn zero_bias(self, config: ZeroBiasConfig) -> Self

Set zero-bias configuration.

Zero-bias controls how DCT coefficients are rounded toward zero during quantization. The default Perceptual mode uses jpegli’s quality-adaptive tables which are optimized for visual quality.

Options

• ZeroBiasConfig::Perceptual (default) - quality-adaptive tables
• ZeroBiasConfig::Disabled - no zero-bias (standard JPEG behavior)
• ZeroBiasConfig::Custom { .. } - provide custom per-component tables

Example

use jpegli::encoder::{EncoderConfig, ZeroBiasConfig};

// Disable zero-bias for standard JPEG behavior
let config = EncoderConfig::new(85, ChromaSubsampling::None)
    .zero_bias(ZeroBiasConfig::Disabled);

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

Enable or disable progressive encoding.

Progressive encoding produces multiple scans for incremental display. Automatically enables optimized Huffman tables (required for progressive).

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

Enable or disable Huffman table optimization.

When enabled (default), computes optimal Huffman tables from image data. When disabled, uses standard JPEG Huffman tables (faster but larger files).

Note: Progressive mode requires optimized Huffman tables.

pub fn restart_interval(self, interval: u16) -> Self

Set the restart interval (MCUs between restart markers).

Restart markers allow partial decoding and error recovery. Set to 0 to disable restart markers (default).

pub fn icc_profile(self, profile: impl Into<Vec<u8>>) -> Self

Attach an ICC color profile to the output JPEG.

The profile will be written as APP2 marker segments with the standard “ICC_PROFILE” signature. Large profiles are automatically chunked (max 65519 bytes per segment) as required by the ICC profile embedding spec.

Common profiles:

• sRGB IEC61966-2.1 (~3KB)
• Display P3 (~0.5KB)
• Adobe RGB 1998 (~0.5KB)

Example

let srgb_profile = std::fs::read("sRGB.icc")?;
let config = EncoderConfig::new()
    .quality(85)
    .icc_profile(srgb_profile);

pub fn exif(self, exif: impl Into<Exif>) -> Self

Attach EXIF metadata to the output JPEG.

Use Exif::raw for raw EXIF bytes, or Exif::build to construct from common fields.

The two modes are mutually exclusive at compile time - you cannot mix raw bytes with field-based building.

Examples

Build from fields (orientation and copyright):

use jpegli::encoder::{EncoderConfig, ChromaSubsampling, Exif, Orientation};

let config = EncoderConfig::new(85, ChromaSubsampling::Quarter)
    .exif(Exif::build()
        .orientation(Orientation::Rotate90)
        .copyright("© 2024 Example Corp"));

Use raw EXIF bytes:

use jpegli::encoder::{EncoderConfig, ChromaSubsampling, Exif};

let config = EncoderConfig::new(85, ChromaSubsampling::Quarter)
    .exif(Exif::raw(my_exif_bytes));

Notes

• EXIF is placed immediately after SOI, before any other markers
• Raw bytes should be TIFF data without the “Exif\0\0” prefix (added automatically)
• Maximum size: 65527 bytes (larger data will be truncated)

pub fn xmp(self, data: impl Into<Vec<u8>>) -> Self

Attach XMP metadata to the output JPEG.

The data will be written as an APP1 marker segment with the standard Adobe XMP namespace signature. The provided bytes should be the raw XMP XML data without the APP1 marker or namespace prefix.

XMP is placed after EXIF (if present) but before ICC profile.

Maximum Size

Standard XMP is limited to 65502 bytes (65535 - 2 length - 29 namespace - 2 padding). For larger XMP data, use Extended XMP (not yet supported).

pub fn color_mode(self, mode: ColorMode) -> Self

Set the output color mode.

pub fn downsampling_method(self, method: DownsamplingMethod) -> Self

Set the chroma downsampling method.

Only affects RGB/RGBX input with chroma subsampling enabled. Ignored for grayscale, YCbCr input, or 4:4:4 subsampling.

pub fn ycbcr(self, subsampling: ChromaSubsampling) -> Self

Set YCbCr color mode with specified chroma subsampling.

Common values:

• ChromaSubsampling::None (4:4:4) - default, best quality
• ChromaSubsampling::Quarter (4:2:0) - good compression, smaller files
• ChromaSubsampling::HalfHorizontal (4:2:2) - horizontal subsampling only

pub fn xyb(self) -> Self

Set XYB color mode with B-quarter subsampling (default, perceptually optimized).

XYB is a perceptual color space that can achieve better quality at the same file size for some images. Requires linear RGB input (f32 or u16).

pub fn xyb_full(self) -> Self

Set XYB color mode with full resolution (no subsampling).

pub fn grayscale(self) -> Self

Set grayscale output mode.

Only the luminance channel is encoded. Works with any input format.

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

Enable or disable SharpYUV (GammaAwareIterative) downsampling.

SharpYUV produces better color preservation on edges and thin lines, at the cost of ~3x slower encoding.

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

Validate the configuration, returning an error for invalid combinations.

Invalid combinations:

• Progressive mode with disabled Huffman optimization

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

Create an encoder from raw bytes with explicit pixel layout.

Use this when working with raw byte buffers and you know the pixel layout.

Arguments

• width: Image width in pixels
• height: Image height in pixels
• layout: Pixel data layout (channel order, depth, color space)

Example

let config = EncoderConfig::new().quality(85);
let mut enc = config.encode_from_bytes(1920, 1080, PixelLayout::Rgb8Srgb)?;
enc.push_packed(&rgb_bytes, Unstoppable)?;
let jpeg = enc.finish()?;

pub fn encode_from_rgb<P: Pixel>( &self, width: u32, height: u32, ) -> Result<RgbEncoder<P>>

Create an encoder from rgb crate pixel types.

Layout is inferred from the type parameter. For RGBA/BGRA types, the 4th channel is ignored.

Type Parameter

• P: Pixel type from the rgb crate (e.g., RGB<u8>, RGBA<f32>)

Example

use rgb::RGB;

let config = EncoderConfig::new().quality(85);
let mut enc = config.encode_from_rgb::<RGB<u8>>(1920, 1080)?;
enc.push_packed(&pixels, Unstoppable)?;
let jpeg = enc.finish()?;

pub fn encode_from_ycbcr_planar( &self, width: u32, height: u32, ) -> Result<YCbCrPlanarEncoder>

Create an encoder from planar YCbCr data.

Use this when you have pre-converted YCbCr from video decoders, etc. Skips RGB->YCbCr conversion entirely.

Only valid with ColorMode::YCbCr. XYB mode requires RGB input.

Example

let config = EncoderConfig::new()
    .quality(85)
    .ycbcr(ChromaSubsampling::Quarter);

let mut enc = config.encode_from_ycbcr_planar(1920, 1080)?;
enc.push(&planes, height, Unstoppable)?;
let jpeg = enc.finish()?;

pub fn estimate_memory(&self, width: u32, height: u32) -> usize

Estimate peak memory usage for encoding an image of the given dimensions.

Returns estimated bytes based on color mode, subsampling, and dimensions. Delegates to the streaming encoder’s estimate which accounts for all internal buffers.

pub fn estimate_memory_ceiling(&self, width: u32, height: u32) -> usize

Returns an absolute ceiling on memory usage.

Unlike estimate_memory, this returns a guaranteed upper bound that actual peak memory will never exceed. Use this for resource reservation when you need certainty rather than a close estimate.

The ceiling accounts for:

• Worst-case token counts per block (high-frequency content)
• Maximum output buffer size (incompressible images)
• Vec capacity overhead (allocator rounding)
• All intermediate buffers at their maximum sizes

Example

use jpegli::encoder::EncoderConfig;

let config = EncoderConfig::new().quality(85);
let ceiling = config.estimate_memory_ceiling(1920, 1080);

// Reserve this much memory - actual usage guaranteed to be less
let buffer = Vec::with_capacity(ceiling);

pub fn get_quality(&self) -> Quality

Get the configured quality.

pub fn get_color_mode(&self) -> ColorMode

Get the configured color mode.

pub fn is_progressive(&self) -> bool

Check if progressive mode is enabled.

pub fn is_optimize_huffman(&self) -> bool

Check if Huffman optimization is enabled.

pub fn get_icc_profile(&self) -> Option<&[u8]>

Get the ICC profile, if set.

pub fn get_exif(&self) -> Option<&Exif>

Get the EXIF data, if set.

pub fn get_xmp(&self) -> Option<&[u8]>

Get the XMP data, if set.

Trait Implementations

impl Clone for EncoderConfig

fn clone(&self) -> EncoderConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for EncoderConfig

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

Formats the value using the given formatter.