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> 12 This page describes the features and status of Mesa's support for the 13 <a href="http://opengl.org/documentation/glsl/" target="_parent"> 14 OpenGL Shading Language</a>. 15 </p> 16 17 <p> 18 Contents 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> 37 The <b>MESA_GLSL</b> environment variable can be set to a comma-separated 38 list of keywords to control some aspects of the GLSL compiler and shader 39 execution. 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> 57 Example: export MESA_GLSL=dump,nopt 58 </p> 59 60 61 <a name="120"> 62 <h2>GLSL Version</h2> 63 64 <p> 65 The GLSL compiler currently supports version 1.20 of the shading language. 66 </p> 67 68 <p> 69 Several 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> 85 The following features of the shading language are not yet fully supported 86 in 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> 99 All 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> 123 These 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> 148 The stand-alone GLSL compiler program can be used to compile GLSL shaders 149 into low-level GPU code. 150 </p> 151 152 <p> 153 This 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> 162 After building Mesa, the compiler can be found at src/glsl/glsl_compiler 163 </p> 164 165 <p> 166 Here's an example of using the compiler to compile a vertex shader and 167 emit GL_ARB_vertex_program-style instructions: 168 </p> 169 <pre> 170 src/glsl/glslcompiler --dump-ast myshader.vert 171 </pre> 172 173 Options 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> 188 The source code for Mesa's shading language compiler is in the 189 <code>src/glsl/</code> directory. 190 </p> 191 192 <p> 193 XXX provide some info about the compiler.... 194 </p> 195 196 <p> 197 The 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> 205 Internally, there are several options that control the compiler's code 206 generation and instruction selection. 207 These options are seen in the gl_shader_state struct and may be set 208 by the device driver to indicate its preferences: 209 210 <pre> 211 struct 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> 224 This option controls instruction selection for loops and conditionals. 225 If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK 226 instructions will be emitted. 227 Otherwise, those constructs will be implemented with BRA instructions. 228 </li> 229 230 <li>EmitCondCodes 231 <br> 232 If set, condition codes (ala GL_NV_fragment_program) will be used for 233 branching and looping. 234 Otherwise, ordinary registers will be used (the IF instruction will 235 examine the first operand's X component and do the if-part if non-zero). 236 This option is only relevant if EmitHighLevelInstructions is set. 237 </li> 238 239 <li>EmitComments 240 <br> 241 If set, instructions will be annoted with comments to help with debugging. 242 Extra 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> 252 Developers working on the GLSL compiler should test frequently to avoid 253 regressions. 254 </p> 255 256 <p> 257 The <a href="http://people.freedesktop.org/~nh/piglit/">Piglit</a> project 258 has many GLSL tests and the 259 <a href="http://glean.sf.net" target="_parent">Glean</a> glsl1 test 260 tests GLSL features. 261 </p> 262 263 <p> 264 The Mesa demos repository also has some good GLSL tests. 265 </p> 266 267 </BODY> 268 </HTML> 269
