Class SSAOEffect

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.

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

Hierarchy (view full)

Effect
- SSAOEffect

Constructors

constructor

new SSAOEffect(camera?, normalBuffer?, options?): SSAOEffect
Constructs a new SSAO effect.
Parameters
- Optionalcamera: Camera
  The main camera.
- OptionalnormalBuffer: Texture
  A texture that contains the scene normals.
- Optionaloptions: {
      bias?: number;
      blendFunction?: BlendFunction;
      color?: Color;
      depthAwareUpsampling?: boolean;
      distanceFalloff?: number;
      distanceScaling?: boolean;
      distanceThreshold?: number;
      fade?: number;
      height?: number;
      intensity?: number;
      luminanceInfluence?: number;
      minRadiusScale?: number;
      normalDepthBuffer?: Texture;
      radius?: number;
      rangeFalloff?: number;
      rangeThreshold?: number;
      resolutionScale?: number;
      resolutionX?: number;
      resolutionY?: number;
      rings?: number;
      samples?: number;
      width?: number;
      worldDistanceFalloff?: number;
      worldDistanceThreshold?: number;
      worldProximityFalloff?: number;
      worldProximityThreshold?: number;
  }
  The options.
  - Optionalbias?: number
    An occlusion bias. Eliminates artifacts caused by depth discontinuities.
  - OptionalblendFunction?: BlendFunction
    The blend function of this effect.
  - Optionalcolor?: Color
    The color of the ambient occlusion.
  - OptionaldepthAwareUpsampling?: boolean
    Enables or disables depth-aware upsampling. Has no effect if WebGL 2 is not supported.
  - OptionaldistanceFalloff?: number
    Deprecated.
  - OptionaldistanceScaling?: boolean
    Deprecated.
  - OptionaldistanceThreshold?: number
    Deprecated.
  - Optionalfade?: number
    Influences the smoothness of the shadows. A lower value results in higher contrast.
  - Optionalheight?: number
    Deprecated. Use resolutionY instead.
  - Optionalintensity?: number
    The intensity of the ambient occlusion.
  - OptionalluminanceInfluence?: number
    Determines how much the luminance of the scene influences the ambient occlusion.
  - OptionalminRadiusScale?: number
    The minimum radius scale.
  - OptionalnormalDepthBuffer?: Texture
    Deprecated.
  - Optionalradius?: number
    The occlusion sampling radius, expressed as a scale relative to the resolution. Range [1e-6, 1.0].
  - OptionalrangeFalloff?: number
    Deprecated.
  - OptionalrangeThreshold?: number
    Deprecated.
  - OptionalresolutionScale?: number
    The resolution scale.
  - OptionalresolutionX?: number
    The horizontal resolution.
  - OptionalresolutionY?: number
    The vertical resolution.
  - Optionalrings?: number
    The amount of spiral turns in the occlusion sampling pattern. Should be a prime number.
  - Optionalsamples?: number
    The amount of samples per pixel. Should not be a multiple of the ring count.
  - Optionalwidth?: number
    Deprecated. Use resolutionX instead.
  - OptionalworldDistanceFalloff?: number
    The world distance falloff. Influences the smoothness of the occlusion cutoff.
  - OptionalworldDistanceThreshold?: number
    The world distance threshold at which the occlusion effect starts to fade out.
  - OptionalworldProximityFalloff?: number
    The world proximity falloff. Influences the smoothness of the proximity cutoff.
  - OptionalworldProximityThreshold?: number
    The world proximity threshold at which the occlusion starts to fade out.
Returns SSAOEffect
Todo
Move normalBuffer to options.

Overrides Effect.constructor

Properties

`Readonly`blendMode

blendMode: BlendMode

The blend mode of this effect.

`Readonly`defines

defines: Map<string, string>

Preprocessor macro definitions.

Call Effect.setChanged after changing macro definitions.

`Readonly`extensions

extensions: Set<WebGLExtension>

WebGL extensions that are required by this effect.

Call Effect.setChanged after adding or removing extensions.

name

name: string

The name of this effect.

`Protected`renderer

renderer: WebGLRenderer

The renderer.

Deprecated

resolution

resolution: Resolution

`Readonly`uniforms

uniforms: Map<string, Uniform<any>>

Shader uniforms.

Call Effect.setChanged after adding or removing uniforms.

Accessors

color

get color(): Color
The color of the ambient occlusion. Set to null to disable.

Returns Color
set color(arg): void
Parameters
- arg: Color
Returns void

depthAwareUpsampling

get depthAwareUpsampling(): boolean
Indicates whether depth-aware upsampling is enabled.

Returns boolean
set depthAwareUpsampling(arg): void
Parameters
- arg: boolean
Returns void

distanceScaling

get distanceScaling(): boolean
Indicates whether distance-based radius scaling is enabled.

Returns boolean
Deprecated
Use ssaoMaterial.distanceScaling instead.
set distanceScaling(arg): void
Parameters
- arg: boolean
Returns void

inputColorSpace

get inputColorSpace(): ColorSpace
Experimental
The input color space.

Returns ColorSpace
Inherited from Effect.inputColorSpace
set inputColorSpace(arg): void
Protected Experimental
Parameters
- arg: ColorSpace
Returns void
Inherited from Effect.inputColorSpace

intensity

get intensity(): number
The intensity.

Returns number
set intensity(arg): void
Parameters
- arg: number
Returns void

luminanceInfluence

get luminanceInfluence(): boolean
The luminance influence factor. Range: [0.0, 1.0].

Returns boolean
set luminanceInfluence(value): void
Parameters
- value: boolean
Returns void

mainCamera

set mainCamera(arg): void
Sets the main camera.
Parameters
- arg: Camera
Returns void
Inherited from Effect.mainCamera

mainScene

set mainScene(arg): void
Sets the main scene.
Parameters
- arg: Scene
Returns void
Inherited from Effect.mainScene

normalBuffer

get normalBuffer(): Texture
Sets the normal buffer.

Returns Texture
set normalBuffer(value): void
Parameters
- value: Texture
Returns void

outputColorSpace

get outputColorSpace(): ColorSpace
Experimental
The output color space.

Should only be changed if this effect converts the input colors to a different color space.

Returns ColorSpace
Inherited from Effect.outputColorSpace
set outputColorSpace(arg): void
Protected Experimental
Parameters
- arg: ColorSpace
Returns void
Inherited from Effect.outputColorSpace

radius

get radius(): number
The occlusion sampling radius.

Returns number
Deprecated
Use ssaoMaterial.radius instead.
set radius(arg): void
Parameters
- arg: number
Returns void

rings

get rings(): number
The amount of spiral turns in the occlusion sampling pattern.

Returns number
Deprecated
Use ssaoMaterial.rings instead.
set rings(arg): void
Parameters
- arg: number
Returns void

samples

get samples(): number
The amount of occlusion samples per pixel.

Returns number
Deprecated
Use ssaoMaterial.samples instead.
set samples(arg): void
Parameters
- arg: number
Returns void

ssaoMaterial

get ssaoMaterial(): SSAOMaterial
The SSAO material.

Returns SSAOMaterial

Methods

addEventListener

addEventListener<T>(type, listener): void
Adds a listener to an event type.
Type Parameters
- T extends keyof Event<string, unknown>
Parameters
- type: T
  The type of event to listen to.
- listener: EventListener<Event<string, unknown>[T], T, SSAOEffect>
  The function that gets called when the event is fired.
Returns void
Inherited from Effect.addEventListener

dispatchEvent

dispatchEvent<T>(event): void
Fire an event type.
Type Parameters
- T extends keyof Event<string, unknown>
Parameters
- event: BaseEvent<T> & Event<string, unknown>[T]
  The event that gets fired.
Returns void
Inherited from Effect.dispatchEvent

dispose

dispose(): void
Performs a shallow search for properties that define a dispose method and deletes them.

The EffectComposer calls this method when it is being destroyed.

Returns void
Inherited from Effect.dispose

getAttributes

getAttributes(): EffectAttribute
Returns the effect attributes.

Returns EffectAttribute
The attributes.

Inherited from Effect.getAttributes

getBlendMode

getBlendMode(): BlendMode
Returns the blend mode.

The result of this effect will be blended with the result of the previous effect using this blend mode.

Returns BlendMode
The blend mode.

Deprecated
Use blendMode instead.

Inherited from Effect.getBlendMode

getColor

getColor(): Color
Returns the color of the ambient occlusion.

Returns Color
The color.

Deprecated
Use color instead.

getDefines

getDefines(): Map<string, string>
Returns the preprocessor macro definitions.

Returns Map<string, string>
The extensions.

Deprecated
Use defines instead.

Inherited from Effect.getDefines

getExtensions

getExtensions(): Set<WebGLExtension>
Returns the WebGL extensions that are required by this effect.

Returns Set<WebGLExtension>
The extensions.

Deprecated
Use extensions instead.

Inherited from Effect.getExtensions

getFragmentShader

getFragmentShader(): string
Returns the fragment shader.

Returns string
The fragment shader.

Inherited from Effect.getFragmentShader

getName

getName(): string
Returns the name of this effect.

Returns string
The name.

Deprecated
Use name instead.

Inherited from Effect.getName

getResolution

getResolution(): Resolution
Returns the resolution settings.

Returns Resolution
The resolution.

Deprecated
Use resolution instead.

getSSAOMaterial

getSSAOMaterial(): SSAOMaterial
Returns the SSAO material.

Returns SSAOMaterial
The material.

Deprecated
Use ssaoMaterial instead.

getUniforms

getUniforms(): Map<string, Uniform<any>>
Returns the uniforms of this effect.

Returns Map<string, Uniform<any>>
The extensions.

Deprecated
Use uniforms instead.

Inherited from Effect.getUniforms

getVertexShader

getVertexShader(): string
Returns the vertex shader.

Returns string
The vertex shader.

Inherited from Effect.getVertexShader

hasEventListener

hasEventListener<T>(type, listener): boolean
Checks if listener is added to an event type.
Type Parameters
- T extends keyof Event<string, unknown>
Parameters
- type: T
  The type of event to listen to.
- listener: EventListener<Event<string, unknown>[T], T, SSAOEffect>
  The function that gets called when the event is fired.
Returns boolean
Inherited from Effect.hasEventListener

initialize

initialize(renderer, alpha, frameBufferType): void
Performs initialization tasks.

This method is called when the associated EffectPass is added to an EffectComposer.
Parameters
- renderer: WebGLRenderer
  The renderer.
- alpha: boolean
  Whether the renderer uses the alpha channel or not.
- frameBufferType: number
  The type of the main frame buffers.
Returns void
Example
```
if(!alpha && frameBufferType === UnsignedByteType) { this.myRenderTarget.texture.format = RGBFormat; }
```
Inherited from Effect.initialize

isDepthAwareUpsamplingEnabled

isDepthAwareUpsamplingEnabled(): boolean
Indicates whether depth-aware upsampling is enabled.

Returns boolean
Whether depth-aware upsampling is enabled.

Deprecated
Use depthAwareUpsampling instead.

removeEventListener

removeEventListener<T>(type, listener): void
Removes a listener from an event type.
Type Parameters
- T extends keyof Event<string, unknown>
Parameters
- type: T
  The type of the listener that gets removed.
- listener: EventListener<Event<string, unknown>[T], T, SSAOEffect>
  The listener function that gets removed.
Returns void
Inherited from Effect.removeEventListener

`Protected`setAttributes

setAttributes(attributes): void
Protected
Sets the effect attributes.

Effects that have the same attributes will be executed in the order in which they were registered. Some attributes imply a higher priority.
Parameters
- attributes: EffectAttribute
  The attributes.
Returns void
Inherited from Effect.setAttributes

`Protected`setChanged

setChanged(): void
Protected
Informs the associated EffectPass that this effect requires a shader recompilation.

Should be called after changing macros or extensions and after adding/removing uniforms.

Returns void
Inherited from Effect.setChanged

setColor

setColor(value): void
Sets the color of the ambient occlusion. Set to null to disable colorization.
Parameters
- value: Color
  The color.
Returns void
Deprecated
Use color instead.

setDepthAwareUpsamplingEnabled

setDepthAwareUpsamplingEnabled(value): void
Enables or disables depth-aware upsampling.
Parameters
- value: boolean
  Whether depth-aware upsampling should be enabled.
Returns void
Deprecated
Use depthAwareUpsampling instead.

setDepthTexture

setDepthTexture(depthTexture, depthPacking?): void
Sets the depth texture.

You may override this method if your effect requires direct access to the depth texture that is bound to the associated EffectPass.
Parameters
- depthTexture: Texture
  A depth texture.
- OptionaldepthPacking: DepthPackingStrategies
  The depth packing.
Returns void
Inherited from Effect.setDepthTexture

setDistanceCutoff

setDistanceCutoff(threshold, falloff): void
Sets the occlusion distance cutoff.
Parameters
- threshold: number
  The distance threshold. Range [0.0, 1.0].
- falloff: number
  The falloff. Range [0.0, 1.0].
Returns void
Deprecated
Use ssaoMaterial instead.

`Protected`setFragmentShader

setFragmentShader(fragmentShader): void
Protected
Sets the fragment shader.
Parameters
- fragmentShader: string
  The fragment shader.
Returns void
Inherited from Effect.setFragmentShader

setProximityCutoff

setProximityCutoff(threshold, falloff): void
Sets the occlusion proximity cutoff.
Parameters
- threshold: number
  The proximity threshold. Range [0.0, 1.0].
- falloff: number
  The falloff. Range [0.0, 1.0].
Returns void
Deprecated
Use ssaoMaterial instead.

setRenderer

setRenderer(renderer): void
Sets the renderer.
Parameters
- renderer: WebGLRenderer
  The renderer.
Returns void
Deprecated
Inherited from Effect.setRenderer

setSize

setSize(width, height): void
Sets the size.
Parameters
- width: number
  The width.
- height: number
  The height.
Returns void
Overrides Effect.setSize

`Protected`setVertexShader

setVertexShader(vertexShader): void
Protected
Sets the vertex shader.
Parameters
- vertexShader: string
  The vertex shader.
Returns void
Inherited from Effect.setVertexShader

update

update(renderer, inputBuffer, deltaTime?): void
Updates this effect.
Parameters
- renderer: WebGLRenderer
  The renderer.
- inputBuffer: WebGLRenderTarget<Texture>
  A frame buffer that contains the result of the previous pass.
- OptionaldeltaTime: number
  The time between the last frame and the current one in seconds.
Returns void
Overrides Effect.update

Class SSAOEffect

Hierarchy (view full)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Optionalbias?: number

OptionalblendFunction?: BlendFunction

Optionalcolor?: Color

OptionaldepthAwareUpsampling?: boolean

OptionaldistanceFalloff?: number

OptionaldistanceScaling?: boolean

OptionaldistanceThreshold?: number

Optionalfade?: number

Optionalheight?: number

Optionalintensity?: number

OptionalluminanceInfluence?: number

OptionalminRadiusScale?: number

OptionalnormalDepthBuffer?: Texture

Optionalradius?: number

OptionalrangeFalloff?: number

OptionalrangeThreshold?: number

OptionalresolutionScale?: number

OptionalresolutionX?: number

OptionalresolutionY?: number

Optionalrings?: number

Optionalsamples?: number

Optionalwidth?: number

OptionalworldDistanceFalloff?: number

OptionalworldDistanceThreshold?: number

OptionalworldProximityFalloff?: number

OptionalworldProximityThreshold?: number

Returns SSAOEffect

Todo

Properties

ReadonlyblendMode

Readonlydefines

Readonlyextensions

name

Protectedrenderer

Deprecated

resolution

Readonlyuniforms

Accessors

color

Returns Color

Parameters

Returns void

depthAwareUpsampling

Returns boolean

Parameters

Returns void

distanceScaling

Returns boolean

Deprecated

Parameters

Returns void

inputColorSpace

Returns ColorSpace

Parameters

Returns void

intensity

Returns number

Parameters

Returns void

luminanceInfluence

Returns boolean

Parameters

Returns void

mainCamera

Parameters

Returns void

mainScene

Parameters

Returns void

normalBuffer

`Optional`bias?: number

`Optional`blendFunction?: BlendFunction

`Optional`color?: Color

`Optional`depthAwareUpsampling?: boolean

`Optional`distanceFalloff?: number

`Optional`distanceScaling?: boolean

`Optional`distanceThreshold?: number

`Optional`fade?: number

`Optional`height?: number

`Optional`intensity?: number

`Optional`luminanceInfluence?: number

`Optional`minRadiusScale?: number

`Optional`normalDepthBuffer?: Texture

`Optional`radius?: number

`Optional`rangeFalloff?: number

`Optional`rangeThreshold?: number

`Optional`resolutionScale?: number

`Optional`resolutionX?: number

`Optional`resolutionY?: number

`Optional`rings?: number

`Optional`samples?: number

`Optional`width?: number

`Optional`worldDistanceFalloff?: number

`Optional`worldDistanceThreshold?: number

`Optional`worldProximityFalloff?: number

`Optional`worldProximityThreshold?: number

`Readonly`blendMode

`Readonly`defines

`Readonly`extensions

`Protected`renderer

`Readonly`uniforms