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