# shdrlib
> **Platform Support Note:**
> This crate is designed to work on any platform with Rust 1.82+ and Vulkan 1.3+ (Windows, Linux, etc.).
> All development and testing for v0.1.4 was performed on Windows. If you encounter platform-specific issues, please report them—community feedback is welcome to help ensure robust cross-platform support.
**Three-tier Vulkan rendering in pure Rust. Choose your abstraction.**
[](https://www.rust-lang.org/)
[](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.4"
ash = "0.38"
```
### EZ Tier - 15 Lines
```rust
use shdrlib::ez::*;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut renderer = EzRenderer::new()?;
// NEW: Pre-built fullscreen quad!
let quad = renderer.create_fullscreen_quad()?;
let pipeline = renderer.quick_pipeline(VERTEX_GLSL, FRAGMENT_GLSL)?;
// NEW: One-line drawing!
renderer.render_frame(|frame| {
frame.draw_mesh(pipeline, &quad)?;
Ok(())
})?;
Ok(())
}
const VERTEX_GLSL: &str = r#"
#version 450
layout(location = 0) in vec2 inPosition;
layout(location = 1) in vec2 inUV;
layout(location = 0) out vec2 fragUV;
void main() { gl_Position = vec4(inPosition, 0.0, 1.0); fragUV = inUV; }
"#;
const FRAGMENT_GLSL: &str = r#"
#version 450
layout(location = 0) in vec2 fragUV;
layout(location = 0) out vec4 outColor;
void main() { outColor = vec4(fragUV, 0.0, 1.0); }
"#;
```
**Alternative: Classic hardcoded vertices (no buffers)**
```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.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 & shader experiments)
cargo run --bin ez_04_splash_screen # Fullscreen shader in ~15 lines!
cargo run --bin ez_01_hello_triangle # Classic triangle
cargo run --bin ez_03_buffers_demo # Before/after Mesh API comparison
# 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** - Automatic resource cleanup via RAII, no leaks or use-after-free
- **Flexible** - Drop to lower tiers anytime for more control
- **Production ready** - Comprehensive memory safety audit passed (see [MEMORY_SAFETY_AUDIT.md](MEMORY_SAFETY_AUDIT.md))
## 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
| CORE Tier | Complete | 48 passing |
| EX Tier | Complete | 25 passing |
| EZ Tier | Complete | 4 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)