XCEngine/docs/Unity SRP API参考文档.md

# Unity SRP (Scriptable Render Pipeline) API 参考文档

## 1. 概述

Unity 的可编写脚本渲染管线 (Scriptable Render Pipeline, SRP) 是一项允许通过 C# 脚本控制渲染的功能。SRP 是通用渲染管线 (URP) 和高清渲染管线 (HDRP) 的底层技术基础。

**命名空间**: `UnityEngine.Rendering`

---

## 2. 核心类 API

### 2.1 RenderPipeline 类

**命名空间**: `UnityEngine.Rendering`

**描述**: 提供实现可编写脚本渲染管线的渲染逻辑的方式。继承自此类以重写 `Render` 方法来实现自定义 SRP。

**示例代码**:
```csharp
using UnityEngine;
using UnityEngine.Rendering;
using System.Collections.Generic;  

public class CustomRenderPipeline : RenderPipeline
{
    protected override void Render(ScriptableRenderContext context, List<Camera> cameras)
    {
        // 实现自定义 SRP 渲染逻辑
    }
}
```

**属性**:
| 属性 | 描述 |
|------|------|
| `disposed` | 返回 true 表示 RenderPipeline 无效或已销毁 |

**受保护的方法**:
| 方法 | 描述 |
|------|------|
| `IsPreviewSupported()` | 指定相机是否可以预览 |
| `IsRenderRequestSupported()` | 实现此方法以指定特定的相机和渲染请求组合是否受支持 |
| `ProcessRenderRequests()` | 执行使用 RenderPipeline.SubmitRenderRequest 提交的渲染请求 |
| `Render()` | 定义此 RenderPipeline 自定义渲染的入口点方法 |

**静态方法**:
| 方法 | 描述 |
|------|------|
| `BeginCameraRendering(ScriptableRenderContext, Camera)` | 调用 RenderPipelineManager.beginCameraRendering 委托 |
| `BeginContextRendering(ScriptableRenderContext, List<Camera>)` | 调用 RenderPipelineManager.beginContextRendering 和 beginFrameRendering 委托 |
| `BeginFrameRendering(ScriptableRenderContext, List<Camera>)` | 调用 RenderPipelineManager.beginFrameRendering 委托 |
| `EndCameraRendering(ScriptableRenderContext, Camera)` | 调用 RenderPipelineManager.endCameraRendering 委托 |
| `EndContextRendering(ScriptableRenderContext, List<Camera>)` | 调用 RenderPipelineManager.endContextRendering 和 endFrameRendering 委托 |
| `EndFrameRendering(ScriptableRenderContext, List<Camera>)` | 调用 RenderPipelineManager.endFrameRendering 委托 |
| `SubmitRenderRequest(Camera, RenderRequest)` | 向相机提交渲染请求（在 Unity 渲染循环之外） |
| `SupportsRenderRequest(Camera, RequestData)` | 检查渲染管线是否支持使用相机的 RequestData 类型 |
| `ProcessRenderRequests(List<RenderRequest>)` | 执行使用 Camera.SubmitRenderRequest 提交的渲染请求 |

---

### 2.2 RenderPipelineAsset 类

**命名空间**: `UnityEngine.Rendering`

**继承**: `ScriptableObject`

**描述**: 生成特定 IRenderPipeline 的资源。IRenderPipelineAsset 的默认实现。管理继承类型的生命周期，并确保创建的 IRenderPipeline 在资源更改时失效。

**属性**:
| 属性 | 描述 |
|------|------|
| `autodeskInteractiveMaskedShader` | 获取此管线的默认 Autodesk Interactive 遮罩 Shader |
| `autodeskInteractiveShader` | 获取此管线的默认 Autodesk Interactive Shader |
| `autodeskInteractiveTransparentShader` | 获取此管线的默认 Autodesk Interactive 透明 Shader |
| `default2DMaskMaterial` | 获取 Sprite Masks 使用的默认 2D 遮罩材质 |
| `default2DMaterial` | 返回此管线的默认 2D 材质 |
| `defaultLineMaterial` | 返回此管线的默认线条材质 |
| `defaultMaterial` | 返回此管线的默认材质 |
| `defaultParticleMaterial` | 返回此管线的默认粒子材质 |
| `defaultShader` | 返回此管线的默认 Shader |
| `defaultSpeedTree7Shader` | 返回 SpeedTree v7 Shader |
| `defaultSpeedTree8Shader` | 返回 SpeedTree v8 Shader |
| `defaultSpeedTree9Shader` | 返回 SpeedTree v9 Shader |
| `defaultTerrainMaterial` | 返回此管线的默认地形材质 |
| `defaultUIETC1SupportedMaterial` | 返回默认 UI ETC1 材质 |
| `defaultUIMaterial` | 返回默认 UI 材质 |
| `defaultUIOverdrawMaterial` | 返回默认 UI overdraw 材质 |
| `pipelineType` | 返回与此 RenderPipelineAsset 实例关联的 RenderPipeline 类型 |
| `renderPipelineShaderTag` | 返回此资源描述的渲染管线的 Shader Tag 值 |
| `terrainBrushPassIndex` | 编辑器中地形笔刷的渲染索引 |
| `terrainDetailGrassBillboardShader` | 返回此管线的细节草 Billboard Shader |
| `terrainDetailGrassShader` | 返回此管线的细节草 Shader |
| `terrainDetailLitShader` | 返回此管线的细节光照 Shader |

**受保护的方法**:
| 方法 | 描述 |
|------|------|
| `CreatePipeline()` | 创建此资源特有的 IRenderPipeline |
| `EnsureGlobalSettings()` | 确保全局设置已准备好并注册到 GraphicsSettings |
| `OnDisable()` | RenderPipelineAsset 的 OnDisable 默认实现 |
| `OnValidate()` | RenderPipelineAsset 的 OnValidate 默认实现 |

---

### 2.3 ScriptableRenderContext 类

**命名空间**: `UnityEngine.Rendering`

**类型**: struct (结构体)

**描述**: 定义自定义渲染管线使用的状态和绘制命令。当定义自定义 RenderPipeline 时，使用 ScriptableRenderContext 来调度和提交状态更新以及绘制命令到 GPU。

**公共方法**:
| 方法 | 描述 |
|------|------|
| `BeginRenderPass(RenderTargetIdentifier, RenderPassAttachment, ClearFlag, Color)` | 调度新渲染 pass 的开始 |
| `BeginScopedRenderPass(...)` | 调度渲染 pass 开始，使用 using 语句会自动调用 EndRenderPass |
| `BeginScopedSubPass(...)` | 调度子 pass 开始，使用 using 语句会自动调用 EndSubPass |
| `BeginSubPass(...)` | 调度子 pass 的开始 |
| `CreateGizmoRendererList(...)` | 创建新的 Gizmo RendererList |
| `CreateRendererList(...)` | 创建新的渲染器 RendererList |
| `CreateShadowRendererList(...)` | 创建新的阴影 RendererList |
| `CreateSkyboxRendererList(...)` | 创建新的天空盒 RendererList |
| `CreateUIOverlayRendererList(...)` | 创建新的 UIOverlay RendererList |
| `CreateWireOverlayRendererList(...)` | 创建新的线框覆盖层 RendererList |
| `Cull(ScriptableCullingParameters)` | 执行基于 ScriptableCullingParameters 的剔除 |
| `CullShadowCasters(...)` | 对所有可见光源执行阴影投射体剔除 |
| `DrawGizmos(Camera, GizmoSubset)` | 调度绘制 Gizmos 子集 |
| `DrawUIOverlay(Camera)` | 绘制 UI 覆盖层 |
| `DrawWireOverlay(Camera)` | 调度线框覆盖层绘制 |
| `EndRenderPass()` | 调度当前活动渲染 pass 的结束 |
| `EndSubPass()` | 调度当前活动子 pass 的结束 |
| `ExecuteCommandBuffer(CommandBuffer)` | 调度自定义图形 CommandBuffer 的执行 |
| `ExecuteCommandBufferAsync(CommandBuffer, ComputeQueueType)` | 在异步计算队列上执行 CommandBuffer |
| `HasInvokeOnRenderObjectCallbacks()` | 检查场景中是否有注册 OnRenderObject 回调的对象 |
| `InvokeOnRenderObjectCallback(Camera)` | 调度 MonoBehaviour 脚本的 OnRenderObject 回调执行 |
| `PrepareRendererListsAsync(List<RendererList>)` | 启动在后台处理提供的 RendererLists |
| `QueryRendererListStatus(RendererList)` | 查询 RendererList 的状态 |
| `SetupCameraProperties(Camera)` | 调度相机特定全局 Shader 变量的设置 |
| `StartMultiEye(Camera)` | 调度在 ScriptableRenderContext 上开始细粒度立体渲染 |
| `StopMultiEye(Camera)` | 调度停止立体渲染 |
| `StereoEndRender(Camera)` | 调度单帧立体渲染完成通知 |
| `Submit()` | 提交所有调度的命令到渲染循环执行 |
| `SubmitForRenderPassValidation()` | 验证渲染 pass 是否可以执行调度的命令 |

**静态方法**:
| 方法 | 描述 |
|------|------|
| `EmitGeometryForCamera(Camera)` | 为指定相机发射 UI 几何体进行渲染 |
| `EmitWorldGeometryForSceneView(SceneView)` | 为场景视图发射 UI 几何体 |
| `PopDisableApiRenderers()` | 启用渲染器场景节点的即时添加和移除 |
| `PushDisableApiRenderers()` | 阻止渲染器场景节点的即时添加或移除 |

---

### 2.4 ScriptableRenderPass 类

**命名空间**: `UnityEngine.Rendering`

**描述**: 可编写脚本的渲染 Pass 基类。用于实现自定义渲染 passes。

**主要成员**:
| 成员 | 描述 |
|------|------|
| `renderPassEvent` | 指定 Pass 在渲染管线中的执行时机 |
| `ConfigureInput()` | 配置渲染器输入 |
| `ConfigureTarget()` | 配置渲染目标 |
| `Execute()` | 执行 Pass 的渲染逻辑 |
| `FrameCleanup()` | 帧清理回调 |
| `OnCameraSetup()` | 相机设置回调 |
| `OnCameraCleanup()` | 相机清理回调 |

---

### 2.5 ScriptableRenderer 类

**命名空间**: `UnityEngine.Rendering`

**描述**: 可编写脚本的渲染器实现基类。

**主要方法**:
| 方法 | 描述 |
|------|------|
| `EnqueuePass(ScriptableRenderPass)` | 将渲染 Pass 加入队列 |
| `Execute(ScriptableRenderContext, ref RenderingData)` | 执行渲染 |
| `Initialize()` | 初始化渲染器 |
| `Submit()` | 提交渲染 |
| `ConfigureCameraTarget(RenderTargetIdentifier, RenderTargetIdentifier)` | 配置相机渲染目标 |
| `ConfigureColorStoreAction(RenderTargetStoreAction)` | 配置颜色存储操作 |
| `ConfigureDepthStoreAction(RenderTargetStoreAction)` | 配置深度存储操作 |

**属性**:
| 属性 | 描述 |
|------|------|
| `supportedRenderingFeatures` | 支持的渲染特性 |
| `rendererFeatures` | 渲染器特性列表 |
| `krenderGraphResourceSet` | 渲染图资源集 |

---

### 2.6 RenderPassEvent 枚举

**命名空间**: `UnityEngine.Rendering`

**描述**: 指定渲染 Pass 在渲染管线中的执行时机。

**枚举值**:
| 值 | 描述 |
|------|------|
| `BeforeRendering` | 渲染开始前 |
| `BeforeRenderingShadows` | 阴影渲染前 |
| `BeforeRenderingPrePasses` | 预 Pass (如深度预通道) 前 |
| `BeforeRenderingOpaques` | 不透明物体渲染前 |
| `BeforeRenderingGbuffer` | G-Buffer (延迟渲染) 前 |
| `BeforeRenderingLit` | 光照物体前 |
| `BeforeRenderingTransparents` | 透明物体渲染前 |
| `BeforeRenderingOverlays` | 覆盖层 (如 UI) 前 |
| `BeforeAlphaMask` | Alpha 遮罩前 |
| `AfterRendering` | 渲染结束后 |
| `AfterRenderingShadows` | 阴影渲染后 |
| `AfterRenderingPrePasses` | 预 Pass 后 |
| `AfterRenderingOpaques` | 不透明物体渲染后 |
| `AfterRenderingGbuffer` | G-Buffer 后 |
| `AfterRenderingLit` | 光照物体后 |
| `AfterRenderingTransparents` | 透明物体渲染后 |
| `AfterRenderingOverlays` | 覆盖层后 |
| `AfterAlphaMask` | Alpha 遮罩后 |

---

### 2.7 CullingResults 类

**命名空间**: `UnityEngine.Rendering`

**描述**: 包含剔除操作的结果，用于渲染对象和光源。

**主要方法**:
| 方法 | 描述 |
|------|------|
| `FillLightAndReflectionProbeIndices(...)` | 填充光照和反射探针索引 |
| `GetLightIndexMap()` | 获取光照索引映射 |
| `GetReflectionProbeIndexMap()` | 获取反射探针索引映射 |
| `SetLightIndexMap(int[], int[])` | 设置光照索引映射 |

**属性**:
| 属性 | 描述 |
|------|------|
| `visibleLights` | 可见光源列表 |
| `visibleReflectionProbes` | 可见反射探针列表 |
| `lightAndReflectionProbeIndex` | 光照和反射探针索引数据 |

---

### 2.8 ScriptableCullingParameters 结构体

**命名空间**: `UnityEngine.Rendering`

**描述**: 包含用于剔除操作的参数。

**主要成员**:
| 成员 | 描述 |
|------|------|
| `camera` | 剔除相机 |
| `cullingPlaneSet` | 剔除平面集 |
| `cullingMask` | 剔除遮罩 |
| `lightCullingMode` | 光照剔除模式 |
| `reflectionProbeCullingMode` | 反射探针剔除模式 |
| `shadowDistance` | 阴影距离 |
| `shadowNearPlane` | 阴影近平面 |
| `maximumPortalCullingJobs` | 最大门户剔除作业数 |

**静态方法**:
| 方法 | 描述 |
|------|------|
| `GetCullingParameters(Camera, ScriptableCullingParameters)` | 从相机获取剔除参数 |
| `GetCullingParametersForEditor(Camera, ScriptableCullingParameters)` | 为编辑器获取剔除参数 |

---

## 3. CommandBuffer 相关 API

### 3.1 CommandBuffer 类

**命名空间**: `UnityEngine.Rendering`

**描述**: 用于存储渲染命令的缓冲区。

**常用方法**:
| 方法 | 描述 |
|------|------|
| `Blit()` | 执行纹理拷贝 (blit) 操作 |
| `DrawRenderer()` | 绘制渲染器 |
| `DrawMesh()` | 绘制网格 |
| `DrawMeshInstanced()` | 绘制实例化网格 |
| `SetRenderTarget()` | 设置渲染目标 |
| `SetGlobalTexture()` | 设置全局纹理 |
| `SetGlobalFloat()` | 设置全局浮点数 |
| `SetGlobalVector()` | 设置全局向量 |
| `SetGlobalMatrix()` | 设置全局矩阵 |
| `SetViewProjectionMatrices()` | 设置视图投影矩阵 |
| `ClearRenderTarget()` | 清除渲染目标 |
| `CopyTexture()` | 复制纹理 |
| `ComputeDispatch()` | 计算着色器调度 |

### 3.2 CommandBufferPool 类

**命名空间**: `UnityEngine.Rendering`

**描述**: CommandBuffer 池化管理器，用于优化内存分配。

**静态方法**:
| 方法 | 描述 |
|------|------|
| `Get(string)` | 从池中获取 CommandBuffer |
| `Release(CommandBuffer)` | 释放 CommandBuffer 回池 |
| `Create(string)` | 创建新的 CommandBuffer |
| `ReleaseAll()` | 释放所有池化的 CommandBuffer |

### 3.3 RenderingData 结构体

**命名空间**: `UnityEngine.Rendering`

**描述**: 包含传递给 ScriptableRenderPass.Execute 的渲染数据。

**属性**:
| 属性 | 描述 |
|------|------|
| `cameraData` | 相机数据 |
| `cullingResults` | 剔除结果 |
| `lightData` | 光照数据 |
| `shadowData` | 阴影数据 |

### 3.4 CameraData 结构体

**命名空间**: `UnityEngine.Rendering`

**描述**: 包含相机相关的渲染数据。

**属性**:
| 属性 | 描述 |
|------|------|
| `camera` | Unity Camera 对象 |
| `projectionMatrix` | 投影矩阵 |
| `viewMatrix` | 视图矩阵 |
| `renderer` | 渲染器 |

---

## 4. 渲染相关类

### 4.1 ShaderTagId

**命名空间**: `UnityEngine.Rendering`

**描述**: Shader 标签标识符，用于标识 Shader 的渲染通道。

### 4.2 LightProbe

**命名空间**: `UnityEngine.Rendering`

**描述**: 光照探针管理类，用于处理光照探针数据。

### 4.3 DrawRendererSettings

**命名空间**: `UnityEngine.Rendering`

**描述**: 渲染器绘制设置结构体，用于配置渲染器绘制参数。

**主要成员**:
| 成员 | 描述 |
|------|------|
| `sorting` | 排序设置 |
| `flags` | 渲染标志 |
| `rendererConfiguration` | 渲染器配置 |
| `passIndex` | Pass 索引 |

---

## 5. URP (Universal Render Pipeline) 核心 API

**包**: `com.unity.render-pipelines.universal`

**命名空间**: `UnityEngine.Rendering.Universal`

URP 是建立在 SRP Core 之上的渲染管线，提供了更简化的 API。

### 5.1 UniversalRenderPipeline 类

**命名空间**: `UnityEngine.Rendering.Universal`

**描述**: URP 的主渲染管线类。

**属性**:
| 属性 | 描述 |
|------|------|
| `asset` | 当前 URP 资源 |
| `current` | 当前活动的渲染管线 |

### 5.2 UniversalRenderPipelineAsset 类

**命名空间**: `UnityEngine.Rendering.Universal`

**描述**: URP 的渲染管线资源资产。

### 5.3 ForwardRenderer 类

**命名空间**: `UnityEngine.Rendering.Universal`

**描述**: URP 的前向渲染器实现。

### 5.4 RenderingData (URP扩展)

URP 扩展了基础的 RenderingData，添加了 URP 特有的渲染数据。

### 5.5 URP 核心 Pass 类

| 类名 | 描述 |
|------|------|
| `ScriptableRenderPass` | URP 中继承自基类的渲染 Pass |
| `ScriptableBlitPass` | Blit 渲染 Pass |
| `ScriptableFullscreenPass` | 全屏渲染 Pass |
| `ColorGradingLutPass` | 颜色分级 LUT Pass |
| `BloomPass` | 泛光 Pass |
| `DepthOfFieldPass` | 景深 Pass |
| `MotionVectorPass` | 运动矢量 Pass |

### 5.6 RenderPassEvent (URP扩展)

URP 扩展了标准的 RenderPassEvent，添加了 URP 特有的渲染事件。

---

## 6. HDRP (High Definition Render Pipeline) 核心 API

**包**: `com.unity.render-pipelines.high-definition`

**命名空间**: `UnityEngine.Rendering.HighDefinition`

HDRP 是建立在 SRP Core 之上的高端渲染管线，提供了高质量的渲染效果。

### 6.1 HDRenderPipeline 类

**命名空间**: `UnityEngine.Rendering.HighDefinition`

**描述**: HDRP 的主渲染管线类。

### 6.2 HDRenderPipelineAsset 类

**命名空间**: `UnityEngine.Rendering.HighDefinition`

**描述**: HDRP 的渲染管线资源资产。

### 6.3 HDRenderer 类

**命名空间**: `UnityEngine.Rendering.HighDefinition`

**描述**: HDRP 的渲染器实现。

### 6.4 HDRP 核心组件

| 类名 | 描述 |
|------|------|
| `HDRenderPipelineAsset` | HDRP 资源资产 |
| `HDRenderer` | HDRP 渲染器 |
| `HDBaker` | 光照烘焙器 |
| `RayTracingShader` | 光线追踪着色器 |

### 6.5 HDRP 专用 Pass

| Pass 类 | 描述 |
|---------|------|
| `DeferredPass` | 延迟渲染 Pass |
| `ForwardEmissivePass` | 前向发光 Pass |
| `TransparentDepthPrePass` | 透明物体深度预 Pass |
| `MotionVectorPass` | 运动矢量 Pass |

---

## 7. SRP Core 核心类 (com.unity.render-pipelines.core)

### 7.1 核心工具类

| 类名 | 描述 |
|------|------|
| `CoreUtils` | SRP 核心工具函数集合 |
| `CoreMatrixUtils` | 矩阵操作工具函数 |
| `Blitter` | Blit (纹理拷贝) 工具 |
| `RTHandle` | 可自动缩放的渲染纹理 |
| `RTHandleSystem` | RTHandle 纹理管理系统 |
| `Volume` | 通用 Volume 组件 |
| `VolumeManager` | Volume 全局管理器 |
| `VolumeProfile` | Volume 设置资源 |
| `VolumeComponent` | Volume 组件基类 |

### 7.2 调试相关类

| 类名 | 描述 |
|------|------|
| `DebugManager` | 调试窗口管理器 |
| `DebugUI` | 调试 UI 类 |
| `DebugUI.Widget` | 调试 UI 组件基类 |
| `ProfilingSampler` | CPU/GPU 性能分析采样器 |
| `ProfilingScope` | 性能分析作用域 |
| `Recorder` | 性能记录器 |
| `Profiler` | 性能分析器 |

### 7.3 资源管理类

| 类名 | 描述 |
|------|------|
| `RenderPipelineGlobalSettings` | 渲染管线全局设置 |
| `RenderPipelineResources` | 渲染管线资源资产基类 |
| `ConstantBuffer` | 常量缓冲区管理 |
| `ShaderVariation` | Shader 变体管理 |
| `MaterialDescription` | 材质描述 |

### 7.4 渲染 Pass 基类

| 类名 | 描述 |
|------|------|
| `ScriptableRenderPass` | 可编写脚本的渲染 Pass 基类 |
| `ScriptableBlitPass` | Blit 操作 Pass 基类 |
| `ScriptableCopyPass` | 拷贝 Pass 基类 |

### 7.5 渲染器特性

| 类名 | 描述 |
|------|------|
| `RenderingFeatures` | 渲染特性集合 |
| `RendererFeatures` | 渲染器特性集合 |
| `RenderPipelineFeature` | 渲染管线特性基类 |

---

## 8. 使用示例

### 8.1 创建自定义渲染管线

```csharp
using UnityEngine;
using UnityEngine.Rendering;
using System.Collections.Generic;

public class CustomRenderPipeline : RenderPipeline
{
    protected override void Render(ScriptableRenderContext context, List<Camera> cameras)
    {
        foreach (var camera in cameras)
        {
            // 渲染每个相机
            Render(context, camera);
        }
        
        // 提交渲染命令
        context.Submit();
    }
    
    private void Render(ScriptableRenderContext context, Camera camera)
    {
        // 设置相机属性
        context.SetupCameraProperties(camera);
        
        // 创建命令缓冲区
        CommandBuffer cmd = CommandBufferPool.Get("Clear");
        cmd.ClearRenderTarget(true, true, Color.black);
        context.ExecuteCommandBuffer(cmd);
        CommandBufferPool.Release(cmd);
        
        // 提交
        context.Submit();
    }
}
```

### 8.2 创建自定义渲染 Pass

```csharp
using UnityEngine;
using UnityEngine.Rendering;

public class CustomRenderPass : ScriptableRenderPass
{
    public CustomRenderPass()
    {
        // 设置 Pass 执行时机
        renderPassEvent = RenderPassEvent.BeforeRenderingOpaques;
    }
    
    public override void OnCameraSetup(CommandBuffer cmd, ref RenderingData renderingData)
    {
        // 相机设置
    }
    
    public override void Execute(ScriptableRenderContext context, ref RenderingData renderingData)
    {
        // 执行渲染逻辑
    }
    
    public override void FrameCleanup(CommandBuffer cmd)
    {
        // 帧清理
    }
}
```

---

## 9. 官方文档资源

- [SRP 官方文档](https://docs.unity3d.com/Manual/ScriptableRenderPipeline.html)
- [URP Scripting API](https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@latest/api/)
- [HDRP Scripting API](https://docs.unity3d.com/Packages/com.unity.render-pipelines.high-definition@latest/api/)
- [SRP Core Scripting API](https://docs.unity3d.com/Packages/com.unity.render-pipelines.core@latest/api/)

---

*文档版本: 1.1*
*更新日期: 2026-03-16*
*Unity 版本: 6.3 LTS (6000.3)*
*基于官方 Unity API 文档调研整理*