Struct Mapping 

pub struct Mapping<'a> { /* private fields */ }

A borrowed view over a dumb buffer’s linear pixel storage.

Invariant 6: a zero-cost view of a lifetime mmap

A dumb buffer is mmap’d once at creation and the mapping is held for the buffer’s whole life, cache-coherent by kernel construction. Acquiring this view therefore costs nothing — no ioctl, no syscall — and dropping it costs nothing either.

In C++ that is a documented promise: BufferMapping carries a function pointer that happens to be null for dumb buffers, and a comment explains that the destructor is a no-op. Here it is structural. This type has no Drop implementation at all, so there is no destructor to become non-trivial by accident — adding one would be a visible, reviewable change rather than a silent regression in per-frame cost.

The borrow is equally load-bearing: the view cannot outlive the buffer it came from, so the use-after-free the C++ warns about (“holding a mapping past the buffer’s destructor”) does not compile.

The lifetime-mmap decision matters beyond convenience — DumbScanoutSink’s pacing depends on map() being free per frame — so it is pinned rather than merely documented.

Implementations

impl<'a> Mapping<'a>

pub const fn is_empty(&self) -> bool

Whether the view covers no storage.

pub const fn pixels(&self) -> &[u8]

The linear pixel storage, read only.

The first row starts at index 0; subsequent rows are stride bytes apart.

pub const fn pixels_mut(&mut self) -> &mut [u8]

The linear pixel storage, mutable.

pub const fn stride(&self) -> u32

Bytes per row.

The kernel may pad this above width * bytes_per_pixel — amdgpu’s DC applies a 256-byte rule, for one. Honor it rather than recomputing.

pub const fn width(&self) -> u32

Buffer width in pixels.

pub const fn height(&self) -> u32

Buffer height in pixels.

pub const fn access(&self) -> MapAccess

The access mode this view was acquired with.

Recorded but unused at the dumb-buffer level; a backend maintaining dirty state across map cycles can switch on it.

pub fn row(&self, row: u32) -> Option<&[u8]>

One row, read only, or None if row is past the bottom.

pub fn row_mut(&mut self, row: u32) -> Option<&mut [u8]>

One row, mutable, or None if row is past the bottom.

Trait Implementations

impl<'a> Debug for Mapping<'a>

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

Formats the value using the given formatter.