docs/shading.html

   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>