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
  67 <h2 id="support">GLSL Version</h2>
  68
  69 <p>
  70 The GLSL compiler currently supports version 3.30 of the shading language.
  71 </p>
  72
  73 <p>
  74 Several GLSL extensions are also supported:
  75 </p>
  76 <ul>
  77 <li>GL_ARB_draw_buffers
  78 <li>GL_ARB_fragment_coord_conventions
  79 <li>GL_ARB_shader_bit_encoding
  80 </ul>
  81
  82
  83 <h2 id="unsup">Unsupported Features</h2>
  84
  85 <p>XXX update this section</p>
  86
  87 <p>
  88 The following features of the shading language are not yet fully supported
  89 in Mesa:
  90 </p>
  91
  92 <ul>
  93 <li>Linking of multiple shaders does not always work.  Currently, linking
  94     is implemented through shader concatenation and re-compiling.  This
  95     doesn't always work because of some #pragma and preprocessor issues.
  96 <li>The gl_Color and gl_SecondaryColor varying vars are interpolated
  97     without perspective correction
  98 </ul>
  99
 100 <p>
 101 All other major features of the shading language should function.
 102 </p>
 103
 104
 105 <h2 id="notes">Implementation Notes</h2>
 106
 107 <ul>
 108 <li>Shading language programs are compiled into low-level programs
 109     very similar to those of GL_ARB_vertex/fragment_program.
 110 <li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
 111     float[4] registers.
 112 <li>Float constants and variables are packed so that up to four floats
 113     can occupy one program parameter/register.
 114 <li>All function calls are inlined.
 115 <li>Shaders which use too many registers will not compile.
 116 <li>The quality of generated code is pretty good, register usage is fair.
 117 <li>Shader error detection and reporting of errors (InfoLog) is not
 118     very good yet.
 119 <li>The ftransform() function doesn't necessarily match the results of
 120     fixed-function transformation.
 121 </ul>
 122
 123 <p>
 124 These issues will be addressed/resolved in the future.
 125 </p>
 126
 127
 128 <h2 id="hints">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 <h2 id="standalone">Stand-alone GLSL Compiler</h2>
 145
 146 <p>
 147 The stand-alone GLSL compiler program can be used to compile GLSL shaders
 148 into low-level GPU code.
 149 </p>
 150
 151 <p>
 152 This tool is useful for:
 153 </p>
 154 <ul>
 155 <li>Inspecting GPU code to gain insight into compilation
 156 <li>Generating initial GPU code for subsequent hand-tuning
 157 <li>Debugging the GLSL compiler itself
 158 </ul>
 159
 160 <p>
 161 After building Mesa, the compiler can be found at src/glsl/glsl_compiler
 162 </p>
 163
 164 <p>
 165 Here's an example of using the compiler to compile a vertex shader and
 166 emit GL_ARB_vertex_program-style instructions:
 167 </p>
 168 <pre>
 169     src/glsl/glsl_compiler --dump-ast myshader.vert
 170 </pre>
 171
 172 Options include
 173 <ul>
 174 <li><b>--dump-ast</b> - dump GPU code
 175 <li><b>--dump-hir</b> - dump high-level IR code
 176 <li><b>--dump-lir</b> - dump low-level IR code
 177 <li><b>--link</b> - ???
 178 </ul>
 179
 180
 181 <h2 id="implementation">Compiler Implementation</h2>
 182
 183 <p>
 184 The source code for Mesa's shading language compiler is in the
 185 <code>src/glsl/</code> directory.
 186 </p>
 187
 188 <p>
 189 XXX provide some info about the compiler....
 190 </p>
 191
 192 <p>
 193 The final vertex and fragment programs may be interpreted in software
 194 (see prog_execute.c) or translated into a specific hardware architecture
 195 (see drivers/dri/i915/i915_fragprog.c for example).
 196 </p>
 197
 198 <h3>Code Generation Options</h3>
 199
 200 <p>
 201 Internally, there are several options that control the compiler's code
 202 generation and instruction selection.
 203 These options are seen in the gl_shader_state struct and may be set
 204 by the device driver to indicate its preferences:
 205
 206 <pre>
 207 struct gl_shader_state
 208 {
 209    ...
 210    /** Driver-selectable options: */
 211    GLboolean EmitHighLevelInstructions;
 212    GLboolean EmitCondCodes;
 213    GLboolean EmitComments;
 214 };
 215 </pre>
 216
 217 <dl>
 218 <dt>EmitHighLevelInstructions</dt>
 219 <dd>
 220 This option controls instruction selection for loops and conditionals.
 221 If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
 222 instructions will be emitted.
 223 Otherwise, those constructs will be implemented with BRA instructions.
 224 </dd>
 225
 226 <dt>EmitCondCodes</dt>
 227 <dd>
 228 If set, condition codes (ala GL_NV_fragment_program) will be used for
 229 branching and looping.
 230 Otherwise, ordinary registers will be used (the IF instruction will
 231 examine the first operand's X component and do the if-part if non-zero).
 232 This option is only relevant if EmitHighLevelInstructions is set.
 233 </dd>
 234
 235 <dt>EmitComments</dt>
 236 <dd>
 237 If set, instructions will be annotated with comments to help with debugging.
 238 Extra NOP instructions will also be inserted.
 239 </dd>
 240 </dl>
 241
 242
 243 <h2 id="validation">Compiler Validation</h2>
 244
 245 <p>
 246 Developers working on the GLSL compiler should test frequently to avoid
 247 regressions.
 248 </p>
 249
 250 <p>
 251 The <a href="http://piglit.freedesktop.org/">Piglit</a> project
 252 has many GLSL tests.
 253 </p>
 254
 255 <p>
 256 The Mesa demos repository also has some good GLSL tests.
 257 </p>
 258
 259 </div>
 260 </body>
 261 </html>