Home Reference Source
import {SSAOEffect} from 'postprocessing'
public class | source

SSAOEffect

Extends:

three~EventDispatcherEffect → SSAOEffect

Indirect Implements:

A Screen Space Ambient Occlusion (SSAO) effect.

For high quality visuals use two SSAO effect instances in a row with different radii, one for rough AO and one for fine details.

This effect supports depth-aware upsampling and should be rendered at a lower resolution. The resolution should match that of the downsampled normals and depth. If you intend to render SSAO at full resolution, do not provide a downsampled normalDepthBuffer and make sure to disable depthAwareUpsampling.

It's recommended to specify a relative render resolution using the resolutionScale constructor parameter to avoid undesired sampling patterns.

Based on "Scalable Ambient Obscurance" by Morgan McGuire et al. and "Depth-aware upsampling experiments" by Eleni Maria Stea: https://research.nvidia.com/publication/scalable-ambient-obscurance https://eleni.mutantstargoat.com/hikiko/on-depth-aware-upsampling

The view position calculation is based on a shader by Norbert Nopper: https://github.com/McNopper/OpenGL/blob/master/Example28/shader/ssao.frag.glsl

Constructor Summary

Public Constructor
public

constructor(camera: Camera, normalBuffer: Texture, options: Object)

Constructs a new SSAO effect.

Member Summary

Public Members
public get

color: Color

The color of the ambient occlusion.

public set

color: Color

Sets the color of the ambient occlusion.

public get

Indicates whether depth-aware upsampling is enabled.

public set

Enables or disables depth-aware upsampling.

public get

Indicates whether distance-based radius scaling is enabled.

public set

Enables or disables distance-based radius scaling.

public get

The occlusion sampling radius.

public set

Sets the occlusion sampling radius.

public

The resolution of this effect.

public get

The amount of spiral turns in the occlusion sampling pattern.

public set

Sets the amount of spiral turns in the occlusion sampling pattern.

public get

The amount of occlusion samples per pixel.

public set

Sets the amount of occlusion samples per pixel.

public get

The SSAO material.

Method Summary

Public Methods
public

setDepthTexture(depthTexture: Texture, depthPacking: Number)

Sets the depth texture.

public

setDistanceCutoff(threshold: Number, falloff: Number)

Sets the occlusion distance cutoff.

public

setProximityCutoff(threshold: Number, falloff: Number)

Sets the occlusion proximity cutoff.

public

setSize(width: Number, height: Number)

Updates the camera projection matrix uniforms and the size of internal render targets.

public

update(renderer: WebGLRenderer, inputBuffer: WebGLRenderTarget, deltaTime: Number)

Updates this effect.

Inherited Summary

From class Effect
public

The blend mode of this effect.

public

Preprocessor macro definitions.

public

WebGL extensions that are required by this effect.

public

The name of this effect.

public

uniforms: Map<String, Uniform>

Shader uniforms.

public

Performs a shallow search for properties that define a dispose method and deletes them.

public

Returns the effect attributes.

public

Returns the fragment shader.

public

Returns the vertex shader.

public

initialize(renderer: WebGLRenderer, alpha: Boolean, frameBufferType: Number)

Performs initialization tasks.

public

setDepthTexture(depthTexture: Texture, depthPacking: Number)

Sets the depth texture.

public

setSize(width: Number, height: Number)

Updates the size of this effect.

public

update(renderer: WebGLRenderer, inputBuffer: WebGLRenderTarget, deltaTime: Number)

Updates the effect by performing supporting operations.

protected

Sets the effect attributes.

protected

Informs the associated EffectPass that this effect has changed in a way that requires a shader recompilation.

protected

setFragmentShader(fragmentShader: String)

Sets the fragment shader.

protected

setVertexShader(vertexShader: String)

Sets the vertex shader.

Public Constructors

public constructor(camera: Camera, normalBuffer: Texture, options: Object) source

Constructs a new SSAO effect.

Override:

Effect#constructor

Params:

NameTypeAttributeDescription
camera Camera

The main camera.

normalBuffer Texture

A texture that contains the scene normals. May be null if a normalDepthBuffer is provided. See NormalPass.

options Object
  • optional

The options.

options.blendFunction BlendFunction
  • optional
  • default: BlendFunction.MULTIPLY

The blend function of this effect.

options.distanceScaling Boolean
  • optional
  • default: true

Enables or disables distance-based radius scaling.

options.depthAwareUpsampling Boolean
  • optional
  • default: true

Enables or disables depth-aware upsampling. Has no effect if WebGL 2 is not supported.

options.normalDepthBuffer Texture
  • optional
  • default: null

A texture that contains downsampled scene normals and depth. See DepthDownsamplingPass.

options.samples Number
  • optional
  • default: 9

The amount of samples per pixel. Should not be a multiple of the ring count.

options.rings Number
  • optional
  • default: 7

The amount of spiral turns in the occlusion sampling pattern. Should be a prime number.

options.distanceThreshold Number
  • optional
  • default: 0.97

A global distance threshold at which the occlusion effect starts to fade out. Range [0.0, 1.0].

options.distanceFalloff Number
  • optional
  • default: 0.03

The distance falloff. Influences the smoothness of the overall occlusion cutoff. Range [0.0, 1.0].

options.rangeThreshold Number
  • optional
  • default: 0.0005

A local occlusion range threshold at which the occlusion starts to fade out. Range [0.0, 1.0].

options.rangeFalloff Number
  • optional
  • default: 0.001

The occlusion range falloff. Influences the smoothness of the proximity cutoff. Range [0.0, 1.0].

options.minRadiusScale Number
  • optional
  • default: 0.33

The minimum radius scale. Has no effect if distance scaling is disabled.

options.luminanceInfluence Number
  • optional
  • default: 0.7

Determines how much the luminance of the scene influences the ambient occlusion.

options.radius Number
  • optional
  • default: 0.1825

The occlusion sampling radius, expressed as a resolution independent scale. Range [1e-6, 1.0].

options.intensity Number
  • optional
  • default: 1.0

The intensity of the ambient occlusion.

options.bias Number
  • optional
  • default: 0.025

An occlusion bias. Eliminates artifacts caused by depth discontinuities.

options.fade Number
  • optional
  • default: 0.01

Influences the smoothness of the shadows. A lower value results in higher contrast.

options.color Color
  • optional
  • default: null

The color of the ambient occlusion.

options.resolutionScale Number
  • optional
  • default: 1.0

The resolution scale.

options.width Number
  • optional
  • default: Resizer.AUTO_SIZE

The render width.

options.height Number
  • optional
  • default: Resizer.AUTO_SIZE

The render height.

TODO:

  • Move normalBuffer to options.

Public Members

public get color: Color source

The color of the ambient occlusion.

public set color: Color source

Sets the color of the ambient occlusion.

Set to null to disable colorization.

public get depthAwareUpsampling: Boolean source

Indicates whether depth-aware upsampling is enabled.

public set depthAwareUpsampling: Boolean source

Enables or disables depth-aware upsampling.

public get distanceScaling: Boolean source

Indicates whether distance-based radius scaling is enabled.

public set distanceScaling: Boolean source

Enables or disables distance-based radius scaling.

public get radius: Number source

The occlusion sampling radius.

public set radius: Number source

Sets the occlusion sampling radius. Range [1e-6, 1.0].

public resolution: Resizer source

The resolution of this effect.

public get rings: Number source

The amount of spiral turns in the occlusion sampling pattern.

public set rings: Number source

Sets the amount of spiral turns in the occlusion sampling pattern.

public get samples: Number source

The amount of occlusion samples per pixel.

public set samples: Number source

Sets the amount of occlusion samples per pixel.

public get ssaoMaterial: SSAOMaterial source

The SSAO material.

Public Methods

public setDepthTexture(depthTexture: Texture, depthPacking: Number) source

Sets the depth texture.

Override:

Effect#setDepthTexture

Params:

NameTypeAttributeDescription
depthTexture Texture

A depth texture.

depthPacking Number
  • optional
  • default: BasicDepthPacking

The depth packing.

public setDistanceCutoff(threshold: Number, falloff: Number) source

Sets the occlusion distance cutoff.

Params:

NameTypeAttributeDescription
threshold Number

The distance threshold. Range [0.0, 1.0].

falloff Number

The falloff. Range [0.0, 1.0].

public setProximityCutoff(threshold: Number, falloff: Number) source

Sets the occlusion proximity cutoff.

Params:

NameTypeAttributeDescription
threshold Number

The range threshold. Range [0.0, 1.0].

falloff Number

The falloff. Range [0.0, 1.0].

public setSize(width: Number, height: Number) source

Updates the camera projection matrix uniforms and the size of internal render targets.

Override:

Effect#setSize

Params:

NameTypeAttributeDescription
width Number

The width.

height Number

The height.

public update(renderer: WebGLRenderer, inputBuffer: WebGLRenderTarget, deltaTime: Number) source

Updates this effect.

Override:

Effect#update

Params:

NameTypeAttributeDescription
renderer WebGLRenderer

The renderer.

inputBuffer WebGLRenderTarget

A frame buffer that contains the result of the previous pass.

deltaTime Number
  • optional

The time between the last frame and the current one in seconds.