- - -

Shading Language Support

Shading Language

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

-Last updated on 28 March 2007. -

Contents

Environment variables +
GLSL 1.40 support
Unsupported Features
Implementation Notes
Programming Hints
Stand-alone GLSL Compiler
Compiler Implementation
Compiler Validation -
GLSL 1.20 support

- -

Unsupported Features

Environment Variables

+ +

+The MESA_GLSL environment variable can be set to a comma-separated +list of keywords to control some aspects of the GLSL compiler and shader +execution. These are generally used for debugging. +

dump - print GLSL shader code to stdout at link time +
log - log all GLSL shaders to files. + The filenames will be "shader_X.vert" or "shader_X.frag" where X + the shader ID. +
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 + texcoord[0] attributes. +
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 3.30 of the shading language. +

+ +

+Several GLSL extensions are also supported: +

GL_ARB_draw_buffers +
GL_ARB_fragment_coord_conventions +
GL_ARB_shader_bit_encoding +

+ + +

Unsupported Features

+ +

XXX update this section

-The following features of the shading language are not yet supported +The following features of the shading language are not yet fully supported in Mesa:

Dereferencing arrays with non-constant indexes -
Comparison of user-defined structs -
Linking of multiple shaders is not supported -
gl_ClipVertex -
The derivative functions such as dFdx() are not implemented -
The inverse trig functions asin(), acos(), and atan() are not implemented +
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.
The gl_Color and gl_SecondaryColor varying vars are interpolated without perspective correction -
Floating point literal suffixes 'f' and 'F' aren't allowed.

@@ -57,8 +133,7 @@ All other major features of the shading language should function.

- -

Implementation Notes

Shading language programs are compiled into low-level programs @@ -81,74 +156,32 @@ These issues will be addressed/resolved in the future.
-
-
Programming Hints
+
Programming Hints
- Declare in function parameters as const whenever possible. - This improves the efficiency of function inlining. -
- To reduce register usage, declare variables within smaller scopes. - For example, the following code: -
```
-    void main()
-    {
-       vec4 a1, a2, b1, b2;
-       gl_Position = expression using a1, a2.
-       gl_Color = expression using b1, b2;
-    }
-
```
  - Can be rewritten as follows to use half as many registers: -
```
-    void main()
-    {
-       {
-          vec4 a1, a2;
-          gl_Position = expression using a1, a2.
-       }
-       {
-          vec4 b1, b2;
-          gl_Color = expression using b1, b2;
-       }
-    }
-
```
  - Alternately, rather than using several float variables, use - a vec4 instead. Use swizzling and writemasks to access the - components of the vec4 as floats. -
- 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);
 
```
  -
- - Use ++i when possible as it's more efficient than i++
-
-
Stand-alone GLSL Compiler
- -
-A unique stand-alone GLSL compiler driver has been added to Mesa. -
+
Stand-alone GLSL Compiler

-The stand-alone compiler (like a conventional command-line compiler) -is a tool that accepts Shading Language programs and emits low-level -GPU programs. +The stand-alone GLSL compiler program can be used to compile GLSL shaders +into low-level GPU code.

This tool is useful for: -
+
- Inspecting GPU code to gain insight into compilation
- Generating initial GPU code for subsequent hand-tuning @@ -156,97 +189,40 @@ This tool is useful for:
-After building Mesa, the glslcompiler can be built by manually running: +After building Mesa, the compiler can be found at src/compiler/glsl/glsl_compiler
-
```
-    cd src/mesa/drivers/glslcompiler
-    make
-
```
-
Here's an example of using the compiler to compile a vertex shader and emit GL_ARB_vertex_program-style instructions:
```
-    bin/glslcompiler --debug --numbers --fs progs/glsl/CH06-brick.frag.txt
-
```
-
-results in: -
-
```
-# Fragment Program/Shader
-  0: RCP TEMP[4].x, UNIFORM[2].xxxx;
-  1: RCP TEMP[4].y, UNIFORM[2].yyyy;
-  2: MUL TEMP[3].xy, VARYING[0], TEMP[4];
-  3: MOV TEMP[1], TEMP[3];
-  4: MUL TEMP[0].w, TEMP[1].yyyy, CONST[4].xxxx;
-  5: FRC TEMP[1].z, TEMP[0].wwww;
-  6: SGT.C TEMP[0].w, TEMP[1].zzzz, CONST[4].xxxx;
-  7: IF (NE.wwww); # (if false, goto 9);
-  8:    ADD TEMP[1].x, TEMP[1].xxxx, CONST[4].xxxx;
-  9: ENDIF;
- 10: FRC TEMP[1].xy, TEMP[1];
- 11: SGT TEMP[2].xy, UNIFORM[3], TEMP[1];
- 12: MUL TEMP[1].z, TEMP[2].xxxx, TEMP[2].yyyy;
- 13: LRP TEMP[0], TEMP[1].zzzz, UNIFORM[0], UNIFORM[1];
- 14: MUL TEMP[0].xyz, TEMP[0], VARYING[1].xxxx;
- 15: MOV OUTPUT[0].xyz, TEMP[0];
- 16: MOV OUTPUT[0].w, CONST[4].yyyy;
- 17: END
+    src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert
 
```
-
-Note that some shading language constructs (such as uniform and varying -variables) aren't expressible in ARB or NV-style programs. -Therefore, the resulting output is not always legal by definition of -those program languages. -
-
-Also note that this compiler driver is still under development. -Over time, the correctness of the GPU programs, with respect to the ARB -and NV languagues, should improve. -
- +Options include +
- --dump-ast - dump GPU code +
- --dump-hir - dump high-level IR code +
- --dump-lir - dump low-level IR code +
- --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 +
-
-
Compiler Implementation
+
Compiler Implementation

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

-The compiler follows a fairly standard design and basically works as follows: +XXX provide some info about the compiler....
-
- The input string is tokenized (see grammar.c) and parsed -(see slang_compiler_*.c) to produce an Abstract Syntax Tree (AST). -The nodes in this tree are slang_operation structures -(see slang_compile_operation.h). -The nodes are decorated with symbol table, scoping and datatype information. -
- The AST is converted into an Intermediate representation (IR) tree -(see the slang_codegen.c file). -The IR nodes represent basic GPU instructions, like add, dot product, -move, etc. -The IR tree is mostly a binary tree, but a few nodes have three or four -children. -In principle, the IR tree could be executed by doing an in-order traversal. -
- The IR tree is traversed in-order to emit code (see slang_emit.c). -This is also when registers are allocated to store variables and temps. -
- In the future, a pattern-matching code generator-generator may be -used for code generation. -Programs such as L-BURG (Bottom-Up Rewrite Generator) and Twig look for -patterns in IR trees, compute weights for subtrees and use the weights -to select the best instructions to represent the sub-tree. -
- The emitted GPU instructions (see prog_instruction.h) are stored in a -gl_program object (see mtypes.h). -
- When a fragment shader and vertex shader are linked (see slang_link.c) -the varying vars are matched up, uniforms are merged, and vertex -attributes are resolved (rewriting instructions as needed). -
The final vertex and fragment programs may be interpreted in software @@ -254,104 +230,22 @@ The final vertex and fragment programs may be interpreted in software (see drivers/dri/i915/i915_fragprog.c for example).
-
Code Generation Options
+
Compiler Validation

-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
- -
-A new Glean test has -been create to exercise the GLSL compiler. -
-
-The glsl1 test runs over 150 sub-tests to check that the language -features and built-in functions work properly. -This test should be run frequently while working on the compiler to catch +Developers working on the GLSL compiler should test frequently to avoid regressions.
+
-The test coverage is reasonably broad and complete but additional tests -should be added. +The Piglit project +has many GLSL tests.
- - -
-
GLSL 1.20 support
-
-Support for GLSL version 1.20 is underway. Status as follows. +The Mesa demos repository also has some good GLSL tests.
-
Supported
-
- mat2x3, mat2x4, etc. types and functions -
- transpose(), outerProduct(), matrixCompMult() functions -(but untested) -
- precision qualifiers (lowp, mediump, highp) -
- -
Partially Complete
-
- invariant qualifier -
- -
Not Completed
-
- array.length() method -
- float[5] a; array syntax -
- centroid qualifier -
- unsized array constructors -
- initializers for uniforms -
- const initializers calling built-in functions -
- - - - - - +

Shading Language Support

Shading Language

Unsupported Features

Environment Variables

Experimenting with Shader Replacements

Capturing Shaders

GLSL Version

Unsupported Features

Implementation Notes

Implementation Notes

Programming Hints

Programming Hints

Stand-alone GLSL Compiler

Stand-alone GLSL Compiler

Compiler Implementation

Compiler Implementation

Code Generation Options

Compiler Validation

Compiler Validation

GLSL 1.20 support

Supported

Partially Complete

Not Completed