@lightningjs/renderer 2.14.3 → 2.15.0

package/src/core/CoreTextureManager.ts

@@ -389,12 +389,18 @@ export class CoreTextureManager extends EventEmitter {
 
         // For non-image textures, upload immediately
         if (texture.type !== TextureType.image) {
-          this.uploadTexture(texture);
+          this.uploadTexture(texture).catch((err) => {
+            console.error('Failed to upload non-image texture:', err);
+            texture.setState('failed');
+          });
         } else {
           // For image textures, queue for throttled upload
           // If it's a priority texture, upload it immediately
           if (priority === true) {
-            this.uploadTexture(texture);
+            this.uploadTexture(texture).catch((err) => {
+              console.error('Failed to upload priority texture:', err);
+              texture.setState('failed');
+            });
           } else {
             this.enqueueUploadTexture(texture);
           }
@@ -410,8 +416,9 @@ export class CoreTextureManager extends EventEmitter {
    * Upload a texture to the GPU
    *
    * @param texture Texture to upload
+   * @returns Promise that resolves when the texture is fully loaded
    */
-  uploadTexture(texture: Texture): void {
+  async uploadTexture(texture: Texture): Promise<void> {
     if (
       this.stage.txMemManager.doNotExceedCriticalThreshold === true &&
       this.stage.txMemManager.criticalCleanupRequested === true
@@ -427,7 +434,7 @@ export class CoreTextureManager extends EventEmitter {
       return;
     }
 
-    coreContext.load();
+    await coreContext.load();
   }
 
   /**
@@ -442,7 +449,7 @@ export class CoreTextureManager extends EventEmitter {
    *
    * @param maxProcessingTime - The maximum processing time in milliseconds
    */
-  processSome(maxProcessingTime: number): void {
+  async processSome(maxProcessingTime: number): Promise<void> {
     if (this.initialized === false) {
       return;
     }
@@ -456,18 +463,28 @@ export class CoreTextureManager extends EventEmitter {
     ) {
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       const texture = this.priorityQueue.pop()!;
-      texture.getTextureData().then(() => {
-        this.uploadTexture(texture);
-      });
+      try {
+        await texture.getTextureData();
+        await this.uploadTexture(texture);
+      } catch (error) {
+        console.error('Failed to process priority texture:', error);
+        // Continue with next texture instead of stopping entire queue
+      }
     }
 
-    // Process uploads
+    // Process uploads - await each upload to prevent GPU overload
     while (
       this.uploadTextureQueue.length > 0 &&
       getTimeStamp() - startTime < maxProcessingTime
     ) {
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      this.uploadTexture(this.uploadTextureQueue.shift()!);
+      const texture = this.uploadTextureQueue.shift()!;
+      try {
+        await this.uploadTexture(texture);
+      } catch (error) {
+        console.error('Failed to upload texture:', error);
+        // Continue with next texture instead of stopping entire queue
+      }
     }
   }
 

package/src/core/Stage.ts

@@ -68,6 +68,7 @@ export interface StageOptions {
   canvas: HTMLCanvasElement | OffscreenCanvas;
   clearColor: number;
   fpsUpdateInterval: number;
+  targetFPS: number;
   enableContextSpy: boolean;
   forceWebGL2: boolean;
   numImageWorkers: number;
@@ -111,6 +112,16 @@ export class Stage {
   public readonly strictBounds: boolean;
   public readonly defaultTexture: Texture | null = null;
 
+  /**
+   * Target frame time in milliseconds (calculated from targetFPS)
+   *
+   * @remarks
+   * This is pre-calculated to avoid recalculating on every frame.
+   * - 0 means no throttling (use display refresh rate)
+   * - >0 means throttle to this frame time (1000 / targetFPS)
+   */
+  public targetFrameTime: number = 0;
+
   /**
    * Renderer Event Bus for the Stage to emit events onto
    *
@@ -156,6 +167,10 @@ export class Stage {
     } = options;
 
     this.eventBus = options.eventBus;
+
+    // Calculate target frame time from targetFPS option
+    this.targetFrameTime = options.targetFPS > 0 ? 1000 / options.targetFPS : 0;
+
     this.txManager = new CoreTextureManager(this, {
       numImageWorkers,
       createImageBitmapSupport,
@@ -292,6 +307,20 @@ export class Stage {
     this.renderRequested = true;
   }
 
+  /**
+   * Update the target frame time based on the current targetFPS setting
+   *
+   * @remarks
+   * This should be called whenever the targetFPS option is changed
+   * to ensure targetFrameTime stays in sync.
+   * targetFPS of 0 means no throttling (targetFrameTime = 0)
+   * targetFPS > 0 means throttle to 1000/targetFPS milliseconds
+   */
+  updateTargetFrameTime() {
+    this.targetFrameTime =
+      this.options.targetFPS > 0 ? 1000 / this.options.targetFPS : 0;
+  }
+
   updateFrameTime() {
     const newFrameTime = getTimeStamp();
     this.lastFrameTime = this.currentFrameTime;
@@ -372,8 +401,13 @@ export class Stage {
       this.root.update(this.deltaTime, this.root.clippingRect);
     }
 
-    // Process some textures
-    this.txManager.processSome(this.options.textureProcessingTimeLimit);
+    // Process some textures asynchronously but don't block the frame
+    // Use a background task to prevent frame drops
+    this.txManager
+      .processSome(this.options.textureProcessingTimeLimit)
+      .catch((err) => {
+        console.error('Error processing textures:', err);
+      });
 
     // Reset render operations and clear the canvas
     renderer.reset();

package/src/core/platform.ts

@@ -24,14 +24,38 @@ import type { Stage } from './Stage.js';
  */
 export const startLoop = (stage: Stage) => {
   let isIdle = false;
-  const runLoop = () => {
+  let lastFrameTime = 0;
+
+  const runLoop = (currentTime: number = 0) => {
+    const targetFrameTime = stage.targetFrameTime;
+
+    // Check if we should throttle this frame
+    if (targetFrameTime > 0 && currentTime - lastFrameTime < targetFrameTime) {
+      // Too early for next frame, schedule with setTimeout for precise timing
+      const delay = targetFrameTime - (currentTime - lastFrameTime);
+      setTimeout(() => requestAnimationFrame(runLoop), delay);
+      return;
+    }
+
+    lastFrameTime = currentTime;
+
     stage.updateFrameTime();
     stage.updateAnimations();
 
     if (!stage.hasSceneUpdates()) {
       // We still need to calculate the fps else it looks like the app is frozen
       stage.calculateFps();
-      setTimeout(runLoop, 16.666666666666668);
+
+      if (targetFrameTime > 0) {
+        // Use setTimeout for throttled idle frames
+        setTimeout(
+          () => requestAnimationFrame(runLoop),
+          Math.max(targetFrameTime, 16.666666666666668),
+        );
+      } else {
+        // Use standard idle timeout when not throttling
+        setTimeout(() => requestAnimationFrame(runLoop), 16.666666666666668);
+      }
 
       if (!isIdle) {
         stage.eventBus.emit('idle');
@@ -49,8 +73,21 @@ export const startLoop = (stage: Stage) => {
     isIdle = false;
     stage.drawFrame();
     stage.flushFrameEvents();
-    requestAnimationFrame(runLoop);
+
+    // Schedule next frame
+    if (targetFrameTime > 0) {
+      // Use setTimeout + rAF combination for precise FPS control
+      const nextFrameDelay = Math.max(
+        0,
+        targetFrameTime - (performance.now() - currentTime),
+      );
+      setTimeout(() => requestAnimationFrame(runLoop), nextFrameDelay);
+    } else {
+      // Use standard rAF when not throttling
+      requestAnimationFrame(runLoop);
+    }
   };
+
   requestAnimationFrame(runLoop);
 };
 

package/src/core/renderers/CoreContextTexture.ts

@@ -34,7 +34,7 @@ export abstract class CoreContextTexture {
     this.memManager.setTextureMemUse(this.textureSource, byteSize);
   }
 
-  abstract load(): void;
+  abstract load(): Promise<void>;
   abstract free(): void;
 
   get renderable(): boolean {

package/src/core/renderers/canvas/CanvasCoreTexture.ts

@@ -35,19 +35,19 @@ export class CanvasCoreTexture extends CoreContextTexture {
       }
     | undefined;
 
-  load(): void {
+  async load(): Promise<void> {
     this.textureSource.setState('loading');
 
-    this.onLoadRequest()
-      .then((size) => {
-        this.textureSource.setState('loaded', size);
-        this.textureSource.freeTextureData();
-        this.updateMemSize();
-      })
-      .catch((err) => {
-        this.textureSource.setState('failed', err as Error);
-        this.textureSource.freeTextureData();
-      });
+    try {
+      const size = await this.onLoadRequest();
+      this.textureSource.setState('loaded', size);
+      this.textureSource.freeTextureData();
+      this.updateMemSize();
+    } catch (err) {
+      this.textureSource.setState('failed', err as Error);
+      this.textureSource.freeTextureData();
+      throw err;
+    }
   }
 
   free(): void {

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

@@ -41,6 +41,11 @@ export class WebGlCoreCtxRenderTexture extends WebGlCoreCtxTexture {
     const { glw } = this;
     const nativeTexture = (this._nativeCtxTexture =
       this.createNativeCtxTexture());
+
+    if (!nativeTexture) {
+      throw new Error('Failed to create native texture for RenderTexture');
+    }
+
     const { width, height } = this.textureSource;
 
     // Create Framebuffer object

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

@@ -78,54 +78,65 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
    * to force the texture to be pre-loaded prior to accessing the ctxTexture
    * property.
    */
-  load() {
-    // If the texture is already loading or loaded, don't load it again.
+  async load(): Promise<void> {
+    // If the texture is already loading or loaded, return resolved promise
     if (this.state === 'loading' || this.state === 'loaded') {
-      return;
+      return Promise.resolve();
     }
 
     this.state = 'loading';
     this.textureSource.setState('loading');
+
+    // Await the native texture creation to ensure GPU buffer is fully allocated
     this._nativeCtxTexture = this.createNativeCtxTexture();
 
     if (this._nativeCtxTexture === null) {
       this.state = 'failed';
-      this.textureSource.setState(
-        'failed',
-        new Error('Could not create WebGL Texture'),
-      );
+      const error = new Error('Could not create WebGL Texture');
+      this.textureSource.setState('failed', error);
       console.error('Could not create WebGL Texture');
-      return;
+      throw error;
     }
 
-    this.onLoadRequest()
-      .then(({ width, height }) => {
-        // If the texture has been freed while loading, return early.
-        if (this.state === 'freed') {
-          return;
-        }
-
-        this.state = 'loaded';
-        this._w = width;
-        this._h = height;
-        // Update the texture source's width and height so that it can be used
-        // for rendering.
-        this.textureSource.setState('loaded', { width, height });
-
-        // cleanup source texture data
-        this.textureSource.freeTextureData();
-      })
-      .catch((err) => {
-        // If the texture has been freed while loading, return early.
-        if (this.state === 'freed') {
-          return;
-        }
-
-        this.state = 'failed';
-        this.textureSource.setState('failed', err);
+    try {
+      const { width, height } = await this.onLoadRequest();
+
+      // If the texture has been freed while loading, return early.
+      // Type assertion needed because state could change during async operations
+      if ((this.state as string) === 'freed') {
+        return;
+      }
+
+      this.state = 'loaded';
+      this._w = width;
+      this._h = height;
+      // Update the texture source's width and height so that it can be used
+      // for rendering.
+      this.textureSource.setState('loaded', { width, height });
+
+      // cleanup source texture data next tick
+      // This is done using queueMicrotask to ensure it runs after the current
+      // event loop tick, allowing the texture to be fully loaded and bound
+      // to the GL context before freeing the source data.
+      // This is important to avoid issues with the texture data being
+      // freed while the texture is still being loaded or used.
+      queueMicrotask(() => {
         this.textureSource.freeTextureData();
-        console.error(err);
       });
+    } catch (err: unknown) {
+      // If the texture has been freed while loading, return early.
+      // Type assertion needed because state could change during async operations
+      if ((this.state as string) === 'freed') {
+        return;
+      }
+
+      this.state = 'failed';
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.textureSource.setState('failed', error);
+      this.textureSource.freeTextureData();
+      console.error(err);
+      throw error; // Re-throw to propagate the error
+    }
   }
 
   /**
@@ -268,17 +279,17 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
   }
 
   /**
-   * Create native context texture
+   * Create native context texture asynchronously
    *
    * @remarks
-   * When this method returns the returned texture will be bound to the GL context state.
+   * When this method resolves, the returned texture will be bound to the GL context state
+   * and fully ready for use. This ensures proper GPU resource allocation timing.
    *
-   * @param width
-   * @param height
-   * @returns
+   * @returns Promise that resolves to the native WebGL texture or null on failure
    */
-  protected createNativeCtxTexture() {
+  protected createNativeCtxTexture(): WebGLTexture | null {
     const { glw } = this;
+
     const nativeTexture = glw.createTexture();
     if (!nativeTexture) {
       return null;
@@ -296,6 +307,7 @@ export class WebGlCoreCtxTexture extends CoreContextTexture {
     // texture wrapping method
     glw.texParameteri(glw.TEXTURE_WRAP_S, glw.CLAMP_TO_EDGE);
     glw.texParameteri(glw.TEXTURE_WRAP_T, glw.CLAMP_TO_EDGE);
+
     return nativeTexture;
   }
 }

package/src/main-api/Renderer.ts

@@ -157,6 +157,22 @@ export interface RendererMainSettings {
    */
   fpsUpdateInterval?: number;
 
+  /**
+   * Target FPS for the global render loop
+   *
+   * @remarks
+   * Controls the maximum frame rate of the entire rendering system.
+   * When set to 0, no throttling is applied (use display refresh rate).
+   * When set to a positive number, the global requestAnimationFrame loop
+   * will be throttled to this target FPS, affecting all animations and rendering.
+   *
+   * This provides global performance control for the entire application,
+   * useful for managing performance on lower-end devices.
+   *
+   * @defaultValue `0` (no throttling, use display refresh rate)
+   */
+  targetFPS?: number;
+
   /**
    * Include context call (i.e. WebGL) information in FPS updates
    *
@@ -403,6 +419,7 @@ export class RendererMain extends EventEmitter {
         settings.devicePhysicalPixelRatio || window.devicePixelRatio,
       clearColor: settings.clearColor ?? 0x00000000,
       fpsUpdateInterval: settings.fpsUpdateInterval || 0,
+      targetFPS: settings.targetFPS || 0,
       numImageWorkers:
         settings.numImageWorkers !== undefined ? settings.numImageWorkers : 2,
       enableContextSpy: settings.enableContextSpy ?? false,
@@ -412,7 +429,7 @@ export class RendererMain extends EventEmitter {
       quadBufferSize: settings.quadBufferSize ?? 4 * 1024 * 1024,
       fontEngines: settings.fontEngines,
       strictBounds: settings.strictBounds ?? true,
-      textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
+      textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 42,
       canvas: settings.canvas || document.createElement('canvas'),
       createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
     };
@@ -449,6 +466,7 @@ export class RendererMain extends EventEmitter {
       enableContextSpy: this.settings.enableContextSpy,
       forceWebGL2: this.settings.forceWebGL2,
       fpsUpdateInterval: this.settings.fpsUpdateInterval,
+      targetFPS: this.settings.targetFPS,
       numImageWorkers: this.settings.numImageWorkers,
       renderEngine: this.settings.renderEngine,
       textureMemory: resolvedTxSettings,
@@ -748,4 +766,42 @@ export class RendererMain extends EventEmitter {
   setClearColor(color: number) {
     this.stage.setClearColor(color);
   }
+
+  /**
+   * Gets the target FPS for the global render loop
+   *
+   * @returns The current target FPS (0 means no throttling)
+   *
+   * @remarks
+   * This controls the maximum frame rate of the entire rendering system.
+   * When 0, the system runs at display refresh rate.
+   */
+  get targetFPS(): number {
+    return this.stage.options.targetFPS;
+  }
+
+  /**
+   * Sets the target FPS for the global render loop
+   *
+   * @param fps - The target FPS to set for the global render loop.
+   *              Set to 0 or a negative value to disable throttling.
+   *
+   * @remarks
+   * This setting affects the entire rendering system immediately.
+   * All animations, rendering, and frame updates will be throttled
+   * to this target FPS. Provides global performance control.
+   *
+   * @example
+   * ```typescript
+   * // Set global target to 30fps for better performance
+   * renderer.targetFPS = 30;
+   *
+   * // Disable global throttling (use display refresh rate)
+   * renderer.targetFPS = 0;
+   * ```
+   */
+  set targetFPS(fps: number) {
+    this.stage.options.targetFPS = fps > 0 ? fps : 0;
+    this.stage.updateTargetFrameTime();
+  }
 }