mach icon indicating copy to clipboard operation
mach copied to clipboard

gpu: complete rewrite of WebGPU API for Zig

Open emidoots opened this issue 3 years ago • 0 comments

As discussed in Matrix earlier, this begins the complete rewrite of mach/gpu. We throw out the old codebase, start entirely from scratch & do it right this time. This also updates us to the latest version of Dawn.

The plan

The general plan is as follows:

  • Base the bindings directly on webgpu.h, specifically the version from Dawn, and document this.
  • Use flagsets everywhere.
  • Maintain 100% ABI compatibility with all types in webgpu.h: the bindings should be zero-overhead. The only situations in which we add overhead should be clearly documented in the README, and should be extremely narrow in scope (such as error handling.)
  • No more terribly nasty copying of descriptor parameters, we can just pass parameters directly to Dawn.
  • No more vtable / runtime interface garbage. We will replace this with comptime-composable interfaces instead.
  • We settle for no less than 100% API coverage, and verify this by making changes incrementally: removing the type from webgpu.h at the same time we add to our Zig API.
  • We use way more clear naming conventions when translating.

In some small cases, the API might not be as nice as before. But this is OK, and supplemented by the fact that:

  1. This rewrite will enable us to begin using the new js-runtime API to add WebAssembly support, knowing we haven't locked ourselves into any terrible choices.
  2. Begin adding a mach/gpu/util package with optional helpers you can use on top, limited to things like this that are API usage quality of life improvements.

Milestones

  • [x] Implement all enum types / constants
  • [x] Implement all descriptor types
  • [x] Define approach for comptime interface composition
  • [x] Implement all functions/methods
  • [x] Eliminate all deprecated methods according to dawn.json
  • [x] Cross-check default values with old implementation, dawn.json or similar
  • [x] Replace *opaque with opaque for type nesting, or consider NullableEnum and Enum with bitcasting?
  • [x] Consider changing "undef"/"undefined"/"dimension_undef" to just "unspecified"?
  • [x] Add Dawn direct implementation (bypass Dawn vtable entirely)
  • [ ] Consider opportunities for helpers / more friendly APIs, document policy for doing this on object methods
  • [ ] Native examples are compiling

WebAssembly support comes next (anyone is free to start on this and send PRs to this branch, but not a blocker for merging this.)

  • [x] By selecting this checkbox, I agree to license my contributions to this project under the license(s) described in the LICENSE file, and I have the right to do so or have received permission to do so by an employer or client I am producing work for whom has this right.

emidoots avatar Jul 11 '22 16:07 emidoots