API Reference > imodeljs-frontend > Rendering > ScreenSpaceEffectBuilder

ScreenSpaceEffectBuilder Interface

An interface used to construct and register with the IModelApp.renderSystem a custom screen-space effect. Screen-space effects take as input the image rendered by a Viewport, as a WebGL texture, and execute a shader program to modify the image. Any number of screen-space effects can be registered, but each must have a unique name. Each Viewport has an ordered list of effects to be applied to it.

Each time a Viewport's contents are rendered, the RenderSystem does the following:

  • Render Viewport's contents to a texture.
  • For each effect name in Viewport.screenSpaceEffects:
    • Look up the corresponding registered effect.
    • If `shouldApply is defined and returns false, skip the effect. Otherwise:
    • For each Uniform defined by the effect, invoke its bind property to set its current value.
    • Bind the Viewport's rendered image to the uniform u_diffuse.
    • Execute the effect shader to alter the viewport's image. In this way, a series of multiple effects can be chained together, each consuming as input the image output by the previous effect.

A screen-space effect that moves pixels from their original locations rather than simply recoloring them may cause some tools to behave unexpectedly:

  • Element locate will only work correctly if ScreenSpaceEffectBuilderParams.sampleSourcePixel is properly defined.
  • Tools like the measurement tool that require snapping to element geometry will not snap correctly since the element geometry has been distorted by the shader.

see Screen-space Effects Sample for an interactive demonstration.

see RenderSystem.createScreenSpaceEffectBuilder to create and register a new effect.

see ScreenSpaceEffectBuilderParams to define the initial state of the builder.

see Viewport.screenSpaceEffects, Viewport.addScreenSpaceEffect, and Viewport.removeScreenSpaceEffects to change the effects applied to a viewport.

see LensDistortionEffect for an simulation of the fish-eye distortion produced by real-world cameras with very wide fields of view.

see SaturationEffect for an example of an effect that adjusts the saturation of the original image.

see VignetteEffect for an example of an effect that applies vignetting to the original image.

see ConvolutionEffect for examples of effects like blur, sharpen, and emboss.

see FlipImageEffect for a very simple example of an effect that shifts pixels from their original locations.

Methods

Name Description
addUniform(params: UniformParams): void Add a uniform variable to the shader program.  
addUniformArray(params: UniformArrayParams): void Add an array of uniform variables to the shader program.  
addVarying(name: string, type: VaryingType): void Add a varying variable to the shader program.  
finish(): void Finishes construction of the effect and, if successful, registers it with IModelApp.renderSystem.  
shouldApply(context: ScreenSpaceEffectContext): boolean Optional If defined, a function invoked each frame before the effect is applied.  

Properties

Name Type Description
isWebGL2 Readonly boolean True if the shader will be used with a WebGL 2 rendering context.  

Defined in

Last Updated: 12 June, 2024