Graphics
Comingwgpu in native 0x games, covering the Vulkan, DX12, Metal and GL backends (no D3D11), GPU limits and quotas, ray queries and mesh shaders, presentation, frame pacing and HDR.
A native game draws with stock wgpu 30. sg_guest::gpu::instance() returns a normal
wgpu::Instance backed by a custom backend. The guest holds only IDs, the host validates every
request and runs it on a real wgpu device, so existing wgpu code (and WGSL shaders) run unchanged.
#Backends
The runtime uses wgpu's backends:
| Backend | Where | Status |
|---|---|---|
| Vulkan | Linux (NVIDIA, AMD RADV, Mesa lavapipe), Windows | The primary backend. Every feature, including ray queries and mesh shaders. |
| DX12 | Windows | Supported by wgpu. Tested only through translation layers so far, not on native Windows drivers. Ray queries and mesh shaders need the DXC compiler (dxcompiler.dll, dxil.dll) next to the runtime. |
| Metal | macOS | Supported by wgpu. Not run yet. |
| GL / GLES | Fallback | Needs desktop GL 4.3 or GLES 3.1 (compute shaders, which wgpu requires). An older context, such as GL 3.3, is refused with the reason. No ray tracing on GL. |
| D3D11 | — | Not supported. wgpu has no D3D11 backend. |
By default the runtime picks wgpu's primary backends (Vulkan on Linux, DX12 and Vulkan on Windows, Metal on macOS) and a high-performance adapter. Players and testers can override it:
| Variable | Effect |
|---|---|
WGPU_BACKEND | vulkan, dx12, metal, gl, or a comma list. |
WGPU_ADAPTER_NAME | The first adapter whose name contains this text (case-insensitive). |
WGPU_POWER_PREF | high (default), low or none. |
#Limits and quotas
| Limit | Value |
|---|---|
| Device limits | Whatever the adapter offers. Asking for more than the adapter's limits fails request_device. |
| GPU memory a game may allocate | 6 GiB (buffers, textures, acceleration structures). |
| One GPU request or reply | 64 MiB. |
| Live GPU objects | about one million. |
| Acceleration structures | 2 GiB in total; at most 256 geometries and 16,777,216 primitives per BLAS; at most 262,144 instances per TLAS. |
| Error scopes | 64 nested. |
Errors behave like WebGPU. A validation error (bad WGSL, a wrong descriptor) is delivered to the game's error scopes, or as an uncaptured error, and the game keeps running. A request that names a bad handle, breaks a rule wgpu would panic on (map ranges, surface state) or goes over the quota traps the guest. A panic inside wgpu ends the game, never the host.
#Ray queries and mesh shaders
Hardware ray queries (BLAS/TLAS, rayQuery in WGSL) and task and mesh shaders are available when
the manifest sets "gpu_experimental": true, the player grants it, and the adapter supports them.
Check adapter.features() and fall back: the runtime can be told to hide either feature
(SG_GPU_DENY=rt,mesh), and a game must still render without them.
| Feature | Measured |
|---|---|
| Hardware ray query, 1920×1080, one ray per pixel, 977k triangles | 0.21–0.24 ms primary, 0.64–0.66 ms incoherent: the same as raw Vulkan on the same GPU. |
| Mesh shaders, 30,538 meshlets | Pixel-identical to the vertex-pipeline reference. |
Mesh shaders are not run on AMD RADV at present (they hang the GPU in tests).
#Presentation
Present mode, frame latency, the frame cap and fullscreen are set from four places. When they conflict, the strongest wins:
- The player's launch settings (
--present-mode,--vsync/--no-vsync,--latency 1-3,--fps-cap N,--fullscreen). These always win; the game is toldLOCKED. - The game at run time:
sg_guest::display::set_present,set_frame_latency,set_frame_cap,set_fullscreen. - The manifest:
"display": {"present_mode": "fifo", "frame_latency": 1, "fps_cap": 0, "fullscreen": "borderless"}. Present modes arefifo,fifo_relaxed,mailbox,immediate,auto_vsync,auto_no_vsync. - The game's own
surface.configure(stock wgpu).
Rules a game can rely on:
- A present mode the surface does not offer makes
configuretrap with a reason, so checksurface.get_capabilities. - The frame cap accepts 10 to 1000 fps, or 0 for none.
- Entering fullscreen needs a recent key or button press from the player, and is rate-limited. F11 and Alt+Enter belong to the player and never reach the game.
frame_statsreports the measured present interval, blocking times and display latency.
#HDR
Render scene-linear BT.709 colour in paper-white units (1.0 = SDR white) and call
sg_encode_output from the WGSL that sg_abi::hdr provides as the last step of your final
pass. It tone-maps to what the output can show and applies the output's encoding:
| Output mode | Surface format and colour space |
|---|---|
| SDR (sRGB format) | *UnormSrgb, sRGB |
| SDR (unorm) | *Unorm, sRGB curve in the shader |
| scRGB | Rgba16Float, extended sRGB linear |
| PQ (HDR10) | Rgb10a2Unorm or Rgba16Float, BT.2100 PQ |
sg_guest::display::negotiate_output (over sg_abi::hdr::negotiate) picks the best mode from the surface's capabilities and falls back to SDR
when no HDR colour space is offered. sg_guest::display::set_hdr_metadata sends mastering metadata (primaries, white
point, luminance, MaxCLL, MaxFALL). The player can turn HDR off (--no-hdr).
