Trait LayerBufferSource 

pub trait LayerBufferSource {
    // Required methods
    fn acquire(&mut self) -> Result<AcquiredBuffer, SourceError>;
    fn release(&mut self, acquired: AcquiredBuffer);
    fn format(&self) -> SourceFormat;

    // Provided methods
    fn release_with_fence(
        &mut self,
        acquired: AcquiredBuffer,
        release_fence: Option<SyncFence>,
    ) { ... }
    fn wants_release_fence(&self) -> bool { ... }
    fn has_fresh_content(&self) -> bool { ... }
    fn on_retired(&mut self) { ... }
    fn binding_model(&self) -> BindingModel { ... }
    fn map(&mut self, access: MapAccess) -> Result<Mapping<'_>, SourceError> { ... }
    fn with_mapping(
        &mut self,
        access: MapAccess,
        f: &mut dyn FnMut(&mut Mapping<'_>),
    ) -> Result<(), SourceError> { ... }
    fn export_dma_buf(&mut self) -> Result<DmaBufDesc<'_>, SourceError> { ... }
    fn bind_to_plane(&mut self, plane_id: u32) -> Result<(), SourceError> { ... }
    fn unbind_from_plane(&mut self, plane_id: u32) { ... }
    fn on_session_paused(&mut self) { ... }
    fn on_session_resumed(&mut self, device: &Device) -> Result<(), SourceError> { ... }
}

Where a layer’s content comes from.

Owning a source is owning the DRM handles it holds: dropping a layer drops its source and the buffers with it.

Required Methods

fn acquire(&mut self) -> Result<AcquiredBuffer, SourceError>

Produce this frame’s buffer.

On success the source has arranged that fb_id names a ready-to-scan-out framebuffer. The scene pairs the result with a later release once the commit completes.

Errors

SourceError::WouldBlock is flow control and expected — see that variant. Any other error aborts the commit.

fn release(&mut self, acquired: AcquiredBuffer)

Return a buffer to the free pool.

Infallible by contract. The scene calls this after page-flip completion, on commit failure, and during shutdown; there is deliberately no error channel, so those cleanup paths stay simple enough to be correct.

fn format(&self) -> SourceFormat

The buffer’s shape, read during layer lowering to populate the properties the allocator consults.

Provided Methods

fn release_with_fence( &mut self, acquired: AcquiredBuffer, release_fence: Option<SyncFence>, )

Release carrying the OUT_FENCE of the commit that displaced this buffer.

Once it signals, the buffer is off-screen and safe to render into again, so a GPU producer can wait on it GPU-side instead of blocking the CPU until the later release edge. None when the CRTC has no OUT_FENCE_PTR or the source did not opt in.

The default forwards to release, so only a source that wants the fence overrides it — see wants_release_fence.

fn wants_release_fence(&self) -> bool

Whether this source wants the per-buffer release fence.

The scene only requests an internal OUT_FENCE when some live source says yes, so this costs nothing otherwise.

fn has_fresh_content(&self) -> bool

Whether a producer submitted something new since the last commit.

Drives the scene’s whole-commit skip: when every live source says no and no layer is dirty, no atomic commit is issued at all — a power win, and what lets a self-refresh panel stay in self-refresh.

The default is true, deliberately. A source that cannot tell whether its buffer changed — a CPU producer painting into a dumb buffer the scene cannot introspect — must say “changed”, or a real update is silently skipped. Only a source that knows it is idle returns false.

fn on_retired(&mut self)

The scene acquires from this source no more: its layer was removed.

Its in-flight buffers still come back through release or release_with_fence, after the commits that displace them. A source that holds its on-screen buffer back from release until a newer frame supersedes it – ExternalDmaBufRing, ExternalDmaBufPool – must let that one go with them: no newer frame is coming, and the producer would never get the buffer back. A client that makes a new pool per geometry would lose one buffer to every resize until it ran out and stalled.

The default does nothing.

fn binding_model(&self) -> BindingModel

Which binding contract this source participates in.

fn map(&mut self, access: MapAccess) -> Result<Mapping<'_>, SourceError>

Acquire a CPU view of the pixel storage.

Composition fallback reads through this, by way of with_mapping, to rescue layers the allocator could not place. A source whose pixels live only in GPU memory returns SourceError::Unsupported — and is then uncompositable: the scene’s CPU composition reads only through these.

Errors

SourceError::Unsupported by default.

fn with_mapping( &mut self, access: MapAccess, f: &mut dyn FnMut(&mut Mapping<'_>), ) -> Result<(), SourceError>

Run f over a CPU view of the pixel storage, writable when access allows it.

What the scene’s composition reads through. The default maps with map and hands that view to f, so a source that implements map needs nothing here. A source that can lend its pixels only for a bounded time – one shared behind a RefCell, whose borrow cannot outlive a call – overrides this instead, and holds whatever it must for exactly as long as f runs.

Errors

Whatever map fails with; f is not called then.

fn export_dma_buf(&mut self) -> Result<DmaBufDesc<'_>, SourceError>

Export the currently-acquired buffer’s DMA-BUF planes.

For a consumer that imports DMA-BUFs: a source whose pixels never reach CPU memory — a V4L2 capture buffer — can be handed on this way. Upstream composites such a layer on the GPU; that compositor is not ported yet, and the scene’s CPU composition reads only through with_mapping.

Errors

SourceError::Unsupported by default.

fn bind_to_plane(&mut self, plane_id: u32) -> Result<(), SourceError>

Bind a driver-owned producer to a plane.

For a BindingModel::DriverOwnsBinding source, after the allocator settles on a plane and before the first acquire for it. Dormant like that variant: nothing in the scene calls it yet. The no-op default is correct for every BindingModel::SceneSubmitsFbId source.

Errors

Never, by default.

fn unbind_from_plane(&mut self, plane_id: u32)

Unbind from a plane, when the layer is reassigned or retired. Dormant, as bind_to_plane is.

fn on_session_paused(&mut self)

The session is losing DRM master; issue no ioctls until resumed.

fn on_session_resumed(&mut self, device: &Device) -> Result<(), SourceError>

The session is back with a fresh device.

A source holding descriptor-bound state must drop every handle tied to the dead descriptor — ioctls against it will fail — and re-allocate equivalent buffers. Dimensions and formats are preserved: callers rely on format returning the same value afterwards.

Errors

Whatever re-allocation failed with.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors