ShaderLab syntax: Pass Tags

Passes use tags to tell how and when they expect to be rendered to the rendering engine.

Syntax

Tags { "TagName1" = "Value1" "TagName2" = "Value2" }

Specifies TagName1 to have Value1, TagName2 to have Value2. You can have as many tags as you like.

Details

Tags are basically key-value pairs. Inside a Pass tags are used to control which role this pass has in the lighting pipeline (ambient, vertex lit, pixel lit etc.) and some other options.

LightMode tag

LightMode tag defines Pass' role in the lighting pipeline. See render pipeline for details.

Possible values for LightMode tag are:

• Vertex: Rendered if any lights hit the object.
• VertexOrNone: (default) Rendered if only vertex lights or no lights at all hit the object.
• VertexOnly: Rendered if only vertex lights hit the object.
• PixelOnly: Rendered once for each pixel light, provided that no vertex lights hit the object.
• Pixel: Rendered once for each pixel light.
• VertexOrPixel: Rendered once if any light hits the object.
• VertexAndPixel: Rendered once if both vertex and pixel lights hit the object.
• PixelOrNone: Rendered if only pixel lights or no lights at all hit the object. Often used as an ambient pass.
• None: Rendered only if no lights affect the object.
• Always: Always rendered. All lights are setup for vertex lighting.

If the active subshader does not have a pass with LightMode of PixelOnly or Pixel, then Unity treats the shader as not supporting pixel lights. In that case, all lights affecting the object are treated as vertex lights.

The most common cases of LightMode usage are:

• Leave it at default value of VertexOrNone (i.e. not use the tag at all). All lights will be setup as vertex lighting + ambient; or if no lights are affecting the object only ambient portion will be set up.
• To implement good pixel lit shaders, most often you write a PixelOrNone pass that renders ambient only, a Vertex pass that renders vertex lighting + ambient, and a Pixel pass that adds illumination one light at a time. Majority of builtin shaders in Unity follow this configuration.

RequireOptions tag

A pass can indicate that it should only be rendered when some external conditions are met. This is done by using RequireOptions tag, whose value is a string of space separated options. Currently the options supported by Unity are:

• SoftVegetation: Render this pass only if Soft Vegetation is on in Quality Settings.

LightTexCount tag

When implementing pixel-lit shaders for older hardware (that does not support fragment programs), it is often required to write separate implementations for different light types because of hardware restrictions. LightTexCount indicates what combination of light attenuation types does the pass support. The tag's value is a string consisting of '0', '1' and '2' characters; meaning a pass supports zero, one or two light attenuation textures. The default value is "012" - i.e. the pass supports all attenuation combinations. See Attenuation and Pixel Lights for details. This tag is not used when writing fragment programs, as different shader implementations are generated by Unity automatically.

See Also

SubShaders can be given Tags as well, see SubShader Tags.