X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;ds=sidebyside;f=docs%2Fshading.html;h=a0bbe997c1b8eeea572fa16260b4af329689cb9c;hb=9f77a9729eb62d7688b796a546e42934496f872a;hp=77a0ee413d90492a0f04eb48fad2b0ebbc5a9c4b;hpb=0691b37732e3b032fbd354537b20090a3ee8e122;p=mesa.git diff --git a/docs/shading.html b/docs/shading.html index 77a0ee413d9..a0bbe997c1b 100644 --- a/docs/shading.html +++ b/docs/shading.html @@ -18,7 +18,7 @@

This page describes the features and status of Mesa's support for the - + OpenGL Shading Language.

@@ -49,8 +49,9 @@ execution. These are generally used for debugging.
  • log - log all GLSL shaders to files. The filenames will be "shader_X.vert" or "shader_X.frag" where X the shader ID. -
  • nopt - disable compiler optimizations -
  • opt - force compiler optimizations +
  • cache_info - print debug information about shader cache +
  • cache_fb - force cached shaders to be ignored and do a full + recompile via the fallback path
  • uniform - print message to stdout when glUniform is called
  • nopvert - force vertex shaders to be a simple shader that just transforms the vertex position with ftransform() and passes through the color and @@ -63,6 +64,35 @@ execution. These are generally used for debugging. Example: export MESA_GLSL=dump,nopt

    +

    Experimenting with Shader Replacements

    +

    +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: +

    +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. +

    + +

    Capturing Shaders

    + +

    +Setting MESA_SHADER_CAPTURE_PATH to a directory will cause the compiler +to write .shader_test files for use with +shader-db, a tool +which compiler developers can use to gather statistics about shaders +(instructions, cycles, memory accesses, and so on). +

    +

    +Notably, this captures linked GLSL shaders - with all stages together - +as well as ARB programs. +

    GLSL Version

    @@ -158,7 +188,7 @@ This tool is useful for:

    -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

    @@ -166,7 +196,7 @@ Here's an example of using the compiler to compile a vertex shader and emit GL_ARB_vertex_program-style instructions: 

    -    src/glsl/glsl_compiler --dump-ast myshader.vert
+    src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert
    Options include @@ -174,7 +204,11 @@ Options include
  • --dump-ast - dump GPU code
  • --dump-hir - dump high-level IR code
  • --dump-lir - dump low-level IR code -
  • --link - ??? +
  • --dump-builder - dump GLSL IR code +
  • --link - link shaders +
  • --just-log - display only shader / linker info if exist, +without any header or separator +
  • --version - [Mandatory] define the GLSL version to use @@ -182,7 +216,7 @@ Options include

    The source code for Mesa's shading language compiler is in the -src/glsl/ directory. +src/compiler/glsl/ directory.

    @@ -195,51 +229,6 @@ The final vertex and fragment programs may be interpreted in software (see drivers/dri/i915/i915_fragprog.c for example).

    -

    Code Generation Options

    - -

    -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: - -

    -struct gl_shader_state
-{
-   ...
-   /** Driver-selectable options: */
-   GLboolean EmitHighLevelInstructions;
-   GLboolean EmitCondCodes;
-   GLboolean EmitComments;
-};
-
    - -
    -
    EmitHighLevelInstructions
    -
    -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. -
    - -
    EmitCondCodes
    -
    -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. -
    - -
    EmitComments
    -
    -If set, instructions will be annotated with comments to help with debugging. -Extra NOP instructions will also be inserted. -
    -
    - -

    Compiler Validation

    @@ -248,7 +237,7 @@ regressions.

    -The Piglit project +The Piglit project has many GLSL tests.