Refactor wgpu.gui for scheduling

README.md

@@ -81,7 +81,7 @@ To render to the screen you can use a variety of GUI toolkits:
 
 ```py
 # The auto backend selects either the glfw, qt or jupyter backend
-from wgpu.gui.auto import WgpuCanvas, run, call_later
+from wgpu.gui.auto import WgpuCanvas, loop
 
 # Visualizations can be embedded as a widget in a Qt application.
 # Import PySide6, PyQt6, PySide2 or PyQt5 before running the line below.

docs/conf.py

@@ -109,7 +109,11 @@ def resolve_crossrefs(text):
         cls.__doc__ = docs or None
         # Docstring of methods
         for method in cls.__dict__.values():
-            if callable(method) and hasattr(method, "__code__"):
+            if (
+                callable(method)
+                and hasattr(method, "__code__")
+                and not method.__name__.startswith("_")
+            ):
                 docs = resolve_crossrefs(method.__doc__)
                 if (
                     method.__code__.co_argcount == 1

docs/gui.rst

@@ -20,14 +20,20 @@ The Canvas base classes
 
     ~WgpuCanvasInterface
     ~WgpuCanvasBase
-    ~WgpuAutoGui
 
 
 For each supported GUI toolkit there is a module that implements a ``WgpuCanvas`` class,
 which inherits from :class:`WgpuCanvasBase`, providing a common API.
-The GLFW, Qt, and Jupyter backends also inherit from  :class:`WgpuAutoGui` to include
-support for events (interactivity). In the next sections we demonstrates the different
-canvas classes that you can use.
+
+
+Events
+------
+
+To implement interaction with a ``WgpuCanvas``, use the :func:`WgpuCanvasBase.add_event_handler()` method.
+Events come in the following flavours:
+
+.. autoclass:: WgpuEventType
+    :members:
 
 
 The auto GUI backend
@@ -39,22 +45,16 @@ across different machines and environments. Using ``wgpu.gui.auto`` selects a
 suitable backend depending on the environment and more. See
 :ref:`interactive_use` for details.
 
-To implement interaction, the ``canvas`` has a :func:`WgpuAutoGui.handle_event()` method
-that can be overloaded. Alternatively you can use it's :func:`WgpuAutoGui.add_event_handler()`
-method. See the `event spec <https://jupyter-rfb.readthedocs.io/en/stable/events.html>`_
-for details about the event objects.
-
-Also see the `triangle auto <https://github.com/pygfx/wgpu-py/blob/main/examples/triangle_auto.py>`_
-and `cube <https://github.com/pygfx/wgpu-py/blob/main/examples/cube.py>`_ examples that demonstrate the auto gui.
+Also see the e.g. the `gui_auto.py <https://github.com/pygfx/wgpu-py/blob/main/examples/gui_auto.py>`_ example.
 
 .. code-block:: py
 
-    from wgpu.gui.auto import WgpuCanvas, run, call_later
+    from wgpu.gui.auto import WgpuCanvas, loop
 
     canvas = WgpuCanvas(title="Example")
     canvas.request_draw(your_draw_function)
 
-    run()
+    loop.run()
 
 
 Support for GLFW
@@ -66,12 +66,12 @@ but you can replace ``from wgpu.gui.auto`` with ``from wgpu.gui.glfw`` to force
 
 .. code-block:: py
 
-    from wgpu.gui.glfw import WgpuCanvas, run, call_later
+    from wgpu.gui.glfw import WgpuCanvas, loop
 
     canvas = WgpuCanvas(title="Example")
     canvas.request_draw(your_draw_function)
 
-    run()
+    loop.run()
 
 
 Support for Qt

docs/guide.rst

@@ -19,7 +19,7 @@ GUI toolkits are supported, see the :doc:`gui`. In general, it's easiest to let
 
 .. code-block:: py
 
-    from wgpu.gui.auto import WgpuCanvas, run
+    from wgpu.gui.auto import WgpuCanvas
 
     canvas = WgpuCanvas(title="a wgpu example")
 

examples/gui_auto.py

@@ -4,7 +4,7 @@
 
 # test_example = true
 
-from wgpu.gui.auto import WgpuCanvas, run
+from wgpu.gui.auto import WgpuCanvas, loop
 
 from triangle import setup_drawing_sync
 # from cube import setup_drawing_sync
@@ -21,4 +21,4 @@ def animate():
 
 
 if __name__ == "__main__":
-    run()
+    loop.run()

examples/gui_demo.py

@@ -0,0 +1,55 @@
+"""
+An example that uses events to trigger some canvas functionality.
+
+A nice demo, and very convenient to test the different backends.
+
+* Can be closed with Escape or by pressing the window close button.
+* In both cases, it should print "Close detected" exactly once.
+* Hit space to spend 2 seconds doing direct draws.
+
+"""
+
+import time
+
+from wgpu.gui.auto import WgpuCanvas, loop
+
+from cube import setup_drawing_sync
+
+
+canvas = WgpuCanvas(
+    size=(640, 480),
+    title="Canvas events on $backend - $fps fps",
+    max_fps=10,
+    update_mode="continuous",
+    present_method="",
+)
+
+
+draw_frame = setup_drawing_sync(canvas)
+canvas.request_draw(lambda: (draw_frame(), canvas.request_draw()))
+
+
+@canvas.add_event_handler("*")
+def process_event(event):
+    if event["event_type"] not in ["pointer_move", "before_draw", "animate"]:
+        print(event)
+
+    if event["event_type"] == "key_down":
+        if event["key"] == "Escape":
+            canvas.close()
+        elif event["key"] == " ":
+            etime = time.time() + 2
+            i = 0
+            while time.time() < etime:
+                i += 1
+                canvas.force_draw()
+            print(f"force-drawed {i} frames in 2s.")
+    elif event["event_type"] == "close":
+        # Should see this exactly once, either when pressing escape, or
+        # when pressing the window close button.
+        print("Close detected!")
+        assert canvas.is_closed()
+
+
+if __name__ == "__main__":
+    loop.run()

examples/gui_events.py

@@ -2,17 +2,25 @@
 A simple example to demonstrate events.
 """
 
-from wgpu.gui.auto import WgpuCanvas, run
+from wgpu.gui.auto import WgpuCanvas, loop
 
+from cube import setup_drawing_sync
 
-canvas = WgpuCanvas(size=(640, 480), title="wgpu events")
+
+canvas = WgpuCanvas(
+    size=(640, 480), title="Canvas events on $backend", update_mode="continuous"
+)
+
+
+draw_frame = setup_drawing_sync(canvas)
+canvas.request_draw(draw_frame)
 
 
 @canvas.add_event_handler("*")
 def process_event(event):
-    if event["event_type"] != "pointer_move":
+    if event["event_type"] not in ["pointer_move", "before_draw", "animate"]:
         print(event)
 
 
 if __name__ == "__main__":
-    run()
+    loop.run()

examples/gui_glfw.py

@@ -4,7 +4,7 @@
 
 # run_example = false
 
-from wgpu.gui.glfw import WgpuCanvas, run
+from wgpu.gui.glfw import WgpuCanvas
 
 from triangle import setup_drawing_sync
 # from cube import setup_drawing_sync
@@ -17,8 +17,8 @@
 @canvas.request_draw
 def animate():
     draw_frame()
-    canvas.request_draw()
+    # canvas.request_draw()
 
 
 if __name__ == "__main__":
-    run()
+    canvas.loop.run()

examples/gui_multiple.py

@@ -0,0 +1,23 @@
+"""
+Run triangle and cube examples two canvases.
+"""
+
+# test_example = true
+
+from wgpu.gui.auto import WgpuCanvas, loop
+
+from triangle import setup_drawing_sync as setup_drawing_sync_triangle
+from cube import setup_drawing_sync as setup_drawing_sync_cube
+
+
+canvas1 = WgpuCanvas(title=f"Triangle example on {WgpuCanvas.__name__}")
+draw_frame1 = setup_drawing_sync_triangle(canvas1)
+canvas1.request_draw(draw_frame1)
+
+canvas2 = WgpuCanvas(title=f"Cube example on {WgpuCanvas.__name__}")
+draw_frame2 = setup_drawing_sync_cube(canvas2)
+canvas2.request_draw(draw_frame2)
+
+
+if __name__ == "__main__":
+    loop.run()

examples/gui_qt.py

@@ -22,15 +22,18 @@
 
 
 app = QtWidgets.QApplication([])
-canvas = WgpuCanvas(title=f"Triangle example on {WgpuCanvas.__name__}")
+canvas = WgpuCanvas(
+    title=f"Triangle example on {WgpuCanvas.__name__}",
+    # present_method="image"
+)
 
 draw_frame = setup_drawing_sync(canvas)
 
 
 @canvas.request_draw
 def animate():
     draw_frame()
-    canvas.request_draw()
+    # canvas.request_draw()
 
 
 # Enter Qt event loop (compatible with qt5/qt6)

examples/gui_threading.py

@@ -0,0 +1,52 @@
+"""
+Example that renders frames in a separate thread.
+
+This uses an offscreen canvas, the result is only used to print the
+frame shape. But one can see how one can e.g. render a movie this way.
+
+Threaded rendering using a real GUI is not supported right now, since
+this is tricky to do with both Qt and glfw. Plus in general its a bad
+idea to run your UI in anything other than the main thread. In other
+words, you should probably only use threaded rendering for off-screen
+stuff.
+
+"""
+
+# test_example = true
+
+import time
+import threading
+
+from wgpu.gui.offscreen import WgpuCanvas
+
+from cube import setup_drawing_sync
+
+
+# create canvas
+canvas = WgpuCanvas()
+draw_frame = setup_drawing_sync(canvas)
+
+
+def main():
+    frame_count = 0
+    canvas.request_draw(draw_frame)
+
+    while not canvas.is_closed():
+        image = canvas.draw()
+        frame_count += 1
+        print(f"Rendered {frame_count} frames, last shape is {image.shape}")
+
+
+if __name__ == "__main__":
+    t1 = threading.Thread(target=main)
+    t1.start()
+
+    # In the main thread, we wait a little
+    time.sleep(1)
+
+    # ... then change the canvas size, and wait some more
+    canvas.set_logical_size(200, 200)
+    time.sleep(1)
+
+    # Close the canvas to stop the tread
+    canvas.close()

tests/renderutils.py

@@ -233,7 +233,7 @@ def render_to_screen(
 ):
     """Render to a window on screen, for debugging purposes."""
     import glfw
-    from wgpu.gui.glfw import WgpuCanvas, update_glfw_canvasses
+    from wgpu.gui.glfw import WgpuCanvas, loop
 
     vbos = vbos or []
     vbo_views = vbo_views or []
@@ -327,6 +327,4 @@ def draw_frame():
     canvas.request_draw(draw_frame)
 
     # Enter main loop
-    while update_glfw_canvasses():
-        glfw.poll_events()
-    glfw.terminate()
+    loop.run()