Gaussian Blur Pass (高斯模糊通道)

• Summary: GaussianBlurPass 是一个后处理通道，用于对渲染结果应用高斯模糊效果。
• Schema: GaussianBlurPass 类及其关键参数。
• Concepts: 后处理通道 (Pass)、高斯模糊、Shader、EffectComposer。
• Configuration: 模糊半径 (radius) 和标准差 (sigma) 参数。
• Examples: 基础使用、参数调整。

Schema

Definition: GaussianBlurPass

GaussianBlurPass 是 FivePass 的子类，用于实现高斯模糊效果。其核心接口如下：

import * as THREE from 'three';
import { FivePass } from './pass';
import { type Camera } from '../../../core/camera';

export class GaussianBlurPass extends FivePass {
  // 构造函数，传入相机实例
  constructor(camera: Camera);

  // 设置模糊半径
  public setRadius(radius: number): void;

  // 渲染方法（由 EffectComposer 调用）
  public render(
    renderer: THREE.WebGLRenderer,
    writeBuffer: THREE.WebGLRenderTarget,
    readBuffer: THREE.WebGLRenderTarget,
    deltaTime: number,
    maskActive?: boolean,
  ): void;

  // 释放资源
  public dispose(): void;
}
Copy

Shader Uniforms (内部 Shader 参数)

该通道使用 ShaderMaterial，包含以下 uniforms：

Uniform	Type	Default	Description
colorMap	THREE.Texture	null	输入纹理（来自 readBuffer）
resolution	THREE.Vector2	相机分辨率	渲染目标的分辨率
radius	number	4.0	模糊采样半径（像素数）
sigma	number	4.0	高斯核的标准差

Concepts

后处理通道 (Post-Processing Pass)

GaussianBlurPass 是 Three.js EffectComposer 生态中的一个通道。它接收前一个通道的输出（readBuffer），进行高斯模糊处理后，输出到下一个通道或屏幕（writeBuffer 或 renderToScreen）。

高斯模糊原理

该通道采用离散高斯核进行模糊。在 fragment shader 中：

• 对采样范围内的像素（由 radius 定义）计算高斯权重
• 根据 sigma 值计算高斯分布的形状
• 对所有采样点的颜色值加权平均

相机依赖

构造函数需传入 Camera 实例，用于获取当前渲染分辨率。通过 camera.resolution 自动同步分辨率变化，确保模糊效果在窗口 resize 时保持正确。

Configuration

常用参数

通过 setRadius() 方法调整模糊效果强度：

Parameter	Type	Default	Range	Description
radius	number	4.0	0 ~ 8	采样半径（像素），值越大模糊越明显
sigma	number	4.0	0.1 ~ 10	高斯核标准差，控制模糊的柔和度

注意：当前实现中 sigma 固定为 4.0，仅 radius 可动态调整。如需修改 sigma，需直接访问 material.uniforms.sigma.value。

Instance Methods

constructor(camera: Camera)

初始化高斯模糊通道，需传入相机实例以获取分辨率信息。

setRadius(radius: number)

动态调整模糊半径。

• 参数: radius - 采样半径，建议范围 1 ~ 8
• 默认值: 4.0
• 影响: 较大的 radius 会增加 GPU 计算成本

render(...)

由 EffectComposer 在每一帧自动调用，用于执行模糊处理。通常不需要手动调用。

dispose()

释放 Shader Material 和 FullScreenQuad 资源。在销毁 Pass 时必须调用，以防内存泄漏。

Examples

快速上手 (Quick Example)

import { Five } from '@realsee/five';
import { GaussianBlurPass } from '../../lib/five/renderer/postprocessing';

const five = new Five();

// 使用 Five 的 addPass() 方法添加后处理通道
const blurPass = new GaussianBlurPass(five.camera);
five.addPass(blurPass);

// 动画循环由 Five 内部管理
function animate() {
  requestAnimationFrame(animate);
  five.render();
}
animate();
Copy

进阶用法 (Advanced Usage)

动态调整模糊强度

const blurPass = new GaussianBlurPass(five.camera);
five.addPass(blurPass);

// 响应用户输入调整模糊半径
document.addEventListener('keydown', (e) => {
  if (e.key === '+') {
    const current = blurPass['material'].uniforms.radius.value;
    blurPass.setRadius(Math.min(8, current + 0.5));
  }
  if (e.key === '-') {
    const current = blurPass['material'].uniforms.radius.value;
    blurPass.setRadius(Math.max(0, current - 0.5));
  }
});
Copy

多通道组合（模糊 + 其他效果）

// Five 的 addPass() 会自动管理后处理链
const blurPass = new GaussianBlurPass(five.camera);
five.addPass(blurPass);

// 可添加其他后处理通道
// five.addPass(otherPass);
Copy

修改高斯标准差 (Advanced)

const blurPass = new GaussianBlurPass(five.camera);
five.addPass(blurPass);

// 获取 Material 并直接修改 sigma
const sigmaMaterial = blurPass['material'] as THREE.ShaderMaterial;
sigmaMaterial.uniforms.sigma.value = 2.0;  // 调整标准差（更强锐利）
Copy

Debugging

检查模糊效果是否生效

• 确保 renderToScreen 为 true，或后续通道正确读取该通道的输出。
• 确保传入的 camera 对象有有效的 resolution 属性。

性能优化建议

• 大 radius 值会导致 GPU 开销增加。建议在性能受限的设备上限制最大 radius（如 ≤ 6）。
• 考虑在低端设备上禁用该通道（设置 blurPass.enabled = false）。

可视化调试

// 监控当前模糊参数
const blurPass = new GaussianBlurPass(five.camera);
console.log('Blur Radius:', blurPass['material'].uniforms.radius.value);
console.log('Blur Sigma:', blurPass['material'].uniforms.sigma.value);
console.log('Resolution:', blurPass['material'].uniforms.resolution.value);
Copy

Common Pitfalls

1. 忘记调用 dispose()

   • 销毁 Pass 时，必须调用 blurPass.dispose() 释放 Shader 资源，否则会导致内存泄漏。

2. 分辨率变化未更新

   • GaussianBlurPass 会自动从 camera.resolution 同步分辨率，无需手动处理。但如果使用自定义相机，需确保其 resolution 属性始终有效。

3. 设置过大的 radius

   • 超过 8 的 radius 值虽然技术上可行，但会显著增加计算成本。建议不超过 8。

4. 与其他 Pass 的 needsSwap 冲突

   • 如果通道链中多个 Pass 设置了不同的 needsSwap 值，可能导致缓冲区错乱。确保通道顺序和 swap 设置一致。

Related

• Postprocessing: 后处理通用概念与 EffectComposer 使用指南。

---

tags: [模糊, 高斯模糊, 毛玻璃, 背景虚化, postprocessing, shader, effect, blur, pass, rendering, gaussian, blur-effect]
Copy