Merge branch 'main' into feat/pauseRafOptimization

.gitignore

@@ -1,7 +1,7 @@
 node_modules
 .DS_store
 .idea
-docs
+typedocs
 dist
 dist-cfg
 dist-vitest

README.md

@@ -28,7 +28,7 @@ pnpm test
 # Run Visual Regression Tests
 pnpm test:visual
 
-# Build API Documentation (builds into ./docs folder)
+# Build API Documentation (builds into ./typedocs folder)
 pnpm typedoc
 
 # Launch Example Tests in dev mode (includes Build Renderer (watch mode))

docs/NodeDependencyGraph.md

@@ -0,0 +1,5 @@
+# Node Depenedency Graph
+
+The diagram below describes the reactive flow of inputs into cached calculated data elements that are updated during each `update()` of a Core Node.
+
+![Dependency graph describing by way of a water fall the input and output relationship of calculated (and cached) data elements of a node](./images/dependency-graph.png)

docs/images/dependency-graph.txt

@@ -0,0 +1,2 @@
+https://lucid.app/lucidchart/f5c48c94-6096-44c5-bca2-97fe2b581095/edit?viewport_loc=-1167%2C-285%2C4800%2C2244%2Cm8WTkWxK2plY&invitationId=inv_44218a81-5bb9-4436-a5e6-5697c146e164
+https://lucid.app/publicSegments/view/56aa76d3-d7c2-4020-a3bc-8638084cb22b/image.png

examples/README.md

@@ -44,8 +44,14 @@ pnpm watch
 - `overlay` (boolean, default: "true")
   - Whether or not to show the text overlay in the bottom-right corner that
     displays the current test and driver being used.
+- `resolution` (number, default: 720)
+  - Resolution (height) of to render the test at (in logical pixels)
 - `fps` (boolean, default: "false")
   - Whether or not to log the latest FPS to the console every 1 second.
+- `ppr` (number, default: 1)
+  - Device physical pixel ratio.
+- `multiplier` (number, default: 1)
+  - In tests that support it, multiply the number of objects created by this number. Useful for performance tests.
 - `automation` (boolean, default: "false")
   - Automation mode.
   - Executes the exported `automation()` function for every Example Test

examples/common/ExampleSettings.ts

@@ -48,6 +48,14 @@ export interface ExampleSettings {
    * Whether the test is being run in automation mode.
    */
   automation: boolean;
+  /**
+   * For performance tests that want to support it, use this number as a multiplier
+   * for the number of objects created by a test.
+   *
+   * @remarks
+   * This value is `1` by default.
+   */
+  perfMultiplier: number;
   /**
    * If the test is run in automation mode, this method will take a visual
    * snapshot of the current state of the renderer's canvas for the Visual

examples/index.ts

@@ -54,30 +54,57 @@ const testModules = import.meta.glob('./tests/*.ts') as Record<
   () => Promise<TestModule>
 >;
 
+const appWidth = 1920;
+const appHeight = 1080;
+const defaultResolution = 720;
+const defaultPhysicalPixelRatio = 1;
+
 (async () => {
   // URL params
   // - driver: main | threadx (default: threadx)
   // - test: <test name> (default: test)
+  // - resolution: <number> (default: 720)
+  //   - Resolution (height) of to render the test at (in logical pixels)
+  // - ppr: <number> (default: 1)
+  //   - Device physical pixel ratio
   // - showOverlay: true | false (default: true)
   // - fps: true | false (default: false)
   //   - Log FPS to console every second
+  // - multiplier: <number> (default: 1)
+  //   - In tests that support it, multiply the number of objects created by
+  //     this number. Useful for performance tests.
   // - finalizationRegistry: true | false (default: false)
   //   - Use FinalizationRegistryTextureUsageTracker instead of
   //     ManualCountTextureUsageTracker
   // - automation: true | false (default: false)
+  //   - Run all tests in automation mode
   const urlParams = new URLSearchParams(window.location.search);
   const automation = urlParams.get('automation') === 'true';
   const test = urlParams.get('test') || (automation ? null : 'test');
   const showOverlay = urlParams.get('overlay') !== 'false';
   const logFps = urlParams.get('fps') === 'true';
+  const perfMultiplier = Number(urlParams.get('multiplier')) || 1;
+  const resolution = Number(urlParams.get('resolution')) || 720;
+  const physicalPixelRatio =
+    Number(urlParams.get('ppr')) || defaultPhysicalPixelRatio;
+  const logicalPixelRatio = resolution / appHeight;
 
   let driverName = urlParams.get('driver');
   if (driverName !== 'main' && driverName !== 'threadx') {
     driverName = 'main';
   }
 
   if (test) {
-    await runTest(test, driverName, urlParams, showOverlay, logFps);
+    await runTest(
+      test,
+      driverName,
+      urlParams,
+      showOverlay,
+      logicalPixelRatio,
+      physicalPixelRatio,
+      logFps,
+      perfMultiplier,
+    );
     return;
   }
   assertTruthy(automation);
@@ -91,7 +118,10 @@ async function runTest(
   driverName: string,
   urlParams: URLSearchParams,
   showOverlay: boolean,
+  logicalPixelRatio: number,
+  physicalPixelRatio: number,
   logFps: boolean,
+  perfMultiplier: number,
 ) {
   const testModule = testModules[getTestPath(test)];
   if (!testModule) {
@@ -109,6 +139,8 @@ async function runTest(
   const { renderer, appElement } = await initRenderer(
     driverName,
     logFps,
+    logicalPixelRatio,
+    physicalPixelRatio,
     customSettings,
   );
 
@@ -137,6 +169,7 @@ async function runTest(
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     testRoot: renderer.root!,
     automation: false,
+    perfMultiplier: perfMultiplier,
     snapshot: async () => {
       // No-op
     },
@@ -149,6 +182,8 @@ async function runTest(
 async function initRenderer(
   driverName: string,
   logFps: boolean,
+  logicalPixelRatio: number,
+  physicalPixelRatio: number,
   customSettings?: Partial<RendererMainSettings>,
 ) {
   let driver: ICoreDriver | null = null;
@@ -163,10 +198,10 @@ async function initRenderer(
 
   const renderer = new RendererMain(
     {
-      appWidth: 1920,
-      appHeight: 1080,
-      deviceLogicalPixelRatio: 0.6666667,
-      devicePhysicalPixelRatio: 1,
+      appWidth,
+      appHeight,
+      deviceLogicalPixelRatio: logicalPixelRatio,
+      devicePhysicalPixelRatio: physicalPixelRatio,
       clearColor: 0x00000000,
       coreExtensionModule: coreExtensionModuleUrl,
       fpsUpdateInterval: logFps ? 1000 : 0,
@@ -190,7 +225,13 @@ async function initRenderer(
 }
 
 async function runAutomation(driverName: string, logFps: boolean) {
-  const { renderer, appElement } = await initRenderer(driverName, logFps);
+  const logicalPixelRatio = defaultResolution / appHeight;
+  const { renderer, appElement } = await initRenderer(
+    driverName,
+    logFps,
+    logicalPixelRatio,
+    defaultPhysicalPixelRatio,
+  );
 
   // Iterate through all test modules
   for (const testPath in testModules) {
@@ -216,6 +257,7 @@ async function runAutomation(driverName: string, logFps: boolean) {
           driverName: driverName as 'main' | 'threadx',
           appElement,
           automation: true,
+          perfMultiplier: 1,
           snapshot: async () => {
             const snapshot = (window as any).snapshot as
               | ((testName: string) => Promise<void>)

examples/package.json

@@ -8,7 +8,7 @@
   "scripts": {
     "start": "concurrently -c \"auto\" \"pnpm:watch:renderer\" \"pnpm:dev\"",
     "start:prod": "concurrently -c \"auto\" \"pnpm:watch:renderer\" \"pnpm:watch\" \"sleep 5 && pnpm preview\"",
-    "dev": "vite --open",
+    "dev": "vite --open --host",
     "build": "vite build",
     "watch": "vite build --watch",
     "watch-all": "concurrently -c \"auto\" \"pnpm:watch:renderer\" \"pnpm:watch\"",

examples/tests/stress.ts

@@ -24,7 +24,11 @@ import type { ExampleSettings } from '../common/ExampleSettings.js';
 const randomIntBetween = (from: number, to: number) =>
   Math.floor(Math.random() * (to - from + 1) + from);
 
-export default async function ({ renderer, testRoot }: ExampleSettings) {
+export default async function ({
+  renderer,
+  testRoot,
+  perfMultiplier,
+}: ExampleSettings) {
   // create 100 nodes
   const nodes: INode[] = [];
 
@@ -35,7 +39,7 @@ export default async function ({ renderer, testRoot }: ExampleSettings) {
     parent: testRoot,
   });
 
-  for (let i = 0; i < 103; i++) {
+  for (let i = 0; i < 100 * perfMultiplier; i++) {
     const node = renderer.createNode({
       width: 505,
       height: 101,
@@ -61,6 +65,8 @@ export default async function ({ renderer, testRoot }: ExampleSettings) {
           {
             duration: 3000,
             easing: 'ease-out',
+            loop: true,
+            stopMethod: 'reverse',
           },
         )
         .start();
@@ -69,5 +75,5 @@ export default async function ({ renderer, testRoot }: ExampleSettings) {
 
   animate();
 
-  setInterval(animate, 3000);
+  // setInterval(animate, 3000);
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/renderer",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Lightning 3 Renderer",
   "type": "module",
   "main": "./dist/exports/index.js",