Merge pull request #9271 from Srinidhi444/feat/keep-connections

feat: introduce KEEP_CONNECTIONS and deprecate FLAT

Author: davepagurek

src/core/constants.js

@@ -1131,12 +1131,22 @@ export const CLAMP = 'clamp';
 export const MIRROR = 'mirror';
 
 // WEBGL GEOMETRY SHADING
+
+/**
+ * @typedef {'keep_connections'} KEEP_CONNECTIONS
+ * @property {KEEP_CONNECTIONS} KEEP_CONNECTIONS
+ * @final
+ */
+export const KEEP_CONNECTIONS = 'keep_connections';
+
 /**
- * @typedef {'flat'} FLAT
+ * @typedef {'keep_connections'} FLAT
  * @property {FLAT} FLAT
  * @final
+ * @deprecated Use `KEEP_CONNECTIONS` instead. May be removed in p5.js 3.0.
  */
-export const FLAT = 'flat';
+export const FLAT = KEEP_CONNECTIONS;
+
 /**
  * @typedef {'smooth'} SMOOTH
  * @property {SMOOTH} SMOOTH

src/webgl/p5.Geometry.js

@@ -919,20 +919,28 @@ class Geometry {
    * <a href="#/p5.Geometry/vertexNormals">myGeometry.vertexNormals</a> array.
    *
    * The first parameter, `shadingType`, is optional. Passing the constant
-   * `FLAT`, as in `myGeometry.computeNormals(FLAT)`, provides neighboring
-   * faces with their own copies of the vertices they share. Surfaces appear
-   * tiled with flat shading. Passing the constant `SMOOTH`, as in
-   * `myGeometry.computeNormals(SMOOTH)`, makes neighboring faces reuse their
-   * shared vertices. Surfaces appear smoother with smooth shading. By
-   * default, `shadingType` is `FLAT`.
+   * `KEEP_CONNECTIONS`, as in `myGeometry.computeNormals(KEEP_CONNECTIONS)`,
+   * preserves the geometry's existing vertex connections. Each vertex normal
+   * is calculated by averaging the face normals of its connected faces.
+   * This may produce smooth transitions between connected faces rather
+   * than true flat shading.
+   *
+   * Passing the constant `SMOOTH`, as in
+   * `myGeometry.computeNormals(SMOOTH)`, calculates smooth normals by
+   * grouping vertices with approximately matching positions, without
+   * modifying the original vertices or their attributes.
+   *
+   * The constant `FLAT` is deprecated and behaves identically to
+   * `KEEP_CONNECTIONS`. It is retained for backward compatibility.
+   * By default, `shadingType` is `KEEP_CONNECTIONS`.
    *
    * The second parameter, `options`, is also optional. If an object with a
    * `roundToPrecision` property is passed, as in
    * `myGeometry.computeNormals(SMOOTH, { roundToPrecision: 5 })`, it sets the
    * number of decimal places to use for calculations. By default,
    * `roundToPrecision` uses 3 decimal places.
    *
-   * @param {(FLAT|SMOOTH)} [shadingType=FLAT] shading type. either FLAT or SMOOTH. Defaults to `FLAT`.
+   * @param {(KEEP_CONNECTIONS|SMOOTH)} [shadingType=KEEP_CONNECTIONS] shading type. Defaults to `KEEP_CONNECTIONS`.
    * @param {Object} [options] shading options.
    * @chainable
    *
@@ -1055,8 +1063,8 @@ class Geometry {
    *   // Create a p5.Geometry object.
    *   myGeometry = buildGeometry(createShape);
    *
-   *   // Compute normals using default (FLAT) shading.
-   *   myGeometry.computeNormals(FLAT);
+   *   // Compute normals while preserving existing vertex connections.
+   *   myGeometry.computeNormals(KEEP_CONNECTIONS);
    *
    *   describe('A white, helical structure drawn on a dark gray background. Its faces appear faceted.');
    * }
@@ -1191,7 +1199,7 @@ class Geometry {
    *   endShape();
    * }
    */
-  computeNormals(shadingType = constants.FLAT, { roundToPrecision = 3 } = {}) {
+  computeNormals(shadingType = constants.KEEP_CONNECTIONS, { roundToPrecision = 3 } = {}) {
     const vertexNormals = this.vertexNormals;
     const vertices = this.vertices;
     const faces = this.faces;

test/unit/webgl/p5.Geometry.js

@@ -47,6 +47,64 @@ suite('p5.Geometry', function () {
       expect(geom.uvs).toEqual(originalUvs);
       expect(geom.vertexNormals[0]).toEqual(geom.vertexNormals[3]);
     });
+    test('KEEP_CONNECTIONS preserves the existing FLAT behavior', function () {
+      const createGeometry = () => {
+        const geom = new p5.Geometry();
+
+        geom.vertices.push(
+          myp5.createVector(0, 0, 0),
+          myp5.createVector(1, 0, 0),
+          myp5.createVector(0, 1, 0),
+          myp5.createVector(0, 0, 1)
+        );
+
+        geom.faces.push(
+          [0, 1, 2],
+          [0, 3, 1]
+        );
+
+        return geom;
+      };
+
+      const flatGeom = createGeometry();
+      const keepConnectionsGeom = createGeometry();
+      const defaultGeom = createGeometry();
+
+      flatGeom.computeNormals(myp5.FLAT);
+      keepConnectionsGeom.computeNormals(myp5.KEEP_CONNECTIONS);
+      defaultGeom.computeNormals();
+
+      // FLAT and KEEP_CONNECTIONS should produce identical normals.
+      expect(flatGeom.vertexNormals).toEqual(
+        keepConnectionsGeom.vertexNormals
+      );
+
+      // Default behavior should match KEEP_CONNECTIONS.
+      expect(defaultGeom.vertexNormals).toEqual(
+        keepConnectionsGeom.vertexNormals
+      );
+
+      // Vertex connections should remain unchanged.
+      for (const geom of [flatGeom, keepConnectionsGeom, defaultGeom]) {
+        expect(geom.vertices.length).toBe(4);
+        expect(geom.faces).toEqual([
+          [0, 1, 2],
+          [0, 3, 1]
+        ]);
+        expect(geom.vertexNormals.length).toBe(4);
+      }
+
+      // Shared vertices should have averaged face normals.
+      const expected = 1 / Math.sqrt(2);
+
+      for (const index of [0, 1]) {
+        const normal = keepConnectionsGeom.vertexNormals[index];
+
+        expect(normal.x).toBeCloseTo(0, 5);
+        expect(normal.y).toBeCloseTo(expected, 5);
+        expect(normal.z).toBeCloseTo(expected, 5);
+      }
+    });
   });
 
   suite('computeTangents', function () {