mrkai77/Subsurface
GitHub: mrkai77/Subsurface
Subsurface 是一个 Swift 库，为 macOS 应用提供对触控板原始多点触控数据、手势识别和触觉反馈的直接访问能力。
Stars: 2 | Forks: 0
Subsurface
适用于 macOS 的原始多点触控、手势和触觉反馈。
Subsurface 让 Swift 应用能够直接访问 Mac 的多点触控设备。它将 Apple 私有的 `MultitouchSupport.framework` 封装为更友好的 API，用于读取原始接触帧、追踪已连接的触控板、识别平移/捏合/旋转手势，以及触发 Force Touch 触觉反馈。
## 安装说明
要将 Subsurface 添加到你的 Xcode 项目中，你可以使用 Swift Package Manager (SPM)。请按照以下步骤操作：
1. 在 Xcode 中打开你的项目。
2. 前往 `File` > `Add Package Dependencies...`。
3. 输入此 URL：`https://github.com/mrkai77/Subsurface`
4. 将 `Subsurface` 库添加到你的 target 中。
Subsurface 目前的目标平台为 macOS 13 及更高版本。
## 用法
下面的示例展示了该包的主要层级。你可以直接操作单个设备、通过 monitor 进行全局监听、将接触帧提供给手势识别器，或者使用触控板执行器来获得触觉反馈。
### 从单个设备读取接触点
```
import Subsurface
guard let device = SubsurfaceDevice.defaultDevice else {
return
}
device.start()
for await contacts in device.contactFrames() {
for contact in contacts {
let position = contact.normalizedVector.position
print("finger \(contact.id): \(position.x), \(position.y)")
}
}
```
`MTContact` 暴露了接触状态、手指和手的分类、归一化位置、速度、压力、角度和触摸椭圆大小。这些值直接来自底层多点触控流，因此你可以决定要进行多少过滤或解释。
### 监控所有触控板
```
import Subsurface
let monitor = SubsurfaceMonitor()
monitor.start()
for await (device, contacts) in monitor.contacts() {
print("\(device.name): \(contacts.count) contacts")
}
```
monitor 会监视 IOKit 中多点触控设备的接入和移除。如果你想同时支持内置触控板和 Magic Trackpad，而又不想让调用者预先选择设备，它将非常有用。
### 识别手势
```
import Subsurface
let monitor = SubsurfaceMonitor()
let recognizer = SubsurfaceGestureRecognizer(fingerCount: 2)
monitor.start()
for await event in recognizer.events(from: monitor) {
switch event {
case let .pan(pan):
print("pan: \(pan.translation), velocity: \(pan.velocity)")
case let .pinch(pinch):
print("pinch: \(pinch.distance) from \(pinch.originDistance)")
case let .rotation(rotation):
print("rotation: \(rotation.rotation) radians")
case let .determining(centroid, fingerCount):
print("waiting on \(fingerCount) fingers at \(centroid)")
case let .unresolvedEnded(reason):
print("gesture ended before resolving: \(reason)")
}
}
```
识别器起始处于判定阶段，随后会锁定到第一个超过其阈值的手势上。首先是捏合，然后是旋转，最后是平移。一旦手势开始，只要表面上至少保留两根手指，它就会持续追踪，这与 macOS 系统手势的粘滞感相吻合。
你可以直接调整阈值：
```
recognizer.minimumPanTranslation = 0.08
recognizer.minimumPinchDistance = 0.1
recognizer.minimumRotation = 0.15
recognizer.inactivityTimeout = .milliseconds(250)
```
### 触觉反馈
```
import Subsurface
guard let actuator = SubsurfaceDevice.defaultDevice?.actuator else {
return
}
actuator.open()
actuator.actuate(pattern: .click, intensity: 0.8)
actuator.close()
```
Subsurface 包含了目前已被映射的内置反馈模式，如果你想构建自己的波形字典，它也支持自定义触觉模式。
## 可视化工具
`Visualizer` 文件夹包含一个小型的 SwiftUI 应用，用于查看原始触摸流。它可以显示接触椭圆，并可选择显示速度矢量、压力等接触元数据、手掌抑制、已连接的设备以及触觉反馈模式。在基于该库进行开发之前，这是检验你的触控板实际报告内容的最简单方法！
该可视化工具正被用于展示 Loop 的触控板手势。
## 许可证
Subsurface 采用 Apache-2.0 许可证发布。请查看仓库中的 [LICENSE](LICENSE) 文件以了解完整的许可证内容。
标签：Swift, 多点触控, 开发库, 手势识别, 触控板, 触觉反馈