mirror of
https://github.com/KhronosGroup/glslang
synced 2024-11-08 11:30:06 +00:00
Format README using markdown.
This commit is contained in:
Lei Zhang
parent
140f3df134
commit
65299b9ef0
187
README.md
Normal file
187
README.md
Normal file
@ -0,0 +1,187 @@
|
||||
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`
|
||||
178
README.txt
178
README.txt
@ -1,178 +0,0 @@
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
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'
|
||||
Loading…
Reference in New Issue
Block a user