From 9fc96279a0b450f86794f015558a028554175ee0 Mon Sep 17 00:00:00 2001
From: Almar Klein <almar@almarklein.org>
Date: Wed, 11 Dec 2024 10:00:16 +0100
Subject: [PATCH] Add doc for migrating from wgpu.gui (#47)

---
 README.md           |  2 ++
 from_wgpu_canvas.md | 48 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 from_wgpu_canvas.md

diff --git a/README.md b/README.md
index c8fbef2..934192c 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,8 @@ 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!
 
+Coming from `wgpu.gui`? Check [from_wgpu_canvas.md](from_wgpu_canvas.md).
+
 
 ## Purpose
 
diff --git a/from_wgpu_canvas.md b/from_wgpu_canvas.md
new file mode 100644
index 0000000..c8efb1f
--- /dev/null
+++ b/from_wgpu_canvas.md
@@ -0,0 +1,48 @@
+# Migrating from wgpu.gui.WgpuCanvas
+
+This project was spun out of wgpu-py, and has evolved to meet our requirements for update-propagation and more.
+This document lists all the changes w.r.t. the last version of the canvas in wgpu-py.
+
+## Changes
+
+*Let me know if I missed any!*
+
+* `WgpuCanvas` -> `RenderCanvas`.
+* `run` -> `loop.run()`.
+* `call_later` -> `loop.call_later`.
+* `canvas.is_closed()` -> `canvas.get_closed()`.
+* The `canvas.get_context()` must be called with an arg: `canvas.get_context("wgpu")`.
+
+
+## Improvements
+
+* Overall cleaner code, more tests, better docs.
+* Support for contexts other than wgpu.
+* Bitmap rendering via builtin`canvas.get_context("bitmap")`.
+* Handling of sigint (ctrl+c).
+* Support for Trio.
+* Support for async event handlers.
+* Support for running async functions via `loop.add_task()`.
+* Simpler Qt lib selection with `from rendercanvas.pyside6 import RenderCanvas`.
+* Generic scheduling system with modes "ondemand", "continious", "fastest".
+
+
+## By example
+
+In wgpu-py:
+```py
+from wgpu.gui.auto import WgpuCanvas, run
+
+...
+
+run()
+```
+
+In rendercanvas:
+```py
+from rendercanvas.auto import RenderCanvas, loop
+
+...
+
+loop.run()
+```