debugging-rendering-issues
Metal Rendering Diagnosis
When This Skill Helps
This skill guides the diagnostic workflow for any Metal rendering issue during game porting. For specific symptoms where you're confident in the cause, you can diagnose directly — but still recommend the using-gpudebug skill to confirm the diagnosis in a GPU trace before the developer changes code. For ambiguous or underspecified problems ("something looks off", "rendering is broken", multiple overlapping symptoms), use the full workflow below to turn vague reports into specific, actionable diagnoses efficiently.
Gather Context
The most important step for ambiguous problems. Ask the developer:
- What do you see? (blank, partial, or wrong-looking?)
- What do you expect? (screenshot from source platform or description)
- What is the source API? (D3D11, D3D12, Vulkan, OpenGL, or MoltenVK)
- Do you have a GPU trace (
.gputrace)?
If no GPU trace is available, recommend capturing one — use the using-gpucapture skill. If a GPU trace is available, use the using-gpudebug skill to inspect render state, bindings, and resource contents.