3 <TITLE>Shading Language Support
</TITLE>
5 <link rel=
"stylesheet" type=
"text/css" href=
"mesa.css"></head>
9 <H1>Shading Language Support
</H1>
12 This page describes the features and status of Mesa's support for the
13 <a href=
"http://opengl.org/documentation/glsl/" target=
"_parent">
14 OpenGL Shading Language
</a>.
21 <li><a href=
"#envvars">Environment variables
</a>
22 <li><a href=
"#120">GLSL
1.20 support
</a>
23 <li><a href=
"#unsup">Unsupported Features
</a>
24 <li><a href=
"#notes">Implementation Notes
</a>
25 <li><a href=
"#hints">Programming Hints
</a>
26 <li><a href=
"#standalone">Stand-alone GLSL Compiler
</a>
27 <li><a href=
"#implementation">Compiler Implementation
</a>
28 <li><a href=
"#validation">Compiler Validation
</a>
34 <h2>Environment Variables
</h2>
37 The
<b>MESA_GLSL
</b> environment variable can be set to a comma-separated
38 list of keywords to control some aspects of the GLSL compiler and shader
39 execution. These are generally used for debugging.
42 <li><b>dump
</b> - print GLSL shader code to stdout at link time
43 <li><b>log
</b> - log all GLSL shaders to files.
44 The filenames will be
"shader_X.vert" or
"shader_X.frag" where X
46 <li><b>nopt
</b> - disable compiler optimizations
47 <li><b>opt
</b> - force compiler optimizations
48 <li><b>uniform
</b> - print message to stdout when glUniform is called
49 <li><b>nopvert
</b> - force vertex shaders to be a simple shader that just transforms
50 the vertex position with ftransform() and passes through the color and
51 texcoord[
0] attributes.
52 <li><b>nopfrag
</b> - force fragment shader to be a simple shader that passes
53 through the color attribute.
54 <li><b>useprog
</b> - log glUseProgram calls to stderr
57 Example: export MESA_GLSL=dump,nopt
65 The GLSL compiler currently supports version
1.20 of the shading language.
69 Several GLSL extensions are also supported:
72 <li>GL_ARB_draw_buffers
73 <li>GL_ARB_texture_rectangle
74 <li>GL_ARB_fragment_coord_conventions
75 <li>GL_EXT_texture_array
80 <h2>Unsupported Features
</h2>
82 <p>XXX update this section
</p>
85 The following features of the shading language are not yet fully supported
90 <li>Linking of multiple shaders does not always work. Currently, linking
91 is implemented through shader concatenation and re-compiling. This
92 doesn't always work because of some #pragma and preprocessor issues.
94 <li>The gl_Color and gl_SecondaryColor varying vars are interpolated
95 without perspective correction
99 All other major features of the shading language should function.
104 <h2>Implementation Notes
</h2>
107 <li>Shading language programs are compiled into low-level programs
108 very similar to those of GL_ARB_vertex/fragment_program.
109 <li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
111 <li>Float constants and variables are packed so that up to four floats
112 can occupy one program parameter/register.
113 <li>All function calls are inlined.
114 <li>Shaders which use too many registers will not compile.
115 <li>The quality of generated code is pretty good, register usage is fair.
116 <li>Shader error detection and reporting of errors (InfoLog) is not
118 <li>The ftransform() function doesn't necessarily match the results of
119 fixed-function transformation.
123 These issues will be addressed/resolved in the future.
128 <h2>Programming Hints
</h2>
131 <li>Use the built-in library functions whenever possible.
132 For example, instead of writing this:
134 float x =
1.0 / sqrt(y);
138 float x = inversesqrt(y);
144 <a name=
"standalone">
145 <h2>Stand-alone GLSL Compiler
</h2>
148 The stand-alone GLSL compiler program can be used to compile GLSL shaders
149 into low-level GPU code.
153 This tool is useful for:
156 <li>Inspecting GPU code to gain insight into compilation
157 <li>Generating initial GPU code for subsequent hand-tuning
158 <li>Debugging the GLSL compiler itself
162 After building Mesa, the compiler can be found at src/glsl/glsl_compiler
166 Here's an example of using the compiler to compile a vertex shader and
167 emit GL_ARB_vertex_program-style instructions:
170 src/glsl/glsl_compiler --dump-ast myshader.vert
175 <li><b>--dump-ast
</b> - dump GPU code
176 <li><b>--dump-hir
</b> - dump high-level IR code
177 <li><b>--dump-lir
</b> - dump low-level IR code
178 <li><b>--link
</b> - ???
184 <a name=
"implementation">
185 <h2>Compiler Implementation
</h2>
188 The source code for Mesa's shading language compiler is in the
189 <code>src/glsl/
</code> directory.
193 XXX provide some info about the compiler....
197 The final vertex and fragment programs may be interpreted in software
198 (see prog_execute.c) or translated into a specific hardware architecture
199 (see drivers/dri/i915/i915_fragprog.c for example).
202 <h3>Code Generation Options
</h3>
205 Internally, there are several options that control the compiler's code
206 generation and instruction selection.
207 These options are seen in the gl_shader_state struct and may be set
208 by the device driver to indicate its preferences:
211 struct gl_shader_state
214 /** Driver-selectable options: */
215 GLboolean EmitHighLevelInstructions;
216 GLboolean EmitCondCodes;
217 GLboolean EmitComments;
222 <li>EmitHighLevelInstructions
224 This option controls instruction selection for loops and conditionals.
225 If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
226 instructions will be emitted.
227 Otherwise, those constructs will be implemented with BRA instructions.
232 If set, condition codes (ala GL_NV_fragment_program) will be used for
233 branching and looping.
234 Otherwise, ordinary registers will be used (the IF instruction will
235 examine the first operand's X component and do the if-part if non-zero).
236 This option is only relevant if EmitHighLevelInstructions is set.
241 If set, instructions will be annoted with comments to help with debugging.
242 Extra NOP instructions will also be inserted.
248 <a name=
"validation">
249 <h2>Compiler Validation
</h2>
252 Developers working on the GLSL compiler should test frequently to avoid
257 The
<a href=
"http://people.freedesktop.org/~nh/piglit/">Piglit
</a> project
258 has many GLSL tests and the
259 <a href=
"http://glean.sf.net" target=
"_parent">Glean
</a> glsl1 test
264 The Mesa demos repository also has some good GLSL tests.