Image Copy Capture
此协议允许客户端请求 compositor 将 output 和 toplevel 等图像源捕获到用户提交的 buffer 中。
警告！本文件中描述的协议目前处于测试阶段。可能会在更新接口版本的同时添加向后兼容的更改。向后不兼容的更改只能通过创建扩展的新主版本来进行。
此对象是一个 manager，提供从 source 开始捕获的 request。
create_session(session: new_id<ext_image_copy_capture_session_v1>, source: object<ext_image_capture_source_v1>, options: uint<ext_image_copy_capture_manager_v1.options>)
参数 | 类型 | 描述 |
|---|---|---|
| session | new_id<ext_image_copy_capture_session_v1> | |
| source | object<ext_image_capture_source_v1> | |
| options | uint<ext_image_copy_capture_manager_v1.options> |
为图像捕获 source 创建一个捕获 session。
如果设置了 paint_cursors 选项，光标应合并到捕获的 frame 上。如果未设置此标志，则光标不得合并到 frame 上。
如果 options 位段无效，则发送 invalid_option 协议错误。
create_pointer_cursor_session(session: new_id<ext_image_copy_capture_cursor_session_v1>, source: object<ext_image_capture_source_v1>, pointer: object<wl_pointer>)
参数 | 类型 | 描述 |
|---|---|---|
| session | new_id<ext_image_copy_capture_cursor_session_v1> | |
| source | object<ext_image_capture_source_v1> | |
| pointer | object<wl_pointer> |
为图像捕获 source 的指针创建一个光标捕获 session。
destroy()
销毁 manager 对象。
通过此接口创建的其他对象不受影响。
options { paint_cursors }
参数 | 值 | 描述 |
|---|---|---|
| paint_cursors | 1 | 将光标绘制到捕获的帧上 |
此对象表示一个活动的图像复制捕获 session。
在创建捕获 session 后，compositor 将发出 buffer 约束事件，以告诉客户端支持从该 session 读取的 buffer 类型和格式。只要 buffer 约束事件发生变化，compositor 就可以重新发送它们。
为了通告 buffer 约束，compositor 必须以不特定的顺序发送：零个或多个 shm_format 和 dmabuf_format 事件、零个或一个 dmabuf_device 事件，以及恰好一个 buffer_size 事件。然后 compositor 必须发送 done 事件。
当客户端收到所有 buffer 约束后，它可以相应地创建一个 buffer，使用 attach_buffer request 将其附加到捕获 session，使用 damage_buffer request 设置 buffer 损坏区域，然后发送 capture request。
create_frame(frame: new_id<ext_image_copy_capture_frame_v1>)
参数 | 类型 | 描述 |
|---|---|---|
| frame | new_id<ext_image_copy_capture_frame_v1> |
为此 session 创建一个捕获 frame。
任何时候对于给定的 session 最多只能存在一个 frame 对象。如果客户端在先前的 frame 对象被销毁之前发送 create_frame request，则会引发 duplicate_frame 协议错误。
destroy()
销毁 session。此 request 可由客户端随时发送。
此 request 不影响由此对象创建的 ext_image_copy_capture_frame_v1 对象。
提供源图像在 buffer 像素坐标中的尺寸。
客户端必须附加匹配此大小的 buffer。
shm_format(format: uint<wl_shm.format>)
参数 | 类型 | 描述 |
|---|---|---|
| format | uint<wl_shm.format> | shm format |
提供必须用于共享内存 buffer 的格式。
此 event 可能会多次发出，在这种情况下，客户端可以选择任何给定的格式。
dmabuf_device(device: array)
参数 | 类型 | 描述 |
|---|---|---|
| device | array | device dev_t value |
此 event 通告必须在之上分配 dma-buf buffer 的设备。
通常设备是一个 DRM 节点。DRM 节点类型（主要 vs. 渲染）未指定。客户端不得依赖 compositor 发送特定的节点类型。客户端不能通过比较 dev_t 值来检查两个设备是否相等。
提供必须用于 dma-buf buffer 的格式。
客户端可以选择在 64 位无符号整数数组中通告的任何修饰符。
此 event 可能会多次发出，在这种情况下，客户端可以选择任何给定的格式。
done()
当所有 buffer 约束事件都已发送后，发送此 event。
无论是发送初始约束还是更新，compositor 必须始终以此 event 结束一批 buffer 约束事件。
stopped()
此 event 表示捕获 session 已停止且不再可用。这可能发生在多种情况下，例如底层 source 被销毁、用户决定结束图像捕获或发生不可恢复的运行时错误。
客户端收到此 event 后应销毁 session。
error { duplicate_frame }
参数 | 值 | 描述 |
|---|---|---|
| duplicate_frame | 1 | 在销毁前一个 frame 之前发送了 create_frame |
此对象表示一个图像捕获 frame。
客户端应附加一个 buffer、损坏该 buffer，然后发送 capture request。
如果捕获成功，compositor 必须发送 frame 元数据（transform、damage、presentation_time，顺序不限），后跟 ready event。
如果捕获失败，compositor 必须发送 failed event。
将 buffer 附加到 session。
wl_buffer.release request 未使用。
新 buffer 替换任何先前附加的 buffer。
此 request 不得在捕获之后发送，否则将引发 already_captured 协议错误。
对下一个要捕获的 buffer 应用损坏。此 request 可以多次发送以描述一个区域。
客户端指示自上次捕获此 wl_buffer 以来的累积损坏。在捕获期间，compositor 将使用客户端传递的区域和 ext_image_copy_capture_frame_v1.damage 通告的区域的并集来更新 buffer。
当 wl_buffer 首次被捕获时，或者客户端不跟踪损坏时，客户端必须损坏整个 buffer。
这是为了优化目的。compositor 可以使用此信息来减少复制。
这些坐标源自 buffer 的左上角。
如果 x 或 y 严格为负数，或者 width 或 height 为负数或零，将引发 invalid_buffer_damage 协议错误。
此 request 不得在捕获之后发送，否则将引发 already_captured 协议错误。
capture()
捕获一个 frame。
除非这是此 session 中首次成功捕获的 frame，否则 compositor 可以在执行复制之前等待不确定的时间，等待 source 内容发生变化。
此 request 只能发送一次，否则将引发 already_captured 协议错误。在发送此 request 之前必须附加 buffer，否则将引发 no_buffer 协议错误。
transform(transform: uint<wl_output.transform>)
参数 | 类型 | 描述 |
|---|---|---|
| transform | uint<wl_output.transform> |
此 event 在 ready event 之前发送，包含 compositor 应用到 buffer 内容的变换。
此 event 在 ready event 之前发送。它可以多次生成以描述一个区域。
session 中首次捕获的 frame 将始终携带完整损坏。后续 frame 的损坏区域描述了自上次 ready event 以来 buffer 的哪些部分发生了变化。
这些坐标源自 buffer 的左上角。
参数 | 类型 | 描述 |
|---|---|---|
| tv_sec_hi | uint | high 32 bits of the seconds part of the timestamp |
| tv_sec_lo | uint | low 32 bits of the seconds part of the timestamp |
| tv_nsec | uint | nanoseconds part of the timestamp |
此 event 指示 frame 在系统单调时间中呈现到 output 的时间。此 event 在 ready event 之前发送。
时间戳以 tv_sec_hi、tv_sec_lo、tv_nsec 三元组表示，每个分量都是无符号 32 位值。整秒在 tv_sec 中，它是由 tv_sec_hi 和 tv_sec_lo 组合而成的 64 位值，额外的小数部分在 tv_nsec 中以纳秒为单位。因此，对于有效时间戳，tv_nsec 必须在 [0, 999999999] 范围内。
ready()
在复制 frame 时立即调用，指示其可供读取。
在此 event 之后，客户端可以重复使用该 buffer。
收到此 event 后，客户端必须销毁该对象。
failed(reason: uint<ext_image_copy_capture_frame_v1.failure_reason>)
此 event 表示尝试的 frame 复制已失败。
收到此 event 后，客户端必须销毁该对象。
error { no_buffer, invalid_buffer_damage, already_captured }
参数 | 值 | 描述 |
|---|---|---|
| no_buffer | 1 | 未附加 buffer 就发送了 capture |
| invalid_buffer_damage | 2 | 无效的 buffer 损坏区域 |
| already_captured | 3 | capture 请求已发送 |
failure_reason { unknown, buffer_constraints, stopped }
参数 | 值 | 描述 |
|---|---|---|
| unknown | 0 | 未知的运行时错误 发生了未指定的运行时错误。客户端可以重试。 |
| buffer_constraints | 1 | buffer 约束不匹配 客户端提交的 buffer 不匹配最新的 session 约束。客户端应重新分配其 buffer 并重试。 |
| stopped | 2 | session 不再可用 session 已停止。参见 ext_image_copy_capture_session_v1.stopped。 |
此对象表示一个光标捕获 session。它通过光标特定的元数据扩展了基本捕获 session。
destroy()
销毁 session。此 request 可由客户端随时发送。
此 request 不影响由此对象创建的 ext_image_copy_capture_frame_v1 对象。
get_capture_session(session: new_id<ext_image_copy_capture_session_v1>)
参数 | 类型 | 描述 |
|---|---|---|
| session | new_id<ext_image_copy_capture_session_v1> |
获取此光标 session 的图像复制捕获 session。
该 session 将生成光标图像的 frame。当光标离开捕获区域时，compositor 可以暂停该 session。
此 request 不得发送超过一次，否则将引发 duplicate_session 协议错误。
enter()
当光标进入捕获区域时发送。当且仅当光标进入该区域时，应在 "position" 和 "hotspot" event 之前生成此 event。
当光标图像与捕获区域相交时，光标进入捕获区域。注意，这与 wl_pointer.enter 等不同。
leave()
当光标离开捕获区域时发送。在光标再次进入捕获区域之前，不会为光标生成 "position" 或 "hotspot" event。
图像捕获 source 之外的光标不会被捕获，并且不会为它们生成 event。
给定的位置是光标的 hotspot 位置，它是相对于主 buffer 左上角的已变换 buffer 像素坐标。坐标可以是负数或大于主 buffer 大小。
hotspot 描述了光标图像与输入设备位置之间的偏移量。
给定的坐标是 hotspot 在 buffer 坐标中相对于原点的偏移量。
客户端不应立即应用 hotspot：hotspot 会在收到下一个 ext_image_copy_capture_frame_v1.ready event 时生效。
Compositor 可能会延迟此 event，直到客户端捕获新 frame。
error { duplicate_session }
参数 | 值 | 描述 |
|---|---|---|
| duplicate_session | 1 | get_capture_session 被发送了两次 |
合成器支持
Cage  | COSMIC  | GameScope  | Hyprland  | Jay | KWin  | Labwc  | Louvre  | Mir  | Muffin  | Mutter  | niri  | phoc  | river  | Sway  | Treeland  | Wayfire  | Weston  | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ext_image_copy_capture_manager_v1 | x | 1 | x | x | 1 | x | 1 | x | 1 | x | x | x | 1 | x | 1 | 1 | x | x |
Copyright
Copyright © 2021-2023 Andri Yngvason Copyright © 2024 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.