Hyprland toplevel export

捕获顶层窗口的内容

此协议允许客户端请求将另一个顶层窗口的表面导出到缓冲区中。

特别适用于共享单个窗口。

hyprland_toplevel_export_manager_v1

版本 2

通知客户端并开始捕获的管理器

此对象是一个管理器，提供从源开始捕获的请求。

hyprland_toplevel_export_manager_v1::capture_toplevel

capture_toplevel(frame: new_id<hyprland_toplevel_export_frame_v1>, overlay_cursor: int, handle: uint)

参数	类型	描述
frame	new_id<hyprland_toplevel_export_frame_v1>
overlay_cursor	int	composite cursor onto the frame
handle	uint	the handle of the toplevel (window) to be captured

捕获一个顶层窗口

捕获顶层窗口（窗口）的下一帧。

捕获的帧不会包含任何服务器端装饰，并且会忽略合成器设置的几何形状，例如圆角。

它将包含所有子表面和弹出窗口，但后者将被裁剪到基础表面的几何形状内。

handle 参数指窗口的地址，如在 `hyprctl clients` 中看到的那样。例如，d161e7b0 对应的值为 3512854448。

hyprland_toplevel_export_manager_v1::destroy

类型: destructor

destroy()

销毁管理器

管理器创建的所有对象将保持有效，直到调用相应的销毁请求。

hyprland_toplevel_export_manager_v1::capture_toplevel_with_wlr_toplevel_handle

起始版本 2

capture_toplevel_with_wlr_toplevel_handle(frame: new_id<hyprland_toplevel_export_frame_v1>, overlay_cursor: int, handle: object<zwlr_foreign_toplevel_handle_v1>)

参数	类型	描述
frame	new_id<hyprland_toplevel_export_frame_v1>
overlay_cursor	int	composite cursor onto the frame
handle	object<zwlr_foreign_toplevel_handle_v1>允许为空	the zwlr_foreign_toplevel_handle_v1 handle of the toplevel to be captured

捕获一个顶层窗口

与 capture_toplevel 相同，但使用 zwlr_foreign_toplevel_handle_v1 句柄。

hyprland_toplevel_export_frame_v1

版本 2

准备好进行复制的帧

此对象代表单个帧。

创建后，将发送一系列缓冲区事件，每个事件代表一种支持的缓冲区类型。随后发送 "buffer_done" 事件，表示所有支持的缓冲区类型已枚举完毕。客户端随后可以发送 "copy" 请求。如果捕获成功，合成器将发送 "flags" 事件，然后是 "ready" 事件。

wl_shm 缓冲区始终被支持，即保证会发送 "buffer" 事件。

如果捕获失败，将发送 "failed" 事件。这可能发生在 "ready" 事件之前的任何时间。

收到 "ready" 或 "failed" 事件后，客户端应销毁该帧。

hyprland_toplevel_export_frame_v1::copy

copy(buffer: object<wl_buffer>, ignore_damage: int)

参数	类型	描述
buffer	object<wl_buffer>
ignore_damage	int

复制帧

将帧复制到提供的缓冲区。缓冲区必须具有正确的大小，参见 hyprland_toplevel_export_frame_v1.buffer 和 hyprland_toplevel_export_frame_v1.linux_dmabuf。缓冲区需要具有支持的格式。

如果帧复制成功，将发送 "flags" 和 "ready" 事件。否则，将发送 "failed" 事件。

此事件将等待适当的损坏区域进行复制，除非 ignore_damage 参数设置为非零值。

hyprland_toplevel_export_frame_v1::destroy

类型: destructor

destroy()

删除此对象，无论是否已使用

销毁该帧。客户端可以在任何时候发送此请求。

hyprland_toplevel_export_frame_v1::buffer

buffer(format: uint<wl_shm.format>, width: uint, height: uint, stride: uint)

参数	类型	描述
format	uint<wl_shm.format>	buffer format
width	uint	buffer width
height	uint	buffer height
stride	uint	buffer stride

wl_shm 缓冲区信息

提供此帧需要使用的 wl_shm 缓冲区参数信息。如果支持 wl_shm 缓冲区，此事件在帧创建后发送一次。

hyprland_toplevel_export_frame_v1::damage

damage(x: uint, y: uint, width: uint, height: uint)

参数	类型	描述
x	uint	damaged x coordinates
y	uint	damaged y coordinates
width	uint	current width
height	uint	current height

携带损坏区域的坐标

此事件在未设置 ignore_damage 时，在 ready 事件之前发送。每个 copy 请求可能生成多次。

参数描述了自上一次 copy 请求以来发生变化的区域周围的包围盒。

在 copy 调用和 ready 事件之间接收到的所有区域的并集是自上一次 ready 事件以来的总损坏区域。

hyprland_toplevel_export_frame_v1::flags

flags(flags: uint<hyprland_toplevel_export_frame_v1.flags>)

参数	类型	描述
flags	uint<hyprland_toplevel_export_frame_v1.flags>	frame flags

帧标志

提供关于帧的标志。此事件在 "ready" 事件之前发送一次。

hyprland_toplevel_export_frame_v1::ready

ready(tv_sec_hi: uint, tv_sec_lo: uint, tv_nsec: uint)

参数	类型	描述
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] 范围内。秒部分在启动时可能有任意偏移。

收到此事件后，客户端应销毁该对象。

hyprland_toplevel_export_frame_v1::failed

failed()

帧复制失败

此事件表示尝试的帧复制失败。

收到此事件后，客户端应销毁该对象。

hyprland_toplevel_export_frame_v1::linux_dmabuf

linux_dmabuf(format: uint, width: uint, height: uint)

参数	类型	描述
format	uint	fourcc pixel format
width	uint	buffer width
height	uint	buffer height

linux-dmabuf 缓冲区信息

提供此帧需要使用的 linux-dmabuf 缓冲区参数信息。如果支持 linux-dmabuf 缓冲区，此事件在帧创建后发送一次。

hyprland_toplevel_export_frame_v1::buffer_done

buffer_done()

所有缓冲区类型已报告

此事件在所有缓冲区事件发送完毕后发送一次。

客户端应继续创建一种支持类型的缓冲区，并发送 "copy" 请求。

hyprland_toplevel_export_frame_v1::error

error { already_used, invalid_buffer }

参数	值	描述
already_used	0	该对象已被用于复制 wl_buffer
invalid_buffer	1	缓冲区属性无效

hyprland_toplevel_export_frame_v1::flags

位字段

flags { y_invert }

参数	值	描述
y_invert	1	内容是 y 轴翻转的

合成器支持

	Cage 0.2.0	COSMIC 1.0.0~beta.8	GameScope 3.15.14	Hyprland 0.52.1	Jay 1.12.0	KWin 6.6	Labwc 0.9.2	Louvre 2.14.1	Mir 2.26	Muffin 6.6.0	Mutter 49.2	niri 25.11	phoc 0.52	river 0.3.13	Sway 1.11	Treeland 0.8.0	Wayfire 0.9.0	Weston 14.0.2
hyprland_toplevel_export_manager_v1	x	x	x	2	x	x	x	x	x	x	x	x	x	x	x	x	x	x

Copyright

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.