ADR-001: wgpu as Rendering Foundation

Status: Accepted Date: 2026-01-15

Context

SiliconGhetto needs a GPU abstraction layer that works in the browser via WebAssembly. The engine must support WebGPU where available and fall back to WebGL2 on older browsers. We need a Rust-native API that compiles to both native targets (for tooling and testing) and wasm32-unknown-unknown.

Options Considered

1. wgpu (chosen)

  • Rust-native WebGPU implementation
  • Compiles to WebGPU in the browser, Vulkan/Metal/DX12 natively
  • Automatic WebGL2 fallback via the webgl feature
  • Active development, used by the Bevy engine and other Rust projects
  • Strong type safety and validation in debug mode

2. Raw WebGPU bindings via web-sys

  • Minimal overhead
  • No native support — testing requires a browser
  • No fallback path — WebGL2 would need a separate implementation
  • Low-level API requires significant boilerplate

3. glow (OpenGL ES / WebGL2)

  • Wide browser support
  • No path forward to WebGPU
  • OpenGL’s stateful API is error-prone
  • Limited compute shader support

Decision

Use wgpu as the sole rendering abstraction. All GPU operations go through wgpu’s API, which maps to WebGPU in the browser and native backends for development.

Consequences

Positive

  • Single rendering codebase for browser and native
  • WebGPU-first with WebGL2 fallback out of the box
  • Compute shaders available where WebGPU is supported
  • Native builds enable fast iteration and GPU debugging
  • Large ecosystem of wgpu examples and learning resources

Negative

  • wgpu is a large dependency (~2MB added to WASM before optimization)
  • WebGL2 fallback has some feature limitations (no compute, no storage textures)
  • wgpu version churn requires periodic updates

Mitigations

  • WASM size managed via wasm-opt, LTO, and codegen-units=1
  • Feature detection at runtime to gracefully degrade on WebGL2
  • Pin wgpu to major versions; update during dedicated maintenance windows

References