OSC 777 扩展封装

在 0.50.0 版本加入.

本分支的终端扩展（例如 数位板指针协议）使用共同的消息封装。本页说明它们共有的规则：帧的读写方式、报告使用的单位和时钟、链路来不及处理时可合并哪些报告，以及如何开启和拒绝模式。各扩展页面列出自己的选择器和字段，仅说明其特有行为。

语法

帧是 OSC 777 转义序列，第一个字段为指明扩展的选择器：:

<OSC> 777 ; <selector> ; <fields> <ST>

<OSC> 为 <ESC> ]，<ST> 为 <ESC> \；也接受 BEL 作为终止符。字段为 ASCII key=value 键值对，以冒号分隔，顺序任意，键名区分大小写。数值为十进制整数，不带前导 +；仅有符号字段允许前导 -。这些页面示例中的空格仅用于清晰展示。每帧都有扩展协议版本 v，以及说明帧类型的 op。

程序发出的帧

程序帧出现以下任一情况时，将整帧拒绝且不改变任何状态：

  • 终端不认识该版本；

  • 同一个键出现多次；

  • 值超出规范规定的范围，或数值未按上述格式书写；

  • 缺少规范要求的字段值。

字段本身没有独立长度限制。帧属于转义序列，因此配置的 escape_limit 可以限制整个 OSC 序列。

程序发送的帧，无论被拒绝、不完整还是被接受，都绝不会作为按键输入传给该程序或其他程序。

协议扩展

无论帧的方向如何，接收方都忽略不认识的键，因此扩展可以新增字段而无需升级版本。程序忽略不认识 op 的帧，也忽略终端发来的不认识版本的帧。只有修改既有内容的含义时才需要新版本。

单位

  • 位置以物理像素的 1/256 为单位，相对于字符单元区域的左上角；允许落在区域外的位置使用有符号值。物理像素指终端所绘制帧缓冲区中的像素，而非系统的逻辑单位，后者在高密度显示器上可能对应多个物理像素。支持显示协议的终端可参阅其中的 Pixels 小节。

  • 设备上的长度（如数位板或触控板尺寸）以 1/256 毫米为单位。

  • 角度以百分之一度为单位。

  • 时间的定义如下。

时间

终端对已发生事件的每条报告都携带 t：同一单调时钟上的毫秒值，全部扩展和全部窗口共用此时钟。因此，笔报告的 t 可与画面报告的 t 相减，计算笔迹到达屏幕所需时间。时钟原点由终端选择，在整个运行期间保持固定，单独的 t 没有绝对意义。t 是系统认定事件发生的时刻；系统未给出时刻时，使用终端获知事件的时刻。若存在 tu，则表示 t 之后的微秒数，范围 0 至 999。只有系统提供比毫秒更精细的时间戳时才发送此字段；没有它的报告仅具有整毫秒精度。

kitty 使用自身计时所用的时钟，从 kitty 启动时开始计时。

传递规则

终端按事件发生顺序发送报告，不丢弃报告。如果程序未读取输入或链路较慢，导致终端或中继无法跟上，则只能合并以下报告：

  • 数位板指针协议中，同一接触点连续的 move 或 hover 报告，期间没有该接触点的其他报告，且 buttons 相同。合并后使用最后一条报告的绝对值，并对相对值 wheel 和 wclicks 求和。被合并分组的帧报告（阶段 6）也随之合并。

  • 同一手势连续的 update 报告，其中 scale 相乘，旋转和平移量分别求和。

  • 同一设备、同一阶段的连续滚动报告，将距离求和。

合并报告携带最后一条被合并报告的 t。其他内容绝不合并或丢弃：down、up、cancel、out、按钮变化、设备描述、回复、模式报告、手势开始或结束、滚动阶段变化，以及画面呈现协议的全部报告。各扩展页面说明了其哪些报告可合并。

Silkie 本身不合并报告。写给程序的内容保留在内存中，等待程序读取，每个窗口最多 100 MiB。如果一次写入会超出 100 MiB，则整次写入被丢弃，并记录错误；积累这么多未读内容的程序已停止读取。