@lightningjs/renderer 3.0.0-beta21 → 3.0.0-beta23

package/src/core/{lib → platforms/web}/WebGlContextWrapper.ts

@@ -1,14 +1,34 @@
+/*
+ * 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.
+ */
+
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable @typescript-eslint/no-unsafe-argument */
 
-import { assertTruthy, isProductionEnvironment } from '../../utils.js';
 import type {
   Vec2,
   Vec3,
   Vec4,
-} from '../renderers/webgl/internal/ShaderUtils.js';
-import { isWebGl2 } from '../renderers/webgl/internal/WebGlUtils.js';
+} from '../../renderers/webgl/internal/ShaderUtils.js';
+import { isWebGl2 } from '../../renderers/webgl/internal/WebGlUtils.js';
+import { GlContextWrapper } from '../GlContextWrapper.js';
+import type { CompressedData } from '../../textures/Texture.js';
 
 /**
  * Optimized WebGL Context Wrapper
@@ -29,7 +49,7 @@ import { isWebGl2 } from '../renderers/webgl/internal/WebGlUtils.js';
  * A subset of GLenum constants are also exposed as properties on this class
  * for convenience.
  */
-export class WebGlContextWrapper {
+export class WebGlContextWrapper extends GlContextWrapper {
   //#region Cached WebGL State
   private activeTextureUnit = 0;
   private texture2dUnits: Array<WebGLTexture | null>;
@@ -97,6 +117,7 @@ export class WebGlContextWrapper {
   //#endregion WebGL Enums
 
   constructor(private gl: WebGLRenderingContext | WebGL2RenderingContext) {
+    super();
     // The following code extracts the current state of the WebGL context
     // to our local JavaScript cached version of it. This is so we can
     // avoid making WebGL calls if we don't need to.
@@ -1367,6 +1388,110 @@ export class WebGlContextWrapper {
     }
     return null;
   }
+
+  /**
+   *
+   * Compressed Textures support
+   */
+  uploadKTX(texture: WebGLTexture, data: CompressedData) {
+    const { glInternalFormat, mipmaps, w: width, h: height, blockInfo } = data;
+    if (mipmaps === undefined) {
+      return;
+    }
+
+    this.bindTexture(texture);
+
+    const blockWidth = blockInfo.width;
+    const blockHeight = blockInfo.height;
+    let w = width;
+    let h = height;
+
+    for (let i = 0; i < mipmaps!.length; i++) {
+      let view = new Uint8Array(mipmaps![i]!);
+
+      const uploadW = Math.ceil(w / blockWidth) * blockWidth;
+      const uploadH = Math.ceil(h / blockHeight) * blockHeight;
+
+      const expectedBytes =
+        Math.ceil(w / blockWidth) *
+        Math.ceil(h / blockHeight) *
+        blockInfo.bytes;
+
+      if (view.byteLength < expectedBytes) {
+        const padded = new Uint8Array(expectedBytes);
+        padded.set(view);
+        view = padded;
+      }
+
+      this.compressedTexImage2D(i, glInternalFormat, uploadW, uploadH, 0, view);
+
+      w = Math.max(1, w >> 1);
+      h = Math.max(1, h >> 1);
+    }
+
+    this.texParameteri(this.TEXTURE_WRAP_S, this.CLAMP_TO_EDGE);
+    this.texParameteri(this.TEXTURE_WRAP_T, this.CLAMP_TO_EDGE);
+    this.texParameteri(this.TEXTURE_MAG_FILTER, this.LINEAR);
+    this.texParameteri(
+      this.TEXTURE_MIN_FILTER,
+      mipmaps!.length > 1 ? this.LINEAR_MIPMAP_LINEAR : this.LINEAR,
+    );
+  }
+
+  uploadPVR(texture: WebGLTexture, data: CompressedData) {
+    const { glInternalFormat, mipmaps, w: width, h: height } = data;
+    if (mipmaps === undefined) {
+      return;
+    }
+    this.bindTexture(texture);
+
+    let w = width;
+    let h = height;
+
+    for (let i = 0; i < mipmaps!.length; i++) {
+      this.compressedTexImage2D(
+        i,
+        glInternalFormat,
+        w,
+        h,
+        0,
+        new Uint8Array(mipmaps[i]!),
+      );
+
+      w = Math.max(1, w >> 1);
+      h = Math.max(1, h >> 1);
+    }
+
+    this.texParameteri(this.TEXTURE_WRAP_S, this.CLAMP_TO_EDGE);
+    this.texParameteri(this.TEXTURE_WRAP_T, this.CLAMP_TO_EDGE);
+    this.texParameteri(this.TEXTURE_MAG_FILTER, this.LINEAR);
+    this.texParameteri(
+      this.TEXTURE_MIN_FILTER,
+      mipmaps.length > 1 ? this.LINEAR_MIPMAP_LINEAR : this.LINEAR,
+    );
+  }
+
+  uploadASTC(texture: WebGLTexture, data: CompressedData) {
+    if (this.getExtension('WEBGL_compressed_texture_astc') === null) {
+      throw new Error('ASTC compressed textures not supported by this device');
+    }
+
+    this.bindTexture(texture);
+
+    const { glInternalFormat, mipmaps, w, h } = data;
+    if (mipmaps === undefined) {
+      return;
+    }
+
+    const view = new Uint8Array(mipmaps[0]!);
+
+    this.compressedTexImage2D(0, glInternalFormat, w, h, 0, view);
+    // ASTC textures MUST use no mipmaps unless stored
+    this.texParameteri(this.TEXTURE_WRAP_S, this.CLAMP_TO_EDGE);
+    this.texParameteri(this.TEXTURE_WRAP_T, this.CLAMP_TO_EDGE);
+    this.texParameteri(this.TEXTURE_MAG_FILTER, this.LINEAR);
+    this.texParameteri(this.TEXTURE_MIN_FILTER, this.LINEAR);
+  }
 }
 
 // prettier-ignore

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

@@ -1,5 +1,37 @@
-import { Platform } from '../Platform.js';
+/*
+ * 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 } from './lib/ImageWorker.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
@@ -9,13 +41,33 @@ interface FontFaceSetWithAdd extends FontFaceSet {
 }
 
 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 = new ImageWorkerManager(numImageWorkers);
+    }
+  }
+
   ////////////////////////
   // Platform-specific methods
   ////////////////////////
 
   override createCanvas(): HTMLCanvasElement {
-    const canvas = document.createElement('canvas');
-    return canvas;
+    return document.createElement('canvas');
+  }
+
+  override createContext(): GlContextWrapper {
+    const gl = createWebGLContext(this.canvas!, this.settings.forceWebGL2);
+    this.glw = new WebGlContextWrapper(gl);
+    return this.glw;
   }
 
   override getElementById(id: string): HTMLElement | null {
@@ -76,7 +128,11 @@ export class WebPlatform extends Platform {
         return;
       }
 
-      isIdle = false;
+      if (isIdle === true) {
+        stage.eventBus.emit('active');
+        isIdle = false;
+      }
+
       stage.drawFrame();
       stage.flushFrameEvents();
 
@@ -97,31 +153,124 @@ export class WebPlatform extends Platform {
   }
 
   ////////////////////////
-  // ImageBitmap
+  // Image handling
   ////////////////////////
 
-  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,
+  override fetch(url: string): Promise<Blob> {
+    return new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+      xhr.responseType = '';
+      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) {
+            resolve(xhr.response);
+          } 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 (isBase64Image(src) === true) {
+      blob = dataURIToBlob(src);
     } else {
-      return createImageBitmap(blob, sxOrOptions);
+      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();
   }

package/src/core/platforms/web/WebPlatformChrome50.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';
+import type { ImageResponse } from '../../textures/ImageTexture.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 {
+  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,140 @@
+/*
+ * 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 {
+  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 = {}) {
+    // Force image workers to be disabled in legacy mode
+    super({ ...settings, numImageWorkers: 0 });
+  }
+
+  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);
+
+    // 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}`);
+    }
+  }
+}