Struct ExportedFrame 

pub struct ExportedFrame {
    pub timestamp: u64,
    pub width: u32,
    pub height: u32,
    pub descriptor: DrmPrimeSurfaceDescriptor,
    /* private fields */
}

One decoded picture, left in the surface the hardware wrote it into.

The GPU counterpart of Frame: same picture, same timestamp, but a DRM PRIME descriptor for the surface rather than a copy of its pixels. The descriptor owns the exported file descriptors and the surface travels with it, so both the allocation and libva’s handle on it outlive the decoder.

The export is NV12 in one object holding both planes, which is what the Intel and AMD drivers produce. Read the modifier off the object before assuming anything about the layout: a decode target is tiled, and the plane pitches carry padding the visible size does not imply. That is also why ExportedFrame::download goes back through the surface instead of reading the file descriptor as rows.

Dropping the frame hands its surface back to the decoder, which decodes a later picture into it. So keep the frame for as long as anything reads the descriptor or an import of it: a GPU consumer holds it until the work that samples it has finished, not merely until that work is submitted. A frame that outlives its decoder, or the sequence it was decoded in, releases its surface to the driver instead.

This is Send and Sync even though Decoder is neither: a surface is a display and an id, both of which libva serializes internally, and none of the decoder’s Rcs come along.

Fields

timestamp: u64

Timestamp of the access unit this picture was coded in, as handed to Decoder::decode_exported.

width: u32

Visible width in pixels, i.e. after the SPS cropping rectangle.

height: u32

Visible height in pixels.

descriptor: DrmPrimeSurfaceDescriptor

The surface’s export: format, modifier, and the offset and pitch of each plane.

Implementations

impl ExportedFrame

pub fn from_surface(surface: Surface<()>, timestamp: u64) -> Result<Self>

Exports surface, an NV12 picture from somewhere other than the decoder, the way the decoder exports its own.

A picture the video processor produced, such as a scaled copy of a captured frame, then reaches its consumer with the same descriptor and the same download fallback as a decoded one, so one consumer handles both. timestamp is carried through untouched.

Errors

Fails when the surface is not NV12, cannot be synced, or the driver will not export it.

pub fn download(&self) -> Result<Frame>

Reads this picture back to client memory as tightly packed NV12.

The way back for a caller that took a descriptor and then found itself with a consumer that wants bytes. It costs the read Decoder::decode would have done up front, so prefer that entry point when nothing on the path draws on the GPU.

Same layout as Frame::data, with the driver’s row padding dropped.

Trait Implementations

impl Debug for ExportedFrame

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

Formats the value using the given formatter.