DRM Plane 是 DRM / KMS 中的显示平面抽象，表示一层可被 显示控制器 在 Scanout 时读取、定位、缩放和混合的图像来源。
可以把 plane 理解成硬件显示管线里的“图层”，但它不是任意软件图层。它受硬件支持的像素格式、缩放倍率、带宽、叠加顺序和接口路由限制。
核心问题
现代显示输出经常不是只有一张全屏图像：
- 主 UI 需要全屏显示。
- 鼠标光标需要单独移动，不能每次都重绘全屏。
- 视频画面希望作为 overlay 直接叠在 UI 上，避免 GPU 重新合成。
- 某些面板或 SoC 显示控制器支持多个硬件图层，以降低功耗和带宽。
DRM Plane 让用户态合成器把不同图像资源交给显示控制器，由硬件在 scanout 时完成一部分定位、缩放、alpha 混合或颜色处理。
核心对象
| 对象 | 含义 | 工程关注点 |
|---|---|---|
| primary plane | 通常承载主画面的 plane | 一般和 CRTC 绑定，用于全屏 framebuffer |
| cursor plane | 专门显示光标的小 plane | 尺寸、格式和位置更新成本 |
| overlay plane | 叠加视频、相机或额外图层的 plane | 支持格式、scaler、z-order、带宽 |
| framebuffer | plane 读取的图像资源 | 帧缓冲、格式、stride、modifier |
| source rectangle | 从 framebuffer 中取哪块区域 | crop、亚像素坐标、fixed-point |
| CRTC rectangle | 放到屏幕上的哪个区域 | 位置、目标尺寸、是否需要 Scaler（硬件缩放器） |
| plane properties | plane 的可配置属性 | FB_ID、CRTC_ID、SRC_*、CRTC_*、zpos、alpha |
核心机制
一个 plane 的最小配置可以抽象成：
plane = {
framebuffer: FB_ID,
source: SRC_X, SRC_Y, SRC_W, SRC_H,
target: CRTC_X, CRTC_Y, CRTC_W, CRTC_H,
zpos: layer_order,
alpha: opacity
}FB_ID指向要显示的 framebuffer。SRC_*是源区域，决定从 framebuffer 中取哪块图像。CRTC_*是目标区域，决定图像放到屏幕坐标系的哪里。zpos决定多个 plane 的上下叠放顺序。alpha决定该 plane 参与混合时的透明度。
当 SRC_W / SRC_H 和 CRTC_W / CRTC_H 不一致时，该 plane 需要硬件 Scaler（硬件缩放器）。当多个 plane 同时启用时，KMS atomic check 会检查硬件是否能同时满足格式、带宽、缩放、混合和路由限制。
典型显示流程如下：
- 合成器为每个候选图层选择 framebuffer 和 plane。
- 对每个 plane 设置源区域、目标区域、透明度和 z-order。
- KMS atomic commit 先做 test-only 验证。
- 验证通过后，显示控制器在 scanout 时读取各 plane。
- 硬件按 plane 顺序完成缩放、颜色处理和混合。
- 最终像素流进入接口输出。
工程用途
- 用 overlay plane 显示视频或相机预览，减少 GPU 合成开销。
- 用 cursor plane 高效显示鼠标光标。
- 在嵌入式设备上用多 plane 分离 UI、视频和 OSD。
- 调试显示管线时通过
modetest查看 plane 支持的格式、属性和可用组合。
边界与常见坑
- Plane 不是 framebuffer：framebuffer 是图像数据描述；plane 是显示控制器读取和摆放这张图像的硬件层。
- Plane 不是窗口：窗口是桌面协议或合成器概念；plane 是底层硬件资源，数量通常很少。
- 有 overlay plane 不代表一定能用：格式、缩放比例、alpha、rotation、带宽和 CRTC 路由都可能让 atomic check 失败。
- Plane 分配是合成器策略：应用一般不能直接假设自己的窗口会得到硬件 plane。
- 缩放和裁剪要分清：
SRC_*控制取源，CRTC_*控制放置，两者尺寸差异才触发 scaler。