Unity URP渲染管线CG到HLSL着色器迁移实战指南

1. 项目概述：为什么URP时代必须拥抱HLSL？

如果你是从Unity内置渲染管线（Built-in Render Pipeline）时代一路走来的开发者，手里肯定攒了不少用CG语言写的Shader。这些Shader曾经是你的宝贝，但随着项目升级到通用渲染管线（Universal Render Pipeline, URP），它们很可能变成了“紫材质”的罪魁祸首，或者性能表现不尽如人意。这不是你的代码写得不好，而是渲染管线的底层逻辑变了。Unity官方在URP中明确推荐使用HLSL（High-Level Shading Language）作为首选着色器语言，这不仅仅是一个建议，而是性能、兼容性和未来维护性的关键。

我经历过将一个中型项目从内置管线迁移到URP的过程，其中Shader的迁移是最耗时但也最核心的环节。直接使用CGPROGRAM块在URP中虽然能被支持，但你会失去SRP Batcher的优化，一些内置的变换函数和光照模型也可能无法正常工作，导致渲染错误或效率低下。因此，将现有的CG Shader手动迁移、重写为HLSL，是确保项目在URP下稳定、高效运行的必经之路。这个过程不是简单的“翻译”，而是理解两种语言在URP新范式下的差异，并重构代码逻辑。本文将以一个最基础的Unlit（无光照）着色器为例，手把手带你完成从CG到HLSL的完整迁移，并解释每一个改动背后的“为什么”，让你不仅能改对一个Shader，更能掌握迁移的核心方法论。

2. 核心差异解析：CG与HLSL在URP下的根本不同

在动手改写之前，我们必须先搞清楚CG和HLSL在URP上下文中的核心区别。这绝非简单的语法替换，而是涉及到底层API、函数库和渲染流程的差异。

2.1 语言本质与包含机制

在Unity内置渲染管线中，CG是事实上的标准。当你写下CGPROGRAM时，Unity会自动为你包含一系列内置的辅助文件、宏和函数（比如UnityCG.cginc）。这些文件封装了旧管线的渲染逻辑。

而在URP（以及所有SRP管线）中，HLSL成为了官方首选。你需要显式地包含URP提供的特定头文件，例如Core.hlsl。这个文件是URP Shader的基石，它本身又包含了Common.hlsl、SpaceTransforms.hlsl等关键文件，提供了适配URP渲染路径的数学函数、空间变换和数据结构。

关键区别：CG在内置管线中“开箱即用”，因为它背后有一整套为旧管线准备的标准库。HLSL在URP中则需要你“按需索取”，明确引入SRP提供的、与URP架构匹配的新函数库。如果你在URP Shader中使用了CGPROGRAM，Unity为了兼容性，仍然会拉取旧的内置函数库，这可能导致与新SRP函数库的命名冲突，是许多诡异错误的根源。

2.2 顶点数据与语义的变化

这是迁移过程中最容易出错的地方。在CG中，我们习惯使用诸如appdata_base、appdata_full这样的预定义结构体，或者自己定义float4 vertex : POSITION。语义（如POSITION,NORMAL,TEXCOORD0）是直接与旧管线模型数据绑定的。

在URP的HLSL中，为了更清晰和模块化，推荐使用自定义的结构体，并且语义命名更具描述性，以体现其坐标空间。

• 输入结构体（Attributes）：通常命名为Attributes或appdata。顶点位置字段的语义推荐使用POSITION，但你在代码中应该明确其是**对象空间（Object Space）**的。因此，一个良好的命名习惯是float3 positionOS : POSITION。这样一眼就能看出这个数据的空间属性。
• 输出结构体（Varyings）：通常命名为Varyings或v2f（vertex-to-fragment）。最关键的是，顶点着色器的输出位置必须使用SV_POSITION语义，而不是CG中常用的SV_POSITION或POSITION。SV_开头的语义是系统值（System-Value），在HLSL中更为严格。在URP中，这个位置值应该是齐次裁剪空间（Homogeneous Clip Space）下的。

2.3 空间变换函数的革新

在CG中，我们使用UnityObjectToClipPos(v.vertex)或mul(UNITY_MATRIX_MVP, v.vertex)来将顶点从对象空间变换到裁剪空间。这些函数或矩阵是内置管线提供的。

在URP的HLSL中，这些旧函数统统不能用了。URP在SpaceTransforms.hlsl文件中提供了一套全新的变换函数。最常用、最核心的一个就是TransformObjectToHClip()。这个函数接受一个对象空间的float3坐标，直接返回齐次裁剪空间下的float4坐标。它的内部封装了当前URP摄像机的视图-投影矩阵以及物体的模型矩阵，你无需再手动处理矩阵乘法。

迁移核心：找到所有进行空间变换（尤其是模型-视图-投影变换）的代码，将旧的CG函数替换为URP HLSL库中的对应函数。这是保证顶点正确渲染的第一步。

2.4 着色器编译指令与标签

CG中常用#pragma surface surf Lambert这样的指令来声明表面着色器。URP的HLSL着色器（无论是Unlit还是Lit）通常使用更基础的#pragma vertex vert和#pragma fragment frag来分别指定顶点和片元着色器函数。

此外，SubShader的Tags也至关重要。为了让URP正确识别并渲染你的Shader，必须在SubShader的Tags中明确声明"RenderPipeline"="UniversalPipeline"。同时，"RenderType"="Opaque"这样的标签对于正确的渲染队列和后期处理效果也很有必要。

3. 实战迁移：逐步拆解一个基础Unlit Shader

现在，我们以一个最简单的、只显示纯色的Unlit Shader为例，进行从头到尾的迁移。假设我们有一个旧的CG Shader如下：

// Legacy CG Shader (Built-in RP) Shader "Custom/MyOldUnlitShader" { Properties { _Color ("Main Color", Color) = (1,1,1,1) } SubShader { Tags { "RenderType"="Opaque" } Pass { CGPROGRAM #pragma vertex vert #pragma fragment frag #include "UnityCG.cginc" struct appdata { float4 vertex : POSITION; }; struct v2f { float4 pos : SV_POSITION; }; float4 _Color; v2f vert (appdata v) { v2f o; o.pos = UnityObjectToClipPos(v.vertex); return o; } fixed4 frag (v2f i) : SV_Target { return _Color; } ENDCG } } }

我们的目标是将它迁移为URP兼容的HLSL Shader。

3.1 第一步：重写Shader声明与属性块

改动不大，但路径最好清晰。Properties块可以完全保留，因为ShaderLab的Properties语法是通用的。

Shader "Custom/MyURPUnlitShader" { Properties { // _MainTex 属性可以保留，即使本例不用 // _Color 属性名和类型不变 _Color ("Main Color", Color) = (1,1,1,1) }

3.2 第二步：更新SubShader Tags

这是让URP识别你的Shader的关键。将Tags修改为URP标准格式。

SubShader { // 关键：添加RenderPipeline标签，告诉Unity这是URP着色器 Tags { "RenderType"="Opaque" "RenderPipeline"="UniversalPipeline" } // ... Pass 块 }

"RenderPipeline"="UniversalPipeline"这个标签是URP Shader的身份证。没有它，URP渲染器可能会忽略这个SubShader，导致材质显示为粉色（Missing Shader）。

3.3 第三步：替换CGPROGRAM为HLSLPROGRAM

在Pass块内部，将CGPROGRAM和ENDCG替换为HLSLPROGRAM和ENDHLSL。

Pass { HLSLPROGRAM // ... 顶点和片元着色器代码将写在这里 ENDHLSL }

3.4 第四步：包含URP核心库并重写结构体

删除旧的#include "UnityCG.cginc"，替换为URP的核心库。

// 核心：包含URP的HLSL核心库，它提供了TransformObjectToHClip等关键函数 #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"

接着，重写输入输出结构体。采用URP中更常见的命名约定。

// 输入结构体：从应用（CPU）传递到顶点着色器的数据 struct Attributes { // 使用POSITION语义，但变量名明确表示为对象空间位置 float4 positionOS : POSITION; // 如果需要，可以在这里添加法线、UV等 // float3 normalOS : NORMAL; // float2 uv : TEXCOORD0; }; // 输出结构体：从顶点着色器传递到片元着色器的数据（插值后） struct Varyings { // 必须使用SV_POSITION语义声明裁剪空间位置 float4 positionHCS : SV_POSITION; // 可以声明需要插值的变量，例如UV // float2 uv : TEXCOORD0; };

注意：positionHCS中的HCS代表 Homogeneous Clip Space（齐次裁剪空间），这是一个很好的命名习惯。

3.5 第五步：重写顶点着色器函数

将顶点着色器函数中的空间变换函数替换为URP的版本。

// 顶点着色器 Varyings vert(Attributes IN) { Varyings OUT; // 核心变换：使用URP提供的函数，将对象空间坐标变换到齐次裁剪空间 OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); // 如果需要传递UV，在这里进行赋值或简单变换 // OUT.uv = TRANSFORM_TEX(IN.uv, _MainTex); // 需要包含对应库和定义_MainTex_ST return OUT; }

TransformObjectToHClip(IN.positionOS.xyz)是这一步的灵魂。它替代了旧的UnityObjectToClipPos或矩阵乘法，更简洁且与URP渲染管线深度集成。

3.6 第六步：重写片元着色器与属性声明

片元着色器改动相对较小，主要是返回类型和精度说明符可能略有差异。同时，需要在HLSL代码块中重新声明在Properties中定义的属性。

// 在HLSL代码中重新声明在Properties块中定义的属性 // 变量名必须与Properties中的一致 half4 _Color; // 片元着色器 half4 frag(Varyings IN) : SV_Target { // 直接返回颜色属性 half4 finalColor = _Color; return finalColor; }

在HLSL中，half4是一种中等精度的数据类型（16位浮点数），在移动平台和不需要高精度颜色的情况下使用，可以提升性能。SV_Target语义表示输出到渲染目标。

3.7 完整迁移后的代码

将以上所有步骤整合，得到完整的URP HLSL Shader：

Shader "Custom/MyURPUnlitShader" { Properties { _Color ("Main Color", Color) = (1,1,1,1) } SubShader { Tags { "RenderType"="Opaque" "RenderPipeline"="UniversalPipeline" } Pass { HLSLPROGRAM #pragma vertex vert #pragma fragment frag #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" struct Attributes { float4 positionOS : POSITION; }; struct Varyings { float4 positionHCS : SV_POSITION; }; half4 _Color; Varyings vert(Attributes IN) { Varyings OUT; OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); return OUT; } half4 frag(Varyings IN) : SV_Target { return _Color; } ENDHLSL } } }

将这个Shader保存为一个新的.shader文件，在URP项目中使用，它应该能正常工作并显示你设定的颜色。

4. 进阶迁移要点与常见坑点

基础迁移完成后，现实项目中的Shader要复杂得多。下面是一些进阶迁移中必然会遇到的要点和坑。

4.1 纹理采样与UV变换

在CG中，我们使用tex2D(_MainTex, i.uv)来采样纹理，并使用TRANSFORM_TEX宏来处理纹理的缩放和偏移（Tiling & Offset）。

在URP HLSL中，流程类似，但需要包含不同的头文件并使用对应的宏。

1. 声明纹理和采样器：通常需要成对声明Texture2D和SamplerState。

   TEXTURE2D(_MainTex); SAMPLER(sampler_MainTex); float4 _MainTex_ST; // 这个必须声明，用于存储Tiling和Offset

2. 包含所需库：TRANSFORM_TEX宏定义在Macros.hlsl中，而该文件通常通过Core.hlsl被间接包含。但为了使用SAMPLE_TEXTURE2D宏，最佳实践是包含SurfaceInput.hlsl或明确包含Sampling.hlsl。一个简单可靠的方法是继续使用Core.hlsl，它已经为你安排好了大部分基础。
3. 变换UV：在顶点着色器中，使用TRANSFORM_TEX(IN.uv, _MainTex)来计算最终的UV。
4. 采样纹理：在片元着色器中，使用SAMPLE_TEXTURE2D宏进行采样，它内部处理了采样器状态。

   half4 frag(Varyings IN) : SV_Target { half4 col = SAMPLE_TEXTURE2D(_MainTex, sampler_MainTex, IN.uv); return col * _Color; }

常见坑点：直接使用tex2D函数在URP HLSL中可能无法编译或采样不正确。务必使用URP提供的TEXTURE2D/SAMPLER/SAMPLE_TEXTURE2D这一套流程。

4.2 法线、光照与顶点颜色

• 法线：如果Shader涉及光照（即使是简单的兰伯特模型），你需要处理法线。在URP中，通常需要在顶点着色器中将法线从对象空间转换到世界空间（或视图空间），这需要使用TransformObjectToWorldNormal()函数（位于SpaceTransforms.hlsl）。记得在Attributes和Varyings结构体中添加normalOS和normalWS字段。
• 简单光照：URP提供了简化光照模型。对于自定义光照，你可能需要包含Lighting.hlsl并访问_MainLightPosition和_MainLightColor等内置变量。对于复杂的表面着色器逻辑，建议参考URP自带的Lit.shader或SimpleLit.shader。
• 顶点颜色：直接从Attributes中获取float4 color : COLOR;并传递到Varyings即可，语义没有变化。

4.3 矩阵与空间查询

在CG中，你可能直接使用_Object2World、_World2Object、UNITY_MATRIX_MVP等内置矩阵。

在URP HLSL中，这些矩阵不再直接可用。所有变换都应通过函数进行。例如：

• TransformObjectToWorld(float3 posOS)：对象空间 -> 世界空间。
• TransformWorldToObject(float3 posWS)：世界空间 -> 对象空间。
• TransformWorldToHClip(float3 posWS)：世界空间 -> 齐次裁剪空间。
• 如果需要获取矩阵本身（例如用于自定义计算），它们定义在ShaderVariablesFunctions.hlsl中，如GetObjectToWorldMatrix()、GetWorldToObjectMatrix()等。你需要包含相关文件并查询使用。

4.4 多编译变体与Shader Feature

CG中使用#pragma multi_compile或#pragma shader_feature来生成Shader变体。在URP HLSL中，语法基本保持不变，但必须将其放在HLSLPROGRAM块内，#include语句之后，否则可能会编译错误或变体生成失败。

HLSLPROGRAM #pragma vertex vert #pragma fragment frag #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" // 多编译指令必须放在include之后 #pragma multi_compile _ _MAIN_LIGHT_SHADOWS #pragma multi_compile _ _ADDITIONAL_LIGHTS // ... 其余代码

5. 调试、验证与性能考量

迁移完成后，Shader能编译通过并不代表万事大吉。

5.1 调试与验证清单

1. 检查控制台：确保没有编译错误或警告。URP对语义和类型检查更严格。
2. 观察材质表现：在场景中应用材质，检查颜色、纹理、光照是否与预期一致。最常见的错误是空间变换错误导致的顶点位置错乱（模型扭曲或消失）。
3. 使用Frame Debugger：Unity的Frame Debugger是神器。逐步查看Draw Call，确认你的Shader是否正确执行，输入数据（如UV、法线）是否正确传递。
4. 对比渲染结果：如果可能，在相同的场景和光照条件下，用旧的内置管线Shader和新的URP HLSL Shader进行渲染对比，确保视觉效果一致（考虑到光照模型差异，完全一致可能很难，但主体效果应相近）。

5.2 性能考量与SRP Batcher

迁移到HLSL的一个重要目标是兼容SRP Batcher。SRP Batcher是URP的核心性能优化，它可以大幅减少CPU在提交Draw Call时的开销。

如何让Shader兼容SRP Batcher？关键在于Shader中常量缓冲区（Constant Buffer）的声明方式。URP Lit Shader已经做好了这些。对于自定义Shader，一个简单的检查方法是：在Unity编辑器的Inspector窗口中查看你的材质，如果底部显示“SRP Batcher: Compatible”，则说明兼容。

通常，你需要确保：

• 所有Properties中定义的、在HLSL代码中使用的变量（如_Color,_MainTex_ST），如果属于“每材质”数据，应该按照URP的规定声明在特定的常量缓冲区中。但对于许多不复杂的自定义Unlit Shader，只要按照上述基础步骤编写，并且没有使用过多特殊的内置管线变量，通常能自动兼容或接近兼容。复杂的、使用了很多属性的Shader可能需要参考URP内置Shader的结构来组织CBUFFER。

5.3 常见错误与解决方案速查表

迁移一个Shader就像给它做一次大手术，需要耐心和细致。从最简单的Unlit Shader开始练手，理解每一步的原理，再逐步处理带有纹理、法线、光照的复杂Shader，是最高效的学习路径。当你成功将第一个自研的复杂特效Shader从CG迁移到HLSL并在URP下完美运行时，那种成就感会让你觉得这一切都是值得的。记住，核心思路就三点：换头文件（Core.hlsl）、换变换函数（TransformObjectToHClip等）、换数据声明方式（明确的结构体和语义）。抓住这三点，你就抓住了URP Shader迁移的牛鼻子。