@types/three 0.182.0 → 0.183.0

three/src/lights/LightShadow.d.ts

@@ -1,11 +1,12 @@
 import { Camera } from "../cameras/Camera.js";
 import { TextureDataType } from "../constants.js";
 import { Object3DJSONObject } from "../core/Object3D.js";
+import { RenderTarget } from "../core/RenderTarget.js";
 import { Frustum } from "../math/Frustum.js";
 import { Matrix4 } from "../math/Matrix4.js";
 import { Vector2, Vector2Tuple } from "../math/Vector2.js";
 import { Vector4 } from "../math/Vector4.js";
-import { WebGLRenderTarget } from "../renderers/WebGLRenderTarget.js";
+import Node from "../nodes/core/Node.js";
 import { Light } from "./Light.js";
 
 export interface LightShadowJSON {
@@ -19,159 +20,174 @@ export interface LightShadowJSON {
 }
 
 /**
- * Serves as a base class for the other shadow classes.
- * @see {@link https://threejs.org/docs/index.html#api/en/lights/shadows/LightShadow | Official Documentation}
- * @see {@link https://github.com/mrdoob/three.js/blob/master/src/lights/LightShadow.js | Source}
+ * Abstract base class for light shadow classes. These classes
+ * represent the shadow configuration for different light types.
  */
-export class LightShadow<TCamera extends Camera = Camera> {
+export abstract class LightShadow<TCamera extends Camera = Camera> {
     /**
-     * Create a new instance of {@link LightShadow}
-     * @param camera The light's view of the world.
+     * Constructs a new light shadow.
+     *
+     * @param {Camera} camera - The light's view of the world.
      */
     constructor(camera: TCamera);
-
     /**
      * The light's view of the world.
-     * @remark This is used to generate a depth map of the scene; objects behind other objects from the light's perspective will be in shadow.
      */
     camera: TCamera;
-
     /**
-     * The intensity of the shadow. The default is `1`. Valid values are in the range `[0, 1]`.
+     * The intensity of the shadow. The default is `1`.
+     * Valid values are in the range `[0, 1]`.
+     *
+     * @default 1
      */
     intensity: number;
-
     /**
-     * Shadow map bias, how much to add or subtract from the normalized depth when deciding whether a surface is in shadow.
-     * @remark The Very tiny adjustments here (in the order of 0.0001) may help reduce artifacts in shadows.
-     * @remarks Expects a `Float`
-     * @defaultValue `0`
+     * Shadow map bias, how much to add or subtract from the normalized depth
+     * when deciding whether a surface is in shadow.
+     *
+     * The default is `0`. Very tiny adjustments here (in the order of `0.0001`)
+     * may help reduce artifacts in shadows.
+     *
+     * @default 0
      */
     bias: number;
-
     /**
-     * Defines how much the position used to query the shadow map is offset along the object normal.
-     * @remark The Increasing this value can be used to reduce shadow acne especially in large scenes where light shines onto geometry at a shallow angle.
-     * @remark The cost is that shadows may appear distorted.
-     * @remarks Expects a `Float`
-     * @defaultValue `0`
+     * A node version of `bias`. Only supported with `WebGPURenderer`.
+     *
+     * If a bias node is defined, `bias` has no effect.
+     *
+     * @default null
+     */
+    biasNode: Node<"float"> | null;
+    /**
+     * Defines how much the position used to query the shadow map is offset along
+     * the object normal. The default is `0`. Increasing this value can be used to
+     * reduce shadow acne especially in large scenes where light shines onto
+     * geometry at a shallow angle. The cost is that shadows may appear distorted.
+     *
+     * @default 0
      */
     normalBias: number;
-
     /**
-     * Setting this to values greater than 1 will blur the edges of the shadow.toi
-     * @remark High values will cause unwanted banding effects in the shadows - a greater {@link LightShadow.mapSize | mapSize
-     *  will allow for a higher value to be used here before these effects become visible.
-     * @remark If {@link THREE.WebGLRenderer.shadowMap.type | WebGLRenderer.shadowMap.type} is set to {@link Renderer | PCFSoftShadowMap},
-     * radius has no effect and it is recommended to increase softness by decreasing {@link LightShadow.mapSize | mapSize} instead.
-     * @remark Note that this has no effect if the {@link THREE.WebGLRenderer.shadowMap | WebGLRenderer.shadowMap}.{@link THREE.WebGLShadowMap.type | type}
-     * is set to {@link THREE.BasicShadowMap | BasicShadowMap}.
-     * @remarks Expects a `Float`
-     * @defaultValue `1`
+     * Setting this to values greater than 1 will blur the edges of the shadow.
+     * High values will cause unwanted banding effects in the shadows - a greater
+     * map size will allow for a higher value to be used here before these effects
+     * become visible.
+     *
+     * The property has no effect when the shadow map type is `BasicShadowMap`.
+     *
+     * @default 1
      */
     radius: number;
-
     /**
      * The amount of samples to use when blurring a VSM shadow map.
-     * @remarks Expects a `Integer`
-     * @defaultValue `8`
+     *
+     * @default 8
      */
     blurSamples: number;
-
     /**
-     * A {@link THREE.Vector2 | Vector2} defining the width and height of the shadow map.
-     * @remarks Higher values give better quality shadows at the cost of computation time.
-     * @remarks Values must be powers of 2, up to the {@link THREE.WebGLRenderer.capabilities | WebGLRenderer.capabilities}.maxTextureSize for a given device,
-     * although the width and height don't have to be the same (so, for example, (512, 1024) is valid).
-     * @defaultValue `new THREE.Vector2(512, 512)`
+     * Defines the width and height of the shadow map. Higher values give better quality
+     * shadows at the cost of computation time. Values must be powers of two.
+     *
+     * @default (512,512)
      */
     mapSize: Vector2;
-
     /**
      * The type of shadow texture. The default is `UnsignedByteType`.
      *
      * @default UnsignedByteType
      */
     mapType: TextureDataType;
-
     /**
-     * The depth map generated using the internal camera; a location beyond a pixel's depth is in shadow. Computed internally during rendering.
-     * @defaultValue null
+     * The depth map generated using the internal camera; a location beyond a
+     * pixel's depth is in shadow. Computed internally during rendering.
+     *
+     * @default null
      */
-    map: WebGLRenderTarget | null;
-
+    map: RenderTarget | null;
     /**
-     * The distribution map generated using the internal camera; an occlusion is calculated based on the distribution of depths. Computed internally during rendering.
-     * @defaultValue null
+     * The distribution map generated using the internal camera; an occlusion is
+     * calculated based on the distribution of depths. Computed internally during
+     * rendering.
+     *
+     * @default null
      */
-    mapPass: WebGLRenderTarget | null;
-
+    mapPass: RenderTarget | null;
     /**
      * Model to shadow camera space, to compute location and depth in shadow map.
-     * Stored in a {@link Matrix4 | Matrix4}.
-     * @remarks This is computed internally during rendering.
-     * @defaultValue new THREE.Matrix4()
+     * This is computed internally during rendering.
      */
     matrix: Matrix4;
-
     /**
-     * Enables automatic updates of the light's shadow. If you do not require dynamic lighting / shadows, you may set this to `false`.
-     * @defaultValue `true`
+     * Enables automatic updates of the light's shadow. If you do not require dynamic
+     * lighting / shadows, you may set this to `false`.
+     *
+     * @default true
      */
     autoUpdate: boolean;
-
     /**
      * When set to `true`, shadow maps will be updated in the next `render` call.
-     * If you have set {@link autoUpdate} to `false`, you will need to set this property to `true` and then make a render call to update the light's shadow.
-     * @defaultValue `false`
+     * If you have set {@link LightShadow#autoUpdate} to `false`, you will need to
+     * set this property to `true` and then make a render call to update the light's shadow.
+     *
+     * @default false
      */
     needsUpdate: boolean;
-
     /**
-     * Used internally by the renderer to get the number of viewports that need to be rendered for this shadow.
+     * Used internally by the renderer to get the number of viewports that need
+     * to be rendered for this shadow.
+     *
+     * @return {number} The viewport count.
      */
     getViewportCount(): number;
-
     /**
-     * Copies value of all the properties from the {@link {@link LightShadow} | source} to this Light.
-     * @param source
-     */
-    copy(source: LightShadow): this;
-
-    /**
-     * Creates a new {@link LightShadow} with the same properties as this one.
-     */
-    clone(recursive?: boolean): this;
-
-    /**
-     * Serialize this LightShadow.
-     */
-    toJSON(): LightShadowJSON;
-
-    /**
-     * Gets the shadow cameras frustum
-     * @remarks
-     * Used internally by the renderer to cull objects.
+     * Gets the shadow cameras frustum. Used internally by the renderer to cull objects.
+     *
+     * @return {Frustum} The shadow camera frustum.
      */
     getFrustum(): Frustum;
-
     /**
      * Update the matrices for the camera and shadow, used internally by the renderer.
-     * @param light The light for which the shadow is being rendered.
+     *
+     * @param {Light} light - The light for which the shadow is being rendered.
      */
     updateMatrices(light: Light): void;
-
+    /**
+     * Returns a viewport definition for the given viewport index.
+     *
+     * @param {number} viewportIndex - The viewport index.
+     * @return {Vector4} The viewport.
+     */
     getViewport(viewportIndex: number): Vector4;
-
     /**
-     * Used internally by the renderer to extend the shadow map to contain all viewports
+     * Returns the frame extends.
+     *
+     * @return {Vector2} The frame extends.
      */
     getFrameExtents(): Vector2;
-
     /**
-     * Frees the GPU-related resources allocated by this instance
-     * @remarks
-     * Call this method whenever this instance is no longer used in your app.
+     * Frees the GPU-related resources allocated by this instance. Call this
+     * method whenever this instance is no longer used in your app.
      */
     dispose(): void;
+    /**
+     * Copies the values of the given light shadow instance to this instance.
+     *
+     * @param {LightShadow} source - The light shadow to copy.
+     * @return {LightShadow} A reference to this light shadow instance.
+     */
+    copy(source: LightShadow): this;
+    /**
+     * Returns a new light shadow instance with copied values from this instance.
+     *
+     * @return {LightShadow} A clone of this instance.
+     */
+    clone(): this;
+    /**
+     * Serializes the light shadow into JSON.
+     *
+     * @return {Object} A JSON object representing the serialized light shadow.
+     * @see {@link ObjectLoader#parse}
+     */
+    toJSON(): LightShadowJSON;
 }

three/src/lights/PointLight.d.ts

@@ -12,102 +12,61 @@ export interface PointLightJSON extends LightJSON {
 }
 
 /**
- * A light that gets emitted from a single point in all directions
- * @remarks
- * A common use case for this is to replicate the light emitted from a bare lightbulb.
- * @example
- * ```typescript
- * const light = new THREE.PointLight(0xff0000, 1, 100);
- * light.position.set(50, 50, 50);
- * scene.add(light);
+ * A light that gets emitted from a single point in all directions. A common
+ * use case for this is to replicate the light emitted from a bare
+ * lightbulb.
+ *
+ * This light can cast shadows - see the {@link PointLightShadow} for details.
+ *
+ * ```js
+ * const light = new THREE.PointLight( 0xff0000, 1, 100 );
+ * light.position.set( 50, 50, 50 );
+ * scene.add( light );
  * ```
- * @see Example: {@link https://threejs.org/examples/#webgl_lights_pointlights | lights / pointlights }
- * @see Example: {@link https://threejs.org/examples/#webgl_effects_anaglyph | effects / anaglyph }
- * @see Example: {@link https://threejs.org/examples/#webgl_geometry_text | geometry / text }
- * @see Example: {@link https://threejs.org/examples/#webgl_lensflares | lensflares }
- * @see {@link https://threejs.org/docs/index.html#api/en/lights/PointLight | Official Documentation}
- * @see {@link https://github.com/mrdoob/three.js/blob/master/src/lights/PointLight.js | Source}
  */
-export class PointLight extends Light<PointLightShadow> {
+export class PointLight extends Light {
     /**
-     * Creates a new PointLight.
-     * @param color Hexadecimal color of the light. Default is 0xffffff (white). Expects an `Integer`
-     * @param intensity Numeric value of the light's strength/intensity. Expects a `Float`. Default `1`
-     * @param distance Maximum range of the light. Default is 0 (no limit).
-     * @param decay The amount the light dims along the distance of the light. Expects a `Float`. Default `2`
+     * Constructs a new point light.
+     *
+     * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+     * @param {number} [intensity=1] - The light's strength/intensity measured in candela (cd).
+     * @param {number} [distance=0] - Maximum range of the light. `0` means no limit.
+     * @param {number} [decay=2] - The amount the light dims along the distance of the light.
      */
     constructor(color?: ColorRepresentation, intensity?: number, distance?: number, decay?: number);
-
-    /**
-     * Read-only flag to check if a given object is of type {@link PointLight}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
-     */
-    readonly isPointLight: true;
-
     /**
-     * @default 'PointLight'
-     */
-    type: string;
-
-    /**
-     * The light's intensity.
+     * This flag can be used for type testing.
      *
-     * When **{@link WebGLRenderer.useLegacyLights | legacy lighting mode} is disabled** — intensity is the luminous intensity of the light measured in candela (cd).
-     * @remarks Changing the intensity will also change the light's power.
-     * @remarks Expects a `Float`
-     * @defaultValue `1`
+     * @default true
      */
-    intensity: number;
-
+    readonly isPointLight: boolean;
     /**
-     * When **Default mode** — When distance is zero, light does not attenuate. When distance is non-zero,
-     * light will attenuate linearly from maximum intensity at the light's position down to zero at this distance from the light.
+     * When distance is zero, light will attenuate according to inverse-square
+     * law to infinite distance. When distance is non-zero, light will attenuate
+     * according to inverse-square law until near the distance cutoff, where it
+     * will then attenuate quickly and smoothly to 0. Inherently, cutoffs are not
+     * physically correct.
      *
-     * When **{@link WebGLRenderer.useLegacyLights | legacy lighting mode} is disabled** — When distance is zero,
-     * light will attenuate according to inverse-square law to infinite distance.
-     * When distance is non-zero, light will attenuate according to inverse-square law until near the distance cutoff,
-     * where it will then attenuate quickly and smoothly to 0. Inherently, cutoffs are not physically correct.
-     *
-     * @defaultValue `0.0`
-     * @remarks Expects a `Float`
+     * @default 0
      */
     distance: number;
-
-    /**
-     * If set to `true` light will cast dynamic shadows.
-     * **Warning**: This is expensive and requires tweaking to get shadows looking right.
-     * @see {@link THREE.PointLightShadow | PointLightShadow} for details.
-     * @defaultValue `false`
-     */
-    castShadow: boolean;
-
     /**
-     * The amount the light dims along the distance of the light.
-     * In context of physically-correct rendering the default value should not be changed.
-     * @remarks Expects a `Float`
-     * @defaultValue `2`
+     * The amount the light dims along the distance of the light. In context of
+     * physically-correct rendering the default value should not be changed.
+     *
+     * @default 2
      */
     decay: number;
-
     /**
-     * A {@link THREE.PointLightShadow | PointLightShadow} used to calculate shadows for this light.
-     * The lightShadow's {@link LightShadow.camera | camera} is set to
-     * a {@link THREE.PerspectiveCamera | PerspectiveCamera} with {@link PerspectiveCamera.fov | fov} of 90,
-     * {@link PerspectiveCamera.aspect | aspect} of 1,
-     * {@link PerspectiveCamera.near | near} clipping plane at 0.5
-     * and {@link PerspectiveCamera.far | far} clipping plane at 500.
-     * @defaultValue new THREE.PointLightShadow()
+     * This property holds the light's shadow configuration.
      */
     shadow: PointLightShadow;
-
+    set power(power: number);
     /**
-     * The light's power.
-     * When **{@link WebGLRenderer.useLegacyLights | legacy lighting mode} is disabled** — power is the luminous power of the light measured in lumens (lm).
-     * @remarks Changing the power will also change the light's intensity.
-     * @remarks Expects a `Float`
+     * The light's power. Power is the luminous power of the light measured in lumens (lm).
+     * Changing the power will also change the light's intensity.
      */
-    power: number;
-
+    get power(): number;
+    copy(source: PointLight, recursive?: boolean): this;
     toJSON(meta?: JSONMeta): PointLightJSON;
 }

three/src/lights/PointLightShadow.d.ts

@@ -2,14 +2,17 @@ import { PerspectiveCamera } from "../cameras/PerspectiveCamera.js";
 import { LightShadow } from "./LightShadow.js";
 
 /**
- * Shadow for {@link THREE.PointLight | PointLight}
- * @see {@link https://github.com/mrdoob/three.js/blob/master/src/lights/PointLightShadow.js | Source}
+ * Represents the shadow configuration of point lights.
  */
 export class PointLightShadow extends LightShadow<PerspectiveCamera> {
     /**
-     * Read-only flag to check if a given object is of type {@link PointLightShadow}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
+     * Constructs a new point light shadow.
      */
-    readonly isPointLightShadow: true;
+    constructor();
+    /**
+     * This flag can be used for type testing.
+     *
+     * @default true
+     */
+    readonly isPointLightShadow: boolean;
 }

three/src/lights/RectAreaLight.d.ts

@@ -2,81 +2,61 @@ import { ColorRepresentation } from "../math/Color.js";
 import { Light } from "./Light.js";
 
 /**
- * {@link RectAreaLight} emits light uniformly across the face a rectangular plane
- * @remarks
- * This light type can be used to simulate light sources such as bright windows or strip lighting.
+ * This class emits light uniformly across the face a rectangular plane.
+ * This light type can be used to simulate light sources such as bright
+ * windows or strip lighting.
+ *
  * Important Notes:
- *  - There is no shadow support.
- *  - Only {@link MeshStandardMaterial | MeshStandardMaterial} and {@link MeshPhysicalMaterial | MeshPhysicalMaterial} are supported.
- *  - You have to include {@link https://threejs.org/examples/jsm/lights/RectAreaLightUniformsLib.js | RectAreaLightUniformsLib} into your scene and call `init()`.
- * @example
- * ```typescript
- * const width = 10;
- * const height = 10;
- * const intensity = 1;
- * const rectLight = new THREE.RectAreaLight(0xffffff, intensity, width, height);
- * rectLight.position.set(5, 5, 0);
- * rectLight.lookAt(0, 0, 0);
- * scene.add(rectLight)
- * const rectLightHelper = new RectAreaLightHelper(rectLight);
- * rectLight.add(rectLightHelper);
+ *
+ * - There is no shadow support.
+ * - Only PBR materials are supported.
+ * - You have to include `RectAreaLightUniformsLib` (`WebGLRenderer`) or `RectAreaLightTexturesLib` (`WebGPURenderer`)
+ * into your app and init the uniforms/textures.
+ *
+ * ```js
+ * RectAreaLightUniformsLib.init(); // only relevant for WebGLRenderer
+ * THREE.RectAreaLightNode.setLTC( RectAreaLightTexturesLib.init() ); //  only relevant for WebGPURenderer
+ *
+ * const intensity = 1; const width = 10; const height = 10;
+ * const rectLight = new THREE.RectAreaLight( 0xffffff, intensity, width, height );
+ * rectLight.position.set( 5, 5, 0 );
+ * rectLight.lookAt( 0, 0, 0 );
+ * scene.add( rectLight )
  * ```
- * @see Example: {@link https://threejs.org/examples/#webgl_lights_rectarealight | WebGL / {@link RectAreaLight} }
- * @see {@link https://threejs.org/docs/index.html#api/en/lights/RectAreaLight | Official Documentation}
- * @see {@link https://github.com/mrdoob/three.js/blob/master/src/lights/RectAreaLight.js | Source}
  */
-export class RectAreaLight extends Light<undefined> {
+export class RectAreaLight extends Light {
     /**
-     * Creates a new {@link RectAreaLight}.
-     * @param color Hexadecimal color of the light. Default `0xffffff` _(white)_.
-     * @param intensity The light's intensity, or brightness. Expects a `Float`. Default `1`
-     * @param width Width of the light. Expects a `Float`. Default `10`
-     * @param height Height of the light. Expects a `Float`. Default `10`
+     * Constructs a new area light.
+     *
+     * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+     * @param {number} [intensity=1] - The light's strength/intensity.
+     * @param {number} [width=10] - The width of the light.
+     * @param {number} [height=10] - The height of the light.
      */
     constructor(color?: ColorRepresentation, intensity?: number, width?: number, height?: number);
-
     /**
-     * Read-only flag to check if a given object is of type {@link RectAreaLight}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
+     * This flag can be used for type testing.
+     *
+     * @default true
      */
-    readonly isRectAreaLight: true;
-
-    /**
-     * A Read-only _string_ to check if `this` object type.
-     * @remarks Sub-classes will update this value.
-     * @defaultValue `RectAreaLight`
-     */
-    override readonly type: string | "RectAreaLight";
-
+    readonly isRectAreaLight: boolean;
     /**
      * The width of the light.
-     * @remarks Expects a `Float`
-     * @defaultValue `10`
+     *
+     * @default 10
      */
     width: number;
-
     /**
      * The height of the light.
-     * @remarks Expects a `Float`
-     * @defaultValue `10`
+     *
+     * @default 10
      */
     height: number;
-
-    /**
-     * The light's intensity.
-     * @remarks Changing the intensity will also change the light's power.
-     * When **{@link WebGLRenderer.useLegacyLights | legacy lighting mode} is disabled** — intensity is the luminance (brightness) of the light measured in nits (cd/m^2).
-     * @remarks Expects a `Float`
-     * @defaultValue `1`
-     */
-    intensity: number;
-
+    set power(power: number);
     /**
-     * The light's power.
-     * @remarks Changing the power will also change the light's intensity.
-     * When **{@link WebGLRenderer.useLegacyLights | legacy lighting mode} is disabled** — power is the luminous power of the light measured in lumens (lm).
-     * @remarks Expects a `Float`
+     * The light's power. Power is the luminous power of the light measured in lumens (lm).
+     * Changing the power will also change the light's intensity.
      */
-    power: number;
+    get power(): number;
+    copy(source: RectAreaLight): this;
 }