Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / 4fe3bf2d77aeb289d2f1c7c695206c2e7889c5ed / . / docs / shading.html
blob: 0e1a5e1a7bcec5e639fc2bcdd59a980df976f2d2 [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>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]18Last updated on 28 March 2007.
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>
25<li><a href="#unsup">Unsupported Features</a>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]26<li><a href="#notes">Implementation Notes</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]27<li><a href="#hints">Programming Hints</a>
28<li><a href="#standalone">Stand-alone Compiler</a>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]29<li><a href="#implementation">Compiler Implementation</a>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]30<li><a href="#validation">Compiler Validation</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]31</ul>
32
33
34<a name="unsup">
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]35<h2>Unsupported Features</h2>
36
37<p>
38The following features of the shading language are not yet supported
39in Mesa:
40</p>
41
42<ul>
Brian6d4cf6b2007-02-21 16:07:03 -0700[diff] [blame]43<li>Dereferencing arrays with non-constant indexes
Brianb67d9312007-03-26 10:23:50 -0600[diff] [blame]44<li>Comparison of user-defined structs
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]45<li>Linking of multiple shaders is not supported
Brianb03e1712007-03-09 09:51:55 -0700[diff] [blame]46<li>gl_ClipVertex
Brianba3d3842007-04-19 14:24:29 -0600[diff] [blame]47<li>The derivative functions such as dFdx() are not implemented
Brian7ff72a72007-04-27 15:23:19 -0600[diff] [blame]48<li>The inverse trig functions asin(), acos(), and atan() are not implemented
Brian4b1d1b72007-04-27 15:25:00 -0600[diff] [blame]49<li>The gl_Color and gl_SecondaryColor varying vars are interpolated
50 without perspective correction
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]51</ul>
52
53<p>
54All other major features of the shading language should function.
55</p>
56
57
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]58<a name="notes">
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]59<h2>Implementation Notes</h2>
60
61<ul>
62<li>Shading language programs are compiled into low-level programs
63 very similar to those of GL_ARB_vertex/fragment_program.
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]64<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]65 float[4] registers.
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]66<li>Float constants and variables are packed so that up to four floats
67 can occupy one program parameter/register.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]68<li>All function calls are inlined.
69<li>Shaders which use too many registers will not compile.
70<li>The quality of generated code is pretty good, register usage is fair.
71<li>Shader error detection and reporting of errors (InfoLog) is not
72 very good yet.
Brian05e6fd82007-03-27 16:05:25 -0600[diff] [blame]73<li>The ftransform() function doesn't necessarily match the results of
74 fixed-function transformation.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]75</ul>
76
77<p>
78These issues will be addressed/resolved in the future.
79</p>
80
81
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]82<a name="hints">
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]83<h2>Programming Hints</h2>
84
85<ul>
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]86<li>Declare <em>in</em> function parameters as <em>const</em> whenever possible.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]87 This improves the efficiency of function inlining.
88</li>
89<br>
90<li>To reduce register usage, declare variables within smaller scopes.
91 For example, the following code:
92<pre>
93 void main()
94 {
95 vec4 a1, a2, b1, b2;
96 gl_Position = expression using a1, a2.
97 gl_Color = expression using b1, b2;
98 }
99</pre>
100 Can be rewritten as follows to use half as many registers:
101<pre>
102 void main()
103 {
104 {
105 vec4 a1, a2;
106 gl_Position = expression using a1, a2.
107 }
108 {
109 vec4 b1, b2;
110 gl_Color = expression using b1, b2;
111 }
112 }
113</pre>
114 Alternately, rather than using several float variables, use
115 a vec4 instead. Use swizzling and writemasks to access the
116 components of the vec4 as floats.
117</li>
118<br>
119<li>Use the built-in library functions whenever possible.
120 For example, instead of writing this:
121<pre>
122 float x = 1.0 / sqrt(y);
123</pre>
124 Write this:
125<pre>
126 float x = inversesqrt(y);
127</pre>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]128<li>
129 Use ++i when possible as it's more efficient than i++
130</li>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]131</ul>
132
133
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]134<a name="standalone">
135<h2>Stand-alone Compiler</h2>
136
137<p>
138A unique stand-alone GLSL compiler driver has been added to Mesa.
139<p>
140
141<p>
142The stand-alone compiler (like a conventional command-line compiler)
143is a tool that accepts Shading Language programs and emits low-level
144GPU programs.
145</p>
146
147<p>
148This tool is useful for:
149<p>
150<ul>
151<li>Inspecting GPU code to gain insight into compilation
152<li>Generating initial GPU code for subsequent hand-tuning
153<li>Debugging the GLSL compiler itself
154</ul>
155
156<p>
Brianff0cc922007-02-22 16:29:48 -0700[diff] [blame]157To build the glslcompiler program (this will be improved someday):
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]158</p>
Brianff0cc922007-02-22 16:29:48 -0700[diff] [blame]159<pre>
160 cd src/mesa
161 make libmesa.a
162 cd drivers/glslcompiler
163 make
164</pre>
165
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]166
167<p>
168Here's an example of using the compiler to compile a vertex shader and
169emit GL_ARB_vertex_program-style instructions:
170</p>
171<pre>
172 glslcompiler --arb --linenumbers --vs vertshader.txt
173</pre>
174<p>
175The output may look similar to this:
176</p>
177<pre>
178!!ARBvp1.0
179 0: MOV result.texcoord[0], vertex.texcoord[0];
180 1: DP4 temp0.x, state.matrix.mvp.row[0], vertex.position;
181 2: DP4 temp0.y, state.matrix.mvp.row[1], vertex.position;
182 3: DP4 temp0.z, state.matrix.mvp.row[2], vertex.position;
183 4: DP4 temp0.w, state.matrix.mvp.row[3], vertex.position;
184 5: MOV result.position, temp0;
185 6: END
186</pre>
187
188<p>
189Note that some shading language constructs (such as uniform and varying
190variables) aren't expressible in ARB or NV-style programs.
191Therefore, the resulting output is not always legal by definition of
192those program languages.
193</p>
194<p>
195Also note that this compiler driver is still under development.
196Over time, the correctness of the GPU programs, with respect to the ARB
197and NV languagues, should improve.
198</p>
199
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]200
201
202<a name="implementation">
203<h2>Compiler Implementation</h2>
204
205<p>
206The source code for Mesa's shading language compiler is in the
207<code>src/mesa/shader/slang/</code> directory.
208</p>
209
210<p>
211The compiler follows a fairly standard design and basically works as follows:
212</p>
213<ul>
214<li>The input string is tokenized (see grammar.c) and parsed
215(see slang_compiler_*.c) to produce an Abstract Syntax Tree (AST).
216The nodes in this tree are slang_operation structures
217(see slang_compile_operation.h).
218The nodes are decorated with symbol table, scoping and datatype information.
219<li>The AST is converted into an Intermediate representation (IR) tree
220(see the slang_codegen.c file).
221The IR nodes represent basic GPU instructions, like add, dot product,
222move, etc.
223The IR tree is mostly a binary tree, but a few nodes have three or four
224children.
225In principle, the IR tree could be executed by doing an in-order traversal.
226<li>The IR tree is traversed in-order to emit code (see slang_emit.c).
227This is also when registers are allocated to store variables and temps.
228<li>In the future, a pattern-matching code generator-generator may be
229used for code generation.
230Programs such as L-BURG (Bottom-Up Rewrite Generator) and Twig look for
231patterns in IR trees, compute weights for subtrees and use the weights
232to select the best instructions to represent the sub-tree.
233<li>The emitted GPU instructions (see prog_instruction.h) are stored in a
234gl_program object (see mtypes.h).
235<li>When a fragment shader and vertex shader are linked (see slang_link.c)
236the varying vars are matched up, uniforms are merged, and vertex
237attributes are resolved (rewriting instructions as needed).
238</ul>
239
240<p>
241The final vertex and fragment programs may be interpreted in software
242(see prog_execute.c) or translated into a specific hardware architecture
243(see drivers/dri/i915/i915_fragprog.c for example).
244</p>
245
Brian8f9db0f2007-03-23 17:49:19 -0600[diff] [blame]246<h3>Code Generation Options</h3>
247
248<p>
249Internally, there are several options that control the compiler's code
250generation and instruction selection.
251These options are seen in the gl_shader_state struct and may be set
252by the device driver to indicate its preferences:
253
254<pre>
255struct gl_shader_state
256{
257 ...
258 /** Driver-selectable options: */
259 GLboolean EmitHighLevelInstructions;
260 GLboolean EmitCondCodes;
261 GLboolean EmitComments;
262};
263</pre>
264
265<ul>
266<li>EmitHighLevelInstructions
267<br>
268This option controls instruction selection for loops and conditionals.
269If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
270instructions will be emitted.
271Otherwise, those constructs will be implemented with BRA instructions.
272</li>
273
274<li>EmitCondCodes
275<br>
276If set, condition codes (ala GL_NV_fragment_program) will be used for
277branching and looping.
278Otherwise, ordinary registers will be used (the IF instruction will
279examine the first operand's X component and do the if-part if non-zero).
280This option is only relevant if EmitHighLevelInstructions is set.
281</li>
282
283<li>EmitComments
284<br>
285If set, instructions will be annoted with comments to help with debugging.
286Extra NOP instructions will also be inserted.
287</br>
288
289</ul>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]290
291
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]292<a name="validation">
293<h2>Compiler Validation</h2>
294
295<p>
296A new <a href="http://glean.sf.net" target="_parent">Glean</a> test has
297been create to exercise the GLSL compiler.
298</p>
299<p>
Brian8598f552007-04-18 09:30:07 -0600[diff] [blame]300The <em>glsl1</em> test runs over 150 sub-tests to check that the language
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]301features and built-in functions work properly.
302This test should be run frequently while working on the compiler to catch
303regressions.
304</p>
305<p>
306The test coverage is reasonably broad and complete but additional tests
307should be added.
308</p>
309
310
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]311</BODY>
312</HTML>