denise-drm

The Linux DRM/KMS backend for Denise — and the primary target the whole toolkit exists for.

Opens the display directly, sets a mode, and page-flips CPU-rendered dumb buffers straight to the scanout engine. No compositor, no window server, no GPU driver stack, no X. One static binary that owns the panel.

# #[cfg(target_os = "linux")]
# fn demo() -> Result<(), denise_drm::DrmError> {
use denise::Surface;
use denise_drm::{DrmSurface, PresentMode, SurfaceConfig};

// Opens the first card with a display output, takes master, picks a mode and
// builds the swapchain.
let mut surface = DrmSurface::open(SurfaceConfig {
    present_mode: PresentMode::Vsync,
    ..SurfaceConfig::default()
})?;
println!("mode {} at {:?}", surface.mode_name(), surface.size());
# Ok(())
# }

DrmSurface::new(card, config) takes a Card you opened yourself — including one handed over as a file descriptor, which is how this coexists with libseat or a systemd unit.

Becoming DRM master

Setting a mode requires being DRM master, and only one process can be. If a compositor or another Denise process holds it, Card::become_master fails with EBUSY or EACCES — the single most common reason a first run on a Pi does nothing. Three ways to have the right:

• Run on a bare VT with no display server. The usual kiosk deployment.
• Be handed a file descriptor by libseat or a systemd unit, via Card::from_fd. Preferred for anything that has to coexist.
• Run as root. Works, and is a poor way to ship a product.

What it deliberately does not do

No gbm. GBM exists to allocate buffers a GPU renders into. Denise renders with the CPU, so DRM dumb buffers are exactly the right allocation: scanout-capable, CPU-mappable, and free of any C library. Adding GBM would drag in libgbm and Mesa, ending both the single-static-binary goal and easy cross-compilation.

No atomic modesetting, yet. Atomic buys FB_DAMAGE_CLIPS, plane composition and tear-free guarantees. The first is worth little here — a page flip swaps whole buffers, so damage saves rasterisation, not bandwidth, and most drivers ignore the property. The second has a legacy equivalent for the one plane that matters, the hardware cursor. So the legacy path gets this working on real hardware at a third of the code, behind a seam atomic can take over when planes earn their keep.

When a frame tears, and when it waits

PresentMode::Immediate flips without waiting for vblank, because on a Pi 3A+ at 1920×1080 that wait is about 17 ms and it is felt as lag by the person pressing the button. A button redrawing itself damages a few thousand pixels, so the seam where the panel switched buffers mid-scan is small, brief and invisible.

A scrolling viewport is the other case, and it fails twice over. The seam crosses the text being read, and — because an async flip never blocks — nothing paces the loop, so the same Pi spends a whole core producing torn frames at 14.5 ms each for as long as a finger keeps moving.

So the flip follows the damage rather than the setting alone: damage covering under a quarter of the screen's rows flips async, at or above it waits for vblank. The latency stays where it is felt, the pacing arrives on the frames that cannot afford to go without it, and an application does not have to know which kind of frame it just drew. PresentMode::Vsync is still an absolute promise; it is Immediate that became a preference.

Rows, not area — which took a second go to get right. The first version compared damaged pixels against the surface, and a Pi still flashed occasionally. The gallery's sidebar is 300×1016 on a 1920×1080 panel: 14.7% of the pixels and 94% of the scanlines, so it went out async and tore across almost the whole height of the screen. A tear is a horizontal seam, so what matters is how many rows the damage touches. A full-width toolbar forty rows tall may still tear freely; a narrow column down the whole screen may not.

Covered, not spanned — which took a third. Counting rows by the damage's bounding box says that two small updates at opposite ends of the screen are a full-height frame, and they are not: outside the damage both buffers hold the same pixels, so a seam falling between them shows nothing. The gallery keeps a spinner turning at the top, so every frame with a pointer in the lower two thirds carried a spinner, a cursor and a bounding box across the eight hundred untouched rows between — vblank-paced, from a rule written for scrolling, and reported as flicker on the hovered control. The count is now the rows the rectangles actually cover, overlaps once. The sidebar covers 1016 either way and still waits.

Testing

Mode selection, the swapchain and the flip decision are platform-independent on purpose and are unit tested everywhere, including on machines with no DRM device. They hold the decisions that are hard to debug in the field and easy to check on a laptop. Everything else is a thin wrapper over ioctls and can only be proven on real hardware — which it has been, on a Raspberry Pi.

Two examples help on a new board: probe prints the connectors, modes and capabilities it finds, and smoke sets a mode and flips.

Platform

Linux only. On any other target the crate compiles to almost nothing, which is what lets the whole workspace be checked and published from one runner. unsafe is permitted here and every block carries a // SAFETY: comment.

Where this sits

Implements denise::Surface. Pair it with denise-evdev for input — both expose raw file descriptors, so an event loop can epoll on input and vblank together and the process idles in the kernel rather than spinning. denise-fbdev is the fallback for kernels with no usable DRM driver.

Status

M2 complete, running on real hardware. Part of Denise — see the repository README and docs/design.md for the whole picture.

MIT licensed.