Options
All
  • Public
  • Public/Protected
  • All
Menu

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

Index

Constructors

  • new SSAOEffect(camera?: Camera, normalBuffer?: Texture, [options]?: { 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 }): SSAOEffect
  • Constructs a new SSAO effect.

    todo

    Move normalBuffer to options.

    Parameters

    • Optional camera: Camera
    • Optional normalBuffer: Texture
    • Optional [options]: { 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.

      • 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

    Returns SSAOEffect

Properties

blendMode: BlendMode

The blend mode of this effect.

defines: Map<string, string>

Preprocessor macro definitions.

Call Effect.setChanged after changing macro definitions.

extensions: Set<WebGLExtension>

WebGL extensions that are required by this effect.

Call Effect.setChanged after adding or removing extensions.

name: string

The name of this effect.

renderer: WebGLRenderer

The renderer.

deprecated
resolution: Resolution
uniforms: Map<string, Uniform<any>>

Shader uniforms.

Call Effect.setChanged after adding or removing uniforms.

Accessors

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

    Returns Color

  • The color of the ambient occlusion. Set to null to disable.

    Parameters

    • arg: Color

    Returns void

  • get depthAwareUpsampling(): boolean
  • set depthAwareUpsampling(arg: boolean): void
  • Indicates whether depth-aware upsampling is enabled.

    Returns boolean

  • Indicates whether depth-aware upsampling is enabled.

    Parameters

    • arg: boolean

    Returns void

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

    deprecated

    Use ssaoMaterial.distanceScaling instead.

    Returns boolean

  • Indicates whether distance-based radius scaling is enabled.

    deprecated

    Use ssaoMaterial.distanceScaling instead.

    Parameters

    • arg: boolean

    Returns void

  • get inputColorSpace(): ColorSpace
  • set inputColorSpace(arg: ColorSpace): void
  • The input color space.

    experimental

    Returns ColorSpace

  • The input color space.

    experimental

    Parameters

    • arg: ColorSpace

    Returns void

  • get intensity(): number
  • set intensity(arg: number): void
  • The intensity.

    Returns number

  • The intensity.

    Parameters

    • arg: number

    Returns void

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

    Returns boolean

  • The luminance influence factor. Range: [0.0, 1.0].

    Parameters

    • value: boolean

    Returns void

  • set mainCamera(arg: Camera): void
  • Sets the main camera.

    Parameters

    • arg: Camera

    Returns void

  • set mainScene(arg: Scene): void
  • Sets the main scene.

    Parameters

    • arg: Scene

    Returns void

  • get normalBuffer(): null | Texture
  • set normalBuffer(value: null | Texture): void
  • Sets the normal buffer.

    Returns null | Texture

  • Sets the normal buffer.

    Parameters

    • value: null | Texture

    Returns void

  • get outputColorSpace(): ColorSpace
  • set outputColorSpace(arg: ColorSpace): void
  • The output color space.

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

    experimental

    Returns ColorSpace

  • The output color space.

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

    experimental

    Parameters

    • arg: ColorSpace

    Returns void

  • get radius(): number
  • set radius(arg: number): void
  • The occlusion sampling radius.

    deprecated

    Use ssaoMaterial.radius instead.

    Returns number

  • The occlusion sampling radius.

    deprecated

    Use ssaoMaterial.radius instead.

    Parameters

    • arg: number

    Returns void

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

    deprecated

    Use ssaoMaterial.rings instead.

    Returns number

  • The amount of spiral turns in the occlusion sampling pattern.

    deprecated

    Use ssaoMaterial.rings instead.

    Parameters

    • arg: number

    Returns void

  • get samples(): number
  • set samples(arg: number): void
  • The amount of occlusion samples per pixel.

    deprecated

    Use ssaoMaterial.samples instead.

    Returns number

  • The amount of occlusion samples per pixel.

    deprecated

    Use ssaoMaterial.samples instead.

    Parameters

    • arg: number

    Returns void

  • get ssaoMaterial(): SSAOMaterial
  • The SSAO material.

    Returns SSAOMaterial

Methods

  • addEventListener<T>(type: T, listener: EventListener<Event<string, unknown>[T], T, SSAOEffect>): void
  • addEventListener<T>(type: T, listener: EventListener<{}, T, SSAOEffect>): 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

  • Type Parameters

    • T extends string

    Parameters

    Returns void

  • dispatchEvent<T>(event: BaseEvent<T> & Event<string, unknown>[T]): 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

  • 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

  • getAttributes(): EffectAttribute
  • Returns the effect attributes.

    Returns EffectAttribute

    The attributes.

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

    deprecated

    Use blendMode instead.

    Returns BlendMode

    The blend mode.

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

    deprecated

    Use color instead.

    Returns Color

    The color.

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

    deprecated

    Use defines instead.

    Returns Map<string, string>

    The extensions.

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

    deprecated

    Use extensions instead.

    Returns Set<WebGLExtension>

    The extensions.

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

    deprecated

    Use name instead.

    Returns string

    The name.

  • Returns the resolution settings.

    deprecated

    Use resolution instead.

    Returns Resolution

    The resolution.

  • getSSAOMaterial(): SSAOMaterial
  • Returns the SSAO material.

    deprecated

    Use ssaoMaterial instead.

    Returns SSAOMaterial

    The material.

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

    deprecated

    Use uniforms instead.

    Returns Map<string, Uniform<any>>

    The extensions.

  • getVertexShader(): string
  • hasEventListener<T>(type: T, listener: EventListener<Event<string, unknown>[T], T, SSAOEffect>): boolean
  • hasEventListener<T>(type: T, listener: EventListener<{}, T, SSAOEffect>): 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

  • Type Parameters

    • T extends string

    Parameters

    Returns boolean

  • initialize(renderer: WebGLRenderer, alpha: boolean, frameBufferType: number): void
  • Performs initialization tasks.

    This method is called when the associated {@link EffectPass} is added to an EffectComposer.

    example

    if(!alpha && frameBufferType === UnsignedByteType) { this.myRenderTarget.texture.format = RGBFormat; }

    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

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

    deprecated

    Use depthAwareUpsampling instead.

    Returns boolean

    Whether depth-aware upsampling is enabled.

  • removeEventListener<T>(type: T, listener: EventListener<Event<string, unknown>[T], T, SSAOEffect>): void
  • removeEventListener<T>(type: T, listener: EventListener<{}, T, SSAOEffect>): 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

  • Type Parameters

    • T extends string

    Parameters

    Returns void

  • setAttributes(attributes: EffectAttribute): void
  • 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

  • setChanged(): void
  • Informs the associated {@link EffectPass} that this effect requires a shader recompilation.

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

    Returns void

  • setColor(value: Color): void
  • Sets the color of the ambient occlusion. Set to null to disable colorization.

    deprecated

    Use color instead.

    Parameters

    • value: Color

      The color.

    Returns void

  • setDepthAwareUpsamplingEnabled(value: boolean): void
  • Enables or disables depth-aware upsampling.

    deprecated

    Use depthAwareUpsampling instead.

    Parameters

    • value: boolean

      Whether depth-aware upsampling should be enabled.

    Returns void

  • setDepthTexture(depthTexture: Texture, depthPacking?: DepthPackingStrategies): 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 {@link EffectPass}.

    Parameters

    • depthTexture: Texture

      A depth texture.

    • Optional depthPacking: DepthPackingStrategies

    Returns void

  • setDistanceCutoff(threshold: number, falloff: number): void
  • Sets the occlusion distance cutoff.

    deprecated

    Use ssaoMaterial instead.

    Parameters

    • threshold: number

      The distance threshold. Range [0.0, 1.0].

    • falloff: number

      The falloff. Range [0.0, 1.0].

    Returns void

  • setFragmentShader(fragmentShader: string): void
  • Sets the fragment shader.

    Parameters

    • fragmentShader: string

      The fragment shader.

    Returns void

  • setProximityCutoff(threshold: number, falloff: number): void
  • Sets the occlusion proximity cutoff.

    deprecated

    Use ssaoMaterial instead.

    Parameters

    • threshold: number

      The proximity threshold. Range [0.0, 1.0].

    • falloff: number

      The falloff. Range [0.0, 1.0].

    Returns void

  • setRenderer(renderer: WebGLRenderer): void
  • Sets the renderer.

    deprecated

    Parameters

    • renderer: WebGLRenderer

      The renderer.

    Returns void

  • setSize(width: number, height: number): void
  • Sets the size.

    Parameters

    • width: number

      The width.

    • height: number

      The height.

    Returns void

  • setVertexShader(vertexShader: string): void
  • Sets the vertex shader.

    Parameters

    • vertexShader: string

      The vertex shader.

    Returns void

  • update(renderer: WebGLRenderer, inputBuffer: WebGLRenderTarget<Texture>, deltaTime?: number): void
  • Updates this effect.

    Parameters

    • renderer: WebGLRenderer

      The renderer.

    • inputBuffer: WebGLRenderTarget<Texture>

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

    • Optional deltaTime: number

    Returns void