From aad4f48e413008397a525cb3e84b3942b96784a2 Mon Sep 17 00:00:00 2001 From: tannevaled Date: Wed, 18 Nov 2026 11:59:55 +0100 Subject: [PATCH 1/2] surfaces/browser: document the damage-aware present (webcanvas v0.15.0) A scene that implements webcanvas.DamageDrawer has only the rectangles it changed copied and put on the canvas; layers are drawn again each frame, with the restore rules for moved, translucent and Opaque ones. Measured numbers and the gpu presenter's open issue are linked. Co-Authored-By: Claude Sonnet 5.5 --- content/en/surfaces/browser.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/content/en/surfaces/browser.md b/content/en/surfaces/browser.md index 1ca0686b..805c9e43 100644 --- a/content/en/surfaces/browser.md +++ b/content/en/surfaces/browser.md @@ -124,6 +124,34 @@ application written against `window` then runs unchanged as a native window, in a browser tab, and in wasmdesk. From window v0.93.0 the tab publishes the accessibility mirror and text layer from the widget tree, with no extra code. +## Repainting only what changed + +Without help, every frame is `Draw` of the whole scene, a copy of the whole +framebuffer into the browser and a `putImageData` of the whole canvas, even when +one caret blinked or only a guest's frame in a `Layer` is new. A scene that +knows what it changed implements `DrawDamaged(buf []byte) []Rect` +(`webcanvas.DamageDrawer`, webcanvas v0.15.0), and the host copies and puts only +those rectangles. + +- **The contract** is the one [`window`'s `DamageRenderer`]({{< relref "/surfaces/native-window.md" >}}) + gives a desktop host, in the browser's terms: the scene repaints what changed + into a framebuffer that persists between frames and returns the rectangles it + repainted (`webcanvas.Rect` is `toolkit.Rect`). An **empty** result means + nothing changed and nothing is put. `Draw` still runs for the first frame and + after every resize. +- **Layers** are drawn again every frame, but cost no scene repaint. A layer + that moved, shrank or went has its old rectangle put back from the scene + buffer; a layer with `Alpha < 1`, or not marked `Opaque`, has the scene put + back under it every frame. `Opaque: true` promises every pixel is opaque, and + is what lets a still guest frame put nothing. +- **Not using it** changes nothing: a scene without `DrawDamaged` is drawn and + put whole, as before. The `webcanvas/gpu` presenter redraws on the GPU every + frame and does not use it yet + ([webcanvas#37](https://github.com/go-widgets/webcanvas/issues/37)). +- **Measured** under `GOOS=js` in node at 1280×800, with a fake 2D context: a + frame that changes one 120×40 widget costs 0.031 ms instead of 2.89 ms, and a + frame with no damage and one opaque layer 0.021 ms instead of 2.90 ms. + ## On the GPU `webcanvas.RunWith(id, app, presenter)` takes a `Presenter`, and the package From 7756d112f951f9967d9600fa243ce779b66457f3 Mon Sep 17 00:00:00 2001 From: tannevaled Date: Wed, 18 Nov 2026 12:12:53 +0100 Subject: [PATCH 2/2] surfaces/browser: fr, de, es, ja, ko, zh-cn versions of the damage-aware present section Co-Authored-By: Claude Sonnet 5.5 --- content/de/surfaces/browser.md | 30 ++++++++++++++++++++++++++++++ content/es/surfaces/browser.md | 29 +++++++++++++++++++++++++++++ content/fr/surfaces/browser.md | 28 ++++++++++++++++++++++++++++ content/ja/surfaces/browser.md | 21 +++++++++++++++++++++ content/ko/surfaces/browser.md | 21 +++++++++++++++++++++ content/zh-cn/surfaces/browser.md | 19 +++++++++++++++++++ 6 files changed, 148 insertions(+) diff --git a/content/de/surfaces/browser.md b/content/de/surfaces/browser.md index 7090718c..488cf1f2 100644 --- a/content/de/surfaces/browser.md +++ b/content/de/surfaces/browser.md @@ -41,6 +41,36 @@ für `js/wasm` gebaut, auf einer gewöhnlichen Seite ein Back-End zurück, das Eine gegen `window` geschriebene Anwendung läuft dann unverändert als natives Fenster, in einem Browser-Tab und in wasmdesk. +## Nur neu zeichnen, was sich geändert hat {#repainting-only-what-changed} + +Ohne Hilfe ist jedes Bild ein `Draw` der ganzen Szene, eine Kopie des ganzen +Framebuffers in den Browser und ein `putImageData` des ganzen Canvas, selbst wenn +nur ein Cursor geblinkt hat oder nur das Bild eines Gasts in einem `Layer` neu +ist. Eine Szene, die weiß, was sie geändert hat, implementiert +`DrawDamaged(buf []byte) []Rect` (`webcanvas.DamageDrawer`, webcanvas v0.15.0), +und der Host kopiert und setzt nur diese Rechtecke. + +- **Der Vertrag** ist der, den der `DamageRenderer` von [`window`]({{< relref "/surfaces/native-window.md" >}}) + einem Desktop-Host gibt, in Browser-Begriffen: Die Szene zeichnet das + Geänderte in einen Framebuffer, der zwischen den Bildern bestehen bleibt, und + gibt die neu gezeichneten Rechtecke zurück (`webcanvas.Rect` ist + `toolkit.Rect`). Ein **leeres** Ergebnis heißt: nichts hat sich geändert, nichts + wird gesetzt. `Draw` läuft weiterhin für das erste Bild und nach jeder + Größenänderung. +- **Layer** werden in jedem Bild neu gezeichnet, ohne die Szene neu zu zeichnen. + Bei einem verschobenen, verkleinerten oder verschwundenen Layer wird das alte + Rechteck aus dem Szenenpuffer wiederhergestellt; unter einem Layer mit + `Alpha < 1` oder ohne `Opaque` wird die Szene in jedem Bild wiederhergestellt. + `Opaque: true` verspricht, dass alle Pixel deckend sind, sodass ein ruhendes + Gastbild nichts setzt. +- **Ohne** `DrawDamaged` ändert sich nichts: Die Szene wird wie bisher ganz + gezeichnet und gesetzt. Der Presenter `webcanvas/gpu` zeichnet in jedem Bild neu + auf der GPU und nutzt es noch nicht + ([webcanvas#37](https://github.com/go-widgets/webcanvas/issues/37)). +- **Gemessen** unter `GOOS=js` in node, 1280×800, mit einem Fake-2D-Kontext: Ein + Bild, das ein 120×40-Widget ändert, kostet 0,031 ms statt 2,89 ms, ein Bild + ohne Änderung mit einem deckenden Layer 0,021 ms statt 2,90 ms. + ## Auf der GPU {#on-the-gpu} `webcanvas.RunWith(id, app, presenter)` nimmt einen `Presenter` entgegen, und diff --git a/content/es/surfaces/browser.md b/content/es/surfaces/browser.md index e2cd50f2..d31544ca 100644 --- a/content/es/surfaces/browser.md +++ b/content/es/surfaces/browser.md @@ -42,6 +42,35 @@ en el `` de la página (`Config.Canvas`, por defecto `"screen"`) a trav de `webcanvas`. Una aplicación escrita contra `window` se ejecuta entonces sin cambios como ventana nativa, en una pestaña del navegador y en wasmdesk. +## Repintar solo lo que cambió {#repainting-only-what-changed} + +Sin ayuda, cada fotograma es un `Draw` de toda la escena, una copia de todo el +framebuffer al navegador y un `putImageData` de todo el canvas, aunque solo haya +parpadeado un cursor o solo sea nueva la imagen de un invitado en un `Layer`. Una +escena que sabe qué cambió implementa `DrawDamaged(buf []byte) []Rect` +(`webcanvas.DamageDrawer`, webcanvas v0.15.0), y el anfitrión copia y pone solo +esos rectángulos. + +- **El contrato** es el que el `DamageRenderer` de [`window`]({{< relref "/surfaces/native-window.md" >}}) + da a un anfitrión de escritorio, en términos del navegador: la escena repinta + lo que cambió en un framebuffer que persiste entre fotogramas y devuelve los + rectángulos repintados (`webcanvas.Rect` es `toolkit.Rect`). Un resultado + **vacío** significa que nada cambió y nada se pone. `Draw` sigue ejecutándose + en el primer fotograma y tras cada cambio de tamaño. +- **Las capas** se dibujan de nuevo en cada fotograma, sin repintar la escena. Si + una capa se movió, se redujo o desapareció, su rectángulo anterior se restaura + desde el búfer de la escena; bajo una capa con `Alpha < 1`, o no marcada como + `Opaque`, la escena se restaura en cada fotograma. `Opaque: true` promete que + todos los píxeles son opacos, y permite que una imagen de invitado quieta no + ponga nada. +- **No usarlo** no cambia nada: una escena sin `DrawDamaged` se dibuja y se pone + entera, como antes. El presentador `webcanvas/gpu` redibuja en la GPU en cada + fotograma y aún no lo usa + ([webcanvas#37](https://github.com/go-widgets/webcanvas/issues/37)). +- **Medido** con `GOOS=js` en node, a 1280×800, con un contexto 2D falso: un + fotograma que cambia un widget de 120×40 cuesta 0,031 ms en lugar de 2,89 ms, y + uno sin daño con una capa opaca 0,021 ms en lugar de 2,90 ms. + ## En la GPU {#on-the-gpu} `webcanvas.RunWith(id, app, presenter)` recibe un `Presenter`, y el paquete diff --git a/content/fr/surfaces/browser.md b/content/fr/surfaces/browser.md index 76f092a3..6ddd7d03 100644 --- a/content/fr/surfaces/browser.md +++ b/content/fr/surfaces/browser.md @@ -41,6 +41,34 @@ compilé pour `js/wasm` sur une page ordinaire renvoie un back-end qui dessine d application écrite pour `window` fonctionne alors sans modification comme fenêtre native, dans un onglet de navigateur et dans wasmdesk. +## Ne repeindre que ce qui a changé {#repainting-only-what-changed} + +Sans aide, chaque image est un `Draw` de toute la scène, une copie de tout le +framebuffer vers le navigateur et un `putImageData` de tout le canvas, même quand +seul un curseur a clignoté ou qu'une image d'invité dans un `Layer` est nouvelle. +Une scène qui sait ce qu'elle a modifié implémente `DrawDamaged(buf []byte) []Rect` +(`webcanvas.DamageDrawer`, webcanvas v0.15.0), et l'hôte ne copie et ne dépose +que ces rectangles. + +- **Le contrat** est celui que le `DamageRenderer` de [`window`]({{< relref "/surfaces/native-window.md" >}}) + donne à un hôte de bureau, en termes de navigateur : la scène repeint ce qui a + changé dans un framebuffer qui persiste d'une image à l'autre et renvoie les + rectangles repeints (`webcanvas.Rect` est `toolkit.Rect`). Un résultat **vide** + signifie que rien n'a changé et que rien n'est déposé. `Draw` s'exécute encore + pour la première image et après chaque redimensionnement. +- **Les calques** sont redessinés à chaque image, sans repeindre la scène. Pour un + calque déplacé, réduit ou disparu, l'ancien rectangle est restauré depuis le + tampon de la scène ; sous un calque avec `Alpha < 1`, ou non marqué `Opaque`, la + scène est restaurée à chaque image. `Opaque: true` promet que tous les pixels + sont opaques, ce qui permet à une image d'invité immobile de ne rien déposer. +- **Ne pas l'utiliser** ne change rien : une scène sans `DrawDamaged` est dessinée + et déposée en entier, comme avant. Le présentateur `webcanvas/gpu` redessine sur + le GPU à chaque image et ne l'utilise pas encore + ([webcanvas#37](https://github.com/go-widgets/webcanvas/issues/37)). +- **Mesuré** sous `GOOS=js` dans node, en 1280×800, avec un faux contexte 2D : une + image qui modifie un widget de 120×40 coûte 0,031 ms au lieu de 2,89 ms, et une + image sans dégât avec un calque opaque 0,021 ms au lieu de 2,90 ms. + ## Sur le GPU {#on-the-gpu} `webcanvas.RunWith(id, app, presenter)` prend un `Presenter`, et le paquet diff --git a/content/ja/surfaces/browser.md b/content/ja/surfaces/browser.md index d06f96bd..55dbeb6d 100644 --- a/content/ja/surfaces/browser.md +++ b/content/ja/surfaces/browser.md @@ -38,6 +38,27 @@ func main() { webcanvas.Run("screen", myScene()) } 返します。そのため、`window` に対して書かれたアプリケーションは、そのままネイティブウィンドウとしても、 ブラウザのタブでも、wasmdesk でも動作します。 +## 変更された部分だけを再描画する {#repainting-only-what-changed} + +何もしなければ、毎フレームがシーン全体の `Draw`、フレームバッファ全体のブラウザへのコピー、キャンバス全体の +`putImageData` になります。カーソルが点滅しただけ、あるいは `Layer` 内のゲストの画像が新しいだけでも同じです。 +何が変わったかを把握しているシーンは `DrawDamaged(buf []byte) []Rect`(`webcanvas.DamageDrawer`、 +webcanvas v0.15.0)を実装し、ホストはその矩形だけをコピーして描き込みます。 + +- **契約**は [`window`]({{< relref "/surfaces/native-window.md" >}}) の `DamageRenderer` がデスクトップホストに + 与えるものを、ブラウザ向けに言い換えたものです。シーンは変更部分を、フレーム間で保持されるフレームバッファに + 再描画し、再描画した矩形を返します(`webcanvas.Rect` は `toolkit.Rect` です)。結果が**空**なら何も変わって + おらず、何も描き込まれません。最初のフレームとリサイズ後には、引き続き `Draw` が実行されます。 +- **レイヤー**は毎フレーム描き直されますが、シーンの再描画は伴いません。移動、縮小、消滅したレイヤーの古い矩形は + シーンのバッファから復元されます。`Alpha < 1` のレイヤー、または `Opaque` でないレイヤーの下では、毎フレーム + シーンが復元されます。`Opaque: true` はすべてのピクセルが不透明であることを約束し、静止したゲストの画像が + 何も描き込まないようにします。 +- **使わなくても**何も変わりません。`DrawDamaged` のないシーンは従来どおり全体が描画され、描き込まれます。 + `webcanvas/gpu` プレゼンターは毎フレーム GPU で描き直しており、まだ使っていません + ([webcanvas#37](https://github.com/go-widgets/webcanvas/issues/37))。 +- **計測**:node 上の `GOOS=js`、1280×800、偽の 2D コンテキストで、120×40 のウィジェットを 1 つ変えるフレームは + 2.89 ms ではなく 0.031 ms、変更がなく不透明なレイヤーが 1 つあるフレームは 2.90 ms ではなく 0.021 ms です。 + ## GPU での描画 {#on-the-gpu} `webcanvas.RunWith(id, app, presenter)` は `Presenter` を受け取り、パッケージ diff --git a/content/ko/surfaces/browser.md b/content/ko/surfaces/browser.md index e21e77fb..a0fd998f 100644 --- a/content/ko/surfaces/browser.md +++ b/content/ko/surfaces/browser.md @@ -40,6 +40,27 @@ func main() { webcanvas.Run("screen", myScene()) } 백엔드를 반환합니다. 그러면 `window`에 맞춰 작성된 애플리케이션이 네이티브 창으로도, 브라우저 탭에서도, wasmdesk에서도 그대로 실행됩니다. +## 바뀐 부분만 다시 그리기 {#repainting-only-what-changed} + +아무 도움이 없으면 모든 프레임이 장면 전체의 `Draw`, 프레임버퍼 전체의 브라우저 복사, 캔버스 전체의 +`putImageData`가 됩니다. 커서가 깜박였을 뿐이거나 `Layer`에 있는 게스트의 이미지만 새로워도 마찬가지입니다. +무엇이 바뀌었는지 아는 장면은 `DrawDamaged(buf []byte) []Rect`(`webcanvas.DamageDrawer`, webcanvas v0.15.0)를 +구현하고, 호스트는 그 사각형만 복사해 그립니다. + +- **계약**은 [`window`]({{< relref "/surfaces/native-window.md" >}})의 `DamageRenderer`가 데스크톱 호스트에 + 주는 것을 브라우저의 용어로 옮긴 것입니다. 장면은 바뀐 부분을 프레임 사이에 유지되는 프레임버퍼에 다시 그리고, + 다시 그린 사각형을 반환합니다(`webcanvas.Rect`는 `toolkit.Rect`입니다). 결과가 **비어 있으면** 아무것도 바뀌지 + 않았으며 아무것도 그리지 않습니다. 첫 프레임과 크기 조정 뒤에는 여전히 `Draw`가 실행됩니다. +- **레이어**는 매 프레임 다시 그려지지만 장면을 다시 그리지는 않습니다. 이동하거나 줄어들거나 사라진 레이어의 + 이전 사각형은 장면 버퍼에서 복원됩니다. `Alpha < 1`인 레이어나 `Opaque`로 표시되지 않은 레이어 아래에서는 매 + 프레임 장면이 복원됩니다. `Opaque: true`는 모든 픽셀이 불투명함을 약속하며, 정지한 게스트 이미지가 아무것도 + 그리지 않게 해 줍니다. +- **사용하지 않아도** 달라지는 것은 없습니다. `DrawDamaged`가 없는 장면은 예전처럼 전체가 그려지고 놓입니다. + `webcanvas/gpu` 프레젠터는 매 프레임 GPU에서 다시 그리며 아직 이를 사용하지 않습니다 + ([webcanvas#37](https://github.com/go-widgets/webcanvas/issues/37)). +- **측정**: node의 `GOOS=js`, 1280×800, 가짜 2D 컨텍스트에서 120×40 위젯 하나를 바꾸는 프레임은 2.89 ms 대신 + 0.031 ms, 변경 없이 불투명 레이어 하나가 있는 프레임은 2.90 ms 대신 0.021 ms입니다. + ## GPU에서 그리기 {#on-the-gpu} `webcanvas.RunWith(id, app, presenter)`는 `Presenter`를 받고, `webcanvas/gpu` diff --git a/content/zh-cn/surfaces/browser.md b/content/zh-cn/surfaces/browser.md index 225bfb5d..3a003240 100644 --- a/content/zh-cn/surfaces/browser.md +++ b/content/zh-cn/surfaces/browser.md @@ -36,6 +36,25 @@ func main() { webcanvas.Run("screen", myScene()) } 会返回一个后端,它通过 `webcanvas` 绘制到页面的 ``(`Config.Canvas`,默认为 `"screen"`)。 这样,针对 `window` 编写的应用无需改动就能作为原生窗口、在浏览器标签页中以及在 wasmdesk 中运行。 +## 只重绘变化的部分 {#repainting-only-what-changed} + +如果不加处理,每一帧都是整个场景的 `Draw`、整个帧缓冲向浏览器的复制,以及整个 canvas 的 `putImageData`, +即使只是光标闪烁了一下,或只是 `Layer` 中客户机的图像更新了。知道自己改变了什么的场景实现 +`DrawDamaged(buf []byte) []Rect`(`webcanvas.DamageDrawer`,webcanvas v0.15.0),宿主就只复制并放置这些矩形。 + +- **约定**与 [`window`]({{< relref "/surfaces/native-window.md" >}}) 的 `DamageRenderer` 给桌面宿主的约定相同, + 只是换成浏览器的说法:场景把变化的部分重绘到帧与帧之间保持不变的帧缓冲中,并返回重绘的矩形 + (`webcanvas.Rect` 就是 `toolkit.Rect`)。结果为**空**表示没有任何变化,也不放置任何内容。第一帧以及每次调整大小后, + 仍会执行 `Draw`。 +- **图层**每一帧都会重新绘制,但不需要重绘场景。图层移动、缩小或消失时,它原来的矩形会从场景缓冲中恢复; + 在 `Alpha < 1` 或未标记 `Opaque` 的图层之下,每一帧都会恢复场景。`Opaque: true` 承诺所有像素都不透明, + 这样静止的客户机画面就不会放置任何内容。 +- **不使用它**则一切照旧:没有 `DrawDamaged` 的场景像以前一样被整体绘制并放置。`webcanvas/gpu` 呈现器每帧都在 + GPU 上重新绘制,目前尚未使用它 + ([webcanvas#37](https://github.com/go-widgets/webcanvas/issues/37))。 +- **测量**:在 node 中以 `GOOS=js`、1280×800 和一个伪造的 2D 上下文测得,改变一个 120×40 部件的帧耗时 0.031 ms, + 而不是 2.89 ms;没有变化且带一个不透明图层的帧耗时 0.021 ms,而不是 2.90 ms。 + ## 在 GPU 上绘制 {#on-the-gpu} `webcanvas.RunWith(id, app, presenter)` 接收一个 `Presenter`,`webcanvas/gpu`