@lightningjs/renderer 0.9.4 → 1.0.0-rc.1

package/dist/src/core/CoreNode.d.ts

@@ -1,7 +1,5 @@
-import type { ShaderMap } from './CoreShaderManager.js';
-import type { ExtractProps, TextureMap, TextureOptions } from './CoreTextureManager.js';
+import type { TextureOptions } from './CoreTextureManager.js';
 import type { CoreRenderer } from './renderers/CoreRenderer.js';
-import type { CoreShader } from './renderers/CoreShader.js';
 import type { Stage } from './Stage.js';
 import type { Texture } from './textures/Texture.js';
 import type { Dimensions } from '../common/CommonTypes.js';
@@ -9,49 +7,15 @@ import { EventEmitter } from '../common/EventEmitter.js';
 import { type Bound, type RectWithValid } from './lib/utils.js';
 import { Matrix3d } from './lib/Matrix3d.js';
 import { RenderCoords } from './lib/RenderCoords.js';
+import type { AnimationSettings } from './animations/CoreAnimation.js';
+import type { IAnimationController } from '../common/IAnimationController.js';
+import type { BaseShaderController } from '../main-api/ShaderController.js';
 export declare enum CoreNodeRenderState {
     Init = 0,
     OutOfBounds = 2,
     InBounds = 4,
     InViewport = 8
 }
-export interface CoreNodeProps {
-    id: number;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    alpha: number;
-    autosize: boolean;
-    clipping: boolean;
-    color: number;
-    colorTop: number;
-    colorBottom: number;
-    colorLeft: number;
-    colorRight: number;
-    colorTl: number;
-    colorTr: number;
-    colorBl: number;
-    colorBr: number;
-    parent: CoreNode | null;
-    zIndex: number;
-    texture: Texture | null;
-    textureOptions: TextureOptions | null;
-    shader: CoreShader | null;
-    shaderProps: Record<string, unknown> | null;
-    zIndexLocked: number;
-    scaleX: number;
-    scaleY: number;
-    mount: number;
-    mountX: number;
-    mountY: number;
-    pivot: number;
-    pivotX: number;
-    pivotY: number;
-    rotation: number;
-    rtt: boolean;
-}
-type ICoreNode = Omit<CoreNodeProps, 'texture' | 'textureOptions' | 'shader' | 'shaderProps'>;
 export declare enum UpdateType {
     /**
      * Child updates
@@ -159,10 +123,454 @@ export declare enum UpdateType {
      */
     All = 8191
 }
-export declare class CoreNode extends EventEmitter implements ICoreNode {
-    protected stage: Stage;
+/**
+ * A custom data map which can be stored on an CoreNode
+ *
+ * @remarks
+ * This is a map of key-value pairs that can be stored on an INode. It is used
+ * to store custom data that can be used by the application.
+ * The data stored can only be of type string, number or boolean.
+ */
+export type CustomDataMap = {
+    [key: string]: string | number | boolean | undefined;
+};
+/**
+ * Writable properties of a Node.
+ */
+export interface CoreNodeProps {
+    /**
+     * 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;
+    /**
+     * Autosize mode
+     *
+     * @remarks
+     * When enabled, when a texture is loaded into the Node, the Node will
+     * automatically resize to the dimensions of the texture.
+     *
+     * Text Nodes are always autosized based on their text content regardless
+     * of this mode setting.
+     *
+     * @default `false`
+     */
+    autosize: boolean;
+    /**
+     * Clipping Mode
+     *
+     * @remarks
+     * Enable Clipping Mode when you want to prevent the drawing of a Node and
+     * its descendants from overflowing outside of the Node's x/y/width/height
+     * bounds.
+     *
+     * For WebGL, clipping is implemented using the high-performance WebGL
+     * operation scissor. As a consequence, clipping does not work for
+     * non-rectangular areas. So, if the element is rotated
+     * (by itself or by any of its ancestors), clipping will not work as intended.
+     *
+     * TODO: Add support for non-rectangular clipping either automatically or
+     * via Render-To-Texture.
+     *
+     * @default `false`
+     */
+    clipping: boolean;
+    /**
+     * 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: CoreNode | 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.createTexture}.
+     *
+     * 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: Texture | null;
+    /**
+     * Options to associate with the Node's Texture
+     */
+    textureOptions: TextureOptions;
+    /**
+     * 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.createShader}.
+     *
+     * 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: BaseShaderController;
+    /**
+     * 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 | null;
+    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 Pivot Point (defined by the {@link pivot}
+     * props).
+     *
+     * Behind the scenes, setting this property sets both the {@link scaleX} and
+     * {@link scaleY} props to the same value.
+     *
+     * NOTE: When the scaleX and scaleY props are explicitly set to different values,
+     * this property returns `null`. Setting `null` on this property will have no
+     * effect.
+     *
+     * @default 1.0
+     */
+    scale: number | null;
+    /**
+     * Scale to render the Node at (X-Axis)
+     *
+     * @remarks
+     * The scaleX value multiplies the provided {@link width} of the Node around
+     * the Node's Pivot Point (defined by the {@link pivot} props).
+     *
+     * @default 1.0
+     */
+    scaleX: number;
+    /**
+     * Scale to render the Node at (Y-Axis)
+     *
+     * @remarks
+     * The scaleY value multiplies the provided {@link height} of the Node around
+     * the Node's Pivot Point (defined by the {@link pivot} props).
+     *
+     * @default 1.0
+     */
+    scaleY: 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;
+    /**
+     * Whether the Node is rendered to a texture
+     *
+     * @remarks
+     * TBD
+     *
+     * @default false
+     */
+    rtt: boolean;
+    /**
+     * Node data element for custom data storage (optional)
+     *
+     * @remarks
+     * This property is used to store custom data on the Node as a key/value data store.
+     * Data values are limited to string, numbers, booleans. Strings will be truncated
+     * to a 2048 character limit for performance reasons.
+     *
+     * This is not a data storage mechanism for large amounts of data please use a
+     * dedicated data storage mechanism for that.
+     *
+     * The custom data will be reflected in the inspector as part of `data-*` attributes
+     *
+     * @default `undefined`
+     */
+    data?: CustomDataMap;
+}
+/**
+ * Grab all the number properties of type T
+ */
+type NumberProps<T> = {
+    [Key in keyof T as NonNullable<T[Key]> extends number ? Key : never]: number;
+};
+/**
+ * Properties of a Node used by the animate() function
+ */
+export interface CoreNodeAnimateProps extends NumberProps<CoreNodeProps> {
+    /**
+     * Shader properties to animate
+     */
+    shaderProps: Record<string, number>;
+}
+/**
+ * A visual Node in the Renderer scene graph.
+ *
+ * @remarks
+ * CoreNode is an internally used class that represents a Renderer Node in the
+ * scene graph. See INode.ts for the public APIs exposed to Renderer users
+ * that include generic types for Shaders.
+ */
+export declare class CoreNode extends EventEmitter {
+    readonly stage: Stage;
     readonly children: CoreNode[];
-    protected props: Required<CoreNodeProps>;
+    protected _id: number;
+    readonly props: CoreNodeProps;
     updateType: UpdateType;
     globalTransform?: Matrix3d;
     scaleRotateTransform?: Matrix3d;
@@ -183,13 +591,12 @@ export declare class CoreNode extends EventEmitter implements ICoreNode {
     hasRTTupdates: boolean;
     parentHasRenderTexture: boolean;
     constructor(stage: Stage, props: CoreNodeProps);
-    loadTexture<Type extends keyof TextureMap>(textureType: Type, props: ExtractProps<TextureMap[Type]>, options?: TextureOptions | null): void;
+    loadTexture(): void;
     unloadTexture(): void;
     autosizeNode(dimensions: Dimensions): void;
     private onTextureLoaded;
     private onTextureFailed;
     private onTextureFreed;
-    loadShader<Type extends keyof ShaderMap>(shaderType: Type, props: ExtractProps<ShaderMap[Type]>): void;
     /**
      * Change types types is used to determine the scope of the changes being applied
      *
@@ -210,7 +617,6 @@ export declare class CoreNode extends EventEmitter implements ICoreNode {
     checkRenderProps(): boolean;
     checkRenderBounds(parentClippingRect: RectWithValid): CoreNodeRenderState;
     updateRenderState(parentClippingRect: RectWithValid): void;
-    setRenderState(state: CoreNodeRenderState): void;
     /**
      * This function updates the `isRenderable` property based on certain conditions.
      *
@@ -298,6 +704,10 @@ export declare class CoreNode extends EventEmitter implements ICoreNode {
     set parent(newParent: CoreNode | null);
     get rtt(): boolean;
     set rtt(value: boolean);
+    get shader(): BaseShaderController;
+    set shader(value: BaseShaderController);
+    get src(): string | null;
+    set src(imageUrl: string | null);
     /**
      * Returns the framebuffer dimensions of the node.
      * If the node has a render texture, the dimensions are the same as the node's dimensions.
@@ -310,6 +720,11 @@ export declare class CoreNode extends EventEmitter implements ICoreNode {
      */
     get parentRenderTexture(): CoreNode | null;
     get texture(): Texture | null;
+    set texture(value: Texture | null);
+    set textureOptions(value: TextureOptions);
+    get textureOptions(): TextureOptions;
     setRTTUpdates(type: number): void;
+    animate(props: Partial<CoreNodeAnimateProps>, settings: Partial<AnimationSettings>): IAnimationController;
+    flush(): void;
 }
 export {};