| name | debugging-rendering-issues |
| description | ALWAYS use when a user porting a game to Metal reports a rendering issue — blank screen, wrong output, or anything that looks incorrect on Metal vs. the source platform. Covers black screen, missing geometry, wrong colors, gamma/sRGB problems, texture artifacts, z-fighting, alpha blending, flickering, visual corruption, and upside-down/mirrored geometry. Works with or without a GPU trace. Do NOT trigger when the user just wants to inspect an existing .gputrace. |
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.
Diagnostic Strategy
- Gather context to resolve ambiguity
- Match symptom using the router below — diagnose directly from this file
- Tiered elimination — only if the symptom is still ambiguous or the router's candidate was ruled out, load a reference file (see Fallback section at end)
After finding the cause: If a GPU trace is available, use the using-gpudebug skill to confirm the diagnosis before reading or changing code. Then search the developer's codebase for the relevant code and suggest or implement the specific fix.
Symptom Router
Match the symptom to the most likely cause. The gotchas column contains non-obvious traps — check these even when you're confident in the diagnosis.
| Symptom | Cause | Gotchas |
|---|
| Clear color visible, no geometry | Viewport zero-size, culling/winding, or depth state | Reversed depth: clear value + compare function must change together |
| Partial corruption each frame | Store action .dontCare | With MSAA, resolve texture + resolve store action both required |
| Flickering correct/corrupt | Load action .dontCare (TBDR), store action, buffering race, or Metal 4 barrier missing MTL4VisibilityOptionDevice | Worse at higher frame rates = buffering race, not static misconfiguration |
| Colors washed out / low contrast | sRGB pixel format missing | GL_FRAMEBUFFER_SRGB toggle → Metal pixel format. newTextureViewWithPixelFormat: for dual-access |
| Colors oversaturated / too dark | Double sRGB conversion or no gamma at all | Both _sRGB format AND manual pow(color, 1/2.2) = double-encode |
| Background color wrong shade | sRGB clear color | sRGB render targets interpret clear color in linear space |
| Wrong or garbled textures | Pixel format translation | BGRA vs RGBA channel order; MTLTextureSwizzleChannels |
| Alpha blending wrong / dark halos | Premultiplied vs straight alpha | CoreAnimation expects premultiplied alpha on the drawable. D3D blend enum integers differ from Metal — don't cast directly |
| Z-fighting everywhere | Reversed depth not fully ported | Clear value + compare function must change together. Depth bias units differ across APIs and between D24/D32F formats — rescale needed |
| Objects wrong depth order | Depth clear + compare mismatch | |
| Objects appear/disappear | Buffering race on dynamic buffers | |
| Ray tracing all-miss (sky only) | Resource residency missing | Binding ≠ residency. Metal 4: no useResource/useHeap — use MTLResidencySet on command queue or command buffer. After TLAS rebuild, residency set must be updated and re-committed |
| Wrong texture on surface | Resource binding index mismatch |
Metal 4
Binding — MTL4ArgumentTable with fixed slot limits (31 buffers, 128 textures, 16 samplers). Set on encoder via setArgumentTable:. initializeBindings defaults NO — unset slots are garbage, not zero.
Residency — All GPU-accessed resources must be in a committed MTLResidencySet (on queue or command buffer). Binding does NOT grant residency — non-resident reads return zeros silently. beginCommandBufferWithAllocator: clears prior useResidencySet: calls — must re-associate every frame. After TLAS rebuild, residency set must be updated.
Barriers — MTL4VisibilityOptionNone = execution order only, no cache flush. D3D12 transitions implicitly flush. Use MTL4VisibilityOptionDevice for data dependencies.
Other — D24_UNORM_S8_UINT not universally supported on Apple GPUs; default to Depth32Float_Stencil8. D3D COLOR_WRITE_ENABLE / Vulkan VkColorComponentFlags to MTLColorWriteMask — bit layout reversed, naive cast drops channels. Metal has no subpasses.
Fallback: Tiered Elimination
Only when the symptom router above doesn't resolve the issue. Load one tier reference file at a time.
- Tier 1 — 7 instant checks:
references/tier-1-instant-checks.md
- Tier 2 — 14 state checks:
references/tier-2-state-inspection.md
- Tier 3 — 7 data checks:
references/tier-3-data-inspection.md
If all tiers are exhausted, review shader source and verify transform math.
