shading.html revision 848b8605
1848b8605Smrg<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2848b8605Smrg<html lang="en"> 3848b8605Smrg<head> 4848b8605Smrg <meta http-equiv="content-type" content="text/html; charset=utf-8"> 5848b8605Smrg <title>Shading Language Support</title> 6848b8605Smrg <link rel="stylesheet" type="text/css" href="mesa.css"> 7848b8605Smrg</head> 8848b8605Smrg<body> 9848b8605Smrg 10848b8605Smrg<div class="header"> 11848b8605Smrg <h1>The Mesa 3D Graphics Library</h1> 12848b8605Smrg</div> 13848b8605Smrg 14848b8605Smrg<iframe src="contents.html"></iframe> 15848b8605Smrg<div class="content"> 16848b8605Smrg 17848b8605Smrg<h1>Shading Language Support</h1> 18848b8605Smrg 19848b8605Smrg<p> 20848b8605SmrgThis page describes the features and status of Mesa's support for the 21848b8605Smrg<a href="http://opengl.org/documentation/glsl/"> 22848b8605SmrgOpenGL Shading Language</a>. 23848b8605Smrg</p> 24848b8605Smrg 25848b8605Smrg<p> 26848b8605SmrgContents 27848b8605Smrg</p> 28848b8605Smrg<ul> 29848b8605Smrg<li><a href="#envvars">Environment variables</a> 30848b8605Smrg<li><a href="#support">GLSL 1.40 support</a> 31848b8605Smrg<li><a href="#unsup">Unsupported Features</a> 32848b8605Smrg<li><a href="#notes">Implementation Notes</a> 33848b8605Smrg<li><a href="#hints">Programming Hints</a> 34848b8605Smrg<li><a href="#standalone">Stand-alone GLSL Compiler</a> 35848b8605Smrg<li><a href="#implementation">Compiler Implementation</a> 36848b8605Smrg<li><a href="#validation">Compiler Validation</a> 37848b8605Smrg</ul> 38848b8605Smrg 39848b8605Smrg 40848b8605Smrg<h2 id="envvars">Environment Variables</h2> 41848b8605Smrg 42848b8605Smrg<p> 43848b8605SmrgThe <b>MESA_GLSL</b> environment variable can be set to a comma-separated 44848b8605Smrglist of keywords to control some aspects of the GLSL compiler and shader 45848b8605Smrgexecution. These are generally used for debugging. 46848b8605Smrg</p> 47848b8605Smrg<ul> 48848b8605Smrg<li><b>dump</b> - print GLSL shader code to stdout at link time 49848b8605Smrg<li><b>log</b> - log all GLSL shaders to files. 50848b8605Smrg The filenames will be "shader_X.vert" or "shader_X.frag" where X 51848b8605Smrg the shader ID. 52848b8605Smrg<li><b>nopt</b> - disable compiler optimizations 53848b8605Smrg<li><b>opt</b> - force compiler optimizations 54848b8605Smrg<li><b>uniform</b> - print message to stdout when glUniform is called 55848b8605Smrg<li><b>nopvert</b> - force vertex shaders to be a simple shader that just transforms 56848b8605Smrg the vertex position with ftransform() and passes through the color and 57848b8605Smrg texcoord[0] attributes. 58848b8605Smrg<li><b>nopfrag</b> - force fragment shader to be a simple shader that passes 59848b8605Smrg through the color attribute. 60848b8605Smrg<li><b>useprog</b> - log glUseProgram calls to stderr 61848b8605Smrg</ul> 62848b8605Smrg<p> 63848b8605SmrgExample: export MESA_GLSL=dump,nopt 64848b8605Smrg</p> 65848b8605Smrg 66848b8605Smrg 67848b8605Smrg<h2 id="support">GLSL Version</h2> 68848b8605Smrg 69848b8605Smrg<p> 70848b8605SmrgThe GLSL compiler currently supports version 3.30 of the shading language. 71848b8605Smrg</p> 72848b8605Smrg 73848b8605Smrg<p> 74848b8605SmrgSeveral GLSL extensions are also supported: 75848b8605Smrg</p> 76848b8605Smrg<ul> 77848b8605Smrg<li>GL_ARB_draw_buffers 78848b8605Smrg<li>GL_ARB_fragment_coord_conventions 79848b8605Smrg<li>GL_ARB_shader_bit_encoding 80848b8605Smrg</ul> 81848b8605Smrg 82848b8605Smrg 83848b8605Smrg<h2 id="unsup">Unsupported Features</h2> 84848b8605Smrg 85848b8605Smrg<p>XXX update this section</p> 86848b8605Smrg 87848b8605Smrg<p> 88848b8605SmrgThe following features of the shading language are not yet fully supported 89848b8605Smrgin Mesa: 90848b8605Smrg</p> 91848b8605Smrg 92848b8605Smrg<ul> 93848b8605Smrg<li>Linking of multiple shaders does not always work. Currently, linking 94848b8605Smrg is implemented through shader concatenation and re-compiling. This 95848b8605Smrg doesn't always work because of some #pragma and preprocessor issues. 96848b8605Smrg<li>The gl_Color and gl_SecondaryColor varying vars are interpolated 97848b8605Smrg without perspective correction 98848b8605Smrg</ul> 99848b8605Smrg 100848b8605Smrg<p> 101848b8605SmrgAll other major features of the shading language should function. 102848b8605Smrg</p> 103848b8605Smrg 104848b8605Smrg 105848b8605Smrg<h2 id="notes">Implementation Notes</h2> 106848b8605Smrg 107848b8605Smrg<ul> 108848b8605Smrg<li>Shading language programs are compiled into low-level programs 109848b8605Smrg very similar to those of GL_ARB_vertex/fragment_program. 110848b8605Smrg<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full 111848b8605Smrg float[4] registers. 112848b8605Smrg<li>Float constants and variables are packed so that up to four floats 113848b8605Smrg can occupy one program parameter/register. 114848b8605Smrg<li>All function calls are inlined. 115848b8605Smrg<li>Shaders which use too many registers will not compile. 116848b8605Smrg<li>The quality of generated code is pretty good, register usage is fair. 117848b8605Smrg<li>Shader error detection and reporting of errors (InfoLog) is not 118848b8605Smrg very good yet. 119848b8605Smrg<li>The ftransform() function doesn't necessarily match the results of 120848b8605Smrg fixed-function transformation. 121848b8605Smrg</ul> 122848b8605Smrg 123848b8605Smrg<p> 124848b8605SmrgThese issues will be addressed/resolved in the future. 125848b8605Smrg</p> 126848b8605Smrg 127848b8605Smrg 128848b8605Smrg<h2 id="hints">Programming Hints</h2> 129848b8605Smrg 130848b8605Smrg<ul> 131848b8605Smrg<li>Use the built-in library functions whenever possible. 132848b8605Smrg For example, instead of writing this: 133848b8605Smrg<pre> 134848b8605Smrg float x = 1.0 / sqrt(y); 135848b8605Smrg</pre> 136848b8605Smrg Write this: 137848b8605Smrg<pre> 138848b8605Smrg float x = inversesqrt(y); 139848b8605Smrg</pre> 140848b8605Smrg</li> 141848b8605Smrg</ul> 142848b8605Smrg 143848b8605Smrg 144848b8605Smrg<h2 id="standalone">Stand-alone GLSL Compiler</h2> 145848b8605Smrg 146848b8605Smrg<p> 147848b8605SmrgThe stand-alone GLSL compiler program can be used to compile GLSL shaders 148848b8605Smrginto low-level GPU code. 149848b8605Smrg</p> 150848b8605Smrg 151848b8605Smrg<p> 152848b8605SmrgThis tool is useful for: 153848b8605Smrg</p> 154848b8605Smrg<ul> 155848b8605Smrg<li>Inspecting GPU code to gain insight into compilation 156848b8605Smrg<li>Generating initial GPU code for subsequent hand-tuning 157848b8605Smrg<li>Debugging the GLSL compiler itself 158848b8605Smrg</ul> 159848b8605Smrg 160848b8605Smrg<p> 161848b8605SmrgAfter building Mesa, the compiler can be found at src/glsl/glsl_compiler 162848b8605Smrg</p> 163848b8605Smrg 164848b8605Smrg<p> 165848b8605SmrgHere's an example of using the compiler to compile a vertex shader and 166848b8605Smrgemit GL_ARB_vertex_program-style instructions: 167848b8605Smrg</p> 168848b8605Smrg<pre> 169848b8605Smrg src/glsl/glsl_compiler --dump-ast myshader.vert 170848b8605Smrg</pre> 171848b8605Smrg 172848b8605SmrgOptions include 173848b8605Smrg<ul> 174848b8605Smrg<li><b>--dump-ast</b> - dump GPU code 175848b8605Smrg<li><b>--dump-hir</b> - dump high-level IR code 176848b8605Smrg<li><b>--dump-lir</b> - dump low-level IR code 177848b8605Smrg<li><b>--link</b> - ??? 178848b8605Smrg</ul> 179848b8605Smrg 180848b8605Smrg 181848b8605Smrg<h2 id="implementation">Compiler Implementation</h2> 182848b8605Smrg 183848b8605Smrg<p> 184848b8605SmrgThe source code for Mesa's shading language compiler is in the 185848b8605Smrg<code>src/glsl/</code> directory. 186848b8605Smrg</p> 187848b8605Smrg 188848b8605Smrg<p> 189848b8605SmrgXXX provide some info about the compiler.... 190848b8605Smrg</p> 191848b8605Smrg 192848b8605Smrg<p> 193848b8605SmrgThe final vertex and fragment programs may be interpreted in software 194848b8605Smrg(see prog_execute.c) or translated into a specific hardware architecture 195848b8605Smrg(see drivers/dri/i915/i915_fragprog.c for example). 196848b8605Smrg</p> 197848b8605Smrg 198848b8605Smrg<h3>Code Generation Options</h3> 199848b8605Smrg 200848b8605Smrg<p> 201848b8605SmrgInternally, there are several options that control the compiler's code 202848b8605Smrggeneration and instruction selection. 203848b8605SmrgThese options are seen in the gl_shader_state struct and may be set 204848b8605Smrgby the device driver to indicate its preferences: 205848b8605Smrg 206848b8605Smrg<pre> 207848b8605Smrgstruct gl_shader_state 208848b8605Smrg{ 209848b8605Smrg ... 210848b8605Smrg /** Driver-selectable options: */ 211848b8605Smrg GLboolean EmitHighLevelInstructions; 212848b8605Smrg GLboolean EmitCondCodes; 213848b8605Smrg GLboolean EmitComments; 214848b8605Smrg}; 215848b8605Smrg</pre> 216848b8605Smrg 217848b8605Smrg<dl> 218848b8605Smrg<dt>EmitHighLevelInstructions</dt> 219848b8605Smrg<dd> 220848b8605SmrgThis option controls instruction selection for loops and conditionals. 221848b8605SmrgIf the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK 222848b8605Smrginstructions will be emitted. 223848b8605SmrgOtherwise, those constructs will be implemented with BRA instructions. 224848b8605Smrg</dd> 225848b8605Smrg 226848b8605Smrg<dt>EmitCondCodes</dt> 227848b8605Smrg<dd> 228848b8605SmrgIf set, condition codes (ala GL_NV_fragment_program) will be used for 229848b8605Smrgbranching and looping. 230848b8605SmrgOtherwise, ordinary registers will be used (the IF instruction will 231848b8605Smrgexamine the first operand's X component and do the if-part if non-zero). 232848b8605SmrgThis option is only relevant if EmitHighLevelInstructions is set. 233848b8605Smrg</dd> 234848b8605Smrg 235848b8605Smrg<dt>EmitComments</dt> 236848b8605Smrg<dd> 237848b8605SmrgIf set, instructions will be annotated with comments to help with debugging. 238848b8605SmrgExtra NOP instructions will also be inserted. 239848b8605Smrg</dd> 240848b8605Smrg</dl> 241848b8605Smrg 242848b8605Smrg 243848b8605Smrg<h2 id="validation">Compiler Validation</h2> 244848b8605Smrg 245848b8605Smrg<p> 246848b8605SmrgDevelopers working on the GLSL compiler should test frequently to avoid 247848b8605Smrgregressions. 248848b8605Smrg</p> 249848b8605Smrg 250848b8605Smrg<p> 251848b8605SmrgThe <a href="http://piglit.freedesktop.org/">Piglit</a> project 252848b8605Smrghas many GLSL tests. 253848b8605Smrg</p> 254848b8605Smrg 255848b8605Smrg<p> 256848b8605SmrgThe Mesa demos repository also has some good GLSL tests. 257848b8605Smrg</p> 258848b8605Smrg 259848b8605Smrg</div> 260848b8605Smrg</body> 261848b8605Smrg</html> 262