OpenGL / OpenGL ES Reference Compiler

Glslang is the official reference compiler front end for the OpenGL ES and OpenGL shading languages. It implements a strict interpretation of the specifications for these languages. It is open and free for anyone to use, either from a command line or programmatically. The OpenGL and OpenGL ES working groups are committed to maintaining consistency between the reference compiler and the corresponding shading language specifications.

Purpose

The primary purpose of the reference compiler is to identify shader portability issues. If glslang accepts a shader without errors, then all OpenGL and OpenGL ES implementations claiming to support the shader's language version should also accept the shader without errors. Likewise, if glslang reports an error when compiling a shader, all OpenGL and OpenGL ES implementations for that language version should report errors, unless the glslang errors are caused by differences in implementation-defined limits or extension support (see below).

Secondarily, glslang is also suitable for programmatic use in a tool chain or a driver, translating the input source into an abstract syntax tree that can be translated into an intermediate representation for machine-independent processing and lowering to machine-specific code. Glslang can also return (even from the command line) uniform variable reflection information (before optimization).

Using Glslang from the Command Line

Basic use from the command line is simple. Put your shader in a file, e.g., shader.frag, and execute:

glslangValidator shader.frag

Any GLSL errors in shader.frag will be printed out. Be sure that your shader includes the appropriate #version statement; the default is #version 100, i.e., the shading language supported in OpenGL ES 2.0. The stage is indicated by the file's extension:

.vert - a vertex shader
.tesc - a tessellation control shader
.tese - a tessellation evaluation shader
.geom - a geometry shader
.frag - a fragment shader
.comp - a compute shader

There is also a non-shader file extension:

.conf - a configuration file of implementation-dependent limits

Multiple shaders can be specified on the same command line.

Specifying implementation-dependent limits

Some versions of GLSL ES allow compilation to fail if a shader uses too many hardware resources, or if it uses constructs that are optional in the language version (e.g. dynamic looping and array indexing in GLSL ES 1.0). By default, glslang tries to enforce these constraints by rejecting shaders that exceed the minimum limits required in the language specification.

To override the default limits, you can supply a .conf file along with your shader. An example default .conf file can be generated by using the '-c' command-line option. You can put this configuration information into a file with a .conf extension, edit it, and then include it on the command line with your shader, e.g.,

glslangValidator -c > my.conf
# edit my.conf
glslangValidator my.conf shader.frag

We encourage hardware vendors to provide .conf files that encode the hardware limits of their GPUs, so that glslang can be used to predict whether a given shader will compile on a given GPU. However, be aware that only shaders that compile with the default configuration are expected to compile on any correct compiler.

The default use described above will report any compile-time issues. To detect link-time issues, use the '-l' (for link) command-line option. You can supply multiple shader files, which glslang will attempt to link as appropriate for the language version you are using.

Other options are available. Execute glslangValidator with no arguments to get a usage statement, which will show additional options.

Using the Reference Compiler in Programs

There is a C++ class-oriented interface for using glslang programmatically. See the top-level README.txt in the Khronos SVN project in the section "Programmatic Interfaces". A C-style functional interface is also provided.

Where to Get Glslang

Binaries

To get pre-compiled binaries for the command-line tool, use a Subversion client to access (or save the files from your web browser) https://github.com/KhronosGroup/glslang/releases/tag/master-tot. There is a Windows directory and a Linux directory. The binaries can be placed where desired, and invoked directly as "glslangValidator".

Source Code

Full source is available at GitHub at SVN from https://github.com/KhronosGroup/glslang. See the README.txt in that directory for more information. Build solutions are based on CMake, which is actively used on multiple platforms.

Reporting Problems

In most cases, differences in behavior between the reference compiler and a specific GPU vendor's compiler should be reported to the GPU vendor. Including the reference compiler version number and output on your shaders will help the vendor address the problem quickly. If the vendor determines that the problem is in the reference compiler, they'll report it to us and we will fix it.

If you find a bug in the reference compiler itself (e.g. it crashes or produces clearly incorrect output), please file a bug on the Khronos public bugzilla at [1]. Use product "OpenGL" or "OpenGL-ES" as appropriate, with Component "GLSL Reference Implementation". Please include the exact version number (obtainable via the '-v' command-line option), and a set of inputs that triggers the problem. If you have a fix for the problem, you can also attach a patch file against the appropriate source version.

More general issues with glslang can be handled using GitHub issues or even submitting a pull request, at https://github.com/KhronosGroup/glslang.

Current Status

Glslang is complete for compile-time validation of:

Glslang also provides compile-time validation of:

(The main missing features are doubles, subroutines, "precise", and arrays of arrays.)

Glslang also provides compile-time validation of these extensions:

Our goal is to provide coverage for new versions of the shading languages as they are released.

Glslang also detects many link-time error conditions for supported versions of GLSL and ESSL when the '-l' command-line option is provided. However, at this time we are only committing to providing complete compile-time validation.

Extensions

GLslang has support for many commonly used language extensions, and our intention is to support all Khronos-ratified (KHR, ARB, and OES) extensions eventually.

SPIR-V Support

GLSL SPIR-V support in glslang is experimental and non-optimized. Use the -V option to create SPIR-V in file stage.spv. Use the -H option to see a human readable form.

For more on SPIR-V and for providing feedback, see https://www.khronos.org/spir.

History and Contributions

LunarG took the glslang written by 3Dlabs for the original GLSL 1.1 and has rewritten it to a higher quality and to simultaneously support multiple versions and extensions.

Glslang is based on the grammar published in the GLSL specification, reflects a strict interpretation of the semantics in the specification, and is shaped from input of Khronos, multiple IHVs, and multiple ISVs.

For more information about LunarG, its projects, or getting involved, see http://lunarg.com/.

Copyright

The following modified BSD license is the copyright/license used in the source files.

//
//Copyright (C) 2002-2005 3Dlabs Inc. Ltd.
//Copyright (C) 2012-2013 LunarG, Inc.
//
//All rights reserved.
//
//Redistribution and use in source and binary forms, with or without
//modification, are permitted provided that the following conditions
//are met:
//
// Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following
// disclaimer in the documentation and/or other materials provided
// with the distribution.
//
// Neither the name of 3Dlabs Inc. Ltd. nor the names of its
// contributors may be used to endorse or promote products derived
// from this software without specific prior written permission.
//
//THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
//"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
//LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
//FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
//COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
//INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
//BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
//LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
//CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
//LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
//ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
//POSSIBILITY OF SUCH DAMAGE.
//