XCEngine/docs/Unity_SRP_API_Reference.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` | 调用 RenderPipelineManager.beginCameraRendering 委托 |
| `BeginContextRendering` | 调用 RenderPipelineManager.beginContextRendering 和 RenderPipelineManager.beginFrameRendering 委托 |
| `EndCameraRendering` | 调用 RenderPipelineManager.endCameraRendering 委托 |
| `EndContextRendering` | 调用 RenderPipelineManager.endContextRendering 和 RenderPipelineManager.endFrameRendering 委托 |
| `SubmitRenderRequest` | 使用渲染管线向相机提交渲染请求（在 Unity 渲染循环之外） |
| `SupportsRenderRequest` | 检查渲染管线是否支持使用相机的 RequestData 类型 |

---

### 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`

**描述**: 渲染上下文的可编写脚本表示。用于调度和执行渲染命令。

**主要方法**:
| 方法 | 描述 |
|------|------|
| `BeginRenderPass()` | 开始渲染 pass |
| `EndRenderPass()` | 结束渲染 pass |
| `ExecuteCommandBuffer()` | 执行命令缓冲区 |
| `Submit()` | 提交所有待处理的渲染命令 |
| `SetupCameraProperties()` | 设置相机属性 |

---

### 2.4 ScriptableRenderPass 类

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

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

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

---

### 2.5 ScriptableRenderer 类

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

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

**主要方法**:
| 方法 | 描述 |
|------|------|
| `EnqueuePass()` | 将渲染 Pass 加入队列 |
| `Execute()` | 执行渲染 |
| `Initialize()` | 初始化渲染器 |
| `Submit()` | 提交渲染 |

---

### 2.6 RenderPassEvent 枚举

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

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

**枚举值**:
| 值 | 描述 |
|------|------|
| `BeforeRendering` | 渲染开始前 |
| `BeforeRenderingShadows` | 阴影渲染前 |
| `BeforeRenderingPrePasses` | 预 Pass 前 |
| `BeforeRenderingOpaques` | 不透明物体前 |
| `BeforeRenderingGbuffer` | G-Buffer 前 |
| `BeforeRenderingLit` | 光照物体前 |
| `BeforeRenderingTransparents` | 透明物体前 |
| `BeforeRenderingOverlays` | 覆盖层前 |
| `AfterRendering` | 渲染结束后 |
| `AfterRenderingShadows` | 阴影渲染后 |
| `AfterRenderingPrePasses` | 预 Pass 后 |
| `AfterRenderingOpaques` | 不透明物体后 |
| `AfterRenderingGbuffer` | G-Buffer 后 |
| `AfterRenderingLit` | 光照物体后 |
| `AfterRenderingTransparents` | 透明物体后 |
| `AfterRenderingOverlays` | 覆盖层后 |

---

## 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 池化管理器，用于优化内存分配。

---

## 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`

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

### 5.1 UniversalRenderPipeline 类

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

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

### 5.2 UniversalRenderPipelineAsset 类

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

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

### 5.3 ForwardRenderer 类

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

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

### 5.4 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 的渲染器实现。

---

## 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 类 |
| `ProfilingSampler` | CPU/GPU 性能分析采样器 |
| `ProfilingScope` | 性能分析作用域 |

### 7.3 资源管理类

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

---

## 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/)

---

*文档生成时间: 2026-03-16*
*Unity 版本: 2023.1+*