fuchsia.images

新增：7

PROTOCOLS

ImagePipe2

定義於 fuchsia.images/image_pipe2.fidl

ImagePipe 是一種機制，可在可能在不同程序中執行的製作者和使用者之間串流共用圖片。

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

呈現佇列一開始是空的。

呈現佇列中的每個項目都包含一張圖片，以及一對選用的同步化圍欄：

  • 取得圍欄：在圖片可供使用時，製作者發出信號
  • 釋放柵欄：當圖片可供生產端釋放或修改時，由消費者發出信號

製作者會執行以下步驟序列，呈現內容：

  • 將一些 BufferCollection 分配並新增至圖片管道，以便使用者設定限制。
  • 將一些圖片 (通常為 2 或 3 張) 分配並新增至圖片管道，以便使用 AddImage() 建立集區。
  • 從集區中取得下一個可用的映像檔。
  • 請使用者將圖片排入佇列以供呈現，並使用 PresentImage() 提供柵欄。
  • 開始轉譯圖片。
  • 在算繪完成時，傳送圖片的取得柵欄信號。
  • 循環呈現更多圖片，並監聽釋放圍欄的信號，將圖片回收至集區。

取用者會針對新增至簡報佇列中的每張圖片，執行下列步驟：

  • 等待圖片的取得柵欄信號。
  • 如果無法滿足柵欄等待時間，或偵測到其他錯誤，請關閉圖片管道。如果沒有，則開始分享圖片內容。
  • 從呈現佇列中退出先前呈現的圖片 (如有)，並在不再需要時發出釋放柵欄信號。
  • 請繼續顯示相同圖片，直到下一個圖片準備就緒為止。迴圈。

如果製作者想要關閉圖片管道，應採取以下做法：

  • 關閉該端的連線。
  • 等待所有透過 PresentImage() 提交的緩衝區的發布圍欄。
  • 繼續清除資源。

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

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

當任何一方偵測到邊界已遭到放棄 (從遠端關閉而未收到信號) 時，應假設相關聯的圖片處於未定狀態。這種情況通常會發生在另一方 (或其中一個委派函) 當機時。最安全的做法是關閉映像檔管道、釋出與其他方共用的所有資源，然後重新連線以復原。

AddBufferCollection

已淘汰：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

只要使用 VkMemoryAllocateInfo 包裝的 VkImportMemoryFuchsiaHandleInfoKHR 呼叫 VkAllocateMemory，即可將 VMO 匯入為 VkDeviceMemory。

PixelFormat strict

類型：uint32

定義於 fuchsia.images/image_info.fidl

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

名稱值說明
0

BGRA_8

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

YUY2

4:2:2 (水平方向採樣 2 次的 UV；垂直方向採樣全解析度 UV)

32 位元元件，其中包含 2 個像素的資訊： 位元順序：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 皆經過 2x 下採樣)

偏移 0：每個像素 Y 平面 8 位元，位元組 YYY。偏移高度 * 步長： 8 位元 V 資料，格式為 uv_stride = 步長 / 2 偏移高度 * 步長 + uv_stride * 高度 / 2: 8 位元 U 資料，含 uv_stride = 步長 / 2

Y 平面有線條間距 >= 寬度。

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

R8G8B8A8

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

此格式只能與 VK_DEVICE_MEMORY 搭配使用。

平鋪 strict

類型：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