当前位置：首页 > news >正文

#pragma multi_compile #pragma shader_feature

news 来源：原创 2024/4/26 14:10:22

参考网址：
https://docs.unity3d.com/Manual/SL-MultipleProgramVariants.html
https://blog.csdn.net/candycat1992/article/details/51417965
http://blog.songyang.net/379.html
https://gameinstitute.qq.com/community/detail/121999

making multiple shader program variants
often it is convenient to keep most of a piece of shader code fixed but also allow slightly different shader “variants” to be produced. this is commonly called “mega shaders” or “ubder shaders”, and is achieved by compiling the shader code multiple times with different preprocessor directives for each case.
to achieve this in unity, u can add a #pragma multi_compile or #pragma shader_feature directive to a shader snippet. this also works in surface shaders.

at run time, unity picks up the appropriate variant from the material keywords (Material.EnableKeyword and Material.DisbaleKeyword) or global shader keywords (Shader.EnableKeyword and Shader.DisableKeyword).

how multi_compile_works

example directive:

#pragma multi_compile FANCY_STUFF_OFF FANCY_STUFF_ON

this example directive produces two shader variants : one with FANCY_STUFF_OFF , and another with FANCY_STUFF_ON. at run time, unity activates one of them based on the material or global shader keywords. if neither of these keywords are enabled, then unity uses the first one (in this example, FANCY_STUFF_OFF）.

u can add more than two keywords on a multi_compile line, for example:
#pragma multi_compile SIMPLE_SHADING BETTER_SHADING GOOD_SHADING BEST_SHADING

this example directive produces four shader varients: SIMPLE_SHADING, BETTER_SHADING,GOOD_SHADING, and BEST_SHADING.

to produce a shader variant with no preprocessor macro define, add a name that is just underscores (__). 两个下划线. this is common technique to avoid using up two keywords,这个技术可以避免使用两个关键字。because there is a limit on how many u can use in a project (see later section on keyword limits). for example:

#pragma multi_compile __ FOO_ON

this directive produces two shader variants: one with nothing defined(__), and one with FOO_ON defined.

difference between shader_feature and multi_compile
shader_feature is very similar to multi_compile. the only difference is that unity does not include unused variants of shader_feature in the build. for this reason, u should use shader_feature for keywords that are set from the materials, while multi_compile is better for keywords that are set from code globally.

additionally, there is shorthand notation with just one keyword:

#pragma shader_feature FANCY_STUFF

which is just shortcut for #pragma shader_feature __ FANCY_STUFF. it expands into two shader variants(first one without the define; second one with it).

combing several multi_compile lines
if u provide multi_compile lines, unity compiles the resulting shader for all possible combinations of the lines, for example:

#pragma multi_compile A B C
#pragma multi_compile D E

this produces three variants for the first line, and two for the second line. in total, it produces total six shader variants (A+D, A+E, B+D, B+E, C+D, C+E).

think of each multi_compile lines as controlling a single shader “feature”. keep in mind that the total number of shader variants grows really fast this way. for example ten multi_compile features, each with two options, produces 1024 shader variants in total.

keyword limits
when using shader variants, there is limit of 256 keywords in unity, and unity uses around 60 of them internally (therefore lowering the available limit). the keywords are enabled globally across a unity project, so be careful not to exceed the limit when u define multiple keywords in several different shaders.

一个项目的总的关键字的数量不能超过256个。

local keywords the main disadvantage of shader_feature and multi_compile is that all keywords defined in them contribute towards unity’s global keyword count limit 256 global keywords, plust 64 local keywords. to avoid this issue, u an use different shader variant directives: shader_feature_local and multi_compile_local.

shader_feature_local: similar to shader_feature, but enumerated keywords are local.
multi_compile_local: similar to multi_compile, but enumerated keywords are local.

local directives keep defined keywords under them specific to that shader, rather than applying them to the whole project. for this reason, u should use local keywords instead of global keywords. unless u are planning to enable those particular keywords through the global api.

u might see a change in performance when u start using local keywords, but the difference depends on how your projects is set up. the total number of local and global keywords per shader affects performance: in an idea set-up, use more local keywords and fewer global keywords, to reduce the total keyword count per shader. 多用局部关键字，减少全局关键字，可以提高性能。

if there are global and local keywords with the same name, unity priorities the local keyword.

limitations:
u can not use local keywords with APIs that make global keyword changes (such as Shader.EnableKeyword or CommandBuffer.EnableShaderKeyword).
there is a maximum of 64 unique local keywords per shader.
if a material has a local keyword enabled, and its shader changes to one that is no longer declared, unity creates a new global keyword.

example

#pragma multi_compile_local __ FOO_ON

this directive produces two shader variants: one with nothing defined (__), and one with FOO_ON defined as a local keyword.

the process for enabling local keywords is the same as enabling global keywords:

public Material mat;
private void Start()
{
	mat.EnableKeyword("FOO_ON");
}

built-in multi_compile shortcuts

there are several “shortcut” notations for compiling multiple shader variants. these are mostly to deal with different light, shadow and lightmap types in unity. see documentation on the rendering.pipeline for details.

multi_compile_fwdbase compiles all variants needed by PassType.ForwardBase. the variants deal with different lightmap types, and the main directional light’s shadows being enabled or disabled.

multi_compile_fwdadd compiles variants for PassType.ForwardAdd. this compiles variants to handle directional, spot or point light types and their variants with cookie textures.

multi_compile_fwdadd_fullshadows, same as multi_compile_fwdadd, but also includes ability for the lights to have real-time shadows.

multi_compile_fog expands to several variants to handle different fog types (off/linear/exp/exp2).

举例：

Shader "MyShader/TestFeature"
{
	SubShader
	{
		Pass
		{
			CGPROGRAM
			#pragma vertex vert
			#pragma fragment frag

			#pragma shader_feature AA

			#include "UnityCG.cginc"

			struct appdata
			{
				float4 vertex : POSITION;
			};

			struct v2f
			{
				float4 vertex : SV_POSITION;
			};


			v2f vert(appdata v)
			{
				v2f o;
				o.vertex = UnityObjectToClipPos(v.vertex);
				return o;
			}

			fixed4 frag(v2f i) : SV_Target
			{
				fixed4 col = fixed4(0,0,0,0);
				#ifdef AA
					col = fixed4(1, 0, 0, 1);
				#else
					col = fixed4(1, 1, 0, 1);
				#endif
					return col;
			}
			ENDCG
		}
	}
}

这里使用的是shader_feature 关键字，我们看看在未运行的时候，为我们编译出了几个变体：
在这里插入图片描述

只有一个空的，AA被忽略，因为未运行的时候AA没有被使用。

我们写个测试代码：

 public MeshRenderer meshRender;
 void Start()
  {
      meshRender = this.GetComponent<MeshRenderer>();
      Material mat = meshRender.material;
      mat.EnableKeyword("AA");
  }