1Shading Language 2================ 3 4This page describes the features and status of Mesa's support for the 5`OpenGL Shading Language <https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language>`__. 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, IR, and NIR to stdout at link time 17- **source** - print GLSL shader code to stdout at link time 18- **log** - log all GLSL shaders to files. The filenames will be 19 "shader_X.vert" or "shader_X.frag" where X the shader ID. 20- **cache_info** - print debug information about shader cache 21- **cache_fb** - force cached shaders to be ignored and do a full 22 recompile via the fallback path 23- **uniform** - print message to stdout when glUniform is called 24- **nopvert** - force vertex shaders to be a simple shader that just 25 transforms the vertex position with ftransform() and passes through 26 the color and texcoord[0] attributes. 27- **nopfrag** - force fragment shader to be a simple shader that passes 28 through the color attribute. 29- **useprog** - log glUseProgram calls to stderr 30- **errors** - GLSL compilation and link errors will be reported to 31 stderr. 32 33Example: export MESA_GLSL=dump,nopt 34 35.. _replacement: 36 37Experimenting with Shader Replacements 38~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 39 40Shaders can be dumped and replaced on runtime for debugging purposes. 41This is controlled via following environment variables: 42 43- **MESA_SHADER_DUMP_PATH** - path where shader sources are dumped 44- **MESA_SHADER_READ_PATH** - path where replacement shaders are read 45 46Note, path set must exist before running for dumping or replacing to 47work. When both are set, these paths should be different so the dumped 48shaders do not clobber the replacement shaders. Also, the filenames of 49the replacement shaders should match the filenames of the corresponding 50dumped shaders. 51 52.. _capture: 53 54Capturing Shaders 55~~~~~~~~~~~~~~~~~ 56 57Setting **MESA_SHADER_CAPTURE_PATH** to a directory will cause the 58compiler to write ``.shader_test`` files for use with 59`shader-db <https://gitlab.freedesktop.org/mesa/shader-db>`__, a tool 60which compiler developers can use to gather statistics about shaders 61(instructions, cycles, memory accesses, and so on). 62 63Notably, this captures linked GLSL shaders - with all stages together - 64as well as ARB programs. 65 66GLSL Version 67------------ 68 69The GLSL compiler currently supports version 3.30 of the shading 70language. 71 72Several GLSL extensions are also supported: 73 74- :ext:`GL_ARB_draw_buffers` 75- :ext:`GL_ARB_fragment_coord_conventions` 76- :ext:`GL_ARB_shader_bit_encoding` 77 78Unsupported Features 79-------------------- 80 81XXX update this section 82 83The following features of the shading language are not yet fully 84supported in Mesa: 85 86- Linking of multiple shaders does not always work. Currently, linking 87 is implemented through shader concatenation and re-compiling. This 88 doesn't always work because of some #pragma and preprocessor issues. 89- The gl_Color and gl_SecondaryColor varying vars are interpolated 90 without perspective correction 91 92All other major features of the shading language should function. 93 94Implementation Notes 95-------------------- 96 97- Shading language programs are compiled into low-level programs very 98 similar to those of :ext:`GL_ARB_vertex_program` / 99 :ext:`GL_ARB_fragment_program`. 100- All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full 101 float[4] registers. 102- Float constants and variables are packed so that up to four floats 103 can occupy one program parameter/register. 104- All function calls are inlined. 105- Shaders which use too many registers will not compile. 106- The quality of generated code is pretty good, register usage is fair. 107- Shader error detection and reporting of errors (InfoLog) is not very 108 good yet. 109- The ftransform() function doesn't necessarily match the results of 110 fixed-function transformation. 111 112These issues will be addressed/resolved in the future. 113 114Programming Hints 115----------------- 116 117- Use the built-in library functions whenever possible. For example, 118 instead of writing this: 119 120 .. code-block:: glsl 121 122 float x = 1.0 / sqrt(y); 123 124 Write this: 125 126 .. code-block:: glsl 127 128 float x = inversesqrt(y); 129 130Stand-alone GLSL Compiler 131------------------------- 132 133The stand-alone GLSL compiler program can be used to compile GLSL 134shaders into GLSL IR code. 135 136This tool is useful for: 137 138- Inspecting GLSL frontend behavior to gain insight into compilation 139- Debugging the GLSL compiler itself 140 141After building Mesa with the ``-Dtools=glsl`` meson option, the compiler will be 142installed as the binary ``glsl_compiler``. 143 144Here's an example of using the compiler to compile a vertex shader and 145emit :ext:`GL_ARB_vertex_program`-style instructions: 146 147.. code-block:: sh 148 149 src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert 150 151Options include 152 153- **--dump-ast** - dump source syntax tree 154- **--dump-hir** - dump high-level IR code 155- **--dump-lir** - dump low-level 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