Chromium surface augmenter
surface_augmenter
暴露表面委托合成功能的全局接口用于实例化 wl_surface 对象的接口扩展。此扩展接口将允许委托表面内容的合成，有效地断开缓冲区与表面内容之间的直接关系（例如添加对纯色四边形和圆角的支持）。
destroy()
通知服务器客户端将不再使用此协议对象。这不会影响任何其他对象，包括 augmenter 对象。
实例化给定大小的缓冲区，用于给定颜色的纯色四边形。
此缓冲区不需要合成器中的资源，因此可以立即重用和共享。因此它不负责发送 wl_buffer.release 或 zwp_linux_buffer_release_v1.*_release 事件。
get_augmented_surface(id: new_id<augmented_surface>, surface: object<wl_surface>)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<augmented_surface> | the new augmenter interface id |
| surface | object<wl_surface> | the surface |
为给定的 wl_surface 实例化接口扩展以扩展其内容的合成。如果给定的 wl_surface 已有关联的 augmentation 对象，则引发 delegate_exists 协议错误。
如果需要调用此方法，必须在创建表面角色对象之前调用。
get_augmented_subsurface(id: new_id<augmented_sub_surface>, subsurface: object<wl_subsurface>)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<augmented_sub_surface> | the new augmenter interface id |
| subsurface | object<wl_subsurface> | the subsurface |
为给定的 wl_subsurface 实例化接口扩展以扩展其内容的合成。如果给定的 wl_subsurface 已有关联的 augmentation 对象，则引发 delegate_exists 协议错误。
error { augmented_surface_exists }
参数 | 值 | 描述 |
|---|---|---|
| augmented_surface_exists | 0 | 该表面已有关联的 augmenter 对象 |
augmented_surface
wl_surface 对象的附加接口，允许客户端指定表面内容的委托合成。
这使得该表面成为仅用于合成其父表面的对象。这意味着该表面将被裁剪到父边界，不会接收输入事件或显示进入/离开事件等。
使用 wl_subsurface 角色对象来表示此对象将为其执行委托合成的父表面。
对此外表面的提交假定与其父提交同步行为，如同同步的 wl_subsurface 一样。
合成器不会执行由 augmented_surface 的移动、大小调整、堆叠更改或消失引入的细粒度损坏扩展计算。执行此类操作的客户端应考虑这一点并相应地损坏父级非增强的 wl_surface。
各种更改（如添加或删除增强子表面、更改其位置或堆叠顺序）不会在合成器端引入额外的损坏。父 wl_surface 应考虑引入的额外损坏。
此表面使用其父级的 wl_subsurface 角色，不能相对于父级的非增强子表面堆叠，但可以相对于其他增强子表面堆叠。此表面也不能有非增强子表面子级。
使用 augmented_surfaces 委托合成 wl_surfaces 的混合树结构如下所示：
wl_surface@1:{ augmented_surface@1,2,3 } / \_____ / \ wl_surface@2: wl_surface@3: { augmented_surface@4,5 } { augmented_surface@6 }
每个 wl_surface 都有一个 augmented_surfaces 列表。假设 wl_surface 堆叠顺序从下到上为： wl_surface@1, wl_surface@2, wl_surface@3
则最终合成顺序从下到上为： wl_surface@1, augmented_surface@1,2,3, wl_surface@2, augmented_surface@4,5, wl_surface@3,...
set_rounded_corners(top_left: fixed, top_right: fixed, bottom_right: fixed, bottom_left: fixed)
参数 | 类型 | 描述 |
|---|---|---|
| top_left | fixed | top left corner |
| top_right | fixed | top right corner |
| bottom_right | fixed | bottom right corner |
| bottom_left | fixed | bottom left corner |
[已弃用]。使用下面的 set_rounded_corners_clip_bounds 请求。
通知服务器它必须应用将在下次提交时应用的圆角蒙版滤镜。请改用 set_rounded_corners_bounds。
设置表面目标视口大小，具有亚像素精度。此状态是双缓冲的，在下次 wl_surface.commit 时应用。
set_rounded_clip_bounds(x: int, y: int, width: int, height: int, top_left: fixed, top_right: fixed, bottom_right: fixed, bottom_left: fixed)
参数 | 类型 | 描述 |
|---|---|---|
| x | int | |
| y | int | |
| width | int | |
| height | int | |
| top_left | fixed | top left corner |
| top_right | fixed | top right corner |
| bottom_right | fixed | bottom right corner |
| bottom_left | fixed | bottom left corner |
[已弃用]。使用下面的 set_rounded_corners_clip_bounds 请求。
通知服务器它必须应用将在下次提交时应用的圆角裁剪蒙版滤镜。该蒙版可以对多个表面统一应用，使两个或多个表面在视觉上看起来像一个具有圆角的单一表面。请注意，这只能用作覆盖层的表面，不能有任何子树。如果边界在表面之外，圆角将被忽略。
set_background_color(color: array)
参数 | 类型 | 描述 |
|---|---|---|
| color | array | overlay color represented by a SkColor4f |
设置此表面的背景颜色。此信息将与下一个缓冲区提交关联。请注意，这与纯色缓冲区不同，纯色缓冲区会创建新的缓冲区实例，而是提供有关如何合成缓冲区的附加信息。传递空数组表示重置背景颜色。默认值由 Wayland 合成器确定。
set_trusted_damage(enabled: int)
参数 | 类型 | 描述 |
|---|---|---|
| enabled | int |
[已弃用] 设置后，此表面信任报告到此表面及后代子表面的所有损坏都是准确的，不会尝试重新计算。如果未设置，各种更改（如添加或删除子表面、更改其位置或堆叠顺序）可能会导致此表面的完全损坏。
初始状态为禁用。
set_rounded_corners_clip_bounds(x: fixed, y: fixed, width: fixed, height: fixed, top_left: fixed, top_right: fixed, bottom_right: fixed, bottom_left: fixed)
参数 | 类型 | 描述 |
|---|---|---|
| x | fixed | |
| y | fixed | |
| width | fixed | |
| height | fixed | |
| top_left | fixed | top left corner |
| top_right | fixed | top right corner |
| bottom_right | fixed | bottom right corner |
| bottom_left | fixed | bottom left corner |
通知服务器它必须应用将在下次提交时应用的圆角裁剪蒙版滤镜。该蒙版可以对多个表面统一应用，使两个或多个表面在视觉上看起来像一个具有圆角的单一表面。
从版本 9 开始，边界将以其原点（左上角像素）放置在表面局部坐标系的 x, y 位置。在版本 8 或更早版本中，它使用其根表面坐标放置，但这已弃用。
请注意，这只能用作覆盖层的表面，不能有任何子树。如果边界在表面之外，圆角将被忽略。
参数 | 类型 | 描述 |
|---|---|---|
| x | fixed | x coordinate in the surface local coordinates |
| y | fixed | y coordinate in the surface local coordinates |
| width | fixed | width of the clip rect |
| height | fixed | height of the clip rect |
计划在绘制此子表面时应用裁剪矩形。裁剪将以其原点（左上角像素）放置在表面局部坐标系的 x, y 位置。坐标不限于表面区域。允许负的 x 和 y 值。
如果 x、y、width 和 height 都为 -1.0，则取消设置裁剪矩形。
最初，表面没有设置裁剪。此状态是双缓冲的，在下次 wl_surface.commit 时应用。
设置跟踪 ID 以连接客户端和服务器端的帧提交跟踪事件流。此状态是双缓冲的，在下次 wl_surface.commit 时应用。
error { bad_value, no_surface, bad_surface }
参数 | 值 | 描述 |
|---|---|---|
| bad_value | 0 | 半径或大小中的负值 |
| no_surface | 1 | wl_surface 已被销毁 |
| bad_surface | 2 | 不兼容的表面 |
wl_subsurface 对象的附加接口，允许客户端指定表面内容的委托合成。
destroy()
关联的 wl_surface 的 augmenter 被移除。更改在下次 wl_surface.commit 时应用。
计划子表面位置更改。子表面将被移动，使其原点（左上角像素）位于父表面坐标系的 x, y 位置。坐标不限于父表面区域。允许负值。
计划的坐标将在父表面状态被应用时生效。何时发生取决于父表面是否处于同步模式。详见 wl_subsurface.set_sync 和 wl_subsurface.set_desync。
如果客户端在父表面提交之前发出多个 set_position 请求，新请求的位置总是替换任何先前请求的计划位置。
初始位置为 0, 0。此状态是双缓冲的，在下次 wl_surface.commit 时应用。
参数 | 类型 | 描述 |
|---|---|---|
| x | fixed | x coordinate in the parent surface |
| y | fixed | y coordinate in the parent surface |
| width | fixed | width of the clip rect |
| height | fixed | height of the clip rect |
[已弃用] 改为在 augmented_surface 上使用 set_clip_rect。计划在绘制此子表面时应用裁剪矩形。裁剪将以其原点（左上角像素）放置在父表面坐标系的 x, y 位置。坐标不限于父表面区域。允许负的 x 和 y 值。
如果 x、y、width 和 height 都为 -1.0，则取消设置裁剪矩形。
最初，表面没有设置裁剪。此状态是双缓冲的，在下次 wl_surface.commit 时应用。
合成器支持
Copyright
Copyright 2021 The Chromium Authors
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.