Struct FfmpegBuffer 

pub struct FfmpegBuffer { /* private fields */ }

Owned, refcounted handle to a contiguous byte range inside an AVBufferRef.

Holds one reference to the underlying AVBufferRef. The view (offset + length) carves out a sub-region of the buffer’s data — useful when an AVFrame packs multiple planes into a single allocation (e.g. NV12 with data[1] == data[0] + Y_size). Each plane gets its own FfmpegBuffer view at a different offset, every view bumps the refcount, and dropping one doesn’t free the underlying buffer until the last view goes away.

Clone shares the same view (offset + length unchanged). Drop releases one reference via av_buffer_unref.

Implementations

impl FfmpegBuffer

pub unsafe fn from_ref(buf: *mut AVBufferRef) -> Option<Self>

Constructs an FfmpegBuffer by incrementing the refcount of an existing AVBufferRef. The view covers the buffer’s full size (offset 0). The caller’s *mut AVBufferRef is unchanged — it still owns its own reference and must be released independently.

Returns None if buf is null or av_buffer_ref fails (out of memory).

Safety

buf must either be null or point to a live AVBufferRef for the duration of this call.

pub unsafe fn from_ref_view( buf: *mut AVBufferRef, offset: usize, len: usize, ) -> Option<Self>

Constructs an FfmpegBuffer view over a sub-region of an existing AVBufferRef. The refcount is incremented; the view runs from offset for len bytes inside (*buf).data.

Returns None if buf is null, av_buffer_ref fails, or offset + len > (*buf).size.

Safety

buf must either be null or point to a live AVBufferRef for the duration of this call.

pub fn empty() -> Self

Allocates a 1-byte refcounted AVBufferRef and exposes a zero-length view over it. Useful as a placeholder when constructing an “empty” mediadecode::VideoFrame / AudioFrame to pass to a decoder’s receive_frame — the decoder overwrites the planes on success, but the slot needs a non-null buffer to satisfy the array shape.

Panics

Panics if FFmpeg fails to allocate (out-of-memory). Allocations of one byte never realistically fail; this matches the behaviour of Clone on a populated FfmpegBuffer. Callers who need to recover from OOM should use Self::try_empty.

pub fn try_empty() -> Option<Self>

Fallible counterpart to Self::empty. Returns None if the 1-byte av_buffer_alloc fails (out-of-memory). Use this when you’d rather propagate an error than panic.

pub fn from_packet(packet: &Packet) -> Option<Self>

Borrows the refcounted payload of an ffmpeg::Packet as an FfmpegBuffer view. The packet’s AVBufferRef is shared via refcount bump — no copy. The view spans exactly (*packet.as_ptr()).data .. data + size (the payload) — not the entire underlying allocation: AVPacket.buf can be larger than the payload (encoder padding, oversized buffers, sub-range references after av_packet_split_side_data), so exposing the whole AVBufferRef would corrupt downstream consumers that trust the buffer to be just the compressed bytes.

Returns None when the packet has no refcounted buffer (buf == NULL) — callers needing universal coverage of stack- or arena-allocated AVPackets can fall back to Self::copy_from_slice over packet.data().

pub fn from_frame_plane(frame: &Frame, plane_idx: usize) -> Option<Self>

Borrows one of an ffmpeg::Frame’s plane buffers (AVFrame.buf[plane_idx]) as an FfmpegBuffer view. The view covers the underlying AVBufferRef’s full size; for per-plane subviews into a multi-plane shared allocation see crate::convert::video_frame_from.

Returns None when plane_idx >= 8 or the plane has no buffer attached.

pub fn copy_from_slice(bytes: &[u8]) -> Option<Self>

Allocates a fresh refcounted AVBufferRef and copies bytes into it. Returns None if the FFmpeg allocation fails.

Useful for adapting non-refcounted FFmpeg payloads (e.g. subtitle AVSubtitleRect.text / .ass / .data[0]) into the refcounted FfmpegBuffer shape the rest of the crate carries.

pub unsafe fn take(buf: *mut AVBufferRef) -> Option<Self>

Takes ownership of an existing AVBufferRef without bumping the refcount. The view covers the buffer’s full size. Use this when the caller’s reference will be dropped (e.g. transferring out of an AVPacket/AVFrame).

Returns None if buf is null.

Safety

buf must be either null or a live AVBufferRef whose reference the caller is willing to give up. After a successful call, the caller MUST NOT call av_buffer_unref on the same pointer.

pub fn len(&self) -> usize

Number of bytes visible through this view.

pub fn is_empty(&self) -> bool

True when the view is zero bytes long.

pub fn as_ptr(&self) -> *const u8

Raw pointer to the start of this view. Valid for Self::len bytes for the lifetime of self. Returns a dangling-but-aligned pointer when the view is empty (parallel to core::ptr::NonNull::dangling) — the caller must respect Self::len before any read.

pub fn as_av_buffer_ref(&self) -> *const AVBufferRef

Underlying *const AVBufferRef. Useful when handing the buffer back to an FFmpeg API that expects a borrowed pointer (do not call av_buffer_unref on the result — self still owns the ref). The returned pointer references the whole buffer, not just this view’s sub-region.

This intentionally returns *const, not *mut. FFmpeg APIs that mutate via the buffer (e.g. av_buffer_make_writable) should be reached through the unsafe constructors which transfer ownership; shared &self access must not allow aliased writes.

pub fn offset(&self) -> usize

Byte offset of this view’s start within the underlying buffer.

pub fn try_clone(&self) -> Option<Self>

Fallible counterpart to Clone::clone. Returns None if av_buffer_ref fails (out-of-memory) instead of panicking. Use this in OOM-recoverable paths; the Clone impl panics on the same failure to match Rust’s standard Clone contract.

Trait Implementations

impl AsRef<[u8]> for FfmpegBuffer

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for FfmpegBuffer

fn clone(&self) -> Self

Refcounts the underlying AVBufferRef. Panics on OOM (see Self::try_clone for the fallible variant).

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FfmpegBuffer

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

Formats the value using the given formatter.

impl Drop for FfmpegBuffer

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for FfmpegBuffer