1848b8605Smrg<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2848b8605Smrg<html lang="en"> 3848b8605Smrg<head> 4848b8605Smrg <meta http-equiv="content-type" content="text/html; charset=utf-8"> 5848b8605Smrg <title>Shading Language Support</title> 6848b8605Smrg <link rel="stylesheet" type="text/css" href="mesa.css"> 7848b8605Smrg</head> 8848b8605Smrg<body> 9848b8605Smrg 10848b8605Smrg<div class="header"> 11848b8605Smrg <h1>The Mesa 3D Graphics Library</h1> 12848b8605Smrg</div> 13848b8605Smrg 14848b8605Smrg<iframe src="contents.html"></iframe> 15848b8605Smrg<div class="content"> 16848b8605Smrg 17848b8605Smrg<h1>Shading Language Support</h1> 18848b8605Smrg 19848b8605Smrg<p> 20848b8605SmrgThis page describes the features and status of Mesa's support for the 21b8e80941Smrg<a href="https://opengl.org/documentation/glsl/"> 22848b8605SmrgOpenGL Shading Language</a>. 23848b8605Smrg</p> 24848b8605Smrg 25848b8605Smrg<p> 26848b8605SmrgContents 27848b8605Smrg</p> 28848b8605Smrg<ul> 29848b8605Smrg<li><a href="#envvars">Environment variables</a> 30848b8605Smrg<li><a href="#support">GLSL 1.40 support</a> 31848b8605Smrg<li><a href="#unsup">Unsupported Features</a> 32848b8605Smrg<li><a href="#notes">Implementation Notes</a> 33848b8605Smrg<li><a href="#hints">Programming Hints</a> 34848b8605Smrg<li><a href="#standalone">Stand-alone GLSL Compiler</a> 35848b8605Smrg<li><a href="#implementation">Compiler Implementation</a> 36848b8605Smrg<li><a href="#validation">Compiler Validation</a> 37848b8605Smrg</ul> 38848b8605Smrg 39848b8605Smrg 40848b8605Smrg<h2 id="envvars">Environment Variables</h2> 41848b8605Smrg 42848b8605Smrg<p> 43848b8605SmrgThe <b>MESA_GLSL</b> environment variable can be set to a comma-separated 44848b8605Smrglist of keywords to control some aspects of the GLSL compiler and shader 45848b8605Smrgexecution. These are generally used for debugging. 46848b8605Smrg</p> 47848b8605Smrg<ul> 48848b8605Smrg<li><b>dump</b> - print GLSL shader code to stdout at link time 49848b8605Smrg<li><b>log</b> - log all GLSL shaders to files. 50848b8605Smrg The filenames will be "shader_X.vert" or "shader_X.frag" where X 51848b8605Smrg the shader ID. 52b8e80941Smrg<li><b>cache_info</b> - print debug information about shader cache 53b8e80941Smrg<li><b>cache_fb</b> - force cached shaders to be ignored and do a full 54b8e80941Smrg recompile via the fallback path</li> 55848b8605Smrg<li><b>uniform</b> - print message to stdout when glUniform is called 56848b8605Smrg<li><b>nopvert</b> - force vertex shaders to be a simple shader that just transforms 57848b8605Smrg the vertex position with ftransform() and passes through the color and 58848b8605Smrg texcoord[0] attributes. 59848b8605Smrg<li><b>nopfrag</b> - force fragment shader to be a simple shader that passes 60848b8605Smrg through the color attribute. 61848b8605Smrg<li><b>useprog</b> - log glUseProgram calls to stderr 62b8e80941Smrg<li><b>errors</b> - GLSL compilation and link errors will be reported to stderr. 63848b8605Smrg</ul> 64848b8605Smrg<p> 65848b8605SmrgExample: export MESA_GLSL=dump,nopt 66848b8605Smrg</p> 67848b8605Smrg 68b8e80941Smrg<h3 id="replacement">Experimenting with Shader Replacements</h3> 69b8e80941Smrg<p> 70b8e80941SmrgShaders can be dumped and replaced on runtime for debugging purposes. This 71b8e80941Smrgfeature is not currently supported by SCons build. 72b8e80941Smrg 73b8e80941SmrgThis is controlled via following environment variables: 74b8e80941Smrg</p> 75b8e80941Smrg<ul> 76b8e80941Smrg<li><b>MESA_SHADER_DUMP_PATH</b> - path where shader sources are dumped 77b8e80941Smrg<li><b>MESA_SHADER_READ_PATH</b> - path where replacement shaders are read 78b8e80941Smrg</ul> 79b8e80941SmrgNote, path set must exist before running for dumping or replacing to work. 80b8e80941SmrgWhen both are set, these paths should be different so the dumped shaders do 81b8e80941Smrgnot clobber the replacement shaders. Also, the filenames of the replacement shaders 82b8e80941Smrgshould match the filenames of the corresponding dumped shaders. 83b8e80941Smrg 84b8e80941Smrg<h3 id="capture">Capturing Shaders</h3> 85b8e80941Smrg 86b8e80941Smrg<p> 87b8e80941SmrgSetting <b>MESA_SHADER_CAPTURE_PATH</b> to a directory will cause the compiler 88b8e80941Smrgto write <tt>.shader_test</tt> files for use with 89b8e80941Smrg<a href="https://gitlab.freedesktop.org/mesa/shader-db">shader-db</a>, a tool 90b8e80941Smrgwhich compiler developers can use to gather statistics about shaders 91b8e80941Smrg(instructions, cycles, memory accesses, and so on). 92b8e80941Smrg</p> 93b8e80941Smrg<p> 94b8e80941SmrgNotably, this captures linked GLSL shaders - with all stages together - 95b8e80941Smrgas well as ARB programs. 96b8e80941Smrg</p> 97848b8605Smrg 98848b8605Smrg<h2 id="support">GLSL Version</h2> 99848b8605Smrg 100848b8605Smrg<p> 101848b8605SmrgThe GLSL compiler currently supports version 3.30 of the shading language. 102848b8605Smrg</p> 103848b8605Smrg 104848b8605Smrg<p> 105848b8605SmrgSeveral GLSL extensions are also supported: 106848b8605Smrg</p> 107848b8605Smrg<ul> 108848b8605Smrg<li>GL_ARB_draw_buffers 109848b8605Smrg<li>GL_ARB_fragment_coord_conventions 110848b8605Smrg<li>GL_ARB_shader_bit_encoding 111848b8605Smrg</ul> 112848b8605Smrg 113848b8605Smrg 114848b8605Smrg<h2 id="unsup">Unsupported Features</h2> 115848b8605Smrg 116848b8605Smrg<p>XXX update this section</p> 117848b8605Smrg 118848b8605Smrg<p> 119848b8605SmrgThe following features of the shading language are not yet fully supported 120848b8605Smrgin Mesa: 121848b8605Smrg</p> 122848b8605Smrg 123848b8605Smrg<ul> 124848b8605Smrg<li>Linking of multiple shaders does not always work. Currently, linking 125848b8605Smrg is implemented through shader concatenation and re-compiling. This 126848b8605Smrg doesn't always work because of some #pragma and preprocessor issues. 127848b8605Smrg<li>The gl_Color and gl_SecondaryColor varying vars are interpolated 128848b8605Smrg without perspective correction 129848b8605Smrg</ul> 130848b8605Smrg 131848b8605Smrg<p> 132848b8605SmrgAll other major features of the shading language should function. 133848b8605Smrg</p> 134848b8605Smrg 135848b8605Smrg 136848b8605Smrg<h2 id="notes">Implementation Notes</h2> 137848b8605Smrg 138848b8605Smrg<ul> 139848b8605Smrg<li>Shading language programs are compiled into low-level programs 140848b8605Smrg very similar to those of GL_ARB_vertex/fragment_program. 141848b8605Smrg<li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full 142848b8605Smrg float[4] registers. 143848b8605Smrg<li>Float constants and variables are packed so that up to four floats 144848b8605Smrg can occupy one program parameter/register. 145848b8605Smrg<li>All function calls are inlined. 146848b8605Smrg<li>Shaders which use too many registers will not compile. 147848b8605Smrg<li>The quality of generated code is pretty good, register usage is fair. 148848b8605Smrg<li>Shader error detection and reporting of errors (InfoLog) is not 149848b8605Smrg very good yet. 150848b8605Smrg<li>The ftransform() function doesn't necessarily match the results of 151848b8605Smrg fixed-function transformation. 152848b8605Smrg</ul> 153848b8605Smrg 154848b8605Smrg<p> 155848b8605SmrgThese issues will be addressed/resolved in the future. 156848b8605Smrg</p> 157848b8605Smrg 158848b8605Smrg 159848b8605Smrg<h2 id="hints">Programming Hints</h2> 160848b8605Smrg 161848b8605Smrg<ul> 162848b8605Smrg<li>Use the built-in library functions whenever possible. 163848b8605Smrg For example, instead of writing this: 164848b8605Smrg<pre> 165848b8605Smrg float x = 1.0 / sqrt(y); 166848b8605Smrg</pre> 167848b8605Smrg Write this: 168848b8605Smrg<pre> 169848b8605Smrg float x = inversesqrt(y); 170848b8605Smrg</pre> 171848b8605Smrg</li> 172848b8605Smrg</ul> 173848b8605Smrg 174848b8605Smrg 175848b8605Smrg<h2 id="standalone">Stand-alone GLSL Compiler</h2> 176848b8605Smrg 177848b8605Smrg<p> 178848b8605SmrgThe stand-alone GLSL compiler program can be used to compile GLSL shaders 179848b8605Smrginto low-level GPU code. 180848b8605Smrg</p> 181848b8605Smrg 182848b8605Smrg<p> 183848b8605SmrgThis tool is useful for: 184848b8605Smrg</p> 185848b8605Smrg<ul> 186848b8605Smrg<li>Inspecting GPU code to gain insight into compilation 187848b8605Smrg<li>Generating initial GPU code for subsequent hand-tuning 188848b8605Smrg<li>Debugging the GLSL compiler itself 189848b8605Smrg</ul> 190848b8605Smrg 191848b8605Smrg<p> 192b8e80941SmrgAfter building Mesa, the compiler can be found at src/compiler/glsl/glsl_compiler 193848b8605Smrg</p> 194848b8605Smrg 195848b8605Smrg<p> 196848b8605SmrgHere's an example of using the compiler to compile a vertex shader and 197848b8605Smrgemit GL_ARB_vertex_program-style instructions: 198848b8605Smrg</p> 199848b8605Smrg<pre> 200b8e80941Smrg src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert 201848b8605Smrg</pre> 202848b8605Smrg 203848b8605SmrgOptions include 204848b8605Smrg<ul> 205848b8605Smrg<li><b>--dump-ast</b> - dump GPU code 206848b8605Smrg<li><b>--dump-hir</b> - dump high-level IR code 207848b8605Smrg<li><b>--dump-lir</b> - dump low-level IR code 208b8e80941Smrg<li><b>--dump-builder</b> - dump GLSL IR code 209b8e80941Smrg<li><b>--link</b> - link shaders 210b8e80941Smrg<li><b>--just-log</b> - display only shader / linker info if exist, 211b8e80941Smrgwithout any header or separator 212b8e80941Smrg<li><b>--version</b> - [Mandatory] define the GLSL version to use 213848b8605Smrg</ul> 214848b8605Smrg 215848b8605Smrg 216848b8605Smrg<h2 id="implementation">Compiler Implementation</h2> 217848b8605Smrg 218848b8605Smrg<p> 219848b8605SmrgThe source code for Mesa's shading language compiler is in the 220b8e80941Smrg<code>src/compiler/glsl/</code> directory. 221848b8605Smrg</p> 222848b8605Smrg 223848b8605Smrg<p> 224848b8605SmrgXXX provide some info about the compiler.... 225848b8605Smrg</p> 226848b8605Smrg 227848b8605Smrg<p> 228848b8605SmrgThe final vertex and fragment programs may be interpreted in software 229848b8605Smrg(see prog_execute.c) or translated into a specific hardware architecture 230848b8605Smrg(see drivers/dri/i915/i915_fragprog.c for example). 231848b8605Smrg</p> 232848b8605Smrg 233848b8605Smrg<h2 id="validation">Compiler Validation</h2> 234848b8605Smrg 235848b8605Smrg<p> 236848b8605SmrgDevelopers working on the GLSL compiler should test frequently to avoid 237848b8605Smrgregressions. 238848b8605Smrg</p> 239848b8605Smrg 240848b8605Smrg<p> 241b8e80941SmrgThe <a href="https://piglit.freedesktop.org/">Piglit</a> project 242848b8605Smrghas many GLSL tests. 243848b8605Smrg</p> 244848b8605Smrg 245848b8605Smrg<p> 246848b8605SmrgThe Mesa demos repository also has some good GLSL tests. 247848b8605Smrg</p> 248848b8605Smrg 249848b8605Smrg</div> 250848b8605Smrg</body> 251848b8605Smrg</html> 252