通訊協定
分配器
定義於 fuchsia.ui.composition/allocator.fidl
RegisterBufferCollection
BufferCollection 是由 Sysmem 建立的一組 VMO,由多個參與者共用,其中一個是 Flatland 轉譯器。部分內容 (例如圖片) 會使用 BufferCollection 做為備份記憶體。
如要瞭解各個引數,請參閱 RegisterBufferCollectionArgs。
要求
| 名稱 | 類型 |
|---|---|
args |
RegisterBufferCollectionArgs
|
回應
| 名稱 | 類型 |
|---|---|
payload |
Allocator_RegisterBufferCollection_Result
|
ChildViewWatcher
定義於 fuchsia.ui.composition/flatland.fidl
這項通訊協定會提供特定孩童檢視模式的相關資訊,該模式附加至父項用戶端擁有的可視區域;與這項通訊協定的連線是在 CreateViewport 中建立。由於 Flatland 工作階段可能包含任意數量的 Viewport,且每個 Viewport 不一定會附加至轉換,因此用戶端可以與相同數量的 ChildViewWatcher 執行個體保持連線。
只要對應的子項 View 存在,每個 ChildViewWatcher 例項就會保持連線;如果子項的 ViewCreationToken 未用於建立 View 就遭到捨棄,連線也會關閉。
GetStatus
用於接收 View 狀態的 Hanging Get。這會向父項提供資訊,例如子項是否已透過這個 View 成功呈現內容。
只有在 ChildViewStatus 與先前傳回的 ChildViewStatus 不同時,系統才會觸發這個懸置 GET。即使 Viewport 的建立者在呼叫 CreateViewport() 後尚未呼叫 Present(),也可能立即發生這種情況。這樣一來,父項就能在修改自己的本機場景圖表以納入子項內容之前,得知子項已準備好顯示內容。
如果先前的呼叫仍在處理中,則呼叫 GetStatus 無效。這麼做會導致這個管道和發出 ChildViewWatcher 的 Flatland 管道關閉。
要求
<EMPTY>
回應
| 名稱 | 類型 |
|---|---|
status |
ChildViewStatus
|
GetViewRef
Hanging get 接收子檢視畫面的 ViewRef。只有在 View 參照與先前傳回的 View 參照不同時,才會觸發。注意:目前 View 參照在首次收到後不會變更,但如果 API 變更為允許重新連結檢視畫面,則會變更。
在檢視畫面納入檢視畫面樹狀結構之前,系統不會傳回 ViewRef。換句話說,當祖系轉換鏈結一路回到場景圖的根目錄 (即顯示畫面) 時,系統才會傳回 ViewRef。
如果先前的呼叫仍在處理中,則呼叫 GetViewRef 無效。這麼做會導致這個管道和發出 ChildViewWatcher 的 Flatland 管道關閉。
如果檢視畫面是使用 CreateView 建立,GetViewRef 呼叫會停止回應,但如果檢視畫面是使用 CreateView2 建立,則會傳回檢視畫面。這是因為 CreateView 不會為該 View 建立 ViewRef。
要求
<EMPTY>
回應
| 名稱 | 類型 |
|---|---|
view_ref |
fuchsia.ui.views/ViewRef
|
Flatland
定義於 fuchsia.ui.composition/flatland.fidl
每個 Flatland 工作階段都包含一個圖表,由一組物件和這些物件之間的關係組成。用戶端可以指定這些物件的子集 (具體來說,是從根轉換開始的有向無環圖),做為某種輸出內容 (通常是螢幕)。
Flatland 圖表既是階層式,也是分散式。不同 Flatland 工作階段的圖表可以連結在一起,讓多個程序參與特定輸出的內容製作。
這個通訊協定中的所有函式都是前饋式。在呼叫 Present 之前,系統不會完整執行這些物件代表的操作。
AddChild
將子項轉換作業新增至父項轉換作業。新的子項 Transform,以及附加至該子項或其子項的任何 Content,都會顯示在父項 Content 和先前新增的任何子項上方。
呼叫端必須確保 child_transform_id 有效且不重複。在多次呼叫中重複傳送 child_transform_id,會導致工作階段關閉。
要求
| 名稱 | 類型 |
|---|---|
parent_transform_id |
TransformId
|
child_transform_id |
TransformId
|
清除
這項功能會重設這個介面上的所有狀態。包括刪除所有現有的 View 和 Viewport,且不將相關聯的權杖傳回給呼叫端。
要求
<EMPTY>
CreateFilledRect
建立純色矩形。根據預設,filled-rect 沒有定義顏色或大小。必須先呼叫 |SetSolidFill| 指定顏色和大小,才能使用填滿矩形進行算繪。否則,矩形的預設大小會是 (0,0),因此在算繪時不會顯示。
rect_id 必須符合標準 ContentId 建立限制。
要求
| 名稱 | 類型 |
|---|---|
rect_id |
ContentId
|
CreateImage
圖片是由 BufferCollection 中特定 VMO 支援的點陣圖。
建立圖片時,必須使用已向 Allocator 註冊的已分配 BufferCollection。除非指定 BufferCollection 的所有用戶端都已設定限制,否則這項函式會失敗。
圖片必須參照有效的 VMO 索引,且 ImageProperties 必須符合支援 BufferCollection 指定的限制 (例如寬度和高度在有效範圍內等)
image_id 必須符合標準 ContentId 建立限制。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ContentId
|
import_token |
BufferCollectionImportToken
|
vmo_index |
uint32
|
properties |
ImageProperties
|
CreateImage2
建立映像檔資源。
image_id 必須符合 LayerId 記載的 ID 規則。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ImageId
|
import_token |
BufferCollectionImportToken
|
vmo_index |
uint32
|
properties |
ImageProperties
|
CreateLayer
圖層是一種 Content,可合成單一 Image 或純色。它會將視覺屬性 (例如大小、翻轉、不透明度和混合) 與原始像素資料分開。
一般的 Content 項目代表靜態視覺資源,而圖層則設計為圖片序列的動態容器。一般用法包括不常設定圖層的視覺屬性和圖片中繼資料,然後快速將使用中的 Image (例如在每個影格上) 替換為具有相符中繼資料的其他圖片。
這種分離方式可讓單一 Image 資源在多個圖層中重複使用,同時採用不同的視覺設定。
如何使用圖層:
- 使用 CreateLayer 建立
Layer。 - 透過 SetLayerProperties 設定
Layer的屬性,包括合成模式。 - 如果是圖片圖層,請透過 SetLayerImage 將
Image與Layer建立關聯。 - 透過 SetStackLayers 將
Layer新增至LayerStack。 - 透過 SetTransformContent 將
LayerStack設為節點的內容。
layer_id 必須符合 LayerId 記載的 ID 規則。
要求
| 名稱 | 類型 |
|---|---|
layer_id |
LayerId
|
CreateLayerStack
使用指定的 stack_id 建立新的圖層堆疊。
stack_id 必須符合 LayerId 記載的 ID 規則。
要求
| 名稱 | 類型 |
|---|---|
stack_id |
LayerStackId
|
CreateTransform
建立新的轉換節點。轉換是 Flatland 圖表的階層式部分。可以有子項,也可以參照內容。由轉換及其子系表示的子圖表可以轉譯至螢幕。
只要轉換是未釋出轉換或根轉換的子項,即使釋出,轉換仍會保持運作。
每個轉換只能附加一項內容。常見的內容類型包括點陣圖、非同步圖片串流,以及其他 Flatland 工作階段中託管的 Viewport to View。
轉換具有屬性。子項轉換會沿用父項的組合屬性。附加至轉換的內容也會受到該轉換屬性的影響。
轉譯轉換的子圖時,系統會從根轉換的內容開始,由後往前轉譯內容,並按照子項新增順序,遞迴處理所有子項轉換。詳情請參閱 AddChild。
轉換 ID 不得為零。所有其他值都有效,前提是這些值尚未在使用中 (詳情請參閱 ReleaseTransform)。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
CreateView
兩個 Flatland 工作階段可以建立上下層關係。父項端點位於 Viewport 中,子項端點則位於 View 中。建立 Viewport 的父項 Flatland 工作階段,可控制子項 View 整合至自身 View 的方式。
父子連線的生命週期始於管道物件的兩個端點:ViewportCreationToken 和 ViewCreationToken。頻外通訊協定會將 ViewportCreationToken 傳遞給呼叫 CreateViewport 的父項,並將 ViewCreationToken 傳遞給呼叫 CreateView 的子項。
只有在這個 Flatland 工作階段中連結至根轉換的節點,才會算繪至父項的檢視區。
第二次呼叫 CreateView 時,系統會中斷根轉換與現有父項 Viewport 的連線,並將其附加至新父項的 Viewport。換句話說,每個 View 只能有一個父項。
這個函式會排入佇列,也就是說,在呼叫 Present 之前,根轉換不會附加至父項 Viewport。不過,用戶端在呼叫這個函式後,即使尚未呼叫 Present 或 SetRootTransform,也會立即透過 ParentViewportWatcher 接收資訊 (例如 LayoutInfo)。這樣一來,用戶端就能先等待父項提供版面配置資訊,再呼叫 Present。
對 ParentViewportWatcher 進行任何非法作業,都會導致 ParentViewportWatcher 管道和這個 Flatland 管道遭到拆除。
生命週期附註。ParentViewportWatcher 管道的生命週期受對等 ViewportCreationToken 限制。ViewportCreationToken 終止時,這個 ParentViewportWatcher 管道就會刪除。
使用 CreateView 建立的 View 和 View 子圖不會顯示在 ViewTree 中,因此無法參與任何依賴 ViewTree 的互動,例如觸控、滑鼠或焦點。Flatland 通訊協定無法讓使用 CreateView 建立的 View 子圖中的 View 知道自己已從 ViewTree 中排除。
要求
| 名稱 | 類型 |
|---|---|
token |
fuchsia.ui.views/ViewCreationToken
|
parent_viewport_watcher |
server_end:ParentViewportWatcher
|
CreateView2
與 CreateView 相同,但允許關聯 View 身分 (ViewRef) 和 View 繫結通訊協定。
要求
| 名稱 | 類型 |
|---|---|
token |
fuchsia.ui.views/ViewCreationToken
|
view_identity |
fuchsia.ui.views/ViewIdentityOnCreation
|
protocols |
ViewBoundProtocols
|
parent_viewport_watcher |
server_end:ParentViewportWatcher
|
CreateViewport
Viewport 和 View 組合在一起,代表兩個 Flatland 工作階段之間的連線。Viewport 是在父項中建立,View 則是在子項中建立。父項可控制子項 View 整合至自身 View 的方式。
對 ChildViewWatcher 執行任何非法作業,都會導致 ChildViewWatcher 管道和這個 Flatland 管道遭到拆除。
ViewportProperties 必須設定 logical_size。這是決定子項版面配置的初始大小。logical_size 也會做為預設內容大小,但後續對 logical_size 的變更不會影響內容大小。
ViewportProperties 可能未設定插圖欄位。在這種情況下,系統會使用預設值 (0, 0, 0, 0)。
logical_size 的 X 和 Y 元件必須為正數。
生命週期附註。ChildViewWatcher 管道的生命週期受對等 ViewCreationToken 限制。當 ViewCreationToken 終止時,這個 ChildViewWatcher 管道就會刪除。
viewport_id 必須符合標準 ContentId 建立限制。
要求
| 名稱 | 類型 |
|---|---|
viewport_id |
ContentId
|
token |
fuchsia.ui.views/ViewportCreationToken
|
properties |
ViewportProperties
|
child_view_watcher |
server_end:ChildViewWatcher
|
CreateViewport2
建立 Viewport 資源。
viewport_id 必須符合 LayerId 記載的 ID 規則。
要求
| 名稱 | 類型 |
|---|---|
viewport_id |
ViewportId
|
token |
fuchsia.ui.views/ViewportCreationToken
|
properties |
ViewportProperties
|
child_view_watcher |
server_end:ChildViewWatcher
|
OnError
如果 Present 後發生錯誤,系統會觸發 OnError 事件並提供相關資訊。
FlatlandErrors 會關閉與用戶端的連線。
- 回應
error用戶端執行無效作業後可能收到的錯誤。
回應
| 名稱 | 類型 |
|---|---|
error |
FlatlandError
|
OnFramePresented
每當同時顯示一或多個禮物,且不再處於飛行狀態時,就會觸發這個事件。
這個事件表示在 Present 之前排入佇列的指令已在場景圖中生效,且全域可見。
除非用戶端明確要求提供先前影格呈現方式的意見回饋,否則「不」需要為這個事件實作處理常式,即可進行基本影格排程。所有後續影格資訊都會在 OnNextFrameBegin 事件中提供。
TODO(https://fxbug.dev/42141795):從這個事件中移除 num_presents_allowed。
回應
| 名稱 | 類型 |
|---|---|
frame_presented_info |
fuchsia.scenic.scheduling/FramePresentedInfo
|
OnNextFrameBegin
當用戶端預期資源爭用情形最少時,就會觸發這個事件。用戶端可以利用這個事件的時間點開始算繪工作,並根據傳回的資訊做出排程決策。
重要的是,只有在用戶端有一或多個顯示點數 (包括此事件傳回的點數) 時,系統才會觸發 OnNextFrameBegin。因此,每次觸發此事件時,都可以安全地顯示一次。
- 回應
values用戶端產生下一個影格所需的資訊表。詳情請參閱 OnNextFrameBeginValues。
回應
| 名稱 | 類型 |
|---|---|
values |
OnNextFrameBeginValues
|
展示
完成所有前饋作業。
如果執行作業時發生錯誤 (例如 CreateTransform(0)),系統會發出 OnError 事件。系統會忽略產生錯誤的作業,並關閉管道。
如果執行成功,系統會發出 OnNextFrameBegin,並提供有效的影格產生資訊。
只有在用戶端擁有非零數量的顯示點數時,才能呼叫 Present,這些點數會由伺服器追蹤。伺服器觸發 OnNextFrameBegin 事件時,可能會增加點數數量,並在用戶端收到額外顯示點數時通知用戶端。每次呼叫 Present 都會使用一個 Present 點數,並將伺服器計數減一。如果用戶端在沒有 Present 抵免額的情況下呼叫 Present,伺服器會傳回 NO_PRESENTS_REMAINING 錯誤。
用戶端應假設在收到任何 OnNextFrameBegin 事件之前,他們有一個顯示抵免額。
每次 Present 呼叫都會產生一個 OnNextFrameBegin 事件和一個 OnFramePresented 事件,通常會依此順序。
當 Present 排出的指令顯示時,系統會觸發 OnFramePresented 事件。這項事件包含與所有呈現相關的資訊,這些呈現的內容是該影格的一部分。
如要進一步瞭解傳入的引數及其角色,請參閱上方的 fuchsia.ui.composition/PresentArgs 說明文件。
要求
| 名稱 | 類型 |
|---|---|
args |
PresentArgs
|
ReleaseFilledRect
當矩形不再需要用於算繪時,系統會自動進行垃圾收集。|rect_id| 必須透過呼叫 |CreateFilledRect| 例項化。釋出後,ID 會立即超出範圍,並可再次使用。
rect_id 必須參照有效的未釋出填滿矩形。
要求
| 名稱 | 類型 |
|---|---|
rect_id |
ContentId
|
ReleaseImage
當圖片不再需要用於算繪時,系統會對釋出的圖片進行垃圾收集。如果是圖片,這表示圖片不再附加至任何轉換,且參照圖片的任何待處理算繪作業都已完成。
使用 SetContent(transform_id, 0) 清除已釋出圖片的參照。
釋出後,該 ID 會立即超出未來函式呼叫的範圍,並可在建立新圖片時重複使用。
使用已釋出的 ID 呼叫函式會發生錯誤 (除非該 ID 已重複用於建構新的 Image)。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ContentId
|
ReleaseImage2
當圖片不再需要用於算繪時,系統會對釋出的圖片進行垃圾收集。圖片:
- 圖片不再繫結至任何圖層,且
- 參照該圖片的所有待處理算繪作業都已完成。
image_id 值會立即釋出,供用戶端重複使用 (ID 唯一性是即時的)。
注意:每個繫結的釋放柵欄 (傳遞至 SetLayerImage) 不會受到這項呼叫的影響。這些物件會追蹤個別層繫結的生命週期,而非用戶端的 image_id。
image_id 必須參照有效的未發布映像檔。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ImageId
|
ReleaseImageImmediately
立即釋出圖片,不等待下一個顯示。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ContentId
|
ReleaseImageImmediately2
立即釋出圖片,不必等待下一個顯示。這是可信任的記憶體清除路徑。
系統會強制解除映像檔與目前參照該映像檔的所有層之間的繫結。在下次 SetLayerImage() 之前,這些圖層的行為就像從未設定圖片一樣 (圖層不可見,但會保留圖片屬性)。
對於遭淘汰 Image 的繫結,任何待處理的釋放柵欄都會在最早的安全點發出信號。
只有在啟用 Flatland2 且工作階段可信任時,才能使用這個方法。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ImageId
|
ReleaseLayer
系統會在不再需要轉譯時,對釋出的圖層進行垃圾收集。對 Layers 而言,這代表:
- Layer 不再由任何 LayerStack 參照,且
- 任何參照該圖層的待處理算繪作業都已完成。
layer_id 必須參照有效的未發布圖層。
要求
| 名稱 | 類型 |
|---|---|
layer_id |
LayerId
|
ReleaseLayerStack
釋出具有指定 stack_id 的圖層堆疊。
要求
| 名稱 | 類型 |
|---|---|
stack_id |
LayerStackId
|
ReleaseTransform
系統會在不再需要轉譯時,對釋出的轉換進行垃圾收集。就轉換而言,這表示任何未發布的轉換都沒有路徑可通往新發布的轉換。
釋出後,該 ID 會立即超出未來函式呼叫的範圍,並可在建立新轉換時重複使用。
使用已釋出的 ID 呼叫函式會發生錯誤 (除非該 ID 已重複用於建構新的 Transform)。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
ReleaseView
釋出 View,將這個 Flatland 工作階段與另一個 Flatland 工作階段中的父項 Viewport 中斷連線。
如要清除畫面上的現有內容,而不釋出目前的 View,請改用 SetRootTransform(0)。
雖然有傳回類型,但這個函式仍是前饋式,就像 CreateView 一樣,需要呼叫 Present 才能執行。執行顯示作業後,系統會傳回 ViewCreationToken。
要求
<EMPTY>
ReleaseViewport
從場景中釋放檢視區塊,即使檢視區塊仍連結至轉換也一樣。與其他資源不同,系統會在下一次呈現時,透過垃圾收集機制回收檢視區,因為已移除的檢視區保證不會提供可轉譯的內容。
使用 SetContent(transform_id, 0) 清理已釋出可視區域的參照。
雖然這個函式有傳回類型,但仍與 CreateView 一樣是前饋函式,需要呼叫 Present 才能執行。執行顯示作業後,系統會傳回 ViewportCreationToken。
要求
| 名稱 | 類型 |
|---|---|
viewport_id |
ContentId
|
回應
| 名稱 | 類型 |
|---|---|
token |
fuchsia.ui.views/ViewportCreationToken
|
ReleaseViewport2
從場景中釋出可視區域。
要求
| 名稱 | 類型 |
|---|---|
viewport_id |
ViewportId
|
回應
| 名稱 | 類型 |
|---|---|
token |
fuchsia.ui.views/ViewportCreationToken
|
RemoveChild
從父項轉換中移除子項轉換。
要求
| 名稱 | 類型 |
|---|---|
parent_transform_id |
TransformId
|
child_transform_id |
TransformId
|
ReplaceChildren
從父項轉換中移除所有子項轉換,並將其替換為 new_child_transform_ids 中的新子項轉換。呼叫端必須確保 new_child_transform_ids 中的所有 TransformId 值都有效,且沒有重複。在 new_child_transform_ids 中傳送重複的 TransformId 會導致工作階段關閉。
要求
| 名稱 | 類型 |
|---|---|
parent_transform_id |
TransformId
|
new_child_transform_ids |
vector<TransformId>:64
|
ResetLayer
解除繫結至圖層的任何圖片,並清除所有儲存的 LayerProperties 欄位,將圖層恢復為剛建立的狀態 (撰寫模式 INVISIBLE,所有屬性均為記錄的預設值)。這是唯一會清除儲存圖層屬性的作業。
layer_id 必須參照有效的未發布圖層。
要求
| 名稱 | 類型 |
|---|---|
layer_id |
LayerId
|
SetClipBoundary
設定邊界 (以轉換的本機座標空間表示),限制附加至這項轉換的內容可算繪的區域。如果內容區域超出裁剪邊界,系統就不會算繪邊界外的區域。這些界限也適用於這個轉換節點的所有子項,包括巢狀 Flatland 工作階段及其節點階層。如果子項轉換嘗試設定大於父項的剪輯邊界,則會剪輯至父項的剪輯邊界。預設狀態是未裁剪轉換,也就是說,其算繪區域不會有任何邊界。剪輯寬度/高度必須為正數。負值會導致錯誤。將空白方塊傳遞至 |rect| 參數,即可移除裁剪邊界。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
rect |
fuchsia.math/Rect?
|
SetContent
只要從根層級 Transform 可以看到 Transform,在 Transform 上設定內容,就會在算繪樹狀結構中顯示該內容。內容會在附加至轉換子項的任何內容之前算繪,因此會「位於其後方」。
由於每個轉換最多只能有一個內容,因此在已有內容的轉換上呼叫這個函式會取代該內容。
一個 Content 可設定多個 Transform。
呼叫此函式時,如果 Content ID 為 0,系統會移除轉換中目前的所有內容。
content_id 必須參照有效且未發布的 Content 物件,或設為 0 來清除。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
content_id |
ContentId
|
SetDebugName
設定目前用戶端的偵錯名稱,Flatland 可將其做為記錄的前置字串,協助用戶端區分自己的記錄。name 可以是任意字串,但建議使用目前程序名稱 (請參閱 fsl::GetCurrentProcessName()) 做為預設值。
要求
| 名稱 | 類型 |
|---|---|
name |
string:64
|
SetHitRegions
設定轉換的互動區域。根據預設,內容不具互動性;必須放置點擊區域,使用者才能與檢視畫面中的內容互動。由於 Flatland 通訊協定會描述命中區域,因此 Flatland 工作階段可以同步處理內容和命中區域。
每個點擊區域都會放置在所屬轉換的座標空間中,且可能會或不會與不同類型的點擊測試互動,具體取決於其 HitTestInteraction 類型。如果有多個點擊區域與點擊測試相交,則會根據下列優先順序規則,決定哪個點擊區域與點擊測試互動。只有可轉移連接至根層級 Transform 的 Transform,其點擊區域才會與點擊測試互動。
呼叫這個函式會取代先前在這個轉換上設定的所有值。如要將轉換重設為「不進行點擊測試」,請使用 SetHitRegions 傳送空白向量。
請注意,根轉換會取得 Flatland 安裝的預設命中區域。詳情請參閱 SetRootTransform 說明文件。
優先順序規則 在轉換中,如果多個點擊區域重疊,點擊測試會檢查每個相交的點擊區域,找出可能的互動。因此,對於一般點擊測試 R 和無障礙點擊測試 A,其中 R 和 A 都與同一轉換上的兩個點擊區域 D (DEFAULT) 和 S (SEMANTICALLY_INVISIBLE) 相交,(1) R 與 D 和 S 互動,以及 (2) A 僅與 D 互動。一般來說,單一轉換中的點擊區域重疊可能會導致混淆行為。
在檢視畫面中,對於特定點擊測試,最前面的轉換點擊區域優先於後面的區域。這會遵循轉換的預期反向「算繪順序」(如 CreateTransform 所述),使用者預期會與可見或最前端的內容互動。
在 Flatland 工作階段中,對於特定點擊測試,最前端工作階段的最前端轉換點擊區域優先於後方區域。這符合預期的反向檢視畫面「算繪順序」,使用者預期會與可見或最前方的檢視畫面互動。舉例來說,如果孩童檢視模式擁有的內容在家長檢視模式上算繪,使用者會預期與孩童檢視模式的內容互動。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
regions |
vector<HitRegion>:64
|
SetImageBlendMode
決定在算繪 |image_id| 指定的內容時,要使用的混合函式。|image_id| 必須是有效的 ContentId,且已透過呼叫 |CreateImage| 或 |CreateFilledRect| 與轉換作業建立關聯。如要進一步瞭解可用的混合函式,請參閱 BlendMode2 列舉。如未呼叫這個函式,預設的混合模式為 BlendMode2::REPLACE。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ContentId
|
blend_mode |
BlendMode2
|
SetImageBlendingFunction
決定轉譯 |image_id| 指定的內容時,要使用的混合函式。|image_id| 必須是有效的 ContentId,且已透過呼叫 |CreateImage| 或 |CreateFilledRect| 與轉換作業建立關聯。如要進一步瞭解可用的混合函式,請參閱 BlendMode 列舉。如未呼叫這個函式,預設混合模式為 BlendMode::SRC。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ContentId
|
blend_mode |
BlendMode
|
SetImageDestinationSize
圖片的內容大小是指圖片在父項邏輯座標空間中占用的矩形大小。這項屬性與附加轉換的全域平移搭配使用,可決定內容在螢幕上顯示的大小和位置。
如未呼叫這個方法,預設圖片目標大小會是 CreateImage 的 ImageProperties 中設定的寬度和高度。如果在附加的 Transform 或其父項上使用 SetScale,目標大小會受到縮放影響。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ContentId
|
size |
fuchsia.math/SizeU
|
SetImageFlip
設定要套用至平面圖片的圖片翻轉效果。這項呼叫必須在成功呼叫 |CreateImage| 後執行。如果提供無效的 |image_id|,管道會因 FlatlandError::BAD_OPERATION 而關閉。這項翻轉作業會先套用至圖片,再套用至父項轉換方向。如未呼叫這個函式,預設翻轉值為 ImageFlip::NONE。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ContentId
|
flip |
ImageFlip
|
SetImageOpacity
設定要套用至 Flatland 圖片的線性空間不透明度。不透明度值必須介於 [0.0, 1.0] 範圍內。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ContentId
|
val |
float32
|
SetImageSampleRegion
這個函式用於判斷 Flatland 算繪時,要使用的圖片區域 (在紋素空間中)。要取樣的圖片由 image_id 參照,取樣區域則由 rect 指定,其本身由原點 (x,y) 以及寬度和高度組成,採用未正規化的座標。在非圖片內容上呼叫這個函式,或在圖片的紋素空間外取樣,都屬於非法行為。換句話說,rect 指定的區域不得超過 (0, image_width) 和 (0, image_height) 的範圍。如果 (rect.x + rect.width > image_width) 或 (rect.y + rect.height > image_height),或任何值為負數,就會發生錯誤。
如未呼叫這個方法,預設取樣區域會是原點為 (0, 0) 的矩形,寬度和高度則設為 CreateImage 的 ImageProperties。
image_id 必須參照有效的未發布映像檔。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ContentId
|
rect |
fuchsia.math/RectF
|
SetInfiniteHitRegion
與 SetHitRegions 相同,但與 transform_id 相關聯的命中區域涵蓋無限區域。命中區域不會因轉換的平移、縮放和方向而改變。
無限點擊區域的範圍仍受限於 View 的裁剪邊界,就像有限點擊區域一樣。
呼叫這個函式會取代先前在這個轉換上設定的所有值。如要將轉換重設為「不進行點擊測試」,請使用 SetHitRegions 傳送空白向量。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
hit_test |
HitTestInteraction
|
SetLayerImage
將圖片與圖層建立關聯。
繫結在任何合成模式中都合法,且具有黏性:在合成模式變更後仍會保留,且只有在後續呼叫 SetLayerImage 時才會被取代 (或由 ResetLayer 清除)。只有在圖層的合成模式為 IMAGE 時,系統才會顯示圖片。
繫結圖片必須夠大,才能容納圖層儲存的 sample_rect;這項檢查會在 fuchsia.ui.composition/Flatland.Present 進行,而非在此處。請參閱 LayerProperties.sample_rect。
layer_id 必須參照有效的未發布圖層。image_id 必須參照有效的未發布映像檔。acquire_fence 是選用的柵欄,必須在顯示圖片前發出信號。release_fence 是選用柵欄,當這個繫結不再參照圖片時,Scenic 會發出信號。這是以繫結為單位,而非以圖片為單位:繫結至多個圖層的圖片,每個繫結都有一個這類柵欄,且只有在每個柵欄都發出信號後,圖片才能安全寫入。
繫結會在下列情況結束:
- 在同一層上被後續的 SetLayerImage 取代
- ResetLayer
- 圖層參照計數達到零,無論是透過 ReleaseLayer 還是由圖層堆疊釋放
- 工作階段終止,結束所有繫結
如果繫結在工作階段進行期間結束,Scenic 會在第一個影格淘汰後發出信號。如果繫結從未顯示在螢幕上 (例如在單一批次中被取代,或在多個 fuchsia.ui.composition/Flatland.Present 呼叫壓縮成單一影格時遺失),則會在該淘汰時發出信號,而非立即發出。因此,訊號最多會保守一個影格,絕不會提早。
要求
| 名稱 | 類型 |
|---|---|
layer_id |
LayerId
|
image_id |
ImageId
|
acquire_fence |
WaitFence?
|
release_fence |
SignalFence?
|
SetLayerProperties
設定圖層屬性。
提供的 properties 表格會合併至圖層的儲存屬性:properties 中未設定的欄位會保留先前儲存的值。儲存的屬性具有黏性;如需完整的持續性語意,請參閱 LayerProperties。
值會依指定方式儲存;取決於其他狀態的驗證 (特別是針對繫結圖片的 sample_rect) 會在 fuchsia.ui.composition/Flatland.Present 進行。請參閱 LayerProperties.sample_rect。
layer_id 必須參照有效的未發布圖層。
要求
| 名稱 | 類型 |
|---|---|
layer_id |
LayerId
|
properties |
LayerProperties
|
SetOpacity
設定線性空間中的不透明度,套用至轉換及其子項,包括其他轉換和內容。不透明度值必須介於 [0.0, 1.0] 之間,其中 0.0 表示完全透明,1.0 表示完全不透明。如果嘗試使用超出該範圍的值呼叫這個函式,會導致錯誤。轉換的不透明度值會與父項的不透明度值相乘。這項效果與群組不透明度的運作方式不同。使用群組不透明度時,子節點會先一起算繪,然後再套用父項的不透明度做為後製效果。不透明度會個別套用至每個子項。這可能會導致截然不同的效果。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
value |
float32
|
SetOrientation
設定轉換的方向。如要瞭解幾何屬性的套用順序,請參閱 SetTranslation 的說明文件。在 Flatland 中,+X 軸位於右側,+Y 軸則位於下方。沒有 Z 軸的概念。逆時針方向是從使用者的視角定義,就像螢幕上顯示擬真時鐘一樣。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
orientation |
Orientation
|
SetRootTransform
設定圖表的根轉換。
由根轉換及其子項定義的子圖,會在連結父項的檢視區塊中算繪為檢視畫面 (請參閱 CreateView)。系統會忽略這個圖表中根轉換的任何父項。
如果釋出根轉換和根轉換的所有子項,這些項目會保持運作 (詳情請參閱 ReleaseTransform)。
根節點只會有一個。由於 0 不是有效的轉換 ID (請參閱 CreateTransform),呼叫 SetRootTransform(0) 會清除目前的 Root,並刪除先前發布但新 Root 未參照的任何物件。
請注意,每個 View 都有一個剪輯邊界,相當於其邏輯大小。剪輯邊界以外的任何內容都不會算繪。因此,根層級轉換的實用座標空間為 (0, 0) 到 (logical_size.width, logical_size.height),其中 (0, 0) 是左上角。
設定根轉換後,系統會在根轉換上安裝全螢幕點擊區域。如果用戶端不希望使用者與根轉換的內容互動,可以移除這個命中區域。如要進一步瞭解命中區域,請參閱 SetHitRegions 說明文件。
預設命中區域規則
預設點擊區域遵循下列規則:
- 呼叫 SetRootTransform(T) 時,T 會收到最大命中區域,涵蓋整個檢視畫面。
- 如果在 SetRootTransform(T) 之前或之後,對 T 呼叫 SetHitRegions,則不會啟用預設命中區域,而是使用用戶端指定的命中區域。
- 如果轉換不再是根轉換,也就是呼叫 SetRootTransform(U) 後,原始轉換就不再具有預設命中區域。
- 用戶端可以移除或修改根轉換的命中區域,方法與重設任何其他轉換的命中區域相同,只要使用適當的向量呼叫 SetHitRegions 即可。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
SetScale
設定轉換的縮放比例。幾何屬性的套用順序如上所述。VecF |scale| 中的 (x,y) 值分別代表 x 軸 (寬度) 和 y 軸 (高度) 的縮放比例係數。縮放值必須是正 32 位元浮點值:https://en.wikipedia.org/wiki/Normal_number_%28computing%29
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
scale |
fuchsia.math/VecF
|
SetSolidFill
定義填滿矩形的顏色和大小。|rect_id| 必須參照透過呼叫 CreateFilledRect 建立的內容。顏色未預乘。顏色值必須介於 [0,1] 範圍內 (含),且為一般 32 位元浮點值:https://en.wikipedia.org/wiki/Normal_number_%28computing%29。不符合這些規格的值會導致管道關閉。矩形的左上角會位於轉換座標空間中的 (0, 0)。因此,右下角會位於 (size.width, size.height)。
rect_id 必須參照有效的未釋出填滿矩形。
要求
| 名稱 | 類型 |
|---|---|
rect_id |
ContentId
|
color |
ColorRgba
|
size |
fuchsia.math/SizeU
|
SetStackLayers
設定堆疊中的圖層。向量中的圖層順序決定了 Z 軸順序,第一個元素位於最底層,最後一個元素位於最上層。
stack_id 必須參照有效的未發布 LayerStack。layers 的每個元素都必須參照有效的未發布圖層。layers 內不得有重複的圖層。
要求
| 名稱 | 類型 |
|---|---|
stack_id |
LayerStackId
|
layers |
vector<LayerId>:32
|
SetTransformContent
設定 (或清除) 轉換內容。
相同內容可以附加至多個轉換;每個附加項目都會在自己的轉換矩陣、剪輯和不透明度下再次合成該內容,因此單一 LayerStack 或 Viewport 可以在場景中重複出現,而用戶端不必複製基礎資源。
如不提供選用的 content,即可清除轉換內容。
如果設定 content,則必須參照有效且未發布的 LayerStack 或 Viewport。
與傳統的 Flatland.SetContent 不同,零 ID 不會清除內容。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
content |
TransformContent?
|
SetTranslation
所有轉換物件都支援所有屬性。
幾何屬性會依下列順序套用:
- 縮放 (相對於父項轉換的座標空間)
- 方向 (相對於父項轉換的座標空間)
- 平移 (相對於父項轉換的座標空間,不受套用至目前轉換的縮放影響)。
- 裁剪 (相對於目前轉換的座標空間)
這些屬性的效果會累加。這表示系統會根據幾何屬性鏈 (向上延伸至根轉換),計算轉換在檢視區塊空間中的位置和裁剪邊界。
舉例來說,在以下巢狀階層中: [Root-Transform -> Transform1 -> Transform2 -> CurrentTransform] 如果 Transform1 經 [2,0] 轉換,Transform2 經 [0,1] 轉換,則 CurrentTransform 的檢視空間位置會是 [2,1]。
設定轉換的平移。幾何屬性的套用順序如上所述。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
translation |
fuchsia.math/Vec
|
SetViewportProperties
轉換通常足以變更內容的呈現方式。不過,檢視區塊具有不屬於轉換階層的特殊屬性。您可以使用這個函式設定這些屬性。
要求
| 名稱 | 類型 |
|---|---|
viewport_id |
ContentId
|
properties |
ViewportProperties
|
SetViewportProperties2
設定可視區域的屬性。
要求
| 名稱 | 類型 |
|---|---|
viewport_id |
ViewportId
|
properties |
ViewportProperties
|
Flatland2
定義於 fuchsia.ui.composition/flatland2.fidl
這項通訊協定會整合至「傳統」Flatland 通訊協定,並清除原始設計中的一些「瑕疵」。
只有在啟用 Flatland2 時 (例如透過 TrustedFlatlandConfig.use_flatland2_api),才能使用這個通訊協定中定義的所有方法。在未啟用 Flatland2 的情況下呼叫這些方法,會導致管道關閉。
一般來說,「瑕疵」是指圖片上不應設定的屬性。舉例來說,應該可以並排顯示同一張圖片的兩個副本,其中一張圖片翻轉 LEFT_RIGHT 以反映另一張圖片。在傳統的 Flatland API 中,這是不可能的,因為翻轉是圖片的屬性。在 Flatland2 中,翻轉是圖層的屬性,用戶端只要使用兩個具有相同圖片和不同翻轉的圖層,就能輕鬆達成目標。
啟用 Flatland2 時,某些「傳統」Flatland 方法會停用/不合法。這些方法最終會移除,Flatland2 將成為在 Flatland 中顯示圖片的標準方式。在此之前,客戶可以透過「選擇加入」的方式,輕鬆遷移至這個現代化 API。停用的方法如下:
- fuchsia.ui.composition/Flatland.CreateFilledRect
- fuchsia.ui.composition/Flatland.CreateImage
- fuchsia.ui.composition/Flatland.CreateViewport
- fuchsia.ui.composition/Flatland.ReleaseFilledRect
- fuchsia.ui.composition/Flatland.ReleaseImage
- fuchsia.ui.composition/Flatland.ReleaseViewport
- fuchsia.ui.composition/Flatland.SetContent
- fuchsia.ui.composition/Flatland.SetImageBlendingFunction
- fuchsia.ui.composition/Flatland.SetImageBlendMode
- fuchsia.ui.composition/Flatland.SetImageDestinationSize
- fuchsia.ui.composition/Flatland.SetImageFlip
- fuchsia.ui.composition/Flatland.SetImageOpacity
- fuchsia.ui.composition/Flatland.SetSolidFill
- fuchsia.ui.composition/Flatland.SetImageSampleRegion
- fuchsia.ui.composition/Flatland.SetViewportProperties
- fuchsia.ui.composition/TrustedFlatland.ReleaseImageImmediately
CreateImage2
建立映像檔資源。
image_id 必須符合 LayerId 記載的 ID 規則。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ImageId
|
import_token |
BufferCollectionImportToken
|
vmo_index |
uint32
|
properties |
ImageProperties
|
CreateLayer
圖層是一種 Content,可合成單一 Image 或純色。它會將視覺屬性 (例如大小、翻轉、不透明度和混合) 與原始像素資料分開。
一般的 Content 項目代表靜態視覺資源,而圖層則設計為圖片序列的動態容器。一般用法包括不常設定圖層的視覺屬性和圖片中繼資料,然後快速將使用中的 Image (例如在每個影格上) 替換為具有相符中繼資料的其他圖片。
這種分離方式可讓單一 Image 資源在多個圖層中重複使用,同時採用不同的視覺設定。
如何使用圖層:
- 使用 CreateLayer 建立
Layer。 - 透過 SetLayerProperties 設定
Layer的屬性,包括合成模式。 - 如果是圖片圖層,請透過 SetLayerImage 將
Image與Layer建立關聯。 - 透過 SetStackLayers 將
Layer新增至LayerStack。 - 透過 SetTransformContent 將
LayerStack設為節點的內容。
layer_id 必須符合 LayerId 記載的 ID 規則。
要求
| 名稱 | 類型 |
|---|---|
layer_id |
LayerId
|
CreateLayerStack
使用指定的 stack_id 建立新的圖層堆疊。
stack_id 必須符合 LayerId 記載的 ID 規則。
要求
| 名稱 | 類型 |
|---|---|
stack_id |
LayerStackId
|
CreateViewport2
建立 Viewport 資源。
viewport_id 必須符合 LayerId 記載的 ID 規則。
要求
| 名稱 | 類型 |
|---|---|
viewport_id |
ViewportId
|
token |
fuchsia.ui.views/ViewportCreationToken
|
properties |
ViewportProperties
|
child_view_watcher |
server_end:ChildViewWatcher
|
ReleaseImage2
當圖片不再需要用於算繪時,系統會對釋出的圖片進行垃圾收集。圖片:
- 圖片不再繫結至任何圖層,且
- 參照該圖片的所有待處理算繪作業都已完成。
image_id 值會立即釋出,供用戶端重複使用 (ID 唯一性是即時的)。
注意:每個繫結的釋放柵欄 (傳遞至 SetLayerImage) 不會受到這項呼叫的影響。這些物件會追蹤個別層繫結的生命週期,而非用戶端的 image_id。
image_id 必須參照有效的未發布映像檔。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ImageId
|
ReleaseLayer
系統會在不再需要轉譯時,對釋出的圖層進行垃圾收集。對 Layers 而言,這代表:
- Layer 不再由任何 LayerStack 參照,且
- 任何參照該圖層的待處理算繪作業都已完成。
layer_id 必須參照有效的未發布圖層。
要求
| 名稱 | 類型 |
|---|---|
layer_id |
LayerId
|
ReleaseLayerStack
釋出具有指定 stack_id 的圖層堆疊。
要求
| 名稱 | 類型 |
|---|---|
stack_id |
LayerStackId
|
ReleaseViewport2
從場景中釋出可視區域。
要求
| 名稱 | 類型 |
|---|---|
viewport_id |
ViewportId
|
回應
| 名稱 | 類型 |
|---|---|
token |
fuchsia.ui.views/ViewportCreationToken
|
ResetLayer
解除繫結至圖層的任何圖片,並清除所有儲存的 LayerProperties 欄位,將圖層恢復為剛建立的狀態 (撰寫模式 INVISIBLE,所有屬性均為記錄的預設值)。這是唯一會清除儲存圖層屬性的作業。
layer_id 必須參照有效的未發布圖層。
要求
| 名稱 | 類型 |
|---|---|
layer_id |
LayerId
|
SetLayerImage
將圖片與圖層建立關聯。
繫結在任何合成模式中都合法,且具有黏性:在合成模式變更後仍會保留,且只有在後續呼叫 SetLayerImage 時才會被取代 (或由 ResetLayer 清除)。只有在圖層的合成模式為 IMAGE 時,系統才會顯示圖片。
繫結圖片必須夠大,才能容納圖層儲存的 sample_rect;這項檢查會在 fuchsia.ui.composition/Flatland.Present 進行,而非在此處。請參閱 LayerProperties.sample_rect。
layer_id 必須參照有效的未發布圖層。image_id 必須參照有效的未發布映像檔。acquire_fence 是選用的柵欄,必須在顯示圖片前發出信號。release_fence 是選用柵欄,當這個繫結不再參照圖片時,Scenic 會發出信號。這是以繫結為單位,而非以圖片為單位:繫結至多個圖層的圖片,每個繫結都有一個這類柵欄,且只有在每個柵欄都發出信號後,圖片才能安全寫入。
繫結會在下列情況結束:
- 在同一層上被後續的 SetLayerImage 取代
- ResetLayer
- 圖層參照計數達到零,無論是透過 ReleaseLayer 還是由圖層堆疊釋放
- 工作階段終止,結束所有繫結
如果繫結在工作階段進行期間結束,Scenic 會在第一個影格淘汰後發出信號。如果繫結從未顯示在螢幕上 (例如在單一批次中被取代,或在多個 fuchsia.ui.composition/Flatland.Present 呼叫壓縮成單一影格時遺失),則會在該淘汰時發出信號,而非立即發出。因此,訊號最多會保守一個影格,絕不會提早。
要求
| 名稱 | 類型 |
|---|---|
layer_id |
LayerId
|
image_id |
ImageId
|
acquire_fence |
WaitFence?
|
release_fence |
SignalFence?
|
SetLayerProperties
設定圖層屬性。
提供的 properties 表格會合併至圖層的儲存屬性:properties 中未設定的欄位會保留先前儲存的值。儲存的屬性具有黏性;如需完整的持續性語意,請參閱 LayerProperties。
值會依指定方式儲存;取決於其他狀態的驗證 (特別是針對繫結圖片的 sample_rect) 會在 fuchsia.ui.composition/Flatland.Present 進行。請參閱 LayerProperties.sample_rect。
layer_id 必須參照有效的未發布圖層。
要求
| 名稱 | 類型 |
|---|---|
layer_id |
LayerId
|
properties |
LayerProperties
|
SetStackLayers
設定堆疊中的圖層。向量中的圖層順序決定了 Z 軸順序,第一個元素位於最底層,最後一個元素位於最上層。
stack_id 必須參照有效的未發布 LayerStack。layers 的每個元素都必須參照有效的未發布圖層。layers 內不得有重複的圖層。
要求
| 名稱 | 類型 |
|---|---|
stack_id |
LayerStackId
|
layers |
vector<LayerId>:32
|
SetTransformContent
設定 (或清除) 轉換內容。
相同內容可以附加至多個轉換;每個附加項目都會在自己的轉換矩陣、剪輯和不透明度下再次合成該內容,因此單一 LayerStack 或 Viewport 可以在場景中重複出現,而用戶端不必複製基礎資源。
如不提供選用的 content,即可清除轉換內容。
如果設定 content,則必須參照有效且未釋出的 LayerStack 或 Viewport。
與傳統的 Flatland.SetContent 不同,零 ID 不會清除內容。
要求
| 名稱 | 類型 |
|---|---|
transform_id |
TransformId
|
content |
TransformContent?
|
SetViewportProperties2
設定可視區域的屬性。
要求
| 名稱 | 類型 |
|---|---|
viewport_id |
ViewportId
|
properties |
ViewportProperties
|
FlatlandDisplay
定義於 fuchsia.ui.composition/flatland.fidl
這個 API 會連線至單例模式「主要螢幕」,並允許在下方附加 Flatland 內容樹狀結構。一次只能有一個 FlatlandDisplay 用戶端連線。
SetContent
要求
| 名稱 | 類型 |
|---|---|
token |
fuchsia.ui.views/ViewportCreationToken
|
child_view_watcher |
server_end:ChildViewWatcher
|
SetDevicePixelRatio
設定顯示器的實體像素與裝置獨立像素的比率,用於附加至此顯示器的 Flatland 內容樹狀結構。詳情請參閱 LayoutInfo.device_pixel_ratio。
預設值為 (1.0, 1.0)。有效值為 1.0 以上。
要求
| 名稱 | 類型 |
|---|---|
device_pixel_ratio |
fuchsia.math/VecF
|
FlatlandFactory
定義於 fuchsia.ui.composition/flatland_factory.fidl
用於產生一般 (不受信任) Flatland 工作階段的工廠通訊協定。
CreateFlatland
使用指定設定建立新的 Flatland 工作階段。
用戶端應樂觀假設連線成功,並立即開始管道化 fuchsia.ui.composition/Flatland 要求,而不必等待這個方法傳回。如果工作階段建立失敗,fuchsia.ui.composition/FlatlandFactory 伺服器會關閉 Flatland 工作階段管道,並傳回 fuchsia.ui.composition/FlatlandFactoryError。用戶端應以非同步方式處理這項失敗,並捨棄 Flatland 用戶端端點。
錯誤
如果作業失敗,則傳回 FlatlandFactoryError。
要求
| 名稱 | 類型 |
|---|---|
server_end |
server_end:Flatland
|
config |
FlatlandConfig
|
回應
| 名稱 | 類型 |
|---|---|
payload |
FlatlandFactory_CreateFlatland_Result
|
ParentViewportWatcher
定義於 fuchsia.ui.composition/flatland.fidl
這項通訊協定會提供與 Flatland 工作階段唯一檢視畫面連結的父項 Viewport 相關資訊。雖然 Flatland 工作階段最多只能有一個檢視畫面,但在將工作階段的檢視畫面替換為另一個檢視畫面 (例如透過 CreateView) 的短暫轉換期間,可能會有多個 ParentViewportWatcher。在這段期間,某些更新可能會重複,並傳送至每個 ParentViewportWatcher 連線。
只要對應的父項 Viewport 存在,ParentViewportWatcher 就會保持連線;如果父項的 ViewportCreationToken 未用於建立 Viewport 即遭捨棄,連線也會關閉。
GetLayout
用於接收版面配置資訊的 Hanging Get。用戶端可能會在 ParentViewportWatcher 作業顯示前收到版面配置資訊。這樣一來,子項就能在首次呼叫 Present 之前,先配置內容。在兩個 ParentViewportWatcher 管道同時存在的轉換情況下,兩個通訊協定工作階段都會收到不同的版面配置資訊。
只有在 LayoutInfo 與先前傳回的 LayoutInfo 不同時,系統才會觸發這個 Hanging Get。請注意,由於 LayoutInfo 是表格,因此可能只有部分欄位會變更。
如果先前的呼叫仍在處理中,則呼叫 GetLayout 無效。這麼做會導致這個管道和提供 ParentViewportWatcher 的 Flatland 管道關閉。
要求
<EMPTY>
回應
| 名稱 | 類型 |
|---|---|
info |
LayoutInfo
|
GetStatus
用於接收父項 Viewport 狀態的懸置 GET。這會為子項提供全域連線能力資訊。
只有在 ParentViewportStatus 與先前傳回的 ParentViewportStatus 不同時,系統才會觸發這個懸置 GET。
如果先前的呼叫仍在處理中,則呼叫 GetStatus 無效。這麼做會導致這個管道和提供 ParentViewportWatcher 的 Flatland 管道關閉。
要求
<EMPTY>
回應
| 名稱 | 類型 |
|---|---|
status |
ParentViewportStatus
|
ScreenCapture
定義於 fuchsia.ui.composition/screen_capture.fidl
這項通訊協定提供低階 ScreenCapture API,供用戶端使用。ScreenCapture 用戶端應熟悉 fuchsia.sysmem/BufferCollection 和 fuchsia.ui.composition/Allocator 通訊協定,因為這些通訊協定是建立 ScreenCapture 使用的 BufferCollection 和圖片所必需。
設定
用戶端應先使用 Allocator 通訊協定註冊 BufferCollection。除非 BufferCollection 的所有用戶端都已設定限制,否則這個函式會失敗,並傳回 BAD_OPERATION。
之後,用戶端應建立並設定最終會使用這個方法算繪的圖片。集合中從 0 到 (buffer_count-1) 的所有緩衝區都可用於螢幕畫面擷取。
用戶端負責判斷螢幕旋轉方向,並套用修正旋轉。舉例來說,如果螢幕順時針旋轉 90 度 (從螢幕正面看,「頂端」位於右側),用戶端應指定旋轉 270 度,以因應這種情況。
同樣地,用戶端必須指定足夠大的緩衝區,才能容納旋轉後的圖片。如果緩衝區太小,系統會盡可能嘗試算繪圖片。
最後,用戶端會使用 GetNextFrame 要求伺服器將目前畫面算繪至共用緩衝區。
如果用戶端想變更任何設定,可以使用新的 BufferCollectionImportToken 再次呼叫 Configure。在這種情況下,先前呼叫 Configure 的所有緩衝區都會釋出。
要求
| 名稱 | 類型 |
|---|---|
payload |
ScreenCaptureConfig
|
回應
| 名稱 | 類型 |
|---|---|
payload |
ScreenCapture_Configure_Result
|
GetNextFrame
成功呼叫 Configure 後,用戶端可以呼叫 GetNextFrame。這會將最新的影格填入緩衝區。
用戶端應等待傳遞的 zx::event,確認螢幕截圖成功完成。不保證在函式傳回時,螢幕截圖會完成。
要求的圖片會位於 BufferCollection 中,該 BufferCollection 是由用戶端在 VMO 中設定,位於 buffer_id 指定的索引。
使用 ScreenCapture 提供串流時,用戶端呼叫 GetNextFrame 的速率會決定影格率。
錯誤: BAD_OPERATION:未呼叫 Configure,或呼叫失敗 MISSING_ARGS:缺少必要引數 BUFFER_FULL:BufferCollection 中的所有緩衝區都在使用中。在這種情況下,必須先呼叫 ReleaseFrame 讓緩衝區可用,才能成功呼叫這個函式。
要求
| 名稱 | 類型 |
|---|---|
payload |
GetNextFrameArgs
|
回應
| 名稱 | 類型 |
|---|---|
payload |
ScreenCapture_GetNextFrame_Result
|
ReleaseFrame
用戶端不再需要圖片時,可以對緩衝區的 VMO 索引呼叫 ReleaseFrame,讓伺服器日後重複使用。
要求
| 名稱 | 類型 |
|---|---|
buffer_id |
uint32
|
回應
| 名稱 | 類型 |
|---|---|
payload |
ScreenCapture_ReleaseFrame_Result
|
螢幕截圖
定義於 fuchsia.ui.composition/screenshot.fidl
收集螢幕目前的圖形內容。
走
在 sRGB 色域中,收集指定緩衝區 format 內顯示畫面的目前圖形內容。請注意,sRGB 色域是非線性的,也就是說,使用非完全飽和色彩進行像素相等檢查的單元測試,應轉換為線性色域。
詳情請參閱 https://fuchsia.dev/fuchsia-src/concepts/ui/scenic/color_spaces。
系統會立即擷取螢幕截圖,並填入最近一次 VSYNC 的螢幕內容。
如果用戶端在第一個 Take 呼叫傳回前再次呼叫 Take,伺服器會關閉螢幕截圖連線,並顯示 ZX_ERR_SHOULD_WAIT 墓誌銘。
如果擷取因內部錯誤而失敗,伺服器會關閉螢幕截圖連線,並顯示 ZX_ERR_INTERNAL 墓誌銘。
要求
| 名稱 | 類型 |
|---|---|
payload |
ScreenshotTakeRequest
|
回應
| 名稱 | 類型 |
|---|---|
payload |
ScreenshotTakeResponse
|
TakeFile
在 sRGB 色域中,收集指定緩衝區 format 內顯示畫面的目前圖形內容。請注意,sRGB 色域是非線性的,也就是說,使用非完全飽和色彩進行像素相等檢查的單元測試,應轉換為線性色域。
TODO(https://fxbug.dev/42065844):在 fuchsia.dev 說明文件上線後,提供相關連結。
系統會立即擷取螢幕截圖,並填入最近一次 VSYNC 的螢幕內容。
如果用戶端在第一個 TakeFile 呼叫傳回前再次呼叫 TakeFile,伺服器會關閉螢幕截圖連線,並顯示 ZX_ERR_SHOULD_WAIT 墓誌銘。
如果擷取因內部錯誤而失敗,伺服器會關閉螢幕截圖連線,並顯示 ZX_ERR_INTERNAL 墓誌銘。
如果用戶端位於主機上,且不支援 VMO (例如 ffx 工具),則應使用這個呼叫。
要求
| 名稱 | 類型 |
|---|---|
payload |
ScreenshotTakeFileRequest
|
回應
| 名稱 | 類型 |
|---|---|
payload |
ScreenshotTakeFileResponse
|
TrustedFlatland
定義於 fuchsia.ui.composition/trusted_flatland_factory.fidl
適用於需要特殊功能的受信任 Flatland 工作階段的特殊權限通訊協定。
這項通訊協定會組合成 [Flatland] 通訊協定。只有透過 [TrustedFlatlandFactory] 建立 Flatland 工作階段,才能使用這個通訊協定中的方法。
ReleaseImageImmediately
立即釋出圖片,不等待下一個顯示。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ContentId
|
ReleaseImageImmediately2
立即釋出圖片,不必等待下一個顯示。這是可信任的記憶體清除路徑。
系統會強制解除映像檔與目前參照該映像檔的所有層之間的繫結。在下次 SetLayerImage() 之前,這些圖層的行為就像從未設定圖片一樣 (圖層不可見,但會保留圖片屬性)。
對於遭淘汰 Image 的繫結,任何待處理的釋放柵欄都會在最早的安全點發出信號。
只有在啟用 Flatland2 且工作階段可信任時,才能使用這個方法。
要求
| 名稱 | 類型 |
|---|---|
image_id |
ImageId
|
TrustedFlatlandFactory
定義於 fuchsia.ui.composition/trusted_flatland_factory.fidl
特殊權限工廠,用於建立具有特殊設定的 Flatland 工作階段。
這個通訊協定適用於受信任的用戶端,這些用戶端需要精細控管 Flatland 的行為,以執行效能關鍵應用程式。不能用於一般用途。如果濫用這個 API,可能會對系統效能和穩定性造成負面影響。
CreateFlatland
使用指定設定建立新的 Flatland 工作階段。
錯誤
如果作業失敗,則會傳回 [TrustedFlatlandFactoryError] 錯誤。
要求
| 名稱 | 類型 |
|---|---|
server_end |
server_end:Flatland
|
config |
TrustedFlatlandConfig
|
回應
| 名稱 | 類型 |
|---|---|
payload |
TrustedFlatlandFactory_CreateFlatland_Result
|
STRUCTS
Allocator_RegisterBufferCollection_Response
定義於 fuchsia.ui.composition/allocator.fidl
<EMPTY>
BufferCollectionExportToken 資源
定義於 fuchsia.ui.composition/allocator.fidl
事件配對的類型包裝函式,代表緩衝區集合的登錄端點。
| 欄位 | 類型 | 說明 | 預設 |
|---|---|---|---|
value |
handle<eventpair>
|
無預設值 |
BufferCollectionImportToken 資源
定義於 fuchsia.ui.composition/allocator.fidl
事件配對的類型包裝函式,代表緩衝區集合的圖片匯入端點。
| 欄位 | 類型 | 說明 | 預設 |
|---|---|---|---|
value |
handle<eventpair>
|
無預設值 |
ColorRgba
定義於 fuchsia.ui.composition/flatland.fidl
代表具有 Alpha 管道的顏色。值為 unorm (即有效範圍為 [0,1]),且位於線性色域中。不會經過伽瑪校正或預乘。
| 欄位 | 類型 | 說明 | 預設 |
|---|---|---|---|
red |
float32
|
無預設值 | |
green |
float32
|
無預設值 | |
blue |
float32
|
無預設值 | |
alpha |
float32
|
無預設值 |
ContentId
定義於 fuchsia.ui.composition/flatland.fidl
使用者定義的特定內容 ID。詳情請參閱內容建立函式 (例如 CreateViewport、CreateImage)。
| 欄位 | 類型 | 說明 | 預設 |
|---|---|---|---|
value |
uint64
|
無預設值 |
FlatlandFactory_CreateFlatland_Response
定義於 fuchsia.ui.composition/flatland_factory.fidl
<EMPTY>
HitRegion
定義於 fuchsia.ui.composition/flatland.fidl
檢視畫面的互動區域,位於特定轉換的座標空間中。
| 欄位 | 類型 | 說明 | 預設 |
|---|---|---|---|
region |
fuchsia.math/RectF
|
這個點擊區域的位置和大小,位於擁有這個點擊區域的轉換座標空間中。 |
無預設值 |
hit_test |
HitTestInteraction
|
為這個點擊區域指定的互動行為。如要指定「完全不互動」,請從所屬轉換中移除這個命中區域。 |
無預設值 |
ImageId
定義於 fuchsia.ui.composition/flatland2.fidl
使用者定義的 ID,用於識別以 Flatland.CreateImage2 建立的特定圖片。
ImageId 不得為零;LayerId 中記錄的共用 ID 規則也適用。
| 欄位 | 類型 | 說明 | 預設 |
|---|---|---|---|
value |
uint64
|
無預設值 |
LayerId
定義於 fuchsia.ui.composition/flatland2.fidl
零 ID:零絕非任何類型的有效 ID,每個 Create* 方法都會拒絕。與傳統 API 不同 (例如 Flatland.SetContent 接受 ID 0 來清除轉換內容),Flatland2 絕不會使用零 ID 來表示清除;如果可以清除,則會省略選用欄位 (請參閱 Flatland.SetTransformContent)。
使用者定義的特定圖層 ID。詳情請參閱 Flatland.CreateLayer 和 Flatland.ReleaseLayer。
| 欄位 | 類型 | 說明 | 預設 |
|---|---|---|---|
value |
uint64
|
無預設值 |
LayerStackId
定義於 fuchsia.ui.composition/flatland2.fidl
使用者定義的 ID,用於識別以 Flatland.CreateLayerStack 建立的特定圖層堆疊。
LayerStackId 不得為零;LayerId 中記錄的共用 ID 規則也適用。
| 欄位 | 類型 | 說明 | 預設 |
|---|---|---|---|
value |
uint64
|
無預設值 |
ScreenCapture_Configure_Response
定義於 fuchsia.ui.composition/screen_capture.fidl
<EMPTY>
ScreenCapture_ReleaseFrame_Response
定義於 fuchsia.ui.composition/screen_capture.fidl
<EMPTY>
TransformId
定義於 fuchsia.ui.composition/flatland.fidl
特定轉換的使用者定義 ID。詳情請參閱 CreateTransform 和 ReleaseTransform。
| 欄位 | 類型 | 說明 | 預設 |
|---|---|---|---|
value |
uint64
|
無預設值 |
TrustedFlatlandFactory_CreateFlatland_Response
定義於 fuchsia.ui.composition/trusted_flatland_factory.fidl
<EMPTY>
ViewportId
定義於 fuchsia.ui.composition/flatland2.fidl
使用者定義的 ID,用於透過 Flatland.CreateViewport2 建立的特定可視區域。
ViewportId 不得為零;LayerId 中記錄的共用 ID 規則也適用。
| 欄位 | 類型 | 說明 | 預設 |
|---|---|---|---|
value |
uint64
|
無預設值 |
ENUMS
BlendMode strict
類型:uint32
定義於 fuchsia.ui.composition/flatland.fidl
決定如何將圖片合成到其他圖片上時,可選擇的一組混合函式。
| 名稱 | 值 | 說明 |
|---|---|---|
SRC |
1 |
表示來源像素會取代目的地像素。換句話說,無論設定的 Alpha 值為何,來源像素都會視為不透明。 |
SRC_OVER |
2 |
來源像素會繪製在目的地像素上方。最終顯示的像素顏色計算方式如下:C_src + (1.0 - alpha_src) * C_dst)。 |
BlendMode2 彈性
類型:uint32
定義於 fuchsia.ui.composition/flatland.fidl
決定如何將圖片合成到其他圖片上時,可選擇的一組混合函式。
| 名稱 | 值 | 說明 |
|---|---|---|
取代 |
1 |
表示來源像素會取代目的地像素:來源像素值 (包括 Alpha) 會依原樣寫入輸出,不會與目的地混合。部分或零 Alpha 的來源像素會以該 Alpha 完整地壓印到輸出中;它不會被視為不透明。(這說明瞭混合函式本身;圖層的 |
PREMULTIPLIED_ALPHA |
2 |
來源像素會繪製在目的地像素上方。最終顯示的像素顏色計算方式如下:C_src + (1.0 - alpha_src) * C_dst。 |
STRAIGHT_ALPHA |
3 |
來源像素會繪製在目的地像素上方。最終顯示的像素顏色計算方式如下:alpha_src * C_src + (1.0 - alpha_src) * C_dst。 |
ChildViewStatus strict
類型:uint32
定義於 fuchsia.ui.composition/flatland.fidl
| 名稱 | 值 | 說明 |
|---|---|---|
CONTENT_HAS_PRESENTED |
1 |
基礎 Flatland 工作階段已連結其檢視畫面 (稱為 Present),且已達到 Present 呼叫的擷取柵欄,表示已有部分內容可供顯示,而「不」表示子項內容已實際顯示在畫面上 (常見用途是父項等待子項內容準備就緒,再將子項附加至全域場景圖)。 |
CompositionMode strict
類型:uint32
定義於 fuchsia.ui.composition/flatland2.fidl
選取圖層合成內容:圖片、純色或不合成任何內容。
INVISIBLE 是新建立的狀態。INVISIBLE 圖層會保留在參照它的任何 LayerStack 中,但不會對影格造成任何影響。由於圖層屬性具有黏性 (請參閱 LayerProperties),因此通過 INVISIBLE 並返回時不會遺失任何內容。
| 名稱 | 值 | 說明 |
|---|---|---|
INVISIBLE |
1 |
|
圖片 |
2 |
|
SOLID_COLOR |
3 |
FlatlandError strict
類型:uint32
定義於 fuchsia.ui.composition/flatland.fidl
OnError 中傳回的錯誤代碼組合。任何錯誤都會導致 Flatland 管道關閉。
| 名稱 | 值 | 說明 |
|---|---|---|
BAD_OPERATION |
1 |
表示函式呼叫中使用的參數無效。 |
NO_PRESENTS_REMAINING |
2 |
表示 |
BAD_HANGING_GET |
3 |
表示用戶端已覆寫傳回通訊協定中的懸置 GET。 |
FlatlandFactoryError 彈性
類型:uint32
定義於 fuchsia.ui.composition/flatland_factory.fidl
使用 fuchsia.ui.composition/FlatlandFactory.CreateFlatland 時可能發生的錯誤。
| 名稱 | 值 | 說明 |
|---|---|---|
INVALID_ARGS |
1 |
用戶端提供的設定無效,因此無法建立 Flatland 工作階段。 |
內部 |
2 |
伺服器因不明原因無法建立 Flatland 工作階段,這並非用戶端的問題。 |
HitTestInteraction 彈性
類型:uint8
定義於 fuchsia.ui.composition/flatland.fidl
點擊區域預期的點擊測試互動類型。
| 名稱 | 值 | 說明 |
|---|---|---|
預設 |
0 |
預設行為是讓點擊區域與一般點擊測試和無障礙點擊測試互動。 |
SEMANTICALLY_INVISIBLE |
1 |
在某些用途中,點擊區域必須與一般點擊測試互動,但不能與無障礙功能點擊測試互動。這裡的「語意」是指無障礙功能的語意樹狀結構資料,用於描述 View 中的 UI 元素。 |
ImageFlip strict
類型:uint32
定義於 fuchsia.ui.composition/flatland.fidl
決定圖片紋理顯示方式時,可選擇的一組圖片翻轉函式。
| 名稱 | 值 | 說明 |
|---|---|---|
無 |
0 |
|
LEFT_RIGHT |
1 |
假設 V 是反射的垂直軸,位置在 width/2。然後,每個像素的 x 座標都會反映在 V 上。y 座標保持不變。例如: |1234| |4321| |abcd| 會變成 |dcba| |
UP_DOWN |
2 |
假設 H 是反射的水平軸,位於 height/2。接著,每個像素的 y 座標都會在 H 上反映。x 座標保持不變。例如: |1234| |abcd| |abcd| 會變成 |1234| |
方向嚴格
類型:uint32
定義於 fuchsia.ui.composition/flatland.fidl
在 Flatland 中,+X 軸位於右側,+Y 軸則位於下方。沒有 Z 軸的概念。由於沒有 Z 軸,因此旋轉時沒有「手性」(右或左) 的數學概念。因此,我們定義逆時針旋轉的方式,就像在螢幕上顯示擬真時鐘,從觀察者的角度來看,時鐘的指針會逆時針移動。
| 名稱 | 值 | 說明 |
|---|---|---|
CCW_0_DEGREES |
1 |
|
CCW_90_DEGREES |
2 |
|
CCW_180_DEGREES |
3 |
|
CCW_270_DEGREES |
4 |
ParentViewportStatus strict
類型:uint32
定義於 fuchsia.ui.composition/flatland.fidl
當 ParentViewportWatcher 主動附加至輸出螢幕 (直接或透過父項可視區域鏈結) 或未附加時,系統會通知 ParentViewportWatcher。在連接到螢幕之前,某些資訊 (例如像素比例) 可能無法使用。
| 名稱 | 值 | 說明 |
|---|---|---|
CONNECTED_TO_DISPLAY |
1 |
|
DISCONNECTED_FROM_DISPLAY |
2 |
RegisterBufferCollectionError strict
類型:uint32
定義於 fuchsia.ui.composition/allocator.fidl
Allocator::RegisterBufferCollection() 傳回的一組錯誤代碼。
| 名稱 | 值 | 說明 |
|---|---|---|
BAD_OPERATION |
1 |
RegisterBufferCollectionUsage strict
類型:uint32
定義於 fuchsia.ui.composition/allocator.fidl
已註冊緩衝區集合的可能用途。
| 名稱 | 值 | 說明 |
|---|---|---|
預設 |
0 |
DEFAULT 表示指定的緩衝區集合將用於 Flatland 和 gfx 圖片建立。 |
SCREENSHOT |
1 |
SCREENSHOT 表示指定的緩衝區集合將用於螢幕截圖。 |
輪播:嚴格
類型:uint32
定義於 fuchsia.ui.composition/screen_capture.fidl
要套用至圖片的旋轉角度。
如果根據 display_info 設定檔,某個螢幕旋轉了 270 度,則套用相同且相反的旋轉角度 CW_270_DEGREES,應該會取消螢幕旋轉,進而正確轉譯螢幕截圖。
用戶端應根據最終要使用的尺寸 (即旋轉後) 分配圖片。這些值與 display_info 設定檔中的 width 和 height 值相同。
| 名稱 | 值 | 說明 |
|---|---|---|
CW_0_DEGREES |
0 |
|
CW_90_DEGREES |
1 |
|
CW_180_DEGREES |
2 |
|
CW_270_DEGREES |
3 |
ScreenCaptureError 彈性
類型:uint32
定義於 fuchsia.ui.composition/screen_capture.fidl
ScreenCapture 通訊協定可能發生的錯誤。
| 名稱 | 值 | 說明 |
|---|---|---|
MISSING_ARGS |
1 |
表格引數缺少一或多個必要引數。 |
INVALID_ARGS |
2 |
一或多個引數無效。 |
BAD_OPERATION |
3 |
方法呼叫期間發生一般錯誤。 |
BUFFER_FULL |
4 |
如果 BufferCollection 中的所有 VMO 都已算繪,呼叫 GetNextFrame 時會傳回錯誤。必須先呼叫 ReleaseFrame,才能成功呼叫 GetNextFrame。 |
ScreenshotFormat flexible
類型:uint8
定義於 fuchsia.ui.composition/screenshot.fidl
可要求的螢幕截圖格式。
| 名稱 | 值 | 說明 |
|---|---|---|
BGRA_RAW |
0 |
預設格式,要求使用 32 位元 BGRA 像素的緊密像素資料。 |
RGBA_RAW |
2 |
要求 32 位元 RGBA 像素的緊密像素資料。 |
PNG |
1 |
要求壓縮成 PNG 格式的緊密像素資料。 |
TrustedFlatlandFactoryError flexible
類型:uint32
定義於 fuchsia.ui.composition/trusted_flatland_factory.fidl
使用 [TrustedFlatlandFactory] 時可能發生的錯誤。
| 名稱 | 值 | 說明 |
|---|---|---|
BAD_OPERATION |
1 |
方法呼叫期間發生一般錯誤。如果設定無效,或系統無法建立新的 Flatland 工作階段,就可能發生這種情況。 |
TABLES
FlatlandConfig
定義於 fuchsia.ui.composition/flatland_factory.fidl
用於例項化一般 Flatland 工作階段的設定參數。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
use_flatland2 |
bool
|
如果為 true,則會將工作階段加入 Flatland2 API 介面和圖層資料模型。預設值為 false。 |
FrameInfo 資源
定義於 fuchsia.ui.composition/screen_capture.fidl
GetNextFrame 算繪影格的中繼資料。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
buffer_id |
uint32
|
已算繪所要求影格的 VMO 索引。必填。 |
GetNextFrameArgs 資源
定義於 fuchsia.ui.composition/screen_capture.fidl
傳入 GetNextFrame 呼叫的引數。所有欄位皆為必填。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
event |
handle<event>
|
在要求的影格算繪完成時發出信號的事件。必填。 |
ImageProperties
定義於 fuchsia.ui.composition/flatland.fidl
用戶端定義的圖片屬性。這些屬性會決定 Image 如何使用備份 BufferCollection。詳情請參閱 CreateImage。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
size |
fuchsia.math/SizeU
|
圖片大小 (以像素為單位)。 |
LayerProperties
定義於 fuchsia.ui.composition/flatland2.fidl
與 Layer 相關聯的有狀態屬性。
所有欄位都是固定的:SetLayerProperties 會將提供的表格合併到圖層的儲存屬性中,而儲存的值會在 SetLayerImage 呼叫和合成模式變更時保留。目前撰寫模式未使用的欄位會保留其值,並在重新進入使用這些欄位的模式時再次生效。系統不會隱含清除任何內容;ResetLayer 是唯一會清除儲存屬性的作業。
**提示 (安全性和效能語意)**:提示 (例如 hint_damage_rects 和 hint_visible_rects) 是用戶端提供的選用最佳化詳細資料。
- 可忽略:實作時可忽略這些提示。如果忽略,轉譯仍會完全正確,但可能不是最佳狀態。
- 正確提示:產生相同的視覺效果,但可能會提升效能 (例如允許組合捷徑或部分更新)。
- 提示不正確:由於實作可能會根據錯誤假設進行最佳化,因此可能會導致顯示畫面出現不自然痕跡、過時區域或不正確的像素。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
display_rect |
fuchsia.math/RectU
|
圖層內容在本機座標空間中顯示的矩形。 如果是圖片圖層,視覺屬性會依下列順序套用:
當轉換後的
注意:這個矩形是在 LayerStack 的本機空間 (或 LayerStack 附加的轉換) 中指定。Flatland 場景圖中父項轉換套用的任何縮放,都會進一步影響實體螢幕上的最終大小。 預設值:(0,0,0,0)。必須設定寬度和高度不為零的矩形,圖層才會顯示。 |
2 |
opacity |
float32
|
圖層的不透明度,範圍為 [0..1]。 與從圖層 預設值:1.0 (套用內容本身的 Alpha 值,不進行修改)。 |
3 |
blend_mode |
BlendMode2
|
用於將圖層與下方內容合成的混合模式。 只有在圖層的有效不透明度為 1.0 時,系統才會採用
預設值: |
4 |
color |
ColorRgba
|
無論 預設值:不透明白色 (1.0、1.0、1.0、1.0)。 |
5 |
sample_rect |
fuchsia.math/RectF
|
描述圖片中要取樣的區域,以未正規化的座標表示 (矩形寬度/高度與圖片寬度/高度相符)。 預設值:(0,0,0,0),解讀為整個圖片區域。用戶端可以將這個欄位設為 (0,0,0,0),重設為完整圖片。 必須位於繫結圖片的範圍內。系統會在 fuchsia.ui.composition/Flatland.Present 期間檢查這項設定,且僅適用於 |
6 |
transform |
FlipThenRotate
|
指定圖片轉換。 預設:不轉換 (身分)。 |
7 |
hint_damage_rects |
vector<fuchsia.math/RectU>
|
提示,說明自上一幀以來已變更的來源圖片區域。在來源圖片 (緩衝區) 的座標空間中指定。 預設值:空白向量 (解讀為整個樣本矩形損壞)。 如需提示的一般安全性和效能語意,請參閱 LayerProperties。 |
8 |
hint_visible_rects |
vector<fuchsia.math/RectU>
|
提示,說明圖層在畫面上的可見區域。在圖層的局部座標空間中指定 (與 預設值:空白向量 (解讀為整個 如需提示的一般安全性和效能語意,請參閱 LayerProperties。 |
9 |
composition_mode |
CompositionMode
|
選取上述哪個屬性群組會生效;請參閱 CompositionMode。 預設值: |
LayoutInfo
定義於 fuchsia.ui.composition/flatland.fidl
GetLayout 的傳回類型。這份表格包含大部分必要資訊,可讓用戶端決定如何在 Flatland 工作階段中配置內容。這項資料可能會在建立 View 的指令出現前提供給用戶端,以便用戶端在首次呼叫 Present 前正確配置內容。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
logical_size |
fuchsia.math/SizeU
|
View 的版面配置大小 (以邏輯像素為單位),由父項呼叫 SetViewportProperties 定義。 邏輯大小也會做為 View 的裁剪邊界。系統不會算繪剪輯邊界以外的任何內容。因此,View 的根轉換具有 (0, 0) 到 (logical_size.width, logical_size.height) 的實用座標空間。 當這個值變更時,用戶端應重新調整內容版面配置。 |
3 |
device_pixel_ratio |
fuchsia.math/VecF
|
螢幕實際像素與裝置獨立像素的比率。View 的每個邏輯像素都會由一或多個實體像素顯示在螢幕上,具體取決於這個比例。當這個值變更時,用戶端不一定要重新配置內容,但應重新分配圖片緩衝區,避免取樣不自然。支援 HiDPI 的用戶端應分配大小為 ( |
4 |
inset |
fuchsia.math/Inset
|
檢視畫面邊緣與可見矩形之間的偏移量。用戶端可以假設插邊和檢視區塊邊緣之間的邊界區域遭到遮蔽,並應調整內容版面配置,避免使用這個區域。這個插邊會以檢視畫面的邏輯座標系統描述。支援 HiDPI 的用戶端應將此值縮放 |
OnNextFrameBeginValues
定義於 fuchsia.ui.composition/flatland.fidl
用戶端產生下一個影格所需的欄位,會在 OnNextFrameBegin 中傳回。每個欄位都保證已設定且包含有效資訊。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
additional_present_credits |
uint32
|
用戶端可額外呼叫 Present 的次數,以便進一步呼叫 Present。這是目前抵免額預算的差額,而非目前抵免額的絕對數量。 |
2 |
future_presentation_infos |
FuturePresentationInfos
|
用戶端可能用於精確排程行為的未來顯示和鎖定時間資訊。 |
PresentArgs 資源
定義於 fuchsia.ui.composition/flatland.fidl
傳遞至 Present 的引數。所有引數皆為選用,如果省略引數,Flatland 會使用合理的預設值,如下所示。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
requested_presentation_time |
zx/Time
|
在目前或過去 (例如 0) 使用 如果使用未來的 每個轉譯的影格都有目標顯示時間。這是 Flatland 預計向使用者顯示影格的時間。在算繪影格之前,Flatland 會將所有排入佇列的操作套用至所有可壓縮的 Present 呼叫,其 |
2 |
acquire_fences |
vector<handle<event>>:16
|
Flatland 會等到 Flatland 工作階段的所有 預設 |
3 |
release_fences |
vector<handle<event>>:16
|
當資源不再出現在目前呈現時的本機場景圖中,且可以安全重複使用時,Flatland 會向所有 (在某些情況下,柵欄可能會提早發出信號,但用戶端不必擔心:只有在可以安全重複使用相關聯資源時,柵欄才會發出信號)。 這些柵欄旨在管理共用記憶體資源 (例如 sysmem 緩衝區) 的重複使用。舉例來說,用戶端不應轉譯為目前顯示在螢幕上的圖片,因為這可能會導致畫面撕裂等圖形不自然感。 用戶端必須維護每個柵欄與資源之間的對應關係,當柵欄收到信號時,這些資源就會變成可重複使用。常見的策略是追蹤先前 Present 使用但目前 Present 不再使用的資源。舉例來說,如果目前的 Present 會從場景中移除圖片,用戶端就會在這裡插入柵欄。當柵欄稍後收到信號時,用戶端就會知道可以安全地轉譯至圖片,並在後續的 Present 中將其插入本機場景圖。 如果發生錯誤,Flatland 可能會關閉管道,而不發出這些柵欄信號。用戶端可能會立即釋出共用緩衝區,但不得立即修改這類緩衝區,因為這些緩衝區可能仍會顯示在螢幕上。目前沒有任何可靠的信號,可讓用戶端知道何時能安全地重複使用共用緩衝區。 預設 |
4 |
unsquashable |
bool
|
如果 如果 如果未提供, |
7 |
present_fences |
vector<handle<counter>>:16
|
當顯示硬體回報與此 預設 新增:HEAD
|
8 |
release_counters |
vector<handle<counter>>:16
|
當可以安全地重複使用資源時,Flatland 會向所有 預設 新增:HEAD
|
RegisterBufferCollectionArgs 資源
定義於 fuchsia.ui.composition/allocator.fidl
RegisterBufferCollection 的引數表格。請注意,下方部分欄位為必填。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
export_token |
BufferCollectionExportToken
|
用戶端可以傳送 export_token,向 Allocator 註冊緩衝區集合,以便日後在 fuchsia.ui.composition/Flatland 執行個體或其他 Scenic API (例如 Screenshot) 中使用。 舉例來說,只要傳遞包含 BufferCollectionExportToken 相符對等項目的 BufferCollectionImportToken,就能透過 fuchsia.ui.composition/Flatland.CreateImage 建立圖片資源。 用戶端應等待回應,再使用 這是必填欄位。 |
2 |
buffer_collection_token |
client_end:fuchsia.sysmem/BufferCollectionToken
|
已移除:NEXT 已淘汰:25 已新增:7
|
3 |
usage |
RegisterBufferCollectionUsage
|
用戶端可以註冊緩衝區集合,用於各種用途,每個用途都有各自的限制。 這是選填欄位。如果省略 淘汰這個引數已在 API 第 9 版淘汰,並新增 |usages|。 如果同時設定 已淘汰:9
|
4 |
usages |
RegisterBufferCollectionUsages
|
用戶端可以註冊緩衝區集合,用於各種用途,並在需要多個用途時合併使用。 這是選填欄位。如果省略 |
5 |
buffer_collection_token2 |
client_end:fuchsia.sysmem2/BufferCollectionToken
|
Flatland 會對 只要用戶端持有有效的 BufferCollectionImportToken,向 必須設定 新增:25
|
ScreenCaptureConfig 資源
定義於 fuchsia.ui.composition/screen_capture.fidl
傳入 Configure 呼叫的引數。請注意,部分欄位為選填。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
import_token |
BufferCollectionImportToken
|
參照向 Allocator 註冊的 BufferCollection 的匯入權杖。必填。 |
2 |
size |
fuchsia.math/SizeU
|
圖片大小 (以像素為單位)。必填。 |
3 |
buffer_count |
uint32
|
BufferCollection 中的緩衝區數量。必填。 |
4 |
rotation |
Rotation
|
要套用至圖片串流的旋轉角度。選用;如未提供,則不會套用任何旋轉。 |
ScreenshotTakeFileRequest 資源
定義於 fuchsia.ui.composition/screenshot.fidl
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
format |
ScreenshotFormat
|
要求的螢幕截圖格式。 |
ScreenshotTakeFileResponse 資源
定義於 fuchsia.ui.composition/screenshot.fidl
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
file |
client_end:fuchsia.io/File
|
|fuchsia.io.File| 管道 used to read the generated screenshot file data. 管道的伺服器端會儲存在裝置上,直到偵測到 ZX_CHANNEL_PEER_CLOSED 為止。 基本用法:用戶端收到檔案管道的用戶端端點後,應先讀取完資料,再呼叫 TakeFile,以免記憶體堆積。讀取完畢後,用戶端應在 |fuchsia.io.File| 管道上呼叫 Close,釋出伺服器端分配的記憶體。 |
2 |
size |
fuchsia.math/SizeU
|
螢幕截圖的大小 (以像素為單位)。 |
ScreenshotTakeRequest 資源
定義於 fuchsia.ui.composition/screenshot.fidl
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
format |
ScreenshotFormat
|
要求的螢幕截圖格式。 |
ScreenshotTakeResponse 資源
定義於 fuchsia.ui.composition/screenshot.fidl
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
vmo |
handle<vmo>
|
包含螢幕截圖資料的 CPU 可對應唯讀 VMO。伺服器擁有 VMO,並可重複用於下一個 Take。對應後,保證可以存取 VMO。在某些分配中,VMO::read() 可能無法使用,例如在模擬器上。 基本用法:用戶端收到 VMO 控制代碼後,為確保資料穩定性,應先完成 VMO 讀取作業,再呼叫 Take。讀取完畢後,用戶端應捨棄 VMO 控制代碼。 進階用法:如要編輯資料,或在下次呼叫 Take 後保留資料,用戶端應將資料複製到私人 VMO。 |
2 |
size |
fuchsia.math/SizeU
|
螢幕截圖的大小 (以像素為單位)。 |
TrustedFlatlandConfig 資源
定義於 fuchsia.ui.composition/trusted_flatland_factory.fidl
所有引數均為選用,如未提供,系統會提供預設值。根據預設,產生的 Flatland 行為與連線至 [Flatland] 服務相同,而非透過工廠連線。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
schedule_asap |
bool
|
如果設為 true,且傳遞至 [Flatland.Present] 的 [PresentArgs.requested_presentation_time] 設為 0 或小於或等於最接近的顯示時間,系統會在所有取得柵欄發出信號後,立即排定顯示影格,而不是等待其他用戶端在同一個 vsync 內顯示。這樣一來,呼叫端就能決定何時喚醒,準備影格。 如果 [requested_presentation_time] 的值大於最接近的顯示時間,這個標記就不會生效,喚醒時間將由排程器決定。 如果未提供, |
2 |
pass_acquire_fences |
bool
|
如果為 true,Scenic 應將取得柵欄傳遞至組合硬體的驅動程式,而不是在 CPU 上等待。這可減少 CPU 負擔,進而提升效能。 如果未提供, |
3 |
skips_present_credits |
bool
|
如果設為 true,用戶端就不會使用 Flatland 的內建影格排程機制,並會忽略現有點數,改為依賴自己的流量控制系統。 如果未提供, |
4 |
skips_on_frame_presented |
bool
|
如果為 true,用戶端就不會收到 [Flatland.OnFramePresented] 事件。 如果未提供, |
5 |
use_flatland2_api |
bool
|
如果為 true,用戶端可以使用 fuchsia.ui.composition/Flatland2 通訊協定,該通訊協定會組合成「傳統」fuchsia.ui.composition/Flatland 通訊協定。 注意:啟用 Flatland2 時,部分「傳統」Flatland 方法會停用;詳情請參閱 fuchsia.ui.composition/Flatland2 說明文件。 如果未提供, |
ViewBoundProtocols 資源
定義於 fuchsia.ui.composition/flatland.fidl
繫結至 Flatland ViewCreationToken 的通訊協定端點。這些通訊協定會在 Flatland 工作階段中,對 ViewCreationToken 建立的 View 執行。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
view_ref_focused |
server_end:fuchsia.ui.views/ViewRefFocused
|
瞭解檢視畫面何時獲得焦點。 繫結至伺服器的 ViewRef。view_ref_focused 用戶端不會明確指定 ViewRef,而是由伺服器實作項目使用 View 建立時所用的 ViewRef,回報焦點移入/移出這個 View 的情況。 |
2 |
view_focuser |
server_end:fuchsia.ui.views/Focuser
|
啟用 View,要求將焦點轉移至子項 (目標) View。 繫結至伺服器的 ViewRef。view_focuser 用戶端不會明確指定「requester」ViewRef,只會指定「target」ViewRef。伺服器實作會改用建立檢視畫面時使用的 ViewRef,做為「要求者」ViewRef。 |
3 |
touch_source |
server_end:fuchsia.ui.pointer/TouchSource
|
接收與 View 相關聯的觸控事件。與 |
4 |
mouse_source |
server_end:fuchsia.ui.pointer/MouseSource
|
接收與 View 相關聯的滑鼠事件。與 |
5 |
touch_source_v2 |
server_end:fuchsia.ui.pointer/TouchSourceV2
|
接收與 View 相關聯的觸控事件。與 新增:33
|
6 |
mouse_source_v2 |
server_end:fuchsia.ui.pointer/MouseSourceV2
|
接收與 View 相關聯的滑鼠事件。與 新增:33
|
ViewportProperties
定義於 fuchsia.ui.composition/flatland.fidl
由父項定義的可視區域屬性。這項資料和一組附加的轉換,將用於計算可視區域檢視畫面的 LayoutInfo。ViewportProperties 必須至少設定一次 logical_size。這是決定子項版面配置的初始大小。
| 序數 | 欄位 | 類型 | 說明 |
|---|---|---|---|
1 |
logical_size |
fuchsia.math/SizeU
|
可視區域的大小 (以邏輯像素為單位)。這會直接對應到 LayoutInfo 中的 logical_size 欄位。有效的 logical_size 必須包含正 X 和 Y 元件。 |
2 |
inset |
fuchsia.math/Inset
|
可視區域邊緣與可見矩形之間的偏移量。這會直接對應至 LayoutInfo 中的 |
UNIONS
Allocator_RegisterBufferCollection_Result strict
定義於 fuchsia.ui.composition/allocator.fidl
| 序數 | Variant | 類型 | 說明 |
|---|---|---|---|
1 |
response |
Allocator_RegisterBufferCollection_Response
|
|
2 |
err |
RegisterBufferCollectionError
|
FlatlandFactory_CreateFlatland_Result strict
定義於 fuchsia.ui.composition/flatland_factory.fidl
| 序數 | Variant | 類型 | 說明 |
|---|---|---|---|
1 |
response |
FlatlandFactory_CreateFlatland_Response
|
|
2 |
err |
FlatlandFactoryError
|
ScreenCapture_Configure_Result strict
定義於 fuchsia.ui.composition/screen_capture.fidl
| 序數 | Variant | 類型 | 說明 |
|---|---|---|---|
1 |
response |
ScreenCapture_Configure_Response
|
|
2 |
err |
ScreenCaptureError
|
ScreenCapture_GetNextFrame_Result strict resource
定義於 fuchsia.ui.composition/screen_capture.fidl
| 序數 | Variant | 類型 | 說明 |
|---|---|---|---|
1 |
response |
FrameInfo
|
|
2 |
err |
ScreenCaptureError
|
ScreenCapture_ReleaseFrame_Result strict
定義於 fuchsia.ui.composition/screen_capture.fidl
| 序數 | Variant | 類型 | 說明 |
|---|---|---|---|
1 |
response |
ScreenCapture_ReleaseFrame_Response
|
|
2 |
err |
ScreenCaptureError
|
嚴格 SignalFence 資源
定義於 fuchsia.ui.composition/flatland2.fidl
當某些條件成立時,Scenic 會發出信號的柵欄。詳情請參閱圍欄所在的方法。
| 序數 | Variant | 類型 | 說明 |
|---|---|---|---|
1 |
basic |
handle<handle>
|
基本控制代碼 (例如 EVENT 或 EVENTPAIR)。 |
2 |
timestamp |
handle<counter>
|
Scenic 發出柵欄信號前,會將對應事件的時間戳記寫入計數器。 |
TransformContent strict
定義於 fuchsia.ui.composition/flatland2.fidl
啟用 Flatland2 時,可附加至轉換的內容。
這個聯集定義了可使用 Flatland.SetTransformContent 附加至轉換的內容類型。
| 序數 | Variant | 類型 | 說明 |
|---|---|---|---|
1 |
layer_stack |
LayerStackId
|
|
2 |
viewport |
ViewportId
|
TrustedFlatlandFactory_CreateFlatland_Result strict
定義於 fuchsia.ui.composition/trusted_flatland_factory.fidl
| 序數 | Variant | 類型 | 說明 |
|---|---|---|---|
1 |
response |
TrustedFlatlandFactory_CreateFlatland_Response
|
|
2 |
err |
TrustedFlatlandFactoryError
|
嚴格 WaitFence 資源
定義於 fuchsia.ui.composition/flatland2.fidl
當相關聯的資源可供 Scenic 使用時,系統會發出信號。如需特定情境的使用資訊,請參閱圍欄所在的方法。
| 序數 | Variant | 類型 | 說明 |
|---|---|---|---|
1 |
basic |
handle<handle>
|
基本控制代碼 (例如 EVENT 或 EVENTPAIR)。 |
2 |
timestamp |
handle<counter>
|
發出柵欄信號時,系統會將對應事件的時間戳記寫入計數器。 |
BITS
FlipThenRotate strict
類型:uint8
定義於 fuchsia.ui.composition/flatland2.fidl
支援所有翻轉和旋轉排列組合的位元組。系統會先執行翻轉 (如有),再執行旋轉 (如有)。
| 名稱 | 值 | 說明 |
|---|---|---|
FLIP_H |
1 | 水平翻轉圖片 (沿 Y 軸)。 |
FLIP_V |
2 | 垂直翻轉圖片 (沿 X 軸)。 |
ROTATE_90 |
4 | 將圖片順時針旋轉 90 度。 |
RegisterBufferCollectionUsages 彈性
類型:uint16
定義於 fuchsia.ui.composition/allocator.fidl
已註冊緩衝區集合的可能用途。可搭配使用多種方式。
| 名稱 | 值 | 說明 |
|---|---|---|
預設 |
1 | 指定的緩衝區集合可用於 Flatland 和 GFX 圖片建立。 |
SCREENSHOT |
2 | 指定的緩衝區集合可用於螢幕截圖。 |
常數
| 名稱 | 值 | 類型 | 說明 |
|---|---|---|---|
| MAX_ACQUIRE_RELEASE_FENCE_COUNT |
16
|
int32 |
|
| MAX_CHILD_TRANSFORMS |
64
|
int32 |
最多 64 個子轉換,足以滿足這些 API 的預期用途。呼叫端可使用 AddChild 超出這項限制。 |
| MAX_HIT_REGION_COUNT |
64
|
int32 |
最多 64 個命中區域,足以滿足這些 API 的預期用途。 |
| MAX_PRESENT_ARGS_FENCE_COUNT |
16
|
int32 |
|
| MAX_STACK_LAYERS |
32
|
int32 |
每個堆疊最多 32 層,足以滿足這些 API 的預期用量。 新增:HEAD
|
別名
| 名稱 | 值 | 說明 |
|---|---|---|
| FuturePresentationInfos |
vector[8] |
使用者定義的未來簡報資訊 ID。目前使用這些 API 時,最多 8 個未來簡報計數就足夠。 |