https://github.com/captkirk88/zevy-alloy
Compile a ZSL (Zig Shader Language) to GLSL, HLSL, METAL, DXIL(tool req), SPIRV(tool req)
https://github.com/captkirk88/zevy-alloy
dxil glsl hlsl metal spirv zevy zevy-ecs zig zig-library zig-package ziglang
Last synced: 4 days ago
JSON representation
Compile a ZSL (Zig Shader Language) to GLSL, HLSL, METAL, DXIL(tool req), SPIRV(tool req)
- Host: GitHub
- URL: https://github.com/captkirk88/zevy-alloy
- Owner: captkirk88
- License: mit
- Created: 2026-05-07T00:48:35.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-06T23:17:00.000Z (18 days ago)
- Last Synced: 2026-06-07T01:12:26.572Z (18 days ago)
- Topics: dxil, glsl, hlsl, metal, spirv, zevy, zevy-ecs, zig, zig-library, zig-package, ziglang
- Language: Zig
- Homepage:
- Size: 230 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> [!NOTE]
> Archived, see [zevy-ecs](https://www.github.com/captkirk88/zevy-ecs) README for details.
# zevy-alloy
> Experimental: zevy-alloy is early-stage and may change in breaking ways.
> Metal support is currently untested, open to contributions and testers.
> HLSL output is currently untested, open to contributions and testers.
zevy-alloy is a ZSL shader compiler and build integration library for Zig projects.
It compiles `.zsl` shader sources to multiple targets, including GLSL 450, GLSL 330,
GLSL ES 300, HLSL, Metal, WGSL, SPIR-V, and DXIL.
## Purpose
- Provide a single shader authoring path (`.zsl`) for multiple graphics backends.
- Expose a CLI for direct shader compilation.
- Expose build helpers to compile shaders from `build.zig`.
## Usage
### Build
```bash
zig build
```
### Run tests
```bash
zig build test
```
### Compile configured shaders from build script
```bash
zig build shaders
```
### CLI
```bash
zevy-alloy [options]
```
Commands:
- `compile`: generate requested shader outputs.
- `validate`: validate existing generated shader files at the requested output paths.
Available output options:
- `--out-hlsl `
- `--out-glsl ` (GLSL 450)
- `--out-glsl330 `
- `--out-glsles ` (GLSL ES 300)
- `--out-msl `
- `--out-wgsl `
- `--out-spv `
- `--out-dxil `
- `--spirv-env ` where `` is `opengl`, `vulkan1.0`, `vulkan1.1`, `vulkan1.2`, `vulkan1.3`, or `vulkan1.4`
- `--spirv-version ` where `` is `spv1.0` through `spv1.6`
- `--dxil-model ` where `` is `6.0` through `6.8`
- `--local-size ` (override compute local size)
- `--local-size-x `
- `--local-size-y `
- `--local-size-z `
If no output flags are provided, zevy-alloy uses default output paths next to the source file for all supported formats.
Validation uses backend tools where available:
- GLSL: `glslangValidator`
- SPIR-V: `spirv-val`
- HLSL and DXIL: `dxc`
- WGSL: currently checked for file presence/content only, no external validation tool used yet.
- MSL: currently checked for file presence/content only, no external validation tool used yet.
WGSL generation uses `spirv-cross` (`spirv-cross --wgsl ...`) under the hood.
If `spirv-cross` is not available on PATH, WGSL output requests are reported and skipped.
Compatibility behavior is strict for versioned targets: if a shader uses features that are incompatible with a requested backend/profile (for example, storage buffers in GLSL 330/ES 300, or standalone uniforms for Vulkan SPIR-V), zevy-alloy fails generation instead of silently emitting partial output.
Compute shaders can also set local size in source with a module-level declaration:
```zig
const zsl = @import("zsl");
pub const compute: zsl.ComputeOpts = .{
.local_size_x = 8,
.local_size_y = 8,
.local_size_z = 1,
};
```
Precedence is deterministic: CLI override flags win over source `compute` options, and if neither is set, local size defaults to `1,1,1`.
## Examples
See [examples/](examples/) for sample shaders and usage patterns.
### App-based circles example (zevy_raylib integration)
The [examples/circles.zig](examples/circles.zig) sample now uses `app.run()` and staged systems instead of a manual game loop.
Run it with:
```bash
zig build circles --release=fast
```
## ZLS and IntelliSense
For editor IntelliSense with ZLS (Zig Language Server), import the ZSL stub module in shader files:
```zig
const zsl = @import("zsl");
```
If your editor cannot resolve that module automatically, point it at the local stub file [zsl.zig](zsl.zig), which provides the type/function surface used for completions and diagnostics.
Plain uniforms are now intended to be declared as top-level `pub var` values with an explicit type, for example `pub var time: f32 = 0.0;`. Buffer/sampler/texture resources still use the explicit `zsl.UniformBuffer(...)`, `zsl.StorageBuffer(...)`, `zsl.Texture2D(...)`, and similar wrapper types in the `pub var` annotation. The older `zsl.Uniform(...)` wrapper is still accepted for compatibility, but it is deprecated.
Entry-point input and output struct names are not special. You can name them however you want; `PSInput` and `PSOutput` are just examples used in older shader snippets.