docs:Add plan of spilting into multi-library

This commit is contained in:
2026-05-21 20:31:17 +08:00
parent 295c5eaa24
commit 6b94ceea14
13 changed files with 5651 additions and 0 deletions
@@ -0,0 +1,479 @@
# IPC 协议规范
> 本文件定义主进程与 `olive-renderer` 子进程之间的全部通信方式。由于采用**"用完即弃"**模型,协议被设计为**极简、无状态、单向请求-响应**。
---
## 1. 通信通道概览
| 通道 | 方向 | 用途 | 格式 |
|---|---|---|---|
| **命令行参数** | 主进程 → 子进程 | 传递渲染配置(模式、路径、参数) | POSIX 风格长选项 |
| **stdin** | 主进程 → 子进程 | 传递节点图 XML(当 XML 过大超出命令行长度限制时) | 原始 XML 字符串 |
| **stdout** | 子进程 → 主进程 | 返回渲染结果元数据 | 单行 JSON |
| **stderr** | 子进程 → 主进程 | 日志和详细错误信息 | 纯文本 |
| **共享内存 / 内存映射文件** | 双向 | 传输大帧数据(像素/采样) | 二进制(ShmHeader + 原始数据) |
| **退出码** | 子进程 → 主进程 | 快速判断成功/失败/异常 | 整数 (0–255) |
**重要**:由于子进程渲染完成后立即退出,不存在**长期状态同步**、**心跳**、**取消信号**(主进程直接 `kill` 即可)。
---
## 2. 命令行参数
### 2.1 参数总表
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|---|---|---|---|---|
| `--mode` | string | 否 | `frame` | 渲染模式:`frame`, `batch`, `audio` |
| `--node-graph` | path | 是 | — | 节点图 XML 文件路径 |
| `--node-graph-stdin` | flag | 否 | false | 从 stdin 读取节点图 XML,而非文件 |
| `--output-node` | string | 否 | 自动探测 | 输出节点 ID |
| `--time` | rational | 条件 | — | 单帧时间点(`--mode=frame` 时必需) |
| `--times` | csv | 条件 | — | 多帧时间点列表(`--mode=batch` 时必需) |
| `--start` | rational | 条件 | — | 音频起始时间(`--mode=audio` 时必需) |
| `--duration` | rational | 条件 | — | 音频持续时间(`--mode=audio` 时必需) |
| `--video-params` | json | 条件 | — | 视频参数(`--mode=frame`/`batch` 时必需) |
| `--audio-params` | json | 条件 | — | 音频参数(`--mode=audio` 时必需) |
| `--color-ref` | string | 否 | — | 参考色彩空间名称 |
| `--color-display` | string | 否 | — | 显示色彩空间名称 |
| `--force-size` | json | 否 | — | 强制输出尺寸,如 `{"width":1920,"height":1080}` |
| `--force-format` | string | 否 | — | 强制像素格式,如 `rgba32f` |
| `--output-shm` | string | 是 | — | 输出共享内存名称或临时文件路径 |
| `--output-shm-size` | int | 是 | — | 输出缓冲区大小(字节) |
| `--output-stdout` | flag | 否 | false | 将帧数据 base64 编码输出到 stdout(仅小帧/测试) |
| `--backend` | string | 否 | `opengl` | 渲染后端:`opengl`, `dummy` |
| `--shader-path` | path | 否 | `<exe_dir>/shaders` | 着色器资源目录 |
| `--ocio-config` | path | 否 | — | OCIO 配置文件路径 |
| `--verbose` | flag | 否 | false | 详细日志输出到 stderr |
| `--version` | flag | 否 | false | 输出版本信息并退出 |
| `--help` | flag | 否 | false | 输出帮助信息并退出 |
### 2.2 参数值格式
**Rational**:`"<numerator>/<denominator>"`,如 `"1001/30000"`, `"0/1"`。
**JSON**:紧凑格式,键用双引号。例如:
```
--video-params='{"width":1920,"height":1080,"format":"rgba32f","channel_count":4,"depth":1}'
```
**CSV**:逗号分隔的有理数字符串。例如:
```
--times="0/24,1/24,2/24,3/24,4/24"
```
---
## 3. 标准输入(stdin)
当 `--node-graph-stdin` 标志存在时,子进程从 stdin 读取节点图 XML,而不是从 `--node-graph` 指定的文件。
### 3.1 使用场景
- 节点图 XML 非常大(> 100KB),超出命令行长度限制。
- 主进程不想在磁盘上创建临时文件。
- 安全考虑:敏感项目数据不写入磁盘。
### 3.2 协议
```
主进程 子进程
│ │
│── XML 数据 ──>│(子进程读取 stdin 直到 EOF)
│ │
```
子进程读取 stdin 的全部内容,视为节点图 XML 字符串。XML 结束后不需要特殊分隔符(EOF 即结束)。
**注意**:由于子进程使用 `QCoreApplication` 且不使用 Qt 的事件循环读取 stdin,应使用阻塞式 `QTextStream(stdin).readAll()` 或 `std::cin`。
---
## 4. 标准输出(stdout)
子进程将渲染结果以**单行 JSON** 输出到 stdout,以换行符 `\n` 结尾。主进程读取第一行后即视为响应完成。
### 4.1 单帧模式输出(`--mode=frame`)
**成功:**
```json
{
"status": "ok",
"mode": "frame",
"time": "1001/30000",
"width": 1920,
"height": 1080,
"format": "rgba32f",
"pixel_format_id": 28,
"channel_count": 4,
"shm_name": "/olive_frame_abc123",
"data_offset": 256,
"data_size": 33177600,
"linesize": 7680,
"render_time_ms": 42
}
```
**失败:**
```json
{
"status": "error",
"mode": "frame",
"time": "1001/30000",
"error_code": "decoder_failure",
"message": "Failed to open decoder for footage 'clip001.mp4'",
"render_time_ms": 5
}
```
### 4.2 批处理模式输出(`--mode=batch`)
**成功:**
```json
{
"status": "ok",
"mode": "batch",
"frame_count": 5,
"frames": [
{"time": "0/24", "data_offset": 256, "data_size": 33177600, "render_time_ms": 45},
{"time": "1/24", "data_offset": 33178056, "data_size": 33177600, "render_time_ms": 38},
{"time": "2/24", "data_offset": 66356112, "data_size": 33177600, "render_time_ms": 41},
{"time": "3/24", "data_offset": 99534168, "data_size": 33177600, "render_time_ms": 39},
{"time": "4/24", "data_offset": 132712224, "data_size": 33177600, "render_time_ms": 42}
],
"total_render_time_ms": 205
}
```
### 4.3 音频模式输出(`--mode=audio`)
**成功:**
```json
{
"status": "ok",
"mode": "audio",
"start": "0/1",
"duration": "48000/48000",
"sample_rate": 48000,
"channels": 2,
"sample_count": 48000,
"shm_name": "/olive_audio_abc123",
"data_offset": 256,
"data_size": 384000,
"render_time_ms": 15
}
```
### 4.4 字段说明
| 字段 | 类型 | 出现条件 | 说明 |
|---|---|---|---|
| `status` | string | 总是 | `"ok"`, `"error"`, `"cancelled"` |
| `mode` | string | 总是 | `"frame"`, `"batch"`, `"audio"` |
| `time` / `times` | string | frame/batch | 渲染时间点 |
| `width` | int | frame/batch | 帧宽 |
| `height` | int | frame/batch | 帧高 |
| `format` | string | frame/batch | 像素格式名称 |
| `pixel_format_id` | int | frame/batch | 像素格式枚举值 |
| `channel_count` | int | frame/batch | 通道数 |
| `shm_name` | string | 总是 | 共享内存名称 |
| `data_offset` | int | 总是 | 实际数据在共享内存中的偏移(跳过 ShmHeader) |
| `data_size` | int | 总是 | 实际数据大小(字节) |
| `linesize` | int | frame/batch | 每行字节数(含 padding) |
| `frame_count` | int | batch | 批处理帧数 |
| `frames` | array | batch | 每帧的元数据 |
| `sample_rate` | int | audio | 采样率 |
| `channels` | int | audio | 通道数 |
| `sample_count` | int | audio | 采样数 |
| `error_code` | string | error | 错误分类码 |
| `message` | string | error | 人类可读错误信息 |
| `render_time_ms` | int | 总是 | 纯渲染耗时(不含进程启动) |
---
## 5. 共享内存二进制布局
### 5.1 整体结构
```
┌─────────────────────────────────────────────────────────────────┐
│ 共享内存区域 │
├────────────────────────┬────────────────────────────────────────┤
│ ShmHeader (256 B) │ Payload Data │
│ │ │
│ magic │ 帧像素数据 / 音频采样数据 │
│ version │ │
│ data_offset │ 大小 = data_size │
│ data_size │ │
│ width │ │
│ height │ │
│ format │ │
│ linesize │ │
│ checksum │ │
│ reserved[...] │ │
└────────────────────────┴────────────────────────────────────────┘
```
### 5.2 ShmHeader 定义(C 结构)
```c
#include <stdint.h>
#define OLIVE_SHM_MAGIC 0x4F4C4956 // 'OLIV' 大端序
#define OLIVE_SHM_VERSION 1
#define OLIVE_SHM_HEADER_SIZE 256
typedef struct {
uint32_t magic; // OLIVE_SHM_MAGIC
uint32_t version; // OLIVE_SHM_VERSION
uint32_t data_offset; // Payload 数据起始偏移(>= 256)
uint64_t data_size; // Payload 实际数据大小(字节)
uint32_t width; // 帧宽 或 采样数
uint32_t height; // 帧高 或 0(音频)
uint32_t depth; // 3D 纹理深度(通常 1)
uint32_t channel_count; // 通道数
uint32_t pixel_format; // OlivePixelFormat 枚举值
uint32_t linesize; // 每行字节数(视频)或 0(音频)
uint64_t checksum; // CRC64 校验和(可选,0 表示未校验)
uint8_t reserved[256 - 48]; // 填充至 256 字节,未来扩展用
} OliveShmHeader;
// 辅助:计算 CRC64
uint64_t olive_shm_checksum(const void* data, size_t size);
```
### 5.3 校验和(Checksum)
- 默认启用 CRC64 校验。
- `checksum` 字段覆盖 **Payload Data 区域**(从 `data_offset` 开始的 `data_size` 字节)。
- 若主进程设置 `checksum = 0`,表示跳过校验(用于调试或性能敏感场景)。
### 5.4 多帧批处理布局
批处理模式下,所有帧连续存储在同一块共享内存中:
```
Offset 0: ShmHeader (256 B)
Offset 256: Frame 0 data (frame_0_size B, 按 linesize 对齐)
Offset 256+N0: Frame 1 data (frame_1_size B)
Offset 256+N0+N1: Frame 2 data
...
```
每帧的 `data_offset` 在 stdout JSON 中单独指定。
---
## 6. 标准错误(stderr)
### 6.1 日志级别
当 `--verbose` 启用时,stderr 输出结构化日志:
```
[2024-05-21T10:30:15.123Z] [INFO] 初始化 OpenGL 上下文
[2024-05-21T10:30:15.245Z] [INFO] OpenGL 版本: 4.6.0 NVIDIA 535.104
[2024-05-21T10:30:15.310Z] [INFO] 加载节点图: 42 个节点
[2024-05-21T10:30:15.412Z] [INFO] 开始渲染帧 @ 1001/30000
[2024-05-21T10:30:15.454Z] [INFO] 渲染完成, 耗时 42ms
[2024-05-21T10:30:15.455Z] [INFO] 写入共享内存: /olive_frame_abc123, 33177600 bytes
```
### 6.2 错误日志
错误同时输出到 stderr 和 stdout JSON:
```
[2024-05-21T10:30:15.456Z] [ERROR] Decoder 初始化失败: codec not found for 'hevc'
```
---
## 7. 退出码
| 退出码 | 名称 | 含义 | 主进程应对 |
|---|---|---|---|
| 0 | `EXIT_OK` | 渲染成功 | 正常处理结果 |
| 1 | `EXIT_GENERIC_ERROR` | 通用错误 | 记录错误,丢弃该帧 |
| 2 | `EXIT_INVALID_ARGS` | 命令行参数无效 | 检查主进程参数组装逻辑 |
| 3 | `EXIT_INIT_FAILED` | 初始化失败(OpenGL/OCIO) | 尝试 `dummy` 后端或提示用户 |
| 4 | `EXIT_GRAPH_LOAD_FAILED` | 节点图加载/解析失败 | 检查 XML 序列化逻辑 |
| 5 | `EXIT_RENDER_FAILED` | 渲染过程中出错 | 记录具体错误,丢弃该帧 |
| 6 | `EXIT_OUTPUT_FAILED` | 输出写入失败(SHM 不足) | 清理 SHM,重试或报错 |
| 130 | `EXIT_SIGINT` | 收到 SIGINT(Ctrl+C / kill -2) | 视为取消,正常丢弃 |
| 137 | `EXIT_SIGKILL` | 收到 SIGKILL(kill -9) | 视为取消,正常丢弃 |
| 139 | `EXIT_SEGFAULT` | 段错误(未捕获信号) | 视为崩溃,记录日志 |
| 其他 | — | 未知错误 | 记录日志,丢弃该帧 |
---
## 8. 主进程与子进程交互时序
### 8.1 单帧完整时序
```
时间轴 ──────────────────────────────────────────────────────────────>
主进程: [准备参数] [创建SHM] [QProcess::start()] [等待] [读JSON] [读SHM] [unlink SHM]
│ │ │ │ │ │ │
子进程: [启动] [解析参数] [加载XML] [初始化GL] [渲染] [写SHM] [写stdout] [exit]
│ │ │ │ │ │ │
└────────┴────────┴───────────┴────────┴────────┴──────────┘
进程生命周期
```
### 8.2 异常情况时序
**子进程崩溃(segfault)**:
```
主进程: [start] ── [wait] ── [finished信号] ── [exitStatus == CrashExit] ── [忽略该帧]
子进程: [启动] ── [崩溃] ──────────────────── [操作系统回收资源]
```
**主进程取消(kill)**:
```
主进程: [start] ── [用户操作/超时] ── [QProcess::kill()] ── [finished信号] ── [unlink SHM]
子进程: [启动] ── [渲染中] ───────── [SIGKILL] ──────────── [立即终止]
```
---
## 9. 共享内存生命周期管理
### 9.1 创建
```cpp
// 主进程创建
QString shm_name = "/olive_" + QUuid::createUuid().toString(QUuid::WithoutBraces);
size_t shm_size = CalculateFrameSize(params) + OLIVE_SHM_HEADER_SIZE;
void* shm_ptr = olive_shm_create(shm_name.toUtf8().constData(), shm_size);
```
### 9.2 命名规范
- POSIX: `/olive_<uuid>`,必须以 `/` 开头,长度 < 255。
- Windows: `Local\\olive_<uuid>` 或 `Global\\olive_<uuid>`。
- 临时文件: `/tmp/olive_<pid>_<uuid>.raw`(内存映射临时文件回退方案)。
### 9.3 清理策略
**正常路径**:
1. 子进程成功渲染,写入数据,退出。
2. 主进程读取数据。
3. 主进程 `olive_shm_close(ptr, size)` + `olive_shm_unlink(name)`。
**异常路径(子进程崩溃)**:
1. 主进程检测到 `QProcess::CrashExit`。
2. 主进程立即 `olive_shm_unlink(name)`(即使数据未读取)。
**双重保险**:
- 主进程在创建 SHM 时启动一个 `QTimer`(5 秒后触发)。
- 若 5 秒后 SHM 仍未被清理(异常路径未执行到 unlink),定时器自动 `olive_shm_unlink(name)`。
- 防止子进程崩溃后主进程也崩溃导致的 SHM 泄漏。
---
## 10. 平台差异
### 10.1 Linux
- 共享内存:`/dev/shm/` 下的 tmpfs 文件。
- 最大名称长度:255 字节(含 null)。
- 权限:`shm_open` 使用 `0666`,确保子进程可以打开。
- 系统限制:`/proc/sys/kernel/shmmax` 通常足够大(> 1GB)。
### 10.2 macOS
- 共享内存:`shm_open` 创建的 POSIX 共享内存对象。
- 注意:macOS 的 `shm_open` 名称长度限制为 31 字符(包括开头的 `/`)!
- **解决方案**:使用 **内存映射临时文件** 替代 POSIX shm。
```cpp
// macOS 专用:使用临时文件替代 shm_open
int fd = mkstemp("/tmp/olive_XXXXXX.raw");
ftruncate(fd, size);
void* ptr = mmap(nullptr, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
// 将文件路径传递给子进程
```
### 10.3 Windows
- 共享内存:`CreateFileMapping` + `MapViewOfFile`。
- 名称:`Local\\olive_<uuid>`(用户会话内可见)。
- 注意:句柄管理。子进程 `MapViewOfFile` 后需要保留 `HANDLE` 以便后续 `UnmapViewOfFile` 和 `CloseHandle`。
- 简化方案:子进程只负责写入,不关闭映射。进程退出后操作系统自动回收。
---
## 11. 性能调优建议
### 11.1 减少进程启动开销
| 技术 | 效果 | 复杂度 |
|---|---|---|
| 静态链接 `olive-renderer` | 避免动态库加载开销 | 低 |
| 预加载 Qt 插件 | 减少 `QCoreApplication` 初始化时间 | 低 |
| 批处理模式 | 摊销 OpenGL 上下文创建开销 | 中 |
| 使用 `EGL` 替代 `GLX`/`WGL` | EGL 上下文创建更快 | 中 |
### 11.2 减少序列化开销
| 技术 | 效果 | 复杂度 |
|---|---|---|
| 节点图 XML 缓存 | 相同图只序列化一次 | 低 |
| 增量参数更新 | 仅发送变更的参数 | 中 |
| 二进制序列化格式 | 替代 XML,解析更快 | 高 |
### 11.3 减少共享内存开销
| 技术 | 效果 | 复杂度 |
|---|---|---|
| 共享内存池 | 预分配 N 块循环使用 | 中 |
| 内存映射临时文件 | 避免 `shm_open` 系统调用 | 低 |
| 零拷贝(GPU 纹理共享) | 跨进程直接共享 GPU 纹理 | 高(平台相关) |
---
## 12. 调试工具
### 12.1 手动运行子进程
```bash
# 直接运行 olive-renderer,独立于主进程
./olive-renderer \
--mode=frame \
--node-graph=/tmp/debug_graph.xml \
--time=0/1 \
--video-params='{"width":100,"height":100,"format":"rgba32f"}' \
--output-shm=/olive_debug \
--output-shm-size=160000 \
--verbose
# 查看 stdout 输出
# 查看 stderr 日志
# 用另一个程序读取 /olive_debug 验证像素数据
```
### 12.2 环境变量
| 变量 | 作用 |
|---|---|
| `OLIVE_RENDERER_BACKEND=dummy` | 强制使用 dummy 后端(跳过 OpenGL) |
| `OLIVE_RENDERER_TIMEOUT=60000` | 子进程超时时间(毫秒) |
| `OLIVE_RENDERER_KEEP_SHM=1` | 子进程退出后不删除共享内存(调试) |
| `OLIVE_RENDERER_LOG_FILE=/path/to.log` | 将日志写入文件 |
### 12.3 重放渲染
将主进程发送给子进程的所有输入(命令行参数 + XML)保存到日志目录,可以精确重放某一帧的渲染:
```bash
# 主进程日志目录:~/.local/share/oak/renderer_logs/
# 每个渲染任务保存为:
# frame_12345.params (命令行参数)
# frame_12345.xml (节点图)
# 重放
./olive-renderer $(cat ~/.local/share/oak/renderer_logs/frame_12345.params)
```