GLSL Specification 4.20.11

The OpenGL
Shading Language
Language Version: 4.20
Document Revision: 11
12-Dec-2011
Editor: John Kessenich
Version 1.1 Authors: John Kessenich, Dave Baldwin, Randi Rost
Copyright (c) 2008-2011 The Khronos Group Inc. All Rights Reserve.
This speci!ic"tion is protecte #y copyright l"$s "n cont"ins %"teri"l propriet"ry to the Khronos Group&
Inc. It or "ny co%ponents %"y not #e reprouce& repu#lishe& istri#ute& tr"ns%itte& ispl"ye&
#ro"c"st or other$ise e'ploite in "ny %"nner $ithout the e'press prior $ritten per%ission o! Khronos
Group. (ou %"y use this speci!ic"tion !or i%ple%enting the !unction"lity therein& $ithout "ltering or
re%oving "ny tr"e%"r)& copyright or other notice !ro% the speci!ic"tion& #ut the receipt or possession o!
this speci!ic"tion oes not convey "ny rights to reprouce& isclose& or istri#ute its contents& or to
%"nu!"cture& use& or sell "nything th"t it %"y escri#e& in $hole or in p"rt.
Khronos Group gr"nts e'press per%ission to "ny current *ro%oter& Contri#utor or Aopter %e%#er o!
Khronos to copy "n reistri#ute +,-./I0I1/ versions o! this speci!ic"tion in "ny !"shion& provie th"t
,. C2ARG1 is %"e !or the speci!ic"tion "n the l"test "v"il"#le up"te o! the speci!ic"tion !or "ny
version o! the A*I is use $henever possi#le. 3uch istri#ute speci!ic"tion %"y #e re-!or%"tte A3
4.,G A3 the contents o! the speci!ic"tion "re not ch"nge in "ny $"y. The speci!ic"tion %"y #e
incorpor"te into " prouct th"t is sol "s long "s such prouct inclues signi!ic"nt inepenent $or)
evelope #y the seller. A lin) to the current version o! this speci!ic"tion on the Khronos Group $e#-site
shoul #e inclue $henever possi#le $ith speci!ic"tion istri#utions.
Khronos Group %")es no& "n e'pressly iscl"i%s "ny& represent"tions or $"rr"nties& e'press or
i%plie& reg"ring this speci!ic"tion& incluing& $ithout li%it"tion& "ny i%plie $"rr"nties o! %erch"nt"#ility
or !itness !or " p"rticul"r purpose or non-in!ringe%ent o! "ny intellectu"l property. Khronos Group %")es
no& "n e'pressly iscl"i%s "ny& $"rr"nties& e'press or i%plie& reg"ring the correctness& "ccur"cy&
co%pleteness& ti%eliness& "n reli"#ility o! the speci!ic"tion. +ner no circu%st"nces $ill the Khronos
Group& or "ny o! its *ro%oters& Contri#utors or -e%#ers or their respective p"rtners& o!!icers& irectors&
e%ployees& "gents or represent"tives #e li"#le !or "ny "%"ges& $hether irect& inirect& speci"l or
conse5uenti"l "%"ges !or lost revenues& lost pro!its& or other$ise& "rising !ro% or in connection $ith
these %"teri"ls.
Khronos& .penK./1& .penK.G3& .pen6G& .pen-A7& .pen34 13 "n .pen80 "re tr"e%"r)s o!
the Khronos Group Inc. C.44A/A is " tr"e%"r) o! 3ony Co%puter 1ntert"in%ent Inc. use #y
per%ission #y Khronos. .penG4 "n .pen-4 "re registere tr"e%"r)s "n the .penG4 13 logo is "
tr"e%"r) o! 3ilicon Gr"phics Inc. use #y per%ission #y Khronos. All other prouct n"%es& tr"e%"r)s&
"n9or co%p"ny n"%es "re use solely !or ienti!ic"tion "n #elong to their respective o$ners.
2
Table of Contents
1 Introduction.................................................................................................................................1
1.1 Acknowledgents................................................................................................................!
1.! "hanges................................................................................................................................!
1.!.1 "hanges #ro revision 1$ o# Version %.1$...................................................................!
1.!.! "hanges #ro revision & o# Version %.!$.....................................................................!
1.!.' "hanges #ro revision ( o# Version %.!$.....................................................................'
1.!.% "hanges #ro revision ) o# Version %.!$.....................................................................'
1.!.* "hanges #ro revision + o# Version %.!$.....................................................................'
1.!.+ ,uar- o# "hanges #ro Version %.1$.....................................................................%
1.' .verview..............................................................................................................................+
1.% Error /andling......................................................................................................................+
1.* 0-1ogra1hical "onventions.................................................................................................+
1.+ De1recation..........................................................................................................................+
! .verview o# .1en23 ,hading....................................................................................................(
!.1 Verte4 5rocessor..................................................................................................................(
!.! 0essellation "ontrol 5rocessor.............................................................................................(
!.' 0essellation Evaluation 5rocessor........................................................................................&
!.% 2eoetr- 5rocessor.............................................................................................................&
!.* 6ragent 5rocessor..............................................................................................................&
' Basics........................................................................................................................................1$
'.1 "haracter ,et......................................................................................................................1$
'.! ,ource ,trings....................................................................................................................1$
'.' 5re1rocessor.......................................................................................................................11
'.% "oents..........................................................................................................................1+
'.* 0okens................................................................................................................................1)
'.+ Ke-words............................................................................................................................1)
'.) Identi#iers...........................................................................................................................1&
'.( De#initions..........................................................................................................................1&
'.(.1 ,tatic 7se....................................................................................................................!$
'.(.! 7ni#or and 8on97ni#or "ontrol 6low..................................................................!$
'.(.' D-naicall- 7ni#or E41ressions.............................................................................!$
% Varia:les and 0-1es..................................................................................................................!1
%.1 Basic 0-1es........................................................................................................................!1
%.1.1 Void............................................................................................................................!*
%.1.! Booleans.....................................................................................................................!*
%.1.' Integers.......................................................................................................................!*
%.1.% 6loats..........................................................................................................................!)
%.1.* Vectors........................................................................................................................!(
%.1.+ ;atrices......................................................................................................................!(
%.1.) .1a<ue 0-1es.............................................................................................................!&
3
%.1.).1 ,a1lers.............................................................................................................!&
%.1.).! Iages.................................................................................................................!&
%.1.).' Atoic "ounters.................................................................................................'$
%.1.( ,tructures....................................................................................................................'$
%.1.& Arra-s.........................................................................................................................'1
%.1.1$ I1licit "onversions................................................................................................''
%.1.11 Initiali=ers.................................................................................................................'%
%.! ,co1ing...............................................................................................................................'+
%.' ,torage >uali#iers...............................................................................................................'(
%.'.1 De#ault ,torage >uali#ier............................................................................................'&
%.'.! "onstant >uali#ier......................................................................................................'&
%.'.' "onstant E41ressions.................................................................................................'&
%.'.% In1ut Varia:les...........................................................................................................%$
%.'.* 7ni#or......................................................................................................................%!
%.'.+ .ut1ut Varia:les.........................................................................................................%'
%.'.) Inter#ace Blocks..........................................................................................................%*
%.% 3a-out >uali#iers................................................................................................................%(
%.%.1 In1ut 3a-out >uali#iers...............................................................................................%(
%.%.1.1 0essellation Evaluation In1uts............................................................................*$
%.%.1.! 2eoetr- ,hader In1uts......................................................................................*1
%.%.1.' 6ragent ,hader In1uts......................................................................................*'
%.%.! .ut1ut 3a-out >uali#iers............................................................................................*%
%.%.!.1 0essellation "ontrol .ut1uts..............................................................................*+
%.%.!.! 2eoetr- .ut1uts...............................................................................................*+
%.%.!.' 6ragent .ut1uts...............................................................................................*(
%.%.' 7ni#or Block 3a-out >uali#iers...............................................................................*&
%.%.% .1a<ue97ni#or 3a-out >uali#iers............................................................................+1
%.%.%.1 Atoic "ounter 3a-out >uali#iers.....................................................................+!
%.%.%.! 6orat 3a-out >uali#iers....................................................................................+'
%.* Inter1olation >uali#iers......................................................................................................+*
%.*.1 Redeclaring Built9in Inter1olation Varia:les in the "o1ati:ilit- 5ro#ile.................++
%.+ 5araeter >uali#iers...........................................................................................................+)
%.) 5recision and 5recision >uali#iers.....................................................................................+)
%.).1 Range and 5recision...................................................................................................+)
%.).! 5recision >uali#iers....................................................................................................+(
%.).' De#ault 5recision >uali#iers.......................................................................................+&
%.).% Availa:le 5recision >uali#iers....................................................................................)$
%.( Variance and the Invariant >uali#ier..................................................................................)$
%.(.1 0he Invariant >uali#ier...............................................................................................)$
%.(.! Invariance o# "onstant E41ressions...........................................................................)1
%.& 0he 5recise >uali#ier..........................................................................................................)1
%.1$ ;eor- >uali#iers...........................................................................................................)'
4
%.11 .rder o# >uali#ication......................................................................................................)*
* .1erators and E41ressions........................................................................................................)+
*.1 .1erators............................................................................................................................)+
*.! Arra- .1erations...............................................................................................................))
*.' 6unction "alls....................................................................................................................))
*.% "onstructors.......................................................................................................................))
*.%.1 "onversion and ,calar "onstructors..........................................................................))
*.%.! Vector and ;atri4 "onstructors.................................................................................)(
*.%.' ,tructure "onstructors................................................................................................($
*.%.% Arra- "onstructors.....................................................................................................(1
*.* Vector and ,calar "o1onents and 3ength.......................................................................(1
*.+ ;atri4 "o1onents............................................................................................................('
*.) ,tructure and Arra- .1erations..........................................................................................('
*.( Assignents.......................................................................................................................(%
*.& E41ressions........................................................................................................................(*
*.1$ Vector and ;atri4 .1erations..........................................................................................((
+ ,tateents and ,tructure...........................................................................................................&$
+.1 6unction De#initions...........................................................................................................&1
+.1.1 6unction "alling "onventions....................................................................................&'
+.1.! ,u:routines.................................................................................................................&*
+.! ,election.............................................................................................................................&+
+.' Iteration..............................................................................................................................&)
+.% Ju1s..................................................................................................................................&(
) Built9in Varia:les......................................................................................................................&&
).1 Built9In 3anguage Varia:les..............................................................................................&&
).1.1 "o1ati:ilit- 5ro#ile Built9In 3anguage Varia:les..................................................1$+
).! "o1ati:ilit- 5ro#ile Verte4 ,hader Built9In In1uts.......................................................1$&
).' Built9In "onstants............................................................................................................1$&
).'.1 "o1ati:ilit- 5ro#ile Built9In "onstants..................................................................111
).% Built9In 7ni#or ,tate.....................................................................................................11!
).%.1 "o1ati:ilit- 5ro#ile ,tate.......................................................................................11!
( Built9in 6unctions...................................................................................................................11+
(.1 Angle and 0rigonoetr- 6unctions..................................................................................11)
(.! E41onential 6unctions......................................................................................................11&
(.' "oon 6unctions..........................................................................................................1!$
(.% 6loating95oint 5ack and 7n1ack 6unctions.....................................................................1!+
(.* 2eoetric 6unctions........................................................................................................1!(
(.+ ;atri4 6unctions..............................................................................................................1'$
(.) Vector Relational 6unctions.............................................................................................1'!
(.( Integer 6unctions..............................................................................................................1'%
(.& 0e4ture 6unctions.............................................................................................................1'+
(.&.1 0e4ture >uer- 6unctions..........................................................................................1')
5
(.&.! 0e4el 3ooku1 6unctions...........................................................................................1'&
(.&.' 0e4ture 2ather Instructions......................................................................................1%+
(.&.% "o1ati:ilit- 5ro#ile 0e4ture 6unctions..................................................................1%&
(.1$ Atoic9"ounter 6unctions.............................................................................................1*1
(.11 Iage 6unctions.............................................................................................................1*1
(.1! 6ragent 5rocessing 6unctions......................................................................................1*%
(.1!.1 Derivative 6unctions..............................................................................................1*%
(.1!.! Inter1olation 6unctions...........................................................................................1*+
(.1' 8oise 6unctions..............................................................................................................1*)
(.1% 2eoetr- ,hader 6unctions...........................................................................................1*(
(.1* ,hader Invocation "ontrol 6unctions.............................................................................1+$
(.1+ ,hader ;eor- "ontrol 6unctions................................................................................1+$
6
1 Introduction
0his docuent s1eci#ies onl- version %.!$ o# the .1en23 ,hading 3anguage. It re<uires ??VER,I.8??
to su:stitute %!$, and re<uires #version to acce1t onl- %!$. I# #version is declared with a saller
nu:er, the language acce1ted is a 1revious version o# the shading language, which will :e su11orted
de1ending on the version and t-1e o# conte4t in the .1en23 A5I. ,ee the .1en23 2ra1hics ,-ste
,1eci#ication, Version %.!, #or details on what language versions are su11orted.
5revious versions o# the .1en23 ,hading 3anguage, as well as the .1en23 E, ,hading 3anguage, are
not strict su:sets o# the version s1eci#ied here, 1articularl- with res1ect to 1recision, nae9hiding rules,
and treatent o# inter#ace varia:les. ,ee the s1eci#ication corres1onding to a 1articular language version
#or details s1eci#ic to that version o# the language.
All .1en23 2ra1hics ,-ste ,1eci#ication re#erences in this s1eci#ication are to version %.!.
1
1 Introduction
1.1 Acknowledgments
0his s1eci#ication is :ased on the work o# those who contri:uted to 1ast versions o# the .1en23
3anguage ,1eci#ication, the .1en23 E, !.$ 3anguage ,1eci#ication, and the #ollowing contri:utors to
this version:
5at Brown, 8VIDIA
Je## Bol=, 8VIDIA
6rank "hen
5ierre Boudier, A;D
5iers Daniell, 8VIDIA
"hris Dodd, 8VIDIA
8ick /aeel, 8VIDIA
Jason 2reen, 0rans2aing
Brent Insko, Intel
Jon 3eech
Bill 3icea9Kane, A;D
Daniel Koch, 0rans2aing
Barthold 3ichten:elt, 8VIDIA
Bruce ;err-, AR;
Ro:ert .hannessian
Acorn 5oole-, 8VIDIA
Kevin Rogovin
Ian Roanick, Intel
2reg Roth, 8vidia
2raha ,ellers, A;D
Dave ,hreiner, AR;
Jere- ,andel, A11le
Ro:ert ,i1son, >ualco
Eric @erness, 8VIDIA
;ark Aoung, A;D
1.2 Changes
1.2.1 Changes from revision 10 of ersion !.10
"lari#- that textureGatherOffsetBC can take non9constants #or the o##sets.
1.2.2 Changes from revision " of ersion !.20
Add su:routine calling s-nta4 to the graar in the :ack Boitted in revision & when su:routine
declarations were addedC.
Allow decial integer literals, which are alwa-s 1ositive, to set the sign :it. E.g., the decial9
literal re1resentation o# $4A$$$$$$$ is legal and creates a negative signed integer o# that :it
1attern.
6i4 t-1o to allow integer cu:e9arra- te4tures in the :uilt9in #unction te4ture,i=eBC.
2
1 Introduction
"orrect inadvertentl- :road inde4ing :- restricting inde4es o# iages and inde4es o# uni#or
:locks to :eing d-naicall-9uni#or integral e41ressions. 0his correction also a11lies to earlier
releases #or uni#or :locks B%.$$ and %.1$C.
1.2.# Changes from revision $ of ersion !.20
5ut the precise ke-word as a <uali#ier in the 1araeter in9line graar in section +.1.1. It has
alwa-s :een descri:ed as 1art o# the 1araeter graar, :ut Dust issing.
Rein#orce that E:it nu:erF will alwa-s re#er to counting u1 #ro the lowest9order :it as :it $.
Be ore s1eci#ic a:out values and seantics o# literal '!9:it integers. In 1articular, 1ositive
signed decial literals ust #it in '1 :its, while unsigned andGor he4adecial literals ust #it in
'! :its.
;ake 23,3 consistent with the A5I regarding user cli11ing, :- no longer re#erring to
gl_Position when gl_ClipVertex is not written. Rather, user cli11ing :ecoes unde#ined.
Add the uni#or declaration #or gl_um!amples.
0-1o: 7se vec! instead o# vec' #or coordinate in te4ture2atherHBsa1ler!DRect,...C.
71date the graar #or
Ar:itrar- lists o# <uali#iers. 0reating :oth 1araeter declarations and non91araeter
declarations the sae.
Add su:routines. Done as 1art o# list o# <uali#iers, #or #uture e41ansion o# #unctions
declared with other <uali#iers.
Add iages.
Add list o# identi#iers #or redeclarations. E.g., invariant var1, var!, var'I
Add 1recise ke-word.
Add constant dou:les.
1.2.! Changes from revision % of ersion !.20
,oe inor graar BEnglishC changes.
"onsistentl- state that verte4 shader in1uts o# dvec3 and dvec4 onl- take a single location.
1.2.& Changes from revision ' of ersion !.20
"lari#- rules #or se1arate9shader9o:Dect inter#ace atching:
au4iliar- <uali#iers ust atch
inter1olation <uali#iers ust atch
location la-out <uali#ier ust atch
1recision <uali#iers need not atch
3
1 Introduction
invariant and precise <uali#iers are #or out1uts so need not :e on a corres1onding in1ut to
atch
"lari#- how locations are used:
locations canJt :e used on :locks or :lock e:ers
verte4 shader in1ut locations are #or the nu:er o# the generic verte4 attri:ute, #ragent
out1ut locations are #or the color out1ut nu:er, and all other in1ut and out1ut locations
s1eci#- a vector nu:er
doule and dvec! take onl- one location
ore detail is given on structure locations
"lari#- that memor"#arrier$% controls onl- eor- accesses within the calling shader, to a##ect
what is o:served :- other invocations.
1.2.' Summar( of Changes from ersion !.10
8ote: 8o #eatures were de1recated :etween versions %.1$ and %.!$.
;ove these 1reviousl- de1recated #eatures to :e onl- in the co1ati:ilit- 1ro#ile:
0he ke-word attriute #or verte4 shader in1uts. B7se in instead.C
0he ke-word var"ing #or in1uts and out1uts. B7se in and out instead.C
0he original te4turing :uilt9in #unctions. B7se the new #ors instead.C
0he :uilt9in varia:les gl_"ragColor and gl_"ragData. B7se out instead.C
Built9in constants related to these.
"hange #ro A,"II to 7069( #or the language character set and also allow an- characters inside
coents Be4ce1t the :-te value $C, including JKJ.
Add line9continuation using JKJ, as in "LL.
E, convergence
Add ta:le showing E0reatent o# ;isatched In1utG.ut1ut Varia:lesF in section %.'.%.
8a8s are not re<uired to :e generated, dividing a non9=ero :- =ero akes in#, see !nd
1aragra1h %.).1 #or #ull odi#ication.
"lari#- that .4-=w4-.4- is illegal, is it te1oraril- akes a Evec+F.
"lari#- that return stateents onl- acce1t values Bno return o# a void #unctionC.
Add iage t-1es B23?ARB?shader?iage?load?storeC
'' new t-1es, all with EimageF in their nae, corres1ond to the non9shadow te4ture t-1es
addition o# eor- <uali#iers: coherent, volatile, restrict, readonl", and writeonl"
can readGwriteGodi#- iages #ro a shader, through new :uilt9in #unctions
4
1 Introduction
<uali#iers can act inde1endentl- on the o1a<ue shader varia:le and the :acking iage, so
e4tra <uali#iers can :e used to se1aratel- <uali#- these
Varia:les declared in if and else stateents are sco1ed onl- to the end o# those stateents. 8ote,
this is not :ackward co1ati:le, it a- de1end on Mversion.
Allow i1licit conversions o# return values to the declared t-1e o# the #unction.
0he const ke-word can :e used to declare varia:les within a #unction :od- with initiali=er
e41ressions that are not constant e41ressions.
>uali#iers on varia:le declarations no longer have to #ollow a strict order. 0he la"out <uali#ier
can :e used ulti1le ties, and ulti1le 1araeter <uali#iers can :e used.
5araeter <uali#iers can include 1recision and eor- <uali#iers.
Add a new atomic&uint t-1e to su11ort atoic counters. Also, add :uilt9in #unctions #or
ani1ulating atoic counters.
atomic'ounter(ncrement, atomic'ounter)ecrement, and atomic'ounter
Add la-out <uali#ier identi#iers #in$ing and o%%set to :ind units to sa1ler and iage varia:le
declarations, atoic counters, and uni#or :locks.
Add :uilt9in #unctions to 1ackGun1ack 1+ :it #loating91oint nu:ers
BARB?shading?language?1ack!#C.
pack*alf!x1+ and unpack*alf!x1+
pack,norm!x1+ and unpack,norm!x1+
Add gl&-rag)epth la-out <uali#iers to counicate what kind o# changes will :e ade to
gl&-rag)epth B23?A;D?conservative de1thC.
Add "9st-le curl- :race initiali=er lists s-nta4 #or initiali=ers. 6ull initiali=ation o# aggregates is
re<uired when these are used.
Allow .lengthBC to :e a11lied to vectors and atrices, returning the nu:er o# co1onents or
coluns.
"lari#- that .lengthBC returns an int t-1e and can :e used as a constant integer e41ression.
Allow swi==le o1erations on scalars.
Even the 1otential #or recursion through su:routine uni#ors is an error.
5ositive signed decial literals, as well as octal and he4adecial, can set all '! :its. 0his
includes setting the sign :it to create a negative value.
;ake 23,3 consistent with the A5I regarding user cli11ing, :- no longer re#erring to
gl_Position when gl_ClipVertex is not written. Rather, user cli11ing :ecoes unde#ined.
;inor consistenc- #i4es, corrections
"onsistentl- state structures have e:ers not #ields. 0he 1eriod B . C is still called the #ield
selector, #or all its ulti1le uses.
Reove coent that there is no counication :etween instantiations o# a shader.
5
1 Introduction
"lari#ied that a coa se<uence9o1erator e41ression cannot :e a constant e41ression. E.g.,
EB!,'CF is not allowed, seanticall-, as a valid constant e41ression ', even though it is an
e41ression that will evaluate to '.
7se vec! instead o# vec3 #or coordinate in te4ture2atherHBsa1ler!DRect,...C.
"lari#- that textureGatherOffsetBC can take non9constants #or the o##sets.
6i4 t-1o to allow integer cu:e9arra- te4tures in the :uilt9in #unction te4ture,i=eBC.
"orrectl- restrict inde4es o# uni#or :locks to :eing d-naicall-9uni#or integral e41ressions.
0his correction also a11lies to earlier releases B%.$$ and %.1$C, which inadvertentl- allowed non9
uni#or inde4es.
71date the graar in the last section.
1.# Overvie)
0his docuent descri:es &'e (pen)L !'a$ing Language* version %.!$.
Inde1endent co1ilation units written in this language are called s'a$ers. A program is a set o# shaders
that are co1iled and linked together, co1letel- creating one or ore o# the 1rograa:le stages o# the
.1en23 1i1eline. All the shaders #or a single 1rograa:le stage ust :e within the sae 1rogra. A
co1lete set o# 1rograa:le stages can :e 1ut into a single 1rogra or the stages can :e 1artitioned
across ulti1le 1rogras. 0he ai o# this docuent is to thoroughl- s1eci#- the 1rograing language.
0he .1en23 2ra1hics ,-ste ,1eci#ication will s1eci#- the .1en23 entr- 1oints used to ani1ulate and
counicate with 1rogras and shaders.
1.! *rror +andling
"o1ilers, in general, acce1t 1rogras that are ill9#ored, due to the i1ossi:ilit- o# detecting all ill9
#ored 1rogras. 5orta:ilit- is onl- ensured #or well9#ored 1rogras, which this s1eci#ication
descri:es. "o1ilers are encouraged to detect ill9#ored 1rogras and issue diagnostic essages, :ut are
not re<uired to do so #or all cases. "o1ilers are re<uired to return essages regarding le4icall-,
graaticall-, or seanticall- incorrect shaders.
1.& T(pographical Conventions
Italic, :old, and #ont choices have :een used in this s1eci#ication 1riaril- to i1rove reada:ilit-. "ode
#ragents use a #i4ed width #ont. Identi#iers e:edded in te4t are italici=ed. Ke-words e:edded in te4t
are :old. .1erators are called :- their nae, #ollowed :- their s-:ol in :old in 1arentheses. 0he
clari#-ing graar #ragents in the te4t use :old #or literals and italics #or non9terinals. 0he o##icial
graar in section & E,hading 3anguage 2raarF uses all ca1itals #or terinals and lower case #or
non9terinals.
1.' ,eprecation
8ote that while this section is true o# 23,3 in general, version %.! has no de1recated #eatures in it.
5reviousl- de1recated #eatures have :een oved to the co1ati:ilit- 1ro#ile and no new #eatures have
:een de1recated.
6
1 Introduction
5revious versions o# the .1en23 ,hading 3anguage de1recated soe #eatures. 0hese are clearl- called
out in this s1eci#ication as Ede1recatedF. 0he- are still 1resent in this version o# the language, :ut are
targeted #or 1otential reoval in a #uture version o# the shading language. 0he .1en23 A5I has a
#orward co1ati:ilit- ode that will disallow use o# de1recated #eatures. I# co1iling in a ode where
use o# de1recated #eatures is disallowed, their use causes co1ile tie errors. ,ee the .1en23 2ra1hics
,-ste ,1eci#ication #or details on what causes de1recated language #eatures to :e acce1ted or to return
an error.
7
2 Overvie) of OpenGL Shading
0he .1en23 ,hading 3anguage is actuall- several closel- related languages. 0hese languages are used
to create shaders #or each o# the 1rograa:le 1rocessors contained in the .1en23 1rocessing 1i1eline.
"urrentl-, these 1rocessors are the verte4, tessellation control, tessellation evaluation, geoetr-, and
#ragent 1rocessors.
7nless otherwise noted in this 1a1er, a language #eature a11lies to all languages, and coon usage will
re#er to these languages as a single language. 0he s1eci#ic languages will :e re#erred to :- the nae o#
the 1rocessor the- target: verte4, tessellation control, tessellation evaluation, geoetr-, or #ragent.
;ost .1en23 state is not tracked or ade availa:le to shaders. 0-1icall-, user9de#ined varia:les will :e
used #or counicating :etween di##erent stages o# the .1en23 1i1eline. /owever, a sall aount o#
state is still tracked and autoaticall- ade availa:le to shaders, and there are a #ew :uilt9in varia:les #or
inter#aces :etween di##erent stages o# the .1en23 1i1eline.
2.1 erte- .rocessor
0he vertex processor is a 1rograa:le unit that o1erates on incoing vertices and their associated data.
"o1ilation units written in the .1en23 ,hading 3anguage to run on this 1rocessor are called vertex
s'a$ers. @hen a co1lete set o# verte4 shaders are co1iled and linked, the- result in a vertex s'a$er
executa#le that runs on the verte4 1rocessor.
0he verte4 1rocessor o1erates on one verte4 at a tie. It does not re1lace gra1hics o1erations that re<uire
knowledge o# several vertices at a tie.
2.2 Tessellation Control .rocessor
0he tessellation control 1rocessor is a 1rograa:le unit that o1erates on a 1atch o# incoing vertices
and their associated data, eitting a new out1ut 1atch. "o1ilation units written in the .1en23 ,hading
3anguage to run on this 1rocessor are called tessellation control shaders. @hen a co1lete set o#
tessellation control shaders are co1iled and linked, the- result in a tessellation control shader e4ecuta:le
that runs on the tessellation control 1rocessor.
0he tessellation control shader is invoked #or each verte4 o# the out1ut 1atch. Each invocation can read
the attri:utes o# an- verte4 in the in1ut or out1ut 1atches, :ut can onl- write 1er9verte4 attri:utes #or the
corres1onding out1ut 1atch verte4. 0he shader invocations collectivel- 1roduce a set o# 1er91atch
attri:utes #or the out1ut 1atch. A#ter all tessellation control shader invocations have co1leted, the out1ut
vertices and 1er91atch attri:utes are asse:led to #or a 1atch to :e used :- su:se<uent 1i1eline stages.
0essellation control shader invocations run ostl- inde1endentl-, with unde#ined relative e4ecution order.
/owever, the :uilt9in #unction :arrierBC can :e used to control e4ecution order :- s-nchroni=ing
invocations, e##ectivel- dividing tessellation control shader e4ecution into a set o# 1hases. 0essellation
control shaders will get unde#ined results i# one invocation reads a 1er9verte4 or 1er91atch attri:ute
8
2 Overview of OpenGL Shading
written :- another invocation at an- 1oint during the sae 1hase, or i# two invocations atte1t to write
di##erent values to the sae 1er91atch out1ut in a single 1hase.
2.# Tessellation *valuation .rocessor
0he tessellation evaluation 1rocessor is a 1rograa:le unit that evaluates the 1osition and other
attri:utes o# a verte4 generated :- the tessellation 1riitive generator, using a 1atch o# incoing vertices
and their associated data. "o1ilation units written in the .1en23 ,hading 3anguage to run on this
1rocessor are called tessellation evaluation shaders. @hen a co1lete set o# tessellation evaluation
shaders are co1iled and linked, the- result in a tessellation evaluation shader e4ecuta:le that runs on the
tessellation evaluation 1rocessor.
Each invocation o# the tessellation evaluation e4ecuta:le co1utes the 1osition and attri:utes o# a single
verte4 generated :- the tessellation 1riitive generator. 0he e4ecuta:le can read the attri:utes o# an-
verte4 in the in1ut 1atch, 1lus the tessellation coordinate, which is the relative location o# the verte4 in the
1riitive :eing tessellated. 0he e4ecuta:le writes the 1osition and other attri:utes o# the verte4.
2.! Geometr( .rocessor
0he geometr+ processor is a 1rograa:le unit that o1erates on data #or incoing vertices #or a 1riitive
asse:led a#ter verte4 1rocessing and out1uts a se<uence o# vertices #oring out1ut 1riitives.
"o1ilation units written in the .1en23 ,hading 3anguage to run on this 1rocessor are called geometr+
s'a$ers. @hen a co1lete set o# geoetr- shaders are co1iled and linked, the- result in a geometr+
s'a$er executa#le that runs on the geoetr- 1rocessor.
A single invocation o# the geoetr- shader e4ecuta:le on the geoetr- 1rocessor will o1erate on a
declared in1ut 1riitive with a #i4ed nu:er o# vertices. 0his single invocation can eit a varia:le
nu:er o# vertices that are asse:led into 1riitives o# a declared out1ut 1riitive t-1e and 1assed to
su:se<uent 1i1eline stages.
2.& /ragment .rocessor
0he %ragment processor is a 1rograa:le unit that o1erates on #ragent values and their associated
data. "o1ilation units written in the .1en23 ,hading 3anguage to run on this 1rocessor are called
%ragment s'a$ers. @hen a co1lete set o# #ragent shaders are co1iled and linked, the- result in a
%ragment s'a$er executa#le that runs on the #ragent 1rocessor.
A #ragent shader cannot change a #ragentJs Bx, +C 1osition. Access to neigh:oring #ragents is not
allowed. 0he values co1uted :- the #ragent shader are ultiatel- used to u1date #rae:u##er eor-
or te4ture eor-, de1ending on the current .1en23 state and the .1en23 coand that caused the
#ragents to :e generated.
9
# 0asics
#.1 Character Set
0he source character set used #or the .1en23 shading languages, outside o# coents, is a su:set o#
7069(. It includes the #ollowing characters:
0he letters a./, A.01 and the underscore B ? C.
0he nu:ers 2.3.
0he s-:ols 1eriod B.C, 1lus B4C, dash B.C, slash B5C, asterisk B6C, 1ercent B7C, angled :rackets B8 and
9C, s<uare :rackets B : and ; C, 1arentheses B $ and % C, :races B < and = C, caret B>C, vertical :ar B ? C,
a1ersand B@C, tilde BAC, e<uals BBC, e4claation 1oint BCC, colon BDC, seicolon BEC, coa B1C, and
<uestion ark BFC.
0he nu:er sign B#C #or 1re1rocessor use.
0he :ackslash B G C as the line9continuation character when used as the last character o# a line, Dust
:e#ore a new line.
@hite s1ace: the s1ace character, hori=ontal ta:, vertical ta:, #or #eed, carriage9return, and line9
#eed.
An error will :e given i# another character is used outside a coent.
0here are no trigra1hs. 0here are no esca1e se<uences or other uses o# the :ackslash :e-ond use as the
line9continuation character.
3ines are relevant #or co1iler diagnostic essages and the 1re1rocessor. 0he- are terinated :-
carriage9return or line9#eed. I# :oth are used together, it will count as onl- a single line terination. 6or
the reainder o# this docuent, an- o# these co:inations is si1l- re#erred to as a new line.
In general, the languageNs use o# this character set is case sensitive.
0here are no character or string data t-1es, so no <uoting characters are included.
0here is no end9o#9#ile character.
#.2 Source Strings
0he source #or a single shader is an arra- o# strings o# characters #ro the character set. A single shader
is ade #ro the concatenation o# these strings. Each string can contain ulti1le lines, se1arated :- new
lines. 8o new lines need :e 1resent in a stringI a single line can :e #ored #ro ulti1le strings. 8o new
lines or other characters are inserted :- the i1leentation when it concatenates the strings to #or a
single shader. ;ulti1le shaders can :e linked together to #or a single 1rogra.
Diagnostic essages returned #ro co1iling a shader ust identi#- :oth the line nu:er within a string
and which source string the essage a11lies to. ,ource strings are counted se<uentiall- with the #irst
1
3 !a"ic"
string :eing string $. 3ine nu:ers are one ore than the nu:er o# new lines that have :een 1rocessed,
including counting the new lines that will :e reoved :- the line9continuation character B G C.
3ines se1arated :- the line9continuation character 1receding a new line are concatenated together :e#ore
either coent 1rocessing or 1re1rocessing. 8o white s1ace is su:stituted #or the line9continuation
character. 0hat is, a single token could :e #ored :- the concatenation :- taking the characters at the end
o# one line concatenating the with the characters at the :eginning o# the ne4t line.
float f\
oo;
// forms a single line equivalent to float foo;
// (assuming '\' is the last character before the new line and oo are
// the first two characters of the next line)
#.# .reprocessor
0here is a 1re1rocessor that 1rocesses the source strings as 1art o# the co1ilation 1rocess.
0he co1lete list o# 1re1rocessor directives is as #ollows.
#
#define
#undef
#if
#ifdef
#ifndef
#else
#elif
#endif
#error
#ragma
#extension
#version
#line
0he #ollowing o1erators are also availa:le
defined
##
Each nu:er sign B#C can :e 1receded in its line onl- :- s1aces or hori=ontal ta:s. It a- also :e
#ollowed :- s1aces and hori=ontal ta:s, 1receding the directive. Each directive is terinated :- a new
line. 5re1rocessing does not change the nu:er or relative location o# new lines in a source string.
5re1rocessing takes 1laces a#ter new lines have :een reoved :- the line9continuation character.
0he nu:er sign B#C on a line :- itsel# is ignored. An- directive not listed a:ove will cause a diagnostic
essage and ake the i1leentation treat the shader as ill9#ored.
11
3 !a"ic"
#define and #undef #unctionalit- are de#ined as is standard #or "LL 1re1rocessors #or acro de#initions
:oth with and without acro 1araeters.
0he #ollowing 1rede#ined acros are availa:le
!!"#$%!!
!!&#"%!!
!!'%()#*$!!
__L,-__ will su:stitute a decial integer constant that is one ore than the nu:er o# 1receding new
lines in the current source string.
__",L-__ will su:stitute a decial integer constant that sa-s which source string nu:er is currentl-
:eing 1rocessed.
__V-R!,(__ will su:stitute a decial integer re#lecting the version nu:er o# the .1en23 shading
language. 0he version o# the shading language descri:ed in this docuent will have __V-R!,(__
su:stitute the decial integer %!$.
All acro naes containing two consecutive underscores B && C are reserved #or #uture use as 1rede#ined
acro naes. All acro naes 1re#i4ed with E23?F BE23F #ollowed :- a single underscoreC are also
reserved.
#if1 #ifdef1 #ifndef1 #else1 #elif1 and #endif are de#ined to o1erate as is standard #or "LL 1re1rocessors.
E41ressions #ollowing #if and #elif are #urther restricted to e41ressions o1erating on literal integer
constants, 1lus identi#iers consued :- the defined o1erator. It is an error to use #if or #elif on
e41ressions containing unde#ined acro naes, other than as arguents to the defined o1erator.
"haracter constants are not su11orted. 0he o1erators availa:le are as #ollows.
.recedence Operator class Operators 1ssociativit(
1 BhighestC 1arenthetical grou1ing B C 8A
! unar- de#ined
L 9 O P
Right to 3e#t
' ulti1licative H G Q 3e#t to Right
% additive L 9 3e#t to Right
* :it9wise shi#t RR SS 3e#t to Right
+ relational R S RT ST 3e#t to Right
) e<ualit- TT PT 3e#t to Right
( :it9wise and U 3e#t to Right
& :it9wise e4clusive or V 3e#t to Right
1$ :it9wise inclusive or W 3e#t to Right
11 logical and UU 3e#t to Right
1! BlowestC logical inclusive or W W 3e#t to Right
12
3 !a"ic"
0he defined o1erator can :e used in either o# the #ollowing wa-s:
defined identifier
defined ( identifier )
0wo tokens in a acro can :e concatenated into one token using the token 1asting B##C o1erator, as is
standard #or "LL 1re1rocessors. 0he result ust :e a valid single token, which will then :e su:Dect to
acro e41ansion. 0hat is, acro e41ansion ha11ens onl- a#ter token 1asting. 0here are no other nu:er
sign :ased o1erators Be.g., no # or #HC, nor is there a si/eof o1erator.
0he seantics o# a11l-ing o1erators to integer literals in the 1re1rocessor atch those standard in the "L
L 1re1rocessor, not those in the .1en23 ,hading 3anguage.
5re1rocessor e41ressions will :e evaluated according to the :ehavior o# the host 1rocessor, not the
1rocessor targeted :- the shader.
#error will cause the i1leentation to 1ut a diagnostic essage into the shader o:DectNs in#oration log
Bsection +.1.1! E,hader and 5rogra >ueriesF in the .1en23 2ra1hics ,-ste ,1eci#ication #or how to
access a shader o:DectNs in#oration logC. 0he essage will :e the tokens #ollowing the #error directive,
u1 to the #irst new line. 0he i1leentation ust then consider the shader to :e ill9#ored.
#pragma allows i1leentation de1endent co1iler control. 0okens #ollowing #pragma are not su:Dect
to 1re1rocessor acro e41ansion. I# an i1leentation does not recogni=e the tokens #ollowing
#pragma, then it will ignore that 1raga. 0he #ollowing 1ragas are de#ined as 1art o# the language.
#ragma )+,-"
0he ,I)GJ 1raga is used to reserve 1ragas #or use :- #uture revisions o# this language. 8o
i1leentation a- use a 1raga whose #irst token is ,I)GJ.
#ragma otimi.e(on)
#ragma otimi.e(off)
can :e used to turn o## o1tii=ations as an aid in develo1ing and de:ugging shaders. It can onl- :e used
outside #unction de#initions. B- de#ault, o1tii=ation is turned on #or all shaders. 0he de:ug 1raga
#ragma debug(on)
#ragma debug(off)
can :e used to ena:le co1iling and annotating a shader with de:ug in#oration, so that it can :e used
with a de:ugger. It can onl- :e used outside #unction de#initions. B- de#ault, de:ug is turned o##.
,haders should declare the version o# the language the- are written to. 0he language version a shader is
written to is s1eci#ied :-
#version number profile
opt
where num#er ust :e a version o# the language, #ollowing the sae convention as __V-R!,(__ a:ove.
0he directive E#version 4!2F is re<uired in an- shader that uses version %.!$ o# the language. An-
num#er re1resenting a version o# the language a co1iler does not su11ort will cause an error to :e
generated. Version 1.1$ o# the language does not re<uire shaders to include this directive, and shaders that
do not include a #version directive will :e treated as targeting version 1.1$. ,haders that s1eci#-
#version 1$$ will :e treated as targeting version 1.$$ o# the .1en23 E, ,hading 3anguage.
13
3 !a"ic"
,haders declaring version 1.%$, 1.*$, '.'$, %.$, or %.1 o# the shading language can :e linked with shaders
declaring version %.!$ in the sae 1rogra. ,haders targeting earlier versions B1.'$ or earlierC o# the
shading language cannot :e linked with version %.!$ shaders.
I# the o1tional pro%ile arguent is 1rovided, it ust :e the nae o# an .1en23 1ro#ile. "urrentl-, there
are two choices:
core
comatibilit/
I# no pro%ile arguent is 1rovided, the de#ault is core. 7nless otherwise s1eci#ied, this s1eci#ication is
docuenting the core 1ro#ile, and ever-thing s1eci#ied #or the core 1ro#ile is also availa:le in the
co1ati:ilit- 1ro#ile. 6eatures s1eci#ied as :elonging s1eci#icall- to the co1ati:ilit- 1ro#ile are not
availa:le in the core 1ro#ile.
0here is a :uilt9in acro de#inition #or each 1ro#ile the i1leentation su11orts. All i1leentations
1rovide the #ollowing acro:
#define -"!core!rofile 0
I1leentations 1roviding the co1ati:ilit- 1ro#ile 1rovide the #ollowing acro:
#define -"!comatibilit/!rofile 0
0he #version directive ust occur in a shader :e#ore an-thing else, e4ce1t #or coents and white s1ace.
14
3 !a"ic"
B- de#ault, co1ilers o# this language ust issue co1ile tie s-ntactic, graatical, and seantic
errors #or shaders that do not con#or to this s1eci#ication. An- e4tended :ehavior ust #irst :e ena:led.
Directives to control the :ehavior o# the co1iler with res1ect to e4tensions are declared with the
#extension directive
#extension extension_name : behavior
#extension all : behavior
where extension_name is the nae o# an e4tension. E4tension naes are not docuented in this
s1eci#ication. 0he token all eans the :ehavior a11lies to all e4tensions su11orted :- the co1iler. 0he
#e'avior can :e one o# the #ollowing
behavior *ffect
re2uire Behave as s1eci#ied :- the e4tension extension_name.
2ive an error on the #extension i# the e4tension extension_name is not
su11orted, or i# all is s1eci#ied.
enable Behave as s1eci#ied :- the e4tension extension_name.
@arn on the #extension i# the e4tension extension_name is not su11orted.
2ive an error on the #extension i# all is s1eci#ied.
)arn Behave as s1eci#ied :- the e4tension extension_name, e4ce1t issue warnings
on an- detecta:le use o# that e4tension, unless such use is su11orted :- other
ena:led or re<uired e4tensions.
I# all is s1eci#ied, then warn on all detecta:le uses o# an- e4tension used.
disable Behave Bincluding issuing errors and warningsC as i# the e4tension
extension_name is not 1art o# the language de#inition.
I# all is s1eci#ied, then :ehavior ust revert :ack to that o# the non9e4tended
core version o# the language :eing co1iled to.
0he extension directive is a si1le, low9level echanis to set the :ehavior #or each e4tension. It does
not de#ine 1olicies such as which co:inations are a11ro1riate, those ust :e de#ined elsewhere. .rder
o# directives atters in setting the :ehavior #or each e4tension: Directives that occur later override those
seen earlier. 0he all variant sets the :ehavior #or all e4tensions, overriding all 1reviousl- issued
extension directives, :ut onl- #or the #e'aviors warn and disale.
15
3 !a"ic"
0he initial state o# the co1iler is as i# the directive
#extension all 1 disable
was issued, telling the co1iler that all error and warning re1orting ust :e done according to this
s1eci#ication, ignoring an- e4tensions.
Each e4tension can de#ine its allowed granularit- o# sco1e. I# nothing is said, the granularit- is a shader
Bthat is, a single co1ilation unitC, and the e4tension directives ust occur :e#ore an- non91re1rocessor
tokens. I# necessar-, the linker can en#orce granularities larger than a single co1ilation unit, in which
case each involved shader will have to contain the necessar- e4tension directive.
;acro e41ansion is not done on lines containing #extension and #version directives.
#line ust have, a#ter acro su:stitution, one o# the #ollowing #ors:
#line line
#line line source-string-number
where line and source-string-num#er are constant integer e41ressions. A#ter 1rocessing this directive
Bincluding its new lineC, the i1leentation will :ehave as i# it is co1iling at line nu:er line and source
string nu:er source-string-num#er. ,u:se<uent source strings will :e nu:ered se<uentiall-, until
another #line directive overrides that nu:ering.
#.! Comments
"oents are deliited :- GH and HG, or :- GG and a new line. 0he :egin coent deliiters BGH or GGC are
not recogni=ed as coent deliiters inside o# a coent, hence coents cannot :e nested. I# a
coent resides entirel- within a single line, it is treated s-ntacticall- as a single s1ace. 8ew lines are
not eliinated :- coents.
Inside coents, an- :-te values a- :e used, e4ce1t a :-te whose value is $. 8o errors will :e given
#or the content o# coents and no validation on the content o# coents need :e done.
Reoval o# new lines :- the line9continuation character B G C logicall- occurs :e#ore coents are
1rocessed. 0hat is, a single9line coent ending in the line9continuation character B G C includes the ne4t
line in the coent.
// a single2line comment containing the next line \
a 3 b; // this is still in the first comment
16
3 !a"ic"
#.& To3ens
0he language is a se<uence o# tokens. A token can :e
to.en:
.e+/or$
i$enti%ier
integer-constant
%loating-constant
operator
E < =
#.' 4e()ords
0he #ollowing are the ke-words in the language, and cannot :e used #or another 1ur1ose than that
de#ined :- this docuent:
attriute const uniform var"ing
coherent volatile restrict readonl" writeonl"
atomic&uint
la"out
centroid flat smooth noperspective
patch sample
reak continue do for while switch case default
if else
suroutine
in out inout
float doule int void ool true false
invariant
discard return
mat! mat3 mat4 dmat! dmat3 dmat4
mat!x! mat!x3 mat!x4 dmat!x! dmat!x3 dmat!x4
mat3x! mat3x3 mat3x4 dmat3x! dmat3x3 dmat3x4
mat4x! mat4x3 mat4x4 dmat4x! dmat4x3 dmat4x4
vec! vec3 vec4 ivec! ivec3 ivec4 vec! vec3 vec4 dvec! dvec3 dvec4
uint uvec! uvec3 uvec4
17
3 !a"ic"
lowp mediump highp precision
sampler1) sampler!) sampler3) sampler'ue
sampler1),hadow sampler!),hadow sampler'ue,hadow
sampler1)Arra" sampler!)Arra"
sampler1)Arra",hadow sampler!)Arra",hadow
isampler1) isampler!) isampler3) isampler'ue
isampler1)Arra" isampler!)Arra"
usampler1) usampler!) usampler3) usampler'ue
usampler1)Arra" usampler!)Arra"
sampler!)Kect sampler!)Kect,hadow isampler!)Kect usampler!)Kect
sampler#uffer isampler#uffer usampler#uffer
sampler!)L, isampler!)L, usampler!)L,
sampler!)L,Arra" isampler!)L,Arra" usampler!)L,Arra"
sampler'ueArra" sampler'ueArra",hadow isampler'ueArra" usampler'ueArra"
image1) iimage1) uimage1)
image!) iimage!) uimage!)
image3) iimage3) uimage3)
image!)Kect iimage!)Kect uimage!)Kect
image'ue iimage'ue uimage'ue
image#uffer iimage#uffer uimage#uffer
image1)Arra" iimage1)Arra" uimage1)Arra"
image!)Arra" iimage!)Arra" uimage!)Arra"
image'ueArra" iimage'ueArra" uimage'ueArra"
image!)L, iimage!)L, uimage!)L,
image!)L,Arra" iimage!)L,Arra" uimage!)L,Arra"
struct
0he #ollowing are the ke-words reserved #or #uture use. 7sing the will result in an error:
common partition active
asm
class union enum t"pedef template this packed
resource
18
3 !a"ic"
goto
inline noinline pulic static extern external interface
long short half fixed unsigned superp
input output
hvec! hvec3 hvec4 fvec! fvec3 fvec4
sampler3)Kect
filter
si/eof cast
namespace using
row&maMor
In addition, all identi#iers containing two consecutive underscores B&&C are reserved as 1ossi:le #uture
ke-words.
#.% Identifiers
Identi#iers are used #or varia:le naes, #unction naes, structure naes, and #ield selectors B#ield
selectors select co1onents o# vectors and atrices siilar to structure e:ers, as discussed in section
*.* EVector "o1onentsF and section *.+ E;atri4 "o1onentsF C. Identi#iers have the #or
i$enti%ier
non$igit
i$enti%ier non$igit
i$enti%ier $igit
non$igit: one o#
& a c d e f g h i M k l m n o p N r s t u v w x " /
A # ' ) O - G * ( P Q J L R O S T K , I U V W X Y 0
$igit: one o#
2 1 ! 3 4 Z + [ \ 3
Identi#iers starting with Egl?F are reserved #or use :- .1en23, and a- not :e declared in a shader as
either a varia:le or a #unction. /owever, as noted in the s1eci#ication, there are soe cases where
1reviousl- declared varia:les can :e redeclared, and 1redeclared Xgl?X naes are allowed to :e
redeclared in a shader onl- #or these s1eci#ic 1ur1oses. ;ore generall-, it is an error to redeclare a
varia:le, including those starting Egl?F.
#.$ ,efinitions
,oe language rules descri:ed :elow de1end on the #ollowing de#initions.
19
3 !a"ic"
#.$.1 Static 5se
A shader contains a static use o# Bor static assignment toC a varia:le x i#, a#ter 1re1rocessing, the shader
contains a stateent that would read Bor writeC x, whether or not run9tie #low o# control will cause that
stateent to :e e4ecuted.
#.$.2 5niform and 6on75niform Control /lo)
@hen e4ecuting stateents in a #ragent shader, control #low starts as uni%orm control %lo/I all #ragents
enter the sae control 1ath into mainBC. "ontrol #low :ecoes non-uni%orm when di##erent #ragents
take di##erent 1aths through control9#low stateents Bselection, iteration, and Du1sC. "ontrol #low
su:se<uentl- returns to :eing uni#or a#ter such divergent su:9stateents or ski11ed code co1letes,
until the ne4t tie di##erent control 1aths are taken.
6or e4a1le:
main()
4
float a 3 555;// this is uniform flow control
if (a 6 b) 4 // this exression is true for some fragments7 not all
5555; // non2uniform flow control
8 else 4
5555; // non2uniform flow control
8
5555; // uniform flow control again
8
.ther e4a1les o# non9uni#or #low control can occur within switch stateents and a#ter conditional
:reaks, continues, earl- returns, and a#ter #ragent discards, when the condition is true #or soe
#ragents :ut not others. 3oo1 iterations that onl- soe #ragents e4ecute are also non9uni#or #low
control.
0his is siilarl- de#ined #or other shader stages, :ased on the 1er9instance data ites the- 1rocess.
#.$.# ,(namicall( 5niform *-pressions
A #ragent9shader e41ression is $+namicall+ uni%orm i# all #ragents evaluating it get the sae resulting
value. @hen loo1s are involved, this re#ers to the e41ressionJs value #or the sae loo1 iteration. @hen
#unctions are involved, this re#ers to calls #ro the sae call 1oint.
0his is siilarl- de#ined #or other shader stages, :ased on the 1er9instance data the- 1rocess.
8ote that constant e41ressions are triviall- d-naicall- uni#or. It #ollows that t-1ical loo1 counters
:ased on these are also d-naicall- uni#or.
2
! ariables and T(pes
All varia:les and #unctions ust :e declared :e#ore :eing used. Varia:le and #unction naes are
identi#iers.
0here are no de#ault t-1es. All varia:le and #unction declarations ust have a declared t-1e, and
o1tionall- <uali#iers. A varia:le is declared :- s1eci#-ing its t-1e #ollowed :- one or ore naes
se1arated :- coas. In an- cases, a varia:le can :e initiali=ed as 1art o# its declaration :- using the
assignent o1erator BBC.
7ser9de#ined t-1es a- :e de#ined using struct to aggregate a list o# e4isting t-1es into a single nae.
0he .1en23 ,hading 3anguage is t-1e sa#e. 0here are soe i1licit conversions :etween t-1es.
E4actl- how and when this can occur is descri:ed in section %.1.1$ EI1licit "onversionsF and as
re#erenced :- other sections in this s1eci#ication.
!.1 0asic T(pes
0he .1en23 ,hading 3anguage su11orts the #ollowing :asic data t-1es, grou1ed as #ollows.
0rans1arent t-1es
T(pe 8eaning
void #or #unctions that do not return a value
ool a conditional t-1e, taking on values o# true or #alse
int a signed integer
uint an unsigned integer
float a single #loating91oint scalar
doule a single dou:le91recision #loating 1oint scalar
vec! a two9co1onent #loating91oint vector
vec3 a three9co1onent #loating91oint vector
vec4 a #our9co1onent #loating91oint vector
dvec! a two9co1onent dou:le91recision #loating91oint vector
dvec3 a three9co1onent dou:le91recision #loating91oint vector
dvec4 a #our9co1onent dou:le91recision #loating91oint vector
vec! a two9co1onent Boolean vector
vec3 a three9co1onent Boolean vector
vec4 a #our9co1onent Boolean vector
ivec! a two9co1onent signed integer vector
21
4 #aria$%e" and &'pe"
T(pe 8eaning
ivec3 a three9co1onent signed integer vector
ivec4 a #our9co1onent signed integer vector
uvec! a two9co1onent unsigned integer vector
uvec3 a three9co1onent unsigned integer vector
uvec4 a #our9co1onent unsigned integer vector
mat! a !Y! #loating91oint atri4
mat3 a 'Y' #loating91oint atri4
mat4 a %Y% #loating91oint atri4
mat!x! sae as a mat!
mat!x3 a #loating91oint atri4 with ! coluns and ' rows
mat!x4 a #loating91oint atri4 with ! coluns and % rows
mat3x! a #loating91oint atri4 with ' coluns and ! rows
mat3x3 sae as a mat3
mat3x4 a #loating91oint atri4 with ' coluns and % rows
mat4x! a #loating91oint atri4 with % coluns and ! rows
mat4x3 a #loating91oint atri4 with % coluns and ' rows
mat4x4 sae as a mat4
dmat! a !Y! dou:le91recision #loating91oint atri4
dmat3 a 'Y' dou:le91recision #loating91oint atri4
dmat4 a %Y% dou:le91recision #loating91oint atri4
dmat!x! sae as a dmat!
dmat!x3 a dou:le91recision #loating91oint atri4 with ! coluns and ' rows
dmat!x4 a dou:le91recision #loating91oint atri4 with ! coluns and % rows
dmat3x! a dou:le91recision #loating91oint atri4 with ' coluns and ! rows
dmat3x3 sae as a dmat3
dmat3x4 a dou:le91recision #loating91oint atri4 with ' coluns and % rows
dmat4x! a dou:le91recision #loating91oint atri4 with % coluns and ! rows
dmat4x3 a dou:le91recision #loating91oint atri4 with % coluns and ' rows
dmat4x4 sae as a dmat4
22
6loating 5oint .1a<ue 0-1es
T(pe 8eaning
sampler1)
image1)
a handle #or accessing a 1D te4ture
sampler!)
image!)
a handle #or accessing a !D te4ture
sampler3)
image3)
a handle #or accessing a 'D te4ture
sampler'ue
image'ue
a handle #or accessing a cu:e a11ed te4ture
sampler!)Kect
image!)Kect
a handle #or accessing a rectangular te4ture
sampler1)Arra"
image1)Arra"
a handle #or accessing a 1D arra- te4ture
sampler!)Arra"
image!)Arra"
a handle #or accessing a !D arra- te4ture
sampler#uffer
image#uffer
a handle #or accessing a :u##er te4ture
sampler!)L,
image!)L,
a handle #or accessing a !D ulti9sa1le te4ture
sampler!)L,Arra"
image!)L,Arra"
a handle #or accessing a !D ulti9sa1le arra- te4ture
sampler'ueArra"
image'ueArra"
a handle #or accessing a cu:e a1 arra- te4ture
sampler1),hadow a handle #or accessing a 1D de1th te4ture with co1arison
sampler!),hadow a handle #or accessing a !D de1th te4ture with co1arison
sampler!)Kect,hadow a handle #or accessing a rectangular te4ture with co1arison
sampler1)Arra",hadow a handle #or accessing a 1D arra- de1th te4ture with co1arison
sampler!)Arra",hadow a handle #or accessing a !D arra- de1th te4ture with co1arison
sampler'ue,hadow a handle #or accessing a cu:e a1 de1th te4ture with co1arison
sampler'ueArra",hadow a handle #or accessing a cu:e a1 arra- de1th te4ture with
co1arison
,igned Integer .1a<ue 0-1es
T(pe 8eaning
isampler1)
iimage1)
a handle #or accessing an integer 1D te4ture
23
T(pe 8eaning
isampler!)
iimage!)
a handle #or accessing an integer !D te4ture
isampler3)
iimage3)
a handle #or accessing an integer 'D te4ture
isampler'ue
iimage'ue
a handle #or accessing an integer cu:e a11ed te4ture
isampler!)Kect
iimage!)Kect
a handle #or accessing an integer !D rectangular te4ture
isampler1)Arra"
iimage1)Arra"
a handle #or accessing an integer 1D arra- te4ture
isampler!)Arra"
iimage!)Arra"
a handle #or accessing an integer !D arra- te4ture
isampler#uffer
iimage#uffer
a handle #or accessing an integer :u##er te4ture
isampler!)L,
iimage!)L,
a handle #or accessing an integer !D ulti9sa1le te4ture
isampler!)L,Arra"
iimage!)L,Arra"
a handle #or accessing an integer !D ulti9sa1le arra- te4ture
isampler'ueArra"
iimage'ueArra"
a handle #or accessing an integer cu:e a1 arra- te4ture
7nsigned Integer .1a<ue 0-1es
T(pe 8eaning
atomic&uint a handle #or accessing an unsigned integer atoic counter
usampler1)
uimage1)
a handle #or accessing an unsigned integer 1D te4ture
usampler!)
uimage!)
a handle #or accessing an unsigned integer !D te4ture
usampler3)
uimage3)
a handle #or accessing an unsigned integer 'D te4ture
usampler'ue
uimage'ue
a handle #or accessing an unsigned integer cu:e a11ed te4ture
usampler!)Kect
uimage!)Kect
a handle #or accessing an unsigned integer rectangular te4ture
usampler1)Arra"
uimage1)Arra"
a handle #or accessing an unsigned integer 1D arra- te4ture
usampler!)Arra"
uimage!)Arra"
a handle #or accessing an unsigned integer !D arra- te4ture
24
T(pe 8eaning
usampler#uffer
uimage#uffer
a handle #or accessing an unsigned integer :u##er te4ture
usampler!)L,
uimage!)L,
a handle #or accessing an unsigned integer !D ulti9sa1le te4ture
usampler!)L,Arra"
uimage!)L,Arra"
a handle #or accessing an unsigned integer !D ulti9sa1le te4ture
arra-
usampler'ueArra"
uimage'ueArra"
a handle #or accessing an unsigned integer cu:e a1 arra- te4ture
In addition, a shader can aggregate these :asic t-1es using arra-s and structures to :uild ore co1le4
t-1es.
0here are no 1ointer t-1es.
!.1.1 oid
6unctions that do not return a value ust :e declared as void. 0here is no de#ault #unction return t-1e.
0he ke-word void cannot :e used in another declarations Be4ce1t #or e1t- #oral or actual 1araeter
listsC.
!.1.2 0ooleans
0o ake conditional e4ecution o# code easier to e41ress, the t-1e ool is su11orted. 0here is no
e41ectation that hardware directl- su11orts varia:les o# this t-1e. It is a genuine Boolean t-1e, holding
onl- one o# two values eaning either true or #alse. 0wo ke-words true and false can :e used as literal
Boolean constants. Booleans are declared and o1tionall- initiali=ed as in the #ollow e4a1le:
bool success; // declare success to be a 9oolean
bool done 3 false; // declare and initiali.e done
0he right side o# the assignent o1erator B B C ust :e an e41ression whose t-1e is ool.
E41ressions used #or conditional Du1s Bif1 for1 FD1 while1 do.whileC ust evaluate to the t-1e ool.
!.1.# Integers
,igned and unsigned integer varia:les are #ull- su11orted. In this docuent, the ter integer is eant to
generall- include :oth signed and unsigned integers. 7nsigned integers have e4actl- '! :its o# 1recision.
,igned integers use '! :its, including a sign :it, in twoJs co1leent #or. .1erations resulting in
over#low or under#low will not cause an- e4ce1tion, nor will the- saturate, rather the- will Ewra1F to -ield
the low9order '! :its o# the result.
Integers are declared and o1tionall- initiali=ed with integer e41ressions, as in the #ollowing e4a1le:
int i7 : 3 ;<; // default integer literal t/e is int
uint = 3 >u; // u establishes the t/e as uint
25
3iteral integer constants can :e e41ressed in decial B:ase 1$C, octal B:ase (C, or he4adecial B:ase 1+C
as #ollows.
integer-constant :
$ecimal-constant integer-su%%ixopt
octal-constant integer-su%%ixopt
'exa$ecimal-constant integer-su%%ixopt
integer-su%%ix: one o#
u U
$ecimal-constant :
non0ero-$igit
$ecimal-constant $igit
octal-constant :
2
octal-constant octal-$igit
'exa$ecimal-constant :
$4 'exa$ecimal-$igit
$Z 'exa$ecimal-$igit
'exa$ecimal-constant 'exa$ecimal-$igit
$igit :
2
non0ero-$igit
non0ero-$igit : one o#
1 ! 3 4 Z + [ \ 3
octal-$igit D one o#
2 1 ! 3 4 Z + [
'exa$ecimal-$igit D one o#
2 1 ! 3 4 Z + [ \ 3
a c d e f
A # ' ) O -
8o white s1ace is allowed :etween the digits o# an integer constant, including a#ter the leading 2 or a#ter
the leading 2x or 2X o# a constant, or :e#ore the su##i4 u or U. @hen tokeni=ing, the a4ial token
atching the a:ove will :e recogni=ed :e#ore a new token is started. @hen the su##i4 u or U is 1resent,
the literal has t-1e uint, otherwise the t-1e is int. A leading unar- inus sign B9C is inter1reted as an
arithetic unar- negation, not as 1art o# the constant. /ence, literals theselves are alwa-s e41ressed
with non9negative s-nta4, though the- could result in a negative value.
It is an error to 1rovide a literal integer whose agnitude is too large to store in a varia:le o# atching
signed or unsigned t-1ewhose :it 1attern cannot #it in '! :its. 0he :it 1attern o# the literal is alwa-s used
unodi#ied. ,o a signed literal whose :it 1attern includes a set sign :it creates a negative value. 6or
e4a1le,
26
int a 3 ?xffffffff; // >< bits7 a gets the value 20
int b 3 ?xffffffff@; // %((*(1 can't convert uint to int
uint c 3 ?xffffffff; // >< bits7 c gets the value ?x&&&&&&&&
uint d 3 ?xffffffff@; // >< bits7 d gets the value ?x&&&&&&&&
int e 3 20; // the literal is 07 then negation is erformed7
// and the resulting non2literal ><2bit signed
// bit attern of ?x&&&&&&&& is assigned7 giving e
// the value of 205
uint f 3 20u; // the literal is 0u7 then negation is erformed7
// and the resulting non2literal ><2bit unsigned
// bit attern of ?x&&&&&&&& is assigned7 giving f
// the value of ?x&&&&&&&&5
int g 3 >?????????; // a signed decimal literal ta=ing >< bits7
// setting the sign bit7 g gets 20<A;ABC<AB
int h 3 ?xD???????; // o=a/7 ><2bit signed hexadecimal
int i 3 E?????????; // %((*(1 needs more than >< bits
int : 3 ?x&&&&&&&&&; // %((*(1 needs more that >< bits
int = 3 ?xF???????; // = gets 2<0;C;F>B;F 33 ?xF???????
int l 3 <0;C;F>B;F; // l gets 2<0;C;F>B;F (the literal set the sign bit)
Des1ite all these e4a1les initiali=ing varia:les, literals are recogni=ed and given values and t-1es
inde1endentl- o# their conte4t.
!.1.! /loats
,ingle91recision and dou:le91recision #loating 1oint varia:les are availa:le #or use in a variet- o# scalar
calculations. 6loating91oint varia:les are de#ined as in the #ollowing e4a1le:
float a7 b 3 05E;
double c7 d 3 <5?"&;
As an in1ut value to one o# the 1rocessing units, a single91recision or dou:le91recision #loating91oint
varia:le is e41ected to atch the corres1onding IEEE )*% #loating91oint de#inition #or 1recision and
d-naic range. 6loating91oint varia:les within a shader are also encoded according to the IEEE )*%
s1eci#ication #or single91recision #loating91oint values Blogicall-, not necessaril- 1h-sicall-C. @hile
encodings are logicall- IEEE )*%, o1erations Baddition, ulti1lication, etc.C are not necessaril- 1er#ored
as re<uired :- IEEE )*%. ,ee section %.).1 ERange and 5recisionF #or ore details on 1recision and
usage o# 8a8s B8ot a 8u:erC and In#s B1ositive or negative in#initiesC.
27
6loating91oint constants are de#ined as #ollows.
%loating-constant :
%ractional-constant exponent-part
opt
%loating-su%%ixopt

$igit-se1uence exponent-part %loating-su%%ixopt
%ractional-constant :
$igit-se1uence . $igit-se1uence
$igit-se1uence .
. $igit-se1uence
exponent-part :
e sign
opt
$igit-se1uence
E sign
opt
$igit-se1uence
sign : one o#
4 ]
$igit-se1uence :
$igit
$igit-se1uence $igit
%loating-su%%ix: one o#
f - lf J-
A decial 1oint B . C is not needed i# the e41onent 1art is 1resent. 8o white s1ace a- a11ear an-where
within a #loating91oint constant, including :e#ore a su##i4. @hen tokeni=ing, the a4ial token atching
the a:ove will :e recogni=ed :e#ore a new token is started. @hen the su##i4 Xl#X or X36X is 1resent, the
literal has t-1e doule. .therwise, the literal has t-1e float. A leading unar- inus sign B.C is inter1reted
as a unar- o1erator and is not 1art o# the #loating91oint constant
!.1.& ectors
0he .1en23 ,hading 3anguage includes data t-1es #or generic !9, '9, and %9co1onent vectors o#
#loating91oint values, integers, or Booleans. 6loating91oint vector varia:les can :e used to store colors,
norals, 1ositions, te4ture coordinates, te4ture looku1 results and the like. Boolean vectors can :e used
#or co1onent9wise co1arisons o# nueric vectors. ,oe e4a1les o# vector declaration are:
vec< texcoord07 texcoord<;
vec> osition;
vec; m/(-9D;
ivec< texture"oo=u;
bvec> less;
Initiali=ation o# vectors can :e done with constructors, which are discussed shortl-.
!.1.' 8atrices
0he .1en23 ,hading 3anguage has :uilt9in t-1es #or !Y!, !Y', !Y%, 'Y!, 'Y', 'Y%, %Y!, %Y', and %Y%
atrices o# #loating91oint nu:ers. ;atri4 t-1es :eginning with XatX have single91recision co1onents
28
while atri4 t-1es :eginning with XdatX have dou:le91recision co1onents. 0he #irst nu:er in the
t-1e is the nu:er o# coluns, the second is the nu:er o# rows. I# there is onl- one nu:er, the atri4
is s<uare. E4a1le atri4 declarations:
mat< mat<,;
mat> otGatrix;
mat; view7 ro:ection;
mat;x; view; // an alternate wa/ of declaring a mat;
mat>x< m; // a matrix with > columns and < rows
dmat; highHrecisionG'H;
dmat<x; dm;
Initiali=ation o# atri4 values is done with constructors Bdescri:ed in section *.% E"onstructorsF C in
colun9aDor order.
!.1.% Opa2ue T(pes
0he o1a<ue t-1es declare varia:les that are e##ectivel- o1a<ue handles to other o:Dects. 0hese o:Dects are
accessed through :uilt9in #unctions, not through direct reading or writing o# the declared varia:le. 0he-
can onl- :e declared as #unction 1araeters or uniform.<uali#ied varia:les. E4ce1t #or arra- inde4ing,
structure e:er selection, and 1arentheses, o1a<ue varia:les are not allowed to :e o1erands in
e41ressions.
.1a<ue varia:les cannot :e treated as l9valuesI hence cannot :e used as out or inout #unction 1araeters,
nor can the- :e assigned into. /owever, the- can :e 1assed as in 1araeters with atching t-1e and
eor- <uali#iers. 0he- are initiali=ed onl- through the .1en23 A5II the- cannot :e declared with an
initiali=er in a shader.
Because a single o1a<ue t-1e declaration e##ectivel- declares two o:Dects, the o1a<ue handle itsel# and the
o:Dect it is a handle to, there is roo #or :oth a storage <uali#ier and a eor- <uali#ier. 0he storage
<uali#ier will <uali#- the o1a<ue handle, while the eor- <uali#ier will <uali#- the o:Dect it as a handle
to.
!.1.%.1 Samplers
,a1ler t-1es Be.g., sampler!)C are o1a<ue t-1es, declared and :ehaving as descri:ed a:ove #or o1a<ue
t-1es. 0he- do not use eor- <uali#iers. @hen aggregated into arra-s within a shader, sa1lers can
onl- :e inde4ed with a d-naicall- uni#or integral e41ression, otherwise results are unde#ined.
,a1ler varia:les are handles to one9, two9, and three9 diensional te4tures, cu:e a1s, de1th te4tures
BshadowingC, etc., as enuerated in the :asic t-1es ta:les. 0here are distinct sa1ler t-1es #or each
te4ture target, and #or each o# #loat, integer, and unsigned integer data t-1es. 0e4ture accesses are done
through :uilt9in te4ture #unctions Bdescri:ed in section (.& E0e4ture 6unctionsF F C and sa1lers are used
to s1eci#- which te4ture to access and how it is to :e #iltered.
!.1.%.2 Images
Iage t-1es are o1a<ue t-1es, declared and :ehaving as descri:ed a:ove #or o1a<ue t-1es. 0he- can :e
#urther <uali#ied with eor- <uali#iers. @hen aggregated into arra-s within a shader, iages can :e
29
inde4ed with general integer e41ressionscan onl- :e inde4ed with a d-naicall- uni#or integral
e41ression, otherwise results are unde#ined..
Iage varia:les are handles to one9, two9, or three9diensional iages corres1onding to all or a 1ortion
o# a single level o# a te4ture iage :ound to an iage unit. 0here are distinct iage t-1es #or each te4ture
target, and #or each o# #loat, integer, and unsigned integer data t-1es. Iage accesses should use an iage
t-1e that atches the target o# the te4ture whose level is :ound to the iage unit, or #or non9la-ered
:indings o# 'D or arra- iages should use the iage t-1e that atches the diensionalit- o# the la-er o#
the iage Bi.e., a la-er o# 'D, !DArra-, "u:e, or "u:eArra- should use image!), a la-er o# 1DArra-
should use image1), and a la-er o# !D;,Arra- should use image!)L,C. I# the iage target t-1e does
not atch the :ound iage in this anner, i# the data t-1e does not atch the :ound iage, or i# the
#orat la-out <uali#ier does not atch the iage unit #orat as descri:ed in ,ection '.&.!$ o# the
.1en23 ,1eci#ication, the results o# iage accesses are unde#ined :ut cannot include 1rogra
terination.
Iage varia:les are used in the iage load, store, and atoic #unctions descri:ed in ,ection (.11 XIage
6unctionsX to s1eci#- an iage to access.
!.1.%.# 1tomic Counters
Atoic counter t-1es Batomic&uintC are o1a<ue handles to counters, declared and :ehaving as descri:ed
a:ove #or o1a<ue t-1es. 0he varia:les the- declare s1eci#- which counter to access when using the :uilt9
in atoic counter #unctions as descri:ed in section (.1$ EAtoic "ounter 6unctionsF. 0he- are :ound to
:u##ers as descri:ed in section %.%.%.1 EAtoic "ounter 3a-out >uali#iersF. @hen aggregated into arra-s
within a shader, atoic counters can onl- :e inde4ed with a d-naicall- uni#or integral e41ression,
otherwise results are unde#ined.
!.1.$ Structures
7ser9de#ined t-1es can :e created :- aggregating other alread- de#ined t-1es into a structure using the
struct ke-word. 6or e4a1le,
struct light 4
float intensit/;
vec> osition;
8 light'ar;
In this e4a1le, lig't :ecoes the nae o# the new t-1e, and lig'tVar :ecoes a varia:le o# t-1e lig't.
0o declare varia:les o# the new t-1e, use its nae Bwithout the ke-word structC.
light light'ar<;
;ore #orall-, structures are declared as #ollows. /owever, the co1lete correct graar is as given in
section & E,hading 3anguage 2raarF .
struct-$e%inition :
1uali%ier
opt
struct name
opt
< mem#er-list = $eclarators
opt
2
mem#er-list :
mem#er-$eclaration2
mem#er-$eclaration mem#er-list2
3
mem#er-$eclaration :
#asic-t+pe $eclarators2
where name :ecoes the user9de#ined t-1e, and can :e used to declare varia:les to :e o# this new t-1e.
0he name shares the sae nae s1ace as other varia:les, t-1es, and #unctions. All 1reviousl- visi:le
varia:les, t-1es, constructors, or #unctions with that nae are hidden. 0he o1tional 1uali%ier onl- a11lies
to an- $eclarators, and is not 1art o# the t-1e :eing de#ined #or name.
,tructures ust have at least one e:er declaration. ;e:er declarators a- contain 1recision
<uali#iers, :ut a- not contain another <uali#iers. Bit #ields are not su11orted. ;e:er t-1es ust :e
alread- de#ined Bthere are no #orward re#erencesC. ;e:er declarations cannot contain initiali=ers.
;e:er declarators can contain arra-s. ,uch arra-s ust have a si=e s1eci#ied, and the si=e ust :e an
integral constant e41ression thatJs greater than =ero Bsee section %.'.' E"onstant E41ressionsFC. Each
level o# structure has its own nae s1ace #or naes given in e:er declaratorsI such naes need onl-
:e uni<ue within that nae s1ace.
Anon-ous structures are not su11orted. E:edded structure de#initions are not su11orted.
struct ) 4 float f; 8;
struct + 4
); // %rror1 anon/mous structures disallowed
struct 4 555 8; // %rror1 embedded structures disallowed
) s; // *=a/1 nested structures with name are allowed
8;
,tructures can :e initiali=ed at declaration tie using constructors, as discussed in section *.%.' E,tructure
"onstructorsF .
An- restrictions on the usage o# a t-1e or <uali#ier also a11l- to an- structure that contains a e:er o#
that t-1e or <uali#ier. 0his also a11lies to structure e:ers that are structures, recursivel-.
!.1." 1rra(s
Varia:les o# the sae t-1e can :e aggregated into arra-s :- declaring a nae #ollowed :- :rackets B : ; C
enclosing an o1tional si=e. @hen an arra- si=e is s1eci#ied in a declaration, it ust :e an integral constant
e41ression Bsee section %.'.' E"onstant E41ressionsF C greater than =ero. I# an arra- is inde4ed with an
e41ression that is not an integral constant e41ression, or i# an arra- is 1assed as an arguent to a #unction,
then its si=e ust :e declared :e#ore an- such use. It is legal to declare an arra- without a si=e and then
later re9declare the sae nae as an arra- o# the sae t-1e and s1eci#- a si=e. It is illegal to declare an
arra- with a si=e, and then later Bin the sae shaderC inde4 the sae arra- with an integral constant
e41ression greater than or e<ual to the declared si=e. It is also illegal to inde4 an arra- with a negative
constant e41ression. Arra-s declared as #oral 1araeters in a #unction declaration ust s1eci#- a si=e.
7nde#ined :ehavior results #ro inde4ing an arra- with a non9constant e41ression thatNs greater than or
e<ual to the arra-Ns si=e or less than $. .nl- one9diensional arra-s a- :e declared. All :asic t-1es and
structures can :e #ored into arra-s. ,oe e4a1les are:
31
float frequenciesI>J;
uniform vec; lightHositionI;J;
light lightsIJ;
const int num"ights 3 <;
light lightsInum"ightsJ;
An arra- t-1e can :e #ored :- s1eci#-ing a t-1e #ollowed :- s<uare :rackets B[ \C and including a si=e:
floatIEJ
0his t-1e can :e used an-where another t-1e can :e used, including as the return value #ro a #unction
floatIEJ foo() 4 8
as a constructor o# an arra-
floatIEJ(>5;7 ;5<7 E5?7 E5<7 050)
as an unnaed 1araeter
void foo(floatIEJ)
and as an alternate wa- o# declaring a varia:le or #unction 1araeter.
floatIEJ a;
It is an error to declare arra-s o# arra-s:
float aIEJI>J; // illegal
floatIEJ aI>J; // illegal
Arra-s can have initiali=ers #ored #ro arra- constructors:
float aIEJ 3 floatIEJ(>5;7 ;5<7 E5?7 E5<7 050);
float aIEJ 3 floatIJ(>5;7 ;5<7 E5?7 E5<7 050); // same thing
7nsi=ed arra-s can :e e41licitl- si=ed :- an initiali=er at declaration tie:
float aIEJ;
555
float bIJ 3 a; // b is exlicitl/ si.e E
float bIEJ 3 a; // means the same thing
float bIJ 3 floatIJ(07<7>7;7E); // also exlicitl/ si.es to E
/owever, i1licitl- si=ed arra-s cannot :e assigned to. 8ote, this is a rare case that initiali=ers and
assignents a11ear to have di##erent seantics.
Arra-s know the nu:er o# eleents the- contain. 0his can :e o:tained :- using the length ethod:
a5length(); // returns E for the above declarations
0his returns a t-1e int. 0he length ethod cannot :e called on an arra- that has not :een e41licitl- si=ed.
32
!.1.10 Implicit Conversions
In soe situations, an e41ression and its t-1e will :e i1licitl- converted to a di##erent t-1e. 0he
#ollowing ta:le shows all allowed i1licit conversions:
T(pe of e-pression Can be implicitl( converted to
int uint
int
uint
float
int
uint
float
doule
ivec! uvec!
ivec3 uvec3
ivec4 uvec4
ivec!
uvec!
vec!
ivec3
uvec3
vec3
ivec4
uvec4
vec4
ivec!
uvec!
vec!
dvec!
ivec3
uvec3
vec3
dvec3
ivec4
uvec4
vec4
dvec4
mat! dmat!
mat3 dmat3
mat4 dmat4
mat!x3 dmat!x3
mat!x4 dmat!x4
mat3x! dmat3x!
mat3x4 dmat3x4
mat4x! dmat4x!
mat4x3 dmat4x3
33
0here are no i1licit arra- or structure conversions. 6or e4a1le, an arra- o# int cannot :e i1licitl-
converted to an arra- o# float.
@hen an i1licit conversion is done, it is not a re9inter1retation o# the e41ressionJs :it 1attern, :ut a
conversion o# its value to an e<uivalent value in the new t-1e. 6or e4a1le, the integer value 9Z will :e
converted to the #loating91oint value 9Z.2. Integer values having ore :its o# 1recision than a #loating
1oint antissa will lose 1recision when converted to float.
@hen 1er#oring i1licit conversion #or :inar- o1erators, there a- :e ulti1le data t-1es to which the
two o1erands can :e converted. 6or e4a1le, when adding an int value to a uint value, :oth values can
:e i1licitl- converted to uint, float, and doule. In such cases, a #loating91oint t-1e is chosen i# either
o1erand has a #loating91oint t-1e. .therwise, an unsigned integer t-1e is chosen i# either o1erand has an
unsigned integer t-1e. .therwise, a signed integer t-1e is chosen. I# o1erands can :e i1licitl- converted
to ulti1le data t-1es deriving #ro the sae :ase data t-1e, the t-1e with the sallest co1onent si=e is
used.
0he conversions in the ta:le a:ove are done onl- as indicated :- other sections o# this s1eci#ication.
!.1.11 Initiali9ers
At declaration, an initial value #or an aggregate varia:le a- :e 1rovided, s1eci#ied as an e<uals BTC
#ollowed :- an initiali=er. 0he initiali=er is either an assignment-expression or a list o# initiali=ers
enclosed in curl- :races. 0he graar #or the initiali=er is:
initiali0er :
assignment-expression
< initiali0er-list =
< initiali0er-list , =
initiali0er-list :
initiali0er
initiali0er-list 1 initiali0er
0he assignment-expression is a noral e41ression e4ce1t that a coa B 1 C outside 1arentheses is
inter1reted as the end o# the initiali=er, not as the se<uence o1erator. As e41lained in ore detail :elow,
this allows creation o# nested initiali=ers: 0he aggregate and its initiali=er ust e4actl- atch in ters o#
nesting, nu:er o# co1onentsGeleentsGe:ers 1resent at each level, and t-1es o#
co1onentsGeleentsGe:ers.
An assignment-expression in an initiali=er ust :e either the sae t-1e as the o:Dect it initiali=es or :e a
t-1e that can :e converted to the o:DectJs t-1e according to section %.1.1$ XI1licit "onversionsX. ,ince
these include constructors, an aggregate can :e initiali=ed :- either a constructor or an initiali=er listI an
eleent in an initiali=er list can :e a constructor.
I# an initiali=er is a list o# initiali=ers enclosed in curl- :races, the varia:le :eing declared ust :e a
vector, a atri4, an arra-, or a structure.
int i 3 4 0 8; // illegal7 i is not an aggregate
34
A list o# initiali=ers enclosed in a atching set o# curl- :races is a11lied to one aggregate. 0his a- :e
the varia:le :eing declared or an aggregate contained in the varia:le :eing declared. Individual
initiali=ers #ro the initiali=er list are a11lied to the eleentsGe:ers o# the aggregate, in order.
I# the aggregate has a vector t-1e, initiali=ers #ro the list are a11lied to the co1onents o# the vector, in
order, starting with co1onent $. 0he nu:er o# initiali=ers ust atch the nu:er o# co1onents.
I# the aggregate has a atri4 t-1e, initiali=ers #ro the list ust :e vector initiali=ers and are a11lied to
the coluns o# the atri4, in order, starting with colun $. 0he nu:er o# initiali=ers ust atch the
nu:er o# coluns.
I# the aggregate has a structure t-1e, initiali=ers #ro the list are a11lied to the e:ers o# the structure,
in the order declared in the structure, starting with the #irst e:er. 0he nu:er o# initiali=ers ust
atch the nu:er o# e:ers.
A11l-ing these rules, the #ollowing atri4 declarations are e<uivalent:
mat<x< a 3 mat<( vec<( 05?7 ?5? )7 vec<( ?5?7 05? ) );
mat<x< b 3 4 vec<( 05?7 ?5? )7 vec<( ?5?7 05? ) 8;
mat<x< c 3 4 4 05?7 ?5? 87 4 ?5?7 05? 8 8;
All o# the #ollowing declarations are illegal.
float aI<J 3 4 >5;7 ;5<7 E5? 8; // illegal
vec< b 3 4 05?7 <5?7 >5? 8; // illegal
mat>x> c 3 4 vec>(?5?)7 vec>(05?)7 vec>(<5?)7 vec>(>5?) 8; // illegal
mat<x< d 3 4 05?7 ?5?7 ?5?7 05? 8; // illegal7 can't flatten nesting
struct 4
float a;
int b;
8 e 3 4 05<7 <7 > 8; // illegal
In all cases, the innerost initiali=er Bi.e., not a list o# initiali=ers enclosed in curl- :racesC a11lied to an
o:Dect ust have the sae t-1e as the o:Dect :eing initiali=ed or :e a t-1e that can :e converted to the
o:DectJs t-1e according to section %.1.1$ XI1licit "onversionsX. In the latter case, an i1licit conversion
will :e done on the initiali=er :e#ore the assignent is done.
struct 4
float a;
int b;
8 e 3 4 05<7 < 8; // legal7 all t/es match
35
struct 4
float a;
int b;
8 e 3 4 07 > 8; // legal7 first initiali.er is converted
All o# the #ollowing declarations are illegal.
int a 3 true; // illegal
vec; bI<J 3 4 vec;(?5?)7 05? 8; // illegal
mat;x< c 3 4 vec>(?5?)7 vec>(05?) 8; // illegal
struct )0 4
vec; a;
vec; b;
8;
struct 4
float s;
float t;
8 dIJ 3 4 )0(vec;(?5?)7 vec;(050)) 8; // illegal
I# an initiali=er Bo# either #orC is 1rovided #or an unsi=ed arra-, the si=e o# the arra- is deterined :- the
nu:er o# to19level Bnon9nestedC initiali=ers within the initiali=er. All o# the #ollowing declarations create
arra-s e41licitl- si=ed with #ive eleents:
float aIJ 3 floatIJ(>5;7 ;5<7 E5?7 E5<7 050);
float bIJ 3 4 >5;7 ;5<7 E5?7 E5<7 050 8;
float cIJ 3 a; // c is exlicitl/ si.e E
float dIEJ 3 b; // means the same thing
It is an error to have too #ew or too an- initiali=ers in an initiali=er list #or the aggregate :eing
initiali=ed. 0hat is, all eleents o# an arra-, all e:ers o# a structure, all coluns o# a atri4, and all
co1onents o# a vector ust have e4actl- one initiali=er e41ression 1resent, with no unconsued
initiali=ers.
!.2 Scoping
0he sco1e o# a varia:le is deterined :- where it is declared. I# it is declared outside all #unction
de#initions, it has glo:al sco1e, which starts #ro where it is declared and 1ersists to the end o# the shader
it is declared in. I# it is declared in a while test or a for stateent, then it is sco1ed to the end o# the
#ollowing su:9stateent. I# it is declared in an if or else stateent, it is sco1ed to the end o# that
stateent. B,ee section +.! E,electionF and section +.' EIterationF #or the location o# stateents and su:9
stateents.C .therwise, i# it is declared as a stateent within a co1ound stateent, it is sco1ed to the
end o# that co1ound stateent. I# it is declared as a 1araeter in a #unction de#inition, it is sco1ed until
the end o# that #unction de#inition. A #unction :od- has a sco1e nested inside the #unctionNs de#inition.
0he if stateentNs e41ression does not allow new varia:les to :e declared, hence does not #or a new
sco1e.
36
@ithin a declaration, the sco1e o# a nae starts iediatel- a#ter the initiali=er i# 1resent or iediatel-
a#ter the nae :eing declared i# not. ,everal e4a1les:
int x 3 0;
4
int x 3 <7 / 3 x; // / is initiali.ed to <
8
struct )
4
int x;
8;
4
) ) 3 )(?); // ')' is onl/ visible as a struct and constructor
); // ')' is now visible as a variable
8
int x 3 x; // %rror if x has not been reviousl/ defined5
All varia:le naes, structure t-1e naes, and #unction naes in a given sco1e share the sae nae s1ace.
6unction naes can :e redeclared in the sae sco1e, with the sae or di##erent 1araeters, without error.
An i1licitl- si=ed arra- can :e re9declared in the sae sco1e as an arra- o# the sae :ase t-1e.
.therwise, within one co1ilation unit, a declared nae cannot :e redeclared in the sae sco1eI doing so
results in a redeclaration error. I# a nested sco1e redeclares a nae used in an outer sco1e, it hides all
e4isting uses o# that nae. 0here is no wa- to access the hidden nae or ake it unhidden, without
e4iting the sco1e that hid it.
0he :uilt9in #unctions are sco1ed in a sco1e outside the glo:al sco1e users declare glo:al varia:les in.
0hat is, a shaderJs glo:al sco1e, availa:le #or user9de#ined #unctions and glo:al varia:les, is nested inside
the sco1e containing the :uilt9in #unctions. @hen a #unction nae is redeclared in a nested sco1e, it hides
all #unctions declared with that nae in the outer sco1e. 6unction declarations B1rotot-1esC cannot occur
inside o# #unctionsI the- ust :e at glo:al sco1e, or #or the :uilt9in #unctions, outside the glo:al sco1e.
,hared glo:als are glo:al varia:les declared with the sae nae in inde1endentl- co1iled units
BshadersC within the sae language Be.g., verte4C that are linked together when aking a single 1rogra.
B2lo:als #oring the inter#ace :etween two di##erent shader languages are discussed in other sections.C
,hared glo:als share the sae nae s1ace, and ust :e declared with the sae t-1e. 0he- will share the
sae storage. ,hared glo:al arra-s ust have the sae :ase t-1e and the sae e41licit si=e. An arra-
i1licitl- si=ed in one shader can :e e41licitl- si=ed :- another shader. I# no shader has an e41licit si=e
#or the arra-, the largest i1licit si=e is used. ,calars ust have e4actl- the sae t-1e nae and t-1e
de#inition. ,tructures ust have the sae nae, se<uence o# t-1e naes, and t-1e de#initions, and
e:er naes to :e considered the sae t-1e. 0his rule a11lies recursivel- #or nested or e:edded
t-1es. I# a shared glo:al has ulti1le initiali=ers, the initiali=ers ust all :e constant e41ressions, and
the- ust all have the sae value. .therwise, a link error will result. BA shared glo:al having onl- one
initiali=er does not re<uire that initiali=er to :e a constant e41ression.C
37
!.# Storage :ualifiers
Varia:le declarations a- have at ost one storage <uali#ier s1eci#ied in #ront o# the t-1e. 0hese are
suari=ed as
Storage :ualifier 8eaning
R none: de#ault S local readGwrite eor-, or an in1ut 1araeter to a #unction
const a varia:le whose value cannot :e changed
in linkage into a shader #ro a 1revious stage, varia:le is co1ied in
out linkage out o# a shader to a su:se<uent stage, varia:le is co1ied out
attriute co1ati:ilit- 1ro#ile onl- and verte4 language onl-I sae as in when in a
verte4 shader
uniform value does not change across the 1riitive :eing 1rocessed, uni#ors
#or the linkage :etween a shader, .1en23, and the a11lication
var"ing co1ati:ilit- 1ro#ile onl- and verte4 and #ragent languages onl-I sae
as out when in a verte4 shader and sae as in when in a #ragent shader
,oe in1ut and out1ut <uali#ied varia:les can :e <uali#ied with at ost one additional au4iliar- storage
<uali#ier:
1u-iliar( Storage
:ualifier
8eaning
centroid centroid9:ased inter1olation
sample 1er9sa1le inter1olation
patch 1er9tessellation91atch attri:utes
8ot all co:inations o# <uali#ication are allowed. @hich varia:le t-1es can have which <uali#iers are
s1eci#icall- de#ined in u1coing sections.
38
3ocal varia:les can onl- use the const storage <uali#ier Bor use no storage <uali#ierC.
6unction 1araeters can use const, in, and out <uali#iers, :ut as parameter 1uali%iers. 5araeter
<uali#iers are discussed in section +.1.1 E6unction "alling "onventionsF.
6unction return t-1es and structure e:ers do not use storage <uali#iers.
Initiali=ers in glo:al declarations a- onl- :e used in declarations o# glo:al varia:les with no storage
<uali#ier, with a const <uali#ier or with a uniform <uali#ier. 2lo:al varia:les without storage <uali#iers
that are not initiali=ed in their declaration or :- the a11lication will not :e initiali=ed :- .1en23, :ut
rather will enter main34 with unde#ined values.
@hen co1aring an out1ut #ro one shader stage to an in1ut o# a su:se<uent shader stage, the in1ut and
out1ut donJt atch i# their au4iliar- <uali#iers Bor lack thereo#C are not the sae.
!.#.1 ,efault Storage :ualifier
I# no <uali#ier is 1resent on a glo:al varia:le, then the varia:le has no linkage to the a11lication or shaders
running on other 1i1eline stages. 6or either glo:al or local un<uali#ied varia:les, the declaration will
a11ear to allocate eor- associated with the 1rocessor it targets. 0his varia:le will 1rovide readGwrite
access to this allocated eor-.
!.#.2 Constant :ualifier
8aed co1ile9tie constants or read9onl- varia:les can :e declared using the const <uali#ier. 0he const
<uali#ier can :e used with an- o# the non9void trans1arent :asic data t-1es, as well as with structures and
arra-s o# these. It is an error to write to a const varia:le outside o# its declaration, so the- ust :e
initiali=ed when declared. 6or e4a1le,
const vec> .Dxis 3 vec> (?5?7 ?5?7 05?);
const float ceiling 3 a K b; // a and b not necessaril/ constants
,tructure e:ers a- not :e <uali#ied with const. ,tructure varia:les can :e declared as const, and
initiali=ed with a structure constructor or initiali=er.
Initiali=ers #or const declarations at glo:al sco1e ust :e constant e41ressions, as de#ined in section %.'.'
E"onstant E41ressions.F
!.#.# Constant *-pressions
A constant expression is one o#
a literal value Be.g., Z or trueC
a varia:le declared with the const <uali#ier and an initiali=er, where the initiali=er is a constant
e41ression
an e41ression #ored :- an o1erator on o1erands that are all constant e41ressions, including getting an
eleent o# a constant arra-, or a e:er o# a constant structure, or co1onents o# a constant vector.
39
/owever, the lowest 1recedence o1erators o# the se<uence o1erator B 1 C and the assignent o1erators
B B, 4B, ...% are not included in the o1erators that can create a constant e41ression.
valid use o# the lengthBC ethod on a si=ed o:Dect, whether or not the o:Dect itsel# is constant
a constructor whose arguents are all constant e41ressions
a :uilt9in #unction call whose arguents are all constant e41ressions, with the e4ce1tion o# the te4ture
looku1 #unctions and the noise #unctions. 0he :uilt9in #unctions d-dx, d-d", and fwidth ust return
$ when evaluated inside an initiali=er with an arguent that is a constant e41ression.
6unction calls to user9de#ined #unctions Bnon9:uilt9in #unctionsC cannot :e used to #or constant
e41ressions.
An integral constant expression is a constant e41ression that evaluates to a scalar signed or unsigned
integer.
"onstant e41ressions will :e evaluated in an invariant wa- so as to create the sae value in ulti1le
shaders when the sae constant e41ressions a11ear in those shaders. ,ee section %.(.1 E0he Invariant
>uali#ierF #or ore details on how to create invariant e41ressions.
!.#.! Input ariables
,hader in1ut varia:les are declared with the storage <uali#ier in. 0he- #or the in1ut inter#ace :etween
1revious stages o# the .1en23 1i1eline and the declaring shader. In1ut varia:les ust :e declared at
glo:al sco1e. Values #ro the 1revious 1i1eline stage are co1ied into in1ut varia:les at the :eginning o#
shader e4ecution. Varia:les declared as in1uts cannot :e written to during shader e4ecution.
.nl- the in1ut varia:les that are staticall- read need to :e written :- the 1revious stageI it is allowed to
have su1er#luous declarations o# in1ut varia:les. 0his is shown in the #ollowing ta:le.
0reatent o# ;isatched In1ut
Varia:les
"onsuing ,hader Bin1ut varia:lesC
8o Declaration Declared :ut no
,tatic 7se
Declared and
,tatic 7se
2enerating
,hader
Bout1ut
varia:lesC
8o Declaration Allowed Allowed Error
Declared :ut no
,tatic 7se
Allowed Allowed
Allowed
Bvalues are unde#inedC
Declared and
,tatic 7se
Allowed Allowed
Allowed
Bvalues are 1otentiall-
unde#inedC
Errors are :ased on static use onl-. "o1ilation a- generate a warning, :ut not an error, #or an-
d-naic use the co1iler can deduce that ight cause consu1tion o# unde#ined values.
,ee section ) EBuilt9in Varia:lesF #or a list o# the :uilt9in in1ut naes.
Verte4 shader in1ut varia:les Bor attri:utesC receive 1er9verte4 data. 0he- are declared in a verte4 shader
with the in <uali#ier. It is an error to use an- au4iliar- or inter1olation <uali#iers on a verte4 shader in1ut.
0he values co1ied in are esta:lished :- the .1en23 A5I or through the use o# the la-out identi#ier
4
location. Verte4 shader in1uts can :e single9 or dou:le91recision #loating91oint scalars, vectors, and
atrices, or signed9 and unsigned9integer scalars and vectors. Verte4 shader in1uts can also #or arra-s
o# these t-1es, :ut not structures.
E4a1le declarations in a verte4 shader:
in vec; osition;
in vec> normal;
in vec< texLoordI;J;
It is e41ected that gra1hics hardware will have a sall nu:er o# #i4ed vector locations #or 1assing verte4
in1uts. 0here#ore, the .1en23 ,hading language de#ines each non9atri4 in1ut varia:le as taking u1 one
such vector location. 0here is an i1leentation de1endent liit on the nu:er o# locations that can :e
used, and i# this is e4ceeded it will cause a link error. BDeclared in1ut varia:les that are not staticall- used
do not count against this liit.C A scalar in1ut counts the sae aount against this liit as a vec4, so
a11lications a- want to consider 1acking grou1s o# #our unrelated #loat in1uts together into a vector to
:etter utili=e the ca1a:ilities o# the underl-ing hardware. A atri4 in1ut will use u1 ulti1le locations.
0he nu:er o# locations used will e<ual the nu:er o# coluns in the atri4.
0essellation control, evaluation, and geoetr- shader in1ut varia:les get the 1er9verte4 values written out
:- out1ut varia:les o# the sae naes in the 1revious active shader stage. 6or these in1uts, centroid and
inter1olation <uali#iers are allowed, :ut have no e##ect. ,ince tessellation control, tessellation evaluation,
and geoetr- shaders o1erate on a set o# vertices, each in1ut varia:le Bor in1ut :lock, see inter#ace :locks
:elowC needs to :e declared as an arra-. 6or e4a1le,
in float fooIJ; // geometr/ shader inut for vertex out float foo
Each eleent o# such an arra- corres1onds to one verte4 o# the 1riitive :eing 1rocessed. Each arra- can
o1tionall- have a si=e declared. 0he arra- si=e will :e set :-, Bor i# 1rovided ust :e consistent withC the
in1ut la"out declarationBsC esta:lishing the t-1e o# in1ut 1riitive, as descri:ed later in section %.%.1
EIn1ut 3a-out >uali#iersF.
,oe in1uts and out1uts are arra+e$, eaning that #or an inter#ace :etween two shader stages either the
in1ut or out1ut declaration re<uires an e4tra level o# arra- inde4ing #or the declarations to atch. 6or
e4a1le, with the inter#ace :etween a verte4 shader and a geoetr- shader, verte4 shader out1ut varia:les
and geoetr- shader in1ut varia:les o# the sae nae ust atch in t-1e and <uali#ication, e4ce1t that
the verte4 shader nae cannot :e declared as an arra- while the geoetr- shader nae ust :e declared
as an arra-, to allow #or verte4 inde4ing. It is a link error i# a non9arra-ed in1ut is not declared with the
sae t-1e, <uali#ication, and arra- diensionalit- as the atching out1ut. It is an error i# an arra-ed in1ut
is not declared as an arra- o# the sae t-1e and <uali#ication as the corres1onding Bnon9arra-C out1ut.
,-etricall-, it is an error i# an arra-ed out1ut is not declared as an arra- o# the sae t-1e and
<uali#ication as the corres1onding Bnon9arra-C in1ut.
I# the out1ut corres1onding to an arra-ed in1ut is itsel# an arra-, it ust a11ear in an out1ut :lock Bsee
inter#ace :locks :elowC in the out1utting shader and in an in1ut :lock in the in1utting shader with a :lock
instance nae declared as an arra-. 0his is re<uired :ecause two9diensional arra-s are not su11orted.
Additionall-, tessellation evaluation shaders su11ort 1er91atch in1ut varia:les declared with the patch and
in <uali#iers. 5er91atch in1ut varia:les are #illed with the values o# 1er91atch out1ut varia:les written :-
the tessellation control shader. 5er91atch in1uts a- :e declared as one9diensional arra-s, :ut are not
inde4ed :- verte4 nu:er. A11l-ing the patch <uali#ier to in1uts can onl- :e done in tessellation
41
evaluation shaders. As with other in1ut varia:les, 1er91atch in1uts ust :e declared using the sae t-1e
and <uali#ication as 1er91atch out1uts #ro the 1revious Btessellation controlC shader stage.
6ragent shader in1uts get 1er9#ragent values, t-1icall- inter1olated #ro a 1revious stageJs out1uts.
0he- are declared in #ragent shaders with the in storage <uali#ier. 0he au4iliar- storage <uali#iers
centroid and sample can also :e a11lied, as well as the inter1olation <uali#iers flat, noperspective, and
smooth. It is an error to use patch in a #ragent shader. 6ragent in1uts can onl- :e signed and
unsigned integers and integer vectors, #loating 1oint scalars, #loating91oint vectors, atrices, or arra-s or
structures o# these. 6ragent shader in1uts that are signed or unsigned integers, integer vectors, or an-
dou:le91recision #loating91oint t-1e ust :e <uali#ied with the inter1olation <uali#ier flat.
6ragent in1uts are declared as in the #ollowing e4a1les:
in vec> normal;
centroid in vec< +exLoord;
invariant centroid in vec; Lolor;
noersective in float temerature;
flat in vec> m/Lolor;
noersective centroid in vec< m/+exLoord;
0he #ragent shader in1uts #or an inter#ace with the last active shader in the verte4 1rocessing 1i1eline.
6or this inter#ace, the last active shader stage out1ut varia:les and #ragent shader in1ut varia:les o# the
sae nae ust atch in t-1e and <uali#ication Bother than out atching to inC.
@hen an inter#ace :etween shader stages is #ored using shaders #ro two se1arate 1rogra o:Dects, it is
not 1ossi:le to detect isatches :etween in1uts and out1uts when the 1rogras are linked. @hen there
are isatches :etween in1uts and out1uts on such inter#aces, the values 1assed across the inter#ace will
:e 1artiall- or co1letel- unde#ined. ,haders can ensure atches across such inter#aces either :- using
in1ut and out1ut la-out <uali#iers Bsections %.%.1 EIn1ut 3a-out >uali#iersF and %.%.! E.ut1ut 3a-out
>uali#iersFC or :- using identical in1ut and out1ut declarations o# :locks or varia:les. "o1lete rules #or
inter#ace atching :etween 1rogras are #ound in the X,hader Inter#ace ;atchingX 1ortion o# section
!.1%.55. o# the .1en23 2ra1hics ,-ste ,1eci#ication.
!.#.& 5niform
0he uniform <uali#ier is used to declare glo:al varia:les whose values are the sae across the entire
1riitive :eing 1rocessed. All uniform varia:les are read9onl- and are initiali=ed e4ternall- either at link
tie or through the A5I. 0he link tie initial value is either the value o# the varia:leJs initiali=er, i#
1resent, or $ i# no initiali=er is 1resent. .1a<ue t-1es cannot have initiali=ers.
E4a1le declarations are:
uniform vec; lightHosition;
uniform vec> color 3 vec>(?5C7 ?5C7 ?5<); // value assigned at lin= time
0he uniform <uali#ier can :e used with an- o# the :asic data t-1es, or when declaring a varia:le whose
t-1e is a structure, or an arra- o# an- o# these.
0here is an i1leentation de1endent liit on the aount o# storage #or uni#ors that can :e used #or
each t-1e o# shader and i# this is e4ceeded it will cause a co1ile9tie or link9tie error. 7ni#or
varia:les that are declared :ut not used do not count against this liit. 0he nu:er o# user9de#ined
42
uni#or varia:les and the nu:er o# :uilt9in uni#or varia:les that are used within a shader are added
together to deterine whether availa:le uni#or storage has :een e4ceeded.
I# ulti1le shaders are linked together, then the- will share a single glo:al uni#or nae s1ace, including
within a language as well as across languages. /ence, the t-1es and initiali=ers o# uni#or varia:les with
the sae nae ust atch across all shaders that are linked into a single 1rogra.
It is legal #or soe shaders to 1rovide an initiali=er #or a 1articular uni#or varia:le, while another shader
does not, :ut all 1rovided initiali=ers ust :e e<ual.
!.#.' Output ariables
,hader out1ut varia:les are declared with a storage <uali#ier using the ke-word out. 0he- #or the out1ut
inter#ace :etween the declaring shader and the su:se<uent stages o# the .1en23 1i1eline. .ut1ut
varia:les ust :e declared at glo:al sco1e. During shader e4ecution the- will :ehave as noral
un<uali#ied glo:al varia:les. 0heir values are co1ied out to the su:se<uent 1i1eline stage on shader e4it.
.nl- out1ut varia:les that are read :- the su:se<uent 1i1eline stage need to :e writtenI it is allowed to
have su1er#luous declarations o# out1ut varia:les.
0here is not an inout storage <uali#ier at glo:al sco1e #or declaring a single varia:le nae as :oth in1ut
and out1ut to a shader. A varia:le also cannot :e declared with :oth the in and the out <uali#iers. .ut1ut
varia:les ust :e declared with di##erent naes than in1ut varia:les. /owever, nesting an in1ut or out1ut
inside an inter#ace :lock with an instance nae allows the sae naes with one re#erenced through a
:lock instance nae.
Verte4, tessellation evaluation, and geoetr- out1ut varia:les out1ut 1er9verte4 data and are declared
using the out storage <uali#ier. A11l-ing patch to an out1ut can onl- :e done in a tessellation control
shader. .ut1ut varia:les can onl- :e #loating91oint scalars, #loating91oint vectors, atrices, signed or
unsigned integers or integer vectors, or arra-s or structures o# an- these.
Individual verte4, tessellation evaluation, and geoetr- out1uts are declared as in the #ollowing e4a1les:
out vec> normal;
centroid out vec< +exLoord;
invariant centroid out vec; Lolor;
noersective out float temerature;
flat out vec> m/Lolor;
noersective centroid out vec< m/+exLoord;
samle out vec; er)amleLolor;
0hese can also a11ear in inter#ace :locks, as descri:ed in section %.'.( EInter#ace BlocksF. Inter#ace
:locks allow si1ler addition o# arra-s to the inter#ace #ro verte4 to geoetr- shader. 0he- also allow a
#ragent shader to have the sae in1ut inter#ace as a geoetr- shader #or a given verte4 shader.
0essellation control shader out1ut varia:les are a- :e used to out1ut 1er9verte4 and 1er91atch data. 5er9
verte4 out1ut varia:les are arra-ed Bsee arra+e$ under %.'.% In1utsC and declared using the out <uali#ier
without the patch <uali#ier. 5er91atch out1ut varia:les are declared using the patch and out <uali#iers.
5er9verte4 and 1er91atch out1ut varia:les can onl- :e #loating91oint scalars, #loating91oint vectors,
atrices, signed or unsigned integers or integer vectors, or arra-s or structures o# an- these. ,ince
tessellation control shaders 1roduce an arra-ed 1riitive co1rising ulti1le vertices, each 1er9verte4
43
out1ut varia:le Bor out1ut :lock, see inter#ace :locks :elowC needs to :e declared as an arra-. 6or
e4a1le,
out float fooIJ; // feeds next stage inut in float fooIJ
Each eleent o# such an arra- corres1onds to one verte4 o# the 1riitive :eing 1roduced. Each arra- can
o1tionall- have a si=e declared. 0he arra- si=e will :e set :- Bor i# 1rovided ust :e consistent withC the
out1ut la-out declarationBsC esta:lishing the nu:er o# vertices in the out1ut 1atch, as descri:ed later in
section %.%.!.1 E0essellation "ontrol .ut1utsF.
As descri:ed under the section %.'.% EIn1ut Varia:lesF a:ove, i# a 1er9verte4 out1ut o# the tessellation
control shader is itsel# an arra- with ulti1le values 1er verte4, it ust a11ear in an out1ut :lock Bsee
inter#ace :locks :elowC in the tessellation control shader with a :lock instance nae declared as an arra-.
Each tessellation control shader invocation has a corres1onding out1ut 1atch verte4, and a- assign
values to 1er9verte4 out1uts onl- i# the- :elong to that corres1onding verte4. I# a 1er9verte4 out1ut
varia:le is used as an l9value, it is an error i# the e41ression indicating the verte4 inde4 is not the identi#ier
gl_,nvocation,D.
0he order o# e4ecution o# a tessellation control shader invocation relative to the other invocations #or the
sae in1ut 1atch is unde#ined unless the :uilt9in #unction arrierBC is used. 0his 1rovides soe control
over relative e4ecution order. @hen a shader invocation calls arrierBC, its e4ecution 1auses until all
other invocations have reached the sae 1oint o# e4ecution. .ut1ut varia:le assignents 1er#ored :-
an- invocation e4ecuted 1rior to calling arrierBC will :e visi:le to another invocation a#ter the call to
arrierBC returns.
Because tessellation control shader invocations e4ecute in unde#ined order :etween :arriers, the values o#
1er9verte4 or 1er91atch out1ut varia:les will soeties :e unde#ined. "onsider the :eginning and end o#
shader e4ecution and each call to arrierBC as s-nchroni=ation 1oints. 0he value o# an out1ut varia:le
will :e unde#ined in an- o# the three #ollowing cases:
1. At the :eginning o# e4ecution.
!. At each s-nchroni=ation 1oint, unless
the value was well9de#ined a#ter the 1revious s-nchroni=ation 1oint and was not written :- an-
invocation since, or
the value was written :- e4actl- one shader invocation since the 1revious s-nchroni=ation
1oint, or
the value was written :- ulti1le shader invocations since the 1revious s-nchroni=ation 1oint,
and the last write 1er#ored :- all such invocations wrote the sae value.
'. @hen read :- a shader invocation, i#
the value was unde#ined at the 1revious s-nchroni=ation 1oint and has not :een writen :- the
sae shader invocation since, or
the out1ut varia:le is written to :- another shader invocation :etween the 1revious and ne4t
s-nchroni=ation 1oints, even i# that assignent occurs in code #ollowing the read.
6ragent out1uts out1ut 1er9#ragent data and are declared using the out storage <uali#ier. It is an error
to use au4iliar- storage <uali#iers or inter1olation <uali#iers on an out1ut in a #ragent shader. 6ragent
out1uts can onl- :e float, #loating91oint vectors, signed or unsigned integers or integer vectors, or arra-s
44
o# an- these. ;atrices and structures cannot :e out1ut. 6ragent out1uts are declared as in the #ollowing
e4a1les:
out vec; &ragmentLolor;
out uint "uminosit/;
!.#.% Interface 0loc3s
In1ut, out1ut, and uni#or varia:le declarations can :e grou1ed into naed inter#ace :locks to 1rovide
coarser granularit- :acking than is achieva:le with individual declarations. 0he- can have an o1tional
instance nae, used in the shader to re#erence their e:ers. An out1ut :lock o# one 1rograa:le
stage is :acked :- a corres1onding in1ut :lock in the su:se<uent 1rograa:le stage. A uni#or :lock is
:acked :- the a11lication with a :u##er o:Dect. It is illegal to have an in1ut :lock in a verte4 shader or an
out1ut :lock in a #ragent shaderI these uses are reserved #or #uture use.
An inter#ace :lock is started :- an in, out, or uniform ke-word, #ollowed :- a :lock nae, #ollowed :-
an o1en curl- :race B < C as #ollows:
inter%ace-#loc. :
la+out-1uali%ieropt inter%ace-1uali%ier #loc.-name < mem#er-list = instance-nameopt E
inter%ace-1uali%ier :
in
out
uniform
mem#er-list :
mem#er-$eclaration
mem#er-$eclaration mem#er-list
mem#er-$eclaration :
la+out-1uali%ieropt 1uali%iersopt t+pe $eclarators E
instance-name :
i$enti%ier
i$enti%ier 5 6
i$enti%ier 5 integral-constant-expression 6
Each o# the a:ove eleents is discussed :elow, with the e4ce1tion o# la-out <uali#iers Bla+out-1uali%ier4,
which are de#ined in the ne4t section.
6irst, an e4a1le,
uniform +ransform 4
mat; Godel'iewGatrix;
mat; Godel'iewHro:ectionGatrix;
uniform mat> $ormalGatrix; // allowed restatement of qualifier
float ,eformation;
8;
0he a:ove esta:lishes a uni#or :lock naed E0rans#orF with #our uni#ors grou1ed inside it.
45
0-1es and declarators are the sae as #or other in1ut, out1ut, and uni#or varia:le declarations outside
:locks, with these e4ce1tions:
initiali=ers are not allowed
o1a<ue t-1es are not allowed
structure de#initions cannot :e nested inside a :lock
.therwise, :uilt9in t-1es, 1reviousl- declared structures, and arra-s o# these are allowed as the t-1e o# a
declarator in the sae anner the- are allowed outside a :lock.
I# no o1tional <uali#ier is used in a e:er9declaration, the <uali#ication o# the varia:le is Dust in, out, or
uniform as deterined :- inter%ace-1uali%ier. I# o1tional <uali#iers are used, the- can include
inter1olation <uali#iers, au4iliar- storage <uali#iers, and storage <uali#iers and the- ust declare an in1ut,
out1ut, or uni#or varia:le consistent with the inter#ace <uali#ier o# the :lock: In1ut varia:les, out1ut
varia:les, and uni#or varia:les can onl- :e in in :locks, out :locks, and uniform :locks, res1ectivel-.
Re1eating the in, out, or uniform inter#ace <uali#ier #or a e:erJs storage <uali#ier is o1tional. 6or
e4a1le,
in Gaterial 4
smooth in vec; Lolor0; // legal7 inut inside in bloc=
smooth vec; Lolor<; // legal7 'in' inherited from 'in Gaterial'
vec< +exLoord; // legal7 +exLoord is an inut
uniform float Dtten; // illegal7 mismatched storage qualifier
8;
6or this section, de#ine an inter%ace to :e one o# these
All the uni#ors o# a 1rogra. 0his s1ans all co1ilation units linked together within one 1rogra.
0he :oundar- :etween adDacent 1rograa:le 1i1eline stages: 0his s1ans all the out1uts in all
co1ilation units o# the #irst stage and all the in1uts in all co1ilation units o# the second stage.
0he :lock nae B#loc.-nameC is used to atch inter#aces: an out1ut :lock o# one 1i1eline stage will :e
atched to an in1ut :lock with the sae nae in the su:se<uent 1i1eline stage. 6or uni#or :locks, the
a11lication uses the :lock nae to identi#- the :lock. Block naes have no other use within a shader
:e-ond inter#ace atchingI it is an error to use a :lock nae at glo:al sco1e #or an-thing other than as a
:lock nae Be.g., use o# a :lock nae #or a glo:al varia:le nae or #unction nae is currentl- reservedC.
;atched :lock naes within an inter#ace Bas de#ined a:oveC ust atch in ters o# having the sae
nu:er o# declarations with the sae se<uence o# t-1es and the sae se<uence o# e:er naes, as well
as having the sae e:er9wise la-out <uali#ication Bsee ne4t sectionC. 6urtherore, i# a atching :lock
is declared as an arra-, then the arra- si=es ust also atch Bor #ollow arra- atching rules #or the
inter#ace :etween a verte4 and a geoetr- shaderC. An- isatch will generate a link error. A :lock
nae is allowed to have di##erent de#initions in di##erent inter#aces within the sae shader, allowing, #or
e4a1le, an in1ut :lock and out1ut :lock to have the sae nae.
46
I# an instance nae Binstance-nameC is not used, the naes declared inside the :lock are sco1ed at the
glo:al level and accessed as i# the- were declared outside the :lock. I# an instance nae Binstance-nameC
is used, then it 1uts all the e:ers inside a sco1e within its own nae s1ace, accessed with the #ield
selector B . C o1erator Banalogousl- to structuresC. 6or e4a1le,
in "ight 4
vec; "ightHos;
vec> "ightLolor;
8;
in Lolored+exture 4
vec; Lolor;
vec< +exLoord;
8 Gaterial; // instance name
vec> Lolor; // different Lolor than Gaterial5Lolor
vec; "ightHos; // illegal7 alread/ defined
555
555 3 "ightHos; // accessing "ightHos
555 3 Gaterial5Lolor; // accessing Lolor in Lolored+exture bloc=
.utside the shading language Bi.e., in the A5IC, e:ers are siilarl- identi#ied e4ce1t the :lock nae is
alwa-s used in 1lace o# the instance nae BA5I accesses are to inter#aces, not to shadersC. I# there is no
instance nae, then the A5I does not use the :lock nae to access a e:er, Dust the e:er nae.
out 'ertex 4
vec; Hosition; // DH# transform/feedbac= will use 'ertex5Hosition
vec< +exture;
8 Loords; // shader will use Loords5Hosition
out 'ertex< 4
vec; Lolor; // DH# will use Lolor
8;
6or :locks declared as arra-s, the arra- inde4 ust also :e included when accessing e:ers, as in this
e4a1le
uniform +ransform 4 // DH# uses +ransformI<J to refer to instance <
mat; Godel'iewGatrix;
mat; Godel'iewHro:ectionGatrix;
float ,eformation;
8 transformsI;J;
555
555 3 transformsI<J5Godel'iewGatrix; // shader access of instance <
// DH# uses +ransform5Godel'iewGatrix to quer/ an offset or other quer/
6or uni#or :locks declared as an arra-, each individual arra- eleent corres1onds to a se1arate :u##er9
o:Dect :ind range, :acking one instance o# the :lock. As the arra- si=e indicates the nu:er o# :u##er
o:Dects needed, uni#or :lock arra- declarations ust s1eci#- an arra- si=e. An- integral e41ression can
:e used to inde4 a uni#or :lock arra- can onl- :e inde4ed with a d-naicall- uni#or integral
e41ression, otherwise results are unde#ined., as 1er section %.1.& XArra-sX.
47
@hen using .1en23 A5I entr- 1oints to identi#- the nae o# an individual :lock in an arra- o# :locks,
the nae string ust include an arra- inde4 Be.g., &rans%orm526C. @hen using .1en23 A5I entr- 1oints
to re#er to o##sets or other characteristics o# a :lock e:er, an arra- inde4 ust not :e s1eci#ied Be.g.,
&rans%orm.7o$elVie/7atrixC.
2eoetr- shader in1ut :locks ust :e declared as arra-s and #ollow the arra- declaration and linking
rules #or all geoetr- shader in1uts. All other in1ut and out1ut :lock arra-s ust s1eci#- an arra- si=e.
0here is an i1leentation de1endent liit on the nu:er o# uni#or :locks that can :e used 1er stage.
I# this liit is e4ceeded, it will cause a link error.
!.! La(out :ualifiers
3a-out <uali#iers can a11ear in several #ors o# declaration. 0he- can a11ear as 1art o# an inter#ace
:lock de#inition or :lock e:er, as shown in the graar in the 1revious section. 0he- can also a11ear
with Dust an inter#ace <uali#ier Ba storage <uali#ier that is in, out, or uniformC to esta:lish la-outs o# other
declarations ade with that inter#ace <uali#ier:
la+out-1uali%ier inter%ace-1uali%ier E
.r, the- can a11ear with an individual varia:le declared with an inter#ace <uali#ier:
la+out-1uali%ier inter%ace-1uali%ier $eclaration E
Declarations o# la-outs can onl- :e ade at glo:al sco1e, and onl- where indicated in the #ollowing
su:sectionsI their details are s1eci#ic to what the inter#ace <uali#ier is, and are discussed individuall-.
0he la+out-1uali%ier e41ands to
la+out-1uali%ier :
la"out $ la+out-1uali%ier-i$-list %
la+out-1uali%ier-i$-list :
la+out-1uali%ier-i$
la+out-1uali%ier-i$ 1 la+out-1uali%ier-i$-list
la+out-1uali%ier-i$
la+out-1uali%ier-name
la+out-1uali%ier-name T la+out-1uali%ier-value
0he tokens used #or la+out-1uali%ier-name are identi#iers, not ke-words. 2enerall-, the- can :e listed in
an- order. .rder9de1endent eanings e4ist onl- i# e41licitl- called out :elow. ,iilarl-, these identi#iers
are not case sensitive, unless e41licitl- noted otherwise.
;ore than one la-out <uali#ier a- a11ear in a single declaration. I# the sae la+out-1uali%ier-name
occurs in ulti1le la-out <uali#iers #or the sae declaration, the last one overrides the #orer ones.
!.!.1 Input La(out :ualifiers
,oe in1ut la-out <uali#iers a11l- to all shader languages and soe a11l- onl- to s1eci#ic languages.
0he latter are discussed in se1arate sections :elow.
All shaders allow in1ut la-out <uali#iers on in1ut varia:le declarations. 0he location la-out <uali#ier
identi#ier #or in1uts is:
48
la+out-1uali%ier-i$
location B integer-constant
.nl- one arguent is acce1ted. 6or e4a1le,
la/out(location 3 >) in vec; normal;
will esta:lish that the shader in1ut normal is assigned to vector location nu:er '. 6or verte4 shader
in1uts, the location s1eci#ies the nu:er o# the generic verte4 attri:ute #ro which in1ut values are taken.
6or in1uts o# all other shader t-1es, the location s1eci#ies a vector nu:er that can :e used to atch
against out1uts #ro a 1revious shader stage, even i# that shader is in a di##erent 1rogra o:Dect.
I# a verte4 shader declared in1ut is an- scalar or vector t-1e, it will consue a single location. I# a non9
verte4 shader in1ut is a scalar or vector t-1e other than dvec3 or dvec4, it will consue a single location,
while . In1uts o# t-1es dvec3 or dvec4 will consue two consecutive locations. In1uts o# t-1e doule
and dvec! will consue onl- a single location, in all stages.
I# the declared in1ut is an arra- o# si=e n and each eleent takes m locations, it will :e assigned m H n
consecutive locations starting with the location s1eci#ied. 6or e4a1le,
la/out(location 3 B) in vec; colorsI>J;
will esta:lish that the shader in1ut colors is assigned to vector location nu:ers +, ), and (.
I# the declared in1ut is an n 4 m single9 or dou:le91recision atri4, it will :e assigned ulti1le locations
starting with the location s1eci#ied. 0he nu:er o# locations assigned #or each atri4 will :e the sae as
#or an n9eleent arra- o# m9co1onent vectors. 6or e4a1le,
la/out(location 3 A) in mat; transformsI<J;
will esta:lish that shader in1ut trans%orms is assigned to vector locations &91+, with trans%orms506 :eing
assigned to locations &91! and trans%orms516 :eing assigned to locations 1'91+.
I# the declared in1ut is a structure, its e:ers will :e assigned consecutive locations in the order o#
declaration, with the #irst e:er assigned the location s1eci#ied #or the structure. 0he nu:er o#
locations consued :- a structure e:er is deterined :- a11l-ing the rules a:ove recursivel- as
though the structure e:er were declared as an in1ut varia:le o# the sae t-1e. 6or e4a1le,
la/out(location 3 >) struct ) 4
vec> a;
mat< b;
vec; cI<J;
8 s;
will assign location ' to s.a, locations % and * to the two colun vectors o# s.#, and locations + and ) to
s.c.
3ocation la-out <uali#iers a- :e used on in1ut varia:les declared as structures, :ut not on individual
e:ers. 3ocation la-out <uali#iers a- not :e used on in1ut :locks or in1ut :lock e:ers.
3ocation la-out <uali#iers a- :e used on structures, :ut not on individual e:ers. ,tructure e:ers
are assigned, in the order o# their declaration, to consecutive locations starting with the location s1eci#ied
#or the structure.
49
0he nu:er o# in1ut locations availa:le to a shader is liited. 6or verte4 shaders, the liit is the
advertised nu:er o# verte4 attri:utes. 6or all other shaders, the liit is i1leentation9de1endent and
ust :e no less than one #ourth o# the advertised a4iu in1ut co1onent count. A 1rogra will #ail to
link i# an- attached shader uses a location greater than or e<ual to the nu:er o# su11orted locations,
unless device9de1endent o1tii=ations are a:le to ake the 1rogra #it within availa:le hardware
resources.
A 1rogra will #ail to link i# an- two non9verte4 shader in1ut varia:les are assigned to the sae location.
6or verte4 shaders, ulti1le in1ut varia:les a- :e assigned to the sae location using either la-out
<uali#iers or via the .1en23 A5I. /owever, such aliasing is intended onl- to su11ort verte4 shaders
where each e4ecution 1ath accesses at ost one in1ut 1er each location. I1leentations are 1eritted,
:ut not re<uired, to generate link errors i# the- detect that ever- 1ath through the verte4 shader e4ecuta:le
accesses ulti1le in1uts assigned to an- single location. 6or all shader t-1es, a 1rogra will #ail to link i#
e41licit location assignents leave the linker una:le to #ind s1ace #or other varia:les without e41licit
assignents.
6or the 1ur1oses o# deterining i# a non9verte4 in1ut atches an out1ut #ro a 1revious shader stage, the
location la-out <uali#ier Bi# an-C ust atch.
I# a verte4 shader in1ut varia:le with no location assigned in the shader te4t has a location s1eci#ied
through the .1en23 A5I, the A5I9assigned location will :e used. .therwise, such varia:les will :e
assigned a location :- the linker. ,ee section !.11.' EVerte4 Attri:utesF o# the .1en23 2ra1hics ,-ste
,1eci#ication #or ore details. A link error will occur i# an in1ut varia:le is declared in ulti1le shaders
o# the sae language with con#licting locations.
!.!.1.1 Tessellation *valuation Inputs
Additional in1ut la-out <uali#ier identi#iers allowed #or tessellation evaluation shaders are:
la+out-1uali%ier-i$
triangles
Nuads
isolines
eNual&spacing
fractional&even&spacing
fractional&odd&spacing
cw
ccw
point&mode
.ne su:set o# these identi#iers, primitive mo$e, is used to s1eci#- a tessellation 1riitive ode to :e used
:- the tessellation 1riitive generator. 0o s1eci#- a 1riitive ode, the identi#ier ust :e one o#
triangles, Nuads, or isolines, which s1eci#- that the tessellation 1riitive generator should su:divide a
triangle into saller triangles, a <uad into triangles, or a <uad into a collection o# lines, res1ectivel-.
A second su:set o# these identi#iers, vertex spacing, is used to s1eci#- the s1acing used :- the tessellation
1riitive generator when su:dividing an edge. 0o s1eci#- verte4 s1acing, the identi#ier ust :e one o#
the #ollowing.
eNual&spacing signi#-ing that edges should :e divided into a collection o# e<ual9si=ed segents.
5
fractional&even&spacing signi#-ing that edges should :e divided into an even nu:er o# e<ual9
length segents 1lus two additional shorter X#ractionalX segents.
fractional&odd&spacing signi#-ing that edges should :e divided into an odd nu:er o# e<ual9
length segents 1lus two additional shorter X#ractionalX segents.
A third su:set o# these identi#iers, or$ering, s1eci#ies whether the tessellation 1riitive generator
1roduces triangles in clockwise or counter9clockwise order, according to the coordinate s-ste de1icted
in the .1en23 s1eci#ication. 0he ordering identi#iers cw and ccw indicate clockwise and counter9
clockwise triangles, res1ectivel-. I# the tessellation 1riitive generator does not 1roduce triangles,
ordering is ignored.
6inall-, point mo$e* is s1eci#ied with the identi#ier point&mode indicating the tessellation 1riitive
generator should 1roduce a 1oint #or each uni<ue verte4 in the su:divided 1riitive, rather than
generating lines or triangles.
An- or all o# these identi#iers a- :e s1eci#ied one or ore ties in a single in1ut la-out declaration. I#
1riitive ode, verte4 s1acing, or ordering is declared ore than once in the tessellation evaluation
shaders o# a 1rogra, all such declarations ust use the sae identi#ier.
At least one tessellation evaluation shader Bco1ilation unitC in a 1rogra ust declare a 1riitive ode
in its in1ut la-out. Declaring verte4 s1acing, ordering, or 1oint ode identi#iers is o1tional. It is not
re<uired that all tessellation evaluation shaders in a 1rogra declare a 1riitive ode. I# s1acing or
verte4 ordering declarations are oitted, the tessellation 1riitive generator will use e<ual s1acing or
counter9clockwise verte4 ordering, res1ectivel-. I# a 1oint ode declaration is oitted, the tessellation
1riitive generator will 1roduce lines or triangles according to the 1riitive ode.
!.!.1.2 Geometr( Shader Inputs
Additional la-out <uali#ier identi#iers #or geoetr- shader in1uts include primitive identi#iers and an
invocation count identi#ier:
la+out-1uali%ier-i$
points
lines
lines&adMacenc"
triangles
triangles&adMacenc"
invocations B integer-constant
0he identi#iers points, lines, lines&adMacenc", triangles, and triangles&adMacenc" are used to s1eci#- the
t-1e o# in1ut primitive acce1ted :- the geoetr- shader, and onl- one o# these is acce1ted. At least one
geoetr- shader Bco1ilation unitC in a 1rogra ust declare this in1ut 1riitive la-out, and all geoetr-
shader in1ut la-out declarations in a 1rogra ust declare the sae la-out. It is not re<uired that all
geoetr- shaders in a 1rogra declare an in1ut 1riitive la-out.
0he identi#ier invocations is used to s1eci#- the nu:er o# ties the geoetr- shader e4ecuta:le is
invoked #or each in1ut 1riitive received. Invocation count declarations are o1tional. I# no invocation
count is declared in an- geoetr- shader in a 1rogra, the geoetr- shader will :e run once #or each
in1ut 1riitive. I# an invocation count is declared, all such declarations ust s1eci#- the sae count. I# a
51
shader s1eci#ies an invocation count greater than the i1leentation9de1endent a4iu, it will #ail to
co1ile.
6or e4a1le,
la/out(triangles7 invocations 3 B) in;
will esta:lish that all in1uts to the geoetr- shader are triangles and that the geoetr- shader e4ecuta:le
is run si4 ties #or each triangle 1rocessed.
All geoetr- shader in1ut unsi=ed arra- declarations will :e si=ed :- an earlier in1ut 1riitive la-out
<uali#ier, when 1resent, as 1er the #ollowing ta:le.
Ja"out ,i/e of (nput Arra"s
1oints 1
lines !
lines?adDacenc- %
triangles '
triangles?adDacenc- +
0he intrinsicall- declared in1ut arra- gl_in56 will also :e si=ed :- an- in1ut 1riitive9la-out declaration.
/ence, the e41ression
gl!in5length()
will return the value #ro the ta:le a:ove.
6or in1uts declared without an arra- si=e, including intrinsicall- declared in1uts Bi.e., gl_inC, a la-out ust
:e declared :e#ore an- use o# the ethod length or other an- arra- use that re<uires the arra- si=e to :e
known.
It is a co1ile9tie error i# a la-out declarationJs arra- si=e B#ro ta:le a:oveC does not atch all the
e41licit arra- si=es s1eci#ied in declarations o# an in1ut varia:les in the sae shader. 0he #ollowing
includes e4a1les o# co1ile tie errors:
52
// code sequence within one shader555
in vec; Lolor0IJ; // legal7 si.e still un=nown
555Lolor05length()555// illegal7 length() un=nown
in vec; Lolor<I<J; // legal7 si.e is <
555Lolor05length()555// illegal7 Lolor0 still has no si.e
in vec; Lolor>I>J; // illegal7 inut si.es are inconsistent
la/out(lines) in; // legal for Lolor<7 inut si.e is <7 matching Lolor<
in vec; Lolor;I>J; // illegal7 contradicts la/out of lines
555Lolor05length()555// legal7 length() is <7 Lolor0 si.ed b/ la/out()
la/out(lines) in; // legal7 matches other la/out() declaration
la/out(triangles) in;// illegal7 does not match earlier la/out() declaration
It is a link9tie error i# not all 1rovided si=es Bsi=ed in1ut arra-s and la-out si=eC atch across all
geoetr- shaders in a 1rogra.
!.!.1.# /ragment Shader Inputs
Additional #ragent la-out <uali#ier identi#iers include the #ollowing #or gl_"ragCoor$
la+out-1uali%ier-i$
origin&upper&left
pixel&center&integer
B- de#ault, gl_"ragCoor$ assues a lower9le#t origin #or window coordinates and assues 1i4el centers
are located at hal#91i4el coordinates. 6or e4a1le, the Bx* +C location B$.*, $.*C is returned #or the lower9
le#t9ost 1i4el in a window. 0he origin can :e changed :- redeclaring gl_"ragCoor$ with the
origin&upper&left identi#ier, oving the origin o# gl_"ragCoor$ to the u11er le#t o# the window, with +
increasing in value toward the :otto o# the window. 0he values returned can also :e shi#ted :- hal# a
1i4el in :oth x and + :- pixel&center&integer so it a11ears the 1i4els are centered at whole nu:er 1i4el
o##sets. 0his oves the Bx, +C value returned :- gl_"ragCoor$ o# B$.*, $.*C :- de#ault, to B$.$, $.$C with
pixel&center&integer.
Redeclarations are done as #ollows
in vec; gl!&ragLoord; // redeclaration that changes nothing is allowed
// Dll the following are allowed redeclaration that change behavior
la/out(origin!uer!left) in vec; gl!&ragLoord;
la/out(ixel!center!integer) in vec; gl!&ragLoord;
la/out(origin!uer!left7 ixel!center!integer) in vec; gl!&ragLoord;
I# gl_"ragCoor$ is redeclared in an- #ragent shader in a 1rogra, it ust :e redeclared in all the
#ragent shaders in that 1rogra that have a static use gl_"ragCoor$. All redeclarations o#
gl_"ragCoor$ in all #ragent shaders in a single 1rogra ust have the sae set o# <uali#iers. @ithin
an- shader, the #irst redeclarations o# gl_"ragCoor$ ust a11ear :e#ore an- use o# gl_"ragCoor$. 0he
:uilt9in gl_"ragCoor$ is onl- 1redeclared in #ragent shaders, so redeclaring it in another shader
language will :e illegal.
Redeclaring gl_"ragCoor$ with origin&upper&left andGor pixel&center&integer <uali#iers onl- a##ects
gl_"ragCoor$.x and gl_"ragCoor$.+. It has no a##ect on rasteri=ation, trans#oration, or another 1art
o# the .1en23 1i1eline or language #eatures.
53
6ragent shaders also allow the #ollowing la-out <uali#ier on in onl- Bnot with varia:le declarationsC
la+out-1uali%ier-i$
earl"&fragment&tests
to re<uest that #ragent tests :e 1er#ored :e#ore #ragent shader e4ecution, as descri:ed in section '.1$
o# the .1en23 ,1eci#ication.
6or e4a1le,
la/out(earl/!fragment!tests) in;
,1eci#-ing this will ake 1er9#ragent tests :e 1er#ored :e#ore #ragent shader e4ecution. I# this is not
declared, 1er9#ragent tests will :e 1er#ored a#ter #ragent shader e4ecution.
!.!.2 Output La(out :ualifiers
,oe out1ut la-out <uali#iers a11l- to all shader languages and soe a11l- onl- to s1eci#ic languages.
0he latter are discussed in se1arate sections :elow.
All shaders allow location out1ut la-out <uali#iers on out1ut varia:le declarations. 0he location la-out
<uali#ier identi#ier #or out1uts is:
la+out-1uali%ier-i$
6ragent shaders allow an additional index out1ut la-out <uali#iers:
la+out-1uali%ier-i$
index B integer-constant
Each o# these <uali#iers a- a11ear at ost once. I# index is s1eci#ied, location ust also :e s1eci#ied.
I# index is not s1eci#ied, the value $ is used. 6or e4a1le, in a #ragent shader,
la/out(location 3 >) out vec; color;
will esta:lish that the #ragent shader out1ut color is assigned to #ragent color ' as the #irst Binde4 =eroC
in1ut to the :lend e<uation. And,
la/out(location 3 >7 index 3 0) out vec; factor;
will esta:lish that the #ragent shader out1ut %actor is assigned to #ragent color ' as the second Binde4
oneC in1ut to the :lend e<uation.
6or #ragent9shader out1uts, the location and inde4 s1eci#- the color out1ut nu:er and inde4 receiving
the values o# the out1ut. 6or out1uts o# all other shader stages, the location s1eci#ies a vector nu:er that
can :e used to atch against in1uts in a su:se<uent shader stage, even i# that shader is in a di##erent
1rogra o:Dect.
I# a declared out1ut is a scalar or vector t-1e other than dvec3 or dvec4, it will consue a single location.
.ut1uts o# t-1e dvec3 or dvec4 will consue two consecutive locations. .ut1uts o# t-1e doule and
dvec! will consue onl- a single location, in all stages.
54
I# the declared out1ut is an arra-, it will :e assigned consecutive locations starting with the location
s1eci#ied. 6or e4a1le,
la/out(location 3 <) out vec; colorsI>J;
will esta:lish that colors is assigned to vector location nu:ers !, ', and %.
I# the declared out1ut is an n 4 m single9 or dou:le91recision atri4, it will :e assigned ulti1le locations
starting with the location s1eci#ied. 0he nu:er o# locations assigned will :e the sae as #or an n9
eleent arra- o# m9co1onent vectors.
I# the declared out1ut is a structure, its e:ers will :e assigned consecutive locations in the order o#
declaration, with the #irst e:er assigned the location s1eci#ied #or the structure. 0he nu:er o#
locations consued :- a structure e:er is deterined :- a11l-ing the rules a:ove recursivel- as
though the structure e:er were declared as an out1ut varia:le o# the sae t-1e.
3ocation la-out <uali#iers a- :e used on out1ut varia:les declared as structures, :ut not on individual
e:ers. 3ocation la-out <uali#iers a- not :e used on out1ut :locks or out1ut :lock e:ers.
3ocation la-out <uali#iers a- :e used on structures, :ut not on individual e:ers. ,tructure e:ers
are assigned, in the order o# their declaration, to consecutive locations starting with the location s1eci#ied
#or the structure.
I# the naed out1ut is o# a dou:le91recision t-1e, it will :e assigned twice the nu:er o# consecutive
locations a single 1recision t-1e would.
0he nu:er o# out1ut locations availa:le to a shader is liited. 6or #ragent shaders, the liit is the
advertised nu:er o# draw :u##ers. 6or all other shaders, the liit is i1leentation9de1endent and ust
:e no less than one #ourth o# the advertised a4iu out1ut co1onent count. A 1rogra will #ail to
link i# an- attached shader uses a location greater than or e<ual to the nu:er o# su11orted locations,
unless device9de1endent o1tii=ations are a:le to ake the 1rogra #it within availa:le hardware
resources.
A 1rogra will #ail to link i# an- two #ragent shader out1ut varia:les are assigned to the sae location
and inde4, or i# an- two out1ut varia:les #ro the sae non9#ragent shader stage are assigned to the
sae location. 6or #ragent shader out1uts, locations can :e assigned using either a la-out <uali#ier or
via the .1en23 A5I. 6or all shader t-1es, a 1rogra will #ail to link i# e41licit location assignents
leave the linker una:le to #ind s1ace #or other varia:les without e41licit assignents.
I# an out1ut varia:le with no location or inde4 assigned in the shader te4t has a location s1eci#ied through
the .1en23 A5I, the A5I9assigned location will :e used. .therwise, such varia:les will :e assigned a
location :- the linker. All such assignents will have a color inde4 o# =ero. ,ee section '.&.! E,hader
E4ecutionF o# the .1en23 2ra1hics ,-ste ,1eci#ication #or ore details. A link error will occur i# an
out1ut varia:le is declared in ulti1le shaders o# the sae language with con#licting location or inde4
values.
6or the 1ur1oses o# deterining i# a non9#ragent out1ut atches an in1ut #ro a su:se<uent shader
stage, the location la-out <uali#ier Bi# an-C ust atch.
55
!.!.2.1 Tessellation Control Outputs
0essellation control shaders allow out1ut la-out <uali#iers onl- on the inter#ace <uali#ier out, not on an
out1ut :lock, :lock e:er, or varia:le declaration. 0he out1ut la-out <uali#ier identi#iers allowed #or
tessellation control shaders include the verte49count la-out <uali#ier:
la+out-1uali%ier-i$
vertices B integer-constant
0he identi#ier vertices s1eci#ies the nu:er o# vertices in the out1ut 1atch 1roduced :- the tessellation
control shader, which also s1eci#ies the nu:er o# ties the tessellation control shader is invoked. It is an
error #or the out1ut verte4 count to :e less than or e<ual to =ero, or greater than the i1leentation9
de1endent a4iu 1atch si=e.
0he intrinsicall- declared tessellation control out1ut arra- gl&out:; will also :e si=ed :- an- out1ut la-out
declaration. /ence, the e41ression
gl!out5length()
will return the out1ut 1atch verte4 count s1eci#ied in a 1revious out1ut la-out <uali#ier. 6or out1uts
declared without an arra- si=e, including intrinsicall- declared out1uts Bi.e., gl&outC, a la-out ust :e
ust :e declared :e#ore an- use o# the ethod lengthBC or other arra- use re<uires its si=e :e known.
It is a co1ile9tie error i# the out1ut 1atch verte4 count s1eci#ied in an out1ut la-out <uali#ier does not
atch the arra- si=e s1eci#ied in an- out1ut varia:le declaration in the sae shader.
All tessellation control shader la-out declarations in a 1rogra ust s1eci#- the sae out1ut 1atch verte4
count. 0here ust :e at least one la-out <uali#ier s1eci#-ing an out1ut 1atch verte4 count in an- 1rogra
containing tessellation control shadersI however, such a declaration is not re<uired in all tessellation
control shaders.
!.!.2.2 Geometr( Outputs
2eoetr- shaders can have three additional t-1es o# out1ut la-out identi#iers: an out1ut primitive t+pe, a
a4iu out1ut vertex count, and 1er9out1ut stream nu:ers. 0he 1riitive t-1e and verte4 count
identi#iers are allowed onl- on the inter#ace <uali#ier out, not on an out1ut :lock, :lock e:er, or
varia:le declaration. 0he strea identi#ier is allowed on the inter#ace <uali#ier out, on out1ut :locks, and
on varia:le declarations.
0he la-out <uali#ier identi#iers #or geoetr- shader out1uts are
la+out-1uali%ier-i$
points
line&strip
triangle&strip
max&vertices B integer-constant
stream B integer-constant
0he 1riitive t-1e identi#iers points, line&strip, and triangle&strip are used to s1eci#- the t-1e o# out1ut
1riitive 1roduced :- the geoetr- shader, and onl- one o# these is acce1ted. At least one geoetr-
shader Bco1ilation unitC in a 1rogra ust declare an out1ut 1riitive t-1e, and all geoetr- shader
56
out1ut 1riitive t-1e declarations in a 1rogra ust declare the sae 1riitive t-1e. It is not re<uired
that all geoetr- shaders in a 1rogra declare an out1ut 1riitive t-1e.
0he verte4 count identi#ier max&vertices is used to s1eci#- the a4iu nu:er o# vertices the shader
will ever eit in a single invocation. At least one geoetr- shader Bco1ilation unitC in a 1rogra ust
declare a a4iu out1ut verte4 count, and all geoetr- shader out1ut verte4 count declarations in a
1rogra ust declare the sae count. It is not re<uired that all geoetr- shaders in a 1rogra declare a
count.
In this e4a1le,
la/out(triangle!stri7 max!vertices 3 B?) out; // order does not matter
la/out(max!vertices 3 B?) out; // redeclaration o=a/
la/out(triangle!stri) out; // redeclaration o=a/
la/out(oints) out; // error7 contradicts triangle!stri
la/out(max!vertices 3 >?) out; // error7 contradicts B?
all out1uts #ro the geoetr- shader are triangles and at ost +$ vertices will :e eitted :- the shader. It
is an error #or the a4iu nu:er o# vertices to :e greater than gl&LaxGeometr"OutputVertices.
0he identi#ier stream is used to s1eci#- that a geoetr- shader out1ut varia:le or :lock is associated with
a 1articular verte4 strea Bnu:ered :eginning with =eroC. A de#ault strea nu:er a- :e declared at
glo:al sco1e :- <uali#-ing inter#ace <uali#ier out as in this e4a1le:
la/out(stream 3 0) out;
0he strea nu:er s1eci#ied in such a declaration re1laces an- 1revious de#ault and a11lies to all
su:se<uent :lock and varia:le declarations until a new de#ault is esta:lished. 0he initial de#ault strea
nu:er is =ero.
Each out1ut :lock or non9:lock out1ut varia:le is associated with a verte4 strea. I# the :lock or varia:le
is declared with the strea identi#ier, it is associated with the s1eci#ied streaI otherwise, it is associated
with the current de#ault strea. A :lock e:er a- :e declared with a strea identi#ier, :ut the
s1eci#ied strea ust atch the strea associated with the containing :lock. .ne e4a1le:
la/out(stream30) out; // default is now stream 0
out vec; var0; // var0 gets default stream (0)
la/out(stream3<) out 9loc=0 4 // M9loc=0M belongs to stream <
la/out(stream3<) vec; var<; // redundant bloc= member stream decl
la/out(stream3>) vec< var>; // #""%-D" (must match bloc= stream)
vec> var;; // belongs to stream <
8;
la/out(stream3?) out; // default is now stream ?
out vec; varE; // varE gets default stream (?)
out 9loc=< 4 // M9loc=<M gets default stream (?)
vec; varB;
8;
la/out(stream3>) out vec; varC; // varC belongs to stream >
Each verte4 eitted :- the geoetr- shader is assigned to a s1eci#ic strea, and the attri:utes o# the
eitted verte4 are taken #ro the set o# out1ut :locks and varia:les assigned to the targeted strea. A#ter
57
each verte4 is eitted, the values o# all out1ut varia:les :ecoe unde#ined. Additionall-, the out1ut
varia:les associated with each verte4 strea a- share storage. @riting to an out1ut varia:le associated
with one strea a- overwrite out1ut varia:les associated with another strea. @hen eitting each
verte4, a geoetr- shader should write to all out1uts associated with the strea to which the verte4 will
:e eitted and to no out1uts associated with another strea.
I# a geoetr- shader out1ut :lock or varia:le is declared ore than once, all such declarations ust
associate the varia:le with the sae verte4 strea. I# an- strea declaration s1eci#ies a non9e4istent
strea nu:er, the shader will #ail to co1ile.
Built9in geoetr- shader out1uts are alwa-s associated with verte4 strea =ero.
All geoetr- shader out1ut la-out declarations in a 1rogra ust declare the sae la-out and sae value
#or max&vertices. I# geoetr- shaders are in a 1rogra, there ust :e at least one geoetr- out1ut
la-out declaration soewhere in that 1rogra, :ut not all geoetr- shaders Bco1ilation unitsC are
re<uired to declare it.
!.!.2.# /ragment Outputs
0he :uilt9in #ragent shader varia:le gl&-rag)epth a- :e redeclared using one o# the #ollowing la-out
<uali#iers.
la+out-1uali%ier-i$
depth&an"
depth&greater
depth&less
depth&unchanged
6or e4a1le:
la/out (deth!greater) out float gl!&rag,eth;
0he la-out <uali#ier #or gl&-rag)epth constrains intentions o# the #inal value o# gl&-rag)epth written
:- an- shader invocation. 23 i1leentations are allowed to 1er#or o1tii=ations assuing that the
de1th test #ails Bor 1assesC #or a given #ragent i# all values o# gl&-rag)epth consistent with the la-out
<uali#ier would #ail Bor 1assC. I# the #inal value o# gl&-rag)epth is inconsistent with its la-out <uali#ier,
the result o# the de1th test #or the corres1onding #ragent is unde#ined. /owever, no error will :e
generated in this case. I# the de1th test 1asses and de1th writes are ena:led, the value written to the de1th
:u##er is alwa-s the value o# gl&-rag)epth, whether or not it is consistent with the la-out <uali#ier.
B- de#ault, gl&-rag)epth is <uali#ied as $ept'_an+. @hen the la-out <uali#ier #or gl&-rag)epth is
$ept'_an+, the shader co1iler will note an- assignent to gl&-rag)epth odi#-ing it in an unknown
wa-, and de1th testing will alwa-s :e 1er#ored a#ter the shader has e4ecuted. @hen the la-out <uali#ier
is $ept'_greater, the 23 can assue that the #inal value o# gl&-rag)epth is greater than or e<ual to the
#ragentJs inter1olated de1th value, as given :- the 0 co1onent o# gl_"ragCoor$. @hen the la-out
<uali#ier is $ept'_less, the 23 can assue that an- odi#ication o# gl&-rag)epth will onl- decrease its
value. @hen the la-out <uali#ier is $ept'_unc'ange$, the shader co1iler will honor an- odi#ication to
gl&-rag)epth, :ut the rest o# the 23 can assue that gl&-rag)epth is not assigned a new value.
58
Redeclarations o# gl&-rag)epth are 1er#ored as #ollows:
// redeclaration that changes nothing is allowed
out float gl!&rag,eth;
// assume it ma/ be modified in an/ wa/
la/out (deth!an/) out float gl!&rag,eth;
// assume it ma/ be modified such that its value will onl/ increase
la/out (deth!greater) out float gl!&rag,eth;
// assume it ma/ be modified such that its value will onl/ decrease
la/out (deth!less) out float gl!&rag,eth;
// assume it will not be modified
la/out (deth!unchanged) out float gl!&rag,eth;
I# gl&-rag)epth is redeclared in an- #ragent shader in a 1rogra, it ust :e redeclared in all #ragent
shaders in that 1rogra that have static assignents to gl&-rag)epth. All redeclarations o#
gl&-rag)epth in all #ragent shaders in a single 1rogra ust have the sae set o# <uali#iers. @ithin
an- shader, the #irst redeclarations o# gl&-rag)epth ust a11ear :e#ore an- use o# gl&-rag)epth. 0he
:uilt9in gl&-rag)epth is onl- 1redeclared in #ragent shaders, so redeclaring it in another shader
language will :e illegal.
!.!.# 5niform 0loc3 La(out :ualifiers
3a-out <uali#iers can :e used #or uni#or :locks, :ut not #or non9:lock uni#or declarations. 0he la-out
<uali#ier identi#iers #or uni#or :locks are
la+out-1uali%ier-i$
shared
packed
std142
row&maMor
column&maMor
inding B integer-constant
8one o# these have an- seantic a##ect at all on the usage o# the varia:les :eing declaredI the- onl-
descri:e how data is laid out in eor-. 6or e4a1le, atri4 seantics are alwa-s colun9:ased, as
descri:ed in the rest o# this s1eci#ication, no atter what la-out <uali#iers are :eing used.
7ni#or :lock la-out <uali#iers can :e declared #or glo:al sco1e, on a single uni#or :lock, or on a single
:lock e:er declaration.
59
De#ault la-outs are esta:lished Be4ce1t #or #in$ingC at glo:al sco1e #or uni#or :locks as
la/out(la+out-1uali%ier-i$-list) uniform;
@hen this is done, the 1revious de#ault <uali#ication is #irst inherited and then overridden as 1er the
override rules listed :elow #or each <uali#ier listed in the declaration. 0he result :ecoes the new de#ault
<uali#ication sco1ed to su:se<uent uni#or :lock de#initions.
0he initial state o# co1ilation is as i# the #ollowing were declared:
la/out(shared7 column!ma:or) uniform;
E41licitl- declaring this in a shader will return de#aults :ack to their initial state.
7ni#or :locks can :e declared with o1tional la-out <uali#iers, and so can their individual e:er
declarations. ,uch :lock la-out <uali#ication is sco1ed onl- to the content o# the :lock. As with glo:al
la-out declarations, :lock la-out <uali#ication #irst inherits #ro the current de#ault <uali#ication and then
overrides it. ,iilarl-, individual e:er la-out <uali#ication is sco1ed Dust to the e:er declaration,
and inherits #ro and overrides the :lockJs <uali#ication.
0he s'are$ <uali#ier overrides onl- the st$140 and pac.e$ <uali#iersI other <uali#iers are inherited. 0he
co1ilerGlinker will ensure that ulti1le 1rogras and 1rograa:le stages containing this de#inition
will share the sae eor- la-out #or this :lock, as long as the- also atched in their ro/_ma8or andGor
column_ma8or <uali#ications. 0his allows use o# the sae :u##er to :ack the sae :lock de#inition across
di##erent 1rogras.
0he pac.e$ <uali#ier overrides onl- st$140 and s'are$I other <uali#iers are inherited. @hen pac.e$ is
used, no sharea:le la-out is guaranteed. 0he co1iler and linker can o1tii=e eor- use :ased on what
varia:les activel- get used and on other criteria. .##sets ust :e <ueried, as there is no other wa- o#
guaranteeing where Band whichC varia:les reside within the :lock. Atte1ts to share a 1acked uni#or
:lock across 1rogras or stages will generall- #ail. /owever, i1leentations a- aid a11lication
anageent o# 1acked :locks :- using canonical la-outs #or 1acked :locks.
0he st$140 <uali#ier overrides onl- the pac.e$ and s'are$ <uali#iersI other <uali#iers are inherited. 0he
la-out is e41licitl- deterined :- this, as descri:ed in section !.11.% E7ni#or Varia:lesF under ,tandard
7ni#or Block 3a-out o# the .1en23 2ra1hics ,-ste ,1eci#ication. /ence, as in s'are$ a:ove, the
resulting la-out is sharea:le across 1rogras.
3a-out <uali#iers on e:er declarations cannot use the s'are$, pac.e$, or st$140 <uali#iers. 0hese can
onl- :e used at glo:al sco1e or on a :lock declaration.
0he ro/_ma8or <uali#ier overrides onl- the column_ma8or <uali#ierI other <uali#iers are inherited. It onl-
a##ects the la-out o# atrices. Eleents within a atri4 row will :e contiguous in eor-.
0he column_ma8or <uali#ier overrides onl- the ro/_ma8or <uali#ierI other <uali#iers are inherited. It onl-
a##ects the la-out o# atrices. Eleents within a atri4 colun will :e contiguous in eor-.
0he #in$ing identi#ier s1eci#ies the uni#or :u##er :inding 1oint corres1onding to the uni#or :lock,
which will :e used to o:tain the values o# the e:er varia:les o# the :lock. It is an error to s1eci#- the
#in$ing identi#ier #or the glo:al sco1e or #or :lock e:er declarations. An- uni#or :lock declared
without a #in$ing identi#ier is initiall- assigned to :lock :inding 1oint =ero. A#ter a 1rogra is linked, the
6
:inding 1oints used #or uni#or :locks declared with or without a #in$ing identi#ier can :e u1dated :- the
.1en23 A5I.
I# the #in$ing identi#ier is used with a uni#or :lock instanced as an arra- then the #irst eleent o# the
arra- takes the s1eci#ied :lock :inding and each su:se<uent eleent takes the ne4t consecutive uni#or
:lock :inding 1oint.
I# the :inding 1oint #or an- uni#or :lock instance is less than =ero, or greater than or e<ual to the
i1leentation9de1endent a4iu nu:er o# uni#or :u##er :indings, a co1ilation error will occur.
@hen the #in$ing identi#ier is used with a uni#or :lock instanced as an arra- o# si=e , all eleents o#
the arra- #ro #in$ing through #in$ing 9 : 1 ust :e within this range.
@hen ulti1le arguents are listed in a la"out declaration, the a##ect will :e the sae as i# the- were
declared one at a tie, in order #ro le#t to right, each in turn inheriting #ro and overriding the result
#ro the 1revious <uali#ication.
6or e4a1le
la/out(row!ma:or7 column!ma:or)
results in the <uali#ication :eing column_ma8or. .ther e4a1les:
la/out(shared7 row!ma:or) uniform; // default is now shared and row!ma:or
la/out(std0;?) uniform +ransform 4 // la/out of this bloc= is std0;?
mat; G0; // row!ma:or
la/out(column!ma:or) mat; G<; // column ma:or
mat> $0; // row!ma:or
8;
uniform +< 4 // la/out of this bloc= is shared
555
8;
la/out(column!ma:or) uniform +> 4 // shared and column!ma:or
mat; G>; // column!ma:or
la/out(row!ma:or) mat; m;; // row ma:or
mat> $<; // column!ma:or
8;
!.!.! Opa2ue75niform La(out :ualifiers
7ni#or la-out <uali#iers can :e used to :ind o1a<ue uni#or varia:les to s1eci#ic :u##ers or units.
0e4ture iage units can :e :ound to sa1lers, iage units can :e :ound to iages, and atoic counters
can :e :ound to :u##ers.
Details #or s1eci#ic to iage #orats and atoic counter :indings are given in the su:sections :elow.
Iage and sa1ler t-1es :oth take the uni#or la-out <uali#ier identi#ier #or :inding:
la+out-1uali%ier-i$
61
0he identi#ier #in$ing s1eci#ies which unit will :e :ound. An- uni#or sa1ler or iage varia:le
declared without a #in$ing <uali#ier is initiall- :ound to unit =ero. A#ter a 1rogra is linked, the unit
re#erenced :- a sa1ler or iage uni#or varia:le declared with or without a :inding identi#ier can :e
u1dated :- the .1en23 A5I.
I# the #in$ing identi#ier is used with an arra-, the #irst eleent o# the arra- takes the s1eci#ied unit and
each su:se<uent eleent takes the ne4t consecutive unit.
I# the #in$ing is less than =ero, or greater than or e<ual to the i1leentation9de1endent a4iu
su11orted nu:er o# units, a co1ilation error will occur. @hen the #in$ing identi#ier is used with an
arra- o# si=e , all eleents o# the arra- #ro #in$ing through #in$ing 9 - 1 ust :e within this range.
A link error will result i# two co1ilation units in a 1rogra s1eci#- di##erent integer-constant :indings
#or the sae o1a<ue9uni#or nae. /owever, it is not an error to s1eci#- a :inding on soe :ut not all
declarations #or the sae nae, as shown in the e4a1les :elow.
// in one comilation unit555
la/out(binding3>) uniform samler<, s; // s bound to unit >
// in another comilation unit555
uniform samler<, s; // o=a/7 s still bound at >
// in another comilation unit555
la/out(binding3;) uniform samler<, s; // %((*(1 contradictor/ bindings
!.!.!.1 1tomic Counter La(out :ualifiers
0he atoic counter <uali#iers are
la+out-1uali%ier-i$
offset B integer-constant
6or e4a1le,
la/out (binding 3 <7 offset 3 ;) uniform atomic!uint a;
will esta:lish that the o1a<ue handle to the atoic counter a will :e :ound to atoic counter :u##er
:inding 1oint ! at an o##set o# % :asic achine units into that :u##er. 0he de#ault o%%set #or :inding 1oint !
will :e 1ost increented :- % Bthe si=e o# an atoic counterC.
A su:se<uent atoic counter declaration will inherit the 1revious B1ost increentedC o##set. 6or e4a1le,
a su:se<uent declaration o#
la/out (binding 3 <) uniform atomic!uint bar;
will esta:lish that the atoic counter #ar has a :inding to :u##er :inding 1oint ! at an o##set o# ( :asic
achine units into that :u##er. 0he o##set #or :inding 1oint ! will again :e 1ost9increented :- % Bthe si=e
o# an atoic counterC.
@hen ulti1le varia:les are listed in a la-out declaration, the e##ect will :e the sae as i# the- were
declared one at a tie, in order #ro le#t to right.
62
Binding 1oints are not inherited, onl- o##sets. Each :inding 1oint tracks its own current de#ault o%%set #or
inheritance o# su:se<uent varia:les using the sae #in$ing. 0he initial state o# co1ilation is that all
#in$ing 1oints have an o%%set o# $. 0he o%%set can :e set 1er :inding 1oint at glo:al sco1e Bwithout
declaring a varia:leC. 6or e4a1le,
la/out (binding 3 <7 offset 3 ;) uniform atomic!uint;
Esta:lishes that the ne4t atomic&uint declaration #or :inding 1oint ! will inherit o%%set % B:ut does not
esta:lish a de#ault #in$ingC:
la/out (binding 3 <) uniform atomic!uint bar; // offset is ;
la/out (offset 3 F) uniform atomic!uint bar; // error7 no default binding
Atoic counters a- share the sae :inding 1oint, :ut i# a :inding is shared, their o##sets ust :e either
e41licitl- or i1licitl- B#ro inheritanceC uni<ue and non overla11ing.
E4a1le valid uni#or declarations, assuing to1 o# shader:
la/out (binding3>7 offset3;) uniform atomic!uint a; // offset 3 ;
la/out (binding3<) uniform atomic!uint b; // offset 3 ?
la/out (binding3>) uniform atomic!uint c; // offset 3 F
la/out (binding3<) uniform atomic!uint d; // offset 3 ;
E4a1le o# an invalid uni#or declaration:
la/out (offset3;) N // error7 must include binding
la/out (binding307 offset3?) N a; // o=a/
la/out (binding3<7 offset3?) N b; // o=a/
la/out (binding307 offset3?) N c; // error7 offsets must not be shared
// between a and c
la/out (binding307 offset3<) N d; // error7 overlas offset ? of a
It is a co1ile9tie error to :ind an atoic counter with a :inding value greater than or e<ual to
gl_7ax;tomicCounter<in$ings.
!.!.!.2 /ormat La(out :ualifiers
6orat la-out <uali#iers can :e used on iage varia:le declarations Bthose declared with a :asic t-1e
having EimageF in its ke-wordC. 0he #orat la-out <uali#ier identi#iers #or iage varia:le declarations
are
la+out-1uali%ier-i$
%loat-image-%ormat-1uali%ier
int-image-%ormat-1uali%ier
uint-image-%ormat-1uali%ier
inding = integer-constant
%loat-image-%ormat-1uali%ier
rga3!f
rga1+f
rg3!f
rg1+f
63
r11f&g11f&12f
r3!f
r1+f
rga1+
rg12&a!
rga\
rg1+
rg\
r1+
r\
rga1+&snorm
rga\&snorm
rg1+&snorm
rg\&snorm
r1+&snorm
r\&snorm
int-image-%ormat-1uali%ier
rga3!i
rga1+i
rga\i
rg3!i
rg1+i
rg\i
r3!i
r1+i
r\i
uint-image-%ormat-1uali%ier
rga3!ui
rga1+ui
rg12&a!ui
rga\ui
rg3!ui
rg1+ui
rg\ui
r3!ui
r1+ui
r\ui
A #orat la-out <uali#ier s1eci#ies the iage #orat associated with a declared iage varia:le. .nl- one
#orat <uali#ier a- :e s1eci#ied #or an- iage varia:le declaration. 6or iage varia:les with #loating9
1oint co1onent t-1es Bke-words starting with EimageFC, signed integer co1onent t-1es Bke-words
starting with EiimageFC, or unsigned integer co1onent t-1es Bke-words starting with EuimageFC, the
#orat <uali#ier used ust atch the %loat-image-%ormat-1uali%ier, int-image-%ormat-1uali%ier, or uint-
image-%ormat-1uali%ier graar rules, res1ectivel-. It is an error to declare an iage varia:le where the
#orat <uali#ier does not atch the iage varia:le t-1e.
64
An- iage varia:le used #or iage loads or atoic o1erations ust s1eci#- a #orat la-out <uali#ierI it is
an error to 1ass an iage uni#or varia:le or #unction 1araeter declared without a #orat la-out
<uali#ier to an iage load or atoic #unction.
0he #in$ing identi#ier was descri:ed in section %.%.% E7ni#or 3a-out >uali#iersF.
7ni#ors not <uali#ied with writeonl" ust have a #orat la-out <uali#ier. 8ote that an iage varia:le
1assed to a #unction #or read access cannot :e declared as writeonl" and hence ust have :een declared
with a #orat la-out <uali#ier.
!.& Interpolation :ualifiers
In1uts and out1uts that could :e inter1olated can :e #urther <uali#ied :- at ost one o# the #ollowing
inter1olation <uali#iers:
:ualifier 8eaning
smooth 1ers1ective correct inter1olation
flat no inter1olation
noperspective linear inter1olation
0he 1resence o# and t-1e o# inter1olation is controlled :- the a:ove inter1olation <uali#iers as well as the
au4iliar- storage <uali#iers centroid and sample. 0he au4iliar- storage <uali#ier patch is not used #or
inter1olationI it is an error to use inter1olation <uali#iers with patch.
A varia:le <uali#ied as flat will not :e inter1olated. Instead, it will have the sae value #or ever-
#ragent within a triangle. 0his value will coe #ro a single 1rovoking verte4, as descri:ed :- the
.1en23 2ra1hics ,-ste ,1eci#ication. A varia:le a- :e <uali#ied as flat can also :e <uali#ied as
centroid or sample, which will ean the sae thing as <uali#-ing it onl- as flat.
A varia:le <uali#ied as smooth will :e inter1olated in a 1ers1ective9correct anner over the 1riitive
:eing rendered. Inter1olation in a 1ers1ective correct anner is s1eci#ied in e<uation '.+ in the .1en23
2ra1hics ,-ste ,1eci#ication, section '.* E3ine ,egentsF.
A varia:le <uali#ied as noperspective ust :e inter1olated linearl- in screen s1ace, as descri:ed in
e<uation '.) in the .1en23 2ra1hics ,-ste ,1eci#ication, section '.* E3ine ,egentsF.
@hen ulti9sa1le rasteri=ation is disa:led, or #or #ragent shader in1ut varia:les <uali#ied with neither
centroid nor sample, the value o# the assigned varia:le a- :e inter1olated an-where within the 1i4el
and a single value a- :e assigned to each sa1le within the 1i4el, to the e4tent 1eritted :- the
.1en23 2ra1hics ,-ste ,1eci#ication.
@hen ultisa1le rasteri=ation is ena:led, centroid and sample a- :e used to control the location and
#re<uenc- o# the sa1ling o# the <uali#ied #ragent shader in1ut. I# a #ragent shader in1ut is <uali#ied
with centroid, a single value a- :e assigned to that varia:le #or all sa1les in the 1i4el, :ut that value
ust :e inter1olated to a location that lies in :oth the 1i4el and in the 1riitive :eing rendered, including
an- o# the 1i4elJs sa1les covered :- the 1riitive. Because the location at which the varia:le is
inter1olated a- :e di##erent in neigh:oring 1i4els, and derivatives a- :e co1uted :- co1uting
di##erences :etween neigh:oring 1i4els, derivatives o# centroid9sa1led in1uts a- :e less accurate than
those #or non9centroid inter1olated varia:les. I# a #ragent shader in1ut is <uali#ied with sample, a
65
se1arate value ust :e assigned to that varia:le #or each covered sa1le in the 1i4el, and that value ust
:e sa1led at the location o# the individual sa1le.
0he t-1e and 1resence o# inter1olation <uali#iers o# varia:les with the sae nae declared in all linked
shaders #or the sae cross9stage inter#ace ust atch, otherwise the link coand will #ail.
@hen co1aring an out1ut #ro one stage to an in1ut o# a su:se<uent stage, the in1ut and out1ut donJt
atch i# their inter1olation <uali#iers Bor lack thereo#C are not the sae.
!.&.1 ;edeclaring 0uilt7in Interpolation ariables in the Compatibilit( .rofile
0he #ollowing 1redeclared varia:les can :e redeclared with an inter1olation <uali#ier when using the
co1ati:ilit- 1ro#ile:
Verte4, tessellation control, tessellation evaluation, and geoetr- languages:
gl!&rontLolor
gl!9ac=Lolor
gl!&ront)econdar/Lolor
gl!9ac=)econdar/Lolor
6ragent language:
gl!Lolor
gl!)econdar/Lolor
6or e4a1le,
in vec; gl!Lolor; // redeclared b/ the fragment language
flat in vec; gl!Lolor; // redeclared b/ user to be flat
flat in vec; gl!&rontLolor; // inut to geometr/ shader7 no gl!inIJ
flat out vec; gl!&rontLolor; // outut from geometr/ shader
Ideall-, these are redeclared as 1art o# the redeclaration o# an inter#ace :lock, as descri:ed in section ).1.1
E"o1ati:ilit- 5ro#ile Built9In 3anguage Varia:lesF. /owever, #or the a:ove 1ur1ose, the- can :e
redeclared as individual varia:les at glo:al sco1e, outside an inter#ace :lock. A co1ilation error will
result i# a shader has :oth an inter#ace :lock redeclaration and a se1arate redeclaration o# a e:er o#
that inter#ace :lock outside the inter#ace :lock redeclaration.
I# gl_Color is redeclared with an inter1olation <uali#ier, then gl_"rontColor and gl_<ac.Color Bi# the-
are written toC ust also :e redeclared with the sae inter1olation <uali#ier, and vice versa. I#
gl_!econ$ar+Color is redeclared with an inter1olation <uali#ier, then gl_"ront!econ$ar+Color and
gl_<ac.!econ$ar+Color Bi# the- are written toC ust also :e redeclared with the sae inter1olation
<uali#ier, and vice versa. 0his <uali#ier atching on 1redeclared varia:les is onl- re<uired #or varia:les
that are staticall- used within the shaders in a 1rogra.
66
!.' .arameter :ualifiers
In addition to 1recision <uali#iers and eor- <uali#iers, 1araeters can have these 1araeter <uali#iers.
:ualifier 8eaning
R none: de#ault S sae is in
const #or #unction 1araeters that cannot :e written to
in #or #unction 1araeters 1assed into a #unction
out #or #unction 1araeters 1assed :ack out o# a #unction, :ut not initiali=ed
#or use when 1assed in
inout #or #unction 1araeters 1assed :oth into and out o# a #unction
5araeter <uali#iers are discussed in ore detail in section +.1.1 E6unction "alling "onventionsF.
!.% .recision and .recision :ualifiers
5recision <uali#iers are added #or code 1orta:ilit- with .1en23 E,, not #or #unctionalit-. 0he- have the
sae s-nta4 as in .1en23 E,, as descri:ed :elow, :ut the- have no seantic eaning, which includes no
e##ect on the 1recision used to store or o1erate on varia:les.
I# an e4tension adds in the sae seantics and #unctionalit- in the .1en23 E, !.$ s1eci#ication #or
1recision <uali#iers, then the e4tension is allowed to reuse the ke-words :elow #or that 1ur1ose.
6or the 1ur1oses o# deterining i# an out1ut #ro one shader stage atches an in1ut o# the ne4t stage, the
1recision <uali#ier need not atch.
!.%.1 ;ange and .recision
0he 1recision o# stored single9 and dou:le91recision #loating91oint varia:les is de#ined :- the IEEE )*%
standard #or '!9:it and +%9:it #loating91oint nu:ers. 0his includes su11ort #or 8a8s B8ot a 8u:erC
and In#s B1ositive or negative in#initiesC.
0he #ollowing rules a11l- to :oth single and dou:le91recision o1erations: In#inities and =eros are
generated as dictated :- IEEE, :ut su:Dect to the 1recisions allowed in the #ollowing ta:le and su:Dect to
allowing 1ositive and negative =eros to :e interchanged. /owever, dividing a non9=ero :- $ results in the
a11ro1riatel- signed IEEE In#: I# :oth 1ositive and negative =eros are i1leented, the correctl- signed
In# will :e generated, otherwise 1ositive In# is generated. An- denorali=ed value in1ut into a shader or
1otentiall- generated :- an- o1eration in a shader can :e #lushed to $. 0he rounding ode cannot :e set
and is unde#ined. 8a8s are not re<uired to :e generated. ,u11ort #or signaling 8a8s is not re<uired and
e4ce1tions are never raised. .1erations and :uilt9in #unctions that o1erate on a 8a8 are not re<uired to
return a 8a8 as the result.
5recisions are e41ressed in ters o# a4iu relative error in units o# 735 Bunits in the last 1laceC,
unless otherwise noted.
67
6or single 1recision o1erations, 1recisions are re<uired as #ollows:
Operation Srecision
a L #, a ] #, a H # "orrectl- rounded.
R, RT, TT, S, ST "orrect result.
a G #, 1.$ G # !.* 735 #or # in the range [!
91!+
, !
1!+
\.
a H # L c "orrectl- rounded single o1eration or se<uence o#
two correctl- rounded o1erations.
fmaBC Inherited #ro a H # L c.
powBx, +C Inherited #ro exp! Bx = log! B+CC.
exp BxC, exp! BxC B' L ! H WxWC 735.
log BC, log! BC ' 735 outside the range [$.*, !.$\.
A:solute error R !
9!1
inside the range [$.*, !.$\.
sNrt BC Inherited #ro 1.$ G inversesNrtBC.
inversesNrt BC ! 735.
i1licit and e41licit
conversions :etween t-1es
"orrectl- rounded.
Built9in #unctions de#ined in the s1eci#ication with an e<uation :uilt #ro the a:ove o1erations inherit the
a:ove errors. 0hese include, #or e4a1le, the geoetric #unctions, the coon #unctions, and an- o#
the atri4 #unctions. Built9in #unctions not listed a:ove and not de#ined as e<uations o# the a:ove have
unde#ined 1recision. 0hese include, #or e4a1le, the trigonoetric #unctions and deterinant.
0he 1recision o# dou:le91recision o1erations is at least that o# single 1recision.
!.%.2 .recision :ualifiers
An- #loating 1oint or an- integer declaration can have the t-1e 1receded :- one o# these 1recision
<uali#iers:
:ualifier 8eaning
highp 8one.
mediump 8one.
lowp 8one.
68
6or e4a1le:
low float color;
out medium vec< H;
low ivec< foo(low mat>);
high mat; m;
3iteral constants do not have 1recision <uali#iers. 8either do Boolean varia:les. 8either do #loating 1oint
constructors nor integer constructors when none o# the constructor arguents have 1recision <uali#iers.
5recision <uali#iers, as with other <uali#iers, do not e##ect the :asic t-1e o# the varia:le. In 1articular,
there are no constructors #or 1recision conversionsI constructors onl- convert t-1es. ,iilarl-, 1recision
<uali#iers, as with other <uali#iers, do not contri:ute to #unction overloading :ased on 1araeter t-1es. As
discussed in the ne4t cha1ter, #unction in1ut and out1ut is done through co1ies, and there#ore <uali#iers do
not have to atch.
!.%.# ,efault .recision :ualifiers
0he 1recision stateent
recision recision2qualifier t/e;
can :e used to esta:lish a de#ault 1recision <uali#ier. 0he t"pe #ield can :e either int or float, and the
precision-1uali%ier can :e lowp, mediump, or highp. An- other t-1es or <uali#iers will result in an error.
I# t+pe is float, the directive a11lies to non91recision9<uali#ied #loating 1oint t-1e Bscalar, vector, and
atri4C declarations. I# t+pe is int, the directive a11lies to all non91recision9<uali#ied integer t-1e Bscalar,
vector, signed, and unsignedC declarations. 0his includes glo:al varia:le declarations, #unction return
declarations, #unction 1araeter declarations, and local varia:le declarations.
8on91recision <uali#ied declarations will use the 1recision <uali#ier s1eci#ied in the ost recent precision
stateent that is still in sco1e. 0he precision stateent has the sae sco1ing rules as varia:le
declarations. I# it is declared inside a co1ound stateent, its e##ect sto1s at the end o# the innerost
stateent it was declared in. 5recision stateents in nested sco1es override 1recision stateents in outer
sco1es. ;ulti1le 1recision stateents #or the sae :asic t-1e can a11ear inside the sae sco1e, with later
stateents overriding earlier stateents within that sco1e.
0he verte4, tessellation, and geoetr- languages have the #ollowing 1redeclared glo:all- sco1ed de#ault
1recision stateents:
recision high float;
recision high int;
0he #ragent language has the #ollowing 1redeclared glo:all- sco1ed de#ault 1recision stateents:
recision medium int;
recision high float;
69
!.%.! 1vailable .recision :ualifiers
0he :uilt9in acro 23?6RA2;E80?5RE"I,I.8?/I2/ is de#ined to 1:
#define -"!&(D-G%$+!H(%L#)#*$!O#-O 0
0his acro is availa:le in the verte4, tessellation, geoetr-, and #ragent languages.
!.$ ariance and the Invariant :ualifier
In this section, variance re#ers to the 1ossi:ilit- o# getting di##erent values #ro the sae e41ression in
di##erent 1rogras. 6or e4a1le, sa- two verte4 shaders, in di##erent 1rogras, each set gl_Position with
the sae e41ression in :oth shaders, and the in1ut values into that e41ression are the sae when :oth
shaders run. It is 1ossi:le, due to inde1endent co1ilation o# the two shaders, that the values assigned to
gl_Position are not e4actl- the sae when the two shaders run. In this e4a1le, this can cause 1ro:les
with alignent o# geoetr- in a ulti91ass algorith.
In general, such variance :etween shaders is allowed. @hen such variance does not e4ist #or a 1articular
out1ut varia:le, that varia:le is said to :e invariant.
!.$.1 The Invariant :ualifier
0o ensure that a 1articular out1ut varia:le is invariant, it is necessar- to use the invariant <uali#ier. It can
either :e used to <uali#- a 1reviousl- declared varia:le as :eing invariant
invariant gl!Hosition; // ma=e existing gl!Hosition be invariant
out vec> Lolor;
invariant Lolor; // ma=e existing Lolor be invariant
or as 1art o# a declaration when a varia:le is declared
invariant centroid out vec> Lolor;
.nl- varia:les out1ut #ro a shader Bincluding those that are then in1ut to a su:se<uent shaderC can :e
candidates #or invariance. 0his includes user9de#ined out1ut varia:les and the :uilt9in out1ut varia:les.
6or varia:les leaving one shader and coing into another shader, the invariant ke-word has to :e used
in :oth shaders, or a link error will result. As onl- out1uts need :e declared with invariant, an out1ut
#ro one shader stage will still atch an in1ut o# a su:se<uent stage without the in1ut :eing declared as
invariant.
In1ut or out1ut instance naes on :locks are not used when redeclaring :uilt9in varia:les.
0he invariant ke-word can :e #ollowed :- a coa se1arated list o# 1reviousl- declared identi#iers. All
uses o# invariant ust :e at the glo:al sco1e, and :e#ore an- use o# the varia:les :eing declared as
invariant.
0o guarantee invariance o# a 1articular out1ut varia:le across two 1rogras, the #ollowing ust also :e
true:
0he out1ut varia:le is declared as invariant in :oth 1rogras.
7
0he sae values ust :e in1ut to all shader in1ut varia:les consued :- e41ressions and #low control
contri:uting to the value assigned to the out1ut varia:le.
0he te4ture #orats, te4el values, and te4ture #iltering are set the sae wa- #or an- te4ture #unction
calls contri:uting to the value o# the out1ut varia:le.
All in1ut values are all o1erated on in the sae wa-. All o1erations in the consuing e41ressions and
an- interediate e41ressions ust :e the sae, with the sae order o# o1erands and sae
associativit-, to give the sae order o# evaluation. Interediate varia:les and #unctions ust :e
declared as the sae t-1e with the sae e41licit or i1licit 1recision <uali#iers. An- control #low
a##ecting the out1ut value ust :e the sae, and an- e41ressions consued to deterine this control
#low ust also #ollow these invariance rules.
All the data #low and control #low leading to setting the invariant out1ut varia:le reside in a single
co1ilation unit.
Essentiall-, all the data #low and control #low leading to an invariant out1ut ust atch.
Initiall-, :- de#ault, all out1ut varia:les are allowed to :e variant. 0o #orce all out1ut varia:les to :e
invariant, use the 1raga
#ragma )+,-" invariant(all)
:e#ore all declarations in a shader. I# this 1raga is used a#ter the declaration o# an- varia:les or
#unctions, then the set o# out1uts that :ehave as invariant is unde#ined. It is an error to use this 1raga in
a #ragent shader.
2enerall-, invariance is ensured at the cost o# #le4i:ilit- in o1tii=ation, so 1er#orance can :e degraded
:- use o# invariance. /ence, use o# this 1raga is intended as a de:ug aid, to avoid individuall- declaring
all out1ut varia:les as invariant.
!.$.2 Invariance of Constant *-pressions
Invariance ust :e guaranteed #or constant e41ressions. A 1articular constant e41ression ust evaluate to
the sae result i# it a11ears again in the sae shader or a di##erent shader. 0his includes the sae
e41ression a11earing two shaders o# the sae language or shaders o# two di##erent languages.
"onstant e41ressions ust evaluate to the sae result when o1erated on as alread- descri:ed a:ove #or
invariant varia:les.
!." The .recise :ualifier
,oe algoriths re<uire #loating91oint co1utations to e4actl- #ollow the order o# o1erations s1eci#ied in
the source code and to treat all o1erations consistentl-, even i# the i1leentation su11orts o1tii=ations
that could 1roduce nearl- e<uivalent results with higher 1er#orance. 6or e4a1le, an- 23
i1leentations su11ort a Xulti1l-9addX instruction that can co1ute a #loating91oint e41ression such as
result 3 (a P b) K (c P d);
in two o1erations instead o# three o1erationsI one ulti1l- and one ulti1l-9add instead o# two ulti1lies
and one add. 0he result o# a #loating91oint ulti1l-9add a- not alwa-s :e identical to #irst doing a
ulti1l- -ielding a #loating91oint result and then doing a #loating91oint add. /ence, in this e4a1le, the
71
two ulti1l- o1erations would not :e treated consistentl-I the two ulti1lies could e##ectivel- a11ear to
have di##ering 1recisions. @ithout an- <uali#iers, i1leentations are 1eritted to 1er#or such
o1tii=ations that e##ectivel- odi#- the order or nu:er o# o1erations used to evaluate an e41ression,
even i# those o1tii=ations a- 1roduce slightl- di##erent results relative to uno1tii=ed code.
0he <uali#ier precise will ensure that o1erations contri:uting to a varia:leJs value are done in their stated
order and are done with o1erator consistenc-. .rder is deterined :- o1erator 1recedence and
1arenthesis, as descri:ed in section *.1 E.1eratorsF. .1erator consistenc- eans #or each 1articular
o1erator, #or e4a1le the ulti1l- o1erator B 6 C, its o1eration is alwa-s co1uted with the sae
1recision. 8ote this e##ectivel- 1revents #using ulti1le o1erations into a single o1eration.
6or e4a1le,
recise out vec; osition;
declares that o1erations used to 1roduce the value o# position ust :e 1er#ored in e4actl- the order
s1eci#ied in the source code and with all o1erators :eing treated consistentl-. As with the invariant
<uali#ier Bsection %.(.1C, the 1recise <uali#ier a- :e used to <uali#- a :uilt9in or 1reviousl- declared user9
de#ined varia:le as :eing 1recise:
out vec> Lolor;
recise Lolor; // ma=e existing Lolor be recise
0his <uali#ier will a##ect the evaluation o# an r9value in a 1articular #unction i# and onl- i# the result is
eventuall- consued in the sae #unction :- an l9value <uali#ied as precise. An- other e41ressions
within a #unction are not a##ected, including return values and out1ut 1araeters not declared as precise
:ut that are eventuall- consued outside the #unction :- an varia:le <uali#ied as precise.
72
,oe e4a1les o# the use o# precise:
in vec; a7 b7 c7 d;
recise out vec; v;
float func(float e7 float f7 float g7 float h)
4
return (ePf) K (gPh); // no constraint on order or
// oerator consistenc/
8
float func<(float e7 float f7 float g7 float h)
4
recise float result 3 (ePf) K (gPh); // ensures same recision for
// the two multilies
return result;
8
float func>(float i7 float :7 recise out float =)
4
= 3 i P i K :; // recise7 due to 6=Q declaration
8
void main()
4
vec; r 3 vec>(a P b); // recise7 used to comute v5x/.
vec; s 3 vec>(c P d); // recise7 used to comute v5x/.
v5x/. 3 r K s; // recise
v5w 3 (a5w P b5w) K (c5w P d5w); // recise
v5x 3 func(a5x7 b5x7 c5x7 d5x); // values comuted in func()
// are $*+ recise
v5x 3 func<(a5x7 b5x7 c5x7 d5x); // reciseR
func>(a5x P b5x7 c5x P d5x7 v5x); // reciseR
8
6or the 1ur1oses o# deterining i# an out1ut #ro one shader stage atches an in1ut o# the ne4t stage, the
precise <uali#ier need not atch :etween the in1ut and the out1ut.
!.10 8emor( :ualifiers
.nl- varia:les declared as iage t-1es Bthe :asic o1a<ue t-1es with EimageF in their ke-wordC can :e
<uali#ied with a eor- <uali#ier.
73
Varia:les declared as iage t-1es can <uali#ied with one or ore o# the #ollowing eor- <uali#iers:
:ualifier 8eaning
coherent eor- varia:le where reads and writes are coherent with reads and
writes #ro other shader invocations
volatile eor- varia:le whose underl-ing value a- :e changed at an- 1oint
during shader e4ecution :- soe source other than the current shader
invocation
restrict eor- varia:le where use o# that varia:le is the onl- wa- to read
and write the underl-ing eor- in the relevant shader stage
readonl" eor- varia:le that can :e used to read the underl-ing eor-, :ut
cannot :e used to write the underl-ing eor-
writeonl" eor- varia:le that can :e used to write the underl-ing eor-, :ut
cannot :e used to read the underl-ing eor-
;eor- accesses to iage varia:les declared using the coherent <uali#ier are 1er#ored coherentl- with
siilar accesses #ro other shader invocations. In 1articular, when reading a varia:le declared as
coherent, the values returned will re#lect the results o# 1reviousl- co1leted writes 1er#ored :- other
shader invocations. @hen writing a varia:le declared as coherent, the values written will :e re#lected in
su:se<uent coherent reads 1er#ored :- other shader invocations. As descri:ed in the ,ection !.11.1' o#
the .1en23 ,1eci#ication, shader eor- reads and writes co1lete in a largel- unde#ined order. 0he
:uilt9in #unction memor"#arrierBC can :e used i# needed to guarantee the co1letion and relative
ordering o# eor- accesses 1er#ored :- a single shader invocation.
@hen accessing eor- using varia:les not declared as coherent, the eor- accessed :- a shader a-
:e cached :- the i1leentation to service #uture accesses to the sae address. ;eor- stores a- :e
cached in such a wa- that the values written a- not :e visi:le to other shader invocations accessing the
sae eor-. 0he i1leentation a- cache the values #etched :- eor- reads and return the sae
values to an- shader invocation accessing the sae eor-, even i# the underl-ing eor- has :een
odi#ied since the #irst eor- read. @hile varia:les not declared as coherent a- not :e use#ul #or
counicating :etween shader invocations, using non9coherent accesses a- result in higher
1er#orance.
;eor- accesses to iage varia:les declared using the volatile <uali#ier ust treat the underl-ing
eor- as though it could :e read or written at an- 1oint during shader e4ecution :- soe source other
than the e4ecuting shader invocation. @hen a volatile varia:le is read, its value ust :e re9#etched #ro
the underl-ing eor-, even i# the shader invocation 1er#oring the read had 1reviousl- #etched its value
#ro the sae eor-. @hen a volatile varia:le is written, its value ust :e written to the underl-ing
eor-, even i# the co1iler can conclusivel- deterine that its value will :e overwritten :- a
su:se<uent write. ,ince the e4ternal source reading or writing a volatile varia:le a- :e another shader
invocation, varia:les declared as volatile are autoaticall- treated as coherent.
;eor- accesses to iage varia:les declared using the restrict <uali#ier a- :e co1iled assuing that
the varia:le used to 1er#or the eor- access is the onl- wa- to access the underl-ing eor- using
the shader stage in <uestion. 0his allows the co1iler to coalesce or reorder loads and stores using
restrict9<uali#ied iage varia:les in wa-s that wouldnJt :e 1eritted #or iage varia:les not so <uali#ied,
74
:ecause the co1iler can assue that the underl-ing iage wonJt :e read or written :- other code.
A11lications are res1onsi:le #or ensuring that iage eor- re#erenced :- varia:les <uali#ied with
restrict will not :e re#erenced using other varia:les in the sae sco1eI otherwise, accesses to restrict9
<uali#ied varia:les will have unde#ined results.
;eor- accesses to iage varia:les declared using the readonl" <uali#ier a- onl- read the underl-ing
eor-, which is treated as read9onl- eor- and cannot :e written to. It is an error to 1ass an iage
varia:le <uali#ied with readonl" to image,toreBC or other :uilt9in #unctions that odi#- iage eor-.
;eor- accesses to iage varia:les declared using the writeonl" <uali#ier a- onl- write the underl-ing
eor-I the underl-ing eor- cannot :e read. It is an error to 1ass an iage varia:le <uali#ied with
writeonl" to imageJoadBC or other :uilt9in #unctions that read iage eor-.
0he values o# iage varia:les <uali#ied with coherent, volatile, restrict, readonl", or writeonl" a- not
:e 1assed to #unctions whose #oral 1araeters lack such <uali#iers. B,ee section +.1 E6unction
De#initionsF #or ore detail on #unction calling.C It is legal to have additional <uali#iers on a #oral
1araeter, :ut not to have #ewer.
vec; funcD(restrict image<, a) 4 555 8
vec; func9(image<, a) 4 555 8
la/out(rgba><f) uniform image<, img0;
la/out(rgba><f) coherent uniform image<, img<;
funcD(img0); // *S7 adding MrestrictM is allowed
func9(img<); // illegal7 striing McoherentM is not
3a-out <uali#iers cannot :e used on #oral #unction 1araeters, :ut the- are not included in 1araeter
atching.
8ote that the use o# const in an iage varia:le declaration is <uali#-ing the const9ness o# varia:le :eing
declared, not the iage it re#ers to: 0he <uali#ier readonl" <uali#ies the iage eor- Bas accessed
through that varia:leC while const <uali#iers the varia:le itsel#.
!.11 Order of :ualification
@hen ulti1le <uali#iers are 1resent in a declaration, the- a- a11ear in an- order, :ut the- ust all
a11ear :e#ore the t-1e. 0he la"out <uali#ier is the onl- <uali#ier that can a11ear ore than once. 6urther,
a declaration can have at ost one storage <uali#ier, at ost one au4iliar- storage <uali#ier, and at ost
one inter1olation <uali#ier. ;ulti1le eor- <uali#iers can :e used. An- violation o# these rules will
cause a co1ile9tie error.
75
& Operators and *-pressions
&.1 Operators
0he .1en23 ,hading 3anguage has the #ollowing o1erators.
.recedence Operator Class Operators 1ssociativit(
1 BhighestC 1arenthetical grou1ing $ % 8A
!
arra- su:scri1t
#unction call and constructor structure
#ield or ethod selector, swi==le
1ost #i4 increent and decreent
: ;
$ %
.
44 ..
3e#t to Right
'
1re#i4 increent and decreent
unar-
44 ..
4 . A C
Right to 3e#t
% ulti1licative 6 5 7 3e#t to Right
* additive 4 . 3e#t to Right
+ :it9wise shi#t 88 99 3e#t to Right
) relational 8 9 8B 9B 3e#t to Right
( e<ualit- BB CB 3e#t to Right
& :it9wise and @ 3e#t to Right
1$ :it9wise e4clusive or > 3e#t to Right
11 :it9wise inclusive or ? 3e#t to Right
1! logical and @@ 3e#t to Right
1' logical e4clusive or >> 3e#t to Right
1% logical inclusive or ? ? 3e#t to Right
1* selection F D Right to 3e#t
1+
Assignent
arithetic assignents
B
4B .B
6B 5B
7B 88B 99B
@B >B ?B
Right to 3e#t
1) BlowestC se<uence 1 3e#t to Right
0here is no address9o# o1erator nor a dere#erence o1erator. 0here is no t-1ecast o1eratorI constructors
are used instead.
76
5 Operator" and ()pre""ion"
&.2 1rra( Operations
0hese are now descri:ed in section *.) E,tructure and Arra- .1erationsF.
&.# /unction Calls
I# a #unction returns a value, then a call to that #unction a- :e used as an e41ression, whose t-1e will :e
the t-1e that was used to declare or de#ine the #unction.
6unction de#initions and calling conventions are discussed in section +.1 E6unction De#initionsF .
&.! Constructors
"onstructors use the #unction call s-nta4, where the #unction nae is a t-1e, and the call akes an o:Dect
o# that t-1e. "onstructors are used the sae wa- in :oth initiali=ers and e41ressions. B,ee section &
E,hading 3anguage 2raarF #or details.C 0he 1araeters are used to initiali=e the constructed value.
"onstructors can :e used to re<uest a data t-1e conversion to change #ro one scalar t-1e to another
scalar t-1e, or to :uild larger t-1es out o# saller t-1es, or to reduce a larger t-1e to a saller t-1e.
In general, constructors are not :uilt9in #unctions with 1redeterined 1rotot-1es. 6or arra-s and
structures, there ust :e e4actl- one arguent in the constructor #or each eleent or e:er. 6or the
other t-1es, the arguents ust 1rovide a su##icient nu:er o# co1onents to 1er#or the initiali=ation,
and it is an error to include so an- arguents that the- cannot all :e used. Detailed rules #ollow. 0he
1rotot-1es actuall- listed :elow are erel- a su:set o# e4a1les.
&.!.1 Conversion and Scalar Constructors
"onverting :etween scalar t-1es is done as the #ollowing 1rotot-1es indicate:
int(uint) // converts an unsigned integer to a signed integer
int(bool) // converts a 9oolean 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 9oolean 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 9oolean
bool(uint) // converts an unsigned integer value to a 9oolean value
bool(float) // converts a float value to a 9oolean
bool(double) // converts a double value to a 9oolean
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 9oolean value to a float
float(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 9oolean value to a double
double(float)// converts a float value to a double
77
@hen constructors are used to convert an- #loating91oint t-1e to an integer t-1e, the #ractional 1art o# the
#loating91oint value is dro11ed. It is unde#ined to convert a negative #loating 1oint value to an uint.
@hen a constructor is used to convert an- integer or #loating91oint t-1e to a ool, $ and $.$ are converted
to false, and non9=ero values are converted to true. @hen a constructor is used to convert a ool to an-
integer or #loating91oint t-1e, false is converted to $ or $.$, and true is converted to 1 or 1.$.
0he constructor intBuintC 1reserves the :it 1attern in the arguent, which will change the arguentJs
value i# its sign :it is set. 0he constructor uintBintC 1reserves the :it 1attern in the arguent, which will
change its value i# it is negative.
Identit- constructors, like floatBfloatC are also legal, :ut o# little use.
,calar constructors with non9scalar 1araeters can :e used to take the #irst eleent #ro a non9scalar.
6or e4a1le, the constructor floatBvec3C will select the #irst co1onent o# the vec3 1araeter.
&.!.2 ector and 8atri- Constructors
"onstructors can :e used to create vectors or atrices #ro a set o# scalars, vectors, or atrices. 0his
includes the a:ilit- to shorten vectors.
I# there is a single scalar 1araeter to a vector constructor, it is used to initiali=e all co1onents o# the
constructed vector to that scalarNs value. I# there is a single scalar 1araeter to a atri4 constructor, it is
used to initiali=e all the co1onents on the atri4Ns diagonal, with the reaining co1onents initiali=ed
to $.$.
I# a vector is constructed #ro ulti1le scalars, one or ore vectors, or one or ore atrices, or a i4ture
o# these, the vectorJs co1onents will :e constructed in order #ro the co1onents o# the arguents. 0he
arguents will :e consued le#t to right, and each arguent will have all its co1onents consued, in
order, :e#ore an- co1onents #ro the ne4t arguent are consued. ,iilarl- #or constructing a atri4
#ro ulti1le scalars or vectors, or a i4ture o# these. ;atri4 co1onents will :e constructed and
consued in colun aDor order. In these cases, there ust :e enough co1onents 1rovided in the
arguents to 1rovide an initiali=er #or ever- co1onent in the constructed value. It is an error to 1rovide
e4tra arguents :e-ond this last used arguent.
I# a atri4 is constructed #ro a atri4, then each co1onent Bcolun i* row 8C in the result that has a
corres1onding co1onent Bcolun i* row 8C in the arguent will :e initiali=ed #ro there. All other
co1onents will :e initiali=ed to the identit- atri4. I# a atri4 arguent is given to a atri4 constructor,
it is an error to have another arguents.
I# the :asic t-1e Bool1 int1 float, or douleC o# a 1araeter to a constructor does not atch the :asic t-1e
o# the o:Dect :eing constructed, the scalar construction rules Ba:oveC are used to convert the 1araeters.
78
,oe use#ul vector constructors are as #ollows:
vec>(float) // initiali.es each comonent of the vec> with the float
vec;(ivec;) // ma=es a vec; with comonent2wise conversion
vec;(mat<) // the vec; is column ? followed b/ column 0
vec<(float7 float) // initiali.es a vec< with < floats
ivec>(int7 int7 int) // initiali.es an ivec> with > ints
bvec;(int7 int7 float7 float) // uses ; 9oolean conversions
vec<(vec>) // dros the third comonent of a vec>
vec>(vec;) // dros the fourth comonent of a vec;
vec>(vec<7 float) // vec>5x 3 vec<5x7 vec>5/ 3 vec<5/7 vec>5. 3 float
vec>(float7 vec<) // vec>5x 3 float7 vec>5/ 3 vec<5x7 vec>5. 3 vec<5/
vec;(vec>7 float)
vec;(float7 vec>)
vec;(vec<7 vec<)
,oe e4a1les o# these are:
vec; color 3 vec;(?5?7 05?7 ?5?7 05?);
vec; rgba 3 vec;(05?); // sets each comonent to 05?
vec> rgb 3 vec>(color); // dro the ;th comonent
0o initiali=e the diagonal o# a atri4 with all other eleents set to =ero:
mat<(float)
mat>(float)
mat;(float)
0hat is, result5i6586 is set to the #loat arguent #or all i > 8 and set to $ #or all i 8.
79
0o initiali=e a atri4 :- s1eci#-ing vectors or scalars, the co1onents are assigned to the atri4 eleents
in colun9aDor order.
mat<(vec<7 vec<); // one column er argument
mat>(vec>7 vec>7 vec>); // one column er argument
mat;(vec;7 vec;7 vec;7 vec;); // one column er argument
mat>x<(vec<7 vec<7 vec<); // one column er argument
dmat<(dvec<7 dvec<);
dmat>(dvec>7 dvec>7 dvec>);
dmat;(dvec;7 dvec;7 dvec;7 dvec;);
mat<(float7 float7 // first column
float7 float); // second column
mat>(float7 float7 float7 // first column
float7 float7 float7 // second column
float7 float7 float); // third column
mat;(float7 float7 float7 float7 // first column
float7 float7 float7 float7 // second column
float7 float7 float7 float7 // third column
float7 float7 float7 float); // fourth column
mat<x>(vec<7 float7 // first column
vec<7 float); // second column
dmat<x;(dvec>7 double7 // first column
double7 dvec>) // second column
A wide range o# other 1ossi:ilities e4ist, to construct a atri4 #ro vectors and scalars, as long as enough
co1onents are 1resent to initiali=e the atri4. 0o construct a atri4 #ro a atri4:
mat>x>(mat;x;); // ta=es the uer2left >x> of the mat;x;
mat<x>(mat;x<); // ta=es the uer2left <x< of the mat;x;7 last row is ?7?
mat;x;(mat>x>); // uts the mat>x> in the uer2left7 sets the lower right
// comonent to 07 and the rest to ?
&.!.# Structure Constructors
.nce a structure is de#ined, and its t-1e is given a nae, a constructor is availa:le with the sae nae to
construct instances o# that structure. 6or e4a1le:
struct light 4
float intensit/;
vec> osition;
8;
light light'ar 3 light(>5?7 vec>(05?7 <5?7 >5?));
8
0he arguents to the constructor will :e used to set the structureJs e:ers, in order, using one arguent
1er e:er. Each arguent ust :e the sae t-1e as the e:er it sets, or :e a t-1e that can :e
converted to the e:erJs t-1e according to section %.1.1$ EI1licit "onversions.F
,tructure constructors can :e used as initiali=ers or in e41ressions.
&.!.! 1rra( Constructors
Arra- t-1es can also :e used as constructor naes, which can then :e used in e41ressions or initiali=ers.
6or e4a1le,
const float cI>J 3 floatI>J(E5?7 C5<7 050);
const float dI>J 3 floatIJ(E5?7 C5<7 050);
float g;
555
float aIEJ 3 floatIEJ(g7 07 g7 <5>7 g);
float bI>J;
b 3 floatI>J(g7 g K 05?7 g K <5?);
0here ust :e e4actl- the sae nu:er o# arguents as the si=e o# the arra- :eing constructed. I# no si=e
is 1resent in the constructor, then the arra- is e41licitl- si=ed to the nu:er o# arguents 1rovided. 0he
arguents are assigned in order, starting at eleent $, to the eleents o# the constructed arra-. Each
arguent ust :e the sae t-1e as the eleent t-1e o# the arra-, or :e a t-1e that can :e converted to the
eleent t-1e o# the arra- according to section %.1.1$ EI1licit "onversions.F
&.& ector and Scalar Components and Length
0he naes o# the co1onents o# a vector or scalar are denoted :- a single letter. As a notational
convenience, several letters are associated with each co1onent :ased on coon usage o# 1osition,
color or te4ture coordinate vectors. 0he individual co1onents can :e selected :- #ollowing the varia:le
nae with 1eriod B . C and then the co1onent nae.
0he co1onent naes su11orted are:
?x* +* 0* /@ 7se#ul when accessing vectors that re1resent 1oints or norals
?r* g* #* a@ 7se#ul when accessing vectors that re1resent colors
?s* t* p* 1@ 7se#ul when accessing vectors that re1resent te4ture coordinates
0he co1onent naes x* r* and s are, #or e4a1le, s-non-s #or the sae B#irstC co1onent in a vector.
0he- are also the naes o# the onl- co1onent in a scalar.
8ote that the third co1onent o# the te4ture coordinate set, r in .1en23, has :een renaed p so as to
avoid the con#usion with r B#or redC in a color.
Accessing co1onents :e-ond those declared #or the t-1e is an error so, #or e4a1le:
81
vec< os;
float height;
os5x // is legal
os5. // is illegal
height5x // is legal
height5/ // is illegal
0he co1onent selection s-nta4 allows ulti1le co1onents to :e selected :- a11ending their naes
B#ro the sae nae setC a#ter the 1eriod B . C.
vec; v;;
v;5rgba; // is a vec; and the same as :ust using v;7
v;5rgb; // is a vec>7
v;5b; // is a float7
v;5x/; // is a vec<7
v;5xgba; // is illegal 2 the comonent names do not come from
// the same set5
0he order o# the co1onents can :e di##erent to swi==le the, or re1licated:
vec; os 3 vec;(05?7 <5?7 >5?7 ;5?);
vec; swi.3 os5w./x; // swi. 3 (;5?7 >5?7 <5?7 05?)
vec; du 3 os5xx//; // du 3 (05?7 05?7 <5?7 <5?)
float f 3 05<;
vec; du 3 f5xxxx; // du 3 (05<7 05<7 05<7 05<)
0his notation is ore concise than the constructor s-nta4. 0o #or an r9value, it can :e a11lied to an-
e41ression that results in a vector or scalar r9value. An- resulting vector o# an- o1eration ust :e a valid
vector in the languageI hence the #ollowing is illegal:
vec; f;
vec; g 3 os5x/.wx/5x/.w; // illegal; os5x/.wx/ is non2existent vecB
0he co1onent grou1 notation can occur on the le#t hand side o# an e41ression.
vec; os 3 vec;(05?7 <5?7 >5?7 ;5?);
os5xw 3 vec<(E5?7 B5?); // os 3 (E5?7 <5?7 >5?7 B5?)
os5wx 3 vec<(C5?7 F5?); // os 3 (F5?7 <5?7 >5?7 C5?)
os5xx 3 vec<(>5?7 ;5?); // illegal 2 'x' used twice
os5x/ 3 vec>(05?7 <5?7 >5?); // illegal 2 mismatch between vec< and vec>
0o #or an l9value, swi==ling ust :e a11lied to an l9value o# vector or scalar t-1e, contain no du1licate
co1onents, and it results in an l9value o# scalar or vector t-1e, de1ending on nu:er o# co1onents
s1eci#ied.
Arra- su:scri1ting s-nta4 can also :e a11lied to vectors B:ut not to scalarsC to 1rovide nueric inde4ing.
,o in
vec; os;
pos526 re#ers to the third eleent o# 1os and is e<uivalent to pos.0. 0his allows varia:le inde4ing into a
vector, as well as a generic wa- o# accessing co1onents. An- integer e41ression can :e used as the
82
su:scri1t. 0he #irst co1onent is at inde4 =ero. Reading #ro or writing to a vector using a constant
integral e41ression with a value that is negative or greater than or e<ual to the si=e o# the vector is illegal.
@hen inde4ing with non9constant e41ressions, :ehavior is unde#ined i# the inde4 is negative, or greater
than or e<ual to the si=e o# the vector.
0he length ethod a- :e a11lied to vectors B:ut not scalarsC. 0he result is the nu:er o# co1onents in
the vector. 6or e4a1le,
vec> v;
const int " 3 v5length();
sets the constant L to '. 0he t-1e returned :- .lengthBC on a vector is int.
&.' 8atri- Components
0he co1onents o# a atri4 can :e accessed using arra- su:scri1ting s-nta4. A11l-ing a single su:scri1t
to a atri4 treats the atri4 as an arra- o# colun vectors, and selects a single colun, whose t-1e is a
vector o# the sae si=e as the atri4. 0he le#tost colun is colun $. A second su:scri1t would then
o1erate on the resulting vector, as de#ined earlier #or vectors. /ence, two su:scri1ts select a colun and
then a row.
mat; m;
mI0J 3 vec;(<5?); // sets the second column to all <5?
mI?JI?J 3 05?; // sets the uer left element to 05?
mI<JI>J 3 <5?; // sets the ;th element of the third column to <5?
Behavior is unde#ined when accessing a co1onent outside the :ounds o# a atri4 with a non9constant
e41ression. It is an error to access a atri4 with a constant e41ression that is outside the :ounds o# the
atri4.
0he length ethod a- :e a11lied to atrices. 0he result is the nu:er o# coluns o# the atri4. 6or
e4a1le,
mat>x; v;
const int " 3 v5length();
sets the constant L to '. 0he t-1e returned :- .lengthBC on a atri4 is int.
&.% Structure and 1rra( Operations
0he e:ers o# a structure and the length ethod o# an arra- are selected using the 1eriod B . C.
In total, onl- the #ollowing o1erators are allowed to o1erate on arra-s and structures as whole entities:
#ield selector .
e<ualit- BB CB
assignent B
inde4ing Barra-s onl-C [ \
83
0he e<ualit- o1erators and assignent o1erator are onl- allowed i# the two o1erands are sae si=e and
t-1e. ,tructure t-1es ust :e o# the sae declared structure. Both arra- o1erands ust :e e41licitl-
si=ed. @hen using the e<ualit- o1erators, two structures are e<ual i# and onl- i# all the e:ers are
co1onent9wise e<ual, and two arra-s are e<ual i# and onl- i# all the eleents are eleent9wise e<ual.
Arra- eleents are accessed using the arra- su:scri1t o1erator B : ; C. An e4a1le o# accessing an arra-
eleent is
diffuseLolor K3 light#ntensit/I>J P $dot";
Arra- indices start at =ero. Arra- eleents are accessed using an e41ression whose t-1e is int or uint.
Behavior is unde#ined i# a shader su:scri1ts an arra- with an inde4 less than $ or greater than or e<ual to
the si=e the arra- was declared with.
Arra-s can also :e accessed with the ethod o1erator B . C and the length ethod to <uer- the si=e o# the
arra-:
light#ntensit/5length() // return the si.e of the arra/
&.$ 1ssignments
Assignents o# values to varia:le naes are done with the assignent o1erator B B C:
lvalue2exression 3 rvalue2exression
0he lvalue-expression evaluates to an l9value. 0he assignent o1erator stores the value o# rvalue-
expression into the l9value and returns an r9value with the t-1e and 1recision o# lvalue-expression. 0he
lvalue-expression and rvalue-expression ust have the sae t-1e, or the e41ression ust have a t-1e in
the ta:le in section %.1.1$ EI1licit "onversionsF that converts to the t-1e o# lvalue-expression, in which
case an i1licit conversion will :e done on the rvalue-expression :e#ore the assignent is done. An-
other desired t-1e9conversions ust :e s1eci#ied e41licitl- via a constructor. 39values ust :e writa:le.
Varia:les that are :uilt9in t-1es, entire structures or arra-s, structure e:ers, l9values with the #ield
selector B . C a11lied to select co1onents or swi==les without re1eated #ields, l9values within 1arentheses,
and l9values dere#erenced with the arra- su:scri1t o1erator B : ; C are all l9values. .ther :inar- or unar-
e41ressions, #unction naes, swi==les with re1eated #ields, and constants cannot :e l9values. 0he ternar-
o1erator BFDC is also not allowed as an l9value.
E41ressions on the le#t o# an assignent are evaluated :e#ore e41ressions on the right o# the assignent.
0he other assignent o1erators are
add into B4BC
su:tract #ro B.BC
ulti1l- into B6BC
divide into B5BC
odulus into B7BC
le#t shi#t :- B88BC
84
right shi#t :- B99BC
and into B@BC
inclusive9or into B?BC
e4clusive9or into B>BC
where the general e41ression
lvalue op3 exression
is e<uivalent to
lvalue 3 lvalue op exression
where op is as descri:ed :elow, and the l9value and e41ression ust satis#- the seantic re<uireents o#
:oth op and e<uals BBC.
Reading a varia:le :e#ore writing Bor initiali=ingC it is legal, however the value is unde#ined.
&." *-pressions
E41ressions in the shading language are :uilt #ro the #ollowing:
"onstants o# t-1e ool1 all integer t-1es, all #loating91oint t-1es, all vector t-1es, and all atri4 t-1es.
"onstructors o# all t-1es.
Varia:le naes o# all t-1es.
An arra- nae with the length ethod a11lied.
,u:scri1ted arra- naes.
6unction calls that return values.
"o1onent #ield selectors and arra- su:scri1t results.
5arenthesi=ed e41ression. An- e41ression can :e 1arenthesi=ed. 5arentheses can :e used to grou1
o1erations. .1erations within 1arentheses are done :e#ore o1erations across 1arentheses.
0he arithetic :inar- o1erators add B4C, su:tract B.C, ulti1l- B6C, and divide B5C o1erate on integer and
#loating91oint scalars, vectors, and atrices. I# the #undaental t-1es in the o1erands do not atch,
then the conversions #ro section %.1.1$ EI1licit "onversionsF are a11lied to create atching t-1es.
All arithetic :inar- o1erators result in the sae #undaental t-1e Bsigned integer, unsigned integer,
single91recision #loating 1oint, or dou:le91recision #loating 1ointC as the o1erands the- o1erate on,
a#ter o1erand t-1e conversion. A#ter conversion, the #ollowing cases are valid
0he two o1erands are scalars. In this case the o1eration is a11lied, resulting in a scalar.
.ne o1erand is a scalar, and the other is a vector or atri4. In this case, the scalar o1eration is
a11lied inde1endentl- to each co1onent o# the vector or atri4, resulting in the sae si=e vector
or atri4.
85
0he two o1erands are vectors o# the sae si=e. In this case, the o1eration is done co1onent9wise
resulting in the sae si=e vector.
0he o1erator is add B4C, su:tract B.C, or divide B5C, and the o1erands are atrices with the sae
nu:er o# rows and the sae nu:er o# coluns. In this case, the o1eration is done co1onent9
wise resulting in the sae si=e atri4.
0he o1erator is ulti1l- B6C, where :oth o1erands are atrices or one o1erand is a vector and the
other a atri4. A right vector o1erand is treated as a colun vector and a le#t vector o1erand as a
row vector. In all these cases, it is re<uired that the nu:er o# coluns o# the le#t o1erand is e<ual
to the nu:er o# rows o# the right o1erand. 0hen, the ulti1l- B6C o1eration does a linear
alge:raic ulti1l-, -ielding an o:Dect that has the sae nu:er o# rows as the le#t o1erand and the
sae nu:er o# coluns as the right o1erand. ,ection *.1$ EVector and ;atri4 .1erationsF
e41lains in ore detail how vectors and atrices are o1erated on.
All other cases are illegal.
Dividing :- =ero does not cause an e4ce1tion :ut does result in an uns1eci#ied value. 7se the :uilt9in
#unctions dot, cross, matrix'ompLult, and outerSroduct, to get, res1ectivel-, vector dot 1roduct,
vector cross 1roduct, atri4 co1onent9wise ulti1lication, and the atri4 1roduct o# a colun
vector ties a row vector.
0he o1erator odulus B7C o1erates on signed or unsigned integer scalars or integer vectors. I# the
#undaental t-1es in the o1erands do not atch, then the conversions #ro section %.1.1$ EI1licit
"onversionsF are a11lied to create atching t-1es. 0he o1erands cannot :e vectors o# di##ering si=e.
I# one o1erand is a scalar and the other vector, then the scalar is a11lied co1onent9wise to the vector,
resulting in the sae t-1e as the vector. I# :oth are vectors o# the sae si=e, the result is co1uted
co1onent9wise. 0he resulting value is unde#ined #or an- co1onent co1uted with a second
o1erand that is =ero, while results #or other co1onents with non9=ero second o1erands reain
de#ined. I# :oth o1erands are non9negative, then the reainder is non9negative. Results are unde#ined
i# one or :oth o1erands are negative. 0he o1erator odulus B7C is not de#ined #or another data
t-1es Bnon9integer t-1esC.
0he arithetic unar- o1erators negate B9C, 1ost9 and 1re9increent and decreent B.. and 44C o1erate
on integer or #loating91oint values Bincluding vectors and atricesC. All unar- o1erators work
co1onent9wise on their o1erands. 0hese result with the sae t-1e the- o1erated on. 6or 1ost9 and
1re9increent and decreent, the e41ression ust :e one that could :e assigned to Ban l9valueC. 5re9
increent and 1re9decreent add or su:tract 1 or 1.$ to the contents o# the e41ression the- o1erate on,
and the value o# the 1re9increent or 1re9decreent e41ression is the resulting value o# that
odi#ication. 5ost9increent and 1ost9decreent e41ressions add or su:tract 1 or 1.$ to the contents
o# the e41ression the- o1erate on, :ut the resulting e41ression has the e41ressionNs value :e#ore the
1ost9increent or 1ost9decreent was e4ecuted.
0he relational o1erators greater than B9C, less than B8C, greater than or e<ual B9BC, and less than or
e<ual B8BC o1erate onl- on scalar integer and scalar #loating91oint e41ressions. 0he result is scalar
Boolean. Either the o1erandsN t-1es ust atch, or the conversions #ro section %.1.1$ EI1licit
"onversionsF will :e a11lied to o:tain atching t-1es. 0o do co1onent9wise relational co1arisons
on vectors, use the :uilt9in #unctions lessIhan1 lessIhanONual1 greaterIhan1 and
greaterIhanONual.
86
0he e<ualit- o1erators eNual BBBC, and not e<ual BCBC o1erate on all t-1es. 0he- result in a scalar
Boolean. I# the o1erand t-1es do not atch, then there ust :e a conversion #ro section %.1.1$
EI1licit "onversionsF a11lied to one o1erand that can ake the atch, in which case this
conversion is done. 6or vectors, atrices, structures, and arra-s, all co1onents, e:ers, or
eleents o# one o1erand ust e<ual the corres1onding co1onents, e:ers, or eleents in the other
o1erand #or the o1erands to :e considered e<ual. 0o get a vector o# co1onent9wise e<ualit- results
#or vectors, use the :uilt9in #unctions eNual and notONual.
0he logical :inar- o1erators and B@@C, or B ? ? C, and e4clusive or B>>C o1erate onl- on two Boolean
e41ressions and result in a Boolean e41ression. And B@@C will onl- evaluate the right hand o1erand
i# the le#t hand o1erand evaluated to true. .r B ? ? C will onl- evaluate the right hand o1erand i# the le#t
hand o1erand evaluated to false. E4clusive or B>>C will alwa-s evaluate :oth o1erands.
0he logical unar- o1erator not BCC. It o1erates onl- on a Boolean e41ression and results in a Boolean
e41ression. 0o o1erate on a vector, use the :uilt9in #unction not.
0he se<uence B 1 C o1erator that o1erates on e41ressions :- returning the t-1e and value o# the right9
ost e41ression in a coa se1arated list o# e41ressions. All e41ressions are evaluated, in order,
#ro le#t to right.
0he ternar- selection o1erator BFDC. It o1erates on three e41ressions Bexp1 F exp2 D expAC. 0his
o1erator evaluates the #irst e41ression, which ust result in a scalar Boolean. I# the result is true, it
selects to evaluate the second e41ression, otherwise it selects to evaluate the third e41ression. .nl-
one o# the second and third e41ressions is evaluated. 0he second and third e41ressions can :e an-
t-1e, as long their t-1es atch, or there is a conversion in section %.1.1$ EI1licit "onversionsF that
can :e a11lied to one o# the e41ressions to ake their t-1es atch. 0his resulting atching t-1e is the
t-1e o# the entire e41ression.
0he oneJs co1leent o1erator BAC. 0he o1erand ust :e o# t-1e signed or unsigned integer or integer
vector, and the result is the oneJs co1leent o# its o1erandI each :it o# each co1onent is
co1leented, including an- sign :its.
0he shi#t o1erators B88C and B99C. 6or :oth o1erators, the o1erands ust :e signed or unsigned
integers or integer vectors. .ne o1erand can :e signed while the other is unsigned. In all cases, the
resulting t-1e will :e the sae t-1e as the le#t o1erand. I# the #irst o1erand is a scalar, the second
o1erand has to :e a scalar as well. I# the #irst o1erand is a vector, the second o1erand ust :e a scalar
or a vector, and the result is co1uted co1onent9wise. 0he result is unde#ined i# the right o1erand is
negative, or greater than or e<ual to the nu:er o# :its in the le#t e41ressionJs :ase t-1e. 0he value o#
E1 RR E! is E1 Binter1reted as a :it 1atternC le#t9shi#ted :- E! :its. 0he value o# E1 SS E! is E1 right9
shi#ted :- E! :it 1ositions. I# E1 is a signed integer, the right9shi#t will e4tend the sign :it. I# E1 is an
unsigned integer, the right9shi#t will =ero9e4tend.
0he :itwise o1erators and B@C, e4clusive9or B>C, and inclusive9or B?C. 0he o1erands ust :e o# t-1e
signed or unsigned integers or integer vectors. 0he o1erands cannot :e vectors o# di##ering si=e. I# one
o1erand is a scalar and the other a vector, the scalar is a11lied co1onent9wise to the vector, resulting
in the sae t-1e as the vector. 0he #undaental t-1es o# the o1erands Bsigned or unsignedC ust
atch, and will :e the resulting #undaental t-1e. 6or and B@C, the result is the :itwise9and #unction
o# the o1erands. 6or e4clusive9or B>C, the result is the :itwise e4clusive9or #unction o# the o1erands.
6or inclusive9or B?C, the result is the :itwise inclusive9or #unction o# the o1erands.
6or a co1lete s1eci#ication o# the s-nta4 o# e41ressions, see section & E,hading 3anguage 2raar.F
87
&.10 ector and 8atri- Operations
@ith a #ew e4ce1tions, o1erations are co1onent9wise. 7suall-, when an o1erator o1erates on a vector or
atri4, it is o1erating inde1endentl- on each co1onent o# the vector or atri4, in a co1onent9wise
#ashion. 6or e4a1le,
vec> v7 u;
float f;
v 3 u K f;
will :e e<uivalent to
v5x 3 u5x K f;
v5/ 3 u5/ K f;
v5. 3 u5. K f;
And
vec> v7 u7 w;
w 3 v K u;
will :e e<uivalent to
w5x 3 v5x K u5x;
w5/ 3 v5/ K u5/;
w5. 3 v5. K u5.;
and likewise #or ost o1erators and all integer and #loating 1oint vector and atri4 t-1es. 0he e4ce1tions
are atri4 ulti1lied :- vector, vector ulti1lied :- atri4, and atri4 ulti1lied :- atri4. 0hese do
not o1erate co1onent9wise, :ut rather 1er#or the correct linear alge:raic ulti1l-.
vec> v7 u;
mat> m;
u 3 v P m;
is e<uivalent to
u5x 3 dot(v7 mI?J); // mI?J is the left column of m
u5/ 3 dot(v7 mI0J); // dot(a7b) is the inner (dot) roduct of a and b
u5. 3 dot(v7 mI<J);
And
u 3 m P v;
is e<uivalent to
u5x 3 mI?J5x P v5x K mI0J5x P v5/ K mI<J5x P v5.;
u5/ 3 mI?J5/ P v5x K mI0J5/ P v5/ K mI<J5/ P v5.;
u5. 3 mI?J5. P v5x K mI0J5. P v5/ K mI<J5. P v5.;
88
And
mat> m7 n7 r;
r 3 m P n;
is e<uivalent to
rI?J5x 3 mI?J5x P nI?J5x K mI0J5x P nI?J5/ K mI<J5x P nI?J5.;
rI0J5x 3 mI?J5x P nI0J5x K mI0J5x P nI0J5/ K mI<J5x P nI0J5.;
rI<J5x 3 mI?J5x P nI<J5x K mI0J5x P nI<J5/ K mI<J5x P nI<J5.;
rI?J5/ 3 mI?J5/ P nI?J5x K mI0J5/ P nI?J5/ K mI<J5/ P nI?J5.;
rI0J5/ 3 mI?J5/ P nI0J5x K mI0J5/ P nI0J5/ K mI<J5/ P nI0J5.;
rI<J5/ 3 mI?J5/ P nI<J5x K mI0J5/ P nI<J5/ K mI<J5/ P nI<J5.;
rI?J5. 3 mI?J5. P nI?J5x K mI0J5. P nI?J5/ K mI<J5. P nI?J5.;
rI0J5. 3 mI?J5. P nI0J5x K mI0J5. P nI0J5/ K mI<J5. P nI0J5.;
rI<J5. 3 mI?J5. P nI<J5x K mI0J5. P nI<J5/ K mI<J5. P nI<J5.;
and siilarl- #or other si=es o# vectors and atrices.
89
' Statements and Structure
0he #undaental :uilding :locks o# the .1en23 ,hading 3anguage are:
stateents and declarations
#unction de#initions
selection Bif.else and switch.case.defaultC
iteration Bfor1 while1 and do.whileC
Du1s Bdiscard1 return1 reak1 and continueC
0he overall structure o# a shader is as #ollows
translation-unit:
glo#al-$eclaration
translation-unit glo#al-$eclaration
glo#al-$eclaration:
%unction-$e%inition
$eclaration
0hat is, a shader is a se<uence o# declarations and #unction :odies. 6unction :odies are de#ined as
%unction-$e%inition:
%unction-protot+pe ? statement-list @
statement-list:
statement
statement-list statement
statement:
compoun$-statement
simple-statement
"url- :races are used to grou1 se<uences o# stateents into co1ound stateents.
compoun$-statement:
? statement-list @
simple-statement:
$eclaration-statement
expression-statement
selection-statement
9
6 State*ent" and Structure
iteration-statement
8ump-statement
,i1le declaration, e41ression, and Du1 stateents end in a sei9colon.
0his a:ove is slightl- si1li#ied, and the co1lete graar s1eci#ied in section & E,hading 3anguage
2raarF should :e used as the de#initive s1eci#ication.
Declarations and e41ressions have alread- :een discussed.
'.1 /unction ,efinitions
As indicated :- the graar a:ove, a valid shader is a se<uence o# glo:al declarations and #unction
de#initions. A #unction is declared as the #ollowing e4a1le shows:
// rotot/e
return+/e function$ame (t/e? arg?7 t/e0 arg07 5557 t/en argn);
and a #unction is de#ined like
// definition
return+/e function$ame (t/e? arg?7 t/e0 arg07 5557 t/en argn)
4
// do some comutation
return return'alue;
8
where return&+pe ust :e 1resent and include a t-1e. I# the t-1e o# returnValue does not atch
return&+pe* there ust :e an i1licit conversion in section %.1.1$ EI1licit "onversionsF that converts
the t-1e o# returnValue to return&+pe* or a co1ile error will result.
Each o# the t+pe ust include a t-1e and can o1tionall- include 1araeter <uali#iers. 0he #oral
arguent naes Bargs a:oveC in the declarations are o1tional #or :oth the declaration and de#inition
#ors.
A #unction is called :- using its nae #ollowed :- a list o# arguents in 1arentheses.
Arra-s are allowed as arguents and as the return t-1e. In :oth cases, the arra- ust :e e41licitl- si=ed.
An arra- is 1assed or returned :- using Dust its nae, without :rackets, and the si=e o# the arra- ust
atch the si=e s1eci#ied in the #unctionJs declaration.
,tructures are also allowed as arguent t-1es. 0he return t-1e can also :e structure.
,ee section & E,hading 3anguage 2raarF #or the de#initive re#erence on the s-nta4 to declare and
de#ine #unctions.
All #unctions ust :e either declared with a 1rotot-1e or de#ined with a :od- :e#ore the- are called. 6or
e4a1le:
float m/func (float f7 // f is an inut arameter
out float g); // g is an outut arameter
91
6unctions that return no value ust :e declared as void. A void #unction can onl- use return without a
return arguent, even i# the return arguent has void t-1e. Return stateents onl- acce1t values:
void #unc1BC ^ _
void #unc!BC ^ return #unc1BCI _ GG illegal return stateent
.nl- a 1recision <uali#ier is allowed on the return t-1e o# a #unction. 6oral 1araeters can have
1araeter, 1recision, and eor- <uali#iers, :ut no other <uali#iers.
6unctions that acce1t no in1ut arguents need not use void in the arguent list :ecause 1rotot-1es Bor
de#initionsC are re<uired and there#ore there is no a:iguit- when an e1t- arguent list XB CX is declared.
0he idio EBvoidCF as a 1araeter list is 1rovided #or convenience.
6unction naes can :e overloaded. 0he sae #unction nae can :e used #or ulti1le #unctions, as long
as the 1araeter t-1es di##er. I# a #unction nae is declared twice with the sae 1araeter t-1es, then the
return t-1es and all <uali#iers ust also atch, and it is the sae #unction :eing declared. 6or e4a1le,
vec; f(in vec; x7 out vec; /); // (D)
vec; f(in vec; x7 out uvec; /); // (9) o=a/7 different argument t/e
vec; f(in ivec; x7 out uvec; /); // (L) o=a/7 different argument t/e
int f(in vec; x7 out ivec; /); // error7 onl/ return t/e differs
vec; f(in vec; x7 in vec; /); // error7 onl/ qualifier differs
vec; f(const in vec; x7 out vec; /); // error7 onl/ qualifier differs
@hen #unction calls are resolved, an e4act t-1e atch #or all the arguents is sought. I# an e4act atch is
#ound, all other #unctions are ignored, and the e4act atch is used. I# no e4act atch is #ound, then the
i1licit conversions in section %.1.1$ EI1licit "onversionsF will :e a11lied to #ind a atch.
;isatched t-1es on in1ut 1araeters Bin or inout or de#ault% ust have a conversion #ro the calling
arguent t-1e to the #oral 1araeter t-1e. ;isatched t-1es on out1ut 1araeters Bout or inoutC ust
have a conversion #ro the #oral 1araeter t-1e to the calling arguent t-1e.
I# i1licit conversions can :e used to #ind ore than one atching #unction, a single :est9atching
#unction is sought. 0o deterine a :est atch, the conversions :etween calling arguent and #oral
1araeter t-1es are co1ared #or each #unction arguent and 1air o# atching #unctions. A#ter these
co1arisons are 1er#ored, each 1air o# atching #unctions are co1ared. A #unction declaration ; is
considered a :etter atch than #unction declaration < i#
#or at least one #unction arguent, the conversion #or that arguent in ; is :etter than the
corres1onding conversion in <I and
there is no #unction arguent #or which the conversion in < is :etter than the corres1onding
conversion in ;.
I# a single #unction declaration is considered a :etter atch than ever- other atching #unction
declaration, it will :e used. .therwise, a seantic error #or an a:iguous overloaded #unction call occurs
and the shader will #ail to co1ile.
0o deterine whether the conversion #or a single arguent in one atch is :etter than that #or another
atch, the #ollowing rules are a11lied, in order:
1. An e4act atch is :etter than a atch involving an- i1licit conversion.
92
!. A atch involving an i1licit conversion #ro float to doule is :etter than a atch involving
another i1licit conversion.
'. A atch involving an i1licit conversion #ro either int or uint to float is :etter than a atch
involving an i1licit conversion #ro either int or uint to doule.
I# none o# the rules a:ove a11l- to a 1articular 1air o# conversions, neither conversion is considered :etter
than the other.
6or the e4a1le #unction 1rotot-1es BAC, BBC, and B"C a:ove, the #ollowing e4a1les show how the rules
a11l- to di##erent sets o# calling arguent t-1es:
f(vec;7 vec;); // exact match of vec; f(in vec; x7 out vec; /)
f(vec;7 uvec;); // exact match of vec; f(in vec; x7 out ivec; /)
f(vec;7 ivec;); // matched to vec; f(in vec; x7 out vec; /)
// (L) not relevant7 can't convert vec; to
// ivec;5 (D) better than (9) for <nd
// argument (rule <)7 same on first argument5
f(ivec;7 vec;); // $*+ matched5 Dll three match b/ imlicit
// conversion5 (L) is better than (D) and (9)
// on the first argument5 (D) is better than
// (9) and (L)5
7ser9de#ined #unctions can have ulti1le declarations, :ut onl- one de#inition. A shader can rede#ine
:uilt9in #unctions. I# a :uilt9in #unction is redeclared in a shader Bi.e., a 1rotot-1e is visi:leC :e#ore a call
to it, then the linker will onl- atte1t to resolve that call within the set o# shaders that are linked with it.
0he #unction main is used as the entr- 1oint to a shader e4ecuta:le. A shader need not contain a #unction
naed main, :ut one shader in a set o# shaders linked together to #or a single shader e4ecuta:le ust.
0his #unction takes no arguents, returns no value, and ust :e declared as t-1e voidD
void main()
4
555
8
0he #unction main can contain uses o# return. ,ee section +.% EJu1sF #or ore details.
It is an error to declare or de#ine a #unction main with another 1araeters or return t-1e.
'.1.1 /unction Calling Conventions
6unctions are called :- value9return. 0his eans in1ut arguents are co1ied into the #unction at call tie,
and out1ut arguents are co1ied :ack to the caller :e#ore #unction e4it. Because the #unction works with
local co1ies o# 1araeters, there are no issues regarding aliasing o# varia:les within a #unction. 0o
control what 1araeters are co1ied in andGor out through a #unction de#inition or declaration:
0he ke-word in is used as a <uali#ier to denote a 1araeter is to :e co1ied in, :ut not co1ied out.
0he ke-word out is used as a <uali#ier to denote a 1araeter is to :e co1ied out, :ut not co1ied in.
0his should :e used whenever 1ossi:le to avoid unnecessaril- co1-ing 1araeters in.
93
0he ke-word inout is used as a <uali#ier to denote the 1araeter is to :e :oth co1ied in and co1ied
out. It eans the sae thing as s1eci#-ing :oth in and out.
A #unction 1araeter declared with no such <uali#ier eans the sae thing as s1eci#-ing in.
All arguents are evaluated at call tie, e4actl- once, in order, #ro le#t to right. Evaluation o# an in
1araeter results in a value that is co1ied to the #oral 1araeter. Evaluation o# an out 1araeter results
in an l9value that is used to co1- out a value when the #unction returns. Evaluation o# an inout 1araeter
results in :oth a value and an l9valueI the value is co1ied to the #oral 1araeter at call tie and the l9
value is used to co1- out a value when the #unction returns.
0he order in which out1ut 1araeters are co1ied :ack to the caller is unde#ined.
I# the #unction atching descri:ed in the 1revious section re<uired arguent t-1e conversions, these
conversions are a11lied at co1-9in and co1-9out ties.
In a #unction, writing to an in1ut9onl- 1araeter is allowed. .nl- the #unctionNs co1- is odi#ied. 0his
can :e 1revented :- declaring a 1araeter with the const <uali#ier.
@hen calling a #unction, e41ressions that do not evaluate to l9values cannot :e 1assed to 1araeters
declared as out or inout.
%unction-protot+pe :
precision-1uali%ier t+pe %unction-name3parameter-1uali%iers precision-1uali%ier t+pe name
arra+-speci%ier* ... 4
t+pe :
an- :asic t-1e, arra- t-1e, structure nae, or structure $e%inition
parameter-1uali%iers :
e1t-
list o# parameter-1uali%ier
parameter-1uali%ier :
const
in
out
inout
precise
memor+ 1uali%ier
precision 1uali%ier
name :
e1t-
identi#ier
arra+-speci%ier :
e1t-
: integral-constant-expression ;
94
0he const <uali#ier cannot :e used with out or inout. 0he a:ove is used #or #unction declarations Bi.e.,
1rotot-1esC and #or #unction de#initions. /ence, #unction de#initions can have unnaed arguents.
Recursion is not allowed, not even staticall-. ,tatic recursion is 1resent i# the static #unction9call gra1h o#
a 1rogra contains c-cles. 0his includes all 1otential #unction calls through varia:les declared as
suroutine uniform Bdescri:ed :elowC. It is an error i# a single co1ilation unit BshaderC contains either
static recursion or the 1otential #or recursion through su:routine varia:les.
'.1.2 Subroutines
,u:routines 1rovide a echanis allowing shaders to :e co1iled in a anner where the target o# one or
ore #unction calls can :e changed at run9tie without re<uiring an- shader reco1ilation. 6or e4a1le,
a single shader a- :e co1iled with su11ort #or ulti1le illuination algoriths to handle di##erent
kinds o# lights or sur#ace aterials. An a11lication using such a shader a- switch illuination
algoriths :- changing the value o# its su:routine uni#ors. 0o use su:routines, a su:routine t-1e is
declared, one or ore #unctions are associated with that su:routine t-1e, and a su:routine varia:le o# that
t-1e is declared. 0he #unction currentl- assigned to the varia:le #unction is then called :- using #unction
calling s-nta4 re1lacing a #unction nae with the nae o# the su:routine varia:le. ,u:routine varia:les
are uni#ors, and are assigned to s1eci#ic #unctions onl- through coands BUniform,uroutinesuivC in
the .1en23 A5I.
,u:routine t-1es are declared using a stateent siilar to a #unction declaration, with the suroutine
ke-word, as #ollows:
subroutine return+/e subroutine+/e$ame(t/e? arg?7 t/e0 arg07
5557 t/en argn);
As with #unction declarations, the #oral arguent naes Bargs a:oveC are o1tional. 6unctions are
associated with su:routine t-1es o# atching declarations :- de#ining the #unction with the suroutine
ke-word and a list o# su:routine t-1es the #unction atches:
subroutine(subroutine+/e$ame?7 5557 subroutine+/e$ame$)
return+/e function$ame(t/e? arg?7 t/e0 arg07 5557 t/en argn)
4 555 8 // function bod/
It is an error i# arguents and return t-1e donJt atch :etween the #unction and each associated su:routine
t-1e.
6unctions declared with suroutine ust include a :od-. An overloaded #unction cannot :e declared
with suroutineI a 1rogra will #ail to co1ile or link i# an- shader or stage contains two or ore
#unctions with the sae nae i# the nae is associated with a su:routine t-1e.
,u:routine t-1e varia:les are re<uired to :e su#routine uni%orms, and are declared with a s1eci#ic
su:routine t-1e in a su:routine uni#or varia:le declaration:
subroutine uniform subroutine+/e$ame subroutine'ar$ame;
,u:routine uni#or varia:les are called the sae wa- #unctions are called. @hen a su:routine varia:le
Bor an eleent o# a su:routine varia:le arra-C is associated with a 1articular #unction, all #unction calls
through that varia:le will call that 1articular #unction.
95
7nlike other uni#or varia:les, su:routine uni#or varia:les are sco1ed to the shader e4ecution stage the
varia:le is declared in.
,u:routine varia:les a- :e declared as e41licitl-9si=ed arra-s, which can :e d-naicall- inde4ed at use.
'.2 Selection
"onditional control #low in the shading language is done :- either if, if9else, or switch stateents:
selection-statement :
if B #ool-expression C statement
if B #ool-expression C statement else statement
switch B init-expression C ^ s/itc'-statement-listopt

_
@here s/itc'-statement-list is a list o# =ero or ore s/itc'-statement and other stateents de#ined :- the
language, where s/itc'-statement adds soe #ors o# la:els. 0hat is
s/itc'-statement-list :
s/itc'-statement
s/itc'-statement-list s/itc'-statement
s/itc'-statement :
case constant-expression D
default D
statement
I# an if.e41ression evaluates to true, then the #irst statement is e4ecuted. I# it evaluates to false and there
is an else 1art then the second statement is e4ecuted.
An- e41ression whose t-1e evaluates to a Boolean can :e used as the conditional e41ression #ool-
expression. Vector t-1es are not acce1ted as the e41ression to if.
"onditionals can :e nested.
0he t-1e o# init-expression in a switch stateent ust :e a scalar integer. I# a case la:el has a constant-
expression o# e<ual value, then e4ecution will continue a#ter that la:el. .therwise, i# there is a default
la:el, e4ecution will continue a#ter that la:el. .therwise, e4ecution ski1s the rest o# the switch stateent.
It is an error to have ore than one default or a re1licated constant-expression. A reak stateent not
nested in a loo1 or other switch stateent Beither not nested or nested onl- in if or if9else stateentsC will
also ski1 the rest o# the switch stateent. 6all through la:els are allowed, :ut it is an error to have no
stateent :etween a la:el and the end o# the switch stateent. 8o stateents are allowed in a switch
stateent :e#ore the #irst case stateent.
8o case or default la:els can :e nested inside other #low control nested within their corres1onding
switch.
96
'.# Iteration
6or, while, and do loo1s are allowed as #ollows:
for (init2exression; condition2exression; loo2exression)
sub2statement
while (condition2exression)
sub2statement
do
statement
while (condition2exression)
,ee section & E,hading 3anguage 2raarF #or the de#initive s1eci#ication o# loo1s.
0he for loo1 #irst evaluates the init-expression, then the con$ition-expression. I# the con$ition-
expression evaluates to true, then the :od- o# the loo1 is e4ecuted. A#ter the :od- is e4ecuted, a for loo1
will then evaluate the loop-expression, and then loo1 :ack to evaluate the con$ition-expression, re1eating
until the con$ition-expression evaluates to #alse. 0he loo1 is then e4ited, ski11ing its :od- and ski11ing
its loop-expression. Varia:les odi#ied :- the loop-expression aintain their value a#ter the loo1 is
e4ited, 1rovided the- are still in sco1e. Varia:les declared in init-expression or con$ition-expression are
onl- in sco1e until the end o# the su:9stateent o# the for loo1.
0he while loo1 #irst evaluates the con$ition-expression. I# true, then the :od- is e4ecuted. 0his is then
re1eated, until the con$ition-expression evaluates to #alse, e4iting the loo1 and ski11ing its :od-.
Varia:les declared in the con$ition-expression are onl- in sco1e until the end o# the su:9stateent o# the
while loo1.
6or :oth for and while loo1s, the su:9stateent does not introduce a new sco1e #or varia:le naes, so the
#ollowing has a redeclaration error:
for (int i 3 ?; i 6 0?; iKK) 4
int i; // redeclaration error
8
0he do.while loo1 #irst e4ecutes the :od-, then e4ecutes the con$ition-expression. 0his is re1eated until
con$ition-expression evaluates to #alse, and then the loo1 is e4ited.
E41ressions #or con$ition-expression ust evaluate to a Boolean.
Both the con$ition-expression and the init-expression can declare and initiali=e a varia:le, e4ce1t in the
do.while loo1, which cannot declare a varia:le in its con$ition-expression. 0he varia:leNs sco1e lasts
onl- until the end o# the su:9stateent that #ors the :od- o# the loo1.
3oo1s can :e nested.
8on9terinating loo1s are allowed. 0he conse<uences o# ver- long or non9terinating loo1s are 1lat#or
de1endent.
97
'.! <umps
0hese are the Du1s:
8ump_statement:
continueE
reakE
returnE
return expressionE
discardE 55 in the #ragent shader language onl-
0here is no EgotoF nor other non9structured #low o# control.
0he continue Du1 is used onl- in loo1s. It ski1s the reainder o# the :od- o# the inner ost loo1 o#
which it is inside. 6or while and do.while loo1s, this Du1 is to the ne4t evaluation o# the loo1
con$ition-expression #ro which the loo1 continues as 1reviousl- de#ined. 6or for loo1s, the Du1 is to
the loop-expression, #ollowed :- the con$ition-expression.
0he reak Du1 can also :e used onl- in loo1s and switch stateents. It is si1l- an iediate e4it o#
the inner9ost loo1 or switch stateents containing the reak. 8o #urther e4ecution o# con$ition-
expression* loop-expression, or s/itc'-statement is done.
0he discard ke-word is onl- allowed within #ragent shaders. It can :e used within a #ragent shader to
a:andon the o1eration on the current #ragent. 0his ke-word causes the #ragent to :e discarded and no
u1dates to an- :u##ers will occur. "ontrol #low e4its the shader, and su:se<uent i1licit or e41licit
derivatives are unde#ined when this e4it is non9uni#or. It would t-1icall- :e used within a conditional
stateent, #or e4a1le:
if (intensit/ 6 ?5?)
discard;
A #ragent shader a- test a #ragentNs al1ha value and discard the #ragent :ased on that test.
/owever, it should :e noted that coverage testing occurs a#ter the #ragent shader runs, and the coverage
test can change the al1ha value.
0he return Du1 causes iediate e4it o# the current #unction. I# it has expression then that is the return
value #or the #unction.
0he #unction main can use return. 0his si1l- causes main to e4it in the sae wa- as when the end o#
the #unction had :een reached. It does not i1l- a use o# discard in a #ragent shader. 7sing return in
ain :e#ore de#ining out1uts will have the sae :ehavior as reaching the end o# ain :e#ore de#ining
out1uts.
98
% 0uilt7in ariables
%.1 0uilt7In Language ariables
,oe .1en23 o1erations occur in #i4ed #unctionalit- and need to 1rovide values to or receive values
#ro shader e4ecuta:les. ,haders counicate with #i4ed9#unction .1en23 1i1eline stages, and
o1tionall- with other shader e4ecuta:les, through the use o# :uilt9in in1ut and out1ut varia:les.
In the verte4 language, the :uilt9ins are intrinsicall- declared as:
in int gl!'ertex#,;
in int gl!#nstance#,;
out gl!Her'ertex 4
vec; gl!Hosition;
float gl!Hoint)i.e;
float gl!Lli,istanceIJ;
8;
99
7 !ui%t+in #aria$%e"
In the geoetr- language, the :uilt9in varia:les are intrinsicall- declared as:
in gl!Her'ertex 4
vec; gl!Hosition;
float gl!Hoint)i.e;
8 gl!inIJ;
in int gl!Hrimitive#,#n;
in int gl!#nvocation#,;
out gl!Her'ertex 4
vec; gl!Hosition;
float gl!Hoint)i.e;
8;
out int gl!Hrimitive#,;
out int gl!"a/er;
out int gl!'iewort#ndex;
In the tessellation control language, :uilt9in varia:les are intrinsicall- declared as:
in gl!Her'ertex 4
vec; gl!Hosition;
float gl!Hoint)i.e;
8 gl!inIgl!GaxHatch'erticesJ;
in int gl!Hatch'ertices#n;
in int gl!Hrimitive#,;
in int gl!#nvocation#,;
out gl!Her'ertex 4
vec; gl!Hosition;
float gl!Hoint)i.e;
8 gl!outIJ;
atch out float gl!+ess"evel*uterI;J;
atch out float gl!+ess"evel#nnerI<J;
In the tessellation evaluation language, :uilt9in varia:les are intrinsicall- declared as:
in gl!Her'ertex 4
vec; gl!Hosition;
float gl!Hoint)i.e;
8 gl!inIgl!GaxHatch'erticesJ;
in int gl!Hatch'ertices#n;
1
in vec> gl!+essLoord;
atch in float gl!+ess"evel*uterI;J;
atch in float gl!+ess"evel#nnerI<J;
out gl!Her'ertex 4
vec; gl!Hosition;
float gl!Hoint)i.e;
8;
In the #ragent language, :uilt9in varia:les are intrinsicall- declared as:
in vec; gl!&ragLoord;
in bool gl!&ront&acing;
in float gl!Lli,istanceIJ;
in vec< gl!HointLoord;
in int gl!)amle#,;
in vec< gl!)amleHosition;
in int gl!)amleGas=#nIJ;
out float gl!&rag,eth;
out int gl!)amleGas=IJ;
Each o# the a:ove varia:les is discussed :elow.
0he varia:le gl_Vertex,D is a verte4 language in1ut varia:le that holds an integer inde4 #or the verte4, as
de#ined under E,hader In1utsF in section !.11.) EVar-ing Varia:lesF in the .1en23 2ra1hics ,-ste
,1eci#ication. @hile the varia:le gl_Vertex,D is alwa-s 1resent, its value is not alwa-s de#ined.
0he varia:le gl_,nstance,D is a verte4 language in1ut varia:le that holds the instance nu:er o# the
current 1riitive in an instanced draw call Bsee E,hader In1utsF in section !.11.) EVar-ing Varia:lesF in
the .1en23 2ra1hics ,-ste ,1eci#icationC. I# the current 1riitive does not coe #ro an instanced
draw call, the value o# gl_,nstance,D is =ero.
As an out1ut varia:le, gl_Position is intended #or writing the hoogeneous verte4 1osition. It can :e
written at an- tie during shader e4ecution. 0his value will :e used :- 1riitive asse:l-, cli11ing,
culling, and other #i4ed #unctionalit- o1erations, i# 1resent, that o1erate on 1riitives a#ter verte4
1rocessing has occurred. Its value is unde#ined a#ter the verte4 1rocessing stage i# the verte4 shader
e4ecuta:le does not write gl_Position, and it is unde#ined a#ter geoetr- 1rocessing i# the geoetr-
e4ecuta:le calls OmitVertexBC without having written gl_Position since the last OmitVertexBC Bor hasnJt
written it at allC. As an in1ut varia:le, gl_Position reads the out1ut written in the 1revious shader stage to
gl_Position.
As an out1ut varia:le, gl_Point!i0e is intended #or a shader to write the si=e o# the 1oint to :e rasteri=ed.
It is easured in 1i4els. I# gl_Point!i0e is not written to, its value is unde#ined in su:se<uent 1i1e stages.
As an in1ut varia:le, gl_Point!i0e reads the out1ut written in the 1revious shader stage to gl_Point!i0e .
11
0he varia:le gl_ClipDistance 1rovides the #orward co1ati:le echanis #or controlling user cli11ing.
0he eleent gl_ClipDistance5i6 s1eci#ies a cli1 distance #or each 1lane i. A distance o# $ eans the
verte4 is on the 1lane, a 1ositive distance eans the verte4 is inside the cli1 1lane, and a negative distance
eans the 1oint is outside the cli1 1lane. 0he cli1 distances will :e linearl- inter1olated across the
1riitive and the 1ortion o# the 1riitive with inter1olated distances less than $ will :e cli11ed.
0he gl_ClipDistance arra- is 1redeclared as unsi=ed and ust :e si=ed :- the shader either redeclaring it
with a si=e or inde4ing it onl- with integral constant e41ressions. 0his needs to si=e the arra- to include
all the cli1 1lanes that are ena:led via the .1en23 A5II i# the si=e does not include all ena:led 1lanes,
results are unde#ined. 0he si=e can :e at ost gl_7axClipDistances. 0he nu:er o# var-ing co1onents
Bsee gl_7axVar+ingComponents4 consued :- gl_ClipDistance will atch the si=e o# the arra-, no
atter how an- 1lanes are ena:led. 0he shader ust also set all values in gl_ClipDistance that have
:een ena:led via the .1en23 A5I, or results are unde#ined. Values written into gl_ClipDistance #or
1lanes that are not ena:led have no e##ect.
As an out1ut varia:le, gl_ClipDistance 1rovides the 1lace #or the shader to write these distances. As an
in1ut in all :ut the #ragent language, it reads the values written in the 1revious shader stage. In the
#ragent language, gl_ClipDistance arra- contains linearl- inter1olated values #or the verte4 values
written :- a shader to the gl_ClipDistance verte4 out1ut varia:le. .nl- eleents in this arra- that have
cli11ing ena:led will have de#ined values.
0he out1ut varia:le gl_Primitive,D is availa:le onl- in the geoetr- language and 1rovides a single
integer that serves as a 1riitive identi#ier. 0his is then availa:le to #ragent shaders as the #ragent
in1ut gl_Primitive,D, which will select the written 1riitive ID #ro the 1rovoking verte4 in the 1riitive
:eing shaded. I# a #ragent shader using gl_Primitive,D is active and a geoetr- shader is also active,
the geoetr- shader ust write to gl_Primitive,D or the #ragent shader in1ut gl_Primitive,D is
unde#ined. ,ee section !.1'.% E2eoetr- ,hader E4ecution EnvironentF Bunder E2eoetr- ,hader
.ut1utsFC and section '.&.! E,hader E4ecutionF Bunder E,hader In1utsFC o# the .1en23 2ra1hics ,-ste
,1eci#ication #or ore in#oration.
6or tessellation control and evaluation languages the in1ut varia:le gl_Primitive,D is #illed with the
nu:er o# 1riitives 1rocessed :- the shader since the current set o# rendering 1riitives was started.
6or the #ragent language, it is #illed with the value written to the gl_Primitive,D geoetr- shader out1ut
i# a geoetr- shader is 1resent. .therwise, it is assigned in the sae anner as with tessellation control
and evaluation shaders.
0he geoetr- language in1ut varia:le gl_Primitive,D,n :ehaves identicall- to the tessellation control and
evaluation language in1ut varia:le gl_Primitive,D.
0he in1ut varia:le gl_,nvocation,D is availa:le onl- in the tessellation control and geoetr- languages.
In the tessellation control shader, it identi#ies the nu:er o# the out1ut 1atch verte4 assigned to the
tessellation control shader invocation. In the geoetr- shader, it identi#ies the invocation nu:er
assigned to the geoetr- shader invocation. In :oth cases, gl_,nvocation,D is assigned integer values in
the range 50* -16, where is the nu:er o# out1ut 1atch vertices or geoetr- shader invocations 1er
1riitive.
0he out1ut varia:le gl_La+er is availa:le onl- in the geoetr- language, and is used to select a s1eci#ic
la-er Bor #ace and la-er o# a cu:e a1C o# a ulti9la-er #rae:u##er attachent. 0he actual la-er used will
coe #ro one o# the vertices in the 1riitive :eing shaded. @hich verte4 the la-er coes #ro is
12
unde#ined, so it is :est to write the sae la-er value #or all vertices o# a 1riitive. I# a shader staticall-
assigns a value to gl_La+er, la-ered rendering ode is ena:led. ,ee section !.1'.% E2eoetr- ,hader
E4ecution EnvironentF Bunder E2eoetr- ,hader .ut1utsFC and section %.%.) E3a-ered 6rae:u##ersF
o# the .1en23 2ra1hics ,-ste ,1eci#ication #or ore in#oration. I# a shader staticall- assigns a value
to gl_La+er, and there is an e4ecution 1ath through the shader that does not set gl_La+er, then the value o#
gl_La+er is unde#ined #or e4ecutions o# the shader that take that 1ath.
0he out1ut varia:le gl_La+er takes on a s1ecial value when used with an arra- o# cu:e a1 te4tures.
Instead o# onl- re#erring to the la-er, it is used to select a cu:e a1 #ace and a la-er. ,etting gl_La+er to
the value la+er=B9%ace will render to #ace %ace o# the cu:e de#ined in la-er la+er. 0he #ace values are
de#ined in 0a:le %.1! o# section %.%.) E3a-ered 6rae:u##ersF o# the .1en23 2ra1hics ,-ste
,1eci#ication, :ut re1eated :elow #or clarit-.
-ace Value Kesulting Iarget
$
+%T+@(%!L@9%!GDH!H*)#+#'%!T
1
+%T+@(%!L@9%!GDH!$%-D+#'%!T
!
+%T+@(%!L@9%!GDH!H*)#+#'%!U
'
+%T+@(%!L@9%!GDH!$%-D+#'%!U
%
+%T+@(%!L@9%!GDH!H*)#+#'%!V
*
+%T+@(%!L@9%!GDH!$%-D+#'%!V
6or e4a1le, to render to the 1ositive + cu:e a1 #ace located in the *th la-er o# the cu:e a1 arra-,
gl_La+er should :e set to C=B92.
0he out1ut varia:le gl_Vie/port,n$ex is availa:le onl- in the geoetr- language and 1rovides the inde4
o# the view1ort to which the ne4t 1riitive eitted #ro the geoetr- shader should :e drawn. 5riitives
generated :- the geoetr- shader will undergo view1ort trans#oration and scissor testing using the
view1ort trans#oration and scissor rectangle selected :- the value o# gl_Vie/port,n$ex. 0he view1ort
inde4 used will coe #ro one o# the vertices in the 1riitive :eing shaded. /owever, which verte4 the
view1ort inde4 coes #ro is i1leentation9de1endent, so it is :est to use the sae view1ort inde4 #or
all vertices o# the 1riitive. I# a geoetr- shader does not assign a value to gl_Vie/port,n$ex, view1ort
trans#or and scissor rectangle =ero will :e used. I# a geoetr- shader staticall- assigns a value to
gl_Vie/port,n$ex and there is a 1ath through the shader that does not assign a value to gl_Vie/port,n$ex,
the value o# gl_Vie/port,n$ex is unde#ined #or e4ecutions o# the shader that take that 1ath. ,ee section
!.1', under X2eoetr- ,hader .ut1utsX o# the .1en23 2ra1hics ,-ste ,1eci#ication B"ore 5ro#ileC #or
ore in#oration.
0he varia:le gl_Patc'Vertices,n is availa:le onl- in the tessellation control and evaluation languages. It
is an integer s1eci#-ing the nu:er o# vertices in the in1ut 1atch :eing 1rocessed :- the shader. A single
tessellation control or evaluation shader can read 1atches o# di##ering si=es, so the value o#
gl_Patc'Vertices,n a- di##er :etween 1atches.
0he out1ut varia:les gl_&essLevel(uter56 and gl_&essLevel,nner56 are availa:le onl- in the tessellation
control language. 0he values written to these varia:les are assigned to the corres1onding outer and inner
13
tessellation levels o# the out1ut 1atch. 0he- are used :- the tessellation 1riitive generator to control
1riitive tessellation and a- :e read :- tessellation evaluation shaders.
0he varia:le gl_&essCoor$ is availa:le onl- in the tessellation evaluation language. It s1eci#ies a three9
co1onent 3u*v*/4 vector identi#-ing the 1osition o# the verte4 :eing 1rocessed :- the shader relative to
the 1riitive :eing tessellated.
0he in1ut varia:les gl_&essLevel(uter56 and gl_&essLevel,nner56 are availa:le onl- in the tessellation
evaluation shader. I# a tessellation control shader is active, these varia:les are #illed with corres1onding
out1uts written :- the tessellation control shader. .therwise, the- are assigned with de#ault tessellation
levels s1eci#ied in section !.1! E0essellationF in the .1en23 2ra1hics ,-ste ,1eci#ication.
6ragent shaders out1ut values to the .1en23 1i1eline using declared out varia:les, the :uilt9in
varia:les gl_"ragDept' and gl_!ample7as., unless the discard stateent is e4ecuted.
0he #i4ed #unctionalit- co1uted de1th #or a #ragent a- :e o:tained :- reading gl_"ragCoor$.0*
descri:ed :elow.
@riting to gl_"ragDept' will esta:lish the de1th value #or the #ragent :eing 1rocessed. I# de1th
:u##ering is ena:led, and no shader writes gl_"ragDept', then the #i4ed #unction value #or de1th will :e
used as the #ragentNs de1th value. I# a shader staticall- assigns a value to gl_"ragDept', and there is an
e4ecution 1ath through the shader that does not set gl_"ragDept', then the value o# the #ragentNs de1th
a- :e unde#ined #or e4ecutions o# the shader that take that 1ath. 0hat is, i# the set o# linked #ragent
shaders staticall- contain a write to gl_"ragDept', then it is res1onsi:le #or alwa-s writing it.
I# a shader e4ecutes the discard ke-word, the #ragent is discarded, and the values o# an- user9de#ined
#ragent out1uts, gl_"ragDept', and gl_!ample7as. :ecoe irrelevant.
0he varia:le gl_"ragCoor$ is availa:le as an in1ut varia:le #ro within #ragent shaders and it holds the
window relative coordinates Bx, +, 0, 1D/C values #or the #ragent. I# ulti9sa1ling, this value can :e #or
an- location within the 1i4el, or one o# the #ragent sa1les. 0he use o# centroid does not #urther
restrict this value to :e inside the current 1riitive. 0his value is the result o# the #i4ed #unctionalit- that
inter1olates 1riitives a#ter verte4 1rocessing to generate #ragents. 0he 0 co1onent is the de1th value
that would :e used #or the #ragentNs de1th i# no shader contained an- writes to gl_"ragDept'. 0his is
use#ul #or invariance i# a shader conditionall- co1utes gl_"ragDept' :ut otherwise wants the #i4ed
#unctionalit- #ragent de1th.
6ragent shaders have access to the in1ut :uilt9in varia:le gl_"ront"acing* whose value is true i# the
#ragent :elongs to a #ront9#acing 1riitive. .ne use o# this is to eulate two9sided lighting :- selecting
one o# two colors calculated :- a verte4 or geoetr- shader.
0he values in gl_PointCoor$ are two9diensional coordinates indicating where within a 1oint 1riitive
the current #ragent is located, when 1oint s1rites are ena:led. 0he- range #ro $.$ to 1.$ across the
1oint. I# the current 1riitive is not a 1oint, or i# 1oint s1rites are not ena:led, then the values read #ro
gl_PointCoor$ are unde#ined.
6or :oth the in1ut arra- gl_!ample7as.,n56 and the out1ut arra- gl_!ample7as.56, :it < o# ask 7
Bgl_!ample7as.,n576 or gl_!ample7as.576C corres1onds to sa1le A2=79<. 0hese arra-s have
ceilBsG'!C eleents, where s is the a4iu nu:er o# color sa1les su11orted :- the i1leentation.
14
0he in1ut varia:le gl_!ample7as.,n indicates the set o# sa1les covered :- the 1riitive generating the
#ragent during ultisa1le rasteri=ation. It has a sa1le :it set i# and onl- i# the sa1le is considered
covered #or this #ragent shader invocation.
0he out1ut arra- gl_!ample7as.56 sets the sa1le ask #or the #ragent :eing 1rocessed. "overage #or
the current #ragent will :ecoe the logical A8D o# the coverage ask and the out1ut gl_!ample7as..
0his arra- ust :e si=ed in the #ragent shader either i1licitl- or e41licitl- to :e the sae si=e descri:ed
a:ove. I# the #ragent shader staticall- assigns a value to gl_!ample7as., the sa1le ask will :e
unde#ined #or an- arra- eleents o# an- #ragent shader invocations that #ail to assign a value. I# a
shader does not staticall- assign a value to gl_!ample7as., the sa1le ask has no e##ect on the
1rocessing o# a #ragent.
0he in1ut varia:le gl_!ample,D is #illed with the sa1le nu:er o# the sa1le currentl- :eing 1rocessed.
0his varia:le is in the range 0 to gl_um!amples-1, where gl_um!amples is the total nu:er o# sa1les
in the #rae:u##er, or 1 i# rendering to a non9ultisa1le #rae:u##er. An- static use o# this varia:le in a
#ragent shader causes the entire shader to :e evaluated 1er9sa1le.
0he in1ut varia:le gl_!amplePosition contains the 1osition o# the current sa1le within the ulti9sa1le
draw :u##er. 0he x and + co1onents o# gl_!amplePosition contain the su:91i4el coordinate o# the current
sa1le and will have values in the range $.$ to 1.$. An- static use o# this varia:le in a #ragent shader
causes the entire shader to :e evaluated 1er sa1le.
0he gl_PerVertex :lock can :e redeclared in a shader to e41licitl- indicate what su:set o# the #i4ed
1i1eline inter#ace will :e used. 0his is necessar- to esta:lish the inter#ace :etween ulti1le 1rogras.
6or e4a1le:
out gl!Her'ertex 4
vec; gl!Hosition; // will use gl!Hosition
float gl!Hoint)i.e; // will use gl!Hoint)i.e
vec; t; // error7 onl/ gl!Her'ertex members allowed
8; // no other members of gl!Her'ertex will be used
0his esta:lishes the out1ut inter#ace the shader will use with the su:se<uent 1i1eline stage. It ust :e a
su:set o# the :uilt9in e:ers o# gl_PerVertex.
I# a :uilt9in inter#ace :lock is redeclared, it ust a11ear in the shader :e#ore an- use o# an- e:er
included in the :uilt9in declaration, or a co1ilation error will result. It is also a co1ilation error to
redeclare the :lock ore than once or to redeclare a :uilt9in :lock and then use a e:er #ro that :uilt9
in :lock that was not included in the redeclaration. Also, i# a :uilt9in inter#ace :lock is redeclared, no
e:er o# the :uilt9in declaration can :e redeclared outside the :lock redeclaration. I# ulti1le shaders
using e:ers o# a :uilt9in :lock :elonging to the sae inter#ace are linked together in the sae
1rogra, the- ust all redeclare the :uilt9in :lock in the sae wa-, as descri:ed in section %.'.(
EInter#ace BlocksF #or inter#ace :lock atching, or a link error will result. It will also :e a link error i#
soe shaders in a 1rogra redeclare a s1eci#ic :uilt9in inter#ace :lock while another shader in that
1rogra does not redeclare that inter#ace :lock -et still uses a e:er o# that inter#ace :lock. I# a :uilt9
in :lock inter#ace is #ored across shaders in di##erent 1rogras, the shaders ust all redeclare the :uilt9
in :lock in the sae wa- Bas descri:ed #or a single 1rograC, or the values 1assed along the inter#ace are
unde#ined.
15
%.1.1 Compatibilit( .rofile 0uilt7In Language ariables
@hen using the co1ati:ilit- 1ro#ile, the 23 can 1rovide #i4ed #unctionalit- :ehavior #or the verte4 and
#ragent 1rograa:le 1i1eline stages. 6or e4a1le, i4ing a #i4ed #unctionalit- verte4 stage with a
1rograa:le #ragent stage.
0he #ollowing :uilt9in verte4, tessellation control, tessellation evaluation, and geoetr- out1ut varia:les
are availa:le to s1eci#- in1uts #or the su:se<uent 1rograa:le shader stage or the #i4ed #unctionalit-
#ragent stage. A 1articular one should :e written to i# an- #unctionalit- in a corres1onding #ragent
shader or #i4ed 1i1eline uses it or state derived #ro it. .therwise, :ehavior is unde#ined. 0he #ollowing
e:ers are added to the out1ut gl_PerVertex :lock in these languages:
out gl!Her'ertex 4 // art of the gl!Her'ertex bloc= described in C50
// in addition to other gl!Her'ertex members555
vec; gl!Lli'ertex;
vec; gl!&rontLolor;
vec; gl!9ac=Lolor;
vec; gl!&ront)econdar/Lolor;
vec; gl!9ac=)econdar/Lolor;
vec; gl!+exLoordIJ;
float gl!&og&ragLoord;
8;
0he out1ut varia:le gl_ClipVertex 1rovides a 1lace #or verte4 and geoetr- shaders to write the
coordinate to :e used with the user cli11ing 1lanes. @riting to gl_ClipDistance is the 1re#erred ethod
#or user cli11ing. It is an error #or the set o# shaders #oring a 1rogra to staticall- read or write :oth
gl_ClipVertex and gl_ClipDistance. I# neither gl_ClipVertex nor gl_ClipDistance is written, their values
are unde#ined and an- cli11ing against user cli1 1lanes is also unde#ined.
,iilarl- to what was 1reviousl- descri:ed #or the core 1ro#ile, the gl_PerVertex :lock can :e redeclared
in a shader to e41licitl- include these additional e:ers. 6or e4a1le:
out gl!Her'ertex 4
vec; gl!Hosition; // will use gl!Hosition
vec; gl!&rontLolor; // will consume gl!color in the fragment shader
vec; gl!9ac=Lolor;
vec; gl!+exLoordI>J; // > elements of gl!+exLoord will be used
8; // no other asects of the fixed interface will be used
0he user ust ensure the cli1 verte4 and user cli11ing 1lanes are de#ined in the sae coordinate s1ace.
7ser cli1 1lanes work 1ro1erl- onl- under linear trans#or. It is unde#ined what ha11ens under non9
linear trans#or.
I# a set o# shaders #oring a 1rogra that out1uts gl_Position contains no static write to gl_ClipVertex or
gl_ClipDistance* :ut the a11lication has re<uested cli11ing against user cli1 1lanes through the A5I, then
the coordinate written to gl_Position is used #or co1arison against the user cli1 1lanes. @riting to
gl_ClipDistance is the 1re#erred ethod #or user cli11ing. It is an error #or the set o# shaders #oring a
1rogra to staticall- read or write :oth gl_ClipVertex and gl_ClipDistance.
16
0he out1ut varia:les gl_"rontColor, gl"ront!econ$ar+Color, gl_<ac.Color, and gl<ac.!econ$ar+Color
assign 1riar- and secondar- colors #or #ront and :ack #aces o# 1riitives containing the verte4 :eing
1rocessed. 0he out1ut varia:le gl_&exCoor$ assigns te4ture coordinates #or the verte4 :eing 1rocessed.
6or gl_"og"ragCoor$, the value written will :e used as the EcF value in section '.11 E6ogF o# the
co1ati:ilit- 1ro#ile o# the .1en23 2ra1hics ,-ste ,1eci#ication, :- the #i4ed #unctionalit- 1i1eline.
6or e4a1le, i# the =9coordinate o# the #ragent in e-e s1ace is desired as EcF, then thatJs what the verte4
shader e4ecuta:le should write into gl_"og"ragCoor$.
As with all arra-s, indices used to su:scri1t gl_&exCoor$ ust either :e an integral constant e41ressions,
or this arra- ust :e re9declared :- the shader with a si=e. 0he si=e can :e at ost
gl_7ax&extureCoor$s. 7sing inde4es close to $ a- aid the i1leentation in 1reserving var-ing
resources. 0he redeclaration o# gl_&exCoor$ can also :e done at glo:al sco1e as, #or e4a1le:
in vec; gl!+exLoordI>J;
out vec; gl!+exLoordI;J;
B0his treatent is a s1ecial case #or gl_&exCoor$56, not a general ethod #or redeclaring e:ers o#
:locks.C It is a co1ilation error to redeclare gl_&exCoor$56 at glo:al sco1e i# there is a redeclaration o#
the corres1onding :uilt9in :lockI onl- one #or o# redeclaration is allowed within a shader Band hence
within a stage, as :lock redeclarations ust atch across all shaders using itC.
In the tessellation control, evaluation, and geoetr- shaders, the out1uts o# the 1revious stage descri:ed
a:ove are also availa:le in the in1ut gl_PerVertex :lock in these languages.
in gl!Her'ertex 4 // art of the gl!Her'ertex bloc= described in C50
// in addition to other gl!Her'ertex members555
vec; gl!Lli'ertex;
vec; gl!&rontLolor;
vec; gl!9ac=Lolor;
vec; gl!&ront)econdar/Lolor;
vec; gl!9ac=)econdar/Lolor;
vec; gl!+exLoordIJ;
float gl!&og&ragLoord;
8 gl!inIJ;
0hese can :e redeclared to esta:lish an e41licit 1i1eline inter#ace, the sae wa- as descri:ed a:ove #or
the out1ut :lock gl_PerVertex, and the in1ut redeclaration ust atch the out1ut redeclaration o# the
1revious stage. /owever, when a :uilt9in inter#ace :lock with an instance nae is redeclared Be.g., gl_inC,
the instance nae ust :e included in the redeclaration. It is an error to not include the :uilt9in instance
nae or to change its nae. 6or e4a1le,
in gl!Her'ertex 4
vec; gl!Lli'ertex;
vec; gl!&rontLolor;
8 gl!inIJ; // must be resent and must be gl!inIJ
0reatent o# gl_&exCoor$56 redeclaration is also identical to that descri:ed #or the out1ut :lock
gl_&exCoor$56 redeclaration.
17
0he #ollowing #ragent in1ut :lock is also availa:le in a #ragent shader when using the co1ati:ilit-
1ro#ile:
in gl!Her&ragment 4
in float gl!&og&ragLoord;
in vec; gl!+exLoordIJ;
in vec; gl!Lolor;
in vec; gl!)econdar/Lolor;
8;
0he values in gl_Color and gl_!econ$ar+Color will :e derived autoaticall- :- the s-ste #ro
gl_"rontColor* gl_<ac.Color* gl_"ront!econ$ar+Color* and gl_<ac.!econ$ar+Color :ased on which
#ace is visi:le in the 1riitive 1roducing the #ragent. I# #i4ed #unctionalit- is used #or verte4 1rocessing,
then gl_"og"ragCoor$ will either :e the =9coordinate o# the #ragent in e-e s1ace, or the inter1olation o#
the #og coordinate, as descri:ed in section '.11 E6ogF o# the co1ati:ilit- 1ro#ile o# the .1en23
2ra1hics ,-ste ,1eci#ication. 0he gl_&exCoor$56 values are the inter1olated gl_&exCoor$56 values
#ro a verte4 shader or the te4ture coordinates o# an- #i4ed 1i1eline :ased verte4 #unctionalit-.
Indices to the #ragent shader gl_&exCoor$ arra- are as descri:ed a:ove in the verte4 shader te4t.
As descri:ed a:ove #or the in1ut and out1ut gl_PerVertex :locks, the gl_Per"ragment :lock can :e
redeclared to create an e41licit inter#ace to another 1rogra. @hen atching these inter#aces :etween
se1arate 1rogras, e:ers in the gl_PerVertex out1ut :lock ust :e declared i# and onl- i# the
corres1onding #ragent9shader e:ers generated #ro the are 1resent in the gl_Per"ragment in1ut
:lock. 0hese atches are descri:ed in detail in section !.1% EVerte4 ,hadersF o# the .1en23 2ra1hics
,-ste ,1eci#ication B"o1ati:ilit- 5ro#ileC. I# the- donJt atch within a 1rogra, a link error will
result. I# the isatch is :etween two 1rogras, values 1assed :etween 1rogras are unde#ined. 7nlike
with all other :lock atching, the order o# declaration within gl_Per"ragment does not have to atch
across shaders and does not have to corres1ond with order o# declaration in a atching gl_PerVertex
redeclaration.
0he #ollowing #ragent out1ut varia:les are availa:le in a #ragent shader when using the co1ati:ilit-
1ro#ile:
out vec; gl!&ragLolor;
out vec; gl!&rag,ataIgl!Gax,raw9uffersJ;
@riting to gl_"ragColor s1eci#ies the #ragent color that will :e used :- the su:se<uent #i4ed
#unctionalit- 1i1eline. I# su:se<uent #i4ed #unctionalit- consues #ragent color and an e4ecution o# the
#ragent shader e4ecuta:le does not write a value to gl_"ragColor then the #ragent color consued is
unde#ined.
0he varia:le gl_"ragData is an arra-. @riting to gl_"ragData5n6 s1eci#ies the #ragent data that will :e
used :- the su:se<uent #i4ed #unctionalit- 1i1eline #or data n. I# su:se<uent #i4ed #unctionalit- consues
#ragent data and an e4ecution o# a #ragent shader e4ecuta:le does not write a value to it, then the
#ragent data consued is unde#ined.
I# a shader staticall- assigns a value to gl_"ragColor, it a- not assign a value to an- eleent o#
gl_"ragData. I# a shader staticall- writes a value to an- eleent o# gl_"ragData, it a- not assign a
value to gl_"ragColor. 0hat is, a shader a- assign values to either gl_"ragColor or gl_"ragData, :ut
not :oth. ;ulti1le shaders linked together ust also consistentl- write Dust one o# these varia:les.
18
,iilarl-, i# user9declared out1ut varia:les are in use Bstaticall- assigned toC, then the :uilt9in varia:les
gl_"ragColor and gl_"ragData a- not :e assigned to. 0hese incorrect usages all generate co1ile tie
errors.
I# a shader e4ecutes the discard ke-word, the #ragent is discarded, and the values o# gl_"ragDept' and
gl_"ragColor :ecoe irrelevant.
%.2 Compatibilit( .rofile erte- Shader 0uilt7In Inputs
0he #ollowing 1redeclared in1ut naes can :e used #ro within a verte4 shader to access the current
values o# .1en23 state when using the co1ati:ilit- 1ro#ile.
in vec; gl!Lolor;
in vec; gl!)econdar/Lolor;
in vec> gl!$ormal;
in vec; gl!'ertex;
in vec; gl!Gulti+exLoord?;
in vec; gl!Gulti+exLoord0;
in vec; gl!Gulti+exLoord<;
in vec; gl!Gulti+exLoord>;
in vec; gl!Gulti+exLoord;;
in vec; gl!Gulti+exLoordE;
in vec; gl!Gulti+exLoordB;
in vec; gl!Gulti+exLoordC;
in float gl!&ogLoord;
%.# 0uilt7In Constants
0he #ollowing :uilt9in constants are 1rovided to all shaders. 0he actual values used are i1leentation
de1endent, :ut ust :e at least the value shown.
//
// #mlementation2deendent constants5 +he examle values below
// are the minimum values allowed for these maximums5
//
const int gl!Gax'ertexDttribs 3 0B;
const int gl!Gax'ertex@niformLomonents 3 0?<;;
const int gl!Gax'ar/ingLomonents 3 B?;
const int gl!Gax'ertex*ututLomonents 3 B;;
const int gl!Gax-eometr/#nutLomonents 3 B;;
const int gl!Gax-eometr/*ututLomonents 3 0<F;
const int gl!Gax&ragment#nutLomonents 3 0<F;
const int gl!Gax'ertex+exture#mage@nits 3 0B;
const int gl!GaxLombined+exture#mage@nits 3 F?;
const int gl!Gax+exture#mage@nits 3 0B;
19
const int gl!Gax#mage@nits 3 F;
const int gl!GaxLombined#mage@nitsDnd&ragment*ututs 3 F;
const int gl!Gax#mage)amles 3 ?;
const int gl!Gax'ertex#mage@niforms 3 ?;
const int gl!Gax+essLontrol#mage@niforms 3 ?;
const int gl!Gax+ess%valuation#mage@niforms 3 ?;
const int gl!Gax-eometr/#mage@niforms 3 ?;
const int gl!Gax&ragment#mage@niforms 3 ?;
const int gl!GaxLombined#mage@niforms 3 ?;
const int gl!Gax&ragment@niformLomonents 3 0?<;;
const int gl!Gax,raw9uffers 3 F;
const int gl!GaxLli,istances 3 F;
const int gl!Gax-eometr/+exture#mage@nits 3 0B;
const int gl!Gax-eometr/*utut'ertices 3 <EB;
const int gl!Gax-eometr/+otal*ututLomonents 3 0?<;;
const int gl!Gax-eometr/@niformLomonents 3 0?<;;
const int gl!Gax-eometr/'ar/ingLomonents 3 B;;
11
const int gl!Gax+essLontrol#nutLomonents 3 0<F;
const int gl!Gax+essLontrol*ututLomonents 3 0<F;
const int gl!Gax+essLontrol+exture#mage@nits 3 0B;
const int gl!Gax+essLontrol@niformLomonents 3 0?<;;
const int gl!Gax+essLontrol+otal*ututLomonents 3 ;?AB;
const int gl!Gax+ess%valuation#nutLomonents 3 0<F;
const int gl!Gax+ess%valuation*ututLomonents 3 0<F;
const int gl!Gax+ess%valuation+exture#mage@nits 3 0B;
const int gl!Gax+ess%valuation@niformLomonents 3 0?<;;
const int gl!Gax+essHatchLomonents 3 0<?;
const int gl!GaxHatch'ertices 3 ><;
const int gl!Gax+ess-en"evel 3 B;;
const int gl!Gax'ieworts 3 0B;
const int gl!Gax'ertex@niform'ectors 3 <EB;
const int gl!Gax&ragment@niform'ectors 3 <EB;
const int gl!Gax'ar/ing'ectors 3 0E;
const int gl!Gax'ertexDtomicLounters 3 ?;
const int gl!Gax+essLontrolDtomicLounters 3 ?;
const int gl!Gax+ess%valuationDtomicLounters 3 ?;
const int gl!Gax-eometr/DtomicLounters 3 ?;
const int gl!Gax&ragmentDtomicLounters 3 F;
const int gl!GaxLombinedDtomicLounters 3 F;
const int gl!GaxDtomicLounter9indings 3 0;
const int gl!Gax'ertexDtomicLounter9uffers 3 ?;
const int gl!Gax+essLontrolDtomicLounter9uffers 3 ?;
const int gl!Gax+ess%valuationDtomicLounter9uffers 3 ?;
const int gl!Gax-eometr/DtomicLounter9uffers 3 ?;
const int gl!Gax&ragmentDtomicLounter9uffers 3 0;
const int gl!GaxLombinedDtomicLounter9uffers 3 0;
const int gl!GaxDtomicLounter9uffer)i.e 3 0B>F;;
const int gl!GinHrogram+exel*ffset 3 2F;
const int gl!GaxHrogram+exel*ffset 3 C;
0he constant gl_7axVar+ing"loats is reoved in the core 1ro#ile, use gl_7axVar+ingComponents
instead.
%.#.1 Compatibilit( .rofile 0uilt7In Constants
const int gl!Gax+exture@nits 3 <;
const int gl!Gax+extureLoords 3 F;
const int gl!GaxLliHlanes 3 F;
const int gl!Gax'ar/ing&loats 3 B?;
111
%.! 0uilt7In 5niform State
As an aid to accessing .1en23 1rocessing state, the #ollowing uni#or varia:les are :uilt into the
.1en23 ,hading 3anguage.
//
// ,eth range in window coordinates7
// section <50;50 Lontrolling the 'iewort in the
// *en-" -rahics )/stem )ecification5
//
struct gl!,eth(angeHarameters 4
float near; // n
float far; // f
float diff; // f 2 n
8;
uniform gl!,eth(angeHarameters gl!,eth(ange;
uniform int gl!$um)amles;
%.!.1 Compatibilit( .rofile State
0hese varia:les are 1resent onl- in the co1ati:ilit- 1ro#ile.
//
// comatibilit/ rofile onl/
//
uniform mat; gl!Godel'iewGatrix;
uniform mat; gl!Hro:ectionGatrix;
uniform mat; gl!Godel'iewHro:ectionGatrix;
uniform mat; gl!+extureGatrixIgl!Gax+extureLoordsJ;
//
//
uniform mat> gl!$ormalGatrix; // transose of the inverse of the
// uer leftmost >x> of gl!Godel'iewGatrix
uniform mat; gl!Godel'iewGatrix#nverse;
uniform mat; gl!Hro:ectionGatrix#nverse;
uniform mat; gl!Godel'iewHro:ectionGatrix#nverse;
uniform mat; gl!+extureGatrix#nverseIgl!Gax+extureLoordsJ;
uniform mat; gl!Godel'iewGatrix+ransose;
uniform mat; gl!Hro:ectionGatrix+ransose;
uniform mat; gl!Godel'iewHro:ectionGatrix+ransose;
uniform mat; gl!+extureGatrix+ransoseIgl!Gax+extureLoordsJ;
uniform mat; gl!Godel'iewGatrix#nverse+ransose;
uniform mat; gl!Hro:ectionGatrix#nverse+ransose;
112
uniform mat; gl!Godel'iewHro:ectionGatrix#nverse+ransose;
uniform mat; gl!+extureGatrix#nverse+ransoseIgl!Gax+extureLoordsJ;
//
//
uniform float gl!$ormal)cale;
//
//
uniform vec; gl!LliHlaneIgl!GaxLliHlanesJ;
//
//
struct gl!HointHarameters 4
float si.e;
float si.eGin;
float si.eGax;
float fade+hreshold)i.e;
float distanceLonstantDttenuation;
float distance"inearDttenuation;
float distanceWuadraticDttenuation;
8;

uniform gl!HointHarameters gl!Hoint;
//
//
struct gl!GaterialHarameters 4
vec; emission; // %cm
vec; ambient; // Dcm
vec; diffuse; // ,cm
vec; secular; // )cm
float shininess; // )rm
8;
uniform gl!GaterialHarameters gl!&rontGaterial;
uniform gl!GaterialHarameters gl!9ac=Gaterial;
113
//
//
struct gl!"ight)ourceHarameters 4
vec; ambient; // Dcli
vec; diffuse; // ,cli
vec; secular; // )cli
vec; osition; // Hli
vec; half'ector; // ,erived1 Oi
vec> sot,irection; // )dli
float sot%xonent; // )rli
float sotLutoff; // Lrli
// (range1 I?5?7A?5?J7 0F?5?)
float sotLosLutoff; // ,erived1 cos(Lrli)
// (range1 I05?7?5?J7205?)
float constantDttenuation; // S?
float linearDttenuation; // S0
float quadraticDttenuation;// S<
8;
uniform gl!"ight)ourceHarameters gl!"ight)ourceIgl!Gax"ightsJ;
struct gl!"ightGodelHarameters 4
vec; ambient; // Dcs
8;
uniform gl!"ightGodelHarameters gl!"ightGodel;
//
//
// ,erived state from roducts of light and material5
//
struct gl!"ightGodelHroducts 4
vec; sceneLolor; // ,erived5 %cm K Dcm P Dcs
8;
uniform gl!"ightGodelHroducts gl!&ront"ightGodelHroduct;
uniform gl!"ightGodelHroducts gl!9ac="ightGodelHroduct;
struct gl!"ightHroducts 4
vec; ambient; // Dcm P Dcli
vec; diffuse; // ,cm P ,cli
vec; secular; // )cm P )cli
8;
uniform gl!"ightHroducts gl!&ront"ightHroductIgl!Gax"ightsJ;
uniform gl!"ightHroducts gl!9ac="ightHroductIgl!Gax"ightsJ;
114
//
//
uniform vec; gl!+exture%nvLolorIgl!Gax+exture@nitsJ;
uniform vec; gl!%/eHlane)Igl!Gax+extureLoordsJ;
uniform vec; gl!%/eHlane+Igl!Gax+extureLoordsJ;
uniform vec; gl!%/eHlane(Igl!Gax+extureLoordsJ;
uniform vec; gl!%/eHlaneWIgl!Gax+extureLoordsJ;
uniform vec; gl!*b:ectHlane)Igl!Gax+extureLoordsJ;
uniform vec; gl!*b:ectHlane+Igl!Gax+extureLoordsJ;
uniform vec; gl!*b:ectHlane(Igl!Gax+extureLoordsJ;
uniform vec; gl!*b:ectHlaneWIgl!Gax+extureLoordsJ;
//
//
struct gl!&ogHarameters 4
vec; color;
float densit/;
float start;
float end;
float scale; // ,erived1 05? / (end 2 start)
8;

uniform gl!&ogHarameters gl!&og;
115
$ 0uilt7in /unctions
0he .1en23 ,hading 3anguage de#ines an assortent o# :uilt9in convenience #unctions #or scalar and
vector o1erations. ;an- o# these :uilt9in #unctions can :e used in ore than one t-1e o# shader, :ut soe
are intended to 1rovide a direct a11ing to hardware and so are availa:le onl- #or a s1eci#ic t-1e o#
shader.
0he :uilt9in #unctions :asicall- #all into three categories:
0he- e41ose soe necessar- hardware #unctionalit- in a convenient wa- such as accessing a te4ture
a1. 0here is no wa- in the language #or these #unctions to :e eulated :- a shader.
0he- re1resent a trivial o1eration Bcla1, i4, etc.C that is ver- si1le #or the user to write, :ut the-
are ver- coon and a- have direct hardware su11ort. It is a ver- hard 1ro:le #or the co1iler to
a1 e41ressions to co1le4 asse:ler instructions.
0he- re1resent an o1eration gra1hics hardware is likel- to accelerate at soe 1oint. 0he trigonoetr-
#unctions #all into this categor-.
;an- o# the #unctions are siilar to the sae naed ones in coon " li:raries, :ut the- su11ort vector
in1ut as well as the ore traditional scalar in1ut.
A11lications should :e encouraged to use the :uilt9in #unctions rather than do the e<uivalent co1utations
in their own shader code since the :uilt9in #unctions are assued to :e o1tial Be.g., 1erha1s su11orted
directl- in hardwareC.
7ser code can re1lace :uilt9in #unctions with their own i# the- choose, :- si1l- re9declaring and de#ining
the sae nae and arguent list. Because :uilt9in #unctions are in a ore outer sco1e than user :uilt9in
#unctions, doing this will hide all :uilt9in #unctions with the sae nae as the re9declared #unction.
@hen the :uilt9in #unctions are s1eci#ied :elow, where the in1ut arguents Band corres1onding out1utC
can :e float, vec!, vec3, or vec4, gen&+pe is used as the arguent. @here the in1ut arguents Band
corres1onding out1utC can :e int, ivec!, ivec3, or ivec4, gen,&+pe is used as the arguent. @here the
in1ut arguents Band corres1onding out1utC can :e uint, uvec!, uvec3, or uvec4, genE&+pe is used as the
arguent. @here the in1ut arguents Bor corres1onding out1utC can :e ool, vec!, vec3, or vec4,
gen<&+pe is used as the arguent. @here the in1ut arguents Band corres1onding out1utC can :e doule,
dvec!, dvec3, dvec4, genD&+pe is used as the arguent. 6or an- s1eci#ic use o# a #unction, the actual
t-1es su:stituted #or gen&+pe, gen,&+pe, genE&+pe* or gen<&+pe have to have the sae nu:er o#
co1onents #or all arguents and #or the return t-1e. ,iilarl-, mat is used #or an- atri4 :asic t-1e
with single91recision co1onents and $mat is used #or an- atri4 :asic t-1e with dou:le91recision
co1onents.
116
8 !ui%t+in ,unction"
$.1 1ngle and Trigonometr( /unctions
6unction 1araeters s1eci#ied as angle are assued to :e in units o# radians. In no case will an- o# these
#unctions result in a divide :- =ero error. I# the divisor o# a ratio is $, then results will :e unde#ined.
0hese all o1erate co1onent9wise. 0he descri1tion is 1er co1onent.
S(nta- ,escription
gen0-1e radians Bgen0-1e $egreesC
"onverts $egrees to radians, i.e.,

1($
$egrees
gen0-1e degrees Bgen0-1e ra$iansC
"onverts ra$ians to degrees, i.e.,
1($
ra$ians
gen0-1e sin Bgen0-1e angleC 0he standard trigonoetric sine #unction.
gen0-1e cos Bgen0-1e angleC 0he standard trigonoetric cosine #unction.
gen0-1e tan Bgen0-1e angleC 0he standard trigonoetric tangent.
gen0-1e asin Bgen0-1e xC Arc sine. Returns an angle whose sine is x. 0he range
o# values returned :- this #unction is
[
!
*
!
]
Results are unde#ined i# x1.
gen0-1e acos Bgen0-1e xC Arc cosine. Returns an angle whose cosine is x. 0he
range o# values returned :- this #unction is [$, \.
gen0-1e atan Bgen0-1e +, gen0-1e xC Arc tangent. Returns an angle whose tangent is +Dx. 0he
signs o# x and + are used to deterine what <uadrant the
angle is in. 0he range o# values returned :- this
#unction is [* ] . Results are unde#ined i# x and
+ are :oth $.
gen0-1e atan Bgen0-1e +_over_xC Arc tangent. Returns an angle whose tangent is
+_over_x. 0he range o# values returned :- this #unction
is
[
!
*
!
]
.
117
S(nta- ,escription
gen0-1e sinh Bgen0-1e xC Returns the h-1er:olic sine #unction
e
x
e
x
!
gen0-1e cosh Bgen0-1e xC Returns the h-1er:olic cosine #unction
e
x
e
x
!
gen0-1e tanh Bgen0-1e xC Returns the h-1er:olic tangent #unction
sinh x
cosh x
gen0-1e asinh Bgen0-1e xC Arc h-1er:olic sineI returns the inverse o# sinh.
gen0-1e acosh Bgen0-1e xC Arc h-1er:olic cosineI returns the non9negative inverse
o# cosh. Results are unde#ined i# x R 1.
gen0-1e atanh Bgen0-1e xC Arc h-1er:olic tangentI returns the inverse o# tanh.
118
$.2 *-ponential /unctions
S(nta- ,escription
gen0-1e pow Bgen0-1e x, gen0-1e +C Returns x raised to the + 1ower, i.e., x
+
Results are unde#ined i# x F 0.
Results are unde#ined i# x > 0 and + F> 0.
gen0-1e exp Bgen0-1e xC Returns the natural e41onentiation o# x, i.e., e
x
.
gen0-1e log Bgen0-1e xC Returns the natural logarith o# x* i.e., returns the value
+ which satis#ies the e<uation x T e
+
.
Results are unde#ined i# x F> 0.
gen0-1e exp! Bgen0-1e xC Returns ! raised to the x 1ower, i.e., !
x
gen0-1e log! Bgen0-1e xC Returns the :ase ! logarith o# x* i.e., returns the value
+ which satis#ies the e<uation x=!
+
gen0-1e sNrt Bgen0-1e xC
genD0-1e sNrt BgenD0-1e xC
Returns
x .
Results are unde#ined i# x F 0.
gen0-1e inversesNrt Bgen0-1e xC
genD0-1e inversesNrt BgenD0-1e xC
Returns
1
x
.
119
$.# Common /unctions
S(nta- ,escription
gen0-1e as Bgen0-1e xC
genI0-1e as BgenI0-1e xC
genD0-1e as BgenD0-1e xC
Returns x i# x ST $, otherwise it returns ]x.
gen0-1e sign Bgen0-1e xC
genI0-1e sign BgenI0-1e xC
genD0-1e sign BgenD0-1e xC
Returns 1.$ i# x S $, $.$ i# x T $, or ]1.$ i# x R $.
gen0-1e floor Bgen0-1e xC
genD0-1e floor BgenD0-1e xC
Returns a value e<ual to the nearest integer that is less
than or e<ual to x.
gen0-1e trunc Bgen0-1e xC
genD0-1e trunc BgenD0-1e xC
Returns a value e<ual to the nearest integer to x whose
a:solute value is not larger than the a:solute value o# x.
gen0-1e round Bgen0-1e xC
genD0-1e round BgenD0-1e xC
Returns a value e<ual to the nearest integer to x. 0he
#raction $.* will round in a direction chosen :- the
i1leentation, 1resua:l- the direction that is #astest.
0his includes the 1ossi:ilit- that roundBxC returns the
sae value as roundOvenBxC #or all values o# x.
gen0-1e roundOven Bgen0-1e xC
genD0-1e roundOven BgenD0-1e xC
Returns a value e<ual to the nearest integer to x. A
#ractional 1art o# $.* will round toward the nearest even
integer. BBoth '.* and %.* #or 4 will return %.$.C
gen0-1e ceil Bgen0-1e xC
genD0-1e ceil BgenD0-1e xC
Returns a value e<ual to the nearest integer that is
greater than or e<ual to x.
gen0-1e fract Bgen0-1e xC
genD0-1e fract BgenD0-1e xC
Returns x ] floor BxC.
gen0-1e mod Bgen0-1e x, #loat +C
gen0-1e mod Bgen0-1e x, gen0-1e +C
genD0-1e mod BgenD0-1e x, dou:le +C
genD0-1e mod BgenD0-1e x, genD0-1e +C
;odulus. Returns x ] + floor BxG+C.
12
S(nta- ,escription
gen0-1e modf Bgen0-1e x, out gen0-1e iC
genD0-1e modf BgenD0-1e x,
out genD0-1e iC
Returns the #ractional 1art o# x and sets i to the integer
1art Bas a whole nu:er #loating 1oint valueC. Both the
return value and the out1ut 1araeter will have the sae
sign as x.
gen0-1e min Bgen0-1e x, gen0-1e +C
gen0-1e min Bgen0-1e x, #loat +C
genD0-1e min BgenD0-1e x, genD0-1e +C
genD0-1e min BgenD0-1e x, dou:le +C
genI0-1e min BgenI0-1e x, genI0-1e +C
genI0-1e min BgenI0-1e x, int +C
gen70-1e min Bgen70-1e x, gen70-1e +C
gen70-1e min Bgen70-1e x, uint +C
Returns + i# + R x, otherwise it returns x.
gen0-1e max Bgen0-1e x, gen0-1e +C
gen0-1e max Bgen0-1e x, #loat +C
genD0-1e max BgenD0-1e x, genD0-1e +C
genD0-1e max BgenD0-1e x, dou:le +C
genI0-1e max BgenI0-1e x, genI0-1e +C
genI0-1e max BgenI0-1e x, int +C
gen70-1e max Bgen70-1e x, gen70-1e +C
gen70-1e max Bgen70-1e x, uint +C
Returns + i# x R +, otherwise it returns x.
121
S(nta- ,escription
gen0-1e clamp Bgen0-1e x,
gen0-1e minVal,
gen0-1e maxValC
#loat minVal,
#loat maxValC
genD0-1e clamp BgenD0-1e x,
genD0-1e minVal,
genD0-1e maxValC
genD0-1e clamp BgenD0-1e x,
dou:le minVal,
dou:le maxValC
genI0-1e clamp BgenI0-1e x,
genI0-1e minVal,
genI0-1e maxValC
genI0-1e clamp BgenI0-1e x,
int minVal,
int maxValC
gen70-1e minVal,
gen70-1e maxValC
uint minVal,
uint maxValC
Returns min Bmax Bx, minValC, maxValC.
Results are unde#ined i# minVal S maxVal.
gen0-1e mix Bgen0-1e x,
gen0-1e +,
gen0-1e aC
gen0-1e +,
#loat aC
genD0-1e mix BgenD0-1e x,
genD0-1e +,
genD0-1e aC
genD0-1e +,
dou:le aC
Returns the linear :lend o# x and +* i.e.,
x1a+a
122
S(nta- ,escription
gen0-1e -,
genB0-1e aC
genD0-1e -,
genB0-1e aC
,elects which vector each returned co1onent coes
#ro. 6or a co1onent o# a that is false, the
corres1onding co1onent o# x is returned. 6or a
co1onent o# a that is true, the corres1onding
co1onent o# + is returned. "o1onents o# x and + that
are not selected are allowed to :e invalid #loating 1oint
values and will have no e##ect on the results. 0hus, this
1rovides di##erent #unctionalit- than, #or e4a1le,
gen0-1e mixBgen0-1e x, gen0-1e +, gen0-1eBaCC
where a is a Boolean vector.
gen0-1e step Bgen0-1e e$ge, gen0-1e xC
gen0-1e step B#loat e$ge, gen0-1e xC
genD0-1e step BgenD0-1e e$ge,
genD0-1e xC
genD0-1e step Bdou:le e$ge, genD0-1e xC
Returns $.$ i# x R e$ge, otherwise it returns 1.$.
gen0-1e smoothstep Bgen0-1e e$ge0,
gen0-1e e$ge1,
gen0-1e xC
gen0-1e smoothstep B#loat e$ge0,
#loat e$ge1,
gen0-1e xC
genD0-1e smoothstep BgenD0-1e e$ge0,
genD0-1e e$ge1,
genD0-1e xC
genD0-1e smoothstep Bdou:le e$ge0,
dou:le e$ge1,
genD0-1e xC
Returns $.$ i# x RT e$ge0 and 1.$ i# x ST e$ge1 and
1er#ors sooth /erite inter1olation :etween $ and 1
when e$ge0 R x R e$ge1. 0his is use#ul in cases where
-ou would want a threshold #unction with a sooth
transition. 0his is e<uivalent to:
gen0-1e tI
t T cla1 BB4 ] edge$C G Bedge1 ] edge$C, $, 1CI
return t H t H B' ] ! H tCI
BAnd siilarl- #or dou:les.C
Results are un$e%ine$ i% e$ge0 G> e$ge1.
genB0-1e isnan Bgen0-1e xC
genB0-1e isnan BgenD0-1e xC
Returns true i# x holds a 8a8. Returns false otherwise.
Alwa-s returns false i# 8a8s are not i1leented.
genB0-1e isinf Bgen0-1e xC
genB0-1e isinf BgenD0-1e xC
Returns true i# x holds a 1ositive in#init- or negative
in#init-. Returns false otherwise.
genI0-1e float#itsIo(nt Bgen0-1e valueC
gen70-1e float#itsIoUint Bgen0-1e valueC
Returns a signed or unsigned integer value re1resenting
the encoding o# a #loating91oint value. 0he #loating9
1oint valueJs :it9level re1resentation is 1reserved.
123
S(nta- ,escription
gen0-1e int#itsIo-loat BgenI0-1e valueC
gen0-1e uint#itsIo-loat Bgen70-1e valueC
Returns a #loating91oint value corres1onding to a signed
or unsigned integer encoding o# a #loating91oint value.
I# a 8a8 is 1assed in, it will not signal, and the resulting
#loating 1oint value is uns1eci#ied. I# an In# is 1assed in,
the resulting #loating91oint value is the corres1onding
In#.
gen0-1e fma Bgen0-1e a, gen0-1e #,
gen0-1e cC
genD0-1e fma BgenD0-1e a, genD0-1e #,
genD0-1e cC
"o1utes and returns a=# 9 c.
In uses where the return value is eventuall- consued :-
a varia:le declared as precise:
fmaBC is considered a single o1eration, whereas the
e41ression EaH# L cF consued :- a varia:le
declared precise is considered two o1erations.
0he 1recision o# fmaBC can di##er #ro the 1recision
o# the the e41ression EaH# L cF.
fmaBC will :e co1uted with the sae 1recision as
another fmaBC consued :- a precise varia:le,
giving invariant results #or the sae in1ut values o#
a, #, and c.
.therwise, in the a:sence o# precise consu1tion, there
are no s1ecial constraints on the nu:er o# o1erations or
di##erence in 1recision :etween fmaBC and the e41ression
EaH# L cF.
gen0-1e frexp Bgen0-1e x,
out genI0-1e expC
genD0-1e frexp BgenD0-1e x,
out genI0-1e expC
,1lits x into a #loating91oint signi#icand in the range
[$.*, 1.$C and an integral e41onent o# two, such that:
x=signi%ican$!
exponent
0he signi#icand is returned :- the #unction and the
e41onent is returned in the 1araeter exp. 6or a
#loating91oint value o# =ero, the signi#icant and e41onent
are :oth =ero. 6or a #loating91oint value that is an
in#init- or is not a nu:er, the results are unde#ined.
gen0-1e ldexp Bgen0-1e x,
in genI0-1e expC
genD0-1e ldexp BgenD0-1e x,
in genI0-1e expC
Builds a #loating91oint nu:er #ro x and the
corres1onding integral e41onent o# two in exp, returning:
signi%ican$!
exponent
I# this 1roduct is too large to :e re1resented in the
#loating91oint t-1e, the result is unde#ined.
124
125
$.! /loating7.oint .ac3 and 5npac3 /unctions
0hese #unctions do not o1erate co1onent9wise, rather as descri:ed in each case.
S(nta- ,escription
uint packUnorm!x1+ Bvec! vC
uint pack,norm!x1+ Bvec! vC
uint packUnorm4x\ Bvec% vC
uint pack,norm4x\ Bvec% vC
6irst, converts each co1onent o# the norali=ed
#loating91oint value v into (9 or 1+9:it integer values.
0hen, the results are 1acked into the returned '!9:it
unsigned integer.
0he conversion #or co1onent c o# v to #i4ed 1oint is
done as #ollows:
packUnorm!x1+: roundBcla1Bc, $, L1C H +**'*.$C
pack,norm!x1+D roundBcla1Bcv, 91, L1C H
'!)+).$C
packUnorm4x\: roundBcla1Bc, $, L1C H !**.$C
pack,norm4x\: roundBcla1Bc, 91, L1C H 1!).$C
0he #irst co1onent o# the vector will :e written to the
least signi#icant :its o# the out1utI the last co1onent
will :e written to the ost signi#icant :its.
vec! unpackUnorm!x1+ Buint pC
vec! unpack,norm!x1+ Buint pC
vec% unpackUnorm4x\ Buint pC
vec% unpack,norm4x\ Buint pC
6irst, un1acks a single '!9:it unsigned integer p into a
1air o# 1+9:it unsigned integers, #our (9:it unsigned
integers, or #our (9:it signed integers. 0hen, each
co1onent is converted to a norali=ed #loating91oint
value to generate the returned two9 or #our9co1onent
vector.
0he conversion #or un1acked #i4ed91oint value % to
#loating 1oint is done as #ollows:
unpackUnorm!x1+D % G +**'*.$
unpack,norm!x1+D cla1B% G '!)+).$, 91, L1C
unpackUnorm4x\D % G !**.$
unpack,norm4x\D cla1B% G 1!).$, 91, L1C
0he #irst co1onent o# the returned vector will :e
e4tracted #ro the least signi#icant :its o# the in1utI the
last co1onent will :e e4tracted #ro the ost
signi#icant :its.
126
S(nta- ,escription
dou:le pack)oule!x3! Buvec! vC Returns a dou:le91recision value o:tained :- 1acking
the co1onents o# v into a +%9:it value. I# an IEEE )*%
In# or 8a8 is created, it will not signal, and the resulting
#loating 1oint value is uns1eci#ied. .therwise, the :it9
level re1resentation o# v is 1reserved. 0he #irst vector
co1onent s1eci#ies the '! least signi#icant :itsI the
second co1onent s1eci#ies the '! ost signi#icant :its.
uvec! unpack)oule!x3! Bdou:le vC Returns a two9co1onent unsigned integer vector
re1resentation o# v. 0he :it9level re1resentation o# v is
1reserved. 0he #irst co1onent o# the vector contains
the '! least signi#icant :its o# the dou:leI the second
co1onent consists the '! ost signi#icant :its.
uint pack*alf!x1+ Bvec! vC Returns an unsigned integer o:tained :- converting the
co1onents o# a two9co1onent #loating91oint vector to
the 1+9:it #loating91oint re1resentation #ound in the
.1en23 ,1eci#ication, and then 1acking these two 1+9
:it integers into a '!9:it unsigned integer.
0he #irst vector co1onent s1eci#ies the 1+ least9
signi#icant :its o# the resultI the second co1onent
s1eci#ies the 1+ ost9signi#icant :its.
vec! unpack*alf!x1+ Buint vC Returns a two9co1onent #loating91oint vector with
co1onents o:tained :- un1acking a '!9:it unsigned
integer into a 1air o# 1+9:it values, inter1reting those
values as 1+9:it #loating91oint nu:ers according to the
.1en23 ,1eci#ication, and converting the to '!9:it
#loating91oint values.
0he #irst co1onent o# the vector is o:tained #ro the
1+ least9signi#icant :its o# vI the second co1onent is
o:tained #ro the 1+ ost9signi#icant :its o# v.
127
$.& Geometric /unctions
0hese o1erate on vectors as vectors, not co1onent9wise.
S(nta- ,escription
#loat length Bgen0-1e xC
dou:le length BgenD0-1e xC
Returns the length o# vector x, i.e.,
x[ $]
!
x[ 1]
!
...
#loat distance Bgen0-1e p0, gen0-1e p1C
dou:le distance BgenD0-1e p0,
genD0-1e p1C
Returns the distance :etween p0 and p1, i.e.,
length Bp0 : p1C
#loat dot Bgen0-1e x, gen0-1e +C
dou:le dot BgenD0-1e x, genD0-1e +C
Returns the dot 1roduct o# x and +, i.e.,
x[ $]+ [$]x [1]+[1]...
vec' cross Bvec' x, vec' +C
dvec' cross Bdvec' x, dvec' +C
Returns the cross 1roduct o# 4 and -, i.e.,
[
x [1]+[ !]+ [1]x [!]
x[ !]+[ $]+ [ !]x[ $]
x[$]+ [1]+ [$]x [1]
]
gen0-1e normali/e Bgen0-1e xC
genD0-1e normali/e BgenD0-1e xC
Returns a vector in the sae direction as x :ut with a
length o# 1.
co1ati:ilit- 1ro#ile onl-
vec% ftransform BC
Availa:le onl- when using the co1ati:ilit- 1ro#ile. 6or
core .1en23, use invariant.
6or verte4 shaders onl-. 0his #unction will ensure that
the incoing verte4 value will :e trans#ored in a wa-
that 1roduces e4actl- the sae result as would :e
1roduced :- .1en23Ns #i4ed #unctionalit- trans#or. It
is intended to :e used to co1ute gl_Position, e.g.,
gl?5osition T ftransformBC
0his #unction should :e used, #or e4a1le, when an
a11lication is rendering the sae geoetr- in se1arate
1asses, and one 1ass uses the #i4ed #unctionalit- 1ath to
render and another 1ass uses 1rograa:le shaders.
128
S(nta- ,escription
gen0-1e faceforward Bgen0-1e ,
gen0-1e ,,
gen0-1e re%C
genD0-1e faceforward BgenD0-1e ,
genD0-1e ,,
genD0-1e re%C
I# dotBre%, ,C R $ return * otherwise return ].
gen0-1e reflect Bgen0-1e ,, gen0-1e C
genD0-1e reflect BgenD0-1e ,,
genD0-1e C
6or the incident vector , and sur#ace orientation ,
returns the re#lection direction:
, ] ! dotB, ,C
ust alread- :e norali=ed in order to achieve the
desired result.
gen0-1e refract Bgen0-1e ,, gen0-1e ,
#loat etaC
genD0-1e refract BgenD0-1e ,,
genD0-1e ,
#loat etaC
6or the incident vector , and sur#ace noral , and the
ratio o# indices o# re#raction eta* return the re#raction
vector. 0he result is co1uted :-
k T 1.$ 9 eta H eta H B1.$ 9 dotB, ,C H dotB, ,CC
i# Bk R $.$C
return gen0-1eB$.$C GG or genD0-1eB$.$C
else
return eta H , 9 Beta H dotB, ,C L sNrtBkCC H
0he in1ut 1araeters #or the incident vector , and the
sur#ace noral ust alread- :e norali=ed to get the
desired results.
129
$.' 8atri- /unctions
6or each o# the #ollowing :uilt9in atri4 #unctions, there is :oth a single91recision #loating 1oint version,
where all arguents and return values are single 1recision, and a dou:le91recision #loating version, where
all arguents and return values are dou:le 1recision. .nl- the single91recision #loating 1oint version is
shown.
S(nta- ,escription
at matrix'ompLult Bat x, at +C ;ulti1l- atri4 x :- atri4 + co1onent9wise, i.e.,
result[i\[D\ is the scalar 1roduct o# x[i\[D\ and +[i\[D\.
8ote: to get linear alge:raic atri4 ulti1lication, use
the ulti1l- o1erator B6C.
at! outerSroduct Bvec! c, vec! rC
at' outerSroduct Bvec' c, vec' rC
at% outerSroduct Bvec% c, vec% rC
at!4' outerSroduct Bvec' c, vec! rC
at'4! outerSroduct Bvec! c, vec' rC
at!4% outerSroduct Bvec% c, vec! rC
at%4! outerSroduct Bvec! c, vec% rC
at'4% outerSroduct Bvec% c, vec' rC
at%4' outerSroduct Bvec' c, vec% rC
0reats the #irst 1araeter c as a colun vector Batri4
with one colunC and the second 1araeter r as a row
vector Batri4 with one rowC and does a linear alge:raic
atri4 ulti1l- c H r, -ielding a atri4 whose nu:er o#
rows is the nu:er o# co1onents in c and whose
nu:er o# coluns is the nu:er o# co1onents in r.
at! transpose Bat! mC
at' transpose Bat' mC
at% transpose Bat% mC
at!4' transpose Bat'4! mC
at'4! transpose Bat!4' mC
at!4% transpose Bat%4! mC
at%4! transpose Bat!4% mC
at'4% transpose Bat%4' mC
at%4' transpose Bat'4% mC
Returns a atri4 that is the trans1ose o# m. 0he in1ut
atri4 m is not odi#ied.
#loat determinant Bat! mC
#loat determinant Bat' mC
#loat determinant Bat% mC
Returns the deterinant o# m.
13
S(nta- ,escription
at! inverse Bat! mC
at' inverse Bat' mC
at% inverse Bat% mC
Returns a atri4 that is the inverse o# m. 0he in1ut
atri4 m is not odi#ied. 0he values in the returned
atri4 are unde#ined i# m is singular or 1oorl-9
conditioned Bnearl- singularC.
131
$.% ector ;elational /unctions
Relational and e<ualit- o1erators B81 8B1 91 9B1 BB1 CBC are de#ined to o1erate on scalars and 1roduce
scalar Boolean results. 6or vector results, use the #ollowing :uilt9in #unctions. Below, the #ollowing
1laceholders are used #or the listed s1eci#ic t-1es:
Slaceholder ,pecific I"pes Allowed
:vec :vec!, :vec', :vec%
ivec ivec!, ivec', ivec%
uvec uvec!, uvec', uvec%
vec vec!, vec', vec%, dvec!, dvec', dvec%
In all cases, the si=es o# all the in1ut and return vectors #or an- 1articular call ust atch.
S(nta- ,escription
:vec lessIhan Bvec 4, vec -C
:vec lessIhan Bivec 4, ivec -C
:vec lessIhan Buvec 4, uvec -C
Returns the co1onent9wise co1are o# x R +.
:vec lessIhanONual Bvec 4, vec -C
:vec lessIhanONual Bivec 4, ivec -C
:vec lessIhanONual Buvec 4, uvec -C
Returns the co1onent9wise co1are o# x RT +.
:vec greaterIhan Bvec 4, vec -C
:vec greaterIhan Bivec 4, ivec -C
:vec greaterIhan Buvec 4, uvec -C
Returns the co1onent9wise co1are o# x S +.
:vec greaterIhanONual Bvec 4, vec -C
:vec greaterIhanONual Bivec 4, ivec -C
:vec greaterIhanONual Buvec 4, uvec -C
Returns the co1onent9wise co1are o# x ST +.
:vec eNual Bvec 4, vec -C
:vec eNual Bivec 4, ivec -C
:vec eNual Buvec 4, uvec -C
:vec eNual B:vec 4, :vec -C
:vec notONual Bvec 4, vec -C
:vec notONual Bivec 4, ivec -C
:vec notONual Buvec 4, uvec -C
:vec notONual B:vec 4, :vec -C
Returns the co1onent9wise co1are o# x TT +.
Returns the co1onent9wise co1are o# x PT +.
:ool an" B:vec 4C Returns true i# an- co1onent o# x is true.
132
S(nta- ,escription
:ool all B:vec 4C Returns true onl- i# all co1onents o# x are true.
:vec not B:vec 4C Returns the co1onent9wise logical co1leent o# x.
133
$.$ Integer /unctions
0hese all o1erate co1onent9wise. 0he descri1tion is 1er co1onent. 0he notation [a, #\ eans the set
o# :its #ro :it9nu:er a through :it9nu:er #, inclusive. 0he lowest9order :it is :it $. EBit nu:erF
will alwa-s re#er to counting u1 #ro the lowest9order :it as :it $.
S(nta- ,escription
gen70-1e uadd'arr" Bgen70-1e x,
gen70-1e +,
out gen70-1e carr+C
Adds '!9:it unsigned integer x and +, returning the su
odulo !
'!
. 0he value carr+ is set to $ i# the su was
less than !
'!
, or to 1 otherwise.
gen70-1e usu#orrow Bgen70-1e x,
gen70-1e +,
out gen70-1e #orro/C
,u:tracts the '!9:it unsigned integer + #ro x, returning
the di##erence i# non9negative, or !
'!
1lus the di##erence
otherwise. 0he value #orro/ is set to $ i# x G> +, or to
1 otherwise.
void umulOxtended Bgen70-1e x,
gen70-1e +,
out gen70-1e ms#,
out gen70-1e ls#C
void imulOxtended BgenI0-1e x,
genI0-1e +,
out genI0-1e ms#,
out genI0-1e ls#C
;ulti1lies '!9:it integers x and +, 1roducing a +%9:it
result. 0he '! least9signi#icant :its are returned in ls#.
0he '! ost9signi#icant :its are returned in ms#.
genI0-1e itfieldOxtract BgenI0-1e value,
int o%%set, int #itsC
gen70-1e itfieldOxtract Bgen70-1e value,
E4tracts :its [o%%set, o%%set L #its - 1\ #ro value,
returning the in the least signi#icant :its o# the result.
6or unsigned data t-1es, the ost signi#icant :its o# the
result will :e set to =ero. 6or signed data t-1es, the
ost signi#icant :its will :e set to the value o# :it o%%set
L #ase#its : 1.
I# #its is =ero, the result will :e =ero. 0he result will :e
unde#ined i# o%%set or #its is negative, or i# the su o#
o%%set and #its is greater than the nu:er o# :its used
to store the o1erand.
134
S(nta- ,escription
genI0-1e itfield(nsert BgenI0-1e #ase,
genI0-1e insert,
gen70-1e itfield(nsert Bgen70-1e #ase,
gen70-1e insert,
Returns the insertion the #its least9signi#icant :its o#
insert into #ase.
0he result will have :its [o%%set, o%%set L #its - 1\ taken
#ro :its [$, #its : 1\ o# insert, and all other :its taken
directl- #ro the corres1onding :its o# #ase. I# #its is
=ero, the result will si1l- :e #ase. 0he result will :e
unde#ined i# o%%set or #its is negative, or i# the su o#
o%%set and #its is greater than the nu:er o# :its used to
store the o1erand.
genI0-1e itfieldKeverse BgenI0-1e valueC
gen70-1e itfieldKeverse Bgen70-1e valueC
Returns the reversal o# the :its o# value. 0he :it
nu:ered n o# the result will :e taken #ro :it B#its - 1C
- n o# value, where #its is the total nu:er o# :its used
to re1resent value.
genI0-1e it'ount BgenI0-1e valueC
genI0-1e it'ount Bgen70-1e valueC
Returns the nu:er o# :its set to 1 in the :inar-
re1resentation o# value.
genI0-1e findJ,# BgenI0-1e valueC
genI0-1e findJ,# Bgen70-1e valueC
Returns the :it nu:er o# the least signi#icant :it set to
1 in the :inar- re1resentation o# value. I# value is =ero,
91will :e returned.
genI0-1e findL,# BgenI0-1e valueC
genI0-1e findL,# Bgen70-1e valueC
Returns the :it nu:er o# the ost signi#icant :it in the
:inar- re1resentation o# value.
6or 1ositive integers, the result will :e the :it nu:er o#
the ost signi#icant :it set to 1. 6or negative integers,
the result will :e the :it nu:er o# the ost signi#icant
:it set to $. 6or a value o# =ero or negative one, 91 will
:e returned.
135
$." Te-ture /unctions
0e4ture looku1 #unctions are availa:le in all shading stages. /owever, autoatic level o# detail is
co1uted onl- #or #ragent shaders. .ther shaders o1erate as though the :ase level o# detail were
co1uted as =ero. 0he #unctions in the ta:le :elow 1rovide access to te4tures through sa1lers, as set u1
through the .1en23 A5I. 0e4ture 1ro1erties such as si=e, 1i4el #orat, nu:er o# diensions, #iltering
ethod, nu:er o# i19a1 levels, de1th co1arison, and so on are also de#ined :- .1en23 A5I calls.
,uch 1ro1erties are taken into account as the te4ture is accessed via the :uilt9in #unctions de#ined :elow.
0e4ture data can :e stored :- the 23 as #loating 1oint, unsigned norali=ed integer, unsigned integer or
signed integer data. 0his is deterined :- the t-1e o# the internal #orat o# the te4ture. 0e4ture looku1s
on unsigned norali=ed integer and #loating 1oint data return #loating 1oint values in the range [$, 1\.
0e4ture looku1 #unctions are 1rovided that can return their result as #loating 1oint, unsigned integer or
signed integer, de1ending on the sa1ler t-1e 1assed to the looku1 #unction. "are ust :e taken to use
the right sa1ler t-1e #or te4ture access. 0he #ollowing ta:le lists the su11orted co:inations o# sa1ler
t-1es and te4ture internal #orats. Blank entries are unsu11orted. Doing a te4ture looku1 will return
unde#ined values #or unsu11orted co:inations.
Internal 0e4ture 6orat
6loating 5oint
,a1ler 0-1es
,igned Integer
,a1ler 0-1es
7nsigned Integer
,a1ler 0-1es
6loating 1oint ,u11orted
8orali=ed Integer ,u11orted
,igned Integer ,u11orted
7nsigned Integer ,u11orted
I# an integer sa1ler t-1e is used, the result o# a te4ture looku1 is an ivec4. I# an unsigned integer sa1ler
t-1e is used, the result o# a te4ture looku1 is a uvec4. I# a #loating 1oint sa1ler t-1e is used, the result o#
a te4ture looku1 is a vec4, where each co1onent is in the range [$, 1\.
In the 1rotot-1es :elow, the EgF in the return t-1e Egvec4F is used as a 1laceholder #or nothing, EiF, or EuF
aking a return t-1e o# vec4, ivec4, or uvec4. In these cases, the sa1ler arguent t-1e also starts with
EgF, indicating the sae su:stitution done on the return t-1eI it is either a #loating 1oint, signed integer, or
unsigned integer sa1ler, atching the :asic t-1e o# the return t-1e, as descri:ed a:ove.
6or shadow #ors Bthe sa1ler 1araeter is a shadow9t-1eC, a de1th co1arison looku1 on the de1th
te4ture :ound to sampler is done as descri:ed in section '.(.1+ E0e4ture "o1arison ;odesF o# the
.1en23 2ra1hics ,-ste ,1eci#ication. ,ee the ta:le :elow #or which co1onent s1eci#ies Dre%. 0he
te4ture :ound to sampler ust :e a de1th te4ture, or results are unde#ined. I# a non9shadow te4ture call is
ade to a sa1ler that re1resents a de1th te4ture with de1th co1arisons turned on, then results are
unde#ined. I# a shadow te4ture call is ade to a sa1ler that re1resents a de1th te4ture with de1th
co1arisons turned o##, then results are unde#ined. I# a shadow te4ture call is ade to a sa1ler that does
not re1resent a de1th te4ture, then results are unde#ined.
136
In all #unctions :elow, the #ias 1araeter is o1tional #or #ragent shaders. 0he #ias 1araeter is not
acce1ted in another shaders. 6or a #ragent shader, i# #ias is 1resent, it is added to the i1licit level o#
detail 1rior to 1er#oring the te4ture access o1eration. 8o #ias or lo$ 1araeters #or rectangular te4tures,
ulti9sa1le te4tures, or te4ture :u##ers are su11orted :ecause i19a1s are not allowed #or these t-1es
o# te4tures.
0he i1licit level o# detail is selected as #ollows: 6or a te4ture that is not i19a11ed, the te4ture is used
directl-. I# it is i19a11ed and running in a #ragent shader, the 3.D co1uted :- the i1leentation
is used to do the te4ture looku1. I# it is i19a11ed and running on the verte4 shader, then the :ase
te4ture is used.
,oe te4ture #unctions Bnon9EJodF and non9EGradF versionsC a- re<uire i1licit derivatives. I1licit
derivatives are unde#ined within non9uni#or control #low and #or non9#ragent9shader te4ture #etches.
6or 'ue #ors, the direction o# P is used to select which #ace to do a !9diensional te4ture looku1 in, as
descri:ed in section '.(.1$ E"u:e ;a1 0e4ture ,electionF in the .1en23 2ra1hics ,-ste ,1eci#ication.
6or Arra" #ors, the arra- la-er used will :e
max $,min $ 1, %loorla+er$.*
where $ is the de1th o# the te4ture arra- and la+er coes #ro the co1onent indicated in the ta:les
:elow.
$.".1 Te-ture :uer( /unctions
0he texture,i/e #unctions <uer- the diensions o# a s1eci#ic te4ture level #or a sa1ler.
0he textureTuer"Jod #unctions are availa:le onl- in a #ragent shader. 0he- take the co1onents o# P
and co1ute the level o# detail in#oration that the te4ture 1i1e would use to access that te4ture through a
noral te4ture looku1. 0he level o# detail HI Be<uation '.1( in the .1en23 2ra1hics ,-ste
,1eci#icationC is o:tained a#ter an- 3.D :ias, :ut 1rior to cla1ing to [0EZ07RE?;I8?3.D,
0EZ07RE?;AZ?3.D\. 0he i1a1 arra-BsC that would :e accessed are also co1uted. I# a single
level o# detail would :e accessed, the level9o#9detail nu:er relative to the :ase level is returned. I#
ulti1le levels o# detail would :e accessed, a #loating91oint nu:er :etween the two levels is returned,
with the #ractional 1art e<ual to the #ractional 1art o# the co1uted and cla1ed level o# detail. 0he
algorith used is given :- the #ollowing 1seudo9code:
137
float LomuteDccessed"od(float comuted"od)
4
// Llam the comuted "*, according to the texture "*, clams5
if (comuted"od 6 +%T+@(%!G#$!"*,) comuted"od 3 +%T+@(%!G#$!"*,;
if (comuted"od Q +%T+@(%!GDT!"*,) comuted"od 3 +%T+@(%!GDT!"*,;
// Llam the comuted "*, to the range of accessible levels5
if (comuted"od 6 ?5?)
comuted"od 3 ?5?;
if (comuted"od Q (float)
maxDccessible"evel) comuted"od 3 (float) maxDccessible"evel;
// (eturn a value according to the min filter5
if (+%T+@(%!G#$!&#"+%( is "#$%D( or $%D(%)+) 4
return ?5?;
8 else if (+%T+@(%!G#$!&#"+%( is $%D(%)+!G#HGDH!$%D(%)+
or "#$%D(!G#HGDH!$%D(%)+) 4
return ceil(comuted"od K ?5E) 2 05?;
8 else 4
return comuted"od;
8
8
0he value max;ccessi#leLevel is the level nu:er o# the sallest accessi:le level o# the i1a1 arra-
Bthe value 1 in section '.(.& E0e4ture ;ini#icationF o# the .1en23 2ra1hics ,-ste ,1eci#icationC inus
the :ase level.
S(nta- ,escription
int texture,i/e Bgsa1ler1D sampler, int lo$C
ivec! texture,i/e Bgsa1ler!D sampler, int lo$C
ivec' texture,i/e Bgsa1ler'D sampler, int lo$C
ivec! texture,i/e Bgsa1ler"u:e sampler, int lo$C
int texture,i/e Bsa1ler1D,hadow sampler, int lo$C
ivec! texture,i/e Bsa1ler!D,hadow sampler, int lo$C
ivec! texture,i/e Bsa1ler"u:e,hadow sampler, int lo$C
ivec' texture,i/e Bgsa1ler"u:eArra- sampler, int lo$C
ivec' texture,i/e Bsa1ler"u:eArra-,hadow sampler, int lo$C
ivec! texture,i/e Bgsa1ler!DRect samplerC
ivec! texture,i/e Bsa1ler!DRect,hadow samplerC
ivec! texture,i/e Bgsa1ler1DArra- sampler, int lo$C
ivec' texture,i/e Bgsa1ler!DArra- sampler, int lo$C
ivec! texture,i/e Bsa1ler1DArra-,hadow sampler, int lo$C
ivec' texture,i/e Bsa1ler!DArra-,hadow sampler, int lo$C
int texture,i/e Bgsa1lerBu##er samplerC
ivec! texture,i/e Bgsa1ler!D;, samplerC
ivec' texture,i/e Bgsa1ler!D;,Arra- samplerC
Returns the diensions o# level
lo$ Bi# 1resentC #or the te4ture
:ound to sampler, as descri:ed
in section !.11.) E,hader
E4ecutionF o# the .1en23
2ra1hics ,-ste ,1eci#ication,
under E0e4ture ,i=e >uer-F.
0he co1onents in the return
value are #illed in, in order, with
the width, height, de1th o# the
te4ture.
6or the arra- #ors, the last
co1onent o# the return value is
the nu:er o# la-ers in the
te4ture arra-.
138
S(nta- ,escription
vec! textureTuer"JodBgsa1ler1D sampler, #loat PC
vec! textureTuer"JodBgsa1ler!D sampler, vec! PC
vec! textureTuer"JodBgsa1ler'D sampler, vec' PC
vec! textureTuer"JodBgsa1ler"u:e sampler, vec' PC
vec! textureTuer"JodBgsa1ler1DArra- sampler, #loat PC
vec! textureTuer"JodBgsa1ler!DArra- sampler, vec! PC
vec! textureTuer"JodBgsa1ler"u:eArra- sampler, vec' PC
vec! textureTuer"JodBsa1ler1D,hadow sampler, #loat PC
vec! textureTuer"JodBsa1ler!D,hadow sampler, vec! PC
vec! textureTuer"JodBsa1ler"u:e,hadow sampler, vec' PC
vec! textureTuer"JodBsa1ler1DArra-,hadow sampler, #loat PC
vec! textureTuer"JodBsa1ler!DArra-,hadow sampler, vec! PC
vec! textureTuer"JodBsa1ler"u:eArra-,hadow sampler, vec' PC
Returns the i1a1 arra-BsC
that would :e accessed in the x
co1onent o# the return value.
Returns the co1uted level o#
detail relative to the :ase level
in the + co1onent o# the return
value.
I# called on an inco1lete
te4ture, the results are
unde#ined.
$.".2 Te-el Loo3up /unctions
S(nta- ,escription
gvec% texture Bgsa1ler1D sampler* #loat P [, #loat #ias\ C
gvec% texture Bgsa1ler!D sampler, vec! P [, #loat #ias\ C
gvec% texture Bgsa1ler'D sampler, vec' P [, #loat #ias\ C
gvec% texture Bgsa1ler"u:e sampler, vec' P [, #loat #ias\ C
#loat texture Bsa1ler1D,hadow sampler* vec' P [, #loat #ias\ C
#loat texture Bsa1ler!D,hadow sampler* vec' P [, #loat #ias\ C
#loat texture Bsa1ler"u:e,hadow sampler* vec% P [, #loat #ias\ C
gvec% texture Bgsa1ler1DArra- sampler* vec! P [, #loat #ias\ C
gvec% texture Bgsa1ler!DArra- sampler, vec' P [, #loat #ias\ C
gvec% texture Bgsa1ler"u:eArra- sampler, vec% P [, #loat #ias\ C
#loat texture Bsa1ler1DArra-,hadow sampler* vec' P
[, #loat #ias\ C
#loat texture Bsa1ler!DArra-,hadow sampler* vec% PC
gvec% texture Bgsa1ler!DRect sampler, vec! PC
#loat texture Bsa1ler!DRect,hadow sampler, vec' PC
#loat texture Bgsa1ler"u:eArra-,hadow sampler, vec% P,
#loat compareC
7se the te4ture coordinate P to
do a te4ture looku1 in the
te4ture currentl- :ound to
sampler.
6or shadow #ors: @hen
compare is 1resent, it is used as
Dre% and the arra- la-er coes
#ro P./. @hen compare is not
1resent, the last co1onent o#
P is used as Dre% and the arra-
la-er coes #ro the second to
last co1onent o# P. B0he
second co1onent o# P is
unused #or 1) shadow looku1s.C
6or non9shadow #ors: the arra-
la-er coes #ro the last
co1onent o# P.
139
S(nta- ,escription
gvec% textureSroM Bgsa1ler1D sampler, vec! P [, #loat #ias\ C
gvec% textureSroM Bgsa1ler1D sampler, vec% P [, #loat #ias\ C
gvec% textureSroM Bgsa1ler!D sampler, vec' P [, #loat #ias\ C
gvec% textureSroM Bgsa1ler!D sampler, vec% P [, #loat #ias\ C
gvec% textureSroM Bgsa1ler'D sampler, vec% P [, #loat #ias\ C
#loat textureSroM Bsa1ler1D,hadow sampler* vec% P
[, #loat #ias\ C
#loat textureSroM Bsa1ler!D,hadow sampler* vec% P
[, #loat #ias\ C
gvec% textureSroM Bgsa1ler!DRect sampler, vec' PC
gvec% textureSroM Bgsa1ler!DRect sampler, vec% PC
#loat textureSroM Bsa1ler!DRect,hadow sampler, vec% PC
Do a te4ture looku1 with
1roDection. 0he te4ture
coordinates consued #ro P,
not including the last co1onent
o# P, are divided :- the last
co1onent o# P. 0he resulting
'
rd
co1onent o# P in the
shadow #ors is used as Dre%.
A#ter these values are co1uted,
te4ture looku1 1roceeds as in
texture.
gvec% textureJod Bgsa1ler1D sampler, #loat P, #loat lo$C
gvec% textureJod Bgsa1ler!D sampler, vec! P, #loat lo$C
gvec% textureJod Bgsa1ler'D sampler, vec' P, #loat lo$C
gvec% textureJod Bgsa1ler"u:e sampler, vec' P, #loat lo$C
#loat textureJod Bsa1ler1D,hadow sampler* vec' P, #loat lo$C
#loat textureJod Bsa1ler!D,hadow sampler* vec' P, #loat lo$C
gvec% textureJod Bgsa1ler1DArra- sampler, vec! P, #loat lo$C
gvec% textureJod Bgsa1ler!DArra- sampler, vec' P, #loat lo$C
#loat textureJod Bsa1ler1DArra-,hadow sampler* vec' P,
#loat lo$C
gvec% textureJod Bgsa1ler"u:eArra- sampler, vec% P, #loat lo$C
Do a te4ture looku1 as in
texture :ut with e41licit 3.DI
lo$ s1eci#ies H#ase and sets the
1artial derivatives as #ollows.
B,ee section '.(.11 E0e4ture
;ini#icationF and e<uation '.1)
in the .1en23 2ra1hics ,-ste
,1eci#ication.C
u
x
= $
v
x
= $
/
x
= $
u
+
= $
v
+
= $
/
+
= $
14
S(nta- ,escription
gvec% textureOffset Bgsa1ler1D sampler* #loat P*
int o%%set [, #loat #ias\ C
gvec% textureOffset Bgsa1ler!D sampler, vec! P,
ivec! o%%set [, #loat #ias\ C
gvec% textureOffset Bgsa1ler'D sampler, vec' P,
ivec' o%%set [, #loat #ias\ C
gvec% textureOffset Bgsa1ler!DRect sampler, vec! P,
ivec! o%%set C
#loat textureOffset Bsa1ler!DRect,hadow sampler, vec' P,
ivec! o%%set C
#loat textureOffset Bsa1ler1D,hadow sampler* vec' P,
#loat textureOffset Bsa1ler!D,hadow sampler* vec' P,
gvec% textureOffset Bgsa1ler1DArra- sampler* vec! P*
gvec% textureOffset Bgsa1ler!DArra- sampler, vec' P,
#loat textureOffset Bsa1ler1DArra-,hadow sampler* vec' P,
texture :ut with o%%set added to
the Bu,v,/C te4el coordinates
:e#ore looking u1 each te4el.
0he o##set value ust :e a
constant e41ression. A liited
range o# o##set values are
su11ortedI the iniu and
a4iu o##set values are
i1leentation9de1endent and
given :-
gl?;in5rogra0e4el.##set and
gl?;a45rogra0e4el.##set,
res1ectivel-.
8ote that o%%set does not a11l-
to the la-er coordinate #or
te4ture arra-s. 0his is e41lained
in detail in section '.(.11
E0e4ture ;ini#icationF o# the
.1en23 2ra1hics ,-ste
,1eci#ication, where o%%set is
u
*
v
*
/
. 8ote that te4el
o##sets are also not su11orted
#or cu:e a1s.
gvec% texel-etch Bgsa1ler1D sampler, int P, int lo$C
gvec% texel-etch Bgsa1ler!D sampler, ivec! P, int lo$C
gvec% texel-etch Bgsa1ler'D sampler, ivec' P, int lo$C
gvec% texel-etch Bgsa1ler!DRect sampler, ivec! PC
gvec% texel-etch Bgsa1ler1DArra- sampler, ivec! P, int lo$C
gvec% texel-etch Bgsa1ler!DArra- sampler, ivec' P, int lo$C
gvec% texel-etch Bgsa1lerBu##er sampler, int PC
gvec% texel-etch Bgsa1ler!D;, sampler, ivec! P, int sampleC
gvec% texel-etch Bgsa1ler!D;,Arra- sampler, ivec' P,
int sampleC
7se integer te4ture coordinate P
to looku1 a single te4el #ro
sampler. 0he arra- la-er coes
#ro the last co1onent o# P #or
the arra- #ors. 0he level9o#9
detail lo$ Bi# 1resentC is as
descri:ed in sections !.11.(
E,hader E4ecutionF under 0e4el
6etches and '.( E0e4turingF o#
the .1en23 2ra1hics ,-ste
,1eci#ication.
141
S(nta- ,escription
gvec% texel-etchOffset Bgsa1ler1D sampler, int P, int lo$,
int o%%setC
gvec% texel-etchOffset Bgsa1ler!D sampler, ivec! P, int lo$,
ivec! o%%setC
gvec% texel-etchOffset Bgsa1ler'D sampler, ivec' P, int lo$,
ivec' o%%setC
gvec% texel-etchOffset Bgsa1ler!DRect sampler, ivec! P,
ivec! o%%setC
gvec% texel-etchOffset Bgsa1ler1DArra- sampler, ivec! P, int lo$,
int o%%setC
gvec% texel-etchOffset Bgsa1ler!DArra- sampler, ivec' P, int lo$,
ivec! o%%setC
6etch a single te4el as in
texel-etch o##set :- o%%set as
descri:ed in textureOffset.
gvec% textureSroMOffset Bgsa1ler1D sampler* vec! P*
gvec% textureSroMOffset Bgsa1ler1D sampler* vec% P*
gvec% textureSroMOffset Bgsa1ler!D sampler, vec' P,
gvec% textureSroMOffset Bgsa1ler!D sampler, vec% P,
gvec% textureSroMOffset Bgsa1ler'D sampler, vec% P,
ivec' o%%set [, #loat #ias\ C
gvec% textureSroMOffset Bgsa1ler!DRect sampler, vec' P,
ivec! o%%set C
gvec% textureSroMOffset Bgsa1ler!DRect sampler, vec% P,
ivec! o%%set C
#loat textureSroMOffset Bsa1ler!DRect,hadow sampler, vec% P,
ivec! o%%set C
#loat textureSroMOffset Bsa1ler1D,hadow sampler* vec% P,
#loat textureSroMOffset Bsa1ler!D,hadow sampler* vec% P,
Do a 1roDective te4ture looku1
as descri:ed in textureSroM
o##set :- o%%set as descri:ed in
textureOffset.
142
S(nta- ,escription
gvec% textureJodOffset Bgsa1ler1D sampler* #loat P,
#loat lo$, int o%%setC
gvec% textureJodOffset Bgsa1ler!D sampler, vec! P,
#loat lo$, ivec! o%%setC
gvec% textureJodOffset Bgsa1ler'D sampler, vec' P,
#loat lo$, ivec' o%%setC
#loat textureJodOffset Bsa1ler1D,hadow sampler* vec' P,
#loat textureJodOffset Bsa1ler!D,hadow sampler* vec' P,
gvec% textureJodOffset Bgsa1ler1DArra- sampler* vec! P,
gvec% textureJodOffset Bgsa1ler!DArra- sampler, vec' P,
#loat textureJodOffset Bsa1ler1DArra-,hadow sampler* vec' P,
Do an o##set te4ture looku1 with
e41licit 3.D. ,ee textureJod
and textureOffset.
gvec% textureSroMJod Bgsa1ler1D sampler, vec! P, #loat lo$C
gvec% textureSroMJod Bgsa1ler1D sampler, vec% P, #loat lo$C
gvec% textureSroMJod Bgsa1ler!D sampler, vec' P, #loat lo$C
gvec% textureSroMJod Bgsa1ler!D sampler, vec% P, #loat lo$C
gvec% textureSroMJod Bgsa1ler'D sampler, vec% P, #loat lo$C
#loat textureSroMJod Bsa1ler1D,hadow sampler* vec% P, #loat lo$C
#loat textureSroMJod Bsa1ler!D,hadow sampler* vec% P* #loat lo$C
Do a 1roDective te4ture looku1
with e41licit 3.D. ,ee
textureSroM and textureJod.
gvec% textureSroMJodOffset Bgsa1ler1D sampler* vec! P,
gvec% textureSroMJodOffset Bgsa1ler1D sampler* vec% P,
gvec% textureSroMJodOffset Bgsa1ler!D sampler, vec' P,
gvec% textureSroMJodOffset Bgsa1ler!D sampler, vec% P,
gvec% textureSroMJodOffset Bgsa1ler'D sampler, vec% P,
#loat lo$, ivec' o%%setC
#loat textureSroMJodOffset Bsa1ler1D,hadow sampler* vec% P,
#loat textureSroMJodOffset Bsa1ler!D,hadow sampler* vec% P,
Do an o##set 1roDective te4ture
looku1 with e41licit 3.D. ,ee
textureSroM, textureJod, and
textureOffset.
143
S(nta- ,escription
gvec% textureGrad Bgsa1ler1D sampler* #loat P,
#loat $P$x, #loat $P$+C
gvec% textureGrad Bgsa1ler!D sampler* vec! P,
vec! $P$x, vec! $P$+C
gvec% textureGrad Bgsa1ler'D sampler* vec' P,
vec' $P$x, vec' $P$+C
gvec% textureGrad Bgsa1ler"u:e sampler, vec' P,
gvec% textureGrad Bgsa1ler!DRect sampler, vec! P,
#loat textureGrad Bsa1ler!DRect,hadow sampler, vec' P,
#loat textureGrad Bsa1ler1D,hadow sampler, vec' P,
#loat textureGrad Bsa1ler!D,hadow sampler, vec' P,
#loat textureGrad Bsa1ler"u:e,hadow sampler, vec% P,
gvec% textureGrad Bgsa1ler1DArra- sampler* vec! P,
gvec% textureGrad Bgsa1ler!DArra- sampler* vec' P,
#loat textureGrad Bsa1ler1DArra-,hadow sampler, vec' P,
#loat textureGrad Bsa1ler!DArra-,hadow sampler, vec% P,
gvec% textureGrad Bgsa1ler"u:eArra- sampler, vec% P,
texture :ut with e41licit
gradients. 0he 1artial
derivatives o# P are with res1ect
to window 4 and window -. ,et
s
x
=
{
P
x
#or a 1D te4ture
P.s
x
otherwise
s
+
=
{
P
+
#or a 1D te4ture
P.s
+
otherwise
t
x
=
{
$.$ #or a 1D te4ture
P.t
x
otherwise
t
+
=
{
$.$ #or a 1D te4ture
P.t
+
otherwise
r
x
=
{
$.$ #or 1D or !D
P.p
x
cu:e, other
r
+
=
{
$.$ #or 1D or !D
P.p
+
cu:e, other
6or the cu:e version, the 1artial
derivatives o# P are assued to
:e in the coordinate s-ste used
:e#ore te4ture coordinates are
1roDected onto the a11ro1riate
cu:e #ace.
144
S(nta- ,escription
gvec% textureGradOffset Bgsa1ler1D sampler* #loat P*
#loat $P$x, #loat $P$+* int o%%setC
gvec% textureGradOffset Bgsa1ler!D sampler, vec! P,
vec! $P$x, vec! $P$+* ivec! o%%setC
gvec% textureGradOffset Bgsa1ler'D sampler, vec' P,
vec' $P$x, vec' $P$+* ivec' o%%setC
gvec% textureGradOffset Bgsa1ler!DRect sampler, vec! P,
#loat textureGradOffset Bsa1ler!DRect,hadow sampler, vec' P,
#loat textureGradOffset Bsa1ler1D,hadow sampler* vec' P,
#loat $P$x, #loat $P$+* int o%%set C
#loat textureGradOffset Bsa1ler!D,hadow sampler* vec' P,
gvec% textureGradOffset Bgsa1ler1DArra- sampler* vec! P*
gvec% textureGradOffset Bgsa1ler!DArra- sampler, vec' P,
#loat textureGradOffset Bsa1ler1DArra-,hadow sampler* vec'
P,
#loat textureGradOffset Bsa1ler!DArra-,hadow sampler* vec%
P,
Do a te4ture looku1 with :oth
e41licit gradient and o##set, as
descri:ed in textureGrad and
textureOffset.
gvec% textureSroMGrad Bgsa1ler1D sampler* vec! P,
gvec% textureSroMGrad Bgsa1ler1D sampler* vec% P,
gvec% textureSroMGrad Bgsa1ler!D sampler* vec' P,
gvec% textureSroMGrad Bgsa1ler!D sampler* vec% P,
gvec% textureSroMGrad Bgsa1ler'D sampler* vec% P,
gvec% textureSroMGrad Bgsa1ler!DRect sampler* vec' P,
gvec% textureSroMGrad Bgsa1ler!DRect sampler* vec% P,
#loat textureSroMGrad Bsa1ler!DRect,hadow sampler* vec% P,
#loat textureSroMGrad Bsa1ler1D,hadow sampler, vec% P,
#loat textureSroMGrad Bsa1ler!D,hadow sampler, vec% P,
Do a te4ture looku1 :oth
1roDectivel-, as descri:ed in
textureSroM, and with e41licit
gradient as descri:ed in
textureGrad. 0he 1artial
derivatives $P$x and $P$+ are
assued to :e alread- 1roDected.
145
S(nta- ,escription
gvec% textureSroMGradOffset Bgsa1ler1D sampler* vec! P,
#loat $P$x, #loat $P$+, int o%%setC
gvec% textureSroMGradOffset Bgsa1ler1D sampler* vec% P,
gvec% textureSroMGradOffset Bgsa1ler!D sampler* vec' P,
vec! $P$x, vec! $P$+, ivec! o%%setC
gvec% textureSroMGradOffset Bgsa1ler!D sampler* vec% P,
gvec% textureSroMGradOffset Bgsa1ler!DRect sampler, vec' P,
gvec% textureSroMGradOffset Bgsa1ler!DRect sampler, vec% P,
#loat textureSroMGradOffset Bsa1ler!DRect,hadow sampler,
vec% P,
gvec% textureSroMGradOffset Bgsa1ler'D sampler* vec% P,
vec' $P$x, vec' $P$+, ivec' o%%setC
#loat textureSroMGradOffset Bsa1ler1D,hadow sampler, vec% P,
#loat textureSroMGradOffset Bsa1ler!D,hadow sampler, vec% P,
Do a te4ture looku1 1roDectivel-
and with e41licit gradient as
descri:ed in textureSroMGrad,
as well as with o##set, as
descri:ed in textureOffset.
$.".# Te-ture Gather Instructions
0he te4ture gather #unctions take co1onents o# a single #loating91oint vector o1erand as a te4ture
coordinate, deterine a set o# #our te4els to sa1le #ro the :ase level o# detail o# the s1eci#ied te4ture
iage, and return one co1onent #ro each te4el in a #our9co1onent result vector.
@hen 1er#oring a te4ture gather o1eration, the ini#ication and agni#ication #ilters are ignored, and
the rules #or 3I8EAR #iltering in the .1en23 ,1eci#ication are a11lied to the :ase level o# the te4ture
iage to identi#- the #our te4els i081* i181* i180* and i080. 0he te4els are then converted to te4ture source
colors BR
s
, )
s
, <
s
, ;
s
C according to 0a:le '.!$, #ollowed :- a11lication o# the te4ture swi==le as descri:ed
in section '.&.! E,hader E4ecutionF o# the .1en23 2ra1hics ,-ste ,1eci#ication. A #our9co1onent
vector is asse:led :- taking the selected co1onent #ro each o# the 1ost9swi==led te4ture source colors
in the order Bi081* i181* i180* i080C.
6or te4ture gather #unctions using a shadow sa1ler t-1e, each o# the #our te4el looku1s 1er#ors a de1th
co1arison against the de1th re#erence value 1assed in Bre%JC, and returns the result o# that co1arison in
the a11ro1riate co1onent o# the result vector.
As with other te4ture looku1 #unctions, the results o# a te4ture gather are unde#ined #or shadow sa1lers i#
the te4ture re#erenced is not a de1th te4ture or has de1th co1arisons disa:ledI or #or non9shadow
sa1lers i# the te4ture re#erenced is a de1th te4ture with de1th co1arisons ena:led.
146
S(nta- ,escription
gvec% textureGatherBgsa1ler!D sampler, vec! P
[, int comp\C
gvec% textureGatherBgsa1ler!DArra- sampler,
vec' P [, int comp\C
gvec% textureGatherBgsa1ler"u:e sampler,
vec' P [, int comp\C
gvec% textureGatherBgsa1ler"u:eArra- sampler,
vec% P[, int comp\C
gvec% textureGatherBgsa1ler!DRect sampler,
vec'! P[, int comp\C
vec% textureGatherBsa1ler!D,hadow sampler,
vec! P, #loat re%JC
vec% textureGatherBsa1ler!DArra-,hadow sampler,
vec' P, #loat re%JC
vec% textureGatherBsa1ler"u:e,hadow sampler,
vec' P, #loat re%JC
vec% textureGatherB
sa1ler"u:eArra-,hadow sampler,
vec% P, #loat re%JCI
vec% textureGatherBsa1ler!DRect,hadow sampler,
vec! P, #loat re%JCI
Returns the value
vec%B,a1le?i$?D1BP, :aseC.comp,
,a1le?i1?D1BP, :aseC.comp,
,a1le?i1?D$BP, :aseC.comp,
,a1le?i$?D$BP, :aseC.compC
I# s1eci#ied, the value o# comp ust :e a
constant integer e41ression with a value o# $,
1, !, or ', identi#-ing the x, +, 0, or / 1ost9
swi==led co1onent o# the #our9co1onent
vector looku1 result #or each te4el,
res1ectivel-. I# comp is not s1eci#ied, it is
treated as $, selecting the x co1onent o#
each te4el to generate the result.
gvec% textureGatherOffsetBgsa1ler!D sampler,
vec! P, ivec! o%%set
[, int comp\C
gvec% textureGatherOffsetBgsa1ler!DArra- sampler,
vec' P, ivec! o%%set
[, int comp\C
gvec% textureGatherOffsetBgsa1ler!DRect sampler*
vec'! P, ivec! o%%set
[, int comp\C
vec% textureGatherOffsetB
sa1ler!D,hadow sampler,
vec! P, #loat re%J, ivec! o%%setC
sa1ler!DArra-,hadow sampler,
vec' P, #loat re%J, ivec! o%%setC
sa1ler!DRect,hadow sampler,
vec! P, #loat re%J, ivec! o%%setC
5er#or a te4ture gather o1eration as in
textureGather :- o%%set as descri:ed in
textureOffset e4ce1t that the o%%set can :e
varia:le Bnon constantC and the
i1leentation9de1endent iniu and
a4iu o##set values are given :-
;I8?5R.2RA;?0EZ07RE?2A0/ER?.66,E0
and
;AZ?5R.2RA;?0EZ07RE?2A0/ER?.66,E0,
res1ectivel-.
147
S(nta- ,escription
gvec% textureGatherOffsetsB
gsa1ler!D sampler,
vec! P, ivec! o%%sets[%\
[, int comp\C
gsa1ler!DArra- sampler,
vec' P, ivec! o%%sets[%\
[, int comp\C
gsa1ler!DRect sampler*
vec' P, ivec! o%%sets[%\
[, int comp\C
vec% textureGatherOffsetsB
sa1ler!D,hadow sampler,
vec! P, #loat re%J, ivec! o%%sets[%\C
sa1ler!DArra-,hadow sampler,
vec' P, #loat re%J, ivec! o%%sets[%\C
sa1ler!DRect,hadow sampler,
vec! P, #loat re%J, ivec! o%%sets[%\C
.1erate identicall- to textureGatherOffset
e4ce1t that o%%sets is used to deterine the
location o# the #our te4els to sa1le. Each
o# the #our te4els is o:tained :- a11l-ing the
corres1onding o##set in o%%sets as a Bu* vC
coordinate o##set to P, identi#-ing the #our9
te4el 3I8EAR #oot1rint, and then selecting
the te4el i080 o# that #oot1rint. 0he s1eci#ied
values in o%%sets ust :e set with constant
integral e41ressions.
148
$.".! Compatibilit( .rofile Te-ture /unctions
0he #ollowing te4ture #unctions are onl- in the co1ati:ilit- 1ro#ile.
S(nta- =deprecated> ,escription =deprecated>
vec% texture1) Bsa1ler1D sampler*
#loat coor$ [, #loat #ias\ C
vec% texture1)SroM Bsa1ler1D sampler,
vec! coor$ [, #loat #ias\ C
vec% texture1)SroM Bsa1ler1D sampler,
vec% coor$ [, #loat #ias\ C
vec% texture1)Jod Bsa1ler1D sampler,
#loat coor$, #loat lo$C
vec% texture1)SroMJod Bsa1ler1D sampler,
vec! coor$, #loat lo$C
vec% texture1)SroMJod Bsa1ler1D sampler,
vec% coor$, #loat lo$C
,ee corres1onding signature a:ove without
E1DF in the nae.
vec% texture!) Bsa1ler!D sampler,
vec! coor$ [, #loat #ias\ C
vec% texture!)SroM Bsa1ler!D sampler,
vec' coor$ [, #loat #ias\ C
vec% texture!)SroM Bsa1ler!D sampler,
vec% texture!)Jod Bsa1ler!D sampler,
vec! coor$, #loat lo$C
vec% texture!)SroMJod Bsa1ler!D sampler,
vec' coor$, #loat lo$C
vec% texture!)SroMJod Bsa1ler!D sampler,
E!DF in the nae.
vec% texture3) Bsa1ler'D sampler,
vec% texture3)SroM Bsa1ler'D sampler,
vec% texture3)Jod Bsa1ler'D sampler,
vec% texture3)SroMJod Bsa1ler'D sampler,
E'DF in the nae.
7se the te4ture coordinate coor$ to do a
te4ture looku1 in the 'D te4ture currentl-
:ound to sampler. 6or the 1roDective
BESroMFC versions, the te4ture coordinate is
divided :- coor$.1.
vec% texture'ue Bsa1ler"u:e sampler,
vec% texture'ueJod Bsa1ler"u:e sampler,
E"u:eF in the nae.
149
S(nta- =deprecated> ,escription =deprecated>
vec% shadow1) Bsa1ler1D,hadow sampler*
vec% shadow!) Bsa1ler!D,hadow sampler*
vec% shadow1)SroM Bsa1ler1D,hadow sampler*
vec% shadow!)SroM Bsa1ler!D,hadow sampler*
vec% shadow1)Jod Bsa1ler1D,hadow sampler*
vec% shadow!)Jod Bsa1ler!D,hadow sampler*
vec% shadow1)SroMJodBsa1ler1D,hadow sampler*
vec% shadow!)SroMJodBsa1ler!D,hadow sampler*
vec% coor$* #loat lo$C
,ae #unctionalit- as the Etexture^ :ased
naes a:ove with the sae signature.
15
$.10 1tomic7Counter /unctions
0he atoic9counter o1erations in this section o1erate atoicall- with res1ect to each other. 0he- are
atoic #or an- single counter, eaning an- o# these o1erations on a s1eci#ic counter in one shader
instantiation will :e indivisi:le :- an- o# these o1erations on the sae counter #ro another shader
instantiation. 0here is no guarantee that these o1erations are atoic with res1ect to other #ors o# access
to the counter or that the- are seriali=ed when a11lied to se1arate counters. ,uch cases would re<uire
additional use o# #ences, :arriers, or other #ors a s-nchroni=ation, i# atoicit- or seriali=ation is desired.
0he value returned :- an atoic9counter #unction is the value o# an atoic counter, which a- :e
returned and increented in an atoic o1eration, or
decreented and returned in an atoic o1eration, or
si1l- returned.
0he underl-ing counter is a '!9:it unsigned integer. Increents and decreents at the liit o# the range
will wra1 to [$, !
'!
91\.
S(nta- ,escription
uint atomic'ounter(ncrement Batoic?uint cC Atoicall-
1. increents the counter #or c, and
!. returns its value 1rior to the increent
o1eration.
0hese two ste1s are done atoicall- with res1ect the
atoic counter #unctions in this ta:le.
uint atomic'ounter)ecrement Batoic?uint cC Atoicall-
1. decreents the counter #or c, and
!. returns the value resulting #ro the
decreent o1eration.
0hese two ste1s are done atoicall- with res1ect to
the atoic counter #unctions in this ta:le.
uint atomic'ounter Batoic?uint cC Returns the counter value #or c.
$.11 Image /unctions
Varia:les using one o# the iage :asic t-1es a- :e used :- the :uilt9in shader iage eor- #unctions
de#ined in this section to read and write individual te4els o# a te4ture. Each iage varia:le re#erences an
iage unit, which has a te4ture iage attached.
@hen iage eor- #unctions :elow access eor-, an individual te4el in the iage is identi#ied using
an BiC, Bi* 8C, or Bi* 8* .C coordinate corres1onding to the values o# P. 6or image!)L, and
image!)L,Arra" varia:les Band the corres1onding intGunsigned int t-1esC corres1onding to ulti9
151
sa1le te4tures, each te4el a- have ulti1le sa1les and an individual sa1le is identi#ied using the
integer sample 1araeter. 0he coordinates and sa1le nu:er are used to select an individual te4el in
the anner descri:ed in section '.&.Z o# the .1en23 s1eci#ication.
3oads and stores su11ort #loat, integer, and unsigned integer t-1es. 0he data t-1es :elow starting
EgimageF serve as 1laceholders eaning t-1es starting either EimageF, EiimageF, or EuimageF in the sae
wa- as gvec or gsampler in earlier sections.
0he ,7;)-_P;R;7! in the 1rotot-1es :elow is a 1laceholder re1resenting '' se1arate #unctions, each
#or a di##erent t-1e o# iage varia:le. 0he ,7;)-_P;R;7! 1laceholder is re1laced :- one o# the
#ollowing 1araeter lists:
giage1D image, int P
giage!D image, ivec! P
giage'D image, ivec' P
giage!DRect image, ivec! P
giage"u:e image, ivec' P
giageBu##er image, int P
giage1DArra- image, ivec! P
giage!DArra- image, ivec' P
giage"u:eArra- image, ivec' P
giage!D;, image, ivec! P, int sample
giage!D;,Arra- image, ivec' P, int sample
where each o# the line re1resents one o# three di##erent iage varia:le t-1es, and image, P, and sample
s1eci#- the individual te4el to o1erate on. 0he ethod #or identi#-ing the individual te4el o1erated on
#ro image, P, and sample, and the ethod #or reading and writing the te4el are s1eci#ied in section '.&.Z
o# the .1en23 s1eci#ication re# .
0he atoic #unctions 1er#or atoic o1erations on individual te4els or sa1les o# an iage varia:le.
Atoic eor- o1erations read a value #ro the selected te4el, co1ute a new value using one o# the
o1erations descri:ed :elow, write the new value to the selected te4el, and return the original value read.
0he contents o# the te4el :eing u1dated :- the atoic o1eration are guaranteed not to :e odi#ied :- an-
other iage store or atoic #unction :etween the tie the original value is read and the tie the new
value is written.
Atoic eor- o1erations are su11orted on onl- a su:set o# all iage varia:le t-1esI image ust :e
either:
a signed integer iage varia:le Bt-1e starts EiimageFC and a #orat <uali#ier o# rA2i, used with a
$ata arguent o# t-1e int* or
an unsigned iage varia:le Bt-1e starts EuimageFC and a #orat <uali#ier o# rA2ui, used with a
$ata arguent o# t-1e uint.
152
S(nta- ,escription
gvec% imageJoad Breadonl- ,7;)-_P;R;7!C 3oads the te4el at the coordinate P #ro the iage
unit image Bin ,7;)-_P;R;7!C. 6or ulti9sa1le
loads, the sa1le nu:er is given :- sample. @hen
image, P, sample identi#- a valid te4el, the :its used
to re1resent the selected te4el in eor- are
converted to a vec4, ivec4, or uvec4 in the anner
descri:ed in section '.&.!$ o# the .1en23
,1eci#ication and returned.
void image,tore Bwriteonl- ,7;)-_P;R;7!,
gvec% $ataC
,tores $ata into the te4el at the coordinate P #ro
the iage s1eci#ied :- image. 6or ulti9sa1le
stores, the sa1le nu:er is given :- sample. @hen
image, P, and sample identi#- a valid te4el, the :its
used to re1resent $ata are converted to the #orat o#
the iage unit in the anner descri:ed in section
'.&.!$ o# the .1en23 ,1eci#ication and stored to the
s1eci#ied te4el.
uint imageAtomicAddB,7;)-_P;R;7!,
uint $ataC
int imageAtomicAddB,7;)-_P;R;7!,
int $ataC
"o1utes a new value :- adding the value o# $ata
to the contents o# the selected te4el.
uint imageAtomicLinB,7;)-_P;R;7!,
uint $ataC
int imageAtomicLinB,7;)-_P;R;7!,
int $ataC
"o1utes a new value :- taking the iniu o# the
value o# $ata and the contents o# the selected te4el.
uint imageAtomicLaxB,7;)-_P;R;7!,
uint $ataC
int imageAtomicLaxB,7;)-_P;R;7!,
int $ataC
"o1utes a new value :- taking the a4iu o# the
value $ata and the contents o# the selected te4el.
uint imageAtomicAndB,7;)-_P;R;7!,
uint $ataC
int imageAtomicAndB,7;)-_P;R;7!,
int $ataC
"o1utes a new value :- 1er#oring a :it9wise and
o# the value o# $ata and the contents o# the selected
te4el.
uint imageAtomicOrB,7;)-_P;R;7!,
uint $ataC
int imageAtomicOrB,7;)-_P;R;7!,
int $ataC
"o1utes a new value :- 1er#oring a :it9wise or
o# the value o# $ata and the contents o# the selected
te4el.
153
S(nta- ,escription
uint imageAtomicXorB,7;)-_P;R;7!,
uint $ataC
int imageAtomicXorB,7;)-_P;R;7!,
int $ataC
"o1utes a new value :- 1er#oring a :it9wise
e4clusive or o# the value o# $ata and the contents o#
the selected te4el.
uint imageAtomicOxchange B,7;)-_P;R;7!,
uint $ataC
int imageAtomicOxchange B,7;)-_P;R;7!,
int $ataC
"o1utes a new value :- si1l- co1-ing the value
o# $ata.
uint imageAtomic'omp,wap
B,7;)-_P;R;7!,
uint compare,
uint $ataC
int imageAtomic'omp,wap
B,7;)-_P;R;7!,
int compare,
int $ataC
"o1ares the value o# compare and the contents o#
the selected te4el. I# the values are e<ual, the new
value is given :- $ataI otherwise, it is taken #ro the
original value loaded #ro the te4el.
$.12 /ragment .rocessing /unctions
6ragent 1rocessing #unctions are onl- availa:le in #ragent shaders.
$.12.1 ,erivative /unctions
Derivatives a- :e co1utationall- e41ensive andGor nuericall- unsta:le. 0here#ore, an .1en23
i1leentation a- a11ro4iate the true derivatives :- using a #ast :ut not entirel- accurate derivative
co1utation. Derivatives are unde#ined within non9uni#or control #low.
0he e41ected :ehavior o# a derivative is s1eci#ied using #orwardG:ackward di##erencing.
6orward di##erencing:
" x$x" x ~$"$x x$x 1a
$"$x x ~
" x$x" x
$x
1:
Backward di##erencing:
" x$x" x ~$"$x x$x !a
$"$x x ~
" x" x$x
$x
!:
154
@ith single9sa1le rasteri=ation, $x RT 1.$ in e<uations 1: and !:. 6or ulti9sa1le rasteri=ation, $x R
!.$ in e<uations 1: and !:.
d-d" is a11ro4iated siilarl-, with + re1lacing x.
A 23 i1leentation a- use the a:ove or other ethods to 1er#or the calculation, su:Dect to the
#ollowing conditions:
1. 0he ethod a- use 1iecewise linear a11ro4iations. ,uch linear a11ro4iations i1l- that higher
order derivatives, d-dxBd-dxBxCC and a:ove, are unde#ined.
!. 0he ethod a- assue that the #unction evaluated is continuous. 0here#ore derivatives within non9
uni#or control #low are unde#ined.
'. 0he ethod a- di##er 1er #ragent, su:Dect to the constraint that the ethod a- var- :- window
coordinates, not screen coordinates. 0he invariance re<uireent descri:ed in section '.! EInvarianceF
o# the .1en23 2ra1hics ,-ste ,1eci#ication, is rela4ed #or derivative calculations, :ecause the
ethod a- :e a #unction o# #ragent location.
.ther 1ro1erties that are desira:le, :ut not re<uired, are:
%. 6unctions should :e evaluated within the interior o# a 1riitive Binter1olated, not e4tra1olatedC.
*. 6unctions #or d-dx should :e evaluated while holding - constant. 6unctions #or d-d" should :e
evaluated while holding 4 constant. /owever, i4ed higher order derivatives, like d-dxBd-d"B+CC
and d-d"Bd-dxBxCC are unde#ined.
+. Derivatives o# constant arguents should :e $.
In soe i1leentations, var-ing degrees o# derivative accurac- a- :e o:tained :- 1roviding 23 hints
Bsection *.% E/intsF o# the .1en23 2ra1hics ,-ste ,1eci#icationC, allowing a user to ake an iage
<ualit- versus s1eed trade o##.
S(nta- ,escription
gen0-1e d-dx Bgen0-1e pC Returns the derivative in 4 using local di##erencing #or
the in1ut arguent p.
gen0-1e d-d" Bgen0-1e pC Returns the derivative in - using local di##erencing #or
the in1ut arguent p.
0hese two #unctions are coonl- used to estiate the
#ilter width used to anti9alias 1rocedural te4tures. @e
are assuing that the e41ression is :eing evaluated in
1arallel on a ,I;D arra- so that at an- given 1oint in
tie the value o# the #unction is known at the grid 1oints
re1resented :- the ,I;D arra-. 3ocal di##erencing
:etween ,I;D arra- eleents can there#ore :e used to
derive d6d4, d6d-, etc.
155
S(nta- ,escription
gen0-1e fwidth Bgen0-1e pC Returns the su o# the a:solute derivative in 4 and -
using local di##erencing #or the in1ut arguent p, i.e.,
as Bd-dx BpCC L as Bd-d" BpCCI
$.12.2 Interpolation /unctions
Built9in inter1olation #unctions are availa:le to co1ute an inter1olated value o# a #ragent shader in1ut
varia:le at a shader9s1eci#ied Bx, +C location. A se1arate Bx, +C location a- :e used #or each invocation o#
the :uilt9in #unction, and those locations a- di##er #ro the de#ault Bx, +C location used to 1roduce the
de#ault value o# the in1ut.
6or all o# the inter1olation #unctions, interpolant ust :e an in1ut varia:le or an eleent o# an in1ut
varia:le declared as an arra-. "o1onent selection o1erators Be.g., .x+C a- not :e used when s1eci#-ing
interpolant. I# interpolant is declared with a flat or centroid <uali#ier, the <uali#ier will have no e##ect on
the inter1olated value. I# interpolant is declared with the noperspective <uali#ier, the inter1olated value
will :e co1uted without 1ers1ective correction.
S(nta- ,escription
#loat interpolateAt'entroid B#loat interpolantC
vec! interpolateAt'entroid Bvec! interpolantC
vec' interpolateAt'entroid Bvec' interpolantC
vec% interpolateAt'entroid Bvec% interpolantC
Return the value o# the in1ut interpolant sa1led at a
location inside the :oth the 1i4el and the 1riitive
:eing 1rocessed. 0he value o:tained would :e the
sae value assigned to the in1ut varia:le i# declared
with the centroid <uali#ier.
#loat interpolateAt,ample B#loat interpolant,
int sampleC
vec! interpolateAt,ample Bvec! interpolant,
int sampleC
vec' interpolateAt,ample Bvec' interpolant,
int sampleC
vec% interpolateAt,ample Bvec% interpolant,
int sampleC
Return the value o# the in1ut interpolant varia:le at
the location o# sa1le nu:er sample. I#
ultisa1le :u##ers are not availa:le, the in1ut
varia:le will :e evaluated at the center o# the 1i4el.
I# sa1le sample does not e4ist, the 1osition used to
inter1olate the in1ut varia:le is unde#ined.
#loat interpolateAtOffset B#loat interpolant,
vec! o##setC
vec! interpolateAtOffset Bvec! interpolant,
vec! o##setC
vec' interpolateAtOffset Bvec' interpolant,
vec! o##setC
vec% interpolateAtOffset Bvec% interpolant,
vec! o##setC
Return the value o# the in1ut interpolant varia:le
sa1led at an o##set #ro the center o# the 1i4el
s1eci#ied :- o%%set. 0he two #loating91oint
co1onents o# o%%set, give the o##set in 1i4els in the x
and + directions, res1ectivel-. An o##set o# B$, $C
identi#ies the center o# the 1i4el. 0he range and
granularit- o# o##sets su11orted :- this #unction is
i1leentation9de1endent.
156
$.1# 6oise /unctions
8oise #unctions are availa:le to #ragent, geoetr-, and verte4 shaders. 0he- are stochastic #unctions that
can :e used to increase visual co1le4it-. Values returned :- the #ollowing noise #unctions give the
a11earance o# randoness, :ut are not trul- rando. 0he noise #unctions :elow are de#ined to have the
#ollowing characteristics:
0he return valueBsC are alwa-s in the range [91.$,1.$\, and cover at least the range [9$.+, $.+\, with a
2aussian9like distri:ution.
0he return valueBsC have an overall average o# $.$
0he- are re1eata:le, in that a 1articular in1ut value will alwa-s 1roduce the sae return value
0he- are statisticall- invariant under rotation Bi.e., no atter how the doain is rotated, it has the sae
statistical characterC
0he- have a statistical invariance under translation Bi.e., no atter how the doain is translated, it has
the sae statistical characterC
0he- t-1icall- give di##erent results under translation.
0he s1atial #re<uenc- is narrowl- concentrated, centered soewhere :etween $.* to 1.$.
0he- are "
1
continuous ever-where Bi.e., the #irst derivative is continuousC
S(nta- ,escription
#loat noise1 Bgen0-1e xC Returns a 1D noise value :ased on the in1ut value x.
vec! noise! Bgen0-1e xC Returns a !D noise value :ased on the in1ut value x.
vec' noise3 Bgen0-1e xC Returns a 'D noise value :ased on the in1ut value x.
vec% noise4 Bgen0-1e xC Returns a %D noise value :ased on the in1ut value x.
157
$.1! Geometr( Shader /unctions
0hese #unctions are onl- availa:le in geoetr- shaders. 0he- are descri:ed in ore de1th #ollowing the
ta:le.
S(nta- ,escription
void Omit,treamVertex Bint streamC Eit the current values o# out1ut varia:les to the current
out1ut 1riitive on strea stream. 0he arguent to stream
ust :e a constant integral e41ression. .n return #ro this
call, the values o# all out1ut varia:les are unde#ined.
"an onl- :e used i# ulti1le out1ut streas are su11orted.
void Ond,treamSrimitive Bint streamC "o1letes the current out1ut 1riitive on strea stream and
starts a new one. 0he arguent to stream ust :e a constant
integral e41ression. 8o verte4 is eitted.
"an onl- :e used i# ulti1le out1ut streas are su11orted.
void OmitVertex BC Eit the current values o# out1ut varia:les to the current
out1ut 1riitive. .n return #ro this call, the values o#
out1ut varia:les are unde#ined.
@hen ulti1le out1ut streas are su11orted, this is
e<uivalent to calling Omit,treamVertexB$C.
void OndSrimitive BC "o1letes the current out1ut 1riitive and starts a new one.
8o verte4 is eitted.
@hen ulti1le out1ut streas are su11orted, this is
e<uivalent to calling Ond,treamSrimitiveB$C.
0he #unction Omit,treamVertexBC s1eci#ies that a verte4 is co1leted. A verte4 is added to the current
out1ut 1riitive in verte4 strea stream using the current values o# all out1ut varia:les associated with
stream. 0hese include gl_Point!i0e, gl_ClipDistance, gl_La+er, gl_Position, gl_Primitive,D and
gl_Vie/port,n$ex. 0he values o# all out1ut varia:les #or all out1ut streas are unde#ined a#ter a call to
Omit,treamVertexBC. I# a geoetr- shader invocation has eitted ore vertices than 1eritted :- the
out1ut la-out <uali#ier max&vertices, the results o# calling Omit,treamVertexBC are unde#ined.
0he #unction Ond,treamSrimitiveBC s1eci#ies that the current out1ut 1riitive #or verte4 strea stream is
co1leted and a new out1ut 1riitive Bo# the sae t-1eC will started :- an- su:se<uent
Omit,treamVertexBC. 0his #unction does not eit a verte4. I# the out1ut la-out is declared to :e
E1ointsF, calling Ond,treamSrimitiveBC is o1tional.
A geoetr- shader starts with an out1ut 1riitive containing no vertices #or each strea. @hen a
geoetr- shader terinates, the current out1ut 1riitive #or each strea is autoaticall- co1leted. It is
not necessar- to call Ond,treamSrimitiveBC i# the geoetr- shader writes onl- a single 1riitive.
158
;ulti1le out1ut streas are su11orted onl- i# the out1ut 1riitive t-1e is declared to :e points. A
1rogra will #ail to link i# it contains a geoetr- shader calling Omit,treamVertexBC or
Ond,treamSrimitiveBC i# its in1ut 1riitive t-1e is not points.
159
$.1& Shader Invocation Control /unctions
0he shader invocation control #unction is availa:le onl- in tessellation control shaders. It is used to
control the relative e4ecution order o# ulti1le shader invocations used to 1rocess a 1atch, which are
otherwise e4ecuted with an unde#ined relative order.
S(nta- ,escription
void arrier BC 6or an- given static instance o# arrierBC, all tessellation control shader
invocations #or a single in1ut 1atch ust enter it :e#ore an- will :e
allowed to continue :e-ond it.
0he #unction arrierBC 1rovides a 1artiall- de#ined order o# e4ecution :etween shader invocations. 0his
ensures that values written :- one invocation 1rior to a given static instance o# arrierBC can :e sa#el-
read :- other invocations a#ter their call to the sae static instance arrierBC. Because invocations a-
e4ecute in unde#ined order :etween these :arrier calls, the values o# a 1er9verte4 or 1er91atch out1ut
varia:le will :e unde#ined in a nu:er o# cases enuerated in section %.'.) E.ut1ut Varia:lesF.
0he arrierBC #unction a- onl- :e 1laced inside the #unction mainBC o# the tessellation control shader
and a- not :e called within an- control #low. Barriers are also disallowed a#ter a return stateent in the
#unction mainBC.
$.1' Shader 8emor( Control /unctions
,haders o# all t-1es a- read and write the contents o# te4tures and :u##er o:Dects using iage varia:les.
@hile the order o# reads and writes within a single shader invocation is well9de#ined, the relative order o#
reads and writes to a single shared eor- address #ro ulti1le se1arate shader invocations is largel-
unde#ined. 0he order o# eor- accesses 1er#ored :- one shader invocation, as o:served :- other
shader invocations, is also largel- unde#ined :ut can :e controlled through eor- control #unctions. can
:e controlled through eor- control #unctions.0hisAdditionall-, the order o# accesses to ulti1le
eor- addresses 1er#ored :- a single shader invocation, as o:served :- other shader invocations, is
also unde#ined.
S(nta- ,escription
void memor"#arrier BC "ontrol the ordering o# eor- transactions issued :- a single shader
invocation.
0he :uilt9in memor"#arrierBC waits on the co1letion o# all eor- accesses resulting #ro the use o#
iage varia:les or atoic counters B:- the sae shader invocation calling memor"#arrier$%C and then
returns with no other e##ect. @hen this #unction returns, the results o# an- eor- stores 1er#ored using
coherent varia:les 1er#ored 1rior to the call will :e visi:le to an- #uture coherent eor- access to the
sae addresses #ro other shader invocations. In 1articular, the values written this wa- in one shader
16
stage are guaranteed to :e visi:le to coherent eor- accesses 1er#ored :- shader invocations in
su:se<uent stages when those invocations were triggered :- the e4ecution o# the original shader
invocation Be.g., #ragent shader invocations #or a 1riitive resulting #ro a 1articular geoetr- shader
invocationC.
161
,hading 3anguage 2raar #or "ore 5ro#ile
0BD: %.! changes 1lus su:routines
0he graar is #ed #ro the out1ut o# le4ical anal-sis. 0he tokens returned #ro le4ical anal-sis are
L*$)+ 9**" &"*D+ ,*@9"% #$+ @#$+
9(%DS L*$+#$@% ,* %")% &*( #& ,#)LD(, (%+@($ )X#+LO LD)% ,%&D@"+ )@9(*@+#$%
9'%L< 9'%L> 9'%L; #'%L< #'%L> #'%L; @'%L< @'%L> @'%L; '%L< '%L> '%L;
GD+< GD+> GD+; L%$+(*#, #$ *@+ #$*@+ @$#&*(G HD+LO )DGH"%
,'%L< ,'%L> ,'%L; ,GD+< ,GD+> ,GD+;
$*H%()H%L+#'% &"D+ )G**+O "DU*@+ HD+LO )DGH"%
GD+<T< GD+<T> GD+<T;
GD+>T< GD+>T> GD+>T;
GD+;T< GD+;T> GD+;T;
,GD+<T< ,GD+<T> ,GD+<T;
,GD+>T< ,GD+>T> ,GD+>T;
,GD+;T< ,GD+;T> ,GD+;T;
)DGH"%(0, )DGH"%(<, )DGH"%(>, )DGH"%(L@9% )DGH"%(0,)OD,*X )DGH"%(<,)OD,*X
)DGH"%(L@9%)OD,*X )DGH"%(0,D((DU )DGH"%(<,D((DU )DGH"%(0,D((DU)OD,*X
)DGH"%(<,D((DU)OD,*X #)DGH"%(0, #)DGH"%(<, #)DGH"%(>, #)DGH"%(L@9%
#)DGH"%(0,D((DU #)DGH"%(<,D((DU @)DGH"%(0, @)DGH"%(<, @)DGH"%(>,
@)DGH"%(L@9% @)DGH"%(0,D((DU @)DGH"%(<,D((DU
)DGH"%(<,(%L+ )DGH"%(<,(%L+)OD,*X #)DGH"%(<,(%L+ @)DGH"%(<,(%L+
)DGH"%(9@&&%( #)DGH"%(9@&&%( @)DGH"%(9@&&%(
)DGH"%(L@9%D((DU )DGH"%(L@9%D((DU)OD,*X
#)DGH"%(L@9%D((DU @)DGH"%(L@9%D((DU
)DGH"%(<,G) #)DGH"%(<,G) @)DGH"%(<,G)
)DGH"%(<,G)Drra/ #)DGH"%(<,G)Drra/ @)DGH"%(<,G)Drra/
#GD-%0, ##GD-%0, @#GD-%0, #GD-%<, ##GD-%<,
@#GD-%<, #GD-%>, ##GD-%>, @#GD-%>,
#GD-%<,(%L+ ##GD-%<,(%L+ @#GD-%<,(%L+
#GD-%L@9% ##GD-%L@9% @#GD-%L@9%
#GD-%9@&&%( ##GD-%9@&&%( @#GD-%9@&&%(
#GD-%0,D((DU ##GD-%0,D((DU @#GD-%0,D((DU
#GD-%<,D((DU ##GD-%<,D((DU @#GD-%<,D((DU
#GD-%L@9%D((DU ##GD-%L@9%D((DU @#GD-%L@9%D((DU
#GD-%<,G) ##GD-%<,G) @#GD-%<,G)
#GD-%<,G)D((DU ##GD-%<,G)D((DU @#GD-%<,G)D((DU
162
)+(@L+ '*#, XO#"%
#,%$+#&#%( +UH%!$DG% &"*D+L*$)+D$+ #$+L*$)+D$+ @#$+L*$)+D$+ 9**"L*$)+D$+
&#%",!)%"%L+#*$
"%&+!*H (#-O+!*H
#$L!*H ,%L!*H "%!*H -%!*H %W!*H $%!*H
D$,!*H *(!*H T*(!*H G@"!D))#-$ ,#'!D))#-$ D,,!D))#-$
G*,!D))#-$ "%&+!D))#-$ (#-O+!D))#-$ D$,!D))#-$ T*(!D))#-$ *(!D))#-$
)@9!D))#-$
"%&+!HD(%$ (#-O+!HD(%$ "%&+!9(DLS%+ (#-O+!9(DLS%+ "%&+!9(DL% (#-O+!9(DL% ,*+
L*GGD L*"*$ %W@D" )%G#L*"*$ 9D$- ,D)O +#",% H"@) )+D( )"D)O H%(L%$+
"%&+!D$-"% (#-O+!D$-"% '%(+#LD"!9D( LD(%+ DGH%()D$, W@%)+#*$
#$'D(#D$+ H(%L#)%
O#-O!H(%L#)#*$ G%,#@G!H(%L#)#*$ "*X!H(%L#)#*$ H(%L#)#*$
0he #ollowing descri:es the graar #or the .1en23 ,hading 3anguage in ters o# the a:ove tokens.
varia#le_i$enti%ier:
,D-&,",-R
primar+_expression:
varia#le_i$enti%ier
,&C(!&;&
E,&C(!&;&
"L(;&C(!&;&
<((LC(!&;&
D(E<L-C(!&;&
L-"&_P;R- expression R,)K&_P;R-
post%ix_expression:
primar+_expression
post%ix_expression L-"&_<R;CL-& integer_expression R,)K&_<R;CL-&
%unction_call
post%ix_expression D(& ",-LD_!-L-C&,(
post%ix_expression ,C_(P
post%ix_expression D-C_(P
integer_expression:
expression
163
%unction_call:
%unction_call_or_met'o$
%unction_call_or_met'o$:
%unction_call_generic
post%ix_expression D(& %unction_call_generic
%unction_call_generic:
%unction_call_'ea$er_/it'_parameters R,)K&_P;R-
%unction_call_'ea$er_no_parameters R,)K&_P;R-
%unction_call_'ea$er_no_parameters:
%unction_call_'ea$er V(,D
%unction_call_'ea$er
%unction_call_'ea$er_/it'_parameters:
%unction_call_'ea$er assignment_expression
%unction_call_'ea$er_/it'_parameters C(77; assignment_expression
%unction_call_'ea$er:
%unction_i$enti%ier L-"&_P;R-
DD )rammar ote: Constructors loo. li.e %unctions* #ut lexical anal+sis recogni0e$ most o% t'em as
DD .e+/or$s. &'e+ are no/ recogni0e$ t'roug' Mt+pe_speci%ierN.
DD 7et'o$s 3.lengt'4* su#routine arra+ calls* an$ i$enti%iers are recogni0e$ t'roug' post%ix_expression.
%unction_i$enti%ier:
t+pe_speci%ier
post%ix_expression
,D-&,",-R
",-LD_!-L-C&,(
unar+_expression:
post%ix_expression
,C_(P unar+_expression
D-C_(P unar+_expression
unar+_operator unar+_expression
DD )rammar ote: o tra$itional st+le t+pe casts.
164
unar+_operator:
PLE!
D;!K
<;)
&,LD-
DD )rammar ote: o I=I or IOI unar+ ops. Pointers are not supporte$.
multiplicative_expression:
unar+_expression
multiplicative_expression !&;R unar+_expression
multiplicative_expression !L;!K unar+_expression
multiplicative_expression P-RC-& unar+_expression
a$$itive_expression:
multiplicative_expression
a$$itive_expression PLE! multiplicative_expression
a$$itive_expression D;!K multiplicative_expression
s'i%t_expression:
a$$itive_expression
s'i%t_expression L-"&_(P a$$itive_expression
s'i%t_expression R,)K&_(P a$$itive_expression
relational_expression:
s'i%t_expression
relational_expression L-"&_;)L- s'i%t_expression
relational_expression R,)K&_;)L- s'i%t_expression
relational_expression L-_(P s'i%t_expression
relational_expression )-_(P s'i%t_expression
e1ualit+_expression:
relational_expression
e1ualit+_expression -P_(P relational_expression
e1ualit+_expression -_(P relational_expression
an$_expression:
e1ualit+_expression
an$_expression ;7P-R!;D e1ualit+_expression
165
exclusive_or_expression:
an$_expression
exclusive_or_expression C;R-& an$_expression
inclusive_or_expression:
exclusive_or_expression
inclusive_or_expression V-R&,C;L_<;R exclusive_or_expression
logical_an$_expression:
inclusive_or_expression
logical_an$_expression ;D_(P inclusive_or_expression
logical_xor_expression:
logical_an$_expression
logical_xor_expression Q(R_(P logical_an$_expression
logical_or_expression:
logical_xor_expression
logical_or_expression (R_(P logical_xor_expression
con$itional_expression:
logical_or_expression
logical_or_expression PE-!&,( expression C(L( assignment_expression
assignment_expression:
con$itional_expression
unar+_expression assignment_operator assignment_expression
assignment_operator:
-PE;L
7EL_;!!,)
D,V_;!!,)
7(D_;!!,)
;DD_;!!,)
!E<_;!!,)
L-"&_;!!,)
R,)K&_;!!,)
;D_;!!,)
Q(R_;!!,)
166
(R_;!!,)
expression:
assignment_expression
expression C(77; assignment_expression
constant_expression:
con$itional_expression
$eclaration:
%unction_protot+pe !-7,C(L(
init_$eclarator_list !-7,C(L(
PR-C,!,( precision_1uali%ier t+pe_speci%ier_no_prec !-7,C(L(
t+pe_1uali%ier ,D-&,",-R L-"&_<R;C- struct_$eclaration_list R,)K&_<R;C- !-7,C(L(
t+pe_1uali%ier ,D-&,",-R L-"&_<R;C- struct_$eclaration_list R,)K&_<R;C-
,D-&,",-R !-7,C(L(
,D-&,",-R L-"&_<R;CL-& R,)K&_<R;CL-& !-7,C(L(
,D-&,",-R L-"&_<R;CL-& constant_expression R,)K&_<R;CL-& !-7,C(L(
t+pe_1uali%ier !-7,C(L(
t+pe_1uali%ier ,D-&,",-R !-7,C(L(
t+pe_1uali%ier ,D-&,",-R i$enti%ier_list !-7,C(L(
i$enti%ier_list:
C(77; ,D-&,",-R
i$enti%ier_list C(77; ,D-&,",-R
%unction_protot+pe:
%unction_$eclarator R,)K&_P;R-
%unction_$eclarator:
%unction_'ea$er
%unction_'ea$er_/it'_parameters
%unction_'ea$er_/it'_parameters:
%unction_'ea$er parameter_$eclaration
%unction_'ea$er_/it'_parameters C(77; parameter_$eclaration
%unction_'ea$er:
167
%ull+_speci%ie$_t+pe ,D-&,",-R L-"&_P;R-
parameter_$eclarator:
t+pe_speci%ier ,D-&,",-R
t+pe_speci%ier ,D-&,",-R L-"&_<R;CL-& constant_expression R,)K&_<R;CL-&
parameter_$eclaration:
parameter_t+pe_1uali%ier parameter_1uali%ier t+pe_1uali%ier parameter_$eclarator
parameter_1uali%ier parameter_$eclarator
parameter_t+pe_1uali%ier parameter_1uali%ier t+pe_1uali%ier parameter_t+pe_speci%ier
parameter_1uali%ier parameter_t+pe_speci%ier
parameter_1uali%ier:
D= empt+ =D
,
(E&
,(E&
parameter_t+pe_speci%ier:
t+pe_speci%ier
init_$eclarator_list:
single_$eclaration
init_$eclarator_list C(77; ,D-&,",-R
init_$eclarator_list C(77; ,D-&,",-R L-"&_<R;CL-& R,)K&_<R;CL-&
init_$eclarator_list C(77; ,D-&,",-R L-"&_<R;CL-& constant_expression
R,)K&_<R;CL-&
init_$eclarator_list C(77; ,D-&,",-R L-"&_<R;CL-&
R,)K&_<R;CL-& -PE;L initiali0er
init_$eclarator_list C(77; ,D-&,",-R L-"&_<R;CL-& constant_expression
init_$eclarator_list C(77; ,D-&,",-R -PE;L initiali0er
single_$eclaration:
%ull+_speci%ie$_t+pe
%ull+_speci%ie$_t+pe ,D-&,",-R
%ull+_speci%ie$_t+pe ,D-&,",-R L-"&_<R;CL-& R,)K&_<R;CL-&
%ull+_speci%ie$_t+pe ,D-&,",-R L-"&_<R;CL-& constant_expression R,)K&_<R;CL-&
%ull+_speci%ie$_t+pe ,D-&,",-R L-"&_<R;CL-& R,)K&_<R;CL-& -PE;L initiali0er
%ull+_speci%ie$_t+pe ,D-&,",-R L-"&_<R;CL-& constant_expression
168
%ull+_speci%ie$_t+pe ,D-&,",-R -PE;L initiali0er
,V;R,;& ,D-&,",-R
DD )rammar ote: o IenumI* or It+pe$e%I.
%ull+_speci%ie$_t+pe:
t+pe_speci%ier
t+pe_1uali%ier t+pe_speci%ier
invariant_1uali%ier:
,V;R,;&
interpolation_1uali%ier:
!7((&K
"L;&
(P-R!P-C&,V-
la+out_1uali%ier:
L;R(E& L-"&_P;R- la+out_1uali%ier_i$_list R,)K&_P;R-
la+out_1uali%ier_i$_list:
la+out_1uali%ier_i$
la+out_1uali%ier_i$_list C(77; la+out_1uali%ier_i$
la+out_1uali%ier_i$:
,D-&,",-R
,D-&,",-R -PE;L ,&C(!&;&
parameter_t+pe_1uali%ier:
C(!&
precise_1uali%ier:
PR-C,!-
t+pe_1uali%ier:
single_t+pe_1uali%ier
t+pe_1uali%ier single_t+pe_1uali%ier
169
single_t+pe_1uali%ier:
storage_1uali%ier
la+out_1uali%ier
precision_1uali%ier
la+out_1uali%ier storage_1uali%ier
interpolation_1uali%ier storage_1uali%ier
interpolation_1uali%ier
invariant_1uali%ier storage_1uali%ier
invariant_1uali%ier interpolation_1uali%ier storage_1uali%ier
invariant_1uali%ier
precise_1uali%ier
storage_1uali%ier:
C(!&
,(E&
,
(E&
C-&R(,D ,
C-&R(,D (E&
P;&CK ,
P;&CK (E&
!;7PL- ,
!;7PL- (E&
E,"(R7
!E<R(E&,-
!E<R(E&,- L-"&_P;R- ,D-&,",-R t+pe_name_list R,)K&_P;R-
t+pe_name_list:
&RP-_;7-
t+pe_name_list C(77; &RP-_;7-
t+pe_speci%ier:
t+pe_speci%ier_no_prec
precision_1uali%ier t+pe_speci%ier_no_prec
t+pe_speci%ier_no_prec:
t+pe_speci%ier_nonarra+
t+pe_speci%ier_nonarra+ L-"&_<R;CL-& R,)K&_<R;CL-&
17
t+pe_speci%ier_nonarra+ L-"&_<R;CL-& constant_expression R,)K&_<R;CL-&
t+pe_speci%ier_nonarra+:
V(,D
"L(;&
D(E<L-
,&
E,&
<((L
V-C2
V-CA
V-C4
DV-C2
DV-CA
DV-C4
<V-C2
<V-CA
<V-C4
,V-C2
,V-CA
,V-C4
EV-C2
EV-CA
EV-C4
7;&2
7;&A
7;&4
7;&2Q2
7;&2QA
7;&2Q4
7;&AQ2
7;&AQA
7;&AQ4
7;&4Q2
7;&4QA
7;&4Q4
D7;&2
171
D7;&A
D7;&4
D7;&2Q2
D7;&2QA
D7;&2Q4
D7;&AQ2
D7;&AQA
D7;&AQ4
D7;&4Q2
D7;&4QA
D7;&4Q4
!;7PL-R1D
!;7PL-R2D
!;7PL-RAD
!;7PL-RCE<-
!;7PL-R1D!K;D(S
!;7PL-R2D!K;D(S
!;7PL-RCE<-!K;D(S
!;7PL-R1D;RR;R
!;7PL-R2D;RR;R
!;7PL-R1D;RR;R!K;D(S
!;7PL-R2D;RR;R!K;D(S
!;7PL-RCE<-;RR;R
!;7PL-RCE<-;RR;R!K;D(S
,!;7PL-R1D
,!;7PL-R2D
,!;7PL-RAD
,!;7PL-RCE<-
,!;7PL-R1D;RR;R
,!;7PL-R2D;RR;R
,!;7PL-RCE<-;RR;R
E!;7PL-R1D
E!;7PL-R2D
E!;7PL-RAD
E!;7PL-RCE<-
E!;7PL-R1D;RR;R
E!;7PL-R2D;RR;R
172
E!;7PL-RCE<-;RR;R
!;7PL-R2DR-C&
!;7PL-R2DR-C&!K;D(S
,!;7PL-R2DR-C&
E!;7PL-R2DR-C&
!;7PL-R<E""-R
,!;7PL-R<E""-R
E!;7PL-R<E""-R
!;7PL-R2D7!
,!;7PL-R2D7!
E!;7PL-R2D7!
!;7PL-R2D7!;RR;Rrra+
,!;7PL-R2D7!;RR;Rrra+
E!;7PL-R2D7!;RR;Rrra+
,7;)-1D
,,7;)-1D
E,7;)-1D
,7;)-2D
,,7;)-2D
E,7;)-2D
,7;)-AD
,,7;)-AD
E,7;)-AD
,7;)-2DR-C&
,,7;)-2DR-C&
E,7;)-2DR-C&
,7;)-CE<-
,,7;)-CE<-
E,7;)-CE<-
,7;)-<E""-R
,,7;)-<E""-R
E,7;)-<E""-R
,7;)-1D;RR;R
,,7;)-1D;RR;R
E,7;)-1D;RR;R
,7;)-2D;RR;R
,,7;)-2D;RR;R
173
E,7;)-2D;RR;R
,7;)-CE<-;RR;R
,,7;)-CE<-;RR;R
E,7;)-CE<-;RR;R
,7;)-2D7!
,,7;)-2D7!
E,7;)-2D7!
,7;)-2D7!;RR;R
,,7;)-2D7!;RR;R
E,7;)-2D7!;RR;R
struct_speci%ier
&RP-_;7-
precision_1uali%ier:
K,)K_PR-C,!,(
7-D,E7_PR-C,!,(
L(S_PR-C,!,(
struct_speci%ier:
!&REC& ,D-&,",-R L-"&_<R;C- struct_$eclaration_list R,)K&_<R;C-
!&REC& L-"&_<R;C- struct_$eclaration_list R,)K&_<R;C-
struct_$eclaration_list:
struct_$eclaration
struct_$eclaration_list struct_$eclaration
struct_$eclaration:
t+pe_speci%ier struct_$eclarator_list !-7,C(L(
t+pe_1uali%ier t+pe_speci%ier struct_$eclarator_list !-7,C(L(
struct_$eclarator_list:
struct_$eclarator
struct_$eclarator_list C(77; struct_$eclarator
struct_$eclarator:
,D-&,",-R
,D-&,",-R L-"&_<R;CL-& R,)K&_<R;CL-&
,D-&,",-R L-"&_<R;CL-& constant_expression R,)K&_<R;CL-&
initiali0er:
assignment_expression
174
$eclaration_statement:
$eclaration
statement:
compoun$_statement
simple_statement
DD )rammar ote: la#ele$ statements %or !S,&CK onl+2 IgotoI is not supporte$.
simple_statement:
$eclaration_statement
expression_statement
selection_statement
s/itc'_statement
case_la#el
iteration_statement
8ump_statement
compoun$_statement:
L-"&_<R;C- R,)K&_<R;C-
L-"&_<R;C- statement_list R,)K&_<R;C-
statement_no_ne/_scope:
compoun$_statement_no_ne/_scope
simple_statement
compoun$_statement_no_ne/_scope:
L-"&_<R;C- R,)K&_<R;C-
L-"&_<R;C- statement_list R,)K&_<R;C-
statement_list:
statement
statement_list statement
expression_statement:
!-7,C(L(
expression !-7,C(L(
selection_statement:
175
," L-"&_P;R- expression R,)K&_P;R- selection_rest_statement
selection_rest_statement:
statement -L!- statement
statement
con$ition:
expression
%ull+_speci%ie$_t+pe ,D-&,",-R -PE;L initiali0er
s/itc'_statement:
!S,&CK L-"&_P;R- expression R,)K&_P;R- L-"&_<R;C- s/itc'_statement_list
R,)K&_<R;C-
s/itc'_statement_list:
D= not'ing =D
statement_list
case_la#el:
C;!- expression C(L(
D-";EL& C(L(
iteration_statement:
SK,L- L-"&_P;R- con$ition R,)K&_P;R- statement_no_ne/_scope
D( statement SK,L- L-"&_P;R- expression R,)K&_P;R- !-7,C(L(
"(R L-"&_P;R- %or_init_statement %or_rest_statement R,)K&_P;R-
statement_no_ne/_scope
%or_init_statement:
expression_statement
$eclaration_statement
con$itionopt:
con$ition
D= empt+ =D
%or_rest_statement:
con$itionopt !-7,C(L(
con$itionopt !-7,C(L( expression
8ump_statement:
C(&,E- !-7,C(L(
<R-;L !-7,C(L(
176
R-&ER !-7,C(L(
R-&ER expression !-7,C(L(
D,!C;RD !-7,C(L( DD "ragment s'a$er onl+.
DD )rammar ote: o IgotoI. )otos are not supporte$.
translation_unit:
external_$eclaration
translation_unit external_$eclaration
external_$eclaration:
%unction_$e%inition
$eclaration
%unction_$e%inition:
%unction_protot+pe compoun$_statement_no_ne/_scope
177

GLSL Specification 4.20.11

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

GLSL Specification 4.20.11

Transféré par

Droits d'auteur :

Formats disponibles

The OpenGL

Vous aimerez peut-être aussi