README.md

   1 Also see the Khronos landing page for glslang as a reference front end:
   2
   3 https://www.khronos.org/opengles/sdk/tools/Reference-Compiler/
   4
   5 The above page includes where to get binaries, and is kept up to date
   6 regarding the feature level of glslang.
   7
   8 glslang
   9 =======
  10
  11 An OpenGL and OpenGL ES shader front end and validator.
  12
  13 There are two components:
  14
  15 1. A front-end library for programmatic parsing of GLSL/ESSL into an AST.
  16
  17 2. A standalone wrapper, `glslangValidator`, that can be used as a shader
  18    validation tool.
  19
  20 How to add a feature protected by a version/extension/stage/profile:  See the
  21 comment in `glslang/MachineIndependent/Versions.cpp`.
  22
  23 Things left to do:  See `Todo.txt`
  24
  25 Execution of Standalone Wrapper
  26 -------------------------------
  27
  28 There are binaries in the `Install/Windows` and `Install/Linux` directories.
  29
  30 To use the standalone binary form, execute `glslangValidator`, and it will print
  31 a usage statement.  Basic operation is to give it a file containing a shader,
  32 and it will print out warnings/errors and optionally an AST.
  33
  34 The applied stage-specific rules are based on the file extension:
  35 * `.vert` for a vertex shader
  36 * `.tesc` for a tessellation control shader
  37 * `.tese` for a tessellation evaluation shader
  38 * `.geom` for a geometry shader
  39 * `.frag` for a fragment shader
  40 * `.comp` for a compute shader
  41
  42 There is also a non-shader extension
  43 * `.conf` for a configuration file of limits, see usage statement for example
  44
  45 Building
  46 --------
  47
  48 CMake: The currently maintained and preferred way of building is through CMake.
  49 In MSVC, after running CMake, you may need to use the Configuration Manager to
  50 check the INSTALL project.
  51
  52 Note there are some legacy build methods still intermingled within the directory
  53 structure (make, MSVC), but these are no longer maintained, having been
  54 replaced with CMake.
  55
  56 Programmatic Interfaces
  57 -----------------------
  58
  59 Another piece of software can programmatically translate shaders to an AST
  60 using one of two different interfaces:
  61 * A new C++ class-oriented interface, or
  62 * The original C functional interface
  63
  64 The `main()` in `StandAlone/StandAlone.cpp` shows examples using both styles.
  65
  66 ### C++ Class Interface (new, preferred)
  67
  68 This interface is in roughly the last 1/3 of `ShaderLang.h`.  It is in the
  69 glslang namespace and contains the following.
  70
  71 ```cxx
  72 const char* GetEsslVersionString();
  73 const char* GetGlslVersionString();
  74 bool InitializeProcess();
  75 void FinalizeProcess();
  76
  77 class TShader
  78     bool parse(...);
  79     void setStrings(...);
  80     const char* getInfoLog();
  81
  82 class TProgram
  83     void addShader(...);
  84     bool link(...);
  85     const char* getInfoLog();
  86     Reflection queries
  87 ```
  88
  89 See `ShaderLang.h` and the usage of it in `StandAlone/StandAlone.cpp` for more
  90 details.
  91
  92 ### C Functional Interface (orginal)
  93
  94 This interface is in roughly the first 2/3 of `ShaderLang.h`, and referred to
  95 as the `Sh*()` interface, as all the entry points start `Sh`.
  96
  97 The `Sh*()` interface takes a "compiler" call-back object, which it calls after
  98 building call back that is passed the AST and can then execute a backend on it.
  99
 100 The following is a simplified resulting run-time call stack:
 101
 102 ```c
 103 ShCompile(shader, compiler) -> compiler(AST) -> <back end>
 104 ```
 105
 106 In practice, `ShCompile()` takes shader strings, default version, and
 107 warning/error and other options for controling compilation.
 108
 109 Testing
 110 -------
 111
 112 `Test` is an active test directory that contains test input and a
 113 subdirectory `baseResults` that contains the expected results of the
 114 tests.  Both the tests and `baseResults` are under source-code control.
 115 Executing the script `./runtests` will generate current results in
 116 the `localResults` directory and `diff` them against the `baseResults`.
 117 When you want to update the tracked test results, they need to be
 118 copied from `localResults` to `baseResults`.
 119
 120 There are some tests borrowed from LunarGLASS.  If LunarGLASS is
 121 missing, those tests just won't run.
 122
 123 Basic Internal Operation
 124 ------------------------
 125
 126 * Initial lexical analysis is done by the preprocessor in
 127   `MachineIndependent/Preprocessor`, and then refined by a GLSL scanner
 128   in `MachineIndependent/Scan.cpp`.  There is currently no use of flex.
 129
 130 * Code is parsed using bison on `MachineIndependent/glslang.y` with the
 131   aid of a symbol table and an AST.  The symbol table is not passed on to
 132   the back-end; the intermediate representation stands on its own.
 133   The tree is built by the grammar productions, many of which are
 134   offloaded into `ParseHelper.cpp`, and by `Intermediate.cpp`.
 135
 136 * The intermediate representation is very high-level, and represented
 137   as an in-memory tree.   This serves to lose no information from the
 138   original program, and to have efficient transfer of the result from
 139   parsing to the back-end.  In the AST, constants are propogated and
 140   folded, and a very small amount of dead code is eliminated.
 141
 142   To aid linking and reflection, the last top-level branch in the AST
 143   lists all global symbols.
 144
 145 * The primary algorithm of the back-end compiler is to traverse the
 146   tree (high-level intermediate representation), and create an internal
 147   object code representation.  There is an example of how to do this
 148   in `MachineIndependent/intermOut.cpp`.
 149
 150 * Reduction of the tree to a linear byte-code style low-level intermediate
 151   representation is likely a good way to generate fully optimized code.
 152
 153 * There is currently some dead old-style linker-type code still lying around.
 154
 155 * Memory pool: parsing uses types derived from C++ `std` types, using a
 156   custom allocator that puts them in a memory pool.  This makes allocation
 157   of individual container/contents just few cycles and deallocation free.
 158   This pool is popped after the AST is made and processed.
 159
 160   The use is simple: if you are going to call `new`, there are three cases:
 161
 162   - the object comes from the pool (its base class has the macro
 163     `POOL_ALLOCATOR_NEW_DELETE` in it) and you do not have to call `delete`
 164
 165   - it is a `TString`, in which case call `NewPoolTString()`, which gets
 166     it from the pool, and there is no corresponding `delete`
 167
 168   - the object does not come from the pool, and you have to do normal
 169     C++ memory management of what you `new`