Autogenerated binary layer

[Korijn]

I've been experimenting a lot with Claude Code recently and one of my experiments was seeing if I could set up a fork of wgpu-py where code generation is pushed to the maximum. You can check it out here (branch dev) https://github.com/Korijn/wgpu-py/tree/dev

If you're interested to see the changeset description and full diff, go here: Korijn#1

The fork is split into roughly 3 layers:

1. 100% autogenerated Python wrapper layer using cffi out-of-line mode, statically built from source against wgpu-native, guaranteed to cover the full C interface. To be clear: this produces a binary wrapper, not a runtime interface.
2. 95% autogenerated WebGPU API layer
3. Compatibility layer for wgpu-py and pygfx

All layers are fully typed too.

I have been thinking to factor layer 1 out to a separate repo under the pygfx umbrella, and publish that as its own wheel to pypi.

It gives everyone who wants it direct low level access, so they can build whatever they want on top of that. And at the same time wgpu-py can also be a consumer, although they can also live happily side by side.

Another benefit is that we can provide typed struct definitions right there, and they will automatically propagate, enabling use of tools like language servers and typecheckers such as mypy/ty.

There are also minor and major performance benefits; of course the import time is way faster. But there are also hot path calls that sped up significantly. See the full benchmark here: Korijn#1 (comment)

What do you think?

[Vipitis]

hey, I have stumbled across the commits in your fork a few days ago and read through some of the changes too.

I have very mixed feelings about some of the concepts used and also the accuracy of some things. But there is also a few very handy things we could already adopt. Below are some of my thoughts.

The main question to ask here is what is wgpu-py? Currently it's very much WebGPU for python, with a few api diffs. It's not a pythonic wrapper of webgpu ... that would be something part way between wgpu-py and pygfx. Think of stuff like context managers, global constructors instead of device methods etc.

But with more and more native only features being available in wgpu-native, there will hopefully be a major update with a bunch of modern features in a couple of weeks (hardware raytracing, cooperative matrix, mesh shaders, low level interop, etc).
wgpu-native, webgpu.h and webgpu.idl already disagree in some places and this drift will only grow as webgpu.h is considered "stable". while the .idl still changes...

I would love to support the new native only features, as extras or similar and I do think there needs to be a different approach. especially as a few native only features are in _api without the need to import extras. For actually using wgpu-py based projects in the browser it would be helpful to make it really clear what is webgpu spec and what is native only extensions.

generating the bindings from the .json (better would be .yaml I believe - since that is the source of truth) instead of just generation annotations from headers is an improvement. It will make updating faster - however there won't be many more large updates and mostly smaller tweaks. Only native only features will be larger additions in the future... and the native only part of wgpu-native doesn't have a specific of the C api in a yaml or json file (this is pretty much a todo stub: gfx-rs/wgpu-native#606 (comment) - but there is already infrastructure to do it better).

What we can definitely use is to remove a lot of the validation code. It shouldn't really happen in python. It's already handled in rust... or the c-to-rust mapping the only benefit is that we will get a python exception instead of the validation error... But I think there might be a better way with improvements coming from wgpu-native (hopefully) soon. If I understand the reasoning behind the performance improvements... maybe that would be a large part of it?
Coldstart/wallclock time to first frame is an issue I would love to see improved, an it's also a problem in wgpu itself that was discussed in last weeks maintainer meeting.

Typing improvements are always welcome, I have seen that cffi might support .pyi eventually? Because it just botheres me that lib. and libf. are not understood by the language server. I have seen how other bindings like uharfbuzz (cython) look... and while it works - it's not easy to read by jumping around in 3 or 4 files when you jump to definition.

If we more or less bind wgpu, and not webgpu.h/wgpu-native why even go to C? there is a few projects that bind the rust project directly to python... I have linked them elsewhere but I also saw this today: https://github.com/pybevy/pybevy (python interface for the bevy engine which runs on wgpu directly).

Developer ergonomics with the git submodule are awful from my experience. If I jump between versions, it's much easier to run the script once than to make sure you update the submodule correctly and rebuilt etc. It's not something I have tried yet.

Even if we are still 0ver, there is more and more users of wgpu-py (like noticed this today: #818 (comment)), including some large projects. So we should avoid breaking too much and perhaps reach some form of stable API at least?

I am currently busy with moving and upcoming trips - so I have only skimmed some parts of the diff, and there is a bunch of questionable implementation details and exposed API which I don't think is actually correct according to the webgpu spec

[Korijn]

It's one big Claude Opus one-shot action that I mostly kicked off to see what would come of it - no intentions whatsoever to merge any of it as is.

At least the baseline C API wrapping with cffi out of line mode compilation seems like a valuable improvement that can be implemented without breakage in wgpu-py, or otherwise delivered independently to pypi.

Why not go directly with Rust is a good question - I think the core argument is that we'd have to do more work, specifically in defining the API to wrap, no?

[Vipitis]

I have no real rust experience. But apparently you can do Pyo3 where it's extern "Python" instead of "extern"C". The motivation here is to reduce the mapping. Instead of going from python to wgpu via wgpu-native and it's webgpu.h interface. We could write an adapter directly in rust to become callable python objects. Which objects? I would assume the classes and functions we currently have, as in _classes.py.
Not sure if they under the hood and with all the compiler magic is actually equivalent. But it feels better if it works as I hope it will.
I am unsure about the compiled blobs you will have and their compatibility across platforms. Perhaps you can even target wasm for pyodide like this.

[almarklein]

It's a massive refactor, I only scanned through the changes so far. Impressive benchmark results!!

I like the idea to roll out level 1 as its own library. That way the higher-level parts can then still easily be dev-installed (without the need for a compiler) and also because it is packaged very differently. And yeah, it may have value on its own.

Questions / comments related to binding and compilation

I learned a few weeks ago that compiled Python code can target the "stable ABI", so that it's not bound to a particular Python version, i.e. it automatically works on future Python versions. This would make it easier to maintain (no rush when a new Python version is released).

Related, from Python 3.15 onwards, there is the abi-t ABI. If you target that, the code supports with-GIL, no-GIL, and all future Python versions.

As for binding at the C level vs Rust; at the C level there is a clear definition (webgpu.h) that is deliberately made in-line with the WebGPU spec, which makes it much easier to bridge the two, as your PR shows. I reckon that would be much harder targeting the Rust API?

More questions

Is compat/__init__.py the 3d layer you mentioned? Our API deviates a bit from the WebGPU api, and it seems like some of these changes occur in "level 2" and others in "level 3"?

Any thoughts on how this would fit with the plan for Pyodide support?

Will this effort also help for automatically adding docstrings? Many seem to now say "see the WebGPU specification".