anv/android: Disable surface and swapchain extensions (v2)

[mesa.git] / docs / shading.html

diff --git a/docs/shading.html b/docs/shading.html
index cf989ce9029a6a420ef55f94419d7ec37b8c165d..a0bbe997c1b8eeea572fa16260b4af329689cb9c 100644 (file)
--- a/docs/shading.html
+++ b/docs/shading.html
@@ -18,7 +18,7 @@
 
 <p>
 This page describes the features and status of Mesa's support for the
-<a href="http://opengl.org/documentation/glsl/">
+<a href="https://opengl.org/documentation/glsl/">
 OpenGL Shading Language</a>.
 </p>
 
@@ -49,8 +49,9 @@ execution.  These are generally used for debugging.
 <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>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
@@ -63,9 +64,9 @@ execution.  These are generally used for debugging.
 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. Mesa 
-needs to be configured with '--with-sha1' to enable this functionality. This 
+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:
@@ -75,7 +76,22 @@ This is controlled via following environment variables:
 </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.
+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.
 </p>
 
 <h2 id="support">GLSL Version</h2>
@@ -172,7 +188,7 @@ This tool is useful for:
 </ul>
 
 <p>
-After building Mesa, the compiler can be found at src/glsl/glsl_compiler
+After building Mesa, the compiler can be found at src/compiler/glsl/glsl_compiler
 </p>
 
 <p>
@@ -180,7 +196,7 @@ 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
+    src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert
 </pre>
 
 Options include
@@ -188,7 +204,11 @@ Options include
 <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> - ???
+<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>
 
 
@@ -196,7 +216,7 @@ Options include
 
 <p>
 The source code for Mesa's shading language compiler is in the
-<code>src/glsl/</code> directory.
+<code>src/compiler/glsl/</code> directory.
 </p>
 
 <p>
@@ -217,7 +237,7 @@ regressions.
 </p>
 
 <p>
-The <a href="http://piglit.freedesktop.org/">Piglit</a> project
+The <a href="https://piglit.freedesktop.org/">Piglit</a> project
 has many GLSL tests.
 </p>