Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / aaceca16dfc57375cdb837b82b3d123e42710c65 / . / docs / shading.html
blob: c41d4a9be2b18e73bb6006774e5acc4d2e790782 [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>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]18Contents
19</p>
20<ul>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]21<li><a href="#envvars">Environment variables</a>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]22<li><a href="#120">GLSL 1.20 support</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]23<li><a href="#unsup">Unsupported Features</a>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]24<li><a href="#notes">Implementation Notes</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]25<li><a href="#hints">Programming Hints</a>
Brian Paul3bfedb72008-07-17 15:40:10 -0600[diff] [blame]26<li><a href="#standalone">Stand-alone GLSL Compiler</a>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]27<li><a href="#implementation">Compiler Implementation</a>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]28<li><a href="#validation">Compiler Validation</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]29</ul>
30
31
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]32
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]33<a name="envvars">
34<h2>Environment Variables</h2>
35
36<p>
37The <b>MESA_GLSL</b> environment variable can be set to a comma-separated
Brian Paul85fb3e42009-10-14 11:28:28 -0600[diff] [blame]38list of keywords to control some aspects of the GLSL compiler and shader
39execution. These are generally used for debugging.
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]40</p>
41<ul>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]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.
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]44 The filenames will be "shader_X.vert" or "shader_X.frag" where X
45 the shader ID.
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]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
Brian Paul85fb3e42009-10-14 11:28:28 -0600[diff] [blame]50 the vertex position with ftransform() and passes through the color and
51 texcoord[0] attributes.
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]52<li><b>nopfrag</b> - force fragment shader to be a simple shader that passes
Brian Paul85fb3e42009-10-14 11:28:28 -0600[diff] [blame]53 through the color attribute.
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]54<li><b>useprog</b> - log glUseProgram calls to stderr
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]55</ul>
56<p>
57Example: export MESA_GLSL=dump,nopt
58</p>
59
60
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]61<a name="120">
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]62<h2>GLSL Version</h2>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]63
64<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]65The GLSL compiler currently supports version 1.20 of the shading language.
66</p>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]67
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]68<p>
69Several GLSL extensions are also supported:
70</p>
71<ul>
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
76</ul>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]77
78
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]79<a name="unsup">
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]80<h2>Unsupported Features</h2>
81
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]82<p>XXX update this section</p>
83
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]84<p>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]85The following features of the shading language are not yet fully supported
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]86in Mesa:
87</p>
88
89<ul>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]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.
Brianb03e1712007-03-09 09:51:55 -0700[diff] [blame]93<li>gl_ClipVertex
Brian4b1d1b72007-04-27 15:25:00 -0600[diff] [blame]94<li>The gl_Color and gl_SecondaryColor varying vars are interpolated
95 without perspective correction
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]96</ul>
97
98<p>
99All other major features of the shading language should function.
100</p>
101
102
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]103<a name="notes">
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]104<h2>Implementation Notes</h2>
105
106<ul>
107<li>Shading language programs are compiled into low-level programs
108 very similar to those of GL_ARB_vertex/fragment_program.
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]109<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]110 float[4] registers.
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]111<li>Float constants and variables are packed so that up to four floats
112 can occupy one program parameter/register.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]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
117 very good yet.
Brian05e6fd82007-03-27 16:05:25 -0600[diff] [blame]118<li>The ftransform() function doesn't necessarily match the results of
119 fixed-function transformation.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]120</ul>
121
122<p>
123These issues will be addressed/resolved in the future.
124</p>
125
126
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]127<a name="hints">
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]128<h2>Programming Hints</h2>
129
130<ul>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]131<li>Use the built-in library functions whenever possible.
132 For example, instead of writing this:
133<pre>
134 float x = 1.0 / sqrt(y);
135</pre>
136 Write this:
137<pre>
138 float x = inversesqrt(y);
139</pre>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]140</li>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]141</ul>
142
143
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]144<a name="standalone">
Brian Paul3bfedb72008-07-17 15:40:10 -0600[diff] [blame]145<h2>Stand-alone GLSL Compiler</h2>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]146
147<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]148The stand-alone GLSL compiler program can be used to compile GLSL shaders
149into low-level GPU code.
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]150</p>
151
152<p>
153This tool is useful for:
154<p>
155<ul>
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
159</ul>
160
161<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]162After building Mesa, the compiler can be found at src/glsl/glsl_compiler
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]163</p>
164
165<p>
166Here's an example of using the compiler to compile a vertex shader and
167emit GL_ARB_vertex_program-style instructions:
168</p>
169<pre>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]170 src/glsl/glslcompiler --dump-ast myshader.vert
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]171</pre>
172
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]173Options 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
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]181
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]182
183
184<a name="implementation">
185<h2>Compiler Implementation</h2>
186
187<p>
188The source code for Mesa's shading language compiler is in the
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]189<code>src/glsl/</code> directory.
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]190</p>
191
192<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]193XXX provide some info about the compiler....
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]194</p>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]195
196<p>
197The 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).
200</p>
201
Brian8f9db0f2007-03-23 17:49:19 -0600[diff] [blame]202<h3>Code Generation Options</h3>
203
204<p>
205Internally, there are several options that control the compiler's code
206generation and instruction selection.
207These options are seen in the gl_shader_state struct and may be set
208by the device driver to indicate its preferences:
209
210<pre>
211struct gl_shader_state
212{
213 ...
214 /** Driver-selectable options: */
215 GLboolean EmitHighLevelInstructions;
216 GLboolean EmitCondCodes;
217 GLboolean EmitComments;
218};
219</pre>
220
221<ul>
222<li>EmitHighLevelInstructions
223<br>
224This option controls instruction selection for loops and conditionals.
225If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
226instructions will be emitted.
227Otherwise, those constructs will be implemented with BRA instructions.
228</li>
229
230<li>EmitCondCodes
231<br>
232If set, condition codes (ala GL_NV_fragment_program) will be used for
233branching and looping.
234Otherwise, ordinary registers will be used (the IF instruction will
235examine the first operand's X component and do the if-part if non-zero).
236This option is only relevant if EmitHighLevelInstructions is set.
237</li>
238
239<li>EmitComments
240<br>
241If set, instructions will be annoted with comments to help with debugging.
242Extra NOP instructions will also be inserted.
243</br>
244
245</ul>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]246
247
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]248<a name="validation">
249<h2>Compiler Validation</h2>
250
251<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]252Developers working on the GLSL compiler should test frequently to avoid
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]253regressions.
254</p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]255
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]256<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]257The <a href="http://people.freedesktop.org/~nh/piglit/">Piglit</a> project
258has many GLSL tests and the
259<a href="http://glean.sf.net" target="_parent">Glean</a> glsl1 test
260tests GLSL features.
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]261</p>
262
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]263<p>
264The Mesa demos repository also has some good GLSL tests.
265</p>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]266
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]267</BODY>
268</HTML>