@lightningjs/renderer 3.0.0-beta8 → 3.0.0

package/src/core/platforms/web/WebPlatform.ts

@@ -1,84 +1,306 @@
-import { Platform } from '../Platform.js';
-import type { Stage } from '../../Stage.js';
-
-export class WebPlatform extends Platform {
-  ////////////////////////
-  // Platform-specific methods
-  ////////////////////////
-
-  override createCanvas(): HTMLCanvasElement {
-    const canvas = document.createElement('canvas');
-    return canvas;
-  }
-
-  override getElementById(id: string): HTMLElement | null {
-    return document.getElementById(id);
-  }
-
-  ////////////////////////
-  // Update loop
-  ////////////////////////
-
-  override startLoop(stage: Stage): void {
-    let isIdle = false;
-    const runLoop = () => {
-      stage.updateFrameTime();
-      stage.updateAnimations();
-
-      if (!stage.hasSceneUpdates()) {
-        // We still need to calculate the fps else it looks like the app is frozen
-        stage.calculateFps();
-        setTimeout(runLoop, 16.666666666666668);
-
-        if (!isIdle) {
-          stage.shManager.cleanup();
-          stage.eventBus.emit('idle');
-          isIdle = true;
-        }
-
-        if (stage.txMemManager.checkCleanup() === true) {
-          stage.txMemManager.cleanup(false);
-        }
-
-        stage.flushFrameEvents();
-        return;
-      }
-
-      isIdle = false;
-      stage.drawFrame();
-      stage.flushFrameEvents();
-      requestAnimationFrame(runLoop);
-    };
-    requestAnimationFrame(runLoop);
-  }
-
-  ////////////////////////
-  // ImageBitmap
-  ////////////////////////
-
-  override createImageBitmap(
-    blob: ImageBitmapSource,
-    sxOrOptions?: number | ImageBitmapOptions,
-    sy?: number,
-    sw?: number,
-    sh?: number,
-    options?: ImageBitmapOptions,
-  ): Promise<ImageBitmap> {
-    if (typeof sxOrOptions === 'number') {
-      return createImageBitmap(
-        blob,
-        sxOrOptions,
-        sy ?? 0,
-        sw ?? 0,
-        sh ?? 0,
-        options,
-      );
-    } else {
-      return createImageBitmap(blob, sxOrOptions);
-    }
-  }
-
-  getTimeStamp(): number {
-    return performance ? performance.now() : Date.now();
-  }
-}
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2026 Comcast Cable Communications Management, LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Platform, type PlatformSettings } from '../Platform.js';
+import {
+  ImageWorkerManager,
+  type ImageWorkerFactory,
+} from './lib/ImageWorker.js';
+import { createImageWorker } from './lib/ImageWorkerDefault.js';
+import type { Stage } from '../../Stage.js';
+import {
+  dataURIToBlob,
+  isBase64Image,
+  convertUrlToAbsolute,
+  createWebGLContext,
+} from './lib/utils.js';
+
+import type { ImageResponse } from '../../textures/ImageTexture.js';
+import { loadSvg } from './lib/textureSvg.js';
+import { loadCompressedTexture } from './lib/textureCompression.js';
+import { WebGlContextWrapper } from './WebGlContextWrapper.js';
+import type { GlContextWrapper } from '../GlContextWrapper.js';
+
+/**
+ * make fontface add not show errors
+ */
+interface FontFaceSetWithAdd extends FontFaceSet {
+  add(font: FontFace): this;
+}
+
+export class WebPlatform extends Platform {
+  private useImageWorker: boolean;
+  private imageWorkerManager: ImageWorkerManager | null = null;
+  private hasWorker = !!self.Worker;
+
+  constructor(settings: PlatformSettings = {}) {
+    super(settings);
+
+    const numImageWorkers = settings.numImageWorkers ?? 0;
+    this.useImageWorker = numImageWorkers > 0 && this.hasWorker;
+
+    if (this.useImageWorker === true) {
+      this.imageWorkerManager = this.createImageWorkerManager(numImageWorkers);
+    }
+  }
+
+  protected createImageWorkerManager(
+    numImageWorkers: number,
+  ): ImageWorkerManager {
+    return new ImageWorkerManager(
+      numImageWorkers,
+      this.getImageWorkerFactory(),
+    );
+  }
+
+  protected getImageWorkerFactory(): ImageWorkerFactory {
+    return createImageWorker;
+  }
+
+  ////////////////////////
+  // Platform-specific methods
+  ////////////////////////
+
+  override createCanvas(): HTMLCanvasElement {
+    return document.createElement('canvas');
+  }
+
+  override createContext(): GlContextWrapper {
+    if (this.canvas === null) {
+      throw new Error('Canvas has not been created yet.');
+    }
+
+    const gl = createWebGLContext(this.canvas, this.settings.forceWebGL2);
+    this.glw = new WebGlContextWrapper(gl);
+    return this.glw;
+  }
+
+  override getElementById(id: string): HTMLElement | null {
+    return document.getElementById(id);
+  }
+
+  ////////////////////////
+  // Update loop
+  ////////////////////////
+
+  override startLoop(stage: Stage): void {
+    let isIdle = false;
+    let lastFrameTime = 0;
+
+    const runLoop = (currentTime: number = 0) => {
+      const targetFrameTime = stage.targetFrameTime;
+
+      // Check if we should throttle this frame
+      if (
+        targetFrameTime > 0 &&
+        currentTime - lastFrameTime < targetFrameTime
+      ) {
+        // Too early for next frame, schedule with setTimeout for precise timing
+        const delay = targetFrameTime - (currentTime - lastFrameTime);
+        setTimeout(() => requestAnimationFrame(runLoop), delay);
+        return;
+      }
+
+      stage.updateFrameTime();
+      stage.updateAnimations();
+
+      if (!stage.hasSceneUpdates()) {
+        // We still need to calculate the fps else it looks like the app is frozen
+        stage.calculateFps();
+
+        if (targetFrameTime > 0) {
+          // Use setTimeout for throttled idle frames
+          setTimeout(
+            () => requestAnimationFrame(runLoop),
+            Math.max(targetFrameTime, 16.666666666666668),
+          );
+        } else {
+          // Use standard idle timeout when not throttling
+          setTimeout(() => requestAnimationFrame(runLoop), 16.666666666666668);
+        }
+
+        if (isIdle === false) {
+          stage.shManager.cleanup();
+          stage.eventBus.emit('idle');
+          isIdle = true;
+        }
+
+        if (stage.txMemManager.checkCleanup() === true) {
+          stage.txMemManager.cleanup();
+        }
+
+        stage.flushFrameEvents();
+        return;
+      }
+
+      if (isIdle === true) {
+        stage.eventBus.emit('active');
+        isIdle = false;
+      }
+
+      stage.drawFrame();
+      stage.flushFrameEvents();
+
+      // Schedule next frame
+      if (targetFrameTime > 0) {
+        // Use setTimeout + rAF combination for precise FPS control
+        const nextFrameDelay = Math.max(
+          0,
+          targetFrameTime - (performance.now() - currentTime),
+        );
+        setTimeout(() => requestAnimationFrame(runLoop), nextFrameDelay);
+      } else {
+        // Use standard rAF when not throttling
+        requestAnimationFrame(runLoop);
+      }
+    };
+    requestAnimationFrame(runLoop);
+  }
+
+  ////////////////////////
+  // Image handling
+  ////////////////////////
+
+  override fetch(url: string): Promise<Blob> {
+    return new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+      xhr.responseType = 'blob';
+      xhr.onreadystatechange = function () {
+        if (xhr.readyState == XMLHttpRequest.DONE) {
+          // On most devices like WebOS and Tizen, the file protocol returns 0 while http(s) protocol returns 200
+          if (xhr.status === 0 || xhr.status === 200) {
+            if (xhr.response instanceof Blob) {
+              resolve(xhr.response);
+            } else {
+              reject(new Error('Expected blob response while loading image.'));
+            }
+          } else {
+            reject(xhr.statusText);
+          }
+        }
+      };
+      xhr.open('GET', url, true);
+      xhr.send(null);
+    });
+  }
+
+  override async createImage(
+    blob: Blob,
+    premultiplyAlpha: boolean | null,
+    sx: number | null,
+    sy: number | null,
+    sw: number | null,
+    sh: number | null,
+  ): Promise<ImageResponse> {
+    const hasAlphaChannel = premultiplyAlpha ?? blob.type.includes('image/png');
+
+    if (sw !== null && sh !== null) {
+      // createImageBitmap with crop
+      const bitmap = await createImageBitmap(blob, sx || 0, sy || 0, sw, sh, {
+        premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
+        colorSpaceConversion: 'none',
+        imageOrientation: 'none',
+      });
+      return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+    }
+
+    // default createImageBitmap without crop but with options
+    const bitmap = await createImageBitmap(blob, {
+      premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
+      colorSpaceConversion: 'none',
+      imageOrientation: 'none',
+    });
+
+    return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+  }
+
+  override async loadImage(
+    src: string,
+    premultiplyAlpha: boolean | null,
+    sx?: number | null,
+    sy?: number | null,
+    sw?: number | null,
+    sh?: number | null,
+  ): Promise<ImageResponse> {
+    const isBase64 = isBase64Image(src);
+    const absoluteSrc = convertUrlToAbsolute(src);
+    const x = sx ?? null;
+    const y = sy ?? null;
+    const width = sw ?? null;
+    const height = sh ?? null;
+
+    // check if image worker is enabled
+    if (this.imageWorkerManager !== null && isBase64 === false) {
+      return this.imageWorkerManager.getImage(
+        absoluteSrc,
+        premultiplyAlpha,
+        x,
+        y,
+        width,
+        height,
+      );
+    }
+
+    // fallback to main thread loading
+    let blob: Blob;
+    if (isBase64 === true) {
+      blob = dataURIToBlob(src);
+    } else {
+      blob = await this.fetch(absoluteSrc);
+    }
+
+    return this.createImage(blob, premultiplyAlpha, x, y, width, height);
+  }
+
+  override async loadSvg(
+    src: string,
+    width: number | null,
+    height: number | null,
+    sx?: number | null,
+    sy?: number | null,
+    sw?: number | null,
+    sh?: number | null,
+  ): Promise<ImageResponse> {
+    return loadSvg(
+      convertUrlToAbsolute(src),
+      width,
+      height,
+      sx ?? null,
+      sy ?? null,
+      sw ?? null,
+      sh ?? null,
+    );
+  }
+
+  override async loadCompressedTexture(src: string): Promise<ImageResponse> {
+    return loadCompressedTexture(convertUrlToAbsolute(src));
+  }
+
+  ////////////////////////
+  // Utilities
+  ////////////////////////
+
+  getTimeStamp(): number {
+    return performance ? performance.now() : Date.now();
+  }
+
+  override addFont(font: FontFace): void {
+    (document.fonts as FontFaceSetWithAdd).add(font);
+  }
+}

package/src/core/platforms/web/WebPlatformChrome50.ts

@@ -0,0 +1,63 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2026 Comcast Cable Communications Management, LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { WebPlatform } from './WebPlatform.js';
+import type { ImageResponse } from '../../textures/ImageTexture.js';
+import type { ImageWorkerFactory } from './lib/ImageWorker.js';
+import { createImageWorkerNoOptions } from './lib/ImageWorkerNoOptions.js';
+
+/**
+ * Chrome 50 Web Platform implementation with limited createImageBitmap support
+ *
+ * @remarks
+ * This platform is designed for Chrome 50 and similar browsers that support
+ * createImageBitmap but with a limited signature (no options or cropping parameters).
+ *
+ * Limitations:
+ * - createImageBitmap is called without options (premultiplyAlpha, colorSpaceConversion, imageOrientation)
+ * - Image cropping (sx, sy, sw, sh parameters) is not supported
+ * - Image workers can still be used if enabled via settings
+ */
+export class WebPlatformChrome50 extends WebPlatform {
+  protected override getImageWorkerFactory(): ImageWorkerFactory {
+    return createImageWorkerNoOptions;
+  }
+
+  override async createImage(
+    blob: Blob,
+    premultiplyAlpha: boolean | null,
+    // Cropping parameters are not supported in Chrome 50
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    sx: number | null,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    sy: number | null,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    sw: number | null,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    sh: number | null,
+  ): Promise<ImageResponse> {
+    const hasAlphaChannel = premultiplyAlpha ?? blob.type.includes('image/png');
+
+    // Chrome 50 createImageBitmap signature: createImageBitmap(blob)
+    // No options or cropping parameters supported
+    const bitmap = await createImageBitmap(blob);
+
+    return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+  }
+}

package/src/core/platforms/web/WebPlatformLegacy.ts

@@ -0,0 +1,150 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2026 Comcast Cable Communications Management, LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { WebPlatform } from './WebPlatform.js';
+import type { PlatformSettings } from '../Platform.js';
+import type { ImageResponse } from '../../textures/ImageTexture.js';
+import type { ImageWorkerFactory } from './lib/ImageWorker.js';
+import { createImageWorkerLegacy } from './lib/ImageWorkerLegacy.js';
+import {
+  isBase64Image,
+  dataURIToBlob,
+  convertUrlToAbsolute,
+} from './lib/utils.js';
+
+/**
+ * Legacy Web Platform implementation that uses Image() instead of createImageBitmap
+ *
+ * @remarks
+ * This platform is designed for environments that don't support createImageBitmap API,
+ * or for compatibility with older browsers. It uses the traditional HTMLImageElement
+ * approach for image loading.
+ *
+ */
+export class WebPlatformLegacy extends WebPlatform {
+  constructor(settings: PlatformSettings = {}) {
+    super({ ...settings, numImageWorkers: settings.numImageWorkers ?? 0 });
+  }
+
+  protected override getImageWorkerFactory(): ImageWorkerFactory {
+    return createImageWorkerLegacy;
+  }
+
+  override async loadImage(
+    src: string,
+    premultiplyAlpha: boolean | null,
+    sx?: number | null,
+    sy?: number | null,
+    sw?: number | null,
+    sh?: number | null,
+  ): Promise<ImageResponse> {
+    const isBase64 = isBase64Image(src);
+
+    if (isBase64 === false && this.settings.numImageWorkers > 0) {
+      return super.loadImage(src, premultiplyAlpha, sx, sy, sw, sh);
+    }
+
+    const absoluteSrc = convertUrlToAbsolute(src);
+
+    // For base64 images, use blob conversion
+    if (isBase64 === true) {
+      const blob = dataURIToBlob(src);
+      return this.createImage(
+        blob,
+        premultiplyAlpha,
+        sx ?? null,
+        sy ?? null,
+        sw ?? null,
+        sh ?? null,
+      );
+    }
+
+    // For regular URLs, load directly without blob conversion
+    const hasAlpha =
+      premultiplyAlpha ?? absoluteSrc.toLowerCase().endsWith('.png');
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+
+    return new Promise<ImageResponse>((resolve, reject) => {
+      img.onload = () => {
+        resolve({ data: img, premultiplyAlpha: hasAlpha });
+      };
+
+      img.onerror = (err) => {
+        const errorMessage =
+          err instanceof Error
+            ? err.message
+            : err instanceof Event
+            ? `Image loading failed for ${img.src}`
+            : 'Unknown image loading error';
+        reject(new Error(`Image loading failed: ${errorMessage}`));
+      };
+
+      img.src = absoluteSrc;
+    });
+  }
+
+  override async createImage(
+    blob: Blob,
+    premultiplyAlpha: boolean | null,
+    // Cropping parameters are not supported in legacy mode
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    sx: number | null,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    sy: number | null,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    sw: number | null,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    sh: number | null,
+  ): Promise<ImageResponse> {
+    const hasAlpha = premultiplyAlpha ?? blob.type.includes('image/png');
+    const src = URL.createObjectURL(blob);
+    const img = new Image();
+
+    if (typeof src === 'string' && isBase64Image(src) === false) {
+      img.crossOrigin = 'anonymous';
+    }
+
+    return new Promise<ImageResponse>((resolve, reject) => {
+      img.onload = () => {
+        URL.revokeObjectURL(src);
+        resolve({ data: img, premultiplyAlpha: hasAlpha });
+      };
+
+      img.onerror = (err) => {
+        URL.revokeObjectURL(src);
+        const errorMessage =
+          err instanceof Error
+            ? err.message
+            : err instanceof Event
+            ? `Image loading failed for ${img.src}`
+            : 'Unknown image loading error';
+        reject(new Error(`Image loading failed: ${errorMessage}`));
+      };
+
+      img.src = src;
+    });
+  }
+
+  override async loadCompressedTexture(src: string): Promise<ImageResponse> {
+    throw new Error(
+      `Compressed textures are not supported in legacy mode. Attempted to load: ${src}`,
+    );
+  }
+}

package/src/core/platforms/web/WebPlatformNext.ts

@@ -0,0 +1,57 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2026 Comcast Cable Communications Management, LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { WebPlatform } from './WebPlatform.js';
+
+/**
+ * Next-generation Web Platform implementation that uses Fetch API
+ *
+ * @remarks
+ * This platform uses the modern Fetch API instead of XMLHttpRequest for
+ * loading image resources. The Fetch API provides a more modern, promise-based
+ * interface for network requests and better streaming capabilities.
+ *
+ * Benefits over XMLHttpRequest:
+ * - Promise-based (no callback-based API)
+ * - Better error handling
+ * - More consistent across browsers
+ * - Better streaming support
+ * - Service Worker compatible
+ *
+ * All other platform features remain the same as WebPlatform.
+ */
+export class WebPlatformNext extends WebPlatform {
+  override async fetch(url: string): Promise<Blob> {
+    try {
+      const response = await fetch(url);
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch resource: ${response.status} ${response.statusText}`,
+        );
+      }
+
+      return await response.blob();
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'Unknown fetch error';
+      throw new Error(`Fetch failed for ${url}: ${errorMessage}`);
+    }
+  }
+}