fuchsia.ui.composition

新增：7

协议

分配器

在 fuchsia.ui.composition/allocator.fidl 中定义

RegisterBufferCollection

BufferCollection 是由 Sysmem 创建并由多个参与者（其中一个是 Flatland 渲染程序）共享的一组 VMO。某些内容（例如图片）使用 BufferCollection 作为其后备内存。

如需了解每个参数，请参阅 RegisterBufferCollectionArgs。

请求

名称类型
args RegisterBufferCollectionArgs

响应

名称类型
payload Allocator_RegisterBufferCollection_Result

ChildViewWatcher

在 fuchsia.ui.composition/flatland.fidl 中定义

一种协议，用于提供有关附加到父客户端拥有的 Viewport 的特定子 View 的信息；与此协议的连接在 CreateViewport 中建立。由于 Flatland 会话可能包含任意数量的视口，每个视口可能附加到转换，也可能不附加到转换，因此客户端可以保持与相同数量的 ChildViewWatcher 实例的连接。

只要相应的子 View 存在，每个 ChildViewWatcher 实例就会保持连接状态；如果子 ViewCreationToken 被丢弃而未用于创建 View，连接也会关闭。

GetStatus

用于接收 View 状态的挂起 get。这会向父级提供信息，例如子级是否已通过此 View 成功呈现内容。

仅当 ChildViewStatus 与之前返回的 ChildViewStatus 不同时，此挂起获取才会触发。即使 Viewport 的创建者在调用 CreateViewport() 后尚未调用 Present()，也可能会立即发生这种情况。这样，父级就可以在修改自己的本地场景图以纳入子级内容之前，知道子级已有可供显示的内容。

在上一次调用仍处于待处理状态时，调用 GetStatus 是无效的。这样做会导致此通道和分发 ChildViewWatcher 的 Flatland 通道都关闭。

请求

<EMPTY>

响应

名称类型
status ChildViewStatus

GetViewRef

挂起 get 以接收子 View 的 ViewRef。仅当视图引用与之前返回的视图引用不同时，才会触发此事件。注意：目前，视图引用在首次收到后不会发生变化，但如果/当 API 发生变化以允许重新关联视图时，视图引用将会发生变化。

在 View 包含在 View 树中之前，不会返回 ViewRef，换句话说，当存在一条祖先转换链一直回到场景图的根（即显示屏）时，才会返回 ViewRef。

在上一次调用仍处于待处理状态时，调用 GetViewRef 是无效的。这样做会导致此通道和分发 ChildViewWatcher 的 Flatland 通道都关闭。

如果 View 是使用 CreateView 创建的，则 GetViewRef 调用会挂起；但如果 View 是使用 CreateView2 创建的，则会返回 View。这是因为 CreateView 不会为该 View 建立 ViewRef。

请求

<EMPTY>

响应

名称类型
view_ref fuchsia.ui.views/ViewRef

Flatland

在 fuchsia.ui.composition/flatland.fidl 中定义

每个 Flatland 会话都包含一个图，该图由一组对象以及这些对象之间的关系组成。客户端可以指定这些对象的一个子集（具体而言，是从根转换开始的有向无环图），以作为内容呈现给某种输出（通常是显示屏）。

Flatland 图既是分层的，也是分布式的。来自不同 Flatland 会话的图表可以连接在一起，从而允许多个进程参与为特定输出创作内容。

此协议中的所有函数都是前馈函数。在调用 Present 之前，它们表示的操作不会完全执行。

AddChild

将子级 Transform 添加到父级 Transform。新的子级 Transform 以及附加到该子级或其子级的所有 Content 都将呈现在父级 Content 以及之前添加的所有子级之上。

调用方必须确保 child_transform_id 有效且没有重复。在多次调用中发送重复的 child_transform_id 会导致会话关闭。

请求

名称类型
parent_transform_id TransformId
child_transform_id TransformId

清除

此函数会重置此接口上的所有状态。这包括销毁所有现有的 View 和 Viewport，而无需将关联的令牌返回给调用方。

请求

<EMPTY>

CreateFilledRect

创建纯色矩形。默认情况下，filled-rect 没有定义的颜色或尺寸。必须先调用 |SetSolidFill| 来指定颜色和大小，然后才能使用填充矩形进行渲染。否则，矩形的默认大小将为 (0,0)，因此在渲染时不会显示。

rect_id 必须满足标准 ContentId 创建限制。

已弃用：33

请求

名称类型
rect_id ContentId

CreateImage

Image 是由 BufferCollection 中的特定 VMO 支持的位图。

创建映像需要向 Allocator 注册已分配的 BufferCollection。除非指定 BufferCollection 的所有客户端都已设置其限制，否则此函数将失败。

Image 必须引用有效的 VMO 索引，并且必须具有在后备 BufferCollection 指定的约束条件范围内的 ImageProperties（即宽度和高度在有效范围内等）。

image_id 必须满足标准 ContentId 创建限制。

已弃用：33

请求

名称类型
image_id ContentId
import_token BufferCollectionImportToken
vmo_index uint32
properties ImageProperties

CreateImage2

创建 Image 资源。

image_id 必须满足 LayerId 中记录的标识符规则。

请求

名称类型
image_id ImageId
import_token BufferCollectionImportToken
vmo_index uint32
properties ImageProperties

CreateLayer

Layer 是一种 Content，用于合成单个 Image 或纯色。它将视觉属性（例如大小、翻转、不透明度和混合）与原始像素数据分开。

与代表静态视觉资源的典型 Content 项不同，图层旨在作为图片序列的动态容器。典型用法包括不频繁地设置图层的视觉属性和图片元数据，然后快速将活跃的 Image（例如在每一帧上）与具有匹配元数据的另一张图片进行交换。

通过这种分离，单个 Image 资源可以同时在具有不同视觉配置的多个层中重复使用。

如需使用 Layer，请执行以下操作：

  1. 使用 CreateLayer 创建 Layer。
  2. 通过 SetLayerProperties 在 Layer 上设置属性，包括合成模式。
  3. 对于图片层，通过 SetLayerImage 将 Image 与 Layer 相关联。
  4. 通过 SetStackLayers 将 Layer 添加到 LayerStack。
  5. 通过 SetTransformContent 将 LayerStack 设置为节点的内容。

layer_id 必须满足 LayerId 中记录的标识符规则。

请求

名称类型
layer_id LayerId

CreateLayerStack

使用指定的 stack_id 创建新的图层堆栈。

stack_id 必须满足 LayerId 中记录的标识符规则。

请求

名称类型
stack_id LayerStackId

CreateTransform

创建新的变换节点。转换是 Flatland 图的分层部分。它们可以有子级，并且可以引用 Content。由 Transform 及其后代表示的子图可以渲染到显示屏。

只要转换是未发布的转换或根转换的子级，即使已发布，也会保持有效。

每个 Transform 都可以附加一个 Content。常见的内容类型包括位图、异步图片流以及其他 Flatland 会话中托管的视图的视口。

转换具有属性。子级转换会继承其父级的组合属性。附加到 Transform 的内容也会受到该 Transform 属性的影响。

渲染转换子图时，内容将从后向前渲染，从根转换上的内容开始，然后按子转换的添加顺序递归遍历其所有子转换。如需了解详情，请参阅 AddChild。

零不是有效的转换 ID。所有其他值均有效，前提是它们尚未被使用（如需了解详情，请参阅 ReleaseTransform）。

请求

名称类型
transform_id TransformId

CreateView

两个 Flatland 会话可以采用父子关系进行连接。父级端点保存在 Viewport 中，子级端点保存在 View 中。创建 Viewport 的父级 Flatland 会话可以控制子级 View 如何集成到其自己的 View 中。

父子连接的生命周期从通道对象的两个端点开始：ViewportCreationToken 和 ViewCreationToken。带外协议会将 ViewportCreationToken 传递给父级（调用 CreateViewport），并将 ViewCreationToken 传递给子级（调用 CreateView）。

只有连接到此 Flatland 会话中根转换的节点才会渲染到父级的视口中。

再次调用 CreateView 会将根转换与现有父级的视口断开连接，并将其附加到新父级的视口。换句话说，每个 View 只能有一个父级。

此函数会排队，这意味着在调用 Present 之前，根转换不会附加到父级 Viewport。不过，客户端在调用此函数后会立即通过其 ParentViewportWatcher（例如 LayoutInfo）收到信息，即使他们尚未调用 Present 或 SetRootTransform 也是如此。这样，客户端就可以在调用 Present 之前等待来自其父级的布局信息。

对 ParentViewportWatcher 的任何非法操作都会导致 ParentViewportWatcher 通道和此 Flatland 通道被拆除。

生命周期说明。ParentViewportWatcher 通道的生命周期受对等 ViewportCreationToken 的约束。当 ViewportCreationToken 终止时，此 ParentViewportWatcher 通道会被销毁。

使用 CreateView 创建的 View 和 View 子图不会在 ViewTree 中表示，因此无法参与任何依赖于 ViewTree 的互动，例如触摸、鼠标或焦点。 Flatland 协议无法让使用 CreateView 创建的 View 的子图中的 View 知道它们已从 ViewTree 中排除。

请求

名称类型
token fuchsia.ui.views/ViewCreationToken
parent_viewport_watcher server_end:ParentViewportWatcher

CreateView2

与 CreateView 相同，但它允许关联视图身份 (ViewRef) 和视图绑定协议。

请求

名称类型
token fuchsia.ui.views/ViewCreationToken
view_identity fuchsia.ui.views/ViewIdentityOnCreation
protocols ViewBoundProtocols
parent_viewport_watcher server_end:ParentViewportWatcher

CreateViewport

Viewport 和 View 对共同表示两个 Flatland 会话之间的连接。Viewport 在父级中创建，View 在子级中创建。父级可以控制子级的 View 如何集成到其自己的 View 中。

对 ChildViewWatcher 的任何非法操作都会导致 ChildViewWatcher 通道和此 Flatland 通道被拆除。

ViewportProperties 必须设置 logical_size。这是将驱动子级布局的初始大小。logical_size 也会用作默认 Content size，但后续对 logical_size 的更改不会影响 Content size。

ViewportProperties 可能未设置 inset 字段。在这种情况下，系统会使用默认值 (0, 0, 0, 0)。

logical_size 必须具有正 X 和 Y 分量。

生命周期说明。ChildViewWatcher 通道的生命周期受对等 ViewCreationToken 的约束。当 ViewCreationToken 终止时，此 ChildViewWatcher 通道会被销毁。

viewport_id 必须满足标准 ContentId 创建限制。

已弃用：33

请求

名称类型
viewport_id ContentId
token fuchsia.ui.views/ViewportCreationToken
properties ViewportProperties
child_view_watcher server_end:ChildViewWatcher

CreateViewport2

创建 Viewport 资源。

viewport_id 必须满足 LayerId 中记录的标识符规则。

请求

名称类型
viewport_id ViewportId
token fuchsia.ui.views/ViewportCreationToken
properties ViewportProperties
child_view_watcher server_end:ChildViewWatcher

OnError

如果 Present 之后发生错误，系统会触发 OnError 事件并提供相关信息。

FlatlandErrors 将关闭与客户端的连接。

  • 响应 error 客户端在执行某些无效操作后可能会收到的错误。

响应

名称类型
error FlatlandError

OnFramePresented

每当一组一个或多个 Present 同时呈现，从而不再处于传输状态时，就会触发此事件。

此事件表示在 Present 之前加入队列的命令已在场景图中生效，并且全局可见。

对于基本帧调度，客户端不必为此事件实现处理程序，除非他们明确希望获得有关先前帧呈现的反馈。所有未来的帧信息都会在 OnNextFrameBegin 事件中提供。

TODO(https://fxbug.dev/42141795)：从此事件中移除 num_presents_allowed。

响应

名称类型
frame_presented_info fuchsia.scenic.scheduling/FramePresentedInfo

OnNextFrameBegin

当客户端预计资源争用最少时，会触发此事件。客户端可以使用此事件的时间来开始其渲染工作，并使用返回的信息来做出调度决策。

重要的是，只有当客户端有一个或多个呈现积分（包括此事件中返回的积分）时，才会触发 OnNextFrameBegin。因此，每次触发此事件时，都可以安全地显示一次。

  • 响应 values 客户端生成下一帧所需的信息表。如需了解详情，请参阅 OnNextFrameBeginValues。

响应

名称类型
values OnNextFrameBeginValues

演示

完成所有前馈操作的执行。

如果执行操作时出错（例如 CreateTransform(0)），则会发出 OnError 事件。产生错误的操作会被忽略，并且通道会关闭。

如果执行成功完成，系统会发出 OnNextFrameBegin，其中包含有效的帧生成信息。

只有当客户端具有非零数量的呈现积分（由服务器跟踪）时，才能调用 Present。服务器可能会在触发 OnNextFrameBegin 事件时增加信用点数，该事件会在客户端收到额外的呈现信用点数时通知客户端。每次 Present 调用都会使用一个呈现积分，并使服务器计数减一。如果客户端在没有呈现积分的情况下调用 Present，服务器将返回 NO_PRESENTS_REMAINING 错误。

客户端应假定在收到任何 OnNextFrameBegin 事件之前，它们有一个呈现积分。

每次 Present 调用都会产生一个 OnNextFrameBegin 事件和一个 OnFramePresented 事件，通常按此顺序发生。

当 Present 刷新的命令显示时，系统会触发 OnFramePresented 事件。此事件包含与该帧中包含内容的所有 Present 相关的信息。

如需详细了解传入的参数及其作用，请参阅上文中的 fuchsia.ui.composition/PresentArgs 文档。

请求

名称类型
args PresentArgs

ReleaseFilledRect

当不再需要矩形进行渲染时，自动对其进行垃圾回收。|rect_id| 必须已通过调用 |CreateFilledRect| 进行实例化。释放后，该 ID 会立即超出范围，并可再次使用。

rect_id 必须引用有效的、未释放的填充矩形。

已弃用：33

请求

名称类型
rect_id ContentId

ReleaseImage

当不再需要渲染时，系统会通过垃圾回收机制回收已释放的图片。对于图片，这意味着图片不再附加到任何转换，并且引用该图片的任何待处理渲染都已完成。

使用 SetContent(transform_id, 0) 清理对已释放 Image 的引用。

释放后，该 ID 会立即超出未来函数调用的范围，并且可在创建新图片时重复使用。

使用已释放的 ID 调用函数是错误的（除非该 ID 已被重复用于构建新 Image）。

已弃用：33

请求

名称类型
image_id ContentId

ReleaseImage2

当不再需要渲染时，系统会通过垃圾回收机制回收已释放的图片。对于图片，这意味着：

  • 该 Image 不再绑定到任何 Layer，并且
  • 任何引用该 Image 的待处理渲染都已完成。

image_id 值会立即释放，供客户端重复使用（标识符唯一性是瞬时的）。

注意：每个绑定的释放栅栏（传递给 SetLayerImage）不受此调用的影响。 它们跟踪的是各个层绑定的生命周期，而不是客户端的 image_id。

image_id 必须引用有效的未发布映像。

请求

名称类型
image_id ImageId

ReleaseImageImmediately

立即释放图片，而无需等待下一次呈现。

请求

名称类型
image_id ContentId

ReleaseImageImmediately2

立即释放 Image，而无需等待下一次呈现。这是一条可信的内存逐出路径。

该图片会强制与当前引用它的所有图层解除绑定。这些图层的行为就像从未设置过其图片一样（它们不可见，但会保留其图片属性），直到下一次 SetLayerImage()。

被逐出 Image 的绑定的所有待处理释放栅栏都将在最早的安全点发出信号。

仅当 Flatland2 处于启用状态且会话可信时，此方法才可用。

请求

名称类型
image_id ImageId

ReleaseLayer

一旦不再需要渲染，系统就会对已释放的层进行垃圾回收。对于图层，这意味着：

  • 任何 LayerStack 都不再引用该 Layer，并且
  • 任何引用该层的待处理渲染均已完成。

layer_id 必须引用有效的未发布层。

请求

名称类型
layer_id LayerId

ReleaseLayerStack

释放具有指定 stack_id 的层堆栈。

请求

名称类型
stack_id LayerStackId

ReleaseTransform

一旦不再需要渲染，系统就会对已释放的转换进行垃圾回收。对于 Transform，这意味着从任何未发布的 Transform 到新发布的 Transform 都没有路径。

释放后，该 ID 会立即超出未来函数调用的范围，并可在创建新转换时重复使用。

使用已释放的 ID 调用函数会出错（除非该 ID 已被重复用于构建新的 Transform）。

请求

名称类型
transform_id TransformId

ReleaseView

释放视图，这会将此 Flatland 会话与其在另一个 Flatland 会话中的父级视口断开连接。

如需在不释放当前 View 的情况下清除屏幕上的现有内容，请改用 SetRootTransform(0)。

尽管具有返回值类型，但此函数仍是前馈函数（如 CreateView），并且需要调用 Present 才能执行。在执行所呈现的操作后，系统将返回 ViewCreationToken。

请求

<EMPTY>

ReleaseViewport

从场景中释放视口，即使视口仍连接到转换也是如此。 与其他资源不同，视口会在下一次 Present 期间由系统进行垃圾回收，因为已移除的视口保证不会提供任何可渲染的内容。

使用 SetContent(transform_id, 0) 清理对已释放视口的引用。

尽管具有返回值类型，但此函数仍像 CreateView 一样是前馈函数，需要调用 Present 才能执行。在执行呈现的操作后，系统会返回 ViewportCreationToken。

已弃用：33

请求

名称类型
viewport_id ContentId

响应

名称类型
token fuchsia.ui.views/ViewportCreationToken

ReleaseViewport2

从场景中释放 Viewport。

请求

名称类型
viewport_id ViewportId

响应

名称类型
token fuchsia.ui.views/ViewportCreationToken

RemoveChild

从父级 Transform 中移除子级 Transform。

请求

名称类型
parent_transform_id TransformId
child_transform_id TransformId

ReplaceChildren

从父级 Transform 中移除所有子级 Transform，并将其替换为 new_child_transform_ids 中的新子级 Transform。调用方必须确保 new_child_transform_ids 中的所有 TransformId 值均有效且不重复。在 new_child_transform_ids 中发送重复的 TransformId 会导致会话关闭。

请求

名称类型
parent_transform_id TransformId
new_child_transform_ids vector<TransformId>:64

ResetLayer

解除与该层绑定的所有 Image，并清除每个存储的 LayerProperties 字段，使该层恢复到新创建的状态（合成模式 INVISIBLE，所有属性均采用其记录的默认值）。这是唯一会忘记存储的图层属性的操作。

layer_id 必须引用有效的未发布层。

请求

名称类型
layer_id LayerId

SetClipBoundary

设置边界（以转换的局部坐标空间表示），用于限制可渲染附加到此转换的内容的区域。如果内容的区域超出剪辑边界，则边界之外的区域将不会呈现。这些边界也适用于此转换节点的所有子节点，包括嵌套的 Flatland 会话及其节点层次结构。如果子级转换尝试设置大于其父级转换的剪辑边界，则会剪辑到父级的剪辑边界。默认状态是转换不被裁剪，这意味着其渲染区域不会有任何边界。剪辑宽度/高度必须为正数。负值会导致错误。 向 |rect| 参数传入空框会移除剪辑边界。

请求

名称类型
transform_id TransformId
rect fuchsia.math/Rect?

SetContent

在 Transform 上设置一段 Content 后，只要该 Transform 从根 Transform 可见，该 Content 就会在渲染树中可见。该内容将在附加到 Transform 后代的所有内容之前（即“后面”）呈现。

由于每个 Transform 最多只能有一个 Content，因此对已有 Content 的 Transform 调用此函数会替换该 Content。

一个 Content 可能会设置在多个 Transform 上。

如果使用 Content ID 0 调用此函数，则会移除当前位于转换中的所有内容。

content_id 必须引用有效的、未发布的 Content 对象，或引用 0 以清除。

已弃用：33

请求

名称类型
transform_id TransformId
content_id ContentId

SetDebugName

设置当前客户端的调试名称，Flatland 可将其用作日志前缀进行输出，以帮助客户端区分哪些日志属于自己。name 可以是任意字符串，但当前进程名称（请参阅 fsl::GetCurrentProcessName()）是一个不错的默认值。

请求

名称类型
name string:64

SetHitRegions

设置 Transform 的互动区域。默认情况下，内容不具有互动性；必须放置点击区域，用户才能与 View 中的内容互动。由于点击区域在 Flatland 协议中进行了描述，因此 Flatland 会话可以同步内容和点击区域。

每个点击区域都位于所属 Transform 的坐标空间中，并且可能会或可能不会与不同类型的点击测试进行交互，具体取决于其 HitTestInteraction 类型。当有多个点击区域与点击测试相交时，以下优先规则将决定哪个点击区域与点击测试进行了互动。只有以传递方式连接到根转换的转换，其点击区域才会与点击测试交互。

调用此函数会替换之前在此 Transform 上设置的所有值。如需将转换重置为“不进行点击测试”，请使用 SetHitRegions 发送空向量。

请注意，根转换会获得 Flatland 安装的默认命中区域。如需了解详情，请参阅 SetRootTransform 文档。

优先级规则 在 Transform 中，如果多个点击区域重叠，点击测试会检查每个相交的点击区域，以确定是否存在可能的互动。因此，对于常规点击测试 R 和无障碍点击测试 A，如果 R 和 A 都与同一转换上的两个点击区域 D (DEFAULT) 和 S (SEMANTICALLY_INVISIBLE) 相交，则 (1) R 与 D 和 S 都会交互，而 (2) A 仅与 D 交互。通常，在单个 Transform 中重叠的点击区域可能会导致混乱的行为。

在 View 中，对于给定的点击测试，最前面的 Transform 的点击区域优先于后面的点击区域。这遵循了预期的反向“渲染顺序”转换（如 CreateTransform 中所述），其中用户希望与可见或最前面的内容进行交互。

在 Flatland 会话中，对于给定的点击测试，最前端会话的最前端转换的点击区域优先于其后面的点击区域。这遵循了预期的反向视图“渲染顺序”，即用户希望与可见或最前面的视图进行互动。例如，如果子视图拥有在父视图上呈现的内容，用户会希望与子视图的内容进行互动。

请求

名称类型
transform_id TransformId
regions vector<HitRegion>:64

SetImageBlendMode

确定在渲染由 |image_id| 指定的内容时要使用的混合函数。|image_id| 必须是通过调用 |CreateImage| 或 |CreateFilledRect| 与转换相关联的有效 ContentId。如需详细了解可用的不同混合函数，请参阅 BlendMode2 枚举。如果未调用此函数，则默认混合模式为 BlendMode2::REPLACE。

已弃用：33 新增：29

请求

名称类型
image_id ContentId
blend_mode BlendMode2

SetImageBlendingFunction

确定在渲染由 |image_id| 指定的内容时要使用的混合函数。|image_id| 必须是通过调用 |CreateImage| 或 |CreateFilledRect| 与转换相关联的有效 ContentId。如需详细了解可用的不同混合函数，请参阅 BlendMode 枚举。如果未调用此函数，则默认混合模式为 BlendMode::SRC。

已弃用：33

请求

名称类型
image_id ContentId
blend_mode BlendMode

SetImageDestinationSize

Image 的内容大小是指图片在父级逻辑坐标空间中占据的矩形的大小。此大小与它所附加到的转换的全局转换相结合，可确定内容在显示屏上的呈现大小和位置。

如果未调用此方法，则默认图片目标尺寸为 CreateImage 中 ImageProperties 处设置的宽度和高度。如果在附加的 Transform 或其父级上使用 SetScale，则目标大小会受到缩放的影响。

已弃用：33

请求

名称类型
image_id ContentId
size fuchsia.math/SizeU

SetImageFlip

设置要应用于平面图像的图像翻转。此调用必须在成功调用 |CreateImage| 后执行。如果提供了无效的 |image_id|，通道将因 FlatlandError::BAD_OPERATION 而关闭。此翻转将在父级转换方向之前应用于图片。如果未调用此函数，则默认翻转值为 ImageFlip::NONE。

已弃用：33

请求

名称类型
image_id ContentId
flip ImageFlip

SetImageOpacity

设置要应用于平面图像的线性空间不透明度。不透明度值必须在 [0.0, 1.0] 范围内。

已弃用：33

请求

名称类型
image_id ContentId
val float32

SetImageSampleRegion

此函数用于确定 Flatland 在渲染时将使用的图片区域（在纹素空间中）。要采样的图片由 image_id 引用，采样区域由 rect 指定，该区域本身由原点 (x,y) 以及宽度和高度（采用非标准化坐标）组成。在非图片内容上调用此函数，或对图片纹素空间之外的区域进行采样，都是不合法的。换句话说，rect 指定的区域不得超出范围 (0, image_width) 和 (0, image_height)。如果 (rect.x + rect.width > image_width) 或 (rect.y + rect.height > image_height)，或者任何值为负，则会导致错误。

如果未调用此方法，则默认采样区域为原点位于 (0, 0) 且宽度和高度设置为 CreateImage 中的 ImageProperties 的矩形。

image_id 必须引用有效的未发布映像。

已弃用：33

请求

名称类型
image_id ContentId
rect fuchsia.math/RectF

SetInfiniteHitRegion

与 SetHitRegions 相同，但与 transform_id 关联的点击区域覆盖无限区域。命中区域不会因 Transform 的平移、缩放和方向而发生变化。

与有限命中区域一样，无限命中区域的范围仍然受视图的剪辑边界限制。

调用此函数会替换之前在此 Transform 上设置的所有值。如需将转换重置为“不进行点击测试”，请使用 SetHitRegions 发送空向量。

请求

名称类型
transform_id TransformId
hit_test HitTestInteraction

SetLayerImage

将图片与图层相关联。

该绑定在任何合成模式下都是合法的，并且具有粘性：它在合成模式更改后仍然有效，并且只能由后续的 SetLayerImage 调用替换（或由 ResetLayer 清除）。仅当图层的合成模式为 IMAGE 时，系统才会显示图片。

绑定的图片必须足够大，才能容纳图层存储的 sample_rect；这会在 fuchsia.ui.composition/Flatland.Present 中进行检查，而不是在此处。请参阅 LayerProperties.sample_rect。

layer_id 必须引用有效的未发布层。 image_id 必须引用有效的未发布映像。 acquire_fence 是一个可选围栏，必须在显示图片之前发出信号。release_fence 是一个可选栅栏，当此绑定不再引用映像时，Scenic 会发出信号。它是按绑定（而非按图片）进行的：绑定到多个层的图片每个绑定都有一个这样的栅栏，并且只有在每个栅栏都发出信号后，图片才能安全写入。

绑定通过以下方式结束：

  • 被同一图层上后续的 SetLayerImage 取代
  • ResetLayer
  • 通过 ReleaseLayer 或由层堆栈释放，使层引用计数达到零
  • 销毁会话，这会结束会话持有的每个绑定

对于在会话处于活跃状态时结束的绑定，Scenic 会在绑定结束后的第一帧退出时发出信号。从未到达屏幕的绑定（例如，在单个批次中被取代的绑定，或者在多个 fuchsia.ui.composition/Flatland.Present 调用被压缩到单个帧中时丢失的绑定）会在同一停用时发出信号，而不是立即发出信号。因此，该信号最多会保守一帧，绝不会提前。

请求

名称类型
layer_id LayerId
image_id ImageId
acquire_fence WaitFence?
release_fence SignalFence?

SetLayerProperties

设置图层的属性。

提供的 properties 表会合并到图层的存储属性中：在 properties 中未设置的字段会保留其先前存储的值。存储的属性具有粘性；如需了解完整的持久性语义，请参阅 LayerProperties。

值会按原样存储；依赖于其他状态（尤其是针对绑定图片的 sample_rect）的验证会在 fuchsia.ui.composition/Flatland.Present 处进行。请参阅 LayerProperties.sample_rect。

layer_id 必须引用有效的未发布层。

请求

名称类型
layer_id LayerId
properties LayerProperties

SetOpacity

设置要应用于转换及其后代（包括其他转换和内容）的线性空间不透明度。不透明度值必须在 [0.0, 1.0] 范围内，其中 0.0 表示完全透明，1.0 表示完全不透明。尝试使用超出该范围的值调用此函数会导致错误。转换的不透明度值会与其父级的不透明度值相乘。此效果与组不透明度不同。使用组不透明度时，子节点会先一起渲染，然后将父级的不透明度作为后效应用。 在这里，不透明度会单独应用于每个子项。这可能会导致截然不同的效果。

请求

名称类型
transform_id TransformId
value float32

SetOrientation

设置 Transform 的方向。SetTranslation 的文档中介绍了应用几何属性的顺序。在 Flatland 中，+X 轴向右，+Y 轴向下。没有 Z 轴的概念。逆时针方向是从用户的视角定义的，就像屏幕上显示了一个拟物化时钟一样。

请求

名称类型
transform_id TransformId
orientation Orientation

SetRootTransform

为图表设置根转换。

由根转换及其子级定义的子图将在所连接父级的 Viewport 中呈现为 View（请参阅 CreateView）。此图表中根变换的任何父级都将被忽略。

如果根转换和根转换的所有子级被释放，它们会保持活跃状态（如需了解详情，请参阅 ReleaseTransform）。

根始终只有一个。由于 0 不是有效的转换 ID（请参阅 CreateTransform），因此调用 SetRootTransform(0) 会清除当前根，从而销毁新根未引用的任何先前释放的对象。

请注意，每个 View 都有一个与其逻辑大小等效的剪辑边界。该剪裁边界之外的任何内容都不会渲染。因此，根转换具有一个有用的坐标空间，范围从 (0, 0) 到 (logical_size.width, logical_size.height)，其中 (0, 0) 是左上角。

设置根转换会在根转换上安装全屏点击区域。如果客户端不希望用户能够与根转换的内容互动，则可以移除此点击区域。如需详细了解点击区域，请参阅 SetHitRegions 文档。

默认命中区域规则

默认命中区域遵循以下规则：

  • 调用 SetRootTransform(T) 时，T 会收到一个覆盖整个视图的最大点击区域。
  • 如果在 SetRootTransform(T) 之前或之后对 T 调用 SetHitRegions，则不会激活默认点击区域，而是使用客户端指定的点击区域。
  • 如果某个转换不再是根转换，即SetRootTransform(U) 时，原始转换将不再具有其默认命中区域。
  • 客户端可以移除或修改根转换的命中区域，方法与重置任何其他转换的命中区域相同，即使用适当的矢量调用 SetHitRegions。

请求

名称类型
transform_id TransformId

SetScale

设置转换的缩放比例。几何属性的应用顺序如上所述。VecF |scale| 中的 (x,y) 值分别指 x 轴（宽度）和 y 轴（高度）上的缩放比例。缩放值必须是正 32 位浮点值：https://en.wikipedia.org/wiki/Normal_number_%28computing%29

请求

名称类型
transform_id TransformId
scale fuchsia.math/VecF

SetSolidFill

定义填充矩形的颜色和大小。|rect_id| 必须引用通过调用 CreateFilledRect 创建的内容。颜色未预乘。颜色值必须在 [0,1] 范围内（含 0 和 1），并且是正常的 32 位浮点值：https://en.wikipedia.org/wiki/Normal_number_%28computing%29。不符合这些规范的值会导致通道关闭。矩形的左上角将位于其转换坐标空间的 (0, 0) 处。 因此，其右下角将位于 (size.width, size.height)。

rect_id 必须引用有效的、未释放的填充矩形。

已弃用：33

请求

名称类型
rect_id ContentId
color ColorRgba
size fuchsia.math/SizeU

SetStackLayers

设置堆栈中的层。向量中图层的顺序决定了其 Z 轴顺序，其中第一个元素位于最底层，最后一个元素位于最顶层。

stack_id 必须引用有效的未释放 LayerStack。layers 的每个元素都必须引用一个有效的、未发布的层。layers 中不允许有重复的层。

请求

名称类型
stack_id LayerStackId
layers vector<LayerId>:32

SetTransformContent

设置（或清除）Transform 的内容。

同一内容可以附加到多个 Transform；每个附件都会在其自己的 Transform 矩阵、剪辑和不透明度下再次合成该内容，因此单个 LayerStack 或 Viewport 可以在场景中重复出现，而无需客户端复制底层资源。

如果不提供可选的 content，则可以清除 Transform 的内容。

如果设置了 content，它必须引用有效的、未发布的 LayerStack 或 Viewport。 与传统的 Flatland.SetContent 不同，零 ID 不会清除内容。

请求

名称类型
transform_id TransformId
content TransformContent?

SetTranslation

所有 Transform 对象都支持所有属性。

几何属性按以下顺序应用：

  1. 缩放（相对于父级转换的坐标空间）
  2. 方向（相对于父级转换的坐标空间）
  3. 平移（相对于父级转换的坐标空间，不受应用于当前转换的缩放比例的影响）。
  4. 剪裁（相对于当前转换的坐标空间）

这些属性的效果是累积的。这意味着，系统会根据该几何属性链（一直到根变换）计算变换在视图空间中的位置及其剪裁边界。

例如，在如下所示的嵌套层次结构中： [Root-Transform -> Transform1 -> Transform2 -> CurrentTransform] 如果 Transform1 平移了 [2,0]，Transform2 平移了 [0,1]，则 CurrentTransform 的视图空间位置将为 [2,1]。

设置 Transform 的平移。几何属性的应用顺序如上所述。

请求

名称类型
transform_id TransformId
translation fuchsia.math/Vec

SetViewportProperties

转换通常足以改变内容的呈现方式。不过，视口具有不属于 Transform 层次结构的特殊属性。这些属性可以使用此函数进行设置。

已弃用：33

请求

名称类型
viewport_id ContentId
properties ViewportProperties

SetViewportProperties2

设置视口的属性。

请求

名称类型
viewport_id ViewportId
properties ViewportProperties

Flatland2

在 fuchsia.ui.composition/flatland2.fidl 中定义

此协议已整合到“经典”Flatland 协议中，并清理了原始设计中的一些“瑕疵”。

此协议中定义的所有方法仅在启用 Flatland2 时可用（例如，通过 TrustedFlatlandConfig.use_flatland2_api）。在未启用 Flatland2 的情况下调用这些方法会导致通道关闭。

从广义上讲，“瑕疵”涉及在不应该设置属性的情况下在图片上设置属性。 例如，应该可以并排显示同一图片的两个副本，其中一个图片翻转 LEFT_RIGHT 以反映另一个图片。这在传统的 Flatland API 中是不可能的，因为翻转是图片的属性。在 Flatland2 中，翻转是图层的一个属性，客户端的目标可以通过两个具有相同图片和不同翻转的图层轻松实现。

启用 Flatland2 后，某些“经典”Flatland 方法会被停用/不合法。 这些方法最终将被移除；Flatland2 将成为在 Flatland 中显示图片的标准方式。在此之前，这种“选择启用”方法为客户提供了一种迁移到此现代化 API 的便捷方式。停用的方法包括：

添加：HEAD

CreateImage2

创建 Image 资源。

image_id 必须满足 LayerId 中记录的标识符规则。

请求

名称类型
image_id ImageId
import_token BufferCollectionImportToken
vmo_index uint32
properties ImageProperties

CreateLayer

Layer 是一种 Content，用于合成单个 Image 或纯色。它将视觉属性（例如大小、翻转、不透明度和混合）与原始像素数据分开。

与代表静态视觉资源的典型 Content 项不同，图层旨在作为图片序列的动态容器。典型用法包括不频繁地设置图层的视觉属性和图片元数据，然后快速将活跃的 Image（例如在每一帧上）与具有匹配元数据的另一张图片进行交换。

通过这种分离，单个 Image 资源可以同时在具有不同视觉配置的多个层中重复使用。

如需使用 Layer，请执行以下操作：

  1. 使用 CreateLayer 创建 Layer。
  2. 通过 SetLayerProperties 在 Layer 上设置属性，包括合成模式。
  3. 对于图片层，通过 SetLayerImage 将 Image 与 Layer 相关联。
  4. 通过 SetStackLayers 将 Layer 添加到 LayerStack。
  5. 通过 SetTransformContent 将 LayerStack 设置为节点的内容。

layer_id 必须满足 LayerId 中记录的标识符规则。

请求

名称类型
layer_id LayerId

CreateLayerStack

使用指定的 stack_id 创建新的图层堆栈。

stack_id 必须满足 LayerId 中记录的标识符规则。

请求

名称类型
stack_id LayerStackId

CreateViewport2

创建 Viewport 资源。

viewport_id 必须满足 LayerId 中记录的标识符规则。

请求

名称类型
viewport_id ViewportId
token fuchsia.ui.views/ViewportCreationToken
properties ViewportProperties
child_view_watcher server_end:ChildViewWatcher

ReleaseImage2

当不再需要渲染时，系统会通过垃圾回收机制回收已释放的图片。对于图片，这意味着：

  • 该 Image 不再绑定到任何 Layer，并且
  • 任何引用该 Image 的待处理渲染都已完成。

image_id 值会立即释放，供客户端重复使用（标识符唯一性是瞬时的）。

注意：每个绑定的释放栅栏（传递给 SetLayerImage）不受此调用的影响。 它们跟踪的是各个层绑定的生命周期，而不是客户端的 image_id。

image_id 必须引用有效的未发布映像。

请求

名称类型
image_id ImageId

ReleaseLayer

一旦不再需要渲染，系统就会对已释放的层进行垃圾回收。对于图层，这意味着：

  • 任何 LayerStack 都不再引用该 Layer，并且
  • 任何引用该层的待处理渲染均已完成。

layer_id 必须引用有效的未发布层。

请求

名称类型
layer_id LayerId

ReleaseLayerStack

释放具有指定 stack_id 的层堆栈。

请求

名称类型
stack_id LayerStackId

ReleaseViewport2

从场景中释放 Viewport。

请求

名称类型
viewport_id ViewportId

响应

名称类型
token fuchsia.ui.views/ViewportCreationToken

ResetLayer

解除与该层绑定的所有 Image，并清除每个存储的 LayerProperties 字段，使该层恢复到新创建的状态（合成模式 INVISIBLE，所有属性均采用其记录的默认值）。这是唯一会忘记存储的图层属性的操作。

layer_id 必须引用有效的未发布层。

请求

名称类型
layer_id LayerId

SetLayerImage

将图片与图层相关联。

该绑定在任何合成模式下都是合法的，并且具有粘性：它在合成模式更改后仍然有效，并且只能由后续的 SetLayerImage 调用替换（或由 ResetLayer 清除）。仅当图层的合成模式为 IMAGE 时，系统才会显示图片。

绑定的图片必须足够大，才能容纳图层存储的 sample_rect；这会在 fuchsia.ui.composition/Flatland.Present 中进行检查，而不是在此处。请参阅 LayerProperties.sample_rect。

layer_id 必须引用有效的未发布层。 image_id 必须引用有效的未发布映像。 acquire_fence 是一个可选围栏，必须在显示图片之前发出信号。release_fence 是一个可选栅栏，当此绑定不再引用映像时，Scenic 会发出信号。它是按绑定（而非按图片）进行的：绑定到多个层的图片每个绑定都有一个这样的栅栏，并且只有在每个栅栏都发出信号后，图片才能安全写入。

绑定通过以下方式结束：

  • 被同一图层上后续的 SetLayerImage 取代
  • ResetLayer
  • 通过 ReleaseLayer 或由层堆栈释放，使层引用计数达到零
  • 销毁会话，这会结束会话持有的每个绑定

对于在会话处于活跃状态时结束的绑定，Scenic 会在绑定结束后的第一帧退出时发出信号。从未到达屏幕的绑定（例如，在单个批次中被取代的绑定，或者在多个 fuchsia.ui.composition/Flatland.Present 调用被压缩到单个帧中时丢失的绑定）会在同一停用时发出信号，而不是立即发出信号。因此，该信号最多会保守一帧，绝不会提前。

请求

名称类型
layer_id LayerId
image_id ImageId
acquire_fence WaitFence?
release_fence SignalFence?

SetLayerProperties

设置图层的属性。

提供的 properties 表会合并到图层的存储属性中：在 properties 中未设置的字段会保留其先前存储的值。存储的属性具有粘性；如需了解完整的持久性语义，请参阅 LayerProperties。

值会按原样存储；依赖于其他状态（尤其是针对绑定图片的 sample_rect）的验证会在 fuchsia.ui.composition/Flatland.Present 处进行。请参阅 LayerProperties.sample_rect。

layer_id 必须引用有效的未发布层。

请求

名称类型
layer_id LayerId
properties LayerProperties

SetStackLayers

设置堆栈中的层。向量中图层的顺序决定了其 Z 轴顺序，其中第一个元素位于最底层，最后一个元素位于最顶层。

stack_id 必须引用有效的未释放 LayerStack。layers 的每个元素都必须引用一个有效的、未发布的层。layers 中不允许有重复的层。

请求

名称类型
stack_id LayerStackId
layers vector<LayerId>:32

SetTransformContent

设置（或清除）Transform 的内容。

同一内容可以附加到多个 Transform；每个附件都会在其自己的 Transform 矩阵、剪辑和不透明度下再次合成该内容，因此单个 LayerStack 或 Viewport 可以在场景中重复出现，而无需客户端复制底层资源。

如果不提供可选的 content，则可以清除 Transform 的内容。

如果设置了 content，它必须引用有效的、未发布的 LayerStack 或 Viewport。 与传统的 Flatland.SetContent 不同，零 ID 不会清除内容。

请求

名称类型
transform_id TransformId
content TransformContent?

SetViewportProperties2

设置视口的属性。

请求

名称类型
viewport_id ViewportId
properties ViewportProperties

FlatlandDisplay

在 fuchsia.ui.composition/flatland.fidl 中定义

此 API 连接到单例“主屏幕”，并允许在下方附加 Flatland 内容树。一次只能有一个 FlatlandDisplay 客户端连接。

SetContent

请求

名称类型
token fuchsia.ui.views/ViewportCreationToken
child_view_watcher server_end:ChildViewWatcher

SetDevicePixelRatio

设置应为此屏幕上附加的 Flatland 内容树使用的屏幕物理像素与设备无关像素的比率。如需了解详情，请参阅 LayoutInfo.device_pixel_ratio。

默认值为 (1.0, 1.0)。有效值为 1.0 及以上。

请求

名称类型
device_pixel_ratio fuchsia.math/VecF

FlatlandFactory

在 fuchsia.ui.composition/flatland_factory.fidl 中定义

用于生成常规（不受信任）Flatland 会话的工厂协议。

添加：HEAD

CreateFlatland

使用指定配置创建新的 Flatland 会话。

客户端应乐观地假设连接成功，并立即开始流水线化 fuchsia.ui.composition/Flatland 请求，而无需等待此方法返回。如果会话创建失败，fuchsia.ui.composition/FlatlandFactory 服务器会关闭 Flatland 会话通道，并返回 fuchsia.ui.composition/FlatlandFactoryError。 客户端应异步处理此故障并舍弃其 Flatland 客户端端点。

错误

如果操作失败，则返回 FlatlandFactoryError。

请求

名称类型
server_end server_end:Flatland
config FlatlandConfig

响应

名称类型
payload FlatlandFactory_CreateFlatland_Result

ParentViewportWatcher

在 fuchsia.ui.composition/flatland.fidl 中定义

一种协议，用于提供有关附加到 Flatland 会话的唯一 View 的父 Viewport 的信息。虽然 Flatland 会话最多只能有一个视图，但在将一个会话的视图替换为另一个视图（例如通过 CreateView）的短暂过渡期内，可能会有多个 ParentViewportWatcher。在此期间，某些更新可能会重复并发送到每个 ParentViewportWatcher 连接。

只要相应的父级 Viewport 存在，ParentViewportWatcher 就会保持连接状态；如果父级的 ViewportCreationToken 在未使用的情况下被丢弃，连接也会关闭。

GetLayout

用于接收布局信息的挂起 get。客户端可能会在 ParentViewportWatcher 操作呈现之前收到布局信息。这样，子项就可以在首次调用 Present 之前布局其内容。在同时存在两个 ParentViewportWatcher 渠道的过渡情况下，两个协议会话都将收到不同的布局信息。

仅当 LayoutInfo 与之前返回的 LayoutInfo 不同时，此挂起获取才会触发。请注意，由于 LayoutInfo 是一个表，因此可能只有部分字段发生了更改。

在上一次调用仍处于待处理状态时，调用 GetLayout 是无效的。这样做会导致此通道和分发 ParentViewportWatcher 的 Flatland 通道都关闭。

请求

<EMPTY>

响应

名称类型
info LayoutInfo

GetStatus

用于接收父级 Viewport 状态的挂起 GET。这会向子级提供全局连接信息。

仅当 ParentViewportStatus 与之前返回的 ParentViewportStatus 不同时，此挂起获取才会触发。

在上一次调用仍处于待处理状态时，调用 GetStatus 是无效的。这样做会导致此通道和分发 ParentViewportWatcher 的 Flatland 通道都关闭。

请求

<EMPTY>

响应

名称类型
status ParentViewportStatus

ScreenCapture

在 fuchsia.ui.composition/screen_capture.fidl 中定义

此协议提供了一个低级 ScreenCapture API 供客户端使用。 ScreenCapture 客户端应熟悉 fuchsia.sysmem/BufferCollection 和 fuchsia.ui.composition/Allocator 协议，因为这些协议是创建 ScreenCapture 使用的 BufferCollection 和图片所必需的。

配置

客户端应首先使用 Allocator 协议注册 BufferCollection。除非 BufferCollection 的所有客户端都已设置其限制，否则此函数将失败并显示 BAD_OPERATION。

之后，客户端应创建并配置最终将使用此方法渲染到的图片。集合中从 0 到 (buffer_count-1) 的所有缓冲区都可用于屏幕截图。

客户端负责确定显示屏的旋转角度，并应用校正旋转。例如，如果显示屏顺时针旋转 90 度（从正面看显示屏时，“顶部”在右侧），则客户端应指定 270 度旋转来解决此问题。

同样，客户端负责为旋转后的图片指定足够大的缓冲区。如果缓冲区太小，系统会尽力渲染图片。

最后，客户端会请求服务器使用 GetNextFrame 将当前屏幕渲染到共享缓冲区。

如果客户端希望更改任何配置设置，可以使用新的 BufferCollectionImportToken 再次调用 Configure。在这种情况下，之前调用 Configure 时使用的所有缓冲区都将被释放。

请求

名称类型
payload ScreenCaptureConfig

响应

名称类型
payload ScreenCapture_Configure_Result

GetNextFrame

成功调用 Configure 后，客户端可以调用 GetNextFrame。这会使用最新帧填充缓冲区。

客户端应等待其传递的 zx::event 成功完成屏幕截图。无法保证在函数返回时屏幕截图已完成。

请求的图片将位于客户端在 VMO 中设置的 BufferCollection 中，其索引由 buffer_id 指定。

当使用 ScreenCapture 提供视频流时，客户端调用 GetNextFrame 的速率将决定帧速率。

错误： BAD_OPERATION：如果未调用 Configure 或未成功调用 MISSING_ARGS：如果缺少必需的参数 BUFFER_FULL：如果 BufferCollection 中的所有缓冲区都在使用中。在这种情况下，必须先调用 ReleaseFrame 以使缓冲区可用，然后才能成功调用此函数。

请求

名称类型
payload GetNextFrameArgs

响应

名称类型
payload ScreenCapture_GetNextFrame_Result

ReleaseFrame

当客户端不再需要某个图片时，可以对缓冲区的 VMO 索引调用 ReleaseFrame，以便服务器将来可以重复使用该图片。

请求

名称类型
buffer_id uint32

响应

名称类型
payload ScreenCapture_ReleaseFrame_Result

屏幕截图

在 fuchsia.ui.composition/screenshot.fidl 中定义

收集显示屏的当前图形内容。

步行

在 sRGB 色彩空间中，将显示屏的当前图形内容收集到指定的缓冲区 format 中。请注意，sRGB 色彩空间是非线性的，这意味着，如果单元测试使用非完全饱和的颜色进行像素等效性检查，则应转换为线性色彩空间。

如需了解详情，请参阅 https://fuchsia.dev/fuchsia-src/concepts/ui/scenic/color_spaces。

系统会立即截取屏幕截图，并填充最近一次 VSYNC 的显示内容。

如果客户端在第一个 Take 调用返回之前再次调用 Take，服务器将关闭屏幕截图连接，并显示 ZX_ERR_SHOULD_WAIT 墓志铭。

如果捕获因内部错误而失败，服务器将关闭屏幕截图连接，并显示 ZX_ERR_INTERNAL 墓志铭。

请求

名称类型
payload ScreenshotTakeRequest

响应

名称类型
payload ScreenshotTakeResponse

TakeFile

在 sRGB 色彩空间中，将显示屏的当前图形内容收集到指定的缓冲区 format 中。请注意，sRGB 色彩空间是非线性的，这意味着，如果单元测试使用非完全饱和的颜色进行像素等效性检查，则应转换为线性色彩空间。

TODO(https://fxbug.dev/42065844)：在 fuchsia.dev 文档上线后，添加指向该文档的链接。

系统会立即截取屏幕截图，并填充最近一次 VSYNC 的显示内容。

如果客户端在第一个 TakeFile 调用返回之前再次调用 TakeFile，服务器将关闭屏幕截图连接，并显示 ZX_ERR_SHOULD_WAIT 墓志铭。

如果捕获因内部错误而失败，服务器将关闭屏幕截图连接，并显示 ZX_ERR_INTERNAL 墓志铭。

如果客户端位于主机上且不支持 VMO（例如 ffx 工具），则应使用此调用。

请求

名称类型
payload ScreenshotTakeFileRequest

响应

名称类型
payload ScreenshotTakeFileResponse

TrustedFlatland

在 fuchsia.ui.composition/trusted_flatland_factory.fidl 中定义

一种特权协议，适用于需要特殊功能的可信 Flatland 会话。

此协议已组合到 [Flatland] 协议中。只有在通过 [TrustedFlatlandFactory] 创建 Flatland 会话时，此协议中的方法才可用。

添加：HEAD

ReleaseImageImmediately

立即释放图片，而无需等待下一次呈现。

请求

名称类型
image_id ContentId

ReleaseImageImmediately2

立即释放 Image，而无需等待下一次呈现。这是一条可信的内存逐出路径。

该图片会强制与当前引用它的所有图层解除绑定。这些图层的行为就像从未设置过其图片一样（它们不可见，但会保留其图片属性），直到下一次 SetLayerImage()。

被逐出 Image 的绑定的所有待处理释放栅栏都将在最早的安全点发出信号。

仅当 Flatland2 处于启用状态且会话可信时，此方法才可用。

请求

名称类型
image_id ImageId

TrustedFlatlandFactory

在 fuchsia.ui.composition/trusted_flatland_factory.fidl 中定义

用于创建具有特殊配置的 Flatland 会话的特权工厂。

此协议适用于需要对 Flatland 行为进行精细控制以实现性能关键型应用的可信客户端。它不适用于一般用途。滥用此 API 可能会对系统性能和稳定性产生负面影响。

添加：HEAD

CreateFlatland

使用指定配置创建新的 Flatland 会话。

错误

如果操作失败，则返回 [TrustedFlatlandFactoryError] 错误。

请求

名称类型
server_end server_end:Flatland
config TrustedFlatlandConfig

响应

名称类型
payload TrustedFlatlandFactory_CreateFlatland_Result

STRUCTS

Allocator_RegisterBufferCollection_Response

在 fuchsia.ui.composition/allocator.fidl 中定义

<EMPTY>

BufferCollectionExportToken 资源

在 fuchsia.ui.composition/allocator.fidl 中定义

事件对的类型化封装容器，表示缓冲区集合的注册表端点。

字段类型说明默认
value handle<eventpair> 无默认应用

BufferCollectionImportToken 资源

在 fuchsia.ui.composition/allocator.fidl 中定义

事件对的类型化封装容器，表示缓冲区集合的图片导入端点。

字段类型说明默认
value handle<eventpair> 无默认应用

ColorRgba

在 fuchsia.ui.composition/flatland.fidl 中定义

表示具有 Alpha 通道的颜色。 这些值是 unorm（即有效范围为 [0,1]），并且位于线性色彩空间中。它们未经伽马校正，也未预乘。

字段类型说明默认
red float32 无默认应用
green float32 无默认应用
blue float32 无默认应用
alpha float32 无默认应用

ContentId

在 fuchsia.ui.composition/flatland.fidl 中定义

特定内容的用户定义标识符。如需了解详情，请参阅内容创建函数（例如 CreateViewport、CreateImage）。

字段类型说明默认
value uint64 无默认应用

FlatlandFactory_CreateFlatland_Response

在 fuchsia.ui.composition/flatland_factory.fidl 中定义

<EMPTY>

HitRegion

在 fuchsia.ui.composition/flatland.fidl 中定义

View 的互动区域，位于特定 Transform 的坐标空间中。

字段类型说明默认
region fuchsia.math/RectF

此点击区域的位置和大小，位于拥有此点击区域的转换的坐标空间中。

 无默认应用
hit_test HitTestInteraction

为此点击区域指定的互动行为。 如需指定“完全不互动”，请从所属 Transform 中移除此命中区域。

 无默认应用

ImageId

在 fuchsia.ui.composition/flatland2.fidl 中定义

使用 Flatland.CreateImage2 创建的特定映像的用户定义标识符。

零绝不是有效的 ImageId；LayerId 中记录的共享标识符规则也适用。

添加：HEAD

字段类型说明默认
value uint64 无默认应用

LayerId

在 fuchsia.ui.composition/flatland2.fidl 中定义

零标识符：对于这些类型中的任何一种，零都不是有效的标识符；每个 Create* 方法都会拒绝它。与经典 API（例如，Flatland.SetContent 接受 ID 0 来清除转换的内容）不同，Flatland2 绝不使用零 ID 来表示清除；在可以清除的情况下，通过省略可选字段来表示（请参阅 Flatland.SetTransformContent）。

特定图层的用户定义标识符。如需了解详情，请参阅 Flatland.CreateLayer 和 Flatland.ReleaseLayer。

添加：HEAD

字段类型说明默认
value uint64 无默认应用

LayerStackId

在 fuchsia.ui.composition/flatland2.fidl 中定义

使用 Flatland.CreateLayerStack 创建的特定层堆栈的用户定义标识符。

零绝不是有效的 LayerStackId；LayerId 中记录的共享标识符规则也适用。

添加：HEAD

字段类型说明默认
value uint64 无默认应用

ScreenCapture_Configure_Response

在 fuchsia.ui.composition/screen_capture.fidl 中定义

<EMPTY>

ScreenCapture_ReleaseFrame_Response

在 fuchsia.ui.composition/screen_capture.fidl 中定义

<EMPTY>

TransformId

在 fuchsia.ui.composition/flatland.fidl 中定义

特定转换的用户定义标识符。如需了解详情，请参阅 CreateTransform 和 ReleaseTransform。

字段类型说明默认
value uint64 无默认应用

TrustedFlatlandFactory_CreateFlatland_Response

在 fuchsia.ui.composition/trusted_flatland_factory.fidl 中定义

<EMPTY>

ViewportId

在 fuchsia.ui.composition/flatland2.fidl 中定义

使用 Flatland.CreateViewport2 创建的特定视口的用户定义标识符。

零绝不是有效的 ViewportId；LayerId 中记录的共享标识符规则也适用。

添加：HEAD

字段类型说明默认
value uint64 无默认应用

枚举

BlendMode strict

类型：uint32

在 fuchsia.ui.composition/flatland.fidl 中定义

在确定如何将图片合成到其他图片之上时，可供选择的一组可能的混合函数。

已弃用：33

名称值说明
1

表示源像素会替换目标像素。换句话说，无论设置了什么 Alpha 值，源像素都会被视为不透明。
2

源像素绘制在目标像素之上。最终显示的像素颜色计算公式为：C_src + (1.0 - alpha_src) * C_dst)。

BlendMode2 灵活

类型：uint32

在 fuchsia.ui.composition/flatland.fidl 中定义

在确定如何将图片合成到其他图片之上时，可供选择的一组可能的混合函数。

新增：29

名称值说明
1

表示源像素会替换目标像素：源像素值（包括 Alpha 值）会按原样写入输出，而不会与目标像素混合。具有部分或零 alpha 的源像素会以该 alpha 完整地标记到输出中；它不会被视为不透明。（这描述了混合函数本身；图层的 opacity 可以降级此模式。请参阅 LayerProperties.blend_mode。）
2

源像素绘制在目标像素之上。显示的最终像素颜色计算公式为：C_src + (1.0 - alpha_src) * C_dst。
3

源像素绘制在目标像素之上。最终显示的像素颜色计算公式为：alpha_src * C_src + (1.0 - alpha_src) * C_dst。

ChildViewStatus strict

类型：uint32

在 fuchsia.ui.composition/flatland.fidl 中定义

名称值说明
1

底层 Flatland 会话已连接其 View（称为 Present），并且已达到 Present 调用的获取围栏，这表示它有一些内容已准备好显示，而不是子内容实际上已显示在屏幕上（常见用例是父级在将子级附加到全局场景图之前等待子级内容准备就绪）。

CompositionMode strict

类型：uint32

在 fuchsia.ui.composition/flatland2.fidl 中定义

选择图层合成的内容：图片、纯色或不合成任何内容。

INVISIBLE 是新创建的状态。INVISIBLE 层在引用它的任何 LayerStack 中保持其位置，但对帧没有任何贡献。由于层属性是粘性的（请参阅 LayerProperties），因此通过 INVISIBLE 传递并返回不会丢失任何内容。

添加：HEAD

名称值说明
1
2
3

FlatlandError strict

类型：uint32

在 fuchsia.ui.composition/flatland.fidl 中定义

OnError 中返回的一组错误代码。任何错误都会导致 Flatland 通道关闭。

名称值说明
1

表示函数调用中使用的参数无效。
2

表示 additional_present_credits 字段未正确处理，并且客户端排队的 Present 数量超出了允许的数量。
3

表示客户端已覆盖返回的协议中的挂起获取。

FlatlandFactoryError flexible

类型：uint32

在 fuchsia.ui.composition/flatland_factory.fidl 中定义

使用 fuchsia.ui.composition/FlatlandFactory.CreateFlatland 时可能发生的错误。

添加：HEAD

名称值说明
1

客户端提供的配置无效，因此无法创建 Flatland 会话。
2

由于未指定的原因（并非客户端的错误），服务器无法建立 Flatland 会话。

HitTestInteraction 灵活

类型：uint8

在 fuchsia.ui.composition/flatland.fidl 中定义

点击区域预期的点击测试互动类型。

名称值说明
0

自然的默认行为是，点击区域会与常规点击测试和无障碍点击测试进行交互。
1

在某些用例中，点击区域需要与常规点击测试互动，但不能与无障碍点击测试互动。这里的“语义”是指无障碍功能的语义树数据，用于描述 View 中的界面元素。

ImageFlip strict

类型：uint32

在 fuchsia.ui.composition/flatland.fidl 中定义

在确定应如何显示图片纹理时，可供选择的一组可能的图片翻转函数。

已弃用：33

名称值说明
0
1

假设 V 是垂直反射轴，位于 width/2 处。然后，每个像素的 x 坐标都会在 V 上反射。y 坐标保持不变。例如： |1234| |4321| |abcd| 会变为 |dcba|
2

假设 H 是反射的水平轴，位于 height/2 处。然后，每个像素的 y 坐标都会在 H 上反射。x 坐标保持不变。例如： |1234| |abcd| |abcd| 会变成 |1234|

屏幕方向严格

类型：uint32

在 fuchsia.ui.composition/flatland.fidl 中定义

在 Flatland 中，+X 轴向右，+Y 轴向下。没有 Z 轴的概念。 由于缺少 Z 轴，因此在旋转方面没有“惯用手”（右手或左手）的数学概念。因此，我们定义逆时针旋转的方式，就像在屏幕上显示一个拟物化时钟一样，从观察者的视角来看，该时钟的指针以逆时针方向移动。

名称值说明
1
2
3
4

ParentViewportStatus strict

类型：uint32

在 fuchsia.ui.composition/flatland.fidl 中定义

当 ParentViewportWatcher 主动连接到输出显示屏（直接连接或通过父级 Viewport 链连接）以及未连接时，都会收到通知。在连接到显示屏之前，某些信息（例如像素比例）可能无法获取。

名称值说明
1
2

RegisterBufferCollectionError strict

类型：uint32

在 fuchsia.ui.composition/allocator.fidl 中定义

Allocator::RegisterBufferCollection() 返回的一组错误代码。

名称值说明
1

RegisterBufferCollectionUsage strict

类型：uint32

在 fuchsia.ui.composition/allocator.fidl 中定义

已注册缓冲区集合的可能用途。

名称值说明
0

DEFAULT 表示指定的缓冲区集合将用于 Flatland 和 gfx 映像创建。

如需了解详情，请参阅 fuchsia.ui.composition/Flatland.CreateImage。
1

SCREENSHOT 表示指定的缓冲区集合将用于屏幕截图。

轮换严格

类型：uint32

在 fuchsia.ui.composition/screen_capture.fidl 中定义

要应用于图片的旋转角度。

如果给定屏幕根据其 display_info 配置文件旋转了 270 度，那么应用等效且相反的旋转 CW_270_DEGREES 应该会抵消屏幕旋转，从而生成正确渲染的屏幕截图。

客户端应根据最终要使用的尺寸（即旋转后）分配图片。这些值与 display_info 配置文件中的 width 和 height 值相同。

名称值说明
0
1
2
3

ScreenCaptureError flexible

类型：uint32

在 fuchsia.ui.composition/screen_capture.fidl 中定义

ScreenCapture 协议可能出现的错误。

名称值说明
1

表参数中缺少一个或多个必需参数。
2

一个或多个参数无效。
3

方法调用期间发生常规错误。
4

如果 BufferCollection 中的所有 VMO 都已渲染，则调用 GetNextFrame 时会返回错误。必须先调用 ReleaseFrame，然后才能成功调用 GetNextFrame。

ScreenshotFormat flexible

类型：uint8

在 fuchsia.ui.composition/screenshot.fidl 中定义

可请求的不同屏幕截图格式。

名称值说明
0

默认格式，请求具有 32 位 BGRA 像素的紧密封装像素数据。
2

请求具有 32 位 RGBA 像素的紧密打包像素数据。
1

请求压缩为 PNG 格式的紧密打包像素数据。

TrustedFlatlandFactoryError flexible

类型：uint32

在 fuchsia.ui.composition/trusted_flatland_factory.fidl 中定义

使用 [TrustedFlatlandFactory] 时可能发生的错误。

添加：HEAD

名称值说明
1

方法调用期间发生常规错误。如果配置无效或系统无法创建新的 Flatland 会话，就可能会发生这种情况。

TABLES

FlatlandConfig

在 fuchsia.ui.composition/flatland_factory.fidl 中定义

用于实例化常规 Flatland 会话的配置参数。

添加：HEAD

序数字段类型说明
use_flatland2 bool

如果为 true，则选择将会话纳入 Flatland2 API Surface 和层数据模型。 默认设置为 false。

FrameInfo 资源

在 fuchsia.ui.composition/screen_capture.fidl 中定义

有关由 GetNextFrame 渲染的帧的元数据。

序数字段类型说明
buffer_id uint32

已渲染所请求帧的 VMO 的索引。必填。

GetNextFrameArgs 资源

在 fuchsia.ui.composition/screen_capture.fidl 中定义

传递到 GetNextFrame 调用的参数。所有字段均为必填项。

序数字段类型说明
event handle<event>

在请求的帧渲染完毕时发出信号的事件。必填。

ImageProperties

在 fuchsia.ui.composition/flatland.fidl 中定义

由客户端定义的 Image 的属性。这些属性决定了 Image 如何使用后备 BufferCollection。如需了解详情，请参阅 CreateImage。

序数字段类型说明
size fuchsia.math/SizeU

图片的大小（以像素为单位）。

LayerProperties

在 fuchsia.ui.composition/flatland2.fidl 中定义

与层关联的有状态属性。

所有字段都是粘性的：SetLayerProperties 会将提供的表合并到图层的存储属性中，并且存储的值会在 SetLayerImage 调用和合成模式更改期间保持不变。当前“撰写”模式未使用的字段会保留其值，并在重新进入使用这些字段的模式时再次生效。系统不会隐式清除任何内容；ResetLayer 是唯一会忘记存储的属性的操作。

**提示（安全和性能语义）**：提示（例如 hint_damage_rects 和 hint_visible_rects）是客户端提供的可选优化详细信息。

  • 设计上可忽略：实现可以自由忽略这些提示。如果忽略，渲染仍然完全正确，但可能不是最佳。
  • 正确的提示：产生相同的视觉效果，但可能会提高性能（例如，通过允许组合快捷方式或部分更新）。
  • 提示不正确：可能会导致渲染伪影、过时区域或显示屏上的像素不正确，因为实现可能会基于错误的假设进行优化。
添加：HEAD

序数字段类型说明
display_rect fuchsia.math/RectU

层内容将在其本地坐标空间中显示的矩形。

对于图片图层，视觉属性会按以下顺序应用：

  1. 示例：从图片中提取 sample_rect 指定的区域。
  2. Transform：采样区域会按照 transform 的指定进行翻转和旋转。
  3. 缩放/自适应：转换后的内容会隐式缩放以适应 display_rect。

当转换后的 sample_rect 的尺寸与 display_rect 的范围不同时，系统会隐式请求硬件图片缩放。并非所有显示硬件都支持缩放，或者可能存在限制。

display_rect 的尺寸必须考虑旋转引起的图像尺寸变化，以避免隐式缩放或失真。例如，如果将 600x300 像素的区域旋转 90 度，则需要在此处指定 300x600 尺寸，以保持宽高比。

注意：此矩形是在 LayerStack（或 LayerStack 附加到的转换）的局部空间中指定的。Flatland 场景图中的父级转换所应用的任何缩放都会进一步影响物理显示屏上的最终尺寸。

默认值：(0,0,0,0)。在设置宽度和高度不为零的矩形之前，该层将不可见。
opacity float32

图层的不透明度，范围为 [0..1]。

与从图层 LayerStack 上方的 Transform 继承的不透明度相乘（请参阅 fuchsia.ui.composition/Flatland.SetOpacity），得出图层的有效不透明度。该层的渲染效果就像其内容自身的 Alpha 值（图片像素的 Alpha 值，或纯色层的 color.alpha）按有效不透明度缩放一样；由于这需要混合，因此有效不透明度低于 1.0 的 REPLACE 层会渲染为 PREMULTIPLIED_ALPHA（请参阅 blend_mode）。有效不透明度为 0.0 的层不可见。

默认值：1.0（应用内容的自身 Alpha 值，不进行修改）。
blend_mode BlendMode2

用于将图层与下方内容合成的混合模式。

仅当图层的有效不透明度为 1.0 时，系统才会遵循 REPLACE（请参阅不透明度）；在有效不透明度较低时，图层会呈现为 PREMULTIPLIED_ALPHA，因此不透明度始终会使图层淡出。如需将精确的亚单位 Alpha 值写入输出（例如，为底层打孔），请在内容本身（图片自己的像素，或纯色图层的 color.alpha）中编写这些值，并将 opacity 保持为 1.0。

STRAIGHT_ALPHA 用于命名内容编码，对图片内容有意义。纯色层的编码由 API 固定（无论 blend_mode 如何，color 都是直通 RGBA），因此对于纯色内容，STRAIGHT_ALPHA 是可接受的，并且合成效果与 PREMULTIPLIED_ALPHA 相同。

默认值：BlendMode2.REPLACE。
color ColorRgba

用于填充图层的颜色，采用直通（非预乘）RGBA 格式，不考虑 blend_mode。合成器会执行渲染所需的任何转换。

默认值：不透明白色 (1.0, 1.0, 1.0, 1.0)。
sample_rect fuchsia.math/RectF

描述图片中要从中采样的区域，采用非标准化坐标（矩形宽度/高度与图片宽度/高度匹配）。

默认值：(0,0,0,0)，表示整个图片区域。客户端可以通过将此字段设置为 (0,0,0,0) 来重置为完整图片。

必须位于绑定图片的边界内。此检查在 fuchsia.ui.composition/Flatland.Present 期间进行，并且仅针对 composition_mode 为 IMAGE 的层，因此批处理中的调用顺序无关紧要：可以按任意顺序设置矩形和大小匹配的图片，并且在未绑定图片（或另一种模式生效）时设置的矩形会存储，而不会发出警告。Present 处的违规行为会关闭与 BAD_OPERATION 的连接。
transform FlipThenRotate

指定图片转换。

默认：无转换（恒等）。
hint_damage_rects vector<fuchsia.math/RectU>

一个提示，用于描述自上一帧以来已发生更改的源图片区域。 在源图片（缓冲区）的坐标空间中指定。

默认值：空向量（解释为整个样本矩形均已损坏）。

如需了解提示的一般安全性和性能语义，请参阅 LayerProperties。
hint_visible_rects vector<fuchsia.math/RectU>

描述屏幕上图层可见区域的提示。 在图层的局部坐标空间中指定（与 display_rect 匹配）。

默认值：空向量（解释为整个 display_rect 可见）。

如需了解提示的一般安全性和性能语义，请参阅 LayerProperties。
composition_mode CompositionMode

选择上述哪个属性组有效；请参阅 CompositionMode。

默认值：CompositionMode.INVISIBLE。

LayoutInfo

在 fuchsia.ui.composition/flatland.fidl 中定义

GetLayout 的返回值类型。此表包含客户端决定如何在 Flatland 会话中布局其内容所需的大部分信息。此数据可能会在创建 View 的命令呈现之前提供给客户端，以便客户端在首次调用 Present 之前正确布置内容。

序数字段类型说明
logical_size fuchsia.math/SizeU

View 的布局大小（以逻辑像素为单位），由父级对 SetViewportProperties 的调用定义。

逻辑大小还用作 View 的剪辑边界。剪辑边界之外的任何内容都不会渲染。因此，View 的根转换具有一个有用的坐标空间，即 (0, 0) 到 (logical_size.width, logical_size.height)。

当此值发生变化时，客户端应重新布局其内容。
device_pixel_ratio fuchsia.math/VecF

显示屏的物理像素与设备无关像素的比率。View 的每个逻辑像素都由一个或多个物理像素在屏幕上显示，具体取决于此比例。 当此值发生变化时，客户端不一定需要重新布局其内容，但应通过重新分配其图片缓冲区来适应变化，以避免采样伪影。支持 HiDPI 的客户端应分配大小为 (logical_size*device_pixel_ratio) 的缓冲区。
inset fuchsia.math/Inset

边缘与视图可见矩形之间的偏移量。客户端可以假定边衬区与视图边缘之间的边界区域被遮挡，并应调整内容布局以避开此区域。此边衬区在视图的逻辑坐标系中描述。支持 HiDPI 的客户端应按 device_pixel_ratio 缩放此值。

OnNextFrameBeginValues

在 fuchsia.ui.composition/flatland.fidl 中定义

客户端生成下一帧所需的字段，在 OnNextFrameBegin 中返回。每个字段都保证已设置并包含有效信息。

序数字段类型说明
additional_present_credits uint32

允许客户端发出的额外 Present 调用次数，以便客户端可以进一步调用 Present。这是当前积分预算的增量，而不是当前积分的绝对数量。
future_presentation_infos FuturePresentationInfos

有关客户端可能针对精确调度行为而设定的未来呈现和锁定时间的信息。

PresentArgs 资源

在 fuchsia.ui.composition/flatland.fidl 中定义

传递到 Present 的参数。所有参数都是可选的，如果省略某个参数，Flatland 将使用合理的默认值，如下所述。

序数字段类型说明
requested_presentation_time zx/Time

requested_presentation_time 指定客户端希望排队的操作在何时或何时之后产生可见效果（点亮屏幕上的像素），以 CLOCK_MONOTONIC 时基中的纳秒表示。

默认 requested_presentation_time 为 0。

如果使用当前或过去（例如 0）的 requested_presentation_time，则会将已加入队列的操作安排在准备下一个帧期间尽快生效。

如果使用未来的 requested_presentation_time，则会将已加入队列的操作安排在指定时间或指定时间之后（尽可能接近指定时间）产生可见效果，但不会早于指定时间。

每个渲染帧都有一个目标呈现时间。这是 Flatland 旨在向用户呈现帧的时间。在渲染帧之前，Flatland 会将与所有可压缩的 Present 调用相关联的所有已加入队列的操作应用于 requested_presentation_time 在帧的目标呈现时间或之前。
acquire_fences vector<handle<event>>:16

Flatland 会等到 Flatland 会话的所有 acquire_fences 都准备就绪后，再执行呈现的命令。不发出 acquire_fences 信号会阻止当前的 Present 以及后续的 Present，即使后续 Present 的 acquire_fences 已发出信号也是如此。

默认 acquire_fences 值为空向量。
release_fences vector<handle<event>>:16

当可以安全地重复使用在当前 Present 时不再出现在本地场景图中的资源时，Flatland 将向所有 release_fences 发出信号。最迟会在本地场景图（在此呈现时设置了检查点）集成到全局场景图且全局场景已显示在屏幕上时发生。

（在某些情况下，围栏可能会提前发出信号，但客户端无需担心这一点：只有在可以安全地重复使用关联资源时，围栏才会发出信号）。

这些围栏旨在管理共享内存资源（例如 sysmem 缓冲区）的重复使用。例如，客户端不应渲染到当前显示在屏幕上的图片，因为这可能会导致图形伪影（例如画面撕裂）。

客户端负责维护每个围栏与资源之间的映射，这些资源将在围栏收到信号时变为可重用。一种常见策略是跟踪上一个 Present 使用但当前 Present 不再使用的资源。例如，如果当前 Present 从场景中移除了某个图像，则客户端会在此处插入一个围栏。当围栏稍后收到信号时，客户端就知道可以安全地渲染到图像中，并在后续的 Present 中将其插入到本地场景图中。

如果发生错误，Flatland 可能会关闭通道，而不会发出这些围栏信号。客户端可以立即释放共享缓冲区，但不应立即修改此类缓冲区，因为它们可能仍会显示在屏幕上。目前，客户端无法获得关于何时可以安全地重复使用共享缓冲区的良好信号。

默认 release_fences 值为空向量。
unsquashable bool

如果 unsquashable 为 true，则保证更新在至少一个 vsync 间隔内唯一显示。

如果 unsquashable 为 false，则更新可以与其后面的更新合并。

如果不存在，则 unsquashable 为 false。
present_fences vector<handle<counter>>:16

当显示硬件报告与此 Present 对应的帧已显示时，Flatland 将向所有 present_fences 发出信号。此外，每个栅栏都会写入相应 VSYNC 的单调时间戳。

默认 present_fences 值为空向量。

添加：HEAD
release_counters vector<handle<counter>>:16

当可以安全地重复使用在当前 Present 时不再出现在本地场景图中的资源（即上一个 present 中的资源）时，Flatland 会向所有 release_counters 发出信号。这与 release_fences 类似，但使用的是计数器而不是事件，计数器会保留资源可以安全重复使用的单调时间戳。对于不关心此时间戳的资源，基于事件的 release_fences 可以与 release_counters 同时使用。

默认 release_counters 值为空向量。

添加：HEAD

RegisterBufferCollectionArgs 资源

在 fuchsia.ui.composition/allocator.fidl 中定义

RegisterBufferCollection 的参数表。请注意，以下部分字段为必填字段。

序数字段类型说明
export_token BufferCollectionExportToken

客户端可以发送 export_token，以便向 Allocator 注册缓冲区集合，供日后在 fuchsia.ui.composition/Flatland 实例或其他 Scenic API（例如 Screenshot）中使用。

例如，通过传递包含 BufferCollectionExportToken 匹配对等方的 BufferCollectionImportToken，它们可以通过 fuchsia.ui.composition/Flatland.CreateImage 创建图片资源。

客户端应先等待响应，然后再使用 import_token。

此字段为必填字段。
buffer_collection_token client_end:fuchsia.sysmem/BufferCollectionToken
移除：NEXT 弃用：25 添加：7
usage RegisterBufferCollectionUsage

客户端可以注册缓冲区集合以用于各种用途，每种用途都有其独特的限制。

此字段为选填字段。如果省略 usage，系统会将其视为具有 DEFAULT 选项。

弃用

此参数在 API 版本 9 中已弃用，并添加了 |usages|。

如果同时设置了 usages 和 usage 字段，则 usages 优先，usage 会被忽略。

已弃用：9
usages RegisterBufferCollectionUsages

客户端可以注册缓冲区集合以用于各种用途，并且可以根据需要组合多种用途。

此字段为选填字段。如果省略 usages，系统会将其视为仅具有 DEFAULT 选项。
buffer_collection_token2 client_end:fuchsia.sysmem2/BufferCollectionToken

Flatland 通过对 buffer_collection_token2（或 buffer_collection_token，在移除之前）引用的 BufferCollection 设置限制来参与缓冲区分配。在客户端使用 BufferCollection 创建内容之前，它不会阻止分配缓冲区。

只要客户端持有有效的 BufferCollectionImportToken，向 export_token 注册的缓冲区集合就可用并保持活跃状态。当所有 BufferCollectionImportToken 都关闭且所有关联的 Image 资源都释放后，系统会对其进行垃圾回收。

必须设置 buffer_collection_token2（或者在移除 buffer_collection_token 之前，必须且只能设置 buffer_collection_token2 和 buffer_collection_token 中的一个）。

新增：25

ScreenCaptureConfig 资源

在 fuchsia.ui.composition/screen_capture.fidl 中定义

传递到 Configure 调用的参数。请注意，并非所有字段都是必填字段。

序数字段类型说明
import_token BufferCollectionImportToken

引用向 Allocator 注册的 BufferCollection 的导入令牌。必填。
size fuchsia.math/SizeU

图片的尺寸（以像素为单位）。必填。
buffer_count uint32

BufferCollection 中的缓冲区数量。必填。
rotation Rotation

要应用于图片流的旋转角度。可选；如果不存在，则不应用旋转。

ScreenshotTakeFileRequest 资源

在 fuchsia.ui.composition/screenshot.fidl 中定义

序数字段类型说明
format ScreenshotFormat

所请求屏幕截图的格式。

ScreenshotTakeFileResponse 资源

在 fuchsia.ui.composition/screenshot.fidl 中定义

序数字段类型说明
file client_end:fuchsia.io/File

用于读取生成的屏幕截图文件数据的 |fuchsia.io.File| 通道。 通道的服务器端会存储在设备上，直到检测到 ZX_CHANNEL_PEER_CLOSED。

基本用法：客户端收到文件通道的客户端端点后，为避免内存堆积，应先完成数据读取，然后再调用 TakeFile。读取完毕后，客户端应在 |fuchsia.io.File| 通道上调用 Close，这将释放服务器端分配的内存。
size fuchsia.math/SizeU

屏幕截图的大小（以像素为单位）。

ScreenshotTakeRequest 资源

在 fuchsia.ui.composition/screenshot.fidl 中定义

序数字段类型说明
format ScreenshotFormat

所请求屏幕截图的格式。

ScreenshotTakeResponse 资源

在 fuchsia.ui.composition/screenshot.fidl 中定义

序数字段类型说明
vmo handle<vmo>

包含屏幕截图数据的 CPU 可映射只读 VMO。服务器拥有 VMO，并可将其重复用于下一个 Take。VMO 在映射后保证可访问。 在某些分配中，VMO::read() 可能不可用，例如在模拟器上。

基本用法：客户端收到 VMO 句柄后，为确保数据稳定性，应先完成 VMO 读取，然后再调用 Take。读取完毕后，客户端应丢弃 VMO 句柄。

高级用法：如需修改数据或在下次 Take 调用后保留数据，客户端应将数据复制到私有 VMO。
size fuchsia.math/SizeU

屏幕截图的大小（以像素为单位）。

TrustedFlatlandConfig 资源

在 fuchsia.ui.composition/trusted_flatland_factory.fidl 中定义

所有参数都是可选的；如果缺少参数，系统将提供默认值。 默认情况下，生成的 Flatland 的行为与连接到 [Flatland] 服务（而不是通过工厂连接）的行为完全相同。

添加：HEAD

序数字段类型说明
schedule_asap bool

如果为 true，并且传递给 [Flatland.Present] 的 [PresentArgs.requested_presentation_time] 设置为 0 或小于或等于最近的呈现时间，则系统会安排在所有获取栅栏发出信号后立即呈现帧，而不是等待其他客户端在同一 vsync 内呈现。这样，调用方就可以决定何时唤醒以准备帧。

如果 [requested_presentation_time] 设置为大于最近呈现时间的值，则此标志将不起作用，并且唤醒时间决策将由调度程序做出。

如果不存在，则 schedule_asap 为 false。
pass_acquire_fences bool

如果为 true，Scenic 应将获取栅栏传递给合成硬件的驱动程序，而不是在 CPU 上等待它们。这可以通过减少 CPU 开销来提高性能。

如果不存在，则 pass_acquire_fences 为 false。
skips_present_credits bool

如果为 true，则客户端不会利用 Flatland 的内置帧调度机制，而是会忽略当前点数，改为依赖自己的流控制系统。

如果不存在，则 skips_present_credits 为 false。
skips_on_frame_presented bool

如果为 true，客户端将不会收到 [Flatland.OnFramePresented] 事件。

如果不存在，则 skips_on_frame_presented 为 false。
use_flatland2_api bool

如果为 true，客户端可以使用 fuchsia.ui.composition/Flatland2 协议，该协议会组合到“经典”fuchsia.ui.composition/Flatland 协议中。

注意：启用 Flatland2 后，某些“经典”Flatland 方法会被停用；如需了解详情，请参阅 fuchsia.ui.composition/Flatland2 文档。

如果不存在，则 use_flatland2_api 为 false。

ViewBoundProtocols 资源

在 fuchsia.ui.composition/flatland.fidl 中定义

绑定到 Flatland ViewCreationToken 的协议端点。这些协议在 ViewCreationToken 在 Flatland 会话中创建的 View 上运行。

序数字段类型说明
view_ref_focused server_end:fuchsia.ui.views/ViewRefFocused

了解 View 何时获得焦点。

绑定到服务器的 ViewRef。view_ref_focused 客户端未明确指定 ViewRef；而是由服务器实现使用在创建 View 时使用的 ViewRef 来报告此 View 的焦点移动。
view_focuser server_end:fuchsia.ui.views/Focuser

使 View 能够请求将焦点转移到子（目标）View。

绑定到服务器的 ViewRef。view_focuser 客户端未明确指定“请求者”ViewRef，仅指定了“目标”ViewRef。而是使用在创建 View 时使用的 ViewRef 作为“请求者”ViewRef。
touch_source server_end:fuchsia.ui.pointer/TouchSource

接收与 View 关联的触摸事件。 它与 touch_source_v2 相互排斥。如果同时提供这两者，则会导致 FlatlandError.BAD_OPERATION 错误和通道关闭。
mouse_source server_end:fuchsia.ui.pointer/MouseSource

接收与 View 关联的鼠标事件。 它与 mouse_source_v2 相互排斥。如果同时提供这两者，则会导致 FlatlandError.BAD_OPERATION 错误和通道关闭。
touch_source_v2 server_end:fuchsia.ui.pointer/TouchSourceV2

接收与 View 关联的触摸事件。 它与 touch_source 相互排斥。如果同时提供这两者，则会导致 FlatlandError.BAD_OPERATION 错误和通道关闭。

添加：33
mouse_source_v2 server_end:fuchsia.ui.pointer/MouseSourceV2

接收与 View 关联的鼠标事件。 它与 mouse_source 相互排斥。如果同时提供这两者，则会导致 FlatlandError.BAD_OPERATION 错误和通道关闭。

添加：33

ViewportProperties

在 fuchsia.ui.composition/flatland.fidl 中定义

由父级定义的 Viewport 的属性。此数据以及一组附加的转换将用于计算视口视图的 LayoutInfo。ViewportProperties 必须至少设置一次 logical_size。这是将驱动子级布局的初始大小。

序数字段类型说明
logical_size fuchsia.math/SizeU

视口的大小（以逻辑像素为单位）。这会直接映射到 LayoutInfo 中的 logical_size 字段。有效的 logical_size 必须具有正 X 和 Y 分量。
inset fuchsia.math/Inset

边缘与视口可见矩形之间的偏移量。这会直接映射到 LayoutInfo 中的 inset 字段。有效边衬区的所有组件都必须大于或等于 0。

UNIONS

Allocator_RegisterBufferCollection_Result strict

在 fuchsia.ui.composition/allocator.fidl 中定义

序数变体类型说明
response Allocator_RegisterBufferCollection_Response
err RegisterBufferCollectionError

FlatlandFactory_CreateFlatland_Result strict

在 fuchsia.ui.composition/flatland_factory.fidl 中定义

序数变体类型说明
response FlatlandFactory_CreateFlatland_Response
err FlatlandFactoryError

ScreenCapture_Configure_Result strict

在 fuchsia.ui.composition/screen_capture.fidl 中定义

序数变体类型说明
response ScreenCapture_Configure_Response
err ScreenCaptureError

ScreenCapture_GetNextFrame_Result strict resource

在 fuchsia.ui.composition/screen_capture.fidl 中定义

序数变体类型说明
response FrameInfo
err ScreenCaptureError

ScreenCapture_ReleaseFrame_Result strict

在 fuchsia.ui.composition/screen_capture.fidl 中定义

序数变体类型说明
response ScreenCapture_ReleaseFrame_Response
err ScreenCaptureError

SignalFence 严格 资源

在 fuchsia.ui.composition/flatland2.fidl 中定义

当某些条件变为 true 时，Scenic 将发出信号的围栏。如需了解详情，请参阅围栏所在的方法。

添加：HEAD
序数变体类型说明
basic handle<handle>

基本句柄（例如 EVENT 或 EVENTPAIR）。
timestamp handle<counter>

在 Scenic 向围栏发出信号之前，它会将相应事件的时间戳写入计数器。

TransformContent strict

在 fuchsia.ui.composition/flatland2.fidl 中定义

启用 Flatland2 后可附加到 Transform 的内容。

此联合定义了可以使用 Flatland.SetTransformContent 附加到转换的内容类型。

添加：HEAD
序数变体类型说明
layer_stack LayerStackId
viewport ViewportId

TrustedFlatlandFactory_CreateFlatland_Result strict

在 fuchsia.ui.composition/trusted_flatland_factory.fidl 中定义

序数变体类型说明
response TrustedFlatlandFactory_CreateFlatland_Response
err TrustedFlatlandFactoryError

WaitFence strict resource

在 fuchsia.ui.composition/flatland2.fidl 中定义

当关联的资源可供 Scenic 使用时，系统会发出信号的围栏。 如需了解特定于上下文的使用信息，请参阅围栏所在的方法。

添加：HEAD
序数变体类型说明
basic handle<handle>

基本句柄（例如 EVENT 或 EVENTPAIR）。
timestamp handle<counter>

在发出围栏信号时，相应事件的时间戳将已写入计数器。

BITS

FlipThenRotate 严格执行

类型：uint8

在 fuchsia.ui.composition/flatland2.fidl 中定义

支持所有翻转和旋转排列组合的位集。先执行翻转（如果有），然后执行旋转（如果有）。

添加：HEAD

名称值说明
1

水平翻转图片（沿 Y 轴）。
2

垂直翻转图片（沿 X 轴）。
4

将图片顺时针旋转 90 度。

RegisterBufferCollectionUsages 灵活

类型：uint16

在 fuchsia.ui.composition/allocator.fidl 中定义

已注册缓冲区集合的可能用途。可以是选项的组合。

名称值说明
1

指定的缓冲区集合可用于 Flatland 和 GFX 映像创建。

如需了解详情，请参阅 fuchsia.ui.composition/Flatland.CreateImage。
2

指定的缓冲区集合可用于截屏。

常量

名称值类型说明
MAX_ACQUIRE_RELEASE_FENCE_COUNT 16 int32
MAX_CHILD_TRANSFORMS 64 int32

对于这些 API 的预期用途，最多 64 个子转换就足够了。调用方可以使用 AddChild 超出此限制。
MAX_HIT_REGION_COUNT 64 int32

对于这些 API 的预期用途，最多 64 个命中区域就足够了。
MAX_PRESENT_ARGS_FENCE_COUNT 16 int32
MAX_STACK_LAYERS 32 int32

每个堆栈最多 32 层，足以满足这些 API 的预期使用需求。

添加：HEAD

别名

名称值说明
FuturePresentationInfos vector[8]

未来展示信息的自定义标识符。对于这些 API 的当前用途，最多 8 个未来展示计数就足够了。