@codexo/exojs 0.8.4 → 0.10.0

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

@@ -1,9 +1,11 @@
 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 { ParticleSystem } from '../../particles/ParticleSystem.js';
+import { BitmapText } from '../text/BitmapText.js';
+import { Text } from '../text/Text.js';
 import { BlendModes } from '../types.js';
-import WebGLDebugUtils from '../../vendor/webgl-debug.js';
 import { Mesh } from '../mesh/Mesh.js';
 import { RenderBackendType } from '../RenderBackendType.js';
 import { RendererRegistry } from '../RendererRegistry.js';
@@ -12,28 +14,51 @@ import { RenderTarget } from '../RenderTarget.js';
 import { Sprite } from '../sprite/Sprite.js';
 import { DataTexture } from '../texture/DataTexture.js';
 import { RenderTexture } from '../texture/RenderTexture.js';
+import { TransformBuffer } from '../TransformBuffer.js';
 import { WebGl2MaskCompositor } from './WebGl2MaskCompositor.js';
 import { WebGl2MeshRenderer } from './WebGl2MeshRenderer.js';
 import { WebGl2ParticleRenderer } from './WebGl2ParticleRenderer.js';
+import { WebGl2PassCoordinator } from './WebGl2PassCoordinator.js';
 import { WebGl2SpriteRenderer } from './WebGl2SpriteRenderer.js';
+import { WebGl2StencilClipper } from './WebGl2StencilClipper.js';
+import { WebGl2TextRenderer } from './WebGl2TextRenderer.js';
 
-const throwOnGlError = (err, funcName) => {
-    throw `${WebGLDebugUtils.glEnumToString(err)} was caused by call to: ${funcName}`;
-};
-const logGlCall = (functionName, args) => {
-    console.log(`gl.${functionName}(${WebGLDebugUtils.glFunctionArgsToString(functionName, args)})`);
-};
-const validateNoneOfTheArgsAreUndefined = (functionName, args) => {
-    for (const argument of args) {
-        if (argument === undefined) {
-            console.error(`undefined passed to gl.${functionName}(${WebGLDebugUtils.glFunctionArgsToString(functionName, args)})`);
-        }
-    }
-};
-const logAndValidate = (functionName, args) => {
-    logGlCall(functionName, args);
-    validateNoneOfTheArgsAreUndefined(functionName, args);
+// 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
  * context, texture and framebuffer caches keyed by user-side
@@ -67,6 +92,10 @@ class WebGl2Backend {
     _clipPointB = new Vector();
     _maskCompositor = new WebGl2MaskCompositor();
     _maskCompositorConnected = false;
+    _stencilClipper = new WebGl2StencilClipper();
+    _stencilStates = new Map();
+    _stencilClipperConnected = false;
+    _passCoordinatorInstance = null;
     _canvas;
     _contextLost;
     _renderTarget;
@@ -79,14 +108,28 @@ class WebGl2Backend {
     _clearColor = new Color();
     _boundFramebuffer = null;
     _stats = createRenderStats();
+    _transformBuffer = new TransformBuffer();
+    _transformTexture = null;
+    _transformTextureHash = 0;
+    _transformTextureCount = -1;
+    _activeDrawCommand = null;
+    _drawPlanDepth = 0;
     constructor(app) {
-        const { width, height, clearColor, webglAttributes, debug, spriteRendererBatchSize, particleRendererBatchSize } = app.options;
+        const canvasOptions = app.options.canvas ?? {};
+        const renderingOptions = app.options.rendering ?? {};
+        const width = canvasOptions.width ?? 800;
+        const height = canvasOptions.height ?? 600;
+        const clearColor = app.options.clearColor;
+        const webglAttributes = renderingOptions.webglAttributes;
+        const debug = renderingOptions.debug ?? false;
+        const spriteRendererBatchSize = renderingOptions.spriteRendererBatchSize ?? 4096;
+        const particleRendererBatchSize = renderingOptions.particleRendererBatchSize ?? 8192;
         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 ? WebGLDebugUtils.makeDebugContext(gl, throwOnGlError, logAndValidate, gl) : gl;
+        this._context = debug ? makeWebGl2DebugContext(gl) : gl;
         this._contextLost = this._context.isContextLost();
         if (this._contextLost) {
             this._restoreContext();
@@ -103,6 +146,8 @@ class WebGl2Backend {
         this.rendererRegistry.registerRenderer(Sprite, new WebGl2SpriteRenderer(spriteRendererBatchSize));
         this.rendererRegistry.registerRenderer(Mesh, new WebGl2MeshRenderer());
         this.rendererRegistry.registerRenderer(ParticleSystem, new WebGl2ParticleRenderer(particleRendererBatchSize));
+        this.rendererRegistry.registerRenderer(Text, new WebGl2TextRenderer());
+        this.rendererRegistry.registerRenderer(BitmapText, new WebGl2TextRenderer());
         this.rendererRegistry.connect(this);
         this._bindRenderTarget(this._renderTarget);
         this.setBlendMode(BlendModes.Normal);
@@ -123,6 +168,19 @@ class WebGl2Backend {
     get stats() {
         return this._stats;
     }
+    /** @internal */
+    get activeDrawCommand() {
+        return this._activeDrawCommand;
+    }
+    /**
+     * Internal render-pass coordinator. Owns target / view / clear orchestration
+     * and the scissor / stencil-clip stacks for this backend; not part of the
+     * public {@link RenderBackend} surface.
+     * @internal
+     */
+    get _passCoordinator() {
+        return (this._passCoordinatorInstance ??= new WebGl2PassCoordinator(this));
+    }
     async initialize() {
         return this;
     }
@@ -130,10 +188,55 @@ class WebGl2Backend {
         resetRenderStats(this._stats);
         return this;
     }
+    /** @internal */
+    _beginDrawPlan(nodeCount) {
+        this._transformBuffer.begin(nodeCount);
+        this._activeDrawCommand = null;
+        this._drawPlanDepth++;
+    }
+    /** @internal */
+    _prepareDrawCommand(command) {
+        this._activeDrawCommand = command;
+        const drawable = command.drawable;
+        this._transformBuffer.write(command.nodeIndex, drawable.getGlobalTransform(), drawable.tint);
+    }
+    /** @internal */
+    _endDrawPlan() {
+        this._activeDrawCommand = null;
+        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.
+        if (this._drawPlanDepth === 0) {
+            this._assertBalancedStencil();
+        }
+    }
+    _assertBalancedStencil() {
+        let unpopped = 0;
+        for (const state of this._stencilStates.values()) {
+            unpopped += state.stack.length;
+        }
+        if (unpopped === 0) {
+            return;
+        }
+        // Reset so a leaked clip cannot corrupt subsequent frames, then surface it.
+        for (const state of this._stencilStates.values()) {
+            state.depth = 0;
+            state.stack.length = 0;
+        }
+        const gl = this._context;
+        gl.stencilFunc(gl.ALWAYS, 0, 0xff);
+        gl.stencilOp(gl.KEEP, gl.KEEP, gl.KEEP);
+        gl.disable(gl.STENCIL_TEST);
+        throw new Error(`Unbalanced stencil clip stack at end of frame (${unpopped} unpopped clip(s)).`);
+    }
     draw(drawable) {
         const renderer = this.rendererRegistry.resolve(drawable);
         this._setActiveRenderer(renderer);
         renderer.render(drawable);
+        this._activeDrawCommand = null;
         this._stats.submittedNodes++;
         return this;
     }
@@ -145,11 +248,18 @@ class WebGl2Backend {
     }
     setRenderTarget(target) {
         const renderTarget = target || this._rootRenderTarget;
-        if (this._renderTarget !== renderTarget) {
+        const changed = this._renderTarget !== renderTarget;
+        if (changed) {
+            this._flushActiveRenderer();
             this._renderTarget = renderTarget;
             this._stats.renderTargetChanges++;
         }
         this._bindRenderTarget(renderTarget);
+        if (changed) {
+            // Stencil state is per-target: restore the new target's clip depth so an
+            // outer clip on the previous target does not leak onto this one.
+            this._applyStencilState(renderTarget);
+        }
         return this;
     }
     pushScissorRect(bounds) {
@@ -175,6 +285,65 @@ class WebGl2Backend {
         this._applyClipState();
         return this;
     }
+    pushStencilClip(shape, transform) {
+        const target = this._renderTarget;
+        const state = this._getStencilState(target);
+        if (state.depth >= 255) {
+            throw new Error('Stencil clip nesting exceeds the 255-level limit.');
+        }
+        this._flushActiveRenderer();
+        this._setActiveRenderer(null);
+        if (!this._stencilClipperConnected) {
+            this._stencilClipper.connect(this);
+            this._stencilClipperConnected = true;
+        }
+        const gl = this._context;
+        const depth = state.depth;
+        if (depth === 0) {
+            this._ensureTargetStencil();
+            gl.enable(gl.STENCIL_TEST);
+            // Clear the whole stencil buffer to 0 regardless of any active scissor,
+            // then restore the scissor state for the shape/content draws.
+            gl.disable(gl.SCISSOR_TEST);
+            gl.clearStencil(0);
+            gl.clear(gl.STENCIL_BUFFER_BIT);
+            this._applyClipState();
+        }
+        // Increment the stencil where the shape covers the already-valid region
+        // (EQUAL depth). Color/depth writes off so only the stencil is touched.
+        gl.colorMask(false, false, false, false);
+        gl.stencilFunc(gl.EQUAL, depth, 0xff);
+        gl.stencilOp(gl.KEEP, gl.KEEP, gl.INCR);
+        this._stencilClipper.draw(this, shape, transform);
+        gl.colorMask(true, true, true, true);
+        state.depth = depth + 1;
+        state.stack.push({ shape, transform: new Matrix().copy(transform) });
+        // Content now passes only where the stencil equals the new depth.
+        gl.stencilFunc(gl.EQUAL, state.depth, 0xff);
+        gl.stencilOp(gl.KEEP, gl.KEEP, gl.KEEP);
+        return this;
+    }
+    popStencilClip() {
+        const target = this._renderTarget;
+        const state = this._getStencilState(target);
+        const entry = state.stack.pop();
+        if (entry === undefined) {
+            return this;
+        }
+        this._flushActiveRenderer();
+        this._setActiveRenderer(null);
+        const gl = this._context;
+        const depth = state.depth;
+        // Decrement the region this clip incremented, restoring the outer level.
+        gl.colorMask(false, false, false, false);
+        gl.stencilFunc(gl.EQUAL, depth, 0xff);
+        gl.stencilOp(gl.KEEP, gl.KEEP, gl.DECR);
+        this._stencilClipper.draw(this, entry.shape, entry.transform);
+        gl.colorMask(true, true, true, true);
+        state.depth = depth - 1;
+        this._applyStencilState(target);
+        return this;
+    }
     composeWithAlphaMask(content, mask, x, y, width, height, blendMode) {
         if (width <= 0 || height <= 0) {
             return this;
@@ -217,10 +386,14 @@ class WebGl2Backend {
     bindVertexArrayObject(vao) {
         if (this._vao !== vao) {
             if (vao) {
+                // Binding a VAO implicitly replaces the previous binding. Only when
+                // switching to "no VAO" do we explicitly unbind — unbinding the old VAO
+                // *after* binding the new one would leave the GL default (null) VAO
+                // bound and silently break the next draw (a renderer/clip VAO switch).
                 vao.bind();
             }
-            if (this._vao) {
-                this._vao.unbind();
+            else {
+                this._vao?.unbind();
             }
             this._vao = vao;
         }
@@ -255,24 +428,64 @@ class WebGl2Backend {
         this._texture = texture;
         return this;
     }
+    /** @internal */
+    bindTransformBufferTexture(unit, minCount) {
+        const requiredCount = Math.max(1, minCount);
+        const transformTexture = this._transformTexture;
+        if (transformTexture?.height !== this._transformBuffer.capacity || transformTexture.buffer !== this._transformBuffer.data) {
+            transformTexture?.destroy();
+            this._transformTexture = new DataTexture({
+                width: 3,
+                height: this._transformBuffer.capacity,
+                format: 'rgba32f',
+                data: this._transformBuffer.data,
+            });
+            this._transformTextureHash = 0;
+            this._transformTextureCount = -1;
+        }
+        const snapshot = this._transformBuffer.commitSnapshot(requiredCount);
+        const nextTransformTexture = this._transformTexture;
+        if (nextTransformTexture === null) {
+            throw new Error('Transform texture must be initialized before binding.');
+        }
+        if (snapshot.changed || snapshot.count !== this._transformTextureCount || snapshot.hash !== this._transformTextureHash) {
+            nextTransformTexture.commitRect(0, 0, 3, snapshot.count);
+            this._transformTextureHash = snapshot.hash;
+            this._transformTextureCount = snapshot.count;
+        }
+        return this.bindTexture(nextTransformTexture, unit);
+    }
     setBlendMode(blendMode) {
         if (blendMode !== this._blendMode) {
             const gl = this._context;
             this._blendMode = blendMode;
             switch (blendMode) {
                 case BlendModes.Additive:
+                    gl.blendEquation(gl.FUNC_ADD);
                     gl.blendFunc(gl.ONE, gl.ONE);
                     break;
                 case BlendModes.Subtract:
+                    gl.blendEquation(gl.FUNC_ADD);
                     gl.blendFunc(gl.ZERO, gl.ONE_MINUS_SRC_COLOR);
                     break;
                 case BlendModes.Multiply:
+                    gl.blendEquation(gl.FUNC_ADD);
                     gl.blendFunc(gl.DST_COLOR, gl.ONE_MINUS_SRC_ALPHA);
                     break;
                 case BlendModes.Screen:
+                    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);
                     break;
             }
@@ -304,8 +517,6 @@ class WebGl2Backend {
         return this;
     }
     resize(width, height) {
-        this._canvas.width = width;
-        this._canvas.height = height;
         this._rootRenderTarget.resize(width, height);
         this._bindRenderTarget(this._renderTarget);
         return this;
@@ -338,17 +549,33 @@ class WebGl2Backend {
             this._maskCompositor.disconnect();
             this._maskCompositorConnected = false;
         }
+        if (this._stencilClipperConnected) {
+            this._stencilClipper.disconnect();
+            this._stencilClipperConnected = false;
+        }
+        this._stencilStates.clear();
+        this._drawPlanDepth = 0;
         this._rootRenderTarget.destroy();
+        if (this._transformTexture !== null) {
+            this._transformTexture.destroy();
+            this._transformTexture = null;
+        }
         this._vao = null;
         this._renderer = null;
         this._shader = null;
         this._blendMode = null;
         this._texture = null;
         this._boundFramebuffer = null;
+        this._activeDrawCommand = null;
+        this._transformTextureCount = -1;
+        this._transformTextureHash = 0;
     }
     _createContext(options) {
         try {
-            return this._canvas.getContext('webgl2', options);
+            // Force a stencil buffer on the default framebuffer so geometric stencil
+            // clipping (RenderNode.clip with a Geometry clipShape) works on the root
+            // target. Inert until a clip is pushed (STENCIL_TEST stays disabled).
+            return this._canvas.getContext('webgl2', { ...options, stencil: true });
         }
         catch (_e) {
             return null;
@@ -422,6 +649,9 @@ class WebGl2Backend {
                 framebuffer: target.root ? null : this._createFramebuffer(),
                 version: -1,
                 attachedTexture: null,
+                stencilRenderbuffer: null,
+                stencilWidth: 0,
+                stencilHeight: 0,
             };
             this._renderTargetStates.set(target, state);
         }
@@ -470,8 +700,13 @@ class WebGl2Backend {
             if (state.framebuffer !== null) {
                 this._context.deleteFramebuffer(state.framebuffer);
             }
+            if (state.stencilRenderbuffer !== null) {
+                this._context.deleteRenderbuffer(state.stencilRenderbuffer);
+                state.stencilRenderbuffer = null;
+            }
             this._renderTargetStates.delete(target);
         }
+        this._stencilStates.delete(target);
         if (this._renderTarget === target) {
             this._renderTarget = this._rootRenderTarget;
             if (rebind) {
@@ -501,7 +736,13 @@ class WebGl2Backend {
         const state = this._prepareRenderTarget(target);
         if (this._boundFramebuffer !== state.framebuffer || state.version !== target.version) {
             const gl = this._context;
-            const { x, y, width, height } = target.getViewport();
+            const viewport = target.getViewport();
+            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));
             gl.bindFramebuffer(gl.FRAMEBUFFER, state.framebuffer);
             gl.viewport(x, y, width, height);
             this._boundFramebuffer = state.framebuffer;
@@ -527,7 +768,10 @@ class WebGl2Backend {
         const state = this._getRenderTargetState(target);
         if (target instanceof RenderTexture && state.framebuffer) {
             const previousFramebuffer = this._boundFramebuffer;
+            const previousUnit = this._textureUnit;
+            this._setTextureUnit(renderTargetTextureSyncUnit);
             const textureState = this._syncTexture(target);
+            this._setTextureUnit(previousUnit);
             if (state.attachedTexture !== textureState.handle) {
                 const gl = this._context;
                 gl.bindFramebuffer(gl.FRAMEBUFFER, state.framebuffer);
@@ -535,9 +779,76 @@ class WebGl2Backend {
                 gl.bindFramebuffer(gl.FRAMEBUFFER, previousFramebuffer);
                 state.attachedTexture = textureState.handle;
             }
+            // Reset the on-demand flag for pooled RenderTexture targets, so a
+            // stencil renderbuffer from a previous use does not permanently
+            // consume GPU memory when the target is re-purposed for non-clip
+            // rendering.
+            if (!this._stencilStates.has(target)) {
+                target.needsStencil = false;
+            }
+            // Keep an existing stencil attachment sized to the (possibly resized)
+            // texture so the framebuffer stays complete during non-clip rendering.
+            if (target.needsStencil || state.stencilRenderbuffer !== null) {
+                this._syncStencilAttachment(target, state);
+            }
+        }
+        return state;
+    }
+    /** Attach a depth/stencil renderbuffer to the active target if it lacks one. */
+    _ensureTargetStencil() {
+        const target = this._renderTarget;
+        if (target.root) {
+            // The default framebuffer's stencil comes from the context attributes.
+            return;
+        }
+        target.needsStencil = true;
+        this._syncStencilAttachment(target, this._getRenderTargetState(target));
+    }
+    _syncStencilAttachment(target, state) {
+        if (state.framebuffer === null) {
+            return;
+        }
+        const gl = this._context;
+        const width = Math.max(1, target.width);
+        const height = Math.max(1, target.height);
+        if (state.stencilRenderbuffer !== null && state.stencilWidth === width && state.stencilHeight === height) {
+            return;
+        }
+        if (state.stencilRenderbuffer === null) {
+            state.stencilRenderbuffer = gl.createRenderbuffer();
+        }
+        gl.bindRenderbuffer(gl.RENDERBUFFER, state.stencilRenderbuffer);
+        gl.renderbufferStorage(gl.RENDERBUFFER, gl.DEPTH24_STENCIL8, width, height);
+        gl.bindRenderbuffer(gl.RENDERBUFFER, null);
+        const previousFramebuffer = this._boundFramebuffer;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, state.framebuffer);
+        gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_STENCIL_ATTACHMENT, gl.RENDERBUFFER, state.stencilRenderbuffer);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, previousFramebuffer);
+        state.stencilWidth = width;
+        state.stencilHeight = height;
+    }
+    _getStencilState(target) {
+        let state = this._stencilStates.get(target);
+        if (state === undefined) {
+            state = { depth: 0, stack: [] };
+            this._stencilStates.set(target, state);
         }
         return state;
     }
+    /** Re-apply the GL stencil test to match `target`'s current clip depth. */
+    _applyStencilState(target) {
+        const gl = this._context;
+        const depth = this._getStencilState(target).depth;
+        if (depth === 0) {
+            gl.stencilFunc(gl.ALWAYS, 0, 0xff);
+            gl.stencilOp(gl.KEEP, gl.KEEP, gl.KEEP);
+            gl.disable(gl.STENCIL_TEST);
+            return;
+        }
+        gl.enable(gl.STENCIL_TEST);
+        gl.stencilFunc(gl.EQUAL, depth, 0xff);
+        gl.stencilOp(gl.KEEP, gl.KEEP, gl.KEEP);
+    }
     _syncTexture(texture) {
         const gl = this._context;
         const state = this._getTextureState(texture);
@@ -640,8 +951,14 @@ class WebGl2Backend {
             return;
         }
         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;
+        const x = Math.floor(clip.x * scaleX);
+        const y = Math.floor(clip.y * scaleY);
+        const width = Math.max(0, Math.round(clip.width * scaleX));
+        const height = Math.max(0, Math.round(clip.height * scaleY));
         gl.enable(gl.SCISSOR_TEST);
-        gl.scissor(clip.x, clip.y, clip.width, clip.height);
+        gl.scissor(x, y, width, height);
     }
 }
 // WebGL2RenderingContext is not defined in jsdom; resolve constants from