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">
11 <h1>The Mesa
3D Graphics Library
</h1>
14 <iframe src=
"contents.html"></iframe>
17 <h1>Shading Language Support
</h1>
20 This page describes the features and status of Mesa's support for the
21 <a href=
"http://opengl.org/documentation/glsl/">
22 OpenGL Shading Language
</a>.
29 <li><a href=
"#envvars">Environment variables
</a>
30 <li><a href=
"#glsl120">GLSL
1.20 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>
40 <h2 id=
"envvars">Environment Variables
</h2>
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.
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
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
63 Example: export MESA_GLSL=dump,nopt
67 <h2 id=
"glsl120">GLSL Version
</h2>
70 The GLSL compiler currently supports version
1.20 of the shading language.
74 Several GLSL extensions are also supported:
77 <li>GL_ARB_draw_buffers
78 <li>GL_ARB_texture_rectangle
79 <li>GL_ARB_fragment_coord_conventions
80 <li>GL_EXT_texture_array
84 <h2 id=
"unsup">Unsupported Features
</h2>
86 <p>XXX update this section
</p>
89 The following features of the shading language are not yet fully supported
94 <li>Linking of multiple shaders does not always work. Currently, linking
95 is implemented through shader concatenation and re-compiling. This
96 doesn't always work because of some #pragma and preprocessor issues.
98 <li>The gl_Color and gl_SecondaryColor varying vars are interpolated
99 without perspective correction
103 All other major features of the shading language should function.
107 <h2 id=
"notes">Implementation Notes
</h2>
110 <li>Shading language programs are compiled into low-level programs
111 very similar to those of GL_ARB_vertex/fragment_program.
112 <li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
114 <li>Float constants and variables are packed so that up to four floats
115 can occupy one program parameter/register.
116 <li>All function calls are inlined.
117 <li>Shaders which use too many registers will not compile.
118 <li>The quality of generated code is pretty good, register usage is fair.
119 <li>Shader error detection and reporting of errors (InfoLog) is not
121 <li>The ftransform() function doesn't necessarily match the results of
122 fixed-function transformation.
126 These issues will be addressed/resolved in the future.
130 <h2 id=
"hints">Programming Hints
</h2>
133 <li>Use the built-in library functions whenever possible.
134 For example, instead of writing this:
136 float x =
1.0 / sqrt(y);
140 float x = inversesqrt(y);
146 <h2 id=
"standalone">Stand-alone GLSL Compiler
</h2>
149 The stand-alone GLSL compiler program can be used to compile GLSL shaders
150 into low-level GPU code.
154 This tool is useful for:
157 <li>Inspecting GPU code to gain insight into compilation
158 <li>Generating initial GPU code for subsequent hand-tuning
159 <li>Debugging the GLSL compiler itself
163 After building Mesa, the compiler can be found at src/glsl/glsl_compiler
167 Here's an example of using the compiler to compile a vertex shader and
168 emit GL_ARB_vertex_program-style instructions:
171 src/glsl/glsl_compiler --dump-ast myshader.vert
176 <li><b>--dump-ast
</b> - dump GPU code
177 <li><b>--dump-hir
</b> - dump high-level IR code
178 <li><b>--dump-lir
</b> - dump low-level IR code
179 <li><b>--link
</b> - ???
183 <h2 id=
"implementation">Compiler Implementation
</h2>
186 The source code for Mesa's shading language compiler is in the
187 <code>src/glsl/
</code> directory.
191 XXX provide some info about the compiler....
195 The final vertex and fragment programs may be interpreted in software
196 (see prog_execute.c) or translated into a specific hardware architecture
197 (see drivers/dri/i915/i915_fragprog.c for example).
200 <h3>Code Generation Options
</h3>
203 Internally, there are several options that control the compiler's code
204 generation and instruction selection.
205 These options are seen in the gl_shader_state struct and may be set
206 by the device driver to indicate its preferences:
209 struct gl_shader_state
212 /** Driver-selectable options: */
213 GLboolean EmitHighLevelInstructions;
214 GLboolean EmitCondCodes;
215 GLboolean EmitComments;
220 <dt>EmitHighLevelInstructions
</dt>
222 This option controls instruction selection for loops and conditionals.
223 If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
224 instructions will be emitted.
225 Otherwise, those constructs will be implemented with BRA instructions.
228 <dt>EmitCondCodes
</dt>
230 If set, condition codes (ala GL_NV_fragment_program) will be used for
231 branching and looping.
232 Otherwise, ordinary registers will be used (the IF instruction will
233 examine the first operand's X component and do the if-part if non-zero).
234 This option is only relevant if EmitHighLevelInstructions is set.
237 <dt>EmitComments
</dt>
239 If set, instructions will be annoted with comments to help with debugging.
240 Extra NOP instructions will also be inserted.
245 <h2 id=
"validation">Compiler Validation
</h2>
248 Developers working on the GLSL compiler should test frequently to avoid
253 The
<a href=
"http://piglit.freedesktop.org/">Piglit
</a> project
254 has many GLSL tests and the
255 <a href=
"http://glean.sf.net">Glean
</a> glsl1 test tests GLSL features.
259 The Mesa demos repository also has some good GLSL tests.