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.

• RenderSystem.createScreenSpaceEffectBuilder to create and register a new effect.
• ScreenSpaceEffectBuilderParams to define the initial state of the builder.
• Viewport.screenSpaceEffects, Viewport.addScreenSpaceEffect, and Viewport.removeScreenSpaceEffects to change the effects applied to a viewport.
• LensDistortionEffect for an simulation of the fish-eye distortion produced by real-world cameras with very wide fields of view.
• SaturationEffect for an example of an effect that adjusts the saturation of the original image.
• VignetteEffect for an example of an effect that applies vignetting to the original image.
• ConvolutionEffect for examples of effects like blur, sharpen, and emboss.
• FlipImageEffect for a very simple example of an effect that shifts pixels from their original locations.

Properties

Defined in

• core/frontend/src/render/ScreenSpaceEffectBuilder.ts Line 193

Last Updated: 25 April, 2024