Variable Syntax (DirectX HLSL)

Use the following syntax rules to declare HLSL variables.

[Storage_Class] [Type_Modifier] Type Name[Index]     [: Semantic]     [Annotations]     [= Initial_Value]     [: Packoffset]     [: Register];

Parameters

Storage_Class

Optional storage-class modifiers that give the compiler hints about variable scope and lifetime; the modifiers can be specified in any order.

Value	Description
extern	Mark a global variable as an external input to the shader; this is the default marking for all global variables. Cannot be combined with static.
nointerpolation	Do not interpolate the outputs of a vertex shader before passing them to a pixel shader.
shared	Mark a variable for sharing between effects; this is a hint to the compiler.
static	Mark a local variable so that it is initialized one time and persists between function calls. If the declaration does not include an initializer, the value is set to zero. A global variable marked static is not visible to an application.
uniform	Mark a variable whose data is constant throughout the execution of a shader (such as a material color in a vertex shader); global variables are considered uniform by default.
volatile	Mark a variable that changes frequently; this is a hint to the compiler. This storage class only applies to a local variable.

Type_Modifier

Optional variable-type modifier.

Value	Description
const	Mark a variable that cannot be changed by a shader, therefore, it must be initialized in the variable declaration. Global variables are considered const by default (suppress this behavior by supplying the /Gec flag to the compiler).
row_major	Mark a variable that stores four components in a single row so they can be stored in a single constant register.
column_major	Mark a variable that stores 4 components in a single column to optimize matrix math.

Type

Any HLSL type listed in Data Types (DirectX HLSL).

Name[Index]

ASCII string that uniquely identifies a shader variable. To define an optional array, use index for the array size, which is a positive integer ≥ 1.

Semantic

Optional parameter-usage information, used by the compiler to link shader inputs and outputs. There are several predefined semantics for vertex and pixel shaders. The compiler ignores semantics unless they are declared on a global variable, or a parameter passed into a shader.

Annotation(s)

Optional metadata, in the form of a string, attached to a global variable. An annotation is used by the effect framework and ignored by HLSL; to see more detailed syntax, see annotation syntax.

Initial_Value

Optional initial value(s); the number of values should match the number of components in Type. Each global variable marked extern must be initialized with a literal value; each variable marked static must be initialized with a constant.

Global variables—that are not marked static or extern—are not compiled into the shader and cannot be optimized. To initialize this type of global variable, use reflection to get their value and then set the value in a shader using a constant buffer.

Packoffset

Optional keyword for manually packing shader constants. See packoffset (DirectX HLSL).

Register

Optional keyword for manually assigning a shader variable to a particular register. See register (DirectX HLSL).

Examples

Here are several examples of shader-variable declarations.

float fVar;

float4 color;
float fVar = 3.1f;

int iVar[3];

int iVar[3] = {1,2,3};

uniform float4 position : SV_POSITION; 
const float4 lightDirection = {0,0,1};

Packing

Pack subcomponents of vectors and scalars whose size is large enough to prevent crossing register boundarys. For example, these are all valid:

cbuffer MyBuffer
{
    float4 Element1 : packoffset(c0);
    float1 Element2 : packoffset(c1);
    float1 Element3 : packoffset(c1.y);
}

Cannot mix packing types.

Like the register keyword, a packoffset can be target specific. Subcomponent packing is only available with the packoffset keyword, not the register keyword. Inside a cbuffer declaration, the register keyword is ignored for Direct3D 10 targets as it is assumed to be for cross-platform compatability.

Packed elements may overlap and the compiler will give no error or warning. In this example, Element2 and Element3 will overlap with Element1.x and Element1.y.

cbuffer MyBuffer
{
    float4 Element1 : packoffset(c0);
    float1 Element2 : packoffset(c0);
    float1 Element3 : packoffset(c0.y);
}

A sample that uses packoffset is: HLSLWithoutFX10 Sample.

See Also

Variables (DirectX HLSL)