触觉反馈协议¶

在 0.50.0 版本加入.

某些输入设备可以向用户回馈轻触感：Apple 笔记本触控板和 Magic Trackpad，Surface Slim Pen 2、Apple Pencil Pro 等笔，以及 Surface Dial 等旋钮。应用可用它表示拖动物体吸附对齐、手势结束、笔落下，或在笔上模拟铅笔／画笔划过纸面的阻力。触觉反馈协议让终端程序请求同类反馈。协议刻意保持简洁：先查询可播放内容，再请求轻触，或开始／停止工具质感。没有硬件或不支持协议的终端不执行操作。

消息封装¶

帧使用带有 haptic 选择器的 OSC 777：:

<OSC> 777 ; haptic ; v=1 : op=play : pattern=alignment <ST>

帧遵循 OSC 777 扩展封装规定的 OSC 777 共用规则：字段语法、拒绝哪些帧，以及单位。协议版本 v 为 1，op 为 query、cap、play、start 或 stop。op 不在其中，或某个键的值不是已定义值时，也会忽略整条请求。终端仅发送回复，回复绝不合并或丢弃。

反馈在目标上播放，由请求中的 target 指定：trackpad``（省略字段时的默认目标）、``pen``（当前正在数位板或屏幕上使用的笔），或 ``dial。无法在指定目标上播放时，终端丢弃请求。

能力探测¶

程序查询终端可播放哪些反馈：:

<OSC> 777 ; haptic ; v=1 : op=query : id=42 <ST>

id 是程序自行选择的非负 31 位整数，回复原样返回，以便匹配查询。支持协议的终端回答：:

<OSC> 777 ; haptic ; v=1 : op=cap : id=42 : caps=1 <ST>

caps 为位集合。1、2 和 4 分别表示当前机器此刻可在触控板、笔和旋钮上播放轻触，且用户没有关闭。8 表示可在笔上播放下述连续反馈。不支持协议的终端会忽略查询，因此程序必须设置超时。配对笔或用户修改设置时，答案可能变化；曾得知某个位未设置的程序可稍后重试查询。

轻触反馈¶

<OSC> 777 ; haptic ; v=1 : op=play : pattern=generic <ST>
<OSC> 777 ; haptic ; v=1 : op=play : target=pen : pattern=complete <ST>

pattern 必需，取以下值之一：

`generic`	单次轻触，用于放下物体或接触
`alignment`	拖动物体吸附到位时的轻触
`level`	压力感应控件切换档位时的轻触
`click`	按钮按下或旋钮经过卡点时的轻触
`complete`	表示操作完成的轻触，例如笔迹识别成形状或路径闭合

终端仅为获得焦点的窗口播放轻触，每个操作系统窗口最多每 50 毫秒一次，其余静默丢弃。不产生回复。

连续反馈¶

带马达的笔可在绘画期间让玻璃表面产生纸面质感。程序在笔划开始时开启，结束时关闭：:

<OSC> 777 ; haptic ; v=1 : op=start : target=pen : pattern=pencil : intensity=60 <ST>
<OSC> 777 ; haptic ; v=1 : op=stop : target=pen <ST>

start 必须带 pattern，指定所需工具质感：ink、pencil、marker、brush 或 eraser。intensity 为最大强度的百分比，范围 0 至 100，省略时为 100。目标已播放反馈时，再次 start 会替换模式和强度，使反馈可跟随笔压力变化。stop 结束反馈；未指定 target 时，停止所有目标上的连续反馈。两者均无回复，也不受轻触反馈频率限制。

连续反馈不能在请求程序退出后持续，因此终端会在以下情况自行停止：

窗口失去焦点；
某目标在一秒内未再次收到 start。因此希望反馈持续的程序至少每秒重复两次 start；相同值的重复不会产生可感知变化；
终端被重置。

中继或多路复用器为获得焦点的窗格转发请求，不代替程序重复 start。

各系统的对应模式¶

这些模式使用各硬件系统原有的反馈，采用最接近的名称。系统列中只有第一列由 Silkie 实际播放；其他列供相应系统上的终端实现参考。

模式	macOS 触控板，`NSHapticFeedbackManager`	Windows 笔或旋钮，`KnownSimpleHapticsControllerWaveforms`	iPadOS Apple Pencil Pro，`UICanvasFeedbackGenerator`
`generic`	`generic`	`Click`
`alignment`	`alignment`	`Align`	`alignmentOccurred(at:)`
`level`	`levelChange`	`Step`
`click`	`generic`	`Click`
`complete`	`generic`	`Success`	`pathCompleted(at:)`
`ink`		`InkContinuous`
`pencil`		`PencilContinuous`
`marker`		`MarkerContinuous`
`brush`		`BrushContinuous`
`eraser`		`EraserContinuous`

表格单元为空时，表示该系统没有相近反馈，终端应丢弃请求。

Silkie 中的实现¶

Silkie 在 macOS 触控板上播放轻触，用通用轻触代替 click 和 complete；用户可通过 haptic_feedback 关闭。Silkie 在其运行的各系统上都无法驱动笔或旋钮，因此 macOS 的 caps 为 1，其他系统为 0；针对其他目标的请求及 start、stop 会被接受，但不产生效果。