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