diff options
Diffstat (limited to 'docs/shading.html')
| -rw-r--r-- | docs/shading.html | 251 |
1 files changed, 0 insertions, 251 deletions
diff --git a/docs/shading.html b/docs/shading.html deleted file mode 100644 index e36bab49c58..00000000000 --- a/docs/shading.html +++ /dev/null @@ -1,251 +0,0 @@ -<!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</title> - <link rel="stylesheet" type="text/css" href="mesa.css"> -</head> -<body> - -<div class="header"> - The Mesa 3D Graphics Library -</div> - -<iframe src="contents.html"></iframe> -<div class="content"> - -<h1>Shading Language</h1> - -<p> -This page describes the features and status of Mesa's support for the -<a href="https://opengl.org/documentation/glsl/"> -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. -<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> -<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 -<li><b>errors</b> - GLSL compilation and link errors will be reported to stderr. -</ul> -<p> -Example: export MESA_GLSL=dump,nopt -</p> - -<h3 id="replacement">Experimenting with Shader Replacements</h3> -<p> -Shaders can be dumped and replaced on runtime for debugging purposes. This -feature is not currently supported by SCons build. - -This is controlled via following environment variables: -</p> -<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 -not clobber the replacement shaders. Also, the filenames of the replacement shaders -should match the filenames of the corresponding dumped shaders. - -<h3 id="capture">Capturing Shaders</h3> - -<p> -Setting <b>MESA_SHADER_CAPTURE_PATH</b> to a directory will cause the compiler -to write <code>.shader_test</code> files for use with -<a href="https://gitlab.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. -</p> - -<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> -After building Mesa, the compiler can be found at src/compiler/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/compiler/glsl/glsl_compiler --version XXX --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>--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 -</ul> - - -<h2 id="implementation">Compiler Implementation</h2> - -<p> -The source code for Mesa's shading language compiler is in the -<code>src/compiler/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> - -<h2 id="validation">Compiler Validation</h2> - -<p> -Developers working on the GLSL compiler should test frequently to avoid -regressions. -</p> - -<p> -The <a href="https://piglit.freedesktop.org/">Piglit</a> project -has many GLSL tests. -</p> - -<p> -The Mesa demos repository also has some good GLSL tests. -</p> - -</div> -</body> -</html> |