@lightningjs/renderer 3.0.0-beta5 → 3.0.0-beta7

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

@@ -351,15 +351,6 @@ export interface CoreNodeProps {
      * {@link TextRenderer} and should not be set explicitly.
      */
     texture: Texture | null;
-    /**
-     * [Deprecated]: Prevents the texture from being cleaned up when the Node is removed
-     *
-     * @remarks
-     * Please use the `preventCleanup` property on {@link TextureOptions} instead.
-     *
-     * @default false
-     */
-    preventCleanup: boolean;
     /**
      * Options to associate with the Node's Texture
      */
@@ -604,6 +595,12 @@ export interface CoreNodeProps {
      * are provided. Only works when createImageBitmap is supported on the browser.
      */
     srcY?: number;
+    /**
+     * Mark the node as interactive so we can perform hit tests on it
+     * when pointer events are registered.
+     * @default false
+     */
+    interactive?: boolean;
     /**
      * By enabling Strict bounds the renderer will not process & render child nodes of a node that is out of the visible area
      *
@@ -674,6 +671,10 @@ export declare class CoreNode extends EventEmitter {
     hasRTTupdates: boolean;
     parentHasRenderTexture: boolean;
     rttParent: CoreNode | null;
+    /**
+     * only used when rtt = true
+     */
+    framebufferDimensions: Dimensions | null;
     constructor(stage: Stage, props: CoreNodeProps);
     loadTexture(): void;
     unloadTexture(): void;
@@ -816,8 +817,6 @@ export declare class CoreNode extends EventEmitter {
     set zIndex(value: number);
     get parent(): CoreNode | null;
     set parent(newParent: CoreNode | null);
-    get preventCleanup(): boolean;
-    set preventCleanup(value: boolean);
     get rtt(): boolean;
     set rtt(value: boolean);
     private initRenderTexture;
@@ -840,12 +839,9 @@ export declare class CoreNode extends EventEmitter {
     get srcY(): number | undefined;
     set srcY(value: number);
     /**
-     * Returns the framebuffer dimensions of the node.
-     * If the node has a render texture, the dimensions are the same as the node's dimensions.
-     * If the node does not have a render texture, the dimensions are inherited from the parent.
-     * If the node parent has a render texture and the node is a render texture, the nodes dimensions are used.
+     * Returns the framebuffer dimensions of the RTT parent
      */
-    get framebufferDimensions(): Dimensions;
+    get parentFramebufferDimensions(): Dimensions;
     /**
      * Returns the parent render texture node if it exists.
      */
@@ -854,6 +850,9 @@ export declare class CoreNode extends EventEmitter {
     set texture(value: Texture | null);
     set textureOptions(value: TextureOptions);
     get textureOptions(): TextureOptions;
+    set interactive(value: boolean | undefined);
+    get interactive(): boolean | undefined;
+    setRTTUpdates(type: number): void;
     get strictBounds(): boolean;
     set strictBounds(v: boolean);
     animate(props: Partial<CoreNodeAnimateProps>, settings: Partial<AnimationSettings>): IAnimationController;

package/dist/src/core/CoreNode.js

@@ -16,7 +16,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { assertTruthy, getNewId, isProductionEnvironment, mergeColorAlphaPremultiplied, } from '../utils.js';
+import { assertTruthy, getNewId, mergeColorAlphaPremultiplied, isProductionEnvironment, } 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';
@@ -197,6 +197,10 @@ export class CoreNode extends EventEmitter {
     hasRTTupdates = false;
     parentHasRenderTexture = false;
     rttParent = null;
+    /**
+     * only used when rtt = true
+     */
+    framebufferDimensions = null;
     constructor(stage, props) {
         super();
         this.stage = stage;
@@ -214,6 +218,7 @@ export class CoreNode extends EventEmitter {
         this.shader = props.shader;
         this.src = props.src;
         this.rtt = props.rtt;
+        this.interactive = props.interactive;
         if (props.boundsMargin) {
             this.boundsMargin = Array.isArray(props.boundsMargin)
                 ? props.boundsMargin
@@ -228,9 +233,6 @@ export class CoreNode extends EventEmitter {
             UpdateType.Local |
             UpdateType.RenderBounds |
             UpdateType.RenderState);
-        if (isProductionEnvironment() === false && props.preventCleanup === true) {
-            console.warn('CoreNode.preventCleanup: Is deprecated and will be removed in upcoming release, please use textureOptions.preventCleanup instead');
-        }
         // 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 &&
@@ -661,7 +663,6 @@ export class CoreNode extends EventEmitter {
         }
     }
     createRenderBounds() {
-        assertTruthy(this.stage);
         if (this.parent !== null && this.parent.strictBound !== undefined) {
             // we have a parent with a valid bound, copy it
             const parentBound = this.parent.strictBound;
@@ -937,7 +938,6 @@ export class CoreNode extends EventEmitter {
             }
         }
         assertTruthy(this.globalTransform);
-        assertTruthy(this.renderCoords);
         // add to list of renderables to be sorted before rendering
         renderer.addQuad({
             width: this.props.width,
@@ -964,7 +964,9 @@ export class CoreNode extends EventEmitter {
             renderCoords: this.renderCoords,
             rtt: this.rtt,
             parentHasRenderTexture: this.parentHasRenderTexture,
-            framebufferDimensions: this.framebufferDimensions,
+            framebufferDimensions: this.parentHasRenderTexture === true
+                ? this.parentFramebufferDimensions
+                : null,
         });
     }
     //#region Properties
@@ -1010,13 +1012,12 @@ export class CoreNode extends EventEmitter {
     }
     set width(value) {
         if (this.props.width !== value) {
+            this.textureCoords = undefined;
             this.props.width = value;
             this.setUpdateType(UpdateType.Local);
-            if (this.props.rtt) {
-                this.texture = this.stage.txManager.createTexture('RenderTexture', {
-                    width: this.width,
-                    height: this.height,
-                });
+            if (this.props.rtt === true) {
+                this.framebufferDimensions.width = value;
+                this.texture = this.stage.txManager.createTexture('RenderTexture', this.framebufferDimensions);
                 this.setUpdateType(UpdateType.RenderTexture);
             }
         }
@@ -1026,13 +1027,12 @@ export class CoreNode extends EventEmitter {
     }
     set height(value) {
         if (this.props.height !== value) {
+            this.textureCoords = undefined;
             this.props.height = value;
             this.setUpdateType(UpdateType.Local);
-            if (this.props.rtt) {
-                this.texture = this.stage.txManager.createTexture('RenderTexture', {
-                    width: this.width,
-                    height: this.height,
-                });
+            if (this.props.rtt === true) {
+                this.framebufferDimensions.height = value;
+                this.texture = this.stage.txManager.createTexture('RenderTexture', this.framebufferDimensions);
                 this.setUpdateType(UpdateType.RenderTexture);
             }
         }
@@ -1294,7 +1294,6 @@ export class CoreNode extends EventEmitter {
         this.props.parent = newParent;
         if (oldParent) {
             const index = oldParent.children.indexOf(this);
-            assertTruthy(index !== -1, "CoreNode.parent: Node not found in old parent's children!");
             oldParent.children.splice(index, 1);
             oldParent.setUpdateType(UpdateType.Children | UpdateType.ZIndexSortedChildren);
         }
@@ -1313,15 +1312,6 @@ export class CoreNode extends EventEmitter {
         // fetch render bounds from parent
         this.setUpdateType(UpdateType.RenderBounds | UpdateType.Children);
     }
-    get preventCleanup() {
-        return this.props.textureOptions.preventCleanup || false;
-    }
-    set preventCleanup(value) {
-        if (isProductionEnvironment() === false) {
-            console.warn('CoreNode.preventCleanup: Is deprecated and will be removed in upcoming release, please use textureOptions.preventCleanup instead');
-        }
-        this.props.textureOptions.preventCleanup = value;
-    }
     get rtt() {
         return this.props.rtt;
     }
@@ -1343,10 +1333,11 @@ export class CoreNode extends EventEmitter {
         }
     }
     initRenderTexture() {
-        this.texture = this.stage.txManager.createTexture('RenderTexture', {
+        this.framebufferDimensions = {
             width: this.width,
             height: this.height,
-        });
+        };
+        this.texture = this.stage.txManager.createTexture('RenderTexture', this.framebufferDimensions);
         this.stage.renderer.renderToTexture(this);
     }
     cleanupRenderTexture() {
@@ -1354,6 +1345,7 @@ export class CoreNode extends EventEmitter {
         this.clearRTTInheritance();
         this.hasRTTupdates = false;
         this.texture = null;
+        this.framebufferDimensions = null;
     }
     markChildrenWithRTT(node = null) {
         const parent = node || this;
@@ -1464,16 +1456,14 @@ export class CoreNode extends EventEmitter {
         this.props.srcY = value;
     }
     /**
-     * Returns the framebuffer dimensions of the node.
-     * If the node has a render texture, the dimensions are the same as the node's dimensions.
-     * If the node does not have a render texture, the dimensions are inherited from the parent.
-     * If the node parent has a render texture and the node is a render texture, the nodes dimensions are used.
+     * Returns the framebuffer dimensions of the RTT parent
      */
-    get framebufferDimensions() {
-        if (this.parentHasRenderTexture && !this.rtt && this.parent) {
-            return this.parent.framebufferDimensions;
+    get parentFramebufferDimensions() {
+        if (this.rttParent !== null) {
+            return this.rttParent.framebufferDimensions;
         }
-        return { width: this.width, height: this.height };
+        this.rttParent = this.findParentRTTNode();
+        return this.rttParent.framebufferDimensions;
     }
     /**
      * Returns the parent render texture node if it exists.
@@ -1514,6 +1504,20 @@ export class CoreNode extends EventEmitter {
     get textureOptions() {
         return this.props.textureOptions;
     }
+    set interactive(value) {
+        this.props.interactive = value;
+        // Update Stage's interactive Set
+        if (value === true) {
+            this.stage.interactiveNodes.add(this);
+        }
+    }
+    get interactive() {
+        return this.props.interactive;
+    }
+    setRTTUpdates(type) {
+        this.hasRTTupdates = true;
+        this.parent?.setRTTUpdates(type);
+    }
     get strictBounds() {
         return this.props.strictBounds;
     }