Occlusion Check System

[AlexAPPi]

Discussion: Goal and Tasks

The main goal is to efficiently cull objects that are fully hidden behind others, in order to avoid wasting GPU resources on unnecessary rendering.
Key tasks:

• Reduce draw calls and pixel workload.

• Organize hierarchical tests (Hi-Z) to reject large clusters of objects.

• Consider API limitations: WebGL2 lacks full asynchronous access to GPU results, while WebGPU provides more flexible access through buffers and query sets.

---

Methods in WebGL2

• Occlusion Query (EXT_occlusion_query_boolean / WebGL2 core)
  Allows retrieving the number of fragments that passed the depth test. Problem: results are asynchronous and may stall the CPU when fetched.
  Mostly useful for coarse-level culling (e.g., “object is completely invisible / at least one pixel is visible”).

• Hierarchical Z (Hi-Z) via textures and mipmaps
  Implemented manually: render the current depth buffer into a texture, build a mip-chain (each level storing min-depth). In vertex/geometry shaders, AABBs can be tested against Hi-Z. This is a fully GPU-based solution, avoiding CPU queries.
  Downside: requires an additional pipeline (depth render → mipmap generation → testing).

• Transform Feedback for GPU-based culling
  Bounding volumes are tested against Hi-Z in vertex-like stages, with visible objects written back to a buffer using transformFeedback. This allows the GPU to generate a list of visible primitives without CPU involvement.

---

Methods in WebGPU

• Query Sets (Occlusion Queries)
  WebGPU natively supports occlusion queries with query sets. Bounding proxy objects can be drawn, and their results collected in GPU buffers. Reading can still be asynchronous, but unlike WebGL2, it does not directly stall the CPU.

• Compute Shader-based Culling (GPU-driven rendering)
  Compute shaders test bounding volumes against the Hi-Z depth buffer, with results written into an indirect argument buffer. Rendering of visible objects can then be launched directly by the GPU (GPU-driven). This is the modern preferred approach.

• Hierarchical Z (Hi-Z) on GPU
  Similar to WebGL2, but more efficient: the depth mip-chain can be generated using compute shaders and then used in further compute passes for visibility testing.
  Combined with indirect rendering, this provides a scalable solution.

---

I managed to implement occlusion testing without modifying the engine code by subscribing to the events:

• pc.EVENT_PRERENDER
• pc.EVENT_POSTRENDER_LAYER

Shader:

using uniform highp sampler2D uSceneDepthMap;

[AlexAPPi]

[AlexAPPi]

My current HZB solution in WebGL2 is based on creating a buffer, running a Transform Feedback shader, and then reading data from the GPU to the CPU using the getBufferSubData function.

After extensive testing, I found the most optimal option for reading data from the GPU.

this.app.on('frameupdate', ms => {
    this._hzbTester?.read(); // create macrotask after render
});

this.app.on('postrender', ms => {
    this._hzbTester?.test(camera);
});

this.app.scene.on(pc.EVENT_POSTRENDER, () => {
    this._hzb?.update();
});

// function run test occlusion by hzb
test(camera) {
    if (!this._lock) {
        const count  = this._internalTest(camera);
        if (count > 0) {
              this._lock = true;
              this._lockCount = 2;
              this._readCount = count;
         }
    }
}

// function run start read data from
read() {

        if (this._readAwaiter) {
            return false;
        }

        if (this._readCount > 0) {
            this._lockCount--;
            if (this._lockCount < 1) {

                // Read from gpu in next macrotask
                this._readAwaiter = setTimeout(() => {

                    this._readAwaiter = undefined;
                    this._internalRead(this._readCount);
                    this._clear();
                    this._readCount = 0;
                    this._lock = false;
                    
                }, 1);

                return true;
            }
        }
        return false;
}

    private _internalRead(length) {

        this._keyStore.clear();

        if (length > 0) {

            // Safe length
            length = Math.min(length, this._outData.length);

            const device = this._device as pcx.WebglGraphicsDevice;
            const gl = device.gl;

            gl.bindBuffer(gl.COPY_READ_BUFFER, this._outputBuffer.impl.bufferId);
            gl.getBufferSubData(gl.COPY_READ_BUFFER, 0, this._outData, 0, length);
            gl.bindBuffer(gl.COPY_READ_BUFFER, null);

            for (let i = 0; i < length; i++) {
                const dataIndex = this._indexQueue.indexes[i];
                this._data[dataIndex] = this._outData[i];
                this._keyStore.set(dataIndex, true);
            }
        }

        this._outDataCount = length;
    }

[AlexAPPi]

I'm also not sure, but queueMicrotask can also be used instead of setTimeout, more tests are needed for this case

[AlexAPPi]

I'm also not sure, but queueMicrotask can also be used instead of setTimeout, more tests are needed for this case

It’s possible to disable occlusion checks (read operation) when the document is hidden:
https://developer.mozilla.org/en-US/docs/Web/API/Document/hidden

[AlexAPPi]

        let hzbTesterAbortController = new AbortController();

        document.addEventListener("visibilitychange", () => {

            if (this._hzb) {

                this._hzb.enabled = !document.hidden;

                hzbTesterAbortController.abort();
                hzbTesterAbortController = new AbortController();
            }
        });

        this.app.graphicsDevice.on('resizecanvas', () => {

            this._hzb?.destroy();
            this._hzb = new HierarchicalZBuffer(this.app.graphicsDevice);

            if (this._hzbTester) {
                this._hzbTester.hzb = this._hzb;
            }
        });

    private _clientWaitAsync(flags: number, interval_ms: number, signal?: AbortSignal) {

        return new Promise<void>((resolve, reject) => {

            const device = this._device as pcx.WebglGraphicsDevice;
            const gl = device.gl;
            const sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0)!;

            device.submit();

            let timeoutAwaiter: number | undefined;

            signal?.addEventListener("abort", (e) => {
                gl?.deleteSync(sync);
                clearTimeout(timeoutAwaiter);
                timeoutAwaiter = undefined;
                reject(new Error('Aborted by signal', { cause: signal.reason }));
            });

            function test() {

                let res = -1;

                if (signal?.aborted !== true) {

                    res = gl.clientWaitSync(sync, flags, 0);

                    if (res === gl.TIMEOUT_EXPIRED) {
                        // check again in a while
                        timeoutAwaiter = setTimeout(test, interval_ms);
                        return;
                    }
                }

                gl.deleteSync(sync);

                if (res === gl.WAIT_FAILED) {
                    reject(new Error('webgl clientWaitSync sync failed'));
                } else {
                    resolve();
                }
            }

            timeoutAwaiter = setTimeout(test, interval_ms);
        });
    }

    public async test(camera: pcx.Camera, signal?: AbortSignal) {

        if (this.hzb.enabled && !this._lock) {

            this.update();

            const count = this._internalTest(camera);

            if (count > 0) {

                try {

                    if (this.device.isWebGL2) {
                        
                        this._lock = true;
                        await this._clientWaitAsync(0, 36, signal); // 36 ~ 2 frame for 60 fps
                        this._internalRead(count);
                    }
                }
                finally {
                    this._lock = false;
                    this.clear();
                }
            }
        }
    }

[AlexAPPi]

When the tabs are deactivated, a reset occurs, and it takes some time for the system to stabilize. In this test, 4,580 objects are being processed. After stabilization, the FPS remains steady at around 75 frames per second.

https://www.youtube.com/watch?v=8GPcbmZ1gso