0xDocs 0x.limo

Docs / Native runtime

Graphics

Coming

wgpu 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:

BackendWhereStatus
VulkanLinux (NVIDIA, AMD RADV, Mesa lavapipe), WindowsThe primary backend. Every feature, including ray queries and mesh shaders.
DX12WindowsSupported 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.
MetalmacOSSupported by wgpu. Not run yet.
GL / GLESFallbackNeeds 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:

VariableEffect
WGPU_BACKENDvulkan, dx12, metal, gl, or a comma list.
WGPU_ADAPTER_NAMEThe first adapter whose name contains this text (case-insensitive).
WGPU_POWER_PREFhigh (default), low or none.

#Limits and quotas

LimitValue
Device limitsWhatever the adapter offers. Asking for more than the adapter's limits fails request_device.
GPU memory a game may allocate6 GiB (buffers, textures, acceleration structures).
One GPU request or reply64 MiB.
Live GPU objectsabout one million.
Acceleration structures2 GiB in total; at most 256 geometries and 16,777,216 primitives per BLAS; at most 262,144 instances per TLAS.
Error scopes64 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.

FeatureMeasured
Hardware ray query, 1920×1080, one ray per pixel, 977k triangles0.21–0.24 ms primary, 0.64–0.66 ms incoherent: the same as raw Vulkan on the same GPU.
Mesh shaders, 30,538 meshletsPixel-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:

  1. The player's launch settings (--present-mode, --vsync/--no-vsync, --latency 1-3, --fps-cap N, --fullscreen). These always win; the game is told LOCKED.
  2. The game at run time: sg_guest::display::set_present, set_frame_latency, set_frame_cap, set_fullscreen.
  3. The manifest: "display": {"present_mode": "fifo", "frame_latency": 1, "fps_cap": 0, "fullscreen": "borderless"}. Present modes are fifo, fifo_relaxed, mailbox, immediate, auto_vsync, auto_no_vsync.
  4. The game's own surface.configure (stock wgpu).

Rules a game can rely on:

  • A present mode the surface does not offer makes configure trap with a reason, so check surface.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_stats reports 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 modeSurface format and colour space
SDR (sRGB format)*UnormSrgb, sRGB
SDR (unorm)*Unorm, sRGB curve in the shader
scRGBRgba16Float, 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).