p5.tree 0.0.1

package/dist/p5.tree.js

@@ -0,0 +1,2754 @@
+(function (p5) {
+  'use strict';
+
+  /**
+   * @file Adds Tree rendering functions to the p5 prototype.
+   * @version 0.0.1
+   * @author JP Charalambos
+   * @license GPL-3.0-only
+   *
+   * @description
+   * A p5.js WEBGL addon for shader development and space transformations.
+   * 
+   * Camera path recording/playback section.
+   *
+   * Requires WEBGL (p5.Camera).
+   *
+   * Camera API:
+   *   camera.path : p5.Camera[]
+   *   camera.addPath(...)
+   *   camera.playPath(...)
+   *   camera.stopPath(...)
+   *   camera.resetPath(...)
+   *   camera.seekPath(...)
+   *
+   * p5 wrappers (same names) forward to current active camera.
+   *
+   * Uses p5 lifecicle predraw hook to tick playback automatically.
+   *
+   * Projection safety:
+   *   p5.Camera.slerp requires that all cameras use the same projection.
+   *   We enforce this by comparing projMatrix.mat4 signatures.
+   */
+
+
+  p5.registerAddon((p5, fn, lifecycles) => {
+    // --- namespace (module shelf) ---
+    p5.Tree ||= {};
+    
+    const CONST = value => ({ value, writable: false, enumerable: true, configurable: false });
+    
+    Object.defineProperties(p5.Tree, {
+      VERSION: CONST('0.0.1'),
+                            
+      NONE: CONST(0),
+    
+      // Spaces
+      WORLD: CONST('WORLD'),
+      EYE: CONST('EYE'),
+      NDC: CONST('NDC'),
+      SCREEN: CONST('SCREEN'),
+      MODEL: CONST('MODEL'),
+    
+      // Points and vectors
+      ORIGIN: CONST(Object.freeze([0, 0, 0])),
+    
+      i: CONST(Object.freeze([1, 0, 0])),
+      j: CONST(Object.freeze([0, 1, 0])),
+      k: CONST(Object.freeze([0, 0, 1])),
+    
+      _i: CONST(Object.freeze([-1, 0, 0])),
+      _j: CONST(Object.freeze([0, -1, 0])),
+      _k: CONST(Object.freeze([0, 0, -1])),
+                            
+      // Axes / grid bits & styles
+      X: CONST(1 << 0),
+      _X: CONST(1 << 1),
+      Y: CONST(1 << 2),
+      _Y: CONST(1 << 3),
+      Z: CONST(1 << 4),
+      _Z: CONST(1 << 5),
+      LABELS: CONST(1 << 6),
+      
+      DOTS: CONST(0),
+      SOLID: CONST(1),
+                            
+      // bullsEye
+      CIRCLE: CONST(0),
+      SQUARE: CONST(1),
+                            
+      // View frustum bits
+      NEAR:   CONST(1 << 0),
+      FAR:    CONST(1 << 1),
+      LEFT:   CONST(1 << 2),
+      RIGHT:  CONST(1 << 3),
+      BOTTOM: CONST(1 << 4),
+      TOP:    CONST(1 << 5),
+      BODY:   CONST(1 << 6),
+      APEX:   CONST(1 << 7),
+                            
+      // Visibility
+      INVISIBLE: CONST(0),
+      VISIBLE: CONST(1),
+      SEMIVISIBLE: CONST(2),
+    });
+    
+    // ---------------------------------------------------------------------------
+    // Matrix queries (p5.treegl -> p5.tree, p5-v2)
+    // Rely on p5-v2, minimal safeties, cache-friendly.
+    // ---------------------------------------------------------------------------
+
+    /**
+     * @private
+     * Returns the WEBGL renderer or undefined.
+     * @param {p5} pInst
+     * @returns {p5.RendererGL|undefined}
+     */
+    const _rendererGL = function (pInst) {
+      const r = pInst._renderer;
+      return r instanceof p5.RendererGL ? r : undefined;
+    };
+
+    // ---------------------------------------------------------------------------
+    // p5.Matrix operations (immutable)
+    // ---------------------------------------------------------------------------
+    
+    /**
+     * @private
+     * Returns the inverse of a matrix (immutable).
+     * p5-v2: invert(a) inverts 'a' into 'this' (gl-matrix style).
+     * @param {p5.Matrix} matrix
+     * @returns {p5.Matrix}
+     */
+    const _invert = function (matrix) {
+      const out = matrix.clone();
+      out.invert(matrix);
+      return out;
+    };
+
+    /**
+     * @private
+     * Returns the transpose of a matrix (immutable).
+     * Fast-path for mat4 / mat3 to match treegl semantics.
+     * @param {p5.Matrix} matrix
+     * @returns {p5.Matrix}
+     */
+    const _transpose = function (matrix) {
+      const m4 = matrix.mat4;
+      if (m4) {
+        return new p5.Matrix([
+          m4[0], m4[4], m4[8],  m4[12],
+          m4[1], m4[5], m4[9],  m4[13],
+          m4[2], m4[6], m4[10], m4[14],
+          m4[3], m4[7], m4[11], m4[15]
+        ]);
+      }
+      const m3 = matrix.mat3;
+      if (m3) {
+        return new p5.Matrix([
+          m3[0], m3[3], m3[6],
+          m3[1], m3[4], m3[7],
+          m3[2], m3[5], m3[8]
+        ]);
+      }
+    };
+    
+    p5.Matrix.prototype.mult4 = function (vector) {
+      return new p5.Vector(...this._mult4([vector.x, vector.y, vector.z, 1]));
+    };
+    
+    p5.Matrix.prototype._mult4 = function (vec4) {
+      if (this.mat4 === undefined) {
+        console.error('_mult4 only works with mat4');
+        return;
+      }
+      return [
+        this.mat4[0] * vec4[0] + this.mat4[4] * vec4[1] + this.mat4[8]  * vec4[2] + this.mat4[12] * vec4[3],
+        this.mat4[1] * vec4[0] + this.mat4[5] * vec4[1] + this.mat4[9]  * vec4[2] + this.mat4[13] * vec4[3],
+        this.mat4[2] * vec4[0] + this.mat4[6] * vec4[1] + this.mat4[10] * vec4[2] + this.mat4[14] * vec4[3],
+        this.mat4[3] * vec4[0] + this.mat4[7] * vec4[1] + this.mat4[11] * vec4[2] + this.mat4[15] * vec4[3]
+      ];
+    };
+
+    /**
+     * Returns the transpose of a matrix (immutable).
+     * @param {p5.Matrix} matrix
+     * @returns {p5.Matrix}
+     */
+    fn.tMatrix = function (matrix) {
+      return _transpose(matrix);
+    };
+
+    /**
+     * Returns the inverse of a matrix.
+     * @param {p5.Matrix} matrix
+     * @returns {p5.Matrix}
+     */
+    fn.iMatrix = function (matrix) {
+      return _invert(matrix);
+    };
+
+    /**
+     * Returns A * B without mutating A (immutable).
+     * @param {p5.Matrix} a
+     * @param {p5.Matrix} b
+     * @returns {p5.Matrix}
+     */
+    fn.axbMatrix = function (a, b) {
+      return a.clone().mult(b);
+    };
+    
+    /**
+     * Creates a new p5.Matrix.
+     * (Wrapper for `new p5.Matrix(...args)`.)
+     *
+     * - `createMatrix()` → identity 4×4
+     * - `createMatrix(n)` → identity n×n (typically 3 or 4)
+     * - `createMatrix(coeffs)` → matrix from coefficients (length 9 or 16)
+     *
+     * @param {...(number|Array<number>)} [args] Arguments forwarded to the p5.Matrix constructor.
+     * @returns {p5.Matrix}
+     */
+    fn.createMatrix = (...args) => new p5.Matrix(...args);
+
+    // ---------------------------------------------------------------------------
+    // Matrix queries (immutable, cache-friendly)
+    // ---------------------------------------------------------------------------
+
+    /**
+     * Returns the current projection matrix (immutable copy).
+     * @returns {p5.Matrix}
+     */
+    p5.RendererGL.prototype.pMatrix = function () {
+      return this.states.uPMatrix.clone();
+    };
+
+    /**
+     * Returns the current projection matrix (immutable copy).
+     * Requires WEBGL.
+     * @returns {p5.Matrix}
+     */
+    fn.pMatrix = function () {
+      return _rendererGL(this).pMatrix();
+    };
+
+    /**
+     * Returns the current model matrix (immutable copy).
+     * @returns {p5.Matrix}
+     */
+    p5.RendererGL.prototype.mMatrix = function () {
+      return this.states.uModelMatrix.clone();
+    };
+
+    /**
+     * Returns the current model matrix (immutable copy).
+     * Requires WEBGL.
+     * @returns {p5.Matrix}
+     */
+    fn.mMatrix = function () {
+      return _rendererGL(this).mMatrix();
+    };
+
+    /**
+     * Returns the view matrix (world -> camera) for this camera (immutable copy).
+     * @returns {p5.Matrix}
+     */
+    p5.Camera.prototype.vMatrix = function () {
+      return this.cameraMatrix.clone();
+    };
+
+    /**
+     * Returns the eye matrix (camera -> world) for this camera (immutable).
+     * @returns {p5.Matrix}
+     */
+    p5.Camera.prototype.eMatrix = function () {
+      return _invert(this.cameraMatrix);
+    };
+
+    /**
+     * Returns the current view matrix (world -> camera) (immutable copy).
+     * Prefers the renderer cached view matrix when available.
+     * @returns {p5.Matrix}
+     */
+    p5.RendererGL.prototype.vMatrix = function () {
+      return (this.states.uViewMatrix || this.states.curCamera.cameraMatrix).clone();
+    };
+
+    /**
+     * Returns the current view matrix (world -> camera) (immutable copy).
+     * Requires WEBGL.
+     * @returns {p5.Matrix}
+     */
+    fn.vMatrix = function () {
+      return _rendererGL(this).vMatrix();
+    };
+
+    /**
+     * Returns the current eye matrix (camera -> world) (immutable).
+     * @returns {p5.Matrix}
+     */
+    p5.RendererGL.prototype.eMatrix = function () {
+      return _invert(this.states.uViewMatrix || this.states.curCamera.cameraMatrix);
+    };
+
+    /**
+     * Returns the current eye matrix (camera -> world) (immutable).
+     * Requires WEBGL.
+     * @returns {p5.Matrix}
+     */
+    fn.eMatrix = function () {
+      return _rendererGL(this).eMatrix();
+    };
+
+    /**
+     * lMatrix({ from, to }):
+     * Location transform (mat4) mapping points from `from` space to `to` space.
+     * treegl semantics: to^-1 * from.
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.from=new p5.Matrix()] Source frame matrix.
+     * @param {p5.Matrix} [opts.to=this.eMatrix()] Target frame matrix.
+     * @returns {p5.Matrix}
+     */
+    p5.RendererGL.prototype.lMatrix = function ({
+      from = new p5.Matrix(4),
+      to = this.eMatrix()
+    } = {}) {
+      return _invert(to).mult(from);
+    };
+
+    /**
+     * lMatrix({ from, to }):
+     * Location transform (mat4) mapping points from `from` space to `to` space.
+     * Requires WEBGL.
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.from]
+     * @param {p5.Matrix} [opts.to]
+     * @returns {p5.Matrix}
+     */
+    fn.lMatrix = function (opts = {}) {
+      return _rendererGL(this).lMatrix(opts);
+    };
+
+    /**
+     * dMatrix({ from, to, matrix }):
+     * Direction transform (mat3) mapping vectors from `from` space to `to` space.
+     * Translation ignored. treegl semantics: linear_part(from^-1 * to).
+     * If `matrix` (mat4) is provided, uses linear_part(matrix).
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.from=new p5.Matrix()] Source frame matrix.
+     * @param {p5.Matrix} [opts.to=this.eMatrix()] Target frame matrix.
+     * @param {p5.Matrix} [opts.matrix] Precomputed mat4 override.
+     * @returns {p5.Matrix} mat3
+     */
+    p5.RendererGL.prototype.dMatrix = function ({
+      from = new p5.Matrix(4),
+      to = this.eMatrix(),
+      matrix
+    } = {}) {
+      const m = (matrix || _invert(from).mult(to));
+      const a = m.mat4 || m.matrix; // v2: mat4 getter if 4x4, else fallback
+      // Note: this is the same "mat4 -> mat3 transpose" as treegl (baked into indices)
+      return new p5.Matrix([
+        a[0], a[4], a[8],
+        a[1], a[5], a[9],
+        a[2], a[6], a[10]
+      ]);
+    };
+
+    /**
+     * dMatrix({ from, to, matrix }):
+     * Direction transform (mat3) mapping vectors from `from` space to `to` space.
+     * Requires WEBGL.
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.from]
+     * @param {p5.Matrix} [opts.to]
+     * @param {p5.Matrix} [opts.matrix]
+     * @returns {p5.Matrix} mat3
+     */
+    fn.dMatrix = function (opts = {}) {
+      return _rendererGL(this).dMatrix(opts);
+    };
+
+    /**
+     * mvMatrix({ vMatrix, mMatrix }):
+     * ModelView matrix (mat4) = M * V (p5-v2 convention).
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.vMatrix=this.vMatrix()] View matrix.
+     * @param {p5.Matrix} [opts.mMatrix=this.mMatrix()] Model matrix.
+     * @returns {p5.Matrix}
+     */
+    p5.RendererGL.prototype.mvMatrix = function ({
+      vMatrix = this.vMatrix(),
+      mMatrix
+    } = {}) {
+      return (mMatrix || this.states.uModelMatrix).clone().mult(vMatrix);
+    };
+
+    /**
+     * mvMatrix({ vMatrix, mMatrix }):
+     * ModelView matrix (mat4) = M * V (p5-v2 convention).
+     * Requires WEBGL.
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.vMatrix]
+     * @param {p5.Matrix} [opts.mMatrix]
+     * @returns {p5.Matrix}
+     */
+    fn.mvMatrix = function (opts = {}) {
+      return _rendererGL(this).mvMatrix(opts);
+    };
+
+    /**
+     * nMatrix({ vMatrix, mMatrix, mvMatrix }):
+     * Normal matrix (mat3) = inverseTranspose(linear_part(MV)).
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.vMatrix] Optional view matrix.
+     * @param {p5.Matrix} [opts.mMatrix] Optional model matrix.
+     * @param {p5.Matrix} [opts.mvMatrix=this.mvMatrix({ mMatrix, vMatrix })] Optional MV matrix override.
+     * @returns {p5.Matrix} mat3
+     */
+    p5.RendererGL.prototype.nMatrix = function ({
+      vMatrix,
+      mMatrix,
+      mvMatrix = this.mvMatrix({ mMatrix, vMatrix })
+    } = {}) {
+      return _transpose(_invert(mvMatrix.createSubMatrix3x3()));
+    };
+
+    /**
+     * nMatrix({ vMatrix, mMatrix, mvMatrix }):
+     * Normal matrix (mat3) = inverseTranspose(linear_part(MV)).
+     * Requires WEBGL.
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.vMatrix]
+     * @param {p5.Matrix} [opts.mMatrix]
+     * @param {p5.Matrix} [opts.mvMatrix]
+     * @returns {p5.Matrix} mat3
+     */
+    fn.nMatrix = function (opts = {}) {
+      return _rendererGL(this).nMatrix(opts);
+    };
+
+    /**
+     * pmvMatrix({ pMatrix, vMatrix, mMatrix, mvMatrix }):
+     * PMV (mat4) = M * V * P (p5-v2 convention).
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.pMatrix=this.pMatrix()] Projection matrix.
+     * @param {p5.Matrix} [opts.vMatrix] Optional view matrix (used if mvMatrix is computed).
+     * @param {p5.Matrix} [opts.mMatrix] Optional model matrix (used if mvMatrix is computed).
+     * @param {p5.Matrix} [opts.mvMatrix=this.mvMatrix({ mMatrix, vMatrix })] Optional MV matrix override.
+     * @returns {p5.Matrix}
+     */
+    p5.RendererGL.prototype.pmvMatrix = function ({
+      pMatrix = this.pMatrix(),
+      vMatrix,
+      mMatrix,
+      mvMatrix
+    } = {}) {
+      return (mvMatrix ? mvMatrix.clone() : this.mvMatrix({ mMatrix, vMatrix })).mult(pMatrix);
+    };
+
+    /**
+     * pmvMatrix({ pMatrix, vMatrix, mMatrix, mvMatrix }):
+     * PMV (mat4) = M * V * P (p5-v2 convention).
+     * Requires WEBGL.
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.pMatrix]
+     * @param {p5.Matrix} [opts.vMatrix]
+     * @param {p5.Matrix} [opts.mMatrix]
+     * @param {p5.Matrix} [opts.mvMatrix]
+     * @returns {p5.Matrix}
+     */
+    fn.pmvMatrix = function (opts = {}) {
+      return _rendererGL(this).pmvMatrix(opts);
+    };
+
+    /**
+     * pvMatrix({ pMatrix, vMatrix }):
+     * PV (mat4) = V * P (p5-v2 convention).
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.pMatrix=this.pMatrix()] Projection matrix.
+     * @param {p5.Matrix} [opts.vMatrix=this.vMatrix()] View matrix.
+     * @returns {p5.Matrix}
+     */
+    p5.RendererGL.prototype.pvMatrix = function ({
+      pMatrix = this.pMatrix(),
+      vMatrix
+    } = {}) {
+      return (vMatrix || (this.states.uViewMatrix || this.states.curCamera.cameraMatrix)).clone().mult(pMatrix);
+    };
+
+    /**
+     * pvMatrix({ pMatrix, vMatrix }):
+     * PV (mat4) = V * P (p5-v2 convention).
+     * Requires WEBGL.
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.pMatrix]
+     * @param {p5.Matrix} [opts.vMatrix]
+     * @returns {p5.Matrix}
+     */
+    fn.pvMatrix = function (opts = {}) {
+      return _rendererGL(this).pvMatrix(opts);
+    };
+    
+    /**
+     * ipvMatrix({ pMatrix, vMatrix, pvMatrix }):
+     * Inverse(PV) (mat4).
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.pMatrix] Optional projection matrix (used if pvMatrix is computed).
+     * @param {p5.Matrix} [opts.vMatrix] Optional view matrix (used if pvMatrix is computed).
+     * @param {p5.Matrix} [opts.pvMatrix=this.pvMatrix({ pMatrix, vMatrix })] Optional PV matrix override.
+     * @returns {p5.Matrix}
+     */
+    p5.RendererGL.prototype.ipvMatrix = function ({
+      pMatrix,
+      vMatrix,
+      pvMatrix = this.pvMatrix({ pMatrix, vMatrix })
+    } = {}) {
+      return _invert(pvMatrix);
+    };
+    
+    /**
+     * ipvMatrix({ pMatrix, vMatrix, pvMatrix }):
+     * Inverse(PV) (mat4). Requires WEBGL.
+     * @param {object} [opts]
+     * @returns {p5.Matrix}
+     */
+    fn.ipvMatrix = function (opts = {}) {
+      return _rendererGL(this).ipvMatrix(opts);
+    };
+
+    // ---------------------------------------------------------------------------
+    // Projection matrix queries (isOrtho, planes, fov, hfov)
+    // ---------------------------------------------------------------------------
+
+    /**
+     * Returns true if this projection matrix is orthographic.
+     * @returns {boolean}
+     */
+    p5.Matrix.prototype.isOrtho = function () {
+      return this.mat4[15] !== 0;
+    };
+
+    /**
+     * Returns true if the current projection is orthographic.
+     * @returns {boolean}
+     */
+    p5.RendererGL.prototype.isOrtho = function () {
+      return this.pMatrix().isOrtho();
+    };
+
+    /**
+     * Returns true if the current projection is orthographic.
+     * Requires WEBGL.
+     * @returns {boolean}
+     */
+    fn.isOrtho = function () {
+      return _rendererGL(this).isOrtho();
+    };
+
+    /**
+     * Near plane distance.
+     * @returns {number}
+     */
+    p5.Matrix.prototype.nPlane = function () {
+      const m = this.mat4;
+      return m[15] === 0 ? m[14] / (m[10] - 1) : (1 + m[14]) / m[10];
+    };
+
+    /**
+     * Far plane distance.
+     * @returns {number}
+     */
+    p5.Matrix.prototype.fPlane = function () {
+      const m = this.mat4;
+      return m[15] === 0 ? m[14] / (1 + m[10]) : (m[14] - 1) / m[10];
+    };
+
+    /**
+     * Left plane at the near plane.
+     * @returns {number}
+     */
+    p5.Matrix.prototype.lPlane = function () {
+      const m = this.mat4;
+      return m[15] === 1 ? -(1 + m[12]) / m[0] : this.nPlane() * (m[8] - 1) / m[0];
+    };
+
+    /**
+     * Right plane at the near plane.
+     * @returns {number}
+     */
+    p5.Matrix.prototype.rPlane = function () {
+      const m = this.mat4;
+      return m[15] === 1 ? (1 - m[12]) / m[0] : this.nPlane() * (1 + m[8]) / m[0];
+    };
+
+    /**
+     * Top plane at the near plane.
+     * @returns {number}
+     */
+    p5.Matrix.prototype.tPlane = function () {
+      const m = this.mat4;
+      return m[15] === 1 ? (m[13] - 1) / m[5] : this.nPlane() * (m[9] - 1) / m[5];
+    };
+
+    /**
+     * Bottom plane at the near plane.
+     * @returns {number}
+     */
+    p5.Matrix.prototype.bPlane = function () {
+      const m = this.mat4;
+      return m[15] === 1 ? (1 + m[13]) / m[5] : this.nPlane() * (1 + m[9]) / m[5];
+    };
+
+    /**
+     * Near plane distance for the current projection.
+     * @returns {number}
+     */
+    p5.RendererGL.prototype.nPlane = function () {
+      return this.pMatrix().nPlane();
+    };
+
+    /**
+     * Far plane distance for the current projection.
+     * @returns {number}
+     */
+    p5.RendererGL.prototype.fPlane = function () {
+      return this.pMatrix().fPlane();
+    };
+
+    /**
+     * Left plane for the current projection.
+     * @returns {number}
+     */
+    p5.RendererGL.prototype.lPlane = function () {
+      return this.pMatrix().lPlane();
+    };
+
+    /**
+     * Right plane for the current projection.
+     * @returns {number}
+     */
+    p5.RendererGL.prototype.rPlane = function () {
+      return this.pMatrix().rPlane();
+    };
+
+    /**
+     * Top plane for the current projection.
+     * @returns {number}
+     */
+    p5.RendererGL.prototype.tPlane = function () {
+      return this.pMatrix().tPlane();
+    };
+
+    /**
+     * Bottom plane for the current projection.
+     * @returns {number}
+     */
+    p5.RendererGL.prototype.bPlane = function () {
+      return this.pMatrix().bPlane();
+    };
+
+    /**
+     * Near plane distance for the current projection.
+     * Requires WEBGL.
+     * @returns {number}
+     */
+    fn.nPlane = function () {
+      return _rendererGL(this).nPlane();
+    };
+
+    /**
+     * Far plane distance for the current projection.
+     * Requires WEBGL.
+     * @returns {number}
+     */
+    fn.fPlane = function () {
+      return _rendererGL(this).fPlane();
+    };
+
+    /**
+     * Left plane for the current projection.
+     * Requires WEBGL.
+     * @returns {number}
+     */
+    fn.lPlane = function () {
+      return _rendererGL(this).lPlane();
+    };
+
+    /**
+     * Right plane for the current projection.
+     * Requires WEBGL.
+     * @returns {number}
+     */
+    fn.rPlane = function () {
+      return _rendererGL(this).rPlane();
+    };
+
+    /**
+     * Top plane for the current projection.
+     * Requires WEBGL.
+     * @returns {number}
+     */
+    fn.tPlane = function () {
+      return _rendererGL(this).tPlane();
+    };
+
+    /**
+     * Bottom plane for the current projection.
+     * Requires WEBGL.
+     * @returns {number}
+     */
+    fn.bPlane = function () {
+      return _rendererGL(this).bPlane();
+    };
+
+    /**
+     * Vertical field of view (radians), perspective only.
+     * @returns {number|undefined}
+     */
+    p5.Matrix.prototype.fov = function () {
+      if (this.mat4[15] !== 0) {
+        console.error('[tree.matrix] fov only works for a perspective projection.');
+        return;
+      }
+      return Math.abs(2 * Math.atan(1 / this.mat4[5]));
+    };
+
+    /**
+     * Horizontal field of view (radians), perspective only.
+     * @returns {number|undefined}
+     */
+    p5.Matrix.prototype.hfov = function () {
+      if (this.mat4[15] !== 0) {
+        console.error('[tree.matrix] hfov only works for a perspective projection.');
+        return;
+      }
+      return Math.abs(2 * Math.atan(1 / this.mat4[0]));
+    };
+
+    /**
+     * Vertical field of view (radians) of the current projection.
+     * @returns {number|undefined}
+     */
+    p5.RendererGL.prototype.fov = function () {
+      return this.pMatrix().fov();
+    };
+
+    /**
+     * Horizontal field of view (radians) of the current projection.
+     * @returns {number|undefined}
+     */
+    p5.RendererGL.prototype.hfov = function () {
+      return this.pMatrix().hfov();
+    };
+
+    /**
+     * Vertical field of view (radians) of the current projection.
+     * Requires WEBGL.
+     * @returns {number|undefined}
+     */
+    fn.fov = function () {
+      return _rendererGL(this).fov();
+    };
+
+    /**
+     * Horizontal field of view (radians) of the current projection.
+     * Requires WEBGL.
+     * @returns {number|undefined}
+     */
+    fn.hfov = function () {
+      return _rendererGL(this).hfov();
+    };
+
+    // --- private keys (shared internal state across protos) ---
+    const STATE_KEY = Symbol.for('tree.camera.path.state');
+    const PLAYERS_KEY = Symbol.for('tree.camera.path.players');
+
+    const clamp01 = function (x) {
+      return x < 0 ? 0 : (x > 1 ? 1 : x);
+    };
+
+    const isFiniteNumber = function (x) {
+      return typeof x === 'number' && Number.isFinite(x);
+    };
+
+    const warn = function (msg) {
+      console.warn('[tree.camera.path] ' + msg);
+    };
+
+    const ensurePath = function (cam) {
+      cam.path || (cam.path = []);
+      return cam.path;
+    };
+
+    const segmentCount = function (path) {
+      return Math.max(0, path.length - 1);
+    };
+
+    const getState = function (cam) {
+      cam[STATE_KEY] || (cam[STATE_KEY] = {
+        playing: false,
+        loop: false,
+        pingPong: false,
+        onEnd: undefined,
+        rate: 1,
+        duration: 30, // frames per segment
+        seg: 0,
+        f: 0,
+        pathIsOrtho: undefined
+      });
+      return cam[STATE_KEY];
+    };
+
+    const getPlayers = function (pInst) {
+      pInst[PLAYERS_KEY] || (pInst[PLAYERS_KEY] = new Set());
+      return pInst[PLAYERS_KEY];
+    };
+    
+    const getActiveCamera = function (pInst) {
+      const r = pInst && pInst._renderer;
+      return (
+        (r && r.states && r.states.curCamera) || // p5-v2 canonical
+        (r && (r._curCamera || r.curCamera || r._camera)) || // fallbacks
+        undefined
+      );
+    };
+
+    /**
+     * Interpolate camera pose at normalized global t in [0..1] along the whole path.
+     * Also updates internal seg/f so playPath resumes from that location.
+     */
+    const seekGlobal = function (cam, t) {
+      const path = ensurePath(cam);
+      const nSeg = segmentCount(path);
+      if (nSeg === 0) return;
+      const st = getState(cam);
+      const tt = clamp01(t);
+      const x = tt * nSeg;
+      const seg = Math.min(nSeg - 1, Math.floor(x));
+      const amt = x - seg;
+      cam.slerp(path[seg], path[seg + 1], amt);
+      st.seg = seg;
+      st.f = Math.round(amt * Math.max(1, st.duration | 0));
+    };
+
+    /**
+     * Interpolate camera pose at amt in [0..1] within a specific segment index.
+     */
+    const seekSegment = function (cam, amt, segIndex) {
+      const path = ensurePath(cam);
+      const nSeg = segmentCount(path);
+      if (nSeg === 0) return;
+      const st = getState(cam);
+      const seg = Math.max(0, Math.min(segIndex | 0, nSeg - 1));
+      const a = clamp01(amt);
+      cam.slerp(path[seg], path[seg + 1], a);
+      st.seg = seg;
+      st.f = Math.round(a * Math.max(1, st.duration | 0));
+    };
+
+    /**
+     * Playback tick.
+     *
+     * Playback runs in "frames per segment" (`duration`), and `rate` is interpreted
+     * as a speed multiplier applied per frame.
+     *
+     * Rate semantics:
+     * - rate > 0 : forward playback
+     * - rate < 0 : reverse playback
+     * - rate === 0 : stopped
+     *
+     * The absolute value of `rate` is used as a per-frame advance amount.
+     * Fractional rates are supported (e.g. 0.5 plays at half speed).
+     *
+     * Segment boundaries are handled according to playback mode:
+     * - pingPong: bounce at the ends and reverse direction
+     * - loop: wrap around to the opposite end
+     * - otherwise: stop at the end and optionally invoke `onEnd`
+     */
+    const tick = function (cam) {
+      const st = getState(cam);
+      if (!st.playing) return;
+      const path = ensurePath(cam);
+      const nSeg = segmentCount(path);
+      if (nSeg === 0) {
+        st.playing = false;
+        return;
+      }
+      const dur = Math.max(1, st.duration | 0);
+      const speed = Math.abs(st.rate);
+      if (speed === 0) {
+        st.playing = false;
+        return;
+      }
+      let dir = st.rate >= 0 ? 1 : -1;
+      st.f += speed;
+      while (st.f >= dur) {
+        st.f -= dur;
+        st.seg += dir;
+        if (st.seg >= nSeg || st.seg < 0) {
+          if (st.pingPong) {
+            // Bounce at endpoints and flip direction.
+            if (dir > 0) {
+              st.seg = nSeg - 1;
+              st.f = 0;
+              st.rate = -speed;
+            } else {
+              st.seg = 0;
+              st.f = 0;
+              st.rate = speed;
+            }
+            dir = st.rate >= 0 ? 1 : -1;
+          } else if (st.loop) {
+            st.seg = dir > 0 ? 0 : (nSeg - 1);
+          } else {
+            st.playing = false;
+            seekGlobal(cam, dir > 0 ? 1 : 0);
+            const cb = st.onEnd;
+            if (typeof cb === 'function') {
+              try { cb(cam); } catch (e) { /* ignore user callback errors */ }
+            }
+            return;
+          }
+        }
+      }
+      const local = st.f / dur;
+      const amt = dir > 0 ? local : (1 - local);
+      cam.slerp(path[st.seg], path[st.seg + 1], amt);
+    };
+
+    // -----------------------
+    // v2 addon lifecycle hook
+    // -----------------------
+
+    lifecycles.predraw = function () {
+      const players = getPlayers(this);
+      players.forEach(cam => {
+        tick(cam);
+        getState(cam).playing || players.delete(cam);
+      });
+    };
+
+    lifecycles.remove = function () {
+      const players = this[PLAYERS_KEY];
+      players && players.clear();
+    };
+
+    // ----------
+    // Camera API
+    // ----------
+
+    /**
+     * addPath overloads (opts, if present, must be last; opts is the only allowed plain object):
+     *
+     *   camera.addPath();                                // snapshot this camera
+     *   camera.addPath(opts);                            // snapshot this camera (with opts)
+     *
+     *   camera.addPath(otherCam, opts);                  // snapshot otherCam
+     *   camera.addPath([camA, camB, ...], opts);         // bulk add (cameras)
+     *
+     *   camera.addPath(eye, center, up, opts);           // eye/center/up: p5.Vector or [x, y, z]
+     *
+     *   camera.addPath(view, opts);                      // view: p5.Matrix (4x4) or mat4[16]
+     *                                                    // (world -> camera), like p5.Camera.cameraMatrix
+     *   camera.addPath([viewA, viewB, ...], opts);       // bulk add (views)
+     *
+     * Options:
+     *   - reset: boolean (default false) Clears the current path before adding.
+     *
+     * Notes:
+     * - Keyframes are stored as camera snapshots (p5.Camera.copy()) so Camera.slerp() works.
+     * - Projection compatibility is enforced (Camera.slerp requires same projection).
+     *
+     * @param  {...any} args
+     * @returns {p5.Camera} this
+     */
+    p5.Camera.prototype.addPath = function (...args) {
+      const st = getState(this);
+      const path = ensurePath(this);
+      const isPlainObject = v => {
+        if (!v || typeof v !== 'object') return false;
+        if (Array.isArray(v)) return false;
+        if (ArrayBuffer.isView(v)) return false;
+        return Object.getPrototypeOf(v) === Object.prototype;
+      };
+      const isVec3 = v =>
+        v instanceof p5.Vector ||
+        (Array.isArray(v) && v.length === 3 && v.every(n => typeof n === 'number' && Number.isFinite(n)));
+      const toVec3 = v => v instanceof p5.Vector ? [v.x, v.y, v.z] : [v[0], v[1], v[2]];
+      const sameKeyframe = function (a, b) {
+        if (!a || !b) return false;
+        const aCM = a.cameraMatrix && a.cameraMatrix.mat4;
+        const bCM = b.cameraMatrix && b.cameraMatrix.mat4;
+        if (!aCM || !bCM) return false;
+        for (let i = 0; i < 16; i++) if (aCM[i] !== bCM[i]) return false;
+        return true;
+      };
+      const addSnapshot = c => {
+        const last = path.length ? path[path.length - 1] : undefined;
+        last && sameKeyframe(last, c) || path.push(c.copy());
+      };
+      const isOrthoCam = c => {
+        const m = c && c.projMatrix && c.projMatrix.mat4;
+        return m && m.length === 16 ? (m[15] !== 0) : undefined;
+      };
+      const initProjBaseline = c => {
+        if (st.pathIsOrtho !== undefined) return;
+        const v = isOrthoCam(c);
+        st.pathIsOrtho = v;
+        v === undefined && warn('addPath: unable to verify projection type (projMatrix.mat4 unavailable).');
+      };
+      const checkProjCompat = c => {
+        initProjBaseline(c);
+        const v = isOrthoCam(c);
+        if (st.pathIsOrtho === undefined || v === undefined) {
+          v === undefined && warn('addPath: unable to verify projection type (projMatrix.mat4 unavailable).');
+          return true;
+        }
+        if (v !== st.pathIsOrtho) {
+          warn('addPath rejected: keyframe has different projection type (ortho vs perspective).');
+          return false;
+        }
+        return true;
+      };
+      const isMat4Array = v =>
+        (Array.isArray(v) || ArrayBuffer.isView(v)) &&
+        v.length === 16 &&
+        Array.prototype.every.call(v, n => typeof n === 'number' && Number.isFinite(n));
+      const isView = v => v instanceof p5.Matrix || isMat4Array(v);
+      const toMat4 = v => v instanceof p5.Matrix ? v.mat4 : v;
+      const dot3 = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+      const len3 = v => Math.sqrt(dot3(v, v));
+      const norm3 = v => {
+        const l = len3(v) || 1;
+        return [v[0] / l, v[1] / l, v[2] / l];
+      };
+      const importViewToCamera = view => {
+        // view is a column-major mat4, world -> camera (p5.Camera.cameraMatrix).
+        const m = toMat4(view);
+        // Rows of rotation part (world->camera):
+        const right = norm3([m[0], m[4], m[8]]);
+        const up = norm3([m[1], m[5], m[9]]);
+        const negFwd = norm3([m[2], m[6], m[10]]);
+        const fwd = [-negFwd[0], -negFwd[1], -negFwd[2]];
+        // Translation column: t = -R^T * eye
+        const t = [m[12], m[13], m[14]];
+        // eye = -(t0*right + t1*up) + t2*forward
+        const eye = [
+          -(t[0] * right[0] + t[1] * up[0]) + t[2] * fwd[0],
+          -(t[0] * right[1] + t[1] * up[1]) + t[2] * fwd[1],
+          -(t[0] * right[2] + t[1] * up[2]) + t[2] * fwd[2]
+        ];
+        // Enforce center using this camera’s current focus distance.
+        const dist = Math.sqrt(
+          (this.centerX - this.eyeX) * (this.centerX - this.eyeX) +
+          (this.centerY - this.eyeY) * (this.centerY - this.eyeY) +
+          (this.centerZ - this.eyeZ) * (this.centerZ - this.eyeZ)
+        ) || 1;
+        const center = [
+          eye[0] + fwd[0] * dist,
+          eye[1] + fwd[1] * dist,
+          eye[2] + fwd[2] * dist
+        ];
+        // Important: use camera(...) so cameraMatrix stays consistent with eye/center/up.
+        const c = this.copy();
+        c.camera(
+          eye[0], eye[1], eye[2],
+          center[0], center[1], center[2],
+          up[0], up[1], up[2]
+        );
+        return c;
+      };
+      // --- opts extraction (opts always last; only plain object is opts) ---
+      const o = args.length && isPlainObject(args[args.length - 1]) ? args.pop() : {};
+      if (o.reset) {
+        path.length = 0;
+        st.seg = 0;
+        st.f = 0;
+        st.pathIsOrtho = undefined;
+      }
+      initProjBaseline(this);
+      // addPath() -> snapshot this
+      if (args.length === 0) {
+        addSnapshot(this);
+        return this;
+      }
+      // addPath(view) OR addPath(camera) OR addPath([cameras]) OR addPath([views])
+      if (args.length === 1) {
+        const override = args[0];
+        // single view
+        if (isView(override)) {
+          const c = importViewToCamera(override);
+          checkProjCompat(c) && addSnapshot(c);
+          return this;
+        }
+        // bulk: views or cameras
+        if (Array.isArray(override)) {
+          const list = override;
+          // bulk views
+          if (list.length && list.every(isView)) {
+            for (let i = 0; i < list.length; i++) {
+              const c = importViewToCamera(list[i]);
+              checkProjCompat(c) && addSnapshot(c);
+            }
+            return this;
+          }
+          // bulk cameras (existing behavior)
+          for (let i = 0; i < list.length; i++) {
+            const c = list[i];
+            if (!(c instanceof p5.Camera)) {
+              warn('addPath: ignored non-camera value.');
+              continue;
+            }
+            checkProjCompat(c) && addSnapshot(c);
+          }
+          return this;
+        }
+        // single camera
+        if (override instanceof p5.Camera) {
+          checkProjCompat(override) && addSnapshot(override);
+          return this;
+        }
+        warn('addPath: ignored unsupported arguments.');
+        return this;
+      }
+      // addPath(eye, center, up, opts)
+      if (args.length === 3 && args.every(isVec3)) {
+        const eye = toVec3(args[0]);
+        const center = toVec3(args[1]);
+        const up = norm3(toVec3(args[2]));
+        // Important: use camera(...) so cameraMatrix stays consistent with eye/center/up.
+        const c = this.copy();
+        c.camera(
+          eye[0], eye[1], eye[2],
+          center[0], center[1], center[2],
+          up[0], up[1], up[2]
+        );
+        checkProjCompat(c) && addSnapshot(c);
+        return this;
+      }
+      warn('addPath: ignored unsupported arguments.');
+      return this;
+    };
+
+    /**
+     * playPath overloads:
+     *   camera.playPath(rate)
+     *   camera.playPath({ duration, loop, pingPong, onEnd, rate })
+     *
+     * Playback runs in "frames per segment" (duration), and rate is interpreted as a
+     * simple speed multiplier:
+     * - rate > 0 : forward
+     * - rate < 0 : reverse
+     * - rate === 0 : stopped (does not register for ticking)
+     *
+     * duration: frames per segment (default 30).
+     * loop: wraps at ends (default false).
+     * pingPong: bounces at ends (default false).
+     * onEnd: called when playback naturally ends (non-looping, non-pingpong).
+     *
+     * Special case (single keyframe):
+     * If camera.path has exactly 1 keyframe, playPath does not start playback.
+     * It restores this camera pose to that keyframe (via p5.Camera.camera())
+     * and ensures playback is stopped/unregistered.
+     *
+     * If both pingPong and loop are true, pingPong takes precedence.
+     */
+    p5.Camera.prototype.playPath = function (rateOrOpts) {
+      const st = getState(this);
+      const path = ensurePath(this);
+      const pInst = this._renderer && this._renderer._pInst;
+      const unregister = () => pInst && getPlayers(pInst).delete(this);
+      const register = () => pInst && getPlayers(pInst).add(this);
+      // 0 keyframes: nothing to do
+      if (path.length === 0) {
+        warn('playPath ignored: need at least 1 keyframe in camera.path.');
+        st.playing = false;
+        unregister();
+        return this;
+      }
+      // 1 keyframe: restore pose only (no playback)
+      if (path.length === 1) {
+        const kf = path[0];
+        st.playing = false;
+        unregister();
+        return this.camera(
+          kf.eyeX, kf.eyeY, kf.eyeZ,
+          kf.centerX, kf.centerY, kf.centerZ,
+          kf.upX, kf.upY, kf.upZ
+        );
+      }
+      const nSeg = segmentCount(path);
+      if (nSeg === 0) {
+        warn('playPath ignored: need at least 2 keyframes in camera.path.');
+        st.playing = false;
+        unregister();
+        return this;
+      }
+      if (isFiniteNumber(rateOrOpts)) {
+        st.rate = rateOrOpts;
+      } else {
+        const o = rateOrOpts || {};
+        st.duration = isFiniteNumber(o.duration) ? o.duration : st.duration;
+        st.loop = !!o.loop;
+        st.pingPong = !!o.pingPong;
+        st.onEnd = typeof o.onEnd === 'function' ? o.onEnd : st.onEnd;
+        st.rate = isFiniteNumber(o.rate) ? o.rate : st.rate;
+      }
+      // rate === 0 means "stop" (don’t register for ticking)
+      if (st.rate === 0) {
+        st.playing = false;
+        unregister();
+        return this;
+      }
+      // If starting from stopped state, default to an endpoint depending on direction.
+      // Important: do NOT use seekGlobal(cam, 1) for reverse start, because seekGlobal sets st.f = dur
+      // and the next tick will immediately underflow the segment and stop (snap).
+      if (!st.playing) {
+        const forward = st.rate >= 0;
+        st.seg = forward ? 0 : (nSeg - 1);
+        st.f = 0;
+        // Snap pose to the start/end of the current segment, but keep st.f = 0.
+        this.slerp(path[st.seg], path[st.seg + 1], forward ? 0 : 1);
+      }  
+      st.playing = true;
+      register();
+      return this;
+    };
+
+    /**
+     * stopPath({ reset=false })
+     * - Stops playback.
+     * - If reset:true, seeks to start (forward) or end (reverse).
+     */
+    p5.Camera.prototype.stopPath = function (opts) {
+      const st = getState(this);
+      const o = opts || {};
+      st.playing = false;
+      const pInst = this._renderer && this._renderer._pInst;
+      pInst && getPlayers(pInst).delete(this);
+      if (o.reset) {
+        const forward = st.rate >= 0;
+        seekGlobal(this, forward ? 0 : 1);
+        st.seg = forward ? 0 : Math.max(0, segmentCount(ensurePath(this)) - 1);
+        st.f = 0;
+      }
+      return this;
+    };
+
+    /**
+     * resetPath(n?)
+     * - resetPath() clears all keyframes and stops.
+     * - resetPath(n) keeps first n keyframes (truncate) and stops.
+     */
+    p5.Camera.prototype.resetPath = function (n) {
+      const st = getState(this);
+      const path = ensurePath(this);
+      st.playing = false;
+      st.seg = 0;
+      st.f = 0;
+      const pInst = this._renderer && this._renderer._pInst;
+      pInst && getPlayers(pInst).delete(this);
+      if (!isFiniteNumber(n)) {
+        path.length = 0;
+        st.pathIsOrtho = undefined;
+        return this;
+      }
+      const nInt = n | 0;
+      const keep = Math.max(0, Math.abs(nInt));
+      if (keep === 0) {
+        path.length = 0;
+        st.pathIsOrtho = undefined;
+        return this;
+      }
+      if (nInt >= 0) {
+        path.length = Math.min(path.length, keep);
+      } else if (path.length > keep) {
+        path.splice(0, path.length - keep);
+      }
+      if (segmentCount(path) === 0) {
+        st.pathIsOrtho = undefined;
+      }
+      return this;
+    };
+
+    /**
+     * seekPath overloads:
+     *   camera.seekPath(t)              // global t in [0..1]
+     *   camera.seekPath(amt, segIndex)  // segment-local
+     *
+     * Seeking always stops playback.
+     */
+    p5.Camera.prototype.seekPath = function (t, segIndex) {
+      const st = getState(this);
+      st.playing = false;
+      const pInst = this._renderer && this._renderer._pInst;
+      pInst && getPlayers(pInst).delete(this);
+      if (isFiniteNumber(segIndex)) {
+        seekSegment(this, t, segIndex);
+        return this;
+      }
+      seekGlobal(this, t);
+      return this;
+    };
+
+    // ------------------------------------------------------------
+    // p5 wrappers (same names, forward to active camera)
+    // ------------------------------------------------------------
+
+    fn.addPath = function (...args) {
+      const cam = getActiveCamera(this);
+      cam && cam.addPath(...args);
+      return this;
+    };
+
+    fn.playPath = function (...args) {
+      const cam = getActiveCamera(this);
+      cam && cam.playPath(...args);
+      return this;
+    };
+    
+    fn.seekPath = function (...args) {
+      const cam = getActiveCamera(this);
+      cam && cam.seekPath(...args);
+      return this;
+    };
+    
+    fn.resetPath = function (...args) {
+      const cam = getActiveCamera(this);
+      cam && cam.resetPath(...args);
+      return this;
+    };
+    
+    fn.stopPath = function (...args) {
+      const cam = getActiveCamera(this);
+      cam && cam.stopPath(...args);
+      return this;
+    };
+    
+    // HUD
+
+    fn.beginHUD = function (...args) {
+      this._renderer?.beginHUD?.(...args);
+      return this;
+    };
+    
+    fn.endHUD = function (...args) {
+      this._renderer?.endHUD?.(...args);
+      return this;
+    };
+    
+    /*
+    // treegl approach:
+    p5.RendererGL.prototype.beginHUD = function () {
+      if (this._hudActive === true) return;
+      const p = this._pInst;
+      const gl = this.drawingContext;
+      const states = this.states;
+      if (!p || !gl || !states) return;
+      // ------------------------------------------------------------------
+      // Save world state (treegl: m, v, p)
+      // ------------------------------------------------------------------
+      this._hudPrevCamera = states.curCamera;
+      // push isolates renderer state (tree-style equivalent of treegl push)
+      p.push();
+      p.resetShader();
+      // Ensure HUD does not inherit model transforms
+      p.resetMatrix();
+      // ------------------------------------------------------------------
+      // Depth state
+      // ------------------------------------------------------------------
+      this._hudDepthWasEnabled = gl.isEnabled(gl.DEPTH_TEST);
+      gl.flush();
+      gl.disable(gl.DEPTH_TEST);
+      // ------------------------------------------------------------------
+      // HUD camera
+      // ------------------------------------------------------------------
+      if (this._hudCam === undefined) {
+        this._hudCam = p.createCamera();
+      }
+      const z = Number.MAX_VALUE;
+      // HUD coordinates:
+      // x ∈ [0, width], y ∈ [0, height], origin at top-left
+      this._hudCam.ortho(0, p.width, -p.height, 0, -z, z);
+      // this._hudCam.ortho(0, p.width, 0, -p.height, -z, z); // flipped variant
+      this._hudCam.camera(0, 0, 1, 0, 0, 0, 0, 1, 0);
+      p.setCamera(this._hudCam);
+      this._hudActive = true;
+    };
+    
+    p5.RendererGL.prototype.endHUD = function () {
+      if (this._hudActive !== true) return;
+      const p = this._pInst;
+      const gl = this.drawingContext;
+      const states = this.states;
+      if (!p || !gl || !states) return;
+      gl.flush();
+      // Restore depth test
+      this._hudDepthWasEnabled ? gl.enable(gl.DEPTH_TEST) : gl.disable(gl.DEPTH_TEST);
+      // Restore renderer state
+      p.pop();
+      // Restore camera (tree equivalent of restoring u* matrices)
+      if (this._hudPrevCamera !== undefined) {
+        p.setCamera(this._hudPrevCamera);
+      }
+      this._hudPrevCamera = undefined;
+      this._hudDepthWasEnabled = undefined;
+      this._hudActive = false;
+    };
+    */
+    
+    p5.RendererGL.prototype.beginHUD = function () {
+      if (this._hudActive === true) return;
+      const p = this._pInst;
+      if (!p) return;
+      const gl = this.drawingContext;
+      const states = this.states;
+      if (!gl || !states) return;
+      p.push(); // isolate all subsequent HUD drawing from caller state
+      p.resetShader();
+      // Ensure HUD space does NOT inherit the user's current model transforms
+      // (e.g. push()/translate()
+      p.resetMatrix();
+      // ---------------------
+      // --- HUD setup ---
+      this._hudPrevCam = states.curCamera;
+      this._hudDepthWasEnabled = gl.isEnabled(gl.DEPTH_TEST);
+      gl.flush();
+      gl.disable(gl.DEPTH_TEST);
+      if (this._hudCam === undefined) this._hudCam = p.createCamera();
+      const z = 1e6;
+      // HUD coordinates: x in [0, width], y in [0, height]
+      this._hudCam.ortho(0, p.width, -p.height, 0, -z, z);
+      // this._hudCam.ortho(0, p.width, 0, -p.height, -z, z); // <- flipped
+      this._hudCam.camera(0, 0, 1, 0, 0, 0, 0, 1, 0);
+      p.setCamera(this._hudCam);
+      this._hudActive = true;
+    };
+    
+    p5.RendererGL.prototype.endHUD = function () {
+      if (this._hudActive !== true) return;
+      const p = this._pInst;
+      const gl = this.drawingContext;
+      const states = this.states;
+      if (p === undefined || gl === undefined || states === undefined) return;
+      gl.flush();
+      this._hudDepthWasEnabled ? gl.enable(gl.DEPTH_TEST) : gl.disable(gl.DEPTH_TEST);
+      p.pop(); // calls: this.pop(this._rendererState);
+      this._hudPrevCam !== undefined && p.setCamera(this._hudPrevCam);
+      this._hudPrevCam = undefined;
+      this._hudDepthWasEnabled = undefined;
+      this._hudActive = false;
+    };
+    
+    // ---------------------------------------------------------------------------
+    // Space transforms: transformPosition / transformDirection
+    // ---------------------------------------------------------------------------
+    
+    p5.RendererGL.prototype._parseTransformArgs = function (defaultMainArg, ...args) {
+      let mainArg = defaultMainArg;
+      const options = {};
+      for (const arg of args) {
+        if (arg instanceof p5.Vector || Array.isArray(arg)) {
+          mainArg = arg;
+        } else if (arg && typeof arg === 'object') {
+          Object.assign(options, arg);
+        }
+      }
+      return { mainArg, options };
+    };
+
+    // ---------------------------------------------------------------------------
+    // Points (positions)
+    // ---------------------------------------------------------------------------
+    
+    fn.transformPosition = function (...args) {
+      return _rendererGL(this)?.transformPosition(...args);
+    };
+    
+    /**
+     * Converts a point (location) from one space into another.
+     *
+     * @param {p5.Vector|number[]} [point=p5.Tree.ORIGIN]
+     * @param {Object} [opts]
+     * @param {p5.Matrix|string} [opts.from=p5.Tree.EYE]
+     * @param {p5.Matrix|string} [opts.to=p5.Tree.WORLD]
+     * @param {p5.Matrix} [opts.pMatrix]
+     * @param {p5.Matrix} [opts.vMatrix]
+     * @param {p5.Matrix} [opts.eMatrix]
+     * @param {p5.Matrix} [opts.pvMatrix]
+     * @param {p5.Matrix} [opts.ipvMatrix]
+     * @returns {p5.Vector}
+     */
+    p5.RendererGL.prototype.transformPosition = function (...args) {
+      const { mainArg, options } = this._parseTransformArgs(p5.Tree.ORIGIN, ...args);
+      return this._position(mainArg, options);
+    };
+    
+    p5.RendererGL.prototype._position = function (
+      point = p5.Tree.ORIGIN,
+      {
+        from = p5.Tree.EYE,
+        to = p5.Tree.WORLD,
+        pMatrix,
+        vMatrix,
+        eMatrix,
+        pvMatrix,
+        ipvMatrix
+      } = {}
+    ) {
+      if (Array.isArray(point)) {
+        point = new p5.Vector(point[0] ?? 0, point[1] ?? 0, point[2] ?? 0);
+      }
+      if (from == p5.Tree.MODEL) {
+        from = this.mMatrix({ eMatrix });
+      }
+      if (to == p5.Tree.MODEL) {
+        to = this.mMatrix({ eMatrix });
+      }
+      if ((from == p5.Tree.WORLD) && (to == p5.Tree.SCREEN)) {
+        return this._worldToScreenPosition({ point, pMatrix, vMatrix, pvMatrix });
+      }
+      if ((from == p5.Tree.SCREEN) && (to == p5.Tree.WORLD)) {
+        return this._screenToWorldPosition({ point, pMatrix, vMatrix, pvMatrix, ipvMatrix });
+      }
+      if (from == p5.Tree.SCREEN && to == p5.Tree.NDC) {
+        return this._screenToNDCPosition(point);
+      }
+      if (from == p5.Tree.NDC && to == p5.Tree.SCREEN) {
+        return this._ndcToScreenPosition(point);
+      }
+      if (from == p5.Tree.WORLD && to == p5.Tree.NDC) {
+        return this._screenToNDCPosition(
+          this._worldToScreenPosition({ point, pMatrix, vMatrix, pvMatrix })
+        );
+      }
+      if (from == p5.Tree.NDC && to == p5.Tree.WORLD) {
+        return this._screenToWorldPosition({
+          point: this._ndcToScreenPosition(point),
+          pMatrix,
+          vMatrix,
+          pvMatrix,
+          ipvMatrix
+        });
+      }
+      if (from == p5.Tree.NDC && (to instanceof p5.Matrix || to == p5.Tree.EYE)) {
+        return (to == p5.Tree.EYE
+          ? (vMatrix ?? this.vMatrix())
+          : to.copy().invert(to)
+        ).mult4(
+          this._screenToWorldPosition({
+            point: this._ndcToScreenPosition(point),
+            pMatrix,
+            vMatrix,
+            pvMatrix,
+            ipvMatrix
+          })
+        );
+      }
+      if ((from instanceof p5.Matrix || from == p5.Tree.EYE) && to == p5.Tree.NDC) {
+        return this._screenToNDCPosition(
+          this._worldToScreenPosition({
+            point: (from == p5.Tree.EYE
+              ? (eMatrix ?? this.eMatrix())
+              : from
+            ).mult4(point),
+            pMatrix,
+            vMatrix,
+            pvMatrix
+          })
+        );
+      }
+      if (from == p5.Tree.WORLD && (to instanceof p5.Matrix || to == p5.Tree.EYE)) {
+        return (to == p5.Tree.EYE
+          ? (vMatrix ?? this.vMatrix())
+          : to.copy().invert(to)
+        ).mult4(point);
+      }
+      if ((from instanceof p5.Matrix || from == p5.Tree.EYE) && to == p5.Tree.WORLD) {
+        return (from == p5.Tree.EYE
+          ? (eMatrix ?? this.eMatrix())
+          : from
+        ).mult4(point);
+      }
+      if (from instanceof p5.Matrix && to instanceof p5.Matrix) {
+        return this.lMatrix({ from: from, to: to }).mult4(point);
+      }
+      if (from == p5.Tree.SCREEN && (to instanceof p5.Matrix || to == p5.Tree.EYE)) {
+        return (to == p5.Tree.EYE
+          ? (vMatrix ?? this.vMatrix())
+          : to.copy().invert(to)
+        ).mult4(
+          this._screenToWorldPosition({ point, pMatrix, vMatrix, pvMatrix, ipvMatrix })
+        );
+      }
+      if ((from instanceof p5.Matrix || from == p5.Tree.EYE) && to == p5.Tree.SCREEN) {
+        return this._worldToScreenPosition({
+          point: (from == p5.Tree.EYE
+            ? (eMatrix ?? this.eMatrix())
+            : from
+          ).mult4(point),
+          pMatrix,
+          vMatrix,
+          pvMatrix
+        });
+      }
+      if (from instanceof p5.Matrix && to == p5.Tree.EYE) {
+        return (vMatrix ?? this.vMatrix()).mult4(from.mult4(point));
+      }
+      if (from == p5.Tree.EYE && to instanceof p5.Matrix) {
+        return to.copy().invert(to).mult4((eMatrix ?? this.eMatrix()).mult4(point));
+      }
+      console.error('couldn\'t parse your transformPosition query!');
+      return point;
+    };
+    
+    p5.RendererGL.prototype._ndcToScreenPosition = function (point) {
+      return new p5.Vector(
+        p5.prototype.map(point.x, -1, 1, 0, this.width),
+        p5.prototype.map(point.y, -1, 1, 0, this.height),
+        p5.prototype.map(point.z, -1, 1, 0, 1)
+      );
+    };
+    
+    p5.RendererGL.prototype._screenToNDCPosition = function (point) {
+      return new p5.Vector(
+        p5.prototype.map(point.x, 0, this.width, -1, 1),
+        p5.prototype.map(point.y, 0, this.height, -1, 1),
+        p5.prototype.map(point.z, 0, 1, -1, 1)
+      );
+    };
+    
+    p5.RendererGL.prototype._worldToScreenPosition = function ({
+      point = new p5.Vector(0, 0, 0.5),
+      pMatrix,
+      vMatrix,
+      pvMatrix = this.pvMatrix({ pMatrix, vMatrix })
+    } = {}) {
+      let target = pvMatrix._mult4([point.x, point.y, point.z, 1]);
+      if (target[3] === 0) {
+        console.error('[p5.tree] World->Screen broken: check pvMatrix.');
+        return point.copy();
+      }
+      const viewport = [0, this.height, this.width, -this.height];
+      target[0] /= target[3];
+      target[1] /= target[3];
+      target[2] /= target[3];
+      target[0] = target[0] * 0.5 + 0.5;
+      target[1] = target[1] * 0.5 + 0.5;
+      target[2] = target[2] * 0.5 + 0.5;
+      target[0] = target[0] * viewport[2] + viewport[0];
+      target[1] = target[1] * viewport[3] + viewport[1];
+      return new p5.Vector(target[0], target[1], target[2]);
+    };
+    
+    p5.RendererGL.prototype._screenToWorldPosition = function ({
+      point = new p5.Vector(this.width / 2, this.height / 2, 0.5),
+      pMatrix,
+      vMatrix,
+      pvMatrix,
+      ipvMatrix = this.ipvMatrix({ pMatrix, vMatrix, pvMatrix })
+    } = {}) {
+      const viewport = [0, this.height, this.width, -this.height];
+      const source = [point.x, point.y, point.z, 1];
+      source[0] = (source[0] - viewport[0]) / viewport[2];
+      source[1] = (source[1] - viewport[1]) / viewport[3];
+      source[0] = source[0] * 2 - 1;
+      source[1] = source[1] * 2 - 1;
+      source[2] = source[2] * 2 - 1;
+      let target = ipvMatrix._mult4(source);
+      if (target[3] === 0) {
+        console.error('[p5.tree] Screen->World broken: check ipvMatrix.');
+        return point.copy();
+      }
+      target[0] /= target[3];
+      target[1] /= target[3];
+      target[2] /= target[3];
+      return new p5.Vector(target[0], target[1], target[2]);
+    };
+    
+    // ---------------------------------------------------------------------------
+    // Directions (vector displacements)
+    // ---------------------------------------------------------------------------
+    
+    fn.transformDirection = function (...args) {
+      return _rendererGL(this)?.transformDirection(...args);
+    };
+    
+    /**
+     * Converts a vector displacement from one space into another.
+     *
+     * @param {p5.Vector|number[]} [vector=p5.Tree._k]
+     * @param {Object} [opts]
+     * @param {p5.Matrix|string} [opts.from=p5.Tree.EYE]
+     * @param {p5.Matrix|string} [opts.to=p5.Tree.WORLD]
+     * @param {p5.Matrix} [opts.vMatrix]
+     * @param {p5.Matrix} [opts.eMatrix]
+     * @param {p5.Matrix} [opts.pMatrix]
+     * @returns {p5.Vector}
+     */
+    p5.RendererGL.prototype.transformDirection = function (...args) {
+      const { mainArg, options } = this._parseTransformArgs(p5.Tree._k, ...args);
+      return this._direction(mainArg, options);
+    };
+    
+    p5.RendererGL.prototype._direction = function (
+      vector = p5.Tree._k,
+      {
+        from = p5.Tree.EYE,
+        to = p5.Tree.WORLD,
+        vMatrix,
+        eMatrix,
+        pMatrix
+      } = {}
+    ) {
+      if (Array.isArray(vector)) {
+        vector = new p5.Vector(vector[0] ?? 0, vector[1] ?? 0, vector[2] ?? 0);
+      }
+      if (from === p5.Tree.MODEL) from = this.mMatrix({ eMatrix });
+      if (to === p5.Tree.MODEL) to = this.mMatrix({ eMatrix });
+      if (from === p5.Tree.WORLD && to === p5.Tree.SCREEN) return this._worldToScreenDirection(vector, pMatrix);
+      if (from === p5.Tree.SCREEN && to === p5.Tree.WORLD) return this._screenToWorldDirection(vector, pMatrix);
+      if (from === p5.Tree.SCREEN && to === p5.Tree.NDC) return this._screenToNDCDirection(vector);
+      if (from === p5.Tree.NDC && to === p5.Tree.SCREEN) return this._ndcToScreenDirection(vector);
+      if (from === p5.Tree.WORLD && to === p5.Tree.NDC) {
+        return this._screenToNDCDirection(this._worldToScreenDirection(vector, pMatrix));
+      }
+      if (from === p5.Tree.NDC && to === p5.Tree.WORLD) {
+        return this._screenToWorldDirection(this._ndcToScreenDirection(vector), pMatrix);
+      }
+      if (from === p5.Tree.NDC && to === p5.Tree.EYE) {
+        const m = this.dMatrix({ matrix: eMatrix ?? this.eMatrix() }); // mat3
+        return m.multiplyVec3(
+          this._screenToWorldDirection(this._ndcToScreenDirection(vector), pMatrix)
+        );
+      }
+      if (from === p5.Tree.EYE && to === p5.Tree.NDC) {
+        const m = this.dMatrix({ matrix: vMatrix ?? this.vMatrix() }); // mat3
+        return this._screenToNDCDirection(
+          this._worldToScreenDirection(m.multiplyVec3(vector), pMatrix)
+        );
+      }
+      if (from === p5.Tree.SCREEN && to instanceof p5.Matrix) {
+        const m = this.dMatrix({ matrix: to }); // mat3
+        return m.multiplyVec3(this._screenToWorldDirection(vector, pMatrix));
+      }
+      if (from instanceof p5.Matrix && to === p5.Tree.SCREEN) {
+        const m = this.dMatrix({ matrix: _invert(from) }); // mat3
+        return this._worldToScreenDirection(m.multiplyVec3(vector), pMatrix);
+      }
+      if (from instanceof p5.Matrix && to instanceof p5.Matrix) {
+        return this.dMatrix({ from, to }).multiplyVec3(vector); // mat3
+      }
+      if (from === p5.Tree.EYE && to === p5.Tree.WORLD) {
+        return this.dMatrix({ matrix: vMatrix ?? this.vMatrix() }).multiplyVec3(vector); // mat3
+      }
+      if (from === p5.Tree.WORLD && to === p5.Tree.EYE) {
+        return this.dMatrix({ matrix: eMatrix ?? this.eMatrix() }).multiplyVec3(vector); // mat3
+      }
+      if (from === p5.Tree.EYE && to === p5.Tree.SCREEN) {
+        return this._worldToScreenDirection(
+          this.dMatrix({ matrix: vMatrix ?? this.vMatrix() }).multiplyVec3(vector),
+          pMatrix
+        );
+      }
+      if (from === p5.Tree.SCREEN && to === p5.Tree.EYE) {
+        return this.dMatrix({ matrix: eMatrix ?? this.eMatrix() }).multiplyVec3(
+          this._screenToWorldDirection(vector, pMatrix)
+        );
+      }
+      if (from === p5.Tree.EYE && to instanceof p5.Matrix) {
+        const m = this.dMatrix({ matrix: (vMatrix ?? this.vMatrix()).apply(to) }); // mat3
+        return m.multiplyVec3(vector);
+      }
+      if (from instanceof p5.Matrix && to === p5.Tree.EYE) {
+        const m = this.dMatrix({ matrix: _invert(from).apply(eMatrix ?? this.eMatrix()) }); // mat3
+        return m.multiplyVec3(vector);
+      }
+      if (from === p5.Tree.WORLD && to instanceof p5.Matrix) {
+        return this.dMatrix({ matrix: to }).multiplyVec3(vector); // mat3
+      }
+      if (from instanceof p5.Matrix && to === p5.Tree.WORLD) {
+        return this.dMatrix({ matrix: _invert(from) }).multiplyVec3(vector); // mat3
+      }
+    
+      if (from instanceof p5.Matrix && to === p5.Tree.NDC) {
+        const m = this.dMatrix({ matrix: _invert(from) }); // mat3
+        return this._screenToNDCDirection(this._worldToScreenDirection(m.multiplyVec3(vector), pMatrix));
+      }
+      if (from === p5.Tree.NDC && to instanceof p5.Matrix) {
+        const m = this.dMatrix({ matrix: to }); // mat3
+        return m.multiplyVec3(
+          this._screenToWorldDirection(this._ndcToScreenDirection(vector), pMatrix)
+        );
+      }
+      console.error('[p5.tree] transformDirection: could not parse query.');
+      return vector;
+    };
+    
+    p5.RendererGL.prototype._worldToScreenDirection = function (vector, pMatrix) {
+      pMatrix = pMatrix ?? this.pMatrix();
+      const eyeVector = this._direction(vector, { from: p5.Tree.WORLD, to: p5.Tree.EYE });
+      let dx = eyeVector.x;
+      let dy = eyeVector.y;
+      const perspective = pMatrix.mat4[15] === 0;
+      if (perspective) {
+        const zEye = this._position(p5.Tree.ORIGIN, { from: p5.Tree.WORLD, to: p5.Tree.EYE }).z;
+        const k = Math.abs(zEye * Math.tan(pMatrix.fov() / 2));
+        dx /= 2 * k / this.height;
+        dy /= 2 * k / this.height;
+      }
+      let dz = eyeVector.z;
+      dz /= (pMatrix.nPlane() - pMatrix.fPlane()) / (
+        perspective
+          ? Math.tan(pMatrix.fov() / 2)
+          : Math.abs(pMatrix.rPlane() - pMatrix.lPlane()) / this.width
+      );
+      return new p5.Vector(dx, dy, dz);
+    };
+    
+    p5.RendererGL.prototype._screenToWorldDirection = function (vector, pMatrix) {
+      pMatrix = pMatrix ?? this.pMatrix();
+    
+      let dx = vector.x;
+      let dy = vector.y;
+    
+      const perspective = pMatrix.mat4[15] === 0;
+      if (perspective) {
+        const zEye = this._position(p5.Tree.ORIGIN, { from: p5.Tree.WORLD, to: p5.Tree.EYE }).z;
+        const k = Math.abs(zEye * Math.tan(pMatrix.fov() / 2));
+        dx *= 2 * k / this.height;
+        dy *= 2 * k / this.height;
+      }
+    
+      let dz = vector.z;
+      dz *= (pMatrix.nPlane() - pMatrix.fPlane()) / (
+        perspective
+          ? Math.tan(pMatrix.fov() / 2)
+          : Math.abs(pMatrix.rPlane() - pMatrix.lPlane()) / this.width
+      );
+    
+      return this._direction(new p5.Vector(dx, dy, dz), { from: p5.Tree.EYE, to: p5.Tree.WORLD });
+    };
+    
+    p5.RendererGL.prototype._ndcToScreenDirection = function (vector) {
+      return new p5.Vector(this.width * vector.x / 2, this.height * vector.y / 2, vector.z / 2);
+    };
+    
+    p5.RendererGL.prototype._screenToNDCDirection = function (vector) {
+      return new p5.Vector(2 * vector.x / this.width, 2 * vector.y / this.height, 2 * vector.z);
+    };
+    
+    // ---------------------------------------------------------------------------
+    // Utilities
+    // ---------------------------------------------------------------------------
+    
+    /**
+     * Returns the world-to-pixel ratio units at a given world point position.
+     *
+     * A line of `n * pixelRatio(point)` world units will be projected with a
+     * length of `n` pixels on screen (locally around that point).
+     *
+     * - In orthographic projection, the ratio is constant.
+     * - In perspective projection, the ratio depends on eye-space depth.
+     *
+     * Requires WEBGL.
+     *
+     * @param {p5.Vector|number[]} [point=p5.Tree.ORIGIN] World-space point.
+     * @returns {number|undefined} World units per pixel at the given point.
+     */
+    fn.pixelRatio = function (point) {
+      return _rendererGL(this)?.pixelRatio(point);
+    };
+    
+    /**
+     * Returns the world-to-pixel ratio units at a given world point position.
+     * @param {p5.Vector|number[]} [point=p5.Tree.ORIGIN]
+     * @returns {number}
+     */
+    p5.RendererGL.prototype.pixelRatio = function (point = p5.Tree.ORIGIN) {
+      return this.isOrtho()
+        ? Math.abs(this.tPlane() - this.bPlane()) / this.height
+        : 2 * Math.abs(
+          this.transformPosition(point, { from: p5.Tree.WORLD, to: p5.Tree.EYE }).z
+        ) * Math.tan(this.fov() / 2) / this.height;
+    };
+
+    /**
+     * Returns the normalized texel size for an image/texture.
+     * Useful for offsetting UVs by exactly one pixel.
+     *
+     * @param {p5.Image|p5.Framebuffer|Object} image Any object exposing `width` and `height`.
+     * @returns {number[]} `[1 / width, 1 / height]`
+     */
+    fn.texOffset = function (image) {
+      return [1 / image.width, 1 / image.height];
+    };
+
+    /**
+     * Returns the current mouse position in *pixel* coordinates.
+     * By default the y-axis is flipped so y=0 is at the bottom (HUD-style).
+     *
+     * @param {boolean} [flip=true] Whether to flip the y coordinate.
+     * @returns {number[]} `[x, y]` in pixels (includes pixelDensity scaling).
+     */
+    fn.mousePosition = function (flip = true) {
+      const pd = this.pixelDensity();
+      return [pd * this.mouseX, pd * (flip ? this.height - this.mouseY : this.mouseY)];
+    };
+
+    /**
+     * Returns a pointer position in *pixel* coordinates from an arbitrary (x, y) pair.
+     * Delegates to the WEBGL renderer.
+     *
+     * Accepts parameters in any order:
+     * - `number, number` → pointerX, pointerY
+     * - optional `boolean` → `flip`
+     *
+     * @param  {...(number|boolean)} args
+     * @returns {number[]|undefined} `[x, y]` in pixels, or undefined if not in WEBGL.
+     */
+    fn.pointerPosition = function (...args) {
+      return _rendererGL(this)?.pointerPosition(...args);
+    };
+
+    /**
+     * Returns the canvas resolution in *pixel* coordinates.
+     * Delegates to the WEBGL renderer.
+     *
+     * @returns {number[]|undefined} `[width, height]` in pixels, or undefined if not in WEBGL.
+     */
+    fn.resolution = function () {
+      return _rendererGL(this)?.resolution();
+    };
+
+    /**
+     * Returns a pointer position in *pixel* coordinates from an arbitrary (x, y) pair.
+     *
+     * Accepts parameters in any order:
+     * - `number, number` → pointerX, pointerY
+     * - optional `boolean` → `flip`
+     *
+     * @param  {...(number|boolean)} args
+     * @returns {number[]} `[x, y]` in pixels (includes pixelDensity scaling).
+     */
+    p5.RendererGL.prototype.pointerPosition = function (...args) {
+      let pointerX;
+      let pointerY;
+      let flip = true;
+      for (const arg of args) {
+        if (typeof arg === 'number') {
+          // First number is x, second is y.
+          pointerX === undefined ? (pointerX = arg) : (pointerY = arg);
+        } else if (typeof arg === 'boolean') {
+          flip = arg;
+        }
+      }
+      const pd = this.pixelDensity();
+      return [pd * pointerX, pd * (flip ? this.height - pointerY : pointerY)];
+    };
+
+    /**
+     * Returns the canvas resolution in *pixel* coordinates.
+     * @returns {number[]} `[width, height]` in pixels (includes pixelDensity scaling).
+     */
+    p5.RendererGL.prototype.resolution = function () {
+      const pd = this.pixelDensity();
+      return [pd * this.width, pd * this.height];
+    };
+    
+    // -------------------------------------------------------------------------
+    // Drawing helpers (axes / grid)
+    // -------------------------------------------------------------------------
+    
+    fn.axes = function (opts) {
+      _rendererGL(this)?.axes(opts);
+      return this;
+    };
+    
+    p5.RendererGL.prototype.axes = function ({
+      size = 100,
+      colors = ['Red', 'Lime', 'DodgerBlue'],
+      bits = p5.Tree.LABELS | p5.Tree.X | p5.Tree.Y | p5.Tree.Z
+    } = {}) {
+      const p = this._pInst;
+      if (!p) return;
+      p.push();
+      if ((bits & p5.Tree.LABELS) !== 0) {
+        const charWidth = size / 40.0;
+        const charHeight = size / 30.0;
+        const charShift = 1.04 * size;
+        // The X
+        p.stroke(colors[0 % colors.length]);
+        p.line(charShift, charWidth, -charHeight, charShift, -charWidth, charHeight);
+        p.line(charShift, -charWidth, -charHeight, charShift, charWidth, charHeight);
+        // The Y
+        p.stroke(colors[1 % colors.length]);
+        p.line(charWidth, charShift, charHeight, 0.0, charShift, 0.0);
+        p.line(0.0, charShift, 0.0, -charWidth, charShift, charHeight);
+        p.line(-charWidth, charShift, charHeight, 0.0, charShift, 0.0);
+        p.line(0.0, charShift, 0.0, 0.0, charShift, -charHeight);
+        // The Z
+        p.stroke(colors[2 % colors.length]);
+        p.line(-charWidth, -charHeight, charShift, charWidth, -charHeight, charShift);
+        p.line(charWidth, -charHeight, charShift, -charWidth, charHeight, charShift);
+        p.line(-charWidth, charHeight, charShift, charWidth, charHeight, charShift);
+      }
+      // X Axis
+      p.stroke(colors[0 % colors.length]);
+      (bits & p5.Tree.X) !== 0 && p.line(0, 0, 0, size, 0, 0);
+      (bits & p5.Tree._X) !== 0 && p.line(0, 0, 0, -size, 0, 0);
+      // Y Axis
+      p.stroke(colors[1 % colors.length]);
+      (bits & p5.Tree.Y) !== 0 && p.line(0, 0, 0, 0, size, 0);
+      (bits & p5.Tree._Y) !== 0 && p.line(0, 0, 0, 0, -size, 0);
+      // Z Axis
+      p.stroke(colors[2 % colors.length]);
+      (bits & p5.Tree.Z) !== 0 && p.line(0, 0, 0, 0, 0, size);
+      (bits & p5.Tree._Z) !== 0 && p.line(0, 0, 0, 0, 0, -size);
+    
+      p.pop();
+    };
+    
+    fn.grid = function (opts) {
+      _rendererGL(this)?.grid(opts);
+      return this;
+    };
+    
+    p5.RendererGL.prototype.grid = function ({
+      size = 100,
+      subdivisions = 10,
+      style = p5.Tree.SOLID,
+      weight = 1,
+      minorSubdivisions = 5
+    } = {}) {
+      const p = this._pInst;
+      if (!p) return;
+      p.push();
+      if (style === p5.Tree.DOTS) {
+        let posi = 0;
+        let posj = 0;
+        p.strokeWeight(weight * 2);
+        p.beginShape(p.POINTS);
+        for (let i = 0; i <= subdivisions; ++i) {
+          posi = size * (2.0 * i / subdivisions - 1.0);
+          for (let j = 0; j <= subdivisions; ++j) {
+            posj = size * (2.0 * j / subdivisions - 1.0);
+            p.vertex(posi, posj, 0);
+          }
+        }
+        p.endShape();
+        const internalSub = Math.max(1, minorSubdivisions | 0);
+        const subSubdivisions = subdivisions * internalSub;
+        p.strokeWeight(weight);
+        p.beginShape(p.POINTS);
+        for (let i = 0; i <= subSubdivisions; ++i) {
+          posi = size * (2.0 * i / subSubdivisions - 1.0);
+          for (let j = 0; j <= subSubdivisions; ++j) {
+            posj = size * (2.0 * j / subSubdivisions - 1.0);
+            ((i % internalSub) !== 0 || (j % internalSub) !== 0) && p.vertex(posi, posj, 0);
+          }
+        }
+        p.endShape();
+      } else {
+        for (let i = 0; i <= subdivisions; ++i) {
+          const pos = size * (2.0 * i / subdivisions - 1.0);
+          p.line(pos, -size, 0, pos, +size, 0);
+          p.line(-size, pos, 0, size, pos, 0);
+        }
+      }
+      p.pop();
+    };
+    
+    // ---------------------------------------------------------------------------
+    // Picking
+    // ---------------------------------------------------------------------------
+    
+    /**
+     * Returns `true` if the mouse is close enough to a target screen position.
+     *
+     * If `x`/`y` are not provided, they are derived by projecting `mMatrix` to
+     * `p5.Tree.SCREEN`. In that case, `size` is interpreted in *world units* and
+     * converted to pixels using `pixelRatio()` at the corresponding world point.
+     *
+     * Requires WEBGL.
+     *
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.mMatrix] Model-space matrix origin to compute (x, y) from.
+     * @param {number} [opts.x] Screen x coordinate in HUD space (pixels).
+     * @param {number} [opts.y] Screen y coordinate in HUD space (pixels).
+     * @param {number} [opts.size=50] Picking diameter (pixels in HUD space, or world units when deriving x/y).
+     * @param {number} [opts.shape=p5.Tree.CIRCLE] Either `p5.Tree.CIRCLE` or `p5.Tree.SQUARE`.
+     * @param {p5.Matrix} [opts.eMatrix] Eye matrix override.
+     * @param {p5.Matrix} [opts.pMatrix] Projection matrix override.
+     * @param {p5.Matrix} [opts.vMatrix] View (camera) matrix override.
+     * @param {p5.Matrix} [opts.pvMatrix] Projection-view matrix override.
+     * @returns {boolean|undefined}
+     */
+    fn.mousePicking = function (opts) {
+      return _rendererGL(this)?.mousePicking(opts);
+    };
+    
+    /**
+     * Returns `true` if a pointer is close enough to a target screen position.
+     *
+     * If `x`/`y` are not provided, they are derived by projecting `mMatrix` to
+     * `p5.Tree.SCREEN`. In that case, `size` is interpreted in *world units* and
+     * converted to pixels using `pixelRatio()` at the corresponding world point.
+     *
+     * Requires WEBGL.
+     *
+     * @param {...any} args
+     * @returns {boolean|undefined}
+     */
+    fn.pointerPicking = function (...args) {
+      return _rendererGL(this)?.pointerPicking(...args);
+    };
+    
+    p5.RendererGL.prototype.mousePicking = function ({
+      mMatrix = this.mMatrix(),
+      x,
+      y,
+      size = 50,
+      shape = p5.Tree.CIRCLE,
+      eMatrix,
+      pMatrix,
+      vMatrix,
+      pvMatrix
+    } = {}) {
+      const p = this._pInst;
+      if (!p) return false;
+      return this.pointerPicking(p.mouseX, p.mouseY, { mMatrix, x, y, size, shape, eMatrix, pMatrix, vMatrix, pvMatrix });
+    };
+    
+    /**
+     * Returns `true` if pointer is close enough to a target screen position.
+     *
+     * Supported call patterns:
+     * - `pointerPicking(pointerX, pointerY, opts)`
+     * - `pointerPicking(opts)` (pointer defaults to current mouse if available)
+     *
+     * @param {...any} args
+     * @returns {boolean}
+     */
+    p5.RendererGL.prototype.pointerPicking = function (...args) {
+      let pointerX;
+      let pointerY;
+      const config = {};
+      for (const arg of args) {
+        if (typeof arg === 'number' && Number.isFinite(arg)) {
+          pointerX == null ? pointerX = arg : pointerY = arg;
+        } else if (arg && typeof arg === 'object') {
+          Object.assign(config, arg);
+        }
+      }
+      const p = this._pInst;
+      if (pointerX == null) pointerX = p ? p.mouseX : this.width / 2;
+      if (pointerY == null) pointerY = p ? p.mouseY : this.height / 2;
+      let {
+        mMatrix = this.mMatrix(),
+        x,
+        y,
+        size = 50,
+        shape = p5.Tree.CIRCLE,
+        eMatrix,
+        pMatrix,
+        vMatrix,
+        pvMatrix
+      } = config;
+      // If target screen position not provided, derive it from mMatrix.
+      // In that case, treat `size` as world units and convert to pixels locally.
+      if (x == null || y == null) {
+        const screen = this.transformPosition({ from: mMatrix, to: p5.Tree.SCREEN, pMatrix, vMatrix, pvMatrix });
+        x = screen.x;
+        y = screen.y;
+        const world = this.transformPosition({ from: mMatrix, to: p5.Tree.WORLD, eMatrix });
+        size = size / this.pixelRatio(world);
+      }
+      const r = size / 2.0;
+      const dx = x - pointerX;
+      const dy = y - pointerY;
+      return shape === p5.Tree.CIRCLE
+        ? Math.sqrt(dx * dx + dy * dy) < r
+        : (Math.abs(dx) < r && Math.abs(dy) < r);
+    };
+    
+    // -------------------------------------------------------------------------
+    // Drawing helpers (bullsEye / cross)
+    // -------------------------------------------------------------------------
+    
+    /**
+     * @private
+     * Draws a circle primitive in the *current* renderer space.
+     *
+     * This is a geometry primitive (lines / triangles in the XY plane at z=0),
+     * so it can be used in 3D *or* in HUD/screen space depending on the caller:
+     * - Call inside `beginHUD()/endHUD()` to interpret `x,y,radius` in screen pixels.
+     * - Call outside HUD to interpret them in the current 3D space units.
+     *
+     * @param {object} [opts]
+     * @param {boolean} [opts.filled=false] Whether to fill the circle.
+     * @param {number} [opts.x=width/2] Center x in current space.
+     * @param {number} [opts.y=height/2] Center y in current space.
+     * @param {number} [opts.radius=100] Radius in current space.
+     * @param {number} [opts.detail=50] Segment count.
+     */
+    p5.RendererGL.prototype._circle = function ({
+      filled = false,
+      x = this.width / 2,
+      y = this.height / 2,
+      radius = 100,
+      detail = 50
+    } = {}) {
+      const p = this._pInst;
+      if (!p) return;
+      p.push();
+      p.translate(x, y);
+      if (filled) {
+        p.beginShape(p.TRIANGLE_STRIP);
+        for (let t = 0; t <= detail; t++) {
+          const cx = Math.cos(t * (2 * Math.PI) / detail);
+          const cy = Math.sin(t * (2 * Math.PI) / detail);
+          p.vertex(0, 0, 0, 0.5, 0.5);
+          p.vertex(radius * cx, radius * cy, 0, (cx * 0.5) + 0.5, (cy * 0.5) + 0.5);
+        }
+        p.endShape();
+      } else {
+        const angle = (2 * Math.PI) / detail;
+        let last = { x: radius, y: 0 };
+        for (let i = 1; i <= detail; i++) {
+          const pos = { x: Math.cos(i * angle) * radius, y: Math.sin(i * angle) * radius };
+          p.line(last.x, last.y, pos.x, pos.y);
+          last = pos;
+        }
+      }
+      p.pop();
+    };
+    
+    /**
+     * Draws a cross in HUD space (`x,y` in screen coordinates).
+     *
+     * If `x` and `y` are not provided, the cross is placed at the screen position
+     * corresponding to the origin of `mMatrix`.
+     *
+     * If `mMatrix` is used (x/y omitted), `size` is interpreted in world units
+     * and converted to pixels using `pixelRatio()` at the corresponding world point.
+     *
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.mMatrix] Model-space matrix origin to compute (x, y) from.
+     * @param {number} [opts.x] Screen x coordinate in HUD space (pixels).
+     * @param {number} [opts.y] Screen y coordinate in HUD space (pixels).
+     * @param {number} [opts.size=50] Cross size (pixels in HUD space, or world units when deriving x/y).
+     * @param {p5.Matrix} [opts.eMatrix] Eye matrix override.
+     * @param {p5.Matrix} [opts.pMatrix] Projection matrix override.
+     * @param {p5.Matrix} [opts.vMatrix] View (camera) matrix override.
+     * @param {p5.Matrix} [opts.pvMatrix] Projection-view matrix override.
+     */
+    fn.cross = function (opts) {
+      _rendererGL(this)?.cross(opts);
+      return this;
+    };
+    
+    p5.RendererGL.prototype.cross = function ({
+      mMatrix = this.mMatrix(),
+      x,
+      y,
+      size = 50,
+      eMatrix,
+      pMatrix,
+      vMatrix,
+      pvMatrix
+    } = {}) {
+      const p = this._pInst;
+      if (!p) return;
+      
+      if (x == null || y == null) {
+        const screen = this.transformPosition({ from: mMatrix, to: p5.Tree.SCREEN, pMatrix, vMatrix, pvMatrix });
+        x = screen.x;
+        y = screen.y;
+        const world = this.transformPosition({ from: mMatrix, to: p5.Tree.WORLD, eMatrix });
+        size = size / this.pixelRatio(world);
+      }
+      const half = size / 2.0;
+      this.beginHUD();
+      p.line(x - half, y, x + half, y);
+      p.line(x, y - half, x, y + half);
+      this.endHUD();
+    };
+    
+    /**
+     * Draws a bulls-eye on the screen (HUD space): either a circle or square-corners,
+     * plus a center cross.
+     *
+     * If `x` and `y` are not provided, the bulls-eye is placed at the screen position
+     * corresponding to the origin of `mMatrix`.
+     *
+     * If `mMatrix` is used (x/y omitted), `size` is interpreted in world units
+     * and converted to pixels using `pixelRatio()` at the corresponding world point.
+     *
+     * @param {object} [opts]
+     * @param {p5.Matrix} [opts.mMatrix] Model-space matrix origin to compute (x, y) from.
+     * @param {number} [opts.x] Screen x coordinate in HUD space (pixels).
+     * @param {number} [opts.y] Screen y coordinate in HUD space (pixels).
+     * @param {number} [opts.size=50] Bulls-eye diameter (pixels in HUD space, or world units when deriving x/y).
+     * @param {number} [opts.shape=p5.Tree.CIRCLE] Either `p5.Tree.CIRCLE` or `p5.Tree.SQUARE`.
+     * @param {p5.Matrix} [opts.eMatrix] Eye matrix override.
+     * @param {p5.Matrix} [opts.pMatrix] Projection matrix override.
+     * @param {p5.Matrix} [opts.vMatrix] View (camera) matrix override.
+     * @param {p5.Matrix} [opts.pvMatrix] Projection-view matrix override.
+     */
+    fn.bullsEye = function (opts) {
+      _rendererGL(this)?.bullsEye(opts);
+      return this;
+    };
+    
+    p5.RendererGL.prototype.bullsEye = function ({
+      mMatrix = this.mMatrix(),
+      x,
+      y,
+      size = 50,
+      shape = p5.Tree.CIRCLE,
+      eMatrix,
+      pMatrix,
+      vMatrix,
+      pvMatrix
+    } = {}) {
+      const p = this._pInst;
+      if (!p) return;
+      if (x == null || y == null) {
+        const screen = this.transformPosition({ from: mMatrix, to: p5.Tree.SCREEN, pMatrix, vMatrix, pvMatrix });
+        x = screen.x;
+        y = screen.y;
+        const world = this.transformPosition({ from: mMatrix, to: p5.Tree.WORLD, eMatrix });
+        size = size / this.pixelRatio(world);
+      }
+      const half = size / 2.0;
+      const corner = 0.6 * half;
+      this.beginHUD();
+      if (shape === p5.Tree.CIRCLE) {
+        this._circle({ x, y, radius: half });
+      } else {
+        p.line(x - half, y - half + corner, x - half, y - half);
+        p.line(x - half, y - half, x - half + corner, y - half);
+        p.line(x + half - corner, y - half, x + half, y - half);
+        p.line(x + half, y - half, x + half, y - half + corner);
+        p.line(x + half, y + half - corner, x + half, y + half);
+        p.line(x + half, y + half, x + half - corner, y + half);
+        p.line(x - half + corner, y + half, x - half, y + half);
+        p.line(x - half, y + half, x - half, y + half - corner);
+      }
+      // Center cross (0.6 * size), in HUD space.
+      const crossHalf = 0.6 * half;
+      p.line(x - crossHalf, y, x + crossHalf, y);
+      p.line(x, y - crossHalf, x, y + crossHalf);
+      this.endHUD();
+    };
+    
+    // ---------------------------------------------------------------------------
+    // View frustum (pg frustum display)
+    // ---------------------------------------------------------------------------
+    
+    fn.viewFrustum = function (opts) {
+      _rendererGL(this)?.viewFrustum(opts);
+      return this;
+    };
+    
+    /**
+     * Displays a view frustum, either from a pg (p5.Graphics / p5.RendererGL) or from eMatrix/pMatrix.
+     *
+     * @param {Object} [opts]
+     * @param {p5.Matrix} [opts.vMatrix=this.vMatrix()] desired view matrix (world -> this eye) for drawing the frustum.
+     * @param {p5.RendererGL|p5.Graphics} [opts.pg] renderer/pg whose frustum is to be displayed.
+     * @param {p5.Matrix} [opts.eMatrix=pg?.eMatrix()] eye matrix defining frustum pose (eye -> world).
+     * @param {p5.Matrix} [opts.pMatrix=pg?.pMatrix()] projection matrix defining frustum projection.
+     * @param {number} [opts.bits=p5.Tree.NEAR|p5.Tree.FAR] bitmask (NEAR/FAR/BODY/APEX).
+     * @param {Function|false|null} [opts.viewer=...] callback drawn at the frustum origin (in frustum space).
+     */
+    p5.RendererGL.prototype.viewFrustum = function ({
+      vMatrix = this.vMatrix(),
+      pg,
+      eMatrix = pg?.eMatrix(),
+      pMatrix = pg?.pMatrix(),
+      bits = p5.Tree.NEAR | p5.Tree.FAR,
+      viewer = () => this.axes({ size: 50, bits: p5.Tree.X | p5.Tree._X | p5.Tree.Y | p5.Tree._Y | p5.Tree.Z | p5.Tree._Z })
+    } = {}) {
+      const p = this._pInst;
+      if (!p) return;
+      if (this === pg) {
+        console.error('displaying viewFrustum requires a pg different than this');
+        return;
+      }
+      if (!pMatrix || !eMatrix) {
+        console.error('displaying viewFrustum requires either a pg or projection and eye matrices');
+        return;
+      }
+      const states = this.states;
+      const uView = states?.uViewMatrix;
+      if (!uView) return;
+      p.push();
+      p.resetMatrix();
+      // Override view matrix in-place (fast path: no inversion).
+      // Save previous values so we can restore them after drawing.
+      const prevView = uView.copy();
+      uView.set(vMatrix);
+      // Apply frustum camera pose (eye -> world) as a model transform.
+      this.applyMatrix(...eMatrix.mat4);
+      // Optional viewer at frustum origin
+      typeof viewer === 'function' && viewer();
+      const isOrtho = pMatrix.isOrtho();
+      const apex = !isOrtho && ((bits & p5.Tree.APEX) !== 0);
+      const n = -pMatrix.nPlane();
+      const f = -pMatrix.fPlane();
+      const l = pMatrix.lPlane();
+      const r = pMatrix.rPlane();
+      // hack preserved (sign handling for t/b differs in ortho vs persp)
+      const t = isOrtho ? -pMatrix.tPlane() : pMatrix.tPlane();
+      const b = isOrtho ? -pMatrix.bPlane() : pMatrix.bPlane();
+      // far plane corners
+      const ratio = isOrtho ? 1 : f / n;
+      const _l = ratio * l;
+      const _r = ratio * r;
+      const _b = ratio * b;
+      const _t = ratio * t;
+      // FAR plane
+      if ((bits & p5.Tree.FAR) !== 0) {
+        this.beginShape();
+        this.vertex(_l, _t, f);
+        this.vertex(_r, _t, f);
+        this.vertex(_r, _b, f);
+        this.vertex(_l, _b, f);
+        this.endShape(p5.prototype.CLOSE);
+      } else {
+        this.line(_l, _t, f, _r, _t, f);
+        this.line(_r, _t, f, _r, _b, f);
+        this.line(_r, _b, f, _l, _b, f);
+        this.line(_l, _b, f, _l, _t, f);
+      }
+      // BODY
+      if ((bits & p5.Tree.BODY) !== 0) {
+        this.beginShape();
+        this.vertex(_l, _t, f);
+        this.vertex(l, t, n);
+        this.vertex(r, t, n);
+        this.vertex(_r, _t, f);
+        this.endShape();
+        this.beginShape();
+        this.vertex(_r, _t, f);
+        this.vertex(r, t, n);
+        this.vertex(r, b, n);
+        this.vertex(_r, _b, f);
+        this.endShape();
+        this.beginShape();
+        this.vertex(_r, _b, f);
+        this.vertex(r, b, n);
+        this.vertex(l, b, n);
+        this.vertex(_l, _b, f);
+        this.endShape();
+        this.beginShape();
+        this.vertex(l, t, n);
+        this.vertex(_l, _t, f);
+        this.vertex(_l, _b, f);
+        this.vertex(l, b, n);
+        this.endShape();
+        if (apex) {
+          this.line(0, 0, 0, r, t, n);
+          this.line(0, 0, 0, l, t, n);
+          this.line(0, 0, 0, l, b, n);
+          this.line(0, 0, 0, r, b, n);
+        }
+      } else {
+        this.line(apex ? 0 : r, apex ? 0 : t, apex ? 0 : n, _r, _t, f);
+        this.line(apex ? 0 : l, apex ? 0 : t, apex ? 0 : n, _l, _t, f);
+        this.line(apex ? 0 : l, apex ? 0 : b, apex ? 0 : n, _l, _b, f);
+        this.line(apex ? 0 : r, apex ? 0 : b, apex ? 0 : n, _r, _b, f);
+      }
+      // NEAR plane
+      if ((bits & p5.Tree.NEAR) !== 0) {
+        this.beginShape();
+        this.vertex(l, t, n);
+        this.vertex(r, t, n);
+        this.vertex(r, b, n);
+        this.vertex(l, b, n);
+        this.endShape(p5.prototype.CLOSE);
+      } else {
+        this.line(l, t, n, r, t, n);
+        this.line(r, t, n, r, b, n);
+        this.line(r, b, n, l, b, n);
+        this.line(l, b, n, l, t, n);
+      }
+      // Restore previous view matrix (no try/finally as requested).
+      uView.set(prevView);
+      p.pop();
+    };
+    
+    // ---------------------------------------------------------------------------
+    // Visibility (frustum culling queries)
+    // ---------------------------------------------------------------------------
+    
+    /**
+     * Returns object visibility with respect to the current view frustum.
+     * Object may be either:
+     * - a point (center),
+     * - a sphere (center + radius),
+     * - or an axis-aligned box (corner1 + corner2).
+     *
+     * @returns {number} One of p5.Tree.VISIBLE, p5.Tree.INVISIBLE, p5.Tree.SEMIVISIBLE.
+     */
+    fn.visibility = function (...args) {
+      return _rendererGL(this).visibility(...args);
+    };
+    
+    /**
+     * Returns the 6 plane equations of the view frustum in world space.
+     * @returns {Object}
+     */
+    fn.bounds = function (opts = {}) {
+      return _rendererGL(this).bounds(opts);
+    };
+    
+    /**
+     * Returns signed distance from a point to a frustum plane.
+     * @returns {number}
+     */
+    fn.distanceToBound = function (...args) {
+      return _rendererGL(this).distanceToBound(...args);
+    };
+    
+    /**
+     * Parses visibility query arguments.
+     * Supports:
+     * - visibility({ corner1, corner2, center, radius, bounds })
+     * - visibility(center[, radius][, bounds])
+     * - visibility(corner1, corner2[, bounds])
+     *
+     * @private
+     */
+    p5.RendererGL.prototype._parseVisibilityArgs = function (...args) {
+      let corner1;
+      let corner2;
+      let center;
+      let radius;
+      let pendingRadius;
+      let bounds;
+      const vecs = [];
+      const isPlainObject = v => {
+        if (!v || typeof v !== 'object') return false;
+        if (Array.isArray(v)) return false;
+        if (ArrayBuffer.isView(v)) return false;
+        return Object.getPrototypeOf(v) === Object.prototype;
+      };
+      for (const arg of args) {
+        if (arg instanceof p5.Vector || Array.isArray(arg)) {
+          vecs.push(arg);
+          continue;
+        }
+        if (typeof arg === 'number' && Number.isFinite(arg) && radius === undefined) {
+          // Only accept a radius if we already have (or will infer) a center.
+          center ? (radius = arg) : (pendingRadius = arg);
+          continue;
+        }
+        if (isPlainObject(arg)) {
+          if ('corner1' in arg || 'corner2' in arg || 'center' in arg || 'radius' in arg || 'bounds' in arg) {
+            corner1 = arg.corner1 ?? corner1;
+            corner2 = arg.corner2 ?? corner2;
+            center = arg.center ?? center;
+            radius = arg.radius ?? radius;
+            bounds = arg.bounds ?? bounds;
+          } else {
+            bounds = arg;
+          }
+        }
+      }
+      // Ordering rule: if 2 vectors are provided, first is corner1, second is corner2.
+      if (!corner1 && !corner2) {
+        if (!center && vecs.length === 1) {
+          center = vecs[0];
+        } else if (!corner1 && !corner2 && vecs.length >= 2) {
+          corner1 = vecs[0];
+          corner2 = vecs[1];
+        }
+      }
+      // Commit leading radius only if we ended up with a center (supports visibility(radius, center[, bounds])).
+      if (radius === undefined && pendingRadius !== undefined && center) {
+        radius = pendingRadius;
+      }
+      return { corner1, corner2, center, radius, bounds };
+    };
+    
+    /**
+     * Returns object visibility with respect to the current view frustum.
+     *
+     * Supported forms:
+     * - visibility(center[, radius][, bounds])
+     * - visibility(radius, center[, bounds])
+     * - visibility(corner1, corner2[, bounds])
+     * - visibility({ corner1, corner2, center, radius, bounds })
+     *
+     * @param {Object} [opts]
+     * @param {p5.Vector|number[]} [opts.corner1] First box corner (use with corner2).
+     * @param {p5.Vector|number[]} [opts.corner2] Second box corner (use with corner1).
+     * @param {p5.Vector|number[]} [opts.center] Sphere (or point) center.
+     * @param {number} [opts.radius] Sphere radius (if omitted, center is treated as point).
+     * @param {Object} [opts.bounds] Frustum plane equations (defaults to this.bounds()).
+     * @returns {number} One of p5.Tree.VISIBLE, p5.Tree.INVISIBLE, p5.Tree.SEMIVISIBLE.
+     */
+    p5.RendererGL.prototype.visibility = function (...args) {
+      const { corner1, corner2, center, radius, bounds } = this._parseVisibilityArgs(...args);
+      const b = bounds ?? this.bounds();
+      return center ? (radius ? this._ballVisibility(center, radius, b) : this._pointVisibility(center, b))
+        : (corner1 && corner2 ? this._boxVisibility(corner1, corner2, b)
+          : (console.error('[p5.tree] visibility: could not parse query.'), p5.Tree.INVISIBLE));
+    };
+    
+    p5.RendererGL.prototype._pointVisibility = function (point, bounds = this.bounds()) {
+      for (const key in bounds) {
+        const d = this.distanceToBound(point, key, bounds);
+        if (d > 0) return p5.Tree.INVISIBLE;
+        if (d === 0) return p5.Tree.SEMIVISIBLE;
+      }
+      return p5.Tree.VISIBLE;
+    };
+    
+    p5.RendererGL.prototype._ballVisibility = function (center, radius, bounds = this.bounds()) {
+      let allInForAllPlanes = true;
+      for (const key in bounds) {
+        const d = this.distanceToBound(center, key, bounds);
+        if (d > radius) return p5.Tree.INVISIBLE;
+        if (d > 0 || -d < radius) allInForAllPlanes = false;
+      }
+      return allInForAllPlanes ? p5.Tree.VISIBLE : p5.Tree.SEMIVISIBLE;
+    };
+    
+    p5.RendererGL.prototype._boxVisibility = function (corner1, corner2, bounds = this.bounds()) {
+      const asVec3 = v =>
+        v instanceof p5.Vector ? v : new p5.Vector(v?.[0] ?? 0, v?.[1] ?? 0, v?.[2] ?? 0);
+      corner1 = asVec3(corner1);
+      corner2 = asVec3(corner2);
+      let allInForAllPlanes = true;
+      for (const key in bounds) {
+        let allOut = true;
+        for (let c = 0; c < 8; ++c) {
+          const pos = new p5.Vector(
+            (c & 4) !== 0 ? corner1.x : corner2.x,
+            (c & 2) !== 0 ? corner1.y : corner2.y,
+            (c & 1) !== 0 ? corner1.z : corner2.z
+          );
+          if (this.distanceToBound(pos, key, bounds) > 0) {
+            allInForAllPlanes = false;
+          } else {
+            allOut = false;
+          }
+        }
+        if (allOut) return p5.Tree.INVISIBLE;
+      }
+      return allInForAllPlanes ? p5.Tree.VISIBLE : p5.Tree.SEMIVISIBLE;
+    };
+    
+    /**
+     * Returns the 6 plane equations of the view frustum bounds defined in world space.
+     * Each plane equation is of the form:
+     *   a*x + b*y + c*z + d = 0
+     *
+     * @param {Object} [opts]
+     * @param {p5.Matrix} [opts.vMatrix] View matrix (world -> eye).
+     * @param {p5.Matrix} [opts.eMatrix] Eye matrix (eye -> world).
+     * @returns {Object} Object keyed by p5.Tree.LEFT/RIGHT/NEAR/FAR/TOP/BOTTOM.
+     */
+    p5.RendererGL.prototype.bounds = function ({
+      vMatrix,
+      eMatrix
+    } = {}) {
+      const n = this.nPlane();
+      const f = this.fPlane();
+      const l = this.lPlane();
+      const r = this.rPlane();
+      const b = this.bPlane();
+      const t = this.tPlane();
+      const normals = Array(6);
+      const distances = Array(6);
+      // Camera position and basis in world space.
+      const pos = this._position([0, 0, 0], { from: p5.Tree.EYE, to: p5.Tree.WORLD, eMatrix });
+      const viewDir = this._direction([0, 0, -1], { from: p5.Tree.EYE, to: p5.Tree.WORLD, vMatrix });
+      const up = this._direction([0, 1, 0], { from: p5.Tree.EYE, to: p5.Tree.WORLD, vMatrix });
+      const right = this._direction([1, 0, 0], { from: p5.Tree.EYE, to: p5.Tree.WORLD, vMatrix });
+      const posViewDir = p5.Vector.dot(pos, viewDir);
+      if (this.isOrtho()) {
+        normals[0] = p5.Vector.mult(right, -1);
+        normals[1] = right;
+        normals[4] = up;
+        normals[5] = p5.Vector.mult(up, -1);
+        distances[0] = p5.Vector.dot(p5.Vector.sub(pos, p5.Vector.mult(right, -l)), normals[0]);
+        distances[1] = p5.Vector.dot(p5.Vector.add(pos, p5.Vector.mult(right, r)), normals[1]);
+        distances[4] = p5.Vector.dot(p5.Vector.add(pos, p5.Vector.mult(up, -b)), normals[4]);
+        distances[5] = p5.Vector.dot(p5.Vector.sub(pos, p5.Vector.mult(up, t)), normals[5]);
+      } else {
+        const hfovr = Math.atan2(r, n);
+        const shfovr = Math.sin(hfovr);
+        const chfovr = Math.cos(hfovr);
+        const hfovl = Math.atan2(l, n);
+        const shfovl = Math.sin(hfovl);
+        const chfovl = Math.cos(hfovl);
+        normals[0] = p5.Vector.add(p5.Vector.mult(viewDir, shfovl), p5.Vector.mult(right, -chfovl));
+        normals[1] = p5.Vector.add(p5.Vector.mult(viewDir, -shfovr), p5.Vector.mult(right, chfovr));
+        const fovt = Math.atan2(t, n);
+        const sfovt = Math.sin(fovt);
+        const cfovt = Math.cos(fovt);
+        const fovb = Math.atan2(b, n);
+        const sfovb = Math.sin(fovb);
+        const cfovb = Math.cos(fovb);
+        normals[4] = p5.Vector.add(p5.Vector.mult(viewDir, -sfovt), p5.Vector.mult(up, cfovt));
+        normals[5] = p5.Vector.add(p5.Vector.mult(viewDir, sfovb), p5.Vector.mult(up, -cfovb));
+        distances[0] = shfovl * posViewDir - chfovl * p5.Vector.dot(pos, right);
+        distances[1] = -shfovr * posViewDir + chfovr * p5.Vector.dot(pos, right);
+        distances[4] = -sfovt * posViewDir + cfovt * p5.Vector.dot(pos, up);
+        distances[5] = sfovb * posViewDir - cfovb * p5.Vector.dot(pos, up);
+      }
+      // Near/far planes (common to ortho and perspective).
+      normals[2] = p5.Vector.mult(viewDir, -1);
+      normals[3] = viewDir;
+      distances[2] = -posViewDir - n;
+      distances[3] = posViewDir + f;
+      const bounds = {};
+      bounds[p5.Tree.LEFT] = { a: normals[0].x, b: normals[0].y, c: normals[0].z, d: distances[0] };
+      bounds[p5.Tree.RIGHT] = { a: normals[1].x, b: normals[1].y, c: normals[1].z, d: distances[1] };
+      bounds[p5.Tree.NEAR] = { a: normals[2].x, b: normals[2].y, c: normals[2].z, d: distances[2] };
+      bounds[p5.Tree.FAR] = { a: normals[3].x, b: normals[3].y, c: normals[3].z, d: distances[3] };
+      bounds[p5.Tree.TOP] = { a: normals[4].x, b: normals[4].y, c: normals[4].z, d: distances[4] };
+      bounds[p5.Tree.BOTTOM] = { a: normals[5].x, b: normals[5].y, c: normals[5].z, d: distances[5] };
+      return bounds;
+    };
+    
+    /**
+     * Returns signed distance between a point and a frustum plane.
+     *
+     * @param {p5.Vector|number[]} point
+     * @param {number|string} key One of p5.Tree.LEFT/RIGHT/BOTTOM/TOP/NEAR/FAR.
+     * @param {Object} [bounds] Plane equations (defaults to this.bounds()).
+     * @returns {number}
+     */
+    p5.RendererGL.prototype.distanceToBound = function (...args) {
+      let point;
+      let key;
+      let bounds = this.bounds();
+      const asVec3 = v =>
+        v instanceof p5.Vector ? v : new p5.Vector(v?.[0] ?? 0, v?.[1] ?? 0, v?.[2] ?? 0);
+      for (const arg of args) {
+        if (arg instanceof p5.Vector || Array.isArray(arg)) {
+          point = asVec3(arg);
+        } else if (typeof arg === 'string' || typeof arg === 'number') {
+          key = arg;
+        } else if (arg && typeof arg === 'object' && !Array.isArray(arg)) {
+          bounds = arg;
+        }
+      }
+      if (!point || key === undefined) {
+        console.error('[p5.tree] distanceToBound: could not parse query.');
+        return 0;
+      }
+      const eq = bounds[key];
+      return p5.Vector.dot(point, new p5.Vector(eq.a, eq.b, eq.c)) - eq.d;
+    };
+  });
+
+})(p5);
+//# sourceMappingURL=p5.tree.js.map