@gjsify/webgl 0.47.0 → 0.49.0

package/README.md

@@ -198,6 +198,65 @@ platform, not from the bridge:
 
 Remaining darwin gaps are tracked in [`status/open-todos.md`](../../../status/open-todos.md).
 
+### The darwin GL 4.1 ceiling
+
+The one-line rule in [packages/framework/AGENTS.md](../AGENTS.md) links here for the
+measurement behind it, because a rule without its reason gets "simplified" back into the
+bug. Measured on macOS 15.7 / GdkMacosGLContext (`4.1 APPLE-21.1.1`, GLSL 4.10).
+
+**The two missing entry points, reproduced.** `glInvalidateFramebuffer` and
+`glInvalidateSubFramebuffer` are GL 4.3 and absent, hence the `epoxyGlVersion() >= 43` gate
+in `webgl2-rendering-context.vala` — libepoxy ABORTS on a missing entry point rather than
+returning null. They are also the only two, and that is a count anyone can re-take: of the
+219 `epoxy_gl*` entry points `libgwebgl.dylib` references, `dlsym` against
+`OpenGL.framework` resolves 217.
+
+```bash
+nm -u libgwebgl.dylib | sed -n 's/^ *_epoxy_//p' | grep -E '^gl[A-Z]'
+# then, per name, ctypes.CDLL('/System/Library/Frameworks/OpenGL.framework/OpenGL')
+```
+
+**The GLES 3.0 spellings with no desktop-4.1 equivalent stay missing**, and this is the part
+the shader rewrite above does not reach: `GL_PRIMITIVE_RESTART_FIXED_INDEX` (4.3 on desktop)
+and the mandatory ETC2/EAC compressed formats. Both surface as a **draw-time** error rather
+than a compile failure, so a shader that compiles is not evidence that a scene using them
+will render.
+
+For the dialect rewrite itself — including why **win32 is rewritten too**, which this file
+predicted wrongly once — see [Platform coverage](#platform-coverage) above. Host diagnosis:
+`gjsify run packages/framework/webgl/scripts/probe-gl-host.js`, which also draws a
+shader-free pattern so a blank window cannot be mistaken for a failed shader.
+
+## HiDPI: the two canvas bridges are NOT symmetric
+
+**This asymmetry is a whole bug class, and it is invisible on every machine you are likely to develop on.**
+
+GTK silently pre-scales a `Gtk.DrawingArea`'s Cairo context, so Canvas2D code written in logical pixels renders sharp with nothing to do. `Gtk.GLArea` does **not**: its framebuffer is `allocation x scale-factor` and `gl.viewport` is in raw device pixels.
+
+So the GL side reports the DRAWING BUFFER in device pixels (`canvas.width` / `canvas.height`, hence `gl.drawingBufferWidth`) while CSS layout size stays logical (`clientWidth` / `offsetWidth`), and `installGlobals()` publishes `devicePixelRatio` as an ACCESSOR over the widget's live `get_scale_factor()`. The identity
+
+```
+clientWidth * devicePixelRatio === canvas.width
+```
+
+is what lets an unmodified Three.js or Excalibur viewport cover the whole framebuffer.
+
+Reporting the allocation as `canvas.width` — as this bridge did until 2026-08 — is invisible at scale-factor 1, which is every desktop, every CI runner and every test VM. On the first scale-factor-3 host it drew each scene into the bottom-left NINTH of its widget: measured on a OnePlus 6T running postmarketOS / GNOME Mobile, where the teapot, the pixel-postprocessing and the Excalibur showcases all rendered a 120x218 corner of a 360x655-logical widget.
+
+`@gjsify/dom-elements`' register seeds `devicePixelRatio: 1` as the widget-less default only. A real `Gtk.GLArea` cannot regression-test this, because its host reports 1 — `html-canvas-element.spec.ts` varies the scale factor through a stub, which is the entire point of that stub.
+
+## Naming the GL you actually got
+
+`WEBGL_debug_renderer_info` is implemented (the spec'd `VENDOR` / `RENDERER` stay masked) and `bridge.rendererInfo` reads it, so a CPU rasteriser (`isSoftwareRenderer`) costs ONE stderr line. A GPU-less host is otherwise invisible: every draw call succeeds, and only the frame budget tells.
+
+**It is DIAGNOSTIC ONLY.** The same driver carries a demand-driven three.js scene and needs 1.1 s for a single textured full-screen draw in a game, so a renderer swap keys on a MEASURED frame budget, never on this string.
+
+## Resize, clone and the WebGL2 overrides
+
+- On resize `WebGLBridge` dispatches a DOM `resize` and re-invokes the last rAF callback — demand-driven re-render, no animation loop.
+- A canvas clones PLAIN (`_createCloneTarget`): there is one GLArea and it stays with the original.
+- `WebGL2RenderingContext` overrides `texImage2D`, `texSubImage2D` and `drawElements` from the WebGL1 base, bypassing WebGL1 format/type validation — the native Vala side handles all GLES 3.2 formats.
+
 ## Diagnosing a host
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/webgl",
-    "version": "0.47.0",
+    "version": "0.49.0",
     "description": "WebGL module for Gjs",
     "module": "lib/esm/index.js",
     "types": "lib/types/index.d.ts",
@@ -61,8 +61,8 @@
         "WebGL"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.47.0",
-        "@gjsify/unit": "^0.47.0",
+        "@gjsify/cli": "^0.49.0",
+        "@gjsify/unit": "^0.49.0",
         "@types/bit-twiddle": "^1.0.3",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
@@ -72,10 +72,10 @@
         "@girs/gjs": "4.6.0",
         "@girs/gtk-4.0": "4.6.0",
         "@girs/gwebgl-0.1": "0.1.0-4.0.0-rc.5",
-        "@gjsify/dom-elements": "^0.47.0",
-        "@gjsify/dom-events": "^0.47.0",
-        "@gjsify/event-bridge": "^0.47.0",
-        "@gjsify/utils": "^0.47.0",
+        "@gjsify/dom-elements": "^0.49.0",
+        "@gjsify/dom-events": "^0.49.0",
+        "@gjsify/event-bridge": "^0.49.0",
+        "@gjsify/utils": "^0.49.0",
         "bit-twiddle": "^1.0.2",
         "glsl-tokenizer": "^2.1.5"
     },
@@ -90,13 +90,13 @@
     },
     "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/framework/webgl#readme",
     "optionalDependencies": {
-        "@gjsify/webgl-darwin-arm64": "0.47.0",
-        "@gjsify/webgl-darwin-x64": "0.47.0",
-        "@gjsify/webgl-linux-arm64": "0.47.0",
-        "@gjsify/webgl-linux-ppc64": "0.47.0",
-        "@gjsify/webgl-linux-riscv64": "0.47.0",
-        "@gjsify/webgl-linux-s390x": "0.47.0",
-        "@gjsify/webgl-linux-x64": "0.47.0",
-        "@gjsify/webgl-win32-x64": "0.47.0"
+        "@gjsify/webgl-darwin-arm64": "0.49.0",
+        "@gjsify/webgl-darwin-x64": "0.49.0",
+        "@gjsify/webgl-linux-arm64": "0.49.0",
+        "@gjsify/webgl-linux-ppc64": "0.49.0",
+        "@gjsify/webgl-linux-riscv64": "0.49.0",
+        "@gjsify/webgl-linux-s390x": "0.49.0",
+        "@gjsify/webgl-linux-x64": "0.49.0",
+        "@gjsify/webgl-win32-x64": "0.49.0"
     }
 }