Manual GLFW integration

[Korijn]

Direct integration of glfw and wgpu-py without using the wgpu.gui Canvas abstraction/class hierarchy.

This is a demonstration for hardcore users that need total low-level control.

Changes:

• Adds examples/triangle_glfw_direct.py
• Refactors examples/triangle.py and wgpu/gui/glfw.py to make some utility code more easily accessible.

Background:

• I was thinking about Update propagation pygfx#495 and decided to see if I can implement a closed loop render mode with wgpu-py and glfw.
• Turns out it was pretty challenging so this example should support users looking to do the same, for example Use own created glfw window. #430
• The main thing making this complicated is that instead of providing direct bindings to webgpu-native, we directly map the webgpu-native API to the IDL-standardized webgpu API
• We could consider "splitting" the webgpu-native backend in 2 parts, one being autogenerated direct python bindings, and one being the translation layer to the IDL-standardized webgpu API, I documented this idea here: Idea: auto-generated bindings for webgpu-native #487

Note: I guess another question is if this can be done with a pygfx renderer.

[almarklein]

Yes, the WgpuCanvasInterface class defines what is needed. It can be used as an interface (as the name suggests)- it does not have to be subclassed.

wgpu-py/wgpu/gui/base.py

Lines 8 to 60 in 570738c

	class WgpuCanvasInterface:
	"""The minimal interface to be a valid canvas.
	Any object that implements these methods is a canvas that wgpu can work with.
	The object does not even have to derive from this class.
	In most cases it's more convenient to subclass :class:`WgpuCanvasBase <wgpu.gui.WgpuCanvasBase>`.
	"""
	def __init__(self, *args, **kwargs):
	# The args/kwargs are there because we may be mixed with e.g. a Qt widget
	super().__init__(*args, **kwargs)
	self._canvas_context = None
	def get_surface_info(self):
	"""Get information about the native window / surface.
	This is used to obtain a surface id, so that wgpu can render to the
	region of the screen occupied by the canvas. Should return None for
	offscreen canvases. Otherwise, this should return a dict with a "window"
	field. On Linux the dict should contain more fields, see the existing
	implementations for reference.
	"""
	return None
	def get_physical_size(self):
	"""Get the physical size of the canvas in integer pixels."""
	raise NotImplementedError()
	def get_context(self, kind="webgpu"):
	"""Get the ``GPUCanvasContext`` object corresponding to this canvas.
	The context is used to obtain a texture to render to, and to
	present that texture to the canvas. This class provides a
	default implementation to get the appropriate context.
	The ``kind`` argument is a remnant from the WebGPU spec and
	must always be "webgpu".
	"""
	# Note that this function is analog to HtmlCanvas.getContext(), except
	# here the only valid arg is 'webgpu', which is also made the default.
	assert kind == "webgpu"
	if self._canvas_context is None:
	# Get the active wgpu backend module
	backend_module = sys.modules["wgpu"].gpu.__module__
	if backend_module == "wgpu._classes":
	raise RuntimeError(
	"A backend must be selected (e.g. with request_adapter()) before canvas.get_context() can be called."
	)
	# Instantiate the context
	CC = sys.modules[backend_module].GPUCanvasContext # noqa: N806
	self._canvas_context = CC(self)
	return self._canvas_context

We also have a test to make sure this works:

wgpu-py/tests/test_gui_glfw.py

Lines 159 to 163 in 570738c

	def test_glfw_canvas_render_custom_canvas():
	"""Render an orange square ... in a glfw window. But not using WgpuCanvas.
	This helps make sure that WgpuCanvasInterface is indeed the minimal
	required canvas API.
	"""

The _vsync attribute being checked is something we should probably refactor. Perhaps make it part of the WgpuCanvasInterface too.

[almarklein]

To respond to your questions:

I can't render a triangle to the screen using the wgpu_native backend with glfw, unless I re-implement the Canvas API.

Yes, some parts. Perhaps we can improve our docs on how this works. The example in this PR will certainly help.

That means I am also bound to its design choices in terms of event loop and abstraction.

I don't think this is the case.

Is our Canvas abstraction and it's API based on any public specs such as webgpu or something by w3c? I don't think so right?

No.

[Korijn]

I think I can see what your idea is now after having had some more time to play with it. I could implement a minimal Canvas class that exposes only the needed methods, but keep control flow out of it. That's cool. I'll try to do that in this branch next.

[almarklein]

I think I can see what your idea is now after having had some more time to play with it.

Definitely room to improve the docs in this regard then 😅

[Korijn]

Well, I think it's just unexpected that the Canvas interface from the gui package defines an API that you must use to work with the rust backend.

In essence that means it's actually a type defined by the rust backend, that is implemented by the gui package. That's the unclear part.

[almarklein]

I don't think we can get it much more minimal than this.