mapspinner 0.1.34 → 0.1.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mapspinner",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "WebGL2 Earth-scale terrain rendering SDK for interactive globe applications",
   "main": "src/index.js",
   "exports": {

package/src/gl-render.js

@@ -49,7 +49,7 @@ export async function initMapspinnerRender(gl, opts = {}) {
   // (-52%) and tris/quad 1152->512 (-55%), so the per-vertex 14-oct broadShapeM VS (browser-9: 95% of
   // the low-alt frame) runs on ~half the vertices. median scales ~24/16 -> ~3.6px, far closer to the
   // band; the fine relief is carried per-pixel by the FS dFdx normal, not the mesh tessellation.
-  const GRID = opts.gridMeshSize || 11;    // mesh quads per edge. 16->11 (user 2026-06-14): FPS is TRIANGLE-THROUGHPUT bound, not broadShapeM ALU (octMax 12->3 left frame time flat; GRID is ~linear). GRID 8 was faster (-50%) but made BIOME CROSSOVER LINES JAGGED (climate varying interpolated across coarse triangles steps along edges) -- reverted to 11 (-37%). Proper fix to reclaim GRID 8 = per-pixel biome sampling in the FS. Override via ?grid=N.
+  const GRID = opts.gridMeshSize || 8;    // mesh quads per edge. FPS is TRIANGLE/VERTEX-throughput bound (not ALU). 16->11->8 (user 2026-06-14 144fps push): GRID 8 reclaimed once the biome bands were WARPED (warpN, no longer straight contours) and the relief-faceting (dFdx(vH)) was removed, so the earlier GRID-8 jaggedness is gone. Override via ?grid=N.
   // Expose the LIVE mesh grid so screen-space-error diagnostics (planet.html __diag.pxPerPoly)
   // divide by the real polys/tile instead of a stale literal. Any future GRID change self-corrects
   // the metric (the 24->16 lever left pxPerPoly defaulting to 24 = 1.5x wrong band fraction).
@@ -569,6 +569,13 @@ export async function initMapspinnerRender(gl, opts = {}) {
   const vbo=gl.createBuffer(); gl.bindBuffer(gl.ARRAY_BUFFER,vbo); gl.bufferData(gl.ARRAY_BUFFER,verts,gl.STATIC_DRAW);
   const ibo=gl.createBuffer(); gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER,ibo); gl.bufferData(gl.ELEMENT_ARRAY_BUFFER,indices,gl.STATIC_DRAW);
   const instBuf=gl.createBuffer();   // per-instance [ox,oy,l,level,face] (filled per frame in render())
+  // DATA-CONTINUITY CACHE (2026-06-14): terrain + water get their OWN persistent instance buffers so
+  // neither clobbers the other (the shared-buffer clobber forced a re-upload every frame and was the
+  // root of the prior 'water drawn as terrain' regression). On a STATIC frame (same quads array object)
+  // the instance data is identical -> skip the Float32Array build + bufferData + water dedup Set-loop
+  // and just rebind+draw. Pure CPU/GC win (GPU is vertex-bound, the upload is off the critical path).
+  const instBufWater=gl.createBuffer();
+  let _instQuadsRef=null, _instWaterRef=null, _instWaterN=0;
 
   // per-face local->world (cube face -> sphere local frame). Column-major mat3 packed
   // into a Float32Array(9). Matches localToWorld3 convention:
@@ -892,14 +899,19 @@ export async function initMapspinnerRender(gl, opts = {}) {
     // h = composeHeight(dir) for each vertex.
     const FLOATS = 5;   // [ox,oy,l,level,face]
     if (n > 0) {
-      const inst = new Float32Array(n * FLOATS);
-      for (let i = 0; i < n; i++) {
-        const q = quads[i].quad;
-        inst[i*FLOATS+0] = q.ox; inst[i*FLOATS+1] = q.oy; inst[i*FLOATS+2] = q.l; inst[i*FLOATS+3] = q.level;
-        inst[i*FLOATS+4] = quads[i].face;
-      }
+      // STATIC-FRAME SKIP: only rebuild + re-upload the instance data when the quad SET changed (the
+      // orchestrator passes the SAME quads array object on a static camera, a fresh array on rebuild).
+      const _dirty = (quads !== _instQuadsRef);
       gl.bindBuffer(gl.ARRAY_BUFFER, instBuf);
-      gl.bufferData(gl.ARRAY_BUFFER, inst, gl.DYNAMIC_DRAW);
+      if (_dirty) {
+        const inst = new Float32Array(n * FLOATS);
+        for (let i = 0; i < n; i++) {
+          const q = quads[i].quad;
+          inst[i*FLOATS+0] = q.ox; inst[i*FLOATS+1] = q.oy; inst[i*FLOATS+2] = q.l; inst[i*FLOATS+3] = q.level;
+          inst[i*FLOATS+4] = quads[i].face;
+        }
+        gl.bufferData(gl.ARRAY_BUFFER, inst, gl.DYNAMIC_DRAW);
+      }
       const STRIDE = FLOATS * 4;
       gl.enableVertexAttribArray(1); gl.vertexAttribPointer(1, 4, gl.FLOAT, false, STRIDE, 0);          gl.vertexAttribDivisor(1, 1);  // iOffset
       gl.enableVertexAttribArray(2); gl.vertexAttribPointer(2, 1, gl.FLOAT, false, STRIDE, 4 * 4);      gl.vertexAttribDivisor(2, 1);  // iFace
@@ -926,17 +938,24 @@ export async function initMapspinnerRender(gl, opts = {}) {
         // (~1.6km) sag ~5cm, far under any visible bathymetry, still ~16-64x fewer water verts
         // than the deep terrain leaves.
         const WCAP = 9;
-        const seen = new Set(); const wl = [];
-        for (let i = 0; i < n; i++) {
-          const q = quads[i].quad; let ox = q.ox, oy = q.oy, l = q.l, lv = q.level;
-          if (lv > WCAP) { const A = l * Math.pow(2, lv - WCAP); ox = Math.floor(ox / A) * A; oy = Math.floor(oy / A) * A; l = A; lv = WCAP; }
-          const key = quads[i].face + ':' + ox + ':' + oy + ':' + l;
-          if (seen.has(key)) continue; seen.add(key);
-          wl.push(ox, oy, l, lv, quads[i].face);
+        // OWN persistent buffer (instBufWater) + static-frame skip: on an unchanged quad set, reuse the
+        // cached water instances (skip the dedup Set-loop + Float32Array + bufferData). Separate buffer
+        // means the terrain pass never clobbers it (the prior water-as-terrain regression root).
+        gl.bindBuffer(gl.ARRAY_BUFFER, instBufWater);
+        if (_dirty || quads !== _instWaterRef) {
+          const seen = new Set(); const wl = [];
+          for (let i = 0; i < n; i++) {
+            const q = quads[i].quad; let ox = q.ox, oy = q.oy, l = q.l, lv = q.level;
+            if (lv > WCAP) { const A = l * Math.pow(2, lv - WCAP); ox = Math.floor(ox / A) * A; oy = Math.floor(oy / A) * A; l = A; lv = WCAP; }
+            const key = quads[i].face + ':' + ox + ':' + oy + ':' + l;
+            if (seen.has(key)) continue; seen.add(key);
+            wl.push(ox, oy, l, lv, quads[i].face);
+          }
+          _instWaterN = wl.length / FLOATS;
+          gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(wl), gl.DYNAMIC_DRAW);
+          _instWaterRef = quads;
         }
-        const wn = wl.length / FLOATS;
-        gl.bindBuffer(gl.ARRAY_BUFFER, instBuf);
-        gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(wl), gl.DYNAMIC_DRAW);
+        const wn = _instWaterN;
         gl.enableVertexAttribArray(1); gl.vertexAttribPointer(1, 4, gl.FLOAT, false, STRIDE, 0);     gl.vertexAttribDivisor(1, 1);
         gl.enableVertexAttribArray(2); gl.vertexAttribPointer(2, 1, gl.FLOAT, false, STRIDE, 4 * 4); gl.vertexAttribDivisor(2, 1);
         if (_uw) {
@@ -954,6 +973,8 @@ export async function initMapspinnerRender(gl, opts = {}) {
         gl.disable(gl.BLEND);
         if (typeof window !== 'undefined') window.__lastWaterQuads = wn;
       }
+      _instQuadsRef = quads;   // mark this quad set uploaded; next frame with the same array skips the rebuild
+      if (typeof window !== 'undefined') window.__instUploads = (window.__instUploads | 0) + (_dirty ? 1 : 0);
     }
     if (typeof window !== 'undefined') window.__lastDrawCalls = (n > 0) ? 2 : 0;
     return 0;   // glError is checked via checkGlError() once per frame after quadtree (CPU/GPU pipelining)

package/src/planet-orchestrator.js

@@ -177,7 +177,7 @@ export async function initMapspinnerPlanet(gl, opts = {}) {
   // count (orbit 860->20, lowalt 1272->328). 1.0 is the calibrated default; override live
   // via window.__splitFactor.
   const splitFactor = opts.splitFactor ?? 1.0;
-  const gridMeshSize = opts.gridMeshSize || 11;   // 16->11 FPS lever (triangle-throughput bound, not ALU; GRID 8 jagged biome crossovers, see gl-render.js GRID)
+  const gridMeshSize = opts.gridMeshSize || 8;   // 16->11 FPS lever (triangle-throughput bound, not ALU; GRID 8 jagged biome crossovers, see gl-render.js GRID)
 
   gl.getExtension('EXT_color_buffer_float');   // RGBA32F atlas render targets
   // OES_texture_float_linear lets the driver LINEAR-filter the RGBA32F HPF/elevation textures. When

package/src/shaders/terrain.glsl

@@ -964,20 +964,24 @@ void main() {
         // so it never drops below the mesh cell (would re-alias) nor exceeds ~1/3 the tile.
         highp float nStepM = (uNrmStepM > 0.0) ? uNrmStepM : 300.0;
         highp float duP = clamp(nStepM / max(defOffset.z, 1.0), 1.0 / ((uGrid > 0.0) ? uGrid : 16.0), 0.34);
-        highp float hPU = 0.0, hMU = 0.0, hPV = 0.0, hMV = 0.0;
-        highp vec3 dPU = dir0, dMU = dir0, dPV = dir0, dMV = dir0;
-        int fdIters = (uGrid >= 0.0) ? 4 : 1;   // 4 offset taps; runtime-bounded (FXC unroll-defeat, see uOctMax)
+        // 3-TAP FORWARD (FPS push 2026-06-14: target 144fps): center + 2 FORWARD offsets, NOT the 5-tap
+        // central. The central was added for jaggedness, but the actual jaggedness root was the dFdx(vH)
+        // relief term (now removed) -- at the LOW-PASS step (duP ~300m >> vertex spacing) the forward vs
+        // central asymmetry is negligible while it costs 3 composeHeight/vertex instead of 5 (-40% of the
+        // dominant VS cost). Still captures vtxDisplace (faceWarp shifts both dir+faceLocal per tap).
+        highp float hPU = 0.0, hPV = 0.0;
+        highp vec3 dPU = dir0, dPV = dir0;
+        int fdIters = (uGrid >= 0.0) ? 2 : 1;   // 2 forward offset taps (+ center hN0) = 3-tap normal; runtime-bounded (FXC unroll-defeat)
         for (int i = 0; i < fdIters; i++) {
-            highp vec2 off = (i == 0) ? vec2(duP, 0.0) : (i == 1) ? vec2(-duP, 0.0) : (i == 2) ? vec2(0.0, duP) : vec2(0.0, -duP);
+            highp vec2 off = (i == 0) ? vec2(duP, 0.0) : vec2(0.0, duP);
             highp vec2 fl = faceWarp((vertex.xy + off) * defOffset.z + defOffset.xy);
             highp vec3 dd = normalize(defLocalToWorld * vec3(fl, defRadius));
             highp float hh = composeHeight(dd, fl, defOffset.z);
-            if (i == 0) { hPU = hh; dPU = dd; } else if (i == 1) { hMU = hh; dMU = dd; }
-            else if (i == 2) { hPV = hh; dPV = dd; } else { hMV = hh; dMV = dd; }
+            if (i == 0) { hPU = hh; dPU = dd; } else { hPV = hh; dPV = dd; }
         }
-        highp vec3 wPU = dPU * (defRadius + hPU), wMU = dMU * (defRadius + hMU);
-        highp vec3 wPV = dPV * (defRadius + hPV), wMV = dMV * (defRadius + hMV);
-        vN = normalize(cross(wPU - wMU, wPV - wMV));
+        highp vec3 wC = dir0 * (defRadius + hN0);
+        highp vec3 wU = dPU * (defRadius + hPU), wV = dPV * (defRadius + hPV);
+        vN = normalize(cross(wU - wC, wV - wC));
         if (dot(vN, dir0) < 0.0) vN = -vN;   // keep it outward (terrain has no overhangs)
     }
     highp float h = hN0;