Shading Language Support
+Shading Language
This page describes the features and status of Mesa's support for the - + OpenGL Shading Language.
--Last updated on 15 December 2008. -
-Contents
- Environment variables -
- GLSL 1.20 support +
- GLSL 1.40 support
- Unsupported Features
- Implementation Notes
- Programming Hints @@ -33,9 +37,7 @@ Contents
Environment Variables
+Environment Variables
The MESA_GLSL environment variable can be set to a comma-separated @@ -43,49 +45,75 @@ 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. +
- 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 +
- 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 +
- nopfrag - force fragment shader to be a simple shader that passes through the color attribute. -
- useprog - log glUseProgram calls to stderr +
- 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
- -GLSL 1.20 support
++The GLSL compiler currently supports version 3.30 of the shading language. +
-GLSL version 1.20 is supported in Mesa 7.3 and later. -Among the features/differences of GLSL 1.20 are: +Several GLSL extensions are also supported: +
-
-
mat2x3, mat2x4, etc. types and functions -transpose(), outerProduct(), matrixCompMult()functions -(but untested) -- precision qualifiers (lowp, mediump, highp) -
invariantqualifier -array.length()method -float[5] a;array syntax -centroidqualifier -- unsized array constructors -
- initializers for uniforms -
- const initializers calling built-in functions +
- 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 fully supported @@ -96,7 +124,6 @@ in Mesa:
Implementation Notes
+Implementation Notes
- Shading language programs are compiled into low-level programs
@@ -130,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:
@@ -176,28 +168,20 @@ These issues will be addressed/resolved in the future.
float x = inversesqrt(y);- - - Use ++i when possible as it's more efficient than i++
-
Stand-alone GLSL 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 @@ -205,99 +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
-- make realclean - make linux - 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 + src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert
--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 -
- --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 @@ -305,70 +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 Glean test has -been create to exercise the GLSL compiler. -
--The glsl1 test runs over 170 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.
++The Mesa demos repository also has some good GLSL tests. +
- - +