CrossTL

CrossTL translates GPU shaders and compute kernels between languages. Every translation goes through CrossGL, a small intermediate language: a frontend imports GLSL, HLSL, Metal or another source language into CrossGL, and a code generator writes CrossGL out as GLSL, HLSL, Metal, SPIR-V, WGSL or another target. You can also write CrossGL directly and generate every target from one source file.

CI measures this chart on every push to main and nightly. Every feature in a pinned upstream feature list gets a generated probe, CrossTL translates it, and the language's reference compiler or validator checks the result. Compute probes also run, on the GPU or on Mesa's software drivers, where the translation must compute what the native probe computes: Metal, GLSL and SPIR-V directly, and HLSL, Slang, WGSL and Rust as the SPIR-V their reference compilers produce. The chart gives each row the number of probes that ran, and marks CUDA, HIP, OpenCL C, Mojo and WebGL compile-only. A translation must also keep the built-ins and decorations, such as flat or the subgroup size, that the feature needs in the SPIR-V its compiler produces, or in the AIR for Metal. The score is supported / (supported + refused + wrong). COVERAGE.md lists every gap behind each bar.

Install

pip install crosstl

CrossTL needs Python 3.11 or later. Validating the generated code needs the target's own compiler or validator (glslang, DXC, spirv-tools, naga, the Metal compiler, nvcc, hipcc, slangc, rust-gpu or the Mojo compiler), which CrossTL does not install. crosstl doctor lists the tools it looks for and which of them are on PATH.

Quickstart

Save this compute kernel as saxpy.cgl:

shader Saxpy {
    compute {
        layout(local_size_x = 64, local_size_y = 1, local_size_z = 1) in;
        buffer float* x;
        buffer float* y;
        uniform float a;

        void main() {
            uint i = gl_GlobalInvocationID.x;
            y[i] = a * x[i] + y[i];
        }
    }
}

Then translate it from Python, where the source language comes from the file extension:

import crosstl

metal = crosstl.translate("saxpy.cgl", backend="metal")
crosstl.translate("saxpy.cgl", backend="wgsl", save_shader="saxpy.wgsl")

# A native shader is imported into CrossGL first, then generated for the target.
glsl = crosstl.translate("blur.hlsl", backend="opengl")
crossgl = crosstl.translate("blur.hlsl", backend="cgl")

or from the command line:

crosstl translate saxpy.cgl --backend directx --output saxpy.hlsl
crosstl translate saxpy.cgl --backend vulkan --output -

python -m crosstl is the same command. The examples/ directory has larger CrossGL programs.

Languages

Language	backend	Output	Input
GLSL	opengl	measured	measured
HLSL	directx	measured	measured
Metal	metal	measured	measured
SPIR-V assembly	vulkan	measured	measured
WGSL	wgsl	measured	not offered
GLSL ES 3.00 (WebGL 2)	webgl	measured	not offered
CUDA	cuda	measured	measured
HIP	hip	measured	measured
Slang	slang	measured	measured
Rust (rust-gpu)	rust	measured	measured
Mojo	mojo	measured	measured
OpenCL C		not offered	measured

A measured direction has a row in COVERAGE.md. CrossTL has no OpenCL C generator, so the OpenCL C input row checks the HLSL that CrossTL writes from each OpenCL C probe. The language names glsl, hlsl, msl and spirv work as backend names too, and cgl writes the CrossGL a native source imports to. CrossGL has its own coverage row, CrossGL IR, which measures how many of the features of all the measured output languages CrossGL can express.

CrossTL is meant to fail closed: a construct it cannot translate raises a diagnostic that names the construct and the target, instead of emitting a placeholder. Output that the reference tool rejects, or that has a comment saying CrossTL wrote a placeholder, counts as wrong in the coverage report, and the Coverage workflow files it as a bug.

How it works

 .hlsl .metal .glsl .cu ...                                        .glsl .hlsl .metal .spvasm .wgsl ...
 native source --> frontend --> CrossGL source --> CrossGL parser --> code generator --> target source
                   (parse and                      (AST and types)     (one per target)
                    import)

Each source language has a frontend in crosstl/backend/<Language>/ that parses it and writes CrossGL. The CrossGL parser in crosstl/translator/ builds the typed AST that every code generator in crosstl/translator/codegen/ reads, so a feature added to CrossGL is available to every target that can express it.

Porting a repository

For a project with many shader or kernel sources, scan it before writing anything, then translate it and check the report:

python -m crosstl scan path/to/repo --target metal --output scan-report.json
python -m crosstl translate-project path/to/repo --target metal --output-dir crosstl-out \
  --report crosstl-out/report.json
python -m crosstl validate-project crosstl-out/report.json --format text
python -m crosstl inspect-report crosstl-out/report.json --format text

This is the beginning of the README. Read the rest at the original. Read the full README ↗