Web 图形与 3D / 系统课时
EffectComposer 配置后处理
EffectComposer 配置后处理
本课把直接渲染改为 EffectComposer 后处理链,配置场景和输出通道,保持色彩转换正确,并在窗口缩放时同步更新相机、画布及离屏缓冲区。
学习目标
- 理解后处理通道的执行顺序和读写缓冲区的作用。
- 使用
EffectComposer替换直接渲染并正确设置输出色彩。 - 在尺寸或设备像素比变化时同步更新渲染器与通道。
认识渲染通道与缓冲区
EffectComposer 是管理后处理 Pass 的组件,适用于 Three.js 的 WebGLRenderer。RenderPass(scene, camera) 负责生成场景画面;中间可插入 Bloom、模糊等效果通道;OutputPass 根据渲染器的色调映射和输出色彩空间设置完成最终转换。通道按 addPass() 顺序执行,最后一个启用的通道默认输出到屏幕。
Composer 内部管理两个渲染目标作为读写缓冲区,中间效果通道需要时可交换输入与输出,避免一边读取纹理一边覆盖同一内容。即使当前只有场景和输出两个通道,也应保留正确顺序,后续增加效果时才不会破坏颜色输出。

从空项目完成配置
以下示例使用支持 three/addons/ 导入路径的 Three.js npm 包以及 Vite 原生 JavaScript 模板。准备 Node.js 和 npm,在终端执行:
npm create vite@latest composer-demo -- --template vanilla
cd composer-demo
npm install
npm install three
npm ls three --depth=0预期输出(仅摘录最后一条命令,实际版本和路径可能不同):
composer-demo@0.0.0 <PATH>
└── three@<VERSION>用下面的完整代码替换 src/main.js。示例创建一个带灯光的旋转立方体,将输出色彩设置交给 OutputPass,并限制 DPR 不超过 2,避免高分辨率屏幕上的离屏纹理过大。
import * as THREE from 'three';
import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
document.body.style.margin = '0';
document.querySelector('#app')?.remove();
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x111820);
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
camera.position.set(3, 2, 5);
camera.lookAt(0, 0, 0);
const renderer = new THREE.WebGLRenderer();
renderer.outputColorSpace = THREE.SRGBColorSpace;
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1;
renderer.domElement.style.display = 'block';
document.body.appendChild(renderer.domElement);
const geometry = new THREE.BoxGeometry(1.5, 1.5, 1.5);
const material = new THREE.MeshStandardMaterial({
color: 0x2aa6a0, metalness: 0.2, roughness: 0.35
});
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);
scene.add(new THREE.HemisphereLight(0xffffff, 0x334455, 2));
const light = new THREE.DirectionalLight(0xffffff, 3);
light.position.set(3, 5, 4);
scene.add(light);
// 输出通道放在效果链的末尾,避免重复做色彩转换。
const composer = new EffectComposer(renderer);
composer.addPass(new RenderPass(scene, camera));
composer.addPass(new OutputPass());
function resize() {
const width = Math.max(1, window.innerWidth);
const height = Math.max(1, window.innerHeight);
const dpr = Math.min(window.devicePixelRatio || 1, 2);
// setSize 使用 CSS 像素,物理分辨率由 DPR 决定。
renderer.setPixelRatio(dpr);
renderer.setSize(width, height);
composer.setPixelRatio(dpr);
composer.setSize(width, height);
camera.aspect = width / height;
camera.updateProjectionMatrix();
}
window.addEventListener('resize', resize);
resize();
renderer.setAnimationLoop((time) => {
cube.rotation.y = time * 0.0005;
// 后处理已接管最终输出,不要再调用 renderer.render()。
composer.render();
});运行与验证
运行开发服务器:
npm run dev预期输出(端口、启动耗时与版本因环境而异):
VITE v<VERSION> ready in <TIME>
Local: http://localhost:<PORT>/打开终端显示的本地地址,应看到深蓝背景中持续旋转的青绿色立方体。拉窄浏览器,立方体不会被横向拉伸;放大窗口,画布仍覆盖视口。RenderPass 加 OutputPass 只是打通链路,不会自动产生辉光。
可用具体尺寸核对逻辑:若窗口内容区是 800×600 CSS 像素,设备 DPR 为 2,两个 setSize() 都应收到 800、600,实际离屏纹理大小则是 1600×1200 像素。不要把宽高先乘 DPR,否则缓冲区会被多放大一次,浪费显存和填充率。
常见错误与维护边界
- 画面空白:确认使用
composer.render()、存在启用的RenderPass,并检查浏览器控制台是否报错;不要在同一帧又调用renderer.render()覆盖后处理结果。 - 缩放后模糊或变形:检查
renderer.setSize()、composer.setSize()、camera.aspect和camera.updateProjectionMatrix()是否一起更新。若画布只占页面局部区域,改用容器的clientWidth/clientHeight,并通过ResizeObserver感知容器尺寸变化。 - 颜色偏灰或过曝:优先核对
renderer.outputColorSpace、renderer.toneMapping、toneMappingExposure及OutputPass的位置,不要再额外插入一次相同的色彩转换。 - 显存逐渐增大:单次调整尺寸不应反复新建 Composer;退出展厅时调用
composer.dispose()、renderer.dispose(),并释放不再使用的几何体和材质。
当新增 Bloom 等效果时,将新通道插入 RenderPass 与 OutputPass 之间,继续保持一帧只调用一次 composer.render()。