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