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 信號後，製作人可以重複使用資源。

這項設計可讓製作人將圖像處理作業分配到多個執行緒 / 程序，而不會造成不必要的協調延遲。每個執行緒 / 程序會在 acquire_fences 中發出自己的柵欄信號，表示已完成 image_id 的部分轉譯作業，並在 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

VMO 可以匯入為 VkDeviceMemory，方法是呼叫 VkAllocateMemory，並將 VkImportMemoryFuchsiaHandleInfoKHR 包裝在 VkMemoryAllocateInfo 中。

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 (水平方向的 UV 降採樣 2 倍；垂直方向的 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 (在兩個方向都以 2 倍的比例降低 UV 取樣率)

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

Y 平面的行步長 >= 寬度。

在此情況下，寬度和高度都必須是偶數。

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

轉換為 RGB 時，UV 資料會在整體上以雙向 2 倍的比例放大。本註解刻意不說明 UV 升頻階段/篩選/訊號處理的確切運作方式，因為這是複雜的主題，且可能因實作方式而異，通常會以升頻速度和品質做為取捨。如要瞭解特定轉換路徑採用的方法，請參閱相關轉換程式碼中的註解。目前不會傳達紫外線資料的確切相對相位。
3

YV12

與 I420 類似，但 V 和 U 會互換。

4:2:0 (在兩個方向都以 2 倍的比例降低 UV 取樣率)

偏移 0： 每個像素 8 位元的 Y 平面，位元組為 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