mapspinner 0.1.37 → 0.1.39

package/package.json

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

package/src/gl-render.js

@@ -272,6 +272,72 @@ export async function initMapspinnerRender(gl, opts = {}) {
     return out[0];
   }
 
+  // ===== THC HEIGHT-CACHE BAKE (2026-06-14, NON-DESTRUCTIVE) =====
+  // A separate program renders composeHeight for one tile into an R32F grid (a fullscreen tri; each
+  // fragment = one tile parametric texel). Used FIRST as a readback witness (bake vs procedural
+  // sampleGroundM) to prove the bake matches the geometry; the pool/LRU + the VS-sample switch are
+  // later DAG nodes. _faceFrames mirror terrain.glsl faceFrame() columns (column-major mat3).
+  const THC_BAKE_RES = 130;
+  const _faceFrames = [
+    [0,0,-1, 0,1,0, 1,0,0], [0,0,1, 0,1,0, -1,0,0],
+    [1,0,0, 0,0,-1, 0,1,0], [1,0,0, 0,0,1, 0,-1,0],
+    [1,0,0, 0,1,0, 0,0,1], [-1,0,0, 0,1,0, 0,0,-1],
+  ];
+  let bakeProg=null, bakeTex=null, bakeFbo=null, _bakeBuilding=null; const _bakeUloc=new Map();
+  const BU = n => { let l=_bakeUloc.get(n); if(l===undefined){ l=gl.getUniformLocation(bakeProg,n); _bakeUloc.set(n,l);} return l; };
+  function ensureBake(){
+    if (bakeProg || _bakeBuilding) return;
+    _bakeBuilding = (async () => {
+      try {
+        const bvs = hdr + 'void main(){ vec2 p=vec2((gl_VertexID==1)?3.0:-1.0,(gl_VertexID==2)?3.0:-1.0); gl_Position=vec4(p,0.0,1.0); }';
+        const bfs = hdr + '\n#define _HEIGHTBAKE_\n' + src;
+        const bv=gl.createShader(gl.VERTEX_SHADER); gl.shaderSource(bv,bvs); gl.compileShader(bv);
+        const bf=gl.createShader(gl.FRAGMENT_SHADER); gl.shaderSource(bf,bfs); gl.compileShader(bf);
+        const bp=gl.createProgram(); gl.attachShader(bp,bv); gl.attachShader(bp,bf); gl.linkProgram(bp);
+        await awaitProgramLink(bp, bv, bf, 'bake');
+        const tex=gl.createTexture(); gl.bindTexture(gl.TEXTURE_2D, tex);
+        gl.texStorage2D(gl.TEXTURE_2D, 1, gl.R32F, THC_BAKE_RES, THC_BAKE_RES);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST); gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        const fbo=gl.createFramebuffer(); gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, tex, 0);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        _bakeUloc.clear(); bakeTex=tex; bakeFbo=fbo; bakeProg=bp;
+      } catch(e){ bakeProg=null; try{ if(typeof window!=='undefined') window.__bakeErr=String(e.message||e); }catch(_){} }
+      finally { _bakeBuilding=null; }
+    })();
+  }
+  const bakeVao = gl.createVertexArray();
+  // bake ONE tile into bakeTex + read it back (Float32Array of THC_BAKE_RES^2 heights). Returns null
+  // until the program is built (lazy). NON-DESTRUCTIVE: does not touch the live render path.
+  function bakeTileReadback(face, ox, oy, l, level){
+    if (!bakeProg){ ensureBake(); return null; }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, bakeFbo);
+    gl.viewport(0,0,THC_BAKE_RES,THC_BAKE_RES);
+    gl.useProgram(bakeProg);
+    gl.bindVertexArray(bakeVao);
+    if (_hpfTex){ gl.activeTexture(gl.TEXTURE3); gl.bindTexture(gl.TEXTURE_2D_ARRAY,_hpfTex); gl.uniform1i(BU('hpfPool'),3); }
+    if (_hpfTex2){ gl.activeTexture(gl.TEXTURE5); gl.bindTexture(gl.TEXTURE_2D_ARRAY,_hpfTex2); gl.uniform1i(BU('hpfPool2'),5); }
+    gl.uniform1i(BU('hasHpf'), _hpfTex?1:0);
+    setComposeHeightUniforms(BU);
+    gl.uniform1f(BU('defRadius'), R);
+    gl.uniformMatrix3fv(BU('uBakeFrame'), false, new Float32Array(_faceFrames[face|0]));
+    gl.uniform4f(BU('uBakeOffset'), ox, oy, l, level);
+    gl.uniform1f(BU('uBakeRes'), THC_BAKE_RES);
+    gl.disable(gl.DEPTH_TEST);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    const buf = new Float32Array(THC_BAKE_RES*THC_BAKE_RES*4);
+    gl.readPixels(0,0,THC_BAKE_RES,THC_BAKE_RES, gl.RGBA, gl.FLOAT, buf);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.bindVertexArray(null);
+    const out = new Float32Array(THC_BAKE_RES*THC_BAKE_RES);
+    for (let i=0;i<out.length;i++) out[i]=buf[i*4];
+    let dbg=null; try{ dbg={ offLoc: BU('uBakeOffset')!=null, resLoc: BU('uBakeRes')!=null, frameLoc: BU('uBakeFrame')!=null,
+      offRead: BU('uBakeOffset')?Array.from(gl.getUniform(bakeProg, BU('uBakeOffset'))):null,
+      resRead: BU('uBakeRes')?gl.getUniform(bakeProg, BU('uBakeRes')):null }; }catch(e){ dbg={err:String(e)}; }
+    return { heights: out, res: THC_BAKE_RES, dbg };
+  }
+  if (typeof window !== 'undefined') { window.__thcBakeReadback = bakeTileReadback; window.__thcEnsureBake = ensureBake; }
+
   // FLOAT-LINEAR FORMAT PROBE (NOT a quality tier): OES_texture_float_linear lets the HPF atlas pools
   // filter LINEAR in hardware -> hpfSample collapses to one texture() call. 0 = manual 4-tap fallback.
   const _halfFloatLinearOK = !!gl.getExtension('OES_texture_float_linear') || !!gl.getExtension('OES_texture_half_float_linear');
@@ -286,6 +352,7 @@ export async function initMapspinnerRender(gl, opts = {}) {
     gl.uniform1f(loc('uDetailOverlay'), g('detailOverlay', 6.0));  // perlin-everywhere ELEVATION term in composeHeight -- probe must match the VS or collision diverges
     gl.uniform1f(loc('vtxDetail'),      g('vtxDetail', 1.0));    // DECISIVE: vtxDisplace strength (early-return on 0)
     gl.uniform1f(loc('canyonDepthMul'), g('canyonDepth', 1.0));
+    gl.uniform1f(loc('uVsCheap'),       (typeof window!=='undefined' && window.__vsCheap) ? 1.0 : 0.0);   // VS carve-cost profiling A/B
     gl.uniform1f(loc('uBeachShelfM'),   g('beachShelf', 2400.0));   // land coastal shelf (geometry); probe MUST match render
     gl.uniform1f(loc('cliffAmt'),       g('cliffAmt', 1.0));
     gl.uniform1i(loc('uFloatLinearOK'), _halfFloatLinearOK ? 1 : 0);
@@ -806,6 +873,7 @@ export async function initMapspinnerRender(gl, opts = {}) {
     // literals so the look is unchanged until the user dials a window global.
     const _g = (n,d)=> (typeof window!=='undefined' && window['__'+n]!=null) ? +window['__'+n] : d;
     gl.uniform1f(U('canyonDepthMul'), _g('canyonDepth', 1.0));
+    gl.uniform1f(U('uVsCheap'),       (typeof window!=='undefined' && window.__vsCheap) ? 1.0 : 0.0);   // VS carve-cost profiling A/B
     gl.uniform1f(U('uBeachShelfM'),   _g('beachShelf', 2400.0));   // land coastal shelf (geometry): h<S eased h*h/S = wide beach
     gl.uniform1f(U('uHiFreqCut'),     _g('hiFreqCut', 0.25));   // 0.5->0.25 (2026-06-10 'blotchy' -- see setComposeHeightUniforms)
     gl.uniform1f(U('uVertexAO'),      _g('vertexAO', 1.0));    // per-vertex shading/AO strength (DEFECT 2, 2026-06-06)

package/src/shaders/terrain.glsl

@@ -198,6 +198,7 @@ float riverCarveM(vec3 dir, out float wet){
 float riverCarveM(vec3 dir){ float w; return riverCarveM(dir, w); }
 const float CANYON_INCISE_DEPTH = 1400.0;  // metres at the gorge floor (user 2026-06-02: deepen+widen so canyons visibly sculpt the elevation; was 480m = invisible vs multi-km relief)
 uniform float canyonDepthMul;              // LIVE canyon-depth lever (window.__canyonDepth; 1.0 default)
+uniform float uVsCheap;                     // VS profiling: >0.5 skips all carves in composeHeight (window.__vsCheap; gpuTimer carve-cost A/B)
 // W5: uNrmGain deleted (only fed the removed VS slopeGain).
 uniform float uVertexAO;                   // per-vertex shading/AO strength lever (window.__vertexAO; 1.0 default)
 // SEPARATE WATER SURFACE (user 2026-06-11 'the ocean should be a separate surface'): the same
@@ -389,7 +390,7 @@ highp vec2 faceWarp(highp vec2 p){ return defRadius * tan((p / defRadius) * 0.78
 uniform float uDetailOverlay;   // amplitude lever (user-tuned 6; 0 = off; __detailOverlay)
 uniform float uGrid;             // interior cells per tile edge (GRID=16); for mesh-based vertex normals
 uniform float uNrmStepM;        // lit-normal FD step in metres (150); uniform-fed to defeat FXC constant folding
-#if defined(_VERTEX_) || defined(_PROBE_)
+#if defined(_VERTEX_) || defined(_PROBE_) || defined(_HEIGHTBAKE_)
 highp float broadShapeM(vec3 dir, float reliefMul, float ridgeMul){   // W7: returns metres (~13000) -> highp
   if (hasHpf == 0) return 0.0;
   float mtnAmp = 1.0;   // mountain-amplitude (was a window.__mtnAmp uniform; inlined at neutral 1.0)
@@ -643,6 +644,10 @@ highp float composeHeight(vec3 dir0, highp vec2 faceLocal, float tileM){   // W7
   // Shore-gated (fades in over the first 250m of land) so the coastline and the flat water planes are
   // untouched and no noise islets pop offshore. The VS FD lit-normal picks it up automatically.
   h += detailFbm(dir0) * uDetailOverlay * 30.0 * step(0.0, h);
+  // VS-PROFILING GATE (2026-06-14): uVsCheap>0.5 returns BEFORE all the carves (valley/lake/river/
+  // canyon/cliff/dune) so gpuTimer can A/B the per-vertex CARVE cost (the doctrine's suspected
+  // dominant term). Transient profiling toggle (window.__vsCheap); 0 = full path (default).
+  if (uVsCheap > 0.5) return h;
   // FLAT-AREA VALLEY NETWORKS + LAKES (user 2026-06-13): incised valley systems in low-relief
   // plains. Replaces the old noise bumps with a ridge-field valley network for connected
   // linear depressions and lakes that fill the valley bottoms. Fades to zero by reliefMul ~0.5.
@@ -2224,3 +2229,22 @@ void main(){
     probeOut = vec4(h, 0.0, 0.0, 1.0);
 }
 #endif
+
+#ifdef _HEIGHTBAKE_
+// THC HEIGHT-CACHE BAKE (2026-06-14): render ONE tile's composeHeight into a height-pool texel grid.
+// Each fragment = one parametric (u,v) of the tile; the dir + faceLocal mapping is IDENTICAL to the
+// mesh VS (faceWarp(vertex.xy*defOffset.z+defOffset.xy), normalize(frame*vec3(faceLocal,defRadius)))
+// so the baked height matches the procedural geometry exactly. NON-DESTRUCTIVE: this is a separate
+// program; the live VS still computes composeHeight until thc-vs-sample switches it to a pool sample.
+uniform mat3 uBakeFrame;    // face-local -> world for this tile's face (== faceFrame(face))
+uniform vec4 uBakeOffset;   // tile (ox, oy, l, level) face-local metres (== iOffset)
+uniform float uBakeRes;     // bake grid resolution (texels per edge)
+out vec4 bakeOut;
+void main(){
+    highp vec2 uv = (gl_FragCoord.xy - 0.5) / max(uBakeRes - 1.0, 1.0);   // texel -> parametric [0,1]
+    highp vec2 faceLocal = faceWarp(uv * uBakeOffset.z + uBakeOffset.xy);
+    highp vec3 dir0 = normalize(uBakeFrame * vec3(faceLocal, defRadius));
+    highp float h = composeHeight(dir0, faceLocal, uBakeOffset.z);
+    bakeOut = vec4(h, 0.0, 0.0, 1.0);
+}
+#endif