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) { ... }
}

A packet-to-frame decoder.

Required Methods

fn codec_id(&self) -> &CodecId

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.

Implementors