将 HDRP 从 8.x 升级到 10.x

在高清渲染管线 (High Definition Render Pipeline, HDRP) 中，主要版本之间某些功能的工作方式有所不同。本文档可帮助你将 HDRP 从 8.x 升级到 10.x。请注意，现已发布包版本 9.x-preview。这个版本与 Unity 2020.1 兼容，并包含 10.x 中的某些功能。但是，此包仅用于获取反馈，以后将不再维护。

常量缓冲区 API

从 10.x 开始，HDRP 使用新的常量缓冲区 API，因此可以在帧期间设置 uniform 值并通过一次传输（而不是多次传输）将它们发送到着色器。为此，以前单独声明的全局变量现在全都位于 ShaderVariablesGlobal 结构中。因此，现在无法再使用 CommandBuffer.SetVectorXXX() 或其相关函数来单独设置任何全局值。现在，若要更改某个全局变量，就需要整体更新该结构。

当前，ShaderVariablesGlobal 结构中唯一可公开访问的变量与摄像机相关，并且只能通过以下函数在自定义通道中使用：

RenderFromCamera()
RenderDepthFromCamera()
RenderNormalFromCamera()
RenderTangentFromCamera()

Frame Settings

从 10.x 开始，如果创建新的 HDRP 资源，则默认将启用 MSAA Within Forward 帧设置。

菜单

从 10.x 开始，为保持一致性，Assets > Create > Shader 中的各种 HDRP 菜单项已被重命名为 HD Render Pipeline。

贴花

从 10.x 开始，贴花不再需要完全的深度预通道。在深度预通道期间，HDRP 仅渲染已启用 Receive Decals 的材质，除非通过其他选项强制执行。

从 10.x 开始，可以使用贴花层系统，该系统将利用网格渲染器 (Mesh Renderer) 和地形 (Terrain) 的 Rendering Layer Mask 属性。在 2020.2 版之前，此属性的默认值未包含任何贴花层标志。这意味着，启用此功能后，在进行正确配置之前，任何网格都不会接收贴花。可以使用提供的脚本 (Edit > Render Pipeline/HD Render Pipeline > Upgrade from Previous Version > Add Decal Layer Default to Loaded Mesh Renderers and Terrains) 来转换已创建的网格，还有一个仅应用于所选项的版本。默认情况下，新建的网格渲染器或地形启用了 Decal Layer Default。

光照

从 10.x 开始，从编辑器菜单创建聚光灯时，HDRP 现在默认会启用 Reflector 属性。请注意，如果通过 C# 脚本创建聚光灯，将禁用此属性。

从 10.x 开始，HDRP 禁用不兼容的光照立方体贴图的背板 (Backplate) 渲染。

从 10.x 开始，屏幕空间环境光遮挡、屏幕空间全局光照、屏幕空间反射、光线追踪效果和体积重投影不会与反射探针交互，因为它们不能正常运行。

从 10.x 开始，如果在 Lighting 窗口中禁用了用作静态光照天空 (Static Lighting Sky) 的天空覆盖，则天空不再影响烘焙光照。以前，即使被禁用，天空也会影响烘焙光照。

从 10.x 开始， HDRP 具有用于点光源剪影的立方体贴图数组，现在使用具有常规 2D 剪影图集的八面体投影。这是为了让光源剪影和 IES 使用单一路径，但是在使用低分辨率立方体剪影时，这可能会产生视觉瑕疵。例如，在对像素美术数据进行投影时。

由于立方体贴图剪影图集 (Cubemap cookie atlas) 不再存在，因此 HDRP 可能在当前的 2D 图集上没有足够空间来容纳剪影。如果出现这种情况，HDRP 会在 Console 窗口中显示一个错误。要解决此问题，请增大 2D 剪影图集的大小。为此，请执行以下操作：选择 HDRP 资源。在 Inspector 中，选择 Lighting > Cookies。在 2D Atlas Size 下拉选单中，选择更大的剪影分辨率。

从 10.x 开始，HDRP 资源中颜色缓冲区的纹理格式也适用于平面反射探针。以前，平面反射探针始终使用 float16 渲染目标。

从 10.x 开始，光源层属性已从 HDRP 设置移至 HDRP 默认设置面板。

从 10.x 开始，在基于物理的天空中，太阳圆盘强度与其尺寸成正比。在此之前有一个错误是不会按太阳圆盘尺寸来驱动太阳圆盘。

从 10.x 开始，如果以前在贴花、光照、分层光照 (LayeredLit) 或无光照材质中使用了 UseEmissiveIntensity 属性，请注意现在 EmissiveColorLDR 属性位于 sRGB 颜色空间中。以前，HDRP 将 EmissiveColor 视为处于线性 RGB 颜色空间中，因此，版本之间的视觉效果可能不一致。为了解决此不一致的问题，HDRP 提供了一个迁移脚本来自动处理转换。

对于从旧的 9.x.x-preview 包迁移的项目，曝光枚举顺序发生了变化，可能会将当前曝光模式更改为曝光体积 (Exposure Volume) 中的另一种模式。需要通过重新选择正确的曝光模式来手动纠正此问题。

从 10.x 开始，移除了调试镜头衰减，但是现在可以在 HDRP 默认设置面板中将镜头衰减设置为模拟完美镜头或不完美镜头。

从 10.x 开始，屏幕空间反射效果始终使用 HDRP 在“折射之前”(Before Refraction) 透明通道后生成的颜色棱锥。这意味着颜色缓冲区仅包含使用 BeforeRefraction 渲染通道的透明游戏对象。以前，内容取决于是否激活了失真效果。

体积雾

将项目升级到 10.2 时，场景中的体积雾质量可能会下降。这是由于新的体积雾控制模式所致。要使体积雾看起来与 8.x 中的相同，请执行以下操作：

在 Fog Volume Override 中，将 Fog Control Mode 设置为 Manual。
对于此模式显示的属性，输入与 8.x 中相同的值。

或者，将 Fog Control Mode 设置为 Balance 并使用以性能为导向的新属性来定义体积雾的质量。

阴影

从 10.x 开始，不再需要更改 HDRP 配置包来设置用于延迟渲染的阴影过滤质量。现在可以直接在 HDRP 资源上更改过滤质量。请注意，如果以前没有在 HDRP 资源上将阴影过滤质量设置为 Medium，则自动项目升级过程会更改阴影质量，这意味着可能需要手动将其恢复为原始值。

HDRP 现在会将 OnEnable 和 OnDemand 阴影存储在单独的图集中，并且可以使用更多 API 来处理它们。有关更多信息，请参阅 HDRP 中的阴影。

着色器函数 SampleShadow_PCSS 现在要求传入一个额外的 float2 参数，该参数包含 x 中的阴影图集分辨率和 y 中的图集分辨率的倒数。

现在向接触阴影添加了光线偏差和厚度参数。这些可能会导致使用默认参数的接触阴影的视觉效果发生细微变化。请考虑调整这些值以适应具体项目的需求。

着色器配置文件

从 10.x 开始，由于阴影贴图的变化，HDRP 将 HDShadowFilteringQuality 枚举移到了 HDShadowManager.cs。HDRP 还从源代码中移除了 ShaderConfig.s_DeferredShadowFiltering 和 ShaderOptions.DeferredShadowFiltering，因为它们不再有效。

从 10.x 开始，提供了一个名为 ColoredShadow 的新选项。此选项可用于控制阴影是彩色还是单色。默认情况下将启用 ColoredShadow，当前仅适用于光线追踪阴影。请注意，与标准阴影相比，有色阴影的处理需要消耗更多资源。

从 10.x 开始，移除了光线追踪选项和等效项生成的着色器宏 SHADEROPTIONS_RAYTRACING。不再需要编辑着色器配置文件即可在 HDRP 中使用光线追踪效果。

着色器代码

从 10.x 开始，HDRP 使用新结构从 LightLoop 输出信息。现在，它使用自定义的 LightLoop 结构，而不是 float3 diffuseLighting、float3 specularLighting 对。这是为了使 HDRP 将来可以在不破坏 API 的情况下从 LightLoop 导出更多信息。

以下函数现在会传递相应的结构，而不是参数对：

LightLoop()，用于光栅化和光线追踪。
PostEvaluateBSDF()
ApplyDebug()
PostEvaluateBSDFDebugDisplay()

为了升级现有着色器，对于上述所有函数：

在 LightLoop 调用之前，将声明 float3 diffuseLighting; float3 specularLighting; 替换为 LightLoopOutput lightLoopOutput;。
将参数对 out float3 diffuseLighting, out float3 specularLighting 替换为 out LightLoopOutput lightLoopOutput。

各种材质中的函数 ModifyBakedDiffuseLighting() 的原型已从： void ModifyBakedDiffuseLighting(float3 V, PositionInputs posInput, SurfaceData surfaceData, inout BuiltinData builtinData) 更改为： void ModifyBakedDiffuseLighting(float3 V, PositionInputs posInput, PreLightData preLightData, BSDFData bsdfData, inout BuiltinData builtinData)

还有一个用于 ModifyBakedDiffuseLighting() 的新定义，该定义使用以前的原型定义，并使用正确参数来调用新函数原型。此更改的目的是为将来的光照功能做准备。要更新自定义着色器，除了原型更新外，还必须删除以下代码行：

BSDFData bsdfData = ConvertSurfaceDataToBSDFData(posInput.positionSS, surfaceData);

PreLightData preLightData = GetPreLightData(V, posInput, bsdfData);

从 10.x 开始，HDRP 包含新的矩形区域阴影评估函数 EvaluateShadow_RectArea。GetAreaLightAttenuation() 函数已重命名为 GetRectAreaShadowAttenuation()。类型 DirectionalShadowType 也已重命名为 SHADOW_TYPE。

从 10.x 开始，移除了宏 ENABLE_RAYTRACING、SHADEROPTIONS_RAYTRACING 和 RAYTRACING_ENABLED。为前向通道引入了一种新的多重编译：SCREEN_SPACE_SHADOWS_OFF SCREEN_SPACE_SHADOWS_ON。因此，无需编辑着色器配置文件即可启用光线追踪效果。

从 10.x 开始，TransparentDepthPrepass 和 TransparentDepthPostpass 标识的 SHADERPASS 分别使用 SHADERPASS_TRANSPARENT_DEPTH_PREPASS 和 SHADERPASS_TRANSPARENT_DEPTH_POSTPASS。以前是 SHADERPASS_DEPTH_ONLY。移除了定义 CUTOFF_TRANSPARENT_DEPTH_PREPASS 和 CUTOFF_TRANSPARENT_DEPTH_POSTPASS，因为现在可以使用新的路径宏。

10.x 引入了用于深度预通道和运动矢量通道的新版多重编译以支持贴花层功能。这些通道现在要求添加 #pragma multi_compile _ WRITE_DECAL_BUFFER。

从 10.x 开始，Decal.shader 着色器代码已更改。以前，此代码使用大约 16 个通道来处理不同贴花属性的渲染。现在仅使用四个通道：DBufferProjector、DecalProjectorForwardEmissive、DBufferMesh、DecalMeshForwardEmissive。有些通道名称也不同。DBufferProjector 和 DBufferMesh 现在使用 multi_compile DECALS_3RT DECALS_4RT 来处理不同变体，并且着色器剥离器也已更新。各种着色器贴花属性已重命名/更改以便匹配一组新的 AffectXXX 属性（_AlbedoMode、_MaskBlendMode、_MaskmapMetal、_MaskmapAO、_MaskmapSmoothness、_Emissive 已更改为 _AffectAlbedo、_AffectNormal、_AffectAO、_AffectMetal、_AffectSmoothness、_AffectEmission，关键字 _ALBEDOCONTRIBUTION 现在是 _MATERIAL_AFFECTS_ALBEDO，并添加了两个新的关键字：_MATERIAL_AFFECTS_NORMAL、_MATERIAL_AFFECTS_MASKMAP）。这些新属性现在与贴花 Shader Graph 的属性匹配，现在将在材质中显示出来。有一个材质升级过程会自动升级所有贴花材质。但是，如果项目中包含创建或操纵贴花材质的任何 C# 脚本，则需要更新脚本以使用新的属性和关键字；迁移对于按程序生成的贴花材质无效。

从 10.x 开始，HDRP 更改了材质内部贴花应用程序的着色器代码。在以前的版本中，HDRP 会进行名为“HTile”的优化，这依赖于 HTileMask。经过进一步研究，此优化已不再是成功的优化，因此，HDRP 移除了与之相关的所有代码。这包括 DecalSurfaceData 中的 HTileMask 成员，以及 DBufferHTileBit 结构和关联的标志。要更新自定义着色器，请移除 DBUFFERHTILEBIT_DIFFUSE、DBUFFERHTILEBIT_NORMAL 和 DBUFFERHTILEBIT_MASK 定义（因为它们不再存在），改为检查各个属性的权重是否非中性。例如，在 ApplyDecalToSurfaceData() 函数中，将以下行：

    if (decalSurfaceData.HTileMask & DBUFFERHTILEBIT_DIFFUSE)
        {
          (...)
        }

        if (decalSurfaceData.HTileMask & DBUFFERHTILEBIT_NORMAL)
        {
          (...)
        }

        if (decalSurfaceData.HTileMask & DBUFFERHTILEBIT_MASK)
        {
            (...)ComputeFresnel0((decalSurfaceData.HTileMask & DBUFFERHTILEBIT_DIFFUSE) ?(...));
        }

分别替换为

    if (decalSurfaceData.baseColor.w  < 1.0)
        {
          (...)
        }

        if (decalSurfaceData.normalWS.w < 1.0)
        {
          (...)
        }

        if (decalSurfaceData.MAOSBlend.x < 1.0 || decalSurfaceData.MAOSBlend.y < 1.0 || decalSurfaceData.mask.w)
        {
            (...)ComputeFresnel0((decalSurfaceData.baseColor.w  < 1.0) ?(...));
        }

有关将贴花应用于材质的最佳做法示例，请参阅 LitDecalData.hlsl 文件中的 ApplyDecalToSurfaceData() 函数。

从 10.x 开始，着色器代码中的贴花函数原型已更改。添加了新的顶点法线参数以用于处理基于角度的淡化。函数 GetDecalSurfaceData() 的原型已从： DecalSurfaceData GetDecalSurfaceData(PositionInputs posInput, inout float alpha) 更改为： DecalSurfaceData GetDecalSurfaceData(PositionInputs posInput, float3 vtxNormal, inout float alpha)

各种材质中的函数 ApplyDecalToSurfaceData() 的原型已从： void ApplyDecalToSurfaceData(DecalSurfaceData decalSurfaceData, inout SurfaceData surfaceData) 更改为： void ApplyDecalToSurfaceData(DecalSurfaceData decalSurfaceData, float3 vtxNormal, inout SurfaceData surfaceData)

从 10.x 开始，HDRP 新增了一个名为 FullScreenDebug 的全屏调试通道。如果任何对象使用的材质基于未包含此通道的着色器，则不会在全屏调试过程中渲染此对象。

从 Unity 2020.2 开始，Shader Graph 中的光线追踪 (Raytracing) 关键字已重命名为光线追踪质量 (Raytracing Quality)，RAYTRACING_SHADER_GRAPH_LOW 和 RAYTRACING_SHADER_GRAPH_HIGH 定义现在分别为 RAYTRACING_SHADER_GRAPH_DEFAULT 和 RAYTRACING_SHADER_GRAPH_RAYTRACED。除非在自定义着色器代码中使用了这些定义，否则无需执行任何操作，因为在加载项目时，Shader Graph 会使用正确的定义来自动重新生成着色器。

从 Unity 2020.2 起，在函数 SampleEnv 中添加了参数 positionNDC。函数原型已从： float4 SampleEnv(LightLoopContext lightLoopContext, int index, float3 texCoord, float lod, float rangeCompressionFactorCompensation, int sliceIdx = 0) 更改为： float4 SampleEnv(LightLoopContext lightLoopContext, int index, float3 texCoord, float lod, float rangeCompressionFactorCompensation, float2 positionNDC, int sliceIdx = 0) 例如，光照着色器中的调用已被更新为： float4 preLD = SampleEnv(lightLoopContext, lightData.envIndex, R, PerceptualRoughnessToMipmapLevel(preLightData.iblPerceptualRoughness), lightData.rangeCompressionFactorCompensation, posInput.positionNDC);

从 10.x 开始，移除了着色器关键字 _BLENDMODE_ALPHA _BLENDMODE_ADD 和 _BLENDMODE_PRE_MULTIPLY。这些关键字已不再使用，而是改用属性 _Blendmode。同样，移除了着色器关键字 _BLENDMODE_PRESERVE_SPECULAR_LIGHTING，并在着色器代码中使用 _EnableBlendModePreserveSpecularLighting 属性取代该关键字。

例如，在 Material.hlsl 中，以下代码行：

    #if defined(_BLENDMODE_ADD) || defined(_BLENDMODE_ALPHA)
            return float4(diffuseLighting * opacity + specularLighting, opacity);

被替换为

    if (_BlendMode == BLENDMODE_ALPHA || _BlendMode == BLENDMODE_ADDITIVE)
            return float4(diffuseLighting * opacity + specularLighting * (
    # ifdef SUPPORT_BLENDMODE_PRESERVE_SPECULAR_LIGHTING
            _EnableBlendModePreserveSpecularLighting ?1.0f :
    # endif
                opacity), opacity);

这一变化减少了着色器变体的数量。如果是自定义着色器，可能需要在声明属性 _Blendmode 之后移动 Material.hlsl 的 include 语句。另外，如果自定义着色器需要支持混合模式保留镜面反射选项，则需要确保定义了 _EnableBlendModePreserveSpecularLighting 属性，并且还定义了编译时间常量 SUPPORT_BLENDMODE_PRESERVE_SPECULAR_LIGHTING。

从 10.x 开始，HDRP 包含针对平面反射探针的新优化。现在，当着色器对探针的环境贴图进行采样时，如果启用了 LightData.roughReflections 参数（值为 1.0），它将从 Mip 级别 0 采样。必须更新自定义着色器以考虑到此行为。例如，光照着色器中的调用已更新为： float4 preLD = SampleEnv(lightLoopContext, lightData.envIndex, R, PerceptualRoughnessToMipmapLevel(preLightData.iblPerceptualRoughness) * lightData.roughReflections, lightData.rangeCompressionFactorCompensation, posInput.positionNDC); 此外，在反射探针上添加了用于伪造基于距离的粗糙度的新功能，并引入了新的 helper 函数。先前的代码在光照着色器中最终被重写为 float4 preLD = SampleEnvWithDistanceBaseRoughness(lightLoopContext, posInput, lightData, R, preLightData.iblPerceptualRoughness, intersectionDistance);。 intersectionDistance 是 EvaluateLight_EnvIntersection() 函数的 return 参数。

从 10.x 开始，使用遮罩贴图时，HDRP 会对金属性属性使用范围重新映射。在 Lit、LitTessellation、LayeredLit 和 LayeredLitTesselation 着色器中，添加了两个新属性：_MetallicRemapMin 和 _MetallicRemapMax。在 Decal 着色器中，添加了 _MetallicRemapMin 属性，并将 _MetallicScale 重命名为 _MetallicRemapMax。

从 10.x 开始，已将新通道 ScenePickingPass 添加到所有着色器和主节点，从而让编辑器可以正确处理对曲面细分对象和背面对象的拾取。

从 10.x 开始，在着色器代码中添加了一个贴花函数。为了处理双面材质的法线翻转，应通过此函数将 GetDecalSurfaceData() 的调用： DecalSurfaceData GetDecalSurfaceData(PositionInputs posInput, float3 vtxNormal, inout float alpha) 更新为： DecalSurfaceData GetDecalSurfaceData(PositionInputs posInput, FragInputs input, inout float alpha)

光线追踪

从 Unity 2020.2 开始，Shader Graph 中的光线追踪节点现在会将光线追踪路径（以前为低路径）应用于除路径追踪之外的所有光线追踪效果。

自定义通道 API

已更改 Execute 函数的签名以简化参数，现在仅将 CustomPassContext 作为其输入： void Execute(CustomPassContext ctx)

CustomPassContext 包含旧版 Execute 函数的所有参数，还包含所有可用的渲染纹理以及对自定义通道实例而言唯一的 MaterialPropertyBlock。

此上下文允许使用新的 CustomPassUtils 类，其中包含可加快自定义通道开发速度的函数。

有关自定义通道实用程序的信息，请参阅自定义通道手册或 CustomPassUtils API 文档。

要升级自定义通道，请将原始的执行函数原型替换成新的原型。为此，请将：

protected override void Execute(ScriptableRenderContext renderContext, CommandBuffer cmd, HDCamera hdCamera, CullingResults cullingResult) { ...}

替换为：

protected override void Execute(CustomPassContext ctx) { ...}

密度体积遮罩纹理

以前，要将 2D 翻页纹理转换为密度遮罩纹理所需的 3D 格式，需要使用 Window > Rendering 菜单中的 Density Volume Texture Tool。从 Unity 2020.2 开始，现在可以直接通过__纹理导入器 (Texture Importer)__ 进行此转换。如需了解如何使用此导入器来转换翻页纹理，请参阅密度体积 (Density Volume) 文档。

扩散配置文件

扩散配置文件列表已从 HDRP 资源 Inspector UI 移至 Default HDRP Settings（在项目设置窗口中）。

如果已将多个 HDRP 资源设置为 Quality Settings，可能受到此更改的影响。在此情况下，如果 Quality Settings 中一个或多个 HDRP 资源的扩散配置文件与 Graphics Settings 中分配的配置文件不同，则 HDRP 资源列表将丢失。现在唯一相关的列表是 Default HDRP Settings 中的列表。

我们建议，在升级之前，将项目中使用的所有扩散配置文件放入 Graphics Settings 中分配的 HDRP 资源中。此操作将防止升级后发生有关项目中扩散配置文件丢失的任何问题。

后期处理

以前，在运动模糊体积组件中，摄像机旋转钳制始终处于活动状态，因此默认情况下会以其他方式钳制源于摄像机旋转的运动矢量部分。由于相对于摄像机的运动矢量变化，这可能造成混乱。

从 2020.2 开始，摄像机旋转钳制选项不是默认选项，而是需要在 Camera Clamp Mode 设置下作为一个选项进行选择。此外，在同样的设置下还提供了对摄像机运动模糊影响的其他钳制控制。