@solidtv/renderer 1.5.2 → 1.5.4

package/src/core/CoreNode.test.ts

@@ -13,6 +13,7 @@ import { premultiplyColorABGR } from '../utils.js';
 describe('set color()', () => {
   const defaultProps = (overrides?: Partial<CoreNodeProps>): CoreNodeProps => ({
     alpha: 0,
+    ignoreParentAlpha: false,
     autosize: false,
     boundsMargin: null,
     clipping: false,
@@ -264,6 +265,112 @@ describe('set color()', () => {
     });
   });
 
+  describe('ignoreParentAlpha', () => {
+    const makeParent = (worldAlpha: number) => {
+      const parent = new CoreNode(stage, defaultProps());
+      parent.globalTransform = Matrix3d.identity();
+      parent.worldAlpha = worldAlpha;
+      return parent;
+    };
+
+    it('multiplies parent world alpha by default', () => {
+      const parent = makeParent(0.5);
+      const node = new CoreNode(stage, defaultProps({ parent, alpha: 0.8 }));
+
+      node.update(0, clippingRect);
+
+      expect(node.worldAlpha).toBeCloseTo(0.4);
+    });
+
+    it('uses own alpha only when enabled', () => {
+      const parent = makeParent(0.5);
+      const node = new CoreNode(
+        stage,
+        defaultProps({ parent, alpha: 0.8, ignoreParentAlpha: true }),
+      );
+
+      node.update(0, clippingRect);
+
+      expect(node.worldAlpha).toBe(0.8);
+    });
+
+    it('keeps its own world alpha while the parent fades toward 0', () => {
+      const parent = makeParent(0.01);
+      const node = new CoreNode(
+        stage,
+        defaultProps({ parent, alpha: 1, ignoreParentAlpha: true }),
+      );
+      node.w = 100;
+      node.h = 100;
+      node.color = 0xffffffff;
+
+      node.update(0, clippingRect);
+
+      expect(node.worldAlpha).toBe(1);
+      expect(node.isRenderable).toBe(true);
+    });
+
+    it('premultiplies colors with the node own alpha when enabled', () => {
+      const parent = makeParent(0.25);
+      const node = new CoreNode(
+        stage,
+        defaultProps({ parent, alpha: 0.8, ignoreParentAlpha: true }),
+      );
+      node.w = 100;
+      node.h = 100;
+      node.color = 0xff0000ff;
+
+      node.update(0, clippingRect);
+
+      expect(node.premultipliedColorTl).toBe(
+        premultiplyColorABGR(0xff0000ff, 0.8),
+      );
+    });
+
+    it('toggling the setter recomputes world alpha', () => {
+      const parent = makeParent(0.5);
+      const node = new CoreNode(stage, defaultProps({ parent, alpha: 0.8 }));
+
+      node.update(0, clippingRect);
+      expect(node.worldAlpha).toBeCloseTo(0.4);
+
+      node.ignoreParentAlpha = true;
+      node.update(1, clippingRect);
+      expect(node.worldAlpha).toBe(0.8);
+
+      node.ignoreParentAlpha = false;
+      node.update(2, clippingRect);
+      expect(node.worldAlpha).toBeCloseTo(0.4);
+    });
+
+    it('setting the same value does not flag an update', () => {
+      const node = new CoreNode(stage, defaultProps());
+      const updateTypeBefore = node.updateType;
+
+      node.ignoreParentAlpha = false;
+
+      expect(node.updateType).toBe(updateTypeBefore);
+    });
+
+    it('descendants inherit the node world alpha as usual', () => {
+      const parent = makeParent(0.5);
+      const node = new CoreNode(
+        stage,
+        defaultProps({ parent, alpha: 0.8, ignoreParentAlpha: true }),
+      );
+      const child = new CoreNode(
+        stage,
+        defaultProps({ parent: node, alpha: 0.5 }),
+      );
+
+      node.update(0, clippingRect);
+      child.update(0, clippingRect);
+
+      expect(node.worldAlpha).toBe(0.8);
+      expect(child.worldAlpha).toBeCloseTo(0.4);
+    });
+  });
+
   describe('autosize system', () => {
     it('should initialize with autosize disabled', () => {
       const node = new CoreNode(stage, defaultProps());
@@ -1605,4 +1712,169 @@ describe('set color()', () => {
       expect(node.isRenderable).toBe(true);
     });
   });
+
+  describe('texture ownership cache', () => {
+    // Same shape as the placeholderColor texture fake: a real EventEmitter so
+    // loadTextureTask subscribes and we can drive freed/loaded by emitting.
+    function emittingTexture(state: string): ImageTexture & {
+      emit: (event: string, data?: unknown) => void;
+    } {
+      return Object.assign(new EventEmitter(), {
+        state,
+        preventCleanup: false,
+        retryCount: 0,
+        maxRetryCount: 1,
+        dimensions: { w: 100, h: 100 },
+        setRenderableOwner: vi.fn(),
+      }) as unknown as ImageTexture & {
+        emit: (event: string, data?: unknown) => void;
+      };
+    }
+
+    function visibleNode(): CoreNode {
+      const parent = new CoreNode(stage, defaultProps());
+      parent.globalTransform = Matrix3d.identity();
+      parent.worldAlpha = 1;
+
+      const node = new CoreNode(stage, defaultProps({ parent }));
+      node.alpha = 1;
+      node.x = 0;
+      node.y = 0;
+      node.w = 100;
+      node.h = 100;
+      return node;
+    }
+
+    const flushMicrotasks = () => Promise.resolve();
+
+    it('repeated updates with unchanged state call setRenderableOwner once', () => {
+      const node = visibleNode();
+      const texture = emittingTexture('loaded');
+      node.texture = texture;
+      node.textureLoaded = true;
+
+      // The texture setter registers ownership with the node's current
+      // isRenderable (false here), so the cache starts false.
+      expect(texture.setRenderableOwner).toHaveBeenCalledTimes(1);
+      expect(texture.setRenderableOwner).toHaveBeenLastCalledWith(
+        expect.anything(),
+        false,
+      );
+
+      node.update(0, clippingRect);
+      expect(texture.setRenderableOwner).toHaveBeenCalledTimes(2);
+      expect(texture.setRenderableOwner).toHaveBeenLastCalledWith(
+        expect.anything(),
+        true,
+      );
+
+      // Steady-state scroll: ownership unchanged, no further calls.
+      node.update(1, clippingRect);
+      node.update(2, clippingRect);
+      expect(texture.setRenderableOwner).toHaveBeenCalledTimes(2);
+    });
+
+    it('moving out of bounds releases ownership once, returning re-adds', () => {
+      const node = visibleNode();
+      const texture = emittingTexture('loaded');
+      node.texture = texture;
+      node.textureLoaded = true;
+
+      node.update(0, clippingRect);
+      expect(texture.setRenderableOwner).toHaveBeenLastCalledWith(
+        expect.anything(),
+        true,
+      );
+      const callsAfterFirstUpdate = (
+        texture.setRenderableOwner as ReturnType<typeof vi.fn>
+      ).mock.calls.length;
+
+      // Out of the 200x200 stage bounds entirely.
+      node.x = 1000;
+      node.update(1, clippingRect);
+      expect(texture.setRenderableOwner).toHaveBeenCalledTimes(
+        callsAfterFirstUpdate + 1,
+      );
+      expect(texture.setRenderableOwner).toHaveBeenLastCalledWith(
+        expect.anything(),
+        false,
+      );
+
+      // Still out of bounds: no repeated release.
+      node.update(2, clippingRect);
+      expect(texture.setRenderableOwner).toHaveBeenCalledTimes(
+        callsAfterFirstUpdate + 1,
+      );
+
+      // Back in view: re-registered exactly once.
+      node.x = 0;
+      node.update(3, clippingRect);
+      expect(texture.setRenderableOwner).toHaveBeenCalledTimes(
+        callsAfterFirstUpdate + 2,
+      );
+      expect(texture.setRenderableOwner).toHaveBeenLastCalledWith(
+        expect.anything(),
+        true,
+      );
+    });
+
+    it('swapping textures releases the old owner and registers the new one', () => {
+      const node = visibleNode();
+      const textureA = emittingTexture('loaded');
+      node.texture = textureA;
+      node.textureLoaded = true;
+      node.update(0, clippingRect);
+      expect(textureA.setRenderableOwner).toHaveBeenLastCalledWith(
+        expect.anything(),
+        true,
+      );
+
+      const textureB = emittingTexture('loaded');
+      node.texture = textureB;
+
+      // A is released via unloadTexture.
+      expect(textureA.setRenderableOwner).toHaveBeenLastCalledWith(
+        expect.anything(),
+        false,
+      );
+      // B is registered with the node's current renderable state (true),
+      // proving the cache reset on swap — a stale cache would skip this.
+      expect(textureB.setRenderableOwner).toHaveBeenCalledWith(
+        expect.anything(),
+        true,
+      );
+    });
+
+    it('freed texture is re-registered on the next update (reload trigger)', async () => {
+      const node = visibleNode();
+      const texture = emittingTexture('initial');
+      node.texture = texture;
+      node.update(0, clippingRect);
+
+      await flushMicrotasks();
+      (texture as { state: string }).state = 'loaded';
+      texture.emit('loaded', { w: 100, h: 100 });
+      node.update(1, clippingRect);
+      expect(texture.setRenderableOwner).toHaveBeenLastCalledWith(
+        expect.anything(),
+        true,
+      );
+
+      // Memory manager frees the texture: the node must drop ownership...
+      (texture as { state: string }).state = 'freed';
+      texture.emit('freed');
+      expect(texture.setRenderableOwner).toHaveBeenLastCalledWith(
+        expect.anything(),
+        false,
+      );
+
+      // ...and the next update pass re-adds it, which is what triggers
+      // Texture.load() for the reload. A stale cache would skip this call.
+      node.update(2, clippingRect);
+      expect(texture.setRenderableOwner).toHaveBeenLastCalledWith(
+        expect.anything(),
+        true,
+      );
+    });
+  });
 });

package/src/core/CoreNode.ts

@@ -46,7 +46,7 @@ import type { IAnimationController } from '../common/IAnimationController.js';
 import { createAnimation } from './animations/CoreAnimation.js';
 import type { CoreShaderNode } from './renderers/CoreShaderNode.js';
 import { AutosizeMode, Autosizer } from './Autosizer.js';
-import { removeChild } from './lib/collectionUtils.js';
+import { removeChild, sortByZIndexStable } from './lib/collectionUtils.js';
 
 export enum CoreNodeRenderState {
   Init = 0,
@@ -63,11 +63,6 @@ const NO_CLIPPING_RECT: RectWithValid = {
   valid: false,
 };
 
-// Hoisted so `sortChildren` doesn't allocate a fresh comparator closure on
-// every z-index reorder.
-const compareZIndex = (a: CoreNode, b: CoreNode): number =>
-  a.props.zIndex - b.props.zIndex;
-
 const CoreNodeRenderStateMap: Map<CoreNodeRenderState, string> = new Map();
 CoreNodeRenderStateMap.set(CoreNodeRenderState.Init, 'init');
 CoreNodeRenderStateMap.set(CoreNodeRenderState.OutOfBounds, 'outOfBounds');
@@ -136,6 +131,7 @@ export enum UpdateType {
    * @remarks
    * CoreNode Properties Updated:
    * - `worldAlpha` = `parent.worldAlpha` * `alpha`
+   *   (or just `alpha` when `ignoreParentAlpha` is enabled)
    */
   WorldAlpha = 64,
 
@@ -250,6 +246,29 @@ export interface CoreNodeProps {
    * @default `1`
    */
   alpha: number;
+  /**
+   * When enabled, the Node's world alpha is computed from its own
+   * {@link alpha} only, ignoring the alpha inherited from its ancestors.
+   *
+   * @remarks
+   * Normally `worldAlpha = parent.worldAlpha * alpha`, so fading a parent
+   * fades every descendant with it. With `ignoreParentAlpha` enabled this
+   * Node keeps rendering at its own alpha while its parent (and the rest of
+   * the subtree) fades.
+   *
+   * Subtrees whose world alpha reaches exactly 0 are culled from rendering
+   * entirely, so this Node still disappears once an ancestor hits alpha 0 —
+   * the prop only has an effect while every ancestor's alpha is above 0.
+   * This keeps the fully-transparent subtree cull free of bookkeeping.
+   *
+   * Descendants of this Node inherit from its world alpha as usual.
+   *
+   * Has no effect inside a render-to-texture subtree: the RTT root's
+   * composited quad is still faded as a single unit by its own world alpha.
+   *
+   * @default `false`
+   */
+  ignoreParentAlpha: boolean;
   /**
    * Autosize
    *
@@ -810,6 +829,14 @@ export class CoreNode extends EventEmitter {
   private hasColorProps = false;
   public textureLoaded = false;
 
+  /**
+   * Last ownership value sent to the current texture via
+   * {@link updateTextureOwnership}. Per (node, texture) pair — must reset to
+   * `false` whenever the texture is swapped or released, or a stale `true`
+   * would skip the re-registration that triggers `Texture.load()`.
+   */
+  private textureOwnership = false;
+
   /**
    * True while this node should render its `placeholderColor` instead of its
    * texture: `placeholderColor` is non-zero, a texture is set, and that
@@ -1066,6 +1093,7 @@ export class CoreNode extends EventEmitter {
     texture.off('failed', this.onTextureFailed);
     texture.off('freed', this.onTextureFreed);
     texture.setRenderableOwner(this._id, false);
+    this.textureOwnership = false;
   }
 
   protected onTextureLoaded: TextureLoadedEventHandler = (_, dimensions) => {
@@ -1453,7 +1481,10 @@ export class CoreNode extends EventEmitter {
     }
 
     if (updateType & UpdateType.WorldAlpha) {
-      this.worldAlpha = parent.worldAlpha * this.props.alpha;
+      this.worldAlpha =
+        props.ignoreParentAlpha === true
+          ? props.alpha
+          : parent.worldAlpha * props.alpha;
       updateType |=
         UpdateType.PremultipliedColors |
         UpdateType.Children |
@@ -1896,6 +1927,10 @@ export class CoreNode extends EventEmitter {
    * Changes the renderable state of the node.
    */
   updateTextureOwnership(isRenderable: boolean) {
+    if (this.textureOwnership === isRenderable) {
+      return;
+    }
+    this.textureOwnership = isRenderable;
     this.texture?.setRenderableOwner(this._id, isRenderable);
   }
 
@@ -2180,7 +2215,7 @@ export class CoreNode extends EventEmitter {
   }
 
   sortChildren() {
-    this.children.sort(compareZIndex);
+    sortByZIndexStable(this.children);
     this.stage.requestRenderListUpdate();
   }
 
@@ -2523,6 +2558,24 @@ export class CoreNode extends EventEmitter {
     this.childUpdateType |= UpdateType.WorldAlpha;
   }
 
+  get ignoreParentAlpha(): boolean {
+    return this.props.ignoreParentAlpha;
+  }
+
+  set ignoreParentAlpha(value: boolean) {
+    if (this.props.ignoreParentAlpha === value) {
+      return;
+    }
+    this.props.ignoreParentAlpha = value;
+    this.setUpdateType(
+      UpdateType.PremultipliedColors |
+        UpdateType.WorldAlpha |
+        UpdateType.Children |
+        UpdateType.IsRenderable,
+    );
+    this.childUpdateType |= UpdateType.WorldAlpha;
+  }
+
   get autosize(): boolean {
     return this.props.autosize;
   }
@@ -3060,6 +3113,7 @@ export class CoreNode extends EventEmitter {
         this.autosizer.setMode(AutosizeMode.Texture); // Set to texture size mode
       }
       value.setRenderableOwner(this._id, this.isRenderable);
+      this.textureOwnership = this.isRenderable;
       this.loadTexture();
     }
 

package/src/core/CoreTextNode.test.ts

@@ -17,6 +17,7 @@ const defaultProps = (
 ): CoreTextNodeProps => ({
   // CoreNodeProps
   alpha: 1,
+  ignoreParentAlpha: false,
   autosize: false,
   boundsMargin: null,
   clipping: false,

package/src/core/CoreTextNode.ts

@@ -266,8 +266,9 @@ export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
         this.setRenderable(false);
 
         if (this.renderState > CoreNodeRenderState.OutOfBounds) {
-          // We do want the texture to load immediately
-          this.texture.setRenderableOwner(this._id, true);
+          // We do want the texture to load immediately. Routed through
+          // updateTextureOwnership so the ownership cache stays in sync.
+          this.updateTextureOwnership(true);
         }
       }
     }

package/src/core/CoreTextureManager.ts

@@ -409,9 +409,9 @@ export class CoreTextureManager extends EventEmitter {
 
     // Anything that arrived before initialization completed is now safe to
     // process. Without this, queued textures would sit until the next frame
-    // tick happens to call processSome().
+    // tick happens to drain them.
     if (this.uploadTextureQueue.size > 0) {
-      this.processSome(Infinity).catch((err) => {
+      this.processUntil(Infinity).catch((err) => {
         console.error('Failed to drain pre-init texture queue:', err);
       });
     }
@@ -587,11 +587,41 @@ export class CoreTextureManager extends EventEmitter {
   }
 
   /**
-   * Process a limited number of uploads.
+   * Upload a single queued texture to the GPU.
    *
-   * @param maxProcessingTime - The maximum processing time in milliseconds
+   * @remarks
+   * Used while animations are running so uploads don't steal time from the
+   * animation. If the dequeued texture already died (failed/freed), nothing is
+   * uploaded this frame and the next call handles the following one.
+   */
+  async processOne(): Promise<void> {
+    if (this.initialized === false) {
+      return;
+    }
+
+    const texture = this.uploadTextureQueue.shift();
+    if (texture === undefined) {
+      return;
+    }
+
+    await this.uploadQueued(texture);
+  }
+
+  /**
+   * Upload queued textures to the GPU until the per-frame time budget runs out.
+   *
+   * @remarks
+   * Called once per frame when idle. Textures are uploaded one-by-one; after
+   * each, the elapsed time is rechecked and processing stops once it exceeds
+   * `maxProcessingTime`, leaving the rest queued for the next frame.
+   *
+   * In normal operation a queued texture's data is already decoded
+   * (`loadTexture` awaits `getTextureData` before enqueuing), so this budgets
+   * GPU upload time. Pass `Infinity` to drain the whole queue.
+   *
+   * @param maxProcessingTime - The time budget for this frame, in milliseconds
    */
-  async processSome(maxProcessingTime: number): Promise<void> {
+  async processUntil(maxProcessingTime: number): Promise<void> {
     if (this.initialized === false) {
       return;
     }
@@ -599,79 +629,54 @@ export class CoreTextureManager extends EventEmitter {
     const platform = this.platform;
     const startTime = platform.getTimeStamp();
 
-    // Decode / fetch ("getTextureData") is IO-bound and parallelisable across
-    // image workers, while GPU upload is effectively serial. Keep a small
-    // sliding window of in-flight data fetches so the next decode runs while
-    // we're uploading the current one.
-    const prefetchLimit = Math.max(1, this.numImageWorkers);
-    const pending: Array<{ texture: Texture; data: Promise<unknown> }> = [];
-
-    // Helper avoids TS narrowing `texture.state` permanently after the first
-    // discriminated check — the property is mutable and can transition across
-    // awaits, so we need to re-read it freshly each time.
-    const isDead = (texture: Texture): boolean =>
-      texture.state === 'failed' || texture.state === 'freed';
-
-    const fillPrefetch = () => {
-      while (pending.length < prefetchLimit) {
-        const texture = this.uploadTextureQueue.shift();
-        if (texture === undefined) break;
-
-        if (isDead(texture)) {
-          continue;
-        }
-
-        // Swallow the rejection here so an early failure doesn't surface as
-        // an unhandled promise rejection while it sits in the prefetch
-        // window; we re-check state after awaiting.
-        const data =
-          texture.textureData === null
-            ? texture.getTextureData().catch((err) => {
-                console.error('Failed to fetch texture data:', err);
-                return null;
-              })
-            : Promise.resolve(texture.textureData);
-
-        pending.push({ texture, data });
+    while (platform.getTimeStamp() - startTime < maxProcessingTime) {
+      const texture = this.uploadTextureQueue.shift();
+      if (texture === undefined) {
+        // Queue drained.
+        break;
       }
-    };
 
-    fillPrefetch();
+      await this.uploadQueued(texture);
+    }
+  }
 
-    while (
-      pending.length > 0 &&
-      platform.getTimeStamp() - startTime < maxProcessingTime
-    ) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const next = pending.shift()!;
-      // Top up the prefetch window before awaiting — the next decode starts
-      // now and overlaps with this upload.
-      fillPrefetch();
+  /**
+   * Decode (if needed) and upload a single already-dequeued texture.
+   *
+   * @remarks
+   * Shared by {@link processOne} and {@link processUntil}. Dead (failed/freed)
+   * textures and upload failures are skipped without throwing.
+   */
+  private async uploadQueued(texture: Texture): Promise<void> {
+    if (this.isTextureDead(texture)) {
+      return;
+    }
 
-      if (isDead(next.texture)) {
-        continue;
+    try {
+      if (texture.textureData === null) {
+        await texture.getTextureData();
       }
-
-      try {
-        await next.data;
-        if (isDead(next.texture)) {
-          continue;
-        }
-        await this.uploadTexture(next.texture);
-      } catch (error) {
-        console.error('Failed to upload texture:', error);
-        // Continue with next texture instead of stopping entire queue
+      if (this.isTextureDead(texture)) {
+        return;
       }
+      await this.uploadTexture(texture);
+    } catch (error) {
+      console.error('Failed to upload texture:', error);
+      // Skip this texture instead of stalling the queue.
     }
+  }
 
-    // Time ran out before we got to these. Put them back so we don't lose
-    // them — their getTextureData() is already in flight and will populate
-    // `textureData` for the next tick.
-    for (const { texture } of pending) {
-      if (!isDead(texture)) {
-        this.uploadTextureQueue.add(texture);
-      }
-    }
+  /**
+   * A texture is "dead" once it has failed or been freed — both terminal for
+   * the upload pipeline.
+   *
+   * @remarks
+   * Kept as a method rather than an inline check so TypeScript doesn't
+   * permanently narrow `state` after the first comparison: the property is
+   * mutable and can transition across the awaits in {@link uploadQueued}.
+   */
+  private isTextureDead(texture: Texture): boolean {
+    return texture.state === 'failed' || texture.state === 'freed';
   }
 
   public hasUpdates(): boolean {

package/src/core/Stage.ts

@@ -379,6 +379,7 @@ export class Stage {
       w: appWidth,
       h: appHeight,
       alpha: 1,
+      ignoreParentAlpha: false,
       autosize: false,
       boundsMargin: null,
       clipping: false,
@@ -594,11 +595,16 @@ export class Stage {
     // Process some textures asynchronously but don't block the frame
     // Use a background task to prevent frame drops
     if (this.txManager.hasUpdates() === true) {
-      const timeLimit = hasActiveAnimations
-        ? this.options.textureProcessingTimeLimit / 2
-        : this.options.textureProcessingTimeLimit;
+      // While animating, upload at most one texture per frame so uploads don't
+      // steal time from the animation; otherwise fill the per-frame time budget.
+      const processing =
+        hasActiveAnimations === true
+          ? this.txManager.processOne()
+          : this.txManager.processUntil(
+              this.options.textureProcessingTimeLimit,
+            );
 
-      this.txManager.processSome(timeLimit).catch((err) => {
+      processing.catch((err) => {
         console.error('Error processing textures:', err);
       });
     }
@@ -1039,6 +1045,7 @@ export class Stage {
       w: props.w ?? 0,
       h: props.h ?? 0,
       alpha: props.alpha ?? 1,
+      ignoreParentAlpha: props.ignoreParentAlpha ?? false,
       autosize: props.autosize ?? false,
       boundsMargin: props.boundsMargin ?? null,
       clipping: props.clipping ?? false,

package/src/core/TextureMemoryManager.test.ts

@@ -175,7 +175,7 @@ function freedCachedTexture(cacheKey: string): Texture & {
     state: 'freed',
     type: TextureType.image,
     preventCleanup: false,
-    renderableOwners: [],
+    renderableOwners: new Set<string | number>(),
     cacheKey,
     free: vi.fn(),
     destroy: vi.fn(),
@@ -206,7 +206,7 @@ describe('TextureMemoryManager — orphaned freed texture eviction', () => {
   it('keeps a freed texture that still has renderable owners', () => {
     const { mgr, keyCache } = makeManager();
     const texture = freedCachedTexture('img:poster.png');
-    (texture.renderableOwners as unknown[]).push(1);
+    texture.renderableOwners.add(1);
     keyCache.set('img:poster.png', texture);
 
     mgr.cleanup();