COSMIC screencopy v1
此协议允许客户端请求合成器将屏幕内容的一部分复制到客户端缓冲区。
警告！此文件中描述的协议是实验性的，可能会进行向后不兼容的更改。可能会添加向后兼容的更改，并相应地提升接口版本。向后不兼容的更改通过提升协议和接口名称中的版本号并重置接口版本来完成。一旦协议被宣布为稳定，协议和接口名称中的 'z' 前缀和版本号将被移除，接口版本号将被重置。
此对象是一个管理器，提供从源开始捕获的请求。
capture_output(session: new_id<zcosmic_screencopy_session_v1>, output: object<wl_output>, cursor: uint<zcosmic_screencopy_manager_v1.cursor_mode>)
参数 | 类型 | 描述 |
|---|---|---|
| session | new_id<zcosmic_screencopy_session_v1> | |
| output | object<wl_output> | |
| cursor | uint<zcosmic_screencopy_manager_v1.cursor_mode> |
为输出创建捕获会话。
请求合成器之前未通过 supported_cursor_mode 事件公布的光标模式是协议错误。
capture_workspace(session: new_id<zcosmic_screencopy_session_v1>, workspace: object<zcosmic_workspace_handle_v1>, output: object<wl_output>, cursor: uint<zcosmic_screencopy_manager_v1.cursor_mode>)
参数 | 类型 | 描述 |
|---|---|---|
| session | new_id<zcosmic_screencopy_session_v1> | |
| workspace | object<zcosmic_workspace_handle_v1> | |
| output | object<wl_output> | |
| cursor | uint<zcosmic_screencopy_manager_v1.cursor_mode> |
为整个工作区创建捕获会话。
必须提供一个之前通过 output_enter 事件与给定工作区关联的输出（请参阅 cosmic-workspace-unstable-v1）。
如果在发送此请求时提供的输出未与工作区关联，捕获将失败并显示 invalid_output，直到建立新的关联。
请求合成器之前未通过 supported_cursor_mode 事件公布的光标模式是协议错误。
capture_toplevel(session: new_id<zcosmic_screencopy_session_v1>, toplevel: object<zcosmic_toplevel_handle_v1>, cursor: uint<zcosmic_screencopy_manager_v1.cursor_mode>)
参数 | 类型 | 描述 |
|---|---|---|
| session | new_id<zcosmic_screencopy_session_v1> | |
| toplevel | object<zcosmic_toplevel_handle_v1> | |
| cursor | uint<zcosmic_screencopy_manager_v1.cursor_mode> |
为顶层窗口创建捕获会话。
请求合成器之前未通过 supported_cursor_mode 事件公布的光标模式是协议错误。
supported_cursor_mode(mode: uint<zcosmic_screencopy_manager_v1.cursor_mode>)
参数 | 类型 | 描述 |
|---|---|---|
| mode | uint<zcosmic_screencopy_manager_v1.cursor_mode> |
在 zcosmic_screencopy_manager_v1 全局初始化后，它将立即发送 supported_cursor_mode 事件以通知客户端受支持的光标模式。
error { invalid_cursor_mode }
参数 | 值 | 描述 |
|---|---|---|
| invalid_cursor_mode | 0 | 提供的光标模式不受支持 |
此对象表示正在被捕获的会话。
创建屏幕捕获会话后，合成器将发出 buffer_info 事件，告知客户端 surface 支持哪些缓冲区类型和格式进行读取。
当客户端了解所有缓冲区属性后，可以创建缓冲区，使用 "attach_buffer" 请求将其附加到屏幕捕获 surface，使用 "damage_buffer" 请求设置缓冲区损坏，然后调用 "commit" 请求。
调用 "commit" 后，下次合成器提交缓冲区时，该缓冲区的内容将被复制到提交到屏幕捕获会话的缓冲区。将生成一系列事件，以 "ready" 事件结束，这意味着缓冲区已准备好使用，可以再次向 surface 提交缓冲区。
"failed" 事件可以随时发送。发生这种情况时，客户端必须销毁会话。根据失败原因，客户端可以创建新会话来替换它。
capture_cursor(session: new_id<zcosmic_screencopy_session_v1>, seat: object<wl_seat>)
参数 | 类型 | 描述 |
|---|---|---|
| session | new_id<zcosmic_screencopy_session_v1> | |
| seat | object<wl_seat> |
创建用于捕获给定 seat 光标的子会话。 当服务器未通过值为 capture 的 supported_cursor_mode 事件表示支持时，使用此请求是协议错误。
子会话不会生成 cursor_enter 或 cursor_leave 事件。它将为捕获的 seat 生成单个 cursor_info 事件（如果光标之前已进入会话），或不生成 cursor_info 事件。该事件将与主会话上生成的匹配 cursor_info 事件相同。
合成器提供的 buffer_info 可能与主会话支持的缓冲区不同，也可能对每个捕获的 seat 不同。
子会话永远不会发送 commit_time 或 ready 事件，但被视为就绪并与主会话一起显示。
将缓冲区附加到 surface。
commit(options: uint<zcosmic_screencopy_session_v1.options>)
参数 | 类型 | 描述 |
|---|---|---|
| options | uint<zcosmic_screencopy_session_v1.options> |
提交屏幕捕获会话。
帧将被复制到会话中。缓冲区就绪时会生成 ready 事件。
如果设置了 "on_damage" 标志，合成器应等待有损坏时再向客户端发送新帧。
buffer_info(type: uint<zcosmic_screencopy_session_v1.buffer_type>, node: string, format: uint, width: uint, height: uint, stride: uint)
参数 | 类型 | 描述 |
|---|---|---|
| type | uint<zcosmic_screencopy_session_v1.buffer_type> | buffer type |
| node | string允许为空 | device node |
| format | uint | buffer drm format |
| width | uint | buffer width |
| height | uint | buffer height |
| stride | uint | buffer stride |
提供主图像需要使用的缓冲区参数信息。创建会话后，会为每种支持的缓冲区类型发送此事件。
stride 参数对 dmabuf 无效，可设置为 0。
transform(transform: int<wl_output.transform>)
参数 | 类型 | 描述 |
|---|---|---|
| transform | int<wl_output.transform> |
此事件在 ready 事件之前发送，包含源缓冲区的变换。
参数 | 类型 | 描述 |
|---|---|---|
| x | uint | damaged x coordinates |
| y | uint | damaged y coordinates |
| width | uint | current width |
| height | uint | current height |
此事件在 ready 事件之前发送。每次提交可以生成多次。
参数描述自上次 ready 事件以来发生变化的区域周围的框。
这些坐标源自缓冲区的左上角。
cursor_enter(seat: object<wl_seat>, input_type: uint<zcosmic_screencopy_session_v1.input_type>)
参数 | 类型 | 描述 |
|---|---|---|
| seat | object<wl_seat> | |
| input_type | uint<zcosmic_screencopy_session_v1.input_type> | input type |
当光标进入捕获的 surface 时发送。当且仅当光标进入 surface 时，应在 cursor_info 事件之前生成。
cursor_leave(seat: object<wl_seat>, input_type: uint<zcosmic_screencopy_session_v1.input_type>)
参数 | 类型 | 描述 |
|---|---|---|
| seat | object<wl_seat> | |
| input_type | uint<zcosmic_screencopy_session_v1.input_type> | input type |
当光标离开捕获的 surface 时发送。不会为给定光标生成 cursor_info 事件。
cursor_info(seat: object<wl_seat>, input_type: uint<zcosmic_screencopy_session_v1.input_type>, position_x: int, position_y: int, width: int, height: int, hotspot_x: int, hotspot_y: int)
参数 | 类型 | 描述 |
|---|---|---|
| seat | object<wl_seat> | |
| input_type | uint<zcosmic_screencopy_session_v1.input_type> | |
| position_x | int | position x coordinates |
| position_y | int | position y coordinates |
| width | int | width of the cursor image |
| height | int | height of the cursor image |
| hotspot_x | int | hotspot x coordinates |
| hotspot_y | int | hotspot y coordinates |
此事件为附加到会话且当前在会话中获得焦点的每个光标缓冲区生成。在 ready 事件之前为每个光标缓冲区生成一次。
surface 外部的光标不会被捕获，也不会为其生成事件。
如果光标图像已更改，光标缓冲区将被更新，has_damage 参数将设置为 1；否则为 0。
给定位置是光标热点的位置，它相对于主缓冲区的左上角（以变换后的缓冲区像素坐标表示）。
热点坐标相对于光标缓冲区的左上角。
failed(reason: uint<zcosmic_screencopy_session_v1.failure_reason>)
此事件表示尝试的帧复制失败。
收到此事件后，客户端必须销毁对象。
参数 | 类型 | 描述 |
|---|---|---|
| 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 |
此事件指示帧在系统单调时间中被提交扫描输出的时间。
时间戳表示为 tv_sec_hi、tv_sec_lo、tv_nsec 三元组，每个分量为无符号 32 位值。整秒在 tv_sec 中，它是 tv_sec_hi 和 tv_sec_lo 组合的 64 位值，附加的分数部分在 tv_nsec 中以纳秒为单位。因此，对于有效时间戳，tv_nsec 必须在 [0, 999999999] 范围内。
error { invalid_cursor_mode }
参数 | 值 | 描述 |
|---|---|---|
| invalid_cursor_mode | 0 | 提供的光标模式不受支持 |
failure_reason { unspec, invalid_buffer, invalid_output, invalid_workspace, invalid_toplevel, invalid_seat, invalid_size }
合成器支持
Copyright
Copyright © 2021-2022 Andri Yngvason Copyright © 2022 Victoria Brekenfeld
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.