Skip to content

PLATFORMS.md

Latest commit

 

History

History
362 lines (265 loc) · 12.7 KB

PLATFORMS.md

File metadata and controls

362 lines (265 loc) · 12.7 KB

Platform Architecture

Overview

The Lightning 3 Renderer uses a modular platform architecture that allows it to intelligently adapt to different browser capabilities and environments. Each platform implementation is optimized for a specific set of browser features, enabling the Renderer to deliver optimal performance across devices ranging from modern browsers to legacy embedded systems.

The platform abstraction handles:

  • Resource Loading: Fetching images, assets, and data (XMLHttpRequest vs Fetch API)
  • Image Processing: Using createImageBitmap with appropriate API versions or fallback to Image elements
  • Background Processing: Multi-threaded image processing via Web Workers (if available)
  • Canvas Creation: Creating WebGL or Canvas contexts
  • Animation Loops: Efficient frame rendering and timing

By automatically selecting the best platform for your target browser or allowing manual selection, Lightning 3 achieves high performance while maintaining broad compatibility.

Available Platforms

WebPlatform (Default)

The standard platform for modern browsers with full WebGL and createImageBitmap support.

Best for: Modern browsers (Chrome 52+, recent Firefox, Safari, Edge)

Features:

  • XMLHttpRequest for loading resources
  • Full createImageBitmap API with all options (premultiplyAlpha, colorSpaceConversion, imageOrientation)
  • Image cropping support
  • Multi-threaded image processing via Web Workers
  • Best performance for image-heavy applications

Browser Support: Chrome 52+, modern Firefox, Safari 14+, Edge 79+

Use cases:

  • Desktop applications
  • Modern smart TVs
  • Progressive web apps on modern devices
  • Default choice for most applications

WebPlatformNext

Platform using the modern Fetch API instead of XMLHttpRequest.

Best for: Modern browsers where Fetch API is preferred, especially progressive web apps

Features:

  • Fetch API for loading resources (promise-based)
  • Service Worker compatible
  • Full createImageBitmap API with options
  • Image cropping support
  • Multi-threaded image processing via Web Workers
  • Better support for progressive web app patterns

Browser Support: Chrome 40+, Firefox 40+, Safari 10.1+, Edge 14+

Use cases:

  • Progressive web apps (PWAs)
  • Applications using Service Workers
  • Modern browser applications preferring async/await patterns
  • Applications requiring offline functionality

WebPlatformChrome50

Compatibility platform for browsers with limited createImageBitmap support.

Best for: Chrome 50-51, browsers with partial createImageBitmap API

Features:

  • XMLHttpRequest for loading resources
  • Limited createImageBitmap API (no options, no cropping parameters)
  • Basic createImageBitmap(blob) only
  • Multi-threaded image processing via Web Workers (if enabled)
  • Graceful fallback for browsers without full API support

Browser Support: Chrome 50-51

Use cases:

  • Legacy Android devices with Chrome 50-51
  • Specific embedded devices stuck on older Chrome versions
  • Environments requiring Chrome 50 compatibility

WebPlatformLegacy

Legacy platform for older browsers without createImageBitmap support.

Best for: Older embedded device browsers, Chrome 38-49

Features:

  • Direct Image element loading (no blob-to-image conversion)
  • HTMLImageElement instead of createImageBitmap
  • Single-threaded image processing (no Web Workers)
  • No image cropping support
  • No compressed texture support
  • Simplified animation loop

Browser Support: Chrome 38-49, older WPEWebKit versions, legacy embedded systems

Use cases:

  • Chrome 38+ embedded devices
  • Older set-top boxes and smart TVs
  • Legacy WPEWebKit versions
  • Maximum backwards compatibility scenarios

Note: WebPlatformLegacy automatically sets numImageWorkers to 0 since it doesn't support Web Workers.

Platform Selection Matrix

Feature WebPlatform WebPlatformNext WebPlatformChrome50 WebPlatformLegacy
Resource Loading XMLHttpRequest Fetch API XMLHttpRequest Direct Image
createImageBitmap Full API + options Full API + options Limited API Not used
Image Cropping ✅ Yes ✅ Yes ❌ No ❌ No
Image Options ✅ premultiply, colorSpace, orientation ✅ premultiply, colorSpace, orientation ❌ None ❌ N/A
Web Workers ✅ Multi-threaded ✅ Multi-threaded ✅ Multi-threaded ❌ Single-threaded
Compressed Textures ✅ Yes ✅ Yes ✅ Yes ❌ No
Min Browser Chrome 52 Chrome 40 Chrome 50 Chrome 38
Performance Best Best Good Fair

Selecting a Platform

Automatic Selection

If you don't specify a platform, Lightning 3 automatically detects your browser's capabilities and uses the most appropriate platform:

import { RendererMain } from '@lightningjs/renderer';
import { WebGlRenderer } from '@lightningjs/renderer/webgl';

// Automatically selects the best platform for your browser
const renderer = new RendererMain(
  {
    appWidth: 1920,
    appHeight: 1080,
    renderEngine: WebGlRenderer,
    // Platform auto-selected based on browser capabilities
  },
  'app', // DOM element ID
);

Manual Selection

Override automatic selection by specifying a platform explicitly:

import { RendererMain } from '@lightningjs/renderer';
import { WebGlRenderer } from '@lightningjs/renderer/webgl';
import {
  WebPlatform,
  WebPlatformNext,
  WebPlatformChrome50,
  WebPlatformLegacy,
} from '@lightningjs/renderer/platform';

const renderer = new RendererMain(
  {
    appWidth: 1920,
    appHeight: 1080,
    renderEngine: WebGlRenderer,
    platform: WebPlatformLegacy, // Force legacy platform for older browsers
    // ...Other Renderer Config
  },
  'app',
);

When to Override

Force WebPlatformLegacy if:

  • Targeting Chrome 38-49 devices
  • Testing backwards compatibility
  • Supporting older embedded device browsers
  • Maximizing browser coverage at the cost of performance

Force WebPlatformNext if:

  • Building a PWA that requires Service Worker support
  • Specifically targeting modern browser capabilities
  • Prefer Promise-based fetch over XMLHttpRequest

Force WebPlatformChrome50 if:

  • Supporting specific Chrome 50-51 devices
  • Testing partial API support scenarios

Creating Custom Platforms

You can create a custom platform tailored to your specific device or environment by extending the Platform base class or one of the existing platform implementations.

Basic Custom Platform

import { Platform } from '@lightningjs/renderer/platform';

export class CustomPlatform extends Platform {
  // Override methods as needed
  async fetch(url: string): Promise<Blob> {
    // Custom resource loading logic
    return super.fetch(url);
  }

  async createImage(
    mediaElement: HTMLImageElement | HTMLCanvasElement,
    options?: ImageBitmapOptions,
  ): Promise<ImageBitmap | HTMLImageElement> {
    // Custom image creation logic
    return super.createImage(mediaElement, options);
  }

  createCanvas(): HTMLCanvasElement {
    // Custom canvas creation logic
    return super.createCanvas();
  }
}

Key Methods to Override

Method Purpose Parameters Returns
fetch(url) Load resources url: string Promise<Blob>
createImage(element, options) Convert to ImageBitmap element, options? Promise<ImageBitmap | HTMLImageElement>
loadImage(src, options) Complete image loading src, options Promise<LoadedImage>
loadSvg(url) Load SVG resources url: string Promise<ImageBitmap>
loadCompressedTexture(url) Load compressed textures url: string Promise<CompressedTexture>
createCanvas() Create canvas element None HTMLCanvasElement
createContext(canvas) Create WebGL context canvas: HTMLCanvasElement WebGLRenderingContext
startLoop(stage) Animation loop stage: Stage void

Custom Platform Example

import { Platform } from '@lightningjs/renderer/platform';

export class EmbeddedDevicePlatform extends Platform {
  // Optimize for specific embedded device APIs
  async fetch(url: string): Promise<Blob> {
    // Use device-specific resource loading if available
    if (window.deviceApi?.loadResource) {
      return window.deviceApi.loadResource(url);
    }
    return super.fetch(url);
  }

  createContext(canvas: HTMLCanvasElement): WebGLRenderingContext {
    // Use device-specific WebGL context creation
    const context = super.createContext(canvas);

    // Apply device-specific WebGL extensions or optimizations
    context.ext_shader_texture_lod = context.getExtension(
      'EXT_shader_texture_lod',
    );

    return context;
  }
}

// Use the custom platform
const renderer = new RendererMain(
  {
    appWidth: 1920,
    appHeight: 1080,
    renderEngine: WebGlRenderer,
    platform: EmbeddedDevicePlatform,
  },
  'app',
);

Platform Configuration

Platforms can be configured with additional options:

const renderer = new RendererMain(
  {
    appWidth: 1920,
    appHeight: 1080,
    renderEngine: WebGlRenderer,
    platform: WebPlatformLegacy,
    // Platform-related config options
    numImageWorkers: 0, // Image Workers (disables for Legacy platform)
    imageWorkerTimeout: 30000, // Worker task timeout in ms
  },
  'app',
);

Performance Considerations

Memory Usage

  • WebPlatform/Next: Higher memory due to createImageBitmap overhead, but better for large images
  • WebPlatformChrome50: Similar to WebPlatform, but with limited options
  • WebPlatformLegacy: Lower memory footprint; better for memory-constrained devices

Rendering Speed

  • WebPlatform: Fastest due to optimized createImageBitmap
  • WebPlatformNext: Similar speed to WebPlatform
  • WebPlatformChrome50: Slightly slower due to limited API
  • WebPlatformLegacy: Slowest; suitable for embedded devices where performance is acceptable

Web Worker Performance

  • WebPlatform/Next/Chrome50: Multi-threaded image processing (requires Worker support)
  • WebPlatformLegacy: Single-threaded; image processing on main thread

Debugging Platform Selection

To check which platform is being used:

const renderer = new RendererMain(/* config */, 'app');
console.log(renderer.platform); // Logs the active Platform instance

To force logging of platform detection:

// Before creating renderer
console.log(
  'Browser createImageBitmap support:',
  typeof window !== 'undefined' &&
    typeof window.createImageBitmap === 'function',
);

Troubleshooting

Images not loading

  • Check platform-specific loading capabilities
  • Verify browser supports required image format
  • For Legacy platform, ensure images are compatible with <img> elements

Performance issues

  • Profile with DevTools to confirm bottleneck
  • Consider forcing WebPlatform if auto-selection chose Legacy
  • Disable Web Workers if causing issues: numImageWorkers: 0

Incompatibility with device APIs

  • Create a custom platform extending the appropriate base implementation
  • Override createContext() for device-specific WebGL setup
  • Override fetch() for device-specific resource loading

See Also