threejs-impl-post-processing

threejs-impl-post-processing

快速参考

架构概览

Three.js 提供两种互不兼容的后期处理系统。切勿混用。

系统	包	方式	最适合
内置 EffectComposer	three/addons/postprocessing/	每种效果使用一个着色器通道	简单配置、自定义 ShaderPass
pmndrs/postprocessing	postprocessing（npm）	将多种效果合并到单个通道	性能关键型应用、R3F 应用
WebGPU PostProcessing	three/addons/tsl/display/	基于节点的 TSL 图	仅限 WebGPU 渲染器

标准管线（内置 EffectComposer）

import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';

const composer = new EffectComposer( renderer );
composer.addPass( new RenderPass( scene, camera ) ); // ALWAYS first
// ... effect passes here ...
composer.addPass( new OutputPass() );                 // ALWAYS last

function animate() {
  composer.render(); // replaces renderer.render( scene, camera )
}

通道排序规则

1. RenderPass 必须是第一个通道——它会将场景渲染到内部缓冲区。
2. 效果通道放在中间，顺序不限（bloom、SSAO、outline 等）。
3. 抗锯齿通道（SMAA、FXAA）放在效果通道之后。
4. OutputPass 必须是最后一个通道——它会应用色调映射和色彩空间转换。
5. 切勿省略 OutputPass——否则颜色会显得褪色或不正确。

关键警告

切勿混用 three/addons/postprocessing/EffectComposer 和 pmndrs/postprocessing 的 EffectComposer。它们使用不兼容的缓冲区格式，会导致渲染异常或崩溃。

切勿忘记在窗口大小变化时调用 composer.setSize()。如果未调整合成器大小，效果会模糊或错位。

使用 EffectComposer 时，切勿调用 renderer.render( scene, camera )。应始终调用 composer.render()——同时调用两者会导致场景渲染两次。

切勿在 WebGPU 渲染器中使用 WebGL 后期处理通道。WebGPU 使用完全独立的、基于节点的 PostProcessing 类。

务必将 RenderPass 作为第一个通道。否则，后续通道接收到的将是空缓冲区。

---

EffectComposer API

构造函数

new EffectComposer( renderer: WebGLRenderer, renderTarget?: WebGLRenderTarget )

• renderer —— WebGLRenderer 实例
• renderTarget —— 可选的自定义渲染目标；省略时会自动创建

属性

属性	类型	说明
.passes	Pass[]	按顺序排列的后期处理通道数组
.readBuffer	WebGLRenderTarget	内部读取缓冲区
.writeBuffer	WebGLRenderTarget	内部写入缓冲区
.renderToScreen	boolean	最后一个通道是否渲染到屏幕（默认值为 true）
.renderer	WebGLRenderer	渲染器实例

方法

方法	说明
.addPass( pass )	将通道追加到处理链末尾
.insertPass( pass, index )	在指定位置插入通道
.removePass( pass )	从处理链中移除通道
.render( deltaTime? )	按顺序执行所有已启用的通道
.setSize( width, height )	调整所有内部缓冲区和通道的大小
.setPixelRatio( ratio )	设置设备像素比
.swapBuffers()	交换读取/写入缓冲区
.reset( renderTarget? )	恢复内部状态
.dispose()	释放所有 GPU 资源

---

可用的通道类型

核心通道（始终需要）

通道	导入路径	用途
RenderPass	postprocessing/RenderPass.js	将场景渲染到缓冲区；始终放在第一位
OutputPass	postprocessing/OutputPass.js	色调映射与色彩空间处理；始终放在最后

效果通道

通道	构造函数	用途
UnrealBloomPass	( resolution, strength?, radius?, threshold? )	HDR 泛光效果
SSAOPass	( scene, camera, width?, height? )	屏幕空间环境光遮蔽
GTAOPass	( scene, camera, width?, height? )	Ground truth AO（质量更高）
SAOPass	( scene, camera )	可扩展环境光遮蔽
OutlinePass	( resolution, scene, camera, selectedObjects? )	对象选择轮廓
BokehPass	( scene, camera, params )	景深
SSRPass	( params )	屏幕空间反射
FilmPass	( intensity?, grayscale? )	胶片颗粒 / 扫描线
GlitchPass	( dtSize? )	数字故障效果
HalftonePass	( width, height, params )	半色调网点图案
DotScreenPass	( center?, angle?, scale? )	网点屏幕叠加效果
AfterimagePass	( damp? )	运动轨迹 / 残影
LUTPass	( params )	颜色 LUT 调色
RenderPixelatedPass	( pixelSize, scene, camera )	像素化效果

抗锯齿通道

通道	构造函数	质量	开销
FXAAPass	()	低 —— 快速近似	最低
SMAAPass	( width, height )	中 —— 子像素形态学抗锯齿	中等
SSAARenderPass	( scene, camera )	高 —— 超采样	高
TAARenderPass	( scene, camera )	高 —— 时间累积	高

实用工具通道

通道	用途
ShaderPass	自定义 GLSL 着色器效果
MaskPass	模板缓冲区遮罩
ClearMaskPass	清除模板遮罩
ClearPass	清除缓冲区
TexturePass	渲染纹理
CubeTexturePass	渲染立方体贴图背景
SavePass	将当前缓冲区保存到渲染目标
RenderTransitionPass	两个场景之间的动画过渡

所有通道均从 three/addons/postprocessing/{PassName}.js 导入。

---

关键效果配置

UnrealBloomPass

import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';

const bloom = new UnrealBloomPass(
  new THREE.Vector2( window.innerWidth, window.innerHeight ),
  1.5,  // strength -- bloom intensity [0, 3+]
  0.4,  // radius -- bloom spread [0, 1]
  0.85  // threshold -- luminance cutoff [0, 1]
);

要使泛光正常工作，必须在渲染器上启用色调映射。原生不支持选择性泛光（针对单个对象）——可使用 layers 系统搭配多个渲染通道作为变通方案。

SSAOPass / GTAOPass

生产环境中始终优先使用 GTAOPass，而非 SSAOPass。SSAOPass 仅用于原型开发。

// SSAOPass (faster, lower quality)
const ssao = new SSAOPass( scene, camera, width, height );
ssao.kernelRadius = 8;
ssao.minDistance = 0.005;
ssao.maxDistance = 0.1;

// GTAOPass (slower, production quality)
const gtao = new GTAOPass( scene, camera, width, height );

OutlinePass

const outline = new OutlinePass(
  new THREE.Vector2( window.innerWidth, window.innerHeight ),
  scene, camera
);
outline.selectedObjects = [ mesh1, mesh2 ];
outline.edgeStrength = 3;
outline.edgeGlow = 0;
outline.edgeThickness = 1;
outline.visibleEdgeColor.set( 0xffffff );
outline.hiddenEdgeColor.set( 0x190a05 );

---

自定义 ShaderPass

import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';

const myShader = {
  uniforms: {
    tDiffuse: { value: null }, // ALWAYS include -- receives read buffer
    amount: { value: 0.5 }
  },
  vertexShader: `
    varying vec2 vUv;
    void main() {
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
    }
  `,
  fragmentShader: `
    uniform sampler2D tDiffuse;
    uniform float amount;
    varying vec2 vUv;
    void main() {
      vec4 color = texture2D( tDiffuse, vUv );
      gl_FragColor = mix( color, vec4( 1.0 - color.rgb, color.a ), amount );
    }
  `
};

const customPass = new ShaderPass( myShader );
composer.insertPass( customPass, 1 ); // after RenderPass

textureID 参数的默认值为 'tDiffuse'。如果着色器使用了其他名称的输入纹理 uniform，请将其作为第二个参数传入：new ShaderPass( myShader, 'myInputTexture' )。

---

pmndrs/postprocessing

架构

pmndrs/postprocessing 库会将多个效果合并到单个着色器通道中，与内置系统相比，可显著减少绘制调用。

import { EffectComposer, EffectPass, RenderPass, BloomEffect,
         SMAAEffect } from 'postprocessing';

const composer = new EffectComposer( renderer );
composer.addPass( new RenderPass( scene, camera ) );
composer.addPass( new EffectPass( camera, new BloomEffect(), new SMAAEffect() ) );

function animate() {
  composer.render();
}

主要效果

效果	用途
BloomEffect	支持配置并使用 mipmap 的泛光
SMAAEffect	子像素形态学抗锯齿
SSAOEffect	屏幕空间环境光遮蔽
DepthOfFieldEffect	Bokeh 景深
ToneMappingEffect	色调映射算子
VignetteEffect	屏幕边缘变暗
ChromaticAberrationEffect	色边效果
NoiseEffect	胶片颗粒
GodRaysEffect	体积光散射

对于 React Three Fiber，请使用 @react-three/postprocessing，它会将这些效果封装为 JSX 组件。

---

调整大小处理

窗口大小变化时，始终同时调整渲染器和合成器的大小：

window.addEventListener( 'resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize( window.innerWidth, window.innerHeight );
  composer.setSize( window.innerWidth, window.innerHeight ); // MUST resize
});

---

WebGPU 后期处理

WebGPU 渲染器使用一套独立的基于节点的系统：

import { PostProcessing } from 'three/addons/tsl/display/PostProcessing.js';

const postProcessing = new PostProcessing( renderer );
// Uses TSL (Three Shading Language) node graphs for effects

此系统与内置的 WebGL EffectComposer 和 pmndrs/postprocessing 均完全不兼容。

---

参考链接

• references/methods.md —— EffectComposer、所有通道和 pmndrs 特效的完整 API 签名
• references/examples.md —— 常见后期处理设置的可运行代码示例
• references/anti-patterns.md —— 后期处理中不该采用的做法

官方来源

• https://threejs.org/docs/#examples/en/postprocessing/EffectComposer
• https://threejs.org/examples/?q=postprocessing
• https://github.com/pmndrs/postprocessing
• https://docs.pmnd.rs/react-three-fiber/tutorials/post-processing