@realsee/five/ai_guides/features/gaussian-blur-pass.md

Realsee Renderer SDK

# Gaussian Blur Pass (高斯模糊通道)

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

## Schema

> **Definition**: [GaussianBlurPass](../../five/renderer/postprocessing/passes/gaussian-blur-pass.d.ts)

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

```ts
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;
}
```

### 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)

```ts
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();
```

### 进阶用法 (Advanced Usage)

#### 动态调整模糊强度

```ts
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));
  }
});
```

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

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

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

#### 修改高斯标准差 (Advanced)

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

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

## Debugging

### 检查模糊效果是否生效
- 确保 `renderToScreen` 为 `true`，或后续通道正确读取该通道的输出。
- 确保传入的 `camera` 对象有有效的 `resolution` 属性。

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

### 可视化调试
```ts
// 监控当前模糊参数
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);
```

## 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](./postprocessing.md): 后处理通用概念与 EffectComposer 使用指南。

---

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