DRM synchronization object
此协议允许客户端请求 buffer 的显式同步。它与 Linux DRM 同步对象（synchronization object）框架绑定。
同步是指协调在 buffer 上执行的流水线操作。大多数 GPU 客户端会调度一个异步操作来向 buffer 渲染，然后立即将该 buffer 发送给 compositor 附加到 surface 上。
在隐式同步（implicit synchronization）中，确保渲染操作在 compositor 显示 buffer 之前完成是一个由内核或用户空间图形驱动程序处理的实现细节。
相比之下，在显式同步（explicit synchronization）中，DRM 同步对象的时间线点标志着异步操作的完成时间。在提交 buffer 时，客户端提供一个时间线点，compositor 在访问 buffer 之前将等待该点，并提供另一个时间线点，compositor 在不再需要为了 surface 提交而访问 buffer 内容时会发出信号。
Linux DRM 同步对象的文档见： https://dri.freedesktop.org/docs/drm/gpu/drm-mm.html#drm-sync-objects
警告！此文件中描述的协议目前处于测试阶段。向后兼容的更改可能会与相应的接口版本提升一起添加。向后不兼容的更改只能通过创建该扩展的新主版本来完成。
此全局对象是一个工厂接口，允许客户端在每个 surface 的基础上请求 buffer 的显式同步。
详情请参见 wp_linux_drm_syncobj_surface_v1。
get_surface(id: new_id<wp_linux_drm_syncobj_surface_v1>, surface: object<wl_surface>)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<wp_linux_drm_syncobj_surface_v1> | the new synchronization surface object id |
| surface | object<wl_surface> | the surface |
实例化给定 wl_surface 的接口扩展以提供显式同步。
如果给定的 wl_surface 已经关联了一个显式同步对象，则引发 surface_exists 协议错误。
像 EGL 或 Vulkan 这样的图形 API 本身会管理 buffer 队列和 wl_surface 提交，它们很可能在内部使用此扩展。如果客户端对一个 wl_surface 使用这样的 API，它不应在该 surface 上直接使用此扩展，以避免引发 surface_exists 协议错误。
import_timeline(id: new_id<wp_linux_drm_syncobj_timeline_v1>, fd: fd)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<wp_linux_drm_syncobj_timeline_v1> | |
| fd | fd | drm_syncobj file descriptor |
实例化一个与提供的 DRM 同步对象文件描述符绑定的 wp_linux_drm_syncobj_timeline_v1 对象。
fd 的所有权转移给了 compositor，compositor 会在完成读取后立即关闭它。
如果 fd 不能被导入为 DRM 同步对象时间线，则引发 invalid_timeline 协议错误。
error { surface_exists, invalid_timeline }
参数 | 值 | 描述 |
|---|---|---|
| surface_exists | 0 | 显式同步对象已经与表面关联 |
| invalid_timeline | 1 | 给定的对象不是一个有效的 DRM 同步对象时间线 |
此对象代表一个显式的从用户空间或由于等待特定硬件事件而发出信号的同步原语。
在此对象上分发的大多数请求和事件期望一个时间线点。这些点将时间线分割成一条单调递增的整数线。对于时间线上不按严格单调顺序请求的每个点，都会引发 invalid_point 协议错误。
对于给定的时间线点，当关联的异步操作已累积完成时，可以说对应的同步基元（synchronization primitive）已经“触发（signaled）”。
destroy()
销毁同步对象时间线。
所有在销毁时尚未“触发（signaled）”的 compositor 等待的引用的时间线点仍将被挂起，对于任何 compositor 承诺触发的引用的时间线点，一旦相关操作完成，仍然会触发。
此对象是 wp_linux_drm_syncobj_manager_v1 提供的关联 wl_surface 的扩展。
当此对象被销毁时，正在等待的 acquire 点以及 compositor 承诺触发的 release 点不会受到影响。
destroy()
销毁 surface 显式同步对象。
对表面状态没有任何改变。
set_acquire_point(timeline: object<wp_linux_drm_syncobj_timeline_v1>, point_hi: uint, point_lo: uint)
参数 | 类型 | 描述 |
|---|---|---|
| timeline | object<wp_linux_drm_syncobj_timeline_v1> | |
| point_hi | uint | high 32 bits of the point value |
| point_lo | uint | low 32 bits of the point value |
设置附加到此 surface 状态的用于获取 buffer 的时间线点。随后的 wl_surface.commit 请求将在等待对应于给定时间线的获取点之后再访问此 buffer。这允许客户端在 buffer 能够被读取前就提交，只要有相关的获取点在读取之前被“触发”。
如果在同一 surface 提交上已经设置了 acquire 时间线点，引发 conflicting_point 协议错误。
如果在此 wl_surface 已经接收到一个 wl_surface.commit 且 acquire 点尚未被等待（未“触发”）的情况下附加任何 buffer，引发 no_buffer 协议错误。
set_release_point(timeline: object<wp_linux_drm_syncobj_timeline_v1>, point_hi: uint, point_lo: uint)
参数 | 类型 | 描述 |
|---|---|---|
| timeline | object<wp_linux_drm_syncobj_timeline_v1> | |
| point_hi | uint | high 32 bits of the point value |
| point_lo | uint | low 32 bits of the point value |
设置附加到此 surface 状态的用于释放 buffer 的时间线点。随后的 wl_surface.commit 请求将使得当这个 buffer 不再由于此次提交而被使用时触发给定时间线的释放点。
对于给定的时间线点，只有当没有任何 compositor 侧的读取操作与此提交相关正在进行时，才会触发。
如果在此 wl_surface 已经接收到一个 wl_surface.commit 时设置了 release 时间线点，引发 conflicting_point 协议错误。
如果同一 surface 的一次提交中没有 buffer，且提供了 release 点，引发 no_buffer 协议错误。
error { no_surface, unsupported_buffer, no_buffer, no_acquire_point, no_release_point, conflicting_points }
参数 | 值 | 描述 |
|---|---|---|
| no_surface | 1 | 关联的 wl_surface 已被销毁 |
| unsupported_buffer | 2 | buffer 类型不支持显式同步 |
| no_buffer | 3 | 对于一个包含显式同步请求的提交，没有附加 buffer |
| no_acquire_point | 4 | 未设置 acquire 时间线点 |
| no_release_point | 5 | 未设置 release 时间线点 |
| conflicting_points | 6 | acquire 和 release 时间线点冲突 |
合成器支持
Cage  | COSMIC  | GameScope  | Hyprland  | Jay | KWin  | Labwc  | Louvre  | Mir  | Muffin  | Mutter  | niri  | phoc  | river  | Sway  | Treeland  | Wayfire  | Weston  | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| wp_linux_drm_syncobj_manager_v1 | x | 1 | 1 | 1 | 1 | 1 | 1 | x | x | x | 1 | x | x | 1 | 1 | x | x | x |
Copyright
Copyright 2016 The Chromium Authors. Copyright 2017 Intel Corporation Copyright 2018 Collabora, Ltd Copyright 2021 Simon Ser
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.