The OpenGL^® Shading Language, Version 4.60.8

A shader contains a static use of a variable x if, after preprocessing, the shader contains a statement that would access any part of x, whether or not flow of control will cause that statement to be executed. Such a variable is referred to as being statically used. If the access is a write then x is further said to be statically assigned.

Some operations require an expression to be dynamically uniform, or that it be located in uniform control flow. These requirements are defined by the following set of definitions.

An invocation is a single execution of main() for a particular stage, operating only on the amount of data explicitly exposed within that stage’s shaders. (Any implicit operation on additional instances of data would comprise additional invocations.) For example, in compute execution models, a single invocation operates only on a single work item, or, in a vertex execution model, a single invocation operates only on a single vertex.

An invocation group is the complete set of invocations collectively processing a particular compute workgroup or graphical operation, where the scope of a "graphical operation" is implementation-dependent, but at least as large as a single triangle or patch, and at most as large as a single rendering command, as defined by the client API.

Within a single invocation, a single shader statement can be executed multiple times, giving multiple dynamic instances of that instruction. This can happen when the instruction is executed in a loop, or in a function called from multiple call sites, or combinations of multiple of these. Different loop iterations and different dynamic function-call-site chains yield different dynamic instances of such an instruction. Dynamic instances are distinguished by their control-flow path within an invocation, not by which invocation executed it. That is, different invocations of main() execute the same dynamic instances of an instruction when they follow the same control-flow path.

An expression is dynamically uniform for a dynamic instance consuming it when its value is the same for all invocations (in the invocation group) that execute that dynamic instance.

Uniform control flow (or converged control flow) occurs when all invocations in the invocation group execute the same control-flow path (and hence the same sequence of dynamic instances of instructions). Uniform control flow is the initial state at the entry into main(), and lasts until a conditional branch takes different control paths for different invocations (non-uniform or divergent control flow). Such divergence can reconverge, with all the invocations once again executing the same control-flow path, and this re-establishes the existence of uniform control flow. If control flow is uniform upon entry into a selection or loop, and all invocations in the invocation group subsequently leave that selection or loop, then control flow reconverges to be uniform.

For example:

Other examples of non-uniform control flow can occur within loops where some invocations execute iterations that others do not, after conditional breaks, continues, early returns, and after fragment discards, when the condition is true for some fragments but not others.

Note that constant expressions are trivially dynamically uniform. It follows that typical loop counters based on these are also dynamically uniform.

Functions that do not return a value must be declared as void. There is no default function return type. The keyword void cannot be used in any other declarations (except for empty formal or actual parameter lists), or a compile-time error results.

To make conditional execution of code easier to express, the type bool is supported. There is no expectation that hardware directly supports variables of this type. It is a genuine Boolean type, holding only one of two values meaning either true or false. Two keywords true and false can be used as literal Boolean constants. Booleans are declared and optionally initialized as in the follow example:

Expressions used for conditional jumps (if, for, ?:, while, do-while) must evaluate to the type bool.

Signed and unsigned integer variables are fully supported. In this document, the term integer is meant to generally include both signed and unsigned integers.

For OpenGL, unsigned integers have exactly 32 bits of precision. When targeting Vulkan, highp unsigned integers have exactly 32 bits of precision.

For OpenGL, signed integers use 32 bits, including a sign bit, in two’s complement form. When targeting Vulkan, highp signed integers use 32 bits, including a sign bit, in two’s complement form.

When targeting Vulkan, mediump and lowp integers are as defined by the SPIR-V RelaxedPrecision decoration.

Addition, subtraction and multiplication resulting in overflow or underflow will result in the low-order 32 bits of the correct result R, where R is computed with enough precision to avoid overflow or underflow. Division resulting in overflow will result in an undefined value.

Integers are declared and optionally initialized with integer expressions, as in the following example:

Literal integer constants can be expressed in decimal (base 10), octal (base 8), or hexadecimal (base 16) as follows.

No white space is allowed between the digits of an integer constant, including after the leading 0 or after the leading 0x or 0X of a constant, or before the suffix u or U. When tokenizing, the maximal token matching the above will be recognized before a new token is started. When the suffix u or U is present, the literal has type uint, otherwise the type is int. A leading unary minus sign (-) is interpreted as an arithmetic unary negation, not as part of the constant. Hence, literals themselves are always expressed with non-negative syntax, though they could result in a negative value.

It is a compile-time error to provide a literal integer whose bit pattern cannot fit in 32 bits. The bit pattern of the literal is always used unmodified. So a signed literal whose bit pattern includes a set sign bit creates a negative value.

For example,

Single-precision and double-precision floating-point variables are available for use in a variety of scalar calculations. Generally, the term floating-point will refer to both single- and double-precision floating-point. Floating-point variables are defined as in the following examples:

As an input value to one of the processing units, a single-precision or double-precision floating-point variable is expected to match the corresponding IEEE 754 floating-point definition for precision and dynamic range. Floating-point variables within a shader are also encoded according to the IEEE 754 specification for single-precision floating-point values

(logically, not necessarily physically). While encodings are logically IEEE 754, operations (addition, multiplication, etc.) are not necessarily performed as required by IEEE 754. See “Range and Precision” for more details on precision and usage of NaNs (Not a Number) and Infs (positive or negative infinities).

Floating-point constants are defined as follows.

A decimal point (.) is not needed if the exponent part is present. No white space may appear anywhere within a floating-point constant, including before a suffix. When tokenizing, the maximal token matching the above will be recognized before a new token is started. When the suffix "lf" or "LF" is present, the literal has type double. Otherwise, the literal has type float. A leading unary minus sign (-) is interpreted as a unary operator and is not part of the floating-point constant.

The OpenGL Shading Language includes data types for generic 2-, 3-, and 4-component vectors of floating-point values, integers, and Booleans. Floating-point vector variables can be used to store colors, normals, positions, texture coordinates, texture lookup results and the like. Boolean vectors can be used for component-wise comparisons of numeric vectors. Some examples of vector declarations are:

Initialization of vectors can be done with constructors. See “Vector and Matrix Constructors”.

The OpenGL Shading Language has built-in types for 2 × 2, 2 × 3, 2 × 4, 3 × 2, 3 × 3, 3 × 4, 4 × 2, 4 × 3, and 4 × 4 matrices of floating-point numbers. Matrix types beginning with "mat" have single-precision components while matrix types beginning with "dmat" have double-precision components. The first number in the type is the number of columns, the second is the number of rows. If there is only one number, the matrix is square. Example matrix declarations:

Initialization of matrix values is done with constructors (described in “Vector and Matrix Constructors”) in column-major order.

The opaque types, as listed in the following sections, declare variables that are effectively opaque handles to other objects. These objects are accessed through built-in functions, not through direct reading or writing of the declared variable. They can only be declared as function parameters or in uniform-qualified variables (see “Uniform Variables”). The only opaque types that take memory qualifiers are the image types. Except for array indexing, structure member selection, and parentheses, opaque variables are not allowed to be operands in expressions; such use results in a compile-time error.

Opaque variables cannot be treated as l-values; hence cannot be used as out or inout function parameters, nor can they be assigned into. Any such use results in a compile-time error. However, they can be passed as in parameters with matching types and memory qualifiers. They cannot be declared with an initializer.

Because a single opaque type declaration effectively declares two objects, the opaque handle itself and the object it is a handle to, there is room for both a storage qualifier and a memory qualifier. The storage qualifier will qualify the opaque handle, while the memory qualifier will qualify the object it is a handle to.

User-defined types can be created by aggregating other already defined types into a structure using the struct keyword. For example,

In this example, light becomes the name of the new type, and lightVar becomes a variable of type light. To declare variables of the new type, use its name (without the keyword struct).

More formally, structures are declared as follows. However, the definitive grammar is as given in “Shading Language Grammar”.

where name becomes the user-defined type, and can be used to declare variables to be of this new type. The name shares the same name space as other variables, types, and functions. All previously visible variables, types, constructors, or functions with that name are hidden. The optional qualifier only applies to any declarators, and is not part of the type being defined for name.

Structures must have at least one member declaration. Bit fields are not supported. Member types must be already defined (there are no forward references).

Member declarations may contain precision qualifiers, but use of any other qualifier results in a compile-time error. Where a member declaration does not include a precision qualifier the member’s precision is inferred as described in Default Precision Qualifiers at the point of the struct type’s declaration.

A compile-time error results if a member declaration contains an initializer. Member declarators can contain arrays. Such arrays must have a size specified, and the size must be a constant integral expression that’s greater than zero (see “Constant Expressions”). Each level of structure has its own name space for names given in member declarators; such names need only be unique within that name space.

Anonymous structures are not supported. Embedded structure definitions are not supported. These result in compile-time errors.

Structures can be initialized at declaration time using constructors, as discussed in “Structure Constructors”.

Any restrictions on the usage of a type or qualifier also apply to any structure that contains a member of that type or qualifier. This also applies to structure members that are structures, recursively.

Variables of the same type can be aggregated into arrays by declaring a name followed by brackets ([ ]) enclosing an optional size. When an array size is specified in a declaration, it must be an integral constant expression (see “Constant Expressions”) greater than zero. Except for the last declared member of a shader storage block (see section “Interface Blocks”), the size of an array must be declared (explicitly sized) before it is indexed with anything other than a constant integral expression. The size of any array must be declared before passing it as an argument to a function. Violation of any of these rules result in compile-time errors. It is legal to declare an array without a size (unsized) and then later redeclare the same name as an array of the same type and specify a size, or index it only with constant integral expressions (implicitly sized). However, unless noted otherwise, blocks cannot be redeclared; an unsized array member in a user-declared block cannot be sized by a block redeclaration. It is a compile-time error to declare an array with a size, and then later (in the same shader) index the same array with a constant integral expression greater than or equal to the declared size. It is a compile-time error to redeclare an unsized array with a size equal to or smaller than any index used earlier in the shader to index the array. It is also a compile-time error to index an array with a negative constant expression. Arrays declared as formal parameters in a function declaration must specify a size. Undefined behavior results from indexing an array with a non-constant expression that’s greater than or equal to the array’s size or less than 0. Arrays only have a single dimension (a single entry within "[ ]"), however, arrays of arrays can be declared. All types (basic types, structures, arrays) can be formed into an array.

All arrays are inherently homogeneous; made of elements all having the same type and size, with one exception. The exception is a shader storage block having an unsized array as its last member (run-time sized); an array can be formed from such a shader storage block, even if the storage blocks have differing lengths for their last member.

Some examples are:

An array type can be formed by specifying non-array type followed by an array specifier. All dimensions of such an array specifier must include a size.

This type can be used anywhere any other type can be used, including as the return value from a function

as a constructor of an array:

as an unnamed parameter:

and as an alternate way of declaring a variable or function parameter:

Arrays can have initializers formed from array constructors:

An array of arrays can be declared as:

which declares a one-dimensional array of size 3 of one-dimensional arrays of size 2 of vec4. The following declarations do the same thing:

When in transparent memory (like in a uniform block), the layout is that the inner-most (right-most in declaration) dimensions iterate faster than the outer dimensions. That is, for the above, the order in memory would be:

The type of a needed for both constructors and nameless parameters is “vec4[3][2]”:

Alternatively, the initializer-list syntax can be used to initialize an array of arrays:

Unsized arrays can be explicitly sized by an initializer at declaration time:

However, it is a compile-time error to assign to an unsized array. Note, this is a rare case that initializers and assignments appear to have different semantics. For arrays of arrays, any unsized dimension is explicitly sized by the initializer:

Arrays know the number of elements they contain. This can be obtained by using the length() method:

This returns a type int. If an array has been explicitly sized, the value returned by the length() method is a constant expression. If an array has not been explicitly sized and is the last declared member of a shader storage block, the value returned will not be a constant expression and will be determined at runtime based on the size of the buffer object providing storage for the block. Such arrays are runtime sized. For runtime-sized arrays, the value returned by the length() method will be undefined if the array is contained in an array of shader storage blocks that is indexed with a non-constant expression less than zero or greater than or equal to the number of blocks in the array.

The length() method cannot be called on an array that is not runtime sized and also has not yet been explicitly sized; this results in a compile-time error.

When the length() method returns a compile-time constant, the expression the length() method is applied to cannot contain any side effects, such as writes to l-values within the expression, or function calls that themselves have side effects: only the compile-time constant length itself need be computed. Behavior and results, including any compile-time error reporting, are undefined if the expression contains other effects.

The length() method works equally well for arrays of arrays:

When the length() method returns a compile-time constant, the expression in brackets (x above) will be parsed and subjected to the rules required for array indices, but the array will not be dereferenced. Thus, behavior is well defined even if the run-time value of the expression is out of bounds, as long as the expression contains no side effects.

When the length() method returns a run-time value (not a compile-time constant), the array will be dereferenced. E.g., if x is not a compile-time constant and is out of range, an undefined value results. More generally, all involved expressions are fully evaluated and executed.

For implicitly-sized or run-time-sized arrays, only the outer-most dimension can be lacking a size. A type that includes an unknown array size cannot be formed into an array until it gets an explicit size, except for shader storage blocks where the only unsized array member is the last member of the block.

In a shader storage block, the last member may be declared without an explicit size. In this case, the effective array size is inferred at run-time from the size of the data store backing the interface block. Such run-time-sized arrays may be indexed with general integer expressions. However, it is a compile-time error to pass them as an argument to a function or index them with a negative constant expression.

In some situations, an expression and its type will be implicitly converted to a different type. The following table shows all allowed implicit conversions:

There are no implicit array or structure conversions. For example, an array of int cannot be implicitly converted to an array of float.

When an implicit conversion is done, it is the same conversion that would be done under explicit conversion, using a constructor. The explicit conversions via constructors are described in Conversion and Scalar Constructors.

When performing implicit conversion for binary operators, there may be multiple data types to which the two operands can be converted. For example, when adding an int value to a uint value, both values can be implicitly converted to uint, float, and double. In such cases, a floating-point type is chosen if either operand has a floating-point type. Otherwise, an unsigned integer type is chosen if either operand has an unsigned integer type. Otherwise, a signed integer type is chosen. If operands can be implicitly converted to multiple data types deriving from the same base data type, the type with the smallest component size is used.

The conversions in the table above are done only as indicated by other sections of this specification.

At declaration, an initial value for a variable may be provided, specified as an equals (=) followed by an initializer. The initializer is either an assignment-expression or a list of initializers enclosed in curly braces. The grammar for the initializer is:

The assignment-expression is a normal expression except that a comma (,) outside parentheses is interpreted as the end of the initializer, not as the sequence operator. As explained in more detail below, this allows creation of nested initializers: The variable type and its initializer must exactly match in terms of nesting, number of components/elements/members present at each level, and types of components/elements/members. An assignment-expression at global scope can include calls to user-defined functions.

An assignment-expression in an initializer must be either the same type as the object it initializes or be a type that can be converted to the object’s type according to “Implicit Conversions”. Since these include constructors, a composite variable can be initialized by either a constructor or an initializer list; and an element in an initializer list can be a constructor.

If an initializer is a list of initializers enclosed in curly braces, the variable being declared must be a vector, a matrix, an array, or a structure.

A list of initializers enclosed in a matching set of curly braces is applied to one composite. This may be the variable being declared or a composite contained in the variable being declared. Individual initializers from the initializer list are applied to the elements/members of the composite, in order.

If the composite has a vector type, initializers from the list are applied to the components of the vector, in order, starting with component 0. The number of initializers must match the number of components.

If the composite has a matrix type, initializers from the list must be vector initializers and are applied to the columns of the matrix, in order, starting with column 0. The number of initializers must match the number of columns.

If the composite has a structure type, initializers from the list are applied to the members of the structure, in the order declared in the structure, starting with the first member. The number of initializers must match the number of members.

Applying these rules, the following matrix declarations are equivalent:

All of the following declarations result in a compile-time error.

In all cases, the inner-most initializer (i.e., not a list of initializers enclosed in curly braces) applied to an object must have the same type as the object being initialized or be a type that can be converted to the object’s type according to “Implicit Conversions”. In the latter case, an implicit conversion will be done on the initializer before the assignment is done.

All of the following declarations result in a compile-time error.

If an initializer (of either form) is provided for an unsized array, the size of the array is determined by the number of top-level (non-nested) initializers within the initializer. All of the following declarations create arrays explicitly sized with five elements:

It is a compile-time error to have too few or too many initializers in an initializer list for the composite being initialized. That is, all elements of an array, all members of a structure, all columns of a matrix, and all components of a vector must have exactly one initializer expression present, with no unconsumed initializers.

If no qualifier is present on a global variable, then the variable has no linkage to the application or shaders running on other pipeline stages. For either global or local unqualified variables, the declaration will appear to allocate memory associated with the processor it targets. This variable will provide read/write access to this allocated memory.

Named compile-time constants or read-only variables can be declared using the const qualifier. The const qualifier can be used with any of the non-void transparent basic data types, as well as with structures and arrays of these. It is a compile-time error to write to a const variable outside of its declaration, so they must be initialized when declared. For example,

Structure members may not be qualified with const. Structure variables can be declared as const, and initialized with a structure constructor or initializer.

Initializers for const declarations at global scope must be constant expressions, as defined in “Constant Expressions”.

SPIR-V specialization constants are expressed in GLSL as const with the layout qualifier constant_id, as described in “Specialization-Constant Qualifier.”

A constant expression is one of

A constant integral expression is a constant expression that evaluates to a scalar signed or unsigned integer.

Constant expressions will be evaluated in an invariant way so as to create the same value in multiple shaders when the same constant expressions appear in those shaders. See “The Invariant Qualifier” for more details on how to create invariant expressions and “Precision Qualifiers” for detail on how expressions are evaluated.

Constant expressions respect the precise and invariant qualifiers but will be always be evaluated in an invariant way, independent of the use of such qualification, so as to create the same value in multiple shaders when the same constant expressions appear in those shaders. See “The Invariant Qualifier” and “The Precise Qualifier” for more details on how to create invariant expressions.

Constant-expressions may be evaluated by a host platform, and are therefore not required to compute the same value that the same expression would evaluate to on the shader execution target. However, the host must use the same or greater precision than the target would use. When the precision qualification cannot be determined, the expression is evaluated at highp. See “Default Precision Qualifiers”.

Specialization-constant expressions are never evaluated by the compiler front end, but instead retain the expression’s operations needed to evaluate them later on the host.

Shader input variables are declared with the in storage qualifier. They form the input interface between previous stages of the API pipeline and the declaring shader. Input variables must be declared at global scope. Values from the previous pipeline stage are copied into input variables at the beginning of shader execution. It is a compile-time error to write to a variable declared as an input.

Only the input variables that are statically read need to be written by the previous stage; it is allowed to have superfluous declarations of input variables. This is shown in the following table.

Consumption errors are based on static use only. Compilation may generate a warning, but not an error, for any dynamic use the compiler can deduce that might cause consumption of undefined values.

See “Built-In Variables” for a list of the built-in input names.

Vertex shader input variables (or attributes) receive per-vertex data. It is a compile-time error to use auxiliary storage or interpolation qualifiers on a vertex shader input. The values copied in are established by the API or through the use of the layout identifier location.

It is a compile-time error to declare a vertex shader input with, or that contains, any of the following types:

Example declarations in a vertex shader:

It is expected that graphics hardware will have a small number of fixed vector locations for passing vertex inputs. Therefore, the OpenGL Shading Language defines each non-matrix input variable as taking up one such vector location. There is an implementation-dependent limit on the number of locations that can be used, and if this is exceeded it will cause a link-time error. (Declared input variables that are not statically used do not count against this limit.) A scalar input counts the same amount against this limit as a vec4, so applications may want to consider packing groups of four unrelated float inputs together into a vector to better utilize the capabilities of the underlying hardware. A matrix input will use up multiple locations. The number of locations used will equal the number of columns in the matrix.

Tessellation control, evaluation, and geometry shader input variables get the per-vertex values written out by output variables of the same names in the previous active shader stage. For these inputs, centroid and interpolation qualifiers are allowed, but have no effect. Since tessellation control, tessellation evaluation, and geometry shaders operate on a set of vertices, each input variable (or input block, see Interface Blocks below) needs to be declared as an array. For example,

Each element of such an array corresponds to one vertex of the primitive being processed. Each array can optionally have a size declared. For geometry shaders, the array size will be set by, (or if provided must be consistent with) the input layout declaration(s) establishing the type of input primitive, as described later in “Input Layout Qualifiers”.

Some inputs and outputs are arrayed, meaning that for an interface between two shader stages either the input or output declaration requires an extra level of array indexing for the declarations to match. For example, with the interface between a vertex shader and a geometry shader, vertex shader output variables and geometry shader input variables of the same name must have matching types, except that the geometry shader will have one more array dimension than the vertex shader, to allow for vertex indexing. If such an arrayed interface variable is not declared with the necessary additional input or output array dimension, a link-time error will result. Geometry shader inputs, tessellation control shader inputs and outputs, and tessellation evaluation inputs all have an additional level of arrayness relative to other shader inputs and outputs. These inputs and outputs are known as per-vertex-arrayed inputs and outputs. Component limits for arrayed interfaces (e.g. gl_MaxTessControlInputComponents) are limits per vertex, not limits for the entire interface.

For non-arrayed interfaces (meaning array dimensionally stays the same between stages), it is a link-time error if the input variable is not declared with the same type, including array dimensionality, as the matching output variable.

The link-time type-matching rules apply to all declared input and output variables, whether or not they are used.

Additionally, tessellation evaluation shaders support per-patch input variables declared with the patch and in qualifiers. Per-patch input variables are filled with the values of per-patch output variables written by the tessellation control shader. Per-patch inputs may be declared as one-dimensional arrays, but are not indexed by vertex number. Applying the patch qualifier to inputs can only be done in tessellation evaluation shaders. As with other input variables, per-patch inputs must be declared using the same type and qualification as per-patch outputs from the previous (tessellation control) shader stage. It is a compile-time error to use patch with inputs in any other stage.

It is a compile-time error to declare a tessellation control, tessellation evaluation or geometry shader input with, or that contains, any of the following types:

Fragment shader inputs get per-fragment values, typically interpolated from a previous stage’s outputs. The auxiliary storage qualifiers centroid and sample can also be applied, as well as the interpolation qualifiers flat, noperspective, and smooth.

It is a compile-time error to declare a fragment shader input with, or that contains, any of the following types:

Fragment shader inputs that are, or contain, integral or double-precision floating-point types must be qualified with the interpolation qualifier flat.

Fragment inputs are declared as in the following examples:

The fragment shader inputs form an interface with the last active shader in the vertex processing pipeline. For this interface, the last active shader stage output variables and fragment shader input variables of the same name must match in type and qualification, with a few exceptions: The storage qualifiers must, of course, differ (one is in and one is out). Also, interpolation qualification (e.g. flat) and auxiliary qualification (e.g. centroid) may differ. These mismatches are allowed between any pair of stages. When interpolation or auxiliary qualifiers do not match, those provided in the fragment shader supersede those provided in previous stages. If any such qualifiers are completely missing in the fragment shaders, then the default is used, rather than any qualifiers that may have been declared in previous stages. That is, what matters is what is declared in the fragment shaders, not what is declared in shaders in previous stages.

When an interface between shader stages is formed using shaders from two separate program objects, it is not possible to detect mismatches between inputs and outputs when the programs are linked. When there are mismatches between inputs and outputs on such interfaces, the values passed across the interface will be partially or completely undefined.

Shaders can ensure matches across such interfaces either by using input and output layout qualifiers (sections “Input Layout Qualifiers” and “Output Layout Qualifiers”) or by using identical input and output declarations of blocks or variables. Complete rules for interface matching are found in section 7.4.1 “Shader Interface Matching” of the OpenGL Specification.

Compute shaders do not permit user-defined input variables and do not form a formal interface with any other shader stage. See “Compute Shader Special Variables” for a description of built-in compute shader input variables. All other input to a compute shader is retrieved explicitly through image loads, texture fetches, loads from uniforms or uniform buffers, or other user supplied code. Redeclaration of built-in input variables in compute shaders is not permitted.

The uniform qualifier is used to declare global variables whose values are the same across the entire primitive being processed. All uniform variables are read-only and are initialized externally either at link time or through the API. The link-time initial value is either the value of the variable’s initializer, if present, or 0 if no initializer is present. Opaque types cannot have initializers, or a compile-time error results. When targeting Vulkan, it is a compile-time error to declare uniform variables outside a block.

Example declarations are:

The uniform qualifier can be used with any of the basic data types, or when declaring a variable whose type is a structure, or an array of any of these.

There is an implementation-dependent limit on the amount of storage for uniforms that can be used for each type of shader and if this is exceeded it will cause a compile-time or link-time error. Uniform variables that are declared but not used do not count against this limit. The number of user-defined uniform variables and the number of built-in uniform variables that are used within a shader are added together to determine whether available uniform storage has been exceeded.

Uniforms in shaders all share a single global name space when linked into a program or separable program. Hence, the types, initializers, and any location specifiers of all statically used uniform variables with the same name must match across all shaders that are linked into a single program. However it is not required to repeat the initializer or location specifier in all the linked shaders. While this single uniform name space is cross stage, a uniform variable name’s scope is per stage: If a uniform variable name is declared in one stage (e.g. a vertex shader) but not in another (e.g. a fragment shader), then that name is still available in the other stage for a different use.

Shader output variables are declared with the out storage qualifier. They form the output interface between the declaring shader and the subsequent stages of the API pipeline. Output variables must be declared at global scope. During shader execution they will behave as normal unqualified global variables. Their values are copied out to the subsequent pipeline stage on shader exit. Only output variables that are read by the subsequent pipeline stage need to be written; it is allowed to have superfluous declarations of output variables.

There is not an inout storage qualifier for declaring a single variable name as both input and output to a shader. Also, a variable cannot be declared with both the in and the out qualifiers, this will result in a compile-time or link-time error. Output variables must be declared with different names than input variables. However, nesting an input or output inside an interface block with an instance name allows the same names with one referenced through a block instance name.

Vertex, tessellation evaluation, and geometry output variables output per-vertex data and are declared using the out storage qualifier. Applying patch to an output can only be done in a tessellation control shader. It is a compile-time error to use patch on outputs in any other stage.

It is a compile-time error to declare a vertex, tessellation evaluation, tessellation control, or geometry shader output with, or that contains, any of the following types:

Individual outputs are declared as in the following examples:

These can also appear in interface blocks, as described in “Interface Blocks”. Interface blocks allow simpler addition of arrays to the interface from vertex to geometry shader. They also allow a fragment shader to have the same input interface as a geometry shader for a given vertex shader.

Tessellation control shader output variables are used to output per-vertex and per-patch data. Per-vertex output variables are arrayed (see arrayed under “Input Variables”) and declared using the out qualifier without the patch qualifier. Per-patch output variables are declared using the patch and out qualifiers.

Since tessellation control shaders produce an arrayed primitive comprising multiple vertices, each per-vertex output variable (or output block, see Interface Blocks below) needs to be declared as an array. For example,

Each element of such an array corresponds to one vertex of the primitive being produced. Each array can optionally have a size declared. The array size will be set by (or if provided must be consistent with) the output layout declaration(s) establishing the number of vertices in the output patch, as described later in “Tessellation Control Outputs”.

Each tessellation control shader invocation has a corresponding output patch vertex, and may assign values to per-vertex outputs only if they belong to that corresponding vertex. If a per-vertex output variable is used as an l-value, it is a compile-time or link-time error if the expression indicating the vertex index is not the identifier gl_InvocationID.

The order of execution of a tessellation control shader invocation relative to the other invocations for the same input patch is undefined unless the built-in function barrier() is used. This provides some control over relative execution order. When a shader invocation calls barrier(), its execution pauses until all other invocations have reached the same point of execution. Output variable assignments performed by any invocation executed prior to calling barrier() will be visible to any other invocation after the call to barrier() returns.

Because tessellation control shader invocations execute in undefined order between barriers, the values of per-vertex or per-patch output variables will sometimes be undefined. Consider the beginning and end of shader execution and each call to barrier() as synchronization points. The value of an output variable will be undefined in any of the three following cases:

Fragment outputs output per-fragment data and are declared using the out storage qualifier. It is a compile-time error to use auxiliary storage qualifiers or interpolation qualifiers in a fragment shader output declaration. It is a compile-time error to declare a fragment shader output with, or that contains, any of the following types:

Fragment outputs are declared as in the following examples:

Compute shaders have no built-in output variables, do not support user-defined output variables and do not form a formal interface with any other shader stage. All outputs from a compute shader take the form of the side effects such as image stores and operations on atomic counters.

The buffer qualifier is used to declare global variables whose values are stored in the data store of a buffer object bound through the API. Buffer variables can be read and written, with the underlying storage shared among all active shader invocations. Buffer variable memory reads and writes within a single shader invocation are processed in order. However, the order of reads and writes performed in one invocation relative to those performed by another invocation is largely undefined. Buffer variables may be qualified with memory qualifiers affecting how the underlying memory is accessed, as described in “Memory Qualifiers”.

The buffer qualifier can be used to declare interface blocks (see “Interface Blocks”), which are then referred to as shader storage blocks. It is a compile-time error to declare buffer variables outside a block.

There are implementation-dependent limits on the number of shader storage blocks used for each type of shader, the combined number of shader storage blocks used for a program, and the amount of storage required by each individual shader storage block. If any of these limits are exceeded, it will cause a compile-time or link-time error.

If multiple shaders are linked together, then they will share a single global buffer variable name space. Hence, the types of all declared buffer variables with the same name must match across all shaders that are linked into a single program.

The shared qualifier is used to declare global variables that have storage shared between all work items in a compute shader workgroup. Variables declared as shared may only be used in compute shaders (see “Compute Processor”). Any other declaration of a shared variable is a compile-time error. Shared variables are implicitly coherent (see “Memory Qualifiers”).

Variables declared as shared may not have initializers and their contents are undefined at the beginning of shader execution. Any data written to shared variables will be visible to other work items (executing the same shader) within the same workgroup.

In the absence of synchronization, the order of reads and writes to the same shared variable by different invocations of a shader is not defined.

In order to achieve ordering with respect to reads and writes to shared variables, control flow barriers must be employed using the barrier() function (see “Shader Invocation Control Functions”).

There is a limit to the total size of all variables declared as shared in a single program. This limit, expressed in units of basic machine units may be determined by using the OpenGL API to query the value of MAX_COMPUTE_SHARED_MEMORY_SIZE.

Input, output, uniform, and buffer variable declarations can be grouped into named interface blocks to provide coarser granularity backing than is achievable with individual declarations. They can have an optional instance name, used in the shader to reference their members. An output block of one programmable stage is backed by a corresponding input block in the subsequent programmable stage. A uniform block is backed by the application with a buffer object. A buffer block, also known as a shader storage block, is also backed by the application with a buffer object. It is a compile-time error to have an input block in a vertex shader or an output block in a fragment shader. These uses are reserved for future use.

An interface block declaration is defined in the grammar as follows:

Each of the above elements is discussed below.

First, an example,

The above establishes a uniform block named “Transform” with four uniforms grouped inside it.

type-qualifier determines the interface of which the block will be a part and, optionally, additional qualifiers that are applied to the block. It is a compile-time error if it does not include one of the storage qualifiers in, out, uniform or buffer. It may optionally include layout qualifiers, the auxiliary storage qualifier patch, and the precise qualifier. buffer blocks may additionally include [memory qualifiers]. It is a compile-time error to include any other qualifiers.

member-list declares the variables that are to be grouped into the block. Types and declarators are the same as for other input, output, uniform, and buffer variable declarations outside blocks, with these exceptions:

Any of these would result in a compile-time error.

If no optional qualifier is used in a member-declaration, the qualification of the member includes all in, out, patch, uniform, or buffer as determined by interface-qualifier. If optional qualifiers are used, they can include interpolation qualifiers, auxiliary storage qualifiers, precision qualifiers, and storage qualifiers and they must declare an input, output, or uniform member consistent with the interface qualifier of the block: Input variables, output variables, uniform variables, and buffer members can only be in in blocks, out blocks, uniform blocks, and shader storage blocks, respectively.

Repeating the in, out, patch, uniform, or buffer interface qualifier for a member’s storage qualifier is optional. For example,

Members of uniform or buffer storage blocks are always represented in memory as highp, regardless of any precision qualifier associated with the declaration. When values are read from or written to such variables they are converted to or from the declared precision as described in Conversion Between Precisions. Operations on the values within the shader will take place using the declared precision as normal.

A shader interface is defined to be one of these:

The block name (block-name) is used to match within shader interfaces: an output block of one pipeline stage will be matched to an input block with the same name in the subsequent pipeline stage. For uniform or shader storage blocks, the application uses the block name to identify the block. Block names have no other use within a shader beyond interface matching; it is a compile-time error to use a block name at global scope for anything other than as a block name (e.g. use of a block name for a global variable name or function name is currently reserved). It is a compile-time error to use the same block name for more than one block declaration in the same shader interface (as defined above) within one shader, even if the block contents are identical.

Matched block names within a shader interface (as defined above) must match in terms of having the same number of declarations with the same sequence of types and the same sequence of member names, as well as having matching member-wise layout qualification (see next section). Matched uniform or shader storage block names (but not input or output block names) must also either all be lacking an instance name or all having an instance name, putting their members at the same scoping level. When instance names are present on matched block names, it is allowed for the instance names to differ; they need not match for the blocks to match. Furthermore, if a matching block is declared as an array, then the array sizes must also match (or follow array matching rules for the shader interface between consecutive shader stages). Any mismatch will generate a link-time error. A block name is allowed to have different definitions in different shader interfaces within the same shader, allowing, for example, an input block and output block to have the same name.

If an instance name (instance-name) is not used, the names declared inside the block are scoped at the global level and accessed as if they were declared outside the block. If an instance name (instance-name) is used, then it puts all the members inside a scope within its own name space, accessed with the field selector (.) operator (analogously to structures). For example,

Outside the shading language (i.e., in the API), members are similarly identified except the block name is always used in place of the instance name (API accesses are to shader interfaces, not to shaders). If there is no instance name, then the API does not use the block name to access a member, just the member name.

Within a shader interface, all declarations of the same global name must be for the same object and must match in type and in whether they declare a variable or member of a block with no instance name. The API also needs this name to uniquely identify an object in the shader interface. It is a link-time error if any particular shader interface contains

For blocks declared as arrays, the array index must also be included when accessing members, as in this example

For uniform or shader storage blocks declared as an array, each individual array element corresponds to a separate buffer object bind range, backing one instance of the block. As the array size indicates the number of buffer objects needed, uniform and shader storage block array declarations must specify an array size. A uniform or shader storage block array can only be indexed with a dynamically uniform integral expression, otherwise results are undefined.

When using OpenGL API entry points to identify the name of an individual block in an array of blocks, the name string may include an array index (e.g. Transform[2]). When using OpenGL API entry points to refer to offsets or other characteristics of a block member, an array index must not be specified (e.g. Transform.ModelViewMatrix).

Tessellation control, tessellation evaluation and geometry shader input blocks must be declared as arrays and follow the array declaration and linking rules for all shader inputs for the respective stages. All other input and output block arrays must specify an array size.

There are implementation-dependent limits on the number of uniform blocks and the number of shader storage blocks that can be used per stage. If either limit is exceeded, it will cause a link-time error.

Layout qualifiers specific to a particular shader language are discussed in separate sections below.

All shaders except compute shaders allow location layout qualifiers on input variable declarations, input block declarations, and input block member declarations. Of these, variables and block members (but not blocks) additionally allow the component layout qualifier.

For example,

will establish that the shader input normal is assigned to vector location number 3 and v is assigned location number 8. For vertex shader inputs, the location specifies the number of the vertex attribute from which input values are taken. For inputs of all other shader types, the location specifies a vector number that can be used to match against outputs from a previous shader stage, even if that shader is in a different program object.

The following language describes how many locations are consumed by a given type. However, geometry shader inputs, tessellation control shader inputs and outputs, and tessellation evaluation inputs all have an additional level of arrayness relative to other shader inputs and outputs. This outer array level is removed from the type before considering how many locations the type consumes.

Except when targeting Vulkan, if a vertex shader input is any scalar or vector type, it will consume a single location. If a non-vertex shader input, or any stage input when targeting Vulkan, is a scalar or vector type other than dvec3 or dvec4, it will consume a single location, while types dvec3 or dvec4 will consume two consecutive locations.

If the declared input (after potentially removing an outer array level as just described above) is an array of size n and each of the elements takes m locations, it will be assigned m * n consecutive locations starting with the location specified. For example,

will establish that the shader input colors is assigned to vector location numbers 6, 7, and 8.

If the declared input is an n × m matrix, it will be assigned multiple locations starting with the location specified. The number of locations assigned for each matrix will be the same as for an n-element array of m-component vectors. For example,

will establish that shader input transforms is assigned to vector locations 9-16, with transforms[0] being assigned to locations 9-12, and transforms[1] being assigned to locations 13-16.

If the declared input is a structure or block, its members will be assigned consecutive locations in their order of declaration, with the first member assigned the location provided in the layout qualifier. For a structure, this process applies to the entire structure. It is a compile-time error to use a location qualifier on a member of a structure. For a block, this process applies to the entire block, or until the first member is reached that has a location layout qualifier.

When a block member is declared with a location qualifier, its location comes from that qualifier; the member’s location qualifier overrides the block-level declaration. Subsequent members are again assigned consecutive locations, based on the newest location, until the next member declared with a location qualifier. The values used for locations do not have to be declared in increasing order.

If a block has no block-level location layout qualifier, it is required that either all or none of its members have a location layout qualifier, or a compile-time error results. For some blocks declared as arrays, the location can only be applied at the block level: When a block is declared as an array where additional locations are needed for each member for each block array element, it is a compile-time error to specify locations on the block members. That is, when locations would be under specified by applying them on block members, they are not allowed on block members. For arrayed interfaces (those generally having an extra level of arrayness due to interface expansion), the outer array is stripped before applying this rule.

When generating SPIR-V, all in and out qualified user-declared (non built-in) variables and blocks (or all their members) must have a shader-specified location. Otherwise, a compile-time error is generated.

The locations consumed by block and structure members are determined by applying the rules above recursively as though the structure member were declared as an input variable of the same type. For example:

The number of input locations available to a shader is limited. For vertex shaders, the limit is the advertised number of vertex attributes. For all other shaders, the limit is implementation-dependent and must be no less than one fourth of the advertised maximum input component count.

A program will fail to link if any attached shader uses a location greater than or equal to the number of supported locations, unless device-dependent optimizations are able to make the program fit within available hardware resources.

A program will fail to link if explicit location assignments leave the linker unable to find space for other variables without explicit assignments.

For the purposes of determining if a non-vertex input matches an output from a previous shader stage, the location layout qualifier (if any) must match.

If a vertex shader input variable with no location assigned in the shader text has a location specified through the OpenGL API, the API-assigned location will be used. Otherwise, such variables will be assigned a location by the linker. See section 11.1.1 “Vertex Attributes” of the OpenGL Specification for more details. A link-time error will occur if an input variable is declared in multiple shaders of the same language with conflicting locations.

The component qualifier allows the location to be more finely specified for scalars and vectors, down to the individual components within a location that are consumed. It is a compile-time error to use component without also specifying the location qualifier (order does not matter). The components within a location are 0, 1, 2, and 3. A variable or block member starting at component N will consume components N, N+1, N+2, …​ up through its size. It is a compile-time error if this sequence of components gets larger than 3. A scalar double will consume two of these components, and a dvec2 will consume all four components available within a location. A dvec3 or dvec4 can only be declared without specifying a component. A dvec3 will consume all four components of the first location and components 0 and 1 of the second location. This leaves components 2 and 3 available for other component-qualified declarations.

For example:

If the variable is an array, each element of the array, in order, is assigned to consecutive locations, but all at the same specified component within each location. For example:

That is, location 2 component 3 will hold d[0], location 3 component 3 will hold d[1], …​, up through location 7 component 3 holding d[5].

This allows packing of two arrays into the same set of locations:

If applying this to an array of arrays, all levels of arrayness are removed to get to the elements that are assigned per location to the specified component. These non-arrayed elements will fill the locations in the order specified for arrays of arrays in “Arrays”.

It is a compile-time error to apply the component qualifier to a matrix, a structure, a block, or an array containing any of these. It is a compile-time error to use component 1 or 3 as the beginning of a double or dvec2. It is a link-time error to specify different components for the same variable within a program.

Location aliasing is causing two variables or block members to have the same location number. Component aliasing is assigning the same (or overlapping) component numbers for two location aliases. (Recall if component is not used, components are assigned starting with 0.) With one exception, location aliasing is allowed only if it does not cause component aliasing; it is a compile-time or link-time error to cause component aliasing. Further, when location aliasing, the aliases sharing the location must have the same underlying numerical type and bit width (floating-point or integer, 32-bit versus 64-bit, etc.) and the same auxiliary storage and interpolation qualification. The one exception where component aliasing is permitted is when targeting OpenGL for two input variables (not block members) to a vertex shader, which are allowed to have component aliasing. This vertex-variable component aliasing is intended only to support vertex shaders where each execution path accesses at most one input per aliased component. Implementations are permitted, but not required, to generate link-time errors if they detect that every path through the vertex shader executable accesses multiple inputs aliased to any single component.

Some output layout qualifiers apply to all shader stages and some apply only to specific stages. The latter are discussed in separate sections below.

As with input layout qualifiers, all shaders except compute shaders allow location layout qualifiers on output variable declarations, output block declarations, and output block member declarations. Of these, variables and block members (but not blocks) additionally allow the component layout qualifier.

The usage and rules for applying the location qualifier and the component qualifier to blocks and structures are exactly as described in “Input Layout Qualifiers”. No component aliasing of output variables or members is allowed.

Fragment shaders allow an additional index output layout qualifier:

Each of these qualifiers may appear at most once. If index is specified, location must also be specified. If index is not specified, the value 0 is used. For example, in a fragment shader,

will establish that the fragment shader output color is assigned to fragment color 3 as the first (index zero) input to the blend equation. And,

will establish that the fragment shader output factor is assigned to fragment color 3 as the second (index one) input to the blend equation.

For fragment shader outputs, the location and index specify the color output number and index receiving the values of the output. For outputs of all other shader stages, the location specifies a vector number that can be used to match against inputs in a subsequent shader stage, even if that shader is in a different program object.

If a declared output is a scalar or vector type other than dvec3 or dvec4, it will consume a single location. Outputs of type dvec3 or dvec4 will consume two consecutive locations. Outputs of type double and dvec2 will consume only a single location, in all stages.

If the declared output is an array, it will be assigned consecutive locations starting with the location specified. For example,

will establish that colors is assigned to vector location numbers 2, 3, and 4.

If the declared output is an n × m matrix, it will be assigned multiple locations starting with the location specified. The number of locations assigned will be the same as for an n-element array of m-component vectors.

If the declared output is a structure, its members will be assigned consecutive locations in the order of declaration, with the first member assigned the location specified for the structure. The number of locations consumed by a structure member is determined by applying the rules above recursively as though the structure member were declared as an output variable of the same type.

location layout qualifiers may be used on output variables declared as structures. However, it is a compile-time error to use a location qualifier on a structure member. Location layout qualifiers may be used on output blocks and output block members.

The number of output locations available to a shader is limited. For fragment shaders, the limit is the advertised number of draw buffers.

For all other shaders, the limit is implementation-dependent and must be no less than one fourth of the advertised maximum output component count (compute shaders have no outputs). A program will fail to link if any attached shader uses a location greater than or equal to the number of supported locations, unless device-dependent optimizations are able to make the program fit within available hardware resources.

Compile-time errors may also be given if at compile time it is known the link will fail. A negative output location will result in a compile-time error. It is also a compile-time error if a fragment shader sets a layout index to less than 0 or greater than 1.

It is a compile-time or link-time error if any of the following occur:

For fragment shader outputs, locations can be assigned using either a layout qualifier or via the OpenGL API.

For all shader types, a program will fail to link if explicit location assignments leave the linker unable to find space for other variables without explicit assignments.

If an output variable with no location or index assigned in the shader text has a location specified through the OpenGL API, the API-assigned location will be used. Otherwise, such variables will be assigned a location by the linker. All such assignments will have a color index of zero. See section 15.2 “Shader Execution” of the OpenGL Specification for more details. A link-time error will occur if an output variable is declared in multiple shaders of the same language with conflicting location or index values.

For the purposes of determining if a non-fragment output matches an input from a subsequent shader stage, the location layout qualifier (if any) must match.

Layout qualifiers can be used for uniform variables and subroutine uniforms. The layout qualifier identifiers for uniform variables and subroutine uniforms are:

The location identifier can be used with default-block uniform variables and subroutine uniforms. The location specifies the location by which the API can reference the uniform and update its value. Individual elements of a uniform array are assigned consecutive locations with the first element taking location location. Default-block uniform variable declarations sharing the same location linked in the program have to match by name, type, qualifiers and arrayness. For arrays their array dimensionality and array sizes must match. For structs this rule applies recursively to all members. No two subroutine uniform variables can have the same location in the same shader stage, otherwise a compile-time or link-time error will be generated. Valid locations for default-block uniform variable locations are in the range of 0 to the implementation-defined maximum number of uniform locations minus one. Valid locations for subroutine uniforms are in the range of 0 to the implementation-defined per-stage maximum number of subroutine uniform locations minus one.

Locations can be assigned to default-block uniform arrays and structures. The first inner-most scalar, vector or matrix member or element takes the specified location and the compiler assigns the next inner-most member or element the next incremental location value. Each subsequent inner-most member or element gets incremental locations for the entire structure or array. This rule applies to nested structures and arrays and gives each inner-most scalar, vector, or matrix member a unique location. For arrays without an explicit size, the size is calculated based on its static usage. When the linker generates locations for uniforms without an explicit location, it assumes for all uniforms with an explicit location all their array elements and structure members are used and the linker will not generate a conflicting location, even if that element or member is deemed unused.

When generating SPIR-V for API’s that accept individual (default block) non-opaque uniform variables, it is a compile-time error to not include a location when declaring them.

When targeting Vulkan, the push_constant qualifier is used to declare an entire block, and represents a set of push constants, as defined by the Vulkan API. It is a compile-time error to apply this to anything other than a uniform block declaration, or when not targeting Vulkan. The values in the block will be initialized as per the Vulkan API specification. A block declared with layout(push_constant) may optionally include an instance-name. There can be only one push_constant block per stage, or a compile-time or link-time error will result. A push-constant array can only be indexed with dynamically uniform indices. Uniform blocks declared with push_constant use different resources than those without; and are accounted for separately.

Layout qualifiers can be used for subroutine functions. The layout qualifier identifiers for subroutine functions are:

Each subroutine with an index qualifier in the shader must be given a unique index, otherwise a compile- or link-time error will be generated. The indices must be in the range of 0 to the implementation defined maximum number of subroutines minus one. It is recommended, but not required, that the shader assigns a range of tightly packed index values starting from zero so that the OpenGL subroutine function enumeration API returns a non-empty name for all active indices.

Layout qualifiers can be used for uniform and shader storage blocks, but not for non-block uniform declarations. The layout qualifier identifiers (and shared keyword) for uniform and shader storage blocks are:

None of these have any semantic effect at all on the usage of the variables being declared; they only describe how data is laid out in memory. For example, matrix semantics are always column-based, as described in the rest of this specification, no matter what layout qualifiers are being used.

Uniform and shader storage block layout qualifiers can be declared for global scope, on a single uniform or shader storage block, or on a single block member declaration.

Default layouts are established at global scope for uniform blocks as:

and for shader storage blocks as:

When this is done, the previous default qualification is first inherited and then overridden as per the override rules listed below for each qualifier listed in the declaration. The result becomes the new default qualification scoped to subsequent uniform or shader storage block definitions.

The initial state of compilation when generating SPIR-V is as if the following were declared:

However, when push_constant is declared, the default layout of the buffer will be std430. There is no method to globally set this default.

The initial state of compilation when not generating SPIR-V is as if the following were declared:

Uniform and shader storage blocks can be declared with optional layout qualifiers, and so can their individual member declarations. Such block layout qualification is scoped only to the content of the block. As with global layout declarations, block layout qualification first inherits from the current default qualification and then overrides it. Similarly, individual member layout qualification is scoped just to the member declaration, and inherits from and overrides the block’s qualification.

The shared qualifier overrides only the std140, std430, and packed qualifiers; other qualifiers are inherited. The compiler/linker will ensure that multiple programs and programmable stages containing this definition will share the same memory layout for this block, as long as all arrays are declared with explicit sizes and all matrices have matching row_major and/or column_major qualifications (which may come from a declaration outside the block definition). This allows use of the same buffer to back the same block definition across different programs. It is a compile-time error to use the shared qualifier when generating SPIR-V.

The packed qualifier overrides only std140, std430, and shared; other qualifiers are inherited. When packed is used, no shareable layout is guaranteed. The compiler and linker can optimize memory use based on what variables actively get used and on other criteria. Offsets must be queried, as there is no other way of guaranteeing where (and which) variables reside within the block.

It is a link-time error to access the same packed uniform or shader storage block in multiple stages within a program. Attempts to access the same packed uniform or shader storage block across programs can result in conflicting member offsets and in undefined values being read. However, implementations may aid application management of packed blocks by using canonical layouts for packed blocks. It is a compile-time error to use the packed qualifier when generating SPIR-V.

The std140 and std430 qualifiers override only the packed, shared, std140, and std430 qualifiers; other qualifiers are inherited. The std430 qualifier is supported only for shader storage blocks; a shader using the std430 qualifier on a uniform block will result in a compile-time error, unless it is also declared with push_constant.

The layout is explicitly determined by this, as described in section 7.6.2.2 “Standard Uniform Block Layout” of the OpenGL Specification. Hence, as in shared above, the resulting layout is shareable across programs.

Layout qualifiers on member declarations cannot use the shared, packed, std140, or std430 qualifiers. These can only be used at global scope (without an object) or on a block declaration, or a compile-time error results.

The row_major and column_major qualifiers only affect the layout of matrices, including all matrices contained in structures and arrays they are applied to, to all depths of nesting. These qualifiers can be applied to other types, but will have no effect.

The row_major qualifier overrides only the column_major qualifier; other qualifiers are inherited. Elements within a matrix row will be contiguous in memory.

The column_major qualifier overrides only the row_major qualifier; other qualifiers are inherited. Elements within a matrix column will be contiguous in memory.

The binding qualifier specifies the uniform buffer binding point corresponding to the uniform or shader storage block, which will be used to obtain the values of the member variables of the block. It is a compile-time error to specify the binding qualifier for the global scope or for block member declarations. Any uniform or shader storage block declared without a binding qualifier is initially assigned to block binding point zero. After a program is linked, the binding points used for uniform and shader storage blocks declared with or without a binding qualifier can be updated by the API.

When used with OpenGL, if the binding qualifier is used with a uniform block or shader storage block instanced as an array, the first element of the array takes the specified block binding and each subsequent element takes the next consecutive binding point. For an array of arrays, each element (e.g. 6 elements for a[2][3]) gets a binding point, and they are ordered per the array of array ordering described in “Arrays.”

When targeting Vulkan, if the binding qualifier is used with a uniform block or buffer block instanced as an array, the entire array takes only the provided binding number. The next consecutive binding number is available for a different object. For an array of arrays, descriptor set array element numbers used in descriptor set accesses are ordered per the array-of-array ordering described in “Arrays.”

If the binding point for any uniform or shader storage block instance is less than zero, or greater than or equal to the corresponding implementation-dependent maximum number of buffer bindings, a compile-time error will occur. When the binding qualifier is used with a uniform or shader storage block instanced as an array of size N, all elements of the array from binding through binding + N - 1 must be within this range. It is a compile-time or link-time error to use the same binding number for more than one uniform block or for more than one buffer block.

The set qualifier is only available when targeting Vulkan. It specifies the descriptor set this object belongs to. It is a compile-time error to apply set to a standalone qualifier, to a member of a block, or when not targeting an API that supports descriptor sets. It is a compile-time error to apply set to a block qualified as push_constant. By default, any non-push-constant uniform or shader storage block declared without a set identifier is assigned to descriptor set 0. Similarly, any sampler, texture, or subpass-input type declared as a uniform without a set identifier is also assigned to descriptor set 0.

If applied to an object declared as an array, all elements of the array belong to the specified set.

When generating SPIR-V, it is a compile-time error for either the set or binding value to exceed a front-end-configuration supplied maximum value.

When multiple arguments are listed in a layout declaration, the effect will be the same as if they were declared one at a time, in order from left to right, each in turn inheriting from and overriding the result from the previous qualification.

For example

results in the qualification being column_major. Other examples:

When targeting Vulkan, the offset and align qualifiers for blocks and block members can only be used with uniform and buffer blocks. When not targeting Vulkan, they can only be used with blocks declared with std140 or std430 layouts.

The offset qualifier can only be used on block members. The offset qualifier forces the qualified member to start at or after the specified layout-qualifier-value, which will be its byte offset from the beginning of the buffer. It is a compile-time error to have any offset, explicit or assigned, that lies within another member of the block. When not generating SPIR-V, it is a compile-time error to specify an offset that is smaller than the offset of the previous member in the block. Two blocks linked together in the same program with the same block name must have the exact same set of members qualified with offset and their layout-qualifier-value values must be the same, or a link-time error results. The specified offset must be a multiple of the base alignment of the type of the block member it qualifies, or a compile-time error results.

The align qualifier makes the start of each block member have a minimum byte alignment. It does not affect the internal layout within each member, which will still follow the std140 or std430 rules. The specified alignment must be greater than 0 and a power of 2, or a compile-time error results.

The actual alignment of a member will be the greater of the specified align alignment and the standard (e.g. std140) base alignment for the member’s type. The actual offset of a member is computed as follows: If offset was declared, start with that offset, otherwise start with the offset immediately following the preceding member (in declaration order). If the resulting offset is not a multiple of the actual alignment, increase it to the first offset that is a multiple of the actual alignment. This results in the actual offset the member will have.

When align is applied to an array, it affects only the start of the array, not the array’s internal stride. Both an offset and an align qualifier can be specified on a declaration.

The align qualifier, when used on a block, has the same effect as qualifying each member with the same align value as declared on the block, and gets the same compile-time results and errors as if this had been done. As described in general earlier, an individual member can specify its own align, which overrides the block-level align, but just for that member.

Examples:

Opaque uniform variables can take the uniform layout qualifier for binding:

The binding qualifier specifies the point where the variable will be bound. Any opaque variable declared without a binding qualifier has a default binding of zero.

When used with OpenGL, if the binding qualifier is used with an array, the first element of the array takes the specified binding point and each subsequent element takes the next consecutive binding point. For an array of arrays, each element (e.g. 6 elements for a[2][3]) gets a binding point, and they are ordered per the array of array ordering described in “Arrays.”

When targeting Vulkan, if the binding qualifier is used with an array, the entire array takes only the provided binding number. The next consecutive binding number is available for a different object.

If the binding is less than zero, or greater than or equal to the implementation-dependent maximum supported number of binding points, a compile-time error will occur. When the binding qualifier is used with an array of size N, all elements of the array from binding through binding + N - 1 must be within this range. It is a compile-time or link-time error to use the same binding number for more than one atomic counter, unless the offset for the atomic counters sharing the same binding are all different.

A link-time error will result if two shaders in a program specify different layout-qualifier-value bindings for the same opaque-uniform name. However, it is not an error to specify a binding on some but not all declarations for the same name, as shown in the examples below.

Atomic counters are not available when targeting Vulkan.

Atomic counter layout qualifiers can be used on atomic counter declarations or at global scope to establish defaults. The atomic counter qualifiers are:

Each binding has a default offset that is initially 0 and is updated following each declaration containing the type atomic_uint. If such a declaration does not declare a variable then it establishes a default for the named binding. It is a compile-time error if any such declaration does not include a binding layout qualifier.

If a declaration contains an offset qualifier then that offset is used in the declaration, otherwise the default offset for the named binding is used. Each atomic counter that is declared is assigned to the named buffer binding point, at the current offset, and then the offset is increased by 4. Arrays of atomic counters assign one such offset to each member, and if multiple variables are declared in the same statement then they will have offsets assigned in order from left to right. Having assigned offsets to variables, if any, the binding’s default offset will be set to the current offset value.

For example,

will establish that the opaque handle to the atomic counter a will be bound to atomic counter buffer binding point 2 at an offset of 4 basic machine units into that buffer. The default offset for binding point 2 will be post incremented by 4 (the size of an atomic counter).

It is a compile-time error to bind an atomic counter with a binding value greater than or equal to gl_MaxAtomicCounterBindings. It is a compile-time error to declare an atomic counter whose offset is such that the buffer containing it would be larger than gl_MaxAtomicCounterBufferSize. It is a compile-time error to declare an atomic counter whose offset is not aligned to a multiple of 4. It is a compile-time error to declare an unsized array of atomic_uint. It is a compile- or link-time error to declare two atomic counters with the same binding and the same offset.

Examples of atomic declarations:

Format layout qualifiers can be used on image variable declarations (those declared with a basic type having “image” in its keyword). The format layout qualifier identifiers for image variable declarations are:

A format layout qualifier specifies the image format associated with a declared image variable. Only one format qualifier may be specified for any image variable declaration. For image variables with floating-point component types (keywords starting with “image”), signed integer component types (keywords starting with “iimage”), or unsigned integer component types (keywords starting with “uimage”), the format qualifier used must match the float-image-format-qualifier, int-image-format-qualifier, or uint-image-format-qualifier grammar rules, respectively. It is a compile-time error to declare an image variable where the format qualifier does not match the image variable type.

Any image variable used for image loads or atomic operations must specify a format layout qualifier; it is a compile-time error to pass an image uniform variable or function parameter declared without a format layout qualifier to an image load or atomic function.

Uniforms not qualified with writeonly must have a format layout qualifier. Note that an image variable passed to a function for read access cannot be declared as writeonly and hence must have been declared with a format layout qualifier.

The binding qualifier was described in “Opaque Uniform Layout Qualifiers”.

Subpass inputs are only available when targeting Vulkan.

Subpass inputs are declared with the basic subpassInput types. They must be declared with the layout qualifier input_attachment_index, or a compile-time error results. For example:

This selects which subpass input is being read from. The value assigned to input_attachment_index, say i (input_attachment_index = i), selects that entry (i th entry) in the input list for the pass. See the API documentation for more detail about passes and the input list.

If an array of size N is declared, it consumes N consecutive input_attachment_index values, starting with the one provided.

It is a compile-time or link-time error to have different variables declared with the same input_attachment_index. This includes any overlap in the implicit input_attachment_index consumed by array declarations.

It is a compile-time error if the value assigned to an input_attachment_index is greater than or equal to gl_MaxInputAttachments.

The following predeclared variables can be redeclared with an interpolation qualifier when using the compatibility profile:

Vertex, tessellation control, tessellation evaluation, and geometry languages:

Fragment language:

For example,

Ideally, these are redeclared as part of the redeclaration of an interface block, as described in “Compatibility Profile Built-In Language Variables”. However, for the above purpose, they can be redeclared as individual variables at global scope, outside an interface block. Such redeclarations also allow adding the transform-feedback qualifiers xfb_buffer, xfb_stride, and xfb_offset to output variables. (Using xfb_buffer on a variable does not change the global default buffer.) A compile-time error will result if a shader has both an interface block redeclaration and a separate redeclaration of a member of that interface block outside the interface block redeclaration.

If gl_Color is redeclared with an interpolation qualifier, then gl_FrontColor and gl_BackColor (if they are written to) must also be redeclared with the same interpolation qualifier, and vice versa. If gl_SecondaryColor is redeclared with an interpolation qualifier, then gl_FrontSecondaryColor and _gl_BackSecondaryColor _(if they are written to) must also be redeclared with the same interpolation qualifier, and vice versa. This qualifier matching on predeclared variables is only required for variables that are statically used within the shaders in a program.

The precision of highp single- and double-precision floating-point variables is defined by the IEEE 754 standard for 32-bit and 64-bit floating-point numbers.

This includes support for NaNs (Not a Number) and Infs (positive or negative infinities) and positive and negative zeros.

The following rules apply to highp for both single and double-precision operations: Signed infinities and zeros are generated as dictated by IEEE, but subject to the precisions allowed in the following table. Any subnormal (denormalized) value input into a shader or potentially generated by any operation in a shader can be flushed to 0. The rounding mode cannot be set and is undefined but must not affect the result by more than 1 ULP. NaNs are not required to be generated. Support for signaling NaNs is not required and exceptions are never raised. Operations including built-in functions that operate on a NaN are not required to return a NaN as the result. However if NaNs are generated, isnan() must return the correct value.

Precisions are expressed in terms of maximum relative error in units of ULP (units in the last place), unless otherwise noted.

For single precision operations, precisions are required as follows:

Built-in functions defined in the specification with an equation built from the above operations inherit the above errors. These include, for example, the geometric functions, the common functions, and many of the matrix functions. Built-in functions not listed above and not defined as equations of the above have undefined precision. These include, for example, the trigonometric functions and determinant.

The precision of double-precision operations is at least that of single precision.

Within the same type, conversion from a lower to a higher precision must be exact. When converting from a higher precision to a lower precision, if the value is representable by the implementation of the target precision, the conversion must also be exact. If the value is not representable, the behavior is dependent on the type:

Any single-precision floating-point, integer, or opaque-type declaration can have the type preceded by one of these precision qualifiers:

For example:

Literal constants do not have precision qualifiers. Neither do Boolean variables.

For this paragraph, “operation” includes operators, built-in functions, and constructors, and “operand” includes function arguments and constructor arguments. The precision qualification associated with any operation is the highest precision qualification of the operands consumed by the operation, if any operand has an associated precision. In cases where no operand has a precision qualifier, the precision qualifications of the operands of the next consuming operation in the expression will be used. This rule can be applied recursively until a precision qualified operand is found. If necessary, it will also include the precision qualification of l-values for assignments, of the declared variable for initializers, of formal parameters for function call arguments, or of function return types for function return values. If the precision cannot be determined by this method e.g. if an entire expression is composed only of operands with no precision qualifier, and the result is not assigned or passed as an argument, then it is evaluated at the default precision of the type or greater. When this occurs in the fragment shader, the default precision must be defined.

For example, consider the statements:

Precision qualifiers, as with other qualifiers, do not affect the basic type of the variable. In particular, there are no constructors for precision conversions; constructors only convert types. Similarly, precision qualifiers, as with other qualifiers, do not contribute to function overloading based on parameter types. As discussed in “Function Calling Conventions”, function input and output is done through copies, and therefore qualifiers do not have to match.

The precision of a variable is determined when the variable is declared and cannot be subsequently changed.

Where the precision of a constant integral or constant floating-point expression is not specified, evaluation is performed at highp. This rule does not affect the precision qualification of the expression.

The evaluation of constant expressions must be invariant and will usually be performed at compile time.

The precision statement

can be used to establish a default precision qualifier. The type field can be either int, float, or any of the opaque types, and the precision-qualifier can be lowp, mediump, or highp.

Any other types or qualifiers will result in a compile-time error. If type is float, the directive applies to non-precision-qualified single-precision floating-point type (scalar, vector, and matrix) declarations. If type is int, the directive applies to all non-precision-qualified integer type (scalar, vector, signed, and unsigned) declarations. This includes global variable declarations, function return declarations, function parameter declarations, and local variable declarations.

Non-precision qualified declarations will use the precision qualifier specified in the most recent precision statement that is still in scope. The precision statement has the same scoping rules as variable declarations. If it is declared inside a compound statement, its effect stops at the end of the inner-most statement it was declared in. Precision statements in nested scopes override precision statements in outer scopes. Multiple precision statements for the same basic type can appear inside the same scope, with later statements overriding earlier statements within that scope.

For any type that accepts a precision qualifier, the default precision qualification will be highp. Because all types requiring a precision qualifier have a default precision, there are no errors for omission of a precision qualifier.

The built-in macro GL_FRAGMENT_PRECISION_HIGH is defined to one:

This macro is available in all languages except compute.

To ensure that a particular output variable is invariant, it is necessary to use the invariant qualifier. It can either be used to qualify a previously declared variable as being invariant:

or as part of a declaration when a variable is declared:

Only variables output from a shader can be candidates for invariance. This includes user-defined output variables and the built-in output variables. As only outputs can be declared as invariant, an output from one shader stage will still match an input of a subsequent stage without the input being declared as invariant.

Input or output instance names on blocks are not used when redeclaring built-in variables.

The invariant keyword can be followed by a comma separated list of previously declared identifiers. All uses of invariant must be at global scope or on block members, and before any use of the variables being declared as invariant.

To guarantee invariance of a particular output variable across two programs, the following must also be true:

Essentially, all the data flow and control flow leading to an invariant output must match.

Initially, by default, all output variables are allowed to be variant. To force all output variables to be invariant, use the pragma

before all declarations in a shader. If this pragma is used after the declaration of any variables or functions, then the set of outputs that behave as invariant is undefined.

Generally, invariance is ensured at the cost of flexibility in optimization, so performance can be degraded by use of invariance. Hence, use of this pragma is intended as a debug aid, to avoid individually declaring all output variables as invariant.

Invariance must be guaranteed for constant expressions. A particular constant expression must evaluate to the same result if it appears again in the same shader or a different shader. This includes the same expression appearing in two shaders of the same language or shaders of two different languages.

Constant expressions must evaluate to the same result when operated on as already described above for invariant variables.