@lightningjs/renderer 3.0.1 → 3.0.3

package/src/core/renderers/webgl/WebGlRenderer.rtt.test.ts

@@ -0,0 +1,551 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2023 Comcast Cable Communications Management, LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * RTT (Render To Texture) pipeline unit tests for WebGlRenderer.
+ *
+ * These tests validate rttNodes ordering, dirty-flag lifecycle, and skip
+ * conditions without requiring a real WebGL context. The WebGlRenderer is
+ * tested at the level of its internal bookkeeping methods only.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { mock } from 'vitest-mock-extended';
+import {
+  CoreNode,
+  CoreNodeRenderState,
+  UpdateType,
+  type CoreNodeProps,
+} from '../../CoreNode.js';
+import type { Stage } from '../../Stage.js';
+import type { CoreRenderer } from '../CoreRenderer.js';
+import { createBound } from '../../lib/utils.js';
+import type { TextureOptions } from '../../CoreTextureManager.js';
+import { Texture } from '../../textures/Texture.js';
+import { WebGlRenderer } from './WebGlRenderer.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const makeDefaultProps = (): CoreNodeProps => ({
+  alpha: 1,
+  autosize: false,
+  boundsMargin: null,
+  clipping: false,
+  color: 0xffffffff,
+  colorBl: 0xffffffff,
+  colorBottom: 0xffffffff,
+  colorBr: 0xffffffff,
+  colorLeft: 0xffffffff,
+  colorRight: 0xffffffff,
+  colorTl: 0xffffffff,
+  colorTop: 0xffffffff,
+  colorTr: 0xffffffff,
+  h: 100,
+  mount: 0,
+  mountX: 0,
+  mountY: 0,
+  parent: null,
+  pivot: 0.5,
+  pivotX: 0.5,
+  pivotY: 0.5,
+  rotation: 0,
+  rtt: false,
+  scale: 1,
+  scaleX: 1,
+  scaleY: 1,
+  shader: null,
+  src: '',
+  texture: null,
+  textureOptions: {} as TextureOptions,
+  w: 100,
+  x: 0,
+  y: 0,
+  zIndex: 0,
+});
+
+/**
+ * Minimal mock stage that satisfies CoreNode's constructor requirements.
+ */
+const makeStage = (): Stage =>
+  mock<Stage>({
+    strictBound: createBound(0, 0, 1920, 1080),
+    preloadBound: createBound(0, 0, 1920, 1080),
+    defaultTexture: { state: 'loaded' } as unknown as Texture,
+    renderer: mock<CoreRenderer>() as CoreRenderer,
+    txManager: {
+      createTexture: vi.fn().mockReturnValue({
+        state: 'loaded',
+        ctxTexture: { framebuffer: {} },
+      }),
+    } as unknown as Stage['txManager'],
+  });
+
+// ---------------------------------------------------------------------------
+// RTT ordering tests — exercised via renderToTexture() on a real
+// WebGlRenderer instance created with Object.create so no GL context is needed.
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a minimal WebGlRenderer instance with only `rttNodes` initialised.
+ * Object.create skips the constructor so no GL context is required.
+ * insertRTTNodeInOrder / findMaxChildRTTIndex / renderToTexture only access
+ * `this.rttNodes`, so this stub is sufficient to exercise the real production
+ * code paths.
+ */
+function makeOrderer(): WebGlRenderer {
+  const r = Object.create(WebGlRenderer.prototype) as WebGlRenderer;
+  r.rttNodes = [];
+  return r;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('RTT — rttNodes insertion ordering', () => {
+  let stage: Stage;
+  let orderer: WebGlRenderer;
+
+  beforeEach(() => {
+    stage = makeStage();
+    orderer = makeOrderer();
+  });
+
+  it('adds a single RTT node to an empty list', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    orderer.renderToTexture(node);
+    expect(orderer.rttNodes.length).toBe(1);
+    expect(orderer.rttNodes[0]).toBe(node);
+  });
+
+  it('does not add the same node twice', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    orderer.renderToTexture(node);
+    orderer.renderToTexture(node);
+    expect(orderer.rttNodes.length).toBe(1);
+  });
+
+  it('places a child RTT node BEFORE its RTT parent', () => {
+    const parent = new CoreNode(stage, makeDefaultProps());
+    const child = new CoreNode(stage, makeDefaultProps());
+    child.parent = parent;
+
+    // Parent added first, then child — child must end up before parent
+    orderer.renderToTexture(parent);
+    orderer.renderToTexture(child);
+
+    const parentIdx = orderer.rttNodes.indexOf(parent);
+    const childIdx = orderer.rttNodes.indexOf(child);
+    expect(childIdx).toBeLessThan(parentIdx);
+  });
+
+  it('places a parent RTT node AFTER an already-registered child', () => {
+    const parent = new CoreNode(stage, makeDefaultProps());
+    const child = new CoreNode(stage, makeDefaultProps());
+    child.parent = parent;
+
+    // Child added first, then parent — parent must end up after child
+    orderer.renderToTexture(child);
+    orderer.renderToTexture(parent);
+
+    const parentIdx = orderer.rttNodes.indexOf(parent);
+    const childIdx = orderer.rttNodes.indexOf(child);
+    expect(childIdx).toBeLessThan(parentIdx);
+  });
+
+  it('handles 3-level nested RTT ordering: grandchild < child < parent', () => {
+    const grandparent = new CoreNode(stage, makeDefaultProps());
+    const parent = new CoreNode(stage, makeDefaultProps());
+    const grandchild = new CoreNode(stage, makeDefaultProps());
+    parent.parent = grandparent;
+    grandchild.parent = parent;
+
+    // Insert in arbitrary order
+    orderer.renderToTexture(grandparent);
+    orderer.renderToTexture(grandchild);
+    orderer.renderToTexture(parent);
+
+    const gpIdx = orderer.rttNodes.indexOf(grandparent);
+    const pIdx = orderer.rttNodes.indexOf(parent);
+    const gcIdx = orderer.rttNodes.indexOf(grandchild);
+
+    expect(gcIdx).toBeLessThan(pIdx);
+    expect(pIdx).toBeLessThan(gpIdx);
+  });
+
+  it('inserts sibling RTT nodes in insertion order (a before b)', () => {
+    const root = new CoreNode(stage, makeDefaultProps());
+    const a = new CoreNode(stage, makeDefaultProps());
+    const b = new CoreNode(stage, makeDefaultProps());
+    a.parent = root;
+    b.parent = root;
+
+    orderer.renderToTexture(a);
+    orderer.renderToTexture(b);
+
+    expect(orderer.rttNodes.length).toBe(2);
+    // Siblings have no ordering constraint relative to each other, so the
+    // expected behaviour is that insertion order is preserved.
+    expect(orderer.rttNodes.indexOf(a)).toBeLessThan(
+      orderer.rttNodes.indexOf(b),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// RTT dirty-flag lifecycle — exercised directly on CoreNode fields
+// (no GL context needed)
+// ---------------------------------------------------------------------------
+
+describe('RTT — hasRTTupdates dirty-flag lifecycle', () => {
+  let stage: Stage;
+
+  beforeEach(() => {
+    stage = makeStage();
+  });
+
+  it('hasRTTupdates starts as false on a new node', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    expect(node.hasRTTupdates).toBe(false);
+  });
+
+  it('notifyParentRTTOfUpdate sets hasRTTupdates on the RTT ancestor', () => {
+    const rttParent = new CoreNode(stage, {
+      ...makeDefaultProps(),
+      rtt: false,
+    });
+    const child = new CoreNode(stage, makeDefaultProps());
+    child.parent = rttParent;
+
+    // Manually wire rttParent flag used by notifyParentRTTOfUpdate path
+    // (normally set by markChildrenWithRTT when rtt is enabled on rttParent)
+    // Simulate the state that exists after rtt=true is set on rttParent
+    rttParent['props'].rtt = true;
+    child.parentHasRenderTexture = true;
+    child.rttParent = rttParent;
+
+    rttParent.hasRTTupdates = false;
+
+    // Call the protected method via cast
+    (
+      child as unknown as { notifyParentRTTOfUpdate(): void }
+    ).notifyParentRTTOfUpdate();
+
+    expect(rttParent.hasRTTupdates).toBe(true);
+  });
+
+  it('notifyParentRTTOfUpdate is a no-op when node has no RTT ancestor', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    // No parent — should not throw
+    expect(() => {
+      (
+        node as unknown as { notifyParentRTTOfUpdate(): void }
+      ).notifyParentRTTOfUpdate();
+    }).not.toThrow();
+    expect(node.hasRTTupdates).toBe(false);
+  });
+
+  it('hasRTTupdates can be reset to false', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    node.hasRTTupdates = true;
+    node.hasRTTupdates = false;
+    expect(node.hasRTTupdates).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// RTT parentHasRenderTexture propagation
+// ---------------------------------------------------------------------------
+
+describe('RTT — parentHasRenderTexture propagation', () => {
+  let stage: Stage;
+
+  beforeEach(() => {
+    stage = makeStage();
+  });
+
+  it('parentHasRenderTexture is false by default', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    expect(node.parentHasRenderTexture).toBe(false);
+  });
+
+  it('markChildrenWithRTT sets parentHasRenderTexture=true on direct children', () => {
+    const parent = new CoreNode(stage, makeDefaultProps());
+    const child = new CoreNode(stage, makeDefaultProps());
+    child.parent = parent;
+
+    // Call private method directly
+    (
+      parent as unknown as { markChildrenWithRTT(): void }
+    ).markChildrenWithRTT();
+
+    expect(child.parentHasRenderTexture).toBe(true);
+  });
+
+  it('markChildrenWithRTT propagates to grandchildren', () => {
+    const parent = new CoreNode(stage, makeDefaultProps());
+    const child = new CoreNode(stage, makeDefaultProps());
+    const grandchild = new CoreNode(stage, makeDefaultProps());
+    child.parent = parent;
+    grandchild.parent = child;
+
+    (
+      parent as unknown as { markChildrenWithRTT(): void }
+    ).markChildrenWithRTT();
+
+    expect(child.parentHasRenderTexture).toBe(true);
+    expect(grandchild.parentHasRenderTexture).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// RTT parentRenderTexture getter — uncached parent-chain walk
+// (this is Bottleneck 1 in the perf analysis)
+// ---------------------------------------------------------------------------
+
+describe('RTT — parentRenderTexture getter', () => {
+  let stage: Stage;
+
+  beforeEach(() => {
+    stage = makeStage();
+  });
+
+  it('returns null when there is no RTT ancestor', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    expect(node.parentRenderTexture).toBe(null);
+  });
+
+  it('returns the nearest RTT ancestor', () => {
+    const rttAncestor = new CoreNode(stage, makeDefaultProps());
+    rttAncestor['props'].rtt = true;
+    const child = new CoreNode(stage, makeDefaultProps());
+    child.parent = rttAncestor;
+
+    expect(child.parentRenderTexture).toBe(rttAncestor);
+  });
+
+  it('returns the NEAREST RTT ancestor in a nested chain', () => {
+    const outer = new CoreNode(stage, makeDefaultProps());
+    const inner = new CoreNode(stage, makeDefaultProps());
+    const leaf = new CoreNode(stage, makeDefaultProps());
+    outer['props'].rtt = true;
+    inner['props'].rtt = true;
+    inner.parent = outer;
+    leaf.parent = inner;
+
+    // leaf's nearest RTT ancestor is inner, not outer
+    expect(leaf.parentRenderTexture).toBe(inner);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// RTT — renderRTTNodes skip conditions
+// Validated via a lightweight simulation of the skip logic
+// ---------------------------------------------------------------------------
+
+describe('RTT — renderRTTNodes skip conditions', () => {
+  let stage: Stage;
+
+  beforeEach(() => {
+    stage = makeStage();
+  });
+
+  /**
+   * Simulate the exact skip gates in renderRTTNodes() for a single node.
+   * Returns true if the node would be rendered, false if skipped.
+   */
+  const wouldRender = (
+    node: CoreNode,
+    texture: { state: string } | null,
+  ): boolean => {
+    if (node.hasRTTupdates === false) return false;
+    if (node.worldAlpha === 0) return false;
+    if (node.renderState === CoreNodeRenderState.OutOfBounds) return false;
+    if (texture === null || texture.state !== 'loaded') return false;
+    return true;
+  };
+
+  it('skips a node when hasRTTupdates is false', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    node.hasRTTupdates = false;
+    node.worldAlpha = 1;
+    node.renderState = CoreNodeRenderState.InBounds;
+    expect(wouldRender(node, { state: 'loaded' })).toBe(false);
+  });
+
+  it('renders a node when hasRTTupdates is true and all other conditions pass', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    node.hasRTTupdates = true;
+    node.worldAlpha = 1;
+    node.renderState = CoreNodeRenderState.InBounds;
+    expect(wouldRender(node, { state: 'loaded' })).toBe(true);
+  });
+
+  it('skips a node when worldAlpha is 0', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    node.hasRTTupdates = true;
+    node.worldAlpha = 0;
+    node.renderState = CoreNodeRenderState.InBounds;
+    expect(wouldRender(node, { state: 'loaded' })).toBe(false);
+  });
+
+  it('skips a node when renderState is OutOfBounds', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    node.hasRTTupdates = true;
+    node.worldAlpha = 1;
+    node.renderState = CoreNodeRenderState.OutOfBounds;
+    expect(wouldRender(node, { state: 'loaded' })).toBe(false);
+  });
+
+  it('skips a node when texture is null', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    node.hasRTTupdates = true;
+    node.worldAlpha = 1;
+    node.renderState = CoreNodeRenderState.InBounds;
+    expect(wouldRender(node, null)).toBe(false);
+  });
+
+  it('skips a node when texture is not loaded', () => {
+    const node = new CoreNode(stage, makeDefaultProps());
+    node.hasRTTupdates = true;
+    node.worldAlpha = 1;
+    node.renderState = CoreNodeRenderState.InBounds;
+    expect(wouldRender(node, { state: 'loading' })).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// RTT_NOTIFY_MASK — gate on notifyParentRTTOfUpdate() inside update()
+//
+// The mask ensures RTT surfaces are re-rendered only when a visually relevant
+// UpdateType flag is present. Non-visual cascade flags (Children, RenderBounds,
+// RenderState, ParentRenderTexture, Autosize) must NOT trigger re-renders.
+// ---------------------------------------------------------------------------
+
+describe('RTT — RTT_NOTIFY_MASK gate in update()', () => {
+  // Minimal clipping rect required by CoreNode.update()
+  const clippingRect = { x: 0, y: 0, w: 1920, h: 1080, valid: false };
+
+  let stage: Stage;
+
+  // Builds a child node wired into an RTT parent so the
+  // `parentHasRenderTexture === true` branch in update() is reachable.
+  function makeRttChild() {
+    const rttParent = new CoreNode(stage, makeDefaultProps());
+    rttParent['props'].rtt = true;
+
+    const child = new CoreNode(stage, makeDefaultProps());
+    child.parent = rttParent;
+    child.parentHasRenderTexture = true;
+    child.rttParent = rttParent;
+    child.hasRTTupdates = false;
+
+    return { rttParent, child };
+  }
+
+  beforeEach(() => {
+    stage = makeStage();
+  });
+
+  it('fires notifyParentRTTOfUpdate for a visual flag (PremultipliedColors)', () => {
+    const { rttParent, child } = makeRttChild();
+    const spy = vi.spyOn(
+      child as unknown as { notifyParentRTTOfUpdate(): void },
+      'notifyParentRTTOfUpdate',
+    );
+    rttParent.hasRTTupdates = false;
+
+    child.updateType = UpdateType.PremultipliedColors;
+    child.update(0, clippingRect);
+
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  it('fires notifyParentRTTOfUpdate for a visual flag (WorldAlpha)', () => {
+    const { child } = makeRttChild();
+    const spy = vi.spyOn(
+      child as unknown as { notifyParentRTTOfUpdate(): void },
+      'notifyParentRTTOfUpdate',
+    );
+
+    child.updateType = UpdateType.WorldAlpha;
+    child.update(0, clippingRect);
+
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  it('does NOT fire notifyParentRTTOfUpdate for Children flag alone', () => {
+    const { child } = makeRttChild();
+    const spy = vi.spyOn(
+      child as unknown as { notifyParentRTTOfUpdate(): void },
+      'notifyParentRTTOfUpdate',
+    );
+
+    // Children is not in RTT_NOTIFY_MASK and hasRTTupdates is false
+    child.updateType = UpdateType.Children;
+    child.hasRTTupdates = false;
+    child.update(0, clippingRect);
+
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('does NOT fire notifyParentRTTOfUpdate for Autosize flag alone', () => {
+    const { child } = makeRttChild();
+    const spy = vi.spyOn(
+      child as unknown as { notifyParentRTTOfUpdate(): void },
+      'notifyParentRTTOfUpdate',
+    );
+
+    child.updateType = UpdateType.Autosize;
+    child.hasRTTupdates = false;
+    child.update(0, clippingRect);
+
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('fires notifyParentRTTOfUpdate when hasRTTupdates=true even for non-visual flag (Children)', () => {
+    const { child } = makeRttChild();
+    const spy = vi.spyOn(
+      child as unknown as { notifyParentRTTOfUpdate(): void },
+      'notifyParentRTTOfUpdate',
+    );
+
+    // hasRTTupdates=true short-circuits the mask check
+    child.updateType = UpdateType.Children;
+    child.hasRTTupdates = true;
+    child.update(0, clippingRect);
+
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  it('does NOT fire notifyParentRTTOfUpdate when parentHasRenderTexture is false, even with visual flag', () => {
+    const { child } = makeRttChild();
+    const spy = vi.spyOn(
+      child as unknown as { notifyParentRTTOfUpdate(): void },
+      'notifyParentRTTOfUpdate',
+    );
+
+    child.parentHasRenderTexture = false;
+    child.updateType = UpdateType.PremultipliedColors;
+    child.update(0, clippingRect);
+
+    expect(spy).not.toHaveBeenCalled();
+  });
+});

package/src/core/renderers/webgl/WebGlRenderer.ts

@@ -474,28 +474,27 @@ export class WebGlRenderer extends CoreRenderer {
   private insertRTTNodeInOrder(node: CoreNode) {
     let insertIndex = this.rttNodes.length; // Default to the end of the array
 
+    // Build a one-shot index map so all lookups below are O(1) instead of O(n).
+    const rttNodes = this.rttNodes;
+    const indexMap = new Map<number, number>();
+    for (let i = 0; i < rttNodes.length; i++) {
+      indexMap.set(rttNodes[i]!.id, i);
+    }
+
     // 1. Traverse upwards to ensure the node is placed before its RTT parent (if any).
     let currentNode: CoreNode = node;
-    while (currentNode) {
-      if (!currentNode.parent) {
-        break;
-      }
-
-      const parentIndex = this.rttNodes.indexOf(currentNode.parent);
-      if (parentIndex !== -1) {
-        // Found an RTT parent in the list; set insertIndex to place node before the parent
+    while (currentNode.parent !== null) {
+      const parentIndex = indexMap.get(currentNode.parent.id);
+      if (parentIndex !== undefined) {
         insertIndex = parentIndex;
         break;
       }
-
       currentNode = currentNode.parent;
     }
 
     // 2. Traverse downwards to ensure the node is placed after any RTT children.
-    // Look through each child recursively to see if any are already in rttNodes.
-    const maxChildIndex = this.findMaxChildRTTIndex(node);
+    const maxChildIndex = this.findMaxChildRTTIndex(node, indexMap);
     if (maxChildIndex !== -1) {
-      // Adjust insertIndex to be after the last child RTT node
       insertIndex = Math.max(insertIndex, maxChildIndex + 1);
     }
 
@@ -503,25 +502,25 @@ export class WebGlRenderer extends CoreRenderer {
     this.rttNodes.splice(insertIndex, 0, node);
   }
 
-  // Helper function to find the highest index of any RTT children of a node within rttNodes
-  private findMaxChildRTTIndex(node: CoreNode): number {
+  // Iterative DFS to find the highest rttNodes index among all RTT descendants of node.
+  private findMaxChildRTTIndex(
+    node: CoreNode,
+    indexMap: Map<number, number>,
+  ): number {
     let maxIndex = -1;
-
-    const traverseChildren = (currentNode: CoreNode) => {
-      const currentIndex = this.rttNodes.indexOf(currentNode);
-      if (currentIndex !== -1) {
-        maxIndex = Math.max(maxIndex, currentIndex);
+    // Explicit stack avoids recursive arrow function allocation and call-stack growth.
+    const stack: CoreNode[] = [node];
+    while (stack.length !== 0) {
+      const current = stack.pop()!;
+      const idx = indexMap.get(current.id);
+      if (idx !== undefined && idx > maxIndex) {
+        maxIndex = idx;
       }
-
-      // Recursively check all children of the current node
-      for (const child of currentNode.children) {
-        traverseChildren(child);
+      const children = current.children;
+      for (let i = 0; i < children.length; i++) {
+        stack.push(children[i]!);
       }
-    };
-
-    // Start traversal directly with the provided node
-    traverseChildren(node);
-
+    }
     return maxIndex;
   }
 
@@ -724,4 +723,15 @@ export class WebGlRenderer extends CoreRenderer {
       normalized: normalizedColor,
     };
   }
+
+  override destroy(): void {
+    const loseCtx = this.glw.getExtension(
+      'WEBGL_lose_context',
+    ) as WEBGL_lose_context | null;
+    loseCtx?.loseContext();
+  }
+
+  override deleteBuffer(buffer: WebGLBuffer): void {
+    this.glw.deleteBuffer(buffer);
+  }
 }