Make non-spec functionality stand out better

[almarklein]

In addition to implementing the WebGPU spec, we also provide additional functionality that wgpu-native offers. It would be a waste not to do this, because it provides more power for desktop use-cases. However, when we add other backends, it is possible that (some of) this functionality is not available in a certain backend, making code that uses these features less portable. And that's sad, because the point of wgpu is to have portable code.

Note that this is not the quite the same as the API differences here: https://wgpu-py.readthedocs.io/en/stable/wgpu.html#differences-from-webgpu. Most these differences don't need extra functionality other than the outlined in the spec.

The cases that I know of that can be a problem are:

• GPUAdapter.request_device_tracing().
• GPU.enumerate_adapters().
• The force_fallback_adapter argument in request_adapter().
• Certain features (i.e. extensions) are specific to wgpu-native.

Some ideas to help with this problem:

• Document clearly that this is functionality specific to desktop use.
• Prefix these functions and arguments with something like "ext_".
• Only allow using such functions by enabling it as a kind of "extension". Perhaps this can be merged with the features mechanism already in webgpu?
• Putting the functionality in the backend module, i.e. not putting it into the main namespace.
• Using backend-specific behavior can only be done in a specific context manager.

In deciding about this, we should also take into account how these functionalities end up in the docs.

[Korijn]

This is an appropriate use case for the NotImplementedError when a backend is used that doesn't support a particular function :)

[rajveermalviya]

(idk the context of this in wgpu-py, but just for sanity check)
force_fallback_adapter is part of the js spec: https://gpuweb.github.io/gpuweb/#adapter-selection

[almarklein]

@rajveermalviya Ah it is! Thanks for clarifying 😄

[almarklein]

This is an appropriate use case for the NotImplementedError when a backend is used that doesn't support a particular function :)

True, but I also want to discourage people to use this non-standard functionality (unless the use-case really needs it). What triggered me is the idea that if/when we get wgpu-py working via PyScript (#407), people will want to run examples of pygfx/fastplotlib/etc. in the browser. Any code that uses non-standard stuff will then be less portable.

[almarklein]

The solution applied in #408 is to provide backend-specific API as functions in the corresponding backend module. We now have request_device_tracing and enumerate_adapters in wgp.backends.wgpu_native.

This solution IMO strikes a nice balance between being simple, being obviously backend-specific, not being too annoying.

[almarklein]

I think that with that we can close this issue. One issue to watch out for is that certain features (i.e. extensions) are backend-specific, but when using features you are probably aware of potentially breaking portability anyway.