rendercanvas 1.0.0__tar.gz

rendercanvas-1.0.0/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2019-2024, Almar Klein, Korijn van Golen
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

rendercanvas-1.0.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.1
+Name: rendercanvas
+Version: 1.0.0
+Summary: One canvas API, multiple backends
+Keywords: canvas,rendering,graphics,wgpu,qt,wx,glfw,jupyter
+Author: Almar Klein, Korijn van Golen
+Requires-Python: >= 3.9
+Description-Content-Type: text/markdown
+Requires-Dist: rendercanvas[lint,tests,examples,docs] ; extra == "dev"
+Requires-Dist: sphinx>7.2 ; extra == "docs"
+Requires-Dist: sphinx_rtd_theme ; extra == "docs"
+Requires-Dist: sphinx-gallery ; extra == "docs"
+Requires-Dist: numpy ; extra == "docs"
+Requires-Dist: wgpu ; extra == "docs"
+Requires-Dist: numpy ; extra == "examples"
+Requires-Dist: wgpu ; extra == "examples"
+Requires-Dist: glfw ; extra == "examples"
+Requires-Dist: pyside6 ; extra == "examples"
+Requires-Dist: glfw>=1.9 ; extra == "glfw"
+Requires-Dist: jupyter_rfb>=0.4.2 ; extra == "jupyter"
+Requires-Dist: ruff ; extra == "lint"
+Requires-Dist: pre-commit ; extra == "lint"
+Requires-Dist: pytest ; extra == "tests"
+Requires-Dist: numpy ; extra == "tests"
+Requires-Dist: wgpu ; extra == "tests"
+Requires-Dist: glfw ; extra == "tests"
+Project-URL: Documentation, https://rendercanvas.readthedocs.io
+Project-URL: Homepage, https://github.com/pygfx/rendercanvas
+Project-URL: Repository, https://github.com/pygfx/rendercanvas
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: examples
+Provides-Extra: glfw
+Provides-Extra: jupyter
+Provides-Extra: lint
+Provides-Extra: tests
+
+[![CI](https://github.com/pygfx/rendercanvas/workflows/CI/badge.svg)](https://github.com/pygfx/rendercanvas/actions)
+[![Documentation Status](https://readthedocs.org/projects/rendercanvas/badge/?version=stable)](https://rendercanvas.readthedocs.io)
+[![PyPI version](https://badge.fury.io/py/rendercanvas.svg)](https://badge.fury.io/py/rendercanvas)
+[![EffVer Versioning](https://img.shields.io/badge/version_scheme-EffVer-0097a7)](https://jacobtomlinson.dev/effver)
+
+
+# rendercanvas
+
+One canvas API, multiple backends 🚀
+
+<div>
+  <img width=354 src='https://github.com/user-attachments/assets/42656d13-0d81-47dd-b9c7-d76da8cfa6c1' />
+  <img width=354 src='https://github.com/user-attachments/assets/af8eefe0-4485-4daf-9fbd-36710e44f07c' />
+</div>
+
+*This project is part of [pygfx.org](https://pygfx.org)*
+
+
+## Introduction
+
+See how the two windows above look the same? That's the idea; they also look the
+same to the code that renders to them. Yet, the GUI systems are very different
+(Qt vs glfw in this case). Now that's a powerful abstraction!
+
+
+## Purpose
+
+* Provide a generic canvas API to render to.
+* Provide an event loop for scheduling events and draws.
+* Provide a simple but powerful event system with standardized event objects.
+* Provide various canvas implementations:
+  * One that is light and easily installed (glfw).
+  * For various GUI libraries (e.g. qt and wx), so visuzalizations can be embedded in a GUI.
+  * For specific platforms (e.g. Jupyter, browser).
+
+
+The main use-case is rendering with [wgpu](https://github.com/pygfx/wgpu-py),
+but ``rendercanvas``can be used by anything that can render based on a window-id or
+by producing bitmap images.
+
+
+## Installation
+
+```
+pip install rendercanvas
+```
+
+To have at least one backend, we recommend:
+```
+pip install rendercanvas glfw
+```
+
+## Usage
+
+Also see the [online documentation](https://rendercanvas.readthedocs.io) and the [examples](https://github.com/pygfx/rendercanvas/tree/main/examples).
+
+A minimal example that renders noise:
+```py
+import numpy as np
+from rendercanvas.auto import RenderCanvas, loop
+
+canvas = RenderCanvas(update_mode="continuous")
+context = canvas.get_context("bitmap")
+
+@canvas.request_draw
+def animate():
+    w, h = canvas.get_logical_size()
+    bitmap = np.random.uniform(0, 255, (h, w)).astype(np.uint8)
+    context.set_bitmap(bitmap)
+
+loop.run()
+```
+
+Run wgpu visualizations:
+```py
+from rendercanvas.auto import RenderCanvas, loop
+from rendercanvas.utils.cube import setup_drawing_sync
+
+
+canvas = RenderCanvas(
+    title="The wgpu cube example on $backend", update_mode="continuous"
+)
+draw_frame = setup_drawing_sync(canvas)
+canvas.request_draw(draw_frame)
+
+loop.run()
+````
+
+Embed in a Qt application:
+```py
+from PySide6 import QtWidgets
+from rendercanvas.qt import QRenderWidget
+
+class Main(QtWidgets.QWidget):
+
+    def __init__(self):
+        super().__init__()
+
+        splitter = QtWidgets.QSplitter()
+        self.canvas = QRenderWidget(splitter)
+        ...
+
+
+app = QtWidgets.QApplication([])
+main = Main()
+app.exec()
+```
+
+
+## License
+
+This code is distributed under the 2-clause BSD license.
+
+
+## Developers
+
+* Clone the repo.
+* Install `rendercanvas` and developer deps using `pip install -e .[dev]`.
+* Use `ruff format` to apply autoformatting.
+* Use `ruff check` to check for linting errors.
+* Optionally, if you install [pre-commit](https://github.com/pre-commit/pre-commit/) hooks with `pre-commit install`, lint fixes and formatting will be automatically applied on `git commit`.
+* Use `pytest tests` to run the tests.
+

rendercanvas-1.0.0/README.md

@@ -0,0 +1,122 @@
+[![CI](https://github.com/pygfx/rendercanvas/workflows/CI/badge.svg)](https://github.com/pygfx/rendercanvas/actions)
+[![Documentation Status](https://readthedocs.org/projects/rendercanvas/badge/?version=stable)](https://rendercanvas.readthedocs.io)
+[![PyPI version](https://badge.fury.io/py/rendercanvas.svg)](https://badge.fury.io/py/rendercanvas)
+[![EffVer Versioning](https://img.shields.io/badge/version_scheme-EffVer-0097a7)](https://jacobtomlinson.dev/effver)
+
+
+# rendercanvas
+
+One canvas API, multiple backends 🚀
+
+<div>
+  <img width=354 src='https://github.com/user-attachments/assets/42656d13-0d81-47dd-b9c7-d76da8cfa6c1' />
+  <img width=354 src='https://github.com/user-attachments/assets/af8eefe0-4485-4daf-9fbd-36710e44f07c' />
+</div>
+
+*This project is part of [pygfx.org](https://pygfx.org)*
+
+
+## Introduction
+
+See how the two windows above look the same? That's the idea; they also look the
+same to the code that renders to them. Yet, the GUI systems are very different
+(Qt vs glfw in this case). Now that's a powerful abstraction!
+
+
+## Purpose
+
+* Provide a generic canvas API to render to.
+* Provide an event loop for scheduling events and draws.
+* Provide a simple but powerful event system with standardized event objects.
+* Provide various canvas implementations:
+  * One that is light and easily installed (glfw).
+  * For various GUI libraries (e.g. qt and wx), so visuzalizations can be embedded in a GUI.
+  * For specific platforms (e.g. Jupyter, browser).
+
+
+The main use-case is rendering with [wgpu](https://github.com/pygfx/wgpu-py),
+but ``rendercanvas``can be used by anything that can render based on a window-id or
+by producing bitmap images.
+
+
+## Installation
+
+```
+pip install rendercanvas
+```
+
+To have at least one backend, we recommend:
+```
+pip install rendercanvas glfw
+```
+
+## Usage
+
+Also see the [online documentation](https://rendercanvas.readthedocs.io) and the [examples](https://github.com/pygfx/rendercanvas/tree/main/examples).
+
+A minimal example that renders noise:
+```py
+import numpy as np
+from rendercanvas.auto import RenderCanvas, loop
+
+canvas = RenderCanvas(update_mode="continuous")
+context = canvas.get_context("bitmap")
+
+@canvas.request_draw
+def animate():
+    w, h = canvas.get_logical_size()
+    bitmap = np.random.uniform(0, 255, (h, w)).astype(np.uint8)
+    context.set_bitmap(bitmap)
+
+loop.run()
+```
+
+Run wgpu visualizations:
+```py
+from rendercanvas.auto import RenderCanvas, loop
+from rendercanvas.utils.cube import setup_drawing_sync
+
+
+canvas = RenderCanvas(
+    title="The wgpu cube example on $backend", update_mode="continuous"
+)
+draw_frame = setup_drawing_sync(canvas)
+canvas.request_draw(draw_frame)
+
+loop.run()
+````
+
+Embed in a Qt application:
+```py
+from PySide6 import QtWidgets
+from rendercanvas.qt import QRenderWidget
+
+class Main(QtWidgets.QWidget):
+
+    def __init__(self):
+        super().__init__()
+
+        splitter = QtWidgets.QSplitter()
+        self.canvas = QRenderWidget(splitter)
+        ...
+
+
+app = QtWidgets.QApplication([])
+main = Main()
+app.exec()
+```
+
+
+## License
+
+This code is distributed under the 2-clause BSD license.
+
+
+## Developers
+
+* Clone the repo.
+* Install `rendercanvas` and developer deps using `pip install -e .[dev]`.
+* Use `ruff format` to apply autoformatting.
+* Use `ruff check` to check for linting errors.
+* Optionally, if you install [pre-commit](https://github.com/pre-commit/pre-commit/) hooks with `pre-commit install`, lint fixes and formatting will be automatically applied on `git commit`.
+* Use `pytest tests` to run the tests.

rendercanvas-1.0.0/pyproject.toml

@@ -0,0 +1,61 @@
+# ===== Project info
+
+[project]
+dynamic = ["version"]
+name = "rendercanvas"
+description = "One canvas API, multiple backends"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Almar Klein" }, { name = "Korijn van Golen" }]
+keywords = [
+    "canvas",
+    "rendering",
+    "graphics",
+    "wgpu",
+    "qt",
+    "wx",
+    "glfw",
+    "jupyter",
+]
+requires-python = ">= 3.9"
+dependencies = [] # no dependencies!
+[project.optional-dependencies]
+# For users
+jupyter = ["jupyter_rfb>=0.4.2"]
+glfw = ["glfw>=1.9"]
+# For devs / ci
+lint = ["ruff", "pre-commit"]
+examples = ["numpy", "wgpu", "glfw", "pyside6"]
+docs = ["sphinx>7.2", "sphinx_rtd_theme", "sphinx-gallery", "numpy", "wgpu"]
+tests = ["pytest", "numpy", "wgpu", "glfw"]
+dev = ["rendercanvas[lint,tests,examples,docs]"]
+
+[project.entry-points."pyinstaller40"]
+hook-dirs = "rendercanvas.__pyinstaller:get_hook_dirs"
+tests = "rendercanvas.__pyinstaller:get_test_dirs"
+
+[project.urls]
+Homepage = "https://github.com/pygfx/rendercanvas"
+Documentation = "https://rendercanvas.readthedocs.io"
+Repository = "https://github.com/pygfx/rendercanvas"
+
+# ===== Building
+
+# Flit is great solution for simple pure-Python projects.
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+# ===== Tooling
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "N", "B", "RUF"]
+ignore = [
+    "E501",   # Line too long
+    "E731",   # Do not assign a `lambda` expression, use a `def`
+    "B007",   # Loop control variable `x` not used within loop body
+    "RUF012", # Mutable class attributes should be annotated with `typing.ClassVar`
+]

rendercanvas-1.0.0/rendercanvas/__init__.py

@@ -0,0 +1,17 @@
+"""
+RenderCanvas: one canvas API, multiple backends.
+"""
+
+# ruff: noqa: F401
+
+from ._version import __version__, version_info
+from . import _coreutils
+from ._events import EventType
+from .base import BaseRenderCanvas, BaseLoop, BaseTimer
+
+__all__ = [
+    "BaseRenderCanvas",
+    "EventType",
+    "BaseLoop",
+    "BaseTimer",
+]

rendercanvas-1.0.0/rendercanvas/__pyinstaller/__init__.py

@@ -0,0 +1,12 @@
+from os.path import dirname
+
+
+HERE = dirname(__file__)
+
+
+def get_hook_dirs():
+    return [HERE]
+
+
+def get_test_dirs():
+    return [HERE]

rendercanvas-1.0.0/rendercanvas/__pyinstaller/conftest.py

@@ -0,0 +1 @@
+from PyInstaller.utils.conftest import *  # noqa: F403

rendercanvas-1.0.0/rendercanvas/__pyinstaller/hook-rendercanvas.py

@@ -0,0 +1,22 @@
+# ruff: noqa: N999
+
+from PyInstaller.utils.hooks import collect_dynamic_libs
+
+# Init variables that PyInstaller will pick up.
+hiddenimports = []
+datas = []
+binaries = []
+
+# Add modules that are safe to add, i.e. don't pull in dependencies that we don't want.
+hiddenimports += ["rendercanvas.offscreen"]
+
+# Since glfw does not have a hook like this, it does not include the glfw binary
+# when freezing. We can solve this with the code below. Makes the binary a bit
+# larger, but only marginally (less than 300kb).
+try:
+    import glfw  # noqa: F401
+except ImportError:
+    pass
+else:
+    hiddenimports += ["rendercanvas.glfw"]
+    binaries += collect_dynamic_libs("glfw")

rendercanvas-1.0.0/rendercanvas/__pyinstaller/test_rendercanvas.py

@@ -0,0 +1,47 @@
+script = """
+# The script part
+import sys
+import importlib
+
+from rendercanvas.auto import RenderCanvas
+
+if "glfw" not in RenderCanvas.__name__.lower():
+    raise RuntimeError(f"Expected a glfw canvas, got {RenderCanvas.__name__}")
+
+# The test part
+if "is_test" in sys.argv:
+    included_modules = [
+        "rendercanvas.glfw",
+        "rendercanvas.offscreen",
+        "glfw",
+    ]
+    excluded_modules = [
+        "PySide6.QtGui",
+        "PyQt6.QtGui",
+    ]
+    for module_name in included_modules:
+        importlib.import_module(module_name)
+    for module_name in excluded_modules:
+        try:
+            importlib.import_module(module_name)
+        except ModuleNotFoundError:
+            continue
+        raise RuntimeError(module_name + " is not supposed to be importable.")
+"""
+
+
+def test_pyi_rendercanvas(pyi_builder):
+    pyi_builder.test_source(script, app_args=["is_test"])
+
+
+# We could also test the script below, but it's not that interesting since it uses direct imports.
+# To safe CI-time we don't actively test it.
+script_qt = """
+import sys
+import importlib
+
+import PySide6
+from rendercanvas.qt import RenderCanvas
+
+assert "qt" in RenderCanvas.__name__.lower()
+"""

rendercanvas-1.0.0/rendercanvas/_context.py

@@ -0,0 +1,78 @@
+"""
+A stub context implementation for documentation purposes.
+It does actually work, but presents nothing.
+"""
+
+import weakref
+
+
+def rendercanvas_context_hook(canvas, present_methods):
+    """Hook function to allow ``rendercanvas`` to detect your context implementation.
+
+    If you make a function with this name available in the module ``your.module``,
+    ``rendercanvas`` will detect and call this function in order to obtain the canvas object.
+    That way, anyone can use ``canvas.get_context("your.module")`` to use your context.
+    The arguments are the same as for ``ContextInterface``.
+    """
+    return ContextInterface(canvas, present_methods)
+
+
+class ContextInterface:
+    """The interface that a context must implement, to be usable with a ``RenderCanvas``.
+
+    Arguments:
+        canvas (BaseRenderCanvas): the canvas to render to.
+        present_methods (dict): The supported present methods of the canvas.
+
+    The ``present_methods`` dict has a field for each supported present-method. A
+    canvas must support either "screen" or "bitmap". It may support both, as well as
+    additional (specialized) present methods. Below we list the common methods and
+    what fields the subdicts have.
+
+    * Render method "screen":
+        * "window": the native window id.
+        * "display": the native display id (Linux only).
+        * "platform": to determine between "x11" and "wayland" (Linux only).
+    * Render method "bitmap":
+        * "formats": a list of supported formats. It should always include "rgba-u8".
+          Other options can be be "i-u8" (intensity/grayscale), "i-f32", "bgra-u8", "rgba-u16", etc.
+
+    """
+
+    def __init__(self, canvas, present_methods):
+        self._canvas_ref = weakref.ref(canvas)
+        self._present_methods = present_methods
+
+    @property
+    def canvas(self):
+        """The associated canvas object. Internally, this should preferably be stored using a weakref."""
+        return self._canvas_ref()
+
+    def present(self):
+        """Present the result to the canvas.
+
+        This is called by the canvas, and should not be called by user-code.
+
+        The implementation should always return a present-result dict, which
+        should have at least a field 'method'. The value of 'method' must be
+        one of the methods that the canvas supports, i.e. it must be in ``present_methods``.
+
+        * If there is nothing to present, e.g. because nothing was rendered yet:
+            * return ``{"method": "skip"}`` (special case).
+        * If presentation could not be done for some reason:
+            * return ``{"method": "fail", "message": "xx"}`` (special case).
+        * If ``present_method`` is "screen":
+            * Render to screen using the info in ``present_methods['screen']``).
+            * Return ``{"method", "screen"}`` as confirmation.
+        * If ``present_method`` is "bitmap":
+            * Return ``{"method": "bitmap", "data": data, "format": format}``.
+            * 'data' is a memoryview, or something that can be converted to a memoryview, like a numpy array.
+            * 'format' is the format of the bitmap, must be in ``present_methods['bitmap']['formats']`` ("rgba-u8" is always supported).
+        * If ``present_method`` is something else:
+            * Return ``{"method": "xx", ...}``.
+            * It's the responsibility of the context to use a render method that is supported by the canvas,
+              and that the appropriate arguments are supplied.
+        """
+
+        # This is a stub
+        return {"method": "skip"}