Struct EncodeOptions 

#[non_exhaustive]
pub struct EncodeOptions {
    pub base_q_idx: u8,
    pub alpha_q_idx: u8,
    pub premultiplied_alpha: bool,
    pub chroma: StillChroma,
    pub embed_exif: bool,
    pub embed_xmp: bool,
    pub embed_icc: bool,
    pub speed: EncodeSpeed,
    pub threads: usize,
}

Tuning for the encoders (crate::encode, crate::encode_rgb8, crate::encode_rgba8, crate::still::encode_still …). The default is a lossless colour encode (base_q_idx = 0), lossless alpha, straight (non-premultiplied) alpha signalling, 4:2:0 for the RGB one-call paths, every metadata block embedded.

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.

base_q_idx: u8

AV1 base_q_idx for the colour planes. 0 = lossless (default); higher = lossier / smaller (255 = coarsest). See Self::with_quality for the 0–100 scale.

alpha_q_idx: u8

AV1 base_q_idx for the alpha auxiliary. Defaults to 0 (lossless) — alpha artefacts are far more visible than colour ones, and flat alpha planes are cheap.

premultiplied_alpha: bool

Emit the prem iref declaring the colour planes premultiplied by alpha (HEIF §6.10.1.1). Signalling only — the samples are stored as given.

chroma: StillChroma

Chroma layout of crate::encode_rgb8 / crate::encode_rgba8 (default 4:2:0; odd extents fall back to 4:4:4, see those functions). crate::encode keeps the image’s own layout.

embed_exif: bool

Embed metadata.exif as an Exif item (default true).

embed_xmp: bool

Embed metadata.xmp as a mime item (default true).

embed_icc: bool

Embed metadata.icc as an ICC colr next to the nclx one (default true).

speed: EncodeSpeed

Search effort of the AV1 encode (default EncodeSpeed::Fast).

threads: usize

Worker threads for the AV1 tile search of every coded item (default 1). The tile layout is derived from the picture size alone, so the coded bytes never depend on this value.

Implementations

impl EncodeOptions

pub fn new(base_q_idx: u8, alpha_q_idx: u8, premultiplied_alpha: bool) -> Self

The historical three-field constructor (base_q_idx, alpha_q_idx, premultiplied_alpha); the other fields take their defaults.

Examples found in repository

examples/decode_threads.rs (line 150)

fn main() {
    let mut args = std::env::args().skip(1);
    let threads: usize = args.next().and_then(|s| s.parse().ok()).unwrap_or(8);
    let width: u32 = args.next().and_then(|s| s.parse().ok()).unwrap_or(4000);
    let height: u32 = args.next().and_then(|s| s.parse().ok()).unwrap_or(3000);

    let input = YuvFrame {
        width,
        height,
        bit_depth: 8,
        format: ChromaFormat::Yuv420,
        y: plane(width, height, 1),
        u: plane(width / 2, height / 2, 2),
        v: plane(width / 2, height / 2, 3),
    };
    let t = Instant::now();
    let coded = encode_still_yuv(&input, &StillOptions::new(120).threads(threads)).expect("encode");
    let av1c = Av1CodecConfig::from_sequence_header(&coded.seq).to_bytes();
    let file = oxideav_avif::encode_still_av1(
        width,
        height,
        coded.temporal_unit_bytes,
        av1c,
        vec![8, 8, 8],
    )
    .expect("mux");
    eprintln!(
        "{width}x{height} 4:2:0 still: {} bytes, encoded in {:.2} s on {threads} threads",
        file.len(),
        t.elapsed().as_secs_f64()
    );

    let (serial, t1) = decode(&file, 1);
    let (parallel, tn) = decode(&file, threads);
    assert_eq!(serial, parallel, "byte-identical at any budget");
    eprintln!(
        "decode: serial {t1:.3} s, {threads} workers {tn:.3} s ({:.2}x), identical bytes",
        t1 / tn
    );

    // The registry encoder on the same picture (quality 50): serial vs
    // the budget — identical bytes, the wall clock is the point.
    let registry_frame = Frame::Video(oxideav_core::frame::VideoFrame {
        pts: Some(0),
        planes: [
            (&input.y, width),
            (&input.u, width / 2),
            (&input.v, width / 2),
        ]
        .iter()
        .map(|(p, w)| oxideav_core::frame::VideoPlane {
            stride: *w as usize,
            data: p.iter().map(|&v| v as u8).collect(),
        })
        .collect(),
    });
    let mut p = CodecParameters::video(CodecId::new(oxideav_avif::CODEC_ID_STR));
    p.width = Some(width);
    p.height = Some(height);
    p.pixel_format = Some(oxideav_core::PixelFormat::Yuv420P);
    p.options = oxideav_core::CodecOptions::new().set("quality", "50");
    let encode_registry = |budget: usize| -> (Vec<u8>, f64) {
        let mut enc = oxideav_avif::make_encoder(&p).expect("encoder");
        if budget > 1 {
            enc.set_execution_context(&ExecutionContext::with_threads(budget));
        }
        let t = Instant::now();
        enc.send_frame(&registry_frame).expect("send");
        let pkt = enc.receive_packet().expect("packet");
        (pkt.data, t.elapsed().as_secs_f64())
    };
    let (e1, te1) = encode_registry(1);
    let (en, ten) = encode_registry(threads);
    assert_eq!(e1, en, "registry encoder: byte-identical at any budget");
    eprintln!(
        "registry encode (quality 50): {} bytes, serial {te1:.2} s, {threads} workers {ten:.2} s ({:.2}x), identical bytes",
        e1.len(),
        te1 / ten
    );

    // The same picture as a 4 × 3 grid of single-tile items.
    let t = Instant::now();
    let still = StillImage::yuv(
        width,
        height,
        8,
        StillChroma::Yuv420,
        input.y.clone(),
        input.u.clone(),
        input.v.clone(),
    )
    .expect("still");
    let grid = encode_still_grid(&still, &EncodeOptions::new(120, 0, false), 4, 3).expect("grid");
    eprintln!(
        "{width}x{height} as a 4x3 grid: {} bytes, encoded in {:.2} s (serial encoder)",
        grid.len(),
        t.elapsed().as_secs_f64()
    );
    let (serial, t1) = decode(&grid, 1);
    let (parallel, tn) = decode(&grid, threads);
    assert_eq!(serial, parallel, "grid: byte-identical at any budget");
    eprintln!(
        "grid decode: serial {t1:.3} s, {threads} workers {tn:.3} s ({:.2}x), identical bytes",
        t1 / tn
    );
}

pub fn with_base_q_idx(self, base_q_idx: u8) -> Self

Setter: replace base_q_idx.

pub fn with_alpha_q_idx(self, alpha_q_idx: u8) -> Self

Setter: replace alpha_q_idx.

pub fn with_premultiplied_alpha(self, premultiplied_alpha: bool) -> Self

Setter: replace premultiplied_alpha.

pub fn with_chroma(self, chroma: StillChroma) -> Self

Setter: replace chroma.

pub fn with_embed_exif(self, embed_exif: bool) -> Self

Setter: replace embed_exif.

pub fn with_embed_xmp(self, embed_xmp: bool) -> Self

Setter: replace embed_xmp.

pub fn with_embed_icc(self, embed_icc: bool) -> Self

Setter: replace embed_icc.

pub fn with_speed(self, speed: EncodeSpeed) -> Self

Setter: replace speed.

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

Setter: replace threads (clamped to at least 1).

pub fn with_quality(self, quality: u8) -> Self

Colour quality on a 0–100 scale (100 = lossless): sets base_q_idx = ((100 − quality) × 255 + 50) / 100, so 100 → 0, 90 → 26, 75 → 64, 50 → 128, 0 → 255. Values above 100 clamp to 100. Alpha stays at its own alpha_q_idx.

Trait Implementations

impl Clone for EncodeOptions

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for EncodeOptions

impl Debug for EncodeOptions

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

Formats the value using the given formatter.

impl Default for EncodeOptions

fn default() -> Self

Returns the “default value” for a type.

impl Eq for EncodeOptions

impl PartialEq for EncodeOptions

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for EncodeOptions