First Commit
This commit is contained in:
244
3rdparty/shaderc/README.md
vendored
Normal file
244
3rdparty/shaderc/README.md
vendored
Normal file
@@ -0,0 +1,244 @@
|
||||
# Shaderc
|
||||
|
||||
A collection of tools, libraries and tests for shader compilation.
|
||||
At the moment it includes:
|
||||
|
||||
- [`glslc`](glslc), a command line compiler for GLSL/HLSL to SPIR-V, and
|
||||
- [`libshaderc`](libshaderc), a library API for accessing `glslc` functionality.
|
||||
|
||||
**Note:** The fact that that `libshaderc` is not named `libshaderc_glslc` is a
|
||||
quirk of history, and a known inconsistency. Changing it would require a
|
||||
significant amount of renaming and breaking of downstream projects, so it is
|
||||
being left as is.
|
||||
|
||||
`glslc` wraps around core functionality in [glslang][khr-glslang]
|
||||
and [SPIRV-Tools][spirv-tools]. `glslc` and its library aims to
|
||||
to provide:
|
||||
* a command line compiler with GCC- and Clang-like usage, for better
|
||||
integration with build systems
|
||||
* an API where functionality can be added without breaking existing clients
|
||||
* an API supporting standard concurrency patterns across multiple
|
||||
operating systems
|
||||
* increased functionality such as file `#include` support
|
||||
|
||||
## Downloads
|
||||
|
||||
**Note: These binaries are just the artifacts of the builders and have not
|
||||
undergone any QA, thus they should be considered unsupported.**
|
||||
|
||||
<img alt="Linux" src="kokoro/img/linux.png" width="20px" height="20px" hspace="2px"/>[](https://storage.googleapis.com/shaderc/badges/build_link_linux_clang_release.html)
|
||||
<img alt="MacOS" src="kokoro/img/macos.png" width="20px" height="20px" hspace="2px"/>[](https://storage.googleapis.com/shaderc/badges/build_link_macos_clang_release.html)
|
||||
<img alt="Windows" src="kokoro/img/windows.png" width="20px" height="20px" hspace="2px"/>[](https://storage.googleapis.com/shaderc/badges/build_link_windows_vs2017_release.html)
|
||||
|
||||
[More downloads](downloads.md)
|
||||
|
||||
## Status
|
||||
|
||||
Shaderc has maintained backward compatibility for quite some time, and we
|
||||
don't anticipate any breaking changes.
|
||||
Ongoing enhancements are described in the [CHANGES](CHANGES) file.
|
||||
|
||||
Shaderc has been shipping in the
|
||||
[Android NDK](https://developer.android.com/ndk/index.html) since version r12b.
|
||||
(The NDK build uses sources from https://android.googlesource.com/platform/external/shaderc/.
|
||||
Those repos are downstream from GitHub.)
|
||||
We currently require r25c.
|
||||
|
||||
For licensing terms, please see the [`LICENSE`](LICENSE) file. If interested in
|
||||
contributing to this project, please see [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
|
||||
This is not an official Google product (experimental or otherwise), it is just
|
||||
code that happens to be owned by Google. That may change if Shaderc gains
|
||||
contributions from others. See the [`CONTRIBUTING.md`](CONTRIBUTING.md) file
|
||||
for more information. See also the [`AUTHORS`](AUTHORS) and
|
||||
[`CONTRIBUTORS`](CONTRIBUTORS) files.
|
||||
|
||||
## File organization
|
||||
|
||||
- `android_test/` : a small Android application to verify compilation
|
||||
- `cmake/`: CMake utility functions and configuration for Shaderc
|
||||
- `examples/`: Example programs
|
||||
- `glslc/`: an executable to compile GLSL to SPIR-V
|
||||
- `libshaderc/`: a library for compiling shader strings into SPIR-V
|
||||
- `libshaderc_util/`: a utility library used by multiple shaderc components
|
||||
- `third_party/`: third party open source packages; see below
|
||||
- `utils/`: utility scripts for Shaderc
|
||||
|
||||
Shaderc depends on glslang, the Khronos reference compiler for GLSL.
|
||||
|
||||
Shaderc depends on [SPIRV-Tools][spirv-tools] for assembling, disassembling,
|
||||
and transforming SPIR-V binaries.
|
||||
|
||||
For testing, Shaderc depends on:
|
||||
| Library | URL | Description |
|
||||
| -- | -- | -- |
|
||||
| Googletest | https://github.com/google/googletest | Testing framework |
|
||||
| Effcee | https://github.com/google/effcee | Stateful pattern matcher inspired by LLVM's FileCheck |
|
||||
| RE2 | https://github.com/google/re2 | Regular expression matcher |
|
||||
| Abseil | https://github.com/abseil/abseil-cpp | Common basic utilities in C++ |
|
||||
|
||||
In the following sections, `$SOURCE_DIR` is the directory you intend to clone
|
||||
Shaderc into.
|
||||
|
||||
## Getting and building Shaderc
|
||||
|
||||
**If you only want prebuilt executables or libraries, see the
|
||||
[Downloads](#downloads) section.**
|
||||
|
||||
The rest of this section describes how to build Shaderc from sources.
|
||||
|
||||
Note: Shaderc assumes Glslang supports HLSL compilation. The instructions
|
||||
below assume you're building Glslang from sources, and in a subtree
|
||||
of `shaderc/third_party`. In that scenario, Glslang's HLSL support
|
||||
is automatically enabled. Shaderc also can be built using a Glslang
|
||||
from outside the `shaderc/third_party` tree. In that case you must
|
||||
ensure that that external Glslang is built with HLSL functionality.
|
||||
See Glslang's `ENABLE_HLSL` CMake setting.)
|
||||
|
||||
1) Check out the source code:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/google/shaderc $SOURCE_DIR
|
||||
cd $SOURCE_DIR
|
||||
./utils/git-sync-deps
|
||||
```
|
||||
|
||||
**Note:** The [known-good](https://github.com/google/shaderc/tree/known-good)
|
||||
branch of the repository contains a
|
||||
[known_good.json](https://github.com/google/shaderc/blob/known-good/known_good.json)
|
||||
file describing a set of repo URLs and specific commits that have been
|
||||
tested together. This information is updated periodically, and typically
|
||||
matches the latest update of these sources in the development branch
|
||||
of the Android NDK.
|
||||
The `known-good` branch also contains a
|
||||
[update_shaderc.py](https://github.com/google/shaderc/blob/known-good/update_shaderc_sources.py)
|
||||
script that will read the JSON file and checkout those specific commits for you.
|
||||
|
||||
2) Ensure you have the requisite tools -- see the tools subsection below.
|
||||
|
||||
3) Decide where to place the build output. In the following steps, we'll call it
|
||||
`$BUILD_DIR`. Any new directory should work. We recommend building outside
|
||||
the source tree, but it is also common to build in a (new) subdirectory of
|
||||
`$SOURCE_DIR`, such as `$SOURCE_DIR/build`.
|
||||
|
||||
4a) Build (and test) with Ninja on Linux or Windows:
|
||||
|
||||
```sh
|
||||
cd $BUILD_DIR
|
||||
cmake -GNinja -DCMAKE_BUILD_TYPE={Debug|Release|RelWithDebInfo} $SOURCE_DIR
|
||||
ninja
|
||||
ctest # optional
|
||||
```
|
||||
|
||||
4b) Or build (and test) with MSVC on Windows:
|
||||
|
||||
```sh
|
||||
cd $BUILD_DIR
|
||||
cmake $SOURCE_DIR
|
||||
cmake --build . --config {Release|Debug|MinSizeRel|RelWithDebInfo}
|
||||
ctest -C {Release|Debug|MinSizeRel|RelWithDebInfo}
|
||||
```
|
||||
|
||||
4c) Or build with MinGW on Linux for Windows:
|
||||
|
||||
```sh
|
||||
cd $BUILD_DIR
|
||||
cmake -GNinja -DCMAKE_BUILD_TYPE={Debug|Release|RelWithDebInfo} $SOURCE_DIR \
|
||||
-DCMAKE_TOOLCHAIN_FILE=$SOURCE_DIR/cmake/linux-mingw-toolchain.cmake
|
||||
ninja
|
||||
```
|
||||
|
||||
After a successful build, you should have a `glslc` executable somewhere under
|
||||
the `$BUILD_DIR/glslc/` directory, as well as a `libshaderc` library somewhere
|
||||
under the `$BUILD_DIR/libshaderc/` directory.
|
||||
|
||||
The default behavior on MSVC is to link with the static CRT. If you would like
|
||||
to change this behavior `-DSHADERC_ENABLE_SHARED_CRT` may be passed on the
|
||||
cmake configure line.
|
||||
|
||||
See [the libshaderc README](libshaderc/README.md) for more on using the library
|
||||
API in your project.
|
||||
|
||||
### Tools you'll need
|
||||
|
||||
For building, testing, and profiling Shaderc, the following tools should be
|
||||
installed regardless of your OS:
|
||||
|
||||
- A C++17 compiler. Recent versions of Clang, GCC, and MSVC work.
|
||||
- [CMake](http://www.cmake.org/) 3.14 or later: for generating compilation targets.
|
||||
- Shaderc is tested with cmake 3.17.2
|
||||
- [Python 3](http://www.python.org/): for utility scripts and running the test suite.
|
||||
|
||||
On Linux, if cross compiling to Windows:
|
||||
- [`mingw`](http://www.mingw.org): A GCC-based cross compiler targeting Windows
|
||||
so that generated executables use the Microsoft C runtime libraries.
|
||||
The MinGW compiler must support C++17.
|
||||
|
||||
On Windows, the following tools should be installed and available on your path:
|
||||
|
||||
- Visual Studio 2017 or later. Previous versions of Visual Studio may work but
|
||||
are untested and unsupported.
|
||||
- Git - including the associated tools, Bash, `diff`.
|
||||
|
||||
Optionally, the following tools may be installed on any OS:
|
||||
|
||||
- [`asciidoctor`](http://asciidoctor.org/): for generating documentation.
|
||||
- [`pygments.rb`](https://rubygems.org/gems/pygments.rb) required by
|
||||
`asciidoctor` for syntax highlighting.
|
||||
|
||||
### Building and running Shaderc using Docker
|
||||
|
||||
Please make sure you have the Docker engine
|
||||
[installed](https://docs.docker.com/engine/installation/) on your machine.
|
||||
|
||||
To create a Docker image containing Shaderc command line tools, issue the
|
||||
following command in `${SOURCE_DIR}`: `docker build -t <IMAGE-NAME> .`.
|
||||
The created image will have all the command line tools installed at
|
||||
`/usr/local` internally, and a data volume mounted at `/code`.
|
||||
|
||||
Assume `<IMAGE-NAME>` is `shaderc/shaderc` from now on.
|
||||
|
||||
To invoke a tool from the above created image in a Docker container:
|
||||
|
||||
```bash
|
||||
docker run shaderc/shaderc glslc --version
|
||||
```
|
||||
|
||||
Alternatively, you can mount a host directory (e.g., `example`) containing
|
||||
the shaders you want to manipulate and run different kinds of tools via
|
||||
an interactive shell in the container:
|
||||
|
||||
```bash
|
||||
$ docker run -i -t -v `pwd`/example:/code shaderc/shaderc
|
||||
/code $ ls
|
||||
test.vert
|
||||
/code $ glslc -c -o - test.vert | spirv-dis
|
||||
```
|
||||
|
||||
## Bug tracking
|
||||
|
||||
We track bugs using GitHub -- click on the "Issues" button on
|
||||
[the project's GitHub page](https://github.com/google/shaderc).
|
||||
|
||||
## Bindings
|
||||
|
||||
Bindings are maintained by third parties, may contain content
|
||||
offered under a different license, and may reference or contain
|
||||
older versions of Shaderc and its dependencies.
|
||||
|
||||
* **Python:** [pyshaderc][pyshaderc]
|
||||
* **Rust:** [shaderc-rs][shaderc-rs]
|
||||
* **Go:** [gshaderc][gshaderc]
|
||||
* **.NET:** [shaderc.net][shadercdotnet]
|
||||
* **Common Lisp:** [shadercl][shaderccommonlisp]
|
||||
|
||||
[khr-glslang]: https://github.com/KhronosGroup/glslang
|
||||
[spirv-tools]: https://github.com/KhronosGroup/SPIRV-Tools
|
||||
[spirv-cross]: https://github.com/KhronosGroup/SPIRV-Cross
|
||||
[pyshaderc]: https://github.com/realitix/pyshaderc
|
||||
[shaderc-rs]: https://github.com/google/shaderc-rs
|
||||
[appveyor]: https://ci.appveyor.com/project/dneto0/shaderc
|
||||
[dawn]: https://dawn.googlesource.com/dawn
|
||||
[gshaderc]: https://github.com/celer/gshaderc
|
||||
[shadercdotnet]: https://github.com/jpbruyere/shaderc.net
|
||||
[shaderccommonlisp]: https://github.com/JolifantoBambla/shadercl
|
||||
Reference in New Issue
Block a user