Trait Decoder 

pub trait Decoder: Send {
    // Required methods
    fn codec_id(&self) -> &CodecId;
    fn send_packet(&mut self, packet: &Packet) -> Result<()>;
    fn receive_frame(&mut self) -> Result<Frame>;
    fn flush(&mut self) -> Result<()>;

    // Provided methods
    fn receive_arena_frame(&mut self) -> Result<Frame> { ... }
    fn reset(&mut self) -> Result<()> { ... }
    fn set_execution_context(&mut self, _ctx: &ExecutionContext) { ... }
    fn output_pixel_format(&self) -> Option<PixelFormat> { ... }
}

A packet-to-frame decoder.

Required Methods

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.

Provided Methods

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

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

Decoders that build their output through an arena::sync::ArenaPool override this to return the pooled arena::sync::Frame directly, with no per-plane memcpy out — the caller gets true zero-copy plane access via arena::sync::FrameInner::plane.

The default implementation delegates to Self::receive_frame and copies the video planes into a freshly-leased one-shot arena::sync::ArenaPool. This makes the method an additive change for every existing Decoder impl: callers using the new API still work, but pay one memcpy per plane.

Audio / subtitle frames: the arena::sync::Frame body is video-only (planes + arena::sync::FrameHeader with width/height/pixel format). The default implementation returns Error::Unsupported for non-video frames; an audio decoder that wants to expose receive_arena_frame() must override it with its own arena-backed audio-frame type once the framework gains one. Until then, audio decoders should keep using Self::receive_frame.

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.

Unlike flush (which signals end-of-stream and drains buffered frames), reset is expected to:

• drop every buffered input packet and pending output frame;
• zero any per-stream filter / predictor / overlap memory so the next send_packet decodes as if it were the first;
• leave the codec id and stream parameters untouched.

The default is a conservative “drain-then-forget”: call flush and ignore any remaining frames. Stateful codecs (LPC predictors, backward-adaptive gain, IMDCT overlap, reference pictures, …) should override this to wipe their internal state explicitly — otherwise the first ~N output samples after a seek will be glitchy until the state re-adapts.

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

Advisory: announce the runtime environment (today: a thread budget for codec-internal parallelism). Called at most once, before the first send_packet. Default no-op; codecs that want to run slice-/GOP-/tile-parallel override this to capture the budget. Ignoring the hint is always safe — callers must still work with a decoder that runs serial.

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

Pixel layout of the video frames this decoder emits, stated before the first frame — from the codec’s configuration record in extradata, from a negotiated hardware session, or from the decoder’s fixed output policy. Some is a fact about the frames to come and takes precedence over the container’s CodecParameters::pixel_format (a stream label is a claim the container made; the decoder is the one producing the planes). None — the default — means “not known yet: trust the stream parameters”, and a decoder whose output depends on the first packet (an untagged file that decides its layout per picture) answers None until it has seen one and the real layout afterwards.

Pipelines and gateways read it to label frames from codec-only registrations and to pick the conversion into an encoder’s accepted_pixel_formats; a frame whose plane shape disagrees with the stated layout is the decoder’s defect, not the consumer’s. The answer may change between frames only for a decoder that documents it.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors