fuchsia.ui.scenic

已移除：17 已弃用：13 添加：7

协议

风景

在 fuchsia.ui.scenic/scenic.fidl 中定义

CreateSession

创建新会话，这是与景观互动的主要方式。

请求

名称类型
session server_end<Session>
listener SessionListener?

CreateSession2

创建新会话，这是与景观互动的主要方式。

在此变体中，调用方可以注册焦点管理请求。view_focuser 的客户端与所请求的 session 相连，此耦合充当安全边界：view_focuser 用作授权基础的 ViewRef 必须来自 session。

请求

名称类型
session server_end<Session>
listener SessionListener?
view_focuser server_end<fuchsia.ui.views/Focuser>?

CreateSessionT

创建新会话，这是与景观互动的主要方式。

在此变体中，调用方可能会提交对其有意义的协议组合。会话协议是唯一必需的协议。SessionEndpoint 表可以用更多协议字段进行扩展，但这些扩展应保持与现有（预编译）客户端的 ABI 和 API 兼容性。

响应会确认创建会话的请求，但实际创建的操作可能会在稍后进行。

请求

名称类型
endpoints SessionEndpoints

响应

<EMPTY>

GetDisplayInfo

获取有关景观区主要显示区的信息。

请求

<EMPTY>

响应

名称类型
info fuchsia.ui.gfx/DisplayInfo

GetDisplayOwnershipEvent

当屏幕所有权更改时，获取通过 displayOwnedSignal 或 displayNotOwnedSignal 发出信号的事件。

请求

<EMPTY>

响应

名称类型
ownership_event handle<event>

TakeScreenshot

截取屏幕截图并在 img_data 中返回数据。如果 success 为 false，img_data 将不包含 BGRA 数据。

请求

<EMPTY>

响应

名称类型
img_data ScreenshotData
success bool

UsesFlatland

返回客户端是否应改用 fuchsia.ui.composition/Flatland 协议与 Views 进行交互。

请求

<EMPTY>

响应

名称类型
flatland_enabled bool

会话

在 fuchsia.ui.scenic/session.fidl 中定义

客户端通过将创建或修改资源的命令加入队列，使用会话与“景观”实例进行交互。

DeregisterBufferCollection

取消注册之前向 buffer_id 注册的 BufferCollection，并将其设置为在资源不再引用时立即进行垃圾回收。

只有之前已注册但尚未取消注册的 buffer_id 才有效。

请求

名称类型
buffer_id uint32

加入队列

请求

名称类型
cmds vector<Command>

OnFramePresented

每当同时呈现一组（一个或多个） Present2 时，此事件就会被触发，因此不再处于飞行状态。

响应

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

演示

显示之前加入队列的所有操作。为了对渲染场景所需的资源的准备进行流水线处理，系统会传递两个栅栏列表（作为事件实现）。

安排演示时间

presentation_time 指定客户端希望加入队列的操作在什么时间或之后生效（屏幕上的点亮像素），以 CLOCK_MONOTONIC 时基中的纳秒表示。期望的呈现时间必须单调不减少。

使用当前或过去所需的呈现时间（例如 0）可安排已加入队列的操作尽快（在要准备的下一帧期间）生效。

在未来使用所需的呈现时间时，应让加入队列的操作尽可能接近或晚于指定时间（但不能更早）生效。

每个渲染帧都有一个目标呈现时间。在渲染帧之前，场景管理器会应用与之前调用 Present()（其所需呈现时间等于或早于帧的目标呈现时间）相关的所有已加入队列的操作。

在场景管理器开始准备第一帧（其中包含其呈现的内容）之前，Present() 方法不会返回。返回后，PresentationInfo 会提供包含所呈现内容的帧的时间信息。

如需在每个连续帧上呈现新内容，请等待 Present() 返回，然后再使用下一帧的内容再次调用 Present()。

还可以一次性将连续的内容帧加入队列并呈现所有帧，并且增加所需的呈现时间，每帧增加 PresentationInfo.presentation_interval。

动画更新也会根据呈现时间进行协调。

同步

View 使用 acquire_fences 等待会话的所有资源均可进行渲染（或允许下游组件（如 Vulkan 驱动程序）等待这些资源）。

例如，Fuchsia 的 Vulkan 驱动程序允许从 VkSemaphore 获取 zx::event。这样，景观客户端就可以提交 Vulkan 命令缓冲区，以生成图像/网格等，并指示 Vulkan 在完成后向 VkSemaphore 发出信号。通过将与此信号量对应的 zx::event 插入 acquire_fences，客户端允许 Views 将工作提交到 Vulkan 驱动程序，而无需等待 CPU 收到事件信号。

release_fences 是当更新后的会话状态被完全提交后，Scene 会向其发送信号的事件列表：未来的帧将使用此状态进行渲染，并且使用以前的会话状态生成的所有帧也已完全渲染并呈现给显示屏。

acquire_fences 和 release_fences 旨在允许客户端实现双缓冲等策略。例如，客户端可能会在 Views 子系统中执行以下操作：

  1. 创建两个资源 ID 为 1 和 2 的图片。
  2. 使用资源 ID 3 和 4 创建两个 Material，分别使用图片 1 和 2 作为纹理。
  3. 创建节点树并将其附加到场景中。
  4. 设置上面的一个节点（例如 5）以使用 Material #3。
  5. 提交 Vulkan 命令缓冲区，该缓冲区会渲染到映像 1，并发出 VkSemaphore 信号。
  6. 使用一个获取栅栏（从上述 VkSemaphore 获取）和一个新创建的释放栅栏调用 Present()。

完成上述步骤后，Sce 会在必要时使用承诺的会话状态渲染帧。当客户端想要显示与图片 1 不同的内容时，会执行类似于第 4 步到第 6 步的操作： 7) 将节点 5 设置为使用 Material 4。 8) 提交 Vulkan 命令缓冲区，该缓冲区会渲染到映像 1 中，并发出 VkSemaphore 信号。9) 使用一个获取栅栏（从上述 VkSemaphore 获取）和一个新创建的释放栅栏调用 Present()。

最后，为了不断绘制新内容，客户端可以重复步骤 4) 到步骤 9)，但有一个重要的区别：第 5 步) 必须等待由第 9 步发出信号的事件。否则，它可能会在图片 1 中渲染到图片 1 中，而这时街景功能仍在使用该图片渲染帧。同样，第 8 步）必须等待第 6 步发出的事件。

上述场景使用一个获取围栏和一个释放围栏，但很容易想象需要更多围栏的情况。例如，除了使用 Vulkan 渲染到映像 1 和 2 中之外，客户端可能还会将其他资源上传到其他 VkQueue 上的 Vulkan，这会发出单独的信号量信号，因此需要额外的获取栅栏。

注意：acquire_fences 和 release_fences 仅对于同步对内存（和其他外部资源）的访问是必需的。通过 Session API 对资源所做的任何修改都会自动同步。

请求

名称类型
presentation_time uint64
acquire_fences vector<event>
release_fences vector<event>

响应

名称类型
presentation_info fuchsia.images/PresentationInfo

Present2

显示之前加入队列的所有操作。为了对渲染场景所需的资源的准备进行流水线准备，传递了两个作为事件实现的栅栏列表。

当客户端调用 Present2 时，它们会立即收到一个回调，该回调包含的信息与使用等效的 requested_prediction_span 调用 RequestPresentationTimes 时获得的相同。如需了解详情，请参阅下面的文档，因为 Present2 的功能是它的超集。

然后，当 Present2 刷新的命令显示出来时，会触发 OnFramePresented 事件。此事件包含与具有属于该帧的内容的所有 Present2 相关的信息。

客户端在每个会话中只能使用“演示/展示 2”中的一个。 在两者之间切换是错误的，会导致会话关闭。

如需详细了解传入的参数及其角色，请参阅上面的 Present2Args 文档。

请求

名称类型
args Present2Args

响应

名称类型
request_presentation_times_info fuchsia.scenic.scheduling/FuturePresentationTimes

RegisterBufferCollection

注册 token 引用的 BufferCollection 并对其设置限制。在创建由某个集合的 VMO 支持的内容（例如 Image2）之前，它不会阻塞正在分配的缓冲区。

buffer_id 的值无效。所有其他值只要当前未使用，则有效。

请求

名称类型
buffer_id uint32
token fuchsia.sysmem/BufferCollectionToken

RequestPresentationTimes

返回有关未来呈现时间及其各自的锁存点的信息。客户端可以根据返回的信息做出明智的调度决策：如果客户端希望在给定的 presentation_time 下显示其帧，则应力求在关联的 latch_point 之前触发所有 acquire_fences。

“风景”将尝试返回时长等于 requested_prediction_span 的时长（不超过上限）的预测结果。

值为 0 时保证至少有一条展示信息。

请求

名称类型
requested_prediction_span zx/Duration

响应

名称类型
request_presentation_times_info fuchsia.scenic.scheduling/FuturePresentationTimes

SetDebugName

为会话设置可选的调试名称。调试名称将在日志记录和跟踪事件等功能中输出。

请求

名称类型
debug_name string

SessionListener

在 fuchsia.ui.scenic/session.fidl 中定义

监听会话中发生的事件。

OnScenicError

在出现错误且会话将销毁时调用。

请求

名称类型
error string

OnScenicEvent

调用以向监听器批量传送一个或多个事件。使用 SetEventMaskCmd 为资源启用事件传送功能。

请求

名称类型
events vector<Event>

结构

ScreenshotData 资源

在 fuchsia.ui.scenic/scenic.fidl 中定义

Views.TakeScreenshot() 返回了采用 sRGB 颜色空间的 BGRA 格式的原始图片，并在此结构体中提供了一个非线性转换函数。

野战类型说明默认
info fuchsia.images/ImageInfo 无默认取景方式
data fuchsia.mem/Buffer 无默认取景方式

表

Present2Args 资源

在 fuchsia.ui.scenic/session.fidl 中定义

传入 Present2() 的参数。请注意，每个参数都是强制性的。

序数野战类型说明
requested_presentation_time zx/Time

requested_presentation_time 指定客户端希望加入队列的操作生效的时间（屏幕上点亮像素），以纳秒为单位，在 CLOCK_MONOTONIC 时基中表示。

使用当前或过去时间的 requested_presentation_time（例如 0）可安排已加入队列的操作，以便在要准备的下一帧期间尽快生效。请求的呈现时间必须单调递增。

如果将来使用 requested_presentation_time，则让加入队列的操作在规定时间前后应尽可能地显现，而不是在更早的时间生效。

每个渲染帧都有一个目标呈现时间。这时，Scene 团队希望将相应的帧呈现给用户。在渲染某个帧之前，场景管理器会应用与 requested_presentation_time 在帧的目标呈现时间当天或之前的所有 Present2 调用相关的所有已加入队列的操作。
acquire_fences vector<event>

观景器会等到会话的所有 acquire_fences 准备就绪，然后再执行显示的命令。
release_fences vector<event>

release_fences 是当以下 Present2 调用的 acquire_fences 已收到信号且更新后的会话状态已完全提交时，Scene 会向其发送信号的事件列表：未来的帧将使用此状态进行渲染，并且使用先前会话状态生成的所有帧也都已完全渲染并呈现给显示屏。
requested_prediction_span zx/Duration

requested_prediction_span 是未来风景区将提供预测的时间量。span 为 0 保证至少在未来提供一次时间。

SessionEndpoint 资源

在 fuchsia.ui.scenic/scenic.fidl 中定义

用于创建景观会话的协议端点。

序数野战类型说明
session server_end<Session>

将命令加入队列并呈现内容。 必选。
session_listener SessionListener

接收与会话相关的事件。 可选。
view_focuser server_end<fuchsia.ui.views/Focuser>

在会话视图的子树内更改视图焦点。 可选。
view_ref_focused server_end<fuchsia.ui.views/ViewRefFocused>

了解此会话视图何时获得或失去视图焦点。 可选。
touch_source server_end<fuchsia.ui.pointer/TouchSource>

请求触摸事件并协商手势所有权。 可选。
mouse_source server_end<fuchsia.ui.pointer/MouseSource>

请求鼠标事件。 可选。

联合

命令严格 资源

在 fuchsia.ui.scenic/commands.fidl 中定义

序数变体类型说明
gfx fuchsia.ui.gfx/Command
views fuchsia.ui.views/Command
已弃用：10
input fuchsia.ui.input/Command
已弃用：10

活动严格 资源

在 fuchsia.ui.scenic/events.fidl 中定义

序数变体类型说明
gfx fuchsia.ui.gfx/Event
input fuchsia.ui.input/InputEvent
已弃用：10
unhandled Command

常量

名称值类型说明
displayNotOwnedSignal 16777216 uint32
displayOwnedSignal 33554432 uint32