shading.html revision 8f9db0f81c13c3244f07333f33a15bfe098e0f31
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> 18Last updated on 17 Feb 2007. 19</p> 20 21<p> 22Contents 23</p> 24<ul> 25<li><a href="#unsup">Unsupported Features</a> 26<li><a href="#notes">Implementation Notes</a> 27<li><a href="#hints">Programming Hints</a> 28<li><a href="#standalone">Stand-alone Compiler</a> 29<li><a href="#implementation">Compiler Implementation</a> 30</ul> 31 32 33<a name="unsup"> 34<h2>Unsupported Features</h2> 35 36<p> 37The following features of the shading language are not yet supported 38in Mesa: 39</p> 40 41<ul> 42<li>Dereferencing arrays with non-constant indexes 43<li>User-defined structs 44<li>Linking of multiple shaders is not supported 45<li>Integer operations are not fully implemented (most are implemented 46 as floating point). 47<li>gl_ClipVertex 48</ul> 49 50<p> 51All other major features of the shading language should function. 52</p> 53 54 55<a name="notes"> 56<h2>Implementation Notes</h2> 57 58<ul> 59<li>Shading language programs are compiled into low-level programs 60 very similar to those of GL_ARB_vertex/fragment_program. 61<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full 62 float[4] registers. 63<li>Float constants and variables are packed so that up to four floats 64 can occupy one program parameter/register. 65<li>All function calls are inlined. 66<li>Shaders which use too many registers will not compile. 67<li>The quality of generated code is pretty good, register usage is fair. 68<li>Shader error detection and reporting of errors (InfoLog) is not 69 very good yet. 70<li>There are known memory leaks in the compiler. 71</ul> 72 73<p> 74These issues will be addressed/resolved in the future. 75</p> 76 77 78<a name="hints"> 79<h2>Programming Hints</h2> 80 81<ul> 82<li>Declare <em>in</em> function parameters as <em>const</em> whenever possible. 83 This improves the efficiency of function inlining. 84</li> 85<br> 86<li>To reduce register usage, declare variables within smaller scopes. 87 For example, the following code: 88<pre> 89 void main() 90 { 91 vec4 a1, a2, b1, b2; 92 gl_Position = expression using a1, a2. 93 gl_Color = expression using b1, b2; 94 } 95</pre> 96 Can be rewritten as follows to use half as many registers: 97<pre> 98 void main() 99 { 100 { 101 vec4 a1, a2; 102 gl_Position = expression using a1, a2. 103 } 104 { 105 vec4 b1, b2; 106 gl_Color = expression using b1, b2; 107 } 108 } 109</pre> 110 Alternately, rather than using several float variables, use 111 a vec4 instead. Use swizzling and writemasks to access the 112 components of the vec4 as floats. 113</li> 114<br> 115<li>Use the built-in library functions whenever possible. 116 For example, instead of writing this: 117<pre> 118 float x = 1.0 / sqrt(y); 119</pre> 120 Write this: 121<pre> 122 float x = inversesqrt(y); 123</pre> 124</ul> 125 126 127<a name="standalone"> 128<h2>Stand-alone Compiler</h2> 129 130<p> 131A unique stand-alone GLSL compiler driver has been added to Mesa. 132<p> 133 134<p> 135The stand-alone compiler (like a conventional command-line compiler) 136is a tool that accepts Shading Language programs and emits low-level 137GPU programs. 138</p> 139 140<p> 141This tool is useful for: 142<p> 143<ul> 144<li>Inspecting GPU code to gain insight into compilation 145<li>Generating initial GPU code for subsequent hand-tuning 146<li>Debugging the GLSL compiler itself 147</ul> 148 149<p> 150To build the glslcompiler program (this will be improved someday): 151</p> 152<pre> 153 cd src/mesa 154 make libmesa.a 155 cd drivers/glslcompiler 156 make 157</pre> 158 159 160<p> 161Here's an example of using the compiler to compile a vertex shader and 162emit GL_ARB_vertex_program-style instructions: 163</p> 164<pre> 165 glslcompiler --arb --linenumbers --vs vertshader.txt 166</pre> 167<p> 168The output may look similar to this: 169</p> 170<pre> 171!!ARBvp1.0 172 0: MOV result.texcoord[0], vertex.texcoord[0]; 173 1: DP4 temp0.x, state.matrix.mvp.row[0], vertex.position; 174 2: DP4 temp0.y, state.matrix.mvp.row[1], vertex.position; 175 3: DP4 temp0.z, state.matrix.mvp.row[2], vertex.position; 176 4: DP4 temp0.w, state.matrix.mvp.row[3], vertex.position; 177 5: MOV result.position, temp0; 178 6: END 179</pre> 180 181<p> 182Note that some shading language constructs (such as uniform and varying 183variables) aren't expressible in ARB or NV-style programs. 184Therefore, the resulting output is not always legal by definition of 185those program languages. 186</p> 187<p> 188Also note that this compiler driver is still under development. 189Over time, the correctness of the GPU programs, with respect to the ARB 190and NV languagues, should improve. 191</p> 192 193 194 195<a name="implementation"> 196<h2>Compiler Implementation</h2> 197 198<p> 199The source code for Mesa's shading language compiler is in the 200<code>src/mesa/shader/slang/</code> directory. 201</p> 202 203<p> 204The compiler follows a fairly standard design and basically works as follows: 205</p> 206<ul> 207<li>The input string is tokenized (see grammar.c) and parsed 208(see slang_compiler_*.c) to produce an Abstract Syntax Tree (AST). 209The nodes in this tree are slang_operation structures 210(see slang_compile_operation.h). 211The nodes are decorated with symbol table, scoping and datatype information. 212<li>The AST is converted into an Intermediate representation (IR) tree 213(see the slang_codegen.c file). 214The IR nodes represent basic GPU instructions, like add, dot product, 215move, etc. 216The IR tree is mostly a binary tree, but a few nodes have three or four 217children. 218In principle, the IR tree could be executed by doing an in-order traversal. 219<li>The IR tree is traversed in-order to emit code (see slang_emit.c). 220This is also when registers are allocated to store variables and temps. 221<li>In the future, a pattern-matching code generator-generator may be 222used for code generation. 223Programs such as L-BURG (Bottom-Up Rewrite Generator) and Twig look for 224patterns in IR trees, compute weights for subtrees and use the weights 225to select the best instructions to represent the sub-tree. 226<li>The emitted GPU instructions (see prog_instruction.h) are stored in a 227gl_program object (see mtypes.h). 228<li>When a fragment shader and vertex shader are linked (see slang_link.c) 229the varying vars are matched up, uniforms are merged, and vertex 230attributes are resolved (rewriting instructions as needed). 231</ul> 232 233<p> 234The final vertex and fragment programs may be interpreted in software 235(see prog_execute.c) or translated into a specific hardware architecture 236(see drivers/dri/i915/i915_fragprog.c for example). 237</p> 238 239<h3>Code Generation Options</h3> 240 241<p> 242Internally, there are several options that control the compiler's code 243generation and instruction selection. 244These options are seen in the gl_shader_state struct and may be set 245by the device driver to indicate its preferences: 246 247<pre> 248struct gl_shader_state 249{ 250 ... 251 /** Driver-selectable options: */ 252 GLboolean EmitHighLevelInstructions; 253 GLboolean EmitCondCodes; 254 GLboolean EmitComments; 255}; 256</pre> 257 258<ul> 259<li>EmitHighLevelInstructions 260<br> 261This option controls instruction selection for loops and conditionals. 262If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK 263instructions will be emitted. 264Otherwise, those constructs will be implemented with BRA instructions. 265</li> 266 267<li>EmitCondCodes 268<br> 269If set, condition codes (ala GL_NV_fragment_program) will be used for 270branching and looping. 271Otherwise, ordinary registers will be used (the IF instruction will 272examine the first operand's X component and do the if-part if non-zero). 273This option is only relevant if EmitHighLevelInstructions is set. 274</li> 275 276<li>EmitComments 277<br> 278If set, instructions will be annoted with comments to help with debugging. 279Extra NOP instructions will also be inserted. 280</br> 281 282</ul> 283 284 285</BODY> 286</HTML> 287