summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/bgfx/3rdparty/glslang/README.md
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/bgfx/3rdparty/glslang/README.md')
-rw-r--r--3rdparty/bgfx/3rdparty/glslang/README.md381
1 files changed, 0 insertions, 381 deletions
diff --git a/3rdparty/bgfx/3rdparty/glslang/README.md b/3rdparty/bgfx/3rdparty/glslang/README.md
deleted file mode 100644
index f5651e1d4bd..00000000000
--- a/3rdparty/bgfx/3rdparty/glslang/README.md
+++ /dev/null
@@ -1,381 +0,0 @@
-Also see the Khronos landing page for glslang as a reference front end:
-
-https://www.khronos.org/opengles/sdk/tools/Reference-Compiler/
-
-The above page includes where to get binaries, and is kept up to date
-regarding the feature level of glslang.
-
-glslang
-=======
-
-[![Build Status](https://travis-ci.org/KhronosGroup/glslang.svg?branch=master)](https://travis-ci.org/KhronosGroup/glslang)
-[![Build status](https://ci.appveyor.com/api/projects/status/q6fi9cb0qnhkla68/branch/master?svg=true)](https://ci.appveyor.com/project/Khronoswebmaster/glslang/branch/master)
-
-An OpenGL and OpenGL ES shader front end and validator.
-
-There are several components:
-
-1. A GLSL/ESSL front-end for reference validation and translation of GLSL/ESSL into an AST.
-
-2. An HLSL front-end for translation of a broad generic HLL into the AST. See [issue 362](https://github.com/KhronosGroup/glslang/issues/362) and [issue 701](https://github.com/KhronosGroup/glslang/issues/701) for current status.
-
-3. A SPIR-V back end for translating the AST to SPIR-V.
-
-4. A standalone wrapper, `glslangValidator`, that can be used as a command-line tool for the above.
-
-How to add a feature protected by a version/extension/stage/profile: See the
-comment in `glslang/MachineIndependent/Versions.cpp`.
-
-Tasks waiting to be done are documented as GitHub issues.
-
-Execution of Standalone Wrapper
--------------------------------
-
-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
-
-Building
---------
-
-Instead of building manually, you can also download the binaries for your
-platform directly from the [master-tot release][master-tot-release] on GitHub.
-Those binaries are automatically uploaded by the buildbots after successful
-testing and they always reflect the current top of the tree of the master
-branch.
-
-### Dependencies
-
-* A C++11 compiler.
- (For MSVS: 2015 is recommended, 2013 is fully supported/tested, and 2010 support is attempted, but not tested.)
-* [CMake][cmake]: for generating compilation targets.
-* make: _Linux_, ninja is an alternative, if configured.
-* [Python 3.x][python]: for executing SPIRV-Tools scripts. (Optional if not using SPIRV-Tools and the 'External' subdirectory does not exist.)
-* [bison][bison]: _optional_, but needed when changing the grammar (glslang.y).
-* [googletest][googletest]: _optional_, but should use if making any changes to glslang.
-
-### Build steps
-
-The following steps assume a Bash shell. On Windows, that could be the Git Bash
-shell or some other shell of your choosing.
-
-#### 1) Check-Out this project
-
-```bash
-cd <parent of where you want glslang to be>
-git clone https://github.com/KhronosGroup/glslang.git
-```
-
-#### 2) Check-Out External Projects
-
-```bash
-cd <the directory glslang was cloned to, "External" will be a subdirectory>
-git clone https://github.com/google/googletest.git External/googletest
-```
-
-If you want to use googletest with Visual Studio 2013, you also need to check out an older version:
-
-```bash
-# to use googletest with Visual Studio 2013
-cd External/googletest
-git checkout 440527a61e1c91188195f7de212c63c77e8f0a45
-cd ../..
-```
-
-If you wish to assure that SPIR-V generated from HLSL is legal for Vulkan,
-or wish to invoke -Os to reduce SPIR-V size from HLSL or GLSL, install
-spirv-tools with this:
-
-```bash
-./update_glslang_sources.py
-```
-
-#### 3) Configure
-
-Assume the source directory is `$SOURCE_DIR` and the build directory is
-`$BUILD_DIR`. First ensure the build directory exists, then navigate to it:
-
-```bash
-mkdir -p $BUILD_DIR
-cd $BUILD_DIR
-```
-
-For building on Linux:
-
-```bash
-cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$(pwd)/install" $SOURCE_DIR
-# "Release" (for CMAKE_BUILD_TYPE) could also be "Debug" or "RelWithDebInfo"
-```
-
-For building on Windows:
-
-```bash
-cmake $SOURCE_DIR -DCMAKE_INSTALL_PREFIX="$(pwd)/install"
-# The CMAKE_INSTALL_PREFIX part is for testing (explained later).
-```
-
-The CMake GUI also works for Windows (version 3.4.1 tested).
-
-Also, consider using `git config --global core.fileMode false` (or with `--local`) on Windows
-to prevent the addition of execution permission on files.
-
-#### 4) Build and Install
-
-```bash
-# for Linux:
-make -j4 install
-
-# for Windows:
-cmake --build . --config Release --target install
-# "Release" (for --config) could also be "Debug", "MinSizeRel", or "RelWithDebInfo"
-```
-
-If using MSVC, after running CMake to configure, use the
-Configuration Manager to check the `INSTALL` project.
-
-### If you need to change the GLSL grammar
-
-The grammar in `glslang/MachineIndependent/glslang.y` has to be recompiled with
-bison if it changes, the output files are committed to the repo to avoid every
-developer needing to have bison configured to compile the project when grammar
-changes are quite infrequent. For windows you can get binaries from
-[GnuWin32][bison-gnu-win32].
-
-The command to rebuild is:
-
-```bash
-m4 -P MachineIndependent/glslang.m4 > MachineIndependent/glslang.y
-bison --defines=MachineIndependent/glslang_tab.cpp.h
- -t MachineIndependent/glslang.y
- -o MachineIndependent/glslang_tab.cpp
-```
-
-The above commands are also available in the bash script in `updateGrammar`,
-when executed from the glslang subdirectory of the glslang repository.
-With no arguments it builds the full grammar, and with a "web" argument,
-the web grammar subset (see more about the web subset in the next section).
-
-### Building to WASM for the Web and Node
-
-Use the steps in [Build Steps](#build-steps), with the following notes/exceptions:
-* For building the web subset of core glslang:
- + execute `updateGrammar web` from the glslang subdirectory
- (or if using your own scripts, `m4` needs a `-DGLSLANG_WEB` argument)
- + set `-DENABLE_HLSL=OFF -DBUILD_TESTING=OFF -DENABLE_OPT=OFF -DINSTALL_GTEST=OFF`
- + turn on `-DENABLE_GLSLANG_WEB=ON`
- + optionally, for GLSL compilation error messages, turn on `-DENABLE_GLSLANG_WEB_DEVEL=ON`
-* `emsdk` needs to be present in your executable search path, *PATH* for
- Bash-like enivironments
- + [Instructions located
- here](https://emscripten.org/docs/getting_started/downloads.html#sdk-download-and-install)
-* Wrap cmake call: `emcmake cmake`
-* To get a fully minimized build, make sure to use `brotli` to compress the .js
- and .wasm files
-
-Example:
-
-```sh
-emcmake cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_GLSLANG_WEB=ON \
- -DENABLE_HLSL=OFF -DBUILD_TESTING=OFF -DENABLE_OPT=OFF -DINSTALL_GTEST=OFF ..
-```
-
-Testing
--------
-
-Right now, there are two test harnesses existing in glslang: one is [Google
-Test](gtests/), one is the [`runtests` script](Test/runtests). The former
-runs unit tests and single-shader single-threaded integration tests, while
-the latter runs multiple-shader linking tests and multi-threaded tests.
-
-### Running tests
-
-The [`runtests` script](Test/runtests) requires compiled binaries to be
-installed into `$BUILD_DIR/install`. Please make sure you have supplied the
-correct configuration to CMake (using `-DCMAKE_INSTALL_PREFIX`) when building;
-otherwise, you may want to modify the path in the `runtests` script.
-
-Running Google Test-backed tests:
-
-```bash
-cd $BUILD_DIR
-
-# for Linux:
-ctest
-
-# for Windows:
-ctest -C {Debug|Release|RelWithDebInfo|MinSizeRel}
-
-# or, run the test binary directly
-# (which gives more fine-grained control like filtering):
-<dir-to-glslangtests-in-build-dir>/glslangtests
-```
-
-Running `runtests` script-backed tests:
-
-```bash
-cd $SOURCE_DIR/Test && ./runtests
-```
-
-### Contributing tests
-
-Test results should always be included with a pull request that modifies
-functionality.
-
-If you are writing unit tests, please use the Google Test framework and
-place the tests under the `gtests/` directory.
-
-Integration tests are placed in the `Test/` directory. It 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.
-
-Google Test runs those integration tests by reading the test input, compiling
-them, and then compare against the expected results in `baseResults/`. The
-integration tests to run via Google Test is registered in various
-`gtests/*.FromFile.cpp` source files. `glslangtests` provides a command-line
-option `--update-mode`, which, if supplied, will overwrite the golden files
-under the `baseResults/` directory with real output from that invocation.
-For more information, please check `gtests/` directory's
-[README](gtests/README.md).
-
-For the `runtests` script, it 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/`. This can be done by
-the `bump` shell script.
-
-You can add your own private list of tests, not tracked publicly, by using
-`localtestlist` to list non-tracked tests. This is automatically read
-by `runtests` and included in the `diff` and `bump` process.
-
-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, here with suggested calls
-for generating SPIR-V:
-
-```cxx
-const char* GetEsslVersionString();
-const char* GetGlslVersionString();
-bool InitializeProcess();
-void FinalizeProcess();
-
-class TShader
- setStrings(...);
- setEnvInput(EShSourceHlsl or EShSourceGlsl, stage, EShClientVulkan or EShClientOpenGL, 100);
- setEnvClient(EShClientVulkan or EShClientOpenGL, EShTargetVulkan_1_0 or EShTargetVulkan_1_1 or EShTargetOpenGL_450);
- setEnvTarget(EShTargetSpv, EShTargetSpv_1_0 or EShTargetSpv_1_3);
- bool parse(...);
- const char* getInfoLog();
-
-class TProgram
- void addShader(...);
- bool link(...);
- const char* getInfoLog();
- Reflection queries
-```
-
-For just validating (not generating code), subsitute these calls:
-
-```cxx
- setEnvInput(EShSourceHlsl or EShSourceGlsl, stage, EShClientNone, 0);
- setEnvClient(EShClientNone, 0);
- setEnvTarget(EShTargetNone, 0);
-```
-
-See `ShaderLang.h` and the usage of it in `StandAlone/StandAlone.cpp` for more
-details. There is a block comment giving more detail above the calls for
-`setEnvInput, setEnvClient, and setEnvTarget`.
-
-### C Functional Interface (original)
-
-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 controlling compilation.
-
-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`
-
-
-[cmake]: https://cmake.org/
-[python]: https://www.python.org/
-[bison]: https://www.gnu.org/software/bison/
-[googletest]: https://github.com/google/googletest
-[bison-gnu-win32]: http://gnuwin32.sourceforge.net/packages/bison.htm
-[master-tot-release]: https://github.com/KhronosGroup/glslang/releases/tag/master-tot