对Unity一个Shader编译Bug的分析(Unrecognized sampler 'samplerunity_lightmap)

---

 写在前面

---

　　Unity的用户量越来越大,越来越有钱,这几年摊子也铺的越来越大,所以各个版本总是有很多Bug。对于一些Bug官方在ReleaseNote里的说明是很不详细的,而对于一些渲染相关的Bug,有时候更是偷偷的修复,即使贴出来也信息量极少。如果你想复用它的一些内置Shader代码到自己的Shader中时千万要注意。
　　今天要分析的Bug是我在2017版本(本人使用2017.4)中遇到的,Shader编写完会出现一个 program 'fragXXX':Unrecognized sampler 'samplerunity_lightmap'的报错.你相信若是你遇到了这个报错,一定会一头雾水,我做错了什么？这个Bug已经在2018.1版本中修复掉了,并在ReleaseNote中给出说明:
　　

　　GI: Building Standalone no longer throws ... program 'frag_surf': Unrecognized sampler 'samplerunity_lightmap' .. error with specific shaders. Shadowmasks now use their own sampler. (955176)
　　

　　Unity虽然告诉你它们解决了这个问题,但是没告诉你它们是怎么改的,在哪改的,所以如果你遇到了这个bug,又不能将版本升到2018的话,就得自己分析下这个问题

---

 哪里报错

---

　　一开始遇到报错,我并不知道我哪里的代码写错了,即使翻看到了上面ReleaseNote里的内容,我也不知道我的代码哪里出了问题。最后我还是靠着一点一点注释掉代码找到了导致报错的那行代码(我们项目是使用ShadowMask来烘培阴影的,如果我用传统方式烘培阴影不会报错):

UNITY_LIGHT_ATTENUATION(atten,i,posWorld); 

对于这个宏我尝试着继续深挖,下了一份2017.4版本的shader源码,注意,Unity的内置宏根据光源类型会有多种定义,我这里只考虑方向光。

//AutoLight.cginc

#ifdef DIRECTIONAL
    #define UNITY_LIGHT_ATTENUATION(destName, input, worldPos) fixed destName = UNITY_SHADOW_ATTENUATION(input, worldPos);
#endif

//AutoLight.cginc

#if defined(HANDLE_SHADOWS_BLENDING_IN_GI) // handles shadows in the depths of the GI function for performance reasons
    ...
#elif defined(SHADOWS_SCREEN) && !defined(LIGHTMAP_ON) && !defined(UNITY_NO_SCREENSPACE_SHADOWS) // no lightmap uv thus store screenPos instead
    ...
#else
#   if defined(SHADOWS_SHADOWMASK)
#       define UNITY_SHADOW_COORDS(idx1) unityShadowCoord2 _ShadowCoord : TEXCOORD##idx1;
#       define UNITY_TRANSFER_SHADOW(a, coord) a._ShadowCoord = coord * unity_LightmapST.xy + unity_LightmapST.zw;
#       if (defined(SHADOWS_DEPTH) || defined(SHADOWS_SCREEN) || defined(SHADOWS_CUBE) || UNITY_LIGHT_PROBE_PROXY_VOLUME)
#           define UNITY_SHADOW_ATTENUATION(a, worldPos) UnityComputeForwardShadows(a._ShadowCoord, worldPos, 0)
#       else
#           ...
#       endif
#   else
...
#   endif
#endif

//AutoLight.cginc

half UnityComputeForwardShadows(float2 lightmapUV, float3 worldPos, float4 screenPos) 
{
    //fade value
    ...
    //baked occlusion if any
    half shadowMaskAttenuation = UnitySampleBakedOcclusion(lightmapUV, worldPos);
    ...
}

//UnityShadowLibrary.cginc

fixed UnitySampleBakedOcclusion (float2 lightmapUV, float3 worldPos)
{
    #if defined (SHADOWS_SHADOWMASK)
        #if defined(LIGHTMAP_ON)
            fixed4 rawOcclusionMask = UNITY_SAMPLE_TEX2D_SAMPLER(unity_ShadowMask, unity_Lightmap, lightmapUV.xy);
        #else
           ...
        #endif
        ...
    #else
           ...
    #endif
}

最后问题正出在最可疑的UNITY_SAMPLE_TEX2D_SAMPLER,我们来看下:

//HLSLSupport.cginc

#if defined(SHADER_API_D3D11) || defined(SHADER_API_XBOXONE) || defined(UNITY_COMPILER_HLSLCC) || defined(SHADER_API_PSSL)
...
#define UNITY_SAMPLE_TEX2D_SAMPLER(tex,samplertex,coord) tex.Sample (sampler##samplertex,coord)
...
#endif

这是DX11环境下的宏定义,我们的报错也正是只在DX11编辑器模式下有.(Unity2017开始放弃了对DX9的支持)

有了上面的代码,最终出问题的代码实际就是:

unity_ShadowMask.Sample(samplerunity_Lightmap,lightmapUV.xy);

这里的参数samplerunity_Lightmap也正好和报错的内容对上了。

---

 为什么报错

---

 报错信息中说无法识别samplerunity_lightmap这个采样器(请无视L被小写)。那咱们就先看看unity有没有声明这个采样器

//UnityShaderVariables.cginc

// ----------------------------------------------------------------------------
// Lightmaps

// Main lightmap
UNITY_DECLARE_TEX2D_HALF(unity_Lightmap);
// Directional lightmap (always used with unity_Lightmap, so can share sampler)
UNITY_DECLARE_TEX2D_NOSAMPLER_HALF(unity_LightmapInd);
// Combined light masks
#if defined (SHADOWS_SHADOWMASK)
    #if defined(LIGHTMAP_ON)
        //Can share sampler if lightmap are used.
        UNITY_DECLARE_TEX2D_NOSAMPLER(unity_ShadowMask);
    #else
        UNITY_DECLARE_TEX2D(unity_ShadowMask);
    #endif
#endif

我把UNITY_DECLARE_TEX2D_HALF和UNITY_DECLARE_TEX2D_NOSAMPLER如下(注意,根据不同环境,存在多套宏定义,此处找出的是符合当前环境的)

//HLSLSupport.cginc

#define UNITY_DECLARE_TEX2D_HALF(tex) Texture2D tex; SamplerState sampler##tex

#define UNITY_DECLARE_TEX2D_NOSAMPLER(tex) Texture2D tex

绝大部分UnityShader都会包含UnityCG.cginc,后者又引入了UnityShaderVariables.cginc,进而又引入了HLSLSupport.cginc,所以上述的两个定义宏一定会被包含进去,也就是

Texture2D unity_Lightmap;
SamplerState samplerunity_Lightmap;
...
Texture2D unity_ShadowMask;

这时候我们再回头去看一下前面找到的引发错误的那一行.

unity_ShadowMask.Sample(samplerunity_Lightmap,lightmapUV.xy);

　　奇怪,这几个变量都声明了呀,怎么会找不到呢？别想远了,Unity的ShaderLab代码会编成目标平台的图形接口代码(此处为DX11的HLSL),跟其他编程语言编译器一样,。在这个过程中会进行优化,最基础的就是移除掉只声明未使用的变量,或者被使用但未影响最终返回结果的变量和语句。
　　看来这个报错就是由于Unity发现samplerunity_Lightmap这个变量没有被使用过。刚刚的那条Sample语句里不就使用了samplerunity_Lightmap了么？这就又涉及到Unity关于DX11的SamplerState的一些规约,
大家去阅读一下这篇官方的文章,这里就不展开了,从文中看到下面这句话:

Unity allows declaring textures and samplers using DX11-style HLSL syntax, with a special naming convention to match them up: samplers that have names in the form of “sampler”+TextureName will take sampling states from that texture.

 　　可见Unity对samplerunity_Lightmap这种命名的采样器变量会去获取unity_Lightmap贴图的sample States,那也就是说samplerunity_Lightmap是依赖于unity_Lightmap的存在。如果unity_Lightmap根据优化条件被优化掉的话,samplerunity_Lightmap的存在也就是没有意义的。

　　Unity发现代码中尝试访问一个没有对应texture的SamplerState变量就会给报一个无法识别SampleState的错误。

---

 如何解决

---

通过上面的分析,最终确定了问题的原因,解决的方案也就很明确了,从两个方向出发:

1.在使用unity_ShadowMask.Sample(samplerunity_Lightmap，lightmapUV.xy)之前要对unity_Lightmap贴图进行某种方式的使用,以避免被优化掉。
2.Unity为了节省SamplerState让unity_ShadowMask去复用unity_Lightmap的采样器,这是导致上述问题的本质原因,那么我们让unity_ShadowMask也有自己的采样器,并将代码改为
unity_ShadowMask.Sample(unity_ShadowMask,lightmapUV.xy)即可。

我们再看看Unity2018里是怎么修复掉这个bug的。

首先在UnityShaderVariables.cginc中去掉了对unity_Lightmap采样器的复用,让unity_ShadowMask有自己的采样器

//UnityShaderVariables.cginc

// ----------------------------------------------------------------------------
// Lightmaps

// Main lightmap
UNITY_DECLARE_TEX2D_HALF(unity_Lightmap);
// Directional lightmap (always used with unity_Lightmap, so can share sampler)
UNITY_DECLARE_TEX2D_NOSAMPLER_HALF(unity_LightmapInd);
// Shadowmasks
UNITY_DECLARE_TEX2D(unity_ShadowMask);

并且对UnityShadowLibrary.cginc中UnitySampleBakedOcclusion函数进行了修改

//UnityShadowLibrary.cginc

// ------------------------------------------------------------------
// Used by the forward rendering path
fixed UnitySampleBakedOcclusion (float2 lightmapUV, float3 worldPos)
{
    #if defined (SHADOWS_SHADOWMASK)
        #if defined(LIGHTMAP_ON)
            fixed4 rawOcclusionMask = UNITY_SAMPLE_TEX2D(unity_ShadowMask, lightmapUV.xy);
        #else
          ...
        #endif
...
    #else
      ...
    #endif
}

也就是我们说的方法二,总结下来如果你遇到问题又不想升级版本的话,可以用方法1,或者用方法2对着2018版本的内置Shader,把编辑器目录里的内置Shader做一些修改。

　　之所以写出这篇文章,更多的是想分享对一个问题的分析和探索的过程。虽然这个问题一开始看似除了升级版本没有其它的解决办法。但顺着问题的脉络一点点寻找线索,最终发现问题,解决问题。但这个过程是享受的。

希望大家能有所收获。

　　尊重他人智慧成果,若要转载,请注明作者esfog,原文地址https://www.cnblogs.com/Esfog/p/Analysis_A_Unity_ShaderCompile_Bug.html