@types/three 0.184.0 → 0.185.0

three/src/nodes/display/BlendModes.d.ts

@@ -1,15 +1,76 @@
+import { Color } from "../../math/Color.js";
+import { Vector3 } from "../../math/Vector3.js";
+import { Vector4 } from "../../math/Vector4.js";
 import Node from "../core/Node.js";
 
-export const blendBurn: (base: Node, blend: Node) => Node<"vec3">;
+type ColorParameter = Node<"float"> | number | Node<"vec3"> | Vector3 | Node<"color"> | Color | Node<"vec4"> | Vector4;
 
-export const blendDodge: (base: Node, blend: Node) => Node<"vec3">;
+/**
+ * Represents a "Color Burn" blend mode.
+ *
+ * It's designed to darken the base layer's colors based on the color of the blend layer.
+ * It significantly increases the contrast of the base layer, making the colors more vibrant and saturated.
+ * The darker the color in the blend layer, the stronger the darkening and contrast effect on the base layer.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color. A white (#ffffff) blend color does not alter the base color.
+ * @return {Node<vec3>} The result.
+ */
+export const blendBurn: (base: ColorParameter, blend: ColorParameter) => Node<"vec3">;
+/**
+ * Represents a "Color Dodge" blend mode.
+ *
+ * It's designed to lighten the base layer's colors based on the color of the blend layer.
+ * It significantly increases the brightness of the base layer, making the colors lighter and more vibrant.
+ * The brighter the color in the blend layer, the stronger the lightening and contrast effect on the base layer.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color. A black (#000000) blend color does not alter the base color.
+ * @return {Node<vec3>} The result.
+ */
+export const blendDodge: (base: ColorParameter, blend: ColorParameter) => Node<"vec3">;
+/**
+ * Represents a "Screen" blend mode.
+ *
+ * Similar to `blendDodge()`, this mode also lightens the base layer's colors based on the color of the blend layer.
+ * The "Screen" blend mode is better for general brightening whereas the "Dodge" results in more subtle and nuanced
+ * effects.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color. A black (#000000) blend color does not alter the base color.
+ * @return {Node<vec3>} The result.
+ */
+export const blendScreen: (base: ColorParameter, blend: ColorParameter) => Node<"vec3">;
+/**
+ * Represents a "Overlay" blend mode.
+ *
+ * It's designed to increase the contrast of the base layer based on the color of the blend layer.
+ * It amplifies the existing colors and contrast in the base layer, making lighter areas lighter and darker areas darker.
+ * The color of the blend layer significantly influences the resulting contrast and color shift in the base layer.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color
+ * @return {Node<vec3>} The result.
+ */
+export const blendOverlay: (base: ColorParameter, blend: ColorParameter) => Node<"vec3">;
+/**
+ * This function blends two color based on their alpha values by replicating the behavior of `THREE.NormalBlending`.
+ * It assumes both input colors have non-premultiplied alpha.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec4>} base - The base color.
+ * @param {Node<vec4>} blend - The blend color
+ * @return {Node<vec4>} The result.
+ */
+export const blendColor: (base: ColorParameter, blend: ColorParameter) => Node<"vec4">;
 
-export const blendScreen: (base: Node, blend: Node) => Node<"vec3">;
-
-export const blendOverlay: (base: Node, blend: Node) => Node<"vec3">;
-
-export const blendColor: (base: Node, blend: Node) => Node<"vec4">;
-
-export const premultiplyAlpha: (color: Node) => Node<"vec4">;
-
-export const unpremultiplyAlpha: (color: Node) => Node<"vec4">;
+export {};

three/src/nodes/display/FrontFacingNode.d.ts

@@ -1,12 +1,71 @@
+import { Vector3 } from "../../math/Vector3.js";
 import Node from "../core/Node.js";
 
+/**
+ * This node can be used to evaluate whether a primitive is front or back facing.
+ *
+ * @augments Node
+ */
 declare class FrontFacingNode extends Node<"bool"> {
-    isFrontFacingNode: true;
+    /**
+     * Constructs a new front facing node.
+     */
     constructor();
+    /**
+     * This flag can be used for type testing.
+     *
+     * @type {boolean}
+     * @readonly
+     * @default true
+     */
+    readonly isFrontFacingNode: boolean;
 }
 
 export default FrontFacingNode;
 
+/**
+ * TSL object that represents whether a primitive is front or back facing
+ *
+ * @tsl
+ * @type {FrontFacingNode<bool>}
+ */
 export const frontFacing: FrontFacingNode;
-export const faceDirection: Node;
-export const directionToFaceDirection: (direction: Node) => Node;
+/**
+ * TSL object that represents the front facing status as a number instead of a bool.
+ * `1` means front facing, `-1` means back facing.
+ *
+ * @tsl
+ * @type {Node<float>}
+ */
+export const faceDirection: Node<"float">;
+/**
+ * Negates a vector if the rendering occurs on the back side of a face,
+ * based on the material's side configuration.
+ *
+ * - If the material's side is `BackSide`, the vector is inverted (negated).
+ * - If the material's side is `DoubleSide`, the vector is multiplied by `faceDirection`
+ *   (negated only for back-facing fragments).
+ * - If the material's side is `FrontSide` (default), the vector remains unchanged.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec3>} vector - The vector to process.
+ * @returns {Node<vec3>} The processed vector.
+ */
+export const negateOnBackSide: (vector: Node<"vec3"> | Vector3) => Node<"vec3">;
+/**
+ * Negates a vector if the rendering occurs on the back side of a face,
+ * based on the material's side configuration.
+ *
+ * - If the material's side is `BackSide`, the vector is inverted (negated).
+ * - If the material's side is `DoubleSide`, the vector is multiplied by `faceDirection`
+ *   (negated only for back-facing fragments).
+ * - If the material's side is `FrontSide` (default), the vector remains unchanged.
+ *
+ * @tsl
+ * @function
+ * @deprecated since r185. Use {@link negateOnBackSide} instead.
+ * @param {Node<vec3>} vector - The vector to convert.
+ * @returns {Node<vec3>} The converted vector.
+ */
+export const directionToFaceDirection: (vector: Node<"vec3"> | Vector3) => Node<"vec3">;

three/src/nodes/display/PassNode.d.ts

@@ -94,8 +94,6 @@ declare class PassNode extends TempNode<"vec4"> {
     setViewport(x: number, y: number, width: number, height: number): void;
     setViewport(x: Vector4): void;
 
-    setPixelRatio(pixelRatio: number): void;
-
     dispose(): void;
 
     static COLOR: "color";

three/src/nodes/display/PremultiplyAlphaFunctions.d.ts

@@ -0,0 +1,37 @@
+import { Color } from "../../math/Color.js";
+import { Vector3 } from "../../math/Vector3.js";
+import { Vector4 } from "../../math/Vector4.js";
+import Node from "../core/Node.js";
+
+type ColorParameter = Node<"float"> | number | Node<"vec3"> | Vector3 | Node<"color"> | Color | Node<"vec4"> | Vector4;
+
+/**
+ * Premultiplies the RGB channels of a color by its alpha channel.
+ *
+ * This function is useful for converting a non-premultiplied alpha color
+ * into a premultiplied alpha format, where the RGB values are scaled
+ * by the alpha value. Premultiplied alpha is often used in graphics
+ * rendering for certain operations, such as compositing and image processing.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec4>} color - The input color with non-premultiplied alpha.
+ * @return {Node<vec4>} The color with premultiplied alpha.
+ */
+export const premultiplyAlpha: (color: ColorParameter) => Node<"vec4">;
+/**
+ * Unpremultiplies the RGB channels of a color by its alpha channel.
+ *
+ * This function is useful for converting a premultiplied alpha color
+ * back into a non-premultiplied alpha format, where the RGB values are
+ * divided by the alpha value. Unpremultiplied alpha is often used in graphics
+ * rendering for certain operations, such as compositing and image processing.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec4>} color - The input color with premultiplied alpha.
+ * @return {Node<vec4>} The color with non-premultiplied alpha.
+ */
+export const unpremultiplyAlpha: (color: ColorParameter) => Node<"vec4">;
+
+export {};

three/src/nodes/gpgpu/AtomicFunctionNode.d.ts

@@ -11,73 +11,81 @@ export type AtomicMethod =
     | typeof AtomicFunctionNode.ATOMIC_OR
     | typeof AtomicFunctionNode.ATOMIC_XOR;
 
-declare class AtomicFunctionNode extends Node {
+interface AtomicFunctionNodeInterface {
     method: AtomicMethod;
     pointerNode: Node;
-    valueNode: Node;
+    valueNode: Node | null;
     parents: boolean;
-
-    constructor(method: AtomicMethod, pointerNode: Node, valueNode: Node);
-
-    static ATOMIC_LOAD: "atomicLoad";
-    static ATOMIC_STORE: "atomicStore";
-    static ATOMIC_ADD: "atomicAdd";
-    static ATOMIC_SUB: "atomicSub";
-    static ATOMIC_MAX: "atomicMax";
-    static ATOMIC_MIN: "atomicMin";
-    static ATOMIC_AND: "atomicAnd";
-    static ATOMIC_OR: "atomicOr";
-    static ATOMIC_XOR: "atomicXor";
 }
 
+declare const AtomicFunctionNode: {
+    new<TNodeType>(
+        method: AtomicMethod,
+        pointerNode: Node,
+        valueNode: Node | null,
+    ): AtomicFunctionNode<TNodeType>;
+
+    ATOMIC_LOAD: "atomicLoad";
+    ATOMIC_STORE: "atomicStore";
+    ATOMIC_ADD: "atomicAdd";
+    ATOMIC_SUB: "atomicSub";
+    ATOMIC_MAX: "atomicMax";
+    ATOMIC_MIN: "atomicMin";
+    ATOMIC_AND: "atomicAnd";
+    ATOMIC_OR: "atomicOr";
+    ATOMIC_XOR: "atomicXor";
+};
+
+export type AtomicFunctionNode<TNodeType> = Node<TNodeType> & AtomicFunctionNodeInterface;
+
 export default AtomicFunctionNode;
 
-export const atomicFunc: (
+export const atomicFunc: <TNodeType>(
     method: AtomicMethod,
-    pointerNode: Node,
-    valueNode: Node,
-) => AtomicFunctionNode;
+    pointerNode: Node<TNodeType>,
+    valueNode: Node | null,
+) => AtomicFunctionNode<TNodeType>;
 
-export const atomicLoad: (
-    pointerNode: Node,
-) => AtomicFunctionNode;
+export const atomicLoad: <TNodeType>(
+    pointerNode: Node<TNodeType>,
+) => AtomicFunctionNode<TNodeType>;
 
-export const atomicStore: (
-    pointerNode: Node,
+export const atomicStore: <TNodeType>(
+    pointerNode: Node<TNodeType>,
     valueNode: Node | number,
-) => AtomicFunctionNode;
+) => AtomicFunctionNode<TNodeType>;
 
-export const atomicAdd: (
-    pointerNode: Node,
+export const atomicAdd: <TNodeType>(
+    pointerNode: Node<TNodeType>,
     valueNode: Node | number,
-) => AtomicFunctionNode;
+) => AtomicFunctionNode<TNodeType>;
 
-export const atomicSub: (
-    pointerNode: Node,
+export const atomicSub: <TNodeType>(
+    pointerNode: Node<TNodeType>,
     valueNode: Node | number,
-) => AtomicFunctionNode;
+) => AtomicFunctionNode<TNodeType>;
 
-export const atomicMax: (
-    pointerNode: Node,
+export const atomicMax: <TNodeType>(
+    pointerNode: Node<TNodeType>,
     valueNode: Node,
-) => AtomicFunctionNode;
+) => AtomicFunctionNode<TNodeType>;
 
-export const atomicMin: (
-    pointerNode: Node,
+export const atomicMin: <TNodeType>(
+    pointerNode: Node<TNodeType>,
     valueNode: Node,
-) => AtomicFunctionNode;
+) => AtomicFunctionNode<TNodeType>;
 
-export const atomicAnd: (
-    pointerNode: Node,
+export const atomicAnd: <TNodeType>(
+    pointerNode: Node<TNodeType>,
     valueNode: Node,
-) => AtomicFunctionNode;
+) => AtomicFunctionNode<TNodeType>;
 
-export const atomicOr: (
-    pointerNode: Node,
+export const atomicOr: <TNodeType>(
+    pointerNode: Node<TNodeType>,
     valueNode: Node,
-) => AtomicFunctionNode;
+) => AtomicFunctionNode<TNodeType>;
 
-export const atomicXor: (
-    pointerNode: Node,
+export const atomicXor: <TNodeType>(
+    pointerNode: Node<TNodeType>,
     valueNode: Node,
-) => AtomicFunctionNode;
+) => AtomicFunctionNode<TNodeType>;

three/src/nodes/lighting/LightingContextNode.d.ts

@@ -1,6 +1,7 @@
 import ContextNode from "../core/ContextNode.js";
 import LightingModel, { LightingModelReflectedLight } from "../core/LightingModel.js";
 import Node from "../core/Node.js";
+import LightingNode from "./LightingNode.js";
 import LightsNode from "./LightsNode.js";
 
 export interface LightingContext {
@@ -9,18 +10,21 @@ export interface LightingContext {
     iblIrradiance: Node;
     ambientOcclusion: Node;
     reflectedLight: LightingModelReflectedLight;
+    materialLightings: LightingNode[];
     backdrop: Node;
     backdropAlpha: Node;
 }
 
 export default class LightingContextNode extends ContextNode<unknown> {
-    lightingModelNode: LightingModel | null;
+    lightingModel: LightingModel | null;
+    materialLightings: LightingNode[];
     backdropNode: Node | null;
     backdropAlphaNode: Node | null;
 
     constructor(
         lightsNode: LightsNode,
         lightingModel?: LightingModel | null,
+        materialLightings?: LightingNode[],
         backdropNode?: Node | null,
         backdropAlphaNode?: Node | null,
     );
@@ -30,5 +34,8 @@ export default class LightingContextNode extends ContextNode<unknown> {
 
 export const lightingContext: (
     node: LightsNode,
-    lightingModelNode?: LightingModel,
+    lightingModel?: LightingModel | null,
+    materialLightings?: LightingNode[],
+    backdropNode?: Node | null,
+    backdropAlphaNode?: Node | null,
 ) => LightingContextNode;

three/src/nodes/lighting/LightsNode.d.ts

@@ -18,13 +18,13 @@ export interface DirectRectAreaLightData {
 }
 
 declare class LightsNode extends Node {
-    totalDiffuseNode: Node;
-    totalSpecularNode: Node;
-    outgoingLightNode: Node;
+    totalDiffuseNode: Node<"vec3">;
+    totalSpecularNode: Node<"vec3">;
+    outgoingLightNode: Node<"vec3">;
 
     constructor();
 
-    setupLightsNode(builder: NodeBuilder): void;
+    setupLightsNode(builder: NodeBuilder): LightingNode[];
 
     setupDirectLight(builder: NodeBuilder, lightNode: Node, lightData: DirectLightData): void;