AtomUI/docs/modules/native/linux.md

AtomUI.Native Linux 平台 API

范围

AtomUI 在 Linux 上有两条完全不同的窗口后端路径：

后端	Avalonia 包	原生对象	AtomUI 可使用的能力
X11 / XWayland	Avalonia.X11	IPlatformHandle，descriptor 为 XID	Xlib 初始几何、_GTK_FRAME_EXTENTS、XCB SHAPE input region
原生 Wayland	Avalonia.Wayland	IWindowImpl.Handle == null	xdg-shell move/resize、CSD/SSD、surface geometry；无公开 input-region API

不得只用 OperatingSystem.IsLinux() 决定调用 X11 API。所有 Xlib/XCB 路径还必须验证窗口后端为 X11；原生 Wayland、Linux framebuffer 和 headless 后端都不是 X11。

本文以 AtomUI 当前公开的平台契约、后端隔离规则和验证条件为准。Avalonia 内部类型仅用于解释集成边界， 不能作为 AtomUI 可直接调用的稳定 API。

X11 能力

初始窗口几何

WindowExtensions.ConfigureLinuxInitialWindowGeometry() 将 Avalonia DIP 尺寸转成 device pixel， 再调用 WindowUtilsLinux.ConfigureInitialWindowGeometry()：

1. XOpenDisplay() 打开独立 Xlib 连接。
2. XSetWMNormalHints() 写入 position、size、min/max size 和 resize increment。
3. XMoveResizeWindow() 在 map 前设置窗口位置和大小。
4. XFlush() 后关闭该次 Xlib 连接。

该逻辑依赖 XID 和全局屏幕坐标，只能由 X11WindowChromeManager 调用。Wayland surface 没有全局位置， Avalonia.Wayland.WindowImpl.Move(PixelPoint) 明确是 no-op。

CSD frame extents

WindowExtensions.SetLinuxX11CsdFrameExtents() 先验证 platform handle descriptor 为 XID，然后由 WindowUtilsLinux.SetX11CsdFrameExtents() 写入 _GTK_FRAME_EXTENTS。

属性格式为四个 32-bit CARDINAL，顺序是 left, right, top, bottom，单位为 device pixel。AtomUI 在 normal 状态写入阴影 extents；最大化和全屏写入全零，避免 Mutter/KWin 继续按旧阴影范围做放置和吸附。

SHAPE input region

WindowExtensions.SetWindowInputRectangle() / ResetWindowInputRegion() 用 XCB SHAPE 的 XCB_SHAPE_SK_INPUT 把输入区限制为一个矩形，目的是让视觉阴影区域的点击穿透到下方窗口。 Native 层只接收 device pixel 坐标并执行 input-region 请求，不决定 shadow 厚度、resize band 或订阅策略。

当前实现的真实生命周期：

1. XcbConnectionHolder 懒创建一条进程级独立 XCB 连接。
2. 首次初始化时查询并缓存 SHAPE 扩展是否可用。
3. 所有请求在 XcbConnectionHolder.SyncRoot 下串行执行。
4. xcb_shape_rectangles_checked() 替换 input region，随后检查请求并 flush。
5. 该连接在进程生命周期内复用；不是每次调用都 connect/disconnect。

X11WindowChromeManager 负责高层 shadow click-through 策略。它监听 Opened、Bounds、 WindowDecorationMargin、WindowState、TransparencyLevelHint、CanResize、FrameShadowThickness 和 IsCsdEnabled，按 RenderScaling 把 DIP 转成 device pixel，并在普通状态下只保留最多 10 DIP 的 resize band。最大化或全屏时 input region 恢复为整个 surface。

这不是“整窗忽略鼠标”的 API。Linux 版本的 SetWindowIgnoreMouseEventsLinux()、 IsWindowIgnoreMouseEventsLinux()、xcb_get_geometry() 和 shape-query 旧实现已经删除；文档和新代码都 不得继续引用这些成员。

Wayland 能力与线程模型

Avalonia Wayland 后端使用专用 AvaloniaWayland worker 线程：

UI thread WindowImpl
  -> WXdgTopLevelProxy
  -> WaylandWorkerClient.Marshaller
  -> PostWithCommit / PostOob
  -> worker-thread WSurface / WlSurface

源码中的关键约束：

• WaylandWorkerClient.CreateTopLevelHandle() 只向 UI 线程暴露 WXdgTopLevelProxy，注释明确说明真实 WXdgTopLevel 是 worker-thread state。
• 普通 surface 状态由 PostWithCommit 排队，与 compositor commit 保持顺序；move/resize 等需要输入 serial 的请求使用 OOB 路径。
• WSurface.OnBeforeNewBufferAttached() 在 attach/commit 前统一应用 frame callback、ack configure、 window geometry、viewport 和 buffer scale。
• WindowImpl.SetShadowExtents() 通过 proxy 更新 persistent surface；WSurface 再根据 shadow extents 调用 xdg_surface.set_window_geometry。

Wayland 核心协议虽然有 wl_surface.set_input_region，但当前公开框架 API 不能表达该能力。AtomUI 当前 AtomUI.Native/Linux/WaylandWindowReflectionExtensions.cs 从私有 proxy 中取出真实 target，并由 WaylandWindowUtils 直接调用 NWayland。这绕过了 worker marshalling 和重连模型，只能作为当前技术债记录， 不能视为线程安全或受 Avalonia 支持的 Native 扩展点。后续正确实现应进入 Avalonia persistent surface/proxy，并通过 PostWithCommit 下发。

Wayland CSD/SSD

Wayland 的 NeedsManagedDecorations 来自 xdg-decoration 协商：

• Client-side mode：请求 TitleBar | Border | Shadow | ResizeGrips。
• Server-side mode：NeedsManagedDecorations=false，由 compositor 提供 SSD。
• 协商结果变化时触发 DrawnDecorationsRequestChanged。

WindowDecorations 在 Wayland 上不是可逆的 CSD/SSD toggle。当前后端的 SetWindowDecorations(None/TitleBar) 会设置 _csdSticky=true 并销毁 decoration object，之后设置 Full 也不会恢复 SSD。因此，AtomUI 不能在 IsCsdEnabled=False 时无条件设置 WindowDecorations=None；这会把刚协商出的 SSD 立即永久切回 CSD。

依赖和边界

AtomUI.Native 与 Avalonia.Wayland 共享 NWayland 类型，必须在依赖升级时验证最终解析版本和 ABI 兼容性。 NWayland 因而会进入所有引用 AtomUI.Native 的依赖图，包括 Browser 的共享项目闭包。Browser 项目 目前通过内部 WASM item 过滤桌面 assembly，这能消除已知 P/Invoke collector warning，但不能消除 restore 图中的桌面依赖，也不是理想的模块边界。

长期结构应把 X11、Wayland、Win32、macOS 后端能力放到可选平台 assembly，避免 AtomUI.Desktop.Controls/Browser 为单个平台实现携带所有桌面后端和协议依赖。平台 manager 负责 Avalonia 控件生命周期和状态机；AtomUI.Native 只负责已经确定后端之后的原生调用，不负责主题、 reflection discovery 或窗口策略。

实现与升级检查入口

AtomUI

• src/AtomUI.Native/Linux/WindowUtils.Interop.cs
• src/AtomUI.Native/Linux/WindowUtils.Linux.cs
• src/AtomUI.Native/Linux/XcbConnectionHolder.cs
• src/AtomUI.Native/Linux/WaylandWindowReflectionExtensions.cs
• src/AtomUI.Native/Linux/WaylandWindowUtils.cs
• src/AtomUI.Native/WindowExtensions.cs
• src/AtomUI.Desktop.Controls/Window/Chrome/X11WindowChromeManager.cs
• src/AtomUI.Desktop.Controls/Window/Chrome/WaylandWindowChromeManager.cs

框架集成验证项

• Wayland 窗口只向 UI 线程暴露 proxy，真实协议对象留在 worker 线程。
• 普通 surface 状态通过 commit 队列提交，不能从 UI 线程直接操作协议对象。
• CSD/SSD 协商、shadow extents 与 window geometry 保持同一状态传播链。
• X11 路径继续以 XID descriptor 为门槛，不能退化为 Linux OS 判断。

框架升级时应针对当前依赖重新验证这些行为，不在长期文档中固化外部文件路径、行号或源码快照。