泛光(Bloom)
泛光是相机/显示器对亮 HDR 信号的响应。将其作为一个由场景亮度驱动的节点管线效果来教授,而不是作为对象或效果的唯一可见形式。
架构优先
生产路径是来自 three/webgpu 的最新 Three.js WebGPURenderer,来自 three/tsl 的 TSL,RenderPipeline、pass()、mrt({ output, emissive }),以及来自 bloom() 的 BloomNode。
从场景通道 MRT 自发光输出构建选择性泛光:
带有 MRT 输出 + 自发光输出的场景通道
-> 场景颜色纹理节点
-> 自发光贡献纹理节点
-> bloom(emissive).setResolutionScale(...)
-> 场景颜色 + 泛光
-> 单个 renderOutput / outputColorTransform 拥有者
这是本技能的最高级架构:一个场景渲染,直接 MRT 选择性贡献,在最终输出变换之前保留 HDR 信号,并为昂贵的模糊工作提供逐通道分辨率缩放。
阅读 references/hdr-bloom-system.md 以了解 r185 时代的 WebGPU/TSL 骨架、能力门控、质量等级、预算、颜色规则、诊断和替换说明。
规范的 WebGPU/TSL 示例:examples/node-selective-bloom/。
工作流程
- 当泛光作为更大图像流水线的一部分时,运行
$threejs-choose-skills预检。 - 使用
NodeMaterial材质编写自发光贡献并将其路由到 MRTemissive。 - 从自发光纹理节点(而不是从单独的场景渲染)提供
BloomNode。 - 在预色调映射的 HDR 中调整
strength、radius、threshold、smoothWidth和setResolutionScale()。 - 保持恰好一个色调映射和输出转换拥有者。
- 在桌面独立显卡、桌面集成显卡和移动设备预算上验证基础、自发光贡献、仅泛光及最终输出视图。
能力门控
任何使用 MRT 或存储资源的实现都必须在渲染器初始化之后进行门控:
await renderer.init();
if ( renderer.backend.isWebGPUBackend !== true ) {
throw new Error(
'threejs-bloom 需要 WebGPU 后端。如果用户明确询问如何在 WebGPU 不可用时应用回退方案,请路由到 threejs-compatibility-fallbacks。'
);
}
// WebGPU 等级可能会降低 bloomScale、pixelRatioCap、贡献者数量,或禁用泛光,同时保留可读的基础场景。
传统的 WebGL 实现(已弃用,请勿扩展):此技能文件夹中没有;明确的回退请求路由到 $threejs-compatibility-fallbacks。
失败条件
- 泛光成为效果的唯一可见形式;
- 普通的漫反射或光照表面泄漏到自发光贡献目标中;
- 所有明亮材质共享一个任意发射倍增器;
- 在色调映射或显示转换之后调整阈值;
- 多个系统拥有色调映射或输出颜色转换;
- 在带宽受限的设备上默认以全分辨率运行泛光通道;
- 调整大小路径省略了
setSize()或分辨率缩放验证; - 高光变灰,因为 HDR 能量在泛光之前被钳制。
路由边界
使用 $threejs-exposure-color-grading 进行测光、适应、色调映射和 LUT。当泛光需要共享深度、法线、AO、TAA 或其他图像空间资源时,使用 $threejs-image-pipeline。使用 $threejs-visual-validation 进行固定视图通道诊断和 GPU 计时证据。