Skip to content

feat(wgpu_context): implement Windows DX12-first Vulkan-fallback policy - #100

Open
GoCoder7 wants to merge 1 commit into
DioxusLabs:mainfrom
techton7:local/win-dx12-policy
Open

GoCoder7 wants to merge 1 commit into
DioxusLabs:mainfrom
techton7:local/win-dx12-policy

Conversation

@GoCoder7

@GoCoder7 GoCoder7 commented Sep 27, 2026 •

Copy link
Copy Markdown

Closes #99

Hi everyone,

1. Summary of Changes

This pull request implements an ordered GPU backend selection policy on Windows in wgpu_context: prioritizing DirectX 12 by default, providing automatic sequential fallback to Vulkan when DX12 is unavailable, and strictly respecting explicit user/environment overrides (WGPU_BACKEND).

Key Scope Points

  1. Authoritative Context Seam (wgpu_context):
    • Updates DeviceHandle::new_from_compatible_surface_with_backends to execute sequential backend fallback.
    • Adds override_backends: Option<wgpu::Backends> and constructor with_features_limits_and_backends to WGPUContext.
    • Re-exports pub use wgpu;.
  2. Zero Downstream Renderer Changes:
    • anyrender_vello_hybrid and anyrender_vello require no code changes. Both delegate surface and device initialization to DeviceHandle::new_from_compatible_surface, immediately inheriting the policy.
  3. Downstream Consumers:
    • Embedders (such as Blitz or dioxus-native) require no first-wave code changes. Consumer-side validation and eventual removal of ad-hoc env hacks are rollout benefits, not part of the upstream patch scope.

2. Exact Seam Touched

Crate File Changes Role
wgpu_context crates/wgpu_context/src/lib.rs +150 / -34 Ordered backend enumeration, compatibility check, and sequential device fallback loop.

3. Policy Semantics

The selection logic follows a strict 3-tier sequence:

[Window / Device Handle Request]
              │
              ▼
   Is WGPU_BACKEND set in env,
   or was backends explicitly passed?
         ├── YES ──► Use specified backend directly (Honors override)
         │
         └── NO  ──► Is target_os = "windows"?
                         ├── NO  ──► Default wgpu adapter resolution
                         │
                         └── YES ──► Tier 1: Try DirectX 12
                                         │
                                         ├─ Found compatible adapter & device created ──► Return DX12 Device
                                         │
                                         └─ Failed or no adapter ──► Tier 2: Try Vulkan Fallback
                                                                         │
                                                                         ├─ Found compatible adapter & device created ──► Return Vulkan Device
                                                                         │
                                                                         └─ Failed ──► Tier 3: Exhaustive default fallback

4. Validation Evidence & Proof Boundaries

Testing was performed on Windows 10 x64 hardware with Intel(R) HD Graphics 520 (Skylake generation, driver 27.20.100.8854):

  1. Compilation:
    • cargo check -p wgpu_context: Passed cleanly with exit code 0.
    • Downstream integration check (browser / dioxus-native consuming this patch): Compiled cleanly without downstream code changes.
  2. Default Execution (WGPU_BACKEND unset):
    • Executed downstream window with WGPU_BACKEND unset.
    • Verified active adapter: adapter: name='Intel(R) HD Graphics 520', backend=Dx12, driver='27.20.100.8854'.
    • DXGI swapchain presented cleanly to DWM; the blank white screen bug caused by Intel Windows Vulkan swapchain failure was completely resolved.
  3. Explicit Override Sanity:
    • Executed with $env:WGPU_BACKEND = "vulkan".
    • Verified active adapter: backend=Vulkan. Confirmed that explicit user/CI intent is never overridden.
  4. Proof Scope (Honesty Note):
    • The default DX12 path and explicit override semantics are directly runtime-proven.
    • The automatic DX12 failure -> Vulkan fallback branch is implementation-backed and verified by code-path review, but was not directly observed on hardware where DX12 itself fails.

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt Windows DX12-First GPU Backend Policy with Ordered Vulkan Fallback

1 participant