Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / e9cf458fa8c60878a17bee6a0f0b5b11f88272a4 / . / docs / shading.html
blob: a0bbe997c1b8eeea572fa16260b4af329689cb9c [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
Eric Engestrom30cf9ff2017-02-09 02:10:17 +0000[diff] [blame]21<a href="https://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.
Timothy Arceri30aa22d2016-07-08 12:44:44 +1000[diff] [blame]52<li><b>cache_info</b> - print debug information about shader cache
Timothy Arceria74300c2017-05-18 15:00:40 +1000[diff] [blame]53<li><b>cache_fb</b> - force cached shaders to be ignored and do a full
54 recompile via the fallback path</li>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]55<li><b>uniform</b> - print message to stdout when glUniform is called
56<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]57 the vertex position with ftransform() and passes through the color and
58 texcoord[0] attributes.
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]59<li><b>nopfrag</b> - force fragment shader to be a simple shader that passes
Brian Paul85fb3e42009-10-14 11:28:28 -0600[diff] [blame]60 through the color attribute.
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]61<li><b>useprog</b> - log glUseProgram calls to stderr
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]62</ul>
63<p>
64Example: export MESA_GLSL=dump,nopt
65</p>
66
Kenneth Graunkee9cf4582017-09-11 15:47:55 -0700[diff] [blame^]67<h3 id="replacement">Experimenting with Shader Replacements</h3>
Tapani Pälli04e201d2015-08-31 09:54:23 +0300[diff] [blame]68<p>
Eleni Maria Stea9f59cb22017-08-04 20:20:12 +0300[diff] [blame]69Shaders can be dumped and replaced on runtime for debugging purposes. This
Tapani Pälli04e201d2015-08-31 09:54:23 +0300[diff] [blame]70feature is not currently supported by SCons build.
71
72This is controlled via following environment variables:
73<ul>
74<li><b>MESA_SHADER_DUMP_PATH</b> - path where shader sources are dumped
75<li><b>MESA_SHADER_READ_PATH</b> - path where replacement shaders are read
76</ul>
77Note, path set must exist before running for dumping or replacing to work.
78When both are set, these paths should be different so the dumped shaders do
Eleni Maria Stea9f59cb22017-08-04 20:20:12 +0300[diff] [blame]79not clobber the replacement shaders. Also, the filenames of the replacement shaders
80should match the filenames of the corresponding dumped shaders.
Tapani Pälli04e201d2015-08-31 09:54:23 +0300[diff] [blame]81</p>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]82
Kenneth Graunkee9cf4582017-09-11 15:47:55 -0700[diff] [blame^]83<h3 id="capture">Capturing Shaders</h3>
84
85<p>
86Setting <b>MESA_SHADER_CAPTURE_PATH</b> to a directory will cause the compiler
87to write <tt>.shader_test</tt> files for use with
88<a href="https://cgit.freedesktop.org/mesa/shader-db">shader-db</a>, a tool
89which compiler developers can use to gather statistics about shaders
90(instructions, cycles, memory accesses, and so on).
91</p>
92<p>
93Notably, this captures linked GLSL shaders - with all stages together -
94as well as ARB programs.
95</p>
96
Andreas Bolld4956692012-10-02 15:35:27 +0200[diff] [blame]97<h2 id="support">GLSL Version</h2>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]98
99<p>
Chris Forbesf6159af2013-11-24 17:44:06 +1300[diff] [blame]100The GLSL compiler currently supports version 3.30 of the shading language.
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]101</p>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]102
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]103<p>
104Several GLSL extensions are also supported:
105</p>
106<ul>
107<li>GL_ARB_draw_buffers
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]108<li>GL_ARB_fragment_coord_conventions
Andreas Bolld4956692012-10-02 15:35:27 +0200[diff] [blame]109<li>GL_ARB_shader_bit_encoding
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]110</ul>
Brian Paulc4341fe2008-12-15 18:30:40 -0700[diff] [blame]111
112
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]113<h2 id="unsup">Unsupported Features</h2>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]114
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]115<p>XXX update this section</p>
116
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]117<p>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]118The following features of the shading language are not yet fully supported
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]119in Mesa:
120</p>
121
122<ul>
Brian Paul439909a2009-04-07 11:09:53 -0600[diff] [blame]123<li>Linking of multiple shaders does not always work. Currently, linking
124 is implemented through shader concatenation and re-compiling. This
125 doesn't always work because of some #pragma and preprocessor issues.
Brian4b1d1b72007-04-27 15:25:00 -0600[diff] [blame]126<li>The gl_Color and gl_SecondaryColor varying vars are interpolated
127 without perspective correction
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]128</ul>
129
130<p>
131All other major features of the shading language should function.
132</p>
133
134
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]135<h2 id="notes">Implementation Notes</h2>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]136
137<ul>
138<li>Shading language programs are compiled into low-level programs
139 very similar to those of GL_ARB_vertex/fragment_program.
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]140<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]141 float[4] registers.
Brianbbec2fd2007-01-28 12:11:10 -0700[diff] [blame]142<li>Float constants and variables are packed so that up to four floats
143 can occupy one program parameter/register.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]144<li>All function calls are inlined.
145<li>Shaders which use too many registers will not compile.
146<li>The quality of generated code is pretty good, register usage is fair.
147<li>Shader error detection and reporting of errors (InfoLog) is not
148 very good yet.
Brian05e6fd82007-03-27 16:05:25 -0600[diff] [blame]149<li>The ftransform() function doesn't necessarily match the results of
150 fixed-function transformation.
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]151</ul>
152
153<p>
154These issues will be addressed/resolved in the future.
155</p>
156
157
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]158<h2 id="hints">Programming Hints</h2>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]159
160<ul>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]161<li>Use the built-in library functions whenever possible.
162 For example, instead of writing this:
163<pre>
164 float x = 1.0 / sqrt(y);
165</pre>
166 Write this:
167<pre>
168 float x = inversesqrt(y);
169</pre>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]170</li>
Brian9595d192007-01-20 13:40:57 -0700[diff] [blame]171</ul>
172
173
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]174<h2 id="standalone">Stand-alone GLSL Compiler</h2>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]175
176<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]177The stand-alone GLSL compiler program can be used to compile GLSL shaders
178into low-level GPU code.
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]179</p>
180
181<p>
182This tool is useful for:
Andreas Bolldf2be222012-06-12 09:05:22 +0200[diff] [blame]183</p>
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]184<ul>
185<li>Inspecting GPU code to gain insight into compilation
186<li>Generating initial GPU code for subsequent hand-tuning
187<li>Debugging the GLSL compiler itself
188</ul>
189
190<p>
Elie TOURNIER5034cf42017-01-18 13:50:11 +0000[diff] [blame]191After building Mesa, the compiler can be found at src/compiler/glsl/glsl_compiler
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]192</p>
193
194<p>
195Here's an example of using the compiler to compile a vertex shader and
196emit GL_ARB_vertex_program-style instructions:
197</p>
198<pre>
Elie TOURNIER5034cf42017-01-18 13:50:11 +0000[diff] [blame]199 src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]200</pre>
201
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]202Options include
203<ul>
204<li><b>--dump-ast</b> - dump GPU code
205<li><b>--dump-hir</b> - dump high-level IR code
206<li><b>--dump-lir</b> - dump low-level IR code
Elie TOURNIER5034cf42017-01-18 13:50:11 +0000[diff] [blame]207<li><b>--dump-builder</b> - dump GLSL IR code
208<li><b>--link</b> - link shaders
209<li><b>--just-log</b> - display only shader / linker info if exist,
210without any header or separator
211<li><b>--version</b> - [Mandatory] define the GLSL version to use
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]212</ul>
213
Brian61d31ae2007-02-17 09:41:19 -0700[diff] [blame]214
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]215<h2 id="implementation">Compiler Implementation</h2>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]216
217<p>
218The source code for Mesa's shading language compiler is in the
Elie TOURNIER5034cf42017-01-18 13:50:11 +0000[diff] [blame]219<code>src/compiler/glsl/</code> directory.
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]220</p>
221
222<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]223XXX provide some info about the compiler....
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]224</p>
Brian07e62082007-02-27 16:45:40 -0700[diff] [blame]225
226<p>
227The final vertex and fragment programs may be interpreted in software
228(see prog_execute.c) or translated into a specific hardware architecture
229(see drivers/dri/i915/i915_fragprog.c for example).
230</p>
231
Andreas Bollcc418882012-06-12 09:05:33 +0200[diff] [blame]232<h2 id="validation">Compiler Validation</h2>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]233
234<p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]235Developers working on the GLSL compiler should test frequently to avoid
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]236regressions.
237</p>
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]238
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]239<p>
Eric Engestrom30cf9ff2017-02-09 02:10:17 +0000[diff] [blame]240The <a href="https://piglit.freedesktop.org/">Piglit</a> project
Andreas Bolld4956692012-10-02 15:35:27 +0200[diff] [blame]241has many GLSL tests.
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]242</p>
243
Brian Paulf3ec1112010-08-24 09:02:05 -0600[diff] [blame]244<p>
245The Mesa demos repository also has some good GLSL tests.
246</p>
Brian7eba12e2007-03-28 17:14:35 -0600[diff] [blame]247
Andreas Bollb5da52a2012-09-18 18:57:02 +0200[diff] [blame]248</div>
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]249</body>
250</html>