Architecture

Architecture

A brief overview of wgpu for (to be) contributors and curious minds.

Does not explain how WebGPU works, just how it is implemented in wgpu! For WebGPU API refer to the official specification.

Relationship to other projects

TODO: Insert svg here

https://app.diagrams.net/#Uhttps%3A%2F%2Fraw.githubusercontent.com%2Fgfx-rs%2Fwgpu%2Fmaster%2Fetc%2Fbig-picture.xml

Consumers of wgpu

• Firefox Implement JS API for using WebGPU in the browser
• wgpu-rs idomatic Rust wrapper for WebGPU (for targeting both native and the web)
• wgpu-native allows use of WebGPU through the native c api
• Deno Implements JS API for using WebGPU on a server

Major dependencies

• gfx-rs Vulkan-like graphics API abstraction. Also referred to as gfx-hal or just gfx
• Naga Shader translation and validation.
• gpu-alloc and gpu-descriptor Implementation agnostic memory and descriptor allocators for Vulkan-like APIs.

Crates

• wgpu-core WebGPU core logic on top of gfx-hal
• wgpu-types Rust types shared with wgpu-rs
• player Allows to replay wgpu traces

Concepts

Lifetime tracking, resource locking

TODO (why/how)

Tracker, handling of barriers

Unlike Vulkan & DX12, WebGPU does not track resource barriers (more info). Therefore, wgpu needs to track and insert barriers. ResourceTracker keeps track of the current usage of a single kind type of resource. TrackerSet ("the" tracker) has ResourceTracker for every type.

Since every CommandBuffer is recorded independently, each of them has a TrackerSet. Each render pass has a separate TrackerSet, and so does each bind group. These tracker sets flow into the parent trackers:

• When a bind group is set in a render pass, it's tracked resources are merged into the pass resources.
• When a render pass is finished recording, it's tracker is merged into the command buffer's tracker, with needed barriers issued.
• Command buffer trackers are combined during queue_submit into the device's tracker. additional resource barriers are generated if necessary.

MemoryInitTracker

Tracks memory initialization state of Buffer resources, i.e. if they have been written to either by the user or by wgpu previously zero-initializing it (WebGPU requires all buffers to behave as-if they are zero inititialized). A MemoryInitTracker tracks a single buffer and allows to insert zero initialization lazily on use. Zero init is inserted if necessary at:

• memory mapping
• queue_submit (for all bindings)

Device maintain

TODO (what/why)

TODO

What else is non-trivial?

API Tracing

Enabled via feature flag. Allows to record all usage (WebGPU api functions essentially) to a .ron file. Any additional data (uploaded data to buffer etc.) is stored in additional files. A trace can be replayed with the Player compiled from the same wgpu revision. Used for testing and bug reporting.