PROTOCOLS
ImagePipe2
在 fuchsia.images/image_pipe2.fidl 中定义
ImagePipe 是一种机制，用于在可能在不同进程中运行的生产者和消费者之间流式传输共享图片。
从概念上讲，图像管道会维护一个由生产者提供的图像资源表，其中可以存储图形内容，还会维护一个演示队列，其中包含生产者要求消费者演示的一系列图像。
展示队列最初为空。
演示队列中的每个条目都包含一个图像以及一对可选的同步栅栏：
- 获取栅栏：由生产者在图像准备好供消费时发出信号
- 释放栅栏：当图像可由生产方释放或修改时，由消费方发出信号
制作方会按以下顺序执行步骤来呈现内容：
- 为图像管道分配并添加了一些 BufferCollection，以允许消费者设置限制。
- 分配一些数量的图片（通常为 2 或 3 张）并将其添加到图片管道，以使用
AddImage()建立一个池。 - 从池中获取下一个可用映像。
- 要求使用方使用
PresentImage()将图片排入队列以供展示并提供栅栏。 - 开始渲染图片。
- 在渲染完成后，发出图像的获取栅栏信号。
- 循环显示更多图片，监听释放栅栏上的信号，以便将图片回收回池中。
对于在演示队列中排队的每个映像，消费者会按以下顺序执行一系列步骤：
- 等待图像的获取栅栏上的信号。
- 如果无法满足栅栏等待条件或检测到其他错误，请关闭图像管道。否则，开始呈现图片的内容。
- 从演示队列中撤消之前呈现的图片（如有），并在不再需要时发出其释放栅栏信号。
- 继续展示同一张图片，直到下一张图片准备就绪。循环播放。
如果生产者想要关闭图片管道，应执行以下操作：
- 关闭其连接。
- 等待通过
PresentImage()提交的缓冲区的所有发布栅栏。 - 继续清理资源。
当消费者检测到图像管道已关闭时，应执行以下操作：
- 停止使用/展示管道中的任何图片。
- 取消映射与管道中的映像关联的所有内存对象。
- 关闭所有 BufferCollection 资源。
- 为已呈现和已加入队列的缓冲区发出所有释放栅栏信号。
- 关闭所有围栏句柄。
- 关闭其连接。
当任一方检测到栅栏已被放弃（远程关闭但未发出信号）时，应假定关联的映像处于不确定状态。当另一方（或其某个委托方）崩溃时，通常会发生这种情况。最安全的做法是关闭图片管道，释放与对方共享的所有资源，然后重新建立连接以恢复。
AddBufferCollection
请求
| 名称 | 类型 |
|---|---|
buffer_collection_id |
uint32
|
buffer_collection_token |
client_end:fuchsia.sysmem/BufferCollectionToken
|
AddBufferCollection2
向图像管道添加 BufferCollection 资源。
预计提供方会针对通过 AddImage() 添加的图片为此资源设置限制。使用方可以在 buffer_collection_token 之前或之后设置其限制。请注意，在生产方和使用方使用所有 BufferCollectionToken 实例来设置限制之前，不会分配缓冲区。如需了解详情，请参阅 collection.fidl。
以下错误会导致连接关闭：
- “
buffer_collection_id”已注册
请求
| 名称 | 类型 |
|---|---|
buffer_collection_id |
uint32
|
buffer_collection_token |
client_end:fuchsia.sysmem2/BufferCollectionToken
|
AddImage
向图片管道添加图片资源。
buffer_collection_id 是指通过 AddBufferCollection() 注册的 BufferCollectionToken 实例。分配的底层内存对象用于寻址图像数据。buffer_collection_index 指的是在 BufferCollection 中分配的内存对象的索引。
image_format 指定图片属性。coded_width 和 coded_height 用于设置图片尺寸。
创建由同一内存对象支持的多个映像是有效的；这些映像甚至可以重叠。消费者必须检测到此情况并相应地进行处理。
以下错误会导致连接关闭：
- “
image_id”已注册 buffer_collection_id指的是未注册的 BufferCollection。buffer_collection_index指向的资源索引超出了已初始化的 BufferCollection 边界- 在已注册的 BufferCollection 中未分配任何资源。
请求
| 名称 | 类型 |
|---|---|
image_id |
uint32
|
buffer_collection_id |
uint32
|
buffer_collection_index |
uint32
|
image_format |
fuchsia.sysmem/ImageFormat_2
|
PresentImage
将指定图片加入队列，以供使用方展示。
acquire_fences 是一组栅栏，生产者必须全部发出信号，然后消费者才能呈现图像。release_fences 是一组栅栏，用于告知生产者可以安全地释放或修改 image_id 图像，并且可以安全地在 acquire_fences 中重复使用栅栏。在 image_id 不再呈现后，消费者必须发出 release_fences 中所有栅栏的信号。在发出任何release_fences信号后，生产者可以重复使用资源。
这种设计允许生产者在多个线程 / 进程中分配图像处理任务，而不会产生不必要的协调延迟。
每个线程 / 进程在完成 image_id 的渲染后，都会在 acquire_fences 中发出自己的栅栏信号，并在 release_fences 中等待自己的栅栏，以便在 image_id 中渲染新内容。
presentation_time 指定了客户端希望已入队的作业开始产生可见效果（点亮屏幕上的像素）的时间，以纳秒为单位，采用 CLOCK_MONOTONIC 时基。所需的呈现时间必须单调不减。
presentation_info 会返回有关提交的帧和未来帧的时序信息（请参阅 presentation_info.fidl）。
制作人可以决定不为图片发出 acquire_fences 信号。在这种情况下，如果稍后有图片入队，并且达到了稍后图片的 presentation_time，则当稍后图片的 acquire_fences 发出信号时，消费者会呈现稍后的图片。使用方还会发出更早图像的 release_fences 信号，并将其从呈现队列中移除。此序列可作为取消机制。
以下错误会导致连接关闭：
image_id未引用当前已注册的图片资源
请求
| 名称 | 类型 |
|---|---|
image_id |
uint32
|
presentation_time |
uint64
|
acquire_fences |
vector<handle<event>>:16
|
release_fences |
vector<handle<event>>:16
|
响应
| 名称 | 类型 |
|---|---|
presentation_info |
PresentationInfo
|
RemoveBufferCollection
从管道中移除 BufferCollection 资源。
buffer_collection_id 资源以及与该 BufferCollection 关联的所有映像都会分离。与对 buffer_collection_id 的所有图片调用 RemoveImage() 得到的结果相同。
由于图像可能仍在演示队列中使用，因此生产者必须等待与图像关联的所有发布栅栏发出信号，然后才能释放或修改底层内存对象。
以下错误会导致连接关闭：
buffer_collection_id不引用当前已注册的 BufferCollection
请求
| 名称 | 类型 |
|---|---|
buffer_collection_id |
uint32
|
RemoveImage
从管道中移除图片资源。
image_id 已与图片资源分离，可以自由地重复使用以添加新的图片资源。
从图像管道中移除图像不会影响呈现队列或当前呈现的图像。
在释放或修改底层内存对象之前，生产者必须等待与映像关联的所有发布栅栏发出信号，因为映像可能仍在演示队列中使用。
以下错误会导致连接关闭：
image_id未引用当前已注册的图片资源
请求
| 名称 | 类型 |
|---|---|
image_id |
uint32
|
STRUCTS
ImageInfo
在 fuchsia.images/image_info.fidl 中定义
有关图形图像（纹理）的信息，包括其格式和大小。
| 字段 | 类型 | 说明 | 默认 |
|---|---|---|---|
transform |
Transform
|
指定是否应在显示之前镜像图片。 |
Transform.NORMAL |
width |
uint32
|
图片的宽度和高度（以像素为单位）。 |
无默认值 |
height |
uint32
|
无默认值 | |
stride |
uint32
|
图像缓冲区中每行的字节数。 |
无默认值 |
pixel_format |
PixelFormat
|
图片的像素格式。 |
PixelFormat.BGRA_8 |
color_space |
ColorSpace
|
像素颜色空间。 |
ColorSpace.SRGB |
tiling |
Tiling
|
内存中的像素排列。 |
Tiling.LINEAR |
alpha_format |
AlphaFormat
|
指定 Alpha 渠道的解释（如果存在）。 |
AlphaFormat.OPAQUE |
PresentationInfo
在 fuchsia.images/presentation_info.fidl 中定义
当消费者开始准备包含呈现内容的第一个帧时，由 ImagePipe.PresentImage() 和 Session.Present() 等方法返回的信息。
| 字段 | 类型 | 说明 | 默认 |
|---|---|---|---|
presentation_time |
uint64
|
预期排队操作生效的实际时间，以 此值会随着每个新帧单调递增，通常以 |
无默认值 |
presentation_interval |
uint64
|
预期在连续呈现的帧之间经过的名义时间量（以纳秒为单位）。在渲染到显示屏时，间隔通常会从显示屏刷新率派生出来。 此值不为零。它可能会不时发生变化，例如在更改显示模式时。 |
无默认值 |
枚举
AlphaFormat strict
类型：uint32
在 fuchsia.images/image_info.fidl 中定义
指定应如何解读 Alpha 信息。
| 名称 | 值 | 说明 |
|---|---|---|
不透明 |
0 |
图片被视为不透明。系统会忽略 Alpha 渠道。 混合函数为：src.RGB |
预乘 |
1 |
颜色通道已预先乘以 Alpha 值。 混合函数为：src.RGB + (dest.RGB * (1 - src.A)) |
NON_PREMULTIPLIED |
2 |
颜色通道尚未与 Alpha 相乘。 混合函数为：(src.RGB * src.A) + (dest.RGB * (1 - src.A)) |
ColorSpace strict
类型：uint32
在 fuchsia.images/image_info.fidl 中定义
指定应如何解读像素颜色信息。
| 名称 | 值 | 说明 |
|---|---|---|
SRGB |
0 |
MemoryType strict
类型：uint32
在 fuchsia.images/memory_type.fidl 中定义
指定 VMO 的内存类型。
| 名称 | 值 | 说明 |
|---|---|---|
HOST_MEMORY |
0 |
VMO 是常规主机 CPU 内存。 |
VK_DEVICE_MEMORY |
1 |
通过调用 VkAllocateMemory 并将 VkImportMemoryFuchsiaHandleInfoKHR 封装在 VkMemoryAllocateInfo 中，可以将 VMO 导入为 VkDeviceMemory。 |
PixelFormat 严格
类型：uint32
在 fuchsia.images/image_info.fidl 中定义
指定像素在图片缓冲区中的表示方式。
| 名称 | 值 | 说明 |
|---|---|---|
BGRA_8 |
0 |
BGRA_8 一种 32 位四分量无符号整数格式。
字节顺序：B、G、R、A（小端 ARGB 封装的 32 位字）。
相当于 Skia |
YUY2 |
1 |
YUY2 4:2:2（UV 水平方向上降采样 2 倍；UV 垂直方向上为全分辨率） 一个 32 位组件，包含 2 个像素的信息： 字节顺序：Y1、U、Y2、V 解封装为 2 个 RGB 像素，其中 RGB1 = func(Y1, U, V)，RGB2 = func(Y2, U, V) 相当于 YUV422 |
NV12 |
2 |
NV12 4:2:0（UV 在两个方向上均下采样 2 倍） 偏移量 0：每像素 8 位 Y 平面，字节为 YYY。 偏移高度 * 步幅：8 位 UV 数据交错字节，格式为 UVUVUV。 Y 平面的行步长 >= 宽度。 在此背景下，宽度和高度都必须为偶数。 UV 数据被分成“行”，每“行”的字节宽度与 Y 数据行的字节宽度相同，并且“行”步幅与 Y 数据的行步幅相同。 UV 数据有 height / 2 个“行”。 在转换为 RGB 时，UV 数据在两个方向上总体上会按 2 倍比例放大。此注释有意未详细说明 UV 放大阶段/过滤/信号处理的具体工作方式，因为这是一个复杂的主题，可能会因实现而异，通常需要在放大速度和质量之间做出权衡。如需了解任何给定转化路径所采用的方法，请参阅相关转化代码中的注释。目前无法传达紫外线数据的精确相对相位。 |
YV12 |
3 |
YV12 与 I420 类似，但 V 和 U 进行了交换。 4:2:0（UV 在两个方向上均下采样 2 倍） 偏移量 0：每像素 8 位 Y 平面，字节为 YYY。 偏移高度 * 步幅：uv_stride = 步幅 / 2 的 8 位 V 数据 偏移高度 * 步幅 + uv_stride * 高度 / 2：uv_stride = 步幅 / 2 的 8 位 U 数据 Y 平面的行步长 >= 宽度。 宽度和高度都必须为偶数。 |
R8G8B8A8 |
4 |
R8G8B8A8 一种 32 位四分量无符号整数格式。
字节顺序：R、G、B、A（小端 ABGR 封装的 32 位字）。
相当于 Skia 此格式只能与 VK_DEVICE_MEMORY 搭配使用。 |
平铺 严格
类型：uint32
在 fuchsia.images/image_info.fidl 中定义
指定像素在内存中的排列方式。
| 名称 | 值 | 说明 |
|---|---|---|
线性 |
0 |
像素以线性方式打包。
等同于 |
GPU_OPTIMAL |
1 |
像素以依赖于 GPU 的最佳格式打包。
等同于 |
转换 strict
类型：uint32
在 fuchsia.images/image_info.fidl 中定义
| 名称 | 值 | 说明 |
|---|---|---|
正常 |
0 |
像素显示正常。 |
FLIP_HORIZONTAL |
1 |
像素左右镜像。 |
FLIP_VERTICAL |
2 |
像素已垂直翻转。 |
FLIP_VERTICAL_AND_HORIZONTAL |
3 |
像素会垂直翻转并左右镜像。 |
常量
| 名称 | 值 | 类型 | 说明 |
|---|---|---|---|
| MAX_ACQUIRE_RELEASE_FENCE_COUNT |
16
|
int32 |
已弃用：13
|