# Introduction To Lights

> Learn the basics of lights in Babylon.js

Source: https://doc.babylonjs.com/features/featuresDeepDive/lights/lights_introduction

## Lights

Lights are used, as you would expect, to affect how meshes are seen, in terms of both illumination and color.
All meshes allow light to pass through them unless shadow generation is activated. The default number of allowed lights is
four, but this can be increased.

![Elements](https://doc.babylonjs.com/img/testlight.webp)

_A pretty sphere with multiple lights_

## Types of Lights

There are five types of lights that can be used, each with a range of lighting properties.

### The Point Light

A point light is a light defined by a unique point in world space. The light is emitted in every direction from this point. A good example of a point light is a standard light bulb.

```javascript
const light = new BABYLON.PointLight("pointLight", new BABYLON.Vector3(1, 10, 1), scene);
```

### The Directional Light

A directional light is defined by a direction (what a surprise!). The light is emitted from everywhere in the specified direction and has an infinite range.
An example of a directional light is a distant planet lit by the apparently parallel lines of light from its sun. Light shining downward will light
the top of an object.

```javascript
const light = new BABYLON.DirectionalLight("DirectionalLight", new BABYLON.Vector3(0, -1, 0), scene);
```

### The Spot Light

A spot light is defined by a position, a direction, an angle, and an exponent. These values define a cone of light starting from the position, emitting toward the direction.

The angle, in radians, defines the size (field of illumination) of the spotlight's conical beam, and the exponent defines how quickly the light decays with distance (reach).

_A simple use of a spot light_

```javascript
const light = new BABYLON.SpotLight("spotLight", new BABYLON.Vector3(0, 30, -10), new BABYLON.Vector3(0, -1, 0), Math.PI / 3, 2, scene);
```

### The Hemispheric Light

A hemispheric light is an easy way to simulate ambient environmental light. A hemispheric light is defined by a direction, usually 'up' toward the sky. However, the full effect is achieved by setting the color properties.

```javascript
const light = new BABYLON.HemisphericLight("HemiLight", new BABYLON.Vector3(0, 1, 0), scene);
```

### The Rectangular Area Light

A rectangular area light is defined by its position, width, and height. It emits light from the resulting surface towards the -Z direction. Even though the RectAreaLight class itself does not have a direction component, it can be attached to a transform node to be rotated and moved around.

```javascript
const light = new BABYLON.RectAreaLight("areaLight", new BABYLON.Vector3(0, 1, 0), 2, 2, scene);
```

One important thing to note is that, due to differences in implementation, StandardMaterial will reflect light based on its "roughness" value (instead of specular power, as with other lights). This difference in behavior is significant, and you should set the correct roughness value in the scene to achieve the desired look.

Also, the current implementation for RectAreaLight does not cast shadows, but we plan to implement this in the future.

### Using emission textures with RectAreaLight

Emission textures can be used as light sources for RectAreaLight by assigning them to the `.emissionTexture` property. However, these textures require pre-processing to work properly.

Pre-processing can be done offline (recommended) or at runtime using `AreaLightTextureTools`. Runtime processing takes several seconds for typical texture sizes (1024 or 2048), so offline processing is preferred for production use. The runtime tool is provided for prototyping and experimentation.

Here's how to use an emission texture at runtime:

```javascript
// AreaLightTextureTools can be created once and reused for processing multiple textures. 
const textureProcessor = new BABYLON.AreaLightTextureTools(engine);

// Create your RectAreaLight
const light = new BABYLON.RectAreaLight("areaLight", new BABYLON.Vector3(0, 1, 0), 2, 2, scene);

// Image that you want to use as emission.
const emissionTexture = new BABYLON.Texture(textureURL, scene);

// Preprocess the texture to get the one that should be used by RectAreaLight
light.emissionTexture = await textureProcessor.processAsync(emissionTexture);
```

We also provide an offline tool that can directly pre-process emission textures: [Babylon Texture Tools](https://babylonjs.com/tools/textures/index.html). By going to the "Area Light" tab, users can drag and drop a PNG into the tool and use the "Render" button to generate the pre-processed texture. The resulting texture can be directly assigned to `light.emissionTexture` without any additional steps.

- [Playground: Area Light with Emission](https://playground.babylonjs.com/#T7FXR8#104) - Area Light using emission texture.


## Color Properties

There are three properties of lights that affect color. Two of these, _diffuse_ and _specular_, apply to all light types; the third, _groundColor_, applies only to a Hemispheric Light.

1. Diffuse gives the basic color to an object;
2. Specular produces a highlight color on an object.

In these playgrounds, see how the specular color (green) is combined with the diffuse color (red) to produce a yellow highlight.

- [Playground: Point Light Example](https://playground.babylonjs.com/#20OAV9) - Simple Example of adding a Point Light to your scene.

- [Playground: Directional Light Example](https://playground.babylonjs.com/#20OAV9#1) - Simple Example of adding a Directional Light to your scene.

- [Playground: Spot Light Example](https://playground.babylonjs.com/#20OAV9#3) - Simple Example of adding a Spot Light to your scene.

- [Playground: Hemispheric Light Example](https://playground.babylonjs.com/#20OAV9#5) - Simple Example of adding a Hemispheric Light to your scene.

- [Playground: Rectangular Area Light Example](https://playground.babylonjs.com/#T7FXR8#20) - Simple Example of adding a Rectangular Area Light to your scene.

For a hemispheric light, the _groundColor_ is the light in the opposite direction from the one specified during creation.
You can think of the _diffuse_ and _specular_ light as coming from the center of the object in the given direction, and the _groundColor_ light as coming from the opposite direction.

- [Playground: Hemispheric Light On 2 Spheres](https://playground.babylonjs.com/#20OAV9#6) - Simple Example of a Hemispheric Light on 2 spheres.

White hemispheric light with a black groundColor is a useful lighting method.

### Intersecting Lights Colors

- [Playground: Intersecting Spot Lights](https://playground.babylonjs.com/#20OAV9#9) - Simple Example of a intersecting spot light colors.

## Limitations

Babylon.js allows you to create and register as many lights as you choose, but note that a single material can only handle a defined number of simultaneous lights (by default, this value is 4, which means the first four enabled lights in the scene's lights list).
You can change this number with this code:

```javascript
const material = new BABYLON.StandardMaterial("mat", scene);
material.maxSimultaneousLights = 6;
```

But beware! By default, all meshes are considered lit by all lights, even when they are not physically lit. Calculating whether a mesh can be lit by a light would be too time-consuming. Also, with more dynamic lights, Babylon.js generates larger shaders, which may not be compatible with low-end devices such as phones or small tablets. In this case, Babylon.js will try to recompile shaders with fewer lights.

- [Playground: 6 Intersecting Point Lights](https://playground.babylonjs.com/#IRVAX#0) - Simple Example with 6 intersecting point lights.

## On, Off or Dimmer

Every light can be switched off using

```javascript
light.setEnabled(false);
```

and switched on with

```javascript
light.setEnabled(true);
```

Want to dim or brighten the light? Then set the _intensity_ property (default value is 1).

```javascript
light0.intensity = 0.5;
light1.intensity = 2.4;
```

For point and spot lights, you can set how far the light reaches using the _range_ property.

```javascript
light.range = 100;
```

## Choosing Meshes to Light

When a light is created, all current meshes will be lit by it. There are two ways to exclude some meshes from being lit.
A mesh can be added to the _excludedMeshes_ array, or the meshes that should not be excluded can be added to the _includedOnlyMeshes_ array. The number of meshes to exclude can help determine which method to use. In the following example, two meshes are excluded from _light0_ and twenty-three from _light1_. Commenting out lines 26 and 27 in turn will show the individual effect.

- [Playground: Example of Excluding Meshes to Light](https://playground.babylonjs.com/#20OAV9#8) - Simple Example of exluding meshes from being lit by a light.

## Lighting Normals

How lights react to a mesh depends on values set for each mesh vertex, called _normals_, shown in the picture below as arrows indicating the direction of the lighting normals. The picture shows two planes and two lights. One light is a spot light and the other is a point light. The front face of each plane is the one you see when the _normals_ point toward you; the back face is the opposite side.

![Elements](https://doc.babylonjs.com/img/how_to/Mesh/normals6.webp)

_A blue back-faced plane and a blue front-faced plane, with a spot light and point light_

As you can see, the lights only affect the front face and not the back face.

## Lightmaps

Complex lighting can be computationally expensive to compute at runtime. To save on computation, lightmaps may be used to store calculated lighting in a texture which will be applied to a given mesh.

```javascript
const lightmap = new BABYLON.Texture("lightmap.png", scene);
const material = new BABYLON.StandardMaterial("material", scene);
material.lightmapTexture = lightmap;
```

Note: To use the texture as a shadow map instead of a lightmap, set the material.useLightmapAsShadowmap field to true.

The way that the scene lights are blended with the lightmap is based on the lightmapMode of the lights in the scene.

```javascript
light.lightmapMode = BABYLON.Light.LIGHTMAP_DEFAULT;
```

This causes the lightmap texture to be blended after the lighting from this light is applied.

```javascript
light.lightmapMode = BABYLON.Light.LIGHTMAP_SPECULAR;
```

This is the same as LIGHTMAP_DEFAULT except only the specular lighting and shadows from the light will be applied.

```javascript
light.lightmapMode = BABYLON.Light.LIGHTMAP_SHADOWSONLY;
```

This is the same as LIGHTMAP_DEFAULT except only the shadows cast from this light will be applied.

- [Playground: Lightmaps Example](https://playground.babylonjs.com/#ULACCM#37) - Simple Example of using lightmaps in your scene.

## Projection Texture

In some cases, it is useful to define the diffuse color of the light (Diffuse gives the basic color to an object) from a texture instead of a constant color. Imagine trying to simulate the light effects inside a cathedral. The light going through the stained glass will be projected onto the ground. The same is true for light coming from a projector or the light effects you see in a disco.

In order to support this feature, you can rely on the `projectionTexture` property of the lights. This is only supported by the **SpotLight** so far.

```javascript
const spotLight = new BABYLON.SpotLight("spot02", new BABYLON.Vector3(30, 40, 30), new BABYLON.Vector3(-1, -2, -1), 1.1, 16, scene);
spotLight.projectionTexture = new BABYLON.Texture("textures/stainedGlass.png", scene);
```

- [Playground: Projection Texture Example](https://playground.babylonjs.com/#CQNGRK) - Simple Example of using projection textures in your scene.

[YouTube video](https://www.youtube.com/watch?v=qqMuuSM7GvI)

In order to control the projection orientation and range, you can also rely on the following properties:

- `projectionTextureLightNear` : near range of the texture projection. If a plane is before this range in light space, there is no texture projection.
- `projectionTextureLightFar` : far range of the texture projection. If a plane is beyond this range in light space, there is no texture projection.
- `projectionTextureUpDirection` : helps define the light space, which is oriented toward the light direction and aligned with the up direction.

The projected information is multiplied against the normal light values to better fit Babylon.js lighting. It also affects only the diffuse value. So, it might be necessary to change the specular color of the light to better fit the scene.

## IES Profile

Starting with Babylon v7.40.0, you can specify an [IES light](https://ieslibrary.com/) profile for your **SpotLight**.

This controls, based on the [IES specification](https://store.ies.org/product/lm-63-19-approved-method-ies-standard-file-format-for-the-electronic-transfer-of-photometric-data-and-related-information/?v=0b3b97fa6688), how the light falloff should be rendered.

To do so, you have to set the `spotLight.iesProfileTexture` to a texture loaded from an `.ies` file.

```
light.iesProfileTexture = new BABYLON.Texture("https://assets.babylonjs.com/meshes/EXT_lights_ies/LightProfile.ies");
```

- [Playground: Projection Texture Example](https://playground.babylonjs.com/#UIAXAU#29) - Simple Example of using an IES profile.
