Struct Frame 

pub struct Frame { /* private fields */ }

CPU-side decoded video frame produced by crate::VideoDecoder.

Implementations

impl Frame

pub fn empty() -> Result<Self>

Construct an empty frame, suitable as the destination passed to crate::VideoDecoder::receive_frame.

Returns Err(Error::Ffmpeg(Other { errno: ENOMEM })) when the underlying av_frame_alloc() returns NULL — ffmpeg_next does not surface that failure, so we check it here rather than letting a null pointer flow into the safe accessors and become UB on first read.

pub fn width(&self) -> u32

Width in pixels.

pub fn height(&self) -> u32

Height in pixels.

pub fn pix_fmt(&self) -> PixelFormat

Pixel format, returned as a PixelFormat (the unified mediadecode enum). The mapping is via boundary::from_av_pixel_format — sound regardless of the linked FFmpeg version, no AVPixelFormat enum is constructed from a runtime integer.

pub fn pts(&self) -> Option<i64>

Presentation timestamp in stream time base, or None for AV_NOPTS_VALUE.

pub fn planes(&self) -> usize

Number of populated planes (1 for packed formats, 2 for NV12/P010, 3 for planar YUV, etc.). Computed by scanning linesize for the first zero entry — no enum reads.

pub fn stride(&self, plane: usize) -> usize

Bytes per row for plane. Reads AVFrame.linesize[plane] directly.

Panics

Panics if plane >= planes() or the linesize is non-positive (FFmpeg allows negative linesize for vertically-flipped formats; this crate does not surface those). Callers who need to handle either case without panicking should use Self::try_stride, or the non-panicking pixel accessors Self::row / Self::rows / Self::row_bytes / Self::as_ptr.

pub fn try_stride(&self, plane: usize) -> Option<usize>

Fallible counterpart to Self::stride. Returns None when plane is out of bounds or the linesize is non-positive (the two conditions Self::stride panics on). Use this when the frame’s plane count or layout is caller-controlled / data-driven and either case should be handled rather than aborting.

pub fn row_bytes(&self, plane: usize) -> Option<usize>

Visible byte width of plane — the number of initialized bytes at the start of every row in that plane.

Distinct from Self::stride, which returns the FFmpeg linesize. linesize is >= row_bytes and may include trailing alignment padding bytes that FFmpeg’s hardware transfer paths do not initialize. row_bytes is what slice::from_raw_parts can safely see.

Returns None when the format is not in the supported HW-output set (see crate pix_fmt) or the plane is out of range.

pub fn row(&self, plane: usize, y: usize) -> Option<&[u8]>

Pixel data for one row of plane, tightly clipped to the visible byte width (Self::row_bytes).

Excludes the trailing alignment padding that Self::stride includes — those bytes are not guaranteed to be initialized by FFmpeg’s hardware transfer paths and must not be exposed through a safe &[u8].

Returns None for any of the following — never panics:

• The frame’s pixel format is not one of the supported hardware- output formats listed in [crate::pix_fmt].
• The plane index is out of range.
• y is past the plane’s row count.
• AVFrame.linesize[plane] is <= 0 or AVFrame.height is <= 0.
• The plane’s data pointer is null.
• The plane size would overflow isize::MAX.

pub fn rows(&self, plane: usize) -> Option<impl Iterator<Item = &[u8]> + '_>

Iterator over every row of plane. Each yielded slice has length Self::row_bytes(plane) — never includes the trailing alignment padding that lives within Self::stride.

Returns None under the same conditions as Self::row.

pub fn as_ptr(&self, plane: usize) -> Option<*const u8>

Raw base pointer to plane’s allocation, or None if the plane fails the same layout validation Self::row applies.

Returns None whenever any of the following is true:

• The plane index is out of range (plane >= planes()).
• The frame’s pixel format is not in the supported HW-output set.
• linesize[plane] <= 0. In particular, FFmpeg permits negative linesizes for vertically-flipped frames with data[n] pointing at the end of the image. Returning that pointer with the advertised “valid for stride * plane_h bytes forward” contract would let a downstream converter walk past the buffer. This accessor refuses the layout instead of handing back a pointer the caller cannot safely interpret as forward-addressable.
• height <= 0, the data pointer is null, row_bytes > stride, or the total plane size would overflow isize::MAX.

On Some(ptr) the pointer is valid for stride(plane) * plane_height forward-addressable bytes, and only the first Self::row_bytes(plane) bytes of each row are guaranteed to be initialized. The trailing per-row alignment padding is uninitialized; callers performing wide SIMD loads that read past row_bytes must mask the result and never surface those bytes through a safe &[u8].

This accessor exists for downstream pixel-format converters (colconv) that work in (ptr, stride, width, height) quadruples; safe code should prefer Self::row / Self::rows.

Trait Implementations

impl Debug for Frame

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

frame::Video (from ffmpeg_next) doesn’t itself implement Debug, so route through the public accessors. Shows the dimensions, pixel format, plane count, and PTS — enough to distinguish frames at debug-print sites without surfacing raw FFI internals.