shading.html revision ecd5c7ceb8e4c8841b2708e5ab7efa145583f8c2
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> 13This page describes the features and status of Mesa's support for the 14<a href="http://opengl.org/documentation/glsl/" target="_parent"> 15OpenGL Shading Language</a>. 16</p> 17 18<p> 19Contents 20</p> 21<ul> 22<li><a href="#envvars">Environment variables</a> 23<li><a href="#120">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 34<a name="envvars"> 35<h2>Environment Variables</h2> 36 37<p> 38The <b>MESA_GLSL</b> environment variable can be set to a comma-separated 39list of keywords to control some aspects of the GLSL compiler and shader 40execution. These are generally used for debugging. 41</p> 42<ul> 43<li><b>dump</b> - print GLSL shader code to stdout at link time 44<li><b>log</b> - log all GLSL shaders to files. 45 The filenames will be "shader_X.vert" or "shader_X.frag" where X 46 the shader ID. 47<li><b>nopt</b> - disable compiler optimizations 48<li><b>opt</b> - force compiler optimizations 49<li><b>uniform</b> - print message to stdout when glUniform is called 50<li><b>nopvert</b> - force vertex shaders to be a simple shader that just transforms 51 the vertex position with ftransform() and passes through the color and 52 texcoord[0] attributes. 53<li><b>nopfrag</b> - force fragment shader to be a simple shader that passes 54 through the color attribute. 55<li><b>useprog</b> - log glUseProgram calls to stderr 56</ul> 57<p> 58Example: export MESA_GLSL=dump,nopt 59</p> 60 61 62<a name="120"> 63<h2>GLSL Version</h2> 64 65<p> 66The GLSL compiler currently supports version 1.20 of the shading language. 67</p> 68 69<p> 70Several GLSL extensions are also supported: 71</p> 72<ul> 73<li>GL_ARB_draw_buffers 74<li>GL_ARB_texture_rectangle 75<li>GL_ARB_fragment_coord_conventions 76<li>GL_EXT_texture_array 77</ul> 78 79 80<a name="unsup"> 81<h2>Unsupported Features</h2> 82 83<p>XXX update this section</p> 84 85<p> 86The following features of the shading language are not yet fully supported 87in Mesa: 88</p> 89 90<ul> 91<li>Linking of multiple shaders does not always work. Currently, linking 92 is implemented through shader concatenation and re-compiling. This 93 doesn't always work because of some #pragma and preprocessor issues. 94<li>gl_ClipVertex 95<li>The gl_Color and gl_SecondaryColor varying vars are interpolated 96 without perspective correction 97</ul> 98 99<p> 100All other major features of the shading language should function. 101</p> 102 103 104<a name="notes"> 105<h2>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> 124These issues will be addressed/resolved in the future. 125</p> 126 127 128<a name="hints"> 129<h2>Programming Hints</h2> 130 131<ul> 132<li>Use the built-in library functions whenever possible. 133 For example, instead of writing this: 134<pre> 135 float x = 1.0 / sqrt(y); 136</pre> 137 Write this: 138<pre> 139 float x = inversesqrt(y); 140</pre> 141</li> 142</ul> 143 144 145<a name="standalone"> 146<h2>Stand-alone GLSL Compiler</h2> 147 148<p> 149The stand-alone GLSL compiler program can be used to compile GLSL shaders 150into low-level GPU code. 151</p> 152 153<p> 154This tool is useful for: 155<p> 156<ul> 157<li>Inspecting GPU code to gain insight into compilation 158<li>Generating initial GPU code for subsequent hand-tuning 159<li>Debugging the GLSL compiler itself 160</ul> 161 162<p> 163After building Mesa, the compiler can be found at src/glsl/glsl_compiler 164</p> 165 166<p> 167Here's an example of using the compiler to compile a vertex shader and 168emit GL_ARB_vertex_program-style instructions: 169</p> 170<pre> 171 src/glsl/glsl_compiler --dump-ast myshader.vert 172</pre> 173 174Options include 175<ul> 176<li><b>--dump-ast</b> - dump GPU code 177<li><b>--dump-hir</b> - dump high-level IR code 178<li><b>--dump-lir</b> - dump low-level IR code 179<li><b>--link</b> - ??? 180</ul> 181 182 183 184 185<a name="implementation"> 186<h2>Compiler Implementation</h2> 187 188<p> 189The source code for Mesa's shading language compiler is in the 190<code>src/glsl/</code> directory. 191</p> 192 193<p> 194XXX provide some info about the compiler.... 195</p> 196 197<p> 198The final vertex and fragment programs may be interpreted in software 199(see prog_execute.c) or translated into a specific hardware architecture 200(see drivers/dri/i915/i915_fragprog.c for example). 201</p> 202 203<h3>Code Generation Options</h3> 204 205<p> 206Internally, there are several options that control the compiler's code 207generation and instruction selection. 208These options are seen in the gl_shader_state struct and may be set 209by the device driver to indicate its preferences: 210 211<pre> 212struct gl_shader_state 213{ 214 ... 215 /** Driver-selectable options: */ 216 GLboolean EmitHighLevelInstructions; 217 GLboolean EmitCondCodes; 218 GLboolean EmitComments; 219}; 220</pre> 221 222<ul> 223<li>EmitHighLevelInstructions 224<br> 225This option controls instruction selection for loops and conditionals. 226If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK 227instructions will be emitted. 228Otherwise, those constructs will be implemented with BRA instructions. 229</li> 230 231<li>EmitCondCodes 232<br> 233If set, condition codes (ala GL_NV_fragment_program) will be used for 234branching and looping. 235Otherwise, ordinary registers will be used (the IF instruction will 236examine the first operand's X component and do the if-part if non-zero). 237This option is only relevant if EmitHighLevelInstructions is set. 238</li> 239 240<li>EmitComments 241<br> 242If set, instructions will be annoted with comments to help with debugging. 243Extra NOP instructions will also be inserted. 244</br> 245 246</ul> 247 248 249<a name="validation"> 250<h2>Compiler Validation</h2> 251 252<p> 253Developers working on the GLSL compiler should test frequently to avoid 254regressions. 255</p> 256 257<p> 258The <a href="http://people.freedesktop.org/~nh/piglit/">Piglit</a> project 259has many GLSL tests and the 260<a href="http://glean.sf.net" target="_parent">Glean</a> glsl1 test 261tests GLSL features. 262</p> 263 264<p> 265The Mesa demos repository also has some good GLSL tests. 266</p> 267 268</body> 269</html> 270