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