@lightningjs/renderer 2.12.1 → 2.13.0

package/src/utils.ts

@@ -1,248 +1,248 @@
-/*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2023 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 { ContextSpy } from './core/lib/ContextSpy.js';
-
-export function createWebGLContext(
-  canvas: HTMLCanvasElement | OffscreenCanvas,
-  forceWebGL2 = false,
-  contextSpy: ContextSpy | null,
-): WebGLRenderingContext {
-  const config: WebGLContextAttributes = {
-    alpha: true,
-    antialias: false,
-    depth: false,
-    stencil: true,
-    desynchronized: false,
-    // Disabled because it prevents Visual Regression Tests from working
-    // failIfMajorPerformanceCaveat: true,
-    powerPreference: 'high-performance',
-    premultipliedAlpha: true,
-    preserveDrawingBuffer: false,
-  };
-  const gl =
-    // TODO: Remove this assertion once this issue is fixed in TypeScript
-    // https://github.com/microsoft/TypeScript/issues/53614
-    (canvas.getContext(forceWebGL2 ? 'webgl2' : 'webgl', config) ||
-      canvas.getContext(
-        'experimental-webgl' as 'webgl',
-        config,
-      )) as unknown as WebGLRenderingContext | null;
-  if (!gl) {
-    throw new Error('Unable to create WebGL context');
-  }
-  if (contextSpy) {
-    // Proxy the GL context to log all GL calls
-    return new Proxy(gl, {
-      get(target, prop) {
-        const value = target[prop as never] as unknown;
-        if (typeof value === 'function') {
-          contextSpy.increment(String(prop));
-          return value.bind(target);
-        }
-        return value;
-      },
-    });
-  }
-
-  return gl;
-}
-
-/**
- * Asserts a condition is truthy, otherwise throws an error
- *
- * @remarks
- * Useful at the top of functions to ensure certain conditions, arguments and
- * properties are set/met before continuing. When using this function,
- * TypeScript will narrow away falsy types from the condition.
- *
- * @param condition
- * @param message
- * @returns
- */
-export function assertTruthy(
-  condition: unknown,
-  message?: string,
-): asserts condition {
-  if (isProductionEnvironment() === true) return;
-  if (!condition) {
-    throw new Error(message || 'Assertion failed');
-  }
-}
-
-/**
- * Merges two colors based on a given progress value.
- *
- * This function takes two colors (c1 and c2) represented as 32-bit integers
- * in RGBA format and blends them based on the provided progress value (p).
- * The result is a new color that is a weighted combination of the input colors,
- * where the weight is determined by the progress value.
- *
- * @param {number} c1 - The first color in RGBA format (32-bit integer).
- * @param {number} c2 - The second color in RGBA format (32-bit integer).
- * @param {number} p - The progress value between 0 and 1.
- * @returns {number} The merged color as a 32-bit integer in RGBA format.
- */
-export function mergeColorProgress(
-  rgba1: number,
-  rgba2: number,
-  p: number,
-): number {
-  const r1 = Math.trunc(rgba1 >>> 24);
-  const g1 = Math.trunc((rgba1 >>> 16) & 0xff);
-  const b1 = Math.trunc((rgba1 >>> 8) & 0xff);
-  const a1 = Math.trunc(rgba1 & 0xff);
-
-  const r2 = Math.trunc(rgba2 >>> 24);
-  const g2 = Math.trunc((rgba2 >>> 16) & 0xff);
-  const b2 = Math.trunc((rgba2 >>> 8) & 0xff);
-  const a2 = Math.trunc(rgba2 & 0xff);
-
-  const r = Math.round(r2 * p + r1 * (1 - p));
-  const g = Math.round(g2 * p + g1 * (1 - p));
-  const b = Math.round(b2 * p + b1 * (1 - p));
-  const a = Math.round(a2 * p + a1 * (1 - p));
-
-  return ((r << 24) | (g << 16) | (b << 8) | a) >>> 0;
-}
-
-/**
- * Given an RGBA encoded number, returns back the RGBA number with it's alpha
- * component multiplied by the passed `alpha` parameter.
- *
- * @internalRemarks
- * This method does NOT premultiply the alpha into the color channels. If that
- * is required (for internal use only) use {@link mergeColorAlphaPremultiplied}
- * instead.
- *
- * @param rgba RGBA encoded number
- * @param alpha Normalized alpha value (Range: 0.0 - 1.0)
- * @returns
- */
-export function mergeColorAlpha(rgba: number, alpha: number): number {
-  const r = rgba >>> 24;
-  const g = (rgba >>> 16) & 0xff;
-  const b = (rgba >>> 8) & 0xff;
-  const a = Math.trunc((rgba & 0xff) * alpha);
-
-  return ((r << 24) | (g << 16) | (b << 8) | a) >>> 0;
-}
-
-let premultiplyRGB = true;
-
-/**
- * RGB components should not be premultiplied when using Canvas renderer
- * @param mode  Renderer mode
- */
-export function setPremultiplyMode(mode: 'webgl' | 'canvas'): void {
-  premultiplyRGB = mode === 'webgl';
-}
-
-/**
- * Given an RGBA encoded number, returns back the RGBA number with it's alpha
- * component multiplied by the passed `alpha` parameter.
- *
- * For the webGl renderer, each color channel is premultiplied by the final alpha value.
- *
- * @remarks
- * If `flipEndianess` is set to true, the function will returned an ABGR encoded number
- * which is useful when the color value needs to be passed into a shader attribute.
- *
- * NOTE: Depending on the mode set by {@link setPremultiplyMode}, this method returns
- * a PREMULTIPLIED alpha color which is generally only useful in the context of the
- * internal rendering process. Use {@link mergeColorAlpha} if you need to blend an alpha
- * value into a color in the context of the Renderer's main API.
- *
- * @internalRemarks
- * Do not expose this method in the main API because Renderer users should instead use
- * {@link mergeColorAlpha} to manipulate the alpha value of a color.
- *
- * @internal
- * @param rgba RGBA encoded number
- * @param alpha Normalized alpha value (Range: 0.0 - 1.0)
- * @param flipEndianess Flip the endianess. RGBA becomes encoded as ABGR (for inserting colors into shader attributes)
- * @returns
- */
-export function mergeColorAlphaPremultiplied(
-  rgba: number,
-  alpha: number,
-  flipEndianess = false,
-): number {
-  const newAlpha = ((rgba & 0xff) / 255) * alpha;
-  const rgbAlpha = premultiplyRGB ? newAlpha : 1;
-  const r = Math.trunc((rgba >>> 24) * rgbAlpha);
-  const g = Math.trunc(((rgba >>> 16) & 0xff) * rgbAlpha);
-  const b = Math.trunc(((rgba >>> 8) & 0xff) * rgbAlpha);
-  const a = Math.trunc(newAlpha * 255);
-
-  if (flipEndianess) {
-    return ((a << 24) | (b << 16) | (g << 8) | r) >>> 0;
-  }
-
-  return ((r << 24) | (g << 16) | (b << 8) | a) >>> 0;
-}
-
-/**
- * Returns true if the given object has the given "own" property.
- *
- * @param obj
- * @param prop
- * @returns
- */
-export function hasOwn(obj: object, prop: string | number | symbol): boolean {
-  return Object.prototype.hasOwnProperty.call(obj, prop);
-}
-
-/**
- * Converts degrees to radians
- *
- * @param degrees
- * @returns
- */
-export function deg2Rad(degrees: number): number {
-  return (degrees * Math.PI) / 180;
-}
-
-/**
- * Returns image aspect ratio
- *
- * @param width
- * @param height
- * @returns
- */
-export function getImageAspectRatio(width: number, height: number): number {
-  return width / height;
-}
-
-/**
- * Checks import.meta if env is production
- *
- * @returns
- */
-export function isProductionEnvironment(): boolean {
-  return import.meta.env && import.meta.env.PROD;
-}
-
-/**
- * Returns a new unique ID
- */
-let nextId = 1;
-export function getNewId(): number {
-  return nextId++;
-}
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2023 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 { ContextSpy } from './core/lib/ContextSpy.js';
+
+export function createWebGLContext(
+  canvas: HTMLCanvasElement | OffscreenCanvas,
+  forceWebGL2 = false,
+  contextSpy: ContextSpy | null,
+): WebGLRenderingContext {
+  const config: WebGLContextAttributes = {
+    alpha: true,
+    antialias: false,
+    depth: false,
+    stencil: true,
+    desynchronized: false,
+    // Disabled because it prevents Visual Regression Tests from working
+    // failIfMajorPerformanceCaveat: true,
+    powerPreference: 'high-performance',
+    premultipliedAlpha: true,
+    preserveDrawingBuffer: false,
+  };
+  const gl =
+    // TODO: Remove this assertion once this issue is fixed in TypeScript
+    // https://github.com/microsoft/TypeScript/issues/53614
+    (canvas.getContext(forceWebGL2 ? 'webgl2' : 'webgl', config) ||
+      canvas.getContext(
+        'experimental-webgl' as 'webgl',
+        config,
+      )) as unknown as WebGLRenderingContext | null;
+  if (!gl) {
+    throw new Error('Unable to create WebGL context');
+  }
+  if (contextSpy) {
+    // Proxy the GL context to log all GL calls
+    return new Proxy(gl, {
+      get(target, prop) {
+        const value = target[prop as never] as unknown;
+        if (typeof value === 'function') {
+          contextSpy.increment(String(prop));
+          return value.bind(target);
+        }
+        return value;
+      },
+    });
+  }
+
+  return gl;
+}
+
+/**
+ * Asserts a condition is truthy, otherwise throws an error
+ *
+ * @remarks
+ * Useful at the top of functions to ensure certain conditions, arguments and
+ * properties are set/met before continuing. When using this function,
+ * TypeScript will narrow away falsy types from the condition.
+ *
+ * @param condition
+ * @param message
+ * @returns
+ */
+export function assertTruthy(
+  condition: unknown,
+  message?: string,
+): asserts condition {
+  if (isProductionEnvironment() === true) return;
+  if (!condition) {
+    throw new Error(message || 'Assertion failed');
+  }
+}
+
+/**
+ * Merges two colors based on a given progress value.
+ *
+ * This function takes two colors (c1 and c2) represented as 32-bit integers
+ * in RGBA format and blends them based on the provided progress value (p).
+ * The result is a new color that is a weighted combination of the input colors,
+ * where the weight is determined by the progress value.
+ *
+ * @param {number} c1 - The first color in RGBA format (32-bit integer).
+ * @param {number} c2 - The second color in RGBA format (32-bit integer).
+ * @param {number} p - The progress value between 0 and 1.
+ * @returns {number} The merged color as a 32-bit integer in RGBA format.
+ */
+export function mergeColorProgress(
+  rgba1: number,
+  rgba2: number,
+  p: number,
+): number {
+  const r1 = Math.trunc(rgba1 >>> 24);
+  const g1 = Math.trunc((rgba1 >>> 16) & 0xff);
+  const b1 = Math.trunc((rgba1 >>> 8) & 0xff);
+  const a1 = Math.trunc(rgba1 & 0xff);
+
+  const r2 = Math.trunc(rgba2 >>> 24);
+  const g2 = Math.trunc((rgba2 >>> 16) & 0xff);
+  const b2 = Math.trunc((rgba2 >>> 8) & 0xff);
+  const a2 = Math.trunc(rgba2 & 0xff);
+
+  const r = Math.round(r2 * p + r1 * (1 - p));
+  const g = Math.round(g2 * p + g1 * (1 - p));
+  const b = Math.round(b2 * p + b1 * (1 - p));
+  const a = Math.round(a2 * p + a1 * (1 - p));
+
+  return ((r << 24) | (g << 16) | (b << 8) | a) >>> 0;
+}
+
+/**
+ * Given an RGBA encoded number, returns back the RGBA number with it's alpha
+ * component multiplied by the passed `alpha` parameter.
+ *
+ * @internalRemarks
+ * This method does NOT premultiply the alpha into the color channels. If that
+ * is required (for internal use only) use {@link mergeColorAlphaPremultiplied}
+ * instead.
+ *
+ * @param rgba RGBA encoded number
+ * @param alpha Normalized alpha value (Range: 0.0 - 1.0)
+ * @returns
+ */
+export function mergeColorAlpha(rgba: number, alpha: number): number {
+  const r = rgba >>> 24;
+  const g = (rgba >>> 16) & 0xff;
+  const b = (rgba >>> 8) & 0xff;
+  const a = Math.trunc((rgba & 0xff) * alpha);
+
+  return ((r << 24) | (g << 16) | (b << 8) | a) >>> 0;
+}
+
+let premultiplyRGB = true;
+
+/**
+ * RGB components should not be premultiplied when using Canvas renderer
+ * @param mode  Renderer mode
+ */
+export function setPremultiplyMode(mode: 'webgl' | 'canvas'): void {
+  premultiplyRGB = mode === 'webgl';
+}
+
+/**
+ * Given an RGBA encoded number, returns back the RGBA number with it's alpha
+ * component multiplied by the passed `alpha` parameter.
+ *
+ * For the webGl renderer, each color channel is premultiplied by the final alpha value.
+ *
+ * @remarks
+ * If `flipEndianess` is set to true, the function will returned an ABGR encoded number
+ * which is useful when the color value needs to be passed into a shader attribute.
+ *
+ * NOTE: Depending on the mode set by {@link setPremultiplyMode}, this method returns
+ * a PREMULTIPLIED alpha color which is generally only useful in the context of the
+ * internal rendering process. Use {@link mergeColorAlpha} if you need to blend an alpha
+ * value into a color in the context of the Renderer's main API.
+ *
+ * @internalRemarks
+ * Do not expose this method in the main API because Renderer users should instead use
+ * {@link mergeColorAlpha} to manipulate the alpha value of a color.
+ *
+ * @internal
+ * @param rgba RGBA encoded number
+ * @param alpha Normalized alpha value (Range: 0.0 - 1.0)
+ * @param flipEndianess Flip the endianess. RGBA becomes encoded as ABGR (for inserting colors into shader attributes)
+ * @returns
+ */
+export function mergeColorAlphaPremultiplied(
+  rgba: number,
+  alpha: number,
+  flipEndianess = false,
+): number {
+  const newAlpha = ((rgba & 0xff) / 255) * alpha;
+  const rgbAlpha = premultiplyRGB ? newAlpha : 1;
+  const r = Math.trunc((rgba >>> 24) * rgbAlpha);
+  const g = Math.trunc(((rgba >>> 16) & 0xff) * rgbAlpha);
+  const b = Math.trunc(((rgba >>> 8) & 0xff) * rgbAlpha);
+  const a = Math.trunc(newAlpha * 255);
+
+  if (flipEndianess) {
+    return ((a << 24) | (b << 16) | (g << 8) | r) >>> 0;
+  }
+
+  return ((r << 24) | (g << 16) | (b << 8) | a) >>> 0;
+}
+
+/**
+ * Returns true if the given object has the given "own" property.
+ *
+ * @param obj
+ * @param prop
+ * @returns
+ */
+export function hasOwn(obj: object, prop: string | number | symbol): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, prop);
+}
+
+/**
+ * Converts degrees to radians
+ *
+ * @param degrees
+ * @returns
+ */
+export function deg2Rad(degrees: number): number {
+  return (degrees * Math.PI) / 180;
+}
+
+/**
+ * Returns image aspect ratio
+ *
+ * @param width
+ * @param height
+ * @returns
+ */
+export function getImageAspectRatio(width: number, height: number): number {
+  return width / height;
+}
+
+/**
+ * Checks import.meta if env is production
+ *
+ * @returns
+ */
+export function isProductionEnvironment(): boolean {
+  return import.meta.env && import.meta.env.PROD;
+}
+
+/**
+ * Returns a new unique ID
+ */
+let nextId = 1;
+export function getNewId(): number {
+  return nextId++;
+}

package/dist/exports/core-api.d.ts

@@ -1,74 +0,0 @@
-/**
- * Lightning 3 Renderer Core API
- *
- * @remarks
- * ```
- * import * from '@lightning/renderer/core';
- * ```
- *
- * The Core API is used by developers to extend the capabilities of the Renderer
- * by writing custom Shaders, Dynamic Shader Effects, Textures, Text Renderers,
- * etc.
- *
- * Custom capabilities as well as fonts can be loaded via Core Extensions.
- *
- * A core extension module is structured like so:
- * ```ts
- * import {
- *   CoreExtension,
- *   WebTrFontFace,
- *   SdfTrFontFace,
- *   type Stage
- * } from '@lightning/renderer/core';
- *
- * export default class MyCoreExtension extends CoreExtension {
- *   async run(stage: Stage) {
- *     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 imported and registered in the application's entry point
- * using the `@lightningjs/vite-plugin-import-chunk-url` plugin:
- * ```ts
- * import coreExtensionModuleUrl from './MyCoreExtension.js?importChunkUrl';
- *
- * // Set up driver, etc.
- *
- * // Initialize the Renderer
- * const renderer = new RendererMain(
- *   {
- *     // Other Renderer Config...
- *     coreExtensionModule: coreExtensionModuleUrl,
- *   },
- *   'app',
- *   driver,
- * );
- * ```
- *
- * @module
- */
-export * from '../src/core/renderers/webgl/WebGlCoreShader.js';
-export * from '../src/core/renderers/webgl/shaders/effects/ShaderEffect.js';
-export * from '../src/core/textures/Texture.js';
-export * from '../src/core/text-rendering/renderers/TextRenderer.js';
-export * from '../src/core/text-rendering/renderers/CanvasTextRenderer.js';
-export * from '../src/core/text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.js';
-export * from '../src/core/text-rendering/font-face-types/TrFontFace.js';
-export * from '../src/core/text-rendering/font-face-types/WebTrFontFace.js';
-export * from '../src/core/text-rendering/font-face-types/SdfTrFontFace/SdfTrFontFace.js';
-export * from '../src/core/CoreExtension.js';
-export type * from '../src/core/Stage.js';

package/dist/exports/core-api.js

@@ -1,96 +0,0 @@
-/*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2023 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.
- */
-/**
- * Lightning 3 Renderer Core API
- *
- * @remarks
- * ```
- * import * from '@lightning/renderer/core';
- * ```
- *
- * The Core API is used by developers to extend the capabilities of the Renderer
- * by writing custom Shaders, Dynamic Shader Effects, Textures, Text Renderers,
- * etc.
- *
- * Custom capabilities as well as fonts can be loaded via Core Extensions.
- *
- * A core extension module is structured like so:
- * ```ts
- * import {
- *   CoreExtension,
- *   WebTrFontFace,
- *   SdfTrFontFace,
- *   type Stage
- * } from '@lightning/renderer/core';
- *
- * export default class MyCoreExtension extends CoreExtension {
- *   async run(stage: Stage) {
- *     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 imported and registered in the application's entry point
- * using the `@lightningjs/vite-plugin-import-chunk-url` plugin:
- * ```ts
- * import coreExtensionModuleUrl from './MyCoreExtension.js?importChunkUrl';
- *
- * // Set up driver, etc.
- *
- * // Initialize the Renderer
- * const renderer = new RendererMain(
- *   {
- *     // Other Renderer Config...
- *     coreExtensionModule: coreExtensionModuleUrl,
- *   },
- *   'app',
- *   driver,
- * );
- * ```
- *
- * @module
- */
-// Shaders
-export * from '../src/core/renderers/webgl/WebGlCoreShader.js';
-export * from '../src/core/renderers/webgl/shaders/effects/ShaderEffect.js';
-// Textures
-export * from '../src/core/textures/Texture.js';
-// Text Rendering & Fonts
-export * from '../src/core/text-rendering/renderers/TextRenderer.js';
-export * from '../src/core/text-rendering/renderers/CanvasTextRenderer.js';
-export * from '../src/core/text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.js';
-export * from '../src/core/text-rendering/font-face-types/TrFontFace.js';
-export * from '../src/core/text-rendering/font-face-types/WebTrFontFace.js';
-export * from '../src/core/text-rendering/font-face-types/SdfTrFontFace/SdfTrFontFace.js';
-// Core Extensions
-export * from '../src/core/CoreExtension.js';
-//# sourceMappingURL=core-api.js.map

package/dist/exports/core-api.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"core-api.js","sourceRoot":"","sources":["../../exports/core-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,UAAU;AACV,cAAc,gDAAgD,CAAC;AAC/D,cAAc,6DAA6D,CAAC;AAE5E,WAAW;AACX,cAAc,iCAAiC,CAAC;AAEhD,yBAAyB;AACzB,cAAc,sDAAsD,CAAC;AACrE,cAAc,4DAA4D,CAAC;AAC3E,cAAc,yEAAyE,CAAC;AACxF,cAAc,0DAA0D,CAAC;AACzE,cAAc,6DAA6D,CAAC;AAC5E,cAAc,2EAA2E,CAAC;AAE1F,kBAAkB;AAClB,cAAc,8BAA8B,CAAC"}