@lightningjs/renderer 2.12.0 → 2.13.0

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

@@ -197,6 +197,12 @@ export interface CoreNodeProps {
      * @default `false`
      */
     autosize: boolean;
+    /**
+     * Margin around the Node's bounds for preloading
+     *
+     * @default `null`
+     */
+    boundsMargin: number | [number, number, number, number] | null;
     /**
      * Clipping Mode
      *
@@ -643,7 +649,9 @@ export declare class CoreNode extends EventEmitter {
     globalTransform?: Matrix3d;
     scaleRotateTransform?: Matrix3d;
     localTransform?: Matrix3d;
+    sceneGlobalTransform?: Matrix3d;
     renderCoords?: RenderCoords;
+    sceneRenderCoords?: RenderCoords;
     renderBound?: Bound;
     strictBound?: Bound;
     preloadBound?: Bound;
@@ -684,6 +692,8 @@ export declare class CoreNode extends EventEmitter {
      */
     update(delta: number, parentClippingRect: RectWithValid): void;
     private findParentRTTNode;
+    private getRTTParentRenderState;
+    private notifyChildrenRTTOfUpdate;
     private notifyParentRTTOfUpdate;
     checkRenderBounds(): CoreNodeRenderState;
     updateBoundingRect(): void;
@@ -772,6 +782,8 @@ export declare class CoreNode extends EventEmitter {
     set alpha(value: number);
     get autosize(): boolean;
     set autosize(value: boolean);
+    get boundsMargin(): number | [number, number, number, number] | null;
+    set boundsMargin(value: number | [number, number, number, number] | null);
     get clipping(): boolean;
     set clipping(value: boolean);
     get color(): number;
@@ -803,7 +815,6 @@ 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

@@ -166,7 +166,9 @@ export class CoreNode extends EventEmitter {
     globalTransform;
     scaleRotateTransform;
     localTransform;
+    sceneGlobalTransform;
     renderCoords;
+    sceneRenderCoords;
     renderBound;
     strictBound;
     preloadBound;
@@ -203,6 +205,16 @@ export class CoreNode extends EventEmitter {
         this.texture = props.texture;
         this.src = props.src;
         this.rtt = props.rtt;
+        if (props.boundsMargin) {
+            this.boundsMargin = Array.isArray(props.boundsMargin)
+                ? props.boundsMargin
+                : [
+                    props.boundsMargin,
+                    props.boundsMargin,
+                    props.boundsMargin,
+                    props.boundsMargin,
+                ];
+        }
         this.setUpdateType(UpdateType.ScaleRotate |
             UpdateType.Local |
             UpdateType.RenderBounds |
@@ -414,17 +426,29 @@ export class CoreNode extends EventEmitter {
         let renderState = null;
         // Handle specific RTT updates at this node level
         if (this.updateType & UpdateType.RenderTexture && this.rtt) {
-            // Only the RTT node itself triggers `renderToTexture`
             this.hasRTTupdates = true;
-            this.loadRenderTexture();
         }
         if (this.updateType & UpdateType.Global) {
             assertTruthy(this.localTransform);
-            this.globalTransform = Matrix3d.copy(parent?.globalTransform || this.localTransform, this.globalTransform);
-            if (this.parentHasRenderTexture && this.props.parent?.rtt) {
+            if (this.parentHasRenderTexture === true && parent?.rtt === true) {
+                // we are at the start of the RTT chain, so we need to reset the globalTransform
+                // for correct RTT rendering
                 this.globalTransform = Matrix3d.identity();
+                // Maintain a full scene global transform for bounds detection
+                this.sceneGlobalTransform = Matrix3d.copy(parent?.globalTransform || Matrix3d.identity()).multiply(this.localTransform);
             }
-            if (parent) {
+            else if (this.parentHasRenderTexture === true &&
+                parent?.rtt === false) {
+                // we're part of an RTT chain but our parent is not the main RTT node
+                // so we need to propogate the sceneGlobalTransform of the parent
+                // to maintain a full scene global transform for bounds detection
+                this.sceneGlobalTransform = Matrix3d.copy(parent?.sceneGlobalTransform || this.localTransform).multiply(this.localTransform);
+                this.globalTransform = Matrix3d.copy(parent?.globalTransform || this.localTransform, this.globalTransform);
+            }
+            else {
+                this.globalTransform = Matrix3d.copy(parent?.globalTransform || this.localTransform, this.globalTransform);
+            }
+            if (parent !== null) {
                 this.globalTransform.multiply(this.localTransform);
             }
             this.calculateRenderCoords();
@@ -440,6 +464,7 @@ export class CoreNode extends EventEmitter {
             this.createRenderBounds();
             this.setUpdateType(UpdateType.RenderState);
             this.setUpdateType(UpdateType.Children);
+            this.childUpdateType |= UpdateType.RenderBounds;
         }
         if (this.updateType & UpdateType.RenderState) {
             renderState = this.checkRenderBounds();
@@ -497,6 +522,7 @@ export class CoreNode extends EventEmitter {
         }
         if (this.props.strictBounds === true &&
             this.renderState === CoreNodeRenderState.OutOfBounds) {
+            this.updateType &= ~UpdateType.RenderBounds; // remove render bounds update
             return;
         }
         if (this.updateType & UpdateType.Children && this.children.length > 0) {
@@ -537,6 +563,13 @@ export class CoreNode extends EventEmitter {
         if (renderState === CoreNodeRenderState.OutOfBounds) {
             this.updateRenderState(renderState);
             this.updateIsRenderable();
+            if (this.rtt === true &&
+                renderState === CoreNodeRenderState.OutOfBounds) {
+                // notify children that we are going out of bounds
+                // we have to do this now before we stop processing the render tree
+                this.notifyChildrenRTTOfUpdate(renderState);
+                // this.childUpdateType |= UpdateType.RenderState;
+            }
         }
         // reset update type
         this.updateType = 0;
@@ -549,6 +582,21 @@ export class CoreNode extends EventEmitter {
         }
         return rttNode;
     }
+    getRTTParentRenderState() {
+        const rttNode = this.rttParent || this.findParentRTTNode();
+        if (!rttNode) {
+            return null;
+        }
+        return rttNode.renderState;
+    }
+    notifyChildrenRTTOfUpdate(renderState) {
+        for (const child of this.children) {
+            // force child to update render state
+            child.updateRenderState(renderState);
+            child.updateIsRenderable();
+            child.notifyChildrenRTTOfUpdate(renderState);
+        }
+    }
     notifyParentRTTOfUpdate() {
         if (this.parent === null) {
             return;
@@ -579,10 +627,6 @@ export class CoreNode extends EventEmitter {
         if (boundLargeThanBound(this.renderBound, this.strictBound)) {
             return CoreNodeRenderState.InViewport;
         }
-        // if we are part of a parent render texture, we're always in bounds
-        if (this.parentHasRenderTexture === true) {
-            return CoreNodeRenderState.InBounds;
-        }
         // check if we dont have dimensions, take our parent's render state
         if (this.parent !== null &&
             (this.props.width === 0 || this.props.height === 0)) {
@@ -591,7 +635,8 @@ export class CoreNode extends EventEmitter {
         return CoreNodeRenderState.OutOfBounds;
     }
     updateBoundingRect() {
-        const { renderCoords, globalTransform: transform } = this;
+        const transform = this.sceneGlobalTransform || this.globalTransform;
+        const renderCoords = this.sceneRenderCoords || this.renderCoords;
         assertTruthy(transform);
         assertTruthy(renderCoords);
         const { tb, tc } = transform;
@@ -610,7 +655,7 @@ export class CoreNode extends EventEmitter {
             // we have a parent with a valid bound, copy it
             const parentBound = this.parent.strictBound;
             this.strictBound = createBound(parentBound.x1, parentBound.y1, parentBound.x2, parentBound.y2);
-            this.preloadBound = createPreloadBounds(this.strictBound, this.stage.boundsMargin);
+            this.preloadBound = createPreloadBounds(this.strictBound, this.boundsMargin);
         }
         else {
             // no parent or parent does not have a bound, take the stage boundaries
@@ -632,11 +677,13 @@ export class CoreNode extends EventEmitter {
         }
         // clipping is enabled and we are in bounds create our own bounds
         const { x, y, width, height } = this.props;
-        const { tx, ty } = this.globalTransform || {};
+        // Pick the global transform if available, otherwise use the local transform
+        // global transform is only available if the node in an RTT chain
+        const { tx, ty } = this.sceneGlobalTransform || this.globalTransform || {};
         const _x = tx ?? x;
         const _y = ty ?? y;
         this.strictBound = createBound(_x, _y, _x + width, _y + height, this.strictBound);
-        this.preloadBound = createPreloadBounds(this.strictBound, this.stage.boundsMargin);
+        this.preloadBound = createPreloadBounds(this.strictBound, this.boundsMargin);
     }
     updateRenderState(renderState) {
         if (renderState === this.renderState) {
@@ -733,9 +780,8 @@ export class CoreNode extends EventEmitter {
         return this.props.shader !== null;
     }
     calculateRenderCoords() {
-        const { width, height, globalTransform: transform } = this;
-        assertTruthy(transform);
-        const { tx, ty, ta, tb, tc, td } = transform;
+        const { width, height } = this;
+        const { tx, ty, ta, tb, tc, td } = this.globalTransform;
         if (tb === 0 && tc === 0) {
             const minX = tx;
             const maxX = tx + width * ta;
@@ -762,6 +808,36 @@ export class CoreNode extends EventEmitter {
             //bottom-left
             tx + height * tb, ty + height * td, this.renderCoords);
         }
+        if (this.sceneGlobalTransform === undefined) {
+            return;
+        }
+        const { tx: stx, ty: sty, ta: sta, tb: stb, tc: stc, td: std, } = this.sceneGlobalTransform;
+        if (stb === 0 && stc === 0) {
+            const minX = stx;
+            const maxX = stx + width * sta;
+            const minY = sty;
+            const maxY = sty + height * std;
+            this.sceneRenderCoords = RenderCoords.translate(
+            //top-left
+            minX, minY, 
+            //top-right
+            maxX, minY, 
+            //bottom-right
+            maxX, maxY, 
+            //bottom-left
+            minX, maxY, this.sceneRenderCoords);
+        }
+        else {
+            this.sceneRenderCoords = RenderCoords.translate(
+            //top-left
+            stx, sty, 
+            //top-right
+            stx + width * sta, sty + width * stc, 
+            //bottom-right
+            stx + width * sta + height * stb, sty + width * stc + height * std, 
+            //bottom-left
+            stx + height * stb, sty + height * std, this.sceneRenderCoords);
+        }
     }
     /**
      * This function calculates the clipping rectangle for a node.
@@ -1058,6 +1134,26 @@ export class CoreNode extends EventEmitter {
     set autosize(value) {
         this.props.autosize = value;
     }
+    get boundsMargin() {
+        return (this.props.boundsMargin ??
+            this.parent?.boundsMargin ??
+            this.stage.boundsMargin);
+    }
+    set boundsMargin(value) {
+        if (value === this.props.boundsMargin) {
+            return;
+        }
+        if (value === null) {
+            this.props.boundsMargin = value;
+        }
+        else {
+            const bm = Array.isArray(value)
+                ? value
+                : [value, value, value, value];
+            this.props.boundsMargin = bm;
+        }
+        this.setUpdateType(UpdateType.RenderBounds);
+    }
     get clipping() {
         return this.props.clipping;
     }
@@ -1235,28 +1331,11 @@ export class CoreNode extends EventEmitter {
             width: this.width,
             height: this.height,
         });
-        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);
-        });
+        this.stage.renderer.renderToTexture(this);
     }
     cleanupRenderTexture() {
         this.unloadTexture();
         this.clearRTTInheritance();
-        this.stage.renderer?.removeRTTNode(this);
         this.hasRTTupdates = false;
         this.texture = null;
     }