@lightningjs/renderer 3.0.0-beta22 → 3.0.0-beta24

package/src/core/platforms/GlContextWrapper.ts

@@ -0,0 +1,291 @@
+/*
+ * 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-explicit-any */
+
+import type {
+  Vec2,
+  Vec3,
+  Vec4,
+} from '../renderers/webgl/internal/ShaderUtils.js';
+
+import type { CompressedData } from '../textures/Texture.js';
+
+/**
+ * Abstract GL Context Wrapper
+ *
+ * @remarks
+ * This abstract class defines the interface for rendering context wrappers.
+ * Implementations should provide optimized state management and caching
+ * to avoid redundant API calls when the state is already set to the desired value.
+ *
+ * The interface is designed to be compatible with WebGL-like rendering contexts
+ * but can be adapted for other rendering backends (Canvas2D, WebGPU, Native, etc.).
+ */
+export abstract class GlContextWrapper {
+  //#region Canvas
+  abstract readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+  //#endregion Canvas
+
+  //#region GL Constants
+  abstract readonly MAX_RENDERBUFFER_SIZE: number;
+  abstract readonly MAX_TEXTURE_SIZE: number;
+  abstract readonly MAX_VIEWPORT_DIMS: number;
+  abstract readonly MAX_VERTEX_TEXTURE_IMAGE_UNITS: number;
+  abstract readonly MAX_TEXTURE_IMAGE_UNITS: number;
+  abstract readonly MAX_COMBINED_TEXTURE_IMAGE_UNITS: number;
+  abstract readonly MAX_VERTEX_ATTRIBS: number;
+  abstract readonly MAX_VARYING_VECTORS: number;
+  abstract readonly MAX_VERTEX_UNIFORM_VECTORS: number;
+  abstract readonly MAX_FRAGMENT_UNIFORM_VECTORS: number;
+  abstract readonly TEXTURE_MAG_FILTER: number;
+  abstract readonly TEXTURE_MIN_FILTER: number;
+  abstract readonly TEXTURE_WRAP_S: number;
+  abstract readonly TEXTURE_WRAP_T: number;
+  abstract readonly LINEAR: number;
+  abstract readonly LINEAR_MIPMAP_LINEAR: number;
+  abstract readonly CLAMP_TO_EDGE: number;
+  abstract readonly RGB: number;
+  abstract readonly RGBA: number;
+  abstract readonly UNSIGNED_BYTE: number;
+  abstract readonly UNPACK_PREMULTIPLY_ALPHA_WEBGL: number;
+  abstract readonly UNPACK_FLIP_Y_WEBGL: number;
+  abstract readonly FLOAT: number;
+  abstract readonly TRIANGLES: number;
+  abstract readonly UNSIGNED_SHORT: number;
+  abstract readonly ONE: number;
+  abstract readonly ONE_MINUS_SRC_ALPHA: number;
+  abstract readonly VERTEX_SHADER: number;
+  abstract readonly FRAGMENT_SHADER: number;
+  abstract readonly STATIC_DRAW: number;
+  abstract readonly COMPILE_STATUS: number;
+  abstract readonly LINK_STATUS: number;
+  abstract readonly DYNAMIC_DRAW: number;
+  abstract readonly COLOR_ATTACHMENT0: number;
+  abstract readonly INVALID_ENUM: number;
+  abstract readonly INVALID_OPERATION: number;
+  //#endregion GL Constants
+
+  //#region Texture Management
+  abstract activeTexture(textureUnit: number): void;
+  abstract bindTexture(texture: any | null): void;
+  abstract texParameteri(pname: number, param: number): void;
+  abstract texImage2D(
+    level: GLint,
+    internalformat: GLint,
+    width: GLsizei,
+    height: GLsizei,
+    border: GLint,
+    format: GLenum,
+    type: GLenum,
+    pixels: ArrayBufferView | null,
+  ): void;
+  abstract texImage2D(
+    level: GLint,
+    internalformat: GLint,
+    format: GLenum,
+    type: GLenum,
+    source: TexImageSource | Uint8Array,
+  ): void;
+  abstract compressedTexImage2D(
+    level: GLint,
+    internalformat: GLenum,
+    width: GLsizei,
+    height: GLsizei,
+    border: GLint,
+    data?: ArrayBufferView,
+  ): void;
+  abstract pixelStorei(pname: GLenum, param: GLint | GLboolean): void;
+  abstract generateMipmap(): void;
+  abstract createTexture(): any;
+  abstract deleteTexture(texture: any | null): void;
+  //#endregion Texture Management
+
+  //#region Viewport & Clear
+  abstract viewport(x: GLint, y: GLint, width: GLsizei, height: GLsizei): void;
+  abstract clearColor(
+    red: GLclampf,
+    green: GLclampf,
+    blue: GLclampf,
+    alpha: GLclampf,
+  ): void;
+  abstract clear(): void;
+  //#endregion Viewport & Clear
+
+  //#region Scissor & Blend
+  abstract setScissorTest(enable: boolean): void;
+  abstract scissor(x: GLint, y: GLint, width: GLsizei, height: GLsizei): void;
+  abstract setBlend(blend: boolean): void;
+  abstract blendFunc(src: GLenum, dst: GLenum): void;
+  //#endregion Scissor & Blend
+
+  //#region Buffer Management
+  abstract createBuffer(): any;
+  abstract arrayBufferData(
+    buffer: any | null,
+    data: ArrayBufferView,
+    usage: GLenum,
+  ): void;
+  abstract elementArrayBufferData(
+    buffer: any | null,
+    data: ArrayBufferView,
+    usage: GLenum,
+  ): void;
+  abstract vertexAttribPointer(
+    buffer: any,
+    index: GLuint,
+    size: GLint,
+    type: GLenum,
+    normalized: GLboolean,
+    stride: GLsizei,
+    offset: GLintptr,
+  ): void;
+  abstract deleteBuffer(buffer: any): void;
+  //#endregion Buffer Management
+
+  //#region Framebuffer Management
+  abstract createFramebuffer(): any;
+  abstract deleteFramebuffer(framebuffer: any | null): void;
+  abstract bindFramebuffer(framebuffer: any | null): void;
+  abstract framebufferTexture2D(
+    attachment: GLenum,
+    texture: any | null,
+    level: GLint,
+  ): void;
+  //#endregion Framebuffer Management
+
+  //#region Shader & Program Management
+  abstract createShader(type: number): any;
+  abstract compileShader(shader: any): void;
+  abstract attachShader(program: any, shader: any): void;
+  abstract linkProgram(program: any): void;
+  abstract deleteProgram(shader: any): void;
+  abstract getShaderParameter(shader: any, pname: GLenum): any;
+  abstract getShaderInfoLog(shader: any): string | null;
+  abstract createProgram(): any;
+  abstract getProgramParameter(program: any, pname: GLenum): any;
+  abstract getProgramInfoLog(program: any): string | null;
+  abstract shaderSource(shader: any, source: string): void;
+  abstract deleteShader(shader: any): void;
+  abstract useProgram(
+    program: any | null,
+    uniformLocations: Record<string, any>,
+  ): void;
+  abstract getUniformLocations(program: any): Record<string, any>;
+  abstract getAttributeLocations(program: any): string[];
+  abstract getAttribLocation(program: any, name: string): number;
+  abstract getUniformLocation(program: any, name: string): any;
+  abstract enableVertexAttribArray(index: number): void;
+  abstract disableVertexAttribArray(index: number): void;
+  //#endregion Shader & Program Management
+
+  //#region Uniform Setters
+  abstract uniform1f(location: string, v0: number): void;
+  abstract uniform1fv(location: string, value: Float32Array): void;
+  abstract uniform1i(location: string, v0: number): void;
+  abstract uniform1iv(location: string, value: Int32Array): void;
+  abstract uniform2f(location: string, v0: number, v1: number): void;
+  abstract uniform2fa(location: string, value: Vec2): void;
+  abstract uniform2fv(location: string, value: Float32Array): void;
+  abstract uniform2i(location: string, v0: number, v1: number): void;
+  abstract uniform2iv(location: string, value: Int32Array): void;
+  abstract uniform3f(
+    location: string,
+    v0: number,
+    v1: number,
+    v2: number,
+  ): void;
+  abstract uniform3fa(location: string, value: Vec3): void;
+  abstract uniform3fv(location: string, value: Float32Array): void;
+  abstract uniform3i(
+    location: string,
+    v0: number,
+    v1: number,
+    v2: number,
+  ): void;
+  abstract uniform3iv(location: string, value: Int32Array): void;
+  abstract uniform4f(
+    location: string,
+    v0: number,
+    v1: number,
+    v2: number,
+    v3: number,
+  ): void;
+  abstract uniform4fa(location: string, value: Vec4): void;
+  abstract uniform4fv(location: string, value: Float32Array): void;
+  abstract uniform4i(
+    location: string,
+    v0: number,
+    v1: number,
+    v2: number,
+    v3: number,
+  ): void;
+  abstract uniform4iv(location: string, value: Int32Array): void;
+  abstract uniformMatrix2fv(location: string, value: Float32Array): void;
+  abstract uniformMatrix3fv(location: string, value: Float32Array): void;
+  abstract uniformMatrix4fv(location: string, value: Float32Array): void;
+  //#endregion Uniform Setters
+
+  //#region Vertex Array Objects
+  abstract createVertexArray(): any;
+  abstract bindVertexArray(vertexArray: any | null): void;
+  abstract deleteVertexArray(vertexArray: any): void;
+  //#endregion Vertex Array Objects
+
+  //#region Drawing
+  abstract drawElements(
+    mode: GLenum,
+    count: GLsizei,
+    type: GLenum,
+    offset: GLintptr,
+  ): void;
+  abstract drawArrays(mode: GLenum, first: GLint, count: GLsizei): void;
+  //#endregion Drawing
+
+  //#region Context Info & Extensions
+  abstract getParameter(pname: GLenum): any;
+  abstract getExtension(name: string): any;
+  abstract getError(): number;
+  abstract checkError(
+    operation: string,
+  ): { error: number; errorName: string; message: string } | null;
+  //#endregion Context Info & Extensions
+
+  //#region compressed texture support
+  abstract uploadKTX(
+    glw: GlContextWrapper,
+    texture: WebGLTexture,
+    data: CompressedData,
+  ): void;
+  abstract uploadPVR(
+    glw: GlContextWrapper,
+    texture: WebGLTexture,
+    data: CompressedData,
+  ): void;
+  abstract uploadASTC(
+    glw: GlContextWrapper,
+    texture: WebGLTexture,
+    data: CompressedData,
+  ): void;
+  //#endregion compressed texture support
+
+  //#region WebGL 2 specific methods (optional)
+  abstract isWebGl2(): boolean;
+  //#endregion WebGL 2 specific methods
+}

package/src/core/platforms/Platform.ts

@@ -18,14 +18,65 @@
  */
 
 import { type Stage } from '../Stage.js';
+import type { WebGlContextWrapper } from './web/WebGlContextWrapper.js';
+import type { ImageResponse } from '../textures/ImageTexture.js';
+import type { GlContextWrapper } from './GlContextWrapper.js';
+
+/**
+ * Settings for the Platform
+ */
+export interface PlatformSettings {
+  /**
+   * Number of image workers to spawn for parallel image processing
+   * @default 2
+   */
+  numImageWorkers?: number;
+
+  /**
+   * Whether to force the use of WebGL2 (if supported by the platform) or WebGL1. By default, the platform will use WebGL2 if it is available, and fall back to WebGL1 if it is not.
+   * @default false
+   */
+  forceWebGL2?: boolean;
+
+  /**
+   * Optional provided canvas element to use for rendering. If not provided, the platform will create its own canvas element.
+   */
+  canvas?: HTMLCanvasElement | null;
+}
 
 export abstract class Platform {
+  public readonly settings: Required<PlatformSettings>;
+
+  public glw: GlContextWrapper | null = null;
+  public canvas: HTMLCanvasElement | null = null;
+
+  constructor(settings: PlatformSettings = {}) {
+    // Apply default settings
+    this.settings = {
+      numImageWorkers: settings.numImageWorkers ?? 2,
+      forceWebGL2: settings.forceWebGL2 ?? false,
+      canvas: settings.canvas ?? null,
+    };
+
+    // If a canvas was provided in the settings, use it. Otherwise, create a new one.
+    if (this.settings.canvas !== null) {
+      this.canvas = this.settings.canvas;
+    } else {
+      this.canvas = this.createCanvas();
+    }
+  }
+
   /**
    * Creates a new canvas element.
    * @returns The created HTMLCanvasElement.
    */
   abstract createCanvas(): HTMLCanvasElement;
 
+  /**
+   * Create new rendering context (only for WebGL, Canvas does not require a context)
+   */
+  abstract createContext(): GlContextWrapper;
+
   /**
    * Get a DOM element by ID
    * @returns The DOM element (or null)
@@ -39,35 +90,77 @@ export abstract class Platform {
   abstract startLoop(stage: Stage): void;
 
   /**
-   * Abstracted createImageBitmap method.
-   * @param blob - The image source to create the ImageBitmap from.
-   * @param sxOrOptions - The source rectangle x coordinate or ImageBitmapOptions.
-   * @param sy - The source rectangle y coordinate.
-   * @param sw - The source rectangle width.
-   * @param sh - The source rectangle height.
-   * @param options - The ImageBitmapOptions.
-   * @returns A promise that resolves with the created ImageBitmap.
+   * Fetches a resource from the network.
+   * @param url - The URL of the resource to fetch.
+   * @returns A promise that resolves with the response.
+   */
+  abstract fetch(url: string): Promise<unknown>;
+
+  /**
+   * Loads an image from a UR and returns it as an ImageBitmap or HTMLImageElement.
+   * @param src - The source URL or Blob of the image to load.
+   * @param premultiplyAlpha - Whether to premultiply alpha (if supported by the platform).
+   * @param sx - The x coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
+   * @param sy - The y coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
+   * @param sw - The width of the sub-rectangle of the source image to draw into the destination context.
+   * @param sh - The height of the sub-rectangle of the source image to draw into the destination context.
+   * @returns A promise that resolves with an object containing the loaded image and whether alpha was premultiplied.
+   */
+  abstract loadImage(
+    src: string,
+    premultiplyAlpha: boolean | null,
+    sx?: number | null,
+    sy?: number | null,
+    sw?: number | null,
+    sh?: number | null,
+  ): Promise<ImageResponse>;
+
+  /**
+   * Create an image out of a Blob
+   *
+   * @param blob - The Blob to create an image from
+   * @param premultiplyAlpha - Whether to premultiply alpha (if supported by the platform).
+   * @param sx - The x coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
+   * @param sy - The y coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
+   * @param sw - The width of the sub-rectangle of the source image to draw into the destination context.
+   * @param sh - The height of the sub-rectangle of the source image to draw into the destination context.
+   * @returns A promise that resolves with an object containing the loaded image and whether alpha was premultiplied.
+   */
+  abstract createImage(
+    blob: Blob,
+    premultiplyAlpha: boolean | null,
+    sx?: number | null,
+    sy?: number | null,
+    sw?: number | null,
+    sh?: number | null,
+  ): Promise<ImageResponse>;
+
+  /**
+   * Loads an SVG image from a URL and returns it as an ImageBitmap or HTMLImageElement.
+   * @param src - The source URL of the SVG image to load.
+   * @param width - The width to render the SVG image.
+   * @param height - The height to render the SVG image.
+   * @param sx - The x coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
+   * @param sy - The y coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
+   * @param sw - The width of the sub-rectangle of the source image to draw into the destination context.
+   * @param sh - The height of the sub-rectangle of the source image to draw into the destination context.
+   */
+  abstract loadSvg(
+    src: string,
+    width: number | null,
+    height: number | null,
+    sx?: number | null,
+    sy?: number | null,
+    sw?: number | null,
+    sh?: number | null,
+  ): Promise<ImageResponse>;
+
+  /**
+   * Loads a compressed texture from a URL and returns it as an ImageBitmap or HTMLImageElement.
+   * @param src - The source URL of the compressed texture to load.
+   * @returns A promise that resolves with an object containing the loaded image and whether alpha was premultiplied.
    */
-  abstract createImageBitmap(blob: ImageBitmapSource): Promise<ImageBitmap>;
-  abstract createImageBitmap(
-    blob: ImageBitmapSource,
-    options: ImageBitmapOptions,
-  ): Promise<ImageBitmap>;
-  abstract createImageBitmap(
-    blob: ImageBitmapSource,
-    sx: number,
-    sy: number,
-    sw: number,
-    sh: number,
-  ): Promise<ImageBitmap>;
-  abstract createImageBitmap(
-    blob: ImageBitmapSource,
-    sx: number,
-    sy: number,
-    sw: number,
-    sh: number,
-    options: ImageBitmapOptions,
-  ): Promise<ImageBitmap>;
+  abstract loadCompressedTexture(src: string): Promise<ImageResponse>;
 
   /**
    * Retrieves the current timestamp.

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