shdrlib 0.1.0 - Docs.rs

# shdrlib

- systems for shaders, shaders for systems.”

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

[![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 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


```toml
[dependencies]
shdrlib = "0.1.0"
ash = "0.38"  # For Vulkan types
```

### Your First Triangle (EZ Tier)


Just **30 lines** to render with Vulkan:

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

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

📖 **[Read the full Quick Start Guide →](QUICKSTART.md)**


---

## 📚 Choose Your Tier


### 🎯 EZ Tier - Perfect for Learning


**Best for:** Prototyping, learning Vulkan, quick demos

```rust
// 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 →](docs/guides/ez-tier-guide.md)** | 🎨 **[Examples →](demos/ez/)**

---

### ⭐ EX Tier - Recommended for Production


**Best for:** Real applications, games, production code

```rust
// 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 →](docs/guides/ex-tier-guide.md)** | 🎨 **[Examples →](demos/ex/)**

---

### 🔧 CORE Tier - Maximum Control


**Best for:** Engine development, custom frameworks

```rust
// 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 →](docs/guides/core-tier-guide.md)** | 🎨 **[Examples →](demos/core/)**


---

## � Documentation


### 🚀 Getting Started

- **[Quick Start](QUICKSTART.md)** - Your first triangle in 5 minutes
- **[Installation](docs/getting-started/installation.md)** - Set up your environment
- **[Choosing a Tier](docs/getting-started/choosing-a-tier.md)** - Which tier is right for you?
- **[FAQ](docs/getting-started/faq.md)** - Common questions answered
- **[Troubleshooting](docs/getting-started/troubleshooting.md)** - Fix common issues

### 📚 Guides

- **[EZ Tier Guide](docs/guides/ez-tier-guide.md)** - High-level API guide
- **[EX Tier Guide](docs/guides/ex-tier-guide.md)** - Production tier guide ⭐
- **[CORE Tier Guide](docs/guides/core-tier-guide.md)** - Low-level API guide
- **[Migration Guide](docs/guides/migration-guide.md)** - Moving between tiers

### 🏗️ Architecture

- **[Overview](docs/architecture/overview.md)** - Design philosophy
- **[Three-Tier Design](docs/architecture/three-tier-design.md)** - Why three tiers?
- **[Zero-Cost Abstractions](docs/architecture/zero-cost-abstractions.md)** - Performance details

### 📖 API Reference

- **[Complete Index](docs/INDEX.md)** - Full documentation map
- **Run `cargo doc --open`** for detailed API docs


---

## 🎨 Examples


### Run Examples


```bash
# 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


```bash
# 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](CONTRIBUTING.md)** - Contribution guidelines
2. **[Code of Conduct](CONTRIBUTING.md#code-of-conduct)** - Be respectful
3. **[Development Workflow](CONTRIBUTING.md#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](LICENSE-MIT) and [LICENSE-APACHE](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](QUICKSTART.md) |
| 📚 **Documentation** | [docs/README.md](docs/README.md) |
| 🎨 **Examples** | [demos/](demos/) |
| 🤝 **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) |
| 📋 **Roadmap** | [CHANGELOG.md](CHANGELOG.md) |
| � **Issues** | [GitHub Issues](https://github.com/paulburnettjones-wq/shdrlib/issues) |
| 💬 **Discussions** | [GitHub Discussions](https://github.com/paulburnettjones-wq/shdrlib/discussions) |

---

**Ready to render?**

```bash
cargo add shdrlib ash
```

Then follow the **[Quick Start Guide](QUICKSTART.md)** to render your first triangle!

---

**Last Updated:** October 30, 2025 | **Version:** 0.1.0