docs/shading.html

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