X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=docs%2Fshading.html;h=bd02335a803d0ccd4bb9512c9b8bc0b59e0f1f16;hb=d2758f3b74838f4d4f1ae691fddca7dc9f4e8c0e;hp=40a6d7ac90b767f7c5674b7841004d3872d307f5;hpb=8f9db0f81c13c3244f07333f33a15bfe098e0f31;p=mesa.git

diff --git a/docs/shading.html b/docs/shading.html
index 40a6d7ac90b..bd02335a803 100644
--- a/docs/shading.html
+++ b/docs/shading.html
@@ -15,36 +15,90 @@ OpenGL Shading Language</a>.
 </p>
 
 <p>
-Last updated on 17 Feb 2007.
+Last updated on 15 December 2008.
 </p>
 
 <p>
 Contents
 </p>
 <ul>
+<li><a href="#envvars">Environment variables</a>
+<li><a href="#120">GLSL 1.20 support</a>
 <li><a href="#unsup">Unsupported Features</a>
 <li><a href="#notes">Implementation Notes</a>
 <li><a href="#hints">Programming Hints</a>
-<li><a href="#standalone">Stand-alone Compiler</a>
+<li><a href="#standalone">Stand-alone GLSL Compiler</a>
 <li><a href="#implementation">Compiler Implementation</a>
+<li><a href="#validation">Compiler Validation</a>
 </ul>
 
 
+
+<a name="envvars">
+<h2>Environment Variables</h2>
+
+<p>
+The <b>MESA_GLSL</b> environment variable can be set to a comma-separated
+list of keywords to control some aspects of the GLSL compiler and shader
+execution.  These are generally used for debugging.
+</p>
+<ul>
+<li>dump - print GLSL shader code to stdout at link time
+<li>log - log all GLSL shaders to files.
+    The filenames will be "shader_X.vert" or "shader_X.frag" where X
+    the shader ID.
+<li>nopt - disable compiler optimizations
+<li>opt - force compiler optimizations
+<li>uniform - print message to stdout when glUniform is called
+<li>nopvert - force vertex shaders to be a simple shader that just transforms
+    the vertex position with ftransform() and passes through the color and
+    texcoord[0] attributes.
+<li>nopfrag - force fragment shader to be a simple shader that passes
+    through the color attribute.
+<li>useprog - log glUseProgram calls to stderr
+</ul>
+<p>
+Example:  export MESA_GLSL=dump,nopt
+</p>
+
+
+<a name="120">
+<h2>GLSL 1.20 support</h2>
+
+<p>
+GLSL version 1.20 is supported in Mesa 7.3 and later.
+Among the features/differences of GLSL 1.20 are:
+<ul>
+<li><code>mat2x3, mat2x4</code>, etc. types and functions
+<li><code>transpose(), outerProduct(), matrixCompMult()</code> functions
+(but untested)
+<li>precision qualifiers (lowp, mediump, highp)
+<li><code>invariant</code> qualifier
+<li><code>array.length()</code> method
+<li><code>float[5] a;</code> array syntax
+<li><code>centroid</code> qualifier
+<li>unsized array constructors
+<li>initializers for uniforms
+<li>const initializers calling built-in functions
+</ul>
+
+
+
 <a name="unsup">
 <h2>Unsupported Features</h2>
 
 <p>
-The following features of the shading language are not yet supported
+The following features of the shading language are not yet fully 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).
+<li>Linking of multiple shaders does not always work.  Currently, linking
+    is implemented through shader concatenation and re-compiling.  This
+    doesn't always work because of some #pragma and preprocessor issues.
 <li>gl_ClipVertex
+<li>The gl_Color and gl_SecondaryColor varying vars are interpolated
+    without perspective correction
 </ul>
 
 <p>
@@ -67,7 +121,8 @@ All other major features of the shading language should function.
 <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 known memory leaks in the compiler.
+<li>The ftransform() function doesn't necessarily match the results of
+    fixed-function transformation.
 </ul>
 
 <p>
@@ -121,11 +176,14 @@ These issues will be addressed/resolved in the future.
 <pre>
         float x = inversesqrt(y);
 </pre>
+<li>
+   Use ++i when possible as it's more efficient than i++
+</li>
 </ul>
 
 
 <a name="standalone">
-<h2>Stand-alone Compiler</h2>
+<h2>Stand-alone GLSL Compiler</h2>
 
 <p>
 A unique stand-alone GLSL compiler driver has been added to Mesa.
@@ -147,12 +205,12 @@ This tool is useful for:
 </ul>
 
 <p>
-To build the glslcompiler program (this will be improved someday):
+After building Mesa, the glslcompiler can be built by manually running:
 </p>
 <pre>
-    cd src/mesa
-    make libmesa.a
-    cd drivers/glslcompiler
+    make realclean
+    make linux
+    cd src/mesa/drivers/glslcompiler
     make
 </pre>
 
@@ -162,20 +220,31 @@ 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
+    bin/glslcompiler --debug --numbers --fs progs/glsl/CH06-brick.frag.txt
 </pre>
 <p>
-The output may look similar to this:
+results in:
 </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
+# Fragment Program/Shader
+  0: RCP TEMP[4].x, UNIFORM[2].xxxx;
+  1: RCP TEMP[4].y, UNIFORM[2].yyyy;
+  2: MUL TEMP[3].xy, VARYING[0], TEMP[4];
+  3: MOV TEMP[1], TEMP[3];
+  4: MUL TEMP[0].w, TEMP[1].yyyy, CONST[4].xxxx;
+  5: FRC TEMP[1].z, TEMP[0].wwww;
+  6: SGT.C TEMP[0].w, TEMP[1].zzzz, CONST[4].xxxx;
+  7: IF (NE.wwww); # (if false, goto 9);
+  8:    ADD TEMP[1].x, TEMP[1].xxxx, CONST[4].xxxx;
+  9: ENDIF;
+ 10: FRC TEMP[1].xy, TEMP[1];
+ 11: SGT TEMP[2].xy, UNIFORM[3], TEMP[1];
+ 12: MUL TEMP[1].z, TEMP[2].xxxx, TEMP[2].yyyy;
+ 13: LRP TEMP[0], TEMP[1].zzzz, UNIFORM[0], UNIFORM[1];
+ 14: MUL TEMP[0].xyz, TEMP[0], VARYING[1].xxxx;
+ 15: MOV OUTPUT[0].xyz, TEMP[0];
+ 16: MOV OUTPUT[0].w, CONST[4].yyyy;
+ 17: END
 </pre>
 
 <p>
@@ -282,5 +351,24 @@ Extra NOP instructions will also be inserted.
 </ul>
 
 
+<a name="validation">
+<h2>Compiler Validation</h2>
+
+<p>
+A <a href="http://glean.sf.net" target="_parent">Glean</a> test has
+been create to exercise the GLSL compiler.
+</p>
+<p>
+The <em>glsl1</em> test runs over 170 sub-tests to check that the language
+features and built-in functions work properly.
+This test should be run frequently while working on the compiler to catch
+regressions.
+</p>
+<p>
+The test coverage is reasonably broad and complete but additional tests
+should be added.
+</p>
+
+
 </BODY>
 </HTML>