docs/shading.rst

   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
   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
  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
  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
  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
 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
 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
 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
 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.