ugly-game 0.5.8 → 0.5.9

package/dist/gpuShadow.d.ts

@@ -52,9 +52,21 @@ export declare class GpuShadowRenderer {
         camVisible: number;
         lightVisible: number;
     };
+    private hizPipe;
+    private hizBGL;
+    private hizTex;
+    private hizView;
+    private hizParam;
+    private hizW;
+    private hizH;
+    private hizReady;
+    private occView;
     constructor(device: GPUDevice, format: GPUTextureFormat);
     private makeCullBuf;
+    private cullBG;
     private makeCullResources;
+    /** (Re)create the coarse Hi-Z for a `w×h` depth target and rebind the cull groups to it. Idempotent per size. */
+    private ensureHiZ;
     private scratch;
     private fill;
     private makeBindGroups;
@@ -65,10 +77,16 @@ export declare class GpuShadowRenderer {
     updateInstances(instances: CubeInstance[]): void;
     /** Translucent overlay cubes drawn over the opaque scene each frame; `emissive` carries per-cube alpha. */
     updateOverlay(instances: CubeInstance[]): void;
-    /** Write a frustum's cull uniform: 6 Gribb-Hartmann planes from `vp` + the live instance count. */
+    /** Write a frustum's cull uniform: 6 planes + count + this frustum's VP + occlusion params (occ on the camera pass). */
     private writeCull;
-    /** camVP/lightVP: column-major Float32Array(16). sunDir: travel direction. */
-    frame(enc: GPUCommandEncoder, colorView: GPUTextureView, sceneDepth: GPUTextureView, camVP: Float32Array, lightVP: Float32Array, sunDir: [number, number, number], sunCol: [number, number, number], ambient: number, load?: boolean): void;
+    /** camVP/lightVP: column-major Float32Array(16). sunDir: travel direction. Pass `occlusion` (the depth target +
+     *  its size) to enable Hi-Z occlusion culling on the camera pass — the renderer rebuilds a coarse Hi-Z from that
+     *  depth each frame and the NEXT frame's cull uses it (hole-free: the first frame + any resize skip occlusion). */
+    frame(enc: GPUCommandEncoder, colorView: GPUTextureView, sceneDepth: GPUTextureView, camVP: Float32Array, lightVP: Float32Array, sunDir: [number, number, number], sunCol: [number, number, number], ambient: number, load?: boolean, occlusion?: {
+        depth: GPUTextureView;
+        w: number;
+        h: number;
+    }): void;
     /** Read back the last frame's GPU cull result (camera-visible, light-visible). Does its OWN copy+submit so it's
      *  safe to call from a live render loop (no per-frame readback cost, no race with the ongoing frames). IR/tests. */
     readCullStats(): Promise<{

package/dist/gpuShadow.js

@@ -77,14 +77,25 @@ fn hsv(hh: f32) -> vec3<f32> {
 // instance quaternion). This is exact for any size/aspect/rotation — critical because a bounding SPHERE from the
 // centre wrongly culls a big flat cube (a ground plane whose centre sits far behind the camera while the ground
 // underfoot is plainly in view). Mirrors gpuDriven.ts; validated against a CPU box-vs-plane oracle.
+// OCCLUSION CULLING (Hi-Z). After the frustum test, an in-frustum cube is ALSO dropped if it's fully hidden behind
+// nearer geometry. `hiz` is a coarse MAX-depth buffer (each texel = the farthest visible NDC depth over its block)
+// built from the PREVIOUS frame's depth. A cube is occluded iff its nearest corner is behind the farthest occluder
+// across its whole screen footprint. Using last frame's depth + a coarse buffer makes this HOLE-FREE by
+// construction: a newly-disoccluded area has far/cleared depth so nothing there is culled — the worst case is
+// under-culling for one frame, never a false cull. occ.x toggles it (camera pass only; the shadow pass never
+// occludes — an off-screen occluder still casts a shadow into view). occ.yz = hiz dims, occ.w = pixels/texel.
 const CULL_WGSL = /* wgsl */ `
 struct Inst { pos: vec4<f32>, scl: vec4<f32>, rot: vec4<f32> };
 struct Args { vc: u32, ic: atomic<u32>, fv: u32, fi: u32 };
-struct CullCam { planes: array<vec4<f32>, 6>, cnt: vec4<f32> };   // cnt.x = instance count
+struct CullCam {
+  planes: array<vec4<f32>, 6>, cnt: vec4<f32>,   // cnt.x = instance count
+  camVP: mat4x4<f32>, occ: vec4<f32>,            // occ.x = occlusion on · occ.yz = hiz w,h · occ.w = downscale
+};
 @group(0) @binding(0) var<storage, read> insts: array<Inst>;
 @group(0) @binding(1) var<storage, read_write> args: Args;
 @group(0) @binding(2) var<storage, read_write> visible: array<u32>;
 @group(0) @binding(3) var<uniform> cc: CullCam;
+@group(0) @binding(4) var hiz: texture_2d<f32>;
 fn qr(q: vec4<f32>, v: vec3<f32>) -> vec3<f32> { let t = 2.0 * cross(q.xyz, v); return v + q.w * t + cross(q.xyz, t); }
 @compute @workgroup_size(${CULL_WG})
 fn cull(@builtin(global_invocation_id) gid: vec3<u32>) {
@@ -101,10 +112,65 @@ fn cull(@builtin(global_invocation_id) gid: vec3<u32>) {
     let e = abs(dot(pl.xyz, bx)) + abs(dot(pl.xyz, by)) + abs(dot(pl.xyz, bz));   // box half-width along the normal
     if (dot(pl.xyz, c) + pl.w < -e) { return; }
   }
+  // ── Hi-Z occlusion (camera pass only) ──
+  if (cc.occ.x > 0.5) {
+    var mn = vec2<f32>(1e9, 1e9);
+    var mx = vec2<f32>(-1e9, -1e9);
+    var nearZ = 1e9;
+    var ok = true;
+    for (var ci = 0u; ci < 8u; ci++) {
+      let s = vec3<f32>(select(-1.0, 1.0, (ci & 1u) != 0u), select(-1.0, 1.0, (ci & 2u) != 0u), select(-1.0, 1.0, (ci & 4u) != 0u));
+      let corner = c + bx * s.x + by * s.y + bz * s.z;
+      let clip = cc.camVP * vec4<f32>(corner, 1.0);
+      if (clip.w <= 0.0) { ok = false; break; }        // a corner at/behind the eye → don't occlusion-cull (keep)
+      let ndc = clip.xyz / clip.w;
+      let uv = ndc.xy * vec2<f32>(0.5, -0.5) + vec2<f32>(0.5, 0.5);
+      mn = min(mn, uv); mx = max(mx, uv);
+      nearZ = min(nearZ, ndc.z);
+    }
+    if (ok && nearZ >= 0.0) {
+      let dim = vec2<f32>(cc.occ.y, cc.occ.z);
+      let t0 = vec2<i32>(floor(clamp(mn, vec2<f32>(0.0), vec2<f32>(1.0)) * dim));
+      let t1 = vec2<i32>(floor(clamp(mx, vec2<f32>(0.0), vec2<f32>(1.0)) * dim));
+      // only query a bounded footprint; a huge on-screen box just isn't occlusion-tested (kept)
+      if (t1.x - t0.x <= 8 && t1.y - t0.y <= 8) {
+        var farOccluder = 0.0;                          // MAX over the footprint of the coarse max-depth
+        for (var y = t0.y; y <= t1.y; y++) {
+          for (var x = t0.x; x <= t1.x; x++) {
+            farOccluder = max(farOccluder, textureLoad(hiz, vec2<i32>(x, y), 0).r);
+          }
+        }
+        if (nearZ > farOccluder) { return; }            // behind the farthest occluder everywhere → occluded
+      }
+    }
+  }
   let slot = atomicAdd(&args.ic, 1u);
   visible[slot] = i;
 }
 `;
+// Hi-Z BUILD: max-reduce the previous frame's depth (a sampleable depth texture) into a coarse R32float buffer —
+// each output texel = the FARTHEST (max) NDC depth over its `down`×`down` source block, so "cube behind this" is a
+// safe occlusion test. depth24plus reads as a depth texture; textureLoad returns the stored [0,1] depth.
+const HIZ_WGSL = /* wgsl */ `
+@group(0) @binding(0) var srcDepth: texture_depth_2d;
+@group(0) @binding(1) var dst: texture_storage_2d<r32float, write>;
+struct P { dim: vec4<u32> };   // dim.xy = dst size, dim.zw = src size
+@group(0) @binding(2) var<uniform> p: P;
+@compute @workgroup_size(8, 8)
+fn build(@builtin(global_invocation_id) gid: vec3<u32>) {
+  if (gid.x >= p.dim.x || gid.y >= p.dim.y) { return; }
+  let down = 8u;
+  var mx = 0.0;
+  for (var dy = 0u; dy < down; dy++) {
+    for (var dx = 0u; dx < down; dx++) {
+      let sx = gid.x * down + dx; let sy = gid.y * down + dy;
+      if (sx < p.dim.z && sy < p.dim.w) { mx = max(mx, textureLoad(srcDepth, vec2<i32>(i32(sx), i32(sy)), 0)); }
+    }
+  }
+  textureStore(dst, vec2<i32>(i32(gid.x), i32(gid.y)), vec4<f32>(mx, 0.0, 0.0, 1.0));
+}
+`;
+const HIZ_DOWN = 8; // source pixels per Hi-Z texel (coarse ⇒ conservative, cheap)
 const SHADOW_WGSL = COMMON_WGSL + /* wgsl */ `
 @group(0) @binding(2) var<storage, read> vis: array<u32>;
 @vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> @builtin(position) vec4<f32> {
@@ -232,6 +298,16 @@ export class GpuShadowRenderer {
     statsBuf; // readback: [camVisible, lightVisible] for the IR/tests
     /** Last frame's visible counts (main-pass camera cull, shadow-pass light cull) + total — for IR/telemetry. */
     lastCull = { total: 0, camVisible: 0, lightVisible: 0 };
+    // Hi-Z OCCLUSION: a coarse max-depth buffer rebuilt from each frame's depth, sampled by next frame's camera cull.
+    hizPipe;
+    hizBGL;
+    hizTex;
+    hizView;
+    hizParam;
+    hizW = 0;
+    hizH = 0;
+    hizReady = false; // a Hi-Z from a prior frame exists → safe to occlusion-test (false on frame 1 + resize)
+    occView; // the texture bound at cull binding 4 (a 1×1 dummy until occlusion is used)
     constructor(device, format) {
         this.device = device;
         this.camBuf = device.createBuffer({ size: this.cam.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
@@ -293,39 +369,71 @@ export class GpuShadowRenderer {
                 { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'read-only-storage' } }, // insts
                 { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } }, // args (atomic ic)
                 { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } }, // visible list
-                { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'uniform' } }, // planes + count
+                { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'uniform' } }, // planes + count + camVP + occ
+                { binding: 4, visibility: GPUShaderStage.COMPUTE, texture: { sampleType: 'unfilterable-float' } }, // Hi-Z (dummy until occlusion is used)
             ] });
         this.cullPipe = device.createComputePipeline({
             layout: device.createPipelineLayout({ bindGroupLayouts: [this.cullBGL] }),
             compute: { module: cullMod, entryPoint: 'cull' },
         });
+        // Hi-Z occlusion build pipeline + a 1×1 dummy Hi-Z (bound when occlusion is off, never sampled)
+        const hizMod = device.createShaderModule({ code: HIZ_WGSL });
+        this.hizBGL = device.createBindGroupLayout({ entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, texture: { sampleType: 'depth' } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, storageTexture: { access: 'write-only', format: 'r32float' } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'uniform' } },
+            ] });
+        this.hizPipe = device.createComputePipeline({
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.hizBGL] }),
+            compute: { module: hizMod, entryPoint: 'build' },
+        });
+        this.hizParam = device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        const dummy = device.createTexture({ size: [1, 1], format: 'r32float', usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING });
+        this.occView = dummy.createView();
     }
     // One frustum's cull resources: indirect args (drawIndirect), a compacted visible-index list sized to the
-    // instance capacity, and a small uniform holding the 6 planes + the live instance count.
+    // instance capacity, and a uniform holding the 6 planes + instance count + camVP + occlusion params.
     makeCullBuf() {
         const d = this.device;
         const args = d.createBuffer({ size: 4 * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC });
         const vis = d.createBuffer({ size: Math.max(1, this.cap) * 4, usage: GPUBufferUsage.STORAGE });
-        const cull = d.createBuffer({ size: 6 * 16 + 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
-        const bg = d.createBindGroup({ layout: this.cullBGL, entries: [
+        const cull = d.createBuffer({ size: 6 * 16 + 16 + 64 + 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST }); // planes+cnt+camVP+occ = 192
+        return { args, vis, cull };
+    }
+    cullBG(args, vis, cull) {
+        return this.device.createBindGroup({ layout: this.cullBGL, entries: [
                 { binding: 0, resource: { buffer: this.instBuf } }, { binding: 1, resource: { buffer: args } },
-                { binding: 2, resource: { buffer: vis } }, { binding: 3, resource: { buffer: cull } }
+                { binding: 2, resource: { buffer: vis } }, { binding: 3, resource: { buffer: cull } },
+                { binding: 4, resource: this.occView }
             ] });
-        return { args, vis, cull, bg };
     }
     makeCullResources() {
         const cam = this.makeCullBuf();
         this.camArgs = cam.args;
         this.camVis = cam.vis;
         this.camCull = cam.cull;
-        this.camCullBG = cam.bg;
         const lit = this.makeCullBuf();
         this.lightArgs = lit.args;
         this.lightVis = lit.vis;
         this.lightCull = lit.cull;
-        this.lightCullBG = lit.bg;
+        this.camCullBG = this.cullBG(this.camArgs, this.camVis, this.camCull);
+        this.lightCullBG = this.cullBG(this.lightArgs, this.lightVis, this.lightCull);
         this.statsBuf = this.device.createBuffer({ size: 4 * 4 * 2, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
     }
+    /** (Re)create the coarse Hi-Z for a `w×h` depth target and rebind the cull groups to it. Idempotent per size. */
+    ensureHiZ(w, h) {
+        const hw = Math.max(1, Math.ceil(w / HIZ_DOWN)), hh = Math.max(1, Math.ceil(h / HIZ_DOWN));
+        if (this.hizTex && this.hizW === hw && this.hizH === hh)
+            return;
+        this.hizW = hw;
+        this.hizH = hh;
+        this.hizReady = false; // fresh texture is uninitialized → skip occlusion until it's built once
+        this.hizTex = this.device.createTexture({ size: [hw, hh], format: 'r32float', usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING });
+        this.hizView = this.hizTex.createView();
+        this.occView = this.hizView; // the cull now samples the real Hi-Z
+        this.camCullBG = this.cullBG(this.camArgs, this.camVis, this.camCull);
+        this.lightCullBG = this.cullBG(this.lightArgs, this.lightVis, this.lightCull);
+    }
     scratch = new Float32Array(0);
     fill(scratch, instances, n) {
         for (let i = 0; i < n; i++) {
@@ -388,10 +496,10 @@ export class GpuShadowRenderer {
             this.device.queue.writeBuffer(this.overlayBuf, 0, this.overlayScratch, 0, n * 12);
         this.overlayCount = n;
     }
-    /** Write a frustum's cull uniform: 6 Gribb-Hartmann planes from `vp` + the live instance count. */
-    writeCull(buf, vp) {
+    /** Write a frustum's cull uniform: 6 planes + count + this frustum's VP + occlusion params (occ on the camera pass). */
+    writeCull(buf, vp, occlude) {
         const planes = frustumPlanes(vp);
-        const u = new Float32Array(6 * 4 + 4);
+        const u = new Float32Array(48); // planes[24] + cnt[4] + camVP[16] + occ[4]
         for (let p = 0; p < 6; p++) {
             u[p * 4] = planes[p][0];
             u[p * 4 + 1] = planes[p][1];
@@ -399,10 +507,17 @@ export class GpuShadowRenderer {
             u[p * 4 + 3] = planes[p][3];
         }
         u[24] = this.count;
+        u.set(vp, 28); // camVP
+        u[44] = occlude ? 1 : 0;
+        u[45] = this.hizW;
+        u[46] = this.hizH;
+        u[47] = HIZ_DOWN;
         this.device.queue.writeBuffer(buf, 0, u);
     }
-    /** camVP/lightVP: column-major Float32Array(16). sunDir: travel direction. */
-    frame(enc, colorView, sceneDepth, camVP, lightVP, sunDir, sunCol, ambient, load = false) {
+    /** camVP/lightVP: column-major Float32Array(16). sunDir: travel direction. Pass `occlusion` (the depth target +
+     *  its size) to enable Hi-Z occlusion culling on the camera pass — the renderer rebuilds a coarse Hi-Z from that
+     *  depth each frame and the NEXT frame's cull uses it (hole-free: the first frame + any resize skip occlusion). */
+    frame(enc, colorView, sceneDepth, camVP, lightVP, sunDir, sunCol, ambient, load = false, occlusion) {
         this.cam.set(camVP, 0);
         this.cam.set(lightVP, 16);
         this.cam[32] = sunDir[0];
@@ -414,14 +529,17 @@ export class GpuShadowRenderer {
         this.cam[38] = sunCol[2];
         this.cam[39] = SHADOW_SIZE;
         this.device.queue.writeBuffer(this.camBuf, 0, this.cam);
+        if (occlusion)
+            this.ensureHiZ(occlusion.w, occlusion.h);
+        const occludeNow = !!occlusion && this.hizReady; // only once a Hi-Z from a prior frame exists (never on frame 1/resize)
         // GPU-DRIVEN CULL: reset each frustum's indirect args ([vertexCount=36, instanceCount=0, 0, 0]), then compute-cull
-        // — main pass vs the camera frustum, shadow pass vs the light frustum. Each dispatch atomically compacts its
-        // survivors into a visible list + counts them in instanceCount, which the matching drawIndirect then consumes.
+        // — main pass vs the camera frustum (+ Hi-Z occlusion), shadow pass vs the light frustum. Each dispatch atomically
+        // compacts its survivors into a visible list + counts them in instanceCount, which the matching drawIndirect consumes.
         const resetArgs = new Uint32Array([36, 0, 0, 0]);
         this.device.queue.writeBuffer(this.camArgs, 0, resetArgs);
         this.device.queue.writeBuffer(this.lightArgs, 0, resetArgs);
-        this.writeCull(this.camCull, camVP);
-        this.writeCull(this.lightCull, lightVP);
+        this.writeCull(this.camCull, camVP, occludeNow);
+        this.writeCull(this.lightCull, lightVP, false);
         if (this.count > 0) {
             const cp = enc.beginComputePass();
             cp.setPipeline(this.cullPipe);
@@ -439,7 +557,7 @@ export class GpuShadowRenderer {
         sp.setBindGroup(0, this.shadowBG);
         sp.drawIndirect(this.lightArgs, 0);
         sp.end();
-        // Pass 2: camera, shadow-sampled (camera-frustum-culled).
+        // Pass 2: camera, shadow-sampled (camera-frustum + Hi-Z-occlusion-culled).
         const mp = enc.beginRenderPass({
             colorAttachments: [{ view: colorView, ...(load ? { loadOp: 'load' } : { clearValue: { r: 0.04, g: 0.05, b: 0.07, a: 1 }, loadOp: 'clear' }), storeOp: 'store' }],
             depthStencilAttachment: { view: sceneDepth, ...(load ? { depthLoadOp: 'load' } : { depthClearValue: 1.0, depthLoadOp: 'clear' }), depthStoreOp: 'store' }
@@ -453,6 +571,19 @@ export class GpuShadowRenderer {
             mp.draw(36, this.overlayCount);
         } // translucent overlay last (uncapped, no cull)
         mp.end();
+        // Rebuild the coarse Hi-Z from the depth just written → next frame's cull uses it.
+        if (occlusion) {
+            this.device.queue.writeBuffer(this.hizParam, 0, new Uint32Array([this.hizW, this.hizH, occlusion.w, occlusion.h]));
+            const bg = this.device.createBindGroup({ layout: this.hizBGL, entries: [
+                    { binding: 0, resource: occlusion.depth }, { binding: 1, resource: this.hizView }, { binding: 2, resource: { buffer: this.hizParam } }
+                ] });
+            const hp = enc.beginComputePass();
+            hp.setPipeline(this.hizPipe);
+            hp.setBindGroup(0, bg);
+            hp.dispatchWorkgroups(Math.ceil(this.hizW / 8), Math.ceil(this.hizH / 8));
+            hp.end();
+            this.hizReady = true;
+        }
         this.lastCull.total = this.count;
     }
     /** Read back the last frame's GPU cull result (camera-visible, light-visible). Does its OWN copy+submit so it's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-game",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "type": "module",
   "exports": {
     ".": {