/axiom-graphics

name: axiom-graphics
description: Use when working with ANY GPU rendering, Metal, OpenGL migration, shaders, 3D content, RealityKit, AR, USD/USDZ files, or display performance. Covers Metal migration, shader conversion, RealityKit ECS, RealityView, USDKit, ProMotion.
license: MIT

Graphics

**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
• Rendering breaks or blurs when the window resizes or moves between screens
• 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
• Reading, editing, or exporting USD/USDZ files in Swift (USDKit)
• Adding ML to a render pipeline (MetalFX denoising, Metal tensors, neural rendering)
• Profiling long game sessions (metalperftrace, look-back traces)

Routing Logic

Metal Migration

**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

Rendering Surfaces Under Window Resizing

**Any rendering surface in a resizable window** → See skills/resizable-rendering.md

• MTKView `drawableSizeWillChange` (projection + render-target reallocation, live-resize throttling)
• CAMetalLayer manual `drawableSize`/`contentsScale` ownership
• Per-surface adaptation table: video layers, maps, charts, Canvas, web views, PDF, SpriteKit/SceneKit
• displayScale-keyed cache invalidation when a scene moves between screens (Mirroring, external display)

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

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

HDR Tone Mapping & Color

**HDR drawing and color metadata** → See skills/hdr-color-ref.md

• HDR images washed out, clipped, or dark when drawn into a `CGContext`
• Choosing a tone-mapping method (`CGContentToneMappingInfo` vs `CGToneMapping`)
• Headroom Adaptive Gain Curve metadata on ICC profiles (`OS27`)
• Persisting `CGColor` / `CGColorSpace` (`Codable` in `OS27`)

USD Authoring (USDKit) `OS27`

**USD file work in Swift** → See skills/usdkit.md

• Open, traverse, edit USD stages and prims
• References and composition
• Accessibility metadata for 3D assets
• USDZ export with mesh/texture compression
• Rendering a USD stage in RealityKit (USDStageComponent)

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? → realitykit 10. Build an AR experience? → realitykit 11. RealityView or Model3D setup? → realitykit-ref 12. 3D content not visible or not tracking? → realitykit-diag 13. Custom Metal rendering of RealityKit content? → realitykit-ref (RealityRenderer) 14. Pathfinding, LOD, soft shadows, splats, reverb meshes? → realitykit-ref (Part 10) 15. Read/edit/export a USD or USDZ file in Swift? → usdkit 16. ML in the render pipeline (denoising, Metal tensors)? → metal-migration-ref (Part 6) 17. Frame drops in long play sessions? → display-performance (Part 12) 18. HDR image looks washed out / clipped when drawn? → hdr-color-ref 19. Choosing a tone-mapping method, or reading HAGC metadata? → hdr-color-ref 20. Rendering stretches, blurs, or letterboxes when the window resizes or moves screens? → resizable-rendering 21. Building a 3D game? → Use axiom-gam