Unity TextMesh Pro SDF着色器宏解析：UNDERLAY效果与版本兼容性

1. 项目概述

在Unity中处理高质量文本渲染，TextMesh Pro（TMP）是绕不开的核心工具，而它的灵魂在于其基于Signed Distance Field（SDF，有向距离场）的着色器。这个系列文章已经来到了第七篇，我们继续深挖TMP_SDF着色器中那些看似不起眼，实则至关重要的宏定义。上一期我们分析了OUTLINE_ON等宏，今天我们把目光聚焦在UNDERLAY_ON、UNDERLAY_INNER以及Unity版本相关的宏上。这些宏控制着文本的“底影”效果和不同Unity版本下的裁剪兼容性，是让文字在不同背景上清晰可读、保证项目跨版本稳定的关键。无论你是想定制自己的TMP材质，还是遇到了“升级Unity后文字显示异常”的坑，理解这部分内容都能让你从“知其然”进阶到“知其所以然”。

2. 核心宏功能解析与设计思路

2.1 UNDERLAY宏：为文字添加“灵魂底影”

在TMP_SDF着色器中，UNDERLAY_ON和UNDERLAY_INNER这两个宏，共同实现了一种我称之为“文字底影”的效果。这可不是简单的投影（Drop Shadow），而是一种更灵活、常用于增强文字可读性的技术。

为什么需要UNDERLAY？想象一下，把白色文字放在一张复杂、颜色多变的图片上，文字很容易被背景“吃掉”，导致难以辨认。直接给文字加粗或加描边有时会显得笨重。这时，一个柔和、颜色可调的底影（比如半透明的深色）就能在文字和背景之间建立一个视觉缓冲层，显著提升文字的可读性，同时保持设计上的轻盈感。这在游戏UI、字幕、或者任何文字需要叠加在动态背景上的场景中极其有用。

两种模式的设计考量：

1. UNDERLAY_ON（外部底影）：这是最常用的模式。底影渲染在文字主体（包括描边）的外部。你可以把它理解为给文字加了一个向外扩散的、柔和的彩色光晕。它不改变文字本身的形状和大小，只是在外围增加了一层视觉衬托。
2. UNDERLAY_INNER（内部底影）：这个模式相对特殊，底影渲染在文字主体内部。它产生的效果更像是让文字内部带有一种“内发光”或者“内部衬底”的感觉。这种效果通常用于创造一些风格化的文字，比如霓虹灯管效果（亮边内部有暗色衬底），或者让文字看起来有凹陷感。

Shader中通过#pragma shader_feature __ UNDERLAY_ON UNDERLAY_INNER来声明这两个互斥的特性开关。这意味着在同一个材质实例上，你只能启用其中一种底影模式，或者都不启用。这种设计保证了Shader变体（Variant）的可管理性，避免生成不必要的Shader组合。

2.2 版本兼容宏：应对Unity的API变迁

另一个至关重要的部分是Unity版本相关的条件编译，主要体现在像素着色器（PixShader）末尾的矩形遮罩（ClipRect）处理上。代码中清晰地出现了#if UNITY_VERSION < 530这样的判断。

背后的痛点：Unity 5.3版本是一个重要的分水岭。在此版本之前，Unity UI系统（uGUI）的矩形遮罩功能在Shader中的实现方式与之后不同。具体来说，在5.2及更早版本中，裁剪是通过一个名为_UseClipRect的属性和一套特定的计算来完成的。而从Unity 5.3开始，Unity引入了一个更通用、更强大的内置函数UnityGet2DClipping（或其相关机制）来处理UI元素的裁剪，并且支持了软边（Softness）遮罩。

TMP的应对策略：TMP作为一个需要兼容广泛Unity版本（从5.x到最新的LTS版本）的资产包，其着色器必须能适应这种底层API的变化。它不能简单地只使用新API，否则在旧项目中会报错或功能失效；也不能只使用旧方法，否则无法享受新版本带来的功能（如软遮罩）。因此，条件编译成为了唯一的选择。

注意：这里使用的UNITY_VERSION是一个由Unity Shader编译器预定义的宏，其值对应着Unity的主版本号（如530代表5.3）。通过判断这个值，Shader可以在编译时就决定为当前Unity版本生成哪一段代码，从而确保运行时不会调用不存在的函数或访问不存在的属性。这是保持Shader跨版本兼容性的标准做法。

3. 核心细节解析与实操要点

3.1 UNDERLAY效果的参数驱动原理

底影效果并非魔法，它完全由一系列材质参数控制，并在顶点着色器（VertShader）和像素着色器（PixShader）中分步计算。理解这个数据流，是自定义效果的基础。

控制参数（Properties）：在Shader的Properties块中，与底影相关的参数有：

• _UnderlayColor：底影的颜色和透明度。
• _UnderlayOffsetX/Y：底影在X和Y方向上的偏移量。这是实现“投影”方向感的关键。
• _UnderlayDilate：底影的扩张或收缩。正值向外扩张，负值向内收缩。
• _UnderlaySoftness：底影边缘的柔和度。
• _ScaleRatioC：一个缩放比率，通常用于自动调整底影参数与文字大小的比例关系，保证在不同字体大小下效果一致。

顶点着色器中的预处理：在VertShader函数中，当检测到启用了任一UNDERLAY宏时，会进行以下关键计算：

1. 独立缩放计算：底影的layerScale是基于文字主体的scale独立计算的，但会额外考虑_UnderlaySoftness的影响。这确保了底影的柔和度不会干扰文字本体的锐利度。

   layerScale /= 1 + ((_UnderlaySoftness * _ScaleRatioC) * layerScale);

2. 偏移量转换：_UnderlayOffsetX/Y是用户直观理解的“像素偏移”或“相对偏移”，但在SDF空间中，需要结合_GradientScale和字体纹理的_TextureWidth/Height将其转换为正确的纹理坐标偏移量（layerOffset）。这一步保证了无论屏幕分辨率如何，底影的偏移视觉比例是稳定的。
3. 数据传递：计算好的layerScale和layerBias（经过UnderlayDilate调整后的阈值偏差）被封装进output.underlayParam，纹理坐标偏移和原始透明度被封装进output.texcoord1，传递给像素着色器。

像素着色器中的合成：在PixShader中，根据不同的宏，进行最终的颜色混合：

• UNDERLAY_ON：这是一个标准的“外部叠加”操作。先采样底影区域的SDF值（d），计算其可见性（saturate(d - input.underlayParam.y)），然后以(1 - c.a)为系数叠加到当前颜色c上。(1 - c.a)是关键，它意味着底影只会出现在文字本体（和描边）透明的区域，从而实现“底影在文字后面”的效果。混合方式是加法（+=），并且预乘了底影颜色的Alpha（_UnderlayColor.rgb * _UnderlayColor.a），这是正确的透明颜色混合方式。
• UNDERLAY_INNER：计算更巧妙一些。它先计算了文字本体（包括描边）的可见性sd。然后采样底影，但这次用(1 - saturate(d - input.underlayParam.y))，这意味着它取的是SDF图形的内部区域。最后，将底影颜色与sd * (1 - c.a)相乘再叠加。这样，底影只出现在文字内部且当前像素未被填充的区域，形成了“内衬”效果。

3.2 版本分支下的遮罩处理差异

让我们仔细对比一下Shader中矩形遮罩处理的两套代码：

Unity 5.2及之前（旧路径）：

#if UNITY_VERSION < 530 if (_UseClipRect) { half2 m = saturate((_ClipRect.zw - _ClipRect.xy - abs(input.mask.xy)) * input.mask.zw); c *= m.x * m.y; } #endif

• 条件执行：它被包裹在一个if (_UseClipRect)判断中。这意味着在旧版本中，矩形遮罩可能是一个可选的特性，需要显式开启。
• 计算逻辑：计算方式与新版类似，都是通过abs(input.mask.xy)获取当前像素到裁剪矩形四边的距离，然后利用saturate和乘法得到一个0到1的遮罩系数m。input.mask.zw存储了基于_MaskSoftnessX/Y和像素大小的软化因子。

Unity 5.3及之后（新路径）：

#else half2 m = saturate((_ClipRect.zw - _ClipRect.xy - abs(input.mask.xy)) * input.mask.zw); c *= m.x * m.y; #endif

• 无条件执行：去掉了if (_UseClipRect)判断。这表明在新版本的UI系统中，矩形裁剪是默认且始终生效的机制（对于UI元素），_ClipRect可能由CanvasRenderer自动设置。
• 功能一致性：尽管执行条件不同，但核心数学计算是完全一致的。这保证了视觉效果在版本迁移前后的一致性。

实操心得：当你从Unity 5.2或更早版本升级一个使用了TMP的项目到新版本时，如果发现UI文字裁剪出现问题，检查Shader中这段代码的编译路径是否正确至关重要。有时，Shader的编译缓存可能导致旧版本的变体被错误使用。一个可靠的解决方法是，在Project面板中找到TMP的Shader文件（如TMP_SDF-Mobile.shader），右键选择“Reimport”，强制Unity使用当前版本的Shader编译器重新编译它。

4. 宏控制的完整渲染流程拆解

4.1 从顶点到像素的数据流与宏开关

要全局理解这些宏如何工作，我们必须梳理一次完整的渲染数据流。当我们在材质上勾选“Underlay”选项时，引擎和Shader编译器会协同完成以下工作：

1. 材质变体编译：当你修改材质并启用Underlay时，Unity的Shader编译器会识别到#pragma shader_feature __ UNDERLAY_ON UNDERLAY_INNER。这会为当前材质生成一个特定的Shader变体。这个变体的代码中，UNDERLAY_ON宏被定义为1（或true），而UNDERLAY_INNER未定义。这意味着在后续的编译中，所有#if UNDERLAY_ON的代码块都会被包含，而#if UNDERLAY_INNER的块会被剔除。这保证了最终GPU执行的代码是最精简、只包含所需功能的。

2. 顶点着色器阶段：在这个阶段，宏主要控制顶点输出结构体（pixel_t）的成员以及相应的计算。

• 如果任一UNDERLAY宏启用，结构体中就会包含texcoord1和underlayParam这两个字段。同时，在VertShader函数内部，#if (UNDERLAY_ON | UNDERLAY_INNER)包围的代码块会被激活，计算层偏移（layerOffset）、层缩放（layerScale）和层偏差（layerBias），并将结果填充到输出结构体中。
• 如果未启用，这些字段和计算代码在编译时就被移除，顶点着色器输出的数据量更小，传输到像素着色器的带宽占用也更少。

3. 像素着色器阶段：这里是效果合成的最终舞台，宏控制着颜色混合的逻辑分支。

• 首先，计算文字本体颜色c。
• 接着，#ifdef OUTLINE_ON决定是否进行描边的颜色插值。
• 然后，#if UNDERLAY_ON和#if UNDERLAY_INNER根据编译出的变体，决定执行哪一段底影混合代码。这两段代码是互斥的，不会同时存在。
• 最后，进行矩形裁剪（UNITY_VERSION宏决定使用哪套裁剪逻辑）。
• 在裁剪之后，还有一个关键的步骤：#if (UNDERLAY_ON | UNDERLAY_INNER) c *= input.texcoord1.z;。这里的input.texcoord1.z存储的是顶点输入的原始颜色Alpha（input.color.a）。这一步至关重要：它将顶点颜色透明度最终应用到底影效果上。这意味着你可以通过修改顶点颜色（例如，在代码中设置TMP_Text.color的Alpha）来动态控制整个文字（包括底影）的淡入淡出，而底影颜色自身的Alpha（_UnderlayColor.a）只控制底影的固有透明度。

4.2 参数联动与视觉调试技巧

理解了流程，我们来看看如何通过参数微调获得理想效果。以下是一个参数影响关系的速查表：

调试技巧：在Scene视图或Game视图调试时，我习惯采用“分层剥离”法：

1. 先关底影：将Underlay Color的Alpha设为0，或者直接禁用Underlay特性，确保文字本体和描边效果是你想要的。
2. 单独调底影：将文字本体颜色调成纯色（如白色），描边暂时关闭或调成对比色。然后慢慢调整底影的Offset、Dilate和Softness，观察底影形状的变化是否符合预期。
3. 调整颜色与混合：最后调整Underlay Color，注意其Alpha值控制的是底影层的“浓度”，而顶点颜色Alpha（或材质整体透明度）控制的是整个文字（含底影）的“可见度”。理解这个区别能避免很多混合错误。
4. 检查版本差异：如果怀疑裁剪问题，可以尝试在材质上调整Mask Softness参数。如果在旧版Unity中软遮罩无效，而在新版中有效，那很可能就是Shader版本编译路径的问题。

5. 常见问题与排查技巧实录

在实际项目开发中，与TMP_SDF宏相关的问题虽然不常发生，但一旦出现往往令人困惑。以下是我总结的几个典型问题及其排查思路。

5.1 问题一：启用了Underlay，但屏幕上什么都看不到

排查步骤：

1. 检查颜色Alpha：这是最常见的原因。首先确认_UnderlayColor的Alpha值是否大于0。一个常见的疏忽是只调整了RGB，忘了调A。
2. 检查偏移和扩张：_UnderlayOffsetX/Y或_UnderlayDilate的值可能设置得过于极端，导致底影完全偏移到了可视区域之外，或者过度收缩以至于看不见。尝试将它们重置为0，再慢慢调整。
3. 检查渲染队列和混合模式：TMP_SDF-Mobile Overlay.shader的渲染队列（Queue）是“Overlay”，混合模式是“Blend One OneMinusSrcAlpha”。如果你的场景中有其他Overlay物体或者混合设置被意外修改，可能会造成遮挡或混合错误。确保你的材质球使用的是正确的Shader，并且没有在代码中被动态修改渲染状态。
4. 检查顶点颜色Alpha：记住，最终输出颜色会乘以input.texcoord1.z（即顶点颜色Alpha）。如果你通过脚本动态修改了TMP文本的color属性，并降低了Alpha，那么底影的可见度也会同步降低。在调试时，可以尝试在代码中暂时将color设置为Color.white。

5.2 问题二：从Unity旧版本升级后，文字裁剪（Mask）异常

问题现象：升级Unity版本（例如从5.2升级到2018.x或更高）后，原本使用RectMask2D或ScrollRect裁剪的TMP文本，要么裁剪完全失效，要么裁剪边缘变得异常尖锐（失去了软边效果）。

根本原因：正如前文所述，这是因为Shader使用了错误的条件编译路径。可能的原因有：

• Shader缓存：Unity没有为升级后的项目重新编译TMP的Shader变体。
• 材质球引用：项目中的材质球可能还引用着旧版本编译的Shader二进制数据。

解决方案：

1. 重新导入Shader：在Project窗口中，导航到TextMesh Pro/Resources/Shaders文件夹，找到你正在使用的SDF Shader文件（例如TMP_SDF-Mobile.shader），右键点击并选择“Reimport”。这能强制Unity使用新版本的编译器重新编译该Shader。
2. 更新材质球：如果问题依旧，可能需要手动更新材质球。选中出问题的材质球，在Inspector面板顶部，检查Shader路径是否正确指向TextMesh Pro/...。有时可以尝试将Shader临时切换为另一个，再切换回来，以刷新其关联的变体。
3. 检查RectMask2D组件：确保RectMask2D组件正常工作，并且其“Softness”参数（如果适用）被正确设置。新版Unity中，软遮罩的计算可能更加依赖于CanvasRenderer传递的数据。

5.3 问题三：Underlay Inner效果不符合预期，看起来像外部发光

排查思路：UNDERLAY_INNER的效果高度依赖于_UnderlayDilate和_UnderlayOffset参数。

• Dilate为正值：这会使底影的SDF阈值向外部扩张，导致底影区域变大，更容易溢出到文字轮廓之外，从而看起来像外部效果。尝试将_UnderlayDilate设置为负值（如-0.2到-0.5），让底影向文字内部收缩。
• Offset值过大：即使Dilate为负，过大的Offset也可能将底影“推”出文字边界。尝试先将Offset归零，调整好Dilate获得清晰的内衬效果后，再微调Offset来制造内部的光源方向感。
• 理解混合公式：回顾UNDERLAY_INNER的像素着色器代码，它用(1 - saturate(d - input.underlayParam.y))来采样底影内部，并与文字本体的可见区域sd相乘。这意味着，底影只出现在“文字本体可见”与“底影内部区域”的交集部分。如果文字描边很粗，sd区域（文字+描边）很大，而底影内部区域（由负的Dilate定义）很小，那么最终显示的内衬区域也会很小。你需要协同调整描边宽度（_OutlineWidth）和底影的Dilate来获得最佳效果。

5.4 性能考量与变体控制

过多或不必要的Shader变体会增加包体大小和运行时内存占用，并可能影响GPU的渲染批次合并。TMP_SDF着色器通过shader_feature来管理变体，这是一种相对高效的方式，因为它只编译项目中实际材质用到的特性组合。

最佳实践：

• 按需创建材质：避免为每一个微调了Underlay参数的文字都创建新的材质实例。尽量复用材质。对于需要动态开关Underlay的情况，可以考虑使用MaterialPropertyBlock来修改参数，而不是替换整个材质。
• 清理未使用的材质：定期检查项目的材质资源，删除那些在场景中不再使用的、或参数重复的TMP材质。
• 理解变体数量：一个典型的TMP_SDF着色器，考虑OUTLINE_ON、UNDERLAY_ON、UNDERLAY_INNER、GLOW_ON（在其他Shader中）等特性，理论上可以产生多个变体。但在实际项目中，你的材质通常只会启用其中一两种固定的组合。Unity的构建管线会负责收集并只打包这些用到的变体。

通过对TMP_SDF着色器中这些宏的深入分析，我们不仅学会了如何调整一个底影效果，更重要的是理解了Unity Shader中条件编译、版本兼容、数据流传递和颜色混合的核心机制。这些知识是进行任何Shader定制和调试的基石。下次当你需要让文字在复杂的游戏场景中脱颖而出，或者解决一个棘手的渲染兼容性问题时，希望这份深入底层的分析能给你带来清晰的思路和解决问题的信心。