Feat: Extend platform abstraction (#746)

Move Image creation and GL wrapper to Platform.

This PR changes:
* `createImageBitmap` support to `Platform`
* Image fetch to `Platform` (by default using `XMLHttpRequest`)
* `ImageWorker` handling to `Platform`
* `GLWrapper` to `Platform`
* Similar, support for TX compression and SVG handling has been moved to
`Platform`

Removed:
* `createImageBitmap` auto detection - this needs to be done by Platform
* Image Fallback handling - this is done by Platform

**NOTE: BREAKING CHANGES**
This requires a different Platform import / init to make it work.

The concept is you create a Platform that matches the functionality the
platform exposes. I.e. if the Platform does not support
`createImageBitmap` or a less version of `createImageBitmap` you should
extend the platform to match that.

@estobbart for ION you can create or upstream an ION specific platform
(or we can create one) that:
* Replace `loadImage` and `createImage` in Platform (possibly `Fetch`
too?)
* Replace the respective GL function


Todo:
- [x] Expose platforms in exports
- [x] Create Legacy Platform for non-`createImageBitmap` platform
- [x] Create Chrome 50 `createImageBitmap` platform
- [x] Create `fetch` supported platform

Author: wouterlucas

README.md

@@ -45,6 +45,99 @@ Any JavaScript language features or browser APIs that cannot be automatically tr
 
 For a more detailed and comprehensive list of browsers and their features please see [browsers](./BROWSERS.md).
 
+## Platform Architecture
+
+The Lightning 3 Renderer uses a modular platform architecture that allows it to adapt to different browser capabilities and environments. This enables optimal performance across a wide range of devices, from modern browsers to legacy embedded systems.
+
+### Available Platforms
+
+The Renderer includes several platform implementations, each tailored for specific browser capabilities:
+
+#### WebPlatform (Default)
+
+The standard platform for modern browsers with full WebGL and createImageBitmap support.
+
+- Uses XMLHttpRequest for loading resources
+- Full createImageBitmap API with options (premultiplyAlpha, colorSpaceConversion, imageOrientation)
+- Supports image cropping
+- Multi-threaded image processing via Web Workers
+- **Use case:** Modern browsers, default choice for most applications
+
+#### WebPlatformNext
+
+Platform using the modern Fetch API instead of XMLHttpRequest.
+
+- Uses Fetch API for loading resources (promise-based, Service Worker compatible)
+- Full createImageBitmap API with options
+- Supports image cropping
+- Multi-threaded image processing via Web Workers
+- **Use case:** Modern browsers where Fetch API is preferred, progressive web apps
+
+#### WebPlatformChrome50
+
+Compatibility platform for browsers with limited createImageBitmap support (Chrome 50-51).
+
+- Uses XMLHttpRequest for loading resources
+- Limited createImageBitmap API (no options or cropping parameters)
+- Multi-threaded image processing via Web Workers (if enabled)
+- **Use case:** Chrome 50-51, browsers with basic createImageBitmap support
+
+#### WebPlatformLegacy
+
+Legacy platform for older browsers without createImageBitmap support.
+
+- Uses direct Image element loading (no blob conversion for URLs)
+- HTMLImageElement instead of createImageBitmap
+- Single-threaded image processing (no Web Workers)
+- No image cropping support
+- No compressed texture support
+- **Use case:** Chrome 38-49, older embedded device browsers
+
+### Using a Platform
+
+Platforms can be specified when initializing the Renderer:
+
+```ts
+import { RendererMain } from '@lightningjs/renderer';
+import { WebGlRenderer } from '@lightningjs/renderer/webgl';
+import {
+  WebPlatform,
+  WebPlatformNext,
+  WebPlatformChrome50,
+  WebPlatformLegacy,
+} from '@lightningjs/renderer/platforms';
+
+const renderer = new RendererMain(
+  {
+    appWidth: 1920,
+    appHeight: 1080,
+    renderEngine: WebGlRenderer,
+    platform: WebPlatformLegacy, // Use legacy platform for older browsers
+    // ...Other Renderer Config
+  },
+  'app',
+);
+```
+
+**Note:** `WebPlatformLegacy` automatically sets `numImageWorkers` to 0 since it doesn't support Web Workers.
+
+### Creating Custom Platforms
+
+You can create your own custom platform tailored to your specific device or environment by extending the `Platform` base class or one of the existing platform implementations.
+
+**Key methods you can override:**
+
+- `fetch(url: string): Promise<Blob>` - Resource loading
+- `createImage(...)` - Image bitmap creation
+- `loadImage(...)` - Complete image loading pipeline
+- `loadSvg(...)` - SVG loading
+- `loadCompressedTexture(...)` - Compressed texture loading
+- `createCanvas()` - Canvas element creation
+- `createContext()` - WebGL context creation
+- `startLoop(stage)` - Animation loop implementation
+
+This allows you to optimize the Renderer for proprietary platforms, embedded systems, or environments with unique capabilities and constraints.
+
 ## Example Tests
 
 The Example Tests sub-project define a set of tests for various Renderer

examples/README.md

@@ -41,6 +41,9 @@ pnpm watch
 - `driver` (string, default: "main")
   - Core driver to use
   - Either `main` or `threadx`
+- `platform` (string, default: "web")
+  - Platform implementation to use
+  - Options: `web` (XMLHttpRequest + createImageBitmap with full options), `next` (Fetch API + createImageBitmap with full options), `chrome50` (limited createImageBitmap, no options/cropping), `legacy` (HTMLImageElement, no createImageBitmap)
 - `overlay` (boolean, default: "true")
   - Whether or not to show the text overlay in the bottom-right corner that
     displays the current test and driver being used.

examples/index.ts

@@ -29,6 +29,12 @@ import {
   CanvasTextRenderer,
 } from '@lightningjs/renderer/canvas';
 
+import {
+  WebPlatform,
+  WebPlatformNext,
+  WebPlatformChrome50,
+  WebPlatformLegacy,
+} from '@lightningjs/renderer/platforms';
 import { Inspector } from '@lightningjs/renderer/inspector';
 import { assertTruthy } from '@lightningjs/renderer/utils';
 
@@ -71,6 +77,13 @@ const appHeight = 1080;
 const defaultResolution = 720;
 const defaultPhysicalPixelRatio = 1;
 
+const platformMap = {
+  web: WebPlatform,
+  next: WebPlatformNext,
+  chrome50: WebPlatformChrome50,
+  legacy: WebPlatformLegacy,
+};
+
 (async () => {
   // See README.md for details on the supported URL params
   const urlParams = new URLSearchParams(window.location.search);
@@ -91,6 +104,7 @@ const defaultPhysicalPixelRatio = 1;
   const textureProcessingLimit =
     Number(urlParams.get('textureProcessingLimit')) || 0;
   const globalTargetFPS = Number(urlParams.get('targetFPS')) || undefined;
+  const platform = urlParams.get('platform') || 'web';
 
   const physicalPixelRatio =
     Number(urlParams.get('ppr')) || defaultPhysicalPixelRatio;
@@ -105,6 +119,7 @@ const defaultPhysicalPixelRatio = 1;
     await runTest(
       test,
       renderMode,
+      platform,
       urlParams,
       showOverlay,
       showMemMonitor,
@@ -121,14 +136,15 @@ const defaultPhysicalPixelRatio = 1;
     return;
   }
   assertTruthy(automation);
-  await runAutomation(renderMode, test, logFps);
+  await runAutomation(renderMode, platform, test, logFps);
 })().catch((err) => {
   console.error(err);
 });
 
 async function runTest(
   test: string,
   renderMode: string,
+  platform: string,
   urlParams: URLSearchParams,
   showOverlay: boolean,
   showMemMonitor: boolean,
@@ -158,6 +174,7 @@ async function runTest(
 
   const { renderer, appElement } = await initRenderer(
     renderMode,
+    platform,
     logFps,
     enableContextSpy,
     logicalPixelRatio,
@@ -233,6 +250,7 @@ async function runTest(
 
 async function initRenderer(
   renderMode: string,
+  platform: string,
   logFps: boolean,
   enableContextSpy: boolean,
   logicalPixelRatio: number,
@@ -256,6 +274,7 @@ async function initRenderer(
       enableContextSpy,
       forceWebGL2,
       inspector,
+      platform: platformMap[platform] || WebPlatform,
       renderEngine: renderMode === 'webgl' ? WebGlRenderer : CanvasRenderer,
       fontEngines: [SdfTextRenderer, CanvasTextRenderer],
       textureProcessingTimeLimit: textureProcessingTimeLimit,
@@ -365,12 +384,14 @@ function wildcardMatch(string: string, wildcardString: string) {
 
 async function runAutomation(
   renderMode: string,
+  platform: string,
   filter: string | null,
   logFps: boolean,
 ) {
   const logicalPixelRatio = defaultResolution / appHeight;
   const { renderer, appElement } = await initRenderer(
     renderMode,
+    platform,
     logFps,
     false,
     logicalPixelRatio,

exports/platform.ts

@@ -0,0 +1,31 @@
+/*
+ * 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.
+ */
+
+export {
+  Platform,
+  type PlatformSettings,
+} from '../src/core/platforms/Platform.js';
+export { WebPlatform } from '../src/core/platforms/web/WebPlatform.js';
+export { WebPlatformNext } from '../src/core/platforms/web/WebPlatformNext.js';
+export { WebPlatformChrome50 } from '../src/core/platforms/web/WebPlatformChrome50.js';
+export { WebPlatformLegacy } from '../src/core/platforms/web/WebPlatformLegacy.js';
+
+// GL Context Wrappers
+export { GlContextWrapper } from '../src/core/platforms/GlContextWrapper.js';
+export { WebGlContextWrapper } from '../src/core/platforms/web/WebGlContextWrapper.js';

package.json

@@ -11,7 +11,8 @@
     "./canvas/shaders": "./dist/exports/canvas-shaders.js",
     "./webgl": "./dist/exports/webgl.js",
     "./webgl/shaders": "./dist/exports/webgl-shaders.js",
-    "./inspector": "./dist/exports/inspector.js"
+    "./inspector": "./dist/exports/inspector.js",
+    "./platforms": "./dist/exports/platform.js"
   },
   "scripts": {
     "start": "cd examples && pnpm start",

src/core/CoreNode.ts

@@ -2727,7 +2727,8 @@ export class CoreNode extends EventEmitter {
   }
 
   draw(renderer: WebGlRenderer) {
-    const { glw, options, stage } = renderer;
+    const { glw, stage } = renderer;
+    const canvas = stage.platform!.canvas!;
     const shader = this.props.shader as any;
 
     stage.shManager.useShader(shader.program);
@@ -2741,7 +2742,7 @@ export class CoreNode extends EventEmitter {
       const clipWidth = Math.round(this.clippingRect.w * pixelRatio);
       const clipHeight = Math.round(this.clippingRect.h * pixelRatio);
       let clipY = Math.round(
-        options.canvas.height - clipHeight - this.clippingRect.y * pixelRatio,
+        canvas.height - clipHeight - this.clippingRect.y * pixelRatio,
       );
       // if parent has render texture, we need to adjust the scissor rect
       // to be relative to the parent's framebuffer