1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
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">
10 <h1>Shading Language Support
</h1>
13 This page describes the features and status of Mesa's support for the
14 <a href=
"http://opengl.org/documentation/glsl/" target=
"_parent">
15 OpenGL Shading Language
</a>.
22 <li><a href=
"#envvars">Environment variables
</a>
23 <li><a href=
"#glsl120">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>
33 <h2 id=
"envvars">Environment Variables
</h2>
36 The
<b>MESA_GLSL
</b> environment variable can be set to a comma-separated
37 list of keywords to control some aspects of the GLSL compiler and shader
38 execution. These are generally used for debugging.
41 <li><b>dump
</b> - print GLSL shader code to stdout at link time
42 <li><b>log
</b> - log all GLSL shaders to files.
43 The filenames will be
"shader_X.vert" or
"shader_X.frag" where X
45 <li><b>nopt
</b> - disable compiler optimizations
46 <li><b>opt
</b> - force compiler optimizations
47 <li><b>uniform
</b> - print message to stdout when glUniform is called
48 <li><b>nopvert
</b> - force vertex shaders to be a simple shader that just transforms
49 the vertex position with ftransform() and passes through the color and
50 texcoord[
0] attributes.
51 <li><b>nopfrag
</b> - force fragment shader to be a simple shader that passes
52 through the color attribute.
53 <li><b>useprog
</b> - log glUseProgram calls to stderr
56 Example: export MESA_GLSL=dump,nopt
60 <h2 id=
"glsl120">GLSL Version
</h2>
63 The GLSL compiler currently supports version
1.20 of the shading language.
67 Several GLSL extensions are also supported:
70 <li>GL_ARB_draw_buffers
71 <li>GL_ARB_texture_rectangle
72 <li>GL_ARB_fragment_coord_conventions
73 <li>GL_EXT_texture_array
77 <h2 id=
"unsup">Unsupported Features
</h2>
79 <p>XXX update this section
</p>
82 The following features of the shading language are not yet fully supported
87 <li>Linking of multiple shaders does not always work. Currently, linking
88 is implemented through shader concatenation and re-compiling. This
89 doesn't always work because of some #pragma and preprocessor issues.
91 <li>The gl_Color and gl_SecondaryColor varying vars are interpolated
92 without perspective correction
96 All other major features of the shading language should function.
100 <h2 id=
"notes">Implementation Notes
</h2>
103 <li>Shading language programs are compiled into low-level programs
104 very similar to those of GL_ARB_vertex/fragment_program.
105 <li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
107 <li>Float constants and variables are packed so that up to four floats
108 can occupy one program parameter/register.
109 <li>All function calls are inlined.
110 <li>Shaders which use too many registers will not compile.
111 <li>The quality of generated code is pretty good, register usage is fair.
112 <li>Shader error detection and reporting of errors (InfoLog) is not
114 <li>The ftransform() function doesn't necessarily match the results of
115 fixed-function transformation.
119 These issues will be addressed/resolved in the future.
123 <h2 id=
"hints">Programming Hints
</h2>
126 <li>Use the built-in library functions whenever possible.
127 For example, instead of writing this:
129 float x =
1.0 / sqrt(y);
133 float x = inversesqrt(y);
139 <h2 id=
"standalone">Stand-alone GLSL Compiler
</h2>
142 The stand-alone GLSL compiler program can be used to compile GLSL shaders
143 into low-level GPU code.
147 This tool is useful for:
150 <li>Inspecting GPU code to gain insight into compilation
151 <li>Generating initial GPU code for subsequent hand-tuning
152 <li>Debugging the GLSL compiler itself
156 After building Mesa, the compiler can be found at src/glsl/glsl_compiler
160 Here's an example of using the compiler to compile a vertex shader and
161 emit GL_ARB_vertex_program-style instructions:
164 src/glsl/glsl_compiler --dump-ast myshader.vert
169 <li><b>--dump-ast
</b> - dump GPU code
170 <li><b>--dump-hir
</b> - dump high-level IR code
171 <li><b>--dump-lir
</b> - dump low-level IR code
172 <li><b>--link
</b> - ???
176 <h2 id=
"implementation">Compiler Implementation
</h2>
179 The source code for Mesa's shading language compiler is in the
180 <code>src/glsl/
</code> directory.
184 XXX provide some info about the compiler....
188 The final vertex and fragment programs may be interpreted in software
189 (see prog_execute.c) or translated into a specific hardware architecture
190 (see drivers/dri/i915/i915_fragprog.c for example).
193 <h3>Code Generation Options
</h3>
196 Internally, there are several options that control the compiler's code
197 generation and instruction selection.
198 These options are seen in the gl_shader_state struct and may be set
199 by the device driver to indicate its preferences:
202 struct gl_shader_state
205 /** Driver-selectable options: */
206 GLboolean EmitHighLevelInstructions;
207 GLboolean EmitCondCodes;
208 GLboolean EmitComments;
213 <li>EmitHighLevelInstructions
215 This option controls instruction selection for loops and conditionals.
216 If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
217 instructions will be emitted.
218 Otherwise, those constructs will be implemented with BRA instructions.
223 If set, condition codes (ala GL_NV_fragment_program) will be used for
224 branching and looping.
225 Otherwise, ordinary registers will be used (the IF instruction will
226 examine the first operand's X component and do the if-part if non-zero).
227 This option is only relevant if EmitHighLevelInstructions is set.
232 If set, instructions will be annoted with comments to help with debugging.
233 Extra NOP instructions will also be inserted.
238 <h2 id=
"validation">Compiler Validation
</h2>
241 Developers working on the GLSL compiler should test frequently to avoid
246 The
<a href=
"http://people.freedesktop.org/~nh/piglit/">Piglit
</a> project
247 has many GLSL tests and the
248 <a href=
"http://glean.sf.net" target=
"_parent">Glean
</a> glsl1 test
253 The Mesa demos repository also has some good GLSL tests.