Back to Details

axiom-graphics

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Graphics

图形开发

You MUST use this skill for ANY GPU rendering, graphics programming, 3D content display, or display performance work.
任何涉及GPU渲染、图形编程、3D内容显示或显示性能优化的工作，都必须使用本技能。

When to Use

使用场景

Use this router when:
  • Porting OpenGL/OpenGL ES code to Metal
  • Porting DirectX code to Metal
  • Converting GLSL/HLSL shaders to Metal Shading Language
  • Setting up MTKView or CAMetalLayer
  • Debugging GPU rendering issues (black screen, wrong colors, crashes)
  • Evaluating translation layers (MetalANGLE, MoltenVK)
  • Optimizing GPU performance or fixing thermal throttling
  • App stuck at 60fps on ProMotion device
  • Configuring CADisplayLink or render loops
  • Variable refresh rate display issues
  • Displaying 3D content in a non-game SwiftUI app
  • Building AR experiences with RealityKit
  • Using RealityView or Model3D in SwiftUI
  • Spatial computing or visionOS 3D content
在以下场景中使用本路由：
  • 将OpenGL/OpenGL ES代码移植到Metal
  • 将DirectX代码移植到Metal
  • 将GLSL/HLSL着色器转换为Metal Shading Language
  • 设置MTKView或CAMetalLayer
  • 调试GPU渲染问题（黑屏、颜色异常、崩溃）
  • 评估转换层（MetalANGLE、MoltenVK）
  • 优化GPU性能或解决热节流问题
  • 应用在ProMotion设备上帧率卡在60fps
  • 配置CADisplayLink或渲染循环
  • 可变刷新率显示问题
  • 在非游戏类SwiftUI应用中显示3D内容
  • 使用RealityKit构建AR体验
  • 在SwiftUI中使用RealityView或Model3D
  • 空间计算或visionOS 3D内容

Routing Logic

路由逻辑

Metal Migration

Metal迁移

Strategy decisions → See skills/metal-migration.md
  • Translation layer vs native rewrite decision
  • Project assessment and migration planning
  • Anti-patterns and common mistakes
  • Pressure scenarios for deadline resistance
API reference & conversion → See skills/metal-migration-ref.md
  • GLSL → MSL shader conversion tables
  • HLSL → MSL shader conversion tables
  • GL/D3D API → Metal API equivalents
  • MTKView setup, render pipelines, compute shaders
  • Complete WWDC code examples
Diagnostics → See skills/metal-migration-diag.md
  • Black screen after porting
  • Shader compilation errors
  • Wrong colors or coordinate systems
  • Performance regressions
  • Time-cost analysis per diagnostic path
策略决策 → 参考 skills/metal-migration.md
  • 转换层 vs 原生重写的决策
  • 项目评估与迁移规划
  • 反模式与常见错误
  • deadline压力下的应对方案
API参考与转换 → 参考 skills/metal-migration-ref.md
  • GLSL → MSL着色器转换对照表
  • HLSL → MSL着色器转换对照表
  • GL/D3D API → Metal API等效映射
  • MTKView设置、渲染管线、计算着色器
  • 完整WWDC代码示例
诊断排查 → 参考 skills/metal-migration-diag.md
  • 移植后黑屏问题
  • 着色器编译错误
  • 颜色或坐标系异常
  • 性能退化
  • 各诊断路径的时间成本分析

Display Performance

显示性能

Frame rate & render loops → See skills/display-performance.md
  • App stuck at 60fps on ProMotion (120Hz) device
  • MTKView or CADisplayLink configuration
  • Variable refresh rate optimization
  • System caps (Low Power Mode, Limit Frame Rate, Thermal, Adaptive Power)
  • Frame budget math (8.33ms for 120Hz)
  • Measuring actual vs reported frame rate
帧率与渲染循环 → 参考 skills/display-performance.md
  • 应用在ProMotion（120Hz）设备上帧率卡在60fps
  • MTKView或CADisplayLink配置
  • 可变刷新率优化
  • 系统限制（低电量模式、帧率限制、热节流、自适应功耗）
  • 帧预算计算（120Hz对应8.33ms）
  • 实际帧率与上报帧率的测量

RealityKit (Non-Game 3D Content)

RealityKit（非游戏类3D内容）

For 3D content in non-game SwiftUI apps, AR experiences, and spatial computing, use the RealityKit skills. For game-specific RealityKit patterns, use the axiom-games router instead.
Architecture, ECS, and best practices → See skills/realitykit.md
  • Entity-Component-System architecture
  • SwiftUI integration: RealityView, Model3D, attachments
  • AR on iOS: AnchorEntity types, SpatialTrackingSession
  • Materials, physics, interaction
  • Performance optimization
API reference → See skills/realitykit-ref.md
  • Complete component catalog
  • RealityView and Model3D API
  • Material system (PBR, Unlit, Occlusion, Custom)
  • RealityRenderer (Metal integration)
Troubleshooting → See skills/realitykit-diag.md
  • Entity not visible, anchor not tracking
  • Gesture not responding, performance issues
  • Material problems, physics issues
针对非游戏类SwiftUI应用中的3D内容、AR体验及空间计算场景，使用RealityKit技能。游戏专属的RealityKit模式，请使用axiom-games路由。
架构、ECS与最佳实践 → 参考 skills/realitykit.md
  • 实体-组件-系统（ECS）架构
  • SwiftUI集成：RealityView、Model3D、附件
  • iOS平台AR：AnchorEntity类型、SpatialTrackingSession
  • 材质、物理、交互
  • 性能优化
API参考 → 参考 skills/realitykit-ref.md
  • 完整组件目录
  • RealityView与Model3D API
  • 材质系统（PBR、无光照、遮挡、自定义）
  • RealityRenderer（Metal集成）
故障排查 → 参考 skills/realitykit-diag.md
  • 实体不可见、锚点追踪失效
  • 手势无响应、性能问题
  • 材质异常、物理问题

Decision Tree

决策树

  1. Translation layer vs native rewrite? → metal-migration
  2. Porting / converting code to Metal? → metal-migration
  3. API reference / shader conversion tables? → metal-migration-ref
  4. MTKView / render pipeline setup? → metal-migration-ref
  5. Something broken after porting (black screen, wrong colors)? → metal-migration-diag
  6. Stuck at 60fps on ProMotion device? → display-performance
  7. CADisplayLink / variable refresh rate? → display-performance
  8. Frame rate not as expected? → display-performance
  9. Display a 3D model in SwiftUI? → axiom-realitykit
  10. Build an AR experience? → axiom-realitykit
  11. RealityView or Model3D setup? → axiom-realitykit-ref
  12. 3D content not visible or not tracking? → axiom-realitykit-diag
  13. Custom Metal rendering of RealityKit content? → axiom-realitykit-ref (RealityRenderer)
  14. Building a 3D game? → Use axiom-games router instead
  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模型？ → axiom-realitykit
  10. 构建AR体验？ → axiom-realitykit
  11. RealityView或Model3D设置？ → axiom-realitykit-ref
  12. 3D内容不可见或追踪失效？ → axiom-realitykit-diag
  13. 自定义Metal渲染RealityKit内容？ → axiom-realitykit-ref（RealityRenderer）
  14. 构建3D游戏？ → 请使用axiom-games路由

Anti-Rationalization

常见误区纠正

ThoughtReality
"I'll just translate the shaders line by line"GLSL→MSL has type, coordinate, and precision differences. metal-migration-ref has conversion tables.
"MetalANGLE will handle everything"Translation layers have significant limitations for production. metal-migration evaluates the trade-offs.
"It's just a black screen, probably a simple bug"Black screen has 6 distinct causes. metal-migration-diag diagnoses in 5 min vs 30+ min.
"My app runs at 60fps, that's fine"ProMotion devices support 120Hz. display-performance configures the correct frame rate.
"I'll just use SceneKit for the 3D model"SceneKit is soft-deprecated. RealityView and Model3D are the modern path. axiom-realitykit covers SwiftUI integration.
"I don't need ECS for one 3D model"Model3D shows one model with zero ECS. RealityView scales to complex scenes. axiom-realitykit shows both paths.
错误想法实际情况
"我直接逐行翻译着色器就行"GLSL→MSL存在类型、坐标系和精度差异，metal-migration-ref提供了转换对照表。
"MetalANGLE能处理所有问题"转换层在生产环境中有明显局限性，metal-migration会评估其利弊。
"只是黑屏而已，应该是小bug"黑屏有6种不同成因，metal-migration-diag能在5分钟内完成诊断，而非耗时30分钟以上的猜测。
"我的应用跑60fps就够了"ProMotion设备支持120Hz，display-performance可配置正确帧率。
"我用SceneKit来展示3D模型就行"SceneKit已处于软废弃状态，RealityView和Model3D是现代解决方案，axiom-realitykit涵盖SwiftUI集成内容。
"单个3D模型不需要ECS"Model3D展示单个模型无需ECS，RealityView可扩展到复杂场景，axiom-realitykit展示了两种实现路径。

Critical Patterns

核心模式

metal-migration:
  • Translation layer (MetalANGLE) for quick demos
  • Native Metal rewrite for production
  • State management differences (GL stateful → Metal explicit)
  • Coordinate system gotchas (Y-flip, NDC differences)
metal-migration-ref:
  • Complete shader type mappings
  • API equivalent tables
  • MTKView vs CAMetalLayer decision
  • Render pipeline setup patterns
metal-migration-diag:
  • GPU Frame Capture workflow (2-5 min vs 30+ min guessing)
  • Shader debugger for variable inspection
  • Metal validation layer for API misuse
  • Performance regression diagnosis
display-performance:
  • MTKView defaults to 60fps (must set preferredFramesPerSecond = 120)
  • CADisplayLink preferredFrameRateRange for explicit rate control
  • System caps: Low Power Mode, Limit Frame Rate, Thermal, Adaptive Power (iOS 26)
  • 8.33ms frame budget for 120Hz
  • UIScreen.maximumFramesPerSecond lies; CADisplayLink tells truth
axiom-realitykit (non-game 3D):
  • RealityView make/update closure pattern
  • Model3D for simple model display
  • AR anchoring with AnchorEntity
  • Material selection (SimpleMaterial, PBR, Occlusion)
axiom-realitykit-ref (API):
  • RealityRenderer for custom Metal rendering of RealityKit content
  • Complete material property reference
  • RealityView gesture integration
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能提供真实帧率
axiom-realitykit（非游戏类3D）:
  • RealityView的make/update闭包模式
  • Model3D用于简单模型展示
  • 基于AnchorEntity的AR锚定
  • 材质选择（SimpleMaterial、PBR、遮挡）
axiom-realitykit-ref（API）:
  • 使用RealityRenderer自定义Metal渲染RealityKit内容
  • 完整材质属性参考
  • RealityView手势集成

Example Invocations

调用示例

User: "Should I use MetalANGLE or rewrite in native Metal?" → See 
skills/metal-migration.md
User: "I'm porting projectM from OpenGL ES to iOS" → See 
skills/metal-migration.md
User: "How do I convert this GLSL shader to Metal?" → See 
skills/metal-migration-ref.md
User: "Setting up MTKView for the first time" → See 
skills/metal-migration-ref.md
User: "My ported app shows a black screen" → See 
skills/metal-migration-diag.md
User: "Performance is worse after porting to Metal" → See 
skills/metal-migration-diag.md
User: "My app is stuck at 60fps on iPhone Pro" → See 
skills/display-performance.md
User: "How do I configure CADisplayLink for 120Hz?" → See 
skills/display-performance.md
User: "ProMotion not working in my Metal app" → See 
skills/display-performance.md
User: "How do I show a 3D model in my SwiftUI app?" → See 
skills/realitykit.md
User: "I need to display a USDZ model" → See 
skills/realitykit.md
User: "How do I set up RealityView?" → See 
skills/realitykit-ref.md
User: "My 3D model isn't showing in RealityView" → See 
skills/realitykit-diag.md
User: "How do I use RealityRenderer with Metal?" → See 
skills/realitykit-ref.md
User: "I need AR in my app" → See 
skills/realitykit.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