@solidtv/renderer 1.6.0 → 1.6.2

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

@@ -2,26 +2,70 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ImageTexture } from './ImageTexture.js';
 import type { CoreTextureManager } from '../CoreTextureManager.js';
 
+const makeTxManager = (
+  imageBitmapSupported: {
+    basic: boolean;
+    options: boolean;
+    full: boolean;
+    premultiplyHonored: boolean | null;
+  },
+  createImageBitmapMock: () => Promise<unknown>,
+) =>
+  ({
+    imageBitmapSupported,
+    platform: {
+      createImageBitmap: createImageBitmapMock,
+    },
+  } as unknown as CoreTextureManager);
+
 describe('ImageTexture.createImageBitmap', () => {
   beforeEach(() => {
     vi.stubGlobal('ImageBitmap', class {});
   });
 
-  it('passes options to createImageBitmap when no crop is requested and options/full are supported', async () => {
+  it('requests a premultiplied bitmap when options are supported and the option is honored', async () => {
+    const createImageBitmapMock = vi.fn(() =>
+      Promise.resolve({ close: () => {} }),
+    );
+    const txManager = makeTxManager(
+      { basic: true, options: true, full: true, premultiplyHonored: true },
+      createImageBitmapMock,
+    );
+
+    const props = ImageTexture.resolveDefaults({
+      src: 'test.png',
+      premultiplyAlpha: true,
+    });
+    const texture = new ImageTexture(txManager, props);
+
+    const blob = new Blob([], { type: 'image/png' });
+    const result = await texture.createImageBitmap(
+      blob,
+      true,
+      null,
+      null,
+      null,
+      null,
+    );
+
+    expect(createImageBitmapMock).toHaveBeenCalledWith(blob, {
+      premultiplyAlpha: 'premultiply',
+      colorSpaceConversion: 'none',
+      imageOrientation: 'none',
+    });
+
+    // The bitmap is already premultiplied; WebGL must not premultiply again
+    expect(result.premultiplyAlpha).toBe(false);
+  });
+
+  it('requests a straight bitmap and defers premultiply to WebGL when the option is not honored', async () => {
     const createImageBitmapMock = vi.fn(() =>
       Promise.resolve({ close: () => {} }),
     );
-    const txManager = {
-      imageBitmapSupported: {
-        basic: true,
-        options: true,
-        full: true,
-        premultiplyHonored: false,
-      },
-      platform: {
-        createImageBitmap: createImageBitmapMock,
-      },
-    } as unknown as CoreTextureManager;
+    const txManager = makeTxManager(
+      { basic: true, options: true, full: true, premultiplyHonored: false },
+      createImageBitmapMock,
+    );
 
     const props = ImageTexture.resolveDefaults({
       src: 'test.png',
@@ -39,14 +83,13 @@ describe('ImageTexture.createImageBitmap', () => {
       null,
     );
 
-    // It should have called createImageBitmap with the options object
     expect(createImageBitmapMock).toHaveBeenCalledWith(blob, {
       premultiplyAlpha: 'none',
       colorSpaceConversion: 'none',
       imageOrientation: 'none',
     });
 
-    // Since premultiplyHonored is false, useGlPremultiply should be true
+    // Since premultiplyHonored is false, WebGL premultiplies on upload
     expect(result.premultiplyAlpha).toBe(true);
   });
 
@@ -54,17 +97,10 @@ describe('ImageTexture.createImageBitmap', () => {
     const createImageBitmapMock = vi.fn(() =>
       Promise.resolve({ close: () => {} }),
     );
-    const txManager = {
-      imageBitmapSupported: {
-        basic: true,
-        options: false,
-        full: false,
-        premultiplyHonored: null,
-      },
-      platform: {
-        createImageBitmap: createImageBitmapMock,
-      },
-    } as unknown as CoreTextureManager;
+    const txManager = makeTxManager(
+      { basic: true, options: false, full: false, premultiplyHonored: null },
+      createImageBitmapMock,
+    );
 
     const props = ImageTexture.resolveDefaults({
       src: 'test.png',
@@ -85,7 +121,39 @@ describe('ImageTexture.createImageBitmap', () => {
     // It should have called basic createImageBitmap without options
     expect(createImageBitmapMock).toHaveBeenCalledWith(blob);
 
-    // And premultiplyAlpha should be false (browser default is assumed to premultiply)
+    // The browser default is assumed to premultiply; WebGL must not premultiply again
     expect(result.premultiplyAlpha).toBe(false);
   });
+
+  it('defers premultiply to WebGL on basic-only devices when premultiplyAlphaHonored is false', async () => {
+    const createImageBitmapMock = vi.fn(() =>
+      Promise.resolve({ close: () => {} }),
+    );
+    const txManager = makeTxManager(
+      { basic: true, options: false, full: false, premultiplyHonored: false },
+      createImageBitmapMock,
+    );
+
+    const props = ImageTexture.resolveDefaults({
+      src: 'test.png',
+      premultiplyAlpha: true,
+    });
+    const texture = new ImageTexture(txManager, props);
+
+    const blob = new Blob([], { type: 'image/png' });
+    const result = await texture.createImageBitmap(
+      blob,
+      true,
+      null,
+      null,
+      null,
+      null,
+    );
+
+    // Still the basic call — no options are supported on these devices
+    expect(createImageBitmapMock).toHaveBeenCalledWith(blob);
+
+    // Device default returns straight alpha; WebGL premultiplies on upload
+    expect(result.premultiplyAlpha).toBe(true);
+  });
 });

package/src/core/textures/ImageTexture.ts

@@ -225,10 +225,12 @@ export class ImageTexture extends Texture {
     ) {
       // basic createImageBitmap without options or crop
       // this is supported for Chrome v50 to v52/54 that doesn't support options.
-      // The browser default premultiplies, so WebGL must not premultiply again.
+      // The browser default premultiplies, so WebGL must not premultiply again —
+      // except on devices whose default returns straight alpha
+      // (premultiplyAlphaHonored: false); there WebGL premultiplies on upload.
       return {
         data: await this.platform.createImageBitmap(blob),
-        premultiplyAlpha: false,
+        premultiplyAlpha: useGlPremultiply,
       };
     }
 

package/src/main-api/Renderer.ts

@@ -481,6 +481,26 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    */
   numImageWorkers: number;
 
+  /**
+   * Maximum number of image fetch+decode operations allowed to run at once
+   * when image workers are unavailable
+   *
+   * @remarks
+   * Only applies when there is no image worker manager (i.e.
+   * `numImageWorkers === 0`, or workers/`createImageBitmap` are unsupported).
+   * In that mode every image decode runs on the main thread, so a burst — such
+   * as a scroll that makes many image nodes renderable in a single tick — can
+   * fire dozens of decodes back-to-back and starve the render loop. This caps
+   * how many run concurrently; on-screen (priority) textures bypass the cap so
+   * they never wait behind off-screen prefetch.
+   *
+   * Has no effect when image workers are active — the worker pool already
+   * bounds concurrency by its size. Set to `0` to disable the cap (unbounded).
+   *
+   * @defaultValue `4`
+   */
+  imageDecodeConcurrency: number;
+
   /**
    * Renderer Engine
    *
@@ -610,13 +630,17 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    * - Full - Supports createImageBitmap(image, sx, sy, sw, sh, options)
    *
    * Note with auto detection, the renderer will attempt to use the most advanced
-   * version of the API available. If the API is not available, the renderer will
-   * fall back to the next available version.
+   * version of the API available. If the API is not available (e.g. Chrome < 50,
+   * including the Chrome 38 support floor), the renderer falls back to loading
+   * images via `new Image()`.
    *
-   * This will affect startup performance as the renderer will need to determine
-   * the supported version of the API.
+   * `'auto'` runs a small startup probe (a 1x1 PNG) to determine support; this
+   * adds a negligible one-time startup cost. Set an explicit value (`'full'`,
+   * `'options'`, `'basic'`) to skip the probe ONLY when the target runtime is
+   * known to support that level — forcing a level the runtime lacks will fail
+   * to load images. When in doubt, use `'auto'`.
    *
-   * @defaultValue `full`
+   * @defaultValue `auto`
    */
   createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
 
@@ -630,12 +654,16 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    * ignore it, returning straight (non-premultiplied) alpha. This causes edge
    * "ghosting" on images with transparency.
    *
-   * Set to `'auto'` to detect via a cheap startup probe (one 1×1 texture
-   * upload + framebuffer readback). Set to a boolean to force the value. Leave
-   * unset to assume the option is honored — the default, which preserves
-   * existing behavior with no probe overhead.
+   * `'auto'` (the default) detects via a cheap startup probe (one 1×1 PNG
+   * decode + texture upload + framebuffer readback). On devices that honor the
+   * option — the vast majority — the probe returns `true` and behavior is
+   * identical to assuming it honored; only devices that actually ignore it
+   * (e.g. the Movistar STB) switch to the WebGL-side premultiply fallback, so
+   * the change is invisible everywhere it isn't needed. Set to a boolean to
+   * force the value and skip the probe (`false` forces the GL-premultiply
+   * fallback; `true` skips it).
    *
-   * @defaultValue `true` (assume honored; no probe)
+   * @defaultValue `'auto'` (probe once at startup)
    */
   premultiplyAlphaHonored?: boolean | 'auto';
 
@@ -781,6 +809,10 @@ export class RendererMain extends EventEmitter {
       textLayoutCacheSize: settings.textLayoutCacheSize ?? 250,
       numImageWorkers:
         settings.numImageWorkers !== undefined ? settings.numImageWorkers : 2,
+      imageDecodeConcurrency:
+        settings.imageDecodeConcurrency !== undefined
+          ? settings.imageDecodeConcurrency
+          : 4,
       enableContextSpy: settings.enableContextSpy ?? false,
       forceWebGL2: settings.forceWebGL2 ?? false,
       disableVertexArrayObject: settings.disableVertexArrayObject ?? false,
@@ -792,12 +824,12 @@ export class RendererMain extends EventEmitter {
       textBaselineMode: settings.textBaselineMode ?? 'optical',
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
       canvas: settings.canvas,
-      createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
-      // undefined -> true (assume honored, no probe); 'auto' -> probe;
-      // explicit boolean -> force the value.
+      createImageBitmapSupport: settings.createImageBitmapSupport || 'auto',
+      // undefined -> 'auto' (probe once at startup); 'auto' -> probe;
+      // explicit boolean -> force the value, skip the probe.
       premultiplyAlphaHonored:
         settings.premultiplyAlphaHonored === undefined
-          ? true
+          ? 'auto'
           : settings.premultiplyAlphaHonored,
       platform: settings.platform || null,
       maxRetryCount: settings.maxRetryCount ?? 5,
@@ -854,6 +886,7 @@ export class RendererMain extends EventEmitter {
       fpsUpdateInterval: settings.fpsUpdateInterval!,
       enableClear: settings.enableClear!,
       numImageWorkers: settings.numImageWorkers!,
+      imageDecodeConcurrency: settings.imageDecodeConcurrency!,
       renderEngine: settings.renderEngine!,
       textureMemory: resolvedTxSettings,
       eventBus: this,