aboutsummaryrefslogtreecommitdiff
path: root/mesalib/docs/shading.html
diff options
context:
space:
mode:
Diffstat (limited to 'mesalib/docs/shading.html')
-rw-r--r--mesalib/docs/shading.html536
1 files changed, 268 insertions, 268 deletions
diff --git a/mesalib/docs/shading.html b/mesalib/docs/shading.html
index cc1f9f1ec..aba395974 100644
--- a/mesalib/docs/shading.html
+++ b/mesalib/docs/shading.html
@@ -1,268 +1,268 @@
-<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>
-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 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><b>dump</b> - print GLSL shader code to stdout at link time
-<li><b>log</b> - log all GLSL shaders to files.
- The filenames will be "shader_X.vert" or "shader_X.frag" where X
- the shader ID.
-<li><b>nopt</b> - disable compiler optimizations
-<li><b>opt</b> - force compiler optimizations
-<li><b>uniform</b> - print message to stdout when glUniform is called
-<li><b>nopvert</b> - 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><b>nopfrag</b> - force fragment shader to be a simple shader that passes
- through the color attribute.
-<li><b>useprog</b> - log glUseProgram calls to stderr
-</ul>
-<p>
-Example: export MESA_GLSL=dump,nopt
-</p>
-
-
-<a name="120">
-<h2>GLSL Version</h2>
-
-<p>
-The GLSL compiler currently supports version 1.20 of the shading language.
-</p>
-
-<p>
-Several GLSL extensions are also supported:
-</p>
-<ul>
-<li>GL_ARB_draw_buffers
-<li>GL_ARB_texture_rectangle
-<li>GL_ARB_fragment_coord_conventions
-<li>GL_EXT_texture_array
-</ul>
-
-
-<a name="unsup">
-<h2>Unsupported Features</h2>
-
-<p>XXX update this section</p>
-
-<p>
-The following features of the shading language are not yet fully supported
-in Mesa:
-</p>
-
-<ul>
-<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>
-All other major features of the shading language should function.
-</p>
-
-
-<a name="notes">
-<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>The ftransform() function doesn't necessarily match the results of
- fixed-function transformation.
-</ul>
-
-<p>
-These issues will be addressed/resolved in the future.
-</p>
-
-
-<a name="hints">
-<h2>Programming Hints</h2>
-
-<ul>
-<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>
-</li>
-</ul>
-
-
-<a name="standalone">
-<h2>Stand-alone GLSL Compiler</h2>
-
-<p>
-The stand-alone GLSL compiler program can be used to compile GLSL shaders
-into low-level GPU code.
-</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>
-After building Mesa, the compiler can be found at src/glsl/glsl_compiler
-</p>
-
-<p>
-Here's an example of using the compiler to compile a vertex shader and
-emit GL_ARB_vertex_program-style instructions:
-</p>
-<pre>
- src/glsl/glsl_compiler --dump-ast myshader.vert
-</pre>
-
-Options include
-<ul>
-<li><b>--dump-ast</b> - dump GPU code
-<li><b>--dump-hir</b> - dump high-level IR code
-<li><b>--dump-lir</b> - dump low-level IR code
-<li><b>--link</b> - ???
-</ul>
-
-
-
-
-<a name="implementation">
-<h2>Compiler Implementation</h2>
-
-<p>
-The source code for Mesa's shading language compiler is in the
-<code>src/glsl/</code> directory.
-</p>
-
-<p>
-XXX provide some info about the compiler....
-</p>
-
-<p>
-The final vertex and fragment programs may be interpreted in software
-(see prog_execute.c) or translated into a specific hardware architecture
-(see drivers/dri/i915/i915_fragprog.c for example).
-</p>
-
-<h3>Code Generation Options</h3>
-
-<p>
-Internally, there are several options that control the compiler's code
-generation and instruction selection.
-These options are seen in the gl_shader_state struct and may be set
-by the device driver to indicate its preferences:
-
-<pre>
-struct gl_shader_state
-{
- ...
- /** Driver-selectable options: */
- GLboolean EmitHighLevelInstructions;
- GLboolean EmitCondCodes;
- GLboolean EmitComments;
-};
-</pre>
-
-<ul>
-<li>EmitHighLevelInstructions
-<br>
-This option controls instruction selection for loops and conditionals.
-If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
-instructions will be emitted.
-Otherwise, those constructs will be implemented with BRA instructions.
-</li>
-
-<li>EmitCondCodes
-<br>
-If set, condition codes (ala GL_NV_fragment_program) will be used for
-branching and looping.
-Otherwise, ordinary registers will be used (the IF instruction will
-examine the first operand's X component and do the if-part if non-zero).
-This option is only relevant if EmitHighLevelInstructions is set.
-</li>
-
-<li>EmitComments
-<br>
-If set, instructions will be annoted with comments to help with debugging.
-Extra NOP instructions will also be inserted.
-</br>
-
-</ul>
-
-
-<a name="validation">
-<h2>Compiler Validation</h2>
-
-<p>
-Developers working on the GLSL compiler should test frequently to avoid
-regressions.
-</p>
-
-<p>
-The <a href="http://people.freedesktop.org/~nh/piglit/">Piglit</a> project
-has many GLSL tests and the
-<a href="http://glean.sf.net" target="_parent">Glean</a> glsl1 test
-tests GLSL features.
-</p>
-
-<p>
-The Mesa demos repository also has some good GLSL tests.
-</p>
-
-</BODY>
-</HTML>
+<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>
+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 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><b>dump</b> - print GLSL shader code to stdout at link time
+<li><b>log</b> - log all GLSL shaders to files.
+ The filenames will be "shader_X.vert" or "shader_X.frag" where X
+ the shader ID.
+<li><b>nopt</b> - disable compiler optimizations
+<li><b>opt</b> - force compiler optimizations
+<li><b>uniform</b> - print message to stdout when glUniform is called
+<li><b>nopvert</b> - 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><b>nopfrag</b> - force fragment shader to be a simple shader that passes
+ through the color attribute.
+<li><b>useprog</b> - log glUseProgram calls to stderr
+</ul>
+<p>
+Example: export MESA_GLSL=dump,nopt
+</p>
+
+
+<a name="120">
+<h2>GLSL Version</h2>
+
+<p>
+The GLSL compiler currently supports version 1.20 of the shading language.
+</p>
+
+<p>
+Several GLSL extensions are also supported:
+</p>
+<ul>
+<li>GL_ARB_draw_buffers
+<li>GL_ARB_texture_rectangle
+<li>GL_ARB_fragment_coord_conventions
+<li>GL_EXT_texture_array
+</ul>
+
+
+<a name="unsup">
+<h2>Unsupported Features</h2>
+
+<p>XXX update this section</p>
+
+<p>
+The following features of the shading language are not yet fully supported
+in Mesa:
+</p>
+
+<ul>
+<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>
+All other major features of the shading language should function.
+</p>
+
+
+<a name="notes">
+<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>The ftransform() function doesn't necessarily match the results of
+ fixed-function transformation.
+</ul>
+
+<p>
+These issues will be addressed/resolved in the future.
+</p>
+
+
+<a name="hints">
+<h2>Programming Hints</h2>
+
+<ul>
+<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>
+</li>
+</ul>
+
+
+<a name="standalone">
+<h2>Stand-alone GLSL Compiler</h2>
+
+<p>
+The stand-alone GLSL compiler program can be used to compile GLSL shaders
+into low-level GPU code.
+</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>
+After building Mesa, the compiler can be found at src/glsl/glsl_compiler
+</p>
+
+<p>
+Here's an example of using the compiler to compile a vertex shader and
+emit GL_ARB_vertex_program-style instructions:
+</p>
+<pre>
+ src/glsl/glsl_compiler --dump-ast myshader.vert
+</pre>
+
+Options include
+<ul>
+<li><b>--dump-ast</b> - dump GPU code
+<li><b>--dump-hir</b> - dump high-level IR code
+<li><b>--dump-lir</b> - dump low-level IR code
+<li><b>--link</b> - ???
+</ul>
+
+
+
+
+<a name="implementation">
+<h2>Compiler Implementation</h2>
+
+<p>
+The source code for Mesa's shading language compiler is in the
+<code>src/glsl/</code> directory.
+</p>
+
+<p>
+XXX provide some info about the compiler....
+</p>
+
+<p>
+The final vertex and fragment programs may be interpreted in software
+(see prog_execute.c) or translated into a specific hardware architecture
+(see drivers/dri/i915/i915_fragprog.c for example).
+</p>
+
+<h3>Code Generation Options</h3>
+
+<p>
+Internally, there are several options that control the compiler's code
+generation and instruction selection.
+These options are seen in the gl_shader_state struct and may be set
+by the device driver to indicate its preferences:
+
+<pre>
+struct gl_shader_state
+{
+ ...
+ /** Driver-selectable options: */
+ GLboolean EmitHighLevelInstructions;
+ GLboolean EmitCondCodes;
+ GLboolean EmitComments;
+};
+</pre>
+
+<ul>
+<li>EmitHighLevelInstructions
+<br>
+This option controls instruction selection for loops and conditionals.
+If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
+instructions will be emitted.
+Otherwise, those constructs will be implemented with BRA instructions.
+</li>
+
+<li>EmitCondCodes
+<br>
+If set, condition codes (ala GL_NV_fragment_program) will be used for
+branching and looping.
+Otherwise, ordinary registers will be used (the IF instruction will
+examine the first operand's X component and do the if-part if non-zero).
+This option is only relevant if EmitHighLevelInstructions is set.
+</li>
+
+<li>EmitComments
+<br>
+If set, instructions will be annoted with comments to help with debugging.
+Extra NOP instructions will also be inserted.
+</br>
+
+</ul>
+
+
+<a name="validation">
+<h2>Compiler Validation</h2>
+
+<p>
+Developers working on the GLSL compiler should test frequently to avoid
+regressions.
+</p>
+
+<p>
+The <a href="http://people.freedesktop.org/~nh/piglit/">Piglit</a> project
+has many GLSL tests and the
+<a href="http://glean.sf.net" target="_parent">Glean</a> glsl1 test
+tests GLSL features.
+</p>
+
+<p>
+The Mesa demos repository also has some good GLSL tests.
+</p>
+
+</BODY>
+</HTML>