Вы находитесь на странице: 1из 161

The OpenGL

Shading Language
Language Version: 4.10
Document Revision: 6
24-Jul-2010
Editor: John Kessenich, Intel
Version 1.1 Authors: John Kessenich, Dave Baldwin, Randi Rost
Copyright (c) 2008-2010 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.!.! "hanges #ro revision %...............................................................................................&
1.!.& "hanges #ro revision &...............................................................................................&
1.!.% "hanges #ro revision !...............................................................................................&
1.!.$ "hanges #ro revision 1...............................................................................................&
1.!.' (uar) o# "hanges #ro Version %.**..................................................................... &
1.& +verview.............................................................................................................................. %
1.% Error ,andling......................................................................................................................%
1.$ -).ogra.hical "onventions................................................................................................. %
1.' De.recation.......................................................................................................................... %
! +verview o# +.en/0 (hading....................................................................................................$
!.1 Verte1 2rocessor.................................................................................................................. $
!.! -essellation "ontrol 2rocessor.............................................................................................$
!.& -essellation Evaluation 2rocessor........................................................................................'
!.% /eoetr) 2rocessor............................................................................................................. '
!.$ 3ragent 2rocessor.............................................................................................................. '
& Basics.......................................................................................................................................... 4
&.1 "haracter (et........................................................................................................................ 4
&.! (ource (trings...................................................................................................................... 4
&.& 2re.rocessor......................................................................................................................... 5
&.% "oents.......................................................................................................................... 1&
&.$ -okens................................................................................................................................ 1&
&.' Ke)words............................................................................................................................1&
&.4 Identi#iers........................................................................................................................... 1$
&.5 De#initions..........................................................................................................................1'
&.5.1 (tatic 6se....................................................................................................................1'
&.5.! 6ni#or and 7on86ni#or "ontrol 3low.................................................................. 1'
&.5.& D)naicall) 6ni#or E1.ressions.............................................................................14
% Varia9les and -).es..................................................................................................................15
%.1 Basic -).es........................................................................................................................ 15
%.1.1 Void............................................................................................................................ !1
%.1.! Booleans..................................................................................................................... !1
%.1.& Integers....................................................................................................................... !!
%.1.% 3loats.......................................................................................................................... !%
%.1.$ Vectors........................................................................................................................!$
%.1.' :atrices...................................................................................................................... !$
%.1.4 (a.lers..................................................................................................................... !$
3
%.1.5 (tructures.................................................................................................................... !'
%.1.; Arra)s......................................................................................................................... !4
%.1.1* I.licit "onversions................................................................................................ !;
%.! (co.ing...............................................................................................................................&*
%.& (torage <uali#iers...............................................................................................................&!
%.&.1 De#ault (torage <uali#ier............................................................................................&&
%.&.! "onstant <uali#ier...................................................................................................... &&
%.&.& "onstant E1.ressions................................................................................................. &&
%.&.% In.uts.......................................................................................................................... &%
%.&.$ 6ni#or...................................................................................................................... &'
%.&.' +ut.uts....................................................................................................................... &4
%.&.4 Inter#ace Blocks.......................................................................................................... &;
%.&.5 0a)out <uali#iers........................................................................................................ %!
%.&.5.1 In.ut 0a)out <uali#iers....................................................................................... %!
%.&.5.! +ut.ut 0a)out <uali#iers.................................................................................... %4
%.&.5.& 6ni#or Block 0a)out <uali#iers....................................................................... $*
%.&.; Inter.olation................................................................................................................$!
%.&.;.1 Redeclaring Built8in Inter.olation Varia9les in the "o.ati9ilit) 2ro#ile.........$&
%.% 2araeter <uali#iers...........................................................................................................$%
%.$ 2recision and 2recision <uali#iers..................................................................................... $%
%.$.1 Range and 2recision................................................................................................... $%
%.$.! 2recision <uali#iers.................................................................................................... $$
%.$.& De#ault 2recision <uali#iers....................................................................................... $'
%.$.% Availa9le 2recision <uali#iers....................................................................................$4
%.' Variance and the Invariant <uali#ier.................................................................................. $4
%.'.1 -he Invariant <uali#ier............................................................................................... $4
%.'.! Invariance o# "onstant E1.ressions........................................................................... $5
%.4 -he 2recise <uali#ier..........................................................................................................$5
%.5 +rder o# <uali#ication........................................................................................................ '*
$ +.erators and E1.ressions........................................................................................................'1
$.1 +.erators............................................................................................................................ '1
$.! Arra) +.erations............................................................................................................... '!
$.& 3unction "alls.................................................................................................................... '!
$.% "onstructors....................................................................................................................... '!
$.%.1 "onversion and (calar "onstructors.......................................................................... '!
$.%.! Vector and :atri1 "onstructors................................................................................. '&
$.%.& (tructure "onstructors................................................................................................ '$
$.%.% Arra) "onstructors..................................................................................................... ''
$.$ Vector "o.onents............................................................................................................''
$.' :atri1 "o.onents............................................................................................................'5
$.4 (tructure and Arra) +.erations..........................................................................................'5
$.5 Assignents....................................................................................................................... ';
4
$.; E1.ressions........................................................................................................................ 4*
$.1* Vector and :atri1 +.erations..........................................................................................4&
' (tateents and (tructure...........................................................................................................4$
'.1 3unction De#initions...........................................................................................................4'
'.1.1 3unction "alling "onventions.................................................................................... 45
'.1.! (u9routines................................................................................................................. 5*
'.! (election............................................................................................................................. 51
'.& Iteration.............................................................................................................................. 5!
'.% Ju.s..................................................................................................................................5&
4 Built8in Varia9les......................................................................................................................5%
4.1 Built8In 0anguage Varia9les.............................................................................................. 5%
4.1.1 "o.ati9ilit) 2ro#ile Built8In 0anguage Varia9les....................................................;1
4.! "o.ati9ilit) 2ro#ile Verte1 (hader Built8In In.uts......................................................... ;%
4.& Built8In "onstants.............................................................................................................. ;%
4.&.1 "o.ati9ilit) 2ro#ile Built8In "onstants....................................................................;$
4.% Built8In 6ni#or (tate....................................................................................................... ;$
4.%.1 "o.ati9ilit) 2ro#ile (tate......................................................................................... ;'
5 Built8in 3unctions................................................................................................................... 1**
5.1 Angle and -rigonoetr) 3unctions..................................................................................1*1
5.! E1.onential 3unctions......................................................................................................1*&
5.& "oon 3unctions.......................................................................................................... 1*%
5.% 3loating82oint 2ack and 6n.ack 3unctions..................................................................... 11*
5.$ /eoetric 3unctions........................................................................................................ 11!
5.' :atri1 3unctions.............................................................................................................. 11%
5.4 Vector Relational 3unctions.............................................................................................11'
5.5 Integer 3unctions.............................................................................................................. 115
5.; -e1ture 3unctions.............................................................................................................1!*
5.;.1 -e1ture <uer) 3unctions.......................................................................................... 1!1
5.;.! -e1el 0ooku. 3unctions........................................................................................... 1!&
5.;.& -e1ture /ather Instructions...................................................................................... 1&*
5.;.% -he #ollowing te1ture #unctions are de.recated....................................................... 1&&
5.1* 3ragent 2rocessing 3unctions......................................................................................1&$
5.1*.1 Derivative 3unctions.............................................................................................. 1&$
5.1*.! Inter.olation 3unctions...........................................................................................1&'
5.11 7oise 3unctions..............................................................................................................1&4
5.1! /eoetr) (hader 3unctions........................................................................................... 1&;
5.1& (hader Invocation "ontrol 3unctions.............................................................................1%1
; (hading 0anguage /raar...................................................................................................1%!
5
1 Introduction
-his docuent s.eci#ies onl) version %.1* o# the +.en/0 (hading 0anguage. It re=uires >>VER(I+7>>
to su9stitute %1*, and re=uires #version to acce.t onl) %1*. I# #version is declared with a saller
nu9er, the language acce.ted is a .revious version o# the shading language, which will 9e su..orted
de.ending on the version and t).e o# conte1t in the +.en/0 A2I. (ee the +.en/0 /ra.hics ()ste
(.eci#ication, Version %.1, #or details on what language versions are su..orted.
2revious versions o# the +.en/0 (hading 0anguage, as well as the +.en/0 E( (hading 0anguage, are
not strict su9sets o# the version s.eci#ied here, .articularl) with res.ect to .recision, nae8hiding rules,
and treatent o# inter#ace varia9les. (ee the s.eci#ication corres.onding to a .articular language version
#or details s.eci#ic to that version o# the language.
All +.en/0 /ra.hics ()ste (.eci#ication re#erences in this s.eci#ication are to version %.1.
1
1 Introduction
1.1 Acknowledgments
-his s.eci#ication is 9ased on the work o# those who contri9uted to .ast versions o# the +.en/0
0anguage (.eci#ication, the +.en/0 E( !.* 0anguage (.eci#ication, and the #ollowing contri9utors to
this version:
2at Brown, 7vidia
Je## Bol?, 7vidia
3rank "hen
2ierre Boudier, A:D
2iers Daniell, 7vidia
"hris Dodd, 7vidia
Eric @erness, 7vidia
7ick ,aeel, A:D
Jason /reen, -rans/aing
Brent Insko, Intel
Jon 0eech
Bill 0icea8Kane, A:D
Daniel Koch, -ransgaing
Barthold 0ichten9elt, 7vidia
Bruce :err), AR:
Ro9ert +hannessian
Acorn 2oole), 7vidia
Kevin Rogovin
Ian Roanick, Intel
/reg Roth, 7vidia
/raha (ellers, A:D
Dave (hreiner, AR:
Jere) (andel, A..le
Ro9ert (i.son, <ualco
:ark Aoung, A:D
1.2 Changes
1.2.1 Changes from revision 5
(ection 4.1 #or redeclaring 9uilt8in 9locks: "lari#) that it is when ulti.le shaders declare 9locks
within the same interface that the 9lock de#initions ust atch within that inter#ace.
(everal .laces had language inconsistentl) liiting la)out =uali#iers too narrowl) #or the newl) added
linking locations. -hese .laces were generali?e to discuss what la)out =uali#iers are allowed, rather
than atte.ting to list is disallowed.
Reove B#i1edC #ro the descri.tion o# interpolateAtOffset, it was e1traneous.
Descri9e how an) locations dou9le t).es use when assigning in.uts and out.uts to locations.
Added samplerCubeShadow to the t).e ta9le in section %.1. It was alread) .art o# the s.eci#ication,
Dust issing #ro this ta9le.
2
1 Introduction
1.2.2 Changes from revision
Added the changes section #or revision &.
:inor u.dates #or linking o# ulti.le .rogras, s)ncing with the latest e1tension s.eci#ication #or
se.arate shader o9Dects E/0>ARB>se.arate>shader>o9DectsF and incor.orating other editorial
#eed9ack.
1.2.! Changes from revision !
Rela1ed .recision re=uireents #or expEF and srtEF.
3or esta9lishing inter#aces 9etween .rogras, no longer allow general glo9al redeclaration o# 9uilt8in
9lock e9ers outside o# 9lock redeclarations.
1.2. Changes from revision 2
Add the inter#ace 9lock gl!er"ragment and redeclaration o# inter#ace 9locks to esta9lish inter#aces
9etween .rogras #or 9uilt8in varia9les.
6.dated soe .recisions with range8s.eci#ic 9ehavior.
1.2.5 Changes from revision 1
Added su..ort #or ulti.le .rogras.
Edited all use o# G.rograG #or consistenc) with su..ort o# 9oth a single .rogra or ulti.le
.rogras to esta9lish a co.lete .i.eline.
:inor graatical #i1es.
1.2." Summar# of Changes from $ersion .%%
7ote: 7o #eatures were reoved or de.recated 9etween versions %.** and %.1*.
(u..ort #or .artitioning shaders into ulti.le .rogras to .rovide light8weight i1ing o# di##erent
shader stages.
I.roved co.ati9ilit) with the +.en/0 E( (hading 0anguage.
E1.licitl) state the re=uired .recision o# ost o.erations.
Add '%89it #loating8.oint attri9utes #or verte1 shader in.uts.
(u..ort view.ort arra)s so where the geoetr) shader selects which view.ort arra) will trans#or its
out.ut.
3
1 Introduction
1.! Overvie&
-his docuent descri9es #he $%en&L 'ha(ing Language) version %.1*.
Inde.endent co.ilation units written in this language are called sha(ers. A %rogram is a set o# shaders
that are co.iled and linked together, co.letel) creating one or ore o# the .rograa9le stages o# the
+.en/0 .i.eline. All the shaders #or a single .rograa9le stage ust 9e within the sae .rogra. A
co.lete set o# .rograa9le stages can 9e .ut into a single .rogra or the stages can 9e .artitioned
across ulti.le .rogras. -he ai o# this docuent is to thoroughl) s.eci#) the .rograing language.
-he +.en/0 /ra.hics ()ste (.eci#ication will s.eci#) the +.en/0 entr) .oints used to ani.ulate and
counicate with .rogras and shaders.
1. 'rror (andling
"o.ilers, in general, acce.t .rogras that are ill8#ored, due to the i.ossi9ilit) o# detecting all ill8
#ored .rogras. 2orta9ilit) is onl) ensured #or well8#ored .rogras, which this s.eci#ication
descri9es. "o.ilers are encouraged to detect ill8#ored .rogras and issue diagnostic essages, 9ut are
not re=uired to do so #or all cases. "o.ilers are re=uired to return essages regarding le1icall),
graaticall), or seanticall) incorrect shaders.
1.5 T#pographical Conventions
Italic, 9old, and #ont choices have 9een used in this s.eci#ication .riaril) to i.rove reada9ilit). "ode
#ragents use a #i1ed width #ont. Identi#iers e9edded in te1t are italici?ed. Ke)words e9edded in te1t
are 9old. +.erators are called 9) their nae, #ollowed 9) their s)9ol in 9old in .arentheses. -he
clari#)ing graar #ragents in the te1t use 9old #or literals and italics #or non8terinals. -he o##icial
graar in section ; B(hading 0anguage /raarC uses all ca.itals #or terinals and lower case #or
non8terinals.
1." )eprecation
2revious versions o# the +.en/0 (hading 0anguage de.recated soe #eatures. -hese are clearl) called
out in this s.eci#ication as Bde.recatedC. -he) are still .resent in this version o# the language, 9ut are
targeted #or .otential reoval in a #uture version o# the shading language. -he +.en/0 A2I has a
#orward co.ati9ilit) ode that will disallow use o# de.recated #eatures. I# co.iling in a ode where
use o# de.recated #eatures is disallowed, their use causes co.ile tie errors. (ee the +.en/0 /ra.hics
()ste (.eci#ication #or details on what causes de.recated language #eatures to 9e acce.ted or to return
an error.
4
2 Overvie& of OpenGL Shading
-he +.en/0 (hading 0anguage is actuall) several closel) related languages. -hese languages are used
to create shaders #or each o# the .rograa9le .rocessors contained in the +.en/0 .rocessing .i.eline.
"urrentl), these .rocessors are the verte1, tessellation control, tessellation evaluation, geoetr), and
#ragent .rocessors.
6nless otherwise noted in this .a.er, a language #eature a..lies to all languages, and coon usage will
re#er to these languages as a single language. -he s.eci#ic languages will 9e re#erred to 9) the nae o#
the .rocessor the) target: verte1, tessellation control, tessellation evaluation, geoetr), or #ragent.
:ost +.en/0 state is not tracked or ade availa9le to shaders. -).icall), user8de#ined varia9les will 9e
used #or counicating 9etween di##erent stages o# the +.en/0 .i.eline. ,owever, a sall aount o#
state is still tracked and autoaticall) ade availa9le to shaders, and there are a #ew 9uilt8in varia9les #or
inter#aces 9etween di##erent stages o# the +.en/0 .i.eline.
2.1 $erte* +rocessor
-he verte* %rocessor is a .rograa9le unit that o.erates on incoing vertices and their associated data.
"o.ilation units written in the +.en/0 (hading 0anguage to run on this .rocessor are called verte*
sha(ers. @hen a co.lete set o# verte1 shaders are co.iled and linked, the) result in a verte* sha(er
e*ecuta+le that runs on the verte1 .rocessor.
-he verte1 .rocessor o.erates on one verte1 at a tie. It does not re.lace gra.hics o.erations that re=uire
knowledge o# several vertices at a tie.
2.2 Tessellation Control +rocessor
-he tessellation control .rocessor is a .rograa9le unit that o.erates on a .atch o# incoing vertices
and their associated data, eitting a new out.ut .atch. "o.ilation units written in the +.en/0 (hading
0anguage to run on this .rocessor are called tessellation control shaders. @hen a co.lete set o#
tessellation control shaders are co.iled and linked, the) result in a tessellation control shader e1ecuta9le
that runs on the tessellation control .rocessor.
-he tessellation control shader is invoked #or each verte1 o# the out.ut .atch. Each invocation can read
the attri9utes o# an) verte1 in the in.ut or out.ut .atches, 9ut can onl) write .er8verte1 attri9utes #or the
corres.onding out.ut .atch verte1. -he shader invocations collectivel) .roduce a set o# .er8.atch
attri9utes #or the out.ut .atch. A#ter all tessellation control shader invocations have co.leted, the out.ut
vertices and .er8.atch attri9utes are asse9led to #or a .atch to 9e used 9) su9se=uent .i.eline stages.
5
2 Overview of OpenGL Shading
-essellation control shader invocation run ostl) inde.endentl), with unde#ined relative e1ecution order.
,owever, the 9uilt8in #unction 9arrierEF can 9e used to control e1ecution order 9) s)nchroni?ing
invocations, e##ectivel) dividing tessellation control shader e1ecution into a set o# .hases. -essellation
control shaders will get unde#ined results i# one invocation reads a .er8verte1 or .er8.atch attri9ute
written 9) another invocation at an) .oint during the sae .hase, or i# two invocations atte.t to write
di##erent values to the sae .er8.atch out.ut in a single .hase.
2.! Tessellation 'valuation +rocessor
-he tessellation evaluation .rocessor is a .rograa9le unit that evaluates the .osition and other
attri9utes o# a verte1 generated 9) the tessellation .riitive generator, using a .atch o# incoing vertices
and their associated data. "o.ilation units written in the +.en/0 (hading 0anguage to run on this
.rocessor are called tessellation evaluation shaders. @hen a co.lete set o# tessellation evaluation
shaders are co.iled and linked, the) result in a tessellation evaluation shader e1ecuta9le that runs on the
tessellation evaluation .rocessor.
Each invocation o# the tessellation evaluation e1ecuta9le co.utes the .osition and attri9utes o# a single
verte1 generated 9) the tessellation .riitive generator. -he e1ecuta9le can read the attri9utes o# an)
verte1 in the in.ut .atch, .lus the tessellation coordinate, which is the relative location o# the verte1 in the
.riitive 9eing tessellated. -he e1ecuta9le writes the .osition and other attri9utes o# the verte1.
2. Geometr# +rocessor
-he geometr, %rocessor is a .rograa9le unit that o.erates on data #or incoing vertices #or a .riitive
asse9led a#ter verte1 .rocessing and out.uts a se=uence o# vertices #oring out.ut .riitives.
"o.ilation units written in the +.en/0 (hading 0anguage to run on this .rocessor are called geometr,
sha(ers. @hen a co.lete set o# geoetr) shaders are co.iled and linked, the) result in a geometr,
sha(er e*ecuta+le that runs on the geoetr) .rocessor.
A single invocation o# the geoetr) shader e1ecuta9le on the geoetr) .rocessor will o.erate on a
declared in.ut .riitive with a #i1ed nu9er o# vertices. -his single invocation can eit a varia9le
nu9er o# vertices that are asse9led into .riitives o# a declared out.ut .riitive t).e and .assed to
su9se=uent .i.eline stages.
2.5 ,ragment +rocessor
-he fragment %rocessor is a .rograa9le unit that o.erates on #ragent values and their associated
data. "o.ilation units written in the +.en/0 (hading 0anguage to run on this .rocessor are called
fragment sha(ers. @hen a co.lete set o# #ragent shaders are co.iled and linked, the) result in a
fragment sha(er e*ecuta+le that runs on the #ragent .rocessor.
A #ragent shader cannot change a #ragentGs E*, ,F .osition. Access to neigh9oring #ragents is not
allowed. -he values co.uted 9) the #ragent shader are ultiatel) used to u.date #rae9u##er eor)
or te1ture eor), de.ending on the current +.en/0 state and the +.en/0 coand that caused the
#ragents to 9e generated.
6
! -asics
!.1 Character Set
-he source character set used #or the +.en/0 shading languages is a su9set o# A("II. It includes the
#ollowing characters:
-he letters a!", A!#$ and the underscore E > F.
-he nu9ers %!&.
-he s)9ols .eriod E.F, .lus E'F, dash E!F, slash E(F, asterisk E)F, .ercent E*F, angled 9rackets E+ and
,F, s=uare 9rackets E - and . F, .arentheses E / and 0 F, 9races E 1 and 2 F, caret E3F, vertical 9ar E 4 F,
a.ersand E5F, tilde E6F, e=uals E7F, e1claation .oint E8F, colon E9F, seicolon E:F, coa E$F, and
=uestion ark E;F.
-he nu9er sign E#F #or .re.rocessor use.
@hite s.ace: the s.ace character, hori?ontal ta9, vertical ta9, #or #eed, carriage8return, and line8
#eed.
0ines are relevant #or co.iler diagnostic essages and the .re.rocessor. -he) are terinated 9)
carriage8return or line8#eed. I# 9oth are used together, it will count as onl) a single line terination. 3or
the reainder o# this docuent, an) o# these co9inations is si.l) re#erred to as a new8line. -here is no
line continuation character.
In general, the languageHs use o# this character set is case sensitive.
-here are no character or string data t).es, so no =uoting characters are included.
-here is no end8o#8#ile character.
!.2 Source Strings
-he 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 ulti.le lines, se.arated 9) new8
lines. 7o new8lines need 9e .resent in a stringI a single line can 9e #ored #ro ulti.le strings. 7o
new8lines or other characters are inserted 9) the i.leentation when it concatenates the strings to #or a
single shader. :ulti.le shaders can 9e linked together to #or a single .rogra.
Diagnostic essages returned #ro co.iling a shader ust identi#) 9oth the line nu9er within a string
and which source string the essage a..lies to. (ource strings are counted se=uentiall) with the #irst
string 9eing string *. 0ine nu9ers are one ore than the nu9er o# new8lines that have 9een .rocessed.
7
3 Basics
!.! +reprocessor
-here is a .re.rocessor that .rocesses the source strings as .art o# the co.ilation .rocess.
-he co.lete list o# .re.rocessor directives is as #ollows.
#
#define
#undef
#if
#ifdef
#ifndef
#else
#elif
#endif
#error
#pragma
#extension
#version
#line
-he #ollowing o.erators are also availa9le
defined
##
Each nu9er sign E#F can 9e .receded in its line onl) 9) s.aces or hori?ontal ta9s. It a) also 9e
#ollowed 9) s.aces and hori?ontal ta9s, .receding the directive. Each directive is terinated 9) a new8
line. 2re.rocessing does not change the nu9er or relative location o# new8lines in a source string.
-he nu9er sign E#F on a line 9) itsel# is ignored. An) directive not listed a9ove will cause a diagnostic
essage and ake the i.leentation treat the shader as ill8#ored.
#define and #undef #unctionalit) are de#ined as is standard #or "JJ .re.rocessors #or acro de#initions
9oth with and without acro .araeters.
-he #ollowing .rede#ined acros are availa9le
__LINE__
__FILE__
__VERSION__
L-./ will su9stitute a decial integer constant that is one ore than the nu9er o# .receding new8
lines in the current source string.
"-L/ will su9stitute a decial integer constant that sa)s which source string nu9er is currentl)
9eing .rocessed.

3 Basics
V/R'-$. will su9stitute a decial integer re#lecting the version nu9er o# the +.en/0 shading
language. -he version o# the shading language descri9ed in this docuent will have V/R'-$.
su9stitute the decial integer %1*.
All acro naes containing two consecutive underscores E << F are reserved #or #uture use as .rede#ined
acro naes. All acro naes .re#i1ed with B/0>C EB/0C #ollowed 9) a single underscoreF are also
reserved.
#if$ #ifdef$ #ifndef$ #else$ #elif$ and #endif are de#ined to o.erate as is standard #or "JJ .re.rocessors.
E1.ressions #ollowing #if and #elif are #urther restricted to e1.ressions o.erating on literal integer
constants, .lus identi#iers consued 9) the defined o.erator. It is an error to use #if or #elif on
e1.ressions containing unde#ined acro naes, other than as arguents to the defined o.erator.
"haracter constants are not su..orted. -he o.erators availa9le are as #ollows.
+recedence Operator class Operators .ssociativit#
1 EhighestF .arenthetical grou.ing E F 7A
! unar) de#ined
J 8 K L
Right to 0e#t
& ulti.licative M N O 0e#t to Right
% additive J 8 0e#t to Right
$ 9it8wise shi#t PP QQ 0e#t to Right
' relational P Q PR QR 0e#t to Right
4 e=ualit) RR LR 0e#t to Right
5 9it8wise and S 0e#t to Right
; 9it8wise e1clusive or T 0e#t to Right
1* 9it8wise inclusive or U 0e#t to Right
11 logical and SS 0e#t to Right
1! ElowestF logical inclusive or U U 0e#t to Right
-he defined o.erator can 9e used in either o# the #ollowing wa)s:
defined identifier
defined ( identifier )
-wo tokens in a acro can 9e concatenated into one token using the token .asting E##F o.erator, as is
standard #or "JJ .re.rocessors. -he result ust 9e a valid single token, which will then 9e su9Dect to
acro e1.ansion. -hat is, acro e1.ansion ha..ens onl) a#ter token .asting. -here are no other nu9er
sign 9ased o.erators Ee.g., no # or #=F, nor is there a si"eof o.erator.
-he seantics o# a..l)ing o.erators to integer literals in the .re.rocessor atch those standard in the
"JJ .re.rocessor, not those in the +.en/0 (hading 0anguage.
!
3 Basics
2re.rocessor e1.ressions will 9e evaluated according to the 9ehavior o# the host .rocessor, not the
.rocessor targeted 9) the shader.
#error will cause the i.leentation to .ut a diagnostic essage into the shader o9DectHs in#oration log
Esection '.1.1! B(hader and 2rogra <ueriesC in the +.en/0 /ra.hics ()ste (.eci#ication #or how to
access a shader o9DectHs in#oration logF. -he essage will 9e the tokens #ollowing the #error directive,
u. to the #irst new8line. -he i.leentation ust then consider the shader to 9e ill8#ored.
#pragma allows i.leentation de.endent co.iler control. -okens #ollowing #pragma are not su9Dect
to .re.rocessor acro e1.ansion. I# an i.leentation does not recogni?e the tokens #ollowing
#pragma, then it will ignore that .raga. -he #ollowing .ragas are de#ined as .art o# the language.
#pragma ST!L
-he S>?@A .raga is used to reserve .ragas #or use 9) #uture revisions o# this language. 7o
i.leentation a) use a .raga whose #irst token is S>?@A.
#pragma optimi"e#on)
#pragma optimi"e#off)
can 9e used to turn o## o.tii?ations as an aid in develo.ing and de9ugging shaders. It can onl) 9e used
outside #unction de#initions. B) de#ault, o.tii?ation is turned on #or all shaders. -he de9ug .raga
#pragma de$ug#on)
#pragma de$ug#off)
can 9e used to ena9le co.iling and annotating a shader with de9ug in#oration, so that it can 9e used
with a de9ugger. It can onl) 9e used outside #unction de#initions. B) de#ault, de9ug is turned o##.
(haders should declare the version o# the language the) are written to. -he language version a shader is
written to is s.eci#ied 9)
#version number profile
opt
where num+er ust 9e a version o# the language, #ollowing the sae convention as V/R'-$. a9ove.
-he directive B#version B1%C is re=uired in an) shader that uses version %.1* o# the language. An)
num+er re.resenting a version o# the language a co.iler does not su..ort will cause an error to 9e
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 9e treated as targeting version 1.1*. (haders that s.eci#)
#version 1** will 9e treated as targeting version 1.** o# the +.en/0 E( (hading 0anguage.
(haders declaring version 1.%*, 1.$*, &.&*, or %.* o# the shading language can 9e linked with shaders
declaring version %.1* in the sae .rogra. (haders targeting earlier versions E1.&* or earlierF o# the
shading language cannot 9e linked with version %.1* shaders.
1"
3 Basics
I# the o.tional %rofile arguent is .rovided, it ust 9e the nae o# an +.en/0 .ro#ile. "urrentl), there
are two choices:
%ore
%ompati$ilit&
I# no %rofile arguent is .rovided, the de#ault is core. 6nless otherwise s.eci#ied, this s.eci#ication is
docuenting the core .ro#ile, and ever)thing s.eci#ied #or the core .ro#ile is also availa9le in the
co.ati9ilit) .ro#ile. 3eatures s.eci#ied as 9elonging s.eci#icall) to the co.ati9ilit) .ro#ile are not
availa9le in the core .ro#ile.
-here is a 9uilt8in acro de#inition #or each .ro#ile the i.leentation su..orts. All i.leentations
.rovide the #ollowing acro:
#define !L_%ore_profile '
I.leentations .roviding the co.ati9ilit) .ro#ile .rovide the #ollowing acro:
#define !L_%ompati$ilit&_profile '
-he #version directive ust occur in a shader 9e#ore an)thing else, e1ce.t #or coents and white s.ace.
11
3 Basics
B) de#ault, co.ilers o# this language ust issue co.ile tie s)ntactic, graatical, and seantic
errors #or shaders that do not con#or to this s.eci#ication. An) e1tended 9ehavior ust #irst 9e ena9led.
Directives to control the 9ehavior o# the co.iler with res.ect to e1tensions are declared with the
#extension directive
#extension extension_name : behavior
#extension all : behavior
where e*tensionname is the nae o# an e1tension. E1tension naes are not docuented in this
s.eci#ication. -he token all eans the 9ehavior a..lies to all e1tensions su..orted 9) the co.iler. -he
+ehavior can 9e one o# the #ollowing
behavior 'ffect
re/uire Behave as s.eci#ied 9) the e1tension e*tensionname.
/ive an error on the #extension i# the e1tension e*tensionname is not
su..orted, or i# all is s.eci#ied.
enable Behave as s.eci#ied 9) the e1tension e*tensionname.
@arn on the #extension i# the e1tension e*tensionname is not su..orted.
/ive an error on the #extension i# all is s.eci#ied.
&arn Behave as s.eci#ied 9) the e1tension e*tensionname, e1ce.t issue warnings
on an) detecta9le use o# that e1tension, unless such use is su..orted 9) other
ena9led or re=uired e1tensions.
I# all is s.eci#ied, then warn on all detecta9le uses o# an) e1tension used.
@arn on the #extension i# the e1tension e*tensionname is not su..orted.
disable Behave Eincluding issuing errors and warningsF as i# the e1tension
e*tensionname is not .art o# the language de#inition.
I# all is s.eci#ied, then 9ehavior ust revert 9ack to that o# the non8e1tended
core version o# the language 9eing co.iled to.
@arn on the #extension i# the e1tension e*tensionname is not su..orted.
-he extension directive is a si.le, low8level echanis to set the 9ehavior #or each e1tension. It does
not de#ine .olicies such as which co9inations are a..ro.riate, those ust 9e de#ined elsewhere. +rder
o# directives atters in setting the 9ehavior #or each e1tension: Directives that occur later override those
seen earlier. -he all variant sets the 9ehavior #or all e1tensions, overriding all .reviousl) issued
extension directives, 9ut onl) #or the +ehaviors warn and disable.
12
3 Basics
-he initial state o# the co.iler is as i# the directive
#extension all ( disa$le
was issued, telling the co.iler that all error and warning re.orting ust 9e done according to this
s.eci#ication, ignoring an) e1tensions.
Each e1tension can de#ine its allowed granularit) o# sco.e. I# nothing is said, the granularit) is a shader
Ethat is, a single co.ilation unitF, and the e1tension directives ust occur 9e#ore an) non8.re.rocessor
tokens. I# necessar), the linker can en#orce granularities larger than a single co.ilation unit, in which
case each involved shader will have to contain the necessar) e1tension directive.
:acro e1.ansion is not done on lines containing #extension and #version directives.
#line ust have, a#ter acro su9stitution, one o# the #ollowing #ors:
#line line
#line line source-string-number
where line and source-string-num+er are constant integer e1.ressions. A#ter .rocessing this directive
Eincluding its new8lineF, the i.leentation will 9ehave as i# it is co.iling at line nu9er line and
source string nu9er source-string-num+er. (u9se=uent source strings will 9e nu9ered se=uentiall),
until another #line directive overrides that nu9ering.
!. Comments
"oents are deliited 9) NM and MN, or 9) NN and a new8line. -he 9egin coent deliiters ENM or NNF are
not recogni?ed as coent deliiters inside o# a coent, hence coents cannot 9e nested. I# a
coent resides entirel) within a single line, it is treated s)ntacticall) as a single s.ace. 7ew8lines are
not eliinated 9) coents.
!.5 To0ens
-he language is a se=uence o# tokens. A token can 9e
to0en:
0e,wor(
i(entifier
integer-constant
floating-constant
o%erator
: 1 2
!." 1e#&ords
-he #ollowing are the ke)words in the language, and cannot 9e used #or an) other .ur.ose than that
de#ined 9) this docuent:
attribute const uniform varCing
laCout
13
3 Basics
centroid flat smooth noperspective
patch sample
break continue do for while switch case default
if else
subroutine
in out inout
float double int void bool true false
invariant
discard return
matD matE matB dmatD dmatE dmatB
matDxD matDxE matDxB dmatDxD dmatDxE dmatDxB
matExD matExE matExB dmatExD dmatExE dmatExB
matBxD matBxE matBxB dmatBxD dmatBxE dmatBxB
vecD vecE vecB ivecD ivecE ivecB bvecD bvecE bvecB dvecD dvecE dvecB
uint uvecD uvecE uvecB
lowp mediump highp precision
sampler1? samplerD? samplerE? samplerCube
sampler1?Shadow samplerD?Shadow samplerCubeShadow
sampler1?ArraC samplerD?ArraC
sampler1?ArraCShadow samplerD?ArraCShadow
isampler1? isamplerD? isamplerE? isamplerCube
isampler1?ArraC isamplerD?ArraC
usampler1? usamplerD? usamplerE? usamplerCube
usampler1?ArraC usamplerD?ArraC
samplerD?Fect samplerD?FectShadow isamplerD?Fect usamplerD?Fect
samplerGuffer isamplerGuffer usamplerGuffer
samplerD?HS isamplerD?HS usamplerD?HS
samplerD?HSArraC isamplerD?HSArraC usamplerD?HSArraC
samplerCubeArraC samplerCubeArraCShadow isamplerCubeArraC usamplerCubeArraC
struct
14
3 Basics
-he #ollowing are the ke)words reserved #or #uture use. 6sing the will result in an error:
common partition active
asm
class union enum tCpedef template this packed
goto
inline noinline volatile public static extern external interface
long short half fixed unsigned superp
input output
hvecD hvecE hvecB fvecD fvecE fvecB
samplerE?Fect
filter
image1? imageD? imageE? imageCube
iimage1? iimageD? iimageE? iimageCube
uimage1? uimageD? uimageE? uimageCube
image1?ArraC imageD?ArraC
iimage1?ArraC iimageD?ArraC uimage1?ArraC uimageD?ArraC
image1?Shadow imageD?Shadow
image1?ArraCShadow imageD?ArraCShadow
imageGuffer iimageGuffer uimageGuffer
si"eof cast
namespace using
row<maIor
In addition, all identi#iers containing two consecutive underscores E<<F are reserved as .ossi9le #uture
ke)words.
!.2 Identifiers
Identi#iers are used #or varia9le naes, #unction naes, structure naes, and #ield selectors E#ield
selectors select co.onents o# vectors and atrices siilar to structure #ields, as discussed in section $.$
BVector "o.onentsC and section $.' B:atri1 "o.onentsC F. Identi#iers have the #or
i(entifier
non(igit
i(entifier non(igit
i(entifier (igit
15
3 Basics
non(igit: one o#
< a b c d e f g h i I k l m n o p r s t u v w x C "
A G C ? J K @ L M N O A H P O Q R F S > S T U V W #
(igit: one o#
% 1 D E B X Y Z [ &
Identi#iers starting with Bgl>C are reserved #or use 9) +.en/0, and a) not 9e declared in a shader as
either a varia9le or a #unction. ,owever, as noted in the s.eci#ication, there are soe cases where
.reviousl) declared varia9les can 9e redeclared to change or add soe .ro.ert), and .redeclared Vgl>V
naes are allowed to 9e redeclared in a shader onl) #or these s.eci#ic .ur.oses. :ore generall), it is an
error to redeclare a varia9le, including those starting Bgl>C.
!.3 )efinitions
(oe language rules descri9ed 9elow de.end on the #ollowing de#initions.
!.3.1 Static 4se
A shader contains a static use o# Eor static assignment toF a varia9le * i#, a#ter .re.rocessing, the shader
contains a stateent that would read Eor writeF *, whether or not run8tie #low o# control will cause that
stateent to 9e e1ecuted.
!.3.2 4niform and 5on64niform Control ,lo&
@hen e1ecuting stateents in a #ragent shader, control #low starts as uniform control flowI all #ragents
enter the sae control .ath into mainEF. "ontrol #low 9ecoes non-uniform when di##erent #ragents
take di##erent .aths through control8#low stateents Eselection, iteration, and Du.sF. "ontrol #low
su9se=uentl) returns to 9eing uni#or a#ter such divergent su98stateents or ski..ed code co.letes,
until the ne1t tie di##erent control .aths are taken.
3or e1a.le:
main#)
)
float a * +++,-- t.is is uniform flo/ %ontrol
if #a 0 $) ) -- t.is expression is true for some fragments1 not all
++++, -- non2uniform flo/ %ontrol
3 else )
++++, -- non2uniform flo/ %ontrol
3
++++, -- uniform flo/ %ontrol again
3
+ther e1a.les o# non8uni#or #low control can occur within switch stateents and a#ter conditional
9reaks, continues, earl) returns, and a#ter #ragent discards, when the condition is true #or soe
#ragents 9ut not others. 0oo. iterations that onl) soe #ragents e1ecute are also non8uni#or #low
control.
16
3 Basics
-his is siilarl) de#ined #or other shader stages, 9ased on the .er8instance data ites the) .rocess.
!.3.! )#namicall# 4niform '*pressions
A #ragent8shader e1.ression is (,namicall, uniform i# all #ragents evaluating it get the sae resulting
value. @hen loo.s are involved, this re#ers to the e1.ressionGs value #or the sae loo. iteration. @hen
#unctions are involved, this re#ers to calls #ro the sae call .oint.
-his is siilarl) de#ined #or other shader stages, 9ased on the .er8instance data the) .rocess.
7ote that constant e1.ressions are triviall) d)naicall) uni#or. It #ollows that t).ical loo. counters
9ased on these are also d)naicall) uni#or.
17
$ariables and T#pes
All varia9les and #unctions ust 9e declared 9e#ore 9eing used. Varia9le and #unction naes are
identi#iers.
-here are no de#ault t).es. All varia9le and #unction declarations ust have a declared t).e, and
o.tionall) =uali#iers. A varia9le is declared 9) s.eci#)ing its t).e #ollowed 9) one or ore naes
se.arated 9) coas. In an) cases, a varia9le can 9e initiali?ed as .art o# its declaration 9) using the
assignent o.erator E7F. -he graar near the end o# this docuent .rovides a #ull re#erence #or the
s)nta1 o# declaring varia9les.
6ser8de#ined t).es a) 9e de#ined using struct to aggregate a list o# e1isting t).es into a single nae.
-he +.en/0 (hading 0anguage is t).e sa#e. -here are no i.licit conversions 9etween t).es, with the
e1ce.tion that an integer value a) a..ear where a #loating8.oint t).e is e1.ected, and 9e converted to a
#loating8.oint value. E1actl) how and when this can occur is descri9ed in section %.1.1* BI.licit
"onversionsC and as re#erenced 9) other sections in this s.eci#ication.
.1 -asic T#pes
-he +.en/0 (hading 0anguage su..orts the #ollowing 9asic data t).es, grou.ed as #ollows.
-rans.arent t).es
T#pe 7eaning
void #or #unctions that do not return a value
bool a conditional t).e, taking on values o# true or #alse
int a signed integer
uint an unsigned integer
float a single #loating8.oint scalar
double a single dou9le8.recision #loating .oint scalar
vecD a two8co.onent #loating8.oint vector
vecE a three8co.onent #loating8.oint vector
vecB a #our8co.onent #loating8.oint vector
dvecD a two8co.onent dou9le8.recision #loating8.oint vector
dvecE a three8co.onent dou9le8.recision #loating8.oint vector
dvecB a #our8co.onent dou9le8.recision #loating8.oint vector
bvecD a two8co.onent Boolean vector
bvecE a three8co.onent Boolean vector
1
4 #aria$%es and &'pes
T#pe 7eaning
bvecB a #our8co.onent Boolean vector
ivecD a two8co.onent signed integer vector
ivecE a three8co.onent signed integer vector
ivecB a #our8co.onent signed integer vector
uvecD a two8co.onent unsigned integer vector
uvecE a three8co.onent unsigned integer vector
uvecB a #our8co.onent unsigned integer vector
matD a !W! #loating8.oint atri1
matE a &W& #loating8.oint atri1
matB a %W% #loating8.oint atri1
matDxD sae as a matD
matDxE a #loating8.oint atri1 with ! coluns and & rows
matDxB a #loating8.oint atri1 with ! coluns and % rows
matExD a #loating8.oint atri1 with & coluns and ! rows
matExE sae as a matE
matExB a #loating8.oint atri1 with & coluns and % rows
matBxD a #loating8.oint atri1 with % coluns and ! rows
matBxE a #loating8.oint atri1 with % coluns and & rows
matBxB sae as a matB
dmatD a !W! dou9le8.recision #loating8.oint atri1
dmatE a &W& dou9le8.recision #loating8.oint atri1
dmatB a %W% dou9le8.recision #loating8.oint atri1
dmatDxD sae as a dmatD
dmatDxE a dou9le8.recision #loating8.oint atri1 with ! coluns and & rows
dmatDxB a dou9le8.recision #loating8.oint atri1 with ! coluns and % rows
dmatExD a dou9le8.recision #loating8.oint atri1 with & coluns and ! rows
dmatExE sae as a dmatE
dmatExB a dou9le8.recision #loating8.oint atri1 with & coluns and % rows
dmatBxD a dou9le8.recision #loating8.oint atri1 with % coluns and ! rows
dmatBxE a dou9le8.recision #loating8.oint atri1 with % coluns and & rows
dmatBxB sae as a dmatB
1!
4 #aria$%es and &'pes
3loating 2oint (a.ler -).es Eo.a=ueF
T#pe 7eaning
sampler1? a handle #or accessing a 1D te1ture
samplerD? a handle #or accessing a !D te1ture
samplerE? a handle #or accessing a &D te1ture
samplerCube a handle #or accessing a cu9e a..ed te1ture
samplerD?Fect a handle #or accessing a rectangular te1ture
sampler1?Shadow a handle #or accessing a 1D de.th te1ture with co.arison
samplerD?Shadow a handle #or accessing a !D de.th te1ture with co.arison
samplerD?FectShadow a handle #or accessing a rectangular te1ture with co.arison
sampler1?ArraC a handle #or accessing a 1D arra) te1ture
samplerD?ArraC a handle #or accessing a !D arra) te1ture
sampler1?ArraCShadow a handle #or accessing a 1D arra) de.th te1ture with co.arison
samplerD?ArraCShadow a handle #or accessing a !D arra) de.th te1ture with co.arison
samplerGuffer a handle #or accessing a 9u##er te1ture
samplerD?HS a handle #or accessing a !D ulti8sa.le te1ture
samplerD?HSArraC a handle #or accessing a !D ulti8sa.le arra) te1ture
samplerCubeShadow a handle #or accessing a cu9e a. de.th te1ture with co.arison
samplerCubeArraC a handle #or accessing a cu9e a. arra) te1ture
samplerCubeArraCShadow a handle #or accessing a cu9e a. arra) de.th te1ture with
co.arison
(igned Integer (a.ler -).es Eo.a=ueF
T#pe 7eaning
isampler1? a handle #or accessing an integer 1D te1ture
isamplerD? a handle #or accessing an integer !D te1ture
isamplerE? a handle #or accessing an integer &D te1ture
isamplerCube a handle #or accessing an integer cu9e a..ed te1ture
isamplerD?Fect a handle #or accessing an integer !D rectangular te1ture
isampler1?ArraC a handle #or accessing an integer 1D arra) te1ture
isamplerD?ArraC a handle #or accessing an integer !D arra) te1ture
isamplerGuffer a handle #or accessing an integer 9u##er te1ture
isamplerD?HS a handle #or accessing an integer !D ulti8sa.le te1ture
isamplerD?HSArraC a handle #or accessing an integer !D ulti8sa.le arra) te1ture
2"
4 #aria$%es and &'pes
T#pe 7eaning
isamplerCubeArraC a handle #or accessing an integer cu9e a. arra) te1ture
6nsigned Integer (a.ler -).es Eo.a=ueF
T#pe 7eaning
usampler1? a handle #or accessing an unsigned integer 1D te1ture
usamplerD? a handle #or accessing an unsigned integer !D te1ture
usamplerE? a handle #or accessing an unsigned integer &D te1ture
usamplerCube a handle #or accessing an unsigned integer cu9e a..ed te1ture
usamplerD?Fect a handle #or accessing an unsigned integer rectangular te1ture
usampler1?ArraC a handle #or accessing an unsigned integer 1D arra) te1ture
usamplerD?ArraC a handle #or accessing an unsigned integer !D arra) te1ture
usamplerGuffer a handle #or accessing an unsigned integer 9u##er te1ture
usamplerD?HS a handle #or accessing an unsigned integer !D ulti8sa.le te1ture
usamplerD?HSArraC a handle #or accessing an unsigned integer !D ulti8sa.le te1ture
arra)
usamplerCubeArraC a handle #or accessing an unsigned integer cu9e a. arra) te1ture
In addition, a shader can aggregate these using arra)s and structures to 9uild ore co.le1 t).es.
-here are no .ointer t).es.
.1.1 $oid
3unctions that do not return a value ust 9e declared as void. -here is no de#ault #unction return t).e.
-he ke)word void cannot 9e used in an) other declarations Ee1ce.t #or e.t) #oral or actual .araeter
listsF.
.1.2 -ooleans
-o ake conditional e1ecution o# code easier to e1.ress, the t).e bool is su..orted. -here is no
e1.ectation that hardware directl) su..orts varia9les o# this t).e. It is a genuine Boolean t).e, holding
onl) one o# two values eaning either true or #alse. -wo ke)words true and false can 9e used as literal
Boolean constants. Booleans are declared and o.tionall) initiali?ed as in the #ollow e1a.le:
$ool su%%ess, -- de%lare 4su%%ess5 to $e a 6oolean
$ool done * false, -- de%lare and initiali"e 4done5
-he right side o# the assignent o.erator E 7 F ust 9e an e1.ression whose t).e is bool.
E1.ressions used #or conditional Du.s Eif$ for$ ;9$ while$ do!whileF ust evaluate to the t).e bool.
21
4 #aria$%es and &'pes
.1.! Integers
(igned and unsigned integer varia9les are #ull) su..orted. In this docuent, the ter integer is eant to
generall) include 9oth signed and unsigned integers. 6nsigned integers have e1actl) &! 9its o# .recision.
(igned integers use &! 9its, including a sign 9it, in twoGs co.leent #or. +.erations resulting in
over#low or under#low will not cause an) e1ce.tion, nor will the) saturate, rather the) will Bwra.C to )ield
the low8order &! 9its o# the result.
Integers are declared and o.tionall) initiali?ed with integer e1.ressions, as in the #ollowing e1a.le:
int i1 7 * 89, -- default integer literal t&pe is int
uint : * ;u, -- 4u5 esta$lis.es t.e t&pe as uint
22
4 #aria$%es and &'pes
0iteral integer constants can 9e e1.ressed in decial E9ase 1*F, octal E9ase 5F, or he1adecial E9ase 1'F
as #ollows.
integer-constant :
(ecimal-constant integer-suffi*o%t
octal-constant integer-suffi*o%t
he*a(ecimal-constant integer-suffi*o%t
integer-suffi*: one o#
u S
(ecimal-constant :
non1ero-(igit
(ecimal-constant (igit
octal-constant :
%
octal-constant octal-(igit
he*a(ecimal-constant :
*1 he*a(ecimal-(igit
*X he*a(ecimal-(igit
he*a(ecimal-constant he*a(ecimal-(igit
(igit :
%
non1ero-(igit
non1ero-(igit : one o#
1 D E B X Y Z [ &
octal-(igit 9 one o#
% 1 D E B X Y Z
he*a(ecimal-(igit 9 one o#
% 1 D E B X Y Z [ &
a b c d e f
A G C ? J K
7o white s.ace is allowed 9etween the digits o# an integer constant, including a#ter the leading % or a#ter
the leading %x or %V o# a constant, or 9e#ore the su##i1 u or S. @hen the su##i1 u or S is .resent, the
literal has t).e uint, otherwise the t).e is int. A leading unar) inus sign E8F is inter.reted as an
arithetic unar) negation, not as .art o# the constant.
It is an error to .rovide a literal integer whose agnitude is too large to store in a varia9le o# atching
signed or unsigned t).e.
23
4 #aria$%es and &'pes
.1. ,loats
(ingle8.recision and dou9le8.recision #loating .oint varia9les are availa9le #or use in a variet) o# scalar
calculations. 3loating8.oint varia9les are de#ined as in the #ollowing e1a.le:
float a1 $ * '+<,
dou$le %1 d * 9+=LF,
As an in.ut value to one o# the .rocessing units, a single8.recision or dou9le8.recision #loating8.oint
varia9le is e1.ected to atch the corres.onding IEEE 4$% #loating8.oint de#inition #or .recision and
d)naic range. 3loating8.oint varia9les within a shader are also encoded according to the IEEE 4$%
s.eci#ication #or single8.recision #loating8.oint values. (ee section %.$.1 BRange and 2recisionC #or ore
details on .recision and usage o# 7a7s E7ot a 7u9erF and In#s E.ositive or negative in#initiesF.
3loating8.oint constants are de#ined as #ollows.
floating-constant :
fractional-constant e*%onent-%art
o%t
floating-suffi*o%t

(igit-se2uence e*%onent-%art floating-suffi*o%t
fractional-constant :
(igit-se2uence . (igit-se2uence
(igit-se2uence .
. (igit-se2uence
e*%onent-%art :
e sign
o%t
(igit-se2uence
E sign
o%t
(igit-se2uence
sign : one o#
' \
(igit-se2uence :
(igit
(igit-se2uence (igit
floating-suffi*: one o#
f K lf AK
A decial .oint E . F is not needed i# the e1.onent .art is .resent. 7o white s.ace a) a..ear an)where
within a #loating8.oint constant, including 9e#ore a su##i1. @hen the su##i1 Vl#V or V03V is .resent, the
literal has t).e double. +therwise, the literal has t).e float. A leading unar) inus sign E!F is inter.reted
as a unar) o.erator and is not .art o# the #loating8.oint constant
24
4 #aria$%es and &'pes
.1.5 $ectors
-he +.en/0 (hading 0anguage includes data t).es #or generic !8, &8, and %8co.onent vectors o#
#loating8.oint values, integers, or Booleans. 3loating8.oint vector varia9les can 9e used to store colors,
norals, .ositions, te1ture coordinates, te1ture looku. results and the like. Boolean vectors can 9e used
#or co.onent8wise co.arisons o# nueric vectors. (oe e1a.les o# vector declaration are:
ve%9 tex%oord'1 tex%oord9,
ve%; position,
ve%8 m&R!6>,
ive%9 textureLoo:up,
$ve%; less,
Initiali?ation o# vectors can 9e done with constructors, which are discussed shortl).
.1." 7atrices
-he +.en/0 (hading 0anguage has 9uilt8in t).es #or !W!, !W&, !W%, &W!, &W&, &W%, %W!, %W&, and %W%
atrices o# #loating8.oint nu9ers. :atri1 t).es 9eginning with VatV have single8.recision co.onents
while atri1 t).es 9eginning with VdatV have dou9le8.recision co.onents. -he #irst nu9er in the
t).e is the nu9er o# coluns, the second is the nu9er o# rows. I# there is onl) one nu9er, the atri1
is s=uare. E1a.le atri1 declarations:
mat9 mat9,
mat; opt?atrix,
mat8 vie/1 pro7e%tion,
mat8x8 vie/, -- an alternate /a& of de%laring a mat8
mat;x9 m, -- a matrix /it. ; %olumns and 9 ro/s
dmat8 .ig.@re%ision?V@,
dmat9x8 dm,
Initiali?ation o# atri1 values is done with constructors Edescri9ed in section $.% B"onstructorsC F in
colun8aDor order.
.1.2 Samplers
(a.ler t).es Ee.g., samplerD?F are e##ectivel) o.a=ue handles to te1tures and their #ilters. -he) are
used with the 9uilt8in te1ture #unctions Edescri9ed in section 5.4 B-e1ture 0ooku. 3unctionsC F to s.eci#)
which te1ture to access and how it is to 9e #iltered. -he) can onl) 9e declared as #unction .araeters or
uniform varia9les Esee section %.&.$ B6ni#orC F. E1ce.t #or arra) inde1ing, structure #ield selection, and
.arentheses, sa.lers are not allowed to 9e o.erands in e1.ressions. (a.lers aggregated into arra)s
within a shader Eusing s=uare 9rackets - .F can onl) 9e inde1ed with a d)naicall) uni#or integral
e1.ression, otherwise results are unde#ined. (a.lers cannot 9e treated as l8valuesI hence cannot 9e used
as out or inout #unction .araeters, nor can the) 9e assigned into. As uni#ors, the) are initiali?ed onl)
with the +.en/0 A2II the) cannot 9e declared with an initiali?er in a shader. As #unction .araeters,
onl) sa.lers a) 9e .assed to sa.lers o# atching t).e. -his ena9les consistenc) checking 9etween
shader te1ture accesses and +.en/0 te1ture state 9e#ore a shader is run.
25
4 #aria$%es and &'pes
.1.3 Structures
6ser8de#ined t).es can 9e created 9) aggregating other alread) de#ined t).es into a structure using the
struct ke)word. 3or e1a.le,
stru%t lig.t )
float intensit&,
ve%; position,
3 lig.tVar,
In this e1a.le, light 9ecoes the nae o# the new t).e, and lightVar 9ecoes a varia9le o# t).e light.
-o declare varia9les o# the new t).e, use its nae Ewithout the ke)word structF.
lig.t lig.tVar9,
:ore #orall), structures are declared as #ollows. ,owever, the co.lete correct graar is as given in
section ; B(hading 0anguage /raarC .
struct-(efinition :
2ualifier
o%t
struct name
o%t
1 mem+er-list 2 (eclarators
o%t
3
mem+er-list :
mem+er-(eclaration3
mem+er-(eclaration mem+er-list3
mem+er-(eclaration :
+asic-t,%e (eclarators3
where name 9ecoes the user8de#ined t).e, and can 9e used to declare varia9les to 9e o# this new t).e.
-he name shares the sae nae s.ace as other varia9les, t).es, and #unctions. All .reviousl) visi9le
varia9les, t).es, constructors, or #unctions with that nae are hidden. -he o.tional 2ualifier onl) a..lies
to an) (eclarators, and is not .art o# the t).e 9eing de#ined #or name.
(tructures ust have at least one e9er declaration. :e9er declarators a) contain .recision
=uali#iers, 9ut a) not contain an) other =uali#iers. Bit #ields are not su..orted. :e9er t).es ust 9e
alread) de#ined Ethere are no #orward re#erencesF. :e9er declarations cannot contain initiali?ers.
:e9er declarators can contain arra)s. (uch arra)s ust have a si?e s.eci#ied, and the si?e ust 9e an
integral constant e1.ression thatGs greater than ?ero Esee section %.&.& B"onstant E1.ressionsCF. Each
level o# structure has its own nae s.ace #or naes given in e9er declaratorsI such naes need onl)
9e uni=ue within that nae s.ace.
26
4 #aria$%es and &'pes
Anon)ous structures are not su..orted. E9edded structure de#initions are not su..orted.
stru%t S ) float f, 3,
stru%t T )
S, -- Error( anon&mous stru%tures disallo/ed
stru%t ) +++ 3, -- Error( em$edded stru%tures disallo/ed
S s, -- O:a&( nested stru%tures /it. name are allo/ed
3,
(tructures can 9e initiali?ed at declaration tie using constructors, as discussed in section $.%.& B(tructure
"onstructorsC .
.1.8 .rra#s
Varia9les o# the sae t).e can 9e aggregated into arra)s 9) declaring a nae #ollowed 9) 9rackets E - . F
enclosing an o.tional si?e. @hen an arra) si?e is s.eci#ied in a declaration, it ust 9e an integral constant
e1.ression Esee section %.&.& B"onstant E1.ressionsC F greater than ?ero. I# an arra) is inde1ed with an
e1.ression that is not an integral constant e1.ression, or i# an arra) is .assed as an arguent to a #unction,
then its si?e ust 9e declared 9e#ore an) such use. It is legal to declare an arra) without a si?e and then
later re8declare the sae nae as an arra) o# the sae t).e and s.eci#) a si?e. It is illegal to declare an
arra) with a si?e, and then later Ein the sae shaderF inde1 the sae arra) with an integral constant
e1.ression greater than or e=ual to the declared si?e. It is also illegal to inde1 an arra) with a negative
constant e1.ression. Arra)s declared as #oral .araeters in a #unction declaration ust s.eci#) a si?e.
6nde#ined 9ehavior results #ro inde1ing an arra) with a non8constant e1.ression thatHs greater than or
e=ual to the arra)Hs si?e or less than *. +nl) one8diensional arra)s a) 9e declared. All 9asic t).es and
structures can 9e #ored into arra)s. (oe e1a.les are:
float freAuen%iesB;C,
uniform ve%8 lig.t@ositionB8C,
lig.t lig.tsBC,
%onst int numLig.ts * 9,
lig.t lig.tsBnumLig.tsC,
An arra) t).e can 9e #ored 9) s.eci#)ing a t).e #ollowed 9) s=uare 9rackets EY ZF and including a si?e:
floatB<C
-his t).e can 9e used an)where an) other t).e can 9e used, including as the return value #ro a #unction
floatB<C foo#) ) 3
as a constructor o# an arra)
floatB<C#;+81 8+91 <+=1 <+91 '+')
as an unnaed .araeter
void foo#floatB<C)
27
4 #aria$%es and &'pes
and as an alternate wa) o# declaring a varia9le or #unction .araeter.
floatB<C a,
It is an error to declare arra)s o# arra)s:
float aB<CB;C, -- illegal
floatB<C aB;C, -- illegal
Arra)s can have initiali?ers #ored #ro arra) constructors:
float aB<C * floatB<C#;+81 8+91 <+=1 <+91 '+'),
float aB<C * floatBC#;+81 8+91 <+=1 <+91 '+'), -- same t.ing
6nsi?ed arra)s can 9e e1.licitl) si?ed 9) an initiali?er at declaration tie:
float aB<C,
+++
float $BC * a, -- $ is expli%itl& si"e <
float $B<C * a, -- means t.e same t.ing
,owever, i.licitl) si?ed arra)s cannot 9e assigned to. 7ote, this is a rare case that initiali?ers and
assignents a..ear to have di##erent seantics.
Arra)s know the nu9er o# eleents the) contain. -his can 9e o9tained 9) using the length ethod:
a+lengt.#), -- returns < for t.e a$ove de%larations
-he length ethod cannot 9e called on an arra) that has not 9een e1.licitl) si?ed.
2
4 #aria$%es and &'pes
.1.1% Implicit Conversions
In soe situations, an e1.ression and its t).e will 9e i.licitl) converted to a di##erent t).e. -he
#ollowing ta9le shows all allowed i.licit conversions:
T#pe of e*pression Can be implicitl# converted to
int uint
int
uint
float
int
uint
float
double
ivecD uvecD
ivecE uvecE
ivecB uvecB
ivecD
uvecD
vecD
ivecE
uvecE
vecE
ivecB
uvecB
vecB
ivecD
uvecD
vecD
dvecD
ivecE
uvecE
vecE
dvecE
ivecB
uvecB
vecB
dvecB
matD dmatD
matE dmatE
matB dmatB
matDxE dmatDxE
matDxB dmatDxB
matExD dmatExD
matExB dmatExB
matBxD dmatBxD
matBxE dmatBxE
2!
4 #aria$%es and &'pes
-here are no i.licit arra) or structure conversions. 3or e1a.le, an arra) o# int cannot 9e i.licitl)
converted to an arra) o# float.
@hen an i.licit conversion is done, it is not a re8inter.retation o# the e1.ressionGs 9it .attern, 9ut a
conversion o# its value to an e=uivalent value in the new t).e. 3or e1a.le, the integer value 8X will 9e
converted to the #loating8.oint value 8X.%. Integer values having ore 9its o# .recision than a #loating
.oint antissa will lose .recision when converted to float.
@hen .er#oring i.licit conversion #or 9inar) o.erators, there a) 9e ulti.le data t).es to which the
two o.erands can 9e converted. 3or e1a.le, when adding an int value to a uint value, 9oth values can
9e i.licitl) converted to uint, float, and double. In such cases, a #loating8.oint t).e is chosen i# either
o.erand has a #loating8.oint t).e. +therwise, an unsigned integer t).e is chosen i# either o.erand has an
unsigned integer t).e. +therwise, a signed integer t).e is chosen. I# o.erands can 9e i.licitl) converted
to ulti.le data t).es deriving #ro the sae 9ase data t).e, the t).e with the sallest co.onent si?e is
used.
-he conversions in the ta9le a9ove are done onl) as indicated 9) other sections o# this s.eci#ication.
.2 Scoping
-he sco.e o# a varia9le is deterined 9) where it is declared. I# it is declared outside all #unction
de#initions, it has glo9al sco.e, which starts #ro where it is declared and .ersists 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 sco.ed to the end o# the
#ollowing su98stateent. +therwise, i# it is declared as a stateent within a co.ound stateent, it is
sco.ed to the end o# that co.ound stateent. I# it is declared as a .araeter in a #unction de#inition, it is
sco.ed until the end o# that #unction de#inition. A #unction 9od) has a sco.e nested inside the #unctionHs
de#inition. -he if stateentHs e1.ression does not allow new varia9les to 9e declared, hence does not
#or a new sco.e.
3"
4 #aria$%es and &'pes
@ithin a declaration, the sco.e o# a nae starts iediatel) a#ter the initiali?er i# .resent or iediatel)
a#ter the nae 9eing declared i# not. (everal e1a.les:
int x * ',
)
int x * 91 & * x, -- & is initiali"ed to 9
3
stru%t S
)
int x,
3,
)
S S * S#=), -- DSD is onl& visi$le as a stru%t and %onstru%tor
S, -- DSD is no/ visi$le as a varia$le
3
int x * x, -- Error if x .as not $een previousl& defined+
All varia9le naes, structure t).e naes, and #unction naes in a given sco.e share the sae nae s.ace.
3unction naes can 9e redeclared in the sae sco.e, with the sae or di##erent .araeters, without error.
An i.licitl) si?ed arra) can 9e re8declared in the sae sco.e as an arra) o# the sae 9ase t).e.
+therwise, within one co.ilation unit, a declared nae cannot 9e redeclared in the sae sco.eI doing so
results in a redeclaration error. I# a nested sco.e redeclares a nae used in an outer sco.e, it hides all
e1isting uses o# that nae. -here is no wa) to access the hidden nae or ake it unhidden, without
e1iting the sco.e that hid it.
-he 9uilt8in #unctions are sco.ed in a sco.e outside the glo9al sco.e users declare glo9al varia9les in.
-hat is, a shaderGs glo9al sco.e, availa9le #or user8de#ined #unctions and glo9al varia9les, is nested inside
the sco.e containing the 9uilt8in #unctions. @hen a #unction nae is redeclared in a nested sco.e, it hides
all #unctions declared with that nae in the outer sco.e. 3unction declarations E.rotot).esF cannot occur
inside o# #unctionsI the) ust 9e at glo9al sco.e, or #or the 9uilt8in #unctions, outside the glo9al sco.e.
(hared glo9als are glo9al varia9les declared with the sae nae in inde.endentl) co.iled units
EshadersF within the sae language Ee.g., verte1F that are linked together when aking a single .rogra.
E/lo9als #oring the inter#ace 9etween two di##erent shader languages are discussed in other sections.F
(hared glo9als share the sae nae s.ace, and ust 9e declared with the sae t).e. -he) will share the
sae storage. (hared glo9al arra)s ust have the sae 9ase t).e and the sae e1.licit si?e. An arra)
i.licitl) si?ed in one shader can 9e e1.licitl) si?ed 9) another shader. I# no shader has an e1.licit si?e
#or the arra), the largest i.licit si?e is used. (calars ust have e1actl) the sae t).e nae and t).e
de#inition. (tructures ust have the sae nae, se=uence o# t).e naes, and t).e de#initions, and #ield
naes to 9e considered the sae t).e. -his rule a..lies recursivel) #or nested or e9edded t).es. All
initiali?ers #or a shared glo9al ust have the sae value, or a link error will result.
31
4 #aria$%es and &'pes
.! Storage 9ualifiers
Varia9le declarations a) have one storage =uali#ier s.eci#ied in #ront o# the t).e. -hese are suari?ed
as
9ualifier 7eaning
P none: de#ault Q local readNwrite eor), or an in.ut .araeter to a #unction
const a co.ile8tie constant, or a #unction .araeter that is read8onl)
in
centroid in
sample in
linkage into a shader #ro a .revious stage, varia9le is co.ied in
linkage with centroid 9ased inter.olation
in.ut linkage with .er8sa.le inter.olation
out
centroid out
sample out
linkage out o# a shader to a su9se=uent stage, varia9le is co.ied out
linkage with centroid 9ased inter.olation
out.ut linkage with .er8sa.le inter.olation
attribute de.recatedI linkage 9etween a verte1 shader and +.en/0 #or .er8verte1
data
uniform value does not change across the .riitive 9eing .rocessed, uni#ors
#or the linkage 9etween a shader, +.en/0, and the a..lication
varCing
centroid varCing
de.recatedI linkage 9etween a verte1 shader and a #ragent shader #or
inter.olated data
patch in tessellation evaluation shader in.ut #or .er8.atch attri9utes
patch out tessellation control shader out.ut #or .er8.atch attri9utes
+ut.uts #ro shader EoutF and in.uts to a shader EinF can 9e #urther =uali#ied with one o# these
inter.olation =uali#iers
9ualifier 7eaning
smooth .ers.ective correct inter.olation
flat no inter.olation
noperspective linear inter.olation
-hese inter.olation =uali#iers a) onl) .recede the =uali#iers in, centroid in, sample in, out, centroid
out, or sample out in a declaration. -he) do not a..l) to the de.recated storage =uali#iers varCing or
centroid varCing. -he) also do not a..l) to in.uts into a verte1 shader or out.uts #ro a #ragent
shader.
0ocal varia9les can onl) use the const storage =uali#ier.
3unction .araeters can use const, in, and out =uali#iers, 9ut as %arameter 2ualifiers. 2araeter
=uali#iers are discussed in section '.1.1 B3unction "alling "onventionsC.
3unction return t).es and structure #ields do not use storage =uali#iers.
32
4 #aria$%es and &'pes
Data t).es #or counication #ro one run o# a shader e1ecuta9le to its ne1t run Eto counicate
9etween #ragents or 9etween verticesF do not e1ist. -his would .revent .arallel e1ecution o# the sae
shader e1ecuta9le on ulti.le vertices or #ragents.
Initiali?ers a) onl) 9e used in declarations o# glo9als with no storage =uali#ier, with a const =uali#ier or
with a uniform =uali#ier. /lo9al varia9les without storage =uali#iers that are not initiali?ed in their
declaration or 9) the a..lication will not 9e initiali?ed 9) +.en/0, 9ut rather will enter main45 with
unde#ined values.
.!.1 )efault Storage 9ualifier
I# no =uali#ier is .resent on a glo9al varia9le, then the varia9le has no linkage to the a..lication or shaders
running on other .i.eline stages. 3or either glo9al or local un=uali#ied varia9les, the declaration will
a..ear to allocate eor) associated with the .rocessor it targets. -his varia9le will .rovide readNwrite
access to this allocated eor).
.!.2 Constant 9ualifier
7aed co.ile8tie constants can 9e declared using the const =uali#ier. An) varia9les =uali#ied as
constant are read8onl) varia9les #or that shader. Declaring varia9les as constant allows ore descri.tive
shaders than using hard8wired nuerical constants. -he const =uali#ier can 9e used with an) o# the 9asic
data t).es. It is an error to write to a const varia9le outside o# its declaration, so the) ust 9e initiali?ed
when declared. 3or e1a.le,
%onst ve%; ">xis * ve%; #=+=1 =+=1 '+=),
(tructure #ields a) not 9e =uali#ied with const. (tructure varia9les can 9e declared as const, and
initiali?ed with a structure constructor.
Initiali?ers #or const declarations ust 9e constant e1.ressions, as de#ined in section %.&.& B"onstant
E1.ressions.C
.!.! Constant '*pressions
A constant e*%ression is one o#
a literal value Ee.g., X or trueF
a glo9al or local varia9le =uali#ied as const Ei.e., not including #unction .araetersF
an e1.ression #ored 9) an o.erator on o.erands that are all constant e1.ressions, including getting an
eleent or length o# a constant arra), or a #ield o# a constant structure, or co.onents o# a constant
vector.
a constructor whose arguents are all constant e1.ressions
a 9uilt8in #unction call whose arguents are all constant e1.ressions, with the e1ce.tion o# the te1ture
looku. #unctions and the noise #unctions. -he 9uilt8in #unctions dKdx, dKdC, and fwidth ust return
* when evaluated inside an initiali?er with an arguent that is a constant e1.ression.
3unction calls to user8de#ined #unctions Enon89uilt8in #unctionsF cannot 9e used to #or constant
e1.ressions.
33
4 #aria$%es and &'pes
An integral constant e*%ression is a constant e1.ression that evaluates to a scalar signed or unsigned
integer.
"onstant e1.ressions will 9e evaluated in an invariant wa) so as to create the sae value in ulti.le
shaders when the sae constant e1.ressions a..ear in those shaders. (ee section %.'.1 B-he Invariant
<uali#ierC #or ore details on how to create invariant e1.ressions.
.!. Inputs
(hader in.ut varia9les are declared with a storage =uali#ier using the ke)word in. -he) #or the in.ut
inter#ace 9etween .revious stages o# the +.en/0 .i.eline and the declaring shader. In.ut varia9les ust
9e declared at glo9al sco.e. Values #ro the .revious .i.eline stage are co.ied into in.ut varia9les at the
9eginning o# shader e1ecution. Varia9les declared as in.uts cannot 9e written to during shader e1ecution.
+nl) the in.ut varia9les that are actuall) read need to 9e written 9) the .revious stageI it is allowed to
have su.er#luous declarations o# in.ut varia9les.
(ee section 4 BBuilt8in Varia9lesC #or a list o# the 9uilt8in in.ut naes.
Verte1 shader in.ut varia9les Eor attri9utesF receive .er8verte1 data. -he) are declared in a verte1 shader
with the in =uali#ier or the de.recated attribute =uali#ier. It is an error to use an) other in.ut storage
=uali#ier or an) inter.olation =uali#iers as a verte1 shader in.ut. -he values co.ied in are esta9lished 9)
the +.en/0 A2I or through the use o# the la)out identi#ier location. It is an error to use attribute in a
non8verte1 shader. Verte1 shader in.uts can onl) 9e single8 or dou9le8.recision #loating8.oint scalars,
single8.recision #loating8.oint vectors, atrices, signed and unsigned integers and integer vectors. Verte1
shader in.uts can also #or arra)s o# these t).es, 9ut not structures.
E1a.le declarations in a verte1 shader:
in ve%8 position,
in ve%; normal,
in ve%9 texEoordB8C,
It is e1.ected that gra.hics hardware will have a sall nu9er o# #i1ed vector locations #or .assing verte1
in.uts. -here#ore, the +.en/0 (hading language de#ines each non8atri1 in.ut varia9le as taking u. one
such vector location. -here is an i.leentation de.endent liit on the nu9er o# locations that can 9e
used, and i# this is e1ceeded it will cause a link error. EDeclared in.ut varia9les that are not staticall) used
do not count against this liit.F A scalar in.ut counts the sae aount against this liit as a vecB, so
a..lications a) want to consider .acking grou.s o# #our unrelated #loat in.uts together into a vector to
9etter utili?e the ca.a9ilities o# the underl)ing hardware. A atri1 in.ut will use u. ulti.le locations.
-he nu9er o# locations used will e=ual the nu9er o# coluns in the atri1.
34
4 #aria$%es and &'pes
-essellation control, evaluation, and geoetr) shader in.ut varia9les get the .er8verte1 values written out
9) out.ut varia9les o# the sae naes in the .revious active shader stage. 3or these in.uts, centroid in
and inter.olation =uali#iers are allowed, 9ut have no e##ect. (ince tessellation control, tessellation
evaluation, and geoetr) shaders o.erate on a set o# vertices, each in.ut var)ing varia9le Eor in.ut 9lock,
see inter#ace 9locks 9elowF needs to 9e declared as an arra). 3or e1a.le,
in float fooBC, -- geometr& s.ader input for vertex 4out float foo5
Each eleent o# such an arra) corres.onds to one verte1 o# the .riitive 9eing .rocessed. Each arra) can
o.tionall) have a si?e declared. -he arra) si?e will 9e set 9), Eor i# .rovided ust 9e consistent withF the
in.ut laCout declarationEsF esta9lishing the t).e o# in.ut .riitive, as descri9ed later in section %.&.5.1
BIn.ut 0a)out <uali#iersC.
(oe in.uts and out.uts are arra,e(, eaning that #or an inter#ace 9etween two shader stages either the
in.ut or out.ut declaration re=uires an e1tra level o# arra) inde1ing #or the declarations to atch. 3or
e1a.le, with the inter#ace 9etween a verte1 shader and a geoetr) shader, verte1 shader out.ut varia9les
and geoetr) shader in.ut varia9les o# the sae nae ust atch in t).e and =uali#ication, e1ce.t that
the verte1 shader nae cannot 9e declared as an arra) while the geoetr) shader nae ust 9e declared
as an arra), to allow #or verte1 inde1ing. It is a link error i# a non8arra)ed in.ut is not declared with the
sae t).e, =uali#ication, and arra) diensionalit) as the atching out.ut. It is an error i# an arra)ed in.ut
is not declared as an arra) o# the sae t).e and =uali#ication as the corres.onding Enon8arra)F out.ut.
()etricall), it is an error i# an arra)ed out.ut is not declared as an arra) o# the sae t).e and
=uali#ication as the corres.onding Enon8arra)F in.ut.
I# the out.ut corres.onding to an arra)ed in.ut is itsel# an arra), it ust a..ear in an out.ut 9lock Esee
inter#ace 9locks 9elowF in the out.utting shader and in an in.ut 9lock in the in.utting shader with a 9lock
instance nae declared as an arra). -his is re=uired 9ecause two8diensional arra)s are not su..orted.
Additionall), tessellation evaluation shaders su..ort .er8.atch in.ut varia9les declared with the patch in
=uali#ier. 2er8.atch in.ut varia9les are #illed with the values o# .er8.atch out.ut varia9les written 9) the
tessellation control shader. 2er8.atch in.uts a) 9e declared as one8diensional arra)s, 9ut are not
inde1ed 9) verte1 nu9er. In.ut varia9les a) not 9e declared using the patch in =uali#ier in tessellation
control or geoetr) shaders. As with other in.ut varia9les, .er8.atch in.uts ust 9e declared using the
sae t).e and =uali#ication as .er8.atch out.uts #ro the .revious Etessellation controlF shader stage.
3ragent shader in.uts get .er8#ragent values, t).icall) inter.olated #ro a .revious stageGs out.uts.
-he) are declared in #ragent shaders with the in storage =uali#ier, the centroid in storage =uali#ier, or
the de.recated varCing and centroid varCing storage =uali#iers. It is an error to use patch in in a
#ragent shader. 3ragent in.uts can onl) 9e signed and unsigned integers and integer vectors, #loating
.oint scalars, #loating8.oint vectors, atrices, or arra)s or structures o# these. 3ragent shader in.uts that
are signed or unsigned integers, integer vectors, or an) dou9le8.recision #loating8.oint t).e ust 9e
=uali#ied with the inter.olation =uali#ier flat.
35
4 #aria$%es and &'pes
3ragent in.uts are declared as in the #ollowing e1a.les:
in ve%; normal,
%entroid in ve%9 TexEoord,
invariant %entroid in ve%8 Eolor,
noperspe%tive in float temperature,
flat in ve%; m&Eolor,
noperspe%tive %entroid in ve%9 m&TexEoord,
-he #ragent shader in.uts #or an inter#ace with the last active shader in the verte1 .rocessing .i.eline.
3or this inter#ace, the last active shader stage out.ut varia9les and #ragent shader in.ut varia9les o# the
sae nae ust atch in t).e and =uali#ication Eother than out atching to inF.
@hen an inter#ace 9etween shader stages is #ored using shaders #ro two se.arate .rogra o9Dects, it is
not .ossi9le to detect isatches 9etween in.uts and out.uts when the .rogras are linked. @hen there
are isatches 9etween in.uts and out.uts on such inter#aces, the values .assed across the inter#ace will
9e .artiall) or co.letel) unde#ined. (haders can ensure atches across such inter#aces either 9) using
in.ut and out.ut la)out =uali#iers Esections %.&.5.1 BIn.ut 0a)out <uali#iersC and %.&.5.! B+ut.ut 0a)out
<uali#iersCF or 9) using identical in.ut and out.ut declarations o# 9locks or varia9les. "o.lete rules #or
inter#ace atching 9etween .rogras are #ound in the V(hader Inter#ace :atchingV .ortion o# section
!.1%.22+ o# the +.en/0 /ra.hics ()ste (.eci#ication.
.!.5 4niform
-he uniform =uali#ier is used to declare glo9al varia9les whose values are the sae across the entire
.riitive 9eing .rocessed. All uniform varia9les are read8onl) and are initiali?ed e1ternall) either at link
tie or through the A2I. -he link tie initial value is either the value o# the varia9leGs initiali?er, i#
.resent, or * i# no initiali?er is .resent. (a.ler t).es cannot have initiali?ers.
E1a.le declarations are:
uniform ve%8 lig.t@osition,
uniform ve%; %olor * ve%;#=+F1 =+F1 =+9), -- value assigned at lin: time
-he uniform =uali#ier can 9e used with an) o# the 9asic data t).es, or when declaring a varia9le whose
t).e is a structure, or an arra) o# an) o# these.
-here is an i.leentation de.endent liit on the aount o# storage #or uni#ors that can 9e used #or
each t).e o# shader and i# this is e1ceeded it will cause a co.ile8tie or link8tie error. 6ni#or
varia9les that are declared 9ut not used do not count against this liit. -he nu9er o# user8de#ined
uni#or varia9les and the nu9er o# 9uilt8in uni#or varia9les that are used within a shader are added
together to deterine whether availa9le uni#or storage has 9een e1ceeded.
I# ulti.le shaders are linked together, then the) will share a single glo9al uni#or nae s.ace, including
within a language as well as across languages. ,ence, the t).es and initiali?ers o# uni#or varia9les with
the sae nae ust atch across all shaders that are linked into a single .rogra.
It is legal #or soe shaders to .rovide an initiali?er #or a .articular uni#or varia9le, while another shader
does not, 9ut all .rovided initiali?ers ust 9e e=ual.
36
4 #aria$%es and &'pes
.!." Outputs
(hader out.ut varia9les are declared with a storage =uali#ier using the ke)word out. -he) #or the out.ut
inter#ace 9etween the declaring shader and the su9se=uent stages o# the +.en/0 .i.eline. +ut.ut
varia9les ust 9e declared at glo9al sco.e. During shader e1ecution the) will 9ehave as noral
un=uali#ied glo9al varia9les. -heir values are co.ied out to the su9se=uent .i.eline stage on shader e1it.
+nl) out.ut varia9les that are read 9) the su9se=uent .i.eline stage need to 9e writtenI it is allowed to
have su.er#luous declarations o# out.ut varia9les.
-here is not an inout storage =uali#ier at glo9al sco.e #or declaring a single varia9le nae as 9oth in.ut
and out.ut to a shader. +ut.ut varia9les ust 9e declared with di##erent naes than in.ut varia9les.
,owever, nesting an in.ut or out.ut inside an inter#ace 9lock with an instance nae allows the sae
naes with one re#erenced through a 9lock instance nae.
Verte1, tessellation evaluation, and geoetr) out.ut varia9les out.ut .er8verte1 data and are declared
using the out, centroid out, or sample out storage =uali#iers, or the de.recated varCing storage =uali#ier.
It is an error to use patch out in a verte1, tessellation evaluation, or geoetr) shader. +ut.ut varia9les
can onl) 9e #loating8.oint scalars, #loating8.oint vectors, atrices, signed or unsigned integers or integer
vectors, or arra)s or structures o# an) these.
Individual verte1, tessellation evaluation, and geoetr) out.uts are declared as in the #ollowing e1a.les:
out ve%; normal,
%entroid out ve%9 TexEoord,
invariant %entroid out ve%8 Eolor,
noperspe%tive out float temperature, -- var&ing is depre%ated
flat out ve%; m&Eolor,
noperspe%tive %entroid out ve%9 m&TexEoord,
sample out ve%8 perSampleEolor,
-hese can also a..ear in inter#ace 9locks, as descri9ed in section %.&.4 BInter#ace BlocksC. Inter#ace
9locks allow si.ler addition o# arra)s to the inter#ace #ro verte1 to geoetr) shader. -he) also allow a
#ragent shader to have the sae in.ut inter#ace as a geoetr) shader #or a given verte1 shader.
-essellation control shader out.ut varia9les are a) 9e used to out.ut .er8verte1 and .er8.atch data. 2er8
verte1 out.ut varia9les are arra)ed Esee arra,e( under %.&.% In.utsF and declared using out or centroid
out storage =uali#iers. 2er8.atch out.ut varia9les are declared using the patch out storage =uali#ier. 2er8
verte1 and .er8.atch out.ut varia9les can onl) 9e #loating8.oint scalars, #loating8.oint vectors, atrices,
signed or unsigned integers or integer vectors, or arra)s or structures o# an) these. (ince tessellation
control shaders .roduce an arra)ed .riitive co.rising ulti.le vertices, each .er8verte1 out.ut varia9le
Eor out.ut 9lock, see inter#ace 9locks 9elowF needs to 9e declared as an arra). 3or e1a.le,
out float fooBC, -- feeds next stage input 4in float fooBC5
Each eleent o# such an arra) corres.onds to one verte1 o# the .riitive 9eing .roduced. Each arra) can
o.tionall) have a si?e declared. -he arra) si?e will 9e set 9) Eor i# .rovided ust 9e consistent withF the
out.ut la)out declarationEsF esta9lishing the nu9er o# vertices in the out.ut .atch, as descri9ed later in
section %.&.5.! B+ut.ut 0a)out <uali#iersC.
37
4 #aria$%es and &'pes
As descri9ed under the section %.&.% BIn.utsC a9ove, i# a .er8verte1 out.ut o# the tessellation control
shader is itsel# an arra) with ulti.le values .er verte1, it ust a..ear in an out.ut 9lock Esee inter#ace
9locks 9elowF in the tessellation control shader with a 9lock instance nae declared as an arra).
Each tessellation control shader invocation has a corres.onding out.ut .atch verte1, and a) assign
values to .er8verte1 out.uts onl) i# the) 9elong to that corres.onding verte1. I# a .er8verte1 out.ut
varia9le is used as an l8value, it is an error i# the e1.ression indicating the verte1 inde1 is not the identi#ier
gl-nvocation-D.
-he order o# e1ecution o# a tessellation control shader invocation relative to the other invocations #or the
sae in.ut .atch is unde#ined unless the 9uilt8in #unction barrierEF is used. -his .rovides soe control
over relative e1ecution order. @hen a shader invocation calls barrierEF, its e1ecution .auses until all
other invocations have reached the sae .oint o# e1ecution. +ut.ut varia9le assignents .er#ored 9)
an) invocation e1ecuted .rior to calling barrierEF will 9e visi9le to an) other invocation a#ter the call to
barrierEF returns.
Because tessellation control shader invocations e1ecute in unde#ined order 9etween 9arriers, the values o#
.er8verte1 or .er8.atch out.ut varia9les will soeties 9e unde#ined. "onsider the 9eginning and end o#
shader e1ecution and each call to barrierEF as s)nchroni?ation .oints. -he value o# an out.ut varia9le
will 9e unde#ined in an) o# the three #ollowing cases:
1. At the 9eginning o# e1ecution.
!. At each s)nchroni?ation .oint, unless
the value was well8de#ined a#ter the .revious s)nchroni?ation .oint and was not written 9) an)
invocation since, or
the value was written 9) e1actl) one shader invocation since the .revious s)nchroni?ation
.oint, or
the value was written 9) ulti.le shader invocations since the .revious s)nchroni?ation .oint,
and the last write .er#ored 9) all such invocations wrote the sae value.
&. @hen read 9) a shader invocation, i#
the value was unde#ined at the .revious s)nchroni?ation .oint and has not 9een writen 9) the
sae shader invocation since, or
the out.ut varia9le is written to 9) an) other shader invocation 9etween the .revious and ne1t
s)nchroni?ation .oints, even i# that assignent occurs in code #ollowing the read.
3ragent out.uts out.ut .er8#ragent data and are declared using the out storage =uali#ier. It is an error
to use centroid out, sample out, or patch out in a #ragent shader. 3ragent out.uts can onl) 9e float,
#loating8.oint vectors, signed or unsigned integers or integer vectors, or arra)s o# an) these. :atrices and
structures cannot 9e out.ut. 3ragent out.uts are declared as in the #ollowing e1a.les:
out ve%8 FragmentEolor,
out uint Luminosit&,
3
4 #aria$%es and &'pes
.!.2 Interface -loc0s
In.ut, out.ut, and uni#or varia9le declarations can 9e grou.ed into naed inter#ace 9locks to .rovide
coarser granularit) 9acking than is achieva9le with individual declarations. -he) can have an o.tional
instance nae, used in the shader to re#erence their e9ers. An out.ut 9lock o# one .rograa9le
stage is 9acked 9) a corres.onding in.ut 9lock in the su9se=uent .rograa9le stage. A uni#or 9lock is
9acked 9) the a..lication with a 9u##er o9Dect. It is illegal to have an in.ut 9lock in a verte1 shader or an
out.ut 9lock in a #ragent shaderI these uses are reserved #or #uture use.
An inter#ace 9lock is started 9) an in, out, or uniform ke)word, #ollowed 9) a 9lock nae, #ollowed 9)
an o.en curl) 9race E 1 F as #ollows:
interface-+loc0 :
la,out-2ualifieropt interface-2ualifier +loc0-name 1 mem+er-list 2 instance-nameopt :
la,out-2ualifier :
laCout / la,out-2ualifier-i(-list 0
interface-2ualifier :
in
out
uniform
la,out-2ualifier-i(-list
coa se.arated list o# la,out-2ualifier-i(
mem+er-list :
mem+er-(eclaration
mem+er-(eclaration mem+er-list
mem+er-(eclaration :
la,out-2ualifieropt 2ualifiersopt t,%e (eclarators :
instance-name :
i(entifier
i(entifier 6 7
i(entifier 6 integral-constant-e*%ression 7
Each o# the a9ove eleents is discussed 9elow, with the e1ce.tion o# la)out =uali#iers Ela,out-2ualifier5,
which are de#ined in the ne1t section.
3irst, an e1a.le,
uniform Transform )
mat8 ?odelVie/?atrix,
mat8 ?odelVie/@ro7e%tion?atrix,
uniform mat; Normal?atrix, -- allo/ed restatement of Aualifier
float eformation,
3,
-he a9ove esta9lishes a uni#or 9lock naed B-rans#orC with #our uni#ors grou.ed inside it.
3!
4 #aria$%es and &'pes
-).es and declarators are the sae as #or other in.ut, out.ut, and uni#or varia9le declarations outside
9locks, with these e1ce.tions:
initiali?ers are not allowed
sa.ler t).es are not allowed
structure de#initions cannot 9e nested inside a 9lock
+therwise, 9uilt8in t).es, .reviousl) declared structures, and arra)s o# these are allowed as the t).e o# a
declarator in the sae anner the) are allowed outside a 9lock.
I# no o.tional =uali#ier is used in a e9er8declaration, the =uali#ication o# the varia9le is Dust in, out, or
uniform as deterined 9) interface-2ualifier. I# o.tional =uali#iers are used, the) can include
inter.olation and storage =uali#iers and the) ust declare an in.ut, out.ut, or uni#or varia9le consistent
with the inter#ace =uali#ier o# the 9lock: In.ut varia9les, out.ut varia9les, and uni#or varia9les can onl)
9e in in 9locks, out 9locks, and uniform 9locks, res.ectivel). Re.eating the in, out, or uniform
inter#ace =uali#ier #or a e9erGs storage =uali#ier is o.tional. Declarations using the de.recated
attribute and varCing =uali#iers are not allowed. 3or e1a.le,
in ?aterial )
smoot. in ve%8 Eolor', -- legal1 input inside in $lo%:
smoot. ve%8 Eolor9, -- legal1 DinD in.erited from Din ?aterialD
ve%9 TexEoord, -- legal1 TexEoord is an input
uniform float >tten, -- illegal1 mismat%.ed interfa%es
var&ing ve%9 TexEoord9,--illegal1 depre%ated :e&/ords donDt get ne/ uses
3,
3or this section, de#ine an interface to 9e one o# these
All the uni#ors o# a .rogra. -his s.ans all co.ilation units linked together within one .rogra.
-he 9oundar) 9etween adDacent .rograa9le .i.eline stages: -his s.ans all the out.uts in all
co.ilation units o# the #irst stage and all the in.uts in all co.ilation units o# the second stage.
-he 9lock nae E+loc0-nameF is used to atch inter#aces: an out.ut 9lock o# one .i.eline stage will 9e
atched to an in.ut 9lock with the sae nae in the su9se=uent .i.eline stage. 3or uni#or 9locks, the
a..lication uses the 9lock nae to identi#) the 9lock. Block naes have no other use within a shader
9e)ond inter#ace atchingI it is an error to use a 9lock nae at glo9al sco.e #or an)thing other than as a
9lock nae Ee.g., use o# a 9lock nae #or a glo9al varia9le nae or #unction nae is currentl) reservedF.
:atched 9lock naes within an inter#ace Eas de#ined a9oveF ust atch in ters o# having the sae
nu9er o# declarations with the sae se=uence o# t).es and the sae se=uence o# e9er naes, as well
as having the sae e9er8wise la)out =uali#ication Esee ne1t sectionF. 3urtherore, i# a atching 9lock
is declared as an arra), then the arra) si?es ust also atch Eor #ollow arra) atching rules #or the
inter#ace 9etween a verte1 and a geoetr) shaderF. An) isatch will generate a link error. A 9lock
nae is allowed to have di##erent de#initions in di##erent inter#aces within the sae shader, allowing, #or
e1a.le, an in.ut 9lock and out.ut 9lock to have the sae nae.
4"
4 #aria$%es and &'pes
I# an instance nae Einstance-nameF is not used, the naes declared inside the 9lock are sco.ed at the
glo9al level and accessed as i# the) were declared outside the 9lock. I# an instance nae Einstance-nameF
is used, then it .uts all the e9ers inside a sco.e within its own nae s.ace, accessed with the #ield
selector E . F o.erator Eanalogousl) to structuresF. 3or e1a.le,
in Lig.t )
ve%8 Lig.t@os,
ve%; Lig.tEolor,
3,
in EoloredTexture )
ve%8 Eolor,
ve%9 TexEoord,
3 ?aterial, -- instan%e name
ve%; Eolor, -- different Eolor t.an ?aterial+Eolor
ve%8 Lig.t@os, -- illegal1 alread& defined
+++
+++ * Lig.t@os, -- a%%essing Lig.t@os
+++ * ?aterial+Eolor, -- a%%essing Eolor in EoloredTexture $lo%:
+utside the shading language Ei.e., in the A2IF, e9ers are siilarl) identi#ied e1ce.t the 9lock nae is
alwa)s used in .lace o# the instance nae EA2I accesses are to inter#aces, not to shadersF. I# there is no
instance nae, then the A2I does not use the 9lock nae to access a e9er, Dust the e9er nae.
out Vertex )
ve%8 @osition, -- >@I transform-feed$a%: /ill use 4Vertex+@osition5
ve%9 Texture,
3 Eoords, -- s.ader /ill use 4Eoords+@osition5
out Vertex9 )
ve%8 Eolor, -- >@I /ill use 4Eolor5
3,
3or 9locks declared as arra)s, the arra) inde1 ust also 9e included when accessing e9ers, as in this
e1a.le
uniform Transform ) -- >@I uses 4TransformB9C5 to refer to instan%e 9
mat8 ?odelVie/?atrix,
mat8 ?odelVie/@ro7e%tion?atrix,
float eformation,
3 transformsB8C,
+++
+++ * transformsB9C+?odelVie/?atrix, -- s.ader a%%ess of instan%e 9
-- >@I uses 4Transform+?odelVie/?atrix5 to Auer& an offset or ot.er Auer&
3or uni#or 9locks declared as an arra), each individual arra) eleent corres.onds to a se.arate 9u##er
o9Dect 9acking one instance o# the 9lock. As the arra) si?e indicates the nu9er o# 9u##er o9Dects needed,
uni#or 9lock arra) declarations ust s.eci#) an arra) si?e. An) integral e1.ression can 9e used to inde1
a uni#or 9lock arra), as .er section %.1.; VArra)sV.
41
4 #aria$%es and &'pes
@hen using +.en/0 A2I entr) .oints to identi#) the nae o# an individual 9lock in an arra) o# 9locks,
the nae string ust include an arra) inde1 Ee.g., #ransform627F. @hen using +.en/0 A2I entr) .oints
to re#er to o##sets or other characteristics o# a 9lock e9er, an arra) inde1 ust not 9e s.eci#ied Ee.g.,
#ransform.8o(elView8atri*F.
/eoetr) shader in.ut 9locks ust 9e declared as arra)s and #ollow the arra) declaration and linking
rules #or all geoetr) shader in.uts. All other in.ut and out.ut 9lock arra)s ust s.eci#) an arra) si?e.
-here is an i.leentation de.endent liit on the nu9er o# uni#or 9locks that can 9e used .er stage.
I# this liit is e1ceeded, it will cause a link error.
.!.3 La#out 9ualifiers
0a)out =uali#iers can a..ear in several #ors o# declaration. -he) can a..ear as .art o# an inter#ace
9lock de#inition or 9lock e9er, as shown in the graar in the .revious section. -he) can also a..ear
with Dust an inter#ace =uali#ier to esta9lish la)outs o# other declarations ade with that inter#ace =uali#ier:
la,out-2ualifier interface-2ualifier :
+r, the) can a..ear with an individual varia9le declared with an inter#ace =uali#ier:
la,out-2ualifier interface-2ualifier (eclaration :
Declarations o# la)outs can onl) 9e ade at glo9al sco.e, and onl) where indicated in the #ollowing
su9sectionsI their details are s.eci#ic to what the inter#ace =uali#ier is, and are discussed individuall).
As shown in the .revious section, la,out-2ualifier e1.ands to
la,out-2ualifier :
laCout / la,out-2ualifier-i(-list 0
-he tokens in an) la,out-2ualifier-i(-list are identi#iers, not ke)words. /enerall), the) can 9e listed in
an) order. +rder8de.endent eanings e1ist onl) i# e1.licitl) called out 9elow. (iilarl), these identi#iers
are not case sensitive, unless e1.licitl) noted otherwise.
.!.3.1 Input La#out 9ualifiers
All shaders allow in.ut la)out =uali#iers on in.ut varia9le declarations. -he location la)out =uali#ier
identi#ier #or in.uts is:
la,out-2ualifier-i(
location 7 integer-constant
+nl) one arguent is acce.ted. 3or e1a.le,
la&out#lo%ation * ;) in ve%8 normal,
will esta9lish that the shader in.ut normal is assigned to vector location nu9er &.
I# the declared in.ut is o# t).e dvecE or dvecB it will consue two consecutive locations. In.uts o# t).e
double and dvecD will consue onl) a single location.
I# the declared in.ut is an arra) o# si?e n and each eleent takes m locations, it will 9e assigned m M n
consecutive locations starting with the location s.eci#ied. 3or e1a.le,
42
4 #aria$%es and &'pes
la&out#lo%ation * G) in ve%8 %olorsB;C,
will esta9lish that the shader in.ut colors is assigned to vector location nu9ers ', 4, and 5.
I# the declared in.ut is an n 1 m single8 or dou9le8.recision atri1, it will 9e assigned ulti.le locations
starting with the location s.eci#ied. -he nu9er o# locations assigned #or each atri1 will 9e the sae as
#or an n8eleent arra) o# m8co.onent vectors. 3or e1a.le,
la&out#lo%ation * H) in mat8 transformsB9C,
will esta9lish that shader in.ut transforms is assigned to vector locations ;81', with transforms607 9eing
assigned to locations ;81! and transforms617 9eing assigned to locations 1&81'.
0ocation la)out =uali#iers a) 9e used on structures, 9ut not on individual e9ers. (tructure e9ers
are assigned, in the order o# their declaration, to consecutive locations starting with the location s.eci#ied
#or the structure.
-he nu9er o# in.ut locations availa9le to a shader is liited. 3or verte1 shaders, the liit is the
advertised nu9er o# verte1 attri9utes. 3or all other shaders, the liit is i.leentation8de.endent and
ust 9e no less than one #ourth o# the advertised a1iu in.ut co.onent count. A .rogra will #ail to
link i# an) attached shader uses a location greater than or e=ual to the nu9er o# su..orted locations,
unless device8de.endent o.tii?ations are a9le to ake the .rogra #it within availa9le hardware
resources.
A .rogra will #ail to link i# an) two non8verte1 shader in.ut varia9les are assigned to the sae location.
3or verte1 shaders, ulti.le in.ut varia9les a) 9e assigned to the sae location using either la)out
=uali#iers or via the +.en/0 A2I. ,owever, such aliasing is intended onl) to su..ort verte1 shaders
where each e1ecution .ath accesses at ost one in.ut .er each location. I.leentations are .eritted,
9ut not re=uired, to generate link errors i# the) detect that ever) .ath through the verte1 shader e1ecuta9le
accesses ulti.le in.uts assigned to an) single location. 3or all shader t).es, a .rogra will #ail to link i#
e1.licit location assignents leave the linker una9le to #ind s.ace #or other varia9les without e1.licit
assignents.
I# a verte1 shader in.ut varia9le with no location assigned in the shader te1t has a location s.eci#ied
through the +.en/0 A2I, the A2I8assigned location will 9e used. +therwise, such varia9les will 9e
assigned a location 9) the linker. (ee section !.11.& BVerte1 Attri9utesC o# the +.en/0 /ra.hics ()ste
(.eci#ication #or ore details. A link error will occur i# an in.ut varia9le is declared in ulti.le verte1
shaders with con#licting locations.
Additional in.ut la)out =uali#ier identi#iers allowed #or tessellation evaluation shaders are:
43
4 #aria$%es and &'pes
la,out-2ualifier-i(
triangles
uads
isolines
eual<spacing
fractional<even<spacing
fractional<odd<spacing
cw
ccw
point<mode
+ne su9set o# these identi#iers, %rimitive mo(e, is used to s.eci#) a tessellation .riitive ode to 9e used
9) the tessellation .riitive generator. -o s.eci#) a .riitive ode, the identi#ier ust 9e one o#
triangles, uads, or isolines, which s.eci#) that the tessellation .riitive generator should su9divide a
triangle into saller triangles, a =uad into triangles, or a =uad into a collection o# lines, res.ectivel).
A second su9set o# these identi#iers, verte* s%acing, is used to s.eci#) the s.acing used 9) the tessellation
.riitive generator when su9dividing an edge. -o s.eci#) verte1 s.acing, the identi#ier ust 9e one o#
the #ollowing.
eual<spacing signi#)ing that edges should 9e divided into a collection o# e=ual8si?ed segents.
fractional<even<spacing signi#)ing that edges should 9e divided into an even nu9er o# e=ual8
length segents .lus two additional shorter V#ractionalV segents.
fractional<odd<spacing signi#)ing that edges should 9e divided into an odd nu9er o# e=ual8
length segents .lus two additional shorter V#ractionalV segents.
A third su9set o# these identi#iers, or(ering, s.eci#ies whether the tessellation .riitive generator
.roduces triangles in clockwise or counter8clockwise order, according to the coordinate s)ste de.icted
in the +.en/0 s.eci#ication. -he ordering identi#iers cw and ccw indicate clockwise and counter8
clockwise triangles, res.ectivel). I# the tessellation .riitive generator does not .roduce triangles,
ordering is ignored.
3inall), %oint mo(e) is s.eci#ied with the identi#ier point<mode indicating the tessellation .riitive
generator should .roduce a .oint #or each uni=ue verte1 in the su9divided .riitive, rather than
generating lines or triangles.
An) or all o# these identi#iers a) 9e s.eci#ied one or ore ties in a single in.ut la)out declaration. I#
.riitive ode, verte1 s.acing, or ordering is declared ore than once in the tessellation evaluation
shaders o# a .rogra, all such declarations ust use the sae identi#ier.
At least one tessellation evaluation shader Eco.ilation unitF in a .rogra ust declare a .riitive ode
in its in.ut la)out. Declaring verte1 s.acing, ordering, or .oint ode identi#iers is o.tional. It is not
re=uired that all tessellation evaluation shaders in a .rogra declare a .riitive ode. I# s.acing or
verte1 ordering declarations are oitted, the tessellation .riitive generator will use e=ual s.acing or
counter8clockwise verte1 ordering, res.ectivel). I# a .oint ode declaration is oitted, the tessellation
.riitive generator will .roduce lines or triangles according to the .riitive ode.
Additional la)out =uali#ier identi#iers #or geoetr) shader in.uts include %rimitive identi#iers and an
invocation count identi#ier:
44
4 #aria$%es and &'pes
la,out-2ualifier-i(
points
lines
lines<adIacencC
triangles
triangles<adIacencC
invocations 7 integer-constant
-he identi#iers points, lines, lines<adIacencC, triangles, and triangles<adIacencC are used to s.eci#) the
t).e o# in.ut %rimitive acce.ted 9) the geoetr) shader, and onl) one o# these is acce.ted. At least one
geoetr) shader Eco.ilation unitF in a .rogra ust declare this in.ut .riitive la)out, and all geoetr)
shader in.ut la)out declarations in a .rogra ust declare the sae la)out. It is not re=uired that all
geoetr) shaders in a .rogra declare an in.ut .riitive la)out.
-he identi#ier invocations is used to s.eci#) the nu9er o# ties the geoetr) shader e1ecuta9le is
invoked #or each in.ut .riitive received. Invocation count declarations are o.tional. I# no invocation
count is declared in an) geoetr) shader in a .rogra, the geoetr) shader will 9e run once #or each
in.ut .riitive. I# an invocation count is declared, all such declarations ust s.eci#) the sae count. I# a
shader s.eci#ies an invocation count greater than the i.leentation8de.endent a1iu, it will #ail to
co.ile.
3or e1a.le,
la&out#triangles1 invo%ations * G) in,
will esta9lish that all in.uts to the geoetr) shader are triangles and that the geoetr) shader e1ecuta9le
is run si1 ties #or each triangle .rocessed.
All geoetr) shader in.ut unsi?ed arra) declarations will 9e si?ed 9) an earlier in.ut .riitive la)out
=uali#ier, when .resent, as .er the #ollowing ta9le.
AaCout Si"e of Mnput ArraCs
.oints 1
lines !
lines>adDacenc) %
triangles &
triangles>adDacenc) '
-he intrinsicall) declared in.ut arra) glin67 will also 9e si?ed 9) an) in.ut .riitive8la)out declaration.
,ence, the e1.ression
gl_in+lengt.#)
will return the value #ro the ta9le a9ove.
3or in.uts declared without an arra) si?e, including intrinsicall) declared in.uts Ei.e., glinF, a la)out ust
9e declared 9e#ore an) use o# the ethod length45 or other arra) use re=uiring its si?e 9e known.
45
4 #aria$%es and &'pes
It is a co.ile8tie error i# a la)out declarationGs arra) si?e E#ro ta9le a9oveF does not atch an) arra)
si?e s.eci#ied in declarations o# an in.ut varia9le in the sae shader. -he #ollowing are all e1a.les o#
co.ile tie errors:
-- %ode seAuen%e /it.in one s.ader+++
in ve%8 Eolor'BC, -- si"e un:no/n
+++Eolor'+lengt.#)+++-- illegal1 lengt.#) un:no/n
in ve%8 Eolor9B9C, -- si"e is 9
+++Eolor'+lengt.#)+++-- illegal1 Eolor' still .as no si"e
in ve%8 Eolor;B;C, -- illegal1 input si"es are in%onsistent
la&out#lines) in, -- legal1 input si"e is 91 mat%.ing
in ve%8 Eolor8B;C, -- illegal1 %ontradi%ts la&out
+++Eolor'+lengt.#)+++-- legal1 lengt.#) is 91 Eolor' si"ed $& la&out#)
la&out#lines) in, -- legal1 mat%.es ot.er la&out#) de%laration
la&out#triangles) in,-- illegal1 does not mat%. earlier la&out#) de%laration
It is a link8tie error i# not all .rovided si?es Esi?ed in.ut arra)s and la)out si?eF atch across all
geoetr) shaders in a .rogra.
Additional la)out =uali#ier identi#iers #or gl"rag9oor( are
la,out-2ualifier-i(
origin<upper<left
pixel<center<integer
B) de#ault, gl"rag9oor( assues a lower8le#t origin #or window coordinates and assues .i1el centers
are located at hal#8.i1el coordinates. 3or e1a.le, the E*) ,F location E*.$, *.$F is returned #or the lower8
le#t8ost .i1el in a window. -he origin can 9e changed 9) redeclaring gl"rag9oor( with the
origin<upper<left identi#ier, oving the origin o# gl"rag9oor( to the u..er le#t o# the window, with ,
increasing in value toward the 9otto o# the window. -he values returned can also 9e shi#ted 9) hal# a
.i1el in 9oth * and , 9) pixel<center<integer so it a..ears the .i1els are centered at whole nu9er .i1el
o##sets. -his oves the E*, ,F value returned 9) gl"rag9oor( o# E*.$, *.$F 9) de#ault, to E*.*, *.*F with
pixel<center<integer. Redeclarations are done as #ollows
in ve%8 gl_FragEoord, -- rede%laration t.at %.anges not.ing is allo/ed
-- >ll t.e follo/ing are allo/ed rede%laration t.at %.ange $e.avior
la&out#origin_upper_left) in ve%8 gl_FragEoord,
la&out#pixel_%enter_integer) in ve%8 gl_FragEoord,
la&out#origin_upper_left1 pixel_%enter_integer) in ve%8 gl_FragEoord,
I# gl"rag9oor( is redeclared in an) #ragent shader in a .rogra, it ust 9e redeclared in all the
#ragent shaders in that .rogra that have a static use gl"rag9oor(. All redeclarations o#
gl"rag9oor( in all #ragent shaders in a single .rogra ust have the sae set o# =uali#iers. @ithin
an) shader, the #irst redeclarations o# gl"rag9oor( ust a..ear 9e#ore an) use o# gl"rag9oor(. -he
9uilt8in gl"rag9oor( is onl) .redeclared in #ragent shaders, so redeclaring it in an) other shader
language will 9e illegal.
Redeclaring gl"rag9oor( with origin<upper<left andNor pixel<center<integer =uali#iers onl) a##ects
gl"rag9oor(.* and gl"rag9oor(.,. It has no a##ect on rasteri?ation, trans#oration, or an) other .art
o# the +.en/0 .i.eline or language #eatures.
46
4 #aria$%es and &'pes
.!.3.2 Output La#out 9ualifiers
-essellation control shaders allow out.ut la)out =uali#iers onl) on the inter#ace =uali#ier out, not on an
out.ut 9lock, 9lock e9er, or varia9le declaration. -he out.ut la)out =uali#ier identi#iers allowed #or
tessellation control shaders include the verte18count la)out =uali#ier:
la,out-2ualifier-i(
vertices 7 integer-constant
-he identi#ier vertices s.eci#ies the nu9er o# vertices in the out.ut .atch .roduced 9) the tessellation
control shader, which also s.eci#ies the nu9er o# ties the tessellation control shader is invoked. It is an
error #or the out.ut verte1 count to 9e less than or e=ual to ?ero, or greater than the i.leentation8
de.endent a1iu .atch si?e.
-he intrinsicall) declared tessellation control out.ut arra) gl<out-. will also 9e si?ed 9) an) out.ut la)out
declaration. ,ence, the e1.ression
gl_out+lengt.#)
will return the out.ut .atch verte1 count s.eci#ied in a .revious out.ut la)out =uali#ier. 3or out.uts
declared without an arra) si?e, including intrinsicall) declared out.uts Ei.e., gl<outF, a la)out ust 9e
ust 9e declared 9e#ore an) use o# the ethod lengthEF or other arra) use re=uires its si?e 9e known.
It is a co.ile8tie error i# the out.ut .atch verte1 count s.eci#ied in an out.ut la)out =uali#ier does not
atch the arra) si?e s.eci#ied in an) out.ut varia9le declaration in the sae shader.
All tessellation control shader la)out declarations in a .rogra ust s.eci#) the sae out.ut .atch verte1
count. -here ust 9e at least one la)out =uali#ier s.eci#)ing an out.ut .atch verte1 count in an) .rogra
containing tessellation control shadersI however, such a declaration is not re=uired in all tessellation
control shaders.
All shaders allow location out.ut la)out =uali#iers on out.ut varia9le declarations. -he location la)out
=uali#ier identi#ier #or out.uts is:
la,out-2ualifier-i(
location 7 integer-constant
3ragent shaders allow an additional index out.ut la)out =uali#iers:
la,out-2ualifier-i(
location 7 integer-constant
index 7 integer-constant
Each o# these =uali#iers a) a..ear at ost once. I# index is s.eci#ied, location ust also 9e s.eci#ied.
I# index is not s.eci#ied, the value * is used. 3or e1a.le, in a #ragent shader,
la&out#lo%ation * ;) out ve%8 %olor,
will esta9lish that the #ragent shader out.ut color is assigned to #ragent color & as the #irst Einde1 ?eroF
in.ut to the 9lend e=uation. And,
47
4 #aria$%es and &'pes
la&out#lo%ation * ;1 index * ') out ve%8 fa%tor,
will esta9lish that the #ragent shader out.ut factor is assigned to #ragent color & as the second Einde1
oneF in.ut to the 9lend e=uation.
I# the declared out.ut is o# t).e dvecE or dvecB, it will consue two consecutive locations. +ut.uts o#
t).e double and dvecD will consue onl) a single location.
I# the declared out.ut is an arra), it will 9e assigned consecutive locations starting with the location
s.eci#ied. 3or e1a.le,
la&out#lo%ation * 9) out ve%8 %olorsB;C,
will esta9lish that colors is assigned to vector location nu9ers !, &, and %.
I# the declared out.ut is an n 1 m single8 or dou9le8.recision atri1, it will 9e assigned ulti.le locations
starting with the location s.eci#ied. -he nu9er o# locations assigned will 9e the sae as #or an n8
eleent arra) o# m8co.onent vectors.
0ocation la)out =uali#iers a) 9e used on structures, 9ut not on individual e9ers. (tructure e9ers
are assigned, in the order o# their declaration, to consecutive locations starting with the location s.eci#ied
#or the structure.
I# the naed out.ut is o# a dou9le8.recision t).e, it will 9e assigned twice the nu9er o# consecutive
locations a single .recision t).e would.
-he nu9er o# out.ut locations availa9le to a shader is liited. 3or #ragent shaders, the liit is the
advertised nu9er o# draw 9u##ers. 3or all other shaders, the liit is i.leentation8de.endent and ust
9e no less than one #ourth o# the advertised a1iu out.ut co.onent count. A .rogra will #ail to
link i# an) attached shader uses a location greater than or e=ual to the nu9er o# su..orted locations,
unless device8de.endent o.tii?ations are a9le to ake the .rogra #it within availa9le hardware
resources.
A .rogra will #ail to link i# an) two #ragent shader out.ut varia9les are assigned to the sae location
and inde1, or i# an) two out.ut varia9les #ro the sae non8#ragent shader stage are assigned to the
sae location. 3or #ragent shader out.uts, locations can 9e assigned using either a la)out =uali#ier or
via the +.en/0 A2I. 3or all shader t).es, a .rogra will #ail to link i# e1.licit location assignents
leave the linker una9le to #ind s.ace #or other varia9les without e1.licit assignents.
I# an out.ut varia9le with no location or inde1 assigned in the shader te1t has a location s.eci#ied through
the +.en/0 A2I, the A2I8assigned location will 9e used. +therwise, such varia9les will 9e assigned a
location 9) the linker. All such assignents will have a color inde1 o# ?ero. (ee section &.;.! B(hader
E1ecutionC o# the +.en/0 /ra.hics ()ste (.eci#ication #or ore details. A link error will occur i# an
in.ut varia9le is declared in ulti.le verte1 shaders with con#licting location or inde1 values.
/eoetr) shaders can have three additional t).es o# out.ut la)out identi#iers: an out.ut %rimitive t,%e, a
a1iu out.ut verte* count, and .er8out.ut stream nu9ers. -he .riitive t).e and verte1 count
identi#iers are allowed onl) on the inter#ace =uali#ier out, not on an out.ut 9lock, 9lock e9er, or
varia9le declaration. -he strea identi#ier is allowed on the inter#ace =uali#ier out, on out.ut 9locks, and
on varia9le declarations.
-he la)out =uali#ier identi#iers #or geoetr) shader out.uts are
4
4 #aria$%es and &'pes
la,out-2ualifier-i(
points
line<strip
triangle<strip
max<vertices 7 integer-constant
stream 7 integer-constant
-he .riitive t).e identi#iers points, line<strip, and triangle<strip are used to s.eci#) the t).e o# out.ut
.riitive .roduced 9) the geoetr) shader, and onl) one o# these is acce.ted. At least one geoetr)
shader Eco.ilation unitF in a .rogra ust declare an out.ut .riitive t).e, and all geoetr) shader
out.ut .riitive t).e declarations in a .rogra ust declare the sae .riitive t).e. It is not re=uired
that all geoetr) shaders in a .rogra declare an out.ut .riitive t).e.
-he verte1 count identi#ier max<vertices is used to s.eci#) the a1iu nu9er o# vertices the shader
will ever eit in a single invocation. At least one geoetr) shader Eco.ilation unitF in a .rogra ust
declare a a1iu out.ut verte1 count, and all geoetr) shader out.ut verte1 count declarations in a
.rogra ust declare the sae count. It is not re=uired that all geoetr) shaders in a .rogra declare a
count.
In this e1a.le,
la&out#triangle_strip1 max_verti%es * G=) out, -- order does not matter
la&out#max_verti%es * G=) out, -- rede%laration o:a&
la&out#triangle_strip) out, -- rede%laration o:a&
la&out#points) out, -- error1 %ontradi%ts triangle_strip
la&out#max_verti%es * ;=) out, -- error1 %ontradi%ts G=
all out.uts #ro the geoetr) shader are triangles and at ost '* vertices will 9e eitted 9) the shader. It
is an error #or the a1iu nu9er o# vertices to 9e greater than gl<Hax@eometrCOutputTertices.
-he identi#ier stream is used to s.eci#) that a geoetr) shader out.ut varia9le or 9lock is associated with
a .articular verte1 strea Enu9ered 9eginning with ?eroF. A de#ault strea nu9er a) 9e declared at
glo9al sco.e 9) =uali#)ing inter#ace =uali#ier out as in this e1a.le:
la&out#stream * ') out,
-he strea nu9er s.eci#ied in such a declaration re.laces an) .revious de#ault and a..lies to all
su9se=uent 9lock and varia9le declarations until a new de#ault is esta9lished. -he initial de#ault strea
nu9er is ?ero.
4!
4 #aria$%es and &'pes
Each out.ut 9lock or non89lock out.ut varia9le is associated with a verte1 strea. I# the 9lock or varia9le
is declared with the strea identi#ier, it is associated with the s.eci#ied streaI otherwise, it is associated
with the current de#ault strea. A 9lock e9er a) 9e declared with a strea identi#ier, 9ut the
s.eci#ied strea ust atch the strea associated with the containing 9lock. +ne e1a.le:
la&out#stream*') out, -- default is no/ stream '
out ve%8 var', -- var' gets default stream #')
la&out#stream*9) out 6lo%:' ) -- I6lo%:'I $elongs to stream 9
la&out#stream*9) ve%8 var9, -- redundant $lo%: mem$er stream de%l
la&out#stream*;) ve%9 var;, -- ILLE!>L #must mat%. $lo%: stream)
ve%; var8, -- $elongs to stream 9
3,
la&out#stream*=) out, -- default is no/ stream =
out ve%8 var<, -- var< gets default stream #=)
out 6lo%:9 ) -- I6lo%:9I gets default stream #=)
ve%8 varG,
3,
la&out#stream*;) out ve%8 varF, -- varF $elongs to stream ;
Each verte1 eitted 9) the geoetr) shader is assigned to a s.eci#ic strea, and the attri9utes o# the
eitted verte1 are taken #ro the set o# out.ut 9locks and varia9les assigned to the targeted strea. A#ter
each verte1 is eitted, the values o# all out.ut varia9les 9ecoe unde#ined. Additionall), the out.ut
varia9les associated with each verte1 strea a) share storage. @riting to an out.ut varia9le associated
with one strea a) overwrite out.ut varia9les associated with an) other strea. @hen eitting each
verte1, a geoetr) shader should write to all out.uts associated with the strea to which the verte1 will
9e eitted and to no out.uts associated with an) other strea.
I# a geoetr) shader out.ut 9lock or varia9le is declared ore than once, all such declarations ust
associate the varia9le with the sae verte1 strea. I# an) strea declaration s.eci#ies a non8e1istent
strea nu9er, the shader will #ail to co.ile.
Built8in geoetr) shader out.uts are alwa)s associated with verte1 strea ?ero.
All geoetr) shader out.ut la)out declarations in a .rogra ust declare the sae la)out and sae value
#or max<vertices. I# geoetr) shaders are in a .rogra, there ust 9e at least one geoetr) out.ut
la)out declaration soewhere in that .rogra, 9ut not all geoetr) shaders Eco.ilation unitsF are
re=uired to declare it.
.!.3.! 4niform -loc0 La#out 9ualifiers
0a)out =uali#iers can 9e used #or uni#or 9locks, 9ut not #or non89lock uni#or declarations. -he la)out
=uali#ier identi#iers #or uni#or 9locks are
la,out-2ualifier-i(
shared
packed
std1B%
row<maIor
column<maIor
5"
4 #aria$%es and &'pes
7one o# these have an) seantic a##ect at all on the usage o# the varia9les 9eing declaredI the) onl)
descri9e how data is laid out in eor). 3or e1a.le, atri1 seantics are alwa)s colun89ased, as
descri9ed in the rest o# this s.eci#ication, no atter what la)out =uali#iers are 9eing used.
6ni#or 9lock la)out =uali#iers can 9e declared #or glo9al sco.e, on a single uni#or 9lock, or on a single
9lock e9er declaration.
De#ault la)outs are esta9lished at glo9al sco.e #or uni#or 9locks as
la&out#la,out-2ualifier-i(-list) uniform,
@hen this is done, the .revious de#ault =uali#ication is #irst inherited and then overridden as .er the
override rules listed 9elow #or each =uali#ier listed in the declaration. -he result 9ecoes the new de#ault
=uali#ication sco.ed to su9se=uent uni#or 9lock de#initions.
-he initial state o# co.ilation is as i# the #ollowing were declared:
la&out#s.ared1 %olumn_ma7or) uniform,
E1.licitl) declaring this in a shader will return de#aults 9ack to their initial state.
6ni#or 9locks can 9e declared with o.tional la)out =uali#iers, and so can their individual e9er
declarations. (uch 9lock la)out =uali#ication is sco.ed onl) to the content o# the 9lock. As with glo9al
la)out declarations, 9lock la)out =uali#ication #irst inherits #ro the current de#ault =uali#ication and then
overrides it. (iilarl), individual e9er la)out =uali#ication is sco.ed Dust to the e9er declaration,
and inherits #ro and overrides the 9lockGs =uali#ication.
-he share( =uali#ier overrides onl) the st(140 and %ac0e( =uali#iersI other =uali#iers are inherited. -he
co.ilerNlinker will ensure that ulti.le .rogras and .rograa9le stages containing this de#inition
will share the sae eor) la)out #or this 9lock, as long as the) also atched in their rowma:or andNor
columnma:or =uali#ications. -his allows use o# the sae 9u##er to 9ack the sae 9lock de#inition across
di##erent .rogras.
-he %ac0e( =uali#ier overrides onl) st(140 and share(I other =uali#iers are inherited. @hen %ac0e( is
used, no sharea9le la)out is guaranteed. -he co.iler and linker can o.tii?e eor) use 9ased on what
varia9les activel) get used and on other criteria. +##sets ust 9e =ueried, as there is no other wa) o#
guaranteeing where Eand whichF varia9les reside within the 9lock. Atte.ts to share a .acked uni#or
9lock across .rogras or stages will generall) #ail. ,owever, i.leentations a) aid a..lication
anageent o# .acked 9locks 9) using canonical la)outs #or .acked 9locks.
-he st(140 =uali#ier overrides onl) the %ac0e( and share( =uali#iersI other =uali#iers are inherited. -he
la)out is e1.licitl) deterined 9) this, as descri9ed in section !.11.% B6ni#or Varia9lesC under (tandard
6ni#or Block 0a)out o# the +.en/0 /ra.hics ()ste (.eci#ication. ,ence, as in share( a9ove, the
resulting la)out is sharea9le across .rogras.
0a)out =uali#iers on e9er declarations cannot use the share(, %ac0e(, or st(140 =uali#iers. -hese can
onl) 9e used at glo9al sco.e or on a 9lock declaration.
-he rowma:or =uali#ier overrides onl) the columnma:or =uali#ierI other =uali#iers are inherited. It onl)
a##ects the la)out o# atrices. Eleents within a atri1 row will 9e contiguous in eor).
51
4 #aria$%es and &'pes
-he columnma:or =uali#ier overrides onl) the rowma:or =uali#ierI other =uali#iers are inherited. It onl)
a##ects the la)out o# atrices. Eleents within a atri1 colun will 9e contiguous in eor).
@hen ulti.le arguents are listed in a laCout declaration, the a##ect will 9e 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 .revious =uali#ication.
3or e1a.le
la&out#ro/_ma7or1 %olumn_ma7or)
results in the =uali#ication 9eing columnma:or. +ther e1a.les:
la&out#s.ared1 ro/_ma7or) uniform, -- default is no/ s.ared and ro/_ma7or
la&out#std'8=) uniform Transform ) -- la&out of t.is $lo%: is std'8=
mat8 ?', -- ro/_ma7or
la&out#%olumn_ma7or) mat8 ?9, -- %olumn ma7or
mat; N', -- ro/_ma7or
3,
uniform T9 ) -- la&out of t.is $lo%: is s.ared
+++
3,
la&out#%olumn_ma7or) uniform T; ) -- s.ared and %olumn_ma7or
mat8 ?;, -- %olumn_ma7or
la&out#ro/_ma7or) mat8 m8, -- ro/ ma7or
mat; N9, -- %olumn_ma7or
3,
.!.8 Interpolation
-he .resence o# and t).e o# inter.olation is controlled 9) the storage =uali#iers centroid in, sample in,
centroid out, and sample out, 9) the o.tional inter.olation =uali#iers smooth, flat, and noperspective,
and 9) de#ault 9ehaviors esta9lished through the +.en/0 A2I when no inter.olation =uali#ier is .resent.
@hen an inter.olation =uali#ier is used, it overrides settings esta9lished through the +.en/0 A2I. It is a
co.ile8tie error to use ore than one inter.olation =uali#ier.
A varia9le =uali#ied as flat will not 9e inter.olated. Instead, it will have the sae value #or ever)
#ragent within a triangle. -his value will coe #ro a single .rovoking verte1, as descri9ed 9) the
+.en/0 /ra.hics ()ste (.eci#ication. A varia9le a) 9e =uali#ied as flat centroid or flat sample,
which will ean the sae thing as =uali#)ing it onl) as flat.
A varia9le =uali#ied as smooth will 9e inter.olated in a .ers.ective8correct anner over the .riitive
9eing rendered. Inter.olation in a .ers.ective correct anner is s.eci#ied in e=uation &.' in the +.en/0
/ra.hics ()ste (.eci#ication, section &.$ B0ine (egentsC.
A varia9le =uali#ied as noperspective ust 9e inter.olated linearl) in screen s.ace, as descri9ed in
e=uation &.4 in the +.en/0 /ra.hics ()ste (.eci#ication, section &.$ B0ine (egentsC.
52
4 #aria$%es and &'pes
@hen ulti8sa.le rasteri?ation is disa9led, or #or #ragent shader in.ut varia9les =uali#ied with neither
centroid in nor sample in, the value o# the assigned varia9le a) 9e inter.olated an)where within the
.i1el and a single value a) 9e assigned to each sa.le within the .i1el, to the e1tent .eritted 9) the
+.en/0 /ra.hics ()ste (.eci#ication.
@hen ultisa.le rasteri?ation is ena9led, centroid and sample a) 9e used to control the location and
#re=uenc) o# the sa.ling o# the =uali#ied #ragent shader in.ut. I# a #ragent shader in.ut is =uali#ied
with centroid in, a single value a) 9e assigned to that varia9le #or all sa.les in the .i1el, 9ut that value
ust 9e inter.olated to a location that lies in 9oth the .i1el and in the .riitive 9eing rendered, including
an) o# the .i1elGs sa.les covered 9) the .riitive. Because the sa.le to which the varia9le is
inter.olated a) 9e di##erent in neigh9oring .i1els, derivatives o# centroid8sa.led in.uts a) 9e less
accurate than those #or non8centroid inter.olated varia9les. I# a #ragent shader in.ut is =uali#ied with
sample in, a se.arate value ust 9e assigned to that varia9le #or each covered sa.le in the .i1el, and
that value ust 9e sa.led at the location o# the individual sa.le.
-he t).e and .resence o# the inter.olation =uali#iers and storage =uali#iers and invariant =uali#iers o#
varia9les with the sae nae declared in all linked shaders ust atch, otherwise the link coand will
#ail.
.!.8.1 :edeclaring -uilt6in Interpolation $ariables in the Compatibilit# +rofile
-he #ollowing .redeclared varia9les can 9e redeclared with an inter.olation =uali#ier when using the
co.ati9ilit) .ro#ile:
Verte1, tessellation control, tessellation evaluation, and geoetr) languages:
gl_FrontEolor
gl_6a%:Eolor
gl_FrontSe%ondar&Eolor
gl_6a%:Se%ondar&Eolor
3ragent language:
gl_Eolor
gl_Se%ondar&Eolor
3or e1a.le,
in ve%8 gl_Eolor, -- prede%lared $& t.e fragment language
flat in ve%8 gl_Eolor, -- rede%lared $& user to $e flat
flat in ve%8 gl_FrontEolor, -- input to geometr& s.ader1 no 4gl_inBC5
flat out ve%8 gl_FrontEolor, -- output from geometr& s.ader
Ideall), these are redeclared as .art o# the redeclaration o# an inter#ace 9lock, as descri9ed in section 4.1.1
B"o.ati9ilit) 2ro#ile Built8In 0anguage Varia9lesC. ,owever, #or the a9ove .ur.ose, the) can 9e
redeclared as individual varia9les at glo9al sco.e, outside an inter#ace 9lock. A co.ilation error will
result i# a shader has 9oth an inter#ace 9lock redeclaration and a se.arate redeclaration o# a e9er o#
that inter#ace 9lock outside the inter#ace 9lock redeclaration.
53
4 #aria$%es and &'pes
I# gl9olor is redeclared with an inter.olation =uali#ier, then gl"ront9olor and gl;ac09olor Ei# the)
are written toF ust also 9e redeclared with the sae inter.olation =uali#ier, and vice versa. I#
gl'econ(ar,9olor is redeclared with an inter.olation =uali#ier, then gl"ront'econ(ar,9olor and
gl;ac0'econ(ar,9olor Ei# the) are written toF ust also 9e redeclared with the sae inter.olation
=uali#ier, and vice versa. -his =uali#ier atching on .redeclared varia9les is onl) re=uired #or varia9les
that are staticall) used within the shaders in a .rogra.
. +arameter 9ualifiers
2araeters can have these =uali#iers.
9ualifier 7eaning
P none: de#ault Q sae is in
in #or #unction .araeters .assed into a #unction
out #or #unction .araeters .assed 9ack out o# a #unction, 9ut not initiali?ed
#or use when .assed in
inout #or #unction .araeters .assed 9oth into and out o# a #unction
2araeter =uali#iers are discussed in ore detail in section '.1.1 B3unction "alling "onventionsC.
.5 +recision and +recision 9ualifiers
2recision =uali#iers are added #or code .orta9ilit) with +.en/0 E(, not #or #unctionalit). -he) have the
sae s)nta1 as in +.en/0 E(, as descri9ed 9elow, 9ut the) have no seantic eaning, which includes no
e##ect on the .recision used to store or o.erate on varia9les.
I# an e1tension adds in the sae seantics and #unctionalit) in the +.en/0 E( !.* s.eci#ication #or
.recision =uali#iers, then the e1tension is allowed to reuse the ke)words 9elow #or that .ur.ose.
.5.1 :ange and +recision
-he .recision o# stored single8 and dou9le8.recision #loating8.oint varia9les is de#ined 9) the IEEE 4$%
standard #or &!89it and '%89it #loating8.oint nu9ers. -his includes su..ort #or 7a7s E7ot a 7u9erF
and In#s E.ositive or negative in#initiesF.
-he #ollowing rules a..l) to 9oth single and dou9le8.recision o.erations: Dividing 9) * results in the
a..ro.riatel) signed IEEE In#. An) denorali?ed value in.ut into a shader or .otentiall) generated 9) an
o.eration in a shader can 9e #lushed to *. In general, correct signedness o# * is not re=uired. -he
rounding ode cannot 9e set and is unde#ined. (u..ort #or signaling 7a7s is not re=uired and e1ce.tions
are never raised. +.erations and 9uilt8in #unctions that o.erate on a 7a7 are not re=uired to return a 7a7
as the result.
2recisions are e1.ressed in ters o# a1iu relative error in units o# 602 Eunits in the last .laceF,
unless otherwise noted.
54
4 #aria$%es and &'pes
3or single .recision o.erations, .recisions are re=uired as #ollows:
Operation Qrecision
a J +, a [ +, a M + "orrectl) rounded.
P, PR, RR, Q, QR "orrect result.
a N +, 1.* N + !.$ 602 #or + in the range Y!
81!'
, !
1!'
Z.
a M + J c "orrectl) rounded single o.eration or se=uence o#
two correctl) rounded o.erations.
fmaEF Inherited #ro a M + J c.
powE*, ,F Inherited #ro expD E* < logD E,FF.
exp E*F, expD E*F E& J ! M U*UF 602.
log EF, logD EF & 602 outside the range Y*.$, !.*Z.
A9solute error P !
8!1
inside the range Y*.$, !.*Z.
srt EF Inherited #ro 1.* N inversesrtEF.
inversesrt EF ! 602.
i.licit and e1.licit
conversions 9etween t).es
"orrectl) rounded.
Built8in #unctions de#ined in the s.eci#ication with an e=uation 9uilt #ro the a9ove o.erations inherit the
a9ove errors. -hese include, #or e1a.le, the geoetric #unctions, the coon #unctions, and an) o#
the atri1 #unctions. Built8in #unctions not listed a9ove and not de#ined as e=uations o# the a9ove have
unde#ined .recision. -hese include, #or e1a.le, the trigonoetric #unctions and deterinant.
-he .recision o# dou9le8.recision o.erations is at least that o# single .recision.
.5.2 +recision 9ualifiers
An) #loating .oint or an) integer declaration can have the t).e .receded 9) one o# these .recision
=uali#iers:
9ualifier 7eaning
highp 7one.
mediump 7one.
lowp 7one.
55
4 #aria$%es and &'pes
3or e1a.le:
lo/p float %olor,
out mediump ve%9 @,
lo/p ive%9 foo#lo/p mat;),
.ig.p mat8 m,
0iteral constants do not have .recision =uali#iers. 7either do Boolean varia9les. 7either do #loating .oint
constructors nor integer constructors when none o# the constructor arguents have .recision =uali#iers.
2recision =uali#iers, as with other =uali#iers, do not e##ect the 9asic t).e o# the varia9le. In .articular,
there are no constructors #or .recision conversionsI constructors onl) convert t).es. (iilarl), .recision
=uali#iers, as with other =uali#iers, do not contri9ute to #unction overloading 9ased on .araeter t).es. As
discussed in the ne1t cha.ter, #unction in.ut and out.ut is done through co.ies, and there#ore =uali#iers do
not have to atch.
-he sae o9Dect declared in di##erent shaders that are linked together ust have the sae .recision
=uali#ication. -his a..lies to in.uts, out.uts, uni#ors, and glo9als.
.5.! )efault +recision 9ualifiers
-he .recision stateent
pre%ision pre%ision2Aualifier t&pe,
can 9e used to esta9lish a de#ault .recision =uali#ier. -he tCpe #ield can 9e either int or float, and the
%recision-2ualifier can 9e lowp, mediump, or highp. An) other t).es or =uali#iers will result in an error.
I# t,%e is float, the directive a..lies to non8.recision8=uali#ied #loating .oint t).e Escalar, vector, and
atri1F declarations. I# t,%e is int, the directive a..lies to all non8.recision8=uali#ied integer t).e Escalar,
vector, signed, and unsignedF declarations. -his includes glo9al varia9le declarations, #unction return
declarations, #unction .araeter declarations, and local varia9le declarations.
7on8.recision =uali#ied declarations will use the .recision =uali#ier s.eci#ied in the ost recent precision
stateent that is still in sco.e. -he precision stateent has the sae sco.ing rules as varia9le
declarations. I# it is declared inside a co.ound stateent, its e##ect sto.s at the end o# the innerost
stateent it was declared in. 2recision stateents in nested sco.es override .recision stateents in outer
sco.es. :ulti.le .recision stateents #or the sae 9asic t).e can a..ear inside the sae sco.e, with later
stateents overriding earlier stateents within that sco.e.
-he verte1 and geoetr) languages have the #ollowing .redeclared glo9all) sco.ed de#ault .recision
stateents:
pre%ision .ig.p float,
pre%ision .ig.p int,
-he #ragent language has the #ollowing .redeclared glo9all) sco.ed de#ault .recision stateents:
pre%ision mediump int,
pre%ision .ig.p float,
56
4 #aria$%es and &'pes
.5. .vailable +recision 9ualifiers
-he 9uilt8in acro /0>3RA/:E7->2RE"I(I+7>,I/, is de#ined to 1:
#define !L_FR>!?ENT_@REEISION_JI!J '
-his acro is availa9le in the verte1, geoetr), and #ragent languages.
." $ariance and the Invariant 9ualifier
In this section, variance re#ers to the .ossi9ilit) o# getting di##erent values #ro the sae e1.ression in
di##erent .rogras. 3or e1a.le, sa) two verte1 shaders, in di##erent .rogras, each set gl!osition with
the sae e1.ression in 9oth shaders, and the in.ut values into that e1.ression are the sae when 9oth
shaders run. It is .ossi9le, due to inde.endent co.ilation o# the two shaders, that the values assigned to
gl!osition are not e1actl) the sae when the two shaders run. In this e1a.le, this can cause .ro9les
with alignent o# geoetr) in a ulti8.ass algorith.
In general, such variance 9etween shaders is allowed. @hen such variance does not e1ist #or a .articular
out.ut varia9le, that varia9le is said to 9e invariant.
.".1 The Invariant 9ualifier
-o ensure that a .articular out.ut varia9le is invariant, it is necessar) to use the invariant =uali#ier. It can
either 9e used to =uali#) a .reviousl) declared varia9le as 9eing invariant
invariant gl_@osition, -- ma:e existing gl_@osition $e invariant
out ve%; Eolor,
invariant Eolor, -- ma:e existing Eolor $e invariant
or as .art o# a declaration when a varia9le is declared
invariant %entroid out ve%; Eolor,
-he invariant =uali#ier ust a..ear 9e#ore an) inter.olation =uali#iers or storage =uali#iers when
co9ined with a declaration. +nl) varia9les out.ut #ro a shader Eincluding those that are then in.ut to a
su9se=uent shaderF can 9e candidates #or invariance. -his includes user8de#ined out.ut varia9les and the
9uilt8in out.ut varia9les. 3or varia9les leaving one shader and coing into another shader, the invariant
ke)word has to 9e used in 9oth shaders, or a link error will result.
In.ut or out.ut instance naes on 9locks are not used when redeclaring 9uilt8in varia9les.
-he invariant ke)word can 9e #ollowed 9) a coa se.arated list o# .reviousl) declared identi#iers. All
uses o# invariant ust 9e at the glo9al sco.e, and 9e#ore an) use o# the varia9les 9eing declared as
invariant.
-o guarantee invariance o# a .articular out.ut varia9le across two .rogras, the #ollowing ust also 9e
true:
-he out.ut varia9le is declared as invariant in 9oth .rogras.
-he sae values ust 9e in.ut to all shader in.ut varia9les consued 9) e1.ressions and #low control
contri9uting to the value assigned to the out.ut varia9le.
57
4 #aria$%es and &'pes
-he te1ture #orats, te1el values, and te1ture #iltering are set the sae wa) #or an) te1ture #unction
calls contri9uting to the value o# the out.ut varia9le.
All in.ut values are all o.erated on in the sae wa). All o.erations in the consuing e1.ressions and
an) interediate e1.ressions ust 9e the sae, with the sae order o# o.erands and sae
associativit), to give the sae order o# evaluation. Interediate varia9les and #unctions ust 9e
declared as the sae t).e with the sae e1.licit or i.licit .recision =uali#iers. An) control #low
a##ecting the out.ut value ust 9e the sae, and an) e1.ressions consued to deterine this control
#low ust also #ollow these invariance rules.
All the data #low and control #low leading to setting the invariant out.ut varia9le reside in a single
co.ilation unit.
Essentiall), all the data #low and control #low leading to an invariant out.ut ust atch.
Initiall), 9) de#ault, all out.ut varia9les are allowed to 9e variant. -o #orce all out.ut varia9les to 9e
invariant, use the .raga
#pragma ST!L invariant#all)
9e#ore all declarations in a shader. I# this .raga is used a#ter the declaration o# an) varia9les or
#unctions, then the set o# out.uts that 9ehave as invariant is unde#ined. It is an error to use this .raga in
a #ragent shader.
/enerall), invariance is ensured at the cost o# #le1i9ilit) in o.tii?ation, so .er#orance can 9e degraded
9) use o# invariance. ,ence, use o# this .raga is intended as a de9ug aid, to avoid individuall) declaring
all out.ut varia9les as invariant.
.".2 Invariance of Constant '*pressions
Invariance ust 9e guaranteed #or constant e1.ressions. A .articular constant e1.ression ust evaluate to
the sae result i# it a..ears again in the sae shader or a di##erent shader. -his includes the sae
e1.ression a..earing two shaders o# the sae language or shaders o# two di##erent languages.
"onstant e1.ressions ust evaluate to the sae result when o.erated on as alread) descri9ed a9ove #or
invariant varia9les.
.2 The +recise 9ualifier
(oe algoriths re=uire #loating8.oint co.utations to e1actl) #ollow the order o# o.erations s.eci#ied in
the source code and to treat all o.erations consistentl), even i# the i.leentation su..orts o.tii?ations
that could .roduce nearl) e=uivalent results with higher .er#orance. 3or e1a.le, an) /0
i.leentations su..ort a Vulti.l)8addV instruction that can co.ute a #loating8.oint e1.ression such as
result * #a K $) L #% K d),
5
4 #aria$%es and &'pes
in two o.erations instead o# three o.erationsI one ulti.l) and one ulti.l)8add instead o# two ulti.lies
and one add. -he result o# a #loating8.oint ulti.l)8add a) not alwa)s 9e identical to #irst doing a
ulti.l) )ielding a #loating8.oint result and then doing a #loating8.oint add. ,ence, in this e1a.le, the
two ulti.l) o.erations would not 9e treated consistentl)I the two ulti.lies could e##ectivel) a..ear to
have di##ering .recisions. @ithout an) =uali#iers, i.leentations are .eritted to .er#or such
o.tii?ations that e##ectivel) odi#) the order or nu9er o# o.erations used to evaluate an e1.ression,
even i# those o.tii?ations a) .roduce slightl) di##erent results relative to uno.tii?ed code.
-he =uali#ier precise will ensure that o.erations contri9uting to a varia9leGs value are done in their stated
order and are done with o.erator consistenc). +rder is deterined 9) o.erator .recedence and
.arenthesis, as descri9ed in section $.1 B+.eratorsC. +.erator consistenc) eans #or each .articular
o.erator, #or e1a.le the ulti.l) o.erator E ) F, its o.eration is alwa)s co.uted with the sae
.recision. 7ote this e##ectivel) .revents #using ulti.le o.erations into a single o.eration.
3or e1a.le,
pre%ise out ve%8 position,
declares that o.erations used to .roduce the value o# %osition ust 9e .er#ored in e1actl) the order
s.eci#ied in the source code and with all o.erators 9eing treated consistentl). As with the invariant
=uali#ier Esection %.'.1F, the .recise =uali#ier a) 9e used to =uali#) a 9uilt8in or .reviousl) declared user8
de#ined varia9le as 9eing .recise:
out ve%; Eolor,
pre%ise Eolor, -- ma:e existing Eolor $e pre%ise
-his =uali#ier will a##ect the evaluation o# an r8value in a .articular #unction i# and onl) i# the result is
eventuall) consued in the sae #unction 9) an l8value =uali#ied as precise. An) other e1.ressions
within a #unction are not a##ected, including return values and out.ut .araeters not declared as precise
9ut that are eventuall) consued outside the #unction 9) an varia9le =uali#ied as precise.
5!
4 #aria$%es and &'pes
(oe e1a.les o# the use o# precise:
in ve%8 a1 $1 %1 d,
pre%ise out ve%8 v,
float fun%#float e1 float f1 float g1 float .)
)
return #eKf) L #gK.), -- no %onstraint on order or
-- operator %onsisten%&
3
float fun%9#float e1 float f1 float g1 float .)
)
pre%ise float result * #eKf) L #gK.), -- ensures same pre%ision for
-- t.e t/o multiplies
return result,
3
float fun%;#float i1 float 71 pre%ise out float :)
)
: * i K i L 7, -- pre%ise1 due to 0:M de%laration
3
void main#)
)
ve%8 r * ve%;#a K $), -- pre%ise1 used to %ompute v+x&"
ve%8 s * ve%;#% K d), -- pre%ise1 used to %ompute v+x&"
v+x&" * r L s, -- pre%ise
v+/ * #a+/ K $+/) L #%+/ K d+/), -- pre%ise
v+x * fun%#a+x1 $+x1 %+x1 d+x), -- values %omputed in fun%#)
-- are NOT pre%ise
v+x * fun%9#a+x1 $+x1 %+x1 d+x), -- pre%iseN
fun%;#a+x K $+x1 %+x K d+x1 v+x), -- pre%iseN
3
.3 Order of 9ualification
@hen ulti.le =uali#ications are .resent, the) ust #ollow a strict order. -his order is as #ollows.
%recise-2ualifier invariant-2ualifier inter%olation-2ualifier storage-2ualifier %recision-2ualifier
storage-2ualifier %arameter-2ualifier %recision-2ualifier
6"
5 Operators and '*pressions
5.1 Operators
-he +.en/0 (hading 0anguage has the #ollowing o.erators.
+recedence Operator Class Operators .ssociativit#
1 EhighestF .arenthetical grou.ing / 0 7A
!
arra) su9scri.t
#unction call and constructor structure
#ield or ethod selector, swi??ler
.ost #i1 increent and decreent
- .
/ 0
.
'' !!
0e#t to Right
&
.re#i1 increent and decreent
unar)
'' !!
' ! 6 8
Right to 0e#t
% ulti.licative ) ( * 0e#t to Right
$ additive ' ! 0e#t to Right
' 9it8wise shi#t ++ ,, 0e#t to Right
4 relational + , +7 ,7 0e#t to Right
5 e=ualit) 77 87 0e#t to Right
; 9it8wise and 5 0e#t to Right
1* 9it8wise e1clusive or 3 0e#t to Right
11 9it8wise inclusive or 4 0e#t to Right
1! logical and 55 0e#t to Right
1& logical e1clusive or 33 0e#t to Right
1% logical inclusive or 4 4 0e#t to Right
1$ selection ; 9 Right to 0e#t
1'
Assignent
arithetic assignents
7
'7 !7
)7 (7
*7 ++7 ,,7
57 37 47
Right to 0e#t
14 ElowestF se=uence $ 0e#t to Right
-here is no address8o# o.erator nor a dere#erence o.erator. -here is no t).ecast o.eratorI constructors
are used instead.
61
5 Operators and ()pressions
5.2 .rra# Operations
-hese are now descri9ed in section $.4 B(tructure and Arra) +.erationsC.
5.! ,unction Calls
I# a #unction returns a value, then a call to that #unction a) 9e used as an e1.ression, whose t).e will 9e
the t).e that was used to declare or de#ine the #unction.
3unction de#initions and calling conventions are discussed in section '.1 B3unction De#initionsC .
5. Constructors
"onstructors use the #unction call s)nta1, where the #unction nae is a t).e, and the call akes an o9Dect
o# that t).e. "onstructors are used the sae wa) in 9oth initiali?ers and e1.ressions. E(ee section ;
B(hading 0anguage /raarC #or details.F -he .araeters are used to initiali?e the constructed value.
"onstructors can 9e used to re=uest a data t).e conversion to change #ro one scalar t).e to another
scalar t).e, or to 9uild larger t).es out o# saller t).es, or to reduce a larger t).e to a saller t).e.
In general, constructors are not 9uilt8in #unctions with .redeterined .rotot).es. 3or arra)s and
structures, there ust 9e e1actl) one arguent in the constructor #or each eleent or #ield. 3or the other
t).es, the arguents ust .rovide a su##icient nu9er o# co.onents to .er#or the initiali?ation, and it
is an error to include so an) arguents that the) cannot all 9e used. Detailed rules #ollow. -he
.rotot).es actuall) listed 9elow are erel) a su9set o# e1a.les.
5..1 Conversion and Scalar Constructors
"onverting 9etween scalar t).es is done as the #ollowing .rotot).es indicate:
int#uint) -- %onverts an unsigned integer to a signed integer
int#$ool) -- %onverts a 6oolean value to an int
int#float) -- %onverts a float value to an int
int#dou$le) -- %onverts a dou$le value to a signed integer
uint#int) -- %onverts a signed integer value to an unsigned integer
uint#$ool) -- %onverts a 6oolean value to an unsigned integer
uint#float) -- %onverts a float value to an unsigned integer
uint#dou$le) -- %onverts a dou$le value to an unsigned integer
$ool#int) -- %onverts a signed integer value to a 6oolean
$ool#uint) -- %onverts an unsigned integer value to a 6oolean value
$ool#float) -- %onverts a float value to a 6oolean
$ool#dou$le) -- %onverts a dou$le value to a 6oolean
float#int) -- %onverts a signed integer value to a float
float#uint) -- %onverts an unsigned integer value to a float value
float#$ool) -- %onverts a 6oolean value to a float
float#dou$le)-- %onverts a dou$le value to a float
dou$le#int) -- %onverts a signed integer value to a dou$le
dou$le#uint) -- %onverts an unsigned integer value to a dou$le
dou$le#$ool) -- %onverts a 6oolean value to a dou$le
dou$le#float)-- %onverts a float value to a dou$le
62
5 Operators and ()pressions
@hen constructors are used to convert an) #loating8.oint t).e to an integer t).e, the #ractional .art o# the
#loating8.oint value is dro..ed. It is unde#ined to convert a negative #loating .oint value to an uint.
@hen a constructor is used to convert an) integer or #loating8.oint t).e to a bool, * and *.* are converted
to false, and non8?ero values are converted to true. @hen a constructor is used to convert a bool to an)
integer or #loating8.oint t).e, false is converted to * or *.*, and true is converted to 1 or 1.*.
-he constructor intEuintF .reserves the 9it .attern in the arguent, which will change the arguentGs
value i# its sign 9it is set. -he constructor uintEintF .reserves the 9it .attern in the arguent, which will
change its value i# it is negative.
Identit) constructors, like floatEfloatF are also legal, 9ut o# little use.
(calar constructors with non8scalar .araeters can 9e used to take the #irst eleent #ro a non8scalar.
3or e1a.le, the constructor floatEvecEF will select the #irst co.onent o# the vecE .araeter.
5..2 $ector and 7atri* Constructors
"onstructors can 9e used to create vectors or atrices #ro a set o# scalars, vectors, or atrices. -his
includes the a9ilit) to shorten vectors.
I# there is a single scalar .araeter to a vector constructor, it is used to initiali?e all co.onents o# the
constructed vector to that scalarHs value. I# there is a single scalar .araeter to a atri1 constructor, it is
used to initiali?e all the co.onents on the atri1Hs diagonal, with the reaining co.onents initiali?ed
to *.*.
I# a vector is constructed #ro ulti.le scalars, one or ore vectors, or one or ore atrices, or a i1ture
o# these, the vectorGs co.onents will 9e constructed in order #ro the co.onents o# the arguents. -he
arguents will 9e consued le#t to right, and each arguent will have all its co.onents consued, in
order, 9e#ore an) co.onents #ro the ne1t arguent are consued. (iilarl) #or constructing a atri1
#ro ulti.le scalars or vectors, or a i1ture o# these. :atri1 co.onents will 9e constructed and
consued in colun aDor order. In these cases, there ust 9e enough co.onents .rovided in the
arguents to .rovide an initiali?er #or ever) co.onent in the constructed value. It is an error to .rovide
e1tra arguents 9e)ond this last used arguent.
I# a atri1 is constructed #ro a atri1, then each co.onent Ecolun i) row :F in the result that has a
corres.onding co.onent Ecolun i) row :F in the arguent will 9e initiali?ed #ro there. All other
co.onents will 9e initiali?ed to the identit) atri1. I# a atri1 arguent is given to a atri1 constructor,
it is an error to have an) other arguents.
I# the 9asic t).e Ebool$ int$ float, or doubleF o# a .araeter to a constructor does not atch the 9asic t).e
o# the o9Dect 9eing constructed, the scalar construction rules Ea9oveF are used to convert the .araeters.
63
5 Operators and ()pressions
(oe use#ul vector constructors are as #ollows:
ve%;#float) -- initiali"es ea%. %omponent of t.e ve%; /it. t.e float
ve%8#ive%8) -- ma:es a ve%8 /it. %omponent2/ise %onversion
ve%8#mat9) -- t.e ve%8 is %olumn = follo/ed $& %olumn '
ve%9#float1 float) -- initiali"es a ve%9 /it. 9 floats
ive%;#int1 int1 int) -- initiali"es an ive%; /it. ; ints
$ve%8#int1 int1 float1 float) -- uses 8 6oolean %onversions
ve%9#ve%;) -- drops t.e t.ird %omponent of a ve%;
ve%;#ve%8) -- drops t.e fourt. %omponent of a ve%8
ve%;#ve%91 float) -- ve%;+x * ve%9+x1 ve%;+& * ve%9+&1 ve%;+" * float
ve%;#float1 ve%9) -- ve%;+x * float1 ve%;+& * ve%9+x1 ve%;+" * ve%9+&
ve%8#ve%;1 float)
ve%8#float1 ve%;)
ve%8#ve%91 ve%9)
(oe e1a.les o# these are:
ve%8 %olor * ve%8#=+=1 '+=1 =+=1 '+=),
ve%8 rg$a * ve%8#'+=), -- sets ea%. %omponent to '+=
ve%; rg$ * ve%;#%olor), -- drop t.e 8t. %omponent
-o initiali?e the diagonal o# a atri1 with all other eleents set to ?ero:
mat9#float)
mat;#float)
mat8#float)
-hat is, result6i76:7 is set to the #loat arguent #or all i = : and set to * #or all i :.
64
5 Operators and ()pressions
-o initiali?e a atri1 9) s.eci#)ing vectors or scalars, the co.onents are assigned to the atri1 eleents
in colun8aDor order.
mat9#ve%91 ve%9), -- one %olumn per argument
mat;#ve%;1 ve%;1 ve%;), -- one %olumn per argument
mat8#ve%81 ve%81 ve%81 ve%8), -- one %olumn per argument
mat;x9#ve%91 ve%91 ve%9), -- one %olumn per argument
dmat9#dve%91 dve%9),
dmat;#dve%;1 dve%;1 dve%;),
dmat8#dve%81 dve%81 dve%81 dve%8),
mat9#float1 float1 -- first %olumn
float1 float), -- se%ond %olumn
mat;#float1 float1 float1 -- first %olumn
float1 float1 float1 -- se%ond %olumn
float1 float1 float), -- t.ird %olumn
mat8#float1 float1 float1 float1 -- first %olumn
float1 float1 float1 float1 -- se%ond %olumn
float1 float1 float1 float1 -- t.ird %olumn
float1 float1 float1 float), -- fourt. %olumn
mat9x;#ve%91 float1 -- first %olumn
ve%91 float), -- se%ond %olumn
dmat9x8#dve%;1 dou$le1 -- first %olumn
dou$le1 dve%;) -- se%ond %olumn
A wide range o# other .ossi9ilities e1ist, to construct a atri1 #ro vectors and scalars, as long as enough
co.onents are .resent to initiali?e the atri1. -o construct a atri1 #ro a atri1:
mat;x;#mat8x8), -- ta:es t.e upper2left ;x; of t.e mat8x8
mat9x;#mat8x9), -- ta:es t.e upper2left 9x9 of t.e mat8x81 last ro/ is =1=
mat8x8#mat;x;), -- puts t.e mat;x; in t.e upper2left1 sets t.e lo/er rig.t
-- %omponent to '1 and t.e rest to =
5..! Structure Constructors
+nce a structure is de#ined, and its t).e is given a nae, a constructor is availa9le with the sae nae to
construct instances o# that structure. 3or e1a.le:
stru%t lig.t )
float intensit&,
ve%; position,
3,
lig.t lig.tVar * lig.t#;+=1 ve%;#'+=1 9+=1 ;+=)),
65
5 Operators and ()pressions
-he arguents to the constructor will 9e used to set the structureGs #ields, in order, using one arguent .er
#ield. Each arguent ust 9e the sae t).e as the #ield it sets, or 9e a t).e that can 9e converted to the
#ieldGs t).e according to section %.1.1* BI.licit "onversions.C
(tructure constructors can 9e used as initiali?ers or in e1.ressions.
5.. .rra# Constructors
Arra) t).es can also 9e used as constructor naes, which can then 9e used in e1.ressions or initiali?ers.
3or e1a.le,
%onst float %B;C * floatB;C#<+=1 F+91 '+'),
%onst float dB;C * floatBC#<+=1 F+91 '+'),
float g,
+++
float aB<C * floatB<C#g1 '1 g1 9+;1 g),
float $B;C,
$ * floatB;C#g1 g L '+=1 g L 9+=),
-here ust 9e e1actl) the sae nu9er o# arguents as the si?e o# the arra) 9eing constructed. I# no si?e
is .resent in the constructor, then the arra) is e1.licitl) si?ed to the nu9er o# arguents .rovided. -he
arguents are assigned in order, starting at eleent *, to the eleents o# the constructed arra). Each
arguent ust 9e the sae t).e as the eleent t).e o# the arra), or 9e a t).e that can 9e converted to the
eleent t).e o# the arra) according to section %.1.1* BI.licit "onversions.C
5.5 $ector Components
-he naes o# the co.onents o# a vector are denoted 9) a single letter. As a notational convenience,
several letters are associated with each co.onent 9ased on coon usage o# .osition, color or te1ture
coordinate vectors. -he individual co.onents o# a vector can 9e selected 9) #ollowing the varia9le
nae with .eriod E . F and then the co.onent nae.
-he co.onent naes su..orted are:
>*) ,) 1) w? 6se#ul when accessing vectors that re.resent .oints or norals
>r) g) +) a? 6se#ul when accessing vectors that re.resent colors
>s) t) %) 2? 6se#ul when accessing vectors that re.resent te1ture coordinates
-he co.onent naes *) r) and s are, #or e1a.le, s)non)s #or the sae E#irstF co.onent in a vector.
7ote that the third co.onent o# the te1ture coordinate set, r in +.en/0, has 9een renaed % so as to
avoid the con#usion with r E#or redF in a color.
Accessing co.onents 9e)ond those declared #or the vector t).e is an error so, #or e1a.le:
66
5 Operators and ()pressions
ve%9 pos,
pos+x -- is legal
pos+" -- is illegal
-he co.onent selection s)nta1 allows ulti.le co.onents to 9e selected 9) a..ending their naes
E#ro the sae nae setF a#ter the .eriod E . F.
ve%8 v8,
v8+rg$a, -- is a ve%8 and t.e same as 7ust using v81
v8+rg$, -- is a ve%;1
v8+$, -- is a float1
v8+x&, -- is a ve%91
v8+xg$a, -- is illegal 2 t.e %omponent names do not %ome from
-- t.e same set+
-he order o# the co.onents can 9e di##erent to swi??le the, or re.licated:
ve%8 pos * ve%8#'+=1 9+=1 ;+=1 8+=),
ve%8 s/i"* pos+/"&x, -- s/i" * #8+=1 ;+=1 9+=1 '+=)
ve%8 dup * pos+xx&&, -- dup * #'+=1 '+=1 9+=1 9+=)
-his notation is ore concise than the constructor s)nta1. -o #or an r8value, it can 9e a..lied to an)
e1.ression that results in a vector r8value.
-he co.onent grou. notation can occur on the le#t hand side o# an e1.ression.
ve%8 pos * ve%8#'+=1 9+=1 ;+=1 8+=),
pos+x/ * ve%9#<+=1 G+=), -- pos * #<+=1 9+=1 ;+=1 G+=)
pos+/x * ve%9#F+=1 O+=), -- pos * #O+=1 9+=1 ;+=1 F+=)
pos+xx * ve%9#;+=1 8+=), -- illegal 2 DxD used t/i%e
pos+x& * ve%;#'+=1 9+=1 ;+=), -- illegal 2 mismat%. $et/een ve%9 and ve%;
-o #or an l8value, swi??ling ust 9e a..lied to an l8value o# vector t).e, contain no du.licate
co.onents, and it results in an l8value o# scalar or vector t).e, de.ending on nu9er o# co.onents
s.eci#ied.
Arra) su9scri.ting s)nta1 can also 9e a..lied to vectors to .rovide nueric inde1ing. (o in
ve%8 pos,
%os627 re#ers to the third eleent o# .os and is e=uivalent to %os.1. -his allows varia9le inde1ing into a
vector, as well as a generic wa) o# accessing co.onents. An) integer e1.ression can 9e used as the
su9scri.t. -he #irst co.onent is at inde1 ?ero. Reading #ro or writing to a vector using a constant
integral e1.ression with a value that is negative or greater than or e=ual to the si?e o# the vector is illegal.
@hen inde1ing with non8constant e1.ressions, 9ehavior is unde#ined i# the inde1 is negative, or greater
than or e=ual to the si?e o# the vector.
67
5 Operators and ()pressions
5." 7atri* Components
-he co.onents o# a atri1 can 9e accessed using arra) su9scri.ting s)nta1. A..l)ing a single su9scri.t
to a atri1 treats the atri1 as an arra) o# colun vectors, and selects a single colun, whose t).e is a
vector o# the sae si?e as the atri1. -he le#tost colun is colun *. A second su9scri.t would then
o.erate on the resulting vector, as de#ined earlier #or vectors. ,ence, two su9scri.ts select a colun and
then a row.
mat8 m,
mB'C * ve%8#9+=), -- sets t.e se%ond %olumn to all 9+=
mB=CB=C * '+=, -- sets t.e upper left element to '+=
mB9CB;C * 9+=, -- sets t.e 8t. element of t.e t.ird %olumn to 9+=
Behavior is unde#ined when accessing a co.onent outside the 9ounds o# a atri1 with a non8constant
e1.ression. It is an error to access a atri1 with a constant e1.ression that is outside the 9ounds o# the
atri1.
5.2 Structure and .rra# Operations
-he #ields o# a structure and the length ethod o# an arra) are selected using the .eriod E . F.
In total, onl) the #ollowing o.erators are allowed to o.erate on arra)s and structures as whole entities:
#ield or ethod selector .
e=ualit) 77 87
assignent 7
inde1ing Earra)s onl)F Y Z
-he e=ualit) o.erators and assignent o.erator are onl) allowed i# the two o.erands are sae si?e and
t).e. (tructure t).es ust 9e o# the sae declared structure. Both arra) o.erands ust 9e e1.licitl)
si?ed. @hen using the e=ualit) o.erators, two structures are e=ual i# and onl) i# all the #ields are
co.onent8wise e=ual, and two arra)s are e=ual i# and onl) i# all the eleents are eleent8wise e=ual.
Arra) eleents are accessed using the arra) su9scri.t o.erator E - . F. An e1a.le o# accessing an arra)
eleent is
diffuseEolor L* lig.tIntensit&B;C K NdotL,
Arra) indices start at ?ero. Arra) eleents are accessed using an e1.ression whose t).e is int or uint.
Behavior is unde#ined i# a shader su9scri.ts an arra) with an inde1 less than * or greater than or e=ual to
the si?e the arra) was declared with.
6
5 Operators and ()pressions
Arra)s can also 9e accessed with the ethod o.erator E . F and the length ethod to =uer) the si?e o# the
arra):
lig.tIntensit&+lengt.#) -- return t.e si"e of t.e arra&
5.3 .ssignments
Assignents o# values to varia9le naes are done with the assignent o.erator E 7 F:
lvalue2expression * rvalue2expression
-he lvalue-e*%ression evaluates to an l8value. -he assignent o.erator stores the value o# rvalue-
e*%ression into the l8value and returns an r8value with the t).e and .recision o# lvalue-e*%ression. -he
lvalue-e*%ression and rvalue-e*%ression ust have the sae t).e, or the e1.ression ust have a t).e in
the ta9le in section %.1.1* BI.licit "onversionsC that converts to the t).e o# lvalue-e*%ression, in which
case an i.licit conversion will 9e done on the rvalue-e*%ression 9e#ore the assignent is done. An)
other desired t).e8conversions ust 9e s.eci#ied e1.licitl) via a constructor. 08values ust 9e writa9le.
Varia9les that are 9uilt8in t).es, entire structures or arra)s, structure #ields, l8values with the #ield selector
E . F a..lied to select co.onents or swi??les without re.eated #ields, l8values within .arentheses, and l8
values dere#erenced with the arra) su9scri.t o.erator E - . F are all l8values. +ther 9inar) or unar)
e1.ressions, #unction naes, swi??les with re.eated #ields, and constants cannot 9e l8values. -he ternar)
o.erator E;9F is also not allowed as an l8value.
E1.ressions on the le#t o# an assignent are evaluated 9e#ore e1.ressions on the right o# the assignent.
-he other assignent o.erators are
add into E'7F
su9tract #ro E!7F
ulti.l) into E)7F
divide into E(7F
odulus into E*7F
le#t shi#t 9) E++7F
right shi#t 9) E,,7F
and into E57F
inclusive8or into E47F
e1clusive8or into E37F
6!
5 Operators and ()pressions
where the general e1.ression
lvalue op* expression
is e=uivalent to
lvalue * lvalue op expression
where o% is as descri9ed 9elow, and the l8value and e1.ression ust satis#) the seantic re=uireents o#
9oth o% and e=uals E7F.
Reading a varia9le 9e#ore writing Eor initiali?ingF it is legal, however the value is unde#ined.
5.8 '*pressions
E1.ressions in the shading language are 9uilt #ro the #ollowing:
"onstants o# t).e bool$ all integer t).es, all #loating8.oint t).es, all vector t).es, and all atri1 t).es.
"onstructors o# all t).es.
Varia9le naes o# all t).es.
An arra) nae with the length ethod a..lied.
(u9scri.ted arra) naes.
3unction calls that return values.
"o.onent #ield selectors and arra) su9scri.t results.
2arenthesi?ed e1.ression. An) e1.ression can 9e .arenthesi?ed. 2arentheses can 9e used to grou.
o.erations. +.erations within .arentheses are done 9e#ore o.erations across .arentheses.
-he arithetic 9inar) o.erators add E'F, su9tract E!F, ulti.l) E)F, and divide E(F o.erate on integer and
#loating8.oint scalars, vectors, and atrices. I# the #undaental t).es in the o.erands do not atch,
then the conversions #ro section %.1.1* BI.licit "onversionsC are a..lied to create atching t).es.
All arithetic 9inar) o.erators result in the sae #undaental t).e Esigned integer, unsigned integer,
single8.recision #loating .oint, or dou9le8.recision #loating .ointF as the o.erands the) o.erate on,
a#ter o.erand t).e conversion. A#ter conversion, the #ollowing cases are valid
-he two o.erands are scalars. In this case the o.eration is a..lied, resulting in a scalar.
+ne o.erand is a scalar, and the other is a vector or atri1. In this case, the scalar o.eration is
a..lied inde.endentl) to each co.onent o# the vector or atri1, resulting in the sae si?e vector
or atri1.
-he two o.erands are vectors o# the sae si?e. In this case, the o.eration is done co.onent8wise
resulting in the sae si?e vector.
-he o.erator is add E'F, su9tract E!F, or divide E(F, and the o.erands are atrices with the sae
nu9er o# rows and the sae nu9er o# coluns. In this case, the o.eration is done co.onent8
wise resulting in the sae si?e atri1.
7"
5 Operators and ()pressions
-he o.erator is ulti.l) E)F, where 9oth o.erands are atrices or one o.erand is a vector and the
other a atri1. A right vector o.erand is treated as a colun vector and a le#t vector o.erand as a
row vector. In all these cases, it is re=uired that the nu9er o# coluns o# the le#t o.erand is e=ual
to the nu9er o# rows o# the right o.erand. -hen, the ulti.l) E)F o.eration does a linear
alge9raic ulti.l), )ielding an o9Dect that has the sae nu9er o# rows as the le#t o.erand and the
sae nu9er o# coluns as the right o.erand. (ection $.1* BVector and :atri1 +.erationsC
e1.lains in ore detail how vectors and atrices are o.erated on.
All other cases are illegal.
Dividing 9) ?ero does not cause an e1ce.tion 9ut does result in an uns.eci#ied value. 6se the 9uilt8in
#unctions dot, cross, matrixCompHult, and outerQroduct, to get, res.ectivel), vector dot .roduct,
vector cross .roduct, atri1 co.onent8wise ulti.lication, and the atri1 .roduct o# a colun
vector ties a row vector.
-he o.erator odulus E*F o.erates on signed or unsigned integer scalars or integer vectors. I# the
#undaental t).es in the o.erands do not atch, then the conversions #ro section %.1.1* BI.licit
"onversionsC are a..lied to create atching t).es. -he o.erands cannot 9e vectors o# di##ering si?e.
I# one o.erand is a scalar and the other vector, then the scalar is a..lied co.onent8wise to the vector,
resulting in the sae t).e as the vector. I# 9oth are vectors o# the sae si?e, the result is co.uted
co.onent8wise. -he resulting value is unde#ined #or an) co.onent co.uted with a second
o.erand that is ?ero, while results #or other co.onents with non8?ero second o.erands reain
de#ined. I# 9oth o.erands are non8negative, then the reainder is non8negative. Results are unde#ined
i# one or 9oth o.erands are negative. -he o.erator odulus E*F is not de#ined #or an) other data
t).es Enon8integer t).esF.
-he arithetic unar) o.erators negate E8F, .ost8 and .re8increent and decreent E!! and ''F o.erate
on integer or #loating8.oint values Eincluding vectors and atricesF. All unar) o.erators work
co.onent8wise on their o.erands. -hese result with the sae t).e the) o.erated on. 3or .ost8 and
.re8increent and decreent, the e1.ression ust 9e one that could 9e assigned to Ean l8valueF. 2re8
increent and .re8decreent add or su9tract 1 or 1.* to the contents o# the e1.ression the) o.erate on,
and the value o# the .re8increent or .re8decreent e1.ression is the resulting value o# that
odi#ication. 2ost8increent and .ost8decreent e1.ressions add or su9tract 1 or 1.* to the contents
o# the e1.ression the) o.erate on, 9ut the resulting e1.ression has the e1.ressionHs value 9e#ore the
.ost8increent or .ost8decreent was e1ecuted.
-he relational o.erators greater than E,F, less than E+F, greater than or e=ual E,7F, and less than or
e=ual E+7F o.erate onl) on scalar integer and scalar #loating8.oint e1.ressions. -he result is scalar
Boolean. Either the o.erandsH t).es ust atch, or the conversions #ro section %.1.1* BI.licit
"onversionsC will 9e a..lied to o9tain atching t).es. -o do co.onent8wise relational co.arisons
on vectors, use the 9uilt8in #unctions less>han$ less>hanJual$ greater>han$ and
greater>hanJual.
-he e=ualit) o.erators eual E77F, and not e=ual E87F o.erate on all t).es. -he) result in a scalar
Boolean. I# the o.erand t).es do not atch, then there ust 9e a conversion #ro section %.1.1*
BI.licit "onversionsC a..lied to one o.erand that can ake the atch, in which case this
conversion is done. 3or vectors, atrices, structures, and arra)s, all co.onents, #ields, or eleents o#
one o.erand ust e=ual the corres.onding co.onents, #ields, or eleents in the other o.erand #or the
o.erands to 9e considered e=ual. -o get a vector o# co.onent8wise e=ualit) results #or vectors, use
the 9uilt8in #unctions eual and notJual.
71
5 Operators and ()pressions
-he logical 9inar) o.erators and E55F, or E 4 4 F, and e1clusive or E33F o.erate onl) on two Boolean
e1.ressions and result in a Boolean e1.ression. And E55F will onl) evaluate the right hand o.erand
i# the le#t hand o.erand evaluated to true. +r E 4 4 F will onl) evaluate the right hand o.erand i# the le#t
hand o.erand evaluated to false. E1clusive or E33F will alwa)s evaluate 9oth o.erands.
-he logical unar) o.erator not E8F. It o.erates onl) on a Boolean e1.ression and results in a Boolean
e1.ression. -o o.erate on a vector, use the 9uilt8in #unction not.
-he se=uence E $ F o.erator that o.erates on e1.ressions 9) returning the t).e and value o# the right8
ost e1.ression in a coa se.arated list o# e1.ressions. All e1.ressions are evaluated, in order,
#ro le#t to right.
-he ternar) selection o.erator E;9F. It o.erates on three e1.ressions Ee*%1 ; e*%2 9 e*%@F. -his
o.erator evaluates the #irst e1.ression, which ust result in a scalar Boolean. I# the result is true, it
selects to evaluate the second e1.ression, otherwise it selects to evaluate the third e1.ression. +nl)
one o# the second and third e1.ressions is evaluated. -he second and third e1.ressions can 9e an)
t).e, as long their t).es atch, or there is a conversion in section %.1.1* BI.licit "onversionsC that
can 9e a..lied to one o# the e1.ressions to ake their t).es atch. -his resulting atching t).e is the
t).e o# the entire e1.ression.
-he oneGs co.leent o.erator E6F. -he o.erand ust 9e o# t).e signed or unsigned integer or integer
vector, and the result is the oneGs co.leent o# its o.erandI each 9it o# each co.onent is
co.leented, including an) sign 9its.
-he shi#t o.erators E++F and E,,F. 3or 9oth o.erators, the o.erands ust 9e signed or unsigned
integers or integer vectors. +ne o.erand can 9e signed while the other is unsigned. In all cases, the
resulting t).e will 9e the sae t).e as the le#t o.erand. I# the #irst o.erand is a scalar, the second
o.erand has to 9e a scalar as well. I# the #irst o.erand is a vector, the second o.erand ust 9e a scalar
or a vector, and the result is co.uted co.onent8wise. -he result is unde#ined i# the right o.erand is
negative, or greater than or e=ual to the nu9er o# 9its in the le#t e1.ressionGs 9ase t).e. -he value o#
E1 PP E! is E1 Einter.reted as a 9it .atternF le#t8shi#ted 9) E! 9its. -he value o# E1 QQ E! is E1 right8
shi#ted 9) E! 9it .ositions. I# E1 is a signed integer, the right8shi#t will e1tend the sign 9it. I# E1 is an
unsigned integer, the right8shi#t will ?ero8e1tend.
-he 9itwise o.erators and E5F, e1clusive8or E3F, and inclusive8or E4F. -he o.erands ust 9e o# t).e
signed or unsigned integers or integer vectors. -he o.erands cannot 9e vectors o# di##ering si?e. I# one
o.erand is a scalar and the other a vector, the scalar is a..lied co.onent8wise to the vector, resulting
in the sae t).e as the vector. -he #undaental t).es o# the o.erands Esigned or unsignedF ust
atch, and will 9e the resulting #undaental t).e. 3or and E5F, the result is the 9itwise8and #unction
o# the o.erands. 3or e1clusive8or E3F, the result is the 9itwise e1clusive8or #unction o# the o.erands.
3or inclusive8or E4F, the result is the 9itwise inclusive8or #unction o# the o.erands.
3or a co.lete s.eci#ication o# the s)nta1 o# e1.ressions, see section ; B(hading 0anguage /raar.C
72
5 Operators and ()pressions
5.1% $ector and 7atri* Operations
@ith a #ew e1ce.tions, o.erations are co.onent8wise. 6suall), when an o.erator o.erates on a vector or
atri1, it is o.erating inde.endentl) on each co.onent o# the vector or atri1, in a co.onent8wise
#ashion. 3or e1a.le,
ve%; v1 u,
float f,
v * u L f,
will 9e e=uivalent to
v+x * u+x L f,
v+& * u+& L f,
v+" * u+" L f,
And
ve%; v1 u1 /,
/ * v L u,
will 9e e=uivalent to
/+x * v+x L u+x,
/+& * v+& L u+&,
/+" * v+" L u+",
and likewise #or ost o.erators and all integer and #loating .oint vector and atri1 t).es. -he e1ce.tions
are atri1 ulti.lied 9) vector, vector ulti.lied 9) atri1, and atri1 ulti.lied 9) atri1. -hese do
not o.erate co.onent8wise, 9ut rather .er#or the correct linear alge9raic ulti.l).
ve%; v1 u,
mat; m,
u * v K m,
is e=uivalent to
u+x * dot#v1 mB=C), -- mB=C is t.e left %olumn of m
u+& * dot#v1 mB'C), -- dot#a1$) is t.e inner #dot) produ%t of a and $
u+" * dot#v1 mB9C),
And
u * m K v,
is e=uivalent to
u+x * mB=C+x K v+x L mB'C+x K v+& L mB9C+x K v+",
u+& * mB=C+& K v+x L mB'C+& K v+& L mB9C+& K v+",
u+" * mB=C+" K v+x L mB'C+" K v+& L mB9C+" K v+",
73
5 Operators and ()pressions
And
mat; m1 n1 r,
r * m K n,
is e=uivalent to
rB=C+x * mB=C+x K nB=C+x L mB'C+x K nB=C+& L mB9C+x K nB=C+",
rB'C+x * mB=C+x K nB'C+x L mB'C+x K nB'C+& L mB9C+x K nB'C+",
rB9C+x * mB=C+x K nB9C+x L mB'C+x K nB9C+& L mB9C+x K nB9C+",
rB=C+& * mB=C+& K nB=C+x L mB'C+& K nB=C+& L mB9C+& K nB=C+",
rB'C+& * mB=C+& K nB'C+x L mB'C+& K nB'C+& L mB9C+& K nB'C+",
rB9C+& * mB=C+& K nB9C+x L mB'C+& K nB9C+& L mB9C+& K nB9C+",
rB=C+" * mB=C+" K nB=C+x L mB'C+" K nB=C+& L mB9C+" K nB=C+",
rB'C+" * mB=C+" K nB'C+x L mB'C+" K nB'C+& L mB9C+" K nB'C+",
rB9C+" * mB=C+" K nB9C+x L mB'C+" K nB9C+& L mB9C+" K nB9C+",
and siilarl) #or other si?es o# vectors and atrices.
74
" Statements and Structure
-he #undaental 9uilding 9locks o# the +.en/0 (hading 0anguage are:
stateents and declarations
#unction de#initions
selection Eif!else and switch!case!defaultF
iteration Efor$ while$ and do!whileF
Du.s Ediscard$ return$ break$ and continueF
-he overall structure o# a shader is as #ollows
translation-unit:
glo+al-(eclaration
translation-unit glo+al-(eclaration
glo+al-(eclaration:
function-(efinition
(eclaration
-hat is, a shader is a se=uence o# declarations and #unction 9odies. 3unction 9odies are de#ined as
function-(efinition:
function-%rotot,%e > statement-list ?
statement-list:
statement
statement-list statement
statement:
com%oun(-statement
sim%le-statement
"url) 9races are used to grou. se=uences o# stateents into co.ound stateents.
com%oun(-statement:
> statement-list ?
sim%le-statement:
(eclaration-statement
e*%ression-statement
selection-statement
75
6 State*ents and Structure
iteration-statement
:um%-statement
(i.le declaration, e1.ression, and Du. stateents end in a sei8colon.
-his a9ove is slightl) si.li#ied, and the co.lete graar s.eci#ied in section ; B(hading 0anguage
/raarC should 9e used as the de#initive s.eci#ication.
Declarations and e1.ressions have alread) 9een discussed.
".1 ,unction )efinitions
As indicated 9) the graar a9ove, a valid shader is a se=uence o# glo9al declarations and #unction
de#initions. A #unction is declared as the #ollowing e1a.le shows:
-- protot&pe
returnT&pe fun%tionName #t&pe= arg=1 t&pe' arg'1 +++1 t&pen argn),
and a #unction is de#ined like
-- definition
returnT&pe fun%tionName #t&pe= arg=1 t&pe' arg'1 +++1 t&pen argn)
)
-- do some %omputation
return returnValue,
3
where return#,%e ust 9e .resent and include a t).e. Each o# the t,%e. ust include a t).e and can
o.tionall) include a .araeter =uali#ier andNor const. -he #oral arguent naes Eargs a9oveF in the
declarations are o.tional #or 9oth the declaration and de#inition #ors.
A #unction is called 9) using its nae #ollowed 9) a list o# arguents in .arentheses.
Arra)s are allowed as arguents and as the return t).e. In 9oth cases, the arra) ust 9e e1.licitl) si?ed.
An arra) is .assed or returned 9) using Dust its nae, without 9rackets, and the si?e o# the arra) ust
atch the si?e s.eci#ied in the #unctionGs declaration.
(tructures are also allowed as arguent t).es. -he return t).e can also 9e structure.
(ee section ; B(hading 0anguage /raarC #or the de#initive re#erence on the s)nta1 to declare and
de#ine #unctions.
All #unctions ust 9e either declared with a .rotot).e or de#ined with a 9od) 9e#ore the) are called. 3or
e1a.le:
float m&fun% #float f1 -- f is an input parameter
out float g), -- g is an output parameter
3unctions that return no value ust 9e declared as void. 3unctions that acce.t no in.ut arguents need
not use void in the arguent list 9ecause .rotot).es Eor de#initionsF are re=uired and there#ore there is no
a9iguit) when an e.t) arguent list VE FV is declared. -he idio BEvoidFC as a .araeter list is
.rovided #or convenience.
76
6 State*ents and Structure
3unction naes can 9e overloaded. -he sae #unction nae can 9e used #or ulti.le #unctions, as long
as the .araeter t).es di##er. I# a #unction nae is declared twice with the sae .araeter t).es, then the
return t).es and all =uali#iers ust also atch, and it is the sae #unction 9eing declared. 3or e1a.le,
ve%8 f#in ve%8 x1 out ve%8 &), -- #>)
ve%8 f#in ve%8 x1 out uve%8 &), -- #6) o:a&1 different argument t&pe
ve%8 f#in ive%8 x1 out uve%8 &), -- #E) o:a&1 different argument t&pe
int f#in ve%8 x1 out ive%8 &), -- error1 onl& return t&pe differs
ve%8 f#in ve%8 x1 in ve%8 &), -- error1 onl& Aualifier differs
ve%8 f#%onst in ve%8 x1 out ve%8 &), -- error1 onl& Aualifier differs
@hen #unction calls are resolved, an e1act t).e atch #or all the arguents is sought. I# an e1act atch is
#ound, all other #unctions are ignored, and the e1act atch is used. I# no e1act atch is #ound, then the
i.licit conversions in section %.1.1* BI.licit "onversionsC will 9e a..lied to #ind a atch.
:isatched t).es on in.ut .araeters Ein or inout or de#ault0 ust have a conversion #ro the calling
arguent t).e to the #oral .araeter t).e. :isatched t).es on out.ut .araeters Eout or inoutF ust
have a conversion #ro the #oral .araeter t).e to the calling arguent t).e.
I# i.licit conversions can 9e used to #ind ore than one atching #unction, a single 9est8atching
#unction is sought. -o deterine a 9est atch, the conversions 9etween calling arguent and #oral
.araeter t).es are co.ared #or each #unction arguent and .air o# atching #unctions. A#ter these
co.arisons are .er#ored, each .air o# atching #unctions are co.ared. A #unction declaration A is
considered a 9etter atch than #unction declaration ; i#
#or at least one #unction arguent, the conversion #or that arguent in A is 9etter than the
corres.onding conversion in ;I and
there is no #unction arguent #or which the conversion in ; is 9etter than the corres.onding
conversion in A.
I# a single #unction declaration is considered a 9etter atch than ever) other atching #unction
declaration, it will 9e used. +therwise, a seantic error #or an a9iguous overloaded #unction call occurs
and the shader will #ail to co.ile.
-o deterine whether the conversion #or a single arguent in one atch is 9etter than that #or another
atch, the #ollowing rules are a..lied, in order:
1. An e1act atch is 9etter than a atch involving an) i.licit conversion.
!. A atch involving an i.licit conversion #ro float to double is 9etter than a atch involving
an) other i.licit conversion.
&. A atch involving an i.licit conversion #ro either int or uint to float is 9etter than a atch
involving an i.licit conversion #ro either int or uint to double.
I# none o# the rules a9ove a..l) to a .articular .air o# conversions, neither conversion is considered 9etter
than the other.
3or the e1a.le #unction .rotot).es EAF, EBF, and E"F a9ove, the #ollowing e1a.les show how the rules
a..l) to di##erent sets o# calling arguent t).es:
77
6 State*ents and Structure
f#ve%81 ve%8), -- exa%t mat%. of ve%8 f#in ve%8 x1 out ve%8 &)
f#ve%81 uve%8), -- exa%t mat%. of ve%8 f#in ve%8 x1 out ive%8 &)
f#ve%81 ive%8), -- mat%.ed to ve%8 f#in ve%8 x1 out ve%8 &)
-- #E) not relevant1 %anDt %onvert ve%8 to
-- ive%8+ #>) $etter t.an #6) for 9nd
-- argument #rule 9)1 same on first argument+
f#ive%81 ve%8), -- NOT mat%.ed+ >ll t.ree mat%. $& impli%it
-- %onversion+ #E) is $etter t.an #>) and #6)
-- on t.e first argument+ #>) is $etter t.an
-- #6) and #E)+
6ser8de#ined #unctions can have ulti.le declarations, 9ut onl) one de#inition. A shader can rede#ine
9uilt8in #unctions. I# a 9uilt8in #unction is redeclared in a shader Ei.e., a .rotot).e is visi9leF 9e#ore a call
to it, then the linker will onl) atte.t to resolve that call within the set o# shaders that are linked with it.
-he #unction main is used as the entr) .oint to a shader e1ecuta9le. A shader need not contain a #unction
naed main, 9ut one shader in a set o# shaders linked together to #or a single shader e1ecuta9le ust.
-his #unction takes no arguents, returns no value, and ust 9e declared as t).e void9
void main#)
)
+++
3
-he #unction main can contain uses o# return. (ee section '.% BJu.sC #or ore details.
It is an error to declare or de#ine a #unction main with an) other .araeters or return t).e.
".1.1 ,unction Calling Conventions
3unctions are called 9) value8return. -his eans in.ut arguents are co.ied into the #unction at call tie,
and out.ut arguents are co.ied 9ack to the caller 9e#ore #unction e1it. Because the #unction works with
local co.ies o# .araeters, there are no issues regarding aliasing o# varia9les within a #unction. -o
control what .araeters are co.ied in andNor out through a #unction de#inition or declaration:
-he ke)word in is used as a =uali#ier to denote a .araeter is to 9e co.ied in, 9ut not co.ied out.
-he ke)word out is used as a =uali#ier to denote a .araeter is to 9e co.ied out, 9ut not co.ied in.
-his should 9e used whenever .ossi9le to avoid unnecessaril) co.)ing .araeters in.
-he ke)word inout is used as a =uali#ier to denote the .araeter is to 9e 9oth co.ied in and co.ied
out.
A #unction .araeter declared with no such =uali#ier eans the sae thing as s.eci#)ing in.
All arguents are evaluated at call tie, e1actl) once, in order, #ro le#t to right. Evaluation o# an in
.araeter results in a value that is co.ied to the #oral .araeter. Evaluation o# an out .araeter results
in an l8value that is used to co.) out a value when the #unction returns. Evaluation o# an inout .araeter
results in 9oth a value and an l8valueI the value is co.ied to the #oral .araeter at call tie and the l8
value is used to co.) out a value when the #unction returns.
-he order in which out.ut .araeters are co.ied 9ack to the caller is unde#ined.
7
6 State*ents and Structure
I# the #unction atching descri9ed in the .revious section re=uired arguent t).e conversions, these
conversions are a..lied at co.)8in and co.)8out ties.
In a #unction, writing to an in.ut8onl) .araeter is allowed. +nl) the #unctionHs co.) is odi#ied. -his
can 9e .revented 9) declaring a .araeter with the const =uali#ier.
@hen calling a #unction, e1.ressions that do not evaluate to l8values cannot 9e .assed to .araeters
declared as out or inout.
7o =uali#ier is allowed on the return t).e o# a #unction.
function-%rotot,%e :
%recision-2ualifier t,%e function-name4const-2ualifier %arameter-2ualifier %recision-2ualifier
t,%e name arra,-s%ecifier) ... 5
t,%e :
an) 9asic t).e, arra) t).e, structure nae, or structure (efinition
const-2ualifier :
e.t)
const
%arameter-2ualifier :
e.t)
in
out
inout
name :
e.t)
identi#ier
arra,-s%ecifier :
e.t)
- integral-constant-e*%ression .
,owever, the const =uali#ier cannot 9e used with out or inout. -he a9ove is used #or #unction
declarations Ei.e., .rotot).esF and #or #unction de#initions. ,ence, #unction de#initions can have unnaed
arguents.
Recursion is not allowed, not even staticall). (tatic recursion is .resent i# the static #unction8call gra.h o#
a .rogra contains c)cles. -his includes all .otential #unction calls through varia9les declared as
subroutine uniform Edescri9ed 9elowF.
7!
6 State*ents and Structure
".1.2 Subroutines
(u9routines .rovide a echanis allowing shaders to 9e co.iled in a anner where the target o# one or
ore #unction calls can 9e changed at run8tie without re=uiring an) shader reco.ilation. 3or e1a.le,
a single shader a) 9e co.iled with su..ort #or ulti.le illuination algoriths to handle di##erent
kinds o# lights or sur#ace aterials. An a..lication using such a shader a) switch illuination
algoriths 9) changing the value o# its su9routine uni#ors. -o use su9routines, a su9routine t).e is
declared, one or ore #unctions are associated with that su9routine t).e, and a su9routine varia9le o# that
t).e is declared. -he #unction currentl) assigned to the varia9le #unction is then called 9) using #unction
calling s)nta1 re.lacing a #unction nae with the nae o# the su9routine varia9le. (u9routine varia9les
are uni#ors, and are assigned to s.eci#ic #unctions onl) through coands ESniformSubroutinesuivF in
the +.en/0 A2I.
(u9routine t).es are declared using a stateent siilar to a #unction declaration, with the subroutine
ke)word, as #ollows:
su$routine returnT&pe su$routineT&peName#t&pe= arg=1 t&pe' arg'1
+++1 t&pen argn),
As with #unction declarations, the #oral arguent naes Eargs a9oveF are o.tional. 3unctions are
associated with su9routine t).es o# atching declarations 9) de#ining the #unction with the subroutine
ke)word and a list o# su9routine t).es the #unction atches:
su$routine#su$routineT&peName=1 +++1 su$routineT&peNameN)
returnT&pe fun%tionName#t&pe= arg=1 t&pe' arg'1 +++1 t&pen argn)
) +++ 3 -- fun%tion $od&
It is an error i# arguents and return t).e donGt atch 9etween the #unction and each associated su9routine
t).e.
3unctions declared with subroutine ust include a 9od). An overloaded #unction cannot 9e declared
with subroutineI a .rogra will #ail to co.ile or link i# an) shader or stage contains two or ore
#unctions with the sae nae i# the nae is associated with a su9routine t).e.
(u9routine t).e varia9les are re=uired to 9e su+routine uniforms, and are declared with a s.eci#ic
su9routine t).e in a su9routine uni#or varia9le declaration:
su$routine uniform su$routineT&peName su$routineVarName,
(u9routine uni#or varia9les are called the sae wa) #unctions are called. @hen a su9routine varia9le
Eor an eleent o# a su9routine varia9le arra)F is associated with a .articular #unction, all #unction calls
through that varia9le will call that .articular #unction.
6nlike other uni#or varia9les, su9routine uni#or varia9les are sco.ed to the shader e1ecution stage the
varia9le is declared in.
(u9routine varia9les a) 9e declared as e1.licitl)8si?ed arra)s, which can 9e d)naicall) inde1ed at use.
"
6 State*ents and Structure
".2 Selection
"onditional control #low in the shading language is done 9) either if, if8else, or switch stateents:
selection-statement :
if E +ool-e*%ression F statement
if E +ool-e*%ression F statement else statement
switch E init-e*%ression F \ switch-statement-listo%t

]
@here switch-statement-list is a list o# ?ero or ore switch-statement and other stateents de#ined 9) the
language, where switch-statement adds soe #ors o# la9els. -hat is
switch-statement-list :
switch-statement
switch-statement-list switch-statement
switch-statement :
case constant-e*%ression 9
default 9
statement
I# an if!e1.ression evaluates to true, then the #irst statement is e1ecuted. I# it evaluates to false and there
is an else .art then the second statement is e1ecuted.
An) e1.ression whose t).e evaluates to a Boolean can 9e used as the conditional e1.ression +ool-
e*%ression. Vector t).es are not acce.ted as the e1.ression to if.
"onditionals can 9e nested.
-he t).e o# init-e*%ression in a switch stateent ust 9e a scalar integer. I# a case la9el has a constant-
e*%ression o# e=ual value, then e1ecution will continue a#ter that la9el. +therwise, i# there is a default
la9el, e1ecution will continue a#ter that la9el. +therwise, e1ecution ski.s the rest o# the switch stateent.
It is an error to have ore than one default or a re.licated constant-e*%ression. A break stateent not
nested in a loo. or other switch stateent Eeither not nested or nested onl) in if or if8else stateentsF will
also ski. the rest o# the switch stateent. 3all through la9els are allowed, 9ut it is an error to have no
stateent 9etween a la9el and the end o# the switch stateent. 7o stateents are allowed in a switch
stateent 9e#ore the #irst case stateent.
7o case or default la9els can 9e nested inside other #low control nested within their corres.onding
switch.
1
6 State*ents and Structure
".! Iteration
3or, while, and do loo.s are allowed as #ollows:
for #init2expression, %ondition2expression, loop2expression)
su$2statement
/.ile #%ondition2expression)
su$2statement
do
statement
/.ile #%ondition2expression)
(ee section ; B(hading 0anguage /raarC #or the de#initive s.eci#ication o# loo.s.
-he for loo. #irst evaluates the init-e*%ression, then the con(ition-e*%ression. I# the con(ition-
e*%ression evaluates to true, then the 9od) o# the loo. is e1ecuted. A#ter the 9od) is e1ecuted, a for loo.
will then evaluate the loo%-e*%ression, and then loo. 9ack to evaluate the con(ition-e*%ression, re.eating
until the con(ition-e*%ression evaluates to #alse. -he loo. is then e1ited, ski..ing its 9od) and ski..ing
its loo%-e*%ression. Varia9les odi#ied 9) the loo%-e*%ression aintain their value a#ter the loo. is
e1ited, .rovided the) are still in sco.e. Varia9les declared in init-e*%ression or con(ition-e*%ression are
onl) in sco.e until the end o# the su98stateent o# the for loo..
-he while loo. #irst evaluates the con(ition-e*%ression. I# true, then the 9od) is e1ecuted. -his is then
re.eated, until the con(ition-e*%ression evaluates to #alse, e1iting the loo. and ski..ing its 9od).
Varia9les declared in the con(ition-e*%ression are onl) in sco.e until the end o# the su98stateent o# the
while loo..
-he do!while loo. #irst e1ecutes the 9od), then e1ecutes the con(ition-e*%ression. -his is re.eated until
con(ition-e*%ression evaluates to #alse, and then the loo. is e1ited.
E1.ressions #or con(ition-e*%ression ust evaluate to a Boolean.
Both the con(ition-e*%ression and the init-e*%ression can declare and initiali?e a varia9le, e1ce.t in the
do!while loo., which cannot declare a varia9le in its con(ition-e*%ression. -he varia9leHs sco.e lasts
onl) until the end o# the su98stateent that #ors the 9od) o# the loo..
0oo.s can 9e nested.
7on8terinating loo.s are allowed. -he conse=uences o# ver) long or non8terinating loo.s are .lat#or
de.endent.
2
6 State*ents and Structure
". ;umps
-hese are the Du.s:
:um%statement:
continue:
break:
return:
return e*%ression:
discard: (( in the #ragent shader language onl)
-here is no BgotoC nor other non8structured #low o# control.
-he continue Du. is used onl) in loo.s. It ski.s the reainder o# the 9od) o# the inner ost loo. o#
which it is inside. 3or while and do!while loo.s, this Du. is to the ne1t evaluation o# the loo.
con(ition-e*%ression #ro which the loo. continues as .reviousl) de#ined. 3or for loo.s, the Du. is to
the loo%-e*%ression, #ollowed 9) the con(ition-e*%ression.
-he break Du. can also 9e used onl) in loo.s and switch stateents. It is si.l) an iediate e1it o#
the inner8ost loo. or switch stateents containing the break. 7o #urther e1ecution o# con(ition-
e*%ression) loo%-e*%ression, or switch-statement is done.
-he discard ke)word is onl) allowed within #ragent shaders. It can 9e used within a #ragent shader to
a9andon the o.eration on the current #ragent. -his ke)word causes the #ragent to 9e discarded and no
u.dates to an) 9u##ers will occur. "ontrol #low e1its the shader, and su9se=uent i.licit or e1.licit
derivatives are unde#ined when this e1it is non8uni#or. It would t).icall) 9e used within a conditional
stateent, #or e1a.le:
if #intensit& 0 =+=)
dis%ard,
A #ragent shader a) test a #ragentHs al.ha value and discard the #ragent 9ased on that test.
,owever, it should 9e noted that coverage testing occurs a#ter the #ragent shader runs, and the coverage
test can change the al.ha value.
-he return Du. causes iediate e1it o# the current #unction. I# it has e*%ression then that is the return
value #or the #unction.
-he #unction main can use return. -his si.l) causes main to e1it in the sae wa) as when the end o#
the #unction had 9een reached. It does not i.l) a use o# discard in a #ragent shader. 6sing return in
ain 9e#ore de#ining out.uts will have the sae 9ehavior as reaching the end o# ain 9e#ore de#ining
out.uts.
3
2 -uilt6in $ariables
2.1 -uilt6In Language $ariables
(oe +.en/0 o.erations occur in #i1ed #unctionalit) and need to .rovide values to or receive values
#ro shader e1ecuta9les. (haders counicate with #i1ed8#unction +.en/0 .i.eline stages, and
o.tionall) with other shader e1ecuta9les, through the use o# 9uilt8in in.ut and out.ut varia9les.
In the verte1 language, the 9uilt8ins are intrinsicall) declared as:
in int gl_VertexI,
in int gl_Instan%eI,
out gl_@erVertex )
ve%8 gl_@osition,
float gl_@ointSi"e,
float gl_Elipistan%eBC,
3,
4
7 Bui%t+in #aria$%es
In the geoetr) language, the 9uilt8in varia9les are intrinsicall) declared as:
in gl_@erVertex )
ve%8 gl_@osition,
float gl_@ointSi"e,
float gl_Elipistan%eBC,
3 gl_inBC,
in int gl_@rimitiveIIn,
in int gl_Invo%ationI,
out gl_@erVertex )
ve%8 gl_@osition,
float gl_@ointSi"e,
float gl_Elipistan%eBC,
3,
out int gl_@rimitiveI,
out int gl_La&er,
out int gl_Vie/portIndex,
In the tessellation control language, 9uilt8in varia9les are intrinsicall) declared as:
in gl_@erVertex )
ve%8 gl_@osition,
float gl_@ointSi"e,
float gl_Elipistan%eBC,
3 gl_inBgl_?ax@at%.Verti%esC,
in int gl_@at%.Verti%esIn,
in int gl_@rimitiveI,
in int gl_Invo%ationI,
out gl_@erVertex )
ve%8 gl_@osition,
float gl_@ointSi"e,
float gl_Elipistan%eBC,
3 gl_outBC,
pat%. out float gl_TessLevelOuterB8C,
pat%. out float gl_TessLevelInnerB9C,
In the tessellation evaluation language, 9uilt8in varia9les are intrinsicall) declared as:
in gl_@erVertex )
ve%8 gl_@osition,
float gl_@ointSi"e,
float gl_Elipistan%eBC,
3 gl_inBgl_?ax@at%.Verti%esC,
in int gl_@at%.Verti%esIn,
5
7 Bui%t+in #aria$%es
in int gl_@rimitiveI,
in ve%; gl_TessEoord,
pat%. in float gl_TessLevelOuterB8C,
pat%. in float gl_TessLevelInnerB9C,
out gl_@erVertex )
ve%8 gl_@osition,
float gl_@ointSi"e,
float gl_Elipistan%eBC,
3,
In the #ragent language, 9uilt8in varia9les are intrinsicall) declared as:
in ve%8 gl_FragEoord,
in $ool gl_FrontFa%ing,
in float gl_Elipistan%eBC,
in ve%9 gl_@ointEoord,
in int gl_@rimitiveI,
in int gl_SampleI,
in ve%9 gl_Sample@osition,
out ve%8 gl_FragEolor, -- depre%ated
out ve%8 gl_FragataBgl_?axra/6uffersC, -- depre%ated
out float gl_Fragept.,
out int gl_Sample?as:BC,
Each o# the a9ove varia9les is discussed 9elow.
-he varia9le glVerte*-D is a verte1 language in.ut varia9le that holds an integer inde1 #or the verte1, as
de#ined under B(hader In.utsC in section !.11.4 BVar)ing Varia9lesC in the +.en/0 /ra.hics ()ste
(.eci#ication. @hile the varia9le glVerte*-D is alwa)s .resent, its value is not alwa)s de#ined.
-he varia9le gl-nstance-D is a verte1 language in.ut varia9le that holds the integer inde1 o# the current
.riitive in an instanced draw call Esee B(hader In.utsC in section !.11.4 BVar)ing Varia9lesC in the
+.en/0 /ra.hics ()ste (.eci#icationF. I# the current .riitive does not coe #ro an instanced draw
call, the value o# gl-nstance-D is ?ero.
As an out.ut varia9le, gl!osition is intended #or writing the hoogeneous verte1 .osition. It can 9e
written at an) tie during shader e1ecution. -his value will 9e used 9) .riitive asse9l), cli..ing,
culling, and other #i1ed #unctionalit) o.erations, i# .resent, that o.erate on .riitives a#ter verte1
.rocessing has occurred. Its value is unde#ined a#ter the verte1 .rocessing stage i# the verte1 shader
e1ecuta9le does not write gl!osition, and it is unde#ined a#ter geoetr) .rocessing i# the geoetr)
e1ecuta9le calls JmitTertexEF without having written gl!osition since the last JmitTertexEF Eor hasnGt
written it at allF. As an in.ut varia9le, gl!osition reads the out.ut written in the .revious shader stage to
gl!osition.
As an out.ut varia9le, gl!oint'i1e is intended #or a shader to write the si?e o# the .oint to 9e rasteri?ed.
It is easured in .i1els. I# gl!oint'i1e is not written to, its value is unde#ined in su9se=uent .i.e stages.
As an in.ut varia9le, gl!oint'i1e reads the out.ut written in the .revious shader stage to gl!osition.
6
7 Bui%t+in #aria$%es
-he varia9le gl9li%Distance .rovides the #orward co.ati9le echanis #or controlling user cli..ing.
-he eleent gl9li%Distance6i7 s.eci#ies a cli. distance #or each .lane i. A distance o# * eans the
verte1 is on the .lane, a .ositive distance eans the verte1 is inside the cli. .lane, and a negative distance
eans the .oint is outside the cli. .lane. -he cli. distances will 9e linearl) inter.olated across the
.riitive and the .ortion o# the .riitive with inter.olated distances less than * will 9e cli..ed.
-he gl9li%Distance arra) is .redeclared as unsi?ed and ust 9e si?ed 9) the shader either redeclaring it
with a si?e or inde1ing it onl) with integral constant e1.ressions. -his needs to si?e the arra) to include
all the cli. .lanes that are ena9led via the +.en/0 A2II i# the si?e does not include all ena9led .lanes,
results are unde#ined. -he si?e can 9e at ost gl8a*9li%Distances. -he nu9er o# var)ing co.onents
Esee gl8a*Var,ing9om%onents5 consued 9) gl9li%Distance will atch the si?e o# the arra), no
atter how an) .lanes are ena9led. -he shader ust also set all values in gl9li%Distance that have
9een ena9led via the +.en/0 A2I, or results are unde#ined. Values written into gl9li%Distance #or
.lanes that are not ena9led have no e##ect.
As an out.ut varia9le, gl9li%Distance .rovides the .lace #or the shader to write these distances. As an
in.ut in all 9ut the #ragent language, it reads the values written in the .revious shader stage. In the
#ragent language, gl9li%Distance arra) contains linearl) inter.olated values #or the verte1 values
written 9) a shader to the gl9li%Distance verte1 out.ut varia9le. +nl) eleents in this arra) that have
cli..ing ena9led will have de#ined values.
-he out.ut varia9le gl!rimitive-D is availa9le onl) in the geoetr) language and .rovides a single
integer that serves as a .riitive identi#ier. -his is then availa9le to #ragent shaders as the #ragent
in.ut gl!rimitive-D, which will select the written .riitive ID #ro the .rovoking verte1 in the .riitive
9eing shaded. I# a #ragent shader using gl!rimitive-D is active and a geoetr) shader is also active,
the geoetr) shader ust write to gl!rimitive-D or the #ragent shader in.ut gl!rimitive-D is
unde#ined. (ee section !.1&.% B/eoetr) (hader E1ecution EnvironentC Eunder B/eoetr) (hader
+ut.utsCF and section &.;.! B(hader E1ecutionC Eunder B(hader In.utsCF o# the +.en/0 /ra.hics ()ste
(.eci#ication #or ore in#oration.
3or tessellation control and evaluation languages the in.ut varia9le gl!rimitive-D is #illed with the
nu9er o# .riitives .rocessed 9) the shader since the current set o# rendering .riitives was started.
3or the #ragent language, it is #illed with the value written to the gl!rimitive-D geoetr) shader out.ut
i# a geoetr) shader is .resent. +therwise, it is assigned in the sae anner as with tessellation control
and evaluation shaders.
-he geoetr) language in.ut varia9le gl!rimitive-D-n 9ehaves identicall) to the tessellation control and
evaluation language in.ut varia9le gl!rimitive-D.
-he in.ut varia9le gl-nvocation-D is availa9le onl) in the tessellation control and geoetr) languages.
In the tessellation control shader, it identi#ies the nu9er o# the out.ut .atch verte1 assigned to the
tessellation control shader invocation. In the geoetr) shader, it identi#ies the invocation nu9er
assigned to the geoetr) shader invocation. In 9oth cases, gl-nvocation-D is assigned integer values in
the range 60) .-17, where . is the nu9er o# out.ut .atch vertices or geoetr) shader invocations .er
.riitive.
7
7 Bui%t+in #aria$%es
-he out.ut varia9le glLa,er is availa9le onl) in the geoetr) language, and is used to select a s.eci#ic
la)er Eor #ace and la)er o# a cu9e a.F o# a ulti8la)er #rae9u##er attachent. -he actual la)er used will
coe #ro one o# the vertices in the .riitive 9eing shaded. @hich verte1 the la)er coes #ro is
unde#ined, so it is 9est to write the sae la)er value #or all vertices o# a .riitive. I# a shader staticall)
assigns a value to glLa,er, la)ered rendering ode is ena9led. (ee section !.1&.% B/eoetr) (hader
E1ecution EnvironentC Eunder B/eoetr) (hader +ut.utsCF and section %.%.4 B0a)ered 3rae9u##ersC
o# the +.en/0 /ra.hics ()ste (.eci#ication #or ore in#oration. I# a shader staticall) assigns a value
to glLa,er, and there is an e1ecution .ath through the shader that does not set glLa,er, then the value o#
glLa,er is unde#ined #or e1ecutions o# the shader that take that .ath.
-he out.ut varia9le glLa,er takes on a s.ecial value when used with an arra) o# cu9e a. te1tures.
Instead o# onl) re#erring to the la)er, it is used to select a cu9e a. #ace and a la)er. (etting glLa,er to
the value la,er<6Bface will render to #ace face o# the cu9e de#ined in la)er la,er. -he #ace values are
de#ined in -a9le %.1! o# section %.%.4 B0a)ered 3rae9u##ersC o# the +.en/0 /ra.hics ()ste
(.eci#ication, 9ut re.eated 9elow #or clarit).
Kace Talue Fesulting >arget
*
TEPTQRE_EQ6E_?>@_@OSITIVE_P
1
TEPTQRE_EQ6E_?>@_NE!>TIVE_P
!
TEPTQRE_EQ6E_?>@_@OSITIVE_R
&
TEPTQRE_EQ6E_?>@_NE!>TIVE_R
%
TEPTQRE_EQ6E_?>@_@OSITIVE_S
$
TEPTQRE_EQ6E_?>@_NE!>TIVE_S
3or e1a.le, to render to the .ositive , cu9e a. #ace located in the $th la)er o# the cu9e a. arra),
glLa,er should 9e set to C<6B2.
-he out.ut varia9le glView%ort-n(e* is availa9le onl) in the geoetr) language and .rovides the inde1
o# the view.ort to which the ne1t .riitive eitted #ro the geoetr) shader should 9e drawn. 2riitives
generated 9) the geoetr) shader will undergo view.ort trans#oration and scissor testing using the
view.ort trans#oration and scissor rectangle selected 9) the value o# glView%ort-n(e*. -he view.ort
inde1 used will coe #ro one o# the vertices in the .riitive 9eing shaded. ,owever, which verte1 the
view.ort inde1 coes #ro is i.leentation8de.endent, so it is 9est to use the sae view.ort inde1 #or
all vertices o# the .riitive. I# a geoetr) shader does not assign a value to glView%ort-n(e*, view.ort
trans#or and scissor rectangle ?ero will 9e used. I# a geoetr) shader staticall) assigns a value to
glView%ort-n(e* and there is a .ath through the shader that does not assign a value to glView%ort-n(e*,
the value o# glView%ort-n(e* is unde#ined #or e1ecutions o# the shader that take that .ath. (ee section
!.1&, under V/eoetr) (hader +ut.utsV o# the +.en/0 /ra.hics ()ste (.eci#ication E"ore 2ro#ileF #or
ore in#oration.
-he varia9le gl!atchVertices-n is availa9le onl) in the tessellation control and evaluation languages. It
is an integer s.eci#)ing the nu9er o# vertices in the in.ut .atch 9eing .rocessed 9) the shader. A single
tessellation control or evaluation shader can read .atches o# di##ering si?es, so the value o#
gl!atchVertices-n a) di##er 9etween .atches.

7 Bui%t+in #aria$%es
-he out.ut varia9les gl#essLevel$uter67 and gl#essLevel-nner67 are availa9le onl) in the tessellation
control language. -he values written to these varia9les are assigned to the corres.onding outer and inner
tessellation levels o# the out.ut .atch. -he) are used 9) the tessellation .riitive generator to control
.riitive tessellation and a) 9e read 9) tessellation evaluation shaders.
-he varia9le gl#ess9oor( is availa9le onl) in the tessellation evaluation language. It s.eci#ies a three8
co.onent 4u)v)w5 vector identi#)ing the .osition o# the verte1 9eing .rocessed 9) the shader relative to
the .riitive 9eing tessellated.
-he in.ut varia9les gl#essLevel$uter67 and gl#essLevel-nner67 are availa9le onl) in the tessellation
evaluation shader. I# a tessellation control shader is active, these varia9les are #illed with corres.onding
out.uts written 9) the tessellation control shader. +therwise, the) are assigned with de#ault tessellation
levels s.eci#ied in section !.1! B-essellationC in the +.en/0 /ra.hics ()ste (.eci#ication.
3ragent shaders out.ut values to the +.en/0 .i.eline using the 9uilt8in varia9les gl"rag9olor)
gl"ragData) and gl"ragDe%th, unless the discard stateent is e1ecuted. Both gl"rag9olor and
gl"ragData are de.recatedI the .re#erred usage is to e1.licitl) declare these out.uts in the #ragent
shader using the out storage =uali#ier.
-he #i1ed #unctionalit) co.uted de.th #or a #ragent a) 9e o9tained 9) reading gl"rag9oor(.1)
descri9ed 9elow.
De.recated: @riting to gl"rag9olor s.eci#ies the #ragent color that will 9e used 9) the su9se=uent
#i1ed #unctionalit) .i.eline. I# su9se=uent #i1ed #unctionalit) consues #ragent color and an e1ecution
o# the #ragent shader e1ecuta9le does not write a value to gl"rag9olor then the #ragent color
consued is unde#ined.
@riting to gl"ragDe%th will esta9lish the de.th value #or the #ragent 9eing .rocessed. I# de.th
9u##ering is ena9led, and no shader writes gl"ragDe%th, then the #i1ed #unction value #or de.th will 9e
used as the #ragentHs de.th value. I# a shader staticall) assigns a value to gl"ragDe%th, and there is an
e1ecution .ath through the shader that does not set gl"ragDe%th, then the value o# the #ragentHs de.th
a) 9e unde#ined #or e1ecutions o# the shader that take that .ath. -hat is, i# the set o# linked #ragent
shaders staticall) contain a write to gl"ragDe%th, then it is res.onsi9le #or alwa)s writing it.
De.recated: -he varia9le gl"ragData is an arra). @riting to gl"ragData6n7 s.eci#ies the #ragent
data that will 9e used 9) the su9se=uent #i1ed #unctionalit) .i.eline #or data n. I# su9se=uent #i1ed
#unctionalit) consues #ragent data and an e1ecution o# a #ragent shader e1ecuta9le does not write a
value to it, then the #ragent data consued is unde#ined.
I# a shader staticall) assigns a value to gl"rag9olor, 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"rag9olor. -hat is, a shader a) assign values to either gl"rag9olor or gl"ragData, 9ut
not 9oth. :ulti.le shaders linked together ust also consistentl) write Dust one o# these varia9les.
(iilarl), i# user declared out.ut varia9les are in use Estaticall) assigned toF, then the 9uilt8in varia9les
gl"rag9olor and gl"ragData a) not 9e assigned to. -hese incorrect usages all generate co.ile tie
errors.
I# a shader e1ecutes the discard ke)word, the #ragent is discarded, and the values o# an) user8de#ined
#ragent out.uts, gl"ragDe%th, gl"rag9olor, and gl"ragData 9ecoe irrelevant.
!
7 Bui%t+in #aria$%es
-he varia9le gl"rag9oor( is availa9le as an in.ut varia9le #ro within #ragent shaders and it holds the
window relative coordinates E*, ,, 1, 1DwF values #or the #ragent. I# ulti8sa.ling, this value can 9e #or
an) location within the .i1el, or one o# the #ragent sa.les. -he use o# centroid in does not #urther
restrict this value to 9e inside the current .riitive. -his value is the result o# the #i1ed #unctionalit) that
inter.olates .riitives a#ter verte1 .rocessing to generate #ragents. -he 1 co.onent is the de.th value
that would 9e used #or the #ragentHs de.th i# no shader contained an) writes to gl"ragDe%th. -his is
use#ul #or invariance i# a shader conditionall) co.utes gl"ragDe%th 9ut otherwise wants the #i1ed
#unctionalit) #ragent de.th.
3ragent shaders have access to the in.ut 9uilt8in varia9le gl"ront"acing) whose value is true i# the
#ragent 9elongs to a #ront8#acing .riitive. +ne use o# this is to eulate two8sided lighting 9) selecting
one o# two colors calculated 9) a verte1 or geoetr) shader.
-he values in gl!oint9oor( are two8diensional coordinates indicating where within a .oint .riitive
the current #ragent is located, when .oint s.rites are ena9led. -he) range #ro *.* to 1.* across the
.oint. I# the current .riitive is not a .oint, or i# .oint s.rites are not ena9led, then the values read #ro
gl!oint9oor( are unde#ined.
-he out.ut arra) gl'am%le8as067 sets the sa.le ask #or the #ragent 9eing .rocessed. "overage #or
the current #ragent will 9ecoe the logical A7D o# the coverage ask and the out.ut gl'am%le8as0.
Bit ; o# ask gl'am%le8as0687 corres.onds to sa.le @2<8B;. -his arra) ust 9e si?ed in the
#ragent shader either i.licitl) or e1.licitl) to 9e the sae si?e as the i.leentation8de.endent
a1iu sa.le8ask Eas an arra) o# &!9it eleentsF, deterined 9) the a1iu nu9er o# sa.les.
I# the #ragent shader staticall) assigns a value to gl'am%le8as0, the sa.le ask will 9e 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'am%le8as0, the sa.le ask has no e##ect on the .rocessing o# a
#ragent.
-he in.ut varia9le gl'am%le-D is #illed with the sa.le nu9er o# the sa.le currentl) 9eing .rocessed.
-his varia9le is in the range 0 to gl.um'am%les-1, where gl.um'am%les is the total nu9er o# sa.les
in the #rae9u##er, or 1 i# rendering to a non8ultisa.le #rae9u##er. An) static use o# this varia9le in a
#ragent shader causes the entire shader to 9e evaluated .er8sa.le.
-he in.ut varia9le gl'am%le!osition contains the .osition o# the current sa.le within the ulti8sa.le
draw 9u##er. -he * and , co.onents o# gl'am%le!osition contain the su98.i1el coordinate o# the current
sa.le and will have values in the range *.* to 1.*. An) static use o# this varia9le in a #ragent shader
causes the entire shader to 9e evaluated .er sa.le.
-he gl!erVerte* 9lock can 9e redeclared in a shader to e1.licitl) indicate what su9set o# the #i1ed
.i.eline inter#ace will 9e used. -his is necessar) to esta9lish the inter#ace 9etween ulti.le .rogras.
3or e1a.le:
out gl_@erVertex )
ve%8 gl_@osition, -- /ill use gl_@osition
float gl_@ointSi"e, -- /ill use gl_@ointSi"e
ve%8 t, -- error1 onl& gl_@erVertex mem$ers allo/ed
3, -- no ot.er mem$ers of gl_@erVertex /ill $e used
-his esta9lishes the out.ut inter#ace the shader will use with the su9se=uent .i.eline stage. It ust 9e a
su9set o# the 9uilt8in e9ers o# gl!erVerte*.
!"
7 Bui%t+in #aria$%es
I# a 9uilt8in inter#ace 9lock is redeclared, it ust a..ear in the shader 9e#ore an) use o# an) e9er
included in the 9uilt8in declaration, or a co.ilation error will result. It is also a co.ilation error to
redeclare the 9lock ore than once or to redeclare a 9uilt8in 9lock and then use a e9er #ro that 9uilt8
in 9lock that was not included in the redeclaration. Also, i# a 9uilt8in inter#ace 9lock is redeclared, no
e9er o# the 9uilt8in declaration can 9e redeclared outside the 9lock redeclaration. I# ulti.le shaders
using e9ers o# a 9uilt8in 9lock 9elonging to the sae inter#ace are linked together in the sae
.rogra, the) ust all redeclare the 9uilt8in 9lock in the sae wa), as descri9ed in section %.&.4
BInter#ace BlocksC #or inter#ace 9lock atching, or a link error will result. It will also 9e a link error i#
soe shaders in a .rogra redeclare a s.eci#ic 9uilt8in inter#ace 9lock while another shader in that
.rogra does not redeclare that inter#ace 9lock )et still uses a e9er o# that inter#ace 9lock. I# a 9uilt8
in 9lock inter#ace is #ored across shaders in di##erent .rogras, the shaders ust all redeclare the 9uilt8
in 9lock in the sae wa) Eas descri9ed #or a single .rograF, or the values .assed along the inter#ace are
unde#ined.
2.1.1 Compatibilit# +rofile -uilt6In Language $ariables
@hen using the co.ati9ilit) .ro#ile, the /0 can .rovide #i1ed #unctionalit) 9ehavior #or the verte1 and
#ragent .rograa9le .i.eline stages. 3or e1a.le, i1ing a #i1ed #unctionalit) verte1 stage with a
.rograa9le #ragent stage.
-he #ollowing 9uilt8in verte1, tessellation control, tessellation evaluation, and geoetr) out.ut varia9les
are availa9le to s.eci#) in.uts #or the su9se=uent .rograa9le shader stage or the #i1ed #unctionalit)
#ragent stage. A .articular one should 9e written to i# an) #unctionalit) in a corres.onding #ragent
shader or #i1ed .i.eline uses it or state derived #ro it. +therwise, 9ehavior is unde#ined. -he #ollowing
e9ers are added to the out.ut gl!erVerte* 9lock in these languages:
out gl_@erVertex ) -- part of t.e gl_@erVertex $lo%: des%ri$ed in F+'
-- in addition to ot.er gl_@erVertex mem$ers+++
ve%8 gl_ElipVertex,
ve%8 gl_FrontEolor,
ve%8 gl_6a%:Eolor,
ve%8 gl_FrontSe%ondar&Eolor,
ve%8 gl_6a%:Se%ondar&Eolor,
ve%8 gl_TexEoordBC,
float gl_FogFragEoord,
3,
-he out.ut varia9le gl9li%Verte* .rovides a .lace #or verte1 and geoetr) shaders to write the
coordinate to 9e used with the user cli..ing .lanes.
(iilarl) to what was .reviousl) descri9ed #or the core .ro#ile, the gl!erVerte* 9lock can 9e redeclared
in a shader to e1.licitl) include these additional #ields. 3or e1a.le:
!1
7 Bui%t+in #aria$%es
out gl_@erVertex )
ve%8 gl_@osition, -- /ill use gl_@osition
ve%8 gl_FrontEolor, -- /ill %onsume gl_%olor in t.e fragment s.ader
ve%8 gl_6a%:Eolor,
ve%8 gl_TexEoordB;C, -- ; elements of gl_TexEoord /ill $e used
3, -- no ot.er aspe%ts of t.e fixed interfa%e /ill $e used
-he user ust ensure the cli. verte1 and user cli..ing .lanes are de#ined in the sae coordinate s.ace.
6ser cli. .lanes work .ro.erl) onl) under linear trans#or. It is unde#ined what ha..ens under non8
linear trans#or.
I# a set o# shaders #oring a .rogra that out.uts gl!osition contains no static write to gl9li%Verte* or
gl9li%Distance) 9ut the a..lication has re=uested cli..ing against user cli. .lanes through the A2I, then
the coordinate written to gl!osition is used #or co.arison against the user cli. .lanes. @riting to
gl9li%Distance is the .re#erred ethod #or user cli..ing. It is an error #or the set o# shaders #oring a
.rogra to staticall) read or write 9oth gl9li%Verte* and gl9li%Distance.
-he out.ut varia9les gl"ront9olor, gl"ront'econ(ar,9olor, gl;ac09olor, and gl;ac0'econ(ar,9olor
assign .riar) and secondar) colors #or #ront and 9ack #aces o# .riitives containing the verte1 9eing
.rocessed. -he out.ut varia9le gl#e*9oor( assigns te1ture coordinates #or the verte1 9eing .rocessed.
3or gl"og"rag9oor(, the value written will 9e used as the BcC value in section &.11 B3ogC o# the
co.ati9ilit) .ro#ile o# the +.en/0 /ra.hics ()ste (.eci#ication, 9) the #i1ed #unctionalit) .i.eline.
3or e1a.le, i# the ?8coordinate o# the #ragent in e)e s.ace is desired as BcC, then thatGs what the verte1
shader e1ecuta9le should write into gl"og"rag9oor(.
As with all arra)s, indices used to su9scri.t gl#e*9oor( ust either 9e an integral constant e1.ressions,
or this arra) ust 9e re8declared 9) the shader with a si?e. -he si?e can 9e at ost
gl8a*#e*ture9oor(s. 6sing inde1es close to * a) aid the i.leentation in .reserving var)ing
resources. -he redeclaration o# gl#e*9oor( can also 9e done at glo9al sco.e as, #or e1a.le:
in ve%8 gl_TexEoordB;C,
out ve%8 gl_TexEoordB8C,
E-his treatent is a s.ecial case #or gl#e*9oor(67, not a general ethod #or redeclaring e9ers o#
9locks.F It is a co.ilation error to redeclare gl#e*9oor(67 at glo9al sco.e i# there is a redeclaration o#
the corres.onding 9uilt8in 9lockI onl) one #or o# redeclaration is allowed within a shader Eand hence
within a stage, as 9lock redeclarations ust atch across all shaders using itF.
In the tessellation control, evaluation, and geoetr) shaders, the out.uts o# the .revious stage descri9ed
a9ove are also availa9le in the in.ut gl!erVerte* 9lock in these languages.
!2
7 Bui%t+in #aria$%es
in gl_@erVertex ) -- part of t.e gl_@erVertex $lo%: des%ri$ed in F+'
-- in addition to ot.er gl_@erVertex mem$ers+++
ve%8 gl_ElipVertex,
ve%8 gl_FrontEolor,
ve%8 gl_6a%:Eolor,
ve%8 gl_FrontSe%ondar&Eolor,
ve%8 gl_6a%:Se%ondar&Eolor,
ve%8 gl_TexEoordBC,
float gl_FogFragEoord,
3 gl_inBC,
-hese can 9e redeclared to esta9lish an e1.licit .i.eline inter#ace, the sae wa) as descri9ed a9ove #or
the out.ut 9lock gl!erVerte*, and the in.ut redeclaration ust atch the out.ut redeclaration o# the
.revious stage. ,owever, when a 9uilt8in inter#ace 9lock with an instance nae is redeclared Ee.g., glinF,
the instance nae ust 9e included in the redeclaration. It is an error to not include the 9uilt8in instance
nae or to change its nae. 3or e1a.le,
in gl_@erVertex )
ve%8 gl_ElipVertex,
ve%8 gl_FrontEolor,
3 gl_inBC, -- must $e present and must $e 4gl_inBC5
-reatent o# gl#e*9oor(67 redeclaration is also identical to that descri9ed #or the out.ut 9lock
gl#e*9oor(67 redeclaration.
-he #ollowing #ragent in.ut 9lock is also availa9le in a #ragent shader when using the co.ati9ilit)
.ro#ile:
in gl_@erFragment )
in float gl_FogFragEoord,
in ve%8 gl_TexEoordBC,
in ve%8 gl_Eolor,
in ve%8 gl_Se%ondar&Eolor,
3,
-he values in gl9olor and gl'econ(ar,9olor will 9e derived autoaticall) 9) the s)ste #ro
gl"ront9olor) gl;ac09olor) gl"ront'econ(ar,9olor) and gl;ac0'econ(ar,9olor 9ased on which
#ace is visi9le in the .riitive .roducing the #ragent. I# #i1ed #unctionalit) is used #or verte1 .rocessing,
then gl"og"rag9oor( will either 9e the ?8coordinate o# the #ragent in e)e s.ace, or the inter.olation o#
the #og coordinate, as descri9ed in section &.11 B3ogC o# the co.ati9ilit) .ro#ile o# the +.en/0
/ra.hics ()ste (.eci#ication. -he gl#e*9oor(67 values are the inter.olated gl#e*9oor(67 values
#ro a verte1 shader or the te1ture coordinates o# an) #i1ed .i.eline 9ased verte1 #unctionalit).
Indices to the #ragent shader gl#e*9oor( arra) are as descri9ed a9ove in the verte1 shader te1t.
!3
7 Bui%t+in #aria$%es
As descri9ed a9ove #or the in.ut and out.ut gl!erVerte* 9locks, the gl!er"ragment 9lock can 9e
redeclared to create an e1.licit inter#ace to another .rogra. @hen atching these inter#aces 9etween
se.arate .rogras, e9ers in the gl!erVerte* out.ut 9lock ust 9e declared i# and onl) i# the
corres.onding #ragent8shader e9ers generated #ro the are .resent in the gl!er"ragment in.ut
9lock. -hese atches are descri9ed in detail in section !.1% BVerte1 (hadersC o# the +.en/0 /ra.hics
()ste (.eci#ication E"o.ati9ilit) 2ro#ileF. I# the) donGt atch within a .rogra, a link error will
result. I# the isatch is 9etween two .rogras, values .assed 9etween .rogras are unde#ined. 6nlike
with all other 9lock atching, the order o# declaration within gl!er"ragment does not have to atch
across shaders and does not have to corres.ond with order o# declaration in a atching gl!erVerte*
redeclaration.
2.2 Compatibilit# +rofile $erte* Shader -uilt6In Inputs
-he #ollowing .redeclared in.ut naes can 9e used #ro within a verte1 shader to access the current
values o# +.en/0 state when using the co.ati9ilit) .ro#ile.
in ve%8 gl_Eolor,
in ve%8 gl_Se%ondar&Eolor,
in ve%; gl_Normal,
in ve%8 gl_Vertex,
in ve%8 gl_?ultiTexEoord=,
in ve%8 gl_?ultiTexEoord',
in ve%8 gl_?ultiTexEoord9,
in ve%8 gl_?ultiTexEoord;,
in ve%8 gl_?ultiTexEoord8,
in ve%8 gl_?ultiTexEoord<,
in ve%8 gl_?ultiTexEoordG,
in ve%8 gl_?ultiTexEoordF,
in float gl_FogEoord,
2.! -uilt6In Constants
-he #ollowing 9uilt8in constants are .rovided to all shaders. -he actual values used are i.leentation
de.endent, 9ut ust 9e at least the value shown. (oe are de.recated, as indicated in coents.
--
-- Implementation dependent %onstants+ T.e example values $elo/
-- are t.e minimum values allo/ed for t.ese maximums+
--
%onst int gl_?axVertex>ttri$s * 'G,
%onst int gl_?axVertexQniformEomponents * '=98,
%onst int gl_?axVar&ingFloats * G=, -- epre%ated
%onst int gl_?axVar&ingEomponents * G=, -- epre%ated
%onst int gl_?axVertexOutputEomponents * G8,
%onst int gl_?ax!eometr&InputEomponents * G8,
%onst int gl_?ax!eometr&OutputEomponents * '9O,
%onst int gl_?axFragmentInputEomponents * '9O,
%onst int gl_?axVertexTextureImageQnits * 'G,
%onst int gl_?axEom$inedTextureImageQnits * O=,
!4
7 Bui%t+in #aria$%es
%onst int gl_?axTextureImageQnits * 'G,
%onst int gl_?axFragmentQniformEomponents * '=98,
%onst int gl_?axra/6uffers * O,
%onst int gl_?axElipistan%es * O,
%onst int gl_?ax!eometr&TextureImageQnits * 'G,
%onst int gl_?ax!eometr&OutputVerti%es * 9<G,
%onst int gl_?ax!eometr&TotalOutputEomponents * '=98,
%onst int gl_?ax!eometr&QniformEomponents * '=98,
%onst int gl_?ax!eometr&Var&ingEomponents * G8,
%onst int gl_?axTessEontrolInputEomponents * '9O,
%onst int gl_?axTessEontrolOutputEomponents * '9O,
%onst int gl_?axTessEontrolTextureImageQnits * 'G,
%onst int gl_?axTessEontrolQniformEomponents * '=98,
%onst int gl_?axTessEontrolTotalOutputEomponents * 8=HG,
%onst int gl_?axTessEvaluationInputEomponents * '9O,
%onst int gl_?axTessEvaluationOutputEomponents * '9O,
%onst int gl_?axTessEvaluationTextureImageQnits * 'G,
%onst int gl_?axTessEvaluationQniformEomponents * '=98,
%onst int gl_?axTess@at%.Eomponents * '9=,
%onst int gl_?ax@at%.Verti%es * ;9,
%onst int gl_?axTess!enLevel * G8,
%onst int gl_?axVie/ports * 'G,
%onst int gl_?axVertexQniformVe%tors * 9<G,
%onst int gl_?axFragmentQniformVe%tors * 9<G,
%onst int gl_?axVar&ingVe%tors * '<,
-he constant gl8a*Var,ing"loats is de.recated, use gl8a*Var,ing9om%onents instead.
2.!.1 Compatibilit# +rofile -uilt6In Constants
%onst int gl_?axTextureQnits * 9,
%onst int gl_?axTextureEoords * O,
%onst int gl_?axElip@lanes * O,
2. -uilt6In 4niform State
As an aid to accessing +.en/0 .rocessing state, the #ollowing uni#or varia9les are 9uilt into the
+.en/0 (hading 0anguage.
!5
7 Bui%t+in #aria$%es
--
-- ept. range in /indo/ %oordinates1
-- se%tion 9+'8+' 4Eontrolling t.e Vie/port5 in t.e
-- Open!L !rap.i%s S&stem Spe%ifi%ation+
--
stru%t gl_ept.Range@arameters )
float near, -- n
float far, -- f
float diff, -- f 2 n
3,
uniform gl_ept.Range@arameters gl_ept.Range,
2..1 Compatibilit# +rofile State
-hese varia9les are .resent onl) in the co.ati9ilit) .ro#ile.
--
-- %ompati$ilit& profile onl&
--
uniform mat8 gl_?odelVie/?atrix,
uniform mat8 gl_@ro7e%tion?atrix,
uniform mat8 gl_?odelVie/@ro7e%tion?atrix,
uniform mat8 gl_Texture?atrixBgl_?axTextureEoordsC,
--
-- %ompati$ilit& profile onl&
--
uniform mat; gl_Normal?atrix, -- transpose of t.e inverse of t.e
-- upper leftmost ;x; of gl_?odelVie/?atrix
uniform mat8 gl_?odelVie/?atrixInverse,
uniform mat8 gl_@ro7e%tion?atrixInverse,
uniform mat8 gl_?odelVie/@ro7e%tion?atrixInverse,
uniform mat8 gl_Texture?atrixInverseBgl_?axTextureEoordsC,
uniform mat8 gl_?odelVie/?atrixTranspose,
uniform mat8 gl_@ro7e%tion?atrixTranspose,
uniform mat8 gl_?odelVie/@ro7e%tion?atrixTranspose,
uniform mat8 gl_Texture?atrixTransposeBgl_?axTextureEoordsC,
uniform mat8 gl_?odelVie/?atrixInverseTranspose,
uniform mat8 gl_@ro7e%tion?atrixInverseTranspose,
uniform mat8 gl_?odelVie/@ro7e%tion?atrixInverseTranspose,
uniform mat8 gl_Texture?atrixInverseTransposeBgl_?axTextureEoordsC,
--
-- %ompati$ilit& profile onl&
--
uniform float gl_NormalS%ale,
!6
7 Bui%t+in #aria$%es
--
-- %ompati$ilit& profile onl&
--
uniform ve%8 gl_Elip@laneBgl_?axElip@lanesC,
--
-- %ompati$ilit& profile onl&
--
stru%t gl_@oint@arameters )
float si"e,
float si"e?in,
float si"e?ax,
float fadeT.res.oldSi"e,
float distan%eEonstant>ttenuation,
float distan%eLinear>ttenuation,
float distan%eTuadrati%>ttenuation,
3,

uniform gl_@oint@arameters gl_@oint,
--
-- %ompati$ilit& profile onl&
--
stru%t gl_?aterial@arameters )
ve%8 emission, -- E%m
ve%8 am$ient, -- >%m
ve%8 diffuse, -- %m
ve%8 spe%ular, -- S%m
float s.ininess, -- Srm
3,
uniform gl_?aterial@arameters gl_Front?aterial,
uniform gl_?aterial@arameters gl_6a%:?aterial,
!7
7 Bui%t+in #aria$%es
--
-- %ompati$ilit& profile onl&
--
stru%t gl_Lig.tSour%e@arameters )
ve%8 am$ient, -- >%li
ve%8 diffuse, -- %li
ve%8 spe%ular, -- S%li
ve%8 position, -- @pli
ve%8 .alfVe%tor, -- erived( Ji
ve%; spotire%tion, -- Sdli
float spotExponent, -- Srli
float spotEutoff, -- Erli
-- #range( B=+=1H=+=C1 'O=+=)
float spotEosEutoff, -- erived( %os#Erli)
-- #range( B'+=1=+=C12'+=)
float %onstant>ttenuation, -- U=
float linear>ttenuation, -- U'
float Auadrati%>ttenuation,-- U9
3,
uniform gl_Lig.tSour%e@arameters gl_Lig.tSour%eBgl_?axLig.tsC,
stru%t gl_Lig.t?odel@arameters )
ve%8 am$ient, -- >%s
3,
uniform gl_Lig.t?odel@arameters gl_Lig.t?odel,
--
-- %ompati$ilit& profile onl&
--
-- erived state from produ%ts of lig.t and material+
--
stru%t gl_Lig.t?odel@rodu%ts )
ve%8 s%eneEolor, -- erived+ E%m L >%m K >%s
3,
uniform gl_Lig.t?odel@rodu%ts gl_FrontLig.t?odel@rodu%t,
uniform gl_Lig.t?odel@rodu%ts gl_6a%:Lig.t?odel@rodu%t,
stru%t gl_Lig.t@rodu%ts )
ve%8 am$ient, -- >%m K >%li
ve%8 diffuse, -- %m K %li
ve%8 spe%ular, -- S%m K S%li
3,
uniform gl_Lig.t@rodu%ts gl_FrontLig.t@rodu%tBgl_?axLig.tsC,
uniform gl_Lig.t@rodu%ts gl_6a%:Lig.t@rodu%tBgl_?axLig.tsC,
!
7 Bui%t+in #aria$%es
--
-- %ompati$ilit& profile onl&
--
uniform ve%8 gl_TextureEnvEolorBgl_?axTextureQnitsC,
uniform ve%8 gl_E&e@laneSBgl_?axTextureEoordsC,
uniform ve%8 gl_E&e@laneTBgl_?axTextureEoordsC,
uniform ve%8 gl_E&e@laneRBgl_?axTextureEoordsC,
uniform ve%8 gl_E&e@laneTBgl_?axTextureEoordsC,
uniform ve%8 gl_O$7e%t@laneSBgl_?axTextureEoordsC,
uniform ve%8 gl_O$7e%t@laneTBgl_?axTextureEoordsC,
uniform ve%8 gl_O$7e%t@laneRBgl_?axTextureEoordsC,
uniform ve%8 gl_O$7e%t@laneTBgl_?axTextureEoordsC,
--
-- %ompati$ilit& profile onl&
--
stru%t gl_Fog@arameters )
ve%8 %olor,
float densit&,
float start,
float end,
float s%ale, -- erived( '+= - #end 2 start)
3,

uniform gl_Fog@arameters gl_Fog,
!!
3 -uilt6in ,unctions
-he +.en/0 (hading 0anguage de#ines an assortent o# 9uilt8in convenience #unctions #or scalar and
vector o.erations. :an) o# these 9uilt8in #unctions can 9e used in ore than one t).e o# shader, 9ut soe
are intended to .rovide a direct a..ing to hardware and so are availa9le onl) #or a s.eci#ic t).e o#
shader.
-he 9uilt8in #unctions 9asicall) #all into three categories:
-he) e1.ose soe necessar) hardware #unctionalit) in a convenient wa) such as accessing a te1ture
a.. -here is no wa) in the language #or these #unctions to 9e eulated 9) a shader.
-he) re.resent a trivial o.eration Ecla., i1, etc.F that is ver) si.le #or the user to write, 9ut the)
are ver) coon and a) have direct hardware su..ort. It is a ver) hard .ro9le #or the co.iler to
a. e1.ressions to co.le1 asse9ler instructions.
-he) re.resent an o.eration gra.hics hardware is likel) to accelerate at soe .oint. -he trigonoetr)
#unctions #all into this categor).
:an) o# the #unctions are siilar to the sae naed ones in coon " li9raries, 9ut the) su..ort vector
in.ut as well as the ore traditional scalar in.ut.
A..lications should 9e encouraged to use the 9uilt8in #unctions rather than do the e=uivalent co.utations
in their own shader code since the 9uilt8in #unctions are assued to 9e o.tial Ee.g., .erha.s su..orted
directl) in hardwareF.
6ser code can re.lace 9uilt8in #unctions with their own i# the) choose, 9) si.l) re8declaring and de#ining
the sae nae and arguent list. Because 9uilt8in #unctions are in a ore outer sco.e than user 9uilt8in
#unctions, doing this will hide all 9uilt8in #unctions with the sae nae as the re8declared #unction.
@hen the 9uilt8in #unctions are s.eci#ied 9elow, where the in.ut arguents Eand corres.onding out.utF
can 9e float, vecD, vecE, or vecB, gen#,%e is used as the arguent. @here the in.ut arguents Eand
corres.onding out.utF can 9e int, ivecD, ivecE, or ivecB, gen-#,%e is used as the arguent. @here the
in.ut arguents Eand corres.onding out.utF can 9e uint, uvecD, uvecE, or uvecB, genE#,%e is used as the
arguent. @here the in.ut arguents Eor corres.onding out.utF can 9e bool, bvecD, bvecE, or bvecB,
gen;#,%e is used as the arguent. @here the in.ut arguents Eand corres.onding out.utF can 9e double,
dvecD, dvecE, dvecB, genD#,%e is used as the arguent. 3or an) s.eci#ic use o# a #unction, the actual
t).es su9stituted #or gen#,%e, gen-#,%e, genE#,%e) or gen;#,%e have to have the sae nu9er o#
co.onents #or all arguents and #or the return t).e. (iilarl), mat is used #or an) atri1 9asic t).e
with single8.recision co.onents and (mat is used #or an) atri1 9asic t).e with dou9le8.recision
co.onents.
1""
Bui%t+in ,unctions
3.1 .ngle and Trigonometr# ,unctions
3unction .araeters s.eci#ied as angle are assued to 9e in units o# radians. In no case will an) o# these
#unctions result in a divide 9) ?ero error. I# the divisor o# a ratio is *, then results will 9e unde#ined.
-hese all o.erate co.onent8wise. -he descri.tion is .er co.onent.
S#nta* )escription
gen-).e radians Egen-).e (egreesF
"onverts (egrees to radians, i.e.,

15*
(egrees
gen-).e degrees Egen-).e ra(iansF
"onverts ra(ians to degrees, i.e.,
15*

ra(ians
gen-).e sin Egen-).e angleF -he standard trigonoetric sine #unction.
gen-).e cos Egen-).e angleF -he standard trigonoetric cosine #unction.
gen-).e tan Egen-).e angleF -he standard trigonoetric tangent.
gen-).e asin Egen-).e *F Arc sine. Returns an angle whose sine is *. -he range
o# values returned 9) this #unction is
[

!
)

!
]
Results are unde#ined i# *1.
gen-).e acos Egen-).e *F Arc cosine. Returns an angle whose cosine is *. -he
range o# values returned 9) this #unction is Y*, Z.
Results are unde#ined i# *1.
gen-).e atan Egen-).e ,, gen-).e *F Arc tangent. Returns an angle whose tangent is ,D*. -he
signs o# * and , are used to deterine what =uadrant the
angle is in. -he range o# values returned 9) this
#unction is [) ]. Results are unde#ined i# * and
, are 9oth *.
gen-).e atan Egen-).e ,over*F Arc tangent. Returns an angle whose tangent is
,over*. -he range o# values returned 9) this #unction
is
[

!
)

!
]
.
1"1
Bui%t+in ,unctions
S#nta* )escription
gen-).e sinh Egen-).e *F Returns the h).er9olic sine #unction
e
*
e
*
!
gen-).e cosh Egen-).e *F Returns the h).er9olic cosine #unction
e
*
e
*
!
gen-).e tanh Egen-).e *F Returns the h).er9olic tangent #unction
sinh *
cosh *
gen-).e asinh Egen-).e *F Arc h).er9olic sineI returns the inverse o# sinh.
gen-).e acosh Egen-).e *F Arc h).er9olic cosineI returns the non8negative inverse
o# cosh. Results are unde#ined i# * P 1.
gen-).e atanh Egen-).e *F Arc h).er9olic tangentI returns the inverse o# tanh.
Results are unde#ined i# *1.
1"2
Bui%t+in ,unctions
3.2 '*ponential ,unctions
-hese all o.erate co.onent8wise. -he descri.tion is .er co.onent.
S#nta* )escription
gen-).e pow Egen-).e *, gen-).e ,F Returns * raised to the , .ower, i.e., *
,
Results are unde#ined i# * F 0.
Results are unde#ined i# * = 0 and , F= 0.
gen-).e exp Egen-).e *F Returns the natural e1.onentiation o# *, i.e., e
*
.
gen-).e log Egen-).e *F Returns the natural logarith o# *) i.e., returns the value
, which satis#ies the e=uation * R e
,
.
Results are unde#ined i# * F= 0.
gen-).e expD Egen-).e *F Returns ! raised to the * .ower, i.e., !
*
gen-).e logD Egen-).e *F Returns the 9ase ! logarith o# *) i.e., returns the value
, which satis#ies the e=uation *=!
,
Results are unde#ined i# * F= 0.
gen-).e srt Egen-).e *F
genD-).e srt EgenD-).e *F
Returns
* .
Results are unde#ined i# * F 0.
gen-).e inversesrt Egen-).e *F
genD-).e inversesrt EgenD-).e *F
Returns
1
*
.
Results are unde#ined i# * F= 0.
1"3
Bui%t+in ,unctions
3.! Common ,unctions
-hese all o.erate co.onent8wise. -he descri.tion is .er co.onent.
S#nta* )escription
gen-).e abs Egen-).e *F
genI-).e abs EgenI-).e *F
genD-).e abs EgenD-).e *F
Returns * i# * QR *, otherwise it returns [*.
gen-).e sign Egen-).e *F
genI-).e sign EgenI-).e *F
genD-).e sign EgenD-).e *F
Returns 1.* i# * Q *, *.* i# * R *, or [1.* i# * P *.
gen-).e floor Egen-).e *F
genD-).e floor EgenD-).e *F
Returns a value e=ual to the nearest integer that is less
than or e=ual to *.
gen-).e trunc Egen-).e *F
genD-).e trunc EgenD-).e *F
Returns a value e=ual to the nearest integer to * whose
a9solute value is not larger than the a9solute value o# *.
gen-).e round Egen-).e *F
genD-).e round EgenD-).e *F
Returns a value e=ual to the nearest integer to *. -he
#raction *.$ will round in a direction chosen 9) the
i.leentation, .resua9l) the direction that is #astest.
-his includes the .ossi9ilit) that roundE*F returns the
sae value as roundJvenE*F #or all values o# *.
gen-).e roundJven Egen-).e *F
genD-).e roundJven EgenD-).e *F
Returns a value e=ual to the nearest integer to *. A
#ractional .art o# *.$ will round toward the nearest even
integer. EBoth &.$ and %.$ #or 1 will return %.*.F
gen-).e ceil Egen-).e *F
genD-).e ceil EgenD-).e *F
Returns a value e=ual to the nearest integer that is
greater than or e=ual to *.
gen-).e fract Egen-).e *F
genD-).e fract EgenD-).e *F
Returns * [ floor E*F.
gen-).e mod Egen-).e *, #loat ,F
gen-).e mod Egen-).e *, gen-).e ,F
genD-).e mod EgenD-).e *, dou9le ,F
genD-).e mod EgenD-).e *, genD-).e ,F
:odulus. Returns * [ , floor E*N,F.
1"4
Bui%t+in ,unctions
S#nta* )escription
gen-).e modf Egen-).e *, out gen-).e iF
genD-).e modf EgenD-).e *,
out genD-).e iF
Returns the #ractional .art o# * and sets i to the integer
.art Eas a whole nu9er #loating .oint valueF. Both the
return value and the out.ut .araeter will have the sae
sign as *.
gen-).e min Egen-).e *, gen-).e ,F
gen-).e min Egen-).e *, #loat ,F
genD-).e min EgenD-).e *, genD-).e ,F
genD-).e min EgenD-).e *, dou9le ,F
genI-).e min EgenI-).e *, genI-).e ,F
genI-).e min EgenI-).e *, int ,F
gen6-).e min Egen6-).e *, gen6-).e ,F
gen6-).e min Egen6-).e *, uint ,F
Returns , i# , P *, otherwise it returns *.
gen-).e max Egen-).e *, gen-).e ,F
gen-).e max Egen-).e *, #loat ,F
genD-).e max EgenD-).e *, genD-).e ,F
genD-).e max EgenD-).e *, dou9le ,F
genI-).e max EgenI-).e *, genI-).e ,F
genI-).e max EgenI-).e *, int ,F
gen6-).e max Egen6-).e *, gen6-).e ,F
gen6-).e max Egen6-).e *, uint ,F
Returns , i# * P ,, otherwise it returns *.
1"5
Bui%t+in ,unctions
S#nta* )escription
gen-).e clamp Egen-).e *,
gen-).e minVal,
gen-).e ma*ValF
gen-).e clamp Egen-).e *,
#loat minVal,
#loat ma*ValF
genD-).e clamp EgenD-).e *,
genD-).e minVal,
genD-).e ma*ValF
genD-).e clamp EgenD-).e *,
dou9le minVal,
dou9le ma*ValF
genI-).e clamp EgenI-).e *,
genI-).e minVal,
genI-).e ma*ValF
genI-).e clamp EgenI-).e *,
int minVal,
int ma*ValF
gen6-).e clamp Egen6-).e *,
gen6-).e minVal,
gen6-).e ma*ValF
gen6-).e clamp Egen6-).e *,
uint minVal,
uint ma*ValF
Returns min Emax E*, minValF, ma*ValF.
Results are unde#ined i# minVal Q ma*Val.
gen-).e mix Egen-).e *,
gen-).e ,,
gen-).e aF
gen-).e mix Egen-).e *,
gen-).e ,,
#loat aF
genD-).e mix EgenD-).e *,
genD-).e ,,
genD-).e aF
genD-).e mix EgenD-).e *,
genD-).e ,,
dou9le aF
Returns the linear 9lend o# * and ,) i.e.,
*1a,a
1"6
Bui%t+in ,unctions
S#nta* )escription
gen-).e mix Egen-).e *,
gen-).e ),
genB-).e aF
genD-).e mix EgenD-).e *,
genD-).e ),
genB-).e aF
(elects which vector each returned co.onent coes
#ro. 3or a co.onent o# a that is false, the
corres.onding co.onent o# * is returned. 3or a
co.onent o# a that is true, the corres.onding
co.onent o# , is returned. "o.onents o# * and , that
are not selected are allowed to 9e invalid #loating .oint
values and will have no e##ect on the results. -hus, this
.rovides di##erent #unctionalit) than, #or e1a.le,
gen-).e mixEgen-).e *, gen-).e ,, gen-).eEaFF
where a is a Boolean vector.
gen-).e step Egen-).e e(ge, gen-).e *F
gen-).e step E#loat e(ge, gen-).e *F
genD-).e step EgenD-).e e(ge,
genD-).e *F
genD-).e step Edou9le e(ge, genD-).e *F
Returns *.* i# * P e(ge, otherwise it returns 1.*.
gen-).e smoothstep Egen-).e e(ge0,
gen-).e e(ge1,
gen-).e *F
gen-).e smoothstep E#loat e(ge0,
#loat e(ge1,
gen-).e *F
genD-).e smoothstep EgenD-).e e(ge0,
genD-).e e(ge1,
genD-).e *F
genD-).e smoothstep Edou9le e(ge0,
dou9le e(ge1,
genD-).e *F
Returns *.* i# * PR e(ge0 and 1.* i# * QR e(ge1 and
.er#ors sooth ,erite inter.olation 9etween * and 1
when e(ge0 P * P e(ge1. -his is use#ul in cases where
)ou would want a threshold #unction with a sooth
transition. -his is e=uivalent to:
gen-).e tI
t R cla. EE1 [ edge*F N Eedge1 [ edge*F, *, 1FI
return t M t M E& [ ! M tFI
EAnd siilarl) #or dou9les.F
Results are un(efine( if e(ge0 G= e(ge1.
genB-).e isnan Egen-).e *F
genB-).e isnan EgenD-).e *F
Returns true i# * holds a 7a7. Returns false otherwise.
genB-).e isinf Egen-).e *F
genB-).e isinf EgenD-).e *F
Returns true i# * holds a .ositive in#init) or negative
in#init). Returns false otherwise.
genI-).e floatGits>oMnt Egen-).e valueF
gen6-).e floatGits>oSint Egen-).e valueF
Returns a signed or unsigned integer value re.resenting
the encoding o# a #loating8.oint value. -he #loating8
.oint valueGs 9it8level re.resentation is .reserved.
1"7
Bui%t+in ,unctions
S#nta* )escription
gen-).e intGits>oKloat EgenI-).e valueF
gen-).e uintGits>oKloat Egen6-).e valueF
Returns a #loating8.oint value corres.onding to a signed
or unsigned integer encoding o# a #loating8.oint value.
I# a 7a7 is .assed in, it will not signal, and the resulting
#loating .oint value is uns.eci#ied. I# an In# is .assed in,
the resulting #loating8.oint value is the corres.onding
In#.
gen-).e fma Egen-).e a, gen-).e +,
gen-).e cF
genD-).e fma EgenD-).e a, genD-).e +,
genD-).e cF
"o.utes and returns a<+ B c.
In uses where the return value is eventuall) consued 9)
a varia9le declared as precise:
fmaEF is considered a single o.eration, whereas the
e1.ression BaM+ J cC consued 9) a varia9le
declared precise is considered two o.erations.
-he .recision o# fmaEF can di##er #ro the .recision
o# the the e1.ression BaM+ J cC.
fmaEF will 9e co.uted with the sae .recision as
an) other fmaEF consued 9) a precise varia9le,
giving invariant results #or the sae in.ut values o#
a, +, and c.
+therwise, in the a9sence o# precise consu.tion, there
are no s.ecial constraints on the nu9er o# o.erations or
di##erence in .recision 9etween fmaEF and the e1.ression
BaM+ J cC.
gen-).e frexp Egen-).e *,
out genI-).e e*%F
genD-).e frexp EgenD-).e *,
out genI-).e e*%F
(.lits * into a #loating8.oint signi#icand in the range
Y*.$, 1.*F and an integral e1.onent o# two, such that:
*=significan(!
e*%onent
-he signi#icand is returned 9) the #unction and the
e1.onent is returned in the .araeter e*%. 3or a
#loating8.oint value o# ?ero, the signi#icant and e1.onent
are 9oth ?ero. 3or a #loating8.oint value that is an
in#init) or is not a nu9er, the results are unde#ined.
gen-).e ldexp Egen-).e *,
in genI-).e e*%F
genD-).e ldexp EgenD-).e *,
in genI-).e e*%F
Builds a #loating8.oint nu9er #ro * and the
corres.onding integral e1.onent o# two in e*%, returning:
significan(!
e*%onent
I# this .roduct is too large to 9e re.resented in the
#loating8.oint t).e, the result is unde#ined.
1"
Bui%t+in ,unctions
1"!
Bui%t+in ,unctions
3. ,loating6+oint +ac0 and 4npac0 ,unctions
-hese #unctions do not o.erate co.onent8wise, rather as descri9ed in each case.
S#nta* )escription
uint packSnormDx1Y Evec! vF
uint packSnormBx[ Evec% vF
uint packSnormBx[ Evec% vF
3irst, converts each co.onent o# the norali?ed
#loating8.oint value v into 58 or 1'89it integer values.
-hen, the results are .acked into the returned &!89it
unsigned integer.
-he conversion #or co.onent c o# v to #i1ed .oint is
done as #ollows:
packSnormDx1Y: roundEcla.Ec, *, J1F M '$$&$.*F
packSnormBx[: roundEcla.Ec, *, J1F M !$$.*F
packSnormBx[: roundEcla.Ec, 81, J1F M 1!4.*F
-he #irst co.onent o# the vector will 9e written to the
least signi#icant 9its o# the out.utI the last co.onent
will 9e written to the ost signi#icant 9its.
vec! unpackSnormDx1Y Euint %F
vec% unpackSnormBx[ Euint %F
vec% unpackSnormBx[ Euint %F
3irst, un.acks a single &!89it unsigned integer % into a
.air o# 1'89it unsigned integers, #our 589it unsigned
integers, or #our 589it signed integers. -hen, each
co.onent is converted to a norali?ed #loating8.oint
value to generate the returned two8 or #our8co.onent
vector.
-he conversion #or un.acked #i1ed8.oint value f to
#loating .oint is done as #ollows:
unpackSnormDx1Y9 f N '$$&$.*
unpackSnormBx[9 f N !$$.*
unpackSnormBx[9 cla.Ef N 1!4.*, 81, J1F
-he #irst co.onent o# the returned vector will 9e
e1tracted #ro the least signi#icant 9its o# the in.utI the
last co.onent will 9e e1tracted #ro the ost
signi#icant 9its.
dou9le pack?oubleDxED Euvec! vF Returns a dou9le8.recision value o9tained 9) .acking
the co.onents o# v into a '%89it value. I# an IEEE 4$%
In# or 7a7 is created, it will not signal, and the resulting
#loating .oint value is uns.eci#ied. +therwise, the 9it8
level re.resentation o# v is .reserved. -he #irst vector
co.onent s.eci#ies the &! least signi#icant 9itsI the
second co.onent s.eci#ies the &! ost signi#icant 9its.
11"
Bui%t+in ,unctions
S#nta* )escription
uvec! unpack?oubleDxED Edou9le v5 Returns a two8co.onent unsigned integer vector
re.resentation o# v. -he 9it8level re.resentation o# v is
.reserved. -he #irst co.onent o# the vector contains
the &! least signi#icant 9its o# the dou9leI the second
co.onent consists the &! ost signi#icant 9its.
111
Bui%t+in ,unctions
3.5 Geometric ,unctions
-hese o.erate on vectors as vectors, not co.onent8wise.
S#nta* )escription
#loat length Egen-).e *F
dou9le length EgenD-).e *F
Returns the length o# vector *, i.e.,
*[ *]
!
*[ 1]
!
...
#loat distance Egen-).e %0, gen-).e %1F
dou9le distance EgenD-).e %0,
genD-).e %1F
Returns the distance 9etween %0 and %1, i.e.,
length E%0 H %1F
#loat dot Egen-).e *, gen-).e ,F
dou9le dot EgenD-).e *, genD-).e ,F
Returns the dot .roduct o# * and ,, i.e.,
*[ *], [*]* [1],[1]...
vec& cross Evec& *, vec& ,F
dvec& cross Edvec& *, dvec& ,F
Returns the cross .roduct o# 1 and ), i.e.,
[
* [1],[ !], [1]* [!]
*[ !],[ *], [ !]*[ *]
*[*], [1], [*]* [1]
]
gen-).e normali"e Egen-).e *F
genD-).e normali"e EgenD-).e *F
Returns a vector in the sae direction as * 9ut with a
length o# 1.
co.ati9ilit) .ro#ile onl)
vec% ftransformEF
Availa9le onl) when using the co.ati9ilit) .ro#ile. 3or
core +.en/0, use invariant.
3or verte1 shaders onl). -his #unction will ensure that
the incoing verte1 value will 9e trans#ored in a wa)
that .roduces e1actl) the sae result as would 9e
.roduced 9) +.en/0Hs #i1ed #unctionalit) trans#or. It
is intended to 9e used to co.ute gl!osition, e.g.,
gl>2osition R ftransformEF
-his #unction should 9e used, #or e1a.le, when an
a..lication is rendering the sae geoetr) in se.arate
.asses, and one .ass uses the #i1ed #unctionalit) .ath to
render and another .ass uses .rograa9le shaders.
112
Bui%t+in ,unctions
S#nta* )escription
gen-).e faceforward Egen-).e .,
gen-).e -,
gen-).e .refF
genD-).e faceforward EgenD-).e .,
genD-).e -,
genD-).e .refF
I# dotE.ref, -F P * return .) otherwise return [..
gen-).e reflect Egen-).e -, gen-).e .F
genD-).e reflect EgenD-).e -,
genD-).e .F
3or the incident vector - and sur#ace orientation .,
returns the re#lection direction:
- [ ! dotE., -F .
. ust alread) 9e norali?ed in order to achieve the
desired result.
gen-).e refract Egen-).e -, gen-).e .,
#loat etaF
genD-).e refract EgenD-).e -,
genD-).e .,
#loat etaF
3or the incident vector - and sur#ace noral ., and the
ratio o# indices o# re#raction eta) return the re#raction
vector. -he result is co.uted 9)
k R 1.* 8 eta M eta M E1.* 8 dotE., -F M dotE., -FF
i# Ek P *.*F
return gen-).eE*.*F NN or genD-).eE*.*F
else
return eta M - 8 Eeta M dotE., -F J srtEkFF M .
-he in.ut .araeters #or the incident vector - and the
sur#ace noral . ust alread) 9e norali?ed to get the
desired results.
113
Bui%t+in ,unctions
3." 7atri* ,unctions
3or each o# the #ollowing 9uilt8in atri1 #unctions, there is 9oth a single8.recision #loating .oint version,
where all arguents and return values are single .recision, and a dou9le8.recision #loating version, where
all arguents and return values are dou9le .recision. +nl) the single8.recision #loating .oint version is
shown.
S#nta* )escription
at matrixCompHult Eat *, at ,F :ulti.l) atri1 * 9) atri1 , co.onent8wise, i.e.,
resultYiZYDZ is the scalar .roduct o# *YiZYDZ and ,YiZYDZ.
7ote: to get linear alge9raic atri1 ulti.lication, use
the ulti.l) o.erator E)F.
at! outerQroductEvec! c, vec! rF
at& outerQroductEvec& c, vec& rF
at% outerQroductEvec% c, vec% rF
at!1& outerQroductEvec& c, vec! rF
at&1! outerQroductEvec! c, vec& rF
at!1% outerQroductEvec% c, vec! rF
at%1! outerQroductEvec! c, vec% rF
at&1% outerQroductEvec% c, vec& rF
at%1& outerQroductEvec& c, vec% rF
-reats the #irst .araeter c as a colun vector Eatri1
with one colunF and the second .araeter r as a row
vector Eatri1 with one rowF and does a linear alge9raic
atri1 ulti.l) c M r, )ielding a atri1 whose nu9er o#
rows is the nu9er o# co.onents in c and whose
nu9er o# coluns is the nu9er o# co.onents in r.
at! transposeEat! mF
at& transposeEat& mF
at% transposeEat% mF
at!1& transposeEat&1! mF
at&1! transposeEat!1& mF
at!1% transposeEat%1! mF
at%1! transposeEat!1% mF
at&1% transposeEat%1& mF
at%1& transposeEat&1% mF
Returns a atri1 that is the trans.ose o# m. -he in.ut
atri1 m is not odi#ied.
#loat determinantEat! mF
#loat determinantEat& mF
#loat determinantEat% mF
Returns the deterinant o# m.
114
Bui%t+in ,unctions
S#nta* )escription
at! inverseEat! mF
at& inverseEat& mF
at% inverseEat% mF
Returns a atri1 that is the inverse o# m. -he in.ut
atri1 m is not odi#ied. -he values in the returned
atri1 are unde#ined i# m is singular or .oorl)8
conditioned Enearl) singularF.
115
Bui%t+in ,unctions
3.2 $ector :elational ,unctions
Relational and e=ualit) o.erators E+$ +7$ ,$ ,7$ 77$ 87F are de#ined to o.erate on scalars and .roduce
scalar Boolean results. 3or vector results, use the #ollowing 9uilt8in #unctions. Below, the #ollowing
.laceholders are used #or the listed s.eci#ic t).es:
Qlaceholder Specific >Cpes Allowed
9vec 9vec!, 9vec&, 9vec%
ivec ivec!, ivec&, ivec%
uvec uvec!, uvec&, uvec%
vec vec!, vec&, vec%, dvec!, dvec&, dvec%
In all cases, the si?es o# all the in.ut and return vectors #or an) .articular call ust atch.
S#nta* )escription
9vec less>hanEvec 1, vec )F
9vec less>hanEivec 1, ivec )F
9vec less>hanEuvec 1, uvec )F
Returns the co.onent8wise co.are o# * P ,.
9vec less>hanJualEvec 1, vec )F
9vec less>hanJualEivec 1, ivec )F
9vec less>hanJualEuvec 1, uvec )F
Returns the co.onent8wise co.are o# * PR ,.
9vec greater>hanEvec 1, vec )F
9vec greater>hanEivec 1, ivec )F
9vec greater>hanEuvec 1, uvec )F
Returns the co.onent8wise co.are o# * Q ,.
9vec greater>hanJualEvec 1, vec )F
9vec greater>hanJualEivec 1, ivec )F
9vec greater>hanJualEuvec 1, uvec )F
Returns the co.onent8wise co.are o# * QR ,.
9vec eualEvec 1, vec )F
9vec eualEivec 1, ivec )F
9vec eualEuvec 1, uvec )F
9vec eualE9vec 1, 9vec )F
9vec notJualEvec 1, vec )F
9vec notJualEivec 1, ivec )F
9vec notJualEuvec 1, uvec )F
9vec notJualE9vec 1, 9vec )F
Returns the co.onent8wise co.are o# * RR ,.
Returns the co.onent8wise co.are o# * LR ,.
9ool anCE9vec 1F Returns true i# an) co.onent o# * is true.
116
Bui%t+in ,unctions
S#nta* )escription
9ool allE9vec 1F Returns true onl) i# all co.onents o# * are true.
9vec notE9vec 1F Returns the co.onent8wise logical co.leent o# *.
117
Bui%t+in ,unctions
3.3 Integer ,unctions
-hese all o.erate co.onent8wise. -he descri.tion is .er co.onent. -he notation Ya, +Z eans the set
o# 9its #ro 9it8nu9er a through 9it8nu9er +, inclusive. -he lowest8order 9it is 9it *.
S#nta* )escription
gen6-).e uaddCarrC Egen6-).e *,
gen6-).e ,,
out gen6-).e carr,F
Adds &!89it unsigned integer * and ,, returning the su
odulo !
&!
. -he value carr, is set to * i# the su was
less than !
&!
, or to 1 otherwise.
gen6-).e usubGorrow Egen6-).e *,
gen6-).e ,,
out gen6-).e +orrowF
(u9tracts the &!89it unsigned integer , #ro *, returning
the di##erence i# non8negative, or !
&!
.lus the di##erence
otherwise. -he value +orrow is set to * i# * G= ,, or to
1 otherwise.
void umulJxtended Egen6-).e *,
gen6-).e ,,
out gen6-).e ms+,
out gen6-).e ls+F
void imulJxtended EgenI-).e *,
genI-).e ,,
out genI-).e ms+,
out genI-).e ls+F
:ulti.lies &!89it integers * and ,, .roducing a '%89it
result. -he &! least8signi#icant 9its are returned in ls+.
-he &! ost8signi#icant 9its are returned in ms+.
genI-).e bitfieldJxtract EgenI-).e value,
int offset, int +itsF
gen6-).e bitfieldJxtract Egen6-).e value,
int offset, int +itsF
E1tracts 9its Yoffset, offset J +its - 1Z #ro value,
returning the in the least signi#icant 9its o# the result.
3or unsigned data t).es, the ost signi#icant 9its o# the
result will 9e set to ?ero. 3or signed data t).es, the
ost signi#icant 9its will 9e set to the value o# 9it offset
J +ase H 1.
I# +its is ?ero, the result will 9e ?ero. -he result will 9e
unde#ined i# offset or +its is negative, or i# the su o#
offset and +its is greater than the nu9er o# 9its used
to store the o.erand.
11
Bui%t+in ,unctions
S#nta* )escription
genI-).e bitfieldMnsert EgenI-).e +ase,
genI-).e insert,
int offset, int +itsF
gen6-).e bitfieldMnsert Egen6-).e +ase,
gen6-).e insert,
int offset, int +itsF
Returns the insertion the +its least8signi#icant 9its o#
insert into +ase.
-he result will have 9its Yoffset, offset J +its - 1Z taken
#ro 9its Y*, +its H 1Z o# insert, and all other 9its taken
directl) #ro the corres.onding 9its o# +ase. I# +its is
?ero, the result will si.l) 9e +ase. -he result will 9e
unde#ined i# offset or +its is negative, or i# the su o#
offset and +its is greater than the nu9er o# 9its used to
store the o.erand.
genI-).e bitfieldFeverse EgenI-).e valueF
gen6-).e bitfieldFeverse Egen6-).e valueF
Returns the reversal o# the 9its o# value. -he 9it
nu9ered n o# the result will 9e taken #ro 9it E+its - 1F
- n o# value, where +its is the total nu9er o# 9its used
to re.resent value.
genI-).e bitCount EgenI-).e valueF
genI-).e bitCount Egen6-).e valueF
Returns the nu9er o# 9its set to 1 in the 9inar)
re.resentation o# value.
genI-).e findASG EgenI-).e valueF
genI-).e findASG Egen6-).e valueF
Returns the 9it nu9er o# the least signi#icant 9it set to
1 in the 9inar) re.resentation o# value. I# value is ?ero,
81will 9e returned.
genI-).e findHSG EgenI-).e valueF
genI-).e findHSG Egen6-).e valueF
Returns the 9it nu9er o# the ost signi#icant 9it in the
9inar) re.resentation o# value.
3or .ositive integers, the result will 9e the 9it nu9er o#
the ost signi#icant 9it set to 1. 3or negative integers,
the result will 9e the 9it nu9er o# the ost signi#icant
9it set to *. 3or a value o# ?ero or negative one, 81 will
9e returned.
11!
Bui%t+in ,unctions
3.8 Te*ture ,unctions
-e1ture looku. #unctions are availa9le in all shading stages. ,owever, autoatic level o# detail is
co.uted onl) #or #ragent shaders. +ther shaders o.erate as though the 9ase level o# detail were
co.uted as ?ero. -he #unctions in the ta9le 9elow .rovide access to te1tures through sa.lers, as set u.
through the +.en/0 A2I. -e1ture .ro.erties such as si?e, .i1el #orat, nu9er o# diensions, #iltering
ethod, nu9er o# i.8a. levels, de.th co.arison, and so on are also de#ined 9) +.en/0 A2I calls.
(uch .ro.erties are taken into account as the te1ture is accessed via the 9uilt8in #unctions de#ined 9elow.
-e1ture data can 9e stored 9) the /0 as #loating .oint, unsigned norali?ed integer, unsigned integer or
signed integer data. -his is deterined 9) the t).e o# the internal #orat o# the te1ture. -e1ture looku.s
on unsigned norali?ed integer and #loating .oint data return #loating .oint values in the range Y*, 1Z.
-e1ture looku. #unctions are .rovided that can return their result as #loating .oint, unsigned integer or
signed integer, de.ending on the sa.ler t).e .assed to the looku. #unction. "are ust 9e taken to use
the right sa.ler t).e #or te1ture access. -he #ollowing ta9le lists the su..orted co9inations o# sa.ler
t).es and te1ture internal #orats. Blank entries are unsu..orted. Doing a te1ture looku. will return
unde#ined values #or unsu..orted co9inations.
Internal -e1ture 3orat
3loating 2oint
(a.ler -).es
(igned Integer
(a.ler -).es
6nsigned Integer
(a.ler -).es
3loating .oint (u..orted
7orali?ed Integer (u..orted
(igned Integer (u..orted
6nsigned Integer (u..orted
I# an integer sa.ler t).e is used, the result o# a te1ture looku. is an ivecB. I# an unsigned integer sa.ler
t).e is used, the result o# a te1ture looku. is a uvecB. I# a #loating .oint sa.ler t).e is used, the result o#
a te1ture looku. is a vecB, where each co.onent is in the range Y*, 1Z.
In the .rotot).es 9elow, the BgC in the return t).e Bgvec4C is used as a .laceholder #or nothing, BiC, or BuC
aking a return t).e o# vecB, ivecB, or uvecB. In these cases, the sa.ler arguent t).e also starts with
BgC, indicating the sae su9stitution done on the return t).eI it is either a #loating .oint, signed integer, or
unsigned integer sa.ler, atching the 9asic t).e o# the return t).e, as descri9ed a9ove.
3or shadow #ors Ethe sa.ler .araeter is a shadow8t).eF, a de.th co.arison looku. on the de.th
te1ture 9ound to sam%ler is done as descri9ed in section &.5.1' B-e1ture "o.arison :odesC o# the
+.en/0 /ra.hics ()ste (.eci#ication. (ee the ta9le 9elow #or which co.onent s.eci#ies Dref. -he
te1ture 9ound to sam%ler ust 9e a de.th te1ture, or results are unde#ined. I# a non8shadow te1ture call is
ade to a sa.ler that re.resents a de.th te1ture with de.th co.arisons turned on, then results are
unde#ined. I# a shadow te1ture call is ade to a sa.ler that re.resents a de.th te1ture with de.th
co.arisons turned o##, then results are unde#ined. I# a shadow te1ture call is ade to a sa.ler that does
not re.resent a de.th te1ture, then results are unde#ined.
12"
Bui%t+in ,unctions
In all #unctions 9elow, the +ias .araeter is o.tional #or #ragent shaders. -he +ias .araeter is not
acce.ted in an) other shaders. 3or a #ragent shader, i# +ias is .resent, it is added to the i.licit level o#
detail .rior to .er#oring the te1ture access o.eration. 7o +ias or lo( .araeters #or rectangular te1tures,
ulti8sa.le te1tures, or te1ture 9u##ers are su..orted 9ecause i.8a.s are not allowed #or these t).es
o# te1tures.
-he i.licit level o# detail is selected as #ollows: 3or a te1ture that is not i.8a..ed, the te1ture is used
directl). I# it is i.8a..ed and running in a #ragent shader, the 0+D co.uted 9) the i.leentation
is used to do the te1ture looku.. I# it is i.8a..ed and running on the verte1 shader, then the 9ase
te1ture is used.
(oe te1ture #unctions Enon8BAodC and non8B@radC versionsF a) re=uire i.licit derivatives. I.licit
derivatives are unde#ined within non8uni#or control #low and #or non8#ragent8shader te1ture #etches.
3or Cube #ors, the direction o# ! is used to select which #ace to do a !8diensional te1ture looku. in, as
descri9ed in section &.5.1* B"u9e :a. -e1ture (electionC in the +.en/0 /ra.hics ()ste (.eci#ication.
3or ArraC #ors, the arra) la)er used will 9e
ma* *, min ( 1, floorla,er*.$
where ( is the de.th o# the te1ture arra) and la,er coes #ro the co.onent indicated in the ta9les
9elow.
3.8.1 Te*ture 9uer# ,unctions
-he textureSi"e #unctions =uer) the diensions o# a s.eci#ic te1ture level #or a sa.ler.
-he textureRuerCAod #unctions are availa9le onl) in a #ragent shader. -he) take the co.onents o# !
and co.ute the level o# detail in#oration that the te1ture .i.e would use to access that te1ture through a
noral te1ture looku.. -he level o# detail IJ Ee=uation &.15 in the +.en/0 /ra.hics ()ste
(.eci#icationF is o9tained a#ter an) 0+D 9ias, 9ut .rior to cla.ing to Y-EX-6RE>:I7>0+D,
-EX-6RE>:AX>0+DZ. -he i.a. arra)EsF that would 9e accessed are also co.uted. I# a single
level o# detail would 9e accessed, the level8o#8detail nu9er relative to the 9ase level is returned. I#
ulti.le levels o# detail would 9e accessed, a #loating8.oint nu9er 9etween the two levels is returned,
with the #ractional .art e=ual to the #ractional .art o# the co.uted and cla.ed level o# detail. -he
algorith used is given 9) the #ollowing .seudo8code:
121
Bui%t+in ,unctions
float Eompute>%%essedLod#float %omputedLod)
)
-- Elamp t.e %omputed LO a%%ording to t.e texture LO %lamps+
if #%omputedLod 0 TEPTQRE_?IN_LO) %omputedLod * TEPTQRE_?IN_LO,
if #%omputedLod M TEPTQRE_?>P_LO) %omputedLod * TEPTQRE_?>P_LO,
-- Elamp t.e %omputed LO to t.e range of a%%essi$le levels+
if #%omputedLod 0 =)
%omputedLod * =+=,
if #%omputedLod M #float)
max>%%essi$leLevel) %omputedLod * #float) max>%%essi$leLevel,
-- Return a value a%%ording to t.e min filter+
if #TEPTQRE_?IN_FILTER is LINE>R or NE>REST) )
return =+=,
3 else if #TEPTQRE_?IN_FILTER is NE>REST_?I@?>@_NE>REST
or LINE>R_?I@?>@_NE>REST) )
return %eil#%omputedLod L =+<) 2 '+=,
3 else )
return %omputedLod,
3
3
-he value ma*Accessi+leLevel is the level nu9er o# the sallest accessi9le level o# the i.a. arra)
Ethe value 2 in section &.5.; B-e1ture :ini#icationC o# the +.en/0 /ra.hics ()ste (.eci#icationF inus
the 9ase level.
S#nta* )escription
int textureSi"e Egsa.ler1D sam%ler, int lo(F
ivec! textureSi"e Egsa.ler!D sam%ler, int lo(F
ivec& textureSi"e Egsa.ler&D sam%ler, int lo(F
ivec! textureSi"e Egsa.ler"u9e sam%ler, int lo(F
int textureSi"e Esa.ler1D(hadow sam%ler, int lo(F
ivec! textureSi"e Esa.ler!D(hadow sam%ler, int lo(F
ivec! textureSi"e Esa.ler"u9e(hadow sam%ler, int lo(F
ivec& textureSi"e Esa.ler"u9eArra) sam%ler, int lo(F
ivec& textureSi"e Esa.ler"u9eArra)(hadow sam%ler, int lo(F
ivec! textureSi"e Egsa.ler!DRect sam%lerF
ivec! textureSi"e Esa.ler!DRect(hadow sam%lerF
ivec! textureSi"e Egsa.ler1DArra) sam%ler, int lo(F
ivec& textureSi"e Egsa.ler!DArra) sam%ler, int lo(F
ivec! textureSi"e Esa.ler1DArra)(hadow sam%ler, int lo(F
ivec& textureSi"e Esa.ler!DArra)(hadow sam%ler, int lo(F
int textureSi"e Egsa.lerBu##er sam%lerF
ivec! textureSi"e Egsa.ler!D:( sam%lerF
ivec! textureSi"e Egsa.ler!D:(Arra) sam%lerF
Returns the diensions o# level
lo( Ei# .resentF #or the te1ture
9ound to sam%ler, as descri9ed
in section !.11.4 B(hader
E1ecutionC o# the +.en/0
/ra.hics ()ste (.eci#ication,
under B-e1ture (i?e <uer)C.
-he co.onents in the return
value are #illed in, in order, with
the width, height, de.th o# the
te1ture.
3or the arra) #ors, the last
co.onent o# the return value is
the nu9er o# la)ers in the
te1ture arra).
122
Bui%t+in ,unctions
S#nta* )escription
vec! textureRuerCAodEgsa.ler1D sam%ler, #loat !F
vec! textureRuerCAodEgsa.ler!D sam%ler, vec! !F
vec! textureRuerCAodEgsa.ler&D sam%ler, vec& !F
vec! textureRuerCAodEgsa.ler"u9e sam%ler, vec& !F
vec! textureRuerCAodEgsa.ler1DArra) sam%ler, #loat !F
vec! textureRuerCAodEgsa.ler!DArra) sam%ler, vec! !F
vec! textureRuerCAodEgsa.ler"u9eArra) sam%ler, vec& !F
vec! textureRuerCAodEsa.ler1D(hadow sam%ler, #loat !F
vec! textureRuerCAodEsa.ler!D(hadow sam%ler, vec! !F
vec! textureRuerCAodEsa.ler"u9e(hadow sam%ler, vec& !F
vec! textureRuerCAodEsa.ler1DArra)(hadow sam%ler, #loat !F
vec! textureRuerCAodEsa.ler!DArra)(hadow sam%ler, vec! !F
vec! textureRuerCAodEsa.ler"u9eArra)(hadow sam%ler, vec& !F
Returns the i.a. arra)EsF
that would 9e accessed in the *
co.onent o# the return value.
Returns the co.uted level o#
detail relative to the 9ase level
in the , co.onent o# the return
value.
I# called on an inco.lete
te1ture, the results are
unde#ined.
3.8.2 Te*el Loo0up ,unctions
S#nta* )escription
gvec% texture Egsa.ler1D sam%ler) #loat ! Y, #loat +iasZ F
gvec% texture Egsa.ler!D sam%ler, vec! ! Y, #loat +iasZ F
gvec% texture Egsa.ler&D sam%ler, vec& ! Y, #loat +iasZ F
gvec% texture Egsa.ler"u9e sam%ler, vec& ! Y, #loat +iasZ F
#loat texture Esa.ler1D(hadow sam%ler) vec& ! Y, #loat +iasZ F
#loat texture Esa.ler!D(hadow sam%ler) vec& ! Y, #loat +iasZ F
#loat texture Esa.ler"u9e(hadow sam%ler) vec% ! Y, #loat +iasZ F
gvec% texture Egsa.ler1DArra) sam%ler) vec! ! Y, #loat +iasZ F
gvec% texture Egsa.ler!DArra) sam%ler, vec& ! Y, #loat +iasZ F
gvec% texture Egsa.ler"u9eArra) sam%ler, vec% ! Y, #loat +iasZ F
#loat texture Esa.ler1DArra)(hadow sam%ler) vec& !
Y, #loat +iasZ F
#loat texture Esa.ler!DArra)(hadow sam%ler) vec% !F
gvec% texture Egsa.ler!DRect sam%ler, vec! !F
#loat texture Esa.ler!DRect(hadow sam%ler, vec& !F
#loat texture Egsa.ler"u9eArra)(hadow sam%ler, vec% !,
#loat com%areF
6se the te1ture coordinate ! to
do a te1ture looku. in the
te1ture currentl) 9ound to
sam%ler.
3or shadow #ors: @hen
com%are is .resent, it is used as
Dref and the arra) la)er coes
#ro !.w. @hen com%are is not
.resent, the last co.onent o#
! is used as Dref and the arra)
la)er coes #ro the second to
last co.onent o# !. E-he
second co.onent o# ! is
unused #or 1? shadow looku.s.F
3or non8shadow #ors: the arra)
la)er coes #ro the last
co.onent o# !.
123
Bui%t+in ,unctions
S#nta* )escription
gvec% textureQroI Egsa.ler1D sam%ler, vec! ! Y, #loat +iasZ F
gvec% textureQroI Egsa.ler1D sam%ler, vec% ! Y, #loat +iasZ F
gvec% textureQroI Egsa.ler!D sam%ler, vec& ! Y, #loat +iasZ F
gvec% textureQroI Egsa.ler!D sam%ler, vec% ! Y, #loat +iasZ F
gvec% textureQroI Egsa.ler&D sam%ler, vec% ! Y, #loat +iasZ F
#loat textureQroI Esa.ler1D(hadow sam%ler) vec% !
Y, #loat +iasZ F
#loat textureQroI Esa.ler!D(hadow sam%ler) vec% !
Y, #loat +iasZ F
gvec% textureQroI Egsa.ler!DRect sam%ler, vec& !F
gvec% textureQroI Egsa.ler!DRect sam%ler, vec% !F
#loat textureQroI Esa.ler!DRect(hadow sam%ler, vec% !F
Do a te1ture looku. with
.roDection. -he te1ture
coordinates consued #ro !,
not including the last co.onent
o# !, are divided 9) the last
co.onent o# !. -he resulting
&
rd
co.onent o# ! in the
shadow #ors is used as Dref.
A#ter these values are co.uted,
te1ture looku. .roceeds as in
texture.
gvec% textureAod Egsa.ler1D sam%ler, #loat !, #loat lo(F
gvec% textureAod Egsa.ler!D sam%ler, vec! !, #loat lo(F
gvec% textureAod Egsa.ler&D sam%ler, vec& !, #loat lo(F
gvec% textureAod Egsa.ler"u9e sam%ler, vec& !, #loat lo(F
#loat textureAod Esa.ler1D(hadow sam%ler) vec& !, #loat lo(F
#loat textureAod Esa.ler!D(hadow sam%ler) vec& !, #loat lo(F
gvec% textureAod Egsa.ler1DArra) sam%ler, vec! !, #loat lo(F
gvec% textureAod Egsa.ler!DArra) sam%ler, vec& !, #loat lo(F
#loat textureAod Esa.ler1DArra)(hadow sam%ler) vec& !,
#loat lo(F
gvec% textureAod Egsa.ler"u9eArra) sam%ler, vec% !, #loat lo(F
Do a te1ture looku. as in
texture 9ut with e1.licit 0+DI
lo( s.eci#ies I+ase and sets the
.artial derivatives as #ollows.
E(ee section &.5.11 B-e1ture
:ini#icationC and e=uation &.14
in the +.en/0 /ra.hics ()ste
(.eci#ication.F
u
*
= *
v
*
= *
w
*
= *
u
,
= *
v
,
= *
w
,
= *
124
Bui%t+in ,unctions
S#nta* )escription
gvec% textureOffset Egsa.ler1D sam%ler) #loat !)
int offset Y, #loat +iasZ F
gvec% textureOffset Egsa.ler!D sam%ler, vec! !,
ivec! offset Y, #loat +iasZ F
gvec% textureOffset Egsa.ler&D sam%ler, vec& !,
ivec& offset Y, #loat +iasZ F
gvec% textureOffset Egsa.ler!DRect sam%ler, vec! !,
ivec! offset F
#loat textureOffset Esa.ler!DRect(hadow sam%ler, vec& !,
ivec! offset F
#loat textureOffset Esa.ler1D(hadow sam%ler) vec& !,
int offset Y, #loat +iasZ F
#loat textureOffset Esa.ler!D(hadow sam%ler) vec& !,
ivec! offset Y, #loat +iasZ F
gvec% textureOffset Egsa.ler1DArra) sam%ler) vec! !)
int offset Y, #loat +iasZ F
gvec% textureOffset Egsa.ler!DArra) sam%ler, vec& !,
ivec! offset Y, #loat +iasZ F
#loat textureOffset Esa.ler1DArra)(hadow sam%ler) vec& !,
int offset Y, #loat +iasZ F
Do a te1ture looku. as in
texture 9ut with offset added to
the Eu,v,wF te1el coordinates
9e#ore looking u. each te1el.
-he o##set value ust 9e a
constant e1.ression. A liited
range o# o##set values are
su..ortedI the iniu and
a1iu o##set values are
i.leentation8de.endent and
given 9)
:I7>2R+/RA:>-EXE0>+33(E- and
:AX>2R+/RA:>-EXE0>+33(E-,
res.ectivel).
7ote that offset does not a..l)
to the la)er coordinate #or
te1ture arra)s. -his is e1.lained
in detail in section &.5.11
B-e1ture :ini#icationC o# the
+.en/0 /ra.hics ()ste
(.eci#ication, where offset is

u
)
v
)
w
. 7ote that te1el
o##sets are also not su..orted
#or cu9e a.s.
gvec% texelKetch Egsa.ler1D sam%ler, int !, int lo(F
gvec% texelKetch Egsa.ler!D sam%ler, ivec! !, int lo(F
gvec% texelKetch Egsa.ler&D sam%ler, ivec& !, int lo(F
gvec% texelKetch Egsa.ler!DRect sam%ler, ivec! !F
gvec% texelKetch Egsa.ler1DArra) sam%ler, ivec! !, int lo(F
gvec% texelKetch Egsa.ler!DArra) sam%ler, ivec& !, int lo(F
gvec% texelKetch Egsa.lerBu##er sam%ler, int !F
gvec% texelKetch Egsa.ler!D:( sam%ler, ivec! !, int sam%leF
gvec% texelKetch Egsa.ler!D:(Arra) sam%ler, ivec& !,
int sam%leF
6se integer te1ture coordinate !
to looku. a single te1el #ro
sam%ler. -he arra) la)er coes
#ro the last co.onent o# ! #or
the arra) #ors. -he level8o#8
detail lo( Ei# .resentF is as
descri9ed in sections !.11.5
B(hader E1ecutionC under -e1el
3etches and &.5 B-e1turingC o#
the +.en/0 /ra.hics ()ste
(.eci#ication.
125
Bui%t+in ,unctions
S#nta* )escription
gvec% texelKetchOffset Egsa.ler1D sam%ler, int !, int lo(,
int offsetF
gvec% texelKetchOffset Egsa.ler!D sam%ler, ivec! !, int lo(,
ivec! offsetF
gvec% texelKetchOffset Egsa.ler&D sam%ler, ivec& !, int lo(,
ivec& offsetF
gvec% texelKetchOffset Egsa.ler!DRect sam%ler, ivec! !,
ivec! offsetF
gvec% texelKetchOffset Egsa.ler1DArra) sam%ler, ivec! !, int lo(,
int offsetF
gvec% texelKetchOffset Egsa.ler!DArra) sam%ler, ivec& !, int lo(,
ivec! offsetF
3etch a single te1el as in
texelKetch o##set 9) offset as
descri9ed in textureOffset.
gvec% textureQroIOffset Egsa.ler1D sam%ler) vec! !)
int offset Y, #loat +iasZ F
gvec% textureQroIOffset Egsa.ler1D sam%ler) vec% !)
int offset Y, #loat +iasZ F
gvec% textureQroIOffset Egsa.ler!D sam%ler, vec& !,
ivec! offset Y, #loat +iasZ F
gvec% textureQroIOffset Egsa.ler!D sam%ler, vec% !,
ivec! offset Y, #loat +iasZ F
gvec% textureQroIOffset Egsa.ler&D sam%ler, vec% !,
ivec& offset Y, #loat +iasZ F
gvec% textureQroIOffset Egsa.ler!DRect sam%ler, vec& !,
ivec! offset F
gvec% textureQroIOffset Egsa.ler!DRect sam%ler, vec% !,
ivec! offset F
#loat textureQroIOffset Esa.ler!DRect(hadow sam%ler, vec% !,
ivec! offset F
#loat textureQroIOffset Esa.ler1D(hadow sam%ler) vec% !,
int offset Y, #loat +iasZ F
#loat textureQroIOffset Esa.ler!D(hadow sam%ler) vec% !,
ivec! offset Y, #loat +iasZ F
Do a .roDective te1ture looku.
as descri9ed in textureQroI
o##set 9) offset as descri9ed in
textureOffset.
126
Bui%t+in ,unctions
S#nta* )escription
gvec% textureAodOffset Egsa.ler1D sam%ler) #loat !,
#loat lo(, int offsetF
gvec% textureAodOffset Egsa.ler!D sam%ler, vec! !,
#loat lo(, ivec! offsetF
gvec% textureAodOffset Egsa.ler&D sam%ler, vec& !,
#loat lo(, ivec& offsetF
#loat textureAodOffset Esa.ler1D(hadow sam%ler) vec& !,
#loat lo(, int offsetF
#loat textureAodOffset Esa.ler!D(hadow sam%ler) vec& !,
#loat lo(, ivec! offsetF
gvec% textureAodOffset Egsa.ler1DArra) sam%ler) vec! !,
#loat lo(, int offsetF
gvec% textureAodOffset Egsa.ler!DArra) sam%ler, vec& !,
#loat lo(, ivec! offsetF
#loat textureAodOffset Esa.ler1DArra)(hadow sam%ler) vec& !,
#loat lo(, int offsetF
Do an o##set te1ture looku. with
e1.licit 0+D. (ee textureAod
and textureOffset.
gvec% textureQroIAod Egsa.ler1D sam%ler, vec! !, #loat lo(F
gvec% textureQroIAod Egsa.ler1D sam%ler, vec% !, #loat lo(F
gvec% textureQroIAod Egsa.ler!D sam%ler, vec& !, #loat lo(F
gvec% textureQroIAod Egsa.ler!D sam%ler, vec% !, #loat lo(F
gvec% textureQroIAod Egsa.ler&D sam%ler, vec% !, #loat lo(F
#loat textureQroIAod Esa.ler1D(hadow sam%ler) vec% !, #loat lo(F
#loat textureQroIAod Esa.ler!D(hadow sam%ler) vec% !) #loat lo(F
Do a .roDective te1ture looku.
with e1.licit 0+D. (ee
textureQroI and textureAod.
gvec% textureQroIAodOffset Egsa.ler1D sam%ler) vec! !,
#loat lo(, int offsetF
gvec% textureQroIAodOffset Egsa.ler1D sam%ler) vec% !,
#loat lo(, int offsetF
gvec% textureQroIAodOffset Egsa.ler!D sam%ler, vec& !,
#loat lo(, ivec! offsetF
gvec% textureQroIAodOffset Egsa.ler!D sam%ler, vec% !,
#loat lo(, ivec! offsetF
gvec% textureQroIAodOffset Egsa.ler&D sam%ler, vec% !,
#loat lo(, ivec& offsetF
#loat textureQroIAodOffset Esa.ler1D(hadow sam%ler) vec% !,
#loat lo(, int offsetF
#loat textureQroIAodOffset Esa.ler!D(hadow sam%ler) vec% !,
#loat lo(, ivec! offsetF
Do an o##set .roDective te1ture
looku. with e1.licit 0+D. (ee
textureQroI, textureAod, and
textureOffset.
127
Bui%t+in ,unctions
S#nta* )escription
gvec% texture@rad Egsa.ler1D sam%ler) #loat !,
#loat (!(*, #loat (!(,F
gvec% texture@rad Egsa.ler!D sam%ler) vec! !,
vec! (!(*, vec! (!(,F
gvec% texture@rad Egsa.ler&D sam%ler) vec& !,
vec& (!(*, vec& (!(,F
gvec% texture@rad Egsa.ler"u9e sam%ler, vec& !,
vec& (!(*, vec& (!(,F
gvec% texture@rad Egsa.ler!DRect sam%ler, vec! !,
vec! (!(*, vec! (!(,F
#loat texture@rad Esa.ler!DRect(hadow sam%ler, vec& !,
vec! (!(*, vec! (!(,F
#loat texture@rad Esa.ler1D(hadow sam%ler, vec& !,
#loat (!(*, #loat (!(,F
#loat texture@rad Esa.ler!D(hadow sam%ler, vec& !,
vec! (!(*, vec! (!(,F
#loat texture@rad Esa.ler"u9e(hadow sam%ler, vec% !,
vec& (!(*, vec& (!(,F
gvec% texture@rad Egsa.ler1DArra) sam%ler) vec! !,
#loat (!(*, #loat (!(,F
gvec% texture@rad Egsa.ler!DArra) sam%ler) vec& !,
vec! (!(*, vec! (!(,F
#loat texture@rad Esa.ler1DArra)(hadow sam%ler, vec& !,
#loat (!(*, #loat (!(,F
#loat texture@rad Esa.ler!DArra)(hadow sam%ler, vec% !,
vec! (!(*, vec! (!(,F
gvec% texture@rad Egsa.ler"u9eArra) sam%ler, vec% !,
vec& (!(*, vec& (!(,F
Do a te1ture looku. as in
texture 9ut with e1.licit
gradients. -he .artial
derivatives o# ! are with res.ect
to window 1 and window ). (et
s
*
=
{
!
*
#or a 1D te1ture
!.s
*
otherwise
s
,
=
{
!
,
#or a 1D te1ture
!.s
,
otherwise
t
*
=
{
*.* #or a 1D te1ture
!.t
*
otherwise
t
,
=
{
*.* #or a 1D te1ture
!.t
,
otherwise
r
*
=
{
*.* #or 1D or !D
!.%
*
cu9e, other
r
,
=
{
*.* #or 1D or !D
!.%
,
cu9e, other
3or the cu9e version, the .artial
derivatives o# ! are assued to
9e in the coordinate s)ste used
9e#ore te1ture coordinates are
.roDected onto the a..ro.riate
cu9e #ace.
12
Bui%t+in ,unctions
S#nta* )escription
gvec% texture@radOffset Egsa.ler1D sam%ler) #loat !)
#loat (!(*, #loat (!(,) int offsetF
gvec% texture@radOffset Egsa.ler!D sam%ler, vec! !,
vec! (!(*, vec! (!(,) ivec! offsetF
gvec% texture@radOffset Egsa.ler&D sam%ler, vec& !,
vec& (!(*, vec& (!(,) ivec& offsetF
gvec% texture@radOffset Egsa.ler!DRect sam%ler, vec! !,
vec! (!(*, vec! (!(,) ivec! offsetF
#loat texture@radOffset Esa.ler!DRect(hadow sam%ler, vec& !,
vec! (!(*, vec! (!(,) ivec! offsetF
#loat texture@radOffset Esa.ler1D(hadow sam%ler) vec& !,
#loat (!(*, #loat (!(,) int offset F
#loat texture@radOffset Esa.ler!D(hadow sam%ler) vec& !,
vec! (!(*, vec! (!(,) ivec! offsetF
gvec% texture@radOffset Egsa.ler1DArra) sam%ler) vec! !)
#loat (!(*, #loat (!(,) int offsetF
gvec% texture@radOffset Egsa.ler!DArra) sam%ler, vec& !,
vec! (!(*, vec! (!(,) ivec! offsetF
#loat texture@radOffset Esa.ler1DArra)(hadow sam%ler) vec&
!,
#loat (!(*, #loat (!(,) int offsetF
#loat texture@radOffset Esa.ler!DArra)(hadow sam%ler) vec%
!,
vec! (!(*, vec! (!(,) ivec! offsetF
Do a te1ture looku. with 9oth
e1.licit gradient and o##set, as
descri9ed in texture@rad and
textureOffset.
gvec% textureQroI@rad Egsa.ler1D sam%ler) vec! !,
#loat (!(*, #loat (!(,F
gvec% textureQroI@rad Egsa.ler1D sam%ler) vec% !,
#loat (!(*, #loat (!(,F
gvec% textureQroI@rad Egsa.ler!D sam%ler) vec& !,
vec! (!(*, vec! (!(,F
gvec% textureQroI@rad Egsa.ler!D sam%ler) vec% !,
vec! (!(*, vec! (!(,F
gvec% textureQroI@rad Egsa.ler&D sam%ler) vec% !,
vec& (!(*, vec& (!(,F
gvec% textureQroI@rad Egsa.ler!DRect sam%ler) vec& !,
vec! (!(*, vec! (!(,F
gvec% textureQroI@rad Egsa.ler!DRect sam%ler) vec% !,
vec! (!(*, vec! (!(,F
#loat textureQroI@rad Esa.ler!DRect(hadow sam%ler) vec% !,
vec! (!(*, vec! (!(,F
#loat textureQroI@rad Esa.ler1D(hadow sam%ler, vec% !,
#loat (!(*, #loat (!(,F
#loat textureQroI@rad Esa.ler!D(hadow sam%ler, vec% !,
vec! (!(*, vec! (!(,F
Do a te1ture looku. 9oth
.roDectivel), as descri9ed in
textureQroI, and with e1.licit
gradient as descri9ed in
texture@rad. -he .artial
derivatives (!(* and (!(, are
assued to 9e alread) .roDected.
12!
Bui%t+in ,unctions
S#nta* )escription
gvec% textureQroI@radOffset Egsa.ler1D sam%ler) vec! !,
#loat (!(*, #loat (!(,, int offsetF
gvec% textureQroI@radOffset Egsa.ler1D sam%ler) vec% !,
#loat (!(*, #loat (!(,, int offsetF
gvec% textureQroI@radOffset Egsa.ler!D sam%ler) vec& !,
vec! (!(*, vec! (!(,, vec! offsetF
gvec% textureQroI@radOffset Egsa.ler!D sam%ler) vec% !,
vec! (!(*, vec! (!(,, vec! offsetF
gvec% textureQroI@radOffset Egsa.ler!DRect sam%ler, vec& !,
vec! (!(*, vec! (!(,) ivec! offsetF
gvec% textureQroI@radOffset Egsa.ler!DRect sam%ler, vec% !,
vec! (!(*, vec! (!(,) ivec! offsetF
#loat textureQroI@radOffset Esa.ler!DRect(hadow sam%ler,
vec% !,
vec! (!(*, vec! (!(,) ivec! offsetF
gvec% textureQroI@radOffset Egsa.ler&D sam%ler) vec% !,
vec& (!(*, vec& (!(,, vec& offsetF
#loat textureQroI@radOffset Esa.ler1D(hadow sam%ler, vec% !,
#loat (!(*, #loat (!(,, int offsetF
#loat textureQroI@radOffset Esa.ler!D(hadow sam%ler, vec% !,
vec! (!(*, vec! (!(,, vec! offsetF
Do a te1ture looku. .roDectivel)
and with e1.licit gradient as
descri9ed in textureQroI@rad,
as well as with o##set, as
descri9ed in textureOffset.
3.8.! Te*ture Gather Instructions
-he te1ture gather #unctions take co.onents o# a single #loating8.oint vector o.erand as a te1ture
coordinate, deterine a set o# #our te1els to sa.le #ro the 9ase level o# detail o# the s.eci#ied te1ture
iage, and return one co.onent #ro each te1el in a #our8co.onent result vector.
@hen .er#oring a te1ture gather o.eration, the ini#ication and agni#ication #ilters are ignored, and
the rules #or 0I7EAR #iltering in the +.en/0 (.eci#ication are a..lied to the 9ase level o# the te1ture
iage to identi#) the #our te1els i0:1) i1:1) i1:0) and i0:0. -he te1els are then converted to te1ture source
colors ER
s
, &
s
, ;
s
, A
s
F according to -a9le &.!*, #ollowed 9) a..lication o# the te1ture swi??le as descri9ed
in section &.;.! B(hader E1ecutionC o# the +.en/0 /ra.hics ()ste (.eci#ication. A #our8co.onent
vector is asse9led 9) taking the selected co.onent #ro each o# the swi??led te1ture source colors in
the order Ei0:1) i1:1) i1:0) i0:0F.
3or te1ture gather #unctions using a shadow sa.ler t).e, each o# the #our te1el looku.s .er#ors a de.th
co.arison against the de.th re#erence value .assed in ErefKF, and returns the result o# that co.arison in
the a..ro.riate co.onent o# the result vector.
As with other te1ture looku. #unctions, the results o# a te1ture gather are unde#ined #or shadow sa.lers i#
the te1ture re#erenced is not a de.th te1ture or has de.th co.arisons disa9ledI or #or non8shadow
sa.lers i# the te1ture re#erenced is a de.th te1ture with de.th co.arisons ena9led.
13"
Bui%t+in ,unctions
S#nta* )escription
gvec% texture@atherEgsa.ler!D sam%ler, vec! !
Y, int com%ZF
gvec% texture@atherEgsa.ler!DArra) sam%ler,
vec& ! Y, int com%ZF
gvec% texture@atherEgsa.ler"u9e sam%ler,
vec& ! Y, int com%ZF
gvec% texture@atherEgsa.ler"u9eArra) sam%ler,
vec% !Y, int com%ZF
gvec% texture@atherEgsa.ler!DRect sam%ler,
vec& !Y, int com%ZF
vec% texture@atherEsa.ler!D(hadow sam%ler,
vec! !, #loat refKF
vec% texture@atherEsa.ler!DArra)(hadow sam%ler,
vec& !, #loat refKF
vec% texture@atherEsa.ler"u9e(hadow sam%ler,
vec& !, #loat refKF
vec% texture@atherE
sa.ler"u9eArra)(hadow sam%ler,
vec% !, #loat refKFI
vec% texture@atherEsa.ler!DRect(hadow sam%ler,
vec! !, #loat refKFI
Returns the value
vec%E(a.le>i*>D1E!, 9aseF.com%,
(a.le>i1>D1E!, 9aseF.com%,
(a.le>i1>D*E!, 9aseF.com%,
(a.le>i*>D*E!, 9aseF.com%F
I# s.eci#ied, the value o# com% ust 9e a
constant integer e1.ression with a value o# *,
1, !, or &, identi#)ing the *, ,, 1, or w
co.onent o# the #our8co.onent vector
looku. result #or each te1el, res.ectivel). I#
com% is not s.eci#ied, it is treated as *,
selecting the * co.onent o# each te1el to
generate the result.
gvec% texture@atherOffsetEgsa.ler!D sam%ler,
vec! !, ivec! offset
Y, int com%ZF
gvec% texture@atherOffsetEgsa.ler!DArra) sam%ler,
vec& !, ivec! offset
Y, int com%ZF
gvec% texture@atherOffsetEgsa.ler!DRect sam%ler)
vec& !, ivec! offset
Y, int com%ZF
vec% texture@atherOffsetE
sa.ler!D(hadow sam%ler,
vec! !, #loat refK, ivec! offsetF
vec% texture@atherOffsetE
sa.ler!DArra)(hadow sam%ler,
vec& !, #loat refK, ivec! offsetF
vec% texture@atherOffsetE
sa.ler!DRect(hadow sam%ler,
vec! !, #loat refK, ivec! offsetF
2er#or a te1ture gather o.eration as in
texture@ather 9) offset as descri9ed in
textureOffset e1ce.t that the
i.leentation8de.endent iniu and
a1iu o##set values are given 9)
:I7>2R+/RA:>-EX-6RE>/A-,ER>+33(E-
and
:AX>2R+/RA:>-EX-6RE>/A-,ER>+33(E-,
res.ectivel).
131
Bui%t+in ,unctions
S#nta* )escription
gvec% texture@atherOffsetsE
gsa.ler!D sam%ler,
vec! !, ivec! offsetY%Z
Y, int com%ZF
gvec% texture@atherOffsetsE
gsa.ler!DArra) sam%ler,
vec& !, ivec! offsetY%Z
Y, int com%ZF
gvec% texture@atherOffsetsE
gsa.ler!DRect sam%ler)
vec& !, ivec! offsetY%Z
Y, int com%ZF
vec% texture@atherOffsetsE
sa.ler!D(hadow sam%ler,
vec! !, #loat refK, ivec! offsetY%ZF
vec% texture@atherOffsetsE
sa.ler!DArra)(hadow sam%ler,
vec& !, #loat refK, ivec! offsetY%ZF
vec% texture@atherOffsetsE
sa.ler!DRect(hadow sam%ler,
vec! !, #loat refK, ivec! offsetY%ZF
+.erate identicall) to texture@atherOffset
e1ce.t that offsets is used to deterine the
location o# the #our te1els to sa.le. Each
o# the #our te1els is o9tained 9) a..l)ing the
corres.onding o##set in offsets as a Eu) vF
coordinate o##set to !, identi#)ing the #our8
te1el 0I7EAR #oot.rint, and then selecting
the te1el i0:0 o# that #oot.rint. -he s.eci#ied
values in offsets ust 9e set with constant
integral e1.ressions.
132
Bui%t+in ,unctions
3.8. The follo&ing te*ture functions are deprecated.
S#nta* <deprecated= )escription <deprecated=
vec% texture1? Esa.ler1D sam%ler)
#loat coor( Y, #loat +iasZ F
vec% texture1?QroI Esa.ler1D sam%ler,
vec! coor( Y, #loat +iasZ F
vec% texture1?QroI Esa.ler1D sam%ler,
vec% coor( Y, #loat +iasZ F
vec% texture1?Aod Esa.ler1D sam%ler,
#loat coor(, #loat lo(F
vec% texture1?QroIAod Esa.ler1D sam%ler,
vec! coor(, #loat lo(F
vec% texture1?QroIAod Esa.ler1D sam%ler,
vec% coor(, #loat lo(F
De.recated. (ee corres.onding signature
a9ove without B1DC in the nae.
vec% textureD? Esa.ler!D sam%ler,
vec! coor( Y, #loat +iasZ F
vec% textureD?QroI Esa.ler!D sam%ler,
vec& coor( Y, #loat +iasZ F
vec% textureD?QroI Esa.ler!D sam%ler,
vec% coor( Y, #loat +iasZ F
vec% textureD?Aod Esa.ler!D sam%ler,
vec! coor(, #loat lo(F
vec% textureD?QroIAod Esa.ler!D sam%ler,
vec& coor(, #loat lo(F
vec% textureD?QroIAod Esa.ler!D sam%ler,
vec% coor(, #loat lo(F
De.recated. (ee corres.onding signature
a9ove without B!DC in the nae.
vec% textureE? Esa.ler&D sam%ler,
vec& coor( Y, #loat +iasZ F
vec% textureE?QroI Esa.ler&D sam%ler,
vec% coor( Y, #loat +iasZ F
vec% textureE?Aod Esa.ler&D sam%ler,
vec& coor(, #loat lo(F
vec% textureE?QroIAod Esa.ler&D sam%ler,
vec% coor(, #loat lo(F
De.recated. (ee corres.onding signature
a9ove without B&DC in the nae.
6se the te1ture coordinate coor( to do a
te1ture looku. in the &D te1ture currentl)
9ound to sam%ler. 3or the .roDective
EBQroICF versions, the te1ture coordinate is
divided 9) coor(.2.
vec% textureCube Esa.ler"u9e sam%ler,
vec& coor( Y, #loat +iasZ F
vec% textureCubeAod Esa.ler"u9e sam%ler,
vec& coor(, #loat lo(F
De.recated. (ee corres.onding signature
a9ove without B"u9eC in the nae.
133
Bui%t+in ,unctions
S#nta* <deprecated= )escription <deprecated=
vec% shadow1? Esa.ler1D(hadow sam%ler)
vec& coor( Y, #loat +iasZ F
vec% shadowD? Esa.ler!D(hadow sam%ler)
vec& coor( Y, #loat +iasZ F
vec% shadow1?QroI Esa.ler1D(hadow sam%ler)
vec% coor( Y, #loat +iasZ F
vec% shadowD?QroI Esa.ler!D(hadow sam%ler)
vec% coor( Y, #loat +iasZ F
vec% shadow1?Aod Esa.ler1D(hadow sam%ler)
vec& coor(, #loat lo(F
vec% shadowD?Aod Esa.ler!D(hadow sam%ler)
vec& coor(, #loat lo(F
vec% shadow1?QroIAodEsa.ler1D(hadow sam%ler)
vec% coor(, #loat lo(F
vec% shadowD?QroIAodEsa.ler!D(hadow sam%ler)
vec% coor() #loat lo(F
De.recated. (ae #unctionalit) as the
Btexture] 9ased naes a9ove with the sae
signature.
134
Bui%t+in ,unctions
3.1% ,ragment +rocessing ,unctions
3ragent .rocessing #unctions are onl) availa9le in #ragent shaders.
3.1%.1 )erivative ,unctions
Derivatives a) 9e co.utationall) e1.ensive andNor nuericall) unsta9le. -here#ore, an +.en/0
i.leentation a) a..ro1iate the true derivatives 9) using a #ast 9ut not entirel) accurate derivative
co.utation. Derivatives are unde#ined within non8uni#or control #low.
-he e1.ected 9ehavior o# a derivative is s.eci#ied using #orwardN9ackward di##erencing.
3orward di##erencing:
" *(*" * ~("(* *(* 1a
("(* * ~
" *(*" *
(*
19
Backward di##erencing:
" *(*" * ~("(* *(* !a
("(* * ~
" *" *(*
(*
!9
@ith single8sa.le rasteri?ation, (* PR 1.* in e=uations 19 and !9. 3or ulti8sa.le rasteri?ation, (* P
!.* in e=uations 19 and !9.
dKdC is a..ro1iated siilarl), with , re.lacing *.
A /0 i.leentation a) use the a9ove or other ethods to .er#or the calculation, su9Dect to the
#ollowing conditions:
1. -he ethod a) use .iecewise linear a..ro1iations. (uch linear a..ro1iations i.l) that higher
order derivatives, dKdxEdKdxE*FF and a9ove, are unde#ined.
!. -he ethod a) assue that the #unction evaluated is continuous. -here#ore derivatives within non8
uni#or control #low are unde#ined.
&. -he ethod a) di##er .er #ragent, su9Dect to the constraint that the ethod a) var) 9) window
coordinates, not screen coordinates. -he invariance re=uireent descri9ed in section &.! BInvarianceC
o# the +.en/0 /ra.hics ()ste (.eci#ication, is rela1ed #or derivative calculations, 9ecause the
ethod a) 9e a #unction o# #ragent location.
+ther .ro.erties that are desira9le, 9ut not re=uired, are:
%. 3unctions should 9e evaluated within the interior o# a .riitive Einter.olated, not e1tra.olatedF.
$. 3unctions #or dKdx should 9e evaluated while holding ) constant. 3unctions #or dKdC should 9e
evaluated while holding 1 constant. ,owever, i1ed higher order derivatives, like dKdxEdKdCE,FF
and dKdCEdKdxE*FF are unde#ined.
135
Bui%t+in ,unctions
'. Derivatives o# constant arguents should 9e *.
In soe i.leentations, var)ing degrees o# derivative accurac) a) 9e o9tained 9) .roviding /0 hints
Esection $.% B,intsC o# the +.en/0 /ra.hics ()ste (.eci#icationF, allowing a user to ake an iage
=ualit) versus s.eed trade o##.
S#nta* )escription
gen-).e dKdx Egen-).e %F Returns the derivative in 1 using local di##erencing #or
the in.ut arguent %.
gen-).e dKdC Egen-).e %F Returns the derivative in ) using local di##erencing #or
the in.ut arguent %.
-hese two #unctions are coonl) used to estiate the
#ilter width used to anti8alias .rocedural te1tures. @e
are assuing that the e1.ression is 9eing evaluated in
.arallel on a (I:D arra) so that at an) given .oint in
tie the value o# the #unction is known at the grid .oints
re.resented 9) the (I:D arra). 0ocal di##erencing
9etween (I:D arra) eleents can there#ore 9e used to
derive d3d1, d3d), etc.
gen-).e fwidth Egen-).e %F Returns the su o# the a9solute derivative in 1 and )
using local di##erencing #or the in.ut arguent %, i.e.,
abs EdKdx E%FF J abs EdKdC E%FFI
3.1%.2 Interpolation ,unctions
Built8in inter.olation #unctions are availa9le to co.ute an inter.olated value o# a #ragent shader in.ut
varia9le at a shader8s.eci#ied E*, ,F location. A se.arate E*, ,F location a) 9e used #or each invocation o#
the 9uilt8in #unction, and those locations a) di##er #ro the de#ault E*, ,F location used to .roduce the
de#ault value o# the in.ut.
3or all o# the inter.olation #unctions, inter%olant ust 9e an in.ut varia9le or an eleent o# an in.ut
varia9le declared as an arra). "o.onent selection o.erators Ee.g., .*,F a) not 9e used when s.eci#)ing
inter%olant. I# inter%olant is declared with a flat or centroid =uali#ier, the =uali#ier will have no e##ect on
the inter.olated value. I# inter%olant is declared with the noperspective =uali#ier, the inter.olated value
will 9e co.uted without .ers.ective correction.
136
Bui%t+in ,unctions
S#nta* )escription
#loat interpolateAtCentroid E#loat inter%olantF
vec! interpolateAtCentroid Evec! inter%olantF
vec& interpolateAtCentroid Evec& inter%olantF
vec% interpolateAtCentroid Evec% inter%olantF
Return the value o# the in.ut var)ing inter%olant
sa.led at a location inside the 9oth the .i1el and the
.riitive 9eing .rocessed. -he value o9tained would
9e the sae value assigned to the in.ut varia9le i#
declared with the centroid =uali#ier.
#loat interpolateAtSample E#loat inter%olant,
int sam%leF
vec! interpolateAtSample Evec! inter%olant,
int sam%leF
vec& interpolateAtSample Evec& inter%olant,
int sam%leF
vec% interpolateAtSample Evec% inter%olant,
int sam%leF
Return the value o# the in.ut var)ing inter%olant at
the location o# sa.le nu9er sam%le. I#
ultisa.le 9u##ers are not availa9le, the in.ut
var)ing will 9e evaluated at the center o# the .i1el. I#
sa.le sam%le does not e1ist, the .osition used to
inter.olate the in.ut var)ing is unde#ined.
#loat interpolateAtOffset E#loat inter%olant,
vec! o##setF
vec! interpolateAtOffset Evec! inter%olant,
vec! o##setF
vec& interpolateAtOffset Evec& inter%olant,
vec! o##setF
vec% interpolateAtOffset Evec% inter%olant,
vec! o##setF
Return the value o# the in.ut var)ing inter%olant
sa.led at an o##set #ro the center o# the .i1el
s.eci#ied 9) offset. -he two #loating8.oint
co.onents o# offset, give the o##set in .i1els in the *
and , directions, res.ectivel). An o##set o# E*, *F
identi#ies the center o# the .i1el. -he range and
granularit) o# o##sets su..orted 9) this #unction is
i.leentation8de.endent.
3.11 5oise ,unctions
7oise #unctions are availa9le to #ragent, geoetr), and verte1 shaders. -he) are stochastic #unctions that
can 9e used to increase visual co.le1it). Values returned 9) the #ollowing noise #unctions give the
a..earance o# randoness, 9ut are not trul) rando. -he noise #unctions 9elow are de#ined to have the
#ollowing characteristics:
-he return valueEsF are alwa)s in the range Y81.*,1.*Z, and cover at least the range Y8*.', *.'Z, with a
/aussian8like distri9ution.
-he return valueEsF have an overall average o# *.*
-he) are re.eata9le, in that a .articular in.ut value will alwa)s .roduce the sae return value
-he) are statisticall) invariant under rotation Ei.e., no atter how the doain is rotated, it has the sae
statistical characterF
-he) have a statistical invariance under translation Ei.e., no atter how the doain is translated, it has
the sae statistical characterF
-he) t).icall) give di##erent results under translation.
137
Bui%t+in ,unctions
-he s.atial #re=uenc) is narrowl) concentrated, centered soewhere 9etween *.$ to 1.*.
-he) are "
1
continuous ever)where Ei.e., the #irst derivative is continuousF
S#nta* )escription
#loat noise1 Egen-).e *F Returns a 1D noise value 9ased on the in.ut value *.
vec! noiseD Egen-).e *F Returns a !D noise value 9ased on the in.ut value *.
vec& noiseE Egen-).e *F Returns a &D noise value 9ased on the in.ut value *.
vec% noiseB Egen-).e *F Returns a %D noise value 9ased on the in.ut value *.
13
Bui%t+in ,unctions
3.12 Geometr# Shader ,unctions
-hese #unctions are onl) availa9le in geoetr) shaders. -he) are descri9ed in ore de.th #ollowing the
ta9le.
S#nta* )escription
void JmitStreamTertex Eint streamF Eit the current values o# out.ut varia9les to the current
out.ut .riitive on strea stream. -he arguent to stream
ust 9e a constant integral e1.ression. +n return #ro this
call, the values o# all out.ut varia9les are unde#ined.
"an onl) 9e used i# ulti.le out.ut streas are su..orted.
void JndStreamQrimitive Eint streamF "o.letes the current out.ut .riitive on strea stream and
starts a new one. -he arguent to stream ust 9e a constant
integral e1.ression. 7o verte1 is eitted.
"an onl) 9e used i# ulti.le out.ut streas are su..orted.
void JmitTertex EF Eit the current values o# out.ut varia9les to the current
out.ut .riitive. +n return #ro this call, the values o#
out.ut varia9les are unde#ined.
@hen ulti.le out.ut streas are su..orted, this is
e=uivalent to calling JmitStreamTertexE*F.
void JndQrimitive EF "o.letes the current out.ut .riitive and starts a new one.
7o verte1 is eitted.
@hen ulti.le out.ut streas are su..orted, this is
e=uivalent to calling JndStreamQrimitiveE*F.
-he #unction JmitStreamTertexEF s.eci#ies that a verte1 is co.leted. A verte1 is added to the current
out.ut .riitive in verte1 strea stream using the current values o# all out.ut varia9les associated with
stream. -hese include gl!oint'i1e, gl9li%Distance, glLa,er, gl!osition, gl!rimitive-D and
glView%ort-n(e*. -he values o# all out.ut varia9les #or all out.ut streas are unde#ined a#ter a call to
JmitStreamTertexEF. I# a geoetr) shader invocation has eitted ore vertices than .eritted 9) the
out.ut la)out =uali#ier max<vertices, the results o# calling JmitStreamTertexEF are unde#ined.
-he #unction JndStreamQrimitiveEF s.eci#ies that the current out.ut .riitive #or verte1 strea stream is
co.leted and a new out.ut .riitive Eo# the sae t).eF will started 9) an) su9se=uent
JmitStreamTertexEF. -his #unction does not eit a verte1. I# the out.ut la)out is declared to 9e
B.ointsC, calling JndStreamQrimitiveEF is o.tional.
A geoetr) shader starts with an out.ut .riitive containing no vertices #or each strea. @hen a
geoetr) shader terinates, the current out.ut .riitive #or each strea is autoaticall) co.leted. It is
not necessar) to call JndStreamQrimitiveEF i# the geoetr) shader writes onl) a single .riitive.
13!
Bui%t+in ,unctions
:ulti.le out.ut streas are su..orted onl) i# the out.ut .riitive t).e is declared to 9e %oints. A
.rogra will #ail to link i# it contains a geoetr) shader calling JmitStreamTertexEF or
JndStreamQrimitiveEF i# its in.ut .riitive t).e is not %oints.
14"
Bui%t+in ,unctions
3.1! Shader Invocation Control ,unctions
-he shader invocation control #unction is availa9le onl) in tessellation control shaders. It is used to
control the relative e1ecution order o# ulti.le shader invocations used to .rocess a .atch, which are
otherwise e1ecuted with an unde#ined relative order.
S#nta* )escription
void barrier EF 3or an) given static instance o# barrierEF, all tessellation control shader
invocations #or a single in.ut .atch ust enter it 9e#ore an) will 9e
allowed to continue 9e)ond it.
-he #unction barrierEF .rovides a .artiall) de#ined order o# e1ecution 9etween shader invocations. -his
ensures that values written 9) one invocation .rior to a given static instance o# barrierEF can 9e sa#el)
read 9) other invocations a#ter their call to the sae static instance barrierEF. Because invocations a)
e1ecute in unde#ined order 9etween these 9arrier calls, the values o# a .er8verte1 or .er8.atch out.ut
varia9le will 9e unde#ined in a nu9er o# cases enuerated in section %.&.' B+ut.utsC.
-he barrierEF #unction a) onl) 9e .laced inside the #unction mainEF o# the tessellation control shader
and a) not 9e called within an) control #low. Barriers are also disallowed a#ter a return stateent in the
#unction mainEF.
141
8 Shading Language Grammar
-BD: su9routines
-he graar is #ed #ro the out.ut o# le1ical anal)sis. -he tokens returned #ro le1ical anal)sis are
>TTRI6QTE EONST 6OOL FLO>T OQ6LE INT QINT
6RE>U EONTINQE O ELSE FOR IF ISE>R RETQRN SVITEJ E>SE EF>QLT SQ6ROQTINE
6VEE9 6VEE; 6VEE8 IVEE9 IVEE; IVEE8 QVEE9 QVEE; QVEE8 VEE9 VEE; VEE8
?>T9 ?>T; ?>T8 EENTROI IN OQT INOQT QNIFOR? V>RRIN! @>TEJ S>?@LE
VEE9 VEE; VEE8 ?>T9 ?>T; ?>T8
NO@ERS@EETIVE FL>T S?OOTJ L>ROQT
?>T9P9 ?>T9P; ?>T9P8
?>T;P9 ?>T;P; ?>T;P8
?>T8P9 ?>T8P; ?>T8P8
?>T9P9 ?>T9P; ?>T9P8
?>T;P9 ?>T;P; ?>T;P8
?>T8P9 ?>T8P; ?>T8P8
S>?@LER' S>?@LER9 S>?@LER; S>?@LEREQ6E S>?@LER'SJ>OV S>?@LER9SJ>OV
S>?@LEREQ6ESJ>OV S>?@LER'>RR>R S>?@LER9>RR>R S>?@LER'>RR>RSJ>OV
S>?@LER9>RR>RSJ>OV IS>?@LER' IS>?@LER9 IS>?@LER; IS>?@LEREQ6E
IS>?@LER'>RR>R IS>?@LER9>RR>R QS>?@LER' QS>?@LER9 QS>?@LER;
QS>?@LEREQ6E QS>?@LER'>RR>R QS>?@LER9>RR>R
S>?@LER9REET S>?@LER9REETSJ>OV IS>?@LER9REET QS>?@LER9REET
S>?@LER6QFFER IS>?@LER6QFFER QS>?@LER6QFFER
S>?@LEREQ6E>RR>R S>?@LEREQ6E>RR>RSJ>OV
IS>?@LEREQ6E>RR>R QS>?@LEREQ6E>RR>R
S>?@LER9?S IS>?@LER9?S QS>?@LER9?S
S>?@LER9?S>rra& IS>?@LER9?S>rra& QS>?@LER9?S>rra&
142
! Shading Language Gra**ar
STRQET VOI VJILE
IENTIFIER TR@E_N>?E FLO>TEONST>NT INTEONST>NT QINTEONST>NT 6OOLEONST>NT
FIEL_SELEETION
LEFT_O@ RI!JT_O@
INE_O@ EE_O@ LE_O@ !E_O@ ET_O@ NE_O@
>N_O@ OR_O@ POR_O@ ?QL_>SSI!N IV_>SSI!N >_>SSI!N
?O_>SSI!N LEFT_>SSI!N RI!JT_>SSI!N >N_>SSI!N POR_>SSI!N OR_>SSI!N
SQ6_>SSI!N
LEFT_@>REN RI!JT_@>REN LEFT_6R>EUET RI!JT_6R>EUET LEFT_6R>EE RI!JT_6R>EE OT
EO??> EOLON ETQ>L SE?IEOLON 6>N! >SJ TILE @LQS ST>R SL>SJ @EREENT
LEFT_>N!LE RI!JT_>N!LE VERTIE>L_6>R E>RET >?@ERS>N TQESTION
INV>RI>NT
JI!J_@REEISION ?EIQ?_@REEISION LOV_@REEISION @REEISION
-he #ollowing descri9es the graar #or the +.en/0 (hading 0anguage in ters o# the a9ove tokens.
varia+lei(entifier:
-D/.#-"-/R
%rimar,e*%ression:
varia+lei(entifier
-.#9$.'#A.#
E-.#9$.'#A.#
"L$A#9$.'#A.#
;$$L9$.'#A.#
L/"#!AR/. e*%ression R-&L#!AR/.
%ostfi*e*%ression:
%rimar,e*%ression
%ostfi*e*%ression L/"#;RA9M/# integere*%ression R-&L#;RA9M/#
functioncall
%ostfi*e*%ression D$# "-/LD'/L/9#-$.
%ostfi*e*%ression -.9$!
%ostfi*e*%ression D/9$!
integere*%ression:
e*%ression
functioncall:
143
! Shading Language Gra**ar
functioncallormetho(
functioncallormetho(:
functioncallgeneric
%ostfi*e*%ression D$# functioncallgeneric
functioncallgeneric:
functioncallhea(erwith%arameters R-&L#!AR/.
functioncallhea(erno%arameters R-&L#!AR/.
functioncallhea(erno%arameters:
functioncallhea(er V$-D
functioncallhea(er
functioncallhea(erwith%arameters:
functioncallhea(er assignmente*%ression
functioncallhea(erwith%arameters 9$88A assignmente*%ression
functioncallhea(er:
functioni(entifier L/"#!AR/.
DD &rammar .ote: 9onstructors loo0 li0e functions) +ut le*ical anal,sis recogni1e( most of them as
DD 0e,wor(s. #he, are now recogni1e( through Nt,%es%ecifierO.
functioni(entifier:
t,%es%ecifier
-D/.#-"-/R
"-/LD'/L/9#-$.
unar,e*%ression:
%ostfi*e*%ression
-.9$! unar,e*%ression
D/9$! unar,e*%ression
unar,o%erator unar,e*%ression
DD &rammar .ote: .o tra(itional st,le t,%e casts.
unar,o%erator:
!LE'
DA'L
144
! Shading Language Gra**ar
;A.&
#-LD/
DD &rammar .ote: .o J<J or JPJ unar, o%s. !ointers are not su%%orte(.
multi%licativee*%ression:
unar,e*%ression
multi%licativee*%ression '#AR unar,e*%ression
multi%licativee*%ression 'LA'L unar,e*%ression
multi%licativee*%ression !/R9/.# unar,e*%ression
a((itivee*%ression:
multi%licativee*%ression
a((itivee*%ression !LE' multi%licativee*%ression
a((itivee*%ression DA'L multi%licativee*%ression
shifte*%ression:
a((itivee*%ression
shifte*%ression L/"#$! a((itivee*%ression
shifte*%ression R-&L#$! a((itivee*%ression
relationale*%ression:
shifte*%ression
relationale*%ression L/"#A.&L/ shifte*%ression
relationale*%ression R-&L#A.&L/ shifte*%ression
relationale*%ression L/$! shifte*%ression
relationale*%ression &/$! shifte*%ression
e2ualit,e*%ression:
relationale*%ression
e2ualit,e*%ression /Q$! relationale*%ression
e2ualit,e*%ression ./$! relationale*%ression
an(e*%ression:
e2ualit,e*%ression
an(e*%ression A8!/R'A.D e2ualit,e*%ression
e*clusiveore*%ression:
an(e*%ression
e*clusiveore*%ression 9AR/# an(e*%ression
145
! Shading Language Gra**ar
inclusiveore*%ression:
e*clusiveore*%ression
inclusiveore*%ression V/R#-9AL;AR e*clusiveore*%ression
logicalan(e*%ression:
inclusiveore*%ression
logicalan(e*%ression A.D$! inclusiveore*%ression
logical*ore*%ression:
logicalan(e*%ression
logical*ore*%ression R$R$! logicalan(e*%ression
logicalore*%ression:
logical*ore*%ression
logicalore*%ression $R$! logical*ore*%ression
con(itionale*%ression:
logicalore*%ression
logicalore*%ression QE/'#-$. e*%ression 9$L$. assignmente*%ression
assignmente*%ression:
con(itionale*%ression
unar,e*%ression assignmento%erator assignmente*%ression
assignmento%erator:
/QEAL
8ELA''-&.
D-VA''-&.
8$DA''-&.
ADDA''-&.
'E;A''-&.
L/"#A''-&.
R-&L#A''-&.
A.DA''-&.
R$RA''-&.
$RA''-&.
e*%ression:
assignmente*%ression
146
! Shading Language Gra**ar
e*%ression 9$88A assignmente*%ression
constante*%ression:
con(itionale*%ression
(eclaration:
function%rotot,%e '/8-9$L$.
init(eclaratorlist '/8-9$L$.
!R/9-'-$. %recision2ualifier t,%es%ecifierno%rec '/8-9$L$.
t,%e2ualifier -D/.#-"-/R L/"#;RA9/ struct(eclarationlist R-&L#;RA9/ '/8-9$L$.
t,%e2ualifier -D/.#-"-/R L/"#;RA9/ struct(eclarationlist R-&L#;RA9/
-D/.#-"-/R '/8-9$L$.
t,%e2ualifier -D/.#-"-/R L/"#;RA9/ struct(eclarationlist R-&L#;RA9/
-D/.#-"-/R L/"#;RA9M/# R-&L#;RA9M/# '/8-9$L$.
t,%e2ualifier -D/.#-"-/R L/"#;RA9/ struct(eclarationlist R-&L#;RA9/
-D/.#-"-/R L/"#;RA9M/# constante*%ression R-&L#;RA9M/# '/8-9$L$.
t,%e2ualifier '/8-9$L$.
function%rotot,%e:
function(eclarator R-&L#!AR/.
function(eclarator:
functionhea(er
functionhea(erwith%arameters
functionhea(erwith%arameters:
functionhea(er %arameter(eclaration
functionhea(erwith%arameters 9$88A %arameter(eclaration
functionhea(er:
full,s%ecifie(t,%e -D/.#-"-/R L/"#!AR/.
%arameter(eclarator:
t,%es%ecifier -D/.#-"-/R
t,%es%ecifier -D/.#-"-/R L/"#;RA9M/# constante*%ression R-&L#;RA9M/#
%arameter(eclaration:
%arametert,%e2ualifier %arameter2ualifier %arameter(eclarator
%arameter2ualifier %arameter(eclarator
%arametert,%e2ualifier %arameter2ualifier %arametert,%es%ecifier
147
! Shading Language Gra**ar
%arameter2ualifier %arametert,%es%ecifier
%arameter2ualifier:
D< em%t, <D
-.
$E#
-.$E#
%arametert,%es%ecifier:
t,%es%ecifier
init(eclaratorlist:
single(eclaration
init(eclaratorlist 9$88A -D/.#-"-/R
init(eclaratorlist 9$88A -D/.#-"-/R L/"#;RA9M/# R-&L#;RA9M/#
init(eclaratorlist 9$88A -D/.#-"-/R L/"#;RA9M/# constante*%ression
R-&L#;RA9M/#
init(eclaratorlist 9$88A -D/.#-"-/R L/"#;RA9M/#
R-&L#;RA9M/# /QEAL initiali1er
init(eclaratorlist 9$88A -D/.#-"-/R L/"#;RA9M/# constante*%ression
R-&L#;RA9M/# /QEAL initiali1er
init(eclaratorlist 9$88A -D/.#-"-/R /QEAL initiali1er
single(eclaration:
full,s%ecifie(t,%e
full,s%ecifie(t,%e -D/.#-"-/R
full,s%ecifie(t,%e -D/.#-"-/R L/"#;RA9M/# R-&L#;RA9M/#
full,s%ecifie(t,%e -D/.#-"-/R L/"#;RA9M/# constante*%ression R-&L#;RA9M/#
full,s%ecifie(t,%e -D/.#-"-/R L/"#;RA9M/# R-&L#;RA9M/# /QEAL initiali1er
full,s%ecifie(t,%e -D/.#-"-/R L/"#;RA9M/# constante*%ression
R-&L#;RA9M/# /QEAL initiali1er
full,s%ecifie(t,%e -D/.#-"-/R /QEAL initiali1er
-.VAR-A.# -D/.#-"-/R
DD &rammar .ote: .o JenumJ) or Jt,%e(efJ.
full,s%ecifie(t,%e:
t,%es%ecifier
t,%e2ualifier t,%es%ecifier
14
! Shading Language Gra**ar
invariant2ualifier:
-.VAR-A.#
inter%olation2ualifier:
'8$$#L
"LA#
.$!/R'!/9#-V/
la,out2ualifier:
LAS$E# L/"#!AR/. la,out2ualifieri(list R-&L#!AR/.
la,out2ualifieri(list:
la,out2ualifieri(
la,out2ualifieri(list 9$88A la,out2ualifieri(
la,out2ualifieri(:
-D/.#-"-/R
-D/.#-"-/R /QEAL -.#9$.'#A.#
%arametert,%e2ualifier:
9$.'#
t,%e2ualifier:
storage2ualifier
la,out2ualifier
la,out2ualifier storage2ualifier
inter%olation2ualifier storage2ualifier
inter%olation2ualifier
invariant2ualifier storage2ualifier
invariant2ualifier inter%olation2ualifier storage2ualifier
invariant
storage2ualifier:
9$.'#
A##R-;E#/ DD Verte* onl,.
VARS-.&
9/.#R$-D VARS-.&
14!
! Shading Language Gra**ar
-.
$E#
9/.#R$-D -.
9/.#R$-D $E#
!A#9L -.
!A#9L $E#
'A8!L/ -.
'A8!L/ $E#
E.-"$R8
t,%es%ecifier:
t,%es%ecifierno%rec
%recision2ualifier t,%es%ecifierno%rec
t,%es%ecifierno%rec:
t,%es%ecifiernonarra,
t,%es%ecifiernonarra, L/"#;RA9M/# R-&L#;RA9M/#
t,%es%ecifiernonarra, L/"#;RA9M/# constante*%ression R-&L#;RA9M/#
t,%es%ecifiernonarra,:
V$-D
"L$A#
D$E;L/
-.#
E-.#
;$$L
V/92
V/9@
V/94
DV/92
DV/9@
DV/94
;V/92
;V/9@
;V/94
-V/92
-V/9@
-V/94
15"
! Shading Language Gra**ar
EV/92
EV/9@
EV/94
8A#2
8A#@
8A#4
8A#2R2
8A#2R@
8A#2R4
8A#@R2
8A#@R@
8A#@R4
8A#4R2
8A#4R@
8A#4R4
D8A#2
D8A#@
D8A#4
D8A#2R2
D8A#2R@
D8A#2R4
D8A#@R2
D8A#@R@
D8A#@R4
D8A#4R2
D8A#4R@
D8A#4R4
'A8!L/R1D
'A8!L/R2D
'A8!L/R@D
'A8!L/R9E;/
'A8!L/R1D'LAD$T
'A8!L/R2D'LAD$T
'A8!L/R9E;/'LAD$T
'A8!L/R1DARRAS
'A8!L/R2DARRAS
'A8!L/R1DARRAS'LAD$T
151
! Shading Language Gra**ar
'A8!L/R2DARRAS'LAD$T
'A8!L/R9E;/ARRAS
'A8!L/R9E;/ARRAS'LAD$T
-'A8!L/R1D
-'A8!L/R2D
-'A8!L/R@D
-'A8!L/R9E;/
-'A8!L/R1DARRAS
-'A8!L/R2DARRAS
-'A8!L/R9E;/ARRAS
E'A8!L/R1D
E'A8!L/R2D
E'A8!L/R@D
E'A8!L/R9E;/
E'A8!L/R1DARRAS
E'A8!L/R2DARRAS
E'A8!L/R9E;/ARRAS
'A8!L/R2DR/9#
'A8!L/R2DR/9#'LAD$T
-'A8!L/R2DR/9#
E'A8!L/R2DR/9#
'A8!L/R;E""/R
-'A8!L/R;E""/R
E'A8!L/R;E""/R
'A8!L/R2D8'
-'A8!L/R2D8'
E'A8!L/R2D8'
'A8!L/R2D8'Arra,
-'A8!L/R2D8'Arra,
E'A8!L/R2D8'Arra,
structs%ecifier
#S!/.A8/
%recision2ualifier:
L-&L!R/9-'-$.
8/D-E8!R/9-'-$.
L$T!R/9-'-$.
structs%ecifier:
'#RE9# -D/.#-"-/R L/"#;RA9/ struct(eclarationlist R-&L#;RA9/
152
! Shading Language Gra**ar
'#RE9# L/"#;RA9/ struct(eclarationlist R-&L#;RA9/
struct(eclarationlist:
struct(eclaration
struct(eclarationlist struct(eclaration
struct(eclaration:
t,%es%ecifier struct(eclaratorlist '/8-9$L$.
t,%e2ualifier t,%es%ecifier struct(eclaratorlist '/8-9$L$.
struct(eclaratorlist:
struct(eclarator
struct(eclaratorlist 9$88A struct(eclarator
struct(eclarator:
-D/.#-"-/R
-D/.#-"-/R L/"#;RA9M/# R-&L#;RA9M/#
-D/.#-"-/R L/"#;RA9M/# constante*%ression R-&L#;RA9M/#
initiali1er:
assignmente*%ression
(eclarationstatement:
(eclaration
statement:
com%oun(statement
sim%lestatement
DD &rammar .ote: la+ele( statements for 'T-#9L onl,3 JgotoJ is not su%%orte(.
sim%lestatement:
(eclarationstatement
e*%ressionstatement
selectionstatement
switchstatement
casela+el
iterationstatement
:um%statement
153
! Shading Language Gra**ar
com%oun(statement:
L/"#;RA9/ R-&L#;RA9/
L/"#;RA9/ statementlist R-&L#;RA9/
statementnonewsco%e:
com%oun(statementnonewsco%e
sim%lestatement
com%oun(statementnonewsco%e:
L/"#;RA9/ R-&L#;RA9/
L/"#;RA9/ statementlist R-&L#;RA9/
statementlist:
statement
statementlist statement
e*%ressionstatement:
'/8-9$L$.
e*%ression '/8-9$L$.
selectionstatement:
-" L/"#!AR/. e*%ression R-&L#!AR/. selectionreststatement
selectionreststatement:
statement /L'/ statement
statement
con(ition:
e*%ression
full,s%ecifie(t,%e -D/.#-"-/R /QEAL initiali1er
switchstatement:
'T-#9L L/"#!AR/. e*%ression R-&L#!AR/. L/"#;RA9/ switchstatementlist
R-&L#;RA9/
switchstatementlist:
D< nothing <D
statementlist
casela+el:
9A'/ e*%ression 9$L$.
D/"AEL# 9$L$.
154
! Shading Language Gra**ar
iterationstatement:
TL-L/ L/"#!AR/. con(ition R-&L#!AR/. statementnonewsco%e
D$ statement TL-L/ L/"#!AR/. e*%ression R-&L#!AR/. '/8-9$L$.
"$R L/"#!AR/. forinitstatement forreststatement R-&L#!AR/.
statementnonewsco%e
forinitstatement:
e*%ressionstatement
(eclarationstatement
con(itiono%t:
con(ition
D< em%t, <D
forreststatement:
con(itiono%t '/8-9$L$.
con(itiono%t '/8-9$L$. e*%ression
:um%statement:
9$.#-.E/ '/8-9$L$.
;R/AM '/8-9$L$.
R/#ER. '/8-9$L$.
R/#ER. e*%ression '/8-9$L$.
D-'9ARD '/8-9$L$. DD "ragment sha(er onl,.
DD &rammar .ote: .o JgotoJ. &otos are not su%%orte(.
translationunit:
e*ternal(eclaration
translationunit e*ternal(eclaration
e*ternal(eclaration:
function(efinition
(eclaration
function(efinition:
function%rotot,%e com%oun(statementnonewsco%e
155

Вам также может понравиться