iOS Graphics Router

iOS Graphics Router

You MUST use this skill for ANY GPU rendering, graphics programming, or display performance work.

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

Routing Logic

Metal Migration

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

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, Adaptive Power)
• Frame budget math (8.33ms for 120Hz)
• Measuring actual vs reported frame rate

Decision Tree

User asks about GPU/​graphics/​Metal/​display
  ├─ "Should I use translation layer or native?" → metal-migration
  ├─ "How do I migrate/​port/​convert?" → metal-migration
  ├─ "Show me the API/​code/​example" → metal-migration-ref
  ├─ "How do I set up MTKView?" → metal-migration-ref
  ├─ "Something's broken/​wrong/​slow" → metal-migration-diag
  ├─ "Stuck at 60fps on ProMotion" → display-performance
  ├─ "CADisplayLink setup/​configuration" → display-performance
  ├─ "Variable refresh rate issues" → display-performance
  └─ "Frame rate not what I expect" → display-performance

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

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