@solidtv/renderer 1.2.9 → 1.3.0

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

@@ -174,6 +174,8 @@ export class WebGlRenderer extends CoreRenderer {
     const glw = (this.glw = new WebGlContextWrapper(gl));
     glw.viewport(0, 0, options.canvas.width, options.canvas.height);
 
+    this.attachContextLossListeners(options.canvas);
+
     this.updateClearColor(this.stage.clearColor);
 
     glw.setBlend(true);
@@ -300,6 +302,32 @@ export class WebGlRenderer extends CoreRenderer {
     ]);
   }
 
+  /**
+   * Listen for WebGL context loss on the canvas.
+   *
+   * @remarks
+   * On low-RAM devices (e.g. Chromium 123+ after backgrounding) the GPU
+   * context is dropped, after which `gl.createTexture()` and friends return
+   * null and the engine would crash. We pause the render loop via the Stage
+   * flag and surface a `contextLost` event so consumers can react.
+   *
+   * We intentionally do NOT call `event.preventDefault()` (which would ask the
+   * browser to restore the context) and do NOT listen for
+   * `webglcontextrestored`: the engine cannot rebuild its GPU resources
+   * in-place, so the supported recovery is to reload the app. See BROWSERS.md.
+   */
+  private attachContextLossListeners(
+    canvas: HTMLCanvasElement | OffscreenCanvas,
+  ): void {
+    if ('addEventListener' in canvas === false) {
+      return;
+    }
+    const target = canvas as HTMLCanvasElement;
+    target.addEventListener('webglcontextlost', () => {
+      this.stage.setContextLost();
+    });
+  }
+
   reset() {
     const { glw } = this;
     if (DIRTY_QUAD_BUFFER) {

package/src/core/textures/ImageTexture.ts

@@ -192,6 +192,18 @@ export class ImageTexture extends Texture {
     const hasAlphaChannel = premultiplyAlpha ?? blob.type.includes('image/png');
     const imageBitmapSupported = this.txManager.imageBitmapSupported;
 
+    // When the device does NOT honor the createImageBitmap premultiply option
+    // (e.g. older Safari), request a straight ('none') bitmap and let WebGL
+    // premultiply on upload instead. `premultiplyAlpha` in the returned
+    // TextureData means "WebGL should premultiply this source on upload".
+    const useGlPremultiply =
+      hasAlphaChannel === true &&
+      imageBitmapSupported.premultiplyHonored === false;
+    const bitmapMode: 'premultiply' | 'none' =
+      hasAlphaChannel === true && useGlPremultiply === false
+        ? 'premultiply'
+        : 'none';
+
     if (imageBitmapSupported.full === true && sw !== null && sh !== null) {
       // createImageBitmap with crop
       const bitmap = await this.platform.createImageBitmap(
@@ -201,28 +213,29 @@ export class ImageTexture extends Texture {
         sw,
         sh,
         {
-          premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
+          premultiplyAlpha: bitmapMode,
           colorSpaceConversion: 'none',
           imageOrientation: 'none',
         },
       );
-      return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+      return { data: bitmap, premultiplyAlpha: useGlPremultiply };
     } else if (imageBitmapSupported.basic === true) {
       // basic createImageBitmap without options or crop
-      // this is supported for Chrome v50 to v52/54 that doesn't support options
+      // this is supported for Chrome v50 to v52/54 that doesn't support options.
+      // The browser default premultiplies, so WebGL must not premultiply again.
       return {
         data: await this.platform.createImageBitmap(blob),
-        premultiplyAlpha: hasAlphaChannel,
+        premultiplyAlpha: false,
       };
     }
 
     // default createImageBitmap without crop but with options
     const bitmap = await this.platform.createImageBitmap(blob, {
-      premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
+      premultiplyAlpha: bitmapMode,
       colorSpaceConversion: 'none',
       imageOrientation: 'none',
     });
-    return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+    return { data: bitmap, premultiplyAlpha: useGlPremultiply };
   }
 
   async loadImage(src: string) {
@@ -274,9 +287,14 @@ export class ImageTexture extends Texture {
       };
     }
 
+    // The loader computes whether WebGL should premultiply this source on
+    // upload (it depends on the source type and on whether createImageBitmap
+    // honored the premultiply option). Preserve it; fall back to the prop only
+    // when the loader didn't decide.
     return {
       data: resp.data,
-      premultiplyAlpha: this.props.premultiplyAlpha ?? true,
+      premultiplyAlpha:
+        resp.premultiplyAlpha ?? this.props.premultiplyAlpha ?? true,
     };
   }
 

package/src/main-api/Renderer.ts

@@ -145,6 +145,28 @@ export interface RendererMainCriticalCleanupFailedEvent {
   criticalThreshold: number;
 }
 
+/**
+ * WebGL Context Lost Event Data
+ *
+ * @remarks
+ * Fired when the underlying WebGL context is lost (e.g. on low-RAM devices
+ * running Chromium 123+ after the app has been backgrounded). The render loop
+ * stops; in-engine GL resources are NOT rebuilt, so the supported handling is
+ * to reload the app.
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('contextLost', () => {
+ *   window.location.reload();
+ * });
+ * ```
+ */
+export interface RendererMainContextLostEvent {
+  /** This event has no payload - listen without parameters */
+  readonly __eventHasNoPayload?: never;
+}
+
 /**
  * Settings for the Renderer that can be updated during runtime.
  */
@@ -436,6 +458,25 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    */
   createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
 
+  /**
+   * Override for whether `createImageBitmap(..., { premultiplyAlpha: 'premultiply' })`
+   * is actually honored by the target device.
+   *
+   * @remarks
+   * Some older browsers (notably older Safari/WebKit) accept the
+   * `premultiplyAlpha: 'premultiply'` option without throwing but silently
+   * 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.
+   *
+   * @defaultValue `true` (assume honored; no probe)
+   */
+  premultiplyAlphaHonored?: boolean | 'auto';
+
   /**
    * Provide an alternative platform abstraction layer
    *
@@ -506,6 +547,7 @@ export type RendererMainSettings = RendererRuntimeSettings & {
  * @see {@link RendererMainIdleEvent}
  * @see {@link RendererMainCriticalCleanupEvent}
  * @see {@link RendererMainCriticalCleanupFailedEvent}
+ * @see {@link RendererMainContextLostEvent}
  *
  * @fires RendererMain#fpsUpdate
  * @fires RendererMain#frameTick
@@ -513,6 +555,7 @@ export type RendererMainSettings = RendererRuntimeSettings & {
  * @fires RendererMain#idle
  * @fires RendererMain#criticalCleanup
  * @fires RendererMain#criticalCleanupFailed
+ * @fires RendererMain#contextLost
  */
 export class RendererMain extends EventEmitter {
   readonly root: INode;
@@ -562,6 +605,12 @@ export class RendererMain extends EventEmitter {
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
       canvas: settings.canvas,
       createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
+      // undefined -> true (assume honored, no probe); 'auto' -> probe;
+      // explicit boolean -> force the value.
+      premultiplyAlphaHonored:
+        settings.premultiplyAlphaHonored === undefined
+          ? true
+          : settings.premultiplyAlphaHonored,
       platform: settings.platform || null,
       maxRetryCount: settings.maxRetryCount ?? 5,
     };
@@ -622,6 +671,7 @@ export class RendererMain extends EventEmitter {
       targetFPS: settings.targetFPS!,
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit!,
       createImageBitmapSupport: settings.createImageBitmapSupport!,
+      premultiplyAlphaHonored: settings.premultiplyAlphaHonored,
       platform,
       maxRetryCount: settings.maxRetryCount ?? 5,
     });