Implement own context classes (#127)

Author: almarklein

.github/workflows/ci.yml

@@ -125,7 +125,7 @@ jobs:
         "
         pytest -v tests
 
-  test-examples-build:
+  test-examples:
     name: Test examples ${{ matrix.pyversion }}
     runs-on: ${{ matrix.os }}
     strategy:
@@ -183,8 +183,8 @@ jobs:
         pushd $HOME
         pytest -v --pyargs rendercanvas.__pyinstaller
 
-  release:
-    name: Build release on ubuntu-latest
+  build-release:
+    name: Build release artifacts
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -227,7 +227,7 @@ jobs:
   publish:
     name: Publish release to Github and Pypi
     runs-on: ubuntu-latest
-    needs: [tests, release]
+    needs: [tests, build-release]
     if: success() && startsWith(github.ref, 'refs/tags/v')
     environment:
       name: pypi

README.md

@@ -61,7 +61,7 @@ import numpy as np
 from rendercanvas.auto import RenderCanvas, loop
 
 canvas = RenderCanvas(update_mode="continuous")
-context = canvas.get_context("bitmap")
+context = canvas.get_bitmap_context()
 
 @canvas.request_draw
 def animate():

docs/api.rst

@@ -1,5 +1,5 @@
-API
-===
+Canvas API
+==========
 
 These are the classes that make up the rendercanvas API:
 

docs/conf.py

@@ -25,8 +25,7 @@
 # Load wgpu so autodoc can query docstrings
 import rendercanvas  # noqa: E402
 import rendercanvas.stub  # noqa: E402 - we use the stub backend to generate docs
-import rendercanvas._context  # noqa: E402 - we use the ContextInterface to generate docs
-import rendercanvas.utils.bitmappresentadapter  # noqa: E402
+
 
 # -- Project information -----------------------------------------------------
 

docs/contextapi.rst

@@ -1,7 +1,7 @@
 How context objects work
 ========================
 
-This page documents the working bentween the ``RenderCanvas`` and the context object.
+This page documents the inner working between the ``RenderCanvas`` and the context object.
 
 
 Introduction
@@ -23,16 +23,13 @@ then present the result to the screen. For this, the canvas provides one or more
                 │         │  ──bitmap──►  │        │
                 └─────────┘               └────────┘
 
-This means that for the context to be able to present to any canvas, it must
-support *both* the 'bitmap' and 'screen' present-methods. If the context prefers
-presenting to the screen, and the canvas supports that, all is well. Similarly,
-if the context has a bitmap to present, and the canvas supports the
-bitmap-method, there's no problem.
+If the context is a ``BitmapContext``, and the canvas supports the bitmap present-method,
+things are easy. Similarly, if the context is a ``WgpuContext``, and the canvas
+supports the screen present-method, the presenting is simply delegated to wgpu.
 
-It get's a little trickier when there's a mismatch, but we can deal with these
-cases too. When the context prefers presenting to screen, the rendered result is
-probably a texture on the GPU. This texture must then be downloaded to a bitmap
-on the CPU. All GPU API's have ways to do this.
+When there's a mismatch, we use different context sub-classes that handle the conversion.
+With the ``WgpuContextToBitmap`` context, the rendered result is inside a texture on the GPU.
+This texture is then downloaded to a bitmap on the CPU that can be passed to the canvas.
 
 .. code-block::
 
@@ -41,11 +38,10 @@ on the CPU. All GPU API's have ways to do this.
     ──render──► | Context │        |            │ Canvas │
                 │         │        └─bitmap──►  │        |
                 └─────────┘                     └────────┘
-                         download from gpu to cpu
+                              download to CPU
 
-If the context has a bitmap to present, and the canvas only supports presenting
-to screen, you can use a small utility: the ``BitmapPresentAdapter`` takes a
-bitmap and presents it to the screen.
+With the ``BitmapContextToScreen`` context, the bitmap is uploaded to a GPU texture,
+which is then rendered to screen using the lower-level canvas-context from ``wgpu``.
 
 .. code-block::
 
@@ -54,46 +50,6 @@ bitmap and presents it to the screen.
     ──render──► | Context │           │            │ Canvas │
                 │         │  ──bitmap─┘            │        |
                 └─────────┘                        └────────┘
-                          use BitmapPresentAdapter
+                               upload to GPU
 
 This way, contexts can be made to work with all canvas backens.
-
-Canvases may also provide additionally present-methods. If a context knows how to
-use that present-method, it can make use of it. Examples could be presenting
-diff images or video streams.
-
-.. code-block::
-
-                ┌─────────┐                               ┌────────┐
-                │         │                               │        │
-    ──render──► | Context │  ──special-present-method──►  │ Canvas │
-                │         │                               │        |
-                └─────────┘                               └────────┘
-
-
-Context detection
------------------
-
-Anyone can make a context that works with ``rendercanvas``. In order for ``rendercanvas`` to find, it needs a little hook.
-
-.. autofunction:: rendercanvas._context.rendercanvas_context_hook
-    :no-index:
-
-
-Context API
------------
-
-The class below describes the API and behavior that is expected of a context object.
-Also see https://github.com/pygfx/rendercanvas/blob/main/rendercanvas/_context.py.
-
-.. autoclass:: rendercanvas._context.ContextInterface
-    :members:
-    :no-index:
-
-
-Adapter
--------
-
-.. autoclass:: rendercanvas.utils.bitmappresentadapter.BitmapPresentAdapter
-    :members:
-    :no-index:

docs/contexts.rst

@@ -0,0 +1,13 @@
+Context API
+===========
+
+.. automodule:: rendercanvas.contexts
+
+.. autoclass:: rendercanvas.contexts.BaseContext
+    :members:
+
+.. autoclass:: rendercanvas.contexts.BitmapContext
+    :members:
+
+.. autoclass:: rendercanvas.contexts.WgpuContext
+    :members:

docs/index.rst

@@ -9,6 +9,7 @@ Welcome to the rendercanvas docs!
 
     start
     api
+    contexts
     backends
     utils
     Gallery <gallery/index.rst>

docs/start.rst

@@ -50,7 +50,7 @@ Rendering using bitmaps:
 
 .. code-block:: py
 
-    context = canvas.get_context("bitmap")
+    context = canvas.get_bitmap_context()
 
     @canvas.request_draw
     def animate():
@@ -61,7 +61,7 @@ Rendering with wgpu:
 
 .. code-block:: py
 
-    context = canvas.get_context("wgpu")
+    context = canvas.get_wgpu_context()
     context.configure(device)
 
     @canvas.request_draw

docs/utils.rst

@@ -7,5 +7,3 @@ Utils
 
     utils_asyncs
     utils_cube
-    utils_bitmappresentadapter.rst
-    utils_bitmaprenderingcontext.rst