Fuchsia.ui.scenic

已移除：17 已淘汰：13 已新增：7

通訊協定

風景

定義於 fuchsia.ui.scenic/scenic.fidl

CreateSession

建立新的工作階段，這是與 View 互動的主要方式。

要求

名稱類型
session server_end<Session>
listener SessionListener?

CreateSession2

建立新的工作階段，這是與 View 互動的主要方式。

在這個變體中，呼叫端可能會註冊焦點管理要求。view_focuser 的用戶端會與要求的 session 結合，而這個耦合為安全性邊界：view_focuser 用來當做 view_focuser 授權的基礎的 ViewRef 必須來自 session。

要求

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

CreateSessionT

建立新的工作階段，這是與 View 互動的主要方式。

在這個變因中，呼叫端可能會提交合理的通訊協定組合。工作階段通訊協定是唯一必要的通訊協定。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 通訊協定與 View 互動。

要求

<EMPTY>

回應

名稱類型
flatland_enabled bool

工作階段

定義於 fuchsia.ui.scenic/session.fidl

用戶端使用工作階段，將建立或修改資源的指令排入佇列，以便與 View 執行個體互動。

DeregisterBufferCollection

取消註冊先前透過 buffer_id 註冊的 BufferCollection，並將該 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 驅動程式庫等下游元件) 等待這些資源。

舉例來說，Fushisia 的 Vulkan 驅動程式庫允許從 VkSemaphore 取得 zx::event。這可讓 View 用戶端提交 Vulkan 指令緩衝區，產生圖像/訊息等，並指示 Vulkan 在完成後發出 VkSemaphore 信號。將與此流程對應的 zx::event 插入 acquire_fences 後，用戶端即可允許 View 將工作提交到 Vulkan 驅動程式，不必等待事件在 CPU 上發出訊號。

release_fences 是一系列事件，可在更新的工作階段狀態完整提交時，View 發出信號：日後的影格會以此狀態轉譯，使用先前工作階段狀態產生的所有影格都已完整轉譯並顯示在螢幕上。

acquire_fences 和 release_fences 兩者的用意是讓用戶端實作雙緩衝等策略。例如，用戶端可能會在風景子系統中執行以下操作：

  1. 建立兩個資源 ID 為 #1 和 #2 的圖片。
  2. 建立兩個資源 ID 為 3 和 #4 的材質，分別使用圖片 #1 和 #2 做為紋理。
  3. 建立節點的樹狀結構，並附加至場景。
  4. 設定上方的其中一個節點 (如 #5)，即可使用 Material #3。
  5. 提交 Vulkan 指令緩衝區，算繪為圖片 #1，並傳送 VkSemaphore 信號。
  6. 呼叫 Present() 和一個新建立的發布圍欄 (從上述的 VkSemaphore 取得)。

完成上述步驟後，View 會在必要時，使用已修訂的工作階段狀態算繪影格。如果用戶端想要顯示與圖片 #1 不同的內容，則會執行與步驟 4) 到 6 類似的操作)：7) 將 Node #5 設定為使用 Material #4。8) 提交可算繪為 Image #1 的 Vulkan 指令緩衝區，並發出 VkSemaphore 信號。9) 使用一個擷取式圍欄 (從上述的 VkSemaphore 取得) 呼叫 Present()，以及一個新建立的發布圍欄。

最後，若要持續繪製新內容，用戶端可以重複步驟 4) 到 9，但有一項重要的差異：步驟 5) 必須等待步驟 9 發出的事件。否則，如果 Image 仍在算繪影格，則可能會顯示為圖片 #1。同樣地，步驟 8) 必須等待步驟 6 發出的事件信號)。

上述情境使用一個擷取圍欄和一個發布圍欄，但很容易想像需要更多的案例。舉例來說，除了使用 Vulkan 將圖片算繪到圖片 #1 和 #2 之外，用戶端也可以將其他資源上傳至不同 VkQueue 上的 Vulkan，這意味著可以傳送獨立的 Semaphore 信號，因此需要額外的開發屏障。

注意：只有在同步處理記憶體 (和其他外部資源) 的存取權時，才需要 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 事件。這個事件包含屬於該影格內容的所有 Present2s 相關資訊。

客戶在每個工作階段只能使用 Present/Present2 2。切換兩者皆出現錯誤，會導致工作階段關閉。

如要進一步瞭解傳遞哪些引數及其角色，請參閱上方的 Present2Args 說明文件。

要求

名稱類型
args Present2Args

回應

名稱類型
request_presentation_times_info fuchsia.scenic.scheduling/FuturePresentationTimes

RegisterBufferCollection

註冊 token 參照的 BufferCollection，並為其設定限制。 在系統建立其中一個集合 VMO 支援的內容 (例如 Image2) 之前，不會封鎖分配的緩衝區。

將 buffer_id 的值設為 0 無效。只要目前未使用，所有其他值都有效。

要求

名稱類型
buffer_id uint32
token fuchsia.sysmem/BufferCollectionToken

RequestPresentationTimes

傳回未來簡報時間及各自的閂鎖點相關資訊。用戶端可利用傳回的資訊做出明智的排程決定：如果用戶端想在特定 presentation_time 顯示影格，就應致力在關聯的 latch_point 之前觸發所有 acquire_fences。

View 會嘗試傳回持續時間等於 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

View.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 會安排將排入佇列的作業盡可能在表定時間之前或之後生效，但不會更早發生。

每個轉譯影格都有目標簡報時間。這時風景照 是要向使用者顯示畫面。在轉譯影格之前，場景管理工具會套用所有與 Present2 相關聯的所有已排入佇列作業，前提是 requested_presentation_time 位於影格目標簡報時間或之前。
acquire_fences vector<event>

「View」會等到工作階段的所有 acquire_fences 準備就緒後，才能執行顯示的指令。
release_fences vector<event>

release_fences 是當下列 Present2 呼叫的 acquire_fences 發出信號信號，並且更新工作階段狀態已完全修訂時，View 發出的事件清單：日後的影格會使用此狀態轉譯，而使用先前工作階段狀態產生的所有影格都已完整轉譯並顯示在螢幕上。
requested_prediction_span zx/Duration

requested_prediction_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

序數Variant類型說明
gfx fuchsia.ui.gfx/Command
views fuchsia.ui.views/Command
已淘汰：10
input fuchsia.ui.input/Command
已淘汰：10

事件嚴格 資源

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

序數Variant類型說明
gfx fuchsia.ui.gfx/Event
input fuchsia.ui.input/InputEvent
已淘汰：10
unhandled Command

業者

名稱值類型說明
displayNotOwnedSignal 16777216 uint32
displayOwnedSignal 33554432 uint32