@solidtv/renderer 1.5.0 → 1.5.1

package/src/core/TextureMemoryManager.ts

@@ -205,11 +205,20 @@ export class TextureMemoryManager {
   }
 
   /**
-   * Destroy a texture and remove it from the memory manager
+   * Destroy a texture, evict its cache entry, and remove it from the memory
+   * manager.
+   *
+   * @remarks
+   * Private on purpose: `destroy()` calls `removeAllListeners()`, so running
+   * this on a texture that still has subscribers severs a live `CoreNode`'s
+   * (or `SubTexture`'s) connection — the blank-poster bug. The only safe
+   * entry point is {@link evictOrphanedTextures}, which proves the texture
+   * is unreferenced first. For memory pressure use {@link freeTexture},
+   * which is reversible.
    *
    * @param texture - The texture to destroy
    */
-  destroyTexture(texture: Texture) {
+  private destroyTexture(texture: Texture) {
     if (this.debugLogging === true) {
       console.log(
         `[TextureMemoryManager] Destroying texture. State: ${texture.state}`,
@@ -278,6 +287,8 @@ export class TextureMemoryManager {
       }
     }
 
+    this.evictOrphanedTextures();
+
     if (this.memUsed >= this.criticalThreshold) {
       this.stage.queueFrameEvent('criticalCleanupFailed', {
         memUsed: this.memUsed,
@@ -300,6 +311,52 @@ export class TextureMemoryManager {
     }
   }
 
+  /**
+   * Destroy-and-evict freed textures that nothing references anymore.
+   *
+   * @remarks
+   * {@link freeTexture} intentionally keeps the texture's cache entry and
+   * listeners so a live `CoreNode` can reload it in place. But once the last
+   * referencing node is destroyed (`unloadTexture` removes its listeners and
+   * owner), the freed texture's `keyCache` entry can never be displayed again
+   * — without eviction the cache grows unboundedly in apps cycling many
+   * unique textures.
+   *
+   * A texture is an orphan only when it has zero `renderableOwners` AND zero
+   * event listeners: every live referencer (`CoreNode.loadTextureTask`,
+   * `SubTexture`) subscribes via `on()`. A texture with any listener must
+   * NEVER be destroyed here — `destroy()` calls `removeAllListeners()`, which
+   * would sever the node's subscription and reintroduce the blank-poster bug
+   * that {@link freeTexture} exists to prevent.
+   *
+   * `'initial'` and `'failed'` orphans leak the same way (created or failed,
+   * then the node was destroyed before the texture ever loaded; nothing will
+   * ever retry a `'failed'` texture without a listener). They are evicted only
+   * after the startup grace period: a node created this same frame subscribes
+   * in a queued microtask, so a fresh texture can look orphaned during a
+   * same-frame cleanup. In-flight states (`'fetching'`/`'loading'`/`'fetched'`)
+   * are never evicted; `'loaded'` orphans go through the pressure-driven free
+   * loop first and are swept here as `'freed'` on a later pass.
+   */
+  private evictOrphanedTextures(): void {
+    const keyCache = this.stage.txManager.keyCache;
+    for (const texture of keyCache.values()) {
+      const state = texture.state;
+      const evictable =
+        state === 'freed' ||
+        ((state === 'initial' || state === 'failed') &&
+          texture.isWithinStartupGracePeriod() === false);
+      if (
+        evictable === true &&
+        texture.preventCleanup === false &&
+        texture.renderableOwners.length === 0 &&
+        texture.hasListeners() === false
+      ) {
+        this.destroyTexture(texture);
+      }
+    }
+  }
+
   /**
    * Get the current texture memory usage information
    *

package/src/core/renderers/canvas/CanvasRenderer.ts

@@ -52,7 +52,13 @@ export class CanvasRenderer extends CoreRenderer {
     const ctx = this.context;
     const { tx, ty, ta, tb, tc, td } = node.globalTransform!;
     const clippingRect = node.clippingRect;
-    let texture = (node.props.texture || this.stage.defaultTexture) as Texture;
+    // While a placeholder is showing, render the color-rect path (the default
+    // ColorTexture) tinted by the node's premultiplied placeholder color.
+    let texture = (
+      node.placeholderActive === true
+        ? this.stage.defaultTexture
+        : node.props.texture || this.stage.defaultTexture
+    ) as Texture;
     // The Canvas2D renderer only supports image textures, no textures are used for color blocks
     if (texture !== null) {
       const textureType = texture.type;

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

@@ -471,7 +471,12 @@ export class WebGlRenderer extends CoreRenderer {
     }
 
     const props = node.props;
-    let tx = props.texture || this.stage.defaultTexture!;
+    // While a placeholder is showing, the quad samples the shared 1x1 white
+    // texture tinted by the node's premultiplied placeholder color.
+    let tx =
+      node.placeholderActive === true
+        ? this.stage.defaultTexture!
+        : props.texture || this.stage.defaultTexture!;
 
     if (tx.type === TextureType.subTexture) {
       tx = (tx as SubTexture).parentTexture;

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

@@ -30,6 +30,35 @@ export class WebGlShaderProgram implements CoreShaderProgram {
   public isDestroyed = false;
   supportsIndexedTextures = false;
 
+  /**
+   * Shadow copies of this program's GL uniform state, used by
+   * {@link bindRenderOp} to skip redundant gl.uniform* calls.
+   *
+   * @remarks
+   * GL uniform values are state on the program object and persist across
+   * useProgram switches, and bindRenderOp is the only writer of these
+   * uniforms, so the shadows always mirror GL truth — even when ops using
+   * other programs are interleaved between two ops of this program.
+   *
+   * `lastBoundUniforms` tracks the shader node's uniform collection by
+   * identity: collections are created once, filled once, and shared by
+   * reference across shader nodes with the same value key (see
+   * WebGlShaderNode.update), so reference equality implies value equality.
+   * The failure direction is safe — a new collection holding identical
+   * values just causes a redundant upload, never a wrong skip.
+   *
+   * Sentinels: -1 never collides with real pixel ratios, resolutions,
+   * alphas, dimensions, or time values (all >= 0).
+   */
+  protected lastBoundUniforms: unknown = null;
+  protected lastPixelRatio = -1;
+  protected lastResolutionW = -1;
+  protected lastResolutionH = -1;
+  protected lastAlpha = -1;
+  protected lastDimensionsW = -1;
+  protected lastDimensionsH = -1;
+  protected lastTime = -1;
+
   /**
    * Cached Vertex Array Objects, keyed by the buffer collection they capture.
    *
@@ -198,44 +227,78 @@ export class WebGlShaderProgram implements CoreShaderProgram {
       return;
     }
 
-    // Bind render texture framebuffer dimensions as resolution
-    // if the parent has a render texture
+    // Resolve target pixel ratio / resolution, then compare-and-set against
+    // the program's shadow state. Each gl.uniform* call below crosses into
+    // the GPU-process command buffer, so skipping value-identical re-uploads
+    // is a real per-op CPU saving on embedded targets.
+    let pixelRatio: number;
+    let resolutionW: number;
+    let resolutionH: number;
     if (USE_RTT && parentHasRenderTexture === true && framebufferDimensions) {
-      const { w, h } = framebufferDimensions;
       // Force pixel ratio to 1.0 for render textures since they are always 1:1
       // the final render texture will be rendered to the screen with the correct pixel ratio
-      this.glw.uniform1f('u_pixelRatio', 1.0);
-
+      pixelRatio = 1.0;
       // Set resolution to the framebuffer dimensions
-      this.glw.uniform2f('u_resolution', w, h);
+      resolutionW = framebufferDimensions.w;
+      resolutionH = framebufferDimensions.h;
     } else {
-      this.glw.uniform1f('u_pixelRatio', renderOp.stage.pixelRatio);
+      pixelRatio = renderOp.stage.pixelRatio;
+      resolutionW = this.glw.canvas.width;
+      resolutionH = this.glw.canvas.height;
+    }
 
-      this.glw.uniform2f(
-        'u_resolution',
-        this.glw.canvas.width,
-        this.glw.canvas.height,
-      );
+    if (pixelRatio !== this.lastPixelRatio) {
+      this.glw.uniform1f('u_pixelRatio', pixelRatio);
+      this.lastPixelRatio = pixelRatio;
     }
 
-    if (this.useTimeValue === true) {
+    if (
+      resolutionW !== this.lastResolutionW ||
+      resolutionH !== this.lastResolutionH
+    ) {
+      this.glw.uniform2f('u_resolution', resolutionW, resolutionH);
+      this.lastResolutionW = resolutionW;
+      this.lastResolutionH = resolutionH;
+    }
+
+    if (this.useTimeValue === true && renderOp.time !== this.lastTime) {
       this.glw.uniform1f('u_time', renderOp.time);
+      this.lastTime = renderOp.time;
     }
 
-    if (this.useSystemAlpha === true) {
+    if (
+      this.useSystemAlpha === true &&
+      renderOp.worldAlpha !== this.lastAlpha
+    ) {
       this.glw.uniform1f('u_alpha', renderOp.worldAlpha);
+      this.lastAlpha = renderOp.worldAlpha;
     }
 
-    if (this.useSystemDimensions === true) {
+    if (
+      this.useSystemDimensions === true &&
+      (renderOp.w !== this.lastDimensionsW ||
+        renderOp.h !== this.lastDimensionsH)
+    ) {
       this.glw.uniform2f('u_dimensions', renderOp.w, renderOp.h);
+      this.lastDimensionsW = renderOp.w;
+      this.lastDimensionsH = renderOp.h;
     }
 
     const shader = renderOp.shader as WebGlShaderNode;
     if (shader.props !== undefined) {
       /**
        * loop over all precalculated uniform types
+       *
+       * Collections are immutable after being filled and shared by reference
+       * across shader nodes with equal value keys, so when the same object is
+       * already bound the GL program still holds exactly these values and the
+       * whole pass (loops + gl calls) can be skipped.
        */
       const uniforms = shader.uniforms;
+      if ((uniforms as unknown) === this.lastBoundUniforms) {
+        return;
+      }
+      this.lastBoundUniforms = uniforms;
 
       for (const key in uniforms.single) {
         const { method, value } = uniforms.single[key]!;

package/src/core/renderers/webgl/WebGlShaderProgram.uniformDedup.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, it, vi } from 'vitest';
+import { WebGlShaderProgram } from './WebGlShaderProgram.js';
+
+/**
+ * Tests for the redundant-uniform-upload skip in bindRenderOp.
+ *
+ * The program instance is created without running the constructor (which
+ * compiles GLSL against a live GL context); the fields bindRenderOp touches
+ * are populated manually, and bindTextures/bindBufferCollection are stubbed.
+ */
+
+type FakeGlw = {
+  uniform1f: ReturnType<typeof vi.fn>;
+  uniform2f: ReturnType<typeof vi.fn>;
+  uniform4f: ReturnType<typeof vi.fn>;
+  canvas: { width: number; height: number };
+};
+
+const makeProgram = (): { program: WebGlShaderProgram; glw: FakeGlw } => {
+  const glw: FakeGlw = {
+    uniform1f: vi.fn(),
+    uniform2f: vi.fn(),
+    uniform4f: vi.fn(),
+    canvas: { width: 1920, height: 1080 },
+  };
+
+  const program = Object.create(
+    WebGlShaderProgram.prototype,
+  ) as WebGlShaderProgram;
+  const p = program as unknown as Record<string, unknown>;
+  p['glw'] = glw;
+  p['useSystemAlpha'] = true;
+  p['useSystemDimensions'] = true;
+  p['useTimeValue'] = false;
+  p['lastBoundUniforms'] = null;
+  p['lastPixelRatio'] = -1;
+  p['lastResolutionW'] = -1;
+  p['lastResolutionH'] = -1;
+  p['lastAlpha'] = -1;
+  p['lastDimensionsW'] = -1;
+  p['lastDimensionsH'] = -1;
+  p['lastTime'] = -1;
+  // Stub the buffer/texture binding done before the uniform pass
+  p['bindTextures'] = vi.fn();
+  p['bindBufferCollection'] = vi.fn();
+  return { program, glw };
+};
+
+const makeUniforms = () => ({
+  single: {
+    u_borderGap: { method: 'uniform1f', value: 0 },
+  },
+  vec2: {},
+  vec3: {},
+  vec4: {
+    u_radius: { method: 'uniform4f', value: [16, 16, 16, 16] },
+  },
+});
+
+const makeOp = (
+  uniforms: ReturnType<typeof makeUniforms>,
+  overrides?: Record<string, unknown>,
+) => ({
+  isCoreNode: true,
+  rtt: false,
+  parentHasRenderTexture: false,
+  parentFramebufferDimensions: null,
+  framebufferDimensions: null,
+  stage: { pixelRatio: 2 },
+  time: 0,
+  worldAlpha: 1,
+  w: 200,
+  h: 100,
+  renderOpTextures: [],
+  quadBufferCollection: {},
+  shader: { props: {}, uniforms },
+  ...overrides,
+});
+
+const totalCalls = (glw: FakeGlw): number =>
+  glw.uniform1f.mock.calls.length +
+  glw.uniform2f.mock.calls.length +
+  glw.uniform4f.mock.calls.length;
+
+describe('bindRenderOp uniform dedup', () => {
+  it('should upload everything on the first bind', () => {
+    const { program, glw } = makeProgram();
+    const uniforms = makeUniforms();
+
+    program.bindRenderOp(makeOp(uniforms) as never);
+
+    // u_pixelRatio, u_alpha, u_borderGap (1f) + u_resolution, u_dimensions (2f) + u_radius (4f)
+    expect(glw.uniform1f.mock.calls.length).toBe(3);
+    expect(glw.uniform2f.mock.calls.length).toBe(2);
+    expect(glw.uniform4f.mock.calls.length).toBe(1);
+  });
+
+  it('should issue zero uniform calls on an identical re-bind', () => {
+    const { program, glw } = makeProgram();
+    const uniforms = makeUniforms();
+
+    program.bindRenderOp(makeOp(uniforms) as never);
+    glw.uniform1f.mockClear();
+    glw.uniform2f.mockClear();
+    glw.uniform4f.mockClear();
+
+    program.bindRenderOp(makeOp(uniforms) as never);
+
+    expect(totalCalls(glw)).toBe(0);
+  });
+
+  it('should skip across interleaved ops (shared collection, different op objects)', () => {
+    const { program, glw } = makeProgram();
+    const uniforms = makeUniforms();
+
+    // Two distinct ops (different cards) sharing the value-cached collection
+    program.bindRenderOp(makeOp(uniforms) as never);
+    glw.uniform1f.mockClear();
+    glw.uniform2f.mockClear();
+    glw.uniform4f.mockClear();
+
+    // GL uniform state persists on the program across useProgram switches,
+    // so an op of another program in between changes nothing here.
+    program.bindRenderOp(makeOp(uniforms) as never);
+
+    expect(totalCalls(glw)).toBe(0);
+  });
+
+  it('should re-upload only the changed system uniform', () => {
+    const { program, glw } = makeProgram();
+    const uniforms = makeUniforms();
+
+    program.bindRenderOp(makeOp(uniforms) as never);
+    glw.uniform1f.mockClear();
+    glw.uniform2f.mockClear();
+    glw.uniform4f.mockClear();
+
+    program.bindRenderOp(makeOp(uniforms, { worldAlpha: 0.5 }) as never);
+
+    expect(glw.uniform1f.mock.calls.length).toBe(1);
+    expect(glw.uniform1f.mock.calls[0]![0]).toBe('u_alpha');
+    expect(glw.uniform1f.mock.calls[0]![1]).toBe(0.5);
+    expect(glw.uniform2f.mock.calls.length).toBe(0);
+    expect(glw.uniform4f.mock.calls.length).toBe(0);
+  });
+
+  it('should re-upload dimensions when the op size differs', () => {
+    const { program, glw } = makeProgram();
+    const uniforms = makeUniforms();
+
+    program.bindRenderOp(makeOp(uniforms) as never);
+    glw.uniform2f.mockClear();
+
+    program.bindRenderOp(makeOp(uniforms, { w: 300, h: 150 }) as never);
+
+    expect(glw.uniform2f.mock.calls.length).toBe(1);
+    expect(glw.uniform2f.mock.calls[0]![0]).toBe('u_dimensions');
+  });
+
+  it('should re-run the collection pass for a different collection object', () => {
+    const { program, glw } = makeProgram();
+    const uniformsA = makeUniforms();
+    const uniformsB = makeUniforms(); // identical values, distinct identity
+
+    program.bindRenderOp(makeOp(uniformsA) as never);
+    glw.uniform1f.mockClear();
+    glw.uniform4f.mockClear();
+
+    program.bindRenderOp(makeOp(uniformsB) as never);
+
+    // Conservative direction: new object => redundant upload, never a skip
+    expect(glw.uniform1f.mock.calls.length).toBe(1); // u_borderGap
+    expect(glw.uniform4f.mock.calls.length).toBe(1); // u_radius
+  });
+
+  it('should re-upload pixel ratio and resolution across an RTT flip', () => {
+    const { program, glw } = makeProgram();
+    const uniforms = makeUniforms();
+
+    program.bindRenderOp(makeOp(uniforms) as never);
+    glw.uniform1f.mockClear();
+    glw.uniform2f.mockClear();
+
+    // RTT op: pixelRatio forced to 1, resolution = framebuffer dimensions
+    program.bindRenderOp(
+      makeOp(uniforms, {
+        isCoreNode: false,
+        parentHasRenderTexture: true,
+        framebufferDimensions: { w: 512, h: 256 },
+      }) as never,
+    );
+
+    const calls1f = glw.uniform1f.mock.calls;
+    const calls2f = glw.uniform2f.mock.calls;
+    expect(calls1f.some((c) => c[0] === 'u_pixelRatio' && c[1] === 1)).toBe(
+      true,
+    );
+    expect(calls2f.some((c) => c[0] === 'u_resolution' && c[1] === 512)).toBe(
+      true,
+    );
+
+    glw.uniform1f.mockClear();
+    glw.uniform2f.mockClear();
+
+    // Back to screen: values flip back and must re-upload
+    program.bindRenderOp(makeOp(uniforms) as never);
+    expect(
+      glw.uniform1f.mock.calls.some(
+        (c) => c[0] === 'u_pixelRatio' && c[1] === 2,
+      ),
+    ).toBe(true);
+    expect(
+      glw.uniform2f.mock.calls.some(
+        (c) => c[0] === 'u_resolution' && c[1] === 1920,
+      ),
+    ).toBe(true);
+  });
+
+  it('should skip the collection pass entirely for propless shaders', () => {
+    const { program, glw } = makeProgram();
+
+    program.bindRenderOp(
+      makeOp(makeUniforms(), {
+        shader: { props: undefined, uniforms: makeUniforms() },
+      }) as never,
+    );
+
+    // Only system uniforms: pixelRatio + alpha (1f), resolution + dimensions (2f)
+    expect(glw.uniform1f.mock.calls.length).toBe(2);
+    expect(glw.uniform2f.mock.calls.length).toBe(2);
+    expect(glw.uniform4f.mock.calls.length).toBe(0);
+  });
+});