1Shading Language 2================ 3 4This page describes the features and status of Mesa's support for the 5`OpenGL Shading Language <https://opengl.org/documentation/glsl/>`__. 6 7.. _envvars: 8 9Environment Variables 10--------------------- 11 12The **MESA_GLSL** environment variable can be set to a comma-separated 13list of keywords to control some aspects of the GLSL compiler and shader 14execution. These are generally used for debugging. 15 16- **dump** - print GLSL shader code to stdout at link time 17- **log** - log all GLSL shaders to files. The filenames will be 18 "shader_X.vert" or "shader_X.frag" where X the shader ID. 19- **cache_info** - print debug information about shader cache 20- **cache_fb** - force cached shaders to be ignored and do a full 21 recompile via the fallback path 22- **uniform** - print message to stdout when glUniform is called 23- **nopvert** - force vertex shaders to be a simple shader that just 24 transforms the vertex position with ftransform() and passes through 25 the color and texcoord[0] attributes. 26- **nopfrag** - force fragment shader to be a simple shader that passes 27 through the color attribute. 28- **useprog** - log glUseProgram calls to stderr 29- **errors** - GLSL compilation and link errors will be reported to 30 stderr. 31 32Example: export MESA_GLSL=dump,nopt 33 34.. _replacement: 35 36Experimenting with Shader Replacements 37~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 38 39Shaders can be dumped and replaced on runtime for debugging purposes. 40This is controlled via following environment variables: 41 42- **MESA_SHADER_DUMP_PATH** - path where shader sources are dumped 43- **MESA_SHADER_READ_PATH** - path where replacement shaders are read 44 45Note, path set must exist before running for dumping or replacing to 46work. When both are set, these paths should be different so the dumped 47shaders do not clobber the replacement shaders. Also, the filenames of 48the replacement shaders should match the filenames of the corresponding 49dumped shaders. 50 51.. _capture: 52 53Capturing Shaders 54~~~~~~~~~~~~~~~~~ 55 56Setting **MESA_SHADER_CAPTURE_PATH** to a directory will cause the 57compiler to write ``.shader_test`` files for use with 58`shader-db <https://gitlab.freedesktop.org/mesa/shader-db>`__, a tool 59which compiler developers can use to gather statistics about shaders 60(instructions, cycles, memory accesses, and so on). 61 62Notably, this captures linked GLSL shaders - with all stages together - 63as well as ARB programs. 64 65GLSL Version 66------------ 67 68The GLSL compiler currently supports version 3.30 of the shading 69language. 70 71Several GLSL extensions are also supported: 72 73- GL_ARB_draw_buffers 74- GL_ARB_fragment_coord_conventions 75- GL_ARB_shader_bit_encoding 76 77Unsupported Features 78-------------------- 79 80XXX update this section 81 82The following features of the shading language are not yet fully 83supported in Mesa: 84 85- Linking of multiple shaders does not always work. Currently, linking 86 is implemented through shader concatenation and re-compiling. This 87 doesn't always work because of some #pragma and preprocessor issues. 88- The gl_Color and gl_SecondaryColor varying vars are interpolated 89 without perspective correction 90 91All other major features of the shading language should function. 92 93Implementation Notes 94-------------------- 95 96- Shading language programs are compiled into low-level programs very 97 similar to those of GL_ARB_vertex/fragment_program. 98- All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full 99 float[4] registers. 100- Float constants and variables are packed so that up to four floats 101 can occupy one program parameter/register. 102- All function calls are inlined. 103- Shaders which use too many registers will not compile. 104- The quality of generated code is pretty good, register usage is fair. 105- Shader error detection and reporting of errors (InfoLog) is not very 106 good yet. 107- The ftransform() function doesn't necessarily match the results of 108 fixed-function transformation. 109 110These issues will be addressed/resolved in the future. 111 112Programming Hints 113----------------- 114 115- Use the built-in library functions whenever possible. For example, 116 instead of writing this: 117 118 .. code-block:: glsl 119 120 float x = 1.0 / sqrt(y); 121 122 Write this: 123 124 .. code-block:: glsl 125 126 float x = inversesqrt(y); 127 128Stand-alone GLSL Compiler 129------------------------- 130 131The stand-alone GLSL compiler program can be used to compile GLSL 132shaders into low-level GPU code. 133 134This tool is useful for: 135 136- Inspecting GPU code to gain insight into compilation 137- Generating initial GPU code for subsequent hand-tuning 138- Debugging the GLSL compiler itself 139 140After building Mesa, the compiler can be found at 141src/compiler/glsl/glsl_compiler 142 143Here's an example of using the compiler to compile a vertex shader and 144emit GL_ARB_vertex_program-style instructions: 145 146.. code-block:: console 147 148 src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert 149 150Options include 151 152- **--dump-ast** - dump GPU code 153- **--dump-hir** - dump high-level IR code 154- **--dump-lir** - dump low-level IR code 155- **--dump-builder** - dump GLSL IR code 156- **--link** - link shaders 157- **--just-log** - display only shader / linker info if exist, without 158 any header or separator 159- **--version** - [Mandatory] define the GLSL version to use 160 161Compiler Implementation 162----------------------- 163 164The source code for Mesa's shading language compiler is in the 165``src/compiler/glsl/`` directory. 166 167XXX provide some info about the compiler.... 168 169The final vertex and fragment programs may be interpreted in software 170(see prog_execute.c) or translated into a specific hardware architecture 171(see drivers/dri/i915/i915_fragprog.c for example). 172 173Compiler Validation 174------------------- 175 176Developers working on the GLSL compiler should test frequently to avoid 177regressions. 178 179The `Piglit <https://piglit.freedesktop.org/>`__ project has many GLSL 180tests. 181 182The Mesa demos repository also has some good GLSL tests. 183