Module drm 

Available on crate feature backend_drm only.

This module represents abstraction on top the linux direct rendering manager api (drm).

DrmDevice

A device exposes certain properties, which are directly derived from the device as perceived by the direct rendering manager api (drm). These resources consists out of:

• connectors represents a port on your computer, possibly with a connected monitor, TV, capture card, etc.
• encoder encodes the data of connected crtcs into a video signal for a fixed set of connectors. E.g. you might have an analog encoder based on a DAG for VGA ports, but another one for digital ones. Also not every encoder might be connected to every crtc.
• framebuffer represents a buffer you may display, see DrmSurface below.
• plane adds another layer on top of the crtcs, which allow us to layer multiple images on top of each other more efficiently then by combining the rendered images in the rendering phase, e.g. via OpenGL. Planes have to be explicitly used by the user to be useful. Every device has at least one primary plane used to display an image to the whole crtc. Additionally cursor and overlay planes may be present. Cursor planes are usually very restricted in size and meant to be used for hardware cursors, while overlay planes may be used for performance reasons to display any overlay on top of the image, e.g. the top-most windows. Overlay planes may have a bunch of weird limitation, that you cannot query, e.g. only working on round pixel coordinates. You code should never rely on a fixed set of overlay planes, but always have a fallback solution in place.
• crtcs represent scanout engines of the device pointer to one framebuffer. Their responsibility is to read the data of the framebuffer and export it into an “Encoder”. The number of crtc’s represent the number of independent output devices the hardware may handle.

On modern graphic cards it is better to think about the crtc as some sort of rendering engine. You can only have so many different pictures, you may display, as you have crtcs, but a single image may be put onto multiple displays.

The main functionality of a Device in smithay is to give access to all these properties for the user to choose an appropriate rendering configuration. What that means is defined by the requirements and constraints documented in the specific device implementations. The second functionality is the creation of a Surface. Surface creation requires a crtc (which cannot be the same as another existing Surface’s crtc), a plane, as well as a Mode and a set of connectors.

smithay does not make sure that connectors are not already in use by another Surface. Overlapping connector-Sets may be an error or result in undefined rendering behavior depending on the Surface implementation.

DrmSurface

A surface is a part of a Device that may output a picture to a number of connectors. It pumps pictures of buffers to outputs.

On surface creation a matching encoder for your connector is automatically selected, if one exists(!), which means you still need to check your configuration beforehand, even if you do not need to provide an encoder.

A surface consists of one crtc that is rendered to by the user. This is fixed for the Surfaces lifetime and cannot be changed. A surface also always needs at least one connector to output the resulting image to as well as a Mode that is valid for the given connectors.

The state of a Surface is double-buffered, meaning all operations that chance the set of connectors or their Mode are stored and only applied on the next commit. Surfaces do their best to validate these changes, if possible.

A commit/page_flip may be triggered to apply the pending state.

Rendering

The drm infrastructure makes no assumptions about the used renderer and does not interface with them directly. It just provides a way to create framebuffers from various buffer types (mainly DumbBuffers and hardware-backed gbm BufferObjects).

Buffer management and details about the various types can be found in the allocator-Module and rendering abstractions, which can target these buffers can be found in the renderer-Module.

Hardware composition

The DrmCompositor provides a simplified way to utilize drm planes for using hardware composition. See the compositor module docs for more information on that topic.

DrmNode

A drm node refers to a drm device and the capabilities that may be performed using the node. Generally DrmNode is primarily used by clients (such as the output backends) which need to allocate buffers for use in X11 or Wayland. If you need to do mode setting, you should use DrmDevice instead.

Modules

compositorwayland_frontend and backend_gbm

Composition for Elements using drm planes

dumb

Utilities to attach framebuffer::Handles to dumb buffers

exporter

Trait and data structures to describe types, that can be exported to a drm framebuffer

gbmbackend_gbm

Utilities to attach framebuffer::Handles to gbm backed buffers

outputwayland_frontend and backend_gbm

Device-wide synchronization helpers

Structs

DrmAccessError

DRM access error

DrmDevice

An open drm device

DrmDeviceFd

Ref-counted file descriptor of an open drm device

DrmDeviceNotifier

Even source of DrmDevice

DrmEventMetadata

Timing metadata for page-flip events

DrmNode

A node which refers to a DRM device.

DrmSurface

An open crtc + plane combination that can be used for scan-out

GbmBufferedSurfacebackend_gbm

Simplified abstraction of a swapchain for gbm-buffers displayed on a DrmSurface.

PlaneClaim

A claim of a plane

PlaneConfig

Configuration for a single plane

PlaneDamageClips

Helper for FB_DAMAGE_CLIPS

PlaneInfo

Info about a single plane

PlaneState

State of a single plane

Planes

A set of planes as supported by a crtc

WeakDrmDeviceFd

Weak variant of DrmDeviceFd

Enums

CreateDrmNodeError

An error that may occur when creating a DrmNode from a file descriptor.

DrmError

Errors thrown by the DrmDevice and the DrmSurface.

DrmEvent

Events that can be generated by a DrmDevice

DrmEventTime

Either a realtime or monotonic timestamp

GbmBufferedSurfaceErrorbackend_gbm

Errors thrown by a GbmBufferedSurface

NodeType

A type of node

VrrSupport

VRR support state

Traits

Framebuffer

Common framebuffer operations