Accessing shader properties in Cg/HLSL

Shader declares Material properties in a PropertiesA generic term for the editable fields, buttons, checkboxes, or menus that comprise a component. An editable property is also referred to as a field. More info
See in Glossary block. If you want to access some of those properties in a shader program, you need to declare a Cg/HLSL variable with the same name and a matching type. An example is provided in Shader Tutorial: Vertex and Fragment Programs.

For example these shaderA small script that contains the mathematical calculations and algorithms for calculating the Color of each pixel rendered, based on the lighting input and the Material configuration. More info
See in Glossary properties:

_MyColor ("Some Color", Color) = (1,1,1,1) 
_MyVector ("Some Vector", Vector) = (0,0,0,0) 
_MyFloat ("My float", Float) = 0.5 
_MyTexture ("Texture", 2D) = "white" {} 
_MyCubemap ("Cubemap", CUBE) = "" {} 

would be declared for access in Cg/HLSL code as:

fixed4 _MyColor; // low precision type is usually enough for colors
float4 _MyVector;
float _MyFloat; 
sampler2D _MyTexture;
samplerCUBE _MyCubemap;

Cg/HLSL can also accept uniform keyword, but it is not necessary:

uniform float4 _MyColor;

Property types in ShaderLabUnity’s declarative language for writing shaders. More info
See in Glossary map to Cg/HLSL variable types this way:

• Color and Vector properties map to float4, half4 or fixed4 variables.
• Range and Float properties map to float, half or fixed variables.
• Texture properties map to sampler2D variables for regular (2D) textures; CubemapsA collection of six square textures that can represent the reflections in an environment or the skybox drawn behind your geometry. The six squares form the faces of an imaginary cube that surrounds an object; each face represents the view along the directions of the world axes (up, down, left, right, forward and back). More info
  See in Glossary map to samplerCUBE; and 3D textures map to sampler3D.

How property values are provided to shaders

Shader property values are found and provided to shaders from these places:

• Per-Renderer values set in MaterialPropertyBlock. This is typically “per-instance” data (e.g. customized tint color for a lot of objects that all share the same material).
• Values set in the MaterialAn asset that defines how a surface should be rendered, by including references to the Textures it uses, tiling information, Color tints and more. The available options for a Material depend on which Shader the Material is using. More info
  See in Glossary that’s used on the rendered object.
• Global shader properties, set either by Unity renderingThe process of drawing graphics to the screen (or to a render texture). By default, the main camera in Unity renders its view to the screen. More info
  See in Glossary code itself (see built-in shader variables), or from your own scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
  See in Glossary (e.g. Shader.SetGlobalTexture).

The order of precedence is like above: per-instance data overrides everything; then Material data is used; and finally if shader property does not exist in these two places then global property value is used. Finally, if there’s no shader property value defined anywhere, then “default” (zero for floats, black for colors, empty white texture for textures) value will be provided.

Serialized and Runtime Material properties

Materials can contain both serialized and runtime-set property values.

Serialized data is all the properties defined in shader’s Properties block. Typically these are values that need to be stored in the material, and are tweakable by the user in Material InspectorA Unity window that displays information about the currently selected GameObject, Asset or Project Settings, allowing you to inspect and edit the values. More info
See in Glossary.

A material can also have some properties that are used by the shader, but not declared in shader’s Properties block. Typically this is for properties that are set from script code at runtime, e.g. via Material.SetColor. Note that matrices and arrays can only exist as non-serialized runtime properties (since there’s no way to define them in Properties block).

Special Texture properties

For each texture that is setup as a shader/material property, Unity also sets up some extra information in additional vector properties.

Texture tiling & offset

Materials often have Tiling and Offset fields for their texture properties. This information is passed into shaders in a float4 {TextureName}_ST property:

• x contains X tiling value
• y contains Y tiling value
• z contains X offset value
• w contains Y offset value

For example, if a shader contains texture named _MainTex, the tiling information will be in a _MainTex_ST vector.

Texture size

{TextureName}_TexelSize - a float4 property contains texture size information:

• x contains 1.0/width
• y contains 1.0/height
• z contains width
• w contains height

Texture HDR parameters

{TextureName}_HDR - a float4 property with information on how to decode a potentially HDRhigh dynamic range
See in Glossary (e.g. RGBM-encoded) texture depending on the color space used. See DecodeHDR function in UnityCG.cginc shader include file.

Color spaces and color/vector shader data

When using Linear color space, all material color properties are supplied as sRGB colors, but are converted into linear values when passed into shaders.

For example, if your Properties shader block contains a Color property called “MyColor“, then the corresponding ”MyColor” HLSL variable will get the linear color value.

For properties that are marked as Float or Vector type, no color space conversions are done by default; it is assumed that they contain non-color data. It is possible to add [Gamma] attribute for float/vector properties to indicate that they are specified in sRGB space, just like colors (see Properties).

See Also

• ShaderLab Properties block.
• Writing Shader Programs.