Home

GLSL Specification

1. Precedence Operator class Operators Associativity 1 highest parenthetical grouping NA 2 unary defined Right to Left eka 3 multiplicative Left to Right 4 additive Left to Right 5 bit wise shift lt lt gt gt Left to Right 6 relational lt gt lt gt Left to Right 7 equality Left to Right 8 bit wise and amp Left to Right 9 bit wise exclusive or A Left to Right 10 bit wise inclusive or Left to Right 11 logical and amp amp Left to Right 12 lowest logical inclusive or Left to Right 16 3 Basics The defined operator can be used in either of the following ways defined identifier defined identifier Two tokens in a macro can be concatenated into one token using the token pasting operator as is standard for C preprocessors The result must be a valid single token which will then be subject to macro expansion That is macro expansion happens only after token pasting There are no other number sign based operators e g no or nor is there a sizeof operator The semantics of applying operators to integer literals in the preprocessor match those standard in the C preprocessor not those in the OpenGL Shading Language Preprocessor expressions will be evaluated according to the behavior of the host processor not the processor targeted by the shader error will cause the implementation to put a compile time diagnostic message
2. Type Meaning ivec3 a three component signed integer vector ivec4 a four component signed integer vector uvec2 a two component unsigned integer vector uvec3 a three component unsigned integer vector uvec4 a four component unsigned integer vector mat2 a 2x2 single precision floating point matrix mat3 a 3x3 single precision floating point matrix mat4 a 4x4 single precision floating point matrix mat2x2 same as a mat2 mat2x3 a single precision floating point matrix with 2 columns and 3 rows mat2x4 a single precision floating point matrix with 2 columns and 4 rows mat3x2 a single precision floating point matrix with 3 columns and 2 rows mat3x3 same as a mat3 mat3x4 a single precision floating point matrix with 3 columns and 4 rows mat4x2 a single precision floating point matrix with 4 columns and 2 rows mat4x3 a single precision floating point matrix with 4 columns and 3 rows mat4x4 same as a mat4 dmat2 a 2x2 double precision floating point matrix dmat3 a 3x3 double precision floating point matrix dmat4 a 4x4 double precision floating point matrix dmat2x2 same as a dmat2 dmat2x3 a double precision floating point matrix with 2 columns and 3 rows dmat2x4 a double precision floating point matrix with 2 columns and 4 rows dmat3x2 a double precision floating point matrix with 3 columns and 2 rows dmat3x3 same as a dmat3 dmat3x4 a double precision floating point matrix with 3 columns and 4 rows dmat4x2 a double precision floating p
3. gvec4 textureGrad gsampler1D sampler float P float dPdx float dPdy gvec4 textureGrad gsampler2D sampler vec2 P vec2 dPdx vec2 dPdy gvec4 textureGrad gsampler3D sampler vec3 P vec3 dPdx vec3 dPdy gvec4 textureGrad gsamplerCube sampler vec3 P vec3 dPdx vec3 dPdy gvec4 textureGrad gsampler2DRect sampler vec2 P vec2 dPdx vec2 dPdy float textureGrad sampler2DRectShadow sampler vec3 P vec2 dPdx vec2 dPdy float textureGrad sampler DShadow sampler vec3 P float dPdx float dPdy float textureGrad sampler2DShadow sampler vec3 P vec2 dPdx vec2 dPdy float textureGrad samplerCubeShadow sampler vec4 P vec3 dPdx vec3 dPdy gvec4 textureGrad gsampler DArray sampler vec2 P float dPdx float dPdy gvec4 textureGrad gsampler2DArray sampler vec3 P vec2 dPdx vec2 dPdy float textureGrad sampler DArrayShadow sampler vec3 P float dPdx float dPdy float textureGrad sampler2DArrayShadow sampler vec4 P vec2 dPdx vec2 dPdy gvec4 textureGrad gsamplerCubeArray sampler vec4 P vec3 dPdx vec3 dPdy Do a texture lookup as in texture but with explicit gradients The partial derivatives of P are with respect to window x and window y Set OP as x for a 1D texture ens otherwise Ox oP as z ay for a 1D texture oy DES otherwise oy a 0 0 fora 1D texture t 0Pt Ox otherwise Ox a 0 0 for a 1D texture t 0Pt oy otherwise oy a 0 0 for 1D or
4. 5 uniform flow control again Other examples of non uniform flow control can occur within switch statements and after conditional breaks continues early returns and after fragment discards when the condition is true for some fragments but not others Loop iterations that only some fragments execute are also non uniform flow control This is similarly defined for other shader stages based on the per instance data items they process Dynamically Uniform Expressions A fragment shader expression is dynamically uniform if all fragments evaluating it get the same resulting value When loops are involved this refers to the expression s value for the same loop iteration When functions are involved this refers to calls from the same call point This is similarly defined for other shader stages based on the per instance data they process Note that constant expressions are trivially dynamically uniform It follows that typical loop counters based on these are also dynamically uniform 24 4 Variables and Types All variables and functions must be declared before being used Variable and function names are identifiers There are no default types All variable and function declarations must have a declared type and optionally qualifiers A variable is declared by specifying its type followed by one or more names separated by commas In many cases a variable can be initialized as part of its declaration by using the assignment o
5. Constant Expressions greater than zero Except for the last declared member of a shader storage block section 4 3 9 Interface Blocks the size of an array must be declared explicitly sized before it is indexed with anything other than an integral constant expression The size of any array must be declared before passing it as an argument to a function Violation of any of these rules 35 4 Variables and Types result in compile time errors It is legal to declare an array without a size unsized and then later redeclare the same name as an array of the same type and specify a size or index it only with integral constant expressions implicitly sized However unless noted otherwise blocks cannot be redeclared an unsized array in a user declared block cannot be sized by a block redeclaration It is a compile time error to declare an array with a size and then later in the same shader index the same array with an integral constant expression greater than or equal to the declared size It is a compile time error to redeclare an unsized array with a size equal to or smaller than any index used earlier in the shader to index the array It is also a compile time error to index an array with a negative constant expression Arrays declared as formal parameters in a function declaration must specify a size Undefined behavior results from indexing an array with a non constant expression that s greater than or equal to the array s size o
6. Srli float spotCutoff Crli range 0 0 90 0 180 0 float spotCosCutoff Derived cos Crli range 1 0 0 0 1 0 loat constantAttenuation KO loat linearAttenuation K1 Fh Fh Fh loat quadraticAttenuation K2 uniform gl LightSourceParameters gl LightSource gl MaxLights struct gl LightModelParameters vec4 ambient Acs uniform gl LightModelParameters gl LightModel compatibility profile only Derived state from products of light and material struct gl LightModelProducts vec4 sceneColor Derived Ecm Acm Acs uniform gl LightModelProducts gl FrontLightModelProduct uniform gl LightModelProducts gl BackLightModelProduct struct gl LightProducts vec4 ambient Acm Acli vec4 diffuse Dem Deli vec4 specular Sem Scli uniform gl LightProducts gl FrontLightProduct gl MaxLights uniform gl LightProducts gl BackLightProduct gl MaxLights 138 compatibility profile only uniform vec4 gl TextureEnvColor gl MaxTextureUnits uniform vec4 gl EyePlaneS gl MaxTextureCoords uniform vec4 gl EyePlaneT gl_ MaxTextureCoords uniform vec4 gl EyePlaneR gl_ MaxTextureCoords uniform vec4 gl EyePlaneQ gl_ MaxTextureCoords uniform vec4 gl ObjectPlaneS gl MaxTextureCoords uniform vec4 gl ObjectPlaneT gl MaxTextureCoords li uniform vec4 gl ObjectPlaneR gl MaxTextureCoords uniform vec4
7. const int gl MaxTextureUnits 2 const int gl MaxTextureCoords 8 const int gl MaxClipPlanes 8 const int gl MaxVaryingFloats 60 Built In Uniform State As an aid to accessing OpenGL processing state the following uniform variables are built into the OpenGL Shading Language ff Depth range in window coordinates section 13 6 1 Controlling the Viewport in the OpenGL Graphics System Specification iff Note Depth range state is only for viewport 0 struct gl DepthRangeParameters float near Ja float far float diff E n uniform gl DepthRangeParameters gl DepthRange uniform int gl NumSamples Compatibility Profile State These variables are present only in the compatibility profile They are not available to compute shaders but are available to all other shaders compatibility profile only kf uniform mat4 gl ModelViewMatrix uniform mat4 gl ProjectionMatrix uniform mat4 gl ModelViewProjectionMatrix uniform mat4 gl TextureMatrix gl_ MaxTextureCoords compatibility profile only ff uniform mat3 gl NormalMatrix transpose of the inverse of th upper leftmost 3x3 of gl ModelViewMatrix uniform mat4 gl ModelViewMatrixInverse uniform mat4 gl ProjectionMatrixInverse uniform mat4 gl ModelViewProjectionMatrixInverse 136 7 Built in Variables uniform mat4 gl TextureMatrixInverse gl MaxTextureCoords uniform mat4 gl ModelViewMatrixTran
8. of the OpenGL specification Loads and stores support float integer and unsigned integer types The data types below starting 59 Gee gimage serve as placeholders meaning types starting either image iimage or uimage in the same way as gvec or gsampler in earlier sections The JMAGE_PARAMS in the prototypes below is a placeholder representing 33 separate functions each for a different type of image variable The IMAGE PARAMS placeholder is replaced by one of the following parameter lists gimagelD image int P gimage2D image ivec2 P gimage3D image ivec3 P gimage2DRect image ivec2 P gimageCube image ivec3 P gimageBuffer image int P gimagel DArray image ivec2 P gimage2DArray image ivec3 P gimageCubeArray image ivec3 P gimage2DMS image ivec2 P int sample gimage2DMSArray image ivec3 P int sample where each of the lines represents one of three different image variable types and image P and sample specify the individual texel to operate on The method for identifying the individual texel operated on from image P and sample and the method for reading and writing the texel are specified in section 8 25 Texture Image Loads and Stores of the OpenGL specification The atomic functions perform atomic operations on individual texels or samples of an image variable Atomic memory operations read a value from the selected texel compute a new value using one of the operations described below wr
9. two operations performed to aid in replicating subdivision computations The input variables g TessLevelOuter and gl TessLevellnner are available only in the tessellation evaluation shader If a tessellation control shader is active these variables are filled with corresponding outputs written by the tessellation control shader Otherwise they are assigned with default tessellation levels specified in section 11 2 3 3 Tessellation Evaluation Shader Inputs in the OpenGL Graphics System Specification Fragment shaders output values to the OpenGL pipeline using declared out variables the built in variables gl FragDepth and gl SampleMask unless the discard statement is executed The fixed functionality computed depth for a fragment may be obtained by reading gl FragCoord z described below Writing to g FragDepth will establish the depth value for the fragment being processed If depth buffering is enabled and no shader writes g FragDepth then the fixed function value for depth will be used as the fragment s depth value If a shader statically assigns a value to gl FragDepth and there is an execution path through the shader that does not set g FragDepth then the value of the fragment s depth may be undefined for executions of the shader that take that path That is if the set of linked fragment shaders statically contain a write to g FragDepth then it is responsible for always writing it If a shader executes the disca
10. 130 7 Built in Variables statically read or write both gl ClipVertex and gl ClipDistance If neither gl ClipVertex nor gl_ClipDistance is written their values are undefined and any clipping against user clip planes is also undefined Similarly to what was previously described for the core profile the gl PerVertex block can be redeclared in a shader to explicitly include these additional members For example out gl PerVertex vec4 gl Position will use gl_Position vec4 gl FrontColor will consume gl color in the fragment shader vec4 gl BackColor vec4 gl TexCoord 3 3 elements of gl TexCoord will be used no other aspects of the fixed interface will be used The user must ensure the clip vertex and user clipping planes are defined in the same coordinate space User clip planes work properly only under linear transform It is undefined what happens under non linear transform The output variables gl FrontColor glFrontSecondaryColor gl BackColor and glBackSecondaryColor assign primary and secondary colors for front and back faces of primitives containing the vertex being processed The output variable g TexCoord assigns texture coordinates for the vertex being processed For gl FogFragCoord the value written will be used as the c value in section 16 4 Fog of the compatibility profile of the OpenGL Graphics System Specification by the fixed functionality pipeline For example if the z coordinate of the
11. 4 Variables and Types Consuming Shader input variables Treatment of Mismatched Input Variables No Declaration Declared but no Declared and Static Use Static Use No Declaration Allowed Allowed Link Time Error Generating Declared but no Allowed Shader Static Use allowed ANEA values are undefined output variables Declared and plowed Allowed Allowed values are potentially Static Use undefined Consumption errors are based on static use only Compilation may generate a warning but not an error for any dynamic use the compiler can deduce that might cause consumption of undefined values See section 7 Built in Variables for a list of the built in input names Vertex shader input variables or attributes receive per vertex data They are declared in a vertex shader with the in qualifier It is a compile time error to use any auxiliary or interpolation qualifier on a vertex shader input The values copied in are established by the OpenGL API or through the use of the layout identifier location It is a compile time error to declare a vertex shader input containing any of the following e A Boolean type bool bvec2 bvec3 bvec4 e An opaque type e A structure Example declarations in a vertex shader in vec4 position in vec3 normal in vec2 texCoord 4 It is expected that graphics hardware will have a small number of fixed vector locations for passing vertex inputs Therefore
12. 4 Variables and Types Literal integer constants can be expressed in decimal base 10 octal base 8 or hexadecimal base 16 as follows integer constant decimal constant integer suffixop octal constant integer suffix op hexadecimal constant integer suffixop integer suffix one of u U decimal constant nonzero digit decimal constant digit octal constant 0 octal constant octal digit hexadecimal constant 0x hexadecimal digit 0X hexadecimal digit hexadecimal constant hexadecimal digit digit 0 nonzero digit nonzero digit one of 123456789 octal digit one of 01234567 hexadecimal digit one of 0123456789 abcdef ABCDEF No white space is allowed between the digits of an integer constant including after the leading 0 or after the leading 0x or 0X of a constant or before the suffix u or U When tokenizing the maximal token matching the above will be recognized before a new token is started When the suffix u or U is present the literal has type uint otherwise the type is int A leading unary minus sign is interpreted as an arithmetic unary negation not as part of the constant Hence literals themselves are always expressed with non negative syntax though they could result in a negative value It is a compile time error to provide a literal integer whose bit pattern cannot fit in 32 bits The bit pattern of the literal is always used unmodified So a signed literal whose bit pattern includes a se
13. Texture image units can be bound to samplers image units can be bound to images and atomic counters can be bound to buffers Details for specific to image formats and atomic counter bindings are given in the subsections below Image and sampler types both take the uniform layout qualifier identifier for binding 81 4 4 6 1 4 Variables and Types layout qualifier id binding integer constant expression The identifier binding specifies which unit will be bound Any uniform sampler or image variable declared without a binding qualifier is initially bound to unit zero After a program is linked the unit referenced by a sampler or image uniform variable declared with or without a binding identifier can be updated by the OpenGL API If the binding identifier is used with an array the first element of the array takes the specified unit and each subsequent element takes the next consecutive unit If the binding is less than zero or greater than or equal to the implementation dependent maximum supported number of units a compile time error will occur When the binding identifier 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 compilation units in a program specify different integer constant expression bindings for the same opaque uniform name However it is not an error to specify a binding on some but not all declarations f
14. 8 7 Veetor Relational PURES nintendo aT ENEE AA 157 8 9 RS OR a ae a wesc cee a E ne ont 159 8 9 Texture CHROM ennemi aiaa a AEEA AE E ape 161 8 9 1 Texture Query FROM caniae AEE E E ARE 162 3 9 2 Texel Lookup Functions sssri seereis eestas aeeie ie Narea iri TAR EES E EE EPEAT ERECT EPEE ESTEE 165 8 9 3 Texture Gather PUR TOR EESE nan 171 3 9 4 Compatibility Profile Text re FUNGOS sssini india 174 8 10 Atomic Co nter Panel renaud ATEA ANTE N AEA 176 8 11 Atomic Memory POne ions ccaivercncssssnecnncesessonnsiausendvsasacnseseosesannapebvieesardiundasmnannnaavacien 176 8 12 Image FUnCH NS en annonc es 177 8 13 Fragment Processing PR ss items 181 8 13 1 Derivative le Le LL nrnna a a a aa aa eeii 181 38 13 2 Interpolation PONSUONES serment 182 o eE Ng ec A A A A eae es Es 183 8 15 Geometry Shader F NcHOnS ssri ensai E EEEE EE ERE A E 184 8 16 Shader Invocation Control Functions 186 8 17 Shader Memory C ntrol Functions sienose a 187 9 Shading Language Grammar for Core PROS sante 189 10 Normative Referent S na nn ne nr EEES ne 205 vi 1 Introduction This document specifies only version 4 40 of the OpenGL Shading Language It requires __ VERSION _ to substitute 440 and requires version to accept only 440 If version is declared with a smaller number the language accepted is a previous version of the shading language which will be supported depending on the version and t
15. Description gvec4 textureGatherOffsets gsampler2D sampler vec2 P ivec2 offsets 4 int comp gvec4 textureGatherOffsets gsampler2DArray sampler vec3 P ivec2 offsets 4 int comp gvec4 textureGatherOffsets gsampler2DRect sampler vec2 P ivec2 offsets 4 int comp vec4 textureGatherOffsets sampler2DShadow sampler vec2 P float refZ ivec2 ofjsets 4 vec4 textureGatherOffsets sampler2DArrayShadow sampler vec3 P float refZ ivec2 ofjsets 4 vec4 textureGatherOffsets sampler2DRectShadow sampler vec2 P float refZ ivec2 ofjsets 4 Operate identically to textureGatherOffset except that offsets is used to determine the location of the four texels to sample Each of the four texels is obtained by applying the corresponding offset in offsets as a u v coordinate offset to P identifying the four texel LINEAR footprint and then selecting the texel ig of that footprint The specified values in offsets must be set with constant integral expressions 172 8 Built in Functions 8 9 4 Compatibility Profile Texture Functions The following texture functions are only in the compatibility profile Syntax deprecated Description deprecated vec4 texture1D sampler1D sampler float coord float bias vec4 texture1DProj sampler1D sampler vec2 coord float bias vec4 texture1DProj sampler1D sampler vec4 coord float bias vec4 texture1DLod sampl
16. GLSL processing is done on the sequence of GLSL tokens 13 3 2 3 Basics Details that fully define source strings comments line numbering new line elimination and preprocessing are all discussed in upcoming sections Sections beyond those describe GLSL processing Source Strings The source for a single shader is an array of strings of characters from the character set A single shader is made from the concatenation of these strings Each string can contain multiple lines separated by new lines No new lines need be present in a string a single line can be formed from multiple strings No new lines or other characters are inserted by the implementation when it concatenates the strings to form a single shader Multiple shaders can be linked together to form a single program Diagnostic messages returned from compiling a shader must identify both the line number within a string and which source string the message applies to Source strings are counted sequentially with the first string being string 0 Line numbers are one more than the number of new lines that have been processed including counting the new lines that will be removed by the line continuation character Lines separated by the line continuation character preceding a new line are concatenated together before either comment processing or preprocessing No white space is substituted for the line continuation character That is a single token could be formed by the concat
17. In this case the operation is applied resulting in a scalar e One operand is a scalar and the other is a vector or matrix In this case the scalar operation is applied independently to each component of the vector or matrix resulting in the same size vector or matrix The two operands are vectors of the same size In this case the operation is done component wise resulting in the same size vector The operator is add subtract or divide and the operands are matrices with the same number of rows and the same number of columns In this case the operation is done component wise resulting in the same size matrix e The operator is multiply where both operands are matrices or one operand is a vector and the other a matrix A right vector operand is treated as a column vector and a left vector operand as a row vector In all these cases it is required that the number of columns of the left operand is equal to the number of rows of the right operand Then the multiply operation does a linear algebraic multiply yielding an object that has the same number of rows as the left operand and the same number of columns as the right operand Section 5 10 Vector and Matrix Operations explains in more detail how vectors and matrices are operated on All other cases result in a compile time error Dividing by zero does not cause an exception but does result in an unspecified value Use the built in functions dot cros
18. The number of initializers must match the number of components If the aggregate has a matrix type initializers from the list must be vector initializers and are applied to the columns of the matrix in order starting with column 0 The number of initializers must match the number of columns If the aggregate has a structure type initializers from the list are applied to the members of the structure in the order declared in the structure starting with the first member The number of initializers must match the number of members Applying these rules the following matrix declarations are equivalent mat2x2 a mat2 vec2 1 0 0 0 vec2 0 0 1 0 mat2x2 b vec2 1 0 0 0 vec2 0 0 1 0 mat2x2 c L 150 OLO Fy 1 02051 15 0 45 Fe All of the following declarations result in a compile time error float a 21 4 364 4 2 95 0 je illegal vec br 1 0 250 320 illegal mat3x3 c vec3 0 0 vec3 1 0 vec3 2 0 vec3 3 0 illegal mat2x2 d 4 7 20 0 205 gt Ow 042 1 20 he illegal can t flatten nesting struct float a int b Fe 4 1 2 2 34 illegal In all cases the innermost initializer 1 e not a list of initializers enclosed in curly braces applied to an object must have the same type as the object being initialized or be a type that can be converted to the object s type according to section 4 1 10 Implicit Conversions In the latter case an implicit conversion will be do
19. This spans all the outputs declared in all compilation units of the first stage and all the inputs declared in all compilation units of the second stage 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 blocks the application uses the block name to identify the block Block names have no other use within a shader beyond interface matching it is a compile time error to use a block name at global scope for anything other than as a block name e g use of a block name for a global variable name or function name is currently reserved It is a compile time error to use the same block name for more than one block declaration in the same shader interface as defined above within one shader even if the block contents are identical Matched block names within a shader interface as defined above must match in terms of having the same number of declarations with the same sequence of types and the same sequence of member names as well as having the same member wise layout qualification see next section Matched uniform 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 t
20. b c d in two operations instead of three operations one multiply and one multiply add instead of two multiplies and one add The result of a floating point multiply add might not always be identical to first doing a multiply yielding a floating point result and then doing a floating point add Hence in this example the two multiply operations would not be treated consistently the two multiplies could effectively appear to have differing precisions 91 4 Variables and Types The key computation that needs to be made consistent appears when tessellating where intermediate points for subdivision are synthesized in different directions yet need to yield the same result as shown in the diagram below Corner points a start with same values Opposing directions Subdivision points l of edge walking need to land on the for subdivision same location to ee prevent cracking Corner points start with same values Without any qualifiers implementations are permitted to perform such optimizations that effectively modify the order or number of operations used to evaluate an expression even if those optimizations may produce slightly different results relative to unoptimized code The qualifier precise will ensure that operations contributing to a variable s value are done in their stated order and are done with operator consistency Order is determined by operator precedence and parenthesis
21. in section 11 1 3 4 Texture Queries of the OpenGL Graphics System Specification The components in the return value are filled in in order with the width height and depth of the texture For the array forms the last component of the return value is the number of layers in the texture array or the number of cubes in the texture cube map array 162 8 Built in Functions Syntax Description vec2 textureQueryLod gsampler D sampler float P vec2 textureQueryLod gsampler2D sampler vec2 P vec2 textureQueryLod gsampler3D sampler vec3 P vec2 textureQueryLod gsamplerCube sampler vec3 P vec2 textureQueryLod gsampler DArray sampler float P vec2 textureQueryLod gsampler2DArray sampler vec2 P vec2 textureQueryLod gsamplerCubeArray sampler vec3 P vec2 textureQueryLod sampler DShadow sampler float P vec2 textureQueryLod sampler2DShadow sampler vec2 P vec2 textureQueryLod samplerCubeShadow sampler vec3 P vec2 textureQueryLod sampler DArrayShadow sampler float P vec2 textureQueryLod sampler2DArrayShadow sampler vec2 P vec2 textureQueryLod samplerCubeArrayShadow sampler vec3 P int textureQueryLevels gsampler1D sampler int textureQueryLevels gsampler2D sampler int textureQueryLevels gsampler3D sampler int textureQueryLevels gsamplerCube sampler int textureQueryLevels gsampler1DArray sampler int textureQueryLevels gsampler2DArray sampler int textureQueryLevels gsamplerCube
22. out block block has buffer 1 vec4 x x has buffer 1 not captured 1 vec4 y okay not captured 0 vec4 z ERROR mismatched buffer layout xfb buffer layout xfb buffer layout xfb offset 0 out vec4 g g has buffer 1 layout xfb buffer 2 out vec4 h does not change global default layout xfb offset 16 out vec4 j j has buffer 1 Note this means all members of a block that go to a transform feedback buffer will go to the same buffer It is a compile time error to specify an xfb_buffer that is greater than the implementation dependent constant gl MaxTransformFeedbackBuffers The xfb_ offset qualifier assigns a byte offset within a transform feedback buffer Only variables block members or blocks can be qualified with xfb_offset If a block is qualified with xfb_offset all its members are assigned transform feedback buffer offsets If a block is not qualified with xfb_offset any members of that block not qualified with an xfb_offset will not be assigned transform feedback buffer offsets Only variables and block members that are assigned offsets will be captured thus a proper subset of a block can be captured Each time such a variable or block member is written in a shader the written value is captured at the assigned offset If such a block member or variable is not written during a shader invocation the buffer contents at the assigned offset will be undefined Even if there are no static writes t
23. return the refraction vector The result is computed by k 1 0 eta eta 1 0 dot N J dot N J if k lt 0 0 return genType 0 0 or genDType 0 0 else return eta I eta dot N J sqrt k N The input parameters for the incident vector and the surface normal N must already be normalized to get the desired results 153 8 6 Matrix Functions 8 Built in Functions For each of the following built in matrix functions there is both a single precision floating point version where all arguments and return values are single precision and a double precision floating point version where all arguments and return values are double precision Only the single precision floating point version is shown Syntax Description mat matrixCompMult mat x mat y Multiply matrix x by matrix y component wise i e result i j is the scalar product of x i j and y i j Note to get linear algebraic matrix multiplication use the multiply operator mat2 outerProduct vec2 c vec2 r mat3 outerProduct vec3 c vec3 r mat4 outerProduct vec4 c vec4 r mat2x3 outerProduct vec3 c vec2 r mat3x2 outerProduct vec2 c vec3 r mat2x4 outerProduct vec4 c vec2 r mat4x2 outerProduct vec2 c vec4 r mat3x4 outerProduct vec4 c vec3 r mat4x3 outerProduct vec3 c vec4 r Treats the first parameter c as a column vector matrix with one column and the second parameter r as a ro
24. 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 The vertex tessellation and geometry languages have the following predeclared globally scoped default precision statements precision highp float precision highp int The fragment language has the following predeclared globally scoped default precision statements precision mediump int precision highp float There are no errors for omission of a precision qualifier so the above is just for reference of what may happen in OpenGL ES versions of the shading languages 89 4 7 4 4 8 4 8 1 4 Variables and Types Available Precision Qualifiers The built in macro GL FRAGMENT PRECISION HIGH is defined to 1 define GL FRAGMENT PRECISION HIGH 1 This macro is available in the vertex tessellation geometry and fragment languages Variance and the Invariant Qualifier In this section variance refers to the possibility of getting different values from the same expression in different programs For example say two vertex shaders in different programs each set g Position with the same expression in both shaders and the input values into that expression are the same when both shaders run It is possible due to independent compilation of the two s
25. tessellation evaluation tessellation control or geometry shader output that contains any of the following e A Boolean type bool bvec2 bvec3 bvec4 e An opaque type 51 4 Variables and Types Individual vertex tessellation evaluation and geometry outputs are declared as in the following examples out vec3 normal centroid out vec2 TexCoord invariant centroid out vec4 Color noperspective out float temperature flat out vec3 myColor noperspective centroid out vec2 myTexCoord sample out vec4 perSampleColor These can also appear in interface blocks as described in section 4 3 9 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 may be used to output per vertex and per patch data Per vertex output variables are arrayed see arrayed under 4 3 4 Inputs 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 out float foo feeds next stage input in float foo Each element o
26. the OpenGL Shading language defines each non matrix input variable as taking up one such vector location There is an implementation dependent limit on the number of locations that can be used and if this is exceeded it will cause a link time error Declared input variables that are not statically used do not count against this limit A scalar input counts the same amount against this limit as a vecd 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 48 4 Variables and Types 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 in float foof geometry shader input for vertex out float foo 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
27. the declaration layout local size x 8 in effectively specifies that a one dimensional compute shader is being compiled and its size is 8 elements If the fixed local group size of the shader in any dimension is greater than the maximum size supported by the implementation for that dimension a compile time error results Also if such a layout qualifier is declared more than once in the same shader all those declarations must set the same set of local work group sizes and set them to the same values otherwise a compile time error results If multiple compute shaders attached to a single program object declare a fixed local group size the declarations must be identical otherwise a link time error results Furthermore if a program object contains any compute shaders at least one must contain an input layout qualifier specifying a fixed local group size for the program or a link time error will occur Output Layout Qualifiers Some output layout qualifiers apply to all shader languages and some apply only to specific languages The latter are discussed in separate sections below As with input layout qualifiers all shaders except compute shaders allow location layout qualifiers on output variable declarations output block declarations and output block member declarations Of these variables and block members but not blocks additionally allow the component layout qualifier The layout qualifier identifiers for outputs are
28. the most significant bits of the result will be set to zero For signed data types the most significant bits will be set to the value of bit offset bits 1 If bits is zero the result will be zero The result will be undefined if offset or bits is negative or if the sum of offset and bits is greater than the number of bits used to store the operand 158 8 Built in Functions Syntax Description genIType bitfieldInsert genIType base genlType insert int offset int bits genUType bitfieldInsert genUType base genUType insert int offset int bits Returns the insertion of the bits least significant bits of insert into base The result will have bits offset offset bits 1 taken from bits 0 bits 1 of insert and all other bits taken directly from the corresponding bits of base If bits is zero the result will simply be base The result will be undefined if offset or bits is negative or if the sum of offset and bits is greater than the number of bits used to store the operand genIType bitfieldReverse genIType value genUType bitfieldReverse genUType value Returns the reversal of the bits of value The bit numbered n of the result will be taken from bit bits 1 n of value where bits is the total number of bits used to represent value genIType bitCount genIType value genIType bitCount genUType value Returns the number of bits set to 1 in the binary representatio
29. to 0 0 0 0 with pixel_center_integer 67 4 4 1 4 4 Variables and Types Redeclarations are done as follows in vec4 gl FragCoord redeclaration that changes nothing is allowed All the following are allowed redeclaration that change behavior layout origin upper left in vec4 gl FragCoord layout pixel center integer in vec4 gl FragCoord layout origin upper left pixel center integer in vec4 gl FragCoord If gl FragCoord is redeclared in any fragment shader in a program it must be redeclared in all the fragment shaders in that program that have a static use gl FragCoord All redeclarations of gl FragCoord in all fragment shaders in a single program must have the same set of qualifiers Within any shader the first redeclarations of gl FragCoord must appear before any use of gl FragCoord The built in g _ FragCoord is only predeclared in fragment shaders so redeclaring it in any other shader language results in a compile time error Redeclaring gl FragCoord with origin_upper_left and or pixel_center_integer qualifiers only affects gl FragCoord x and gl FragCoord y It has no affect on rasterization transformation or any other part of the OpenGL pipeline or language features Fragment shaders also allow the following layout qualifier on in only not with variable declarations layout qualifier id early_fragment_tests to request that fragment tests be performed before fragment shader execution as describe
30. uvec3 uvec4 vec vec2 vec3 vec4 dvec2 dvec3 dvec4 In all cases the sizes of all the input and return vectors for any particular call must match Syntax Description bvec lessThan vec x vec y bvec lessThan ivec x ivec y bvec lessThan uvec x uvec y Returns the component wise compare of x lt y bvec lessThanEqual vec x vec y bvec lessThanEqual ivec x ivec y bvec lessThanEqual uvec x uvec y Returns the component wise compare of x lt y bvec greaterThan vec x vec y bvec greaterThan ivec x ivec y bvec greaterThan uvec x uvec y Returns the component wise compare of x gt y bvec greaterThanEqual vec x vec y bvec greaterThanEqual ivec x ivec y bvec greaterThanEqual uvec x uvec y Returns the component wise compare of x gt y bvec equal vec x vec y bvec equal ivec x ivec y bvec equal uvec x uvec y bvec equal bvec x bvec y bvec notEqual vec x vec y bvec notEqual ivec x ivec y bvec notEqual uvec x uvec y bvec notEqual bvec x bvec y Returns the component wise compare of x y Returns the component wise compare of x y bool any bvec x Returns true if any component of x is true 156 8 Built in Functions Syntax Description bool all bvec x Returns true only if all components of x are true bvec not bvec x Returns the component wise logical complement of x
31. vec2 offset vec4 interpolateAtOffset vec4 interpolant vec2 offset Returns the value of the input interpolant variable sampled at an offset from the center of the pixel specified by offset The two floating point components of offset give the offset in pixels in the x and y directions respectively An offset of 0 0 identifies the center of the pixel The range and granularity of offsets supported by this function is implementation dependent Noise Functions The noise functions noisel noise2 noise3 and noise4 have been deprecated starting with version 4 4 of GLSL They are defined to return the value 0 0 or a vector whose components are all 0 0 However as in previous releases they are not semantically considered to be compile time constant expressions Syntax deprecated Description deprecated float noisel genType x Returns a 1D noise value based on the input value x vec2 noise2 genType x Returns a 2D noise value based on the input value x vec3 noise3 genType x Returns a 3D noise value based on the input value x vec4 noise4 genType x Returns a 4D noise value based on the input value x 182 8 Built in Functions 8 15 Geometry Shader Functions These functions are only available in geometry shaders They are described in more depth following the table Syntax Description void EmitStreamVertex int stream Emits the current values of output v
32. 1 Texture Access of the OpenGL Graphics System Specification A four component vector is assembled by taking the selected component from each of the post swizzled texture source colors in the order igi ijn ijo iojo For texture gather functions using a shadow sampler type each of the four texel lookups perform a depth comparison against the depth reference value passed in refZ and returns the result of that comparison in the appropriate component of the result vector As with other texture lookup functions the results of a texture gather are undefined for shadow samplers if the texture referenced is not a depth texture or has depth comparisons disabled or for non shadow samplers if the texture referenced is a depth texture with depth comparisons enabled 170 8 Built in Functions Syntax Description gvec4 textureGather gsampler2D sampler vec2 P int comp gvec4 textureGather gsampler2DArray sampler vec3 P int comp gvec4 textureGather gsamplerCube sampler vec3 P int comp gvec4 textureGather gsamplerCubeArray sampler vec4 P int comp gvec4 textureGather gsampler2DRect sampler vec2 P int comp vec4 textureGather sampler2DShadow sampler vec2 P float refZ vec4 textureGather sampler2DArrayShadow sampler vec3 P float refZ vec4 textureGather samplerCubeShadow sampler vec3 P float refZ vec4 textureGather samplerCubeArrayShadow sampler vec4 P float refZ vec4 texture
33. 12 logical and amp amp Left to Right 13 logical exclusive or A Left to Right 14 logical inclusive or Left to Right 15 selection 2 Right to Left Assignment Right to Left arithmetic assignments lt lt gt gt 16 17 lowest sequence 3 Left to Right 98 There is no address of operator nor a dereference operator There is no typecast operator constructors are used instead 5 2 5 3 5 4 5 4 1 5 Operators and Expressions Array Operations These are now described in section 5 7 Structure and Array Operations Function Calls If a function returns a value then a call to that function may be used as an expression whose type will be the type that was used to declare or define the function Function definitions and calling conventions are discussed in section 6 1 Function Definitions Constructors Constructors use the function call syntax where the function name is a type and the call makes an object of that type Constructors are used the same way in both initializers and expressions See section 9 Shading Language Grammar for details The parameters are used to initialize the constructed value Constructors can be used to request a data type conversion to change from one scalar type to another scalar type or to build larger types out of smaller types or to reduce a larger type to a smaller type In general constructors are not built in functions with p
34. 2 d error overlaps offset 0 of a It is a compile time error to bind an atomic counter with a binding value greater than or equal to gl MaxAtomicCounterBindings Format Layout Qualifiers 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 layout qualifier id float image format qualifier int image format qualifier uint image format qualifier binding integer constant expression float image format qualifier rgba32f 83 4 Variables and Types rgbal6f rg32f rg16f rliif g11f b10f r32f rl6f rgbal6 rgb10_a2 rgba8 rg16 rg8 r16 r8 rgba16 snorm rgba8 snorm rg16 snorm rg8_snorm r16 snorm r8_snorm int image format qualifier rgba32i rgbal6i rgba8i rg32i rg16i rg8i r32i rl6i rgi uint image format qualifier rgba32ui rgbal6ui rgb10_a2ui rgba8ui rg32ui rg16ui rg8ui r32ui rl6ui r8ui 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 fl
35. 2D lt 0P Ox P cube other Ox 0 0 for 1D or 2D ae OP oy a cube other For the cube version the partial derivatives of P are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face 168 8 Built in Functions Syntax Description gvec4 textureGradOffset gsampler1D sampler float P float dPdx float dPdy int offset gvec4 textureGradOffset gsampler2D sampler vec2 P vec2 dPdx vec2 dPdy ivec2 offset gvec4 textureGradOffset gsampler3D sampler vec3 P vec3 dPdx vec3 dPdy ivec3 offset gvec4 textureGradOffset gsampler2DRect sampler vec2 P vec2 dPdx vec2 dPdy ivec2 offset float textureGradOffset sampler2DRectShadow sampler vec3 P vec2 dPdx vec2 dPdy ivec2 offset float textureGradOffset sampler DShadow sampler vec3 P float dPdx float dPdy int offset float textureGradOffset sampler2DShadow sampler vec3 P vec2 dPdx vec2 dPdy ivec2 offset gvec4 textureGradOffset gsampler DArray sampler vec2 P float dPdx float dPdy int offset gvec4 textureGradOffset gsampler2DArray sampler vec3 P vec2 dPdx vec2 dPdy ivec2 offset float textureGradOffset sampler DArrayShadow sampler vec3 P float dPdx float dPdy int offset float textureGradOffset sampler2DArrayShadow sampler vec4 P vec2 dPdx vec2 dPdy ivec2 offset Do a texture lookup with both explicit gradient and offset as described in textureGrad and textur
36. 2D texture uimage2D usampler3D a handle for accessing an unsigned integer 3D texture uimage3D usamplerCube a handle for accessing an unsigned integer cube mapped texture uimageCube usampler2DRect a handle for accessing an unsigned integer rectangle texture uimage2DRect usampler1DArray a handle for accessing an unsigned integer 1D array texture uimage1DArray usampler2DArray a handle for accessing an unsigned integer 2D array texture uimage2DArray 28 4 1 1 4 1 2 4 1 3 4 Variables and Types Type Meaning usamplerBuffer a handle for accessing an unsigned integer buffer texture uimageBuffer usampler2DMS a handle for accessing an unsigned integer 2D multi sample texture uimage2DMS usampler2DMSArray a handle for accessing an unsigned integer 2D multi sample texture uimage2DMSArray array usamplerCubeArray a handle for accessing an unsigned integer cube map array texture uimageCubeArray In addition a shader can aggregate these basic types using arrays and structures to build more complex types There are no pointer types Void Functions that do not return a value must be declared as void There is no default function return type The keyword void cannot be used in any other declarations except for empty formal or actual parameter lists or a compile time error results Booleans To make conditional execution of code easier to express the type bool is supported There is no expect
37. Description void barrier For any given static instance of barrier all tessellation control shader invocations for a single input patch must enter it before any will be allowed to continue beyond it or all invocations for a single work group must enter it before any will continue beyond it The function barrier provides a partially defined order of execution between shader invocations This ensures that values written by one invocation prior to a given static instance of barrier can be safely read by other invocations after their call to the same static instance barrier Because invocations may execute in undefined order between these barrier calls the values of a per vertex or per patch output variable or shared variables for compute shaders will be undefined in a number of cases enumerated in section 4 3 6 Output Variables for tessellation control shaders and section 4 3 8 Shared Variables for compute shaders For tessellation control shaders the barrier function may only be placed inside the function main of the tessellation control shader and may not be called within any control flow Barriers are also disallowed after a return statement in the function main Any such misplaced barriers result in a compile time error For compute shaders the barrier function may be placed within flow control but that flow control must be uniform flow control That is all the controlling expressions that lead to exe
38. PAREN LEFT BRACKET RIGHT BRACKET LEFT BRACE RIGHT BRACE DOT COMMA COLON EQUAL SEMICOLON BANG DASH TILDE PLUS STAR SLASH PERCENT EFT ANGLE RIGHT ANGLE VERTICAL BAR CARET AMPERSAND QUESTIO INVARIANT PRECISE HIGH PRECISION MEDIUM PRECISION LOW PRECISION PRECISION The following describes the grammar for the OpenGL Shading Language in terms of the above tokens The starting rule is translation unit An empty shader one having no tokens to parse after pre processing is valid resulting in no compile time errors even though the grammar below does not have a tule to accept an empty token stream variable_identifier IDENTIFIER primary_expression variable_identifier INTCONSTANT UINTCONSTANT FLOATCONSTANT BOOLCONSTANT DOUBLECONSTANT LEFT PAREN expression RIGHT PAREN postfix_expression primary_expression postfix_expression LEFT BRACKET integer_expression RIGHT BRACKET function_call postfix_expression DOT FIELD_SELECTION postfix_expression INC_OP postfix_expression DEC_OP 189 9 Shading Language Grammar for Core Profile integer_expression expression function_call function_call_or_method function_call_or_method function_call_generic function_call_generic function_call_header_with_parameters RIGHT PAREN function_call_header_no_parameters RIGHT PAREN function_call_header_no_parameters
39. and y are both 0 genType atan genType y over x Arc tangent Returns an angle whose tangent is y_over_x The range of values returned by this function TT Fo Poe 141 8 Built in Functions Syntax Description genType sinh genType x Returns the hyperbolic sine function e es e 2 genType cosh genType x Returns the hyperbolic cosine function e e 2 genType tanh genType x Returns the hyperbolic tangent function sinh x cosh x genType asinh genType x Arc hyperbolic sine returns the inverse of sinh genType acosh genType x Arc hyperbolic cosine returns the non negative inverse of cosh Results are undefined if x lt 1 genType atanh genType x Arc hyperbolic tangent returns the inverse of tanh Results are undefined if x gt 1 142 8 2 Exponential Functions 8 Built in Functions These all operate component wise The description is per component Syntax Description genType pow genType x genType y Returns x raised to the y power i e x Results are undefined if x lt 0 Results are undefined if x 0 and y lt 0 genType exp genType x Returns the natural exponentiation of x i e e genType log genType x Returns the natural logarithm of x i e returns the value y which satisfies the equation x Results are undefined if x lt 0 genType exp2 genType x Returns 2 raised to the x power i e
40. as described in section 5 1 Operators Operator consistency means for each particular operator for example the multiply operator its operation is always computed with the same precision Specifically values computed by compiler generated code must adhere to the following identities 1l a b bta 2 a b b a 3 a b c d b a c d d c b a lt any other mathematically valid combination gt While the following are prevented 4 a b c is not allowed to become a b c 5 a b c is not allowed to become a b c 6 a b c isnot allowed to become a single operation fma a b c Where a b c and d are scalars or vectors not matrices Matrix multiplication generally does not commute It is the shader writer s responsibility to express the computation in terms of these rules and the compiler s responsibility to follow these rules See the description of g TessCoord for the rules the tessellation stages are responsible for following which in conjunction with the above allow avoiding cracking when subdividing 92 4 Variables and Types For example precise out vec4 position declares that operations used to produce the value of position must be performed in exactly the order specified in the source code and with all operators being treated consistently As with the invariant qualifier section 4 8 1 The Invariant Qualifier the precise qualifier may be used to qualify a built in or previously decla
41. be bound within the memory extent of the active program It will not be possible to access memory from other programs and accesses will not result in abnormal program termination Out of bounds reads return undefined values which include values from other variables of the active program or zero Out of bounds writes may be discarded or overwrite other variables of the active program depending on the value of the computed index and how this relates to the extent of the active program s memory Applications that require defined behavior for out of bounds accesses should range check all computed indices before dereferencing an array 111 6 Statements and Structure The fundamental building blocks of the OpenGL Shading Language are e statements and declarations e function definitions e selection if else and switch case default iteration for while and do while jumps discard return break and continue The overall structure of a shader is as follows translation unit global declaration translation unit global declaration global declaration function definition declaration That is a shader is a sequence of declarations and function bodies Function bodies are defined as function definition function prototype statement list statement list statement statement list statement statement compound statement simple statement 112 6 1 6 Statements and Structure Curly braces are used to group sequences of
42. be used by the subsequent fixed functionality pipeline If subsequent fixed functionality consumes fragment color and an execution of the fragment shader executable does not write a value to g FragColor then the fragment color consumed is undefined The variable g FragData is an array Writing to gl FragData n specifies the fragment data that will be used by the subsequent fixed functionality pipeline for data n If subsequent fixed functionality consumes fragment data and an execution of a fragment shader executable does not write a value to it then the fragment data consumed is undefined If a shader statically assigns a value to g FragColor it may not assign a value to any element of gl FragData If a shader statically writes a value to any element of g FragData it may not assign a value to gl FragColor That is a shader may assign values to either g FragColor or gl _FragData but not both Multiple shaders linked together must also consistently write just one of these variables Similarly if user declared output variables are in use statically assigned to then the built in variables gl FragColor and gl_FragData may not be assigned to These incorrect usages all generate compile time or link time errors If a shader executes the discard keyword the fragment is discarded and the values of gl FragDepth and gl FragColor become irrelevant Compatibility Profile Vertex Shader Built In Inputs The following predeclared input names can
43. be used from within a vertex shader to access the current values of OpenGL state when using the compatibility profile in vec4 gl Color in vec4 gl SecondaryColor in vec3 gl Normal in vec4 gl Vertex in vec4 gl MultiTexCoord0 in vec4 gl MultiTexCoordl in vec4 gl MultiTexCoord2 in vec4 gl MultiTexCoord3 in vec4 gl MultiTexCoord4 in vec4 gl MultiTexCoord5 in vec4 gl MultiTexCoord6 in vec4 gl MultiTexCoord7 in float gl FogCoord 133 7 Built in Variables 7 3 Built In Constants The following built in constants are provided to all shaders The actual values used are implementation dependent but must be at least the value shown Implementation dependent constants Th xample values below are the minimum values allowed for these maximums const ivec3 gl MaxComputeWorkGroupCount 65535 65535 65535 const ivec3 gl MaxComputeWorkGroupSize 1024 1024 64 const int gl MaxComputeUniformComponents 1024 const int gl MaxComputeTexturelmageUnits 16 const int gl MaxComputeImageUniforms 8 const int gl MaxComputeAtomicCounters 8 const int gl MaxComputeAtomicCounterBuffers 8 const int gl MaxVertexAttribs 16 const int gl MaxVertexUniformComponents 1024 const int gl MaxVaryingComponents 60 const int gl MaxVertexOutputComponents 64 const int gl MaxGeometryInputComponents 64 const int gl MaxGeometryOutputComponents 128 const int gl MaxFragmentInputCom
44. blocks When a block declaration is qualified with a memory qualifier it is as if all of its members were declared with the same memory qualifier For example the block declaration coherent buffer Block readonly vec4 member1 vec4 member2 is equivalent to buffer Block coherent readonly vec4 member1 coherent vec4 member2 Memory qualifiers are only supported in the declarations of image variables buffer variables and shader storage blocks it is an error to use such qualifiers in any other declarations The values of image variables qualified with coherent volatile restrict readonly or writeonly may not be passed to functions whose formal parameters lack such qualifiers See section 6 1 Function Definitions for more detail on function calling It is legal to have additional qualifiers on a formal parameter but not to have fewer 96 4 11 4 Variables and Types vec4 funcA restrict image2D a sise Gh vec4 funcB image2D a te layout rgba32f uniform image2D imgl layout rgba32f coherent uniform image2D img2 funcA imgl OK adding restrict is allowed funcB img2 illegal stripping coherent is not Layout qualifiers cannot be used on formal function parameters but they are not included in parameter matching Note that the use of const in an image variable declaration is qualifying the const ness of the variable being declared not the image it refers to The qualifier r
45. but not required that the shader assigns a range of tightly packed index values starting from zero so that the OpenGL subroutine function enumeration API returns a non empty name for all active indices Uniform and Shader Storage Block Layout Qualifiers 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 layout qualifier id shared packed std140 std430 row_major column_major binding integer constant expression offset integer constant expression align integer constant expression 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 for shared packed std140 std430 row_major and column_major are established at global scope for uniform blocks as layout layout qualifier id list uniform and for shader storage blocks as 78 4 Variables and Types layout layout qualifier id list buffer When this is done the previous default qualification is
46. by or if provided must be consistent with the input layout declaration s establishing the type of input primitive as described later in section 4 4 1 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 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 de
47. by the invocation performing the stores an invocation reading from a variable that it previously wrote will always see the most recently written value unless another shader invocation also wrote to the same memory 187 9 Shading Language Grammar for Core Profile 9 Shading Language Grammar for Core Profile The grammar is fed from the output of lexical analysis The tokens returned from lexical analysis are CONST BOOL FLOAT DOUBLE INT UINT BREAK CONTINUE DO ELSE FOR IF DISCARD RETURN SWITCH CASE DEFAULT SUBROUTIN BVEC2 BVEC3 BVEC4 IVEC2 IVEC3 IVEC4 UVEC2 UVEC3 UVEC4 VEC2 VEC3 VEC4 AT2 MAT3 MAT4 CENTROID IN OUT INOUT UNIFORM PATCH SAMPLE BUFFER SHARED COHERENT VOLATILE RESTRICT READONLY WRITEONLY DVEC2 DVEC3 DVEC4 DMAT2 DMAT3 DMAT4 Le NOPERSPECTIVE FLAT SMOOTH LAYOUT AT2X2 MAT2X3 MAT2X4 AT3X2 MAT3X3 MAT3X4 ATAX2 MAT4X3 MAT4X4 DMAT2X2 DMAT2X3 DMAT2X4 DMAT3X2 DMAT3X3 DMAT3X4 DMAT4X2 DMAT4X3 DMAT4X4 ATOMIC UI SAMPLER1D SAMPLER2D SAMPLER3D SAMPLERCUBE SAMPLERIDSHADOW SAMPLER2DSHADOW SAMPLERCUBESHADOW SAMPLERIDARRAY SAMPLER2DARRAY SAMPLER1DARRAY SHADOW SAMPLER2DARRAYSHADOW ISAMPLERID ISAMPLER2D ISAMPLER3D ISAMPLERCUBE ISAM DARRAY ISAMPLER2DARRAY USAMPLER1D USAMPLER2D USAMPLER3D USAMPLERCUBE USAMPLERIDARRAY USAMPLER2DARRAY SAMPLER2DRECT SAMPLER2DRE ER2DRECT USAMPLER2DRECT SAMPLERBUFFER ISAMPLERBUFFER USAM
48. can be redeclared to establish an explicit pipeline interface the same way as described above for the output block gi PerVertex and the input redeclaration must match the output redeclaration of the previous stage However when a built in interface block with an instance name is redeclared e g gl in the instance name must be included in the redeclaration It is a compile time error to not include the built in instance name or to change its name For example in gl PerVertex vec4 gl ClipVertex vec4 gl FrontColor gl_in must be present and must be gl in Treatment of g _TexCoord redeclaration is also identical to that described for the output block gl TexCoord redeclaration The following fragment input block is also available in a fragment shader when using the compatibility profile in gl PerFragment in float gl FogFragCoord in vec4 gl TexCoord in vec4 gl Color in vec4 gl SecondaryColor The values in g Color and gl_SecondaryColor will be derived automatically by the system from gl FrontColor gl_BackColor gl FrontSecondaryColor and gl BackSecondaryColor based on which face is visible in the primitive producing the fragment If fixed functionality is used for vertex processing then gl FogFragCoord will either be the z coordinate of the fragment in eye space or the interpolation of the fog coordinate as described in section 16 4 Fog of the compatibility profile of the OpenGL Graphics Sy
49. definitions both with and without macro parameters The following predefined macros are available 15 3 Basics __ LINE _ FILE __ VERSION __ _ LINE _ will substitute a decimal integer constant that is one more than the number of preceding new lines in the current source string __FILE _ will substitute a decimal integer constant that says which source string number is currently being processed __VERSION _ will substitute a decimal integer reflecting the version number of the OpenGL shading language The version of the shading language described in this document will have _ VERSION __ substitute the decimal integer 440 By convention all macro names containing two consecutive underscores ___ are reserved for use by underlying software layers Defining such a name in a shader does not itself result in an error but may result in unintended behaviors that stem from having multiple definitions of the same name All macro names prefixed with GL_ GL followed by a single underscore are also reserved and defining such a name results in a compile time error if ifdef ifndef else elif and endif are defined to operate as is standard for C preprocessors Expressions following if and elif are further restricted to expressions operating on literal integer constants plus identifiers consumed by the defined operator Character constants are not supported The operators available are as follows
50. described for a single program or the values passed along the interface are undefined Compatibility Profile Built In Language Variables When using the compatibility profile the GL can provide fixed functionality behavior for the vertex and fragment programmable pipeline stages For example mixing a fixed functionality vertex stage with a programmable fragment stage The following built in vertex tessellation control tessellation evaluation and geometry output variables are available to specify inputs for the subsequent programmable shader stage or the fixed functionality fragment stage A particular one should be written to if any functionality in a corresponding fragment shader or fixed pipeline uses it or state derived from it Otherwise behavior is undefined The following members are added to the output g PerVertex block in these languages out gl PerVertex part of the gl PerVertex block described in 7 1 in addition to other gl PerVertex members vec4 gl ClipVertex vec4 gl FrontColor vec4 gl BackColor vec4 gl FrontSecondaryColor vec4 gl BackSecondaryColor vec4 gl TexCoord g float gl FogFragCoord The output variable gl ClipVertex provides a place for vertex and geometry shaders to write the coordinate to be used with the user clipping planes Writing to g ClipDistance is the preferred method for user clipping It is a compile time or link time error for the set of shaders forming a program to
51. exiting the scope that hid it The built in functions are scoped in a scope outside the global scope users declare global variables in That is a shader s global scope available for user defined functions and global variables is nested inside the scope containing the built in functions When a function name is redeclared in a nested scope it hides all functions declared with that name in the outer scope Function declarations prototypes cannot occur inside of functions they must be at global scope or for the built in functions outside the global scope otherwise a compile time error results Shared globals are global variables declared with the same name in independently compiled units shaders within the same language 1 e same stage e g vertex that are linked together when making a single program Globals forming the interface between two different shader languages are discussed in other sections Shared globals share the same name space and must be declared with the same type They will share the same storage Shared global arrays must have the same base type and the same explicit size An array implicitly sized in one shader can be explicitly sized by another shader in the same stage If no shader in a stage has an explicit size for the array the largest implicit size one more than the largest index used in that stage is used There is no cross stage array sizing If there is no static access to an implicitly sized array within
52. fragment in eye space is desired as c then that s what the vertex shader executable should write into gl FogFragCoord As with all arrays indices used to subscript g TexCoord must either be an integral constant expressions or this array must be redeclared by the shader with a size The size can be at most g MaxTextureCoords Using indexes close to 0 may aid the implementation in preserving varying resources The redeclaration of gl TexCoord can also be done at global scope as for example in vec4 gl TexCoord 3 out vec4 gl TexCoord 4 This treatment is a special case for g TexCoord not a general method for redeclaring members of blocks It is a compile time error to redeclare gl TexCoord at global scope if there is a redeclaration of the corresponding built in block only one form of redeclaration is allowed within a shader and hence within a stage as block redeclarations must match across all shaders using it In the tessellation control evaluation and geometry shaders the outputs of the previous stage described above are also available in the input g PerVertex block in these languages 131 7 Built in Variables in gl PerVertex part of the gl PerVertex block described in 7 1 in addition to other gl PerVertex members vec4 gl ClipVertex vec4 gl FrontColor vec4 gl BackColor vec4 gl FrontSecondaryColor vec4 gl BackSecondaryColor vec4 gl TexCoord float gl FogFragCoord gl_in These
53. gl ObjectPlaneQ gl MaxTextureCoords r LT compatibility profile only struct gl FogParameters vec4 color float density float start float end float scale Derived 1 0 end start uniform gl FogParameters gl Fog 139 7 Built in Variables 8 Built in Functions The OpenGL Shading Language defines an assortment of built in convenience functions for scalar and vector operations Many of these built in functions can be used in more than one type of shader but some are intended to provide a direct mapping to hardware and so are available only for a specific type of shader The built in functions basically fall into three categories e They expose some necessary hardware functionality in a convenient way such as accessing a texture map There is no way in the language for these functions to be emulated by a shader e They represent a trivial operation clamp mix etc that is very simple for the user to write but they are very common and may have direct hardware support It is a very hard problem for the compiler to map expressions to complex assembler instructions e They represent an operation graphics hardware is likely to accelerate at some point The trigonometry functions fall into this category Many of the functions are similar to the same named ones in common C libraries but they support vector input as well as the more traditional scalar input Applications should be encouraged t
54. into the shader object s information log see section 7 12 Shader and Program Queries in the OpenGL Graphics System Specification for how to access a shader object s information log The message will be the tokens following the error directive up to the first new line The implementation must then consider the shader to be ill formed pragma allows implementation dependent compiler control Tokens following pragma are not subject to preprocessor macro expansion If an implementation does not recognize the tokens following pragma then it will ignore that pragma The following pragmas are defined as part of the language pragma STDGL The STDGL pragma is used to reserve pragmas for use by future revisions of this language No implementation may use a pragma whose first token is STDGL pragma optimize on pragma optimize off can be used to turn off optimizations as an aid in developing and debugging shaders It can only be used outside function definitions By default optimization is turned on for all shaders The debug pragma pragma debug on pragma debug off can be used to enable compiling and annotating a shader with debug information so that it can be used with a debugger It can only be used outside function definitions By default debug is turned off Shaders should declare the version of the language they are written to The language version a shader is written to is specified by version number profile
55. is associated with a particular function all function calls through that variable will call that particular function Unlike other uniform variables subroutine uniform variables are scoped to the shader execution stage the variable is declared in Subroutine variables may be declared as explicitly sized arrays which can be indexed only with dynamically uniform expressions Selection Conditional control flow in the shading language is done by either if if else or switch statements selection statement if bool expression statement if bool expression statement else statement switch init expression switch statement list Where switch statement list is a nested scope containing a list of zero or more switch statement and other statements defined by the language where switch statement adds some forms of labels That is 118 6 3 6 Statements and Structure switch statement list switch statement switch statement list switch statement switch statement case constant expression default statement If an if expression evaluates to true then the first statement is executed If it evaluates to false and there is an else part then the second statement is executed Any expression whose type evaluates to a Boolean can be used as the conditional expression bool expression Vector types are not accepted as the expression to if Conditionals can be nested The type of the init expression value in a switch st
56. label and the end of the switch statement existing compiler errors for this can turn into a warning Bug 11180 Clarify behavior of frexp and Idexp at boundary conditions Bug 10802 Mark g MaxGeometryVaryingComponents as deprecated Bug 11635 State in more places that and don t apply to opaque types 1 2 2 Changes since revision 7 of GLSL version 4 40 Bug 10440 Clarify that a name collision between members of two anonymous blocks or between a variable and a member of an anonymous block is an error Bug 11009 Removed packed from the reserved word list Bug 11299 Fixed textureOffset for sampler2DArrayShadow to take a ivec2 not a vec2 for the offset Bug 11209 It is a compile time error to use the same block name for more than one block declaration in the same interface within one shader even if the block contents are identical Bug 11100 Simplify statement of what is written by EmitStreamVertex to just say all built in and user defined output variables 1 Introduction Bug 11096 gl SampleMask can be sized to be no larger than the implementation dependent maximum sample mask Bug 10812 Missing text Added the phrase a pair of 16 bit signed integers when describing unpackSnorm2x16 Bug 10804 When a uniform layout location is used it is not required that all declarations of that name include the location only that those that include a location use the same location Bug 11001 Remove extraneous
57. memory qualifiers parameters can have these parameter qualifiers Qualifier Meaning lt none default gt same is in const for function parameters that cannot be written to in for function parameters passed into a function out for function parameters passed back out of a function but not initialized for use when passed in inout for function parameters passed both into and out of a function Parameter qualifiers are discussed in more detail in section 6 1 1 Function Calling Conventions Precision and Precision Qualifiers Precision qualifiers are added for code portability with OpenGL ES not for functionality They have the same syntax as in OpenGL ES as described below but they have no semantic meaning which includes no effect on the precision used to store or operate on variables If an extension adds in the same semantics and functionality in the OpenGL ES 2 0 specification for precision qualifiers then the extension is allowed to reuse the keywords below for that purpose For the purposes of determining if an output from one shader stage matches an input of the next stage the precision qualifier need not match Range and Precision The precision of stored single and double precision floating point variables is defined by the IEEE 754 standard for 32 bit and 64 bit floating point numbers This includes support for NaNs Not a Number and Infs positive or negative infinities The follo
58. must be at least one geometry output layout declaration somewhere in that program but not all geometry shaders compilation units are required to declare it Fragment Outputs The built in fragment shader variable gl FragDepth may be redeclared using one of the following layout qualifiers layout qualifier id depth_any depth_greater depth_less depth_unchanged For example layout depth greater out float gl FragDepth The layout qualifier for gl_ FragDepth constrains intentions of the final value of gl FragDepth written by any shader invocation GL implementations are allowed to perform optimizations assuming that the depth test fails or passes for a given fragment if all values of gl_FragDepth consistent with the layout qualifier would fail or pass This potentially includes skipping shader execution if the fragment is discarded because it is occluded and the shader has no side effects If the final value of gl_ FragDepth is inconsistent with its layout qualifier the result of the depth test for the corresponding fragment is undefined However no error will be generated in this case If the depth test passes and depth writes are enabled the value written to the depth buffer is always the value of gl_FragDepth whether or not it is consistent with the layout qualifier By default gl FragDepth is qualified as depth_any When the layout qualifier for gl_ FragDepth is depth_any the shader compiler will note any assignment to gl Fra
59. 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 Accessing the same packed uniform or shader storage block in multiple stages within a program may result in a link time error If no link time error is given then members will have the same offsets across stages and reads will be well defined Accessing 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 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 using std430 on a uniform block will result in a compile time error The layout is explicitly determined by this as described in section 7 6 2 Uniform Blocks under Standard Uniform Block Layout of the OpenGL Graphics System 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 qual
60. otherwise accesses to restrict qualified variables will have returned undefined values Memory accesses to image variables declared using the readonly qualifier may only read the underlying memory which is treated as read only memory and cannot be written to It is a compile time error to pass an image variable qualified with readonly to imageStore or other built in functions that modify image memory Memory accesses to image variables declared using the writeonly qualifier may only write the underlying memory the underlying memory cannot be read It is a compile time error to pass an image variable qualified with writeonly to imageLoad or other built in functions that read image memory A variable could be qualified as both readonly and writeonly disallowing both read and write but still be passed to imageSize to have the size queried The memory qualifiers coherent volatile restrict readonly and writeonly may be used in the declaration of buffer variables 1 e members of shader storage blocks When a buffer variable is declared with a memory qualifier the behavior specified for memory accesses involving image variables described above applies identically to memory accesses involving that buffer variable It is a compile time error to assign to a buffer variable qualified with readonly or to read from a buffer variable qualified with writeonly Additionally memory qualifiers may also be used in the declaration of shader storage
61. p where number must be a version of the language following the same convention as _ VERSION _ above The directive version 440 is required in any shader that uses version 4 40 of the language Any number representing a version of the language a compiler does not support will cause a compile time error to be generated Version 1 10 of the language does not require shaders to include this directive and shaders that do not include a version directive will be treated as targeting version 1 10 Shaders that 17 3 Basics specify version 100 will be treated as targeting version 1 00 of the OpenGL ES Shading Language Shaders that specify version 300 will be treated as targeting version 3 00 of the OpenGL ES Shading Language If the optional profile argument is provided it must be the name of an OpenGL profile Currently there are three choices core compatibility es A profile argument can only be used with version 150 or greater If no profile argument is provided and the version is 150 or greater the default is core If version 300 is specified the profile argument is not optional and must be es or a compile time error results The Language Specification for the es profile is specified in The OpenGL ES Shading Language specification Shaders for the core or compatibility profiles that declare different versions can be linked together However es profile shaders cannot be linked with non es profile shaders or with es profile sh
62. present No white space may appear anywhere within a floating point constant including before a suffix When tokenizing the maximal token matching the above will be recognized before a new token is started When the suffix If or LF is present the literal has type double Otherwise the literal has type float A leading unary minus sign is interpreted as a unary operator and is not part of the floating point constant Vectors The OpenGL Shading Language includes data types for generic 2 3 and 4 component vectors of floating point values integers or 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 declaration are vec2 texcoordl texcoord2 vec3 position vec4 myRGBA ivec2 textureLookup bvec3 less Initialization of vectors can be done with constructors which are discussed shortly Matrices The OpenGL Shading Language has built in types for 2x2 2x3 2x4 3x2 3x3 3x4 4x2 4x3 and 4x4 matrices of floating point numbers Matrix types beginning with mat have single precision components 32 4 1 7 4 1 7 1 4 1 7 2 4 Variables and Types while matrix types beginning with dmat have double precision components The first number in the type is the number of columns the second is the number of rows If there is
63. qualifier or with a uniform qualifier Global variables without storage qualifiers that are not initialized in their declaration or by the application will not be initialized by OpenGL but rather will enter main with undefined values When comparing an output from one shader stage to an input of a subsequent shader stage the input and output don t match if their auxiliary qualifiers or lack thereof are not the same Default Storage Qualifier 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 Constant Qualifier Named compile time constants or read only variables can be declared using the const qualifier The const qualifier can be used with any of the non void transparent basic data types as well as with structures and arrays of these It is a compile time error to write to a const variable outside of its declaration so they must be initialized when declared For example const vec3 zAxis vec3 0 0 0 0 1 0 const float ceiling a b a and b not necessarily constants Structure members may not be qualified with const Structure variables can be declared as const and initialized with a structure constructor or initializer In
64. relational_expression LEFT ANGLE shift expression relational_expression RIGHT ANGLE shift _ expression relational_expression LE_OP shift _ expression relational_expression GE_OP shift_expression equality_expression relational_expression equality_expression EQ_OP relational_expression equality_expression NE_OP relational_expression and_expression equality_expression and_expression AMPERSAND equality_expression 191 9 Shading Language Grammar for Core Profile exclusive _or_expression and_expression exclusive or expression CARET and_expression inclusive _or_expression exclusive or expression inclusive or expression VERTICAL BAR exclusive or expression logical_and_expression inclusive_or_expression logical_and_expression AND_OP inclusive_or_expression logical_xor_expression logical_and_expression logical_xor_expression XOR_OP logical_and_expression logical_or_expression logical_xor_expression logical_or_expression OR_OP logical_xor_expression conditional_expression logical_or_expression logical_or_expression QUESTION expression COLON assignment_expression assignment_expression conditional_expression unary_expression assignment_operator assignment_expression assignment_operator EQUAL MUL_ASSIGN DIV_ASSIGN MOD_ASSIGN ADD_ASSIGN SUB_ASSIGN LEFT ASSIGN RIGHT ASSIGN AND_ASSIGN XOR_ASSIGN 192 9 Shading Language Grammar for Core Profile OR_ASSIGN expression assignment_expressi
65. set to the float argument for all i j and set to 0 for all i 101 5 4 3 5 Operators and Expressions To initialize a matrix by specifying vectors or scalars the components are assigned to the matrix elements in column major order mat2 vec2 vec2 one column per argument mat3 vec3 vec3 vec3 one column per argument mat4 vec4 vec4 vec4 vec4 one column per argument mat3x2 vec2 vec2 vec2 one column per argument dmat2 dvec2 dvec2 dmat3 dvec3 dvec3 dvec3 dmat4 dvec4 dvec4 dvec4 dvec4 mat2 float float first column float float second column mat3 float float float first column float float float second column float float float third column mat4 float float float float first column float float float float second column float float float float third column float float float float fourth column mat2x3 vec2 float first column vec2 float second column dmat2x4 dvec3 double first column double dvec3 second column 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 mat3x3 mat4x4 takes the upper left 3x3 of the mat4x4 mat2x3 mat4x2 takes the upper left 2x2 of the mat4x4 last row is 0 0 mat4x4 mat3x3 puts the mat3x3 in the upper le
66. the stage declaring it then the array is given a size of 1 which is relevant when the array is declared within an interface block that is shared with other stages or the application other unused arrays might be eliminated by the optimizer Shared global scalars must have exactly the same 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 a shared global has multiple initializers the initializers must all be constant expressions and they must all have the same value Otherwise a link time error will result A shared global having only one initializer does not require that initializer to be a constant expression 44 4 3 Storage Qualifiers 4 Variables and Types Variable declarations may have at most one storage qualifier specified in front of the type These are summarized as Storage Qualifier Meaning lt none default gt local read write memory or an input parameter to a function const a variable whose value cannot be changed in linkage into a shader from a previous stage variable is copied in out linkage out of a shader to a subsequent stage variable is copied out attribute compatibility profile only and vertex language only same as in when in a vertex shader uniform value does not change across the primitive be
67. to buffer variables issued within a single shader invocation void memoryBarrierShared Control the ordering of memory transactions to shared variables issued within a single shader invocation Only available in compute shaders void memoryBarrierImage Control the ordering of memory transactions to images issued within a single shader invocation void groupMemoryBarrier Control the ordering of all memory transactions issued within a single shader invocation as viewed by other invocations in the same work group Only available in compute shaders The memory barrier built in functions can be used to order reads and writes to variables stored in memory accessible to other shader invocations When called these functions will wait for the completion of all reads and writes previously performed by the caller that access selected variable types and then return with no other effect The built in functions memoryBarrierAtomicCounter memoryBarrierBuffer memoryBarrierImage and memoryBarrierShared wait for the completion of accesses to atomic counter buffer image and shared variables respectively The built in functions memoryBarrier and groupMemoryBarrier wait for the completion of accesses to all of the above variable types The functions memoryBarrierShared and groupMemoryBarrier are available only in compute shaders the other functions are available in all shader types 186 8 Built in Functi
68. to geometry shader no gl in flat out vec4 gl FrontColor output from geometry shader Ideally these are redeclared as part of the redeclaration of an interface block as described in section 7 1 1 Compatibility Profile Built In Language Variables However for the above purpose they can be redeclared as individual variables at global scope outside an interface block Such redeclarations also allow adding the transform feedback qualifiers xfb_buffer xfb_stride and xfb_offset to output variables Using xfb_buffer on a variable does not change the global default buffer A compile time error will result if a shader has both an interface block redeclaration and a separate redeclaration of a member of that interface block outside the interface block redeclaration If gl Color is redeclared with an interpolation qualifier then g FrontColor and gl BackColor if they are written to must also be redeclared with the same interpolation qualifier and vice versa If gl _SecondaryColor is redeclared with an interpolation qualifier then g FrontSecondaryColor and gl BackSecondaryColor if they are written to must also be redeclared with the same interpolation qualifier and vice versa This qualifier matching on predeclared variables is only required for variables that are statically used within the shaders in a program 86 4 6 4 7 4 7 1 4 Variables and Types Parameter Qualifiers In addition to precision qualifiers and
69. to the formal parameter at call time and the 1 value is used to copy out a value when the function returns The order in which output parameters are copied back to the caller is undefined If the function matching described in the previous section required argument type conversions these conversions are applied at copy in and copy out times In a function writing to an input only parameter is allowed Only the function s copy is modified This can be prevented by declaring a parameter with the const qualifier When calling a function expressions that do not evaluate to l values cannot be passed to parameters declared as out or inout or a compile time error results 116 6 1 2 6 Statements and Structure function prototype precision qualifier type function name parameter qualifiers precision qualifier type name array specifier type any basic type array type structure name or structure definition parameter qualifiers empty list of parameter qualifier parameter qualifier const in out inout precise memory qualifier precision qualifier name empty identifier array specifier empty integral constant expression The const qualifier cannot be used with out or inout or a compile time error results The above is used both for function declarations i e prototypes and for function definitions Hence function definitions can have unnamed arguments Recursion is not allowed not even stati
70. together completely creating one or more of the programmable stages of the OpenGL pipeline All the shaders for a single programmable stage must be within the same program A complete set of programmable stages can be put into a single program or the stages can be partitioned across multiple programs The aim of this document is to thoroughly specify the programming language The OpenGL Graphics System Specification will specify the OpenGL entry points used to manipulate and communicate with programs and shaders Error Handling Compilers in general accept programs that are ill formed due to the impossibility of detecting all ill formed programs Portability is only ensured for well formed programs which this specification describes Compilers are encouraged to detect ill formed programs and issue diagnostic messages but are not required to do so for all cases Compile time errors must be returned for lexically or grammatically incorrect shaders Other errors are reported at compile time or link time as indicated Code that is dead must still be error checked For example 1 5 1 6 1 Introduction if false changing false to true cannot uncover additional errors statement statement must be error checked regardless Typographical Conventions Italic bold and font choices have been used in this specification primarily to improve readability Code fragments use a fixed width font Identifiers embedded in text are italiciz
71. undefined when this exit is non uniform It would typically be used within a conditional statement for example if intensity lt 0 0 discard A fragment shader may test a fragment s alpha value and discard the fragment based on that test However it should be noted that coverage testing occurs after the fragment shader runs and the coverage test can change the alpha value The return jump causes immediate exit of the current function If it has expression then that is the return value for the function The function main can use return This simply causes main to exit in the same way as when the end of the function had been reached It does not imply a use of discard in a fragment shader Using return in main before defining outputs will have the same behavior as reaching the end of main before defining outputs 121 7 Built in Variables 7 1 Built In Language Variables Some OpenGL operations occur in fixed functionality and need to provide values to or receive values from shader executables Shaders communicate with fixed function OpenGL pipeline stages and optionally with other shader executables through the use of built in input and output variables In the compute language the built in variables are declared as follows work group in uvec3 gl const uvec3 gl work group in uvec3 gl in uvec3 gl dimensions _NumWorkGroups _WorkGroupSize and invocation IDs _WorkGroupID _LocalInvocationID de
72. used directly If it is mipmapped and running in a fragment shader the LOD computed by the implementation is used to do the texture lookup If it is mipmapped and running on the vertex shader then the base texture is used Some texture functions non Lod and non Grad versions may require implicit derivatives Implicit derivatives are undefined within non uniform control flow and for non fragment shader texture fetches For Cube forms the direction of P is used to select which face to do a 2 dimensional texture lookup in as described in section 8 13 Cube Map Texture Selection in the OpenGL Graphics System Specification For Array forms the array layer used will be max 0 min d 1 floor layer 0 5 where d is the depth of the texture array and layer comes from the component indicated in the tables below For depth stencil textures the sampler type should match the component being accessed as set through the OpenGL API When the depth stencil texture mode is set to DEPTH COMPONENT a floating point sampler type should be used When the depth stencil texture mode is set to STENCIL_ INDEX an unsigned integer sampler type should be used Doing a texture lookup with an unsupported combination will return undefined values Texture Query Functions The textureSize functions query the dimensions of a specific texture level for a sampler The textureQueryLod functions are available only in a fragment shader They take the com
73. will refer to these languages as a single language The specific languages will be referred to by the name of the processor they target vertex tessellation control tessellation evaluation geometry fragment or compute Most OpenGL state is not tracked or made available to shaders Typically user defined variables will be used for communicating between different stages of the OpenGL pipeline However a small amount of state is still tracked and automatically made available to shaders and there are a few built in variables for interfaces between different stages of the OpenGL pipeline Vertex Processor The vertex processor is a programmable unit that operates on incoming vertices and their associated data Compilation units written in the OpenGL Shading Language to run on this processor are called vertex shaders When a set of vertex shaders are successfully compiled and linked they result in a vertex shader executable that runs on the vertex processor The vertex processor operates on one vertex at a time It does not replace graphics operations that require knowledge of several vertices at a time Tessellation Control Processor The tessellation control processor is a programmable unit that operates on a patch of incoming vertices and their associated data emitting a new output patch Compilation units written in the OpenGL Shading Language to run on this processor are called tessellation control shaders When a set of tessellation con
74. y genDType max genDType x genDType y genDType max genDType x double y genIType max genIType x genIType y genIType max genIType x int y genUType max genUType x genUType y genUType max genUType x uint y 145 8 Built in Functions Description Syntax genType clamp genType x genType minVal genType maxVal genType clamp genType x float minVal float max Val genDType clamp genDType x genDType minVal genDType maxVal genDType clamp genDType x double minVal double maxVal genlType clamp genIType x genIType minVal genIType maxVal genlType clamp genIType x int minVal int maxVal genUType clamp genUType x genUType minVal genUType maxVal genUType clamp genUType x uint minVal uint maxVal Returns min max x minVal maxVal Results are undefined if minVal gt maxVal genType mix genType x genType y genType a genType mix genType x genType y float a genDType mix genDType x genDType y genDType a genDType mix genDType x genDType y double a Returns the linear blend of x and y i e x l a y a 146 8 Built in Functions Syntax Description genType mix genType x genType y genBType a genDType mix genDType x genDType y genBType a Selects which vector each returned component comes from For a component of a that is false the corresponding component of x is returned For a component of a that
75. 1 0 Unsized arrays can be explicitly sized by an initializer at declaration time float a 5 float b a b is explicitly size 5 float b 5 a means the same thing float b float 1 2 3 4 5 also explicitly sizes to 5 However it is a compile time error to assign to an unsized array Note this is a rare case that initializers and assignments appear to have different semantics For arrays of arrays any unsized dimension is explicitly sized by the initializer vec4 a vec4 2 vec4 0 0 vec4 1 0 okay size to a 3 2 37 4 Variables and Types vec4 2 vec4 0 0 vec4 1 0 vec4 2 vec4 0 0 vec4 1 0 Arrays know the number of elements they contain This can be obtained by using the length method float a 5 a length returns 5 This returns a type int If an array has been explicitly sized the value returned by the length method is a constant expression If an array has not been explicitly sized and is not the last declared member of a shader storage block the value returned by the length method is not a constant expression and will be determined when a program is linked If an array has not been explicitly sized and is the last declared member of a shader storage block the value returned will not be a constant expression and will be determined at run time based on the size of the buffer object providing storage for the block For such arrays the value returned by the length
76. 157 8 8 Integer Functions 8 Built in Functions These all operate component wise The description is per component The notation a b means the set of bits from bit number a through bit number b inclusive The lowest order bit is bit 0 Bit number will always refer to counting up from the lowest order bit as bit 0 Syntax Description genUType uaddCarry genUType x genUType y out genUType carry Adds 32 bit unsigned integer x and y returning the sum modulo 2 The value carry is set to 0 if the sum was less than 2 or to 1 otherwise genUType usubBorrow genUType x genUType y out genUType borrow Subtracts the 32 bit unsigned integer y from x returning the difference if non negative or 2 plus the difference otherwise The value borrow is set to 0 if x gt y or to 1 otherwise void umulExtended genUType x genUType y out genUType msb out genUType sb void imulExtended genIType x genIType y out genIType msb out genIType sb Multiplies 32 bit integers x and y producing a 64 bit result The 32 least significant bits are returned in sb The 32 most significant bits are returned in msb genIType bitfieldExtract genIType value int offset int bits genUType bitfieldExtract genUType value int offset int bits Extracts bits offset offset bits 1 from value returning them in the least significant bits of the result For unsigned data types
77. 2 genType log2 genType x Returns the base 2 logarithm of x i e returns the value y which satisfies the equation x 2 Results are undefined if x lt 0 genType sqrt genType x genDType sqrt genDType x Returns Vx Results are undefined if x lt 0 genType inversesqrt genType x genDType inversesqrt genDType x 1 Returns TE Results are undefined if x lt 0 143 8 3 Common Functions 8 Built in Functions These all operate component wise The description is per component Syntax Description genType abs genType x genIType abs genIType x genDType abs genDType x Returns x if x gt 0 otherwise it returns x genType sign genType x genlType sign genIType x genDType sign genDType x Returns 1 0 if x gt 0 0 0 if x 0 or 1 0 if x lt 0 genType floor genType x genDType floor genDType x Returns a value equal to the nearest integer that is less than or equal to x genType trunc genType x genDType trune genDType x Returns a value equal to the nearest integer to x whose absolute value is not larger than the absolute value of x genType round genType x genDType round genDType x Returns a value equal to the nearest integer to x The fraction 0 5 will round in a direction chosen by the implementation presumably the direction that is fastest This includes the possibility that round x returns the same value as round
78. 8 0 2 0 3 0 7 0 pos xx vec2 3 0 4 0 illegal x used twice pos xy vec3 1 0 2 0 3 0 illegal mismatch between vec2 and vec3 To form an I value swizzling must be applied to an value of vector or scalar type contain no duplicate components and it results in an l value of scalar or vector type depending on number of components specified 104 5 6 5 7 5 Operators and Expressions Array subscripting syntax can also be applied to vectors but not to scalars to provide numeric indexing So in vec4 pos pos 2 refers to the third element of pos and is equivalent to pos z This allows variable indexing into a vector as well as a generic way of accessing components Any integer expression can be used as the subscript The first component is at index zero Reading from or writing to a vector using a constant integral expression with a value that is negative or greater than or equal to the size of the vector results in a compile time error When indexing with non constant expressions behavior is undefined if the index is negative or greater than or equal to the size of the vector The length method may be applied to vectors but not scalars The result is the number of components in the vector For example vec3 v const int L v length sets the constant L to 3 The type returned by length on a vector is int and the value returned is a constant expression Matrix Components The components of a m
79. Array sampler int textureQueryLevels sampler DShadow sampler int textureQueryLevels sampler2DShadow sampler int textureQueryLevels samplerCubeShadow sampler int textureQueryLevels sampler DArrayShadow sampler int textureQueryLevels sampler2DArrayShadow sampler int textureQueryLevels samplerCubeArrayShadow sampler Returns the mipmap array s that would be accessed in the x component of the return value Returns the computed level of detail relative to the base level in the y component of the return value If called on an incomplete texture the results are undefined Returns the number of mipmap levels accessible in the texture associated with sampler as defined in the OpenGL Specification The value zero will be returned if no texture or an incomplete texture is associated with sampler Available in all shader stages 163 8 Built in Functions 8 9 2 Texel Lookup Functions Syntax Description gvec4 texture gsampler1D sampler float P float bias Use the texture coordinate P to gvec4 texture gsampler2D sampler vec2 P float bias do a texture lookup in the gvec4 texture gsampler3D sampler vec3 P float bias texture currently bound to gvec4 texture gsamplerCube sampler vec3 P float bias sampler float texture sampler1DShadow sampler vec3 P float bias For shadow forms When float texture sampler2DShadow sampler vec3 P float bias compare is present it is u
80. Even x for all values of x genType roundEven genType x genDType roundEven genDType x Returns a value equal to the nearest integer to x A fractional part of 0 5 will round toward the nearest even integer Both 3 5 and 4 5 for x will return 4 0 genType ceil genType x genDType ceil genDType x Returns a value equal to the nearest integer that is greater than or equal to x genType fract genType x genDType fract genDType x Returns x floor x genType mod genType x float y genType mod genType x genType y genDType mod genDType x double y genDType mod genDType x genDType y Modulus Returns x y floor x y 144 8 Built in Functions Syntax Description genType modf genType x out genType i Returns the fractional part of x and sets i to the integer genDType modf genDType x part as a whole number floating point value Both the out genDType i return value and the output parameter will have the same sign as x genType min genType x genType y Returns y if y lt x otherwise it returns x genType min genType x float y genDType min genDType x genDType y genDType min genDType x double y genIType min genIType x genIType y genIType min genIType x int y genUType min genUType x genUType y genUType min genUType x uint y genType max genType x genType y Returns y if x lt y otherwise it returns x genType max genType x float
81. Gather sampler2DRectShadow sampler vec2 P float refZ Returns the value vec4 Sample 10 j1 P base comp Sample il j1 P base comp Sample _il_j0 P base comp Sample 10 j0 P base comp If specified the value of comp must be a constant integer expression with a value of 0 1 2 or 3 identifying the x y z or w post swizzled component of the four component vector lookup result for each texel respectively If comp is not specified it is treated as 0 selecting the x component of each texel to generate the result gvec4 textureGatherOffset gsampler2D sampler vec2 P ivec2 offset int comp gvec4 textureGatherOffset gsampler2DArray sampler vec3 P ivec2 offset int comp gvec4 textureGatherOffset gsampler2DRect sampler vec2 P ivec2 offset int comp vec4 textureGatherOffset sampler2DShadow sampler vec P float refZ ivec2 offset vec4 textureGatherOffset sampler2DArrayShadow sampler vec3 P float refZ ivec2 offset vec4 textureGatherOffset sampler2DRectShadow sampler vec P float refZ ivec2 offset Perform a texture gather operation as in textureGather by offset as described in textureOffset except that the offset can be variable non constant and the implementation dependent minimum and maximum offset values are given by MIN PROGRAM TEXTURE GATHER OFFSET and MAX PROGRAM TEXTURE GATHER OFFSET respectively 171 8 Built in Functions Syntax
82. L invariant all 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 It is a compile time error to use this pragma in a fragment shader Generally invariance is ensured at the cost of flexibility in optimization so performance can be degraded by use of invariance Hence use of this pragma is intended as a debug aid to avoid individually declaring all output variables as invariant Invariance of Constant Expressions 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 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 whether or not the invariant qualifier is used The Precise Qualifier Some algorithms require floating point computations to exactly follow the order of operations specified in the source code and to treat all operations consistently even if the implementation supports optimizations that could produce nearly equivalent results with higher performance For example many GL implementations support a multiply add instruction that can compute a floating point expression such as result a
83. PLERBUFFER SAMPLERCUBEARRAY SAMPLERCUBEARRAY SHADOW ISAMPLERCUBEARRAY USAMPLERCUBEARRAY SAMPLER2DMS ISAMPLER2DMS USAMPLER2DMS SAMPLER2DMSARRAY ISAMPLER2DMSARRAY USAMPLER2DMSARRAY IMAGE1D IIMAGE1D UIMAGI E2D TIMAGE2D T a 1 UIMAGE2D IMAGE3D IIMAGI H IMAGE2DRECT IIMAGE2DRECT UIMAGE2DRECT IMAGECUBE IIMAGECUBE UIMAGECUBE B 1 2 IMAGEBUFFER IIMAGEBUFFER UIMAGEBUFFER U IMAGE1DARRAY IIMAGE1DARRAY UIMAGE1DARRAY IMAGE2DARRAY IIMAGE2DARRAY UIMAGE2DARRAY IMAGECUBEARRAY IIMAGECUBEARRAY UIMAGECUBEARRAY IMAGE2DMS IIMAGE2DMS UIMAGE2DMS IMAGE2DMSARRAY IIMAGE2DMSARRAY UIMAGE2DMSARRAY T LT GI S GI 188 9 Shading Language Grammar for Core Profile STRUCT VOID WHILE DENTIFIER TYPE NAME I FLOATCONSTANT DOUBLECONSTANT INTCONSTANT UINTCONSTANT BOOLCONSTANT FIELD SELECTION LEFT OP RIGHT OP INC OP DEC OP LE OP GE OP EQ OP NE OP A M S D OP OR OP XOR OP MUL ASSIGN DIV _ ASSIGN ADD ASSIGN OD ASSIGN LEFT ASSIGN RIGHT ASSIGN AND ASSIGN XOR ASSIGN OR ASSIGN UB ASSIG EFT PAREN RIGHT
84. The OpenGL Shading Language Language Version 4 40 Document Revision 9 16 Jun 2014 Editor John Kessenich LunarG Version 1 1 Authors John Kessenich Dave Baldwin Randi Rost Copyright c 2008 2014 The Khronos Group Inc All Rights Reserved This specification is protected by copyright laws and contains material proprietary to the Khronos Group Inc It or any components may not be reproduced republished distributed transmitted displayed broadcast or otherwise exploited in any manner without the express prior written permission of Khronos Group You may use this specification for implementing the functionality therein without altering or removing any trademark copyright or other notice from the specification but the receipt or possession of this specification does not convey any rights to reproduce disclose or distribute its contents or to manufacture use or sell anything that it may describe in whole or in part Khronos Group grants express permission to any current Promoter Contributor or Adopter member of Khronos to copy and redistribute UNMODIFIED versions of this specification in any fashion provided that NO CHARGE is made for the specification and the latest available update of the specification for any version of the API is used whenever possible Such distributed specification may be re formatted AS LONG AS the contents of the specification are not changed in any way The specification may be incorporated into a produc
85. USAMPLER2DMSARRAY IMAGE1D UMAGEID UIMAGEID IMAGE2D IIMAGE2D UIMAGE2D IMAGE3D IIMAGE3D UIMAGE3D IMAGE2DRECT IIMAGE2DRECT UIMAGE2DRECT IMAGECUBE IIMAGECUBE UIMAGECUBE IMAGEBUFFER IIMAGEBUFFER UIMAGEBUFFER IMAGEIDARRAY IIMAGEIDARRAY UIMAGEIDARRAY IMAGE2DARRAY IIMAGE2DARRAY UIMAGE2DARRAY IMAGECUBEARRAY IIMAGECUBEARRAY UIMAGECUBEARRAY IMAGE2DMS IIMAGE2DMS UIMAGE2DMS IMAGE2DMSARRAY IIMAGE2DMSARRAY UIMAGE2DMSARRAY struct_specifier TYPE_NAME precision_qualifier HIGH_PRECISION 199 9 Shading Language Grammar for Core Profile MEDIUM PRECISION LOW _PRECISION struct_specifier STRUCT IDENTIFIER LEFT BRACE struct_declaration_list RIGHT BRACE STRUCT LEFT BRACE struct_declaration_list RIGHT BRACE struct declaration list struct_declaration struct_ declaration list struct_ declaration struct_declaration type specifier struct_declarator_ list SEMICOLON type qualifier type _specifier struct_declarator_list SEMICOLON struct_declarator _list struct_declarator struct_declarator_list COMMA struct_declarator struct_declarator IDENTIFIER IDENTIFIER array _specifier initializer assignment_expression LEFT BRACE initializer_list RIGHT BRACE LEFT BRACE initializer_list COMMA RIGHT BRACE initializer_list initializer initializer_list COMMA initializer declaration_statement declaration statement compound_statement simple_statement Grammar Note labeled statements for SWITCH only goto is no
86. XTURE MIN FILTER is LINEAR or NEAREST TEXTURE MIN FILTER is NEAREST MIPMAP NEAREST or LINEAR MIPMAP NEAREST 1 0 else return computedLod The value maxAccessibleLevel is the level number of the smallest accessible level of the mipmap array the value q in section 8 14 3 Mipmapping of the OpenGL Graphics System Specification minus the base level Syntax Description int textureSize gsampler1D sampler int lod ivec2 textureSize gsampler2D sampler int lod ivec3 textureSize gsampler3D sampler int lod ivec2 textureSize gsamplerCube sampler int lod int textureSize sampler DShadow sampler int lod ivec2 textureSize sampler2DShadow sampler int lod ivec2 textureSize samplerCubeShadow sampler int lod ivec3 textureSize gsamplerCubeArray sampler int lod ivec3 textureSize samplerCubeArrayShadow sampler int lod ivec2 textureSize gsampler2DRect sampler ivec2 textureSize sampler2DRectShadow sampler ivec2 textureSize gsampler DArray sampler int lod ivec3 textureSize gsampler2DArray sampler int lod ivec2 textureSize sampler DArrayShadow sampler int lod ivec3 textureSize sampler2DArrayShadow sampler int lod int textureSize gsamplerBuffer sampler ivec2 textureSize gsampler2DMS sampler ivec3 textureSize gsampler2DMSArray sampler Returns the dimensions of level lod if present for the texture bound to sampler as described
87. _even_spacing signifying that edges should be divided into an even number of equal length segments plus two additional shorter fractional segments fractional_odd_spacing signifying that edges should be divided into an odd number of equal length segments plus two additional shorter fractional segments A third subset of these identifiers ordering specifies whether the tessellation primitive generator produces triangles in clockwise or counter clockwise order according to the coordinate system depicted in the OpenGL specification The ordering identifiers cw and cew indicate clockwise and counter clockwise triangles respectively If the tessellation primitive generator does not produce triangles ordering is ignored Finally point mode is specified with the identifier point_mode indicating the tessellation primitive generator should produce a point for each distinct vertex in the subdivided primitive rather than generating lines or triangles Any or all of these identifiers may be specified one or more times in a single input layout declaration If primitive mode vertex spacing or ordering is declared more than once in the tessellation evaluation shaders of a program all such declarations must use the same identifier At least one tessellation evaluation shader compilation unit in a program must declare a primitive mode in its input layout Declaring vertex spacing ordering or point mode identifiers is optional It is not require
88. _list COMMA IDENTIFIER array_specifier init_declarator_list COMMA IDENTIFIER array_specifier EQUAL initializer init_declarator_list COMMA IDENTIFIER EQUAL initializer single_declaration fully_specified_type fully_specified_type IDENTIFIER fully_specified_type IDENTIFIER array_specifier fully_specified_type IDENTIFIER array_specifier EQUAL initializer fully_specified_type IDENTIFIER EQUAL initializer Grammar Note No enum or typedef fully_specified_type type_specifier type_qualifier type_specifier invariant_qualifier INVARIANT interpolation_ qualifier 194 9 Shading Language Grammar for Core Profile SMOOTH FLAT NOPERSPECTIVE layout_qualifier LAYOUT LEFT PAREN layout qualifier id list RIGHT PAREN layout_qualifier_id_ list layout_qualifier_id layout_qualifier_id_list COMMA layout_qualifier_id layout_qualifier_id IDENTIFIER IDENTIFIER EQUAL constant_expression SHARED precise_qualifier PRECISE type_qualifier single_type_qualifier type_qualifier single_type_qualifier single_type_qualifier storage_qualifier layout_qualifier precision_qualifier interpolation_qualifier invariant_qualifier precise_qualifier storage_qualifier CONST INOUT IN OUT CENTROID PATCH SAMPLE 195 9 Shading Language Grammar for Core Profile UNIFORM BUFFER SHARED COHERENT VOLATILE RESTRICT READONLY WRITEONLY SUBROUTINE SUBROUTINE LEFT _PAREN type name list RIGHT_PAREN type name li
89. a Lien AE 23 Dict Statie USE eiia re AO D EOE een 24 3 8 2 Uniform and Non Uniform Control Flow 24 3 8 3 Dynamically Uniform ER DTESSLDR nissan 24 4 Vanables and Types oozes ease ie ed ea en a 25 4 1 Basic Types prr enea E A A EEE eine 25 a ee A E E ee Co S 29 D erra E AE E a ee A EREL tnt 29 A DA ER TEACS APE PR ee RS EEE TT E O eet rere rere 29 4 A FEloa ng Point VatableS ireira i E EET R E R 31 AS N O E E E E D LE E E 32 Da de de aida nt rA eaat 32 ill 417 ODA RER neue dense ea andere 417l Samplet So acca ct htl piace tenes tana R aE AA Ns Tot RAS oi sczsnensadnscnvsaianiassaseanaaoansiesadaaudcsesainawa sane scinlesnsneuataxs ia sansad veunuaaiitueniaeuandeennes 4 1 7 3 Atomic A OUMIPCIR 05s seuseisieecnantsdnadeondsaonsaascausiededenowdaqshoodnbad shontaqn Seudeipbacsaanieauseuanee AlS SUCUT E S EP PS Gesu cbioanyencterexeasstraievs qundeschiseadeadvoressacesceta tote en ne ee a du ie meee ALTO Implicit Conversions jjis e aai E E E EEEE EEEa AT TaS re e ae a a a de E AEE EEEE 4 2 OO a ba E a O encoder RSS LUN AL LEUR E eee 4 3 1 Default Stort ge QUE norm ment 4 3 2 Const nt Qualifier een amant re ont 4 3 3 Constant EXP ESSiOnS sni e E E N REE TA A RS 4 3 4 laput Si iA AACS sereine i a E A E 4 3S EG Den 8 V AD Le 1 43 0 Q tp t Variables ER EEEE EEEE EEE ERES 4 3 1 Buffer AA LL Le SP TE ER ia e R E ae eK 4 3 8 Shared VIe dan nid st nn EEEa E AEE adda 4 3 9 Interface BENG CES sa sssinnisainiense
90. ables will be visible to other shader processors executing the same shader within the same local work group Order of execution with respect to 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 memory barriers must be employed using the barrier function see section 8 16 Shader Invocation Control Functions There is a limit to the total size of all variables declared as shared in a single program This limit expressed in units of basic machine units may be determined by using the OpenGL API to query the value of MAX COMPUTE SHARED MEMORY SIZE Interface Blocks 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 block of buffer variables called 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 54 4 Variables and Types An int
91. ader which are allowed to have component aliasing This vertex variable component aliasing is intended only to support vertex shaders where each execution path accesses at most one input per each aliased component Implementations are permitted but not required to generate link time errors if they detect that every path through the vertex shader executable accesses multiple inputs aliased to any single component Tessellation Evaluation Inputs Additional input layout qualifier identifiers allowed for tessellation evaluation shaders are 64 4 Variables and Types layout qualifier id triangles quads isolines equal spacing fractional even _spacing fractional odd_ spacing cw cew point_mode One subset of these identifiers primitive mode is used to specify a tessellation primitive mode to be used by the tessellation primitive generator To specify a primitive mode the identifier must be one of triangles quads or isolines which specify that the tessellation primitive generator should subdivide a triangle into smaller triangles a quad into triangles or a quad into a collection of lines respectively A second subset of these identifiers vertex spacing is used to specify the spacing used by the tessellation primitive generator when subdividing an edge To specify vertex spacing the identifier must be one of the following equal spacing signifying that edges should be divided into a collection of equal sized segments fractional
92. aders of a different version or a link time error will result When linking shaders of versions allowed by these rules remaining link time errors will be given as per the linking rules in the GLSL version corresponding to the version of the context the shaders are linked under Shader compile time errors must still be given strictly based on the version declared or defaulted to within each shader Unless otherwise specified this specification is documenting the core profile and everything specified for the core profile is also available in the compatibility profile Features specified as belonging specifically to the compatibility profile are not available in the core profile There is a built in macro definition for each profile the implementation supports All implementations provide the following macro define GL_core profile 1 Implementations providing the compatibility profile provide the following macro define GL compatibility profile 1 Implementations providing the es profile provide the following macro define GL_es profile 1 The version directive must occur in a shader before anything else except for comments and white space 18 3 Basics By default compilers of this language must issue compile time lexical and grammatical errors for shaders that do not conform to this specification Any extended behavior must first be enabled Directives to control the behavior of the compiler with respect to extensions are decla
93. age qualifier will qualify the opaque handle while the memory qualifier will qualify the object it is a handle to Samplers Sampler types e g sampler2D are opaque types declared and behaving as described above for opaque types When aggregated into arrays within a shader samplers can only be indexed with a dynamically uniform integral expression otherwise results are undefined Sampler variables are handles to one two and three dimensional textures cube maps depth textures shadowing etc as enumerated in the basic types tables There are distinct sampler types for each texture target and for each of float integer and unsigned integer data types Texture accesses are done through built in texture functions described in section 8 9 Texture Functions and samplers are used to specify which texture to access and how it is to be filtered Images Image types are opaque types declared and behaving as described above for opaque types They can be further qualified with memory qualifiers When aggregated into arrays within a shader images can only be indexed with a dynamically uniform integral expression otherwise results are undefined 33 4 1 7 3 4 Variables and Types Image variables are handles to one two or three dimensional images corresponding to all or a portion of a single level of a texture image bound to an image unit There are distinct image types for each texture target and for each of float integ
94. al for inputs and outputs Bug 11178 Correct function overloading examples which were from a different revision of the spec than the current rules Bug 10593 Clarify that within a declaration if inout is used neither in nor out may be used and none of these can be repeated Bug 11052 Make type matching across compilation units in the same program apply to all declared variables not just those statically used etc Bug 10941 When accessing the same packed buffer across multiple stages in the same program it either works or you get a link error 1 2 3 1 2 4 1 Introduction Changes since revision 6 of GLSL version 4 40 Deprecation Bug 384 Noise is now o defined to return 0 and o deprecated not removed Changes Bug 10628 Subroutine arrays now require the index to be dynamically uniform Bug 10440 Refine the link time error Within an 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 Bug 10713 Update the offset align example in section 4 4 5 to adhere to the std140 alignment requirements A few other examples corrected Changed o gl MaxComputeAtomicCounterBuffers to 8 and o gl MaxCombinedTexturelmageUnits to 96 Clarifications Bug 10655 Clarification that opaque types e g samplers can be in a uniform e g member in a Struct not just a non aggregate unif
95. alifier are performed coherently with similar accesses from other shader invocations In particular when reading a variable declared as coherent the values returned will reflect the results of previously completed writes performed by other shader invocations When writing a variable declared as coherent the values written will be reflected in subsequent coherent reads performed by other shader invocations As described in section 7 11 Shader Memory Access of the OpenGL Specification shader memory reads and writes complete in a largely undefined order The built in function memoryBarrier can be used if needed to guarantee the completion and relative ordering of memory accesses performed by a single shader invocation When accessing memory using variables not declared as coherent the memory accessed by a shader may be cached by the implementation to service future accesses to the same address Memory stores may be cached in such a way that the values written might not be visible to other shader invocations accessing the same memory The implementation may cache the values fetched by memory reads and return the same values to any shader invocation accessing the same memory even if the underlying memory has been modified since the first memory read While variables not declared as coherent might not be useful for communicating between shader invocations using non coherent accesses may result in higher performance Memory accesses to image variab
96. all components members or elements of one operand must equal the corresponding components members or elements in the other operand for the operands to be considered equal To get a vector of component wise equality results for vectors use the built in functions equal and notEqual The logical binary operators and amp amp or and exclusive or operate only on two Boolean expressions and result in a Boolean expression And amp amp will only evaluate the right hand operand if the left hand operand evaluated to true Or will only evaluate the right hand operand if the left hand operand evaluated to false Exclusive or will always evaluate both operands The logical unary operator not It operates only on a Boolean expression and results in a Boolean expression To operate on a vector use the built in function not The sequence operator that operates on expressions by returning the type and value of the right most expression in a comma separated list of expressions All expressions are evaluated in order from left to right The ternary selection operator It operates on three expressions exp exp2 exp3 This operator evaluates the first expression which must result in a scalar Boolean If the result is true it selects to evaluate the second expression otherwise it selects to evaluate the third expression Only one of the second and third expressions is evaluated The second and third expressio
97. ample function prototypes A B and C above the following examples show how the rules apply to different sets of calling argument types f vec4 vec4 exact match of vec4 f in vec4 x out vec4 y f vec4 uvec4 exact match of vec4 f in vec4 x out uvec4 y f vec4 ivec4 matched to vec4 f in vec4 x out vec4 y C not relevant can t convert vec4 to ivec4 A better than B for 2nd ff argument rule 3 same on first argument f ivec4 vec4 NOT matched All three match by implicit les conversion C is better than A and B 14 on the first argument A is better than B and C User defined functions can have multiple declarations but only one definition A shader can redefine built in functions If a built in function is redeclared in a shader i e a prototype is visible before a call to it then the linker will only attempt to resolve that call within the set of shaders that are linked with it The function main is used as the entry point to a shader executable A shader need not contain a function named main but one shader in a set of shaders linked together to form a single shader executable must or a link time error results This function takes no arguments returns no value and must be declared as type void void main The function main can contain uses of return See section 6 4 Jumps for more details It is a compile time or link time error to declare or defin
98. and outputs This outer array level is removed from the type before considering how many locations the type consumes If a vertex shader input is any scalar or vector type it will consume a single location If a non vertex shader input is a scalar or vector type other than dvec3 or dvec4 it will consume a single location while types dvec3 or dvec4 will consume two consecutive locations Inputs of type double and dvec2 will consume only a single location in all stages If the declared input after potentially removing an outer array level as just described above is an array of size n and each element takes m locations it will be assigned m n consecutive locations starting with the location specified For example layout location 6 in vec4 colors 3 will establish that the shader input colors is assigned to vector location numbers 6 7 and 8 If the declared input is an n x m single or double precision 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 layout location 9 in mat4 transforms 2 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 loca
99. ariable in its condition expression The variable s scope lasts only until the end of the sub statement that forms the body of the loop Loops can be nested Non terminating loops are allowed The consequences of very long or non terminating loops are platform dependent Jumps These are the jumps jump_statement continue break return return expression discard in the fragment shader language only There is no goto nor other non structured flow of control The continue jump is used only in loops It skips the remainder of the body of the inner most loop of which it is inside For while and do while loops this jump is to the next evaluation of the loop condition expression from which the loop continues as previously defined For for loops the jump is to the Joop expression followed by the condition expression The break jump can also be used only in loops and switch statements It is simply an immediate exit of the inner most loop or switch statements containing the break No further execution of condition expression loop expression or switch statement is done The discard keyword is only allowed within fragment shaders It can be used within a fragment shader to abandon the operation on the current fragment This keyword causes the fragment to be discarded and no updates to any buffers will occur Control flow exits the shader and subsequent implicit or explicit 120 6 Statements and Structure derivatives are
100. ariables to the current output primitive on stream stream The argument to stream must be a constant integral expression On return from this call the values of all output variables are undefined Can only be used if multiple output streams are supported void EndStreamPrimitive int stream Completes the current output primitive on stream stream and starts a new one The argument to stream must be a constant integral expression No vertex is emitted Can only be used if multiple output streams are supported void EmitVertex Emits the current values of output variables to the current output primitive On return from this call the values of output variables are undefined When multiple output streams are supported this is equivalent to calling EmitStreamVertex 0 void EndPrimitive Completes the current output primitive and starts a new one No vertex is emitted When multiple output streams are supported this is equivalent to calling EndStreamPrimitive 0 The function EmitStreamVertex specifies that a vertex is completed A vertex is added to the current output primitive in vertex stream stream using the current values of all built in and user defined output variables associated with stream The values of all output variables for all output streams are undefined after a call to EmitStreamVertex If a geometry shader invocation has emitted more vertices than permitted by the output layout qualifier m
101. at double converts a double value to a float double int converts a signed integer value to a double double uint converts an unsigned integer value to a double double bool converts a Boolean value to a double double float converts a float value to a double 99 5 4 2 5 Operators and Expressions When constructors are used to convert any 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 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 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 Vector and Matrix Constructors Constructors can be used to create vectors or matrices
102. at those that include a location use the same location Output Variables Shader output variables are declared with a storage qualifier using the storage qualifier out They form the output interface between the declaring shader and the subsequent stages of the OpenGL 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 at global scope 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
103. atch size The intrinsically declared tessellation control output array gl_out will also be sized by any output layout declaration Hence the expression gl_out length will return the output patch vertex count specified in a previous output layout qualifier For outputs declared without an array size including intrinsically declared outputs 1 e gl_out a layout must be must be declared before any use of the method length or other array use requires its size to be known It is a compile time error if the output patch vertex count specified in an output layout qualifier does not match the array size specified in any output variable declaration in the same shader All tessellation control shader layout declarations in a program must specify the same output patch vertex count There must be at least one layout qualifier specifying an output patch vertex count in any program containing tessellation control shaders however such a declaration is not required in all tessellation control shaders Geometry Outputs Geometry shaders can have three additional types of output layout identifiers an output primitive type a maximum output vertex count and per output stream numbers The primitive type and vertex count identifiers are allowed only on the interface qualifier out not on an output block block member or variable declaration The stream identifier is allowed on the interface qualifier out on output blocks and on variable declarat
104. atement must be a scalar int or uint The type of the constant expression value in a case label also must be a scalar int or uint When any pair of these values is tested for equal value and the types do not match an implicit conversion will be done to convert the int to a uint see section 4 1 10 Implicit Conversions before the compare is done If a case label has a constant expression of equal value to init expression execution will continue after that label It is a compile time error to have two case label constant expression of equal value Otherwise if there is a default label execution will continue after that label Otherwise execution skips the rest of the switch statement It is a compile time error to have more than one default A break statement not nested in a loop or other switch statement either not nested or nested only in if or if else statements will also skip the rest of the switch statement Fall through labels are allowed No statements are allowed in a switch statement before the first case statement No case or default labels can be nested inside other statement or compound statement within their corresponding switch Iteration For while and do loops are allowed as follows for init expression condition expression loop expression sub statement while condition expression sub statement do statement while condition expression See section 9 Shading Language Grammar for the definitive specif
105. ating point signed integer or unsigned integer sampler matching the basic type of the return type as described above For shadow forms the sampler parameter is a shadow type a depth comparison lookup on the depth texture bound to sampler is done as described in section 8 22 Texture Comparison Modes of the OpenGL Graphics System Specification See the table below for which component specifies D The texture bound to sampler must be a depth texture or results are undefined If a non shadow texture call is made to a sampler that represents a depth texture with depth comparisons turned on then results are undefined If a shadow texture call is made to a sampler that represents a depth texture with depth comparisons turned off then results are undefined If a shadow texture call is made to a sampler that does not represent a depth texture then results are undefined 160 8 9 1 8 Built in Functions In all functions below the bias parameter is optional for fragment shaders The bias parameter is not accepted in any other shader stage For a fragment shader if bias is present it is added to the implicit level of detail prior to performing the texture access operation No bias or lod parameters for rectangle textures multi sample textures or texture buffers are supported because mipmaps are not allowed for these types of textures The implicit level of detail is selected as follows For a texture that is not mipmapped the texture is
106. ation 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 bool success declare success to be a Boolean bool done false declare and initialize done The right side of the assignment operator must be an expression whose type is bool Expressions used for conditional jumps if for while do while must evaluate to the type bool Integers Signed and unsigned integer variables are fully supported In this document the term integer is meant to generally include both signed and unsigned integers Unsigned integers have exactly 32 bits of precision Signed integers use 32 bits including a sign bit in two s complement form Addition subtraction and shift operations resulting in overflow or underflow will not cause any exception nor will they saturate rather they will wrap to yield the low order 32 bits of the result Division and multiplication operations resulting in overflow or underflow will not cause any exception but will result in an undefined value Integers are declared and optionally initialized with integer expressions as in the following example int i j 42 default integer literal type is int uint k 3u u establishes the type as uint 29
107. atrix basic type with double precision components 140 8 1 8 Built in Functions Angle and Trigonometry Functions Function parameters specified as angle are assumed to be in units of radians In no case will any of these functions result in a divide by zero error If the divisor of a ratio is 0 then results will be undefined These all operate component wise The description is per component Syntax Description genType radians genType degrees TT Converts degrees to radians i e T80 degrees genT ype degrees genType radians 180 Converts radians to degrees i e en radians genType sin genType angle The standard trigonometric sine function genType cos genType angle The standard trigonometric cosine function genType tan genType angle The standard trigonometric tangent genType asin genType x Arc sine Returns an angle whose sine is x The range Riots TT of values returned by this function is 5 Results are undefined if x gt 1 genType acos genType x Arc cosine Returns an angle whose cosine is x The range of values returned by this function is 0 x Results are undefined if x gt 1 genType atan genType y genType x Arc tangent Returns an angle whose tangent is y x The signs of x and y are used to determine what quadrant the angle is in The range of values returned by this function is 1 71t Results are undefined if x
108. atrix can be accessed using array subscripting syntax Applying a single subscript to a matrix treats the matrix as an array of column vectors and selects a single column whose type is a vector of the same size as the matrix The leftmost column is column 0 A second subscript would then operate on the resulting vector as defined earlier for vectors Hence two subscripts select a column and then a row mat4 m m 1 vec4 2 0 sets the second column to all 2 0 m 0 0 1 0 sets the upper left element to 1 0 m 2 3 2 0 sets the 4th element of the third column to 2 0 Behavior is undefined when accessing a component outside the bounds of a matrix with a non constant expression It is a compile time error to access a matrix with a constant expression that is outside the bounds of the matrix The length method may be applied to matrices The result is the number of columns of the matrix For example mat3x4 v const int L v length sets the constant L to 3 The type returned by length on a matrix is int and the value returned is a constant expression Structure and Array Operations The members of a structure and the length method of an array are selected using the period 105 5 8 5 Operators and Expressions In total only the following operators are allowed to operate on arrays and structures as whole entities field selector equality assignment indexing arrays o
109. ax_vertices the results of calling EmitStreamVertex are undefined The function EndStreamPrimitive specifies that the current output primitive for vertex stream stream is completed and a new output primitive of the same type will be started by any subsequent EmitStreamVertex This function does not emit a vertex If the output layout is declared to be points calling EndStreamPrimitive is optional A geometry shader starts with an output primitive containing no vertices for each stream When a geometry shader terminates the current output primitive for each stream is automatically completed It is not necessary to call EndStreamPrimitive if the geometry shader writes only a single primitive 183 8 Built in Functions Multiple output streams are supported only if the output primitive type is declared to be points A program will fail to link if it contains a geometry shader calling EmitStreamVertex or EndStreamPrimitive if its output primitive type is not points 184 8 16 8 Built in Functions Shader Invocation Control Functions The shader invocation control function is available only in tessellation control shaders and compute shaders It is used to control the relative execution order of multiple shader invocations used to process a patch in the case of tessellation control shaders or a local work group in the case of compute shaders which are otherwise executed with an undefined relative order Syntax
110. ayout xfb offset 0 vec3 g okay increasing order not required When no xfb_stride is specified for a buffer the stride of the buffer will be the smallest needed to hold the variable placed at the highest offset including any required padding For example if there no other declarations for buffer 3 it has stride 32 layout xfb buffer 3 out block4 layout xfb offset 0 vec4 e layout xfb offset 16 vec4 f The resulting stride implicit or explicit when divided by 4 must be less than or equal to the implementation dependent constant g MaxTransformFeedbackInterleavedComponents 4 4 2 2 Tessellation Control Outputs Other than for the transform feedback layout qualifiers tessellation control shaders allow output layout qualifiers only on the interface qualifier out not on an output block block member or variable 73 4 4 2 3 4 Variables and Types declaration The output layout qualifier identifiers allowed for tessellation control shaders include the vertex count layout qualifier layout qualifier id vertices integer constant expression The identifier vertices specifies the number of vertices in the output patch produced by the tessellation control shader which also specifies the number of times the tessellation control shader is invoked It is a compile or link time error for the output vertex count to be less than or equal to zero or greater than the implementation dependent maximum p
111. cally Static recursion is present if the static function call graph of a program contains cycles This includes all potential function calls through variables declared as subroutine uniform described below It is a compile time or link time error if a single compilation unit shader contains either static recursion or the potential for recursion through subroutine variables Subroutines Subroutines provide a mechanism allowing shaders to be compiled in a manner where the target of one or more function calls can be changed at run time without requiring any shader recompilation For example a single shader may be compiled with support for multiple illumination algorithms to handle different kinds of lights or surface materials An application using such a shader may switch illumination algorithms by changing the value of its subroutine uniforms To use subroutines a subroutine type is declared one or more functions are associated with that subroutine type and a subroutine variable of that type is declared The function currently assigned to the variable function is then called by using function calling syntax replacing a function name with the name of the subroutine variable Subroutine variables 117 6 2 6 Statements and Structure are uniforms and are assigned to specific functions only through commands UniformSubroutinesuiv in the OpenGL API Subroutine types are declared using a statement similar to a function declaration with the s
112. cessed This variable is in the range 0 to gl NumSamples 1 where gl_ NumSamples is the total number of samples in the framebuffer or if rendering to a non multisample framebuffer Any static use of this variable in a fragment shader causes the entire shader to be evaluated per sample The input variable gl SamplePosition contains the position of the current sample within the multi sample draw buffer The x and y components of g _ SamplePosition contain the sub pixel coordinate of the current sample and will have values in the range 0 0 to 1 0 Any static use of this variable in a fragment shader causes the entire shader to be evaluated per sample The gi PerVertex block can be redeclared in a shader to explicitly indicate what subset of the fixed pipeline interface will be used This is necessary to establish the interface between multiple programs For example out gl PerVertex vec4 gl Position will use gl_Position float gl PointSize will use gl_PointSize vec4 t error only gl_PerVertex members allowed no other members of gl PerVertex will be used This establishes the output interface the shader will use with the subsequent pipeline stage It must be a subset of the built in members of g PerVertex Such a redeclaration can also add the invariant qualifier 129 7 1 1 7 Built in Variables interpolation qualifiers and the layout qualifiers xfb_ offset xfb_buffer and xfb_stride It can also add an array siz
113. ch against inputs in a subsequent shader stage even if that shader is in a different program object If a declared output is a scalar or vector type other than dvec3 or dvec4 it will consume a single location Outputs of type dvec3 or dvec4 will consume two consecutive locations Outputs of type double and dvec2 will consume only a single location in all stages If the declared output is an array it will be assigned consecutive locations starting with the location specified For example layout location 2 out vec4 colors 3 will establish that colors is assigned to vector location numbers 2 3 and 4 If the declared output is an n x m single or double precision 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 but not on individual members Location layout qualifiers may not be used on output blocks or output block members Compile time err
114. clared 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 Fragment shader inputs get per fragment values typically interpolated from a previous stage s outputs They are declared in fragment shaders with the in storage qualifier The auxiliary storage qualifiers centroid and sample can also be applied as well as the interpolation qualifiers flat noperspective and smooth It is a compile time error to declare a fragment shader input containing any of the following e A Boolean type bool bvec2 bvec3 bvec4 e An opaque type Fragment shader inputs that are signed or unsigned integers integer vectors or any double precision floating point type must be qualified with the interpolation qualifier flat 49 4 3 5 4 Variables and Types Fragment inputs are declared as in the following examples in vec3 normal centroid in vec2 TexCoord invariant centroid in vec4 Color noperspective in float tempe
115. code sequence within one shader in vec4 Colorl legal size still unknown in vec4 Color2 2 legal size is 2 in vec4 Color3 3 illegal input sizes are inconsistent layout lines in legal for Color2 input size is 2 matching Color2 in vec4 Color4 3 illegal contradicts layout of lines layout lines in legal matches other layout declaration layout triangles in illegal does not match earlier layout declaration It is a link time error if not all provided sizes sized input arrays and layout size match across all geometry shaders in a program Fragment Shader Inputs Additional fragment layout qualifier identifiers include the following for gl FragCoord layout qualifier id origin_upper_left pixel_center_integer By default g FragCoord assumes a lower left origin for window coordinates and assumes pixel centers are located at half pixel coordinates For example the x y location 0 5 0 5 is returned for the lower left most pixel in a window The origin can be changed by redeclaring gl FragCoord with the origin_upper_left identifier moving the origin of g FragCoord to the upper left of the window with y increasing in value toward the bottom of the window The values returned can also be shifted by half a pixel in both x and y by pixel_center_integer so it appears the pixels are centered at whole number pixel offsets This moves the x y value returned by g FragCoord of 0 5 0 5 by default
116. cution of the barrier must be dynamically uniform expressions This ensures that if any shader invocation enters a conditional statement then all invocations will enter it While compilers are encouraged to give warnings if they can detect this might not happen compilers cannot completely determine this Hence it is the author s responsibility to ensure barrier only exists inside uniform flow control Otherwise some shader invocations will stall indefinitely waiting for a barrier that is never reached by other invocations 185 8 17 8 Built in Functions Shader Memory Control Functions Shaders of all types may read and write the contents of textures and buffer objects using image variables While the order of reads and writes within a single shader invocation is well defined the relative order of reads and writes to a single shared memory address from multiple separate shader invocations is largely undefined The order of memory accesses performed by one shader invocation as observed by other shader invocations is also largely undefined but can be controlled through memory control functions Syntax Description void memoryBarrier Control the ordering of memory transactions issued by a single shader invocation void memoryBarrierAtomicCounter Control the ordering of accesses to atomic counter variables issued by a single shader invocation void memoryBarrierBuffer Control the ordering of memory transactions
117. d in section 15 2 4 Early Fragment Tests of the OpenGL Specification For example layout early fragment_tests in Specifying this will make per fragment tests be performed before fragment shader execution If this is not declared per fragment tests will be performed after fragment shader execution Only one fragment shader compilation unit need declare this though more than one can If at least one declares this then it is enabled Compute Shader Inputs There are no layout location qualifiers for compute shader inputs Layout qualifier identifiers for compute shader inputs are the work group size qualifiers layout qualifier id local_size_x integer constant expression local_size_y integer constant expression local_size_z integer constant expression The local_size_x local_size_y and local_size_z qualifiers are used to declare a fixed local group size by the compute shader in the first second and third dimension respectively The default size in each dimension is 1 If a shader does not specify a size for one of the dimensions that dimension will have a size of 1 68 4 4 2 4 Variables and Types For example the following declaration in a compute shader layout local size x 32 local size y 32 in is used to declare a two dimensional compute shader with a local size of 32 X 32 elements which is equivalent to a three dimensional compute shader where the third dimension has size one As another example
118. d that all tessellation evaluation shaders in a program declare a primitive mode If spacing or vertex ordering declarations are omitted the tessellation primitive generator will use equal spacing or counter clockwise vertex ordering respectively If a point mode declaration is omitted the tessellation primitive generator will produce lines or triangles according to the primitive mode 65 4 Variables and Types 4 4 1 2 Geometry Shader Inputs Additional layout qualifier identifiers for geometry shader inputs include primitive identifiers and an invocation count identifier layout qualifier id points lines lines_adjacency triangles triangles_adjacency invocations integer constant expression The identifiers points lines lines_adjacency triangles and triangles_adjacency are used to specify the type of input primitive accepted by the geometry shader and only one of these is accepted At least one geometry shader compilation unit in a program must declare this input primitive layout and all geometry shader input layout declarations in a program must declare the same layout It is not required that all geometry shaders in a program declare an input primitive layout The identifier invocations is used to specify the number of times the geometry shader executable is invoked for each input primitive received Invocation count declarations are optional If no invocation count is declared in any geometry shader in a program the geometry s
119. der 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 1 At the beginning of execution 2 At each synchronization point unless e the value was well defined after the previous synchronization point and was not written by any invocation since or e the value was written by exactly one shader invocation since the previous synchronization 52 4 3 7 4 Variables and Types point or e the value was written by multiple shader invocations since the previous synchronization point and the last write performed by all such invocations wrote the same value 3 When read by a shader invocation if e the value was undefined at the previous synchronization point and has not been writen by the same shader invocation since or e the output variable is written to by any other shader invocation between the previous and next synchronization points even if that assignment occurs in code following the read Fragment outputs output per fragment data and are declared using the out storage qualifier It is a compile time error to use auxiliary storage qualifiers or interpolation qualifiers on an output in a fragment shader It is a compile time error to declare a fragment shader output that contains any of the following e A Boolean type bool bvec2 bvec3 bvec4 e A double precision scalar or vector double dvec2 dvec3 dvec4 e An opaque type e Any mat
120. der should be drawn Primitives generated by the geometry shader will undergo viewport transformation and scissor testing using the viewport transformation and scissor rectangle selected by the value of g ViewportIndex The viewport index used will come from one of the vertices in the primitive being shaded However which vertex the viewport index comes from is implementation dependent so it is best to use the same viewport index for all vertices of the primitive If a geometry shader does not assign a value to g Viewportindex viewport transform and scissor rectangle zero will be used If a geometry shader statically assigns a value to gl ViewportIndex and there is a path through the shader that does not assign a value to g Viewportindex the value of gl ViewportIndex is undefined for executions of the shader that take that path See section 11 3 4 6 Layer and Viewport Selection of the OpenGL Graphics System Specification Core Profile for more information The input variable gl ViewportIndex in the fragment stage will have the same value that was written to the output variable g ViewportIndex in the geometry stage If the geometry stage does not dynamically assign to gl ViewportIndex the value of gl_ViewportIndex in the fragment shader will be undefined If the geometry stage makes no static assignment to g _ViewportIndex the fragment stage will read zero Otherwise the fragment stage will read the same value written by the geometry stage
121. e and interpolateAtOffset will be evaluated at the specified location ignoring the location normally used with the centroid qualifier If interpolant is declared with the noperspective qualifier the interpolated value will be computed without perspective correction 181 8 14 8 Built in Functions Syntax Description float interpolateAtCentroid float interpolant vec2 interpolateAtCentroid vec2 interpolant vec3 interpolateAtCentroid vec3 interpolant vec4 interpolateAtCentroid vec4 interpolant Returns the value of the input interpolant sampled at a location inside both the pixel and the primitive being processed The value obtained would be the same value assigned to the input variable if declared with the centroid qualifier float interpolateAtSample float interpolant int sample vec2 interpolateAtSample vec2 interpolant int sample vec3 interpolateAtSample vec3 interpolant int sample vec4 interpolateAtSample vec4 interpolant int sample Returns the value of the input interpolant variable at the location of sample number sample If multisample buffers are not available the input variable will be evaluated at the center of the pixel If sample sample does not exist the position used to interpolate the input variable is undefined float interpolateAtOffset float interpolant vec2 offset vec interpolateAtOffset vec2 interpolant vec2 offset vec3 interpolateAtOffset vec3 interpolant
122. e a function main with any other parameters or return type 115 6 1 1 6 Statements and Structure Function Calling Conventions Functions are called by value return This means input arguments are copied into the function at call time and output arguments are copied back to the caller before function exit Because the function works with local copies of parameters there are no issues regarding aliasing of variables within a function To control what parameters are copied in and or out through a function definition or declaration e The keyword in is used as a qualifier to denote a parameter is to be copied in but not copied out e The keyword out is used as a qualifier to denote a parameter is to be copied out but not copied in This should be used whenever possible to avoid unnecessarily copying parameters in e The keyword inout is used as a qualifier to denote the parameter is to be both copied in and copied out It means the same thing as specifying both in and out e A function parameter declared with no such qualifier means the same thing as specifying in All arguments are evaluated at call time exactly once in order from left to right Evaluation of an in parameter results in a value that is copied to the formal parameter Evaluation of an out parameter results in an l value that is used to copy out a value when the function returns Evaluation of an inout parameter results in both a value and an I value the value is copied
123. e and expression must satisfy the semantic requirements of both op and equals Reading a variable before writing or initializing it is legal however the value is undefined Expressions Expressions in the shading language are built from the following Constants of type bool all integer types all floating point types all vector types and all matrix types Constructors of all types Variable names of all types An array vector or matrix expression with the length method applied Subscripted array names Function calls that return values Component field selectors and array subscript results Parenthesized expression Any expression can be parenthesized Parentheses can be used to group operations Operations within parentheses are done before operations across parentheses 107 5 Operators and Expressions The arithmetic binary operators add subtract multiply and divide operate on integer and floating point scalars vectors and matrices If the fundamental types in the operands do not match then the conversions from section 4 1 10 Implicit Conversions are applied to create matching types All arithmetic binary operators result in the same fundamental type signed integer unsigned integer single precision floating point or double precision floating point as the operands they operate on after operand type conversion After conversion the following cases are valid e The two operands are scalars
124. e for unsized arrays For example out layout xfb buffer 1 xfb stride 16 gl PerVertex vec4 gl Position layout xfb offset 0 float gl_ClipDistance 4 Other layout qualifiers like location cannot be added to such a redeclaration unless specifically stated If a built in interface block is redeclared it must appear in the shader before any use of any member included in the built in declaration or a compile time error will result It is also a compile time error to redeclare the block more than once or to redeclare a built in block and then use a member from that built in block that was not included in the redeclaration Also if a built in interface block is redeclared no member of the built in declaration can be redeclared outside the block redeclaration If multiple shaders using members of a built in block belonging to the same interface are linked together in the same program they must all redeclare the built in block in the same way as described in section 4 3 9 Interface Blocks for interface block matching or a link time error will result It will also be a link time error if some shaders in a program redeclare a specific built in interface block while another shader in that program does not redeclare that interface block yet still uses a member of that interface block If a built in block interface is formed across shaders in different programs the shaders must all redeclare the built in block in the same way as
125. e is a simple low level mechanism to set the behavior for each extension It does not define policies such as which combinations are appropriate those must be defined elsewhere Order of directives matters in setting the behavior for each extension Directives that occur later override those seen earlier The all variant sets the behavior for all extensions overriding all previously issued extension directives but only for the behaviors warn and disable 19 3 4 3 Basics The initial state of the compiler is as if the directive extension all disable was issued telling the compiler that all error and warning reporting must be done according to this specification ignoring any extensions Each extension can define its allowed granularity of scope If nothing is said the granularity is a shader that is a single compilation unit and the extension directives must occur before any non preprocessor tokens If necessary the linker can enforce granularities larger than a single compilation unit in which case each involved shader will have to contain the necessary extension directive Macro expansion is not done on lines containing extension and version directives line must have after macro substitution one of the following forms line line line line source string number where line and source string number are constant integer expressions After processing this directive including its new line the implementation will beha
126. e only unsized array member is the last member of the block In a shader storage block the last member may be declared without an explicit size In this case the effective array size is inferred at run time from the size of the data store backing the interface block Such run time sized arrays may be indexed with general integer expressions However it is a compile time error to pass them as an argument to a function or index them with a negative constant expression 38 4 1 10 Implicit Conversions 4 Variables and Types In some situations an expression and its type will be implicitly converted to a different type The following table shows all allowed implicit conversions Type of expression Can be implicitly converted to int uint int float uint int double uint float ivec2 uvec2 ivec3 uvec3 ivec4 uvec4 ivec2 vec2 uvec2 ivec3 vec3 uvec3 ivec4 vec4 uvec4 ivec2 dvec2 uvec2 vec2 ivec3 dvec3 uvec3 vec3 ivec4 dvec4 uvec4 vec4 mat2 dmat2 mat3 dmat3 mat4 dmat4 mat2x3 dmat2x3 mat2x4 dmat2x4 mat3x2 dmat3x2 mat3x4 dmat3x4 mat4x2 dmat4x2 mat4x3 dmat4x3 39 4 1 11 4 Variables and Types There are no implicit array or structure conversions For example an array of int cannot be implicitly converted to an array of float When an implicit conversion is done it is not a re interpretation of the expression s bit pattern but a con
127. e original value is read and the time the new value is written 175 8 12 8 Built in Functions Atomic memory functions are supported only for a limited set of variables A shader will fail to compile if the value passed to the mem argument of an atomic memory function does not correspond to a buffer or shared variable It is acceptable to pass an element of an array or a single component of a vector to the mem argument of an atomic memory function as long as the underlying array or vector is a buffer or shared variable Syntax Description uint atomicAdd inout uint mem uint data Computes a new value by adding the value of data to int atomicAdd inout int mem int data the contents mem uint atomicMin inout uint mem uint data Computes a new value by taking the minimum of the int atomicMin inout int mem int data value of data and the contents of mem uint atomicMax inout uint mem uint data Computes a new value by taking the maximum of the int atomicMax inout int mem int data value of data and the contents of mem uint atomicAnd inout uint mem uint data Computes a new value by performing a bit wise int atomicAnd inout int mem int data AND of the value of data and the contents of mem uint atomicOr inout uint mem uint data Computes a new value by performing a bit wise OR int atomicOr inout int mem int data of the value of data and the contents of mem uint atomicXor inout uint mem uint data Com
128. e shared within the local work group It is a compile time error to use g WorkGroupSize in a shader that does not declare a fixed local group size or before that shader has declared a fixed local group size using local_size_x local_size_y and local_size_z When a size is given for some of these identifiers but not all the corresponding gl WorkGroupSize will have a size of 1 The built in variable g WorkGroupID is a compute shader input variable containing the three dimensional index of the global work group that the current invocation is executing in The possible values range across the parameters passed into DispatchCompute 1 e from 0 0 0 to el NumWorkGroups x 1 gl NumWorkGroups y 1 gl NumWorkGroups z 1 124 7 Built in Variables The built in variable g LocalInvocationID is a compute shader input variable containing the t dimensional index of the local work group within the global work group that the current invocation is executing in The possible values for this variable range across the local work group size 1 e 0 0 0 to el WorkGroupSize x 1 gl WorkGroupSize y 1 gl WorkGroupSize z 1 The built in variable g GlobalInvocationID is a compute shader input variable containing the global index of the current work item This value uniquely identifies this invocation from all other invocations across all local and global work groups initiated by the current DispatchCompute call This is computed as gl_Gl
129. e2DArray uimage2DArray imageCubeArray iimageCubeArray uimageCubeArray image2DMS iimage2DMS_ uimage2DMS image2DMSArray iimage2DMSArray uimage2DMSArray struct The following are the keywords reserved for future use Using them will result in a compile time error common partition active asm class union enum typedef template this resource 22 3 7 3 8 3 Basics goto inline noinline public static extern external interface long short half fixed unsigned superp input output hvec2 hvec3 hvec4 fvec2 fvec3 fvec4 sampler3DRect filter sizeof cast namespace using In addition all identifiers containing two consecutive underscores ___ are reserved for use by underlying software layers Defining such a name in a shader does not itself result in an error but may result in unintended behaviors that stem from having multiple definitions of the same name Identifiers Identifiers are used for variable names function names structure names and field selectors field selectors select components of vectors and matrices similar to structure members as discussed in section 5 5 Vector and Scalar Components and section 5 6 Matrix Components Identifiers have the form identifier nondigit identifier nondigit identifier digit nondigit one of _abcdefghijkIlmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ digit one of 0123456789 Identifiers starting with gl are reserved for use by OpenGL and may not be declared in a
130. eOffset gvec4 textureProjGrad gsampler1D sampler vec2 P float dPdx float dPdy gvec4 textureProjGrad gsampler1D sampler vec4 P float dPdx float dPdy gvec4 textureProjGrad gsampler2D sampler vec3 P vec2 dPdx vec2 dPdy gvec4 textureProjGrad gsampler2D sampler vec4 P vec2 dPdx vec2 dPdy gvec4 textureProjGrad gsampler3D sampler vec4 P vec3 dPdx vec3 dPdy gvec4 textureProjGrad gsampler2DRect sampler vec3 P vec2 dPdx vec2 dPdy gvec4 textureProjGrad gsampler2DRect sampler vec4 P vec2 dPdx vec2 dPdy float textureProjGrad sampler2DRectShadow sampler vec4 P vec2 dPdx vec2 dPdy float textureProjGrad sampler DShadow sampler vec4 P float dPdx float dPdy float textureProjGrad sampler2DShadow sampler vec4 P vec2 dPdx vec2 dPdy Do a texture lookup both projectively as described in textureProj and with explicit gradient as described in textureGrad The partial derivatives dPdx and dPdy are assumed to be already projected 169 8 9 3 8 Built in Functions Syntax Description gvec4 textureProjGradOffset gsampler1D sampler vec2 P Do a texture lookup projectively float dPdx float dPdy int offset and with explicit gradient as gvec4 textureProjGradOffset gsampler1D sampler vec4 P described in textureProjGrad float dPdx float dPdy int offset as well as with offset as gvec4 textureProjGradOffset gsampler2D sampler vec3 P described in textureOtiset vec2 dPdx v
131. eadonly qualifies the image memory as accessed through that variable while const qualifies the variable itself Order and Repetition of Qualification When multiple qualifiers are present in a variable or parameter declaration they may appear in any order but they must all appear before the type The layout qualifier is the only qualifier that can appear more than once Further a declaration can have at most one storage qualifier at most one auxiliary storage qualifier and at most one interpolation qualifier If inout is used neither in nor out may be used Multiple memory qualifiers can be used Any violation of these rules will cause a compile time error 97 5 Operators and Expressions 5 1 Operators The OpenGL Shading Language has the following operators Precedence Operator Class Operators Associativity 1 highest parenthetical grouping O NA array subscript Left to Right function call and constructor structure O field or method selector swizzle 2 post fix increment and decrement prefix increment and decrement Right to Left 3 unary 4 multiplicative 1 Left to Right 5 additive Left to Right 6 bit wise shift lt lt gt gt Left to Right 7 relational lt gt lt gt Left to Right 8 equality Left to Right 9 bit wise and amp Left to Right 10 bit wise exclusive or Left to Right 11 bit wise inclusive or Left to Right
132. ec2 dPdy ivec2 offset gvec4 textureProjGradOffset gsampler2D sampler vec4 P vec2 dPdx vec2 dPdy ivec2 offset gvec4 textureProjGradOffset gsampler2DRect sampler vec3 P vec2 dPdx vec2 dPdy ivec2 offset gvec4 textureProjGradOffset gsampler2DRect sampler vec4 P vec2 dPdx vec2 dPdy ivec2 offset float textureProjGradOffset sampler2DRectShadow sampler vec4 P vec2 dPdx vec2 dPdy ivec2 offset gvec4 textureProjGradOffset gsampler3D sampler vec4 P vec3 dPdx vec3 dPdy ivec3 offset float textureProjGradOffset sampler DShadow sampler vec4 P float dPdx float dPdy int offset float textureProjGradOffset sampler2DShadow sampler vec4 P vec2 dPdx vec2 dPdy ivec2 offset Texture Gather Functions The texture gather functions take components of a single floating point vector operand as a texture coordinate determine a set of four texels to sample from the base level of detail of the specified texture image and return one component from each texel in a four component result vector When performing a texture gather operation the minification and magnification filters are ignored and the rules for LINEAR filtering in the OpenGL Specification are applied to the base level of the texture image to identify the four texels igi iij izjo and igjo The texels are then converted to texture base colors Rs Gs Bs As according to table 15 1 followed by application of the texture swizzle as described in section 15 2
133. eclared as invariant To guarantee invariance of a particular output variable across two programs the following must also be true e The output variable is declared as invariant in both programs e The same values must be input to all shader input variables consumed by expressions and flow control contributing to the value assigned to the output variable 90 4 8 2 4 9 4 Variables and Types e The texture formats texel values and texture filtering are set the same way for any texture function calls contributing to the value of the output variable e All input values are all operated on in the same way All operations in the consuming expressions and any intermediate expressions must be the same with the same order of operands and same associativity to give the same order of evaluation Intermediate variables and functions must be declared as the same type with the same explicit or implicit precision qualifiers Any control flow affecting the output value must be the same and any expressions consumed to determine this control flow must also follow these invariance rules e All the data flow and control flow leading to setting the invariant output variable reside in a single compilation unit 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 pragma STDG
134. ed Keywords embedded in text are bold Operators are called by their name followed by their symbol in bold in parentheses The clarifying grammar fragments in the text use bold for literals and italics for non terminals The official grammar in section 9 Shading Language Grammar uses all capitals for terminals and lower case for non terminals Deprecation The OpenGL Shading Language has deprecated some features These are clearly called out in this specification as deprecated They are still present in this version of the language but are targeted for potential removal in a future version of the shading language The OpenGL API has a forward compatibility mode that will disallow use of deprecated features If compiling in a mode where use of deprecated features is disallowed their use causes compile time or link time errors See the OpenGL Graphics System Specification for details on what causes deprecated language features to be accepted or to return an error 2 Overview of OpenGL Shading 2 1 2 2 The OpenGL Shading Language is actually several closely related languages These languages are used to create shaders for each of the programmable processors contained in the OpenGL processing pipeline Currently these processors are the vertex tessellation control tessellation evaluation geometry fragment and compute processors Unless otherwise noted in this paper a language feature applies to all languages and common usage
135. elected texel 178 8 Built in Functions Syntax Description uint imageAtomicMin MAGE PARAMS Computes a new value by taking the minimum of the uint data value of data and the contents of the selected texel int imageAtomicMin IMAGE PARAMS int data uint imageAtomicMax IMAGE PARAMS uint data int imageAtomicMax IMAGE PARAMS int data Computes a new value by taking the maximum of the value data and the contents of the selected texel uint imageAtomicAnd WAGE PARAMS uint data int imageAtomicAnd IMAGE PARAMS int data Computes a new value by performing a bit wise AND of the value of data and the contents of the selected texel uint imageAtomicOr IMAGE _PARAMS uint data int imageAtomicOr IMAGE PARAMS int data Computes a new value by performing a bit wise OR of the value of data and the contents of the selected texel uint imageAtomicXor MAGE PARAMS uint data int imageAtomicXor MAGE PARAMS int data Computes a new value by performing a bit wise EXCLUSIVE OR of the value of data and the contents of the selected texel uint imageAtomicExchange IMAGE PARAMS uint data int imageAtomicExchange MAGE _ PARAMS int data Computes a new value by simply copying the value of data uint imageAtomicCompSwap UMAGE_PARAMS uint compare uint data int imageAtomicCompSwap UMAGE_PARAMS int compare int data Compares the value of compare and the con
136. enation by taking the characters at the end of one line concatenating them with the characters at the beginning of the next line 14 3 3 3 Basics float f 00 forms a single lin quivalent to float foo assuming is the last character before the new line and oo are the first two characters of the next line Preprocessor There is a preprocessor that processes the source strings as part of the compilation process Except as noted below it behaves as the C standard preprocessor see section 10 Normative References The complete list of preprocessor directives is as follows define undef if ifdef ifndef else elif endif error pragma extension version line The following operators are also available defined Each number sign can be preceded in its line only by spaces or horizontal tabs It may also be followed by spaces and horizontal tabs preceding the directive Each directive is terminated by a new line Preprocessing does not change the number or relative location of new lines in a source string Preprocessing takes places after new lines have been removed by the line continuation character The number sign on a line by itself is ignored Any directive not listed above will cause a diagnostic message and make the implementation treat the shader as ill formed define and undef functionality are defined as is standard for C preprocessors for macro
137. entation 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 Layout qualifiers can appear in several forms of declaration They can appear as part of an interface block definition or block member as shown in the grammar in the previous section They can also appear with just an interface qualifier a storage qualifier that is in out or uniform to establish layouts of other declarations made with that interface qualifier layout qualifier interface qualifier Or they can appear with an individual variable declared with an interface qualifier layout qualifier interface qualifier declaration Declarations of layouts can only be made at global scope and only where indicated in the following subsections their details are specific to what the interface qualifier is and are discussed individually The ayout qualifier expands to layout qualifier layout ayout qualifier id list layout qualifier id list layout qualifier id layout qualifier id layout qualifier id list layout qualifier id layout qualifier name layout qualifier name layout qualifier value shared The tokens used for ayout qualifier name are identifiers not keywords however the shared keyword is allowed as a layout qualifier id Generally they can be listed in any order Order dependent meanings exist only if e
138. er and unsigned integer data types Image accesses should use an image type that matches the target of the texture whose level is bound to the image unit or for non layered bindings of 3D or array images should use the image type that matches the dimensionality of the layer of the image i e a layer of 3D 2DArray Cube or CubeArray should use image2D a layer of 1DArray should use image1D and a layer of 2DMSArray should use image2DMS If the image target type does not match the bound image in this manner if the data type does not match the bound image or if the format layout qualifier does not match the image unit format as described in section 8 25 Texture Image Loads and Stores of the OpenGL Specification the results of image accesses are undefined but cannot include program termination Image variables are used in the image load store and atomic functions described in section 8 12 Image Functions to specify an image to access Atomic Counters Atomic counter types atomic_uint are opaque handles to counters declared and behaving as described above for opaque types The variables they declare specify which counter to access when using the built in atomic counter functions as described in section 8 10 Atomic Counter Functions They are bound to buffers as described in section 4 4 6 1 Atomic Counter Layout Qualifiers When aggregated into arrays within a shader atomic counters can only be indexed with a dynamically uni
139. er shared coherent volatile restrict readonly writeonly atomic_uint layout centroid flat smooth noperspective patch sample break continue do for while switch case default if else subroutine in out inout float double int void bool true false invariant precise discard return mat2 mat3 mat4 dmat2 dmat3 dmat4 mat2x2 mat2x3 mat2x4 dmat2x2 dmat2x3 dmat2x4 mat3x2 mat3x3 mat3x4 dmat3x2 dmat3x3 dmat3x4 mat4x2 mat4x3 mat4x4 dmat4x2 dmat4x3 dmat4x4 vec2 vec3 vec4 ivec2 ivec3 ivec4 bvec2 bvec3 bvec4 uint uvec2 uvec3 uvec4 21 dvec2 dvec3 dvec4 3 Basics lowp mediump highp precision sampler1D sampler2D sampler3D samplerCube sampler1DShadow sampler2DShadow samplerCubeShadow sampler1DArray sampler2DArray sampler1DArrayShadow sampler2DArrayShadow isampler1D isampler2D isampler3D isamplerCube isampler1DArray isampler2DArray usampler1D usampler2D usampler3D usamplerCube usampler1DArray usampler2DArray sampler2DRect sampler2DRectShadow isampler2DRect usampler2DRect samplerBuffer isamplerBuffer usamplerBuffer sampler2DMS isampler2DMS usampler2DMS sampler2DMSArray isampler2DMSArray usampler2DMSArray samplerCubeArray samplerCubeArrayShadow isamplerCubeArray usamplerCubeArray imagelD iimagel1D uimage1D image2D iimage2D uimage2D image3D iimage3D uimage3D image2DRect iimage2DRect uimage2DRect imageCube iimageCube uimageCube imageBuffer iimageBuffer uimageBuffer imagelDArray iimagelDArray uimagelDArray image2DArray iimag
140. er1D sampler float coord float lod vec4 texture1DProjLod sampler1D sampler vec2 coord float lod vec4 texture1DProjLod sampler1D sampler vec4 coord float lod See corresponding signature above without 1D in the name vec4 texture2D sampler2D sampler vec2 coord float bias vec4 texture2DProj sampler2D sampler vec3 coord float bias vec4 texture2DProj sampler2D sampler vec4 coord float bias vec4 texture2DLod sampler2D sampler vec2 coord float lod vec4 texture2DProjLod sampler2D sampler vec3 coord float lod vec4 texture2DProjLod sampler2D sampler vec4 coord float lod See corresponding signature above without 2D in the name vec4 texture3D sampler3D sampler vec3 coord float bias vec4 texture3DProj sampler3D sampler vec4 coord float bias vec4 texture3DLod sampler3D sampler vec3 coord float lod vec4 texture3DProjLod sampler3D sampler vec4 coord float lod See corresponding signature above without 3D in the name Use the texture coordinate coord to do a texture lookup in the 3D texture currently bound to sampler For the projective Proj versions the texture coordinate is divided by coord g vec4 textureCube samplerCube sampler vec3 coord float bias vec4 textureCubeLod samplerCube sampler vec3 coord float lod See corresponding signature above without Cube in the name 173 8 Built in Function
141. erface block is started by an in out uniform or buffer keyword followed by a block name followed by an open curly brace as follows interface block layout qualifierop interface qualifier block name member list instance nameop 3 Note Order of qualifiers is not actually fixed qualifiers can be in any order interface qualifier in out patch in Note Qualifiers can be in any order patch out uniform buffer member list member declaration member declaration member list member declaration layout qualifierwt qualifiersop type declarators Note Qualifiers can be in any order instance name identifier identifier identifier integral constant expression Each of the above elements is discussed below with the exception of layout qualifiers ayout qualifier which are defined in the next section First an example uniform Transform mat4 ModelViewMatrix mat4 ModelViewProjectionMatrix uniform mat3 NormalMatrix allowed restatement of qualifier float Deformation The above establishes a uniform block named Transform with four uniforms grouped inside it Types and declarators are the same as for other input output uniform and buffer variable declarations outside blocks with these exceptions e initializers are not allowed opaque types are not allowed e structure definitions cannot be nested inside a block Any of these would result in a compile time error Othe
142. es in int gl PrimitivelD in vec3 gl TessCoord patch in float gl_TessLevelOuter 4 patch in float gl TessLevelInner 2 out gl PerVertex vec4 gl Position float gl PointSize float gl_ClipDistance In the fragment language built in variables are intrinsically declared as in vec4 gl FragCoord in bool gl FrontFacing in float gl_ClipDistance in vec2 gl PointCoord in int gl PrimitivelD in int gl SampleID in vec2 gl SamplePosition in int gl_SampleMaskIn in int gl Layer in int gl ViewportIndex out float gl FragDepth out int gl SampleMask Each of the above variables is discussed below The built in variable g NumWorkGroups is a compute shader input variable containing the total number of global work items in each dimension of the work group that will execute the compute shader Its content is equal to the values specified in the num_groups_x num_groups_y and num_groups_z parameters passed to the DispatchCompute API entry point The built in constant g WorkGroupSize is a compute shader constant containing the local work group size of the shader The size of the work group in the X Y and Z dimensions is stored in the x y and z components The constants values in g WorkGroupSize will match those specified in the required local_size_x local_size_y and local_size_z layout qualifiers for the current shader This is a constant so that it can be used to size arrays of memory that can b
143. even if that value is 127 7 Built in Variables out of range If a fragment shader contains a static access to g ViewportIndex it will count against the implementation defined limit for the maximum number of inputs to the fragment stage The variable gl PatchVerticesIn is available only in the tessellation control and evaluation languages It is an integer specifying the number of vertices in the input patch being processed by the shader A single tessellation control or evaluation shader can read patches of differing sizes so the value of gl PatchVerticesIn may differ between patches The output variables gl TessLevelOuter and gl_TessLevellnner are available only in the tessellation control language The values written to these variables are assigned to the corresponding outer and inner tessellation levels of the output patch They are used by the tessellation primitive generator to control primitive tessellation and may be read by tessellation evaluation shaders The variable gl TessCoord is available only in the tessellation evaluation language It specifies a three component u v w vector identifying the position of the vertex being processed by the shader relative to the primitive being tessellated Its values will obey the properties gl_TessCoord x 1 0 1 0 gl_TessCoord x two operations performed gl_TessCoord y 1 0 1 0 gl_TessCoord y two operations performed gl TessCoord z 1 0 1 0 gl TessCoord z
144. ex to be dynamically uniform Changed o gl MaxComputeAtomicCounterBuffers to 8 and o gl MaxCombinedTexturelmageUnits to 96 Bug 11009 Removed packed from the reserved word list Bug 11209 It is a compile time error to use the same block name for more than one block declaration in the same interface within one shader even if the block contents are identical Bug 11096 gl SampleMask can be sized to be no larger than the implementation dependent maximum sample mask Bug 10804 When a uniform layout location is used it is not required that all declarations of that name include the location only that those that include a location use the same location Bug 11052 Make type matching across compilation units in the same program apply to all declared variables not just those statically used etc Bug 10941 When accessing the same packed buffer across multiple stages in the same program it either works or you get a link error Bug 11734 Add gl MaxCombinedShaderOutputResources Bug 12112 Allow link time or compile time error when non g _JnvocationID is used for a tessellation control shader per vertex output Bug 12101 Compile time error to resize an array to a smaller size than it s already been indexed with earlier in the shader Bug 11527 Add missing patch as an interface block qualifier This was always the intent Also be clear they are only for outputs of tessellation control shaders and inputs of tessellation evaluation s
145. expression must be one that could be assigned to an I value Pre increment and pre decrement add or subtract or 1 0 to the contents of the expression they operate on 108 5 Operators and Expressions and the value of the pre increment or pre decrement expression is the resulting value of that modification Post increment and post decrement expressions add or subtract 1 or 1 0 to the contents of the expression they operate on but the resulting expression has the expression s value before the post increment or post decrement was executed The relational operators greater than gt less than lt greater than or equal gt and less than or equal lt operate only on scalar integer and scalar floating point expressions The result is scalar Boolean Either the operands types must match or the conversions from section 4 1 10 Implicit Conversions will be applied to obtain matching types To do component wise relational comparisons on vectors use the built in functions lessThan lessThanEqual greaterThan and greaterThanEqual The equality operators equal and not equal operate on all types except aggregates that contain opaque types They result in a scalar Boolean If the operand types do not match then there must be a conversion from section 4 1 10 Implicit Conversions applied to one operand that can make them match in which case this conversion is done For vectors matrices structures and arrays
146. f 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 section 4 4 2 1 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 I value it is a compile time or link time error if the expression indicating the vertex index is not the identifier g _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 sha
147. fect 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 the next chapter function input and output is done through copies and therefore qualifiers do not have to match Default Precision Qualifiers The precision statement precision precision qualifier type can be used to establish a default precision qualifier The type field can be either int or float or any of the sampler types and the precision qualifier can be lowp mediump or highp Any other types or qualifiers will result in a compile time error If type is float the directive applies to non precision qualified single precision floating point type scalar vector and matrix declarations If type is int the directive applies to all non precision qualified integer type scalar vector signed and unsigned declarations This includes global variable declarations function return declarations function parameter declarations and local variable declarations Non precision qualified declarations will use the precision qualifier specified in the most recent precision statement that is still in scope The precision statement has the same scoping rules as variable declarations If it is declared inside a compound statement its effect stops at the end of the innermost
148. ference in precision between fma and the expression a b c genType frexp genType x out genIType exp genDType frexp genDType x out genIType exp Splits x into a floating point significand in the range 0 5 1 0 and an integral exponent of two such that exponent x significand 2 The significand is returned by the function and the exponent is returned in the parameter exp For a floating point value of zero the significand and exponent are both zero For a floating point value that is an infinity or is not a number the results are undefined If an implementation supports negative 0 frexp 0 should return 0 otherwise it will return 0 148 8 Built in Functions Syntax Description genType Idexp genType x in genlT ype exp genDType Idexp genDType x in genlType exp Builds a floating point number from x and the corresponding integral exponent of two in exp returning exponent significand 2 If this product is too large to be represented in the floating point type the result is undefined If exp is greater than 128 single precision or 1024 double precision the value returned is undefined If exp is less than 126 single precision or 1022 double precision the value returned may be flushed to zero Additionally splitting the value into a significand and exponent using frexp and then reconstructing a floating point value using Idexp should yield
149. 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 is as if the following were declared layout shared column_major uniform layout shared column_major buffer 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 std 40 std430 and packed qualifiers other qualifiers are inherited The compiler linker will ensure that multiple programs and programmable stages containing this definition will share the same memory layout for this block as long as all arrays are declared with explicit sizes and all matrices have matching row_major and or column_major qualifications which may come from a declaration outside the block definition This allows use of the same buffer to back the same block definition across different programs The packed qualifier overrides
150. float bias gvec4 textureProjOffset gsampler1D sampler vec4 P int offset float bias gvec4 textureProjOffset gsampler2D sampler vec3 P ivec2 offset float bias gvec4 textureProjOffset gsampler2D sampler vec4 P ivec2 offset float bias gvec4 textureProjOffset gsampler3D sampler vec4 P ivec3 offset float bias gvec4 textureProjOffset gsampler2DRect sampler vec3 P ivec2 offset gvec4 textureProjOffset gsampler2DRect sampler vec4 P ivec2 offset float textureProjOffset sampler2DRectShadow sampler vec4 P ivec2 offset float textureProjOffset sampler DShadow sampler vec4 P int offset float bias float textureProjOffset sampler2DShadow sampler vec4 P ivec2 offset float bias Do a projective texture lookup as described in textureProj offset by offset as described in textureOffset 166 8 Built in Functions Syntax Description gvec4 textureLodOffset gsampler1D sampler float P float lod int offset gvec4 textureLodOffset gsampler2D sampler vec2 P float lod ivec2 offset gvec4 textureLodOffset gsampler3D sampler vec3 P float lod ivec3 offset float textureLodOffset sampler Shadow sampler vec3 P float lod int offset float textureLodOffset sampler2DShadow sampler vec3 P float lod ivec2 offset gvec4 textureLodOffset gsampler1 DArray sampler vec2 P float lod int offset gvec4 textureLodOffset gsampler2DArray sampler vec3 P float lod i
151. for red in a color Accessing components beyond those declared for the type is a compile time error so for example vec2 pos float height pos x is legal pos z is illegal height x is legal height y is illegal The component selection syntax allows multiple components to be selected by appending their names from the same name set after the period vec4 v4 v4 rgba is a vec4 and the same as just using v4 v4 rgb is a vec3 v4 b is a float v4 xy is a vec2 v4 xgba is illegal the component names do not come from the same set The order of the components can be different to swizzle them or replicated vec4 pos vec4 1 0 2 0 3 0 4 0 vec4 swiz pos wzyx swiz 4 0 3 0 2 0 1 0 vec4 dup pos xxyy dup 1s 05e 107 205 2 0 float f 1 2 vec4 dup f xxxx dup 122 462 422 1 52 This notation is more concise than the constructor syntax To form an r value it can be applied to any expression that results in a vector or scalar r value Any resulting vector of any operation must be a valid vector in the language hence the following results in a compile time error vec4 f vec4 g pos xyzwxy xyzw illegal pos xyzwxy is non existent vec6 The component group notation can occur on the left hand side of an expression vec4 pos vec4 1 0 2 0 3 0 4 0 pos xw vec2 5 0 6 0 pos 5 0 2 0 3 0 6 0 pos wx vec2 7 0 8 0 pos
152. form control flow are undefined 3 The method may differ per fragment subject to the constraint that the method may vary by window coordinates not screen coordinates The invariance requirement described in section 14 2 Invariance of the OpenGL Graphics System Specification is relaxed for derivative calculations because the method may be a function of fragment location Other properties that are desirable but not required are 4 Functions should be evaluated within the interior of a primitive interpolated not extrapolated 180 8 13 2 8 Built in Functions 5 Functions for dFdx should be evaluated while holding y constant Functions for dFdy should be evaluated while holding x constant However mixed higher order derivatives like dFdx dFdy y and dFdy dFdx x are undefined 6 Derivatives of constant arguments should be 0 In some implementations varying degrees of derivative accuracy may be obtained by providing GL hints section 21 4 Hints of the OpenGL Graphics System Specification allowing a user to make an image quality versus speed trade off Syntax Description genType dFdx genType p Returns the derivative in x using local differencing for the input argument p genType dFdy genType p Returns the derivative in y using local differencing for the input argument p These two functions are commonly used to estimate the filter width used to anti alias procedural textures We are assumin
153. form integral expression otherwise results are undefined Members of structures cannot be declared as atomic counter types Structures User defined types can be created by aggregating other already defined types into a structure using the struct keyword For example struct light float intensity vec3 position lightVar 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 light lightVar2 34 4 1 9 4 Variables and Types More formally structures are declared as follows However the complete correct grammar is as given in section 9 Shading Language Grammar struct definition qualifier struct name member list declarators opt opt op 4 member list member declaration member declaration member list member declaration basic type declarators 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 Member declarators may contain precision qualifiers but use of any other qualifier result
154. 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 a compile time error to provide extra arguments beyond this last used argument If a matrix is constructed from a matrix then each component column 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
155. ft sets the lower right FA component to 1 and the rest to 0 Structure Constructors 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 struct light float intensity vec3 position light lightVar light 3 0 vec3 1 0 2 0 3 0 102 5 4 4 5 5 5 Operators and Expressions 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 or be a type that can be converted to the member s type according to section 4 1 10 Implicit Conversions Structure constructors can be used as initializers or in expressions Array Constructors Array types can also be used as constructor names which can then be used in expressions or initializers For example const float c 3 float 3 5 0 7 2 1 1 const float d 3 float 5 0 7 2 1 1 float g float a 5 float 5 g 1 g 2 3 9 float b 3 b float 3 g g 1 0 g 2 0 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 elemen
156. function_call_header VOID function_call_header function_call_header_with_parameters function_call_header assignment_expression function_call_header_with_parameters COMMA assignment_expression function_call_header function_identifier LEFT PAREN Grammar Note Constructors look like functions but lexical analysis recognized most of them as keywords They are now recognized through type specifier Methods length subroutine array calls and identifiers are recognized through postfix_expression function_identifier type_specifier postfix_expression unary_expression postfix_expression INC_OP unary_expression DEC_OP unary_expression unary_operator unary_expression Grammar Note No traditional style type casts 190 9 Shading Language Grammar for Core Profile unary_operator PLUS DASH BANG TILDE Grammar Note No or amp unary ops Pointers are not supported multiplicative_expression unary_expression multiplicative_expression STAR unary_expression multiplicative_expression SLASH unary_expression multiplicative_expression PERCENT unary_expression additive_expression multiplicative_expression additive_expression PLUS multiplicative_expression additive_expression DASH multiplicative_expression shift_expression additive_expression shift_expression LEFT_OP additive_expression shift_expression RIGHT _OP additive_expression relational_expression shift_expression
157. g from some gsampler shadow types Bug 10990 Remove old contradictory text requiring interpolation qualifiers to match cross stage they must only match within a stage Bug 9999 Editorial add explanatory text about optimizing in section 4 4 2 4 about fragment output layout qualifiers This potentially includes skipping shader execution if the fragment is discarded because it is occluded and the shader has no side effects Bug 10485 It is only geometry shaders whose input is sized by the input primitive layout declaration Bug 10903 Clarify that members of structures cannot be declared as atomic counter types Put missing storage qualifiers in component examples Bug 11457 Add missing SHARED to the layout_qualifier_id grammar in section 9 This was already correctly reflected in the body of the specification Bug 11392 Clarify that comments do eliminate new lines but don t change the line count and that the preprocessing character set is bigger than the character set used in the resulting stream of GLSL tokens Bug 7343 Clarify interactions between comments new lines and preprocessing by explicitly listing the logical phases of compilation Bug 11362 When counting locations consumed clarify that the outer array level for geometry shader inputs tessellation control shader inputs and outputs and tessellation evaluation inputs is first removed before counting Bug 10737 State more clearly which types are illeg
158. g that the expression is being evaluated in parallel on a SIMD array so that at any given point in time the value of the function is known at the grid points represented by the SIMD array Local differencing between SIMD array elements can therefore be used to derive dFdx dFdy etc genType fwidth genType p Returns the sum of the absolute derivative in x and y using local differencing for the input argument p 1 e abs dFdx p abs dFdy p Interpolation Functions Built in interpolation functions are available to compute an interpolated value of a fragment shader input variable at a shader specified x y location A separate x y location may be used for each invocation of the built in function and those locations may differ from the default x y location used to produce the default value of the input For all of the interpolation functions interpolant must be an input variable or an element of an input variable declared as an array Component selection operators e g xy may be used when specifying interpolant Arrayed inputs can be indexed with general nonuniform integer expressions If interpolant is declared with the flat qualifier the interpolated value will have the same value everywhere for a single primitive so the location used for interpolation has no effect and the functions just return that same value If interpolant is declared with the centroid qualifier the value returned by interpolateAtSampl
159. gDepth modifying it in an unknown way and depth testing will always be performed after the shader has executed When the layout qualifier is depth_greater the GL can assume that the final value of gl FragDepth is greater than or equal to the fragment s interpolated depth value as given by the z component of g FragCoord When the layout qualifier is depth less the GL can assume that any modification of gl FragDepth will only decrease its value When the layout qualifier is depth_unchanged the shader compiler will honor any modification to gl_FragDepth but the rest of the GL can assume that gl FragDepth is not assigned a new value 76 4 4 3 4 Variables and Types Redeclarations of gl_FragDepth are performed as follows redeclaration that changes nothing is allowed out float gl FragDepth assume it may be modified in any way layout depth any out float gl FragDepth assume it may be modified such that its value will only increase layout depth greater out float gl FragDepth assume i layout dep may be modified such that its value will only decrease h_less out float gl FragDepth assume it will not be modified layout depth unchanged out float gl FragDepth If gl_FragDepth is redeclared in any fragment shader in a program it must be redeclared in all fragment shaders in that program that have static assignments to gl FragDepth All redeclarations of gl_FragDepth in all fragment shaders in a s
160. genDType x Returns a vector in the same direction as x but with a length of 1 compatibility profile only vec4 ftransform Available only when using the compatibility profile For core OpenGL use invariant For vertex shaders only This function will ensure that the incoming vertex value will be transformed in a way that produces exactly the same result as would be produced by OpenGL s fixed functionality transform It is intended to be used to compute g Position e g gl Position ftransform This function should be used for example when an application is rendering the same geometry in separate passes and one pass uses the fixed functionality path to render and another pass uses programmable shaders 152 8 Built in Functions Description Syntax genType faceforward genType N genType J genType Nref genDType faceforward genDType N genDType J genDType Nref If dot Nref J lt 0 return N otherwise return N genType reflect genType Z genType N genDType reflect genDType 7 genDType N For the incident vector J and surface orientation N returns the reflection direction 1 2 dot N J N N must already be normalized in order to achieve the desired result genType refract genType J genType N float eta genDType refract genDType J genDType N float eta For the incident vector J and surface normal N and the ratio of indices of refraction eta
161. ges 1 2 1 Changes since revision 8 of GLSL version 4 40 Minor editorial changes for consistency with the OpenGL ES language specification Bug 11702 Errors for reserved symbols are clarified gl in a GLSL name is an error use of GL_ in a preprocessor macro name is an error Use of consecutive double underscores is reserved but not an error Bug 11987 Allow array of array constructors and initialized variables to have any dimension unsized not just the outer dimension and get their size from the content of the constructor or initializer Bug 12032 Be clear that float 3 2 means logically float 3 2 not float 3 2 Bug 11734 Add gl MaxCombinedShaderOutputResources and mark gl MaxCombinedImageUnitsAndFragmentOutputs as deprecated Bug 12112 Allow link time or compile time error when non g _InvocationID is used for a tessellation control shader per vertex output Bug 12101 Compile time error to resize an array to a smaller size than it s already been indexed with earlier in the shader Bug 11527 Add missing patch as an interface block qualifier This was always the intent Also be clear they are only for outputs of tessellation control shaders and inputs of tessellation evaluation shaders Bug 11856 Clarifications on switch statements The switch s form a nested name scope and case default can t be nested in deeper than that scope Removed the rule about having no statement between a
162. h within a stage Bug 9999 Editorial add explanatory text about optimizing in section 4 4 2 4 about fragment output layout qualifiers This potentially includes skipping shader execution if the fragment is discarded because it is occluded and the shader has no side effects Bug 10485 Clarify it is only geometry shaders whose input is sized by the input primitive layout declaration Bug 10903 Clarify that members of structures cannot be declared as atomic counter types Put missing storage qualifiers in component examples Bug 11457 Add missing SHARED to the layout_qualifier_id grammar in section 9 This was already correctly reflected in the body of the specification Bug 11392 Clarify that comments do eliminate new lines but don t change the line count and that the preprocessing character set is bigger than the character set used in the resulting stream of GLSL tokens Bug 7343 Clarify interactions between comments new lines and preprocessing by explicitly listing the logical phases of compilation Bug 11362 When counting locations consumed clarify that the outer array level for geometry shader inputs tessellation control shader inputs and outputs and tessellation evaluation inputs is first removed before counting Bug 10737 State more clearly which types are illegal for inputs and outputs Bug 11178 Correct function overloading examples which were from a different revision of the spec than the current rule
163. hader will be run once for each input primitive If an invocation count is declared all such declarations must specify the same count Ifa shader specifies an invocation count greater than the implementation dependent maximum it will fail to compile For example layout triangles invocations 6 in will establish that all inputs to the geometry shader are triangles and that the geometry shader executable is run six times for each triangle processed All geometry shader input unsized array declarations will be sized by an earlier input primitive layout qualifier when present as per the following table Layout Size of Input Arrays points 1 lines 2 lines_adjacency 4 triangles 3 triangles adjacency 6 66 4 4 1 3 4 Variables and Types The intrinsically declared input array gl in will also be sized by any input primitive layout declaration Hence the expression gl_in length will return the value from the table above For inputs declared without an array size including intrinsically declared inputs i e g _in a layout must be declared before any use of the method length or other any array use that requires the array size to be known It is a compile time error if a layout declaration s array size from table above does not match all the explicit array sizes specified in declarations of an input variables in the same shader The following includes examples of compile time errors
164. haders Clarifications and Typographical Errors Editorial Added layout qualifier table for non opaque type and interface layout qualifiers Editorial changes around compute shader group sizes for language consistency within the spec and extensions Bug 10327 Editorial Say character set is subset of Unicode in UTF 8 encoding 1 Introduction Bug 11299 Fixed textureOffset for sampler2DArrayShadow to take a ivec2 not a vec2 for the offset Bug 10440 Clarify that a name collision between members of two anonymous blocks or a variable and a member of an anonymous block is an error Bug 10655 Clarification that opaque types e g samplers can be in a uniform e g member in a Struct not just a non aggregate uniform variable Bug 10659 Be even more clear that blocks generally cannot be redeclared as a way to size an unsized array contained in the block Bug 10682 Clarify that built in functions with void return or out arguments are not included in in the set of constant expressions Bug 11100 Editorial Simplify statement of what is written by EmitStreamVertex to just say all built in and user defined output variables Bug 10812 Missing text Added the phrase a pair of 16 bit signed integers when describing unpackSnorm2x16 Bug 11001 Remove extraneous g from some gsampler shadow types Bug 10990 Remove old contradictory text requiring interpolation qualifiers to match cross stage they must only matc
165. haders that the values assigned to gl Position are not exactly the same when the two shaders run In this example this can cause problems with alignment of geometry in a multi pass algorithm In general such variance between shaders is allowed When such variance does not exist for a particular output variable that variable is said to be invariant The Invariant Qualifier 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 invariant gl Position make existing gl Position be invariant out vec3 Color invariant Color make existing Color be invariant or as part of a declaration when a variable is declared invariant centroid out vec3 Color Only variables output from a shader including those that are then input to a subsequent shader can be candidates for invariance This includes user defined output variables and the built in output variables As only outputs need be declared with invariant an output from one shader stage will still match an input of a subsequent stage without the input being declared as invariant Input or output instance names on blocks are not used when redeclaring built in variables The invariant keyword can be followed by a comma separated list of previously declared identifiers All uses of invariant must be at the global scope and before any use of the variables being d
166. hey 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 a vertex and a geometry shader 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 56 4 Variables and Types 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 in Light vec4 LightPos vec3 LightColor in ColoredTexture vec4 Color vec2 TexCoord Material instance name vec3 Color different Color than Material Color vec4 LightPos illegal already defined LightPos accessing LightPos Material Color accessing Color in ColoredTexture block 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 na
167. ication of loops The for loop first evaluates the init expression then the condition expression If the condition expression evaluates to true then the body of the loop is executed After the body is executed a for loop will then evaluate the oop expression and then loop back to evaluate the condition expression repeating 119 6 4 6 Statements and Structure until the condition expression evaluates to false The loop is then exited skipping its body and skipping its loop expression Variables modified by the oop expression maintain their value after the loop is exited provided they are still in scope Variables declared in init expression or condition expression are only in scope until the end of the sub statement of the for loop The while loop first evaluates the condition expression If true then the body is executed This is then repeated until the condition expression evaluates to false exiting the loop and skipping its body Variables declared in the condition expression are only in scope until the end of the sub statement of the while loop The do while loop first executes the body then executes the condition expression This is repeated until condition expression evaluates to false and then the loop is exited Expressions for condition expression must evaluate to a Boolean Both the condition expression and the init expression can declare and initialize a variable except in the do while loop which cannot declare a v
168. ich 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 If it is declared in an if or else statement it is scoped to the end of that statement See section 6 2 Selection and section 6 3 Iteration for the location of statements and sub statements 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 nested in the global scope The if statement s expression does not allow new variables to be declared hence does not form a new scope 42 4 Variables and Types 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 int x 1 int x 2 y x y is initialized to 2 struct S int x S S S 0 S is only visible as a struct and constructor S S is now visible as a variable int x x Error if x has not been previously defined If the previous definition of x was in this same scope this causes a redeclaration error int f nested scope begins here int k in
169. ifiers These can only be used at global scope or on a block declaration or a compile time error results The row_major and column_major qualifiers 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 79 4 Variables and Types 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 identifier 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 identifier for the global scope or for block member declarations Any uniform or shader storage block declared without a binding identifier is initially assigned to block binding point zero After a program is linked the binding points used for uniform and shader storage blocks declared with or without a binding identifier can be updated by the OpenGL API If the binding identifier is used with a uniform or shader storage block instanced as an array the first element of the array takes the specified block bindi
170. image variables and atomic counters It does not have any predefined inputs nor any fixed function outputs It is not part of the graphics pipeline and its visible side effects are through changes to images storage buffers and atomic counters A compute shader operates on a group of work items called a work group A work group is a collection of shader invocations that execute the same code potentially in parallel An invocation within a work group may share data with other members of the same work group through shared variables and issue memory and control barriers to synchronize with other members of the same work group 12 3 Basics 3 1 Character Set and Phases of Compilation The source character set used for the OpenGL shading languages is Unicode in the UTF 8 encoding scheme After preprocessing only the following characters are allowed in the resulting stream of GLSL tokens The letters a z A Z and the underscore _ The numbers 0 9 The symbols period plus dash slash asterisk percent angled brackets lt and gt square brackets and parentheses and braces and caret vertical bar ampersand amp tilde equals exclamation point colon semicolon comma and question mark A compile time error will be given if any other character is used in a GLSL token There are no digraphs or trigraphs There are no escape sequences or u
171. imum number of subroutine uniform locations minus one Locations can be assigned to default block uniform arrays and structures The first inner most scalar vector or matrix member or element takes the specified location and the compiler assigns the next inner most member or element the next incremental location value Each subsequent inner most member or element gets incremental locations for the entire structure or array This rule applies to nested structures and arrays and gives each inner most scalar vector or matrix type a unique location For arrays without an explicit size the size is calculated based on its static usage When the linker generates locations for 77 4 4 4 4 4 5 4 Variables and Types 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 of member is deemed unused Subroutine Function Layout Qualifiers Layout qualifiers can be used for subroutine functions The layout qualifier identifiers for subroutine functions are layout qualifier id index integer constant expression Each subroutine with an index qualifier in the shader must be given a unique index otherwise a compile or link time error will be generated The indices must be in the range of 0 to the implementation defined maximum number of subroutines minus one It is recommended
172. ing it with a size or implicitly sized by indexing it only with integral constant expressions This needs to size the array to include all the clip planes that are enabled via the OpenGL API if the size does not include all enabled planes results are undefined The size can be at most g MaxClipDistances The number of varying components see gl MaxVaryingComponents consumed by gl _ClipDistance will match the size of the array no matter how many planes are enabled The shader must also set all values in gl_ClipDistance that have been enabled via the OpenGL API or results are undefined Values written into gl ClipDistance for planes that are not enabled have no effect As an output variable g ClipDistance provides the place for the shader to write these distances As an input in all but the fragment language it reads the values written in the previous shader stage In the fragment language gl ClipDistance array contains linearly interpolated values for the vertex values written by a shader to the g ClipDistance vertex output variable Only elements in this array that have clipping enabled will have defined values The output variable g _PrimitivelD is available only in the geometry language and provides a single integer that serves as a primitive identifier This is then available to fragment shaders as the fragment input gl PrimitivelD which will select the written primitive ID from the provoking vertex in the primitive being shaded If a fragmen
173. ing processed uniforms form the linkage between a shader OpenGL and the application varying compatibility profile only and vertex and fragment languages only same as out when in a vertex shader and same as in when in a fragment shader buffer value is stored in a buffer object and can be read or written both by shader invocations and the OpenGL API shared compute shader only variable storage is shared across all work items in a local work group Some input and output qualified variables can be qualified with at most one additional auxiliary storage qualifier 45 4 3 1 4 3 2 4 Variables and Types Auxiliary Storage Meaning Qualifier centroid centroid based interpolation sample per sample interpolation patch per tessellation patch attributes Not all combinations of qualification are allowed Auxiliary storage qualifiers can only be used with the in or out storage qualifiers Additional qualifier rules are defined in upcoming sections Local variables can only use the const storage qualifier or use no storage qualifier Function parameters can use const in and out qualifiers but as parameter qualifiers Parameter qualifiers are discussed in section 6 1 1 Function Calling Conventions Function return types and structure members do not use storage qualifiers Initializers in global declarations may only be used in declarations of global variables with no storage qualifier with a const
174. ingle program must have the same set of qualifiers Within any shader the first redeclarations of gl FragDepth must appear before any use of gl FragDepth The built in gl_FragDepth is only predeclared in fragment shaders so redeclaring it in any other shader language results in a compile time error Uniform Variable Layout Qualifiers Layout qualifiers can be used for uniform variables and subroutine uniforms The layout qualifier identifiers for uniform variables and subroutine uniforms are layout qualifier id location integer constant expression The location identifier can be used with default block uniform variables and subroutine uniforms The location specifies the location by which the OpenGL 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 No two default block uniform variables in the program can have the same location even if they are unused otherwise a compile time or link time error will be generated No two subroutine uniform variables can have the same location in the same shader stage otherwise a compile time or link time error will be generated Valid locations for default block uniform variable locations are in the range of 0 to the implementation defined maximum number of uniform locations minus one Valid locations for subroutine uniforms are in the range of 0 to the implementation defined per stage max
175. ions The layout qualifier identifiers for geometry shader outputs are layout qualifier id points line_strip triangle_strip max_vertices integer constant expression stream integer constant expression The primitive type identifiers points line_strip and triangle_strip are used to specify the type of output primitive produced by the geometry shader and only one of these is accepted At least one geometry shader compilation unit in a program must declare an output primitive type and all geometry shader output primitive type declarations in a program must declare the same primitive type It is not required that all geometry shaders in a program declare an output primitive type 74 4 Variables and Types The vertex count identifier max_vertices is used to specify the maximum number of vertices the shader will ever emit in a single invocation At least one geometry shader compilation unit in a program must declare a maximum output vertex count and all geometry shader output vertex count declarations in a program must declare the same count It is not required that all geometry shaders in a program declare a count In this example layout triangle strip max vertices 60 out order does not matter layout max_vertices 60 out redeclaration okay layout triangle strip out redeclaration okay layout points out error contradicts triangle strip layout max vertices 30 out error contradicts 60 all ou
176. is true the corresponding component of y is returned Components of x and y that are not selected are allowed to be invalid floating point values and will have no effect on the results Thus this provides different functionality than for example genType mix genType x genType y genType a where a is a Boolean vector genType step genType edge genType x genType step float edge genType x genDType step genDType edge genDType x genDType step double edge genDType x Returns 0 0 if x lt edge otherwise it returns 1 0 genType smoothstep genType edge0 genType edgel genType x genType smoothstep float edge0 float edgel genType x genDType smoothstep genDType edge0 genDType edgel genDType x genDType smoothstep double edge0 double edgel genDType x Returns 0 0 if x lt edge0 and 1 0 if x gt edge and performs smooth Hermite interpolation between 0 and 1 when edge0 lt x lt edgel This is useful in cases where you would want a threshold function with a smooth transition This is equivalent to genType t t clamp x edge0 edgel edge0 0 1 return t t 3 2 t And similarly for doubles Results are undefined if edge0 gt edgel genBType isnan genType x genBType isnan genDType x Returns true if x holds a NaN Returns false otherwise Always returns false if NaNs are not implemented genBType isinf genType x genBType isinf genDType x Retur
177. ite the new value to the selected texel and return the original value read The contents of the texel being updated by the atomic operation are guaranteed not to be modified by any other image store or atomic function between the time the original value is read and the time the new value is written Atomic memory operations are supported on only a subset of all image variable types image must be either e a signed integer image variable type starts iimage and a format qualifier of r32i used with a data argument of type int or e an unsigned image variable type starts uimage and a format qualifier of r32ui used with a data argument of type uint 177 8 Built in Functions Syntax Description int imageSize readonly writeonly gimagelD image ivec2 imageSize readonly writeonly gimage2D image ivec3 imageSize readonly writeonly gimage3D image ivec2 imageSize readonly writeonly gimageCube image ivec3 imageSize readonly writeonly gimageCubeArray image ivec2 imageSize readonly writeonly gimageRect image ivec2 imageSize readonly writeonly gimagel DArray image ivec3 imageSize readonly writeonly gimage2DArray image int imageSize readonly writeonly gimageBuffer image ivec2 imageSize readonly writeonly gimage2DMS image ivec3 imageSize readonly writeonly gimage2DMSArray image Returns the dimensions of the image or images bound to image For arrayed images the last component of the return val
178. itializers for const declarations at global scope must be constant expressions as defined in section 4 3 3 Constant Expressions 46 4 3 3 4 3 4 4 Variables and Types Constant Expressions A constant expression is one of e a literal value e g 5 or true e a variable declared with the const qualifier and an initializer where the initializer is a constant expression e an expression formed by an operator on operands that are all constant expressions including getting an element of a constant array or a member of a constant structure or components of a constant vector However the lowest precedence operators of the sequence operator and the assignment operators are not included in the operators that can create a constant expression e valid use of the length method on an explicitly sized object whether or not the object itself is constant implicitly sized or run time sized arrays do not return a constant expression e a constructor whose arguments are all constant expressions e the value returned by a built in function call whose arguments are all constant expressions with the exception of the texture lookup functions and the noise functions This rule excludes functions with a void return or functions that have an out parameter The built in functions dFdx dFdy and fwidth must return 0 when evaluated with an argument that is a constant expression Function calls to user defined functions non b
179. layout qualifier id location integer constant expression component integer constant expression The usage and rules for using the component qualifier and applying location qualifier to blocks and structures are exactly as described in section 4 4 1 Input Layout Qualifiers Additionally for fragment shader outputs if two variables are placed within the same location they must have the same underlying type floating point or integer No component aliasing of output variables or members is allowed Fragment shaders allow an additional index output layout qualifier layout qualifier id index integer constant expression Each of these qualifiers may appear at most once If index is specified location must also be specified If index is not specified the value 0 is used For example in a fragment shader 69 4 Variables and Types layout location 3 out vec4 color will establish that the fragment shader output color is assigned to fragment color 3 as the first index zero input to the blend equation And layout location 3 index 1 out vec4 factor will establish that the fragment shader output factor is assigned to fragment color 3 as the second index one input to the blend equation For fragment shader outputs the location and index specify the color output number and index receiving the values of the output For outputs of all other shader stages the location specifies a vector number that can be used to mat
180. le whose type is a structure or an array of any of these 50 4 3 6 4 Variables and Types There is an implementation dependent limit on the amount of storage for uniforms that can be used for each type of shader and if this is exceeded it will cause a compile time or link time error Uniform variables that are declared but not used do not count against this limit The number of user defined uniform variables and the number of built in uniform variables that are used within a shader are added together to determine whether available uniform storage has been exceeded If multiple shaders are linked together then they will share a single global uniform name space including within a language as well as across languages Hence the types and initializers of all declared uniform variables with the same name must match across all shaders that are linked into a single program 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 It is legal for some shaders to provide an initializer for a particular uniform variable while another shader does not but all provided initializers must be equal Similarly when a layout location is used it is not required that all declarations of that name include the location only th
181. les declared using the volatile qualifier must treat the underlying memory as though it could be read or written at any point during shader execution by some source other than the executing shader invocation When a volatile variable is read its value must be re fetched from the underlying memory even if the shader invocation performing the read had previously fetched its value from the same memory When a volatile variable is written its value must be written to the underlying memory even if the compiler can conclusively determine that its value will be overwritten by a subsequent write Since the external source reading or writing a volatile variable may be another shader invocation variables declared as volatile are automatically treated as coherent Memory accesses to image variables declared using the restrict qualifier may be compiled assuming that the variable used to perform the memory access is the only way to access the underlying memory using the shader stage in question This allows the compiler to coalesce or reorder loads and stores using restrict qualified image variables in ways that wouldn t be permitted for image variables not so qualified because the compiler can assume that the underlying image won t be read or written by other code Applications are responsible for ensuring that image memory referenced by variables qualified with 95 4 Variables and Types restrict will not be referenced using other variables in the same scope
182. lowed by a list of arguments in parentheses Arrays are allowed as arguments and as the return type In both cases the array must be explicitly sized An array is passed or returned by using just its name without brackets and the size of the array must match the size specified in the function s declaration Structures are also allowed as argument types The return type can also be structure 113 6 Statements and Structure See section 9 Shading Language Grammar for the definitive reference on the syntax to declare and define functions All functions must be either declared with a prototype or defined with a body before they are called For example float myfunc float f f is an input parameter out float g g is an output parameter Functions that return no value must be declared as void A void function can only use return without a return argument even if the return argument has void type Return statements only accept values void funcl void func2 return func1 illegal return statement Only a precision qualifier is allowed on the return type of a function Formal parameters can have parameter precision and memory qualifiers but no other qualifiers Functions that accept no input arguments need not use void in the argument list because prototypes or definitions are required and therefore there is no ambiguity when an empty argument list is declared The idiom void as a parameter li
183. lue of an atomic counter which may be e returned and incremented in an atomic operation or e decremented and returned in an atomic operation or e simply returned The underlying counter is a 32 bit unsigned integer Increments and decrements at the limit of the range will wrap to 0 2 1 Syntax Description uint atomicCounterIncrement atomic uintc Atomically 1 increments the counter for c and 2 returns its value prior to the increment operation These two steps are done atomically with respect to the atomic counter functions in this table uint atomicCounterDecrement atomic_uint c Atomically 1 decrements the counter for c and 2 returns the value resulting from the decrement operation These two steps are done atomically with respect to the atomic counter functions in this table uint atomicCounter atomic_uint c Returns the counter value for c Atomic Memory Functions Atomic memory functions perform atomic operations on an individual signed or unsigned integer stored in buffer object or shared variable storage All of the atomic memory operations read a value from memory compute a new value using one of the operations described below write the new value to memory and return the original value read The contents of the memory being updated by the atomic operation are guaranteed not to be modified by any other assignment or atomic memory function in any shader invocation between the time th
184. matrix argument is given to a matrix constructor it is a compile time error to have any other arguments If the basic type bool int float or double 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 100 5 Operators and Expressions Some useful vector constructors are as follows vec3 float vec4 ivec4 vec4 mat2 vec2 float ivec3 int bvec4 int vec2 vec3 vec3 vec4 vec3 vec2 vec3 float float vec4 vec3 vec4 vec4 vec2 initializes each component of the vec3 with the float makes a vec4 with component wise conversion the vec4 is column 0 followed by column 1 float int int int float Some examples of these are vec4 color vec4 rgba vec3 rgb float vec2 float vec3 vec2 vec4 0 0 vec4 1 0 initializes a vec2 with 2 floats initializes an ivec3 with 3 ints float uses 4 Boolean conversions drops the third component of a vec3 drops the fourth component of a vec4 vec3 x vec2 x vec3 y vec2 y vec3 z float vec3 x float vec3 y vec2 x vec3 z vec2 y 1 0 0 0 1 0 sets each component to 1 0 vec3 color drop the 4th component To initialize the diagonal of a matrix with all other elements set to zero mat2 float mat3 float mat4 float That is result i j is
185. me 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 e two different blocks each having no instance name and each having a member of the same name or e a variable outside a block and a block with no instance name where the variable has the same name as a member in the block 57 4 Variables and Types out Vertex vec4 Position API transform feedback will use Vertex Position vec2 Texture Coords shader will use Coords Position out Vertex2 vec4 Color API will use Color float Color2 in same program as Vertex2 above out Vertex3 float Intensity vec4 Color ERROR name collision with Color in Vertex2 float Color2 ERROR collides with Color2 in Vertex2 For blocks declared as arrays the array index must also be included when accessing members as in this example uniform Transform API uses Transform 2 to refer to instance 2 mat4 ModelViewMatrix mat4 ModelViewProjectionMatrix vec4 all array will get implicitly sized float Deformation transforms 4 transforms 2 ModelViewMatrix shader access
186. mes beginning components 0 1 and 2 of each of 6 slots layout location 0 component 0 in vec3 e 6 consumes last component of the same 6 slots layout location 0 component 3 in float f 6 If applying this to an array of arrays all levels of arrayness are removed to get to the elements that are assigned per location to the specified component These non arrayed elements will fill the locations in the order specified for arrays of arrays in section 4 1 9 Arrays It is a compile time error to apply the component qualifier to a matrix a structure a block or an array containing any of these It is a link time error to specify different components for the same variable within a program Location aliasing is causing two variables or block members to have the same location number Component aliasing is assigning the same or overlapping component numbers for two location aliases Recall if component is not used component s are assigned starting with 0 With one exception location aliasing is allowed only if it does not cause component aliasing it is a compile time or link time error to cause component aliasing Further when location aliasing the aliases sharing the location must have the same underlying numerical type floating point or integer and the same auxiliary storage and interpolation qualification The one exception where component aliasing is permitted is for two input variables not block members to a vertex sh
187. method will be undefined if the array is contained in an array of shader storage blocks that is indexed with a non constant expression less than zero or greater than or equal to the number of blocks in the array The length method cannot be called on an array that has not yet been explicitly sized this results in a compile time error The length method works equally well for arrays of arrays vec4 a 3 2 a length this is 3 a x length this is 2 When the length method returns a compile time constant the expression in brackets x above will be evaluated and subjected to the rules required for array indexes 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 When the length method returns a run time value the array will be dereferenced with the value x If x is not a compile time constant and is out of range an undefined value results for an array b containing a member array a b x a length b is never dereferenced but x is evaluated for an array s of a shader storage object containing a member array a s x a length s is dereferenced x needs to be a valid index For implicitly sized or run time sized arrays only the outermost dimension can be lacking a size A type that includes an unknown array size cannot be formed into an array until it gets an explicit size except for shader storage blocks where th
188. mie een t nnente 105 ETTE a E A A E E E A E A T 106 JO DA CL LOL D ET 107 5 10 Vector and Matrix Op r tiQns ssssssminucennenionennnensein intenses 110 5 11 Ou t of Bounds ACCESSES niinno niena i ia A EEE E aadi Na 111 Statements and SURI soon maintenant end 112 6 1 Eunction D Le 1e OL LUN Ce ase menssen soree ra ina oR Roa 113 6 1 1 Function Calling Coyne 5 5 25 ncccservsacsnessaresunsvedveoendavaserednonsnevenvannscnsvareansezeane 116 CC a vase len a eosin E 117 CR LE C0 LOS E D RES RD 118 Co nt a eas de ee da au 119 ee a On ee nate ee eat se nea ace ca eee 120 PEA rah RS ed ic nn Cd bi ni one 122 Tal Built in Language Variables era 122 7 1 1 Compatibility Profile Built In Language Variables 131 7 2 Compatibility Profile Vertex Shader Built In puits sis ssensnenisasnss 134 LS Bult Constants acinar e E E EE aa 135 7 3 1 Compatibility Profile Built In Cons 137 14 Built In Uniform Stale sereine a r E mad on NE araa Aia 137 TAL Compatibilty Profile Statessa ee EEE EEE ES 137 D Built in FIR sessin ean Gabe aa etat cane te Eana aa Eaa E A aaa 141 Sol An gleand Trigo ometry POUR sssrinin e asai iaai 142 8 2 Exponential Functions scssi oee E E E EA E ES 144 8 3 Common I fy nent a A EE ESTEAN St de ne 145 8 4 Floating Point Pack and Unpack Functions 150 8 3 Geometric Functions de aE EE ae am mm oi 153 8 6 Matrix PASS ee es a on nine Nord aaa 155
189. mpler2DShadow sampler vec4 P shadow forms is used as D float bias After these values are computed gvec4 textureProj gsampler2DRect sampler vec3 P texture lookup proceeds as in gvec4 textureProj gsampler2DRect sampler vec4 P texture float textureProj sampler2DRectShadow sampler vec4 P gvec4 textureLod gsampler1D sampler float P float lod Do a texture lookup as in gvec4 textureLod gsampler2D sampler vec2 P float lod texture but with explicit LOD gvec4 textureLod gsampler3D sampler vec3 P float lod lod specifies and sets the gvec4 textureLod gsamplerCube sampler vec3 P float lod partial derivatives as follows float textureLod sampler DShadow sampler vec3 P float lod See section 8 14 Texture float textureLod sampler2DShadow sampler vec3 P float lod Minification and equations 8 4 gvec4 textureLod gsampler DArray sampler vec2 P float lod 8 6 in the OpenGL Graphics gvec4 textureLod gsampler2DArray sampler vec3 P float lod System Specification float textureLod sampler DArrayShadow sampler vec3 P Ou av aw float lod Ax 0 Ae 0 a 0 gvec4 textureLod gsamplerCubeArray sampler vec4 P float lod au av aw 0 0 0 oy oy y 164 8 Built in Functions Syntax Description gvec4 textureOffset gsampler1D sampler float P int offset float bias gvec4 textureOffset gsampler2D sampler vec2 P ivec2 offset float bias gvec4 textureOffset gsam
190. multiplied by matrix These do not operate component wise but rather perform the correct linear algebraic multiply vec3 v u mat3 m u v m is equivalent to 110 5 Operators and Expressions u x dot v m 0 m 0 is the left column of m u y dot v m 1 dot a b is the inner dot product of a and b u z dot v m 2 And u m v is equivalent to u x m O x v x m 1l x vey m 2 x v z u y m O y v x m il y vey m 2 y v z WeZzcS MLO 2 vex tb mpl vey a m2 2 iv And mat3 m n r r m n is equivalent to r 0 x m 0 x n O x m x n 0 y m 2 x n 0 z flex m 0O x n 1 x m x nL eys om LZ x MIL 2 r 2 x m 0 x n x m eo ot y m 2 x n as r O y m 0 y n O x m y n O y m 2 y n 0 z r l y m 0O y n 1l x mf1 y nf 1 y m 2 y n 1 z y m 0 y n x m y n y m 2 y n Zi r 0 z m 0 z n 0 x mf1 z n 0 y m 2 z n 0 z r l z m 0 Ami ix VE am La yey t sm 2 om LL a2 r 2 z m 0 z n 2 x m l1l z n 2 y m 2 z n 2 z and similarly for other sizes of vectors and matrices 5 11 Out of Bounds Accesses In the subsections described above for array vector matrix and structure accesses any out of bounds access produced undefined behavior However if robust buffer access is enabled via the OpenGL API such accesses will
191. n input variable is declared in multiple shaders of the same language with conflicting locations The component qualifier allows the location to be more finely specified for scalars and vectors down to the individual components within a location that are consumed It is a compile time error to use component without also specifying the location qualifier order does not matter The components within a location are 0 1 2 and 3 A variable or block member starting at component N will consume components N N 1 N 2 up through its size It is a compile time error if this sequence of components gets larger than 3 For example 63 4 4 1 1 4 Variables and Types a consumes components 2 and 3 of location 4 layout location 4 component 2 in vec2 a b consumes component 1 of location 4 layout location 4 component 1 in float b ERROR c overflows components 2 and 3 layout location 3 component 2 in vec3 c If the variable is an array each element of the array in order is assigned to consecutive locations but all at the same specified component within each location For example component 3 in 6 locations are consumed layout location 2 component 3 in float d 6 That is location 2 component 3 will hold d 0 location 3 component 3 will hold d up through location 7 component 3 holding d 5 This allows packing of two arrays into the same set of locations e consu
192. n of value genIType findLSB genIType value genlType findLSB genUType value Returns the bit number of the least significant bit set to 1 in the binary representation of value If value is zero 1 will be returned genIT ype findMSB genIType value genIT ype findMSB genUType value Returns the bit number of the most significant bit in the binary representation of value For positive integers the result will be the bit number of the most significant bit set to 1 For negative integers the result will be the bit number of the most significant bit set to 0 For a value of zero or negative one 1 will be returned 159 8 9 8 Built in Functions Texture Functions Texture lookup functions are available in all shading stages However automatic level of detail is computed only for fragment shaders Other shaders operate as though the base level of detail were computed as zero The functions in the table below provide access to textures through samplers as set up through the OpenGL API Texture properties such as size pixel format number of dimensions filtering method number of mipmap levels depth comparison and so on are also defined by OpenGL API calls Such properties are taken into account as the texture is accessed via the built in functions defined below Texture data can be stored by the GL as single precision floating point unsigned normalized integer unsigned integer or signed integer data Thi
193. nanemonnmmanimrmddeen 87 4 7 1 Range and Precision sinsin sssri iee nE e tekstit R 87 4 T2 Precision OMR URSS a ee ann a 88 4 7 3 Default Precision Qualitiers lt 3es0ssaecassedsansdardedadsavdabsconaweeseivivoansaveadeaasosesaaboiadavsecas 89 4 74 Ava ilable Precision A FUNNIES cscs esc vacates one poe iara AE e E NEEESE SER EE 90 4 8 Va ance and the Inyariant Citer anses va eae EEEE S 90 MS Eie ivarm Ouale eee a seni RA E R K OE RR 90 4 8 2 Invariance of Constant Expressions ssriunseuensneientenetirens 91 4 9 The Preise Oua leE sieisen iioi ienie TAi A NOKE R E NE O ENE TIRE 91 4 10 Memory Qualifiers annees ERO E E E 94 4 11 Order and Repetition f Ouah On sccsivcssrecsccdasneavacsansecanseasioaserasicesotinavedsaneacaseastens 97 Operators And RE ATI ennemi oo nm roots 98 Cl A eae dd a a LR 98 DE AU DL CO TR RS 99 SE M D 1579157 LL ARR SRE ER RE ER RES RER ER ER PR RE PEN 99 S4 CONS HOCUS esrar etes EEEE noces dans lies ss E tennis ente Le ee nneres send nes Loose 99 5 4 1 Conversi n and Scalar COnS nICtOnS sen nantes etienne a atet linda 99 5 4 2 Vector and Matrix On i osisvszsversacbndccaasriociaiavs caveersialbsaiencnasreschomoneenianeeies 100 5 4 3 Structure COnStructOTs cccccecccccccccessssssscceceeccccecssssssccesecccecsssssseeeeccecceseeeeeceeceeeess 102 5 44 Arra CAME nn een nent ati 103 5 5 Vector and Scalar Components and EME nn a a 103 5 6 Matrix COMES nent 105 5 7 Structure and Array CBS enne
194. ne on the initializer before the assignment is done struct float a int by Fes le 2p 2s legal all types match 41 4 2 4 Variables and Types struct float a int by e 1 3 legal first initializer is converted All of the following declarations result in a compile time error int a true illegal vec4 b 2 vec4 0 0 1 0 illegal mat4x2 c vec3 0 0 vec3 1 0 illegal struct Sl vec4 a vec4 b struct float s float t df Sl vec4 0 0 vec4 1 1 illegal If an initializer of either form is provided for an unsized array the size of the array is determined by the number of top level non nested initializers within the initializer All of the following declarations create arrays explicitly sized with five elements float af float 3 4 4 2 5 0 5 2 1 1 float b 3 4 4 2 5 0 5 2 1 1 float c a is explicitly size 5 float d 5 b means the same thing It is a compile time error to have too few or too many initializers in an initializer list for the aggregate being initialized That is all elements of an array all members of a structure all columns of a matrix and all components of a vector must have exactly one initializer expression present with no unconsumed initializers Scoping The scope of a variable is determined by where it is declared If it is declared outside all function definitions it has global scope wh
195. ng and each subsequent element takes the next consecutive uniform block binding point If the binding point for any uniform or shader storage block instance is less than zero or greater than or equal to the implementation dependent maximum number of uniform buffer bindings a compile time error will occur When the binding identifier 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 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 layout row_major column_major results in the qualification being column_major Other examples layout shared row major uniform default is now shared and row major layout std140 uniform Transform layout of this block is std140 mat4 M1 row major layout column major mat4 M2 column major mat3 N1 row major uniform T2 layout of this block is shared layout column major uniform T3 shared and column major mat4 M3 column major layout row major mat4 m4 row major mat3 N2 column major The offset qualifier can only be used on block members of blocks declared with std140 or std430 layouts The offset qualifier forces the q
196. nly The equality operators and assignment operator are only allowed if the two operands are same size and type The operands cannot contain any opaque types Structure types must be of the same declared structure Both array operands must be explicitly sized When using the equality operators two structures are equal if and only if all the members are component wise equal and two arrays are equal if and only if all the elements are element wise equal Array elements are accessed using the array subscript operator An example of accessing an array element is diffuseColor lightIntensity 3 NdotL Array indices start at zero Array elements are accessed using an expression whose type is int or uint Behavior is undefined if a shader subscripts an array with an index less than 0 or greater than or equal to the size the array was declared with Arrays can also be accessed with the method operator and the length method to query the size of the array lightIntensity length return the size of the array Assignments Assignments of values to variable names are done with the assignment operator lvalue expression rvalue expression The value expression evaluates to an l value The assignment operator stores the value of rvalue expression into the l value and returns an r value with the type and precision of value expression The lvalue expression and rvalue expression must have the same t
197. ns can be any type as long their types match or there is a conversion in section 4 1 10 Implicit Conversions that can be applied to one of the expressions to make their types match This resulting matching type is the type of the entire expression The one s complement operator The operand must be of type signed or unsigned integer or integer vector and the result is the one s complement of its operand each bit of each component is complemented including any sign bits The shift operators lt lt and gt gt For both operators the operands must be signed or unsigned integers or integer vectors One operand can be signed while the other is unsigned In all cases the resulting type will be the same type as the left operand If the first operand is a scalar the second operand has to be a scalar as well If the first operand is a vector the second operand must be a scalar or a vector and the result is computed component wise The result is undefined if the right operand is negative or greater than or equal to the number of bits in the left expression s base type The value of El lt lt F2 is El interpreted as a bit pattern left shifted by E2 bits The value of El gt gt E2 is El right 109 5 10 5 Operators and Expressions shifted by E2 bit positions If El is a signed integer the right shift will extend the sign bit If El is an unsigned integer the right shift will zero extend e The bitwise operators and am
198. ns true if x holds a positive infinity or negative infinity Returns false otherwise genlType floatBitsToInt genType value genUType floatBitsToUint genType value Returns a signed or unsigned integer value representing the encoding of a float The float value s bit level representation is preserved 147 8 Built in Functions Syntax Description genType intBitsToFloat genIType value genType uintBitsToFloat genUType value Returns a float value corresponding to a signed or unsigned integer encoding of a float If a NaN is passed in it will not signal and the resulting value is unspecified If an Inf is passed in the resulting value is the corresponding Inf genType fma genType a genType b genType c genDType fma genDType a genDType b genDType c Computes and returns a b c In uses where the return value is eventually consumed by a variable declared as precise e fma is considered a single operation whereas the expression a b c consumed by a variable declared precise is considered two operations e The precision of fma can differ from the precision of the expression a b c e fma will be computed with the same precision as any other fma consumed by a precise variable giving invariant results for the same input values of a b and c Otherwise in the absence of precise consumption there are no special constraints on the number of operations or dif
199. nt int axTessControlInputComponents 128 TessControlOutputComponents 128 i ressControl1 xturelmageUnits 16 TessControlUniformComponents 1024 TessControlTotalOutputComponents 4096 TessEvaluationInputComponents 128 TessEvaluationOutputComponents 128 TessEvaluationTextureImageUnits 16 TessEvaluationUniformComponents 1024 TessPatchComponents 120 axPatchVertices 32 axTessGenLevel 64 axViewports 16 MaxVertexUniformVectors 256 MaxFragmentUniformVectors 256 MaxVaryingVectors 15 MaxVertexAtomicCounters 0 MaxTessControlAtomicCounters 0 a MaxTessEvaluationAtomicCounters 0 MaxGeometryAtomicCounters 0 MaxFragmentAtomicCounters 8 MaxCombinedAtomicCounters 8 MaxAtomicCounterBindings 1 MaxVertexAtomicCounterBuffers 0 axTessControlAtomicCounterBuffers 0 axTessEvaluationAtomicCounterBuffers 0 axGeometryAtomicCounterBuffers 0 1 1 axFragmentAtomicCounterBuffers axCombinedAtomicCounterBuffers axAtomicCounterBufferSize 32 inProgramTexelOffset 8 7 axProgramTexelOffset axTransformFeedbackBuffers 4 axTransformFeedbackInterleavedComponents 7 Built in Variables 64 The constant g MaxVaryingFloats is removed in the core profile use gl MaxVaryingComponents instead 135 7 3 1 7 4 7 4 1 7 Built in Variables Compatibility Profile Built In Constants
200. nt sprites are not enabled then the values read from gl PointCoord are undefined For both the input array g _ SampleMaskIn and the output array gl SampleMask bit B of mask M gl SampleMaskIn M or gl_SampleMask M corresponds to sample 32 M B These arrays have ceil s 32 elements where s is the maximum number of color samples supported by the implementation The input variable g _ SampleMaskin indicates the set of samples covered by the primitive generating the fragment during multisample rasterization It has a sample bit set if and only if the sample is considered covered for this fragment shader invocation The output array g SampleMask sets the sample mask for the fragment being processed Coverage for the current fragment will become the logical AND of the coverage mask and the output g SampleMask This array must be sized in the fragment shader either implicitly or explicitly to be no larger than the implementation dependent maximum sample mask as an array of 32bit elements determined by the maximum number of samples If the fragment shader statically assigns a value to g SampleMask the sample mask will be undefined for any array elements of any fragment shader invocations that fail to assign a value If a shader does not statically assign a value to g SampleMask the sample mask has no effect on the processing of a fragment The input variable gl _SamplelD is filled with the sample number of the sample currently being pro
201. nversion for unpacked fixed point value f to floating point is done as follows unpackUnorm2x16 f 65535 0 unpackSnorm2x16 clamp f 32767 0 1 1 unpackUnorm4x8 f 255 0 unpackSnorm4x8 clamp f 127 0 1 1 The first component of the returned vector will be extracted from the least significant bits of the input the last component will be extracted from the most significant bits double packDouble2x32 uvec2 v Returns a double precision value obtained by packing the components of v into a 64 bit value If an IEEE 754 Inf or NaN is created it will not signal and the resulting floating point value is unspecified Otherwise the bit level representation of v is preserved The first vector component specifies the 32 least significant bits the second component specifies the 32 most significant bits uvec2 unpackDouble2x32 double v Returns a two component unsigned integer vector representation of v The bit level representation of v is preserved The first component of the vector contains the 32 least significant bits of the double the second component consists of the 32 most significant bits uint packHalf2x16 vec2 v Returns an unsigned integer obtained by converting the components of a two component floating point vector to the 16 bit floating point representation found in the OpenGL Specification and then packing these two 16 bit integers into a 32 bit unsigned integer The first vector component
202. o a variable or member that is assigned a transform feedback offset the space is still allocated in the buffer and still affects the stride Variables and block members qualified with xfb_offset can be scalars vectors matrices structures and sized arrays of these The offset must be a multiple of the size of the first component of the first qualified variable or block member or a compile time error results Further if applied to an aggregate containing a double the offset must also be a multiple of 8 and the space taken in the buffer will be a multiple of 8 The given offset applies to the first component of the first member of the qualified entity Then within the qualified entity subsequent components are each assigned in order to the next available offset aligned to a multiple of that component s size Aggregate types are flattened down to the component level to get this sequence of components It is a compile time error to apply xfb_ offset to the declaration of an unsized array No aliasing in output buffers is allowed It is a compile time or link time error to specify variables with overlapping transform feedback offsets The xfb_ stride qualifier specifies how many bytes are consumed by each captured vertex It applies to the transform feedback buffer for that declaration whether it is inherited or explicitly declared It can be applied to variables blocks block members or just the qualifier out If the buffer is capturing any
203. o find space for other variables without explicit assignments If an output variable with no location or index assigned in the shader text has a location specified through the OpenGL API the API assigned location will be used Otherwise such variables will be assigned a location by the linker All such assignments will have a color index of zero See section 15 2 Shader Execution of the OpenGL Graphics System Specification for more details A link time error will occur if an output variable is declared in multiple shaders of the same language with conflicting location or index values For the purposes of determining if a non fragment output matches an input from a subsequent shader stage the location layout qualifier if any must match Transform Feedback Layout Qualifiers The vertex tessellation and geometry stages allow shaders to control transform feedback When doing this shaders will dictate which transform feedback buffers are in use which output variables will be written to which buffers and how each buffer is laid out To accomplish this shaders allow the following layout qualifier identifiers on output declarations layout qualifier id xfb_buffer integer constant expression xfb_offset integer constant expression xfb_stride integer constant expression Any shader making any static use after preprocessing of any of these xfb_ qualifiers will cause the shader to be in a transform feedback capturing mode and hence res
204. o right Binding points are not inherited only offsets Each binding point tracks its own current default offset for inheritance of subsequent variables using the same binding The initial state of compilation is that all binding points have an offset of 0 The offset can be set per binding point at global scope without declaring a variable For example layout binding 2 offset 4 uniform atomic_uint Establishes that the next atomic_uint declaration for binding point 2 will inherit offset 4 but does not establish a default binding layout binding 2 uniform atomic_uint bar offset is 4 8 layout offset uniform atomic_uint bar error no default binding Atomic counters may share the same binding point but if a binding is shared their offsets must be either explicitly or implicitly from inheritance unique and non overlapping Example valid uniform declarations assuming top of shader layout binding 3 offset 4 uniform atomic uint a offset 4 layout binding 2 uniform atomic_uint b offset 0 layout binding 3 uniform atomic uint c offset 8 layout binding 2 uniform atomic uint d offset 4 Example of an invalid uniform declaration layout offset 4 error must include binding layout binding 1 offset 0 a okay layout binding 2 offset 0 b okay layout binding 1 offset 0 c error offsets must not be shared between a andc layout binding 1 offset
205. o stream 2 layout stream 0 out default is now stream 0 out vec4 var5 var5 gets default stream 0 out Block2 Block2 gets default stream 0 vec4 var6 layout stream 3 out vec4 var var7 belongs to stream 3 Each vertex emitted by the geometry shader is assigned to a specific stream and the attributes of the emitted vertex are taken from the set of output blocks and variables assigned to the targeted stream After each vertex is emitted the values of all output variables become undefined Additionally the output variables associated with each vertex stream may share storage Writing to an output variable associated with one stream may overwrite output variables associated with any other stream When emitting each 75 4 4 2 4 4 Variables and Types vertex a geometry shader should write to all outputs associated with the stream to which the vertex will be emitted and to no outputs associated with any other stream If a geometry shader output block or variable is declared more than once all such declarations must associate the variable with the same vertex stream If any stream declaration specifies a non existent stream number the shader will fail to compile Built in geometry shader outputs are always associated with vertex stream zero All geometry shader output layout declarations in a program must declare the same layout and same value for max_vertices If geometry shaders are in a program there
206. o use the built in functions rather than do the equivalent computations in their own shader code since the built in functions are assumed to be optimal e g perhaps supported directly in hardware User code can replace built in functions with their own if they choose by simply redeclaring and defining the same name and argument list Because built in functions are in a more outer scope than user built in functions doing this will hide all built in functions with the same name as the redeclared function When the built in functions are specified below where the input arguments and corresponding output can be float vec2 vec3 or vec4 genType is used as the argument Where the input arguments and corresponding output can be int ivec2 ivec3 or ivec4 gen Type is used as the argument Where the input arguments and corresponding output can be uint uvec2 uvec3 or uvec4 genUType is used as the argument Where the input arguments or corresponding output can be bool bvec2 bvec3 or bvec4 genBType is used as the argument Where the input arguments and corresponding output can be double dvec2 dvec3 dvec4 genDType is used as the argument For any specific use of a function the actual types substituted for genType genlType genUType or genBType have to have the same number of components for all arguments and for the return type Similarly mat is used for any matrix basic type with single precision components and dmat is used for any m
207. oat image format qualifier int image format qualifier or uint 84 4 5 4 Variables and Types image format qualifier grammar rules respectively It is a compile time error to declare an image variable where the format qualifier does not match the image variable type Any image variable used for image loads or atomic operations must specify a format layout qualifier it is a compile time error to pass an image uniform variable or function parameter declared without a format layout qualifier to an image load or atomic function The binding identifier was described in section 4 4 5 Uniform and Shader Storage Block Layout Qualifiers Uniforms not qualified with writeonly must have a format layout qualifier Note that an image variable passed to a function for read access cannot be declared as writeonly and hence must have been declared with a format layout qualifier Interpolation Qualifiers Inputs and outputs that could be interpolated can be further qualified by at most one of the following interpolation qualifiers Qualifier Meaning smooth perspective correct interpolation flat no interpolation noperspective linear interpolation The presence of and type of interpolation is controlled by the above interpolation qualifiers as well as the auxiliary storage qualifiers centroid and sample The auxiliary storage qualifier patch is not used for interpolation it is a compile time error to use interpolation
208. oat lS 3 4 452 5 0 522 121 as an unnamed parameter void foo float 5 36 4 Variables and Types and as an alternate way of declaring a variable or function parameter float 5 a Arrays can have initializers formed from array constructors float a 5 float a 5 float 5 3 4 4 2 5 0 5 2 1 1 float 3 4 4 2 5 0 5 2 1 1 same thing An array of arrays can be declared as vec4 a 3 2 size 3 array of size 2 array of vec4 which declares a one dimensional array of size 3 of one dimensional arrays of size 2 of vee4s These following declarations do the same thing vec4 2 a 3 size 3 array of size 2 array of vec4 vec4 3 2 a size 3 array of size 2 array of vec4 When in transparent memory like in a uniform block the layout is that the inner most right most in declaration dimensions iterate faster than outer dimensions That is for the above the order in memory would be Low address a 0 0 a 0 1 a 1 0 a 1 1 a 2 0 a 2 1 High address The type of a needed for both constructors and nameless parameters is vec4 3 2 vec4 b 2 vec4 2 vec4 0 0 vec4 0 1 vec4 3 2 a vec4 3 2 b b b constructor void foo vec4 3 2 prototype with unnamed parameter Alternatively the initializer list syntax can be used to initialize an array of arrays vec4 a 3 2 vec4 2 vec4 0 0 vec4 1 0 vec4 2 vec4 0 0 vec4 1 0 vec4 2 vec4 0 0 vec4
209. obalInvocationID gl WorkGroupID gl WorkGroupSize gl LocalInvocationID The built in variable g Locallnvocationindex is a compute shader input variable that contains the one dimensional representation of the g LocallInvocationID This is useful for uniquely identifying a unique region of shared memory within the local work group for this invocation to use This is computed as gl_LocalInvocationIndex gl_LocalInvocationID z gl WorkGroupSize x gl WorkGroupSize y gl_LocalInvocationID y gl WorkGroupSize x gl_LocalInvocationID x The variable gl VertexID is a vertex language input variable that holds an integer index for the vertex as defined under Shader Inputs in section 11 1 3 9 Shader Inputs in the OpenGL Graphics System Specification While the variable g VertexID is always present its value is not always defined The variable gl InstancelD is a vertex language input variable that holds the instance number of the current primitive in an instanced draw call see Shader Inputs in section 11 1 3 9 Shader Inputs in the OpenGL Graphics System Specification If the current primitive does not come from an instanced draw call the value of g InstancelD is zero As an output variable g Position is intended for writing the homogeneous vertex position It can be written at any time during shader execution This value will be used by primitive assembly clipping culling and other fixed functionality ope
210. of instance 2 API uses Transform ModelViewMatrix to query an offset or other query transforms x a length same length for a for all x Transform x illegal must use transforms Transform a length illegal must use transforms transforms 2 a 3 if these are the only two dereferences of a transforms 3 a 7 then a must be size 8 for all transforms x For uniform or shader storage blocks declared as an array each individual array element corresponds to a separate buffer object bind range backing one instance of the block As the array size indicates the number of buffer objects needed uniform and shader storage block array declarations must specify an array size A uniform or shader storage block array can only be indexed with a dynamically uniform integral expression otherwise results are undefined When using OpenGL API entry points to identify the name of an individual block in an array of blocks the name string must include an array index e g Transform 2 When using OpenGL API entry points to refer to offsets or other characteristics of a block member an array index must not be specified e g Transform ModelViewMatrix Geometry shader input blocks must be declared as arrays and follow the array declaration and linking rules for all geometry shader inputs All other input and output block arrays must specify an array size 58 4 4 4 Variables and Types There are implem
211. oint matrix with 4 columns and 2 rows dmat4x3 a double precision floating point matrix with 4 columns and 3 rows dmat4x4 same as a dmat4 26 Floating Point Opaque Types 4 Variables and Types Type Meaning sampler1D a handle for accessing a 1D texture image1D sampler2D a handle for accessing a 2D texture image2D sampler3D a handle for accessing a 3D texture image3D samplerCube a handle for accessing a cube mapped texture imageCube sampler2DRect a handle for accessing a rectangle texture image2DRect sampler1DArray a handle for accessing a 1D array texture image1DArray sampler2DArray a handle for accessing a 2D array texture image2DArray samplerBuffer a handle for accessing a buffer texture imageBuffer sampler2DMS a handle for accessing a 2D multi sample texture image2DMS sampler2DMSArray a handle for accessing a 2D multi sample array texture image2DMSArray samplerCubeArray a handle for accessing a cube map array texture imageCubeArray sampler DShadow a handle for accessing a 1D depth texture with comparison sampler2DShadow a handle for accessing a 2D depth texture with comparison sampler2DRectShadow a handle for accessing a rectangle texture with comparison sampler DArrayShadow a handle for accessing a 1D array depth texture with comparison sampler2DArrayShadow a handle for accessing a 2D array depth texture with comparison samplerCubeShadow a handle for acces
212. on expression COMMA assignment_expression constant_expression conditional_expression declaration function_prototype SEMICOLON init_declarator_list SEMICOLON PRECISION precision_qualifier type_specifier SEMICOLON type qualifier IDENTIFIER LEFT BRACE struct_declaration_list RIGHT BRACE SEMICOLON type qualifier IDENTIFIER LEFT BRACE struct_declaration_list RIGHT BRACE IDENTIFIER SEMICOLON type qualifier IDENTIFIER LEFT BRACE struct_declaration_list RIGHT BRACE IDENTIFIER array_specifier SEMICOLON type_qualifier SEMICOLON type_qualifier IDENTIFIER SEMICOLON type_qualifier IDENTIFIER identifier list SEMICOLON identifier _list COMMA IDENTIFIER identifier_list COMMA IDENTIFIER function_prototype function_declarator RIGHT PAREN function_declarator function_header function_header_with_parameters function_header_with_parameters function_header parameter_declaration function_header_with_parameters COMMA parameter_declaration function_header fully_specified_type IDENTIFIER LEFT PAREN 193 9 Shading Language Grammar for Core Profile parameter_declarator type_specifier IDENTIFIER type_specifier IDENTIFIER array_specifier parameter_declaration type_qualifier parameter_declarator parameter_declarator type_qualifier parameter_type_specifier parameter_type_specifier parameter_type_specifier type_specifier init_declarator list single_declaration init_declarator_list COMMA IDENTIFIER init_declarator
213. on 4 vec4 e gets location 5 layout location 7 vec4 f gets location 7 vec4 g gets location 8 layout location 1 vec4 h gets location 1 vec4 i gets location 2 vec4 j gets location 3 vec4 k ERROR location 4 already used The number of input locations available to a shader is limited For vertex shaders the limit is the advertised number of vertex attributes For all other shaders the limit is implementation dependent and must be no less than one fourth of the advertised maximum input component count A program will fail to link if any attached shader uses a location greater than or equal to the number of supported locations unless device dependent optimizations are able to make the program fit within available hardware resources A program will fail to link if explicit location assignments leave the linker unable to find space for other variables without explicit assignments For the purposes of determining if a non vertex input matches an output from a previous shader stage the location layout qualifier if any must match If a vertex shader input variable with no location assigned in the shader text has a location specified through the OpenGL API the API assigned location will be used Otherwise such variables will be assigned a location by the linker See section 11 1 1 Vertex Attributes of the OpenGL Graphics System Specification for more details A link time error will occur if a
214. only one number the matrix is square Example matrix declarations mat2 mat2D mat3 optMatrix mat4 view projection mat4x4 view an alternate way of declaring a mat4 mat3x2 m a matrix with 3 columns and 2 rows dmat4 highPrecisionMVP dmat2x4 dm Initialization of matrix values is done with constructors described in section 5 4 Constructors in column major order Opaque Types The opaque types 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 The only opaque types that take memory qualifiers are the image types Except for array indexing structure member selection and parentheses opaque variables are not allowed to be operands in expressions such use results in a compile time error Opaque variables cannot be treated as l values hence cannot be used as out or inout function parameters nor can they be assigned into Any such use results in a compile time error However they can be passed as in parameters with matching type 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 stor
215. ons When these functions return the results of any memory stores performed using coherent variables performed prior to the call will be visible to any future coherent access to the same memory performed by any other shader invocation In particular the values written this way in one shader stage are guaranteed to be visible to coherent memory accesses performed by shader invocations in subsequent stages when those invocations were triggered by the execution of the original shader invocation e g fragment shader invocations for a primitive resulting from a particular geometry shader invocation Additionally memory barrier functions order stores performed by the calling invocation as observed by other shader invocations Without memory barriers if one shader invocation performs two stores to coherent variables a second shader invocation might see the values written by the second store prior to seeing those written by the first However if the first shader invocation calls a memory barrier function between the two stores selected other shader invocations will never see the results of the second store before seeing those of the first When using the function groupMemoryBarrier this ordering guarantee applies only to other shader invocations in the same compute shader work group all other memory barrier functions provide the guarantee to all other shader invocations No memory barrier is required to guarantee the order of memory stores as observed
216. onversions between calling argument and formal parameter types are compared for each function argument and pair of matching functions After these comparisons are performed each pair of matching functions are compared A function declaration A is considered a better match than function declaration B if e forat least one function argument the conversion for that argument in A is better than the corresponding conversion in B and 114 6 Statements and Structure e there is no function argument for which the conversion in B is better than the corresponding conversion in A If a single function declaration is considered a better match than every other matching function declaration it will be used Otherwise a compile time semantic error for an ambiguous overloaded function call occurs To determine whether the conversion for a single argument in one match is better than that for another match the following rules are applied in order 1 Anexact match is better than a match involving any implicit conversion 2 A match involving an implicit conversion from float to double is better than a match involving any other implicit conversion 3 A match involving an implicit conversion from either int or uint to float is better than a match involving an implicit conversion from either int or uint to double If none of the rules above apply to a particular pair of conversions neither conversion is considered better than the other For the ex
217. opt SEMICOLON conditionopt SEMICOLON expression jump_statement CONTINUE SEMICOLON BREAK SEMICOLON RETURN SEMICOLON RETURN expression SEMICOLON DISCARD SEMICOLON Fragment shader only Grammar Note No goto Gotos are not supported translation_unit external_declaration translation_unit external_declaration 202 9 Shading Language Grammar for Core Profile external declaration function _ definition declaration function _ definition function prototype compound statement no _new_scope 203 10 Normative References 10 Normative References 1 International Standard ISO IEC 14882 1998 E Programming Languages C Referenced for preprocessor only 204
218. or company names are used solely for identification and belong to their respective owners ii Table of Contents I CRUE Le PT AAE RA A EEREN 1 LR Acknowledgments rrisin e E EEN EE ed ORERE 2 12 CHINEES an nn E E E t 3 1 2 1 Changes since revision 8 of GLSL version 4 40 3 1 2 2 Changes since revision 7 of GLSL version AAO oasiiseccsssescarossteanoritiasticasaieinaivn 3 1 2 3 Changes since revision 6 of GLSL version 4 40 5 1 2 4 Summary of Changes from Revision 9 of GLSL Version 4 30 5 OR tn a rte on ris 8 1 4 Eitor Mr Rg a recess chien cn eee decked ested vise erie cesta E E ER EER S 8 1 5 Typ graphical Conventions enr a E E EEEE EEEREN ERA 9 OR en De E 9 2 Overview of OpenGL PME een mule ananas one 10 2 1 Vertex PROCESSOM Loisir ans r a saa ea E E soon iy ar tte dote ere 10 222 Tess llation Control PDO hdmi mnnniehenemndiaNunntai 10 2 3 Tessellation Evaluation ProcesSOm a ciciscscsacsensssnsssnscesessarennessnsicaansarsiaesserdennososandessassbensesen 11 2 4 oo PRES ne tante mettaient sise ete 11 2 5 Fragment PMO SSI ou nine sde AAA E 11 2 0 Compute TNE an aus nee a tr non 11 ee 13 3 1 Character Set and Phases of Compilation 355 35 554csnsrotibacannyshisanovatialesedundsantaedacabdemtiasencends 13 3 2 Source SUMAS anim E E EE E E E ERa 14 Re A EE 15 o OOTD E A E A E EE E AE EE TE 20 re Ko a a E E E E 21 3 6 KeyWords roret ne a R E E E E is EESE E O AE RESE ET 21 ee A E E a E A 23 By DIETIL E AE E A P NE B
219. or the same name as shown in the examples below in one compilation unit layout binding 3 uniform sampler2D s s bound to unit 3 in another compilation unit uniform sampler2D s okay s still bound at 3 in another compilation unit layout binding 4 uniform sampler2D s ERROR contradictory bindings Atomic Counter Layout Qualifiers The atomic counter qualifiers are layout qualifier id binding integer constant expression offset integer constant expression For example layout binding 2 offset 4 uniform atomic_uint a 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 A subsequent atomic counter declaration will inherit the previous post incremented offset For example a subsequent declaration of layout binding 2 uniform atomic_uint bar will establish that the atomic counter bar has a binding to buffer binding point 2 at an offset of 8 basic machine units into that buffer The offset for binding point 2 will again be post incremented by 4 the size of an atomic counter 82 4 4 6 2 4 Variables and Types When multiple variables 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 t
220. orm variable Bug 10659 Be even more clear that blocks generally cannot be redeclared as a way to size an unsized array contained in the block Bug 10735 Clarify that sampler type declarations can have precision qualifiers Bug 10682 Clarify that built in functions with void return or out arguments are not included in in the set of constant expressions Summary of Changes from Revision 9 of GLSL Version 4 30 Deprecations The built in noise functions are deprecated They are not removed but are defined to return 0 Built in constant g MaxCombinedImageUnitsAndFragmentOutputs is deprecated Built in constant gl MaxGeometryVaryingComponents is deprecated Changes Incorporate the ARB_enhanced_layouts extension which adds o compile time constant expressions for layout qualifier integers 1 Introduction o new offset and align layout qualifiers for control over buffer block layouts o add location layout qualifier for input and output blocks and block members o new component layout qualifier for finer grained layout control of input and output variables and blocks o new xfb_buffer xfb_stride and xfb_ offset layout qualifiers to allow the shader to control transform feedback buffering Bug 10530 To be consistent with ES include sample types as valid in a precision statement Note the defaults are irrelevant as precision qualifiers are not required or have any meaning Bug 10628 Subroutine arrays now require the ind
221. ors result if these rules are not followed The number of output locations available to a shader is limited For fragment shaders the limit is the advertised number of draw buffers For all other shaders the limit is implementation dependent and must be no less than one fourth of the advertised maximum output component count Compute shaders have no outputs A program will fail to link if any attached shader uses a location greater than or equal to the number of supported locations unless device dependent optimizations are able to make the program fit within available hardware resources Compile time errors may also be given if at compile time it is known the link will fail A negative output location will result in a compile time error It is also a compile time error if a fragment shader sets a layout index to less than 0 or greater than 1 A program will fail to link if any of the following occur e any two fragment shader output variables are assigned to the same location and index or e any two geometry shader output variables are assigned the same location and stream or 70 4 4 2 1 4 Variables and Types e if any two output variables from the same vertex or tessellation shader stage are assigned to the same location For fragment shader outputs locations can be assigned using either a layout qualifier or via the OpenGL API For all shader types a program will fail to link if explicit location assignments leave the linker unable t
222. oth single and double precision floating point Floating point variables are defined as in the following examples float a b 1 5 single precision floating point double c d 2 0LF double precision floating point As an input value to one of the processing units a single precision or double precision floating point variable is expected to match the corresponding IEEE 754 floating point definition for precision and dynamic range Floating point variables within a shader are also encoded according to the IEEE 754 specification for single precision floating point values logically not necessarily physically While encodings are logically IEEE 754 operations addition multiplication etc are not necessarily performed as required by IEEE 754 See section 4 7 1 Range and Precision for more details on precision and usage of NaNs Not a Number and Infs positive or negative infinities 31 4 1 5 4 1 6 4 Variables and Types Floating point constants are defined as follows floating constant fractional constant exponent part floating suffix opt digit sequence exponent part floating suffixop fractional constant digit sequence digit sequence digit sequence digit sequence exponent part e sign digit sequence opt E sign digit sequence sign one of Les digit sequence digit digit sequence digit floating suffix one of f F lf LF A decimal point is not needed if the exponent part is
223. outputs with double precision components the stride must be a multiple of 8 otherwise it must be a 72 4 Variables and Types multiple of 4 or a compile time or link time error results It is a compile time or link time error to have any xfb_offset that overflows xfb_stride whether stated on declarations before or after the xfb_stride or in different compilation units While xfb_stride can be declared multiple times for the same buffer it is a compile time or link time error to have different values specified for the stride for the same buffer For example buffer 1 has 32 byte stride layout xfb buffer 1 xfb stride 32 out same as previous example order within layout does not matter layout xfb stride 32 xfb buffer 1 out everything in this block goes to buffer 0 layout xfb buffer 0 xfb stride 32 out blockl layout xfb offset 0 vec4 a a goes to byte offset 0 of buffer 0 layout xfb offset 16 vec4 b b goes to offset 16 of buffer 0 layout xfb buffer 3 xfb offset 12 out block vec4 v v will be written to byte offsets 12 through 27 of buffer float u u will be written to offset 28 layout xfb_ offset 40 vec4 w vec4 x x will be written to offset 56 the next available offset layout xfb buffer 2 xfb stride 32 out block3 layout xfb offset 12 vec3 c layout xfb offset 24 vec3 d ERROR requires stride of 36 l
224. p exclusive or and inclusive or The operands must be of type signed or unsigned integers or integer vectors The operands cannot be vectors of differing size this is a compile time error If one operand is a scalar and the other a vector the scalar is applied component wise to the vector resulting in the same type as the vector The fundamental types of the operands signed or unsigned must match and will be the resulting fundamental type For and amp the result is the bitwise and function of the operands For exclusive or the result is the bitwise exclusive or function of the operands For inclusive or the result is the bitwise inclusive or function of the operands For a complete specification of the syntax of expressions see section 9 Shading Language Grammar Vector and Matrix Operations With a few exceptions operations are component wise Usually when an operator operates on a vector or matrix it is operating independently on each component of the vector or matrix in a component wise fashion For example vec3 v u float f v u f will be equivalent to v x u x f vey u y f v z u z f And vec3 v u W w v u will be equivalent to W X V X u x w y v y u y W Z V Z U Z and likewise for most operators and all integer and floating point vector and matrix types The exceptions are matrix multiplied by vector vector multiplied by matrix and matrix
225. perator User defined types may be defined using struct to aggregate a list of existing types into a single name The OpenGL Shading Language is type safe There are some implicit conversions between types Exactly how and when this can occur is described in section 4 1 10 Implicit Conversions and as referenced by other sections in this specification 4 1 Basic Types The OpenGL Shading Language supports the following basic data types grouped as follows Transparent types Type Meaning void for functions that do not return a value bool a conditional type taking on values of true or false int a signed integer uint an unsigned integer float a single precision floating point scalar double a double precision floating point scalar vec2 a two component single precision floating point vector vec3 a three component single precision floating point vector vec4 a four component single precision floating point vector dvec2 a two component double precision floating point vector dvec3 a three component double precision floating point vector dvec4 a four component double precision floating point vector bvec2 a two component Boolean vector bvec3 a three component Boolean vector bvec4 a four component Boolean vector ivec2 a two component signed integer vector 25 4 Variables and Types
226. pler ivec2 P int lod gvec4 texelFetch gsampler3D sampler ivec3 P int lod gvec4 texelFetch gsampler2DRect sampler ivec2 P gvec4 texelFetch gsampler DArray sampler ivec2 P int lod gvec4 texelFetch gsampler2DArray sampler ivec3 P int lod gvec4 texelFetch gsamplerBuffer sampler int P gvec4 texelFetch gsampler2DMS sampler ivec2 P int sample gvec4 texelFetch gsampler2DMSArray sampler ivec3 P int sample Use integer texture coordinate P to lookup a single texel from sampler The array layer comes from the last component of P for the array forms The level of detail od if present is as described in sections 11 1 3 2 Texel Fetches and 8 14 1 Scale Factor and Level of Detail of the OpenGL Graphics System Specification 165 8 Built in Functions Syntax Description gvec4 texelFetchOffset gsampler1D sampler int P int lod int offset gvec4 texelFetchOffset gsampler2D sampler ivec2 P int lod ivec2 offset gvec4 texelFetchOffset gsampler3D sampler ivec3 P int lod ivec3 offset gvec4 texelFetchOffset gsampler2DRect sampler ivec2 P ivec2 offset gvec4 texelFetchOffset gsampler1 DArray sampler ivec2 P int lod int offset gvec4 texelFetchOffset gsampler2DArray sampler ivec3 P int lod ivec2 offset Fetch a single texel as in texelFetch offset by offset as described in textureOffset gvec4 textureProjOffset gsampler1D sampler vec2 P int offset
227. pler3D sampler vec3 P ivec3 offset float bias gvec4 textureOffset gsampler2DRect sampler vec2 P ivec2 offset float textureOffset sampler2DRectShadow sampler vec3 P ivec2 offset float textureOffset sampler DShadow sampler vec3 P int offset float bias float textureOffset sampler2DShadow sampler vec3 P ivec2 offset float bias gvec4 textureOffset gsampler DArray sampler vec2 P int offset float bias gvec4 textureOffset gsampler2DArray sampler vec3 P ivec2 offset float bias float textureOffset sampler DArrayShadow sampler vec3 P int offset float bias float textureOffset sampler2DArrayShadow sampler vec4 P ivec2 offset Do a texture lookup as in texture but with offset added to the u v w texel coordinates before looking up each texel The offset value must be a constant expression A limited range of offset values are supported the minimum and maximum offset values are implementation dependent and given by gl MinProgramTexelOffset and gl MaxProgramTexelOffset respectively Note that offset does not apply to the layer coordinate for texture arrays This is explained in detail in section 8 14 2 Coordinate Wrapping and Texel Selection of the OpenGL Graphics System Specification where offset is 8 6 Note that texel offsets are also not supported for cube maps gvec4 texelFetch gsampler1D sampler int P int lod gvec4 texelFetch gsampler2D sam
228. ponents 128 const int gl MaxVertexTexturelmageUnits 16 const int gl MaxCombinedTexturelmageUnits 96 const int gl MaxTexturelmageUnits 16 const int gl MaxImageUnits 8 const int gl MaxCombinedImageUnitsAndFragmentOutputs 8 const int gl MaxCombinedShaderOutputResources 8 const int gl MaxImageSamples 0 const int gl MaxVertexImageUniforms 0 const int gl MaxTessControlImageUniforms 0 const int gl MaxTessEvaluationImageUniforms 0 const int gl MaxGeometryImageUniforms 0 const int gl MaxFragmentImageUniforms 8 const int gl MaxCombinedImageUniforms 8 const int gl MaxFragmentUniformComponents 1024 const int gl MaxDrawBuffers 8 const int gl MaxClipDistances 8 const int gl MaxGeometryTexturelmageUnits 16 const int gl MaxGeometryOutputVertices 256 const int gl MaxGeometryTotalOutputComponents 1024 const int gl MaxGeometryUniformComponents 1024 const int gl MaxGeometryVaryingComponents 64 134 deprecated deprecated const const const const const const const const const const const const const const const const const const const const const const const const const const const const const const const const const const int int int int int int int int int int int int int int int int int int int int int int int int int int int int int ant int int i
229. ponents of P and compute the level of detail information that the texture pipe would use to access that texture through a normal texture lookup The level of detail 2 equation 3 18 in the OpenGL Graphics System Specification is obtained after any LOD bias but prior to clamping to TEXTURE MIN LOD TEXTURE MAX LOD The mipmap array s that would be accessed are also computed If a single level of detail would be accessed the level of detail number relative to the base level is returned If multiple levels of detail would be accessed a floating point number between the two levels is returned with the fractional part equal to the fractional part of the computed and clamped level of detail 161 8 Built in Functions The algorithm used is given by the following pseudo code float ComputeAccessedLod float computedLod Clamp if computedLod lt TEXTURE MIN LOD computedLod gt TEXTURE MAX LOD Fh H i maxAccessibleLevel Re if T return 0 0 else if return ceil computedLod 0 5 computedLod 0 0 if computedLod gt the computed LOD according to the texture LOD clamps computedLod TEXTURE MIN LOD computedLod TEXTURE MAX LOD Clamp the computed LOD to the range of accessible levels f computedLod lt 0 0 float computedLod float maxAccessibleLevel turn a value according to the min filter E
230. ponsible for describing the transform feedback setup This mode will capture any output selected by xfb_offset directly or indirectly to a transform feedback buffer The xfb_buffer qualifier specifies which transform feedback buffer will capture outputs selected with xfb_offset The xfb_buffer qualifier can be applied to the qualifier out to output variables to output blocks and to output block members Shaders in the transform feedback capturing mode have an initial global default of layout xfb buffer 0 out This default can be changed by declaring a different buffer with xfb_buffer on the interface qualifier out This is the only way the global default can be changed When a variable or output block is declared without an xfb_buffer qualifier it inherits the global default buffer When a variable or output block is declared with an xfb_buffer qualifier it has that declared buffer All members of a block inherit the block s buffer A member is allowed to declare an xfb_buffer but it must match the buffer inherited from its block or a compile time error results 71 4 Variables and Types layout xfb buffer 2 xfb offset 0 out block block s buffer is 2 layout xfb buffer 2 vec4 v okay matches the inherited 2 layout xfb buffer 3 vec4 u ERROR mismatched buffer vec4 w inherited layout xfb offset 16 out vec4 t initial default is buffer 0 layout xfb buffer 1 out new global default of 1
231. putes a new value by performing a bit wise int atomicXor inout int mem int data EXCLUSIVE OR of the value of data and the contents of mem uint atomicExchange inout uint mem uint data Computes a new value by simply copying the value int atomicExchange inout int mem int data of data uint atomicCompSwap inout uint mem Compares the value of compare and the contents of uint compare uint data mem If the values are equal the new value is given int atomicCompSwap inout int mem by data otherwise it is taken from the original int compare int data contents of mem Image Functions Variables using one of the image basic types may be used by the built in shader image memory functions defined in this section to read and write individual texels of a texture Each image variable references an image unit which has a texture image attached When image memory functions below access memory an individual texel in the image is identified using an i i j or i j coordinate corresponding to the values of P For image2DMS and image2DMSArray variables and the corresponding int unsigned int types corresponding to multi sample textures each texel may have multiple samples and an individual sample is identified using the 176 8 Built in Functions integer sample parameter The coordinates and sample number are used to select an individual texel in the manner described in section 8 25 Texture Image Loads and Stores
232. qualifiers with patch A variable qualified as flat will not be interpolated Instead it will have the same value for every fragment within a triangle This value will come from a single provoking vertex as described by the OpenGL Graphics System Specification A variable may be qualified as flat can also be qualified as centroid or sample which will mean the same thing as qualifying it only as flat A variable qualified as smooth will be interpolated in a perspective correct manner over the primitive being rendered Interpolation in a perspective correct manner is specified in equation 14 7 in the OpenGL Graphics System Specification section 14 5 Line Segments A variable qualified as noperspective must be interpolated linearly in screen space as described in equation 3 7 in the OpenGL Graphics System Specification section 3 5 Line Segments When multi sample rasterization is disabled or for fragment shader input variables qualified with neither centroid nor sample the value of the assigned variable may be interpolated anywhere within the pixel and a single value may be assigned to each sample within the pixel to the extent permitted by the OpenGL Graphics System Specification When multisample rasterization is enabled centroid and sample may be used to control the location and frequency of the sampling of the qualified fragment shader input If a fragment shader input is qualified with centroid a single value may be assigned
233. r are discussed in separate sections below All shaders except compute shaders allow location layout qualifiers on input variable declarations input block declarations and input block member declarations Of these variables and block members but not blocks additionally allow the component layout qualifier The layout qualifier identifiers for inputs are layout qualifier id location integer constant expression component integer constant expression Where integral constant expression is defined in section 4 3 3 Constant Expressions as integral constant expression For example layout location 3 in vec4 normal const int start 6 layout location start 2 int vec4 v will establish that the shader input normal is assigned to vector location number 3 and v is assigned location number 8 For vertex shader inputs the location specifies the number of the generic vertex 61 4 Variables and Types 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
234. r less than 0 Arrays only have a single dimension a single entry within however arrays of arrays can be declared All types basic types structures arrays can be formed into an array All arrays are inherently homogeneous made of elements all having the same type and size with one exception The exception is a shader storage block having an unsized array as its last member run time sized an array can be formed from such a shader storage block even if the storage blocks have differing lengths for their last member Some examples are float frequencies 3 uniform vec4 lightPosition 4 light lights const int numLights 2 light lights numLights a shader storage block introduced in section 4 3 7 buffer variables buffer b float u an error unless u gets statically sized by link time vec4 vi okay v will be sized dynamically if not statically name 3 when the block is arrayed all u will be the same size but not necessarily all v if sized dynamically An array type can be formed by specifying non array type followed by an array specifier All dimensions of such an array specifier must include a size float 5 an array of size 5 of float float 2 3 an array of size 2 3 of float not size 3 of float 2 This type can be used anywhere any other type can be used including as the return value from a function float 5 foo as a constructor of an array Fl
235. r the purposes of determining if an output from one shader stage matches an input of the next stage the precise qualifier need not match between the input and the output All constant expressions are evaluated as if precise was present whether or not it is present However as described in section 4 3 3 Constant Expressions there is no requirement that a compile time constant expression evaluates to the same value as a corresponding non constant expression Memory Qualifiers Variables declared as image types the basic opaque types with image in their keyword can be further qualified with one or more of the following memory qualifiers 94 4 Variables and Types Qualifier Meaning coherent memory variable where reads and writes are coherent with reads and writes from other shader invocations volatile memory variable whose underlying value may be changed at any point during shader execution by some source other than the current shader invocation restrict memory variable where use of that variable is the only way to read and write the underlying memory in the relevant shader stage readonly memory variable that can be used to read the underlying memory but cannot be used to write the underlying memory writeonly memory variable that can be used to write the underlying memory but cannot be used to read the underlying memory Memory accesses to image variables declared using the coherent qu
236. rations if present that operate on primitives after vertex processing has occurred Its value is undefined after the vertex processing stage if the vertex shader executable does not write g Position and it is undefined after geometry processing if the geometry executable calls EmitVertex without having written g Position since the last EmitVertex or hasn t written it at all As an input variable g Position reads the output written in the previous shader stage to gl Position As an output variable gl PointSize is intended for a shader to write the size of the point to be rasterized It is measured in pixels If g PointSize is not written to its value is undefined in subsequent pipe stages As an input variable gl PointSize reads the output written in the previous shader stage to gl PointSize The variable gl ClipDistance provides the forward compatible mechanism for controlling user clipping The element g ClipDistance i specifies a clip distance for each plane i A distance of 0 means the vertex is on the plane a positive distance means the vertex is inside the clip plane and a negative distance means the point is outside the clip plane The clip distances will be linearly interpolated across the primitive and the portion of the primitive with interpolated distances less than 0 will be clipped 125 7 Built in Variables The gi ClipDistance array is predeclared as unsized and must be explicitly sized by the shader either redeclar
237. rature flat in vec3 myColor noperspective centroid in vec2 myTexCoord The fragment shader inputs form an interface with the last active shader in the vertex processing pipeline For this interface the last active shader stage output variables and fragment shader input variables of the same name must match in type and qualification with a few exceptions The storage qualifiers must of course differ one is in and one is out Also interpolation qualification e g flat and auxiliary qualification e g centroid may differ These mismatches are allowed between any pair of stages When interpolation or auxiliary qualifiers do not match those provided in the fragment shader supersede those provided in previous stages If any such qualifiers are completely missing in the fragment shaders then the default is used rather than any qualifiers that may have been declared in previous stages That is what matters is what is declared in the fragment shaders not what is declared in shaders in previous stages When an interface between shader stages is formed using shaders from two separate program objects it is not possible to detect mismatches between inputs and outputs when the programs are linked When there are mismatches between inputs and outputs on such interfaces the values passed across the interface will be partially or completely undefined Shaders can ensure matches across such interfaces either by using input and output layout qualifier
238. rd keyword the fragment is discarded and the values of any user defined fragment outputs g FragDepth and gl SampleMask become irrelevant The variable gl FragCoord is available as an input variable from within fragment shaders and it holds the window relative coordinates x y z 1 w values for the fragment If multi sampling this value can be for any location within the pixel or one of the fragment samples The use of centroid does not further restrict this value to be inside the current primitive This value is the result of the fixed functionality that interpolates primitives after vertex processing to generate fragments The z component is the depth value that would be used for the fragment s depth if no shader contained any writes to g FragDepth This is 128 7 Built in Variables useful for invariance if a shader conditionally computes gl FragDepth but otherwise wants the fixed functionality fragment depth Fragment shaders have access to the input built in variable g _FrontFacing whose value is true if the fragment belongs to a front facing primitive One use of this is to emulate two sided lighting by selecting one of two colors calculated by a vertex or geometry shader The values in g PointCoord are two dimensional coordinates indicating where within a point primitive the current fragment is located when point sprites are enabled They range from 0 0 to 1 0 across the point If the current primitive is not a point or if poi
239. red user defined variable as being precise out vec3 Color precise Color make existing Color be precise This qualifier will affect the evaluation of an r value in a particular function if and only if the result is eventually consumed in the same function by an l value qualified as precise Any other expressions within a function are not affected including return values and output parameters not declared as precise but that are eventually consumed outside the function by an variable qualified as precise 93 4 10 Some examples of the use of precise in vec4 a b c d precise out vec4 v float func float e float f float g float h return e f g h 4 Variables and Types no constraint on order or operator consistency float func2 float e float f float g precise float result e f g h float h nsures same precision for the two multiplies return result float func3 float i float j k i tit 4 void main vec3 r vec3 a b precise vec3 s vec3 c d precise v exyz r sS v w a w b w c w d w v x func a x b x C X d x v x func2 a x b x c x d x func3 a x b x c x d x v x precise precise out float k due to lt k gt declaration used to compute v xyz used to compute v xyz precise precise values computed in func are NOT precise precise precise Fo
240. red with the extension directive extension extension name behavior extension all behavior where extension name is the name of an extension Extension names are not documented in this specification The token all means the behavior applies to all extensions supported by the compiler The behavior can be one of the following behavior Effect require Behave as specified by the extension extension name Give a compile time error on the extension if the extension extension name is not supported or if all is specified enable Behave as specified by the extension extension_name Warn on the extension if the extension extension_name is not supported Give a compile time error on the extension if all is specified warn Behave as specified by the extension extension_name except issue warnings on any detectable use of that extension unless such use is supported by other enabled or required extensions If all is specified then warn on all detectable uses of any extension used Warn on the extension if the extension extension_name is not supported disable Behave including issuing errors and warnings as if the extension extension_name is not part of the language definition If all is specified then behavior must revert back to that of the non extended core version of the language being compiled to Warn on the extension if the extension extension_name is not supported The extension directiv
241. redetermined prototypes For arrays and structures there must be exactly one argument in the constructor for each element or member For the other types the arguments must provide a sufficient number of components to perform the initialization and it is a compile time error to include so many arguments that they cannot all be used Detailed rules follow The prototypes actually listed below are merely a subset of examples Conversion and Scalar Constructors Converting between scalar types is done as the following prototypes indicate int uint converts an unsigned integer to a signed integer int bool converts a Boolean value to an int int float converts a float value to an int int double converts a double value to a signed integer uint int converts a signed integer value to an unsigned integer uint bool converts a Boolean value to an unsigned integer uint float converts a float value to an unsigned integer uint double converts a double value to an unsigned integer bool int converts a signed integer value to a Boolean bool uint converts an unsigned integer value to a Boolean value bool float converts a float value to a Boolean bool double converts a double value to a Boolean float int converts a signed integer value to a float float uint converts an unsigned integer value to a float value float bool converts a Boolean value to a float flo
242. rived variables in uvec3 gl in uint gl _GlobaliInvocationID _LocalInvocationIndex In the vertex language the built ins are intrinsically declared as in int gl VertexID in int gl_InstancelID out gl PerVertex vec4 gl Position float gl PointSize float gl ClipDistance 122 7 Built in Variables In the geometry language the built in variables are intrinsically declared as in gl PerVertex vec4 gl Position float gl PointSize float gl_ClipDistance gl_in in int gl PrimitivelDIn in int gl InvocationID out gl PerVertex vec4 gl Position float gl PointSize float gl_ClipDistance out int gl PrimitivelD out int gl Layer out int gl ViewportIndex In the tessellation control language built in variables are intrinsically declared as in gl PerVertex vec4 gl Position float gl PointSize float gl _ClipDistance gl _in gl MaxPatchVertices in int gl PatchVerticesIn in int gl PrimitivelID in int gl InvocationID out gl PerVertex vec4 gl Position float gl PointSize float gl_ClipDistance gl out patch out float gl_TessLevelOuter 4 patch out float gl TessLevelInner 2 In the tessellation evaluation language built in variables are intrinsically declared as in gl PerVertex vec4 gl Position float gl PointSize float gl _ClipDistance gl _in gl MaxPatchVertices in int gl PatchVerticesIn 123 7 Built in Variabl
243. rix type e A structure Fragment outputs are declared as in the following examples out vec4 FragmentColor out uint Luminosity 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 Buffer Variables The buffer qualifier is used to declare global variables whose values are stored in the data store of a buffer object bound through the OpenGL 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 section 4 10 Memory Qualifiers The buffer qualifier can be used to declare interface blocks section 4 3 9 Interface Blocks which are then referred to as shader storage blocks It is a compile time error to declare buffer variables at global scope outside a block 53 4 3 8 4 3 9 4 Variables and Types use buffer to create a buffer block shader storage block buffer BufferName e
244. rwise built in types previously declared structures and arrays of these are allowed as the type of a declarator in the same manner they are allowed outside a block 55 4 Variables and Types 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 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 an in out patch uniform or buffer interface qualifier for a member s storage qualifier is optional For example in Material smooth in vec4 Colorl legal input inside in block smooth vec4 Color2 legal in inherited from in Material vec2 TexCoord legal TexCoord is an input uniform float Atten illegal mismatched storage qualifier For this section define a shader interface to be one of these e All the uniform variables and uniform blocks declared in a program This spans all compilation units linked together within one program e All the buffer blocks declared in a program e The boundary between adjacent programmable pipeline stages
245. s Syntax deprecated Description deprecated vec4 shadow1D sampler DShadow sampler vec3 coord float bias vec4 shadow2D sampler2DShadow sampler vec3 coord float bias vec4 shadow1DProj sampler DShadow sampler vec4 coord float bias vec4 shadow2DProj sampler2DShadow sampler vec4 coord float bias vec4 shadow1DLod sampler DShadow sampler vec3 coord float lod vec4 shadow2DLod sampler2DShadow sampler vec3 coord float lod vec4 shadow1DProjLod sampler DShadow sampler vec4 coord float lod vec4 shadow2DProjLod sampler2DShadow sampler vec4 coord float lod Same functionality as the texture based names above with the same signature 174 8 10 8 11 8 Built in Functions Atomic Counter Functions The atomic counter operations in this section operate atomically with respect to each other They are atomic for any single counter meaning any of these operations on a specific counter in one shader instantiation will be indivisible by any of these operations on the same counter from another shader instantiation There is no guarantee that these operations are atomic with respect to other forms of access to the counter or that they are serialized when applied to separate counters Such cases would require additional use of fences barriers or other forms of synchronization if atomicity or serialization is desired The value returned by an atomic counter function is the va
246. s 1 3 1 4 1 Introduction e Bug 10593 Clarify that within a declaration if inout is used neither in nor out may be used and none of these can be repeated e Minor editorial changes for consistency with the OpenGL ES language specification e Bug 11702 Errors for reserved symbols are clarified gl_ in a GLSL name is an error use of GL_ in a preprocessor macro name is an error Use of consecutive double underscores is reserved but not an error e Bug 11987 Allow array of array constructors and initialized variables to have any dimension unsized not just the outer dimension and get their size from the content of the constructor or initializer e Bug 12032 Be clear that float 3 2 means logically float 3 2 not float 3 2 e Bug 11856 Clarifications on switch statements The switch s form a nested name scope and case default can t be nested in deeper than that scope Removed the rule about having no statement between a label and the end of the switch statement existing compiler errors for this can turn into a warning e Bug 11180 Clarify behavior of frexp and Idexp at boundary conditions e Bug 11635 State in more places that and don t apply to opaque types Overview This document describes The OpenGL Shading Language version 4 40 Independent compilation units written in this language are called shaders A program is a set of shaders that are compiled and linked
247. s matrixCompMult and outerProduct to get respectively vector dot product vector cross product matrix component wise multiplication and the matrix product of a column vector times a row vector The operator modulus operates on signed or unsigned integer scalars or integer vectors If the fundamental types in the operands do not match then the conversions from section 4 1 10 Implicit Conversions are applied to create matching types The operands cannot be vectors of differing size this is a compile time error If one operand is a scalar and the other vector then the scalar is applied component wise to the vector resulting in the same type as the vector If both are vectors of the same size the result is computed component wise The resulting value is undefined for any component computed with a second operand that is zero while results for other components with non zero second operands remain defined If both operands are non negative then the remainder is non negative Results are undefined if one or both operands are negative The operator modulus is not defined for any other data types non integer types The arithmetic unary operators negate post and pre increment and decrement and operate on integer or floating point values including vectors and matrices All unary operators work component wise on their operands These result with the same type they operated on For post and pre increment and decrement the
248. s sections 4 4 1 Input Layout Qualifiers and 4 4 2 Output Layout Qualifiers or by using identical input and output declarations of blocks or variables Complete rules for interface matching between programs are found in section 7 4 1 Shader Interface Matching of the OpenGL Graphics System Specification Compute shaders do not permit user defined input variables and do not form a formal interface with any other shader stage See section 7 1 Built In Variables for a description of built in compute shader input variables All other input to a compute shader is retrieved explicitly through image loads texture fetches loads from uniforms or uniform buffers or other user supplied code Redeclaration of built in input variables in compute shaders is not permitted Uniform Variables The uniform qualifier is used to declare global variables whose values are the same across the entire primitive being processed All uniform variables are read only and are initialized externally either at link time or through the API The link time initial value is either the value of the variable s initializer if present or 0 if no initializer is present Opaque types cannot have initializers or a compile time error results Example declarations are uniform vec4 lightPosition uniform vec3 color vec3 0 7 0 7 0 2 value assigned at link time The uniform qualifier can be used with any of the basic data types or when declaring a variab
249. s in a compile time error Bit fields are not supported Member types must be already defined there are no forward references 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 an integral constant expression that s greater than zero see section 4 3 3 Constant Expressions Each level of structure has its own name space for names given in member declarators such names need only be unique within that name space Anonymous structures are not supported Embedded structure definitions are not supported These result in compile time errors struct S float f struct T S Error anonymous structures disallowed struct Error embedded structures disallowed S s Okay nested structures with name are allowed Structures can be initialized at declaration time using constructors as discussed in section 5 4 3 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 Arrays Variables of the same type can be aggregated into arrays by declaring a name followed by brackets enclosing an optional size When an array size is specified in a declaration it must be an integral constant expression see section 4 3 3
250. s is determined by the type of the internal format of the texture Texture lookups on unsigned normalized integer and floating point data return floating point values in the range 0 1 Texture lookup functions are provided that can return their result as floating point unsigned integer or signed integer depending on the sampler type passed to the lookup function Care must be taken to use the right sampler type for texture access The following table lists the supported combinations of sampler types and texture internal formats Blank entries are unsupported Doing a texture lookup will return undefined values for unsupported combinations nol Tete Format ening ot ec Ue oe Floating point Supported Normalized Integer Supported Signed Integer Supported Unsigned Integer Supported If an integer sampler type is used the result of a texture lookup is an ivec4 If an unsigned integer sampler type is used the result of a texture lookup is a uvec4 If a floating point sampler type is used the result of a texture lookup is a vec4 where each component is in the range 0 1 ce 66 99 In the prototypes below the g in the return type gvec4 is used as a placeholder for nothing i or u making a return type of vec4 ivec4 or uvec4 In these cases the sampler argument type also starts with go indicating the same substitution done on the return type it is either a single precision flo
251. savaien chenoainsadensooapnaioaiiavebansiensa tentes sinke ioiii 44 Layout OMS em dan rO a E E E E EE S ed EE a TER 4 4 1 Taput Layout QualifietS rreri note es 4 4 1 1 Tessellation Evaluation pulse ereina a aaia 4 4 1 2 Geometry Shader MANS ner tan inseri rriaire ranit Ee sra 4 4 1 3 Eragment Shader IDD NOE EEEE E EE 4 4 1 4 Compute Shader TS serisini anrea i E E E AEAEE 4 4 2 Output Layout Qualifiers cs nnscessisvsicanionasdeadveveceunpannencatiwencannsandaexecneiieneunyentarturaeaiadawne 4 4 2 1 Transform Feedback Layout Calinees is cisseivestsinesdsavesancctsustuatsiansssneseveoassanes 442 2 Tessellation Control FAT ic nent neue nee 4 4 2 3 Geometry Cul sirinin a EE EE EA E 442A Fragment PDU amande E A E mesa enue ETER ERRES 4 4 3 Uniform Va able Layo t Qualifiers isseire erii i i 4 4 4 S bro tine F nction Layout Qualifiers siseses senii n a ar E R EE 4 4 5 Uniform and Shader Storage Block Layout Qualifiers 4 4 6 Opaque Uniform Layout Qualifiers ss 44 6 1 Atomic Counter Layout Quali erg ssis soisin 4 4 6 2 Format OO RS eks a R Es EEEa EE EVERE EEEE E 4 5 Interpolation QUARMERS isonmsnentureneenmtennenonaesencmemntimenonerttnan 4 5 1 Redeclaring Built in Interpolation Variables in the Compatibility Profile 4 6 Parameter CMe uenisse riea EAEE aa ets em ere alee SESS iv 47 Precision and Precision DOM USRS nnmemamammm
252. sed as float texture samplerCubeShadow sampler vec4 PT float bias D and the array layer comes gvec4 texture gsamplerl DArray sampler vec2 P float bias from P w When compare is not gvec4 texture gsampler2DArray sampler vec3 P float bias present the last component of gvec4 texture gsamplerCubeArray sampler vec4 PT float bias P is used as D and the array float texture sampler DArrayShadow sampler vec3 P layer comes from the second to float bias last component of P The float texture sampler2DArrayShadow sampler vec4 P second component of P is gvec4 texture gsampler2DRect sampler vec2 P unused for 1D shadow lookups float texture sampler2DRectShadow sampler vec3 P float texture gsamplerCubeArrayShadow sampler vec4 P float compare For non shadow forms the array layer comes from the last component of P gvec4 textureProj gsampler1D sampler vec2 P float bias Do a texture lookup with gvec4 textureProj gsampler1D sampler vec4 P float bias projection The texture gvec4 textureProj gsampler2D sampler vec3 P float bias coordinates consumed from P gvec4 textureProj gsampler2D sampler vec4 P float bias not including the last component gvec4 textureProj gsampler3D sampler vec4 P float bias of P are divided by the last float textureProj sampler DShadow sampler vec4 P component of P The resulting float bias 3 component of P in the float textureProj sa
253. ses of the backslash beyond use as the line continuation character Lines are relevant for compiler diagnostic messages and the preprocessor They are terminated by carriage return or line feed If both are used together it will count as only a single line termination For the remainder of this document any of these combinations is simply referred to as a new line In general the language s use of this character set is case sensitive There are no character or string data types so no quoting characters are included There is no end of file character More formally compilation happens as if the following logical phases were executed in order 1 Source strings are concatenated to form a single input All provided new lines are retained 2 Line numbering is noted based on all present new lines and does not change when new lines are later eliminated 3 Wherever a backslash occurs immediately before a new line both are eliminated Note no white space is substituted allowing a single token to span a new line Any newly formed backslash followed by a new line is not eliminated only those pairs originally occurring after phase 1 are eliminated 4 All comments are replaced with a single space Note that style comments end before their terminating new lines and white space is generally relevant to preprocessing 5 Preprocessing is done resulting in a sequence of GLSL tokens formed from the character set stated above 6
254. shader this results in a compile time error However as noted in the specification there are some cases where previously declared variables can be redeclared and predeclared gl_ names are allowed to be redeclared in a shader only for these specific purposes More generally it is a compile time error to redeclare a variable including those starting gl Definitions Some language rules described below depend on the following definitions 23 3 8 1 3 8 2 3 8 3 3 Basics Static Use A shader contains a static use of or static assignment to a variable x if after preprocessing the shader contains a statement that would read or write x whether or not run time flow of control will cause that statement to be executed Uniform and Non Uniform Control Flow When executing statements in a fragment shader control flow starts as uniform control flow all fragments enter the same control path into main Control flow becomes non uniform when different fragments take different paths through control flow statements selection iteration and jumps Control flow subsequently returns to being uniform after such divergent sub statements or skipped code completes until the next time different control paths are taken For example main float a this is uniform flow control if a lt b this expression is true for some fragments not all SRE non uniform flow control else N non uniform flow control
255. sing a cube map depth texture with comparison samplerCubeArrayShadow a handle for accessing a cube map array depth texture with comparison Signed Integer Opaque Types Type Meaning isampler1D a handle for accessing an integer 1D texture iimage1D 27 4 Variables and Types Type Meaning isampler2D a handle for accessing an integer 2D texture iimage2D isampler3D a handle for accessing an integer 3D texture iimage3D isamplerCube a handle for accessing an integer cube mapped texture iimageCube isampler2DRect a handle for accessing an integer 2D rectangle texture iimage2DRect isampler1DArray a handle for accessing an integer 1D array texture iimage1DArray isampler2DArray a handle for accessing an integer 2D array texture iimage2DArray isamplerBuffer a handle for accessing an integer buffer texture iimageBuffer isampler2DMS a handle for accessing an integer 2D multi sample texture iimage2DMS isampler2DMSArray a handle for accessing an integer 2D multi sample array texture iimage2DMSArray isamplerCubeArray a handle for accessing an integer cube map array texture iimageCubeArray Unsigned Integer Opaque Types Type Meaning atomic_uint a handle for accessing an unsigned integer atomic counter usampler1D a handle for accessing an unsigned integer 1D texture uimage1D usampler2D a handle for accessing an unsigned integer
256. specifies the 16 least significant bits of the result the second component specifies the 16 most significant bits 150 8 Built in Functions Syntax Description vec2 unpackHalf2x16 uint v Returns a two component floating point vector with components obtained by unpacking a 32 bit unsigned integer into a pair of 16 bit values interpreting those values as 16 bit floating point numbers according to the OpenGL Specification and converting them to 32 bit floating point values The first component of the vector is obtained from the 16 least significant bits of v the second component is obtained from the 16 most significant bits of v 151 8 5 Geometric Functions 8 Built in Functions These operate on vectors as vectors not component wise Syntax Description float length genType x double length genDType x Returns the length of vector x 1 e Valo x fE float distance genType p0 genType p1 double distance genDType p0 genDType p1 Returns the distance between p0 and p1 i e length p0 p1 float dot genType x genType y double dot genDType x genDType y Returns the dot product of x and y i e x 0 y 0 x 1 y 1 vec3 cross vec3 x vec3 y dvec3 cross dvec3 x dvec3 y Returns the cross product of x and y i e x 1 y 2 y 1 x 2 x 2 y 0 y 2 x 0 x 0 y 1 y 0 x 1 genType normalize genType x genDType normalize
257. spose uniform mat4 gl ProjectionMatrixTranspose uniform mat4 gl ModelViewProjectionMatrixTranspose uniform mat4 gl TextureMatrixTranspose gl MaxTextureCoords uniform mat4 gl ModelViewMatrixInverseTranspose uniform mat4 gl ProjectionMatrixInverseTranspose uniform mat4 gl ModelViewProjectionMatrixInverseTranspose uniform mat4 gl TextureMatrixInverseTranspose gl MaxTextureCoords Ef compatibility profile only uniform float gl NormalScale compatibility profile only uniform vec4 gl ClipPlane gl MaxClipPlanes compatibility profile only struct gl PointParameters loat size loat sizeMin loat sizeMax loat fadeThresholdSize loat distanceConstantAttenuation loat distanceLinearAttenuation Hh FH FH FH FH Eh Hh loat distanceQuadraticAttenuation uniform gl PointParameters gl Point compatibility profile only struct gl MaterialParameters vec4 emission Ecm vec4 ambient Acm vec4 diffuse Dem vec4 specular Sem float shininess Srm uniform gl MaterialParameters gl FrontMaterial uniform gl MaterialParameters gl BackMaterial 137 7 Built in Variables compatibility profile only struct gl LightSourceParameters vec4 ambient Acli vec4 diffuse Deli vec4 specular Scli vec4 position Ppli vec4 halfVector Derived Hi vec3 spotDirection Sali float spotExponent
258. st TYPE_NAME type name list COMMA TYPE NAME type _specifier type specifier nonarray type specifier nonarray array_specifier array_specifier LEFT BRACKET RIGHT BRACKET LEFT BRACKET constant expression RIGHT BRACKET array_specifier LEFT BRACKET RIGHT BRACKET array_specifier LEFT BRACKET constant expression RIGHT BRACKET type _specifier_nonarray VOID FLOAT DOUBLE INT UINT BOOL VEC2 VEC3 VEC4 DVEC2 DVEC3 196 9 Shading Language Grammar for Core Profile DVEC4 BVEC2 BVEC3 BVEC4 IVEC2 IVEC3 IVEC4 UVEC2 UVEC3 UVEC4 MAT2 MAT3 MAT4 MAT2X2 MAT2X3 MAT2X4 MAT3X2 MAT3X3 MAT3X4 MAT4X2 MAT4X3 MAT4X4 DMAT2 DMAT3 DMAT4 DMAT2X2 DMAT2X3 DMAT2X4 DMAT3X2 DMAT3X3 DMAT3X4 DMAT4X2 DMAT4X3 DMAT4X4 ATOMIC_UINT SAMPLERID SAMPLER2D 197 9 Shading Language Grammar for Core Profile SAMPLER3D SAMPLERCUBE SAMPLERIDSHADOW SAMPLER2DSHADOW SAMPLERCUBESHADOW SAMPLERIDARRAY SAMPLER2DARRAY SAMPLERIDARRAYSHADOW SAMPLER2DARRAYSHADOW SAMPLERCUBEARRAY SAMPLERCUBEARRAYSHADOW ISAMPLERID ISAMPLER2D ISAMPLER3D ISAMPLERCUBE ISAMPLERIDARRAY ISAMPLER2DARRAY ISAMPLERCUBEARRAY USAMPLERID USAMPLER2D USAMPLER3D USAMPLERCUBE USAMPLERIDARRAY USAMPLER2DARRAY USAMPLERCUBEARRAY SAMPLER2DRECT SAMPLER2DRECTSHADOW ISAMPLER2DRECT USAMPLER2DRECT SAMPLERBUFFER ISAMPLERBUFFER USAMPLERBUFFER SAMPLER2DMS ISAMPLER2DMS USAMPLER2DMS SAMPLER2DMSARRAY ISAMPLER2DMSARRAY 198 9 Shading Language Grammar for Core Profile
259. st is provided for convenience Function names can be overloaded The same function name can be used for multiple functions as long as the parameter types differ If a function name is declared twice with the same parameter types then the return types and all qualifiers must also match and it is the same function being declared For example vec4 f in vec4 x out vec4 y A vec4 f in vec4 x out uvec4 y B okay different argument type vec4 f in ivec4 x out dvec4 y C okay different argument type int f in vec4 x out vec4 y error only return type differs vec4 f in vec4 x in vec4 y error only qualifier differs vec4 f const in vec4 x out vec4 y error only qualifier differs When function calls are resolved an exact type match for all the arguments is sought If an exact match is found all other functions are ignored and the exact match is used If no exact match is found then the implicit conversions in section 4 1 10 Implicit Conversions will be applied to find a match Mismatched types on input parameters in or inout or default must have a conversion from the calling argument type to the formal parameter type Mismatched types on output parameters out or inout must have a conversion from the formal parameter type to the calling argument type If implicit conversions can be used to find more than one matching function a single best matching function is sought To determine a best match the c
260. statements into compound statements compound statement statement list simple statement declaration statement expression statement selection statement iteration statement jump statement Simple declaration expression and jump statements end in a semi colon This above is slightly simplified and the complete grammar specified in section 9 Shading Language Grammar should be used as the definitive specification Declarations and expressions have already been discussed Function Definitions As indicated by the grammar above a valid shader is a sequence of global declarations and function definitions A function is declared as the following example shows prototype returnType functionName typeO arg0 typel argl typen argn and a function is defined like definition returnType functionName typeO arg0 typel argl typen argn do some computation return returnValue where returnType must be present and include a type If the type of returnValue does not match returnType there must be an implicit conversion in section 4 1 10 Implicit Conversions that converts the type of returnValue to returnType or a compile time error will result Each of the typeN must include a type and can optionally include parameter qualifiers The formal argument names args above in the declarations are optional for both the declaration and definition forms A function is called by using its name fol
261. stem Specification The g TexCoord values are the interpolated gl TexCoord values from a vertex shader or the texture coordinates of any fixed pipeline based vertex functionality Indices to the fragment shader g _TexCoord array are as described above in the vertex shader text As described above for the input and output g PerVertex blocks the gl PerFragment block can be redeclared to create an explicit interface to another program When matching these interfaces between separate programs members in the g PerVertex output block must be declared if and only if the corresponding fragment shader members generated from them are present in the g PerFragment input block These matches are described in detail in section 7 4 1 Shader Interface Matching of the OpenGL 132 7 2 7 Built in Variables Graphics System Specification If they don t match within a program a link time error will result If the mismatch is between two programs values passed between programs are undefined Unlike with all other block matching the order of declaration within g PerFragment does not have to match across shaders and does not have to correspond with order of declaration in a matching g PerVertex redeclaration The following fragment output variables are available in a fragment shader when using the compatibility profile out vec4 gl FragColor out vec4 gl FragData gl MaxDrawBuffers Writing to g FragColor specifies the fragment color that will
262. t expression is a normal expression except that a comma outside parentheses is interpreted as the end of the initializer not as the sequence operator As explained in more detail below this allows creation of nested initializers The aggregate and its initializer must exactly match in terms of nesting number of components elements members present at each level and types of components elements members An assignment expression in an initializer must be either the same type as the object it initializes or be a type that can be converted to the object s type according to section 4 1 10 Implicit Conversions Since these include constructors an aggregate can be initialized by either a constructor or an initializer list an element in an initializer list can be a constructor If an initializer is a list of initializers enclosed in curly braces the variable being declared must be a vector a matrix an array or a structure int i 1 illegal i is not an aggregate 40 4 Variables and Types A list of initializers enclosed in a matching set of curly braces is applied to one aggregate This may be the variable being declared or an aggregate contained in the variable being declared Individual initializers from the initializer list are applied to the elements members of the aggregate in order If the aggregate has a vector type initializers from the list are applied to the components of the vector in order starting with component 0
263. t k k 3 redeclaration error of the name k int f int k int k k 3 2nd k is parameter initializing nested first k int m k use of new k which is hiding the parameter 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 for nested scope begins here int i 0 i lt 10 i int i redeclaration error 43 4 Variables and Types 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 int i 17 do int i 4 okay in nested scope while i 0 i is 17 scoped outside the do while body The statement following a switch forms a nested scope 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 An implicitly sized array can be redeclared in the same scope as an array of the same base type Otherwise within one compilation unit a declared name cannot be redeclared in the same scope doing so results in a redeclaration compile time 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
264. t shader using g PrimitivelD is active and a geometry shader is also active the geometry shader must write to g PrimitivelD or the fragment shader input gl PrimitivelD is undefined See section 11 3 4 5 Geometry Shader Outputs of the OpenGL Graphics System Specification for more information For tessellation control and evaluation languages the input variable gl PrimitivelD is filled with the number of primitives processed by the shader since the current set of rendering primitives was started For the fragment language it is filled with the value written to the g PrimitivelD geometry shader output if a geometry shader is present Otherwise it is assigned in the same manner as with tessellation control and evaluation shaders The geometry language input variable g PrimitivelDIn behaves identically to the tessellation control and evaluation language input variable g PrimitivelD The input variable g InvocationID is available only in the tessellation control and geometry languages In the tessellation control shader it identifies the number of the output patch vertex assigned to the tessellation control shader invocation In the geometry shader it identifies the invocation number assigned to the geometry shader invocation In both cases g _InvocationID is assigned integer values in the range 0 N 1 where N is the number of output patch vertices or geometry shader invocations per primitive The variable g Layer is available as an outpu
265. t sign bit creates a negative value For example 30 4 1 4 4 Variables and Types int a Oxffffffff 32 bits a gets the value 1 int b OxffffffffU ERROR can t convert uint to int uint c Oxffffffff 32 bits c gets the value OxFFFFFFFF uint d OxffffffffU 32 bits d gets the value OxFFFFFFFF int e 1 the literal is 1 then negation is performed and the resulting non literal 32 bit signed bit pattern of OxFFFFFFFF is assigned giving e the value of 1 uint f lu the literal is lu then negation is performed and the resulting non literal 32 bit unsigned bit pattern of OxFFFFFFFF is assigned giving f the value of OxFFFFFFFF int g 3000000000 a signed decimal literal taking 32 bits setting the sign bit g gets 1294967296 int h 0xA0000000 okay 32 bit signed hexadecimal int i 5000000000 ERROR needs more than 32 bits int j OxFFFFFFFFF ERROR needs more than 32 bits int k 0x80000000 k gets 2147483648 0x80000000 int 1 2147483648 1 gets 2147483648 the literal set the sign bit Despite all these examples initializing variables literals are recognized and given values and types independently of their context Floating Point Variables Single precision and double precision floating point variables are available for use in a variety of scalar calculations Generally the term floating point will refer to b
266. t supported 200 9 Shading Language Grammar for Core Profile simple_statement declaration statement expression statement selection statement switch _ statement case_label iteration_statement jump_statement compound_statement LEFT BRACE RIGHT BRACE LEFT BRACE statement_list RIGHT BRACE Statement_no_new_scope compound_statement_no_new_scope simple_statement compound_statement_no_new_scope LEFT BRACE RIGHT BRACE LEFT BRACE statement list RIGHT BRACE statement list statement statement list statement expression statement SEMICOLON expression SEMICOLON selection statement IF LEFT PAREN expression RIGHT PAREN selection rest statement selection rest statement statement ELSE statement statement condition expression fully specified type IDENTIFIER EQUAL initializer 201 9 Shading Language Grammar for Core Profile switch statement SWITCH LEFT PAREN expression RIGHT PAREN LEFT BRACE switch statement list RIGHT BRACE switch statement list nothing statement list case_label CASE expression COLON DEFAULT COLON iteration_statement WHILE LEFT PAREN condition RIGHT PAREN statement_no_new_scope DO statement WHILE LEFT PAREN expression RIGHT PAREN SEMICOLON FOR LEFT PAREN for_init_statement for rest statement RIGHT PAREN statement_no_new_scope for_init_statement expression_statement declaration_statement conditionopt condition empty for_rest_statement condition
267. t that is sold as long as such product includes significant independent work developed by the seller A link to the current version of this specification on the Khronos Group web site should be included whenever possible with specification distributions Khronos Group makes no and expressly disclaims any representations or warranties express or implied regarding this specification including without limitation any implied warranties of merchantability or fitness for a particular purpose or non infringement of any intellectual property Knronos Group makes no and expressly disclaims any warranties express or implied regarding the correctness accuracy completeness timeliness and reliability of the specification Under no circumstances will the Khronos Group or any of its Promoters Contributors or Members or their respective partners officers directors employees agents or representatives be liable for any damages whether direct indirect special or consequential damages for lost revenues lost profits or otherwise arising from or in connection with these materials Khronos OpenKODE OpenKOGS OpenVG OpenMAX OpenSL ES and OpenWF are trademarks of the Khronos Group Inc COLLADA is a trademark of Sony Computer Entertainment Inc used by permission by Khronos OpenGL and OpenML are registered trademarks and the OpenGL ES logo is a trademark of Silicon Graphics Inc used by permission by Khronos All other product names trademarks and
268. t type of the array or be a type that can be converted to the element type of the array according to section 4 1 10 Implicit Conversions Arrays of arrays are similarly constructed and the size for any dimension is optional vec4 b 2 vec4 3 2 b b b constructor vec4 2 b b b constructor valid size deduced vec4 3 b b b constructor valid size deduced vec4 b b b constructor valid both sizes deduced Vector and Scalar Components and Length The names of the components of a vector or scalar are denoted by a single letter As a notational convenience several letters are associated with each component based on common usage of position color or texture coordinate vectors The individual components can be selected by following the variable name with period and then the component name The component names supported are x y Z W Useful when accessing vectors that represent points or normals fr 2 b a Useful when accessing vectors that represent colors fs t p q Useful when accessing vectors that represent texture coordinates 103 5 Operators and Expressions The component names x r and s are for example synonyms for the same first component in a vector They are also the names of the only component in a scalar Note that the third component of the texture coordinate set r in OpenGL has been renamed p so as to avoid the confusion with r
269. t variable in the geometry language and an input variable in the fragment language In the geometry language it is used to select a specific layer or face and layer of a cube map of a multi layer framebuffer attachment The actual layer used will come from one of the vertices in the primitive being shaded Which vertex the layer comes from is discussed in section 11 3 4 6 Layer and Viewport Selection of the OpenGL Specification It might be undefined so it is best to write the same layer value for all vertices of a primitive If a shader statically assigns a value to gl Layer layered rendering mode is enabled See section 11 3 4 5 Geometry Shader Outputs and section 9 4 9 Layered Framebuffers of the OpenGL Graphics System Specification for more information If a shader statically assigns a value to g Layer and there is an execution path through the shader that does not set gl Layer then the value of g Layer is undefined for executions of the shader that take that path 126 7 Built in Variables The output variable g Layer takes on a special value when used with an array of cube map textures Instead of only referring to the layer it is used to select a cube map face and a layer Setting g Layer to the value layer 6 face will render to face face of the cube defined in layer layer The face values are defined in Table 9 3 of section 9 4 9 Layered Framebuffers of the OpenGL Graphics System Specification but repeated belo
270. tents of the selected texel If the values are equal the new value is given by data otherwise it is taken from the original value loaded from the texel 179 8 13 8 13 1 8 Built in Functions Fragment Processing Functions Fragment processing functions are only available in fragment shaders Derivative Functions Derivatives may be computationally expensive and or numerically unstable Therefore an OpenGL implementation may approximate the true derivatives by using a fast but not entirely accurate derivative computation Derivatives are undefined within non uniform control flow The expected behavior of a derivative is specified using forward backward differencing Forward differencing F x dx F x dFdx x dx la drs x FOIE Fs Ib Backward differencing F x dx F x dFdx x dx 2a F x F x dx dFdx x FE 2b With single sample rasterization dx lt 1 0 in equations 1b and 2b For multi sample rasterization dx lt 2 0 in equations 1b and 2b dFdy is approximated similarly with y replacing x A GL implementation may use the above or other methods to perform the calculation subject to the following conditions 1 The method may use piecewise linear approximations Such linear approximations imply that higher order derivatives dFdx dFdx x and above are undefined 2 The method may assume that the function evaluated is continuous Therefore derivatives within non uni
271. tes of a vertex generated by the tessellation primitive generator using a patch of incoming vertices and their associated data Compilation units written in the OpenGL Shading Language to run on this processor are called tessellation evaluation shaders When a set of tessellation evaluation shaders are successfully compiled and linked they result in a tessellation evaluation shader executable that runs on the tessellation evaluation processor Each invocation of the tessellation evaluation executable computes the position and attributes of a single vertex generated by the tessellation primitive generator The executable can read the attributes of any vertex in the input patch plus the tessellation coordinate which is the relative location of the vertex in the primitive being tessellated The executable writes the position and other attributes of the vertex Geometry Processor The geometry processor is a programmable unit that operates on data for incoming vertices for a primitive assembled after vertex processing and outputs a sequence of vertices forming output primitives Compilation units written in the OpenGL Shading Language to run on this processor are called geometry shaders When a set of geometry shaders are successfully compiled and linked they result in a geometry shader executable that runs on the geometry processor A single invocation of the geometry shader executable on the geometry processor will operate on a declared input primiti
272. the original input for zero and all finite non denormized values 8 4 Floating Point Pack and Unpack Functions These functions do not operate component wise rather as described in each case Syntax Description uint packUnorm2x16 vec2 v uint packSnorm2x16 vec v uint packUnorm4x8 vec4 v uint packSnorm4x8 vec4 v First converts each component of the normalized floating point value v into 8 or 16 bit integer values Then the results are packed into the returned 32 bit unsigned integer The conversion for component c of v to fixed point is done as follows packUnorm2x16 round clamp c 0 1 65535 0 packSnorm2x16 round clamp c 1 1 32767 0 packUnorm4x8 round clamp c 0 1 255 0 packSnorm4x8 round clamp c 1 1 127 0 The first component of the vector will be written to the least significant bits of the output the last component will be written to the most significant bits 149 8 Built in Functions Syntax Description vec2 unpackUnorm2x16 uint p vec2 unpackSnorm2x16 uint p vec4 unpackUnorm4x8 uint p vec4 unpackSnorm4x8 uint p First unpacks a single 32 bit unsigned integer p into a pair of 16 bit unsigned integers a pair of 16 bit signed integers four 8 bit unsigned integers or four 8 bit signed integers Then each component is converted to a normalized floating point value to generate the returned two or four component vector The co
273. 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 effects 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 layout std140 uniform block vec4 a a takes offsets 0 15 layout offset 32 vec3 b b takes offsets 32 43 layout offset 40 vec2 GC ERROR lies within previous member layout offset 48 vec2 d d takes offsets 48 55 layout align 16 float e takes offsets 64 67 layout align 2 double f f takes offsets 72 79 layout align 6 double g ERROR 6 is not a power of 2 layout offset 80 float h h takes offsets 80 83 layout align 64 dvec3 i i takes offsets 128 151 layout offset 164 align 8 float j j takes offsets 168 171 Opaque Uniform Layout Qualifiers Uniform layout qualifiers can be used to bind opaque uniform variables to specific buffers or units
274. tions 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 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 62 4 Variables and Types layout location 3 in struct S vec3 a gets location 3 mat2 b gets locations 4 and 5 vec4 c 2 gets locations 6 and 7 layout location 8 vec2 A ERROR can t use on struct member s layout location 4 in block vec4 d gets locati
275. to that variable for all samples in the pixel but that value must be interpolated to a location that lies in both the pixel and in the primitive being rendered including 85 4 5 1 4 Variables and Types any of the pixel s samples covered by the primitive Because the location at which the variable is interpolated may be different in neighboring pixels and derivatives may be computed by computing differences between neighboring pixels derivatives of centroid sampled inputs may be less accurate than those for non centroid interpolated variables If a fragment shader input is qualified with sample a separate value must be assigned to that variable for each covered sample in the pixel and that value must be sampled at the location of the individual sample It is a link time error if within the same stage the interpolation qualifiers of variables of the same name do not match Redeclaring Built in Interpolation Variables in the Compatibility Profile The following predeclared variables can be redeclared with an interpolation qualifier when using the compatibility profile Vertex tessellation control tessellation evaluation and geometry languages gl FrontColor gl BackColor gl FrontSecondaryColor gl BackSecondaryColor Fragment language gl Color gl SecondaryColor For example in vec4 gl Color predeclared by the fragment language flat in vec4 gl Color redeclared by user to be flat flat in vec4 gl FrontColor input
276. tputs from the geometry shader are triangles and at most 60 vertices will be emitted by the shader It is an error for the maximum number of vertices to be greater than gl MaxGeometryOutputVertices The identifier stream is used to specify that a geometry shader output variable or block is associated with a particular vertex stream numbered beginning with zero A default stream number may be declared at global scope by qualifying interface qualifier out as in this example layout stream 1 out The stream number specified in such a declaration replaces any previous default and applies to all subsequent block and variable declarations until a new default is established The initial default stream number is zero Each output block or non block output variable is associated with a vertex stream If the block or variable is declared with the stream identifier it is associated with the specified stream otherwise it is associated with the current default stream A block member may be declared with a stream identifier but the specified stream must match the stream associated with the containing block One example layout stream 1 out default is now stream 1 out vec4 varl varl gets default stream 1 layout stream 2 out Blockl Blockl belongs to stream 2 layout stream 2 vec4 var2 redundant block member stream decl layout stream 3 vec2 var3 ILLEGAL must match block stream vec3 var4 belongs t
277. trol shaders are successfully compiled and linked they result in a tessellation control shader executable that runs on the tessellation control processor The tessellation control shader is invoked for each vertex of the output patch Each invocation can read the attributes of any vertex in the input or output patches but can only write per vertex attributes for the corresponding output patch vertex The shader invocations collectively produce a set of per patch attributes for the output patch After all tessellation control shader invocations have completed the output vertices and per patch attributes are assembled to form a patch to be used by subsequent pipeline stages Tessellation control shader invocations run mostly independently with undefined relative execution order However the built in function barrier can be used to control execution order by synchronizing invocations effectively dividing tessellation control shader execution into a set of phases Tessellation control shaders will get undefined results if one invocation reads a per vertex or per patch attribute 10 2 3 2 4 2 5 2 6 2 Overview of OpenGL Shading written by another invocation at any point during the same phase or if two invocations attempt to write different values to the same per patch output in a single phase Tessellation Evaluation Processor The tessellation evaluation processor is a programmable unit that evaluates the position and other attribu
278. ualified member to start at or after the specified integral constant expression which will be its byte offset from the beginning of the buffer It is a compile time error to 80 4 4 6 4 Variables and Types specify an offset that is smaller than the offset of the previous member in the block or that lies within the previous 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 integral constant expression 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 can only be used on blocks or block members and only for blocks declared with std140 or std430 layouts 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 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 next available offset If the resulting offset is not a multiple of
279. ubroutine keyword as follows subroutine returnType subroutineTypeName type0O arg0 typel argl typen argn As with function declarations the formal argument names args above are optional Functions are associated with subroutine types of matching declarations by defining the function with the subroutine keyword and a list of subroutine types the function matches subroutine subroutineTypeName0 subroutineTypeNameN returnType functionName type0O arg0 typel argl typen argn function body It is a compile time error if arguments and return type don t match between the function and each associated subroutine type Functions declared with subroutine must include a body An overloaded function cannot be declared with subroutine a program will fail to compile or link if any shader or stage contains two or more functions with the same name if the name is associated with a subroutine type A function declared with subroutine can also be called directly with a static use of functionName as is done with non subroutine function declarations and calls Subroutine type variables are required to be subroutine uniforms and are declared with a specific subroutine type in a subroutine uniform variable declaration subroutine uniform subroutineTypeName subroutineVarName Subroutine uniform variables are called the same way functions are called When a subroutine variable or an element of a subroutine variable array
280. ue will hold the size of the array Cube images only return the dimensions of one face and the number of cubes in the cube map array if arrayed Note The qualification readonly writeonly accepts a variable qualified with readonly writeonly both or neither It means the formal argument will be used for neither reading nor writing to the underlying memory gvec4 imageLoad readonly IMAGE_PARAMS Loads the texel at the coordinate P from the image unit image in IMAGE_PARAMS For multi sample loads the sample number is given by sample When image P sample identify a valid texel the bits used to represent the selected texel in memory are converted to a vec4 ivec4 or uvec4 in the manner described in section 8 25 Texture Image Loads and Stores of the OpenGL Specification and returned void imageStore writeonly IMAGE PARAMS gvec4 data Stores data into the texel at the coordinate P from the image specified by image For multi sample stores the sample number is given by sample When image P and sample identify a valid texel the bits used to represent data are converted to the format of the image unit in the manner described in section 8 25 Texture Image Loads and Stores of the OpenGL Specification and stored to the specified texel uint imageAtomicAdd IMAGE PARAMS uint data int imageAtomicAdd MAGE_PARAMS int data Computes a new value by adding the value of data to the contents of the s
281. uilt in functions cannot be used to form constant expressions An integral constant expression is a constant expression that evaluates to a scalar signed or unsigned integer Constant expressions will be always be evaluated in an invariant way independent of use of invariant and precise qualification so as to create the same value in multiple shaders when the same constant expressions appear in those shaders See section 4 8 1 The Invariant Qualifier and section 4 9 The Precise Qualifier for more details on how to create invariant expressions Constant expressions may be evaluated by the compiler s 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 Input Variables Shader input variables are declared with the storage qualifier in They form the input interface between previous stages of the OpenGL pipeline and the declaring shader Input variables must be declared at global scope Values from the previous pipeline stage are copied into input variables at the beginning of shader execution It is a compile time error to write to a variable declared as an input Only the input variables that are statically read need to be written by the previous stage it is allowed to have superfluous declarations of input variables This is shown in the following table 47
282. ve as if it is compiling at line number ine and source string number source string number Subsequent source strings will be numbered sequentially until another line directive overrides that numbering Comments Comments are delimited by and or by and a new line The begin comment delimiters or are not recognized as comment delimiters inside of a comment hence comments cannot be nested A comment includes its terminating delimiter However a comment does not include or eliminate its terminating new line Inside comments any byte values may be used except a byte whose value is 0 No errors will be given for the content of comments and no validation on the content of comments need be done Removal of new lines by the line continuation character logically occurs before comments are processed That is a single line comment ending in the line continuation character includes the next line in the comment a single line comment containing the next line a b this is still in the first comment 20 3 5 Tokens 3 Basics The language after preprocessing is a sequence of GLSL tokens A token can be token keyword identifier integer constant floating constant operator 3 3 3 6 Keywords The following are the language s keywords and after preprocessing can only be used as described in this specification or a compile time error results attribute const uniform varying buff
283. ve with a fixed number of vertices This single invocation can emit a variable number of vertices that are assembled into primitives of a declared output primitive type and passed to subsequent pipeline stages Fragment Processor The fragment processor is a programmable unit that operates on fragment values and their associated data Compilation units written in the OpenGL Shading Language to run on this processor are called fragment shaders When a set of fragment shaders are successfully compiled and linked they result in a fragment shader executable that runs on the fragment processor A fragment shader cannot change a fragment s x y position Access to neighboring fragments is not allowed The values computed by the fragment shader are ultimately used to update framebuffer memory or texture memory depending on the current OpenGL state and the OpenGL command that caused the fragments to be generated Compute Processor The compute processor is a programmable unit that operates independently from the other shader processors Compilation units written in the OpenGL Shading Language to run on this processor are called compute shaders When a set of compute shaders are successfully compiled and linked they result in a compute shader executable that runs on the compute processor 11 2 Overview of OpenGL Shading A compute shader has access to many of the same resources as fragment and other shader processors including textures buffers
284. vec2 offset float textureLodOffset sampler DArrayShadow sampler vec3 P float lod int offset Do an offset texture lookup with explicit LOD See textureLod and textureOffset gvec4 textureProjLod gsampler D sampler vec2 P float lod gvec4 textureProjLod gsampler1D sampler vec4 P float lod gvec4 textureProjLod gsampler2D sampler vec3 P float lod gvec4 textureProjLod gsampler2D sampler vec4 P float lod gvec4 textureProjLod gsampler3D sampler vec4 P float lod float textureProjLod sampler DShadow sampler vec4 P float lod float textureProjLod sampler2DShadow sampler vec4 P float lod Do a projective texture lookup with explicit LOD See textureProj and textureLod gvec4 textureProjLodOffset gsampler1D sampler vec2 P float lod int offset gvec4 textureProjLodOffset gsampler1D sampler vec4 P float lod int offset gvec4 textureProjLodOffset gsampler2D sampler vec3 P float lod ivec2 offset gvec4 textureProjLodOffset gsampler2D sampler vec4 P float lod ivec2 offset gvec4 textureProjLodOffset gsampler3D sampler vec4 P float lod ivec3 offset float textureProjLodOffset sampler DShadow sampler vec4 P float lod int offset float textureProjLodOffset sampler2DShadow sampler vec4 P float lod ivec2 offset Do an offset projective texture lookup with explicit LOD See textureProj textureLod and textureOffset 167 8 Built in Functions Syntax Description
285. version of its value to an equivalent value in the new type For example the integer value 5 will be converted to the floating point value 5 0 Integer values having more bits of precision than a single precision floating point mantissa will lose precision when converted to float When performing implicit conversion for binary operators there may be multiple data types to which the two operands can be converted For example when adding an int value to a uint value both values can be implicitly converted to uint float and double In such cases a floating point type is chosen if either operand has a floating point type Otherwise an unsigned integer type is chosen if either operand has an unsigned integer type Otherwise a signed integer type is chosen If operands can be implicitly converted to multiple data types deriving from the same base data type the type with the smallest component size is used The conversions in the table above are done only as indicated by other sections of this specification Initializers At declaration an initial value for an aggregate variable may be provided specified as an equals followed by an initializer The initializer is either an assignment expression or a list of initializers enclosed in curly braces The grammar for the initializer is initializer assignment expression initializer list initializer list initializer list initializer initializer list initializer The assignmen
286. w vector matrix with one row and does a linear algebraic matrix multiply c r yielding a matrix whose number of rows is the number of components in c and whose number of columns is the number of components in r mat2 transpose mat2 m mat3 transpose mat3 m mat4 transpose mat4 m mat2x3 transpose mat3x2 m mat3x2 transpose mat2x3 m mat2x4 transpose mat4x2 m mat4x2 transpose mat2x4 m mat3x4 transpose mat4x3 m mat4x3 transpose mat3x4 m Returns a matrix that is the transpose of m The input matrix m is not modified float determinant mat2 m float determinant mat3 m float determinant mat4 m Returns the determinant of m 154 8 Built in Functions Syntax Description mat2 inverse mat2 m mat3 inverse mat3 m mat4 inverse mat4 m Returns a matrix that is the inverse of m The input matrix m is not modified The values in the returned matrix are undefined if m is singular or poorly conditioned nearly singular 155 8 7 8 Built in Functions Vector Relational Functions Relational and equality operators lt lt gt gt are defined to operate on scalars and produce scalar Boolean results For vector results use the following built in functions Below the following placeholders are used for the listed specific types Placeholder Specific Types Allowed bvec bvec2 bvec3 bvec4 ivec ivec2 ivec3 ivec4 uvec uvec2
287. w for clarity Face Value Resulting Target 0 TEXTURE CUBE MAP POSITIVE X 1 TEXTURE CUBE MAP NEGATIVE X 2 TEXTURE CUBE MAP POSITIVE Y 3 TEXTURE CUBE MAP NEGATIVE Y 4 TEXTURE CUBE MAP POSITIVE Z 5 TEXTURE CUBE MAP NEGATIVE Z For example to render to the positive y cube map face located in the Sth layer of the cube map array gl Layer should be set to 5 6 2 The input variable g Layer in the fragment language will have the same value that was written to the output variable g Layer in the geometry language If the geometry stage does not dynamically assign a value to g Layer the value of gl Layer in the fragment stage will be undefined If the geometry stage makes no static assignment to g Layer the input value in the fragment stage will be zero Otherwise the fragment stage will read the same value written by the geometry stage even if that value is out of range If a fragment shader contains a static access to g Layer it will count against the implementation defined limit for the maximum number of inputs to the fragment stage The variable gl ViewportIndex is available as an output variable in the geometry language and an input variable in the fragment language In the geometry language it provides the index of the viewport to which the next primitive emitted from the geometry sha
288. wing rules apply to both single and double precision operations Infinities and zeros are generated as dictated by IEEE but subject to the precisions allowed in the following table and subject to allowing positive and negative zeros to be interchanged However dividing a non zero by 0 results in the appropriately signed IEEE Inf If both positive and negative zeros are implemented the correctly signed Inf will be generated otherwise positive Inf is generated Any 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 NaNs are not required to be generated Support for signaling NaNs is not required and exceptions are never raised Operations and built in functions that operate on a NaN are not required to return a NaN as the result Precisions are expressed in terms of maximum relative error in units of ULP units in the last place unless otherwise noted 87 4 7 2 4 Variables and Types For single precision operations precisions are required as follows Operation Precision a b a b a b Correctly rounded lt lt gt gt Correct result a b 1 0 b 2 5 ULP for b in the range 2 2 4 a b c Correctly rounded single operation or sequence of two correctly rounded operations fma Inherited from a b c pow x y Inherited from exp2 x log2 y exp x exp2
289. x 3 2 x ULP log log2 3 ULP outside the range 0 5 2 0 Absolute error lt 2 inside the range 0 5 2 0 sqrt Inherited from 1 0 inversesqrt inversesqrt 2 ULP implicit and explicit conversions between types Correctly rounded Built in functions defined in the specification with an equation built from the above operations inherit the above errors These include for example the geometric functions the common functions and many of the matrix functions Built in functions not listed above and not defined as equations of the above have undefined precision These include for example the trigonometric functions and determinant The precision of double precision operations is at least that of single precision Precision Qualifiers Any single precision floating point declaration integer declaration or sampler declaration can have the type preceded by one of these precision qualifiers Qualifier Meaning highp None mediump None lowp None 88 4 7 3 4 Variables and Types For example lowp float color out mediump vec2 P lowp ivec2 foo lowp mat3 highp mat4 m Literal constants do not have precision qualifiers Neither do Boolean variables Neither do floating point constructors nor integer constructors when none of the constructor arguments have precision qualifiers Precision qualifiers as with other qualifiers do not ef
290. x std430 row_major column_major x uniform buffer binding opaque types x only offset X align X X location uniform buffer and X 3 subroutine variables location X X X all in out except for component X X compute fragment out index x and subroutine functions triangles quads X tessellation evaluation in isolines equal_spacing fractional_even_spacing X tessellation evaluation in fractional_odd_spacing ew X tessellation evaluation in ccw point_mode X tessellation evaluation in points X geometry in out points lines lines_adjacency X geometry in triangles triangles_adjacency invocations X geometry in origin upper left gl FragCoord pixel_center_integer only fragment in early_fragment_tests X 60 4 4 1 4 Variables and Types Layout Qualifier Qualifier Individual Block Only Variable Block Member Allowed Interfaces local size x local size y x compute in local size _z xfb_buffer xfb stride x x x x vertex tessellation and geometry out xfb_ offset x x X vertices X tessellation control out points line strip x triangle strip geometry out max _vertices X stream X x x X depth_any depth_greater gl FragDepth a fr t out depth_less only Bem ere depth_unchanged Input Layout Qualifiers Some input layout qualifiers apply to all shader languages and some apply only to specific languages The latte
291. xplicitly called out below Similarly these identifiers are not case sensitive unless explicitly noted otherwise More than one layout qualifier may appear in a single declaration Additionally the same ayout qualifier name can occur multiple times within a layout qualifier or across multiple layout qualifiers in the same declaration When the same ayout qualifier name occurs multiple times in a single declaration the last occurrence overrides the former occurrence s Further if such a layout qualifier name will affect subsequent declarations or other observable behavior it is only the last occurrence that will have any effect behaving as if the earlier occurrence s within the declaration are not present This is also true for overriding layout qualifier names where one overrides the other e g row_major vs column_major only the last occurrence has any effect The following table summarizes the use of layout qualifiers applied to non opaque types It shows for each one what kinds of declarations it may be applied to These are all discussed in detail in the following sections Layout qualifiers applied to opaque types are not show in this table but are discussed subsequently in section 4 4 6 Opaque Uniform Layout Qualifiers 59 4 Variables and Types Layout Qualifier Qualifier Individual Block Only Variable Block Member Allowed Interfaces shared packed std140
292. xternally visible name of buffer int count typed shared memory age Pie Spied vec4 v last element may be an array that is not sized until after link time dynamically sized Name name of block within the shader 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 including within a language as well as across languages Hence the types of all declared buffer variables with the same name must match across all shaders that are linked into a single program Shared Variables The shared qualifier is used to declare variables that have storage shared between all work items compute shader local work group Variables declared as shared may only be used in compute shaders see section 2 6 Compute Processor Shared variables are implicitly coherent That is writes to shared variables from one shader invocation will eventually be seen by other invocations within the same local work group Variables declared as shared may not have initializers and their contents are undefined at the beginning of shader execution Any data written to shared vari
293. ype or the expression must have a type in the table in section 4 1 10 Implicit Conversions that converts to the type of value expression in which case an implicit conversion will be done on the rvalue expression before the assignment is done Any other desired type conversions must be specified explicitly via a constructor L values must be writable Variables that are built in types entire structures or arrays structure members l values with the field selector applied to select components or swizzles without repeated fields 1 values within parentheses and I values dereferenced with the array subscript operator are all l values Other binary or unary expressions function names swizzles with repeated fields and constants cannot be I values The ternary operator is also not allowed as an I value Using an incorrect expression as an l value results in a compile time error Expressions on the left of an assignment are evaluated before expressions on the right of the assignment 106 5 9 5 Operators and Expressions The other assignment operators are add into subtract from multiply into divide into modulus into left shift by lt lt right shift by gt gt and into amp inclusive or into exclusive or into 4 where the general expression lvalue op expression is equivalent to lvalue lvalue op expression where op is as described below and the l valu
294. ype of context in the OpenGL API See the OpenGL Graphics System Specification Version 4 4 for details on what language versions are supported Previous versions of the OpenGL Shading Language as well as the OpenGL ES Shading Language are not strict subsets of the version specified here particularly with respect to precision name hiding rules and treatment of interface variables See the specification corresponding to a particular language version for details specific to that version of the language All OpenGL Graphics System Specification references in this specification are to version 4 4 1 1 Acknowledgments 1 Introduction This specification is based on the work of those who contributed to past versions of the OpenGL Language Specification the OpenGL ES 2 0 Language Specification and the following contributors to this version Pat Brown NVIDIA Jeff Bolz NVIDIA Frank Chen Pierre Boudier AMD Piers Daniell NVIDIA Chris Dodd NVIDIA Nick Haemel NVIDIA Jason Green TransGaming Brent Insko Intel Jon Leech Bill Licea Kane AMD Daniel Koch TransGaming Graeme Leese Broadcom Barthold Lichtenbelt NVIDIA Bruce Merry ARM Robert Ohannessian Tom Olson ARM Acorn Pooley NVIDIA Christophe Riccio AMD Kevin Rogovin Jan Romanick Intel Greg Roth Nvidia Graham Sellers AMD Dave Shreiner ARM Jeremy Sandmel Apple Robert Simpson Qualcomm Eric Werness NVIDIA Mark Young AMD 1 Introduction 1 2 Chan

GLSL Specification

Contents

Download Pdf Manuals

Related Search

Related Contents