-Also see the Khronos landing page for glslang as a reference front end:
+# News
-https://www.khronos.org/opengles/sdk/tools/Reference-Compiler/
+1. [As discussed in #3107](https://github.com/KhronosGroup/glslang/issues/3107), the default branch of this repository is now 'main'. This change should be transparent to repository users, since github rewrites many references to the old 'master' branch to 'main'. However, if you have a checked-out local clone, you may wish to take the following steps as recommended by github:
-The above page includes where to get binaries, and is kept up to date
-regarding the feature level of glslang.
+```sh
+git branch -m master main
+git fetch origin
+git branch -u origin/main main
+git remote set-head origin -a
+```
-glslang
-=======
+2. C++17 (all platforms) and Visual Studio 2019 (Windows) are now required. This change was driven by the external dependency on SPIRV-Tools.
-[](https://travis-ci.org/KhronosGroup/glslang)
-[](https://ci.appveyor.com/project/Khronoswebmaster/glslang/branch/master)
+
+
+[](https://securityscorecards.dev/viewer/?uri=github.com/KhronosGroup/glslang)
-An OpenGL and OpenGL ES shader front end and validator.
+# Glslang Components and Status
There are several components:
-1. A GLSL/ESSL front-end for reference validation and translation of GLSL/ESSL into an AST.
+### Reference Validator and GLSL/ESSL -> AST Front End
+
+An OpenGL GLSL and OpenGL|ES GLSL (ESSL) front-end for reference validation and translation of GLSL/ESSL into an internal abstract syntax tree (AST).
+
+**Status**: Virtually complete, with results carrying similar weight as the specifications.
+
+### HLSL -> AST Front End
+
+An HLSL front-end for translation of an approximation of HLSL to glslang's AST form.
+
+**Status**: Partially complete. Semantics are not reference quality and input is not validated.
+This is in contrast to the [DXC project](https://github.com/Microsoft/DirectXShaderCompiler), which receives a much larger investment and attempts to have definitive/reference-level semantics.
+
+See [issue 362](https://github.com/KhronosGroup/glslang/issues/362) and [issue 701](https://github.com/KhronosGroup/glslang/issues/701) for current status.
+
+### AST -> SPIR-V Back End
+
+Translates glslang's AST to the Khronos-specified SPIR-V intermediate language.
+
+**Status**: Virtually complete.
-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.
+### Reflector
-3. A SPIR-V back end for translating the AST to SPIR-V.
+An API for getting reflection information from the AST, reflection types/variables/etc. from the HLL source (not the SPIR-V).
-4. A standalone wrapper, `glslangValidator`, that can be used as a command-line tool for the above.
+**Status**: There is a large amount of functionality present, but no specification/goal to measure completeness against. It is accurate for the input HLL and AST, but only approximate for what would later be emitted for SPIR-V.
-How to add a feature protected by a version/extension/stage/profile: See the
-comment in `glslang/MachineIndependent/Versions.cpp`.
+### Standalone Wrapper
+
+`glslang` is command-line tool for accessing the functionality above.
+
+Status: Complete.
Tasks waiting to be done are documented as GitHub issues.
-Deprecations
-------------
+## Other References
+
+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, while not kept up to date, includes additional information regarding glslang as a reference validator.
-1. GLSLang, when installed through CMake, will install a `SPIRV` folder into
-`${CMAKE_INSTALL_INCLUDEDIR}`. This `SPIRV` folder is being moved to
-`glslang/SPIRV`. During the transition the `SPIRV` folder will be installed into
-both locations. The old install of `SPIRV/` will be removed as a CMake install
-target no sooner than May 1, 2020. See issue #1964.
+# How to Use Glslang
-Execution of Standalone Wrapper
--------------------------------
+## Execution of Standalone Wrapper
-To use the standalone binary form, execute `glslangValidator`, and it will print
+To use the standalone binary form, execute `glslang`, 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.
* `.frag` for a fragment shader
* `.comp` for a compute shader
-There is also a non-shader extension
+For ray tracing pipeline shaders:
+* `.rgen` for a ray generation shader
+* `.rint` for a ray intersection shader
+* `.rahit` for a ray any-hit shader
+* `.rchit` for a ray closest-hit shader
+* `.rmiss` for a ray miss shader
+* `.rcall` for a callable shader
+
+There is also a non-shader extension:
* `.conf` for a configuration file of limits, see usage statement for example
-Building
---------
+## Building (CMake)
Instead of building manually, you can also download the binaries for your
-platform directly from the [master-tot release][master-tot-release] on GitHub.
+platform directly from the [main-tot release][main-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
+testing and they always reflect the current top of the tree of the main
branch.
### Dependencies
-* A C++11 compiler.
- (For MSVS: 2015 is recommended, 2013 is fully supported/tested, and 2010 support is attempted, but not tested.)
+* A C++17 compiler.
+ (For MSVS: use 2019 or later.)
* [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.)
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
+#### 1) Check-Out this project
```bash
cd <parent of where you want glslang to be>
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:
+TEMPORARY NOTICE: additionally perform the following to avoid a current
+breakage in googletest:
```bash
-# to use googletest with Visual Studio 2013
cd External/googletest
-git checkout 440527a61e1c91188195f7de212c63c77e8f0a45
+git checkout 0c400f67fcf305869c5fb113dd296eca266c9725
cd ../..
```
# "Release" (for CMAKE_BUILD_TYPE) could also be "Debug" or "RelWithDebInfo"
```
+For building on Android:
+```bash
+cmake $SOURCE_DIR -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX="$(pwd)/install" -DANDROID_ABI=arm64-v8a -DCMAKE_BUILD_TYPE=Release -DANDROID_STL=c++_static -DANDROID_PLATFORM=android-24 -DCMAKE_SYSTEM_NAME=Android -DANDROID_TOOLCHAIN=clang -DANDROID_ARM_MODE=arm -DCMAKE_MAKE_PROGRAM=$ANDROID_NDK_HOME/prebuilt/linux-x86_64/bin/make -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
+# If on Windows will be -DCMAKE_MAKE_PROGRAM=%ANDROID_NDK_HOME%\prebuilt\windows-x86_64\bin\make.exe
+# -G is needed for building on Windows
+# -DANDROID_ABI can also be armeabi-v7a for 32 bit
+```
+
For building on Windows:
```bash
If using MSVC, after running CMake to configure, use the
Configuration Manager to check the `INSTALL` project.
+### Building (GN)
+
+glslang can also be built with the [GN build system](https://gn.googlesource.com/gn/).
+
+#### 1) Install `depot_tools`
+
+Download [depot_tools.zip](https://storage.googleapis.com/chrome-infra/depot_tools.zip),
+extract to a directory, and add this directory to your `PATH`.
+
+#### 2) Synchronize dependencies and generate build files
+
+This only needs to be done once after updating `glslang`.
+
+With the current directory set to your `glslang` checkout, type:
+
+```bash
+./update_glslang_sources.py
+gclient sync --gclientfile=standalone.gclient
+gn gen out/Default
+```
+
+#### 3) Build
+
+With the current directory set to your `glslang` checkout, type:
+
+```bash
+cd out/Default
+ninja
+```
+
### If you need to change the GLSL grammar
The grammar in `glslang/MachineIndependent/glslang.y` has to be recompiled with
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`,
+The above command is 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
+### Building a standalone JS/WASM library 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_JS=ON`
- + optionally, for a minimum-size binary, turn on `-DENABLE_GLSLANG_WEBMIN=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 environments
- + [Instructions located
- here](https://emscripten.org/docs/getting_started/downloads.html#sdk-download-and-install)
+ Bash-like environments:
+ + [Instructions located here](https://emscripten.org/docs/getting_started/downloads.html#sdk-download-and-install)
* Wrap cmake call: `emcmake cmake`
+* Set `-DBUILD_TESTING=OFF -DENABLE_OPT=OFF`.
+* Set `-DENABLE_HLSL=OFF` if HLSL is not needed.
+* For a standalone JS/WASM library, turn on `-DENABLE_GLSLANG_JS=ON`.
* 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 ..
+emcmake cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_GLSLANG_JS=ON \
+ -DENABLE_HLSL=OFF -DBUILD_TESTING=OFF -DENABLE_OPT=OFF ..
```
-Testing
--------
+## Building glslang - Using vcpkg
+
+You can download and install glslang using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
+
+ git clone https://github.com/Microsoft/vcpkg.git
+ cd vcpkg
+ ./bootstrap-vcpkg.sh
+ ./vcpkg integrate install
+ ./vcpkg install glslang
+
+The glslang port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
+
+## 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
`localtestlist` to list non-tracked tests. This is automatically read
by `runtests` and included in the `diff` and `bump` process.
-Programmatic Interfaces
------------------------
+## Programmatic Interfaces
Another piece of software can programmatically translate shaders to an AST
using one of two different interfaces:
In practice, `ShCompile()` takes shader strings, default version, and
warning/error and other options for controlling compilation.
-Basic Internal Operation
-------------------------
+### C Functional Interface (new)
+
+This interface is located `glslang_c_interface.h` and exposes functionality similar to the C++ interface. The following snippet is a complete example showing how to compile GLSL into SPIR-V 1.5 for Vulkan 1.2.
+
+```c
+#include <glslang/Include/glslang_c_interface.h>
+
+// Required for use of glslang_default_resource
+#include <glslang/Public/resource_limits_c.h>
+
+typedef struct SpirVBinary {
+ uint32_t *words; // SPIR-V words
+ int size; // number of words in SPIR-V binary
+} SpirVBinary;
+
+SpirVBinary compileShaderToSPIRV_Vulkan(glslang_stage_t stage, const char* shaderSource, const char* fileName) {
+ const glslang_input_t input = {
+ .language = GLSLANG_SOURCE_GLSL,
+ .stage = stage,
+ .client = GLSLANG_CLIENT_VULKAN,
+ .client_version = GLSLANG_TARGET_VULKAN_1_2,
+ .target_language = GLSLANG_TARGET_SPV,
+ .target_language_version = GLSLANG_TARGET_SPV_1_5,
+ .code = shaderSource,
+ .default_version = 100,
+ .default_profile = GLSLANG_NO_PROFILE,
+ .force_default_version_and_profile = false,
+ .forward_compatible = false,
+ .messages = GLSLANG_MSG_DEFAULT_BIT,
+ .resource = glslang_default_resource(),
+ };
+
+ glslang_shader_t* shader = glslang_shader_create(&input);
+
+ SpirVBinary bin = {
+ .words = NULL,
+ .size = 0,
+ };
+ if (!glslang_shader_preprocess(shader, &input)) {
+ printf("GLSL preprocessing failed %s\n", fileName);
+ printf("%s\n", glslang_shader_get_info_log(shader));
+ printf("%s\n", glslang_shader_get_info_debug_log(shader));
+ printf("%s\n", input.code);
+ glslang_shader_delete(shader);
+ return bin;
+ }
+
+ if (!glslang_shader_parse(shader, &input)) {
+ printf("GLSL parsing failed %s\n", fileName);
+ printf("%s\n", glslang_shader_get_info_log(shader));
+ printf("%s\n", glslang_shader_get_info_debug_log(shader));
+ printf("%s\n", glslang_shader_get_preprocessed_code(shader));
+ glslang_shader_delete(shader);
+ return bin;
+ }
+
+ glslang_program_t* program = glslang_program_create();
+ glslang_program_add_shader(program, shader);
+
+ if (!glslang_program_link(program, GLSLANG_MSG_SPV_RULES_BIT | GLSLANG_MSG_VULKAN_RULES_BIT)) {
+ printf("GLSL linking failed %s\n", fileName);
+ printf("%s\n", glslang_program_get_info_log(program));
+ printf("%s\n", glslang_program_get_info_debug_log(program));
+ glslang_program_delete(program);
+ glslang_shader_delete(shader);
+ return bin;
+ }
+
+ glslang_program_SPIRV_generate(program, stage);
+
+ bin.size = glslang_program_SPIRV_get_size(program);
+ bin.words = malloc(bin.size * sizeof(uint32_t));
+ glslang_program_SPIRV_get(program, bin.words);
+
+ const char* spirv_messages = glslang_program_SPIRV_get_messages(program);
+ if (spirv_messages)
+ printf("(%s) %s\b", fileName, spirv_messages);
+
+ glslang_program_delete(program);
+ glslang_shader_delete(shader);
+
+ return bin;
+}
+```
+
+## Basic Internal Operation
* Initial lexical analysis is done by the preprocessor in
`MachineIndependent/Preprocessor`, and then refined by a GLSL scanner
- the object does not come from the pool, and you have to do normal
C++ memory management of what you `new`
+* Features can be protected by version/extension/stage/profile:
+ See the comment in `glslang/MachineIndependent/Versions.cpp`.
[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
+[main-tot-release]: https://github.com/KhronosGroup/glslang/releases/tag/main-tot
projects / platform / upstream / glslang.git / blobdiff