X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=docs%2Fshading.html;h=ae7b8e6c5eae19d4e8fddfa9a8240c19505b7c7c;hb=3d11b075f0af363f8c8c433508b379454d8db9a8;hp=c41d4a9be2b18e73bb6006774e5acc4d2e790782;hpb=222d2f2ac2c7d93cbc0643082c78278ad2c8cfce;p=mesa.git diff --git a/docs/shading.html b/docs/shading.html index c41d4a9be2b..ae7b8e6c5ea 100644 --- a/docs/shading.html +++ b/docs/shading.html @@ -1,16 +1,24 @@ - + + + + + Shading Language + + + -Shading Language Support +
+ The Mesa 3D Graphics Library +
- + +
- - -

Shading Language Support

+

Shading Language

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

@@ -19,7 +27,7 @@ Contents

- - -

Environment Variables

+

Environment Variables

The MESA_GLSL environment variable can be set to a comma-separated @@ -43,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 @@ -52,17 +59,46 @@ execution. These are generally used for debugging.
  • nopfrag - force fragment shader to be a simple shader that passes through the color attribute.
  • useprog - log glUseProgram calls to stderr +
  • errors - GLSL compilation and link errors will be reported to stderr.

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

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

    -     -

    GLSL Version

    +

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

    @@ -70,14 +106,12 @@ Several GLSL extensions are also supported:

    - -

    Unsupported Features

    +

    Unsupported Features

    XXX update this section

    @@ -90,7 +124,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 @@ -100,8 +133,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.

    @@ -199,54 +230,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 @@ -254,15 +238,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.

    - - +
    • + +