fuchsia.ui.pointerjector

添加次数：7

协议

设备

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

用于将指针事件注入目标的渠道。 关联的 |Config| 适用于注入的指针事件。

|Device| 可以将指针事件注入场景中的目标中，但向该目标视图树中的界面客户端的指针事件调度将取决于调度政策和场景拓扑。

注入

将事件注入目标。

批处理：调用方应批量注入具有相同时间戳的所有事件（例如多个手指样本）。每次注入调用可能有多个这样的批次。

流控制：调用方一次最多只允许进行一次进行中的 |Inject| 调用：后续的 |Inject| 调用必须等待确认返回。违规会导致频道关闭。

请求

名称类型
events vector<Event>[128]

响应

<EMPTY>

注册类型

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

一种协调机制，用于明确定义向场景中注入指针事件（注入政策、注入上下文等）以将指针事件分派到界面客户端（由 |fuchsia.ui.views.ViewRef| 引用）的协调机制。

注意！只能向可信计算基准中的组件授予对本协议的访问权限。 (1) 注入器设备根据用户授权进行操作。界面客户端无法区分真实用户和注入器设备之间的区别。(2) 注册注入器设备时，上下文是自行指定的。获得敏感上下文访问权限的注入器设备将在该作用域内运行。(3) 注入的事件可以是任意的。注入器设备可以将它希望的任何内容注入到它能够触及的客户端。

此协议为注入器 |Device| 定义了上下文和目标，以与目标在空间关系上放置视口，并将 |Device| 连接到视口。这些参数是在 |Config| 中设置的。|Device| 可以在视口上注入指针事件，但指针事件到目标中的界面客户端的调度将取决于调度政策和场景拓扑。

|Device| 在上下文中操作，有以下两种用途：(1) 范围。用于确认 |Device| 有权在指定目标上注入指针事件。 (2) 坐标系。它提供参考坐标系，用于定义视口相对于目标的位置和大小。

保证。|Device| 指向场景中的指定目标，此类目标可以保证一定程度上防止来自目标视图树之外的界面客户端（“非目标客户端”）的窥探和干扰。非目标客户端从未注入向其分派的事件：|Device| 可保护目标客户端的机密性。非目标客户端绝不会阻止注入的事件在注入时到达目标或调度时到达目标客户端：|Device| 可保留目标客户端的完整性和可用性。不过，|Device| 本身容易被目标的祖先视图中断（请参阅连接性不变）。

注意：此协议及其政策不能充分防范界面伪装攻击！机密性、完整性和可用性保证仅适用于非目标客户端。在目标中，目标客户端之间仍可能会发生界面修复攻击。

连接不变。|Device| 在连接到根视图的稳定视图树中运行。当目标（或同时涉及上下文和目标）被界面客户端与视图树断开连接时，|Device| 通道会关闭。如果事件流正在进行中，服务器将在信道关闭后分派最终 CANCEL 事件；然后根据调度政策传播此 CANCEL 事件。

注册

为 |Device|（|Device| 的目标）设置上下文，并通过处于上下文中的视口将 |Device| 指向目标。这些参数在 |Config| 中指定。

如果 |config| 无效（例如缺少重要数据），|Device| 请求将被拒绝：通道将关闭。

返回事件会告知调用方：(1) 服务器已处理通话，并且 (2) |Device| 已连接。

请求

名称类型
config Config
injector server_end<Device>

响应

<EMPTY>

枚举

DeviceType 严格

类型：uint32

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

设备发出指针事件流的特性。

名称值说明
1

一种通过直接接触其表面来操纵的设备。
2

一种通过在表面上进行精确移动来操控的设备。

DispatchPolicy 严格

类型：uint32

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

界面客户端的规范，这些客户端可能已注入在 |Target| 中分派给它们的事件。在 |Config| 中指定了一个规范。

一个有用的概念是“锁存”，即一个或多个客户端可以在分配流所有权之前开始接收指针事件流。分配所有权（例如，通过手势消歧协议）后，非拥有的客户端会终止其锁存，而不再接收指针事件流。

  • 客户端的锁存本身不会授予数据流所有权（接收整个指针事件流）；手势消除歧义或设备终止可能会提前结束分派给该客户端的数据流。
  • 客户端可能在用户处于隐藏状态时进行锁定（即操纵对用户不可见的表面），其中遮挡表面归 |Target| 以外的客户端所有。相反，这些遮挡的客户端无法锁存，因为被锁存的客户端必须位于 |Target| 的视图树中。

名称值说明
1

单个客户端锁定一个指针事件流，其中：

  • 指针事件流从视口矩形内开始
  • 锁存发生在指针事件流的 ADD 阶段；
  • 客户是 |Target| 本身。 所有权会立即分配给客户。

注意：此政策可保证向客户端分派的机密性、完整性和可用性，但其本身并不会使系统获得针对界面修复攻击的豁免权。
2

多个客户端可能会锁定一个指针流，其中：

  • 指针流从视口矩形内开始
  • 在指针事件流的 ADD 阶段执行点击测试，该阶段会返回 |Target| 视图树中的最顶层表面（按绘制顺序）。
  • 最顶层 Surface 的客户端锁存指针流，
  • |Target| 视图树中客户端的祖先实体也会锁定指针流。

使用多个锁存时，会将指针流并行分派给每个锁存的客户端，直到通过手势消除分配来分配所有权。所有者客户端将继续接收指针流，非所有者则会收到该流的最终 CANCEL 事件。

注意：如果点击测试未能命中 |Target| 的任何子视图中的任何表面，则没有客户端会锁存。 注意：每个客户端都有自己的视口副本，相应副本放置在各自的坐标系中。
3

当光标位于 |Target| 视图树中时，除非鼠标固定到特定客户端，否则 |Target| 视图树中的顶级命中客户端会收到悬停事件。

鼠标通过按下按钮启动锁存，直到该锁存被释放，鼠标事件才会传递到该锁存客户端；其他客户端在锁存期间不会接收悬停事件。

注意：如果点击测试未能命中 |Target| 的任何子视图中的任何表面，则没有客户端会锁存。 注意：每个客户端都有自己的视口副本，相应副本分别放置在自己的坐标系中。

EventPhase 严格

类型：uint32

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

指针事件流状态机的可能状态。

一个典型的指针将在以下状态机中移动： ADD - CHANGE* - REMOVE

名称值说明
1

设备已开始跟踪指针。
2

设备已报告指针状态更新。
3

设备已停止跟踪指针。
4

事件流已不再可用。

表

配置资源

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

注入器 |Device| 规范。

必须填写所有字段。

序数字段类型说明
device_id uint32

用于发出指针事件流的指针设备的标识符。
device_type DeviceType

指控设备的特征。
context Context

注入器 |Device| 的范围和坐标系。

注意：为避免出现循环注入场景，|context| 必须是 |target| 的严格祖先实体。
target Target

尝试针对注入的事件进行调度的区域。

注意：为避免出现循环注入场景，|target| 必须是 |context| 的严格后代。
viewport Viewport

注入事件的初始视口。对视口的后续修改也可以与注入事件同步发送。
dispatch_policy DispatchPolicy

|target| 中可能已注入事件分派给它们的界面客户端规范。

例如，如果 |dispatch_policy| 为 |EXCLUSIVE|，则只有 |target| 可以注入已分派给它的事件，而不考虑其他因素，例如 |target| 内外客户端的 Surface 遮挡。
scroll_v_range fuchsia.input.report/Axis

设备发出的垂直滚动值的范围。
scroll_h_range fuchsia.input.report/Axis

设备发出的水平滚动值的范围。
buttons vector<uint8>[32]

设备发出的鼠标按钮标识符（按优先级顺序排列）。

鼠标按钮的优先级顺序是由注入器制定的政策选择。此优先级顺序通过 fuchsia.ui.pointer.MouseDeviceInfo.buttons 逐字传达给界面客户端，因此多个界面客户端之间以一致的方式共享按钮优先级。例如，若要使左侧 (0x1) 和右侧 (0x2) 实体按钮不再具有其传统鼠标按钮（主按钮和辅助按钮）的角色，注入器可以在此“按钮”矢量中指定 [0x2, 0x1, ...]。

请注意，保留实体按钮 ID 也是一项政策选择。如果保留，识别的界面客户端可以区分标准答案（按下的实体按钮）与所需的解释（该实体按钮在当前系统中的优先级）。
relative_motion_range RelativeMotionRange

鼠标设备 X 和 Y 的移动范围。

事件

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

序数字段类型说明
timestamp zx/Time

观察到此事件的时间。

必选。
data Data

事件的数据。

必选。
trace_flow_id uint64

用于关联此事件跨组件边界或抽象层的发送/接收情况的标识符。

PointerSample

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

对指控设备的每个采样数据点的说明。

序数字段类型说明
pointer_id uint32

发出此事件的指针的标识符。 它仅对特定指控设备具有唯一性。
phase EventPhase

指针事件流的状态机中此事件的状态。
position_in_viewport Point2

此事件在视口坐标系中的位置。
scroll_v int64

按定位点的相对垂直滚动位移。
scroll_h int64

按定位点的相对水平滚动位移。
pressed_buttons vector<uint8>[32]

当前按下按钮的标识符。
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) 坐标系。它提供参考坐标系，用于定义视口相对于目标的位置和大小。

序数变体类型说明
view fuchsia.ui.views/ViewRef

尝试通过该 View 视图对注入事件进行注入。

  • 此视图必须连接到场景图以进行注入。
  • 注入的事件仅限于此视图及其子视图。

数据灵活

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

通过通道发送的一组 FIFO 数据。 每项数据可能具有不同的发布政策。

序数变体类型说明
viewport Viewport

视口的参数，足以让客户端正确解释分派给它的指针事件的位置和缩放比例。

  • 每当视口发生变化时都会发出该监听器。
pointer_sample PointerSample

指针事件流中每个采样数据点的说明。

  • 它会针对指针事件流中的每个样本发出。

目标严格 资源

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

尝试在其中调度注入的事件的区域。您可以在 |Config| 中指定特定的调度政策。

序数变体类型说明
view fuchsia.ui.views/ViewRef

在该视图中尝试调度注入的事件。

  • 此视图必须连接到场景图才能进行调度。
  • 注入的事件仅限于此视图及其子视图。

常量

名称值类型说明
MAX_INJECT 128 uint32

别名

名称值说明
范围 array[2]

一对浮点数，表示最小和最大范围。

  • 值会按照（最小、最大）顺序排列。
Mat3 array[9]

浮点 3x3 矩阵。

  • 这些值按列主要顺序排列。
Point2 array[2]

一个二维浮点数。

  • 这些值将按 (x, y) 顺序排列。
RelativeMotion array[2]

鼠标设备执行的相对动作。
RelativeMotionRange array[2]

鼠标设备的相对动作的有效值。

  • 范围会按 (x, y) 顺序排列。