iOS Graphics Router

You MUST use this skill for ANY GPU rendering, graphics programming, 3D content display, 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

• 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

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, Thermal, Adaptive Power)

• Frame budget math (8.33ms for 120Hz)

• Measuring actual vs reported frame rate

RealityKit (Non-Game 3D Content)

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

Decision Tree

• Translation layer vs native rewrite? → metal-migration

• Porting / converting code to Metal? → metal-migration

• API reference / shader conversion tables? → metal-migration-ref

• MTKView / render pipeline setup? → metal-migration-ref

• Something broken after porting (black screen, wrong colors)? → metal-migration-diag

• Stuck at 60fps on ProMotion device? → display-performance

• CADisplayLink / variable refresh rate? → display-performance

• Frame rate not as expected? → display-performance

• Display a 3D model in SwiftUI? → axiom-realitykit

• Build an AR experience? → axiom-realitykit

• RealityView or Model3D setup? → axiom-realitykit-ref

• 3D content not visible or not tracking? → axiom-realitykit-diag

• Custom Metal rendering of RealityKit content? → axiom-realitykit-ref (RealityRenderer)

• Building a 3D game? → Use ios-games router instead

Anti-Rationalization

Thought Reality

"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.

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

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