Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / mesa3d / 2e570be85211f603b820dd2c5e9aa2f29a51fc66 / . / docs / shading.html
blob: 77c86be3aa63e2e55109757d41b5550410b90885 [file] [log] [blame]
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]1<HTML>
2
3<TITLE>Shading Language Support</TITLE>
4
5<link rel="stylesheet" type="text/css" href="mesa.css"></head>
6
7<BODY>
8
9<H1>Shading Language Support</H1>
10
11<p>
12This page describes the features and status of Mesa's support for the
13<a href="http://opengl.org/documentation/glsl/" target="_parent">
14OpenGL Shading Language</a>.
15</p>
16
17<p>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]18Last updated on 15 December 2008.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]19</p>
20
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]21<p>
22Contents
23</p>
24<ul>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]25<li><a href="#envvars">Environment variables</a>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]26<li><a href="#120">GLSL 1.20 support</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]27<li><a href="#unsup">Unsupported Features</a>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]28<li><a href="#notes">Implementation Notes</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]29<li><a href="#hints">Programming Hints</a>
Brian Paul3bfedb72008-07-17 15:40:10 -0600[diff] [blame]30<li><a href="#standalone">Stand-alone GLSL Compiler</a>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]31<li><a href="#implementation">Compiler Implementation</a>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]32<li><a href="#validation">Compiler Validation</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]33</ul>
34
35
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]36
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]37<a name="envvars">
38<h2>Environment Variables</h2>
39
40<p>
41The <b>MESA_GLSL</b> environment variable can be set to a comma-separated
42list of keywords to control some aspects of the GLSL compiler:
43</p>
44<ul>
45<li>dump - print GLSL shader code to stdout at link time
46<li>log - log all GLSL shaders to files.
47 The filenames will be "shader_X.vert" or "shader_X.frag" where X
48 the shader ID.
49<li>nopt - disable compiler optimizations
50<li>opt - force compiler optimizations
51<li>uniform - print message to stdout when glUniform is called
52</ul>
53<p>
54Example: export MESA_GLSL=dump,nopt
55</p>
56
57
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]58<a name="120">
59<h2>GLSL 1.20 support</h2>
60
61<p>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]62GLSL version 1.20 is supported in Mesa 7.3 and later.
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]63Among the features/differences of GLSL 1.20 are:
64<ul>
65<li><code>mat2x3, mat2x4</code>, etc. types and functions
66<li><code>transpose(), outerProduct(), matrixCompMult()</code> functions
67(but untested)
68<li>precision qualifiers (lowp, mediump, highp)
69<li><code>invariant</code> qualifier
70<li><code>array.length()</code> method
71<li><code>float[5] a;</code> array syntax
72<li><code>centroid</code> qualifier
73<li>unsized array constructors
74<li>initializers for uniforms
75<li>const initializers calling built-in functions
76</ul>
77
78
79
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]80<a name="unsup">
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]81<h2>Unsupported Features</h2>
82
83<p>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]84The following features of the shading language are not yet fully supported
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]85in Mesa:
86</p>
87
88<ul>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]89<li>Linking of multiple shaders does not always work. Currently, linking
90 is implemented through shader concatenation and re-compiling. This
91 doesn't always work because of some #pragma and preprocessor issues.
Brianb03e1712007-03-09 09:51:55 -0700[diff] [blame]92<li>gl_ClipVertex
Brian4b1d1b72007-04-27 15:25:00 -0600[diff] [blame]93<li>The gl_Color and gl_SecondaryColor varying vars are interpolated
94 without perspective correction
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]95</ul>
96
97<p>
98All other major features of the shading language should function.
99</p>
100
101
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]102<a name="notes">
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]103<h2>Implementation Notes</h2>
104
105<ul>
106<li>Shading language programs are compiled into low-level programs
107 very similar to those of GL_ARB_vertex/fragment_program.
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]108<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]109 float[4] registers.
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]110<li>Float constants and variables are packed so that up to four floats
111 can occupy one program parameter/register.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]112<li>All function calls are inlined.
113<li>Shaders which use too many registers will not compile.
114<li>The quality of generated code is pretty good, register usage is fair.
115<li>Shader error detection and reporting of errors (InfoLog) is not
116 very good yet.
Brian05e6fd82007-03-27 16:05:25 -0600[diff] [blame]117<li>The ftransform() function doesn't necessarily match the results of
118 fixed-function transformation.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]119</ul>
120
121<p>
122These issues will be addressed/resolved in the future.
123</p>
124
125
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]126<a name="hints">
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]127<h2>Programming Hints</h2>
128
129<ul>
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]130<li>Declare <em>in</em> function parameters as <em>const</em> whenever possible.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]131 This improves the efficiency of function inlining.
132</li>
133<br>
134<li>To reduce register usage, declare variables within smaller scopes.
135 For example, the following code:
136<pre>
137 void main()
138 {
139 vec4 a1, a2, b1, b2;
140 gl_Position = expression using a1, a2.
141 gl_Color = expression using b1, b2;
142 }
143</pre>
144 Can be rewritten as follows to use half as many registers:
145<pre>
146 void main()
147 {
148 {
149 vec4 a1, a2;
150 gl_Position = expression using a1, a2.
151 }
152 {
153 vec4 b1, b2;
154 gl_Color = expression using b1, b2;
155 }
156 }
157</pre>
158 Alternately, rather than using several float variables, use
159 a vec4 instead. Use swizzling and writemasks to access the
160 components of the vec4 as floats.
161</li>
162<br>
163<li>Use the built-in library functions whenever possible.
164 For example, instead of writing this:
165<pre>
166 float x = 1.0 / sqrt(y);
167</pre>
168 Write this:
169<pre>
170 float x = inversesqrt(y);
171</pre>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]172<li>
173 Use ++i when possible as it's more efficient than i++
174</li>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]175</ul>
176
177
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]178<a name="standalone">
Brian Paul3bfedb72008-07-17 15:40:10 -0600[diff] [blame]179<h2>Stand-alone GLSL Compiler</h2>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]180
181<p>
182A unique stand-alone GLSL compiler driver has been added to Mesa.
183<p>
184
185<p>
186The stand-alone compiler (like a conventional command-line compiler)
187is a tool that accepts Shading Language programs and emits low-level
188GPU programs.
189</p>
190
191<p>
192This tool is useful for:
193<p>
194<ul>
195<li>Inspecting GPU code to gain insight into compilation
196<li>Generating initial GPU code for subsequent hand-tuning
197<li>Debugging the GLSL compiler itself
198</ul>
199
200<p>
Brian Paul77497eb2008-07-21 09:01:21 -0600[diff] [blame]201After building Mesa, the glslcompiler can be built by manually running:
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]202</p>
Brianff0cc922007-02-22 16:29:48 -0700[diff] [blame]203<pre>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]204 make realclean
205 make linux
Brian Paul3bfedb72008-07-17 15:40:10 -0600[diff] [blame]206 cd src/mesa/drivers/glslcompiler
Brianff0cc922007-02-22 16:29:48 -0700[diff] [blame]207 make
208</pre>
209
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]210
211<p>
212Here's an example of using the compiler to compile a vertex shader and
213emit GL_ARB_vertex_program-style instructions:
214</p>
215<pre>
Brian Paul3bfedb72008-07-17 15:40:10 -0600[diff] [blame]216 bin/glslcompiler --debug --numbers --fs progs/glsl/CH06-brick.frag.txt
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]217</pre>
218<p>
Brian Paul3bfedb72008-07-17 15:40:10 -0600[diff] [blame]219results in:
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]220</p>
221<pre>
Brian Paul3bfedb72008-07-17 15:40:10 -0600[diff] [blame]222# Fragment Program/Shader
223 0: RCP TEMP[4].x, UNIFORM[2].xxxx;
224 1: RCP TEMP[4].y, UNIFORM[2].yyyy;
225 2: MUL TEMP[3].xy, VARYING[0], TEMP[4];
226 3: MOV TEMP[1], TEMP[3];
227 4: MUL TEMP[0].w, TEMP[1].yyyy, CONST[4].xxxx;
228 5: FRC TEMP[1].z, TEMP[0].wwww;
229 6: SGT.C TEMP[0].w, TEMP[1].zzzz, CONST[4].xxxx;
230 7: IF (NE.wwww); # (if false, goto 9);
231 8: ADD TEMP[1].x, TEMP[1].xxxx, CONST[4].xxxx;
232 9: ENDIF;
233 10: FRC TEMP[1].xy, TEMP[1];
234 11: SGT TEMP[2].xy, UNIFORM[3], TEMP[1];
235 12: MUL TEMP[1].z, TEMP[2].xxxx, TEMP[2].yyyy;
236 13: LRP TEMP[0], TEMP[1].zzzz, UNIFORM[0], UNIFORM[1];
237 14: MUL TEMP[0].xyz, TEMP[0], VARYING[1].xxxx;
238 15: MOV OUTPUT[0].xyz, TEMP[0];
239 16: MOV OUTPUT[0].w, CONST[4].yyyy;
240 17: END
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]241</pre>
242
243<p>
244Note that some shading language constructs (such as uniform and varying
245variables) aren't expressible in ARB or NV-style programs.
246Therefore, the resulting output is not always legal by definition of
247those program languages.
248</p>
249<p>
250Also note that this compiler driver is still under development.
251Over time, the correctness of the GPU programs, with respect to the ARB
252and NV languagues, should improve.
253</p>
254
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]255
256
257<a name="implementation">
258<h2>Compiler Implementation</h2>
259
260<p>
261The source code for Mesa's shading language compiler is in the
262<code>src/mesa/shader/slang/</code> directory.
263</p>
264
265<p>
266The compiler follows a fairly standard design and basically works as follows:
267</p>
268<ul>
269<li>The input string is tokenized (see grammar.c) and parsed
270(see slang_compiler_*.c) to produce an Abstract Syntax Tree (AST).
271The nodes in this tree are slang_operation structures
272(see slang_compile_operation.h).
273The nodes are decorated with symbol table, scoping and datatype information.
274<li>The AST is converted into an Intermediate representation (IR) tree
275(see the slang_codegen.c file).
276The IR nodes represent basic GPU instructions, like add, dot product,
277move, etc.
278The IR tree is mostly a binary tree, but a few nodes have three or four
279children.
280In principle, the IR tree could be executed by doing an in-order traversal.
281<li>The IR tree is traversed in-order to emit code (see slang_emit.c).
282This is also when registers are allocated to store variables and temps.
283<li>In the future, a pattern-matching code generator-generator may be
284used for code generation.
285Programs such as L-BURG (Bottom-Up Rewrite Generator) and Twig look for
286patterns in IR trees, compute weights for subtrees and use the weights
287to select the best instructions to represent the sub-tree.
288<li>The emitted GPU instructions (see prog_instruction.h) are stored in a
289gl_program object (see mtypes.h).
290<li>When a fragment shader and vertex shader are linked (see slang_link.c)
291the varying vars are matched up, uniforms are merged, and vertex
292attributes are resolved (rewriting instructions as needed).
293</ul>
294
295<p>
296The final vertex and fragment programs may be interpreted in software
297(see prog_execute.c) or translated into a specific hardware architecture
298(see drivers/dri/i915/i915_fragprog.c for example).
299</p>
300
Brian8f9db0f2007-03-23 17:49:19 -0600[diff] [blame]301<h3>Code Generation Options</h3>
302
303<p>
304Internally, there are several options that control the compiler's code
305generation and instruction selection.
306These options are seen in the gl_shader_state struct and may be set
307by the device driver to indicate its preferences:
308
309<pre>
310struct gl_shader_state
311{
312 ...
313 /** Driver-selectable options: */
314 GLboolean EmitHighLevelInstructions;
315 GLboolean EmitCondCodes;
316 GLboolean EmitComments;
317};
318</pre>
319
320<ul>
321<li>EmitHighLevelInstructions
322<br>
323This option controls instruction selection for loops and conditionals.
324If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
325instructions will be emitted.
326Otherwise, those constructs will be implemented with BRA instructions.
327</li>
328
329<li>EmitCondCodes
330<br>
331If set, condition codes (ala GL_NV_fragment_program) will be used for
332branching and looping.
333Otherwise, ordinary registers will be used (the IF instruction will
334examine the first operand's X component and do the if-part if non-zero).
335This option is only relevant if EmitHighLevelInstructions is set.
336</li>
337
338<li>EmitComments
339<br>
340If set, instructions will be annoted with comments to help with debugging.
341Extra NOP instructions will also be inserted.
342</br>
343
344</ul>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]345
346
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]347<a name="validation">
348<h2>Compiler Validation</h2>
349
350<p>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]351A <a href="http://glean.sf.net" target="_parent">Glean</a> test has
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]352been create to exercise the GLSL compiler.
353</p>
354<p>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]355The <em>glsl1</em> test runs over 170 sub-tests to check that the language
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]356features and built-in functions work properly.
357This test should be run frequently while working on the compiler to catch
358regressions.
359</p>
360<p>
361The test coverage is reasonably broad and complete but additional tests
362should be added.
363</p>
364
365
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]366</BODY>
367</HTML>