Important Notice

Emscripten's WebGPU bindings are in a temporary breaking-change freeze. Bugfixes and small feature additions are still welcome.

Stable headers are being developed in webgpu-headers but will require a number of breaking changes relative to Emscripten‘s current implementation. Instead of constantly landing incremental breaking changes in Emscripten, the Dawn project (native C++ implementation of webgpu.h) has forked Emscripten’s bindings to do these incremental changes, before upstreaming all of the changes at once back into Emscripten. See emdawnwebgpu for more info.

WebGPU Bindings

These files, and several snippets of other files, are generated by Dawn (Chromium's WebGPU library):

• Generator
• Generator input
• Generator output

The C header is intended to be mostly the same as the “upstream” webgpu.h, but both are in flux, and some experimental elements are included and other native-specific elements are excluded.

The C++ files are currently Dawn-specific, but included in Emscripten for better compatibility with Dawn: it has roughly the same API as Dawn's copy, but is included here because it is strongly tied to an exact webgpu.h revision.

To update these bindings from Dawn: (TODO: these links are broken because Chromium Code Search is not currently building these generated files.)

1. Copy webgpu_enum_class_bitmasks.h from Dawn's source to system/include/webgpu/webgpu_enum_class_bitmasks.h

2. Build Dawn's emdawnwebgpu_headers_gen and emdawnwebgpu_js_gen targets (in a gn build of Dawn, or a build of Chromium) - or, use the Chromium Code Search copy of the generated files if no changes are needed

3. Copy the generated include files into Emscripten's system directory:

   • system/include/webgpu/webgpu.h
   • system/include/webgpu/webgpu_cpp.h
   • system/include/webgpu/webgpu_cpp_chained_struct.h

4. Paste the contents of library_webgpu_enum_tables.js over the “Map from enum number to enum string” section of library_webgpu.js

5. Copy the generated struct_info_webgpu.json to struct_info_webgpu.json.

6. Manually update the globalThis.gpu compile-time enum tables (AdapterType, BackendType, etc.):

   • Inspect the webgpu.h diff for changes to the integer values of any enums used here. (It‘s not necessary to add new enum values to these tables until they’re needed for something.)

7. Manually update the “Map from enum string back to enum number” tables.

   • Inspect the webgpu.h diff for changes to these enums. (These tables need to be complete so that we can handle any enum string the browser gives us.)

8. Update Emscripten's auto-generated files:

   emcc --clear-cache
   ./tools/gen_struct_info.py
   ./tools/gen_struct_info.py --wasm64
   ./tools/maint/gen_sig_info.py
   

Testing

There is a browser.test_webgpu_basic_rendering with minimal WebGPU API testing that can be handy to test manually before making a contribution. Use browser64.test_webgpu_basic_rendering to test the MEMORY64 build.

test/runner browser.test_webgpu_basic_rendering
test/runner browser64.test_webgpu_basic_rendering

You may need to specify extra browser cmd args to assign the WebGPU supported browser, which is needed if you work on linux where WebGPU is not enabled by default in chrome at present.

test/runner browser.test_webgpu_basic_rendering --browser="google-chrome-unstable --enable-unsafe-webgpu --enable-features=Vulkan,UseSkiaRenderer"

Alternatively you can test your emscripten updates by building the source file, and then serve (e.g. use node http-server) and view in browser to make sure things work fine.

emcc --clear-cache
emcc test/webgpu_basic_rendering.cpp -sUSE_WEBGPU -o path/to/index.html