1<!DOCTYPE html> 2<html lang="en"> 3<head> 4<meta charset="UTF-8"> 5<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> 6<meta name="viewport" content="width=device-width, initial-scale=1.0"> 7<meta name="generator" content="Asciidoctor 1.5.7.1"> 8<meta name="author" content="Robert J. Simpson, Qualcomm (Editor), John Kessenich, Google (Editor), Dave Baldwin and Randi Rost (Version 1.1 Authors)"> 9<title>The OpenGL ES® Shading Language, Version 3.20.6</title> 10<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"> 11<style> 12/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */ 13/* Uncomment @import statement below to use as custom stylesheet */ 14/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/ 15article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block} 16audio,canvas,video{display:inline-block} 17audio:not([controls]){display:none;height:0} 18script{display:none!important} 19html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%} 20a{background:transparent} 21a:focus{outline:thin dotted} 22a:active,a:hover{outline:0} 23h1{font-size:2em;margin:.67em 0} 24abbr[title]{border-bottom:1px dotted} 25b,strong{font-weight:bold} 26dfn{font-style:italic} 27hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0} 28mark{background:#ff0;color:#000} 29code,kbd,pre,samp{font-family:monospace;font-size:1em} 30pre{white-space:pre-wrap} 31q{quotes:"\201C" "\201D" "\2018" "\2019"} 32small{font-size:80%} 33sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} 34sup{top:-.5em} 35sub{bottom:-.25em} 36img{border:0} 37svg:not(:root){overflow:hidden} 38figure{margin:0} 39fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} 40legend{border:0;padding:0} 41button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} 42button,input{line-height:normal} 43button,select{text-transform:none} 44button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer} 45button[disabled],html input[disabled]{cursor:default} 46input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0} 47button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} 48textarea{overflow:auto;vertical-align:top} 49table{border-collapse:collapse;border-spacing:0} 50*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box} 51html,body{font-size:100%} 52body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased} 53a:hover{cursor:pointer} 54img,object,embed{max-width:100%;height:auto} 55object,embed{height:100%} 56img{-ms-interpolation-mode:bicubic} 57.left{float:left!important} 58.right{float:right!important} 59.text-left{text-align:left!important} 60.text-right{text-align:right!important} 61.text-center{text-align:center!important} 62.text-justify{text-align:justify!important} 63.hide{display:none} 64img,object,svg{display:inline-block;vertical-align:middle} 65textarea{height:auto;min-height:50px} 66select{width:100%} 67.center{margin-left:auto;margin-right:auto} 68.stretch{width:100%} 69.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em} 70div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr} 71a{color:#2156a5;text-decoration:underline;line-height:inherit} 72a:hover,a:focus{color:#1d4b8f} 73a img{border:none} 74p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} 75p aside{font-size:.875em;line-height:1.35;font-style:italic} 76h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em} 77h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0} 78h1{font-size:2.125em} 79h2{font-size:1.6875em} 80h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} 81h4,h5{font-size:1.125em} 82h6{font-size:1em} 83hr{border:solid #ddddd8;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0} 84em,i{font-style:italic;line-height:inherit} 85strong,b{font-weight:bold;line-height:inherit} 86small{font-size:60%;line-height:inherit} 87code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} 88ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} 89ul,ol{margin-left:1.5em} 90ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em} 91ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} 92ul.square{list-style-type:square} 93ul.circle{list-style-type:circle} 94ul.disc{list-style-type:disc} 95ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} 96dl dt{margin-bottom:.3125em;font-weight:bold} 97dl dd{margin-bottom:1.25em} 98abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help} 99abbr{text-transform:none} 100blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} 101blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)} 102blockquote cite::before{content:"\2014 \0020"} 103blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)} 104blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} 105@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} 106h1{font-size:2.75em} 107h2{font-size:2.3125em} 108h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} 109h4{font-size:1.4375em}} 110table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede} 111table thead,table tfoot{background:#f7f8f7} 112table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left} 113table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} 114table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7} 115table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6} 116h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} 117h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} 118.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} 119.clearfix::after,.float-group::after{clear:both} 120*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word} 121*:not(pre)>code.nobreak{word-wrap:normal} 122*:not(pre)>code.nowrap{white-space:nowrap} 123pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed} 124em em{font-style:normal} 125strong strong{font-weight:400} 126.keyseq{color:rgba(51,51,51,.8)} 127kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap} 128.keyseq kbd:first-child{margin-left:0} 129.keyseq kbd:last-child{margin-right:0} 130.menuseq,.menuref{color:#000} 131.menuseq b:not(.caret),.menuref{font-weight:inherit} 132.menuseq{word-spacing:-.02em} 133.menuseq b.caret{font-size:1.25em;line-height:.8} 134.menuseq i.caret{font-weight:bold;text-align:center;width:.45em} 135b.button::before,b.button::after{position:relative;top:-1px;font-weight:400} 136b.button::before{content:"[";padding:0 3px 0 2px} 137b.button::after{content:"]";padding:0 2px 0 3px} 138p a>code:hover{color:rgba(0,0,0,.9)} 139#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} 140#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table} 141#header::after,#content::after,#footnotes::after,#footer::after{clear:both} 142#content{margin-top:1.25em} 143#content::before{content:none} 144#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} 145#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #ddddd8} 146#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #ddddd8;padding-bottom:8px} 147#header .details{border-bottom:1px solid #ddddd8;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap} 148#header .details span:first-child{margin-left:-.125em} 149#header .details span.email a{color:rgba(0,0,0,.85)} 150#header .details br{display:none} 151#header .details br+span::before{content:"\00a0\2013\00a0"} 152#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} 153#header .details br+span#revremark::before{content:"\00a0|\00a0"} 154#header #revnumber{text-transform:capitalize} 155#header #revnumber::after{content:"\00a0"} 156#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #ddddd8;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} 157#toc{border-bottom:1px solid #efefed;padding-bottom:.5em} 158#toc>ul{margin-left:.125em} 159#toc ul.sectlevel0>li>a{font-style:italic} 160#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} 161#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} 162#toc li{line-height:1.3334;margin-top:.3334em} 163#toc a{text-decoration:none} 164#toc a:active{text-decoration:underline} 165#toctitle{color:#7a2518;font-size:1.2em} 166@media screen and (min-width:768px){#toctitle{font-size:1.375em} 167body.toc2{padding-left:15em;padding-right:0} 168#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #efefed;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} 169#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} 170#toc.toc2>ul{font-size:.9em;margin-bottom:0} 171#toc.toc2 ul ul{margin-left:0;padding-left:1em} 172#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} 173body.toc2.toc-right{padding-left:0;padding-right:15em} 174body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #efefed;left:auto;right:0}} 175@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} 176#toc.toc2{width:20em} 177#toc.toc2 #toctitle{font-size:1.375em} 178#toc.toc2>ul{font-size:.95em} 179#toc.toc2 ul ul{padding-left:1.25em} 180body.toc2.toc-right{padding-left:0;padding-right:20em}} 181#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} 182#content #toc>:first-child{margin-top:0} 183#content #toc>:last-child{margin-bottom:0} 184#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em} 185#footer-text{color:rgba(255,255,255,.8);line-height:1.44} 186#content{margin-bottom:.625em} 187.sect1{padding-bottom:.625em} 188@media screen and (min-width:768px){#content{margin-bottom:1.25em} 189.sect1{padding-bottom:1.25em}} 190.sect1:last-child{padding-bottom:0} 191.sect1+.sect1{border-top:1px solid #efefed} 192#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400} 193#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em} 194#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible} 195#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none} 196#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} 197.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} 198.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic} 199table.tableblock.fit-content>caption.title{white-space:nowrap;width:0} 200.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)} 201table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit} 202.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} 203.admonitionblock>table td.icon{text-align:center;width:80px} 204.admonitionblock>table td.icon img{max-width:none} 205.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} 206.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8;color:rgba(0,0,0,.6)} 207.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} 208.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px} 209.exampleblock>.content>:first-child{margin-top:0} 210.exampleblock>.content>:last-child{margin-bottom:0} 211.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} 212.sidebarblock>:first-child{margin-top:0} 213.sidebarblock>:last-child{margin-bottom:0} 214.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} 215.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} 216.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8} 217.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1} 218.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;padding:1em;font-size:.8125em} 219.literalblock pre.nowrap,.literalblock pre[class].nowrap,.listingblock pre.nowrap,.listingblock pre[class].nowrap{overflow-x:auto;white-space:pre;word-wrap:normal} 220@media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}} 221@media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}} 222.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)} 223.listingblock pre.highlightjs{padding:0} 224.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px} 225.listingblock pre.prettyprint{border-width:0} 226.listingblock>.content{position:relative} 227.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999} 228.listingblock:hover code[data-lang]::before{display:block} 229.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999} 230.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} 231table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none} 232table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45} 233table.pyhltable td.code{padding-left:.75em;padding-right:0} 234pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #ddddd8} 235pre.pygments .lineno{display:inline-block;margin-right:.25em} 236table.pyhltable .linenodiv{background:none!important;padding-right:0!important} 237.quoteblock{margin:0 1em 1.25em 1.5em;display:table} 238.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em} 239.quoteblock blockquote,.quoteblock blockquote p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} 240.quoteblock blockquote{margin:0;padding:0;border:0} 241.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)} 242.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} 243.quoteblock .attribution{margin-top:.5em;margin-right:.5ex;text-align:right} 244.quoteblock .quoteblock{margin-left:0;margin-right:0;padding:.5em 0;border-left:3px solid rgba(0,0,0,.6)} 245.quoteblock .quoteblock blockquote{padding:0 0 0 .75em} 246.quoteblock .quoteblock blockquote::before{display:none} 247.verseblock{margin:0 1em 1.25em} 248.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility} 249.verseblock pre strong{font-weight:400} 250.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} 251.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} 252.quoteblock .attribution br,.verseblock .attribution br{display:none} 253.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} 254.quoteblock.abstract{margin:0 1em 1.25em;display:block} 255.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} 256.quoteblock.abstract blockquote,.quoteblock.abstract blockquote p{word-spacing:0;line-height:1.6} 257.quoteblock.abstract blockquote::before,.quoteblock.abstract p::before{display:none} 258table.tableblock{max-width:100%;border-collapse:separate} 259p.tableblock:last-child{margin-bottom:0} 260td.tableblock>.content{margin-bottom:-1.25em} 261table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} 262table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0} 263table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0} 264table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0} 265table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px} 266table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0} 267table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0} 268table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0} 269table.frame-all{border-width:1px} 270table.frame-sides{border-width:0 1px} 271table.frame-topbot,table.frame-ends{border-width:1px 0} 272table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7} 273table.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none} 274th.halign-left,td.halign-left{text-align:left} 275th.halign-right,td.halign-right{text-align:right} 276th.halign-center,td.halign-center{text-align:center} 277th.valign-top,td.valign-top{vertical-align:top} 278th.valign-bottom,td.valign-bottom{vertical-align:bottom} 279th.valign-middle,td.valign-middle{vertical-align:middle} 280table thead th,table tfoot th{font-weight:bold} 281tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7} 282tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} 283p.tableblock>code:only-child{background:none;padding:0} 284p.tableblock{font-size:1em} 285td>div.verse{white-space:pre} 286ol{margin-left:1.75em} 287ul li ol{margin-left:1.5em} 288dl dd{margin-left:1.125em} 289dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} 290ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} 291ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} 292ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} 293ul.unstyled,ol.unstyled{margin-left:0} 294ul.checklist{margin-left:.625em} 295ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em} 296ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em} 297ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em} 298ul.inline>li{margin-left:1.25em} 299.unstyled dl dt{font-weight:400;font-style:normal} 300ol.arabic{list-style-type:decimal} 301ol.decimal{list-style-type:decimal-leading-zero} 302ol.loweralpha{list-style-type:lower-alpha} 303ol.upperalpha{list-style-type:upper-alpha} 304ol.lowerroman{list-style-type:lower-roman} 305ol.upperroman{list-style-type:upper-roman} 306ol.lowergreek{list-style-type:lower-greek} 307.hdlist>table,.colist>table{border:0;background:none} 308.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} 309td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} 310td.hdlist1{font-weight:bold;padding-bottom:1.25em} 311.literalblock+.colist,.listingblock+.colist{margin-top:-.5em} 312.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} 313.colist td:not([class]):first-child img{max-width:none} 314.colist td:not([class]):last-child{padding:.25em 0} 315.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd} 316.imageblock.left,.imageblock[style*="float: left"]{margin:.25em .625em 1.25em 0} 317.imageblock.right,.imageblock[style*="float: right"]{margin:.25em 0 1.25em .625em} 318.imageblock>.title{margin-bottom:0} 319.imageblock.thumb,.imageblock.th{border-width:6px} 320.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} 321.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} 322.image.left{margin-right:.625em} 323.image.right{margin-left:.625em} 324a.image{text-decoration:none;display:inline-block} 325a.image object{pointer-events:none} 326sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} 327sup.footnote a,sup.footnoteref a{text-decoration:none} 328sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} 329#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} 330#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} 331#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} 332#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} 333#footnotes .footnote:last-of-type{margin-bottom:0} 334#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} 335.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0} 336.gist .file-data>table td.line-data{width:99%} 337div.unbreakable{page-break-inside:avoid} 338.big{font-size:larger} 339.small{font-size:smaller} 340.underline{text-decoration:underline} 341.overline{text-decoration:overline} 342.line-through{text-decoration:line-through} 343.aqua{color:#00bfbf} 344.aqua-background{background-color:#00fafa} 345.black{color:#000} 346.black-background{background-color:#000} 347.blue{color:#0000bf} 348.blue-background{background-color:#0000fa} 349.fuchsia{color:#bf00bf} 350.fuchsia-background{background-color:#fa00fa} 351.gray{color:#606060} 352.gray-background{background-color:#7d7d7d} 353.green{color:#006000} 354.green-background{background-color:#007d00} 355.lime{color:#00bf00} 356.lime-background{background-color:#00fa00} 357.maroon{color:#600000} 358.maroon-background{background-color:#7d0000} 359.navy{color:#000060} 360.navy-background{background-color:#00007d} 361.olive{color:#606000} 362.olive-background{background-color:#7d7d00} 363.purple{color:#600060} 364.purple-background{background-color:#7d007d} 365.red{color:#bf0000} 366.red-background{background-color:#fa0000} 367.silver{color:#909090} 368.silver-background{background-color:#bcbcbc} 369.teal{color:#006060} 370.teal-background{background-color:#007d7d} 371.white{color:#bfbfbf} 372.white-background{background-color:#fafafa} 373.yellow{color:#bfbf00} 374.yellow-background{background-color:#fafa00} 375span.icon>.fa{cursor:default} 376a span.icon>.fa{cursor:inherit} 377.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} 378.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c} 379.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} 380.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900} 381.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400} 382.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000} 383.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold} 384.conum[data-value] *{color:#fff!important} 385.conum[data-value]+b{display:none} 386.conum[data-value]::after{content:attr(data-value)} 387pre .conum[data-value]{position:relative;top:-.125em} 388b.conum *{color:inherit!important} 389.conum:not([data-value]):empty{display:none} 390dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} 391h1,h2,p,td.content,span.alt{letter-spacing:-.01em} 392p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} 393p,blockquote,dt,td.content,span.alt{font-size:1.0625rem} 394p{margin-bottom:1.25rem} 395.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} 396.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc} 397.print-only{display:none!important} 398@page{margin:1.25cm .75cm} 399@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important} 400html{font-size:80%} 401a{color:inherit!important;text-decoration:underline!important} 402a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} 403a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} 404abbr[title]::after{content:" (" attr(title) ")"} 405pre,blockquote,tr,img,object,svg{page-break-inside:avoid} 406thead{display:table-header-group} 407svg{max-width:100%} 408p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} 409h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} 410#toc,.sidebarblock,.exampleblock>.content{background:none!important} 411#toc{border-bottom:1px solid #ddddd8!important;padding-bottom:0!important} 412body.book #header{text-align:center} 413body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} 414body.book #header .details{border:0!important;display:block;padding:0!important} 415body.book #header .details span:first-child{margin-left:0!important} 416body.book #header .details br{display:block} 417body.book #header .details br+span::before{content:none!important} 418body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} 419body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} 420.listingblock code[data-lang]::before{display:block} 421#footer{padding:0 .9375em} 422.hide-on-print{display:none!important} 423.print-only{display:block!important} 424.hide-for-print{display:none!important} 425.show-for-print{display:inherit!important}} 426@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem} 427.sect1{padding:0!important} 428.sect1+.sect1{border:0} 429#footer{background:none} 430#footer-text{color:rgba(0,0,0,.6);font-size:.9em}} 431@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} 432</style> 433<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"> 434<style> 435/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */ 436/*pre.CodeRay {background-color:#f7f7f8;}*/ 437.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em} 438.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)} 439.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)} 440table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none} 441table.CodeRay td{vertical-align: top;line-height:1.45} 442table.CodeRay td.line-numbers{text-align:right} 443table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)} 444table.CodeRay td.code{padding:0 0 0 .5em} 445table.CodeRay td.code>pre{padding:0} 446.CodeRay .debug{color:#fff !important;background:#000080 !important} 447.CodeRay .annotation{color:#007} 448.CodeRay .attribute-name{color:#000080} 449.CodeRay .attribute-value{color:#700} 450.CodeRay .binary{color:#509} 451.CodeRay .comment{color:#998;font-style:italic} 452.CodeRay .char{color:#04d} 453.CodeRay .char .content{color:#04d} 454.CodeRay .char .delimiter{color:#039} 455.CodeRay .class{color:#458;font-weight:bold} 456.CodeRay .complex{color:#a08} 457.CodeRay .constant,.CodeRay .predefined-constant{color:#008080} 458.CodeRay .color{color:#099} 459.CodeRay .class-variable{color:#369} 460.CodeRay .decorator{color:#b0b} 461.CodeRay .definition{color:#099} 462.CodeRay .delimiter{color:#000} 463.CodeRay .doc{color:#970} 464.CodeRay .doctype{color:#34b} 465.CodeRay .doc-string{color:#d42} 466.CodeRay .escape{color:#666} 467.CodeRay .entity{color:#800} 468.CodeRay .error{color:#808} 469.CodeRay .exception{color:inherit} 470.CodeRay .filename{color:#099} 471.CodeRay .function{color:#900;font-weight:bold} 472.CodeRay .global-variable{color:#008080} 473.CodeRay .hex{color:#058} 474.CodeRay .integer,.CodeRay .float{color:#099} 475.CodeRay .include{color:#555} 476.CodeRay .inline{color:#000} 477.CodeRay .inline .inline{background:#ccc} 478.CodeRay .inline .inline .inline{background:#bbb} 479.CodeRay .inline .inline-delimiter{color:#d14} 480.CodeRay .inline-delimiter{color:#d14} 481.CodeRay .important{color:#555;font-weight:bold} 482.CodeRay .interpreted{color:#b2b} 483.CodeRay .instance-variable{color:#008080} 484.CodeRay .label{color:#970} 485.CodeRay .local-variable{color:#963} 486.CodeRay .octal{color:#40e} 487.CodeRay .predefined{color:#369} 488.CodeRay .preprocessor{color:#579} 489.CodeRay .pseudo-class{color:#555} 490.CodeRay .directive{font-weight:bold} 491.CodeRay .type{font-weight:bold} 492.CodeRay .predefined-type{color:inherit} 493.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold} 494.CodeRay .key{color:#808} 495.CodeRay .key .delimiter{color:#606} 496.CodeRay .key .char{color:#80f} 497.CodeRay .value{color:#088} 498.CodeRay .regexp .delimiter{color:#808} 499.CodeRay .regexp .content{color:#808} 500.CodeRay .regexp .modifier{color:#808} 501.CodeRay .regexp .char{color:#d14} 502.CodeRay .regexp .function{color:#404;font-weight:bold} 503.CodeRay .string{color:#d20} 504.CodeRay .string .string .string{background:#ffd0d0} 505.CodeRay .string .content{color:#d14} 506.CodeRay .string .char{color:#d14} 507.CodeRay .string .delimiter{color:#d14} 508.CodeRay .shell{color:#d14} 509.CodeRay .shell .delimiter{color:#d14} 510.CodeRay .symbol{color:#990073} 511.CodeRay .symbol .content{color:#a60} 512.CodeRay .symbol .delimiter{color:#630} 513.CodeRay .tag{color:#008080} 514.CodeRay .tag-special{color:#d70} 515.CodeRay .variable{color:#036} 516.CodeRay .insert{background:#afa} 517.CodeRay .delete{background:#faa} 518.CodeRay .change{color:#aaf;background:#007} 519.CodeRay .head{color:#f8f;background:#505} 520.CodeRay .insert .insert{color:#080} 521.CodeRay .delete .delete{color:#800} 522.CodeRay .change .change{color:#66f} 523.CodeRay .head .head{color:#f4f} 524</style> 525<link rel="stylesheet" href="../katex/katex.min.css"> 526<script src="../katex/katex.min.js"></script> 527<script src="../katex/contrib/auto-render.min.js"></script> 528 <!-- Use KaTeX to render math once document is loaded, see 529 https://github.com/Khan/KaTeX/tree/master/contrib/auto-render --> 530<script> 531 document.addEventListener("DOMContentLoaded", function () { 532 renderMathInElement( 533 document.body, 534 { 535 delimiters: [ 536 { left: "$$", right: "$$", display: true}, 537 { left: "\\[", right: "\\]", display: true}, 538 { left: "$", right: "$", display: false}, 539 { left: "\\(", right: "\\)", display: false} 540 ] 541 } 542 ); 543 }); 544</script></head> 545<body class="book toc2 toc-left" style="max-width: 100;"> 546<div id="header"> 547<h1>The OpenGL ES<sup>®</sup> Shading Language, Version 3.20.6</h1> 548<div class="details"> 549<span id="author" class="author">Robert J. Simpson, Qualcomm (Editor), John Kessenich, Google (Editor), Dave Baldwin and Randi Rost (Version 1.1 Authors)</span><br> 550<span id="revnumber">version 3.20.6,</span> 551<span id="revdate">Wed, 10 Jul 2019 20:42:56 +0000</span> 552<br><span id="revremark">Git branch information not available</span> 553</div> 554<div id="toc" class="toc2"> 555<div id="toctitle">Table of Contents</div> 556<ul class="sectlevel1"> 557<li><a href="#introduction">1. Introduction</a> 558<ul class="sectlevel2"> 559<li><a href="#changes">1.1. Changes</a></li> 560<li><a href="#overview">1.2. Overview</a></li> 561<li><a href="#error-handling">1.3. Error Handling</a></li> 562<li><a href="#typographical-conventions">1.4. Typographical Conventions</a></li> 563<li><a href="#compatibility">1.5. Compatibility</a></li> 564</ul> 565</li> 566<li><a href="#overview-of-opengl-shading">2. Overview of Shading</a> 567<ul class="sectlevel2"> 568<li><a href="#vertex-processor">2.1. Vertex Processor</a></li> 569<li><a href="#tessellation-control-processor">2.2. Tessellation Control Processor</a></li> 570<li><a href="#tessellation-evaluation-processor">2.3. Tessellation Evaluation Processor</a></li> 571<li><a href="#geometry-processor">2.4. Geometry Processor</a></li> 572<li><a href="#fragment-processor">2.5. Fragment Processor</a></li> 573<li><a href="#compute-processor">2.6. Compute Processor</a></li> 574</ul> 575</li> 576<li><a href="#basics">3. Basics</a> 577<ul class="sectlevel2"> 578<li><a href="#character-set">3.1. Character Set</a></li> 579<li><a href="#source-strings">3.2. Source Strings</a></li> 580<li><a href="#version-declaration">3.3. Version Declaration</a></li> 581<li><a href="#preprocessor">3.4. Preprocessor</a></li> 582<li><a href="#comments">3.5. Comments</a></li> 583<li><a href="#tokens">3.6. Tokens</a></li> 584<li><a href="#keywords">3.7. Keywords</a></li> 585<li><a href="#identifiers">3.8. Identifiers</a></li> 586<li><a href="#definitions">3.9. Definitions</a></li> 587<li><a href="#logical-phases-of-compilation">3.10. Logical Phases of Compilation</a></li> 588</ul> 589</li> 590<li><a href="#variables-and-types">4. Variables and Types</a> 591<ul class="sectlevel2"> 592<li><a href="#basic-types">4.1. Basic Types</a></li> 593<li><a href="#scoping">4.2. Scoping</a></li> 594<li><a href="#storage-qualifiers">4.3. Storage Qualifiers</a></li> 595<li><a href="#layout-qualifiers">4.4. Layout Qualifiers</a></li> 596<li><a href="#interpolation-qualifiers">4.5. Interpolation Qualifiers</a></li> 597<li><a href="#parameter-qualifiers">4.6. Parameter Qualifiers</a></li> 598<li><a href="#precision-and-precision-qualifiers">4.7. Precision and Precision Qualifiers</a></li> 599<li><a href="#variance-and-the-invariant-qualifier">4.8. Variance and the Invariant Qualifier</a></li> 600<li><a href="#the-precise-qualifier">4.9. The Precise Qualifier</a></li> 601<li><a href="#memory-qualifiers">4.10. Memory Qualifiers</a></li> 602<li><a href="#specialization-constant-qualifier">4.11. Specialization-Constant Qualifier</a></li> 603<li><a href="#order-of-qualification">4.12. Order and Repetition of Qualification</a></li> 604<li><a href="#empty-declarations">4.13. Empty Declarations</a></li> 605</ul> 606</li> 607<li><a href="#operators-and-expressions">5. Operators and Expressions</a> 608<ul class="sectlevel2"> 609<li><a href="#operators">5.1. Operators</a></li> 610<li><a href="#array-operations">5.2. Array Operations</a></li> 611<li><a href="#function-calls">5.3. Function Calls</a></li> 612<li><a href="#constructors">5.4. Constructors</a></li> 613<li><a href="#vector-components">5.5. Vector Components</a></li> 614<li><a href="#matrix-components">5.6. Matrix Components</a></li> 615<li><a href="#structure-and-array-operations">5.7. Structure and Array Operations</a></li> 616<li><a href="#assignments">5.8. Assignments</a></li> 617<li><a href="#expressions">5.9. Expressions</a></li> 618<li><a href="#vector-and-matrix-operations">5.10. Vector and Matrix Operations</a></li> 619<li><a href="#specialization-constant-operations">5.11. Specialization-Constant Operations</a></li> 620<li><a href="#evaluation-of-expressions">5.12. Evaluation of Expressions</a></li> 621</ul> 622</li> 623<li><a href="#statements-and-structure">6. Statements and Structure</a> 624<ul class="sectlevel2"> 625<li><a href="#function-definitions">6.1. Function Definitions</a></li> 626<li><a href="#selection">6.2. Selection</a></li> 627<li><a href="#iteration">6.3. Iteration</a></li> 628<li><a href="#jumps">6.4. Jumps</a></li> 629</ul> 630</li> 631<li><a href="#built-in-variables">7. Built-In Variables</a> 632<ul class="sectlevel2"> 633<li><a href="#built-in-language-variables">7.1. Built-In Language Variables</a></li> 634<li><a href="#built-in-constants">7.2. Built-In Constants</a></li> 635<li><a href="#built-in-uniform-state">7.3. Built-In Uniform State</a></li> 636<li><a href="#redeclaring-built-in-blocks">7.4. Redeclaring Built-In Blocks</a></li> 637</ul> 638</li> 639<li><a href="#built-in-functions">8. Built-In Functions</a> 640<ul class="sectlevel2"> 641<li><a href="#angle-and-trigonometry-functions">8.1. Angle and Trigonometry Functions</a></li> 642<li><a href="#exponential-functions">8.2. Exponential Functions</a></li> 643<li><a href="#common-functions">8.3. Common Functions</a></li> 644<li><a href="#floating-point-pack-and-unpack-functions">8.4. Floating-Point Pack and Unpack Functions</a></li> 645<li><a href="#geometric-functions">8.5. Geometric Functions</a></li> 646<li><a href="#matrix-functions">8.6. Matrix Functions</a></li> 647<li><a href="#vector-relational-functions">8.7. Vector Relational Functions</a></li> 648<li><a href="#integer-functions">8.8. Integer Functions</a></li> 649<li><a href="#texture-functions">8.9. Texture Functions</a></li> 650<li><a href="#atomic-counter-functions">8.10. Atomic Counter Functions</a></li> 651<li><a href="#atomic-memory-functions">8.11. Atomic Memory Functions</a></li> 652<li><a href="#image-functions">8.12. Image Functions</a></li> 653<li><a href="#geometry-shader-functions">8.13. Geometry Shader Functions</a></li> 654<li><a href="#fragment-processing-functions">8.14. Fragment Processing Functions</a></li> 655<li><a href="#shader-invocation-control-functions">8.15. Shader Invocation Control Functions</a></li> 656<li><a href="#shader-memory-control-functions">8.16. Shader Memory Control Functions</a></li> 657<li><a href="#_subpass_input_functions">8.17. Subpass-Input Functions</a></li> 658</ul> 659</li> 660<li><a href="#shader-interface-matching">9. Shader Interface Matching</a> 661<ul class="sectlevel2"> 662<li><a href="#input-output-matching-by-name-in-linked-programs">9.1. Input Output Matching by Name in Linked Programs</a></li> 663<li><a href="#matching-of-qualifiers">9.2. Matching of Qualifiers</a></li> 664</ul> 665</li> 666<li><a href="#shading-language-grammar">10. Shading Language Grammar</a></li> 667<li><a href="#counting-of-inputs-and-outputs">11. Counting of Inputs and Outputs</a></li> 668<li><a href="#acknowledgments">12. Acknowledgments</a></li> 669<li><a href="#references">13. Normative References</a></li> 670<li><a href="#_non_normative_spir_v_mappings">14. Non-Normative SPIR-V Mappings</a> 671<ul class="sectlevel2"> 672<li><a href="#_feature_comparisons">14.1. Feature Comparisons</a></li> 673<li><a href="#_mapping_from_glsl_to_spir_v">14.2. Mapping from GLSL to SPIR-V</a></li> 674</ul> 675</li> 676</ul> 677</div> 678</div> 679<div id="content"> 680<div id="preamble"> 681<div class="sectionbody"> 682<div style="page-break-after: always;"></div> 683<div class="paragraph"> 684<p>Copyright © 2008-2018 The Khronos Group Inc. All Rights Reserved.</p> 685</div> 686<div class="paragraph"> 687<p>This specification is protected by copyright laws and contains material 688proprietary to the Khronos Group, Inc. It or any components may not be 689reproduced, republished, distributed, transmitted, displayed, broadcast, 690or otherwise exploited in any manner without the express prior written 691permission of Khronos Group. You may use this specification for 692implementing the functionality therein, without altering or removing any 693trademark, copyright or other notice from the specification, but the 694receipt or possession of this specification does not convey any rights 695to reproduce, disclose, or distribute its contents, or to manufacture, 696use, or sell anything that it may describe, in whole or in part.</p> 697</div> 698<div class="paragraph"> 699<p>Khronos Group grants express permission to any current Promoter, 700Contributor or Adopter member of Khronos to copy and redistribute 701UNMODIFIED versions of this specification in any fashion, provided that 702NO CHARGE is made for the specification and the latest available update 703of the specification for any version of the API is used whenever 704possible. Such distributed specification may be reformatted AS LONG AS 705the contents of the specification are not changed in any way. The 706specification may be incorporated into a product that is sold as long as 707such product includes significant independent work developed by the 708seller. A link to the current version of this specification on the 709Khronos Group website should be included whenever possible with 710specification distributions.</p> 711</div> 712<div class="paragraph"> 713<p>Khronos Group makes no, and expressly disclaims any, representations or 714warranties, express or implied, regarding this specification, including, 715without limitation, any implied warranties of merchantability or fitness 716for a particular purpose or noninfringement of any intellectual 717property. Khronos Group makes no, and expressly disclaims any, 718warranties, express or implied, regarding the correctness, accuracy, 719completeness, timeliness, and reliability of the specification. Under no 720circumstances will the Khronos Group, or any of its Promoters, 721Contributors or Members or their respective partners, officers, 722directors, employees, agents, or representatives be liable for any 723damages, whether direct, indirect, special or consequential damages for 724lost revenues, lost profits, or otherwise, arising from or in connection 725with these materials.</p> 726</div> 727<div class="paragraph"> 728<p>Khronos, Vulkan, SYCL, SPIR, WebGL, EGL, COLLADA, StreamInput, OpenVX, 729OpenKCam, glTF, OpenKODE, OpenVG, OpenWF, OpenSL ES, OpenMAX, OpenMAX 730AL, OpenMAX IL and OpenMAX DL are trademarks and WebCL is a 731certification mark of the Khronos Group Inc. OpenCL is a trademark of 732Apple Inc. and OpenGL and OpenML are registered trademarks and the 733OpenGL ES and OpenGL SC logos are trademarks of Silicon Graphics 734International used under license by Khronos. All other product names, 735trademarks, and/or company names are used solely for identification and 736belong to their respective owners.</p> 737</div> 738<div style="page-break-after: always;"></div> 739<!-- toc disabled --> 740</div> 741</div> 742<div class="sect1"> 743<h2 id="introduction">1. Introduction</h2> 744<div class="sectionbody"> 745<div class="paragraph"> 746<p>This document specifies only version 3.20 of the OpenGL ES Shading Language (GLSL ES). 747It requires __VERSION__ to substitute 320, and requires 748<strong>#version</strong> to accept only 749<code>320 es</code>. 750If <strong>#version</strong> is declared with a smaller number, the language accepted is a 751previous version of the shading language, which will be supported depending 752on the version and type of context in the API. 753See the <a href="#references">normative references</a> for details on what language 754versions are supported.</p> 755</div> 756<div class="paragraph"> 757<p>Throughout, when generating SPIR-V for consumption by the Vulkan API 758(see <a href="#references">normative references</a>), this will be said to be 759<em>targeting Vulkan</em>.</p> 760</div> 761<div class="paragraph"> 762<p>While this specification and the OpenGL ES Specification are normative for OpenGL ES Shading Language, for 763SPIR-V generation it is still the SPIR-V specification and the SPIR-V client 764API specification that are normative for the generated SPIR-V. 765See the <a href="#references">normative references</a> for further detail.</p> 766</div> 767<div class="paragraph"> 768<p>For SPIR-V generation, the SPIR-V client API specifies the commands used to 769manipulate SPIR-V shaders.</p> 770</div> 771<div class="paragraph"> 772<p>Independent offline tool chains will compile GLSL ES down to the SPIR-V 773intermediate language. 774SPIR-V generation is not enabled with a <strong>#extension</strong>, <strong>#version</strong>, or a 775profile. 776Instead, use of GLSL ES for SPIR-V is determined by offline tool-chain use. 777See the documentation of such tools to see how to request generation of 778SPIR-V for its client API.</p> 779</div> 780<div class="paragraph"> 781<p>GLSL ES → SPIR-V compilers must be directed as to what SPIR-V <strong>Capabilities</strong> 782are legal at run-time and give errors for GLSL ES feature use outside those 783capabilities. 784This is also true for implementation-dependent limits that can be error 785checked by the front-end against built-in constants present in the GLSL ES 786source: the front-end can be informed of such limits, and report errors when 787they are exceeded.</p> 788</div> 789<div class="paragraph"> 790<p>All references in this specification to the <a href="#references">OpenGL ES Specification</a> are to 791version 3.2.</p> 792</div> 793<div class="sect2"> 794<h3 id="changes">1.1. Changes</h3> 795<div class="sect3"> 796<h4 id="_changes_from_glsl_es_3_2_revision_5">1.1.1. Changes from GLSL ES 3.2 revision 5</h4> 797<div class="ulist"> 798<ul> 799<li> 800<p>Incorporated the GL_KHR_vulkan_glsl specification.</p> 801</li> 802<li> 803<p>Clarify it is same location that triggers default-uniform block matching 804rules. 805See <a href="#uniform-variable-layout-qualifiers">Uniform Variable Layout Qualifiers</a>.</p> 806</li> 807</ul> 808</div> 809</div> 810<div class="sect3"> 811<h4 id="changes-from-glsl-es-3.2-revision-4">1.1.2. Changes from GLSL ES 3.2 revision 4</h4> 812<div class="ulist"> 813<ul> 814<li> 815<p>Clarified that this specification completely defines the OpenGL ES Shading Language. 816Normatively reference C++ only for the preprocessor.</p> 817</li> 818<li> 819<p>Private GLSL issues 7, 38: Corrected the values of some builtin constants. 820The values were given correctly in the OpenGL ES Specification.</p> 821</li> 822<li> 823<p>Private GLSL issue 30: Clarify that output packing rules apply to the last 824vertex pipeline stage, not necessarily the vertex stage.</p> 825</li> 826<li> 827<p>Private GLSL issue 15: Clarify the ordering of bindings for arrays of arrays.</p> 828</li> 829<li> 830<p>Private GLSL issue 14: Uniform variables need only match at link time if they 831are statically used.</p> 832</li> 833<li> 834<p>For <strong>precise</strong> computations, the controlling expressions for 835control flow and ternary operators (<strong>?:</strong>) are not included.</p> 836</li> 837</ul> 838</div> 839</div> 840<div class="sect3"> 841<h4 id="changes-from-glsl-es-3.2-revision-3">1.1.3. Changes from GLSL ES 3.2 revision 3</h4> 842<div class="ulist"> 843<ul> 844<li> 845<p>Matching of default uniforms when shaders are linked.</p> 846</li> 847<li> 848<p><em>gl_DepthRange</em> is only guaranteed to be available in the fragment 849stage.</p> 850</li> 851<li> 852<p>Clarification of definition of static use.</p> 853</li> 854<li> 855<p>Sampling behavior in the absence of <strong>sample</strong> and <strong>centroid</strong>.</p> 856</li> 857<li> 858<p>Clarified the requirements when the specification uses the terms 859<em>should</em>/<em>should not</em> and <em>undefined behavior</em>.</p> 860</li> 861<li> 862<p>Arrayed blocks cannot have layout location qualifiers on members</p> 863</li> 864<li> 865<p><strong>barrier</strong>() defines a partial order which includes tessellation control 866shader outputs.</p> 867</li> 868<li> 869<p>Vertex shader integer output qualification.</p> 870</li> 871<li> 872<p>Incorrect use of predefined pragmas.</p> 873</li> 874<li> 875<p>Clarified use of <strong>readonly</strong> and <strong>writeonly</strong> qualifiers.</p> 876</li> 877<li> 878<p>USAMPLERBUFFER added to grammar.</p> 879</li> 880<li> 881<p>Clarified precision qualifiers can be used in interface blocks.</p> 882</li> 883<li> 884<p>Clarified <strong>memoryBarrierShared</strong> only applies to the current workgroup.</p> 885</li> 886<li> 887<p>The layout qualifier <em>invocations</em> must not be zero.</p> 888</li> 889<li> 890<p>The layout qualifier <em>local_size</em> must not be zero.</p> 891</li> 892<li> 893<p>Clarified the definition of static assignment.</p> 894</li> 895<li> 896<p>Removed list of types with no default precision.</p> 897</li> 898<li> 899<p>Removed scoping rules from the grammar. Refer instead to the <a href="#scoping">scoping</a> section.</p> 900</li> 901<li> 902<p>Require a statement after the final label of a switch.</p> 903</li> 904<li> 905<p>Define <strong>gl_BoundingBox</strong>.</p> 906</li> 907<li> 908<p><strong>length</strong>() expressions returning a constant-value may not include side effects.</p> 909</li> 910<li> 911<p>Clarified that variables may be declared <strong>readonly writeonly</strong>.</p> 912</li> 913<li> 914<p>Use of constant expressions within <strong>#line</strong> directives is undefined.</p> 915</li> 916<li> 917<p><strong>gl_in</strong> can be redeclared using unsized-array syntax.</p> 918</li> 919<li> 920<p>Clarified which sampler types may be used for depth and stencil textures.</p> 921</li> 922<li> 923<p>Added order-of-operation and other explanations to the 924<a href="#the-precise-qualifier">Precise Qualifier</a> section.</p> 925</li> 926<li> 927<p>The <strong>precise</strong> qualifier applied to a block/struct applies recursively to the members.</p> 928</li> 929</ul> 930</div> 931</div> 932<div class="sect3"> 933<h4 id="changes-from-glsl-es-3.2-revision-2">1.1.4. Changes from GLSL ES 3.2 revision 2</h4> 934<div class="ulist"> 935<ul> 936<li> 937<p>Updated value for <em>gl_MaxTessControlTotalOutputComponents</em></p> 938</li> 939<li> 940<p>Clarified the allowed character set for pre-processing</p> 941</li> 942<li> 943<p>Integer division wrapping behavior</p> 944</li> 945<li> 946<p>Clarified pre-processor expressions (<em>pp-constant-expression</em>)</p> 947</li> 948<li> 949<p>UBO and SSBO precisions do not need to match for linked shaders 950(consistent with GLSL ES 3.1)</p> 951</li> 952<li> 953<p><strong>modf</strong> function</p> 954</li> 955<li> 956<p>Sequence and ternary operators with <strong>void</strong> type</p> 957</li> 958<li> 959<p>Sequence and ternary operators with array types</p> 960</li> 961</ul> 962</div> 963</div> 964<div class="sect3"> 965<h4 id="changes-from-glsl-es-3.2-revision-1">1.1.5. Changes from GLSL ES 3.2 revision 1</h4> 966<div class="ulist"> 967<ul> 968<li> 969<p>Signed zeros must be supported</p> 970</li> 971<li> 972<p>Layout qualifier table</p> 973</li> 974<li> 975<p>Allowed optimizations when evaluating expressions</p> 976</li> 977<li> 978<p>Updated value for <em>gl_MaxTessControlInputComponents</em></p> 979</li> 980<li> 981<p>Updated value for <em>gl_MaxTessControlOutputComponents</em></p> 982</li> 983<li> 984<p>Updated value for <em>gl_MaxTessEvaluationInputComponents</em></p> 985</li> 986<li> 987<p>Updated value for <em>gl_MaxTessEvaluationOutputComponents</em></p> 988</li> 989<li> 990<p>Updated value for <em>gl_MaxGeometryOutputComponents</em></p> 991</li> 992<li> 993<p>Require precisions in blocks to match when linking</p> 994</li> 995<li> 996<p>Updated conclusions in issues section</p> 997</li> 998</ul> 999</div> 1000</div> 1001<div class="sect3"> 1002<h4 id="changes-from-glsl-es-3.1-revision-4">1.1.6. Changes from GLSL ES 3.1 revision 4</h4> 1003<div class="ulist"> 1004<ul> 1005<li> 1006<p>Added the following extensions:</p> 1007<div class="ulist"> 1008<ul> 1009<li> 1010<p><a href="https://www.opengl.org/registry/specs/KHR/blend_equation_advanced.txt">KHR_blend_equation_advanced</a></p> 1011</li> 1012<li> 1013<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_sample_variables.txt">OES_sample_variables</a></p> 1014</li> 1015<li> 1016<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_shader_image_atomic.txt">OES_shader_image_atomic</a></p> 1017</li> 1018<li> 1019<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_shader_multisample_interpolation.txt">OES_shader_multisample_interpolation</a></p> 1020</li> 1021<li> 1022<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_texture_storage_multisample_2d_array.txt">OES_texture_storage_multisample_2d_array</a></p> 1023</li> 1024<li> 1025<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_geometry_shader.txt">OES_geometry_shader</a></p> 1026</li> 1027<li> 1028<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_gpu_shader5.txt">OES_gpu_shader5</a></p> 1029</li> 1030<li> 1031<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_primitive_bounding_box.txt">OES_primitive_bounding_box</a></p> 1032</li> 1033<li> 1034<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_shader_io_blocks.txt">OES_shader_io_blocks</a></p> 1035</li> 1036<li> 1037<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_tessellation_shader.txt">OES_tessellation_shader</a></p> 1038</li> 1039<li> 1040<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_texture_buffer.txt">OES_texture_buffer</a></p> 1041</li> 1042<li> 1043<p><a href="https://www.khronos.org/registry/gles/extensions/OES/OES_texture_cube_map_array.txt">OES_texture_cube_map_array</a></p> 1044</li> 1045<li> 1046<p><a href="https://www.opengl.org/registry/specs/KHR/robustness.txt">KHR_robustness</a></p> 1047</li> 1048</ul> 1049</div> 1050</li> 1051</ul> 1052</div> 1053</div> 1054</div> 1055<div class="sect2"> 1056<h3 id="overview">1.2. Overview</h3> 1057<div class="paragraph"> 1058<p>This document describes <em>The OpenGL ES Shading Language, version 3.20</em>.</p> 1059</div> 1060<div class="paragraph"> 1061<p>Independent compilation units written in this language are called <em>shaders</em>. 1062A <em>program</em> is a set of shaders that are compiled and linked 1063together. 1064The aim of this document is to thoroughly specify the programming language. 1065The <a href="#references">normative references</a> will specify the API entry points 1066used to manipulate and communicate with programs and shaders.</p> 1067</div> 1068</div> 1069<div class="sect2"> 1070<h3 id="error-handling">1.3. Error Handling</h3> 1071<div class="paragraph"> 1072<p>Compilers, in general, accept programs that are ill-formed, due to the 1073impossibility of detecting all ill-formed programs. 1074Portability is only ensured for well-formed programs, which this 1075specification describes. 1076Compilers are encouraged to detect ill-formed programs and issue diagnostic 1077messages, but are not required to do so for all cases.</p> 1078</div> 1079<div class="paragraph"> 1080<p>The compilation process is implementation-dependent but is generally split 1081into a number of stages, each of which occurs at one of the following times:</p> 1082</div> 1083<div class="ulist"> 1084<ul> 1085<li> 1086<p>A call to <em>glCompileShader</em></p> 1087</li> 1088<li> 1089<p>A call to <em>glLinkProgram</em></p> 1090</li> 1091<li> 1092<p>A draw call or a call to <em>glValidateProgram</em></p> 1093</li> 1094</ul> 1095</div> 1096<div class="paragraph"> 1097<p>The implementation should report errors as early a possible but in any case 1098must satisfy the following:</p> 1099</div> 1100<div class="ulist"> 1101<ul> 1102<li> 1103<p>All lexical, grammatical and semantic errors must have been detected 1104following a call to <em>glLinkProgram</em></p> 1105</li> 1106<li> 1107<p>Errors due to mismatch between the shaders (link-time errors) must have 1108been detected following a call to <em>glLinkProgram</em></p> 1109</li> 1110<li> 1111<p>Errors due to exceeding resource limits must have been detected 1112following any draw call or a call to <em>glValidateProgram</em></p> 1113</li> 1114<li> 1115<p>A call to <em>glValidateProgram</em> must report all errors associated with a 1116program object given the current GL state.</p> 1117</li> 1118</ul> 1119</div> 1120<div class="paragraph"> 1121<p>Where the specification uses the terms <em>required</em>, <em>must</em>/<em>must</em> <em>not</em>, 1122<em>does</em>/<em>does</em> <em>not</em>, <em>disallowed</em>, or <em>not</em> <em>supported</em>, the compiler or 1123linker is required to detect and report any violations. 1124Similarly when a condition or situation is an <strong>error</strong>, it must be reported. 1125Use of any feature marked as <em>reserved</em> is an error. 1126Where the specification uses the terms <em>should</em>/<em>should</em> <em>not</em>, <em>undefined</em> 1127<em>behavior</em>, <em>undefined</em> <em>value</em> or <em>undefined</em> <em>*results*</em>, implementations 1128will not produce a compile-time error but are encouraged to issue a warning 1129for violations. 1130The run-time behavior of the program in these cases is not constrained (and 1131so may include termination or system instability). 1132It is expected that systems will be designed to handle these cases 1133gracefully but specification of this is outside the scope of this 1134specification.</p> 1135</div> 1136<div class="paragraph"> 1137<p>Implementations may not in general support functionality beyond the mandated 1138parts of the specification without use of the relevant extension. 1139The only exceptions are:</p> 1140</div> 1141<div class="olist arabic"> 1142<ol class="arabic"> 1143<li> 1144<p>If a feature is marked as optional.</p> 1145</li> 1146<li> 1147<p>Where a maximum value is stated (e.g. the maximum number of vertex 1148outputs), the implementation may support a higher value than that 1149specified.</p> 1150</li> 1151</ol> 1152</div> 1153<div class="paragraph"> 1154<p>Where the implementation supports more than the mandated specification, 1155off-target compilers are encouraged to issue warnings if these features are 1156used.</p> 1157</div> 1158<div class="paragraph"> 1159<p>The compilation process is split between the compiler and linker. 1160The allocation of tasks between the compiler and linker is implementation 1161dependent. 1162Consequently there are many errors which may be detected either at compile 1163or link time, depending on the implementation.</p> 1164</div> 1165</div> 1166<div class="sect2"> 1167<h3 id="typographical-conventions">1.4. Typographical Conventions</h3> 1168<div class="paragraph"> 1169<p>Italic, bold, and font choices have been used in this specification 1170primarily to improve readability. 1171Code fragments use a fixed width font. 1172Identifiers embedded in text are italicized. 1173Keywords embedded in text are bold. 1174Operators are called by their name, followed by their symbol in bold in 1175parentheses. 1176The clarifying grammar fragments in the text use bold for literals and 1177italics for non-terminals. 1178The official grammar in “<a href="#shading-language-grammar">Shading Language 1179Grammar</a>” uses all capitals for terminals and lower case for 1180non-terminals.</p> 1181</div> 1182</div> 1183<div class="sect2"> 1184<h3 id="compatibility">1.5. Compatibility</h3> 1185<div class="paragraph"> 1186<p>The OpenGL ES 3.2 API is designed to work with GLSL ES v1.00, 1187GLSL ES 3.00, GLSL ES 3.10 and GLSL ES 3.20. 1188In general a shader written for versions prior to OpenGL ES 3.2 1189should work without modification in OpenGL ES 3.2.</p> 1190</div> 1191<div class="paragraph"> 1192<p>When porting applications from an earlier to later version of the GLSL ES, 1193the following points should be noted:</p> 1194</div> 1195<div class="ulist"> 1196<ul> 1197<li> 1198<p>Not all language constructs present in earlier versions of the language 1199are available in later versions e.g. attribute and varying qualifiers 1200are present in v1.00 but not v3.00. 1201However, the functionality of GLSL ES 3.20 is a super-set of 1202GLSL ES 3.10.</p> 1203</li> 1204<li> 1205<p>Some features of later versions of the API require language features 1206that are not present in earlier version of the language.</p> 1207</li> 1208<li> 1209<p>It is an error to link shaders if they are written in different versions 1210of the language.</p> 1211</li> 1212<li> 1213<p>The OpenGL ES 2.0 and 3.0 APIs do not support shaders written in GLSL ES 12143.20.</p> 1215</li> 1216<li> 1217<p>Using GLSL ES 1.00 shaders within OpenGL ES 3.x may extend the resources 1218available beyond the minima specified in GLSL ES 1.0. 1219Shaders which make use of this will not necessarily run on an OpenGL ES 12202.0 implementation: Similarly for GLSL ES 3.00 shaders running within 1221OpenGL ES 3.2.</p> 1222</li> 1223<li> 1224<p>Support of line continuation and support of UTF-8 characters within 1225comments is optional in GLSL ES 1.00 when used with the OpenGL ES 2.0 1226API. 1227However, support is mandated for both of these when a GLSL ES 1.00 1228shader is used with the OpenGL ES 3.x APIs.</p> 1229</li> 1230</ul> 1231</div> 1232</div> 1233</div> 1234</div> 1235<div class="sect1"> 1236<h2 id="overview-of-opengl-shading">2. Overview of Shading</h2> 1237<div class="sectionbody"> 1238<div class="paragraph"> 1239<p>The OpenGL ES Shading Language is actually several closely related languages. 1240These languages are used to create shaders for each of the programmable 1241processors contained in the API’s processing pipeline. 1242Currently, these processors are the vertex, tessellation control, 1243tessellation evaluation, geometry, fragment, and compute processors.</p> 1244</div> 1245<div class="paragraph"> 1246<p>Compilation units for these processors are referred to as <em>shaders</em> and the 1247processors themselves are also referred to as <em>shader stages</em>. 1248Only one shader can be run on a processor at any one time; there is no 1249support for linking multiple compilation units together for a single shader 1250stage. 1251One or more shaders are linked together to form a single program and each 1252program contains shader <em>executables</em> for one or more consecutive shader 1253stages.</p> 1254</div> 1255<div class="paragraph"> 1256<p>Unless otherwise noted in this paper, a language feature applies to all 1257languages, and common usage will refer to these languages as a single 1258language. 1259The specific languages will be referred to by the name of the processor they 1260target: vertex, tessellation control, tessellation evaluation, geometry, 1261fragment, or compute.</p> 1262</div> 1263<div class="paragraph"> 1264<p>Most API state is not tracked or made available to shaders. 1265Typically, user-defined variables will be used for communicating between 1266different stages of the API pipeline. 1267However, a small amount of state is still tracked and automatically made 1268available to shaders, and there are a few built-in variables for interfaces 1269between different stages of the API pipeline.</p> 1270</div> 1271<div class="sect2"> 1272<h3 id="vertex-processor">2.1. Vertex Processor</h3> 1273<div class="paragraph"> 1274<p>The <em>vertex processor</em> is a programmable unit that operates on incoming 1275vertices and their associated data. 1276Compilation units written in the OpenGL ES Shading Language to run on this processor are called 1277<em>vertex shaders</em>.</p> 1278</div> 1279<div class="paragraph"> 1280<p>The vertex processor operates on one vertex at a time. 1281It does not replace graphics operations that require knowledge of several 1282vertices at a time.</p> 1283</div> 1284</div> 1285<div class="sect2"> 1286<h3 id="tessellation-control-processor">2.2. Tessellation Control Processor</h3> 1287<div class="paragraph"> 1288<p>The <em>tessellation control processor</em> is a programmable unit that operates on 1289a patch of incoming vertices and their associated data, emitting a new 1290output patch. 1291Compilation units written in the OpenGL ES Shading Language to run on this processor are called 1292tessellation control shaders.</p> 1293</div> 1294<div class="paragraph"> 1295<p>The tessellation control shader is invoked for each vertex of the output 1296patch. 1297Each invocation can read the attributes of any vertex in the input or output 1298patches, but can only write per-vertex attributes for the corresponding 1299output patch vertex. 1300The shader invocations collectively produce a set of per-patch attributes 1301for the output patch.</p> 1302</div> 1303<div class="paragraph"> 1304<p>After all tessellation control shader invocations have completed, the output 1305vertices and per-patch attributes are assembled to form a patch to be used 1306by subsequent pipeline stages.</p> 1307</div> 1308<div class="paragraph"> 1309<p>Tessellation control shader invocations run mostly independently, with 1310undefined relative execution order. 1311However, the built-in function <strong>barrier</strong>() can be used to control execution 1312order by synchronizing invocations, effectively dividing tessellation 1313control shader execution into a set of phases. 1314Tessellation control shaders will get undefined results if one invocation 1315reads from a per-vertex or per-patch attribute written by another invocation 1316at any point during the same phase, or if two invocations attempt to write 1317different values to the same per-patch output 1318in a single phase.</p> 1319</div> 1320</div> 1321<div class="sect2"> 1322<h3 id="tessellation-evaluation-processor">2.3. Tessellation Evaluation Processor</h3> 1323<div class="paragraph"> 1324<p>The <em>tessellation evaluation processor</em> is a programmable unit that 1325evaluates the position and other attributes of a vertex generated by the 1326tessellation primitive generator, using a patch of incoming vertices and 1327their associated data. 1328Compilation units written in the OpenGL ES Shading Language to run on this processor are called 1329tessellation evaluation shaders.</p> 1330</div> 1331<div class="paragraph"> 1332<p>Each invocation of the tessellation evaluation executable computes the 1333position and attributes of a single vertex generated by the tessellation 1334primitive generator. 1335The executable can read the attributes of any vertex in the input patch, 1336plus the tessellation coordinate, which is the relative location of the 1337vertex in the primitive being tessellated. 1338The executable writes the position and other attributes of the vertex.</p> 1339</div> 1340</div> 1341<div class="sect2"> 1342<h3 id="geometry-processor">2.4. Geometry Processor</h3> 1343<div class="paragraph"> 1344<p>The <em>geometry processor</em> is a programmable unit that operates on data for 1345incoming vertices for a primitive assembled after vertex processing and 1346outputs a sequence of vertices forming output primitives. 1347Compilation units written in the OpenGL ES Shading Language to run on this processor are called 1348<em>geometry shaders</em>.</p> 1349</div> 1350<div class="paragraph"> 1351<p>A single invocation of the geometry shader executable on the geometry 1352processor will operate on a declared input primitive with a fixed number of 1353vertices. 1354This single invocation can emit a variable number of vertices that are 1355assembled into primitives of a declared output primitive type and passed to 1356subsequent pipeline stages.</p> 1357</div> 1358</div> 1359<div class="sect2"> 1360<h3 id="fragment-processor">2.5. Fragment Processor</h3> 1361<div class="paragraph"> 1362<p>The <em>fragment processor</em> is a programmable unit that operates on fragment 1363values and their associated data. 1364Compilation units written in the OpenGL ES Shading Language to run on this processor are called 1365<em>fragment shaders</em>.</p> 1366</div> 1367<div class="paragraph"> 1368<p>A fragment shader cannot change a fragment’s (<em>x</em>, <em>y</em>) position. 1369Access to neighboring fragments is not allowed. 1370The values computed by the fragment shader are ultimately used to update 1371framebuffer memory or texture memory, depending on the current API 1372state and the API command that caused the fragments to be generated.</p> 1373</div> 1374</div> 1375<div class="sect2"> 1376<h3 id="compute-processor">2.6. Compute Processor</h3> 1377<div class="paragraph"> 1378<p>The <em>compute processor</em> is a programmable unit that operates independently 1379from the other shader processors. 1380Compilation units written in the OpenGL ES Shading Language to run on this processor are called 1381<em>compute shaders</em>.</p> 1382</div> 1383<div class="paragraph"> 1384<p>A compute shader has access to many of the same resources as fragment and 1385other shader processors, such as textures, buffers, image variables, and 1386atomic counters. 1387It does not have fixed-function outputs. 1388It is not part of the graphics pipeline and its visible side effects are 1389through changes to images, storage buffers, and atomic counters.</p> 1390</div> 1391<div class="paragraph"> 1392<p>A compute shader operates on a group of work items called a <em>workgroup</em>. 1393A workgroup is a collection of shader invocations that execute the same 1394code, potentially in parallel. 1395An invocation within a workgroup may share data with other members of the 1396same workgroup through shared variables and issue memory and control flow 1397barriers to synchronize with other members of the same workgroup.</p> 1398</div> 1399</div> 1400</div> 1401</div> 1402<div class="sect1"> 1403<h2 id="basics">3. Basics</h2> 1404<div class="sectionbody"> 1405<div class="sect2"> 1406<h3 id="character-set">3.1. Character Set</h3> 1407<div class="paragraph"> 1408<p>The source character set used for the OpenGL ES Shading Language is Unicode in the UTF-8 1409encoding scheme. 1410Invalid UTF-8 characters are ignored. 1411During pre-processing, the following applies:</p> 1412</div> 1413<div class="ulist"> 1414<ul> 1415<li> 1416<p>A byte with the value zero is always interpreted as the end of the 1417string</p> 1418</li> 1419<li> 1420<p>Backslash ('\'), is used to indicate line continuation when immediately 1421preceding a new-line.</p> 1422</li> 1423<li> 1424<p>White space consists of one or more of the following characters: the 1425space character, horizontal tab, vertical tab, form feed, 1426carriage-return, line-feed.</p> 1427</li> 1428<li> 1429<p>The number sign (<strong>#</strong>) is used for preprocessor directives</p> 1430</li> 1431<li> 1432<p>Macro names are restricted to:</p> 1433<div class="ulist"> 1434<ul> 1435<li> 1436<p>The letters <strong>a-z</strong>, <strong>A-Z</strong>, and the underscore (<strong>_</strong>).</p> 1437</li> 1438<li> 1439<p>The numbers <strong>0-9</strong>, except for the first character of a macro name.</p> 1440</li> 1441</ul> 1442</div> 1443</li> 1444</ul> 1445</div> 1446<div class="paragraph"> 1447<p>After preprocessing, only the following characters are allowed in the 1448resulting stream of GLSL ES tokens:</p> 1449</div> 1450<div class="ulist"> 1451<ul> 1452<li> 1453<p>The letters <strong>a-z</strong>, <strong>A-Z</strong>, and the underscore (<strong>_</strong>).</p> 1454</li> 1455<li> 1456<p>The numbers <strong>0-9</strong>.</p> 1457</li> 1458<li> 1459<p>The symbols period (<strong>.</strong>), plus (<strong>+</strong>), dash (<strong>-</strong>), slash (<strong>/</strong>), asterisk 1460(<strong>*</strong>), percent (<strong>%</strong>), angled brackets (<strong><</strong> and <strong>></strong>), square brackets 1461(<strong>[</strong> and <strong>]</strong>), parentheses (<strong>(</strong> and <strong>)</strong>), braces (<strong>{</strong> and <strong>}</strong>), caret 1462(<strong>^</strong>), vertical bar (<strong>|</strong>), ampersand (<strong>&</strong>), tilde (<strong>~</strong>), equals (<strong>=</strong>), 1463exclamation point (<strong>!</strong>), colon (<strong>:</strong>), semicolon (<strong>;</strong>), comma (<strong>,</strong>), and 1464question mark (<strong>?</strong>).</p> 1465</li> 1466</ul> 1467</div> 1468<div class="paragraph"> 1469<p>There are no digraphs or trigraphs. 1470There are no escape sequences or other uses of the backslash beyond use as 1471the line-continuation character.</p> 1472</div> 1473<div class="paragraph"> 1474<p>Lines are relevant for compiler diagnostic messages and the preprocessor. 1475They are terminated by carriage-return or line-feed. 1476If both are used together, it will count as only a single line termination. 1477For the remainder of this document, any of these combinations is simply 1478referred to as a new-line. 1479Lines may be of arbitrary length.</p> 1480</div> 1481<div class="paragraph"> 1482<p>In general, the language’s use of this character set is case sensitive.</p> 1483</div> 1484<div class="paragraph"> 1485<p>There are no character or string data types, so no quoting characters are 1486included.</p> 1487</div> 1488<div class="paragraph"> 1489<p>There is no end-of-file character.</p> 1490</div> 1491</div> 1492<div class="sect2"> 1493<h3 id="source-strings">3.2. Source Strings</h3> 1494<div class="paragraph"> 1495<p>The source for a single shader is an array of strings of characters from the 1496character set. 1497A single shader is made from the concatenation of these strings. 1498Each string can contain multiple lines, separated by new-lines. 1499No new-lines need be present in a string; a single line can be formed from 1500multiple strings. 1501No new-lines or other characters are inserted by the implementation when it 1502concatenates the strings to form a single shader.</p> 1503</div> 1504<div class="paragraph"> 1505<p>Diagnostic messages returned from compiling a shader must identify both the 1506line number within a string and which source string the message applies to. 1507Source strings are counted sequentially with the first string being string 15080. 1509Line numbers are one more than the number of new-lines that have been 1510processed, including counting the new-lines that will be removed by the 1511line-continuation character (<strong>\</strong>).</p> 1512</div> 1513<div class="paragraph"> 1514<p>Lines separated by the line-continuation character preceding a new-line are 1515concatenated together before either comment processing or preprocessing. 1516This means that no white space is substituted for the line-continuation 1517character. 1518That is, a single token could be formed by the concatenation by taking the 1519characters at the end of one line concatenating them with the characters at 1520the beginning of the next line.</p> 1521</div> 1522<div class="listingblock"> 1523<div class="content"> 1524<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span> f\ 1525oo; 1526<span class="comment">// forms a single line equivalent to "float foo;"</span> 1527<span class="comment">// (assuming '\' is the last character before the new-line and "oo" are</span> 1528<span class="comment">// the first two characters of the next line)</span></code></pre> 1529</div> 1530</div> 1531</div> 1532<div class="sect2"> 1533<h3 id="version-declaration">3.3. Version Declaration</h3> 1534<div class="paragraph"> 1535<p>Shaders must declare the version of the language they are written to. 1536The version is specified in the first line of a shader by a character 1537string:</p> 1538</div> 1539<div class="listingblock"> 1540<div class="content"> 1541<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#version</span> number es</code></pre> 1542</div> 1543</div> 1544<div class="paragraph"> 1545<p>where <em>number</em> must be a version of the language, following the same 1546convention as __VERSION__ above. 1547The directive “<strong>#version 320 es</strong>” is required in any shader that 1548uses version 3.20 of the language. 1549Any <em>number</em> representing a version of the language a compiler does not 1550support will cause an error to be generated. 1551Version 1.00 of the language does not require shaders to include this 1552directive, and shaders that do not include a <strong>#version</strong> directive will be 1553treated as targeting version 1.00.</p> 1554</div> 1555<div class="paragraph"> 1556<p>Shaders declaring version 3.20 of the shading language cannot be 1557linked with shaders declaring a previous version.</p> 1558</div> 1559<div class="paragraph"> 1560<p>The <strong>#version</strong> directive must be present in the first line of a shader and 1561must be followed by a newline. 1562It may contain optional white-space as specified below but no other 1563characters are allowed. 1564The directive is only permitted in the first line of a shader.</p> 1565</div> 1566<div class="paragraph"> 1567<p>Processing of the #version directive occurs before all other preprocessing, 1568including line concatenation and comment processing.</p> 1569</div> 1570<div class="openblock bnf"> 1571<div class="content"> 1572<div class="dlist"> 1573<dl> 1574<dt class="hdlist1"><em>version-declaration</em> : </dt> 1575<dd> 1576<p><em>whitespace<sub>opt</sub></em> POUND <em>whitespace<sub>opt</sub></em> VERSION <em>whitespace</em> <em>number</em> 1577<em>whitespace</em> ES <em>whitespace<sub>opt</sub></em></p> 1578</dd> 1579</dl> 1580</div> 1581</div> 1582</div> 1583<div class="paragraph"> 1584<p>Tokens:</p> 1585</div> 1586<div class="dlist"> 1587<dl> 1588<dt class="hdlist1"></dt> 1589<dd> 1590<p>POUND <strong>#</strong><br> 1591VERSION <strong>version</strong><br> 1592ES <strong>es</strong></p> 1593</dd> 1594</dl> 1595</div> 1596</div> 1597<div class="sect2"> 1598<h3 id="preprocessor">3.4. Preprocessor</h3> 1599<div class="paragraph"> 1600<p>There is a preprocessor that processes the source strings as part of the 1601compilation process. 1602Except as noted below, it behaves as the C++ standard preprocessor (see 1603“<a href="#references">Normative References</a>”).</p> 1604</div> 1605<div class="paragraph"> 1606<p>The complete list of preprocessor directives is as follows.</p> 1607</div> 1608<div class="dlist"> 1609<dl> 1610<dt class="hdlist1"></dt> 1611<dd> 1612<p>#<br> 1613#define<br> 1614#undef<br></p> 1615</dd> 1616<dt class="hdlist1"></dt> 1617<dd> 1618<p>#if<br> 1619#ifdef<br> 1620#ifndef<br> 1621#else<br> 1622#elif<br> 1623#endif<br></p> 1624</dd> 1625<dt class="hdlist1"></dt> 1626<dd> 1627<p>#error<br> 1628#pragma<br></p> 1629</dd> 1630<dt class="hdlist1"></dt> 1631<dd> 1632<p>#extension<br></p> 1633</dd> 1634<dt class="hdlist1"></dt> 1635<dd> 1636<p>#line</p> 1637</dd> 1638</dl> 1639</div> 1640<div class="paragraph"> 1641<p>The following 1642operator is 1643also available:</p> 1644</div> 1645<div class="dlist"> 1646<dl> 1647<dt class="hdlist1"></dt> 1648<dd> 1649<p>defined<br></p> 1650</dd> 1651</dl> 1652</div> 1653<div class="paragraph"> 1654<p>Note that the version directive is not considered to be a preprocessor 1655directive and so is not listed here.</p> 1656</div> 1657<div class="paragraph"> 1658<p>Each number sign (<strong>#</strong>) can be preceded in its line only by spaces or 1659horizontal tabs. 1660It may also be followed by spaces and horizontal tabs, preceding the 1661directive. 1662Each directive is terminated by a new-line. 1663Preprocessing does not change the number or relative location of new-lines 1664in a source string.</p> 1665</div> 1666<div class="paragraph"> 1667<p>The number sign (<strong>#</strong>) on a line by itself is ignored. 1668Any directive not listed above will cause an error.</p> 1669</div> 1670<div class="paragraph"> 1671<p><strong>#define</strong> and <strong>#undef</strong> functionality are defined as is standard for C++ 1672preprocessors for macro definitions both with and without macro parameters.</p> 1673</div> 1674<div class="paragraph"> 1675<p>The following predefined macros are available:</p> 1676</div> 1677<div class="dlist"> 1678<dl> 1679<dt class="hdlist1"></dt> 1680<dd> 1681<p>__LINE__<br> 1682__FILE__<br> 1683__VERSION__<br> 1684GL_ES</p> 1685</dd> 1686</dl> 1687</div> 1688<div class="paragraph"> 1689<p>__LINE__ will substitute a decimal integer constant that is one more than 1690the number of preceding new-lines in the current source string.</p> 1691</div> 1692<div class="paragraph"> 1693<p>__FILE__ will substitute a decimal integer constant that says which source 1694string number is currently being processed.</p> 1695</div> 1696<div class="paragraph"> 1697<p>__VERSION__ will substitute a decimal integer reflecting the version 1698number of the OpenGL ES Shading Language. 1699The version of the shading language described in this document will have 1700__VERSION__ substitute the decimal integer 320.</p> 1701</div> 1702<div class="paragraph"> 1703<p>GL_ES will be defined and set to 1. 1704This is not true for the non-ES OpenGL Shading Language, so it can be used 1705to do a compile time test to determine if a shader is compiling as an 1706GLSL ES shader.</p> 1707</div> 1708<div class="paragraph"> 1709<p>By convention, all macro names containing two consecutive underscores (__) 1710are reserved for use by underlying software layers. 1711Defining 1712such a name in a shader does not itself result in an error, but may 1713result in unintended behaviors that stem from having multiple definitions of 1714the same name. 1715All macro names prefixed with “GL_” (“GL” followed by a single 1716underscore) are also reserved, and defining 1717such a name results in a compile-time error.</p> 1718</div> 1719<div class="paragraph"> 1720<p>It is an error to undefine or to redefine a built-in (pre-defined) macro 1721name.</p> 1722</div> 1723<div class="paragraph"> 1724<p>Implementations must support macro-name lengths of up to 1024 characters. 1725It is an error to declare a name with a length greater than this.</p> 1726</div> 1727<div class="paragraph"> 1728<p><strong>#if</strong>, <strong>#ifdef</strong>, <strong>#ifndef</strong>, <strong>#else</strong>, <strong>#elif</strong>, and <strong>#endif</strong> are defined to 1729operate as is standard for C++ preprocessors except for the following:</p> 1730</div> 1731<div class="ulist"> 1732<ul> 1733<li> 1734<p>Expressions following <strong>#if</strong> and <strong>#elif</strong> are 1735restricted to <em>pp-constant-expressions</em> as defined below.</p> 1736</li> 1737<li> 1738<p>Undefined identifiers not consumed by the <strong>defined</strong> operator do not 1739default to '0'. 1740Use of such identifiers causes an error.</p> 1741</li> 1742<li> 1743<p>Character constants are not supported.</p> 1744</li> 1745</ul> 1746</div> 1747<div class="paragraph"> 1748<p>As in C++, a macro name defined with an empty replacement list does not 1749default to '0' when used in a preprocessor expression.</p> 1750</div> 1751<div class="paragraph"> 1752<p>A <em>pp-constant-expression</em> is an integral expression, evaluated at 1753compile-time during preprocessing and formed from literal integer constants 1754and the following operators:</p> 1755</div> 1756<table class="tableblock frame-all grid-all stretch"> 1757<colgroup> 1758<col style="width: 25%;"> 1759<col style="width: 25%;"> 1760<col style="width: 25%;"> 1761<col style="width: 25%;"> 1762</colgroup> 1763<thead> 1764<tr> 1765<th class="tableblock halign-left valign-top">Precedence</th> 1766<th class="tableblock halign-left valign-top">Operator class</th> 1767<th class="tableblock halign-left valign-top">Operators</th> 1768<th class="tableblock halign-left valign-top">Associativity</th> 1769</tr> 1770</thead> 1771<tbody> 1772<tr> 1773<td class="tableblock halign-left valign-top"><p class="tableblock">1 (highest)</p></td> 1774<td class="tableblock halign-left valign-top"><p class="tableblock">parenthetical grouping</p></td> 1775<td class="tableblock halign-left valign-top"><p class="tableblock">( )</p></td> 1776<td class="tableblock halign-left valign-top"><p class="tableblock">NA</p></td> 1777</tr> 1778<tr> 1779<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> 1780<td class="tableblock halign-left valign-top"><p class="tableblock">unary</p></td> 1781<td class="tableblock halign-left valign-top"><p class="tableblock">defined<br> 1782 + - ~ !</p></td> 1783<td class="tableblock halign-left valign-top"><p class="tableblock">Right to Left</p></td> 1784</tr> 1785<tr> 1786<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> 1787<td class="tableblock halign-left valign-top"><p class="tableblock">multiplicative</p></td> 1788<td class="tableblock halign-left valign-top"><p class="tableblock">* / %</p></td> 1789<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 1790</tr> 1791<tr> 1792<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> 1793<td class="tableblock halign-left valign-top"><p class="tableblock">additive</p></td> 1794<td class="tableblock halign-left valign-top"><p class="tableblock">+ -</p></td> 1795<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 1796</tr> 1797<tr> 1798<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> 1799<td class="tableblock halign-left valign-top"><p class="tableblock">bit-wise shift</p></td> 1800<td class="tableblock halign-left valign-top"><p class="tableblock"><< >></p></td> 1801<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 1802</tr> 1803<tr> 1804<td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> 1805<td class="tableblock halign-left valign-top"><p class="tableblock">relational</p></td> 1806<td class="tableblock halign-left valign-top"><p class="tableblock">< > <= >=</p></td> 1807<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 1808</tr> 1809<tr> 1810<td class="tableblock halign-left valign-top"><p class="tableblock">7</p></td> 1811<td class="tableblock halign-left valign-top"><p class="tableblock">equality</p></td> 1812<td class="tableblock halign-left valign-top"><p class="tableblock">== !=</p></td> 1813<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 1814</tr> 1815<tr> 1816<td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td> 1817<td class="tableblock halign-left valign-top"><p class="tableblock">bit-wise and</p></td> 1818<td class="tableblock halign-left valign-top"><p class="tableblock">&</p></td> 1819<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 1820</tr> 1821<tr> 1822<td class="tableblock halign-left valign-top"><p class="tableblock">9</p></td> 1823<td class="tableblock halign-left valign-top"><p class="tableblock">bit-wise exclusive or</p></td> 1824<td class="tableblock halign-left valign-top"><p class="tableblock">^</p></td> 1825<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 1826</tr> 1827<tr> 1828<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td> 1829<td class="tableblock halign-left valign-top"><p class="tableblock">bit-wise inclusive or</p></td> 1830<td class="tableblock halign-left valign-top"><p class="tableblock">|</p></td> 1831<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 1832</tr> 1833<tr> 1834<td class="tableblock halign-left valign-top"><p class="tableblock">11</p></td> 1835<td class="tableblock halign-left valign-top"><p class="tableblock">logical and</p></td> 1836<td class="tableblock halign-left valign-top"><p class="tableblock">&&</p></td> 1837<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 1838</tr> 1839<tr> 1840<td class="tableblock halign-left valign-top"><p class="tableblock">12 (lowest)</p></td> 1841<td class="tableblock halign-left valign-top"><p class="tableblock">logical inclusive or</p></td> 1842<td class="tableblock halign-left valign-top"><p class="tableblock">||</p></td> 1843<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 1844</tr> 1845</tbody> 1846</table> 1847<div class="paragraph"> 1848<p>The <strong>defined</strong> operator can be used in either of the following ways:</p> 1849</div> 1850<div class="listingblock"> 1851<div class="content"> 1852<pre class="CodeRay highlight"><code data-lang="c++">defined identifier 1853defined ( identifier )</code></pre> 1854</div> 1855</div> 1856<div class="paragraph"> 1857<p>There are no number sign based operators (e.g. no <strong><mark></strong> or <strong></mark>@</strong>), no <strong>##</strong> 1858operator, nor is there a <strong>sizeof</strong> operator.</p> 1859</div> 1860<div class="paragraph"> 1861<p>The semantics of applying operators in the preprocessor match those standard 1862in the C++ preprocessor with the following exceptions:</p> 1863</div> 1864<div class="ulist"> 1865<ul> 1866<li> 1867<p>The 2<sup>nd</sup> operand in a logical and ('&&') operation is evaluated if and 1868only if the 1<sup>st</sup> operand evaluates to non-zero.</p> 1869</li> 1870<li> 1871<p>The 2<sup>nd</sup> operand in a logical or ('||') operation is evaluated if and 1872only if the 1<sup>st</sup> operand evaluates to zero.</p> 1873</li> 1874<li> 1875<p>There is no boolean type and no boolean literals. 1876A <em>true</em> or <em>false</em> result is returned as integer <em>one</em> or <em>zero</em> 1877respectively. 1878Wherever a boolean operand is expected, any non-zero integer is 1879interpreted as <em>true</em> and a zero integer as <em>false</em>.</p> 1880</li> 1881</ul> 1882</div> 1883<div class="paragraph"> 1884<p>If an operand is not evaluated, the presence of undefined identifiers in the 1885operand will not cause an error.</p> 1886</div> 1887<div class="paragraph"> 1888<p><strong>#error</strong> will cause the implementation to put a compile-time diagnostic message 1889into the shader object’s information log (see section 7.12 “Shader, Program 1890and Program Pipeline Queries” of the <a href="#references">OpenGL ES Specification</a> for how to 1891access a shader object’s information log). 1892The message will be the tokens following the <strong>#error</strong> directive, up to the 1893first new-line. 1894The implementation must treat the presence of a <strong>#error</strong> directive as a 1895compile-time error.</p> 1896</div> 1897<div class="paragraph"> 1898<p><strong>#pragma</strong> allows implementation-dependent compiler control. 1899Tokens following <strong>#pragma</strong> are not subject to preprocessor macro expansion. 1900If an implementation does not recognize the tokens following <strong>#pragma</strong>, then 1901it will ignore that pragma. 1902The following pragmas are defined as part of the language.</p> 1903</div> 1904<div class="listingblock"> 1905<div class="content"> 1906<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#pragma</span> STDGL</code></pre> 1907</div> 1908</div> 1909<div class="paragraph"> 1910<p>The <strong>STDGL</strong> pragma is used to reserve pragmas for use by future revisions of 1911this language. 1912No implementation may use a pragma whose first token is <strong>STDGL</strong>.</p> 1913</div> 1914<div class="listingblock"> 1915<div class="content"> 1916<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#pragma</span> optimize(on) 1917<span class="preprocessor">#pragma</span> optimize(off)</code></pre> 1918</div> 1919</div> 1920<div class="paragraph"> 1921<p>can be used to turn off optimizations as an aid in developing and debugging 1922shaders. 1923It can only be used outside function definitions. 1924By default, optimization is turned on for all shaders. 1925The debug pragma</p> 1926</div> 1927<div class="listingblock"> 1928<div class="content"> 1929<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#pragma</span> debug(on) 1930<span class="preprocessor">#pragma</span> debug(off)</code></pre> 1931</div> 1932</div> 1933<div class="paragraph"> 1934<p>can be used to enable compiling and annotating a shader with debug 1935information, so that it can be used with a debugger. 1936It can only be used outside function definitions. 1937By default, debug is turned off.</p> 1938</div> 1939<div class="paragraph"> 1940<p>The scope as well as the effect of the optimize and debug pragmas is 1941implementation-dependent except that their use must not generate an error. 1942Incorrect use of predefined pragmas does not cause an error.</p> 1943</div> 1944<div class="paragraph"> 1945<p>By default, compilers of this language must issue compile-time 1946syntactic, semantic, 1947and 1948grammatical errors for shaders that do not conform to this specification. 1949Any extended behavior must first be enabled. 1950Directives to control the behavior of the compiler with respect to 1951extensions are declared with the <strong>#extension</strong> directive</p> 1952</div> 1953<div class="listingblock"> 1954<div class="content"> 1955<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#extension</span> extension_name : behavior 1956<span class="preprocessor">#extension</span> all : behavior</code></pre> 1957</div> 1958</div> 1959<div class="paragraph"> 1960<p>where <em>extension_name</em> is the name of an extension. 1961Extension names are not documented in this specification. 1962The token <strong>all</strong> means the behavior applies to all extensions supported by 1963the compiler. 1964The <em>behavior</em> can be one of the following:</p> 1965</div> 1966<table class="tableblock frame-all grid-all stretch"> 1967<colgroup> 1968<col style="width: 50%;"> 1969<col style="width: 50%;"> 1970</colgroup> 1971<thead> 1972<tr> 1973<th class="tableblock halign-left valign-top">Behavior</th> 1974<th class="tableblock halign-left valign-top">Effect</th> 1975</tr> 1976</thead> 1977<tbody> 1978<tr> 1979<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>require</strong></p></td> 1980<td class="tableblock halign-left valign-top"><p class="tableblock">Behave as specified by the extension <em>extension_name</em>.<br> 1981 Give a compile-time error on the <strong>#extension</strong> if the extension 1982 <em>extension_name</em> is not supported, or if <strong>all</strong> is specified.</p></td> 1983</tr> 1984<tr> 1985<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>enable</strong></p></td> 1986<td class="tableblock halign-left valign-top"><p class="tableblock">Behave as specified by the extension <em>extension_name</em>.<br> 1987 Warn on the <strong>#extension</strong> if the extension <em>extension_name</em> is 1988 not supported.<br> 1989 Give an error on the <strong>#extension</strong> if <strong>all</strong> is 1990 specified.</p></td> 1991</tr> 1992<tr> 1993<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>warn</strong></p></td> 1994<td class="tableblock halign-left valign-top"><p class="tableblock">Behave as specified by the extension <em>extension_name</em>, 1995 except issue warnings on any detectable use of that extension, 1996 unless such use is supported by other enabled or required 1997 extensions.<br> 1998 If <strong>all</strong> is specified, then warn on all detectable uses of any 1999 extension used.<br> 2000 Warn on the <strong>#extension</strong> if the extension <em>extension_name</em> is 2001 not supported.</p></td> 2002</tr> 2003<tr> 2004<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>disable</strong></p></td> 2005<td class="tableblock halign-left valign-top"><p class="tableblock">Behave (including issuing errors and warnings) as if the 2006 extension <em>extension_name</em> is not part of the language 2007 definition.<br> 2008 If <strong>all</strong> is specified, then behavior must revert back to that 2009 of the non-extended core version of the language being 2010 compiled to.<br> 2011 Warn on the <strong>#extension</strong> if the extension <em>extension_name</em> is 2012 not supported.</p></td> 2013</tr> 2014</tbody> 2015</table> 2016<div class="paragraph"> 2017<p>The <strong>extension</strong> directive is a simple, low-level mechanism to set the 2018behavior for each extension. 2019It does not define policies such as which combinations are appropriate, 2020those must be defined elsewhere. 2021Order of directives matters in setting the behavior for each extension: 2022Directives that occur later override those seen earlier. 2023The <strong>all</strong> variant sets the behavior for all extensions, overriding all 2024previously issued <strong>extension</strong> directives, but only for the <em>behaviors</em> 2025<strong>warn</strong> and <strong>disable</strong>.</p> 2026</div> 2027<div class="paragraph"> 2028<p>The initial state of the compiler is as if the directive</p> 2029</div> 2030<div class="listingblock"> 2031<div class="content"> 2032<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#extension</span> all : disable</code></pre> 2033</div> 2034</div> 2035<div class="paragraph"> 2036<p>was issued, telling the compiler that all error and warning reporting must 2037be done according to this specification, ignoring any extensions.</p> 2038</div> 2039<div class="paragraph"> 2040<p>Each extension can define its allowed granularity of scope. 2041If nothing is said, the granularity is a shader (that is, a single 2042compilation unit), and the extension directives must occur before any 2043non-preprocessor tokens. 2044If necessary, the linker can enforce granularities larger than a single 2045compilation unit, in which case each involved shader will have to contain 2046the necessary extension directive.</p> 2047</div> 2048<div class="paragraph"> 2049<p>Macro expansion is not done on lines containing <strong>#extension</strong> and <strong>#version</strong> 2050directives.</p> 2051</div> 2052<div class="paragraph"> 2053<p>For each extension there is an associated macro. 2054The macro is always defined in an implementation that supports the 2055extension. 2056This allows the following construct to be used:</p> 2057</div> 2058<div class="listingblock"> 2059<div class="content"> 2060<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#ifdef</span> OES_extension_name 2061 <span class="preprocessor">#extension</span> OES_extension_name : enable 2062 <span class="comment">// code that requires the extension</span> 2063<span class="preprocessor">#else</span> 2064 <span class="comment">// alternative code</span> 2065<span class="preprocessor">#endif</span></code></pre> 2066</div> 2067</div> 2068<div class="paragraph"> 2069<p><strong>#line</strong> must have, after macro substitution, one of the following forms:</p> 2070</div> 2071<div class="listingblock"> 2072<div class="content"> 2073<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#line</span> line 2074<span class="preprocessor">#line</span> line source-<span class="predefined-type">string</span>-number</code></pre> 2075</div> 2076</div> 2077<div class="paragraph"> 2078<p>where <em>line</em> and <em>source-string-number</em> are 2079<em>pp-constant-expressions</em>. 2080If these constant expressions are not integer literals then behavior is undefined. 2081After processing this directive (including its new-line), the implementation 2082will behave as if it is compiling at line number <em>line</em> and source string 2083number <em>source-string-number</em>. 2084Subsequent source strings will be numbered sequentially, until another 2085<strong>#line</strong> directive overrides that numbering.</p> 2086</div> 2087<div class="admonitionblock note"> 2088<table> 2089<tr> 2090<td class="icon"> 2091<i class="fa icon-note" title="Note"></i> 2092</td> 2093<td class="content"> 2094<div class="title">Note</div> 2095<div class="paragraph"> 2096<p>Some implementations have allowed constant expressions in #line directives and 2097some have not. Even where expressions are supported the grammar is ambiguous and so 2098results are implementation dependent. For example, 2099+ #line +2 +2 // Line number set to 4, or file to 2 and line to 2</p> 2100</div> 2101</td> 2102</tr> 2103</table> 2104</div> 2105<div class="paragraph"> 2106<p>When targeting Vulkan, the following predefined macro is available:</p> 2107</div> 2108<div class="listingblock"> 2109<div class="content"> 2110<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#define</span> VULKAN <span class="integer">100</span></code></pre> 2111</div> 2112</div> 2113<div class="paragraph"> 2114<p>If during macro expansion a preprocessor directive is encountered, the 2115results are undefined; the compiler may or may not report an error in such 2116cases.</p> 2117</div> 2118</div> 2119<div class="sect2"> 2120<h3 id="comments">3.5. Comments</h3> 2121<div class="paragraph"> 2122<p>Comments are delimited by <strong>/*</strong> and <strong>*/</strong>, or by <strong>//</strong> and a new-line. 2123// style comments include the initial // marker and continue up to, but 2124not including, the terminating newline. 2125/*...*/ comments include both the start and end marker. 2126The begin comment delimiters (/* or //) are not recognized as comment 2127delimiters inside of a comment, hence comments cannot be nested. 2128Comments are treated syntactically as a single space.</p> 2129</div> 2130</div> 2131<div class="sect2"> 2132<h3 id="tokens">3.6. Tokens</h3> 2133<div class="paragraph"> 2134<p>The language, after preprocessing, is a sequence of tokens. 2135A token can be</p> 2136</div> 2137<div class="openblock bnf"> 2138<div class="content"> 2139<div class="dlist"> 2140<dl> 2141<dt class="hdlist1"><em>token</em> : </dt> 2142<dd> 2143<p><em>keyword</em><br> 2144<em>identifier</em><br> 2145<em>integer-constant</em><br> 2146<em>floating-constant</em><br> 2147<em>operator</em><br> 2148<strong>;</strong> <strong>{</strong> <strong>}</strong></p> 2149</dd> 2150</dl> 2151</div> 2152</div> 2153</div> 2154</div> 2155<div class="sect2"> 2156<h3 id="keywords">3.7. Keywords</h3> 2157<div class="paragraph"> 2158<p>The following are the keywords in the language and (after 2159preprocessing) can only be used as described in this specification, 2160or an error results:</p> 2161</div> 2162<div class="dlist"> 2163<dl> 2164<dt class="hdlist1"></dt> 2165<dd> 2166<p><strong>const</strong> <strong>uniform</strong> <strong>buffer</strong> <strong>shared</strong></p> 2167</dd> 2168<dt class="hdlist1"></dt> 2169<dd> 2170<p><strong>coherent</strong> <strong>volatile</strong> <strong>restrict</strong> <strong>readonly</strong> <strong>writeonly</strong></p> 2171</dd> 2172<dt class="hdlist1"></dt> 2173<dd> 2174<p><strong>atomic_uint</strong></p> 2175</dd> 2176<dt class="hdlist1"></dt> 2177<dd> 2178<p><strong>layout</strong></p> 2179</dd> 2180<dt class="hdlist1"></dt> 2181<dd> 2182<p><strong>centroid</strong> <strong>flat</strong> <strong>smooth</strong></p> 2183</dd> 2184<dt class="hdlist1"></dt> 2185<dd> 2186<p><strong>patch</strong> <strong>sample</strong></p> 2187</dd> 2188<dt class="hdlist1"></dt> 2189<dd> 2190<p><strong>invariant</strong> <strong>precise</strong></p> 2191</dd> 2192<dt class="hdlist1"></dt> 2193<dd> 2194<p><strong>break</strong> <strong>continue</strong> <strong>do</strong> <strong>for</strong> <strong>while</strong> <strong>switch</strong> <strong>case</strong> <strong>default</strong></p> 2195</dd> 2196<dt class="hdlist1"></dt> 2197<dd> 2198<p><strong>if</strong> <strong>else</strong></p> 2199</dd> 2200<dt class="hdlist1"></dt> 2201<dd> 2202<p><strong>in</strong> <strong>out</strong> <strong>inout</strong></p> 2203</dd> 2204<dt class="hdlist1"></dt> 2205<dd> 2206<p><strong>int</strong> <strong>void</strong> <strong>bool</strong> <strong>true</strong> <strong>false</strong> <strong>float</strong></p> 2207</dd> 2208<dt class="hdlist1"></dt> 2209<dd> 2210<p><strong>discard</strong> <strong>return</strong></p> 2211</dd> 2212<dt class="hdlist1"></dt> 2213<dd> 2214<p><strong>vec2</strong> <strong>vec3</strong> <strong>vec4</strong> <strong>ivec2</strong> <strong>ivec3</strong> <strong>ivec4</strong> <strong>bvec2</strong> <strong>bvec3</strong> <strong>bvec4</strong></p> 2215</dd> 2216<dt class="hdlist1"></dt> 2217<dd> 2218<p><strong>uint</strong> <strong>uvec2</strong> <strong>uvec3</strong> <strong>uvec4</strong></p> 2219</dd> 2220<dt class="hdlist1"></dt> 2221<dd> 2222<p><strong>mat2</strong> <strong>mat3</strong> <strong>mat4</strong></p> 2223</dd> 2224<dt class="hdlist1"></dt> 2225<dd> 2226<p><strong>mat2x2</strong> <strong>mat2x3</strong> <strong>mat2x4</strong></p> 2227</dd> 2228<dt class="hdlist1"></dt> 2229<dd> 2230<p><strong>mat3x2</strong> <strong>mat3x3</strong> <strong>mat3x4</strong></p> 2231</dd> 2232<dt class="hdlist1"></dt> 2233<dd> 2234<p><strong>mat4x2</strong> <strong>mat4x3</strong> <strong>mat4x4</strong></p> 2235</dd> 2236<dt class="hdlist1"></dt> 2237<dd> 2238<p><strong>lowp</strong> <strong>mediump</strong> <strong>highp</strong> <strong>precision</strong></p> 2239</dd> 2240<dt class="hdlist1"></dt> 2241<dd> 2242<p><strong>sampler2D</strong> <strong>sampler2DShadow</strong> <strong>sampler2DArray</strong> <strong>sampler2DArrayShadow</strong></p> 2243</dd> 2244<dt class="hdlist1"></dt> 2245<dd> 2246<p><strong>isampler2D</strong> <strong>isampler2DArray</strong> <strong>usampler2D</strong> <strong>usampler2DArray</strong></p> 2247</dd> 2248<dt class="hdlist1"></dt> 2249<dd> 2250<p><strong>sampler2DMS</strong> <strong>isampler2DMS</strong> <strong>usampler2DMS</strong></p> 2251</dd> 2252<dt class="hdlist1"></dt> 2253<dd> 2254<p><strong>sampler2DMSArray</strong> <strong>isampler2DMSArray</strong> <strong>usampler2DMSArray</strong></p> 2255</dd> 2256<dt class="hdlist1"></dt> 2257<dd> 2258<p><strong>sampler3D</strong> <strong>isampler3D</strong> <strong>usampler3D</strong></p> 2259</dd> 2260<dt class="hdlist1"></dt> 2261<dd> 2262<p><strong>samplerCube</strong> <strong>samplerCubeShadow</strong> <strong>isamplerCube</strong> <strong>usamplerCube</strong></p> 2263</dd> 2264<dt class="hdlist1"></dt> 2265<dd> 2266<p><strong>samplerCubeArray</strong> <strong>samplerCubeArrayShadow</strong></p> 2267</dd> 2268<dt class="hdlist1"></dt> 2269<dd> 2270<p><strong>isamplerCubeArray</strong> <strong>usamplerCubeArray</strong></p> 2271</dd> 2272<dt class="hdlist1"></dt> 2273<dd> 2274<p><strong>samplerBuffer</strong> <strong>isamplerBuffer</strong> <strong>usamplerBuffer</strong></p> 2275</dd> 2276<dt class="hdlist1"></dt> 2277<dd> 2278<p><strong>image2D</strong> <strong>iimage2D</strong> <strong>uimage2D</strong></p> 2279</dd> 2280<dt class="hdlist1"></dt> 2281<dd> 2282<p><strong>image2DArray</strong> <strong>iimage2DArray</strong> <strong>uimage2DArray</strong></p> 2283</dd> 2284<dt class="hdlist1"></dt> 2285<dd> 2286<p><strong>image3D</strong> <strong>iimage3D</strong> <strong>uimage3D</strong></p> 2287</dd> 2288<dt class="hdlist1"></dt> 2289<dd> 2290<p><strong>imageCube</strong> <strong>iimageCube</strong> <strong>uimageCube</strong></p> 2291</dd> 2292<dt class="hdlist1"></dt> 2293<dd> 2294<p><strong>imageCubeArray</strong> <strong>iimageCubeArray</strong> <strong>uimageCubeArray</strong></p> 2295</dd> 2296<dt class="hdlist1"></dt> 2297<dd> 2298<p><strong>imageBuffer</strong> <strong>iimageBuffer</strong> <strong>uimageBuffer</strong></p> 2299</dd> 2300<dt class="hdlist1"></dt> 2301<dd> 2302<p><strong>struct</strong></p> 2303</dd> 2304</dl> 2305</div> 2306<div class="paragraph"> 2307<p>In addition, when targeting Vulkan, the following keywords also exist:</p> 2308</div> 2309<div class="dlist"> 2310<dl> 2311<dt class="hdlist1"></dt> 2312<dd> 2313<p><strong>texture2D</strong> <strong>texture2DArray</strong></p> 2314</dd> 2315<dt class="hdlist1"></dt> 2316<dd> 2317<p><strong>itexture2D</strong> <strong>itexture2DArray</strong> <strong>utexture2D</strong> <strong>utexture2DArray</strong></p> 2318</dd> 2319<dt class="hdlist1"></dt> 2320<dd> 2321<p><strong>texture2DMS</strong> <strong>itexture2DMS</strong> <strong>utexture2DMS</strong></p> 2322</dd> 2323<dt class="hdlist1"></dt> 2324<dd> 2325<p><strong>texture2DMSArray</strong> <strong>itexture2DMSArray</strong> <strong>utexture2DMSArray</strong></p> 2326</dd> 2327<dt class="hdlist1"></dt> 2328<dd> 2329<p><strong>texture3D</strong> <strong>itexture3D</strong> <strong>utexture3D</strong></p> 2330</dd> 2331<dt class="hdlist1"></dt> 2332<dd> 2333<p><strong>textureCube</strong> <strong>itextureCube</strong> <strong>utextureCube</strong></p> 2334</dd> 2335<dt class="hdlist1"></dt> 2336<dd> 2337<p><strong>textureCubeArray</strong> <strong>itextureCubeArray</strong> <strong>utextureCubeArray</strong></p> 2338</dd> 2339<dt class="hdlist1"></dt> 2340<dd> 2341<p><strong>textureBuffer</strong> <strong>itextureBuffer</strong> <strong>utextureBuffer</strong></p> 2342</dd> 2343<dt class="hdlist1"></dt> 2344<dd> 2345<p><strong>sampler</strong> <strong>samplerShadow</strong></p> 2346</dd> 2347<dt class="hdlist1"></dt> 2348<dd> 2349<p><strong>subpassInput</strong> <strong>isubpassInput</strong> <strong>usubpassInput</strong></p> 2350</dd> 2351<dt class="hdlist1"></dt> 2352<dd> 2353<p><strong>subpassInputMS</strong> <strong>isubpassInputMS</strong> <strong>usubpassInputMS</strong></p> 2354</dd> 2355</dl> 2356</div> 2357<div class="paragraph"> 2358<p>The following are the keywords reserved for future use. 2359Using them will result in an error:</p> 2360</div> 2361<div class="dlist"> 2362<dl> 2363<dt class="hdlist1"></dt> 2364<dd> 2365<p><strong>attribute</strong> <strong>varying</strong></p> 2366</dd> 2367<dt class="hdlist1"></dt> 2368<dd> 2369<p><strong>noperspective</strong></p> 2370</dd> 2371<dt class="hdlist1"></dt> 2372<dd> 2373<p><strong>subroutine</strong></p> 2374</dd> 2375<dt class="hdlist1"></dt> 2376<dd> 2377<p><strong>common</strong> <strong>partition</strong> <strong>active</strong></p> 2378</dd> 2379<dt class="hdlist1"></dt> 2380<dd> 2381<p><strong>asm</strong></p> 2382</dd> 2383<dt class="hdlist1"></dt> 2384<dd> 2385<p><strong>class</strong> <strong>union</strong> <strong>enum</strong> <strong>typedef</strong> <strong>template</strong> <strong>this</strong></p> 2386</dd> 2387<dt class="hdlist1"></dt> 2388<dd> 2389<p><strong>resource</strong></p> 2390</dd> 2391<dt class="hdlist1"></dt> 2392<dd> 2393<p><strong>goto</strong></p> 2394</dd> 2395<dt class="hdlist1"></dt> 2396<dd> 2397<p><strong>inline</strong> <strong>noinline</strong> <strong>public</strong> <strong>static</strong> <strong>extern</strong> <strong>external</strong> <strong>interface</strong></p> 2398</dd> 2399<dt class="hdlist1"></dt> 2400<dd> 2401<p><strong>long</strong> <strong>short</strong> <strong>half</strong> <strong>fixed</strong> <strong>unsigned</strong> <strong>superp</strong> 2402<strong>double</strong></p> 2403</dd> 2404<dt class="hdlist1"></dt> 2405<dd> 2406<p><strong>input</strong> <strong>output</strong></p> 2407</dd> 2408<dt class="hdlist1"></dt> 2409<dd> 2410<p><strong>hvec2</strong> <strong>hvec3</strong> <strong>hvec4</strong> <strong>fvec2</strong> <strong>fvec3</strong> <strong>fvec4</strong></p> 2411</dd> 2412<dt class="hdlist1"></dt> 2413<dd> 2414<p><strong>dvec2</strong> <strong>dvec3</strong> <strong>dvec4</strong></p> 2415</dd> 2416<dt class="hdlist1"></dt> 2417<dd> 2418<p><strong>dmat2</strong> <strong>dmat3</strong> <strong>dmat4</strong></p> 2419</dd> 2420<dt class="hdlist1"></dt> 2421<dd> 2422<p><strong>dmat2x2</strong> <strong>dmat2x3</strong> <strong>dmat2x4</strong></p> 2423</dd> 2424<dt class="hdlist1"></dt> 2425<dd> 2426<p><strong>dmat3x2</strong> <strong>dmat3x3</strong> <strong>dmat3x4</strong></p> 2427</dd> 2428<dt class="hdlist1"></dt> 2429<dd> 2430<p><strong>dmat4x2</strong> <strong>dmat4x3</strong> <strong>dmat4x4</strong></p> 2431</dd> 2432<dt class="hdlist1"></dt> 2433<dd> 2434<p><strong>filter</strong></p> 2435</dd> 2436<dt class="hdlist1"></dt> 2437<dd> 2438<p><strong>sizeof</strong> <strong>cast</strong></p> 2439</dd> 2440<dt class="hdlist1"></dt> 2441<dd> 2442<p><strong>namespace</strong> <strong>using</strong></p> 2443</dd> 2444<dt class="hdlist1"></dt> 2445<dd> 2446<p><strong>sampler1D</strong> <strong>sampler1DShadow</strong> <strong>sampler1DArray</strong> <strong>sampler1DArrayShadow</strong></p> 2447</dd> 2448<dt class="hdlist1"></dt> 2449<dd> 2450<p><strong>isampler1D</strong> <strong>isampler1DArray</strong> <strong>usampler1D</strong> <strong>usampler1DArray</strong></p> 2451</dd> 2452<dt class="hdlist1"></dt> 2453<dd> 2454<p><strong>sampler2DRect</strong> <strong>sampler2DRectShadow</strong> <strong>isampler2DRect</strong> <strong>usampler2DRect</strong></p> 2455</dd> 2456<dt class="hdlist1"></dt> 2457<dd> 2458<p><strong>sampler3DRect</strong></p> 2459</dd> 2460<dt class="hdlist1"></dt> 2461<dd> 2462<p><strong>image1D</strong> <strong>iimage1D</strong> <strong>uimage1D</strong></p> 2463</dd> 2464<dt class="hdlist1"></dt> 2465<dd> 2466<p><strong>image1DArray</strong> <strong>iimage1DArray</strong> <strong>uimage1DArray</strong></p> 2467</dd> 2468<dt class="hdlist1"></dt> 2469<dd> 2470<p><strong>image2DRect</strong> <strong>iimage2DRect</strong> <strong>uimage2DRect</strong></p> 2471</dd> 2472<dt class="hdlist1"></dt> 2473<dd> 2474<p><strong>image2DMS</strong> <strong>iimage2DMS</strong> <strong>uimage2DMS</strong></p> 2475</dd> 2476<dt class="hdlist1"></dt> 2477<dd> 2478<p><strong>image2DMSArray</strong> <strong>iimage2DMSArray</strong> <strong>uimage2DMSArray</strong></p> 2479</dd> 2480</dl> 2481</div> 2482<div class="paragraph"> 2483<p>In addition, all identifiers containing two consecutive underscores (__) 2484are reserved for use by underlying software layers. 2485Defining such a name in a shader does not itself result in an error, but may 2486result in unintended behaviors that stem from having multiple definitions of 2487the same name.</p> 2488</div> 2489</div> 2490<div class="sect2"> 2491<h3 id="identifiers">3.8. Identifiers</h3> 2492<div class="paragraph"> 2493<p>Identifiers are used for variable names, function names, structure names, 2494and field selectors (field selectors select components of 2495<code><a href="#vector-components">vectors</a></code> and <code><a href="#matrix-components">matrices</a></code>, 2496similarly to structure members). 2497Identifiers have the form:</p> 2498</div> 2499<div class="openblock bnf"> 2500<div class="content"> 2501<div class="dlist"> 2502<dl> 2503<dt class="hdlist1"><em>identifier</em> : </dt> 2504<dd> 2505<p><em>nondigit</em><br> 2506<em>identifier</em> <em>nondigit</em><br> 2507<em>identifier</em> <em>digit</em></p> 2508</dd> 2509<dt class="hdlist1"><em>nondigit</em> : one of </dt> 2510<dd> 2511<p><strong>_</strong> <strong>a b c d e f g h i j k l m n o p q r s t u v w x y z</strong><br> 2512<strong>A B C D E F G H I J K L M N O P Q R S T U V W X Y Z</strong></p> 2513</dd> 2514<dt class="hdlist1"><em>digit</em> : one of </dt> 2515<dd> 2516<p><strong>0 1 2 3 4 5 6 7 8 9</strong></p> 2517</dd> 2518</dl> 2519</div> 2520</div> 2521</div> 2522<div class="paragraph"> 2523<p>Identifiers starting with “gl_” are reserved, and 2524in general, may not be declared in a shader; 2525this results in an error. 2526However, as noted in the specification, there are some cases where 2527previously declared variables can be redeclared, and predeclared “gl_” 2528names are allowed to be redeclared in a shader only for these specific 2529purposes.</p> 2530</div> 2531<div class="paragraph"> 2532<p>Implementations must support identifier lengths of up to 1024 characters. 2533It is an error if the length exceeds this value.</p> 2534</div> 2535</div> 2536<div class="sect2"> 2537<h3 id="definitions">3.9. Definitions</h3> 2538<div class="paragraph"> 2539<p>Some language rules described below depend on the following definitions.</p> 2540</div> 2541<div class="sect3"> 2542<h4 id="static-use">3.9.1. Static Use</h4> 2543<div class="paragraph"> 2544<p>A shader contains a <em>static use</em> of a variable <em>x</em> if, after preprocessing, 2545the shader contains a statement that would access any part of <em>x</em>, 2546whether or not flow of control will cause that statement to be executed. 2547Such a variable is referred to as being <em>statically used</em>. If the access is a 2548write then <em>x</em> is further said to be <em>statically assigned</em>.</p> 2549</div> 2550</div> 2551<div class="sect3"> 2552<h4 id="uniform-and-non-uniform-control-flow">3.9.2. Uniform and Non-Uniform Control Flow</h4> 2553<div class="paragraph"> 2554<p>When executing statements in a fragment shader, control flow starts as 2555<em>uniform control flow</em>; all fragments enter the same control path into 2556<em>main()</em>. 2557Control flow becomes <em>non-uniform</em> when different fragments take different 2558paths through control-flow statements (selection, iteration, and jumps). 2559Control flow subsequently returns to being uniform after such divergent 2560sub-statements or skipped code completes, until the next time different 2561control paths are taken.</p> 2562</div> 2563<div class="paragraph"> 2564<p>For example:</p> 2565</div> 2566<div class="listingblock"> 2567<div class="content"> 2568<pre class="CodeRay highlight"><code data-lang="c++">main() 2569{ 2570 <span class="predefined-type">float</span> a = ...; <span class="comment">// this is uniform control flow</span> 2571 <span class="keyword">if</span> (a < b) { <span class="comment">// this expression is true for some fragments, not all</span> 2572 ...; <span class="comment">// non-uniform control flow</span> 2573 } <span class="keyword">else</span> { 2574 ...; <span class="comment">// non-uniform control flow</span> 2575 } 2576 ...; <span class="comment">// uniform control flow again</span> 2577}</code></pre> 2578</div> 2579</div> 2580<div class="paragraph"> 2581<p>Other examples of non-uniform control flow can occur within switch 2582statements and after conditional breaks, continues, early returns, and after 2583fragment discards, when the condition is true for some fragments but not 2584others. 2585Loop iterations that only some fragments execute are also non-uniform 2586control flow.</p> 2587</div> 2588<div class="paragraph"> 2589<p>This is similarly defined for other shader stages, based on the per-instance 2590data items they process.</p> 2591</div> 2592</div> 2593<div class="sect3"> 2594<h4 id="dynamically-uniform-expressions">3.9.3. Dynamically Uniform Expressions</h4> 2595<div class="paragraph"> 2596<p>A fragment-shader expression is <em>dynamically uniform</em> if all fragments 2597evaluating it get the same resulting value. 2598When loops are involved, this refers to the expression’s value for the same 2599loop iteration. 2600When functions are involved, this refers to calls from the same call point.</p> 2601</div> 2602<div class="paragraph"> 2603<p>This is similarly defined for other shader stages, based on the per-instance 2604data they process.</p> 2605</div> 2606<div class="paragraph"> 2607<p>Note that constant expressions are trivially dynamically uniform. 2608It follows that typical loop counters based on these are also dynamically 2609uniform.</p> 2610</div> 2611</div> 2612</div> 2613<div class="sect2"> 2614<h3 id="logical-phases-of-compilation">3.10. Logical Phases of Compilation</h3> 2615<div class="paragraph"> 2616<p>The compilation units for the shader processors are processed separately 2617before optionally being linked together in the final stage of compilation. 2618The logical phases of compilation are:</p> 2619</div> 2620<div class="olist arabic"> 2621<ol class="arabic"> 2622<li> 2623<p>Source strings are input as byte sequences. 2624The value 'zero' is interpreted as a terminator.</p> 2625</li> 2626<li> 2627<p>Source strings are concatenated to form a single input. 2628Zero bytes are discarded but all other values are retained.</p> 2629</li> 2630<li> 2631<p>Each string is interpreted according to the UTF-8 standard, with the 2632exception that all invalid byte sequences are retained in their original 2633form for subsequent processing.</p> 2634</li> 2635<li> 2636<p>Each {carriage-return, line-feed} and {line-feed, carriage return} 2637sequence is replaced by a single newline. 2638All remaining carriage-return and line-feed characters are then each 2639replaced by a newline.</p> 2640</li> 2641<li> 2642<p>Line numbering for each character, which is equal to the number of 2643preceding newlines plus one, is noted. 2644Note this can only be subsequently changed by the #line directive and is 2645not affected by the removal of newlines in phase 6 of compilation.</p> 2646</li> 2647<li> 2648<p>Wherever a backslash ('\') occurs immediately before a newline, both are 2649deleted. 2650Note that no whitespace is substituted, thereby allowing a single 2651preprocessing token to span a newline. 2652This operation is not recursive; any new {backslash newline} sequences 2653generated are not removed.</p> 2654</li> 2655<li> 2656<p>All comments are replaced with a single space. 2657All (non-zero) characters and invalid UTF-8 byte sequences are allowed 2658within comments. 2659'//' style comments include the initial '//' marker and continue up to, 2660but not including, the terminating newline. 2661'/<strong>…​</strong>/' comments include both the start and end marker.</p> 2662</li> 2663<li> 2664<p>The source string is converted into a sequence of preprocessing tokens. 2665These tokens include preprocessing numbers, identifiers and 2666preprocessing operations. 2667The line number associated with each token is copied from the line 2668number of the first character of the token.</p> 2669</li> 2670<li> 2671<p>The preprocessor is run. 2672Directives are executed and macro expansion is performed.</p> 2673</li> 2674<li> 2675<p>White space and newlines are discarded.</p> 2676</li> 2677<li> 2678<p>Preprocessing tokens are converted into tokens.</p> 2679</li> 2680<li> 2681<p>The syntax is analyzed according to the GLSL ES grammar.</p> 2682</li> 2683<li> 2684<p>The result is checked according to the semantic rules of the language.</p> 2685</li> 2686<li> 2687<p>Optionally, the shaders are linked together to form one or more programs 2688or separable programs. 2689When a pair of shaders from consecutive stages are linked into the same 2690program, any outputs and corresponding inputs not used in both shaders 2691may be discarded.</p> 2692</li> 2693<li> 2694<p>The binary is generated.</p> 2695</li> 2696</ol> 2697</div> 2698</div> 2699</div> 2700</div> 2701<div class="sect1"> 2702<h2 id="variables-and-types">4. Variables and Types</h2> 2703<div class="sectionbody"> 2704<div class="paragraph"> 2705<p>All variables and functions must be declared before being used. 2706Variable and function names are identifiers.</p> 2707</div> 2708<div class="paragraph"> 2709<p>There are no default types. 2710All variable and function declarations must have a declared type, and 2711optionally qualifiers. 2712A variable is declared by specifying its type followed by one or more names 2713separated by commas. 2714In many cases, a variable can be initialized as part of its declaration by 2715using the assignment operator (<strong>=</strong>).</p> 2716</div> 2717<div class="paragraph"> 2718<p>User-defined types may be defined using <strong>struct</strong> to aggregate a list of 2719existing types into a single name.</p> 2720</div> 2721<div class="paragraph"> 2722<p>The OpenGL ES Shading Language is type safe. 2723There are no implicit conversions between types.</p> 2724</div> 2725<div class="sect2"> 2726<h3 id="basic-types">4.1. Basic Types</h3> 2727<div class="dlist"> 2728<dl> 2729<dt class="hdlist1">Definition</dt> 2730<dd> 2731<p>A <em>basic type</em> is a type defined by a keyword in the language.</p> 2732</dd> 2733</dl> 2734</div> 2735<div class="paragraph"> 2736<p>The OpenGL ES Shading Language supports the following basic data types, grouped as follows.</p> 2737</div> 2738<div class="paragraph"> 2739<p><strong>Transparent Types</strong></p> 2740</div> 2741<table class="tableblock frame-all grid-all stretch"> 2742<colgroup> 2743<col style="width: 50%;"> 2744<col style="width: 50%;"> 2745</colgroup> 2746<thead> 2747<tr> 2748<th class="tableblock halign-left valign-top">Type</th> 2749<th class="tableblock halign-left valign-top">Meaning</th> 2750</tr> 2751</thead> 2752<tbody> 2753<tr> 2754<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>void</strong></p></td> 2755<td class="tableblock halign-left valign-top"><p class="tableblock">for functions that do not return a value</p></td> 2756</tr> 2757<tr> 2758<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>bool</strong></p></td> 2759<td class="tableblock halign-left valign-top"><p class="tableblock">a conditional type, taking on values of true or false</p></td> 2760</tr> 2761<tr> 2762<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>int</strong></p></td> 2763<td class="tableblock halign-left valign-top"><p class="tableblock">a signed integer</p></td> 2764</tr> 2765<tr> 2766<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>uint</strong></p></td> 2767<td class="tableblock halign-left valign-top"><p class="tableblock">an unsigned integer</p></td> 2768</tr> 2769<tr> 2770<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>float</strong></p></td> 2771<td class="tableblock halign-left valign-top"><p class="tableblock">a single-precision floating-point scalar</p></td> 2772</tr> 2773<tr> 2774<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>vec2</strong></p></td> 2775<td class="tableblock halign-left valign-top"><p class="tableblock">a two-component single-precision floating-point vector</p></td> 2776</tr> 2777<tr> 2778<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>vec3</strong></p></td> 2779<td class="tableblock halign-left valign-top"><p class="tableblock">a three-component single-precision floating-point vector</p></td> 2780</tr> 2781<tr> 2782<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>vec4</strong></p></td> 2783<td class="tableblock halign-left valign-top"><p class="tableblock">a four-component single-precision floating-point vector</p></td> 2784</tr> 2785<tr> 2786<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>bvec2</strong></p></td> 2787<td class="tableblock halign-left valign-top"><p class="tableblock">a two-component Boolean vector</p></td> 2788</tr> 2789<tr> 2790<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>bvec3</strong></p></td> 2791<td class="tableblock halign-left valign-top"><p class="tableblock">a three-component Boolean vector</p></td> 2792</tr> 2793<tr> 2794<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>bvec4</strong></p></td> 2795<td class="tableblock halign-left valign-top"><p class="tableblock">a four-component Boolean vector</p></td> 2796</tr> 2797<tr> 2798<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>ivec2</strong></p></td> 2799<td class="tableblock halign-left valign-top"><p class="tableblock">a two-component signed integer vector</p></td> 2800</tr> 2801<tr> 2802<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>ivec3</strong></p></td> 2803<td class="tableblock halign-left valign-top"><p class="tableblock">a three-component signed integer vector</p></td> 2804</tr> 2805<tr> 2806<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>ivec4</strong></p></td> 2807<td class="tableblock halign-left valign-top"><p class="tableblock">a four-component signed integer vector</p></td> 2808</tr> 2809<tr> 2810<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>uvec2</strong></p></td> 2811<td class="tableblock halign-left valign-top"><p class="tableblock">a two-component unsigned integer vector</p></td> 2812</tr> 2813<tr> 2814<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>uvec3</strong></p></td> 2815<td class="tableblock halign-left valign-top"><p class="tableblock">a three-component unsigned integer vector</p></td> 2816</tr> 2817<tr> 2818<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>uvec4</strong></p></td> 2819<td class="tableblock halign-left valign-top"><p class="tableblock">a four-component unsigned integer vector</p></td> 2820</tr> 2821<tr> 2822<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat2</strong></p></td> 2823<td class="tableblock halign-left valign-top"><p class="tableblock">a 2 × 2 single-precision floating-point matrix</p></td> 2824</tr> 2825<tr> 2826<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat3</strong></p></td> 2827<td class="tableblock halign-left valign-top"><p class="tableblock">a 3 × 3 single-precision floating-point matrix</p></td> 2828</tr> 2829<tr> 2830<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat4</strong></p></td> 2831<td class="tableblock halign-left valign-top"><p class="tableblock">a 4 × 4 single-precision floating-point matrix</p></td> 2832</tr> 2833<tr> 2834<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat2x2</strong></p></td> 2835<td class="tableblock halign-left valign-top"><p class="tableblock">same as a <strong>mat2</strong></p></td> 2836</tr> 2837<tr> 2838<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat2x3</strong></p></td> 2839<td class="tableblock halign-left valign-top"><p class="tableblock">a single-precision floating-point matrix with 2 columns and 3 rows</p></td> 2840</tr> 2841<tr> 2842<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat2x4</strong></p></td> 2843<td class="tableblock halign-left valign-top"><p class="tableblock">a single-precision floating-point matrix with 2 columns and 4 rows</p></td> 2844</tr> 2845<tr> 2846<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat3x2</strong></p></td> 2847<td class="tableblock halign-left valign-top"><p class="tableblock">a single-precision floating-point matrix with 3 columns and 2 rows</p></td> 2848</tr> 2849<tr> 2850<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat3x3</strong></p></td> 2851<td class="tableblock halign-left valign-top"><p class="tableblock">same as a <strong>mat3</strong></p></td> 2852</tr> 2853<tr> 2854<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat3x4</strong></p></td> 2855<td class="tableblock halign-left valign-top"><p class="tableblock">a single-precision floating-point matrix with 3 columns and 4 rows</p></td> 2856</tr> 2857<tr> 2858<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat4x2</strong></p></td> 2859<td class="tableblock halign-left valign-top"><p class="tableblock">a single-precision floating-point matrix with 4 columns and 2 rows</p></td> 2860</tr> 2861<tr> 2862<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat4x3</strong></p></td> 2863<td class="tableblock halign-left valign-top"><p class="tableblock">a single-precision floating-point matrix with 4 columns and 3 rows</p></td> 2864</tr> 2865<tr> 2866<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mat4x4</strong></p></td> 2867<td class="tableblock halign-left valign-top"><p class="tableblock">same as a <strong>mat4</strong></p></td> 2868</tr> 2869</tbody> 2870</table> 2871<div class="paragraph"> 2872<p>Note that where the following tables say “accessing a texture”, the 2873<strong>sampler*</strong> opaque types access textures, and the <strong>image*</strong> opaque types 2874access images, of a specified type.</p> 2875</div> 2876<div class="paragraph"> 2877<p><strong>Floating-Point Opaque Types</strong></p> 2878</div> 2879<table class="tableblock frame-all grid-all stretch"> 2880<colgroup> 2881<col style="width: 50%;"> 2882<col style="width: 50%;"> 2883</colgroup> 2884<thead> 2885<tr> 2886<th class="tableblock halign-left valign-top">Type</th> 2887<th class="tableblock halign-left valign-top">Meaning</th> 2888</tr> 2889</thead> 2890<tbody> 2891<tr> 2892<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>sampler2D</strong><br> 2893 <strong>texture2D</strong><br> 2894 <strong>image2D</strong></p></td> 2895<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a 2D texture</p></td> 2896</tr> 2897<tr> 2898<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>sampler2DShadow</strong></p></td> 2899<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a 2D depth texture with comparison</p></td> 2900</tr> 2901<tr> 2902<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>sampler2DArray</strong><br> 2903 <strong>texture2DArray</strong><br> 2904 <strong>image2DArray</strong></p></td> 2905<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a 2D array texture</p></td> 2906</tr> 2907<tr> 2908<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>sampler2DArrayShadow</strong></p></td> 2909<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a 2D array depth texture with comparison</p></td> 2910</tr> 2911<tr> 2912<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>sampler2DMS</strong><br> 2913 <strong>texture2DMS</strong></p></td> 2914<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a 2D multisample texture</p></td> 2915</tr> 2916<tr> 2917<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>sampler2DMSArray</strong></p></td> 2918<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a 2D multisample array texture</p></td> 2919</tr> 2920<tr> 2921<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>sampler3D</strong><br> 2922 <strong>texture3D</strong><br> 2923 <strong>image3D</strong></p></td> 2924<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a 3D texture</p></td> 2925</tr> 2926<tr> 2927<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>samplerCube</strong><br> 2928 <strong>textureCube</strong><br> 2929 <strong>imageCube</strong></p></td> 2930<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a cube mapped texture</p></td> 2931</tr> 2932<tr> 2933<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>samplerCubeShadow</strong></p></td> 2934<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a cube map depth texture with comparison</p></td> 2935</tr> 2936<tr> 2937<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>samplerCubeArray</strong><br> 2938 <strong>textureCubeArray</strong><br> 2939 <strong>imageCubeArray</strong></p></td> 2940<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a cube map array texture</p></td> 2941</tr> 2942<tr> 2943<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>samplerCubeArrayShadow</strong></p></td> 2944<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a cube map array depth texture with comparison</p></td> 2945</tr> 2946<tr> 2947<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>samplerBuffer</strong><br> 2948 <strong>textureBuffer</strong><br> 2949 <strong>imageBuffer</strong></p></td> 2950<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a buffer texture</p></td> 2951</tr> 2952<tr> 2953<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>subpassInput</strong></p></td> 2954<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a floating-point subpass input</p></td> 2955</tr> 2956<tr> 2957<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>subpassInputMS</strong></p></td> 2958<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a multi-sampled floating-point subpass input</p></td> 2959</tr> 2960</tbody> 2961</table> 2962<div class="paragraph"> 2963<p><strong>Signed Integer Opaque Types</strong></p> 2964</div> 2965<table class="tableblock frame-all grid-all stretch"> 2966<colgroup> 2967<col style="width: 50%;"> 2968<col style="width: 50%;"> 2969</colgroup> 2970<thead> 2971<tr> 2972<th class="tableblock halign-left valign-top">Type</th> 2973<th class="tableblock halign-left valign-top">Meaning</th> 2974</tr> 2975</thead> 2976<tbody> 2977<tr> 2978<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>isampler2D</strong><br> 2979 <strong>itexture2D</strong><br> 2980 <strong>iimage2D</strong></p></td> 2981<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an integer 2D texture</p></td> 2982</tr> 2983<tr> 2984<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>isampler2DArray</strong><br> 2985 <strong>itexture2DArray</strong><br> 2986 <strong>iimage2DArray</strong></p></td> 2987<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an integer 2D array texture</p></td> 2988</tr> 2989<tr> 2990<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>isampler2DMS</strong><br> 2991 <strong>itexture2DMS</strong></p></td> 2992<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an integer 2D multisample texture</p></td> 2993</tr> 2994<tr> 2995<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>isampler2DMSArray</strong><br> 2996 <strong>itexture2DMSArray</strong></p></td> 2997<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an integer 2D multisample array texture</p></td> 2998</tr> 2999<tr> 3000<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>isampler3D</strong><br> 3001 <strong>itexture3D</strong><br> 3002 <strong>iimage3D</strong></p></td> 3003<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an integer 3D texture</p></td> 3004</tr> 3005<tr> 3006<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>isamplerCube</strong><br> 3007 <strong>itextureCube</strong><br> 3008 <strong>iimageCube</strong></p></td> 3009<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an integer cube mapped texture</p></td> 3010</tr> 3011<tr> 3012<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>isamplerCubeArray</strong><br> 3013 <strong>itextureCubeArray</strong><br> 3014 <strong>iimageCubeArray</strong></p></td> 3015<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an integer cube map array texture</p></td> 3016</tr> 3017<tr> 3018<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>isamplerBuffer</strong><br> 3019 <strong>itextureBuffer</strong><br> 3020 <strong>iimageBuffer</strong></p></td> 3021<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an integer buffer texture</p></td> 3022</tr> 3023<tr> 3024<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>isubpassInput</strong></p></td> 3025<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an integer subpass input</p></td> 3026</tr> 3027<tr> 3028<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>isubpassInputMS</strong></p></td> 3029<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a multi-sampled integer subpass input</p></td> 3030</tr> 3031</tbody> 3032</table> 3033<div class="paragraph"> 3034<p><strong>Unsigned Integer Opaque Types</strong></p> 3035</div> 3036<table class="tableblock frame-all grid-all stretch"> 3037<colgroup> 3038<col style="width: 50%;"> 3039<col style="width: 50%;"> 3040</colgroup> 3041<thead> 3042<tr> 3043<th class="tableblock halign-left valign-top">Type</th> 3044<th class="tableblock halign-left valign-top">Meaning</th> 3045</tr> 3046</thead> 3047<tbody> 3048<tr> 3049<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>usampler2D</strong><br> 3050 <strong>utexture2D</strong><br> 3051 <strong>uimage2D</strong></p></td> 3052<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an unsigned integer 2D texture</p></td> 3053</tr> 3054<tr> 3055<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>usampler2DArray</strong><br> 3056 <strong>utexture1DArray</strong><br> 3057 <strong>uimage2DArray</strong></p></td> 3058<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an unsigned integer 2D array texture</p></td> 3059</tr> 3060<tr> 3061<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>usampler2DMS</strong><br> 3062 <strong>utexture2DMS</strong></p></td> 3063<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an unsigned integer 2D multisample texture</p></td> 3064</tr> 3065<tr> 3066<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>usampler2DMSArray</strong><br> 3067 <strong>utexture2DMSArray</strong></p></td> 3068<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an unsigned integer 2D multisample array texture</p></td> 3069</tr> 3070<tr> 3071<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>usampler3D</strong><br> 3072 <strong>utexture3D</strong><br> 3073 <strong>uimage3D</strong></p></td> 3074<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an unsigned integer 3D texture</p></td> 3075</tr> 3076<tr> 3077<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>usamplerCube</strong><br> 3078 <strong>utextureCube</strong><br> 3079 <strong>uimageCube</strong></p></td> 3080<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an unsigned integer cube mapped texture</p></td> 3081</tr> 3082<tr> 3083<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>usamplerCubeArray</strong><br> 3084 <strong>utextureCubeArray</strong><br> 3085 <strong>uimageCubeArray</strong></p></td> 3086<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an unsigned integer cube map array texture</p></td> 3087</tr> 3088<tr> 3089<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>usamplerBuffer</strong><br> 3090 <strong>utextureBuffer</strong><br> 3091 <strong>uimageBuffer</strong></p></td> 3092<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an unsigned integer buffer texture</p></td> 3093</tr> 3094<tr> 3095<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>atomic_uint</strong></p></td> 3096<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an unsigned integer atomic counter</p></td> 3097</tr> 3098<tr> 3099<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>usubpassInput</strong></p></td> 3100<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing an unsigned-integer subpass input</p></td> 3101</tr> 3102<tr> 3103<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>usubpassInputMS</strong></p></td> 3104<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing a multi-sampled unsigned-integer subpass input</p></td> 3105</tr> 3106</tbody> 3107</table> 3108<div class="paragraph"> 3109<p><strong>Sampler Opaque Types</strong></p> 3110</div> 3111<table class="tableblock frame-all grid-all stretch"> 3112<colgroup> 3113<col style="width: 50%;"> 3114<col style="width: 50%;"> 3115</colgroup> 3116<thead> 3117<tr> 3118<th class="tableblock halign-left valign-top">Type</th> 3119<th class="tableblock halign-left valign-top">Meaning</th> 3120</tr> 3121</thead> 3122<tbody> 3123<tr> 3124<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>sampler</strong></p></td> 3125<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing state describing how to sample a texture</p></td> 3126</tr> 3127<tr> 3128<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>samplerShadow</strong></p></td> 3129<td class="tableblock halign-left valign-top"><p class="tableblock">a handle for accessing state describing how to sample a depth 3130 texture with comparison</p></td> 3131</tr> 3132</tbody> 3133</table> 3134<div class="paragraph"> 3135<p>In addition, a shader can aggregate these basic types using arrays and 3136structures to build more complex types.</p> 3137</div> 3138<div class="paragraph"> 3139<p>There are no pointer types.</p> 3140</div> 3141<div class="sect3"> 3142<h4 id="void">4.1.1. Void</h4> 3143<div class="paragraph"> 3144<p>Functions that do not return a value must be declared as <strong>void</strong>. 3145There is no default function return type. 3146The keyword <strong>void</strong> cannot be used in any other declarations (except for 3147empty formal or actual parameter lists), or an error results.</p> 3148</div> 3149</div> 3150<div class="sect3"> 3151<h4 id="booleans">4.1.2. Booleans</h4> 3152<div class="dlist"> 3153<dl> 3154<dt class="hdlist1">Definition</dt> 3155<dd> 3156<p>A <em>boolean type</em> is any boolean scalar or vector type (<strong>bool</strong>, <strong>bvec2</strong>, 3157<strong>bvec3</strong>, <strong>bvec4</strong>)</p> 3158</dd> 3159</dl> 3160</div> 3161<div class="paragraph"> 3162<p>To make conditional execution of code easier to express, the type <strong>bool</strong> is 3163supported. 3164There is no expectation that hardware directly supports variables of this 3165type. 3166It is a genuine Boolean type, holding only one of two values meaning either 3167true or false. 3168Two keywords <strong>true</strong> and <strong>false</strong> can be used as literal Boolean constants. 3169Booleans are declared and optionally initialized as in the follow example:</p> 3170</div> 3171<div class="listingblock"> 3172<div class="content"> 3173<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">bool</span> success; <span class="comment">// declare "success" to be a Boolean</span> 3174<span class="predefined-type">bool</span> done = <span class="predefined-constant">false</span>; <span class="comment">// declare and initialize "done"</span></code></pre> 3175</div> 3176</div> 3177<div class="paragraph"> 3178<p>Expressions used for conditional jumps (<strong>if</strong>, <strong>for</strong>, <strong>?:</strong>, <strong>while</strong>, 3179<strong>do</strong>-<strong>while</strong>) must evaluate to the type <strong>bool</strong>.</p> 3180</div> 3181</div> 3182<div class="sect3"> 3183<h4 id="integers">4.1.3. Integers</h4> 3184<div class="dlist"> 3185<dl> 3186<dt class="hdlist1">Definitions</dt> 3187<dd> 3188<p>An <em>integral type</em> is any signed or unsigned, scalar or vector integer type. 3189It excludes arrays and structures.</p> 3190</dd> 3191<dt class="hdlist1"></dt> 3192<dd> 3193<p>A <em>scalar integral type</em> is a scalar signed or unsigned integer type:</p> 3194</dd> 3195<dt class="hdlist1"></dt> 3196<dd> 3197<p>A <em>vector integral type</em> is a vector of signed or unsigned integers:</p> 3198</dd> 3199</dl> 3200</div> 3201<div class="paragraph"> 3202<p>Signed and unsigned integer variables are fully supported. 3203In this document, the term <em>integer</em> is meant to generally include both 3204signed and unsigned integers.</p> 3205</div> 3206<div class="paragraph"> 3207<p><strong>highp</strong> 3208unsigned integers have exactly 32 bits of precision.</p> 3209</div> 3210<div class="paragraph"> 3211<p><strong>highp</strong> 3212signed integers use 32 bits, including a sign bit, in two’s complement form.</p> 3213</div> 3214<div class="paragraph"> 3215<p>When targeting Vulkan, <strong>mediump</strong> and <strong>lowp</strong> integers are as defined by the 3216SPIR-V <strong>RelaxedPrecision</strong> decoration. 3217Otherwise, <strong>mediump</strong> and <strong>lowp</strong> integers have implementation-defined numbers of bits. 3218See “<a href="#range-and-precision">Range and Precision</a>” for details.</p> 3219</div> 3220<div class="paragraph"> 3221<p>For all precisions, addition, 3222subtraction and multiplication resulting in overflow or 3223underflow will result in the low-order 3224n 3225bits of the correct result R, where 3226n is the size in bits of the integer and 3227R is computed with enough precision to avoid overflow or underflow. 3228Division resulting in overflow will result in an undefined value.</p> 3229</div> 3230<div class="paragraph"> 3231<p>Integers are declared and optionally initialized with integer expressions, 3232as in the following example:</p> 3233</div> 3234<div class="listingblock"> 3235<div class="content"> 3236<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">int</span> i, j = <span class="integer">42</span>; <span class="comment">// default integer literal type is int</span> 3237uint k = <span class="integer">3</span>u; <span class="comment">// "u" establishes the type as uint</span></code></pre> 3238</div> 3239</div> 3240<div class="paragraph"> 3241<p>Literal integer constants can be expressed in decimal (base 10), octal (base 32428), or hexadecimal (base 16) as follows.</p> 3243</div> 3244<div class="openblock bnf"> 3245<div class="content"> 3246<div class="dlist"> 3247<dl> 3248<dt class="hdlist1"><em>integer-constant</em> : </dt> 3249<dd> 3250<p><em>decimal-constant</em> <em>integer-suffix<sub>opt</sub></em><br> 3251<em>octal-constant</em> <em>integer-suffix<sub>opt</sub></em><br> 3252<em>hexadecimal-constant</em> <em>integer-suffix<sub>opt</sub></em></p> 3253</dd> 3254<dt class="hdlist1"><em>integer-suffix</em> : one of </dt> 3255<dd> 3256<p><strong>u</strong> <strong>U</strong></p> 3257</dd> 3258<dt class="hdlist1"><em>decimal-constant</em> : </dt> 3259<dd> 3260<p><em>nonzero-digit</em><br> 3261<em>decimal-constant</em> <em>digit</em></p> 3262</dd> 3263<dt class="hdlist1"><em>octal-constant</em> : </dt> 3264<dd> 3265<p><strong>0</strong><br> 3266<em>octal-constant</em> <em>octal-digit</em></p> 3267</dd> 3268<dt class="hdlist1"><em>hexadecimal-constant</em> : </dt> 3269<dd> 3270<p><strong>0x</strong> <em>hexadecimal-digit</em><br> 3271<strong>0X</strong> <em>hexadecimal-digit</em><br> 3272<em>hexadecimal-constant</em> <em>hexadecimal-digit</em></p> 3273</dd> 3274<dt class="hdlist1"><em>digit</em> : </dt> 3275<dd> 3276<p><strong>0</strong><br> 3277<em>nonzero-digit</em></p> 3278</dd> 3279<dt class="hdlist1"><em>nonzero-digit</em> : one of </dt> 3280<dd> 3281<p><strong>1 2 3 4 5 6 7 8 9</strong></p> 3282</dd> 3283<dt class="hdlist1"><em>octal-digit</em> : one of </dt> 3284<dd> 3285<p><strong>0 1 2 3 4 5 6 7</strong></p> 3286</dd> 3287<dt class="hdlist1"><em>hexadecimal-digit</em> : one of </dt> 3288<dd> 3289<p><strong>0 1 2 3 4 5 6 7 8 9<br> 3290a b c d e f<br> 3291A B C D E F</strong></p> 3292</dd> 3293</dl> 3294</div> 3295</div> 3296</div> 3297<div class="paragraph"> 3298<p>No white space is allowed between the digits of an integer constant, 3299including after the leading <strong>0</strong> or after the leading <strong>0x</strong> or <strong>0X</strong> of a 3300constant, or before the suffix <strong>u</strong> or <strong>U</strong>. 3301When the suffix <strong>u</strong> or <strong>U</strong> is present, the literal has type <strong>uint</strong>, 3302otherwise the type is <strong>int</strong>. 3303A leading unary minus sign (-) is interpreted as an arithmetic unary 3304negation, not as part of the constant. 3305Hence, literals themselves are always expressed with non-negative syntax, 3306though they could result in a negative value.</p> 3307</div> 3308<div class="paragraph"> 3309<p>It is an error to provide a literal integer whose bit pattern 3310cannot fit in 32 bits. 3311The bit pattern of the literal is always used unmodified. 3312So a signed literal whose bit pattern includes a set sign bit creates a 3313negative value.</p> 3314</div> 3315<div class="paragraph"> 3316<p>For example,</p> 3317</div> 3318<div class="listingblock"> 3319<div class="content"> 3320<pre class="CodeRay highlight"><code data-lang="c++"><span class="integer">1</span> <span class="comment">// OK. Signed integer, value 1</span> 3321<span class="integer">1</span>u <span class="comment">// OK. Unsigned integer, value 1</span> 3322-<span class="integer">1</span> <span class="comment">// OK. Unary minus applied to signed integer.</span> 3323 <span class="comment">// result is a signed integer, value -1</span> 3324-<span class="integer">1</span>u <span class="comment">// OK. Unary minus applies to unsigned integer.</span> 3325 <span class="comment">// Result is an unsigned integer, value 0xffffffff</span> 3326<span class="hex">0xA0000000</span> <span class="comment">// OK. 32-bit signed hexadecimal</span> 3327<span class="hex">0xABcdEF00</span>u <span class="comment">// OK. 32-bit unsigned hexadecimal</span> 3328<span class="hex">0xffffffff</span> <span class="comment">// OK. Signed integer, value -1</span> 3329<span class="hex">0x80000000</span> <span class="comment">// OK. Evaluates to -2147483648</span> 3330<span class="hex">0xffffffff</span>u <span class="comment">// OK. Unsigned integer, value 0xffffffff</span> 3331<span class="hex">0xfffffffff</span> <span class="comment">// Error: needs more than 32 bits</span> 3332<span class="integer">3000000000</span> <span class="comment">// OK. A signed decimal literal taking 32 bits.</span> 3333 <span class="comment">// It evaluates to -1294967296</span> 3334<span class="integer">2147483648</span> <span class="comment">// OK. Evaluates to -2147483648 (the literal set the sign bit)</span> 3335<span class="integer">5000000000</span> <span class="comment">// Error: needs more than 32 bits</span></code></pre> 3336</div> 3337</div> 3338</div> 3339<div class="sect3"> 3340<h4 id="floats">4.1.4. Floats</h4> 3341<div class="dlist"> 3342<dl> 3343<dt class="hdlist1">Definition</dt> 3344<dd> 3345<p>A <em>floating-point type</em> is any floating-point scalar, vector or matrix type. 3346It excludes arrays and structures.</p> 3347</dd> 3348</dl> 3349</div> 3350<div class="paragraph"> 3351<p>Floats are available for use in a variety of scalar calculations. 3352Floating-point variables are defined as in the following example:</p> 3353</div> 3354<div class="listingblock"> 3355<div class="content"> 3356<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span> a, b = <span class="float">1</span><span class="float">.5</span>;</code></pre> 3357</div> 3358</div> 3359<div class="paragraph"> 3360<p>As an input value to one of the processing units, a floating-point variable 3361is expected to match the IEEE 754 single precision floating-point definition 3362for precision and dynamic range. 3363<strong>highp</strong> floating-point variables within a shader are encoded according to 3364the IEEE 754 specification for single-precision floating-point values 3365(logically, not necessarily physically). 3366While encodings are logically IEEE 754, operations (addition, 3367multiplication, etc.) are not necessarily performed as required by IEEE 754. 3368See “<a href="#range-and-precision">Range and Precision</a>” for more details on 3369precision and usage of NaNs (Not a Number) and Infs (positive or negative 3370infinities).</p> 3371</div> 3372<div class="paragraph"> 3373<p>Floating-point constants are defined as follows.</p> 3374</div> 3375<div class="openblock bnf"> 3376<div class="content"> 3377<div class="dlist"> 3378<dl> 3379<dt class="hdlist1"><em>floating-constant</em> : </dt> 3380<dd> 3381<p><em>fractional-constant</em> <em>exponent-part<sub>opt</sub></em> <em>floating-suffix<sub>opt</sub></em><br> 3382<em>digit-sequence</em> <em>exponent-part</em> <em>floating-suffix<sub>opt</sub></em></p> 3383</dd> 3384<dt class="hdlist1"><em>fractional-constant</em> : </dt> 3385<dd> 3386<p><em>digit-sequence</em> <strong>.</strong> <em>digit-sequence</em><br> 3387<em>digit-sequence</em> <strong>.</strong><br> 3388<strong>.</strong> <em>digit-sequence</em></p> 3389</dd> 3390<dt class="hdlist1"><em>exponent-part</em> : </dt> 3391<dd> 3392<p><strong>e</strong> <em>sign<sub>opt</sub></em> <em>digit-sequence</em><br> 3393<strong>E</strong> <em>sign<sub>opt</sub></em> <em>digit-sequence</em></p> 3394</dd> 3395<dt class="hdlist1"><em>sign</em> : one of </dt> 3396<dd> 3397<p><strong>+</strong> <strong>-</strong></p> 3398</dd> 3399<dt class="hdlist1"><em>digit-sequence</em> : </dt> 3400<dd> 3401<p><em>digit</em><br> 3402<em>digit-sequence</em> <em>digit</em></p> 3403</dd> 3404<dt class="hdlist1"><em>floating-suffix</em> : one of </dt> 3405<dd> 3406<p><strong>f</strong> <strong>F</strong></p> 3407</dd> 3408</dl> 3409</div> 3410</div> 3411</div> 3412<div class="paragraph"> 3413<p>A decimal point (<strong>.</strong>) is not needed if the exponent part is present. 3414No white space may appear anywhere within a floating-point constant, 3415including before a suffix. 3416A leading unary minus sign (<strong>-</strong>) is interpreted as a unary operator and is 3417not part of the floating-point constant.</p> 3418</div> 3419<div class="paragraph"> 3420<p>There is no limit on the number of digits in any <em>digit-sequence</em>. 3421If the value of the floating-point number is too large (small) to be stored 3422as a single precision value, it is converted to positive (negative) 3423infinity. 3424A value with a magnitude too small to be represented as a mantissa and 3425exponent is converted to zero. 3426Implementations may also convert subnormal (denormalized) numbers to zero.</p> 3427</div> 3428</div> 3429<div class="sect3"> 3430<h4 id="vectors">4.1.5. Vectors</h4> 3431<div class="paragraph"> 3432<p>The OpenGL ES Shading Language includes data types for generic 2-, 3-, and 4-component vectors 3433of floating-point values, integers, and Booleans. 3434Floating-point vector variables can be used to store colors, normals, 3435positions, texture coordinates, texture lookup results and the like. 3436Boolean vectors can be used for component-wise comparisons of numeric 3437vectors. 3438Some examples of vector declarations are:</p> 3439</div> 3440<div class="listingblock"> 3441<div class="content"> 3442<pre class="CodeRay highlight"><code data-lang="c++">vec2 texcoord1, texcoord2; 3443vec3 position; 3444vec4 myRGBA; 3445ivec2 textureLookup; 3446bvec3 less;</code></pre> 3447</div> 3448</div> 3449<div class="paragraph"> 3450<p>Initialization of vectors can be done with constructors. 3451See “<a href="#vector-and-matrix-constructors">Vector and Matrix Constructors</a>”.</p> 3452</div> 3453</div> 3454<div class="sect3"> 3455<h4 id="matrices">4.1.6. Matrices</h4> 3456<div class="paragraph"> 3457<p>The OpenGL ES Shading Language has built-in types for 2 × 2, 2 × 3, 2 × 4, 3 3458× 2, 3 × 3, 3 × 4, 4 × 2, 4 × 3, and 4 × 34594 matrices of floating-point numbers. 3460The first number in the type is the number of columns, the second is the 3461number of rows. 3462If there is only one number, the matrix is square. 3463Example matrix declarations:</p> 3464</div> 3465<div class="listingblock"> 3466<div class="content"> 3467<pre class="CodeRay highlight"><code data-lang="c++">mat2 mat2D; 3468mat3 optMatrix; 3469mat4 view, projection; 3470mat4x4 view; <span class="comment">// an alternate way of declaring a mat4</span> 3471mat3x2 m; <span class="comment">// a matrix with 3 columns and 2 rows</span></code></pre> 3472</div> 3473</div> 3474<div class="paragraph"> 3475<p>Initialization of matrix values is done with constructors (described in 3476“<a href="#vector-and-matrix-constructors">Vector and Matrix Constructors</a>”) in 3477column-major order.</p> 3478</div> 3479<div class="paragraph"> 3480<p><strong>mat2</strong> is an alias for <strong>mat2x2</strong>, not a distinct type. 3481Similarly for <strong>mat3</strong> and <strong>mat4.</strong> The following is legal:</p> 3482</div> 3483<div class="listingblock"> 3484<div class="content"> 3485<pre class="CodeRay highlight"><code data-lang="c++">mat2 a; 3486mat2x2 b = a;</code></pre> 3487</div> 3488</div> 3489</div> 3490<div class="sect3"> 3491<h4 id="opaque-types">4.1.7. Opaque Types</h4> 3492<div class="dlist"> 3493<dl> 3494<dt class="hdlist1">Definition</dt> 3495<dd> 3496<p>An <em>opaque type</em> is a type where the internal structure of the type is 3497hidden from the language.</p> 3498</dd> 3499</dl> 3500</div> 3501<div class="paragraph"> 3502<p>The opaque types, as listed in the following sections, declare variables 3503that are effectively opaque handles to other objects. 3504These objects are accessed through built-in functions, not through direct 3505reading or writing of the declared variable. 3506They can only be declared as function parameters or in <strong>uniform</strong>-qualified 3507variables (see “<a href="#uniform-variables">Uniform Variables</a>”). 3508The only opaque types that take memory qualifiers are the image types. 3509Except for array indexing, structure member selection, and parentheses, 3510opaque variables are not allowed to be operands in expressions; such use 3511results in a compile-time error.</p> 3512</div> 3513<div class="paragraph"> 3514<p>When aggregated into arrays within a shader, opaque types can only be 3515indexed with a dynamically uniform integral expression (see “Dynamically 3516Uniform Expressions”) unless otherwise noted; otherwise, results are 3517undefined.</p> 3518</div> 3519<div class="paragraph"> 3520<p>Opaque variables cannot be treated as l-values; hence cannot be used as 3521<strong>out</strong> or <strong>inout</strong> function parameters, nor can they be assigned into. 3522Any such use results in a compile-time error. 3523However, they can be passed as <strong>in</strong> parameters with matching types and 3524memory qualifiers. 3525They cannot be declared with an initializer.</p> 3526</div> 3527<div class="paragraph"> 3528<p>Because a single opaque type declaration effectively declares two objects, 3529the opaque handle itself and the object it is a handle to, there is room for 3530both a storage qualifier and a memory qualifier. 3531The storage qualifier will qualify the opaque handle, while the memory 3532qualifier will qualify the object it is a handle to.</p> 3533</div> 3534<div class="sect4"> 3535<h5 id="samplers">Texture-Combined Samplers</h5> 3536<div class="paragraph"> 3537<p>Texture-combined sampler types (e.g. <strong>sampler2D</strong>) are the sampler types 3538described in the Basic Types tables as handles for accessing textures. 3539(They do not include <strong>sampler</strong> and <strong>samplerShadow</strong>.) 3540There are distinct texture-combined sampler types for each texture target, 3541and for each of float, integer, and unsigned integer data types. 3542Texture accesses are done through built-in texture functions (described in 3543“<a href="#texture-functions">Texture Functions</a>”) and texture-combined samplers 3544are used to specify which texture to access and how it is to be filtered.</p> 3545</div> 3546<div class="paragraph"> 3547<p>Texture-combined sampler types are opaque types, 3548declared and behaving as described above for opaque types.</p> 3549</div> 3550</div> 3551<div class="sect4"> 3552<h5 id="images">Images</h5> 3553<div class="paragraph"> 3554<p>Image types are opaque types, declared and behaving as described above for 3555opaque types. 3556They can be further qualified with memory qualifiers. 3557When aggregated into arrays within a shader, images can only be indexed with 3558a constant integral expression.</p> 3559</div> 3560<div class="paragraph"> 3561<p>Image variables are handles to 3562two-, or three-dimensional images 3563corresponding to all or a portion of a single level of a texture image bound 3564to an image unit. 3565There are distinct image variable types for each texture target, and for 3566each of float, integer, and unsigned integer data types. 3567Image accesses should use an image type that matches the target of the 3568texture whose level is bound to the image unit, or for non-layered bindings 3569of 3D or array images should use the image type that matches the 3570dimensionality of the layer of the image (i.e., a layer of 3D, 2DArray, 3571Cube, or CubeArray should use 3572<strong>image2D</strong>). 3573If the image target type does not match the bound image in this manner, if 3574the data type does not match the bound image, or if the format layout 3575qualifier does not match the image unit format as described in section 35768.22 3577“Texture Image Loads and Stores” of the <a href="#references">OpenGL ES Specification</a>, the 3578results of image accesses are undefined but cannot include program 3579termination.</p> 3580</div> 3581<div class="paragraph"> 3582<p>Image variables are used in the image load, store, and atomic functions 3583described in “<a href="#image-functions">Image Functions</a>” to specify an image to 3584access.</p> 3585</div> 3586</div> 3587<div class="sect4"> 3588<h5 id="atomic-counters">Atomic Counters</h5> 3589<div class="paragraph"> 3590<p>Atomic counter types (e.g. <strong>atomic_uint</strong>) are opaque handles to counters, 3591declared and behaving as described above for opaque types. 3592The variables they declare specify which counter to access when using the 3593built-in atomic counter functions as described in 3594“<a href="#atomic-counter-functions">Atomic Counter Functions</a>”. 3595They are bound to buffers as described in 3596“<a href="#atomic-counter-layout-qualifiers">Atomic Counter Layout Qualifiers</a>”.</p> 3597</div> 3598<div class="paragraph"> 3599<p>Atomic counters aggregated into arrays within a shader can only be indexed 3600with dynamically uniform integral expressions, otherwise results are 3601undefined.</p> 3602</div> 3603<div class="paragraph"> 3604<p>Members of structures cannot be declared as atomic counter types.</p> 3605</div> 3606<div class="paragraph"> 3607<p>The default precision of all atomic types is <strong>highp</strong>. 3608It is an error to declare an atomic type with a different precision or to 3609specify the default precision for an atomic type to be <strong>lowp</strong> or <strong>mediump</strong>.</p> 3610</div> 3611<div class="paragraph"> 3612<p>Atomic counter types are not available when targeting Vulkan.</p> 3613</div> 3614</div> 3615<div class="sect4"> 3616<h5 id="_texture_sampler_and_samplershadow_types">Texture, <strong>sampler</strong>, and <strong>samplerShadow</strong> Types</h5> 3617<div class="paragraph"> 3618<p>Texture (e.g., <strong>texture2D</strong>), <strong>sampler</strong>, and <strong>samplerShadow</strong> types are opaque 3619types, declared and behaving as described above for opaque types. 3620These types are only available when targeting Vulkan. 3621When aggregated into arrays within a shader, these types can only be indexed 3622with a dynamically uniform expression, or texture lookup will result in 3623undefined values. 3624Texture variables are handles to one-, two-, and three-dimensional textures, 3625cube maps, etc., as enumerated in the basic types tables. 3626There are distinct texture types for each texture target, and for each of 3627float, integer, and unsigned integer data types. 3628Textures can be combined with a variable of type <strong>sampler</strong> or <strong>samplerShadow</strong> 3629to create a texture-combined sampler type (e.g., sampler2D, or sampler2DShadow). 3630This is done with a constructor, e.g., <code>sampler2D(texture2D, sampler)</code>, 3631<code>sampler2DShadow(texture2D, sampler)</code>, <code>sampler2DShadow(texture2D, samplerShadow)</code>, 3632or <code>sampler2D(texture2D, samplerShadow)</code> and is described in more detail 3633in section 5.4 "Constructors".</p> 3634</div> 3635</div> 3636<div class="sect4"> 3637<h5 id="_subpass_inputs">Subpass Inputs</h5> 3638<div class="paragraph"> 3639<p>Subpass-input types are only available when targeting Vulkan.</p> 3640</div> 3641<div class="paragraph"> 3642<p>Subpass-input types (e.g., <strong>subpassInput</strong>) are opaque types, declared 3643and behaving as described above for opaque types. 3644When aggregated into arrays within a shader, they can only be indexed with a 3645dynamically uniform integral expression, otherwise results are undefined.</p> 3646</div> 3647<div class="paragraph"> 3648<p>Subpass-input types are handles to two-dimensional single sampled or 3649multi-sampled images, with distinct types for each of float, integer, 3650and unsigned integer data types.</p> 3651</div> 3652<div class="paragraph"> 3653<p>Subpass-input types are only available in fragment shaders. It is 3654an error to use them in any other stage.</p> 3655</div> 3656</div> 3657</div> 3658<div class="sect3"> 3659<h4 id="structures">4.1.8. Structures</h4> 3660<div class="paragraph"> 3661<p>User-defined types can be created by aggregating other already defined types 3662into a structure using the <strong>struct</strong> keyword. 3663For example,</p> 3664</div> 3665<div class="listingblock"> 3666<div class="content"> 3667<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">struct</span> light { 3668 <span class="predefined-type">float</span> intensity; 3669 vec3 position; 3670} lightVar;</code></pre> 3671</div> 3672</div> 3673<div class="paragraph"> 3674<p>In this example, <em>light</em> becomes the name of the new type, and <em>lightVar</em> 3675becomes a variable of type <em>light</em>. 3676To declare variables of the new type, use its name (without the keyword 3677<strong>struct</strong>).</p> 3678</div> 3679<div class="listingblock"> 3680<div class="content"> 3681<pre class="CodeRay highlight"><code data-lang="c++">light lightVar2;</code></pre> 3682</div> 3683</div> 3684<div class="paragraph"> 3685<p>More formally, structures are declared as follows. 3686However, the definitive grammar is as given in 3687“<a href="#shading-language-grammar">Shading Language Grammar</a>”.</p> 3688</div> 3689<div class="openblock bnf"> 3690<div class="content"> 3691<div class="dlist"> 3692<dl> 3693<dt class="hdlist1"><em>struct-definition</em> : </dt> 3694<dd> 3695<p><em>qualifier<sub>opt</sub></em> <strong>struct</strong> name<sub>opt</sub>_ <strong>{</strong> <em>member-list</em> <strong>}</strong> 3696<em>declarators<sub>opt</sub></em> <strong>;</strong></p> 3697</dd> 3698<dt class="hdlist1"><em>member-list</em> : </dt> 3699<dd> 3700<p><em>member-declaration</em> <strong>;</strong><br> 3701<em>member-declaration</em> <em>member-list</em> <strong>;</strong></p> 3702</dd> 3703<dt class="hdlist1"><em>member-declaration</em> : </dt> 3704<dd> 3705<p><em>basic-type</em> <em>declarators</em> <strong>;</strong></p> 3706</dd> 3707</dl> 3708</div> 3709</div> 3710</div> 3711<div class="paragraph"> 3712<p>where <em>name</em> becomes the user-defined type, and can be used to declare 3713variables to be of this new type. 3714The <em>name</em> shares the same name space as other variables, types, and 3715functions. 3716All previously visible variables, types, constructors, or functions with 3717that name are hidden. 3718The optional <em>qualifier</em> only applies to any <em>declarators</em>, and is not part 3719of the type being defined for <em>name</em>.</p> 3720</div> 3721<div class="paragraph"> 3722<p>Structures must have at least one member declaration. 3723Member declarators may contain precision qualifiers, but use of any other 3724qualifier results in an error. 3725Bit fields are not supported. 3726Member types must be already defined (there are no forward references). 3727Member declarations cannot contain initializers. 3728Member declarators can contain arrays. 3729Such arrays must have a size specified, and the size must be a constant 3730integral expression that’s greater than zero (see 3731“<a href="#constant-expressions">Constant Expressions</a>”). 3732Each level of structure has its own name space for names given in member 3733declarators; such names need only be unique within that name space.</p> 3734</div> 3735<div class="paragraph"> 3736<p>Anonymous structures are not supported. 3737Embedded structure definitions are not supported.</p> 3738</div> 3739<div class="listingblock"> 3740<div class="content"> 3741<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">struct</span> S { <span class="predefined-type">float</span> f; }; <span class="comment">// Allowed: S is defined as a structure.</span> 3742 3743<span class="keyword">struct</span> T { 3744 S; <span class="comment">// Error: anonymous structures disallowed</span> 3745 <span class="keyword">struct</span> { ... }; <span class="comment">// Error: embedded structures disallowed</span> 3746 S s; <span class="comment">// Allowed: nested structure with a name.</span> 3747};</code></pre> 3748</div> 3749</div> 3750<div class="paragraph"> 3751<p>Structures can be initialized at declaration time using constructors, as 3752discussed in “<a href="#structure-constructors">Structure Constructors</a>”.</p> 3753</div> 3754<div class="paragraph"> 3755<p>Any restrictions on the usage of a type or qualifier also apply to any 3756structure that contains a member of that type or qualifier. 3757This also applies to structure members that are structures, recursively.</p> 3758</div> 3759<div class="paragraph"> 3760<p>Structures can contain variables of any type except:</p> 3761</div> 3762<div class="ulist"> 3763<ul> 3764<li> 3765<p><strong>atomic_uint</strong> (since there is no mechanism to specify the binding)</p> 3766</li> 3767<li> 3768<p>image types (since there is no mechanism to specify the format 3769qualifier)</p> 3770</li> 3771</ul> 3772</div> 3773</div> 3774<div class="sect3"> 3775<h4 id="arrays">4.1.9. Arrays</h4> 3776<div class="paragraph"> 3777<p>Variables of the same type can be aggregated into arrays by declaring a name 3778followed by brackets (<strong>[ ]</strong>) enclosing an optional size.</p> 3779</div> 3780<div class="paragraph"> 3781<p>When present, the array size must be a constant integral expression (see 3782“<a href="#constant-expressions">Constant Expressions</a>”) greater than zero. 3783The type of the size parameter can be a signed or unsigned integer and the 3784choice of type does not affect the type of the resulting array. 3785Arrays only have a single dimension (a single number within “[ ]”), 3786however, arrays of arrays can be declared. 3787Any type can be formed into an array.</p> 3788</div> 3789<div class="paragraph"> 3790<p>Arrays are sized either at compile-time or at run-time. 3791To size an array at compile-time, either the size must be specified within 3792the brackets as above or must be inferred from the type of the initializer.</p> 3793</div> 3794<div class="paragraph"> 3795<p>If an array is declared as the last member of a shader storage block and the 3796size is not specified at compile-time, it is sized at run-time. 3797In all other cases, arrays are sized only at compile-time. 3798An array declaration sized at compile-time which leaves the size of the 3799array unspecified is an error.</p> 3800</div> 3801<div class="paragraph"> 3802<p>For compile-time sized arrays, it is illegal to index an array with a 3803constant integral expression greater than or equal to the declared size or 3804with a negative constant expression. 3805Arrays declared as formal parameters in a function declaration must also 3806specify a size. 3807Undefined behavior results from indexing an array with a non-constant 3808expression that’s greater than or equal to the array’s size or less than 0. 3809If robust buffer access is enabled (see section 10.3.5 “Robust Buffer 3810Access” of the <a href="#references">OpenGL ES Specification</a>), such indexing must not result in 3811abnormal program termination. 3812The results are still undefined, but implementations are encouraged to 3813produce zero values for such accesses.</p> 3814</div> 3815<div class="paragraph"> 3816<p>Some examples are:</p> 3817</div> 3818<div class="listingblock"> 3819<div class="content"> 3820<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span> frequencies[<span class="integer">3</span>]; 3821uniform vec4 lightPosition[<span class="integer">4</span>u]; 3822<span class="directive">const</span> <span class="predefined-type">int</span> numLights = <span class="integer">2</span>; 3823light lights[numLights]; 3824vec4 a[<span class="integer">3</span>][<span class="integer">2</span>]; 3825a.length() <span class="comment">// this is 3</span> 3826a[x].length() <span class="comment">// this is 2</span> 3827<span class="comment">// a shader storage block, introduced in section 4.3.7 "Buffer Variables"</span> 3828buffer b { 3829 <span class="predefined-type">float</span> u[]; <span class="comment">// an error</span> 3830 vec4 v[]; <span class="comment">// okay, v will be sized at run-time</span> 3831} name[<span class="integer">3</span>]; <span class="comment">// when the block is arrayed, all u will be the same size,</span> 3832 <span class="comment">// but not necessarily all v, if sized dynamically</span></code></pre> 3833</div> 3834</div> 3835<div class="paragraph"> 3836<p>When the <strong>length</strong>() method will return a compile-time constant, the 3837expression in brackets (x above) will be evaluated and subject to the rules 3838required for array indices, but the array will not be dereferenced. 3839Thus, behavior is well defined even if the run-time value of the expression 3840is out of bounds.</p> 3841</div> 3842<div class="paragraph"> 3843<p>An array type can be formed by specifying a non-array type 3844(<a href="#type_specifier_nonarray">[type_specifier_nonarray]</a>) followed by an <a href="#array_specifier">[array_specifier]</a>.</p> 3845</div> 3846<div class="listingblock"> 3847<div class="content"> 3848<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span>[<span class="integer">5</span>]</code></pre> 3849</div> 3850</div> 3851<div class="paragraph"> 3852<p>Note that the construct <em>type [size]</em> does not always result in an array of 3853length <em>size</em> of type <em>type</em>:</p> 3854</div> 3855<div class="listingblock"> 3856<div class="content"> 3857<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span>[<span class="integer">2</span>][<span class="integer">3</span>] <span class="comment">// an array of size [2] of array of size [3] of float,</span> 3858 <span class="comment">// not size [3] of float[2]</span></code></pre> 3859</div> 3860</div> 3861<div class="paragraph"> 3862<p>This type can be used anywhere any other type can be used, including as the 3863return value from a function</p> 3864</div> 3865<div class="listingblock"> 3866<div class="content"> 3867<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span>[<span class="integer">5</span>] foo() { }</code></pre> 3868</div> 3869</div> 3870<div class="paragraph"> 3871<p>as a constructor of an array:</p> 3872</div> 3873<div class="listingblock"> 3874<div class="content"> 3875<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span>[<span class="integer">5</span>](<span class="float">3</span><span class="float">.4</span>, <span class="float">4</span><span class="float">.2</span>, <span class="float">5</span><span class="float">.0</span>, <span class="float">5</span><span class="float">.2</span>, <span class="float">1</span><span class="float">.1</span>)</code></pre> 3876</div> 3877</div> 3878<div class="paragraph"> 3879<p>as an unnamed parameter:</p> 3880</div> 3881<div class="listingblock"> 3882<div class="content"> 3883<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span> foo(<span class="predefined-type">float</span>[<span class="integer">5</span>])</code></pre> 3884</div> 3885</div> 3886<div class="paragraph"> 3887<p>and as an alternate way of declaring a variable or function parameter:</p> 3888</div> 3889<div class="listingblock"> 3890<div class="content"> 3891<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span>[<span class="integer">5</span>] a;</code></pre> 3892</div> 3893</div> 3894<div class="paragraph"> 3895<p>An array type can also be formed without specifying a size if the definition 3896includes an initializer:</p> 3897</div> 3898<div class="listingblock"> 3899<div class="content"> 3900<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span> x[] = <span class="predefined-type">float</span>[<span class="integer">2</span>] (<span class="float">1</span><span class="float">.0</span>, <span class="float">2</span><span class="float">.0</span>); <span class="comment">// declares an array of size 2</span> 3901<span class="predefined-type">float</span> y[] = <span class="predefined-type">float</span>[] (<span class="float">1</span><span class="float">.0</span>, <span class="float">2</span><span class="float">.0</span>, <span class="float">3</span><span class="float">.0</span>); <span class="comment">// declares an array of size 3</span> 3902<span class="predefined-type">float</span> a[<span class="integer">5</span>]; 3903<span class="predefined-type">float</span> b[] = a;</code></pre> 3904</div> 3905</div> 3906<div class="paragraph"> 3907<p>Note that the initializer itself does not need to be a constant expression 3908but the length of the initializer will be a constant expression.</p> 3909</div> 3910<div class="paragraph"> 3911<p>Arrays can have initializers formed from array constructors:</p> 3912</div> 3913<div class="listingblock"> 3914<div class="content"> 3915<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span> a[<span class="integer">5</span>] = <span class="predefined-type">float</span>[<span class="integer">5</span>](<span class="float">3</span><span class="float">.4</span>, <span class="float">4</span><span class="float">.2</span>, <span class="float">5</span><span class="float">.0</span>, <span class="float">5</span><span class="float">.2</span>, <span class="float">1</span><span class="float">.1</span>); 3916<span class="predefined-type">float</span> a[<span class="integer">5</span>] = <span class="predefined-type">float</span>[](<span class="float">3</span><span class="float">.4</span>, <span class="float">4</span><span class="float">.2</span>, <span class="float">5</span><span class="float">.0</span>, <span class="float">5</span><span class="float">.2</span>, <span class="float">1</span><span class="float">.1</span>); <span class="comment">// same thing</span></code></pre> 3917</div> 3918</div> 3919<div class="paragraph"> 3920<p>An array of arrays can be declared as:</p> 3921</div> 3922<div class="listingblock"> 3923<div class="content"> 3924<pre class="CodeRay highlight"><code data-lang="c++">vec4 a[<span class="integer">3</span>][<span class="integer">2</span>]; <span class="comment">// size-3 array of size-2 array of vec4</span></code></pre> 3925</div> 3926</div> 3927<div class="paragraph"> 3928<p>which declares a one-dimensional array of size 3 of one-dimensional arrays 3929of size 2 of <strong>vec4</strong>. 3930The following declarations do the same thing:</p> 3931</div> 3932<div class="listingblock"> 3933<div class="content"> 3934<pre class="CodeRay highlight"><code data-lang="c++">vec4[<span class="integer">2</span>] a[<span class="integer">3</span>]; <span class="comment">// size-3 array of size-2 array of vec4</span> 3935vec4[<span class="integer">3</span>][<span class="integer">2</span>] a; <span class="comment">// size-3 array of size-2 array of vec4</span></code></pre> 3936</div> 3937</div> 3938<div class="paragraph"> 3939<p>When in transparent memory (like in a uniform block), the layout is that the 3940inner-most (right-most in declaration) dimensions iterate faster than the 3941outer dimensions. 3942That is, for the above, the order in memory would be:</p> 3943</div> 3944<div class="dlist"> 3945<dl> 3946<dt class="hdlist1"></dt> 3947<dd> 3948<p>Low address : a[0][0] : a[0][1] : a[1][0] : a[1][1] : a[2][0] : a[2][1] 3949: High address</p> 3950</dd> 3951</dl> 3952</div> 3953<div class="paragraph"> 3954<p>The last member of a shader storage block (see “<a href="#buffer-variables">Buffer 3955Variables</a>”), may be declared without specifying a size. 3956For such arrays, the effective array size is inferred at run-time from the 3957size of the data store backing the shader storage block. 3958Such runtime-sized arrays may be indexed with general integer expressions, 3959but may not be passed as an argument to a function or indexed with a 3960negative constant expression.</p> 3961</div> 3962<div class="listingblock"> 3963<div class="content"> 3964<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">struct</span> S { <span class="predefined-type">float</span> f; }; 3965buffer ShaderStorageBlock1 3966{ 3967 vec4 a[]; <span class="comment">// illegal</span> 3968 vec4 b[]; <span class="comment">// legal, runtime-sized arrays are last member</span> 3969}; 3970buffer ShaderStorageBlock2 3971{ 3972 vec4 a[<span class="integer">4</span>]; <span class="comment">// legal, size declared</span> 3973 S b[]; <span class="comment">// legal, runtime-sized arrays are allowed,</span> 3974 <span class="comment">// including arrays of structures</span> 3975};</code></pre> 3976</div> 3977</div> 3978<div class="paragraph"> 3979<p>However, it is a compile-time error to assign to a runtime-sized array. 3980Assignments to individual elements of the array is allowed.</p> 3981</div> 3982<div class="paragraph"> 3983<p>Arrays have a fixed number of elements. 3984This can be obtained by using the <strong>length</strong>() method:</p> 3985</div> 3986<div class="listingblock"> 3987<div class="content"> 3988<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span> a[<span class="integer">5</span>]; 3989a.length(); <span class="comment">// returns 5</span></code></pre> 3990</div> 3991</div> 3992<div class="paragraph"> 3993<p>The return value is a signed integral expression. 3994For compile-time sized arrays, the value returned by the length method is a 3995constant expression. 3996For run-time sized arrays , the value returned will not be constant 3997expression and will be determined at run time based on the size of the 3998buffer object providing storage for the block.</p> 3999</div> 4000<div class="paragraph"> 4001<p>The precision is determined using the same rules as for other cases where 4002there is no intrinsic precision. 4003See “<a href="#precision-qualifiers">Precision Qualifiers</a>”.</p> 4004</div> 4005<div class="paragraph"> 4006<p>Any restrictions on the usage of a type also apply to arrays of that type. 4007This applies recursively.</p> 4008</div> 4009</div> 4010</div> 4011<div class="sect2"> 4012<h3 id="scoping">4.2. Scoping</h3> 4013<div class="paragraph"> 4014<p>The scope of a declaration determines where the declaration is visible. 4015GLSL ES uses a system of statically nested scopes. 4016This allows names to be redefined within a shader.</p> 4017</div> 4018<div class="sect3"> 4019<h4 id="definition-of-terms">4.2.1. Definition of Terms</h4> 4020<div class="paragraph"> 4021<p>The term <em>scope</em> refers to a specified region of the program where names are 4022guaranteed to be visible. 4023For example, a <em>compound_statement_with_scope</em> ('{' <em>statement</em> <em>statement</em> 4024…​ 4025'}') defines a scope.</p> 4026</div> 4027<div class="paragraph"> 4028<p>A <em>nested scope</em> is a scope defined within an outer scope.</p> 4029</div> 4030<div class="paragraph"> 4031<p>The terms '<em>same scope'</em> and '<em>current scope</em>' are equivalent to the term 4032'<em>scope</em>' but used to emphasize that nested scopes are excluded.</p> 4033</div> 4034<div class="paragraph"> 4035<p>The <em>scope of a declaration</em> is the region or regions of the program where 4036that declaration is visible.</p> 4037</div> 4038<div class="paragraph"> 4039<p>A <em>name space</em> defines where names may be defined. 4040Within a single name space, a name has at most one entry, specifying it to 4041be one of: structure, variable, or function.</p> 4042</div> 4043<div class="paragraph"> 4044<p>In general, each scope has an associated name space. 4045However, in certain cases e.g. for uniforms, multiple scopes share the same 4046name space. 4047In these cases, conflicting declarations are an error, even though the name 4048is only visible in the scopes where it is declared.</p> 4049</div> 4050</div> 4051<div class="sect3"> 4052<h4 id="types-of-scope">4.2.2. Types of Scope</h4> 4053<div class="paragraph"> 4054<p>The scope of a variable is determined by where it is declared. 4055If it is declared outside all function definitions, it has global scope, 4056which starts from where it is declared and persists to the end of the shader 4057it is declared in. 4058If it is declared in a <strong>while</strong> test or a <strong>for</strong> statement, then it is scoped 4059to the end of the following sub-statement (specified as 4060<em>statement-no-new-scope</em> in the grammar). 4061Otherwise, if it is declared as a statement within a compound statement, it 4062is scoped to the end of that compound statement. 4063If it is declared as a parameter in a function definition, it is scoped 4064until the end of that function definition. 4065A function’s parameter declarations and body together form a single scope.</p> 4066</div> 4067<div class="listingblock"> 4068<div class="content"> 4069<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">int</span> f( <span class="comment">/* nested scope begins here */</span> <span class="predefined-type">int</span> k) 4070{ 4071 <span class="predefined-type">int</span> k = k + <span class="integer">3</span>; <span class="comment">// redeclaration error of the name k</span> 4072 ... 4073} 4074<span class="predefined-type">int</span> f(<span class="predefined-type">int</span> k) 4075{ 4076 { 4077 <span class="predefined-type">int</span> k = k + <span class="integer">3</span>; <span class="comment">// 2nd k is parameter, initializing nested first k</span> 4078 <span class="predefined-type">int</span> m = k <span class="comment">// use of new k, which is hiding the parameter</span> 4079 } 4080}</code></pre> 4081</div> 4082</div> 4083<div class="paragraph"> 4084<p>For both for and while loops, the sub-statement itself does not introduce a 4085new scope for variable names, so the following has a redeclaration 4086compile-time error:</p> 4087</div> 4088<div class="listingblock"> 4089<div class="content"> 4090<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">for</span> ( <span class="comment">/* nested scope begins here */</span> <span class="predefined-type">int</span> i = <span class="integer">0</span>; i < <span class="integer">10</span>; i++) 4091{ 4092 <span class="predefined-type">int</span> i; <span class="comment">// redeclaration error</span> 4093}</code></pre> 4094</div> 4095</div> 4096<div class="paragraph"> 4097<p>The body of a <strong>do</strong>-<strong>while</strong> loop introduces a new scope lasting only between 4098the do and while (not including the while test expression), whether or not 4099the body is simple or compound:</p> 4100</div> 4101<div class="listingblock"> 4102<div class="content"> 4103<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">int</span> _i_ = <span class="integer">17</span>; 4104<span class="keyword">do</span> 4105 <span class="predefined-type">int</span> i = <span class="integer">4</span>; <span class="comment">// okay, in nested scope</span> 4106<span class="keyword">while</span> (i == <span class="integer">0</span>); <span class="comment">// i is 17, scoped outside the do-while body</span></code></pre> 4107</div> 4108</div> 4109<div class="paragraph"> 4110<p>The statement following a <strong>switch</strong> (…​) forms a nested scope.</p> 4111</div> 4112<div class="paragraph"> 4113<p>Representing the if construct as:</p> 4114</div> 4115<div class="paragraph"> 4116<p><strong>if</strong> if-expression <strong>then</strong> if-statement <strong>else</strong> else-statement,</p> 4117</div> 4118<div class="paragraph"> 4119<p>a variable declared in the if-statement is scoped to the end of the 4120if-statement. 4121A variable declared in the else-statement is scoped to the end of the 4122else-statement. 4123This applies both when these statements are simple statements and when they 4124are compound statements. 4125The if-expression does not allow new variables to be declared, hence does 4126not form a new scope.</p> 4127</div> 4128<div class="paragraph"> 4129<p>Within a declaration, the scope of a name starts immediately after the 4130initializer if present or immediately after the name being declared if not. 4131Several examples:</p> 4132</div> 4133<div class="listingblock"> 4134<div class="content"> 4135<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">int</span> x = <span class="integer">1</span>; 4136{ 4137 <span class="predefined-type">int</span> x = <span class="integer">2</span>,<span class="comment">/* 2nd x visible here */</span> y = x; <span class="comment">// y is initialized to 2</span> 4138 <span class="predefined-type">int</span> z = z; <span class="comment">// error if z not previously defined.</span> 4139} 4140{ 4141<span class="predefined-type">int</span> x = x; <span class="comment">// x is initialized to '1'</span> 4142}</code></pre> 4143</div> 4144</div> 4145<div class="paragraph"> 4146<p>A structure name declaration is visible at the end of the <em>struct_specifier</em> 4147in which it was declared:</p> 4148</div> 4149<div class="listingblock"> 4150<div class="content"> 4151<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">struct</span> S 4152{ 4153 <span class="predefined-type">int</span> x; 4154}; 4155{ 4156 S S = S(<span class="integer">0</span>); <span class="comment">// 'S' is only visible as a struct and constructor</span> 4157 S; <span class="comment">// 'S' is now visible as a variable</span> 4158} 4159<span class="predefined-type">int</span> x = x; <span class="comment">// Error if x has not been previously defined.</span></code></pre> 4160</div> 4161</div> 4162</div> 4163<div class="sect3"> 4164<h4 id="redeclaring-names">4.2.3. Redeclaring Names</h4> 4165<div class="paragraph"> 4166<p>All variable names, structure type names, and function names in a given 4167scope share the same name space. 4168Function names can be redeclared in the same scope, with the same or 4169different parameters, without error. 4170Otherwise, within a shader, a declared name cannot be redeclared in the same 4171scope; doing so results in a redeclaration error. 4172If a nested scope redeclares a name used in an outer scope, it hides all 4173existing uses of that name. 4174There is no way to access the hidden name or make it unhidden, without 4175exiting the scope that hid it.</p> 4176</div> 4177<div class="paragraph"> 4178<p>Names of built-in functions cannot be redeclared as functions. 4179Therefore overloading or redefining built-in functions is an error.</p> 4180</div> 4181<div class="paragraph"> 4182<p>A <em>declaration</em> is considered to be a statement that adds a name or 4183signature to the symbol table. 4184A <em>definition</em> is a statement that fully defines that name or signature. 4185E.g.</p> 4186</div> 4187<div class="listingblock"> 4188<div class="content"> 4189<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">int</span> f();<span class="comment">// declaration;</span> 4190<span class="predefined-type">int</span> f() {<span class="keyword">return</span> <span class="integer">0</span>;}<span class="comment">// declaration and definition</span> 4191<span class="predefined-type">int</span> x; <span class="comment">// declaration and definition</span> 4192<span class="predefined-type">int</span> a[<span class="integer">4</span>];<span class="comment">// array declaration and definition</span> 4193<span class="keyword">struct</span> S {<span class="predefined-type">int</span> x;};<span class="comment">// structure declaration and definition</span></code></pre> 4194</div> 4195</div> 4196<div class="paragraph"> 4197<p>The determination of equivalence of two declarations depends on the type of 4198declaration. 4199For functions, the whole function signature must be considered (see 4200“Function Definitions”). 4201For variables (including arrays) and structures only the names must match.</p> 4202</div> 4203<div class="paragraph"> 4204<p>Within each scope, a name may be declared either as a variable declaration 4205<em>or</em> as function declarations <em>or</em> as a structure.</p> 4206</div> 4207<div class="paragraph"> 4208<p>Examples of combinations that are allowed:</p> 4209</div> 4210<div class="paragraph"> 4211<p>1.</p> 4212</div> 4213<div class="openblock"> 4214<div class="content"> 4215<div class="listingblock"> 4216<div class="content"> 4217<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span> f(<span class="predefined-type">int</span>) {...} 4218<span class="directive">void</span> f(<span class="predefined-type">float</span>) {...}<span class="comment">// function overloading allowed</span></code></pre> 4219</div> 4220</div> 4221</div> 4222</div> 4223<div class="paragraph"> 4224<p>2.</p> 4225</div> 4226<div class="openblock"> 4227<div class="content"> 4228<div class="listingblock"> 4229<div class="content"> 4230<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span> f(<span class="predefined-type">int</span>);<span class="comment">// 1^st^ declaration (allowed)</span> 4231<span class="directive">void</span> f(<span class="predefined-type">int</span>);<span class="comment">// repeated declaration (allowed)</span> 4232<span class="directive">void</span> f(<span class="predefined-type">int</span>) {...}<span class="comment">// single definition (allowed)</span></code></pre> 4233</div> 4234</div> 4235</div> 4236</div> 4237<div class="paragraph"> 4238<p>Examples of combinations that are disallowed:</p> 4239</div> 4240<div class="paragraph"> 4241<p>1.</p> 4242</div> 4243<div class="openblock"> 4244<div class="content"> 4245<div class="listingblock"> 4246<div class="content"> 4247<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span> f(<span class="predefined-type">int</span>) {...} 4248<span class="directive">void</span> f(<span class="predefined-type">int</span>) {...}<span class="comment">// Error: repeated definition</span></code></pre> 4249</div> 4250</div> 4251</div> 4252</div> 4253<div class="paragraph"> 4254<p>2.</p> 4255</div> 4256<div class="openblock"> 4257<div class="content"> 4258<div class="listingblock"> 4259<div class="content"> 4260<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span> f(<span class="predefined-type">int</span>); 4261<span class="keyword">struct</span> f {<span class="predefined-type">int</span> x;};<span class="comment">// Error: type 'f' conflicts with function 'f'</span></code></pre> 4262</div> 4263</div> 4264</div> 4265</div> 4266<div class="paragraph"> 4267<p>3.</p> 4268</div> 4269<div class="openblock"> 4270<div class="content"> 4271<div class="listingblock"> 4272<div class="content"> 4273<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">struct</span> f {<span class="predefined-type">int</span> x;}; 4274<span class="predefined-type">int</span> f;<span class="comment">// Error: conflicts with the type 'f'</span></code></pre> 4275</div> 4276</div> 4277</div> 4278</div> 4279<div class="paragraph"> 4280<p>4.</p> 4281</div> 4282<div class="openblock"> 4283<div class="content"> 4284<div class="listingblock"> 4285<div class="content"> 4286<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">int</span> a[<span class="integer">3</span>]; 4287<span class="predefined-type">int</span> a[<span class="integer">3</span>];<span class="comment">// Error: repeated array definition</span></code></pre> 4288</div> 4289</div> 4290</div> 4291</div> 4292<div class="paragraph"> 4293<p>5.</p> 4294</div> 4295<div class="openblock"> 4296<div class="content"> 4297<div class="listingblock"> 4298<div class="content"> 4299<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">int</span> x; 4300<span class="predefined-type">int</span> x;<span class="comment">// Error: repeated variable definition</span></code></pre> 4301</div> 4302</div> 4303</div> 4304</div> 4305</div> 4306<div class="sect3"> 4307<h4 id="global-scope">4.2.4. Global Scope</h4> 4308<div class="paragraph"> 4309<p>The built-in functions are scoped in the global scope users declare global 4310variables in. 4311That is, a shader’s global scope, available for user-defined functions and 4312global variables, is the same as the scope containing the built-in 4313functions. 4314Function declarations (prototypes) cannot occur inside of functions; they 4315must be at global scope. 4316Hence it is not possible to hide a name with a function.</p> 4317</div> 4318</div> 4319<div class="sect3"> 4320<h4 id="shared-globals">4.2.5. Shared Globals</h4> 4321<div class="paragraph"> 4322<p>Shared globals are variables that can be accessed by multiple compilation 4323units. 4324In GLSL ES the only shared globals are uniforms. 4325Vertex shader outputs are not considered to be shared globals since they 4326must pass through the rasterization stage before they are used as input by 4327the fragment shader.</p> 4328</div> 4329<div class="paragraph"> 4330<p>Shared globals share the same name space, and must be declared with the same 4331type and precision. 4332They will share the same storage. 4333Shared global arrays must have the same base type and the same explicit 4334size. 4335Scalars must have exactly the same precision, type name and type definition. 4336Structures must have the same name, sequence of type names, and type 4337definitions, and member names to be considered the same type. 4338This rule applies recursively for nested or embedded types.</p> 4339</div> 4340</div> 4341</div> 4342<div class="sect2"> 4343<h3 id="storage-qualifiers">4.3. Storage Qualifiers</h3> 4344<div class="paragraph"> 4345<p>Variable declarations may have at most one storage qualifier specified in 4346front of the type. 4347These are summarized as</p> 4348</div> 4349<table class="tableblock frame-all grid-all stretch"> 4350<colgroup> 4351<col style="width: 50%;"> 4352<col style="width: 50%;"> 4353</colgroup> 4354<thead> 4355<tr> 4356<th class="tableblock halign-left valign-top">Storage Qualifier</th> 4357<th class="tableblock halign-left valign-top">Meaning</th> 4358</tr> 4359</thead> 4360<tbody> 4361<tr> 4362<td class="tableblock halign-left valign-top"><p class="tableblock"><none: default></p></td> 4363<td class="tableblock halign-left valign-top"><p class="tableblock">local read/write memory, or an input parameter to a 4364 function</p></td> 4365</tr> 4366<tr> 4367<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>const</strong></p></td> 4368<td class="tableblock halign-left valign-top"><p class="tableblock">a compile-time constant</p></td> 4369</tr> 4370<tr> 4371<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>in</strong></p></td> 4372<td class="tableblock halign-left valign-top"><p class="tableblock">linkage into a shader from a previous stage, variable 4373 is copied in</p></td> 4374</tr> 4375<tr> 4376<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>out</strong></p></td> 4377<td class="tableblock halign-left valign-top"><p class="tableblock">linkage out of a shader to a subsequent stage, 4378 variable is copied out</p></td> 4379</tr> 4380<tr> 4381<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>uniform</strong></p></td> 4382<td class="tableblock halign-left valign-top"><p class="tableblock">value does not change across the primitive being 4383 processed, uniforms form the linkage between a shader, 4384 API, and the application</p></td> 4385</tr> 4386<tr> 4387<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>buffer</strong></p></td> 4388<td class="tableblock halign-left valign-top"><p class="tableblock">value is stored in a buffer object, and can be read or 4389 written both by shader invocations and the API</p></td> 4390</tr> 4391<tr> 4392<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>shared</strong></p></td> 4393<td class="tableblock halign-left valign-top"><p class="tableblock">compute shader only; variable storage is shared across 4394 all work items in a workgroup</p></td> 4395</tr> 4396</tbody> 4397</table> 4398<div class="paragraph"> 4399<p>Some input and output qualified variables can be qualified with at most one 4400additional auxiliary storage qualifier:</p> 4401</div> 4402<table class="tableblock frame-all grid-all stretch"> 4403<colgroup> 4404<col style="width: 50%;"> 4405<col style="width: 50%;"> 4406</colgroup> 4407<thead> 4408<tr> 4409<th class="tableblock halign-left valign-top">Auxiliary Storage Qualifier</th> 4410<th class="tableblock halign-left valign-top">Meaning</th> 4411</tr> 4412</thead> 4413<tbody> 4414<tr> 4415<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>centroid</strong></p></td> 4416<td class="tableblock halign-left valign-top"><p class="tableblock">centroid-based interpolation</p></td> 4417</tr> 4418<tr> 4419<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>sample</strong></p></td> 4420<td class="tableblock halign-left valign-top"><p class="tableblock">per-sample interpolation</p></td> 4421</tr> 4422<tr> 4423<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>patch</strong></p></td> 4424<td class="tableblock halign-left valign-top"><p class="tableblock">per-tessellation-patch attributes</p></td> 4425</tr> 4426</tbody> 4427</table> 4428<div class="paragraph"> 4429<p>Local variables can only use the <strong>const</strong> storage qualifier (or use no 4430storage qualifier).</p> 4431</div> 4432<div class="paragraph"> 4433<p>Note that function parameters can use <strong>const</strong>, <strong>in</strong>, and <strong>out</strong> qualifiers, 4434but as <em>parameter qualifiers</em>. 4435Parameter qualifiers are discussed in 4436“<a href="#function-calling-conventions">Function Calling Conventions</a>”.</p> 4437</div> 4438<div class="paragraph"> 4439<p>Function return types and structure members do not use storage qualifiers.</p> 4440</div> 4441<div class="paragraph"> 4442<p>Data types for communication from one run of a shader executable to its next 4443run (to communicate between fragments or between vertices) do not exist. 4444This would prevent parallel execution of the same shader executable on 4445multiple vertices or fragments.</p> 4446</div> 4447<div class="paragraph"> 4448<p>In declarations of global variables with no storage qualifier or with a 4449const qualifier, any initializer must be a constant expression. 4450Declarations of global variables with other storage qualifiers may not 4451contain initializers. 4452Global variables without storage qualifiers that are not initialized in 4453their declaration or by the application will not be initialized, 4454but rather will enter <em>main()</em> with undefined values.</p> 4455</div> 4456<div class="sect3"> 4457<h4 id="default-storage-qualifier">4.3.1. Default Storage Qualifier</h4> 4458<div class="paragraph"> 4459<p>If no qualifier is present on a global variable, then the variable has no 4460linkage to the application or shaders running on other pipeline stages. 4461For either global or local unqualified variables, the declaration will 4462appear to allocate memory associated with the processor it targets. 4463This variable will provide read/write access to this allocated memory.</p> 4464</div> 4465</div> 4466<div class="sect3"> 4467<h4 id="constant-qualifier">4.3.2. Constant Qualifier</h4> 4468<div class="paragraph"> 4469<p>Named compile-time constants 4470can be declared using 4471the <strong>const</strong> qualifier. 4472Any variables qualified as constant are read-only variables for that shader. 4473Declaring variables as constant allows more descriptive shaders than using 4474hard-wired numerical constants. 4475The <strong>const</strong> qualifier can be used with any of the non-void transparent basic 4476data types, as well as with structures and arrays of these. 4477It is an error to write to a <strong>const</strong> variable outside of its 4478declaration, so they must be initialized when declared. 4479For example,</p> 4480</div> 4481<div class="listingblock"> 4482<div class="content"> 4483<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">const</span> vec3 zAxis = vec3 (<span class="float">0</span><span class="float">.0</span>, <span class="float">0</span><span class="float">.0</span>, <span class="float">1</span><span class="float">.0</span>);</code></pre> 4484</div> 4485</div> 4486<div class="paragraph"> 4487<p>Structure members may not be qualified with <strong>const</strong>. 4488Structure variables can be declared as <strong>const</strong>, and initialized with a 4489structure 4490constructor.</p> 4491</div> 4492<div class="paragraph"> 4493<p>Initializers for <strong>const</strong> declarations 4494must be constant expressions, as defined in 4495“<a href="#constant-expressions">Constant Expressions</a>”.</p> 4496</div> 4497</div> 4498<div class="sect3"> 4499<h4 id="constant-expressions">4.3.3. Constant Expressions</h4> 4500<div class="paragraph"> 4501<p>SPIR-V specialization constants are expressed in GLSL ES as <strong>const</strong> with the 4502layout qualifier <strong>constant_id</strong>, as described in 4503“<a href="#specialization-constant-qualifier">Specialization-Constant 4504Qualifier.</a>”</p> 4505</div> 4506<div class="paragraph"> 4507<p>A <em>constant expression</em> is one of</p> 4508</div> 4509<div class="ulist"> 4510<ul> 4511<li> 4512<p>A literal value (e.g. <strong>5</strong> or <strong>true</strong>).</p> 4513</li> 4514<li> 4515<p>A variable declared with the <strong>const</strong> qualifier and an initializer, where 4516the initializer is a constant expression. 4517This includes both <strong>const</strong> declared with a specialization-constant 4518layout qualifier, e.g. <strong>layout</strong>(<strong>constant_id</strong> = …​), and those declared 4519without a specialization-constant layout qualifier.</p> 4520</li> 4521<li> 4522<p>Built-in variables qualified as <strong>const</strong>.</p> 4523</li> 4524<li> 4525<p>An expression formed by an operator on operands that are all constant 4526expressions, including getting an element of a constant array, or a 4527member of a constant structure, or components of a constant vector. 4528However, the lowest precedence operators of the sequence operator (<strong>,</strong>) 4529and the assignment operators (<strong>=</strong>, <strong>+=</strong>, <strong>…​</strong>) are not included in the 4530operators that can create a constant expression. 4531Also, an array access with a specialization constant as an index does 4532not result in a constant expression.</p> 4533</li> 4534<li> 4535<p>The <strong>length</strong>() method on a compile-time sized array, whether or not the 4536object itself is constant.</p> 4537</li> 4538<li> 4539<p>A constructor whose arguments are all constant expressions.</p> 4540</li> 4541<li> 4542<p>For non-specialization constants only: 4543A built-in function call whose arguments are all constant expressions, 4544with the exception of the texture lookup functions. 4545This rule excludes functions with a <strong>void</strong> return or functions that have 4546an <strong>out</strong> parameter. 4547The built-in functions <strong>dFdx</strong>, <strong>dFdy</strong>, and <strong>fwidth</strong> must return 0 when 4548evaluated inside an initializer with an argument that is a constant 4549expression.</p> 4550</li> 4551</ul> 4552</div> 4553<div class="paragraph"> 4554<p>Function calls to user-defined functions (non-built-in functions) cannot be 4555used to form constant expressions.</p> 4556</div> 4557<div class="paragraph"> 4558<p>Scalar, vector, matrix, array and structure variables are constant 4559expressions if qualified as <strong>const</strong>. 4560Opaque types cannot be constant expressions.</p> 4561</div> 4562<div class="paragraph"> 4563<p>A <em>constant integral expression</em> is a constant expression that evaluates to 4564a scalar signed or unsigned integer.</p> 4565</div> 4566<div class="paragraph"> 4567<p>Constant expressions will be evaluated in an invariant way so as to create 4568the same value in multiple shaders when the same constant expressions appear 4569in those shaders. 4570See “<a href="#the-invariant-qualifier">The Invariant Qualifier</a>” for more details 4571on how to create invariant expressions and 4572“<a href="#precision-qualifiers">Precision Qualifiers</a>” for detail on how 4573expressions are evaluated.</p> 4574</div> 4575<div class="paragraph"> 4576<p>Constant expressions respect the <strong>precise</strong> and <strong>invariant</strong> qualifiers but 4577will be always be evaluated in an invariant way, independent of the use of 4578such qualification, so as to create the same value in multiple shaders when 4579the same constant expressions appear in those shaders. 4580See “<a href="#the-invariant-qualifier">The Invariant Qualifier</a>” and 4581“<a href="#the-precise-qualifier">The Precise Qualifier</a>” for more details on how 4582to create invariant expressions.</p> 4583</div> 4584<div class="paragraph"> 4585<p>Constant-expressions may be evaluated by a 4586host platform, and are therefore not required to compute the same value that 4587the same expression would evaluate to on the shader execution target. 4588However, the host must use the same or greater precision than the target 4589would use. 4590When the precision qualification cannot be determined, the expression is 4591evaluated at <strong>highp</strong>. 4592See “<a href="#default-precision-qualifiers">Default Precision Qualifiers</a>”.</p> 4593</div> 4594<div class="paragraph"> 4595<p>Specialization-constant expressions are never evaluated by the compiler 4596front end, but instead retain the expression’s operations needed to evaluate 4597them later on the host.</p> 4598</div> 4599</div> 4600<div class="sect3"> 4601<h4 id="input-variables">4.3.4. Input Variables</h4> 4602<div class="paragraph"> 4603<p>Shader input variables are declared with the <strong>in</strong> storage qualifier. 4604They form the input interface between previous stages of the API 4605pipeline and the declaring shader. 4606Input variables must be declared at global scope. 4607Values from the previous pipeline stage are copied into input variables at 4608the beginning of shader execution. 4609It is an error to write to a variable declared as an input.</p> 4610</div> 4611<div class="paragraph"> 4612<p>Only the input variables that are 4613actually 4614read need to be written by the 4615previous stage; it is allowed to have superfluous declarations of input 4616variables.</p> 4617</div> 4618<div class="paragraph"> 4619<p>See “<a href="#built-in-variables">Built-In Variables</a>” for a list of the built-in 4620input names.</p> 4621</div> 4622<div class="paragraph"> 4623<p>Vertex shader input variables (or attributes) receive per-vertex data. 4624It is an error to use auxiliary storage or interpolation qualifiers 4625on a vertex shader input. 4626The values copied in are established by the API or through the use 4627of the layout identifier <strong>location</strong>.</p> 4628</div> 4629<div class="paragraph"> 4630<p>It is a compile-time error to declare a vertex shader input with, or that 4631contains, any of the following types:</p> 4632</div> 4633<div class="ulist"> 4634<ul> 4635<li> 4636<p>A <a href="#booleans">boolean type</a></p> 4637</li> 4638<li> 4639<p>An <a href="#opaque-types">opaque type</a></p> 4640</li> 4641<li> 4642<p>An array</p> 4643</li> 4644<li> 4645<p>A structure</p> 4646</li> 4647</ul> 4648</div> 4649<div class="paragraph"> 4650<p>Example declarations in a vertex shader:</p> 4651</div> 4652<div class="listingblock"> 4653<div class="content"> 4654<pre class="CodeRay highlight"><code data-lang="c++">in vec4 position; 4655in vec3 normal; 4656in vec2 texCoord[<span class="integer">4</span>];</code></pre> 4657</div> 4658</div> 4659<div class="paragraph"> 4660<p>It is expected that graphics hardware will have a small number of fixed 4661vector locations for passing vertex inputs. 4662Therefore, the OpenGL ES Shading Language defines each non-matrix input variable as taking up 4663one such vector location. 4664There is an implementation-dependent limit on the number of locations that 4665can be used, and if this is exceeded it will cause a link-time error. 4666(Declared input variables that are not statically used do not count against 4667this limit.) A scalar input counts the same amount against this limit as a 4668<strong>vec4</strong>, so applications may want to consider packing groups of four 4669unrelated float inputs together into a vector to better utilize the 4670capabilities of the underlying hardware. 4671A matrix input will use up multiple locations. 4672The number of locations used will equal the number of columns in the matrix.</p> 4673</div> 4674<div class="paragraph"> 4675<p>Tessellation control, evaluation, and geometry shader input variables get 4676the per-vertex values written out by output variables of the same names in 4677the previous active shader stage. 4678For these inputs, <strong>centroid</strong> and interpolation qualifiers are allowed, but 4679have no effect. 4680Since tessellation control, tessellation evaluation, and geometry shaders 4681operate on a set of vertices, each input variable (or input block, see 4682interface blocks below) needs to be declared as an array. 4683For example,</p> 4684</div> 4685<div class="listingblock"> 4686<div class="content"> 4687<pre class="CodeRay highlight"><code data-lang="c++">in <span class="predefined-type">float</span> foo[]; <span class="comment">// geometry shader input for vertex "out float foo"</span></code></pre> 4688</div> 4689</div> 4690<div class="paragraph"> 4691<p>Each element of such an array corresponds to one vertex of the primitive 4692being processed. 4693Each array can optionally have a size declared. 4694For geometry shaders, the array size will be set by, (or if provided must be 4695consistent with) the input <strong>layout</strong> declaration(s) establishing the type of 4696input primitive, as described later in “<a href="#input-layout-qualifiers">Input 4697Layout Qualifiers</a>”.</p> 4698</div> 4699<div class="paragraph"> 4700<p>Some inputs and outputs are <em>arrayed</em>, meaning that for an interface between 4701two shader stages either the input or output declaration requires an extra 4702level of array indexing for the declarations to match. 4703For example, with the interface between a vertex shader and a geometry 4704shader, vertex shader output variables and geometry shader input variables 4705of the same name must have matching types, except that the geometry shader 4706will have one more array dimension than the vertex shader, to allow for 4707vertex indexing. 4708If such an arrayed interface variable is not declared with the necessary 4709additional input or output array dimension, a link-time error will result. 4710Geometry shader inputs, tessellation control shader inputs and outputs, and 4711tessellation evaluation inputs all have an additional level of arrayness 4712relative to other shader inputs and outputs. 4713These inputs and outputs are known as <em>per-vertex-arrayed</em> inputs and 4714outputs. 4715Component limits for arrayed interfaces (e.g. 4716<em>gl_MaxTessControlInputComponents</em>) are limits per vertex, not limits for 4717the entire interface.</p> 4718</div> 4719<div class="paragraph"> 4720<p>For non-arrayed interfaces (meaning array dimensionally stays the same 4721between stages), it is a link-time error if the input variable is not 4722declared with the same type, including array dimensionality, as the matching 4723output variable.</p> 4724</div> 4725<div class="paragraph"> 4726<p>The link-time type-matching rules apply to all declared input and output 4727variables, whether or not they are used.</p> 4728</div> 4729<div class="paragraph"> 4730<p>Additionally, tessellation evaluation shaders support per-patch input 4731variables declared with the <strong>patch</strong> and <strong>in</strong> qualifiers. 4732Per-patch input variables are filled with the values of per-patch output 4733variables written by the tessellation control shader. 4734Per-patch inputs may be declared as one-dimensional arrays, but are not 4735indexed by vertex number. 4736Applying the <strong>patch</strong> qualifier to inputs can only be done in tessellation 4737evaluation shaders. 4738As with other input variables, per-patch inputs must be declared using the 4739same type and qualification as per-patch outputs from the previous 4740(tessellation control) shader stage. 4741It is a compile-time error to use <strong>patch</strong> with inputs in any other stage.</p> 4742</div> 4743<div class="paragraph"> 4744<p>It is a compile-time error to declare a tessellation control, tessellation 4745evaluation or geometry shader input with, or that contains, any of the 4746following types:</p> 4747</div> 4748<div class="ulist"> 4749<ul> 4750<li> 4751<p>A <a href="#booleans">boolean type</a></p> 4752</li> 4753<li> 4754<p>An <a href="#opaque-types">opaque type</a></p> 4755</li> 4756<li> 4757<p>A structure containing an array</p> 4758</li> 4759<li> 4760<p>A structure containing a structure</p> 4761</li> 4762<li> 4763<p>For per-vertex-arrayed variables:</p> 4764<div class="ulist"> 4765<ul> 4766<li> 4767<p>Per-vertex-arrayed arrays of arrays</p> 4768</li> 4769<li> 4770<p>Per-vertex-arrayed arrays of structures</p> 4771</li> 4772</ul> 4773</div> 4774</li> 4775<li> 4776<p>For non-per-vertex-arrayed variables:</p> 4777<div class="ulist"> 4778<ul> 4779<li> 4780<p>An array of arrays</p> 4781</li> 4782<li> 4783<p>An array of structures</p> 4784</li> 4785</ul> 4786</div> 4787</li> 4788</ul> 4789</div> 4790<div class="paragraph"> 4791<p>Fragment shader inputs get per-fragment values, typically interpolated from 4792a previous stage’s outputs.</p> 4793</div> 4794<div class="paragraph"> 4795<p>It is a compile-time error to declare a fragment shader input with, or that 4796contains, any of the following types:</p> 4797</div> 4798<div class="ulist"> 4799<ul> 4800<li> 4801<p>A <a href="#booleans">boolean type</a></p> 4802</li> 4803<li> 4804<p>An <a href="#opaque-types">opaque type</a></p> 4805</li> 4806<li> 4807<p>An array of arrays</p> 4808</li> 4809<li> 4810<p>An array of structures</p> 4811</li> 4812<li> 4813<p>A structure containing an array</p> 4814</li> 4815<li> 4816<p>A structure containing a structure</p> 4817</li> 4818</ul> 4819</div> 4820<div class="paragraph"> 4821<p>Fragment shader inputs that are, or contain, integral 4822types must be 4823qualified with the interpolation qualifier <strong>flat</strong>.</p> 4824</div> 4825<div class="paragraph"> 4826<p>Fragment inputs are declared as in the following examples:</p> 4827</div> 4828<div class="listingblock"> 4829<div class="content"> 4830<pre class="CodeRay highlight"><code data-lang="c++">in vec3 normal; 4831centroid in vec2 TexCoord; 4832flat in vec3 myColor;</code></pre> 4833</div> 4834</div> 4835<div class="paragraph"> 4836<p>The fragment shader inputs form an interface with the last active shader in 4837the vertex processing pipeline. 4838For this interface, the last active shader stage output variables and 4839fragment shader input variables of the same name must match in type and 4840qualification, with a few exceptions: The storage qualifiers must, of 4841course, differ (one is <strong>in</strong> and one is <strong>out</strong>). 4842Also, 4843auxiliary qualification (e.g. <strong>centroid</strong>) may differ. 4844When 4845auxiliary qualifiers do not match, those provided in 4846the fragment shader supersede those provided in previous stages. 4847If any such qualifiers are completely missing in the fragment shaders, then 4848the default is used, rather than any qualifiers that may have been declared 4849in previous stages. 4850That is, what matters is what is declared in the fragment shaders, not what 4851is declared in shaders in previous stages.</p> 4852</div> 4853<div class="paragraph"> 4854<p>When an interface between shader stages is formed using shaders from two 4855separate program objects, it is not possible to detect mismatches between 4856inputs and outputs when the programs are linked. 4857When there are mismatches between inputs and outputs on such interfaces, 4858attempting to use the two programs in the same program pipeline will result 4859in program pipeline validation failures, as described in section 7.4.1 4860“Shader Interface Matching” of the <a href="#references">OpenGL ES Specification</a>.</p> 4861</div> 4862<div class="paragraph"> 4863<p>Shaders can ensure matches across such interfaces either by using input and 4864output layout qualifiers (sections “<a href="#input-layout-qualifiers">Input Layout 4865Qualifiers</a>” and “<a href="#output-layout-qualifiers">Output Layout 4866Qualifiers</a>”) or by using identical input and output declarations of 4867blocks or variables. 4868Complete rules for interface matching are found in section 7.4.1 “Shader 4869Interface Matching” of the <a href="#references">OpenGL ES Specification</a>.</p> 4870</div> 4871<div class="paragraph"> 4872<p>Compute shaders do not permit user-defined input variables and do not form a 4873formal interface with any other shader stage. 4874See “<a href="#compute-shader-special-variables">Compute Shader Special 4875Variables</a>” for a description of built-in compute shader input variables. 4876All other input to a compute shader is retrieved explicitly through image 4877loads, texture fetches, loads from uniforms or uniform buffers, or other 4878user supplied code.</p> 4879</div> 4880</div> 4881<div class="sect3"> 4882<h4 id="uniform-variables">4.3.5. Uniform Variables</h4> 4883<div class="paragraph"> 4884<p>The <strong>uniform</strong> qualifier is used to declare global variables whose values are 4885the same across the entire primitive being processed. 4886All <strong>uniform</strong> variables are read-only. 4887Except for variables declared within a uniform block, all uniform variables 4888are initialized to 0 at link time and may be updated through the API. 4889When targeting Vulkan, it is an error to declare <strong>uniform</strong> 4890variables outside a block.</p> 4891</div> 4892<div class="paragraph"> 4893<p>Example declarations are:</p> 4894</div> 4895<div class="listingblock"> 4896<div class="content"> 4897<pre class="CodeRay highlight"><code data-lang="c++">uniform vec4 lightPosition;</code></pre> 4898</div> 4899</div> 4900<div class="paragraph"> 4901<p>The <strong>uniform</strong> qualifier can be used with any of the basic data types, or 4902when declaring a variable whose type is a structure, or an array of any of 4903these.</p> 4904</div> 4905<div class="paragraph"> 4906<p>There is an implementation-dependent limit on the amount of storage for 4907uniforms that can be used for each type of shader and if this is exceeded it 4908will cause a compile-time or link-time error. 4909Uniform variables that are declared but not 4910statically 4911used do not count against this limit. 4912The number of user-defined uniform variables and the number of built-in 4913uniform variables that are used within a shader are added together to 4914determine whether available uniform storage has been exceeded.</p> 4915</div> 4916<div class="paragraph"> 4917<p>Uniforms in shaders all share a single global name space when linked into a 4918program or separable program. 4919Hence, the types, 4920precisions, 4921and any location specifiers of all statically used uniform variables with the 4922same name must match across all shaders that are linked into a single program. 4923However it is not required to repeat the 4924location specifier in all the linked shaders. 4925While this single uniform name space is cross stage, a uniform variable 4926name’s scope is per stage: If a uniform variable name is declared in one 4927stage (e.g. a vertex shader) but not in another (e.g. a fragment shader), 4928then that name is still available in the other stage for a different use.</p> 4929</div> 4930<div class="paragraph"> 4931<p>A compile or link-time error is generated if any of the explicitly given or 4932compiler generated uniform locations is greater than the 4933implementation-defined maximum number of uniform locations minus one.</p> 4934</div> 4935<div class="paragraph"> 4936<p>Unlike locations for inputs and outputs, uniform locations are logical 4937values, not register locations, and there is no concept of overlap. 4938For example:</p> 4939</div> 4940<div class="listingblock"> 4941<div class="content"> 4942<pre class="CodeRay highlight"><code data-lang="c++">layout(location = <span class="integer">2</span>) uniform mat4 x; 4943layout(location = <span class="integer">3</span>) uniform mat4 y; <span class="comment">// No overlap with x</span> 4944layout(location = <span class="integer">2</span>) in mat4 x; 4945layout(location = <span class="integer">3</span>) in mat4 y; <span class="comment">// Error, locations conflict with x</span></code></pre> 4946</div> 4947</div> 4948</div> 4949<div class="sect3"> 4950<h4 id="output-variables">4.3.6. Output Variables</h4> 4951<div class="paragraph"> 4952<p>Shader output variables are declared with the <strong>out</strong> storage qualifier. 4953They form the output interface between the declaring shader and the 4954subsequent stages of the API pipeline. 4955Output variables must be declared at global scope. 4956During shader execution they will behave as normal unqualified global 4957variables. 4958Their values are copied out to the subsequent pipeline stage on shader exit. 4959Only output variables that are read by the subsequent pipeline stage need to 4960be written; it is allowed to have superfluous declarations of output 4961variables.</p> 4962</div> 4963<div class="paragraph"> 4964<p>There is <em>not</em> an <strong>inout</strong> storage qualifier for declaring a single variable 4965name as both input and output to a shader. 4966Also, a variable cannot be declared with both the <strong>in</strong> and the <strong>out</strong> 4967qualifiers, this will result in a compile-time or link-time error. 4968Output variables must be declared with different names than input variables. 4969However, nesting an input or output inside an interface block with an 4970instance name allows the same names with one referenced through a block 4971instance name.</p> 4972</div> 4973<div class="paragraph"> 4974<p>Vertex, tessellation evaluation, and geometry output variables output 4975per-vertex data and are declared using the <strong>out</strong> storage qualifier. 4976Applying <strong>patch</strong> to an output can only be done in a tessellation control 4977shader. 4978It is a compile-time error to use <strong>patch</strong> on outputs in any other stage.</p> 4979</div> 4980<div class="paragraph"> 4981<p>It is a compile-time error to declare a vertex, tessellation evaluation, 4982tessellation control, or geometry shader output with, or that contains, any 4983of the following types:</p> 4984</div> 4985<div class="ulist"> 4986<ul> 4987<li> 4988<p>A <a href="#booleans">boolean type</a></p> 4989</li> 4990<li> 4991<p>An <a href="#opaque-types">opaque type</a></p> 4992</li> 4993<li> 4994<p>A structure containing an array</p> 4995</li> 4996<li> 4997<p>A structure containing a structure</p> 4998</li> 4999<li> 5000<p>For per-vertex-arrayed variables (applies to tessellation control, 5001tessellation evaluation and geometry shaders):</p> 5002<div class="ulist"> 5003<ul> 5004<li> 5005<p>Per-vertex-arrayed arrays of arrays</p> 5006</li> 5007<li> 5008<p>Per-vertex-arrayed arrays of structures</p> 5009</li> 5010</ul> 5011</div> 5012</li> 5013<li> 5014<p>For non-per-vertex-arrayed variables:</p> 5015<div class="ulist"> 5016<ul> 5017<li> 5018<p>An array of arrays</p> 5019</li> 5020<li> 5021<p>An array of structures</p> 5022</li> 5023</ul> 5024</div> 5025</li> 5026</ul> 5027</div> 5028<div class="paragraph"> 5029<p>Vertex shader outputs may be qualified with the interpolation qualifier 5030<strong>flat</strong><sup>1</sup>.</p> 5031</div> 5032<div class="dlist"> 5033<dl> 5034<dt class="hdlist1">1</dt> 5035<dd> 5036<p>Unlike previous versions of the OpenGL ES Shading Language, there is no requirement for 5037outputs containing integers to be qualified as <strong>flat</strong>, since the vertex 5038shader may interface with the tessellation control shader. 5039However, in all cases, the qualifier must match across interfaces.</p> 5040</dd> 5041</dl> 5042</div> 5043<div class="paragraph"> 5044<p>Individual outputs are declared as in the following examples:</p> 5045</div> 5046<div class="listingblock"> 5047<div class="content"> 5048<pre class="CodeRay highlight"><code data-lang="c++">out vec3 normal; 5049centroid out vec2 TexCoord; 5050invariant centroid out vec4 Color; 5051flat out vec3 myColor; 5052sample out vec4 perSampleColor;</code></pre> 5053</div> 5054</div> 5055<div class="paragraph"> 5056<p>These can also appear in interface blocks, as described in 5057“<a href="#interface-blocks">Interface Blocks</a>”. 5058Interface blocks allow simpler addition of arrays to the interface from 5059vertex to geometry shader. 5060They also allow a fragment shader to have the same input interface as a 5061geometry shader for a given vertex shader.</p> 5062</div> 5063<div class="paragraph"> 5064<p>Tessellation control shader output variables are used to output 5065per-vertex and per-patch data. 5066Per-vertex output variables are arrayed (see <em>arrayed</em> under 5067“<a href="#input-variables">Input Variables</a>”) and declared using the <strong>out</strong> 5068qualifier without the <strong>patch</strong> qualifier. 5069Per-patch output variables are declared using the <strong>patch</strong> and <strong>out</strong> 5070qualifiers.</p> 5071</div> 5072<div class="paragraph"> 5073<p>Since tessellation control shaders produce an arrayed primitive comprising 5074multiple vertices, each per-vertex output variable (or output block, see 5075interface blocks below) needs to be declared as an array. 5076For example,</p> 5077</div> 5078<div class="listingblock"> 5079<div class="content"> 5080<pre class="CodeRay highlight"><code data-lang="c++">out <span class="predefined-type">float</span> foo[]; <span class="comment">// feeds next stage input "in float foo[]"</span></code></pre> 5081</div> 5082</div> 5083<div class="paragraph"> 5084<p>Each element of such an array corresponds to one vertex of the primitive 5085being produced. 5086Each array can optionally have a size declared. 5087The array size will be set by (or if provided must be consistent with) the 5088output layout declaration(s) establishing the number of vertices in the 5089output patch, as described later in 5090“<a href="#tessellation-control-outputs">Tessellation Control Outputs</a>”.</p> 5091</div> 5092<div class="paragraph"> 5093<p>Each tessellation control shader invocation has a corresponding output patch 5094vertex, and may assign values to per-vertex outputs only if they belong to 5095that corresponding vertex. 5096If a per-vertex output variable is used as an l-value, it is a compile-time 5097or link-time error if the expression indicating the vertex index is not the 5098identifier <em>gl_InvocationID</em>.</p> 5099</div> 5100<div class="paragraph"> 5101<p>The order of execution of a tessellation control shader invocation relative 5102to the other invocations for the same input patch is undefined unless the 5103built-in function <strong>barrier</strong>() is used. 5104This provides some control over relative execution order. 5105When a shader invocation calls <strong>barrier</strong>(), its execution pauses until all 5106other invocations have reached the same point of execution. 5107Output variable assignments performed by any invocation executed prior to 5108calling <strong>barrier</strong>() will be visible to any other invocation after the call 5109to <strong>barrier</strong>() returns.</p> 5110</div> 5111<div class="paragraph"> 5112<p>Because tessellation control shader invocations execute in undefined order 5113between barriers, the values of per-vertex or per-patch output variables 5114will sometimes be undefined. 5115Consider the beginning and end of shader execution and each call to 5116<strong>barrier</strong>() as synchronization points. 5117The value of an output variable will be undefined in any of the three 5118following cases:</p> 5119</div> 5120<div class="olist arabic"> 5121<ol class="arabic"> 5122<li> 5123<p>At the beginning of execution.</p> 5124</li> 5125<li> 5126<p>At each synchronization point, unless</p> 5127<div class="openblock"> 5128<div class="content"> 5129<div class="ulist"> 5130<ul> 5131<li> 5132<p>the value was well-defined after the previous synchronization point and 5133was not written by any invocation since, or</p> 5134</li> 5135<li> 5136<p>the value was written by exactly one shader invocation since the previous 5137synchronization point, or</p> 5138</li> 5139<li> 5140<p>the value was written by multiple shader invocations since the previous 5141synchronization point, and the last write performed by all such 5142invocations wrote the same value.</p> 5143</li> 5144</ul> 5145</div> 5146</div> 5147</div> 5148</li> 5149<li> 5150<p>When read by a shader invocation, if</p> 5151<div class="openblock"> 5152<div class="content"> 5153<div class="ulist"> 5154<ul> 5155<li> 5156<p>the value was undefined at the previous synchronization point and has not 5157been written by the same shader invocation since, or</p> 5158</li> 5159<li> 5160<p>the output variable is written to by any other shader invocation between 5161the previous and next synchronization points, even if that assignment 5162occurs in code following the read.</p> 5163</li> 5164</ul> 5165</div> 5166</div> 5167</div> 5168</li> 5169</ol> 5170</div> 5171<div class="paragraph"> 5172<p>Fragment outputs output per-fragment data and are declared using the <strong>out</strong> 5173storage qualifier. 5174It is an error to use auxiliary storage qualifiers or 5175interpolation qualifiers in a fragment shader output declaration. 5176It is a compile-time error to declare a fragment shader output with, or that 5177contains, any of the following types:</p> 5178</div> 5179<div class="ulist"> 5180<ul> 5181<li> 5182<p>A <a href="#booleans">boolean type</a></p> 5183</li> 5184<li> 5185<p>An <a href="#opaque-types">opaque type</a></p> 5186</li> 5187<li> 5188<p>A matrix type</p> 5189</li> 5190<li> 5191<p>A structure</p> 5192</li> 5193<li> 5194<p>An array of arrays</p> 5195</li> 5196</ul> 5197</div> 5198<div class="paragraph"> 5199<p>Fragment shader outputs declared as arrays may only be indexed by a constant 5200integral expression.</p> 5201</div> 5202<div class="paragraph"> 5203<p>Fragment outputs are declared as in the following examples:</p> 5204</div> 5205<div class="listingblock"> 5206<div class="content"> 5207<pre class="CodeRay highlight"><code data-lang="c++">out vec4 FragmentColor; 5208out uint Luminosity;</code></pre> 5209</div> 5210</div> 5211<div class="paragraph"> 5212<p>Compute shaders have no built-in output variables, do not support 5213user-defined output variables and do not form a formal interface with any 5214other shader stage. 5215All outputs from a compute shader take the form of the side effects such as 5216image stores and operations on atomic counters.</p> 5217</div> 5218</div> 5219<div class="sect3"> 5220<h4 id="buffer-variables">4.3.7. Buffer Variables</h4> 5221<div class="paragraph"> 5222<p>The <strong>buffer</strong> qualifier is used to declare global variables whose values are 5223stored in the data store of a buffer object bound through the API. 5224Buffer variables can be read and written, with the underlying storage shared 5225among all active shader invocations. 5226Buffer variable memory reads and writes within a single shader invocation 5227are processed in order. 5228However, the order of reads and writes performed in one invocation relative 5229to those performed by another invocation is largely undefined. 5230Buffer variables may be qualified with memory qualifiers affecting how the 5231underlying memory is accessed, as described in “<a href="#memory-qualifiers">Memory 5232Qualifiers</a>”.</p> 5233</div> 5234<div class="paragraph"> 5235<p>The <strong>buffer</strong> qualifier can be used to declare interface blocks (see 5236“<a href="#interface-blocks">Interface Blocks</a>”), which are then referred to as 5237shader storage blocks. 5238It is a compile-time error to declare buffer variables outside a block. 5239Buffer variables cannot have initializers.</p> 5240</div> 5241<div class="admonitionblock note"> 5242<table> 5243<tr> 5244<td class="icon"> 5245<i class="fa icon-note" title="Note"></i> 5246</td> 5247<td class="content"> 5248<div class="title">Note</div> 5249<div class="paragraph"> 5250<p>The terms <em>shader storage buffer (object)</em>, and <em>shader storage block</em> are 5251often used interchangeably. 5252The former generally refers to the underlying storage whereas the latter 5253refers only to the interface definition in the shader. 5254Similarly for <em>uniform buffer objects</em> and _uniform blocks.</p> 5255</div> 5256</td> 5257</tr> 5258</table> 5259</div> 5260<div class="listingblock"> 5261<div class="content"> 5262<pre class="CodeRay highlight"><code data-lang="c++"><span class="comment">// use buffer to create a buffer block (shader storage block)</span> 5263buffer BufferName { <span class="comment">// externally visible name of buffer</span> 5264 <span class="predefined-type">int</span> count; <span class="comment">// typed, shared memory...</span> 5265 ... <span class="comment">// ...</span> 5266 vec4 v[]; <span class="comment">// last member may be an array that is not sized</span> 5267 <span class="comment">// until after link time (dynamically sized)</span> 5268} Name; <span class="comment">// name of block within the shader</span></code></pre> 5269</div> 5270</div> 5271<div class="paragraph"> 5272<p>There are implementation-dependent limits on the number of shader storage 5273blocks used for each type of shader, the combined number of shader storage 5274blocks used for a program, and the amount of storage required by each 5275individual shader storage block. 5276If any of these limits are exceeded, it will cause a compile-time or 5277link-time error.</p> 5278</div> 5279<div class="paragraph"> 5280<p>If multiple shaders are linked together, then they will share a single 5281global buffer variable name space. 5282Hence, the types of all declared buffer variables with the same name must 5283match across all shaders that are linked into a single program.</p> 5284</div> 5285<div class="paragraph"> 5286<p>Precision qualifiers for such variables need not match.</p> 5287</div> 5288</div> 5289<div class="sect3"> 5290<h4 id="shared-variables">4.3.8. Shared Variables</h4> 5291<div class="paragraph"> 5292<p>The <strong>shared</strong> qualifier is used to declare global variables that have storage 5293shared between all work items in a compute shader workgroup. 5294Variables declared as <strong>shared</strong> may only be used in compute shaders (see 5295“<a href="#compute-processor">Compute Processor</a>”). 5296Any other declaration of a <strong>shared</strong> variable is an error. 5297Shared variables are implicitly coherent (see 5298“<a href="#memory-qualifiers">Memory Qualifiers</a>”).</p> 5299</div> 5300<div class="paragraph"> 5301<p>Variables declared as <strong>shared</strong> may not have initializers and their contents 5302are undefined at the beginning of shader execution. 5303Any data written to <strong>shared</strong> variables will be visible to other work items 5304(executing the same shader) within the same workgroup.</p> 5305</div> 5306<div class="paragraph"> 5307<p>In the absence of synchronization, the order of reads and writes to the same 5308<strong>shared</strong> variable by different invocations of a shader is not defined.</p> 5309</div> 5310<div class="paragraph"> 5311<p>In order to achieve ordering with respect to reads and writes to <strong>shared</strong> 5312variables, control flow barriers must be employed using the <strong>barrier</strong>() function 5313(see “<a href="#shader-invocation-control-functions">Shader Invocation Control 5314Functions</a>”).</p> 5315</div> 5316<div class="paragraph"> 5317<p>There is a limit to the total size of all variables declared as <strong>shared</strong> in a 5318single program. 5319This limit, expressed in units of basic machine units may be determined by 5320using the OpenGL ES API to query the value of 5321MAX_COMPUTE_SHARED_MEMORY_SIZE.</p> 5322</div> 5323</div> 5324<div class="sect3"> 5325<h4 id="interface-blocks">4.3.9. Interface Blocks</h4> 5326<div class="paragraph"> 5327<p>Input, output, uniform, and buffer variable declarations can be grouped into 5328named interface blocks to provide coarser granularity backing than is 5329achievable with individual declarations. 5330They can have an optional instance name, used in the shader to reference 5331their members. 5332An output block of one programmable stage is backed by a corresponding input 5333block in the subsequent programmable stage. 5334A <em>uniform block</em> is backed by the application with a buffer object. 5335A block of buffer variables, called a <em>shader storage block</em>, is also backed 5336by the application with a buffer object. 5337It is a compile-time error to have an input block in a vertex shader or an 5338output block in a fragment shader. 5339These uses are reserved for future use.</p> 5340</div> 5341<div class="paragraph"> 5342<p>An interface block is started by an <strong>in</strong>, <strong>out</strong>, <strong>uniform</strong>, or <strong>buffer</strong> 5343keyword, followed by a block name, followed by an open curly brace (<strong>{</strong>) as 5344follows:</p> 5345</div> 5346<div class="openblock bnf"> 5347<div class="content"> 5348<div class="dlist"> 5349<dl> 5350<dt class="hdlist1"><em>interface-block</em> : </dt> 5351<dd> 5352<p><em>layout-qualifier<sub>opt</sub></em> <em>interface-qualifier</em> <em>block-name</em> <strong>{</strong> 5353<em>member-list</em> <strong>}</strong> <em>instance-name<sub>opt</sub></em> <strong>;</strong></p> 5354</dd> 5355</dl> 5356</div> 5357<div class="dlist"> 5358<dl> 5359<dt class="hdlist1"><em>interface-qualifier</em> : </dt> 5360<dd> 5361<p><strong>in</strong><br> 5362<strong>out</strong><br> 5363<strong>patch</strong> <strong>in</strong> // Note: Qualifiers can be in any order.<br> 5364<strong>patch</strong> <strong>out</strong><br> 5365<strong>uniform</strong><br> 5366<strong>buffer</strong></p> 5367</dd> 5368</dl> 5369</div> 5370<div class="dlist"> 5371<dl> 5372<dt class="hdlist1"><em>member-list</em> : </dt> 5373<dd> 5374<p><em>member-declaration</em><br> 5375<em>member-declaration</em> <em>member-list</em></p> 5376</dd> 5377<dt class="hdlist1"><em>member-declaration</em> : </dt> 5378<dd> 5379<p><em>layout-qualifier<sub>opt</sub></em> <em>qualifiers<sub>opt</sub></em> <em>type</em> <em>declarators</em> <strong>;</strong></p> 5380</dd> 5381</dl> 5382</div> 5383<div class="dlist"> 5384<dl> 5385<dt class="hdlist1"><em>instance-name</em> : </dt> 5386<dd> 5387<p><em>identifier</em><br> 5388<em>identifier</em> <strong>[</strong> <strong>]</strong><br> 5389<em>identifier</em> <strong>[</strong> <em>constant-integral-expression</em> <strong>]</strong></p> 5390</dd> 5391</dl> 5392</div> 5393</div> 5394</div> 5395<div class="paragraph"> 5396<p>Each of the above elements is discussed below, with the exception of layout 5397qualifiers (<em>layout-qualifier</em>), which are defined in the next section.</p> 5398</div> 5399<div class="paragraph"> 5400<p>First, an example,</p> 5401</div> 5402<div class="listingblock"> 5403<div class="content"> 5404<pre class="CodeRay highlight"><code data-lang="c++">uniform Transform { 5405 mat4 ModelViewMatrix; 5406 mat4 ModelViewProjectionMatrix; 5407 uniform mat3 NormalMatrix; <span class="comment">// allowed restatement of qualifier</span> 5408 <span class="predefined-type">float</span> Deformation; 5409};</code></pre> 5410</div> 5411</div> 5412<div class="paragraph"> 5413<p>The above establishes a uniform block named “Transform” with four uniforms 5414grouped inside it.</p> 5415</div> 5416<div class="paragraph"> 5417<p>Types and declarators are the same as for other input, output, uniform, and 5418buffer variable declarations outside blocks, with these exceptions:</p> 5419</div> 5420<div class="ulist"> 5421<ul> 5422<li> 5423<p>Opaque types are not allowed</p> 5424</li> 5425<li> 5426<p>Structure definitions cannot be nested inside a block</p> 5427</li> 5428<li> 5429<p>Arrays of arrays of blocks are not allowed, except for the case in the 5430tessellation pipe where the declaration is a per-vertex-array of arrays 5431of blocks.</p> 5432</li> 5433</ul> 5434</div> 5435<div class="paragraph"> 5436<p>If no optional qualifier is used in a member-declaration, the qualification 5437of the member includes all <strong>in</strong>, <strong>out</strong>, <strong>patch</strong>, <strong>uniform</strong>, or <strong>buffer</strong> as 5438determined by <em>interface-qualifier</em>. 5439If optional qualifiers are used, they can include interpolation qualifiers, 5440auxiliary storage qualifiers, 5441precision qualifiers, 5442and storage qualifiers and they must declare 5443an input, output, or uniform member consistent with the interface qualifier 5444of the block: Input variables, output variables, uniform variables, and 5445<strong>buffer</strong> members can only be in <strong>in</strong> blocks, <strong>out</strong> blocks, <strong>uniform</strong> blocks, 5446and shader storage blocks, respectively.</p> 5447</div> 5448<div class="paragraph"> 5449<p>Repeating the <strong>in</strong>, <strong>out</strong>, <strong>patch</strong>, <strong>uniform</strong>, or <strong>buffer</strong> interface 5450qualifier for a member’s storage qualifier is optional. 5451For example,</p> 5452</div> 5453<div class="listingblock"> 5454<div class="content"> 5455<pre class="CodeRay highlight"><code data-lang="c++">in Material { 5456 smooth in vec4 Color1; <span class="comment">// legal, input inside in block</span> 5457 smooth vec4 Color2; <span class="comment">// legal, 'in' inherited from 'in Material'</span> 5458 vec2 TexCoord; <span class="comment">// legal, TexCoord is an input</span> 5459 uniform <span class="predefined-type">float</span> Atten; <span class="comment">// illegal, mismatched storage qualifier</span> 5460};</code></pre> 5461</div> 5462</div> 5463<div class="paragraph"> 5464<p>A <em>shader interface</em> is defined to be one of these:</p> 5465</div> 5466<div class="ulist"> 5467<ul> 5468<li> 5469<p>All the uniform variables and uniform blocks declared in a program. 5470This spans all compilation units linked together within one program.</p> 5471</li> 5472<li> 5473<p>All the <strong>buffer</strong> blocks declared in a program.</p> 5474</li> 5475<li> 5476<p>The boundary between adjacent programmable pipeline stages: This spans 5477all the outputs declared in all compilation units of the first stage and 5478all the inputs declared in all compilation units of the second stage. 5479Note that for the purposes of this definition, the fragment shader and 5480the preceding shader are considered to have a shared boundary even 5481though in practice, all values passed to the fragment shader first pass 5482through the rasterizer and interpolator.</p> 5483</li> 5484</ul> 5485</div> 5486<div class="paragraph"> 5487<p>The block name (<em>block-name</em>) is used to match within shader interfaces: an 5488output block of one pipeline stage will be matched to an input block with 5489the same name in the subsequent pipeline stage. 5490For uniform or shader storage blocks, the application uses the block name to 5491identify the block. 5492Block names have no other use within a shader beyond interface matching; it 5493is an error 5494to use a block name at global scope for anything other than as a 5495block name (e.g. use of a block name for a global variable name or function 5496name is currently reserved). 5497It is a compile-time error to use the same block name for more than one 5498block declaration in the same shader interface (as defined above) within one 5499shader, even if the block contents are identical.</p> 5500</div> 5501<div class="paragraph"> 5502<p>Matched block names within a shader interface (as defined above) must match 5503in terms of having the same number of declarations with the same sequence of 5504types and the same sequence of member names, as well as having matching 5505member-wise layout qualification 5506as defined in “<a href="#matching-of-qualifiers">Matching of Qualifiers</a>”. 5507Matched uniform or shader storage block names (but not input or output block 5508names) must also either all be lacking an instance name or all having an 5509instance name, putting their members at the same scoping level. 5510When instance names are present on matched block names, it is allowed for 5511the instance names to differ; they need not match for the blocks to match. 5512Furthermore, if a matching block is declared as an array, then the array 5513sizes must also match (or follow array matching rules for the shader 5514interface between consecutive shader stages). 5515Any mismatch will generate a link-time error. 5516A block name is allowed to have different definitions in different shader 5517interfaces within the same shader, allowing, for example, an input block and 5518output block to have the same name.</p> 5519</div> 5520<div class="paragraph"> 5521<p>If an instance name (<em>instance-name</em>) is not used, the names declared inside 5522the block are scoped at the global level and accessed as if they were 5523declared outside the block. 5524If an instance name (<em>instance-name</em>) is used, then it puts all the members 5525inside a scope within its own name space, accessed with the field selector 5526(<strong>.</strong>) operator (analogously to structures). 5527For example,</p> 5528</div> 5529<div class="listingblock"> 5530<div class="content"> 5531<pre class="CodeRay highlight"><code data-lang="c++">in Light { 5532 vec4 LightPos; 5533 vec3 LightColor; 5534}; 5535in ColoredTexture { 5536 vec4 Color; 5537 vec2 TexCoord; 5538} Material; <span class="comment">// instance name</span> 5539vec3 Color; <span class="comment">// different Color than Material.Color</span> 5540vec4 LightPos; <span class="comment">// illegal, already defined</span> 5541... 5542... = LightPos; <span class="comment">// accessing LightPos</span> 5543... = Material.Color; <span class="comment">// accessing Color in ColoredTexture block</span></code></pre> 5544</div> 5545</div> 5546<div class="paragraph"> 5547<p>Outside the shading language (i.e., in the API), members are similarly 5548identified except the block name is always used in place of the instance 5549name (API accesses are to shader interfaces, not to shaders). 5550If there is no instance name, then the API does not use the block name to 5551access a member, just the member name.</p> 5552</div> 5553<div class="paragraph"> 5554<p>Within a shader interface, all declarations of the same global name must be 5555for the same object and must match in type and in whether they declare a 5556variable or member of a block with no instance name. 5557The API also needs this name to uniquely identify an object in the shader 5558interface. 5559It is a link-time error if any particular shader interface contains</p> 5560</div> 5561<div class="ulist"> 5562<ul> 5563<li> 5564<p>two different blocks, each having no instance name, and each having a 5565member of the same name, or</p> 5566</li> 5567<li> 5568<p>a variable outside a block, and a block with no instance name, where the 5569variable has the same name as a member in the block.</p> 5570</li> 5571</ul> 5572</div> 5573<div class="listingblock"> 5574<div class="content"> 5575<pre class="CodeRay highlight"><code data-lang="c++">out Vertex { 5576 vec4 Position; <span class="comment">// API transform/feedback will use "Vertex.Position"</span> 5577 vec2 Texture; 5578} Coords; <span class="comment">// shader will use "Coords.Position"</span> 5579out Vertex2 { 5580 vec4 Color; <span class="comment">// API will use "Color"</span> 5581 <span class="predefined-type">float</span> Color2; 5582}; 5583 5584<span class="comment">// in same program as Vertex2 above:</span> 5585out Vertex3 { 5586 <span class="predefined-type">float</span> Intensity; 5587 vec4 Color; <span class="comment">// ERROR, name collision with Color in Vertex2</span> 5588}; 5589<span class="predefined-type">float</span> Color2; <span class="comment">// ERROR, collides with Color2 in Vertex2</span></code></pre> 5590</div> 5591</div> 5592<div class="paragraph"> 5593<p>For blocks declared as arrays, the array index must also be included when 5594accessing members, as in this example</p> 5595</div> 5596<div class="listingblock"> 5597<div class="content"> 5598<pre class="CodeRay highlight"><code data-lang="c++">uniform Transform { <span class="comment">// API uses "Transform[2]" to refer to instance 2</span> 5599 mat4 ModelViewMatrix; 5600 mat4 ModelViewProjectionMatrix; 5601 <span class="predefined-type">float</span> Deformation; 5602} transforms[<span class="integer">4</span>]; 5603... 5604... = transforms[<span class="integer">2</span>].ModelViewMatrix; <span class="comment">// shader access of instance 2</span> 5605<span class="comment">// API uses "Transform.ModelViewMatrix" to query an offset or other query</span></code></pre> 5606</div> 5607</div> 5608<div class="paragraph"> 5609<p>For uniform or shader storage blocks declared as an array, each individual 5610array element corresponds to a separate buffer object bind range, backing 5611one instance of the block. 5612As the array size indicates the number of buffer objects needed, uniform and 5613shader storage block array declarations must specify an array size. 5614All indices used to index a shader storage block array must be constant 5615integral expressions. 5616A uniform block array can only be indexed with a dynamically uniform 5617integral expression, otherwise results are undefined.</p> 5618</div> 5619<div class="paragraph"> 5620<p>When using OpenGL ES API entry points to identify the name of an individual 5621block in an array of blocks, the name string may include an array index 5622(e.g. <em>Transform[2]</em>). 5623When using OpenGL ES API entry points to refer to offsets or other 5624characteristics of a block member, an array index must not be specified 5625(e.g. <em>Transform.ModelViewMatrix</em>). 5626See section 7.3.1 “Program Interfaces” of the <a href="#references">OpenGL ES Specification</a> for 5627details.</p> 5628</div> 5629<div class="paragraph"> 5630<p>Tessellation control, tessellation evaluation and geometry shader input 5631blocks must be declared as arrays and follow the array declaration and 5632linking rules for all shader inputs for the respective stages. 5633All other input and output block arrays must specify an array size.</p> 5634</div> 5635<div class="paragraph"> 5636<p>There are implementation-dependent limits on the number of uniform blocks 5637and the number of shader storage blocks that can be used per stage. 5638If either limit is exceeded, it will cause a link-time error.</p> 5639</div> 5640</div> 5641</div> 5642<div class="sect2"> 5643<h3 id="layout-qualifiers">4.4. Layout Qualifiers</h3> 5644<div class="paragraph"> 5645<p>Layout qualifiers can appear in several forms of declaration. 5646They can appear as part of an interface block definition or block member, as 5647shown in the grammar in the previous section. 5648They can also appear with just an <em>interface-qualifier</em> to establish layouts 5649of other declarations made with that qualifier:</p> 5650</div> 5651<div class="openblock bnf"> 5652<div class="content"> 5653<div class="paragraph"> 5654<p><em>layout-qualifier</em> <em>interface-qualifier</em> <strong>;</strong></p> 5655</div> 5656</div> 5657</div> 5658<div class="paragraph"> 5659<p>Or, they can appear with an individual variable declared with an interface 5660qualifier:</p> 5661</div> 5662<div class="openblock bnf"> 5663<div class="content"> 5664<div class="paragraph"> 5665<p><em>layout-qualifier</em> <em>interface-qualifier</em> <em>declaration</em> <strong>;</strong></p> 5666</div> 5667</div> 5668</div> 5669<div class="paragraph"> 5670<p>Declarations of layouts can only be made at global scope or block members, 5671and only where indicated in the following subsections; their details are 5672specific to what the interface qualifier is, and are discussed individually.</p> 5673</div> 5674<div class="paragraph"> 5675<p>The <em>layout-qualifier</em> expands to:</p> 5676</div> 5677<div class="openblock bnf"> 5678<div class="content"> 5679<div class="dlist"> 5680<dl> 5681<dt class="hdlist1"><em>layout-qualifier</em> : </dt> 5682<dd> 5683<p><strong>layout</strong> <strong>(</strong> <em>layout-qualifier-id-list</em> <strong>)</strong></p> 5684</dd> 5685<dt class="hdlist1"><em>layout-qualifier-id-list</em> : </dt> 5686<dd> 5687<p><em>layout-qualifier-id</em><br> 5688<em>layout-qualifier-id</em> <strong>,</strong> <em>layout-qualifier-id-list</em></p> 5689</dd> 5690<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 5691<dd> 5692<p><em>layout-qualifier-name</em><br> 5693<em>layout-qualifier-name</em> <strong>=</strong> <em>layout-qualifier-value</em><br> 5694<strong>shared</strong></p> 5695</dd> 5696</dl> 5697</div> 5698</div> 5699</div> 5700<div class="openblock bnf"> 5701<div class="content"> 5702<div class="dlist"> 5703<dl> 5704<dt class="hdlist1"><em>layout-qualifier-value</em> : </dt> 5705<dd> 5706<p><em>integer-constant</em></p> 5707</dd> 5708</dl> 5709</div> 5710</div> 5711</div> 5712<div class="paragraph"> 5713<p>The tokens used for <em>layout-qualifier-name</em> are identifiers, not keywords, 5714however, the <strong>shared</strong> keyword is allowed as a <em>layout-qualifier-id</em>. 5715Generally, they can be listed in any order. 5716Order-dependent meanings exist only if explicitly called out below. 5717As for other identifiers, they are case sensitive.</p> 5718</div> 5719<div class="paragraph"> 5720<p>The set of allowed layout qualifiers depends on the shader, the interface 5721and the variable type as specified in the following sections. 5722For example, a sampler in the default uniform block in a fragment shader can 5723have <strong>location</strong> and <strong>binding</strong> layout qualifiers but no others. 5724Invalid use of layout qualifiers is an error.</p> 5725</div> 5726<div class="paragraph"> 5727<p>The following table summarizes the use of layout qualifiers. 5728It shows for each one what kinds of declarations it may be applied to. 5729These are all discussed in detail in the following sections.</p> 5730</div> 5731<table class="tableblock frame-all grid-all stretch"> 5732<colgroup> 5733<col style="width: 16.6666%;"> 5734<col style="width: 16.6666%;"> 5735<col style="width: 16.6666%;"> 5736<col style="width: 16.6666%;"> 5737<col style="width: 16.6666%;"> 5738<col style="width: 16.667%;"> 5739</colgroup> 5740<thead> 5741<tr> 5742<th class="tableblock halign-left valign-middle">Layout Qualifier</th> 5743<th class="tableblock halign-center valign-middle">Qualifier Only</th> 5744<th class="tableblock halign-center valign-middle">Individual Variable</th> 5745<th class="tableblock halign-center valign-middle">Block</th> 5746<th class="tableblock halign-center valign-middle">Block Member</th> 5747<th class="tableblock halign-left valign-middle">Allowed Interfaces</th> 5748</tr> 5749</thead> 5750<tbody> 5751<tr> 5752<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>shared</strong><br> 5753 <strong>packed</strong><br> 5754 <strong>std140</strong><br> 5755 <strong>std430</strong></p></td> 5756<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5757<td class="tableblock halign-center valign-middle"></td> 5758<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5759<td class="tableblock halign-center valign-middle"></td> 5760<td class="tableblock halign-left valign-middle" rowspan="5"><p class="tableblock"><strong>uniform</strong> / <strong>buffer</strong></p></td> 5761</tr> 5762<tr> 5763<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>row_major</strong><br> 5764 <strong>column_major</strong></p></td> 5765<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5766<td class="tableblock halign-center valign-middle"></td> 5767<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5768<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5769</tr> 5770<tr> 5771<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>binding</strong> =</p></td> 5772<td class="tableblock halign-center valign-middle"></td> 5773<td class="tableblock halign-center valign-middle"><p class="tableblock">opaque types only</p></td> 5774<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5775<td class="tableblock halign-center valign-middle"></td> 5776</tr> 5777<tr> 5778<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>offset</strong> =</p></td> 5779<td class="tableblock halign-center valign-middle"></td> 5780<td class="tableblock halign-center valign-middle"><p class="tableblock">atomic counters only</p></td> 5781<td class="tableblock halign-center valign-middle"></td> 5782<td class="tableblock halign-center valign-middle"><p class="tableblock">Vulkan only</p></td> 5783</tr> 5784<tr> 5785<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>align</strong> =</p></td> 5786<td class="tableblock halign-center valign-middle"></td> 5787<td class="tableblock halign-center valign-middle"></td> 5788<td class="tableblock halign-center valign-middle"><p class="tableblock">Vulkan only</p></td> 5789<td class="tableblock halign-center valign-middle"><p class="tableblock">Vulkan only</p></td> 5790</tr> 5791<tr> 5792<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>set</strong> =</p></td> 5793<td class="tableblock halign-center valign-middle"></td> 5794<td class="tableblock halign-center valign-middle"><p class="tableblock">opaque types only</p></td> 5795<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5796<td class="tableblock halign-center valign-middle"></td> 5797<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>uniform</strong> / <strong>buffer</strong> (Vulkan only)</p></td> 5798</tr> 5799<tr> 5800<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>push_constant</strong></p></td> 5801<td class="tableblock halign-center valign-middle"></td> 5802<td class="tableblock halign-center valign-middle"></td> 5803<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5804<td class="tableblock halign-center valign-middle"></td> 5805<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>uniform</strong> (Vulkan only)</p></td> 5806</tr> 5807<tr> 5808<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>input_attachment_index</strong> =</p></td> 5809<td class="tableblock halign-center valign-middle"></td> 5810<td class="tableblock halign-center valign-middle"><p class="tableblock">subpass types only</p></td> 5811<td class="tableblock halign-center valign-middle"></td> 5812<td class="tableblock halign-center valign-middle"></td> 5813<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>uniform</strong> (Vulkan only)</p></td> 5814</tr> 5815<tr> 5816<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>location</strong> =</p></td> 5817<td class="tableblock halign-center valign-middle"></td> 5818<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5819<td class="tableblock halign-center valign-middle"></td> 5820<td class="tableblock halign-center valign-middle"></td> 5821<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>uniform</strong> / <strong>buffer</strong></p></td> 5822</tr> 5823<tr> 5824<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>location</strong> =</p></td> 5825<td class="tableblock halign-center valign-middle"></td> 5826<td class="tableblock halign-center valign-middle"><p class="tableblock">X<sup>1</sup></p></td> 5827<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5828<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5829<td class="tableblock halign-left valign-middle"><p class="tableblock">all <strong>in</strong> / <strong>out</strong>, except for compute</p></td> 5830</tr> 5831<tr> 5832<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>triangles</strong><br> 5833 <strong>quads</strong><br> 5834 <strong>isolines</strong></p></td> 5835<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5836<td class="tableblock halign-center valign-middle"></td> 5837<td class="tableblock halign-center valign-middle"></td> 5838<td class="tableblock halign-center valign-middle"></td> 5839<td class="tableblock halign-left valign-middle"><p class="tableblock">tessellation evaluation <strong>in</strong></p></td> 5840</tr> 5841<tr> 5842<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>equal_spacing</strong><br> 5843 <strong>fractional_even_spacing</strong><br> 5844 <strong>fractional_odd_spacing</strong></p></td> 5845<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5846<td class="tableblock halign-center valign-middle"></td> 5847<td class="tableblock halign-center valign-middle"></td> 5848<td class="tableblock halign-center valign-middle"></td> 5849<td class="tableblock halign-left valign-middle"><p class="tableblock">tessellation evaluation <strong>in</strong></p></td> 5850</tr> 5851<tr> 5852<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>cw</strong><br> 5853 <strong>ccw</strong></p></td> 5854<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5855<td class="tableblock halign-center valign-middle"></td> 5856<td class="tableblock halign-center valign-middle"></td> 5857<td class="tableblock halign-center valign-middle"></td> 5858<td class="tableblock halign-left valign-middle"><p class="tableblock">tessellation evaluation <strong>in</strong></p></td> 5859</tr> 5860<tr> 5861<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>point_mode</strong></p></td> 5862<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5863<td class="tableblock halign-center valign-middle"></td> 5864<td class="tableblock halign-center valign-middle"></td> 5865<td class="tableblock halign-center valign-middle"></td> 5866<td class="tableblock halign-left valign-middle"><p class="tableblock">tessellation evaluation <strong>in</strong></p></td> 5867</tr> 5868<tr> 5869<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>points</strong></p></td> 5870<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5871<td class="tableblock halign-center valign-middle"></td> 5872<td class="tableblock halign-center valign-middle"></td> 5873<td class="tableblock halign-center valign-middle"></td> 5874<td class="tableblock halign-left valign-middle"><p class="tableblock">geometry <strong>in</strong>/<strong>out</strong></p></td> 5875</tr> 5876<tr> 5877<td class="tableblock halign-left valign-middle"><p class="tableblock">[ <strong>points</strong> ]<br> 5878 <strong>lines</strong><br> 5879 <strong>lines_adjacency</strong><br> 5880 <strong>triangles</strong><br> 5881 <strong>triangles_adjacency</strong></p></td> 5882<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5883<td class="tableblock halign-center valign-middle"></td> 5884<td class="tableblock halign-center valign-middle"></td> 5885<td class="tableblock halign-center valign-middle"></td> 5886<td class="tableblock halign-left valign-middle"><p class="tableblock">geometry <strong>in</strong></p></td> 5887</tr> 5888<tr> 5889<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>invocations</strong> =</p></td> 5890<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5891<td class="tableblock halign-center valign-middle"></td> 5892<td class="tableblock halign-center valign-middle"></td> 5893<td class="tableblock halign-center valign-middle"></td> 5894<td class="tableblock halign-left valign-middle"><p class="tableblock">geometry <strong>in</strong></p></td> 5895</tr> 5896<tr> 5897<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>early_fragment_tests</strong></p></td> 5898<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5899<td class="tableblock halign-center valign-middle"></td> 5900<td class="tableblock halign-center valign-middle"></td> 5901<td class="tableblock halign-center valign-middle"></td> 5902<td class="tableblock halign-left valign-middle"><p class="tableblock">fragment <strong>in</strong></p></td> 5903</tr> 5904<tr> 5905<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>local_size_x</strong> =<br> 5906 <strong>local_size_y</strong> =<br> 5907 <strong>local_size_z</strong> =</p></td> 5908<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5909<td class="tableblock halign-center valign-middle"></td> 5910<td class="tableblock halign-center valign-middle"></td> 5911<td class="tableblock halign-center valign-middle"></td> 5912<td class="tableblock halign-left valign-middle"><p class="tableblock">compute <strong>in</strong></p></td> 5913</tr> 5914<tr> 5915<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>local_size_x_id</strong> =<br> 5916 <strong>local_size_y_id</strong> =<br> 5917 <strong>local_size_z_id</strong> =</p></td> 5918<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5919<td class="tableblock halign-center valign-middle"></td> 5920<td class="tableblock halign-center valign-middle"></td> 5921<td class="tableblock halign-center valign-middle"></td> 5922<td class="tableblock halign-left valign-middle"><p class="tableblock">compute <strong>in</strong> (SPIR-V only)</p></td> 5923</tr> 5924<tr> 5925<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>vertices</strong> =</p></td> 5926<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5927<td class="tableblock halign-center valign-middle"></td> 5928<td class="tableblock halign-center valign-middle"></td> 5929<td class="tableblock halign-center valign-middle"></td> 5930<td class="tableblock halign-left valign-middle"><p class="tableblock">tessellation control <strong>out</strong></p></td> 5931</tr> 5932<tr> 5933<td class="tableblock halign-left valign-middle"><p class="tableblock">[ <strong>points</strong> ]<br> 5934 <strong>line_strip</strong><br></p> 5935<p class="tableblock"> <strong>triangle_strip</strong></p></td> 5936<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5937<td class="tableblock halign-center valign-middle"></td> 5938<td class="tableblock halign-center valign-middle"></td> 5939<td class="tableblock halign-center valign-middle"></td> 5940<td class="tableblock halign-left valign-middle" rowspan="2"><p class="tableblock">geometry <strong>out</strong></p></td> 5941</tr> 5942<tr> 5943<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>max_vertices</strong> =</p></td> 5944<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5945<td class="tableblock halign-center valign-middle"></td> 5946<td class="tableblock halign-center valign-middle"></td> 5947<td class="tableblock halign-center valign-middle"></td> 5948</tr> 5949<tr> 5950<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>constant_id</strong> =</p></td> 5951<td class="tableblock halign-center valign-middle"></td> 5952<td class="tableblock halign-center valign-middle"><p class="tableblock">scalar only</p></td> 5953<td class="tableblock halign-center valign-middle"></td> 5954<td class="tableblock halign-center valign-middle"></td> 5955<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>const</strong> (SPIR-V only)</p></td> 5956</tr> 5957<tr> 5958<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>rgba32f</strong><br> 5959 <strong>rgba16f</strong><br> 5960 <strong>r32f</strong><br> 5961 <strong>rgba8</strong><br> 5962 <strong>rgba8_snorm</strong><br> 5963 <strong>rgba32i</strong><br> 5964 <strong>rgba16i</strong><br> 5965 <strong>rgba8i</strong><br> 5966 <strong>r32i</strong><br> 5967 <strong>rgba32ui</strong><br> 5968 <strong>rgba16ui</strong><br> 5969 <strong>rgba8ui</strong><br> 5970 <strong>r32ui</strong></p></td> 5971<td class="tableblock halign-center valign-middle"></td> 5972<td class="tableblock halign-center valign-middle"><p class="tableblock">image types only</p></td> 5973<td class="tableblock halign-center valign-middle"></td> 5974<td class="tableblock halign-center valign-middle"></td> 5975<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>uniform</strong></p></td> 5976</tr> 5977<tr> 5978<td class="tableblock halign-left valign-middle"><p class="tableblock"><strong>blend_support_multiply</strong><br> 5979 <strong>blend_support_screen</strong><br> 5980 <strong>blend_support_overlay</strong><br> 5981 <strong>blend_support_darken</strong><br> 5982 <strong>blend_support_lighten</strong><br> 5983 <strong>blend_support_colordodge blend_support_colorburn</strong><br> 5984 <strong>blend_support_hardlight</strong><br> 5985 <strong>blend_support_softlight</strong><br> 5986 <strong>blend_support_difference</strong><br> 5987 <strong>blend_support_exclusion</strong><br> 5988 <strong>blend_support_hsl_hue</strong><br> 5989 <strong>blend_support_hsl_saturation</strong><br> 5990 <strong>blend_support_hsl_color blend_support_hsl_luminosity</strong><br> 5991 <strong>blend_support_all_equations</strong></p></td> 5992<td class="tableblock halign-center valign-middle"><p class="tableblock">X</p></td> 5993<td class="tableblock halign-center valign-middle"></td> 5994<td class="tableblock halign-center valign-middle"></td> 5995<td class="tableblock halign-center valign-middle"></td> 5996<td class="tableblock halign-left valign-middle"><p class="tableblock">fragment <strong>out</strong></p></td> 5997</tr> 5998</tbody> 5999</table> 6000<div class="dlist"> 6001<dl> 6002<dt class="hdlist1">1</dt> 6003<dd> 6004<p>Location qualifiers are not allowed for members of an arrayed block, 6005except for per-vertex-arrays (see “<a href="#interface-blocks">Interface 6006Blocks</a>”).</p> 6007</dd> 6008</dl> 6009</div> 6010<div class="sect3"> 6011<h4 id="input-layout-qualifiers">4.4.1. Input Layout Qualifiers</h4> 6012<div class="paragraph"> 6013<p>Layout qualifiers specific to a particular shader language are discussed in 6014separate sections below.</p> 6015</div> 6016<div class="paragraph"> 6017<p>All shaders except compute shaders allow <strong>location</strong> layout qualifiers on 6018input variable declarations, input block declarations, and input block 6019member declarations.</p> 6020</div> 6021<div class="openblock bnf"> 6022<div class="content"> 6023<div class="dlist"> 6024<dl> 6025<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 6026<dd> 6027<p><strong>location</strong> <strong>=</strong> <em>layout-qualifier-value</em></p> 6028</dd> 6029</dl> 6030</div> 6031</div> 6032</div> 6033<div class="paragraph"> 6034<p>For example,</p> 6035</div> 6036<div class="listingblock"> 6037<div class="content"> 6038<pre class="CodeRay highlight"><code data-lang="c++">layout(location = <span class="integer">3</span>) in vec4 normal;</code></pre> 6039</div> 6040</div> 6041<div class="paragraph"> 6042<p>will establish that the shader input <em>normal</em> is assigned to vector location 6043number 60443. 6045For vertex shader inputs, the location specifies the number of the 6046vertex attribute from which input values are taken. 6047For inputs of all other shader types, the location specifies a vector number 6048that can be used to match against outputs from a previous shader stage, even 6049if that shader is in a different program object.</p> 6050</div> 6051<div class="paragraph"> 6052<p>The following language describes how many locations are consumed by a given 6053type. 6054However, geometry shader inputs, tessellation control shader inputs and 6055outputs, and tessellation evaluation inputs all have an additional level of 6056arrayness relative to other shader inputs and outputs. 6057This outer array level is removed from the type before considering how many 6058locations the type consumes.</p> 6059</div> 6060<div class="paragraph"> 6061<p>If a shader input is any scalar or vector type, it will consume a single 6062location.</p> 6063</div> 6064<div class="paragraph"> 6065<p>If the declared input (after potentially removing an outer array level as 6066just described above) is an array of size <em>n</em> and each of the elements takes 6067<em>m</em> locations, it will be assigned <em>m</em> * <em>n</em> consecutive locations starting 6068with the location specified. 6069For example,</p> 6070</div> 6071<div class="listingblock"> 6072<div class="content"> 6073<pre class="CodeRay highlight"><code data-lang="c++">layout(location = <span class="integer">6</span>) in vec4 colors[<span class="integer">3</span>];</code></pre> 6074</div> 6075</div> 6076<div class="paragraph"> 6077<p>will establish that the shader input <em>colors</em> is assigned to vector location 6078numbers 6, 7, and 8.</p> 6079</div> 6080<div class="paragraph"> 6081<p>If the declared input is an <em>n</em> × <em>m</em> 6082matrix, it will be assigned multiple locations starting with the location 6083specified. 6084The number of locations assigned for each matrix will be the same as for an 6085<em>n</em>-element array of <em>m</em>-component vectors. 6086For example,</p> 6087</div> 6088<div class="listingblock"> 6089<div class="content"> 6090<pre class="CodeRay highlight"><code data-lang="c++">layout(location = <span class="integer">9</span>) in mat4 transforms[<span class="integer">2</span>];</code></pre> 6091</div> 6092</div> 6093<div class="paragraph"> 6094<p>will establish that shader input <em>transforms</em> is assigned to vector 6095locations 9-16, with <em>transforms[0]</em> being assigned to locations 9-12, and 6096<em>transforms[1]</em> being assigned to locations 13-16.</p> 6097</div> 6098<div class="paragraph"> 6099<p>If the declared input is a structure or block, its members will be assigned 6100consecutive locations in their order of declaration, with the first member 6101assigned the location provided in the layout qualifier. 6102For a structure, this process applies to the entire structure. 6103It is a compile-time error to use a <strong>location</strong> qualifier on a member of a 6104structure. 6105For a block, this process applies to the entire block, or until the first 6106member is reached that has a <strong>location</strong> layout qualifier.</p> 6107</div> 6108<div class="paragraph"> 6109<p>When a block member is declared with a <strong>location</strong> qualifier, its location 6110comes from that qualifier; the member’s <strong>location</strong> qualifier overrides the 6111block-level declaration. 6112Subsequent members are again assigned consecutive locations, based on the 6113newest location, until the next member declared with a <strong>location</strong> qualifier. 6114The values used for locations do not have to be declared in increasing 6115order.</p> 6116</div> 6117<div class="paragraph"> 6118<p>If a block has no block-level <strong>location</strong> layout qualifier, it is required 6119that either all or none of its members have a <strong>location</strong> layout qualifier, 6120or a compile-time error results.</p> 6121</div> 6122<div class="paragraph"> 6123<p>If an input is declared as an array of blocks, excluding per-vertex-arrays 6124as required for tessellation, it is an error to declare a member of the 6125block with a <strong>location</strong> qualifier.</p> 6126</div> 6127<div class="paragraph"> 6128<p>When generating SPIR-V, all <strong>in</strong> and <strong>out</strong> qualified user-declared (non 6129built-in) variables and blocks (or all their members) must have a 6130shader-specified <strong>location</strong>. 6131Otherwise, a compile-time error is generated.</p> 6132</div> 6133<div class="paragraph"> 6134<p>The locations consumed by block and structure members are determined by 6135applying the rules above recursively as though the structure member were 6136declared as an input variable of the same type. 6137For example:</p> 6138</div> 6139<div class="listingblock"> 6140<div class="content"> 6141<pre class="CodeRay highlight"><code data-lang="c++">layout(location = <span class="integer">3</span>) in <span class="keyword">struct</span> S 6142{ 6143 vec3 a; <span class="comment">// gets location 3</span> 6144 mat2 b; <span class="comment">// gets locations 4 and 5</span> 6145 vec4 c[<span class="integer">2</span>]; <span class="comment">// gets locations 6 and 7</span> 6146 layout(location = <span class="integer">8</span>) vec2 A; <span class="comment">// ERROR, can't use on struct member</span> 6147} s; 6148layout(location = <span class="integer">4</span>) in block 6149{ 6150 vec4 d; <span class="comment">// gets location 4</span> 6151 vec4 e; <span class="comment">// gets location 5</span> 6152 layout(location = <span class="integer">7</span>) vec4 f; <span class="comment">// gets location 7</span> 6153 vec4 g; <span class="comment">// gets location 8</span> 6154 layout(location = <span class="integer">1</span>) vec4 h; <span class="comment">// gets location 1</span> 6155 vec4 i; <span class="comment">// gets location 2</span> 6156 vec4 j; <span class="comment">// gets location 3</span> 6157 vec4 k; <span class="comment">// ERROR, location 4 already used</span> 6158};</code></pre> 6159</div> 6160</div> 6161<div class="paragraph"> 6162<p>The number of input locations available to a shader is limited. 6163For vertex shaders, the limit is the advertised number of vertex attributes. 6164For all other shaders, the limit is implementation-dependent and must be no 6165less than one fourth of the advertised maximum input component count.</p> 6166</div> 6167<div class="paragraph"> 6168<p>A program will fail to link if any attached shader uses a location greater 6169than or equal to the number of supported locations, unless device-dependent 6170optimizations are able to make the program fit within available hardware 6171resources.</p> 6172</div> 6173<div class="paragraph"> 6174<p>A program will fail to link if explicit location assignments leave the 6175linker unable to find space for other variables without explicit 6176assignments.</p> 6177</div> 6178<div class="paragraph"> 6179<p>For the purposes of determining if a non-vertex input matches an output from 6180a previous shader stage, the <strong>location</strong> layout qualifier (if any) must 6181match.</p> 6182</div> 6183<div class="paragraph"> 6184<p>If a vertex shader input variable with no location assigned in the shader 6185text has a location specified through the OpenGL ES API, the API-assigned 6186location will be used. 6187Otherwise, such variables will be assigned a location by the linker. 6188See section 11.1.1 “Vertex Attributes” of the <a href="#references">OpenGL ES Specification</a> for 6189more details.</p> 6190</div> 6191<div class="paragraph"> 6192<p>It is an error if more than one input or element of a matrix input is bound 6193to the same location.</p> 6194</div> 6195<div class="sect4"> 6196<h5 id="tessellation-evaluation-inputs">Tessellation Evaluation Inputs</h5> 6197<div class="paragraph"> 6198<p>Additional input layout qualifier identifiers allowed for tessellation 6199evaluation shaders are described below.</p> 6200</div> 6201<div class="openblock bnf"> 6202<div class="content"> 6203<div class="dlist"> 6204<dl> 6205<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 6206<dd> 6207<p><em>primitive_mode</em><br> 6208<em>vertex_spacing</em><br> 6209<em>ordering</em><br> 6210<em>point_mode</em></p> 6211</dd> 6212</dl> 6213</div> 6214</div> 6215</div> 6216<div class="paragraph"> 6217<p>The <strong>primitive-mode</strong> is used to specify a tessellation primitive mode to be 6218used by the tessellation primitive generator.</p> 6219</div> 6220<div class="openblock bnf"> 6221<div class="content"> 6222<div class="dlist"> 6223<dl> 6224<dt class="hdlist1"><em>primitive-mode</em>: </dt> 6225<dd> 6226<p><strong>triangles</strong><br> 6227<strong>quads</strong><br> 6228<strong>isolines</strong></p> 6229</dd> 6230</dl> 6231</div> 6232</div> 6233</div> 6234<div class="paragraph"> 6235<p>If present, the <em>primitive-mode</em> specifies that the tessellation primitive 6236generator should subdivide a triangle into smaller triangles, a quad into 6237triangles, or a quad into a collection of lines, respectively.</p> 6238</div> 6239<div class="paragraph"> 6240<p>A second group of layout identifiers, <em>vertex spacing</em>, is used to specify 6241the spacing used by the tessellation primitive generator when subdividing an 6242edge.</p> 6243</div> 6244<div class="openblock bnf"> 6245<div class="content"> 6246<div class="dlist"> 6247<dl> 6248<dt class="hdlist1"><em>vertex-spacing</em>: </dt> 6249<dd> 6250<p><strong>equal_spacing</strong><br> 6251<strong>fractional_even_spacing</strong><br> 6252<strong>fractional_odd_spacing</strong></p> 6253</dd> 6254</dl> 6255</div> 6256</div> 6257</div> 6258<div class="paragraph"> 6259<p><strong>equal_spacing</strong> specifies that edges should be divided into a collection of 6260equal-sized segments;</p> 6261</div> 6262<div class="paragraph"> 6263<p><strong>fractional_even_spacing</strong> specifies that edges should be divided into an 6264even number of equal-length segments plus two additional shorter 6265“fractional” segments; or</p> 6266</div> 6267<div class="paragraph"> 6268<p><strong>fractional_odd_spacing</strong> specifies that edges should be divided into an odd 6269number of equal-length segments plus two additional shorter “fractional” 6270segments.</p> 6271</div> 6272<div class="paragraph"> 6273<p>A third group of layout identifiers, <em>ordering</em>, specifies whether the 6274tessellation primitive generator produces triangles in clockwise or 6275counter-clockwise order, according to the coordinate system depicted in the 6276<a href="#references">OpenGL ES Specification</a>.</p> 6277</div> 6278<div class="openblock bnf"> 6279<div class="content"> 6280<div class="dlist"> 6281<dl> 6282<dt class="hdlist1"><em>ordering</em>: </dt> 6283<dd> 6284<p><strong>cw</strong><br> 6285<strong>ccw</strong></p> 6286</dd> 6287</dl> 6288</div> 6289</div> 6290</div> 6291<div class="paragraph"> 6292<p>The identifiers <strong>cw</strong> and <strong>ccw</strong> indicate clockwise and counter-clockwise 6293triangles, respectively. 6294If the tessellation primitive generator does not produce triangles, the 6295order is ignored.</p> 6296</div> 6297<div class="paragraph"> 6298<p>Finally, <em>point mode</em> indicates that the tessellation primitive generator 6299should produce one point for each distinct vertex in the subdivided 6300primitive, rather than generating lines or triangles.</p> 6301</div> 6302<div class="openblock bnf"> 6303<div class="content"> 6304<div class="dlist"> 6305<dl> 6306<dt class="hdlist1"><em>point-mode</em>: </dt> 6307<dd> 6308<p><strong>point_mode</strong></p> 6309</dd> 6310</dl> 6311</div> 6312</div> 6313</div> 6314<div class="paragraph"> 6315<p>Any or all of these identifiers may be specified one or more times in a 6316single input layout declaration.</p> 6317</div> 6318<div class="paragraph"> 6319<p>The tessellation evaluation shader object in a program must declare a 6320primitive mode in its input layout. 6321Declaring vertex spacing, ordering, or point mode identifiers is optional. 6322If spacing or vertex ordering declarations are omitted, the tessellation 6323primitive generator will use equal spacing or counter-clockwise vertex 6324ordering, respectively. 6325If a point mode declaration is omitted, the tessellation primitive generator 6326will produce lines or triangles according to the primitive mode.</p> 6327</div> 6328</div> 6329<div class="sect4"> 6330<h5 id="geometry-shader-inputs">Geometry Shader Inputs</h5> 6331<div class="paragraph"> 6332<p>Additional layout qualifier identifiers for geometry shader inputs include 6333<em>primitive</em> identifiers and an <em>invocation count</em> identifier:</p> 6334</div> 6335<div class="openblock bnf"> 6336<div class="content"> 6337<div class="dlist"> 6338<dl> 6339<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 6340<dd> 6341<p><strong>points</strong><br> 6342<strong>lines</strong><br> 6343<strong>lines_adjacency</strong><br> 6344<strong>triangles</strong><br> 6345<strong>triangles_adjacency</strong><br> 6346<strong>invocations</strong> <strong>=</strong> <em>layout-qualifier-value</em></p> 6347</dd> 6348</dl> 6349</div> 6350</div> 6351</div> 6352<div class="paragraph"> 6353<p>The identifiers <strong>points</strong>, <strong>lines</strong>, <strong>lines_adjacency</strong>, <strong>triangles</strong>, and 6354<strong>triangles_adjacency</strong> are used to specify the type of input primitive 6355accepted by the geometry shader, and only one of these is accepted. 6356The geometry shader must declare this input primitive layout.</p> 6357</div> 6358<div class="paragraph"> 6359<p>The identifier <strong>invocations</strong> is used to specify the number of times the 6360geometry shader executable is invoked for each input primitive received. 6361Invocation count declarations are optional. 6362If no invocation count is declared in the geometry shader, it will be run 6363once for each input primitive. 6364If an invocation count is declared, all such declarations must specify the 6365same count. 6366If a shader specifies an invocation count greater than the 6367implementation-dependent maximum, or less than or equal to zero, 6368a compile-time error results.</p> 6369</div> 6370<div class="paragraph"> 6371<p>For example,</p> 6372</div> 6373<div class="listingblock"> 6374<div class="content"> 6375<pre class="CodeRay highlight"><code data-lang="c++">layout(triangles, invocations = <span class="integer">6</span>) in;</code></pre> 6376</div> 6377</div> 6378<div class="paragraph"> 6379<p>will establish that all inputs to the geometry shader are triangles and that 6380the geometry shader executable is run six times for each triangle processed.</p> 6381</div> 6382<div class="paragraph"> 6383<p>All geometry shader input unsized array declarations will be sized by an 6384earlier input primitive layout qualifier, when present, as per the following 6385table.</p> 6386</div> 6387<table class="tableblock frame-all grid-all stretch"> 6388<colgroup> 6389<col style="width: 50%;"> 6390<col style="width: 50%;"> 6391</colgroup> 6392<thead> 6393<tr> 6394<th class="tableblock halign-left valign-top">Layout</th> 6395<th class="tableblock halign-left valign-top">Size of Input Arrays</th> 6396</tr> 6397</thead> 6398<tbody> 6399<tr> 6400<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>points</strong></p></td> 6401<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> 6402</tr> 6403<tr> 6404<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lines</strong></p></td> 6405<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> 6406</tr> 6407<tr> 6408<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lines_adjacency</strong></p></td> 6409<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> 6410</tr> 6411<tr> 6412<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>triangles</strong></p></td> 6413<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> 6414</tr> 6415<tr> 6416<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>triangles_adjacency</strong></p></td> 6417<td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> 6418</tr> 6419</tbody> 6420</table> 6421<div class="paragraph"> 6422<p>The intrinsically declared input array <em>gl_in[]</em> will also be sized by any 6423input primitive-layout declaration. 6424Hence, the expression</p> 6425</div> 6426<div class="listingblock"> 6427<div class="content"> 6428<pre class="CodeRay highlight"><code data-lang="c++">gl_in.length()</code></pre> 6429</div> 6430</div> 6431<div class="paragraph"> 6432<p>will return the value from the table above.</p> 6433</div> 6434<div class="paragraph"> 6435<p>An input can be declared without an array size if there is a previous layout 6436which specifies the size. 6437For built-in inputs (e.g. <em>gl_in[]</em>), a layout must be declared before any 6438use.</p> 6439</div> 6440<div class="paragraph"> 6441<p>It is a compile-time error if a layout declaration’s array size (from the 6442table above) does not match all the explicit array sizes specified in 6443declarations of an input variables in the same shader. 6444The following includes examples of compile-time errors:</p> 6445</div> 6446<div class="listingblock"> 6447<div class="content"> 6448<pre class="CodeRay highlight"><code data-lang="c++"><span class="comment">// code sequence within one shader...</span> 6449in vec4 Color2[<span class="integer">2</span>]; <span class="comment">// legal, size is 2</span> 6450in vec4 Color3[<span class="integer">3</span>]; <span class="comment">// illegal, input sizes are inconsistent</span> 6451layout(lines) in; <span class="comment">// legal for Color2, input size is 2, matching Color2</span> 6452in vec4 Color4[<span class="integer">3</span>]; <span class="comment">// illegal, contradicts layout of lines</span> 6453layout(lines) in; <span class="comment">// legal, matches other layout() declaration</span> 6454layout(triangles) in; <span class="comment">// illegal, does not match earlier layout() declaration</span></code></pre> 6455</div> 6456</div> 6457<div class="paragraph"> 6458<p>It is a link-time error if not all provided sizes (sized input arrays and 6459layout size) match in the geometry shader of a program.</p> 6460</div> 6461</div> 6462<div class="sect4"> 6463<h5 id="fragment-shader-inputs">Fragment Shader Inputs</h5> 6464<div class="paragraph"> 6465<p>Fragment shaders allow the following layout qualifier on <strong>in</strong> only (not with 6466variable declarations):</p> 6467</div> 6468<div class="openblock bnf"> 6469<div class="content"> 6470<div class="dlist"> 6471<dl> 6472<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 6473<dd> 6474<p><strong>early_fragment_tests</strong></p> 6475</dd> 6476</dl> 6477</div> 6478</div> 6479</div> 6480<div class="paragraph"> 6481<p>to request that fragment tests be performed before fragment shader 6482execution, as described in section 13.8.4 “Early Fragment Tests” of the 6483<a href="#references">OpenGL ES Specification</a>.</p> 6484</div> 6485<div class="paragraph"> 6486<p>For example,</p> 6487</div> 6488<div class="listingblock"> 6489<div class="content"> 6490<pre class="CodeRay highlight"><code data-lang="c++">layout(early_fragment_tests) in;</code></pre> 6491</div> 6492</div> 6493<div class="paragraph"> 6494<p>Specifying this will make per-fragment tests be performed before fragment 6495shader execution. 6496In addition it is an error to statically write to <em>gl_FragDepth</em> in the 6497fragment shader. 6498If this is not declared, per-fragment tests will be performed after fragment 6499shader execution.</p> 6500</div> 6501</div> 6502<div class="sect4"> 6503<h5 id="compute-shader-inputs">Compute Shader Inputs</h5> 6504<div class="paragraph"> 6505<p>There are no layout location qualifiers for compute shader inputs.</p> 6506</div> 6507<div class="paragraph"> 6508<p>Layout qualifier identifiers for compute shader inputs are the workgroup 6509size qualifiers:</p> 6510</div> 6511<div class="openblock bnf"> 6512<div class="content"> 6513<div class="dlist"> 6514<dl> 6515<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 6516<dd> 6517<p><strong>local_size_x</strong> <strong>=</strong> <em>layout-qualifier-value</em><br> 6518<strong>local_size_y</strong> <strong>=</strong> <em>layout-qualifier-value</em><br> 6519<strong>local_size_z</strong> <strong>=</strong> <em>layout-qualifier-value</em></p> 6520</dd> 6521</dl> 6522</div> 6523</div> 6524</div> 6525<div class="paragraph"> 6526<p>The <strong>local_size_x</strong>, <strong>local_size_y</strong>, and <strong>local_size_z</strong> qualifiers are used 6527to declare a fixed workgroup size by the compute shader in the first, 6528second, and third dimension, respectively. 6529If a shader does not specify a size for one of the dimensions, that 6530dimension will have a size of 1.</p> 6531</div> 6532<div class="paragraph"> 6533<p>For example, the following declaration in a compute shader</p> 6534</div> 6535<div class="listingblock"> 6536<div class="content"> 6537<pre class="CodeRay highlight"><code data-lang="c++">layout(local_size_x = <span class="integer">32</span>, local_size_y = <span class="integer">32</span>) in;</code></pre> 6538</div> 6539</div> 6540<div class="paragraph"> 6541<p>is used to declare a two-dimensional compute shader with a workgroup size of 32 6542X 32 elements, which is equivalent to a three-dimensional compute shader 6543where the third dimension has size one.</p> 6544</div> 6545<div class="paragraph"> 6546<p>As another example, the declaration</p> 6547</div> 6548<div class="listingblock"> 6549<div class="content"> 6550<pre class="CodeRay highlight"><code data-lang="c++">layout(local_size_x = <span class="integer">8</span>) in;</code></pre> 6551</div> 6552</div> 6553<div class="paragraph"> 6554<p>effectively specifies that a one-dimensional compute shader is being 6555compiled, and its size is 8 elements.</p> 6556</div> 6557<div class="paragraph"> 6558<p>If the fixed workgroup size of the shader in any dimension is less than 6559or equal to zero or greater than the maximum size supported by the 6560implementation for that dimension, a compile-time error results. 6561Also, if such a layout qualifier is declared more than once in the same 6562shader, all those declarations must set the same set of workgroup 6563sizes and set them to the same values; otherwise a compile-time error 6564results.</p> 6565</div> 6566<div class="paragraph"> 6567<p>Furthermore, if a program object contains a compute shader, that shader must 6568contain an input layout qualifier specifying a fixed workgroup size for 6569the program, or a link-time error will occur.</p> 6570</div> 6571</div> 6572</div> 6573<div class="sect3"> 6574<h4 id="output-layout-qualifiers">4.4.2. Output Layout Qualifiers</h4> 6575<div class="paragraph"> 6576<p>Some output layout qualifiers apply to all shader stages and some apply only 6577to specific stages. 6578The latter are discussed in separate sections below.</p> 6579</div> 6580<div class="paragraph"> 6581<p>As with input layout qualifiers, all shaders except compute shaders allow 6582<strong>location</strong> layout qualifiers on output variable declarations, output block 6583declarations, and output block member declarations.</p> 6584</div> 6585<div class="openblock bnf"> 6586<div class="content"> 6587<div class="dlist"> 6588<dl> 6589<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 6590<dd> 6591<p><strong>location</strong> <strong>=</strong> <em>layout-qualifier-value</em></p> 6592</dd> 6593</dl> 6594</div> 6595</div> 6596</div> 6597<div class="paragraph"> 6598<p>The usage and rules for applying the <strong>location</strong> qualifier 6599to blocks and structures are exactly as described in 6600“<a href="#input-layout-qualifiers">Input Layout Qualifiers</a>”.</p> 6601</div> 6602<div class="paragraph"> 6603<p>The qualifier may appear at most once within a declaration. 6604For example, in a fragment shader,</p> 6605</div> 6606<div class="listingblock"> 6607<div class="content"> 6608<pre class="CodeRay highlight"><code data-lang="c++">layout(location = <span class="integer">3</span>) out vec4 color;</code></pre> 6609</div> 6610</div> 6611<div class="paragraph"> 6612<p>will establish that the fragment shader output <em>color</em> is assigned to</p> 6613</div> 6614<div class="paragraph"> 6615<p>fragment color 3.</p> 6616</div> 6617<div class="paragraph"> 6618<p>For fragment shader outputs, the location 6619specifies 6620the color output number 6621receiving the values of the output. 6622For outputs of all other shader stages, the location specifies a vector 6623number that can be used to match against inputs in a subsequent shader 6624stage, even if that shader is in a different program object.</p> 6625</div> 6626<div class="paragraph"> 6627<p>Declared outputs of scalar or vector type consume a single location.</p> 6628</div> 6629<div class="paragraph"> 6630<p>If the declared output is an array, it will be assigned consecutive 6631locations starting with the location specified. 6632For example,</p> 6633</div> 6634<div class="listingblock"> 6635<div class="content"> 6636<pre class="CodeRay highlight"><code data-lang="c++">layout(location = <span class="integer">2</span>) out vec4 colors[<span class="integer">3</span>];</code></pre> 6637</div> 6638</div> 6639<div class="paragraph"> 6640<p>will establish that <em>colors</em> is assigned to vector location numbers 2, 3, 6641and 4.</p> 6642</div> 6643<div class="paragraph"> 6644<p>If the declared output is an <em>n</em> × <em>m</em> 6645matrix, it will be assigned multiple locations starting with the location 6646specified. 6647The number of locations assigned will be the same as for an <em>n</em>-element 6648array of <em>m</em>-component vectors.</p> 6649</div> 6650<div class="paragraph"> 6651<p>If the declared output is a structure, its members will be assigned 6652consecutive locations in the order of declaration, with the first member 6653assigned the location specified for the structure. 6654The number of locations consumed by a structure member is determined by 6655applying the rules above recursively as though the structure member were 6656declared as an output variable of the same type.</p> 6657</div> 6658<div class="paragraph"> 6659<p><strong>location</strong> layout qualifiers may be used on output variables declared as 6660structures. 6661However, it is a compile-time error to use a <strong>location</strong> qualifier on a 6662structure member. 6663Location layout qualifiers may be used on output blocks and output block 6664members.</p> 6665</div> 6666<div class="paragraph"> 6667<p>If an output is declared as an array of blocks, excluding per-vertex-arrays 6668as required for tessellation, it is an error to declare a member of the 6669block with a <strong>location</strong> qualifier.</p> 6670</div> 6671<div class="paragraph"> 6672<p>The number of output locations available to a shader is limited. 6673For fragment shaders, the limit is the advertised number of draw buffers.</p> 6674</div> 6675<div class="paragraph"> 6676<p>For all other shaders, the limit is implementation-dependent and must be no 6677less than one fourth of the advertised maximum output component count 6678(compute shaders have no outputs). 6679A program will fail to link if any attached shader uses a location greater 6680than or equal to the number of supported locations, unless device-dependent 6681optimizations are able to make the program fit within available hardware 6682resources.</p> 6683</div> 6684<div class="paragraph"> 6685<p>Compile-time errors may also be given if at compile time it is known the 6686link will fail. 6687A negative output location will result in an error.</p> 6688</div> 6689<div class="paragraph"> 6690<p>It is a compile-time or link-time error if any of the following occur:</p> 6691</div> 6692<div class="ulist"> 6693<ul> 6694<li> 6695<p>any two fragment shader output variables are assigned to the same 6696location.</p> 6697</li> 6698<li> 6699<p>if any two output variables from the same vertex, tessellation or 6700geometry shader stage are assigned to the same location.</p> 6701</li> 6702</ul> 6703</div> 6704<div class="paragraph"> 6705<p>For all shader types, a program will fail to link if explicit location 6706assignments leave the linker unable to find space for other variables 6707without explicit assignments.</p> 6708</div> 6709<div class="paragraph"> 6710<p>If an output variable has no location assigned in the shader text, it will 6711be assigned a location by the linker. 6712See section 11.1.3 “Shader Execution” of the <a href="#references">OpenGL ES Specification</a> for 6713more details.</p> 6714</div> 6715<div class="paragraph"> 6716<p>If there is only a single output, the location does not need to be 6717specified, in which case it defaults to zero. 6718This applies for all output types, including arrays. 6719If there is more than one fragment output, the location must be specified 6720for all outputs.</p> 6721</div> 6722<div class="paragraph"> 6723<p>For the purposes of determining if a non-fragment output matches an input 6724from a subsequent shader stage, the <strong>location</strong> layout qualifier (if any) 6725must match.</p> 6726</div> 6727<div class="sect4"> 6728<h5 id="tessellation-control-outputs">Tessellation Control Outputs</h5> 6729<div class="paragraph"> 6730<p>Tessellation control shaders allow output layout qualifiers only on the 6731interface 6732qualifier <strong>out</strong>, not on an output block, block member, or variable 6733declaration. 6734The output layout qualifier identifiers allowed for tessellation control 6735shaders are:</p> 6736</div> 6737<div class="openblock bnf"> 6738<div class="content"> 6739<div class="dlist"> 6740<dl> 6741<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 6742<dd> 6743<p><strong>vertices</strong> <strong>=</strong> <em>layout-qualifier-value</em></p> 6744</dd> 6745</dl> 6746</div> 6747</div> 6748</div> 6749<div class="paragraph"> 6750<p>The identifier <strong>vertices</strong> specifies the number of vertices in the output 6751patch produced by the tessellation control shader, which also specifies the 6752number of times the tessellation control shader is invoked. 6753It is a compile- or link-time error for the output vertex count to be less 6754than or equal to zero, or greater than the implementation-dependent maximum 6755patch size.</p> 6756</div> 6757<div class="paragraph"> 6758<p>The intrinsically declared tessellation control output array <em>gl_out[]</em> will 6759also be sized by any output layout declaration. 6760Hence, the expression</p> 6761</div> 6762<div class="listingblock"> 6763<div class="content"> 6764<pre class="CodeRay highlight"><code data-lang="c++">gl_out.length()</code></pre> 6765</div> 6766</div> 6767<div class="paragraph"> 6768<p>will return the output patch vertex count specified in a previous output 6769layout qualifier. 6770For outputs declared without an array size, including intrinsically declared 6771outputs (i.e., <em>gl_out</em>), a layout must be declared before any use of the 6772method <strong>length</strong>() or other array use that requires its size to be known.</p> 6773</div> 6774<div class="paragraph"> 6775<p>It is a compile-time error if the output patch vertex count specified in an 6776output layout qualifier does not match the array size specified in any 6777output variable declaration in the same shader.</p> 6778</div> 6779<div class="paragraph"> 6780<p>All tessellation control shader layout declarations in a program must 6781specify the same output patch vertex count. 6782There must be at least one layout qualifier specifying an output patch 6783vertex count in any program containing a tessellation control shader.</p> 6784</div> 6785</div> 6786<div class="sect4"> 6787<h5 id="geometry-outputs">Geometry Outputs</h5> 6788<div class="paragraph"> 6789<p>Geometry shaders can have two additional types of output layout identifiers: 6790an output primitive type and a maximum output vertex count. 6791The primitive type and vertex count identifiers are allowed only on the 6792interface qualifier <strong>out</strong>, not on an output block, block member, or variable 6793declaration.</p> 6794</div> 6795<div class="paragraph"> 6796<p>The layout qualifier identifiers for geometry shader outputs are</p> 6797</div> 6798<div class="openblock bnf"> 6799<div class="content"> 6800<div class="dlist"> 6801<dl> 6802<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 6803<dd> 6804<p><strong>points</strong><br> 6805<strong>line_strip</strong><br> 6806<strong>triangle_strip</strong><br> 6807<strong>max_vertices</strong> <strong>=</strong> <em>layout-qualifier-value</em></p> 6808</dd> 6809</dl> 6810</div> 6811</div> 6812</div> 6813<div class="paragraph"> 6814<p>The primitive type identifiers <strong>points</strong>, <strong>line_strip</strong>, and <strong>triangle_strip</strong> 6815are used to specify the type of output primitive produced by the geometry 6816shader, and only one of these is accepted. 6817The geometry shader object in a program must declare an output primitive 6818type, and all geometry shader output primitive type declarations in a 6819program must declare the same primitive type.</p> 6820</div> 6821<div class="paragraph"> 6822<p>The vertex count identifier <strong>max_vertices</strong> is used to specify the maximum 6823number of vertices the shader will ever emit in a single invocation. 6824The geometry shader object in a program must declare a maximum output vertex 6825count, and all geometry shader output vertex count declarations in a program 6826must declare the same count.</p> 6827</div> 6828<div class="paragraph"> 6829<p>In this example,</p> 6830</div> 6831<div class="listingblock"> 6832<div class="content"> 6833<pre class="CodeRay highlight"><code data-lang="c++">layout(triangle_strip, max_vertices = <span class="integer">60</span>) out; <span class="comment">// order does not matter</span> 6834layout(max_vertices = <span class="integer">60</span>) out; <span class="comment">// redeclaration okay</span> 6835layout(triangle_strip) out; <span class="comment">// redeclaration okay</span> 6836layout(points) out; <span class="comment">// error, contradicts triangle_strip</span> 6837layout(max_vertices = <span class="integer">30</span>) out; <span class="comment">// error, contradicts 60</span></code></pre> 6838</div> 6839</div> 6840<div class="paragraph"> 6841<p>all outputs from the geometry shader are triangles and at most 60 vertices 6842will be emitted by the shader. 6843It is an error for the maximum number of vertices to be greater than 6844<em>gl_MaxGeometryOutputVertices</em>.</p> 6845</div> 6846<div class="paragraph"> 6847<p>All geometry shader output layout declarations in a program must declare the 6848same layout and same value for <strong>max_vertices</strong>. 6849If geometry shaders are in a program, there must be at least one geometry 6850output layout declaration somewhere in that 6851program.</p> 6852</div> 6853</div> 6854<div class="sect4"> 6855<h5 id="fragment-outputs">Fragment Outputs</h5> 6856<div class="paragraph"> 6857<p>Fragment shaders can have an output layout for redeclaring the built-in 6858variable <em>gl_FragDepth</em>:</p> 6859</div> 6860<div class="listingblock"> 6861<div class="content"> 6862<pre class="CodeRay highlight"><code data-lang="c++"><span class="comment">// redeclaration that changes nothing is allowed +</span> 6863out <span class="predefined-type">float</span> gl_FragDepth;</code></pre> 6864</div> 6865</div> 6866<div class="paragraph"> 6867<p>The built-in <em>gl_FragDepth</em> is only predeclared in fragment shaders, so 6868redeclaring it in any other shader language results in an error.</p> 6869</div> 6870<div class="paragraph"> 6871<p>Fragment shaders additionally support layout qualifiers specifying a set of 6872advanced blend equations supported when the fragment shader is used. 6873These layout qualifiers are only permitted on the interface qualifier <strong>out</strong>, 6874and use the identifiers specified in the “Layout Qualifier” column of the 6875table below.</p> 6876</div> 6877<div class="paragraph"> 6878<p>If a layout qualifier in the table below is specified in the fragment 6879shader, the fragment shader may be used with the corresponding advanced 6880blend equation in the “Blend Equation(s) Supported” column. 6881Additionally, the special qualifier <strong>blend_support_all_equations</strong> indicates 6882that the shader may be used with any advanced blending equation supported by 6883the <a href="#references">OpenGL ES Specification</a>. 6884It is not an error to specify more than one of these identifiers in any 6885fragment shader. 6886Specifying more than one qualifier or <strong>blend_support_all_equations</strong> means 6887that the fragment shader may be used with multiple advanced blend equations. 6888Additionally, it is not an error to specify any single one of these layout 6889qualifiers more than once.</p> 6890</div> 6891<table class="tableblock frame-all grid-all stretch"> 6892<colgroup> 6893<col style="width: 50%;"> 6894<col style="width: 50%;"> 6895</colgroup> 6896<tbody> 6897<tr> 6898<td class="tableblock halign-left valign-top"><p class="tableblock">Layout Qualifier</p></td> 6899<td class="tableblock halign-left valign-top"><p class="tableblock">Blend Equations(s) Supported</p></td> 6900</tr> 6901<tr> 6902<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_multiply</strong></p></td> 6903<td class="tableblock halign-left valign-top"><p class="tableblock">MULTIPLY</p></td> 6904</tr> 6905<tr> 6906<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_screen</strong></p></td> 6907<td class="tableblock halign-left valign-top"><p class="tableblock">SCREEN</p></td> 6908</tr> 6909<tr> 6910<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_overlay</strong></p></td> 6911<td class="tableblock halign-left valign-top"><p class="tableblock">OVERLAY</p></td> 6912</tr> 6913<tr> 6914<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_darken</strong></p></td> 6915<td class="tableblock halign-left valign-top"><p class="tableblock">DARKEN</p></td> 6916</tr> 6917<tr> 6918<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_lighten</strong></p></td> 6919<td class="tableblock halign-left valign-top"><p class="tableblock">LIGHTEN</p></td> 6920</tr> 6921<tr> 6922<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_colordodge</strong></p></td> 6923<td class="tableblock halign-left valign-top"><p class="tableblock">COLORDODGE</p></td> 6924</tr> 6925<tr> 6926<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_colorburn</strong></p></td> 6927<td class="tableblock halign-left valign-top"><p class="tableblock">COLORBURN</p></td> 6928</tr> 6929<tr> 6930<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_hardlight</strong></p></td> 6931<td class="tableblock halign-left valign-top"><p class="tableblock">HARDLIGHT</p></td> 6932</tr> 6933<tr> 6934<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_softlight</strong></p></td> 6935<td class="tableblock halign-left valign-top"><p class="tableblock">SOFTLIGHT</p></td> 6936</tr> 6937<tr> 6938<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_difference</strong></p></td> 6939<td class="tableblock halign-left valign-top"><p class="tableblock">DIFFERENCE</p></td> 6940</tr> 6941<tr> 6942<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_exclusion</strong></p></td> 6943<td class="tableblock halign-left valign-top"><p class="tableblock">EXCLUSION</p></td> 6944</tr> 6945<tr> 6946<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_hsl_hue</strong></p></td> 6947<td class="tableblock halign-left valign-top"><p class="tableblock">HSL_HUE</p></td> 6948</tr> 6949<tr> 6950<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_hsl_saturation</strong></p></td> 6951<td class="tableblock halign-left valign-top"><p class="tableblock">HSL_SATURATION</p></td> 6952</tr> 6953<tr> 6954<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_hsl_color</strong></p></td> 6955<td class="tableblock halign-left valign-top"><p class="tableblock">HSL_COLOR</p></td> 6956</tr> 6957<tr> 6958<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_hsl_luminosity</strong></p></td> 6959<td class="tableblock halign-left valign-top"><p class="tableblock">HSL_LUMINOSITY</p></td> 6960</tr> 6961<tr> 6962<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>blend_support_all_equations</strong></p></td> 6963<td class="tableblock halign-left valign-top"><p class="tableblock">all blend equations</p></td> 6964</tr> 6965</tbody> 6966</table> 6967</div> 6968</div> 6969<div class="sect3"> 6970<h4 id="uniform-variable-layout-qualifiers">4.4.3. Uniform Variable Layout Qualifiers</h4> 6971<div class="paragraph"> 6972<p>The following layout qualifier can be used for all default-block uniform 6973variables but not for variables in uniform or shader storage blocks. 6974The layout qualifier identifier for uniform variables is:</p> 6975</div> 6976<div class="openblock bnf"> 6977<div class="content"> 6978<div class="dlist"> 6979<dl> 6980<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 6981<dd> 6982<p><strong>location</strong> <strong>=</strong> <em>layout-qualifier-value</em></p> 6983</dd> 6984</dl> 6985</div> 6986</div> 6987</div> 6988<div class="paragraph"> 6989<p>The location specifies the location by which the API can reference 6990the uniform and update its value. 6991Individual elements of a uniform array are assigned consecutive locations 6992with the first element taking location <strong>location</strong>. 6993Default-block uniform variable declarations sharing the same location 6994linked in the program have to match by name, type, qualifiers and arrayness. 6995For arrays their array dimensionality and array sizes must match. 6996For structs this rule applies recursively to all members. 6997Valid locations for default-block uniform variable locations are in the 6998range of 0 to the implementation-defined maximum number of uniform locations 6999minus one.</p> 7000</div> 7001<div class="paragraph"> 7002<p>Locations can be assigned to default-block uniform arrays and structures. 7003The first inner-most scalar, vector or matrix member or element takes the 7004specified <strong>location</strong> and the compiler assigns the next inner-most member or 7005element the next incremental location value. 7006Each subsequent inner-most member or element gets incremental locations for 7007the entire structure or array. 7008This rule applies to nested structures and arrays and gives each inner-most 7009scalar, vector, or matrix member a unique location. 7010When the linker generates locations for uniforms without an explicit 7011location, it assumes for all uniforms with an explicit location all their 7012array elements and structure members are used and the linker will not 7013generate a conflicting location, even if that element or member is deemed 7014unused.</p> 7015</div> 7016<div class="paragraph"> 7017<p>When targeting Vulkan, the <strong>push_constant</strong> qualifier is used to 7018declare an entire block, and represents a set of <em>push constants</em>, as defined 7019by the Vulkan API. 7020It is an error to apply this to anything other than a uniform block 7021declaration, or when not targeting Vulkan. 7022The values in the block will be initialized as per the Vulkan API specification. 7023A block declared with <code>layout(push_constant)</code> may optionally include an 7024<em>instance-name</em>. 7025There can be only one <strong>push_constant</strong> block per stage, or a compile-time or 7026link-time error will result. 7027A push-constant array can only be indexed with dynamically uniform indices. 7028Uniform blocks declared with <strong>push_constant</strong> use different resources 7029than those without; and are accounted for separately.</p> 7030</div> 7031</div> 7032<div class="sect3"> 7033<h4 id="uniform-and-shader-storage-block-layout-qualifiers">4.4.4. Uniform and Shader Storage Block Layout Qualifiers</h4> 7034<div class="paragraph"> 7035<p>Layout qualifiers can be used for uniform and shader storage blocks, but not 7036for non-block uniform declarations. 7037The layout qualifier identifiers (and <strong>shared</strong> keyword) for uniform and 7038shader storage blocks are:</p> 7039</div> 7040<div class="openblock bnf"> 7041<div class="content"> 7042<div class="dlist"> 7043<dl> 7044<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 7045<dd> 7046<p><strong>shared</strong><br> 7047<strong>packed</strong><br> 7048<strong>std140</strong><br> 7049<strong>std430</strong><br> 7050<strong>row_major</strong><br> 7051<strong>column_major</strong><br> 7052<strong>binding</strong> <strong>=</strong> <em>layout-qualifier-value</em><br> 7053<strong>offset</strong> <strong>=</strong> <em>layout-qualifier-value</em> // Vulkan only<br> 7054<strong>align</strong> <strong>=</strong> <em>layout-qualifier-value</em> // Vulkan only</p> 7055</dd> 7056</dl> 7057</div> 7058</div> 7059</div> 7060<div class="paragraph"> 7061<p>None of these have any semantic effect at all on the usage of the variables 7062being declared; they only describe how data is laid out in memory. 7063For example, matrix semantics are always column-based, as described in the 7064rest of this specification, no matter what layout qualifiers are being used.</p> 7065</div> 7066<div class="paragraph"> 7067<p>Uniform and shader storage block layout qualifiers can be declared for 7068global scope, on a single uniform or shader storage block, or on a single 7069block member declaration.</p> 7070</div> 7071<div class="paragraph"> 7072<p>Default layouts are established at global scope for uniform blocks as:</p> 7073</div> 7074<div class="listingblock"> 7075<div class="content"> 7076<pre class="CodeRay highlight"><code data-lang="c++">layout(layout-qualifier-id-list) uniform;</code></pre> 7077</div> 7078</div> 7079<div class="paragraph"> 7080<p>and for shader storage blocks as:</p> 7081</div> 7082<div class="listingblock"> 7083<div class="content"> 7084<pre class="CodeRay highlight"><code data-lang="c++">layout(layout-qualifier-id-list) buffer;</code></pre> 7085</div> 7086</div> 7087<div class="paragraph"> 7088<p>When this is done, the previous default qualification is first inherited and 7089then overridden as per the override rules listed below for each qualifier 7090listed in the declaration. 7091The result becomes the new default qualification scoped to subsequent 7092uniform or shader storage block definitions.</p> 7093</div> 7094<div class="paragraph"> 7095<p>The initial state of compilation when generating SPIR-V is as if the 7096following were declared:</p> 7097</div> 7098<div class="listingblock"> 7099<div class="content"> 7100<pre class="CodeRay highlight"><code data-lang="c++">layout(std140, column_major) uniform; 7101layout(std430, column_major) buffer;</code></pre> 7102</div> 7103</div> 7104<div class="paragraph"> 7105<p>However, when <strong>push_constant</strong> is declared, the default layout of the 7106buffer will be <strong>std430</strong>. There is no method to globally set this default.</p> 7107</div> 7108<div class="paragraph"> 7109<p>The initial state of compilation when not generating SPIR-V is as if the 7110following were declared:</p> 7111</div> 7112<div class="listingblock"> 7113<div class="content"> 7114<pre class="CodeRay highlight"><code data-lang="c++">layout(shared, column_major) uniform; 7115layout(shared, column_major) buffer;</code></pre> 7116</div> 7117</div> 7118<div class="paragraph"> 7119<p>Uniform and shader storage blocks can be declared with optional layout 7120qualifiers, and so can their individual member declarations. 7121Such block layout qualification is scoped only to the content of the block. 7122As with global layout declarations, block layout qualification first 7123inherits from the current default qualification and then overrides it. 7124Similarly, individual member layout qualification is scoped just to the 7125member declaration, and inherits from and overrides the block’s 7126qualification.</p> 7127</div> 7128<div class="paragraph"> 7129<p>The <strong>shared</strong> qualifier overrides only the <strong>std140</strong>, <strong>std430</strong>, and <strong>packed</strong> 7130qualifiers; other qualifiers are inherited. 7131The compiler/linker will ensure that multiple programs and programmable 7132stages containing this definition will share the same memory layout for this 7133block, as long as they also matched in their <strong>row_major</strong> and/or 7134<strong>column_major</strong> qualifications. 7135This allows use of the same buffer to back the same block definition across 7136different programs. 7137It is a compile-time error to use the <strong>shared</strong> qualifier when generating 7138SPIR-V.</p> 7139</div> 7140<div class="paragraph"> 7141<p>The <strong>packed</strong> qualifier overrides only <strong>std140</strong>, <strong>std430</strong>, and <strong>shared</strong>; 7142other qualifiers are inherited. 7143When <strong>packed</strong> is used, no shareable layout is guaranteed. 7144The compiler and linker can optimize memory use based on what variables 7145actively get used and on other criteria. 7146Offsets must be queried, as there is no other way of guaranteeing where (and 7147which) variables reside within the block.</p> 7148</div> 7149<div class="paragraph"> 7150<p>It is a link-time error to access the same packed uniform or shader storage 7151block in multiple stages within a program. 7152Attempts to access the same packed uniform or shader storage block across 7153programs can result in conflicting member offsets and in undefined values 7154being read. 7155However, implementations may aid application management of packed blocks by 7156using canonical layouts for packed blocks. 7157It is a compile-time error to use the <strong>packed</strong> qualifier when generating 7158SPIR-V.</p> 7159</div> 7160<div class="paragraph"> 7161<p>The <strong>std140</strong> and <strong>std430</strong> qualifiers override only the <strong>packed</strong>, <strong>shared</strong>, 7162<strong>std140</strong>, and <strong>std430</strong> qualifiers; other qualifiers are inherited. 7163The <strong>std430</strong> qualifier is supported only for shader storage blocks; a shader 7164using the <strong>std430</strong> qualifier on a uniform block will result in 7165an error, unless it is also declared with <strong>push_constant</strong>.</p> 7166</div> 7167<div class="paragraph"> 7168<p>The layout is explicitly determined by this, as described in section 7.6.2.2 7169“Standard Uniform Block Layout” of the <a href="#references">OpenGL ES Specification</a>. 7170Hence, as in <strong>shared</strong> above, the resulting layout is shareable across 7171programs.</p> 7172</div> 7173<div class="paragraph"> 7174<p>Layout qualifiers on member declarations cannot use the <strong>shared</strong>, <strong>packed</strong>, 7175<strong>std140</strong>, or <strong>std430</strong> qualifiers. 7176These can only be used at global scope (without an object) or on a block 7177declaration, or an error results.</p> 7178</div> 7179<div class="paragraph"> 7180<p>The <strong>row_major</strong> and <strong>column_major</strong> qualifiers only affect the layout of 7181matrices, including all matrices contained in structures and arrays they are 7182applied to, to all depths of nesting. 7183These qualifiers can be applied to other types, but will have no effect.</p> 7184</div> 7185<div class="paragraph"> 7186<p>The <strong>row_major</strong> qualifier overrides only the <strong>column_major</strong> qualifier; other 7187qualifiers are inherited. 7188Elements within a matrix row will be contiguous in memory.</p> 7189</div> 7190<div class="paragraph"> 7191<p>The <strong>column_major</strong> qualifier overrides only the <strong>row_major</strong> qualifier; other 7192qualifiers are inherited. 7193Elements within a matrix column will be contiguous in memory.</p> 7194</div> 7195<div class="paragraph"> 7196<p>The <strong>binding</strong> qualifier specifies the uniform buffer binding point 7197corresponding to the uniform or shader storage block, which will be used to 7198obtain the values of the member variables of the block. 7199It is a compile-time error to specify the <strong>binding</strong> qualifier for the global 7200scope or for block member declarations. 7201Any uniform or shader storage block declared without a <strong>binding</strong> qualifier 7202is initially assigned to block binding point zero. 7203After a program is linked, the binding points used for uniform 7204(but not shader storage) blocks 7205declared with or without a <strong>binding</strong> qualifier can be updated 7206by the API.</p> 7207</div> 7208<div class="paragraph"> 7209<p>When used with OpenGL ES, 7210if the <strong>binding</strong> qualifier is used with a uniform block or shader storage 7211block instanced as an array, the first element of the array takes the 7212specified block binding and each subsequent element takes the next 7213consecutive binding point. 7214For an array of arrays, each element (e.g. 6 elements for a[2][3]) gets a 7215binding point, and they are ordered per the array of array ordering 7216described in “<a href="#arrays">Arrays.</a>”</p> 7217</div> 7218<div class="paragraph"> 7219<p>When targeting Vulkan, 7220if the <strong>binding</strong> qualifier is used with a uniform block or buffer block 7221instanced as an array, the entire array takes only the provided binding 7222number. 7223The next consecutive binding number is available for a different 7224object. 7225For an array of arrays, descriptor set array element numbers used 7226in descriptor set accesses are ordered per the array-of-array ordering 7227described in “<a href="#arrays">Arrays.</a>”</p> 7228</div> 7229<div class="paragraph"> 7230<p>If the binding point for any uniform or shader storage block instance is 7231less than zero, or greater than or equal to the corresponding 7232implementation-dependent maximum number of buffer bindings, a compile-time 7233error will occur. 7234When the <strong>binding</strong> qualifier is used with a uniform or shader storage block 7235instanced as an array of size <em>N</em>, all elements of the array from <strong>binding</strong> 7236through <em>binding + N - 1</em> must be within this range.</p> 7237</div> 7238<div class="paragraph"> 7239<p>The <strong>set</strong> qualifier is only available when targeting Vulkan. 7240It specifies the descriptor set this object belongs to. 7241It is an error to apply <strong>set</strong> to a standalone qualifier, to 7242a member of a block, or when not targeting an API that supports descriptor sets. 7243It is an error to apply <strong>set</strong> to a block qualified as <strong>push_constant</strong>. 7244By default, any non-push-constant uniform or shader storage block declared 7245without a <strong>set</strong> identifier is assigned to descriptor set 0. 7246Similarly, any sampler, texture, or subpass-input type declared as a uniform 7247without a <strong>set</strong> identifier is also assigned to descriptor set 0.</p> 7248</div> 7249<div class="paragraph"> 7250<p>If applied to an object declared as an array, all elements of the array 7251belong to the specified <strong>set</strong>.</p> 7252</div> 7253<div class="paragraph"> 7254<p>When generating SPIR-V, it is an error for either the <strong>set</strong> or 7255<strong>binding</strong> value to exceed a front-end-configuration supplied maximum value.</p> 7256</div> 7257<div class="paragraph"> 7258<p>When multiple arguments are listed in a <strong>layout</strong> declaration, the effect 7259will be the same as if they were declared one at a time, in order from left 7260to right, each in turn inheriting from and overriding the result from the 7261previous qualification.</p> 7262</div> 7263<div class="paragraph"> 7264<p>For example</p> 7265</div> 7266<div class="listingblock"> 7267<div class="content"> 7268<pre class="CodeRay highlight"><code data-lang="c++">layout(row_major, column_major)</code></pre> 7269</div> 7270</div> 7271<div class="paragraph"> 7272<p>results in the qualification being <strong>column_major</strong>. 7273Other examples:</p> 7274</div> 7275<div class="listingblock"> 7276<div class="content"> 7277<pre class="CodeRay highlight"><code data-lang="c++">layout(shared, row_major) uniform; <span class="comment">// default is now shared and row_major</span> 7278 7279layout(std140) uniform Transform { <span class="comment">// layout of this block is std140</span> 7280 mat4 M1; <span class="comment">// row major</span> 7281 layout(column_major) mat4 M2; <span class="comment">// column major</span> 7282 mat3 N1; <span class="comment">// row major</span> 7283}; 7284 7285uniform T2 { <span class="comment">// layout of this block is shared</span> 7286 ... 7287}; 7288 7289layout(column_major) uniform T3 { <span class="comment">// shared and column major</span> 7290 mat4 M3; <span class="comment">// column major</span> 7291 layout(row_major) mat4 m4; <span class="comment">// row major</span> 7292 mat3 N2; <span class="comment">// column major</span> 7293};</code></pre> 7294</div> 7295</div> 7296<div class="paragraph"> 7297<p>When targeting Vulkan, the <strong>offset</strong> and <strong>align</strong> qualifiers for blocks and 7298block members can only be used with <strong>uniform</strong> and <strong>buffer</strong> blocks. 7299When not targeting Vulkan, they cannot be used with blocks or block members.</p> 7300</div> 7301<div class="paragraph"> 7302<p>The <strong>offset</strong> qualifier can only be used on block members. 7303The <strong>offset</strong> qualifier forces the qualified member to start at or after the 7304specified <em>layout-qualifier-value</em>, which will be its byte offset from 7305the beginning of the buffer. 7306It is a compile-time error to have any offset, explicit or assigned, that 7307lies within another member of the block. 7308Two blocks linked together in the same program with the same block name must 7309have the exact same set of members qualified with <strong>offset</strong> and their 7310<em>layout-qualifier-value</em> values must be the same, or a link-time error 7311results. 7312The specified offset must be a multiple of the base alignment of the type of 7313the block member it qualifies, or a compile-time error results.</p> 7314</div> 7315<div class="paragraph"> 7316<p>The <strong>align</strong> qualifier makes the start of each block member have a minimum 7317byte alignment. 7318It does not affect the internal layout within each member, which will still 7319follow the <strong>std140</strong> or <strong>std430</strong> rules. 7320The specified alignment must be greater than 0 and a power of 2, or a 7321compile-time error results.</p> 7322</div> 7323<div class="paragraph"> 7324<p>The <em>actual alignment</em> of a member will be the greater of the specified 7325<strong>align</strong> alignment and the standard (e.g. <strong>std140</strong>) base alignment for the 7326member’s type. 7327The <em>actual offset</em> of a member is computed as follows: If <strong>offset</strong> was 7328declared, start with that offset, otherwise start with the offset immediately 7329following the preceding member (in declaration order). 7330If the resulting offset is not a multiple of the <em>actual alignment</em>, 7331increase it to the first offset that is a multiple of the <em>actual 7332alignment</em>. 7333This results in the <em>actual offset</em> the member will have.</p> 7334</div> 7335<div class="paragraph"> 7336<p>When <strong>align</strong> is applied to an array, it affects only the start of the array, 7337not the array’s internal stride. 7338Both an <strong>offset</strong> and an <strong>align</strong> qualifier can be specified on a declaration.</p> 7339</div> 7340<div class="paragraph"> 7341<p>The <strong>align</strong> qualifier, when used on a block, has the same effect as 7342qualifying each member with the same <strong>align</strong> value as declared on the block, 7343and gets the same compile-time results and errors as if this had been done. 7344As described in general earlier, an individual member can specify its own 7345<strong>align</strong>, which overrides the block-level <strong>align</strong>, but just for that member.</p> 7346</div> 7347<div class="paragraph"> 7348<p>Examples:</p> 7349</div> 7350<div class="listingblock"> 7351<div class="content"> 7352<pre class="CodeRay highlight"><code data-lang="c++">layout(std140) uniform block { 7353 vec4 a; <span class="comment">// a takes offsets 0-15</span> 7354 layout(offset = <span class="integer">32</span>) vec3 b; <span class="comment">// b takes offsets 32-43</span> 7355 layout(offset = <span class="integer">40</span>) vec2 c; <span class="comment">// ERROR, lies within previous member</span> 7356 layout(offset = <span class="integer">48</span>) vec2 d; <span class="comment">// d takes offsets 48-55</span> 7357 layout(align = <span class="integer">16</span>) <span class="predefined-type">float</span> e; <span class="comment">// e takes offsets 64-67</span> 7358 layout(align = <span class="integer">2</span>) <span class="predefined-type">double</span> f; <span class="comment">// f takes offsets 72-79</span> 7359 layout(align = <span class="integer">6</span>) <span class="predefined-type">double</span> g; <span class="comment">// ERROR, 6 is not a power of 2</span> 7360 layout(offset = <span class="integer">80</span>) <span class="predefined-type">float</span> h; <span class="comment">// h takes offsets 80-83</span> 7361 layout(align = <span class="integer">64</span>) dvec3 i; <span class="comment">// i takes offsets 128-151</span> 7362 layout(offset = <span class="integer">164</span>, align = <span class="integer">8</span>) 7363 <span class="predefined-type">float</span> j; <span class="comment">// j takes offsets 168-171</span> 7364};</code></pre> 7365</div> 7366</div> 7367</div> 7368<div class="sect3"> 7369<h4 id="opaque-uniform-layout-qualifiers">4.4.5. Opaque Uniform Layout Qualifiers</h4> 7370<div class="paragraph"> 7371<p>Opaque uniform variables can take the uniform layout qualifier for binding:</p> 7372</div> 7373<div class="openblock bnf"> 7374<div class="content"> 7375<div class="dlist"> 7376<dl> 7377<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 7378<dd> 7379<p><strong>binding</strong> <strong>=</strong> <em>layout-qualifier-value</em></p> 7380</dd> 7381</dl> 7382</div> 7383</div> 7384</div> 7385<div class="paragraph"> 7386<p>The <strong>binding</strong> qualifier specifies the point where the variable will be bound. 7387Any opaque variable declared without a binding qualifier has a default binding 7388of zero.</p> 7389</div> 7390<div class="paragraph"> 7391<p>When used with OpenGL ES, 7392if the <strong>binding</strong> qualifier is used with an array, the first element of the 7393array takes the specified binding point and each subsequent element takes the 7394next consecutive binding point. 7395For an array of arrays, each element (e.g. 6 elements for a[2][3]) gets a 7396binding point, and they are ordered per the array of array ordering 7397described in “<a href="#arrays">Arrays.</a>”</p> 7398</div> 7399<div class="paragraph"> 7400<p>When targeting Vulkan, 7401if the <strong>binding</strong> qualifier is used with an array, the entire array 7402takes only the provided binding number. The next consecutive binding 7403number is available for a different object.</p> 7404</div> 7405<div class="paragraph"> 7406<p>If the <strong>binding</strong> is less than zero, or greater than or equal to the 7407implementation-dependent maximum supported number of binding points, 7408a compile-time error will occur. 7409When the <strong>binding</strong> qualifier is used with an array of size <em>N</em>, all elements 7410of the array from <strong>binding</strong> through <em>binding + N - 1</em> must be within this 7411range.</p> 7412</div> 7413<div class="paragraph"> 7414<p>A link-time error will result if two shaders in a program specify different 7415<em>layout-qualifier-value</em> bindings for the same opaque-uniform name. 7416However, it is not an error to specify a binding on some but not all 7417declarations for the same name, as shown in the examples below.</p> 7418</div> 7419<div class="listingblock"> 7420<div class="content"> 7421<pre class="CodeRay highlight"><code data-lang="c++"><span class="comment">// in one shader...</span> 7422layout(binding=<span class="integer">3</span>) uniform sampler2D s; <span class="comment">// s bound to point 3</span> 7423 7424<span class="comment">// in another shader...</span> 7425uniform sampler2D s; <span class="comment">// okay, s still bound at 3</span> 7426 7427<span class="comment">// in another shader...</span> 7428layout(binding=<span class="integer">4</span>) uniform sampler2D s; <span class="comment">// ERROR: contradictory bindings</span></code></pre> 7429</div> 7430</div> 7431</div> 7432<div class="sect3"> 7433<h4 id="atomic-counter-layout-qualifiers">4.4.6. Atomic Counter Layout Qualifiers</h4> 7434<div class="paragraph"> 7435<p>Atomic counters are not available when targeting Vulkan.</p> 7436</div> 7437<div class="paragraph"> 7438<p>Atomic counter layout qualifiers can be used on atomic counter declarations. 7439The atomic counter qualifiers are:</p> 7440</div> 7441<div class="openblock bnf"> 7442<div class="content"> 7443<div class="dlist"> 7444<dl> 7445<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 7446<dd> 7447<p><strong>binding</strong> <strong>=</strong> <em>layout-qualifier-value</em><br> 7448<strong>offset</strong> <strong>=</strong> <em>layout-qualifier-value</em></p> 7449</dd> 7450</dl> 7451</div> 7452</div> 7453</div> 7454<div class="paragraph"> 7455<p>For example,</p> 7456</div> 7457<div class="listingblock"> 7458<div class="content"> 7459<pre class="CodeRay highlight"><code data-lang="c++">layout(binding = <span class="integer">2</span>, offset = <span class="integer">4</span>) uniform atomic_uint a;</code></pre> 7460</div> 7461</div> 7462<div class="paragraph"> 7463<p>will establish that the opaque handle to the atomic counter <em>a</em> will be 7464bound to atomic counter buffer binding point 2 at an offset of 4 basic 7465machine units into that buffer. 7466The default <em>offset</em> for binding point 2 will be post incremented by 4 (the 7467size of an atomic counter).</p> 7468</div> 7469<div class="paragraph"> 7470<p>A subsequent atomic counter declaration will inherit the previous (post 7471incremented) offset. 7472For example, a subsequent declaration of</p> 7473</div> 7474<div class="listingblock"> 7475<div class="content"> 7476<pre class="CodeRay highlight"><code data-lang="c++">layout(binding = <span class="integer">2</span>) uniform atomic_uint bar;</code></pre> 7477</div> 7478</div> 7479<div class="paragraph"> 7480<p>will establish that the atomic counter <em>bar</em> has a binding to buffer binding 7481point 2 at an offset of 8 basic machine units into that buffer. 7482The offset for binding point 2 will again be post-incremented by 4 (the size 7483of an atomic counter).</p> 7484</div> 7485<div class="paragraph"> 7486<p>When multiple variables are listed in a layout declaration, the effect will 7487be the same as if they were declared one at a time, in order from left to 7488right.</p> 7489</div> 7490<div class="paragraph"> 7491<p>Binding points are not inherited, only offsets. 7492Each binding point tracks its own current default <em>offset</em> for inheritance 7493of subsequent variables using the same <strong>binding</strong>. 7494The initial state of compilation is that all <strong>binding</strong> points have an 7495<em>offset</em> of 0. 7496The <em>offset</em> can be set per binding point at global scope (without declaring 7497a variable). 7498For example,</p> 7499</div> 7500<div class="listingblock"> 7501<div class="content"> 7502<pre class="CodeRay highlight"><code data-lang="c++">layout(binding = <span class="integer">2</span>, offset = <span class="integer">4</span>) uniform atomic_uint;</code></pre> 7503</div> 7504</div> 7505<div class="paragraph"> 7506<p>Establishes that the next <strong>atomic_uint</strong> declaration for binding point 2 will 7507inherit <em>offset</em> 4 (but does not establish a default <strong>binding</strong>):</p> 7508</div> 7509<div class="listingblock"> 7510<div class="content"> 7511<pre class="CodeRay highlight"><code data-lang="c++">layout(binding = <span class="integer">2</span>) uniform atomic_uint bar; <span class="comment">// offset is 4</span> 7512layout(offset = <span class="integer">8</span>) uniform atomic_uint bar; <span class="comment">// error, no default binding</span></code></pre> 7513</div> 7514</div> 7515<div class="paragraph"> 7516<p>Atomic counters may share the same binding point, but if a binding is 7517shared, their offsets must be either explicitly or implicitly (from 7518inheritance) unique and non overlapping.</p> 7519</div> 7520<div class="paragraph"> 7521<p>Example valid uniform declarations, assuming top of shader:</p> 7522</div> 7523<div class="listingblock"> 7524<div class="content"> 7525<pre class="CodeRay highlight"><code data-lang="c++">layout(binding=<span class="integer">3</span>, offset=<span class="integer">4</span>) uniform atomic_uint a; <span class="comment">// offset = 4</span> 7526layout(binding=<span class="integer">2</span>) uniform atomic_uint b; <span class="comment">// offset = 0</span> 7527layout(binding=<span class="integer">3</span>) uniform atomic_uint c; <span class="comment">// offset = 8</span> 7528layout(binding=<span class="integer">2</span>) uniform atomic_uint d; <span class="comment">// offset = 4</span></code></pre> 7529</div> 7530</div> 7531<div class="paragraph"> 7532<p>Example of an invalid uniform declaration:</p> 7533</div> 7534<div class="listingblock"> 7535<div class="content"> 7536<pre class="CodeRay highlight"><code data-lang="c++">layout(offset=<span class="integer">4</span>) ... <span class="comment">// error, must include binding</span> 7537layout(binding=<span class="integer">1</span>, offset=<span class="integer">0</span>) ... a; <span class="comment">// okay</span> 7538layout(binding=<span class="integer">2</span>, offset=<span class="integer">0</span>) ... b; <span class="comment">// okay</span> 7539layout(binding=<span class="integer">1</span>, offset=<span class="integer">0</span>) ... c; <span class="comment">// error, offsets must not be shared</span> 7540 <span class="comment">// between a and c</span> 7541layout(binding=<span class="integer">1</span>, offset=<span class="integer">2</span>) ... d; <span class="comment">// error, overlaps offset 0 of a</span></code></pre> 7542</div> 7543</div> 7544<div class="paragraph"> 7545<p>It is a compile-time error to bind an atomic counter with a binding value 7546greater than or equal to <em>gl_MaxAtomicCounterBindings</em>.</p> 7547</div> 7548</div> 7549<div class="sect3"> 7550<h4 id="format-layout-qualifiers">4.4.7. Format Layout Qualifiers</h4> 7551<div class="paragraph"> 7552<p>Format layout qualifiers can be used on image variable declarations (those 7553declared with a basic type having “<strong>image</strong>” in its keyword). 7554The format layout qualifier identifiers for image variable declarations are:</p> 7555</div> 7556<div class="openblock bnf"> 7557<div class="content"> 7558<div class="dlist"> 7559<dl> 7560<dt class="hdlist1"><em>layout-qualifier-id</em> : </dt> 7561<dd> 7562<p><em>float-image-format-qualifier</em><br> 7563<em>int-image-format-qualifier</em><br> 7564<em>uint-image-format-qualifier</em><br> 7565<strong>binding</strong> <strong>=</strong> <em>layout-qualifier-value</em></p> 7566</dd> 7567</dl> 7568</div> 7569</div> 7570</div> 7571<div class="openblock bnf"> 7572<div class="content"> 7573<div class="dlist"> 7574<dl> 7575<dt class="hdlist1"><em>float-image-format-qualifier</em> : </dt> 7576<dd> 7577<p><strong>rgba32f</strong><br> 7578<strong>rgba16f</strong><br> 7579<strong>r32f</strong><br> 7580<strong>rgba8</strong><br> 7581<strong>rgba8_snorm</strong></p> 7582</dd> 7583<dt class="hdlist1"><em>int-image-format-qualifier</em> : </dt> 7584<dd> 7585<p><strong>rgba32i</strong><br> 7586<strong>rgba16i</strong><br> 7587<strong>rgba8i</strong><br> 7588<strong>r32i</strong></p> 7589</dd> 7590<dt class="hdlist1"><em>uint-image-format-qualifier</em> : </dt> 7591<dd> 7592<p><strong>rgba32ui</strong><br> 7593<strong>rgba16ui</strong><br> 7594<strong>rgba8ui</strong><br> 7595<strong>r32ui</strong></p> 7596</dd> 7597</dl> 7598</div> 7599</div> 7600</div> 7601<div class="paragraph"> 7602<p>A format layout qualifier specifies the image format associated with a 7603declared image variable. 7604Only one format qualifier may be specified for any image variable 7605declaration. 7606For image variables with floating-point component types (keywords starting 7607with “<strong>image</strong>”), signed integer component types (keywords starting with 7608“<strong>iimage</strong>”), or unsigned integer component types (keywords starting with 7609“<strong>uimage</strong>”), the format qualifier used must match the 7610<em>float-image-format-qualifier</em>, <em>int-image-format-qualifier</em>, or 7611<em>uint-image-format-qualifier</em> grammar rules, respectively. 7612It is an error to declare an image variable where the format 7613qualifier does not match the image variable type.</p> 7614</div> 7615<div class="paragraph"> 7616<p>Any image variable must specify a format layout qualifier.</p> 7617</div> 7618<div class="paragraph"> 7619<p>The <strong>binding</strong> qualifier was described in 7620“<a href="#opaque-uniform-layout-qualifiers">Opaque Uniform Layout Qualifiers</a>”.</p> 7621</div> 7622</div> 7623<div class="sect3"> 7624<h4 id="_subpass_input_qualifier">4.4.8. Subpass Input Qualifier</h4> 7625<div class="paragraph"> 7626<p>Subpass inputs are only available when targeting Vulkan.</p> 7627</div> 7628<div class="paragraph"> 7629<p>Subpass inputs are declared with the basic <strong>subpassInput</strong> types. 7630They must be declared with the layout qualifier 7631<strong>input_attachment_index</strong>, or an error results. 7632For example:</p> 7633</div> 7634<div class="listingblock"> 7635<div class="content"> 7636<pre class="CodeRay highlight"><code data-lang="c++">layout(input_attachment_index = <span class="integer">2</span>) uniform subpassInput t;</code></pre> 7637</div> 7638</div> 7639<div class="paragraph"> 7640<p>This selects which subpass input is being read from. The value assigned 7641to <strong>input_attachment_index</strong>, say <em>i</em> (<code>input_attachment_index = i</code>), selects 7642that entry (<em>i</em> th entry) in the input list for the pass. See the API 7643documentation for more detail about passes and the input list.</p> 7644</div> 7645<div class="paragraph"> 7646<p>If an array of size <em>N</em> is declared, it consumes <em>N</em> consecutive 7647<strong>input_attachment_index</strong> values, starting with the one provided.</p> 7648</div> 7649<div class="paragraph"> 7650<p>It is a compile-time or link-time error to have different variables 7651declared with the same <strong>input_attachment_index</strong>. 7652This includes any overlap in the implicit <strong>input_attachment_index</strong> consumed by 7653array declarations.</p> 7654</div> 7655<div class="paragraph"> 7656<p>It is an error if the value assigned to an <strong>input_attachment_index</strong> 7657is greater than or equal to <em>gl_MaxInputAttachments</em>.</p> 7658</div> 7659</div> 7660</div> 7661<div class="sect2"> 7662<h3 id="interpolation-qualifiers">4.5. Interpolation Qualifiers</h3> 7663<div class="paragraph"> 7664<p>Inputs and outputs that could be interpolated can be further qualified by at 7665most one of the following interpolation qualifiers:</p> 7666</div> 7667<table class="tableblock frame-all grid-all stretch"> 7668<colgroup> 7669<col style="width: 50%;"> 7670<col style="width: 50%;"> 7671</colgroup> 7672<thead> 7673<tr> 7674<th class="tableblock halign-left valign-top">Qualifier</th> 7675<th class="tableblock halign-left valign-top">Meaning</th> 7676</tr> 7677</thead> 7678<tbody> 7679<tr> 7680<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>smooth</strong></p></td> 7681<td class="tableblock halign-left valign-top"><p class="tableblock">perspective correct interpolation</p></td> 7682</tr> 7683<tr> 7684<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>flat</strong></p></td> 7685<td class="tableblock halign-left valign-top"><p class="tableblock">no interpolation</p></td> 7686</tr> 7687</tbody> 7688</table> 7689<div class="paragraph"> 7690<p>The presence of and type of interpolation is controlled by the above 7691interpolation qualifiers as well as the auxiliary storage qualifiers 7692<strong>centroid</strong> and <strong>sample</strong>. 7693When no interpolation qualifier is present, smooth interpolation is used. 7694It is a compile-time error to use more than one interpolation qualifier. 7695The auxiliary storage qualifier <strong>patch</strong> is not used for interpolation; it is 7696a compile-time error to use interpolation qualifiers with <strong>patch</strong>.</p> 7697</div> 7698<div class="paragraph"> 7699<p>A variable qualified as <strong>flat</strong> will not be interpolated. 7700Instead, it will have the same value for every fragment within a primitive. 7701This value will come from a single provoking vertex, as described by the 7702<a href="#references">API</a>. 7703A variable qualified as <strong>flat</strong> may also be qualified as <strong>centroid</strong> or 7704<strong>sample</strong>, which will mean the same thing as qualifying it only as <strong>flat</strong>.</p> 7705</div> 7706<div class="paragraph"> 7707<p>A variable qualified as <strong>smooth</strong> will be interpolated in a 7708perspective-correct manner over the primitive being rendered.</p> 7709</div> 7710<div class="paragraph"> 7711<p>Interpolation in a perspective correct manner is specified in equations 13.4 7712of the <a href="#references">OpenGL ES Specification</a>, section 13.4.1 “Line Segments” and 7713equation 13.7, section 13.5.1 “Polygon Interpolation”.</p> 7714</div> 7715<div class="paragraph"> 7716<p>When multisample rasterization is disabled, or for fragment shader input 7717variables qualified with neither <strong>centroid</strong> nor <strong>sample</strong>, the value of the 7718assigned variable may be interpolated anywhere within the pixel and a single 7719value may be assigned to each sample within the pixel, to the extent 7720permitted by the <a href="#references">OpenGL ES Specification</a>.</p> 7721</div> 7722<div class="paragraph"> 7723<p>When multisample rasterization is enabled, <strong>centroid</strong> and <strong>sample</strong> may be 7724used to control the location and frequency of the sampling of the qualified 7725fragment shader input. 7726If a fragment shader input is qualified with <strong>centroid</strong>, a single value may 7727be assigned to that variable for all samples in the pixel, but that value 7728must be interpolated at a location that lies in both the pixel and in the 7729primitive being rendered, including any of the pixel’s samples covered by 7730the primitive. 7731Because the location at which the variable is interpolated may be different 7732in neighboring pixels, and derivatives may be computed by computing 7733differences between neighboring pixels, derivatives of centroid-sampled 7734inputs may be less accurate than those for non-centroid interpolated 7735variables. 7736If a fragment shader input is qualified with <strong>sample</strong>, a separate value must 7737be assigned to that variable for each covered sample in the pixel, and that 7738value must be sampled at the location of the individual sample.</p> 7739</div> 7740</div> 7741<div class="sect2"> 7742<h3 id="parameter-qualifiers">4.6. Parameter Qualifiers</h3> 7743<div class="paragraph"> 7744<p>In addition to precision qualifiers and memory qualifiers, parameters can 7745have these parameter qualifiers.</p> 7746</div> 7747<table class="tableblock frame-all grid-all stretch"> 7748<colgroup> 7749<col style="width: 50%;"> 7750<col style="width: 50%;"> 7751</colgroup> 7752<thead> 7753<tr> 7754<th class="tableblock halign-left valign-top">Qualifier</th> 7755<th class="tableblock halign-left valign-top">Meaning</th> 7756</tr> 7757</thead> 7758<tbody> 7759<tr> 7760<td class="tableblock halign-left valign-top"><p class="tableblock"><none: default></p></td> 7761<td class="tableblock halign-left valign-top"><p class="tableblock">same as <strong>in</strong></p></td> 7762</tr> 7763<tr> 7764<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>in</strong></p></td> 7765<td class="tableblock halign-left valign-top"><p class="tableblock">for function parameters passed into a function</p></td> 7766</tr> 7767<tr> 7768<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>out</strong></p></td> 7769<td class="tableblock halign-left valign-top"><p class="tableblock">for function parameters passed back out of a function, 7770 but not initialized for use when passed in</p></td> 7771</tr> 7772<tr> 7773<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>inout</strong></p></td> 7774<td class="tableblock halign-left valign-top"><p class="tableblock">for function parameters passed both into and out of a 7775 function</p></td> 7776</tr> 7777</tbody> 7778</table> 7779<div class="paragraph"> 7780<p>Parameter qualifiers are discussed in more detail in 7781“<a href="#function-calling-conventions">Function Calling Conventions</a>”.</p> 7782</div> 7783</div> 7784<div class="sect2"> 7785<h3 id="precision-and-precision-qualifiers">4.7. Precision and Precision Qualifiers</h3> 7786<div class="paragraph"> 7787<p>When targeting Vulkan: 7788For interface matching, uniform variables and uniform and buffer block 7789members must have the same precision qualification. 7790Global variables declared in different compilation units linked into the 7791same shader stage must be declared with the same precision qualification.</p> 7792</div> 7793<div class="paragraph"> 7794<p>For the purposes of determining if an output from one shader stage matches 7795an input of the next stage, the precision qualifier need not match.</p> 7796</div> 7797<div class="sect3"> 7798<h4 id="range-and-precision">4.7.1. Range and Precision</h4> 7799<div class="paragraph"> 7800<p>The precision of <strong>highp</strong> 7801floating-point variables is defined by the IEEE 754 standard for 780232-bit 7803floating-point numbers.</p> 7804</div> 7805<div class="paragraph"> 7806<p>This includes support for NaNs (Not a Number) and Infs (positive or negative 7807infinities) and positive and negative zeros.</p> 7808</div> 7809<div class="paragraph"> 7810<p>The following rules apply to <strong>highp</strong> 7811operations: 7812Signed infinities and zeros are generated as dictated by IEEE, but subject 7813to the precisions allowed in the following table. 7814Any subnormal (denormalized) value input into a shader or potentially 7815generated by any operation in a shader can be flushed to 0. 7816The rounding mode cannot be set and is undefined but must not affect the 7817result by more than 1 ULP. 7818NaNs are not required to be generated. 7819Support for signaling NaNs is not required and exceptions are never raised. 7820Operations including built-in functions that operate on a NaN are not 7821required to return a NaN as the result. 7822However if NaNs are generated, <strong>isnan</strong>() must return the correct value.</p> 7823</div> 7824<div class="paragraph"> 7825<p>Precisions are expressed in terms of maximum relative error in units of ULP 7826(units in the last place), unless otherwise noted.</p> 7827</div> 7828<div class="paragraph"> 7829<p>For single precision operations, precisions are required as follows:</p> 7830</div> 7831<table class="tableblock frame-all grid-all stretch"> 7832<colgroup> 7833<col style="width: 50%;"> 7834<col style="width: 50%;"> 7835</colgroup> 7836<thead> 7837<tr> 7838<th class="tableblock halign-left valign-top">Operation</th> 7839<th class="tableblock halign-left valign-top">Precision</th> 7840</tr> 7841</thead> 7842<tbody> 7843<tr> 7844<td class="tableblock halign-left valign-top"><p class="tableblock"><em>a</em> + <em>b</em>, <em>a</em> - <em>b</em>, <em>a</em> * <em>b</em></p></td> 7845<td class="tableblock halign-left valign-top"><p class="tableblock">Correctly rounded.</p></td> 7846</tr> 7847<tr> 7848<td class="tableblock halign-left valign-top"><p class="tableblock"><, <=, ==, >, >=</p></td> 7849<td class="tableblock halign-left valign-top"><p class="tableblock">Correct result.</p></td> 7850</tr> 7851<tr> 7852<td class="tableblock halign-left valign-top"><p class="tableblock"><em>a</em> / <em>b</em>, 1.0 / <em>b</em></p></td> 7853<td class="tableblock halign-left valign-top"><p class="tableblock">2.5 ULP for <span class="eq">|b|</span> in the range <span class="eq">[2<sup>-126</sup>, 2<sup>126</sup>]</span>.</p></td> 7854</tr> 7855<tr> 7856<td class="tableblock halign-left valign-top"><p class="tableblock"><em>a</em> * <em>b</em> + <em>c</em></p></td> 7857<td class="tableblock halign-left valign-top"><p class="tableblock">Correctly rounded single operation or 7858 sequence of two correctly rounded operations.</p></td> 7859</tr> 7860<tr> 7861<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>fma</strong>()</p></td> 7862<td class="tableblock halign-left valign-top"><p class="tableblock">Inherited from <em>a</em> * <em>b</em> + <em>c</em>.</p></td> 7863</tr> 7864<tr> 7865<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>pow</strong>(<em>x</em>, <em>y</em>)</p></td> 7866<td class="tableblock halign-left valign-top"><p class="tableblock">Inherited from <strong>exp2</strong>(<em>y</em> * <strong>log2</strong>(<em>x</em>)).</p></td> 7867</tr> 7868<tr> 7869<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>exp</strong>(<em>x</em>), <strong>exp2</strong>(<em>x</em>)</p></td> 7870<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="eq">(3 + 2 · |x|)</span> ULP.</p></td> 7871</tr> 7872<tr> 7873<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>log</strong>(), <strong>log2</strong>()</p></td> 7874<td class="tableblock halign-left valign-top"><p class="tableblock">3 ULP outside the range <span class="eq">[0.5,2.0]</span>.<br> 7875 Absolute error < 2<sup>-21</sup> inside the range 7876 <span class="eq">[0.5,2.0]</span>.</p></td> 7877</tr> 7878<tr> 7879<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>sqrt</strong>()</p></td> 7880<td class="tableblock halign-left valign-top"><p class="tableblock">Inherited from 1.0 / <strong>inversesqrt</strong>().</p></td> 7881</tr> 7882<tr> 7883<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>inversesqrt</strong>()</p></td> 7884<td class="tableblock halign-left valign-top"><p class="tableblock">2 ULP.</p></td> 7885</tr> 7886<tr> 7887<td class="tableblock halign-left valign-top"><p class="tableblock">implicit and explicit 7888 conversions between types</p></td> 7889<td class="tableblock halign-left valign-top"><p class="tableblock">Correctly rounded.</p></td> 7890</tr> 7891</tbody> 7892</table> 7893<div class="paragraph"> 7894<p>Built-in functions defined in the specification with an equation built from 7895the above operations inherit the above errors. 7896These include, for example, the geometric functions, the common functions, 7897and many of the matrix functions. 7898Built-in functions not listed above and not defined as equations of the 7899above have undefined precision. 7900These include, for example, the trigonometric functions and determinant.</p> 7901</div> 7902<div class="paragraph"> 7903<p>Storage requirements are declared through use of <em>precision qualifiers</em>. 7904The precision of operations must preserve the storage precisions of the 7905variables involved.</p> 7906</div> 7907<div class="paragraph"> 7908<p><strong>highp</strong> floating-point values are stored in IEEE 754 single precision 7909floating-point format. 7910<strong>mediump</strong> and <strong>lowp</strong> floating-point values have minimum range and precision 7911requirements as detailed below and have maximum range and precision as 7912defined by IEEE 754.</p> 7913</div> 7914<div class="paragraph"> 7915<p>All integral types are assumed to be implemented as integers and so may not 7916be emulated by floating-point values. 7917<strong>highp</strong> signed integers are represented as twos-complement 32-bit signed 7918integers. 7919<strong>highp</strong> unsigned integers are represented as unsigned 32-bit integers. 7920<strong>mediump</strong> integers (signed and unsigned) must be represented as an integer 7921with between 16 and 32 bits inclusive. 7922<strong>lowp</strong> integers (signed and unsigned) must be represented as an integer with 7923between 9 and 32 bits inclusive.</p> 7924</div> 7925<div class="paragraph"> 7926<p>The required ranges and precisions for precision qualifiers are:</p> 7927</div> 7928<table class="tableblock frame-all grid-all stretch"> 7929<colgroup> 7930<col style="width: 16.6666%;"> 7931<col style="width: 16.6666%;"> 7932<col style="width: 16.6666%;"> 7933<col style="width: 16.6666%;"> 7934<col style="width: 16.6666%;"> 7935<col style="width: 16.667%;"> 7936</colgroup> 7937<thead> 7938<tr> 7939<th class="tableblock halign-left valign-top">Qualifier</th> 7940<th class="tableblock halign-left valign-top">Floating-Point Range</th> 7941<th class="tableblock halign-left valign-top">Floating-Point Magnitude Range</th> 7942<th class="tableblock halign-left valign-top">Floating-Point Precision</th> 7943<th class="tableblock halign-left valign-top">Signed Integer Range</th> 7944<th class="tableblock halign-left valign-top">Unsigned Integer Range</th> 7945</tr> 7946</thead> 7947<tbody> 7948<tr> 7949<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>highp</strong></p></td> 7950<td class="tableblock halign-left valign-top"><p class="tableblock">Subset of IEEE-754<br> 7951 <span class="eq">(-2<sup>128</sup>,2<sup>128</sup>)</span></p></td> 7952<td class="tableblock halign-left valign-top"><p class="tableblock">Subset of IEEE-754<br> 7953 0.0, <span class="eq">[2<sup>-126</sup>,2<sup>128</sup>)</span></p></td> 7954<td class="tableblock halign-left valign-top"><p class="tableblock">Subset of IEEE-754 relative:<br> 7955 <span class="eq">2<sup>-23</sup></span></p></td> 7956<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="eq">[-2<sup>31</sup>,2<sup>31</sup>-1]</span></p></td> 7957<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="eq">[0,2<sup>32</sup>-1]</span></p></td> 7958</tr> 7959<tr> 7960<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mediump</strong> (minimum requirements)</p></td> 7961<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="eq">(-2<sup>14</sup>,2<sup>14</sup>)</span></p></td> 7962<td class="tableblock halign-left valign-top"><p class="tableblock">0.0, <span class="eq">[2<sup>-14</sup>,2<sup>14</sup>)</span></p></td> 7963<td class="tableblock halign-left valign-top"><p class="tableblock">Relative:<br> 7964 <span class="eq">2<sup>-10</sup></span></p></td> 7965<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="eq">[-2<sup>15</sup>,2<sup>15</sup>-1]</span></p></td> 7966<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="eq">[0,2<sup>16</sup>-1]</span></p></td> 7967</tr> 7968<tr> 7969<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lowp</strong> (minimum requirements)</p></td> 7970<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="eq">(-2,2)</span></p></td> 7971<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="eq">(2<sup>-8</sup>,2)</span></p></td> 7972<td class="tableblock halign-left valign-top"><p class="tableblock">Absolute:<br> 7973 <span class="eq">2<sup>-8</sup></span></p></td> 7974<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="eq">[-2<sup>8</sup>,2<sup>8</sup>-1]</span></p></td> 7975<td class="tableblock halign-left valign-top"><p class="tableblock"><span class="eq">[0,2<sup>9</sup>-1]</span></p></td> 7976</tr> 7977</tbody> 7978</table> 7979<div class="paragraph"> 7980<p>The semi-open interval notation used for the magnitude ranges means that the 7981lower end of the interval is included, but the upper end is excluded. Thus the 7982largest required magnitude is half of the relative precision less than the 7983value given. The largest required value for highp, for example, is <span class="eq">2<sup>128</sup> 7984× (1 - 2<sup>-24</sup>)</span>.</p> 7985</div> 7986<div class="paragraph"> 7987<p><em>Relative precision</em> is defined as the worst case (i.e. largest) ratio of 7988the smallest step in relation to the value for all non-zero values in the 7989required ranges, above:</p> 7990</div> 7991<div class="stemblock"> 7992<div class="content"> 7993\[\begin{aligned} 7994 \mathit{Precision}_{relative} = { 7995 \left| { 7996 { \left| v_1 - v_2 \right| }_{min} } \over { v_1 } 7997 \right| 7998 }_{max}, & 7999 v_1,v_2 \neq 0, v_1 \neq v_2 8000\end{aligned}\] 8001</div> 8002</div> 8003<div class="paragraph"> 8004<p>It is therefore twice the maximum rounding error when converting from a real 8005number. 8006Subnormal numbers may be supported and may have lower relative precision.</p> 8007</div> 8008<div class="paragraph"> 8009<p>In addition, the range and precision of a <strong>mediump</strong> floating-point value 8010must be the same as or greater than the range and precision of a <strong>lowp</strong> 8011floating-point value. 8012The range and precision of a <strong>highp</strong> floating-point value must be the same 8013as or greater than the range and precision of a <strong>mediump</strong> floating-point 8014value.</p> 8015</div> 8016<div class="paragraph"> 8017<p>The range of a <strong>mediump</strong> integer value must be the same as or greater than 8018the range of a <strong>lowp</strong> integer value. 8019The range of a <strong>highp</strong> integer value must be the same as or greater than the 8020range of a <strong>mediump</strong> integer value.</p> 8021</div> 8022<div class="paragraph"> 8023<p>Within the above specification, an implementation is allowed to vary the 8024representation of numeric values, both within a shader and between different 8025shaders. 8026If necessary, this variance can be controlled using the invariance 8027qualifier.</p> 8028</div> 8029<div class="paragraph"> 8030<p>The actual ranges and precisions provided by an implementation can be 8031queried through the API. 8032See the <a href="#references">normative references</a> for details on how to do 8033this.</p> 8034</div> 8035</div> 8036<div class="sect3"> 8037<h4 id="conversion-between-precisions">4.7.2. Conversion between precisions</h4> 8038<div class="paragraph"> 8039<p>Within the same type, conversion from a lower to a higher precision must be 8040exact. 8041When converting from a higher precision to a lower precision, if the value 8042is representable by the implementation of the target precision, the 8043conversion must also be exact. 8044If the value is not representable, the behavior is dependent on the type:</p> 8045</div> 8046<div class="ulist"> 8047<ul> 8048<li> 8049<p>For signed and unsigned integers, the value is truncated; bits in 8050positions not present in the target precision are set to zero. 8051(Positions start at zero and the least significant bit is considered to 8052be position zero for this purpose.)</p> 8053</li> 8054<li> 8055<p>For floating-point values, the value should either clamp to +Inf or 8056-Inf, or to the maximum or minimum value that the implementation 8057supports. 8058While this behavior is implementation-dependent, it should be consistent 8059for a given implementation.</p> 8060</li> 8061</ul> 8062</div> 8063</div> 8064<div class="sect3"> 8065<h4 id="precision-qualifiers">4.7.3. Precision Qualifiers</h4> 8066<div class="paragraph"> 8067<p>Any 8068floating-point, integer, or opaque-type declaration can have the type 8069preceded by one of these precision qualifiers:</p> 8070</div> 8071<table class="tableblock frame-all grid-all stretch"> 8072<colgroup> 8073<col style="width: 50%;"> 8074<col style="width: 50%;"> 8075</colgroup> 8076<tbody> 8077<tr> 8078<td class="tableblock halign-left valign-top"><p class="tableblock">Qualifier</p></td> 8079<td class="tableblock halign-left valign-top"><p class="tableblock">Meaning</p></td> 8080</tr> 8081<tr> 8082<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>highp</strong></p></td> 8083<td class="tableblock halign-left valign-top"><p class="tableblock">The variable satisfies the minimum requirements for <strong>highp</strong> 8084 described above. <strong>highp</strong> variables have the maximum range and 8085 precision available but may cause operations to run more 8086 slowly on some implementations.</p></td> 8087</tr> 8088<tr> 8089<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>mediump</strong></p></td> 8090<td class="tableblock halign-left valign-top"><p class="tableblock">SPIR-V <strong>RelaxedPrecision</strong> when targeting Vulkan, otherwise 8091 the variable satisfies the minimum requirements for <strong>mediump</strong> 8092 described above. <strong>mediump</strong> variables may typically be used to 8093 store high dynamic range colors and low precision geometry.</p></td> 8094</tr> 8095<tr> 8096<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lowp</strong></p></td> 8097<td class="tableblock halign-left valign-top"><p class="tableblock">SPIR-V <strong>RelaxedPrecision</strong> when targeting Vulkan, otherwise 8098 the variable satisfies the minimum requirements for <strong>lowp</strong> 8099 described above. <strong>lowp</strong> variables may typically be used to 8100 store 8-bit color values.</p></td> 8101</tr> 8102</tbody> 8103</table> 8104<div class="paragraph"> 8105<p>For example:</p> 8106</div> 8107<div class="listingblock"> 8108<div class="content"> 8109<pre class="CodeRay highlight"><code data-lang="c++">lowp <span class="predefined-type">float</span> color; 8110out mediump vec2 P; 8111lowp ivec2 foo(lowp mat3); 8112highp mat4 m;</code></pre> 8113</div> 8114</div> 8115<div class="paragraph"> 8116<p>Literal constants do not have precision qualifiers. 8117Neither do Boolean variables. 8118Neither do constructors.</p> 8119</div> 8120<div class="paragraph"> 8121<p>For this paragraph, “operation” includes operators, built-in functions, 8122and constructors, and “operand” includes function arguments and 8123constructor arguments. 8124The precision used to internally evaluate an operation, and the precision 8125qualification subsequently associated with any resulting intermediate 8126values, must be at least as high as the highest precision qualification of 8127the operands consumed by the operation.</p> 8128</div> 8129<div class="paragraph"> 8130<p>In cases where operands do not have a precision qualifier, the precision 8131qualification will come from the other operands. 8132If no operands have a precision qualifier, then the precision qualifications 8133of the operands of the next consuming operation in the expression will be 8134used. 8135This rule can be applied recursively until a precision qualified operand is 8136found. 8137If necessary, it will also include the precision qualification of l-values 8138for assignments, of the declared variable for initializers, of formal 8139parameters for function call arguments, or of function return types for 8140function return values. 8141If the precision cannot be determined by this method e.g. if an entire 8142expression is composed only of operands with no precision qualifier, and the 8143result is not assigned or passed as an argument, then it is evaluated at the 8144default precision of the type or greater. 8145When this occurs in the fragment shader, the default precision must be 8146defined.</p> 8147</div> 8148<div class="paragraph"> 8149<p>For example, consider the statements:</p> 8150</div> 8151<div class="listingblock"> 8152<div class="content"> 8153<pre class="CodeRay highlight"><code data-lang="c++">uniform highp <span class="predefined-type">float</span> h1; 8154highp <span class="predefined-type">float</span> h2 = <span class="float">2</span><span class="float">.3</span> * <span class="float">4</span><span class="float">.7</span>; <span class="comment">// operation and result are highp</span> 8155precision 8156mediump <span class="predefined-type">float</span> m; 8157m = <span class="float">3</span><span class="float">.7</span> * h1 * h2; <span class="comment">// all operations are highp precision</span> 8158h2 = m * h1; <span class="comment">// operation is highp precision</span> 8159m = h2 - h1; <span class="comment">// operation is highp precision</span> 8160h2 = m + m; <span class="comment">// addition and result at mediump precision</span> 8161<span class="directive">void</span> f(highp <span class="predefined-type">float</span> p); 8162f(<span class="float">3</span><span class="float">.3</span>); <span class="comment">// 3.3 will be passed in at highp precision</span></code></pre> 8163</div> 8164</div> 8165<div class="paragraph"> 8166<p>Precision qualifiers, as with other qualifiers, do not affect the basic type 8167of the variable. 8168In particular, there are no constructors for precision conversions; 8169constructors only convert types. 8170Similarly, precision qualifiers, as with other qualifiers, do not contribute 8171to function overloading based on parameter types. 8172As discussed in “<a href="#function-calling-conventions">Function Calling 8173Conventions</a>”, function input and output is done through copies, and 8174therefore qualifiers do not have to match.</p> 8175</div> 8176<div class="paragraph"> 8177<p>Precision qualifiers for outputs in one shader matched to inputs in another 8178shader need not match when both shaders are linked into the same program. 8179When both shaders are in separate programs, mismatched precision qualifiers 8180will result in a program interface mismatch that will result in program 8181pipeline validation failures, as described in section 7.4.1 “Shader 8182Interface Matching” of the <a href="#references">OpenGL ES Specification</a>.</p> 8183</div> 8184<div class="paragraph"> 8185<p>The precision of a variable is determined when the variable is declared and 8186cannot be subsequently changed.</p> 8187</div> 8188<div class="paragraph"> 8189<p>Where the precision of a constant integral or constant floating-point 8190expression is not specified, evaluation is performed at <strong>highp</strong>. 8191This rule does not affect the precision qualification of the expression.</p> 8192</div> 8193<div class="paragraph"> 8194<p>The evaluation of constant expressions must be invariant and will usually be 8195performed at compile time.</p> 8196</div> 8197</div> 8198<div class="sect3"> 8199<h4 id="default-precision-qualifiers">4.7.4. Default Precision Qualifiers</h4> 8200<div class="paragraph"> 8201<p>The precision statement</p> 8202</div> 8203<div class="listingblock"> 8204<div class="content"> 8205<pre class="CodeRay highlight"><code data-lang="c++">precision precision-qualifier type;</code></pre> 8206</div> 8207</div> 8208<div class="paragraph"> 8209<p>can be used to establish a default precision qualifier. 8210The <em>type</em> field can be either <strong>int</strong>, <strong>float</strong>, or any of the opaque types, 8211and the <em>precision-qualifier</em> can be <strong>lowp</strong>, <strong>mediump</strong>, or <strong>highp</strong>.</p> 8212</div> 8213<div class="paragraph"> 8214<p>Any other types or qualifiers will result in an error. 8215If <em>type</em> is <strong>float</strong>, the directive applies to non-precision-qualified 8216floating-point type (scalar, vector, and matrix) declarations. 8217If <em>type</em> is <strong>int</strong>, the directive applies to all non-precision-qualified 8218integer type (scalar, vector, signed, and unsigned) declarations. 8219This includes global variable declarations, function return declarations, 8220function parameter declarations, and local variable declarations.</p> 8221</div> 8222<div class="paragraph"> 8223<p>Non-precision qualified declarations will use the precision qualifier 8224specified in the most recent <strong>precision</strong> statement that is still in scope. 8225The <strong>precision</strong> statement has the same scoping rules as variable 8226declarations. 8227If it is declared inside a compound statement, its effect stops at the end 8228of the inner-most statement it was declared in. 8229Precision statements in nested scopes override precision statements in outer 8230scopes. 8231Multiple precision statements for the same basic type can appear inside the 8232same scope, with later statements overriding earlier statements within that 8233scope.</p> 8234</div> 8235<div class="paragraph"> 8236<p>All languages except for the fragment language have the following 8237predeclared globally scoped default precision statements:</p> 8238</div> 8239<div class="listingblock"> 8240<div class="content"> 8241<pre class="CodeRay highlight"><code data-lang="c++">precision highp <span class="predefined-type">float</span>; 8242precision highp <span class="predefined-type">int</span>; 8243precision lowp sampler2D; 8244precision lowp samplerCube; 8245precision highp atomic_uint;</code></pre> 8246</div> 8247</div> 8248<div class="paragraph"> 8249<p>The fragment language has the following predeclared globally scoped default 8250precision statements:</p> 8251</div> 8252<div class="listingblock"> 8253<div class="content"> 8254<pre class="CodeRay highlight"><code data-lang="c++">precision mediump <span class="predefined-type">int</span>; 8255precision lowp sampler2D; 8256precision lowp samplerCube; 8257precision highp atomic_uint;</code></pre> 8258</div> 8259</div> 8260<div class="paragraph"> 8261<p>The fragment language has no default precision qualifier for floating-point 8262types. 8263Hence for <strong>float</strong>, floating-point vector and matrix variable declarations, 8264either the declaration must include a precision qualifier or the default 8265float precision must have been previously declared. 8266Similarly, there is no default precision qualifier in any of the languages 8267for any type not listed above.</p> 8268</div> 8269</div> 8270<div class="sect3"> 8271<h4 id="available-precision-qualifiers">4.7.5. Available Precision Qualifiers</h4> 8272<div class="paragraph"> 8273<p>The built-in macro GL_FRAGMENT_PRECISION_HIGH is defined to one:</p> 8274</div> 8275<div class="listingblock"> 8276<div class="content"> 8277<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#define</span> GL_FRAGMENT_PRECISION_HIGH <span class="integer">1</span></code></pre> 8278</div> 8279</div> 8280<div class="paragraph"> 8281<p>This macro is available in all languages except compute.</p> 8282</div> 8283</div> 8284</div> 8285<div class="sect2"> 8286<h3 id="variance-and-the-invariant-qualifier">4.8. Variance and the Invariant Qualifier</h3> 8287<div class="paragraph"> 8288<p>In this section, <em>variance</em> refers to the possibility of getting different 8289values from the same expression in different programs. 8290For example, consider the situation where two vertex shaders, in different 8291programs, each set <em>gl_Position</em> with the same expression, and the input 8292values into that expression are the same when both shaders run. 8293It is possible, due to independent compilation of the two shaders, that the 8294values assigned to <em>gl_Position</em> are not exactly the same when the two 8295shaders run. 8296In this example, this can cause problems with alignment of geometry in a 8297multi-pass algorithm.</p> 8298</div> 8299<div class="paragraph"> 8300<p>In general, such variance between shaders is allowed. 8301When such variance does not exist for a particular output variable, that 8302variable is said to be <em>invariant</em>.</p> 8303</div> 8304<div class="sect3"> 8305<h4 id="the-invariant-qualifier">4.8.1. The Invariant Qualifier</h4> 8306<div class="paragraph"> 8307<p>To ensure that a particular output variable is invariant, it is necessary to 8308use the <strong>invariant</strong> qualifier. 8309It can either be used to qualify a previously declared variable as being 8310invariant:</p> 8311</div> 8312<div class="listingblock"> 8313<div class="content"> 8314<pre class="CodeRay highlight"><code data-lang="c++">invariant gl_Position; <span class="comment">// make existing gl_Position be invariant</span> 8315out vec3 Color; 8316invariant Color; <span class="comment">// make existing Color be invariant</span></code></pre> 8317</div> 8318</div> 8319<div class="paragraph"> 8320<p>or as part of a declaration when a variable is declared:</p> 8321</div> 8322<div class="listingblock"> 8323<div class="content"> 8324<pre class="CodeRay highlight"><code data-lang="c++">invariant centroid out vec3 Color;</code></pre> 8325</div> 8326</div> 8327<div class="paragraph"> 8328<p>Only variables output from a shader can be candidates for invariance. 8329This includes user-defined output variables and the built-in output 8330variables. 8331As only outputs can be declared as invariant, an output from one shader 8332stage will still match an input of a subsequent stage without the input 8333being declared as invariant.</p> 8334</div> 8335<div class="paragraph"> 8336<p>The <strong>invariant</strong> keyword can be followed by a comma separated list of 8337previously declared identifiers. 8338All uses of <strong>invariant</strong> must be at global scope or on block 8339members, and before any use of the variables being declared as invariant.</p> 8340</div> 8341<div class="paragraph"> 8342<p>To guarantee invariance of a particular output variable across two programs, 8343the following must also be true:</p> 8344</div> 8345<div class="ulist"> 8346<ul> 8347<li> 8348<p>The output variable is declared as invariant in both programs.</p> 8349</li> 8350<li> 8351<p>The same values must be input to all shader input variables consumed by 8352expressions and control flow contributing to the value assigned to the 8353output variable.</p> 8354</li> 8355<li> 8356<p>The texture formats, texel values, and texture filtering are set the 8357same way for any texture function calls contributing to the value of the 8358output variable.</p> 8359</li> 8360<li> 8361<p>All input values are all operated on in the same way. 8362 All operations in the consuming expressions and any intermediate 8363 expressions must be the same, with the same order of operands and same 8364 associativity, to give the same order of evaluation. 8365 Intermediate variables and functions must be declared as the same type 8366 with the same explicit or implicit precision 8367qualifiers and the same constant qualifiers. 8368 Any control flow affecting the output value must be the same, and any 8369 expressions consumed to determine this control flow must also follow 8370 these invariance rules.</p> 8371</li> 8372<li> 8373<p>All the data flow and control flow leading to setting the invariant 8374output variable reside in a single compilation unit.</p> 8375</li> 8376</ul> 8377</div> 8378<div class="paragraph"> 8379<p>Essentially, all the data flow and control flow leading to an invariant 8380output must match.</p> 8381</div> 8382<div class="paragraph"> 8383<p>Initially, by default, all output variables are allowed to be variant. 8384To force all output variables to be invariant, use the pragma</p> 8385</div> 8386<div class="listingblock"> 8387<div class="content"> 8388<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#pragma</span> STDGL invariant(all)</code></pre> 8389</div> 8390</div> 8391<div class="paragraph"> 8392<p>before all declarations in a shader. 8393If this pragma is used after the declaration of any variables or functions, 8394then the set of outputs that behave as invariant is undefined.</p> 8395</div> 8396<div class="paragraph"> 8397<p>Generally, invariance is ensured at the cost of flexibility in optimization, 8398so performance can be degraded by use of invariance. 8399Hence, use of this pragma is intended as a debug aid, to avoid individually 8400declaring all output variables as invariant.</p> 8401</div> 8402</div> 8403<div class="sect3"> 8404<h4 id="invariance-within-a-shader">4.8.2. Invariance Within a Shader</h4> 8405<div class="paragraph"> 8406<p>When a value is stored in a variable, it is usually assumed it will remain 8407constant unless explicitly changed. 8408However, during the process of optimization, it is possible that the 8409compiler may choose to recompute a value rather than store it in a register. 8410Since the precision of operations is not completely specified (e.g. a low 8411precision operation may be done at medium or high precision), it would be 8412possible for the recomputed value to be different from the original value.</p> 8413</div> 8414<div class="paragraph"> 8415<p>Values are allowed to be variant within a shader. 8416To prevent this, the invariant qualifier or invariant pragma must be used.</p> 8417</div> 8418<div class="paragraph"> 8419<p>Within a shader, there is no invariance for values generated by different 8420non-constant expressions, even if those expressions are identical.</p> 8421</div> 8422<div class="paragraph"> 8423<p>Example 1:</p> 8424</div> 8425<div class="listingblock"> 8426<div class="content"> 8427<pre class="CodeRay highlight"><code data-lang="c++">precision mediump; 8428vec4 col; 8429vec2 a = ... 8430... 8431col = texture(tex, a);<span class="comment">// a has a value _a1 _</span> 8432... 8433col = texture(tex, a); <span class="comment">// a has a value a2 where possibly a1 != a2</span></code></pre> 8434</div> 8435</div> 8436<div class="paragraph"> 8437<p>To enforce invariance in this example use:</p> 8438</div> 8439<div class="listingblock"> 8440<div class="content"> 8441<pre class="CodeRay highlight"><code data-lang="c++"><span class="preprocessor">#pragma</span> STDGL invariant(all)</code></pre> 8442</div> 8443</div> 8444<div class="paragraph"> 8445<p>Example 2:</p> 8446</div> 8447<div class="listingblock"> 8448<div class="content"> 8449<pre class="CodeRay highlight"><code data-lang="c++">vec2 m = ...; 8450vec2 n = ...; 8451vec2 a = m + n; 8452vec2 b = m + n; <span class="comment">// a and b are not guaranteed to be exactly equal</span></code></pre> 8453</div> 8454</div> 8455<div class="paragraph"> 8456<p>There is no mechanism to enforce invariance between a and b.</p> 8457</div> 8458</div> 8459<div class="sect3"> 8460<h4 id="invariance-of-constant-expressions">4.8.3. Invariance of Constant Expressions</h4> 8461<div class="paragraph"> 8462<p>Invariance must be guaranteed for constant expressions. 8463A particular constant expression must evaluate to the same result if it 8464appears again in the same shader or a different shader. 8465This includes the same expression appearing in two shaders of the same 8466language or shaders of two different languages.</p> 8467</div> 8468<div class="paragraph"> 8469<p>Constant expressions must evaluate to the same result when operated on as 8470already described above for invariant variables. 8471Constant expressions are not invariant with respect to equivalent 8472non-constant expressions, even when the <strong>invariant</strong> qualifier or pragma is 8473used.</p> 8474</div> 8475</div> 8476<div class="sect3"> 8477<h4 id="invariance-of-undefined-values">4.8.4. Invariance of Undefined Values</h4> 8478<div class="paragraph"> 8479<p>Undefined values are not invariant nor can they be made invariant by use of 8480the invariant qualifier or pragma. 8481In some implementations, undefined values may cause unexpected behavior if 8482they are used in control-flow expressions e.g. in the following case, one, 8483both or neither functions may be executed and this may not be consistent 8484over multiple invocations of the shader:</p> 8485</div> 8486<div class="listingblock"> 8487<div class="content"> 8488<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">int</span> x; <span class="comment">// undefined value</span> 8489<span class="keyword">if</span> (x == <span class="integer">1</span>) 8490{ 8491 f(); <span class="comment">// Undefined whether f() is executed</span> 8492} 8493<span class="keyword">if</span> (x == <span class="integer">2</span>) 8494{ 8495 g(); <span class="comment">// Undefined whether g() is executed.</span> 8496}</code></pre> 8497</div> 8498</div> 8499<div class="paragraph"> 8500<p>Note that an undefined value is a value that has not been specified. 8501A value that has been specified but has a potentially large error due to, 8502for example, lack of precision in an expression, is not undefined and so can 8503be made invariant.</p> 8504</div> 8505</div> 8506</div> 8507<div class="sect2"> 8508<h3 id="the-precise-qualifier">4.9. The Precise Qualifier</h3> 8509<div class="paragraph"> 8510<p>Some algorithms require floating-point computations to exactly follow the 8511order of operations specified in the source code and to treat all operations 8512consistently, even if the implementation supports optimizations that could 8513produce nearly equivalent results with higher performance. 8514For example, many GL implementations support a “multiply-add” instruction 8515that can compute a floating-point expression such as</p> 8516</div> 8517<div class="listingblock"> 8518<div class="content"> 8519<pre class="CodeRay highlight"><code data-lang="c++">result = (a * b) + (c * d);</code></pre> 8520</div> 8521</div> 8522<div class="paragraph"> 8523<p>in two operations instead of three operations; one multiply and one 8524multiply-add instead of two multiplies and one add. 8525The result of a floating-point multiply-add might not always be identical to 8526first doing a multiply yielding a floating-point result and then doing a 8527floating-point add. 8528Hence, in this example, the two multiply operations would not be treated 8529consistently; the two multiplies could effectively appear to have differing 8530precisions.</p> 8531</div> 8532<div class="paragraph"> 8533<p>The key computation that needs to be made consistent appears when 8534tessellating, where intermediate points for subdivision are synthesized in 8535different directions, yet need to yield the same result, as shown in the 8536diagram below.</p> 8537</div> 8538<div id="img-precise" class="imageblock"> 8539<div class="content"> 8540<img src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KCjxzdmcgdmVyc2lvbj0iMS4yIiBiYXNlUHJvZmlsZT0idGlueSIgd2lkdGg9IjIxMG1tIiBoZWlnaHQ9IjI5N21tIiB2aWV3Qm94PSIwIDAgMjEwMDAgMjk3MDAiIHByZXNlcnZlQXNwZWN0UmF0aW89InhNaWRZTWlkIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiIGNsaXAtcGF0aD0idXJsKCNwcmVzZW50YXRpb25fY2xpcF9wYXRoKSIgc3Ryb2tlLXdpZHRoPSIyOC4yMjIiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6b29vPSJodHRwOi8veG1sLm9wZW5vZmZpY2Uub3JnL3N2Zy9leHBvcnQiIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB4bWw6c3BhY2U9InByZXNlcnZlIj4KIDxkZWZzIGNsYXNzPSJDbGlwUGF0aEdyb3VwIj4KICA8Y2xpcFBhdGggaWQ9InByZXNlbnRhdGlvbl9jbGlwX3BhdGgiIGNsaXBQYXRoVW5pdHM9InVzZXJTcGFjZU9uVXNlIj4KICAgPHJlY3QgeD0iMCIgeT0iMCIgd2lkdGg9IjIxMDAwIiBoZWlnaHQ9IjI5NzAwIi8+CiAgPC9jbGlwUGF0aD4KIDwvZGVmcz4KIDxkZWZzPgogIDxmb250IGlkPSJFbWJlZGRlZEZvbnRfMSIgaG9yaXotYWR2LXg9IjIwNDgiPgogICA8Zm9udC1mYWNlIGZvbnQtZmFtaWx5PSJMaWJlcmF0aW9uIFNhbnMgZW1iZWRkZWQiIHVuaXRzLXBlci1lbT0iMjA0OCIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgZm9udC1zdHlsZT0ibm9ybWFsIiBhc2NlbnQ9IjE4NTIiIGRlc2NlbnQ9IjQyMyIvPgogICA8bWlzc2luZy1nbHlwaCBob3Jpei1hZHYteD0iMjA0OCIgZD0iTSAwLDAgTCAyMDQ3LDAgMjA0NywyMDQ3IDAsMjA0NyAwLDAgWiIvPgogICA8Z2x5cGggdW5pY29kZT0idyIgaG9yaXotYWR2LXg9IjE1MDkiIGQ9Ik0gMTE3NCwwIEwgOTY1LDAgNzkyLDY5OCBDIDc4Nyw3MTYgNzgxLDczOCA3NzYsNzY1IDc3MCw3OTIgNzY0LDgxOCA3NTksODQzIDc1Miw4NzIgNzQ2LDkwMyA3NDAsOTM0IDczNCw5MDQgNzI4LDg3NCA3MjEsODQ1IDcxNiw4MjAgNzEwLDc5MyA3MDQsNzY2IDY5Nyw3MzkgNjkxLDcxNSA2ODYsNjk0IEwgNTA4LDAgMzAwLDAgLTMsMTA4MiAxNzUsMTA4MiAzNTgsMzQ3IEMgMzYzLDMzMiAzNjcsMzEzIDM3MiwyOTEgMzc3LDI2OCAzODEsMjQ2IDM4NiwyMjUgMzkxLDIwMCAzOTYsMTc1IDQwMSwxNDkgNDA2LDE3NCA0MTIsMTk5IDQxOCwyMjMgNDIzLDI0NCA0MjksMjY1IDQzNCwyODYgNDM5LDMwNyA0NDQsMzI1IDQ0OCwzMzkgTCA2NDQsMTA4MiA4MzcsMTA4MiAxMDI2LDMzOSBDIDEwMzEsMzIyIDEwMzYsMzAyIDEwNDEsMjgwIDEwNDYsMjU4IDEwNTEsMjM3IDEwNTYsMjE4IDEwNjEsMTk1IDEwNjcsMTcyIDEwNzIsMTQ5IDEwNzcsMTc0IDEwODMsMTk5IDEwODgsMjIzIDEwOTMsMjQ0IDEwOTgsMjY1IDExMDMsMjg4IDExMDgsMzEwIDExMTIsMzMwIDExMTcsMzQ3IEwgMTMwOCwxMDgyIDE0ODQsMTA4MiAxMTc0LDAgWiIvPgogICA8Z2x5cGggdW5pY29kZT0idiIgaG9yaXotYWR2LXg9IjEwMzMiIGQ9Ik0gNjEzLDAgTCA0MDAsMCA3LDEwODIgMTk5LDEwODIgNDM3LDM3OCBDIDQ0MiwzNjMgNDQ3LDM0NiA0NTQsMzI1IDQ2MCwzMDQgNDY2LDI4MiA0NzMsMjU5IDQ4MCwyMzYgNDg2LDIxNSA0OTIsMTk0IDQ5NywxNzMgNTAyLDE1NSA1MDYsMTQxIDUxMCwxNTUgNTE1LDE3MyA1MjIsMTk0IDUyOCwyMTUgNTM0LDIzNiA1NDEsMjU4IDU0OCwyODAgNTU1LDMwMiA1NjIsMzIzIDU2OSwzNDQgNTc1LDM2MSA1ODAsMzc2IEwgODI2LDEwODIgMTAxNywxMDgyIDYxMywwIFoiLz4KICAgPGdseXBoIHVuaWNvZGU9InUiIGhvcml6LWFkdi14PSI4NzQiIGQ9Ik0gMzE0LDEwODIgTCAzMTQsMzk2IEMgMzE0LDM0MyAzMTgsMjk5IDMyNiwyNjQgMzMzLDIyOSAzNDYsMjAwIDM2MywxNzkgMzgwLDE1NyA0MDMsMTQyIDQzMiwxMzMgNDYwLDEyNCA0OTUsMTE5IDUzNywxMTkgNTgwLDExOSA2MTgsMTI3IDY1MywxNDIgNjg3LDE1NyA3MTYsMTc4IDc0MSwyMDcgNzY1LDIzNSA3ODQsMjcwIDc5NywzMTIgODEwLDM1MyA4MTcsNDAxIDgxNyw0NTUgTCA4MTcsMTA4MiA5OTcsMTA4MiA5OTcsMjMxIEMgOTk3LDIwOCA5OTcsMTg1IDk5OCwxNjAgOTk4LDEzNSA5OTgsMTExIDk5OSw4OSAxMDAwLDY2IDEwMDAsNDcgMTAwMSwzMSAxMDAyLDE1IDEwMDIsNSAxMDAzLDAgTCA4MzMsMCBDIDgzMiwzIDgzMiwxMiA4MzEsMjcgODMwLDQyIDgzMCw1OSA4MjksNzggODI4LDk3IDgyNywxMTYgODI2LDEzNiA4MjUsMTU1IDgyNSwxNzIgODI1LDE4NSBMIDgyMiwxODUgQyA4MDUsMTU0IDc4NiwxMjUgNzY1LDEwMCA3NDQsNzUgNzIwLDUzIDY5MywzNiA2NjYsMTggNjM0LDQgNTk5LC02IDU2NCwtMTUgNTIzLC0yMCA0NzYsLTIwIDQxNiwtMjAgMzY0LC0xMyAzMjEsMiAyNzgsMTcgMjQyLDM5IDIxNCw3MCAxODYsMTAxIDE2NiwxNDAgMTUzLDE4OCAxNDAsMjM2IDEzMywyOTQgMTMzLDM2MSBMIDEzMywxMDgyIDMxNCwxMDgyIFoiLz4KICAgPGdseXBoIHVuaWNvZGU9InQiIGhvcml6LWFkdi14PSI1MzEiIGQ9Ik0gNTU0LDggQyA1MjcsMSA0OTksLTUgNDcxLC0xMCA0NDIsLTE0IDQwOSwtMTYgMzcyLC0xNiAyMjgsLTE2IDE1Niw2NiAxNTYsMjI5IEwgMTU2LDk1MSAzMSw5NTEgMzEsMTA4MiAxNjMsMTA4MiAyMTYsMTMyNCAzMzYsMTMyNCAzMzYsMTA4MiA1MzYsMTA4MiA1MzYsOTUxIDMzNiw5NTEgMzM2LDI2OCBDIDMzNiwyMTYgMzQ1LDE4MCAzNjIsMTU5IDM3OSwxMzggNDA4LDEyNyA0NTAsMTI3IDQ2NywxMjcgNDg0LDEyOCA1MDEsMTMxIDUxNywxMzQgNTM1LDEzNyA1NTQsMTQxIEwgNTU0LDggWiIvPgogICA8Z2x5cGggdW5pY29kZT0icyIgaG9yaXotYWR2LXg9IjkwMSIgZD0iTSA5NTAsMjk5IEMgOTUwLDI0OCA5NDAsMjAzIDkyMSwxNjQgOTAxLDEyNCA4NzIsOTEgODM1LDY0IDc5OCwzNyA3NTIsMTYgNjk4LDIgNjQzLC0xMyA1ODEsLTIwIDUxMSwtMjAgNDQ4LC0yMCAzOTIsLTE1IDM0MiwtNiAyOTEsNCAyNDcsMjAgMjA5LDQxIDE3MSw2MiAxMzksOTEgMTE0LDEyNiA4OCwxNjEgNjksMjAzIDU3LDI1NCBMIDIxNiwyODUgQyAyMzEsMjI3IDI2MywxODUgMzExLDE1OCAzNTksMTMxIDQyNiwxMTcgNTExLDExNyA1NTAsMTE3IDU4NSwxMjAgNjE4LDEyNSA2NTAsMTMwIDY3OCwxNDAgNzAxLDE1MyA3MjQsMTY2IDc0MywxODMgNzU2LDIwNSA3NjksMjI2IDc3NSwyNTMgNzc1LDI4NSA3NzUsMzE4IDc2NywzNDUgNzUyLDM2NiA3MzcsMzg3IDcxNSw0MDQgNjg4LDQxOCA2NjEsNDMyIDYyOCw0NDQgNTg5LDQ1NSA1NTAsNDY1IDUwNyw0NzYgNDYwLDQ4OSA0MTcsNTAwIDM3NCw1MTMgMzMxLDUyNyAyODgsNTQxIDI1MCw1NjAgMjE2LDU4MyAxODEsNjA2IDE1Myw2MzQgMTMyLDY2OCAxMTEsNzAyIDEwMCw3NDUgMTAwLDc5NiAxMDAsODk1IDEzNSw5NzAgMjA2LDEwMjIgMjc2LDEwNzMgMzc4LDEwOTkgNTEzLDEwOTkgNjMyLDEwOTkgNzI3LDEwNzggNzk4LDEwMzYgODY4LDk5NCA5MTIsOTI3IDkzMSw4MzQgTCA3NjksODE0IEMgNzYzLDg0MiA3NTIsODY2IDczNiw4ODUgNzIwLDkwNCA3MDEsOTE5IDY3OCw5MzEgNjU1LDk0MiA2MzAsOTUxIDYwMiw5NTYgNTczLDk2MSA1NDQsOTYzIDUxMyw5NjMgNDMyLDk2MyAzNzIsOTUxIDMzMyw5MjYgMjk0LDkwMSAyNzUsODY0IDI3NSw4MTQgMjc1LDc4NSAyODIsNzYxIDI5Nyw3NDIgMzExLDcyMyAzMzEsNzA3IDM1Nyw2OTQgMzgyLDY4MSA0MTMsNjY5IDQ0OSw2NjAgNDg1LDY1MCA1MjUsNjQwIDU2OCw2MjkgNTk3LDYyMiA2MjYsNjE0IDY1Niw2MDYgNjg2LDU5NyA3MTUsNTg3IDc0NCw1NzYgNzcyLDU2NCA3OTksNTUwIDgyNCw1MzUgODQ5LDUxOSA4NzAsNTAwIDg4OSw0NzggOTA4LDQ1NiA5MjMsNDMwIDkzNCw0MDEgOTQ1LDM3MiA5NTAsMzM4IDk1MCwyOTkgWiIvPgogICA8Z2x5cGggdW5pY29kZT0iciIgaG9yaXotYWR2LXg9IjUzMCIgZD0iTSAxNDIsMCBMIDE0Miw4MzAgQyAxNDIsODUzIDE0Miw4NzYgMTQyLDkwMCAxNDEsOTIzIDE0MSw5NDYgMTQwLDk2OCAxMzksOTkwIDEzOSwxMDExIDEzOCwxMDMwIDEzNywxMDQ5IDEzNywxMDY3IDEzNiwxMDgyIEwgMzA2LDEwODIgQyAzMDcsMTA2NyAzMDgsMTA0OSAzMDksMTAzMCAzMTAsMTAxMCAzMTEsOTkwIDMxMiw5NjkgMzEzLDk0OCAzMTMsOTI5IDMxNCw5MTAgMzE0LDg5MSAzMTQsODc0IDMxNCw4NjEgTCAzMTgsODYxIEMgMzMxLDkwMiAzNDQsOTM4IDM1OSw5NjkgMzczLDk5OSAzOTAsMTAyNCA0MDksMTA0NCA0MjgsMTA2MyA0NTEsMTA3OCA0NzgsMTA4OCA1MDUsMTA5NyA1MzcsMTEwMiA1NzUsMTEwMiA1OTAsMTEwMiA2MDQsMTEwMSA2MTcsMTA5OSA2MzAsMTA5NiA2NDEsMTA5NCA2NDgsMTA5MiBMIDY0OCw5MjcgQyA2MzYsOTMwIDYyMiw5MzMgNjA2LDkzNSA1OTAsOTM2IDU3Miw5MzcgNTUyLDkzNyA1MTEsOTM3IDQ3Niw5MjggNDQ3LDkwOSA0MTgsODkwIDM5NCw4NjUgMzc2LDgzMiAzNTcsNzk5IDM0NCw3NTkgMzM1LDcxNCAzMjYsNjY4IDMyMiw2MTggMzIyLDU2NCBMIDMyMiwwIDE0MiwwIFoiLz4KICAgPGdseXBoIHVuaWNvZGU9InAiIGhvcml6LWFkdi14PSI5NTMiIGQ9Ik0gMTA1Myw1NDYgQyAxMDUzLDQ2NCAxMDQ2LDM4OCAxMDMzLDMxOSAxMDIwLDI1MCA5OTgsMTkwIDk2NywxNDAgOTM2LDkwIDg5NSw1MSA4NDQsMjMgNzkzLC02IDczMCwtMjAgNjU1LC0yMCA1NzgsLTIwIDUxMCwtNSA0NTIsMjQgMzk0LDUzIDM1MCwxMDEgMzE5LDE2OCBMIDMxNCwxNjggQyAzMTUsMTY3IDMxNSwxNjEgMzE2LDE1MCAzMTYsMTM5IDMxNiwxMjYgMzE3LDExMCAzMTcsOTQgMzE3LDc2IDMxOCw1NyAzMTgsMzcgMzE4LDE3IDMxOCwtMiBMIDMxOCwtNDI1IDEzOCwtNDI1IDEzOCw4NjEgQyAxMzgsODg3IDEzOCw5MTIgMTM4LDkzNiAxMzcsOTYwIDEzNyw5ODIgMTM2LDEwMDIgMTM1LDEwMjEgMTM1LDEwMzggMTM0LDEwNTIgMTMzLDEwNjYgMTMzLDEwNzYgMTMyLDEwODIgTCAzMDYsMTA4MiBDIDMwNywxMDgwIDMwOCwxMDczIDMwOSwxMDYxIDMxMCwxMDQ5IDMxMSwxMDM1IDMxMiwxMDE4IDMxMywxMDAxIDMxNCw5ODIgMzE1LDk2MyAzMTYsOTQ0IDMxNiw5MjUgMzE2LDkwOCBMIDMyMCw5MDggQyAzMzcsOTQzIDM1Niw5NzIgMzc3LDk5NyAzOTgsMTAyMSA0MjMsMTA0MSA0NTAsMTA1NyA0NzcsMTA3MiA1MDgsMTA4NCA1NDIsMTA5MSA1NzUsMTA5OCA2MTMsMTEwMSA2NTUsMTEwMSA3MzAsMTEwMSA3OTMsMTA4OCA4NDQsMTA2MSA4OTUsMTAzNCA5MzYsOTk3IDk2Nyw5NDkgOTk4LDkwMCAxMDIwLDg0MiAxMDMzLDc3NCAxMDQ2LDcwNSAxMDUzLDYyOSAxMDUzLDU0NiBaIE0gODY0LDU0MiBDIDg2NCw2MDkgODYwLDY2OCA4NTIsNzIwIDg0NCw3NzIgODMwLDgxNiA4MTEsODUyIDc5MSw4ODggNzY1LDkxNSA3MzIsOTM0IDY5OSw5NTMgNjU4LDk2MiA2MDksOTYyIDU2OSw5NjIgNTMxLDk1NiA0OTYsOTQ1IDQ2MSw5MzQgNDMwLDkxMiA0MDQsODgwIDM3Nyw4NDggMzU2LDgwNCAzNDEsNzQ4IDMyNiw2OTEgMzE4LDYxOCAzMTgsNTI4IDMxOCw0NTEgMzI0LDM4NyAzMzcsMzM0IDM1MCwyODEgMzY4LDIzOCAzOTMsMjA1IDQxNywxNzIgNDQ3LDE0OSA0ODMsMTM1IDUxOSwxMjAgNTYwLDExMyA2MDcsMTEzIDY1NywxMTMgNjk5LDEyMyA3MzIsMTQyIDc2NSwxNjEgNzkxLDE4OSA4MTEsMjI2IDgzMCwyNjMgODQ0LDMwOCA4NTIsMzYxIDg2MCw0MTQgODY0LDQ3NCA4NjQsNTQyIFoiLz4KICAgPGdseXBoIHVuaWNvZGU9Im8iIGhvcml6LWFkdi14PSI5ODAiIGQ9Ik0gMTA1Myw1NDIgQyAxMDUzLDM1MyAxMDExLDIxMiA5MjgsMTE5IDg0NSwyNiA3MjQsLTIwIDU2NSwtMjAgNDkwLC0yMCA0MjIsLTkgMzYzLDE0IDMwNCwzNyAyNTQsNzEgMjEzLDExOCAxNzIsMTY1IDE0MCwyMjMgMTE5LDI5NCA5NywzNjQgODYsNDQ3IDg2LDU0MiA4Niw5MTUgMjQ4LDExMDIgNTcxLDExMDIgNjU1LDExMDIgNzI4LDEwOTAgNzg5LDEwNjcgODUwLDEwNDQgOTAwLDEwMDkgOTM5LDk2MiA5NzgsOTE1IDEwMDYsODU3IDEwMjUsNzg3IDEwNDQsNzE3IDEwNTMsNjM1IDEwNTMsNTQyIFogTSA4NjQsNTQyIEMgODY0LDYyNiA4NTgsNjk1IDg0NSw3NTAgODMyLDgwNSA4MTMsODQ4IDc4OCw4ODEgNzYzLDkxNCA3MzIsOTM3IDY5Niw5NTAgNjYwLDk2MyA2MTksOTY5IDU3NCw5NjkgNTI4LDk2OSA0ODcsOTYyIDQ1MCw5NDkgNDEzLDkzNSAzODEsOTEyIDM1NSw4NzkgMzI5LDg0NiAzMDksODAyIDI5Niw3NDcgMjgyLDY5MiAyNzUsNjI0IDI3NSw1NDIgMjc1LDQ1OCAyODIsMzg5IDI5NywzMzQgMzEyLDI3OSAzMzIsMjM1IDM1OCwyMDIgMzgzLDE2OSA0MTQsMTQ2IDQ0OSwxMzMgNDg0LDEyMCA1MjIsMTEzIDU2MywxMTMgNjA5LDExMyA2NTEsMTIwIDY4OCwxMzMgNzI1LDE0NiA3NTcsMTY4IDc4MywyMDEgODA5LDIzNCA4MjksMjc4IDg0MywzMzMgODU3LDM4OCA4NjQsNDU4IDg2NCw1NDIgWiIvPgogICA8Z2x5cGggdW5pY29kZT0ibiIgaG9yaXotYWR2LXg9Ijg3NCIgZD0iTSA4MjUsMCBMIDgyNSw2ODYgQyA4MjUsNzM5IDgyMSw3ODMgODE0LDgxOCA4MDYsODUzIDc5Myw4ODIgNzc2LDkwNCA3NTksOTI1IDczNiw5NDEgNzA4LDk1MCA2NzksOTU5IDY0NCw5NjMgNjAyLDk2MyA1NTksOTYzIDUyMSw5NTYgNDg3LDk0MSA0NTIsOTI2IDQyMyw5MDQgMzk5LDg3NiAzNzQsODQ3IDM1NSw4MTIgMzQyLDc3MSAzMjksNzI5IDMyMiw2ODEgMzIyLDYyNyBMIDMyMiwwIDE0MiwwIDE0Miw4NTEgQyAxNDIsODc0IDE0Miw4OTggMTQyLDkyMyAxNDEsOTQ4IDE0MSw5NzEgMTQwLDk5NCAxMzksMTAxNiAxMzksMTAzNSAxMzgsMTA1MSAxMzcsMTA2NyAxMzcsMTA3NyAxMzYsMTA4MiBMIDMwNiwxMDgyIEMgMzA3LDEwNzkgMzA3LDEwNzAgMzA4LDEwNTUgMzA5LDEwNDAgMzEwLDEwMjQgMzExLDEwMDUgMzEyLDk4NiAzMTIsOTY2IDMxMyw5NDcgMzE0LDkyNyAzMTQsOTEwIDMxNCw4OTcgTCAzMTcsODk3IEMgMzM0LDkyOCAzNTMsOTU3IDM3NCw5ODIgMzk1LDEwMDcgNDE5LDEwMjkgNDQ2LDEwNDcgNDczLDEwNjQgNTA1LDEwNzggNTQwLDEwODggNTc1LDEwOTcgNjE2LDExMDIgNjYzLDExMDIgNzIzLDExMDIgNzc1LDEwOTUgODE4LDEwODAgODYxLDEwNjUgODk3LDEwNDMgOTI1LDEwMTIgOTUzLDk4MSA5NzQsOTQyIDk4Nyw4OTQgMTAwMCw4NDUgMTAwNiw3ODggMTAwNiw3MjEgTCAxMDA2LDAgODI1LDAgWiIvPgogICA8Z2x5cGggdW5pY29kZT0ibSIgaG9yaXotYWR2LXg9IjE0NTciIGQ9Ik0gNzY4LDAgTCA3NjgsNjg2IEMgNzY4LDczOSA3NjUsNzgzIDc1OCw4MTggNzUxLDg1MyA3NDAsODgyIDcyNSw5MDQgNzA5LDkyNSA2ODgsOTQxIDY2Myw5NTAgNjM4LDk1OSA2MDcsOTYzIDU3MCw5NjMgNTMyLDk2MyA0OTgsOTU2IDQ2Nyw5NDEgNDM2LDkyNiA0MTAsOTA0IDM4OSw4NzYgMzY3LDg0NyAzNTAsODEyIDMzOSw3NzEgMzI3LDcyOSAzMjEsNjgxIDMyMSw2MjcgTCAzMjEsMCAxNDIsMCAxNDIsODUxIEMgMTQyLDg3NCAxNDIsODk4IDE0Miw5MjMgMTQxLDk0OCAxNDEsOTcxIDE0MCw5OTQgMTM5LDEwMTYgMTM5LDEwMzUgMTM4LDEwNTEgMTM3LDEwNjcgMTM3LDEwNzcgMTM2LDEwODIgTCAzMDYsMTA4MiBDIDMwNywxMDc5IDMwNywxMDcwIDMwOCwxMDU1IDMwOSwxMDQwIDMxMCwxMDI0IDMxMSwxMDA1IDMxMiw5ODYgMzEyLDk2NiAzMTMsOTQ3IDMxNCw5MjcgMzE0LDkxMCAzMTQsODk3IEwgMzE3LDg5NyBDIDMzMyw5MjggMzUwLDk1NyAzNjksOTgyIDM4OCwxMDA3IDQxMCwxMDI5IDQzNSwxMDQ3IDQ2MCwxMDY0IDQ4OCwxMDc4IDUyMSwxMDg4IDU1MywxMDk3IDU5MCwxMTAyIDYzMywxMTAyIDcxNSwxMTAyIDc4MCwxMDg2IDgyOCwxMDUzIDg3NSwxMDIwIDkwOCw5NjggOTI3LDg5NyBMIDkzMCw4OTcgQyA5NDYsOTI4IDk2NCw5NTcgOTg0LDk4MiAxMDA0LDEwMDcgMTAyNywxMDI5IDEwNTQsMTA0NyAxMDgxLDEwNjQgMTExMSwxMDc4IDExNDQsMTA4OCAxMTc3LDEwOTcgMTIxNSwxMTAyIDEyNTgsMTEwMiAxMzEzLDExMDIgMTM2MCwxMDk1IDE0MDAsMTA4MCAxNDM5LDEwNjUgMTQ3MiwxMDQzIDE0OTcsMTAxMiAxNTIyLDk4MSAxNTQxLDk0MiAxNTUzLDg5NCAxNTY1LDg0NSAxNTcxLDc4OCAxNTcxLDcyMSBMIDE1NzEsMCAxMzkzLDAgMTM5Myw2ODYgQyAxMzkzLDczOSAxMzkwLDc4MyAxMzgzLDgxOCAxMzc2LDg1MyAxMzY1LDg4MiAxMzUwLDkwNCAxMzM0LDkyNSAxMzEzLDk0MSAxMjg4LDk1MCAxMjYzLDk1OSAxMjMyLDk2MyAxMTk1LDk2MyAxMTU3LDk2MyAxMTIzLDk1NiAxMDkyLDk0MiAxMDYxLDkyNyAxMDM1LDkwNiAxMDE0LDg3OCA5OTIsODUwIDk3NSw4MTUgOTY0LDc3MyA5NTIsNzMxIDk0Niw2ODIgOTQ2LDYyNyBMIDk0NiwwIDc2OCwwIFoiLz4KICAgPGdseXBoIHVuaWNvZGU9ImwiIGhvcml6LWFkdi14PSIxODciIGQ9Ik0gMTM4LDAgTCAxMzgsMTQ4NCAzMTgsMTQ4NCAzMTgsMCAxMzgsMCBaIi8+CiAgIDxnbHlwaCB1bmljb2RlPSJrIiBob3Jpei1hZHYteD0iOTAxIiBkPSJNIDgxNiwwIEwgNDUwLDQ5NCAzMTgsMzg1IDMxOCwwIDEzOCwwIDEzOCwxNDg0IDMxOCwxNDg0IDMxOCw1NTcgNzkzLDEwODIgMTAwNCwxMDgyIDU2NSw2MTcgMTAyNywwIDgxNiwwIFoiLz4KICAgPGdseXBoIHVuaWNvZGU9ImkiIGhvcml6LWFkdi14PSIxODciIGQ9Ik0gMTM3LDEzMTIgTCAxMzcsMTQ4NCAzMTcsMTQ4NCAzMTcsMTMxMiAxMzcsMTMxMiBaIE0gMTM3LDAgTCAxMzcsMTA4MiAzMTcsMTA4MiAzMTcsMCAxMzcsMCBaIi8+CiAgIDxnbHlwaCB1bmljb2RlPSJoIiBob3Jpei1hZHYteD0iODc0IiBkPSJNIDMxNyw4OTcgQyAzMzcsOTM0IDM1OSw5NjUgMzgyLDk5MSA0MDUsMTAxNiA0MzEsMTAzNyA0NTksMTA1NCA0ODcsMTA3MSA1MTgsMTA4MyA1NTEsMTA5MSA1ODQsMTA5OCA2MjIsMTEwMiA2NjMsMTEwMiA3MzIsMTEwMiA3ODksMTA5MyA4MzQsMTA3NCA4NzgsMTA1NSA5MTMsMTAyOSA5MzksOTk2IDk2NCw5NjIgOTgyLDkyMiA5OTIsODc1IDEwMDEsODI4IDEwMDYsNzc3IDEwMDYsNzIxIEwgMTAwNiwwIDgyNSwwIDgyNSw2ODYgQyA4MjUsNzMyIDgyMiw3NzIgODE3LDgwNyA4MTEsODQyIDgwMCw4NzEgNzg0LDg5NCA3NjgsOTE3IDc0NSw5MzQgNzE2LDk0NiA2ODcsOTU3IDY0OSw5NjMgNjAyLDk2MyA1NTksOTYzIDUyMSw5NTUgNDg3LDk0MCA0NTIsOTI1IDQyMyw5MDMgMzk5LDg3NSAzNzQsODQ3IDM1NSw4MTMgMzQyLDc3MyAzMjksNzMzIDMyMiw2ODggMzIyLDYzOCBMIDMyMiwwIDE0MiwwIDE0MiwxNDg0IDMyMiwxNDg0IDMyMiwxMDk4IEMgMzIyLDEwNzYgMzIyLDEwNTQgMzIxLDEwMzIgMzIwLDEwMTAgMzIwLDk5MCAzMTksOTcxIDMxOCw5NTIgMzE3LDkzNyAzMTYsOTI0IDMxNSw5MTEgMzE1LDkwMiAzMTQsODk3IEwgMzE3LDg5NyBaIi8+CiAgIDxnbHlwaCB1bmljb2RlPSJnIiBob3Jpei1hZHYteD0iOTI3IiBkPSJNIDU0OCwtNDI1IEMgNDg2LC00MjUgNDMxLC00MTkgMzgzLC00MDYgMzM1LC0zOTMgMjk0LC0zNzUgMjYwLC0zNTIgMjI2LC0zMjggMTk4LC0zMDAgMTc3LC0yNjcgMTU2LC0yMzQgMTQwLC0xOTggMTMxLC0xNTggTCAzMTIsLTEzMiBDIDMyNCwtMTgyIDM1MSwtMjIwIDM5MiwtMjQ4IDQzMywtMjc0IDQ4NiwtMjg4IDU1MywtMjg4IDU5NCwtMjg4IDYzMSwtMjgyIDY2NCwtMjcxIDY5NywtMjYwIDcyNiwtMjQxIDc0OSwtMjE3IDc3MiwtMTkxIDc5MCwtMTU5IDgwMywtMTE5IDgxNiwtNzkgODIyLC0zMCA4MjIsMjcgTCA4MjIsMjAxIDgyMCwyMDEgQyA4MDcsMTc0IDc5MCwxNDggNzcxLDEyMyA3NTEsOTggNzI3LDc1IDY5OSw1NiA2NzAsMzcgNjM3LDIxIDYwMCwxMCA1NjMsLTIgNTIwLC04IDQ3MiwtOCA0MDMsLTggMzQ1LDQgMjk2LDI3IDI0Nyw1MCAyMDcsODQgMTc2LDEzMCAxNDUsMTc2IDEyMiwyMzMgMTA4LDMwMiA5MywzNzAgODYsNDQ5IDg2LDUzOSA4Niw2MjYgOTMsNzA0IDEwOCw3NzMgMTIyLDg0MiAxNDUsOTAxIDE3OCw5NTAgMjEwLDk5OCAyNTIsMTAzNSAzMDQsMTA2MSAzNTUsMTA4NiA0MTgsMTA5OSA0OTIsMTA5OSA1NjksMTA5OSA2MzUsMTA4MiA2OTIsMTA0NyA3NDgsMTAxMiA3OTEsOTYyIDgyMiw4OTcgTCA4MjQsODk3IEMgODI0LDkxNCA4MjUsOTMyIDgyNiw5NTMgODI3LDk3NCA4MjgsOTkzIDgyOSwxMDEyIDgzMCwxMDMwIDgzMSwxMDQ2IDgzMiwxMDU5IDgzMywxMDcyIDgzNSwxMDgwIDgzNiwxMDgyIEwgMTAwNywxMDgyIEMgMTAwNiwxMDc2IDEwMDYsMTA2NiAxMDA1LDEwNTIgMTAwNCwxMDM3IDEwMDQsMTAyMCAxMDAzLDEwMDAgMTAwMiw5ODAgMTAwMiw5NTggMTAwMiw5MzQgMTAwMSw5MDkgMTAwMSw4ODQgMTAwMSw4NTggTCAxMDAxLDMxIEMgMTAwMSwtMTIwIDk2NCwtMjM0IDg5MCwtMzExIDgxNSwtMzg3IDcwMSwtNDI1IDU0OCwtNDI1IFogTSA4MjIsNTQxIEMgODIyLDYxNiA4MTQsNjgxIDc5OCw3MzUgNzgxLDc4OCA3NjAsODMyIDczMyw4NjYgNzA2LDkwMCA2NzYsOTI1IDY0Miw5NDEgNjA3LDk1NyA1NzIsOTY1IDUzNiw5NjUgNDkwLDk2NSA0NTEsOTU3IDQxOCw5NDEgMzg1LDkyNSAzNTcsOTAwIDMzNiw4NjYgMzE0LDgzMSAyOTgsNzg3IDI4OCw3MzQgMjc3LDY4MCAyNzIsNjE2IDI3Miw1NDEgMjcyLDQ2MyAyNzcsMzk4IDI4OCwzNDUgMjk4LDI5MiAzMTQsMjQ5IDMzNSwyMTYgMzU2LDE4MyAzODMsMTYwIDQxNiwxNDYgNDQ5LDEzMiA0ODgsMTI1IDUzMywxMjUgNTY5LDEyNSA2MDQsMTMzIDYzOSwxNDggNjczLDE2MyA3MDQsMTg4IDczMSwyMjEgNzU4LDI1NCA3ODAsMjk3IDc5NywzNTAgODE0LDQwMyA4MjIsNDY2IDgyMiw1NDEgWiIvPgogICA8Z2x5cGggdW5pY29kZT0iZiIgaG9yaXotYWR2LXg9IjU1NyIgZD0iTSAzNjEsOTUxIEwgMzYxLDAgMTgxLDAgMTgxLDk1MSAyOSw5NTEgMjksMTA4MiAxODEsMTA4MiAxODEsMTIwNCBDIDE4MSwxMjQzIDE4NSwxMjgwIDE5MiwxMzE0IDE5OSwxMzQ3IDIxMywxMzc3IDIzMywxNDAyIDI1MiwxNDI3IDI3OSwxNDQ2IDMxMywxNDYxIDM0NywxNDc1IDM5MSwxNDgyIDQ0NSwxNDgyIDQ2NiwxNDgyIDQ4OSwxNDgxIDUxMiwxNDc5IDUzNSwxNDc3IDU1NSwxNDc0IDU3MiwxNDcwIEwgNTcyLDEzMzMgQyA1NjEsMTMzNSA1NDgsMTMzNyA1MzMsMTMzOSA1MTgsMTM0MCA1MDQsMTM0MSA0OTIsMTM0MSA0NjUsMTM0MSA0NDQsMTMzNyA0MjcsMTMzMCA0MTAsMTMyMyAzOTYsMTMxMiAzODcsMTI5OSAzNzcsMTI4NSAzNzAsMTI2OCAzNjcsMTI0OCAzNjMsMTIyOCAzNjEsMTIwNSAzNjEsMTE3OSBMIDM2MSwxMDgyIDU3MiwxMDgyIDU3Miw5NTEgMzYxLDk1MSBaIi8+CiAgIDxnbHlwaCB1bmljb2RlPSJlIiBob3Jpei1hZHYteD0iOTgwIiBkPSJNIDI3Niw1MDMgQyAyNzYsNDQ2IDI4MiwzOTQgMjk0LDM0NyAzMDUsMjk5IDMyMywyNTggMzQ4LDIyNCAzNzIsMTg5IDQwMywxNjMgNDQxLDE0NCA0NzksMTI1IDUyNSwxMTUgNTc4LDExNSA2NTYsMTE1IDcxOSwxMzEgNzY2LDE2MiA4MTMsMTkzIDg0NCwyMzMgODYxLDI4MSBMIDEwMTksMjM2IEMgMTAwOCwyMDYgOTkyLDE3NiA5NzIsMTQ2IDk1MSwxMTUgOTI0LDg4IDg5MCw2NCA4NTYsMzkgODE0LDE5IDc2Myw0IDcxMiwtMTIgNjUwLC0yMCA1NzgsLTIwIDQxOCwtMjAgMjk2LDI4IDIxMywxMjMgMTI5LDIxOCA4NywzNjAgODcsNTQ4IDg3LDY0OSAxMDAsNzM1IDEyNSw4MDYgMTUwLDg3NiAxODUsOTMzIDIyOSw5NzcgMjczLDEwMjEgMzI0LDEwNTMgMzgzLDEwNzMgNDQyLDEwOTIgNTA0LDExMDIgNTcxLDExMDIgNjYyLDExMDIgNzM4LDEwODcgNzk5LDEwNTggODYwLDEwMjkgOTA5LDk4OCA5NDYsOTM3IDk4Myw4ODUgMTAwOSw4MjQgMTAyNSw3NTQgMTA0MCw2ODQgMTA0OCw2MDggMTA0OCw1MjcgTCAxMDQ4LDUwMyAyNzYsNTAzIFogTSA4NjIsNjQxIEMgODUyLDc1NSA4MjMsODM4IDc3NSw4OTEgNzI3LDk0MyA2NTgsOTY5IDU2OCw5NjkgNTM4LDk2OSA1MDcsOTY0IDQ3NCw5NTUgNDQxLDk0NSA0MTAsOTI4IDM4Miw5MDMgMzU0LDg3OCAzMzAsODQ1IDMxMSw4MDMgMjkyLDc2MCAyODEsNzA2IDI3OCw2NDEgTCA4NjIsNjQxIFoiLz4KICAgPGdseXBoIHVuaWNvZGU9ImQiIGhvcml6LWFkdi14PSI5MjciIGQ9Ik0gODIxLDE3NCBDIDc4OCwxMDUgNzQ0LDU1IDY4OSwyNSA2MzQsLTUgNTY1LC0yMCA0ODQsLTIwIDM0NywtMjAgMjQ3LDI2IDE4MywxMTggMTE4LDIxMCA4NiwzNDkgODYsNTM2IDg2LDkxMyAyMTksMTEwMiA0ODQsMTEwMiA1NjYsMTEwMiA2MzQsMTA4NyA2ODksMTA1NyA3NDQsMTAyNyA3ODgsOTc5IDgyMSw5MTQgTCA4MjMsOTE0IEMgODIzLDkyMSA4MjMsOTMxIDgyMyw5NDYgODIyLDk2MCA4MjIsOTc1IDgyMiw5OTEgODIxLDEwMDYgODIxLDEwMjEgODIxLDEwMzUgODIxLDEwNDkgODIxLDEwNTkgODIxLDEwNjUgTCA4MjEsMTQ4NCAxMDAxLDE0ODQgMTAwMSwyMjMgQyAxMDAxLDE5NyAxMDAxLDE3MiAxMDAyLDE0OCAxMDAyLDEyNCAxMDAyLDEwMiAxMDAzLDgyIDEwMDQsNjIgMTAwNCw0NSAxMDA1LDMxIDEwMDYsMTYgMTAwNiw2IDEwMDcsMCBMIDgzNSwwIEMgODM0LDcgODMzLDE2IDgzMiwyOSA4MzEsNDEgODMwLDU1IDgyOSw3MSA4MjgsODcgODI3LDEwNCA4MjYsMTIyIDgyNSwxMzkgODI1LDE1NyA4MjUsMTc0IEwgODIxLDE3NCBaIE0gMjc1LDU0MiBDIDI3NSw0NjcgMjgwLDQwMyAyODksMzUwIDI5OCwyOTcgMzEzLDI1MyAzMzQsMjE5IDM1NSwxODQgMzgxLDE1OSA0MTMsMTQzIDQ0NSwxMjcgNDg0LDExOSA1MzAsMTE5IDU3NywxMTkgNjE5LDEyNyA2NTYsMTQyIDY5MiwxNTcgNzIyLDE4MiA3NDcsMjE3IDc3MSwyNTEgNzg5LDI5NiA4MDIsMzUxIDgxNSw0MDYgODIxLDQ3NCA4MjEsNTU0IDgyMSw2MzEgODE1LDY5NiA4MDIsNzQ5IDc4OSw4MDIgNzcxLDg0NCA3NDYsODc3IDcyMSw5MTAgNjkxLDkzMyA2NTYsOTQ4IDYyMCw5NjIgNTc5LDk2OSA1MzIsOTY5IDQ4OCw5NjkgNDUwLDk2MSA0MTgsOTQ2IDM4Niw5MzEgMzU5LDkwNiAzMzgsODcyIDMxNyw4MzggMzAxLDc5NCAyOTEsNzQwIDI4MCw2ODUgMjc1LDYxOSAyNzUsNTQyIFoiLz4KICAgPGdseXBoIHVuaWNvZGU9ImMiIGhvcml6LWFkdi14PSI5MDEiIGQ9Ik0gMjc1LDU0NiBDIDI3NSw0ODQgMjgwLDQyNyAyODksMzc1IDI5OCwzMjMgMzEzLDI3OCAzMzQsMjQxIDM1NSwyMDMgMzg0LDE3NCA0MTksMTUzIDQ1NCwxMzIgNDk3LDEyMiA1NDgsMTIyIDYxMiwxMjIgNjY2LDEzOSA3MDksMTczIDc1MiwyMDYgNzc4LDI1OCA3ODgsMzI4IEwgOTcwLDMyOCBDIDk2NCwyODMgOTUxLDIzOSA5MzEsMTk3IDkxMSwxNTUgODg0LDExOCA4NTAsODYgODE1LDU0IDc3MywyOCA3MjQsOSA2NzUsLTEwIDYxOCwtMjAgNTUzLC0yMCA0NjgsLTIwIDM5NiwtNiAzMzcsMjMgMjc4LDUyIDIzMCw5MSAxOTMsMTQyIDE1NiwxOTIgMTI5LDI1MSAxMTIsMzIwIDk1LDM4OCA4Nyw0NjIgODcsNTQyIDg3LDYxNSA5Myw2NzkgMTA1LDczNSAxMTcsNzkwIDEzNCw4MzkgMTU2LDg4MSAxNzcsOTIyIDIwMyw5NTcgMjMyLDk4NiAyNjEsMTAxNCAyOTMsMTAzNyAzMjgsMTA1NCAzNjIsMTA3MSAzOTgsMTA4MyA0MzYsMTA5MSA0NzQsMTA5OCA1MTIsMTEwMiA1NTEsMTEwMiA2MTIsMTEwMiA2NjYsMTA5NCA3MTMsMTA3NyA3NjAsMTA2MCA4MDEsMTAzOCA4MzYsMTAwOSA4NzAsOTgwIDg5OCw5NDUgOTE5LDkwNiA5NDAsODY3IDk1NSw4MjQgOTY0LDc3OSBMIDc3OSw3NjUgQyA3NzAsODI1IDc0Niw4NzMgNzA4LDkwOCA2NzAsOTQzIDYxNiw5NjEgNTQ2LDk2MSA0OTUsOTYxIDQ1Miw5NTMgNDE4LDkzNiAzODMsOTE5IDM1NSw4OTMgMzM0LDg1OSAzMTMsODI0IDI5OCw3ODEgMjg5LDcyOSAyODAsNjc3IDI3NSw2MTYgMjc1LDU0NiBaIi8+CiAgIDxnbHlwaCB1bmljb2RlPSJiIiBob3Jpei1hZHYteD0iOTUzIiBkPSJNIDEwNTMsNTQ2IEMgMTA1MywxNjkgOTIwLC0yMCA2NTUsLTIwIDU3MywtMjAgNTA1LC01IDQ1MSwyNSAzOTYsNTQgMzUyLDEwMiAzMTgsMTY4IEwgMzE2LDE2OCBDIDMxNiwxNTEgMzE2LDEzMyAzMTUsMTE0IDMxNCw5NSAzMTMsNzggMzEyLDYyIDMxMSw0NiAzMTAsMzIgMzA5LDIxIDMwOCwxMCAzMDcsMyAzMDYsMCBMIDEzMiwwIEMgMTMzLDYgMTMzLDE2IDEzNCwzMSAxMzUsNDUgMTM1LDYyIDEzNiw4MiAxMzcsMTAyIDEzNywxMjQgMTM4LDE0OCAxMzgsMTcyIDEzOCwxOTcgMTM4LDIyMyBMIDEzOCwxNDg0IDMxOCwxNDg0IDMxOCwxMDYxIEMgMzE4LDEwNDEgMzE4LDEwMjIgMzE4LDEwMDQgMzE3LDk4NSAzMTcsOTY5IDMxNiw5NTUgMzE1LDkzOCAzMTUsOTIzIDMxNCw5MDggTCAzMTgsOTA4IEMgMzUxLDk3NyAzOTYsMTAyNyA0NTEsMTA1NyA1MDYsMTA4NyA1NzQsMTEwMiA2NTUsMTEwMiA3OTIsMTEwMiA4OTIsMTA1NiA5NTcsOTY0IDEwMjEsODcyIDEwNTMsNzMzIDEwNTMsNTQ2IFogTSA4NjQsNTQwIEMgODY0LDYxNSA4NTksNjc5IDg1MCw3MzIgODQxLDc4NSA4MjYsODI5IDgwNSw4NjQgNzg0LDg5OCA3NTgsOTIzIDcyNiw5MzkgNjk0LDk1NSA2NTUsOTYzIDYwOSw5NjMgNTYyLDk2MyA1MjAsOTU1IDQ4NCw5NDAgNDQ3LDkyNSA0MTcsOTAwIDM5Myw4NjYgMzY4LDgzMiAzNTAsNzg3IDMzNyw3MzIgMzI0LDY3NyAzMTgsNjA5IDMxOCw1MjkgMzE4LDQ1MiAzMjQsMzg3IDMzNywzMzQgMzUwLDI4MSAzNjgsMjM5IDM5MywyMDYgNDE3LDE3MyA0NDcsMTQ5IDQ4MywxMzUgNTE5LDEyMCA1NjAsMTEzIDYwNywxMTMgNjUxLDExMyA2ODksMTIxIDcyMSwxMzYgNzUzLDE1MSA3ODAsMTc2IDgwMSwyMTAgODIyLDI0NCA4MzgsMjg4IDg0OSwzNDMgODU5LDM5NyA4NjQsNDYzIDg2NCw1NDAgWiIvPgogICA8Z2x5cGggdW5pY29kZT0iYSIgaG9yaXotYWR2LXg9IjEwNjAiIGQ9Ik0gNDE0LC0yMCBDIDMwNSwtMjAgMjI0LDkgMTY5LDY2IDExNCwxMjQgODcsMjAzIDg3LDMwMyA4NywzNzUgMTAxLDQzNCAxMjgsNDgwIDE1NSw1MjYgMTkwLDU2MiAyMzQsNTg4IDI3Nyw2MTQgMzI3LDYzMiAzODMsNjQyIDQzOSw2NTIgNDk2LDY1NyA1NTQsNjU3IEwgNzk3LDY1NyA3OTcsNzE3IEMgNzk3LDc2MiA3OTIsODAwIDc4Myw4MzIgNzc0LDg2MyA3NTksODg5IDc0MCw5MDggNzIxLDkyOCA2OTcsOTQyIDY2OCw5NTEgNjM5LDk2MCA2MDQsOTY1IDU2NSw5NjUgNTMwLDk2NSA0OTksOTYzIDQ3MSw5NTggNDQzLDk1MyA0MTksOTQ0IDM5OCw5MzEgMzc3LDkxOCAzNjEsOTAwIDM0OCw4NzggMzM1LDg1NSAzMjcsODI3IDMyMyw3OTMgTCAxMzUsODEwIEMgMTQyLDg1MyAxNTQsODkyIDE3Myw5MjggMTkyLDk2MyAyMTgsOTk0IDI1MywxMDIwIDI4NywxMDQ2IDMzMCwxMDY2IDM4MiwxMDgxIDQzMywxMDk1IDQ5NiwxMTAyIDU2OSwxMTAyIDcwNSwxMTAyIDgwNywxMDcxIDg3NiwxMDA5IDk0NSw5NDYgOTc5LDg1NiA5NzksNzM4IEwgOTc5LDI3MiBDIDk3OSwyMTkgOTg2LDE3OSAxMDAwLDE1MiAxMDE0LDEyNSAxMDQxLDExMSAxMDgwLDExMSAxMDkwLDExMSAxMTAwLDExMiAxMTEwLDExMyAxMTIwLDExNCAxMTMwLDExNiAxMTM5LDExOCBMIDExMzksNiBDIDExMTYsMSAxMDk0LC0zIDEwNzIsLTYgMTA0OSwtOSAxMDI1LC0xMCAxMDAwLC0xMCA5NjYsLTEwIDkzNywtNSA5MTMsNCA4ODgsMTMgODY4LDI2IDg1Myw0NSA4MzgsNjMgODI2LDg2IDgxOCwxMTMgODEwLDE0MCA4MDUsMTcxIDgwMywyMDcgTCA3OTcsMjA3IEMgNzc4LDE3MiA3NTcsMTQxIDczNCwxMTMgNzExLDg1IDY4NCw2MSA2NTMsNDIgNjIyLDIyIDU4OCw3IDU0OSwtNCA1MTAsLTE1IDQ2NSwtMjAgNDE0LC0yMCBaIE0gNDU1LDExNSBDIDUxMiwxMTUgNTYzLDEyNSA2MDYsMTQ2IDY0OSwxNjcgNjg0LDE5NCA3MTMsMjI2IDc0MSwyNTkgNzYyLDI5NCA3NzYsMzMyIDc5MCwzNzEgNzk3LDQwOCA3OTcsNDQzIEwgNzk3LDUzMSA2MDAsNTMxIEMgNTU2LDUzMSA1MTQsNTI4IDQ3NSw1MjIgNDM1LDUxNyA0MDAsNTA2IDM3MCw0ODkgMzQwLDQ3MiAzMTYsNDQ5IDI5OSw0MTggMjgxLDM4OCAyNzIsMzQ5IDI3MiwzMDAgMjcyLDI0MSAyODgsMTk1IDMyMCwxNjMgMzUxLDEzMSAzOTYsMTE1IDQ1NSwxMTUgWiIvPgogICA8Z2x5cGggdW5pY29kZT0iUyIgaG9yaXotYWR2LXg9IjExOTIiIGQ9Ik0gMTI3MiwzODkgQyAxMjcyLDMzMCAxMjYxLDI3NSAxMjM4LDIyNSAxMjE1LDE3NSAxMTc5LDEzMiAxMTMxLDk2IDEwODMsNTkgMTAyMywzMSA5NTAsMTEgODc3LC0xMCA3OTAsLTIwIDY5MCwtMjAgNTE1LC0yMCAzNzgsMTEgMjgwLDcyIDE4MiwxMzMgMTIwLDIyMiA5MywzMzggTCAyNzgsMzc1IEMgMjg3LDMzOCAzMDIsMzA1IDMyMSwyNzUgMzQwLDI0NSAzNjcsMjE5IDQwMCwxOTggNDMzLDE3NiA0NzMsMTU5IDUyMiwxNDcgNTcxLDEzNSA2MjksMTI5IDY5NywxMjkgNzU0LDEyOSA4MDYsMTM0IDg1MywxNDQgOTAwLDE1MyA5NDEsMTY4IDk3NSwxODggMTAwOSwyMDggMTAzNiwyMzQgMTA1NSwyNjYgMTA3NCwyOTcgMTA4MywzMzUgMTA4MywzNzkgMTA4Myw0MjUgMTA3Myw0NjIgMTA1Miw0OTEgMTAzMSw1MjAgMTAwMSw1NDMgOTYzLDU2MiA5MjUsNTgxIDg4MCw1OTYgODI3LDYwOSA3NzQsNjIyIDcxNiw2MzUgNjUyLDY1MCA2MTMsNjU5IDU3Myw2NjggNTM0LDY3OSA0OTQsNjg5IDQ1Niw3MDEgNDIwLDcxNiAzODMsNzMwIDM0OSw3NDcgMzE3LDc2NiAyODUsNzg1IDI1Nyw4MDkgMjM0LDgzNiAyMTEsODYzIDE5Miw4OTQgMTc5LDkzMCAxNjYsOTY1IDE1OSwxMDA2IDE1OSwxMDUzIDE1OSwxMTIwIDE3MywxMTc3IDIwMCwxMjI1IDIyNywxMjcyIDI2NCwxMzExIDMxMiwxMzQyIDM2MCwxMzczIDQxNywxMzk1IDQ4MiwxNDA5IDU0NywxNDIzIDYxOCwxNDMwIDY5NCwxNDMwIDc4MSwxNDMwIDg1NiwxNDIzIDkxOCwxNDEwIDk4MCwxMzk2IDEwMzIsMTM3NSAxMDc1LDEzNDggMTExOCwxMzIxIDExNTIsMTI4NyAxMTc4LDEyNDcgMTIwMywxMjA2IDEyMjQsMTE1OSAxMjM5LDExMDYgTCAxMDUxLDEwNzMgQyAxMDQyLDExMDcgMTAyOCwxMTM3IDEwMTEsMTE2NCA5OTMsMTE5MSA5NzAsMTIxMyA5NDEsMTIzMSA5MTIsMTI0OSA4NzgsMTI2MyA4MzcsMTI3MiA3OTYsMTI4MSA3NDcsMTI4NiA2OTIsMTI4NiA2MjcsMTI4NiA1NzIsMTI4MCA1MjgsMTI2OSA0ODMsMTI1NyA0NDgsMTI0MSA0MjEsMTIyMSAzOTQsMTIwMSAzNzQsMTE3OCAzNjMsMTE1MSAzNTEsMTEyNCAzNDUsMTA5NCAzNDUsMTA2MyAzNDUsMTAyMSAzNTYsOTg3IDM3Nyw5NjAgMzk4LDkzMyA0MjYsOTEwIDQ2Miw4OTIgNDk4LDg3NCA1NDAsODU5IDU4Nyw4NDcgNjM0LDgzNSA2ODUsODIzIDczOCw4MTEgNzgxLDgwMSA4MjUsNzkxIDg2OCw3ODEgOTExLDc3MCA5NTIsNzU4IDk5MSw3NDQgMTAzMCw3MjkgMTA2Nyw3MTIgMTEwMiw2OTMgMTEzNiw2NzQgMTE2Niw2NTAgMTE5MSw2MjIgMTIxNiw1OTQgMTIzNiw1NjEgMTI1MSw1MjMgMTI2NSw0ODUgMTI3Miw0NDAgMTI3MiwzODkgWiIvPgogICA8Z2x5cGggdW5pY29kZT0iTyIgaG9yaXotYWR2LXg9IjE0MzAiIGQ9Ik0gMTQ5NSw3MTEgQyAxNDk1LDYwMSAxNDc5LDUwMSAxNDQ4LDQxMSAxNDE2LDMyMSAxMzcwLDI0NCAxMzEwLDE4MCAxMjUwLDExNiAxMTc3LDY3IDEwOTAsMzIgMTAwMywtMyA5MDUsLTIwIDc5NSwtMjAgNjc5LC0yMCA1NzcsLTIgNDkwLDM1IDQwMyw3MSAzMzAsMTIyIDI3MiwxODcgMjE0LDI1MiAxNzAsMzI5IDE0MSw0MTggMTEyLDUwNyA5Nyw2MDUgOTcsNzExIDk3LDgyMSAxMTIsOTIwIDE0MywxMDA5IDE3NCwxMDk4IDIxOSwxMTczIDI3OCwxMjM2IDMzNywxMjk4IDQxMSwxMzQ2IDQ5OCwxMzgwIDU4NSwxNDEzIDY4NCwxNDMwIDc5NywxNDMwIDkwOSwxNDMwIDEwMDksMTQxMyAxMDk2LDEzNzkgMTE4MywxMzQ1IDEyNTYsMTI5NyAxMzE1LDEyMzQgMTM3NCwxMTcxIDE0MTgsMTA5NiAxNDQ5LDEwMDcgMTQ4MCw5MTggMTQ5NSw4MjAgMTQ5NSw3MTEgWiBNIDEzMDAsNzExIEMgMTMwMCw3OTYgMTI4OSw4NzMgMTI2OCw5NDIgMTI0NiwxMDExIDEyMTQsMTA3MSAxMTcyLDExMjAgMTEyOSwxMTY5IDEwNzcsMTIwNyAxMDE0LDEyMzQgOTUxLDEyNjEgODc5LDEyNzQgNzk3LDEyNzQgNzEzLDEyNzQgNjM5LDEyNjEgNTc2LDEyMzQgNTEzLDEyMDcgNDYwLDExNjkgNDE4LDExMjAgMzc1LDEwNzEgMzQ0LDEwMTEgMzIzLDk0MiAzMDIsODczIDI5MSw3OTYgMjkxLDcxMSAyOTEsNjI2IDMwMiw1NDkgMzI0LDQ3OSAzNDUsNDA4IDM3NywzNDggNDIwLDI5NyA0NjIsMjQ2IDUxNSwyMDYgNTc4LDE3OCA2NDEsMTQ5IDcxMywxMzUgNzk1LDEzNSA4ODMsMTM1IDk1OSwxNDkgMTAyMywxNzggMTA4NiwyMDcgMTEzOSwyNDcgMTE4MCwyOTggMTIyMSwzNDkgMTI1MSw0MDkgMTI3MSw0ODAgMTI5MCw1NTEgMTMwMCw2MjggMTMwMCw3MTEgWiIvPgogICA8Z2x5cGggdW5pY29kZT0iQyIgaG9yaXotYWR2LXg9IjEzMjQiIGQ9Ik0gNzkyLDEyNzQgQyA3MTIsMTI3NCA2NDEsMTI2MSA1ODAsMTIzNCA1MTgsMTIwNyA0NjYsMTE2OSA0MjUsMTEyMCAzODMsMTA3MSAzNTEsMTAxMSAzMzAsOTQyIDMwOSw4NzMgMjk4LDc5NiAyOTgsNzExIDI5OCw2MjYgMzEwLDU0OSAzMzMsNDc5IDM1Niw0MDggMzg5LDM0OCA0MzIsMjk3IDQ3NSwyNDYgNTI3LDIwNyA1OTAsMTc5IDY1MiwxNTEgNzIyLDEzNyA4MDAsMTM3IDg1NSwxMzcgOTA1LDE0NCA5NTAsMTU5IDk5NSwxNzMgMTAzNSwxOTMgMTA3MiwyMTkgMTEwOCwyNDUgMTE0MCwyNzYgMTE2OSwzMTIgMTE5OCwzNDcgMTIyMywzODcgMTI0NSw0MzAgTCAxNDAxLDM1MiBDIDEzNzYsMjk5IDEzNDQsMjUwIDEzMDcsMjA1IDEyNzAsMTYwIDEyMjYsMTIwIDExNzYsODcgMTEyNSw1NCAxMDY4LDI4IDEwMDUsOSA5NDEsLTEwIDg3MCwtMjAgNzkxLC0yMCA2NzcsLTIwIDU3NywtMiA0OTIsMzUgNDA2LDcxIDMzNCwxMjIgMjc3LDE4NyAyMTksMjUyIDE3NiwzMjkgMTQ3LDQxOCAxMTgsNTA3IDEwNCw2MDUgMTA0LDcxMSAxMDQsODIxIDExOSw5MjAgMTUwLDEwMDkgMTgwLDEwOTggMjI0LDExNzMgMjgzLDEyMzYgMzQxLDEyOTggNDEzLDEzNDYgNDk4LDEzODAgNTgzLDE0MTMgNjgxLDE0MzAgNzkwLDE0MzAgOTQwLDE0MzAgMTA2NSwxNDAxIDExNjYsMTM0MiAxMjY3LDEyODMgMTM0MSwxMTk2IDEzODgsMTA4MSBMIDEyMDcsMTAyMSBDIDExOTQsMTA1NCAxMTc2LDEwODYgMTE1MywxMTE3IDExMzAsMTE0NyAxMTAyLDExNzQgMTA2OCwxMTk3IDEwMzQsMTIyMCA5OTQsMTIzOSA5NDksMTI1MyA5MDMsMTI2NyA4NTEsMTI3NCA3OTIsMTI3NCBaIi8+CiAgIDxnbHlwaCB1bmljb2RlPSIgIiBob3Jpei1hZHYteD0iNTU2Ii8+CiAgPC9mb250PgogPC9kZWZzPgogPGRlZnMgY2xhc3M9IlRleHRTaGFwZUluZGV4Ij4KICA8ZyBvb286c2xpZGU9ImlkMSIgb29vOmlkLWxpc3Q9ImlkMyBpZDQgaWQ1IGlkNiBpZDcgaWQ4IGlkOSBpZDEwIGlkMTEgaWQxMiBpZDEzIGlkMTQgaWQxNSBpZDE2IGlkMTcgaWQxOCBpZDE5Ii8+CiA8L2RlZnM+CiA8ZGVmcyBjbGFzcz0iRW1iZWRkZWRCdWxsZXRDaGFycyI+CiAgPGcgaWQ9ImJ1bGxldC1jaGFyLXRlbXBsYXRlKDU3MzU2KSIgdHJhbnNmb3JtPSJzY2FsZSgwLjAwMDQ4ODI4MTI1LC0wLjAwMDQ4ODI4MTI1KSI+CiAgIDxwYXRoIGQ9Ik0gNTgwLDExNDEgTCAxMTYzLDU3MSA1ODAsMCAtNCw1NzEgNTgwLDExNDEgWiIvPgogIDwvZz4KICA8ZyBpZD0iYnVsbGV0LWNoYXItdGVtcGxhdGUoNTczNTQpIiB0cmFuc2Zvcm09InNjYWxlKDAuMDAwNDg4MjgxMjUsLTAuMDAwNDg4MjgxMjUpIj4KICAgPHBhdGggZD0iTSA4LDExMjggTCAxMTM3LDExMjggMTEzNywwIDgsMCA4LDExMjggWiIvPgogIDwvZz4KICA8ZyBpZD0iYnVsbGV0LWNoYXItdGVtcGxhdGUoMTAxNDYpIiB0cmFuc2Zvcm09InNjYWxlKDAuMDAwNDg4MjgxMjUsLTAuMDAwNDg4MjgxMjUpIj4KICAgPHBhdGggZD0iTSAxNzQsMCBMIDYwMiw3MzkgMTc0LDE0ODEgMTQ1Niw3MzkgMTc0LDAgWiBNIDEzNTgsNzM5IEwgMzA5LDEzNDYgNjU5LDczOSAxMzU4LDczOSBaIi8+CiAgPC9nPgogIDxnIGlkPSJidWxsZXQtY2hhci10ZW1wbGF0ZSgxMDEzMikiIHRyYW5zZm9ybT0ic2NhbGUoMC4wMDA0ODgyODEyNSwtMC4wMDA0ODgyODEyNSkiPgogICA8cGF0aCBkPSJNIDIwMTUsNzM5IEwgMTI3NiwwIDcxNywwIDEyNjAsNTQzIDE3NCw1NDMgMTc0LDkzNiAxMjYwLDkzNiA3MTcsMTQ4MSAxMjc0LDE0ODEgMjAxNSw3MzkgWiIvPgogIDwvZz4KICA8ZyBpZD0iYnVsbGV0LWNoYXItdGVtcGxhdGUoMTAwMDcpIiB0cmFuc2Zvcm09InNjYWxlKDAuMDAwNDg4MjgxMjUsLTAuMDAwNDg4MjgxMjUpIj4KICAgPHBhdGggZD0iTSAwLC0yIEMgLTcsMTQgLTE2LDI3IC0yNSwzNyBMIDM1Niw1NjcgQyAyNjIsODIzIDIxNSw5NTIgMjE1LDk1NCAyMTUsOTc5IDIyOCw5OTIgMjU1LDk5MiAyNjQsOTkyIDI3Niw5OTAgMjg5LDk4NyAzMTAsOTkxIDMzMSw5OTkgMzU0LDEwMTIgTCAzODEsOTk5IDQ5Miw3NDggNzcyLDEwNDkgODM2LDEwMjQgODYwLDEwNDkgQyA4ODEsMTAzOSA5MDEsMTAyNSA5MjIsMTAwNiA4ODYsOTM3IDgzNSw4NjMgNzcwLDc4NCA3NjksNzgzIDcxMCw3MTYgNTk0LDU4NCBMIDc3NCwyMjMgQyA3NzQsMTk2IDc1MywxNjggNzExLDEzOSBMIDcyNywxMTkgQyA3MTcsOTAgNjk5LDc2IDY3Miw3NiA2NDEsNzYgNTcwLDE3OCA0NTcsMzgxIEwgMTY0LC03NiBDIDE0MiwtMTEwIDExMSwtMTI3IDcyLC0xMjcgMzAsLTEyNyA5LC0xMTAgOCwtNzYgMSwtNjcgLTIsLTUyIC0yLC0zMiAtMiwtMjMgLTEsLTEzIDAsLTIgWiIvPgogIDwvZz4KICA8ZyBpZD0iYnVsbGV0LWNoYXItdGVtcGxhdGUoMTAwMDQpIiB0cmFuc2Zvcm09InNjYWxlKDAuMDAwNDg4MjgxMjUsLTAuMDAwNDg4MjgxMjUpIj4KICAgPHBhdGggZD0iTSAyODUsLTMzIEMgMTgyLC0zMyAxMTEsMzAgNzQsMTU2IDUyLDIyOCA0MSwzMzMgNDEsNDcxIDQxLDU0OSA1NSw2MTYgODIsNjcyIDExNiw3NDMgMTY5LDc3OCAyNDAsNzc4IDI5Myw3NzggMzI4LDc0NyAzNDYsNjg0IEwgMzY5LDUwOCBDIDM3Nyw0NDQgMzk3LDQxMSA0MjgsNDEwIEwgMTE2MywxMTE2IEMgMTE3NCwxMTI3IDExOTYsMTEzMyAxMjI5LDExMzMgMTI3MSwxMTMzIDEyOTIsMTExOCAxMjkyLDEwODcgTCAxMjkyLDk2NSBDIDEyOTIsOTI5IDEyODIsOTAxIDEyNjIsODgxIEwgNDQyLDQ3IEMgMzkwLC02IDMzOCwtMzMgMjg1LC0zMyBaIi8+CiAgPC9nPgogIDxnIGlkPSJidWxsZXQtY2hhci10ZW1wbGF0ZSg5Njc5KSIgdHJhbnNmb3JtPSJzY2FsZSgwLjAwMDQ4ODI4MTI1LC0wLjAwMDQ4ODI4MTI1KSI+CiAgIDxwYXRoIGQ9Ik0gODEzLDAgQyA2MzIsMCA0ODksNTQgMzgzLDE2MSAyNzYsMjY4IDIyMyw0MTEgMjIzLDU5MiAyMjMsNzczIDI3Niw5MTYgMzgzLDEwMjMgNDg5LDExMzAgNjMyLDExODQgODEzLDExODQgOTkyLDExODQgMTEzNiwxMTMwIDEyNDUsMTAyMyAxMzUzLDkxNiAxNDA3LDc3MiAxNDA3LDU5MiAxNDA3LDQxMiAxMzUzLDI2OCAxMjQ1LDE2MSAxMTM2LDU0IDk5MiwwIDgxMywwIFoiLz4KICA8L2c+CiAgPGcgaWQ9ImJ1bGxldC1jaGFyLXRlbXBsYXRlKDgyMjYpIiB0cmFuc2Zvcm09InNjYWxlKDAuMDAwNDg4MjgxMjUsLTAuMDAwNDg4MjgxMjUpIj4KICAgPHBhdGggZD0iTSAzNDYsNDU3IEMgMjczLDQ1NyAyMDksNDgzIDE1NSw1MzUgMTAxLDU4NiA3NCw2NDkgNzQsNzIzIDc0LDc5NiAxMDEsODU5IDE1NSw5MTEgMjA5LDk2MyAyNzMsOTg5IDM0Niw5ODkgNDE5LDk4OSA0ODAsOTYzIDUzMSw5MTAgNTgyLDg1OSA2MDgsNzk2IDYwOCw3MjMgNjA4LDY0OCA1ODMsNTg2IDUzMiw1MzUgNDgyLDQ4MyA0MjAsNDU3IDM0Niw0NTcgWiIvPgogIDwvZz4KICA8ZyBpZD0iYnVsbGV0LWNoYXItdGVtcGxhdGUoODIxMSkiIHRyYW5zZm9ybT0ic2NhbGUoMC4wMDA0ODgyODEyNSwtMC4wMDA0ODgyODEyNSkiPgogICA8cGF0aCBkPSJNIC00LDQ1OSBMIDExMzUsNDU5IDExMzUsNjA2IC00LDYwNiAtNCw0NTkgWiIvPgogIDwvZz4KIDwvZGVmcz4KIDxkZWZzIGNsYXNzPSJUZXh0RW1iZWRkZWRCaXRtYXBzIi8+CiA8Zz4KICA8ZyBpZD0iaWQyIiBjbGFzcz0iTWFzdGVyX1NsaWRlIj4KICAgPGcgaWQ9ImJnLWlkMiIgY2xhc3M9IkJhY2tncm91bmQiLz4KICAgPGcgaWQ9ImJvLWlkMiIgY2xhc3M9IkJhY2tncm91bmRPYmplY3RzIi8+CiAgPC9nPgogPC9nPgogPGcgY2xhc3M9IlNsaWRlR3JvdXAiPgogIDxnPgogICA8ZyBpZD0iaWQxIiBjbGFzcz0iU2xpZGUiIGNsaXAtcGF0aD0idXJsKCNwcmVzZW50YXRpb25fY2xpcF9wYXRoKSI+CiAgICA8ZyBjbGFzcz0iUGFnZSI+CiAgICAgPGcgY2xhc3M9ImNvbS5zdW4uc3Rhci5kcmF3aW5nLlJlY3RhbmdsZVNoYXBlIj4KICAgICAgPGcgaWQ9ImlkMyI+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODQ1MCw3MDAwIEwgNzAwMCw3MDAwIDcwMDAsMzAwMCA5OTAwLDMwMDAgOTkwMCw3MDAwIDg0NTAsNzAwMCBaIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgY2xhc3M9ImNvbS5zdW4uc3Rhci5kcmF3aW5nLlJlY3RhbmdsZVNoYXBlIj4KICAgICAgPGcgaWQ9ImlkNCI+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gMTIwNTAsNzAwMCBMIDEwMTAwLDcwMDAgMTAxMDAsMzAwMCAxNDAwMCwzMDAwIDE0MDAwLDcwMDAgMTIwNTAsNzAwMCBaIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgY2xhc3M9ImNvbS5zdW4uc3Rhci5kcmF3aW5nLkVsbGlwc2VTaGFwZSI+CiAgICAgIDxnIGlkPSJpZDUiPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDg5OTksMzMwMCBDIDkxMDUsMzMxMiA5MTk1LDMzODMgOTI4OCwzNTMxIDkzODcsMzY5MCA5NDU5LDM4ODkgOTUxNiw0MTY1IDk1NzQsNDQ0MSA5NjAwLDQ3MTIgOTYwMCw1MDMxIDk2MDAsNTM1MCA5NTc0LDU2MjEgOTUxNiw1ODk3IDk0NTksNjE3MyA5NDAyLDYzMjggOTMxOSw2NDc4Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJyZ2IoMCwwLDApIiBzdHJva2U9Im5vbmUiIGQ9Ik0gOTE0MSw2NzAxIEwgOTQwNSw2NTI2IDkyNDgsNjQwMyA5MTQxLDY3MDEgWiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGNsYXNzPSJjb20uc3VuLnN0YXIuZHJhd2luZy5FbGxpcHNlU2hhcGUiPgogICAgICA8ZyBpZD0iaWQ2Ij4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSAxMDc5NCw2NzEwIEMgMTA3NDgsNjY2OSAxMDcxMCw2NjE4IDEwNjY4LDY1NDAgMTA1ODMsNjM4MCAxMDUyMSw2MTgxIDEwNDcyLDU5MDUgMTA0MjIsNTYyOCAxMDQwMCw1MzU2IDEwNDAwLDUwMzYgMTA0MDAsNDcxNiAxMDQyMiw0NDQ0IDEwNDcyLDQxNjggMTA1MjEsMzg5MSAxMDU4MywzNjkyIDEwNjY4LDM1MzIgMTA3NDgsMzM4MyAxMDY5MCwzNDkyIDEwNzAxLDM0NzQiLz4KICAgICAgIDxwYXRoIGZpbGw9InJnYigwLDAsMCkiIHN0cm9rZT0ibm9uZSIgZD0iTSAxMDkxNiwzMzAwIEwgMTA2MjIsMzQxNiAxMDc1MCwzNTY5IDEwOTE2LDMzMDAgWiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGNsYXNzPSJjb20uc3VuLnN0YXIuZHJhd2luZy5DdXN0b21TaGFwZSI+CiAgICAgIDxnIGlkPSJpZDciPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDk4OTksNjkwMCBDIDk5NTUsNjkwMCA5OTk5LDY5NDMgOTk5OSw2OTk5IDk5OTksNzA1NSA5OTU1LDcwOTkgOTg5OSw3MDk5IDk4NDMsNzA5OSA5ODAwLDcwNTUgOTgwMCw2OTk5IDk4MDAsNjk0MyA5ODQzLDY5MDAgOTg5OSw2OTAwIFoiLz4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSA5ODAwLDY5MDAgTCA5ODAwLDY5MDAgWiIvPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDEwMDAxLDcxMDEgTCAxMDAwMSw3MTAxIFoiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBjbGFzcz0iY29tLnN1bi5zdGFyLmRyYXdpbmcuQ3VzdG9tU2hhcGUiPgogICAgICA8ZyBpZD0iaWQ4Ij4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSAxMDA5OSwyOTAwIEMgMTAxNTUsMjkwMCAxMDE5OSwyOTQzIDEwMTk5LDI5OTkgMTAxOTksMzA1NSAxMDE1NSwzMDk5IDEwMDk5LDMwOTkgMTAwNDMsMzA5OSAxMDAwMCwzMDU1IDEwMDAwLDI5OTkgMTAwMDAsMjk0MyAxMDA0MywyOTAwIDEwMDk5LDI5MDAgWiIvPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDEwMDAwLDI5MDAgTCAxMDAwMCwyOTAwIFoiLz4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSAxMDIwMSwzMTAxIEwgMTAyMDEsMzEwMSBaIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgY2xhc3M9ImNvbS5zdW4uc3Rhci5kcmF3aW5nLkN1c3RvbVNoYXBlIj4KICAgICAgPGcgaWQ9ImlkOSI+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gOTg5OSwyOTAwIEMgOTk1NSwyOTAwIDk5OTksMjk0MyA5OTk5LDI5OTkgOTk5OSwzMDU1IDk5NTUsMzA5OSA5ODk5LDMwOTkgOTg0MywzMDk5IDk4MDAsMzA1NSA5ODAwLDI5OTkgOTgwMCwyOTQzIDk4NDMsMjkwMCA5ODk5LDI5MDAgWiIvPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDk4MDAsMjkwMCBMIDk4MDAsMjkwMCBaIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gMTAwMDEsMzEwMSBMIDEwMDAxLDMxMDEgWiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGNsYXNzPSJjb20uc3VuLnN0YXIuZHJhd2luZy5DdXN0b21TaGFwZSI+CiAgICAgIDxnIGlkPSJpZDEwIj4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSA5ODk5LDQ5MDAgQyA5OTU1LDQ5MDAgOTk5OSw0OTQzIDk5OTksNDk5OSA5OTk5LDUwNTUgOTk1NSw1MDk5IDk4OTksNTA5OSA5ODQzLDUwOTkgOTgwMCw1MDU1IDk4MDAsNDk5OSA5ODAwLDQ5NDMgOTg0Myw0OTAwIDk4OTksNDkwMCBaIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gOTgwMCw0OTAwIEwgOTgwMCw0OTAwIFoiLz4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSAxMDAwMSw1MTAxIEwgMTAwMDEsNTEwMSBaIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgY2xhc3M9ImNvbS5zdW4uc3Rhci5kcmF3aW5nLkN1c3RvbVNoYXBlIj4KICAgICAgPGcgaWQ9ImlkMTEiPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDEwMDk5LDQ5MDAgQyAxMDE1NSw0OTAwIDEwMTk5LDQ5NDMgMTAxOTksNDk5OSAxMDE5OSw1MDU1IDEwMTU1LDUwOTkgMTAwOTksNTA5OSAxMDA0Myw1MDk5IDEwMDAwLDUwNTUgMTAwMDAsNDk5OSAxMDAwMCw0OTQzIDEwMDQzLDQ5MDAgMTAwOTksNDkwMCBaIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gMTAwMDAsNDkwMCBMIDEwMDAwLDQ5MDAgWiIvPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDEwMjAxLDUxMDEgTCAxMDIwMSw1MTAxIFoiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBjbGFzcz0iY29tLnN1bi5zdGFyLmRyYXdpbmcuQ3VzdG9tU2hhcGUiPgogICAgICA8ZyBpZD0iaWQxMiI+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gMTAwOTksNjkwMCBDIDEwMTU1LDY5MDAgMTAxOTksNjk0MyAxMDE5OSw2OTk5IDEwMTk5LDcwNTUgMTAxNTUsNzA5OSAxMDA5OSw3MDk5IDEwMDQzLDcwOTkgMTAwMDAsNzA1NSAxMDAwMCw2OTk5IDEwMDAwLDY5NDMgMTAwNDMsNjkwMCAxMDA5OSw2OTAwIFoiLz4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSAxMDAwMCw2OTAwIEwgMTAwMDAsNjkwMCBaIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gMTAyMDEsNzEwMSBMIDEwMjAxLDcxMDEgWiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGNsYXNzPSJjb20uc3VuLnN0YXIuZHJhd2luZy5DdXN0b21TaGFwZSI+CiAgICAgIDxnIGlkPSJpZDEzIj4KICAgICAgIDxwYXRoIGZpbGw9InJnYigyNTUsMjU1LDI1NSkiIHN0cm9rZT0ibm9uZSIgZD0iTSA1MTAwLDUyMDAgTCAzNTAwLDUyMDAgMzUwMCwzMDAwIDY3MDAsMzAwMCA2NzAwLDUyMDAgNTEwMCw1MjAwIFoiLz4KICAgICAgIDx0ZXh0IGNsYXNzPSJUZXh0U2hhcGUiPjx0c3BhbiBjbGFzcz0iVGV4dFBhcmFncmFwaCIgZm9udC1mYW1pbHk9IkxpYmVyYXRpb24gU2Fucywgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIzNTNweCIgZm9udC13ZWlnaHQ9IjQwMCI+PHRzcGFuIGNsYXNzPSJUZXh0UG9zaXRpb24iIHg9IjM3NTAiIHk9IjM0MzMiPjx0c3BhbiBmaWxsPSJyZ2IoMCwwLDApIiBzdHJva2U9Im5vbmUiPlN1YmRpdmlzaW9uIDwvdHNwYW4+PC90c3Bhbj48dHNwYW4gY2xhc3M9IlRleHRQb3NpdGlvbiIgeD0iMzc1MCIgeT0iMzgyNyI+PHRzcGFuIGZpbGw9InJnYigwLDAsMCkiIHN0cm9rZT0ibm9uZSI+cG9pbnRzIG5lZWQgdG8gPC90c3Bhbj48L3RzcGFuPjx0c3BhbiBjbGFzcz0iVGV4dFBvc2l0aW9uIiB4PSIzNzUwIiB5PSI0MjIxIj48dHNwYW4gZmlsbD0icmdiKDAsMCwwKSIgc3Ryb2tlPSJub25lIj5sYW5kIG9uIHRoZSBzYW1lIDwvdHNwYW4+PC90c3Bhbj48dHNwYW4gY2xhc3M9IlRleHRQb3NpdGlvbiIgeD0iMzc1MCIgeT0iNDYxNSI+PHRzcGFuIGZpbGw9InJnYigwLDAsMCkiIHN0cm9rZT0ibm9uZSI+bG9jYXRpb24gdG8gPC90c3Bhbj48L3RzcGFuPjx0c3BhbiBjbGFzcz0iVGV4dFBvc2l0aW9uIiB4PSIzNzUwIiB5PSI1MDA5Ij48dHNwYW4gZmlsbD0icmdiKDAsMCwwKSIgc3Ryb2tlPSJub25lIj5wcmV2ZW50IGNyYWNraW5nPC90c3Bhbj48L3RzcGFuPjwvdHNwYW4+PC90ZXh0PgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGNsYXNzPSJjb20uc3VuLnN0YXIuZHJhd2luZy5MaW5lU2hhcGUiPgogICAgICA8ZyBpZD0iaWQxNCI+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNjYwMCw0MjAwIEwgNjY1MSw0MjEzIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNjcwMyw0MjI3IEwgNjc1NCw0MjQwIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNjgwNiw0MjUzIEwgNjg1Nyw0MjY2Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNjkwOCw0MjgwIEwgNjk2MCw0MjkzIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNzAxMSw0MzA2IEwgNzA2Myw0MzE5Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNzExNCw0MzMzIEwgNzE2NSw0MzQ2Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNzIxNyw0MzU5IEwgNzI2OCw0MzcyIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNzMyMCw0Mzg2IEwgNzM3MSw0Mzk5Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNzQyMyw0NDEyIEwgNzQ3NCw0NDI2Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNzUyNSw0NDM5IEwgNzU3Nyw0NDUyIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNzYyOCw0NDY1IEwgNzY4MCw0NDc5Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNzczMSw0NDkyIEwgNzc4Miw0NTA1Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNzgzNCw0NTE4IEwgNzg4NSw0NTMyIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gNzkzNyw0NTQ1IEwgNzk4OCw0NTU4Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODAzOSw0NTcxIEwgODA5MSw0NTg1Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODE0Miw0NTk4IEwgODE5NCw0NjExIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODI0NSw0NjI1IEwgODI5Niw0NjM4Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODM0OCw0NjUxIEwgODM5OSw0NjY0Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODQ1MSw0Njc4IEwgODUwMiw0NjkxIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODU1Myw0NzA0IEwgODYwNSw0NzE3Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODY1Niw0NzMxIEwgODcwOCw0NzQ0Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODc1OSw0NzU3IEwgODgxMSw0NzcwIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODg2Miw0Nzg0IEwgODkxMyw0Nzk3Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gODk2NSw0ODEwIEwgOTAxNiw0ODI0Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gOTA2OCw0ODM3IEwgOTExOSw0ODUwIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gOTE3MCw0ODYzIEwgOTIyMiw0ODc3Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gOTI3Myw0ODkwIEwgOTMyNSw0OTAzIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gOTM3Niw0OTE2IEwgOTQyNyw0OTMwIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gOTQ3OSw0OTQzIEwgOTUzMCw0OTU2Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gOTU4Miw0OTY5IEwgOTYzMyw0OTgzIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gOTY4NCw0OTk2IEwgOTcwMCw1MDAwIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgY2xhc3M9ImNvbS5zdW4uc3Rhci5kcmF3aW5nLkN1c3RvbVNoYXBlIj4KICAgICAgPGcgaWQ9ImlkMTUiPgogICAgICAgPHBhdGggZmlsbD0icmdiKDI1NSwyNTUsMjU1KSIgc3Ryb2tlPSJub25lIiBkPSJNIDEyNjUwLDI3MDAgTCAxMDcwMCwyNzAwIDEwNzAwLDE1MDAgMTQ2MDAsMTUwMCAxNDYwMCwyNzAwIDEyNjUwLDI3MDAgWiIvPgogICAgICAgPHRleHQgY2xhc3M9IlRleHRTaGFwZSI+PHRzcGFuIGNsYXNzPSJUZXh0UGFyYWdyYXBoIiBmb250LWZhbWlseT0iTGliZXJhdGlvbiBTYW5zLCBzYW5zLXNlcmlmIiBmb250LXNpemU9IjM1M3B4IiBmb250LXdlaWdodD0iNDAwIj48dHNwYW4gY2xhc3M9IlRleHRQb3NpdGlvbiIgeD0iMTA5NTAiIHk9IjIwMjQiPjx0c3BhbiBmaWxsPSJyZ2IoMCwwLDApIiBzdHJva2U9Im5vbmUiPkNvcm5lciBwb2ludHMgc3RhcnQgPC90c3Bhbj48L3RzcGFuPjx0c3BhbiBjbGFzcz0iVGV4dFBvc2l0aW9uIiB4PSIxMDk1MCIgeT0iMjQxOCI+PHRzcGFuIGZpbGw9InJnYigwLDAsMCkiIHN0cm9rZT0ibm9uZSI+d2l0aCB0aGUgc2FtZSB2YWx1ZXM8L3RzcGFuPjwvdHNwYW4+PC90c3Bhbj48L3RleHQ+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgY2xhc3M9ImNvbS5zdW4uc3Rhci5kcmF3aW5nLkN1c3RvbVNoYXBlIj4KICAgICAgPGcgaWQ9ImlkMTYiPgogICAgICAgPHBhdGggZmlsbD0icmdiKDI1NSwyNTUsMjU1KSIgc3Ryb2tlPSJub25lIiBkPSJNIDEyODUwLDg1MDAgTCAxMDkwMCw4NTAwIDEwOTAwLDczMDAgMTQ4MDAsNzMwMCAxNDgwMCw4NTAwIDEyODUwLDg1MDAgWiIvPgogICAgICAgPHRleHQgY2xhc3M9IlRleHRTaGFwZSI+PHRzcGFuIGNsYXNzPSJUZXh0UGFyYWdyYXBoIiBmb250LWZhbWlseT0iTGliZXJhdGlvbiBTYW5zLCBzYW5zLXNlcmlmIiBmb250LXNpemU9IjM1M3B4IiBmb250LXdlaWdodD0iNDAwIj48dHNwYW4gY2xhc3M9IlRleHRQb3NpdGlvbiIgeD0iMTExNTAiIHk9Ijc4MjQiPjx0c3BhbiBmaWxsPSJyZ2IoMCwwLDApIiBzdHJva2U9Im5vbmUiPkNvcm5lciBwb2ludHMgc3RhcnQgPC90c3Bhbj48L3RzcGFuPjx0c3BhbiBjbGFzcz0iVGV4dFBvc2l0aW9uIiB4PSIxMTE1MCIgeT0iODIxOCI+PHRzcGFuIGZpbGw9InJnYigwLDAsMCkiIHN0cm9rZT0ibm9uZSI+d2l0aCB0aGUgc2FtZSB2YWx1ZXM8L3RzcGFuPjwvdHNwYW4+PC90c3Bhbj48L3RleHQ+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgY2xhc3M9ImNvbS5zdW4uc3Rhci5kcmF3aW5nLkN1c3RvbVNoYXBlIj4KICAgICAgPGcgaWQ9ImlkMTciPgogICAgICAgPHBhdGggZmlsbD0icmdiKDI1NSwyNTUsMjU1KSIgc3Ryb2tlPSJub25lIiBkPSJNIDEyNDAwLDUyMDAgTCAxMDkwMCw1MjAwIDEwOTAwLDMzMDAgMTM5MDAsMzMwMCAxMzkwMCw1MjAwIDEyNDAwLDUyMDAgWiIvPgogICAgICAgPHRleHQgY2xhc3M9IlRleHRTaGFwZSI+PHRzcGFuIGNsYXNzPSJUZXh0UGFyYWdyYXBoIiBmb250LWZhbWlseT0iTGliZXJhdGlvbiBTYW5zLCBzYW5zLXNlcmlmIiBmb250LXNpemU9IjM1M3B4IiBmb250LXdlaWdodD0iNDAwIj48dHNwYW4gY2xhc3M9IlRleHRQb3NpdGlvbiIgeD0iMTExNTAiIHk9IjM3ODAiPjx0c3BhbiBmaWxsPSJyZ2IoMCwwLDApIiBzdHJva2U9Im5vbmUiPk9wcG9zaW5nIDwvdHNwYW4+PC90c3Bhbj48dHNwYW4gY2xhc3M9IlRleHRQb3NpdGlvbiIgeD0iMTExNTAiIHk9IjQxNzQiPjx0c3BhbiBmaWxsPSJyZ2IoMCwwLDApIiBzdHJva2U9Im5vbmUiPmRpcmVjdGlvbnMgb2YgPC90c3Bhbj48L3RzcGFuPjx0c3BhbiBjbGFzcz0iVGV4dFBvc2l0aW9uIiB4PSIxMTE1MCIgeT0iNDU2OCI+PHRzcGFuIGZpbGw9InJnYigwLDAsMCkiIHN0cm9rZT0ibm9uZSI+ZWRnZSB3YWxraW5nIDwvdHNwYW4+PC90c3Bhbj48dHNwYW4gY2xhc3M9IlRleHRQb3NpdGlvbiIgeD0iMTExNTAiIHk9IjQ5NjIiPjx0c3BhbiBmaWxsPSJyZ2IoMCwwLDApIiBzdHJva2U9Im5vbmUiPmZvciBzdWJkaXZpc2lvbjwvdHNwYW4+PC90c3Bhbj48L3RzcGFuPjwvdGV4dD4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBjbGFzcz0iY29tLnN1bi5zdGFyLmRyYXdpbmcuTGluZVNoYXBlIj4KICAgICAgPGcgaWQ9ImlkMTgiPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDEwMzAwLDI5MDAgTCAxMDM0MSwyODY3Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gMTAzODMsMjgzNCBMIDEwNDI0LDI4MDEiLz4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSAxMDQ2NiwyNzY3IEwgMTA1MDcsMjczNCIvPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDEwNTQ5LDI3MDEgTCAxMDU5MCwyNjY4Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gMTA2MzIsMjYzNSBMIDEwNjczLDI2MDIiLz4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSAxMDcxNSwyNTY4IEwgMTA3NTYsMjUzNSIvPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDEwNzk3LDI1MDIgTCAxMDgwMCwyNTAwIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgY2xhc3M9ImNvbS5zdW4uc3Rhci5kcmF3aW5nLkxpbmVTaGFwZSI+CiAgICAgIDxnIGlkPSJpZDE5Ij4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSAxMDIwMCw3MTAwIEwgMTAyNDMsNzEzMSIvPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDEwMjg2LDcxNjIgTCAxMDMzMCw3MTkzIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gMTAzNzMsNzIyMyBMIDEwNDE2LDcyNTQiLz4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSAxMDQ1OSw3Mjg1IEwgMTA1MDIsNzMxNiIvPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDEwNTQ2LDczNDcgTCAxMDU4OSw3Mzc4Ii8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gMTA2MzIsNzQwOSBMIDEwNjc1LDc0MzkiLz4KICAgICAgIDxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDAsMCwwKSIgZD0iTSAxMDcxOCw3NDcwIEwgMTA3NjIsNzUwMSIvPgogICAgICAgPHBhdGggZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMCwwLDApIiBkPSJNIDEwODA1LDc1MzIgTCAxMDg0OCw3NTYzIi8+CiAgICAgICA8cGF0aCBmaWxsPSJub25lIiBzdHJva2U9InJnYigwLDAsMCkiIGQ9Ik0gMTA4OTEsNzU5NCBMIDEwOTAwLDc2MDAiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgPC9nPgogIDwvZz4KIDwvZz4KPC9zdmc+" alt="precise"> 8541</div> 8542</div> 8543<div class="paragraph"> 8544<p>As stated in “<a href="#evaluation-of-expressions">Evaluation of Expressions</a>”, 8545the compiler may transform expressions even if this changes the resulting 8546value. 8547Without any qualifiers, implementations are permitted to perform 8548optimizations that effectively modify the order or number of operations used 8549to evaluate an expression, even if those optimizations may produce slightly 8550different results relative to unoptimized code.</p> 8551</div> 8552<div class="paragraph"> 8553<p>The <strong>precise</strong> qualifier ensures that operations contributing to a 8554variable’s value are done in their stated order and with operator consistency. 8555The order is determined by operator precedence and parenthesis, as described in 8556“<a href="#operators">Operators</a>”. 8557Operator consistency means for each particular operator, for example the 8558multiply operator (<strong>*</strong>), its operation is always computed with the same 8559precision. 8560Specifically, values computed by compiler-generated code must adhere to the 8561following identities:</p> 8562</div> 8563<div class="olist arabic"> 8564<ol class="arabic"> 8565<li> 8566<p>a + b = b + a</p> 8567</li> 8568<li> 8569<p>a * b = b * a</p> 8570</li> 8571<li> 8572<p>a * b + c * d = b * a + c* d = d * c + b * a = <any other mathematically 8573valid combination></p> 8574</li> 8575</ol> 8576</div> 8577<div class="paragraph"> 8578<p>While the following are prevented:</p> 8579</div> 8580<div class="olist arabic"> 8581<ol class="arabic"> 8582<li> 8583<p>a + (b + c) is not allowed to become (a + b) + c</p> 8584</li> 8585<li> 8586<p>a * (b * c) is not allowed to become (a * b) * c</p> 8587</li> 8588<li> 8589<p>a * b + c is not allowed to become a single operation <strong>fma</strong>(a, b, c)</p> 8590</li> 8591</ol> 8592</div> 8593<div class="paragraph"> 8594<p>Where <em>a</em>, <em>b</em>, <em>c</em>, and <em>d</em>, are scalars or vectors, not matrices. 8595(Matrix multiplication generally does not commute.) It is the shader 8596writer’s responsibility to express the computation in terms of these rules 8597and the compiler’s responsibility to follow these rules. 8598See the description of <em>gl_TessCoord</em> for the rules the tessellation stages 8599are responsible for following, which in conjunction with the above allow 8600avoiding cracking when subdividing.</p> 8601</div> 8602<div class="paragraph"> 8603<p>For example,</p> 8604</div> 8605<div class="listingblock"> 8606<div class="content"> 8607<pre class="CodeRay highlight"><code data-lang="c++">precise out vec4 position;</code></pre> 8608</div> 8609</div> 8610<div class="paragraph"> 8611<p>declares that operations used to produce the value of <em>position</em> must be 8612performed in exactly the order specified in the source code and with all 8613operators being treated consistently. 8614As with the <strong>invariant</strong> qualifier (see “<a href="#the-invariant-qualifier">The 8615Invariant Qualifier</a>”), the <strong>precise</strong> qualifier may be used to qualify a 8616built-in or previously declared user-defined variable as being precise:</p> 8617</div> 8618<div class="listingblock"> 8619<div class="content"> 8620<pre class="CodeRay highlight"><code data-lang="c++">out vec3 Color; 8621precise Color; <span class="comment">// make existing Color be precise</span></code></pre> 8622</div> 8623</div> 8624<div class="paragraph"> 8625<p>When applied to a block, a structure type, or a variable of structure type, 8626<strong>precise</strong> applies to each contained member, recursively.</p> 8627</div> 8628<div class="paragraph"> 8629<p>This qualifier will affect the evaluation of an r-value in a particular 8630function if and only if the result is eventually consumed in the same 8631function by an l-value qualified as <strong>precise</strong>. 8632Any other expressions within a function are not affected, including return 8633values and output parameters not declared as <strong>precise</strong> but that are 8634eventually consumed outside the function by a variable qualified as 8635<strong>precise</strong>. Unaffected expressions also include the controlling expressions 8636in selection and iteration statements and the condition in ternary 8637operators (<strong>?:</strong>).</p> 8638</div> 8639<div class="paragraph"> 8640<p>Some examples of the use of <strong>precise</strong>:</p> 8641</div> 8642<div class="listingblock"> 8643<div class="content"> 8644<pre class="CodeRay highlight"><code data-lang="c++">in vec4 a, b, c, d; 8645precise out vec4 v; 8646 8647<span class="predefined-type">float</span> func(<span class="predefined-type">float</span> e, <span class="predefined-type">float</span> f, <span class="predefined-type">float</span> g, <span class="predefined-type">float</span> h) 8648{ 8649 <span class="keyword">return</span> (e*f) + (g*h); <span class="comment">// no constraint on order or operator consistency</span> 8650} 8651 8652<span class="predefined-type">float</span> func2(<span class="predefined-type">float</span> e, <span class="predefined-type">float</span> f, <span class="predefined-type">float</span> g, <span class="predefined-type">float</span> h) 8653{ 8654 precise <span class="predefined-type">float</span> result = (e*f) + (g*h); <span class="comment">// ensures same precision for the two multiplies</span> 8655 <span class="keyword">return</span> result; 8656} 8657 8658<span class="predefined-type">float</span> func3(<span class="predefined-type">float</span> i, <span class="predefined-type">float</span> j, precise out <span class="predefined-type">float</span> k) 8659{ 8660 k = i * i + j; <span class="comment">// precise, due to <k> declaration</span> 8661} 8662 8663<span class="directive">void</span> main() 8664{ 8665 vec3 r = vec3(a * b); <span class="comment">// precise, used to compute v.xyz</span> 8666 vec3 s = vec3(c * d); <span class="comment">// precise, used to compute v.xyz</span> 8667 v.xyz = r + s; <span class="comment">// precise</span> 8668 v.w = (a.w * b.w) + (c.w * d.w); <span class="comment">// precise</span> 8669 v.x = func(a.x, b.x, c.x, d.x); <span class="comment">// values computed in func() are NOT precise</span> 8670 v.x = func2(a.x, b.x, c.x, d.x); <span class="comment">// precise!</span> 8671 func3(a.x * b.x, c.x * d.x, v.x); <span class="comment">// precise!</span> 8672}</code></pre> 8673</div> 8674</div> 8675<div class="paragraph"> 8676<p>For the purposes of determining if an output from one shader stage matches 8677an input of the next stage, the <strong>precise</strong> qualifier need not match between 8678the input and the output.</p> 8679</div> 8680<div class="paragraph"> 8681<p>All constant expressions are evaluated as if <strong>precise</strong> was present, whether 8682or not it is present. 8683However, as described in “<a href="#constant-expressions">Constant Expressions</a>”, 8684there is no requirement that a compile-time constant expression evaluates to 8685the same value as a corresponding non-constant expression.</p> 8686</div> 8687</div> 8688<div class="sect2"> 8689<h3 id="memory-qualifiers">4.10. Memory Qualifiers</h3> 8690<div class="paragraph"> 8691<p>Shader storage blocks, variables declared within shader storage blocks and 8692variables declared as image types (the basic opaque types with “<strong>image</strong>” 8693in their keyword), can be further qualified with one or more of the 8694following memory qualifiers:</p> 8695</div> 8696<table class="tableblock frame-all grid-all stretch"> 8697<colgroup> 8698<col style="width: 50%;"> 8699<col style="width: 50%;"> 8700</colgroup> 8701<thead> 8702<tr> 8703<th class="tableblock halign-left valign-top">Qualifier</th> 8704<th class="tableblock halign-left valign-top">Meaning</th> 8705</tr> 8706</thead> 8707<tbody> 8708<tr> 8709<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>coherent</strong></p></td> 8710<td class="tableblock halign-left valign-top"><p class="tableblock">memory variable where reads and writes are coherent with 8711 reads and writes from other shader invocations</p></td> 8712</tr> 8713<tr> 8714<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>volatile</strong></p></td> 8715<td class="tableblock halign-left valign-top"><p class="tableblock">memory variable whose underlying value may be changed at any 8716 point during shader execution by some source other than the 8717 current shader invocation</p></td> 8718</tr> 8719<tr> 8720<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>restrict</strong></p></td> 8721<td class="tableblock halign-left valign-top"><p class="tableblock">memory variable where use of that variable is the only way 8722 to read and write the underlying memory in the relevant 8723 shader stage</p></td> 8724</tr> 8725<tr> 8726<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>readonly</strong></p></td> 8727<td class="tableblock halign-left valign-top"><p class="tableblock">memory variable that can be used to read the underlying 8728 memory, but cannot be used to write the underlying memory</p></td> 8729</tr> 8730<tr> 8731<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>writeonly</strong></p></td> 8732<td class="tableblock halign-left valign-top"><p class="tableblock">memory variable that can be used to write the underlying 8733 memory, but cannot be used to read the underlying memory</p></td> 8734</tr> 8735</tbody> 8736</table> 8737<div class="paragraph"> 8738<p>Memory accesses to image variables declared using the <strong>coherent</strong> qualifier 8739are performed coherently with accesses to the same location from other 8740shader invocations.</p> 8741</div> 8742<div class="paragraph"> 8743<p>As described in section 87447.11 8745“Shader Memory Access” of the 8746<a href="#references">OpenGL ES Specification</a>, shader memory reads and writes complete in a 8747largely undefined order. 8748The built-in function <strong>memoryBarrier</strong>() can be used if needed to guarantee 8749the completion and relative ordering of memory accesses performed by a 8750single shader invocation.</p> 8751</div> 8752<div class="paragraph"> 8753<p>When accessing memory using variables not declared as <strong>coherent</strong>, the memory 8754accessed by a shader may be cached by the implementation to service future 8755accesses to the same address. 8756Memory stores may be cached in such a way that the values written may not be 8757visible to other shader invocations accessing the same memory. 8758The implementation may cache the values fetched by memory reads and return 8759the same values to any shader invocation accessing the same memory, even if 8760the underlying memory has been modified since the first memory read. 8761While variables not declared as <strong>coherent</strong> may not be useful for 8762communicating between shader invocations, using non-coherent accesses may 8763result in higher performance.</p> 8764</div> 8765<div class="paragraph"> 8766<p>Memory accesses to image variables declared using the <strong>volatile</strong> qualifier 8767must treat the underlying memory as though it could be read or written at 8768any point during shader execution by some source other than the executing 8769shader invocation. 8770When a volatile variable is read, its value must be re-fetched from the 8771underlying memory, even if the shader invocation performing the read had 8772previously fetched its value from the same memory. 8773When a volatile variable is written, its value must be written to the 8774underlying memory, even if the compiler can conclusively determine that its 8775value will be overwritten by a subsequent write. 8776Since the external source reading or writing a <strong>volatile</strong> variable may be 8777another shader invocation, variables declared as <strong>volatile</strong> are 8778automatically treated as coherent.</p> 8779</div> 8780<div class="paragraph"> 8781<p>Memory accesses to image variables declared using the <strong>restrict</strong> qualifier 8782may be compiled assuming that the variable used to perform the memory access 8783is the only way to access the underlying memory using the shader stage in 8784question. 8785This allows the compiler to coalesce or reorder loads and stores using 8786<strong>restrict</strong>-qualified image variables in ways that wouldn’t be permitted 8787for image variables not so qualified, because the compiler can assume that 8788the underlying image won’t be read or written by other code. 8789Applications are responsible for ensuring that image memory referenced by 8790variables qualified with <strong>restrict</strong> will not be referenced using other 8791variables in the same scope; otherwise, accesses to <strong>restrict</strong>-qualified 8792variables will have undefined results.</p> 8793</div> 8794<div class="paragraph"> 8795<p>Memory accesses to image variables declared using the <strong>readonly</strong> qualifier 8796may only read the underlying memory, which is treated as read-only memory 8797and cannot be written to. 8798It is an error to pass an image variable qualified with 8799<strong>readonly</strong> to <strong>imageStore</strong>() or other built-in functions that modify image 8800memory.</p> 8801</div> 8802<div class="paragraph"> 8803<p>Memory accesses to image variables declared using the <strong>writeonly</strong> qualifier 8804may only write the underlying memory; the underlying memory cannot be read. 8805It is an error to pass an image variable qualified with 8806<strong>writeonly</strong> to <strong>imageLoad</strong>() or other built-in functions that read image 8807memory.</p> 8808</div> 8809<div class="paragraph"> 8810<p>A variable could be qualified as both <strong>readonly</strong> and <strong>writeonly</strong>, disallowing 8811both read and write. Such variables can still be used with some queries, for 8812example <strong>imageSize</strong>() and <strong>.length</strong>().</p> 8813</div> 8814<div class="paragraph"> 8815<p>Except for image variables qualified with the format qualifiers <strong>r32f</strong>, 8816<strong>r32i</strong>, and <strong>r32ui</strong>, image variables must specify a memory qualifier 8817(<strong>readonly</strong>, <strong>writeonly</strong>, or both).</p> 8818</div> 8819<div class="paragraph"> 8820<p>The memory qualifiers <strong>coherent</strong>, <strong>volatile</strong>, <strong>restrict</strong>, <strong>readonly</strong>, and 8821<strong>writeonly</strong> may be used in the declaration of buffer variables (i.e., 8822members of shader storage blocks). 8823When a buffer variable is declared with a memory qualifier, the behavior 8824specified for memory accesses involving image variables described above 8825applies identically to memory accesses involving that buffer variable. 8826It is a compile-time error to assign to a buffer variable qualified with 8827<strong>readonly</strong> or to read from a buffer variable qualified with <strong>writeonly</strong>. 8828The combination <strong>readonly</strong> <strong>writeonly</strong> is allowed.</p> 8829</div> 8830<div class="paragraph"> 8831<p>Additionally, memory qualifiers may be used at the block-level declaration 8832of a shader storage block, including the combination <strong>readonly</strong> <strong>writeonly</strong>. 8833When a block declaration is qualified with a memory qualifier, it is as if 8834all of its members were declared with the same memory qualifier. 8835For example, the block declaration</p> 8836</div> 8837<div class="listingblock"> 8838<div class="content"> 8839<pre class="CodeRay highlight"><code data-lang="c++">coherent buffer Block { 8840 readonly vec4 member1; 8841 vec4 member2; 8842};</code></pre> 8843</div> 8844</div> 8845<div class="paragraph"> 8846<p>is equivalent to</p> 8847</div> 8848<div class="listingblock"> 8849<div class="content"> 8850<pre class="CodeRay highlight"><code data-lang="c++">buffer Block { 8851 coherent readonly vec4 member1; 8852 coherent vec4 member2; 8853};</code></pre> 8854</div> 8855</div> 8856<div class="paragraph"> 8857<p>Memory qualifiers are only supported in the declarations of image variables, 8858buffer variables, and shader storage blocks; it is an error to use such 8859qualifiers in any other declarations.</p> 8860</div> 8861<div class="paragraph"> 8862<p>When calling user-defined functions, variables qualified with <strong>coherent</strong>, 8863<strong>volatile</strong>, <strong>readonly</strong>, or <strong>writeonly</strong> may not be passed to functions whose 8864formal parameters lack such qualifiers. 8865(See “<a href="#function-definitions">Function Definitions</a>” for more detail on 8866function calling.) It is legal to have any additional memory qualifiers on a 8867formal parameter, but only <strong>restrict</strong> can be taken away from a calling 8868argument, by a formal parameter that lacks the <strong>restrict</strong> qualifier.</p> 8869</div> 8870<div class="paragraph"> 8871<p>When a built-in function is called, the code generated is to be based on the 8872actual qualification of the calling argument, not on the list of memory 8873qualifiers specified on the formal parameter in the prototype.</p> 8874</div> 8875<div class="listingblock"> 8876<div class="content"> 8877<pre class="CodeRay highlight"><code data-lang="c++">vec4 funcA(restrict image2D a) { ... } 8878vec4 funcB(image2D a) { ... } 8879layout(rgba32f) uniform image2D img1; 8880layout(rgba32f) coherent uniform image2D img2; 8881 8882funcA(img1); <span class="comment">// OK, adding "restrict" is allowed</span> 8883funcB(img2); <span class="comment">// illegal, stripping "coherent" is not</span></code></pre> 8884</div> 8885</div> 8886<div class="paragraph"> 8887<p>Layout qualifiers cannot be used on formal function parameters, and layout 8888qualification is not included in parameter matching.</p> 8889</div> 8890<div class="paragraph"> 8891<p>Note that the use of <strong>const</strong> in an image variable declaration is qualifying 8892the const-ness of the variable being declared, not the image it refers to. 8893The qualifier <strong>readonly</strong> qualifies the image memory (as accessed through 8894that variable) while <strong>const</strong> qualifies the variable itself.</p> 8895</div> 8896</div> 8897<div class="sect2"> 8898<h3 id="specialization-constant-qualifier">4.11. Specialization-Constant Qualifier</h3> 8899<div class="paragraph"> 8900<p>Specialization constants are used only for SPIR-V and declared using the 8901<strong>constant_id</strong> layout qualifier. 8902For example:</p> 8903</div> 8904<div class="listingblock"> 8905<div class="content"> 8906<pre class="CodeRay highlight"><code data-lang="c++">layout(constant_id = <span class="integer">17</span>) <span class="directive">const</span> <span class="predefined-type">int</span> arraySize = <span class="integer">12</span>;</code></pre> 8907</div> 8908</div> 8909<div class="paragraph"> 8910<p>The above makes a specialization constant with a default value of 12. 8911The number 17 is an example author-chosen id by which the API or other tools 8912can later refer to this specific specialization constant. 8913If it is never changed before final lowering, it will retain the value of 891412. 8915It is a compile-time error to use the <strong>constant_id</strong> qualifier on anything 8916but SPIR-V generation of a scalar <strong>bool</strong>, <strong>int</strong>, <strong>uint</strong>, <strong>float</strong>, or 8917<strong>double</strong>.</p> 8918</div> 8919<div class="paragraph"> 8920<p>Built-in constants can be declared to be specialization constants. 8921For example:</p> 8922</div> 8923<div class="listingblock"> 8924<div class="content"> 8925<pre class="CodeRay highlight"><code data-lang="c++">layout(constant_id = <span class="integer">31</span>) gl_MaxClipDistances; <span class="comment">// add specialization_id</span></code></pre> 8926</div> 8927</div> 8928<div class="paragraph"> 8929<p>The declaration uses just the name of the previously declared built-in 8930variable, with a <strong>constant_id</strong> layout-qualifier declaration. 8931It is a compile-time error to do this after the constant has been used: 8932Constants are strictly either non-specialization constants or specialization 8933constants, not both.</p> 8934</div> 8935<div class="paragraph"> 8936<p>The built-in constant vector <em>gl_WorkGroupSize</em> can be specialized using the 8937<strong>local_size_{xyz}_id</strong> qualifiers, to individually give the components an id. 8938For example:</p> 8939</div> 8940<div class="listingblock"> 8941<div class="content"> 8942<pre class="CodeRay highlight"><code data-lang="c++">layout(local_size_x_id = <span class="integer">18</span>, local_size_z_id = <span class="integer">19</span>) in;</code></pre> 8943</div> 8944</div> 8945<div class="paragraph"> 8946<p>This leaves <em>gl_WorkGroupSize.y</em> as a non-specialization constant, with 8947<em>gl_WorkGroupSize</em> being a partially specialized vector. 8948Its <em>x</em> and <em>z</em> components can be later specialized, after generating 8949SPIR-V, using the ids 18 and 19. 8950These ids are declared independently from declaring the workgroup size:</p> 8951</div> 8952<div class="listingblock"> 8953<div class="content"> 8954<pre class="CodeRay highlight"><code data-lang="c++">layout(local_size_x = <span class="integer">32</span>, local_size_y = <span class="integer">32</span>) in; <span class="comment">// size is (32,32,1)</span> 8955layout(local_size_x_id = <span class="integer">18</span>) in; <span class="comment">// constant_id for x</span> 8956layout(local_size_z_id = <span class="integer">19</span>) in; <span class="comment">// constant_id for z</span></code></pre> 8957</div> 8958</div> 8959<div class="paragraph"> 8960<p>Existing rules for declaring <strong>local_size_x</strong>, <strong>local_size_y</strong>, and 8961<strong>local_size_z</strong> are not changed. 8962For the local-size ids, it is a compile-time error to provide different id 8963values for the same local-size id, or to provide them after any use. 8964Otherwise, order, placement, number of statements, and replication do not 8965cause errors.</p> 8966</div> 8967<div class="paragraph"> 8968<p>Two arrays sized with specialization constants are the same type only if 8969sized with the same symbol, and involving no operations. 8970For example:</p> 8971</div> 8972<div class="listingblock"> 8973<div class="content"> 8974<pre class="CodeRay highlight"><code data-lang="c++">layout(constant_id = <span class="integer">51</span>) <span class="directive">const</span> <span class="predefined-type">int</span> aSize = <span class="integer">20</span>; 8975<span class="directive">const</span> <span class="predefined-type">int</span> pad = <span class="integer">2</span>; 8976<span class="directive">const</span> <span class="predefined-type">int</span> total = aSize + pad; <span class="comment">// specialization constant</span> 8977<span class="predefined-type">int</span> a[total], b[total]; <span class="comment">// a and b have the same type</span> 8978<span class="predefined-type">int</span> c[<span class="integer">22</span>]; <span class="comment">// different type than a or b</span> 8979<span class="predefined-type">int</span> d[aSize + pad]; <span class="comment">// different type than a, b, or c</span> 8980<span class="predefined-type">int</span> e[aSize + <span class="integer">2</span>]; <span class="comment">// different type than a, b, c, or d</span></code></pre> 8981</div> 8982</div> 8983<div class="paragraph"> 8984<p>Types containing arrays sized with a specialization constant cannot be 8985compared, assigned as aggregates, declared with an initializer, or used as 8986an initializer. 8987They can, however, be passed as arguments to functions having formal 8988parameters of the same type. 8989Only the outer-most dimension of a variable declared as an array of arrays 8990can be a specialization constant, otherwise a compile-time error results.</p> 8991</div> 8992<div class="paragraph"> 8993<p>Arrays inside a block may be sized with a specialization constant, but the 8994block will have a static layout. 8995Changing the specialized size will not re-layout the block. 8996In the absence of explicit offsets, the layout will be based on the default 8997size of the array.</p> 8998</div> 8999</div> 9000<div class="sect2"> 9001<h3 id="order-of-qualification">4.12. Order and Repetition of Qualification</h3> 9002<div class="paragraph"> 9003<p>When multiple qualifiers are present in a declaration, they may appear in 9004any order, but they must all appear before the type. 9005The <strong>layout</strong> qualifier is the only qualifier that can appear more than once. 9006Further, a declaration can have at most one storage qualifier, at most one 9007auxiliary storage qualifier, and at most one interpolation qualifier. 9008Multiple memory qualifiers can be used. 9009Any violation of these rules will cause a compile-time error.</p> 9010</div> 9011</div> 9012<div class="sect2"> 9013<h3 id="empty-declarations">4.13. Empty Declarations</h3> 9014<div class="paragraph"> 9015<p><em>Empty declarations</em> are declarations without a variable name, meaning no 9016object is instantiated by the declaration. 9017Generally, empty declarations are allowed. 9018Some are useful when declaring structures, while many others have no effect. 9019For example:</p> 9020</div> 9021<div class="listingblock"> 9022<div class="content"> 9023<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">int</span>; <span class="comment">// No effect</span> 9024<span class="keyword">struct</span> S {<span class="predefined-type">int</span> x;}; <span class="comment">// Defines a struct S</span></code></pre> 9025</div> 9026</div> 9027<div class="paragraph"> 9028<p>The combinations of qualifiers that cause compile-time or link-time errors 9029are the same whether or not the declaration is empty, for example:</p> 9030</div> 9031<div class="listingblock"> 9032<div class="content"> 9033<pre class="CodeRay highlight"><code data-lang="c++">invariant in <span class="predefined-type">float</span> x; <span class="comment">// Error. An input cannot be invariant.</span> 9034invariant in <span class="predefined-type">float</span>; <span class="comment">// Error even though no variable is declared.</span></code></pre> 9035</div> 9036</div> 9037</div> 9038</div> 9039</div> 9040<div class="sect1"> 9041<h2 id="operators-and-expressions">5. Operators and Expressions</h2> 9042<div class="sectionbody"> 9043<div class="sect2"> 9044<h3 id="operators">5.1. Operators</h3> 9045<div class="paragraph"> 9046<p>The OpenGL ES Shading Language has the following operators.</p> 9047</div> 9048<table class="tableblock frame-all grid-all stretch"> 9049<colgroup> 9050<col style="width: 25%;"> 9051<col style="width: 25%;"> 9052<col style="width: 25%;"> 9053<col style="width: 25%;"> 9054</colgroup> 9055<thead> 9056<tr> 9057<th class="tableblock halign-left valign-top">Precedence</th> 9058<th class="tableblock halign-left valign-top">Operator Class</th> 9059<th class="tableblock halign-left valign-top">Operators</th> 9060<th class="tableblock halign-left valign-top">Associativity</th> 9061</tr> 9062</thead> 9063<tbody> 9064<tr> 9065<td class="tableblock halign-left valign-top"><p class="tableblock">1 (highest)</p></td> 9066<td class="tableblock halign-left valign-top"><p class="tableblock">parenthetical grouping</p></td> 9067<td class="tableblock halign-left valign-top"><p class="tableblock">( )</p></td> 9068<td class="tableblock halign-left valign-top"><p class="tableblock">NA</p></td> 9069</tr> 9070<tr> 9071<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> 9072<td class="tableblock halign-left valign-top"><p class="tableblock">array subscript<br> 9073 function call and constructor structure<br> 9074 field or method selector, swizzle<br> 9075 post fix increment and decrement</p></td> 9076<td class="tableblock halign-left valign-top"><p class="tableblock">[ ]<br> 9077 ( )<br> 9078 .<br> 9079 ++ --</p></td> 9080<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9081</tr> 9082<tr> 9083<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> 9084<td class="tableblock halign-left valign-top"><p class="tableblock">prefix increment and decrement<br> 9085 unary</p></td> 9086<td class="tableblock halign-left valign-top"><p class="tableblock">++ --<br> 9087 + - ~ !</p></td> 9088<td class="tableblock halign-left valign-top"><p class="tableblock">Right to Left</p></td> 9089</tr> 9090<tr> 9091<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> 9092<td class="tableblock halign-left valign-top"><p class="tableblock">multiplicative</p></td> 9093<td class="tableblock halign-left valign-top"><p class="tableblock">* / %</p></td> 9094<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9095</tr> 9096<tr> 9097<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> 9098<td class="tableblock halign-left valign-top"><p class="tableblock">additive</p></td> 9099<td class="tableblock halign-left valign-top"><p class="tableblock">+ -</p></td> 9100<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9101</tr> 9102<tr> 9103<td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> 9104<td class="tableblock halign-left valign-top"><p class="tableblock">bit-wise shift</p></td> 9105<td class="tableblock halign-left valign-top"><p class="tableblock"><< >></p></td> 9106<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9107</tr> 9108<tr> 9109<td class="tableblock halign-left valign-top"><p class="tableblock">7</p></td> 9110<td class="tableblock halign-left valign-top"><p class="tableblock">relational</p></td> 9111<td class="tableblock halign-left valign-top"><p class="tableblock">< > <= >=</p></td> 9112<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9113</tr> 9114<tr> 9115<td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td> 9116<td class="tableblock halign-left valign-top"><p class="tableblock">equality</p></td> 9117<td class="tableblock halign-left valign-top"><p class="tableblock">== !=</p></td> 9118<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9119</tr> 9120<tr> 9121<td class="tableblock halign-left valign-top"><p class="tableblock">9</p></td> 9122<td class="tableblock halign-left valign-top"><p class="tableblock">bit-wise and</p></td> 9123<td class="tableblock halign-left valign-top"><p class="tableblock">&</p></td> 9124<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9125</tr> 9126<tr> 9127<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td> 9128<td class="tableblock halign-left valign-top"><p class="tableblock">bit-wise exclusive or</p></td> 9129<td class="tableblock halign-left valign-top"><p class="tableblock">^</p></td> 9130<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9131</tr> 9132<tr> 9133<td class="tableblock halign-left valign-top"><p class="tableblock">11</p></td> 9134<td class="tableblock halign-left valign-top"><p class="tableblock">bit-wise inclusive or</p></td> 9135<td class="tableblock halign-left valign-top"><p class="tableblock">|</p></td> 9136<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9137</tr> 9138<tr> 9139<td class="tableblock halign-left valign-top"><p class="tableblock">12</p></td> 9140<td class="tableblock halign-left valign-top"><p class="tableblock">logical and</p></td> 9141<td class="tableblock halign-left valign-top"><p class="tableblock">&&</p></td> 9142<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9143</tr> 9144<tr> 9145<td class="tableblock halign-left valign-top"><p class="tableblock">13</p></td> 9146<td class="tableblock halign-left valign-top"><p class="tableblock">logical exclusive or</p></td> 9147<td class="tableblock halign-left valign-top"><p class="tableblock">^^</p></td> 9148<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9149</tr> 9150<tr> 9151<td class="tableblock halign-left valign-top"><p class="tableblock">14</p></td> 9152<td class="tableblock halign-left valign-top"><p class="tableblock">logical inclusive or</p></td> 9153<td class="tableblock halign-left valign-top"><p class="tableblock">||</p></td> 9154<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9155</tr> 9156<tr> 9157<td class="tableblock halign-left valign-top"><p class="tableblock">15</p></td> 9158<td class="tableblock halign-left valign-top"><p class="tableblock">selection</p></td> 9159<td class="tableblock halign-left valign-top"><p class="tableblock">? :</p></td> 9160<td class="tableblock halign-left valign-top"><p class="tableblock">Right to Left</p></td> 9161</tr> 9162<tr> 9163<td class="tableblock halign-left valign-top"><p class="tableblock">16</p></td> 9164<td class="tableblock halign-left valign-top"><p class="tableblock">Assignment<br> 9165 arithmetic assignments</p></td> 9166<td class="tableblock halign-left valign-top"><p class="tableblock">=<br> 9167 += -=<br> 9168 *= /=<br> 9169 %= <<= >>=<br> 9170 &= ^= |=</p></td> 9171<td class="tableblock halign-left valign-top"><p class="tableblock">Right to Left</p></td> 9172</tr> 9173<tr> 9174<td class="tableblock halign-left valign-top"><p class="tableblock">17 (lowest)</p></td> 9175<td class="tableblock halign-left valign-top"><p class="tableblock">sequence</p></td> 9176<td class="tableblock halign-left valign-top"><p class="tableblock">,</p></td> 9177<td class="tableblock halign-left valign-top"><p class="tableblock">Left to Right</p></td> 9178</tr> 9179</tbody> 9180</table> 9181<div class="paragraph"> 9182<p>There is no address-of operator nor a dereference operator. 9183There is no typecast operator; constructors are used instead.</p> 9184</div> 9185</div> 9186<div class="sect2"> 9187<h3 id="array-operations">5.2. Array Operations</h3> 9188<div class="paragraph"> 9189<p>These are now described in “<a href="#structure-and-array-operations">Structure and 9190Array Operations</a>”.</p> 9191</div> 9192</div> 9193<div class="sect2"> 9194<h3 id="function-calls">5.3. Function Calls</h3> 9195<div class="paragraph"> 9196<p>If a function returns a value, then a call to that function may be used as 9197an expression, whose type will be the type that was used to declare or 9198define the function.</p> 9199</div> 9200<div class="paragraph"> 9201<p>Function definitions and calling conventions are discussed in 9202“<a href="#function-definitions">Function Definitions</a>”.</p> 9203</div> 9204</div> 9205<div class="sect2"> 9206<h3 id="constructors">5.4. Constructors</h3> 9207<div class="paragraph"> 9208<p>Constructors use the function call syntax, where the function name is a 9209type, and the call makes an object of that type. 9210Constructors are used the same way in both initializers and expressions. 9211(See “<a href="#shading-language-grammar">Shading Language Grammar</a>” for details.) 9212The parameters are used to initialize the constructed value. 9213Constructors can be used to request a data type conversion to change from 9214one scalar type to another scalar type, or to build larger types out of 9215smaller types, or to reduce a larger type to a smaller type.</p> 9216</div> 9217<div class="paragraph"> 9218<p>In general, constructors are not built-in functions with predetermined 9219prototypes. 9220For arrays and structures, there must be exactly one argument in the 9221constructor for each element or member. 9222For the other types, the arguments must provide a sufficient number of 9223components to perform the initialization, and it is an error to 9224include so many arguments that they cannot all be used. 9225Detailed rules follow. 9226The prototypes actually listed below are merely a subset of examples.</p> 9227</div> 9228<div class="sect3"> 9229<h4 id="conversion-and-scalar-constructors">5.4.1. Conversion and Scalar Constructors</h4> 9230<div class="paragraph"> 9231<p>Converting between scalar types is done as the following prototypes 9232indicate:</p> 9233</div> 9234<div class="listingblock"> 9235<div class="content"> 9236<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">int</span>(uint) <span class="comment">// converts an unsigned integer to a signed integer</span> 9237<span class="predefined-type">int</span>(<span class="predefined-type">bool</span>) <span class="comment">// converts a Boolean value to an int</span> 9238<span class="predefined-type">int</span>(<span class="predefined-type">float</span>) <span class="comment">// converts a float value to an int</span> 9239uint(<span class="predefined-type">int</span>) <span class="comment">// converts a signed integer value to an unsigned integer</span> 9240uint(<span class="predefined-type">bool</span>) <span class="comment">// converts a Boolean value to an unsigned integer</span> 9241uint(<span class="predefined-type">float</span>) <span class="comment">// converts a float value to an unsigned integer</span> 9242<span class="predefined-type">bool</span>(<span class="predefined-type">int</span>) <span class="comment">// converts a signed integer value to a Boolean</span> 9243<span class="predefined-type">bool</span>(uint) <span class="comment">// converts an unsigned integer value to a Boolean value</span> 9244<span class="predefined-type">bool</span>(<span class="predefined-type">float</span>) <span class="comment">// converts a float value to a Boolean</span> 9245<span class="predefined-type">float</span>(<span class="predefined-type">int</span>) <span class="comment">// converts a signed integer value to a float</span> 9246<span class="predefined-type">float</span>(uint) <span class="comment">// converts an unsigned integer value to a float value</span> 9247<span class="predefined-type">float</span>(<span class="predefined-type">bool</span>) <span class="comment">// converts a Boolean value to a float</span></code></pre> 9248</div> 9249</div> 9250<div class="paragraph"> 9251<p>When constructors are used to convert a floating-point type to an integer 9252type, the fractional part of the floating-point value is dropped. 9253It is undefined to convert a negative floating-point value to an <strong>uint</strong>.</p> 9254</div> 9255<div class="paragraph"> 9256<p>Integer values having more bits of precision than a single-precision 9257floating-point mantissa will lose precision when converted to <strong>float</strong>.</p> 9258</div> 9259<div class="paragraph"> 9260<p>When a constructor is used to convert any integer or floating-point type to 9261a <strong>bool</strong>, 0 and 0.0 are converted to <strong>false</strong>, and non-zero values are 9262converted to <strong>true</strong>. 9263When a constructor is used to convert a <strong>bool</strong> to any integer or 9264floating-point type, <strong>false</strong> is converted to 0 or 0.0, and <strong>true</strong> is 9265converted to 1 or 1.0.</p> 9266</div> 9267<div class="paragraph"> 9268<p>The constructor <strong>int</strong>(<strong>uint</strong>) preserves the bit pattern in the argument, 9269which will change the argument’s value if its sign bit is set. 9270The constructor <strong>uint</strong>(<strong>int</strong>) preserves the bit pattern in the argument, 9271which will change its value if it is negative.</p> 9272</div> 9273<div class="paragraph"> 9274<p>Identity constructors, like <strong>float</strong>(<strong>float</strong>) are also legal, but of little 9275use.</p> 9276</div> 9277<div class="paragraph"> 9278<p>Scalar constructors with non-scalar parameters can be used to take the first 9279element from a non-scalar. 9280For example, the constructor <strong>float</strong>(<strong>vec3</strong>) will select the first component 9281of the <strong>vec3</strong> parameter.</p> 9282</div> 9283</div> 9284<div class="sect3"> 9285<h4 id="vector-and-matrix-constructors">5.4.2. Vector and Matrix Constructors</h4> 9286<div class="paragraph"> 9287<p>Constructors can be used to create vectors or matrices from a set of 9288scalars, vectors, or matrices. 9289This includes the ability to shorten vectors.</p> 9290</div> 9291<div class="paragraph"> 9292<p>If there is a single scalar parameter to a vector constructor, it is used to 9293initialize all components of the constructed vector to that scalar’s value. 9294If there is a single scalar parameter to a matrix constructor, it is used to 9295initialize all the components on the matrix’s diagonal, with the remaining 9296components initialized to 0.0.</p> 9297</div> 9298<div class="paragraph"> 9299<p>If a vector is constructed from multiple scalars, one or more vectors, or 9300one or more matrices, or a mixture of these, the vector’s components will be 9301constructed in order from the components of the arguments. 9302The arguments will be consumed left to right, and each argument will have 9303all its components consumed, in order, before any components from the next 9304argument are consumed. 9305Similarly for constructing a matrix from multiple scalars or vectors, or a 9306mixture of these. 9307Matrix components will be constructed and consumed in column major order. 9308In these cases, there must be enough components provided in the arguments to 9309provide an initializer for every component in the constructed value. 9310It is an error to provide extra arguments beyond this last used 9311argument.</p> 9312</div> 9313<div class="paragraph"> 9314<p>If a matrix is constructed from a matrix, then each component (column <em>i</em>, 9315row <em>j</em>) in the result that has a corresponding component (column <em>i</em>, row 9316<em>j</em>) in the argument will be initialized from there. 9317All other components will be initialized to the identity matrix. 9318If a matrix argument is given to a matrix constructor, it is 9319an error to have any other arguments.</p> 9320</div> 9321<div class="paragraph"> 9322<p>If the basic type (<strong>bool</strong>, <strong>int</strong>, 9323or <strong>float</strong>) 9324of a parameter to a 9325constructor does not match the basic type of the object being constructed, 9326the scalar construction rules (above) are used to convert the parameters.</p> 9327</div> 9328<div class="paragraph"> 9329<p>Some useful vector constructors are as follows:</p> 9330</div> 9331<div class="listingblock"> 9332<div class="content"> 9333<pre class="CodeRay highlight"><code data-lang="c++">vec3(<span class="predefined-type">float</span>) <span class="comment">// initializes each component of the vec3 with the float</span> 9334vec4(ivec4) <span class="comment">// makes a vec4 with component-wise conversion</span> 9335vec4(mat2) <span class="comment">// the vec4 is column 0 followed by column 1</span> 9336vec2(<span class="predefined-type">float</span>, <span class="predefined-type">float</span>) <span class="comment">// initializes a vec2 with 2 floats</span> 9337ivec3(<span class="predefined-type">int</span>, <span class="predefined-type">int</span>, <span class="predefined-type">int</span>) <span class="comment">// initializes an ivec3 with 3 ints</span> 9338bvec4(<span class="predefined-type">int</span>, <span class="predefined-type">int</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>) <span class="comment">// uses 4 Boolean conversions</span> 9339vec2(vec3) <span class="comment">// drops the third component of a vec3</span> 9340vec3(vec4) <span class="comment">// drops the fourth component of a vec4</span> 9341vec3(vec2, <span class="predefined-type">float</span>) <span class="comment">// vec3.x = vec2.x, vec3.y = vec2.y, vec3.z = float</span> 9342vec3(<span class="predefined-type">float</span>, vec2) <span class="comment">// vec3.x = float, vec3.y = vec2.x, vec3.z = vec2.y</span> 9343vec4(vec3, <span class="predefined-type">float</span>) 9344vec4(<span class="predefined-type">float</span>, vec3) 9345vec4(vec2, vec2)</code></pre> 9346</div> 9347</div> 9348<div class="paragraph"> 9349<p>Some examples of these are:</p> 9350</div> 9351<div class="listingblock"> 9352<div class="content"> 9353<pre class="CodeRay highlight"><code data-lang="c++">vec4 color = vec4(<span class="float">0</span><span class="float">.0</span>, <span class="float">1</span><span class="float">.0</span>, <span class="float">0</span><span class="float">.0</span>, <span class="float">1</span><span class="float">.0</span>); 9354vec4 rgba = vec4(<span class="float">1</span><span class="float">.0</span>); <span class="comment">// sets each component to 1.0</span> 9355vec3 rgb = vec3(color); <span class="comment">// drop the 4th component</span></code></pre> 9356</div> 9357</div> 9358<div class="paragraph"> 9359<p>To initialize the diagonal of a matrix with all other elements set to zero:</p> 9360</div> 9361<div class="listingblock"> 9362<div class="content"> 9363<pre class="CodeRay highlight"><code data-lang="c++">mat2(<span class="predefined-type">float</span>) 9364mat3(<span class="predefined-type">float</span>) 9365mat4(<span class="predefined-type">float</span>)</code></pre> 9366</div> 9367</div> 9368<div class="paragraph"> 9369<p>That is, <em>result[i][j]</em> is set to the <em>float</em> argument for all \(i 9370= j\) and set to 0 for all \(i \neq j\).</p> 9371</div> 9372<div class="paragraph"> 9373<p>To initialize a matrix by specifying vectors or scalars, the components are 9374assigned to the matrix elements in column-major order.</p> 9375</div> 9376<div class="listingblock"> 9377<div class="content"> 9378<pre class="CodeRay highlight"><code data-lang="c++">mat2(vec2, vec2); <span class="comment">// one column per argument</span> 9379mat3(vec3, vec3, vec3); <span class="comment">// one column per argument</span> 9380mat4(vec4, vec4, vec4, vec4); <span class="comment">// one column per argument</span> 9381mat3x2(vec2, vec2, vec2); <span class="comment">// one column per argument</span> 9382mat2(<span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="comment">// first column</span> 9383 <span class="predefined-type">float</span>, <span class="predefined-type">float</span>); <span class="comment">// second column</span> 9384mat3(<span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="comment">// first column</span> 9385 <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="comment">// second column</span> 9386 <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>); <span class="comment">// third column</span> 9387mat4(<span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="comment">// first column</span> 9388 <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="comment">// second column</span> 9389 <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="comment">// third column</span> 9390 <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>, <span class="predefined-type">float</span>); <span class="comment">// fourth column</span> 9391mat2x3(vec2, <span class="predefined-type">float</span>, <span class="comment">// first column</span> 9392 vec2, <span class="predefined-type">float</span>); <span class="comment">// second column</span></code></pre> 9393</div> 9394</div> 9395<div class="paragraph"> 9396<p>A wide range of other possibilities exist, to construct a matrix from 9397vectors and scalars, as long as enough components are present to initialize 9398the matrix. 9399To construct a matrix from a matrix:</p> 9400</div> 9401<div class="listingblock"> 9402<div class="content"> 9403<pre class="CodeRay highlight"><code data-lang="c++">mat3x3(mat4x4); <span class="comment">// takes the upper-left 3x3 of the mat4x4</span> 9404mat2x3(mat4x2); <span class="comment">// takes the upper-left 2x2 of the mat4x4, last row is 0,0</span> 9405mat4x4(mat3x3); <span class="comment">// puts the mat3x3 in the upper-left, sets the lower right</span> 9406 <span class="comment">// component to 1, and the rest to 0</span></code></pre> 9407</div> 9408</div> 9409</div> 9410<div class="sect3"> 9411<h4 id="structure-constructors">5.4.3. Structure Constructors</h4> 9412<div class="paragraph"> 9413<p>Once a structure is defined, and its type is given a name, a constructor is 9414available with the same name to construct instances of that structure. 9415For example:</p> 9416</div> 9417<div class="listingblock"> 9418<div class="content"> 9419<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">struct</span> light { 9420 <span class="predefined-type">float</span> intensity; 9421 vec3 position; 9422}; 9423 9424light lightVar = light(<span class="float">3</span><span class="float">.0</span>, vec3(<span class="float">1</span><span class="float">.0</span>, <span class="float">2</span><span class="float">.0</span>, <span class="float">3</span><span class="float">.0</span>));</code></pre> 9425</div> 9426</div> 9427<div class="paragraph"> 9428<p>The arguments to the constructor will be used to set the structure’s 9429members, in order, using one argument per member. 9430Each argument must be the same type as the member it 9431sets.</p> 9432</div> 9433<div class="paragraph"> 9434<p>Structure constructors can be used as initializers or in expressions.</p> 9435</div> 9436</div> 9437<div class="sect3"> 9438<h4 id="array-constructors">5.4.4. Array Constructors</h4> 9439<div class="paragraph"> 9440<p>Array types can also be used as constructor names, which can then be used in 9441expressions or initializers. 9442For example,</p> 9443</div> 9444<div class="listingblock"> 9445<div class="content"> 9446<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">const</span> <span class="predefined-type">float</span> c[<span class="integer">3</span>] = <span class="predefined-type">float</span>[<span class="integer">3</span>](<span class="float">5</span><span class="float">.0</span>, <span class="float">7</span><span class="float">.2</span>, <span class="float">1</span><span class="float">.1</span>); 9447<span class="directive">const</span> <span class="predefined-type">float</span> d[<span class="integer">3</span>] = <span class="predefined-type">float</span>[](<span class="float">5</span><span class="float">.0</span>, <span class="float">7</span><span class="float">.2</span>, <span class="float">1</span><span class="float">.1</span>); 9448 9449<span class="predefined-type">float</span> g; 9450... 9451<span class="predefined-type">float</span> a[<span class="integer">5</span>] = <span class="predefined-type">float</span>[<span class="integer">5</span>](g, <span class="integer">1</span>, g, <span class="float">2</span><span class="float">.3</span>, g); 9452<span class="predefined-type">float</span> b[<span class="integer">3</span>]; 9453 9454b = <span class="predefined-type">float</span>[<span class="integer">3</span>](g, g + <span class="float">1</span><span class="float">.0</span>, g + <span class="float">2</span><span class="float">.0</span>);</code></pre> 9455</div> 9456</div> 9457<div class="paragraph"> 9458<p>There must be exactly the same number of arguments as the size of the array 9459being constructed. 9460If no size is present in the constructor, then the array is explicitly sized 9461to the number of arguments provided. 9462The arguments are assigned in order, starting at element 0, to the elements 9463of the constructed array. 9464Each argument must be the same type as the element type of the 9465array.</p> 9466</div> 9467<div class="paragraph"> 9468<p>Arrays of arrays are similarly constructed, and the size for any dimension 9469is <strong class="purple">optional</strong></p> 9470</div> 9471<div class="listingblock"> 9472<div class="content"> 9473<pre class="CodeRay highlight"><code data-lang="c++">vec4 b[<span class="integer">2</span>] = ...; 9474vec4[<span class="integer">3</span>][<span class="integer">2</span>](b, b, b); <span class="comment">// constructor</span> 9475vec4[][<span class="integer">2</span>](b, b, b); <span class="comment">// constructor, valid, size deduced</span> 9476vec4[<span class="integer">3</span>][](b, b, b); <span class="comment">// constructor, valid, size deduced</span> 9477vec4[][](b, b, b); <span class="comment">// constructor, valid, both sizes deduced</span></code></pre> 9478</div> 9479</div> 9480</div> 9481<div class="sect3"> 9482<h4 id="_texture_combined_sampler_constructors">5.4.5. Texture-Combined Sampler Constructors</h4> 9483<div class="paragraph"> 9484<p>Texture-combined sampler constructors are only available when targeting Vulkan.</p> 9485</div> 9486<div class="paragraph"> 9487<p>Texture-combined sampler types, like <strong>sampler2D</strong>, can be declared with an 9488initializer 9489that is a constructor of the same type, and consuming a texture and a 9490<strong>sampler</strong> or <strong>samplerShadow</strong>. 9491For example:</p> 9492</div> 9493<div class="listingblock"> 9494<div class="content"> 9495<pre class="CodeRay highlight"><code data-lang="c++"> layout(...) uniform sampler s; <span class="comment">// handle to filtering information</span> 9496 layout(...) uniform texture2D t; <span class="comment">// handle to a texture</span> 9497 layout(...) in vec2 tCoord; 9498 ... 9499 texture(sampler2D(t, s), tCoord);</code></pre> 9500</div> 9501</div> 9502<div class="paragraph"> 9503<p>The result of a texture-combined sampler constructor cannot be assigned to a 9504variable:</p> 9505</div> 9506<div class="listingblock"> 9507<div class="content"> 9508<pre class="CodeRay highlight"><code data-lang="c++"> ... sampler2D sConstruct = sampler2D(t, s); <span class="comment">// ERROR</span></code></pre> 9509</div> 9510</div> 9511<div class="paragraph"> 9512<p>Texture-combined sampler constructors can only be consumed by a function parameter.</p> 9513</div> 9514<div class="paragraph"> 9515<p>Texture-combined sampler constructors of arrays are illegal:</p> 9516</div> 9517<div class="listingblock"> 9518<div class="content"> 9519<pre class="CodeRay highlight"><code data-lang="c++"> layout(...) uniform texture2D tArray[<span class="integer">6</span>]; 9520 ... 9521 ... sampler2D[](tArray, s) ... <span class="comment">// ERROR</span></code></pre> 9522</div> 9523</div> 9524<div class="paragraph"> 9525<p>Formally:</p> 9526</div> 9527<div class="ulist"> 9528<ul> 9529<li> 9530<p>every texture-combined sampler type can be used as a constructor</p> 9531</li> 9532<li> 9533<p>the type of the constructor must match the type of the variable being declared</p> 9534</li> 9535<li> 9536<p>the constructor’s first argument must be a texture type</p> 9537</li> 9538<li> 9539<p>the constructor’s second argument must be a scalar of type <strong>sampler</strong> 9540or <strong>samplerShadow</strong></p> 9541</li> 9542<li> 9543<p>the dimensionality (1D, 2D, 3D, Cube, Rect, Buffer, MS, and Array) 9544of the texture type must match that of the constructed type 9545(that is, the suffixes of the type of the first argument and the 9546type of the constructor will be spelled the same way)</p> 9547</li> 9548<li> 9549<p>there is no control flow construct (e.g., <code>?:</code>) that consumes any sampler type</p> 9550</li> 9551</ul> 9552</div> 9553<div class="paragraph"> 9554<p>Note: Shadow mismatches are allowed between constructors and the second argument. 9555Texture-combined non-shadow samplers can be constructed from <strong>samplerShadow</strong> and 9556texture-combined shadow samplers can be constructed from <strong>sampler</strong>.</p> 9557</div> 9558</div> 9559</div> 9560<div class="sect2"> 9561<h3 id="vector-components">5.5. Vector Components</h3> 9562<div class="paragraph"> 9563<p>The names of the components of a vector 9564are denoted by a single letter. 9565As a notational convenience, several letters are associated with each 9566component based on common usage of position, color or texture coordinate 9567vectors. 9568The individual components can be selected by following the variable name 9569with period (<strong>.</strong>) and then the component name.</p> 9570</div> 9571<div class="paragraph"> 9572<p>The component names supported are:</p> 9573</div> 9574<table class="tableblock frame-all grid-all fit-content"> 9575<colgroup> 9576<col> 9577<col> 9578</colgroup> 9579<tbody> 9580<tr> 9581<td class="tableblock halign-left valign-top"><p class="tableblock"><em>{ x, y, z, w }</em></p></td> 9582<td class="tableblock halign-left valign-top"><p class="tableblock">Useful when accessing vectors that represent points or normals</p></td> 9583</tr> 9584<tr> 9585<td class="tableblock halign-left valign-top"><p class="tableblock"><em>{ r, g, b, a }</em></p></td> 9586<td class="tableblock halign-left valign-top"><p class="tableblock">Useful when accessing vectors that represent colors</p></td> 9587</tr> 9588<tr> 9589<td class="tableblock halign-left valign-top"><p class="tableblock"><em>{ s, t, p, q }</em></p></td> 9590<td class="tableblock halign-left valign-top"><p class="tableblock">Useful when accessing vectors that represent texture coordinates</p></td> 9591</tr> 9592</tbody> 9593</table> 9594<div class="paragraph"> 9595<p>The component names <em>x</em>, <em>r</em>, and <em>s</em> are, for example, synonyms for the 9596same (first) component in a vector.</p> 9597</div> 9598<div class="paragraph"> 9599<p>Note that the third component of the texture coordinate set 9600has been renamed <em>p</em> so as to avoid the confusion with <em>r</em> (for 9601red) in a color.</p> 9602</div> 9603<div class="paragraph"> 9604<p>Accessing components beyond those declared for the type is 9605an error so, for example:</p> 9606</div> 9607<div class="listingblock"> 9608<div class="content"> 9609<pre class="CodeRay highlight"><code data-lang="c++">vec2 pos; 9610pos.x <span class="comment">// is legal</span> 9611pos.z <span class="comment">// is illegal</span></code></pre> 9612</div> 9613</div> 9614<div class="paragraph"> 9615<p>The component selection syntax allows multiple components to be selected by 9616appending their names (from the same name set) after the period (<strong>.</strong>).</p> 9617</div> 9618<div class="listingblock"> 9619<div class="content"> 9620<pre class="CodeRay highlight"><code data-lang="c++">vec4 v4; 9621v4.rgba; <span class="comment">// is a vec4 and the same as just using v4,</span> 9622v4.rgb; <span class="comment">// is a vec3,</span> 9623v4.b; <span class="comment">// is a float,</span> 9624v4.xy; <span class="comment">// is a vec2,</span> 9625v4.xgba; <span class="comment">// is illegal - the component names do not come from the same set</span></code></pre> 9626</div> 9627</div> 9628<div class="paragraph"> 9629<p>No more than 4 components can be selected.</p> 9630</div> 9631<div class="listingblock"> 9632<div class="content"> 9633<pre class="CodeRay highlight"><code data-lang="c++">vec4 v4; 9634v4.xyzwxy; <span class="comment">// is illegal since it has 6 components</span> 9635(v4.xyzwxy).xy; <span class="comment">// is illegal since the intermediate value has 6</span> 9636components</code></pre> 9637</div> 9638</div> 9639<div class="paragraph"> 9640<p>The order of the components can be different to swizzle them, or replicated:</p> 9641</div> 9642<div class="listingblock"> 9643<div class="content"> 9644<pre class="CodeRay highlight"><code data-lang="c++">vec4 pos = vec4(<span class="float">1</span><span class="float">.0</span>, <span class="float">2</span><span class="float">.0</span>, <span class="float">3</span><span class="float">.0</span>, <span class="float">4</span><span class="float">.0</span>); 9645vec4 swiz = pos.wzyx; <span class="comment">// swiz = (4.0, 3.0, 2.0, 1.0)</span> 9646vec4 dup = pos.xxyy; <span class="comment">// dup = (1.0, 1.0, 2.0, 2.0)</span></code></pre> 9647</div> 9648</div> 9649<div class="paragraph"> 9650<p>This notation is more concise than the constructor syntax. 9651To form an r-value, it can be applied to any expression that results in a 9652vector r-value.</p> 9653</div> 9654<div class="paragraph"> 9655<p>The component group notation can occur on the left hand side of an 9656expression.</p> 9657</div> 9658<div class="listingblock"> 9659<div class="content"> 9660<pre class="CodeRay highlight"><code data-lang="c++">vec4 pos = vec4(<span class="float">1</span><span class="float">.0</span>, <span class="float">2</span><span class="float">.0</span>, <span class="float">3</span><span class="float">.0</span>, <span class="float">4</span><span class="float">.0</span>); 9661pos.xw = vec2(<span class="float">5</span><span class="float">.0</span>, <span class="float">6</span><span class="float">.0</span>); <span class="comment">// pos = (5.0, 2.0, 3.0, 6.0)</span> 9662pos.wx = vec2(<span class="float">7</span><span class="float">.0</span>, <span class="float">8</span><span class="float">.0</span>); <span class="comment">// pos = (8.0, 2.0, 3.0, 7.0)</span> 9663pos.xx = vec2(<span class="float">3</span><span class="float">.0</span>, <span class="float">4</span><span class="float">.0</span>); <span class="comment">// illegal - 'x' used twice</span> 9664pos.xy = vec3(<span class="float">1</span><span class="float">.0</span>, <span class="float">2</span><span class="float">.0</span>, <span class="float">3</span><span class="float">.0</span>); <span class="comment">// illegal - mismatch between vec2 and vec3</span></code></pre> 9665</div> 9666</div> 9667<div class="paragraph"> 9668<p>To form an l-value, swizzling must further be applied to an l-value and 9669contain no duplicate components. It results in an l-value of scalar or 9670vector type, depending on number of components specified.</p> 9671</div> 9672<div class="paragraph"> 9673<p>Array subscripting syntax can also be applied to vectors (but not to 9674scalars) to provide numeric indexing. 9675So in</p> 9676</div> 9677<div class="listingblock"> 9678<div class="content"> 9679<pre class="CodeRay highlight"><code data-lang="c++">vec4 pos;</code></pre> 9680</div> 9681</div> 9682<div class="paragraph"> 9683<p><em>pos[2]</em> refers to the third element of <em>pos</em> and is equivalent to <em>pos.z</em>. 9684This allows variable indexing into a vector, as well as a generic way of 9685accessing components. 9686Any integer expression can be used as the subscript. 9687The first component is at index zero. 9688Reading from or writing to a vector using a constant integral expression 9689with a value that is negative or greater than or equal to the size of the 9690vector results in an error. 9691When indexing with non-constant expressions, behavior is undefined if the 9692index is negative, or greater than or equal to the size of the vector.</p> 9693</div> 9694<div class="paragraph"> 9695<p>Note that scalars are not considered to be single-component vectors and 9696therefore the use of component selection operators on scalars is illegal.</p> 9697</div> 9698</div> 9699<div class="sect2"> 9700<h3 id="matrix-components">5.6. Matrix Components</h3> 9701<div class="paragraph"> 9702<p>The components of a matrix can be accessed using array subscripting syntax. 9703Applying a single subscript to a matrix treats the matrix as an array of 9704column vectors, and selects a single column, whose type is a vector of the 9705same size as the (column size of the) matrix. 9706The leftmost column is column 0. 9707A second subscript would then operate on the resulting vector, as defined 9708earlier for vectors. 9709Hence, two subscripts select a column and then a row.</p> 9710</div> 9711<div class="listingblock"> 9712<div class="content"> 9713<pre class="CodeRay highlight"><code data-lang="c++">mat4 m; 9714m[<span class="integer">1</span>] = vec4(<span class="float">2</span><span class="float">.0</span>); <span class="comment">// sets the second column to all 2.0</span> 9715m[<span class="integer">0</span>][<span class="integer">0</span>] = <span class="float">1</span><span class="float">.0</span>; <span class="comment">// sets the upper left element to 1.0</span> 9716m[<span class="integer">2</span>][<span class="integer">3</span>] = <span class="float">2</span><span class="float">.0</span>; <span class="comment">// sets the 4th element of the third column to 2.0</span></code></pre> 9717</div> 9718</div> 9719<div class="paragraph"> 9720<p>Behavior is undefined when accessing a component outside the bounds of a 9721matrix with a non-constant expression. 9722It is an error to access a matrix with a constant expression 9723that is outside the bounds of the matrix.</p> 9724</div> 9725</div> 9726<div class="sect2"> 9727<h3 id="structure-and-array-operations">5.7. Structure and Array Operations</h3> 9728<div class="paragraph"> 9729<p>The members of a structure and the <strong>length</strong>() method of an array are 9730selected using the period (<strong>.</strong>).</p> 9731</div> 9732<div class="paragraph"> 9733<p>In total, only the following operators are allowed to operate on arrays and 9734structures as whole entities:</p> 9735</div> 9736<table class="tableblock frame-all grid-all fit-content"> 9737<colgroup> 9738<col> 9739<col> 9740</colgroup> 9741<tbody> 9742<tr> 9743<td class="tableblock halign-left valign-top"><p class="tableblock">field selector</p></td> 9744<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>.</strong></p></td> 9745</tr> 9746<tr> 9747<td class="tableblock halign-left valign-top"><p class="tableblock">equality</p></td> 9748<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>==</strong> <strong>!=</strong></p></td> 9749</tr> 9750<tr> 9751<td class="tableblock halign-left valign-top"><p class="tableblock">assignment</p></td> 9752<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>=</strong></p></td> 9753</tr> 9754<tr> 9755<td class="tableblock halign-left valign-top"><p class="tableblock">Ternary operator</p></td> 9756<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>?:</strong></p></td> 9757</tr> 9758<tr> 9759<td class="tableblock halign-left valign-top"><p class="tableblock">Sequence operator</p></td> 9760<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>,</strong></p></td> 9761</tr> 9762<tr> 9763<td class="tableblock halign-left valign-top"><p class="tableblock">indexing (arrays only)</p></td> 9764<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>[</strong> <strong>]</strong></p></td> 9765</tr> 9766</tbody> 9767</table> 9768<div class="paragraph"> 9769<p>The equality operators and assignment operator are only allowed if the two 9770operands are same size and type. 9771The operands cannot contain any opaque types. 9772Structure types must be of the same declared structure. 9773Both array operands must be 9774compile-time 9775sized. 9776When using the equality operators, two structures are equal if and only if 9777all the members are component-wise equal, and two arrays are equal if and 9778only if all the elements are element-wise equal.</p> 9779</div> 9780<div class="paragraph"> 9781<p>Array elements are accessed using the array subscript operator (<strong>[ ]</strong>). 9782An example of accessing an array element is</p> 9783</div> 9784<div class="listingblock"> 9785<div class="content"> 9786<pre class="CodeRay highlight"><code data-lang="c++">diffuseColor += lightIntensity[<span class="integer">3</span>] * NdotL;</code></pre> 9787</div> 9788</div> 9789<div class="paragraph"> 9790<p>Array indices start at zero. 9791Array elements are accessed using an expression whose type is <strong>int</strong> or 9792<strong>uint</strong>.</p> 9793</div> 9794<div class="paragraph"> 9795<p>Behavior is undefined if a shader subscripts an array with an index less 9796than 0 or greater than or equal to the size the array was declared with.</p> 9797</div> 9798<div class="paragraph"> 9799<p>Arrays can also be accessed with the method operator (<strong>.</strong>) and the <strong>length</strong> 9800method to query the size of the array:</p> 9801</div> 9802<div class="listingblock"> 9803<div class="content"> 9804<pre class="CodeRay highlight"><code data-lang="c++">lightIntensity.length() <span class="comment">// return the size of the array</span></code></pre> 9805</div> 9806</div> 9807</div> 9808<div class="sect2"> 9809<h3 id="assignments">5.8. Assignments</h3> 9810<div class="paragraph"> 9811<p>Assignments of values to variable names are done with the assignment 9812operator (<strong>=</strong>):</p> 9813</div> 9814<div class="dlist"> 9815<dl> 9816<dt class="hdlist1"></dt> 9817<dd> 9818<p><em>lvalue-expression</em> = <em>rvalue-expression</em></p> 9819</dd> 9820</dl> 9821</div> 9822<div class="paragraph"> 9823<p>The <em>lvalue-expression</em> evaluates to an l-value. 9824The assignment operator stores the value of <em>rvalue-expression</em> into the 9825l-value and returns an r-value with the type and precision of 9826<em>lvalue-expression</em>. 9827The <em>lvalue-expression</em> and <em>rvalue-expression</em> must have the same 9828type. 9829Any type-conversions must be specified explicitly via constructors. 9830It is an error if the l-value is not writable. 9831Variables that are built-in types, entire structures or arrays, structure 9832members, l-values with the field selector (<strong>.</strong>) applied to select components 9833or swizzles without repeated fields, l-values within parentheses, and 9834l-values dereferenced with the array subscript operator (<strong>[ ]</strong>) are all 9835l-values. 9836Other binary or unary expressions, function names, swizzles with repeated 9837fields, and constants cannot be l-values. 9838The ternary operator (<strong>?:</strong>) is also not allowed as an l-value. 9839Using an incorrect expression as an l-value results in an error.</p> 9840</div> 9841<div class="paragraph"> 9842<p>Expressions on the left of an assignment are evaluated before expressions on 9843the right of the assignment.</p> 9844</div> 9845<div class="paragraph"> 9846<p>The other assignment operators are</p> 9847</div> 9848<div class="ulist"> 9849<ul> 9850<li> 9851<p>add into (<strong>+=</strong>)</p> 9852</li> 9853<li> 9854<p>subtract from (<strong>-=</strong>)</p> 9855</li> 9856<li> 9857<p>multiply into (<strong>*=</strong>)</p> 9858</li> 9859<li> 9860<p>divide into (<strong>/=</strong>)</p> 9861</li> 9862<li> 9863<p>modulus into (<strong>%=</strong>)</p> 9864</li> 9865<li> 9866<p>left shift by (<strong><<=</strong>)</p> 9867</li> 9868<li> 9869<p>right shift by (<strong>>>=</strong>)</p> 9870</li> 9871<li> 9872<p>and into (<strong>&=</strong>)</p> 9873</li> 9874<li> 9875<p>inclusive-or into (<strong>|=</strong>)</p> 9876</li> 9877<li> 9878<p>exclusive-or into (<strong>^=</strong>)</p> 9879</li> 9880</ul> 9881</div> 9882<div class="paragraph"> 9883<p>where the general expression</p> 9884</div> 9885<div class="dlist"> 9886<dl> 9887<dt class="hdlist1"></dt> 9888<dd> 9889<p><em>lvalue</em> <em>op</em>= <em>expression</em></p> 9890</dd> 9891</dl> 9892</div> 9893<div class="paragraph"> 9894<p>is equivalent to</p> 9895</div> 9896<div class="dlist"> 9897<dl> 9898<dt class="hdlist1"></dt> 9899<dd> 9900<p><em>lvalue</em> = <em>lvalue</em> <em>op</em> <em>expression</em></p> 9901</dd> 9902</dl> 9903</div> 9904<div class="paragraph"> 9905<p>where <em>lvalue</em> is the value returned by <em>lvalue-expression</em>, <em>op</em> is as 9906described below, and the <em>lvalue-expression</em> and <em>expression</em> must satisfy 9907the semantic requirements of both <em>op</em> and equals (<strong>=</strong>).</p> 9908</div> 9909<div class="paragraph"> 9910<p>Reading a variable before writing (or initializing) it is legal, however the 9911value is undefined.</p> 9912</div> 9913</div> 9914<div class="sect2"> 9915<h3 id="expressions">5.9. Expressions</h3> 9916<div class="paragraph"> 9917<p>Expressions in the shading language are built from the following:</p> 9918</div> 9919<div class="ulist"> 9920<ul> 9921<li> 9922<p>Constants of type <strong>bool</strong>, all integral types, all floating-point types, 9923all vector types, and all matrix types.</p> 9924</li> 9925<li> 9926<p>Constructors of all types.</p> 9927</li> 9928<li> 9929<p>Variable names of all types.</p> 9930</li> 9931<li> 9932<p>Arrays with the length method applied.</p> 9933</li> 9934<li> 9935<p>Subscripted arrays.</p> 9936</li> 9937<li> 9938<p>Function calls that return values. 9939In some cases, function calls returning <strong>void</strong> are also allowed in 9940expressions as specified below.</p> 9941</li> 9942<li> 9943<p>Component field selectors and array subscript results.</p> 9944</li> 9945<li> 9946<p>Parenthesized expressions. 9947Any expression, including expressions with void type can be 9948parenthesized. 9949Parentheses can be used to group operations. 9950Operations within parentheses are done before operations across 9951parentheses.</p> 9952</li> 9953<li> 9954<p>The arithmetic binary operators add (<strong>+</strong>), subtract (<strong>-</strong>), multiply 9955(<strong>*</strong>), and divide (<strong>/</strong>) operate on integer and floating-point scalars, 9956vectors, and matrices. 9957If the operands are integral types, they must both be signed or both be 9958unsigned. 9959All arithmetic binary operators result in the same fundamental type 9960(signed integer, unsigned integer, or floating-point) as the operands 9961they operate on. 9962The following cases are valid</p> 9963<div class="ulist"> 9964<ul> 9965<li> 9966<p>The two operands are scalars. 9967In this case the operation is applied, resulting in a scalar.</p> 9968</li> 9969<li> 9970<p>One operand is a scalar, and the other is a vector or matrix. 9971In this case, the scalar operation is applied independently to each 9972component of the vector or matrix, resulting in the same size vector or 9973matrix.</p> 9974</li> 9975<li> 9976<p>The two operands are vectors of the same size. 9977In this case, the operation is done component-wise resulting in the 9978same size vector.</p> 9979</li> 9980<li> 9981<p>The operator is add (<strong>+</strong>), subtract (<strong>-</strong>), or divide (<strong>/</strong>), and the 9982operands are matrices with the same number of rows and the same number 9983of columns. 9984In this case, the operation is done component-wise resulting in the 9985same size matrix.</p> 9986</li> 9987<li> 9988<p>The operator is multiply (<strong>*</strong>), where both operands are matrices or one 9989operand is a vector and the other a matrix. 9990A right vector operand is treated as a column vector and a left vector 9991operand as a row vector. 9992In all these cases, it is required that the number of columns of the 9993left operand is equal to the number of rows of the right operand. 9994Then, the multiply (<strong>*</strong>) operation does a linear algebraic multiply, 9995yielding an object that has the same number of rows as the left operand 9996and the same number of columns as the right operand. 9997“<a href="#vector-and-matrix-operations">Vector and Matrix Operations</a>” 9998explains in more detail how vectors and matrices are operated on.</p> 9999<div class="openblock"> 10000<div class="content"> 10001<div class="paragraph"> 10002<p>All other cases result in an error.</p> 10003</div> 10004<div class="paragraph"> 10005<p>Use the built-in functions <strong>dot</strong>, <strong>cross</strong>, <strong>matrixCompMult</strong>, and 10006<strong>outerProduct</strong>, to get, respectively, vector dot product, vector cross 10007product, matrix component-wise multiplication, and the matrix product of a 10008column vector times a row vector.</p> 10009</div> 10010</div> 10011</div> 10012</li> 10013</ul> 10014</div> 10015</li> 10016<li> 10017<p>The operator modulus (<strong>%</strong>) operates on signed or unsigned integers or 10018integer vectors. 10019The operand types must both be signed or both be unsigned. 10020The operands cannot be vectors of differing size; this is 10021an error. 10022If one operand is a scalar and the other vector, then the scalar is 10023applied component-wise to the vector, resulting in the same type as the 10024vector. 10025If both are vectors of the same size, the result is computed 10026component-wise. 10027The resulting value is undefined for any component computed with a 10028second operand that is zero, while results for other components with 10029non-zero second operands remain defined. 10030If both operands are non-negative, then the remainder is non-negative. 10031Results are undefined if one or both operands are negative. 10032The operator modulus (<strong>%</strong>) is not defined for any other data types 10033(non-integer types).</p> 10034</li> 10035<li> 10036<p>The arithmetic unary operators negate (<strong>-</strong>), post- and pre-increment and 10037decrement (<strong>--</strong> and <strong>++</strong>) operate on integer or floating-point values 10038(including vectors and matrices). 10039All unary operators work component-wise on their operands. 10040These result with the same type they operated on. 10041For post- and pre-increment and decrement, the expression must be a writable 10042l-value. 10043Pre-increment and pre-decrement add or subtract 1 or 1.0 to the contents 10044of the expression they operate on, and the value of the pre-increment or 10045pre-decrement expression is the resulting value of that modification. 10046Post-increment and post-decrement expressions add or subtract 1 or 1.0 10047to the contents of the expression they operate on, but the resulting 10048expression has the expression’s value before the post-increment or 10049post-decrement was executed.</p> 10050</li> 10051<li> 10052<p>The relational operators greater than (<strong>></strong>), less than (<strong><</strong>), greater 10053than or equal (<strong>>=</strong>), and less than or equal (<strong><=</strong>) operate only on 10054scalar integer and scalar floating-point expressions. 10055The result is scalar Boolean. 10056The types of the operands must match. 10057To do component-wise relational comparisons on vectors, use the built-in 10058functions <strong>lessThan</strong>, <strong>lessThanEqual</strong>, <strong>greaterThan</strong>, and 10059<strong>greaterThanEqual.</strong></p> 10060</li> 10061<li> 10062<p>The equality operators <strong>equal</strong> (<strong>==</strong>), and not equal (<strong>!=</strong>) operate on 10063all types except opaque types. 10064They result in a scalar Boolean. 10065The types of the operands must match. 10066For vectors, matrices, structures, and arrays, all components, members, 10067or elements of one operand must equal the corresponding components, 10068members, or elements in the other operand for the operands to be 10069considered equal. 10070To get a vector of component-wise equality results for vectors, use the 10071built-in functions <strong>equal</strong> and <strong>notEqual</strong>.</p> 10072</li> 10073<li> 10074<p>The logical binary operators and (<strong>&&</strong>), or (<strong>||</strong>), and exclusive or 10075(<strong>^^</strong>) operate only on two Boolean expressions and result in a Boolean 10076expression. 10077And (<strong>&&</strong>) will only evaluate the right hand operand if the left hand 10078operand evaluated to <strong>true</strong>. 10079Or (<strong>||</strong>) will only evaluate the right hand operand if the left hand 10080operand evaluated to <strong>false</strong>. 10081Exclusive or (<strong>^^</strong>) will always evaluate both operands.</p> 10082</li> 10083<li> 10084<p>The logical unary operator not (<strong>!</strong>). 10085It operates only on a Boolean expression and results in a Boolean 10086expression. 10087To operate on a vector, use the built-in function <strong>not</strong>.</p> 10088</li> 10089<li> 10090<p>The sequence (<strong>,</strong>) operator that operates on expressions by returning 10091the type and value of the right-most expression in a comma separated 10092list of expressions. 10093All expressions are evaluated, in order, from left to right. 10094The operands to the sequence operator may have <strong>void</strong> type. 10095Opaque types cannot be used with the sequence (,) operator.</p> 10096</li> 10097<li> 10098<p>The ternary selection operator (<strong>?:</strong>). 10099It operates on three expressions (<em>exp1</em> <strong>?</strong> <em>exp2</em> <strong>:</strong> <em>exp3</em>). 10100This operator evaluates the first expression, which must result in a 10101scalar Boolean. 10102If the result is true, it selects to evaluate the second expression, 10103otherwise it selects to evaluate the third expression. 10104Only one of the second and third expressions is evaluated. 10105The second and third expressions cannot be opaque types, 10106or there will be an error. 10107Otherwise, 10108the second and third expressions can be any type, including <strong>void</strong>, as 10109long their types match. 10110This resulting matching type is the type of the entire expression.</p> 10111</li> 10112<li> 10113<p>The one’s complement operator (<strong>~</strong>). 10114The operand must be of type signed or unsigned integer or integer 10115vector, and the result is the one’s complement of its operand; each bit 10116of each component is complemented, including any sign bits.</p> 10117</li> 10118<li> 10119<p>The shift operators (<strong><<</strong>) and (<strong>>></strong>). 10120For both operators, the operands must be signed or unsigned integers or 10121integer vectors. 10122One operand can be signed while the other is unsigned. 10123In all cases, the resulting type will be the same type as the left 10124operand. 10125If the first operand is a scalar, the second operand has to be a scalar 10126as well. 10127If the first operand is a vector, the second operand must be a scalar or 10128a vector with the same size as the first operand, and the result is 10129computed component-wise. 10130The result is undefined if the right operand is negative, or greater 10131than or equal to the number of bits in the left expression’s base type. 10132The value of E1 << E2 is E1 (interpreted as a bit pattern) left-shifted 10133by E2 bits. 10134The value of E1 >> E2 is E1 right-shifted by E2 bit positions. 10135If E1 is a signed integer, the right-shift will extend the sign bit. 10136If E1 is an unsigned integer, the right-shift will zero-extend.</p> 10137</li> 10138<li> 10139<p>The bitwise operators and (<strong>&</strong>), exclusive-or (<strong>^</strong>), and inclusive-or 10140(<strong>|</strong>). 10141The operands must be of type signed or unsigned integers or integer 10142vectors. 10143The operands cannot be vectors of differing size; this is an error. 10144If one operand is a scalar and the other a vector, the scalar is applied 10145component-wise to the vector, resulting in the same type as the vector. 10146The fundamental types of the operands (signed or unsigned) must match, 10147and will be the resulting fundamental type. 10148For and (<strong>&</strong>), the result is the bitwise-and function of the operands. 10149For exclusive-or (<strong>^</strong>), the result is the bitwise exclusive-or function 10150of the operands. 10151For inclusive-or (<strong>|</strong>), the result is the bitwise inclusive-or function 10152of the operands.</p> 10153</li> 10154</ul> 10155</div> 10156<div class="paragraph"> 10157<p>For a complete specification of the syntax of expressions, see 10158“<a href="#shading-language-grammar">Shading Language Grammar</a>”.</p> 10159</div> 10160</div> 10161<div class="sect2"> 10162<h3 id="vector-and-matrix-operations">5.10. Vector and Matrix Operations</h3> 10163<div class="paragraph"> 10164<p>With a few exceptions, operations are component-wise. 10165Usually, when an operator operates on a vector or matrix, it is operating 10166independently on each component of the vector or matrix, in a component-wise 10167fashion. 10168For example,</p> 10169</div> 10170<div class="listingblock"> 10171<div class="content"> 10172<pre class="CodeRay highlight"><code data-lang="c++">vec3 v, u; 10173<span class="predefined-type">float</span> f; 10174v = u + f;</code></pre> 10175</div> 10176</div> 10177<div class="paragraph"> 10178<p>will be equivalent to</p> 10179</div> 10180<div class="listingblock"> 10181<div class="content"> 10182<pre class="CodeRay highlight"><code data-lang="c++">v.x = u.x + f; 10183v.y = u.y + f; 10184v.z = u.z + f;</code></pre> 10185</div> 10186</div> 10187<div class="paragraph"> 10188<p>And</p> 10189</div> 10190<div class="listingblock"> 10191<div class="content"> 10192<pre class="CodeRay highlight"><code data-lang="c++">vec3 v, u, w; 10193w = v + u;</code></pre> 10194</div> 10195</div> 10196<div class="paragraph"> 10197<p>will be equivalent to</p> 10198</div> 10199<div class="listingblock"> 10200<div class="content"> 10201<pre class="CodeRay highlight"><code data-lang="c++">w.x = v.x + u.x; 10202w.y = v.y + u.y; 10203w.z = v.z + u.z;</code></pre> 10204</div> 10205</div> 10206<div class="paragraph"> 10207<p>and likewise for most operators and all integer and floating-point vector 10208and matrix types. 10209The exceptions are matrix multiplied by vector, vector multiplied by matrix, 10210and matrix multiplied by matrix. 10211These do not operate component-wise, but rather perform the correct linear 10212algebraic multiply.</p> 10213</div> 10214<div class="listingblock"> 10215<div class="content"> 10216<pre class="CodeRay highlight"><code data-lang="c++">vec3 v, u; 10217mat3 m; 10218u = v * m;</code></pre> 10219</div> 10220</div> 10221<div class="paragraph"> 10222<p>is equivalent to</p> 10223</div> 10224<div class="listingblock"> 10225<div class="content"> 10226<pre class="CodeRay highlight"><code data-lang="c++">u.x = dot(v, m[<span class="integer">0</span>]); <span class="comment">// m[0] is the left column of m</span> 10227u.y = dot(v, m[<span class="integer">1</span>]); <span class="comment">// dot(a,b) is the inner (dot) product of a and b</span> 10228u.z = dot(v, m[<span class="integer">2</span>]);</code></pre> 10229</div> 10230</div> 10231<div class="paragraph"> 10232<p>And</p> 10233</div> 10234<div class="listingblock"> 10235<div class="content"> 10236<pre class="CodeRay highlight"><code data-lang="c++">u = m * v;</code></pre> 10237</div> 10238</div> 10239<div class="paragraph"> 10240<p>is equivalent to</p> 10241</div> 10242<div class="listingblock"> 10243<div class="content"> 10244<pre class="CodeRay highlight"><code data-lang="c++">u.x = m[<span class="integer">0</span>].x * v.x + m[<span class="integer">1</span>].x * v.y + m[<span class="integer">2</span>].x * v.z; 10245u.y = m[<span class="integer">0</span>].y * v.x + m[<span class="integer">1</span>].y * v.y + m[<span class="integer">2</span>].y * v.z; 10246u.z = m[<span class="integer">0</span>].z * v.x + m[<span class="integer">1</span>].z * v.y + m[<span class="integer">2</span>].z * v.z;</code></pre> 10247</div> 10248</div> 10249<div class="paragraph"> 10250<p>And</p> 10251</div> 10252<div class="listingblock"> 10253<div class="content"> 10254<pre class="CodeRay highlight"><code data-lang="c++">mat3 m, n, r; 10255r = m * n;</code></pre> 10256</div> 10257</div> 10258<div class="paragraph"> 10259<p>is equivalent to</p> 10260</div> 10261<div class="listingblock"> 10262<div class="content"> 10263<pre class="CodeRay highlight"><code data-lang="c++">r[<span class="integer">0</span>].x = m[<span class="integer">0</span>].x * n[<span class="integer">0</span>].x + m[<span class="integer">1</span>].x * n[<span class="integer">0</span>].y + m[<span class="integer">2</span>].x * n[<span class="integer">0</span>].z; 10264r[<span class="integer">1</span>].x = m[<span class="integer">0</span>].x * n[<span class="integer">1</span>].x + m[<span class="integer">1</span>].x * n[<span class="integer">1</span>].y + m[<span class="integer">2</span>].x * n[<span class="integer">1</span>].z; 10265r[<span class="integer">2</span>].x = m[<span class="integer">0</span>].x * n[<span class="integer">2</span>].x + m[<span class="integer">1</span>].x * n[<span class="integer">2</span>].y + m[<span class="integer">2</span>].x * n[<span class="integer">2</span>].z; 10266r[<span class="integer">0</span>].y = m[<span class="integer">0</span>].y * n[<span class="integer">0</span>].x + m[<span class="integer">1</span>].y * n[<span class="integer">0</span>].y + m[<span class="integer">2</span>].y * n[<span class="integer">0</span>].z; 10267r[<span class="integer">1</span>].y = m[<span class="integer">0</span>].y * n[<span class="integer">1</span>].x + m[<span class="integer">1</span>].y * n[<span class="integer">1</span>].y + m[<span class="integer">2</span>].y * n[<span class="integer">1</span>].z; 10268r[<span class="integer">2</span>].y = m[<span class="integer">0</span>].y * n[<span class="integer">2</span>].x + m[<span class="integer">1</span>].y * n[<span class="integer">2</span>].y + m[<span class="integer">2</span>].y * n[<span class="integer">2</span>].z; 10269r[<span class="integer">0</span>].z = m[<span class="integer">0</span>].z * n[<span class="integer">0</span>].x + m[<span class="integer">1</span>].z * n[<span class="integer">0</span>].y + m[<span class="integer">2</span>].z * n[<span class="integer">0</span>].z; 10270r[<span class="integer">1</span>].z = m[<span class="integer">0</span>].z * n[<span class="integer">1</span>].x + m[<span class="integer">1</span>].z * n[<span class="integer">1</span>].y + m[<span class="integer">2</span>].z * n[<span class="integer">1</span>].z; 10271r[<span class="integer">2</span>].z = m[<span class="integer">0</span>].z * n[<span class="integer">2</span>].x + m[<span class="integer">1</span>].z * n[<span class="integer">2</span>].y + m[<span class="integer">2</span>].z * n[<span class="integer">2</span>].z;</code></pre> 10272</div> 10273</div> 10274<div class="paragraph"> 10275<p>and similarly for other sizes of vectors and matrices.</p> 10276</div> 10277</div> 10278<div class="sect2"> 10279<h3 id="specialization-constant-operations">5.11. Specialization-Constant Operations</h3> 10280<div class="paragraph"> 10281<p>Specialization-constant operations are only available when targeting SPIR-V.</p> 10282</div> 10283<div class="paragraph"> 10284<p>Only some operations discussed in this section may be applied to a 10285specialization constant and still yield a result that is a specialization 10286constant. 10287The operations that do so are listed below. 10288When a specialization constant is operated on with one of these operators 10289and with another constant or specialization constant, the result is 10290implicitly a specialization constant.</p> 10291</div> 10292<div class="ulist"> 10293<ul> 10294<li> 10295<p><strong>int</strong>(), <strong>uint</strong>(), and <strong>bool</strong>() constructors for type conversions from 10296any of the following types to any of the following types:</p> 10297<div class="ulist"> 10298<ul> 10299<li> 10300<p><strong>int</strong></p> 10301</li> 10302<li> 10303<p><strong>uint</strong></p> 10304</li> 10305<li> 10306<p><strong>bool</strong></p> 10307</li> 10308</ul> 10309</div> 10310</li> 10311<li> 10312<p>vector versions of the above conversion constructors</p> 10313</li> 10314<li> 10315<p>allowed implicit conversions of the above</p> 10316</li> 10317<li> 10318<p>swizzles (e.g. <code>foo.yx</code>)</p> 10319</li> 10320<li> 10321<p>the following when applied to integer or unsigned integer types:</p> 10322<div class="ulist"> 10323<ul> 10324<li> 10325<p>unary negative (<strong>-</strong>)</p> 10326</li> 10327<li> 10328<p>binary operations (<strong>+</strong>, <strong>-</strong>, <strong>*</strong>, <strong>/</strong>, <strong>%</strong>)</p> 10329</li> 10330<li> 10331<p>shift (<strong><<</strong>, <strong>>></strong>)</p> 10332</li> 10333<li> 10334<p>bitwise operations (<strong>&</strong>, <strong>|</strong>, <strong>^</strong>)</p> 10335</li> 10336</ul> 10337</div> 10338</li> 10339<li> 10340<p>the following when applied to integer or unsigned integer scalar types:</p> 10341<div class="ulist"> 10342<ul> 10343<li> 10344<p>comparison (<strong>==</strong>, <strong>!=</strong>, <strong>></strong>, <strong>>=</strong>, <strong><</strong>, <strong>⇐</strong>)</p> 10345</li> 10346</ul> 10347</div> 10348</li> 10349<li> 10350<p>The following when applied to the Boolean scalar type:</p> 10351<div class="ulist"> 10352<ul> 10353<li> 10354<p>not (<strong>!</strong>)</p> 10355</li> 10356<li> 10357<p>logical operations (<strong>&&</strong>, <strong>||</strong>, <strong>^^</strong>)</p> 10358</li> 10359<li> 10360<p>comparison (<strong>==</strong>, <strong>!=</strong>)</p> 10361</li> 10362</ul> 10363</div> 10364</li> 10365<li> 10366<p>the ternary operator (<strong>?:</strong>)</p> 10367</li> 10368</ul> 10369</div> 10370</div> 10371<div class="sect2"> 10372<h3 id="evaluation-of-expressions">5.12. Evaluation of Expressions</h3> 10373<div class="paragraph"> 10374<p>In general expressions must be evaluated in the order specified by the 10375precedence of operations and may only be regrouped if the result is the same or 10376where the result is undefined. 10377No other transforms may be applied that affect the result of an operation. 10378GLSL ES relaxes these requirements for scalar operations in the following 10379ways:</p> 10380</div> 10381<div class="ulist"> 10382<ul> 10383<li> 10384<p>Addition and multiplication are assumed to be associative.</p> 10385</li> 10386<li> 10387<p>Multiplication is assumed to be distributive over addition. 10388Therefore expressions may be expanded and re-factored.</p> 10389</li> 10390<li> 10391<p>Floating-point division may be replaced by reciprocal and 10392multiplication.</p> 10393</li> 10394<li> 10395<p>Multiplication may be replaced by repeated addition.</p> 10396</li> 10397<li> 10398<p>Within the constraints of invariance (where applicable), the precision 10399used may vary.</p> 10400</li> 10401</ul> 10402</div> 10403<div class="paragraph"> 10404<p>These rules also apply to the built-in functions.</p> 10405</div> 10406</div> 10407</div> 10408</div> 10409<div class="sect1"> 10410<h2 id="statements-and-structure">6. Statements and Structure</h2> 10411<div class="sectionbody"> 10412<div class="paragraph"> 10413<p>The fundamental building blocks of the OpenGL ES Shading Language are:</p> 10414</div> 10415<div class="ulist"> 10416<ul> 10417<li> 10418<p>statements and declarations</p> 10419</li> 10420<li> 10421<p>function definitions</p> 10422</li> 10423<li> 10424<p>selection (<strong>if</strong>-<strong>else</strong> and <strong>switch</strong>-<strong>case</strong>-<strong>default</strong>)</p> 10425</li> 10426<li> 10427<p>iteration (<strong>for</strong>, <strong>while</strong>, and <strong>do</strong>-<strong>while</strong>)</p> 10428</li> 10429<li> 10430<p>jumps (<strong>discard</strong>, <strong>return</strong>, <strong>break</strong>, and <strong>continue</strong>)</p> 10431</li> 10432</ul> 10433</div> 10434<div class="paragraph"> 10435<p>The overall structure of a shader is as follows</p> 10436</div> 10437<div class="openblock bnf"> 10438<div class="content"> 10439<div class="dlist"> 10440<dl> 10441<dt class="hdlist1"><em>translation-unit</em> : </dt> 10442<dd> 10443<p><em>global-declaration</em><br> 10444<em>translation-unit</em> <em>global-declaration</em></p> 10445</dd> 10446<dt class="hdlist1"><em>global-declaration</em> : </dt> 10447<dd> 10448<p><em>function-definition</em><br> 10449<em>declaration</em></p> 10450</dd> 10451</dl> 10452</div> 10453</div> 10454</div> 10455<div class="paragraph"> 10456<p>That is, a shader is a sequence of declarations and function bodies. 10457Function bodies are defined as</p> 10458</div> 10459<div class="openblock bnf"> 10460<div class="content"> 10461<div class="dlist"> 10462<dl> 10463<dt class="hdlist1"><em>function-definition</em> : </dt> 10464<dd> 10465<p><em>function-prototype</em> <strong>{</strong> <em>statement-list</em> <strong>}</strong></p> 10466</dd> 10467<dt class="hdlist1"><em>statement-list</em> : </dt> 10468<dd> 10469<p><em>statement</em><br> 10470<em>statement-list</em> <em>statement</em></p> 10471</dd> 10472<dt class="hdlist1"><em>statement</em> : </dt> 10473<dd> 10474<p><em>compound-statement</em><br> 10475<em>simple-statement</em></p> 10476</dd> 10477</dl> 10478</div> 10479</div> 10480</div> 10481<div class="paragraph"> 10482<p>Curly braces are used to group sequences of statements into compound 10483statements.</p> 10484</div> 10485<div class="openblock bnf"> 10486<div class="content"> 10487<div class="dlist"> 10488<dl> 10489<dt class="hdlist1"><em>compound-statement</em> : </dt> 10490<dd> 10491<p><strong>{</strong> <em>statement-list</em> <strong>}</strong></p> 10492</dd> 10493<dt class="hdlist1"><em>simple-statement</em> : </dt> 10494<dd> 10495<p><em>declaration-statement</em><br> 10496<em>expression-statement</em><br> 10497<em>selection-statement</em><br> 10498<em>iteration-statement</em><br> 10499<em>jump-statement</em></p> 10500</dd> 10501</dl> 10502</div> 10503</div> 10504</div> 10505<div class="paragraph"> 10506<p>Simple declaration, expression, and jump statements end in a semi-colon.</p> 10507</div> 10508<div class="paragraph"> 10509<p>This above is slightly simplified, and the complete grammar specified in 10510“<a href="#shading-language-grammar">Shading Language Grammar</a>” should be used as 10511the definitive specification.</p> 10512</div> 10513<div class="paragraph"> 10514<p>Declarations and expressions have already been discussed.</p> 10515</div> 10516<div class="sect2"> 10517<h3 id="function-definitions">6.1. Function Definitions</h3> 10518<div class="paragraph"> 10519<p>As indicated by the grammar above, a valid shader is a sequence of global 10520declarations and function definitions. 10521A function is declared as the following example shows:</p> 10522</div> 10523<div class="listingblock"> 10524<div class="content"> 10525<pre class="CodeRay highlight"><code data-lang="c++"><span class="comment">// prototype</span> 10526returnType functionName (type0 arg0, type1 arg1, ..., typen argn);</code></pre> 10527</div> 10528</div> 10529<div class="paragraph"> 10530<p>and a function is defined like</p> 10531</div> 10532<div class="listingblock"> 10533<div class="content"> 10534<pre class="CodeRay highlight"><code data-lang="c++"><span class="comment">// definition</span> 10535returnType functionName (type0 arg0, type1 arg1, ..., typen argn) 10536{ 10537 <span class="comment">// do some computation</span> 10538 <span class="keyword">return</span> returnValue; 10539}</code></pre> 10540</div> 10541</div> 10542<div class="paragraph"> 10543<p>where <em>returnType</em> must be present and cannot be void, or:</p> 10544</div> 10545<div class="listingblock"> 10546<div class="content"> 10547<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span> functionName (type0 arg0, type1 arg1, ..., typen argn) 10548{ 10549 <span class="comment">// do some computation</span> 10550 <span class="keyword">return</span>; <span class="comment">// optional</span> 10551}</code></pre> 10552</div> 10553</div> 10554<div class="paragraph"> 10555<p>Each of the <em>typeN</em> must include a type and can optionally include a 10556parameter qualifier and/or <strong>const</strong>.</p> 10557</div> 10558<div class="paragraph"> 10559<p>A function is called by using its name followed by a list of arguments in 10560parentheses.</p> 10561</div> 10562<div class="paragraph"> 10563<p>Arrays are allowed as arguments and as the return type. 10564In both cases, the array must be 10565compile-time 10566sized. 10567An array is passed or returned by using just its name, without brackets, and 10568the size of the array must match the size specified in the function’s 10569declaration.</p> 10570</div> 10571<div class="paragraph"> 10572<p>Structures are also allowed as argument types. 10573The return type can also be a structure.</p> 10574</div> 10575<div class="paragraph"> 10576<p>See “<a href="#shading-language-grammar">Shading Language Grammar</a>” for the 10577definitive reference on the syntax to declare and define functions.</p> 10578</div> 10579<div class="paragraph"> 10580<p>All functions must be either declared with a prototype or defined with a 10581body before they are called. 10582For example:</p> 10583</div> 10584<div class="listingblock"> 10585<div class="content"> 10586<pre class="CodeRay highlight"><code data-lang="c++"><span class="predefined-type">float</span> myfunc (<span class="predefined-type">float</span> f, <span class="comment">// f is an input parameter</span> 10587 out <span class="predefined-type">float</span> g); <span class="comment">// g is an output parameter</span></code></pre> 10588</div> 10589</div> 10590<div class="paragraph"> 10591<p>Functions that return no value must be declared as <strong>void</strong>. 10592A <strong>void</strong> function can only use <strong>return</strong> without a return argument, even if 10593the return argument has <strong>void</strong> type. 10594Return statements only accept values:</p> 10595</div> 10596<div class="listingblock"> 10597<div class="content"> 10598<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span> func1() { } 10599<span class="directive">void</span> func2() { <span class="keyword">return</span> func1(); } <span class="comment">// illegal return statement</span></code></pre> 10600</div> 10601</div> 10602<div class="paragraph"> 10603<p>Only a precision qualifier is allowed on the return type of a function. 10604Formal parameters can have parameter, precision, and memory qualifiers, but 10605no other qualifiers.</p> 10606</div> 10607<div class="paragraph"> 10608<p>Functions that accept no input arguments need not use <strong>void</strong> in the argument 10609list because prototypes (or definitions) are required and therefore there is 10610no ambiguity when an empty argument list “( )” is declared. 10611The idiom “(<strong>void</strong>)” as a parameter list is provided for convenience.</p> 10612</div> 10613<div class="paragraph"> 10614<p>Function names can be overloaded. 10615The same function name can be used for multiple functions, as long as the 10616parameter types differ. 10617If a function name is declared twice with the same parameter types, then the 10618return types and all qualifiers must also match, and it is the same function 10619being declared. 10620When function calls are resolved, an exact type match for all the arguments 10621is required.</p> 10622</div> 10623<div class="paragraph"> 10624<p>For example,</p> 10625</div> 10626<div class="listingblock"> 10627<div class="content"> 10628<pre class="CodeRay highlight"><code data-lang="c++">vec4 f(in vec4 x, out vec4 y); 10629vec4 f(in vec4 x, out uvec4 y); <span class="comment">// allowed, different argument type</span> 10630<span class="predefined-type">int</span> f(in vec4 x, out vec4 y); <span class="comment">// error, only return type differs</span> 10631vec4 f(in vec4 x, in vec4 y); <span class="comment">// error, only qualifier differs</span> 10632vec4 f(<span class="directive">const</span> in vec4 x, out vec4 y); <span class="comment">// error, only qualifier differs</span></code></pre> 10633</div> 10634</div> 10635<div class="paragraph"> 10636<p>Calling the first two functions above with the following argument types 10637yields</p> 10638</div> 10639<div class="listingblock"> 10640<div class="content"> 10641<pre class="CodeRay highlight"><code data-lang="c++">f(vec4, vec4) <span class="comment">// exact match of vec4 f(in vec4 x, out vec4 y)</span> 10642f(vec4, uvec4) <span class="comment">// exact match of vec4 f(in vec4 x, out uvec4 y)</span> 10643f(ivec4, vec4) <span class="comment">// error, no exact match.</span> 10644f(ivec4, uvec4) <span class="comment">// error, no exact match.</span></code></pre> 10645</div> 10646</div> 10647<div class="paragraph"> 10648<p>User-defined functions can have multiple declarations, but only one 10649definition.</p> 10650</div> 10651<div class="paragraph"> 10652<p>A shader cannot redefine or overload built-in functions.</p> 10653</div> 10654<div class="paragraph"> 10655<p>The function <em>main</em> is used as the entry point to a shader executable. 10656All shaders must define a function named <em>main</em>. 10657This function takes no arguments, returns no value, and must be declared as 10658type <strong>void</strong>:</p> 10659</div> 10660<div class="listingblock"> 10661<div class="content"> 10662<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">void</span> main() 10663{ 10664 ... 10665}</code></pre> 10666</div> 10667</div> 10668<div class="paragraph"> 10669<p>The function <em>main</em> can contain uses of <strong>return</strong>. 10670See “<a href="#jumps">Jumps</a>” for more details.</p> 10671</div> 10672<div class="paragraph"> 10673<p>It is a compile-time or link-time error to declare or define a function 10674<strong>main</strong> with any other parameters or return type.</p> 10675</div> 10676<div class="sect3"> 10677<h4 id="function-calling-conventions">6.1.1. Function Calling Conventions</h4> 10678<div class="paragraph"> 10679<p>Functions are called by value-return. 10680This means input arguments are copied into the function at call time, and 10681output arguments are copied back to the caller before function exit. 10682Because the function works with local copies of parameters, there are no 10683issues regarding aliasing of variables within a function. 10684To control what parameters are copied in and/or out through a function 10685definition or declaration:</p> 10686</div> 10687<div class="ulist"> 10688<ul> 10689<li> 10690<p>The keyword <strong>in</strong> is used as a qualifier to denote a parameter is to be 10691copied in, but not copied out.</p> 10692</li> 10693<li> 10694<p>The keyword <strong>out</strong> is used as a qualifier to denote a parameter is to be 10695copied out, but not copied in. 10696This should be used whenever possible to avoid unnecessarily copying 10697parameters in.</p> 10698</li> 10699<li> 10700<p>The keyword <strong>inout</strong> is used as a qualifier to denote the parameter is to 10701be both copied in and copied out. 10702It means the same thing as specifying both <strong>in</strong> and <strong>out</strong>.</p> 10703</li> 10704<li> 10705<p>A function parameter declared with no such qualifier means the same 10706thing as specifying <strong>in</strong>.</p> 10707</li> 10708</ul> 10709</div> 10710<div class="paragraph"> 10711<p>All arguments are evaluated at call time, exactly once, in order, from left 10712to right. 10713Evaluation of an <strong>in</strong> parameter results in a value that is copied to the 10714formal parameter. 10715Evaluation of an <strong>out</strong> parameter results in an l-value that is used to copy 10716out a value when the function returns. 10717Evaluation of an <strong>inout</strong> parameter results in both a value and an l-value; 10718the value is copied to the formal parameter at call time and the l-value is 10719used to copy out a value when the function returns.</p> 10720</div> 10721<div class="paragraph"> 10722<p>The order in which output parameters are copied back to the caller is 10723undefined.</p> 10724</div> 10725<div class="paragraph"> 10726<p>In a function, writing to an input-only parameter is allowed. 10727Only the function’s copy is modified. 10728This can be prevented by declaring a parameter with the <strong>const</strong> qualifier.</p> 10729</div> 10730<div class="paragraph"> 10731<p>When calling a function, expressions that do not evaluate to l-values cannot 10732be passed to parameters declared as <strong>out</strong> or <strong>inout</strong>, or an error 10733results.</p> 10734</div> 10735<div class="paragraph"> 10736<p>Only precision qualifiers are allowed on the return type of a function.</p> 10737</div> 10738<div class="paragraph"> 10739<p>The syntax for function prototypes can be informally expressed as:</p> 10740</div> 10741<div class="openblock bnf"> 10742<div class="content"> 10743<div class="dlist"> 10744<dl> 10745<dt class="hdlist1"><em>function_prototype</em> : </dt> 10746<dd> 10747<p>[ <em>type_qualifier</em> ] <em>type_specifier</em> <em>IDENTIFIER</em> <em>LEFT_PAREN</em> 10748<em>parameter_declaration</em> , <em>parameter_declaration</em> , …​ 10749, <em>RIGHT_PAREN</em></p> 10750</dd> 10751<dt class="hdlist1"><em>parameter_declaration</em> : </dt> 10752<dd> 10753<p>[ <em>type_qualifier</em> ] <em>type_specifier</em> [ <em>IDENTIFIER</em> [ <em>array_specifier</em> 10754] ]</p> 10755</dd> 10756<dt class="hdlist1"><em>type_qualifier</em> : </dt> 10757<dd> 10758<p><em>single_type_qualifier</em> , <em>single_type_qualifier</em> , …​</p> 10759</dd> 10760</dl> 10761</div> 10762</div> 10763</div> 10764<div class="paragraph"> 10765<p>The qualifiers allowed on formal parameters are:</p> 10766</div> 10767<div class="openblock bnf"> 10768<div class="content"> 10769<div class="dlist"> 10770<dl> 10771<dt class="hdlist1"></dt> 10772<dd> 10773<p><em>empty</em><br> 10774<strong>const</strong><br> 10775<strong>in</strong><br> 10776<strong>out</strong><br> 10777<strong>inout</strong><br> 10778<strong>precise</strong><br> 10779<em>memory-qualifier</em><br> 10780<em>precision-qualifier</em></p> 10781</dd> 10782</dl> 10783</div> 10784</div> 10785</div> 10786<div class="paragraph"> 10787<p>The <strong>const</strong> qualifier cannot be used with <strong>out</strong> or <strong>inout</strong>, or 10788an error results. 10789The above is used both for function declarations (i.e., prototypes) and for 10790function definitions. 10791Hence, function definitions can have unnamed arguments.</p> 10792</div> 10793<div class="paragraph"> 10794<p>Static, and hence dynamic recursion, are not allowed. 10795Static recursion is present if the static function-call graph of a program 10796contains cycles. 10797Dynamic recursion occurs if at any time control flow has entered but not 10798exited a single function more than once.</p> 10799</div> 10800</div> 10801</div> 10802<div class="sect2"> 10803<h3 id="selection">6.2. Selection</h3> 10804<div class="paragraph"> 10805<p>Conditional control flow in the shading language is done by either <strong>if</strong>, 10806<strong>if</strong>-<strong>else</strong>, or <strong>switch</strong> statements:</p> 10807</div> 10808<div class="openblock bnf"> 10809<div class="content"> 10810<div class="dlist"> 10811<dl> 10812<dt class="hdlist1"><em>selection-statement</em> : </dt> 10813<dd> 10814<p><strong>if</strong> <strong>(</strong> <em>bool-expression</em> <strong>)</strong> <em>statement</em><br> 10815<strong>if</strong> <strong>(</strong> <em>bool-expression</em> <strong>)</strong> <em>statement</em> <strong>else</strong> <em>statement</em><br> 10816<strong>switch</strong> <strong>(</strong> <em>init-expression</em> <strong>)</strong> <strong>{</strong> <em>switch-statement-list<sub>opt</sub></em> <strong>}</strong></p> 10817</dd> 10818</dl> 10819</div> 10820</div> 10821</div> 10822<div class="paragraph"> 10823<p>Where <em>switch-statement-list</em> is a nested scope containing a list of zero or 10824more <em>switch-statement</em> and other statements defined by the language, where 10825<em>switch-statement</em> adds some forms of labels. 10826That is</p> 10827</div> 10828<div class="openblock bnf"> 10829<div class="content"> 10830<div class="dlist"> 10831<dl> 10832<dt class="hdlist1"><em>switch-statement-list</em> : </dt> 10833<dd> 10834<p><em>switch-statement</em><br> 10835<em>switch-statement-list</em> <em>switch-statement</em></p> 10836</dd> 10837<dt class="hdlist1"><em>switch-statement</em> : </dt> 10838<dd> 10839<p><strong>case</strong> <em>constant-expression</em> <strong>:</strong><br> 10840<strong>default</strong> <strong>:</strong> <em>statement</em></p> 10841</dd> 10842</dl> 10843</div> 10844</div> 10845</div> 10846<div class="paragraph"> 10847<p>Note the above grammar’s purpose is to aid discussion in this section; the 10848normative grammar is in “<a href="#shading-language-grammar">Shading Language 10849Grammar</a>”.</p> 10850</div> 10851<div class="paragraph"> 10852<p>If an <strong>if</strong>-expression evaluates to <strong>true</strong>, then the first <em>statement</em> is 10853executed. 10854If it evaluates to <strong>false</strong> and there is an <strong>else</strong> part then the second 10855<em>statement</em> is executed.</p> 10856</div> 10857<div class="paragraph"> 10858<p>Any expression whose type evaluates to a Boolean can be used as the 10859conditional expression <em>bool-expression</em>. 10860Vector types are not accepted as the expression to <strong>if</strong>.</p> 10861</div> 10862<div class="paragraph"> 10863<p>Conditionals can be nested.</p> 10864</div> 10865<div class="paragraph"> 10866<p>The type of <em>init-expression</em> in a <strong>switch</strong> statement must be a scalar 10867integer. 10868The type of <em>init-expression</em> must match the type of the <strong>case</strong> labels 10869within each <strong>switch</strong> statement. 10870Either signed integers or unsigned integers are allowed but there is no 10871implicit type conversion between the two. 10872If a <strong>case</strong> label has a <em>constant-expression</em> of equal value to 10873<em>init-expression</em>, execution will continue after that label. 10874Otherwise, if there is a <strong>default</strong> label, execution will continue after that 10875label. 10876Otherwise, execution skips the rest of the switch statement. 10877It is an error to have more than one <strong>default</strong> or a replicated 10878<em>constant-expression</em>. 10879A <strong>break</strong> statement not nested in a loop or other switch statement (either 10880not nested or nested only in <strong>if</strong> or <strong>if</strong>-<strong>else</strong> statements) will also skip 10881the rest of the switch statement. 10882Fall through labels are allowed, but it is an error to have no 10883statement between a label and the end of the switch statement. 10884No statements are allowed in a switch statement before the first <strong>case</strong> 10885statement.</p> 10886</div> 10887<div class="paragraph"> 10888<p>The <strong>case</strong> and <strong>default</strong> labels can only appear within a <strong>switch</strong> statement. 10889No <strong>case</strong> or <strong>default</strong> labels can be nested inside other statements or 10890compound statements within their corresponding <strong>switch</strong>.</p> 10891</div> 10892</div> 10893<div class="sect2"> 10894<h3 id="iteration">6.3. Iteration</h3> 10895<div class="paragraph"> 10896<p>For, while, and do loops are allowed as follows:</p> 10897</div> 10898<div class="listingblock"> 10899<div class="content"> 10900<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">for</span> (init-expression; condition-expression; loop-expression) 10901 sub-statement 10902<span class="keyword">while</span> (condition-expression) 10903 sub-statement 10904<span class="keyword">do</span> 10905 statement 10906<span class="keyword">while</span> (condition-expression)</code></pre> 10907</div> 10908</div> 10909<div class="paragraph"> 10910<p>See “<a href="#shading-language-grammar">Shading Language Grammar</a>” for the 10911definitive specification of loops.</p> 10912</div> 10913<div class="paragraph"> 10914<p>The <strong>for</strong> loop first evaluates the <em>init-expression</em>, then the 10915<em>condition-expression</em>. 10916If the <em>condition-expression</em> evaluates to <strong>true</strong>, then the body of the loop 10917is executed. 10918After the body is executed, a <strong>for</strong> loop will then evaluate the 10919<em>loop-expression</em>, and then loop back to evaluate the 10920<em>condition-expression</em>, repeating until the <em>condition-expression</em> evaluates 10921to <strong>false</strong>. 10922The loop is then exited, skipping its body and skipping its 10923<em>loop-expression</em>. 10924Variables modified by the <em>loop-expression</em> maintain their value after the 10925loop is exited, provided they are still in scope. 10926Variables declared in <em>init-expression</em> or <em>condition-expression</em> are only 10927in scope until the end of the sub-statement of the <strong>for</strong> loop.</p> 10928</div> 10929<div class="paragraph"> 10930<p>The <strong>while</strong> loop first evaluates the <em>condition-expression</em>. 10931If <strong>true</strong>, then the body is executed. 10932This is then repeated, until the <em>condition-expression</em> evaluates to 10933<strong>false</strong>, exiting the loop and skipping its body. 10934Variables declared in the <em>condition-expression</em> are only in scope until the 10935end of the sub-statement of the <strong>while</strong> loop.</p> 10936</div> 10937<div class="paragraph"> 10938<p>For both <strong>for</strong> and <strong>while</strong> loops, the sub-statement does not introduce a new 10939scope for variable names, so the following has a redeclaration error:</p> 10940</div> 10941<div class="listingblock"> 10942<div class="content"> 10943<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">for</span> (<span class="predefined-type">int</span> i = <span class="integer">0</span>; i < <span class="integer">10</span>; i++) + 10944{ 10945 <span class="predefined-type">int</span> i; <span class="comment">// redeclaration error +</span> 10946}</code></pre> 10947</div> 10948</div> 10949<div class="paragraph"> 10950<p>The <strong>do</strong>-<strong>while</strong> loop first executes the body, then executes the 10951<em>condition-expression</em>. 10952This is repeated until <em>condition-expression</em> evaluates to <strong>false</strong>, and then 10953the loop is exited.</p> 10954</div> 10955<div class="paragraph"> 10956<p>Expressions for <em>condition-expression</em> must evaluate to a Boolean.</p> 10957</div> 10958<div class="paragraph"> 10959<p>Both the <em>condition-expression</em> and the <em>init-expression</em> can declare and 10960initialize a variable, except in the <strong>do</strong>-<strong>while</strong> loop, which cannot declare 10961a variable in its <em>condition-expression</em>. 10962The variable’s scope lasts only until the end of the sub-statement that 10963forms the body of the loop.</p> 10964</div> 10965<div class="paragraph"> 10966<p>Loops can be nested.</p> 10967</div> 10968<div class="paragraph"> 10969<p>Non-terminating loops are allowed. 10970The consequences of very long or non-terminating loops are platform 10971dependent.</p> 10972</div> 10973</div> 10974<div class="sect2"> 10975<h3 id="jumps">6.4. Jumps</h3> 10976<div class="paragraph"> 10977<p>These are the jumps:</p> 10978</div> 10979<div class="openblock bnf"> 10980<div class="content"> 10981<div class="dlist"> 10982<dl> 10983<dt class="hdlist1"><em>jump_statement</em> : </dt> 10984<dd> 10985<p><strong>continue</strong> <strong>;</strong><br> 10986<strong>break</strong> <strong>;</strong><br> 10987<strong>return</strong> <strong>;</strong><br> 10988<strong>return</strong> <em>expression</em> <strong>;</strong><br> 10989<strong>discard</strong> <strong>;</strong> // in the fragment shader language only</p> 10990</dd> 10991</dl> 10992</div> 10993</div> 10994</div> 10995<div class="paragraph"> 10996<p>There is no “goto” or other non-structured flow of control.</p> 10997</div> 10998<div class="paragraph"> 10999<p>The <strong>continue</strong> jump is used only in loops. 11000It skips the remainder of the body of the inner-most loop of which it is 11001inside. 11002For <strong>while</strong> and <strong>do</strong>-<strong>while</strong> loops, this jump is to the next evaluation of 11003the loop <em>condition-expression</em> from which the loop continues as previously 11004defined. 11005For <strong>for</strong> loops, the jump is to the <em>loop-expression</em>, followed by the 11006<em>condition-expression</em>.</p> 11007</div> 11008<div class="paragraph"> 11009<p>The <strong>break</strong> jump can also be used only in loops and <strong>switch</strong> statements. 11010It is simply an immediate exit of the inner-most loop or <strong>switch</strong> statements 11011containing the <strong>break</strong>. 11012No further execution of <em>condition-expression</em>, <em>loop-expression</em>, or 11013<em>switch-statement</em> is done.</p> 11014</div> 11015<div class="paragraph"> 11016<p>The <strong>discard</strong> keyword is only allowed within fragment shaders. 11017It can be used within a fragment shader to abandon the operation on the 11018current fragment. 11019This keyword causes the fragment to be discarded and no updates to any 11020buffers will occur. 11021Any prior writes to other buffers such as shader storage buffers are 11022unaffected. 11023Control flow exits the shader, and subsequent implicit or explicit 11024derivatives are undefined when this control flow is non-uniform (meaning 11025different fragments within the primitive take different control paths). 11026It would typically be used within a conditional statement, for example:</p> 11027</div> 11028<div class="listingblock"> 11029<div class="content"> 11030<pre class="CodeRay highlight"><code data-lang="c++"><span class="keyword">if</span> (intensity < <span class="float">0</span><span class="float">.0</span>) 11031 discard;</code></pre> 11032</div> 11033</div> 11034<div class="paragraph"> 11035<p>A fragment shader may test a fragment’s alpha value and discard the fragment 11036based on that test. 11037However, it should be noted that coverage testing occurs after the fragment 11038shader runs, and the coverage test can change the alpha value.</p> 11039</div> 11040<div class="paragraph"> 11041<p>The <strong>return</strong> jump causes immediate exit of the current function. 11042If it has <em>expression</em> then that is the return value for the function.</p> 11043</div> 11044<div class="paragraph"> 11045<p>The function <em>main</em> can use <strong>return</strong>. 11046This simply causes <em>main</em> to exit in the same way as when the end of the 11047function had been reached. 11048It does not imply a use of <strong>discard</strong> in a fragment shader. 11049Using <strong>return</strong> in <em>main</em> before defining outputs will have the same behavior 11050as reaching the end of <em>main</em> before defining outputs.</p> 11051</div> 11052</div> 11053</div> 11054</div> 11055<div class="sect1"> 11056<h2 id="built-in-variables">7. Built-In Variables</h2> 11057<div class="sectionbody"> 11058<div class="sect2"> 11059<h3 id="built-in-language-variables">7.1. Built-In Language Variables</h3> 11060<div class="paragraph"> 11061<p>Some operations occur outside shader functionality and need to provide 11062values to or receive values from shader executables. 11063Shaders communicate with fixed-function pipeline stages, and 11064optionally with other shader executables, through the use of built-in input 11065and output variables.</p> 11066</div> 11067<div class="sect3"> 11068<h4 id="vertex-shader-special-variables">7.1.1. Vertex Shader Special Variables</h4> 11069<div class="paragraph"> 11070<p>The built-in vertex shader variables are intrinsically declared as follows:</p> 11071</div> 11072<div class="listingblock"> 11073<div class="content"> 11074<pre class="CodeRay highlight"><code data-lang="c++">in highp <span class="predefined-type">int</span> gl_VertexID; <span class="comment">// only present when not targeting Vulkan</span> 11075in highp <span class="predefined-type">int</span> gl_InstanceID; <span class="comment">// only present when not targeting Vulkan</span> 11076in highp <span class="predefined-type">int</span> gl_VertexIndex; <span class="comment">// only present when targeting Vulkan</span> 11077in highp <span class="predefined-type">int</span> gl_InstanceIndex; <span class="comment">// only present when targeting Vulkan</span> 11078 11079out gl_PerVertex { 11080 out highp vec4 gl_Position; 11081 out highp <span class="predefined-type">float</span> gl_PointSize; 11082};</code></pre> 11083</div> 11084</div> 11085<div class="paragraph"> 11086<p>The variable <em>gl_Position</em> is intended for writing the homogeneous vertex 11087position. 11088It can be written at any time during shader execution. 11089This value will be used by primitive assembly, clipping, culling, and other 11090fixed functionality operations, if present, that operate on primitives after 11091vertex processing has occurred. 11092Its value is undefined after the vertex processing stage if the vertex 11093shader executable does not write <em>gl_Position</em>.</p> 11094</div> 11095<div class="paragraph"> 11096<p>The variable <em>gl_PointSize</em> is intended for a shader to write the size of 11097the point to be rasterized. 11098It is measured in pixels. 11099If <em>gl_PointSize</em> is not written to, its value is undefined in subsequent 11100pipe stages.</p> 11101</div> 11102<div class="paragraph"> 11103<p>The variable <em>gl_VertexID</em> is a vertex shader input variable that holds an 11104integer index for the vertex, as defined under “Shader Inputs” in section 1110511.1.3.9 “Shader Inputs” of the <a href="#references">OpenGL ES Specification</a>. 11106It is only present when not targeting Vulkan. 11107Even when present, the value of <em>gl_VertexID</em> is not always defined.</p> 11108</div> 11109<div class="paragraph"> 11110<p>The variable <em>gl_InstanceID</em> is a vertex shader input variable that holds 11111the instance number of the current primitive in an instanced draw call (see 11112“Shader Inputs” in section 11.1.3.9 “Shader Inputs” of the 11113<a href="#references">OpenGL ES Specification</a>). 11114It is only present when not targeting Vulkan. 11115If the current primitive does not come from an instanced draw call, the 11116value of <em>gl_InstanceID</em> is zero.</p> 11117</div> 11118<div class="paragraph"> 11119<p>The variable <em>gl_VertexIndex</em> is a vertex language input variable that 11120holds an integer index for the vertex, relative to a base. 11121It is only present when targeting Vulkan. 11122Even when present, the value of <em>gl_VertexIndex</em> is not always defined.</p> 11123</div> 11124<div class="paragraph"> 11125<p>The variable <em>gl_InstanceIndex</em> is a vertex language input variable that 11126holds the instance number of the current primitive in an instanced draw 11127call, relative to a base. 11128It is only present when targeting Vulkan. 11129If the current primitive does not come from an instanced draw call, 11130the value of gl_InstanceIndex is zero.</p> 11131</div> 11132</div> 11133<div class="sect3"> 11134<h4 id="tessellation-control-shader-special-variables">7.1.2. Tessellation Control Shader Special Variables</h4> 11135<div class="paragraph"> 11136<p>In the tessellation control shader, built-in variables are intrinsically 11137declared as:</p> 11138</div> 11139<div class="listingblock"> 11140<div class="content"> 11141<pre class="CodeRay highlight"><code data-lang="c++">in gl_PerVertex { 11142 highp vec4 gl_Position; 11143} gl_in[gl_MaxPatchVertices]; 11144 11145in highp <span class="predefined-type">int</span> gl_PatchVerticesIn; 11146in highp <span class="predefined-type">int</span> gl_PrimitiveID; 11147in highp <span class="predefined-type">int</span> gl_InvocationID; 11148 11149out gl_PerVertex { 11150 highp vec4 gl_Position; 11151} gl_out[]; 11152 11153patch out highp <span class="predefined-type">float</span> gl_TessLevelOuter[<span class="integer">4</span>]; 11154patch out highp <span class="predefined-type">float</span> gl_TessLevelInner[<span class="integer">2</span>]; 11155patch out highp vec4 gl_BoundingBox[<span class="integer">2</span>];</code></pre> 11156</div> 11157</div> 11158<div class="sect4"> 11159<h5 id="tessellation-control-input-variables">Tessellation Control Input Variables</h5> 11160<div class="paragraph"> 11161<p><em>gl_Position</em> contains the output written in the previous shader stage to 11162<em>gl_Position</em>.</p> 11163</div> 11164<div class="paragraph"> 11165<p><em>gl_PatchVerticesIn</em> contains the number of vertices in the input patch 11166being processed by the shader. 11167A single shader can read patches of differing sizes, so the value of 11168<em>gl_PatchVerticesIn</em> may differ between patches.</p> 11169</div> 11170<div class="paragraph"> 11171<p><em>gl_PrimitiveID</em> contains the number of primitives processed by the shader 11172since the current set of rendering primitives was started.</p> 11173</div> 11174<div class="paragraph"> 11175<p><em>gl_InvocationID</em> contains the number of the output patch vertex assigned to 11176the tessellation control shader invocation. 11177It is assigned integer values in the range [0, N-1], where N is the number 11178of output patch vertices per primitive.</p> 11179</div> 11180</div> 11181<div class="sect4"> 11182<h5 id="tessellation-control-output-variables">Tessellation Control Output Variables</h5> 11183<div class="paragraph"> 11184<p><em>gl_Position</em> is used in the same fashion as the corresponding output 11185variable in the vertex shader.</p> 11186</div> 11187<div class="paragraph"> 11188<p>The values written to <em>gl_TessLevelOuter</em> and <em>gl_TessLevelInner</em> are 11189assigned to the corresponding outer and inner tessellation levels of the 11190output patch. 11191They are used by the tessellation primitive generator to control primitive 11192tessellation and may be read by tessellation evaluation shaders.</p> 11193</div> 11194<div class="paragraph"> 11195<p>The values written to <em>gl_BoundingBox</em> specify the minimum and maximum 11196clip-space extents of a bounding box containing all primitives generated 11197from the patch by the primitive generator, geometry shader, and clipping. 11198Fragments may or may not be generated for portions of these primitives 11199that extend outside the window-coordinate projection of this bounding 11200box.</p> 11201</div> 11202</div> 11203</div> 11204<div class="sect3"> 11205<h4 id="tessellation-evaluation-shader-special-variables">7.1.3. Tessellation Evaluation Shader Special Variables</h4> 11206<div class="paragraph"> 11207<p>In the tessellation evaluation shader, built-in variables are intrinsically 11208declared as:</p> 11209</div> 11210<div class="listingblock"> 11211<div class="content"> 11212<pre class="CodeRay highlight"><code data-lang="c++">in gl_PerVertex { 11213 highp vec4 gl_Position; 11214} gl_in[gl_MaxPatchVertices]; 11215 11216in highp <span class="predefined-type">int</span> gl_PatchVerticesIn; 11217in highp <span class="predefined-type">int</span> gl_PrimitiveID; 11218in highp vec3 gl_TessCoord; 11219patch in highp <span class="predefined-type">float</span> gl_TessLevelOuter[<span class="integer">4</span>]; 11220patch in highp <span class="predefined-type">float</span> gl_TessLevelInner[<span class="integer">2</span>]; 11221 11222out gl_PerVertex { 11223 highp vec4 gl_Position; 11224};</code></pre> 11225</div> 11226</div> 11227<div class="sect4"> 11228<h5 id="tessellation-evaluation-input-variables">Tessellation Evaluation Input Variables</h5> 11229<div class="paragraph"> 11230<p><em>gl_Position</em> contains the output written in the previous shader stage to 11231<em>gl_Position</em>.</p> 11232</div> 11233<div class="paragraph"> 11234<p><em>gl_PatchVerticesIn</em> and <em>gl_PrimitiveID</em> are defined in the same fashion as 11235the corresponding input variables in the tessellation control shader.</p> 11236</div> 11237<div class="paragraph"> 11238<p><em>gl_TessCoord</em> specifies a three-component <em>(u,v,w)</em> vector identifying the 11239position of the vertex being processed by the shader relative to the 11240primitive being tessellated. 11241Its values will obey the properties</p> 11242</div> 11243<div class="listingblock"> 11244<div class="content"> 11245<pre class="CodeRay highlight"><code data-lang="c++">gl_TessCoord.x == <span class="float">1</span><span class="float">.0</span> - (<span class="float">1</span><span class="float">.0</span> - gl_TessCoord.x) <span class="comment">// two operations performed</span> 11246gl_TessCoord.y == <span class="float">1</span><span class="float">.0</span> - (<span class="float">1</span><span class="float">.0</span> - gl_TessCoord.y) <span class="comment">// two operations performed</span> 11247gl_TessCoord.z == <span class="float">1</span><span class="float">.0</span> - (<span class="float">1</span><span class="float">.0</span> - gl_TessCoord.z) <span class="comment">// two operations performed</span></code></pre> 11248</div> 11249</div> 11250<div class="paragraph"> 11251<p>to aid in replicating subdivision computations.</p> 11252</div> 11253<div class="paragraph"> 11254<p><em>gl_TessLevelOuter</em> and <em>gl_TessLevelInner</em> are filled with the 11255corresponding outputs written by the active tessellation control shader.</p> 11256</div> 11257</div> 11258<div class="sect4"> 11259<h5 id="tessellation-evaluation-output-variables">Tessellation Evaluation Output Variables</h5> 11260<div class="paragraph"> 11261<p><em>gl_Position</em> is used in the same fashion as the corresponding output 11262variable in the vertex shader.</p> 11263</div> 11264</div> 11265</div> 11266<div class="sect3"> 11267<h4 id="geometry-shader-special-variables">7.1.4. Geometry Shader Special Variables</h4> 11268<div class="paragraph"> 11269<p>In the geometry shader, built-in variables are intrinsically declared as:</p> 11270</div> 11271<div class="listingblock"> 11272<div class="content"> 11273<pre class="CodeRay highlight"><code data-lang="c++">in gl_PerVertex { 11274 highp vec4 gl_Position; 11275} gl_in[]; 11276 11277in highp <span class="predefined-type">int</span> gl_PrimitiveIDIn; 11278in highp <span class="predefined-type">int</span> gl_InvocationID; 11279 11280out gl_PerVertex { 11281 highp vec4 gl_Position; 11282}; 11283 11284out highp <span class="predefined-type">int</span> gl_PrimitiveID; 11285out highp <span class="predefined-type">int</span> gl_Layer;</code></pre> 11286</div> 11287</div> 11288<div class="sect4"> 11289<h5 id="geometry-shader-input-variables">Geometry Shader Input Variables</h5> 11290<div class="paragraph"> 11291<p><em>gl_Position</em> contains the output written in the previous shader stage to 11292<em>gl_Position</em>.</p> 11293</div> 11294<div class="paragraph"> 11295<p><em>gl_PrimitiveIDIn</em> contains the number of primitives processed by the shader 11296since the current set of rendering primitives was started.</p> 11297</div> 11298<div class="paragraph"> 11299<p><em>gl_InvocationID</em> contains the invocation number assigned to the geometry 11300shader invocation. 11301It is assigned integer values in the range [0, N-1], where N is the number 11302of geometry shader invocations per primitive.</p> 11303</div> 11304</div> 11305<div class="sect4"> 11306<h5 id="geometry-shader-output-variables">Geometry Shader Output Variables</h5> 11307<div class="paragraph"> 11308<p><em>gl_Position</em> is used in the same fashion as the corresponding output 11309variable in the vertex shader.</p> 11310</div> 11311<div class="paragraph"> 11312<p><em>gl_PrimitiveID</em> is filled with a single integer that serves as a primitive 11313identifier to the fragment shader. 11314This is then available to fragment shaders, which will select the written 11315primitive ID from the provoking vertex of the primitive being shaded. 11316If a fragment shader using <em>gl_PrimitiveID</em> is active and a geometry shader 11317is also active, the geometry shader must write to <em>gl_PrimitiveID</em> or the 11318fragment shader input <em>gl_PrimitiveID</em> is undefined. 11319See section 11.3.4.4 “Geometry Shader Outputs” of the 11320<a href="#references">OpenGL ES Specification</a> for more information.</p> 11321</div> 11322<div class="paragraph"> 11323<p><em>gl_Layer</em> is used to select a specific layer (or face and layer of a cube 11324map) of a multi-layer framebuffer attachment. 11325The actual layer used will come from one of the vertices in the primitive 11326being shaded. 11327Which vertex the layer comes from is determined as discussed in section 1132811.3.4.4 of the <a href="#references">OpenGL ES Specification</a> 11329but may be undefined, so it is best to write the same layer value for all 11330vertices of a primitive. 11331If a shader statically assigns a value to <em>gl_Layer</em>, layered rendering mode 11332is enabled. 11333See section 11.3.4.4 “Geometry Shader Outputs” and section 9.8 “Layered 11334Framebuffers” of the <a href="#references">OpenGL ES Specification</a> for more information. 11335If a shader statically assigns a value to <em>gl_Layer</em>, and there is an 11336execution path through the shader that does not set <em>gl_Layer</em>, then the 11337value of <em>gl_Layer</em> is undefined for executions of the shader that take that 11338path.</p> 11339</div> 11340<div class="paragraph"> 11341<p>The output variable <em>gl_Layer</em> takes on a special value when used with an 11342array of cube map textures. 11343Instead of only referring to the layer, it is used to select a cube map face 11344and a layer. 11345Setting <em>gl_Layer</em> to the value <em>layer*6+face</em> will render to face <em>face</em> of 11346the cube defined in layer <em>layer</em>. 11347The face values are defined in table 8.25 of the <a href="#references">OpenGL ES Specification</a>, 11348but repeated below for clarity.</p> 11349</div> 11350<table class="tableblock frame-all grid-all stretch"> 11351<colgroup> 11352<col style="width: 50%;"> 11353<col style="width: 50%;"> 11354</colgroup> 11355<thead> 11356<tr> 11357<th class="tableblock halign-left valign-top">Face Value</th> 11358<th class="tableblock halign-left valign-top">Resulting Target</th> 11359</tr> 11360</thead> 11361<tbody> 11362<tr> 11363<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> 11364<td class="tableblock halign-left valign-top"><p class="tableblock">TEXTURE_CUBE_MAP_POSITIVE_X</p></td> 11365</tr> 11366<tr> 11367<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> 11368<td class="tableblock halign-left valign-top"><p class="tableblock">TEXTURE_CUBE_MAP_NEGATIVE_X</p></td> 11369</tr> 11370<tr> 11371<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> 11372<td class="tableblock halign-left valign-top"><p class="tableblock">TEXTURE_CUBE_MAP_POSITIVE_Y</p></td> 11373</tr> 11374<tr> 11375<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> 11376<td class="tableblock halign-left valign-top"><p class="tableblock">TEXTURE_CUBE_MAP_NEGATIVE_Y</p></td> 11377</tr> 11378<tr> 11379<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> 11380<td class="tableblock halign-left valign-top"><p class="tableblock">TEXTURE_CUBE_MAP_POSITIVE_Z</p></td> 11381</tr> 11382<tr> 11383<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> 11384<td class="tableblock halign-left valign-top"><p class="tableblock">TEXTURE_CUBE_MAP_NEGATIVE_Z</p></td> 11385</tr> 11386</tbody> 11387</table> 11388<div class="paragraph"> 11389<p>For example, to render to the positive <em>y</em> cube map face located in the 5th 11390layer of the cube map array, <em>gl_Layer</em> should be set to <em>5 * 6 + 2</em>.</p> 11391</div> 11392</div> 11393</div> 11394<div class="sect3"> 11395<h4 id="fragment-shader-special-variables">7.1.5. Fragment Shader Special Variables</h4> 11396<div class="paragraph"> 11397<p>The built-in special variables that are accessible from a fragment shader 11398are intrinsically declared as follows:</p> 11399</div> 11400<div class="listingblock"> 11401<div class="content"> 11402<pre class="CodeRay highlight"><code data-lang="c++">in highp vec4 gl_FragCoord; 11403in <span class="predefined-type">bool</span> gl_FrontFacing; 11404out highp <span class="predefined-type">float</span> gl_FragDepth; 11405in mediump vec2 gl_PointCoord; 11406in <span class="predefined-type">bool</span> gl_HelperInvocation; 11407in highp <span class="predefined-type">int</span> gl_PrimitiveID; 11408in highp <span class="predefined-type">int</span> gl_Layer; 11409in lowp <span class="predefined-type">int</span> gl_SampleID; 11410in mediump vec2 gl_SamplePosition; 11411in highp <span class="predefined-type">int</span> gl_SampleMaskIn[(gl_MaxSamples+<span class="integer">31</span>)/<span class="integer">32</span>]; 11412out highp <span class="predefined-type">int</span> gl_SampleMask[(gl_MaxSamples+<span class="integer">31</span>)/<span class="integer">32</span>];</code></pre> 11413</div> 11414</div> 11415<div class="paragraph"> 11416<p>The output of the fragment shader executable is processed by the fixed 11417function operations at the back end of the API pipeline.</p> 11418</div> 11419<div class="paragraph"> 11420<p>The fixed functionality computed depth for a fragment may be obtained by 11421reading <em>gl_FragCoord.z</em>, described below.</p> 11422</div> 11423<div class="paragraph"> 11424<p>Writing to <em>gl_FragDepth</em> will establish the depth value for the fragment 11425being processed. 11426If depth buffering is enabled, and no shader writes <em>gl_FragDepth</em>, then the 11427fixed function value for depth will be used as the fragment’s depth value. 11428If a shader statically assigns a value to <em>gl_FragDepth</em>, and there is an 11429execution path through the shader that does not set <em>gl_FragDepth</em>, then the 11430value of the fragment’s depth may be undefined for executions of the shader 11431that take that path. 11432That is, if the set of linked fragment shaders statically contain a write to 11433<em>gl_FragDepth</em>, then it is responsible for always writing it.</p> 11434</div> 11435<div class="paragraph"> 11436<p>If a shader executes the <strong>discard</strong> keyword, the fragment is discarded, and 11437the values of any user-defined fragment outputs, <em>gl_FragDepth</em>, and 11438<em>gl_SampleMask</em> become irrelevant.</p> 11439</div> 11440<div class="paragraph"> 11441<p>The variable <em>gl_FragCoord</em> is available as an input variable from within 11442fragment shaders and it holds the window relative coordinates (<em>x</em>, <em>y</em>, 11443<em>z</em>, <em>1/w</em>) values for the fragment. 11444If multi-sampling, this value can be for any location within the pixel, or 11445one of the fragment samples. 11446The use of <strong>centroid</strong> does not further restrict this value to be inside the 11447current primitive. 11448This value is the result of the fixed functionality that interpolates 11449primitives after vertex processing to generate fragments. 11450The <em>z</em> component is the depth value that would be used for the fragment’s 11451depth if no shader contained any writes to <em>gl_FragDepth</em>. 11452This is useful for invariance if a shader conditionally computes 11453<em>gl_FragDepth</em> but otherwise wants the fixed functionality fragment depth.</p> 11454</div> 11455<div class="paragraph"> 11456<p>Fragment shaders have access to the input built-in variable 11457<em>gl_FrontFacing</em>, whose value is <strong>true</strong> if the fragment belongs to a 11458front-facing primitive. 11459One use of this is to emulate two-sided lighting by selecting one of two 11460colors calculated by a vertex or geometry shader.</p> 11461</div> 11462<div class="paragraph"> 11463<p>The values in <em>gl_PointCoord</em> are two-dimensional coordinates indicating 11464where within a point primitive the current fragment is located, when point 11465sprites are enabled. 11466They range from 0.0 to 1.0 across the point. 11467If the current primitive is not a point, or if point sprites are not 11468enabled, then the values read from <em>gl_PointCoord</em> are undefined.</p> 11469</div> 11470<div class="paragraph"> 11471<p>For both the input array <em>gl_SampleMaskIn[]</em> and the output array 11472<em>gl_SampleMask[]</em>, bit <em>B</em> of mask <em>M</em> (<em>gl_SampleMaskIn[M]</em> or 11473<em>gl_SampleMask[M]</em>) corresponds to sample <em>32*M+B</em>. 11474These arrays have <strong>ceil</strong>(<em>s</em>/32) elements, where <em>s</em> is the maximum number 11475of color samples supported by the implementation.</p> 11476</div> 11477<div class="paragraph"> 11478<p>The input variable <em>gl_SampleMaskIn</em> indicates the set of samples covered by 11479the primitive generating the fragment during multisample rasterization. 11480It has a sample bit set if and only if the sample is considered covered for 11481this fragment shader invocation.</p> 11482</div> 11483<div class="paragraph"> 11484<p>The output array <em>gl_SampleMask[]</em> sets the sample mask for the fragment 11485being processed. 11486Coverage for the current fragment will become the logical AND of the 11487coverage mask and the output <em>gl_SampleMask</em>. 11488This array must be sized in the fragment shader either implicitly or 11489explicitly, to be no larger than the implementation-dependent maximum 11490sample-mask (as an array of 32bit elements), determined by the maximum 11491number of samples.. 11492If the fragment shader statically assigns a value to <em>gl_SampleMask</em>, the 11493sample mask will be undefined for any array elements of any fragment shader 11494invocations that fail to assign a value. 11495If a shader does not statically assign a value to <em>gl_SampleMask</em>, the 11496sample mask has no effect on the processing of a fragment.</p> 11497</div> 11498<div class="paragraph"> 11499<p>The input variable <em>gl_SampleID</em> is filled with the sample number of the 11500sample currently being processed. 11501This variable is in the range <em>0</em> to <em>gl_NumSamples-1</em>, where 11502<em>gl_NumSamples</em> is the total number of samples in the framebuffer, or 1 if 11503rendering to a non-multisample framebuffer. 11504Any static use of this variable in a fragment shader causes the entire 11505shader to be evaluated per-sample.</p> 11506</div> 11507<div class="paragraph"> 11508<p>The input variable <em>gl_SamplePosition</em> contains the position of the current 11509sample within the multisample draw buffer. 11510The <em>x</em> and <em>y</em> components of <em>gl_SamplePosition</em> contain the sub-pixel 11511coordinate of the current sample and will have values in the range 0.0 to 115121.0. 11513Any static use of this variable in a fragment shader causes the entire 11514shader to be evaluated per sample.</p> 11515</div> 11516<div class="paragraph"> 11517<p>The value <em>gl_HelperInvocation</em> is <strong>true</strong> if the fragment shader invocation 11518is considered a <em>helper invocation</em> and is <strong>false</strong> otherwise. 11519A helper invocation is a fragment shader invocation that is created solely 11520for the purposes of evaluating derivatives for use in non-helper fragment 11521shader invocations. 11522Such derivatives are computed implicitly in the built-in function 11523<strong>texture</strong>() (see “<a href="#texture-functions">Texture Functions</a>”), and 11524explicitly in the derivative functions in 11525“<a href="#derivative-functions">Derivative Functions</a>”, for example <strong>dFdx</strong>() and 11526<strong>dFdy</strong>().</p> 11527</div> 11528<div class="paragraph"> 11529<p>Fragment shader helper invocations execute the same shader code as 11530non-helper invocations, but will not have side effects that modify the 11531framebuffer or other shader-accessible memory. 11532In particular:</p> 11533</div> 11534<div class="ulist"> 11535<ul> 11536<li> 11537<p>Fragments corresponding to helper invocations are discarded when shader 11538execution is complete, without updating the framebuffer.</p> 11539</li> 11540<li> 11541<p>Stores to image and buffer variables performed by helper invocations 11542have no effect on the underlying image or buffer memory.</p> 11543</li> 11544<li> 11545<p>Atomic operations to image, buffer, or atomic counter variables 11546performed by helper invocations have no effect on the underlying image 11547or buffer memory. 11548The values returned by such atomic operations are undefined.</p> 11549</li> 11550</ul> 11551</div> 11552<div class="paragraph"> 11553<p>Helper invocations may be generated for pixels not covered by a primitive 11554being rendered. 11555While fragment shader inputs qualified with <strong>centroid</strong> are normally required 11556to be sampled in the intersection of the pixel and the primitive, the 11557requirement is ignored for such pixels since there is no intersection 11558between the pixel and primitive.</p> 11559</div> 11560<div class="paragraph"> 11561<p>Helper invocations may also be generated for fragments that are covered by a 11562primitive being rendered when the fragment is killed by early fragment tests 11563(using the <strong>early_fragment_tests</strong> qualifier) or where the implementation is 11564able to determine that executing the fragment shader would have no effect 11565other than assisting in computing derivatives for other fragment shader 11566invocations.</p> 11567</div> 11568<div class="paragraph"> 11569<p>The set of helper invocations generated when processing any set of 11570primitives is implementation-dependent.</p> 11571</div> 11572<div class="paragraph"> 11573<p>The input variable <em>gl_PrimitiveID</em> is filled with the value written to the 11574<em>gl_PrimitiveID</em> geometry shader output, if a geometry shader is present. 11575Otherwise, it is filled with the number of primitives processed by the 11576shader since the current set of rendering primitives was started.</p> 11577</div> 11578<div class="paragraph"> 11579<p>The input variable <em>gl_Layer</em> is filled with the value written to the 11580<em>gl_Layer</em> geometry shader output, if a geometry shader is present. 11581If the geometry stage does not dynamically assign a value to <em>gl_Layer</em>, the 11582value of <em>gl_Layer</em> in the fragment stage will be undefined. 11583If the geometry stage makes no static assignment to <em>gl_Layer</em>, the input 11584value in the fragment stage will be zero. 11585Otherwise, the fragment stage will read the same value written by the 11586geometry stage, even if that value is out of range. 11587If a fragment shader contains a static access to <em>gl_Layer</em>, it will count 11588against the implementation defined limit for the maximum number of inputs to 11589the fragment stage.</p> 11590</div> 11591</div> 11592<div class="sect3"> 11593<h4 id="compute-shader-special-variables">7.1.6. Compute Shader Special Variables</h4> 11594<div class="paragraph"> 11595<p>In the compute shader, built-in variables are declared as follows:</p> 11596</div> 11597<div class="listingblock"> 11598<div class="content"> 11599<pre class="CodeRay highlight"><code data-lang="c++"><span class="comment">// workgroup dimensions</span> 11600in uvec3 gl_NumWorkGroups; 11601<span class="directive">const</span> uvec3 gl_WorkGroupSize; 11602 11603<span class="comment">// workgroup and invocation IDs</span> 11604in uvec3 gl_WorkGroupID; 11605in uvec3 gl_LocalInvocationID; 11606 11607<span class="comment">// derived variables</span> 11608in uvec3 gl_GlobalInvocationID; 11609in uint gl_LocalInvocationIndex;</code></pre> 11610</div> 11611</div> 11612<div class="paragraph"> 11613<p>The built-in variable <em>gl_NumWorkGroups</em> is a compute-shader input variable 11614containing the number of workgroups in each dimension of the dispatch that 11615will execute the compute shader. 11616Its content is equal to the values specified in the <em>num_groups_x</em>, 11617<em>num_groups_y</em>, and <em>num_groups_z</em> parameters passed to the 11618<em>DispatchCompute</em> API entry point.</p> 11619</div> 11620<div class="paragraph"> 11621<p>The built-in constant <em>gl_WorkGroupSize</em> is a compute-shader constant 11622containing the workgroup size of the shader. 11623The size of the workgroup in the <em>X</em>, <em>Y</em>, and <em>Z</em> dimensions is stored in 11624the <em>x</em>, <em>y</em>, and <em>z</em> components. 11625The constants values in <em>gl_WorkGroupSize</em> will match those specified in the 11626required <strong>local_size_x</strong>, <strong>local_size_y</strong>, and <strong>local_size_z</strong> layout 11627qualifiers for the current shader. 11628This is a constant so that it can be used to size arrays of memory that can 11629be shared within the workgroup. 11630It is a compile-time error to use <em>gl_WorkGroupSize</em> in a shader that does 11631not declare a fixed workgroup size, or before that shader has declared a 11632fixed workgroup size, using <strong>local_size_x</strong>, <strong>local_size_y</strong>, and 11633<strong>local_size_z</strong>.</p> 11634</div> 11635<div class="paragraph"> 11636<p>The built-in variable <em>gl_WorkGroupID</em> is a compute-shader input variable 11637containing the three-dimensional index of the workgroup that the 11638current invocation is executing in. 11639The possible values range across the parameters passed into 11640<em>DispatchCompute</em>, i.e., from (0, 0, 0) to (<em>gl_NumWorkGroups.x</em> - 1, 11641<em>gl_NumWorkGroups.y</em> - 1, <em>gl_NumWorkGroups.z</em> -1).</p> 11642</div> 11643<div class="paragraph"> 11644<p>The built-in variable <em>gl_LocalInvocationID</em> is a compute-shader input 11645variable containing the three-dimensional index of the current work item 11646within the workgroup. 11647The possible values for this variable range across the workgroup 11648size, i.e., (0,0,0) to (<em>gl_WorkGroupSize.x</em> - 1, <em>gl_WorkGroupSize.y</em> - 1, 11649<em>gl_WorkGroupSize.z</em> - 1). Use of <em>gl_LocalInvocationID</em> is allowed 11650before declarations of <strong>local_size_x</strong>, <strong>local_size_y</strong>, and <strong>local_size_z</strong>.</p> 11651</div> 11652<div class="paragraph"> 11653<p>The built-in variable <em>gl_GlobalInvocationID</em> is a compute shader input 11654variable containing the global index of the current work item. 11655This value uniquely identifies this invocation from all other invocations 11656across all workgroups initiated by the current <em>DispatchCompute</em> call. 11657This is computed as:</p> 11658</div> 11659<div class="listingblock"> 11660<div class="content"> 11661<pre class="CodeRay highlight"><code data-lang="c++">gl_GlobalInvocationID = 11662 gl_WorkGroupID * gl_WorkGroupSize + gl_LocalInvocationID;</code></pre> 11663</div> 11664</div> 11665<div class="paragraph"> 11666<p>The built-in variable <em>gl_LocalInvocationIndex</em> is a compute shader input 11667variable that contains the one-dimensional representation of the 11668<em>gl_LocalInvocationID</em>. 11669This is computed as:</p> 11670</div> 11671<div class="listingblock"> 11672<div class="content"> 11673<pre class="CodeRay highlight"><code data-lang="c++">gl_LocalInvocationIndex = 11674 gl_LocalInvocationID.z * gl_WorkGroupSize.x * gl_WorkGroupSize.y + 11675 gl_LocalInvocationID.y * gl_WorkGroupSize.x + 11676 gl_LocalInvocationID.x;</code></pre> 11677</div> 11678</div> 11679<div class="paragraph"> 11680<p>Use of <em>gl_LocalInvocationIndex</em> is allowed before declarations of 11681<strong>local_size_x</strong>, <strong>local_size_y</strong>, and <strong>local_size_z</strong>.</p> 11682</div> 11683</div> 11684</div> 11685<div class="sect2"> 11686<h3 id="built-in-constants">7.2. Built-In Constants</h3> 11687<div class="paragraph"> 11688<p>The following built-in constants are declared in all shaders. 11689The actual values used are implementation-dependent, but must be at least 11690the value shown.</p> 11691</div> 11692<div class="listingblock"> 11693<div class="content"> 11694<pre class="CodeRay highlight"><code data-lang="c++"><span class="comment">//</span> 11695<span class="comment">// Implementation-dependent constants. The example values below</span> 11696<span class="comment">// are the minimum values allowed for these maximums.</span> 11697<span class="comment">//</span></code></pre> 11698</div> 11699</div> 11700<div class="listingblock"> 11701<div class="content"> 11702<pre class="CodeRay highlight"><code data-lang="c++"><span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxVertexAttribs = <span class="integer">16</span>; 11703<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxVertexUniformVectors = <span class="integer">256</span>; 11704<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxVertexOutputVectors = <span class="integer">16</span>; 11705<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxVertexTextureImageUnits = <span class="integer">16</span>; 11706<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxVertexImageUniforms = <span class="integer">0</span>; 11707<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxVertexAtomicCounters = <span class="integer">0</span>; 11708<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxVertexAtomicCounterBuffers = <span class="integer">0</span>; 11709 11710<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessControlInputComponents = <span class="integer">64</span>; 11711<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessControlOutputComponents = <span class="integer">64</span>; 11712<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessControlTextureImageUnits = <span class="integer">16</span>; 11713<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessControlUniformComponents = <span class="integer">1024</span>; 11714<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessControlTotalOutputComponents = <span class="integer">2048</span>; 11715<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessControlImageUniforms = <span class="integer">0</span>; 11716<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessControlAtomicCounters = <span class="integer">0</span>; 11717<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessControlAtomicCounterBuffers = <span class="integer">0</span>; 11718 11719<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessPatchComponents = <span class="integer">120</span>; 11720<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxPatchVertices = <span class="integer">32</span>; 11721<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessGenLevel = <span class="integer">64</span>; 11722 11723<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessEvaluationInputComponents = <span class="integer">64</span>; 11724<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessEvaluationOutputComponents = <span class="integer">64</span>; 11725<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessEvaluationTextureImageUnits = <span class="integer">16</span>; 11726<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessEvaluationUniformComponents = <span class="integer">1024</span>; 11727<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessEvaluationImageUniforms = <span class="integer">0</span>; 11728<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessEvaluationAtomicCounters = <span class="integer">0</span>; 11729<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTessEvaluationAtomicCounterBuffers = <span class="integer">0</span>; 11730 11731<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxGeometryInputComponents = <span class="integer">64</span>; 11732<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxGeometryOutputComponents = <span class="integer">64</span>; 11733<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxGeometryImageUniforms = <span class="integer">0</span>; 11734<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxGeometryTextureImageUnits = <span class="integer">16</span>; 11735<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxGeometryOutputVertices = <span class="integer">256</span>; 11736<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxGeometryTotalOutputComponents = <span class="integer">1024</span>; 11737<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxGeometryUniformComponents = <span class="integer">1024</span>; 11738<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxGeometryAtomicCounters = <span class="integer">0</span>; 11739<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxGeometryAtomicCounterBuffers = <span class="integer">0</span>; 11740 11741<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxFragmentInputVectors = <span class="integer">15</span>; 11742<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxFragmentImageUniforms = <span class="integer">4</span>; 11743<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxFragmentUniformVectors = <span class="integer">256</span>; 11744<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxFragmentAtomicCounters = <span class="integer">8</span>; 11745<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxFragmentAtomicCounterBuffers = <span class="integer">1</span>; 11746 11747<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxDrawBuffers = <span class="integer">4</span>; 11748<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxTextureImageUnits = <span class="integer">16</span>; 11749<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MinProgramTexelOffset = -<span class="integer">8</span>; 11750<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxProgramTexelOffset = <span class="integer">7</span>; 11751<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxImageUnits = <span class="integer">4</span>; 11752<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxSamples = <span class="integer">4</span>; 11753 11754<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxComputeImageUniforms = <span class="integer">4</span>; 11755<span class="directive">const</span> highp ivec3 gl_MaxComputeWorkGroupCount = ivec3(<span class="integer">65535</span>, <span class="integer">65535</span>, <span class="integer">65535</span>); 11756<span class="directive">const</span> highp ivec3 gl_MaxComputeWorkGroupSize = ivec3(<span class="integer">128</span>, <span class="integer">128</span>, <span class="integer">64</span>); 11757<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxComputeUniformComponents = <span class="integer">1024</span>; 11758<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxComputeTextureImageUnits = <span class="integer">16</span>; 11759<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxComputeAtomicCounters = <span class="integer">8</span>; 11760<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxComputeAtomicCounterBuffers = <span class="integer">1</span>; 11761 11762<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxCombinedTextureImageUnits = <span class="integer">96</span>; 11763<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxCombinedImageUniforms = <span class="integer">4</span>; 11764<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxCombinedShaderOutputResources = <span class="integer">4</span>; 11765<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxCombinedAtomicCounters = <span class="integer">8</span>; 11766<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxCombinedAtomicCounterBuffers = <span class="integer">1</span>; 11767<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxAtomicCounterBindings = <span class="integer">1</span>; 11768<span class="directive">const</span> mediump <span class="predefined-type">int</span> gl_MaxAtomicCounterBufferSize = <span class="integer">32</span>; 11769 11770<span class="directive">const</span> highp <span class="predefined-type">int</span> gl_MaxInputAttachments = <span class="integer">1</span>; <span class="comment">// only present when targeting Vulkan</span></code></pre> 11771</div> 11772</div> 11773</div> 11774<div class="sect2"> 11775<h3 id="built-in-uniform-state">7.3. Built-In Uniform State</h3> 11776<div class="paragraph"> 11777<p>Built-in uniform state is not available when generating SPIR-V. 11778Otherwise, as an aid to accessing OpenGL ES processing state, the following 11779uniform variables are built into the OpenGL ES Shading Language.</p> 11780</div> 11781<div class="listingblock"> 11782<div class="content"> 11783<pre class="CodeRay highlight"><code data-lang="c++"><span class="comment">//</span> 11784<span class="comment">// Depth range in window coordinates,</span> 11785<span class="comment">// section 12.5.1 "Controlling the Viewport" in the</span> 11786<span class="comment">// OpenGL ES Specification.</span> 11787<span class="comment">//</span> 11788<span class="keyword">struct</span> gl_DepthRangeParameters { 11789 highp <span class="predefined-type">float</span> near; <span class="comment">// n</span> 11790 highp <span class="predefined-type">float</span> far; <span class="comment">// f</span> 11791 highp <span class="predefined-type">float</span> diff; <span class="comment">// f - n</span> 11792}; 11793uniform gl_DepthRangeParameters gl_DepthRange; 11794uniform lowp <span class="predefined-type">int</span> gl_NumSamples;</code></pre> 11795</div> 11796</div> 11797<div class="paragraph"> 11798<p>These variables are only guaranteed to be available in the fragment stage. 11799In other stages, their presence and function is implementation-defined.</p> 11800</div> 11801</div> 11802<div class="sect2"> 11803<h3 id="redeclaring-built-in-blocks">7.4. Redeclaring Built-In Blocks</h3> 11804<div class="paragraph"> 11805<p>The <em>gl_PerVertex</em> block can be redeclared in a shader to explicitly 11806indicate what subset of the fixed pipeline interface will be used. 11807This is necessary to establish the interface between multiple programs.</p> 11808</div> 11809<div class="paragraph"> 11810<p>If the <em>gl_PerVertex</em> block is not redefined in a given program, the 11811intrinsically declared definition of that block is used for the program 11812interface.</p> 11813</div> 11814<div class="paragraph"> 11815<p>For example:</p> 11816</div> 11817<div class="listingblock"> 11818<div class="content"> 11819<pre class="CodeRay highlight"><code data-lang="c++">out gl_PerVertex { 11820 highp vec4 gl_Position; <span class="comment">// will use gl_Position</span> 11821 highp vec4 t; <span class="comment">// error, only gl_PerVertex members allowed</span> 11822}; <span class="comment">// no other members of gl_PerVertex will be used</span></code></pre> 11823</div> 11824</div> 11825<div class="paragraph"> 11826<p>This establishes the output interface the shader will use with the 11827subsequent pipeline stage. 11828It must be a subset of the built-in members of <em>gl_PerVertex</em>. 11829Such a redeclaration can also add the <strong>invariant</strong> qualifier and 11830interpolation qualifiers.</p> 11831</div> 11832<div class="paragraph"> 11833<p>Other layout qualifiers, like <strong>location</strong>, cannot be added to such a 11834redeclaration, unless specifically stated.</p> 11835</div> 11836<div class="paragraph"> 11837<p>If a built-in interface block is redeclared, it must appear in the shader 11838before any use of any member included in the built-in declaration, or a 11839compile-time error will result. 11840It is also a compile-time error to redeclare the block more than once or to 11841redeclare a built-in block and then use a member from that built-in block 11842that was not included in the redeclaration. 11843Also, if a built-in interface block is redeclared, no member of the built-in 11844declaration can be redeclared outside the block redeclaration. 11845If multiple shaders using members of a built-in block belonging to the same 11846interface are linked together in the same program, they must all redeclare 11847the built-in block in the same way, as described in 11848“<a href="#interface-blocks">Interface Blocks</a>” for interface block matching, or a 11849link-time error will result. 11850It will also be a link-time error if some shaders in a program redeclare a 11851specific built-in interface block while another shader in that program does 11852not redeclare that interface block yet still uses a member of that interface 11853block. 11854If a built-in block interface is formed across shaders in different 11855programs, the shaders must all redeclare the built-in block in the same way 11856(as described for a single program), or the values passed along the 11857interface are undefined.</p> 11858</div> 11859</div> 11860</div> 11861</div> 11862<div class="sect1"> 11863<h2 id="built-in-functions">8. Built-In Functions</h2> 11864<div class="sectionbody"> 11865<div class="paragraph"> 11866<p>The OpenGL ES Shading Language defines an assortment of built-in convenience functions for 11867scalar and vector operations. 11868Many of these built-in functions can be used in more than one type of 11869shader, but some are intended to provide a direct mapping to hardware and so 11870are available only for a specific type of shader.</p> 11871</div> 11872<div class="paragraph"> 11873<p>The built-in functions basically fall into three categories:</p> 11874</div> 11875<div class="ulist"> 11876<ul> 11877<li> 11878<p>They expose some necessary hardware functionality in a convenient way 11879such as accessing a texture map. 11880There is no way in the language for these functions to be emulated by a 11881shader.</p> 11882</li> 11883<li> 11884<p>They represent a trivial operation (clamp, mix, etc.) that is very 11885simple for the user to write, but they are very common and may have 11886direct hardware support. 11887It is a very hard problem for the compiler to map expressions to complex 11888assembler instructions.</p> 11889</li> 11890<li> 11891<p>They represent an operation graphics hardware is likely to accelerate at 11892some point. 11893The trigonometry functions fall into this category.</p> 11894</li> 11895</ul> 11896</div> 11897<div class="paragraph"> 11898<p>Many of the functions are similar to the same named ones in common C 11899libraries, but they support vector input as well as the more traditional 11900scalar input.</p> 11901</div> 11902<div class="paragraph"> 11903<p>Applications should be encouraged to use the built-in functions rather than 11904do the equivalent computations in their own shader code since the built-in 11905functions are assumed to be optimal (e.g. perhaps supported directly in 11906hardware).</p> 11907</div> 11908<div class="paragraph"> 11909<p>When the built-in functions are specified below, where the input arguments 11910(and corresponding output) can be <strong>float</strong>, <strong>vec2</strong>, <strong>vec3</strong>, or <strong>vec4</strong>, 11911<em>genFType</em> is used as the argument. 11912Where the input arguments (and corresponding output) can be <strong>int</strong>, <strong>ivec2</strong>, 11913<strong>ivec3</strong>, or <strong>ivec4</strong>, <em>genIType</em> is used as the argument. 11914Where the input arguments (and corresponding output) can be <strong>uint</strong>, <strong>uvec2</strong>, 11915<strong>uvec3</strong>, or <strong>uvec4</strong>, <em>genUType</em> is used as the argument. 11916Where the input arguments (or corresponding output) can be <strong>bool</strong>, <strong>bvec2</strong>, 11917<strong>bvec3</strong>, or <strong>bvec4</strong>, <em>genBType</em> is used as the argument. 11918For any specific use of a function, the actual types substituted for 11919<em>genFType</em>, <em>genIType</em>, <em>genUType</em>, or <em>genBType</em> have to have the same 11920number of components for all arguments and for the return type. 11921Similarly, <em>mat</em> is used for any matrix basic 11922type.</p> 11923</div> 11924<div class="paragraph"> 11925<p>Built-in functions have an effective precision qualification. 11926This qualification cannot be set explicitly and may be different from the 11927precision qualification of the result.</p> 11928</div> 11929<div class="paragraph"> 11930<p>The precision qualification of the operation of a built-in function is based 11931on the precision qualification of its formal parameters and actual 11932parameters (input arguments): When a formal parameter specifies a precision 11933qualifier, that is used, otherwise, the precision qualification of the 11934actual (calling) argument is used. 11935The highest precision of these will be the precision of the operation of the 11936built-in function. 11937Generally, this is applied across all arguments to a built-in function, with 11938the exceptions being:</p> 11939</div> 11940<div class="ulist"> 11941<ul> 11942<li> 11943<p><strong>bitfieldExtract</strong> and <strong>bitfieldInsert</strong> ignore the <em>offset</em> and <em>bits</em> 11944arguments.</p> 11945</li> 11946<li> 11947<p><strong>interpolateAt</strong> functions only look at the <em>interpolant</em> argument.</p> 11948</li> 11949</ul> 11950</div> 11951<div class="paragraph"> 11952<p>The precision qualification of the result of a built-in function is 11953determined in one of the following ways:</p> 11954</div> 11955<div class="paragraph"> 11956<p>For the texture sampling, image load and image store functions, the 11957precision of the return type matches the precision of the 11958texture-combined sampler type:</p> 11959</div> 11960<div class="listingblock"> 11961<div class="content"> 11962<pre class="CodeRay highlight"><code data-lang="c++">uniform lowp sampler2D texSampler; 11963highp vec2 coord; 11964... 11965lowp vec4 col = texture (texSampler, coord); <span class="comment">// texture() returns lowp</span></code></pre> 11966</div> 11967</div> 11968<div class="paragraph"> 11969<p>Otherwise:</p> 11970</div> 11971<div class="ulist"> 11972<ul> 11973<li> 11974<p>For prototypes that do not specify a resulting precision qualifier, the 11975precision will be the same as the precision of the operation (as defined 11976earlier).</p> 11977</li> 11978<li> 11979<p>For prototypes that do specify a resulting precision qualifier, the 11980specified precision qualifier is the precision qualification of the 11981result.</p> 11982</li> 11983</ul> 11984</div> 11985<div class="paragraph"> 11986<p>Where the built-in functions in the following sections specify an equation, 11987the entire equation will be evaluated at the operation’s precision. 11988This may lead to underflow or overflow in the result, even when the correct 11989result could be represented in the operation precision.</p> 11990</div> 11991<div class="sect2"> 11992<h3 id="angle-and-trigonometry-functions">8.1. Angle and Trigonometry Functions</h3> 11993<div class="paragraph"> 11994<p>Function parameters specified as <em>angle</em> are assumed to be in units of 11995radians. 11996In no case will any of these functions result in a divide by zero error. 11997If the divisor of a ratio is 0, then results will be undefined.</p> 11998</div> 11999<div class="paragraph"> 12000<p>These all operate component-wise. 12001The description is per component.</p> 12002</div> 12003<table class="tableblock frame-all grid-all stretch"> 12004<colgroup> 12005<col style="width: 50%;"> 12006<col style="width: 50%;"> 12007</colgroup> 12008<thead> 12009<tr> 12010<th class="tableblock halign-left valign-top">Syntax</th> 12011<th class="tableblock halign-left valign-top">Description</th> 12012</tr> 12013</thead> 12014<tbody> 12015<tr> 12016<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>radians</strong>(genFType <em>degrees</em>)</p></td> 12017<td class="tableblock halign-left valign-top"><p class="tableblock">Converts <em>degrees</em> to radians, i.e., 12018 <span class="eq">(π / 180) · degrees</span>.</p></td> 12019</tr> 12020<tr> 12021<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>degrees</strong>(genFType <em>radians</em>)</p></td> 12022<td class="tableblock halign-left valign-top"><p class="tableblock">Converts <em>radians</em> to degrees, i.e., 12023 <span class="eq">(180 / π) · radians</span>.</p></td> 12024</tr> 12025<tr> 12026<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>sin</strong>(genFType <em>angle</em>)</p></td> 12027<td class="tableblock halign-left valign-top"><p class="tableblock">The standard trigonometric sine function.</p></td> 12028</tr> 12029<tr> 12030<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>cos</strong>(genFType <em>angle</em>)</p></td> 12031<td class="tableblock halign-left valign-top"><p class="tableblock">The standard trigonometric cosine function.</p></td> 12032</tr> 12033<tr> 12034<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>tan</strong>(genFType <em>angle</em>)</p></td> 12035<td class="tableblock halign-left valign-top"><p class="tableblock">The standard trigonometric tangent.</p></td> 12036</tr> 12037<tr> 12038<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>asin</strong>(genFType <em>x</em>)</p></td> 12039<td class="tableblock halign-left valign-top"><p class="tableblock">Arc sine. 12040 Returns an angle whose sine is <em>x</em>. 12041 The range of values returned by this function is 12042 <span class="eq">[-π / 2, π / 2]</span>. 12043 Results are undefined if <span class="eq">|x| > 1</span>.</p></td> 12044</tr> 12045<tr> 12046<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>acos</strong>(genFType <em>x</em>)</p></td> 12047<td class="tableblock halign-left valign-top"><p class="tableblock">Arc cosine. 12048 Returns an angle whose cosine is <em>x</em>. 12049 The range of values returned by this function is <span class="eq">[0,π]</span>. 12050 Results are undefined if <span class="eq">|x| > 1</span>.</p></td> 12051</tr> 12052<tr> 12053<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>atan</strong>(genFType <em>y</em>, genFType <em>x</em>)</p></td> 12054<td class="tableblock halign-left valign-top"><p class="tableblock">Arc tangent. 12055 Returns an angle whose tangent is <span class="eq">y / x</span>. 12056 The signs of <em>x</em> and <em>y</em> are used to determine what quadrant the angle 12057 is in. 12058 The range of values returned by this function is <span class="eq">[-π, π</span>. 12059 Results are undefined if <em>x</em> and <em>y</em> are both 0.</p></td> 12060</tr> 12061<tr> 12062<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>atan</strong>(genFType <em>y_over_x</em>)</p></td> 12063<td class="tableblock halign-left valign-top"><p class="tableblock">Arc tangent. 12064 Returns an angle whose tangent is <em>y_over_x</em>. 12065 The range of values returned by this function is 12066 <span class="eq">[-π / 2, π / 2]</span>.</p></td> 12067</tr> 12068<tr> 12069<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>sinh</strong>(genFType <em>x</em>)</p></td> 12070<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the hyperbolic sine function <span class="eq">(e<sup>x</sup> - e<sup>-x</sup>) / 2</span>.</p></td> 12071</tr> 12072<tr> 12073<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>cosh</strong>(genFType <em>x</em>)</p></td> 12074<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the hyperbolic cosine function <span class="eq">(e<sup>x</sup> + e<sup>-x</sup>) / 2</span>.</p></td> 12075</tr> 12076<tr> 12077<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>tanh</strong>(genFType <em>x</em>)</p></td> 12078<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the hyperbolic tangent function <span class="eq">sinh(x) / cosh(x)</span>.</p></td> 12079</tr> 12080<tr> 12081<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>asinh</strong>(genFType <em>x</em>)</p></td> 12082<td class="tableblock halign-left valign-top"><p class="tableblock">Arc hyperbolic sine; returns the inverse of <strong>sinh</strong>.</p></td> 12083</tr> 12084<tr> 12085<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>acosh</strong>(genFType <em>x</em>)</p></td> 12086<td class="tableblock halign-left valign-top"><p class="tableblock">Arc hyperbolic cosine; returns the non-negative inverse of <strong>cosh</strong>. 12087 Results are undefined if <span class="eq">x < 1</span>.</p></td> 12088</tr> 12089<tr> 12090<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>atanh</strong>(genFType <em>x</em>)</p></td> 12091<td class="tableblock halign-left valign-top"><p class="tableblock">Arc hyperbolic tangent; returns the inverse of <strong>tanh</strong>. 12092 Results are undefined if <span class="eq">x ≥ 1</span>.</p></td> 12093</tr> 12094</tbody> 12095</table> 12096</div> 12097<div class="sect2"> 12098<h3 id="exponential-functions">8.2. Exponential Functions</h3> 12099<div class="paragraph"> 12100<p>These all operate component-wise. 12101The description is per component.</p> 12102</div> 12103<table class="tableblock frame-all grid-all stretch"> 12104<colgroup> 12105<col style="width: 50%;"> 12106<col style="width: 50%;"> 12107</colgroup> 12108<thead> 12109<tr> 12110<th class="tableblock halign-left valign-top">Syntax</th> 12111<th class="tableblock halign-left valign-top">Description</th> 12112</tr> 12113</thead> 12114<tbody> 12115<tr> 12116<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>pow</strong>(genFType <em>x</em>, genFType <em>y</em>)</p></td> 12117<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <em>x</em> raised to the <em>y</em> power, i.e., <span class="eq">x<sup>y</sup></span>. 12118 Results are undefined if <span class="eq">x < 0</span>. 12119 Results are undefined if <span class="eq">x = 0</span> and <span class="eq">y ≤ 0</span>.</p></td> 12120</tr> 12121<tr> 12122<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>exp</strong>(genFType <em>x</em>)</p></td> 12123<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the natural exponentiation of <em>x</em>, i.e., <span class="eq">e<sup>x</sup></span>.</p></td> 12124</tr> 12125<tr> 12126<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>log</strong>(genFType <em>x</em>)</p></td> 12127<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the natural logarithm of <em>x</em>, i.e., returns the value <em>y</em> 12128 which satisfies the equation <span class="eq">x = e<sup>y</sup></span>. 12129 Results are undefined if <span class="eq">x ≤ 0</span>.</p></td> 12130</tr> 12131<tr> 12132<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>exp2</strong>(genFType <em>x</em>)</p></td> 12133<td class="tableblock halign-left valign-top"><p class="tableblock">Returns 2 raised to the <em>x</em> power, i.e., <span class="eq">2<sup>x</sup></span>.</p></td> 12134</tr> 12135<tr> 12136<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>log2</strong>(genFType <em>x</em>)</p></td> 12137<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the base 2 logarithm of <em>x</em>, i.e., returns the value <em>y</em> which 12138 satisfies the equation <span class="eq">x = 2<sup>y</sup></span>. 12139 Results are undefined if <span class="eq">x ≤ 0</span>.</p></td> 12140</tr> 12141<tr> 12142<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>sqrt</strong>(genFType <em>x</em>)<br> 12143 genDType <strong>sqrt</strong>(genDType <em>x</em>)</p></td> 12144<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <span class="eq">sqrt(x)</span>. 12145 Results are undefined if <span class="eq">x < 0</span>.</p></td> 12146</tr> 12147<tr> 12148<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>inversesqrt</strong>(genFType <em>x</em>)<br> 12149 genDType <strong>inversesqrt</strong>(genDType <em>x</em>)</p></td> 12150<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <span class="eq">1 / sqrt(x)</span>. 12151 Results are undefined if <span class="eq">x ≤ 0</span>.</p></td> 12152</tr> 12153</tbody> 12154</table> 12155</div> 12156<div class="sect2"> 12157<h3 id="common-functions">8.3. Common Functions</h3> 12158<div class="paragraph"> 12159<p>These all operate component-wise. 12160The description is per component.</p> 12161</div> 12162<table class="tableblock frame-all grid-all stretch"> 12163<colgroup> 12164<col style="width: 50%;"> 12165<col style="width: 50%;"> 12166</colgroup> 12167<thead> 12168<tr> 12169<th class="tableblock halign-left valign-top">Syntax</th> 12170<th class="tableblock halign-left valign-top">Description</th> 12171</tr> 12172</thead> 12173<tbody> 12174<tr> 12175<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>abs</strong>(genFType <em>x</em>)<br> 12176 genIType <strong>abs</strong>(genIType <em>x</em>)</p></td> 12177<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <em>x</em> if <span class="eq">x ≥ 0</span>; otherwise it returns -<em>x</em>.</p></td> 12178</tr> 12179<tr> 12180<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>sign</strong>(genFType <em>x</em>)<br> 12181 genIType <strong>sign</strong>(genIType <em>x</em>)</p></td> 12182<td class="tableblock halign-left valign-top"><p class="tableblock">Returns 1.0 if <em>x</em> > 0, 0.0 if <em>x</em> = 0, or -1.0 if <em>x</em> < 0.</p></td> 12183</tr> 12184<tr> 12185<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>floor</strong>(genFType <em>x</em>)</p></td> 12186<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a value equal to the nearest integer that is less than or 12187 equal to <em>x</em>.</p></td> 12188</tr> 12189<tr> 12190<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>trunc</strong>(genFType <em>x</em>)</p></td> 12191<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a value equal to the nearest integer to <em>x</em> whose absolute 12192 value is not larger than the absolute value of <em>x</em>.</p></td> 12193</tr> 12194<tr> 12195<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>round</strong>(genFType <em>x</em>)</p></td> 12196<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a value equal to the nearest integer to <em>x</em>. 12197 The fraction 0.5 will round in a direction chosen by the 12198 implementation, presumably the direction that is fastest. 12199 This includes the possibility that <strong>round</strong>(<em>x</em>) returns the same value 12200 as <strong>roundEven</strong>(<em>x</em>) for all values of <em>x</em>.</p></td> 12201</tr> 12202<tr> 12203<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>roundEven</strong>(genFType <em>x</em>)</p></td> 12204<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a value equal to the nearest integer to <em>x</em>. 12205 A fractional part of 0.5 will round toward the nearest even integer. 12206 (Both 3.5 and 4.5 for x will return 4.0.)</p></td> 12207</tr> 12208<tr> 12209<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>ceil</strong>(genFType <em>x</em>)</p></td> 12210<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a value equal to the nearest integer that is greater than or 12211 equal to <em>x</em>.</p></td> 12212</tr> 12213<tr> 12214<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>fract</strong>(genFType <em>x</em>)</p></td> 12215<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <em>x</em> - <strong>floor</strong>(<em>x</em>).</p></td> 12216</tr> 12217<tr> 12218<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>mod</strong>(genFType <em>x</em>, float <em>y</em>)<br> 12219 genFType <strong>mod</strong>(genFType <em>x</em>, genFType <em>y</em>)</p></td> 12220<td class="tableblock halign-left valign-top"><p class="tableblock">Modulus. 12221 Returns <span class="eq">x - y · <strong>floor</strong>(x / y)</span>.</p></td> 12222</tr> 12223<tr> 12224<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>modf</strong>(genFType <em>x</em>, out genFType <em>i</em>)<br></p></td> 12225<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the fractional part of <em>x</em> and sets <em>i</em> to the integer part (as 12226 a whole number floating-point value). 12227 Both the return value and the output parameter will have the same sign 12228 as <em>x</em>. 12229 If <em>x</em> has the value +/- Inf, the return value should be NaN and must 12230 be either NaN or 0.0. 12231 For <strong>highp</strong> non-constant expressions, the value returned must be 12232 consistent.</p></td> 12233</tr> 12234<tr> 12235<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>min</strong>(genFType <em>x</em>, genFType <em>y</em>)<br> 12236 genFType <strong>min</strong>(genFType <em>x</em>, float <em>y</em>)<br> 12237 genIType <strong>min</strong>(genIType <em>x</em>, genIType <em>y</em>)<br> 12238 genIType <strong>min</strong>(genIType <em>x</em>, int <em>y</em>)<br> 12239 genUType <strong>min</strong>(genUType <em>x</em>, genUType <em>y</em>)<br> 12240 genUType <strong>min</strong>(genUType <em>x</em>, uint <em>y</em>)</p></td> 12241<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <em>y</em> if <em>y</em> < <em>x;</em> otherwise it returns <em>x</em>.</p></td> 12242</tr> 12243<tr> 12244<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>max</strong>(genFType <em>x</em>, genFType <em>y</em>)<br> 12245 genFType <strong>max</strong>(genFType <em>x</em>, float <em>y</em>)<br> 12246 genIType <strong>max</strong>(genIType <em>x</em>, genIType <em>y</em>)<br> 12247 genIType <strong>max</strong>(genIType <em>x</em>, int <em>y</em>)<br> 12248 genUType <strong>max</strong>(genUType <em>x</em>, genUType <em>y</em>)<br> 12249 genUType <strong>max</strong>(genUType <em>x</em>, uint <em>y</em>)</p></td> 12250<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <em>y</em> if <em>x</em> < <em>y;</em> otherwise it returns <em>x</em>.</p></td> 12251</tr> 12252<tr> 12253<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>clamp</strong>(genFType <em>x</em>, genFType <em>minVal</em>, genFType <em>maxVal</em>)<br> 12254 genFType <strong>clamp</strong>(genFType <em>x</em>, float <em>minVal</em>, float <em>maxVal</em>)<br> 12255 genIType <strong>clamp</strong>(genIType <em>x</em>, genIType <em>minVal</em>, genIType <em>maxVal</em>)<br> 12256 genIType <strong>clamp</strong>(genIType <em>x</em>, int <em>minVal</em>, int <em>maxVal</em>)<br> 12257 genUType <strong>clamp</strong>(genUType <em>x</em>, genUType <em>minVal</em>, genUType <em>maxVal</em>)<br> 12258 genUType <strong>clamp</strong>(genUType <em>x</em>, uint <em>minVal</em>, uint <em>maxVal</em>)</p></td> 12259<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <strong>min</strong>(<strong>max</strong>(<em>x</em>, <em>minVal</em>), <em>maxVal</em>). 12260 Results are undefined if <em>minVal</em> > <em>maxVal</em>.</p></td> 12261</tr> 12262<tr> 12263<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>mix</strong>(genFType <em>x</em>, genFType <em>y</em>, genFType <em>a</em>)<br> 12264 genFType <strong>mix</strong>(genFType <em>x</em>, genFType <em>y</em>, float <em>a</em>)<br></p></td> 12265<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the linear blend of <em>x</em> and <em>y</em>, i.e., 12266 <span class="eq">x · (1 - a) + y · a</span>.</p></td> 12267</tr> 12268<tr> 12269<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>mix</strong>(genFType <em>x</em>, genFType <em>y</em>, genBType <em>a</em>)<br> 12270 genIType <strong>mix</strong>(genIType <em>x</em>, genIType <em>y</em>, genBType <em>a</em>)<br> 12271 genUType <strong>mix</strong>(genUType <em>x</em>, genUType <em>y</em>, genBType <em>a</em>)<br> 12272 genBType <strong>mix</strong>(genBType <em>x</em>, genBType <em>y</em>, genBType <em>a</em>)</p></td> 12273<td class="tableblock halign-left valign-top"><p class="tableblock">Selects which vector each returned component comes from. 12274 For a component of <em>a</em> that is <strong>false</strong>, the corresponding component of 12275 <em>x</em> is returned. 12276 For a component of <em>a</em> that is <strong>true</strong>, the corresponding component of 12277 <em>y</em> is returned. 12278 Components of <em>x</em> and <em>y</em> that are not selected are allowed to be 12279 invalid floating-point values and will have no effect on the results. 12280 Thus, this provides different functionality than, for example,<br> 12281 genFType <strong>mix</strong>(genFType <em>x</em>, genFType <em>y</em>, genFType(<em>a</em>))<br> 12282 where <em>a</em> is a Boolean vector.</p></td> 12283</tr> 12284<tr> 12285<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>step</strong>(genFType <em>edge</em>, genFType <em>x</em>)<br> 12286 genFType <strong>step</strong>(float <em>edge</em>, genFType <em>x</em>)</p></td> 12287<td class="tableblock halign-left valign-top"><p class="tableblock">Returns 0.0 if <em>x</em> < <em>edge;</em> otherwise it returns 1.0.</p></td> 12288</tr> 12289<tr> 12290<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>smoothstep</strong>(genFType <em>edge0</em>, genFType <em>edge1</em>, genFType <em>x</em>)<br> 12291 genFType <strong>smoothstep</strong>(float <em>edge0</em>, float <em>edge1</em>, genFType <em>x</em>)<br></p></td> 12292<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 12293<p>Returns 0.0 if <span class="eq">x ≤ edge0</span> and 1.0 if <span class="eq">x ≥ edge1</span>, and 12294 performs smooth Hermite interpolation between 0 and 1 when <span class="eq">edge0 12295 < x < edge1</span>. 12296 This is useful in cases where you would want a threshold function with 12297 a smooth transition. 12298 This is equivalent to:</p> 12299</div> 12300<div class="openblock"> 12301<div class="content"> 12302<div class="listingblock"> 12303<div class="content"> 12304<pre class="CodeRay highlight"><code data-lang="c++">genFType t; 12305t = clamp ((x - edge0) / (edge1 - edge0), <span class="integer">0</span>, <span class="integer">1</span>); 12306<span class="keyword">return</span> t * t * (<span class="integer">3</span> - <span class="integer">2</span> * t);</code></pre> 12307</div> 12308</div> 12309<div class="paragraph"> 12310<p>(And similarly for doubles.) Results are undefined if <span class="eq">edge0 ≥ 12311edge1</span>.</p> 12312</div> 12313</div> 12314</div></div></td> 12315</tr> 12316<tr> 12317<td class="tableblock halign-left valign-top"><p class="tableblock">genBType <strong>isnan</strong>(genFType <em>x</em>)</p></td> 12318<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <strong>true</strong> if <em>x</em> holds a NaN. 12319 Returns <strong>false</strong> otherwise. 12320 Always returns <strong>false</strong> if NaNs are not implemented.</p></td> 12321</tr> 12322<tr> 12323<td class="tableblock halign-left valign-top"><p class="tableblock">genBType <strong>isinf</strong>(genFType <em>x</em>)</p></td> 12324<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <strong>true</strong> if <em>x</em> holds a positive infinity or negative infinity. 12325 Returns <strong>false</strong> otherwise.</p></td> 12326</tr> 12327<tr> 12328<td class="tableblock halign-left valign-top"><p class="tableblock">genIType <strong>floatBitsToInt</strong>(highp genFType <em>value</em>)<br> 12329 genUType <strong>floatBitsToUint</strong>(highp genFType <em>value</em>)</p></td> 12330<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a signed or unsigned integer value representing the encoding 12331 of a floating-point value. 12332 The <strong>float</strong> value’s bit-level representation is preserved.</p></td> 12333</tr> 12334<tr> 12335<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>intBitsToFloat</strong>(highp genIType <em>value</em>)<br> 12336 genFType <strong>uintBitsToFloat</strong>(highp genUType <em>value</em>)</p></td> 12337<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a floating-point value corresponding to a signed or unsigned 12338 integer encoding of a floating-point value. 12339 If an Inf or NaN is passed in, it will not signal, and the resulting 12340 floating-point value is unspecified. 12341 Otherwise, the bit-level representation is preserved.</p></td> 12342</tr> 12343<tr> 12344<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>fma</strong>(genFType <em>a</em>, genFType <em>b</em>, genFType <em>c</em>)<br></p></td> 12345<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 12346<p>Computes and returns <code>a * b + c</code>. 12347 In uses where the return value is eventually consumed by a variable 12348 declared as <strong>precise</strong>:</p> 12349</div> 12350<div class="openblock"> 12351<div class="content"> 12352<div class="ulist"> 12353<ul> 12354<li> 12355<p><strong>fma</strong>() is considered a single operation, whereas the expression <code>a * b 12356+ c</code> consumed by a variable declared <strong>precise</strong> is considered two 12357operations.</p> 12358</li> 12359<li> 12360<p>The precision of <strong>fma</strong>() can differ from the precision of the expression 12361<code>a * b + c</code>.</p> 12362</li> 12363<li> 12364<p><strong>fma</strong>() will be computed with the same precision as any other <strong>fma</strong>() 12365consumed by a precise variable, giving invariant results for the same 12366input values of <em>a</em>, <em>b</em>, and <em>c</em>.</p> 12367</li> 12368</ul> 12369</div> 12370<div class="paragraph"> 12371<p>Otherwise, in the absence of <strong>precise</strong> consumption, there are no special 12372constraints on the number of operations or difference in precision between 12373<strong>fma</strong>() and the expression <code>a * b + c</code>.</p> 12374</div> 12375</div> 12376</div></div></td> 12377</tr> 12378<tr> 12379<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>frexp</strong>(highp genFType <em>x</em>, out highp genIType <em>exp</em>)</p></td> 12380<td class="tableblock halign-left valign-top"><p class="tableblock">Splits <em>x</em> into a floating-point significand in the range 12381 <span class="eq">[0.5,1.0]</span>, and an integral exponent of two, such that</p> 12382<p class="tableblock"> <span class="eq">x = significant · 2<sup>exponent</sup></span></p> 12383<p class="tableblock"> The significand is returned by the function and the exponent is 12384 returned in the parameter <em>exp</em>. 12385 For a floating-point value of zero, the significand and exponent are 12386 both zero.</p> 12387<p class="tableblock"> If an implementation supports signed zero, an input value of minus 12388 zero should return a significand of minus zero. 12389 For a floating-point value that is an infinity or is not a number, the 12390 results are undefined.</p> 12391<p class="tableblock"> If the input <em>x</em> is a vector, this operation is performed in a 12392 component-wise manner; the value returned by the function and the 12393 value written to <em>exp</em> are vectors with the same number of components 12394 as <em>x</em>.</p></td> 12395</tr> 12396<tr> 12397<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>ldexp</strong>(highp genFType <em>x</em>, highp genIType <em>exp</em>)<br></p></td> 12398<td class="tableblock halign-left valign-top"><p class="tableblock">Builds a floating-point number from <em>x</em> and the corresponding integral 12399 exponent of two in <em>exp</em>, returning:</p> 12400<p class="tableblock"> <span class="eq">significand · 2<sup>exponent</sup></span></p> 12401<p class="tableblock"> If this product is too large to be represented in the floating-point 12402 type, the result is undefined.</p> 12403<p class="tableblock"> If <em>exp</em> is greater than +128, the value returned is undefined. 12404 If <em>exp</em> is less than -126, the value returned may be flushed to zero. 12405 Additionally, splitting the value into a significand and exponent 12406 using <strong>frexp</strong>() and then reconstructing a floating-point value using 12407 <strong>ldexp</strong>() should yield the original input for zero and all finite 12408 non-denormalized values.<br> 12409 If the input <em>x</em> is a vector, this operation is performed in a 12410 component-wise manner; the value passed in <em>exp</em> and returned by the 12411 function are vectors with the same number of components as <em>x</em>.</p></td> 12412</tr> 12413</tbody> 12414</table> 12415</div> 12416<div class="sect2"> 12417<h3 id="floating-point-pack-and-unpack-functions">8.4. Floating-Point Pack and Unpack Functions</h3> 12418<div class="paragraph"> 12419<p>These functions do not operate component-wise, rather, as described in each 12420case.</p> 12421</div> 12422<table class="tableblock frame-all grid-all stretch"> 12423<colgroup> 12424<col style="width: 50%;"> 12425<col style="width: 50%;"> 12426</colgroup> 12427<thead> 12428<tr> 12429<th class="tableblock halign-left valign-top">Syntax</th> 12430<th class="tableblock halign-left valign-top">Description</th> 12431</tr> 12432</thead> 12433<tbody> 12434<tr> 12435<td class="tableblock halign-left valign-top"><p class="tableblock">highp uint <strong>packUnorm2x16</strong>(vec2 <em>v</em>)<br> 12436 highp uint <strong>packSnorm2x16</strong>(vec2 <em>v</em>)<br> 12437 highp uint <strong>packUnorm4x8</strong>(vec4 <em>v</em>)<br> 12438 highp uint <strong>packSnorm4x8</strong>(vec4 <em>v</em>)</p></td> 12439<td class="tableblock halign-left valign-top"><p class="tableblock">First, converts each component of the normalized floating-point value 12440 <em>v</em> into 16-bit (<strong>2x16</strong>) or 8-bit (<strong>4x8</strong>) integer values. 12441 Then, the results are packed into the returned 32-bit unsigned 12442 integer.</p> 12443<p class="tableblock"> The conversion for component <em>c</em> of <em>v</em> to fixed point is done as 12444 follows:</p> 12445<p class="tableblock"> <strong>packUnorm2x16</strong>: <strong>round</strong>(<strong>clamp</strong>(<em>c</em>, 0, +1) * 65535.0)<br> 12446 <strong>packSnorm2x16:</strong> <strong>round</strong>(<strong>clamp</strong>(<em>c</em>, -1, +1) * 32767.0)<br> 12447 <strong>packUnorm4x8</strong>: <strong>round</strong>(<strong>clamp</strong>(<em>c</em>, 0, +1) * 255.0)<br> 12448 <strong>packSnorm4x8</strong>: <strong>round</strong>(<strong>clamp</strong>(<em>c</em>, -1, +1) * 127.0)</p> 12449<p class="tableblock"> The first component of the vector will be written to the least 12450 significant bits of the output; the last component will be written to 12451 the most significant bits.</p></td> 12452</tr> 12453<tr> 12454<td class="tableblock halign-left valign-top"><p class="tableblock">highp vec2 <strong>unpackUnorm2x16</strong>(highp uint <em>p</em>)<br> 12455 highp vec2 <strong>unpackSnorm2x16</strong>(highp uint <em>p</em>)<br> 12456 mediump vec4 <strong>unpackUnorm4x8</strong>(highp uint <em>p</em>)<br> 12457 mediump vec4 <strong>unpackSnorm4x8</strong>(highp uint <em>p</em>)</p></td> 12458<td class="tableblock halign-left valign-top"><p class="tableblock">First, unpacks a single 32-bit unsigned integer <em>p</em> into a pair of 12459 16-bit unsigned integers, a pair of 16-bit signed integers, four 8-bit 12460 unsigned integers, or four 8-bit signed integers, respectively. 12461 Then, each component is converted to a normalized floating-point value 12462 to generate the returned two- or four-component vector.</p> 12463<p class="tableblock"> The conversion for unpacked fixed-point value <em>f</em> to floating-point is 12464 done as follows:</p> 12465<p class="tableblock"> <strong>unpackUnorm2x16</strong>: <em>f</em> / 65535.0<br> 12466 <strong>unpackSnorm2x16</strong>: <strong>clamp</strong>(<em>f</em> / 32767.0, -1, +1)<br> 12467 <strong>unpackUnorm4x8</strong>: <em>f</em> / 255.0<br> 12468 <strong>unpackSnorm4x8</strong>: <strong>clamp</strong>(<em>f</em> / 127.0, -1, +1)</p> 12469<p class="tableblock"> The first component of the returned vector will be extracted from the 12470 least significant bits of the input; the last component will be 12471 extracted from the most significant bits.</p></td> 12472</tr> 12473<tr> 12474<td class="tableblock halign-left valign-top"><p class="tableblock">highp uint <strong>packHalf2x16</strong>(vec2 <em>v</em>)</p></td> 12475<td class="tableblock halign-left valign-top"><p class="tableblock">Returns an unsigned integer obtained by converting the components of a 12476 two-component floating-point vector to the 16-bit floating-point 12477 representation of the <a href="#references">API</a>, and 12478 then packing these two 16-bit integers into a 32-bit unsigned integer.</p> 12479<p class="tableblock"> The first vector component specifies the 16 least-significant bits of 12480 the result; the second component specifies the 16 most-significant 12481 bits.</p></td> 12482</tr> 12483<tr> 12484<td class="tableblock halign-left valign-top"><p class="tableblock">mediump vec2 <strong>unpackHalf2x16</strong>(highp uint <em>v</em>)</p></td> 12485<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a two-component floating-point vector with components obtained 12486 by unpacking a 32-bit unsigned integer into a pair of 16-bit values, 12487 interpreting those values as 16-bit floating-point numbers according 12488 to the <a href="#references">API</a>, and converting them to 12489 32-bit floating-point values.</p> 12490<p class="tableblock"> The first component of the vector is obtained from the 16 12491 least-significant bits of <em>v</em>; the second component is obtained from 12492 the 16 most-significant bits of <em>v</em>.</p></td> 12493</tr> 12494</tbody> 12495</table> 12496</div> 12497<div class="sect2"> 12498<h3 id="geometric-functions">8.5. Geometric Functions</h3> 12499<div class="paragraph"> 12500<p>These operate on vectors as vectors, not component-wise.</p> 12501</div> 12502<table class="tableblock frame-all grid-all stretch"> 12503<colgroup> 12504<col style="width: 50%;"> 12505<col style="width: 50%;"> 12506</colgroup> 12507<thead> 12508<tr> 12509<th class="tableblock halign-left valign-top">Syntax</th> 12510<th class="tableblock halign-left valign-top">Description</th> 12511</tr> 12512</thead> 12513<tbody> 12514<tr> 12515<td class="tableblock halign-left valign-top"><p class="tableblock">float <strong>length</strong>(genFType <em>x</em>)</p></td> 12516<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 12517<p>Returns the length of vector <em>x</em>, i.e., 12518 <span class="eq">sqrt( x<sub>0</sub><sup>2</sup> + x<sub>1</sub><sup>2</sup> + …​ )</span>.</p> 12519</div></div></td> 12520</tr> 12521<tr> 12522<td class="tableblock halign-left valign-top"><p class="tableblock">float <strong>distance</strong>(genFType <em>p0</em>, genFType <em>p1</em>)</p></td> 12523<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the distance between <em>p0</em> and <em>p1</em>, i.e., 12524 <strong>length</strong>(<em>p0</em> - <em>p1</em>)</p></td> 12525</tr> 12526<tr> 12527<td class="tableblock halign-left valign-top"><p class="tableblock">float <strong>dot</strong>(genFType <em>x</em>, genFType <em>y</em>)</p></td> 12528<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the dot product of <em>x</em> and <em>y</em>, i.e., 12529 <span class="eq">x<sub>0</sub> · y<sub>0</sub> + x<sub>1</sub> · y<sub>1</sub> + …​</span></p></td> 12530</tr> 12531<tr> 12532<td class="tableblock halign-left valign-top"><p class="tableblock">vec3 <strong>cross</strong>(vec3 <em>x</em>, vec3 <em>y</em>)</p></td> 12533<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 12534<p>Returns the cross product of <em>x</em> and <em>y</em>, i.e., 12535 <span class="eq">(x<sub>1</sub> · y<sub>2</sub> - y<sub>1</sub> · x<sub>2</sub>, 12536 x<sub>2</sub> · y<sub>0</sub> - y<sub>2</sub> · x<sub>0</sub>, 12537 x<sub>0</sub> · y<sub>1</sub> - y<sub>0</sub> · x<sub>1</sub>)</span>.</p> 12538</div></div></td> 12539</tr> 12540<tr> 12541<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>normalize</strong>(genFType <em>x</em>)</p></td> 12542<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a vector in the same direction as <em>x</em> but with a length of 1, 12543 i.e. <em>x</em> / <strong>length</strong>(x).</p></td> 12544</tr> 12545<tr> 12546<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>faceforward</strong>(genFType <em>N</em>, genFType <em>I</em>, genFType <em>Nref</em>)<br></p></td> 12547<td class="tableblock halign-left valign-top"><p class="tableblock">If <strong>dot</strong>(<em>Nref</em>, <em>I</em>) < 0 return <em>N</em>, otherwise return -<em>N</em>.</p></td> 12548</tr> 12549<tr> 12550<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>reflect</strong>(genFType <em>I</em>, genFType <em>N</em>)</p></td> 12551<td class="tableblock halign-left valign-top"><p class="tableblock">For the incident vector <em>I</em> and surface orientation <em>N</em>, returns the 12552 reflection direction: <span class="eq">I - 2 · <strong>dot</strong>(N, I) · N</span>. 12553 <em>N</em> must already be normalized in order to achieve the desired result.</p></td> 12554</tr> 12555<tr> 12556<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>refract</strong>(genFType <em>I</em>, genFType <em>N</em>, float <em>eta</em>)<br></p></td> 12557<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 12558<p>For the incident vector <em>I</em> and surface normal <em>N</em>, and the ratio of 12559 indices of refraction <em>eta</em>, return the refraction vector. 12560 The result is computed by the <a href="#refraction-equation">refraction 12561 equation</a> shown below.</p> 12562</div> 12563<div class="literalblock"> 12564<div class="content"> 12565<pre>The input parameters for the incident vector _I_ and the surface 12566normal _N_ must already be normalized to get the desired results.</pre> 12567</div> 12568</div></div></td> 12569</tr> 12570</tbody> 12571</table> 12572<div class="sect3"> 12573<h4 id="refraction-equation">8.5.1. Refraction Equation</h4> 12574<div class="stemblock"> 12575<div class="content"> 12576\[k = 1.0 - eta * eta * (1.0 - \textbf{dot}(N,I) \cdot \textbf{dot}(N,I))\] 12577</div> 12578</div> 12579<div class="stemblock"> 12580<div class="content"> 12581\[\begin{aligned} 12582result &= 12583 \begin{cases} 12584 genFType(0.0), & k < 0.0 \\ 12585 eta * I - (eta * \textbf{dot}(N,I) + \sqrt { k }) * N, & \textbf{otherwise} 12586 \end{cases} 12587\end{aligned}\] 12588</div> 12589</div> 12590</div> 12591</div> 12592<div class="sect2"> 12593<h3 id="matrix-functions">8.6. Matrix Functions</h3> 12594<div class="paragraph"> 12595<p>For each of the following built-in matrix functions, there is both a 12596single-precision floating-point version, where all arguments and return 12597values are single precision, and a double-precision floating-point version, 12598where all arguments and return values are double precision. 12599Only the single-precision floating-point version is shown.</p> 12600</div> 12601<table class="tableblock frame-all grid-all stretch"> 12602<colgroup> 12603<col style="width: 50%;"> 12604<col style="width: 50%;"> 12605</colgroup> 12606<thead> 12607<tr> 12608<th class="tableblock halign-left valign-top">Syntax</th> 12609<th class="tableblock halign-left valign-top">Description</th> 12610</tr> 12611</thead> 12612<tbody> 12613<tr> 12614<td class="tableblock halign-left valign-top"><p class="tableblock">mat <strong>matrixCompMult</strong>(mat <em>x</em>, mat <em>y</em>)</p></td> 12615<td class="tableblock halign-left valign-top"><p class="tableblock">Multiply matrix <em>x</em> by matrix <em>y</em> component-wise, i.e., result[i][j] 12616 is the scalar product of <em>x</em>[i][j] and <em>y</em>[i][j].<br></p> 12617<p class="tableblock"> Note: to get linear algebraic matrix multiplication, use the multiply 12618 operator (<strong>*</strong>).</p></td> 12619</tr> 12620<tr> 12621<td class="tableblock halign-left valign-top"><p class="tableblock">mat2 <strong>outerProduct</strong>(vec2 <em>c</em>, vec2 <em>r</em>)<br> 12622 mat3 <strong>outerProduct</strong>(vec3 <em>c</em>, vec3 <em>r</em>)<br> 12623 mat4 <strong>outerProduct</strong>(vec4 <em>c</em>, vec4 <em>r</em>)<br> 12624 mat2x3 <strong>outerProduct</strong>(vec3 <em>c</em>, vec2 <em>r</em>)<br> 12625 mat3x2 <strong>outerProduct</strong>(vec2 <em>c</em>, vec3 <em>r</em>)<br> 12626 mat2x4 <strong>outerProduct</strong>(vec4 <em>c</em>, vec2 <em>r</em>)<br> 12627 mat4x2 <strong>outerProduct</strong>(vec2 <em>c</em>, vec4 <em>r</em>)<br> 12628 mat3x4 <strong>outerProduct</strong>(vec4 <em>c</em>, vec3 <em>r</em>)<br> 12629 mat4x3 <strong>outerProduct</strong>(vec3 <em>c</em>, vec4 <em>r</em>)</p></td> 12630<td class="tableblock halign-left valign-top"><p class="tableblock">Treats the first parameter <em>c</em> as a column vector (matrix with one 12631 column) and the second parameter <em>r</em> as a row vector (matrix with one 12632 row) and does a linear algebraic matrix multiply <em>c</em> * <em>r</em>, yielding a 12633 matrix whose number of rows is the number of components in <em>c</em> and 12634 whose number of columns is the number of components in <em>r</em>.</p></td> 12635</tr> 12636<tr> 12637<td class="tableblock halign-left valign-top"><p class="tableblock">mat2 <strong>transpose</strong>(mat2 <em>m</em>)<br> 12638 mat3 <strong>transpose</strong>(mat3 <em>m</em>)<br> 12639 mat4 <strong>transpose</strong>(mat4 <em>m</em>)<br> 12640 mat2x3 <strong>transpose</strong>(mat3x2 <em>m</em>)<br> 12641 mat3x2 <strong>transpose</strong>(mat2x3 <em>m</em>)<br> 12642 mat2x4 <strong>transpose</strong>(mat4x2 <em>m</em>)<br> 12643 mat4x2 <strong>transpose</strong>(mat2x4 <em>m</em>)<br> 12644 mat3x4 <strong>transpose</strong>(mat4x3 <em>m</em>)<br> 12645 mat4x3 <strong>transpose</strong>(mat3x4 <em>m</em>)</p></td> 12646<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a matrix that is the transpose of <em>m</em>. 12647 The input matrix <em>m</em> is not modified.</p></td> 12648</tr> 12649<tr> 12650<td class="tableblock halign-left valign-top"><p class="tableblock">float <strong>determinant</strong>(mat2 <em>m</em>)<br> 12651 float <strong>determinant</strong>(mat3 <em>m</em>)<br> 12652 float <strong>determinant</strong>(mat4 <em>m</em>)</p></td> 12653<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the determinant of <em>m</em>.</p></td> 12654</tr> 12655<tr> 12656<td class="tableblock halign-left valign-top"><p class="tableblock">mat2 <strong>inverse</strong>(mat2 <em>m</em>)<br> 12657 mat3 <strong>inverse</strong>(mat3 <em>m</em>)<br> 12658 mat4 <strong>inverse</strong>(mat4 <em>m</em>)</p></td> 12659<td class="tableblock halign-left valign-top"><p class="tableblock">Returns a matrix that is the inverse of <em>m</em>. 12660 The input matrix <em>m</em> is not modified. 12661 The values in the returned matrix are undefined if <em>m</em> is singular or 12662 poorly-conditioned (nearly singular).</p></td> 12663</tr> 12664</tbody> 12665</table> 12666</div> 12667<div class="sect2"> 12668<h3 id="vector-relational-functions">8.7. Vector Relational Functions</h3> 12669<div class="paragraph"> 12670<p>Relational and equality operators (<strong><</strong>, <strong><=</strong>, <strong>></strong>, <strong>>=</strong>, <strong>==</strong>, <strong>!=</strong>) are 12671defined to operate on scalars and produce scalar Boolean results. 12672For vector results, use the following built-in functions. 12673Below, the following placeholders are used for the listed specific types:</p> 12674</div> 12675<table class="tableblock frame-all grid-all stretch"> 12676<colgroup> 12677<col style="width: 50%;"> 12678<col style="width: 50%;"> 12679</colgroup> 12680<thead> 12681<tr> 12682<th class="tableblock halign-left valign-top">Placeholder</th> 12683<th class="tableblock halign-left valign-top">Specific Types Allowed</th> 12684</tr> 12685</thead> 12686<tbody> 12687<tr> 12688<td class="tableblock halign-left valign-top"><p class="tableblock">bvec</p></td> 12689<td class="tableblock halign-left valign-top"><p class="tableblock">bvec2, bvec3, bvec4</p></td> 12690</tr> 12691<tr> 12692<td class="tableblock halign-left valign-top"><p class="tableblock">ivec</p></td> 12693<td class="tableblock halign-left valign-top"><p class="tableblock">ivec2, ivec3, ivec4</p></td> 12694</tr> 12695<tr> 12696<td class="tableblock halign-left valign-top"><p class="tableblock">uvec</p></td> 12697<td class="tableblock halign-left valign-top"><p class="tableblock">uvec2, uvec3, uvec4</p></td> 12698</tr> 12699<tr> 12700<td class="tableblock halign-left valign-top"><p class="tableblock">vec</p></td> 12701<td class="tableblock halign-left valign-top"><p class="tableblock">vec2, vec3, vec4</p></td> 12702</tr> 12703</tbody> 12704</table> 12705<div class="paragraph"> 12706<p>In all cases, the sizes of all the input and return vectors for any 12707particular call must match.</p> 12708</div> 12709<table class="tableblock frame-all grid-all stretch"> 12710<colgroup> 12711<col style="width: 50%;"> 12712<col style="width: 50%;"> 12713</colgroup> 12714<thead> 12715<tr> 12716<th class="tableblock halign-left valign-top">Syntax</th> 12717<th class="tableblock halign-left valign-top">Description</th> 12718</tr> 12719</thead> 12720<tbody> 12721<tr> 12722<td class="tableblock halign-left valign-top"><p class="tableblock">bvec <strong>lessThan</strong>(vec x, vec y)<br> 12723 bvec <strong>lessThan</strong>(ivec x, ivec y)<br> 12724 bvec <strong>lessThan</strong>(uvec x, uvec y)</p></td> 12725<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the component-wise compare of <span class="eq">x < y</span>.</p></td> 12726</tr> 12727<tr> 12728<td class="tableblock halign-left valign-top"><p class="tableblock">bvec <strong>lessThanEqual</strong>(vec x, vec y)<br> 12729 bvec <strong>lessThanEqual</strong>(ivec x, ivec y)<br> 12730 bvec <strong>lessThanEqual</strong>(uvec x, uvec y)</p></td> 12731<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the component-wise compare of <span class="eq">x ≤ y</span>.</p></td> 12732</tr> 12733<tr> 12734<td class="tableblock halign-left valign-top"><p class="tableblock">bvec <strong>greaterThan</strong>(vec x, vec y)<br> 12735 bvec <strong>greaterThan</strong>(ivec x, ivec y)<br> 12736 bvec <strong>greaterThan</strong>(uvec x, uvec y)</p></td> 12737<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the component-wise compare of <span class="eq">x > y</span>.</p></td> 12738</tr> 12739<tr> 12740<td class="tableblock halign-left valign-top"><p class="tableblock">bvec <strong>greaterThanEqual</strong>(vec x, vec y)<br> 12741 bvec <strong>greaterThanEqual</strong>(ivec x, ivec y)<br> 12742 bvec <strong>greaterThanEqual</strong>(uvec x, uvec y)</p></td> 12743<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the component-wise compare of <span class="eq">x ≥ y</span>.</p></td> 12744</tr> 12745<tr> 12746<td class="tableblock halign-left valign-top"><p class="tableblock">bvec <strong>equal</strong>(vec x, vec y)<br> 12747 bvec <strong>equal</strong>(ivec x, ivec y)<br> 12748 bvec <strong>equal</strong>(uvec x, uvec y)<br> 12749 bvec <strong>equal</strong>(bvec x, bvec y)</p></td> 12750<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the component-wise compare of <span class="eq">x == y</span>.</p></td> 12751</tr> 12752<tr> 12753<td class="tableblock halign-left valign-top"><p class="tableblock">bvec <strong>notEqual</strong>(vec x, vec y)<br> 12754 bvec <strong>notEqual</strong>(ivec x, ivec y)<br> 12755 bvec <strong>notEqual</strong>(uvec x, uvec y)<br> 12756 bvec <strong>notEqual</strong>(bvec x, bvec y)</p></td> 12757<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the component-wise compare of <span class="eq">x ≠ y</span>.</p></td> 12758</tr> 12759<tr> 12760<td class="tableblock halign-left valign-top"><p class="tableblock">bool <strong>any</strong>(bvec x)</p></td> 12761<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <strong>true</strong> if any component of <em>x</em> is <strong>true</strong>.</p></td> 12762</tr> 12763<tr> 12764<td class="tableblock halign-left valign-top"><p class="tableblock">bool <strong>all</strong>(bvec x)</p></td> 12765<td class="tableblock halign-left valign-top"><p class="tableblock">Returns <strong>true</strong> only if all components of <em>x</em> are <strong>true</strong>.</p></td> 12766</tr> 12767<tr> 12768<td class="tableblock halign-left valign-top"><p class="tableblock">bvec <strong>not</strong>(bvec x)</p></td> 12769<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the component-wise logical complement of <em>x</em>.</p></td> 12770</tr> 12771</tbody> 12772</table> 12773</div> 12774<div class="sect2"> 12775<h3 id="integer-functions">8.8. Integer Functions</h3> 12776<div class="paragraph"> 12777<p>These all operate component-wise. 12778The description is per component. 12779The notation [<em>a</em>, <em>b</em>] means the set of bits from bit-number <em>a</em> through 12780bit-number <em>b</em>, inclusive. 12781The lowest-order bit is bit 0. 12782“Bit number” will always refer to counting up from the lowest-order bit as 12783bit 0.</p> 12784</div> 12785<table class="tableblock frame-all grid-all stretch"> 12786<colgroup> 12787<col style="width: 50%;"> 12788<col style="width: 50%;"> 12789</colgroup> 12790<thead> 12791<tr> 12792<th class="tableblock halign-left valign-top">Syntax</th> 12793<th class="tableblock halign-left valign-top">Description</th> 12794</tr> 12795</thead> 12796<tbody> 12797<tr> 12798<td class="tableblock halign-left valign-top"><p class="tableblock">genUType <strong>uaddCarry</strong>(highp genUType <em>x</em>, highp genUType <em>y</em>, out lowp genUType <em>carry</em>)</p></td> 12799<td class="tableblock halign-left valign-top"><p class="tableblock">Adds 32-bit unsigned integers <em>x</em> and <em>y</em>, returning the sum modulo 12800 2<sup>32</sup>. 12801 The value <em>carry</em> is set to zero if the sum was less than 2<sup>32</sup>, or 12802 one otherwise.</p></td> 12803</tr> 12804<tr> 12805<td class="tableblock halign-left valign-top"><p class="tableblock">genUType <strong>usubBorrow</strong>(highp genUType <em>x</em>, highp genUType <em>y</em>, out lowp genUType <em>borrow</em>)</p></td> 12806<td class="tableblock halign-left valign-top"><p class="tableblock">Subtracts the 32-bit unsigned integer <em>y</em> from <em>x</em>, returning the 12807 difference if non-negative, or 2<sup>32</sup> plus the difference otherwise. 12808 The value <em>borrow</em> is set to zero if <span class="eq">x ≥ y</span>, or one 12809 otherwise.</p></td> 12810</tr> 12811<tr> 12812<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>umulExtended</strong>(highp genUType <em>x</em>, highp genUType <em>y</em>, out highp genUType <em>msb</em>, out highp genUType <em>lsb</em>)<br> 12813 void <strong>imulExtended</strong>(highp genIType <em>x</em>, highp genIType <em>y</em>, out highp genIType <em>msb</em>, out highp genIType <em>lsb</em>)</p></td> 12814<td class="tableblock halign-left valign-top"><p class="tableblock">Multiplies 32-bit unsigned or signed integers <em>x</em> and <em>y</em>, producing a 12815 64-bit result. 12816 The 32 least-significant bits are returned in <em>lsb</em>. 12817 The 32 most-significant bits are returned in <em>msb</em>.</p></td> 12818</tr> 12819<tr> 12820<td class="tableblock halign-left valign-top"><p class="tableblock">genIType <strong>bitfieldExtract</strong>(genIType <em>value</em>, int <em>offset</em>, int <em>bits</em>)<br> 12821 genUType <strong>bitfieldExtract</strong>(genUType <em>value</em>, int <em>offset</em>, int <em>bits</em>)</p></td> 12822<td class="tableblock halign-left valign-top"><p class="tableblock">Extracts bits <span class="eq">[offset, offset + bits - 1]</span> from <em>value</em>, 12823 returning them in the least significant bits of the result.<br></p> 12824<p class="tableblock"> For unsigned data types, the most significant bits of the result will 12825 be set to zero. 12826 For signed data types, the most significant bits will be set to the 12827 value of bit <span class="eq">offset + bits - 1</span>.<br></p> 12828<p class="tableblock"> If <em>bits</em> is zero, the result will be zero. 12829 The result will be undefined if <em>offset</em> or <em>bits</em> is negative, or if 12830 the sum of <em>offset</em> and <em>bits</em> is greater than the number of bits used 12831 to store the operand. 12832 Note that for vector versions of <strong>bitfieldExtract</strong>(), a single pair of 12833 <em>offset</em> and <em>bits</em> values is shared for all components.</p></td> 12834</tr> 12835<tr> 12836<td class="tableblock halign-left valign-top"><p class="tableblock">genIType <strong>bitfieldInsert</strong>(genIType <em>base</em>, genIType <em>insert</em>, int <em>offset</em>, int <em>bits</em>)<br> 12837 genUType <strong>bitfieldInsert</strong>(genUType <em>base</em>, genUType <em>insert</em>, int <em>offset</em>, int <em>bits</em>)</p></td> 12838<td class="tableblock halign-left valign-top"><p class="tableblock">Inserts the <em>bits</em> least significant bits of <em>insert</em> into <em>base</em>.</p> 12839<p class="tableblock"> The result will have bits <span class="eq">[offset, offset + bits - 1]</span> taken from 12840 bits <span class="eq">[0, bits - 1]</span> of <em>insert</em>, and all other bits taken 12841 directly from the corresponding bits of <em>base</em>. 12842 If <em>bits</em> is zero, the result will simply be <em>base</em>. 12843 The result will be undefined if <em>offset</em> or <em>bits</em> is negative, or if 12844 the sum of <em>offset</em> and <em>bits</em> is greater than the number of bits used 12845 to store the operand.<br> 12846 Note that for vector versions of <strong>bitfieldInsert</strong>(), a single pair of 12847 <em>offset</em> and <em>bits</em> values is shared for all components.</p></td> 12848</tr> 12849<tr> 12850<td class="tableblock halign-left valign-top"><p class="tableblock">genIType <strong>bitfieldReverse</strong>(highp genIType <em>value</em>)<br> 12851 genUType <strong>bitfieldReverse</strong>(highp genUType <em>value</em>)</p></td> 12852<td class="tableblock halign-left valign-top"><p class="tableblock">Reverses the bits of <em>value</em>. 12853 The bit numbered <em>n</em> of the result will be taken from bit <span class="eq">(bits - 12854 1) - n</span> of <em>value</em>, where <em>bits</em> is the total number of bits used to 12855 represent <em>value</em>.</p></td> 12856</tr> 12857<tr> 12858<td class="tableblock halign-left valign-top"><p class="tableblock">lowp genIType <strong>bitCount</strong>(genIType <em>value</em>)<br> 12859 lowp genIType <strong>bitCount</strong>(genUType <em>value</em>)</p></td> 12860<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the number of one bits in the binary representation of 12861 <em>value</em>.</p></td> 12862</tr> 12863<tr> 12864<td class="tableblock halign-left valign-top"><p class="tableblock">lowp genIType <strong>findLSB</strong>(genIType <em>value</em>)<br> 12865 lowp genIType <strong>findLSB</strong>(genUType <em>value</em>)</p></td> 12866<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the bit number of the least significant one bit in the binary 12867 representation of <em>value</em>. 12868 If <em>value</em> is zero, -1 will be returned.</p></td> 12869</tr> 12870<tr> 12871<td class="tableblock halign-left valign-top"><p class="tableblock">lowp genIType <strong>findMSB</strong>(highp genIType <em>value</em>)<br> 12872 lowp genIType <strong>findMSB</strong>(highp genUType <em>value</em>)</p></td> 12873<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the bit number of the most significant bit in the binary 12874 representation of <em>value</em>.</p> 12875<p class="tableblock"> For positive integers, the result will be the bit number of the most 12876 significant one bit. 12877 For negative integers, the result will be the bit number of the most 12878 significant zero bit. 12879 For a <em>value</em> of zero or negative one, -1 will be returned.</p></td> 12880</tr> 12881</tbody> 12882</table> 12883</div> 12884<div class="sect2"> 12885<h3 id="texture-functions">8.9. Texture Functions</h3> 12886<div class="paragraph"> 12887<p>Texture lookup functions are available in all shading stages. 12888However, level-of-detail is implicitly computed only for fragment shaders. 12889Other shaders operate as though the base level-of-detail were computed as 12890zero. 12891The functions in the table below provide access to textures through 12892texture-combined samplers, as set up through the API. 12893Texture properties such as size, pixel format, number of dimensions, 12894filtering method, number of mipmap levels, depth comparison, and so on are 12895also defined by API calls. 12896Such properties are taken into account as the texture is accessed via the 12897built-in functions defined below.</p> 12898</div> 12899<div class="paragraph"> 12900<p>Texture data can be stored by the GL as single-precision floating-point, 12901unsigned normalized integer, unsigned integer or signed integer data. 12902This is determined by the type of the internal format of the texture.</p> 12903</div> 12904<div class="paragraph"> 12905<p>Texture lookup functions are provided that can return their result as 12906floating-point, unsigned integer or signed integer, depending on the sampler 12907type passed to the lookup function. 12908Care must be taken to use the right sampler type for texture access. 12909The following table lists the supported combinations of sampler types and 12910texture internal formats. 12911Blank entries are unsupported. 12912Doing a texture lookup will return undefined values for unsupported 12913combinations.</p> 12914</div> 12915<div class="paragraph"> 12916<p>For depth/stencil textures, the internal texture format is determined by the 12917component being accessed as set through the API. 12918When the depth/stencil texture mode is set to DEPTH_COMPONENT, the internal 12919format of the depth component should be used. 12920When the depth/stencil texture mode is set to STENCIL_INDEX, the internal format 12921of the stencil component should be used.</p> 12922</div> 12923<table class="tableblock frame-all grid-all stretch"> 12924<colgroup> 12925<col style="width: 25%;"> 12926<col style="width: 25%;"> 12927<col style="width: 25%;"> 12928<col style="width: 25%;"> 12929</colgroup> 12930<thead> 12931<tr> 12932<th class="tableblock halign-left valign-top">Internal Texture Format</th> 12933<th class="tableblock halign-left valign-top">Floating-Point Sampler Types</th> 12934<th class="tableblock halign-left valign-top">Signed Integer Sampler Types</th> 12935<th class="tableblock halign-left valign-top">Unsigned Integer Sampler Types</th> 12936</tr> 12937</thead> 12938<tbody> 12939<tr> 12940<td class="tableblock halign-left valign-top"><p class="tableblock">Floating-point</p></td> 12941<td class="tableblock halign-left valign-top"><p class="tableblock">Supported</p></td> 12942<td class="tableblock halign-left valign-top"></td> 12943<td class="tableblock halign-left valign-top"></td> 12944</tr> 12945<tr> 12946<td class="tableblock halign-left valign-top"><p class="tableblock">Normalized Integer</p></td> 12947<td class="tableblock halign-left valign-top"><p class="tableblock">Supported</p></td> 12948<td class="tableblock halign-left valign-top"></td> 12949<td class="tableblock halign-left valign-top"></td> 12950</tr> 12951<tr> 12952<td class="tableblock halign-left valign-top"><p class="tableblock">Signed Integer</p></td> 12953<td class="tableblock halign-left valign-top"></td> 12954<td class="tableblock halign-left valign-top"><p class="tableblock">Supported</p></td> 12955<td class="tableblock halign-left valign-top"></td> 12956</tr> 12957<tr> 12958<td class="tableblock halign-left valign-top"><p class="tableblock">Unsigned Integer</p></td> 12959<td class="tableblock halign-left valign-top"></td> 12960<td class="tableblock halign-left valign-top"></td> 12961<td class="tableblock halign-left valign-top"><p class="tableblock">Supported</p></td> 12962</tr> 12963</tbody> 12964</table> 12965<div class="paragraph"> 12966<p>If an integer sampler type is used, the result of a texture lookup is an 12967<strong>ivec4</strong>. 12968If an unsigned integer sampler type is used, the result of a texture lookup 12969is a <strong>uvec4</strong>. 12970If a floating-point sampler type is used, the result of a texture lookup is 12971a <strong>vec4</strong>.</p> 12972</div> 12973<div class="paragraph"> 12974<p>In the prototypes below, the <code>g</code> in the return type <code>gvec4</code> is used 12975as a placeholder for either nothing, <code>i</code>, or <code>u</code> making a return type of 12976<strong>vec4</strong>, <strong>ivec4</strong>, or <strong>uvec4</strong>. 12977In these cases, the sampler argument type also starts with <code>g</code>, 12978indicating the same substitution done on the return type; it is either a 12979floating-point, signed integer, or unsigned integer sampler, matching the 12980basic type of the return type, as described above.</p> 12981</div> 12982<div class="paragraph"> 12983<p>For shadow forms (the sampler parameter is a shadow-type), a depth 12984comparison lookup on the depth texture bound to <em>sampler</em> is done as 12985described in section 129868.20 12987“Texture Comparison Modes” of the 12988<a href="#references">OpenGL ES Specification</a>. 12989See the table below for which component specifies <em>D<sub>ref</sub></em>. 12990The texture bound to <em>sampler</em> must be a depth texture, or results are 12991undefined. 12992If a non-shadow texture call is made to a sampler that represents a depth 12993texture with depth comparisons turned on, then results are undefined. 12994If a shadow texture call is made to a sampler that represents a depth 12995texture with depth comparisons turned off, then results are undefined. 12996If a shadow texture call is made to a sampler that does not represent a 12997depth texture, then results are undefined.</p> 12998</div> 12999<div class="paragraph"> 13000<p>In all functions below, the <em>bias</em> parameter is optional for fragment 13001shaders. 13002The <em>bias</em> parameter is not accepted in any other shader stage. 13003For a fragment shader, if <em>bias</em> is present, it is added to the implicit 13004level-of-detail prior to performing the texture access operation. 13005No <em>bias</em> or <em>lod</em> parameters for 13006multisample textures, or texture buffers 13007are supported because mipmaps are not allowed for these types of textures.</p> 13008</div> 13009<div class="paragraph"> 13010<p>The implicit level-of-detail is selected as follows: For a texture that is 13011not mipmapped, the texture is used directly. 13012If it is mipmapped and running in a fragment shader, the level-of-detail 13013computed by the implementation is used to do the texture lookup. 13014If it is mipmapped and running in a non-fragment shader, then the base 13015texture is used.</p> 13016</div> 13017<div class="paragraph"> 13018<p>Some texture functions (non-“<strong>Lod</strong>” and non-“<strong>Grad</strong>” versions) may 13019require implicit derivatives. 13020Implicit derivatives are undefined within non-uniform control flow and for 13021non-fragment shader texture fetches.</p> 13022</div> 13023<div class="paragraph"> 13024<p>For <strong>Cube</strong> forms, the direction of <em>P</em> is used to select which face to do a 130252-dimensional texture lookup in, as described in section 8.13 “Cube Map 13026Texture Selection” of the <a href="#references">OpenGL ES Specification</a>.</p> 13027</div> 13028<div class="paragraph"> 13029<p>For <strong>Array</strong> forms, the array layer used will be</p> 13030</div> 13031<div class="paragraph"> 13032<p>\(\max(0,\min(d-1,\left\lfloor layer + 0.5\right\rfloor))\)</p> 13033</div> 13034<div class="paragraph"> 13035<p>where <em>d</em> is the depth of the texture array and <em>layer</em> comes from the 13036component indicated in the tables below.</p> 13037</div> 13038<div class="sect3"> 13039<h4 id="texture-query-functions">8.9.1. Texture Query Functions</h4> 13040<div class="paragraph"> 13041<p>The <strong>textureSize</strong> functions query the dimensions of a specific texture level 13042for a texture-combined sampler.</p> 13043</div> 13044<table class="tableblock frame-all grid-all stretch"> 13045<colgroup> 13046<col style="width: 50%;"> 13047<col style="width: 50%;"> 13048</colgroup> 13049<thead> 13050<tr> 13051<th class="tableblock halign-left valign-top">Syntax</th> 13052<th class="tableblock halign-left valign-top">Description</th> 13053</tr> 13054</thead> 13055<tbody> 13056<tr> 13057<td class="tableblock halign-left valign-top"><p class="tableblock">highp ivec2 <strong>textureSize</strong>(gsampler2D <em>sampler</em>, int <em>lod</em>)<br> 13058 highp ivec3 <strong>textureSize</strong>(gsampler3D <em>sampler</em>, int <em>lod</em>)<br> 13059 highp ivec2 <strong>textureSize</strong>(gsamplerCube <em>sampler</em>, int <em>lod</em>)<br> 13060 highp ivec2 <strong>textureSize</strong>(sampler2DShadow <em>sampler</em>, int <em>lod</em>)<br> 13061 highp ivec2 <strong>textureSize</strong>(samplerCubeShadow <em>sampler</em>, int <em>lod</em>) 13062 highp ivec3 <strong>textureSize</strong>(gsamplerCubeArray <em>sampler</em>, int <em>lod</em>)<br> 13063 highp ivec3 <strong>textureSize</strong>(samplerCubeArrayShadow <em>sampler</em>, int <em>lod</em>)<br> 13064 highp ivec3 <strong>textureSize</strong>(gsampler2DArray <em>sampler</em>, int <em>lod</em>)<br> 13065 highp ivec3 <strong>textureSize</strong>(sampler2DArrayShadow <em>sampler</em>, int <em>lod</em>)<br> 13066 highp int <strong>textureSize</strong>(gsamplerBuffer <em>sampler</em>)<br> 13067 highp ivec2 <strong>textureSize</strong>(gsampler2DMS <em>sampler</em>)<br> 13068 highp ivec3 <strong>textureSize</strong>(gsampler2DMSArray <em>sampler</em>)</p></td> 13069<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the dimensions of level <em>lod</em> (if present) for the texture 13070 bound to <em>sampler</em>, as described in section 13071 8.11 “Texture Queries” of the <a href="#references">OpenGL ES Specification</a>.<br> 13072 The components in the return value are filled in, in order, with the 13073 width, height, and depth of the texture.</p> 13074<p class="tableblock"> For the array forms, the last component of the return value is the 13075 number of layers in the texture array, or the number of cubes in the 13076 texture cube map array.</p></td> 13077</tr> 13078</tbody> 13079</table> 13080</div> 13081<div class="sect3"> 13082<h4 id="texel-lookup-functions">8.9.2. Texel Lookup Functions</h4> 13083<table class="tableblock frame-all grid-all stretch"> 13084<colgroup> 13085<col style="width: 50%;"> 13086<col style="width: 50%;"> 13087</colgroup> 13088<thead> 13089<tr> 13090<th class="tableblock halign-left valign-top">Syntax</th> 13091<th class="tableblock halign-left valign-top">Description</th> 13092</tr> 13093</thead> 13094<tbody> 13095<tr> 13096<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>texture</strong>(gsampler2D <em>sampler</em>, vec2 <em>P</em> [, float <em>bias</em>] )<br> 13097 gvec4 <strong>texture</strong>(gsampler3D <em>sampler</em>, vec3 <em>P</em> [, float <em>bias</em>] )<br> 13098 gvec4 <strong>texture</strong>(gsamplerCube <em>sampler</em>, vec3 <em>P</em>[, float <em>bias</em>] )<br> 13099 float <strong>texture</strong>(sampler2DShadow <em>sampler</em>, vec3 <em>P</em> [, float <em>bias</em>])<br> 13100 float <strong>texture</strong>(samplerCubeShadow <em>sampler</em>, vec4 <em>P</em> [, float <em>bias</em>] )<br> 13101 gvec4 <strong>texture</strong>(gsampler2DArray <em>sampler</em>, vec3 <em>P</em> [, float <em>bias</em>] )<br> 13102 gvec4 <strong>texture</strong>(gsamplerCubeArray <em>sampler</em>, vec4 <em>P</em> [, float <em>bias</em>] )<br> 13103 float <strong>texture</strong>(sampler2DArrayShadow <em>sampler</em>, vec4 <em>P</em>)<br> 13104 float <strong>texture</strong>(samplerCubeArrayShadow <em>sampler</em>, vec4 <em>P</em>, float <em>compare</em>)</p></td> 13105<td class="tableblock halign-left valign-top"><p class="tableblock">Use the texture coordinate <em>P</em> to do a texture lookup in the texture 13106 currently bound to <em>sampler</em>.</p> 13107<p class="tableblock"> For shadow forms: When <em>compare</em> is present, it is used as <em>D<sub>ref</sub></em> 13108 and the array layer comes from the last component of <em>P</em>. 13109 When <em>compare</em> is not present, the last component of <em>P</em> is used as 13110 <em>D<sub>ref</sub></em> and the array layer comes from the second to last component 13111 of <em>P</em>.</p> 13112<p class="tableblock"> For non-shadow forms: the array layer comes from the last component of 13113 <em>P</em>.</p></td> 13114</tr> 13115<tr> 13116<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureProj</strong>(gsampler2D <em>sampler</em>, vec3 <em>P</em> [, float <em>bias</em>] )<br> 13117 gvec4 <strong>textureProj</strong>(gsampler2D <em>sampler</em>, vec4 <em>P</em> [, float <em>bias</em>] )<br> 13118 gvec4 <strong>textureProj</strong>(gsampler3D <em>sampler</em>, vec4 <em>P</em> [, float <em>bias</em>] )<br> 13119 float <strong>textureProj</strong>(sampler2DShadow <em>sampler</em>, vec4 <em>P</em> [, float <em>bias</em>] )<br></p></td> 13120<td class="tableblock halign-left valign-top"><p class="tableblock">Do a texture lookup with projection. 13121 The texture coordinates consumed from <em>P</em>, not including the last 13122 component of <em>P</em>, are divided by the last component of <em>P</em> to 13123 form projected coordinates <em>P'</em>. 13124 The resulting third component of <em>P</em> in the shadow forms is used as 13125 <em>D<sub>ref</sub></em>. 13126 The third component of <em>P</em> is ignored when <em>sampler</em> has type 13127 <strong>gsampler2D</strong> and <em>P</em> has type <strong>vec4</strong>. 13128 After these values are computed, texture lookup proceeds as in 13129 <strong>texture</strong>.</p></td> 13130</tr> 13131<tr> 13132<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureLod</strong>(gsampler2D <em>sampler</em>, vec2 <em>P</em>, float <em>lod</em>)<br> 13133 gvec4 <strong>textureLod</strong>(gsampler3D <em>sampler</em>, vec3 <em>P</em>, float <em>lod</em>)<br> 13134 gvec4 <strong>textureLod</strong>(gsamplerCube <em>sampler</em>, vec3 <em>P</em>, float <em>lod</em>)<br> 13135 float <strong>textureLod</strong>(sampler2DShadow <em>sampler</em>, vec3 <em>P</em>, float <em>lod</em>)<br> 13136 gvec4 <strong>textureLod</strong>(gsampler2DArray <em>sampler</em>, vec3 <em>P</em>, float <em>lod</em>)<br> 13137 gvec4 <strong>textureLod</strong>(gsamplerCubeArray <em>sampler</em>, vec4 <em>P</em>, float <em>lod</em>)</p></td> 13138<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 13139<p>Do a texture lookup as in <strong>texture</strong> but with explicit level-of-detail; 13140 <em>lod</em> specifies <span class="eq">λ<sub>base</sub>]</span> and sets the partial derivatives 13141 as follows:<br> 13142 (See section 8.14 “Texture Minification” and equations 8.4-8.6 of 13143 the <a href="#references">OpenGL ES Specification</a>.)<br> 13144 <br> 13145 <span class="eq">∂u / ∂x = 13146 ∂v / ∂x = 13147 ∂w / ∂x = 0</span> 13148 <br> 13149 <span class="eq">∂u / ∂y = 13150 ∂v / ∂y = 13151 ∂w / ∂y = 0</span></p> 13152</div></div></td> 13153</tr> 13154<tr> 13155<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureOffset</strong>(gsampler2D <em>sampler</em>, vec2 <em>P</em>, ivec2 <em>offset</em> [, float <em>bias</em>] )<br> 13156 gvec4 <strong>textureOffset</strong>(gsampler3D <em>sampler</em>, vec3 <em>P</em>, ivec3 <em>offset</em> [, float <em>bias</em>] )<br> 13157 float <strong>textureOffset</strong>(sampler2DShadow <em>sampler</em>, vec3 <em>P</em>, ivec2 <em>offset</em> [, float <em>bias</em>] )<br> 13158 gvec4 <strong>textureOffset</strong>(gsampler2DArray <em>sampler</em>, vec3 <em>P</em>, ivec2 <em>offset</em> [, float <em>bias</em>] )<br></p></td> 13159<td class="tableblock halign-left valign-top"><p class="tableblock">Do a texture lookup as in <strong>texture</strong> but with <em>offset</em> added to the 13160 <span class="eq">(u,v,w)</span> texel coordinates before looking up each texel. 13161 The offset value must be a constant expression. 13162 A limited range of offset values are supported; the minimum and 13163 maximum offset values are implementation-dependent and given by 13164 <em>gl_MinProgramTexelOffset</em> and <em>gl_MaxProgramTexelOffset</em>, 13165 respectively.</p> 13166<p class="tableblock"> Note that <em>offset</em> does not apply to the layer coordinate for texture 13167 arrays. 13168 This is explained in detail in section 8.14.2 “Coordinate Wrapping 13169 and Texel Selection” of the <a href="#references">OpenGL ES Specification</a>, where <em>offset</em> 13170 is <span class="eq">(δ<sub>u</sub>, δ<sub>v</sub>, δ<sub>w</sub>)</span>.<br> 13171 Note that texel offsets are also not supported for cube maps.</p></td> 13172</tr> 13173<tr> 13174<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>texelFetch</strong>(gsampler2D <em>sampler</em>, ivec2 <em>P</em>, int <em>lod</em>)<br> 13175 gvec4 <strong>texelFetch</strong>(gsampler3D <em>sampler</em>, ivec3 <em>P</em>, int <em>lod</em>) 13176 gvec4 <strong>texelFetch</strong>(gsampler2DArray <em>sampler</em>, ivec3 <em>P</em>, int <em>lod</em>)<br> 13177 gvec4 <strong>texelFetch</strong>(gsamplerBuffer <em>sampler</em>, int <em>P</em>)<br> 13178 gvec4 <strong>texelFetch</strong>(gsampler2DMS <em>sampler</em>, ivec2 <em>P</em>, int <em>sample</em>)<br> 13179 gvec4 <strong>texelFetch</strong>(gsampler2DMSArray <em>sampler</em>, ivec3 <em>P</em>, int <em>sample</em>)</p></td> 13180<td class="tableblock halign-left valign-top"><p class="tableblock">Use integer texture coordinate <em>P</em> to lookup a single texel from 13181 <em>sampler</em>. 13182 The array layer comes from the last component of <em>P</em> for the array 13183 forms. 13184 The level-of-detail <em>lod</em> (if present) is as described in sections 13185 11.1.3.2 “Texel Fetches” and 8.14.1 “Scale Factor and Level of 13186 Detail” of the <a href="#references">OpenGL ES Specification</a>.</p></td> 13187</tr> 13188<tr> 13189<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>texelFetchOffset</strong>(gsampler2D <em>sampler</em>, ivec2 <em>P</em>, int <em>lod</em>, ivec2 <em>offset</em>)<br> 13190 gvec4 <strong>texelFetchOffset</strong>(gsampler3D <em>sampler</em>, ivec3 <em>P</em>, int <em>lod</em>, ivec3 <em>offset</em>)<br> 13191 gvec4 <strong>texelFetchOffset</strong>(gsampler2DArray <em>sampler</em>, ivec3 <em>P</em>, int <em>lod</em>, ivec2 <em>offset</em>)</p></td> 13192<td class="tableblock halign-left valign-top"><p class="tableblock">Fetch a single texel as in <strong>texelFetch</strong>, offset by <em>offset</em> as 13193 described in <strong>textureOffset</strong>.</p></td> 13194</tr> 13195<tr> 13196<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureProjOffset</strong>(gsampler2D <em>sampler</em>, vec3 <em>P</em>, ivec2 <em>offset</em> [, float <em>bias</em>] )<br> 13197 gvec4 <strong>textureProjOffset</strong>(gsampler2D <em>sampler</em>, vec4 <em>P</em>, ivec2 <em>offset</em> [, float <em>bias</em>] )<br> 13198 gvec4 <strong>textureProjOffset</strong>(gsampler3D <em>sampler</em>, vec4 <em>P</em>, ivec3 <em>offset</em> [, float <em>bias</em>] )<br> 13199 float <strong>textureProjOffset</strong>(sampler2DShadow <em>sampler</em>, vec4 <em>P</em>, ivec2 <em>offset</em> [, float <em>bias</em>] )</p></td> 13200<td class="tableblock halign-left valign-top"><p class="tableblock">Do a projective texture lookup as described in <strong>textureProj</strong>, offset 13201 by <em>offset</em> as described in <strong>textureOffset</strong>.</p></td> 13202</tr> 13203<tr> 13204<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureLodOffset</strong>(gsampler2D <em>sampler</em>, vec2 <em>P</em>, float <em>lod</em>, ivec2 <em>offset</em>)<br> 13205 gvec4 <strong>textureLodOffset</strong>(gsampler3D <em>sampler</em>, vec3 <em>P</em>, float <em>lod</em>, ivec3 <em>offset</em>)<br> 13206 float <strong>textureLodOffset</strong>(sampler2DShadow <em>sampler</em>, vec3 <em>P</em>, float <em>lod</em>, ivec2 <em>offset</em>)<br> 13207 gvec4 <strong>textureLodOffset</strong>(gsampler2DArray <em>sampler</em>, vec3 <em>P</em>, float <em>lod</em>, ivec2 <em>offset</em>)<br></p></td> 13208<td class="tableblock halign-left valign-top"><p class="tableblock">Do an offset texture lookup with explicit level-of-detail. 13209 See <strong>textureLod</strong> and <strong>textureOffset</strong>.</p></td> 13210</tr> 13211<tr> 13212<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureProjLod</strong>(gsampler2D <em>sampler</em>, vec3 <em>P</em>, float <em>lod</em>)<br> 13213 gvec4 <strong>textureProjLod</strong>(gsampler2D <em>sampler</em>, vec4 <em>P</em>, float <em>lod</em>)<br> 13214 gvec4 <strong>textureProjLod</strong>(gsampler3D <em>sampler</em>, vec4 <em>P</em>, float <em>lod</em>)<br> 13215 float <strong>textureProjLod</strong>(sampler2DShadow <em>sampler</em>, vec4 <em>P</em>, float <em>lod</em>)</p></td> 13216<td class="tableblock halign-left valign-top"><p class="tableblock">Do a projective texture lookup with explicit level-of-detail. 13217 See <strong>textureProj</strong> and <strong>textureLod</strong>.</p></td> 13218</tr> 13219<tr> 13220<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureProjLodOffset</strong>(gsampler2D <em>sampler</em>, vec3 <em>P</em>, float <em>lod</em>, ivec2 <em>offset</em>)<br> 13221 gvec4 <strong>textureProjLodOffset</strong>(gsampler2D <em>sampler</em>, vec4 <em>P</em>, float <em>lod</em>, ivec2 <em>offset</em>)<br> 13222 gvec4 <strong>textureProjLodOffset</strong>(gsampler3D <em>sampler</em>, vec4 <em>P</em>, float <em>lod</em>, ivec3 <em>offset</em>)<br> 13223 float <strong>textureProjLodOffset</strong>(sampler2DShadow <em>sampler</em>, vec4 <em>P</em>, float <em>lod</em>, ivec2 <em>offset</em>)</p></td> 13224<td class="tableblock halign-left valign-top"><p class="tableblock">Do an offset projective texture lookup with explicit level-of-detail. 13225 See <strong>textureProj</strong>, <strong>textureLod</strong>, and <strong>textureOffset</strong>.</p></td> 13226</tr> 13227<tr> 13228<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureGrad</strong>(gsampler2D <em>sampler</em>, vec2 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>)<br> 13229 gvec4 <strong>textureGrad</strong>(gsampler3D <em>sampler</em>, <em>P</em>, vec3 <em>dPdx</em>, vec3 <em>dPdy</em>)<br> 13230 gvec4 <strong>textureGrad</strong>(gsamplerCube <em>sampler</em>, vec3 <em>P</em>, vec3 <em>dPdx</em>, vec3 <em>dPdy</em>)<br> 13231 float <strong>textureGrad</strong>(sampler2DShadow <em>sampler</em>, vec3 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>)<br> 13232 float <strong>textureGrad</strong>(samplerCubeShadow <em>sampler</em>, vec4 <em>P</em>, vec3 <em>dPdx</em>, vec3 <em>dPdy</em>)<br> 13233 float <strong>textureGrad</strong>(sampler2DArrayShadow <em>sampler</em>, vec4 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>)<br> 13234 gvec4 <strong>textureGrad</strong>(gsamplerCubeArray <em>sampler</em>, vec4 <em>P</em>, vec3 <em>dPdx</em>, vec3 <em>dPdy</em>)<br></p></td> 13235<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 13236<p>Do a texture lookup as in <strong>texture</strong> but with <a href="#explicit-gradients">explicit gradients</a> as shown below. 13237 The partial derivatives of <em>P</em> are with respect to window <em>x</em> and 13238 window <em>y</em>. 13239 For the cube version, the partial derivatives of <em>P</em> are assumed to be 13240 in the coordinate system used before texture coordinates are projected 13241 onto the appropriate cube face.</p> 13242</div></div></td> 13243</tr> 13244<tr> 13245<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureGradOffset</strong>(gsampler2D <em>sampler</em>, vec2 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>, ivec2 <em>offset</em>)<br> 13246 gvec4 <strong>textureGradOffset</strong>(gsampler3D <em>sampler</em>, vec3 <em>P</em>, vec3 <em>dPdx</em>, vec3 <em>dPdy</em>, ivec3 <em>offset</em>)<br> 13247 float <strong>textureGradOffset</strong>(sampler2DShadow <em>sampler</em>, vec3 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>, ivec2 <em>offset</em>)<br> 13248 gvec4 <strong>textureGradOffset</strong>(gsampler2DArray <em>sampler</em>, vec3 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>, ivec2 <em>offset</em>)<br> 13249 float <strong>textureGradOffset</strong>(sampler2DArrayShadow <em>sampler</em>, vec4 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>, ivec2 <em>offset</em>)<br></p></td> 13250<td class="tableblock halign-left valign-top"><p class="tableblock">Do a texture lookup with both explicit gradient and offset, as 13251 described in <strong>textureGrad</strong> and <strong>textureOffset</strong>.</p></td> 13252</tr> 13253<tr> 13254<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureProjGrad</strong>(gsampler2D <em>sampler</em>, vec3 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>)<br> 13255 gvec4 <strong>textureProjGrad</strong>(gsampler2D <em>sampler</em>, vec4 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>)<br> 13256 gvec4 <strong>textureProjGrad</strong>(gsampler3D <em>sampler</em>, vec4 <em>P</em>, vec3 <em>dPdx</em>, vec3 <em>dPdy</em>)<br> 13257 float <strong>textureProjGrad</strong>(sampler2DShadow <em>sampler</em>, vec4 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>)</p></td> 13258<td class="tableblock halign-left valign-top"><p class="tableblock">Do a texture lookup both projectively, as described in <strong>textureProj</strong>, 13259 and with explicit gradient as described in <strong>textureGrad</strong>. 13260 The partial derivatives <em>dPdx</em> and <em>dPdy</em> are assumed to be already 13261 projected.</p></td> 13262</tr> 13263<tr> 13264<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureProjGradOffset</strong>(gsampler2D <em>sampler</em>, vec3 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>, ivec2 <em>offset</em>)<br> 13265 gvec4 <strong>textureProjGradOffset</strong>(gsampler2D <em>sampler</em>, vec4 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>, ivec2 <em>offset</em>)<br> 13266 gvec4 <strong>textureProjGradOffset</strong>(gsampler3D <em>sampler</em>, vec4 <em>P</em>, vec3 <em>dPdx</em>, vec3 <em>dPdy</em>, ivec3 <em>offset</em>)<br> 13267 float <strong>textureProjGradOffset</strong>(sampler2DShadow <em>sampler</em>, vec4 <em>P</em>, vec2 <em>dPdx</em>, vec2 <em>dPdy</em>, ivec2 <em>offset</em>)</p></td> 13268<td class="tableblock halign-left valign-top"><p class="tableblock">Do a texture lookup projectively and with explicit gradient as 13269 described in <strong>textureProjGrad</strong>, as well as with offset, as described in 13270 <strong>textureOffset</strong>.</p></td> 13271</tr> 13272</tbody> 13273</table> 13274</div> 13275<div class="sect3"> 13276<h4 id="explicit-gradients">8.9.3. Explicit Gradients</h4> 13277<div class="paragraph"> 13278<p>In the <strong>textureGrad</strong> functions described above, explicit gradients control 13279texture lookups as follows:</p> 13280</div> 13281<div class="stemblock"> 13282<div class="content"> 13283\[\begin{aligned} 13284 \frac{\partial{s}}{\partial{x}} & = \frac{\partial{P.s}}{\partial{x}} \\[0.8em] 13285 \frac{\partial{s}}{\partial{y}} & = \frac{\partial{P.s}}{\partial{y}} \\[0.8em] 13286 \frac{\partial{t}}{\partial{x}} & = \frac{\partial{P.t}}{\partial{x}} \\[0.8em] 13287 \frac{\partial{t}}{\partial{y}} & = \frac{\partial{P.t}}{\partial{y}} \\[0.8em] 13288 \frac{\partial{r}}{\partial{x}} & = 13289 \begin{cases} 13290 0.0, & \text{for 2D} \\[0.8em] 13291 \frac{\partial{P.p}}{\partial{x}}, & \text{cube, other} 13292 \end{cases} \\[2.5em] 13293 \frac{\partial{r}}{\partial{y}} & = 13294 \begin{cases} 13295 0.0, & \text{for 2D} \\[0.8em] 13296 \frac{\partial{P.p}}{\partial{y}}, & \text{cube, other} 13297 \end{cases} 13298\end{aligned}\] 13299</div> 13300</div> 13301</div> 13302<div class="sect3"> 13303<h4 id="texture-gather-functions">8.9.4. Texture Gather Functions</h4> 13304<div class="paragraph"> 13305<p>The texture gather functions take components of a single floating-point 13306vector operand as a texture coordinate, determine a set of four texels to 13307sample from the base level-of-detail of the specified texture image, and 13308return one component from each texel in a four-component result vector.</p> 13309</div> 13310<div class="paragraph"> 13311<p>When performing a texture gather operation, the minification and 13312magnification filters are ignored, and the rules for LINEAR filtering in the 13313<a href="#references">OpenGL ES Specification</a> are applied to the base level of the texture image 13314to identify the four texels <em>i<sub>0</sub> j<sub>1</sub></em>, <em>i<sub>1</sub> j<sub>1</sub></em>, <em>i<sub>1</sub> j<sub>0</sub></em>, and <em>i<sub>0</sub> 13315j<sub>0</sub></em>. 13316The texels are then converted to texture base colors (<em>R<sub>s</sub></em>, <em>G<sub>s</sub></em>, 13317<em>B<sub>s</sub></em>, <em>A<sub>s</sub></em>) according to table 15.1, followed by application of the 13318texture swizzle as described in section 15.2.1 “Texture Access” of the 13319<a href="#references">OpenGL ES Specification</a>. 13320A four-component vector is assembled by taking the selected component from 13321each of the post-swizzled texture source colors in the order (<em>i<sub>0</sub> j<sub>1</sub></em>, 13322<em>i<sub>1</sub> j<sub>1</sub></em>, <em>i<sub>1</sub> j<sub>0</sub></em>, <em>i<sub>0</sub> j<sub>0</sub></em>).</p> 13323</div> 13324<div class="paragraph"> 13325<p>The selected component is identified by the optional <em>comp</em> argument, where 13326the values zero, one, two, and three identify the <em>R<sub>s</sub></em>, <em>G<sub>s</sub></em>, <em>B<sub>s</sub></em>, or 13327<em>A<sub>s</sub></em> component, respectively. 13328If <em>comp</em> is omitted, it is treated as identifying the <em>R<sub>s</sub></em> component.</p> 13329</div> 13330<div class="paragraph"> 13331<p>Incomplete textures (see section 8.16 “Texture Completeness” of the 13332<a href="#references">OpenGL ES Specification</a>) return a texture source color of (0,0,0,1) for all 13333four source texels.</p> 13334</div> 13335<div class="paragraph"> 13336<p>For texture gather functions using a texture-combined shadow sampler type, 13337each of the four 13338texel lookups perform a depth comparison against the depth reference value 13339passed in (<em>refZ</em>), and returns the result of that comparison in the 13340appropriate component of the result vector.</p> 13341</div> 13342<div class="paragraph"> 13343<p>As with other texture lookup functions, the results of a texture gather are 13344undefined for shadow samplers if the texture referenced is not a depth 13345texture or has depth comparisons disabled; or for non-shadow samplers if the 13346texture referenced is a depth texture with depth comparisons enabled.</p> 13347</div> 13348<div class="paragraph"> 13349<p>The <strong>textureGatherOffset</strong> built-in functions from the OpenGL ES Shading Language return a vector 13350derived from sampling four texels in the image array of level <em>level<sub>base</sub></em>. 13351For each of the four texel offsets specified by the <em>offsets</em> argument, the 13352rules for the LINEAR minification filter are applied to identify a 2 × 133532 texel footprint, from which the single texel T<sub>i0j0</sub> is selected. 13354A four-component vector is then assembled by taking a single component from 13355each of the four T<sub>i0j0</sub> texels in the same manner as for the 13356<strong>textureGather</strong> function.</p> 13357</div> 13358<table class="tableblock frame-all grid-all stretch"> 13359<colgroup> 13360<col style="width: 50%;"> 13361<col style="width: 50%;"> 13362</colgroup> 13363<thead> 13364<tr> 13365<th class="tableblock halign-left valign-top">Syntax</th> 13366<th class="tableblock halign-left valign-top">Description</th> 13367</tr> 13368</thead> 13369<tbody> 13370<tr> 13371<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureGather</strong>(gsampler2D <em>sampler</em>, vec2 <em>P</em> [, int <em>comp</em>])<br> 13372 gvec4 <strong>textureGather</strong>(gsampler2DArray <em>sampler</em>, vec3 <em>P</em> [, int <em>comp</em>])<br> 13373 gvec4 <strong>textureGather</strong>(gsamplerCube <em>sampler</em>, vec3 <em>P</em> [, int <em>comp</em>])<br> 13374 gvec4 <strong>textureGather</strong>(gsamplerCubeArray <em>sampler</em>, vec4 <em>P</em>[, int <em>comp</em>])<br> 13375 vec4 <strong>textureGather</strong>(sampler2DShadow <em>sampler</em>, vec2 <em>P</em>, float <em>refZ</em>)<br> 13376 vec4 <strong>textureGather</strong>(sampler2DArrayShadow <em>sampler</em>, vec3 <em>P</em>, float <em>refZ</em>)<br> 13377 vec4 <strong>textureGather</strong>(samplerCubeShadow <em>sampler</em>, vec3 <em>P</em>, float <em>refZ</em>)<br> 13378 vec4 <strong>textureGather</strong>(samplerCubeArrayShadow <em>sampler</em>, vec4 <em>P</em>, float <em>refZ</em>)<br></p></td> 13379<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 13380<p>Returns the value<br></p> 13381</div> 13382<div class="openblock"> 13383<div class="content"> 13384<div class="listingblock"> 13385<div class="content"> 13386<pre class="CodeRay highlight"><code data-lang="c++">vec4(Sample_i0_j1(P, base).comp, 13387 Sample_i1_j1(P, base).comp, 13388 Sample_i1_j0(P, base).comp, 13389 Sample_i0_j0(P, base).comp)</code></pre> 13390</div> 13391</div> 13392<div class="paragraph"> 13393<p>If specified, the value of <em>comp</em> must be a constant integer expression with 13394a value of 0, 1, 2, or 3, identifying the <em>x</em>, <em>y</em>, <em>z</em>, or <em>w</em> 13395post-swizzled component of the four-component vector lookup result for each 13396texel, respectively. 13397If <em>comp</em> is not specified, it is treated as 0, selecting the <em>x</em> component 13398of each texel to generate the result.</p> 13399</div> 13400</div> 13401</div></div></td> 13402</tr> 13403<tr> 13404<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureGatherOffset</strong>(gsampler2D <em>sampler</em>, vec2 <em>P</em>, ivec2 <em>offset</em>, [ int <em>comp</em>])<br> 13405 gvec4 <strong>textureGatherOffset</strong>(gsampler2DArray <em>sampler</em>, vec3 <em>P</em>, ivec2 <em>offset</em> [ int <em>comp</em>])<br> 13406 vec4 <strong>textureGatherOffset</strong>(sampler2DShadow <em>sampler</em>, vec2 <em>P</em>, float <em>refZ</em>, ivec2 <em>offset</em>)<br> 13407 vec4 <strong>textureGatherOffset</strong>(sampler2DArrayShadow <em>sampler</em>, vec3 <em>P</em>, float <em>refZ</em>, ivec2 <em>offset</em>)<br></p></td> 13408<td class="tableblock halign-left valign-top"><p class="tableblock">Perform a texture gather operation as in <strong>textureGather</strong> by <em>offset</em> 13409 as described in <strong>textureOffset</strong> except that the <em>offset</em> can be 13410 variable (non constant) and the implementation-dependent minimum and 13411 maximum offset values are given by MIN_PROGRAM_TEXTURE_GATHER_OFFSET 13412 and MAX_PROGRAM_TEXTURE_GATHER_OFFSET, respectively.</p></td> 13413</tr> 13414<tr> 13415<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>textureGatherOffsets</strong>(gsampler2D <em>sampler</em>, vec2 <em>P</em>, ivec2 <em>offsets</em>[4] [, int <em>comp</em>])<br> 13416 gvec4 <strong>textureGatherOffsets</strong>(gsampler2DArray <em>sampler</em>, vec3 <em>P</em>, ivec2 <em>offsets</em>[4] [, int <em>comp</em>])<br> 13417 vec4 <strong>textureGatherOffsets</strong>(sampler2DShadow <em>sampler</em>, vec2 <em>P</em>, float <em>refZ</em>, ivec2 <em>offsets</em>[4])<br> 13418 vec4 <strong>textureGatherOffsets</strong>(sampler2DArrayShadow <em>sampler</em>, vec3 <em>P</em>, float <em>refZ</em>, ivec2 <em>offsets</em>[4])<br></p></td> 13419<td class="tableblock halign-left valign-top"><p class="tableblock">Operate identically to <strong>textureGatherOffset</strong> except that <em>offsets</em> is 13420 used to determine the location of the four texels to sample. 13421 Each of the four texels is obtained by applying the corresponding 13422 offset in <em>offsets</em> as a (<em>u</em>, <em>v</em>) coordinate offset to <em>P</em>, 13423 identifying the four-texel LINEAR footprint, and then selecting the 13424 texel <em>i<sub>0</sub> j<sub>0</sub></em> of that footprint. 13425 The specified values in <em>offsets</em> must be constant integral 13426 expressions.</p></td> 13427</tr> 13428</tbody> 13429</table> 13430</div> 13431</div> 13432<div class="sect2"> 13433<h3 id="atomic-counter-functions">8.10. Atomic Counter Functions</h3> 13434<div class="paragraph"> 13435<p>The atomic-counter operations in this section operate atomically with 13436respect to each other. 13437They are atomic for any single counter, meaning any of these operations on a 13438specific counter in one shader instantiation will be indivisible by any of 13439these operations on the same counter from another shader instantiation. 13440There is no guarantee that these operations are atomic with respect to other 13441forms of access to the counter or that they are serialized when applied to 13442separate counters. 13443Such cases would require additional use of fences, barriers, or other forms 13444of synchronization, if atomicity or serialization is desired.</p> 13445</div> 13446<div class="paragraph"> 13447<p>The underlying counter is a 32-bit unsigned integer. 13448The result of operations will wrap to [0, 2<sup>32</sup>-1].</p> 13449</div> 13450<table class="tableblock frame-all grid-all stretch"> 13451<colgroup> 13452<col style="width: 50%;"> 13453<col style="width: 50%;"> 13454</colgroup> 13455<thead> 13456<tr> 13457<th class="tableblock halign-left valign-top">Syntax</th> 13458<th class="tableblock halign-left valign-top">Description</th> 13459</tr> 13460</thead> 13461<tbody> 13462<tr> 13463<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicCounterIncrement</strong>(atomic_uint <em>c</em>)</p></td> 13464<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 13465<p>Atomically<br></p> 13466</div> 13467<div class="openblock"> 13468<div class="content"> 13469<div class="olist arabic"> 13470<ol class="arabic"> 13471<li> 13472<p>increments the counter for <em>c</em>, and</p> 13473</li> 13474<li> 13475<p>returns its value prior to the increment operation.</p> 13476</li> 13477</ol> 13478</div> 13479<div class="paragraph"> 13480<p>These two steps are done atomically with respect to the atomic counter 13481functions in this table.</p> 13482</div> 13483</div> 13484</div></div></td> 13485</tr> 13486<tr> 13487<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicCounterDecrement</strong>(atomic_uint <em>c</em>)</p></td> 13488<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 13489<p>Atomically<br></p> 13490</div> 13491<div class="openblock"> 13492<div class="content"> 13493<div class="olist arabic"> 13494<ol class="arabic"> 13495<li> 13496<p>decrements the counter for <em>c</em>, and</p> 13497</li> 13498<li> 13499<p>returns the value resulting from the decrement operation.</p> 13500</li> 13501</ol> 13502</div> 13503<div class="paragraph"> 13504<p>These two steps are done atomically with respect to the atomic counter 13505functions in this table.</p> 13506</div> 13507</div> 13508</div></div></td> 13509</tr> 13510<tr> 13511<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicCounter</strong>(atomic_uint <em>c</em>)</p></td> 13512<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the counter value for <em>c</em>.</p></td> 13513</tr> 13514</tbody> 13515</table> 13516</div> 13517<div class="sect2"> 13518<h3 id="atomic-memory-functions">8.11. Atomic Memory Functions</h3> 13519<div class="paragraph"> 13520<p>Atomic memory functions perform atomic operations on an individual signed or 13521unsigned integer stored in buffer object or shared variable storage. 13522All of the atomic memory operations read a value from memory, compute a new 13523value using one of the operations described below, write the new value to 13524memory, and return the original value read. 13525The contents of the memory being updated by the atomic operation are 13526guaranteed not to be modified by any other assignment or atomic memory 13527function in any shader invocation between the time the original value is 13528read and the time the new value is written.</p> 13529</div> 13530<div class="paragraph"> 13531<p>Atomic memory functions are supported only for a limited set of variables. 13532A shader will fail to compile if the value passed to the <em>mem</em> argument of 13533an atomic memory function does not correspond to a buffer or shared 13534variable. 13535It is acceptable to pass an element of an array or a single component of a 13536vector to the <em>mem</em> argument of an atomic memory function, as long as the 13537underlying array or vector is a buffer or shared variable.</p> 13538</div> 13539<div class="paragraph"> 13540<p>All the built-in functions in this section accept arguments with 13541combinations of <strong>restrict</strong>, <strong>coherent</strong>, and <strong>volatile</strong> memory qualification, 13542despite not having them listed in the prototypes. 13543The atomic operation will operate as required by the calling argument’s 13544memory qualification, not by the built-in function’s formal parameter memory 13545qualification.</p> 13546</div> 13547<table class="tableblock frame-all grid-all stretch"> 13548<colgroup> 13549<col style="width: 50%;"> 13550<col style="width: 50%;"> 13551</colgroup> 13552<thead> 13553<tr> 13554<th class="tableblock halign-left valign-top">Syntax</th> 13555<th class="tableblock halign-left valign-top">Description</th> 13556</tr> 13557</thead> 13558<tbody> 13559<tr> 13560<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicAdd</strong>(inout uint <em>mem</em>, uint <em>data</em>)<br> 13561 int <strong>atomicAdd</strong>(inout int <em>mem</em>, int <em>data</em>)</p></td> 13562<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by adding the value of <em>data</em> to the contents 13563 <em>mem</em>.</p></td> 13564</tr> 13565<tr> 13566<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicMin</strong>(inout uint <em>mem</em>, uint <em>data</em>)<br> 13567 int <strong>atomicMin</strong>(inout int <em>mem</em>, int <em>data</em>)</p></td> 13568<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by taking the minimum of the value of <em>data</em> and 13569 the contents of <em>mem</em>.</p></td> 13570</tr> 13571<tr> 13572<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicMax</strong>(inout uint <em>mem</em>, uint <em>data</em>)<br> 13573 int <strong>atomicMax</strong>(inout int <em>mem</em>, int <em>data</em>)</p></td> 13574<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by taking the maximum of the value of <em>data</em> and 13575 the contents of <em>mem</em>.</p></td> 13576</tr> 13577<tr> 13578<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicAnd</strong>(inout uint <em>mem</em>, uint <em>data</em>)<br> 13579 int <strong>atomicAnd</strong>(inout int <em>mem</em>, int <em>data</em>)</p></td> 13580<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by performing a bit-wise AND of the value of 13581 <em>data</em> and the contents of <em>mem</em>.</p></td> 13582</tr> 13583<tr> 13584<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicOr</strong>(inout uint <em>mem</em>, uint <em>data</em>)<br> 13585 int <strong>atomicOr</strong>(inout int <em>mem</em>, int <em>data</em>)</p></td> 13586<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by performing a bit-wise OR of the value of 13587 <em>data</em> and the contents of <em>mem</em>.</p></td> 13588</tr> 13589<tr> 13590<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicXor</strong>(inout uint <em>mem</em>, uint <em>data</em>)<br> 13591 int <strong>atomicXor</strong>(inout int <em>mem</em>, int <em>data</em>)</p></td> 13592<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by performing a bit-wise EXCLUSIVE OR of the 13593 value of <em>data</em> and the contents of <em>mem</em>.</p></td> 13594</tr> 13595<tr> 13596<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicExchange</strong>(inout uint <em>mem</em>, uint <em>data</em>)<br> 13597 int <strong>atomicExchange</strong>(inout int <em>mem</em>, int <em>data</em>)</p></td> 13598<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by simply copying the value of <em>data</em>.</p></td> 13599</tr> 13600<tr> 13601<td class="tableblock halign-left valign-top"><p class="tableblock">uint <strong>atomicCompSwap</strong>(inout uint <em>mem</em>, uint <em>compare</em>, uint <em>data</em>)<br> 13602 int <strong>atomicCompSwap</strong>(inout int <em>mem</em>, int <em>compare</em>, int <em>data</em>)</p></td> 13603<td class="tableblock halign-left valign-top"><p class="tableblock">Compares the value of <em>compare</em> and the contents of <em>mem</em>. 13604 If the values are equal, the new value is given by <em>data</em>; otherwise, 13605 it is taken from the original contents of <em>mem</em>.</p></td> 13606</tr> 13607</tbody> 13608</table> 13609</div> 13610<div class="sect2"> 13611<h3 id="image-functions">8.12. Image Functions</h3> 13612<div class="paragraph"> 13613<p>Variables using one of the image basic types may be used by the built-in 13614shader image memory functions defined in this section to read and write 13615individual texels of a texture. 13616Each image variable references an image unit, which has a texture image 13617attached.</p> 13618</div> 13619<div class="paragraph"> 13620<p>When image memory functions below access memory, an individual texel in the 13621image is identified using an (<em>i</em>), (<em>i, j</em>), or (<em>i, j, k</em>) coordinate 13622corresponding to the values of <em>P</em>. 13623The coordinates 13624are used to select an individual texel in the manner described in section 136258.22 13626“Texture Image Loads and Stores” of the <a href="#references">OpenGL ES Specification</a>.</p> 13627</div> 13628<div class="paragraph"> 13629<p>Loads and stores support float, integer, and unsigned integer types. 13630The data types below starting <code>gimage</code> serve as placeholders meaning 13631types starting either “<strong>image</strong>”, “<strong>iimage</strong>”, or “<strong>uimage</strong>” in the same 13632way as "<strong>gvec</strong>" or "<strong>gsampler</strong>" in earlier sections.</p> 13633</div> 13634<div class="paragraph"> 13635<p>The <em>IMAGE_PARAMS</em> in the prototypes below is a placeholder representing 1363618 13637separate functions, each for a different type of image variable. 13638The <em>IMAGE_PARAMS</em> placeholder is replaced by one of the following parameter 13639lists:</p> 13640</div> 13641<div class="dlist"> 13642<dl> 13643<dt class="hdlist1"></dt> 13644<dd> 13645<p>gimage2D <em>image</em>, ivec2 <em>P</em></p> 13646</dd> 13647<dt class="hdlist1"></dt> 13648<dd> 13649<p>gimage3D <em>image</em>, ivec3 <em>P</em></p> 13650</dd> 13651<dt class="hdlist1"></dt> 13652<dd> 13653<p>gimageCube <em>image</em>, ivec3 <em>P</em></p> 13654</dd> 13655<dt class="hdlist1"></dt> 13656<dd> 13657<p>gimageBuffer <em>image</em>, int <em>P</em></p> 13658</dd> 13659<dt class="hdlist1"></dt> 13660<dd> 13661<p>gimage2DArray <em>image</em>, ivec3 <em>P</em></p> 13662</dd> 13663<dt class="hdlist1"></dt> 13664<dd> 13665<p>gimageCubeArray <em>image</em>, ivec3 <em>P</em></p> 13666</dd> 13667</dl> 13668</div> 13669<div class="paragraph"> 13670<p>where each of the lines represents one of three different image variable 13671types, and <em>image</em>, 13672<em>P</em> 13673specify the individual texel to operate on. 13674The method for identifying the individual texel operated on from <em>image</em>, 13675<em>P</em>, 13676and the method for reading and writing the texel are specified in section 136778.22 13678“Texture Image Loads and Stores” of the <a href="#references">OpenGL ES Specification</a>.</p> 13679</div> 13680<div class="paragraph"> 13681<p>The atomic functions perform operations on individual texels or samples of 13682an image variable. 13683Atomic memory operations read a value from the selected texel, compute a new 13684value using one of the operations described below, write the new value to 13685the selected texel, and return the original value read. 13686The contents of the texel being updated by the atomic operation are 13687guaranteed not to be modified by any other image store or atomic function 13688between the time the original value is read and the time the new value is 13689written.</p> 13690</div> 13691<div class="paragraph"> 13692<p>Atomic memory operations are supported on only a subset of all image 13693variable types; <em>image</em> must be either:</p> 13694</div> 13695<div class="ulist"> 13696<ul> 13697<li> 13698<p>a signed integer image variable (type starts “<strong>iimage</strong>”) and a format 13699qualifier of <strong>r32i</strong>, used with a <em>data</em> argument of type <strong>int</strong>, or</p> 13700</li> 13701<li> 13702<p>an unsigned integer image variable (type starts “<strong>uimage</strong>”) and a 13703format qualifier of <strong>r32ui</strong>, used with a <em>data</em> argument of type <strong>uint</strong>, 13704or</p> 13705</li> 13706<li> 13707<p>a float image variable (type starts “<strong>image</strong>”) and a format qualifier 13708of <strong>r32f</strong>, used with a <em>data</em> argument of type <strong>float</strong> 13709(<strong>imageAtomicExchange</strong> only).</p> 13710</li> 13711</ul> 13712</div> 13713<div class="paragraph"> 13714<p>All the built-in functions in this section accept arguments with 13715combinations of <strong>restrict</strong>, <strong>coherent</strong>, and <strong>volatile</strong> memory qualification, 13716despite not having them listed in the prototypes. 13717The image operation will operate as required by the calling argument’s 13718memory qualification, not by the built-in function’s formal parameter memory 13719qualification.</p> 13720</div> 13721<table class="tableblock frame-all grid-all stretch"> 13722<colgroup> 13723<col style="width: 50%;"> 13724<col style="width: 50%;"> 13725</colgroup> 13726<thead> 13727<tr> 13728<th class="tableblock halign-left valign-top">Syntax</th> 13729<th class="tableblock halign-left valign-top">Description</th> 13730</tr> 13731</thead> 13732<tbody> 13733<tr> 13734<td class="tableblock halign-left valign-top"><p class="tableblock">highp ivec2 <strong>imageSize</strong>(readonly writeonly gimage2D <em>image</em>)<br> 13735 highp ivec3 <strong>imageSize</strong>(readonly writeonly gimage3D <em>image</em>)<br> 13736 highp ivec2 <strong>imageSize</strong>(readonly writeonly gimageCube <em>image</em>)<br> 13737 highp ivec3 <strong>imageSize</strong>(readonly writeonly gimageCubeArray <em>image</em>)<br> 13738 highp ivec3 <strong>imageSize</strong>(readonly writeonly gimage2DArray <em>image</em>)<br> 13739 highp int <strong>imageSize</strong>(readonly writeonly gimageBuffer <em>image</em>)</p></td> 13740<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the dimensions of the image or images bound to <em>image</em>. 13741 For arrayed images, the last component of the return value will hold 13742 the size of the array. 13743 Cube images only return the dimensions of one face, and the number of 13744 cubes in the cube map array, if arrayed.<br> 13745 Note: The qualification <strong>readonly writeonly</strong> accepts a variable 13746 qualified with <strong>readonly</strong>, <strong>writeonly</strong>, both, or neither. 13747 It means the formal argument will be used for neither reading nor 13748 writing to the underlying memory.</p></td> 13749</tr> 13750<tr> 13751<td class="tableblock halign-left valign-top"><p class="tableblock">highp gvec4 <strong>imageLoad</strong>(readonly <em>IMAGE_PARAMS</em>)</p></td> 13752<td class="tableblock halign-left valign-top"><p class="tableblock">Loads the texel at the coordinate <em>P</em> from the image unit <em>image</em> (in 13753 <em>IMAGE_PARAMS</em>). 13754 When <em>image</em> and <em>P</em> 13755 identify a valid texel, the bits used to represent the selected texel in 13756 memory are converted to a <strong>vec4</strong>, <strong>ivec4</strong>, or <strong>uvec4</strong> in the manner 13757 described in section 137588.23 13759 “Texture Image Loads and Stores” of the 13760 <a href="#references">OpenGL ES Specification</a> and returned.</p></td> 13761</tr> 13762<tr> 13763<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>imageStore</strong>(writeonly <em>IMAGE_PARAMS</em>, gvec4 <em>data</em>)</p></td> 13764<td class="tableblock halign-left valign-top"><p class="tableblock">Stores <em>data</em> into the texel at the coordinate <em>P</em> from the image 13765 specified by <em>image</em>. 13766 When <em>image</em> and <em>P</em> 13767 identify a valid texel, the bits used to represent <em>data</em> are converted 13768 to the format of the image unit in the manner described in section 137698.23 13770 “Texture Image Loads and Stores” of the <a href="#references">OpenGL ES Specification</a> 13771 and stored to the specified texel.</p></td> 13772</tr> 13773<tr> 13774<td class="tableblock halign-left valign-top"><p class="tableblock">highp uint <strong>imageAtomicAdd</strong>(<em>IMAGE_PARAMS</em>, uint <em>data</em>)<br> 13775 highp int <strong>imageAtomicAdd</strong>(<em>IMAGE_PARAMS</em>, int <em>data</em>)</p></td> 13776<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by adding the value of <em>data</em> to the contents of 13777 the selected texel.</p></td> 13778</tr> 13779<tr> 13780<td class="tableblock halign-left valign-top"><p class="tableblock">highp uint <strong>imageAtomicMin</strong>(<em>IMAGE_PARAMS</em>, uint <em>data</em>)<br> 13781 highp int <strong>imageAtomicMin</strong>(<em>IMAGE_PARAMS</em>, int <em>data</em>)</p></td> 13782<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by taking the minimum of the value of <em>data</em> and 13783 the contents of the selected texel.</p></td> 13784</tr> 13785<tr> 13786<td class="tableblock halign-left valign-top"><p class="tableblock">highp uint <strong>imageAtomicMax</strong>(<em>IMAGE_PARAMS</em>, uint <em>data</em>)<br> 13787 highp int <strong>imageAtomicMax</strong>(<em>IMAGE_PARAMS</em>, int <em>data</em>)</p></td> 13788<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by taking the maximum of the value <em>data</em> and the 13789 contents of the selected texel.</p></td> 13790</tr> 13791<tr> 13792<td class="tableblock halign-left valign-top"><p class="tableblock">highp uint <strong>imageAtomicAnd</strong>(<em>IMAGE_PARAMS</em>, uint <em>data</em>)<br> 13793 highp int <strong>imageAtomicAnd</strong>(<em>IMAGE_PARAMS</em>, int <em>data</em>)</p></td> 13794<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by performing a bit-wise AND of the value of 13795 <em>data</em> and the contents of the selected texel.</p></td> 13796</tr> 13797<tr> 13798<td class="tableblock halign-left valign-top"><p class="tableblock">highp uint <strong>imageAtomicOr</strong>(<em>IMAGE_PARAMS</em>, uint <em>data</em>)<br> 13799 highp int <strong>imageAtomicOr</strong>(<em>IMAGE_PARAMS</em>, int <em>data</em>)</p></td> 13800<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by performing a bit-wise OR of the value of 13801 <em>data</em> and the contents of the selected texel.</p></td> 13802</tr> 13803<tr> 13804<td class="tableblock halign-left valign-top"><p class="tableblock">highp uint <strong>imageAtomicXor</strong>(<em>IMAGE_PARAMS</em>, uint <em>data</em>)<br> 13805 highp int <strong>imageAtomicXor</strong>(<em>IMAGE_PARAMS</em>, int <em>data</em>)</p></td> 13806<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by performing a bit-wise EXCLUSIVE OR of the 13807 value of <em>data</em> and the contents of the selected texel.</p></td> 13808</tr> 13809<tr> 13810<td class="tableblock halign-left valign-top"><p class="tableblock">highp uint <strong>imageAtomicExchange</strong>(<em>IMAGE_PARAMS</em>, uint <em>data</em>)<br> 13811 highp int <strong>imageAtomicExchange</strong>(<em>IMAGE_PARAMS</em>, int <em>data</em>)<br> 13812 highp float <strong>imageAtomicExchange</strong>(<em>IMAGE_PARAMS</em>, float <em>data</em>)</p></td> 13813<td class="tableblock halign-left valign-top"><p class="tableblock">Computes a new value by simply copying the value of <em>data</em>.</p></td> 13814</tr> 13815<tr> 13816<td class="tableblock halign-left valign-top"><p class="tableblock">highp uint <strong>imageAtomicCompSwap</strong>(<em>IMAGE_PARAMS</em>, uint <em>compare</em>, uint <em>data</em>)<br> 13817 highp int <strong>imageAtomicCompSwap</strong>(<em>IMAGE_PARAMS</em>, int <em>compare</em>, int <em>data</em>)</p></td> 13818<td class="tableblock halign-left valign-top"><p class="tableblock">Compares the value of <em>compare</em> and the contents of the selected 13819 texel. 13820 If the values are equal, the new value is given by <em>data</em>; otherwise, 13821 it is taken from the original value loaded from the texel.</p></td> 13822</tr> 13823</tbody> 13824</table> 13825</div> 13826<div class="sect2"> 13827<h3 id="geometry-shader-functions">8.13. Geometry Shader Functions</h3> 13828<div class="paragraph"> 13829<p>These functions are only available in geometry shaders. 13830They are described in more depth following the table.</p> 13831</div> 13832<table class="tableblock frame-all grid-all stretch"> 13833<colgroup> 13834<col style="width: 50%;"> 13835<col style="width: 50%;"> 13836</colgroup> 13837<thead> 13838<tr> 13839<th class="tableblock halign-left valign-top">Syntax</th> 13840<th class="tableblock halign-left valign-top">Description</th> 13841</tr> 13842</thead> 13843<tbody> 13844<tr> 13845<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>EmitVertex</strong>()<br></p></td> 13846<td class="tableblock halign-left valign-top"><p class="tableblock">Emits the current values of output variables to the current output 13847 primitive. 13848 On return from this call, the values of output variables are 13849 undefined.</p></td> 13850</tr> 13851<tr> 13852<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>EndPrimitive</strong>()</p></td> 13853<td class="tableblock halign-left valign-top"><p class="tableblock">Completes the current output primitive and starts a new one. 13854 No vertex is emitted.</p></td> 13855</tr> 13856</tbody> 13857</table> 13858<div class="paragraph"> 13859<p>The function <strong>EmitVertex</strong>() specifies that a vertex is completed. 13860A vertex is added to the current output primitive using the current values 13861of all built-in and user-defined output variables. 13862The values of all output variables are undefined after a call to 13863<strong>EmitVertex</strong>(). 13864If a geometry shader invocation has emitted more vertices than permitted by 13865the output layout qualifier <strong>max_vertices</strong>, the results of calling 13866<strong>EmitVertex</strong>() are undefined.</p> 13867</div> 13868<div class="paragraph"> 13869<p>The function <strong>EndPrimitive</strong>() specifies that the current output primitive is 13870completed and a new output primitive (of the same type) will be started by 13871any subsequent <strong>EmitVertex</strong>(). 13872This function does not emit a vertex. 13873If the output layout is declared to be <strong>points</strong>, calling <strong>EndPrimitive</strong>() is 13874optional.</p> 13875</div> 13876<div class="paragraph"> 13877<p>A geometry shader starts with an output primitive containing no vertices. 13878When a geometry shader terminates, the current output primitive is 13879automatically completed. 13880It is not necessary to call <strong>EndPrimitive</strong>() if the geometry shader writes 13881only a single primitive.</p> 13882</div> 13883</div> 13884<div class="sect2"> 13885<h3 id="fragment-processing-functions">8.14. Fragment Processing Functions</h3> 13886<div class="paragraph"> 13887<p>Fragment processing functions are only available in fragment shaders.</p> 13888</div> 13889<div class="sect3"> 13890<h4 id="derivative-functions">8.14.1. Derivative Functions</h4> 13891<div class="paragraph"> 13892<p>Derivatives may be computationally expensive and/or numerically unstable. 13893Therefore, an implementation may approximate the true derivatives 13894by using a fast but not entirely accurate derivative computation. 13895Derivatives are undefined within non-uniform control flow.</p> 13896</div> 13897<div class="paragraph"> 13898<p>The expected behavior of a derivative is specified using forward/backward 13899differencing.</p> 13900</div> 13901<div class="paragraph"> 13902<p>Forward differencing:</p> 13903</div> 13904<div class="paragraph"> 13905<p>\(F(x+dx) - F(x) \sim dFdx(x) \cdot dx (1a)\)</p> 13906</div> 13907<div class="paragraph"> 13908<p>\(dFdx(x) \sim \frac{F(x+dx) - F(x)}{dx} (1b)\)</p> 13909</div> 13910<div class="paragraph"> 13911<p>Backward differencing:</p> 13912</div> 13913<div class="paragraph"> 13914<p>\(F(x-dx) - F(x) \sim -dFdx(x) \cdot dx (2a)\)</p> 13915</div> 13916<div class="paragraph"> 13917<p>\(dFdx(x) \sim \frac{F(x) - F(x-dx)}{dx} (2b)\)</p> 13918</div> 13919<div class="paragraph"> 13920<p>With single-sample rasterization, \(dx \leq 1.0\) in equations 1b 13921and 2b. 13922For multisample rasterization, \(dx < 2.0\) in equations 1b and 2b.</p> 13923</div> 13924<div class="paragraph"> 13925<p>\(dFdy\) is approximated similarly, with <em>y</em> replacing <em>x</em>.</p> 13926</div> 13927<div class="paragraph"> 13928<p>An implementation may use the above or other methods to perform 13929the calculation, subject to the following conditions:</p> 13930</div> 13931<div class="olist arabic"> 13932<ol class="arabic"> 13933<li> 13934<p>The method may use piecewise linear approximations. 13935Such linear approximations imply that higher order derivatives, 13936<strong>dFdx</strong>(<strong>dFdx</strong>(<em>x</em>)) and above, are undefined.</p> 13937</li> 13938<li> 13939<p>The method may assume that the function evaluated is continuous. 13940Therefore derivatives within the body of a non-uniform conditional are 13941undefined.</p> 13942</li> 13943<li> 13944<p>The method may differ per fragment, subject to the constraint that the 13945method may vary by window coordinates, not screen coordinates. 13946The invariance requirement described in section 13.2 “Invariance” of 13947the <a href="#references">OpenGL ES Specification</a>, is relaxed for derivative calculations, 13948because the method may be a function of fragment location.</p> 13949</li> 13950</ol> 13951</div> 13952<div class="paragraph"> 13953<p>Other properties that are desirable, but not required, are:</p> 13954</div> 13955<div class="olist arabic"> 13956<ol class="arabic"> 13957<li> 13958<p>Functions should be evaluated within the interior of a primitive 13959(interpolated, not extrapolated).</p> 13960</li> 13961<li> 13962<p>Functions for <strong>dFdx</strong> should be evaluated while holding <em>y</em> constant. 13963Functions for <strong>dFdy</strong> should be evaluated while holding <em>x</em> constant. 13964However, mixed higher order derivatives, like <strong>dFdx</strong>(<strong>dFdy</strong>(<em>y</em>)) and 13965<strong>dFdy</strong>(<strong>dFdx</strong>(<em>x</em>)) are undefined.</p> 13966</li> 13967<li> 13968<p>Derivatives of constant arguments should be 0.</p> 13969</li> 13970</ol> 13971</div> 13972<div class="paragraph"> 13973<p>In some implementations, varying degrees of derivative accuracy may be 13974obtained by providing GL hints (see section 19.1 “Hints” of the 13975<a href="#references">OpenGL ES Specification</a>), allowing a user to make an image quality versus 13976speed trade off.</p> 13977</div> 13978<table class="tableblock frame-all grid-all stretch"> 13979<colgroup> 13980<col style="width: 50%;"> 13981<col style="width: 50%;"> 13982</colgroup> 13983<thead> 13984<tr> 13985<th class="tableblock halign-left valign-top">Syntax</th> 13986<th class="tableblock halign-left valign-top">Description</th> 13987</tr> 13988</thead> 13989<tbody> 13990<tr> 13991<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>dFdx</strong>(genFType <em>p</em>)</p></td> 13992<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the derivative in x using local differencing for the input 13993 argument <em>p</em>.</p></td> 13994</tr> 13995<tr> 13996<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>dFdy</strong>(genFType <em>p</em>)</p></td> 13997<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the derivative in y using local differencing for the input 13998 argument <em>p</em>.<br> 13999 <br> 14000 These two functions are commonly used to estimate the filter width used 14001 to anti-alias procedural textures. We are assuming that the expression 14002 is being evaluated in parallel on a SIMD array so that at any given 14003 point in time the value of the function is known at the grid points 14004 represented by the SIMD array. Local differencing between SIMD array 14005 elements can therefore be used to derive <strong>dFdx</strong>, <strong>dFdy</strong>, etc.</p></td> 14006</tr> 14007<tr> 14008<td class="tableblock halign-left valign-top"><p class="tableblock">genFType <strong>fwidth</strong>(genFType <em>p</em>)</p></td> 14009<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the sum of the absolute derivative in x and y using local 14010 differencing for the input argument <em>p</em>, i.e., <strong>abs</strong>(<strong>dFdx</strong>(<em>p</em>)) 14011 + <strong>abs</strong>(<strong>dFdy</strong>(<em>p</em>));</p></td> 14012</tr> 14013</tbody> 14014</table> 14015</div> 14016<div class="sect3"> 14017<h4 id="interpolation-functions">8.14.2. Interpolation Functions</h4> 14018<div class="paragraph"> 14019<p>Built-in interpolation functions are available to compute an interpolated 14020value of a fragment shader input variable at a shader-specified (<em>x</em>, <em>y</em>) 14021location. 14022A separate (<em>x</em>, <em>y</em>) location may be used for each invocation of the 14023built-in function, and those locations may differ from the default (<em>x</em>, 14024<em>y</em>) location used to produce the default value of the input. 14025For the <strong>interpolateAt*</strong> functions, the call will return a precision 14026qualification matching the precision of the <em>interpolant</em> argument to the 14027function call.</p> 14028</div> 14029<div class="paragraph"> 14030<p>For all of the interpolation functions, <em>interpolant</em> must be an l-value 14031from an <strong>in</strong> declaration; 14032this can be either a variable, or an array element. 14033Component selection operators (e.g. <strong>.xy</strong>) may not be used when specifying <em>interpolant</em>.</p> 14034</div> 14035<div class="paragraph"> 14036<p>If <em>interpolant</em> is declared with the <strong>flat</strong> qualifier, the interpolated 14037value will have the same value everywhere for a single primitive, so the 14038location used for interpolation has no effect and the functions just return 14039that same value. 14040If <em>interpolant</em> is declared with the <strong>centroid</strong> qualifier, the value 14041returned by <strong>interpolateAtSample</strong>() and <strong>interpolateAtOffset</strong>() will be 14042evaluated at the specified location, ignoring the location normally used 14043with the <strong>centroid</strong> qualifier.</p> 14044</div> 14045<table class="tableblock frame-all grid-all stretch"> 14046<colgroup> 14047<col style="width: 50%;"> 14048<col style="width: 50%;"> 14049</colgroup> 14050<thead> 14051<tr> 14052<th class="tableblock halign-left valign-top">Syntax</th> 14053<th class="tableblock halign-left valign-top">Description</th> 14054</tr> 14055</thead> 14056<tbody> 14057<tr> 14058<td class="tableblock halign-left valign-top"><p class="tableblock">float <strong>interpolateAtCentroid</strong>(float <em>interpolant</em>)<br> 14059 vec2 <strong>interpolateAtCentroid</strong>(vec2 <em>interpolant</em>)<br> 14060 vec3 <strong>interpolateAtCentroid</strong>(vec3 <em>interpolant</em>)<br> 14061 vec4 <strong>interpolateAtCentroid</strong>(vec4 <em>interpolant</em>)</p></td> 14062<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the value of the input <em>interpolant</em> sampled at a location 14063 inside both the pixel and the primitive being processed. 14064 The value obtained would be the same value assigned to the input 14065 variable if declared with the <strong>centroid</strong> qualifier.</p></td> 14066</tr> 14067<tr> 14068<td class="tableblock halign-left valign-top"><p class="tableblock">float <strong>interpolateAtSample</strong>(float <em>interpolant</em>, int <em>sample</em>)<br> 14069 vec2 <strong>interpolateAtSample</strong>(vec2 <em>interpolant</em>, int <em>sample</em>)<br> 14070 vec3 <strong>interpolateAtSample</strong>(vec3 <em>interpolant</em>, int <em>sample</em>)<br> 14071 vec4 <strong>interpolateAtSample</strong>(vec4 <em>interpolant</em>, int <em>sample</em>)</p></td> 14072<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the value of the input <em>interpolant</em> variable at the location 14073 of sample number <em>sample</em>. 14074 If multisample buffers are not available, the input variable will be 14075 evaluated at the center of the pixel. 14076 If sample <em>sample</em> does not exist, the position used to interpolate 14077 the input variable is undefined.</p></td> 14078</tr> 14079<tr> 14080<td class="tableblock halign-left valign-top"><p class="tableblock">float <strong>interpolateAtOffset</strong>(float <em>interpolant</em>, vec2 offset)<br> 14081 vec2 <strong>interpolateAtOffset</strong>(vec2 <em>interpolant</em>, vec2 offset)<br> 14082 vec3 <strong>interpolateAtOffset</strong>(vec3 <em>interpolant</em>, vec2 offset)<br> 14083 vec4 <strong>interpolateAtOffset</strong>(vec4 <em>interpolant</em>, vec2 offset)</p></td> 14084<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the value of the input <em>interpolant</em> variable sampled at an 14085 offset from the center of the pixel specified by <em>offset</em>. 14086 The two floating-point components of <em>offset</em>, give the offset in 14087 pixels in the <em>x</em> and <em>y</em> directions, respectively.<br> 14088 An offset of (0, 0) identifies the center of the pixel. 14089 The range and granularity of offsets supported by this function is 14090 implementation-dependent.</p></td> 14091</tr> 14092</tbody> 14093</table> 14094</div> 14095</div> 14096<div class="sect2"> 14097<h3 id="shader-invocation-control-functions">8.15. Shader Invocation Control Functions</h3> 14098<div class="paragraph"> 14099<p>The shader invocation control function is only available in tessellation 14100control and compute shaders. 14101It is used to control the relative execution order of multiple shader 14102invocations used to process a patch (in the case of tessellation control 14103shaders) or a workgroup (in the case of compute shaders), which are 14104otherwise executed with an undefined relative order.</p> 14105</div> 14106<table class="tableblock frame-all grid-all stretch"> 14107<colgroup> 14108<col style="width: 50%;"> 14109<col style="width: 50%;"> 14110</colgroup> 14111<thead> 14112<tr> 14113<th class="tableblock halign-left valign-top">Syntax</th> 14114<th class="tableblock halign-left valign-top">Description</th> 14115</tr> 14116</thead> 14117<tbody> 14118<tr> 14119<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>barrier</strong>()</p></td> 14120<td class="tableblock halign-left valign-top"><p class="tableblock">For any given static instance of <strong>barrier</strong>(), all tessellation control 14121 shader invocations for a single input patch must enter it before any 14122 will be allowed to continue beyond it, or all compute shader 14123 invocations for a single workgroup must enter it before any will 14124 continue beyond it.</p></td> 14125</tr> 14126</tbody> 14127</table> 14128<div class="paragraph"> 14129<p>The function <strong>barrier</strong>() provides a partially defined order of execution 14130between shader invocations. 14131The ensures that, for some types of memory accesses, values written by one 14132invocation prior to a given static instance of <strong>barrier</strong>() can be safely read 14133by other invocations after their call to the same static instance <strong>barrier</strong>(). 14134Because invocations may execute in an undefined order between these barrier 14135calls, the values of a per-vertex or per-patch output variable for tessellation 14136control shaders, or the values of <strong>shared</strong> variables for compute shaders will be 14137undefined in a number of cases enumerated in 14138“<a href="#output-variables">Output Variables</a>” (for tessellation control shaders) 14139and “<a href="#shared-variables">Shared Variables</a>” (for compute shaders).</p> 14140</div> 14141<div class="paragraph"> 14142<p>For tessellation control shaders, the <strong>barrier</strong>() function may only be 14143placed inside the function <strong>main</strong>() of the shader and may not be called 14144within any control flow. 14145Barriers are also disallowed after a return statement in the function 14146<strong>main</strong>(). 14147Any such misplaced barriers result in a compile-time error.</p> 14148</div> 14149<div class="paragraph"> 14150<p>A <strong>barrier</strong>() affects control flow but only synchronizes memory accesses 14151to <strong>shared</strong> variables and tessellation control output variables. 14152For other memory accesses, it does not ensure that values written by one invocation 14153prior to a given static instance of <strong>barrier</strong>() can be safely read by other 14154invocations after their call to the same static instance of <strong>barrier</strong>(). 14155To achieve this requires the use of both <strong>barrier</strong>() and a memory barrier.</p> 14156</div> 14157<div class="paragraph"> 14158<p>For compute shaders, the <strong>barrier</strong>() function may be placed within control 14159flow, but that control flow must be uniform control flow. 14160That is, all the controlling expressions that lead to execution of the 14161barrier must be dynamically uniform expressions. 14162This ensures that if any shader invocation enters a conditional statement, 14163then all invocations will enter it. 14164While compilers are encouraged to give warnings if they can detect this 14165might not happen, compilers cannot completely determine this. 14166Hence, it is the author’s responsibility to ensure <strong>barrier</strong>() only exists 14167inside uniform control flow. 14168Otherwise, some shader invocations will stall indefinitely, waiting for a 14169barrier that is never reached by other invocations.</p> 14170</div> 14171</div> 14172<div class="sect2"> 14173<h3 id="shader-memory-control-functions">8.16. Shader Memory Control Functions</h3> 14174<div class="paragraph"> 14175<p>Within a single shader invocation, the visibility and order of writes made 14176by that invocation are well-defined. 14177However, the relative order of reads and writes to a single shared memory 14178address from multiple separate shader invocations is largely undefined. 14179Additionally, the order of accesses to multiple memory addresses performed 14180by a single shader invocation, as observed by other shader invocations, is 14181also undefined.</p> 14182</div> 14183<div class="paragraph"> 14184<p>The following built-in functions can be used to control the ordering of 14185reads and writes:</p> 14186</div> 14187<table class="tableblock frame-all grid-all stretch"> 14188<colgroup> 14189<col style="width: 50%;"> 14190<col style="width: 50%;"> 14191</colgroup> 14192<thead> 14193<tr> 14194<th class="tableblock halign-left valign-top">Syntax</th> 14195<th class="tableblock halign-left valign-top">Description</th> 14196</tr> 14197</thead> 14198<tbody> 14199<tr> 14200<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>memoryBarrier</strong>()</p></td> 14201<td class="tableblock halign-left valign-top"><p class="tableblock">Control the ordering of memory transactions issued by a single shader 14202 invocation.</p></td> 14203</tr> 14204<tr> 14205<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>memoryBarrierAtomicCounter</strong>()</p></td> 14206<td class="tableblock halign-left valign-top"><p class="tableblock">Control the ordering of accesses to atomic-counter variables issued by 14207 a single shader invocation.</p></td> 14208</tr> 14209<tr> 14210<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>memoryBarrierBuffer</strong>()</p></td> 14211<td class="tableblock halign-left valign-top"><p class="tableblock">Control the ordering of memory transactions to buffer variables issued 14212 within a single shader invocation.</p></td> 14213</tr> 14214<tr> 14215<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>memoryBarrierShared</strong>()</p></td> 14216<td class="tableblock halign-left valign-top"><p class="tableblock">Control the ordering of memory transactions to shared variables issued 14217 within a single shader invocation, as viewed by other invocations in 14218 the same workgroup.<br> 14219 Only available in compute shaders.</p></td> 14220</tr> 14221<tr> 14222<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>memoryBarrierImage</strong>()</p></td> 14223<td class="tableblock halign-left valign-top"><p class="tableblock">Control the ordering of memory transactions to images issued within a 14224 single shader invocation.</p></td> 14225</tr> 14226<tr> 14227<td class="tableblock halign-left valign-top"><p class="tableblock">void <strong>groupMemoryBarrier</strong>()</p></td> 14228<td class="tableblock halign-left valign-top"><p class="tableblock">Control the ordering of all memory transactions issued within a single 14229 shader invocation, as viewed by other invocations in the same workgroup.<br> 14230 Only available in compute shaders.</p></td> 14231</tr> 14232</tbody> 14233</table> 14234<div class="paragraph"> 14235<p>The memory barrier built-in functions can be used to order reads and writes 14236to variables stored in memory accessible to other shader invocations. 14237When called, these functions will wait for the completion of all reads and 14238writes previously performed by the caller that access selected variable 14239types, and then return with no other effect. 14240The built-in functions <strong>memoryBarrierAtomicCounter</strong>(), 14241<strong>memoryBarrierBuffer</strong>(), <strong>memoryBarrierImage</strong>(), and <strong>memoryBarrierShared</strong>() 14242wait for the completion of accesses to atomic counter, buffer, image, and 14243shared variables, respectively. 14244The built-in functions <strong>memoryBarrier</strong>() and <strong>groupMemoryBarrier</strong>() wait for 14245the completion of accesses to all of the above variable types. 14246The functions <strong>memoryBarrierShared</strong>() and <strong>groupMemoryBarrier</strong>() are 14247available only in compute shaders; the other functions are available in all 14248shader types.</p> 14249</div> 14250<div class="paragraph"> 14251<p>When these functions return, the effects of any memory stores performed 14252using coherent variables prior to the call will be visible to any 14253future<sup>1</sup> coherent access to the same memory performed by any other shader 14254invocation. 14255In particular, the values written this way in one shader stage are 14256guaranteed to be visible to coherent memory accesses performed by shader 14257invocations in subsequent stages when those invocations were triggered by 14258the execution of the original shader invocation (e.g. fragment shader 14259invocations for a primitive resulting from a particular geometry 14260shader invocation).</p> 14261</div> 14262<div class="dlist"> 14263<dl> 14264<dt class="hdlist1">1</dt> 14265<dd> 14266<p>An access is only a <em>future</em> access if a <em>happens-before</em> relation can 14267be established between the store and the load.</p> 14268</dd> 14269</dl> 14270</div> 14271<div class="paragraph"> 14272<p>Additionally, memory barrier functions order stores performed by the calling 14273invocation, as observed by other shader invocations. 14274Without memory barriers, if one shader invocation performs two stores to 14275coherent variables, a second shader invocation might see the values written 14276by the second store prior to seeing those written by the first. 14277However, if the first shader invocation calls a memory barrier function 14278between the two stores, selected other shader invocations will never see the 14279results of the second store before seeing those of the first. 14280When using the functions <strong>groupMemoryBarrier</strong>() or <strong>memoryBarrierShared</strong>(), 14281this ordering guarantee applies only to other shader invocations in the same 14282compute shader workgroup; all other memory barrier functions provide the 14283guarantee to all other shader invocations. 14284No memory barrier is required to guarantee the order of memory stores as 14285observed by the invocation performing the stores; an invocation reading from 14286a variable that it previously wrote will always see the most recently 14287written value unless another shader invocation also wrote to the same 14288memory.</p> 14289</div> 14290</div> 14291<div class="sect2"> 14292<h3 id="_subpass_input_functions">8.17. Subpass-Input Functions</h3> 14293<div class="paragraph"> 14294<p>Subpass-input functions are only available when targeting a Vulkan fragment stage.</p> 14295</div> 14296<div class="paragraph"> 14297<p>Subpass inputs are read through the built-in functions below. The <code>g</code> is again 14298a placeholder for either nothing, <code>i</code>, or <code>u</code>, indicating either a floating-point, 14299signed integer, or unsigned integer, and these must match between argument type 14300and return type.</p> 14301</div> 14302<table class="tableblock frame-all grid-all stretch"> 14303<colgroup> 14304<col style="width: 50%;"> 14305<col style="width: 50%;"> 14306</colgroup> 14307<thead> 14308<tr> 14309<th class="tableblock halign-left valign-top">Syntax</th> 14310<th class="tableblock halign-left valign-top">Description</th> 14311</tr> 14312</thead> 14313<tbody> 14314<tr> 14315<td class="tableblock halign-left valign-top"><p class="tableblock">gvec4 <strong>subpassLoad</strong>(gsubpassInput subpass)<br> 14316 gvec4 <strong>subpassLoad</strong>(gsubpassInputMS subpass, int sample)</p></td> 14317<td class="tableblock halign-left valign-top"><p class="tableblock">Read from a subpass input, from the implicit location <em>(x, y, layer)</em> 14318 of the current fragment coordinate.</p></td> 14319</tr> 14320</tbody> 14321</table> 14322</div> 14323</div> 14324</div> 14325<div class="sect1"> 14326<h2 id="shader-interface-matching">9. Shader Interface Matching</h2> 14327<div class="sectionbody"> 14328<div class="paragraph"> 14329<p>As described in chapter 7 of the <a href="#references">OpenGL ES Specification</a>, shaders may be 14330linked together to form a <em>program object</em> before being bound to the 14331pipeline or may be linked and bound individually as <em>separable program 14332objects</em>.</p> 14333</div> 14334<div class="admonitionblock note"> 14335<table> 14336<tr> 14337<td class="icon"> 14338<i class="fa icon-note" title="Note"></i> 14339</td> 14340<td class="content"> 14341<div class="title">Note</div> 14342<div class="paragraph"> 14343<p>These were previously known as separate shader objects (SSOs) but the 14344mechanism has been extended to support future versions of the specification 14345that have more than two shader stages. 14346It allows a subset of the shaders to be linked together.</p> 14347</div> 14348</td> 14349</tr> 14350</table> 14351</div> 14352<div class="paragraph"> 14353<p>Within a <em>program object</em> or a <em>separable program object</em>, qualifiers for 14354matching variables must themselves match according to the rules specified in 14355this section. 14356There are also matching rules for qualifiers of matching variables between 14357separable program objects but only for variables across an input/output 14358boundary between shader stages. 14359For other shader interface variables such as uniforms, each program object 14360or separable program object has its own name space and so the same name can 14361refer to multiple independent variables. 14362Consequently, there are no matching rules for qualifiers in these cases.</p> 14363</div> 14364<div class="sect2"> 14365<h3 id="input-output-matching-by-name-in-linked-programs">9.1. Input Output Matching by Name in Linked Programs</h3> 14366<div class="paragraph"> 14367<p>When linking shaders, the type of declared vertex outputs and fragment 14368inputs with the same name must match, otherwise the link command will fail. 14369Only those fragment inputs statically used (i.e. read) in the fragment 14370shader must be declared as outputs in the vertex shader; declaring 14371superfluous vertex shader outputs is permissible.</p> 14372</div> 14373<div class="paragraph"> 14374<p>The following table summarizes the rules for matching shader outputs to 14375shader inputs in consecutive stages when shaders are linked together.</p> 14376</div> 14377<table class="tableblock frame-all grid-all fit-content"> 14378<colgroup> 14379<col> 14380<col> 14381<col> 14382<col> 14383<col> 14384</colgroup> 14385<tbody> 14386<tr> 14387<td class="tableblock halign-left valign-top" colspan="2" rowspan="2"><p class="tableblock">Treatment of Mismatched Input Variables</p></td> 14388<td class="tableblock halign-left valign-top" colspan="3"><p class="tableblock">Consuming Shader (input variables)</p></td> 14389</tr> 14390<tr> 14391<td class="tableblock halign-left valign-top"><p class="tableblock">No Declaration</p></td> 14392<td class="tableblock halign-left valign-top"><p class="tableblock">Declared but no Static Use</p></td> 14393<td class="tableblock halign-left valign-top"><p class="tableblock">Declared and Static Use</p></td> 14394</tr> 14395<tr> 14396<td class="tableblock halign-left valign-top" rowspan="3"><p class="tableblock">Generating Shader (output variables)</p></td> 14397<td class="tableblock halign-left valign-top"><p class="tableblock">No Declaration</p></td> 14398<td class="tableblock halign-left valign-top"><p class="tableblock">Allowed</p></td> 14399<td class="tableblock halign-left valign-top"><p class="tableblock">Allowed</p></td> 14400<td class="tableblock halign-left valign-top"><p class="tableblock">error</p></td> 14401</tr> 14402<tr> 14403<td class="tableblock halign-left valign-top"><p class="tableblock">Declares; no static Use</p></td> 14404<td class="tableblock halign-left valign-top"><p class="tableblock">Allowed</p></td> 14405<td class="tableblock halign-left valign-top"><p class="tableblock">Allowed</p></td> 14406<td class="tableblock halign-left valign-top"><p class="tableblock">Allowed (values are undefined)</p></td> 14407</tr> 14408<tr> 14409<td class="tableblock halign-left valign-top"><p class="tableblock">Declares and static Use</p></td> 14410<td class="tableblock halign-left valign-top"><p class="tableblock">Allowed</p></td> 14411<td class="tableblock halign-left valign-top"><p class="tableblock">Allowed</p></td> 14412<td class="tableblock halign-left valign-top"><p class="tableblock">Allowed (values are potentially undefined)</p></td> 14413</tr> 14414</tbody> 14415</table> 14416<div class="paragraph"> 14417<p>See “<a href="#static-use">Static Use</a>” for the definition of <em>static use</em>.</p> 14418</div> 14419<div class="paragraph"> 14420<p>The precision of a vertex output does not need to match the precision of the 14421corresponding fragment input. 14422The minimum precision at which vertex outputs are interpolated is the 14423minimum of the vertex output precision and the fragment input precision, 14424with the exception that for <strong>highp</strong>, implementations do not have to support 14425full IEEE 754 precision.</p> 14426</div> 14427<div class="paragraph"> 14428<p>The precision of values exported to a transform feedback buffer is the 14429precision of the outputs of the vertex shader. 14430However, they are converted to <strong>highp</strong> format before being written.</p> 14431</div> 14432</div> 14433<div class="sect2"> 14434<h3 id="matching-of-qualifiers">9.2. Matching of Qualifiers</h3> 14435<div class="paragraph"> 14436<p>The following tables summarize the requirements for matching of qualifiers. 14437It applies whenever there are two or more matching variables in a shader 14438interface.</p> 14439</div> 14440<div class="paragraph"> 14441<p>Notes:</p> 14442</div> 14443<div class="olist arabic"> 14444<ol class="arabic"> 14445<li> 14446<p><em>Yes</em> means the qualifiers must match.</p> 14447</li> 14448<li> 14449<p><em>No</em> means the qualifiers do not need to match.</p> 14450</li> 14451<li> 14452<p><em>Consistent</em> means qualifiers may be missing from a subset of 14453declarations but they cannot conflict</p> 14454</li> 14455<li> 14456<p>If there are conflicting qualifiers, only the last of these is 14457significant.</p> 14458</li> 14459<li> 14460<p>Matching is based only on the resulting qualification, not on the 14461presence or otherwise of qualifiers.</p> 14462</li> 14463<li> 14464<p>The rules apply to all declared variables, irrespective of whether they 14465are statically used, with the exception of inputs and outputs when 14466shaders are linked (see 14467“<a href="#input-output-matching-by-name-in-linked-programs">Input Output 14468Matching by Name in Linked Programs</a>”).</p> 14469</li> 14470<li> 14471<p>Errors are generated for any conflicts.</p> 14472</li> 14473</ol> 14474</div> 14475<div class="sect3"> 14476<h4 id="linked-shaders">9.2.1. Linked Shaders</h4> 14477<table class="tableblock frame-all grid-all stretch"> 14478<colgroup> 14479<col style="width: 16.6666%;"> 14480<col style="width: 16.6666%;"> 14481<col style="width: 16.6666%;"> 14482<col style="width: 16.6666%;"> 14483<col style="width: 16.6666%;"> 14484<col style="width: 16.667%;"> 14485</colgroup> 14486<thead> 14487<tr> 14488<th class="tableblock halign-left valign-top">Qualifier Class</th> 14489<th class="tableblock halign-left valign-top">Qualifier</th> 14490<th class="tableblock halign-left valign-top"><strong>in</strong>/<strong>out</strong></th> 14491<th class="tableblock halign-left valign-top">Default Uniforms</th> 14492<th class="tableblock halign-left valign-top"><strong>uniform</strong> Block</th> 14493<th class="tableblock halign-left valign-top"><strong>buffer</strong> Block</th> 14494</tr> 14495</thead> 14496<tbody> 14497<tr> 14498<td class="tableblock halign-left valign-top"><p class="tableblock">Storage<sup>1</sup></p></td> 14499<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>in</strong><br> 14500 <strong>out</strong><br> 14501 <strong>uniform</strong></p></td> 14502<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14503<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14504<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14505<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14506</tr> 14507<tr> 14508<td class="tableblock halign-left valign-top" rowspan="2"><p class="tableblock">Auxiliary</p></td> 14509<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>centroid</strong><br> 14510 <strong>sample</strong></p></td> 14511<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 14512<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14513<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14514<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14515</tr> 14516<tr> 14517<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>patch</strong></p></td> 14518<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14519<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14520<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14521<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14522</tr> 14523<tr> 14524<td class="tableblock halign-left valign-top" rowspan="5"><p class="tableblock">Layout</p></td> 14525<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>location</strong></p></td> 14526<td class="tableblock halign-left valign-top"><p class="tableblock">Yes<sup>2</sup></p></td> 14527<td class="tableblock halign-left valign-top"><p class="tableblock">Consistent</p></td> 14528<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14529<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14530</tr> 14531<tr> 14532<td class="tableblock halign-left valign-top"><p class="tableblock">Block layout<sup>3,4</sup></p></td> 14533<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14534<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14535<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14536<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14537</tr> 14538<tr> 14539<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>binding</strong></p></td> 14540<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14541<td class="tableblock halign-left valign-top"><p class="tableblock">Consistent</p></td> 14542<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14543<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14544</tr> 14545<tr> 14546<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>offset</strong></p></td> 14547<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14548<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14549<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14550<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14551</tr> 14552<tr> 14553<td class="tableblock halign-left valign-top"><p class="tableblock">format</p></td> 14554<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14555<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14556<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14557<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14558</tr> 14559<tr> 14560<td class="tableblock halign-left valign-top"><p class="tableblock">Interpolation</p></td> 14561<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>smooth</strong><br> 14562 <strong>flat</strong></p></td> 14563<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14564<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14565<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14566<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14567</tr> 14568<tr> 14569<td class="tableblock halign-left valign-top"><p class="tableblock">Precision</p></td> 14570<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lowp</strong><br> 14571 <strong>mediump</strong><br> 14572 <strong>highp</strong></p></td> 14573<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 14574<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14575<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 14576<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 14577</tr> 14578<tr> 14579<td class="tableblock halign-left valign-top"><p class="tableblock">Variance</p></td> 14580<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>invariant</strong><br> 14581 <strong>precise</strong></p></td> 14582<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 14583<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14584<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14585<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14586</tr> 14587<tr> 14588<td class="tableblock halign-left valign-top"><p class="tableblock">Memory</p></td> 14589<td class="tableblock halign-left valign-top"><p class="tableblock">all</p></td> 14590<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14591<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14592<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14593<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14594</tr> 14595</tbody> 14596</table> 14597<div class="dlist"> 14598<dl> 14599<dt class="hdlist1">1</dt> 14600<dd> 14601<p>Storage qualifiers determine <em>when</em> variables match rather than being 14602<em>required</em> to match for matching variables. 14603Note also that each shader interface has a separate name space so for 14604example, it is possible to use the same name for a vertex output and 14605fragment uniform.</p> 14606</dd> 14607<dt class="hdlist1">2</dt> 14608<dd> 14609<p>If present, the <strong>location</strong> qualifier determines the matching of inputs 14610and outputs. 14611See section 7.4.1 “Shader interface Matching” of the 14612<a href="#references">OpenGL ES Specification</a> for details.]</p> 14613</dd> 14614<dt class="hdlist1">3</dt> 14615<dd> 14616<p>The <strong>row_major</strong> and <strong>column_major</strong> layout qualifiers do not need to 14617match when applied to non-matrix types.</p> 14618</dd> 14619<dt class="hdlist1">4</dt> 14620<dd> 14621<p>In cases where a layout qualifier overrides a previous layout qualifier 14622or a default, only the resulting qualification must match.</p> 14623</dd> 14624</dl> 14625</div> 14626</div> 14627<div class="sect3"> 14628<h4 id="separable-programs">9.2.2. Separable Programs</h4> 14629<table class="tableblock frame-all grid-all stretch"> 14630<colgroup> 14631<col style="width: 33.3333%;"> 14632<col style="width: 33.3333%;"> 14633<col style="width: 33.3334%;"> 14634</colgroup> 14635<thead> 14636<tr> 14637<th class="tableblock halign-left valign-top">Qualifier Class</th> 14638<th class="tableblock halign-left valign-top">Qualifier</th> 14639<th class="tableblock halign-left valign-top"><strong>in</strong>/<strong>out</strong></th> 14640</tr> 14641</thead> 14642<tbody> 14643<tr> 14644<td class="tableblock halign-left valign-top"><p class="tableblock">Storage</p></td> 14645<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>in</strong><br> 14646 <strong>out</strong><br> 14647 <strong>uniform</strong></p></td> 14648<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14649</tr> 14650<tr> 14651<td class="tableblock halign-left valign-top" rowspan="2"><p class="tableblock">Auxiliary</p></td> 14652<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>centroid</strong><br> 14653 <strong>sample</strong></p></td> 14654<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 14655</tr> 14656<tr> 14657<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>patch</strong></p></td> 14658<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14659</tr> 14660<tr> 14661<td class="tableblock halign-left valign-top" rowspan="5"><p class="tableblock">Layout</p></td> 14662<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>location</strong></p></td> 14663<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14664</tr> 14665<tr> 14666<td class="tableblock halign-left valign-top"><p class="tableblock">Block layout</p></td> 14667<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14668</tr> 14669<tr> 14670<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>binding</strong></p></td> 14671<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14672</tr> 14673<tr> 14674<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>offset</strong></p></td> 14675<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14676</tr> 14677<tr> 14678<td class="tableblock halign-left valign-top"><p class="tableblock">format</p></td> 14679<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14680</tr> 14681<tr> 14682<td class="tableblock halign-left valign-top"><p class="tableblock">Interpolation</p></td> 14683<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>smooth</strong><br> 14684 <strong>flat</strong></p></td> 14685<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14686</tr> 14687<tr> 14688<td class="tableblock halign-left valign-top"><p class="tableblock">Precision</p></td> 14689<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lowp</strong><br> 14690 <strong>mediump</strong><br> 14691 <strong>highp</strong></p></td> 14692<td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> 14693</tr> 14694<tr> 14695<td class="tableblock halign-left valign-top"><p class="tableblock">Variance</p></td> 14696<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>invariant</strong><br> 14697 <strong>precise</strong></p></td> 14698<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> 14699</tr> 14700<tr> 14701<td class="tableblock halign-left valign-top"><p class="tableblock">Memory</p></td> 14702<td class="tableblock halign-left valign-top"><p class="tableblock">all</p></td> 14703<td class="tableblock halign-left valign-top"><p class="tableblock">N/A</p></td> 14704</tr> 14705</tbody> 14706</table> 14707</div> 14708</div> 14709</div> 14710</div> 14711<div class="sect1"> 14712<h2 id="shading-language-grammar">10. Shading Language Grammar</h2> 14713<div class="sectionbody"> 14714<div class="paragraph"> 14715<p>The grammar is fed from the output of lexical analysis. 14716The tokens returned from lexical analysis are</p> 14717</div> 14718<div class="openblock bnf"> 14719<div class="content"> 14720<div class="paragraph"> 14721<p>CONST BOOL FLOAT INT UINT</p> 14722</div> 14723<div class="paragraph"> 14724<p>BVEC2 BVEC3 BVEC4 IVEC2 IVEC3 IVEC4 UVEC2 UVEC3 UVEC4 VEC2 VEC3 VEC4</p> 14725</div> 14726<div class="paragraph"> 14727<p>MAT2 MAT3 MAT4 14728MAT2X2 MAT2X3 MAT2X4 14729MAT3X2 MAT3X3 MAT3X4 14730MAT4X2 MAT4X3 MAT4X4</p> 14731</div> 14732<div class="paragraph"> 14733<p>CENTROID IN OUT INOUT UNIFORM PATCH SAMPLE BUFFER SHARED 14734COHERENT VOLATILE RESTRICT READONLY WRITEONLY 14735FLAT SMOOTH LAYOUT</p> 14736</div> 14737<div class="paragraph"> 14738<p>ATOMIC_UINT</p> 14739</div> 14740<div class="paragraph"> 14741<p>SAMPLER2D SAMPLER3D SAMPLERCUBE SAMPLER2DSHADOW 14742SAMPLERCUBESHADOW SAMPLER2DARRAY SAMPLER2DARRAYSHADOW 14743ISAMPLER2D ISAMPLER3D ISAMPLERCUBE ISAMPLER2DARRAY 14744USAMPLER2D USAMPLER3D USAMPLERCUBE USAMPLER2DARRAY</p> 14745</div> 14746<div class="paragraph"> 14747<p>SAMPLERBUFFER ISAMPLERBUFFER USAMPLERBUFFER 14748SAMPLERCUBEARRAY SAMPLERCUBEARRAYSHADOW 14749ISAMPLERCUBEARRAY USAMPLERCUBEARRAY 14750SAMPLER2DMS ISAMPLER2DMS USAMPLER2DMS 14751SAMPLER2DMSARRAY ISAMPLER2DMSARRAY USAMPLER2DMSARRAY 14752IMAGE2D IIMAGE2D UIMAGE2D 14753IMAGE3D IIMAGE3D UIMAGE3D 14754IMAGECUBE IIMAGECUBE UIMAGECUBE 14755IMAGEBUFFER IIMAGEBUFFER UIMAGEBUFFER 14756IMAGE2DARRAY IIMAGE2DARRAY UIMAGE2DARRAY 14757IMAGECUBEARRAY IIMAGECUBEARRAY UIMAGECUBEARRAY</p> 14758</div> 14759<div class="paragraph"> 14760<p>STRUCT VOID</p> 14761</div> 14762<div class="paragraph"> 14763<p>WHILE BREAK CONTINUE DO ELSE FOR IF DISCARD RETURN SWITCH CASE DEFAULT</p> 14764</div> 14765<div class="paragraph"> 14766<p>IDENTIFIER TYPE_NAME 14767FLOATCONSTANT INTCONSTANT UINTCONSTANT BOOLCONSTANT 14768FIELD_SELECTION</p> 14769</div> 14770<div class="paragraph"> 14771<p>LEFT_OP RIGHT_OP 14772INC_OP DEC_OP LE_OP GE_OP EQ_OP NE_OP 14773AND_OP OR_OP XOR_OP MUL_ASSIGN DIV_ASSIGN ADD_ASSIGN 14774MOD_ASSIGN LEFT_ASSIGN RIGHT_ASSIGN AND_ASSIGN XOR_ASSIGN OR_ASSIGN 14775SUB_ASSIGN 14776LEFT_PAREN RIGHT_PAREN LEFT_BRACKET RIGHT_BRACKET LEFT_BRACE RIGHT_BRACE DOT 14777COMMA COLON EQUAL SEMICOLON BANG DASH TILDE PLUS STAR SLASH PERCENT 14778LEFT_ANGLE RIGHT_ANGLE VERTICAL_BAR CARET AMPERSAND QUESTION</p> 14779</div> 14780<div class="paragraph"> 14781<p>INVARIANT PRECISE 14782HIGH_PRECISION MEDIUM_PRECISION LOW_PRECISION PRECISION</p> 14783</div> 14784</div> 14785</div> 14786<div class="paragraph"> 14787<p>The following describes the grammar for the OpenGL ES Shading Language in terms of the above 14788tokens. 14789The starting rule is <em>translation_unit</em>.</p> 14790</div> 14791<div class="openblock bnf"> 14792<div class="content"> 14793<div class="dlist"> 14794<dl> 14795<dt class="hdlist1"><em>variable_identifier</em> : </dt> 14796<dd> 14797<p><em>IDENTIFIER</em></p> 14798</dd> 14799<dt class="hdlist1"><em>primary_expression</em> : </dt> 14800<dd> 14801<p><em>variable_identifier</em><br> 14802<em>INTCONSTANT</em><br> 14803<em>UINTCONSTANT</em><br> 14804<em>FLOATCONSTANT</em><br> 14805<em>BOOLCONSTANT</em><br> 14806<em>LEFT_PAREN</em> <em>expression</em> <em>RIGHT_PAREN</em></p> 14807</dd> 14808<dt class="hdlist1"><em>postfix_expression</em> : </dt> 14809<dd> 14810<p><em>primary_expression</em><br> 14811<em>postfix_expression</em> <em>LEFT_BRACKET</em> <em>integer_expression</em> <em>RIGHT_BRACKET</em><br> 14812<em>function_call</em><br> 14813<em>postfix_expression</em> <em>DOT</em> <em>FIELD_SELECTION</em><br> 14814<em>postfix_expression</em> <em>INC_OP</em><br> 14815<em>postfix_expression</em> <em>DEC_OP</em></p> 14816</dd> 14817</dl> 14818</div> 14819<div class="admonitionblock note"> 14820<table> 14821<tr> 14822<td class="icon"> 14823<i class="fa icon-note" title="Note"></i> 14824</td> 14825<td class="content"> 14826<div class="paragraph"> 14827<p>FIELD_SELECTION includes members in structures, component selection for 14828vectors and the 'length' identifier for the length() method</p> 14829</div> 14830</td> 14831</tr> 14832</table> 14833</div> 14834<div class="dlist"> 14835<dl> 14836<dt class="hdlist1"><em>integer_expression</em> : </dt> 14837<dd> 14838<p><em>expression</em></p> 14839</dd> 14840<dt class="hdlist1"><em>function_call</em> : </dt> 14841<dd> 14842<p><em>function_call_or_method</em></p> 14843</dd> 14844<dt class="hdlist1"><em>function_call_or_method</em> : </dt> 14845<dd> 14846<p><em>function_call_generic</em></p> 14847</dd> 14848<dt class="hdlist1"><em>function_call_generic</em> : </dt> 14849<dd> 14850<p><em>function_call_header_with_parameters</em> <em>RIGHT_PAREN</em><br> 14851<em>function_call_header_no_parameters</em> <em>RIGHT_PAREN</em></p> 14852</dd> 14853<dt class="hdlist1"><em>function_call_header_no_parameters</em> : </dt> 14854<dd> 14855<p><em>function_call_header</em> <em>VOID</em><br> 14856<em>function_call_header</em></p> 14857</dd> 14858<dt class="hdlist1"><em>function_call_header_with_parameters</em> : </dt> 14859<dd> 14860<p><em>function_call_header</em> <em>assignment_expression</em><br> 14861<em>function_call_header_with_parameters</em> <em>COMMA</em> <em>assignment_expression</em></p> 14862</dd> 14863<dt class="hdlist1"><em>function_call_header</em> : </dt> 14864<dd> 14865<p><em>function_identifier</em> <em>LEFT_PAREN</em></p> 14866</dd> 14867</dl> 14868</div> 14869<div class="admonitionblock note"> 14870<table> 14871<tr> 14872<td class="icon"> 14873<i class="fa icon-note" title="Note"></i> 14874</td> 14875<td class="content"> 14876<div class="paragraph"> 14877<p>Grammar Note: Constructors look like functions, but lexical analysis 14878recognized most of them as keywords. 14879They are now recognized through <em>type_specifier</em>.</p> 14880</div> 14881</td> 14882</tr> 14883</table> 14884</div> 14885<div class="admonitionblock note"> 14886<table> 14887<tr> 14888<td class="icon"> 14889<i class="fa icon-note" title="Note"></i> 14890</td> 14891<td class="content"> 14892<div class="paragraph"> 14893<p>Methods (<strong>.length</strong>) and identifiers are recognized through 14894<em>postfix_expression</em>.</p> 14895</div> 14896</td> 14897</tr> 14898</table> 14899</div> 14900<div class="dlist"> 14901<dl> 14902<dt class="hdlist1"><em>function_identifier</em> : </dt> 14903<dd> 14904<p><em>type_specifier</em><br> 14905<em>postfix_expression</em></p> 14906</dd> 14907<dt class="hdlist1"><em>unary_expression</em> : </dt> 14908<dd> 14909<p><em>postfix_expression</em><br> 14910<em>INC_OP</em> <em>unary_expression</em><br> 14911<em>DEC_OP</em> <em>unary_expression</em><br> 14912<em>unary_operator</em> <em>unary_expression</em></p> 14913</dd> 14914</dl> 14915</div> 14916<div class="admonitionblock note"> 14917<table> 14918<tr> 14919<td class="icon"> 14920<i class="fa icon-note" title="Note"></i> 14921</td> 14922<td class="content"> 14923<div class="paragraph"> 14924<p>Grammar Note: No traditional style type casts.</p> 14925</div> 14926</td> 14927</tr> 14928</table> 14929</div> 14930<div class="dlist"> 14931<dl> 14932<dt class="hdlist1"><em>unary_operator</em> : </dt> 14933<dd> 14934<p><em>PLUS</em><br> 14935<em>DASH</em><br> 14936<em>BANG</em><br> 14937<em>TILDE</em></p> 14938</dd> 14939</dl> 14940</div> 14941<div class="admonitionblock note"> 14942<table> 14943<tr> 14944<td class="icon"> 14945<i class="fa icon-note" title="Note"></i> 14946</td> 14947<td class="content"> 14948<div class="paragraph"> 14949<p>Grammar Note: No '*' or '&' unary ops. 14950Pointers are not supported.</p> 14951</div> 14952</td> 14953</tr> 14954</table> 14955</div> 14956<div class="dlist"> 14957<dl> 14958<dt class="hdlist1"><em>multiplicative_expression</em> : </dt> 14959<dd> 14960<p><em>unary_expression</em><br> 14961<em>multiplicative_expression</em> <em>STAR</em> <em>unary_expression</em><br> 14962<em>multiplicative_expression</em> <em>SLASH</em> <em>unary_expression</em><br> 14963<em>multiplicative_expression</em> <em>PERCENT</em> <em>unary_expression</em></p> 14964</dd> 14965<dt class="hdlist1"><em>additive_expression</em> : </dt> 14966<dd> 14967<p><em>multiplicative_expression</em><br> 14968<em>additive_expression</em> <em>PLUS</em> <em>multiplicative_expression</em><br> 14969<em>additive_expression</em> <em>DASH</em> <em>multiplicative_expression</em></p> 14970</dd> 14971<dt class="hdlist1"><em>shift_expression</em> : </dt> 14972<dd> 14973<p><em>additive_expression</em><br> 14974<em>shift_expression</em> <em>LEFT_OP</em> <em>additive_expression</em><br> 14975<em>shift_expression</em> <em>RIGHT_OP</em> <em>additive_expression</em></p> 14976</dd> 14977<dt class="hdlist1"><em>relational_expression</em> : </dt> 14978<dd> 14979<p><em>shift_expression</em><br> 14980<em>relational_expression</em> <em>LEFT_ANGLE</em> <em>shift_expression</em><br> 14981<em>relational_expression</em> <em>RIGHT_ANGLE</em> <em>shift_expression</em><br> 14982<em>relational_expression</em> <em>LE_OP</em> <em>shift_expression</em><br> 14983<em>relational_expression</em> <em>GE_OP</em> <em>shift_expression</em></p> 14984</dd> 14985<dt class="hdlist1"><em>equality_expression</em> : </dt> 14986<dd> 14987<p><em>relational_expression</em><br> 14988<em>equality_expression</em> <em>EQ_OP</em> <em>relational_expression</em><br> 14989<em>equality_expression</em> <em>NE_OP</em> <em>relational_expression</em></p> 14990</dd> 14991<dt class="hdlist1"><em>and_expression</em> : </dt> 14992<dd> 14993<p><em>equality_expression</em><br> 14994<em>and_expression</em> <em>AMPERSAND</em> <em>equality_expression</em></p> 14995</dd> 14996<dt class="hdlist1"><em>exclusive_or_expression</em> : </dt> 14997<dd> 14998<p><em>and_expression</em><br> 14999<em>exclusive_or_expression</em> <em>CARET</em> <em>and_expression</em></p> 15000</dd> 15001<dt class="hdlist1"><em>inclusive_or_expression</em> : </dt> 15002<dd> 15003<p><em>exclusive_or_expression</em><br> 15004<em>inclusive_or_expression</em> <em>VERTICAL_BAR</em> <em>exclusive_or_expression</em></p> 15005</dd> 15006<dt class="hdlist1"><em>logical_and_expression</em> : </dt> 15007<dd> 15008<p><em>inclusive_or_expression</em><br> 15009<em>logical_and_expression</em> <em>AND_OP</em> <em>inclusive_or_expression</em></p> 15010</dd> 15011<dt class="hdlist1"><em>logical_xor_expression</em> : </dt> 15012<dd> 15013<p><em>logical_and_expression</em><br> 15014<em>logical_xor_expression</em> <em>XOR_OP</em> <em>logical_and_expression</em></p> 15015</dd> 15016<dt class="hdlist1"><em>logical_or_expression</em> : </dt> 15017<dd> 15018<p><em>logical_xor_expression</em><br> 15019<em>logical_or_expression</em> <em>OR_OP</em> <em>logical_xor_expression</em></p> 15020</dd> 15021<dt class="hdlist1"><em>conditional_expression</em> : </dt> 15022<dd> 15023<p><em>logical_or_expression</em><br> 15024<em>logical_or_expression</em> <em>QUESTION</em> <em>expression</em> <em>COLON</em> 15025<em>assignment_expression</em></p> 15026</dd> 15027<dt class="hdlist1"><em>assignment_expression</em> : </dt> 15028<dd> 15029<p><em>conditional_expression</em><br> 15030<em>unary_expression</em> <em>assignment_operator</em> <em>assignment_expression</em></p> 15031</dd> 15032<dt class="hdlist1"><em>assignment_operator</em> : </dt> 15033<dd> 15034<p><em>EQUAL</em><br> 15035<em>MUL_ASSIGN</em><br> 15036<em>DIV_ASSIGN</em><br> 15037<em>MOD_ASSIGN</em><br> 15038<em>ADD_ASSIGN</em><br> 15039<em>SUB_ASSIGN</em><br> 15040<em>LEFT_ASSIGN</em><br> 15041<em>RIGHT_ASSIGN</em><br> 15042<em>AND_ASSIGN</em><br> 15043<em>XOR_ASSIGN</em><br> 15044<em>OR_ASSIGN</em></p> 15045</dd> 15046<dt class="hdlist1"><em>expression</em> : </dt> 15047<dd> 15048<p><em>assignment_expression</em><br> 15049<em>expression</em> <em>COMMA</em> <em>assignment_expression</em></p> 15050</dd> 15051<dt class="hdlist1"><em>constant_expression</em> : </dt> 15052<dd> 15053<p><em>conditional_expression</em></p> 15054</dd> 15055<dt class="hdlist1"><em>declaration</em> : </dt> 15056<dd> 15057<p><em>function_prototype</em> <em>SEMICOLON</em><br> 15058<em>init_declarator_list</em> <em>SEMICOLON</em><br> 15059<em>PRECISION</em> <em>precision_qualifier</em> <em>type_specifier</em> <em>SEMICOLON</em><br> 15060<em>type_qualifier</em> <em>IDENTIFIER</em> <em>LEFT_BRACE</em> <em>struct_declaration_list</em> 15061<em>RIGHT_BRACE</em> <em>SEMICOLON</em><br> 15062<em>type_qualifier</em> <em>IDENTIFIER</em> <em>LEFT_BRACE</em> <em>struct_declaration_list</em> 15063<em>RIGHT_BRACE</em> <em>IDENTIFIER</em> <em>SEMICOLON</em><br> 15064<em>type_qualifier</em> <em>IDENTIFIER</em> <em>LEFT_BRACE</em> <em>struct_declaration_list</em> 15065<em>RIGHT_BRACE</em> <em>IDENTIFIER</em> <em>array_specifier</em> <em>SEMICOLON</em><br> 15066<em>type_qualifier</em> <em>SEMICOLON</em><br> 15067<em>type_qualifier</em> <em>IDENTIFIER</em> <em>SEMICOLON</em><br> 15068<em>type_qualifier</em> <em>IDENTIFIER</em> <em>identifier_list</em> <em>SEMICOLON</em></p> 15069</dd> 15070<dt class="hdlist1"><em>identifier_list</em> : </dt> 15071<dd> 15072<p><em>COMMA</em> <em>IDENTIFIER</em><br> 15073<em>identifier_list</em> <em>COMMA</em> <em>IDENTIFIER</em></p> 15074</dd> 15075<dt class="hdlist1"><em>function_prototype</em> : </dt> 15076<dd> 15077<p><em>function_declarator</em> <em>RIGHT_PAREN</em></p> 15078</dd> 15079<dt class="hdlist1"><em>function_declarator</em> : </dt> 15080<dd> 15081<p><em>function_header</em><br> 15082<em>function_header_with_parameters</em></p> 15083</dd> 15084<dt class="hdlist1"><em>function_header_with_parameters</em> : </dt> 15085<dd> 15086<p><em>function_header</em> <em>parameter_declaration</em><br> 15087<em>function_header_with_parameters</em> <em>COMMA</em> <em>parameter_declaration</em></p> 15088</dd> 15089<dt class="hdlist1"><em>function_header</em> : </dt> 15090<dd> 15091<p><em>fully_specified_type</em> <em>IDENTIFIER</em> <em>LEFT_PAREN</em></p> 15092</dd> 15093<dt class="hdlist1"><em>parameter_declarator</em> : </dt> 15094<dd> 15095<p><em>type_specifier</em> <em>IDENTIFIER</em><br> 15096<em>type_specifier</em> <em>IDENTIFIER</em> <em>array_specifier</em></p> 15097</dd> 15098<dt class="hdlist1"><em>parameter_declaration</em> : </dt> 15099<dd> 15100<p><em>type_qualifier</em> <em>parameter_declarator</em><br> 15101<em>parameter_declarator</em><br> 15102<em>type_qualifier</em> <em>parameter_type_specifier</em><br> 15103<em>parameter_type_specifier</em></p> 15104</dd> 15105<dt class="hdlist1"><em>parameter_type_specifier</em> : </dt> 15106<dd> 15107<p><em>type_specifier</em></p> 15108</dd> 15109<dt class="hdlist1"><em>init_declarator_list</em> : </dt> 15110<dd> 15111<p><em>single_declaration</em><br> 15112<em>init_declarator_list</em> <em>COMMA</em> <em>IDENTIFIER</em><br> 15113<em>init_declarator_list</em> <em>COMMA</em> <em>IDENTIFIER</em> <em>array_specifier</em><br> 15114<em>init_declarator_list</em> <em>COMMA</em> <em>IDENTIFIER</em> <em>array_specifier</em> <em>EQUAL</em> 15115<em>initializer</em><br> 15116<em>init_declarator_list</em> <em>COMMA</em> <em>IDENTIFIER</em> <em>EQUAL</em> <em>initializer</em></p> 15117</dd> 15118<dt class="hdlist1"><em>single_declaration</em> : </dt> 15119<dd> 15120<p><em>fully_specified_type</em><br> 15121<em>fully_specified_type</em> <em>IDENTIFIER</em><br> 15122<em>fully_specified_type</em> <em>IDENTIFIER</em> <em>array_specifier</em><br> 15123<em>fully_specified_type</em> <em>IDENTIFIER</em> <em>array_specifier</em> <em>EQUAL</em> 15124<em>initializer</em><br> 15125<em>fully_specified_type</em> <em>IDENTIFIER</em> <em>EQUAL</em> <em>initializer</em></p> 15126</dd> 15127</dl> 15128</div> 15129<div class="admonitionblock note"> 15130<table> 15131<tr> 15132<td class="icon"> 15133<i class="fa icon-note" title="Note"></i> 15134</td> 15135<td class="content"> 15136<div class="paragraph"> 15137<p>Grammar Note: No 'enum', or 'typedef'.</p> 15138</div> 15139</td> 15140</tr> 15141</table> 15142</div> 15143<div class="dlist"> 15144<dl> 15145<dt class="hdlist1"><em>fully_specified_type</em> : </dt> 15146<dd> 15147<p><em>type_specifier</em><br> 15148<em>type_qualifier</em> <em>type_specifier</em></p> 15149</dd> 15150<dt class="hdlist1"><em>invariant_qualifier</em> : </dt> 15151<dd> 15152<p><em>INVARIANT</em></p> 15153</dd> 15154<dt class="hdlist1"><em>interpolation_qualifier</em> : </dt> 15155<dd> 15156<p><em>SMOOTH</em><br> 15157<em>FLAT</em></p> 15158</dd> 15159<dt class="hdlist1"><em>layout_qualifier</em> : </dt> 15160<dd> 15161<p><em>LAYOUT</em> <em>LEFT_PAREN</em> <em>layout_qualifier_id_list</em> <em>RIGHT_PAREN</em></p> 15162</dd> 15163<dt class="hdlist1"><em>layout_qualifier_id_list</em> : </dt> 15164<dd> 15165<p><em>layout_qualifier_id</em><br> 15166<em>layout_qualifier_id_list</em> <em>COMMA</em> <em>layout_qualifier_id</em></p> 15167</dd> 15168<dt class="hdlist1"><em>layout_qualifier_id</em> : </dt> 15169<dd> 15170<p><em>IDENTIFIER</em><br> 15171<em>IDENTIFIER</em> <em>EQUAL</em> <em>INTCONSTANT</em><br> 15172<em>IDENTIFIER</em> <em>EQUAL</em> <em>UINTCONSTANT</em><br> 15173<em>SHARED</em></p> 15174</dd> 15175<dt class="hdlist1"><em>precise_qualifier</em> : </dt> 15176<dd> 15177<p><em>PRECISE</em></p> 15178</dd> 15179<dt class="hdlist1"><em>type_qualifier</em> : </dt> 15180<dd> 15181<p><em>single_type_qualifier</em><br> 15182<em>type_qualifier</em> <em>single_type_qualifier</em></p> 15183</dd> 15184<dt class="hdlist1"><em>single_type_qualifier</em> : </dt> 15185<dd> 15186<p><em>storage_qualifier</em><br> 15187<em>layout_qualifier</em><br> 15188<em>precision_qualifier</em><br> 15189<em>interpolation_qualifier</em><br> 15190<em>invariant_qualifier</em><br> 15191<em>precise_qualifier</em></p> 15192</dd> 15193<dt class="hdlist1"><em>storage_qualifier</em> : </dt> 15194<dd> 15195<p><em>CONST</em><br> 15196<em>IN</em><br> 15197<em>OUT</em><br> 15198<em>INOUT</em><br> 15199<em>CENTROID</em><br> 15200<em>PATCH</em><br> 15201<em>SAMPLE</em><br> 15202<em>UNIFORM</em><br> 15203<em>BUFFER</em><br> 15204<em>SHARED</em><br> 15205<em>COHERENT</em><br> 15206<em>VOLATILE</em><br> 15207<em>RESTRICT</em><br> 15208<em>READONLY</em><br> 15209<em>WRITEONLY</em></p> 15210</dd> 15211<dt class="hdlist1"><em>type_specifier</em> : </dt> 15212<dd> 15213<p><em>type_specifier_nonarray</em><br> 15214<em>type_specifier_nonarray</em> <em>array_specifier</em></p> 15215</dd> 15216<dt class="hdlist1"><em>array_specifier</em> : </dt> 15217<dd> 15218<p><em>LEFT_BRACKET</em> <em>RIGHT_BRACKET</em><br> 15219<em>LEFT_BRACKET</em> <em>conditional_expression</em> <em>RIGHT_BRACKET</em><br> 15220<em>array_specifier</em> <em>LEFT_BRACKET</em> <em>RIGHT_BRACKET</em><br> 15221<em>array_specifier</em> <em>LEFT_BRACKET</em> <em>conditional_expression</em> <em>RIGHT_BRACKET</em></p> 15222</dd> 15223<dt class="hdlist1"><em>type_specifier_nonarray</em> : </dt> 15224<dd> 15225<p><em>VOID</em><br> 15226<em>FLOAT</em><br> 15227<em>INT</em><br> 15228<em>UINT</em><br> 15229<em>BOOL</em><br> 15230<em>VEC2</em><br> 15231<em>VEC3</em><br> 15232<em>VEC4</em><br> 15233<em>BVEC2</em><br> 15234<em>BVEC3</em><br> 15235<em>BVEC4</em><br> 15236<em>IVEC2</em><br> 15237<em>IVEC3</em><br> 15238<em>IVEC4</em><br> 15239<em>UVEC2</em><br> 15240<em>UVEC3</em><br> 15241<em>UVEC4</em><br> 15242<em>MAT2</em><br> 15243<em>MAT3</em><br> 15244<em>MAT4</em><br> 15245<em>MAT2X2</em><br> 15246<em>MAT2X3</em><br> 15247<em>MAT2X4</em><br> 15248<em>MAT3X2</em><br> 15249<em>MAT3X3</em><br> 15250<em>MAT3X4</em><br> 15251<em>MAT4X2</em><br> 15252<em>MAT4X3</em><br> 15253<em>MAT4X4</em><br> 15254<em>ATOMIC_UINT</em><br> 15255<em>SAMPLER2D</em><br> 15256<em>SAMPLER3D</em><br> 15257<em>SAMPLERCUBE</em><br> 15258<em>SAMPLER2DSHADOW</em><br> 15259<em>SAMPLERCUBESHADOW</em><br> 15260<em>SAMPLER2DARRAY</em><br> 15261<em>SAMPLER2DARRAYSHADOW</em><br> 15262<em>SAMPLERCUBEARRAY</em><br> 15263<em>SAMPLERCUBEARRAYSHADOW</em><br> 15264<em>ISAMPLER2D</em><br> 15265<em>ISAMPLER3D</em><br> 15266<em>ISAMPLERCUBE</em><br> 15267<em>ISAMPLER2DARRAY</em><br> 15268<em>ISAMPLERCUBEARRAY</em><br> 15269<em>USAMPLER2D</em><br> 15270<em>USAMPLER3D</em><br> 15271<em>USAMPLERCUBE</em><br> 15272<em>USAMPLER2DARRAY</em><br> 15273<em>USAMPLERCUBEARRAY</em><br> 15274<em>SAMPLERBUFFER</em><br> 15275<em>ISAMPLERBUFFER</em><br> 15276<em>USAMPLERBUFFER</em><br> 15277<em>SAMPLER2DMS</em><br> 15278<em>ISAMPLER2DMS</em><br> 15279<em>USAMPLER2DMS</em><br> 15280<em>SAMPLER2DMSARRAY</em><br> 15281<em>ISAMPLER2DMSARRAY</em><br> 15282<em>USAMPLER2DMSARRAY</em><br> 15283<em>IMAGE2D</em><br> 15284<em>IIMAGE2D</em><br> 15285<em>UIMAGE2D</em><br> 15286<em>IMAGE3D</em><br> 15287<em>IIMAGE3D</em><br> 15288<em>UIMAGE3D</em><br> 15289<em>IMAGECUBE</em><br> 15290<em>IIMAGECUBE</em><br> 15291<em>UIMAGECUBE</em><br> 15292<em>IMAGEBUFFER</em><br> 15293<em>IIMAGEBUFFER</em><br> 15294<em>UIMAGEBUFFER</em><br> 15295<em>IMAGE2DARRAY</em><br> 15296<em>IIMAGE2DARRAY</em><br> 15297<em>UIMAGE2DARRAY</em><br> 15298<em>IMAGECUBEARRAY</em><br> 15299<em>IIMAGECUBEARRAY</em><br> 15300<em>UIMAGECUBEARRAY</em><br> 15301<em>struct_specifier</em><br> 15302<em>TYPE_NAME</em></p> 15303</dd> 15304<dt class="hdlist1"><em>precision_qualifier</em> : </dt> 15305<dd> 15306<p><em>HIGH_PRECISION</em><br> 15307<em>MEDIUM_PRECISION</em><br> 15308<em>LOW_PRECISION</em></p> 15309</dd> 15310<dt class="hdlist1"><em>struct_specifier</em> : </dt> 15311<dd> 15312<p><em>STRUCT</em> <em>IDENTIFIER</em> <em>LEFT_BRACE</em> <em>struct_declaration_list</em> 15313<em>RIGHT_BRACE</em><br> 15314<em>STRUCT</em> <em>LEFT_BRACE</em> <em>struct_declaration_list</em> <em>RIGHT_BRACE</em></p> 15315</dd> 15316<dt class="hdlist1"><em>struct_declaration_list</em> : </dt> 15317<dd> 15318<p><em>struct_declaration</em><br> 15319<em>struct_declaration_list</em> <em>struct_declaration</em></p> 15320</dd> 15321<dt class="hdlist1"><em>struct_declaration</em> : </dt> 15322<dd> 15323<p><em>type_specifier</em> <em>struct_declarator_list</em> <em>SEMICOLON</em><br> 15324<em>type_qualifier</em> <em>type_specifier</em> <em>struct_declarator_list</em> <em>SEMICOLON</em></p> 15325</dd> 15326<dt class="hdlist1"><em>struct_declarator_list</em> : </dt> 15327<dd> 15328<p><em>struct_declarator</em><br> 15329<em>struct_declarator_list</em> <em>COMMA</em> <em>struct_declarator</em></p> 15330</dd> 15331<dt class="hdlist1"><em>struct_declarator</em> : </dt> 15332<dd> 15333<p><em>IDENTIFIER</em><br> 15334<em>IDENTIFIER</em> <em>array_specifier</em></p> 15335</dd> 15336<dt class="hdlist1"><em>initializer</em> : </dt> 15337<dd> 15338<p><em>assignment_expression</em></p> 15339</dd> 15340<dt class="hdlist1"><em>declaration_statement</em> : </dt> 15341<dd> 15342<p><em>declaration</em></p> 15343</dd> 15344<dt class="hdlist1"><em>statement</em> : </dt> 15345<dd> 15346<p><em>compound_statement</em><br> 15347<em>simple_statement</em></p> 15348</dd> 15349</dl> 15350</div> 15351<div class="admonitionblock note"> 15352<table> 15353<tr> 15354<td class="icon"> 15355<i class="fa icon-note" title="Note"></i> 15356</td> 15357<td class="content"> 15358<div class="paragraph"> 15359<p>Grammar Note: labeled statements for SWITCH only; 'goto' is not supported.</p> 15360</div> 15361</td> 15362</tr> 15363</table> 15364</div> 15365<div class="dlist"> 15366<dl> 15367<dt class="hdlist1"><em>simple_statement</em> : </dt> 15368<dd> 15369<p><em>declaration_statement</em><br> 15370<em>expression_statement</em><br> 15371<em>selection_statement</em><br> 15372<em>switch_statement</em><br> 15373<em>case_label</em><br> 15374<em>iteration_statement</em><br> 15375<em>jump_statement</em></p> 15376</dd> 15377<dt class="hdlist1"><em>compound_statement</em> : </dt> 15378<dd> 15379<p><em>LEFT_BRACE</em> <em>RIGHT_BRACE</em><br> 15380<em>LEFT_BRACE</em> <em>statement_list</em> <em>RIGHT_BRACE</em></p> 15381</dd> 15382<dt class="hdlist1"><em>statement_no_new_scope</em> : </dt> 15383<dd> 15384<p><em>compound_statement_no_new_scope</em><br> 15385<em>simple_statement</em></p> 15386</dd> 15387<dt class="hdlist1"><em>compound_statement_no_new_scope</em> : </dt> 15388<dd> 15389<p><em>LEFT_BRACE</em> <em>RIGHT_BRACE</em><br> 15390<em>LEFT_BRACE</em> <em>statement_list</em> <em>RIGHT_BRACE</em></p> 15391</dd> 15392<dt class="hdlist1"><em>statement_list</em> : </dt> 15393<dd> 15394<p><em>statement</em><br> 15395<em>statement_list</em> <em>statement</em></p> 15396</dd> 15397<dt class="hdlist1"><em>expression_statement</em> : </dt> 15398<dd> 15399<p><em>SEMICOLON</em><br> 15400<em>expression</em> <em>SEMICOLON</em></p> 15401</dd> 15402<dt class="hdlist1"><em>selection_statement</em> : </dt> 15403<dd> 15404<p><em>IF</em> <em>LEFT_PAREN</em> <em>expression</em> <em>RIGHT_PAREN</em> <em>selection_rest_statement</em></p> 15405</dd> 15406<dt class="hdlist1"><em>selection_rest_statement</em> : </dt> 15407<dd> 15408<p><em>statement</em> <em>ELSE</em> <em>statement</em><br> 15409<em>statement</em></p> 15410</dd> 15411<dt class="hdlist1"><em>condition</em> : </dt> 15412<dd> 15413<p><em>expression</em><br> 15414<em>fully_specified_type</em> <em>IDENTIFIER</em> <em>EQUAL</em> <em>initializer</em></p> 15415</dd> 15416<dt class="hdlist1"><em>switch_statement</em> : </dt> 15417<dd> 15418<p><em>SWITCH</em> <em>LEFT_PAREN</em> <em>expression</em> <em>RIGHT_PAREN</em> <em>LEFT_BRACE</em> 15419<em>switch_statement_list</em><br> 15420<em>RIGHT_BRACE</em></p> 15421</dd> 15422<dt class="hdlist1"><em>switch_statement_list</em> : </dt> 15423<dd> 15424<p>/* <em>nothing</em> */<br> 15425<em>statement_list</em></p> 15426</dd> 15427<dt class="hdlist1"><em>case_label</em> : </dt> 15428<dd> 15429<p><em>CASE</em> <em>expression</em> <em>COLON</em><br> 15430<em>DEFAULT</em> <em>COLON</em></p> 15431</dd> 15432<dt class="hdlist1"><em>iteration_statement</em> : </dt> 15433<dd> 15434<p><em>WHILE</em> <em>LEFT_PAREN</em> <em>condition</em> <em>RIGHT_PAREN</em> <em>statement_no_new_scope</em><br> 15435<em>DO</em> <em>statement</em> <em>WHILE</em> <em>LEFT_PAREN</em> <em>expression</em> <em>RIGHT_PAREN</em> 15436<em>SEMICOLON</em><br> 15437<em>FOR</em> <em>LEFT_PAREN</em> <em>for_init_statement</em> <em>for_rest_statement</em> 15438<em>RIGHT_PAREN</em> <em>statement_no_new_scope</em></p> 15439</dd> 15440<dt class="hdlist1"><em>for_init_statement</em> : </dt> 15441<dd> 15442<p><em>expression_statement</em><br> 15443<em>declaration_statement</em></p> 15444</dd> 15445<dt class="hdlist1"><em>conditionopt</em> : </dt> 15446<dd> 15447<p><em>condition</em><br> 15448/* <em>empty</em> */</p> 15449</dd> 15450<dt class="hdlist1"><em>for_rest_statement</em> : </dt> 15451<dd> 15452<p><em>conditionopt</em> <em>SEMICOLON</em><br> 15453<em>conditionopt</em> <em>SEMICOLON</em> <em>expression</em></p> 15454</dd> 15455<dt class="hdlist1"><em>jump_statement</em> : </dt> 15456<dd> 15457<p><em>CONTINUE</em> <em>SEMICOLON</em><br> 15458<em>BREAK</em> <em>SEMICOLON</em><br> 15459<em>RETURN</em> <em>SEMICOLON</em><br> 15460<em>RETURN</em> <em>expression</em> <em>SEMICOLON</em><br> 15461<em>DISCARD</em> <em>SEMICOLON</em> // Fragment shader only.</p> 15462</dd> 15463</dl> 15464</div> 15465<div class="admonitionblock note"> 15466<table> 15467<tr> 15468<td class="icon"> 15469<i class="fa icon-note" title="Note"></i> 15470</td> 15471<td class="content"> 15472<div class="paragraph"> 15473<p>Grammar Note: No 'goto'. 15474Gotos are not supported.</p> 15475</div> 15476</td> 15477</tr> 15478</table> 15479</div> 15480<div class="dlist"> 15481<dl> 15482<dt class="hdlist1"><em>translation_unit</em> : </dt> 15483<dd> 15484<p><em>external_declaration</em><br> 15485<em>translation_unit</em> <em>external_declaration</em></p> 15486</dd> 15487<dt class="hdlist1"><em>external_declaration</em> : </dt> 15488<dd> 15489<p><em>function_definition</em><br> 15490<em>declaration</em></p> 15491</dd> 15492<dt class="hdlist1"><em>function_definition</em> : </dt> 15493<dd> 15494<p><em>function_prototype</em> <em>compound_statement_no_new_scope</em></p> 15495</dd> 15496</dl> 15497</div> 15498</div> 15499</div> 15500<div class="paragraph"> 15501<p>In general the above grammar describes a super set of the OpenGL ES Shading Language. 15502Certain constructs that are valid purely in terms of the grammar are 15503disallowed by statements elsewhere in this specification.</p> 15504</div> 15505</div> 15506</div> 15507<div class="sect1"> 15508<h2 id="counting-of-inputs-and-outputs">11. Counting of Inputs and Outputs</h2> 15509<div class="sectionbody"> 15510<div class="paragraph"> 15511<p>This section applies to outputs from the last active vertex processing stage 15512and inputs to the fragment stage. 15513GLSL ES 3.20 specifies the storage available for such variables in terms of 15514an array of 4-vectors. 15515The assumption is that variables will be packed into these arrays without 15516wasting space. 15517This places significant burden on implementations since optimal packing is 15518computationally intensive. 15519Implementations may have more internal resources than exposed to the 15520application and so avoid the need to perform packing but this is also 15521considered an expensive solution.</p> 15522</div> 15523<div class="paragraph"> 15524<p>GLSL ES 3.20 therefore relaxes the requirements for packing by 15525specifying a simpler algorithm that may be used. 15526This algorithm specifies a minimum requirement for when a set of variables 15527must be supported by an implementation. 15528The implementation is allowed to support more than the minimum and so may 15529use a more efficient algorithm and/or may support more registers than the 15530virtual target machine.</p> 15531</div> 15532<div class="paragraph"> 15533<p>Outputs from the last active vertex stage and inputs to the fragment stage are 15534counted separately. 15535If statically used in the fragment shader, the built-in special variables 15536(<em>gl_FragCoord</em>, <em>gl_FrontFacing</em> and <em>gl_PointCoord</em>) are included when 15537calculating the storage requirements of fragment inputs.</p> 15538</div> 15539<div class="paragraph"> 15540<p>If the last active vertex-pipeline shader and fragment shader are linked 15541together, inputs and outputs are only counted if they are statically used 15542within the shader. 15543If the shaders are each compiled into a separable program, all declared inputs 15544and outputs are counted.</p> 15545</div> 15546<div class="admonitionblock note"> 15547<table> 15548<tr> 15549<td class="icon"> 15550<i class="fa icon-note" title="Note"></i> 15551</td> 15552<td class="content"> 15553<div class="title">Note</div> 15554<div class="paragraph"> 15555<p>GLSL ES 3.20 does not require the implementation to remove 15556outputs which are not statically used in the fragment shader.</p> 15557</div> 15558</td> 15559</tr> 15560</table> 15561</div> 15562<div class="paragraph"> 15563<p>For the algorithm used, failing resource allocation for a variable must 15564result in an error.</p> 15565</div> 15566<div class="paragraph"> 15567<p>The resource allocation of variables must succeed for all cases where the 15568following packing algorithm succeeds:</p> 15569</div> 15570<div class="ulist"> 15571<ul> 15572<li> 15573<p>The target architecture consists of a grid of registers, 16 rows by 4 15574columns. 15575Each register can contain a scalar value, i.e. a float, int or uint.</p> 15576</li> 15577<li> 15578<p>Variables with an explicit location are allocated first. 15579When attempting to allocate a location for other variables, if there is 15580a conflict, the search moves to the next available free location.</p> 15581</li> 15582<li> 15583<p>Structures are assumed to be flattened. 15584Each data member is treated as if it were at global scope.</p> 15585</li> 15586<li> 15587<p>Variables are packed into the registers one at a time so that they each 15588occupy a contiguous sub-rectangle. 15589No splitting of variables is permitted.</p> 15590</li> 15591<li> 15592<p>The orientation of variables is fixed. 15593Vectors always occupy registers in a single row. 15594Elements of an array must be in different rows. 15595E.g. <strong>vec4</strong> will always occupy one row; float[16] will occupy one 15596column. 15597Since it is not permitted to split a variable, large arrays e.g. 15598float[32] will always fail with this algorithm.</p> 15599</li> 15600<li> 15601<p>Non-square matrices of type <strong>matCxR</strong> consume the same space as a square 15602matrix of type <strong>matN</strong> where N is the greater of C and R. 15603Variables of type <strong>mat2</strong> occupies 2 complete rows. 15604These rules allow implementations more flexibility in how variables are 15605stored. 15606+ Other variables consume only the minimum space required.</p> 15607</li> 15608<li> 15609<p>Arrays of size N are assumed to take N times the size of the base type.</p> 15610</li> 15611<li> 15612<p>Variables are packed in the following order:</p> 15613<div class="olist arabic"> 15614<ol class="arabic"> 15615<li> 15616<p><strong>mat4</strong> and arrays of <strong>mat4</strong>.</p> 15617</li> 15618<li> 15619<p><strong>mat2</strong> and arrays of <strong>mat2</strong> (since they occupy full rows)</p> 15620</li> 15621<li> 15622<p><strong>vec4</strong> and arrays of <strong>vec4</strong></p> 15623</li> 15624<li> 15625<p><strong>mat3</strong> and arrays of <strong>mat3</strong></p> 15626</li> 15627<li> 15628<p><strong>vec3</strong> and arrays of <strong>vec3</strong></p> 15629</li> 15630<li> 15631<p><strong>vec2</strong> and arrays of <strong>vec2</strong></p> 15632</li> 15633<li> 15634<p>Scalar types and arrays of scalar types</p> 15635</li> 15636</ol> 15637</div> 15638</li> 15639<li> 15640<p>For each of the above types, the arrays are processed in order of size, 15641largest first. 15642Arrays of size 1 and the base type are considered equivalent. 15643The first type to be packed will be mat4[4], mat4[3], mat[2] followed by 15644mat4, mat2[4]…​mat2[2], mat2, vec4[8], vec4[7],…​vec4[1], vec4, 15645mat3[2], mat3 and so on. 15646The last variables to be packed will be float (and float[1]).</p> 15647</li> 15648<li> 15649<p>For 2,3 and 4 component variables packing is started using the 1<sup>st</sup> 15650column of the 1<sup>st</sup> row. 15651Variables are then allocated to successive rows, aligning them to the 156521<sup>st</sup> column.</p> 15653</li> 15654<li> 15655<p>For 2 component variables, when there are no spare rows, the strategy is 15656switched to using the highest numbered row and the lowest numbered 15657column where the variable will fit. 15658(In practice, this means they will be aligned to the x or z component.) 15659Packing of any further 3 or 4 component variables will fail at this 15660point.</p> 15661</li> 15662<li> 15663<p>1 component variables (e.g. floats and arrays of floats) have their own 15664packing rule. 15665They are packed in order of size, largest first. 15666Each variable is placed in the column that leaves the least amount of 15667space in the column and aligned to the lowest available rows within that 15668column. 15669During this phase of packing, space will be available in up to 4 15670columns. 15671The space within each column is always contiguous in the case where no 15672variables have explicit locations.</p> 15673</li> 15674<li> 15675<p>For each type, variables with the 'smooth' property are packed first, 15676followed by variables with the 'flat' property.</p> 15677</li> 15678<li> 15679<p>Each row can contain either values with the 'smooth' property or the 15680'flat' property but not both. 15681If this situation is encountered during allocation, the algorithm skips 15682the component location and continues with the next available location. 15683These skipped locations may be used for other values later in the 15684allocation process.</p> 15685</li> 15686<li> 15687<p>There is no backtracking. 15688Once a value is assigned a location, it cannot be changed, even if such 15689a change is required for a successful allocation.</p> 15690</li> 15691</ul> 15692</div> 15693<div class="paragraph"> 15694<p>Example: pack the following types:</p> 15695</div> 15696<div class="listingblock"> 15697<div class="content"> 15698<pre class="CodeRay highlight"><code data-lang="c++">out vec4 a; <span class="comment">// top left</span> 15699out mat3 b; <span class="comment">// align to left, lowest numbered rows</span> 15700out mat2x3 c; <span class="comment">// same size as mat3, align to left</span> 15701out vec2 d[<span class="integer">6</span>]; <span class="comment">// align to left, lowest numbered rows</span> 15702out vec2 e[<span class="integer">4</span>]; <span class="comment">// Cannot align to left so align to z column, highest</span> 15703 <span class="comment">// numbered rows</span> 15704out vec2 f; <span class="comment">// Align to left, lowest numbered rows.</span> 15705out <span class="predefined-type">float</span> g[<span class="integer">3</span>] <span class="comment">// Column with minimum space</span> 15706out <span class="predefined-type">float</span> h[<span class="integer">2</span>]; <span class="comment">// Column with minimum space (choice of 3, any</span> 15707 <span class="comment">// can be used)</span> 15708out <span class="predefined-type">float</span> i; <span class="comment">// Column with minimum space</span></code></pre> 15709</div> 15710</div> 15711<div class="paragraph"> 15712<p>In this example, the variables happen to be listed in the order in which 15713they are packed. 15714Packing is independent of the order of declaration.</p> 15715</div> 15716<table class="tableblock frame-all grid-all stretch"> 15717<colgroup> 15718<col style="width: 20%;"> 15719<col style="width: 20%;"> 15720<col style="width: 20%;"> 15721<col style="width: 20%;"> 15722<col style="width: 20%;"> 15723</colgroup> 15724<tbody> 15725<tr> 15726<td class="tableblock halign-left valign-top"></td> 15727<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>x</strong></p></td> 15728<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>y</strong></p></td> 15729<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>z</strong></p></td> 15730<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>w</strong></p></td> 15731</tr> 15732<tr> 15733<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> 15734<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>a</strong></p></td> 15735<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>a</strong></p></td> 15736<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>a</strong></p></td> 15737<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>a</strong></p></td> 15738</tr> 15739<tr> 15740<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> 15741<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>b</strong></p></td> 15742<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>b</strong></p></td> 15743<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>b</strong></p></td> 15744<td class="tableblock halign-left valign-top"></td> 15745</tr> 15746<tr> 15747<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> 15748<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>b</strong></p></td> 15749<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>b</strong></p></td> 15750<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>b</strong></p></td> 15751<td class="tableblock halign-left valign-top"></td> 15752</tr> 15753<tr> 15754<td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> 15755<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>b</strong></p></td> 15756<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>b</strong></p></td> 15757<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>b</strong></p></td> 15758<td class="tableblock halign-left valign-top"></td> 15759</tr> 15760<tr> 15761<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> 15762<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>c</strong></p></td> 15763<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>c</strong></p></td> 15764<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>c</strong></p></td> 15765<td class="tableblock halign-left valign-top"></td> 15766</tr> 15767<tr> 15768<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> 15769<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>c</strong></p></td> 15770<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>c</strong></p></td> 15771<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>c</strong></p></td> 15772<td class="tableblock halign-left valign-top"></td> 15773</tr> 15774<tr> 15775<td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> 15776<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>c</strong></p></td> 15777<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>c</strong></p></td> 15778<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>c</strong></p></td> 15779<td class="tableblock halign-left valign-top"></td> 15780</tr> 15781<tr> 15782<td class="tableblock halign-left valign-top"><p class="tableblock">7</p></td> 15783<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15784<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15785<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>g</strong></p></td> 15786<td class="tableblock halign-left valign-top"></td> 15787</tr> 15788<tr> 15789<td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td> 15790<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15791<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15792<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>g</strong></p></td> 15793<td class="tableblock halign-left valign-top"></td> 15794</tr> 15795<tr> 15796<td class="tableblock halign-left valign-top"><p class="tableblock">9</p></td> 15797<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15798<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15799<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>g</strong></p></td> 15800<td class="tableblock halign-left valign-top"></td> 15801</tr> 15802<tr> 15803<td class="tableblock halign-left valign-top"><p class="tableblock">10</p></td> 15804<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15805<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15806<td class="tableblock halign-left valign-top"></td> 15807<td class="tableblock halign-left valign-top"></td> 15808</tr> 15809<tr> 15810<td class="tableblock halign-left valign-top"><p class="tableblock">11</p></td> 15811<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15812<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15813<td class="tableblock halign-left valign-top"></td> 15814<td class="tableblock halign-left valign-top"></td> 15815</tr> 15816<tr> 15817<td class="tableblock halign-left valign-top"><p class="tableblock">12</p></td> 15818<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15819<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>d</strong></p></td> 15820<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>e</strong></p></td> 15821<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>e</strong></p></td> 15822</tr> 15823<tr> 15824<td class="tableblock halign-left valign-top"><p class="tableblock">13</p></td> 15825<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>f</strong></p></td> 15826<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>f</strong></p></td> 15827<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>e</strong></p></td> 15828<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>e</strong></p></td> 15829</tr> 15830<tr> 15831<td class="tableblock halign-left valign-top"><p class="tableblock">14</p></td> 15832<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>h</strong></p></td> 15833<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>i</strong></p></td> 15834<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>e</strong></p></td> 15835<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>e</strong></p></td> 15836</tr> 15837<tr> 15838<td class="tableblock halign-left valign-top"><p class="tableblock">15</p></td> 15839<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>h</strong></p></td> 15840<td class="tableblock halign-left valign-top"></td> 15841<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>e</strong></p></td> 15842<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>e</strong></p></td> 15843</tr> 15844</tbody> 15845</table> 15846<div class="paragraph"> 15847<p>Some types e.g. mat4[8] will be too large to fit. 15848These always fail with this algorithm.</p> 15849</div> 15850</div> 15851</div> 15852<div class="sect1"> 15853<h2 id="acknowledgments">12. Acknowledgments</h2> 15854<div class="sectionbody"> 15855<div class="paragraph"> 15856<p>This specification is based on the work of those who contributed to past 15857versions of the Open GL and Open GL ES Language Specifications and the 15858following contributors to this version:</p> 15859</div> 15860<div class="paragraph"> 15861<p>Acorn Pooley, NVIDIA<br> 15862Alberto Moreira, Qualcomm<br> 15863Aleksandra Krstic, Qualcomm<br> 15864Alon Or-bach, Nokia & Samsung<br> 15865Andrzej Kacprowski, Intel<br> 15866Arzhange Safdarzadeh, Intel<br> 15867Aske Simon Christensen, ARM<br> 15868Avi Shapira, Graphic Remedy<br> 15869Barthold Lichtenbelt, NVIDIA<br> 15870Ben Bowman, Imagination Technologies<br> 15871Ben Brierton, Broadcom<br> 15872Benj Lipchak, Apple<br> 15873Benson Tao, Vivante<br> 15874Bill Licea-Kane, Qualcomm<br> 15875Brent Insko, Intel<br> 15876Brian Murray, Freescale<br> 15877Bruce Merry, ARM<br> 15878Carlos Santa, TI<br> 15879Cass Everitt, Epic Games & NVIDIA<br> 15880Cemil Azizoglu, TI<br> 15881Chang-Hyo Yu, Samsung<br> 15882Chris Dodd, NVIDIA<br> 15883Chris Knox, NVIDIA<br> 15884Chris Tserng, TI<br> 15885Clay Montgomery, TI<br> 15886Daniel Kartch, NVIDIA<br> 15887Daniel Koch, Transgaming& NVIDIA<br> 15888Daoxiang Gong, Imagination Technologies<br> 15889Dave Shreiner, ARM<br> 15890David Garcia, AMD<br> 15891David Jarmon, Vivante<br> 15892Derek Cornish, Epic Games<br> 15893Dominick Witczak, Mobica<br> 15894Eben Upton, Broadcom<br> 15895Ed Plowman, ARM<br> 15896Eisaku Ohbuchi, DMP<br> 15897Elan Lennard, ARM<br> 15898Erik Faye-Lund, ARM<br> 15899Graham Connor, Imagination Technologies<br> 15900Graham Sellers, AMD<br> 15901Greg Roth, NVIDIA<br> 15902Guillaume Portier, Hi Corporation<br> 15903Guofang Jiao, Qualcomm<br> 15904Hans-Martin Will, Vincent<br> 15905Hwanyong Lee, Huone<br> 15906I-Gene Leong, NVIDIA<br> 15907Ian Romanick, Intel<br> 15908Ian South-Dickinson, NVIDIA<br> 15909Ilan Aelion-Exch, Samsung<br> 15910Inkyun Lee, Huone<br> 15911Jacob Strm, Ericsson<br> 15912James Adams, Broadcom<br> 15913James Jones, Imagination Technologies<br> 15914James McCombe, Imagination Technologies<br> 15915Jamie Gennis, Google<br> 15916Jan-Harald Fredriksen, ARM<br> 15917Jani Vaisanen, Nokia<br> 15918Jarkko Kemppainen, Symbio<br> 15919Jeff Bolz, NVIDIA<br> 15920Jeff Leger, Qualcomm<br> 15921Jeff Vigil, Qualcomm<br> 15922Jeremy Sandmel, Apple<br> 15923Jeremy Thorne, Broadcom<br> 15924Jim Hauxwell, Broadcom<br> 15925Jinsung Kim, Huone<br> 15926Jiyoung Yoon, Huone<br> 15927John Kessenich, Google<br> 15928Jon Kennedy, 3DLabs<br> 15929Jon Leech, Khronos<br> 15930Jonathan Putsman, Imagination Technologies<br> 15931Joohoon Lee, Samsung<br> 15932JoukoKylmäoja, Symbio<br> 15933Jrn Nystad, ARM<br> 15934Jussi Rasanen, NVIDIA<br> 15935Kalle Raita, drawElements<br> 15936Kari Pulli, Nokia<br> 15937Keith Whitwell, VMware<br> 15938Kent Miller, Netlogic Microsystems<br> 15939Kimmo Nikkanen, Nokia<br> 15940Konsta Karsisto, Nokia<br> 15941Krzysztof Kaminski, Intel<br> 15942Larry Seiler, Intel<br> 15943Lars Remes, Symbio<br> 15944Lee Thomason, Adobe<br> 15945Lefan Zhong, Vivante<br> 15946Marcus Lorentzon, Ericsson<br> 15947Mark Butler, Imagination Technologies<br> 15948Mark Callow, Hi Corporation<br> 15949Mark Cresswell, Broadcom<br> 15950Mark Snyder, Alt Software<br> 15951Mark Young, AMD<br> 15952Mathieu Robart, STM<br> 15953Matt Netsch, Qualcomm<br> 15954Matt Russo, Matrox<br> 15955Maurice Ribble, Qualcomm<br> 15956Max Kazakov, DMP<br> 15957Mika Pesonen, Nokia<br> 15958Mike Cai, Vivante<br> 15959Mike Weiblen, Zebra Imaging & Qualcomm<br> 15960Mila Smith, AMD<br> 15961Nakhoon Baek, Kyungpook Univeristy<br> 15962Nate Huang, NVIDIA<br> 15963Neil Trevett, NVIDIA<br> 15964Nelson Kidd, Intel<br> 15965Nick Haemel, NVIDIA<br> 15966Nick Penwarden, Epic Games<br> 15967Niklas Smedberg, Epic Games<br> 15968Nizar Romdan, ARM<br> 15969Oliver Wohlmuth , Fujitsu<br> 15970Pat Brown, NVIDIA<br> 15971Paul Ruggieri, Qualcomm<br> 15972Per Wennersten, Ericsson<br> 15973Petri Talala, Symbio<br> 15974Phil Huxley, ZiiLabs<br> 15975Philip Hatcher, Freescale & Intel<br> 15976Piers Daniell, NVIDIA<br> 15977Pyry Haulos, drawElements<br> 15978Piotr Tomaszewski, Ericsson<br> 15979Piotr Uminski, Intel<br> 15980Rami Mayer, Samsung<br> 15981Rauli Laatikainen, RightWare<br> 15982Rob Barris, NVIDIA<br> 15983Rob Simpson, Qualcomm<br> 15984Roj Langhi, Vivante<br> 15985Rune Holm, ARM<br> 15986Sami Kyostila, Nokia<br> 15987Sean Ellis, ARM<br> 15988Shereef Shehata, TI<br> 15989Sila Kayo, Nokia<br> 15990Slawomir Cygan, Intel<br> 15991Slawomir Grajewski, Intel<br> 15992Steve Hill, STM & Broadcom<br> 15993Steven Olney, DMP<br> 15994Suman Sharma, Intel<br> 15995Tapani Palli, Nokia<br> 15996Teemu Laakso, Symbio<br> 15997Tero Karras, NVIDIA<br> 15998Timo Suoranta, Imagination Technologies & Broadcom<br> 15999Tom Cooksey, ARM<br> 16000Tom McReynolds, NVIDIA<br> 16001Tom Olson, TI & ARM<br> 16002Tomi Aarnio, Nokia<br> 16003Tommy Asano, Takumi<br> 16004Wes Bang, Nokia<br> 16005Yanjun Zhang, Vivante</p> 16006</div> 16007</div> 16008</div> 16009<div class="sect1"> 16010<h2 id="references">13. Normative References</h2> 16011<div class="sectionbody"> 16012<div class="olist arabic"> 16013<ol class="arabic"> 16014<li> 16015<p>International Standard ISO/IEC 14882:1998(E). 16016Programming Languages - C++. Referenced for preprocessor only</p> 16017</li> 16018<li> 16019<p>“OpenGL<sup>R</sup> ES, Version 3.2”, 16020<a href="https://www.khronos.org/registry/OpenGL/index_es.php" class="bare">https://www.khronos.org/registry/OpenGL/index_es.php</a>, November 3, 2016.</p> 16021</li> 16022<li> 16023<p>“The OpenGL<sup>R</sup> Graphics System: A Specification, Version 4.6 (Core 16024Profile)”, <a href="https://www.khronos.org/registry/OpenGL/index_gl.php" class="bare">https://www.khronos.org/registry/OpenGL/index_gl.php</a>, June 160251, 2016.</p> 16026</li> 16027<li> 16028<p>International Standard ISO/IEC 646:1991. 16029Information technology - ISO 7-bit coded character set for information 16030interchange</p> 16031</li> 16032<li> 16033<p>The Unicode Standard Version 6.0 - Core Specification.</p> 16034</li> 16035<li> 16036<p>IEEE 754-2008. 16037<em>IEEE Standard for Floating-Point Arithmetic</em></p> 16038</li> 16039<li> 16040<p>“SPIR-V Specification, Version 1.3, Revision 7” , 16041<a href="https://www.khronos.org/registry/spir-v/" class="bare">https://www.khronos.org/registry/spir-v/</a>.</p> 16042</li> 16043<li> 16044<p>“Vulkan<sup>R</sup> 1.1.105 - A Specification”, 16045<a href="https://www.khronos.org/registry/vulkan/" class="bare">https://www.khronos.org/registry/vulkan/</a>, 16046March 19, 2019.</p> 16047</li> 16048</ol> 16049</div> 16050</div> 16051</div> 16052<div class="sect1"> 16053<h2 id="_non_normative_spir_v_mappings">14. Non-Normative SPIR-V Mappings</h2> 16054<div class="sectionbody"> 16055<div class="paragraph"> 16056<p>This appendix includes:</p> 16057</div> 16058<div class="ulist"> 16059<ul> 16060<li> 16061<p>a comparision of feature differences with SPIR-V versus without, for both Vulkan and OpenGL</p> 16062</li> 16063<li> 16064<p>a discussion of how GLSL features logically map to SPIR-V features.</p> 16065</li> 16066</ul> 16067</div> 16068<div class="sect2"> 16069<h3 id="_feature_comparisons">14.1. Feature Comparisons</h3> 16070<div class="paragraph"> 16071<p>The following features are removed for both OpenGL and Vulkan:</p> 16072</div> 16073<div class="ulist"> 16074<ul> 16075<li> 16076<p>subroutines</p> 16077</li> 16078<li> 16079<p>shared and packed block layouts</p> 16080</li> 16081<li> 16082<p>the already deprecated texturing functions (e.g., <code>texture2D()</code>)</p> 16083</li> 16084<li> 16085<p>the already deprecated noise functions (e.g., <code>noise1()</code>)</p> 16086</li> 16087<li> 16088<p>compatibility-profile features</p> 16089</li> 16090<li> 16091<p><em>gl_DepthRangeParameters</em> and <em>gl_NumSamples</em></p> 16092</li> 16093</ul> 16094</div> 16095<div class="paragraph"> 16096<p>Vulkan removed the following features, which are still present for OpenGL:</p> 16097</div> 16098<div class="ulist"> 16099<ul> 16100<li> 16101<p>Default uniforms, for non-opaque types: 16102The <strong>UniformConstant</strong> storage class can be used on individual 16103variables at global scope. (That is, uniforms don’t have to be in a 16104block, unless they are built-in members that are in block in GLSL 16105version 4.5 or above.)</p> 16106</li> 16107<li> 16108<p>GLSL atomic-counter bindings have the <em>offset</em> layout qualifier → 16109SPIR-V <strong>AtomicCounter</strong> storage class using the <strong>Offset</strong> decoration</p> 16110</li> 16111<li> 16112<p>GLSL <em>origin_lower_left</em> → SPIR-V <strong>OriginLowerLeft</strong></p> 16113</li> 16114<li> 16115<p>special rules for locations for input doubles in the vertex shader</p> 16116</li> 16117<li> 16118<p><em>gl_VertexID</em> and <em>gl_InstanceID</em> (more detail follows)</p> 16119</li> 16120</ul> 16121</div> 16122<div class="paragraph"> 16123<p>The following features are added for both OpenGL and Vulkan:</p> 16124</div> 16125<div class="ulist"> 16126<ul> 16127<li> 16128<p>specialization constants</p> 16129</li> 16130<li> 16131<p><em>offset</em> can organize members in a different order than declaration order</p> 16132</li> 16133<li> 16134<p><em>offset</em> and <em>align</em> layout qualifiers for uniform/buffer blocks for 16135versions that did not support them</p> 16136</li> 16137</ul> 16138</div> 16139<div class="paragraph"> 16140<p>Vulkan Only: The following features are added:</p> 16141</div> 16142<div class="ulist"> 16143<ul> 16144<li> 16145<p>push-constant buffers</p> 16146</li> 16147<li> 16148<p>shader combining of separate textures and samplers (SPIR-V <strong>OpTypeSampler</strong>)</p> 16149</li> 16150<li> 16151<p>descriptor sets (<strong>DescriptorSet</strong> must be 0, if present)</p> 16152</li> 16153<li> 16154<p><em>gl_VertexIndex</em> and <em>gl_InstanceIndex</em></p> 16155</li> 16156<li> 16157<p>subpass-input targets and input attachments (<em>input_attachment_index</em>)</p> 16158</li> 16159</ul> 16160</div> 16161<div class="paragraph"> 16162<p>The following features are changed in both OpenGL and Vulkan:</p> 16163</div> 16164<div class="ulist"> 16165<ul> 16166<li> 16167<p><em>gl_FragColor</em> will no longer indicate an implicit broadcast</p> 16168</li> 16169</ul> 16170</div> 16171<div class="paragraph"> 16172<p>Vulkan Only: The following features are changed:</p> 16173</div> 16174<div class="ulist"> 16175<ul> 16176<li> 16177<p>precision qualifiers (<strong>mediump</strong> and <strong>lowp</strong>) will be respected for all 16178versions, not dropped for desktop versions (default precision for 16179desktop versions is <strong>highp</strong> for all types)</p> 16180</li> 16181<li> 16182<p>arrays of uniforms and buffer blocks take only one binding number for 16183the entire object, not one per array element</p> 16184</li> 16185<li> 16186<p>the default origin is <em>origin_upper_left</em> instead of <em>origin_lower_left</em></p> 16187</li> 16188</ul> 16189</div> 16190<div class="paragraph"> 16191<p>Vulkan does not allow multi-dimensional arrays of resources like 16192UBOs and SSBOs in its SPIR-V environment spec. SPIR-V supports 16193it and OpenGL already allows this for GLSL shaders. SPIR-V 16194for OpenGL also allows it.</p> 16195</div> 16196</div> 16197<div class="sect2"> 16198<h3 id="_mapping_from_glsl_to_spir_v">14.2. Mapping from GLSL to SPIR-V</h3> 16199<div class="sect3"> 16200<h4 id="_specialization_constants">14.2.1. Specialization Constants</h4> 16201<div class="paragraph"> 16202<p>SPIR-V specialization constants, which can be set later by the client API, 16203can be declared using <code>layout(constant_id=…​)</code>. For example, to make a 16204specialization constant with a default value of 12:</p> 16205</div> 16206<div class="literalblock"> 16207<div class="content"> 16208<pre>layout(constant_id = 17) const int arraySize = 12;</pre> 16209</div> 16210</div> 16211<div class="paragraph"> 16212<p>Above, <code>17</code> is the ID by which the API or other tools can later refer to 16213this specific specialization constant. The API or an intermediate tool can 16214then change its value to another constant integer before it is fully 16215lowered to executable code. If it is never changed before final lowering, 16216it will retain the value of 12.</p> 16217</div> 16218<div class="paragraph"> 16219<p>Specialization constants have const semantics, except they don’t fold. 16220Hence, an array can be declared with <code>arraySize</code> from above:</p> 16221</div> 16222<div class="literalblock"> 16223<div class="content"> 16224<pre>vec4 data[arraySize]; // legal, even though arraySize might change</pre> 16225</div> 16226</div> 16227<div class="paragraph"> 16228<p>Specialization constants can be in expressions:</p> 16229</div> 16230<div class="literalblock"> 16231<div class="content"> 16232<pre>vec4 data2[arraySize + 2];</pre> 16233</div> 16234</div> 16235<div class="paragraph"> 16236<p>This will make <code>data2</code> be sized by 2 more than whatever constant value 16237<code>arraySize</code> has when it is time to lower the shader to executable code.</p> 16238</div> 16239<div class="paragraph"> 16240<p>An expression formed with specialization constants also behaves in the 16241shader like a specialization constant, not a like a constant.</p> 16242</div> 16243<div class="literalblock"> 16244<div class="content"> 16245<pre>arraySize + 2 // a specialization constant (with no constant_id)</pre> 16246</div> 16247</div> 16248<div class="paragraph"> 16249<p>Such expressions can be used in the same places as a constant.</p> 16250</div> 16251<div class="paragraph"> 16252<p>The <em>constant_id</em> can only be applied to a scalar integer, a scalar floating-point 16253or a scalar Boolean.</p> 16254</div> 16255<div class="paragraph"> 16256<p>Only basic operators and constructors can be applied to a specialization 16257constant and still result in a specialization constant:</p> 16258</div> 16259<div class="literalblock"> 16260<div class="content"> 16261<pre>layout(constant_id = 17) const int arraySize = 12; 16262sin(float(arraySize)); // result is not a specialization constant</pre> 16263</div> 16264</div> 16265<div class="paragraph"> 16266<p>While SPIR-V specialization constants are only for scalars, a vector 16267can be made by operations on scalars:</p> 16268</div> 16269<div class="literalblock"> 16270<div class="content"> 16271<pre>layout(constant_id = 18) const int scX = 1; 16272layout(constant_id = 19) const int scZ = 1; 16273const vec3 scVec = vec3(scX, 1, scZ); // partially specialized vector</pre> 16274</div> 16275</div> 16276<div class="paragraph"> 16277<p>A built-in variable can have a <em>constant_id</em> attached to it:</p> 16278</div> 16279<div class="literalblock"> 16280<div class="content"> 16281<pre>layout(constant_id = 18) gl_MaxImageUnits;</pre> 16282</div> 16283</div> 16284<div class="paragraph"> 16285<p>This makes it behave as a specialization constant. It is not a full 16286redeclaration; all other characteristics are left intact from the 16287original built-in declaration.</p> 16288</div> 16289<div class="paragraph"> 16290<p>The built-in vector <em>gl_WorkGroupSize</em> can be specialized using special 16291layout <code>local_size_{xyz}_id</code> applied to the <strong>in</strong> qualifier. For example:</p> 16292</div> 16293<div class="literalblock"> 16294<div class="content"> 16295<pre>layout(local_size_x_id = 18, local_size_z_id = 19) in;</pre> 16296</div> 16297</div> 16298<div class="paragraph"> 16299<p>This leaves <em>gl_WorkGroupSize.y</em> as a non-specialization constant, with 16300<em>gl_WorkGroupSize</em> being a partially specialized vector. Its <em>x</em> and <em>z</em> 16301components can be later specialized using the ID’s 18 and 19.</p> 16302</div> 16303</div> 16304<div class="sect3"> 16305<h4 id="_vulkan_only_push_constants">14.2.2. Vulkan Only: Push Constants</h4> 16306<div class="paragraph"> 16307<p>Push constants reside in a uniform block declared using the new 16308layout-qualifier-id <em>push_constant</em> applied to a uniform-block declaration. 16309The API writes a set of constants to a push-constant buffer, and the shader 16310reads them from a <em>push_constant</em> block:</p> 16311</div> 16312<div class="literalblock"> 16313<div class="content"> 16314<pre>layout(push_constant) uniform BlockName { 16315 int member1; 16316 float member2; 16317 ... 16318} InstanceName; // optional instance name 16319... = InstanceName.member2; // read a push constant</pre> 16320</div> 16321</div> 16322<div class="paragraph"> 16323<p>The memory accounting used for the <em>push_constant</em> uniform block is different 16324than for other uniform blocks: There is a separate small pool of memory 16325it must fit within. By default, a <em>push_constant</em> buffer follows the std430 16326packing rules.</p> 16327</div> 16328</div> 16329<div class="sect3"> 16330<h4 id="_vulkan_only_descriptor_sets">14.2.3. Vulkan Only: Descriptor Sets</h4> 16331<div class="paragraph"> 16332<p>Each shader resource in a descriptor set is assigned a tuple of (set 16333number, binding number, array element) that defines its location within 16334a descriptor set layout. 16335In GLSL, the set number and binding number are assigned via the <em>set</em> 16336and <em>binding</em> layout qualifiers respectively, and the array element is 16337implicitly assigned consecutively starting with index equal to zero for 16338the first element of an array (and array element is zero for non-array 16339variables):</p> 16340</div> 16341<div class="literalblock"> 16342<div class="content"> 16343<pre>// Assign set number = M, binding number = N, array element = 0 16344layout (set=M, binding=N) uniform sampler2D variableName;</pre> 16345</div> 16346</div> 16347<div class="literalblock"> 16348<div class="content"> 16349<pre>// Assign set number = M, binding number = N for all array elements, 16350// and array element = i for the ith member of an array of size I. 16351layout (set=M, binding=N) uniform sampler2D variableNameArray[I];</pre> 16352</div> 16353</div> 16354<div class="paragraph"> 16355<p>For example, two combined texture/sampler objects can be declared in two 16356different descriptor sets as follows</p> 16357</div> 16358<div class="literalblock"> 16359<div class="content"> 16360<pre>layout(set = 0, binding = 0) uniform sampler2D ts3; 16361layout(set = 1, binding = 0) uniform sampler2D ts4;</pre> 16362</div> 16363</div> 16364<div class="paragraph"> 16365<p>See the API documentation for more detail on the operation model of 16366descriptor sets.</p> 16367</div> 16368</div> 16369<div class="sect3"> 16370<h4 id="_vulkan_only_samplers_images_textures_and_buffers">14.2.4. Vulkan Only: Samplers, Images, Textures, and Buffers</h4> 16371<div class="sect4"> 16372<h5 id="_storage_images">Storage Images</h5> 16373<div class="paragraph"> 16374<p>Storage images are declared in GLSL shader source using uniform image 16375variables of the appropriate dimensionality as well as a format layout 16376qualifier (if necessary):</p> 16377</div> 16378<div class="literalblock"> 16379<div class="content"> 16380<pre>layout (set=m, binding=n, r32f) uniform image2D myStorageImage;</pre> 16381</div> 16382</div> 16383<div class="paragraph"> 16384<p>Which maps to the following SPIR-V:</p> 16385</div> 16386<div class="literalblock"> 16387<div class="content"> 16388<pre> ... 16389%1 = OpExtInstImport "GLSL.std.450" 16390 ... 16391 OpName %9 "myStorageImage" 16392 OpDecorate %9 DescriptorSet m 16393 OpDecorate %9 Binding n 16394%2 = OpTypeVoid 16395%3 = OpTypeFunction %2 16396%6 = OpTypeFloat 32 16397%7 = OpTypeImage %6 2D 0 0 0 2 R32f 16398%8 = OpTypePointer UniformConstant %7 16399%9 = OpVariable %8 UniformConstant 16400 ...</pre> 16401</div> 16402</div> 16403</div> 16404<div class="sect4"> 16405<h5 id="_samplers">Samplers</h5> 16406<div class="paragraph"> 16407<p>SPIR-V samplers are declared in GLSL shader source using uniform <strong>sampler</strong> and 16408<strong>samplerShadow</strong> types:</p> 16409</div> 16410<div class="literalblock"> 16411<div class="content"> 16412<pre>layout (set=m, binding=n) uniform sampler mySampler;</pre> 16413</div> 16414</div> 16415<div class="paragraph"> 16416<p>Which maps to the following SPIR-V:</p> 16417</div> 16418<div class="literalblock"> 16419<div class="content"> 16420<pre> ... 16421%1 = OpExtInstImport "GLSL.std.450" 16422 ... 16423 OpName %8 "mySampler" 16424 OpDecorate %8 DescriptorSet m 16425 OpDecorate %8 Binding n 16426%2 = OpTypeVoid 16427%3 = OpTypeFunction %2 16428%6 = OpTypeSampler 16429%7 = OpTypePointer UniformConstant %6 16430%8 = OpVariable %7 UniformConstant 16431 ...</pre> 16432</div> 16433</div> 16434</div> 16435<div class="sect4"> 16436<h5 id="_textures_sampled_images">Textures (Sampled Images)</h5> 16437<div class="paragraph"> 16438<p>Textures are declared in GLSL shader source using uniform texture 16439variables of the appropriate dimensionality:</p> 16440</div> 16441<div class="literalblock"> 16442<div class="content"> 16443<pre>layout (set=m, binding=n) uniform texture2D mySampledImage;</pre> 16444</div> 16445</div> 16446<div class="paragraph"> 16447<p>Which maps to the following SPIR-V:</p> 16448</div> 16449<div class="literalblock"> 16450<div class="content"> 16451<pre> ... 16452%1 = OpExtInstImport "GLSL.std.450" 16453 ... 16454 OpName %9 "mySampledImage" 16455 OpDecorate %9 DescriptorSet m 16456 OpDecorate %9 Binding n 16457%2 = OpTypeVoid 16458%3 = OpTypeFunction %2 16459%6 = OpTypeFloat 32 16460%7 = OpTypeImage %6 2D 0 0 0 1 Unknown 16461%8 = OpTypePointer UniformConstant %7 16462%9 = OpVariable %8 UniformConstant 16463 ...</pre> 16464</div> 16465</div> 16466</div> 16467<div class="sect4"> 16468<h5 id="_combined_texture_and_samplers">Combined Texture and Samplers</h5> 16469<div class="paragraph"> 16470<p>Combined textures and samplers are declared in GLSL shader source using 16471uniform texture-combined sampler variables of the appropriate dimensionality:</p> 16472</div> 16473<div class="literalblock"> 16474<div class="content"> 16475<pre>layout (set=m, binding=n) uniform sampler2D myCombinedImageSampler;</pre> 16476</div> 16477</div> 16478<div class="paragraph"> 16479<p>Which maps to the following SPIR-V:</p> 16480</div> 16481<div class="literalblock"> 16482<div class="content"> 16483<pre> ... 16484%1 = OpExtInstImport "GLSL.std.450" 16485 ... 16486 OpName %10 "myCombinedImageSampler" 16487 OpDecorate %10 DescriptorSet m 16488 OpDecorate %10 Binding n 16489%2 = OpTypeVoid 16490%3 = OpTypeFunction %2 16491%6 = OpTypeFloat 32 16492%7 = OpTypeImage %6 2D 0 0 0 1 Unknown 16493%8 = OpTypeSampledImage %7 16494%9 = OpTypePointer UniformConstant %8 16495%10 = OpVariable %9 UniformConstant 16496 ...</pre> 16497</div> 16498</div> 16499<div class="paragraph"> 16500<p>Note that a combined image sampler descriptor can be referred to as just 16501an image or sampler in the shader as per the above sections.</p> 16502</div> 16503</div> 16504<div class="sect4"> 16505<h5 id="_combining_separate_samplers_and_textures">Combining Separate Samplers and Textures</h5> 16506<div class="paragraph"> 16507<p>A sampler, declared with the keyword <strong>sampler</strong>, contains just filtering 16508information, containing neither a texture nor an image:</p> 16509</div> 16510<div class="literalblock"> 16511<div class="content"> 16512<pre>uniform sampler s; // a handle to filtering information</pre> 16513</div> 16514</div> 16515<div class="paragraph"> 16516<p>A texture, declared with keywords like <strong>texture2D</strong>, contains just image 16517information, not filtering information:</p> 16518</div> 16519<div class="literalblock"> 16520<div class="content"> 16521<pre>uniform texture2D t; // a handle to a texture (an image in SPIR-V)</pre> 16522</div> 16523</div> 16524<div class="paragraph"> 16525<p>Constructors can then be used to combine a sampler and a texture at the 16526point of making a texture lookup call:</p> 16527</div> 16528<div class="literalblock"> 16529<div class="content"> 16530<pre>texture(sampler2D(t, s), ...);</pre> 16531</div> 16532</div> 16533<div class="paragraph"> 16534<p>Note, <code>layout()</code> information is omitted above for clarity of this feature.</p> 16535</div> 16536</div> 16537<div class="sect4"> 16538<h5 id="_texture_buffers_uniform_texel_buffers">Texture Buffers (Uniform Texel Buffers)</h5> 16539<div class="paragraph"> 16540<p>Texture buffers are declared in GLSL shader source using uniform 16541textureBuffer variables:</p> 16542</div> 16543<div class="literalblock"> 16544<div class="content"> 16545<pre>layout (set=m, binding=n) uniform textureBuffer myUniformTexelBuffer;</pre> 16546</div> 16547</div> 16548<div class="paragraph"> 16549<p>Which maps to the following SPIR-V:</p> 16550</div> 16551<div class="literalblock"> 16552<div class="content"> 16553<pre> ... 16554%1 = OpExtInstImport "GLSL.std.450" 16555 ... 16556 OpName %9 "myUniformTexelBuffer" 16557 OpDecorate %9 DescriptorSet m 16558 OpDecorate %9 Binding n 16559%2 = OpTypeVoid 16560%3 = OpTypeFunction %2 16561%6 = OpTypeFloat 32 16562%7 = OpTypeImage %6 Buffer 0 0 0 1 Unknown 16563%8 = OpTypePointer UniformConstant %7 16564%9 = OpVariable %8 UniformConstant 16565 ...</pre> 16566</div> 16567</div> 16568</div> 16569<div class="sect4"> 16570<h5 id="_image_buffers_storage_texel_buffers">Image Buffers (Storage Texel Buffers)</h5> 16571<div class="paragraph"> 16572<p>Image buffers are declared in GLSL shader source using uniform 16573imageBuffer variables:</p> 16574</div> 16575<div class="literalblock"> 16576<div class="content"> 16577<pre>layout (set=m, binding=n, r32f) uniform imageBuffer myStorageTexelBuffer;</pre> 16578</div> 16579</div> 16580<div class="paragraph"> 16581<p>Which maps to the following SPIR-V:</p> 16582</div> 16583<div class="literalblock"> 16584<div class="content"> 16585<pre> ... 16586%1 = OpExtInstImport "GLSL.std.450" 16587 ... 16588 OpName %9 "myStorageTexelBuffer" 16589 OpDecorate %9 DescriptorSet m 16590 OpDecorate %9 Binding n 16591%2 = OpTypeVoid 16592%3 = OpTypeFunction %2 16593%6 = OpTypeFloat 32 16594%7 = OpTypeImage %6 Buffer 0 0 0 2 R32f 16595%8 = OpTypePointer UniformConstant %7 16596%9 = OpVariable %8 UniformConstant 16597 ...</pre> 16598</div> 16599</div> 16600</div> 16601<div class="sect4"> 16602<h5 id="_storage_buffers">Storage Buffers</h5> 16603<div class="paragraph"> 16604<p>Storage buffers are declared in GLSL shader source using buffer storage 16605qualifier and block syntax:</p> 16606</div> 16607<div class="literalblock"> 16608<div class="content"> 16609<pre>layout (set=m, binding=n) buffer myStorageBuffer 16610{ 16611 vec4 myElement[]; 16612};</pre> 16613</div> 16614</div> 16615<div class="paragraph"> 16616<p>Which maps to the following SPIR-V:</p> 16617</div> 16618<div class="literalblock"> 16619<div class="content"> 16620<pre> ... 16621%1 = OpExtInstImport "GLSL.std.450" 16622 ... 16623 OpName %9 "myStorageBuffer" 16624 OpMemberName %9 0 "myElement" 16625 OpName %11 "" 16626 OpDecorate %8 ArrayStride 16 16627 OpMemberDecorate %9 0 Offset 0 16628 OpDecorate %9 BufferBlock 16629 OpDecorate %11 DescriptorSet m 16630 OpDecorate %11 Binding n 16631%2 = OpTypeVoid 16632%3 = OpTypeFunction %2 16633%6 = OpTypeFloat 32 16634%7 = OpTypeVector %6 4 16635%8 = OpTypeRuntimeArray %7 16636%9 = OpTypeStruct %8 16637%10 = OpTypePointer Uniform %9 16638%11 = OpVariable %10 Uniform 16639 ...</pre> 16640</div> 16641</div> 16642</div> 16643<div class="sect4"> 16644<h5 id="_uniform_buffers">Uniform Buffers</h5> 16645<div class="paragraph"> 16646<p>Uniform buffers are declared in GLSL shader source using the uniform storage 16647qualifier and block syntax:</p> 16648</div> 16649<div class="literalblock"> 16650<div class="content"> 16651<pre>layout (set=m, binding=n) uniform myUniformBuffer 16652{ 16653 vec4 myElement[32]; 16654};</pre> 16655</div> 16656</div> 16657<div class="paragraph"> 16658<p>Which maps to the following SPIR-V:</p> 16659</div> 16660<div class="literalblock"> 16661<div class="content"> 16662<pre> ... 16663%1 = OpExtInstImport "GLSL.std.450" 16664 ... 16665 OpName %11 "myUniformBuffer" 16666 OpMemberName %11 0 "myElement" 16667 OpName %13 "" 16668 OpDecorate %10 ArrayStride 16 16669 OpMemberDecorate %11 0 Offset 0 16670 OpDecorate %11 Block 16671 OpDecorate %13 DescriptorSet m 16672 OpDecorate %13 Binding n 16673%2 = OpTypeVoid 16674%3 = OpTypeFunction %2 16675%6 = OpTypeFloat 32 16676%7 = OpTypeVector %6 4 16677%8 = OpTypeInt 32 0 16678%9 = OpConstant %8 32 16679%10 = OpTypeArray %7 %9 16680%11 = OpTypeStruct %10 16681%12 = OpTypePointer Uniform %11 16682%13 = OpVariable %12 Uniform 16683 ...</pre> 16684</div> 16685</div> 16686</div> 16687<div class="sect4"> 16688<h5 id="_subpass_inputs_2">Subpass Inputs</h5> 16689<div class="paragraph"> 16690<p>Within a rendering pass, a subpass can write results to an output target 16691that can then be read by the next subpass as an input subpass. The 16692"Subpass Input" feature regards the ability to read an output target.</p> 16693</div> 16694<div class="paragraph"> 16695<p>Subpass inputs are read through a new set of types, available only 16696to fragment shaders:</p> 16697</div> 16698<div class="literalblock"> 16699<div class="content"> 16700<pre>subpassInput 16701subpassInputMS 16702isubpassInput 16703isubpassInputMS 16704usubpassInput 16705usubpassInputMS</pre> 16706</div> 16707</div> 16708<div class="paragraph"> 16709<p>Unlike sampler and image objects, subpass inputs are implicitly addressed 16710by the fragment’s (<em>x</em>, <em>y</em>, <em>layer</em>) coordinate.</p> 16711</div> 16712<div class="paragraph"> 16713<p>Input attachments are decorated with their input attachment index in 16714addition to descriptor set and binding numbers.</p> 16715</div> 16716<div class="literalblock"> 16717<div class="content"> 16718<pre>layout (input_attachment_index=i, set=m, binding=n) uniform subpassInput myInputAttachment;</pre> 16719</div> 16720</div> 16721<div class="paragraph"> 16722<p>Which maps to the following SPIR-V:</p> 16723</div> 16724<div class="literalblock"> 16725<div class="content"> 16726<pre> ... 16727%1 = OpExtInstImport "GLSL.std.450" 16728 ... 16729 OpName %9 "myInputAttachment" 16730 OpDecorate %9 DescriptorSet m 16731 OpDecorate %9 Binding n 16732 OpDecorate %9 InputAttachmentIndex i 16733%2 = OpTypeVoid 16734%3 = OpTypeFunction %2 16735%6 = OpTypeFloat 32 16736%7 = OpTypeImage %6 SubpassData 0 0 0 2 Unknown 16737%8 = OpTypePointer UniformConstant %7 16738%9 = OpVariable %8 UniformConstant 16739 ...</pre> 16740</div> 16741</div> 16742<div class="paragraph"> 16743<p>An <em>input_attachment_index</em> of i selects the ith entry in the input pass 16744list. (See API specification for more information.)</p> 16745</div> 16746<div class="paragraph"> 16747<p>These objects support reading the subpass input through the following 16748functions:</p> 16749</div> 16750<div class="literalblock"> 16751<div class="content"> 16752<pre>gvec4 subpassLoad(gsubpassInput subpass); 16753gvec4 subpassLoad(gsubpassInputMS subpass, int sample);</pre> 16754</div> 16755</div> 16756</div> 16757</div> 16758<div class="sect3"> 16759<h4 id="_mapping_variables">14.2.5. Mapping Variables</h4> 16760<div class="sect4"> 16761<h5 id="_gl_fragcolor"><em>gl_FragColor</em></h5> 16762<div class="paragraph"> 16763<p>The fragment-stage built-in <em>gl_FragColor</em>, which implies a broadcast to all 16764outputs, is not present in SPIR-V. Shaders where writing to <em>gl_FragColor</em> 16765is allowed can still write to it, but it only means to write to an output:</p> 16766</div> 16767<div class="ulist"> 16768<ul> 16769<li> 16770<p>of the same type as <em>gl_FragColor</em></p> 16771</li> 16772<li> 16773<p>decorated with location 0</p> 16774</li> 16775<li> 16776<p>not decorated as a built-in variable.</p> 16777</li> 16778</ul> 16779</div> 16780<div class="paragraph"> 16781<p>There is no implicit broadcast.</p> 16782</div> 16783</div> 16784<div class="sect4"> 16785<h5 id="_vulkan_gl_vertexindex_and_gl_instanceindex">Vulkan <em>gl_VertexIndex</em> and <em>gl_InstanceIndex</em></h5> 16786<div class="paragraph"> 16787<p>Adds two new built-in variables, <em>gl_VertexIndex</em> and <em>gl_InstanceIndex</em> to 16788replace the existing built-in variables <em>gl_VertexID</em> and <em>gl_InstanceID</em>.</p> 16789</div> 16790<div class="paragraph"> 16791<p>In the situations where the indexing is relative to some base offset, 16792these built-in variables are defined, for Vulkan, to take on values as 16793follows:</p> 16794</div> 16795<div class="literalblock"> 16796<div class="content"> 16797<pre>gl_VertexIndex base, base+1, base+2, ... 16798gl_InstanceIndex base, base+1, base+2, ...</pre> 16799</div> 16800</div> 16801<div class="paragraph"> 16802<p>Where it depends on the situation what the base actually is.</p> 16803</div> 16804</div> 16805<div class="sect4"> 16806<h5 id="_storage_classes">Storage Classes:</h5> 16807<div class="literalblock"> 16808<div class="content"> 16809<pre>uniform sampler2D...; -> UniformConstant 16810uniform blockN { ... } ...; -> Uniform, with Block decoration 16811in / out variable -> Input/Output, possibly with block (below) 16812in / out block... -> Input/Output, with Block decoration 16813buffer blockN { ... } ...; -> Uniform, with BufferBlock decoration 16814shared -> Workgroup 16815<normal global> -> Private</pre> 16816</div> 16817</div> 16818<div class="literalblock"> 16819<div class="content"> 16820<pre>Vulkan Only: buffer blockN { ... } ...; -> StorageBuffer, when requested 16821OpenGL Only: uniform variable (non-block) -> UniformConstant 16822OpenGL Only: ... uniform atomic_uint ... -> AtomicCounter</pre> 16823</div> 16824</div> 16825</div> 16826<div class="sect4"> 16827<h5 id="_inputoutput">Input/Output</h5> 16828<div class="paragraph"> 16829<p>Mapping of input/output blocks or variables is the same for all versions 16830of GLSL or ESSL. To the extent variables or members are available in a 16831version, its location is as follows:</p> 16832</div> 16833<div class="paragraph"> 16834<p>These are mapped to SPIR-V individual variables, with similarly spelled 16835built-in decorations (except as noted):</p> 16836</div> 16837<div class="paragraph"> 16838<p>Any stage:</p> 16839</div> 16840<div class="literalblock"> 16841<div class="content"> 16842<pre>in gl_VertexIndex (Vulkan only) 16843in gl_VertexID (OpenGL only) 16844in gl_InstanceIndex (Vulkan only) 16845in gl_InstanceID (OpenGL only) 16846in gl_InvocationID 16847in gl_PatchVerticesIn (PatchVertices) 16848in gl_PrimitiveIDIn (PrimitiveID) 16849in/out gl_PrimitiveID (in/out based only on storage qualifier) 16850in gl_TessCoord</pre> 16851</div> 16852</div> 16853<div class="literalblock"> 16854<div class="content"> 16855<pre>in/out gl_Layer 16856in/out gl_ViewportIndex</pre> 16857</div> 16858</div> 16859<div class="literalblock"> 16860<div class="content"> 16861<pre>patch in/out gl_TessLevelOuter (uses Patch decoration) 16862patch in/out gl_TessLevelInner (uses Patch decoration)</pre> 16863</div> 16864</div> 16865<div class="paragraph"> 16866<p>Compute stage only:</p> 16867</div> 16868<div class="literalblock"> 16869<div class="content"> 16870<pre>in gl_NumWorkGroups 16871in gl_WorkGroupSize 16872in gl_WorkGroupID 16873in gl_LocalInvocationID 16874in gl_GlobalInvocationID 16875in gl_LocalInvocationIndex</pre> 16876</div> 16877</div> 16878<div class="paragraph"> 16879<p>Fragment stage only:</p> 16880</div> 16881<div class="literalblock"> 16882<div class="content"> 16883<pre>in gl_FragCoord 16884in gl_FrontFacing 16885in gl_ClipDistance 16886in gl_CullDistance 16887in gl_PointCoord 16888in gl_SampleID 16889in gl_SamplePosition 16890in gl_HelperInvocation 16891out gl_FragDepth 16892in gl_SampleMaskIn (SampleMask) 16893out gl_SampleMask (in/out based only on storage qualifier)</pre> 16894</div> 16895</div> 16896<div class="paragraph"> 16897<p>These are mapped to SPIR-V blocks, as implied by the pseudo code, with 16898the members decorated with similarly spelled built-in decorations:</p> 16899</div> 16900<div class="paragraph"> 16901<p>Non-fragment stage:</p> 16902</div> 16903<div class="literalblock"> 16904<div class="content"> 16905<pre>in/out gl_PerVertex { // some subset of these members will be used 16906 gl_Position 16907 gl_PointSize 16908 gl_ClipDistance 16909 gl_CullDistance 16910} // name of block is for debug only</pre> 16911</div> 16912</div> 16913<div class="paragraph"> 16914<p>There is at most one input and one output block per stage in SPIR-V. 16915The subset and order of members will match between stages sharing an 16916interface.</p> 16917</div> 16918</div> 16919</div> 16920<div class="sect3"> 16921<h4 id="_vulkan_only_mapping_of_precision_qualifiers">14.2.6. Vulkan Only: Mapping of Precision Qualifiers</h4> 16922<div class="literalblock"> 16923<div class="content"> 16924<pre>lowp -> RelaxedPrecision, on storage variable and operation 16925mediump -> RelaxedPrecision, on storage variable and operation 16926highp -> 32-bit, same as int or float</pre> 16927</div> 16928</div> 16929<div class="literalblock"> 16930<div class="content"> 16931<pre>portability tool/mode -> OpQuantizeToF16</pre> 16932</div> 16933</div> 16934</div> 16935<div class="sect3"> 16936<h4 id="_mapping_of_precise">14.2.7. Mapping of <strong>precise</strong>:</h4> 16937<div class="literalblock"> 16938<div class="content"> 16939<pre>precise -> NoContraction</pre> 16940</div> 16941</div> 16942</div> 16943<div class="sect3"> 16944<h4 id="_opengl_mapping_of_atomic_uint_offset_layout_qualifier">14.2.8. OpenGL Mapping of <strong>atomic_uint</strong> <em>offset</em> layout qualifier</h4> 16945<div class="literalblock"> 16946<div class="content"> 16947<pre>offset -> Offset (decoration)</pre> 16948</div> 16949</div> 16950</div> 16951<div class="sect3"> 16952<h4 id="_mapping_of_images">14.2.9. Mapping of Images</h4> 16953<div class="literalblock"> 16954<div class="content"> 16955<pre>imageLoad() -> OpImageRead 16956imageStore() -> OpImageWrite 16957texelFetch() -> OpImageFetch 16958subpassInput -> OpTypeImage with Dim of SubpassData (Vulkan only) 16959subpassLoad() -> OpImageRead (Vulkan only)</pre> 16960</div> 16961</div> 16962<div class="literalblock"> 16963<div class="content"> 16964<pre>imageAtomicXXX(params, data) -> %ptr = OpImageTexelPointer params 16965 OpAtomicXXX %ptr, data</pre> 16966</div> 16967</div> 16968<div class="literalblock"> 16969<div class="content"> 16970<pre>XXXQueryXXX(combined) -> %image = OpImage combined 16971 OpXXXQueryXXX %image</pre> 16972</div> 16973</div> 16974</div> 16975<div class="sect3"> 16976<h4 id="_mapping_of_layouts">14.2.10. Mapping of Layouts</h4> 16977<div class="literalblock"> 16978<div class="content"> 16979<pre>std140/std430 -> explicit Offset, ArrayStride, and MatrixStride 16980 Decoration on struct members 16981shared/packed -> not allowed 16982<default> -> not shared, but std140 or std430 16983xfb_offset -> Offset Decoration on the object or struct member 16984xfb_buffer -> XfbBuffer Decoration on the object 16985xfb_stride -> XfbStride Decoration on the object 16986any xfb_* -> the Xfb Execution Mode is set 16987captured XFB -> has both XfbBuffer and Offset 16988non-captured -> lacking XfbBuffer or Offset</pre> 16989</div> 16990</div> 16991<div class="literalblock"> 16992<div class="content"> 16993<pre>max_vertices -> OutputVertices</pre> 16994</div> 16995</div> 16996</div> 16997<div class="sect3"> 16998<h4 id="_mapping_of_barriers">14.2.11. Mapping of barriers</h4> 16999<div class="literalblock"> 17000<div class="content"> 17001<pre>barrier() (compute) -> OpControlBarrier(/*Execution*/Workgroup, 17002 /*Memory*/Workgroup, 17003 /*Semantics*/AcquireRelease | 17004 WorkgroupMemory)</pre> 17005</div> 17006</div> 17007<div class="literalblock"> 17008<div class="content"> 17009<pre>barrier() (tess control) -> OpControlBarrier(/*Execution*/Workgroup, 17010 /*Memory*/Invocation, 17011 /*Semantics*/None)</pre> 17012</div> 17013</div> 17014<div class="literalblock"> 17015<div class="content"> 17016<pre>memoryBarrier() -> OpMemoryBarrier(/*Memory*/Device, 17017 /*Semantics*/AcquireRelease | 17018 UniformMemory | 17019 WorkgroupMemory | 17020 ImageMemory)</pre> 17021</div> 17022</div> 17023<div class="literalblock"> 17024<div class="content"> 17025<pre>memoryBarrierBuffer() -> OpMemoryBarrier(/*Memory*/Device, 17026 /*Semantics*/AcquireRelease | 17027 UniformMemory)</pre> 17028</div> 17029</div> 17030<div class="literalblock"> 17031<div class="content"> 17032<pre>memoryBarrierShared() -> OpMemoryBarrier(/*Memory*/Device, 17033 /*Semantics*/AcquireRelease | 17034 WorkgroupMemory)</pre> 17035</div> 17036</div> 17037<div class="literalblock"> 17038<div class="content"> 17039<pre>memoryBarrierImage() -> OpMemoryBarrier(/*Memory*/Device, 17040 /*Semantics*/AcquireRelease | 17041 ImageMemory)</pre> 17042</div> 17043</div> 17044<div class="literalblock"> 17045<div class="content"> 17046<pre>groupMemoryBarrier() -> OpMemoryBarrier(/*Memory*/Workgroup, 17047 /*Semantics*/AcquireRelease | 17048 UniformMemory | 17049 WorkgroupMemory | 17050 ImageMemory)</pre> 17051</div> 17052</div> 17053</div> 17054<div class="sect3"> 17055<h4 id="_mapping_of_atomics">14.2.12. Mapping of atomics</h4> 17056<div class="literalblock"> 17057<div class="content"> 17058<pre>all atomic builtin functions -> Semantics = None(Relaxed)</pre> 17059</div> 17060</div> 17061<div class="literalblock"> 17062<div class="content"> 17063<pre>atomicExchange() -> OpAtomicExchange 17064imageAtomicExchange() -> OpAtomicExchange 17065atomicCompSwap() -> OpAtomicCompareExchange 17066imageAtomicCompSwap() -> OpAtomicCompareExchange 17067N/A -> OpAtomicCompareExchangeWeak</pre> 17068</div> 17069</div> 17070</div> 17071<div class="sect3"> 17072<h4 id="_opengl_only_mapping_of_atomics">14.2.13. OpenGL Only: Mapping of Atomics</h4> 17073<div class="literalblock"> 17074<div class="content"> 17075<pre>atomicCounterIncrement -> OpAtomicIIncrement 17076atomicCounterDecrement -> OpAtomicIDecrement 17077atomicCounter -> OpAtomicLoad</pre> 17078</div> 17079</div> 17080</div> 17081<div class="sect3"> 17082<h4 id="_mapping_of_other_instructions">14.2.14. Mapping of other instructions</h4> 17083<div class="literalblock"> 17084<div class="content"> 17085<pre>% -> OpUMod/OpSMod 17086mod() -> OpFMod 17087N/A -> OpSRem/OpFRem</pre> 17088</div> 17089</div> 17090<div class="literalblock"> 17091<div class="content"> 17092<pre>pack/unpack (conversion) -> pack/unpack in GLSL extended instructions 17093pack/unpack (no conversion) -> OpBitcast</pre> 17094</div> 17095</div> 17096</div> 17097</div> 17098</div> 17099</div> 17100</div> 17101<div id="footer"> 17102<div id="footer-text"> 17103Version 3.20.6<br> 17104Last updated 2019-07-10 14:42:53 MDT 17105</div> 17106</div> 17107 17108<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js?config=TeX-MML-AM_HTMLorMML"></script> 17109</body> 17110</html>