# 离线预览器

## 1. 目标

预览器在不调用 Spine Editor、不开启网络的情况下直接读取：

```text
.json/.skel + .atlas/.atlas.txt + texture pages
```

用户通过预览确认资源配对、版本、Scale、Alpha、动画和 Skin 后，才进入转换。

## 2. Runtime 版本矩阵

| 数据 | Runtime 插件 |
|---|---|
| 3.8.20+ | `dts-runtime-3_8` |
| 4.0.x | `dts-runtime-4_0` |
| 4.1.x | `dts-runtime-4_1` |
| 4.2.x | `dts-runtime-4_2` |
| 4.3.x | `dts-runtime-4_3` |

每个插件基于官方仓库对应分支的 `spine-cpp`。Runtime 与数据主/次版本必须一致。

## 3. 公共插件 ABI

公共 API 使用版本号和结构体大小实现向前兼容：

```text
dtsRuntimeGetApiVersion
dtsRuntimeCreate
dtsRuntimeDestroy
dtsRuntimeLoad
dtsRuntimeGetMetadata
dtsRuntimeGetAnimations
dtsRuntimeGetSkins
dtsRuntimeSetAnimation
dtsRuntimeSetSkin
dtsRuntimeSeek
dtsRuntimeUpdate
dtsRuntimeBuildFrame
dtsRuntimeGetLastError
```

设计规则：

- 调用方提供结构体 `size`。
- 插件返回的内存由插件释放。
- 错误不能以 C++ 异常越过 ABI。
- 所有字符串为 UTF-8，并带长度。
- 插件的所有上游符号默认隐藏。
- 主程序校验插件文件和 ABI 版本后才加载。

## 4. 统一绘制数据

插件输出与 Runtime 版本无关的 draw list：

```text
PreviewFrame
  bounds
  vertices[]
  indices[]
  commands[]

DrawCommand
  textureHandle
  firstIndex
  indexCount
  blendMode
  premultipliedAlpha
```

顶点至少包含：

- position
- uv
- light color
- dark color

Clipping 优先在对应 Runtime/adapter 中完成，使主渲染器只处理最终三角形。

## 5. 纹理加载

主程序实现统一 Texture Provider：

- 根据 Atlas 页面路径读取本地文件。
- 拒绝 HTTP/HTTPS 和 data URL。
- 规范化相对路径并阻止目录逃逸。
- 支持 PNG、JPG/JPEG、WebP。
- 保留源 Alpha 模式元数据。
- 缓存按 canonical path、修改时间和文件大小失效。

图片解码插件必须随安装包部署，不能在运行时下载。

## 6. 渲染功能

首版必须支持：

- Region 和 Mesh
- Weighted Mesh、Linked Mesh
- Clipping
- Normal、Additive、Multiply、Screen
- 单颜色和 Two Color Tint
- PMA 和 Straight Alpha
- 多页 Atlas
- 高 DPI
- 骨骼、Mesh、边界、裁剪调试层

Shader 作为本地资源随程序部署，并在构建期或启动期从本地加载。

## 7. 播放状态

每个预览会话保存：

```text
selectedAnimation
selectedSkin
loop
playbackSpeed
time
paused
camera
background
debugFlags
```

切换资源组时保留各组会话，避免用户往返查看时丢失位置。

Seek 需要确定性：先恢复 setup pose，再从动画起点应用到目标时间，不能依赖累积浮点步进得到任意帧。

## 8. 错误隔离

首版采用动态插件；技术原型评估损坏 SKEL 是否可能使上游 Runtime 崩溃。如果无法通过输入边界检查和测试降低风险，发布版改为每个版本一个 helper process：

```text
UI ↔ local IPC ↔ preview-worker-4_2
```

是否进程隔离由原型的崩溃与模糊测试结果决定，不在未验证前锁死。

## 9. 性能目标

- 普通单骨骼资源首次预览在本地 SSD 上目标小于 1 秒。
- 预览默认 60 FPS；窗口不可见时暂停刷新。
- 大资源限制最大纹理尺寸、顶点数、附件数和单帧命令数。
- 纹理解码在线程池执行，OpenGL 创建在渲染线程执行。
- 切换动画不重复加载 Atlas 纹理。

## 10. 预览验收

- 五个版本官方示例的选定动画与官方参考视觉一致。
- 动画名、Skin 名和时长与 Runtime 数据一致。
- PMA/Straight Alpha 无明显黑边或白边。
- Mesh、Clipping、双颜色 Tint 和混合模式分别有测试样本。
- 缺失纹理不会导致崩溃，并能在画布上定位缺失项。
- 拔网后所有预览功能保持可用。