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