Back to Details

axiom-ios-graphics

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

iOS Graphics Router

iOS Graphics Router

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 → 
/skill axiom-metal-migration
  • Translation layer vs native rewrite decision
  • Project assessment and migration planning
  • Anti-patterns and common mistakes
  • Pressure scenarios for deadline resistance
API reference & conversion → 
/skill axiom-metal-migration-ref
  • 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 → 
/skill axiom-metal-migration-diag
  • Black screen after porting
  • Shader compilation errors
  • Wrong colors or coordinate systems
  • Performance regressions
  • Time-cost analysis per diagnostic path
策略决策 → 
/skill axiom-metal-migration
  • 翻译层与原生重写的决策
  • 项目评估与迁移规划
  • 反模式与常见错误
  • 截止日期压力下的应对方案
API参考与转换 → 
/skill axiom-metal-migration-ref
  • GLSL → MSL着色器转换表
  • HLSL → MSL着色器转换表
  • GL/D3D API → Metal API等效对照表
  • MTKView设置、渲染管线、计算着色器
  • 完整的WWDC代码示例
诊断 → 
/skill axiom-metal-migration-diag
  • 移植后出现黑屏
  • 着色器编译错误
  • 颜色或坐标系错误
  • 性能退化
  • 各诊断路径的时间成本分析

Display Performance

显示性能

Frame rate & render loops → 
/skill axiom-display-performance
  • 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
帧率与渲染循环 → 
/skill axiom-display-performance
  • 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 ios-games router instead.
Architecture, ECS, and best practices → 
/skill axiom-realitykit
  • Entity-Component-System architecture
  • SwiftUI integration: RealityView, Model3D, attachments
  • AR on iOS: AnchorEntity types, SpatialTrackingSession
  • Materials, physics, interaction
  • Performance optimization
API reference → 
/skill axiom-realitykit-ref
  • Complete component catalog
  • RealityView and Model3D API
  • Material system (PBR, Unlit, Occlusion, Custom)
  • RealityRenderer (Metal integration)
Troubleshooting → 
/skill axiom-realitykit-diag
  • Entity not visible, anchor not tracking
  • Gesture not responding, performance issues
  • Material problems, physics issues
对于非游戏类SwiftUI应用中的3D内容、AR体验和空间计算，请使用RealityKit技能。针对游戏特定的RealityKit模式，请改用ios-games路由。
架构、ECS与最佳实践 → 
/skill axiom-realitykit
  • 实体-组件-系统（ECS）架构
  • SwiftUI集成：RealityView、Model3D、附件
  • iOS上的AR：AnchorEntity类型、SpatialTrackingSession
  • 材质、物理效果、交互
  • 性能优化
API参考 → 
/skill axiom-realitykit-ref
  • 完整的组件目录
  • RealityView与Model3D API
  • 材质系统（PBR、无光照、遮挡、自定义）
  • RealityRenderer（Metal集成）
故障排查 → 
/skill axiom-realitykit-diag
  • 实体不可见、锚点未跟踪
  • 手势无响应、性能问题
  • 材质问题、物理效果问题

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 ios-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游戏？ → 改用ios-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分钟以上）
  • 用于变量检查的着色器调试器
  • 用于API误用检测的Metal验证层
  • 性能退化诊断
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）:
  • 用于自定义Metal渲染RealityKit内容的RealityRenderer
  • 完整的材质属性参考
  • RealityView手势集成

Example Invocations

调用示例

User: "Should I use MetalANGLE or rewrite in native Metal?" → Invoke: 
/skill axiom-metal-migration
User: "I'm porting projectM from OpenGL ES to iOS" → Invoke: 
/skill axiom-metal-migration
User: "How do I convert this GLSL shader to Metal?" → Invoke: 
/skill axiom-metal-migration-ref
User: "Setting up MTKView for the first time" → Invoke: 
/skill axiom-metal-migration-ref
User: "My ported app shows a black screen" → Invoke: 
/skill axiom-metal-migration-diag
User: "Performance is worse after porting to Metal" → Invoke: 
/skill axiom-metal-migration-diag
User: "My app is stuck at 60fps on iPhone Pro" → Invoke: 
/skill axiom-display-performance
User: "How do I configure CADisplayLink for 120Hz?" → Invoke: 
/skill axiom-display-performance
User: "ProMotion not working in my Metal app" → Invoke: 
/skill axiom-display-performance
User: "How do I show a 3D model in my SwiftUI app?" → Invoke: 
/skill axiom-realitykit
User: "I need to display a USDZ model" → Invoke: 
/skill axiom-realitykit
User: "How do I set up RealityView?" → Invoke: 
/skill axiom-realitykit-ref
User: "My 3D model isn't showing in RealityView" → Invoke: 
/skill axiom-realitykit-diag
User: "How do I use RealityRenderer with Metal?" → Invoke: 
/skill axiom-realitykit-ref
User: "I need AR in my app" → Invoke: 
/skill axiom-realitykit
用户："我应该用MetalANGLE还是原生重写Metal？" → 调用：
/skill axiom-metal-migration
用户："我正在将projectM从OpenGL ES移植到iOS" → 调用：
/skill axiom-metal-migration
用户："如何将这个GLSL着色器转换为Metal？" → 调用：
/skill axiom-metal-migration-ref
用户："首次设置MTKView" → 调用：
/skill axiom-metal-migration-ref
用户："我移植后的应用显示黑屏" → 调用：
/skill axiom-metal-migration-diag
用户："移植到Metal后性能下降" → 调用：
/skill axiom-metal-migration-diag
用户："我的应用在iPhone Pro上帧率卡在60fps" → 调用：
/skill axiom-display-performance
用户："如何配置CADisplayLink以支持120Hz？" → 调用：
/skill axiom-display-performance
用户："我的Metal应用中ProMotion无法工作" → 调用：
/skill axiom-display-performance
用户："如何在我的SwiftUI应用中显示3D模型？" → 调用：
/skill axiom-realitykit
用户："我需要显示USDZ模型" → 调用：
/skill axiom-realitykit
用户："如何设置RealityView？" → 调用：
/skill axiom-realitykit-ref
用户："我的3D模型在RealityView中不显示" → 调用：
/skill axiom-realitykit-diag
用户："如何结合Metal使用RealityRenderer？" → 调用：
/skill axiom-realitykit-ref
用户："我的应用需要AR功能" → 调用：
/skill axiom-realitykit