axiom-graphics

图形

任何 GPU 渲染、图形编程、3D 内容显示或显示性能相关工作，都必须使用此技能。

适用场景

在以下情况下使用此路由：

• 将 OpenGL/OpenGL ES 代码移植到 Metal
• 将 DirectX 代码移植到 Metal
• 将 GLSL/HLSL 着色器转换为 Metal Shading Language
• 设置 MTKView 或 CAMetalLayer
• 窗口调整大小或在屏幕之间移动时，渲染出现故障或模糊
• 调试 GPU 渲染问题（黑屏、颜色错误、崩溃）
• 评估转换层（MetalANGLE、MoltenVK）
• 优化 GPU 性能或解决热降频问题
• App 在 ProMotion 设备上卡在 60fps
• 配置 CADisplayLink 或渲染循环
• 可变刷新率显示问题
• 在非游戏 SwiftUI App 中显示 3D 内容
• 使用 RealityKit 构建 AR 体验
• 在 SwiftUI 中使用 RealityView 或 Model3D
• 空间计算或 visionOS 3D 内容
• 在 Swift 中读取、编辑或导出 USD/USDZ 文件（USDKit）
• 在渲染管线中加入 ML（MetalFX 降噪、Metal 张量、神经渲染）
• 分析长时间游戏会话（metalperftrace、回溯跟踪）

路由逻辑

Metal 迁移

策略决策 → 参见 skills/metal-migration.md

• 决定使用转换层还是原生重写
• 项目评估与迁移规划
• 反模式与常见错误
• 应对截止期限压力的场景

API 参考与转换 → 参见 skills/metal-migration-ref.md

• GLSL → MSL 着色器转换表
• HLSL → MSL 着色器转换表
• GL/D3D API → Metal API 对应关系
• MTKView 设置、渲染管线、计算着色器
• 完整的 WWDC 代码示例

诊断 → 参见 skills/metal-migration-diag.md

• 移植后黑屏
• 着色器编译错误
• 颜色或坐标系错误
• 性能回退
• 各诊断路径的时间成本分析

窗口调整大小时的渲染表面

可调整大小的窗口中的任何渲染表面 → 参见 skills/resizable-rendering.md

• MTKView drawableSizeWillChange（投影 + 重新分配渲染目标、实时调整大小时的限流）
• CAMetalLayer 手动管理 drawableSize/contentsScale
• 各类表面的适配表：视频图层、地图、图表、Canvas、Web 视图、PDF、SpriteKit/SceneKit
• 场景在屏幕之间移动时，按 displayScale 使缓存失效（镜像、外接显示器）

显示性能

帧率与渲染循环 → 参见 skills/display-performance.md

• App 在 ProMotion（120Hz）设备上卡在 60fps
• MTKView 或 CADisplayLink 配置
• 可变刷新率优化
• 系统限制（低电量模式、限制帧速率、热限制、自适应电源）
• 帧预算计算（120Hz 时为 8.33ms）
• 测量实际帧率与报告帧率

RealityKit（非游戏 3D 内容）

对于非游戏 SwiftUI App 中的 3D 内容、AR 体验和空间计算，请使用 RealityKit 技能。对于游戏专用的 RealityKit 模式，请改用 axiom-games 路由。

架构、ECS 与最佳实践 → 参见 skills/realitykit.md

• 实体-组件-系统架构
• SwiftUI 集成：RealityView、Model3D、附件
• iOS 上的 AR：AnchorEntity 类型、SpatialTrackingSession
• 材质、物理、交互
• 性能优化

API 参考 → 参见 skills/realitykit-ref.md

• 完整的组件目录
• RealityView 和 Model3D API
• 材质系统（PBR、Unlit、Occlusion、Custom）
• RealityRenderer（Metal 集成）

故障排查 → 参见 skills/realitykit-diag.md

• 实体不可见、锚点未跟踪
• 手势无响应、性能问题
• 材质问题、物理问题

HDR 色调映射与颜色

HDR 绘制与颜色元数据 → 参见 skills/hdr-color-ref.md

• HDR 图像绘制到 CGContext 时褪色、过曝或变暗
• 选择色调映射方法（CGContentToneMappingInfo 与 CGToneMapping）
• ICC 配置文件中的 Headroom 自适应增益曲线元数据（OS27）
• 持久化 CGColor / CGColorSpace（OS27 中的 Codable）

USD 创作（USDKit）OS27

在 Swift 中处理 USD 文件 → 参见 skills/usdkit.md

• 打开、遍历和编辑 USD 阶段与基元
• 引用与组合
• 3D 资源的辅助功能元数据
• 导出 USDZ，并进行网格／纹理压缩
• 在 RealityKit 中渲染 USD 阶段（USDStageComponent）

决策树

1. 转换层还是原生重写？→ metal-migration
2. 将代码移植／转换为 Metal？→ metal-migration
3. API 参考／着色器转换表？→ metal-migration-ref
4. MTKView／渲染管线设置？→ metal-migration-ref
5. 移植后出现问题（黑屏、颜色错误）？→ metal-migration-diag
6. 在 ProMotion 设备上卡在 60fps？→ display-performance
7. CADisplayLink／可变刷新率？→ display-performance
8. 帧率不符合预期？→ display-performance
9. 在 SwiftUI 中显示 3D 模型？→ realitykit
10. 构建 AR 体验？→ realitykit
11. 设置 RealityView 或 Model3D？→ realitykit-ref
12. 3D 内容不可见或无法追踪？→ realitykit-diag
13. 对 RealityKit 内容进行自定义 Metal 渲染？→ realitykit-ref（RealityRenderer）
14. 寻路、LOD、柔和阴影、点云、混响网格？→ realitykit-ref（第 10 部分）
15. 在 Swift 中读取／编辑／导出 USD 或 USDZ 文件？→ usdkit
16. 在渲染管线中使用 ML（降噪、Metal 张量）？→ metal-migration-ref（第 6 部分）
17. 长时间游玩后出现掉帧？→ display-performance（第 12 部分）
18. 绘制时 HDR 图像显得褪色／过曝？→ hdr-color-ref
19. 选择色调映射方法或读取 HAGC 元数据？→ hdr-color-ref
20. 窗口调整大小或切换屏幕时，渲染内容被拉伸、模糊或出现黑边？→ resizable-rendering
21. 构建 3D 游戏？→ 改用 axiom-games 路由器

避免自我合理化

想法	现实
“我只要逐行转换着色器就行”	GLSL→MSL 在类型、坐标和精度方面存在差异。metal-migration-ref 提供转换表。
“MetalANGLE 能处理所有事情”	转换层在生产环境中存在显著局限。metal-migration 会评估其中的权衡。
“只是黑屏，可能是个简单的错误”	黑屏有 6 种不同原因。metal-migration-diag 可在 5 分钟内完成诊断，而不是耗费 30 多分钟。
“我的应用能以 60fps 运行，足够了”	ProMotion 设备支持 120Hz。display-performance 可配置正确的帧率。
“我直接用 SceneKit 显示 3D 模型就行”	SceneKit 已被软弃用。RealityView 和 Model3D 才是现代方案。skills/realitykit.md 介绍了 SwiftUI 集成。
“只有一个 3D 模型，不需要 ECS”	Model3D 可以不使用 ECS 显示单个模型。RealityView 则可扩展到复杂场景。skills/realitykit.md 展示了这两种方案。
“我自己解析 USD 文件／打包 OpenUSD 就行”	在 OS 27 系列版本中，USDKit 提供系统内置的 USD 支持。skills/usdkit.md 介绍了阶段、编辑和压缩导出。
“我自己在场景图上实现寻路就行”	RealityKit 27 提供导航网格，支持代价和网格外连接。参见 skills/realitykit-ref.md 第 10 部分。
“只在游玩一小时后才掉帧，无法追踪”	OS 27 系列版本会持续记录 Metal 指标，可事后使用 metalperftrace 收集。参见 skills/display-performance.md 第 12 部分。
“根据屏幕边界设置渲染目标大小就行”	在 OS 27 中，窗口会持续调整大小，场景也会在缩放比例不同的屏幕之间移动。请根据 drawable／视图和 trait 缩放比例设置大小——参见 skills/resizable-rendering.md。
“我用 CGContentToneMappingInfo——它是现代 Swift 枚举”	它无法表达 Headroom Adaptive Gain Curve；只有通过 C 导入的 CGToneMapping 才能做到。名称更新，能力却更窄。参见 skills/hdr-color-ref.md 第 1 部分。

关键模式

metal-migration：

• 使用转换层（MetalANGLE）快速制作演示
• 为生产环境重写为原生 Metal
• 状态管理差异（GL 有状态 → Metal 显式管理）
• 坐标系注意事项（Y 轴翻转、NDC 差异）

metal-migration-ref：

• 完整的着色器类型映射
• API 等效项对照表
• MTKView 与 CAMetalLayer 的选择
• 渲染管线设置模式

metal-migration-diag：

• GPU 帧捕获工作流（2–5 分钟，避免盲目猜测 30 多分钟）
• 使用着色器调试器检查变量
• 使用 Metal 验证层检查 API 误用
• 性能回退诊断

display-performance：

• MTKView 默认使用 60fps（必须设置 preferredFramesPerSecond = 120）
• 使用 CADisplayLink 的 preferredFrameRateRange 显式控制帧率
• 系统限制：低电量模式、限制帧速率、温度、自适应电源（iOS 26）
• 120Hz 下每帧预算为 8.33ms
• UIScreen.maximumFramesPerSecond 不可靠；CADisplayLink 才能反映实际情况

realitykit（非游戏 3D）：

• RealityView 的 make/update 闭包模式
• 使用 Model3D 简单显示模型
• 使用 AnchorEntity 进行 AR 锚定
• 材质选择（SimpleMaterial、PBR、Occlusion）

realitykit-ref（API）：

• 使用 RealityRenderer 对 RealityKit 内容进行自定义 Metal 渲染
• 完整的材质属性参考
• RealityView 手势集成
• RealityKit 27 新增内容：导航网格、LOD、柔和阴影、高斯泼溅、混响网格（第 10 部分）、布料模拟（ClothBodyComponent）、ComputeGraph 框架

usdkit（USD 创作，27 个版本）：

• USDStage 的打开、遍历和编辑，以及引用与组合
• 3D 资源的无障碍元数据架构
• 压缩 USDZ 导出（AOM 网格 + AVIF 纹理）
• USDStageComponent / USDPlayer RealityKit 桥接

示例调用

用户：“调整 iPad 窗口大小时，我的 MTKView 内容会被拉伸” → 参见 skills/resizable-rendering.md

用户：“通过 iPhone Mirroring 查看时，我缓存的缩略图显得模糊” → 参见 skills/resizable-rendering.md

用户：“我应该使用 MetalANGLE，还是改写为原生 Metal？” → 参见 skills/metal-migration.md

用户：“我正在将 projectM 从 OpenGL ES 移植到 iOS” → 参见 skills/metal-migration.md

用户：“如何将这个 GLSL 着色器转换为 Metal？” → 参见 skills/metal-migration-ref.md

用户：“首次设置 MTKView” → 参见 skills/metal-migration-ref.md

用户：“移植后的应用显示黑屏” → 参见 skills/metal-migration-diag.md

用户：“移植到 Metal 后性能变差了” → 参见 skills/metal-migration-diag.md

用户：“我的应用在 iPhone Pro 上卡在 60fps” → 参见 skills/display-performance.md

用户：“如何将 CADisplayLink 配置为 120Hz？” → 参见 skills/display-performance.md

用户：“我的 Metal 应用无法使用 ProMotion” → 参见 skills/display-performance.md

用户：“如何在 SwiftUI 应用中显示 3D 模型？” → 参见 skills/realitykit.md

用户：“我需要显示 USDZ 模型” → 参见 skills/realitykit.md

用户：“如何设置 RealityView？” → 参见 skills/realitykit-ref.md

用户：“我的 3D 模型没有显示在 RealityView 中” → 参见 skills/realitykit-diag.md

用户：“如何将 RealityRenderer 与 Metal 搭配使用？” → 参见 skills/realitykit-ref.md

用户：“我需要在应用中添加 AR” → 参见 skills/realitykit.md

用户：“如何用 Swift 读取和编辑 USD 文件？” → 参见 skills/usdkit.md

用户：“如何缩小 USDZ 资源，以便交付？” → 参见 skills/usdkit.md

用户：“如何为 RealityKit 场景添加寻路功能？” → 参见 skills/realitykit-ref.md（第 10 部分）

用户：“我的游戏运行一小时后帧率下降” → 参见 skills/display-performance.md（第 12 部分）

用户：“如何在 Metal 着色器中运行神经网络？” → 参见 skills/metal-migration-ref.md（第 6 部分）

用户：“将 HDR 照片绘制到 CGContext 时，画面看起来褪色了” → 参见 skills/hdr-color-ref.md

用户：“如何检查图像的 ICC 配置文件是否包含增益曲线？” → 参见 skills/hdr-color-ref.md