Unity ScriptableRenderFeature与注入点完全指南

深入理解 URP 渲染管线的可编程注入点避免采样黑屏与时序错误掌握自定义 Pass 的正确姿势什么是 ScriptableRenderFeatureScriptableRenderFeature 是 Unity URPUniversal Render Pipeline提供的核心扩展机制。它允许开发者在渲染管线的任意阶段插入自定义的渲染逻辑实现诸如后处理效果、深度/法线抓取、自定义光照等高级功能。核心概念ScriptableRenderFeature 功能定义何时执行 ScriptableRenderPass 执行逻辑做什么。二者配合使用构成了 URP 渲染管线的插件系统。URP 渲染管线阶段一览注入点资源可用性对照表不同的注入点对渲染资源的可用性各不相同。以下表格详细列出了各注入点可以安全访问的纹理资源注入点 (RenderPassEvent)深度图 _CameraDepthTexture颜色图(Opaque) _CameraOpaqueTexture颜色图(Transparent)BeforeRenderingOpaques✓ 已完成✓ 已完成✗ 未写入AfterRenderingOpaques✓ 已完成✓ 已完成✗ 未写入BeforeRenderingTransparents✓ 已完成✓ 已完成△ 部分可用AfterRenderingTransparents✓ 已完成✓ 已完成✓ 已完成BeforeRenderingPostProcessing✓ 已完成✓ 已完成✓ 已完成AfterRenderingPostProcessing✓ 已完成✓ 已完成✓ 已完成关键提醒深度图和颜色图的抓取需要在 UniversalRenderer Data 资产中启用相应选项。默认情况下这些纹理可能不会被生成。完整代码示例创建自定义 Render Feature第一步定义 ScriptableRenderPassusing UnityEngine.Rendering.Universal; using UnityEngine.Rendering; public class CustomRenderPass : ScriptableRenderPass { // Pass 运行时数据 private RenderTargetIdentifier tempRT; private Material customMaterial; // 设置材质和其他资源 public void Setup(Material mat) { customMaterial mat; } // 核心执行逻辑 public override void Execute( ScriptableRenderContext context, ref RenderingDataRendering cameraTargetSettings renderingData) { if (customMaterial null) return; var cmd new CommandBuffer(); cmd.name Custom Effect Pass; // 在此处添加渲染逻辑 // 例如Blit、绘制全屏Quad等 context.ExecuteCommandBuffer(cmd); cmd.Release(); } }第二步创建 ScriptableRenderFeatureusing UnityEngine; using UnityEngine.Rendering.Universal; public class CustomRenderFeature : ScriptableRendererFeature { // ★ 核心选择正确的注入点 // 可选BeforeRenderingOpaques / AfterRenderingOpaques / // BeforeRenderingTransparents / AfterRenderingTransparents / // BeforeRenderingPostProcessing / AfterRenderingPostProcessing public RenderPassEvent passEvent RenderPassEvent.AfterRenderingOpaques; private CustomRenderPass customPass; public Material customMaterial; // 初始化 Pass 实例 public override void Create() { customPass new CustomRenderPass(); // 设置 Pass 的注入点和渲染优先级 customPass.renderPassEvent passEvent; } // 将 Pass 添加到渲染管线 public override void AddRenderPasses( ScriptableRenderer renderer, ref RenderingData renderingData) { // 配置 Pass 并入队 customPass.Setup(customMaterial); renderer.EnqueuePass(customPass); } }第三步在 Pass 中正确采样纹理public override void Execute( ScriptableRenderContext context, ref RenderingData renderingData) { var cameraData renderingData.cameraData; var cmd new CommandBuffer(); // // ★ 核心安全采样渲染资源 // // 1. 采样深度图如果需要 // 在 AfterRenderingOpaques 时深度图已可用 if (cameraData.camera.depthTextureMode.HasFlag(DepthTextureMode.Depth)) { var depthTex Shader.GetGlobalTexture(_CameraDepthTexture); cmd.SetGlobalTexture(_MyDepthTex, depthTex); } // 2. 采样不透明颜色图如果需要 // 使用 _CameraOpaqueTexture 采样不透明物体渲染结果 var opaqueTex Shader.GetGlobalTexture(_CameraOpaqueTexture); cmd.SetGlobalTexture(_MyOpaqueTex, opaqueTex); // 3. 应用自定义效果使用 Blit var tempRT RenderTexture.GetTemporary( cameraData.camera.pixelWidth, cameraData.camera.pixelHeight, 0, RenderTextureFormat.Default ); cmd.Blit(RenderTargetIdentifier.None, tempRT, customMaterial); cmd.Blit(tempRT, cameraData.targetTexture); RenderTexture.ReleaseTemporary(tempRT); context.ExecuteCommandBuffer(cmd); cmd.Release(); }常见错误与解决方案问题一在透明物体 Pass 中采样透明颜色图得到黑屏错误代码位置在BeforeRenderingTransparents或更早的位置尝试采样透明物体的渲染结果。原因透明物体的颜色缓冲在BeforeRenderingTransparents时还未被写入此时读取只能得到黑屏或旧数据。解决方案将采样逻辑移到AfterRenderingTransparents注入点class TransparentGrabPass : ScriptableRenderPass { public override void Execute(ScriptableRenderContext context, RefRenderingData renderingData) { // ✅ 在 AfterRenderingTransparents 时可以安全采样 var cmd new CommandBuffer(); var transparentTex RenderingUtils.GetTransparentTexture(renderingData); // 现在 transparentTex 包含正确的透明物体渲染结果 } }问题二在 Opaque 渲染前采样颜色图获得的是上一帧数据错误理解以为BeforeRenderingOpaques时颜色图已经是当前帧的内容。实际原因颜色图是在上一帧的AfterRenderingOpaques阶段写入的并非当前帧。解决方案如果需要当前帧的不透明物体结果在AfterRenderingOpaques之后使用AfterRenderingOpaques- 采样当前帧不透明结果推荐BeforeRenderingTransparents- 同样可用AfterRenderingTransparents- 全部渲染完成后问题三深度图在某些设备上不可用表现在 Editor 中正常但在某些 Android/iOS 设备上出现黑屏或深度效果错误。原因未在 Renderer Data 中正确配置深度纹理或设备不支持所需格式。解决方案在 URP Asset 中启用 Depth Texture 选项// 在 Pass 中检查深度图可用性 public override void Execute(ScriptableRenderContext context, RefRenderingData renderingData) { var cameraData renderingData.cameraData; if (!cameraData.camera.depthTextureMode..HasFlag(DepthTextureMode.Depth)) { Debug.LogWarning(Depth texture not available! Enable it in Renderer Data.); return; } // 安全使用深度图 var depthTex Shader.GetGlobalTexture(_CameraDepthTexture); }最佳实践总结Opaque 物体效果深度图可用颜色图(Opaque)可用颜色图(Transparent)不可用使用注入点AfterRenderingOpaques透明物体效果深度图可用颜色图(Opaque)可用颜色图(Transparent)可用使用注入点AfterRenderingTransparents全场景后处理深度图可用颜色图(Opaque)可用颜色图(Transparent)可用使用注入点Before/AfterRenderingPostProcessing延迟写入所有纹理可用最终合成的完整画面无法再修改透明物体使用注入点AfterRenderingPostProcessing