Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / d52419e0c3b2916609a9707b66195ac41020ebdb / . / docs / shading.html
blob: 371891711d7b4a80218079b1539d8dd3cd8e682a [file] [log] [blame]
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html lang="en">
3<head>
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">
7</head>
8<body>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]9
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]10<h1>Shading Language Support</h1>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]11
12<p>
13This page describes the features and status of Mesa's support for the
14<a href="http://opengl.org/documentation/glsl/" target="_parent">
15OpenGL Shading Language</a>.
16</p>
17
18<p>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]19Contents
20</p>
21<ul>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]22<li><a href="#envvars">Environment variables</a>
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]23<li><a href="#glsl120">GLSL 1.20 support</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]24<li><a href="#unsup">Unsupported Features</a>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]25<li><a href="#notes">Implementation Notes</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]26<li><a href="#hints">Programming Hints</a>
Brian Paul3bfedb72008-07-17 15:40:10 -0600[diff] [blame]27<li><a href="#standalone">Stand-alone GLSL Compiler</a>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]28<li><a href="#implementation">Compiler Implementation</a>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]29<li><a href="#validation">Compiler Validation</a>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]30</ul>
31
32
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]33<h2 id="envvars">Environment Variables</h2>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]34
35<p>
36The <b>MESA_GLSL</b> environment variable can be set to a comma-separated
Brian Paul85fb3e42009-10-14 11:28:28 -0600[diff] [blame]37list of keywords to control some aspects of the GLSL compiler and shader
38execution. These are generally used for debugging.
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]39</p>
40<ul>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]41<li><b>dump</b> - print GLSL shader code to stdout at link time
42<li><b>log</b> - log all GLSL shaders to files.
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]43 The filenames will be "shader_X.vert" or "shader_X.frag" where X
44 the shader ID.
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]45<li><b>nopt</b> - disable compiler optimizations
46<li><b>opt</b> - force compiler optimizations
47<li><b>uniform</b> - print message to stdout when glUniform is called
48<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]49 the vertex position with ftransform() and passes through the color and
50 texcoord[0] attributes.
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]51<li><b>nopfrag</b> - force fragment shader to be a simple shader that passes
Brian Paul85fb3e42009-10-14 11:28:28 -0600[diff] [blame]52 through the color attribute.
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]53<li><b>useprog</b> - log glUseProgram calls to stderr
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]54</ul>
55<p>
56Example: export MESA_GLSL=dump,nopt
57</p>
58
59
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]60<h2 id="glsl120">GLSL Version</h2>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]61
62<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]63The GLSL compiler currently supports version 1.20 of the shading language.
64</p>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]65
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]66<p>
67Several GLSL extensions are also supported:
68</p>
69<ul>
70<li>GL_ARB_draw_buffers
71<li>GL_ARB_texture_rectangle
72<li>GL_ARB_fragment_coord_conventions
73<li>GL_EXT_texture_array
74</ul>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]75
76
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]77<h2 id="unsup">Unsupported Features</h2>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]78
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]79<p>XXX update this section</p>
80
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]81<p>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]82The following features of the shading language are not yet fully supported
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]83in Mesa:
84</p>
85
86<ul>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]87<li>Linking of multiple shaders does not always work. Currently, linking
88 is implemented through shader concatenation and re-compiling. This
89 doesn't always work because of some #pragma and preprocessor issues.
Brianb03e1712007-03-09 09:51:55 -0700[diff] [blame]90<li>gl_ClipVertex
Brian4b1d1b72007-04-27 15:25:00 -0600[diff] [blame]91<li>The gl_Color and gl_SecondaryColor varying vars are interpolated
92 without perspective correction
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]93</ul>
94
95<p>
96All other major features of the shading language should function.
97</p>
98
99
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]100<h2 id="notes">Implementation Notes</h2>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]101
102<ul>
103<li>Shading language programs are compiled into low-level programs
104 very similar to those of GL_ARB_vertex/fragment_program.
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]105<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]106 float[4] registers.
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]107<li>Float constants and variables are packed so that up to four floats
108 can occupy one program parameter/register.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]109<li>All function calls are inlined.
110<li>Shaders which use too many registers will not compile.
111<li>The quality of generated code is pretty good, register usage is fair.
112<li>Shader error detection and reporting of errors (InfoLog) is not
113 very good yet.
Brian05e6fd82007-03-27 16:05:25 -0600[diff] [blame]114<li>The ftransform() function doesn't necessarily match the results of
115 fixed-function transformation.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]116</ul>
117
118<p>
119These issues will be addressed/resolved in the future.
120</p>
121
122
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]123<h2 id="hints">Programming Hints</h2>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]124
125<ul>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]126<li>Use the built-in library functions whenever possible.
127 For example, instead of writing this:
128<pre>
129 float x = 1.0 / sqrt(y);
130</pre>
131 Write this:
132<pre>
133 float x = inversesqrt(y);
134</pre>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]135</li>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]136</ul>
137
138
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]139<h2 id="standalone">Stand-alone GLSL Compiler</h2>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]140
141<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]142The stand-alone GLSL compiler program can be used to compile GLSL shaders
143into low-level GPU code.
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]144</p>
145
146<p>
147This tool is useful for:
Andreas Bolldf2be222012-06-12 09:05:22 +0200[diff] [blame]148</p>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]149<ul>
150<li>Inspecting GPU code to gain insight into compilation
151<li>Generating initial GPU code for subsequent hand-tuning
152<li>Debugging the GLSL compiler itself
153</ul>
154
155<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]156After building Mesa, the compiler can be found at src/glsl/glsl_compiler
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]157</p>
158
159<p>
160Here's an example of using the compiler to compile a vertex shader and
161emit GL_ARB_vertex_program-style instructions:
162</p>
163<pre>
Sam Hocevarfde49432011-02-16 17:04:03 -0700[diff] [blame]164 src/glsl/glsl_compiler --dump-ast myshader.vert
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]165</pre>
166
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]167Options include
168<ul>
169<li><b>--dump-ast</b> - dump GPU code
170<li><b>--dump-hir</b> - dump high-level IR code
171<li><b>--dump-lir</b> - dump low-level IR code
172<li><b>--link</b> - ???
173</ul>
174
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]175
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]176<h2 id="implementation">Compiler Implementation</h2>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]177
178<p>
179The source code for Mesa's shading language compiler is in the
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]180<code>src/glsl/</code> directory.
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]181</p>
182
183<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]184XXX provide some info about the compiler....
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]185</p>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]186
187<p>
188The final vertex and fragment programs may be interpreted in software
189(see prog_execute.c) or translated into a specific hardware architecture
190(see drivers/dri/i915/i915_fragprog.c for example).
191</p>
192
Brian8f9db0f2007-03-23 17:49:19 -0600[diff] [blame]193<h3>Code Generation Options</h3>
194
195<p>
196Internally, there are several options that control the compiler's code
197generation and instruction selection.
198These options are seen in the gl_shader_state struct and may be set
199by the device driver to indicate its preferences:
200
201<pre>
202struct gl_shader_state
203{
204 ...
205 /** Driver-selectable options: */
206 GLboolean EmitHighLevelInstructions;
207 GLboolean EmitCondCodes;
208 GLboolean EmitComments;
209};
210</pre>
211
Andreas Bolld52419e2012-06-25 21:51:28 +0200[diff] [blame^]212<dl>
213<dt>EmitHighLevelInstructions</dt>
214<dd>
Brian8f9db0f2007-03-23 17:49:19 -0600[diff] [blame]215This option controls instruction selection for loops and conditionals.
216If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
217instructions will be emitted.
218Otherwise, those constructs will be implemented with BRA instructions.
Andreas Bolld52419e2012-06-25 21:51:28 +0200[diff] [blame^]219</dd>
Brian8f9db0f2007-03-23 17:49:19 -0600[diff] [blame]220
Andreas Bolld52419e2012-06-25 21:51:28 +0200[diff] [blame^]221<dt>EmitCondCodes</dt>
222<dd>
Brian8f9db0f2007-03-23 17:49:19 -0600[diff] [blame]223If set, condition codes (ala GL_NV_fragment_program) will be used for
224branching and looping.
225Otherwise, ordinary registers will be used (the IF instruction will
226examine the first operand's X component and do the if-part if non-zero).
227This option is only relevant if EmitHighLevelInstructions is set.
Andreas Bolld52419e2012-06-25 21:51:28 +0200[diff] [blame^]228</dd>
Brian8f9db0f2007-03-23 17:49:19 -0600[diff] [blame]229
Andreas Bolld52419e2012-06-25 21:51:28 +0200[diff] [blame^]230<dt>EmitComments</dt>
231<dd>
Brian8f9db0f2007-03-23 17:49:19 -0600[diff] [blame]232If set, instructions will be annoted with comments to help with debugging.
233Extra NOP instructions will also be inserted.
Andreas Bolld52419e2012-06-25 21:51:28 +0200[diff] [blame^]234</dd>
235</dl>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]236
237
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]238<h2 id="validation">Compiler Validation</h2>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]239
240<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]241Developers working on the GLSL compiler should test frequently to avoid
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]242regressions.
243</p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]244
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]245<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]246The <a href="http://people.freedesktop.org/~nh/piglit/">Piglit</a> project
247has many GLSL tests and the
248<a href="http://glean.sf.net" target="_parent">Glean</a> glsl1 test
249tests GLSL features.
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]250</p>
251
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]252<p>
253The Mesa demos repository also has some good GLSL tests.
254</p>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]255
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]256</body>
257</html>