MirageLinuxDisplay — Linux 桌面显示集成层

MirageWallpaper 的 Linux 显示集成层

让 MirageWallpaper 的帧，在 Linux 桌面上醒来。

基于 mirage-display-v1 协议、稳定的 C ABI 消费/生产库与路由核心， MirageLinuxDisplay 让渲染器把 DMA-BUF 帧交给嵌入式 broker，再由 KDE Plasma 等桌面环境自有的壁纸表面呈现。像素数据全程留在 GPU 显存，从不经过 broker 拷贝。

阅读文档浏览源码

MirageLinuxDisplay 架构数据流图 — **协议驱动 · 零拷贝 · DE 自有的壁纸表面**mirage-display-v1 · DMA-BUF · 显式同步

核心能力

三个组件，一条协议。

PROTOCOL

协议驱动

mirage-display-v1 协议已经冻结，覆盖握手、输出注册、缓冲池绑定、帧与同步、配置、指针输入与错误处理等全部环节，以 protocol/mirage_display_v1.xml 为权威定义。

BROKER

零拷贝路由

嵌入式 md_broker 以权限 0600 的 Unix 域套接字提供服务，通过 SO_PEERCRED 校验对端是否同 UID，再按稳定输出标识把单个生产者与多个桌面消费者匹配起来，只转发报文与文件描述符。

C ABI

消费 / 生产双库

核心实现使用 C++20，但 include/ 只导出 C11 与 C++ 都能用的稳定 C ABI，兼容 Qt、GObject 与 Rust FFI，公开 DTO 统一采用八字节定长布局。

ROUTING CORE

一个 broker，稳定调度所有输出。

broker 负责稳定的发现与多输出路由，渲染器或桌面壳层重启后也能自动恢复连接；稳定输出标识取代了过去的屏幕索引约定。

同 UID 校验
格式与修饰符协商
多消费者同步扇出
缓冲池代际管理
断连自动重连

$ ls -l $XDG_RUNTIME_DIR/mirage-wallpaper/
drwx------ mirage
srwx------ display-v1.sock    # AF_UNIX · SOCK_SEQPACKET · 0600

$ ss -xlp | grep display-v1
u_seq ESTAB 0 0 display-v1.sock
  peer: pid=… uid=1000        # SO_PEERCRED 同 UID

GPU HELPERS

EGL 与 Vulkan，两条导入路径。

EGL 路径借助 EGL_EXT_image_dma_buf_import 与原生 fence 完成同步；Vulkan 路径通过 external memory FD 与 DRM 修饰符导入，遇到无法直接采样的格式时，用同设备 relay/blit 回退到宿主可采样的图像。

GPU 助手指南

EGL    EGL_EXT_image_dma_buf_import
        EGL_LINUX_DMA_BUF_EXT + 原生 fence
Vulkan  VK_KHR_external_memory_fd
        DRM 修饰符枚举 + relay/blit 回退
Sync    DRM syncobj 扇出 · sync_file 桥接

KDE PLASMA

一个壁纸包，X11 / Wayland 通用。

作为 Plasma 6 的 Plasma/Wallpaper 壁纸包，它以 Qt Quick 显示项提供 EGL 与 Vulkan 双后端，支持多显示器、旋转、缩放、指针转发与窗口状态；工作区信息来自 Plasma/KWin 接口。

KDE 适配器指南

$ kpackagetool6 -t Plasma/Wallpaper \
    -i mirage-wallpaper-0.2.0.zip

C ABI

非阻塞握手，回调驱动。

消费端与生产端库都提供非阻塞握手、完整的缓冲池生命周期、帧接收与显式同步；帧与同步文件描述符的所有权转移有明确约定，断连时保证恰好关闭一次。

消费库指南

md_display_t* d = md_display_new(&cb);
md_display_connect(d, sock, "kde",
                   "0.2.0", &output, &caps, 5000);
for (;;) md_display_dispatch(d);

渲染器 → 生产者
  → MirageQt 内嵌 broker
  → libmirage-display 消费者
  → DE 壁纸 / 背景 API
  → 合成器或 X 服务器

CLEAR BOUNDARY

桌面，交给桌面环境自己呈现。

本项目不会创建、也不会管理裸的 X11 桌面或根窗口。无论 X11 还是 Wayland，最终呈现都发生在桌面环境自有的集成点里——最后一跳永远属于桌面环境。

了解边界

OPEN & FREE

协议冻结，ABI 稳定。

mirage-display-v1 的报文语义、描述符所有权与回调顺序保持稳定；0.2.0 把跨语言的 FD、超时与状态计数统一为定宽类型，并为公开 DTO 固定了八字节布局。

ABI 与兼容性协议参考浏览源码

mirage-display-v1 · major=1 minor=0
magic "MDP1" · 24 字节报文头
小端 · 定宽类型 · 显式同步
C ABI：C11 / C++ / Rust FFI

让 Linux 桌面再多一个维度。

面向 KDE Plasma（X11 / Wayland），GNOME 与 layer-shell 正在规划中。

阅读文档浏览源码