Struct AvifDecoder 

pub struct AvifDecoder { /* private fields */ }

Decoder trait impl registered under codec id avif.

Implementations

impl AvifDecoder

pub fn new(codec_id: CodecId) -> Self

pub fn effective_options(&self) -> DecodeOptions

The options a decode runs with: Self::options with the execution context’s worker budget filled in when no explicit threads was set (the threads codec option or DecodeOptions::with_threads).

pub fn threads(&self) -> usize

The worker budget the next decode runs the AV1 decoder with.

pub fn with_params(params: &CodecParameters) -> Result<Self>

Build a decoder from a parameter set, its options parsed strictly against AvifDecoderOptions’s schema: gain_map (base, the default, or apply) selects set_tone_mapped; reference_white (cd/m², default 203) sets set_reference_white; threads fixes the AV1 worker budget (0, the default, follows the execution context); max_width / max_height / max_pixels / max_bytes (0 = unlimited), strict and layer (-1 = the file’s lsel) set the matching DecodeOptions fields. An unknown key or a malformed value is refused.

pub fn set_tone_mapped(&mut self, tone_mapped: bool)

Gain-map application (av1-avif §4.2.2, HEIF Amd 1:2025 §6.6.2.4, ISO 21496-1 §6): with true the decoder yields the tmap alternative of the primary — the tmap item that is the primary itself, or the one in an altr group with it (MIAF Amd 1 §7.3.11.5) whose base input it is — reconstructed with the gain map fully applied (the weight of 1.0 / −1.0 of §6.6.2.4.1) and re-encoded in the tmap item’s own colr at its pixi depth (the base’s alpha carried over). Default false: the base image, what readers without tone-map support show. A tmap that is the input of another derived item is always applied (§6.6.2.4.1). Files without a tmap decode the same either way.

pub fn with_tone_mapped(self, tone_mapped: bool) -> Self

Builder form of set_tone_mapped.

pub fn tone_mapped(&self) -> bool

Whether gain maps are applied (see set_tone_mapped).

pub fn options(&self) -> &DecodeOptions

The full DecodeOptions this decoder runs the contract functions with (crate::decode_with / crate::decode_all).

pub fn set_options(&mut self, options: DecodeOptions)

Replace the DecodeOptions (limits, strictness, gain-map application, reference white, layer selection).

pub fn with_options(self, options: DecodeOptions) -> Self

Builder form of set_options.

pub fn set_reference_white(&mut self, nits: f64) -> Result<()>

The HDR reference white, in cd/m², a PQ-coded reconstruction is anchored at (ISO 21496-1 fixes none; 203 is the value its headroom definition uses as the example and the default). Finite and positive, else refused.

pub fn color_signal(&self) -> Option<ColorSignal>

The colour signal (oxideav-core ColorSignal: range + H.273 primaries / transfer / matrix) of the last decoded file — the primary item’s effective colr under MIAF §7.3.6.4 (its nclx, else the MIAF default: full range, BT.709 / sRGB / BT.601) for a still, the av01 sample entry’s colr for a sequence. Every frame this decoder emits carries the same value as its colour-signal side channel. None before the first decode.

pub fn output_format(&self) -> Option<PixelFormat>

The framework pixel-format label of the frames of the last decoded file: planar RGB (Gbrp* / Gbrap*, planes G B R [A]) for an identity-matrix 4:4:4 picture, YuvJ* for a full-range 8-bit Y′CbCr still, the storage layout otherwise (see crate::signal::labelled_pixel_format). None before the first decode.

pub fn decode_file(&mut self, file: &[u8]) -> Result<AvifInfo>

Parse an AVIF file and decode the primary item’s output image (HEIF §6.3): the reconstructed image of a coded av01 item or of a derived item (grid tile stitch, iovl overlay composition, iden identity — recursively over their inputs), with the alpha auxiliary composited and the item’s transformative properties applied in ipma order. Returns the resolved AvifInfo on success.

pub fn info(&self) -> Option<&AvifInfo>

pub fn decode_avis_file(&mut self, file: &[u8]) -> Result<usize>

Decode every frame of an AVIF Image Sequence (AVIS) — av1-avif §6.3 + ISO/IEC 14496-12 §8 (movie / track / sample-table boxes).

Walks the track’s stbl to recover the sample byte ranges and (duration, is_sync) per sample, lifts the AV1CodecConfigurationRecord from stsd → av01 → av1C, and fans every sample through a single shared AV1 registry decoder instance so inter-prediction across samples is preserved (when the underlying av1 crate supports it).

Each successfully decoded sample is queued on pending with a pts derived from the cumulative stts duration so the Decoder::receive_frame consumer can pull frames in presentation order. Samples that the av1 decoder rejects are surfaced as the first error returned by this function — the caller can then flush and re-try, or treat the sequence as partially-decodable. Returns the count of frames queued.

AVIS files that lack a moov (and thus look like still images with no sequence track) bubble up Error::InvalidData from [parse_avis]; callers detecting this should fall back to the still-image [decode_file] path.

Trait Implementations

impl Decoder for AvifDecoder

fn set_execution_context(&mut self, ctx: &ExecutionContext)

The worker budget for the AV1 decode of every item / sample (see DecodeOptions::threads); an explicit threads option wins over it. Byte-identical output at any budget.

fn output_pixel_format(&self) -> Option<PixelFormat>

The label of the frames of the last decoded file (AvifDecoder::output_format); None before the first decode.

fn codec_id(&self) -> &CodecId

Identifier of the codec this decoder handles.

fn send_packet(&mut self, packet: &Packet) -> Result<()>

Feed one compressed packet. May or may not produce a frame immediately — call receive_frame in a loop afterwards.

fn receive_frame(&mut self) -> Result<Frame>

Pull the next decoded frame, if any. Returns Error::NeedMore when the decoder needs another packet.

fn flush(&mut self) -> Result<()>

Signal end-of-stream. After this, receive_frame will drain buffered frames and eventually return Error::Eof.

fn reset(&mut self) -> Result<()>

Discard all carry-over state so the decoder can resume from a new bitstream position without producing stale output. Called by the player after a container seek.

fn receive_arena_frame(&mut self) -> Result<Arc<FrameInner>, Error>

Pull the next decoded frame as an arena-backed arena::sync::Frame.