Skip to main content

AnimationFrameDecoder

zencodec::decode

Trait AnimationFrameDecoder 

Source 
pub trait AnimationFrameDecoder: Sized {
    type Error: Error + Send + Sync + 'static;

    // Required methods
    fn wrap_sink_error(err: SinkError) -> Self::Error;
    fn info(&self) -> &ImageInfo;
    fn render_next_frame(
        &mut self,
        stop: Option<&dyn Stop>,
    ) -> Result<Option<AnimationFrame<'_>>, Self::Error>;
    fn render_next_frame_to_sink(
        &mut self,
        stop: Option<&dyn Stop>,
        sink: &mut dyn DecodeRowSink,
    ) -> Result<Option<OutputInfo>, Self::Error>;

    // Provided methods
    fn frame_count(&self) -> Option<u32> { ... }
    fn loop_count(&self) -> Option<u32> { ... }
    fn render_next_frame_owned(
        &mut self,
        stop: Option<&dyn Stop>,
    ) -> Result<Option<OwnedAnimationFrame>, Self::Error> { ... }
}
Expand description

Full-frame composited animation decode.

The decoder composites internally (handling disposal, blending, sub-canvas positioning, reference slots, etc.) and yields full-canvas frames ready for display.

Created by DecodeJob::animation_frame_decoder() with input data and format preferences already bound.

§Frame index

Frame indices are 0-based and count only displayed frames. Internal compositing helper frames (e.g. JXL zero-duration frames) are consumed internally and never yielded.

§Borrowed vs owned

render_next_frame() returns a AnimationFrame that borrows the decoder’s internal canvas — zero-copy but invalidated by the next call. render_next_frame_owned() copies to an OwnedAnimationFrame for independent ownership.

§Cooperative cancellation

Each render method takes an Option<&dyn Stop> token for cooperative cancellation. The codec checks this token periodically during decode and returns early with StopReason if cancellation is requested.

Because AnimationFrameDec: 'static, the decoder cannot borrow the job’s stop token. Instead, the caller passes a stop token per call. Codecs that also stored an owned stop at construction time (e.g. via Stopper) can combine the two with OrStop. Pass None when cancellation is not needed.

Required Associated Types§

Source

type Error: Error + Send + Sync + 'static

The codec-specific error type.

Required Methods§

Source

fn wrap_sink_error(err: SinkError) -> Self::Error

Wrap a SinkError into this decoder’s error type.

Used by default implementations of sink-based methods. Mirrors the reject pattern on encoders.

A typical implementation:

ⓘ
fn wrap_sink_error(err: SinkError) -> Self::Error {
    MyError::Sink(err) // or MyError::External(err.to_string())
}
Source

fn info(&self) -> &ImageInfo

Image metadata, available after construction.

Source

fn render_next_frame( &mut self, stop: Option<&dyn Stop>, ) -> Result<Option<AnimationFrame<'_>>, Self::Error>

Render the next composited full-canvas frame.

Returns Ok(Some(frame)) with the composited frame borrowing the decoder’s internal canvas, or Ok(None) when all frames are consumed.

The returned AnimationFrame borrows the decoder’s canvas buffer. Calling this method again invalidates the previous frame.

Pass None if cancellation is not needed.

Source

fn render_next_frame_to_sink( &mut self, stop: Option<&dyn Stop>, sink: &mut dyn DecodeRowSink, ) -> Result<Option<OutputInfo>, Self::Error>

Render the next frame directly into a caller-owned sink (push model).

Returns Ok(Some(info)) with frame metadata, or Ok(None) when all frames are consumed.

Codecs with native row streaming should write directly into the sink. Codecs that render to an internal canvas should call zencodec::helpers::copy_frame_to_sink() as a fallback.

Pass None if cancellation is not needed.

Provided Methods§

Source

fn frame_count(&self) -> Option<u32>

Number of frames, if known without decoding.

Source

fn loop_count(&self) -> Option<u32>

Animation loop count from the container.

  • Some(0) = loop forever
  • Some(n) = loop n times
  • None = unknown or not specified
Source

fn render_next_frame_owned( &mut self, stop: Option<&dyn Stop>, ) -> Result<Option<OwnedAnimationFrame>, Self::Error>

Render the next frame as an owned copy.

Default implementation calls render_next_frame() and copies the pixel data. Codecs that produce owned data natively may override for efficiency.

Pass None if cancellation is not needed.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§