@types/three 0.150.1 → 0.151.0

three/src/lights/LightProbe.d.ts

@@ -1,20 +1,47 @@
 import { SphericalHarmonics3 } from './../math/SphericalHarmonics3';
 import { Light } from './Light';
 
+/**
+ * Light probes are an alternative way of adding light to a 3D scene.
+ * @remarks
+ * Unlike classical light sources (e.g
+ * directional, point or spot lights), light probes do not emit light
+ * Instead they store information about light passing through 3D space
+ * During rendering, the light that hits a 3D object is approximated by using the data from the light probe.
+ * Light probes are usually created from (radiance) environment maps
+ * The class {@link THREE.LightProbeGenerator | LightProbeGenerator} can be used to create light probes from
+ * instances of {@link THREE.CubeTexture | CubeTexture} or {@link THREE.WebGLCubeRenderTarget | WebGLCubeRenderTarget}
+ * However, light estimation data could also be provided in other forms e.g
+ * by WebXR
+ * This enables the rendering of augmented reality content that reacts to real world lighting.
+ * The current probe implementation in three.js supports so-called diffuse light probes
+ * This type of light probe is functionally equivalent to an irradiance environment map.
+ * @see Example: {@link https://threejs.org/examples/#webgl_lightprobe | WebGL / light probe }
+ * @see Example: {@link https://threejs.org/examples/#webgl_lightprobe_cubecamera | WebGL / light probe / cube camera }
+ * @see {@link https://threejs.org/docs/index.html#api/en/lights/LightProbe | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/lights/LightProbe.js | Source}
+ */
 export class LightProbe extends Light {
+    /**
+     * Creates a new LightProbe.
+     * @param sh An instance of {@link THREE.SphericalHarmonics3 | SphericalHarmonics3}. Default `new THREE.SphericalHarmonics3()``.
+     * @param intensity Numeric value of the light probe's intensity. Expects a `Float`. Default `1`.
+     */
     constructor(sh?: SphericalHarmonics3, intensity?: number);
 
     /**
-     * @default 'LightProbe'
+     * Read-only flag to check if a given object is of type {@link DirectionalLight}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
      */
-    type: string;
-
     readonly isLightProbe: true;
 
     /**
-     * @default new THREE.SphericalHarmonics3()
+     * A light probe uses spherical harmonics to encode lighting information.
+     * @defaultValue `new THREE.SphericalHarmonics3()`
      */
     sh: SphericalHarmonics3;
 
-    fromJSON(json: object): LightProbe;
+    /** @internal */
+    fromJSON(json: {}): LightProbe;
 }

three/src/lights/LightShadow.d.ts

@@ -4,68 +4,150 @@ import { Vector2 } from './../math/Vector2';
 import { Vector4 } from './../math/Vector4';
 import { Matrix4 } from './../math/Matrix4';
 import { WebGLRenderTarget } from '../renderers/WebGLRenderTarget';
+import { Frustum } from '../Three';
 
-export class LightShadow {
-    constructor(camera: Camera);
+/**
+ * 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}
+ */
+export class LightShadow<TCamera extends Camera = Camera> {
+    /**
+     * Create a new instance of {@link LightShadow}
+     * @param camera The light's view of the world.
+     */
+    constructor(camera: TCamera);
 
-    camera: Camera;
+    /**
+     * 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;
 
     /**
-     * @default 0
+     * 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`
      */
     bias: number;
 
     /**
-     * @default 0
+     * 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`
      */
     normalBias: number;
 
     /**
-     * @default 1
+     * 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`
      */
     radius: number;
 
     /**
-     * @default 8
+     * The amount of samples to use when blurring a VSM shadow map.
+     * @remarks Expects a `Integer`
+     * @defaultValue `8`
      */
     blurSamples: number;
 
     /**
-     * @default new THREE.Vector2( 512, 512 )
+     * 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)`
      */
     mapSize: Vector2;
 
     /**
-     * @default null
+     * The depth map generated using the internal camera; a location beyond a pixel's depth is in shadow. Computed internally during rendering.
+     * @defaultValue null
      */
-    map: WebGLRenderTarget;
+    map: WebGLRenderTarget | null;
 
     /**
-     * @default 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
      */
-    mapPass: WebGLRenderTarget;
+    mapPass: WebGLRenderTarget | null;
 
     /**
-     * @default new THREE.Matrix4()
+     * 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()
      */
     matrix: Matrix4;
 
     /**
-     * @default true
+     * Enables automatic updates of the light's shadow. If you do not require dynamic lighting / shadows, you may set this to `false`.
+     * @defaultValue `true`
      */
     autoUpdate: boolean;
 
     /**
-     * @default false
+     * 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`
      */
     needsUpdate: boolean;
 
+    /**
+     * Used internally by the renderer to get the number of viewports that need to be rendered for this shadow.
+     */
+    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;
-    toJSON(): any;
-    getFrustum(): number;
-    updateMatrices(light: Light, viewportIndex?: number): void;
+
+    /**
+     * Serialize this LightShadow.
+     */
+    toJSON(): {};
+
+    /**
+     * Gets the shadow cameras frustum
+     * @remarks
+     * Used internally by the renderer to cull objects.
+     */
+    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.
+     */
+    updateMatrices(light: Light): void;
+
     getViewport(viewportIndex: number): Vector4;
+
+    /**
+     * Used internally by the renderer to extend the shadow map to contain all viewports
+     */
     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.
+     */
     dispose(): void;
 }

three/src/lights/PointLight.d.ts

@@ -1,14 +1,32 @@
-import { ColorRepresentation } from '../utils';
+import { ColorRepresentation } from '../math/Color';
 import { Light } from './Light';
 import { PointLightShadow } from './PointLightShadow';
 
 /**
+ * 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
- * const light = new THREE.PointLight( 0xff0000, 1, 100 );
- * light.position.set( 50, 50, 50 );
- * scene.add( light );
+ * ```typescript
+ * 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 {
+export class PointLight extends Light<PointLightShadow> {
+    /**
+     * Creates a new PointLight.
+     * @param color Hexadecimal color of the light. Default is 0xffffff (white). Expects a `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`
+     */
     constructor(color?: ColorRepresentation, intensity?: number, distance?: number, decay?: number);
 
     /**
@@ -17,34 +35,61 @@ export class PointLight extends Light {
     type: string;
 
     /**
-     * Light's intensity.
-     * @default 2
+     * The light's intensity.
+     *
+     * When **{@link WebGLRenderer.physicallyCorrectLights | physically correct} mode** — 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`
      */
     intensity: number;
 
     /**
-     * If non-zero, light will attenuate linearly from maximum intensity at light position down to zero at distance.
-     * @default 0
+     * 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 **{@link WebGLRenderer.physicallyCorrectLights | Physically correct} rendering mode** — 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`
      */
     distance: number;
 
     /**
      * If set to `true` light will cast dynamic shadows.
      * **Warning**: This is expensive and requires tweaking to get shadows looking right.
-     * See the {@link PointLightShadow} for details.
-     * The default is `false`.
+     * @see {@link THREE.PointLightShadow | PointLightShadow} for details.
+     * @defaultValue `false`
      */
     castShadow: boolean;
 
     /**
-     * @default 1
+     * The amount the light dims along the distance of the light.
+     * In **{@link WebGLRenderer.physicallyCorrectLights | physically correct} rendering mode** — the default value **should not** be changed.
+     * @remarks Expects a `Float`
+     * @defaultValue `2`
      */
     decay: number;
 
     /**
-     * @default new THREE.PointLightShadow()
+     * 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()
      */
     shadow: PointLightShadow;
 
+    /**
+     * The light's power.
+     * When **{@link WebGLRenderer.physicallyCorrectLights | physically correct} rendering mode** — 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`
+     */
     power: number;
 }

three/src/lights/PointLightShadow.d.ts

@@ -1,6 +1,22 @@
 import { PerspectiveCamera } from './../cameras/PerspectiveCamera';
+import { Light } from './Light';
 import { LightShadow } from './LightShadow';
 
-export class PointLightShadow extends LightShadow {
-    camera: PerspectiveCamera;
+/**
+ * Shadow for {@link THREE.PointLight | PointLight}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/lights/PointLightShadow.js | Source}
+ */
+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`
+     */
+    readonly isPointLightShadow = true;
+
+    /**
+     * Update the matrices for the camera and shadow, used internally by the renderer.
+     * @param light The light for which the shadow is being rendered.
+     */
+    override updateMatrices(light: Light, viewportIndex?: number): void;
 }

three/src/lights/RectAreaLight.d.ts

@@ -1,30 +1,82 @@
 import { Light } from './Light';
-import { ColorRepresentation } from '../utils';
+import { ColorRepresentation } from '../math/Color';
 
-export class RectAreaLight extends Light {
+/**
+ * {@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.
+ * 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);
+ * ```
+ * @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> {
+    /**
+     * 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`
+     */
     constructor(color?: ColorRepresentation, intensity?: number, width?: number, height?: number);
 
     /**
-     * @default 'RectAreaLight'
+     * Read-only flag to check if a given object is of type {@link RectAreaLight}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isRectAreaLight: true;
+
+    /**
+     * A Read-only _string_ to check if `this` object type.
+     * @remarks Sub-classes will update this value.
+     * @defaultValue `RectAreaLight`
      */
-    type: string;
+    override readonly type: string | 'RectAreaLight';
 
     /**
-     * @default 10
+     * The width of the light.
+     * @remarks Expects a `Float`
+     * @defaultValue `10`
      */
     width: number;
 
     /**
-     * @default 10
+     * The height of the light.
+     * @remarks Expects a `Float`
+     * @defaultValue `10`
      */
     height: number;
 
     /**
-     * @default 1
+     * The light's intensity.
+     * @remarks Changing the intensity will also change the light's power.
+     * In **{@link WebGLRenderer.physicallyCorrectLights | physically correct} rendering mode** — intensity is the luminance (brightness) of the light measured in nits (cd/m^2).
+     * @remarks Expects a `Float`
+     * @defaultValue `1`
      */
     intensity: number;
 
+    /**
+     * The light's power.
+     * @remarks Changing the power will also change the light's intensity.
+     * In **{@link WebGLRenderer.physicallyCorrectLights | physically correct} rendering mode** — power is the luminous power of the light measured in lumens (lm).
+     * @remarks Expects a `Float`
+     */
     power: number;
-
-    readonly isRectAreaLight: true;
 }

three/src/lights/SpotLight.d.ts

@@ -1,15 +1,41 @@
-import { Color } from './../math/Color';
 import { Vector3 } from '../math/Vector3';
 import { Object3D } from './../core/Object3D';
 import { SpotLightShadow } from './SpotLightShadow';
 import { Light } from './Light';
-import { ColorRepresentation } from '../utils';
+import { ColorRepresentation } from '../math/Color';
 import { Texture } from '../textures/Texture';
 
 /**
- * A point light that can cast shadow in one direction.
+ * This light gets emitted from a single point in one direction, along a cone that increases in size the further from the light it gets.
+ * @example
+ * ```typescript
+ * // white {@link SpotLight} shining from the side, modulated by a texture, casting a shadow
+ * const {@link SpotLight} = new THREE.SpotLight(0xffffff);
+ * spotLight.position.set(100, 1000, 100);
+ * spotLight.map = new THREE.TextureLoader().load(url);
+ * spotLight.castShadow = true;
+ * spotLight.shadow.mapSize.width = 1024;
+ * spotLight.shadow.mapSize.height = 1024;
+ * spotLight.shadow.camera.near = 500;
+ * spotLight.shadow.camera.far = 4000;
+ * spotLight.shadow.camera.fov = 30;
+ * scene.add(spotLight);
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webgl_lights_spotlight | lights / {@link SpotLight} }
+ * @see Example: {@link https://threejs.org/examples/#webgl_lights_spotlights | lights / spotlights }
+ * @see {@link https://threejs.org/docs/index.html#api/en/lights/SpotLight | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/lights/SpotLight.js | Source}
  */
-export class SpotLight extends Light {
+export class SpotLight extends Light<SpotLightShadow> {
+    /**
+     * Creates a new SpotLight.
+     * @param color Hexadecimal color of the light. Default `0xffffff` _(white)_.
+     * @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). Expects a `Float`.
+     * @param angle Maximum angle of light dispersion from its direction whose upper bound is Math.PI/2.
+     * @param penumbra Percent of the {@link SpotLight} cone that is attenuated due to penumbra. Takes values between zero and 1. Expects a `Float`. Default `0`.
+     * @param decay The amount the light dims along the distance of the light. Expects a `Float`. Default `2`.
+     */
     constructor(
         color?: ColorRepresentation,
         intensity?: number,
@@ -20,61 +46,119 @@ export class SpotLight extends Light {
     );
 
     /**
-     * @default 'SpotLight'
+     * Read-only flag to check if a given object is of type {@link SpotLight}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
      */
-    type: string;
+    readonly isSpotLight: true;
 
     /**
-     * This is set equal to {@link Object3D.DEFAULT_UP} (0, 1, 0), so that the light shines from the top down.
-     *
-     * @default {@link Object3D.DEFAULT_UP}
+     * A Read-only _string_ to check if `this` object type.
+     * @remarks Sub-classes will update this value.
+     * @defaultValue `SpotLight`
+     */
+    override readonly type: string | 'SpotLight';
+
+    /**
+     * This is set equal to {@link THREE.Object3D.DEFAULT_UP | Object3D.DEFAULT_UP} (0, 1, 0), so that the light shines from the top down.
+     * @defaultValue `{@link Object3D.DEFAULT_UP}`
      */
     position: Vector3;
 
     /**
-     * Spotlight focus points at target.position.
-     * @default new THREE.Object3D()
+     * The {@link SpotLight} points from its {@link SpotLight.position | position} to target.position.
+     * @remarks
+     * **Note**: For the target's position to be changed to anything other than the default,
+     * it must be added to the {@link Scene | scene} using
+     *
+     * ```typescript
+     * scene.add( light.target );
+     * ```
+     *
+     * This is so that the target's {@link Object3D.matrixWorld | matrixWorld} gets automatically updated each frame.
+     * It is also possible to set the target to be another object in the scene (anything with a {@link THREE.Object3D.position | position} property), like so:
+     * ```typescript
+     * const targetObject = new THREE.Object3D();
+     * scene.add(targetObject);
+     * light.target = targetObject;
+     * ```
+     * The {@link SpotLight} will now track the target object.
+     * @defaultValue `new THREE.Object3D()` _The default position of the target is *(0, 0, 0)*._
      */
     target: Object3D;
 
     /**
-     * Light's intensity.
-     * @default 2
+     * If set to `true` light will cast dynamic shadows.
+     * @remarks  **Warning**: This is expensive and requires tweaking to get shadows looking right. the {@link THREE.SpotLightShadow | SpotLightShadow} for details.
+     * @defaultValue `false`
+     */
+    override castShadow: boolean;
+
+    /**
+     * The light's intensity.
+     * @remarks Changing the intensity will also change the light's power.
+     * When **{@link WebGLRenderer.physicallyCorrectLights | Physically correct} rendering mode** — intensity is the luminous intensity of the light measured in candela (cd).
+     * @remarks Expects a `Float`
+     * @defaultValue `1`
      */
     intensity: number;
 
     /**
-     * If non-zero, light will attenuate linearly from maximum intensity at light position down to zero at distance.
-     * @default 0
+     * 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 **{@link WebGLRenderer.physicallyCorrectLights | Physically correct} rendering mode** — 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.
+     * @remarks Expects a `Float`
+     * @defaultValue `0.0`
      */
     distance: number;
 
     /**
      * Maximum extent of the spotlight, in radians, from its direction.
-     * @default Math.PI / 3.
+     * @remarks Should be no more than `Math.PI/2`.
+     * @remarks Expects a `Float`
+     * @defaultValue `Math.PI / 3`
      */
     angle: number;
 
     /**
-     * @default 1
+     * The amount the light dims along the distance of the light.
+     * In **{@link WebGLRenderer.physicallyCorrectLights | physically correct} rendering mode** — the default value should not be changed.
+     * @remarks Expects a `Float`
+     * @defaultValue `2`
      */
     decay: number;
 
     /**
-     * @default new THREE.SpotLightShadow()
+     * A {@link THREE.SpotLightShadow | SpotLightShadow} used to calculate shadows for this light.
+     * @defaultValue `new THREE.SpotLightShadow()`
      */
     shadow: SpotLightShadow;
+
+    /**
+     * The light's power.
+     * @remarks Changing the power will also change the light's intensity.
+     * In **{@link WebGLRenderer.physicallyCorrectLights | physically correct} rendering mode** —  power is the luminous power of the light measured in lumens (lm).
+     * @remarks Expects a `Float`
+     */
     power: number;
 
     /**
-     * @default 0
+     * Percent of the {@link SpotLight} cone that is attenuated due to penumbra.
+     * @remarks Takes values between zero and 1.
+     * @remarks Expects a `Float`
+     * @defaultValue `0.0`
      */
     penumbra: number;
 
     /**
-     * @default null
+     * A {@link THREE.Texture | Texture} used to modulate the color of the light.
+     * The spot light color is mixed with the _RGB_ value of this texture, with a ratio corresponding to its alpha value.
+     * The cookie-like masking effect is reproduced using pixel values (0, 0, 0, 1-cookie_value).
+     * @remarks **Warning**: {@link SpotLight.map} is disabled if {@link SpotLight.castShadow} is `false`.
      */
     map: Texture | null;
-
-    readonly isSpotLight: true;
 }