@lightningjs/renderer 0.9.1 → 0.9.3

package/package.json

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

package/src/common/IAnimationController.ts

@@ -16,14 +16,73 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { IEventEmitter } from '@lightningjs/threadx';
 
 export type AnimationControllerState = 'running' | 'paused' | 'stopped';
 
-export interface IAnimationController {
+/**
+ * Animation Controller interface
+ *
+ * @remarks
+ * This interface is used to control animations. It provides methods to start,
+ * stop, pause, and restore animations. It also provides a way to wait for the
+ * animation to stop.
+ *
+ * This interface extends the `IEventEmitter` interface, which means you can
+ * listen to these events emitted by the animation controller:
+ * - `animating` - Emitted when the animation finishes it's delay phase and
+ *   starts animating.
+ * - `stopped` - Emitted when the animation stops either by calling the `stop()`
+ *    method or when the animation finishes naturally.
+ */
+export interface IAnimationController extends IEventEmitter {
+  /**
+   * Start the animation
+   *
+   * @remarks
+   * If the animation is paused this method will resume the animation.
+   */
   start(): IAnimationController;
+  /**
+   * Stop the animation
+   *
+   * @remarks
+   * Resets the animation to the start state
+   */
   stop(): IAnimationController;
+  /**
+   * Pause the animation
+   */
   pause(): IAnimationController;
+  /**
+   * Restore the animation to the original values
+   */
   restore(): IAnimationController;
+
+  /**
+   * Promise that resolves when the last active animation is stopped (including
+   * when the animation finishes naturally).
+   *
+   * @remarks
+   * The Promise returned by this method is reset every time the animation
+   * enters a new start/stop cycle. This means you must call `start()` before
+   * calling this method if you want to wait for the animation to stop.
+   *
+   * This method always returns a resolved promise if the animation is currently
+   * in a stopped state.
+   *
+   * @returns
+   */
   waitUntilStopped(): Promise<void>;
+
+  /**
+   * Current state of the animation
+   *
+   * @remarks
+   * - `stopped` - The animation is currently stopped (at the beggining or end
+   *   of the animation)
+   * - `running` - The animation is currently running
+   * - `paused` - The animation is currently paused
+   */
   readonly state: AnimationControllerState;
 }

package/src/core/CoreNode.ts

@@ -339,6 +339,7 @@ export class CoreNode extends EventEmitter implements ICoreNode {
 
   private onTextureLoaded: TextureLoadedEventHandler = (target, dimensions) => {
     this.autosizeNode(dimensions);
+
     // Texture was loaded. In case the RAF loop has already stopped, we request
     // a render to ensure the texture is rendered.
     this.stage.requestRender();
@@ -353,6 +354,11 @@ export class CoreNode extends EventEmitter implements ICoreNode {
       type: 'texture',
       dimensions,
     } satisfies NodeTextureLoadedPayload);
+
+    // 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);
+    }
   };
 
   private onTextureFailed: TextureFailedEventHandler = (target, error) => {
@@ -431,6 +437,45 @@ export class CoreNode extends EventEmitter implements ICoreNode {
       .multiply(this.scaleRotateTransform)
       .translate(-pivotTranslateX, -pivotTranslateY);
 
+    // Handle 'contain' resize mode
+    const { width, height } = this.props;
+    const texture = this.props.texture;
+    if (
+      texture &&
+      texture.dimensions &&
+      this.props.textureOptions?.resizeMode?.type === 'contain'
+    ) {
+      let resizeModeScaleX = 1;
+      let resizeModeScaleY = 1;
+      let extraX = 0;
+      let extraY = 0;
+      const { width: tw, height: th } = texture.dimensions;
+      const txAspectRatio = tw / th;
+      const nodeAspectRatio = width / height;
+      if (txAspectRatio > nodeAspectRatio) {
+        // Texture is wider than node
+        // Center the node vertically (shift down by extraY)
+        // Scale the node vertically to maintain original aspect ratio
+        const scaleX = width / tw;
+        const scaledTxHeight = th * scaleX;
+        extraY = (height - scaledTxHeight) / 2;
+        resizeModeScaleY = scaledTxHeight / height;
+      } else {
+        // Texture is taller than node (or equal)
+        // Center the node horizontally (shift right by extraX)
+        // Scale the node horizontally to maintain original aspect ratio
+        const scaleY = height / th;
+        const scaledTxWidth = tw * scaleY;
+        extraX = (width - scaledTxWidth) / 2;
+        resizeModeScaleX = scaledTxWidth / width;
+      }
+
+      // Apply the extra translation and scale to the local transform
+      this.localTransform
+        .translate(extraX, extraY)
+        .scale(resizeModeScaleX, resizeModeScaleY);
+    }
+
     this.setUpdateType(UpdateType.Global);
   }
 

package/src/core/CoreTextureManager.ts

@@ -57,6 +57,36 @@ export interface TextureManagerDebugInfo {
   idCacheSize: number;
 }
 
+export type ResizeModeOptions =
+  | {
+      /**
+       * Specifies that the image should be resized to cover the specified dimensions.
+       */
+      type: 'cover';
+      /**
+       * The horizontal clipping position
+       * To clip the left, set clipX to 0. To clip the right, set clipX to 1.
+       * clipX 0.5 will clip a equal amount from left and right
+       *
+       * @defaultValue 0.5
+       */
+      clipX?: number;
+      /**
+       * The vertical clipping position
+       * To clip the top, set clipY to 0. To clip the bottom, set clipY to 1.
+       * clipY 0.5 will clip a equal amount from top and bottom
+       *
+       * @defaultValue 0.5
+       */
+      clipY?: number;
+    }
+  | {
+      /**
+       * Specifies that the image should be resized to fit within the specified dimensions.
+       */
+      type: 'contain';
+    };
+
 /**
  * Universal options for all texture types
  *
@@ -129,6 +159,15 @@ export interface TextureOptions {
    * @defaultValue `false`
    */
   flipY?: boolean;
+
+  /**
+   * You can use resizeMode to determine the clipping automatically from the width
+   * and height of the source texture. This can be convenient if you are unsure about
+   * the exact image sizes but want the image to cover a specific area.
+   *
+   * The resize modes cover and contain are supported
+   */
+  resizeMode?: ResizeModeOptions;
 }
 
 export class CoreTextureManager {
@@ -161,7 +200,7 @@ export class CoreTextureManager {
 
   constructor(numImageWorkers: number) {
     // Register default known texture types
-    if (this.hasCreateImageBitmap && this.hasWorker) {
+    if (this.hasCreateImageBitmap && this.hasWorker && numImageWorkers > 0) {
       this.imageWorkerManager = new ImageWorkerManager(numImageWorkers);
     }
 

package/src/core/animations/CoreAnimation.ts

@@ -36,6 +36,7 @@ export interface AnimationSettings {
 export class CoreAnimation extends EventEmitter {
   public propStartValues: Partial<INodeAnimatableProps> = {};
   public restoreValues: Partial<INodeAnimatableProps> = {};
+  public settings: AnimationSettings;
   private progress = 0;
   private delayFor = 0;
   private timingFunction: (t: number) => number | undefined;
@@ -44,7 +45,7 @@ export class CoreAnimation extends EventEmitter {
   constructor(
     private node: CoreNode,
     private props: Partial<INodeAnimatableProps>,
-    public settings: Partial<AnimationSettings>,
+    settings: Partial<AnimationSettings>,
   ) {
     super();
     this.propStartValues = {};
@@ -53,12 +54,19 @@ export class CoreAnimation extends EventEmitter {
       this.propStartValues[propName] = node[propName];
     });
 
-    this.timingFunction = (t: number) => t;
-
-    if (settings.easing && typeof settings.easing === 'string') {
-      this.timingFunction = getTimingFunction(settings.easing);
-    }
-    this.delayFor = settings.delay || 0;
+    const easing = settings.easing || 'linear';
+    const delay = settings.delay ?? 0;
+    this.settings = {
+      duration: settings.duration ?? 0,
+      delay,
+      easing,
+      loop: settings.loop ?? false,
+      repeat: settings.repeat ?? 0,
+      repeatDelay: settings.repeatDelay ?? 0,
+      stopMethod: settings.stopMethod ?? false,
+    };
+    this.timingFunction = getTimingFunction(easing);
+    this.delayFor = delay;
   }
 
   reset() {
@@ -96,24 +104,40 @@ export class CoreAnimation extends EventEmitter {
     }
   }
 
-  applyEasing(p: number, s: number, e: number): number {
+  private applyEasing(p: number, s: number, e: number): number {
     return (this.timingFunction(p) || p) * (e - s) + s;
   }
 
   update(dt: number) {
     const { duration, loop, easing, stopMethod } = this.settings;
-    if (!duration) {
+    const { delayFor } = this;
+    if (duration === 0 && delayFor === 0) {
       this.emit('finished', {});
       return;
     }
 
     if (this.delayFor > 0) {
       this.delayFor -= dt;
+      if (this.delayFor >= 0) {
+        // Either no or more delay left. Exit.
+        return;
+      } else {
+        // We went beyond the delay time, add it back to dt so we can continue
+        // with the animation.
+        dt = -this.delayFor;
+        this.delayFor = 0;
+      }
+    }
+
+    if (duration === 0) {
+      // No duration, we are done.
+      this.emit('finished', {});
       return;
     }
 
-    if (this.delayFor <= 0 && this.progress === 0) {
-      this.emit('start', {});
+    if (this.progress === 0) {
+      // Progress is 0, we are starting the post-delay part of the animation.
+      this.emit('animating', {});
     }
 
     this.progress += dt / duration;

package/src/core/animations/CoreAnimationController.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/unbound-method */
 /*
  * If not stated otherwise in this file or this component's LICENSE file the
  * following copyright and licenses apply:
@@ -24,50 +25,48 @@ import type {
 import type { AnimationManager } from './AnimationManager.js';
 import type { CoreAnimation } from './CoreAnimation.js';
 import { assertTruthy } from '../../utils.js';
+import { EventEmitter } from '../../common/EventEmitter.js';
 
-export class CoreAnimationController implements IAnimationController {
-  startedPromise: Promise<void> | null = null;
-  /**
-   * If this is null, then the animation hasn't started yet.
-   */
-  startedResolve: ((scope?: any) => void) | null = null;
-
-  stoppedPromise: Promise<void> | null = null;
+export class CoreAnimationController
+  extends EventEmitter
+  implements IAnimationController
+{
+  stoppedPromise: Promise<void>;
   /**
    * If this is null, then the animation is in a finished / stopped state.
    */
   stoppedResolve: (() => void) | null = null;
+  state: AnimationControllerState;
 
   constructor(
     private manager: AnimationManager,
     private animation: CoreAnimation,
   ) {
+    super();
     this.state = 'stopped';
-  }
+    // Initial stopped promise is resolved (since the animation is stopped)
+    this.stoppedPromise = Promise.resolve();
 
-  state: AnimationControllerState;
+    // Bind event handlers
+    this.onAnimating = this.onAnimating.bind(this);
+    this.onFinished = this.onFinished.bind(this);
+  }
 
   start(): IAnimationController {
-    this.makeStartedPromise();
-    this.animation.once('start', this.started.bind(this));
-
-    this.makeStoppedPromise();
-    this.animation.once('finished', this.finished.bind(this));
-
-    // prevent registering the same animation twice
-    if (!this.manager.activeAnimations.has(this.animation)) {
-      this.manager.registerAnimation(this.animation);
+    if (this.state !== 'running') {
+      this.makeStoppedPromise();
+      this.registerAnimation();
+      this.state = 'running';
     }
-
-    this.state = 'running';
     return this;
   }
 
   stop(): IAnimationController {
-    this.manager.unregisterAnimation(this.animation);
+    this.unregisterAnimation();
     if (this.stoppedResolve !== null) {
       this.stoppedResolve();
       this.stoppedResolve = null;
+      this.emit('stopped', this);
     }
     this.animation.reset();
     this.state = 'stopped';
@@ -75,7 +74,7 @@ export class CoreAnimationController implements IAnimationController {
   }
 
   pause(): IAnimationController {
-    this.manager.unregisterAnimation(this.animation);
+    this.unregisterAnimation();
     this.state = 'paused';
     return this;
   }
@@ -86,26 +85,24 @@ export class CoreAnimationController implements IAnimationController {
     return this;
   }
 
-  waitUntilStarted(): Promise<void> {
-    this.makeStartedPromise();
-    const promise = this.startedPromise;
-    assertTruthy(promise);
-    return promise;
+  waitUntilStopped(): Promise<void> {
+    return this.stoppedPromise;
   }
 
-  waitUntilStopped(): Promise<void> {
-    this.makeStoppedPromise();
-    const promise = this.stoppedPromise;
-    assertTruthy(promise);
-    return promise;
+  private registerAnimation(): void {
+    // Hook up event listeners
+    this.animation.once('finished', this.onFinished);
+    this.animation.on('animating', this.onAnimating);
+    // Then register the animation
+    this.manager.registerAnimation(this.animation);
   }
 
-  private makeStartedPromise(): void {
-    if (this.startedResolve === null) {
-      this.startedPromise = new Promise((resolve) => {
-        this.startedResolve = resolve;
-      });
-    }
+  private unregisterAnimation(): void {
+    // First unregister the animation
+    this.manager.unregisterAnimation(this.animation);
+    // Then unhook event listeners
+    this.animation.off('finished', this.onFinished);
+    this.animation.off('animating', this.onAnimating);
   }
 
   private makeStoppedPromise(): void {
@@ -116,33 +113,31 @@ export class CoreAnimationController implements IAnimationController {
     }
   }
 
-  private started(): void {
-    assertTruthy(this.startedResolve);
-    // resolve promise (and pass current this to continue to the chain)
-    this.startedResolve(this);
-    this.startedResolve = null;
-  }
-
-  private finished(): void {
+  private onFinished(this: CoreAnimationController): void {
     assertTruthy(this.stoppedResolve);
     // If the animation is looping, then we need to restart it.
     const { loop, stopMethod } = this.animation.settings;
 
     if (stopMethod === 'reverse') {
       this.animation.reverse();
-      this.start();
       return;
     }
 
-    // resolve promise
-    this.stoppedResolve();
-    this.stoppedResolve = null;
-
     if (loop) {
       return;
     }
 
     // unregister animation
-    this.manager.unregisterAnimation(this.animation);
+    this.unregisterAnimation();
+
+    // resolve promise
+    this.stoppedResolve();
+    this.stoppedResolve = null;
+    this.emit('stopped', this);
+    this.state = 'stopped';
+  }
+
+  private onAnimating(this: CoreAnimationController): void {
+    this.emit('animating', this);
   }
 }

package/src/core/lib/ImageWorker.ts

@@ -119,15 +119,10 @@ export class ImageWorkerManager {
     return workers;
   }
 
-  private getNextWorker(): Worker {
+  private getNextWorker(): Worker | undefined {
     const worker = this.workers[this.workerIndex];
     this.workerIndex = (this.workerIndex + 1) % this.workers.length;
-    return worker!;
-  }
-
-  private convertUrlToAbsolute(url: string): string {
-    const absoluteUrl = new URL(url, self.location.href);
-    return absoluteUrl.href;
+    return worker;
   }
 
   getImage(
@@ -137,14 +132,16 @@ export class ImageWorkerManager {
     return new Promise((resolve, reject) => {
       try {
         if (this.workers) {
-          const absoluteSrcUrl = this.convertUrlToAbsolute(src);
           const id = this.nextId++;
           this.messageManager[id] = [resolve, reject];
-          this.getNextWorker().postMessage({
-            id,
-            src: absoluteSrcUrl,
-            premultiplyAlpha,
-          });
+          const nextWorker = this.getNextWorker();
+          if (nextWorker) {
+            nextWorker.postMessage({
+              id,
+              src: src,
+              premultiplyAlpha,
+            });
+          }
         }
       } catch (error) {
         reject(error);

package/src/core/lib/utils.ts

@@ -248,3 +248,28 @@ export function isBoundPositive(bound: Bound): boolean {
 export function isRectPositive(rect: Rect): boolean {
   return rect.width > 0 && rect.height > 0;
 }
+
+export function convertUrlToAbsolute(url: string): string {
+  // handle local file imports
+  if (self.location.protocol === 'file:') {
+    const path = self.location.pathname.split('/');
+    path.pop();
+    const basePath = path.join('/');
+    const baseUrl = self.location.protocol + '//' + basePath;
+
+    // check if url has a leading dot
+    if (url.charAt(0) === '.') {
+      url = url.slice(1);
+    }
+
+    // check if url has a leading slash
+    if (url.charAt(0) === '/') {
+      url = url.slice(1);
+    }
+
+    return baseUrl + '/' + url;
+  }
+
+  const absoluteUrl = new URL(url, self.location.href);
+  return absoluteUrl.href;
+}

package/src/core/renderers/webgl/WebGlCoreRenderer.ts

@@ -50,6 +50,7 @@ import { WebGlContextWrapper } from '../../lib/WebGlContextWrapper.js';
 import { RenderTexture } from '../../textures/RenderTexture.js';
 import type { CoreNode } from '../../CoreNode.js';
 import { WebGlCoreCtxRenderTexture } from './WebGlCoreCtxRenderTexture.js';
+import { ImageTexture } from '../../textures/ImageTexture.js';
 
 const WORDS_PER_QUAD = 24;
 // const BYTES_PER_QUAD = WORDS_PER_QUAD * 4;
@@ -298,6 +299,32 @@ export class WebGlCoreRenderer extends CoreRenderer {
       texture = texture.parentTexture;
     }
 
+    const resizeMode = textureOptions?.resizeMode ?? false;
+
+    if (texture instanceof ImageTexture) {
+      if (resizeMode && texture.dimensions) {
+        const { width: tw, height: th } = texture.dimensions;
+        if (resizeMode.type === 'cover') {
+          const scaleX = width / tw;
+          const scaleY = height / th;
+          const scale = Math.max(scaleX, scaleY);
+          const precision = 1 / scale;
+          // Determine based on width
+          if (scale && scaleX && scaleX < scale) {
+            const desiredSize = precision * width;
+            texCoordX1 = (1 - desiredSize / tw) * (resizeMode.clipX ?? 0.5);
+            texCoordX2 = texCoordX1 + desiredSize / tw;
+          }
+          // Determine based on height
+          if (scale && scaleY && scaleY < scale) {
+            const desiredSize = precision * height;
+            texCoordY1 = (1 - desiredSize / th) * (resizeMode.clipY ?? 0.5);
+            texCoordY2 = texCoordY1 + desiredSize / th;
+          }
+        }
+      }
+    }
+
     // Flip texture coordinates if dictated by texture options
     if (flipX) {
       [texCoordX1, texCoordX2] = [texCoordX2, texCoordX1];

package/src/core/renderers/webgl/shaders/effects/BorderEffect.ts

@@ -76,7 +76,8 @@ export class BorderEffect extends ShaderEffect {
   };
 
   static override onEffectMask = `
-  float mask = clamp(shaderMask + width, 0.0, 1.0) - clamp(shaderMask, 0.0, 1.0);
+  float intR = shaderMask + 1.0;
+  float mask = clamp(intR + width, 0.0, 1.0) - clamp(intR, 0.0, 1.0);
   return mix(shaderColor, mix(shaderColor, maskColor, maskColor.a), mask);
   `;
 

package/src/core/textures/ImageTexture.ts

@@ -23,6 +23,7 @@ import {
   isCompressedTextureContainer,
   loadCompressedTexture,
 } from '../lib/textureCompression.js';
+import { convertUrlToAbsolute } from '../lib/utils.js';
 
 /**
  * Properties of the {@link ImageTexture}
@@ -37,7 +38,7 @@ export interface ImageTextureProps {
    *
    * @default ''
    */
-  src?: string | ImageData;
+  src?: string | ImageData | (() => ImageData);
   /**
    * Whether to premultiply the alpha channel into the color channels of the
    * image.
@@ -50,6 +51,10 @@ export interface ImageTextureProps {
    * @default true
    */
   premultiplyAlpha?: boolean | null;
+  /**
+   * `ImageData` textures are not cached unless a `key` is provided
+   */
+  key?: string | null;
 }
 
 /**
@@ -85,9 +90,16 @@ export class ImageTexture extends Texture {
         data: null,
       };
     }
-    if (src instanceof ImageData) {
+
+    if (typeof src !== 'string') {
+      if (src instanceof ImageData) {
+        return {
+          data: src,
+          premultiplyAlpha,
+        };
+      }
       return {
-        data: src,
+        data: src(),
         premultiplyAlpha,
       };
     }
@@ -97,13 +109,16 @@ export class ImageTexture extends Texture {
       return loadCompressedTexture(src);
     }
 
+    // Convert relative URL to absolute URL
+    const absoluteSrc = convertUrlToAbsolute(src);
+
     if (this.txManager.imageWorkerManager) {
       return await this.txManager.imageWorkerManager.getImage(
-        src,
+        absoluteSrc,
         premultiplyAlpha,
       );
     } else if (this.txManager.hasCreateImageBitmap) {
-      const response = await fetch(src);
+      const response = await fetch(absoluteSrc);
       const blob = await response.blob();
       const hasAlphaChannel =
         premultiplyAlpha ?? this.hasAlphaChannel(blob.type);
@@ -120,7 +135,7 @@ export class ImageTexture extends Texture {
       if (!(src.substr(0, 5) === 'data:')) {
         img.crossOrigin = 'Anonymous';
       }
-      img.src = src;
+      img.src = absoluteSrc;
       await new Promise<void>((resolve, reject) => {
         img.onload = () => resolve();
         img.onerror = () => reject(new Error(`Failed to load image`));
@@ -137,11 +152,12 @@ export class ImageTexture extends Texture {
 
   static override makeCacheKey(props: ImageTextureProps): string | false {
     const resolvedProps = ImageTexture.resolveDefaults(props);
-    // ImageTextures sourced by ImageData are non-cacheable
-    if (resolvedProps.src instanceof ImageData) {
+    // Only cache key-able textures; prioritise key
+    const key = resolvedProps.key || resolvedProps.src;
+    if (typeof key !== 'string') {
       return false;
     }
-    return `ImageTexture,${resolvedProps.src},${resolvedProps.premultiplyAlpha}`;
+    return `ImageTexture,${key},${resolvedProps.premultiplyAlpha ?? 'true'}`;
   }
 
   static override resolveDefaults(
@@ -150,6 +166,7 @@ export class ImageTexture extends Texture {
     return {
       src: props.src ?? '',
       premultiplyAlpha: props.premultiplyAlpha ?? true, // null,
+      key: props.key ?? null,
     };
   }