@lightningjs/renderer 0.8.3 → 0.9.0

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

@@ -17,12 +17,12 @@
  * limitations under the License.
  */
 
+import { assertTruthy, createWebGLContext, hasOwn } from '../../../utils.js';
 import {
-  assertTruthy,
-  createWebGLContext,
-  hasOwn,
-} from '../../../utils.js';
-import { CoreRenderer, type CoreRendererOptions, type QuadOptions } from '../CoreRenderer.js';
+  CoreRenderer,
+  type CoreRendererOptions,
+  type QuadOptions,
+} from '../CoreRenderer.js';
 import { WebGlCoreRenderOp } from './WebGlCoreRenderOp.js';
 import type { CoreContextTexture } from '../CoreContextTexture.js';
 import {
@@ -47,6 +47,9 @@ import {
 import type { Dimensions } from '../../../common/CommonTypes.js';
 import { WebGlCoreShader } from './WebGlCoreShader.js';
 import { WebGlContextWrapper } from '../../lib/WebGlContextWrapper.js';
+import { RenderTexture } from '../../textures/RenderTexture.js';
+import type { CoreNode } from '../../CoreNode.js';
+import { WebGlCoreCtxRenderTexture } from './WebGlCoreCtxRenderTexture.js';
 
 const WORDS_PER_QUAD = 24;
 // const BYTES_PER_QUAD = WORDS_PER_QUAD * 4;
@@ -72,7 +75,8 @@ export class WebGlCoreRenderer extends CoreRenderer {
   //// Render Op / Buffer Filling State
   curBufferIdx = 0;
   curRenderOp: WebGlCoreRenderOp | null = null;
-  renderables: Array<QuadOptions | WebGlCoreRenderOp> = [];
+  override rttNodes: CoreNode[] = [];
+  activeRttNode: CoreNode | null = null;
 
   //// Default Shader
   defaultShader: WebGlCoreShader;
@@ -83,6 +87,11 @@ export class WebGlCoreRenderer extends CoreRenderer {
    */
   defaultTexture: Texture;
 
+  /**
+   * Whether the renderer is currently rendering to a texture.
+   */
+  public renderToTextureActive = false;
+
   constructor(options: WebGlCoreRendererOptions) {
     super(options);
     this.mode = 'webgl';
@@ -90,6 +99,12 @@ export class WebGlCoreRenderer extends CoreRenderer {
     const { canvas, clearColor, bufferMemory } = options;
 
     this.defaultTexture = new ColorTexture(this.txManager);
+
+    // Mark the default texture as ALWAYS renderable
+    // This prevents it from ever being garbage collected.
+    // Fixes https://github.com/lightning-js/renderer/issues/262
+    this.defaultTexture.setRenderableOwner(this, true);
+
     // When the default texture is loaded, request a render in case the
     // RAF is paused. Fixes: https://github.com/lightning-js/renderer/issues/123
     this.defaultTexture.once('loaded', () => {
@@ -177,6 +192,12 @@ export class WebGlCoreRenderer extends CoreRenderer {
         this.txMemManager,
         textureSource,
       );
+    } else if (textureSource instanceof RenderTexture) {
+      return new WebGlCoreCtxRenderTexture(
+        this.glw,
+        this.txMemManager,
+        textureSource,
+      );
     }
     return new WebGlCoreCtxTexture(this.glw, this.txMemManager, textureSource);
   }
@@ -213,6 +234,9 @@ export class WebGlCoreRenderer extends CoreRenderer {
       tb,
       tc,
       td,
+      rtt: renderToTexture,
+      parentHasRenderTexture,
+      framebufferDimensions,
     } = params;
     let { texture } = params;
 
@@ -234,39 +258,22 @@ export class WebGlCoreRenderer extends CoreRenderer {
     const targetDims = {
       width,
       height,
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     };
     const targetShader = shader || this.defaultShader;
     assertTruthy(targetShader instanceof WebGlCoreShader);
-    if (curRenderOp) {
-      // If the current render op is not the same shader, create a new one
-      // If the current render op's shader props are not compatible with the
-      // the new shader props, create a new one render op.
-      if (
-        curRenderOp.shader !== targetShader ||
-        !compareRect(curRenderOp.clippingRect, clippingRect) ||
-        (curRenderOp.shader !== this.defaultShader &&
-          (!shaderProps ||
-            !curRenderOp.shader.canBatchShaderProps(
-              curRenderOp.shaderProps,
-              shaderProps,
-            )))
-      ) {
-        curRenderOp = null;
-      }
-    }
-    assertTruthy(targetShader instanceof WebGlCoreShader);
 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any
-    if (!curRenderOp) {
+    if (!this.reuseRenderOp(params)) {
       // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
       this.newRenderOp(
         targetShader,
-        shaderProps as any,
+        shaderProps as Record<string, unknown>,
         alpha,
         targetDims,
         clippingRect,
         bufferIdx,
+        renderToTexture,
+        parentHasRenderTexture,
+        framebufferDimensions,
       );
       curRenderOp = this.curRenderOp;
       assertTruthy(curRenderOp);
@@ -303,6 +310,7 @@ export class WebGlCoreRenderer extends CoreRenderer {
     const ctxTexture = txManager.getCtxTexture(texture);
     assertTruthy(ctxTexture instanceof WebGlCoreCtxTexture);
     const textureIdx = this.addTexture(ctxTexture, bufferIdx);
+
     curRenderOp = this.curRenderOp;
     assertTruthy(curRenderOp);
 
@@ -398,6 +406,9 @@ export class WebGlCoreRenderer extends CoreRenderer {
     dimensions: Dimensions,
     clippingRect: RectWithValid,
     bufferIdx: number,
+    renderToTexture?: boolean,
+    parentHasRenderTexture?: boolean,
+    framebufferDimensions?: Dimensions,
   ) {
     const curRenderOp = new WebGlCoreRenderOp(
       this.glw,
@@ -410,6 +421,9 @@ export class WebGlCoreRenderer extends CoreRenderer {
       dimensions,
       bufferIdx,
       0, // Z-Index is only used for explictly added Render Ops
+      renderToTexture,
+      parentHasRenderTexture,
+      framebufferDimensions,
     );
     this.curRenderOp = curRenderOp;
     this.renderOps.push(curRenderOp);
@@ -456,6 +470,50 @@ export class WebGlCoreRenderer extends CoreRenderer {
     return textureIdx;
   }
 
+  /**
+   * Test if the current Render operation can be reused for the specified parameters.
+   * @param params
+   * @returns
+   */
+  reuseRenderOp(params: QuadOptions) {
+    const { shader, shaderProps, parentHasRenderTexture, rtt, clippingRect } =
+      params;
+
+    const targetShader = shader || this.defaultShader;
+
+    // Switching shader program will require a new render operation
+    if (this.curRenderOp?.shader !== targetShader) {
+      return false;
+    }
+
+    // Switching clipping rect will require a new render operation
+    if (!compareRect(this.curRenderOp.clippingRect, clippingRect)) {
+      return false;
+    }
+
+    // Force new render operation if rendering to texture
+    // @todo: This needs to be improved, render operations could also be reused
+    // for rendering to texture
+    if (parentHasRenderTexture || rtt) {
+      return false;
+    }
+
+    // Check if the shader can batch the shader properties
+    if (
+      this.curRenderOp.shader !== this.defaultShader &&
+      (!shaderProps ||
+        !this.curRenderOp.shader.canBatchShaderProps(
+          this.curRenderOp.shaderProps,
+          shaderProps,
+        ))
+    ) {
+      return false;
+    }
+
+    // Render operation can be reused
+    return true;
+  }
+
   /**
    * add RenderOp to the render pipeline
    */
@@ -483,16 +541,91 @@ export class WebGlCoreRenderer extends CoreRenderer {
     if (doLog) {
       console.log('renderOps', this.renderOps.length);
     }
+
     this.renderOps.forEach((renderOp, i) => {
       if (doLog) {
-        console.log('renderOp', i, renderOp.numQuads);
+        console.log('Quads per operation', renderOp.numQuads);
       }
       renderOp.draw();
     });
+  }
 
-    // clean up
-    this.renderables = [];
+  renderToTexture(node: CoreNode) {
+    for (let i = 0; i < this.rttNodes.length; i++) {
+      if (this.rttNodes[i] === node) {
+        return;
+      }
+    }
+
+    // @todo: Better bottom up rendering order
+    this.rttNodes.unshift(node);
   }
-}
 
-const idx = 0;
+  renderRTTNodes() {
+    const { glw } = this;
+    const { txManager } = this.stage;
+    // Render all associated RTT nodes to their textures
+    for (let i = 0; i < this.rttNodes.length; i++) {
+      const node = this.rttNodes[i];
+
+      // Skip nodes that don't have RTT updates
+      if (!node || !node.hasRTTupdates) {
+        continue;
+      }
+
+      // Set the active RTT node to the current node
+      // So we can prevent rendering children of nested RTT nodes
+      this.activeRttNode = node;
+
+      assertTruthy(node.texture, 'RTT node missing texture');
+      const ctxTexture = txManager.getCtxTexture(node.texture);
+      assertTruthy(ctxTexture instanceof WebGlCoreCtxRenderTexture);
+      this.renderToTextureActive = true;
+
+      // Bind the the texture's framebuffer
+      glw.bindFramebuffer(ctxTexture.framebuffer);
+
+      glw.viewport(0, 0, ctxTexture.w, ctxTexture.h);
+      glw.clear();
+
+      // Render all associated quads to the texture
+      for (let i = 0; i < node.children.length; i++) {
+        const child = node.children[i];
+        if (!child) {
+          continue;
+        }
+        child.update(this.stage.deltaTime, {
+          x: 0,
+          y: 0,
+          width: 0,
+          height: 0,
+          valid: false,
+        });
+
+        this.stage.addQuads(child);
+        child.hasRTTupdates = false;
+      }
+
+      // Render all associated quads to the texture
+      this.render();
+
+      // Reset render operations
+      this.renderOps.length = 0;
+      node.hasRTTupdates = false;
+    }
+
+    // Bind the default framebuffer
+    glw.bindFramebuffer(null);
+
+    glw.viewport(0, 0, this.glw.canvas.width, this.glw.canvas.height);
+    this.renderToTextureActive = false;
+  }
+
+  removeRTTNode(node: CoreNode) {
+    const index = this.rttNodes.indexOf(node);
+    if (index === -1) {
+      return;
+    }
+    this.rttNodes.splice(index, 1);
+  }
+}

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

@@ -261,10 +261,35 @@ export abstract class WebGlCoreShader extends CoreShader {
     if (renderOp.textures.length > 0) {
       this.bindTextures(renderOp.textures);
     }
-    const { glw } = renderOp;
-    // Bind standard automatic uniforms
-    this.setUniform('u_resolution', [glw.canvas.width, glw.canvas.height]);
-    this.setUniform('u_pixelRatio', renderOp.options.pixelRatio);
+
+    const { glw, parentHasRenderTexture, renderToTexture } = renderOp;
+
+    // Skip if the parent and current operation both have render textures
+    if (renderToTexture && parentHasRenderTexture) {
+      return;
+    }
+
+    // Bind render texture framebuffer dimensions as resolution
+    // if the parent has a render texture
+    if (parentHasRenderTexture) {
+      const { width, height } = renderOp.framebufferDimensions || {};
+      // Force pixel ratio to 1.0 for render textures since they are always 1:1
+      // the final render texture will be rendered to the screen with the correct pixel ratio
+      this.setUniform('u_pixelRatio', 1.0);
+
+      // Set resolution to the framebuffer dimensions
+      this.setUniform(
+        'u_resolution',
+        new Float32Array([width ?? 0, height ?? 0]),
+      );
+    } else {
+      this.setUniform('u_pixelRatio', renderOp.options.pixelRatio);
+      this.setUniform(
+        'u_resolution',
+        new Float32Array([glw.canvas.width, glw.canvas.height]),
+      );
+    }
+
     if (props) {
       // Bind optional automatic uniforms
       // These are only bound if their keys are present in the props.

package/src/core/renderers/webgl/shaders/DefaultShader.ts

@@ -61,16 +61,14 @@ export class DefaultShader extends WebGlCoreShader {
       varying vec2 v_textureCoordinate;
 
       void main() {
-        vec2 normalized = a_position * u_pixelRatio / u_resolution;
-        vec2 zero_two = normalized * 2.0;
-        vec2 clip_space = zero_two - 1.0;
+        vec2 normalized = a_position * u_pixelRatio;
+        vec2 screenSpace = vec2(2.0 / u_resolution.x, -2.0 / u_resolution.y);
 
-        // pass to fragment
         v_color = a_color;
         v_textureCoordinate = a_textureCoordinate;
 
-        // flip y
-        gl_Position = vec4(clip_space * vec2(1.0, -1.0), 0, 1);
+        gl_Position = vec4(normalized.x * screenSpace.x - 1.0, normalized.y * -abs(screenSpace.y) + 1.0, 0.0, 1.0);
+        gl_Position.y = -sign(screenSpace.y) * gl_Position.y;
       }
     `,
     fragment: `

package/src/core/renderers/webgl/shaders/SdfShader.ts

@@ -136,8 +136,13 @@ export class SdfShader extends WebGlCoreShader {
       void main() {
         vec2 scrolledPosition = a_position * u_size - vec2(0, u_scrollY);
         vec2 transformedPosition = (u_transform * vec3(scrolledPosition, 1)).xy;
-        gl_Position = vec4((transformedPosition * u_pixelRatio / u_resolution * 2.0 - 1.0) * vec2(1, -1), 0, 1);
+
+        // Calculate screen space with pixel ratio
+        vec2 screenSpace = (transformedPosition * u_pixelRatio / u_resolution * 2.0 - 1.0) * vec2(1, -1);
+
+        gl_Position = vec4(screenSpace, 0.0, 1.0);
         v_texcoord = a_textureCoordinate;
+
       }
     `,
     fragment: `

package/src/core/text-rendering/TextRenderingUtils.ts

@@ -0,0 +1,36 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2024 Comcast Cable Communications Management, LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { NormalizedFontMetrics } from './font-face-types/TrFontFace.js';
+
+/**
+ * Calculate the default line height given normalized font metrics
+ *
+ * @remarks
+ * This method may be used for both the WebTrFontFace and SdfTrFontFace font types.
+ *
+ * @param metrics
+ * @param fontSize
+ * @returns
+ */
+export function calcDefaultLineHeight(
+  metrics: NormalizedFontMetrics,
+  fontSize: number,
+): number {
+  return fontSize * (metrics.ascender - metrics.descender + metrics.lineGap);
+}

package/src/core/text-rendering/TextTextureRendererUtils.ts

@@ -17,6 +17,9 @@
  * limitations under the License.
  */
 
+import type { NormalizedFontMetrics } from './font-face-types/TrFontFace.js';
+import type { WebTrFontFace } from './font-face-types/WebTrFontFace.js';
+
 /**
  * Returns CSS font setting string for use in canvas context.
  *
@@ -120,6 +123,77 @@ export function measureText(
   }, 0);
 }
 
+/**
+ * Get the font metrics for a font face.
+ *
+ * @remarks
+ * This function will attempt to grab the explicitly defined metrics from the
+ * font face first. If the font face does not have metrics defined, it will
+ * attempt to calculate the metrics using the browser's measureText method.
+ *
+ * If the browser does not support the font metrics API, it will use some
+ * default values.
+ *
+ * @param context
+ * @param fontFace
+ * @param fontSize
+ * @returns
+ */
+export function getWebFontMetrics(
+  context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+  fontFace: WebTrFontFace,
+  fontSize: number,
+): NormalizedFontMetrics {
+  if (fontFace.metrics) {
+    return fontFace.metrics;
+  }
+  // If the font face doesn't have metrics defined, we fallback to using the
+  // browser's measureText method to calculate take a best guess at the font
+  // actual font's metrics.
+  // - fontBoundingBox[Ascent|Descent] is the best estimate but only supported
+  //   in Chrome 87+ (2020), Firefox 116+ (2023), and Safari 11.1+ (2018).
+  //   - It is an estimate as it can vary between browsers.
+  // - actualBoundingBox[Ascent|Descent] is less accurate and supported in
+  //   Chrome 77+ (2019), Firefox 74+ (2020), and Safari 11.1+ (2018).
+  // - If neither are supported, we'll use some default values which will
+  //   get text on the screen but likely not be great.
+  // NOTE: It's been decided not to rely on fontBoundingBox[Ascent|Descent]
+  // as it's browser support is limited and it also tends to produce higher than
+  // expected values. It is instead HIGHLY RECOMMENDED that developers provide
+  // explicit metrics in the font face definition.
+  const browserMetrics = context.measureText(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+  );
+  console.warn(
+    `Font metrics not provided for Canvas Web font ${fontFace.fontFamily}. ` +
+      'Using fallback values. It is HIGHLY recommended you use the latest ' +
+      'version of the Lightning 3 `msdf-generator` tool to extract the default ' +
+      'metrics for the font and provide them in the Canvas Web font definition.',
+  );
+  let metrics: NormalizedFontMetrics;
+  if (
+    browserMetrics.actualBoundingBoxDescent &&
+    browserMetrics.actualBoundingBoxAscent
+  ) {
+    metrics = {
+      ascender: browserMetrics.actualBoundingBoxAscent / fontSize,
+      descender: -browserMetrics.actualBoundingBoxDescent / fontSize,
+      lineGap: 0.2,
+    };
+  } else {
+    // If the browser doesn't support the font metrics API, we'll use some
+    // default values.
+    metrics = {
+      ascender: 0.8,
+      descender: -0.2,
+      lineGap: 0.2,
+    };
+  }
+  // Save the calculated metrics to the font face for future use.
+  (fontFace.metrics as NormalizedFontMetrics | null) = metrics;
+  return metrics;
+}
+
 export interface WrapTextResult {
   l: string[];
   n: number[];

package/src/core/text-rendering/font-face-types/SdfTrFontFace/SdfTrFontFace.ts

@@ -22,7 +22,12 @@ import { assertTruthy } from '../../../../utils.js';
 import type { Stage } from '../../../Stage.js';
 import { WebGlCoreRenderer } from '../../../renderers/webgl/WebGlCoreRenderer.js';
 import { ImageTexture } from '../../../textures/ImageTexture.js';
-import { TrFontFace, type TrFontFaceDescriptors } from '../TrFontFace.js';
+import {
+  TrFontFace,
+  type NormalizedFontMetrics,
+  type TrFontFaceDescriptors,
+  type TrFontFaceOptions,
+} from '../TrFontFace.js';
 import type { FontShaper } from './internal/FontShaper.js';
 import { SdfFontShaper, type SdfFontData } from './internal/SdfFontShaper.js';
 
@@ -42,6 +47,12 @@ interface GlyphAtlasEntry {
   height: number;
 }
 
+export interface SdfTrFontFaceOptions extends TrFontFaceOptions {
+  atlasUrl: string;
+  atlasDataUrl: string;
+  stage: Stage;
+}
+
 export class SdfTrFontFace<
   FontTypeT extends SdfFontType = SdfFontType,
 > extends TrFontFace {
@@ -49,21 +60,16 @@ export class SdfTrFontFace<
   public readonly texture: ImageTexture;
   /**
    * Height of the tallest character in the font including the whitespace above it
+   * in SDF/vertex units.
    */
   public readonly maxCharHeight: number = 0;
   public readonly data: SdfFontData | undefined;
   public readonly shaper: FontShaper | undefined;
   public readonly glyphMap: Map<number, SdfFontData['chars'][0]> = new Map();
 
-  constructor(
-    fontFamily: string,
-    descriptors: Partial<TrFontFaceDescriptors>,
-    type: FontTypeT,
-    stage: Stage,
-    atlasUrl: string,
-    atlasDataUrl: string,
-  ) {
-    super(fontFamily, descriptors);
+  constructor(type: FontTypeT, options: SdfTrFontFaceOptions) {
+    super(options);
+    const { atlasUrl, atlasDataUrl, stage } = options;
     this.type = type;
     const renderer = stage.renderer;
     assertTruthy(
@@ -95,10 +101,11 @@ export class SdfTrFontFace<
       .then(async (response) => {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
         (this.data as SdfFontData) = await response.json();
+        assertTruthy(this.data);
         // Add all the glyphs to the glyph map
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         let maxCharHeight = 0;
-        this.data!.chars.forEach((glyph) => {
+        this.data.chars.forEach((glyph) => {
           this.glyphMap.set(glyph.id, glyph);
           const charHeight = glyph.yoffset + glyph.height;
           if (charHeight > maxCharHeight) {
@@ -110,9 +117,31 @@ export class SdfTrFontFace<
         // We know `data` is defined here, because we just set it
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         (this.shaper as FontShaper) = new SdfFontShaper(
-          this.data!,
+          this.data,
           this.glyphMap,
         );
+
+        // If the metrics aren't provided explicitly in the font face options,
+        // Gather them from the metrics added by the msdf-generator tool ()
+        // If they are missing then we throw an error.
+        if (!this.metrics) {
+          if (this.data?.lightningMetrics) {
+            const { ascender, descender, lineGap, unitsPerEm } =
+              this.data.lightningMetrics;
+            (this.metrics as NormalizedFontMetrics | null) = {
+              ascender: ascender / unitsPerEm,
+              descender: descender / unitsPerEm,
+              lineGap: lineGap / unitsPerEm,
+            };
+          } else {
+            throw new Error(
+              `Font metrics not found in ${this.type} font ${this.fontFamily}. ` +
+                'Make sure you are using the latest version of the Lightning ' +
+                '3 `msdf-generator` tool to generate your SDF fonts.',
+            );
+          }
+        }
+
         this.checkLoaded();
       })
       .catch(console.error);

package/src/core/text-rendering/font-face-types/SdfTrFontFace/internal/SdfFontShaper.ts

@@ -19,6 +19,7 @@
 
 import type { PeekableIterator } from '../../../renderers/SdfTextRenderer/internal/PeekableGenerator.js';
 import { SpecialCodepoints } from '../../../renderers/SdfTextRenderer/internal/SpecialCodepoints.js';
+import type { FontMetrics } from '../../TrFontFace.js';
 import {
   FontShaper,
   type FontShaperProps,
@@ -166,4 +167,5 @@ export interface SdfFontData {
     fieldType: 'sdf' | 'msdf';
     distanceRange: number;
   };
+  lightningMetrics?: FontMetrics;
 }