xuanchi/XCEngine

Fork 0

Files

ssdfasd 9bad996ecf refactor: reorganize docs into plan/ and add skills/

2026-03-18 17:49:22 +08:00

20 KiB

Raw Blame History

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。

示例代码:

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 创建自定义渲染管线

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

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. 官方文档资源

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

20 KiB Raw Blame History Unescape Escape

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

1. 概述

2. 核心类 API

2.1 RenderPipeline 类

2.2 RenderPipelineAsset 类

2.3 ScriptableRenderContext 类

2.4 ScriptableRenderPass 类

2.5 ScriptableRenderer 类

2.6 RenderPassEvent 枚举

2.7 CullingResults 类

2.8 ScriptableCullingParameters 结构体

3. CommandBuffer 相关 API

3.1 CommandBuffer 类

3.2 CommandBufferPool 类

3.3 RenderingData 结构体

3.4 CameraData 结构体

4. 渲染相关类

4.1 ShaderTagId

4.2 LightProbe

4.3 DrawRendererSettings

5. URP (Universal Render Pipeline) 核心 API

5.1 UniversalRenderPipeline 类

5.2 UniversalRenderPipelineAsset 类

5.3 ForwardRenderer 类

5.4 RenderingData (URP扩展)

5.5 URP 核心 Pass 类

5.6 RenderPassEvent (URP扩展)

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

6.1 HDRenderPipeline 类

6.2 HDRenderPipelineAsset 类

6.3 HDRenderer 类

6.4 HDRP 核心组件

6.5 HDRP 专用 Pass

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

7.1 核心工具类

7.2 调试相关类

7.3 资源管理类

7.4 渲染 Pass 基类

7.5 渲染器特性

8. 使用示例

8.1 创建自定义渲染管线

8.2 创建自定义渲染 Pass

9. 官方文档资源

20 KiB

Raw Blame History