2013-09-05 07:58:30 -06:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
|
|
|
<html lang="en">
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8">
|
|
|
|
|
<title>Shading Language Support</title>
|
|
|
|
|
<link rel="stylesheet" type="text/css" href="mesa.css">
|
|
|
|
|
</head>
|
|
|
|
|
<body>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<div class="header">
|
|
|
|
|
<h1>The Mesa 3D Graphics Library</h1>
|
|
|
|
|
</div>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<iframe src="contents.html"></iframe>
|
|
|
|
|
<div class="content">
|
2007-11-24 10:25:28 -07:00
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<h1>Shading Language Support</h1>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
This page describes the features and status of Mesa's support for the
|
2013-09-05 07:58:30 -06:00
|
|
|
<a href="http://opengl.org/documentation/glsl/">
|
2007-11-24 10:25:28 -07:00
|
|
|
OpenGL Shading Language</a>.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Contents
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
2010-05-22 14:05:42 -06:00
|
|
|
<li><a href="#envvars">Environment variables</a>
|
2013-09-05 07:58:30 -06:00
|
|
|
<li><a href="#support">GLSL 1.40 support</a>
|
2007-11-24 10:25:28 -07:00
|
|
|
<li><a href="#unsup">Unsupported Features</a>
|
|
|
|
|
<li><a href="#notes">Implementation Notes</a>
|
|
|
|
|
<li><a href="#hints">Programming Hints</a>
|
2008-11-02 07:58:06 -07:00
|
|
|
<li><a href="#standalone">Stand-alone GLSL Compiler</a>
|
2007-11-24 10:25:28 -07:00
|
|
|
<li><a href="#implementation">Compiler Implementation</a>
|
|
|
|
|
<li><a href="#validation">Compiler Validation</a>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<h2 id="envvars">Environment Variables</h2>
|
2010-05-22 14:05:42 -06:00
|
|
|
|
|
|
|
|
<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>
|
2011-10-23 07:37:25 -06:00
|
|
|
<li><b>dump</b> - print GLSL shader code to stdout at link time
|
|
|
|
|
<li><b>log</b> - log all GLSL shaders to files.
|
2010-05-22 14:05:42 -06:00
|
|
|
The filenames will be "shader_X.vert" or "shader_X.frag" where X
|
|
|
|
|
the shader ID.
|
2011-10-23 07:37:25 -06:00
|
|
|
<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
|
2010-05-22 14:05:42 -06:00
|
|
|
the vertex position with ftransform() and passes through the color and
|
|
|
|
|
texcoord[0] attributes.
|
2011-10-23 07:37:25 -06:00
|
|
|
<li><b>nopfrag</b> - force fragment shader to be a simple shader that passes
|
2010-05-22 14:05:42 -06:00
|
|
|
through the color attribute.
|
2011-10-23 07:37:25 -06:00
|
|
|
<li><b>useprog</b> - log glUseProgram calls to stderr
|
2010-05-22 14:05:42 -06:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
Example: export MESA_GLSL=dump,nopt
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<h2 id="support">GLSL Version</h2>
|
2009-05-17 14:26:36 -06:00
|
|
|
|
|
|
|
|
<p>
|
2013-09-05 07:58:30 -06:00
|
|
|
The GLSL compiler currently supports version 1.40 of the shading language.
|
2011-10-23 07:37:25 -06:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Several GLSL extensions are also supported:
|
|
|
|
|
</p>
|
2009-05-17 14:26:36 -06:00
|
|
|
<ul>
|
2011-10-23 07:37:25 -06:00
|
|
|
<li>GL_ARB_draw_buffers
|
|
|
|
|
<li>GL_ARB_fragment_coord_conventions
|
2013-09-05 07:58:30 -06:00
|
|
|
<li>GL_ARB_shader_bit_encoding
|
2009-05-17 14:26:36 -06:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<h2 id="unsup">Unsupported Features</h2>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
2011-10-23 07:37:25 -06:00
|
|
|
<p>XXX update this section</p>
|
|
|
|
|
|
2007-11-24 10:25:28 -07:00
|
|
|
<p>
|
2010-05-22 14:05:42 -06:00
|
|
|
The following features of the shading language are not yet fully supported
|
2007-11-24 10:25:28 -07:00
|
|
|
in Mesa:
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2010-05-22 14:05:42 -06:00
|
|
|
<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.
|
2007-11-24 10:25:28 -07:00
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<h2 id="notes">Implementation Notes</h2>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<h2 id="hints">Programming Hints</h2>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<h2 id="standalone">Stand-alone GLSL Compiler</h2>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
|
|
|
|
<p>
|
2011-10-23 07:37:25 -06:00
|
|
|
The stand-alone GLSL compiler program can be used to compile GLSL shaders
|
|
|
|
|
into low-level GPU code.
|
2007-11-24 10:25:28 -07:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
This tool is useful for:
|
2013-09-05 07:58:30 -06:00
|
|
|
</p>
|
2007-11-24 10:25:28 -07:00
|
|
|
<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>
|
2011-10-23 07:37:25 -06:00
|
|
|
After building Mesa, the compiler can be found at src/glsl/glsl_compiler
|
2007-11-24 10:25:28 -07:00
|
|
|
</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>
|
2011-10-23 07:37:25 -06:00
|
|
|
src/glsl/glsl_compiler --dump-ast myshader.vert
|
2007-11-24 10:25:28 -07:00
|
|
|
</pre>
|
|
|
|
|
|
2011-10-23 07:37:25 -06:00
|
|
|
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>
|
|
|
|
|
|
2007-11-24 10:25:28 -07:00
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<h2 id="implementation">Compiler Implementation</h2>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
The source code for Mesa's shading language compiler is in the
|
2011-10-23 07:37:25 -06:00
|
|
|
<code>src/glsl/</code> directory.
|
2007-11-24 10:25:28 -07:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
2011-10-23 07:37:25 -06:00
|
|
|
XXX provide some info about the compiler....
|
2007-11-24 10:25:28 -07:00
|
|
|
</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>
|
|
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<dl>
|
|
|
|
|
<dt>EmitHighLevelInstructions</dt>
|
|
|
|
|
<dd>
|
2007-11-24 10:25:28 -07:00
|
|
|
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.
|
2013-09-05 07:58:30 -06:00
|
|
|
</dd>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<dt>EmitCondCodes</dt>
|
|
|
|
|
<dd>
|
2007-11-24 10:25:28 -07:00
|
|
|
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.
|
2013-09-05 07:58:30 -06:00
|
|
|
</dd>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<dt>EmitComments</dt>
|
|
|
|
|
<dd>
|
2007-11-24 10:25:28 -07:00
|
|
|
If set, instructions will be annoted with comments to help with debugging.
|
|
|
|
|
Extra NOP instructions will also be inserted.
|
2013-09-05 07:58:30 -06:00
|
|
|
</dd>
|
|
|
|
|
</dl>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
|
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
<h2 id="validation">Compiler Validation</h2>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
|
|
|
|
<p>
|
2011-10-23 07:37:25 -06:00
|
|
|
Developers working on the GLSL compiler should test frequently to avoid
|
2007-11-24 10:25:28 -07:00
|
|
|
regressions.
|
|
|
|
|
</p>
|
2011-10-23 07:37:25 -06:00
|
|
|
|
2007-11-24 10:25:28 -07:00
|
|
|
<p>
|
2013-09-05 07:58:30 -06:00
|
|
|
The <a href="http://piglit.freedesktop.org/">Piglit</a> project
|
|
|
|
|
has many GLSL tests.
|
2007-11-24 10:25:28 -07:00
|
|
|
</p>
|
|
|
|
|
|
2011-10-23 07:37:25 -06:00
|
|
|
<p>
|
|
|
|
|
The Mesa demos repository also has some good GLSL tests.
|
|
|
|
|
</p>
|
2007-11-24 10:25:28 -07:00
|
|
|
|
2013-09-05 07:58:30 -06:00
|
|
|
</div>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
