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 Last updated on 17 Feb 2007.
  19 </p>
  20
  21 <p>
  22 Contents
  23 </p>
  24 <ul>
  25 <li><a href="#unsup">Unsupported Features</a>
  26 <li><a href="#impl">Implementation Notes</a>
  27 <li><a href="#hints">Programming Hints</a>
  28 <li><a href="#standalone">Stand-alone Compiler</a>
  29 </ul>
  30
  31
  32 <a name="unsup">
  33 <h2>Unsupported Features</h2>
  34
  35 <p>
  36 The following features of the shading language are not yet supported
  37 in Mesa:
  38 </p>
  39
  40 <ul>
  41 <li>Arrays
  42 <li>Structs
  43 <li>Linking of multiple shaders is not supported
  44 <li>Not all built-in OpenGL state variables are supported yet.
  45     Common variables such as gl_ModelViewMatrix and gl_NormalMatrix
  46     are supported.
  47 <li>Integer operations are not fully implemented (most are implemented
  48     as floating point).
  49 </ul>
  50
  51 <p>
  52 All other major features of the shading language should function.
  53 </p>
  54
  55
  56 <a name="impl">
  57 <h2>Implementation Notes</h2>
  58
  59 <ul>
  60 <li>Shading language programs are compiled into low-level programs
  61     very similar to those of GL_ARB_vertex/fragment_program.
  62 <li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
  63     float[4] registers.
  64 <li>Float constants and variables are packed so that up to four floats
  65     can occupy one program parameter/register.
  66 <li>All function calls are inlined.
  67 <li>Shaders which use too many registers will not compile.
  68 <li>The quality of generated code is pretty good, register usage is fair.
  69 <li>Shader error detection and reporting of errors (InfoLog) is not
  70     very good yet.
  71 <li>There are massive memory leaks in the compiler.
  72 </ul>
  73
  74 <p>
  75 These issues will be addressed/resolved in the future.
  76 </p>
  77
  78
  79 <a name="hints">
  80 <h2>Programming Hints</h2>
  81
  82 <ul>
  83 <li>Declare <em>in</em> function parameters as <em>const</em> whenever possible.
  84     This improves the efficiency of function inlining.
  85 </li>
  86 <br>
  87 <li>To reduce register usage, declare variables within smaller scopes.
  88     For example, the following code:
  89 <pre>
  90     void main()
  91     {
  92        vec4 a1, a2, b1, b2;
  93        gl_Position = expression using a1, a2.
  94        gl_Color = expression using b1, b2;
  95     }
  96 </pre>
  97     Can be rewritten as follows to use half as many registers:
  98 <pre>
  99     void main()
 100     {
 101        {
 102           vec4 a1, a2;
 103           gl_Position = expression using a1, a2.
 104        }
 105        {
 106           vec4 b1, b2;
 107           gl_Color = expression using b1, b2;
 108        }
 109     }
 110 </pre>
 111     Alternately, rather than using several float variables, use
 112     a vec4 instead.  Use swizzling and writemasks to access the
 113     components of the vec4 as floats.
 114 </li>
 115 <br>
 116 <li>Use the built-in library functions whenever possible.
 117     For example, instead of writing this:
 118 <pre>
 119         float x = 1.0 / sqrt(y);
 120 </pre>
 121     Write this:
 122 <pre>
 123         float x = inversesqrt(y);
 124 </pre>
 125 </ul>
 126
 127
 128 <a name="standalone">
 129 <h2>Stand-alone Compiler</h2>
 130
 131 <p>
 132 A unique stand-alone GLSL compiler driver has been added to Mesa.
 133 <p>
 134
 135 <p>
 136 The stand-alone compiler (like a conventional command-line compiler)
 137 is a tool that accepts Shading Language programs and emits low-level
 138 GPU programs.
 139 </p>
 140
 141 <p>
 142 This tool is useful for:
 143 <p>
 144 <ul>
 145 <li>Inspecting GPU code to gain insight into compilation
 146 <li>Generating initial GPU code for subsequent hand-tuning
 147 <li>Debugging the GLSL compiler itself
 148 </ul>
 149
 150 <p>
 151 (compiler build instructions TBD)
 152 </p>
 153
 154 <p>
 155 Here's an example of using the compiler to compile a vertex shader and
 156 emit GL_ARB_vertex_program-style instructions:
 157 </p>
 158 <pre>
 159     glslcompiler --arb --linenumbers --vs vertshader.txt
 160 </pre>
 161 <p>
 162 The output may look similar to this:
 163 </p>
 164 <pre>
 165 !!ARBvp1.0
 166   0: MOV result.texcoord[0], vertex.texcoord[0];
 167   1: DP4 temp0.x, state.matrix.mvp.row[0], vertex.position;
 168   2: DP4 temp0.y, state.matrix.mvp.row[1], vertex.position;
 169   3: DP4 temp0.z, state.matrix.mvp.row[2], vertex.position;
 170   4: DP4 temp0.w, state.matrix.mvp.row[3], vertex.position;
 171   5: MOV result.position, temp0;
 172   6: END
 173 </pre>
 174
 175 <p>
 176 Note that some shading language constructs (such as uniform and varying
 177 variables) aren't expressible in ARB or NV-style programs.
 178 Therefore, the resulting output is not always legal by definition of
 179 those program languages.
 180 </p>
 181 <p>
 182 Also note that this compiler driver is still under development.
 183 Over time, the correctness of the GPU programs, with respect to the ARB
 184 and NV languagues, should improve.
 185 </p>
 186
 187 </BODY>
 188 </HTML>