Fuchsia.ui.pointerinjector

新增日期：7

通訊協定

裝置

在 fuchsia.ui.pointerinjector/device.fidl 中定義

將指標事件插入目標的管道。相關聯的 |Config| 適用於插入的指標事件。

|Device| 可能會「插入」指標事件至場景的目標，但指標事件的「分派」至該目標檢視區塊樹狀結構中的 UI 用戶端將取決於分派政策和場景拓撲。

插入

將事件插入目標。

批次處理：呼叫端應批次插入具有相同時間戳記的所有事件 (例如多指取樣)。每次插入呼叫可能會有多個這類批次。

流量控制：呼叫端系統一次只能進行最多一項進行中 |Inject| 呼叫：後續的 |Inject| 呼叫必須等待確認傳回。違反規定會使管道遭關閉。

要求

名稱類型
events vector<Event>[128]

回應

<EMPTY>

註冊類型

在 fuchsia.ui.pointerinjector/device.fidl 中定義

一種協調機制，可明確定義指標事件的「插入」 (插入政策、插入內容等)，以便「分派」指標事件給 UI 用戶端 (由 |fuchsia.ui.views.ViewRef| 參照)。

注意！唯有在信任的運算基礎中，才能取得此通訊協定的存取權。(1) 插入者裝置會接待使用者授權。UI 用戶端無法分辨實際使用者和插入器裝置之間的差異。(2) 註冊插入裝置時，系統會自行指定結構定義。可存取機密結構定義的插入裝置會在該範圍內運作。(3) 插入的事件可為任意值。插入裝置可以插入任何希望與用戶端連線的項目。

這個通訊協定會定義插入器 |Device| 的結構定義和目標，將可視區域置於與目標相關的空間中，並將 |Device| 連結至可視區域。這些參數是在 |Config| 中設定。|Device| 可能會在可視區域插入指標事件，但將指標事件分派至目標中的 UI 用戶端，取決於分派政策和場景拓撲。

|Device| 會在結構定義中運作，並且具有兩種用途：(1) 限定範圍。這樣可確認 |Device| 有權在指定的目標中插入指標事件。(2) 座標系統。可提供參照座標系統，以便定義可視區域相對於目標的位置和大小。

保證。|Device| 會導向場景中的指定目標，這類目標會給予部分保證，防止在目標檢視區塊樹狀結構外的 UI 用戶端遭到窺探和乾擾 (即「非目標用戶端」)。非目標用戶端從未將插入的事件傳送給他們：|Device| 能為目標用戶端保留可信度。非目標用戶端絕對不會封鎖插入的事件：在插入時觸及目標，或是分派攻擊目標用戶端：|Device| 能為目標用戶端保留完整性和可用性。不過，|Device| 本身可能會受到目標的祖系檢視畫面中斷 (請參閱不變的連線)。

注意：此通訊協定及其政策「不足」不足以防範 UI 救濟攻擊！機密性、完整性和可用性保證僅適用於非目標用戶端。在目標中，目標用戶端之間仍可能發生 UI 修正攻擊。

連線不固定。|Device| 會在連線至根層級檢視畫面的穩定檢視畫面樹狀結構中運作。如果目標 (或情境和目標) 與 UI 用戶端的檢視畫面樹狀結構取消連結，|Device| 管道就會關閉。如果事件串流仍在執行中，伺服器會在管道關閉後分派最終 CANCEL 事件，然後根據分派政策傳播這個 CANCEL 事件。

註冊

為 |Device| 設定背景資訊 (也就是 |Device| 的目標)，並透過可視區域 (在結構定義中) 將 |Device| 引導至目標。這些參數是在 |Config| 中指定。

如果 |config| 無效 (例如缺少重要資料)，系統會拒絕 |Device| 要求：管道將會關閉。

回傳事件會告知呼叫端：(1) 伺服器已處理呼叫，且 (2) 已連線 |Device|。

要求

名稱類型
config Config
injector server_end<Device>

回應

<EMPTY>

ENUMS

DeviceType strict

類型：uint32

在 fuchsia.ui.pointerinjector/config.fidl 中定義

用於發出指標事件串流的裝置特性。

名稱值說明
1

可透過裝置表面直接接觸操控的裝置。
2

可透過在表面上精準移動而操控的裝置。

DispatchPolicy 嚴格

類型：uint32

在 fuchsia.ui.pointerinjector/config.fidl 中定義

這裡的 UI 用戶端規格，其中可能已透過 |Target| 分派到這些用戶端。|Config| 中指定了其中一個。

「閂鎖」是一個實用概念，其中一或多個用戶端可能會在指派串流擁有權之前，開始接收指標事件串流。指派擁有權後 (例如透過手勢消歧通訊協定)，非擁有的用戶端就會終止其閂鎖，進而停止接收指標事件串流。

  • 用戶端的閂鎖本身不會轉移串流擁有權 (接收整個指標事件串流)；手勢消除或裝置終止可能會提前結束分派給該用戶端的串流。
  • 用戶端可以在對使用者隱藏時隱藏閂鎖 (例如操控使用者看不到的途徑)，其中遮蔽介面由 |Target| 以外的用戶端擁有。相反地，這些遮蔽的用戶端必須位於 |Target| 的檢視畫面樹狀結構中。

名稱值說明
1

單一用戶端閂鎖到指標事件串流，其中：

  • 指標事件串流在可視區域矩形中開始
  • 閂鎖發生在指標事件串流的 ADD 階段，
  • 用戶端就是 |Target| 本身。 擁有權會立即指派給客戶。

注意：這項政策可以保證調度給用戶端的機密性、完整性和可用性，但本身「無法」保障 UI 救濟攻擊的免責事項。
2

多個用戶端可以鎖定指標串流，其中：

  • 指標串流從可視區域矩形開始
  • 對指標事件串流的 ADD 階段執行命中測試，後者會傳回 |Target| 的檢視畫面樹狀結構中最頂層的表面 (按照繪製順序)。
  • 最頂層介面的用戶端閂鎖放在指標資料流上，
  • 在 |Target| 的檢視樹狀結構中，用戶端的祖係也會鎖上指標串流。

如果有多個閂鎖，指標串流會平行分派給每個已閂上的用戶端，直到透過手勢消歧指派擁有權為止。擁有者用戶端會繼續收到指標串流，非擁有者則會收到串流的最終「取消」事件。

注意：如果命中測試未能成功到達 |Target| 的任何子檢視畫面，就沒有任何用戶端可以延遲。 注意：每個用戶端都有自己的可視區域副本，並以自身的座標系統為準。
3

除非滑鼠已固定在特定用戶端，否則 |Target| 檢視樹狀結構中最頂端的命中用戶端會收到懸停事件，

滑鼠按下按鈕後會啟動閂鎖，而在那個閂鎖釋放之前，滑鼠事件會傳送至已閂鎖的用戶端；其他用戶端在閂鎖持續時間內不會接收懸停事件。

注意：如果命中測試失敗後無法命中 |Target| 的任何子檢視畫面，有可能沒有任何用戶端位置。 注意：每個用戶端都有自己的可視區域副本，並以自身的座標系統為準。

事件階段嚴格

類型：uint32

在 fuchsia.ui.pointerinjector/event.fidl 中定義

指標事件串流狀態機器的可能狀態。

一般指標會在此狀態機器上移動： ADD - CHANGE* - REMOVE

名稱值說明
1

裝置已開始追蹤指標。
2

裝置已回報指標狀態更新。
3

裝置已停止追蹤指標。
4

該事件串流已無法使用。

資料表

設定 資源

在 fuchsia.ui.pointerinjector/config.fidl 中定義

插入器 |Device| 的規格。

請填寫所有欄位。

序數欄位類型說明
device_id uint32

問題指標事件串流的指標裝置 ID。
device_type DeviceType

指標裝置的特性。
context Context

插入器 |Device| 的範圍和座標系統。

注意：為避免循環插入情境，|context| 必須是 |target| 的嚴格祖系。
target Target

分派作業嘗試插入已插入事件的區域。

注意：為避免循環插入情境，|target| 必須採用嚴謹的 |context| 限制。
viewport Viewport

已插入事件的初始可視區域。後續對可視區域的修改也可以與插入的事件同步傳送。
dispatch_policy DispatchPolicy

這個規範適用於 |target| 中的 UI 用戶端規格，其中可能已將插入的事件分派給這些用戶端。

舉例來說，如果 |dispatch_policy| 是 |EXCLUSIVE|，則無論其他因素為何，例如 |target| 內部和外部的用戶端遮蔽事件，只有 |target| 可能都會分派事件給它。
scroll_v_range fuchsia.input.report/Axis

裝置核發的垂直捲動值範圍。
scroll_h_range fuchsia.input.report/Axis

裝置核發的水平捲動值範圍。
buttons vector<uint8>[32]

裝置核發的滑鼠按鈕 ID (優先順序)。

滑鼠按鈕的優先順序是由插入程式所做的政策選擇。 這個優先順序順序會透過 fuchsia.ui.pointer.MouseDeviceInfo.buttons 向 UI 用戶端傳達，因此多個 UI 用戶端會一致地分享按鈕優先順序。舉例來說，如要將左側 (0x1) 和右側 (0x2) 實體按鈕與滑鼠主要和次要滑鼠按鈕的傳統角色替換，插入器可以在這個按鈕向量中指定 [0x2, 0x1, ...]。

請注意，保留實體按鈕 ID 也是政策選擇。如果保留，有不同的 UI 用戶端可以區分實際資料 (按下的實體按鈕) 和想要的解釋 (實體按鈕在目前系統中的優先順序)。
relative_motion_range RelativeMotionRange

滑鼠裝置執行的 X 和 Y 動作範圍。

活動

在 fuchsia.ui.pointerinjector/event.fidl 中定義

序數欄位類型說明
timestamp zx/Time

觀察到此事件的時間。

必填。
data Data

事件的資料。

必填。
trace_flow_id uint64

這個 ID 會關聯此事件在元件邊界或抽象層之間的傳送/接收發生情況。

PointerSample

在 fuchsia.ui.pointerinjector/event.fidl 中定義

指標裝置每個取樣資料點的說明。

序數欄位類型說明
pointer_id uint32

核發這個事件的指標 ID。僅適用於特定指標裝置。
phase EventPhase

在指標事件串流的狀態機器中，此事件的狀態。
position_in_viewport Point2

此事件在可視區域的座標系統中的位置。
scroll_v int64

垂直捲動的相對垂直捲動偏移。
scroll_h int64

相對水平捲動位移位移。
pressed_buttons vector<uint8>[32]

目前所按下按鈕的 ID。
relative_motion RelativeMotion

滑鼠的移動方式，與可視區域的座標系統無關。
scroll_v_physical_pixel float64

按實體像素推薦的垂直捲動移位，計算方式為加速器、露點 / 毫米和像素比例等。
scroll_h_physical_pixel float64

按實體像素建議的水平捲動移位，可以採用加速器、露點 / 毫米和像素比例等值進行計算。
is_precision_scroll bool

指出捲動事件是否來自精確度捲動裝置 (HI_RES 滑鼠或觸控板)。用戶端可能需要在無法精密的捲動裝置上播放內插動畫，以便順暢捲動。

可視區域

在 fuchsia.ui.pointerinjector/config.fidl 中定義

將插入事件導向目標的矩形區域。

可視區域與多個獨立座標系統的指標位置相關：結構定義、可視區域和調度用戶端。可視區域基本上是指標位置對應至場景互動部分的方式。

矩陣可用來建立可視區域座標系統與結構定義座標系統的關係。一組範圍定義可視區域座標系統中可視區域的大小。兩者合而是在內容座標系統中，定義可視區域的位置。

可視區域座標系統可透過縮放不變的方式傳遞指標座標，以調度用戶端，讓指標移動能在放大等效果下正確解讀。結構定義會定義可視區域座標系統中可視區域的最小和最大範圍。

  • 可視區域的邊界 (矩形) 與可視區域座標系統對齊；但可在其中任意定位 (「浮點」)，也就是有平移和縮放，但沒有旋轉。
  • 浮動式可讓插入程式選擇如何傳遞座標，例如在 Vulkan NDC 或螢幕像素座標中。
  • 可視區域矩形會定義分派使用的閂鎖區域 (如下所述)。

調度用戶端會在可視區域座標系統中接收指標座標，以及將可視區域座標系統的座標轉換為調度用戶端座標系統的矩陣。

請填寫所有欄位。

TODO(https://fxbug.dev/42162296)：重新命名可視區域，用於 Flatland。

序數欄位類型說明
extents Extents

可視區域在可視區域座標系統中，最小和最大範圍。
viewport_to_context_transform Mat3

轉換矩陣，說明如何將可視區域座標系統對應至內容座標系統。

這項轉換與 |extents| 一同會定義可視區域在內容座標系統中的位置。

這個轉換必須是不可逆的矩陣 (即具有非零確定性)，以保證可視區域座標系統與結構定義座標系統之間出現分界現象。系統拒絕不可逆的矩陣。

聯合國

背景資訊嚴格 資源

在 fuchsia.ui.pointerinjector/config.fidl 中定義

嘗試插入事件的來源區域。結構定義有兩個用途：(1) 限定範圍。這會確認 |Device| 有權在指定的目標中插入指標事件。具體而言，結構定義必須是目標的檢視區塊樹狀結構祖系。(2) 座標系統。可提供參照座標系統，以便定義可視區域相對於目標的位置和大小。

序數Variant類型說明
view fuchsia.ui.views/ViewRef

系統嘗試插入插入事件的景觀檢視畫面。

  • 這個檢視畫面必須連結至場景圖才能插入。
  • 插入的事件僅限於這個檢視畫面及其子檢視畫面。

資料彈性

在 fuchsia.ui.pointerinjector/event.fidl 中定義

透過管道傳送的一組 FIFO 資料。 每項資料可能有不同的核發政策。

序數Variant類型說明
viewport Viewport

可視區域的參數足以讓用戶端正確解讀分派給其的指標事件位置和比例。

  • 每次變更可視區域時都會核發此值。
pointer_sample PointerSample

指標事件串流中每個取樣資料點的說明。

  • 它會在指標事件串流中的每個樣本上發出。

目標嚴格 資源

在 fuchsia.ui.pointerinjector/config.fidl 中定義

系統嘗試分派至已插入事件的區域。您可以在 |Config| 中指定特定分派政策。

序數Variant類型說明
view fuchsia.ui.views/ViewRef

系統嘗試分派插入事件的景觀檢視畫面。

  • 這個檢視畫面必須連結至場景圖，才能進行分派作業。
  • 插入的事件僅限於這個檢視畫面及其子檢視畫面。

業者

名稱值類型說明
MAX_INJECT 128 uint32

別名

名稱值說明
偵測器 array[2]

一對浮點值，代表最小和最大範圍。

  • 值的排列順序為 (最小、最大值)。
Mat3 array[9]

浮點數 3x3 矩陣。

  • 這些值會以資料欄的順序排列。
Point2 array[2]

浮點 2D 點。

  • 值的排列順序為 (x, y)。
RelativeMotion array[2]

滑鼠裝置執行的相對動作。
RelativeMotionRange array[2]

滑鼠裝置相關動態的有效值。

  • 範圍的排列順序是 (x, y)，