[brycekottke]

video_core: diagnostics for task/mesh skips and null TIC descriptors

• I have read and followed the Contribution Guidelines.
• I have read and followed the AI Policy.
• I have read and followed the Coding Guidelines to the best of my ability.
• I have put [HUMANMADE] in the title if the pr was human-made

Summary

While debugging a black screen at the cutscene-to-gameplay transition in
Ocarina of Time (NUP, 0400486024DEC000) on Intel Xe-LP, three places hid the
root cause silently. This PR adds diagnostics for them:

1. vk_pipeline_cache.cpp: CreateGraphicsPipeline returned nullptr for
   task/mesh pipelines on devices without VK_EXT_mesh_shader without any log
   (a silent return nullptr), so affected draws only showed up as
   "Draw skipped ... miss=creation-failed". It now logs which stage and
   pipeline hash was skipped and why.
2. vulkan_device.cpp: one line at device init reporting VK_EXT_mesh_shader
   availability (extension loaded, taskShader/meshShader feature bits, final
   enabled state), so "does this device take the mesh path" is answerable
   from a log alone. ANV only enables task/mesh on Arc-class hardware; on
   Xe-LP the extension is advertised by other vendors' stacks but silently
   absent here, which cost a full debugging session to establish.
3. Null TIC diagnostics: a format-0 TIC decodes to address 0, 1x1x1 — a
   benign placeholder the game binds to handle 0 (the lookup already falls
   back to A8B8G8R8). shader_environment.cpp logs the raw words of such
   TICs bound in shaders (handle included), and image_info.cpp logs the
   raw words of format-0 TICs entering the texture cache, deduplicated per
   descriptor. This distinguishes the placeholder from a real unmapped NX2
   format, which would otherwise look identical in the format_lookup_table
   assert.

Root cause of the black screen itself (for the record): the title's gameplay
scene passes use NVN task + mesh programs, which are skipped entirely on
devices without VK_EXT_mesh_shader; the offscreen scene targets stay empty.
Confirmed by running the same title on llvmpipe (supports task/mesh in
software): no skips, no black screen. This is a hardware support gap, not an
emulator bug — a compute lowering for task/mesh programs is the eventual
fix, and NX2_NOTES row 89 records the ISBE layout such a lowering needs.
These diagnostics exist so the next person reaches that conclusion in
minutes instead of hours.

This PR was written with AI assistance (agent-assisted debugging and patch
authoring), reviewed and tested by a human.

Type of change

• [] Bug fix
• Game compatibility / game-support
• Performance
• New feature
• Refactor / cleanup
• CI / build
• Documentation

Related issues

None found; this documents the diagnosis of the Xe-LP black screen.

Testing

• Tested on Windows
• Tested on Linux
• Tested on macOS
• Tested on NVIDIA
• Tested on AMD
• Tested on Intel

Games tested:

The Legend of Zelda: Ocarina of Time (NUP) — reaches gameplay on llvmpipe
with no mesh skips; on Intel Xe-LP the new warnings fire exactly once per
placeholder descriptor and once per skipped task/mesh pipeline.

Checklist

• I built it locally and it compiles without new warnings
• I did not add any copyrighted game data, keys or firmware
• Docs updated if needed
• I added AI Disclosure if one was used

Screenshots / logs

Before (Xe-LP, gameplay transition):

Draw skipped (no pipeline): vs=0x... ps=0x... rt0=0x... 128x128 miss=creation-failed
(repeated, no reason given; screen stays black)

After:

Skipping task shader pipeline 0x46cc6aaba42f700f: the device has no VK_EXT_mesh_shader
VK_EXT_mesh_shader: extension NOT loaded taskShader=0 meshShader=0 -> enabled=false
TIC with INVALID format bound to handle 0x0: raw={...} addr=0x0 1x1x1 type=0 hv=3
(warning, once per distinct placeholder descriptor)

[github-actions]

Retargeted to nx2-experimental for pre-build testing. It will be promoted to nx2 after validation.

[brycekottke]

Hope this helps a bit. while i was debugging a black screen in Ocarina of Time on a X1 thinkpad (i know, not much of a graphics card. Intel Xe-LP) i found a few places failing silently. this PR just adds log lines for skipped task/mesh pipelines, VK_EXT_mesh_shader availability at device init, and placeholder TIC descriptors. there's more details in the PR description. anyway. great work y'all! very cool project.

[aidankinzett]

Thanks for the write-up. The root-cause analysis of the Xe-LP black screen (no VK_EXT_mesh_shader, so task/mesh draws are skipped) is useful, and logging it is a good idea.

Blocking

• This PR changes the Discord invite link in README.md and CONTRIBUTING.md (discord.gg/jCCZ58VExk to discord.gg/XkS5NVPTUY)

Suggestions

• The null-TIC log in shader_environment.cpp is LOG_WARNING even though the comment calls the case benign, and it fires once per handle per shader environment, so it will repeat for every pipeline that touches the placeholder. LOG_DEBUG or a once-per-raw-words guard would keep logs readable.
• In image_info.cpp the function-local static std::vector is unsynchronised, unbounded and searched linearly. A mutex-guarded std::set, or a simple once-only flag, would be safer, and the file needs , and .
• {:#016x} includes 0x in the width, so the pipeline hash prints with 14 digits. {:016x} would be consistent.

Nits

• Please drop the unrelated blank-line removals in vk_pipeline_cache.cpp and vulkan_device.cpp.
• A few new log lines are over 100 columns, and the continuation lines in shader_environment.cpp are misaligned. Running clang-format would fix both.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 3bc7475d-8829-4bef-be11-e8cae6d5c82e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[brycekottke]

Thanks for the review @aidankinzett. All should be addressed and force-pushed (branch re-targeted to nx2-experimental per the bot, rebased on it, now merging clean):

• Discord links: Should be gone. My branch was based on a commit predating [HUMANMADE] Fix discord invite link in docs #752, so the link change was only appearing in the diff incidentally. Rebased onto current nx2-experimental, which should already have the upstream fix.
• Null-TIC log spam: the per-descriptor std::vector dedup in image_info.cpp is replaced with a once-per-process static std::atomic<bool> guard, and the shader_environment.cpp one got the same. I kept them at WARNING with the once-guard rather than dropping to DEBUG, so a real unexpected format-0 TIC is still visible in a default run. I'd be more than happy to move to DEBUG if you'd prefer.
• image_info.cpp includes: <algorithm>/<array>/<vector> removed along with the vector, <atomic> added.
• Format string: {:016x} everywhere now (dropped the redundant 0x from the width spec).
• Whitespace/formatting: unrelated blank-line removals restored (they no longer appear in the diff), misaligned continuations fixed, and all new log lines wrapped under 100 columns.

One change in scope on the rebase: this PR originally logged the task/mesh pipeline skip on devices without VK_EXT_mesh_shader, but nx2-experimental now routes task/mesh through the compute-based mesh emulation with its own init log, so I dropped that hunk as obsolete rather than duplicating/conflicting with it. What remains is the VK_EXT_mesh_shader availability line at device init (still useful for answering "did this device take the mesh/emulation path" from a log alone) and the null/placeholder-TIC diagnostics in shader_environment.cpp and image_info.cpp.

Also worth noting for anyone following the OOT black-screen thread in the PR description: the Xe-LP machine that motivated this now gets task/mesh through the emulation path instead of skipping, so the original skip-the-pipeline failure mode shouldn't occur on current nx2-experimental.