README.md

glslang
=======

An OpenGL and OpenGL ES shader front end and validator.

There are two components:

1. A front-end library for programmatic parsing of GLSL/ESSL into an AST.

2. A standalone wrapper, `glslangValidator`, that can be used as a shader
   validation tool.

How to add a feature protected by a version/extension/stage/profile:  See the
comment in `glslang/MachineIndependent/Versions.cpp`.

Things left to do:  See `Todo.txt`

Execution of Standalone Wrapper
-------------------------------

There are binaries in the `Install/Windows` and `Install/Linux` directories.

To use the standalone binary form, execute `glslangValidator`, and it will print
a usage statement.  Basic operation is to give it a file containing a shader,
and it will print out warnings/errors and optionally an AST.

The applied stage-specific rules are based on the file extension:
* `.vert` for a vertex shader
* `.tesc` for a tessellation control shader
* `.tese` for a tessellation evaluation shader
* `.geom` for a geometry shader
* `.frag` for a fragment shader
* `.comp` for a compute shader

There is also a non-shader extension
* `.conf` for a configuration file of limits, see usage statement for example

Source: Build and run on Linux
-------------------------------

A simple bash script `BuildLinux.sh` is provided at the root directory
to do the build and run a test cases.  You will need a recent version of
bison installed.

Once the executable is generated, it needs to be dynamically linked with the
shared object created in `lib` directory. To achieve that, `cd` to
`StandAlone` directory to update the `LD_LIBRARY_PATH` as follows

```bash
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./../glslang/MachineIndependent/lib
```

You can also update `LD_LIBRARY_PATH` in the `.cshrc` or `.bashrc` file,
depending on the shell you are using. You will need to give the complete path
of `lib` directory in `.cshrc` or `.bashrc` files.

Source: Build and run on Windows
--------------------------------

Current development is with Visual Studio verion 11 (2012).  The solution
file is in the project's root directory `Standalone.sln`.

Building the StandAlone project (the default) will create `glslangValidate.exe`
and copy it into the `Test` directory and `Install` directory.  This allows
local test scripts to use either the debug or release version, whichever was
built last.

Windows execution and testing is generally done from within a cygwin
shell.

Note: Despite appearances, the use of a DLL is currently disabled; it
simply makes a standalone executable from a statically linked library.

Programmatic Interfaces
-----------------------

Another piece of software can programmatically translate shaders to an AST
using one of two different interfaces:
* A new C++ class-oriented interface, or
* The original C functional interface

The `main()` in `StandAlone/StandAlone.cpp` shows examples using both styles.

### C++ Class Interface (new, preferred)

This interface is in roughly the last 1/3 of `ShaderLang.h`.  It is in the
glslang namespace and contains the following.

```cxx
const char* GetEsslVersionString();
const char* GetGlslVersionString();
bool InitializeProcess();
void FinalizeProcess();

class TShader
    bool parse(...);
    void setStrings(...);
    const char* getInfoLog();

class TProgram
    void addShader(...);
    bool link(...);
    const char* getInfoLog();
    Reflection queries
```

See `ShaderLang.h` and the usage of it in `StandAlone/StandAlone.cpp` for more
details.

### C Functional Interface (orginal)

This interface is in roughly the first 2/3 of `ShaderLang.h`, and referred to
as the `Sh*()` interface, as all the entry points start `Sh`.

The `Sh*()` interface takes a "compiler" call-back object, which it calls after
building call back that is passed the AST and can then execute a backend on it.

The following is a simplified resulting run-time call stack:

```c
ShCompile(shader, compiler) -> compiler(AST) -> <back end>
```

In practice, `ShCompile()` takes shader strings, default version, and
warning/error and other options for controling compilation.

Testing
-------

`Test` is an active test directory that contains test input and a
subdirectory `baseResults` that contains the expected results of the
tests.  Both the tests and `baseResults` are under source-code control.
Executing the script `./runtests` will generate current results in
the `localResults` directory and `diff` them against the `baseResults`.
When you want to update the tracked test results, they need to be
copied from `localResults` to `baseResults`.

There are some tests borrowed from LunarGLASS.  If LunarGLASS is
missing, those tests just won't run.

Basic Internal Operation
------------------------

* Initial lexical analysis is done by the preprocessor in
  `MachineIndependent/Preprocessor`, and then refined by a GLSL scanner
  in `MachineIndependent/Scan.cpp`.  There is currently no use of flex.

* Code is parsed using bison on `MachineIndependent/glslang.y` with the
  aid of a symbol table and an AST.  The symbol table is not passed on to
  the back-end; the intermediate representation stands on its own.
  The tree is built by the grammar productions, many of which are
  offloaded into `ParseHelper.cpp`, and by `Intermediate.cpp`.

* The intermediate representation is very high-level, and represented
  as an in-memory tree.   This serves to lose no information from the
  original program, and to have efficient transfer of the result from
  parsing to the back-end.  In the AST, constants are propogated and
  folded, and a very small amount of dead code is eliminated.

  To aid linking and reflection, the last top-level branch in the AST
  lists all global symbols.

* The primary algorithm of the back-end compiler is to traverse the
  tree (high-level intermediate representation), and create an internal
  object code representation.  There is an example of how to do this
  in `MachineIndependent/intermOut.cpp`.

* Reduction of the tree to a linear byte-code style low-level intermediate
  representation is likely a good way to generate fully optimized code.

* There is currently some dead old-style linker-type code still lying around.

* Memory pool: parsing uses types derived from C++ `std` types, using a
  custom allocator that puts them in a memory pool.  This makes allocation
  of individual container/contents just few cycles and deallocation free.
  This pool is popped after the AST is made and processed.

  The use is simple: if you are going to call `new`, there are three cases:

  - the object comes from the pool (its base class has the macro
    `POOL_ALLOCATOR_NEW_DELETE` in it) and you do not have to call `delete`

  - it is a `TString`, in which case call `NewPoolTString()`, which gets
    it from the pool, and there is no corresponding `delete`

  - the object does not come from the pool, and you have to do normal
    C++ memory management of what you `new`