@solidtv/renderer 1.5.3 → 1.5.4

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

@@ -595,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);
       });
     }

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();

package/src/core/TextureMemoryManager.ts

@@ -349,7 +349,7 @@ export class TextureMemoryManager {
       if (
         evictable === true &&
         texture.preventCleanup === false &&
-        texture.renderableOwners.length === 0 &&
+        texture.renderableOwners.size === 0 &&
         texture.hasListeners() === false
       ) {
         this.destroyTexture(texture);

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

@@ -161,10 +161,11 @@ export class WebGlCtxTexture extends CoreContextTexture {
       );
     }
 
-    // Set to a 1x1 transparent texture
-    glw.texImage2D(0, glw.RGBA, 1, 1, 0, glw.RGBA, glw.UNSIGNED_BYTE, null);
-    this.setTextureMemUse(TRANSPARENT_TEXTURE_DATA.byteLength);
-
+    // No placeholder upload here: every branch below fully (re)uploads the
+    // texture before this method returns, and there is no `await` in between,
+    // so no frame can render an intermediate 1x1. The empty-texture case
+    // (`tdata === null`) does its own 1x1 upload. Uploading a throwaway 1x1
+    // first would be a wasted texImage2D + setTextureMemUse per texture.
     let w = 0;
     let h = 0;
 

package/src/core/textures/SubTexture.ts

@@ -79,7 +79,7 @@ export class SubTexture extends Texture {
     // Resolve parent texture from cache or fallback to provided texture
     this.parentTexture = txManager.resolveParentTexture(this.props.texture);
 
-    if (this.renderableOwners.length > 0) {
+    if (this.renderableOwners.size > 0) {
       this.parentTexture.setRenderableOwner(this.subtextureId, true);
     }
 

package/src/core/textures/Texture.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Texture, type TextureData } from './Texture.js';
+import type { CoreTextureManager } from '../CoreTextureManager.js';
+
+class TestTexture extends Texture {
+  override async getTextureSource(): Promise<TextureData> {
+    return { data: null };
+  }
+}
+
+function makeTexture(): {
+  texture: TestTexture;
+  loadTexture: ReturnType<typeof vi.fn>;
+  onChangeIsRenderable: ReturnType<typeof vi.fn>;
+} {
+  const loadTexture = vi.fn();
+  const txManager = {
+    maxRetryCount: 3,
+    loadTexture,
+  } as unknown as CoreTextureManager;
+  const texture = new TestTexture(txManager);
+  const onChangeIsRenderable = vi.fn();
+  texture.onChangeIsRenderable = onChangeIsRenderable;
+  return { texture, loadTexture, onChangeIsRenderable };
+}
+
+describe('Texture.setRenderableOwner', () => {
+  it('adding an owner fires the 0→1 transition exactly once and loads', () => {
+    const { texture, loadTexture, onChangeIsRenderable } = makeTexture();
+
+    texture.setRenderableOwner(1, true);
+
+    expect(texture.renderableOwners.size).toBe(1);
+    expect(texture.renderable).toBe(true);
+    expect(onChangeIsRenderable).toHaveBeenCalledTimes(1);
+    expect(onChangeIsRenderable).toHaveBeenCalledWith(true);
+    expect(loadTexture).toHaveBeenCalledTimes(1);
+  });
+
+  it('double-add of the same owner is a no-op (size stays 1, one event)', () => {
+    const { texture, loadTexture, onChangeIsRenderable } = makeTexture();
+
+    texture.setRenderableOwner(1, true);
+    texture.setRenderableOwner(1, true);
+
+    expect(texture.renderableOwners.size).toBe(1);
+    expect(onChangeIsRenderable).toHaveBeenCalledTimes(1);
+    expect(loadTexture).toHaveBeenCalledTimes(1);
+  });
+
+  it('a second distinct owner does not re-fire the transition', () => {
+    const { texture, loadTexture, onChangeIsRenderable } = makeTexture();
+
+    texture.setRenderableOwner(1, true);
+    texture.setRenderableOwner(2, true);
+
+    expect(texture.renderableOwners.size).toBe(2);
+    expect(onChangeIsRenderable).toHaveBeenCalledTimes(1);
+    expect(loadTexture).toHaveBeenCalledTimes(1);
+  });
+
+  it('removing a non-member owner does not fire a transition', () => {
+    const { texture, onChangeIsRenderable } = makeTexture();
+
+    texture.setRenderableOwner(1, false);
+
+    expect(texture.renderableOwners.size).toBe(0);
+    expect(texture.renderable).toBe(false);
+    expect(onChangeIsRenderable).not.toHaveBeenCalled();
+  });
+
+  it('1→0 fires onChangeIsRenderable(false) exactly once', () => {
+    const { texture, onChangeIsRenderable } = makeTexture();
+
+    texture.setRenderableOwner(1, true);
+    texture.setRenderableOwner(1, false);
+    texture.setRenderableOwner(1, false);
+
+    expect(texture.renderableOwners.size).toBe(0);
+    expect(texture.renderable).toBe(false);
+    expect(onChangeIsRenderable).toHaveBeenCalledTimes(2);
+    expect(onChangeIsRenderable).toHaveBeenLastCalledWith(false);
+  });
+
+  it('re-adding an owner after 1→0 triggers load again (freed→reload cycle)', () => {
+    const { texture, loadTexture } = makeTexture();
+
+    texture.setRenderableOwner(1, true);
+    texture.setRenderableOwner(1, false);
+    texture.setRenderableOwner(1, true);
+
+    expect(texture.renderable).toBe(true);
+    expect(loadTexture).toHaveBeenCalledTimes(2);
+  });
+
+  it('string and number owners coexist (node ids vs subtexture/font keys)', () => {
+    const { texture } = makeTexture();
+
+    texture.setRenderableOwner(7, true);
+    texture.setRenderableOwner('subtexture-7', true);
+
+    expect(texture.renderableOwners.size).toBe(2);
+
+    texture.setRenderableOwner(7, false);
+    expect(texture.renderableOwners.size).toBe(1);
+    expect(texture.renderable).toBe(true);
+
+    texture.setRenderableOwner('subtexture-7', false);
+    expect(texture.renderableOwners.size).toBe(0);
+    expect(texture.renderable).toBe(false);
+  });
+
+  it('canBeCleanedUp respects remaining owners', () => {
+    const { texture } = makeTexture();
+    // Skip the startup grace period so owners are the deciding factor.
+    texture.isWithinStartupGracePeriod = () => false;
+
+    texture.setRenderableOwner(1, true);
+    expect(texture.canBeCleanedUp()).toBe(false);
+
+    texture.setRenderableOwner(1, false);
+    expect(texture.canBeCleanedUp()).toBe(true);
+  });
+});

package/src/core/textures/Texture.ts

@@ -141,7 +141,7 @@ export abstract class Texture extends EventEmitter {
   // aggregate state
   public state: TextureState = 'initial';
 
-  readonly renderableOwners: any[] = [];
+  readonly renderableOwners: Set<string | number> = new Set();
 
   readonly renderable: boolean = false;
 
@@ -251,7 +251,7 @@ export abstract class Texture extends EventEmitter {
     }
 
     // Don't cleanup if there are still renderable owners
-    if (this.renderableOwners.length > 0) {
+    if (this.renderableOwners.size > 0) {
       return false;
     }
 
@@ -274,28 +274,25 @@ export abstract class Texture extends EventEmitter {
    * @param renderable
    */
   setRenderableOwner(owner: string | number, renderable: boolean): void {
-    const oldSize = this.renderableOwners.length;
-    const hasOwnerIndex = this.renderableOwners.indexOf(owner);
+    const owners = this.renderableOwners;
 
     if (renderable === true) {
-      if (hasOwnerIndex === -1) {
-        // Add the owner to the set
-        this.renderableOwners.push(owner);
+      if (owners.has(owner) === true) {
+        return;
       }
 
-      const newSize = this.renderableOwners.length;
-      if (oldSize !== newSize && newSize === 1) {
+      owners.add(owner);
+      if (owners.size === 1) {
         (this.renderable as boolean) = true;
         this.onChangeIsRenderable?.(true);
         this.load();
       }
     } else {
-      if (hasOwnerIndex !== -1) {
-        this.renderableOwners.splice(hasOwnerIndex, 1);
+      if (owners.delete(owner) === false) {
+        return;
       }
 
-      const newSize = this.renderableOwners.length;
-      if (oldSize !== newSize && newSize === 0) {
+      if (owners.size === 0) {
         (this.renderable as boolean) = false;
         this.onChangeIsRenderable?.(false);
 

package/src/main-api/Inspector.ts

@@ -1104,7 +1104,7 @@ export class Inspector {
     // Update renderable owners count
     div.setAttribute(
       'data-texture-owners',
-      String(texture.renderableOwners.length),
+      String(texture.renderableOwners.size),
     );
 
     // Update retry count