p5.tree 0.0.2 → 0.0.4

package/dist/p5.tree.js

@@ -3,16 +3,16 @@
 
   /**
    * @file Adds Tree rendering functions to the p5 prototype.
-   * @version 0.0.2
+   * @version 0.0.4
    * @author JP Charalambos
    * @license GPL-3.0-only
    *
    * @description
-   * A p5.js WEBGL addon for shader development and space transformations.
+   * A p5.js 3D addon for matrix queries, shader workflows, and space transformations.
    * 
    * Camera path recording/playback section.
    *
-   * Requires WEBGL (p5.Camera).
+   * Requires 3D renderer (p5.Camera).
    *
    * Camera API:
    *   camera.path : p5.Camera[]
@@ -39,7 +39,7 @@
     const CONST = value => ({ value, writable: false, enumerable: true, configurable: false });
     
     Object.defineProperties(p5.Tree, {
-      VERSION: CONST('0.0.2'),
+      VERSION: CONST('0.0.4'),
                             
       NONE: CONST(0),
     
@@ -49,6 +49,7 @@
       NDC: CONST('NDC'),
       SCREEN: CONST('SCREEN'),
       MODEL: CONST('MODEL'),
+      OBJECT: CONST('MODEL'), // alias of MODEL (shader terminology)
     
       // Points and vectors
       ORIGIN: CONST(Object.freeze([0, 0, 0])),
@@ -69,9 +70,6 @@
       Z: CONST(1 << 4),
       _Z: CONST(1 << 5),
       LABELS: CONST(1 << 6),
-      
-      DOTS: CONST(0),
-      SOLID: CONST(1),
                             
       // bullsEye
       CIRCLE: CONST(0),
@@ -100,13 +98,13 @@
 
     /**
      * @private
-     * Returns the WEBGL renderer or undefined.
-     * @param {p5} pInst
-     * @returns {p5.RendererGL|undefined}
+     * Returns the active 3D renderer (WEBGL or WEBGPU) or undefined.
+     * @param {p5} pInst - The p5 instance.
+     * @returns {p5.Renderer3D|undefined} The active 3D renderer if available.
      */
-    const _rendererGL = function (pInst) {
-      const r = pInst._renderer;
-      return r instanceof p5.RendererGL ? r : undefined;
+    const _renderer3D = function (pInst) {
+      const r = pInst?._renderer;
+      return r instanceof p5.Renderer3D ? r : undefined;
     };
 
     // ---------------------------------------------------------------------------
@@ -219,34 +217,34 @@
      * Returns the current projection matrix (immutable copy).
      * @returns {p5.Matrix}
      */
-    p5.RendererGL.prototype.pMatrix = function () {
+    p5.Renderer3D.prototype.pMatrix = function () {
       return this.states.uPMatrix.clone();
     };
 
     /**
      * Returns the current projection matrix (immutable copy).
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {p5.Matrix}
      */
     fn.pMatrix = function () {
-      return _rendererGL(this).pMatrix();
+      return _renderer3D(this).pMatrix();
     };
 
     /**
      * Returns the current model matrix (immutable copy).
      * @returns {p5.Matrix}
      */
-    p5.RendererGL.prototype.mMatrix = function () {
+    p5.Renderer3D.prototype.mMatrix = function () {
       return this.states.uModelMatrix.clone();
     };
 
     /**
      * Returns the current model matrix (immutable copy).
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {p5.Matrix}
      */
     fn.mMatrix = function () {
-      return _rendererGL(this).mMatrix();
+      return _renderer3D(this).mMatrix();
     };
 
     /**
@@ -270,46 +268,46 @@
      * Prefers the renderer cached view matrix when available.
      * @returns {p5.Matrix}
      */
-    p5.RendererGL.prototype.vMatrix = function () {
+    p5.Renderer3D.prototype.vMatrix = function () {
       return (this.states.uViewMatrix || this.states.curCamera.cameraMatrix).clone();
     };
 
     /**
      * Returns the current view matrix (world -> camera) (immutable copy).
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {p5.Matrix}
      */
     fn.vMatrix = function () {
-      return _rendererGL(this).vMatrix();
+      return _renderer3D(this).vMatrix();
     };
 
     /**
      * Returns the current eye matrix (camera -> world) (immutable).
      * @returns {p5.Matrix}
      */
-    p5.RendererGL.prototype.eMatrix = function () {
+    p5.Renderer3D.prototype.eMatrix = function () {
       return _invert(this.states.uViewMatrix || this.states.curCamera.cameraMatrix);
     };
 
     /**
      * Returns the current eye matrix (camera -> world) (immutable).
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {p5.Matrix}
      */
     fn.eMatrix = function () {
-      return _rendererGL(this).eMatrix();
+      return _renderer3D(this).eMatrix();
     };
 
     /**
      * lMatrix({ from, to }):
-     * Position transform (mat4) mapping points from `from` space to `to` space.
+     * 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 ({
+    p5.Renderer3D.prototype.lMatrix = function ({
       from = new p5.Matrix(4),
       to = this.eMatrix()
     } = {}) {
@@ -318,15 +316,15 @@
 
     /**
      * lMatrix({ from, to }):
-     * Position transform (mat4) mapping points from `from` space to `to` space.
-     * Requires WEBGL.
+     * Location transform (mat4) mapping points from `from` space to `to` space.
+     * Requires 3D renderer.
      * @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);
+      return _renderer3D(this).lMatrix(opts);
     };
 
     /**
@@ -340,7 +338,7 @@
      * @param {p5.Matrix} [opts.matrix] Precomputed mat4 override.
      * @returns {p5.Matrix} mat3
      */
-    p5.RendererGL.prototype.dMatrix = function ({
+    p5.Renderer3D.prototype.dMatrix = function ({
       from = new p5.Matrix(4),
       to = this.eMatrix(),
       matrix
@@ -358,7 +356,7 @@
     /**
      * dMatrix({ from, to, matrix }):
      * Direction transform (mat3) mapping vectors from `from` space to `to` space.
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @param {object} [opts]
      * @param {p5.Matrix} [opts.from]
      * @param {p5.Matrix} [opts.to]
@@ -366,7 +364,7 @@
      * @returns {p5.Matrix} mat3
      */
     fn.dMatrix = function (opts = {}) {
-      return _rendererGL(this).dMatrix(opts);
+      return _renderer3D(this).dMatrix(opts);
     };
 
     /**
@@ -377,7 +375,7 @@
      * @param {p5.Matrix} [opts.mMatrix=this.mMatrix()] Model matrix.
      * @returns {p5.Matrix}
      */
-    p5.RendererGL.prototype.mvMatrix = function ({
+    p5.Renderer3D.prototype.mvMatrix = function ({
       vMatrix = this.vMatrix(),
       mMatrix
     } = {}) {
@@ -387,14 +385,14 @@
     /**
      * mvMatrix({ vMatrix, mMatrix }):
      * ModelView matrix (mat4) = M * V (p5-v2 convention).
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @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);
+      return _renderer3D(this).mvMatrix(opts);
     };
 
     /**
@@ -406,7 +404,7 @@
      * @param {p5.Matrix} [opts.mvMatrix=this.mvMatrix({ mMatrix, vMatrix })] Optional MV matrix override.
      * @returns {p5.Matrix} mat3
      */
-    p5.RendererGL.prototype.nMatrix = function ({
+    p5.Renderer3D.prototype.nMatrix = function ({
       vMatrix,
       mMatrix,
       mvMatrix = this.mvMatrix({ mMatrix, vMatrix })
@@ -417,7 +415,7 @@
     /**
      * nMatrix({ vMatrix, mMatrix, mvMatrix }):
      * Normal matrix (mat3) = inverseTranspose(linear_part(MV)).
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @param {object} [opts]
      * @param {p5.Matrix} [opts.vMatrix]
      * @param {p5.Matrix} [opts.mMatrix]
@@ -425,7 +423,7 @@
      * @returns {p5.Matrix} mat3
      */
     fn.nMatrix = function (opts = {}) {
-      return _rendererGL(this).nMatrix(opts);
+      return _renderer3D(this).nMatrix(opts);
     };
 
     /**
@@ -438,7 +436,7 @@
      * @param {p5.Matrix} [opts.mvMatrix=this.mvMatrix({ mMatrix, vMatrix })] Optional MV matrix override.
      * @returns {p5.Matrix}
      */
-    p5.RendererGL.prototype.pmvMatrix = function ({
+    p5.Renderer3D.prototype.pmvMatrix = function ({
       pMatrix = this.pMatrix(),
       vMatrix,
       mMatrix,
@@ -450,7 +448,7 @@
     /**
      * pmvMatrix({ pMatrix, vMatrix, mMatrix, mvMatrix }):
      * PMV (mat4) = M * V * P (p5-v2 convention).
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @param {object} [opts]
      * @param {p5.Matrix} [opts.pMatrix]
      * @param {p5.Matrix} [opts.vMatrix]
@@ -459,7 +457,7 @@
      * @returns {p5.Matrix}
      */
     fn.pmvMatrix = function (opts = {}) {
-      return _rendererGL(this).pmvMatrix(opts);
+      return _renderer3D(this).pmvMatrix(opts);
     };
 
     /**
@@ -470,7 +468,7 @@
      * @param {p5.Matrix} [opts.vMatrix=this.vMatrix()] View matrix.
      * @returns {p5.Matrix}
      */
-    p5.RendererGL.prototype.pvMatrix = function ({
+    p5.Renderer3D.prototype.pvMatrix = function ({
       pMatrix = this.pMatrix(),
       vMatrix
     } = {}) {
@@ -480,14 +478,14 @@
     /**
      * pvMatrix({ pMatrix, vMatrix }):
      * PV (mat4) = V * P (p5-v2 convention).
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @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);
+      return _renderer3D(this).pvMatrix(opts);
     };
     
     /**
@@ -499,7 +497,7 @@
      * @param {p5.Matrix} [opts.pvMatrix=this.pvMatrix({ pMatrix, vMatrix })] Optional PV matrix override.
      * @returns {p5.Matrix}
      */
-    p5.RendererGL.prototype.ipvMatrix = function ({
+    p5.Renderer3D.prototype.ipvMatrix = function ({
       pMatrix,
       vMatrix,
       pvMatrix = this.pvMatrix({ pMatrix, vMatrix })
@@ -509,12 +507,12 @@
     
     /**
      * ipvMatrix({ pMatrix, vMatrix, pvMatrix }):
-     * Inverse(PV) (mat4). Requires WEBGL.
+     * Inverse(PV) (mat4). Requires 3D renderer.
      * @param {object} [opts]
      * @returns {p5.Matrix}
      */
     fn.ipvMatrix = function (opts = {}) {
-      return _rendererGL(this).ipvMatrix(opts);
+      return _renderer3D(this).ipvMatrix(opts);
     };
 
     // ---------------------------------------------------------------------------
@@ -533,17 +531,17 @@
      * Returns true if the current projection is orthographic.
      * @returns {boolean}
      */
-    p5.RendererGL.prototype.isOrtho = function () {
+    p5.Renderer3D.prototype.isOrtho = function () {
       return this.pMatrix().isOrtho();
     };
 
     /**
      * Returns true if the current projection is orthographic.
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {boolean}
      */
     fn.isOrtho = function () {
-      return _rendererGL(this).isOrtho();
+      return _renderer3D(this).isOrtho();
     };
 
     /**
@@ -604,7 +602,7 @@
      * Near plane distance for the current projection.
      * @returns {number}
      */
-    p5.RendererGL.prototype.nPlane = function () {
+    p5.Renderer3D.prototype.nPlane = function () {
       return this.pMatrix().nPlane();
     };
 
@@ -612,7 +610,7 @@
      * Far plane distance for the current projection.
      * @returns {number}
      */
-    p5.RendererGL.prototype.fPlane = function () {
+    p5.Renderer3D.prototype.fPlane = function () {
       return this.pMatrix().fPlane();
     };
 
@@ -620,7 +618,7 @@
      * Left plane for the current projection.
      * @returns {number}
      */
-    p5.RendererGL.prototype.lPlane = function () {
+    p5.Renderer3D.prototype.lPlane = function () {
       return this.pMatrix().lPlane();
     };
 
@@ -628,7 +626,7 @@
      * Right plane for the current projection.
      * @returns {number}
      */
-    p5.RendererGL.prototype.rPlane = function () {
+    p5.Renderer3D.prototype.rPlane = function () {
       return this.pMatrix().rPlane();
     };
 
@@ -636,7 +634,7 @@
      * Top plane for the current projection.
      * @returns {number}
      */
-    p5.RendererGL.prototype.tPlane = function () {
+    p5.Renderer3D.prototype.tPlane = function () {
       return this.pMatrix().tPlane();
     };
 
@@ -644,62 +642,62 @@
      * Bottom plane for the current projection.
      * @returns {number}
      */
-    p5.RendererGL.prototype.bPlane = function () {
+    p5.Renderer3D.prototype.bPlane = function () {
       return this.pMatrix().bPlane();
     };
 
     /**
      * Near plane distance for the current projection.
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {number}
      */
     fn.nPlane = function () {
-      return _rendererGL(this).nPlane();
+      return _renderer3D(this).nPlane();
     };
 
     /**
      * Far plane distance for the current projection.
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {number}
      */
     fn.fPlane = function () {
-      return _rendererGL(this).fPlane();
+      return _renderer3D(this).fPlane();
     };
 
     /**
      * Left plane for the current projection.
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {number}
      */
     fn.lPlane = function () {
-      return _rendererGL(this).lPlane();
+      return _renderer3D(this).lPlane();
     };
 
     /**
      * Right plane for the current projection.
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {number}
      */
     fn.rPlane = function () {
-      return _rendererGL(this).rPlane();
+      return _renderer3D(this).rPlane();
     };
 
     /**
      * Top plane for the current projection.
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {number}
      */
     fn.tPlane = function () {
-      return _rendererGL(this).tPlane();
+      return _renderer3D(this).tPlane();
     };
 
     /**
      * Bottom plane for the current projection.
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {number}
      */
     fn.bPlane = function () {
-      return _rendererGL(this).bPlane();
+      return _renderer3D(this).bPlane();
     };
 
     /**
@@ -730,7 +728,7 @@
      * Vertical field of view (radians) of the current projection.
      * @returns {number|undefined}
      */
-    p5.RendererGL.prototype.fov = function () {
+    p5.Renderer3D.prototype.fov = function () {
       return this.pMatrix().fov();
     };
 
@@ -738,26 +736,26 @@
      * Horizontal field of view (radians) of the current projection.
      * @returns {number|undefined}
      */
-    p5.RendererGL.prototype.hfov = function () {
+    p5.Renderer3D.prototype.hfov = function () {
       return this.pMatrix().hfov();
     };
 
     /**
      * Vertical field of view (radians) of the current projection.
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {number|undefined}
      */
     fn.fov = function () {
-      return _rendererGL(this).fov();
+      return _renderer3D(this).fov();
     };
 
     /**
      * Horizontal field of view (radians) of the current projection.
-     * Requires WEBGL.
+     * Requires 3D renderer.
      * @returns {number|undefined}
      */
     fn.hfov = function () {
-      return _rendererGL(this).hfov();
+      return _renderer3D(this).hfov();
     };
 
     // --- private keys (shared internal state across protos) ---
@@ -1340,7 +1338,7 @@
     
     /*
     // treegl approach:
-    p5.RendererGL.prototype.beginHUD = function () {
+    p5.Renderer3D.prototype.beginHUD = function () {
       if (this._hudActive === true) return;
       const p = this._pInst;
       const gl = this.drawingContext;
@@ -1377,7 +1375,7 @@
       this._hudActive = true;
     };
     
-    p5.RendererGL.prototype.endHUD = function () {
+    p5.Renderer3D.prototype.endHUD = function () {
       if (this._hudActive !== true) return;
       const p = this._pInst;
       const gl = this.drawingContext;
@@ -1398,46 +1396,54 @@
     };
     */
     
-    p5.RendererGL.prototype.beginHUD = function () {
+    p5.Renderer3D.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
+      if (!p || !states) return;
+      p.push();
       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);
+      this._hudDepthMode = undefined;
+      this._hudDepthWasEnabled = undefined;
+      if (typeof this.clearDepth === 'function') {
+        this.flushDraw?.();
+        this.clearDepth(1);
+        this._hudDepthMode = 'clearDepth';
+      } else {
+        const gl = this.drawingContext;
+        if (gl && typeof gl.isEnabled === 'function' && gl.DEPTH_TEST !== undefined) {
+          this._hudDepthWasEnabled = gl.isEnabled(gl.DEPTH_TEST);
+          gl.flush?.();
+          gl.disable(gl.DEPTH_TEST);
+          this._hudDepthMode = 'depthTestToggle';
+        }
+      }
       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 () {
+    p5.Renderer3D.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);
+      if (!p) return;
+      if (this._hudDepthMode === 'depthTestToggle') {
+        const gl = this.drawingContext;
+        if (gl && gl.DEPTH_TEST !== undefined) {
+          gl.flush?.();
+          this._hudDepthWasEnabled ? gl.enable(gl.DEPTH_TEST) : gl.disable(gl.DEPTH_TEST);
+        }
+      }
+      p.pop();
       this._hudPrevCam !== undefined && p.setCamera(this._hudPrevCam);
       this._hudPrevCam = undefined;
       this._hudDepthWasEnabled = undefined;
+      this._hudDepthMode = undefined;
       this._hudActive = false;
     };
     
@@ -1445,7 +1451,7 @@
     // Space transforms: mapLocation / mapDirection
     // ---------------------------------------------------------------------------
     
-    p5.RendererGL.prototype._parseTransformArgs = function (defaultMainArg, ...args) {
+    p5.Renderer3D.prototype._parseTransformArgs = function (defaultMainArg, ...args) {
       let mainArg = defaultMainArg;
       const options = {};
       for (const arg of args) {
@@ -1463,7 +1469,7 @@
     // ---------------------------------------------------------------------------
     
     fn.mapLocation = function (...args) {
-      return _rendererGL(this)?.mapLocation(...args);
+      return _renderer3D(this)?.mapLocation(...args);
     };
     
     /**
@@ -1480,12 +1486,12 @@
      * @param {p5.Matrix} [opts.ipvMatrix]
      * @returns {p5.Vector}
      */
-    p5.RendererGL.prototype.mapLocation = function (...args) {
+    p5.Renderer3D.prototype.mapLocation = function (...args) {
       const { mainArg, options } = this._parseTransformArgs(p5.Tree.ORIGIN, ...args);
       return this._location(mainArg, options);
     };
     
-    p5.RendererGL.prototype._location = function (
+    p5.Renderer3D.prototype._location = function (
       point = p5.Tree.ORIGIN,
       {
         from = p5.Tree.EYE,
@@ -1507,25 +1513,25 @@
         to = this.mMatrix({ eMatrix });
       }
       if ((from == p5.Tree.WORLD) && (to == p5.Tree.SCREEN)) {
-        return this._worldToScreenPosition({ point, pMatrix, vMatrix, pvMatrix });
+        return this._worldToScreenLocation({ point, pMatrix, vMatrix, pvMatrix });
       }
       if ((from == p5.Tree.SCREEN) && (to == p5.Tree.WORLD)) {
-        return this._screenToWorldPosition({ point, pMatrix, vMatrix, pvMatrix, ipvMatrix });
+        return this._screenToWorldLocation({ point, pMatrix, vMatrix, pvMatrix, ipvMatrix });
       }
       if (from == p5.Tree.SCREEN && to == p5.Tree.NDC) {
-        return this._screenToNDCPosition(point);
+        return this._screenToNDCLocation(point);
       }
       if (from == p5.Tree.NDC && to == p5.Tree.SCREEN) {
-        return this._ndcToScreenPosition(point);
+        return this._ndcToScreenLocation(point);
       }
       if (from == p5.Tree.WORLD && to == p5.Tree.NDC) {
-        return this._screenToNDCPosition(
-          this._worldToScreenPosition({ point, pMatrix, vMatrix, pvMatrix })
+        return this._screenToNDCLocation(
+          this._worldToScreenLocation({ point, pMatrix, vMatrix, pvMatrix })
         );
       }
       if (from == p5.Tree.NDC && to == p5.Tree.WORLD) {
-        return this._screenToWorldPosition({
-          point: this._ndcToScreenPosition(point),
+        return this._screenToWorldLocation({
+          point: this._ndcToScreenLocation(point),
           pMatrix,
           vMatrix,
           pvMatrix,
@@ -1537,8 +1543,8 @@
           ? (vMatrix ?? this.vMatrix())
           : to.copy().invert(to)
         ).mult4(
-          this._screenToWorldPosition({
-            point: this._ndcToScreenPosition(point),
+          this._screenToWorldLocation({
+            point: this._ndcToScreenLocation(point),
             pMatrix,
             vMatrix,
             pvMatrix,
@@ -1547,8 +1553,8 @@
         );
       }
       if ((from instanceof p5.Matrix || from == p5.Tree.EYE) && to == p5.Tree.NDC) {
-        return this._screenToNDCPosition(
-          this._worldToScreenPosition({
+        return this._screenToNDCLocation(
+          this._worldToScreenLocation({
             point: (from == p5.Tree.EYE
               ? (eMatrix ?? this.eMatrix())
               : from
@@ -1579,11 +1585,11 @@
           ? (vMatrix ?? this.vMatrix())
           : to.copy().invert(to)
         ).mult4(
-          this._screenToWorldPosition({ point, pMatrix, vMatrix, pvMatrix, ipvMatrix })
+          this._screenToWorldLocation({ point, pMatrix, vMatrix, pvMatrix, ipvMatrix })
         );
       }
       if ((from instanceof p5.Matrix || from == p5.Tree.EYE) && to == p5.Tree.SCREEN) {
-        return this._worldToScreenPosition({
+        return this._worldToScreenLocation({
           point: (from == p5.Tree.EYE
             ? (eMatrix ?? this.eMatrix())
             : from
@@ -1603,7 +1609,7 @@
       return point;
     };
     
-    p5.RendererGL.prototype._ndcToScreenPosition = function (point) {
+    p5.Renderer3D.prototype._ndcToScreenLocation = 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),
@@ -1611,7 +1617,7 @@
       );
     };
     
-    p5.RendererGL.prototype._screenToNDCPosition = function (point) {
+    p5.Renderer3D.prototype._screenToNDCLocation = 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),
@@ -1619,7 +1625,7 @@
       );
     };
     
-    p5.RendererGL.prototype._worldToScreenPosition = function ({
+    p5.Renderer3D.prototype._worldToScreenLocation = function ({
       point = new p5.Vector(0, 0, 0.5),
       pMatrix,
       vMatrix,
@@ -1642,7 +1648,7 @@
       return new p5.Vector(target[0], target[1], target[2]);
     };
     
-    p5.RendererGL.prototype._screenToWorldPosition = function ({
+    p5.Renderer3D.prototype._screenToWorldLocation = function ({
       point = new p5.Vector(this.width / 2, this.height / 2, 0.5),
       pMatrix,
       vMatrix,
@@ -1672,7 +1678,7 @@
     // ---------------------------------------------------------------------------
     
     fn.mapDirection = function (...args) {
-      return _rendererGL(this)?.mapDirection(...args);
+      return _renderer3D(this)?.mapDirection(...args);
     };
     
     /**
@@ -1687,12 +1693,12 @@
      * @param {p5.Matrix} [opts.pMatrix]
      * @returns {p5.Vector}
      */
-    p5.RendererGL.prototype.mapDirection = function (...args) {
+    p5.Renderer3D.prototype.mapDirection = function (...args) {
       const { mainArg, options } = this._parseTransformArgs(p5.Tree._k, ...args);
       return this._direction(mainArg, options);
     };
     
-    p5.RendererGL.prototype._direction = function (
+    p5.Renderer3D.prototype._direction = function (
       vector = p5.Tree._k,
       {
         from = p5.Tree.EYE,
@@ -1786,7 +1792,7 @@
       return vector;
     };
     
-    p5.RendererGL.prototype._worldToScreenDirection = function (vector, pMatrix) {
+    p5.Renderer3D.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;
@@ -1807,7 +1813,7 @@
       return new p5.Vector(dx, dy, dz);
     };
     
-    p5.RendererGL.prototype._screenToWorldDirection = function (vector, pMatrix) {
+    p5.Renderer3D.prototype._screenToWorldDirection = function (vector, pMatrix) {
       pMatrix = pMatrix ?? this.pMatrix();
     
       let dx = vector.x;
@@ -1831,11 +1837,11 @@
       return this._direction(new p5.Vector(dx, dy, dz), { from: p5.Tree.EYE, to: p5.Tree.WORLD });
     };
     
-    p5.RendererGL.prototype._ndcToScreenDirection = function (vector) {
+    p5.Renderer3D.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) {
+    p5.Renderer3D.prototype._screenToNDCDirection = function (vector) {
       return new p5.Vector(2 * vector.x / this.width, 2 * vector.y / this.height, 2 * vector.z);
     };
     
@@ -1852,13 +1858,13 @@
      * - In orthographic projection, the ratio is constant.
      * - In perspective projection, the ratio depends on eye-space depth.
      *
-     * Requires WEBGL.
+     * Requires 3D renderer.
      *
      * @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);
+      return _renderer3D(this)?.pixelRatio(point);
     };
     
     /**
@@ -1866,7 +1872,7 @@
      * @param {p5.Vector|number[]} [point=p5.Tree.ORIGIN]
      * @returns {number}
      */
-    p5.RendererGL.prototype.pixelRatio = function (point = p5.Tree.ORIGIN) {
+    p5.Renderer3D.prototype.pixelRatio = function (point = p5.Tree.ORIGIN) {
       return this.isOrtho()
         ? Math.abs(this.tPlane() - this.bPlane()) / this.height
         : 2 * Math.abs(
@@ -1899,27 +1905,27 @@
 
     /**
      * Returns a pointer position in *pixel* coordinates from an arbitrary (x, y) pair.
-     * Delegates to the WEBGL renderer.
+     * Delegates to the active 3D 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.
+     * @returns {number[]|undefined} `[x, y]` in pixels, or undefined if no 3D renderer is active.
      */
     fn.pointerPosition = function (...args) {
-      return _rendererGL(this)?.pointerPosition(...args);
+      return _renderer3D(this)?.pointerPosition(...args);
     };
 
     /**
      * Returns the canvas resolution in *pixel* coordinates.
-     * Delegates to the WEBGL renderer.
+     * Delegates to the active 3D renderer.
      *
-     * @returns {number[]|undefined} `[width, height]` in pixels, or undefined if not in WEBGL.
+     * @returns {number[]|undefined} `[width, height]` in pixels, or undefined if no 3D renderer is active.
      */
     fn.resolution = function () {
-      return _rendererGL(this)?.resolution();
+      return _renderer3D(this)?.resolution();
     };
 
     /**
@@ -1932,7 +1938,7 @@
      * @param  {...(number|boolean)} args
      * @returns {number[]} `[x, y]` in pixels (includes pixelDensity scaling).
      */
-    p5.RendererGL.prototype.pointerPosition = function (...args) {
+    p5.Renderer3D.prototype.pointerPosition = function (...args) {
       let pointerX;
       let pointerY;
       let flip = true;
@@ -1952,7 +1958,7 @@
      * Returns the canvas resolution in *pixel* coordinates.
      * @returns {number[]} `[width, height]` in pixels (includes pixelDensity scaling).
      */
-    p5.RendererGL.prototype.resolution = function () {
+    p5.Renderer3D.prototype.resolution = function () {
       const pd = this.pixelDensity();
       return [pd * this.width, pd * this.height];
     };
@@ -1962,11 +1968,51 @@
     // -------------------------------------------------------------------------
     
     fn.axes = function (opts) {
-      _rendererGL(this)?.axes(opts);
+      _renderer3D(this)?.axes(opts);
       return this;
     };
     
-    p5.RendererGL.prototype.axes = function ({
+    /**
+     * Draws 3D reference axes (X, Y, Z) centered at the origin in model space,
+     * using the current stroke settings.
+     *
+     * Each axis can be enabled independently using bitwise flags, and optional
+     * axis labels (X, Y, Z) can be rendered near the positive ends.
+     *
+     * @method axes
+     * @for p5.Renderer3D
+     * @param {Object} [opts] Axes options.
+     * @param {Number} [opts.size=100] Length of each axis in world units.
+     * @param {Array<String>} [opts.colors=['Red','Lime','DodgerBlue']]
+     *        Stroke colors for X, Y, and Z axes respectively.
+     * @param {Number} [opts.bits=p5.Tree.LABELS | p5.Tree.X | p5.Tree.Y | p5.Tree.Z]
+     *        Bitmask controlling which axes and labels are drawn.
+     *
+     * @example
+     * function draw() {
+     *   background(30);
+     *   orbitControl();
+     *   axes({ size: 300 });
+     * }
+     *
+     * @example
+     * // Draw only X and Z axes, no labels
+     * axes({
+     *   size: 200,
+     *   bits: p5.Tree.X | p5.Tree.Z
+     * });
+     *
+     * @example
+     * // Draw full axes in both positive and negative directions
+     * axes({
+     *   size: 150,
+     *   bits: p5.Tree.X | p5.Tree._X |
+     *         p5.Tree.Y | p5.Tree._Y |
+     *         p5.Tree.Z | p5.Tree._Z |
+     *         p5.Tree.LABELS
+     * });
+     */
+    p5.Renderer3D.prototype.axes = function ({
       size = 100,
       colors = ['Red', 'Lime', 'DodgerBlue'],
       bits = p5.Tree.LABELS | p5.Tree.X | p5.Tree.Y | p5.Tree.Z
@@ -2011,51 +2057,40 @@
     };
     
     fn.grid = function (opts) {
-      _rendererGL(this)?.grid(opts);
+      _renderer3D(this)?.grid(opts);
       return this;
     };
     
-    p5.RendererGL.prototype.grid = function ({
+    /**
+     * Draws a simple X/Y reference grid on the Z=0 plane in the current model space.
+     *
+     * The grid is centered at the origin and spans from `-size` to `+size` on both X and Y.
+     * It draws `subdivisions + 1` lines in each direction (including the borders).
+     *
+     * @method grid
+     * @for p5.Renderer3D
+     * @param {Object} [opts] Grid options.
+     * @param {Number} [opts.size=100] Half-extent of the grid in world units.
+     * @param {Number} [opts.subdivisions=10] Number of subdivisions per side (must be >= 1).
+     * @example
+     * function draw() {
+     *   background(30);
+     *   orbitControl();
+     *   grid({ size: 300, subdivisions: 20 });
+     * }
+     */
+    p5.Renderer3D.prototype.grid = function ({
       size = 100,
-      subdivisions = 10,
-      style = p5.Tree.SOLID,
-      weight = 1,
-      minorSubdivisions = 5
+      subdivisions = 10
     } = {}) {
       const p = this._pInst;
-      if (!p) return;
+      if (!p) return;  
+      subdivisions = Math.max(1, subdivisions);
       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);
-        }
+      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();
     };
@@ -2071,7 +2106,7 @@
      * `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.
+     * Requires 3D renderer.
      *
      * @param {object} [opts]
      * @param {p5.Matrix} [opts.mMatrix] Model-space matrix origin to compute (x, y) from.
@@ -2086,7 +2121,7 @@
      * @returns {boolean|undefined}
      */
     fn.mousePicking = function (opts) {
-      return _rendererGL(this)?.mousePicking(opts);
+      return _renderer3D(this)?.mousePicking(opts);
     };
     
     /**
@@ -2096,16 +2131,16 @@
      * `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.
+     * Requires 3D renderer.
      *
      * @param {...any} args
      * @returns {boolean|undefined}
      */
     fn.pointerPicking = function (...args) {
-      return _rendererGL(this)?.pointerPicking(...args);
+      return _renderer3D(this)?.pointerPicking(...args);
     };
     
-    p5.RendererGL.prototype.mousePicking = function ({
+    p5.Renderer3D.prototype.mousePicking = function ({
       mMatrix = this.mMatrix(),
       x,
       y,
@@ -2131,7 +2166,7 @@
      * @param {...any} args
      * @returns {boolean}
      */
-    p5.RendererGL.prototype.pointerPicking = function (...args) {
+    p5.Renderer3D.prototype.pointerPicking = function (...args) {
       let pointerX;
       let pointerY;
       const config = {};
@@ -2193,7 +2228,7 @@
      * @param {number} [opts.radius=100] Radius in current space.
      * @param {number} [opts.detail=50] Segment count.
      */
-    p5.RendererGL.prototype._circle = function ({
+    p5.Renderer3D.prototype._circle = function ({
       filled = false,
       x = this.width / 2,
       y = this.height / 2,
@@ -2245,11 +2280,11 @@
      * @param {p5.Matrix} [opts.pvMatrix] Projection-view matrix override.
      */
     fn.cross = function (opts) {
-      _rendererGL(this)?.cross(opts);
+      _renderer3D(this)?.cross(opts);
       return this;
     };
     
-    p5.RendererGL.prototype.cross = function ({
+    p5.Renderer3D.prototype.cross = function ({
       mMatrix = this.mMatrix(),
       x,
       y,
@@ -2298,11 +2333,11 @@
      * @param {p5.Matrix} [opts.pvMatrix] Projection-view matrix override.
      */
     fn.bullsEye = function (opts) {
-      _rendererGL(this)?.bullsEye(opts);
+      _renderer3D(this)?.bullsEye(opts);
       return this;
     };
     
-    p5.RendererGL.prototype.bullsEye = function ({
+    p5.Renderer3D.prototype.bullsEye = function ({
       mMatrix = this.mMatrix(),
       x,
       y,
@@ -2349,22 +2384,22 @@
     // ---------------------------------------------------------------------------
     
     fn.viewFrustum = function (opts) {
-      _rendererGL(this)?.viewFrustum(opts);
+      _renderer3D(this)?.viewFrustum(opts);
       return this;
     };
     
     /**
-     * Displays a view frustum, either from a pg (p5.Graphics / p5.RendererGL) or from eMatrix/pMatrix.
+     * Displays a view frustum, either from a pg (p5.Graphics / p5.Renderer3D) 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.Renderer3D|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 ({
+    p5.Renderer3D.prototype.viewFrustum = function ({
       vMatrix = this.vMatrix(),
       pg,
       eMatrix = pg?.eMatrix(),
@@ -2495,7 +2530,7 @@
      * @returns {number} One of p5.Tree.VISIBLE, p5.Tree.INVISIBLE, p5.Tree.SEMIVISIBLE.
      */
     fn.visibility = function (...args) {
-      return _rendererGL(this).visibility(...args);
+      return _renderer3D(this).visibility(...args);
     };
     
     /**
@@ -2503,7 +2538,7 @@
      * @returns {Object}
      */
     fn.bounds = function (opts = {}) {
-      return _rendererGL(this).bounds(opts);
+      return _renderer3D(this).bounds(opts);
     };
     
     /**
@@ -2511,7 +2546,7 @@
      * @returns {number}
      */
     fn.distanceToBound = function (...args) {
-      return _rendererGL(this).distanceToBound(...args);
+      return _renderer3D(this).distanceToBound(...args);
     };
     
     /**
@@ -2523,7 +2558,7 @@
      *
      * @private
      */
-    p5.RendererGL.prototype._parseVisibilityArgs = function (...args) {
+    p5.Renderer3D.prototype._parseVisibilityArgs = function (...args) {
       let corner1;
       let corner2;
       let center;
@@ -2592,7 +2627,7 @@
      * @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) {
+    p5.Renderer3D.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))
@@ -2600,7 +2635,7 @@
           : (console.error('[p5.tree] visibility: could not parse query.'), p5.Tree.INVISIBLE));
     };
     
-    p5.RendererGL.prototype._pointVisibility = function (point, bounds = this.bounds()) {
+    p5.Renderer3D.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;
@@ -2609,7 +2644,7 @@
       return p5.Tree.VISIBLE;
     };
     
-    p5.RendererGL.prototype._ballVisibility = function (center, radius, bounds = this.bounds()) {
+    p5.Renderer3D.prototype._ballVisibility = function (center, radius, bounds = this.bounds()) {
       let allInForAllPlanes = true;
       for (const key in bounds) {
         const d = this.distanceToBound(center, key, bounds);
@@ -2619,7 +2654,7 @@
       return allInForAllPlanes ? p5.Tree.VISIBLE : p5.Tree.SEMIVISIBLE;
     };
     
-    p5.RendererGL.prototype._boxVisibility = function (corner1, corner2, bounds = this.bounds()) {
+    p5.Renderer3D.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);
@@ -2654,7 +2689,7 @@
      * @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 ({
+    p5.Renderer3D.prototype.bounds = function ({
       vMatrix,
       eMatrix
     } = {}) {
@@ -2726,7 +2761,7 @@
      * @param {Object} [bounds] Plane equations (defaults to this.bounds()).
      * @returns {number}
      */
-    p5.RendererGL.prototype.distanceToBound = function (...args) {
+    p5.Renderer3D.prototype.distanceToBound = function (...args) {
       let point;
       let key;
       let bounds = this.bounds();