README

⚔️ CrossShader

A cross compiler for shader languages. Convert between SPIR-V, GLSL / GLSL ES, HLSL, Metal Shader Language, or older versions of a given language. Cross Shader wraps glslang and SPIRV-Cross, exposing a simpler interface to transpile shaders.

Installation

Node.js Installation

npm i cross-shader -S

Note the use of dash-case vs CamelCase for the npm module name, this is to follow the JavaScript community's focus on making names that fit well with browser URLs.

Using this module will require Node 8.x or above, or a browser that supports WebAssembly.

C++ Installation

First add the repo as a submodule in your dependencies folder such as external/:

cd external
git submodule add https://github.com/alaingalvan/crossshader.git

Then in your CMakeLists.txt file, include the following:

# ⬇ Add your dependency:
add_subdirectories(external/crossshader)

# 🔗 Link CrossShader to your project:
target_link_libraries(
    ${PROJECT_NAME}
    CrossShader
)

Usage

This library exposes a single function compile(...) and its config structs/enums, and returns either the output string, or throws an exception if there's an error compiling, with the error message exposed in the exception object.

Node.js Example

TypeScript types are included, refer to cross-shader.d.ts for more details.

Similar to other WebAssembly modules, importing the module gives you a promise to the compiled WebAssembly binary:

import xsdr from 'cross-shader';

xsdr.then(({ compile, ShaderFormat, ShaderStage }) => {
  const ioptions = {
    format: ShaderFormat.GLSL,
    stage: ShaderStage.Vertex,
    es: false,
    glslVersion: 450
  };

  const ooptions = {
    format: ShaderFormat.GLSL,
    es: true,
    glslVersion: 100
  }

  let outputString = compile(inputString, ioptions, ooptions);
});

C++ Example

Refer to src/CrossShader/CrossShader.h for more details.

#include "CrossShader/CrossShader.h"

void main()
{
  xsdr::InputOptions ioptions;
  ioptions.format = xsdr::ShaderFormat::GLSL;
  ioptions.stage = xsdr::ShaderStage::Vertex;
  ioptions.es = false;
  ioptions.glslVersion = 110;

  xsdr::OutputOptions ooptions;
  ooptions.format = xsdr::ShaderFormat::GLSL;
  ooptions.es = true;
  ooptions.glslVersion = 100;

  std::string out = xsdr::compile(vertSource, ioptions, ooptions);
}

Development

Be sure to have:

Git
Any terminal such as Hyper

And type the following in any folder:

# 🐑 Clone the repo
git clone https://github.com/alaingalvan/crossshader.git --recurse-submodules

# 💿 go inside the folder
cd crossshader

# 👯 If you forget to `recurse-submodules` you can always run:
git submodule update --init

From there we'll need to set up our build files. Be sure to have the following installed:

CMake
An IDE such as Visual Studio, XCode, or a compiler such as GCC.

Then type the following in your terminal from the repo folder:

# 👷 Make a build folder
mkdir build
cd build

# 🖼️ To build your Visual Studio solution on Windows x64
cmake .. -A x64

# 🍎 To build your XCode project on Mac OS
cmake .. -G Xcode

# 🐧 To build your MakeFile on Linux
cmake ..

# 🔨 Build on any platform:
cmake --build .

Whenever you add new files to the project, run cmake .. from your solution/project folder, and if you edit the CMakeLists.txt file be sure to delete the generated files and run Cmake again.

WebAssembly

Note: if you're on Windows, I would highly recommend using the Windows Subsystem for Linux.

First, install the latest version of Emscripten via the Emscripten SDK. Make sure to add it's Emscripten installation to your PATH, then:

# ⚠️ Possible dependencies you might need:
sudo apt-get update
sudo apt-get install cmake build-essential llvm

# 🏃 Then run the following:
mkdir wasm
cd wasm
emcmake cmake ..
emmake make CrossShader -j

License

CrossShader is licensed as either MIT or Apache-2.0, whichever you would prefer.

Usage no npm install needed!