Need help with shaderc-rs?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

google
165 Stars 48 Forks Apache License 2.0 178 Commits 17 Opened issues

Description

Rust bindings for the shaderc library.

Services available

!
?

Need anything else?

Contributors list

shaderc-rs

Version Documentation Build Status Build status

Rust bindings for the shaderc library.

Disclaimer

This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google.

Usage

The included shaderc-sys crate uses

build.rs
to discover or build a copy of shaderc libraries. See Setup section.

First add to your

Cargo.toml
:
[dependencies]
shaderc = "0.7"

Then add to your crate root:

extern crate shaderc;

Documentation

shaderc provides the

Compiler
interface to compile GLSL/HLSL source code into SPIR-V binary modules or assembly code. It can also assemble SPIR-V assembly into binary module. Default compilation behavior can be adjusted using
CompileOptions
. Successful results are kept in
CompilationArtifact
s.

Please see Documentation for detailed documentation.

Example

Compile a shader into SPIR-V binary module and assembly text:

use shaderc;

let source = "#version 310 es\n void EP() {}";

let mut compiler = shaderc::Compiler::new().unwrap(); let mut options = shaderc::CompileOptions::new().unwrap(); options.add_macro_definition("EP", Some("main")); let binary_result = compiler.compile_into_spirv( source, shaderc::ShaderKind::Vertex, "shader.glsl", "main", Some(&options)).unwrap();

assert_eq!(Some(&0x07230203), binary_result.as_binary().first());

let text_result = compiler.compile_into_spirv_assembly( source, shaderc::ShaderKind::Vertex, "shader.glsl", "main", Some(&options)).unwrap();

assert!(text_result.as_text().starts_with("; SPIR-V\n"));

Setup

shaderc-rs needs the C++ shaderc library. It's shipped inside the Vulkan SDK. You may be able to install it directly on some Linux distro's using the package manager. The C++ shaderc project provides artifacts downloads. You can also build it from source.

The order of preference in which the build script attempts to obtain native shaderc can be controlled by several options, which are passed through to shaderc-sys when building shaderc-rs:

  1. Building from source, if option
    --features build-from-source
    is specified.
  2. If the
    SHADERC_LIB_DIR
    environment variable is set to
    /path/to/shaderc/libs/
    , that path will be searched for native dynamic or static shaderc library.
  3. If the
    VULKAN_SDK
    environment variable is set, then
    $VULKAN_SDK/lib
    will be searched for native dynamicd or static shaderc library.
  4. On Linux, system library paths like
    /usr/lib/
    will additionally be searched for native dynamic or shaderc library, if the
    SHADERC_LIB_DIR
    is not set.
  5. Building from source, if the native shaderc library is not found via the above steps.

For each library directory, the build script will try to fine and link to the dynamic native shaderc library

shaderc_shared
first and the static native shaderc library
shaderc_combined
next.

Building from Source

The shaderc-sys

build.rs
will automatically check out and compile a copy of native C++ shaderc and link to the generated artifacts, which requires

git
,
cmake
, and
python
existing in the
PATH
:
  • CMake
  • Git
  • Python (only works with Python 3, on Windows the executable must be named
    python.exe
    )
  • a C++11 compiler

Additionally: - Ninja is required on windows-msvc, but optional on all other platforms.

These requirements can be either installed with your favourite package manager or with installers from the projects' websites. Below are some example ways to get setup.

windows-msvc Example Setup

  1. rustup default stable-x86_64-pc-windows-msvc
  2. Install Build Tools for Visual Studio 2017. If you have already been using this toolchain then its probably already installed.
  3. Install the necessary tools as listed in the above and add their paths to the
    PATH
    environment variable.

windows-gnu Example Setup

windows-gnu toolchain is not supported but you can instead cross-compile to windows-gnu from windows-msvc.

Steps 1 and 2 are to workaround https://github.com/rust-lang/rust/issues/49078 by using the same mingw that rust uses.

  1. Download and extract https://s3-us-west-1.amazonaws.com/rust-lang-ci2/rust-ci-mirror/x8664-6.3.0-release-posix-seh-rtv5-rev2.7z
  2. Add the absolute path to mingw64\bin to your PATH environment variable.
  3. Run the command:
    rustup default stable-x86_64-pc-windows-msvc
  4. Run the command:
    rustup target install x86_64-pc-windows-gnu
  5. Install Build Tools for Visual Studio 2017. If you have already been using this toolchain then its probably already installed.
  6. Install msys2, following ALL of the instructions.
  7. Then in the msys2 terminal run:
    pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-make mingw-w64-x86_64-python3 mingw-w64-x86_64-ninja
  8. Add the msys2 mingw64 binary path to the PATH environment variable.
  9. Any cargo command that builds the project needs to include
    --target x86_64-pc-windows-gnu
    e.g. to run:
    cargo run --target x86_64-pc-windows-gnu

Linux Example Setup

Use your package manager to install the required dev-tools

For example on ubuntu:

sudo apt-get install build-essential cmake git ninja python3

On Arch linux, you can directly install the shaderc package.

macOS Example Setup

Assuming Homebrew:

brew install git cmake ninja [email protected]

Contributions

This project is licensed under the Apache 2 license. Please see CONTRIBUTING before contributing.

Authors

This project is initialized and mainly developed by Lei Zhang (@antiagainst).

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.