denise_fbdev/lib.rs
1//! Legacy Linux fbdev backend for Denise.
2//!
3//! # Read this before reaching for it
4//!
5//! This is a fallback, and on any current kernel it is a fallback to DRM through a
6//! longer route. `/dev/fb0` on a modern system is almost always
7//! `CONFIG_DRM_FBDEV_EMULATION` — DRM pretending to be fbdev. The Alpine VM this
8//! was developed against reports its framebuffer's name as `virtio_gpudrmfb`, and
9//! a Raspberry Pi running Bookworm reports `vc4drmfb`. Going through it means
10//! giving up page flips, vsync and buffer age, to reach the same hardware
11//! [`denise_drm`](../denise_drm/index.html) already drives properly.
12//!
13//! So prefer DRM. Use this when:
14//!
15//! - the kernel is old enough to predate a usable DRM driver for the panel,
16//! - the panel has an fbdev driver and no DRM driver at all, which still happens
17//! with small SPI displays,
18//! - or DRM master cannot be obtained and a degraded picture beats none.
19//!
20//! # What it costs
21//!
22//! No page flip and no vsync, so a frame can tear. Drawing goes through a shadow
23//! buffer and only damaged rows are copied out, which keeps the tear as small as
24//! the change that caused it — the only mitigation available here, and another
25//! reason damage tracking belongs in the core rather than in a backend.
26//!
27//! # Permissions
28//!
29//! Writing to `/dev/fb*` needs the `video` group, or root.
30
31// `chunks_exact` over `as_chunks`, against clippy 1.98's advice: `as_chunks`
32// stabilised in 1.98 and this workspace supports 1.95, so taking the advice
33// would trade a style lint for a compile error on every older toolchain. Revisit
34// when the MSRV passes 1.98. `unknown_lints` because the lint does not exist
35// before 1.98 either, and naming an absent lint is itself a warning.
36#![allow(unknown_lints, clippy::chunks_exact_to_as_chunks)]
37
38pub mod info;
39
40pub use info::{FbInfo, FbInfoError, PixelLayout};
41
42#[cfg(target_os = "linux")]
43mod error;
44#[cfg(target_os = "linux")]
45mod surface;
46
47#[cfg(target_os = "linux")]
48pub use error::FbdevError;
49#[cfg(target_os = "linux")]
50pub use surface::FbdevSurface;
51
52/// Compiles the examples in this crate's README, so they cannot drift from the API
53/// they claim to demonstrate. Never built except under `cargo test --doc`.
54#[cfg(doctest)]
55#[doc = include_str!("../README.md")]
56struct Readme;