@lightningjs/renderer 0.0.1

package/dist/src/main-api/INode.d.ts

@@ -0,0 +1,390 @@
+import type { IEventEmitter } from '@lightningjs/threadx';
+import type { IAnimationController } from '../common/IAnimationController.js';
+import type { ShaderDesc, TextureDesc } from './RendererMain.js';
+import type { TextRendererMap, TrProps } from '../core/text-rendering/renderers/TextRenderer.js';
+import type { IAnimationSettings } from '../core/animations/CoreAnimation.js';
+/**
+ * Writable properties of a Node.
+ */
+export interface INodeWritableProps {
+    /**
+     * The x coordinate of the Node's Mount Point.
+     *
+     * @remarks
+     * See {@link mountX} and {@link mountY} for more information about setting
+     * the Mount Point.
+     *
+     * @default `0`
+     */
+    x: number;
+    /**
+     * The y coordinate of the Node's Mount Point.
+     *
+     * @remarks
+     * See {@link mountX} and {@link mountY} for more information about setting
+     * the Mount Point.
+     *
+     * @default `0`
+     */
+    y: number;
+    /**
+     * The width of the Node.
+     *
+     * @default `0`
+     */
+    width: number;
+    /**
+     * The height of the Node.
+     *
+     * @default `0`
+     */
+    height: number;
+    /**
+     * The alpha opacity of the Node.
+     *
+     * @remarks
+     * The alpha value is a number between 0 and 1, where 0 is fully transparent
+     * and 1 is fully opaque.
+     *
+     * @default `1`
+     */
+    alpha: number;
+    /**
+     * The color of the Node.
+     *
+     * @remarks
+     * The color value is a number in the format 0xRRGGBBAA, where RR is the red
+     * component, GG is the green component, BB is the blue component, and AA is
+     * the alpha component.
+     *
+     * Gradient colors may be set by setting the different color sub-properties:
+     * {@link colorTop}, {@link colorBottom}, {@link colorLeft}, {@link colorRight},
+     * {@link colorTl}, {@link colorTr}, {@link colorBr}, {@link colorBl} accordingly.
+     *
+     * @default `0xffffffff` (opaque white)
+     */
+    color: number;
+    /**
+     * The color of the top edge of the Node for gradient rendering.
+     *
+     * @remarks
+     * See {@link color} for more information about color values and gradient
+     * rendering.
+     */
+    colorTop: number;
+    /**
+     * The color of the bottom edge of the Node for gradient rendering.
+     *
+     * @remarks
+     * See {@link color} for more information about color values and gradient
+     * rendering.
+     */
+    colorBottom: number;
+    /**
+     * The color of the left edge of the Node for gradient rendering.
+     *
+     * @remarks
+     * See {@link color} for more information about color values and gradient
+     * rendering.
+     */
+    colorLeft: number;
+    /**
+     * The color of the right edge of the Node for gradient rendering.
+     *
+     * @remarks
+     * See {@link color} for more information about color values and gradient
+     * rendering.
+     */
+    colorRight: number;
+    /**
+     * The color of the top-left corner of the Node for gradient rendering.
+     *
+     * @remarks
+     * See {@link color} for more information about color values and gradient
+     * rendering.
+     */
+    colorTl: number;
+    /**
+     * The color of the top-right corner of the Node for gradient rendering.
+     *
+     * @remarks
+     * See {@link color} for more information about color values and gradient
+     * rendering.
+     */
+    colorTr: number;
+    /**
+     * The color of the bottom-right corner of the Node for gradient rendering.
+     *
+     * @remarks
+     * See {@link color} for more information about color values and gradient
+     * rendering.
+     */
+    colorBr: number;
+    /**
+     * The color of the bottom-left corner of the Node for gradient rendering.
+     *
+     * @remarks
+     * See {@link color} for more information about color values and gradient
+     * rendering.
+     */
+    colorBl: number;
+    /**
+     * The Node's parent Node.
+     *
+     * @remarks
+     * The value `null` indicates that the Node has no parent. This may either be
+     * because the Node is the root Node of the scene graph, or because the Node
+     * has been removed from the scene graph.
+     *
+     * In order to make sure that a Node can be rendered on the screen, it must
+     * be added to the scene graph by setting it's parent property to a Node that
+     * is already in the scene graph such as the root Node.
+     *
+     * @default `null`
+     */
+    parent: INode | null;
+    /**
+     * The Node's z-index.
+     *
+     * @remarks
+     * TBD
+     */
+    zIndex: number;
+    /**
+     * The Node's Texture.
+     *
+     * @remarks
+     * The `texture` defines a rasterized image that is contained within the
+     * {@link width} and {@link height} dimensions of the Node. If null, the
+     * Node will use an opaque white {@link ColorTexture} when being drawn, which
+     * essentially enables colors (including gradients) to be drawn.
+     *
+     * If set, by default, the texture will be drawn, as is, stretched to the
+     * dimensions of the Node. This behavior can be modified by setting the TBD
+     * and TBD properties.
+     *
+     * To create a Texture in order to set it on this property, call
+     * {@link RendererMain.makeTexture}.
+     *
+     * If the {@link src} is set on a Node, the Node will use the
+     * {@link ImageTexture} by default and the Node will simply load the image at
+     * the specified URL.
+     *
+     * Note: If this is a Text Node, the Texture will be managed by the Node's
+     * {@link TextRenderer} and should not be set explicitly.
+     */
+    texture: TextureDesc | null;
+    /**
+     * The Node's shader
+     *
+     * @remarks
+     * The `shader` defines a {@link Shader} used to draw the Node. By default,
+     * the Default Shader is used which simply draws the defined {@link texture}
+     * or {@link color}(s) within the Node without any special effects.
+     *
+     * To create a Shader in order to set it on this property, call
+     * {@link RendererMain.makeShader}.
+     *
+     * Note: If this is a Text Node, the Shader will be managed by the Node's
+     * {@link TextRenderer} and should not be set explicitly.
+     */
+    shader: ShaderDesc | null;
+    /**
+     * Image URL
+     *
+     * @remarks
+     * When set, the Node's {@link texture} is automatically set to an
+     * {@link ImageTexture} using the source image URL provided (with all other
+     * settings being defaults)
+     */
+    src: string;
+    zIndexLocked: number;
+    /**
+     * Scale to render the Node at
+     *
+     * @remarks
+     * The scale value multiplies the provided {@link width} and {@link height}
+     * of the Node around the Node's Mount Point (defined by the {@link mount}
+     * props).
+     *
+     * @default 1.0
+     */
+    scale: number;
+    /**
+     * Combined position of the Node's Mount Point
+     *
+     * @remarks
+     * The value can be any number between `0.0` and `1.0`:
+     * - `0.0` defines the Mount Point at the top-left corner of the Node.
+     * - `0.5` defines it at the center of the Node.
+     * - `1.0` defines it at the bottom-right corner of the node.
+     *
+     * Use the {@link mountX} and {@link mountY} props seperately for more control
+     * of the Mount Point.
+     *
+     * When assigned, the same value is also passed to both the {@link mountX} and
+     * {@link mountY} props.
+     *
+     * @default 0 (top-left)
+     */
+    mount: number;
+    /**
+     * X position of the Node's Mount Point
+     *
+     * @remarks
+     * The value can be any number between `0.0` and `1.0`:
+     * - `0.0` defines the Mount Point's X position as the left-most edge of the
+     *   Node
+     * - `0.5` defines it as the horizontal center of the Node
+     * - `1.0` defines it as the right-most edge of the Node.
+     *
+     * The combination of {@link mountX} and {@link mountY} define the Mount Point
+     *
+     * @default 0 (left-most edge)
+     */
+    mountX: number;
+    /**
+     * Y position of the Node's Mount Point
+     *
+     * @remarks
+     * The value can be any number between `0.0` and `1.0`:
+     * - `0.0` defines the Mount Point's Y position as the top-most edge of the
+     *   Node
+     * - `0.5` defines it as the vertical center of the Node
+     * - `1.0` defines it as the bottom-most edge of the Node.
+     *
+     * The combination of {@link mountX} and {@link mountY} define the Mount Point
+     *
+     * @default 0 (top-most edge)
+     */
+    mountY: number;
+    /**
+     * Combined position of the Node's Pivot Point
+     *
+     * @remarks
+     * The value can be any number between `0.0` and `1.0`:
+     * - `0.0` defines the Pivot Point at the top-left corner of the Node.
+     * - `0.5` defines it at the center of the Node.
+     * - `1.0` defines it at the bottom-right corner of the node.
+     *
+     * Use the {@link pivotX} and {@link pivotY} props seperately for more control
+     * of the Pivot Point.
+     *
+     * When assigned, the same value is also passed to both the {@link pivotX} and
+     * {@link pivotY} props.
+     *
+     * @default 0.5 (center)
+     */
+    pivot: number;
+    /**
+     * X position of the Node's Pivot Point
+     *
+     * @remarks
+     * The value can be any number between `0.0` and `1.0`:
+     * - `0.0` defines the Pivot Point's X position as the left-most edge of the
+     *   Node
+     * - `0.5` defines it as the horizontal center of the Node
+     * - `1.0` defines it as the right-most edge of the Node.
+     *
+     * The combination of {@link pivotX} and {@link pivotY} define the Pivot Point
+     *
+     * @default 0.5 (centered on x-axis)
+     */
+    pivotX: number;
+    /**
+     * Y position of the Node's Pivot Point
+     *
+     * @remarks
+     * The value can be any number between `0.0` and `1.0`:
+     * - `0.0` defines the Pivot Point's Y position as the top-most edge of the
+     *   Node
+     * - `0.5` defines it as the vertical center of the Node
+     * - `1.0` defines it as the bottom-most edge of the Node.
+     *
+     * The combination of {@link pivotX} and {@link pivotY} define the Pivot Point
+     *
+     * @default 0.5 (centered on y-axis)
+     */
+    pivotY: number;
+    /**
+     * Rotation of the Node (in Radians)
+     *
+     * @remarks
+     * Sets the amount to rotate the Node by around it's Pivot Point (defined by
+     * the {@link pivot} props). Positive values rotate the Node clockwise, while
+     * negative values rotate it counter-clockwise.
+     *
+     * Example values:
+     * - `-Math.PI / 2`: 90 degree rotation counter-clockwise
+     * - `0`: No rotation
+     * - `Math.PI / 2`: 90 degree rotation clockwise
+     * - `Math.PI`: 180 degree rotation clockwise
+     * - `3 * Math.PI / 2`: 270 degree rotation clockwise
+     * - `2 * Math.PI`: 360 rotation clockwise
+     */
+    rotation: number;
+    worldX?: number;
+    worldY?: number;
+}
+export type INodeAnimatableProps = {
+    [Key in keyof INodeWritableProps as INodeWritableProps[Key] extends number ? Key : never]: number;
+};
+export interface INodeEvents {
+    [s: string]: (target: INode, data: any) => void;
+}
+/**
+ * Main API interface representing a Node in the Renderer scene graph.
+ *
+ * @remarks
+ * A Node is a basic building block of the Renderer scene graph. It can be a
+ * container for other Nodes, or it can be a leaf Node that renders a solid
+ * color, gradient, image, or specific texture, using a specific shader.
+ *
+ * For text rendering, see {@link ITextNode}.
+ *
+ * Nodes are represented by an interface since they may be implemented in
+ * different ways depending on the Core Driver. For example, the MainRenderDriver
+ * implements it with it's `MainOnlyNode` while the ThreadXRenderDriver implements
+ * it with it's `ThreadXMainNode`.
+ */
+export interface INode extends INodeWritableProps, IEventEmitter<INodeEvents> {
+    id: number;
+    readonly children: INode[];
+    animate(props: Partial<INodeAnimatableProps>, settings: Partial<IAnimationSettings>): IAnimationController;
+    destroy(): void;
+    flush(): void;
+}
+export interface ITextNodeWritableProps extends INodeWritableProps, TrProps {
+    /**
+     * Force Text Node to use a specific Text Renderer
+     *
+     * @remarks
+     * By default, Text Nodes resolve the Text Renderer to use based on the font
+     * that is matched using the font family and other font selection properties.
+     *
+     * If two fonts supported by two separate Text Renderers are matched setting
+     * this override forces the Text Node to resolve to the Text Renderer defined
+     * here.
+     *
+     * @default null
+     */
+    textRendererOverride: keyof TextRendererMap | null;
+}
+/**
+ * Main API interface representing a Node in the Renderer scene graph that renders text.
+ *
+ * @remarks
+ * A Text Node is the second graphical building block of the Renderer scene
+ * graph. It renders text using a specific text renderer that is automatically
+ * chosen based on the font requested and what type of fonts are installed
+ * into an app via a CoreExtension.
+ *
+ * The text renderer can be overridden by setting the `textRendererOverride`
+ *
+ * The `texture` and `shader` properties are managed by loaded text renderer and
+ * should not be set directly.
+ *
+ * For non-text rendering, see {@link INode}.
+ */
+export interface ITextNode extends INode, ITextNodeWritableProps {
+}

package/dist/src/main-api/INode.js

@@ -0,0 +1,20 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2023 Comcast
+ *
+ * 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.
+ */
+export {};
+//# sourceMappingURL=INode.js.map

package/dist/src/main-api/INode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"INode.js","sourceRoot":"","sources":["../../../src/main-api/INode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/src/main-api/IRenderDriver.d.ts

@@ -0,0 +1,20 @@
+import type { INode, INodeWritableProps, ITextNode, ITextNodeWritableProps } from './INode.js';
+import type { RendererMain, RendererMainSettings } from './RendererMain.js';
+/**
+ * This interface is to be implemented by Core Drivers
+ *
+ * @remarks
+ * Both the {@link MainRenderDriver} and the {@link ThreadXRenderDriver} exist
+ * that implement this interface to support both the single-threaded and
+ * multi-threaded Core modes.
+ */
+export interface IRenderDriver {
+    init(rendererMain: RendererMain, rendererSettings: Required<RendererMainSettings>, canvas: HTMLCanvasElement): Promise<void>;
+    createNode(props: INodeWritableProps): INode;
+    createTextNode(props: ITextNodeWritableProps): ITextNode;
+    destroyNode(node: INode): void;
+    getRootNode(): INode;
+    releaseTexture(textureDescId: number): void;
+    onCreateNode(node: INode): void;
+    onBeforeDestroyNode(node: INode): void;
+}

package/dist/src/main-api/IRenderDriver.js

@@ -0,0 +1,20 @@
+/*
+ * If not stated otherwise in this file or this component's LICENSE file the
+ * following copyright and licenses apply:
+ *
+ * Copyright 2023 Comcast
+ *
+ * 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.
+ */
+export {};
+//# sourceMappingURL=IRenderDriver.js.map

package/dist/src/main-api/IRenderDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRenderDriver.js","sourceRoot":"","sources":["../../../src/main-api/IRenderDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/src/main-api/RendererMain.d.ts

@@ -0,0 +1,232 @@
+import type { ShaderMap } from '../core/CoreShaderManager.js';
+import type { ExtractProps, TextureMap, TextureOptions } from '../core/CoreTextureManager.js';
+import type { INode, INodeWritableProps, ITextNode, ITextNodeWritableProps } from './INode.js';
+import type { IRenderDriver } from './IRenderDriver.js';
+/**
+ * A description of a Texture
+ *
+ * @remarks
+ * This structure should only be created by the RendererMain's `makeTexture`
+ * method. The structure is immutable and should not be modified once created.
+ */
+export interface TextureDesc<TxType extends keyof TextureMap = keyof TextureMap> {
+    readonly descType: 'texture';
+    readonly txType: TxType;
+    readonly props: ExtractProps<TextureMap[TxType]>;
+    readonly options?: Readonly<TextureOptions>;
+}
+export interface ShaderDesc<ShType extends keyof ShaderMap = keyof ShaderMap> {
+    readonly descType: 'shader';
+    readonly shType: ShType;
+    readonly props: ExtractProps<ShaderMap[ShType]>;
+}
+/**
+ * Configuration settings for {@link RendererMain}
+ */
+export interface RendererMainSettings {
+    /**
+     * Authored logical pixel width of the application
+     *
+     * @defaultValue `1920`
+     */
+    appWidth?: number;
+    /**
+     * Authored logical pixel height of the application
+     *
+     * @defaultValue `1080`
+     */
+    appHeight?: number;
+    /**
+     * Factor to convert app-authored logical coorindates to device logical coordinates
+     *
+     * @remarks
+     * This value allows auto-scaling to support larger/small resolutions than the
+     * app was authored for.
+     *
+     * If the app was authored for 1920x1080 and this value is 2, the app's canvas
+     * will be rendered at 3840x2160 logical pixels.
+     *
+     * Likewise, if the app was authored for 1920x1080 and this value is 0.66667,
+     * the app's canvas will be rendered at 1280x720 logical pixels.
+     *
+     * @defaultValue `1`
+     */
+    deviceLogicalPixelRatio?: number;
+    /**
+     * Factor to convert device logical coordinates to device physical coordinates
+     *
+     * @remarks
+     * This value allows auto-scaling to support devices with different pixel densities.
+     *
+     * This controls the number of physical pixels that are used to render each logical
+     * pixel. For example, if the device has a pixel density of 2, each logical pixel
+     * will be rendered using 2x2 physical pixels.
+     *
+     * By default, it will be set to `window.devicePixelRatio` which is the pixel
+     * density of the device the app is running on reported by the browser.
+     *
+     * @defaultValue `window.devicePixelRatio`
+     */
+    devicePhysicalPixelRatio?: number;
+    /**
+     * RGBA encoded number of the background to use
+     *
+     * @defaultValue `0x00000000`
+     */
+    clearColor?: number;
+    /**
+     * Path to a custom core module to use
+     */
+    coreExtensionModule?: string | null;
+}
+/**
+ * The Renderer Main API
+ *
+ * @remarks
+ * This is the primary class used to configure and operate the Renderer.
+ *
+ * It is used to create and destroy Nodes, as well as Texture and Shader
+ * references.
+ *
+ * Example:
+ * ```ts
+ * import { RendererMain, MainRenderDriver } from '@lightningjs/renderer';
+ *
+ * // Initialize the Renderer
+ * const renderer = new RendererMain(
+ *   {
+ *     appWidth: 1920,
+ *     appHeight: 1080
+ *   },
+ *   'app',
+ *   new MainRenderDriver(),
+ * );
+ * ```
+ */
+export declare class RendererMain {
+    readonly root: INode | null;
+    readonly driver: IRenderDriver;
+    private canvas;
+    private settings;
+    private nodes;
+    private nextTextureId;
+    private textureRegistry;
+    /**
+     * Constructs a new Renderer instance
+     *
+     * @param settings Renderer settings
+     * @param target Element ID or HTMLElement to insert the canvas into
+     * @param driver Core Driver to use
+     */
+    constructor(settings: RendererMainSettings, target: string | HTMLElement, driver: IRenderDriver);
+    /**
+     * Initialize the renderer
+     *
+     * @remarks
+     * This method must be called and resolved asyncronously before any other
+     * methods are called.
+     */
+    init(): Promise<void>;
+    /**
+     * Create a new scene graph node
+     *
+     * @remarks
+     * A node is the main graphical building block of the Renderer scene graph. It
+     * can be a container for other nodes, or it can be a leaf node that renders a
+     * solid color, gradient, image, or specific texture, using a specific shader.
+     *
+     * To create a text node, see {@link createTextNode}.
+     *
+     * See {@link INode} for more details.
+     *
+     * @param props
+     * @returns
+     */
+    createNode(props: Partial<INodeWritableProps>): INode;
+    /**
+     * Create a new scene graph text node
+     *
+     * @remarks
+     * A text node is the second graphical building block of the Renderer scene
+     * graph. It renders text using a specific text renderer that is automatically
+     * chosen based on the font requested and what type of fonts are installed
+     * into an app via a CoreExtension.
+     *
+     * See {@link ITextNode} for more details.
+     *
+     * @param props
+     * @returns
+     */
+    createTextNode(props: Partial<ITextNodeWritableProps>): ITextNode;
+    /**
+     * Resolves the default property values for a Node
+     *
+     * @remarks
+     * This method is used internally by the RendererMain to resolve the default
+     * property values for a Node. It is exposed publicly so that it can be used
+     * by Core Driver implementations.
+     *
+     * @param props
+     * @returns
+     */
+    resolveNodeDefaults(props: Partial<INodeWritableProps>): INodeWritableProps;
+    /**
+     * Destroy a node
+     *
+     * @remarks
+     * This method destroys a node but does not destroy its children.
+     *
+     * @param node
+     * @returns
+     */
+    destroyNode(node: INode): void;
+    /**
+     * Create a new texture reference
+     *
+     * @remarks
+     * This method creates a new reference to a texture. The texture is not
+     * loaded until it is used on a node.
+     *
+     * It can be assigned to a node's `texture` property, or it can be used
+     * when creating a SubTexture.
+     *
+     * @param textureType
+     * @param props
+     * @param options
+     * @returns
+     */
+    makeTexture<Type extends keyof TextureMap>(textureType: Type, props: TextureDesc<Type>['props'], options?: TextureOptions): TextureDesc<Type>;
+    /**
+     * Create a new shader reference
+     *
+     * @remarks
+     * This method creates a new reference to a shader. The shader is not
+     * loaded until it is used on a Node.
+     *
+     * It can be assigned to a Node's `shader` property.
+     *
+     * @param shaderType
+     * @param props
+     * @returns
+     */
+    makeShader<ShType extends keyof ShaderMap>(shaderType: ShType, props?: ShaderDesc<ShType>['props']): ShaderDesc<ShType>;
+    /**
+     * Get a Node by its ID
+     *
+     * @param id
+     * @returns
+     */
+    getNodeById(id: number): INode | null;
+    toggleFreeze(): void;
+    advanceFrame(): void;
+    /**
+     * Re-render the current frame without advancing any running animations.
+     *
+     * @remarks
+     * Any state changes will be reflected in the re-rendered frame. Useful for
+     * debugging.
+     *
+     * May not do anything if the render loop is running on a separate worker.
+     */
+    rerender(): void;
+}