fuchsia.images

新增:7

通訊協定

ImagePipe2

定義於 fuchsia.images/image_pipe2.fidl

ImagePipe 是一種機制,可在產生者和消費者之間串流共用圖片,這些圖片可能在不同的程序中執行。

從概念上來說,圖片管道會維護由產生器提供的圖片資源表格,其中可能儲存圖形內容,以及包含產生器要求消費者呈現的一連串圖片的呈現佇列。

顯示佇列一開始是空的。

顯示佇列中的每個項目都包含一張圖片,以及一對選用的同步處理柵欄:

  • 取得柵欄:在圖像可供使用時,由生產者發出信號
  • 釋出柵欄:當映像檔可由生產端釋出或修改時,由消耗端發出信號

製作者會按照下列步驟呈現內容:

  • 分配並新增一些 BufferCollection 到圖片管道,讓消費者設定限制。
  • 分配並新增一些圖片 (通常為 2 或 3 張) 至圖片管道,以使用 AddImage() 建立集區。
  • 從集區中取得下一個可用的圖片。
  • 要求消費者將圖片排入佇列以供顯示,並使用 PresentImage() 提供柵欄。
  • 開始算繪圖片。
  • 在算繪完成時,向圖片的取得柵欄發出信號。
  • 循環顯示更多圖片,監聽釋放柵欄上的信號,將圖片回收至集區。

消費者會針對顯示佇列中的每張圖片,執行下列步驟:

  • 等待圖片取得柵欄上的信號。
  • 如果無法滿足柵欄等待條件,或偵測到其他錯誤,請關閉圖片管道。否則,請開始呈現圖片內容。
  • 從顯示佇列中淘汰先前顯示的圖片 (如有),並在不再需要時發出釋放柵欄信號。
  • 繼續顯示同一張圖片,直到下一張圖片準備就緒。Loop。

如果產生器想關閉圖片管道,應執行下列操作:

  • 關閉連線。
  • 等待所有釋出柵欄,以便處理已透過 PresentImage() 提交的緩衝區。
  • 繼續清除資源。

當消費者偵測到圖片管道已關閉時,應執行以下操作:

  • 停止使用/展示來自管道的任何圖片。
  • 取消對應與管道中圖片相關聯的所有記憶體物件。
  • 關閉所有 BufferCollection 資源。
  • 為顯示和排入佇列的緩衝區,發出所有釋出柵欄的信號。
  • 關閉所有圍欄控制代碼。
  • 關閉連線。

當任一方偵測到柵欄已遭棄用 (在未收到信號的情況下從遠端關閉),應假設相關聯的圖片處於不確定狀態。這通常發生在另一方 (或其委派代表) 異常終止時。最安全的做法是關閉圖片管道、釋出與另一方共用的所有資源,然後重新建立連線以復原。

AddBufferCollection

已移除:NEXT 已淘汰:13

要求

名稱類型
buffer_collection_id uint32
buffer_collection_token client_end:fuchsia.sysmem/BufferCollectionToken

AddBufferCollection2

將 BufferCollection 資源新增至圖片管道。

製作者應為透過 AddImage() 新增的圖片設定這項資源的限制。消費者可以在 buffer_collection_token 之前或之後設定限制。請注意,在生產端和消費端,必須使用所有 BufferCollectionToken 執行個體設定限制,系統才會分配緩衝區。詳情請參閱 collection.fidl。

下列錯誤會導致連線關閉:

  • buffer_collection_id已註冊
已淘汰:25 已新增:25

要求

名稱類型
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 中分配資源。
已淘汰:13

要求

名稱類型
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 未參照目前註冊的圖片資源
已淘汰:13

要求

名稱類型
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
已淘汰:13

要求

名稱類型
buffer_collection_id uint32

RemoveImage

從管道中移除圖片資源。

image_id 會與圖片資源分離,並可重複使用,以新增圖片資源。

從圖像管道中移除圖像,不會影響呈現佇列或目前呈現的圖像。

由於圖片可能仍用於顯示佇列,因此生產端必須等待與圖片相關聯的所有釋出柵欄發出信號,才能釋出或修改基礎記憶體物件。

下列錯誤會導致連線關閉:

  • image_id 未參照目前註冊的圖片資源
已淘汰:13

要求

名稱類型
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() 等方法傳回的資訊。

已淘汰:13

欄位類型說明預設
presentation_time uint64

預計排入佇列作業實際生效的時間,以 CLOCK_MONOTONIC 時基的奈秒表示。

這個值會隨著每個新影格單調遞增,通常以 presentation_interval 的增量遞增。

無預設值
presentation_interval uint64

預期在連續顯示的影格之間經過的時間,以奈秒為單位。算繪至螢幕時,間隔通常會根據螢幕刷新率計算。

這個值不為零。這個值可能會不時變動,例如變更顯示模式時。

無預設值

ENUMS

AlphaFormat strict

類型:uint32

定義於 fuchsia.images/image_info.fidl

指定 Alpha 資訊的解讀方式。

名稱值說明
0

圖片會視為不透明。系統會忽略 Alpha 版。混合函式為:src.RGB

1

色彩通道已預乘 Alpha。混合函式為:src.RGB + (dest.RGB * (1 - src.A))

2

顏色通道尚未預先乘以 Alpha。混合函式為:(src.RGB * src.A) + (dest.RGB * (1 - src.A))

ColorSpace strict

類型:uint32

定義於 fuchsia.images/image_info.fidl

指定像素顏色資訊的解讀方式。

名稱值說明
0

MemoryType strict

類型:uint32

定義於 fuchsia.images/memory_type.fidl

指定 VMO 的記憶體類型。

已淘汰:13

名稱值說明
0

VMO 是標準主機 CPU 記憶體。

1

呼叫 VkAllocateMemory 時,只要將 VkImportMemoryFuchsiaHandleInfoKHR 包裝在 VkMemoryAllocateInfo 中,即可將 VMO 匯入為 VkDeviceMemory。

PixelFormat strict

類型:uint32

定義於 fuchsia.images/image_info.fidl

指定像素在圖片緩衝區中的表示方式。

名稱值說明
0

BGRA_8

32 位元四元件無正負號整數格式。位元組順序:B、G、R、A (小端序 ARGB 封裝 32 位元字組)。等同於 Skia kBGRA_8888_SkColorType 顏色類型。相當於小端序架構上的 Zircon ARGB_8888 像素格式。

1

YUY2

4:2:2 (水平方向 2 倍降採樣 UV;垂直方向全解析度 UV)

包含 2 個像素資訊的 32 位元元件: 位元組順序:Y1、U、Y2、V 解壓縮為 2 個 RGB 像素,其中 RGB1 = func(Y1, U, V) 且 RGB2 = func(Y2, U, V) 相當於 YUV422

2

NV12

4:2:0 (兩個方向的 UV 降採樣 2 倍)

偏移 0: 每個像素 8 位元的 Y 平面,位元組為 YYY。 偏移高度 * 步幅: 8 位元 UV 資料交錯位元組,格式為 UVUVUV。

Y 平面的線條步幅 >= 寬度。

在這種情況下,寬度和高度都必須是偶數。

UV 資料會分成「行」,每「行」的位元組寬度與 Y 資料行相同,且「行」步幅與 Y 資料的行步幅相同。UV 資料的高度為 2「行」。

轉換為 RGB 時,UV 資料在兩個方向上都會放大 2 倍。這則註解刻意不提及 UV 放大階段/篩選/信號處理的運作方式,因為這是一個複雜的主題,可能會因實作方式而異,通常會權衡放大的速度和品質。請參閱相關轉換程式碼中的註解,瞭解任何指定轉換路徑採用的方法。目前不會傳達 UV 資料的精確相對相位。

3

YV12

與 I420 類似,但 V 和 U 互換。

4:2:0 (兩個方向的 UV 降採樣 2 倍)

偏移 0: 每個像素 8 位元的 Y 平面,位元組為 YYY。 Offset height * stride: 8 bit V data with uv_stride = stride / 2 Offset height * stride + uv_stride * height / 2: 8 bit U data with uv_stride = stride / 2

Y 平面的線條步幅 >= 寬度。

寬度和高度都必須是偶數。

4

R8G8B8A8

32 位元四元件無正負號整數格式。位元組順序:R、G、B、A (小端序 ABGR 封裝 32 位元字組)。等同於 Skia kRGBA_8888_SkColorType 顏色類型。相當於小端序架構上的 Zircon ABGR_8888 像素格式。

這個格式只能與 VK_DEVICE_MEMORY 搭配使用。

平鋪嚴格

類型:uint32

定義於 fuchsia.images/image_info.fidl

指定像素在記憶體中的排列方式。

名稱值說明
0

像素會以線性方式封裝。等同於 VK_IMAGE_TILING_LINEAR。

1

像素會以 GPU 依賴的最佳格式封裝。等同於 VK_IMAGE_TILING_OPTIMAL。

轉換 strict

類型:uint32

定義於 fuchsia.images/image_info.fidl

名稱值說明
0

像素正常顯示。

1

像素會左右鏡像。

2

像素會垂直翻轉。

3

像素會垂直翻轉,並左右鏡像。

常數

名稱值類型說明
MAX_ACQUIRE_RELEASE_FENCE_COUNT 16 int32
已淘汰:13