| Kai Ninomiya | b30c517 | 2024-06-11 01:59:33 | [diff] [blame] | 1 | # WebGPU Headers |
| Corentin Wallez | fe60050 | 2023-10-05 11:55:13 | [diff] [blame] | 2 | |
| Kai Ninomiya | b30c517 | 2024-06-11 01:59:33 | [diff] [blame] | 3 | This repository contains C headers equivalent to the [WebGPU](https://gpuweb.github.io/gpuweb/) API and documentation on the native specificities of the headers. |
| 4 | |
| 5 | **This header is NOT STABLE yet, and the documentation is very much a work in progress!** |
| 6 | |
| 7 | All of the API is defined in the [webgpu.h](./webgpu.h) header file. |
| 8 | **[Read the documentation here!](https://webgpu-native.github.io/webgpu-headers/)** |
| 9 | |
| 10 | ## Why? |
| Corentin Wallez | fe60050 | 2023-10-05 11:55:13 | [diff] [blame] | 11 | |
| 12 | While WebGPU is a JavaScript API made for the Web, it is a good tradeoff of ergonomic, efficient and portable graphics API. |
| 13 | Almost all of its concepts are not specific to the Web platform and the headers replicate them exactly, while adding capabilities to interact with native concepts (like windows). |
| 14 | |
| Corentin Wallez | fe60050 | 2023-10-05 11:55:13 | [diff] [blame] | 15 | Implementations of this header include: |
| 16 | |
| Kai Ninomiya | b30c517 | 2024-06-11 01:59:33 | [diff] [blame] | 17 | - [Dawn](https://dawn.googlesource.com/dawn), the C++ WebGPU implementation used in Chromium |
| 18 | - [wgpu-native](https://github.com/gfx-rs/wgpu-native), C bindings to [wgpu](https://github.com/gfx-rs/wgpu), the Rust WebGPU implementation used in Firefox |
| Corentin Wallez | fe60050 | 2023-10-05 11:55:13 | [diff] [blame] | 19 | - [Emscripten](https://github.com/emscripten-core/emscripten/blob/main/src/library_webgpu.js) translates [webgpu.h](./webgpu.h) calls to JavaScript WebGPU calls when compiling to WASM |
| Elie Michel | 616512a | 2024-03-04 20:54:00 | [diff] [blame] | 20 | |
| 21 | ## Details |
| 22 | |
| 23 | Here are some details about the structure of this repository. |
| 24 | |
| 25 | ### Main files |
| 26 | |
| 27 | - `webgpu.h` is the one and only header file that defines the WebGPU C API. Only this needs to be integrated in a C project that links against a WebGPU implementation. |
| 28 | |
| 29 | - `webgpu.yml` is the main machine-readable source of truth for the C API and its documentation (in [YAML](https://yaml.org/) format). It is used to generate the official `webgpu.h` header present in this repository, (will be used) to generate the official documentation, and may be used by any other third party to design tools and wrappers around WebGPU-Native. |
| 30 | |
| 31 | - `schema.json` is the [JSON schema](https://json-schema.org/) that formally specifies the structure of `webgpu.yml`. |
| 32 | |
| 33 | ### Generator |
| 34 | |
| 35 | - `Makefile` defines the rules to automatically generate `webgpu.h` from `webgpu.yml` and check the result. |
| 36 | |
| 37 | - `gen/` and the `go.*` files are the source code of the generator called by the `Makefile`. |
| 38 | |
| 39 | - `tests/compile` is used to check that the generated C header is indeed valid C/C++ code. |
| 40 | |
| 41 | ### Workflows |
| 42 | |
| 43 | - `.github/workflows` defines the automated processes that run upon new commits/PR, to check that changes in `webgpu.yml` and `webgpu.h` are consistent. |
| 44 | |
| 45 | ## Contributing |
| 46 | |
| 47 | **Important** When submitting a change, one must modify both the `webgpu.yml` and `webgpu.h` files in a consistent way. One should first edit `webgpu.yml` (the source of truth), then run `make gen` to update `webgpu.h` and finally commit both changes together. |
