From 5507a358aaeee728d5810306357cfa3e69d48663 Mon Sep 17 00:00:00 2001 From: Almar Klein Date: Fri, 25 Oct 2024 13:18:57 +0200 Subject: [PATCH] Add docs --- docs/Makefile | 20 ++++ docs/api.rst | 14 +++ docs/conf.py | 75 +++++++++++++++ docs/gui.rst | 200 ++++++++++++++++++++++++++++++++++++++ docs/guide.rst | 255 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 22 +++++ docs/make.bat | 35 +++++++ docs/start.rst | 30 ++++++ 8 files changed, 651 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/api.rst create mode 100644 docs/conf.py create mode 100644 docs/gui.rst create mode 100644 docs/guide.rst create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/start.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..1929774 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,14 @@ +rendercanvas base classes +========================= + +.. autoclass:: rendercanvas.base.WgpuCanvasInterface + :members: + +.. autoclass:: rendercanvas.base.WgpuCanvasBase + :members: + +.. .. autoclass:: rendercanvas.base.WgpuLoop +.. :members: + +.. .. autoclass:: rendercanvas.base.WgpuTimer +.. :members: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..cfd68f7 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,75 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + +import os +import sys +import shutil + + +ROOT_DIR = os.path.abspath(os.path.join(__file__, "..", "..")) +sys.path.insert(0, ROOT_DIR) + +os.environ["WGPU_FORCE_OFFSCREEN"] = "true" + + +# Load wglibu so autodoc can query docstrings +import rendercanvas # noqa: E402 + + +# -- Project information ----------------------------------------------------- + +project = "rendercanvas" +copyright = "2020-2024, Almar Klein, Korijn van Golen" +author = "Almar Klein, Korijn van Golen" +release = rendercanvas.__version__ + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx_rtd_theme", +] + +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "numpy": ("https://numpy.org/doc/stable", None), + "wgpu": ("https://wgpu-py.readthedocs.io/en/latest", None), +} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +master_doc = "index" + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. + +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = [] diff --git a/docs/gui.rst b/docs/gui.rst new file mode 100644 index 0000000..4c2d5b3 --- /dev/null +++ b/docs/gui.rst @@ -0,0 +1,200 @@ +gui API +======= + +.. currentmodule:: rendercanvas + +You can use vanilla wgpu for compute tasks and to render offscreen. To +render to a window on screen we need a *canvas*. Since the Python +ecosystem provides many different GUI toolkits, rendercanvas implements a base +canvas class, and has builtin support for a few GUI toolkits. At the +moment these include GLFW, Jupyter, Qt, and wx. + + +The Canvas base classes +----------------------- + +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. + + +The auto GUI backend +-------------------- + +Generally the best approach for examples and small applications is to use the +automatically selected GUI backend. This ensures that the code is portable +across different machines and environments. Using ``rendercanvas.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 `_ +for details about the event objects. + + +.. code-block:: py + + from wgpu.gui.auto import WgpuCanvas, run, call_later + + canvas = WgpuCanvas(title="Example") + canvas.request_draw(your_draw_function) + + run() + + +Support for GLFW +---------------- + +`GLFW `_ is a lightweight windowing toolkit. +Install it with ``pip install glfw``. The preferred approach is to use the auto backend, +but you can replace ``from rendercanvas.auto`` with ``from rendercanvas.glfw`` to force using GLFW. + +.. code-block:: py + + from wgpu.gui.glfw import WgpuCanvas, run, call_later + + canvas = WgpuCanvas(title="Example") + canvas.request_draw(your_draw_function) + + run() + + +Support for Qt +-------------- + +There is support for PyQt5, PyQt6, PySide2 and PySide6. The rendercanvas library detects what +library you are using by looking what module has been imported. +For a toplevel widget, the ``rendercanvas.qt.WgpuCanvas`` class can be imported. If you want to +embed the canvas as a subwidget, use ``rendercanvas.qt.WgpuWidget`` instead. + +Also see the `Qt triangle example `_ +and `Qt triangle embed example `_. + +.. code-block:: py + + # Import any of the Qt libraries before importing the WgpuCanvas. + # This way wgpu knows which Qt library to use. + from PySide6 import QtWidgets + from wgpu.gui.qt import WgpuCanvas + + app = QtWidgets.QApplication([]) + + # Instantiate the canvas + canvas = WgpuCanvas(title="Example") + + # Tell the canvas what drawing function to call + canvas.request_draw(your_draw_function) + + app.exec_() + + +Support for wx +-------------- + +There is support for embedding a wgpu visualization in wxPython. +For a toplevel widget, the ``gui.wx.WgpuCanvas`` class can be imported. If you want to +embed the canvas as a subwidget, use ``gui.wx.WgpuWidget`` instead. + +Also see the `wx triangle example `_ +and `wx triangle embed example `_. + +.. code-block:: py + + import wx + from wgpu.gui.wx import WgpuCanvas + + app = wx.App() + + # Instantiate the canvas + canvas = WgpuCanvas(title="Example") + + # Tell the canvas what drawing function to call + canvas.request_draw(your_draw_function) + + app.MainLoop() + + + +Support for offscreen +--------------------- + +You can also use a "fake" canvas to draw offscreen and get the result as a numpy array. +Note that you can render to a texture without using any canvas +object, but in some cases it's convenient to do so with a canvas-like API. + +.. code-block:: py + + from wgpu.gui.offscreen import WgpuCanvas + + # Instantiate the canvas + canvas = WgpuCanvas(size=(500, 400), pixel_ratio=1) + + # ... + + # Tell the canvas what drawing function to call + canvas.request_draw(your_draw_function) + + # Perform a draw + array = canvas.draw() # numpy array with shape (400, 500, 4) + + +Support for Jupyter lab and notebook +------------------------------------ + +WGPU can be used in Jupyter lab and the Jupyter notebook. This canvas +is based on `jupyter_rfb `_, an ipywidget +subclass implementing a remote frame-buffer. There are also some `wgpu examples `_. + +.. code-block:: py + + # from wgpu.gui.jupyter import WgpuCanvas # Direct approach + from wgpu.gui.auto import WgpuCanvas # Approach compatible with desktop usage + + canvas = WgpuCanvas() + + # ... wgpu code + + canvas # Use as cell output + + +.. _interactive_use: + +Using a canvas interactively +---------------------------- + +The rendercanvas gui's are designed to support interactive use. Firstly, this is +realized by automatically selecting the appropriate GUI backend. Secondly, the +``run()`` function (which normally enters the event-loop) does nothing in an +interactive session. + +Many interactive environments have some sort of GUI support, allowing the repl +to stay active (i.e. you can run new code), while the GUI windows is also alive. +In rendercanvas we try to select the GUI that matches the current environment. + +On ``jupyter notebook`` and ``jupyter lab`` the jupyter backend (i.e. +``jupyter_rfb``) is normally selected. When you are using ``%gui qt``, rendercanvas will +honor that and use Qt instead. + +On ``jupyter console`` and ``qtconsole``, the kernel is the same as in ``jupyter notebook``, +making it (about) impossible to tell that we cannot actually use +ipywidgets. So it will try to use ``jupyter_rfb``, but cannot render anything. +It's theefore advised to either use ``%gui qt`` or set the ``WGPU_GUI_BACKEND`` env var +to "glfw". The latter option works well, because these kernels *do* have a +running asyncio event loop! + +On other environments that have a running ``asyncio`` loop, the glfw backend is +preferred. E.g on ``ptpython --asyncio``. + +On IPython (the old-school terminal app) it's advised to use ``%gui qt`` (or +``--gui qt``). It seems not possible to have a running asyncio loop here. + +On IDE's like Spyder or Pyzo, rendercanvas detects the integrated GUI, running on +glfw if asyncio is enabled or Qt if a qt app is running. + +On an interactive session without GUI support, one must call ``run()`` to make +the canvases interactive. This enters the main loop, which prevents entering new +code. Once all canvases are closed, the loop returns. If you make new canvases +afterwards, you can call ``run()`` again. This is similar to ``plt.show()`` in Matplotlib. diff --git a/docs/guide.rst b/docs/guide.rst new file mode 100644 index 0000000..c1a02c6 --- /dev/null +++ b/docs/guide.rst @@ -0,0 +1,255 @@ +Guide (deprecated) +================== + +**TODO: REMOVE/REPLACE THIS** + +The ``wgpu`` library presents a Pythonic API for the `WebGPU spec +`_. It is an API to control graphics +hardware. Like OpenGL but modern. Or like Vulkan but higher level. +GPU programming is a craft that requires knowledge of how GPU's work. + + +Getting started +--------------- + +Creating a canvas ++++++++++++++++++ + +If you want to render to the screen, you need a canvas. Multiple +GUI toolkits are supported, see the :doc:`gui`. In general, it's easiest to let ``wgpu`` select a GUI automatically: + +.. code-block:: py + + from wgpu.gui.auto import WgpuCanvas, run + + canvas = WgpuCanvas(title="a wgpu example") + + +Next, we can setup the render context, which we will need later on. + +.. code-block:: py + + present_context = canvas.get_context() + render_texture_format = present_context.get_preferred_format(device.adapter) + present_context.configure(device=device, format=render_texture_format) + + +Obtaining a device +++++++++++++++++++ + +The next step is to obtain an adapter, which represents an abstract render device. +You can pass it the ``canvas`` that you just created, or pass ``None`` for the canvas +if you have none (e.g. for compute or offscreen rendering). From the adapter, +you can obtain a device. + +.. code-block:: py + + adapter = wgpu.gpu.request_adapter_sync(power_preference="high-performance") + device = adapter.request_device_sync() + +The ``wgpu.gpu`` object is the API entrypoint (:class:`wgpu.GPU`). It contains just a handful of functions, +including ``request_adapter()``. The device is used to create most other GPU objects. + + +Creating buffers, textures shaders, etc. +++++++++++++++++++++++++++++++++++++++++ + +Using the device, you can create buffers, textures, write shader code, and put +these together into pipeline objects. How to do this depends a lot on what you +want to achieve, and is therefore out of scope for this guide. Have a look at the examples +or some of the tutorials that we link to below. + +Setting up a draw function +++++++++++++++++++++++++++ + +Let's now define a function that will actually draw the stuff we put together in +the previous step. + +.. code-block:: py + + def draw_frame(): + + # We'll record commands that we do on a render pass object + command_encoder = device.create_command_encoder() + current_texture_view = present_context.get_current_texture() + render_pass = command_encoder.begin_render_pass( + color_attachments=[ + { + "view": current_texture_view, + "resolve_target": None, + "clear_value": (1, 1, 1, 1), + "load_op": wgpu.LoadOp.clear, + "store_op": wgpu.StoreOp.store, + } + ], + ) + + # Perform commands, something like ... + render_pass.set_pipeline(...) + render_pass.set_index_buffer(...) + render_pass.set_vertex_buffer(...) + render_pass.set_bind_group(...) + render_pass.draw_indexed(...) + + # When done, submit the commands to the device queue. + render_pass.end() + device.queue.submit([command_encoder.finish()]) + + # If you want to draw continuously, request a new draw right now + canvas.request_draw() + + +Starting the event loop ++++++++++++++++++++++++ + + +We can now pass the above render function to the canvas. The canvas will then +call the function whenever it (re)draws the window. And finally, we call ``run()`` to enter the mainloop. + +.. code-block:: py + + canvas.request_draw(draw_frame) + run() + + +Offscreen ++++++++++ + +If you render offscreen, or only do compute, you do not need a canvas. You also won't need a GUI toolkit, draw function or enter the event loop. +Instead, you will obtain a command encoder and submit its records to the queue directly. + + +Examples and external resources +------------------------------- + +Examples that show wgpu-py in action: + +* https://github.com/pygfx/wgpu-py/tree/main/examples + +.. note:: The examples in the main branch of the repository may not match the pip installable version. Be sure to refer to the examples from the git tag that matches the version of wgpu you have installed. + + +External resources: + +* https://webgpu.rocks/ +* https://sotrh.github.io/learn-wgpu/ +* https://rust-tutorials.github.io/learn-wgpu/ + + +A brief history of WebGPU +------------------------- + +For years, OpenGL has been the only cross-platform API to talk to the GPU. +But over time OpenGL has grown into an inconsistent and complex API ... + + *OpenGL is dying* + --- Dzmitry Malyshau at `Fosdem 2020 `_ + +In recent years, modern API's have emerged that solve many of OpenGL's +problems. You may have heard of Vulkan, Metal, and DX12. These +API's are much closer to the hardware, which makes the drivers more +consistent and reliable. Unfortunately, the huge amount of "knobs to +turn" also makes them quite hard to work with for developers. + +Therefore, higher level API are needed, which use the same concepts, but are much easier to work with. +The most notable one is the `WebGPU specification `_. This is what future devs +will be using to write GPU code for the browser. And for desktop and mobile as well. + +As the WebGPU spec is being developed, a reference implementation is +also build. It's written in Rust and powers the WebGPU implementation in Firefox. +This reference implementation, called `wgpu `__, +also exposes a C-api (via `wgpu-native `__), +so that it can be wrapped in Python. And this is precisely what wgpu-py does. + +So in short, wgpu-py is a Python wrapper of wgpu, which is an desktop +implementation of WebGPU, an API that wraps Vulkan, Metal and DX12, +which talk to the GPU hardware. + + + +Coordinate system +----------------- + +In wgpu, the Y-axis is up in normalized device coordinate (NDC): point(-1.0, -1.0) +in NDC is located at the bottom-left corner of NDC. In addition, x and +y in NDC should be between -1.0 and 1.0 inclusive, while z in NDC should +be between 0.0 and 1.0 inclusive. Vertices out of this range in NDC +will not introduce any errors, but they will be clipped. + + +Array data +---------- + +The wgpu library makes no assumptions about how you store your data. +In places where you provide data to the API, it can consume any data +that supports the buffer protocol, which includes ``bytes``, +``bytearray``, ``memoryview``, ctypes arrays, and numpy arrays. + +In places where data is returned, the API returns a ``memoryview`` +object. These objects provide a quite versatile view on ndarray data: + +.. code-block:: py + + # One could, for instance read the content of a buffer + m = device.queue.read_buffer(buffer) + # Cast it to float32 + m = m.cast("f") + # Index it + m[0] + # Show the content + print(m.tolist()) + +Chances are that you prefer Numpy. Converting the ``memoryview`` to a +numpy array (without copying the data) is easy: + +.. code-block:: py + + array = np.frombuffer(m, np.float32) + + +Debugging +--------- + +If the default wgpu-backend causes issues, or if you want to run on a +different backend for another reason, you can set the +`WGPU_BACKEND_TYPE` environment variable to "Vulkan", "Metal", "D3D12", +or "OpenGL". + +The log messages produced (by Rust) in wgpu-native are captured and +injected into Python's "wgpu" logger. One can set the log level to +"INFO" or even "DEBUG" to get detailed logging information. + +Many GPU objects can be given a string label. This label will be used +in Rust validation errors, and are also used in e.g. RenderDoc to +identify objects. Additionally, you can insert debug markers at the +render/compute pass object, which will then show up in RenderDoc. + +Eventually, wgpu-native will fully validate API input. Until then, it +may be worthwhile to enable the Vulkan validation layers. To do so, run +a debug build of wgpu-native and make sure that the Lunar Vulkan SDK +is installed. + +You can run your application via RenderDoc, which is able to capture a +frame, including all API calls, objects and the complete pipeline state, +and display all of that information within a nice UI. + +You can use ``adapter.request_device_sync()`` to provide a directory path +where a trace of all API calls will be written. This trace can then be used +to re-play your use-case elsewhere (it's cross-platform). + +Also see wgpu-core's section on debugging: +https://github.com/gfx-rs/wgpu/wiki/Debugging-wgpu-Applications + + +Freezing apps +------------- + +In wgpu a PyInstaller-hook is provided to help simplify the freezing process +(it e.g. ensures that the wgpu-native DLL is included). This hook requires +PyInstaller version 4+. + +Our hook also includes ``glfw`` when it is available, so code using ``wgpu.gui.auto`` +should Just Work. + +Note that PyInstaller needs ``wgpu`` to be installed in `site-packages` for +the hook to work (i.e. it seems not to work with a ``pip -e .`` dev install). diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..0ca67bf --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,22 @@ +Welcome to the rendercanvas docs! +================================= + +.. automodule:: rendercanvas + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + start + guide + gui + api + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..2119f51 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/start.rst b/docs/start.rst new file mode 100644 index 0000000..801798e --- /dev/null +++ b/docs/start.rst @@ -0,0 +1,30 @@ +Installation +============ + +Install with pip +---------------- + +You can install ``rendercanvas`` via pip. +Python 3.9 or higher is required. Pypy is supported. + +.. code-block:: bash + + pip install rendercanvas + + +Since most users will want to render something to screen, we recommend installing GLFW as well: + +.. code-block:: bash + + pip install rendercanvas glfw + + +GUI libraries +------------- + +Multiple GUI backends are supported, see :doc:`the GUI API ` for details: + +* `glfw `_: a lightweight GUI for the desktop +* `jupyter_rfb `_: only needed if you plan on using wgpu in Jupyter +* qt (PySide6, PyQt6, PySide2, PyQt5) +* wx