Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Smithay/drm-rs/llms.txt

Use this file to discover all available pages before exploring further.

A DRM plane is a hardware memory object that holds a framebuffer and feeds pixel data to a CRTC for display. Every CRTC has at least one primary plane representing the main display surface. Additional overlay and cursor planes may be available for hardware compositing and pointer rendering, respectively. Planes carry the list of pixel formats they can accept (as DRM FourCC codes) and a bitmask indicating which CRTCs they can be attached to. In the atomic modesetting model, almost all configuration — framebuffer, position, scaling, format — is expressed as property values on the plane object. Planes are enumerated with Device::plane_handles() and inspected with Device::get_plane().
By default, DRM only exposes primary planes. To see overlay and cursor planes you must enable ClientCapability::UniversalPlanes before enumerating planes.

​
plane::Handle

An opaque, copy-cheap handle to a plane resource. Internally a NonZeroU32 wrapped with repr(transparent). Implements ResourceHandle with FFI_TYPE = DRM_MODE_OBJECT_PLANE. 
// plane_handles() returns Vec<plane::Handle>
let plane_handles = card.plane_handles().unwrap();

​
plane::Info

Returned by Device::get_plane(). Describes the current state and capabilities of a plane.
MethodReturn typeDescription
handle()HandleThe plane’s own handle
crtc()Option<crtc::Handle>The CRTC this plane is currently attached to, or None if unused
framebuffer()Option<framebuffer::Handle>The framebuffer currently set on this plane, or None
possible_crtcs()CrtcListFilterBitmask of compatible CRTCs; use with ResourceHandles::filter_crtcs
formats()&[u32]Raw FourCC codes for pixel formats this plane accepts
Info also implements Display, formatting as "Plane <id>".
formats() returns raw u32 values. Convert them with drm_fourcc::DrmFourcc::try_from(code) to obtain typed format identifiers.

​
PlaneType

The functional role of a plane. Determined at runtime by reading the "type" KMS property on the plane object, not from plane::Info directly.
VariantValueDescription
PrimaryDRM_PLANE_TYPE_PRIMARYThe main content plane; every CRTC has exactly one. Attaching a framebuffer to a CRTC in the legacy API implicitly uses this plane.
OverlayDRM_PLANE_TYPE_OVERLAYAdditional compositing layers above the primary plane, composited in hardware. Useful for video overlays and layered UI.
CursorDRM_PLANE_TYPE_CURSORHardware cursor plane with a hotspot. Typically limited to small sizes (64×64 pixels) and specific formats.
use drm::control::{Device as ControlDevice, PlaneType};

// Read the plane type property
let props = card.get_properties(plane_handle).unwrap();
let (handles, values) = props.as_props_and_values();
for (&prop_handle, &raw_value) in handles.iter().zip(values.iter()) {
    let info = card.get_property(prop_handle).unwrap();
    if info.name().to_str().unwrap() == "type" {
        let plane_type = match raw_value as u32 {
            drm_ffi::DRM_PLANE_TYPE_PRIMARY => PlaneType::Primary,
            drm_ffi::DRM_PLANE_TYPE_OVERLAY => PlaneType::Overlay,
            drm_ffi::DRM_PLANE_TYPE_CURSOR  => PlaneType::Cursor,
            _ => continue,
        };
        println!("Plane {:?} is {:?}", plane_handle, plane_type);
    }
}

​
Listing All Planes

use drm::control::Device as ControlDevice;

// Enable universal planes to see overlay and cursor planes
card.set_client_capability(drm::ClientCapability::UniversalPlanes, true).unwrap();

for handle in card.plane_handles().unwrap() {
    let info = card.get_plane(handle).unwrap();

    println!(
        "Plane {:?}: crtc={:?}, fb={:?}, {} formats supported",
        handle,
        info.crtc(),
        info.framebuffer(),
        info.formats().len(),
    );
}

​
Plane Properties (Atomic Modesetting)

When using atomic modesetting, planes are configured entirely through properties. The most important standard plane properties are:
Property nameTypeDescription
FB_IDObject (Framebuffer)The framebuffer to display
CRTC_IDObject (CRTC)The CRTC to attach to
SRC_X, SRC_Y, SRC_W, SRC_HUnsignedRangeSource crop in Q16.16 fixed-point (pixels × 65536)
CRTC_X, CRTC_Y, CRTC_W, CRTC_HSignedRange / UnsignedRangeDestination rectangle on the CRTC in pixels
typeEnumPrimary, Overlay, or Cursor (read-only)
rotationBitmaskHardware rotation/reflection flags
zposUnsignedRangeZ-order within the CRTC’s plane stack
IN_FORMATSBlobSupported format/modifier combinations
Source coordinates (SRC_*) use Q16.16 fixed-point format. Multiply integer pixel values by 65536 before writing them to the atomic request. See AtomicModeReq for a complete example.

Build docs developers (and LLMs) love

Get started for freeTalk to us