157 lines
3.8 KiB
Markdown
157 lines
3.8 KiB
Markdown
# 离线预览器
|
||
|
||
## 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 和混合模式分别有测试样本。
|
||
- 缺失纹理不会导致崩溃，并能在画布上定位缺失项。
|
||
- 拔网后所有预览功能保持可用。
|