@gjsify/webgl 0.27.0 → 0.28.0

package/README.md

@@ -113,9 +113,11 @@ yarn build:prebuilds
 
 ## Prebuilt binaries
 
-Prebuilds for `linux-x64`, `linux-arm64`, `linux-ppc64`, `linux-s390x`, and `linux-riscv64` are built automatically by CI
+Prebuilds for every target in `package.json#gjsify.platforms` are built automatically by CI
 (`.github/workflows/prebuilds.yml`) when the Vala source changes and committed back
-to the repository. They are included in the npm package via the `files` field.
+to the repository. Since ADR 0017 each one ships in its own
+`@gjsify/webgl-<os>-<arch>` package, referenced from here as an `optionalDependency`, so a
+consumer installs only the artifact that fits its platform.
 
 ## Inspirations and credits
 
@@ -130,17 +132,44 @@ to the repository. They are included in the npm package via the `files` field.
 | `linux-x64` | ✅ `libgwebgl.so` + `Gwebgl-0.1.typelib` | native runner |
 | `linux-arm64` | ✅ | native runner |
 | `linux-ppc64`, `linux-s390x`, `linux-riscv64` | ✅ | QEMU emulation |
-| macOS (`darwin-arm64` / `darwin-x64`) | ❌ | **unverified, see below** |
+| `darwin-arm64` / `darwin-x64` | ✅ `libgwebgl.dylib` + `Gwebgl-0.1.typelib` | native runner — **WebGL1 only, see below** |
 | Windows | ❌ | — no Vala/GI bridge in this repo targets Windows |
 
-**macOS is not blocked — it is unverified, and a green build would not be enough.** The
-build needs gtk4 + libepoxy + gdk-pixbuf from Homebrew (all available). The real question is
-runtime: GTK4's macOS (Quartz) backend goes through CGL, which tops out at desktop OpenGL 4.1
-Core and offers no GLES 3.2 — the profile this Vala bridge is written against. So compiling
-successfully on macOS would say nothing about whether `Gtk.GLArea` can actually render a
-WebGL2 context there. `meson.build` already emits the correct `.dylib` typelib leaf; the
-manual-dispatch `build-prebuilds-macos-experimental` job in the prebuilds workflow exists to
-establish the compile half of the answer.
+**macOS renders — WebGL1 only.** Measured on macOS 15.7.8 / x86_64 with gtk 4.22 and
+libepoxy 1.5.10: `Gtk.GLArea` realizes a `GdkMacosGLContext`, and this bridge draws real
+pixels through it. That describes the GL stack once GTK is loaded — reaching it needed
+`DYLD_LIBRARY_PATH=/usr/local/lib` exported by hand, because the `Gtk-4.0` typelib names a
+bare `libgtk-4.1.dylib` leaf that a Homebrew prefix does not put on the loader's search path
+for every host; that defect is tracked and fixed separately. Two further limits come from the
+platform, not from the bridge:
+
+- GTK4's macOS backend goes through **CGL, which offers desktop OpenGL only** — no GLES
+  profile at any version. A GLES-exclusive request (`gtk_gl_area_set_use_es(TRUE)`) fails
+  with *"Application does not support OpenGL API"*, so `WebGLBridge` declares
+  `set_allowed_apis(GL | GLES)` and lets GDK choose: GLES 3.2 where it exists, desktop
+  GL 4.1 on macOS.
+- Desktop GL 4.1 has **no GLSL ES 3.00 compiler** (that needs `ARB_ES3_compatibility`, GL 4.3),
+  so `#version 300 es` shaders — i.e. all WebGL2 content, including three.js ≥ r163 and
+  Excalibur 0.32 — do not compile. `#version 100` (WebGL1) does, via `ARB_ES2_compatibility`.
+  Of the 219 GL entry points the library references, exactly two are absent from Apple's
+  `OpenGL.framework` (`glInvalidateFramebuffer`, `glInvalidateSubFramebuffer`, both GL 4.3);
+  they are gated on `epoxy_gl_version() >= 43` because libepoxy aborts rather than returning
+  null.
+
+Remaining darwin gaps are tracked in [`status/open-todos.md`](../../../status/open-todos.md).
+
+## Diagnosing a host
+
+```bash
+gjsify run packages/framework/webgl/scripts/probe-gl-host.js [--seconds N]
+```
+
+Configures a bare `Gtk.GLArea` exactly as `WebGLBridge` does and reports the negotiated GL API
+and version, the widget scale factor, the logical allocation versus the device-pixel drawing
+buffer, the GL vendor/renderer/GLSL strings and which shader dialects compile — then draws a
+recognisable pattern using only `clearColor` + `scissor` + `clear`, so a blank window can never
+be mistaken for a failed shader. Exits non-zero when the GLArea does not realize. It needs a
+real display, which is why it is a script rather than a spec.
 
 ## License
 

package/lib/esm/webgl-bridge.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{WebGLRenderingContext as e}from"./webgl-rendering-context.js";import{WebGL2RenderingContext as t}from"./webgl2-rendering-context.js";import{HTMLCanvasElement as n}from"./html-canvas-element.js";import{notifyElementResize as r}from"@gjsify/dom-elements";import i from"gi://GObject";import a from"gi://GLib?version=2.0";import o from"gi://Gtk?version=4.0";import{attachEventControllers as s}from"@gjsify/event-bridge";import{Event as c}from"@gjsify/dom-events";const l=i.registerClass({GTypeName:`GjsifyWebGLBridge`},class WebGLBridge extends o.GLArea{constructor(e){super(e),this._canvas=null,this._readyCallbacks=[],this._resizeCallbacks=[],this._renderTag=null,this._tickCallbackId=null,this._frameCallback=null,this._lastFrameCallback=null,this._lastFrameTime=0,this._replaying=!1,this._frameCallbackId=0,this._nextFrameId=1,this._timeOrigin=a.get_monotonic_time(),this.set_use_es(!0),this.set_required_version(3,2),this.set_has_depth_buffer(!0),this.set_has_stencil_buffer(!0),s(this,()=>this._canvas,{captureKeys:!0}),this._tickCallbackId=this.add_tick_callback((e,t)=>(this._frameCallback!==null&&this.queue_render(),a.SOURCE_CONTINUE));let t=this.connect(`render`,()=>{this.disconnect(t),this.make_current(),this._canvas=new n(this);{let e=globalThis;e.document?.body&&e.document.body.appendChild(this._canvas)}this._canvas.getContext(`webgl2`);let e=this._canvas.getContext(`webgl`);if(e){for(let t of this._readyCallbacks)t(this._canvas,e);this._readyCallbacks=[]}return this._renderTag=this.connect(`render`,e=>{let t=(a.get_monotonic_time()-this._timeOrigin)/1e3;if(this._frameCallback!==null){globalThis.__GJSIFY_DEBUG_RAF===!0&&console.log(`[rAF] frame callback fires t=${t.toFixed(1)}`);let e=this._frameCallback;this._frameCallback=null,this._frameCallbackId=0,this._lastFrameCallback=e,this._lastFrameTime=t,e(t)}else if(this._lastFrameCallback!==null){this._replaying=!0;try{this._lastFrameCallback(this._lastFrameTime)}finally{this._replaying=!1}}return!0}),!0});this.connect(`resize`,()=>{let e=this.get_allocated_width(),t=this.get_allocated_height();this._canvas&&(this._canvas.dispatchEvent(new c(`resize`)),r(this._canvas,e,t));for(let n of this._resizeCallbacks)n(e,t);this._frameCallback&&this.requestAnimationFrame(this._frameCallback)}),this.connect(`unrealize`,()=>{this._renderTag!==null&&(this.disconnect(this._renderTag),this._renderTag=null),this._tickCallbackId!==null&&(this.remove_tick_callback(this._tickCallbackId),this._tickCallbackId=null),this._frameCallback=null,this._lastFrameCallback=null,this._lastFrameTime=0,this._replaying=!1,this._canvas=null})}get canvas(){return this._canvas}onReady(e){if(this._canvas){let t=this._canvas.getContext(`webgl`);if(t){e(this._canvas,t);return}}this._readyCallbacks.push(e)}onWebGLReady(e){this.onReady(e)}onResize(e){this._resizeCallbacks.push(e)}requestAnimationFrame(e){let t=this._nextFrameId++;return this._replaying?t:(this._frameCallback=e,this._frameCallbackId=t,this.queue_render(),t)}cancelAnimationFrame(e){e!==0&&e===this._frameCallbackId&&(this._frameCallback=null,this._frameCallbackId=0,this._lastFrameCallback=null,this._lastFrameTime=0)}installGlobals(){let n=globalThis;n.requestAnimationFrame=e=>this.requestAnimationFrame(e),n.cancelAnimationFrame=e=>this.cancelAnimationFrame(e),n.WebGLRenderingContext=e,n.WebGL2RenderingContext=t,Object.defineProperty(globalThis,"devicePixelRatio",{get:()=>this.get_scale_factor()||1,configurable:!0});let r=this._timeOrigin;n.performance={now:()=>(a.get_monotonic_time()-r)/1e3,timeOrigin:Date.now()}}});export{l as WebGLBridge};
+import"./_virtual/_rolldown/runtime.js";import{WebGLRenderingContext as e}from"./webgl-rendering-context.js";import{WebGL2RenderingContext as t}from"./webgl2-rendering-context.js";import{HTMLCanvasElement as n}from"./html-canvas-element.js";import{notifyElementResize as r}from"@gjsify/dom-elements";import i from"gi://GObject";import a from"gi://Gdk?version=4.0";import o from"gi://GLib?version=2.0";import s from"gi://Gtk?version=4.0";import{attachEventControllers as c}from"@gjsify/event-bridge";import{Event as l}from"@gjsify/dom-events";const u=i.registerClass({GTypeName:`GjsifyWebGLBridge`},class WebGLBridge extends s.GLArea{constructor(e){super(e),this._canvas=null,this._readyCallbacks=[],this._resizeCallbacks=[],this._renderTag=null,this._tickCallbackId=null,this._frameCallback=null,this._lastFrameCallback=null,this._lastFrameTime=0,this._replaying=!1,this._frameCallbackId=0,this._nextFrameId=1,this._timeOrigin=o.get_monotonic_time(),this.set_allowed_apis(a.GLAPI.GL|a.GLAPI.GLES),this.set_required_version(3,2),this.set_has_depth_buffer(!0),this.set_has_stencil_buffer(!0),c(this,()=>this._canvas,{captureKeys:!0}),this._tickCallbackId=this.add_tick_callback((e,t)=>(this._frameCallback!==null&&this.queue_render(),o.SOURCE_CONTINUE));let t=this.connect(`render`,()=>{this.disconnect(t),this.make_current(),this._canvas=new n(this);{let e=globalThis;e.document?.body&&e.document.body.appendChild(this._canvas)}this._canvas.getContext(`webgl2`);let e=this._canvas.getContext(`webgl`);if(e){for(let t of this._readyCallbacks)t(this._canvas,e);this._readyCallbacks=[]}return this._renderTag=this.connect(`render`,e=>{let t=(o.get_monotonic_time()-this._timeOrigin)/1e3;if(this._frameCallback!==null){globalThis.__GJSIFY_DEBUG_RAF===!0&&console.log(`[rAF] frame callback fires t=${t.toFixed(1)}`);let e=this._frameCallback;this._frameCallback=null,this._frameCallbackId=0,this._lastFrameCallback=e,this._lastFrameTime=t,e(t)}else if(this._lastFrameCallback!==null){this._replaying=!0;try{this._lastFrameCallback(this._lastFrameTime)}finally{this._replaying=!1}}return!0}),!0});this.connect(`resize`,()=>{let e=this.get_allocated_width(),t=this.get_allocated_height();this._canvas&&(this._canvas.dispatchEvent(new l(`resize`)),r(this._canvas,e,t));for(let n of this._resizeCallbacks)n(e,t);this._frameCallback&&this.requestAnimationFrame(this._frameCallback)}),this.connect(`unrealize`,()=>{this._renderTag!==null&&(this.disconnect(this._renderTag),this._renderTag=null),this._tickCallbackId!==null&&(this.remove_tick_callback(this._tickCallbackId),this._tickCallbackId=null),this._frameCallback=null,this._lastFrameCallback=null,this._lastFrameTime=0,this._replaying=!1,this._canvas=null})}get canvas(){return this._canvas}onReady(e){if(this._canvas){let t=this._canvas.getContext(`webgl`);if(t){e(this._canvas,t);return}}this._readyCallbacks.push(e)}onWebGLReady(e){this.onReady(e)}onResize(e){this._resizeCallbacks.push(e)}requestAnimationFrame(e){let t=this._nextFrameId++;return this._replaying?t:(this._frameCallback=e,this._frameCallbackId=t,this.queue_render(),t)}cancelAnimationFrame(e){e!==0&&e===this._frameCallbackId&&(this._frameCallback=null,this._frameCallbackId=0,this._lastFrameCallback=null,this._lastFrameTime=0)}installGlobals(){let n=globalThis;n.requestAnimationFrame=e=>this.requestAnimationFrame(e),n.cancelAnimationFrame=e=>this.cancelAnimationFrame(e),n.WebGLRenderingContext=e,n.WebGL2RenderingContext=t,Object.defineProperty(globalThis,"devicePixelRatio",{get:()=>this.get_scale_factor()||1,configurable:!0});let r=this._timeOrigin;n.performance={now:()=>(o.get_monotonic_time()-r)/1e3,timeOrigin:Date.now()}}});export{u as WebGLBridge};

package/lib/types/webgl-bridge.d.ts

@@ -1,5 +1,5 @@
 import GObject from 'gi://GObject';
-import type Gdk from 'gi://Gdk?version=4.0';
+import Gdk from 'gi://Gdk?version=4.0';
 import GLib from 'gi://GLib?version=2.0';
 import Gtk from 'gi://Gtk?version=4.0';
 import { HTMLCanvasElement as OurHTMLCanvasElement } from './html-canvas-element.js';

package/package.json

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