Shading Language Support

-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. -
nopt - disable compiler optimizations -
opt - force compiler optimizations -
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 -

-Example: export MESA_GLSL=dump,nopt -

GLSL Version

-The GLSL compiler currently supports version 1.20 of the shading language. -

-Several GLSL extensions are also supported: -

GL_ARB_draw_buffers -
GL_ARB_texture_rectangle -
GL_ARB_fragment_coord_conventions -
GL_EXT_texture_array -

Unsupported Features

XXX update this section

-The following features of the shading language are not yet fully supported -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 -

-All other major features of the shading language should function. -

Implementation Notes

Shading language programs are compiled into low-level programs - very similar to those of GL_ARB_vertex/fragment_program. -
All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full - float[4] registers. -
Float constants and variables are packed so that up to four floats - can occupy one program parameter/register. -
All function calls are inlined. -
Shaders which use too many registers will not compile. -
The quality of generated code is pretty good, register usage is fair. -
Shader error detection and reporting of errors (InfoLog) is not - very good yet. -
The ftransform() function doesn't necessarily match the results of - fixed-function transformation. -

-These issues will be addressed/resolved in the future. -

Programming Hints

Use the built-in library functions whenever possible. - For example, instead of writing this: -
```
-        float x = 1.0 / sqrt(y);
-
```
- Write this: -
```
-        float x = inversesqrt(y);
-
```
-

Stand-alone GLSL Compiler

-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 -
Debugging the GLSL compiler itself -

-After building Mesa, the compiler can be found at src/glsl/glsl_compiler -

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

- -Options include -

--dump-ast - dump GPU code -
--dump-hir - dump high-level IR code -
--dump-lir - dump low-level IR code -
--link - ??? -

- - - - - -

Compiler Implementation

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

-XXX provide some info about the compiler.... -

-The final vertex and fragment programs may be interpreted in software -(see prog_execute.c) or translated into a specific hardware architecture -(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

-Developers working on the GLSL compiler should test frequently to avoid -regressions. -

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

- -

-The Mesa demos repository also has some good GLSL tests. -

- - - + + +Shading Language Support + + + + + +

Shading Language Support

+ +

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

+ +

+Contents +

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

+ + + + +

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. +
nopt - disable compiler optimizations +
opt - force compiler optimizations +
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 +

+Example: export MESA_GLSL=dump,nopt +

GLSL Version

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

+Several GLSL extensions are also supported: +

GL_ARB_draw_buffers +
GL_ARB_texture_rectangle +
GL_ARB_fragment_coord_conventions +
GL_EXT_texture_array +

Unsupported Features

XXX update this section

+The following features of the shading language are not yet fully supported +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 +

+All other major features of the shading language should function. +

Implementation Notes

Shading language programs are compiled into low-level programs + very similar to those of GL_ARB_vertex/fragment_program. +
All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full + float[4] registers. +
Float constants and variables are packed so that up to four floats + can occupy one program parameter/register. +
All function calls are inlined. +
Shaders which use too many registers will not compile. +
The quality of generated code is pretty good, register usage is fair. +
Shader error detection and reporting of errors (InfoLog) is not + very good yet. +
The ftransform() function doesn't necessarily match the results of + fixed-function transformation. +

+These issues will be addressed/resolved in the future. +

Programming Hints

Use the built-in library functions whenever possible. + For example, instead of writing this: +
```
+        float x = 1.0 / sqrt(y);
+
```
+ Write this: +
```
+        float x = inversesqrt(y);
+
```
+

Stand-alone GLSL Compiler

+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 +
Debugging the GLSL compiler itself +

+After building Mesa, the compiler can be found at src/glsl/glsl_compiler +

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

+ +Options include +

--dump-ast - dump GPU code +
--dump-hir - dump high-level IR code +
--dump-lir - dump low-level IR code +
--link - ??? +

+ + + + + +

Compiler Implementation

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

+XXX provide some info about the compiler.... +

+The final vertex and fragment programs may be interpreted in software +(see prog_execute.c) or translated into a specific hardware architecture +(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

+Developers working on the GLSL compiler should test frequently to avoid +regressions. +