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> 20This page describes the features and status of Mesa's support for the 21<a href="http://opengl.org/documentation/glsl/"> 22OpenGL Shading Language</a>. 23</p> 24 25<p> 26Contents 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> 43The <b>MESA_GLSL</b> environment variable can be set to a comma-separated 44list of keywords to control some aspects of the GLSL compiler and shader 45execution. 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> 63Example: export MESA_GLSL=dump,nopt 64</p> 65 66<p> 67Shaders can be dumped and replaced on runtime for debugging purposes. Mesa 68needs to be configured with '--with-sha1' to enable this functionality. This 69feature is not currently supported by SCons build. 70 71This is controlled via following environment variables: 72<ul> 73<li><b>MESA_SHADER_DUMP_PATH</b> - path where shader sources are dumped 74<li><b>MESA_SHADER_READ_PATH</b> - path where replacement shaders are read 75</ul> 76Note, path set must exist before running for dumping or replacing to work. 77When both are set, these paths should be different so the dumped shaders do 78not clobber the replacement shaders. 79</p> 80 81<h2 id="support">GLSL Version</h2> 82 83<p> 84The GLSL compiler currently supports version 3.30 of the shading language. 85</p> 86 87<p> 88Several GLSL extensions are also supported: 89</p> 90<ul> 91<li>GL_ARB_draw_buffers 92<li>GL_ARB_fragment_coord_conventions 93<li>GL_ARB_shader_bit_encoding 94</ul> 95 96 97<h2 id="unsup">Unsupported Features</h2> 98 99<p>XXX update this section</p> 100 101<p> 102The following features of the shading language are not yet fully supported 103in Mesa: 104</p> 105 106<ul> 107<li>Linking of multiple shaders does not always work. Currently, linking 108 is implemented through shader concatenation and re-compiling. This 109 doesn't always work because of some #pragma and preprocessor issues. 110<li>The gl_Color and gl_SecondaryColor varying vars are interpolated 111 without perspective correction 112</ul> 113 114<p> 115All other major features of the shading language should function. 116</p> 117 118 119<h2 id="notes">Implementation Notes</h2> 120 121<ul> 122<li>Shading language programs are compiled into low-level programs 123 very similar to those of GL_ARB_vertex/fragment_program. 124<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full 125 float[4] registers. 126<li>Float constants and variables are packed so that up to four floats 127 can occupy one program parameter/register. 128<li>All function calls are inlined. 129<li>Shaders which use too many registers will not compile. 130<li>The quality of generated code is pretty good, register usage is fair. 131<li>Shader error detection and reporting of errors (InfoLog) is not 132 very good yet. 133<li>The ftransform() function doesn't necessarily match the results of 134 fixed-function transformation. 135</ul> 136 137<p> 138These issues will be addressed/resolved in the future. 139</p> 140 141 142<h2 id="hints">Programming Hints</h2> 143 144<ul> 145<li>Use the built-in library functions whenever possible. 146 For example, instead of writing this: 147<pre> 148 float x = 1.0 / sqrt(y); 149</pre> 150 Write this: 151<pre> 152 float x = inversesqrt(y); 153</pre> 154</li> 155</ul> 156 157 158<h2 id="standalone">Stand-alone GLSL Compiler</h2> 159 160<p> 161The stand-alone GLSL compiler program can be used to compile GLSL shaders 162into low-level GPU code. 163</p> 164 165<p> 166This tool is useful for: 167</p> 168<ul> 169<li>Inspecting GPU code to gain insight into compilation 170<li>Generating initial GPU code for subsequent hand-tuning 171<li>Debugging the GLSL compiler itself 172</ul> 173 174<p> 175After building Mesa, the compiler can be found at src/compiler/glsl/glsl_compiler 176</p> 177 178<p> 179Here's an example of using the compiler to compile a vertex shader and 180emit GL_ARB_vertex_program-style instructions: 181</p> 182<pre> 183 src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert 184</pre> 185 186Options include 187<ul> 188<li><b>--dump-ast</b> - dump GPU code 189<li><b>--dump-hir</b> - dump high-level IR code 190<li><b>--dump-lir</b> - dump low-level IR code 191<li><b>--dump-builder</b> - dump GLSL IR code 192<li><b>--link</b> - link shaders 193<li><b>--just-log</b> - display only shader / linker info if exist, 194without any header or separator 195<li><b>--version</b> - [Mandatory] define the GLSL version to use 196</ul> 197 198 199<h2 id="implementation">Compiler Implementation</h2> 200 201<p> 202The source code for Mesa's shading language compiler is in the 203<code>src/compiler/glsl/</code> directory. 204</p> 205 206<p> 207XXX provide some info about the compiler.... 208</p> 209 210<p> 211The final vertex and fragment programs may be interpreted in software 212(see prog_execute.c) or translated into a specific hardware architecture 213(see drivers/dri/i915/i915_fragprog.c for example). 214</p> 215 216<h2 id="validation">Compiler Validation</h2> 217 218<p> 219Developers working on the GLSL compiler should test frequently to avoid 220regressions. 221</p> 222 223<p> 224The <a href="http://piglit.freedesktop.org/">Piglit</a> project 225has many GLSL tests. 226</p> 227 228<p> 229The Mesa demos repository also has some good GLSL tests. 230</p> 231 232</div> 233</body> 234</html> 235