Struct VideoRef 

pub struct VideoRef<'a, S: FrameFree<RawFrame = NDIlib_video_frame_v2_t>> { /* private fields */ }

A zero-copy borrowed video frame, generic over its free strategy S.

This type wraps an RAII Guard that owns the NDI frame buffer lifetime, exposing a safe, zero-copy view of the video data. The frame is automatically freed when dropped, via whichever NDIlib_*_free_video* call the strategy S encodes.

The two public spellings are type aliases over this one core, so every accessor and the Debug impl are written exactly once:

• VideoFrameRef<'rx> — frames captured from a Receiver (freed via NDIlib_recv_free_video_v2).
• FrameSyncVideoRef<'fs> — frames captured from a FrameSync (freed via NDIlib_framesync_free_video).

Key characteristics:

• Zero allocations: References NDI SDK buffers directly
• Zero copies: No memcpy of pixel data
• RAII lifetime: Exactly one free per frame, enforced at compile time
• Receiver refs are Send + Sync; FrameSync refs stay on their capture thread
• Immutable plane/row views support scoped worker reads from either family

Lifetime

The lifetime parameter 'a ties this frame to the owner (a Receiver or a FrameSync) that created it. The borrow checker ensures the owner cannot be dropped while any frame references are alive, preventing use-after-free at compile time with zero runtime cost. The underlying NDI buffer is freed when the frame ref is dropped.

Performance

For a 1920×1080 BGRA frame, this eliminates ~8.3 MB of memcpy compared to the owned VideoFrame. At 60 fps, this saves ~475 MB/s of memory bandwidth.

Implementations

impl<'a, S: FrameFree<RawFrame = NDIlib_video_frame_v2_t>> VideoRef<'a, S>

pub fn width(&self) -> i32

Get the frame width in pixels.

pub fn height(&self) -> i32

Get the frame height in pixels.

pub fn pixel_format(&self) -> PixelFormat

Get the pixel format (FourCC code).

This is guaranteed to be a valid, supported format since it’s validated during construction.

pub fn frame_rate_n(&self) -> i32

Get the frame rate numerator.

pub fn frame_rate_d(&self) -> i32

Get the frame rate denominator.

pub fn picture_aspect_ratio(&self) -> f32

Get the picture aspect ratio.

pub fn scan_type(&self) -> ScanType

Get the scan type (progressive, interlaced, etc.).

This is guaranteed to be valid since it is checked during construction.

pub fn timecode(&self) -> i64

Get the timecode in 100 ns units.

pub fn timestamp(&self) -> i64

Get the receive timestamp in 100 ns units since the Unix epoch.

pub fn line_stride_or_size(&self) -> LineStrideOrSize

Get the line stride or data size.

This returns the cached, validated value computed at construction time.

pub fn metadata(&self) -> Option<&str>

Get frame metadata as UTF-8 text, if present.

pub fn data(&self) -> Option<&[u8]>

Borrow all active pixels when contiguous, in SDK plane order.

Returns None if padding separates active rows or planes. Use Self::planes / Self::plane for zero-copy padded access, or Self::to_owned for a tightly packed owned buffer. A single packed row can be borrowed even when its stride includes trailing padding.

pub fn plane(&self, index: usize) -> Option<VideoPlane<'_>>

Get one plane in SDK memory order, or None for an invalid index.

pub fn planes(&self) -> VideoPlanes<'_>

Iterate planes in SDK memory order without allocating or copying.

pub fn encode_png(&self) -> Result<Vec<u8>>

Encode PNG directly from the borrowed SDK pixels, without first copying the frame into an owned VideoFrame. Uses the same supported formats and padding handling as VideoFrame::encode_png.

pub fn encode_jpeg(&self, quality: u8) -> Result<Vec<u8>>

Encode JPEG directly from borrowed SDK pixels. Quality must be in 1..=100; see VideoFrame::encode_jpeg for format restrictions.

pub fn encode_data_url(&self, format: ImageFormat) -> Result<String>

Encode borrowed SDK pixels as a PNG or JPEG base64 data URL without an intermediate owned frame. See VideoFrame::encode_data_url.

pub fn to_owned(&self) -> Result<VideoFrame>

Convert this borrowed frame to an owned VideoFrame.

Copies only active rows into one tightly packed pixel allocation and copies metadata separately. The owned stride can be smaller than the SDK stride. Preserves format, timing, aspect ratio, and scan type.

Trait Implementations

impl<'a, S: FrameFree<RawFrame = NDIlib_video_frame_v2_t>> Debug for VideoRef<'a, S>

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

Formats the value using the given formatter.