fuchsia.ui.composition

RegisterBufferCollection

BufferCollection 是由 Sysmem 建立並由多位參與者共用的 VMO，其中一個是 Flatland Renderer。有些內容 (例如圖片) 會使用 BufferCollection 做為其幕後記憶體。

如要瞭解每個引數，請參閱 RegisterBufferCollectionArgs。

要求

名稱	類型
`args`	`RegisterBufferCollectionArgs`

回應

名稱	類型
`payload`	`Allocator_RegisterBufferCollection_Result`

ChildViewWatcher

提供特定子項 View 相關資訊的通訊協定，該檢視區塊會附加在上層用戶端擁有的可視區域；這個通訊協定的連線則包含在 CreateViewport 中。由於 Flatland 執行個體包含任意數量的可視區域，每個可視區域不一定可附加至轉換，因此用戶端可以維持相同數量的 ChildViewWatcher 執行個體連線。

只要有對應的子項 View，每個 ChildViewWatcher 例項都會保持連線；如果子項的 ViewCreationToken 遭到捨棄，而未使用建立 View，連結也會關閉。

GetStatus

等待接收 View 狀態的掛斷。這會向父項提供資訊，例如子項是否透過這個 View 成功呈現內容。

只有在 ChildViewStatus 與先前傳回的 ChildViewStatus 不同時，才會觸發此懸掛項目。這種情況會立即發生，即使可視區域的建立者在呼叫 CreateViewport() 後尚未呼叫 Present() 為止。這可讓父項在父項修改其本機場景圖來整合子項內容之前，知道子項有可顯示的內容。

先前的通話仍在等待期間，無法呼叫 GetStatus。這樣做會同時導致這個管道和 Flatland 管道，委請 ChildViewWatcher 關閉。

要求

<EMPTY>

回應

名稱	類型
`status`	`ChildViewStatus`

GetViewRef

停留以接收子項 View 的 ViewRef。只有當檢視參照與先前傳回的 View 參照不同時，才會觸發這個屬性。注意：目前檢視參照不會變更，但在 API 變更為允許重新連結檢視畫面時，這項變更會改變。

只有在 View 納入 View 樹狀結構時，系統才會傳回 ViewRef，也就是說，如果有祖系鏈結，會一直向上回到場景圖表的根層級 (即顯示畫面)。

先前的通話仍在等待期間，無法呼叫 GetViewRef。這樣做會同時導致這個管道和 Flatland 管道，委請 ChildViewWatcher 關閉。

如果使用 CreateView 建立 View，GetViewRef 呼叫會停止運作，但如果 View 是使用 CreateView2 建立，就會傳回 View。這是因為 CreateView 不會為該檢視畫面建立 ViewRef。

要求

<EMPTY>

回應

名稱	類型
`view_ref`	`fuchsia.ui.views/ViewRef`

平地

每個 Flatland 例項都包含一個圖表，這個圖形是由一組物件所組成，以及這些物件之間的關係。用戶端可以指定這些物件的子集 (具體來說，就是從根轉換開始，以內容形式呈現給某種輸出 (通常是顯示) 的有向非循環圖)。

平地圖分為階層和分佈兩種。來自不同 Flatland 執行個體的圖形可連結在一起，以允許使用多個程序編寫特定輸出的內容。

這個通訊協定中的所有函式都是前饋層。這些作業在呼叫 Present 後才會完整執行。

AddChild

將子項 Transform 新增至父項轉換。新的子項 Transform 以及其本身或其子項的任何「內容」，以及先前新增的所有子項，都會顯示在父項的「Content」上方。

要求

名稱	類型
`parent_transform_id`	`TransformId`
`child_transform_id`	`TransformId`

清除

這個函式會重設這個介面上的所有狀態。這包括刪除所有現有的 View 和 Viewport，而不會將相關聯的權杖傳回呼叫端。

要求

<EMPTY>

CreateFilledRect

建立純色矩形。根據預設，填滿矩形並未定義顏色或大小。您必須先呼叫 |SetSolidFill| 指定顏色和尺寸，才能使用已填滿的矩形進行轉譯。不這麼做會導致

要求

名稱	類型
`rect_id`	`ContentId`

CreateImage

映像檔是緩衝區集合中特定 VMO 支援的點陣圖。

建立圖片時，需要向配置器註冊已分配的 BufferCollection。除非指定 BufferCollection 的所有用戶端都設定其限制，否則這個函式將會失敗。

映像檔必須參照有效的 VMO 索引，且 ImageProperties 須位於幕後緩衝區集合指定的限制範圍內 (即寬度和高度在有效範圍內等等)。

0 並非有效的映像檔 ID。所有其他值都有效，前提是這些值未用於其他內容片段 (詳情請參閱 ReleaseImage)。

要求

名稱	類型
`image_id`	`ContentId`
`import_token`	`BufferCollectionImportToken`
`vmo_index`	`uint32`
`properties`	`ImageProperties`

CreateTransform

建立新的 Transform 節點。「轉換」是 Flatland 圖表的階層結構。其中包含子項，而且可以參照「內容」。一個 Transform 代表的子圖表及其子圖表都可以轉譯到螢幕上。

只要轉換是未發布或 Root 轉換的子項，即使已釋出，仍會保持有效。

每項轉換作業都能有一段附加內容。常見的內容類型包括點陣圖、非同步圖片串流，以及在其他 Flatland 執行個體中託管的 View 可視區域。

轉換具有屬性，子項轉換會繼承父項的合併屬性。附加至 Transform 的內容也會受到該 Transform 屬性的影響。

算繪轉換的子圖表時，內容會往前轉譯，從根轉換上的「內容」開始，並按照新增子項的順序繼續顯示所有子項轉換。詳情請參閱AddChild。

0 不是有效的轉換 ID。其他所有值都有效，如果這些值尚未使用 (詳情請參閱 ReleaseTransform)。

要求

名稱	類型
`transform_id`	`TransformId`

CreateView

兩個 Flatland 實例可透過父項/子項關係建立連結。父項端點會保存在可視區域，子端點則會保存在 View 中。建立可視區域的父項 Flatland 例項，可以控制子項的 View 與自身 View 整合的方式。

父項/子項連線的生命週期是從管道物件的兩個端點開始：ViewportCreationToken 和 ViewCreationToken。頻外通訊協定會將 ViewportCreationToken 傳送給父項，進而呼叫 CreateViewport，並將 ViewCreationToken 傳送給子項 (呼叫 CreateView)。

只有在這個 Flatland 執行個體中連線至 Root Transform 的節點，才會算繪到父項的可視區域。

第二次呼叫 CreateView 會中斷 Root Transform 與現有父項的可視區域的連線，並附加至新父項的可視區域。也就是說，每個檢視畫面只能有一個父項。

這個函式已排入佇列，表示在呼叫 Present 後，根轉換才會附加至父項可視區域。不過，客戶會透過 ParentViewportWatcher 接收資訊 (例如LayoutInfo)。SetRootTransform這可讓用戶端先等待來自父項的版面配置資訊，再呼叫 Present。

在 ParentViewportWatcher 上如有非法操作，均會導致 ParentViewportWatcher 管道和這個 Flatland 管道一併終止。

生命週期附註ParentViewportWatcher 管道的生命週期會受到對等 ViewportCreationToken 繫結。當 ViewportCreationToken 失敗時，這個 ParentViewportWatcher 管道會遭到刪除。

使用 CreateView 建立的 View 檢視畫面和子圖表不會呈現在 ViewTree 中，因此也無法參與任何與 ViewTree 相關的互動，例如觸控、滑鼠或焦點。「Flatland 通訊協定」無法為使用 CreateView 建立的檢視畫面子圖表提供子資源，系統會知道這些檢視畫面已從 ViewTree 中排除。

要求

名稱	類型
`token`	`fuchsia.ui.views/ViewCreationToken`
`parent_viewport_watcher`	`server_end<ParentViewportWatcher>`

CreateView2

與 CreateView 相同，只是允許與 View 身分 (ViewRef) 和檢視繫結通訊協定建立關聯。

要求

名稱	類型
`token`	`fuchsia.ui.views/ViewCreationToken`
`view_identity`	`fuchsia.ui.views/ViewIdentityOnCreation`
`protocols`	`ViewBoundProtocols`
`parent_viewport_watcher`	`server_end<ParentViewportWatcher>`

CreateViewport

可視區域與 View 的組合結合，代表兩個 Flatland 執行個體之間的連線。可視區域是在上層中建立，而 View 則是在子項中建立。上層可控管子項的 View 與自身 View 整合的方式。

對 ChildViewWatcher 進行的任何非法作業將導致 ChildViewWatcher 管道和這個 Flatland 管道皆遭終止。

「ViewportProperties」必須設定 logical_size。此為初始大小，會驅動子項的版面配置。logical_size 也可當做預設內容大小使用，但後續對 logical_size 所做的變更不會對內容大小產生任何影響。

ViewportProperties 可能未設定插邊欄位。在此情況下，系統會使用預設值 (0, 0, 0, 0)。

logical_size 必須具備正 X 和 Y 元件。

0 不是有效的 ContentId。所有其他值都有效，前提是這些值並未用於其他內容片段 (詳情請參閱 ReleaseViewport)。

生命週期附註ChildViewWatcher 管道的生命週期與對等 ViewCreationToken 繫結。當 ViewCreationToken 失敗時，這個 ChildViewWatcher 管道會遭到刪除。

要求

名稱	類型
`viewport_id`	`ContentId`
`token`	`fuchsia.ui.views/ViewportCreationToken`
`properties`	`ViewportProperties`
`child_view_watcher`	`server_end<ChildViewWatcher>`

OnError

如果在 Present 後發生錯誤，系統會觸發 OnError 事件並提供相關資訊。

FlatlandErrors 將會關閉與用戶端的連線。

回應 error 是用戶端在執行某些無效作業後可能收到的錯誤。

回應

名稱	類型
`error`	`FlatlandError`

OnFramePresented

如果同時呈現一組一或多個 Present 時，因此不再需要該事件。

這個事件代表已排入佇列的指令在 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 會與其他有效欄位一併發出 NO_ERROR。

只有在現有抵免額數量大於零，由伺服器追蹤時，用戶端才能呼叫 Present。伺服器可能會在觸發 OnNextFrameBegin 事件時增加抵免額數量，在收到額外的代表抵免額時通知用戶端。每個 Present 呼叫都會用到一個抵免額，並將伺服器數量減去 1。如果用戶端呼叫 Present 時找不到抵免額，伺服器會傳回 NO_PRESENTS_REMAINING 錯誤。

用戶端應假設在收到任何 OnNextFrameBegin 事件之前，只有一個功勞。

每個 Present 呼叫都會產生一個 OnNextFrameBegin 事件和一個 OnFramePresented 事件，通常按照這個順序排列。

當 Present 用來清除指令的指令出現時，就會觸發 OnFramePresented 事件。這個事件包含含有該影格內容的所有 Present 相關資訊。

如要進一步瞭解哪些引數傳入和這些引數的角色，請參閱上方的 fuchsia.ui.composition/PresentArgs 文件。

要求

名稱	類型
`args`	`PresentArgs`

ReleaseFilledRect

當矩形不再需要轉譯時，自動收集矩形。|rect_id| 必須透過呼叫 |CreateFilledRect| 完成例項化。釋出之後，ID 會立即排除範圍，再次供人使用。

要求

名稱	類型
`rect_id`	`ContentId`

ReleaseImage

一旦系統不再需要轉譯，發布的圖片就會垃圾收集。對圖片而言，這表示圖片不再附加至任何轉換，以及參照該圖片的所有待處理算繪作業。

使用 SetContent(transform_id, 0) 清除對已發布映像檔的參照。

釋出後，ID 會立即超出未來函式呼叫的範圍，並可在建立新映像檔時重複使用。

使用釋出的 ID 呼叫函式會發生錯誤 (除非已重複使用該 ID 建構新的 Image)。

要求

名稱	類型
`image_id`	`ContentId`

ReleaseTransform

一旦系統不再需要轉譯，您就能將已發布的轉換視為垃圾收集。對轉換而言，這表示沒有任何未發布的轉換前往新發布的轉換路徑。

釋出之後，ID 會立即超出未來函式呼叫的範圍，並可在建立新轉換時重複使用。

使用釋出的 ID 呼叫函式會發生錯誤 (除非該 ID 已重複使用以建構新的轉換)。

要求

名稱	類型
`transform_id`	`TransformId`

ReleaseView

要求

<EMPTY>

ReleaseViewport

從場景中釋放可視區域，即使可視區域仍然與轉換相關聯。不同於其他資源，可視區域為系統在下一次 Present 期間收集的垃圾資料，因為已移除的可視區域保證不會提供可轉譯的內容。

使用 SetContent(transform_id, 0) 清除已釋出可視區域的參照。

儘管有傳回類型，此函式仍舊是前饋函式 (例如 CreateView)，並且需要呼叫 Present 時才能執行。執行呈現的作業後，系統會傳回 ViewportCreationToken。

要求

名稱	類型
`viewport_id`	`ContentId`

回應

名稱	類型
`token`	`fuchsia.ui.views/ViewportCreationToken`

RemoveChild

從父項轉換中移除子項 Transform。

要求

名稱	類型
`parent_transform_id`	`TransformId`
`child_transform_id`	`TransformId`

SetClipBoundary

設定以轉換的本機座標空間表示的邊界，限制可轉譯附加至此轉換內容的區域。如果內容區域超過裁剪邊界，系統就不會顯示該邊界以外的區域。這些邊界也適用於此轉換節點的所有子項，包括巢狀 Flatland 執行個體及其節點階層。如果子項轉換嘗試設定的裁剪邊界大於父項的邊界，就會裁剪至父項的裁剪邊界。預設狀態是要取消裁剪的轉換，也就是說其算繪區域不會設有任何邊界。片段寬度/高度必須為正數。負值會導致錯誤。如果將空白方塊傳入 |rect| 參數，系統就會移除裁剪邊界。

要求

名稱	類型
`transform_id`	`TransformId`
`rect`	`fuchsia.math/Rect?`

SetContent

在 Transform 上設定內容片段後，只要根 Transform 可以顯示轉換，就表示內容會顯示在轉譯樹狀結構中。內容會在之前轉譯，因此「後面」是附加至 Transform 子系的任何「內容」。

因為每個 Transform 最多可有單一的「內容」片段，在已有 Content 的轉換轉換上呼叫此函式，將取代該內容。

一個內容可同時在多項轉換上設定，

以內容 ID 為 0 呼叫這個函式，會移除目前轉換中的所有內容。

要求

名稱	類型
`transform_id`	`TransformId`
`content_id`	`ContentId`

SetDebugName

設定目前用戶端的偵錯名稱，讓 Flatland 以前置字串的形式列印記錄，協助用戶端區分其內容。「name」可以是任意字串，但目前的程序名稱 (請參閱 fsl::GetCurrentProcessName()) 是適當的預設值。

要求

名稱	類型
`name`	`string[64]`

SetHitRegions

設定 Transform 的互動區域。根據預設，內容無法互動；命中區域必須放置於使用者，才能在檢視畫面中與內容互動。由於命中地區已在 Flatland 通訊協定中說明，因此 Flatland 執行個體可以同步處理內容和命中區域。

每個命中區域都放在自有轉換的座標空間，且不一定與不同類型的命中測試互動，視其 HitTestInteraction 類型而定。如果有多個命中區域與命中測試相交，下方提供的優先順序規則會決定哪個命中區域已與命中測試互動。只有間接連線至根轉換的轉換，才會與命中測試互動。

呼叫此函式會取代此轉換先前設定的所有值。如要將轉換重設為「無命中測試」，請使用 SetHitRegions 傳送空白向量。

請注意，根轉換會由 Flatland 安裝的預設命中區域。詳情請參閱 SetRootTransform 說明文件。

在轉換中，優先順序規則如果有多個命中地區重疊，命中測試會檢查每個相交命中區域找出可能的互動。因此，在一般命中測試 R 和無障礙功能命中測試 A 中，R 和 A 都會在同一個轉換中交集兩個命中區域 D (DEFAULT) 和 S (SEMANTICALLY_INVISIBLE)，(1) R 會與 D 和 S 互動，且 (2) A 只會與 D 互動。一般而言，在單一轉換中命中區域會導致混淆。

在 View 中，對於特定命中測試，最前方的 Transform 命中區域會優先於落後區域。這會遵循轉換的預期反向「轉譯順序」(如 CreateTransform 中所述)，也就是使用者預期會與顯示在最前方或最前方的內容互動。

在 Flatland 執行個體中，對於特定命中測試，最前方的執行個體最前端 Transform 命中區域的優先順序會高於其落後區域。這遵循預期的反向「算繪順序」，也就是使用者預期會與可見 (也就是最上層) 的檢視畫面互動。舉例來說，如果子項 View 擁有在父項檢視畫面上算繪的內容，則使用者會預期與子項的內容互動。

要求

名稱	類型
`transform_id`	`TransformId`
`regions`	`vector<HitRegion>[64]`

SetImageBlendingFunction

要求

名稱	類型
`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。

新增日期：10 位

要求

名稱	類型
`image_id`	`ContentId`
`flip`	`ImageFlip`

SetImageOpacity

設定要套用至平地圖片的線性空間的透明度。不透明度值必須在 [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`	`ContentId`
`rect`	`fuchsia.math/RectF`

SetInfiniteHitRegion

與 SetHitRegions 相同，但與 transform_id 相關聯的命中區域僅涵蓋無限區域。命中區域會因轉換、資源調度和方向而異。

就像有限命中區域一樣，無限命中區域仍會受到 View 裁剪邊界的限制。

呼叫此函式會取代此轉換先前設定的所有值。如要將轉換重設為「無命中測試」，請使用 SetHitRegions 傳送空白向量。

新增日期：10 位

要求

名稱	類型
`transform_id`	`TransformId`
`hit_test`	`HitTestInteraction`

SetOpacity

設定要套用至轉換及其子系 (包括其他轉換和內容) 的線性空間不透明度。不透明度值必須在 [0.0, 1.0] 的範圍內，其中 0.0 表示完全透明，1.0 表示完全不透明。如果嘗試使用該範圍以外的值呼叫此函式，將會產生錯誤。轉換的不透明度值乘以父項的數值。這個效果與群組不透明度的運作方式不同。使用群組不透明度時，系統會先算繪子項節點，然後再套用父項的不透明度做為後效效果。在這裡，不透明度會個別套用至每個子項。這可能會造成非常不同的效果。

要求

名稱	類型
`transform_id`	`TransformId`
`value`	`float32`

SetOrientation

設定轉換的方向。如需幾何圖形屬性應用程式的順序，請參閱 SetTranslation 說明文件。在平地中，+X 軸位於右側，+Y 軸則向下。沒有 Z 軸的概念。在使用者 POV 中定義 CCW，就如同螢幕上會顯示骨骼時一樣。

要求

名稱	類型
`transform_id`	`TransformId`
`orientation`	`Orientation`

SetRootTransform

設定圖表的根轉換。

由 Root Transform 定義的子圖表及其子項會在連結父項的可視區域顯示為 View (請參閱 CreateView)。這個圖表中所有 Root 轉換的父項都會遭到忽略。

如果 Root Transform 和 Root 轉換的子項已發布，就會保持運作 (詳情請參閱 ReleaseTransform)。

只有一個根由於 0 不是有效的轉換 ID (請參閱 CreateTransform)，呼叫 SetRootTransform(0) 會清除目前的根層級，並刪除所有未由新根層級參照的先前發布物件。

請注意，每個檢視畫面都有與邏輯大小相等的裁剪界線。該裁剪範圍以外的所有區域都不會顯示。因此，Root Transform 有實用的座標空間，也就是 (0, 0) 到 (logical_size.width, logical_size.height)，其中 (0, 0) 位於左上方。

設定根轉換會在根轉換上安裝全螢幕命中區域。如果用戶端不想讓使用者與根轉換的內容互動，則可移除這個命中區域。如要進一步瞭解命中區域，請參閱 SetHitRegions 說明文件。

預設命中區域規則

預設命中區域遵循下列規則：

呼叫 SetRootTransform(T) 時，T 會接收到最大命中區域，並涵蓋整個檢視畫面。
如果在 T 之前或之後在 T 上呼叫 SetHitRegions，即 SetRootTransform(T) 之前或之後，系統不會啟用預設命中區域，且會使用用戶端指定的命中區域。
如果轉換不再是根轉換，即系統會呼叫 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`	`ContentId`
`color`	`ColorRgba`
`size`	`fuchsia.math/SizeU`

SetTranslation

所有 Transform 物件都支援所有屬性。

幾何圖形屬性是按照下列順序套用：

比例 (相對於父項轉換的座標空間)
方向 (相對於父項轉換的座標空間)
平移 (以父項轉換的座標空間為準，不影響目前轉換套用的縮放比例)。
裁剪 (相對於目前轉換的座標空間)

這些屬性的效果會逐漸累積。這表示轉換在檢視空間中的位置，以及其裁剪邊界，將根據直達根轉換的幾何屬性鏈結計算。

舉例來說，在巢狀階層中，如以下所示：[Root-Transform -> Transform1 -> Transform2 -> CurrentTransform]如果 Transform1 由 [2,0] 轉譯，且 Transform2 由 [0,1] 轉譯，則 CurrentTransform 的檢視空間位置將會是 [2,1]。

在 Transform 上設定翻譯。幾何圖形屬性應用程式的順序請參考上述說明。

要求

名稱	類型
`transform_id`	`TransformId`
`translation`	`fuchsia.math/Vec`

SetViewportProperties

轉換通常足以改變「內容」的呈現方式。然而，可視區域具有不屬於轉換階層的特殊屬性。您可以使用這個函式來設定這些屬性。

要求

名稱	類型
`viewport_id`	`ContentId`
`properties`	`ViewportProperties`

FlatlandDisplay

這個 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 以上。

新增日期：9

要求

名稱	類型
`device_pixel_ratio`	`fuchsia.math/VecF`

ParentViewportWatcher

提供附加至 Flatland 執行個體單一 View 父項可視區域相關資訊的通訊協定。雖然 Flatland 執行個體最多可擁有一個檢視畫面，但在將執行個體的 View 替換為另一個 View (例如透過 CreateView) 時，在短暫的轉換期內可能會有多個 ParentViewportWatcher。在這段期間，系統可能會重複進行某些更新，並傳送至各個 ParentViewportWatcher 連線。

只要對應的上層可視區域存在，就會保持 ParentViewportWatcher 連線；如果父項的 ViewportCreationToken 捨棄，而沒有使用該檢視點建立可視區域，連結也會關閉。

GetLayout

等待接收版面配置資訊的掛斷。提供 ParentViewportWatcher 作業之前，用戶端可能會收到版面配置資訊。這可讓子項在第一次呼叫 Present 時，先設定內容版面配置。在同時存在兩個 ParentViewportWatcher 頻道的情況下，兩個通訊協定執行個體都會收到不同的版面配置資訊。

只有在 LayoutInfo 與先前傳回的 LayoutInfo 不同時，才會觸發此懸浮動作。請注意，由於 LayoutInfo 是資料表，因此只有部分欄位已變更。

先前的通話仍在等待期間，無法呼叫 GetLayout。這麼做會導致這個管道和 Flatland 管道，分派 ParentViewportWatcher 關閉。

要求

<EMPTY>

回應

名稱	類型
`info`	`LayoutInfo`

GetStatus

等待接收上層可視區域狀態的掛鉤。這會為子項提供全域連線資訊。

只有在 ParentViewportStatus 與先前傳回的 ParentViewportStatus 不同時，才會觸發此等待事件。

先前的通話仍在等待期間，無法呼叫 GetStatus。這麼做會導致這個管道和 Flatland 管道，分派 ParentViewportWatcher 關閉。

要求

<EMPTY>

回應

名稱	類型
`status`	`ParentViewportStatus`

ScreenCapture

在 fuchsia.ui.composition/screen_capture.fidl 中定義的

此通訊協定提供低階 ScreenCapture API，可供用戶端使用。螢幕擷取用戶端應熟悉 fuchsia.sysmem/BufferCollection 和 fuchsia.ui.composition/Allocator 通訊協定，因為這些通訊協定是建立 BufferCollections 和圖片 ScreenCapture 所需的通訊協定。

設定

用戶端必須先使用配置器通訊協定註冊 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 傳送後，才能成功完成螢幕截圖。我們不保證在這個函式傳回時完成螢幕截圖。

要求的映像檔會位於用戶端在 VMO 設定的 BufferCollection 中，位於 buffer_id 指定索引。

使用 ScreenCapture 提供串流時，用戶端呼叫 GetNextFrame 的速率將提升畫面更新率。

錯誤：如果 BufferCollection 中的所有緩衝區均在使用中，則未呼叫 setup 或未成功呼叫 MISSING_ARGS。如果缺少必要引數，則傳回 BAD_OPERATION。在這種情況下，必須呼叫 ReleaseFrame 以提供緩衝區，才能成功呼叫這個函式。

要求

名稱	類型
`payload`	`GetNextFrameArgs`

回應

名稱	類型
`payload`	`ScreenCapture_GetNextFrame_Result`

ReleaseFrame

一旦用戶端不再需要圖片，便可在緩衝區的 VMO 索引上呼叫 ReleaseFrame，讓伺服器日後可以重複使用。

要求

名稱	類型
`buffer_id`	`uint32`

回應

名稱	類型
`payload`	`ScreenCapture_ReleaseFrame_Result`

螢幕截圖

收集螢幕目前的圖像內容。

新增時間：12 張

拍攝

以在 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

TODO(https://fxbug.dev/42065844)： fuchsia.dev 說明文件顯示在檔案上。

系統立即擷取螢幕截圖，並填入最新的 VSYNC 顯示內容。

如果用戶端在第一次 TakeFile 呼叫傳回前第二次呼叫 TakeFile，伺服器將會關閉使用 ZX_ERR_SHOULD_WAIT 劇集的「螢幕截圖」連線。

如果因內部錯誤而擷取失敗，伺服器會關閉使用 ZX_ERR_INTERNAL 劇集的「螢幕截圖」連線。

如果用戶端是在主機上，且不支援 VMO，則應使用這項呼叫，就像 ffx 工具一樣。

要求

名稱	類型
`payload`	`ScreenshotTakeFileRequest`

回應

名稱	類型
`payload`	`ScreenshotTakeFileResponse`

結構化

Allocator_RegisterBufferCollection_Response

<EMPTY>

BufferCollectionExportToken 資源

用於事件組合的型別包裝函式，代表緩衝區集合的註冊端點。

欄位	類型	說明	預設
`value`	`handle<eventpair>`		無預設

BufferCollectionImportToken 資源

事件組合的型別包裝函式，代表緩衝區集合的映像檔匯入端點。

欄位	類型	說明	預設
`value`	`handle<eventpair>`		無預設

ColorRgba

代表使用 Alpha 管道的顏色。值為一 (即有效範圍為 [0,1])，位於線性色彩空間中。並未經過 Gamma 修正或預先調節係數。

欄位	類型	預設
`red`	`float32`	無預設
`green`	`float32`	無預設
`blue`	`float32`	無預設
`alpha`	`float32`	無預設

ContentId

特定「內容」的使用者定義 ID。詳情請參閱內容建立函式 (例如 CreateViewport、CreateImage)。

欄位	類型	說明	預設
`value`	`uint64`		無預設

HitRegion

View 的互動式區域，放置在特定 Transform 的座標空間中。

欄位	類型	說明	預設
`region`	`fuchsia.math/RectF`	此命中區域的位置和大小，位於擁有此命中區域轉換的座標空間。	無預設
`hit_test`	`HitTestInteraction`	為這個命中區域指定的互動行為。如要指定「完全沒有互動」，請從擁有的轉換的轉換中移除這個命中區域。	無預設

ScreenCapture_Configure_Response

定義於 fuchsia.ui.composition/screen_capture.fidl

<EMPTY>

ScreenCapture_ReleaseFrame_Response

定義於 fuchsia.ui.composition/screen_capture.fidl

<EMPTY>

TransformId

特定轉換的使用者定義 ID。詳情請參閱 CreateTransform 和 ReleaseTransform。

欄位	類型	說明	預設
`value`	`uint64`		無預設

ENUMS

BlendMode 嚴格

類型：uint32

一組可能的混合函式，在決定圖片的合成方式時可選擇。

名稱	值	說明
SRC	`1`	表示來源像素會取代目的地像素。換句話說，無論設定的 Alpha 值為何，來源像素都會視為不透明。
SRC_OVER	`2`	來源像素會繪製在目標像素上。最終顯示的像素顏色計算方式如下：C_src + (1.0 - alpha_src) * C_dst。

ChildViewStatus 嚴格

類型：uint32

名稱	值	說明
CONTENT_HAS_PRESENTED	`1`	基礎 Flatland 例項已將其命名為「Present」，而所有 Present 呼叫的獲客圍欄，表示它有部分內容可顯示，但子內容並未實際顯示在螢幕上 (常見用途是等待子項內容準備就緒後，再將子項內容附加至全域場景圖)。

FlatlandError strict

類型：uint32

OnError 中傳回的錯誤代碼組合。除了 NO_ERROR 以外的所有資訊，都會關閉 Flatland 管道。

名稱	值	說明
BAD_OPERATION	`1`	表示使用函式呼叫的參數無效。
NO_PRESENTS_REMAINING	`2`	表示 `additional_present_credits` 欄位未正確處理，且用戶端排入佇列的 Present 數量超過允許的上限。
BAD_HANGING_GET	`3`	指出用戶端在傳回的通訊協定中已覆寫等待中的掛斷問題。

HitTestInteraction 彈性

類型：uint8

命中區域預期的命中測試互動類型。

名稱	值	說明
預設	`0`	命中區域的自然預設行為是與一般命中測試和無障礙功能命中測試互動。
SEMANTICALLY_INVISIBLE	`1`	某些用途會要求命中區域能與一般命中測試互動，但不需要與無障礙功能命中測試互動。在本例中，「語意」是指無障礙功能的語意樹狀結構資料，用來說明 View 中的 UI 元素。

ImageFlip 嚴格

類型：uint32

一組在決定圖片紋理顯示方式時可選擇的圖片翻轉函式。

新增日期：10 位

名稱	值	說明
無	`0`
LEFT_RIGHT	`1`	將 V 設為寬度/2 的垂直軸，接著，每個像素的 x 座標會在 V 中反映。y 座標保持不變。例如： \|1234\| \|4321\| \|abcd\| 會變成 \|dcba\|
UP_DOWN	`2`	將 H 設為反射的水平軸，位置為高度/2。接著，每個像素的 y 座標都會反映在 H 之間。x 座標保持不變。例如： \|1234\| \|abcd\| \|abcd\| 會變成 \|1234\|

螢幕方向嚴格

類型：uint32

在平地中，+X 軸位於右側，+Y 軸則向下。沒有 Z 軸的概念。由於缺少 Z 軸，因此旋轉時沒有「手掌」(不論是右還是左) 的數學概念。因此，我們定義逆時針旋轉的方式，與顯示螢幕上的骨架時鐘相同，而那隻手的指針會從觀察器的 POV 移動 CCW 動作。

名稱	值	說明
CCW_0_DEGREES	`1`
CCW_90_DEGREES	`2`
CCW_180_DEGREES	`3`
CCW_270_DEGREES	`4`

ParentViewportStatus 嚴格

類型：uint32

當 ParentViewportWatchers 主動連接輸出螢幕 (直接或透過父項可視區域鏈) 時，系統就會通知他們。除非與螢幕連結，否則部分資訊可能無法使用，例如像素縮放。

名稱	值	說明
CONNECTED_TO_DISPLAY	`1`
DISCONNECTED_FROM_DISPLAY	`2`

RegisterBufferCollectionError 嚴格

類型：uint32

Allocator::RegisterBufferCollection() 傳回的錯誤代碼。

名稱	值	說明
BAD_OPERATION	`1`

RegisterBufferCollectionUsage 嚴格

類型：uint32

已註冊的緩衝區收集功能可能的用途。

名稱值說明

預設

0

DEFAULT 表示指定的緩衝區集合會用於建立 Flatland 和 gfx 映像檔。

詳情請參閱 fuchsia.ui.composition/Flatland.CreateImage。

螢幕截圖

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。

螢幕截圖格式彈性

類型：uint8

可要求的不同螢幕截圖格式。

新增時間：12 張

名稱	值	說明
BGRA_RAW	`0`	預設格式，要求使用 32 位元 BGRA 像素大小進行緊密封裝的像素資料。
PNG	`1`	要求緊密封裝的像素資料 (壓縮為 PNG 格式)。已新增：HEAD

資料表

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

由用戶端定義的 Image 屬性。這些屬性可決定圖片使用備份緩衝區集合的方式。詳情請參閱 CreateImage。

序數	欄位	類型	說明
1	`size`	`fuchsia.math/SizeU`	圖片的像素大小。

LayoutInfo

GetLayout 的傳回類型。下表包含客戶決定如何在 Flatland 執行個體中配置內容版面配置的大部分必要資訊。系統可能會在顯示建立 View 的指令之前，將這項資料提供給用戶端，因此用戶端可在第一次呼叫 Present 前，先正確安排內容的版面配置。

序數欄位類型說明

1

logical_size

fuchsia.math/SizeU

檢視畫面的版面配置大小，以邏輯像素為單位，由父項對 SetViewportProperties 的呼叫所定義。

邏輯大小也會當做檢視畫面的裁剪邊界。裁剪界線外的所有內容都不會算繪。因此，檢視畫面的 Root 轉換有實用的座標空間 (0, 0) 到 (logical_size.width, logical_size.height)。

當這個值發生變化時，用戶端應重新版面配置內容。

3

device_pixel_ratio

fuchsia.math/VecF

螢幕的實體像素與裝置獨立像素的比率。檢視畫面的每個邏輯像素都會以一或多個實體像素在螢幕上顯示，並由這個比例決定。當這個值變更時，用戶端不一定需要重新設定其內容版面配置，但可透過重新配置圖片緩衝區來因應，避免對成果進行取樣。具備 HiDPI 感知的用戶端應分配大小 (logical_size*device_pixel_ratio) 的緩衝區。

新增日期：9

4

inset

fuchsia.math/Inset

檢視畫面邊緣與可見矩形之間的偏移值。用戶端可以假設插邊和檢視畫面邊緣之間的邊界區域已遮蔽，因此應調整內容版面配置來避免這個區域。此插邊可在檢視畫面的邏輯座標系統中說明。以 HiDPI 感知的客戶來說，應在 device_pixel_ratio前進行資源調度。

新增日期：9

OnNextFrameBeginValues

用戶端為產生下一個影格所需的欄位，在 OnNextFrameBegin 中傳回。我們保證每個欄位都能設定，並且包含有效的資訊。

序數	欄位	類型	說明
1	`additional_present_credits`	`uint32`	允許用戶端「再」呼叫「簡報」次數，以便進一步呼叫 Present 時間。此為目前抵免額預算的差異，而非目前抵免額的絕對值。
2	`future_presentation_infos`	`FuturePresentationInfos`	客戶日後會為了準確排程行為而瞄準的簡報和閂鎖時間相關資訊。

PresentArgs 資源

傳遞至 Present 的引數。所有引數皆為選用，如有省略引數，則系統會採用以下指定的合理預設值。

序數	欄位	類型	說明
1	`requested_presentation_time`	`zx/Time`	`requested_presentation_time` 會指定用戶端希望排入佇列的作業何時開始或之後的時間 (以 `CLOCK_MONOTONIC` 時間集表示，以奈秒表示)。 `requested_presentation_time` 的預設值為 0。使用 `requested_presentation_time` (例如 0) 過去或過去的時間，會排定在下一個影格中，為已排入佇列的作業盡快生效，以便做好準備。日後會使用 `requested_presentation_time`，將排入佇列的作業安排在表定時間後或盡可能近乎顯示效果，但不會提早生效。每個轉譯影格都有目標簡報時間。因此 Flatland 的目標是向使用者顯示影格。在轉譯影格之前，Flatland 會將與所有可壓縮呼叫相關聯的所有已佇列作業套用至 Present 時，如果 `requested_presentation_time` 位於影格目標簡報時間或之前。
2	`acquire_fences`	`vector<event>[16]`	Flatland 會等到 Flatland 執行個體的所有 `acquire_fences` 都準備就緒後，才能執行提出的指令。沒有傳送信號給 `acquire_fences` 會封鎖目前的存在，以及下列的項目，即使其 `acquire_fences` 已發出信號也一樣。預設的 `acquire_fences` 值為空白向量。
3	`release_fences`	`vector<event>[16]`	如果資源在適合重複使用於目前 Present 時的本機場景圖中不再顯示，扁平地就會向所有 `release_fences` 發出信號。最近，當本機場景圖 (在這份簡報中指出的檢查項目) 整合至全域場景圖中，且全域場景已顯示於螢幕上，就會發生此情況。 (在某些情況下，系統可能會提早發出圍欄，但用戶端不需要擔心：只有在可以安全重複使用相關資源時，系統才會發出圍欄訊號。這些圍欄是用來管理共用記憶體資源 (例如 sysmem 緩衝區) 的重複使用作業。例如，用戶端並不適合算繪到目前顯示的圖片，因為這可能會產生撕裂等圖形構件。用戶端可自行決定是否要維持每個圍欄與在圍欄收到訊號時可重複使用的資源。常見的策略是追蹤先前 Present 所使用，但目前 Present 不再使用的資源。舉例來說，如果圖片根據目前 Present 時從場景中移除，用戶端會在這裡插入圍欄。等圍欄稍後發出信號時，用戶端會知道可以安全轉譯到圖片，再透過後續的「Present」部分，將內容插入本機場景圖中。如果發生錯誤，Flatland 可能會在不告知這類圍欄的情況下關閉管道。用戶端可以立即釋出共用緩衝區，但這些緩衝區可能仍會顯示在螢幕上，因此不應立即修改。目前，在可以安全重複使用共用緩衝區的情況下，用戶端沒有良好的訊號。預設的 `release_fences` 值為空白向量。
4	`unsquashable`	`bool`	如果 `unsquashable` 為 true，則更新保證至少會有一個 vsync 間隔顯示。如果 `unsquashable` 為 false，則更新可以與之後的更新合併。如果從缺，`unsquashable` 為 false。
5	`server_wait_fences`	`vector<event>[16]`	未使用。原本是要重新命名 `acquire_fences`，但實際上並未連線。已淘汰：HEAD
6	`server_signal_fences`	`vector<event>[16]`	未使用。原本是要重新命名 `release_fences`，但實際上並未連線。已淘汰：HEAD

RegisterBufferCollectionArgs 資源

RegisterBufferCollection 的引數表格。請注意，以下部分欄位為「必要」。

序數	欄位	類型	說明
1	`export_token`	`BufferCollectionExportToken`	用戶端可以傳送 export_token，透過 Allocator 註冊緩衝區集合，以便在 fuchsia.ui.composition/Flatland 執行個體或其他 View API (例如螢幕截圖) 中使用。例如，傳遞含有 BufferCollectionExportToken 相符對等點的 BufferCollectionImportToken，就可以透過 fuchsia.ui.composition/Flatland.CreateImage 建立圖片資源。用戶端應等待回應，才能使用 `import_token`。這是「必填」欄位。
2	`buffer_collection_token`	`fuchsia.sysmem/BufferCollectionToken`	Flatland 會透過在 `buffer_collection_token` 參照的 BufferCollection 上設定限制，參與緩衝區分配。除非用戶端使用 BufferCollection 建立內容，否則不會封鎖分配的緩衝區。只要用戶端持有有效的 BufferCollectionImportToken，即可使用 `export_token` 註冊的緩衝區集合並保持運作。關閉所有 BufferCollectionImportToken 並釋出所有相關聯的映像檔資源後，就會對這些映像檔進行垃圾收集。這是「必填」欄位。
3	`usage`	`RegisterBufferCollectionUsage`	用戶端可針對各種用途註冊緩衝區集合，每個用途都有各自的限制。這是 OPTIONAL 欄位。如果省略 `usage`，系統會將其視為有 DEFAULT 選項。淘汰這個引數在 API 第 9 版中已淘汰，並加上 \|usages\|。如果同時設定 `usages` 和 `usage` 欄位，系統會優先採用 `usages`，並忽略 `usage`。已淘汰：9
4	`usages`	`RegisterBufferCollectionUsages`	用戶端可以註冊緩衝區集合以用於各種用途，也可視需要組合使用情況。這是 OPTIONAL 欄位。如果省略 `usages`，系統會將其視為只有 DEFAULT 選項。新增日期：9

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 資源

序數	欄位	類型	說明
1	`format`	`ScreenshotFormat`	要求螢幕截圖的格式。

ScreenshotTakeFileResponse 資源

序數欄位類型說明

1

file

fuchsia.io/File

|fuchsia.io.File| 管道可用來讀取產生的螢幕截圖檔案資料。管道的伺服器端會儲存在裝置上，直到偵測到 ZX_CHANNEL_PEER_CLOSED 為止。

基本用法：在用戶端收到檔案管道的用戶端端後，為了避免記憶體堆積增加，應在再次呼叫 TakeFile 之前完成資料讀取作業。閱讀完畢後，用戶端應呼叫 |fuchsia.io.File| 管道上的 Close，這樣就能在伺服器端釋出分配的記憶體。

2

size

fuchsia.math/SizeU

螢幕截圖的大小 (以像素為單位)。

ScreenshotTakeRequest 資源

序數	欄位	類型	說明
1	`format`	`ScreenshotFormat`	要求螢幕截圖的格式。

ScreenshotTakeResponse 資源

序數欄位類型說明

1

vmo

handle<vmo>

包含螢幕截圖資料的可對應 CPU 唯讀 VMO。這個伺服器擁有 VMO，可以重複用於下一個 Take。對應後即可確保 VMO 可以存取。在某些配置中，VMO::read() 可能無法使用，亦即在模擬器上。

基本使用：用戶端收到 VMO 控制代碼後，為了確保資料穩定性，應先讀取 VMO 再呼叫 Take。讀取完畢後，用戶端應捨棄 VMO 控制代碼。

進階使用：如要編輯資料，或在下一次「Take」呼叫之後保留資料，用戶端應將資料複製到私人 VMO。

2

size

fuchsia.math/SizeU

螢幕截圖的大小 (以像素為單位)。

ViewBoundProtocols 資源

繫結至 Flatland ViewCreationToken 的通訊協定端點。這些通訊協定會在 Flatland 工作階段中建立的 ViewCreationToken 上運作。

序數	欄位	類型	說明
1	`view_ref_focused`	`server_end<fuchsia.ui.views/ViewRefFocused>`	瞭解當檢視畫面獲得關注的時機。伺服器繫結的 ViewRef。view_ref_focused 用戶端不會明確指定 ViewRef；而伺服器實作則會使用在建立檢視畫面中使用的 ViewRef，回報這個檢視畫面的焦點移動。
2	`view_focuser`	`server_end<fuchsia.ui.views/Focuser>`	啟用檢視畫面，要求將焦點轉移到子項 (目標) 檢視畫面。伺服器繫結的 ViewRef。view_focuser 用戶端不會明確指定「requestor」ViewRef，而只會指定「target」ViewRef。相反地，伺服器實作會使用 View 建立期間使用的 ViewRef 做為「要求者」ViewRef。
3	`touch_source`	`server_end<fuchsia.ui.pointer/TouchSource>`	接收與檢視畫面相關聯的觸控事件。
4	`mouse_source`	`server_end<fuchsia.ui.pointer/MouseSource>`	接收與檢視畫面相關聯的滑鼠事件。

ViewportProperties

父項定義的可視區域屬性。這項資料以及附加的轉換組合，將用來計算可視區域檢視畫面的 LayoutInfo。ViewportProperties 必須設定 logical_size 至少一次。這是驅動子項版面配置的初始大小。

序數	欄位	類型	說明
1	`logical_size`	`fuchsia.math/SizeU`	可視區域的大小 (以邏輯像素為單位)。這會直接對應至 LayoutInfo 中的 logical_size 欄位。有效的 logical_size 必須具備正 X 和 Y 元件。
2	`inset`	`fuchsia.math/Inset`	可視區域的邊緣與可見矩形之間的偏移值。這會直接對應至 LayoutInfo 中的 `inset` 欄位。有效的插邊必須具備所有大於或等於 0 的元件。新增日期：9

聯合國

Allocator_RegisterBufferCollection_Result 嚴格

序數	Variant	類型	說明
1	`response`	`Allocator_RegisterBufferCollection_Response`
2	`err`	`RegisterBufferCollectionError`

ScreenCapture_Configure_Result 嚴格

在 fuchsia.ui.composition/screen_capture.fidl 中定義的

序數	Variant	類型	說明
1	`response`	`ScreenCapture_Configure_Response`
2	`err`	`ScreenCaptureError`

ScreenCapture_GetNextFrame_Result 嚴格 資源

在 fuchsia.ui.composition/screen_capture.fidl 中定義的

序數	Variant	類型	說明
1	`response`	`FrameInfo`
2	`err`	`ScreenCaptureError`

ScreenCapture_ReleaseFrame_Result 嚴格

在 fuchsia.ui.composition/screen_capture.fidl 中定義的

序數	Variant	類型	說明
1	`response`	`ScreenCapture_ReleaseFrame_Response`
2	`err`	`ScreenCaptureError`

帳單

RegisterBufferCollectionUsages 彈性

類型：uint16