Skip to main content

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 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:

To inspect captured depth on screen, use TextureRenderer.sceneDepth.

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.

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:

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:

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 documentation.

CameraFrame Integration​

When using CameraFrame for HDR post-processing, you can request depth and color maps through the 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 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 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.
// 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
GrabPass
  • GroundFog demonstrates the use of the depth buffer: GroundFog
GroundFog
  • Dispersion demonstrates refraction and chromatic dispersion using the scene color texture: Dispersion
Dispersion