# Depth Layer

Some rendering techniques require access to the depth or the color buffer of the scene for a specific camera. The Depth Layer is a special layer, which can be added to the `layers` property of a camera. The [`order`](https://developer.playcanvas.com/user-manual/graphics/layers.md#choosing-the-layer-order) of the layers defines at which point during the rendering, the depth or the color buffer is captured. The captured buffers can then be used in the following layers of the camera.

Typically, those buffers are captured after all opaque layers are rendered and can be used in following transparent layers or post-processing.

Additionally, to capture these buffers, the capture needs to be enabled on a CameraComponent from a script:

- [```requestSceneColorMap```](https://api.playcanvas.com/engine/classes/CameraComponent.html#requestscenecolormap) to request a color map
- [```requestSceneDepthMap```](https://api.playcanvas.com/engine/classes/CameraComponent.html#requestscenedepthmap) to request a depth map

To inspect captured depth on screen, use [TextureRenderer.sceneDepth](https://developer.playcanvas.com/user-manual/graphics/debug-drawing.md#scene-depth).

## Buffer access

To access one of these buffers in the shader as a texture, these are the uniform names to be used:

- for the color map: `uSceneColorMap`
- for the depth map: `uSceneDepthMap`

Compute shaders do not use these uniforms. They access the maps of a camera through the compute instance instead, see [Scene Depth and Color Maps](https://developer.playcanvas.com/user-manual/graphics/shaders/compute-shaders.md#scene-depth-and-color-maps).

## Color Space Handling

When using `uSceneColorMap`, it's important to handle color space correctly. The scene color texture contains either gamma-corrected values (when rendering LDR to a non-sRGB target) or linear values (when using HDR rendering with CameraFrame).

### SCENE_COLORMAP_GAMMA Define

The engine automatically provides a `SCENE_COLORMAP_GAMMA` shader define when the scene color map contains gamma-corrected values that need to be converted to linear space. This typically occurs during LDR rendering when the camera outputs gamma-corrected colors to a standard (non-sRGB) render target.

**GLSL Example:**

```glsl
vec3 sceneColor = texture2DLod(uSceneColorMap, uv, 0.0).rgb;

#ifdef SCENE_COLORMAP_GAMMA
// Convert from gamma to linear space
sceneColor = decodeGamma(sceneColor);
#endif

// Now sceneColor is in linear space for lighting calculations
```

**WGSL Example:**

```wgsl
var sceneColor: vec3f = textureSampleLevel(uSceneColorMap, uSceneColorMapSampler, uv, 0.0).rgb;

#ifdef SCENE_COLORMAP_GAMMA
// Convert from gamma to linear space
sceneColor = decodeGamma3(sceneColor);
#endif

// Now sceneColor is in linear space for lighting calculations
```

The `decodeGamma()` and `decodeGamma3()` functions are built-in utility functions that perform the gamma-to-linear conversion using the standard gamma 2.2 curve.

For more information on linear workflow and color space handling, see the [Linear Workflow](https://developer.playcanvas.com/user-manual/graphics/linear-workflow.md) documentation.

## CameraFrame Integration

When using [`CameraFrame`](https://developer.playcanvas.com/user-manual/graphics/posteffects/cameraframe.md) for HDR post-processing, you can request depth and color maps through the [`rendering`](https://api.playcanvas.com/engine/classes/CameraFrame.html#rendering) settings:

- **Color Map**: Set `cameraFrame.rendering.sceneColorMap = true` to enable access to `uSceneColorMap` (e.g., for refraction or custom post-processing effects)
- **Depth Map**: Set `cameraFrame.rendering.sceneDepthMap = true` to enable access to `uSceneDepthMap` (e.g., for depth-dependent effects like custom fog or edge detection)

The color map in CameraFrame contains linear HDR values (no gamma correction needed), so the `SCENE_COLORMAP_GAMMA` define will not be set. This ensures consistent color space handling across different rendering configurations.

## Color map mipmaps

The color map has mipmaps, which materials with rough refraction sample to blur what is behind them. A custom shader selects the mip level with `texture2DLod` in GLSL, or `textureSampleLevel` in WGSL. Two properties of the camera component control the mipmaps, of the color map captured by the Depth layer as well as by CameraFrame:

- [`sceneColorMapMipmapFilter`](https://api.playcanvas.com/engine/classes/CameraComponent.html#scenecolormapmipmapfilter) selects the filter generating the mipmaps. The default `MIPMAPFILTER_BOX` averages blocks of texels, which show as blocks that flicker in a strongly blurred refraction. `MIPMAPFILTER_GAUSSIAN` blurs it smoothly, at a higher cost of generating the mipmaps.
- [`sceneColorMapMipmaps`](https://api.playcanvas.com/engine/classes/CameraComponent.html#scenecolormapmipmaps) set to `false` captures the color map without mipmaps. Refraction is then always sharp, which suits clear glass or a heat haze, and this saves generating the mipmaps each frame and about a third of the memory of the color map.

```javascript
// a smooth blur of rough refraction
cameraEntity.camera.sceneColorMapMipmapFilter = MIPMAPFILTER_GAUSSIAN;

// or, where only sharp refraction is needed
cameraEntity.camera.sceneColorMapMipmaps = false;
```

## Examples

These engine examples demonstrate the rendering of both the depth and the color map, and also custom shaders allowing their use:

- GrabPass demonstrates the use of the color buffer by frosted glass, which samples its blurred mip levels, and compares the box and Gaussian mipmap filters: `GrabPass`

[Live example: GrabPass](https://playcanvas.com/examples/#/shaders/grab-pass) ([source](https://github.com/playcanvas/engine/blob/main/examples/src/examples/shaders/grab-pass/example.mjs))

- GroundFog demonstrates the use of the depth buffer: `GroundFog`

[Live example: GroundFog](https://playcanvas.com/examples/#/shaders/ground-fog) ([source](https://github.com/playcanvas/engine/blob/main/examples/src/examples/shaders/ground-fog/example.mjs))

- Dispersion demonstrates refraction and chromatic dispersion using the scene color texture: `Dispersion`

[Live example: Dispersion](https://playcanvas.com/examples/#/materials/dispersion) ([source](https://github.com/playcanvas/engine/blob/main/examples/src/examples/materials/dispersion/example.mjs))