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
• Not Send: Prevents accidental cross-thread use of FFI buffers

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.

pub fn timestamp(&self) -> i64

Get the timestamp.

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) -> &[u8]

Get a zero-copy view of the frame data.

This returns a slice directly into the NDI SDK’s buffer. No allocation or memcpy is performed.

For planar 4:2:0 formats (YV12/I420/NV12), this returns the full buffer including Y and UV planes.

Safety Guarantee

The slice length is computed once at construction time using checked arithmetic and validated against MAX_VIDEO_BYTES. This eliminates the possibility of integer overflow or unbounded slice creation.

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

Convert this borrowed frame to an owned VideoFrame.

This performs a single memcpy of the frame data and metadata, allowing the frame to outlive the NDI buffer and be sent across threads.

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.