This repository contains the implementation of Dawn, which is itself composed of two main libraries (dawn_native and dawn_wire), along with support libraries, tests, and samples. Dawn makes heavy use of code-generation based on the
dawn.json file that describes the native WebGPU API. It is used to generate the API headers, C++ wrapper, parts of the client-server implementation, and more!
dawn.json: contains a description of the native WebGPU in JSON form. It is the data model that's used by the code generators.
dawn_wire.json: contains additional information used to generate
dawn_wirefiles, such as commands in addition to regular WebGPU commands.
examples: a small collection of samples using the native WebGPU API. They were mostly used when bringing up Dawn for the first time, and to test the
generator: directory containg the code generators and their templates. Generators are based on Jinja2 and parse data-models from JSON files.
infra: configuration file for the commit-queue infrastructure.
scripts: contains a grab-bag of files that are used for building Dawn, in testing, etc.
common: helper code that is allowed to be used by Dawn's core libraries,
dawn_wire. Also allowed for use in all other Dawn targets.
dawn_native: code for the implementation of WebGPU on top of graphics APIs. Files in this folder are the “frontend” while subdirectories are “backends”.
<backend>: code for the implementation of the backend on a specific graphics API, for example
dawn_platform: definition of interfaces for dependency injection in
dawn_wire: code for an implementation of WebGPU as a client-server architecture.
fuzzers: various fuzzers for Dawn that are running in Clusterfuzz.
include: public headers with subdirectories for each library. Note that some headers are auto-generated and not present directly in the directory.
end2end: tests for the execution of the WebGPU API and require a GPU to run.
perf_tests: benchmarks for various aspects of Dawn.
unittests: code unittests of internal classes, but also by extension WebGPU API tests that don't require a GPU to run.
validation: WebGPU validation tests not using the GPU (frontend tests)
white_box: tests using the GPU that need to access the internals of
utils: helper code to use Dawn used by tests and samples but disallowed for
third_party: directory where dependencies live as well as their buildfiles.
The largest library in Dawn is
dawn_native which implements the WebGPU API by translating to native graphics APIs such as D3D12, Metal or Vulkan. It is composed of a frontend that does all the state-tracking and validation, and backends that do the actual translation to the native graphics APIs.
dawn_native hosts the spirv-val for validation of SPIR-V shaders and uses SPIRV-Cross shader translator to convert SPIR-V shaders to an equivalent shader for use in the native graphics API (HLSL for D3D12, MSL for Metal or Vulkan SPIR-V for Vulkan).
A second library that implements both a client that takes WebGPU commands and serializes them into a buffer, and a server that deserializes commands from a buffer, validates they are well-formed and calls the relevant WebGPU commands. Some server to client communication also happens so the API's callbacks work properly.
dawn_wire is meant to do as little state-tracking as possible so that the client can be lean and defer most of the heavy processing to the server side where the server calls into
Normally libraries implementing
webgpu.h should implement function like
wgpuDeviceCreateBuffer but instead
dawn_wire implement the
dawnProcTable which is a structure containing all the WebGPU functions Dawn implements. Then a
dawn_proc library contains a static version of this
dawnProcTable and for example forwards
wgpuDeviceCreateBuffer to the
procTable.deviceCreateBuffer function pointer. This is useful in two ways:
dawn_wire, which is useful to test boths paths with the same binary in our infrastructure.
When the WebGPU API evolves a lot of places in Dawn have to be updated, so to reduce efforts, Dawn relies heavily on code generation. The code generators are based on Jinja2 and separate the model from the view like in Web development. The model is some JSON file, usually
dawn.json and the views are the Jinja2 templates in
generator/templates. The generated files are not checked into the repository but instead are generated during the build.