Renderer v1.0.0

.eslintignore

@@ -11,3 +11,4 @@ releases
 .tmp
 .env
 scripts
+vitest.config.ts

.gitignore

@@ -3,8 +3,7 @@ node_modules
 .idea
 typedocs
 dist
-dist-cfg
-dist-vitest
+dist-*
 examples/dist-tsc
 visual-regression/failed-results
 visual-regression/certified-snapshots/*-local

Dockerfile

@@ -4,13 +4,13 @@ FROM mcr.microsoft.com/playwright:v1.39.0-jammy
 # Set the working directory
 WORKDIR /work
 
-# Install PNPM
-RUN npm install -g pnpm
-
 # Copy the necessary files to the container
 COPY .npmrc .npmrc
 COPY package.json package.json
 
+# Install PNPM
+RUN corepack prepare && corepack enable
+
 # Get pnpm to install the version of Node declared in .npmrc
 RUN pnpm exec ls
 

README.md

@@ -89,145 +89,42 @@ See [docs/ManualRegressionTests.md].
 
 See [RELEASE.md](./RELEASE.md)
 
-## Main Space vs Core Space
+## Installing Fonts
 
-The Lightning 3 Renderer runs code in two logically seperate environments:
-the **Main Space** and the **Core Space**.
-
-Users of the Renderer will write most of their code for the Main Space using
-the **Main API**. This is code that will always run on the browser's main thread
-and includes initializing the Renderer, creating/modifying/destroying nodes,
-controlling animations, etc.
-
-The Core Space is where the actual rendering of each UI frame happens and is
-mostly meant to be transparent to users of the Renderer. However, the Core Space
-is where all of the code that must be tightly coupled to the rendering process
-must be loaded and run. The Core Space is extendible by users by writing
-**Core Extensions** via the **Core API**. This allows for users to develop their
-own shaders, textures, text renderers, dynamic shader effects, and more. Fonts
-used in an application must be loaded in this way too. The Core Space exists
-seperately from the Main Space because it is allowed to execute on the page's
-main thread OR a Web Worker thread. A **Core Driver** (see below) is used to
-bridge the Main Space with the Core Space.
-
-## Core Drivers
-
-The Lightning 3 Renderer is designed to be able to use a single thread or
-multiple web worker threads based on the configuration of a **Core Driver**.
-
-A Core Driver essentially acts as a bridge between the Main and Core spaces
-defined above.
-
-The Renderer comes with two Core Drivers: the Main Core Driver for single
-threaded rendering and the ThreadX Core Driver for multi-threaded rendering.
-
-NOTE: The ThreadX Core Driver is experimental and even when the Renderer
-graduates from beta may still not be ready for production use.
-
-### Main Core Driver
-
-The Main Core Driver renders your application on the web page's main thread.
-
-It can be configured into the Renderer like so:
-
-```ts
-import { MainCoreDriver, RendererMain } from '@lightningjs/renderer';
-
-const renderer = new RendererMain(
-  {
-    // App Config
-  },
-  'app', // App div ID
-  new MainCoreDriver(), // Main Render driver
-);
-
-// ...
-```
-
-### ThreadX Core Driver
-
-The ThreadX Core Driver renders your application on a seperately spawned
-Web Worker thread.
-
-It can be configured into the Renderer like so:
+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 {
-  ThreadXCoreDriver,
   RendererMain,
+  WebTrFontFace,
+  SdfTrFontFace,
 } from '@lightningjs/renderer';
 
-// The `@lightningjs/vite-plugin-import-chunk-url` Vite plugin is required for this:
-import coreWorkerUrl from './common/CoreWorker.js?importChunkUrl';
-
 const renderer = new RendererMain(
   {
-    // App Config
+    appWidth: 1920,
+    appHeight: 1080,
+    // ...Other Renderer Config
   },
-  'app', // App div ID
-  new ThreadXCoreDriver({
-    coreWorkerUrl,
-  });
+  'app', // id of div to insert Canvas.
 );
-```
-
-## Core Extensions
-
-To load fonts, and/or other custom code into the Core Space, you must write a
-Core Extension and pass it via dynamically importable URL to the initialization
-of the Renderer.
 
-Just like with loading the ThreadX Core Web Worker for the ThreadX, you import
-your core extension using the `@lightningjs/vite-plugin-import-chunk-url` plugin so that
-it's code is bundled and loaded seperately from your main app's bundle.
-
-You can write a Core Extension by extending the CoreExtension class from the
-Core API like so:
-
-```ts
-import {
-  CoreExtension,
-  WebTrFontFace,
-  SdfTrFontFace,
-  type Stage,
-} from '@lightning/renderer/core';
-
-export default class MyCoreExtension extends CoreExtension {
-  async run(stage: Stage) {
-    // Load fonts into core
-    stage.fontManager.addFontFace(
-      new WebTrFontFace('Ubuntu', {}, '/fonts/Ubuntu-Regular.ttf'),
-    );
-
-    stage.fontManager.addFontFace(
-      new SdfTrFontFace(
-        'Ubuntu',
-        {},
-        'msdf',
-        stage,
-        '/fonts/Ubuntu-Regular.msdf.png',
-        '/fonts/Ubuntu-Regular.msdf.json',
-      ),
-    );
-  }
-}
-```
-
-And then in your application's main entry point you can import it using
-`@lightningjs/vite-plugin-import-chunk-url`:
-
-```ts
-import coreExtensionModuleUrl from './MyCoreExtension.js?importChunkUrl';
-
-// Set up driver, etc.
+// Load fonts into renderer
+renderer.stage.fontManager.addFontFace(
+  new WebTrFontFace('Ubuntu', {}, '/fonts/Ubuntu-Regular.ttf'),
+);
 
-// Initialize the Renderer
-const renderer = new RendererMain(
-  {
-    // Other Renderer Config...
-    coreExtensionModule: coreExtensionModuleUrl,
-  },
-  'app',
-  driver,
+renderer.stage.fontManager.addFontFace(
+  new SdfTrFontFace(
+    'Ubuntu',
+    {},
+    'msdf',
+    stage,
+    '/fonts/Ubuntu-Regular.msdf.png',
+    '/fonts/Ubuntu-Regular.msdf.json',
+  ),
 );
 ```

docs/CustomShaderEffectTexture.md

@@ -0,0 +1,5 @@
+# Custom Shaders / Effects / Textures
+
+For some examples on how to create custom shaders, effects and textures, see
+the (custom-shader-effect-texture)[./example-projects/custom-shader-effect-texture]
+example project.

docs/ManualRegressionTests.md

@@ -4,49 +4,49 @@ In addition to the automated [Visual Regression Tests](../visual-regression/READ
 there are some tests that should be run manually on embedded devices to ensure
 the Renderer is working properly.
 
-## Reference-Based Texture Memory Management Test
+## Critical Texture Memory Cleanup Test
 
-`?test=reference-texture-memory`
+`?test=texture-cleanup-critical&monitor=true`
 
-This test confirms the Renderer's ability to proactively garbage collect
-textures that are, at the very least, likely to not be referenced anymore in
-memory.
+This test confirms the Renderer's ability to clean up textures when it never
+has a chance to perform Idle Texture Cleanups.
 
 Within an infinite loop, the test updates the texture of a single full screen
 background node to a new random NoiseTexture in rapid succession.
 
-**Expected Results**: The test runs for at least 1 hour without crashing.
+**Expected Results**: The tests runs for at least 30 mins minutes without
+crashing or the visible Nodes becoming black. The Memory Monitor shows loaded
+textures reaching the Critical Threshold and then falling back to the target.
 
-To confirm that the textures are being properly disposed of, you can use the Chrome Task Manager to monitor the GPU's memory usage:
+To further confirm that the textures are being properly disposed of, you can use
+the Chrome Task Manager to monitor the GPU's memory usage:
 
 1. Click Window > Task Manager
 2. Locate the "GPU Process"
 3. Observe the "Memory Footprint" column
-4. The value should eventually drop significantly toward a minimum and/or reach a
-   threadhold.
+4. Like the Memory Monitor, the value should increase, and fall significantly
+   repeatedly.
 
-By default, the ManualCountTextureUsageTracker is used to track texture usage. Also test the experimental FinalizationRegistryTextureUsageTracker instead, by setting the URL param "finalizationRegistry=true".
+## Idle Texture Memory Cleanup Test
 
-## Threshold-Based Texture Memory Management Test
+`?test=texture-cleanup-idle&monitor=true`
 
-`?test=threshold-texture-memory`
-
-This test confirms the Renderer's ability to garbage collect textures from GPU VRAM
-that are still referenced and assigned to Nodes but no longer visible within
-the configured `boundsMargin` when the configured `txMemByteThreshold` is
-exceeded.
+This test confirms the Renderer's ability to clean up textures that are no longer
+renderable (not in the configured `boundsMargin`) from GPU VRAM when the Renderer
+becomes idle.
 
 Within an infinite loop, this test generates a grid of Nodes with random NoiseTextures
 assigned first completely visible on screen (for at least a frame) and then moves
 them outside of the configured `boundsMargin` before repeating the loop.
 
-**Expected Results**: The tests runs for at least XXXX minutes on an XXXX running WPE
-without crashing or the visible Nodes becoming blank.
+**Expected Results**: The tests runs for at least 30 mins minutes without
+crashing or the visible Nodes becoming black. The Memory Monitor shows loaded
+textures falling to the Target Threshold roughly every 5 seconds.
 
-To test that the textures are being properly disposed of, you can use the Chrome Task Manager to monitor the GPU's memory usage:
+To further test that the textures are being properly disposed of, you can use the Chrome Task Manager to monitor the GPU's memory usage:
 
 1. Click Window > Task Manager
 2. Locate the "GPU Process"
 3. Observe the "Memory Footprint" column
-4. The value should eventually drop significantly toward a minimum and/or reach a
-   threshold.
+4. Like the Memory Monitor, the value should increase, and fall significantly
+   repeatedly.

docs/example-projects/custom-shader-effect-texture/index.html

@@ -0,0 +1,21 @@
+<html>
+  <head>
+    <title>Renderer Browser Test</title>
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+        overflow: hidden;
+      }
+
+      #app {
+        display: inline-block;
+        background: #3677e0;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./src/index.ts"></script>
+  </body>
+</html>

docs/example-projects/custom-shader-effect-texture/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "renderer-custom-shader",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "start": "vite --open --host",
+    "build": "tsc && vite build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@lightningjs/renderer": "link:../../.."
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.12",
+    "typescript": "^5.4.5",
+    "vite": "^5.2.11"
+  }
+}