# 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)
```