ScreenSpaceEffectBuilder Interface
An interface used to construct and register with the 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 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
bindproperty 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 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.
- createScreenSpaceEffectBuilder to create and register a new effect.
- ScreenSpaceEffectBuilderParams to define the initial state of the builder.
- screenSpaceEffects, addScreenSpaceEffect, and 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
| Name | Type | 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 renderSystem. | |
| isWebGL2 Readonly | boolean | True if the shader will be used with a WebGL 2 rendering context. | Deprecated |
| shouldApply | (context: ScreenSpaceEffectContext) => boolean | undefined | If defined, a function invoked each frame before the effect is applied. |
Defined in
Last Updated: 21 November, 2024
Found something wrong, missing, or unclear on this page?Raise an issue in our repo.