# Layer

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/scene/layer.js#L93

A Layer represents a renderable subset of the scene. It can contain a list of mesh instances,
lights and cameras, their render settings and also defines custom callbacks before, after or
during rendering. Layers are organized inside [LayerComposition](https://api.playcanvas.com/engine/classes/LayerComposition.md) in a desired order.

A mesh instance is drawn through the layers it belongs to, and a camera draws only the layers
listed in [CameraComponent#layers](https://api.playcanvas.com/engine/classes/CameraComponent.md#layers). Components place their mesh instances by layer id, for
example through [RenderComponent#layers](https://api.playcanvas.com/engine/classes/RenderComponent.md#layers), and lights through [LightComponent#layers](https://api.playcanvas.com/engine/classes/LightComponent.md#layers);
mesh instances you create yourself go in with [addMeshInstances](https://api.playcanvas.com/engine/classes/Layer.md#addmeshinstances) and out with
[removeMeshInstances](https://api.playcanvas.com/engine/classes/Layer.md#removemeshinstances).

The application creates five layers, reachable by id from [Scene#layers](https://api.playcanvas.com/engine/classes/Scene.md#layers):
[LAYERID_WORLD](https://api.playcanvas.com/engine/variables/LAYERID_WORLD.md) for the scene itself, [LAYERID_DEPTH](https://api.playcanvas.com/engine/variables/LAYERID_DEPTH.md), [LAYERID_SKYBOX](https://api.playcanvas.com/engine/variables/LAYERID_SKYBOX.md),
[LAYERID_IMMEDIATE](https://api.playcanvas.com/engine/variables/LAYERID_IMMEDIATE.md) for debug drawing and [LAYERID_UI](https://api.playcanvas.com/engine/variables/LAYERID_UI.md). Within a layer, opaque and
transparent mesh instances are drawn as two separate parts, ordered by [opaqueSortMode](https://api.playcanvas.com/engine/classes/Layer.md#opaquesortmode)
and [transparentSortMode](https://api.playcanvas.com/engine/classes/Layer.md#transparentsortmode), and the composition decides where each part falls in the frame.
Set [enabled](https://api.playcanvas.com/engine/classes/Layer.md#enabled) to false to skip a layer entirely, and use [onEnable](https://api.playcanvas.com/engine/classes/Layer.md#onenable) and
[onDisable](https://api.playcanvas.com/engine/classes/Layer.md#ondisable) to react to that.

**Example**

```ts
// Draw a set of mesh instances in a layer of their own, right after the world's opaque objects
const layers = app.scene.layers;
const layer = new Layer({ name: 'Overlay' });
const world = layers.getLayerById(LAYERID_WORLD);
layers.insert(layer, layers.getOpaqueIndex(world) + 1);
layer.addMeshInstances(meshInstances);
```

## Constructors

### constructor

```ts
new Layer(options?: any)
```

Create a new Layer instance.

**Parameters**

- `options` (`any`, optional, default `{}`): Object for passing optional arguments. These arguments are the
  same as properties of the Layer.

## Properties

### id

```ts
id: number
```

A unique ID of the layer. Layer IDs are stored inside [ModelComponent#layers](https://api.playcanvas.com/engine/classes/ModelComponent.md#layers),
[RenderComponent#layers](https://api.playcanvas.com/engine/classes/RenderComponent.md#layers), [CameraComponent#layers](https://api.playcanvas.com/engine/classes/CameraComponent.md#layers),
[LightComponent#layers](https://api.playcanvas.com/engine/classes/LightComponent.md#layers) and [ElementComponent#layers](https://api.playcanvas.com/engine/classes/ElementComponent.md#layers) instead of names.
Can be used in [LayerComposition#getLayerById](https://api.playcanvas.com/engine/classes/LayerComposition.md#getlayerbyid).

### name

```ts
name: string
```

Name of the layer. Can be used in [LayerComposition#getLayerByName](https://api.playcanvas.com/engine/classes/LayerComposition.md#getlayerbyname).

### onDisable

```ts
onDisable: Function
```

Custom function that is called after the layer has been disabled. This happens when:

- [enabled](https://api.playcanvas.com/engine/classes/Layer.md#enabled) was changed from true to false
- `decrementCounter` was called and set the counter to zero.

### onEnable

```ts
onEnable: Function
```

Custom function that is called after the layer has been enabled. This happens when:

- The layer is created with [enabled](https://api.playcanvas.com/engine/classes/Layer.md#enabled) set to true (which is the default value).
- [enabled](https://api.playcanvas.com/engine/classes/Layer.md#enabled) was changed from false to true

### opaqueSortMode

```ts
opaqueSortMode: number = SORTMODE_MATERIALMESH
```

Defines the method used for sorting opaque (that is, not semi-transparent) mesh
instances before rendering. Can be:

- [SORTMODE_NONE](https://api.playcanvas.com/engine/variables/SORTMODE_NONE.md)
- [SORTMODE_MANUAL](https://api.playcanvas.com/engine/variables/SORTMODE_MANUAL.md)
- [SORTMODE_MATERIALMESH](https://api.playcanvas.com/engine/variables/SORTMODE_MATERIALMESH.md)
- [SORTMODE_BACK2FRONT](https://api.playcanvas.com/engine/variables/SORTMODE_BACK2FRONT.md)
- [SORTMODE_FRONT2BACK](https://api.playcanvas.com/engine/variables/SORTMODE_FRONT2BACK.md)

Defaults to [SORTMODE_MATERIALMESH](https://api.playcanvas.com/engine/variables/SORTMODE_MATERIALMESH.md).

### transparentSortMode

```ts
transparentSortMode: number = SORTMODE_BACK2FRONT
```

Defines the method used for sorting semi-transparent mesh instances before rendering. Can be:

- [SORTMODE_NONE](https://api.playcanvas.com/engine/variables/SORTMODE_NONE.md)
- [SORTMODE_MANUAL](https://api.playcanvas.com/engine/variables/SORTMODE_MANUAL.md)
- [SORTMODE_MATERIALMESH](https://api.playcanvas.com/engine/variables/SORTMODE_MATERIALMESH.md)
- [SORTMODE_BACK2FRONT](https://api.playcanvas.com/engine/variables/SORTMODE_BACK2FRONT.md)
- [SORTMODE_FRONT2BACK](https://api.playcanvas.com/engine/variables/SORTMODE_FRONT2BACK.md)

Defaults to [SORTMODE_BACK2FRONT](https://api.playcanvas.com/engine/variables/SORTMODE_BACK2FRONT.md).

## Accessors

### clearColorBuffer

```ts
get clearColorBuffer(): boolean
set clearColorBuffer(val: boolean)
```

Gets whether the camera will clear the color buffer when it renders this layer.

### clearDepthBuffer

```ts
get clearDepthBuffer(): boolean
set clearDepthBuffer(val: boolean)
```

Gets whether the camera will clear the depth buffer when it renders this layer.

### clearStencilBuffer

```ts
get clearStencilBuffer(): boolean
set clearStencilBuffer(val: boolean)
```

Gets whether the camera will clear the stencil buffer when it renders this layer.

### enabled

```ts
get enabled(): boolean
set enabled(val: boolean)
```

Gets the enabled state of the layer.

## Methods

### addCamera

```ts
addCamera(camera: CameraComponent): void
```

Adds a camera to this layer.

**Parameters**

- `camera` ([`CameraComponent`](https://api.playcanvas.com/engine/classes/CameraComponent.md)): A [CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md).

### addLight

```ts
addLight(light: LightComponent): void
```

Adds a light to this layer.

**Parameters**

- `light` ([`LightComponent`](https://api.playcanvas.com/engine/classes/LightComponent.md)): A [LightComponent](https://api.playcanvas.com/engine/classes/LightComponent.md).

### addMeshInstances

```ts
addMeshInstances(meshInstances: MeshInstance[], skipShadowCasters?: boolean): void
```

Adds an array of mesh instances to this layer.

**Parameters**

- `meshInstances` ([`MeshInstance`](https://api.playcanvas.com/engine/classes/MeshInstance.md)`[]`): Array of [MeshInstance](https://api.playcanvas.com/engine/classes/MeshInstance.md).
- `skipShadowCasters` (`boolean`, optional): Set it to true if you don't want these mesh instances
  to cast shadows in this layer. Defaults to false.

### addShadowCasters

```ts
addShadowCasters(meshInstances: MeshInstance[]): void
```

Adds an array of mesh instances to this layer, but only as shadow casters (they will not be
rendered anywhere, but only cast shadows on other objects).

**Parameters**

- `meshInstances` ([`MeshInstance`](https://api.playcanvas.com/engine/classes/MeshInstance.md)`[]`): Array of [MeshInstance](https://api.playcanvas.com/engine/classes/MeshInstance.md).

### clearCameras

```ts
clearCameras(): void
```

Removes all cameras from this layer.

### clearLights

```ts
clearLights(): void
```

Removes all lights from this layer.

### clearMeshInstances

```ts
clearMeshInstances(skipShadowCasters?: boolean): void
```

Removes all mesh instances from this layer.

**Parameters**

- `skipShadowCasters` (`boolean`, optional, default `false`): Set it to true if you want to continue the existing mesh
  instances to cast shadows. Defaults to false, which removes shadow casters as well.

### removeCamera

```ts
removeCamera(camera: CameraComponent): void
```

Removes a camera from this layer.

**Parameters**

- `camera` ([`CameraComponent`](https://api.playcanvas.com/engine/classes/CameraComponent.md)): A [CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md).

### removeLight

```ts
removeLight(light: LightComponent): void
```

Removes a light from this layer.

**Parameters**

- `light` ([`LightComponent`](https://api.playcanvas.com/engine/classes/LightComponent.md)): A [LightComponent](https://api.playcanvas.com/engine/classes/LightComponent.md).

### removeMeshInstances

```ts
removeMeshInstances(meshInstances: MeshInstance[], skipShadowCasters?: boolean): void
```

Removes multiple mesh instances from this layer.

**Parameters**

- `meshInstances` ([`MeshInstance`](https://api.playcanvas.com/engine/classes/MeshInstance.md)`[]`): Array of [MeshInstance](https://api.playcanvas.com/engine/classes/MeshInstance.md). If they were added to
  this layer, they will be removed.
- `skipShadowCasters` (`boolean`, optional): Set it to true if you want to still cast shadows from
  removed mesh instances or if they never did cast shadows before. Defaults to false.

### removeShadowCasters

```ts
removeShadowCasters(meshInstances: MeshInstance[]): void
```

Removes multiple mesh instances from the shadow casters list of this layer, meaning they
will stop casting shadows.

**Parameters**

- `meshInstances` ([`MeshInstance`](https://api.playcanvas.com/engine/classes/MeshInstance.md)`[]`): Array of [MeshInstance](https://api.playcanvas.com/engine/classes/MeshInstance.md). If they were added to
  this layer, they will be removed.