diff --git a/docs/essentials/settings.md b/docs/essentials/settings.md index cff25216..c3aa0559 100644 --- a/docs/essentials/settings.md +++ b/docs/essentials/settings.md @@ -71,6 +71,40 @@ Example font object: |----------------|-----------|-------------| | `renderMode` | `'webgl' \| 'canvas'` | Renderer mode (default: 'webgl') | | `canvas` | `HTMLCanvasElement` | Custom canvas to render to | +| `platform` | `'web' \| 'next' \| 'chrome50' \| 'legacy' \| Platform` | Platform abstraction layer used by the Lightning renderer (default: `'web'`) | + +### Platform + +The `platform` setting selects which platform abstraction the underlying Lightning renderer uses to talk to the browser (image loading, canvas creation, etc.). Most Apps should leave this unset and use the default `web` platform; the alternatives exist for environments where the modern browser APIs aren't fully available. + +You can pass either a **string alias** (recommended) or a **`Platform` class reference** imported directly from `@lightningjs/renderer/platforms` for full control (including custom subclasses). + +| Value | Browser engine | +|------------|-------------| +| `web` | Chrome 70+ | +| `next` | Chrome 70+ | +| `chrome50` | Chrome 50+ | +| `legacy` | Chrome 40+ | + +Example using a string alias: +```js +Blits.Launch(App, 'app', { + w: 1920, + h: 1080, + platform: 'legacy', +}) +``` + +Example passing a class reference: +```js +import { WebPlatformChrome50 } from '@lightningjs/renderer/platforms' + +Blits.Launch(App, 'app', { + w: 1920, + h: 1080, + platform: WebPlatformChrome50, +}) +``` ## Effects & Shaders @@ -118,5 +152,6 @@ Blits.Launch(App, 'app', { inspector: false, announcer: true, enableMouse: false, // set true for hover + click-to-focus on canvas + platform: 'web', // 'web' (default) | 'next' | 'chrome50' | 'legacy' }) ``` diff --git a/index.d.ts b/index.d.ts index 8ce31ae4..63d42f84 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1003,6 +1003,7 @@ declare module '@lightningjs/blits' { type ReactivityModes = 'Proxy' | 'defineProperty' type RenderModes = 'webgl' | 'canvas' + type Platforms = 'web' | 'next' | 'chrome50' | 'legacy' /** * Settings @@ -1222,6 +1223,30 @@ declare module '@lightningjs/blits' { */ renderMode?: RenderModes, + /** + * Selects the platform abstraction layer used by the Lightning renderer. + * + * Accepts either: + * - A string alias for one of the bundled implementations: + * - `web` (default) - Modern browsers with full `createImageBitmap` support + * - `next` - PWAs / Service Worker environments using the Fetch API for image loading + * - `chrome50` - Older Chromium / WPEWebKit 2017 with basic `createImageBitmap` support + * - `legacy` - QtWebKit and other legacy engines with limited browser APIs + * - A `Platform` class reference imported from `@lightningjs/renderer/platforms` + * (or a custom subclass) for full control over the platform implementation. + * + * When omitted, the renderer falls back to `WebPlatform`. + * + * @example + * ```js + * import { WebPlatformChrome50 } from '@lightningjs/renderer/platforms' + * + * Blits.Launch(App, 'app', { platform: WebPlatformChrome50 }) + * Blits.Launch(App, 'app', { platform: 'chrome50' }) // equivalent + * ``` + */ + platform?: Platforms | (new (...args: any[]) => any), + /** * The time, in milliseconds, after which Blits considers a key press a _hold_ key press * diff --git a/package-lock.json b/package-lock.json index 1b45ee93..7798b625 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "2.4.1", "license": "Apache-2.0", "dependencies": { - "@lightningjs/renderer": "^3.0.3", + "@lightningjs/renderer": "^3.0.5", "magic-string": "^0.30.21" }, "bin": { @@ -752,9 +752,9 @@ } }, "node_modules/@lightningjs/renderer": { - "version": "3.0.3", - "resolved": "https://registry.npmjs.org/@lightningjs/renderer/-/renderer-3.0.3.tgz", - "integrity": "sha512-DKvQsesjjGZCDAyG/mK40V9sm+L8KYassB9HJGOvBcA/EOdNwYIcOvsLddMYVJBCttRvgqzgMZBSW3dQyuk31w==", + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/@lightningjs/renderer/-/renderer-3.0.5.tgz", + "integrity": "sha512-r/LFj8MmskZXC434okkV8CdTm3B7z9leb6aXVksvkWrLgBGxARTyTt7dIH9/Ho3GxIN9Eu/7QfN742K4tHfe+Q==", "license": "Apache-2.0", "engines": { "node": ">= 18.0.0", diff --git a/package.json b/package.json index a977c75c..87dbb694 100644 --- a/package.json +++ b/package.json @@ -75,7 +75,7 @@ "tape": "^5.5.0" }, "dependencies": { - "@lightningjs/renderer": "^3.0.3", + "@lightningjs/renderer": "^3.0.5", "magic-string": "^0.30.21" }, "repository": { diff --git a/src/engines/L3/launch.js b/src/engines/L3/launch.js index 5ee5ed2f..6298cf1e 100644 --- a/src/engines/L3/launch.js +++ b/src/engines/L3/launch.js @@ -19,6 +19,12 @@ import { RendererMain } from '@lightningjs/renderer' import { WebGlCoreRenderer, SdfTextRenderer } from '@lightningjs/renderer/webgl' import { CanvasCoreRenderer, CanvasTextRenderer } from '@lightningjs/renderer/canvas' import { Inspector } from '@lightningjs/renderer/inspector' +import { + WebPlatform, + WebPlatformNext, + WebPlatformChrome50, + WebPlatformLegacy, +} from '@lightningjs/renderer/platforms' import { Log } from '../../lib/log.js' import { SCREEN_RESOLUTIONS, RENDER_QUALITIES } from '../../constants.js' @@ -43,6 +49,13 @@ const textRenderEngines = (settings) => { if (renderMode === 'canvas') return [CanvasTextRenderer] } +const PLATFORMS = { + web: WebPlatform, + next: WebPlatformNext, + chrome50: WebPlatformChrome50, + legacy: WebPlatformLegacy, +} + const textureMemorySettings = (settings) => { const gpuMemory = { ...{ @@ -100,7 +113,10 @@ export default (App, target, settings = {}) => { textureMemory: textureMemorySettings(settings), createImageBitmapSupport: 'auto', targetFPS: 'maxFPS' in settings ? settings.maxFPS : 0, - platform: 'platform' in settings ? settings.platform : null, + platform: + typeof settings.platform === 'function' + ? settings.platform + : PLATFORMS[settings.platform] || WebPlatform, }, ...(settings.advanced || {}), }, diff --git a/src/launch.js b/src/launch.js index 0449c977..2da2ab80 100644 --- a/src/launch.js +++ b/src/launch.js @@ -83,6 +83,7 @@ async function rendererVersion() { * @property {number} [gpuMemoryLimit] - Threshold after which textures are freed (deprecated) * @property {object} [gpuMemory] - Configures the gpu memory settings * @property {"webgl"|"canvas"} [renderMode] - Defines which mode the renderer should operate in + * @property {"web"|"next"|"chrome50"|"legacy"|Function} [platform] - Platform abstraction layer used by the renderer. Either a string alias or a `Platform` class from `@lightningjs/renderer/platforms` * @property {number} [holdTimeout] - Time after which a key press is considered a hold * @property {HTMLCanvasElement} [canvas] - Custom canvas object used to render the App * @property {number} [textureProcessingTimeLimit] - Max time renderer can process textures in a frame