Windows x64: @perryts/webgpu builds & presents frames but window stays gray (+ link/manifest/arg-passing fixes)

[proggeramlug]

Summary

A community user (@nikolas_beckel) got a Perry @perryts/webgpu program building and running on Windows x64 (with AI assistance, zero Rust experience). It opens a window and wgpu presents ~15 frames successfully, but the rendered frames never show up in the window — it stays gray. Several patches were needed along the way to get that far. This issue tracks debugging the Windows path so it works out of the box.

Environment

• Platform: Windows x64
• Package: @perryts/webgpu (unless noted)
• Backends in play: wgpu d3d12 / vulkan / gl

Findings / patches the user had to apply

1. Manifest lib name mismatch. The manifest "windows" lib is declared as libperry_ext_webgpu.a, but on Windows it actually builds as perry_ext_webgpu.lib. The manifest/link logic should resolve the platform-correct name.

2. Missing Windows link libs. Windows link needs d3dcompiler + opengl32, otherwise LNK2019 unresolved externals on wgl* / D3DCompile (pulled in by wgpu's d3d12/gl backends).

3. request_adapter ignores the surface. request_adapter uses compatible_surface: None, which makes surfaceConfigure fail on d3d12/vulkan ("queue family" error). Picking the adapter against the surface fixed it.

4. textureCreateView(tex) without a descriptor crashes in read_string. Passing all args explicitly worked around it — suggests Perry may be passing garbage for omitted/optional args on win64 (calling-convention / default-arg lowering bug?).

5. Frames present but never display (main wall). After the above, wgpu presents 15 frames fine, but they never appear in the window — it stays gray. Likely a surface present / swapchain / window-compositing issue on Windows.

Suspected Perry-side bugs (vs. just wgpu usage)

• Item 4 strongly smells like a Perry codegen/ABI issue: omitted optional args producing garbage on win64. Worth reproducing in isolation (a function with a trailing optional/object param called with the arg omitted).
• Item 1 is a manifest/link-name resolution bug specific to Windows.

Tasks

• Reproduce on a Windows x64 box.
• Fix manifest lib-name resolution (lib*.a vs *.lib) for Windows.
• Add d3dcompiler + opengl32 to the Windows link line for the webgpu ext (and audit other exts that pull wgpu backends).
• Make request_adapter pass compatible_surface so d3d12/vulkan surfaceConfigure succeeds.
• Root-cause the textureCreateView omitted-arg crash — minimal repro of omitted optional args on win64; fix in codegen if confirmed.
• Investigate the gray-window / frames-never-presented issue (surface present / swapchain / compositing on Windows).

Credit

Reported by @nikolas_beckel on X. Thanks for the detailed write-up and patches!

[proggeramlug]

All five items are now fixed, verified on Windows 11 x64 hardware (d3d12), and shipped:

#	Item	Fix	Shipped in
1	Manifest lib*.a vs *.lib	lib_name_variants probes MSVC-translated names	perry #5814 (merged)
2	d3dcompiler/opengl32 LNK2019	Perry auto-appends for declared d3d12/vulkan backends and the webgpu manifest declares them	perry #5814 + @perryts/webgpu@0.3.0
3	request_adapter ignores surface	requestAdapter(compatibleSurface?) passes compatible_surface; docs/example switched to surface-first order	@perryts/webgpu@0.3.0
4	textureCreateView(tex) crash	Perry padded omitted trailing native-lib args with typed null/zero sentinels (was uninitialized-register garbage into read_string)	perry #5814 (merged)
5	Gray window	Root cause: swapchain built while the view HWND was parked under perry-ui's hidden message-only window — presents are never composed, and a pre-mount render loop deadlocks at acquire once the queue fills (~10 frames; the "~15 frames present fine, then gray"). Fix: surfaceGetCurrentTexture returns 0 while the view is invisible (retry contract) + recreates the wgpu::Surface on reparent so the swapchain rebinds to the visible window tree. A/B-verified with screen captures (deadlock/no window → solid clear color on screen).	@perryts/webgpu@0.3.0 (PerryTS/webgpu#2)

Debug knobs shipped in the binding: PERRY_WEBGPU_DIAG=1 (per-call window-state logging), PERRY_WEBGPU_NO_REBIND=1 (bisection).

Follow-up spun off: #5884 — perry-ui-windows DPI mismatch (BloomView child HWND DPI-scaled inside an unscaled top-level window, content clips out of view). That's the last thing between this and a pixel-perfect out-of-the-box triangle on Windows.

Note for users: the no-arg requestAdapter() (headless/compute) path needs a Perry build containing #5814's omitted-arg fix; the on-screen path passes the surface explicitly and works either way.

Thanks again @nikolas_beckel for the razor-sharp report — the "~15 frames" detail was the key clue.

[nikolas-beckel]

Hey, found this. Thank you very much for fixing this! 🙏

[nikolas-beckel]

I'm trying it out now. :)