cube-vksc: Fix Windows D2D display acquisition and pipeline cache handling

[dgkoch]

Summary

• Fix inverted WinRT display acquisition condition: wsi_platform != WSI_PLATFORM_DISPLAY was backwards — the display was never acquired when using display mode. Fix to == WSI_PLATFORM_DISPLAY. Also fix typo in error message ("get acqurie" → "acquire").

• Add --native-resolution flag: Some implementations only support swapchain creation at the display's native panel resolution. When --native-resolution is specified, all available modes are enumerated and the one matching physicalResolution is selected; if none matches, falls back to mode[0] with a warning. Without the flag, mode[0] is used (default, spec-correct behaviour). If swapchain creation fails in display mode, an actionable error message directs the user to --native-resolution.

• Fix cube.pc.json: Use named flag format for colorWriteMask as required by the pcutil JSON schema (VK_COLOR_COMPONENT_*_BIT instead of "0xf"). Use "NULL" for pViewports and pScissors when those fields are dynamic state, matching the format the pcutil serializer produces for null pointers.

• Regenerate pipeline_cache.h using the VulkanSC SDK 1.0.22 emulation layer PCC.

Tested

On NVIDIA RTX 5070 with VulkanSC SDK 1.0.22:

• --wsi display --native-resolution: spinning cube visible on 1920×1200 display, on both drivers that enumerate only native modes and drivers that enumerate non-native modes that fail swapchain creation. ✓
• --wsi display without --native-resolution on an affected driver: clear error message directing the user to use --native-resolution. ✓
• --wsi file: all pixels non-zero, max 230/255. ✓
• Emulation ICD (VK_DRIVER_FILES=<vksconvk.json>): exit code 0, embedded pipeline cache works. ✓

🤖 Generated with Claude Code

[aqnuep]

Fix inverted WinRT display acquisition condition: wsi_platform != WSI_PLATFORM_DISPLAY was backwards. The display was never acquired when using display mode. Fix to == WSI_PLATFORM_DISPLAY. Also fix typo in error message ("get acqurie" → "acquire").

No question, that's clearly a bug.

Select the best display mode: The original code called vkGetDisplayModePropertiesKHR with mode_count=1, picking whichever mode the driver returned first. On some drivers/displays this yields a low-resolution mode (e.g. 1280×960) that does not support swapchain creation - the driver requires the native panel resolution. Fix: enumerate all available modes (up to 256) and select the one matching the display's native resolution; fall back to highest area then highest refresh rate.

This seems arbitrary. The driver shouldn't report display modes that is not actually supported.

Fix colorWriteMask format: Change "0xf" to the named flag string format required by the pcutil JSON schema (VK_COLOR_COMPONENT_*_BIT).

This looks like a bug in the pcutil JSON schema, as we did intend to retain the ability of the old schema allowing integer values (encoded as integer or string). We'll have to look into that.

Add placeholder viewport and scissor entries: Some PCC implementations validate that pViewports/pScissors are non-empty even when those fields are listed in pDynamicState. Add placeholder values as a workaround. Note: the PCC should not require this per the Vulkan spec and pcutil schema — this is a PCC parser bug, that we'll address but will take some time to reach public drivers.

Such PCC implementations seem to be broken, as the spec clearly states that the viewport/scissor arrays can be NULL if they are dynamic.

[aqnuep]

Actually, I looked into the history of this. Apparently the 0xf format (while allowed by the legacy invalid JSON schema), was never accepted even by the legacy parser, but the legacy generator did produce it, so I think this part is a legitimate fix for remnants of the legacy tooling.

[dgkoch]

Add placeholder viewport and scissor entries: Some PCC implementations validate that pViewports/pScissors are non-empty even when those fields are listed in pDynamicState. Add placeholder values as a workaround. Note: the PCC should not require this per the Vulkan spec and pcutil schema — this is a PCC parser bug, that we'll address but will take some time to reach public drivers.

Such PCC implementations seem to be broken, as the spec clearly states that the viewport/scissor arrays can be NULL if they are dynamic.

I investigated this more after posting (trying to fix the alleged pcc bug), and it's actually the pcutils parser that rejects it. It turns out that the arrays can be NULL, but not [] as was used here, and this is also what the json serializer would produce, so have changed that in the latest update (and it works on both native NVIDIA Vulkan SC driver and the emulation driver). Incidentally if the vksc emulator would have used pcutils instead of a custom parser, it would have caught these issues too.

[aqnuep]

I investigated this more after posting (trying to fix the alleged pcc bug), and it's actually the pcutils parser that rejects it. It turns out that the arrays can be NULL, but not [] as was used here, and this is also what the json serializer would produce, so have changed that in the latest update (and it works on both native NVIDIA Vulkan SC driver and the emulation driver). Incidentally if the vksc emulator would have used pcutils instead of a custom parser, it would have caught these issues too.

I see. Then yes, the JSON has to be fixed. Unfortunately, that JSON pre-dates the new tools and we never went there to re-validate / fix it.

Sure, the Vulkan SC Emulation PCC could use the new parser. It's one of the many good-to-have features we postponed due to other priorities. I guess we may have to revisit that.

[dgkoch]

Select the best display mode: The original code called vkGetDisplayModePropertiesKHR with mode_count=1, picking whichever mode the driver returned first. On some drivers/displays this yields a low-resolution mode (e.g. 1280×960) that does not support swapchain creation - the driver requires the native panel resolution. Fix: enumerate all available modes (up to 256) and select the one matching the display's native resolution; fall back to highest area then highest refresh rate.

This seems arbitrary. The driver shouldn't report display modes that is not actually supported.

Fair. However, our direct display implementation has behaved that way for Vulkan (and now Vulkan SC) for at least several years, so while I'll look into improving it, all of our shipping drivers behave this way today. That said the heuristic was a bit janky, so I've just replaced it with an explicit --native-resolution option.

[aqnuep]

Otherwise this seems reasonable now.

[dgkoch]

Updated since last review:

• --native-resolution now picks the highest refresh rate at native panel resolution rather than the first enumerated match. Testing on a 3440×1440 display showed that only the 165 Hz mode (the highest native rate) succeeds for swapchain creation — other rates at the same resolution fail. Picking the highest rate is more reliable across displays.

• Swapchain error message gated on display WSI (addressing inline comment): the --native-resolution hint in the vkCreateSwapchainKHR failure path is now only shown when wsi_platform == WSI_PLATFORM_DISPLAY.

• Code review fixes: merged the double mode enumeration into a single pass; added mode_props = {0} initialisation; guarded against unsigned underflow in the --refresh-rate tolerance check (req - 500 when req < 500); guarded against UB when a negative value is passed to --refresh-rate.

Tested on both a 1920×1200 and a 3440×1440 display with --native-resolution. Both work correctly.

🤖 Generated with Claude Code

[dgkoch]

Updated since last review:

Restructured into two commits:

• Commit 1 (bf73ef61): uncontroversial bug fixes only — WinRT acquire condition, typo, vkCreateSwapchainKHR assert→error exit, (int32_t) casts, cube.pc.json fixes, pipeline_cache.h regen.
• Commit 2 (effb2d40): --native-resolution flag.

--mode-index removed — was a debugging aid, not appropriate for the sample.

--native-resolution now picks the highest refresh rate at native panel resolution. Testing showed that on a 3440×1440 display only the 165 Hz mode (the highest rate at native resolution) succeeds for swapchain creation — other rates at the same resolution fail. Picking highest rate is more reliable across displays.

vkCreateSwapchainKHR error message now gated on display WSI as requested, so non-display platforms get the generic message.

🤖 Generated with Claude Code