Struct SourceFrame 

pub struct SourceFrame {
    pub width: u32,
    pub height: u32,
    pub format: SourceFormat,
    /* private fields */
}

One frame a source hands the bus.

The extent and format are plain public fields; the payload and the release callback are private, so they stay together. Build a frame with Self::new or Self::rgba8 and attach a callback with Self::on_release; read the payload in place with Self::payload.

Dropping a frame that still holds its release callback runs it: the bus runs it for every frame it is handed (see the module docs), and a frame nobody released — dropped by a holder that never passed it on, or lost to a panic in the source or the pass — still releases, exactly once. Because the type implements Drop, it cannot be destructured; the bus splits it with the unsafe Self::into_parts. A release callback must not panic: the guard around it only applies to panic=unwind builds (see [run_release]).

Fields

width: u32

Width in pixels.

height: u32

Height in pixels.

format: SourceFormat

How the payload’s pixels are laid out.

Implementations

impl SourceFrame

pub fn new( width: u32, height: u32, format: SourceFormat, payload: SourcePayload, ) -> SourceFrame

A frame of the given extent and format over payload, with no release callback.

pub fn rgba8(width: u32, height: u32, pixels: Arc<[u8]>) -> SourceFrame

A CPU frame of tightly packed premultiplied RGBA8 with no release callback.

pub fn on_release(self, release: impl FnOnce() + Send + 'static) -> SourceFrame

Attaches the callback run once the bus is done with the frame. A callback already attached runs first (through the same guard as every other release), so no callback is ever dropped unrun.

pub fn meta(&self) -> SourceMeta

The extent and format.

pub fn payload(&self) -> &SourcePayload

The pixels, or the platform buffer holding them, borrowed in place. The frame still owns the payload and its release callback.

pub fn has_release(&self) -> bool

Whether a release callback is attached.

pub unsafe fn into_parts( self, ) -> (SourceMeta, SourcePayload, Option<Box<dyn FnOnce() + Send>>)

Consumes the frame, handing over its extent and format, its payload and its release callback, and disarms the drop guard — the one way to move a native handle out of a frame. A caller that only needs to read the frame uses Self::meta and Self::payload instead.

Safety

The caller must run the returned release callback exactly once, after the last use of the payload’s native handle (or move it, with the handle, into a holder that does), and must not place that handle into another frame without it. The callback gives the producer’s reference to the buffer back; a handle used after it ran points at a buffer the producer no longer keeps alive.

pub fn release(self)

Runs the release callback, if any, consuming the frame — the same as dropping it, spelled out.

Trait Implementations

impl Debug for SourceFrame

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

Formats the value using the given formatter.

impl Drop for SourceFrame

fn drop(&mut self)

A frame dropped still holding its callback was released by no one, so it releases itself; one whose callback already ran or was taken on (into a held import) is None here.

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.