后处理 (Post Processing)

• Summary: Five 提供了基于 EffectComposer 的后处理机制，默认挂载了自适应亮度 (Auto Exposure) 和眼球穹顶光照 (EDL) 两种效果，同时提供多种可选内置 Pass，并支持开发者编写自定义 Pass。
• Schema: FivePass 类及 Pass 接口。
• Concepts: EffectComposer, G-Buffer, Pass, AdaptiveLuminance, EyeDomeLighting。
• Configuration: 开启内置 Pass 的开关及参数配置。
• Examples: 开启内置 Pass 示例，自定义黑白滤镜 Pass 示例。

Schema

Definition: FivePass

/**
 * Pass 接口 (兼容 three.js EffectComposer)
 */
export interface Pass {
  enabled: boolean;
  needsSwap: boolean;
  clear: boolean;
  renderToScreen: boolean;
  setSize(width: number, height: number): void;
  render(
    renderer: THREE.WebGLRenderer,
    writeBuffer: THREE.WebGLRenderTarget,
    readBuffer: THREE.WebGLRenderTarget,
    deltaTime?: number,
    maskActive?: boolean
  ): void;
}

/**
 * FivePass 基类
 * 支持 G-Buffer 注入 (depth, normal, color)
 */
export class FivePass implements Pass {
  public enabled: boolean = true;
  public needsSwap: boolean = true;
  public clear: boolean = false;
  public renderToScreen: boolean = true;
  public dependencies: ('depth' | 'normal' | 'color')[];

  // 由 EffectComposer 在 render 时注入
  public gbuffer!: Map<'depth' | 'normal' | 'color', THREE.Texture>;

  constructor(dependencies?: ('depth' | 'normal' | 'color')[]);
  // ... render method implementation
}
Copy

Concepts

• EffectComposer: 后处理管理器，负责按顺序执行 Pass，管理渲染目标 (RenderTarget) 和 G-Buffer。
• FivePass: Five 引擎优化的 Pass 基类。相比普通 Pass，它声明了 dependencies，Five 会在渲染 Pass 之前准备好所需的 G-Buffer (如深度图、法线图)，避免在每个 Pass 中重复渲染场景。
• AdaptiveLuminancePass (自适应亮度): 模拟人眼对光线的适应过程。当场景亮度变化时，会自动平滑调整曝光度，使画面保持在舒适的亮度范围内。
• EyeDomeLightingPass (EDL): 一种非真实感渲染技术，主要用于增强点云模型的深度感知。通过屏幕空间的深度差计算遮蔽效果，让点云看起来更有轮廓感。

Built-in Passes (内置 Pass)

Five 默认挂载了两个 Pass 实例，挂载在 five 实例上，默认是关闭状态。

1. AdaptiveLuminancePass

位于 five.adaptiveLuminancePass。

• 作用: 自动调整画面曝光。
• 开启方式: five.adaptiveLuminancePass.enabled = true。
• 配置项:
  • luminanceScale (number): 亮度缩放系数，影响最终画面的整体亮度。
  • luminanceStep (number): 亮度适应步长，影响适应速度。

2. EyeDomeLightingPass

位于 five.eyeDomeLightingPass。

• 作用: 增强点云的轮廓和深度感。
• 开启方式: five.eyeDomeLightingPass.enabled = true。
• 配置项:
  • strength (number): 增强强度，值越大轮廓越明显。
  • radius (number): 采样半径，影响阴影的范围。
• 注意: 这是一个基于屏幕空间深度的算法，依赖 Depth Buffer。

3. Optional Built-in Passes (可选内置 Pass)

Five 新增了三个可选使用的内置 Pass，这些 Pass 没有预先挂载在 five 实例上，需手动导入并添加到渲染链中：

• GaussianBlurPass: 高斯模糊效果。
• FlowingLight2DPass: 2D 流光效果（通常用于平面路线流光）。
• FlowingLight3DPass: 3D 流光效果（通常用于空间路径流光）。

GaussianBlurPass 使用示例

import { GaussianBlurPass } from '@realsee/five';

// 1. 创建 GaussianBlurPass 实例 (需要传入 camera)
const gaussianBlurPass = new GaussianBlurPass(five.camera);

// 2. 配置参数
// 设置模糊半径 (默认 4.0)
gaussianBlurPass.setRadius(6);

// 3. 将 Pass 添加到渲染链
five.addPass(gaussianBlurPass);

// 4. (可选) 动态开关
// gaussianBlurPass.enabled = false;

// 5. (可选) 移除 Pass
// five.removePass(gaussianBlurPass);
Copy

Custom Pass (自定义 Pass)

如果需要实现自定义的后处理效果（如景深、色彩校正、描边等），建议继承 FivePass。

步骤

1. 创建类: 继承 FivePass。
2. 声明依赖: 在 super() 中传入需要的 G-Buffer 依赖 (如 ['depth'])。
3. 实现 render: 使用 readBuffer 作为输入，将结果渲染到 writeBuffer (或直接渲染到屏幕)。
4. 挂载: 使用 five.addPass(pass) 将其实例添加到渲染链中。

Examples

开启内置 Pass

import { Five } from '@realsee/five';

const five = new Five();

// 开启自适应亮度
five.adaptiveLuminancePass.enabled = true;
five.adaptiveLuminancePass.luminanceScale = 0.5; // 调整目标亮度

// 开启 EDL (通常用于点云模式)
five.eyeDomeLightingPass.enabled = true;
five.eyeDomeLightingPass.strength = 1.5; // 增强轮廓感

five.needsRender = true;
Copy

自定义 Pass (黑白滤镜)

import * as THREE from 'three';
import { Five, FivePass } from '@realsee/five';
import { FullScreenQuad } from '@realsee/five/lib/five/tools/full-screen-quad'; // 需根据实际路径引用

// 1. 定义 Shader
const grayscaleVertexShader = `
  varying vec2 vUv;
  void main() {
    vUv = uv;
    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
  }
`;

const grayscaleFragmentShader = `
  uniform sampler2D tDiffuse;
  varying vec2 vUv;
  void main() {
    vec4 color = texture2D(tDiffuse, vUv);
    float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));
    gl_FragColor = vec4(vec3(gray), color.a);
  }
`;

// 2. 创建 Pass 类
class GrayscalePass extends FivePass {
  private material: THREE.ShaderMaterial;
  private fsQuad: FullScreenQuad;

  constructor() {
    super(); // 不需要额外的 G-Buffer 依赖，只需要前一个 Pass 的颜色结果
    this.material = new THREE.ShaderMaterial({
      uniforms: {
        tDiffuse: { value: null }
      },
      vertexShader: grayscaleVertexShader,
      fragmentShader: grayscaleFragmentShader
    });
    this.fsQuad = new FullScreenQuad(this.material);
  }

  render(renderer, writeBuffer, readBuffer) {
    // 将上一个 Pass 的结果 (readBuffer) 传给 Shader
    this.material.uniforms.tDiffuse.value = readBuffer.texture;

    if (this.renderToScreen) {
      // 如果是最后一个 Pass，直接渲染到屏幕
      renderer.setRenderTarget(null);
      this.fsQuad.render(renderer);
    } else {
      // 否则渲染到 writeBuffer，供下一个 Pass 使用
      renderer.setRenderTarget(writeBuffer);
      if (this.clear) renderer.clear();
      this.fsQuad.render(renderer);
    }
  }
}

// 3. 挂载到 Five
const grayPass = new GrayscalePass();
five.addPass(grayPass);

// 触发重绘
five.needsRender = true;
Copy

使用 G-Buffer (深度图示例)

如果你的 Pass 需要使用场景的深度信息（例如雾效），可以在构造函数中声明依赖。

class FogPass extends FivePass {
  constructor() {
    super(['depth']); // 声明需要深度图
  }

  render(renderer, writeBuffer, readBuffer) {
    // 获取深度图
    const depthTexture = this.gbuffer.get('depth');

    // 在 Shader 中使用 depthTexture ...
    // this.material.uniforms.tDepth.value = depthTexture;

    // ... 渲染逻辑
  }
}
Copy

Debugging

• 查看 Pass 列表: 检查 five.fiveRenderer.composer.passes 数组，确认 Pass 是否已添加以及顺序是否正确。
• 检查 Enabled 状态: 确保 Pass 实例的 .enabled 属性为 true。
• G-Buffer 调试: 如果自定义 Pass 依赖 G-Buffer 但效果不对，检查 this.gbuffer 是否包含预期的纹理。

Common Pitfalls

1. Pass 顺序: 后处理是按顺序执行的。如果添加了多个 Pass，要注意它们的添加顺序。addPass 会添加到末尾，insertPass 可以插入到指定位置。
2. renderToScreen: 只有链中的最后一个 Pass (且 renderToScreen 为 true) 才会渲染到屏幕。EffectComposer 会自动管理这个标志，但自定义 Pass 必须在 render 方法中正确处理 this.renderToScreen 逻辑。
3. Performance: 过多的后处理 Pass 会显著降低帧率，尤其是在高分辨率屏幕上。尽量合并 Shader 逻辑，避免频繁的 Buffer 拷贝。
4. Dependencies: 只有继承 FivePass 并声明了 dependencies，this.gbuffer 才会有值。普通 Pass 实现无法自动获取 G-Buffer。

Related

• Gaussian Blur Pass: 高斯模糊 Pass 文档。
• Flowing Light 2D Pass: 2D 流光 Pass 文档。
• Flowing Light 3D Pass: 3D 流光 Pass 文档。
• five.ts: 查看 addPass 方法的实现。
• pass.ts: 查看 FivePass 基类定义。

---

tags: [后处理, 特效, 自定义shader, 滤镜, 描边, 景深, 色彩校正, 渲染管线, postprocessing, shader, effect, adaptive-luminance, edl, effect-composer, addPass]
Copy