@codexo/exojs 0.13.0 → 0.15.0

package/dist/esm/rendering/webgl2/WebGl2Backend.js

@@ -2,8 +2,9 @@ import { Color } from '../../core/Color.js';
 import { Signal } from '../../core/Signal.js';
 import { Matrix } from '../../math/Matrix.js';
 import { Vector } from '../../math/Vector.js';
+import { GpuResourceAccountant, estimateTextureBytes, dataTextureBytesPerPixel } from '../GpuResourceAccountant.js';
 import { resolveUploadTransform } from '../pixelSnap.js';
-import { drawCommandUsesSharedTransform } from '../plan/RenderCommand.js';
+import { RenderEntryKind, drawCommandUsesSharedTransform } from '../plan/RenderCommand.js';
 import { RenderBackendType } from '../RenderBackendType.js';
 import { RendererRegistry } from '../RendererRegistry.js';
 import { createRenderStats, resetRenderStats } from '../RenderStats.js';
@@ -12,45 +13,12 @@ import { DataTexture } from '../texture/DataTexture.js';
 import { RenderTexture } from '../texture/RenderTexture.js';
 import { TransformBuffer } from '../TransformBuffer.js';
 import { BlendModes } from '../types.js';
+import { WebGl2BackdropBlendCompositor } from './WebGl2BackdropBlendCompositor.js';
 import { WebGl2MaskCompositor } from './WebGl2MaskCompositor.js';
+import { WebGl2MeshRenderer } from './WebGl2MeshRenderer.js';
 import { WebGl2PassCoordinator } from './WebGl2PassCoordinator.js';
 import { WebGl2StencilClipper } from './WebGl2StencilClipper.js';
 
-// Inline GL debug helpers — replaces the webgl-debug vendor lib.
-// Used only when renderingOptions.debug = true.
-const glEnumToString = (gl, value) => {
-    const ctor = gl.constructor;
-    for (const key of Object.getOwnPropertyNames(ctor)) {
-        if (ctor[key] === value)
-            return key;
-    }
-    return `0x${value.toString(16).padStart(4, '0').toUpperCase()}`;
-};
-const glArgsToString = (gl, args) => args.map(a => (typeof a === 'number' ? glEnumToString(gl, a) : String(a))).join(', ');
-const makeWebGl2DebugContext = (gl) => new Proxy(gl, {
-    get(target, prop, receiver) {
-        const value = Reflect.get(target, prop, receiver);
-        if (typeof value !== 'function')
-            return value;
-        const name = String(prop);
-        return (...args) => {
-            console.log(`gl.${name}(${glArgsToString(target, args)})`);
-            for (const arg of args) {
-                if (arg === undefined) {
-                    console.error(`undefined passed to gl.${name}(${glArgsToString(target, args)})`);
-                }
-            }
-            const result = Reflect.apply(value, target, args);
-            if (name !== 'getError') {
-                const err = target.getError();
-                if (err !== target.NO_ERROR) {
-                    throw new Error(`${glEnumToString(target, err)} was caused by call to: ${name}`);
-                }
-            }
-            return result;
-        };
-    },
-});
 const renderTargetTextureSyncUnit = 15;
 /**
  * WebGL 2.0 implementation of {@link RenderBackend}. Manages the GL
@@ -85,6 +53,8 @@ class WebGl2Backend {
     _clipPointB = new Vector();
     _maskCompositor = new WebGl2MaskCompositor();
     _maskCompositorConnected = false;
+    _backdropBlendCompositor = new WebGl2BackdropBlendCompositor();
+    _backdropBlendCompositorConnected = false;
     _stencilClipper = new WebGl2StencilClipper();
     _stencilStates = new Map();
     _stencilClipperConnected = false;
@@ -102,12 +72,15 @@ class WebGl2Backend {
     _clearColor = new Color();
     _boundFramebuffer = null;
     _stats = createRenderStats();
+    _accountant = new GpuResourceAccountant(this._stats);
     _transformBuffer = new TransformBuffer();
     _transformTexture = null;
     _transformTextureHash = 0;
     _transformTextureCount = -1;
     _activeDrawCommand = null;
     _drawPlanDepth = 0;
+    _planBaseStack = [];
+    _planHashStack = [];
     constructor(app) {
         const canvasOptions = app.options.canvas ?? {};
         const renderingOptions = app.options.rendering ?? {};
@@ -115,13 +88,13 @@ class WebGl2Backend {
         const height = canvasOptions.height ?? 600;
         const clearColor = app.options.clearColor;
         const webglAttributes = renderingOptions.webglAttributes;
-        const debug = renderingOptions.debug ?? false;
+        renderingOptions.debug ?? false;
         this._canvas = app.canvas;
         const gl = this._createContext(webglAttributes);
         if (!gl) {
             throw new Error('This browser or hardware does not support WebGL.');
         }
-        this._context = debug ? makeWebGl2DebugContext(gl) : gl;
+        this._context = gl;
         this._contextLost = this._context.isContextLost();
         if (this._contextLost) {
             this._restoreContext();
@@ -157,6 +130,15 @@ class WebGl2Backend {
     get stats() {
         return this._stats;
     }
+    /**
+     * Per-backend GPU resource accountant (VRAM / upload / download bookkeeping).
+     * Used by this backend's renderers (e.g. batched vertex/index buffers) to
+     * book their own allocations and uploads. Not part of any public surface.
+     * @internal
+     */
+    get accountant() {
+        return this._accountant;
+    }
     /** @internal */
     get activeDrawCommand() {
         return this._activeDrawCommand;
@@ -175,16 +157,29 @@ class WebGl2Backend {
     }
     resetStats() {
         resetRenderStats(this._stats);
+        // The transform buffer is frame-scoped: reset it once per frame here (was
+        // previously reset per render() call in _beginDrawPlan).
+        this._transformBuffer.begin();
         return this;
     }
+    /** Frame-global slot base the plan builder indexes from. @internal */
+    get transformBufferCount() {
+        return this._transformBuffer.count;
+    }
     /** @internal */
-    _beginDrawPlan(nodeCount) {
-        this._transformBuffer.begin(nodeCount);
+    _beginDrawPlan(_nodeCount) {
+        // Do NOT reset the transform buffer here — it is frame-scoped (reset in
+        // resetStats). The builder already based this plan's node indices at the
+        // current buffer count, so writes land in fresh frame-global slots and
+        // batches survive across render() calls. Remember this plan's base so a
+        // nested plan can free its rows on end.
+        this._planBaseStack.push(this._transformBuffer.count);
+        this._planHashStack.push(this._transformBuffer.frameHash);
         this._activeDrawCommand = null;
         this._drawPlanDepth++;
     }
     /** @internal */
-    _prepareRenderGroupUpload(group) {
+    _prepareRenderGroupUpload(entries, startIndex, count) {
         // Pack the whole render group's world transforms (+ tint) into the shared
         // transform buffer at the group's upload boundary, keyed by each draw
         // command's stable nodeIndex. Every draw the player will submit for this
@@ -192,12 +187,20 @@ class WebGl2Backend {
         // write previously done in `_prepareDrawCommand` is no longer needed and
         // the buffer is filled one contiguous group slice at a time.
         //
+        // The group is the entries range `[startIndex, startIndex + count)`; every
+        // entry in it is a draw, so the player no longer materializes a group array.
+        //
         // Renderers that pack their own per-node data (Text, Particle) never read
         // the shared buffer, so their commands are skipped — no consuming draw ever
         // references their slots (nodeIndex is unique per command).
-        const instructions = group.instructions;
-        for (let i = 0; i < instructions.length; i++) {
-            const command = instructions[i];
+        const end = startIndex + count;
+        for (let i = startIndex; i < end; i++) {
+            const entry = entries[i];
+            // Every entry in a group run is a draw; narrow to read its command.
+            if (entry.kind !== RenderEntryKind.Draw) {
+                continue;
+            }
+            const command = entry.command;
             if (drawCommandUsesSharedTransform(command, this)) {
                 this._writeTransformCommand(command);
             }
@@ -267,12 +270,20 @@ class WebGl2Backend {
     /** @internal */
     _endDrawPlan() {
         this._activeDrawCommand = null;
+        const planBase = this._planBaseStack.pop() ?? 0;
+        const planHash = this._planHashStack.pop() ?? 0;
         if (this._drawPlanDepth > 0) {
             this._drawPlanDepth--;
         }
-        // Only assert balance at the outermost plan: cacheAsBitmap draws a cache
-        // sprite via a nested render(), whose inner _endDrawPlan sees the still-open
-        // outer clips — those are not leaks.
+        // A nested plan (filter / cacheAsBitmap) just ended: flush its draws, then
+        // free its transform rows so the frame-scoped buffer only grows with
+        // top-level render() calls. Top-level plans (depth back to 0) keep their rows
+        // so cross-call batching survives to the frame-end flush.
+        if (this._drawPlanDepth > 0) {
+            this._flushActiveRenderer();
+            this._transformBuffer.rewindTo(planBase, planHash);
+        }
+        // Only assert balance at the outermost plan.
         if (this._drawPlanDepth === 0) {
             this._assertBalancedStencil();
         }
@@ -304,6 +315,31 @@ class WebGl2Backend {
         this._stats.submittedNodes++;
         return this;
     }
+    drawInstanced(mesh, transforms, tints, count) {
+        if (count <= 0 || mesh.vertexCount === 0) {
+            return this;
+        }
+        if (transforms.length < count || tints.length < count) {
+            throw new Error(`drawInstanced requires ${count} transforms and tints (got ${transforms.length}/${tints.length}).`);
+        }
+        const renderer = this.rendererRegistry.resolve(mesh);
+        if (!(renderer instanceof WebGl2MeshRenderer)) {
+            throw new Error('drawInstanced requires a mesh handled by the WebGL2 mesh renderer.');
+        }
+        this._setActiveRenderer(renderer);
+        // Write each instance's (transform, tint) into a fresh, contiguous transform
+        // slot — before the renderer's draw uploads the buffer (write-before-bind) —
+        // then draw the geometry once over [startNodeIndex, startNodeIndex + count).
+        // In-bounds: `i < count <= transforms.length` and `<= tints.length` (guarded above).
+        const startNodeIndex = this._transformBuffer.push(transforms[0], tints[0]);
+        for (let i = 1; i < count; i++) {
+            this._transformBuffer.push(transforms[i], tints[i]);
+        }
+        renderer.drawInstancedBatch(mesh, startNodeIndex, count);
+        this._activeDrawCommand = null;
+        this._stats.submittedNodes += count;
+        return this;
+    }
     execute(pass) {
         this._flushActiveRenderer();
         this._stats.renderPasses++;
@@ -423,8 +459,40 @@ class WebGl2Backend {
         this._maskCompositor.compose(this, content, mask, x, y, width, height, blendMode);
         return this;
     }
+    composeWithBackdropBlend(source, x, y, width, height, mode) {
+        if (width <= 0 || height <= 0) {
+            return this;
+        }
+        this._flushActiveRenderer();
+        this._setActiveRenderer(null);
+        if (!this._backdropBlendCompositorConnected) {
+            this._backdropBlendCompositor.connect(this);
+            this._backdropBlendCompositorConnected = true;
+        }
+        this._backdropBlendCompositor.compose(this, source, x, y, width, height, mode);
+        return this;
+    }
+    /**
+     * Return the GL framebuffer for `target`, preparing the render-target state so
+     * the texture is attached. Used internally by {@link WebGl2BackdropBlendCompositor}
+     * for framebuffer blits. Null for the root (default) framebuffer.
+     * @internal
+     */
+    _renderTargetFramebuffer(target) {
+        return this._prepareRenderTarget(target).framebuffer;
+    }
+    /**
+     * Re-bind the currently active render target as the GL DRAW framebuffer and
+     * restore the viewport. Called by {@link WebGl2BackdropBlendCompositor} after
+     * it unbinds the framebuffer for a blit operation.
+     * @internal
+     */
+    _rebindActiveTarget() {
+        this._bindRenderTarget(this._renderTarget);
+    }
     acquireRenderTexture(width, height) {
         for (let index = 0; index < this._temporaryRenderTextures.length; index++) {
+            // In-bounds: `index` ranges over `0..length-1`.
             const texture = this._temporaryRenderTextures[index];
             if (texture.width === width && texture.height === height) {
                 this._temporaryRenderTextures.splice(index, 1);
@@ -442,7 +510,12 @@ class WebGl2Backend {
         return this;
     }
     setView(view) {
-        this._flushActiveRenderer();
+        // Only flush the open batch when the view actually changes. The unconditional
+        // flush forced one draw call per render() call (each render() re-applies the
+        // same camera view), defeating cross-call batching.
+        if (this._renderTarget.view !== view) {
+            this._flushActiveRenderer();
+        }
         this._renderTarget.setView(view);
         this._bindRenderTarget(this._renderTarget);
         return this;
@@ -492,6 +565,21 @@ class WebGl2Backend {
         this._texture = texture;
         return this;
     }
+    /**
+     * Make `unit` the active texture unit through the backend's unit cache.
+     *
+     * Renderers that bind a *raw* `WebGLTexture` to a unit (e.g. the text
+     * renderer's private node-data texture) must route the unit switch through
+     * here instead of calling `gl.activeTexture` directly — otherwise the cache
+     * goes stale and a later {@link bindTexture} can skip its own `activeTexture`
+     * call, binding to the wrong unit. After this returns the caller may issue its
+     * own raw `gl.bindTexture` on the now-active unit.
+     * @internal
+     */
+    setActiveTextureUnit(unit) {
+        this._setTextureUnit(unit);
+        return this;
+    }
     /** @internal */
     bindTransformBufferTexture(unit, minCount) {
         const requiredCount = Math.max(1, minCount);
@@ -512,11 +600,21 @@ class WebGl2Backend {
         if (nextTransformTexture === null) {
             throw new Error('Transform texture must be initialized before binding.');
         }
+        // A skipped flush (all three guards false) leaves the dirty range uncleared
+        // until the next begin(). Safe: every write() mixes its slot into _frameHash,
+        // so a non-empty dirty range always coincides with snapshot.changed = true —
+        // the upload branch is always taken before any dirty rows could be stale.
         if (snapshot.changed || snapshot.count !== this._transformTextureCount || snapshot.hash !== this._transformTextureHash) {
-            nextTransformTexture.commitRect(0, 0, 3, snapshot.count);
-            this._transformBuffer.recordUpload(snapshot.count);
-            this._transformTextureHash = snapshot.hash;
+            // Upload only the rows actually written since the last upload (delta), so
+            // barrier-heavy frames don't re-upload the whole growing buffer. A reused
+            // slot below the high-water mark is in the dirty range, so it re-uploads.
+            const { firstRow, rowCount } = this._transformBuffer.consumeDirtyRange(snapshot.count);
+            if (rowCount > 0) {
+                nextTransformTexture.commitRect(0, firstRow, 3, rowCount);
+                this._transformBuffer.recordUpload(rowCount);
+            }
             this._transformTextureCount = snapshot.count;
+            this._transformTextureHash = snapshot.hash;
         }
         return this.bindTexture(nextTransformTexture, unit);
     }
@@ -541,14 +639,6 @@ class WebGl2Backend {
                     gl.blendEquation(gl.FUNC_ADD);
                     gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_COLOR);
                     break;
-                case BlendModes.Darken:
-                    gl.blendEquation(gl.MIN);
-                    gl.blendFunc(gl.ONE, gl.ONE);
-                    break;
-                case BlendModes.Lighten:
-                    gl.blendEquation(gl.MAX);
-                    gl.blendFunc(gl.ONE, gl.ONE);
-                    break;
                 default:
                     gl.blendEquation(gl.FUNC_ADD);
                     gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
@@ -614,6 +704,10 @@ class WebGl2Backend {
             this._maskCompositor.disconnect();
             this._maskCompositorConnected = false;
         }
+        if (this._backdropBlendCompositorConnected) {
+            this._backdropBlendCompositor.disconnect();
+            this._backdropBlendCompositorConnected = false;
+        }
         if (this._stencilClipperConnected) {
             this._stencilClipper.disconnect();
             this._stencilClipperConnected = false;
@@ -690,6 +784,26 @@ class WebGl2Backend {
         }
         return texture;
     }
+    /**
+     * Re-book a managed texture's GPU storage with the resource accountant after a
+     * full `texImage2D` (re)allocation: frees the previously booked size (if any —
+     * e.g. on resize) and allocates the new `width · height · bytesPerPixel`
+     * footprint, including the mip chain when the texture generates mips.
+     */
+    _bookTextureStorage(state, texture, bytesPerPixel) {
+        const nextBytes = estimateTextureBytes(texture.width, texture.height, bytesPerPixel, this._textureMipLevelCount(texture));
+        state.accountedBytes = this._accountant.reallocate(state.accountedBytes, nextBytes);
+    }
+    _textureMipLevelCount(texture) {
+        if (!texture.generateMipMap) {
+            return 1;
+        }
+        const maxSize = Math.max(texture.width, texture.height);
+        if (maxSize <= 1) {
+            return 1;
+        }
+        return Math.floor(Math.log2(maxSize)) + 1;
+    }
     _destroyManagedResources() {
         for (const renderTarget of [...this._renderTargetStates.keys()]) {
             this._evictRenderTarget(renderTarget, false);
@@ -733,6 +847,7 @@ class WebGl2Backend {
                 version: -1,
                 width: 0,
                 height: 0,
+                accountedBytes: 0,
             };
             this._textureStates.set(texture, state);
         }
@@ -788,6 +903,8 @@ class WebGl2Backend {
                 this._texture = null;
             }
             this._context.deleteTexture(state.handle);
+            this._accountant.free(state.accountedBytes);
+            state.accountedBytes = 0;
             this._textureStates.delete(texture);
         }
         if (this._texture === texture) {
@@ -805,9 +922,14 @@ class WebGl2Backend {
             const scaleX = target.root && target.width > 0 ? this._canvas.width / target.width : 1;
             const scaleY = target.root && target.height > 0 ? this._canvas.height / target.height : 1;
             const x = Math.floor(viewport.x * scaleX);
-            const y = Math.floor(viewport.y * scaleY);
             const width = Math.max(0, Math.round(viewport.width * scaleX));
             const height = Math.max(0, Math.round(viewport.height * scaleY));
+            // `viewport.y` is top-left (the View / RenderTarget convention); GL's viewport
+            // origin is bottom-left, so flip it. A full viewport (y = 0, height = full) maps
+            // to y = 0 unchanged — only partial viewports (split-screen / pip / minimap) were
+            // affected, landing at the wrong edge before this flip.
+            const backingHeight = target.root ? this._canvas.height : target.height;
+            const y = backingHeight - (Math.floor(viewport.y * scaleY) + height);
             gl.bindFramebuffer(gl.FRAMEBUFFER, state.framebuffer);
             gl.viewport(x, y, width, height);
             this._boundFramebuffer = state.framebuffer;
@@ -926,11 +1048,27 @@ class WebGl2Backend {
             gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, texture.wrapMode);
             gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, texture.premultiplyAlpha);
             if (texture instanceof DataTexture) {
-                const formatInfo = webgl2DataTextureFormat(texture.format);
+                // `instanceof DataTexture` narrows to `DataTexture<any>` (the generic is
+                // erased), so `texture.format` widens to `any`; the class invariant
+                // guarantees it is a `DataTextureFormat`, so restore that type here.
+                const format = texture.format;
+                const formatInfo = webgl2DataTextureFormat(format);
                 const region = texture._consumeDirtyRegion();
                 const needsAlloc = state.version === -1 || state.width !== texture.width || state.height !== texture.height;
+                // Our DataTexture buffers are tightly packed (no per-row padding), but
+                // WebGL defaults UNPACK_ALIGNMENT to 4. For single-byte (r8) data a
+                // sub-region upload whose width isn't a multiple of 4 would be misread
+                // — or rejected with INVALID_OPERATION for height > 1 — leaving the
+                // region un-uploaded. That is exactly what corrupts a partial glyph-
+                // atlas upload when new glyphs first appear after the initial full
+                // upload (e.g. switching to a scene with new characters). Force tight
+                // packing for the upload, then restore the GL default.
+                gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+                const bytesPerPixel = dataTextureBytesPerPixel(format);
                 if (needsAlloc || region === null || region.full) {
                     gl.texImage2D(gl.TEXTURE_2D, 0, formatInfo.internalFormat, texture.width, texture.height, 0, formatInfo.format, formatInfo.type, texture.buffer);
+                    this._bookTextureStorage(state, texture, bytesPerPixel);
+                    this._accountant.recordTextureUpload(texture.width * texture.height * bytesPerPixel);
                 }
                 else {
                     // Partial upload: pack a contiguous sub-region from the row-major
@@ -947,23 +1085,30 @@ class WebGl2Backend {
                         subView.set(texture.buffer.subarray(sourceStart, sourceStart + subFloats), targetStart);
                     }
                     gl.texSubImage2D(gl.TEXTURE_2D, 0, region.x, region.y, region.width, region.height, formatInfo.format, formatInfo.type, subView);
+                    this._accountant.recordTextureUpload(region.width * region.height * bytesPerPixel);
                 }
+                gl.pixelStorei(gl.UNPACK_ALIGNMENT, 4);
             }
             else if (texture instanceof RenderTexture) {
                 if (state.version === -1 || state.width !== texture.width || state.height !== texture.height || texture.source === null) {
                     gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, texture.width, texture.height, 0, gl.RGBA, gl.UNSIGNED_BYTE, texture.source);
+                    this._bookTextureStorage(state, texture, RGBA8_BYTES_PER_PIXEL);
+                    this._accountant.recordTextureUpload(texture.width * texture.height * RGBA8_BYTES_PER_PIXEL);
                 }
                 else {
                     gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, texture.width, texture.height, gl.RGBA, gl.UNSIGNED_BYTE, texture.source);
+                    this._accountant.recordTextureUpload(texture.width * texture.height * RGBA8_BYTES_PER_PIXEL);
                 }
             }
             else if (texture.source) {
                 if (state.version === -1 || state.width !== texture.width || state.height !== texture.height) {
                     gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, texture.source);
+                    this._bookTextureStorage(state, texture, RGBA8_BYTES_PER_PIXEL);
                 }
                 else {
                     gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, gl.RGBA, gl.UNSIGNED_BYTE, texture.source);
                 }
+                this._accountant.recordTextureUpload(texture.width * texture.height * RGBA8_BYTES_PER_PIXEL);
             }
             if (texture.generateMipMap && (texture instanceof RenderTexture || texture.source !== null)) {
                 gl.generateMipmap(gl.TEXTURE_2D);
@@ -1015,6 +1160,7 @@ class WebGl2Backend {
             gl.disable(gl.SCISSOR_TEST);
             return;
         }
+        // In-bounds: the empty-stack case returned above, so the top entry exists.
         const clip = this._clipPixelStack[this._clipPixelStack.length - 1];
         const scaleX = this._renderTarget.root && this._renderTarget.width > 0 ? this._canvas.width / this._renderTarget.width : 1;
         const scaleY = this._renderTarget.root && this._renderTarget.height > 0 ? this._canvas.height / this._renderTarget.height : 1;
@@ -1026,6 +1172,8 @@ class WebGl2Backend {
         gl.scissor(x, y, width, height);
     }
 }
+// Content + render textures upload as gl.RGBA / gl.UNSIGNED_BYTE = 4 bytes/px.
+const RGBA8_BYTES_PER_PIXEL = 4;
 // WebGL2RenderingContext is not defined in jsdom; resolve constants from
 // the live gl context instead of the global class so test environments
 // without WebGL2 still load this module.