1<HTML> 2 3<TITLE>Shading Language Support</TITLE> 4 5<link rel="stylesheet" type="text/css" href="mesa.css"></head> 6 7<BODY> 8 9<H1>Shading Language Support</H1> 10 11<p> 12This page describes the features and status of Mesa's support for the 13<a href="http://opengl.org/documentation/glsl/" target="_parent"> 14OpenGL Shading Language</a>. 15</p> 16 17<p> 18Contents 19</p> 20<ul> 21<li><a href="#envvars">Environment variables</a> 22<li><a href="#120">GLSL 1.20 support</a> 23<li><a href="#unsup">Unsupported Features</a> 24<li><a href="#notes">Implementation Notes</a> 25<li><a href="#hints">Programming Hints</a> 26<li><a href="#standalone">Stand-alone GLSL Compiler</a> 27<li><a href="#implementation">Compiler Implementation</a> 28<li><a href="#validation">Compiler Validation</a> 29</ul> 30 31 32 33<a name="envvars"> 34<h2>Environment Variables</h2> 35 36<p> 37The <b>MESA_GLSL</b> environment variable can be set to a comma-separated 38list of keywords to control some aspects of the GLSL compiler and shader 39execution. These are generally used for debugging. 40</p> 41<ul> 42<li><b>dump</b> - print GLSL shader code to stdout at link time 43<li><b>log</b> - log all GLSL shaders to files. 44 The filenames will be "shader_X.vert" or "shader_X.frag" where X 45 the shader ID. 46<li><b>nopt</b> - disable compiler optimizations 47<li><b>opt</b> - force compiler optimizations 48<li><b>uniform</b> - print message to stdout when glUniform is called 49<li><b>nopvert</b> - force vertex shaders to be a simple shader that just transforms 50 the vertex position with ftransform() and passes through the color and 51 texcoord[0] attributes. 52<li><b>nopfrag</b> - force fragment shader to be a simple shader that passes 53 through the color attribute. 54<li><b>useprog</b> - log glUseProgram calls to stderr 55</ul> 56<p> 57Example: export MESA_GLSL=dump,nopt 58</p> 59 60 61<a name="120"> 62<h2>GLSL Version</h2> 63 64<p> 65The GLSL compiler currently supports version 1.20 of the shading language. 66</p> 67 68<p> 69Several GLSL extensions are also supported: 70</p> 71<ul> 72<li>GL_ARB_draw_buffers 73<li>GL_ARB_texture_rectangle 74<li>GL_ARB_fragment_coord_conventions 75<li>GL_EXT_texture_array 76</ul> 77 78 79<a name="unsup"> 80<h2>Unsupported Features</h2> 81 82<p>XXX update this section</p> 83 84<p> 85The following features of the shading language are not yet fully supported 86in Mesa: 87</p> 88 89<ul> 90<li>Linking of multiple shaders does not always work. Currently, linking 91 is implemented through shader concatenation and re-compiling. This 92 doesn't always work because of some #pragma and preprocessor issues. 93<li>gl_ClipVertex 94<li>The gl_Color and gl_SecondaryColor varying vars are interpolated 95 without perspective correction 96</ul> 97 98<p> 99All other major features of the shading language should function. 100</p> 101 102 103<a name="notes"> 104<h2>Implementation Notes</h2> 105 106<ul> 107<li>Shading language programs are compiled into low-level programs 108 very similar to those of GL_ARB_vertex/fragment_program. 109<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full 110 float[4] registers. 111<li>Float constants and variables are packed so that up to four floats 112 can occupy one program parameter/register. 113<li>All function calls are inlined. 114<li>Shaders which use too many registers will not compile. 115<li>The quality of generated code is pretty good, register usage is fair. 116<li>Shader error detection and reporting of errors (InfoLog) is not 117 very good yet. 118<li>The ftransform() function doesn't necessarily match the results of 119 fixed-function transformation. 120</ul> 121 122<p> 123These issues will be addressed/resolved in the future. 124</p> 125 126 127<a name="hints"> 128<h2>Programming Hints</h2> 129 130<ul> 131<li>Use the built-in library functions whenever possible. 132 For example, instead of writing this: 133<pre> 134 float x = 1.0 / sqrt(y); 135</pre> 136 Write this: 137<pre> 138 float x = inversesqrt(y); 139</pre> 140</li> 141</ul> 142 143 144<a name="standalone"> 145<h2>Stand-alone GLSL Compiler</h2> 146 147<p> 148The stand-alone GLSL compiler program can be used to compile GLSL shaders 149into low-level GPU code. 150</p> 151 152<p> 153This tool is useful for: 154<p> 155<ul> 156<li>Inspecting GPU code to gain insight into compilation 157<li>Generating initial GPU code for subsequent hand-tuning 158<li>Debugging the GLSL compiler itself 159</ul> 160 161<p> 162After building Mesa, the compiler can be found at src/glsl/glsl_compiler 163</p> 164 165<p> 166Here's an example of using the compiler to compile a vertex shader and 167emit GL_ARB_vertex_program-style instructions: 168</p> 169<pre> 170 src/glsl/glslcompiler --dump-ast myshader.vert 171</pre> 172 173Options include 174<ul> 175<li><b>--dump-ast</b> - dump GPU code 176<li><b>--dump-hir</b> - dump high-level IR code 177<li><b>--dump-lir</b> - dump low-level IR code 178<li><b>--link</b> - ??? 179</ul> 180 181 182 183 184<a name="implementation"> 185<h2>Compiler Implementation</h2> 186 187<p> 188The source code for Mesa's shading language compiler is in the 189<code>src/glsl/</code> directory. 190</p> 191 192<p> 193XXX provide some info about the compiler.... 194</p> 195 196<p> 197The final vertex and fragment programs may be interpreted in software 198(see prog_execute.c) or translated into a specific hardware architecture 199(see drivers/dri/i915/i915_fragprog.c for example). 200</p> 201 202<h3>Code Generation Options</h3> 203 204<p> 205Internally, there are several options that control the compiler's code 206generation and instruction selection. 207These options are seen in the gl_shader_state struct and may be set 208by the device driver to indicate its preferences: 209 210<pre> 211struct gl_shader_state 212{ 213 ... 214 /** Driver-selectable options: */ 215 GLboolean EmitHighLevelInstructions; 216 GLboolean EmitCondCodes; 217 GLboolean EmitComments; 218}; 219</pre> 220 221<ul> 222<li>EmitHighLevelInstructions 223<br> 224This option controls instruction selection for loops and conditionals. 225If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK 226instructions will be emitted. 227Otherwise, those constructs will be implemented with BRA instructions. 228</li> 229 230<li>EmitCondCodes 231<br> 232If set, condition codes (ala GL_NV_fragment_program) will be used for 233branching and looping. 234Otherwise, ordinary registers will be used (the IF instruction will 235examine the first operand's X component and do the if-part if non-zero). 236This option is only relevant if EmitHighLevelInstructions is set. 237</li> 238 239<li>EmitComments 240<br> 241If set, instructions will be annoted with comments to help with debugging. 242Extra NOP instructions will also be inserted. 243</br> 244 245</ul> 246 247 248<a name="validation"> 249<h2>Compiler Validation</h2> 250 251<p> 252Developers working on the GLSL compiler should test frequently to avoid 253regressions. 254</p> 255 256<p> 257The <a href="http://people.freedesktop.org/~nh/piglit/">Piglit</a> project 258has many GLSL tests and the 259<a href="http://glean.sf.net" target="_parent">Glean</a> glsl1 test 260tests GLSL features. 261</p> 262 263<p> 264The Mesa demos repository also has some good GLSL tests. 265</p> 266 267</BODY> 268</HTML> 269