# LayerComposition

Class · extends [`EventHandler`](https://api.playcanvas.com/engine/classes/EventHandler.md) · category: Graphics

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/scene/composition/layer-composition.js#L41

Layer Composition is a collection of [Layer](https://api.playcanvas.com/engine/classes/Layer.md) that is fed to [Scene#layers](https://api.playcanvas.com/engine/classes/Scene.md#layers) to define
rendering order.

Each layer is rendered as two parts, its opaque mesh instances and its transparent ones, and
[layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist) holds the sequence of parts in the order they are drawn. [push](https://api.playcanvas.com/engine/classes/LayerComposition.md#push) and
[insert](https://api.playcanvas.com/engine/classes/LayerComposition.md#insert) add both parts of a layer together, while [pushOpaque](https://api.playcanvas.com/engine/classes/LayerComposition.md#pushopaque),
[pushTransparent](https://api.playcanvas.com/engine/classes/LayerComposition.md#pushtransparent), [insertOpaque](https://api.playcanvas.com/engine/classes/LayerComposition.md#insertopaque) and [insertTransparent](https://api.playcanvas.com/engine/classes/LayerComposition.md#inserttransparent) place one part at a
time, which is how the default composition places the depth and skybox layers between the world's
opaque and transparent parts. Look layers up with [getLayerById](https://api.playcanvas.com/engine/classes/LayerComposition.md#getlayerbyid) and
[getLayerByName](https://api.playcanvas.com/engine/classes/LayerComposition.md#getlayerbyname), find where a part sits with [getOpaqueIndex](https://api.playcanvas.com/engine/classes/LayerComposition.md#getopaqueindex) and
[getTransparentIndex](https://api.playcanvas.com/engine/classes/LayerComposition.md#gettransparentindex), and take a layer out with [remove](https://api.playcanvas.com/engine/classes/LayerComposition.md#remove). The composition fires
`add` and `remove` as layers come and go.

The composition the application creates ends with the UI layer, so a pushed layer renders after
the UI and outside the range a camera's post-processing applies to. To render inside that range,
insert at an index taken from [getOpaqueIndex](https://api.playcanvas.com/engine/classes/LayerComposition.md#getopaqueindex) or [getTransparentIndex](https://api.playcanvas.com/engine/classes/LayerComposition.md#gettransparentindex).

**Example**

```ts
// Draw decals right after the world's opaque objects and before its transparent ones
const layers = app.scene.layers;
const world = layers.getLayerById(LAYERID_WORLD);
const decals = new Layer({ name: 'Decals' });
layers.insertOpaque(decals, layers.getOpaqueIndex(world) + 1);
```

## Constructors

### constructor

```ts
new LayerComposition(name?: string)
```

Create a new layer composition.

**Parameters**

- `name` (`string`, optional, default `'Untitled'`): Optional non-unique name of the layer composition. Defaults to
  "Untitled" if not specified.

## Properties

### layerList

```ts
layerList: Layer[] = []
```

A read-only array of [Layer](https://api.playcanvas.com/engine/classes/Layer.md) sorted in the order they will be rendered.

### subLayerEnabled

```ts
subLayerEnabled: boolean[] = []
```

A read-only array of boolean values, matching [layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist). True means the
layer is rendered, false means it's skipped.

## Methods

### getLayerById

```ts
getLayerById(id: number): Layer | null
```

Finds a layer inside this composition by its ID. Null is returned, if nothing is found.

**Parameters**

- `id` (`number`): An ID of the layer to find.

**Returns** [`Layer`](https://api.playcanvas.com/engine/classes/Layer.md) `| null`: The layer corresponding to the specified ID. Returns null if layer is
not found.

### getLayerByName

```ts
getLayerByName(name: string): Layer | null
```

Finds a layer inside this composition by its name. Null is returned, if nothing is found.

**Parameters**

- `name` (`string`): The name of the layer to find.

**Returns** [`Layer`](https://api.playcanvas.com/engine/classes/Layer.md) `| null`: The layer corresponding to the specified name. Returns null if layer
is not found.

### getOpaqueIndex

```ts
getOpaqueIndex(layer: Layer): number
```

Gets index of the opaque part of the supplied layer in the [layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to find index of.

**Returns** `number`: The index of the opaque part of the specified layer, or -1 if it is not
part of the composition.

### getTransparentIndex

```ts
getTransparentIndex(layer: Layer): number
```

Gets index of the semi-transparent part of the supplied layer in the [layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to find index of.

**Returns** `number`: The index of the semi-transparent part of the specified layer, or -1 if it
is not part of the composition.

### insert

```ts
insert(layer: Layer, index: number): void
```

Inserts a layer (both opaque and semi-transparent parts) at the chosen index in the
[layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to add.
- `index` (`number`): Insertion position.

### insertOpaque

```ts
insertOpaque(layer: Layer, index: number): void
```

Inserts an opaque part of the layer (non semi-transparent mesh instances) at the chosen
index in the [layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to add.
- `index` (`number`): Insertion position.

### insertTransparent

```ts
insertTransparent(layer: Layer, index: number): void
```

Inserts a semi-transparent part of the layer at the chosen index in the [layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to add.
- `index` (`number`): Insertion position.

### push

```ts
push(layer: Layer): void
```

Adds a layer (both opaque and semi-transparent parts) to the end of the [layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

The default composition ends with the UI layer, so a layer pushed here renders after the UI
and after the last layer a camera's post-processing applies to. To place a layer inside the
post-processed range instead, use [LayerComposition#insert](https://api.playcanvas.com/engine/classes/LayerComposition.md#insert) with an index from
[LayerComposition#getOpaqueIndex](https://api.playcanvas.com/engine/classes/LayerComposition.md#getopaqueindex).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to add.

### pushOpaque

```ts
pushOpaque(layer: Layer): void
```

Adds part of the layer with opaque (non semi-transparent) objects to the end of the
[layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to add.

### pushTransparent

```ts
pushTransparent(layer: Layer): void
```

Adds part of the layer with semi-transparent objects to the end of the [layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to add.

### remove

```ts
remove(layer: Layer): void
```

Removes a layer (both opaque and semi-transparent parts) from [layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to remove.

### removeOpaque

```ts
removeOpaque(layer: Layer): void
```

Removes an opaque part of the layer (non semi-transparent mesh instances) from
[layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to remove.

### removeTransparent

```ts
removeTransparent(layer: Layer): void
```

Removes a transparent part of the layer from [layerList](https://api.playcanvas.com/engine/classes/LayerComposition.md#layerlist).

**Parameters**

- `layer` ([`Layer`](https://api.playcanvas.com/engine/classes/Layer.md)): A [Layer](https://api.playcanvas.com/engine/classes/Layer.md) to remove.

## Inherited from [EventHandler](https://api.playcanvas.com/engine/classes/EventHandler.md)

- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`