X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=docs%2Fshading.html;h=9e3c7218e31e5ad8385c76585a4bf22c3a8a433a;hb=e9f84f1447b53a279779280172756f70c09eda91;hp=604bd1d37a652a13041970c6bb3bd0d04b382236;hpb=ecd5c7ceb8e4c8841b2708e5ab7efa145583f8c2;p=mesa.git diff --git a/docs/shading.html b/docs/shading.html index 604bd1d37a6..9e3c7218e31 100644 --- a/docs/shading.html +++ b/docs/shading.html @@ -7,11 +7,18 @@ +
+

The Mesa 3D Graphics Library

+
+ + +
+

Shading Language Support

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

@@ -20,7 +27,7 @@ Contents

- - -

Environment Variables

+

Environment Variables

The MESA_GLSL environment variable can be set to a comma-separated @@ -44,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 @@ -58,12 +64,40 @@ 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. - -

    GLSL Version

    +This is controlled via following environment variables: +
      +
    • MESA_SHADER_DUMP_PATH - path where shader sources are dumped +
    • MESA_SHADER_READ_PATH - path where replacement shaders are read +
    +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

    -The GLSL compiler currently supports version 1.20 of the shading language. +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

    + +

    +The GLSL compiler currently supports version 3.30 of the shading language.

    @@ -71,14 +105,12 @@ Several GLSL extensions are also supported:

    - -

    Unsupported Features

    +

    Unsupported Features

    XXX update this section

    @@ -91,7 +123,6 @@ in Mesa:
  • 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. -
  • gl_ClipVertex
  • The gl_Color and gl_SecondaryColor varying vars are interpolated without perspective correction @@ -101,8 +132,7 @@ All other major features of the shading language should function.

    -     -

    Implementation Notes

    +

    Implementation Notes

     - - - -

    Compiler Implementation

    +

    Compiler Implementation

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

    @@ -200,54 +229,7 @@ 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 annoted with comments to help with debugging. -Extra NOP instructions will also be inserted. -
      - -
    - - -     -

    Compiler Validation

    +

    Compiler Validation

    Developers working on the GLSL compiler should test frequently to avoid @@ -255,15 +237,14 @@ regressions.

    -The Piglit project -has many GLSL tests and the -Glean glsl1 test -tests GLSL features. +The Piglit project +has many GLSL tests.

    The Mesa demos repository also has some good GLSL tests.

    +