pub struct Buffer { /* private fields */ }Expand description
An owned dumb buffer, its optional KMS framebuffer, and its CPU mapping.
Dumb buffers are KMS’s GPU-free allocation path: any driver implementing
DRM_CAP_DUMB_BUFFER — every modern KMS driver — can allocate a
CPU-mappable linear pixel buffer with no accelerator involved. They are the
right tool for cursors, client-side decorations, software-rendered UI, and
test harnesses.
§Deviation: the mapping is established once, not per map()
The drm crate’s map_dumb_buffer performs an mmap on every call and its
guard munmaps on drop. That is the opposite of what invariant 6
requires — one mapping held for the buffer’s lifetime, and a free map()
per frame. So the allocation and destruction ioctls come from the drm
crate (DR-2), while the mapping is established once here at creation and
held. See Mapping for why the cost contract matters.
Implementations§
Source§impl Buffer
impl Buffer
Sourcepub fn create(device: &Device, config: &Config) -> Result<Self>
pub fn create(device: &Device, config: &Config) -> Result<Self>
Allocate a single-plane dumb buffer.
§Errors
DumbError::InvalidConfigfor zero dimensions, a zero format, a zero bpp, dimensions past 16384, or aFourCCthedrmcrate does not recognize.DumbError::TooLargeif the kernel’s allocation size does not fit ausize.DumbError::Ioif an ioctl or themmapfails.
Sourcepub fn create_planar(
device: &Device,
fourcc_code: u32,
width: u32,
height: u32,
) -> Result<Self>
pub fn create_planar( device: &Device, fourcc_code: u32, width: u32, height: u32, ) -> Result<Self>
Allocate a dumb buffer for a recognized semi-planar YUV format —
NV12, NV21, P010, P012, or P016.
The kernel allocates one linear region; the framebuffer points the Y and interleaved-UV planes at distinct byte offsets within it. Pass the image dimensions: the over-allocation for the half-height chroma plane and the 8- versus 16-bit sample width are derived internally.
height should be even. The chroma half-height uses integer division,
so an odd height rounds down.
§Errors
DumbError::UnsupportedFormatfor a format outside the recognized set — fall back toBuffer::createfor single-plane formats.DumbError::InvalidConfigfor zero or out-of-range dimensions.DumbError::TooLargeif the row count or chroma offset would not fit the kernel’s 32-bit fields, or the allocation size ausize.DumbError::Ioif an ioctl or themmapfails.
Sourcepub const fn height(&self) -> u32
pub const fn height(&self) -> u32
Height in pixels — the image height, not the over-allocated row count of a planar buffer.
Sourcepub fn size_bytes(&self) -> usize
pub fn size_bytes(&self) -> usize
Total mapped bytes.
Sourcepub fn gem_handle(&self) -> Option<u32>
pub fn gem_handle(&self) -> Option<u32>
The GEM handle on the originating descriptor.
Legacy cursor paths consume this directly; atomic paths use
fb_id.
Sourcepub fn map(&mut self, access: MapAccess) -> Mapping<'_>
pub fn map(&mut self, access: MapAccess) -> Mapping<'_>
Acquire a scoped CPU view.
Free in both directions — see Mapping and invariant 6. The access
mode is recorded on the view but ignored here; it exists so the same
scoped painting code works against dumb and GBM buffers.
Yields an empty view when the buffer is empty.
Sourcepub fn forget(&mut self)
pub fn forget(&mut self)
Abandon the GEM handle and framebuffer id without issuing ioctls.
For when the originating descriptor is known to be dead — libseat’s
session-resume replaced the device. The CPU mapping is still torn down,
because munmap is descriptor-independent, so the caller is left with a
valid empty buffer. The kernel reclaims the orphaned handles when the
descriptor closes.