repository·main·Indexed 23 days ago
https://github.com/0beqz/realism-effectsA library for enhancing three.js scenes with realistic visual effects. It provides a collection of post-processing passes and effects, including Screen Space Global Illumination (SSGIEffect), Screen Space Reflections (SSREffect), Horizon Based Ambient Occlusion (HBAOEffect), Temporal Robust Anti-Aliasing (TRAAEffect), and Motion Blur. The library includes specialized G-Buffer materials and tools for temporal reprojection, velocity calculation, and debugging G-Buffer contents.
To explore the realism-effects library in action, you can run the provided example project. Navigate to the example directory, install the dependencies, and start the development server.
cd example
npm install
npm run devThe realism-effects library provides a collection of post-processing effects and passes designed to enhance visual realism in graphics applications. You can import specific effects or passes directly from the main entrypoint to integrate them into your rendering pipeline.
import {
SSGIEffect,
SSREffect,
TAAPass,
TRAAEffect,
MotionBlurEffect,
VelocityPass,
VelocityDepthNormalPass,
TemporalReprojectPass,
PoissonDenoisePass,
HBAOEffect,
SharpnessEffect,
GradualBackgroundEffect,
SparkleEffect,
LensDistortionEffect
} from 'realism-effects';The SSGI (Screen Space Global Illumination) effect can be configured using an options object. These options control ray tracing distance, intersection refinement, denoising behavior, and performance scaling via resolution.
distance: Maximum distance a SSGI ray can travel to find what it reflects.steps: Maximum number of steps a SSGI ray can take to find an intersection.refineSteps: Number of binary search steps used to find the exact intersection point after a ray hits an object.thickness: Maximum depth difference between a ray and the depth at its screen position before refining with binary search. Higher values improve performance.missedRays: If true, SSGI is still applied to rays that didn't find a reflecting point, which can create a 'stretched' look.denoiseIterations: Number of times the denoise filter runs. More iterations improve quality but decrease performance.radius: The radius of the denoiser. Higher values reduce noise on smooth surfaces but increase noise on detailed surfaces.depthPhi: Depth factor for the denoiser. Higher values use neighbors with different depths, reducing noise but losing detail.normalPhi: Normals factor for the denoiser. Higher values use neighbors with different normals, reducing noise but losing sharpness.roughnessPhi: Controls how much the denoiser applies blur to rougher surfaces. A value of 0 blurs mirror-like and rough surfaces equally.specularPhi: Factor for how much the denoiser blurs specular reflections.lumaPhi: Luminance factor; determines how aggressive the denoiser is in areas with different luminance.envBlur: Higher values sample lower mipmaps, reducing noise but decreasing detail in environment lighting.importanceSampling: Whether to use importance sampling for the environment map.resolutionScale: The resolution scale of the effect (e.g., 0.5 renders the effect at half resolution for better performance).The TemporalReprojectPass is configured via the defaultTemporalReprojectPassOptions object. These options control the behavior of the temporal accumulation algorithm.
| Option | Type | Description |
|---|---|---|
dilation | boolean | Enables dilation in the shader. |
fullAccumulate | boolean | If true, accumulates data when the camera is static. |
neighborhoodClamp | boolean or boolean[] | Enables neighborhood clamping to reduce ghosting. Can be an array of booleans per texture. |
neighborhoodClampRadius | number | The radius for neighborhood clamping. |
neighborhoodClampIntensity | number | The intensity of the neighborhood clamping. |
maxBlend | number | The maximum blending factor. |
logTransform | boolean | Enables log transform in the shader. |
depthDistance | number | Distance threshold for depth-based rejection. |
worldDistance | number | World space distance threshold for rejection. |
reprojectSpecular | boolean or boolean[] | Enables specular reprojection. Can be an array of booleans per texture. |
renderTarget | WebGLMultipleRenderTargets | Custom render target (internal use). |
copyTextures | boolean | Whether to copy textures. |
confidencePower | number | Power used for confidence calculation. |
inputType | "diffuseSpecular" | "diffuse" | "specular" | The type of input texture being processed. |
export const defaultTemporalReprojectPassOptions = {
dilation: false,
fullAccumulate: false,
neighborhoodClamp: false,
neighborhoodClampRadius: 1,
neighborhoodClampIntensity: 1,
maxBlend: 1,
logTransform: false,
depthDistance: 2,
worldDistance: 4,
reprojectSpecular: false,
renderTarget: null,
copyTextures: true,
confidencePower: 0.75,
inputType: "diffuse"
}reset() on a TemporalReprojectPass instance to clear accumulated data. This is useful when the scene state changes significantly and old temporal data is no longer valid (e.g., a sudden teleport or major lighting change).The GBufferDebugPass is a post-processing pass used for debugging and visualizing the contents of a G-Buffer. It allows you to inspect different material properties by switching between modes.
To use it, instantiate the class with your gBufferTexture and add it to your post-processing pipeline. You can control which property is displayed by updating the mode uniform on the fullscreenMaterial.
The jitter function applies a sub-pixel offset to a camera to facilitate Temporal Anti-Aliasing. It uses a pre-computed r2Sequence (a Halton-like quasi-random sequence) to select an offset based on the current frame index.
To use this, your camera object must implement a setViewOffset method with the following signature:
setViewOffset(width, height, offsetX, offsetY, viewportWidth, viewportHeight).
Arguments:
width: The width of the render target.height: The height of the render target.camera: The camera object. Must have a setViewOffset method.frame: The current frame index (used to index into the r2Sequence).jitterScale: A multiplier for the jitter offset (defaults to 1).GBufferMaterial instance and want to update its primitive properties (strings or numbers) from another material, use copyPropsToGBufferMaterial. This is useful for updating material parameters dynamically without re-creating the entire material object.src/ssgi/index.js entrypoint provides access to Screen Space Global Illumination (SSGIEffect) and Screen Space Reflections (SSREffect) along with default configuration options for SSGI. These effects are used to enhance visual realism in a rendering pipeline.The TemporalReprojectPass is a post-processing pass used for temporal reprojection and accumulation, typically used to reduce noise or improve quality by reusing data from previous frames. It requires a velocityDepthNormalPass to provide motion vectors and depth information.
To use it, instantiate the pass with the required scene, camera, velocity/depth pass, and the input texture you wish to accumulate.
scene: The Three.js scene.camera: The Three.js camera used for reprojection.velocityDepthNormalPass: A pass that provides renderTarget.texture (velocity) and depthTexture.texture: The input texture to be reprojected.textureCount: The number of textures to accumulate.options: (Optional) An object following defaultTemporalReprojectPassOptions.The MotionBlurEffect class provides a post-processing motion blur effect. It requires a velocityPass (which must provide a .texture property) to function. You can customize the effect using an options object.
constructor(velocityPass, options)
velocityPass: An object containing a texture property (typically a velocity pass from a post-processing pipeline).options: An optional configuration object (see MotionBlurEffect options).| Option | Default | Description |
|---|---|---|
intensity | 1 | Controls the strength of the blur. |
jitter | 1 | Controls the amount of jitter applied to samples. |
samples | 16 | The number of samples used for the blur effect. This value is used to define shader constants at initialization. |
The MotionBlurEffect instance exposes intensity and jitter as reactive properties. Updating these values on the instance will automatically update the underlying shader uniforms.
Note that samples is used to define shader constants during initialization and cannot be changed reactively after the effect is instantiated.