The OpenGL ES^® Shading Language, Version 3.20.8

There are no changes between revision 7 and revision 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 an 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.

highp unsigned integers have exactly 32 bits of precision.

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. Otherwise, mediump and lowp integers have implementation-defined numbers of bits. See “Range and Precision” for details.

For all precisions, addition, subtraction and multiplication resulting in overflow or underflow will result in the low-order n bits of the correct result R, where n is the size in bits of the integer and 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 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 an 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,

Floats are available for use in a variety of scalar calculations. Floating-point variables are defined as in the following example:

As an input value to one of the processing units, a floating-point variable is expected to match the IEEE 754 single precision floating-point definition for precision and dynamic range. highp floating-point variables within a shader are 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. A leading unary minus sign (-) is interpreted as a unary operator and is not part of the floating-point constant.

There is no limit on the number of digits in any digit-sequence. If the value of the floating-point number is too large (small) to be stored as a single precision value, it is converted to positive (negative) infinity. A value with a magnitude too small to be represented as a mantissa and exponent is converted to zero. Implementations may also convert subnormal (denormalized) numbers to zero.

The OpenGL ES 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 ES 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. 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.

mat2 is an alias for mat2x2, not a distinct type. Similarly for mat3 and mat4. The following is legal:

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.

When aggregated into arrays within a shader, opaque types can only be indexed with a dynamically uniform integral expression (see “Dynamically Uniform Expressions”) unless otherwise noted; otherwise, results are undefined.

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 an 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.

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.

Structures can contain variables of any type except:

Variables of the same type can be aggregated into arrays by declaring a name followed by brackets ([ ]) enclosing an optional size.

When present, the array size must be a constant integral expression (see “Constant Expressions”) greater than zero. The type of the size parameter can be a signed or unsigned integer and the choice of type does not affect the type of the resulting array. Arrays only have a single dimension (a single number within “[ ]”), however, arrays of arrays can be declared. Any type can be formed into an array.

Arrays are sized either at compile-time or at run-time. To size an array at compile-time, either the size must be specified within the brackets as above or must be inferred from the type of the initializer.

If an array is declared as the last member of a shader storage block and the size is not specified at compile-time, it is sized at run-time. In all other cases, arrays are sized only at compile-time. An array declaration sized at compile-time which leaves the size of the array unspecified is an error.

For compile-time sized arrays, it is illegal to index an array with a constant integral expression greater than or equal to the declared size or with a negative constant expression. Arrays declared as formal parameters in a function declaration must also 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. If robust buffer access is enabled (see section 10.3.5 “Robust Buffer Access” of the OpenGL ES Specification), such indexing must not result in abnormal program termination. The results are still undefined, but implementations are encouraged to produce zero values for such accesses.

Some examples are:

When the length() method will return a compile-time constant, the expression in brackets (x above) will be evaluated and subject 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.

An array type can be formed by specifying a non-array type ([type_specifier_nonarray]) followed by an [array_specifier].

Note that the construct type [size] does not always result in an array of length size of type type:

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:

An array type can also be formed without specifying a size if the definition includes an initializer:

Note that the initializer itself does not need to be a constant expression but the length of the initializer will be a constant expression.

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 last member of a shader storage block (see “Buffer Variables”), may be declared without specifying a size. For such arrays, the effective array size is inferred at run-time from the size of the data store backing the shader storage block. Such runtime-sized arrays may be indexed with general integer expressions, but may not be passed as an argument to a function or indexed with a negative constant expression.

However, it is a compile-time error to assign to a runtime-sized array. Assignments to individual elements of the array is allowed.

Arrays have a fixed number of elements. This can be obtained by using the length() method:

The return value is a signed integral expression. For compile-time sized arrays, the value returned by the length method is a constant expression. For run-time sized arrays , the value returned will not be constant expression and will be determined at run time based on the size of the buffer object providing storage for the block.

The precision is determined using the same rules as for other cases where there is no intrinsic precision. See “Precision Qualifiers”.

Any restrictions on the usage of a type also apply to arrays of that type. This applies recursively.

The term scope refers to a specified region of the program where names are guaranteed to be visible. For example, a compound_statement_with_scope ('{' statement statement …​ '}') defines a scope.

A nested scope is a scope defined within an outer scope.

The terms 'same scope' and 'current scope' are equivalent to the term 'scope' but used to emphasize that nested scopes are excluded.

The scope of a declaration is the region or regions of the program where that declaration is visible.

A name space defines where names may be defined. Within a single name space, a name has at most one entry, specifying it to be one of: structure, variable, or function.

In general, each scope has an associated name space. However, in certain cases e.g. for uniforms, multiple scopes share the same name space. In these cases, conflicting declarations are an error, even though the name is only visible in the scopes where it is declared.

The scope of a variable is determined by where it is declared. If it is declared outside all function definitions, it has global scope, which starts from where it is declared and persists to the end of the shader it is declared in. If it is declared in a while test or a for statement, then it is scoped to the end of the following sub-statement (specified as statement-no-new-scope in the grammar). Otherwise, if it is declared as a statement within a compound statement, it is scoped to the end of that compound statement. If it is declared as a parameter in a function definition, it is scoped until the end of that function definition. A function’s parameter declarations and body together form a single scope.

For both for and while loops, the sub-statement itself does not introduce a new scope for variable names, so the following has a redeclaration compile-time error:

The body of a do-while loop introduces a new scope lasting only between the do and while (not including the while test expression), whether or not the body is simple or compound:

The statement following a switch (…​) forms a nested scope.

Representing the if construct as:

if if-expression then if-statement else else-statement,

a variable declared in the if-statement is scoped to the end of the if-statement. A variable declared in the else-statement is scoped to the end of the else-statement. This applies both when these statements are simple statements and when they are compound statements. The if-expression does not allow new variables to be declared, hence does not form a new scope.

Within a declaration, the scope of a name starts immediately after the initializer if present or immediately after the name being declared if not. Several examples:

A structure name declaration is visible at the end of the struct_specifier in which it was declared:

All variable names, structure type names, and function names in a given scope share the same name space. Function names can be redeclared in the same scope, with the same or different parameters, without error. Otherwise, within a shader, a declared name cannot be redeclared in the same scope; doing so results in a redeclaration error. If a nested scope redeclares a name used in an outer scope, it hides all existing uses of that name. There is no way to access the hidden name or make it unhidden, without exiting the scope that hid it.

Names of built-in functions cannot be redeclared as functions. Therefore overloading or redefining built-in functions is an error.

A declaration is considered to be a statement that adds a name or signature to the symbol table. A definition is a statement that fully defines that name or signature. E.g.

The determination of equivalence of two declarations depends on the type of declaration. For functions, the whole function signature must be considered (see “Function Definitions”). For variables (including arrays) and structures only the names must match.

Within each scope, a name may be declared either as a variable declaration or as function declarations or as a structure.

Examples of combinations that are allowed:

1.

2.

Examples of combinations that are disallowed:

1.

2.

3.

4.

5.

The built-in functions are scoped in the global scope users declare global variables in. That is, a shader’s global scope, available for user-defined functions and global variables, is the same as the scope containing the built-in functions. Function declarations (prototypes) cannot occur inside of functions; they must be at global scope. Hence it is not possible to hide a name with a function.

Shared globals are variables that can be accessed by multiple compilation units. In GLSL ES the only shared globals are uniforms. Vertex shader outputs are not considered to be shared globals since they must pass through the rasterization stage before they are used as input by the fragment shader.

Shared globals share the same name space, and must be declared with the same type and precision. They will share the same storage. Shared global arrays must have the same base type and the same explicit size. Scalars must have exactly the same precision, type name and type definition. Structures must have the same name, sequence of type names, and type definitions, and member names to be considered the same type. This rule applies recursively for nested or embedded types.

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 can be declared using the const qualifier. Any variables qualified as constant are read-only variables for that shader. Declaring variables as constant allows more descriptive shaders than using hard-wired numerical constants. 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 an 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.

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

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

A constant expression is one of

Function calls to user-defined functions (non-built-in functions) cannot be used to form constant expressions.

Scalar, vector, matrix, array and structure variables are constant expressions if qualified as const. Opaque types cannot be constant expressions.

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 an error to write to a variable declared as an input.

Only the input variables that are actually read need to be written by the previous stage; it is allowed to have superfluous declarations of input variables.

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 an 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 ES 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.

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 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, auxiliary qualification (e.g. centroid) may differ. When 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, attempting to use the two programs in the same program pipeline will result in program pipeline validation failures, as described in section 7.4.1 “Shader Interface Matching” of the OpenGL ES Specification.

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 ES 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.

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. Except for variables declared within a uniform block, all uniform variables are initialized to 0 at link time and may be updated through the API. When targeting Vulkan, it is an 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 statically 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, precisions, 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 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.

A compile or link-time error is generated if any of the explicitly given or compiler generated uniform locations is greater than the implementation-defined maximum number of uniform locations minus one.

Unlike locations for inputs and outputs, uniform locations are logical values, not register locations, and there is no concept of overlap. For example:

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:

Vertex shader outputs may be qualified with the interpolation qualifier flat¹.

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 an 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 shader outputs declared as arrays may only be indexed by a constant integral expression.

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.

Precision qualifiers for such variables need not match.

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 an 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 ES 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:

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 an 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 as defined in “Matching of Qualifiers”. 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. All indices used to index a shader storage block array must be constant integral expressions. A uniform block array can only be indexed with a dynamically uniform integral expression, otherwise results are undefined.

When using OpenGL ES 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 ES 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). See section 7.3.1 “Program Interfaces” of the OpenGL ES Specification for details.

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.

For example,

will establish that the shader input normal is assigned to vector location number 3. 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.

If a shader input is any scalar or vector type, it will consume a single location.

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.

If an input is declared as an array of blocks, excluding per-vertex-arrays as required for tessellation, it is an error to declare a member of the block with a location qualifier.

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 ES 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 ES Specification for more details.

It is an error if more than one input or element of a matrix input is bound to the same location.

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.

The usage and rules for applying the location qualifier to blocks and structures are exactly as described in “Input Layout Qualifiers”.

The qualifier may appear at most once within a declaration. For example, in a fragment shader,

will establish that the fragment shader output color is assigned to fragment color 3.

For fragment shader outputs, the location specifies the color output number 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.

Declared outputs of scalar or vector type consume a single location.

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.

If an output is declared as an array of blocks, excluding per-vertex-arrays as required for tessellation, it is an error to declare a member of the block with a location qualifier.

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 an error.

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

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 has no location assigned in the shader text, it will be assigned a location by the linker. See section 11.1.3 “Shader Execution” of the OpenGL ES Specification for more details.

If there is only a single output, the location does not need to be specified, in which case it defaults to zero. This applies for all output types, including arrays. If there is more than one fragment output, the location must be specified for all outputs.

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.

The following layout qualifier can be used for all default-block uniform variables but not for variables in uniform or shader storage blocks. The layout qualifier identifier for uniform variables is:

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. 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.

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. 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 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 an 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 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 they also matched in their row_major and/or column_major qualifications. 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 an 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 ES 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 an 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 (but not shader storage) blocks declared with or without a binding qualifier can be updated by the API.

When used with OpenGL ES, 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.

The set qualifier is only available when targeting Vulkan. It specifies the descriptor set this object belongs to. It is an 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 an 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 an 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 cannot be used with blocks or block members.

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. 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 ES, 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.

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- 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 an error to declare an image variable where the format qualifier does not match the image variable type.

Any image variable must specify 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 an 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 an error if the value assigned to an input_attachment_index is greater than or equal to gl_MaxInputAttachments.

The precision of highp floating-point variables is defined by the IEEE 754 standard for 32-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 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.

Storage requirements are declared through use of precision qualifiers. The precision of operations must preserve the storage precisions of the variables involved.

highp floating-point values are stored in IEEE 754 single precision floating-point format. mediump and lowp floating-point values have minimum range and precision requirements as detailed below and have maximum range and precision as defined by IEEE 754.

All integral types are assumed to be implemented as integers and so may not be emulated by floating-point values. highp signed integers are represented as twos-complement 32-bit signed integers. highp unsigned integers are represented as unsigned 32-bit integers. mediump integers (signed and unsigned) must be represented as an integer with between 16 and 32 bits inclusive. lowp integers (signed and unsigned) must be represented as an integer with between 9 and 32 bits inclusive.

The required ranges and precisions for precision qualifiers are:

The semi-open interval notation used for the magnitude ranges means that the lower end of the interval is included, but the upper end is excluded. Thus the largest required magnitude is half of the relative precision less than the value given. The largest required value for highp, for example, is 2¹²⁸ × (1 - 2^-24).

Relative precision is defined as the worst case (i.e. largest) ratio of the smallest step in relation to the value for all non-zero values in the required ranges, above:

It is therefore twice the maximum rounding error when converting from a real number. Subnormal numbers may be supported and may have lower relative precision.

In addition, the range and precision of a mediump floating-point value must be the same as or greater than the range and precision of a lowp floating-point value. The range and precision of a highp floating-point value must be the same as or greater than the range and precision of a mediump floating-point value.

The range of a mediump integer value must be the same as or greater than the range of a lowp integer value. The range of a highp integer value must be the same as or greater than the range of a mediump integer value.

The actual ranges and precisions provided by an implementation can be queried through the API. See the normative references for details on how to do this.

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 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.

Precision qualifiers for outputs in one shader matched to inputs in another shader need not match when both shaders are linked into the same program. When both shaders are in separate programs, mismatched precision qualifiers will result in a program interface mismatch that will result in program pipeline validation failures, as described in section 7.4.1 “Shader Interface Matching” of the OpenGL ES Specification.

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 an error. If type is float, the directive applies to non-precision-qualified 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.

All languages except for the fragment language have the following predeclared globally scoped default precision statements:

The fragment language has the following predeclared globally scoped default precision statements:

The fragment language has no default precision qualifier for floating-point types. Hence for float, floating-point vector and matrix variable declarations, either the declaration must include a precision qualifier or the default float precision must have been previously declared. Similarly, there is no default precision qualifier in any of the languages for any type not listed above.

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.

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.

When a value is stored in a variable, it is usually assumed it will remain constant unless explicitly changed. However, during the process of optimization, it is possible that the compiler may choose to recompute a value rather than store it in a register. Since the precision of operations is not completely specified (e.g. a low precision operation may be done at medium or high precision), it would be possible for the recomputed value to be different from the original value.

Values are allowed to be variant within a shader. To prevent this, the invariant qualifier or invariant pragma must be used.

Within a shader, there is no invariance for values generated by different non-constant expressions, even if those expressions are identical.

Example 1:

To enforce invariance in this example use:

Example 2:

There is no mechanism to enforce invariance between a and b.

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. Constant expressions are not invariant with respect to equivalent non-constant expressions, even when the invariant qualifier or pragma is used.

Undefined values are not invariant nor can they be made invariant by use of the invariant qualifier or pragma. In some implementations, undefined values may cause unexpected behavior if they are used in control-flow expressions e.g. in the following case, one, both or neither functions may be executed and this may not be consistent over multiple invocations of the shader:

Note that an undefined value is a value that has not been specified. A value that has been specified but has a potentially large error due to, for example, lack of precision in an expression, is not undefined and so can be made invariant.

Converting between scalar types is done as the following prototypes indicate:

When constructors are used to convert a floating-point type to an integer type, the fractional part of the floating-point value is dropped. It is undefined to convert a negative floating-point value to an uint.

Integer values having more bits of precision than a single-precision floating-point mantissa will lose precision when converted to float.

When a constructor is used to convert any integer or floating-point type to a bool, 0 and 0.0 are converted to false, and non-zero values are converted to true. When a constructor is used to convert a bool to any integer or floating-point type, false is converted to 0 or 0.0, and true is converted to 1 or 1.0.

The constructor int(uint) preserves the bit pattern in the argument, which will change the argument’s value if its sign bit is set. The constructor uint(int) preserves the bit pattern in the argument, which will change its value if it is negative.

Identity constructors, like float(float) are also legal, but of little use.

Scalar constructors with non-scalar parameters can be used to take the first element from a non-scalar. For example, the constructor float(vec3) will select the first component of the vec3 parameter.

Constructors can be used to create vectors or matrices from a set of scalars, vectors, or matrices. This includes the ability to shorten vectors.

If there is a single scalar parameter to a vector constructor, it is used to initialize all components of the constructed vector to that scalar’s value. If there is a single scalar parameter to a matrix constructor, it is used to initialize all the components on the matrix’s diagonal, with the remaining components initialized to 0.0.

If a vector is constructed from multiple scalars, one or more vectors, or one or more matrices, or a mixture of these, the vector’s components will be constructed in order from the components of the arguments. The arguments will be consumed left to right, and each argument will have all its components consumed, in order, before any components from the next argument are consumed. Similarly for constructing a matrix from multiple scalars or vectors, or a mixture of these. Matrix components will be constructed and consumed in column major order. In these cases, there must be enough components provided in the arguments to provide an initializer for every component in the constructed value. It is an error to provide extra arguments beyond this last used argument.

If a matrix is constructed from a matrix, then each component (column i, row j) in the result that has a corresponding component (column i, row j) in the argument will be initialized from there. All other components will be initialized to the identity matrix. If a matrix argument is given to a matrix constructor, it is an error to have any other arguments.

If the basic type (bool, int, or float) of a parameter to a constructor does not match the basic type of the object being constructed, the scalar construction rules (above) are used to convert the parameters.

Some useful vector constructors are as follows:

Some examples of these are:

To initialize the diagonal of a matrix with all other elements set to zero:

That is, result[i][j] is set to the float argument for all \(i = j\) and set to 0 for all \(i \neq j\).

To initialize a matrix by specifying vectors or scalars, the components are assigned to the matrix elements in column-major order.

A wide range of other possibilities exist, to construct a matrix from vectors and scalars, as long as enough components are present to initialize the matrix. To construct a matrix from a matrix:

Once a structure is defined, and its type is given a name, a constructor is available with the same name to construct instances of that structure. For example:

The arguments to the constructor will be used to set the structure’s members, in order, using one argument per member. Each argument must be the same type as the member it sets.

Structure constructors can be used as initializers or in expressions.

Array types can also be used as constructor names, which can then be used in expressions or initializers. For example,

There must be exactly the same number of arguments as the size of the array being constructed. If no size is present in the constructor, then the array is explicitly sized to the number of arguments provided. The arguments are assigned in order, starting at element 0, to the elements of the constructed array. Each argument must be the same type as the element type of the array.

Arrays of arrays are similarly constructed, and the size for any dimension is optional

Texture-combined sampler constructors are only available when targeting Vulkan.

Texture-combined sampler types, like sampler2D, can be declared with an initializer that is a constructor of the same type, and consuming a texture and a sampler or samplerShadow. For example:

The result of a texture-combined sampler constructor cannot be assigned to a variable:

Texture-combined sampler constructors can only be consumed by a function parameter.

Texture-combined sampler constructors of arrays are illegal:

Formally:

Note: Shadow mismatches are allowed between constructors and the second argument. Texture-combined non-shadow samplers can be constructed from samplerShadow and texture-combined shadow samplers can be constructed from sampler.