Discover Core Image debugging techniques

Highlight

Apple 提供 CI_PRINT_TREE 环境变量，让 Core Image 开发者把每次渲染的 graph 输出为文本、PDF 或 PNG，用来定位颜色空间转换、中间缓冲、ROI、耗时和内存问题。

核心内容

Core Image 的输出经常看起来像一张图片，实际内部是一条延迟执行的 recipe。开发者创建 filter、设置输入、拿到 outputImage 时，很多工作还没有真正渲染。问题出在颜色管理、优化重排、GPU pass 或缓存命中时，只看最终图像很难判断是哪一步改坏了结果。

这场 session 聚焦一个工具：CI_PRINT_TREE。它基于 Xcode 中 Core Image Quick Look 使用的同一套基础设施。调试时点击 CIImage 旁边的 eye 图标，可以看到生成这张图像的可视化 recipe；打开环境变量后，每次 render 还可以自动输出 Core Image graph。

这个 graph 的价值在于把隐藏的管线摊开。你可以看初始树确认颜色空间，看优化树确认 Core Image 如何重排、合并和裁剪节点，也可以看连接到 GPU program 后需要多少中间 buffer。对于照片、视频和视觉效果类 App，这比盯着最终 frame 猜原因更直接。

详细内容

1. 在 Xcode 或 Terminal 中打开 CI_PRINT_TREE（01:41）

CI_PRINT_TREE 是一个环境变量。session 给出两种开启方式：在 Xcode target scheme 的 Arguments 面板加入环境变量，或在 Terminal 中设置后再启动 App executable。

CI_PRINT_TREE=1 /path/to/AppExecutable

关键点：

• CI_PRINT_TREE 的值控制 Core Image 输出哪一种 graph。
• 1 对应每次 image render 的初始状态，适合先检查输入和颜色空间。
• 这个变量只影响调试输出，不改变 Core Image 的滤镜算法。

2. 用 1、2、4、7 选择 graph 阶段（02:26）

Core Image render 有三个可观察阶段。type 1 是初始状态，type 2 是优化后的 render，type 4 是 Core Image 把阶段连接成 GPU program 之后的结果。session 明确提到这些值可以组合，7 会同时输出 1、2 和 4。

CI_PRINT_TREE=1   # initial render tree
CI_PRINT_TREE=2   # optimized render tree
CI_PRINT_TREE=4   # concatenated GPU-program tree
CI_PRINT_TREE=7   # 1 + 2 + 4

关键点：

• 1 用来确认 render 开始时每个 image 和 node 的状态。
• 2 用来观察 Core Image 如何 reorder、combine 和 prune render 阶段。
• 4 用来查看 Core Image 连接 GPU program 后需要的中间 buffer。
• 7 适合完整排查一次复杂 render，但输出量会增加。

3. 选择 PDF、PNG、text 或 oslog 输出（03:13）

输出类型可以是 PDF 或 PNG。指定这些类型时，Core Image 会为每次 render 保存 graph document。macOS 会写入 temporary items directory；iOS 会优先写入 Documents directory，失败时退回 temporary directory。没有指定输出类型时，Core Image 会把紧凑文本输出到 standard out。

export CI_LOG_FILE="oslog"

关键点：

• CI_LOG_FILE="oslog" 会把文本输出送到 Console.app，对 iOS 调试更方便。
• PDF 或 PNG 适合分析节点结构、颜色转换和中间结果。
• text 输出适合快速看 render 是否触发，以及 graph 是否按预期生成。

4. 用 context、frame 和中间图像缩小排查范围（03:52）

复杂 App 可能有多个 CIContext，视频 App 还会连续 render 很多 frame。session 提到 context==name 可以只记录指定名称的 context，frame-number 可以只记录每个 context 的第 n 次 render。还有一些选项可以把输入图像、中间图像和输出图像一起写进 document。

context==name
frame-number
dump-intermediates

关键点：

• context==name 用来过滤某一个命名的 CIContext。
• frame-number 用来抓取指定 render 次数，适合视频或实时预览。
• dump-intermediates 与 type 4 配合时，可以显示除输出 pass 外每个 pass 的中间 buffer。
• 带图像的 document 会增加生成时间和内存，session 明确要求谨慎使用。

5. 从 graph 里读颜色、ROI、缓存和资源压力（05:24）

CI_PRINT_TREE document 的阅读方向是底部输入、顶部输出。绿色节点代表 warp kernel，红色节点代表 color kernel。初始树里可以寻找 colormatch 节点，确认输入图像是否从 HLG colorspace 转到 Core Image linear working space。

input images: bottom
output image: top
green nodes: warp kernels
red nodes: color kernels
ROI: region of interest

关键点：

• colormatch 节点能暴露颜色空间转换，适合排查 HDR 或视频颜色不一致。
• 每个节点显示 ROI（region of interest），说明本次 render 需要该节点的哪一块区域。
• 如果某个中间图像没有出现在 tree 里，Core Image 可能复用了早先 render 的缓存。
• document 还能显示每个 pass 的 execution time、pixel count 和 pixel format，用来判断时间和内存消耗集中在哪一段。

核心启发

Core Image 调试开关

做什么：在 Debug 构建里加入一个 Core Image graph 导出开关。

为什么值得做：CI_PRINT_TREE 可以把 render 的初始树、优化树和 GPU program 树输出成可读 document，团队不必只靠最终图像猜测错误来源。

怎么开始：先在 Xcode scheme 中添加 CI_PRINT_TREE=1，确认输出路径和文件权限，再为复杂场景切到 7 抓完整 graph。

HDR 颜色管线审计

做什么：为照片或视频编辑 App 做一个颜色空间排查流程。

为什么值得做：session 展示了通过 colormatch 节点查看 HLG 到 Core Image linear working space 的转换，颜色问题可以在 graph 里直接定位。

怎么开始：抓取 type 1 的初始 tree，查找 colormatch 节点和 colorspace 名称，把输入素材、工作空间和输出配置记录到同一份调试报告。

视频帧性能采样

做什么：给实时滤镜预览增加按 frame 抓取的性能样本。

为什么值得做：frame-number 可以只记录指定 render；document 里有 execution time、pixel count 和 pixel format，能指出最耗时或最占内存的 pass。

怎么开始：先用 frame-number 固定一次异常 frame，再用 type 4 和 dump-intermediates 查看中间 buffer，最后对照 UI 操作复现同一帧。

iOS 设备现场诊断

做什么：为 iOS 调试版准备一套取回 Core Image graph 的流程。

为什么值得做：session 说明 iOS 会把 document 写入 Documents directory 或 temporary directory，CI_LOG_FILE="oslog" 还能把文本日志送到 Console.app。

怎么开始：开启 iTunes file sharing，把 graph document 从 Finder 的 Files 面板拖回 Mac；日志侧使用 Console.app 按进程过滤。

关联 Session

• Optimize the Core Image pipeline for your video app — 讲 Core Image 视频管线的内存、播放视图和 Metal command queue 优化，适合和 CI_PRINT_TREE 的性能分析一起看。
• Build Metal-based Core Image kernels with Xcode — 展开 .ci.metal kernel 的集成和加载，适合排查自定义 Core Image kernel 的 graph。
• Gain insights into your Metal app with Xcode 12 — 介绍 Xcode 12 的 Metal 调试与性能工具，补足 GPU 层面的图形问题定位。
• Optimize Metal apps and games with GPU counters — 展示 GPU counters 的采集和解读方式，适合继续分析 Core Image 背后的 Metal 工作负载。