Shading Language Support

Shading Language

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 @@ -58,16 +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

+ +

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

@@ -131,11 +162,11 @@ These issues will be addressed/resolved in the future.

Use the built-in library functions whenever possible. For example, instead of writing this:

-        float x = 1.0 / sqrt(y);
+float x = 1.0 / sqrt(y);

Write this:

-        float x = inversesqrt(y);
+float x = inversesqrt(y);

@@ -158,7 +189,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 +197,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 +205,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 +217,7 @@ Options include

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

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

- -

Compiler Validation

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

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