drmkit_dumb/lib.rs
1// SPDX-FileCopyrightText: (c) 2026 Joel Winarske
2// SPDX-License-Identifier: MIT
3
4//! DRM dumb buffers: GPU-free, CPU-mappable scanout surfaces.
5//!
6//! Port of `src/dumb/` plus `src/buffer_mapping.hpp` from drm-cxx @ `dc2915b`.
7//!
8//! Dumb buffers are KMS's allocation path that needs no accelerator: any driver
9//! implementing `DRM_CAP_DUMB_BUFFER` — every modern KMS driver — can hand back
10//! a linear, CPU-mappable pixel buffer. They are the right tool for cursors,
11//! client-side decorations, software-rendered UI, and test harnesses.
12//!
13//! # Invariant 6
14//!
15//! [`Buffer::map`] is a zero-cost view of a mapping established once and held
16//! for the buffer's whole life. [`Mapping`] has no [`Drop`] implementation, so
17//! "the guard's destructor is a no-op" is structural rather than documented,
18//! and the borrow makes outliving the buffer a compile error.
19//!
20//! This is load-bearing beyond convenience: `DumbScanoutSink`'s pacing depends
21//! on `map()` costing nothing per frame.
22//!
23//! # Example
24//!
25//! ```no_run
26//! use drmkit_core::Device;
27//! use drmkit_dumb::{Buffer, Config, MapAccess};
28//! use drmkit_fmt::fourcc;
29//!
30//! let device = Device::open("/dev/dri/card0")?;
31//! let mut buffer = Buffer::create(
32//! &device,
33//! &Config { width: 64, height: 64, fourcc: fourcc::XRGB8888, ..Config::default() },
34//! )?;
35//!
36//! // Free to acquire, free to drop -- once per frame is fine.
37//! let mut view = buffer.map(MapAccess::Write);
38//! if let Some(row) = view.row_mut(0) {
39//! row.fill(0xff);
40//! }
41//! # Ok::<(), Box<dyn std::error::Error>>(())
42//! ```
43
44mod buffer;
45mod error;
46mod mapping;
47
48pub use buffer::{Buffer, Config};
49pub use error::{DumbError, Result};
50pub use mapping::{MapAccess, Mapping};
51
52#[cfg(test)]
53mod tests;