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 CRTC (CRT Controller) is the core scanout engine in DRM. It reads pixel data from a primary plane, applies display timing (the Mode), and drives the signal through an encoder to a connector. Without an active CRTC the display goes dark — enabling one performs what the kernel calls a “modeset”. Each CRTC has at least one associated primary plane. Additional overlay and cursor planes can be layered on top for hardware compositing. The CRTC also owns a gamma lookup table for colour correction. CRTCs are enumerated through Device::resource_handles() and inspected with Device::get_crtc().

​
crtc::Handle

An opaque, copy-cheap handle to a CRTC resource. Internally a NonZeroU32 wrapped with repr(transparent). Implements ResourceHandle with FFI_TYPE = DRM_MODE_OBJECT_CRTC. 
let res = card.resource_handles().unwrap();
let crtc_handles: &[crtc::Handle] = res.crtcs();

​
crtc::Info

Returned by Device::get_crtc(). Describes the current hardware state of a CRTC.
MethodReturn typeDescription
handle()HandleThe CRTC’s own handle
position()(u32, u32)(x, y) pixel offset within the display plane (used for multi-monitor positioning)
mode()Option<Mode>The active display timing mode, or None if the CRTC is disabled
framebuffer()Option<framebuffer::Handle>The framebuffer currently being scanned out, or None if disabled
gamma_length()u32Number of entries in the gamma lookup table (use with get_gamma / set_gamma)
Info also implements Display, formatting as "CRTC <id>".

​
Mode

Mode is a display timing structure (repr(transparent) over the kernel’s drm_mode_modeinfo). It is returned by connector::Info::modes() and stored in crtc::Info.
MethodReturn typeDescription
name()&CStrMode name string (e.g. "1920x1080")
clock()u32Pixel clock in kHz
size()(u16, u16)Active resolution (width, height) in pixels
hsync()(u16, u16, u16)Horizontal sync start, end, and total
vsync()(u16, u16, u16)Vertical sync start, end, and total
hskew()u16Horizontal skew
vscan()u16Vertical scan multiplier
vrefresh()u32Vertical refresh rate in Hz
mode_type()ModeTypeFlagsWhether the mode is preferred, user-defined, or driver-reported
flags()ModeFlagsSync polarity, interlace, doublescan, stereo, and other flags

​
CrtcListFilter

A bitmask returned by encoder::Info::possible_crtcs() and plane::Info::possible_crtcs(). Use with ResourceHandles::filter_crtcs to obtain the subset of CRTCs compatible with a given encoder or plane. 
let enc_info = card.get_encoder(enc_handle).unwrap();
let compatible_crtcs = res.filter_crtcs(enc_info.possible_crtcs());

​
Listing Active CRTCs

use drm::control::Device as ControlDevice;

let res = card.resource_handles().unwrap();

for &handle in res.crtcs() {
    let info = card.get_crtc(handle).unwrap();

    match info.mode() {
        Some(mode) => {
            println!(
                "CRTC {:?}: {}x{} @ {}Hz, gamma table size {}",
                handle,
                mode.size().0,
                mode.size().1,
                mode.vrefresh(),
                info.gamma_length(),
            );
        }
        None => {
            println!("CRTC {:?}: disabled", handle);
        }
    }
}

​
Finding a CRTC for a Connector

To set up a display, you need to find a CRTC that is compatible with the connector’s encoder: 
use drm::control::Device as ControlDevice;

let res = card.resource_handles().unwrap();
let con_info = card.get_connector(con_handle, true).unwrap();

// Walk compatible encoders, then find a CRTC each supports
let crtc = con_info.encoders().iter().find_map(|&enc_handle| {
    let enc_info = card.get_encoder(enc_handle).unwrap();
    res.filter_crtcs(enc_info.possible_crtcs()).into_iter().next()
});

if let Some(crtc_handle) = crtc {
    println!("Will use CRTC {:?}", crtc_handle);
}
Prefer atomic_commit over the legacy set_crtc API for new code. Atomic commits are validated atomically before being applied, and are required for features such as format modifiers, HDR metadata, and variable refresh rate (VRR).

Build docs developers (and LLMs) love

Get started for freeTalk to us