@gjsify/webgl 0.0.3 → 0.1.0

package/README.md

@@ -1,14 +1,86 @@
 # @gjsify/webgl
 
-WebGL module for Gjs
+GJS implementation of WebGL 1.0/2.0 using a custom Vala extension (gwebgl). Provides CanvasWebGLWidget extending Gtk.GLArea.
 
-## Dependencies
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
 
+## Installation
+
+```bash
+npm install @gjsify/webgl
+# or
+yarn add @gjsify/webgl
+```
+
+## Usage
+
+```typescript
+import { CanvasWebGLWidget } from '@gjsify/webgl';
+
+const widget = new CanvasWebGLWidget();
+widget.installGlobals();
+
+widget.onReady((canvas, gl) => {
+  gl.clearColor(0, 0, 0, 1);
+  gl.clear(gl.COLOR_BUFFER_BIT);
+});
+
+window.set_child(widget);
+```
+
+## Running GJS apps that use this package
+
+This package ships prebuilt native libraries for supported platforms:
+
+```
+prebuilds/
+  linux-x86_64/   libgwebgl.so + Gwebgl-0.1.typelib
+  linux-aarch64/  libgwebgl.so + Gwebgl-0.1.typelib
+```
+
+Use the gjsify CLI to run your app — it automatically sets `LD_LIBRARY_PATH` and
+`GI_TYPELIB_PATH` so GJS can find the native library:
+
+```bash
+gjsify run dist/gjs.js
+```
+
+To see what env vars are needed for running directly with `gjs`:
+
+```bash
+gjsify info dist/gjs.js
+# or for shell eval:
+eval $(gjsify info --export)
+gjs -m dist/gjs.js
 ```
-sudo dnf install libepoxy-devel
+
+## Building the native library locally
+
+Requires: `meson`, `valac`, `gcc`, `libepoxy-devel`, `gtk4-devel`, `gdk-pixbuf2-devel`, `gobject-introspection-devel`
+
+```bash
+# Fedora / RHEL
+sudo dnf install meson vala gcc libepoxy-devel gtk4-devel gdk-pixbuf2-devel gobject-introspection-devel
+
+# Build
+yarn build:meson
+
+# Build and copy to prebuilds/ for the current architecture
+yarn build:prebuilds
 ```
 
+## Prebuilt binaries
+
+Prebuilds for `linux-x86_64` and `linux-aarch64` 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.
+
 ## Inspirations and credits
- * https://github.com/realh/gwebgl
- * https://github.com/stackgl/headless-gl
- * https://github.com/Maia-Everett/valagl
+
+- [realh/gwebgl](https://github.com/realh/gwebgl)
+- [stackgl/headless-gl](https://github.com/stackgl/headless-gl)
+- [Maia-Everett/valagl](https://github.com/Maia-Everett/valagl)
+
+## License
+
+MIT

package/lib/esm/canvas-webgl-widget.js

@@ -0,0 +1,116 @@
+import GObject from "gi://GObject";
+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";
+import { attachEventControllers } from "@gjsify/event-bridge";
+const CanvasWebGLWidget = GObject.registerClass(
+  { GTypeName: "GjsifyCanvasWebGLWidget" },
+  class CanvasWebGLWidget2 extends Gtk.GLArea {
+    constructor(params) {
+      super(params);
+      this._canvas = null;
+      this._readyCallbacks = [];
+      this._renderTag = null;
+      this._tickCallbackId = null;
+      this._frameCallback = null;
+      // Time origin in microseconds (GLib monotonic clock).
+      // Both requestAnimationFrame timestamps and performance.now() are
+      // relative to this origin, matching the browser DOMHighResTimeStamp spec.
+      this._timeOrigin = GLib.get_monotonic_time();
+      this.set_use_es(true);
+      this.set_required_version(3, 2);
+      this.set_has_depth_buffer(true);
+      this.set_has_stencil_buffer(true);
+      attachEventControllers(this, () => this._canvas);
+      const initId = this.connect("render", () => {
+        this.disconnect(initId);
+        this.make_current();
+        this._canvas = new OurHTMLCanvasElement(this);
+        const gl = this._canvas.getContext("webgl");
+        if (gl) {
+          for (const cb of this._readyCallbacks) {
+            cb(this._canvas, gl);
+          }
+          this._readyCallbacks = [];
+        }
+        return true;
+      });
+      this.connect("unrealize", () => {
+        if (this._renderTag !== null) {
+          this.disconnect(this._renderTag);
+          this._renderTag = null;
+        }
+        if (this._tickCallbackId !== null) {
+          this.remove_tick_callback(this._tickCallbackId);
+          this._tickCallbackId = null;
+        }
+        this._canvas = null;
+      });
+    }
+    /** The HTMLCanvasElement wrapping this GLArea. Available after the first render. */
+    get canvas() {
+      return this._canvas;
+    }
+    /**
+     * Registers a callback to be called once the WebGL context is ready.
+     * If the context is already available, the callback fires synchronously.
+     */
+    onReady(cb) {
+      if (this._canvas) {
+        const gl = this._canvas.getContext("webgl");
+        if (gl) {
+          cb(this._canvas, gl);
+          return;
+        }
+      }
+      this._readyCallbacks.push(cb);
+    }
+    /**
+     * @deprecated Use `onReady()` instead.
+     */
+    onWebGLReady(cb) {
+      this.onReady(cb);
+    }
+    /**
+     * Schedules a single animation frame callback, matching the browser `requestAnimationFrame` API.
+     * Backed by GTK frame clock (vsync-synced) + the GLArea render signal.
+     * Returns 0 (handle — cancel not yet implemented).
+     */
+    requestAnimationFrame(cb) {
+      this._frameCallback = cb;
+      if (this._tickCallbackId === null) {
+        this._tickCallbackId = this.add_tick_callback((_widget, _frameClock) => {
+          this._tickCallbackId = null;
+          if (this._renderTag === null) {
+            this._renderTag = this.connect("render", () => {
+              this.disconnect(this._renderTag);
+              this._renderTag = null;
+              const time = (GLib.get_monotonic_time() - this._timeOrigin) / 1e3;
+              this._frameCallback?.(time);
+              return true;
+            });
+          }
+          this.queue_render();
+          return GLib.SOURCE_REMOVE;
+        });
+      }
+      this.queue_render();
+      return 0;
+    }
+    /**
+     * Sets browser globals (`requestAnimationFrame`, `performance`) so that
+     * browser-targeted code (e.g. Three.js) works unchanged on GJS.
+     */
+    installGlobals() {
+      globalThis.requestAnimationFrame = (cb) => this.requestAnimationFrame(cb);
+      const timeOrigin = this._timeOrigin;
+      globalThis.performance = {
+        now: () => (GLib.get_monotonic_time() - timeOrigin) / 1e3,
+        timeOrigin: Date.now()
+      };
+    }
+  }
+);
+export {
+  CanvasWebGLWidget
+};

package/lib/esm/html-canvas-element.js

@@ -1,70 +1,51 @@
-import { warnNotImplemented, notImplemented } from "@gjsify/utils";
-import { GjsifyWebGLRenderingContext } from "./webgl-rendering-context.js";
-class GjsifyHTMLCanvasElement {
+import { HTMLCanvasElement as BaseHTMLCanvasElement } from "@gjsify/dom-elements";
+import { WebGLRenderingContext as OurWebGLRenderingContext } from "./webgl-rendering-context.js";
+import { WebGL2RenderingContext as OurWebGL2RenderingContext } from "./webgl2-rendering-context.js";
+class HTMLCanvasElement extends BaseHTMLCanvasElement {
   constructor(gtkGlArea) {
+    super();
     this.gtkGlArea = gtkGlArea;
   }
-  _getGlArea() {
-    return this.gtkGlArea;
+  /** Width from the GTK GLArea allocated size (overrides DOM attr-backed getter). */
+  get width() {
+    return this.gtkGlArea.get_allocated_width();
   }
-  /** Gets the height of a canvas element on a document. */
+  set width(_width) {
+  }
+  /** Height from the GTK GLArea allocated size (overrides DOM attr-backed getter). */
   get height() {
     return this.gtkGlArea.get_allocated_height();
   }
-  get clientHeight() {
-    return this.height;
-  }
-  /** Sets the height of a canvas element on a document. */
   set height(_height) {
-    warnNotImplemented("GjsifyHTMLCanvasElement.set_height");
-  }
-  /** Gets the width of a canvas element on a document. */
-  get width() {
-    return this.gtkGlArea.get_allocated_width();
-  }
-  /** Sets the width of a canvas element on a document. */
-  set width(_width) {
-    warnNotImplemented("GjsifyHTMLCanvasElement.set_width");
   }
   get clientWidth() {
     return this.width;
   }
-  captureStream(_frameRequestRate) {
-    notImplemented("HTMLCanvasElement.captureStream");
-    return new MediaStream();
-  }
-  getContext(contextId, options) {
-    switch (contextId) {
-      case "webgl":
-        if (this._webgl) {
-          return this._webgl;
-        }
-        this._webgl = new GjsifyWebGLRenderingContext(this, options);
-        return this._webgl;
-      default:
-        warnNotImplemented(`GjsifyHTMLCanvasElement.getContext("${contextId}")`);
-    }
-    return null;
+  get clientHeight() {
+    return this.height;
   }
-  toBlob(_callback, _type, _quality) {
-    notImplemented("HTMLCanvasElement.toBlob");
+  /** Returns the underlying Gtk.GLArea. Used by WebGLRenderingContext for GLSL version detection. */
+  getGlArea() {
+    return this.gtkGlArea;
   }
   /**
-   * Returns the content of the current canvas as an image that you can use as a source for another canvas or an HTML element.
-   * @param _type The standard MIME type for the image format to return. If you do not specify this parameter, the default value is a PNG format image.
+   * Returns a WebGL rendering context backed by the underlying Gtk.GLArea.
+   * 'webgl' and 'experimental-webgl' return a WebGLRenderingContext (WebGL 1.0).
+   * 'webgl2' returns a WebGL2RenderingContext (WebGL 2.0).
+   * Other context types emit a warning and return null.
    */
-  toDataURL(_type, _quality) {
-    notImplemented("HTMLCanvasElement.toDataURL");
-    return "";
-  }
-  addEventListener(_type, _listener, _options) {
-    notImplemented("HTMLCanvasElement.addEventListener");
-  }
-  removeEventListener(_type, _listener, _options) {
-    notImplemented("HTMLCanvasElement.removeEventListener");
+  getContext(contextId, options) {
+    if (contextId === "webgl" || contextId === "experimental-webgl") {
+      this._webgl ??= new OurWebGLRenderingContext(this, options);
+      return this._webgl;
+    }
+    if (contextId === "webgl2") {
+      this._webgl2 ??= new OurWebGL2RenderingContext(this, options);
+      return this._webgl2;
+    }
+    return super.getContext(contextId, options);
   }
 }
 export {
-  GjsifyHTMLCanvasElement,
-  GjsifyHTMLCanvasElement as HTMLCanvasElement
+  HTMLCanvasElement
 };

package/lib/esm/index.js

@@ -2,6 +2,7 @@ import "@girs/gjs";
 import "@girs/gio-2.0";
 import "@girs/gtk-4.0";
 export * from "./html-canvas-element.js";
+export * from "./canvas-webgl-widget.js";
 export * from "./webgl-active-info.js";
 export * from "./webgl-buffer.js";
 export * from "./webgl-context-attributes.js";
@@ -9,8 +10,14 @@ export * from "./webgl-drawing-buffer-wrapper.js";
 export * from "./webgl-framebuffer.js";
 export * from "./webgl-program.js";
 export * from "./webgl-renderbuffer.js";
+export * from "./webgl-query.js";
 export * from "./webgl-rendering-context.js";
+export * from "./webgl-sampler.js";
 export * from "./webgl-shader-precision-format.js";
+export * from "./webgl-sync.js";
+export * from "./webgl-transform-feedback.js";
+export * from "./webgl-vertex-array-object.js";
+export * from "./webgl2-rendering-context.js";
 export * from "./webgl-shader.js";
 export * from "./webgl-texture-unit.js";
 export * from "./webgl-texture.js";