Struct BorrowedVideoFrame 

pub struct BorrowedVideoFrame<'buf> { /* private fields */ }

A borrowed video frame that references external pixel data. Used for zero-copy async send operations.

Fields are private to enforce safety invariants. Use try_from_uncompressed for supported typed formats or from_parts_unchecked as the explicit unsafe escape hatch for unsupported SDK layouts.

Implementations

impl<'buf> BorrowedVideoFrame<'buf>

pub fn try_from_uncompressed( data: &'buf [u8], width: i32, height: i32, pixel_format: PixelFormat, frame_rate_n: i32, frame_rate_d: i32, ) -> Result<Self>

Create a borrowed video frame from an uncompressed pixel buffer.

This constructor validates that the buffer is large enough for the specified dimensions and pixel format, returning an error if validation fails.

Arguments

• data - Borrowed slice containing pixel data
• width - Frame width in pixels
• height - Frame height in pixels
• pixel_format - Uncompressed pixel format (BGRA, UYVY, etc.)
• frame_rate_n - Frame rate numerator (e.g., 60 for 60fps, 30000 for 29.97fps)
• frame_rate_d - Frame rate denominator (e.g., 1 for 60fps, 1001 for 29.97fps)

Errors

Returns Error::InvalidFrame if the buffer is too small for the specified format.

Example

let buffer = vec![0u8; 1920 * 1080 * 4]; // BGRA buffer
let frame = BorrowedVideoFrame::try_from_uncompressed(
    &buffer,
    1920,
    1080,
    PixelFormat::BGRA,
    30,
    1
)?;

pub unsafe fn from_parts_unchecked( data: &'buf [u8], width: i32, height: i32, fourcc: u32, frame_rate_n: i32, frame_rate_d: i32, picture_aspect_ratio: f32, scan_type: ScanType, timecode: i64, line_stride_or_size: LineStrideOrSize, metadata: Option<&'buf CStr>, timestamp: i64, ) -> Self

Create a borrowed video frame without validation (unsafe).

Safety

The caller must ensure all SDK-facing fields describe a valid frame:

• fourcc is a correct NDI video FourCC for the payload.
• The FourCC and line_stride_or_size union field are paired according to the SDK contract: uncompressed formats use LineStrideOrSize::LineStrideBytes, compressed or opaque formats use LineStrideOrSize::DataSizeBytes.
• Dimensions are positive where required by the SDK format, and any planar format dimension or stride requirements are satisfied.
• Line stride or data size is positive, fits the SDK field, and is sufficient for every byte the SDK may read.
• data is live and large enough for the final layout for the full send lifetime.
• frame_rate_n and frame_rate_d are positive, picture_aspect_ratio is finite and positive, and scan_type matches a supported SDK scan type.
• metadata, when present, remains valid, NUL-terminated, UTF-8, and within the crate metadata size cap for the full send lifetime.

Zero/default timecode and timestamp values are passed through to the SDK as default timing values.

Violating these invariants will cause the NDI SDK to read out of bounds through FFI, leading to undefined behavior.

Example

let buffer = vec![0u8; 1920 * 1080 * 4];
let stride = PixelFormat::BGRA.try_line_stride(1920).unwrap();

// SAFETY: Buffer is correctly sized for 1920x1080 BGRA
let frame = unsafe {
    BorrowedVideoFrame::from_parts_unchecked(
        &buffer,
        1920,
        1080,
        PixelFormat::BGRA.into(),
        30,
        1,
        16.0 / 9.0,
        grafton_ndi::ScanType::Progressive,
        0,
        LineStrideOrSize::LineStrideBytes(stride),
        None,
        0,
    )
};

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) -> Option<PixelFormat>

Get the supported typed pixel format, if the raw FourCC is one of the crate’s supported uncompressed formats.

pub fn fourcc(&self) -> u32

Get the raw SDK FourCC value.

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.

pub fn timecode(&self) -> i64

Get the timecode.

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

Get a reference to the pixel data.

pub fn line_stride_or_size(&self) -> LineStrideOrSize

Get the line stride or data size.

pub fn validated_data_len(&self) -> Option<usize>

Get the validated SDK data length for frames built through the safe typed constructor.

Returns None for frames created with Self::from_parts_unchecked, because those layouts are intentionally outside the crate’s supported typed model.

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

Get the metadata as UTF-8 text, if any.

pub fn timestamp(&self) -> i64

Get the timestamp.

Trait Implementations

impl<'buf> From<&'buf VideoFrame> for BorrowedVideoFrame<'buf>

fn from(frame: &'buf VideoFrame) -> Self

Converts to this type from the input type.