@lightningjs/renderer 2.9.0-beta2 → 2.9.0-beta4

package/README.md

@@ -1,147 +1,147 @@
-# Lightning 3 Renderer
-
-A powerful 2D scene renderer designed for rendering highly performant user
-interfaces on web browsers running on embedded devices using WebGL.
-
-The Renderer is part of the [LightningJS](https://lightningjs.io) project. While it is possible to use the renderer directly, it is not recommended. Instead, Lightning 3 works best when combined with [Blits](https://lightningjs.io/v3-docs/blits/getting_started/intro.html).
-
-## Setup & Commands
-
-```
-# Install renderer + example dependencies
-pnpm install
-
-# Build Renderer
-pnpm build
-
-# Build Renderer (watch mode)
-pnpm watch
-
-# Run unit tests
-pnpm test
-
-# Run Visual Regression Tests
-pnpm test:visual
-
-# Build API Documentation (builds into ./typedocs folder)
-pnpm typedoc
-
-# Launch Example Tests in dev mode (includes Build Renderer (watch mode))
-pnpm start
-
-# Launch Example Tests in production mode
-# IMPORTANT: To run test examples on embedded devices that use older browser versions
-# you MUST run the examples in this mode.
-pnpm start:prod
-```
-
-## Browser Targets
-
-The Lightning 3 Renderer's goal is to work with the following browser versions and above:
-
-- Chrome v38 (Released October 7, 2014)
-
-Any JavaScript language features or browser APIs that cannot be automatically transpiled or polyfilled by industry standard transpilers (such as Babel) to target these versions must be carefully considered before use.
-
-For a more detailed and comprehensive list of browsers and their features please see [browsers](./BROWSERS.md).
-
-## Example Tests
-
-The Example Tests sub-project define a set of tests for various Renderer
-features. This is NOT an automated test. The command below will launch a
-web server which can be accessed by a web browser for manual testing. However,
-many of the Example Tests define Snapshots for the Visual Regression Test Runner
-(see below).
-
-The Example Tests can be launched with:
-
-```
-pnpm start
-```
-
-A hosted version can be found [here](https://lightning-js.github.io/renderer/).
-
-This supports modern browsers as well as Chrome 38 and above through a legacy build.
-
-See [examples/README.md](./examples/README.md) for more info.
-
-## Visual Regression Tests
-
-In order to prevent bugs on existing Renderer features when new features or bug
-fixes are added, the Renderer includes a Visual Regression Test Runner along
-with a set of certified snapshot files that are checked into the repository.
-
-These tests can be launched with:
-
-```
-pnpm test:visual
-```
-
-The captured Snapshots of these tests are optionally defined in the individual
-Example Tests.
-
-See [visual-regression/README.md](./visual-regression/README.md) for more info.
-
-## Manual Regression Tests
-
-See [docs/ManualRegressionTests.md].
-
-## Release Procedure
-
-See [RELEASE.md](./RELEASE.md)
-
-## Installing Fonts
-
-Fonts can be installed into the Font Manager exposed by the Renderer's Stage.
-There are two types of fonts that you can install, Web/Canvas2D fonts (WebTrFontFace)
-and SDF fonts (SdfTrFontFace). Install that fonts that your applications needs
-at start up so they are ready when your application is rendered.
-
-```ts
-import {
-  RendererMain,
-  WebTrFontFace,
-  SdfTrFontFace,
-} from '@lightningjs/renderer';
-
-import {
-  WebGlCoreRenderer,
-  SdfTextRenderer,
-} from '@lightningjs/renderer/webgl';
-import { CanvasTextRenderer } from '@lightningjs/renderer/canvas';
-
-const renderer = new RendererMain(
-  {
-    appWidth: 1920,
-    appHeight: 1080,
-    renderEngine: WebGlCoreRenderer,
-    fontEngines: [SdfTextRenderer, CanvasTextRenderer],
-    // ...Other Renderer Config
-  },
-  'app', // id of div to insert Canvas.
-);
-
-// Load fonts into renderer
-renderer.stage.fontManager.addFontFace(
-  new WebTrFontFace('Ubuntu', {}, '/fonts/Ubuntu-Regular.ttf'),
-);
-
-renderer.stage.fontManager.addFontFace(
-  new SdfTrFontFace(
-    'Ubuntu',
-    {},
-    'msdf',
-    stage,
-    '/fonts/Ubuntu-Regular.msdf.png',
-    '/fonts/Ubuntu-Regular.msdf.json',
-  ),
-);
-```
-
-Please note that the WebGL renderer supports both SDF Fonts and Web Fonts, however the
-Canvas renderer only supports Web Fonts:
-
-| Font Type Renderer | SDF Font | Web Font |
-| ------------------ | -------- | -------- |
-| WebGL              | Y        | Y        |
-| Canvas             | N        | Y        |
+# Lightning 3 Renderer
+
+A powerful 2D scene renderer designed for rendering highly performant user
+interfaces on web browsers running on embedded devices using WebGL.
+
+The Renderer is part of the [LightningJS](https://lightningjs.io) project. While it is possible to use the renderer directly, it is not recommended. Instead, Lightning 3 works best when combined with [Blits](https://lightningjs.io/v3-docs/blits/getting_started/intro.html).
+
+## Setup & Commands
+
+```
+# Install renderer + example dependencies
+pnpm install
+
+# Build Renderer
+pnpm build
+
+# Build Renderer (watch mode)
+pnpm watch
+
+# Run unit tests
+pnpm test
+
+# Run Visual Regression Tests
+pnpm test:visual
+
+# Build API Documentation (builds into ./typedocs folder)
+pnpm typedoc
+
+# Launch Example Tests in dev mode (includes Build Renderer (watch mode))
+pnpm start
+
+# Launch Example Tests in production mode
+# IMPORTANT: To run test examples on embedded devices that use older browser versions
+# you MUST run the examples in this mode.
+pnpm start:prod
+```
+
+## Browser Targets
+
+The Lightning 3 Renderer's goal is to work with the following browser versions and above:
+
+- Chrome v38 (Released October 7, 2014)
+
+Any JavaScript language features or browser APIs that cannot be automatically transpiled or polyfilled by industry standard transpilers (such as Babel) to target these versions must be carefully considered before use.
+
+For a more detailed and comprehensive list of browsers and their features please see [browsers](./BROWSERS.md).
+
+## Example Tests
+
+The Example Tests sub-project define a set of tests for various Renderer
+features. This is NOT an automated test. The command below will launch a
+web server which can be accessed by a web browser for manual testing. However,
+many of the Example Tests define Snapshots for the Visual Regression Test Runner
+(see below).
+
+The Example Tests can be launched with:
+
+```
+pnpm start
+```
+
+A hosted version can be found [here](https://lightning-js.github.io/renderer/).
+
+This supports modern browsers as well as Chrome 38 and above through a legacy build.
+
+See [examples/README.md](./examples/README.md) for more info.
+
+## Visual Regression Tests
+
+In order to prevent bugs on existing Renderer features when new features or bug
+fixes are added, the Renderer includes a Visual Regression Test Runner along
+with a set of certified snapshot files that are checked into the repository.
+
+These tests can be launched with:
+
+```
+pnpm test:visual
+```
+
+The captured Snapshots of these tests are optionally defined in the individual
+Example Tests.
+
+See [visual-regression/README.md](./visual-regression/README.md) for more info.
+
+## Manual Regression Tests
+
+See [docs/ManualRegressionTests.md].
+
+## Release Procedure
+
+See [RELEASE.md](./RELEASE.md)
+
+## Installing Fonts
+
+Fonts can be installed into the Font Manager exposed by the Renderer's Stage.
+There are two types of fonts that you can install, Web/Canvas2D fonts (WebTrFontFace)
+and SDF fonts (SdfTrFontFace). Install that fonts that your applications needs
+at start up so they are ready when your application is rendered.
+
+```ts
+import {
+  RendererMain,
+  WebTrFontFace,
+  SdfTrFontFace,
+} from '@lightningjs/renderer';
+
+import {
+  WebGlCoreRenderer,
+  SdfTextRenderer,
+} from '@lightningjs/renderer/webgl';
+import { CanvasTextRenderer } from '@lightningjs/renderer/canvas';
+
+const renderer = new RendererMain(
+  {
+    appWidth: 1920,
+    appHeight: 1080,
+    renderEngine: WebGlCoreRenderer,
+    fontEngines: [SdfTextRenderer, CanvasTextRenderer],
+    // ...Other Renderer Config
+  },
+  'app', // id of div to insert Canvas.
+);
+
+// Load fonts into renderer
+renderer.stage.fontManager.addFontFace(
+  new WebTrFontFace('Ubuntu', {}, '/fonts/Ubuntu-Regular.ttf'),
+);
+
+renderer.stage.fontManager.addFontFace(
+  new SdfTrFontFace(
+    'Ubuntu',
+    {},
+    'msdf',
+    stage,
+    '/fonts/Ubuntu-Regular.msdf.png',
+    '/fonts/Ubuntu-Regular.msdf.json',
+  ),
+);
+```
+
+Please note that the WebGL renderer supports both SDF Fonts and Web Fonts, however the
+Canvas renderer only supports Web Fonts:
+
+| Font Type Renderer | SDF Font | Web Font |
+| ------------------ | -------- | -------- |
+| WebGL              | Y        | Y        |
+| Canvas             | N        | Y        |

package/dist/src/core/CoreNode.d.ts

@@ -1,7 +1,7 @@
 import type { TextureOptions } from './CoreTextureManager.js';
 import type { CoreRenderer } from './renderers/CoreRenderer.js';
 import type { Stage } from './Stage.js';
-import type { Texture } from './textures/Texture.js';
+import { type Texture } from './textures/Texture.js';
 import type { Dimensions } from '../common/CommonTypes.js';
 import { EventEmitter } from '../common/EventEmitter.js';
 import { type Bound, type RectWithValid } from './lib/utils.js';
@@ -681,18 +681,40 @@ export declare class CoreNode extends EventEmitter {
     update(delta: number, parentClippingRect: RectWithValid): void;
     private findParentRTTNode;
     private notifyParentRTTOfUpdate;
-    hasRenderableProperties(): boolean;
     checkRenderBounds(): CoreNodeRenderState;
     updateBoundingRect(): void;
     createRenderBounds(): void;
     updateRenderState(renderState: CoreNodeRenderState): void;
     /**
-     * This function updates the `isRenderable` property based on certain conditions.
-     *
-     * @returns
+     * Updates the `isRenderable` property based on various conditions.
      */
     updateIsRenderable(): void;
-    onChangeIsRenderable(isRenderable: boolean): void;
+    /**
+     * Checks if the node is renderable based on world alpha, dimensions and out of bounds status.
+     */
+    checkBasicRenderability(): boolean;
+    /**
+     * Sets the renderable state and triggers changes if necessary.
+     * @param isRenderable - The new renderable state
+     */
+    setRenderable(isRenderable: boolean): void;
+    /**
+     * Changes the renderable state of the node.
+     */
+    updateTextureOwnership(isRenderable: boolean): void;
+    /**
+     * Checks if the node is out of the viewport bounds.
+     */
+    isOutOfBounds(): boolean;
+    /**
+     * Checks if the node has dimensions (width/height)
+     */
+    hasDimensions(): boolean;
+    /**
+     * Checks if the node has any color properties set.
+     */
+    hasColorProperties(): boolean;
+    hasShader(): boolean;
     calculateRenderCoords(): void;
     /**
      * This function calculates the clipping rectangle for a node.
@@ -777,6 +799,7 @@ export declare class CoreNode extends EventEmitter {
     get rtt(): boolean;
     set rtt(value: boolean);
     private initRenderTexture;
+    private loadRenderTexture;
     private cleanupRenderTexture;
     private markChildrenWithRTT;
     private applyRTTInheritance;

package/dist/src/core/CoreNode.js

@@ -17,6 +17,7 @@
  * limitations under the License.
  */
 import { assertTruthy, getNewId, mergeColorAlphaPremultiplied, } from '../utils.js';
+import {} from './textures/Texture.js';
 import { EventEmitter } from '../common/EventEmitter.js';
 import { copyRect, intersectRect, createBound, boundInsideBound, boundLargeThanBound, createPreloadBounds, } from './lib/utils.js';
 import { Matrix3d } from './lib/Matrix3d.js';
@@ -206,6 +207,14 @@ export class CoreNode extends EventEmitter {
             UpdateType.Local |
             UpdateType.RenderBounds |
             UpdateType.RenderState);
+        // if the default texture isn't loaded yet, wait for it to load
+        // this only happens when the node is created before the stage is ready
+        if (this.stage.defaultTexture &&
+            this.stage.defaultTexture.state !== 'loaded') {
+            this.stage.defaultTexture.once('loaded', () => {
+                this.setUpdateType(UpdateType.IsRenderable);
+            });
+        }
     }
     //#region Textures
     loadTexture() {
@@ -217,10 +226,6 @@ export class CoreNode extends EventEmitter {
         // synchronous task after calling loadTexture()
         queueMicrotask(() => {
             texture.preventCleanup = this.props.preventCleanup;
-            // Preload texture if required
-            if (this.textureOptions.preload) {
-                texture.ctxTexture.load();
-            }
             texture.on('loaded', this.onTextureLoaded);
             texture.on('failed', this.onTextureFailed);
             texture.on('freed', this.onTextureFreed);
@@ -262,6 +267,7 @@ export class CoreNode extends EventEmitter {
     }
     onTextureLoaded = (_, dimensions) => {
         this.autosizeNode(dimensions);
+        this.setUpdateType(UpdateType.IsRenderable);
         // Texture was loaded. In case the RAF loop has already stopped, we request
         // a render to ensure the texture is rendered.
         this.stage.requestRender();
@@ -269,16 +275,20 @@ export class CoreNode extends EventEmitter {
         if (this.parentHasRenderTexture) {
             this.notifyParentRTTOfUpdate();
         }
-        this.emit('loaded', {
-            type: 'texture',
-            dimensions,
-        });
+        // ignore 1x1 pixel textures
+        if (dimensions.width > 1 && dimensions.height > 1) {
+            this.emit('loaded', {
+                type: 'texture',
+                dimensions,
+            });
+        }
         // Trigger a local update if the texture is loaded and the resizeMode is 'contain'
         if (this.props.textureOptions?.resizeMode?.type === 'contain') {
             this.setUpdateType(UpdateType.Local);
         }
     };
     onTextureFailed = (_, error) => {
+        this.setUpdateType(UpdateType.IsRenderable);
         // If parent has a render texture, flag that we need to update
         if (this.parentHasRenderTexture) {
             this.notifyParentRTTOfUpdate();
@@ -289,6 +299,7 @@ export class CoreNode extends EventEmitter {
         });
     };
     onTextureFreed = () => {
+        this.setUpdateType(UpdateType.IsRenderable);
         // If parent has a render texture, flag that we need to update
         if (this.parentHasRenderTexture) {
             this.notifyParentRTTOfUpdate();
@@ -398,7 +409,7 @@ export class CoreNode extends EventEmitter {
         if (this.updateType & UpdateType.RenderTexture && this.rtt) {
             // Only the RTT node itself triggers `renderToTexture`
             this.hasRTTupdates = true;
-            this.stage.renderer?.renderToTexture(this);
+            this.loadRenderTexture();
         }
         if (this.updateType & UpdateType.Global) {
             assertTruthy(this.localTransform);
@@ -547,51 +558,6 @@ export class CoreNode extends EventEmitter {
             rttNode.notifyParentRTTOfUpdate();
         }
     }
-    //check if CoreNode is renderable based on props
-    hasRenderableProperties() {
-        if (this.props.texture) {
-            return true;
-        }
-        if (!this.props.width || !this.props.height) {
-            return false;
-        }
-        if (this.props.shader !== this.stage.defShaderCtr) {
-            return true;
-        }
-        if (this.props.clipping) {
-            return true;
-        }
-        if (this.props.color !== 0) {
-            return true;
-        }
-        // Consider removing these checks and just using the color property check above.
-        // Maybe add a forceRender prop for nodes that should always render.
-        if (this.props.colorTop !== 0) {
-            return true;
-        }
-        if (this.props.colorBottom !== 0) {
-            return true;
-        }
-        if (this.props.colorLeft !== 0) {
-            return true;
-        }
-        if (this.props.colorRight !== 0) {
-            return true;
-        }
-        if (this.props.colorTl !== 0) {
-            return true;
-        }
-        if (this.props.colorTr !== 0) {
-            return true;
-        }
-        if (this.props.colorBl !== 0) {
-            return true;
-        }
-        if (this.props.colorBr !== 0) {
-            return true;
-        }
-        return false;
-    }
     checkRenderBounds() {
         assertTruthy(this.renderBound);
         assertTruthy(this.strictBound);
@@ -679,26 +645,86 @@ export class CoreNode extends EventEmitter {
         });
     }
     /**
-     * This function updates the `isRenderable` property based on certain conditions.
-     *
-     * @returns
+     * Updates the `isRenderable` property based on various conditions.
      */
     updateIsRenderable() {
-        let newIsRenderable;
-        if (this.worldAlpha === 0 || !this.hasRenderableProperties()) {
-            newIsRenderable = false;
+        let newIsRenderable = false;
+        let needsTextureOwnership = false;
+        // If the node is out of bounds or has an alpha of 0, it is not renderable
+        if (this.checkBasicRenderability() === false) {
+            this.updateTextureOwnership(false);
+            this.setRenderable(false);
+            return;
         }
-        else {
-            newIsRenderable = this.renderState > CoreNodeRenderState.OutOfBounds;
+        if (this.texture !== null) {
+            needsTextureOwnership = true;
+            // we're only renderable if the texture state is loaded
+            newIsRenderable = this.texture.state === 'loaded';
+        }
+        else if ((this.hasShader() || this.hasColorProperties() === true) &&
+            this.hasDimensions() === true) {
+            // This mean we have dimensions and a color set, so we can render a ColorTexture
+            if (this.stage.defaultTexture &&
+                this.stage.defaultTexture.state === 'loaded') {
+                newIsRenderable = true;
+            }
+        }
+        this.updateTextureOwnership(needsTextureOwnership);
+        this.setRenderable(newIsRenderable);
+    }
+    /**
+     * Checks if the node is renderable based on world alpha, dimensions and out of bounds status.
+     */
+    checkBasicRenderability() {
+        if (this.worldAlpha === 0 || this.isOutOfBounds() === true) {
+            return false;
         }
-        if (this.isRenderable !== newIsRenderable) {
-            this.isRenderable = newIsRenderable;
-            this.onChangeIsRenderable(newIsRenderable);
+        else {
+            return true;
         }
     }
-    onChangeIsRenderable(isRenderable) {
+    /**
+     * Sets the renderable state and triggers changes if necessary.
+     * @param isRenderable - The new renderable state
+     */
+    setRenderable(isRenderable) {
+        this.isRenderable = isRenderable;
+    }
+    /**
+     * Changes the renderable state of the node.
+     */
+    updateTextureOwnership(isRenderable) {
         this.texture?.setRenderableOwner(this, isRenderable);
     }
+    /**
+     * Checks if the node is out of the viewport bounds.
+     */
+    isOutOfBounds() {
+        return this.renderState <= CoreNodeRenderState.OutOfBounds;
+    }
+    /**
+     * Checks if the node has dimensions (width/height)
+     */
+    hasDimensions() {
+        return this.props.width !== 0 && this.props.height !== 0;
+    }
+    /**
+     * Checks if the node has any color properties set.
+     */
+    hasColorProperties() {
+        return (this.props.color !== 0 ||
+            this.props.colorTop !== 0 ||
+            this.props.colorBottom !== 0 ||
+            this.props.colorLeft !== 0 ||
+            this.props.colorRight !== 0 ||
+            this.props.colorTl !== 0 ||
+            this.props.colorTr !== 0 ||
+            this.props.colorBl !== 0 ||
+            this.props.colorBr !== 0);
+    }
+    hasShader() {
+        return this.props.shader !== null;
+    }
     calculateRenderCoords() {
         const { width, height, globalTransform: transform } = this;
         assertTruthy(transform);
@@ -821,7 +847,9 @@ export class CoreNode extends EventEmitter {
             colorTr: this.premultipliedColorTr,
             colorBl: this.premultipliedColorBl,
             colorBr: this.premultipliedColorBr,
-            texture: this.texture,
+            // if we do not have a texture, use the default texture
+            // this assumes any renderable node is either a distinct texture or a ColorTexture
+            texture: this.texture || this.stage.defaultTexture,
             textureOptions: this.textureOptions,
             zIndex: this.zIndex,
             shader: this.shader.shader,
@@ -886,11 +914,10 @@ export class CoreNode extends EventEmitter {
             this.props.width = value;
             this.setUpdateType(UpdateType.Local);
             if (this.props.rtt) {
-                this.texture = this.stage.txManager.loadTexture('RenderTexture', {
+                this.texture = this.stage.txManager.createTexture('RenderTexture', {
                     width: this.width,
                     height: this.height,
                 });
-                this.textureOptions.preload = true;
                 this.setUpdateType(UpdateType.RenderTexture);
             }
         }
@@ -903,11 +930,10 @@ export class CoreNode extends EventEmitter {
             this.props.height = value;
             this.setUpdateType(UpdateType.Local);
             if (this.props.rtt) {
-                this.texture = this.stage.txManager.loadTexture('RenderTexture', {
+                this.texture = this.stage.txManager.createTexture('RenderTexture', {
                     width: this.width,
                     height: this.height,
                 });
-                this.textureOptions.preload = true;
                 this.setUpdateType(UpdateType.RenderTexture);
             }
         }
@@ -1195,12 +1221,27 @@ export class CoreNode extends EventEmitter {
         }
     }
     initRenderTexture() {
-        this.texture = this.stage.txManager.loadTexture('RenderTexture', {
+        this.texture = this.stage.txManager.createTexture('RenderTexture', {
             width: this.width,
             height: this.height,
         });
-        this.textureOptions.preload = true;
-        this.stage.renderer?.renderToTexture(this); // Only this RTT node
+        this.loadRenderTexture();
+    }
+    loadRenderTexture() {
+        if (this.texture === null) {
+            return;
+        }
+        // If the texture is already loaded, render to it immediately
+        if (this.texture.state === 'loaded') {
+            this.stage.renderer?.renderToTexture(this);
+            return;
+        }
+        // call load immediately to ensure the texture is created
+        this.stage.txManager.loadTexture(this.texture, true);
+        this.texture.once('loaded', () => {
+            this.stage.renderer?.renderToTexture(this); // Only this RTT node
+            this.setUpdateType(UpdateType.IsRenderable);
+        });
     }
     cleanupRenderTexture() {
         this.unloadTexture();
@@ -1263,7 +1304,7 @@ export class CoreNode extends EventEmitter {
             this.texture = null;
             return;
         }
-        this.texture = this.stage.txManager.loadTexture('ImageTexture', {
+        this.texture = this.stage.txManager.createTexture('ImageTexture', {
             src: imageUrl,
             width: this.props.width,
             height: this.props.height,
@@ -1345,8 +1386,8 @@ export class CoreNode extends EventEmitter {
             this.unloadTexture();
         }
         this.props.texture = value;
-        if (value) {
-            value.setRenderableOwner(this, this.isRenderable);
+        if (value !== null) {
+            value.setRenderableOwner(this, this.isRenderable); // WVB TODO: check if this is correct
             this.loadTexture();
         }
         this.setUpdateType(UpdateType.IsRenderable);
@@ -1370,9 +1411,7 @@ export class CoreNode extends EventEmitter {
     }
     animate(props, settings) {
         const animation = new CoreAnimation(this, props, settings);
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
         const controller = new CoreAnimationController(this.stage.animationManager, animation);
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
         return controller;
     }
     flush() {