shdrlib

• systems for shaders, shaders for systems.”

A three-tiered Vulkan shader compilation and rendering framework built in pure Rust.

---

🎯 What is shdrlib?

shdrlib is a backend Vulkan rendering library with a unique three-tier architecture that lets you choose your abstraction level:

┌─────────────────────────────────────────────────┐
│  EZ TIER   │  One-liners with smart defaults     │  13x code reduction
│  (Easy)    │  Perfect for learning & prototyping │  ~30 lines
├────────────┼─────────────────────────────────────┤
│  EX TIER ⭐ │  Explicit control, ergonomic APIs   │  4-8x code reduction
│  (Explicit)│  Production-ready, type-safe        │  ~100 lines
├────────────┼─────────────────────────────────────┤
│  CORE TIER │  Thin Vulkan wrappers               │  Maximum control
│  (Control) │  For frameworks and engines         │  ~400 lines
└─────────────────────────────────────────────────┘

Key Features:

• ✅ Pure Rust - No external build tools (uses naga for shader compilation)
• ✅ Zero-cost abstractions - All tiers compile to identical machine code
• ✅ Memory safe - Rust's ownership prevents use-after-free
• ✅ Progressive disclosure - Drop to lower tiers anytime for more control
• ✅ All three tiers complete - CORE, EX, and EZ are production-ready!

This is NOT a game engine - it's a backend library. You bring your own windowing (winit, sdl2, etc.).

---

🚀 Quick Start

Installation

[dependencies]

shdrlib = "0.1.0"

ash = "0.38"  # For Vulkan types

Your First Triangle (EZ Tier)

Just 30 lines to render with Vulkan:

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(())
}

That's it! You just rendered a triangle with Vulkan.

📖 Read the full Quick Start Guide →

---

📚 Choose Your Tier

🎯 EZ Tier - Perfect for Learning

Best for: Prototyping, learning Vulkan, quick demos

// One-liner setup
let mut renderer = EzRenderer::new()?;

// One-liner pipelines
let graphics = renderer.quick_pipeline(VERTEX, FRAGMENT)?;
let compute = renderer.quick_compute(COMPUTE)?;

// One-liner buffers
let vertices = renderer.create_vertex_buffer(&data)?;

Pros:

• ✅ 13x less code than CORE (30 lines vs 400)
• ✅ Perfect for learning Vulkan
• ✅ Intelligent defaults
• ✅ Hard to misuse

Use when: Learning, prototyping, teaching, demos

📖 EZ Tier Guide → | 🎨 Examples →

---

⭐ EX Tier - Recommended for Production

Best for: Real applications, games, production code

// Explicit but ergonomic
let mut runtime = RuntimeManager::new(RuntimeConfig::default())?;
let mut shaders = ShaderManager::new(runtime.device())?;

let shader_id = shaders.add_shader(source, stage, "name")?;
let pipeline_id = shaders.build_pipeline(
    PipelineBuilder::new()
        .vertex_shader(vert_module, "main")
        .fragment_shader(frag_module, "main")
        .color_attachment_formats(vec![Format::R8G8B8A8_UNORM]),
    "my_pipeline"
)?;

Pros:

• ✅ 4-8x less code than CORE (100 lines vs 400)
• ✅ Type-safe (ShaderId, PipelineId)
• ✅ Zero-cost abstractions
• ✅ Memory safe
• ✅ Production-ready

Use when: Building apps/games, need safety + control

📖 EX Tier Guide → | 🎨 Examples →

---

🔧 CORE Tier - Maximum Control

Best for: Engine development, custom frameworks

// Direct Vulkan control
let instance = Instance::new(&entry, &instance_info)?;
let device = Device::new(&instance, physical_device, &device_info)?;
let shader = Shader::from_glsl(&device, source, ShaderStage::Vertex)?;

Pros:

• ✅ Maximum control
• ✅ Zero overhead
• ✅ Drop down anytime from higher tiers
• ✅ Direct Vulkan access

Use when: Building frameworks, need absolute control

📖 CORE Tier Guide → | 🎨 Examples →

---

� Documentation

🚀 Getting Started

• Quick Start - Your first triangle in 5 minutes
• Installation - Set up your environment
• Choosing a Tier - Which tier is right for you?
• FAQ - Common questions answered
• Troubleshooting - Fix common issues

📚 Guides

• EZ Tier Guide - High-level API guide
• EX Tier Guide - Production tier guide ⭐
• CORE Tier Guide - Low-level API guide
• Migration Guide - Moving between tiers

🏗️ Architecture

• Overview - Design philosophy
• Three-Tier Design - Why three tiers?
• Zero-Cost Abstractions - Performance details

📖 API Reference

• Complete Index - Full documentation map
• Run cargo doc --open for detailed API docs

---

🎨 Examples

Run Examples

# EZ tier (learning & prototyping)

cargo run --bin ez_01_hello_triangle

cargo run --bin ez_02_compute_multiply


# EX tier (production) ⭐ Recommended

cargo run --bin ex_01_triangle_100_lines

cargo run --bin ex_03_textured_quad


# CORE tier (advanced)

cargo run --bin 01_triangle_raw

Example Comparison

Example	CORE Tier	EX Tier	EZ Tier
Triangle	400 lines	100 lines	30 lines
Textured Quad	400 lines	50 lines	35 lines
Compute Shader	300 lines	75 lines	25 lines

Code reduction: 4x to 13x while maintaining identical performance!

---

🧪 Testing

# Run all tests

cargo test


# Run tier-specific tests

cargo test --lib core::

cargo test --lib ex::


# Run with output

cargo test -- --nocapture

Status: 73 tests passing ✅ (48 CORE + 25 EX)

---

🏗️ Project Status

Component	Status	LOC	Tests
CORE Tier	✅ Complete	~3,440	48 ✅
EX Tier	✅ Complete	~3,000	25 ✅
EZ Tier	✅ Complete	~600	3 demos ✅
Documentation	🚧 In Progress	-	-

All three tiers are production-ready! 🎉

---

🗺️ Roadmap

Current Release (v0.1) - Q4 2025

• ✅ CORE tier complete (12 modules)
• ✅ EX tier complete (6 components)
• ✅ EZ tier complete
• ✅ 9 working demos
• 🚧 Documentation overhaul

Next Release (v0.2) - Q1 2026

• 📋 Performance benchmarks
• 📋 Texture loading from files
• 📋 Enhanced EZ tier features
• 📋 More advanced examples

Future (v0.3+)

• 📋 Ray tracing support
• 📋 Render graph system
• 📋 Multi-threaded recording
• 📋 Advanced profiling

---

🤝 Contributing

We welcome contributions! Please read:

1. CONTRIBUTING.md - Contribution guidelines
2. Code of Conduct - Be respectful
3. Development Workflow - How to contribute

Areas we need help:

• 📖 Documentation improvements
• 🧪 More test coverage
• 🎨 Additional examples
• 🐛 Bug fixes

---

� Dependencies

• ash 0.38 - Vulkan bindings
• naga 22 - Pure Rust GLSL→SPIR-V compiler
• spirv-reflect 0.2 - SPIR-V reflection
• thiserror 1.0 - Error handling

No external build tools required! Pure Rust shader compilation.

---

🔧 Requirements

• Rust: Edition 2024 (Rust 1.82+)
• Vulkan: 1.3+ with dynamic rendering support
• OS: Windows, Linux, or macOS

---

📄 License

Dual-licensed under MIT or Apache-2.0 (your choice).

See LICENSE-MIT and LICENSE-APACHE.

---

🙏 Acknowledgments

• ash - Excellent Vulkan bindings for Rust
• naga - Pure Rust shader compilation
• Vulkan - Powerful graphics API

---

� Quick Links

Resource	Link
📖 Quick Start	QUICKSTART.md
📚 Documentation	docs/README.md
🎨 Examples	demos/
🤝 Contributing	CONTRIBUTING.md
📋 Roadmap	CHANGELOG.md
� Issues	GitHub Issues
💬 Discussions	GitHub Discussions

---

Ready to render?

cargo add shdrlib ash

Then follow the Quick Start Guide to render your first triangle!

---

Last Updated: October 30, 2025 | Version: 0.1.0