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 <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>