summaryrefslogtreecommitdiff
path: root/docs/shading.html
blob: 412c89389e51ed0d25bf8f7171575e88d0aca9c5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
<HTML>

<TITLE>Shading Language Support</TITLE>

<link rel="stylesheet" type="text/css" href="mesa.css"></head>

<BODY>

<H1>Shading Language Support</H1>

<p>
This page describes the features and status of Mesa's support for the
<a href="http://opengl.org/documentation/glsl/" target="_parent">
OpenGL Shading Language</a>.
</p>

<p>
Last updated on 17 Feb 2007.
</p>

<p>
Contents
</p>
<ul>
<li><a href="#unsup">Unsupported Features</a>
<li><a href="#impl">Implementation Notes</a>
<li><a href="#hints">Programming Hints</a>
<li><a href="#standalone">Stand-alone Compiler</a>
</ul>


<a name="unsup">
<h2>Unsupported Features</h2>

<p>
The following features of the shading language are not yet supported
in Mesa:
</p>

<ul>
<li>Dereferencing arrays with non-constant indexes
<li>User-defined structs
<li>Linking of multiple shaders is not supported
<li>Integer operations are not fully implemented (most are implemented
    as floating point).
</ul>

<p>
All other major features of the shading language should function.
</p>


<a name="impl">
<h2>Implementation Notes</h2>

<ul>
<li>Shading language programs are compiled into low-level programs
    very similar to those of GL_ARB_vertex/fragment_program.
<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
    float[4] registers.
<li>Float constants and variables are packed so that up to four floats
    can occupy one program parameter/register.
<li>All function calls are inlined.
<li>Shaders which use too many registers will not compile.
<li>The quality of generated code is pretty good, register usage is fair.
<li>Shader error detection and reporting of errors (InfoLog) is not
    very good yet.
<li>There are massive memory leaks in the compiler.
</ul>

<p>
These issues will be addressed/resolved in the future.
</p>


<a name="hints">
<h2>Programming Hints</h2>

<ul>
<li>Declare <em>in</em> function parameters as <em>const</em> whenever possible.
    This improves the efficiency of function inlining.
</li>
<br>
<li>To reduce register usage, declare variables within smaller scopes.
    For example, the following code:
<pre>
    void main()
    {
       vec4 a1, a2, b1, b2;
       gl_Position = expression using a1, a2.
       gl_Color = expression using b1, b2;
    }
</pre>
    Can be rewritten as follows to use half as many registers:
<pre>
    void main()
    {
       {
          vec4 a1, a2;
          gl_Position = expression using a1, a2.
       }
       {
          vec4 b1, b2;
          gl_Color = expression using b1, b2;
       }
    }
</pre>
    Alternately, rather than using several float variables, use
    a vec4 instead.  Use swizzling and writemasks to access the
    components of the vec4 as floats.
</li>
<br>
<li>Use the built-in library functions whenever possible.
    For example, instead of writing this:
<pre>
        float x = 1.0 / sqrt(y);
</pre>
    Write this:
<pre>
        float x = inversesqrt(y);
</pre>
</ul>


<a name="standalone">
<h2>Stand-alone Compiler</h2>

<p>
A unique stand-alone GLSL compiler driver has been added to Mesa.
<p>

<p>
The stand-alone compiler (like a conventional command-line compiler)
is a tool that accepts Shading Language programs and emits low-level
GPU programs.
</p>

<p>
This tool is useful for:
<p>
<ul>
<li>Inspecting GPU code to gain insight into compilation
<li>Generating initial GPU code for subsequent hand-tuning
<li>Debugging the GLSL compiler itself
</ul>

<p>
To build the glslcompiler program (this will be improved someday):
</p>
<pre>
    cd src/mesa
    make libmesa.a
    cd drivers/glslcompiler
    make
</pre>


<p>
Here's an example of using the compiler to compile a vertex shader and
emit GL_ARB_vertex_program-style instructions:
</p>
<pre>
    glslcompiler --arb --linenumbers --vs vertshader.txt
</pre>
<p>
The output may look similar to this:
</p>
<pre>
!!ARBvp1.0
  0: MOV result.texcoord[0], vertex.texcoord[0];
  1: DP4 temp0.x, state.matrix.mvp.row[0], vertex.position;
  2: DP4 temp0.y, state.matrix.mvp.row[1], vertex.position;
  3: DP4 temp0.z, state.matrix.mvp.row[2], vertex.position;
  4: DP4 temp0.w, state.matrix.mvp.row[3], vertex.position;
  5: MOV result.position, temp0;
  6: END
</pre>

<p>
Note that some shading language constructs (such as uniform and varying
variables) aren't expressible in ARB or NV-style programs.
Therefore, the resulting output is not always legal by definition of
those program languages.
</p>
<p>
Also note that this compiler driver is still under development.
Over time, the correctness of the GPU programs, with respect to the ARB
and NV languagues, should improve.
</p>

</BODY>
</HTML>