Xwayland shell
本协议添加了一个 xwayland_surface 角色，允许 Xwayland 服务器将 X11 窗口关联到一个 wl_surface。
在本协议出现之前，这通常通过 Xwayland 服务器在 X 窗口上使用具有 WL_SURFACE_ID atom 的 client message 提供 wl_surface 的 resource id 来完成。 这种做法存在问题，因为如果与窗口的 WL_SURFACE_ID 关联的 wl_surface 在 compositor 处理 client message 之前被销毁，并且另一个 surface（或其他对象）由于回收而占用了其 id，则可能发生竞争条件。
本协议通过将“将 X11 窗口关联到 wl_surface” 的步骤移动到 Wayland 端来解决该问题，这意味着该关联过程不会与 wl_surface 的资源生命周期发生不同步。
本协议通过在 wl_surface（通过 xwayland_surface_v1 的 set_serial 方法）和 X11 窗口（通过 `WL_SURFACE_SERIAL` client message）上设置完全唯一的非零单调递增序列号 (serial number)，可用于关联它们并同步这两个时间线，从而避免在另一侧重复该竞争问题。
本文档中的关键字“must”、“must not”、“required”、“shall”、“shall not”、“should”、“should not”、“recommended”、“may”和“optional”应按照 IETF RFC 2119 中的描述进行解释。
警告！此文件中描述的协议目前处于测试阶段。可以随着相应的接口版本号增加而添加向后兼容的更改。向后不兼容的更改只能通过创建该扩展的一个新的主要版本来进行。
xwayland_shell_v1 是一个单例全局对象，提供了为给定的 wl_surface 创建 xwayland_surface_v1 对象的功能。
此接口旨在由 Xwayland 服务器绑定。
compositor 不得允许除 Xwayland 之外的 client 绑定此接口。compositor 应该从其他 client 的 wl_registry 中隐藏这个全局对象。 不被 compositor 认为是 Xwayland 服务器的 client 试图绑定此接口将导致实现定义的错误 (implementation-defined error)。
已绑定此接口的 Xwayland 服务器不得在窗口上设置 `WL_SURFACE_ID` atom。
destroy()
销毁 xwayland_shell_v1 对象。
通过此接口创建的子对象不受影响。
get_xwayland_surface(id: new_id<xwayland_surface_v1>, surface: object<wl_surface>)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<xwayland_surface_v1> | |
| surface | object<wl_surface> |
为给定的 wl_surface 对象创建一个 xwayland_surface_v1 接口，并为其分配 xwayland_surface 角色。
客户端多次调用此方法对同一个 wl_surface 对象是违法的。 如果给定的 wl_surface 已经有了另一个角色，这也会引发错误。
Xwayland 关联 wl_surface 到 X11 窗口的接口。
通过此接口，Xwayland 关联的 wl_surface 与普通的 wl_surface 没有任何不同，在没有收到进一步状态改变时，除非使用其他扩展（如 wp_tearing_control_v1）或者有 compositor 特定保证存在，不应认为它是隐式映射的。
参数 | 类型 | 描述 |
|---|---|---|
| serial_lo | uint | The lower 32-bits of the serial number associated with the X11 window |
| serial_hi | uint | The upper 32-bits of the serial number associated with the X11 window |
将单调递增的序列号与 wl_surface 相关联。
Xwayland 服务器可以通过在相关联的 X11 窗口上发送带有该序列号（由 64 位无符号整数构成的两个 32 位值，低 32 位优先）作为 `WL_SURFACE_SERIAL` client message 来将 wl_surface 关联到一个 X11 窗口。
时间线、起始点及产生此序列号的语义未定义，仅需保证所使用的序列号在一个 X11 客户端的生命周期内从不重复单次（64 位循环后可重复），并且必须为非零值。
destroy()
销毁 xwayland_surface_v1 对象。
与该对象相关联的 wl_surface 及其拥有的其他关联状态不再关联。 只要没有对 wl_surface 进行其他修改，此请求就不会引起任何进一步的改变。
error { already_associated, invalid_serial }
参数 | 值 | 描述 |
|---|---|---|
| already_associated | 0 | 给定的 wl_surface 已关联到 X11 窗口 |
| invalid_serial | 1 | 序列号无效 |
合成器支持
Cage  | COSMIC  | GameScope  | Hyprland  | Jay | KWin  | Labwc  | Louvre  | Mir  | Muffin  | Mutter  | niri  | phoc  | river  | Sway  | Treeland  | Wayfire  | Weston  | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| xwayland_shell_v1 | 1 | x | x | 1 | x | x | x | x | x | x | x | x | x | x | x | x | 1 | x |
Copyright
Copyright © 2022 Joshua Ashton
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.