Struct Surface 

pub struct Surface { /* private fields */ }

A decoration’s pixels, and the framebuffer they scan out through.

Implementations

impl Surface

pub fn create( device: &Device, config: SurfaceConfig, ) -> Result<Self, SurfaceError>

Allocate a decoration surface.

Errors

SurfaceError::Invalid for a zero dimension — refused here rather than passed to the kernel, which reports the same thing less clearly — and SurfaceError::Allocate if the driver refuses it.

pub const fn is_empty(&self) -> bool

Whether this surface holds no buffer.

pub fn fb_id(&self) -> u32

The framebuffer id, or zero when empty.

Zero rather than an error because that is what a presenter writes to disarm a plane — an empty surface and a disarmed slot are the same thing said twice.

pub fn width(&self) -> u32

Width in pixels, or zero when empty.

pub fn height(&self) -> u32

Height in pixels, or zero when empty.

pub fn stride(&self) -> u32

Bytes between rows, or zero when empty.

pub const fn format(&self) -> u32

Always SURFACE_FOURCC, empty or not.

A constant rather than a stored field: an empty surface still answers, because a caller laying out a decoration it has not allocated yet needs to know what it will be.

pub const fn generation(&self) -> u64

How many times this surface has been painted — mapped by paint for anything other than MapAccess::Read.

pub fn paint(&mut self, access: MapAccess) -> Result<Mapping<'_>, SurfaceError>

Map the pixels for drawing, and count the paint.

The generation is bumped for any map that allows writing, whether or not anything is actually written: a caller that mapped for writing intends to, and under-reporting a change leaves a stale decoration on screen where over-reporting only costs a recomposite. A read-only (MapAccess::Read) map does not bump it.

Errors

SurfaceError::Empty when there is no buffer.

pub fn export(&self, device: &Device) -> Result<OwnedFd, SurfaceError>

Export the buffer as a DMA-BUF.

The descriptor is close-on-exec, as the reference exports it, so a compositor that spawns a client does not hand it the decoration.

Errors

SurfaceError::Empty when there is no buffer, and SurfaceError::Export with the kernel’s errno when the export is refused.

pub fn forget(&mut self)

Drop the buffer without issuing ioctls against its descriptor.

For a session that lost its device: the handles are already dead, so destroying them would fail, and the kernel reclaims them when the descriptor closes. Forgetting an already-empty surface is a no-op, which is what a caller tearing down twice does.

Trait Implementations

impl Debug for Surface

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

Formats the value using the given formatter.

impl Default for Surface

fn default() -> Self

Returns the “default value” for a type.