企业官网建设流程全解析

1. 项目概述：为什么我们需要自定义后效组件？

如果你在Cocos Creator里做过一些3D项目，大概率用过内置的后期效果（Post-Processing），比如泛光（Bloom）、色调映射（Tone Mapping）或者抗锯齿（FXAA）。编辑器里勾选一下，调调参数，效果立马就出来了，非常方便。但不知道你有没有遇到过这样的困境：内置的效果参数调来调去，总觉得差那么点意思，想要一个特殊的模糊效果，或者想把几个效果以非标准的方式组合起来，却发现无从下手。官方提供的后效就像一套精装修的样板间，风格固定，你只能调整家具的位置，却没法改变墙体的结构。

这就是我们今天要聊的核心：自定义渲染管线（Custom Pipeline）中的自定义后效组件。标题里提到的“别再只调内置后效了”，正是这个意思。停留在使用和微调内置效果，就像是只会在别人的代码框架里填空，而掌握自定义后效，意味着你获得了“装修设计图”，可以亲手砌墙、布线，打造独一无二的视觉空间。对于追求特定艺术风格、需要极致性能优化（比如移动端）或者实现一些“黑科技”视觉效果的项目来说，这是必须跨越的一道坎。

以最基础的“模糊”效果为例，它不仅是许多高级效果（如景深、泛光、屏幕空间反射）的基石，其实现过程也完美涵盖了自定义后效的核心流程：创建渲染通道（Pass）、编写着色器（Shader）、管理渲染纹理（Render Texture）、在管线中插入执行。通过封装一个自己的模糊组件，你能彻底理解Cocos Creator的渲染管线是如何组织、调度这些后处理步骤的。这不仅仅是实现一个功能，更是一次对引擎渲染底层机制的深度探索。

2. 核心思路拆解：自定义后效的四大支柱

在动手写代码之前，我们必须先理清思路。在Cocos Creator 3.8的自定义管线框架下，实现一个后效组件，本质上是完成以下四个核心环节的对接。理解它们，就拿到了打开自定义后效大门的钥匙。

2.1 支柱一：渲染管线（Pipeline）—— 流程的指挥官

自定义后效不是孤立存在的，它必须嵌入到一个渲染流程中。在Cocos Creator 3.8中，你需要继承Pipeline类（通常是ForwardPipeline）来创建自己的管线。这个自定义管线定义了渲染一帧的完整步骤：阴影映射、几何渲染、后处理等。我们的后效组件，就需要在这个管线定义的某个“插槽”中被调用。

关键点在于理解管线的render方法。它会依次执行多个RenderPass。后处理效果通常是在主要的场景渲染完成之后，在一个或多个独立的PostProcessPass中执行。你的自定义后效组件，最终会贡献一个或多个Pass，插入到这个后处理阶段。

2.2 支柱二：渲染通道（RenderPass）—— 效果的执行单元

这是后效的核心载体。一个RenderPass定义了一次完整的渲染操作：输入什么（Input Slot）、输出到哪里（Output Slot）、用什么着色器（Shader）、设置哪些渲染状态。对于模糊效果，我们通常需要创建至少一个RenderPass。

例如，高斯模糊通常需要两个Pass（水平模糊和垂直模糊）来高效实现。每个Pass都会接收上一个Pass的输出（或原始场景颜色纹理）作为输入，应用模糊着色器，并将结果渲染到一个中间渲染纹理（RenderTexture）上。

2.3 支柱三：着色器（Shader）—— 效果的灵魂

这是定义“模糊”如何计算的地方。你需要在assets目录下创建.effect文件，在其中编写GLSL着色器代码。一个典型的后效着色器至少包含一个顶点着色器（Vertex Shader）和一个片元着色器（Fragment Shader）。

顶点着色器通常很简单，负责将屏幕空间的四边形（两个三角形）映射到裁剪空间。核心逻辑在片元着色器中，它会采样输入纹理的多个相邻像素，根据某种权重（如高斯核）进行混合，从而产生模糊效果。权重核的大小、标准差等参数，就是我们可以从编辑器调节的变量。

2.4 支柱四：组件（Component）与资源绑定—— 用户交互的桥梁

为了让美术和策划同学能在编辑器里轻松使用你的效果，我们需要将上述技术细节封装成一个普通的Cocos组件。这个组件继承自Component，它负责：

1. 声明属性：在类里用@property装饰器定义模糊半径、强度等参数，这些会自动显示在属性检查器（Inspector）中。
2. 资源管理：关联我们编写的.effect文件和可能用到的其他资源（如噪声图）。
3. 与管线通信：在适当的生命周期（如onEnable,onDisable）中，向当前激活的自定义管线注册或注销自己提供的RenderPass。同时，将组件上设置的参数（如模糊半径）传递给对应的Pass和着色器。

把这四大支柱串联起来，数据流是这样的：用户在场景中为摄像机添加你的“自定义模糊组件” -> 组件向自定义管线注册一个“模糊RenderPass” -> 每一帧，自定义管线在执行后处理阶段时，调用这个“模糊RenderPass” -> Pass使用绑定的“模糊Shader”和组件传来的参数，对输入纹理进行处理 -> 输出模糊后的结果，供后续Pass使用或最终显示。

3. 实战：从零封装高斯模糊后效组件

理论清晰后，我们进入实战环节。我将以“高斯模糊”为例，带你一步步创建完整的自定义后效组件。请确保你使用的是Cocos Creator 3.8或更高版本。

3.1 第一步：创建自定义渲染管线基础框架

首先，我们需要一个自定义管线作为舞台。在你的项目assets目录下，创建一个scripts/pipeline文件夹。

1. 创建自定义管线脚本：新建一个TypeScript文件，例如CustomForwardPipeline.ts。

import { _decorator, CCClass, gfx, pipeline, rendering } from 'cc'; const { ccclass, property } = _decorator; const { ForwardPipeline } = pipeline; const { RenderPass, BaseStage, RenderFlow, RenderStage } = rendering; // 1. 定义一个后处理阶段 (PostProcessStage) class CustomPostProcessStage extends BaseStage { public render (camera: rendering.Camera, renderPass: RenderPass): void { // 这里会汇集所有后效组件的RenderPass并执行 const postProcessPasses = this._pipeline.getPostProcessPasses(camera); for (const pass of postProcessPasses) { pass.render(camera, renderPass); } } } // 2. 创建自定义管线，继承自ForwardPipeline @ccclass('CustomForwardPipeline') export class CustomForwardPipeline extends ForwardPipeline { // 重写init函数，插入我们自定义的后处理阶段 public init (): boolean { if (!super.init()) { return false; } // 找到默认的ForwardFlow const forwardFlow = this._flows.find(flow => flow.name === 'ForwardFlow') as RenderFlow; if (!forwardFlow) { console.error('ForwardFlow not found'); return false; } // 创建一个自定义后处理阶段 const postProcessStage = new CustomPostProcessStage(); postProcessStage.name = 'CustomPostProcessStage'; postProcessStage.initialize(this); // 将这个阶段添加到ForwardFlow的末尾（在默认的PostProcess阶段之后或替换它） // 这里为了简单，我们假设在默认流程后添加。更复杂的做法可能需要重构整个Flow。 // 注意：实际插入位置需要根据引擎版本和需求仔细设计，这里是一个概念示例。 // forwardFlow.addStage(postProcessStage); // 更常见的做法是：替换或扩展管线中管理后效Pass的机制。 // 我们通常会在管线中维护一个后效Pass的列表。 this._postProcessPasses = []; // 用于存储后效组件注册的Pass return true; } // 提供方法让后效组件注册它们的Pass private _postProcessPasses: rendering.RenderPass[] = []; public addPostProcessPass (pass: rendering.RenderPass): void { if (this._postProcessPasses.indexOf(pass) === -1) { this._postProcessPasses.push(pass); // 可能需要根据优先级排序 } } public removePostProcessPass (pass: rendering.RenderPass): void { const index = this._postProcessPasses.indexOf(pass); if (index !== -1) { this._postProcessPasses.splice(index, 1); } } public getPostProcessPasses (camera: rendering.Camera): rendering.RenderPass[] { // 可以根据摄像机筛选不同的后效 return this._postProcessPasses; } }

注意：上述代码中的CustomPostProcessStage和向Flow添加Stage的部分是一个高度简化的概念演示。在Cocos Creator 3.8的实际框架中，更规范的做法是通过实现IPostProcessStage接口或类似机制，将后效Pass集成到引擎定义的后处理阶段中。完全自定义一个Stage并插入Flow需要深入理解引擎内部渲染图（Render Graph）的构建过程，复杂度较高。对于入门，更常见的实践是直接在后效组件中创建Pass，并在组件内管理其生命周期，管线主要负责调度。我们接下来的步骤将采用更贴近实际、更易实现的组件内管理Pass的方式。

3.2 第二步：编写高斯模糊着色器（Shader）

在assets下创建effects文件夹，新建一个custom-gaussian-blur.effect文件。

# 这是一个YAML格式的effect文件 name: custom-gaussian-blur techniques: - passes: - vert: blur-vs frag: blur-fs-horizontal # 水平模糊Pass properties: &props mainTexture: { value: 'white', editor: { type: 'texture' } } textureSize: { value: [1024.0, 1024.0], editor: { visible: false } } # 纹理尺寸，由代码传入 blurRadius: { value: 5.0, editor: { type: 'slider', min: 1, max: 20, step: 1 } } # 模糊半径 blurWeights: { value: [], editor: { visible: false } } # 高斯权重数组，由代码计算传入 - vert: blur-vs frag: blur-fs-vertical # 垂直模糊Pass。复用同一个顶点着色器。 properties: *props # 共享属性定义 # 顶点着色器 - 绘制一个覆盖全屏的四边形 blur-vs: | precision highp float; #include <cc-global> #include <cc-local> in vec3 a_position; in vec2 a_texCoord; out vec2 v_uv; void main () { v_uv = a_texCoord; gl_Position = vec4(a_position, 1.0); } # 片元着色器 - 水平方向高斯模糊 blur-fs-horizontal: | precision highp float; #include <cc-global> in vec2 v_uv; layout(set = 2, binding = 0) uniform sampler2D mainTexture; uniform BlurUniform { vec2 textureSize; float blurRadius; float blurWeights[32]; // 假设最大半径支持到15，需要 (15*2+1)=31个权重，这里取32 }; out vec4 fragColor; void main () { vec2 texelSize = 1.0 / textureSize; vec4 result = vec4(0.0); float weightSum = 0.0; // 从负半径到正半径采样 int kernelSize = int(blurRadius) * 2 + 1; int radius = int(blurRadius); for (int i = -radius; i <= radius; ++i) { float weight = blurWeights[i + radius]; vec2 offset = vec2(float(i) * texelSize.x, 0.0); // 水平方向偏移 result += texture(mainTexture, v_uv + offset) * weight; weightSum += weight; } // 归一化，防止权重和不为1导致亮度变化 fragColor = result / weightSum; } # 片元着色器 - 垂直方向高斯模糊 blur-fs-vertical: | precision highp float; #include <cc-global> in vec2 v_uv; layout(set = 2, binding = 0) uniform sampler2D mainTexture; uniform BlurUniform { vec2 textureSize; float blurRadius; float blurWeights[32]; }; out vec4 fragColor; void main () { vec2 texelSize = 1.0 / textureSize; vec4 result = vec4(0.0); float weightSum = 0.0; int kernelSize = int(blurRadius) * 2 + 1; int radius = int(blurRadius); for (int i = -radius; i <= radius; ++i) { float weight = blurWeights[i + radius]; vec2 offset = vec2(0.0, float(i) * texelSize.y); // 垂直方向偏移 result += texture(mainTexture, v_uv + offset) * weight; weightSum += weight; } fragColor = result / weightSum; }

这个着色器定义了两个Pass，分别进行水平和垂直方向的一维高斯模糊。这样做比直接使用二维高斯核性能更高（复杂度从O(n²)降到O(2n)）。blurWeights数组需要我们在TypeScript代码中根据blurRadius预先计算好高斯核权重并传入。

3.3 第三步：实现高斯模糊渲染通道（BlurRenderPass）

现在创建Pass类，它负责组织渲染状态、着色器资源和执行渲染命令。在scripts/pipeline下创建BlurRenderPass.ts。

import { _decorator, gfx, pipeline, rendering, Vec2 } from 'cc'; const { RenderPass } = rendering; const { Device, CommandBuffer, Texture, RenderPipeline, Format, Filter, Address } = gfx; export class BlurRenderPass extends RenderPass { // 水平模糊和垂直模糊是两个独立的子Pass private _horizontalPass: rendering.RenderPass | null = null; private _verticalPass: rendering.RenderPass | null = null; // 中间渲染纹理，用于存储水平模糊的结果 private _intermediateRT: Texture | null = null; // 着色器资源 private _blurEffectAsset: any = null; // 实际类型是 EffectAsset private _blurMaterial: rendering.Material | null = null; // 属性 private _blurRadius: number = 5; private _textureSize: Vec2 = new Vec2(1024, 1024); private _gaussianWeights: number[] = []; constructor (name: string) { super(name); this._priority = rendering.RenderPriority.POST_PROCESS; // 设置为后处理优先级 } // 初始化Pass，创建子Pass和Material public initialize (device: Device, effectAsset: any, renderPass: RenderPass): boolean { this._blurEffectAsset = effectAsset; // 从effectAsset创建材质 this._blurMaterial = new rendering.Material(); this._blurMaterial.initialize({ effectAsset: this._blurEffectAsset }); // 创建水平模糊的子Pass this._horizontalPass = new RenderPass('BlurHorizontal'); this._horizontalPass.initialize(device); // 这里需要配置RenderPass的渲染状态、着色器变体等，简化处理 // 实际中需要更详细的setup，例如设置使用的Material和Pass索引(0) // 创建垂直模糊的子Pass (使用同一个Material，但Pass索引为1) this._verticalPass = new RenderPass('BlurVertical'); this._verticalPass.initialize(device); // 计算初始高斯权重 this._updateGaussianWeights(); return true; } // 每一帧渲染前调用，用于更新参数、分配渲染纹理等 public update (camera: rendering.Camera, pipeline: pipeline.RenderPipeline): void { if (!this._blurMaterial || !this._horizontalPass || !this._verticalPass) return; // 获取当前渲染的屏幕尺寸（或后效输入纹理的尺寸） const mainWindow = pipeline.mainWindow; if (mainWindow) { this._textureSize.x = mainWindow.width; this._textureSize.y = mainWindow.height; } // 更新材质参数 const pass = this._blurMaterial.passes[0]; // 假设第一个Pass是水平模糊 pass.setUniform('textureSize', this._textureSize); pass.setUniform('blurRadius', this._blurRadius); pass.setUniformArray('blurWeights', this._gaussianWeights); // 垂直模糊Pass的参数会在渲染时单独设置，但权重和半径是一样的 // 检查并创建/调整中间渲染纹理 this._setupRenderTextures(pipeline.device); } // 执行渲染 public render (camera: rendering.Camera, renderPass: RenderPass): void { if (!this._horizontalPass || !this._verticalPass || !this._intermediateRT) return; const pipeline = renderPass.pipeline as pipeline.RenderPipeline; const cmdBuff = pipeline.commandBuffers[0]; // **Pass 1: 水平模糊到中间纹理** // 1. 设置渲染目标为 _intermediateRT // 2. 绑定输入纹理（通常是上一Pass的输出或场景颜色） // 3. 使用水平模糊的Material Pass (index 0) 绘制全屏四边形 // 伪代码： // cmdBuff.beginRenderPass(this._horizontalPass, this._intermediateRT, ...); // cmdBuff.bindMaterial(this._blurMaterial, 0); // 使用第一个pass (水平) // cmdBuff.draw(...); // 绘制全屏Quad // cmdBuff.endRenderPass(); // **Pass 2: 垂直模糊到最终目标** // 1. 设置渲染目标为 renderPass 的输出（或下一个后效的输入） // 2. 绑定输入纹理为 _intermediateRT（水平模糊的结果） // 3. 使用垂直模糊的Material Pass (index 1) 绘制全屏四边形 // cmdBuff.beginRenderPass(this._verticalPass, renderPass.framebuffer, ...); // cmdBuff.bindMaterial(this._blurMaterial, 1); // 使用第二个pass (垂直) // cmdBuff.bindTexture(..., this._intermediateRT); // 绑定水平模糊结果 // cmdBuff.draw(...); // cmdBuff.endRenderPass(); console.log(`[BlurRenderPass] Rendering blur with radius ${this._blurRadius}`); } // 设置模糊半径 public setBlurRadius (radius: number): void { if (radius !== this._blurRadius) { this._blurRadius = Math.max(1, Math.min(radius, 15)); // 限制范围 this._updateGaussianWeights(); } } public getBlurRadius (): number { return this._blurRadius; } // 清理资源 public destroy (): void { if (this._intermediateRT) { this._intermediateRT.destroy(); this._intermediateRT = null; } // 清理子Pass和Material... super.destroy(); } // --- 私有方法 --- private _updateGaussianWeights (): void { const radius = this._blurRadius; const sigma = radius / 2.0; // 高斯函数的标准差，影响模糊形状 this._gaussianWeights.length = 0; let weightSum = 0.0; const kernelSize = radius * 2 + 1; // 计算一维高斯核权重 for (let i = -radius; i <= radius; i++) { const weight = Math.exp(-(i * i) / (2 * sigma * sigma)) / (Math.sqrt(2 * Math.PI) * sigma); this._gaussianWeights.push(weight); weightSum += weight; } // 归一化权重，使和为1 for (let i = 0; i < this._gaussianWeights.length; i++) { this._gaussianWeights[i] /= weightSum; } // 如果着色器定义的数组更大，用0填充剩余部分（避免UBO数据不对齐问题） while (this._gaussianWeights.length < 32) { this._gaussianWeights.push(0.0); } } private _setupRenderTextures (device: Device): void { const neededWidth = Math.floor(this._textureSize.x); const neededHeight = Math.floor(this._textureSize.y); // 如果中间RT不存在或尺寸不对，则创建/重建 if (!this._intermediateRT || this._intermediateRT.width !== neededWidth || this._intermediateRT.height !== neededHeight) { if (this._intermediateRT) { this._intermediateRT.destroy(); } // 创建用于存储水平模糊结果的渲染纹理 // 格式通常与场景颜色缓冲区一致，如Format.RGBA8 this._intermediateRT = device.createTexture(new gfx.TextureInfo( gfx.TextureType.TEX2D, gfx.TextureUsageBit.COLOR_ATTACHMENT | gfx.TextureUsageBit.SAMPLED, Format.RGBA8, neededWidth, neededHeight )); } } }

这个BlurRenderPass类封装了模糊效果的核心渲染逻辑。它管理了两个子Pass（水平/垂直），一个中间渲染纹理，以及关联的着色器材质。updateGaussianWeights函数根据设置的模糊半径动态计算高斯核权重，这是实现可调节模糊效果的关键。

3.4 第四步：创建用户组件（CustomBlurComponent）

最后，我们创建用户实际挂在摄像机（或任何节点）上的组件。在scripts/components下创建CustomBlurComponent.ts。

import { _decorator, Component, Node, CCBoolean, CCFloat, renderer, director } from 'cc'; import { BlurRenderPass } from '../pipeline/BlurRenderPass'; // 假设路径 const { ccclass, property, menu, executeInEditMode } = _decorator; const { Pipeline } = renderer; @ccclass('CustomBlurComponent') @menu('PostProcess/CustomBlur') @executeInEditMode // 允许在编辑器内预览效果 export class CustomBlurComponent extends Component { // 在属性检查器中显示的参数 @property({ type: CCFloat, tooltip: '模糊半径（像素）', min: 1, max: 20, slide: true }) public blurRadius: number = 5.0; @property({ type: CCBoolean, tooltip: '是否启用效果' }) public enabledEffect: boolean = true; // 内部持有的RenderPass实例 private _blurPass: BlurRenderPass | null = null; // 关联的EffectAsset private _blurEffect: any = null; onLoad () { // 动态加载我们编写的高斯模糊Effect资源 // 注意：实际项目中，建议通过bundle或预加载方式获取，避免运行时加载卡顿 // 这里为了演示，使用resources.load // resources.load('effects/custom-gaussian-blur', (err, asset) => { // if (err) { console.error(err); return; } // this._blurEffect = asset; // this._tryInitializePass(); // }); // 简化：假设Effect已通过其他方式加载或引用 this._tryInitializePass(); } onEnable () { // 组件启用时，向当前渲染管线注册我们的Pass this._registerToPipeline(); } onDisable () { // 组件禁用时，从管线中注销 this._unregisterFromPipeline(); } onDestroy () { // 清理资源 if (this._blurPass) { this._blurPass.destroy(); this._blurPass = null; } } update (deltaTime: number) { if (!this._blurPass || !this.enabledEffect) return; // 如果编辑器或运行时修改了参数，同步到Pass // 这里可以添加参数变化的检查，例如： // if (this._lastBlurRadius !== this.blurRadius) { // this._blurPass.setBlurRadius(this.blurRadius); // this._lastBlurRadius = this.blurRadius; // } this._blurPass.setBlurRadius(this.blurRadius); } // --- 私有方法 --- private _tryInitializePass (): void { if (this._blurPass || !this._blurEffect) return; // 创建BlurRenderPass实例 this._blurPass = new BlurRenderPass('CustomGaussianBlur'); // 这里需要获取当前的Device和RenderPass来进行初始化，简化处理 // const pipeline = director.root?.pipeline; // if (pipeline && pipeline instanceof CustomForwardPipeline) { // const device = pipeline.device; // const mainRenderPass = ...; // 需要获取合适的RenderPass // this._blurPass.initialize(device, this._blurEffect, mainRenderPass); // } console.log('[CustomBlurComponent] Blur pass initialized.'); } private _registerToPipeline (): void { if (!this._blurPass || !this.enabledEffect) return; const root = director.root; if (!root) return; const pipeline = root.pipeline; // 检查当前管线是否是我们自定义的管线，或者支持添加后效Pass的管线 // if (pipeline && (pipeline as any).addPostProcessPass) { // (pipeline as any).addPostProcessPass(this._blurPass); // console.log('[CustomBlurComponent] Blur pass registered to pipeline.'); // } else { // console.warn('[CustomBlurComponent] Current pipeline does not support custom post-process passes.'); // } // 简化：直接打印日志 console.log('[CustomBlurComponent] Attempting to register blur pass.'); } private _unregisterFromPipeline (): void { if (!this._blurPass) return; const root = director.root; if (!root) return; const pipeline = root.pipeline; // if (pipeline && (pipeline as any).removePostProcessPass) { // (pipeline as any).removePostProcessPass(this._blurPass); // console.log('[CustomBlurComponent] Blur pass unregistered from pipeline.'); // } console.log('[CustomBlurComponent] Attempting to unregister blur pass.'); } }

这个组件是用户交互的界面。它暴露了blurRadius和enabledEffect参数到编辑器，并在其生命周期内管理BlurRenderPass的创建、注册、更新和销毁。@menu装饰器为它在编辑器的组件菜单中创建了一个便捷的入口。

3.5 第五步：在项目中使用自定义管线和组件

1. 设置自定义渲染管线：在项目设置（Project Settings）的“功能裁剪”（Feature Cropping）或“渲染管线”（Rendering Pipeline）部分，将默认管线切换为你创建的CustomForwardPipeline。具体路径取决于Cocos Creator版本，通常在“项目设置 -> 管线”中。
2. 添加效果组件：在场景中选中主摄像机（Main Camera）节点，在属性检查器中点击“添加组件”，在“PostProcess”分类下找到“CustomBlur”并添加。
3. 调整参数：添加后，你可以在组件属性中实时调整“模糊半径”，并在场景预览或游戏运行时看到模糊效果的变化。

4. 深度解析与性能优化实战

一个能跑起来的基础模糊组件只是开始。要让它在实际项目中可用、好用且高效，我们还需要深入更多细节。

4.1 着色器优化：从O(n)到O(1)的采样技巧

我们之前的高斯模糊着色器在片元着色器中使用了一个循环，循环次数取决于模糊半径。如果半径设为10，每个像素就需要采样21次（水平+垂直共42次），性能开销很大。一个经典的优化技巧是利用GPU的线性纹理过滤进行双线性采样。

原理是：高斯模糊的权重分布是对称且连续的。我们可以将多个采样点及其权重，合并为对纹理中间某一点的一次采样。GPU在采样非整数坐标时，会自动在相邻四个纹素间进行双线性插值。通过精心计算采样坐标和对应的混合权重，我们可以用远少于核大小的采样次数来近似高斯模糊。

例如，一个5x5的高斯核，传统需要25次采样。优化后，我们可以只采样4个点（上、下、左、右各一个偏移点），但每个采样点的坐标是计算出来的非整数位置，使得GPU的一次采样实际上混合了周围多个纹素，近似了高斯权重。这通常被称为“优化分离高斯模糊”或“利用硬件线性过滤”。

修改后的片元着色器核心思路（以水平方向为例）：

void main () { vec2 texelSize = 1.0 / textureSize; vec4 result = vec4(0.0); // 假设我们预计算了4个优化后的采样偏移和权重（通过脚本传入） for (int i = 0; i < 4; ++i) { // offsetWeights[i].xy 是偏移向量，.z 是权重 vec3 ow = u_offsetWeights[i]; // 采样非整数坐标，利用硬件过滤 result += texture(mainTexture, v_uv + ow.xy * texelSize.x) * ow.z; } fragColor = result; }

这需要你在TypeScript端预先计算好这些优化的偏移和权重。对于移动端或性能敏感场景，这种优化至关重要。

4.2 渲染纹理管理：Downsample与缓存

全分辨率进行模糊计算非常昂贵，尤其是对于移动设备。常见的优化手段是降采样（Downsample）。

1. 创建降采样链：在水平模糊之前，先将输入纹理（场景颜色）渲染到一个尺寸减半（如1/2或1/4）的渲染纹理中。在这个低分辨率纹理上进行模糊操作，性能会成倍提升。
2. 模糊后再上采样：垂直模糊（或最终输出）可以仍在低分辨率进行，最后用一个简单的双线性或双三次上采样Pass将结果放大到屏幕分辨率。对于全屏的、美学性的模糊（如UI背景模糊），视觉损失通常可以接受。
3. 纹理缓存：如果你的游戏有多个后效，且它们顺序执行，中间会产生多个临时RT。应该设计一个RT池（Render Texture Pool），根据尺寸和格式复用这些纹理，避免每一帧都创建和销毁，减少GC压力。

在BlurRenderPass的_setupRenderTextures方法中，你可以根据一个downsampleFactor（如2）来创建尺寸更小的中间纹理。

4.3 与内置后效的兼容与排序

你的自定义后效可能需要和内置的Bloom、Color Grading等一起工作。这就涉及到后效执行顺序的问题。例如，通常色调映射（Tone Mapping）应该在所有颜色处理完成后最后执行。你的模糊效果应该在Bloom之前还是之后？这取决于你想要的效果。

在自定义管线中，你需要管理一个后效Pass的列表，并允许设置优先级。BlurRenderPass中的_priority属性就是用于此目的。在管线的渲染方法中，你需要根据这个优先级对_postProcessPasses数组进行排序，然后依次执行。

// 在CustomForwardPipeline的某个渲染阶段 this._postProcessPasses.sort((a, b) => a.priority - b.priority); for (const pass of this._postProcessPasses) { pass.render(camera, currentRenderPass); }

4.4 编辑器集成与实时预览

为了让美术设计师更高效地工作，我们需要加强编辑器集成：

1. 属性联动：当在编辑器中修改blurRadius时，不仅组件属性变化，还应能实时预览效果。这需要组件在onFocusInEditor或属性setter被调用时，立即将参数同步给BlurRenderPass并触发场景视图重绘。@executeInEditMode装饰器允许组件在编辑器下运行update函数，是实现实时预览的基础。
2. 效果开关：enabledEffect属性应该能立刻在场景视图中启用/禁用效果，而不需要运行游戏。
3. 自定义UI（进阶）：对于复杂的参数（如权重曲线），你可以通过定义@property的editor字段来提供滑块、颜色选择器或曲线编辑器，提升易用性。

5. 常见问题、调试技巧与避坑指南

在实际开发和集成自定义后效时，你会遇到各种“坑”。以下是我从项目中总结的一些典型问题和解决方案。

5.1 问题一：屏幕上一片黑或粉红色（无效纹理）

• 现象：启用自定义后效后，屏幕变黑、粉红或显示其他异常颜色。
• 排查思路：
  1. 检查着色器编译：首先确认你的.effect文件没有语法错误。在Cocos Creator的“控制台”中查看是否有着色器编译错误。你可以临时在着色器开头写fragColor = vec4(1.0, 0.0, 0.0, 1.0);输出纯红色，如果屏幕变红，说明着色器基本执行了，问题在后续逻辑。
  2. 检查纹理绑定：确保你的Pass正确绑定了输入纹理（mainTexture）。最常见的错误是纹理单元（Binding）设置不对，或者传入的纹理对象是null。在渲染命令中，使用cmdBuff.bindTexture后，检查绑定点是否与着色器中的layout(set=x, binding=y)声明匹配。
  3. 检查渲染目标（Framebuffer）：确认beginRenderPass时设置的渲染目标（Render Target）是有效的。如果是渲染到中间纹理，确保该纹理已成功创建且格式正确（例如，具有COLOR_ATTACHMENT用途位）。全黑有时意味着渲染目标清除颜色是黑色且没有绘制任何内容。
  4. 检查视口和裁剪：确保渲染Pass的视口（Viewport）和裁剪矩形（Scissor）设置正确，覆盖了整个屏幕。

5.2 问题二：模糊效果不对（有重影、方向错误或没效果）

• 现象：模糊看起来很奇怪，不是均匀的模糊，或者根本没有模糊感。
• 排查思路：
  1. 验证权重计算：在TypeScript端打印出计算出的_gaussianWeights数组，检查其和是否接近1，以及分布是否对称、平滑。错误的权重会导致模糊不均匀。
  2. 检查纹理坐标和偏移：在着色器中，将v_uv直接输出为颜色（fragColor = vec4(v_uv, 0.0, 1.0);），检查UV是否正确映射（屏幕左下角(0,0)，右上角(1,1)）。然后检查偏移量offset的计算。texelSize计算是否正确？texelSize = 1.0 / textureSize，其中textureSize是纹理的像素尺寸（如 (1920, 1080)），而不是归一化的。
  3. 分离测试：分别测试水平模糊和垂直模糊。可以先将垂直模糊的权重全部设为0（除了中心点为1），只观察水平模糊的效果，看条纹是否是水平的。
  4. 采样器状态：确保用于采样的纹理的采样器（Sampler）设置正确。对于后处理，通常需要Filter.LINEAR（线性过滤）和Address.CLAMP_TO_EDGE（边缘钳制），以避免边缘出现奇怪的颜色。

5.3 问题三：性能急剧下降

• 现象：开启效果后，帧率（FPS）大幅降低。
• 排查思路与优化：
  1. Profile工具：使用Cocos Creator的分析器（Profiler），特别是渲染（Rendering）部分，查看Draw Call数量、三角面片数以及GPU时间。确认性能瓶颈是在你的后效Pass上。
  2. 降低采样次数：如上文所述，采用优化采样技术，将采样次数从2*radius+1减少到固定的4或6次。
  3. 实施降采样：这是提升模糊性能最有效的手段。尝试以1/2或1/4分辨率进行模糊计算。
  4. 减少不必要的全屏绘制：确保你的后效只在需要时执行。例如，可以通过一个开关变量控制，或者只在摄像机看到特定图层时才启用。
  5. 检查RT创建：避免在每帧的update中都创建新的渲染纹理。确保纹理创建和销毁在initialize和destroy中管理，或者使用纹理池。

5.4 问题四：与UI渲染冲突

• 现象：模糊效果把UI也模糊了，或者UI显示在模糊效果之上/之下不正确。
• 原因与解决：Cocos Creator的渲染顺序通常是：3D场景 -> 后处理 -> UI。如果你的后效作用于整个屏幕缓冲区，自然会包含UI。
  • 方案A（推荐）：将后效的输入指定为场景颜色缓冲区，而不是最终的屏幕缓冲区。在自定义管线中，你需要获取到渲染完3D场景但尚未与UI混合的那个纹理。这通常涉及到更精细的管线设置，使用不同的RenderTarget。
  • 方案B：如果UI需要特殊的混合（如半透明），你可能需要设计更复杂的渲染流程，或者将UI渲染到一个单独的纹理，最后再与后效结果合成。这属于高级话题，需要对引擎的渲染图有更深理解。

5.5 调试利器：Frame Debugger与RenderDoc

当视觉问题复杂时，光靠猜和打印日志是不够的。

1. Cocos Creator Frame Debugger：在编辑器运行游戏时，打开开发者 -> 帧调试器（Frame Debugger）。你可以逐帧、逐Pass地查看渲染命令、状态和纹理内容。这是查看你的自定义Pass是否被正确插入和执行的最直观工具。你可以检查每个Pass的输入输出纹理，对比预期。
2. RenderDoc：一个强大的独立GPU调试工具。抓取一帧，你可以看到所有API级别的调用（如glDrawElements）、绑定的纹理数据、着色器代码和生成的像素。当遇到极其诡异的渲染问题时（如驱动兼容性问题），RenderDoc是终极武器。你可以检查传入着色器的uniform值是否正确，纹理数据是否符合预期。

封装自定义后效组件，尤其是从模糊这样的基础效果入手，是深入理解现代游戏引擎渲染管线的绝佳路径。它迫使你去思考数据如何流动、GPU指令如何组织、资源如何管理。当你成功让第一个自定义模糊效果在屏幕上显现时，那种对底层控制的成就感，是单纯使用内置效果无法比拟的。更重要的是，这套方法论可以平移到任何其他后效：运动模糊、景深、屏幕空间环境光遮蔽（SSAO）、色彩查找表（LUT）调色等等。你不再被引擎提供的工具所限制，而是获得了创造视觉新可能的自由。