Emdawnwebgpu

Emdawnwebgpu is Dawn‘s implementation of webgpu.h for Emscripten (on top of the WebGPU JS API). It is a fork of Emscripten’s original USE_WEBGPU bindings, and while it is maintained in Dawn, it works in any browser supporting WebGPU (modulo individual feature support).

Emdawnwebgpu provides everything necessary to use <webgpu/webgpu.h> and the Dawn-style <webgpu/webgpu_cpp.h> with Emscripten.

API Stability

Core parts of webgpu.h (defined in https://github.com/webgpu-native/webgpu-headers) are considered a stable API and should not change, except for bugfixes (though guarantees are not made). Dawn/Emscripten-specific parts, and all of webgpu_cpp.h, are NOT considered stable, and may change.

How to use Emdawnwebgpu

Emdawnwebgpu is distributed in three ways. Choose the one that works for you.

In all cases, it is important to enable Closure to reduce code size in release builds. Pass the following flag to emcc during linking:

--closure=1

Easiest: “Remote” port built into Emscripten

Recent releases of Emscripten vendor a copy of a “remote” port which automatically downloads a pinned version of Emdawnwebgpu and configures it.

Pass the following flag to emcc during both compilation and linking:

--use-port=emdawnwebgpu

Latest: “Remote” port from Dawn release

This is the same as the built-in port, but you can download a newer version if you need recent bugfixes or features in Emdawnwebgpu that haven't been rolled into Emscripten yet. Requires Emscripten 4.0.10+.

Download and extract the emdawnwebgpu-*.remoteport.py file from https://github.com/google/dawn/releases.

Pass the following flag to emcc during both compilation and linking:

--use-port=path/to/emdawnwebgpu_remoteport_file.py

Latest, without automatic downloading: “Local” port from Dawn release

If your build system requires sources to be local (e.g. checked into your repository) instead of automatically downloaded, use this method.

Download and extract the emdawnwebgpu_pkg-*.zip package from https://github.com/google/dawn/releases.

Pass the following flag to emcc during both compilation and linking:

--use-port=path/to/emdawnwebgpu_pkg/emdawnwebgpu.port.py

If (and only if) using Emscripten before 4.0.7, pass this flag during linking:

--closure-args=--externs=path/to/emdawnwebgpu_pkg/webgpu/src/webgpu-externs.js

Port options

Options can be set by appending :key1=value:key2=value to --use-port. For information about port options, run:

emcc --use-port=emdawnwebgpu:help
emcc --use-port=path/to/emdawnwebgpu_remoteport_file.py:help
emcc --use-port=path/to/emdawnwebgpu_pkg/emdawnwebgpu.port.py:help

C++ bindings

By default, C++ bindings are provided in the include path. Note that unlike webgpu.h, these are not intended to be fully stable. If you don‘t want these for any reason (you have custom bindings, you’re using a pinned snapshot of webgpu_cpp.h, etc.), you can set the option cpp_bindings=false:

--use-port=emdawnwebgpu:cpp_bindings=false
--use-port=path/to/emdawnwebgpu_remoteport_file.py:cpp_bindings=false
--use-port=path/to/emdawnwebgpu_pkg/emdawnwebgpu.port.py:cpp_bindings=false

Embuilder

If your build process needs a separate step to build the port before linking, use Emscripten's embuilder.

Under embuilder, some options cannot be set automatically, so they must be set manually. For details, see OPTIONS in emdawnwebgpu.port.py (in the package zip).