Hyprland surface

Hyprland 特定的 wl_surface 扩展

此协议暴露 Hyprland 特定的 wl_surface 属性。

hyprland_surface_manager_v1

版本 2

Hyprland surface 对象管理器

此接口允许客户端创建 Hyprland surface 对象。

hyprland_surface_manager_v1::get_hyprland_surface

get_hyprland_surface(id: new_id<hyprland_surface_v1>, surface: object<wl_surface>)

参数	类型	描述
id	new_id<hyprland_surface_v1>
surface	object<wl_surface>

创建一个 Hyprland surface 对象

为给定的 Wayland surface 创建一个 Hyprland surface 对象。

如果该 wl_surface 已经关联了一个 hyprland_surface_v1 对象（即使来自不同的管理器），则创建操作将产生协议错误。

hyprland_surface_manager_v1::destroy

类型: destructor

destroy()

销毁 Hyprland surface 管理器

销毁 surface 管理器。此操作不会销毁已存在的 surface 对象。

hyprland_surface_manager_v1::error

error { already_constructed }

参数	值	描述
already_constructed	0	wl_surface 已经拥有一个 Hyprland surface 对象

hyprland_surface_v1

版本 2

Hyprland 特定的 wl_surface 属性

此接口允许访问 wl_surface 的 Hyprland 特定属性。

一旦 wl_surface 被销毁，Hyprland surface 对象也必须随之销毁。所有其他操作都将产生协议错误。

hyprland_surface_v1::set_opacity

set_opacity(opacity: fixed)

参数	类型	描述
opacity	fixed

设置 surface 的整体不透明度

设置 surface 整体不透明度的乘数。此乘数不仅适用于 surface 的内容，还适用于视觉效果（如 surface 背后的模糊效果）。

默认值为 1.0。设置超出 0.0 - 1.0（含）范围的值将产生协议错误。在调用 wl_surface.commit 之前不会生效。

hyprland_surface_v1::destroy

类型: destructor

destroy()

销毁 Hyprland surface 接口

销毁 Hyprland surface 对象，在下次 wl_surface.commit 时将此接口提供的属性重置为默认值。

hyprland_surface_v1::set_visible_region

起始版本 2

set_visible_region(region: object<wl_region>)

参数	类型	描述
region	object<wl_region>允许为空

设置 surface 的可见区域

此请求设置 surface 中包含可见内容的区域。可见内容指的是 alpha 值大于零的内容。

可见区域是为 compositor 提供的优化提示，使其可以避免绘制 surface 中不可见的部分。设置一个未包含 surface 中所有内容的可见区域可能导致部分内容未被绘制。

可见区域以 buffer 本地坐标指定。

compositor 会忽略超出 surface 范围的可见区域部分。当区域的所有部分都超出 buffer 几何范围时，compositor 可以完全避免渲染该 surface。

可见区域的初始值为空。设置可见区域具有拷贝语义，wl_region 对象可以立即销毁。NULL wl_region 会使可见区域被设置为空。

在调用 wl_surface.commit 之前不会生效。

hyprland_surface_v1::error

error { no_surface, out_of_range }

参数	值	描述
no_surface	0	wl_surface 已被销毁
out_of_range	1	给定的不透明度不在 0.0 - 1.0（含）范围内

合成器支持

	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_surface_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.