shdrlib 0.1.2

A three-tiered Vulkan shader compilation and rendering framework built in pure Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

# shdrlib


**Three-tier Vulkan rendering in pure Rust. Choose your abstraction.**

[![Rust](https://img.shields.io/badge/rust-2024-orange.svg)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)

## What is this?


A backend Vulkan library with three tiers of abstraction:

- **EZ** - One-liners, smart defaults (~30 lines for a triangle)
- **EX** (recommended) - Explicit control, production-ready (~100 lines for a triangle)
- **CORE** - Thin Vulkan wrappers, max control (~400 lines for a triangle)

**This is NOT a game engine.** It's a rendering library. You bring your own windowing.

## Quick Start


```toml
[dependencies]
shdrlib = "0.1.2"
ash = "0.38"
```

### EZ Tier - 30 Lines


```rust
use shdrlib::ez::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut renderer = EzRenderer::new()?;
    let pipeline = renderer.quick_pipeline(VERTEX_GLSL, FRAGMENT_GLSL)?;
    
    renderer.render_frame(|frame| {
        frame.bind_pipeline(pipeline)?;
        frame.set_viewport(0.0, 0.0, 800.0, 600.0);
        frame.set_scissor(0, 0, 800, 600);
        frame.draw(3, 1, 0, 0);
        Ok(())
    })?;
    
    Ok(())
}

const VERTEX_GLSL: &str = r#"
#version 450

vec2 pos[3] = vec2[](vec2(0.0,-0.5), vec2(0.5,0.5), vec2(-0.5,0.5));
void main() { gl_Position = vec4(pos[gl_VertexIndex], 0.0, 1.0); }
"#;

const FRAGMENT_GLSL: &str = r#"
#version 450

layout(location = 0) out vec4 outColor;
void main() { outColor = vec4(1.0, 0.5, 0.2, 1.0); }
"#;
```

### EX Tier - 100 Lines (Recommended)


```rust
use shdrlib::{core::ShaderStage, ex::*};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut runtime = RuntimeManager::new(RuntimeConfig::default())?;
    let mut shaders = ShaderManager::new(runtime.device())?;

    let vert = shaders.add_shader(VERTEX_GLSL, ShaderStage::Vertex, "vert")?;
    let frag = shaders.add_shader(FRAGMENT_GLSL, ShaderStage::Fragment, "frag")?;

    let pipeline = shaders.build_pipeline(
        PipelineBuilder::new()
            .vertex_shader(shaders.get_shader(vert)?.handle(), "main")
            .fragment_shader(shaders.get_shader(frag)?.handle(), "main")
            .color_attachment_formats(vec![ash::vk::Format::R8G8B8A8_UNORM]),
        "triangle"
    )?;

    loop {
        let frame = runtime.begin_frame()?;
        // ... record commands ...
        runtime.end_frame(&Default::default())?;
    }
}
```

### CORE Tier - Maximum Control


```rust
use shdrlib::core::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let instance = Instance::new(&InstanceCreateInfo::default())?;
    let device = Device::new(&instance, /* ... */)?;
    let shader = Shader::from_glsl(&device, GLSL, ShaderStage::Vertex)?;
    // ... 400+ lines of explicit setup ...
}
```

## Examples


```bash
# EZ tier (learning)

cargo run --bin ez_01_hello_triangle

# EX tier (production, recommended)

cargo run --bin ex_01_triangle_100_lines

# CORE tier (advanced)

cargo run --bin 01_triangle_raw
```

## Features


- **Pure Rust** - naga for shader compilation, no external tools
- **Zero-cost abstractions** - All tiers compile to same machine code
- **Memory safe** - Rust ownership prevents use-after-free
- **Flexible** - Drop to lower tiers anytime for more control

## Documentation


- **[Quick Start](QUICKSTART.md)** - Triangle in 5 minutes
- **[User Guide](docs/README.md)** - Full documentation
- **[API Docs](https://docs.rs/shdrlib)** - Or run `cargo doc --open`
- **[Examples](demos/)** - Working code for all tiers

## Requirements


- Rust 1.82+ (Edition 2024)
- Vulkan 1.3+ with dynamic rendering
- Windows, Linux, or macOS

## Status


| Component | Status | Tests |
|-----------|--------|-------|
| CORE Tier | Complete | 48 passing |
| EX Tier | Complete | 25 passing |
| EZ Tier | Complete | 3 demos |

## Dependencies


- **ash** 0.38 - Vulkan bindings
- **naga** 22 - GLSL→SPIR-V compiler
- **spirv-reflect** 0.2 - Reflection
- **thiserror** 1.0 - Error handling

## License


Dual-licensed under MIT or Apache-2.0.

## Contributing


See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

**Getting Started:** `cargo add shdrlib ash` and see [QUICKSTART.md](QUICKSTART.md)