← Back to branch summary

~ubuntu-branches/ubuntu/natty/mesa/natty-proposed

« back to all changes in this revision

Viewing changes to docs/shading.html

  • Committer: Bazaar Package Importer
  • Author(s): Robert Hooker, Robert Hooker, Christopher James Halse Rogers
  • Date: 2010-09-14 08:55:40 UTC
  • mfrom: (1.2.28 upstream)
  • Revision ID: james.westby@ubuntu.com-20100914085540-m4fpl0hdjlfd4jgz
Tags: 7.9~git20100909-0ubuntu1
https://launchpad.net/bugs/631413
https://launchpad.net/bugs/628930
https://launchpad.net/bugs/628727
https://launchpad.net/bugs/596292
https://launchpad.net/bugs/599741
https://launchpad.net/bugs/630315
https://launchpad.net/bugs/613694
https://launchpad.net/bugs/599741
https://launchpad.net/bugs/578619
https://launchpad.net/bugs/626943
https://launchpad.net/bugs/610541
https://launchpad.net/bugs/601052
[ Robert Hooker ]
* New upstream git snapshot up to commit 94118fe2d4b1e5 (LP: #631413)
* New features include ATI HD5xxx series support in r600, and a vastly
  improved glsl compiler.
* Remove pre-generated .pc's, use the ones generated at build time
  instead.
* Remove all references to mesa-utils now that its no longer shipped
  with the mesa source.
* Disable the experimental ARB_fragment_shader option by default on
  i915, it exposes incomplete functionality that breaks KDE compositing
  among other things. It can be enabled via driconf still. (LP: #628930).

[ Christopher James Halse Rogers ]
* debian/patches/04_osmesa_version.diff:
  - Refresh for new upstream
* Bugs fixed in this release:
  - Fixes severe rendering corruption in Unity on radeon (LP: #628727,
    LP: #596292, LP: #599741, LP: #630315, LP: #613694, LP: #599741).
  - Also fixes rendering in gnome-shell (LP: #578619).
  - Flickering in OpenGL apps on radeon (LP: #626943, LP: #610541).
  - Provides preliminary support for new intel chips (LP: #601052).
* debian/rules:
  - Update configure flags to match upstream reshuffling.
  - Explicitly remove gallium DRI drivers that we don't want to ship.
* Update debian/gbp.conf for this Maverick-specific packaging
* libegl1-mesa-dri-x11,kms: There are no longer separate kms or x11 drivers
  for EGL, libegl1-mesa-drivers now contains a single driver that provides
  both backends.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/shading.html
39
39
execution.  These are generally used for debugging.
40
40
</p>
41
41
<ul>
42
 
<li>dump - print GLSL shader code to stdout at link time
43
 
<li>log - log all GLSL shaders to files.
 
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
44
    The filenames will be "shader_X.vert" or "shader_X.frag" where X
45
45
    the shader ID.
46
 
<li>nopt - disable compiler optimizations
47
 
<li>opt - force compiler optimizations
48
 
<li>uniform - print message to stdout when glUniform is called
49
 
<li>nopvert - force vertex shaders to be a simple shader that just transforms
 
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
50
    the vertex position with ftransform() and passes through the color and
51
51
    texcoord[0] attributes.
52
 
<li>nopfrag - force fragment shader to be a simple shader that passes
 
52
<li><b>nopfrag</b> - force fragment shader to be a simple shader that passes
53
53
    through the color attribute.
54
 
<li>useprog - log glUseProgram calls to stderr
 
54
<li><b>useprog</b> - log glUseProgram calls to stderr
55
55
</ul>
56
56
<p>
57
57
Example:  export MESA_GLSL=dump,nopt
59
59
 
60
60
 
61
61
<a name="120">
62
 
<h2>GLSL 1.20 support</h2>
63
 
 
64
 
<p>
65
 
GLSL version 1.20 is supported in Mesa 7.3 and later.
66
 
Among the features/differences of GLSL 1.20 are:
 
62
<h2>GLSL Version</h2>
 
63
 
 
64
<p>
 
65
The GLSL compiler currently supports version 1.20 of the shading language.
 
66
</p>
 
67
 
 
68
<p>
 
69
Several GLSL extensions are also supported:
 
70
</p>
67
71
<ul>
68
 
<li><code>mat2x3, mat2x4</code>, etc. types and functions
69
 
<li><code>transpose(), outerProduct(), matrixCompMult()</code> functions
70
 
(but untested)
71
 
<li>precision qualifiers (lowp, mediump, highp)
72
 
<li><code>invariant</code> qualifier
73
 
<li><code>array.length()</code> method
74
 
<li><code>float[5] a;</code> array syntax
75
 
<li><code>centroid</code> qualifier
76
 
<li>unsized array constructors
77
 
<li>initializers for uniforms
78
 
<li>const initializers calling built-in functions
 
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
79
76
</ul>
80
77
 
81
78
 
82
 
 
83
79
<a name="unsup">
84
80
<h2>Unsupported Features</h2>
85
81
 
 
82
<p>XXX update this section</p>
 
83
 
86
84
<p>
87
85
The following features of the shading language are not yet fully supported
88
86
in Mesa:
130
128
<h2>Programming Hints</h2>
131
129
 
132
130
<ul>
133
 
<li>Declare <em>in</em> function parameters as <em>const</em> whenever possible.
134
 
    This improves the efficiency of function inlining.
135
 
</li>
136
 
<br>
137
 
<li>To reduce register usage, declare variables within smaller scopes.
138
 
    For example, the following code:
139
 
<pre>
140
 
    void main()
141
 
    {
142
 
       vec4 a1, a2, b1, b2;
143
 
       gl_Position = expression using a1, a2.
144
 
       gl_Color = expression using b1, b2;
145
 
    }
146
 
</pre>
147
 
    Can be rewritten as follows to use half as many registers:
148
 
<pre>
149
 
    void main()
150
 
    {
151
 
       {
152
 
          vec4 a1, a2;
153
 
          gl_Position = expression using a1, a2.
154
 
       }
155
 
       {
156
 
          vec4 b1, b2;
157
 
          gl_Color = expression using b1, b2;
158
 
       }
159
 
    }
160
 
</pre>
161
 
    Alternately, rather than using several float variables, use
162
 
    a vec4 instead.  Use swizzling and writemasks to access the
163
 
    components of the vec4 as floats.
164
 
</li>
165
 
<br>
166
131
<li>Use the built-in library functions whenever possible.
167
132
    For example, instead of writing this:
168
133
<pre>
172
137
<pre>
173
138
        float x = inversesqrt(y);
174
139
</pre>
175
 
<li>
176
 
   Use ++i when possible as it's more efficient than i++
177
140
</li>
178
141
</ul>
179
142
 
182
145
<h2>Stand-alone GLSL Compiler</h2>
183
146
 
184
147
<p>
185
 
A unique stand-alone GLSL compiler driver has been added to Mesa.
186
 
<p>
187
 
 
188
 
<p>
189
 
The stand-alone compiler (like a conventional command-line compiler)
190
 
is a tool that accepts Shading Language programs and emits low-level
191
 
GPU programs.
 
148
The stand-alone GLSL compiler program can be used to compile GLSL shaders
 
149
into low-level GPU code.
192
150
</p>
193
151
 
194
152
<p>
201
159
</ul>
202
160
 
203
161
<p>
204
 
After building Mesa, the glslcompiler can be built by manually running:
 
162
After building Mesa, the compiler can be found at src/glsl/glsl_compiler
205
163
</p>
206
 
<pre>
207
 
    make realclean
208
 
    make linux
209
 
    cd src/mesa/drivers/glslcompiler
210
 
    make
211
 
</pre>
212
 
 
213
164
 
214
165
<p>
215
166
Here's an example of using the compiler to compile a vertex shader and
216
167
emit GL_ARB_vertex_program-style instructions:
217
168
</p>
218
169
<pre>
219
 
    bin/glslcompiler --debug --numbers --fs progs/glsl/CH06-brick.frag.txt
220
 
</pre>
221
 
<p>
222
 
results in:
223
 
</p>
224
 
<pre>
225
 
# Fragment Program/Shader
226
 
  0: RCP TEMP[4].x, UNIFORM[2].xxxx;
227
 
  1: RCP TEMP[4].y, UNIFORM[2].yyyy;
228
 
  2: MUL TEMP[3].xy, VARYING[0], TEMP[4];
229
 
  3: MOV TEMP[1], TEMP[3];
230
 
  4: MUL TEMP[0].w, TEMP[1].yyyy, CONST[4].xxxx;
231
 
  5: FRC TEMP[1].z, TEMP[0].wwww;
232
 
  6: SGT.C TEMP[0].w, TEMP[1].zzzz, CONST[4].xxxx;
233
 
  7: IF (NE.wwww); # (if false, goto 9);
234
 
  8:    ADD TEMP[1].x, TEMP[1].xxxx, CONST[4].xxxx;
235
 
  9: ENDIF;
236
 
 10: FRC TEMP[1].xy, TEMP[1];
237
 
 11: SGT TEMP[2].xy, UNIFORM[3], TEMP[1];
238
 
 12: MUL TEMP[1].z, TEMP[2].xxxx, TEMP[2].yyyy;
239
 
 13: LRP TEMP[0], TEMP[1].zzzz, UNIFORM[0], UNIFORM[1];
240
 
 14: MUL TEMP[0].xyz, TEMP[0], VARYING[1].xxxx;
241
 
 15: MOV OUTPUT[0].xyz, TEMP[0];
242
 
 16: MOV OUTPUT[0].w, CONST[4].yyyy;
243
 
 17: END
244
 
</pre>
245
 
 
246
 
<p>
247
 
Note that some shading language constructs (such as uniform and varying
248
 
variables) aren't expressible in ARB or NV-style programs.
249
 
Therefore, the resulting output is not always legal by definition of
250
 
those program languages.
251
 
</p>
252
 
<p>
253
 
Also note that this compiler driver is still under development.
254
 
Over time, the correctness of the GPU programs, with respect to the ARB
255
 
and NV languagues, should improve.
256
 
</p>
 
170
    src/glsl/glslcompiler --dump-ast myshader.vert
 
171
</pre>
 
172
 
 
173
Options include
 
174
<ul>
 
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> - ???
 
179
</ul>
 
180
 
257
181
 
258
182
 
259
183
 
262
186
 
263
187
<p>
264
188
The source code for Mesa's shading language compiler is in the
265
 
<code>src/mesa/shader/slang/</code> directory.
 
189
<code>src/glsl/</code> directory.
266
190
</p>
267
191
 
268
192
<p>
269
 
The compiler follows a fairly standard design and basically works as follows:
 
193
XXX provide some info about the compiler....
270
194
</p>
271
 
<ul>
272
 
<li>The input string is tokenized (see grammar.c) and parsed
273
 
(see slang_compiler_*.c) to produce an Abstract Syntax Tree (AST).
274
 
The nodes in this tree are slang_operation structures
275
 
(see slang_compile_operation.h).
276
 
The nodes are decorated with symbol table, scoping and datatype information.
277
 
<li>The AST is converted into an Intermediate representation (IR) tree
278
 
(see the slang_codegen.c file).
279
 
The IR nodes represent basic GPU instructions, like add, dot product,
280
 
move, etc. 
281
 
The IR tree is mostly a binary tree, but a few nodes have three or four
282
 
children.
283
 
In principle, the IR tree could be executed by doing an in-order traversal.
284
 
<li>The IR tree is traversed in-order to emit code (see slang_emit.c).
285
 
This is also when registers are allocated to store variables and temps.
286
 
<li>In the future, a pattern-matching code generator-generator may be
287
 
used for code generation.
288
 
Programs such as L-BURG (Bottom-Up Rewrite Generator) and Twig look for
289
 
patterns in IR trees, compute weights for subtrees and use the weights
290
 
to select the best instructions to represent the sub-tree.
291
 
<li>The emitted GPU instructions (see prog_instruction.h) are stored in a
292
 
gl_program object (see mtypes.h).
293
 
<li>When a fragment shader and vertex shader are linked (see slang_link.c)
294
 
the varying vars are matched up, uniforms are merged, and vertex
295
 
attributes are resolved (rewriting instructions as needed).
296
 
</ul>
297
195
 
298
196
<p>
299
197
The final vertex and fragment programs may be interpreted in software
351
249
<h2>Compiler Validation</h2>
352
250
 
353
251
<p>
354
 
A <a href="http://glean.sf.net" target="_parent">Glean</a> test has
355
 
been create to exercise the GLSL compiler.
356
 
</p>
357
 
<p>
358
 
The <em>glsl1</em> test runs over 170 sub-tests to check that the language
359
 
features and built-in functions work properly.
360
 
This test should be run frequently while working on the compiler to catch
 
252
Developers working on the GLSL compiler should test frequently to avoid
361
253
regressions.
362
254
</p>
363
 
<p>
364
 
The test coverage is reasonably broad and complete but additional tests
365
 
should be added.
366
 
</p>
367
 
 
 
255
 
 
256
<p>
 
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 
 
260
tests GLSL features.
 
261
</p>
 
262
 
 
263
<p>
 
264
The Mesa demos repository also has some good GLSL tests.
 
265
</p>
368
266
 
369
267
</BODY>
370
268
</HTML>