2015-11-21 19:36:47 -07: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>
|
|
|
|
|
|
|
|
|
|
<div class="header">
|
|
|
|
|
<h1>The Mesa 3D Graphics Library</h1>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<iframe src="contents.html"></iframe>
|
|
|
|
|
<div class="content">
|
|
|
|
|
|
|
|
|
|
<h1>Shading Language Support</h1>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
This page describes the features and status of Mesa's support for the
|
2018-10-23 00:35:32 -06:00
|
|
|
<a href="https://opengl.org/documentation/glsl/">
|
2015-11-21 19:36:47 -07:00
|
|
|
OpenGL Shading Language</a>.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Contents
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><a href="#envvars">Environment variables</a>
|
|
|
|
|
<li><a href="#support">GLSL 1.40 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>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="envvars">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.
|
2018-10-23 00:35:32 -06:00
|
|
|
<li><b>cache_info</b> - print debug information about shader cache
|
|
|
|
|
<li><b>cache_fb</b> - force cached shaders to be ignored and do a full
|
|
|
|
|
recompile via the fallback path</li>
|
2015-11-21 19:36:47 -07:00
|
|
|
<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>
|
|
|
|
|
|
2018-10-23 00:35:32 -06:00
|
|
|
<h3 id="replacement">Experimenting with Shader Replacements</h3>
|
2016-05-29 04:11:54 -06:00
|
|
|
<p>
|
2018-10-23 00:35:32 -06:00
|
|
|
Shaders can be dumped and replaced on runtime for debugging purposes. This
|
2016-05-29 04:11:54 -06:00
|
|
|
feature is not currently supported by SCons build.
|
|
|
|
|
|
|
|
|
|
This is controlled via following environment variables:
|
|
|
|
|
<ul>
|
|
|
|
|
<li><b>MESA_SHADER_DUMP_PATH</b> - path where shader sources are dumped
|
|
|
|
|
<li><b>MESA_SHADER_READ_PATH</b> - path where replacement shaders are read
|
|
|
|
|
</ul>
|
|
|
|
|
Note, path set must exist before running for dumping or replacing to work.
|
|
|
|
|
When both are set, these paths should be different so the dumped shaders do
|
2018-10-23 00:35:32 -06:00
|
|
|
not clobber the replacement shaders. Also, the filenames of the replacement shaders
|
|
|
|
|
should match the filenames of the corresponding dumped shaders.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<h3 id="capture">Capturing Shaders</h3>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Setting <b>MESA_SHADER_CAPTURE_PATH</b> to a directory will cause the compiler
|
|
|
|
|
to write <tt>.shader_test</tt> files for use with
|
|
|
|
|
<a href="https://cgit.freedesktop.org/mesa/shader-db">shader-db</a>, a tool
|
|
|
|
|
which compiler developers can use to gather statistics about shaders
|
|
|
|
|
(instructions, cycles, memory accesses, and so on).
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Notably, this captures linked GLSL shaders - with all stages together -
|
|
|
|
|
as well as ARB programs.
|
2016-05-29 04:11:54 -06:00
|
|
|
</p>
|
2015-11-21 19:36:47 -07:00
|
|
|
|
|
|
|
|
<h2 id="support">GLSL Version</h2>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
The GLSL compiler currently supports version 3.30 of the shading language.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Several GLSL extensions are also supported:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>GL_ARB_draw_buffers
|
|
|
|
|
<li>GL_ARB_fragment_coord_conventions
|
|
|
|
|
<li>GL_ARB_shader_bit_encoding
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="unsup">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>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>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="notes">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>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="hints">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>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="standalone">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>
|
2018-10-23 00:35:32 -06:00
|
|
|
After building Mesa, the compiler can be found at src/compiler/glsl/glsl_compiler
|
2015-11-21 19:36:47 -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>
|
2018-10-23 00:35:32 -06:00
|
|
|
src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert
|
2015-11-21 19:36:47 -07:00
|
|
|
</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
|
2018-10-23 00:35:32 -06:00
|
|
|
<li><b>--dump-builder</b> - dump GLSL IR code
|
|
|
|
|
<li><b>--link</b> - link shaders
|
|
|
|
|
<li><b>--just-log</b> - display only shader / linker info if exist,
|
|
|
|
|
without any header or separator
|
|
|
|
|
<li><b>--version</b> - [Mandatory] define the GLSL version to use
|
2015-11-21 19:36:47 -07:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="implementation">Compiler Implementation</h2>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
The source code for Mesa's shading language compiler is in the
|
2018-10-23 00:35:32 -06:00
|
|
|
<code>src/compiler/glsl/</code> directory.
|
2015-11-21 19:36:47 -07:00
|
|
|
</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>
|
|
|
|
|
|
|
|
|
|
<h2 id="validation">Compiler Validation</h2>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Developers working on the GLSL compiler should test frequently to avoid
|
|
|
|
|
regressions.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
2018-10-23 00:35:32 -06:00
|
|
|
The <a href="https://piglit.freedesktop.org/">Piglit</a> project
|
2015-11-21 19:36:47 -07:00
|
|
|
has many GLSL tests.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
The Mesa demos repository also has some good GLSL tests.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
