Shading Language Support
+Shading Language
This page describes the features and status of Mesa's support for the - + OpenGL Shading Language.
--Last updated on 17 Feb 2007. -
-Contents
-
+
- Environment variables +
- GLSL 1.40 support
- Unsupported Features -
- Implementation Notes +
- Implementation Notes
- Programming Hints -
- Stand-alone Compiler +
- 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. +
- 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 +
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
+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:
-
-
- Arrays -
- Structs -
- Linking of multiple shaders is not supported -
- Not all built-in OpenGL state variables are supported yet. - Common variables such as gl_ModelViewMatrix and gl_NormalMatrix - are supported. -
- Integer operations are not fully implemented (most are implemented - as floating point). +
- 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
@@ -53,8 +133,7 @@ All other major features of the shading language should function.
- -Implementation Notes
+Implementation Notes
- Shading language programs are compiled into low-level programs @@ -68,7 +147,8 @@ All other major features of the shading language should function.
- 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. -
- There are massive memory leaks in the compiler. +
- The ftransform() function doesn't necessarily match the results of + fixed-function transformation.
@@ -76,43 +156,9 @@ 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:
@@ -122,25 +168,20 @@ These issues will be addressed/resolved in the future.
float x = inversesqrt(y);
+
-
Stand-alone Compiler
+Stand-alone GLSL Compiler
-A unique stand-alone GLSL compiler driver has been added to Mesa. -
- -
-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 @@ -148,7 +189,7 @@ This tool is useful for:
-(compiler build instructions TBD) +After building Mesa, the compiler can be found at src/compiler/glsl/glsl_compiler
@@ -156,33 +197,55 @@ Here's an example of using the compiler to compile a vertex shader and emit GL_ARB_vertex_program-style instructions:
- glslcompiler --arb --linenumbers --vs vertshader.txt + src/compiler/glsl/glsl_compiler --version XXX --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 +
- --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
+
-The output may look similar to this:
+The source code for Mesa's shading language compiler is in the
+src/compiler/glsl/
directory.
+
+XXX provide some info about the compiler....
--!!ARBvp1.0 - 0: MOV result.texcoord[0], vertex.texcoord[0]; - 1: DP4 temp0.x, state.matrix.mvp.row[0], vertex.position; - 2: DP4 temp0.y, state.matrix.mvp.row[1], vertex.position; - 3: DP4 temp0.z, state.matrix.mvp.row[2], vertex.position; - 4: DP4 temp0.w, state.matrix.mvp.row[3], vertex.position; - 5: MOV result.position, temp0; - 6: END -
-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. +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).
+ +Compiler Validation
+ ++Developers working on the GLSL compiler should test frequently to avoid +regressions. +
+ ++The Piglit project +has many GLSL tests. +
+-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. +The Mesa demos repository also has some good GLSL tests.
- - +