threejs-postprocessing

# Three.js Post-Processing ## Iron Law **Always use composer.render() instead of renderer.render() when post-processing is active — calling both causes double rendering and doubles GPU cost.** ## Quick Start ```javascript import * as THREE from "three"; import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js"; import { RenderPass } from "three/addons/postprocessing/RenderPass.js"; import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js"; // Setup composer const composer = new EffectComposer(renderer); // Render scene const renderPass = new RenderPass(scene, camera); composer.addPass(renderPass); // Add bloom const bloomPass = new UnrealBloomPass( new THREE.Vector2(window.innerWidth, window.innerHeight), 1.5, // strength 0.4, // radius 0.85, // threshold ); composer.addPass(bloomPass); // Animation loop - use composer instead of renderer function animate() { requestAnimationFrame(animate); composer.render(); // NOT renderer.render() } ``` ## EffectComposer Setup ```javascript import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js"; import { RenderPass } from "three/addons/postprocessing/RenderPass.js"; const composer = new EffectComposer(renderer); // First pass: render scene const renderPass = new RenderPass(scene, camera); composer.addPass(renderPass); // Add more passes... composer.addPass(effectPass); // Last pass should render to screen effectPass.renderToScreen = true; // Default for last pass // Handle resize function onResize() { const width = window.innerWidth; const height = window.innerHeight; camera.aspect = width / height; camera.updateProjectionMatrix(); renderer.setSize(width, height); composer.setSize(width, height); } ``` ## Common Effects ### Bloom (Glow) ```javascript import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js"; const bloomPass = new UnrealBloomPass( new THREE.Vector2(window.innerWidth, window.innerHeight), 1.5, // strength - intensity of glow 0.4, // radius - spread of glow 0.85, // threshold - brightness threshold ); composer.addPass(bloomPass); // Adjust at runtime bloomPass.strength = 2.0; bloomPass.threshold = 0.5; bloomPass.radius = 0.8; ``` ### Selective Bloom Apply bloom only to specific objects. ```javascript import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js"; import { ShaderPass } from "three/addons/postprocessing/ShaderPass.js"; // Layer setup const BLOOM_LAYER = 1; const bloomLayer = new THREE.Layers(); bloomLayer.set(BLOOM_LAYER); // Mark objects to bloom glowingMesh.layers.enable(BLOOM_LAYER); // Dark material for non-blooming objects const darkMaterial = new THREE.MeshBasicMaterial({ color: 0x000000 }); const materials = {}; function darkenNonBloomed(obj) { if (obj.isMesh && !bloomLayer.test(obj.layers)) { materials[obj.uuid] = obj.material; obj.material = darkMaterial; } } function restoreMaterial(obj) { if (materials[obj.uuid]) { obj.material = materials[obj.uuid]; delete materials[obj.uuid]; } } // Custom render loop function render() { // Render bloom pass scene.traverse(darkenNonBloomed); composer.render(); scene.traverse(restoreMaterial); // Render final scene over bloom renderer.render(scene, camera); } ``` ### FXAA (Anti-Aliasing) ```javascript import { ShaderPass } from "three/addons/postprocessing/ShaderPass.js"; import { FXAAShader } from "three/addons/shaders/FXAAShader.js"; const fxaaPass = new ShaderPass(FXAAShader); fxaaPass.material.uniforms["resolution"].value.set( 1 / window.innerWidth, 1 / window.innerHeight, ); composer.addPass(fxaaPass); // Update on resize function onResize() { fxaaPass.material.uniforms["resolution"].value.set( 1 / window.innerWidth, 1 / window.innerHeight, ); } ``` ### SMAA (Better Anti-Aliasing) ```javascript import { SMAAPass } from "three/addons/postprocessing/SMAAPass.js"; const smaaPass = new SMAAPass( window.innerWidth * renderer.getPixelRatio(), window.innerHeight * renderer.getPixelRatio(), ); composer.addPass(smaaPass); ``` ### SSAO (Ambient Occlusion) ```javascript import { SSAOPass } from "three/addons/postprocessing/SSAOPass.js"; const ssaoPass = new SSAOPass( scene, camera, window.innerWidth, window.innerHeight, ); ssaoPass.kernelRadius = 16; ssaoPass.minDistance = 0.005; ssaoPass.maxDistance = 0.1; composer.addPass(ssaoPass); // Output modes ssaoPass.output = SSAOPass.OUTPUT.Default; // SSAOPass.OUTPUT.Default - Final composited output // SSAOPass.OUTPUT.SSAO - Just the AO // SSAOPass.OUTPUT.Blur - Blurred AO // SSAOPass.OUTPUT.Depth - Depth buffer // SSAOPass.OUTPUT.Normal - Normal buffer ``` ### Depth of Field (DOF) ```javascript import { BokehPass } from "three/addons/postprocessing/BokehPass.js"; const bokehPass = new BokehPass(scene, camera, { focus: 10.0, // Focus distance aperture: 0.025, // Aperture (smaller = more DOF) maxblur: 0.01, // Max blur amount }); composer.addPass(bokehPass); // Update focus dynamically bokehPass.uniforms["focus"].value = distanceToTarget; ``` ### Outline ```javascript import { OutlinePass } from "three/addons/postprocessing/OutlinePass.js"; const outlinePass = new OutlinePass( new THREE.Vector2(window.innerWidth, window.innerHeight), scene, camera, ); outlinePass.edgeStrength = 3; outlinePass.edgeGlow = 0; outlinePass.edgeThickness = 1; outlinePass.pulsePeriod = 0; outlinePass.visibleEdgeColor.set(0xffffff); outlinePass.hiddenEdgeColor.set(0x190a05); // Select objects to outline outlinePass.selectedObjects = [mesh1, mesh2]; composer.addPass(outlinePass); ``` ## Custom ShaderPass Create your own post-processing effects. The key requirement: include `tDiffuse` uniform (the input texture from previous passes). ```javascript import { ShaderPass } from "three/addons/postprocessing/ShaderPass.js"; const CustomShader = { uniforms: { tDiffuse: { value: null }, // Required: input from previous pass time: { value: 0 }, intensity: { value: 1.0 }, }, vertexShader: ` varying vec2 vUv; void main() { vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); } `, fragmentShader: ` uniform sampler2D tDiffuse; uniform float time; uniform float intensity; varying vec2 vUv; void main() { vec2 uv = vUv; uv.x += sin(uv.y * 10.0 + time) * 0.01 * intensity; gl_FragColor = texture2D(tDiffuse, uv); } `, }; const customPass = new ShaderPass(CustomShader); composer.addPass(customPass); // Update in animation loop customPass.uniforms.time.value = clock.getElapsedTime(); ``` > More custom shader examples (invert, chromatic aberration) → `references/effects-catalog.md` ## Combining Multiple Effects ```javascript import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js"; import { RenderPass } from "three/addons/postprocessing/RenderPass.js"; import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js"; import { ShaderPass } from "three/addons/postprocessing/ShaderPass.js"; import { FXAAShader } from "three/addons/shaders/FXAAShader.js"; import { VignetteShader } from "three/addons/shaders/VignetteShader.js"; import { GammaCorrectionShader } from "three/addons/shaders/GammaCorrectionShader.js"; const composer = new EffectComposer(renderer); // 1. Render scene composer.addPass(new RenderPass(scene, camera)); // 2. Bloom const bloomPass = new UnrealBloomPass( new THREE.Vector2(window.innerWidth, window.innerHeight), 0.5, 0.4, 0.85, ); composer.addPass(bloomPass); // 3. Vignette const vignettePass = new ShaderPass(VignetteShader); vignettePass.uniforms["offset"].value = 0.95; vignettePass.uniforms["darkness"].value = 1.0; composer.addPass(vignettePass); // 4. Gamma correction composer.addPass(new ShaderPass(GammaCorrectionShader)); // 5. Anti-aliasing (always last before output) const fxaaPass = new ShaderPass(FXAAShader); fxaaPass.uniforms["resolution"].value.set( 1 / window.innerWidth, 1 / window.innerHeight, ); composer.addPass(fxaaPass); ``` ## References - `references/effects-catalog.md` — Film grain, vignette, color correction, gamma, pixelation, glitch, halftone, chromatic aberration, invert; multi-pass rendering, render-to-texture, WebGPU node-based post-processing, resize handling, and performance tips ## See Also - `threejs-shaders` - Custom shader development - `threejs-textures` - Render targets - `threejs-fundamentals` - Renderer setup