From 959cddb8d49af7a3a9b48eccb1f4eca5d0f5a812 Mon Sep 17 00:00:00 2001 From: Almar Klein Date: Mon, 9 Dec 2024 16:23:45 +0100 Subject: [PATCH] Add backend overview to docs (#43) --- docs/backends.rst | 64 +++++++++++++++++++++++++++++++++++++++ rendercanvas/glfw.py | 2 +- rendercanvas/jupyter.py | 2 +- rendercanvas/offscreen.py | 6 ++-- rendercanvas/qt.py | 2 +- rendercanvas/stub.py | 2 +- rendercanvas/wx.py | 2 +- tests/test_backends.py | 2 +- tests/test_context.py | 2 +- tests/test_offscreen.py | 12 ++++---- 10 files changed, 80 insertions(+), 16 deletions(-) diff --git a/docs/backends.rst b/docs/backends.rst index 03cfc0a..ae48e2a 100644 --- a/docs/backends.rst +++ b/docs/backends.rst @@ -1,6 +1,70 @@ Backends ======== +Overview +-------- + +The table below gives an overview of the names in the different ``rendercanvas`` backend modules. + +.. list-table:: + + * - **backend module** + - **names** + - **purpose** + * - ``auto`` + - | ``RenderCanvas`` + | ``loop`` + - | Select a backend automatically. + * - ``glfw`` + - | ``GlfwRenderCanvas`` + | ``RenderCanvas`` (alias) + | ``loop`` (an ``AsyncioLoop``) + - | A lightweight backend. + * - ``jupyter`` + - | ``JupyterRenderCanvas`` + | ``RenderCanvas`` (alias) + | ``loop`` (an ``AsyncioLoop``) + - | Integrate in Jupyter notebook / lab. + * - ``offscreen`` + - | ``OffscreenRenderCanvas`` + | ``RenderCanvas`` (alias) + | ``loop`` (a ``StubLoop``) + - | For offscreen rendering. + * - ``qt`` + - | ``QRenderCanvas`` (toplevel) + | ``RenderCanvas`` (alias) + | ``QRenderWidget`` (subwidget) + | ``QtLoop`` + | ``loop`` + - | Create a standalone canvas using Qt, or + | integrate a render canvas in a Qt application. + * - ``wx`` + - | ``WxRenderCanvas`` (toplevel) + | ``RenderCanvas`` (alias) + | ``WxRenderWidget`` (subwidget) + | ``WxLoop`` + | ``loop`` + - | Create a standalone canvas using wx, or + | integrate a render canvas in a wx application. + + +There are also two loop-backends. These are mainly intended for use with the glfw backend: + +.. list-table:: + + * - **backend module** + - **names** + - **purpose** + * - ``asyncio`` + - | ``AsyncoLoop`` + | ``loop`` + - | Provide a generic loop based on Asyncio. + * - ``trio`` + - | ``TrioLoop`` + | ``loop`` + - | Provide a loop based on Trio. + + The auto backend ----------------- diff --git a/rendercanvas/glfw.py b/rendercanvas/glfw.py index 35ef8b1..159335d 100644 --- a/rendercanvas/glfw.py +++ b/rendercanvas/glfw.py @@ -7,7 +7,7 @@ or ``sudo apt install libglfw3-wayland`` when using Wayland. """ -__all__ = ["RenderCanvas", "loop"] +__all__ = ["GlfwRenderCanvas", "RenderCanvas", "loop"] import sys import time diff --git a/rendercanvas/jupyter.py b/rendercanvas/jupyter.py index fe77296..f09c2cc 100644 --- a/rendercanvas/jupyter.py +++ b/rendercanvas/jupyter.py @@ -3,7 +3,7 @@ can be used as cell output, or embedded in an ipywidgets gui. """ -__all__ = ["RenderCanvas", "loop"] +__all__ = ["JupyterRenderCanvas", "RenderCanvas", "loop"] import time diff --git a/rendercanvas/offscreen.py b/rendercanvas/offscreen.py index 513c07c..e0269c9 100644 --- a/rendercanvas/offscreen.py +++ b/rendercanvas/offscreen.py @@ -2,7 +2,7 @@ Offscreen canvas. No scheduling. """ -__all__ = ["RenderCanvas", "loop"] +__all__ = ["OffscreenRenderCanvas", "RenderCanvas", "loop"] import time @@ -13,7 +13,7 @@ class OffscreenCanvasGroup(BaseCanvasGroup): pass -class ManualOffscreenRenderCanvas(BaseRenderCanvas): +class OffscreenRenderCanvas(BaseRenderCanvas): """An offscreen canvas intended for manual use. Call the ``.draw()`` method to perform a draw and get the result. @@ -90,7 +90,7 @@ def draw(self): return self._last_image -RenderCanvas = ManualOffscreenRenderCanvas +RenderCanvas = OffscreenRenderCanvas class StubLoop(BaseLoop): diff --git a/rendercanvas/qt.py b/rendercanvas/qt.py index 7a7ea45..20351d1 100644 --- a/rendercanvas/qt.py +++ b/rendercanvas/qt.py @@ -3,7 +3,7 @@ can be used as a standalone window or in a larger GUI. """ -__all__ = ["QRenderWidget", "RenderCanvas", "RenderWidget", "loop"] +__all__ = ["QRenderCanvas", "QRenderWidget", "QtLoop", "RenderCanvas", "loop"] import sys import ctypes diff --git a/rendercanvas/stub.py b/rendercanvas/stub.py index 4054d7b..89d59fc 100644 --- a/rendercanvas/stub.py +++ b/rendercanvas/stub.py @@ -2,7 +2,7 @@ A stub backend for documentation purposes. """ -__all__ = ["RenderCanvas", "loop"] +__all__ = ["RenderCanvas", "StubLoop", "StubRenderCanvas", "loop"] from .base import BaseCanvasGroup, WrapperRenderCanvas, BaseRenderCanvas, BaseLoop diff --git a/rendercanvas/wx.py b/rendercanvas/wx.py index d2625d9..5486dec 100644 --- a/rendercanvas/wx.py +++ b/rendercanvas/wx.py @@ -3,7 +3,7 @@ can be used as a standalone window or in a larger GUI. """ -__all__ = ["RenderCanvas", "RenderWidget", "WxRenderWidget", "loop"] +__all__ = ["RenderCanvas", "WxLoop", "WxRenderCanvas", "WxRenderWidget", "loop"] import sys import time diff --git a/tests/test_backends.py b/tests/test_backends.py index b2e0eba..9d923c9 100644 --- a/tests/test_backends.py +++ b/tests/test_backends.py @@ -251,7 +251,7 @@ def test_offscreen_module(): canvas_class = m.get_canvas_class() m.check_canvas(canvas_class) - assert canvas_class.name == "ManualOffscreenRenderCanvas" + assert canvas_class.name == "OffscreenRenderCanvas" def test_qt_module(): diff --git a/tests/test_context.py b/tests/test_context.py index 0e9b5d4..39829c9 100644 --- a/tests/test_context.py +++ b/tests/test_context.py @@ -1,7 +1,7 @@ import numpy as np from rendercanvas.utils.bitmappresentadapter import BitmapPresentAdapter from rendercanvas.utils.bitmaprenderingcontext import BitmapRenderingContext -from rendercanvas.offscreen import ManualOffscreenRenderCanvas +from rendercanvas.offscreen import OffscreenRenderCanvas as ManualOffscreenRenderCanvas from testutils import can_use_wgpu_lib, run_tests import pytest diff --git a/tests/test_offscreen.py b/tests/test_offscreen.py index 432c56d..ffcca1c 100644 --- a/tests/test_offscreen.py +++ b/tests/test_offscreen.py @@ -11,7 +11,7 @@ def test_offscreen_selection_using_env_var(): - from rendercanvas.offscreen import ManualOffscreenRenderCanvas + from rendercanvas.offscreen import OffscreenRenderCanvas ori = os.getenv("RENDERCANVAS_FORCE_OFFSCREEN") os.environ["RENDERCANVAS_FORCE_OFFSCREEN"] = "1" @@ -24,12 +24,12 @@ def test_offscreen_selection_using_env_var(): for value in ["", "0", "false", "False", "wut"]: os.environ["RENDERCANVAS_FORCE_OFFSCREEN"] = value module = select_backend() - assert module.RenderCanvas is not ManualOffscreenRenderCanvas + assert module.RenderCanvas is not OffscreenRenderCanvas for value in ["1", "true", "True"]: os.environ["RENDERCANVAS_FORCE_OFFSCREEN"] = value module = select_backend() - assert module.RenderCanvas is ManualOffscreenRenderCanvas + assert module.RenderCanvas is OffscreenRenderCanvas finally: if ori is not None: @@ -37,7 +37,7 @@ def test_offscreen_selection_using_env_var(): def test_offscreen_selection_using_legacyt_env_var(): - from rendercanvas.offscreen import ManualOffscreenRenderCanvas + from rendercanvas.offscreen import OffscreenRenderCanvas ori1 = os.getenv("RENDERCANVAS_FORCE_OFFSCREEN") ori2 = os.getenv("WGPU_FORCE_OFFSCREEN") @@ -53,12 +53,12 @@ def test_offscreen_selection_using_legacyt_env_var(): for value in ["", "0", "false", "False", "wut"]: os.environ["WGPU_FORCE_OFFSCREEN"] = value module = select_backend() - assert module.RenderCanvas is not ManualOffscreenRenderCanvas + assert module.RenderCanvas is not OffscreenRenderCanvas for value in ["1", "true", "True"]: os.environ["WGPU_FORCE_OFFSCREEN"] = value module = select_backend() - assert module.RenderCanvas is ManualOffscreenRenderCanvas + assert module.RenderCanvas is OffscreenRenderCanvas finally: if ori1 is not None: