# Quick Start Guide
Get up and running with shdrlib in under 5 minutes!
## Installation
Add shdrlib to your `Cargo.toml`:
```toml
[dependencies]
shdrlib = "0.1"
ash = "0.38" # For Vulkan types
```
## Choose Your Tier
shdrlib offers three tiers of abstraction. Pick the one that matches your needs:
### 🎯 EZ Tier - Perfect for Learning
**Best for:** Prototyping, learning Vulkan, quick demos
**Code reduction:** 13x fewer lines than raw Vulkan
**Time to first triangle:** 5 minutes
### ⭐ EX Tier - Recommended for Production
**Best for:** Real applications, games, production code
**Code reduction:** 4-8x fewer lines than raw Vulkan
**Time to first triangle:** 15 minutes
### 🔧 CORE Tier - Maximum Control
**Best for:** Engine development, custom frameworks
**Code reduction:** Thin wrappers only
**Time to first triangle:** 60+ minutes
---
## 🎯 EZ Tier: Your First Triangle in 30 Lines
The fastest way to render with Vulkan:
```rust
use shdrlib::ez::*;
fn main() -> Result<(), Box<dyn std::error::Error>> {
// One-liner setup
let mut renderer = EzRenderer::new()?;
// One-liner pipeline
let pipeline = renderer.quick_pipeline(
VERTEX_SHADER,
FRAGMENT_SHADER
)?;
// Simple render loop
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_SHADER: &str = r#"
#version 450
vec2 positions[3] = vec2[](
vec2(0.0, -0.5),
vec2(0.5, 0.5),
vec2(-0.5, 0.5)
);
void main() {
gl_Position = vec4(positions[gl_VertexIndex], 0.0, 1.0);
}
"#;
const FRAGMENT_SHADER: &str = r#"
#version 450
layout(location = 0) out vec4 outColor;
void main() {
outColor = vec4(1.0, 0.5, 0.2, 1.0);
}
"#;
```
**Run it:**
```bash
cargo run
```
**What just happened?**
- `EzRenderer::new()` - Created Vulkan instance, device, and queues
- `quick_pipeline()` - Compiled shaders and created graphics pipeline
- `render_frame()` - Recorded and submitted commands
- **Total: ~30 lines of actual code!**
### Next Steps with EZ Tier
**Add a vertex buffer:**
```rust
let vertices = vec![
Vertex { pos: [0.0, -0.5], color: [1.0, 0.0, 0.0] },
Vertex { pos: [0.5, 0.5], color: [0.0, 1.0, 0.0] },
Vertex { pos: [-0.5, 0.5], color: [0.0, 0.0, 1.0] },
];
let buffer = renderer.create_vertex_buffer(&vertices)?;
```
**Add a texture:**
```rust
let texture = renderer.create_texture(256, 256, Format::R8G8B8A8_UNORM)?;
```
**Add a compute shader:**
```rust
let compute = renderer.quick_compute(COMPUTE_SHADER)?;
renderer.dispatch_compute(compute, 256, 1, 1)?;
```
📚 **See:** `demos/ez/` for complete examples
---
## ⭐ EX Tier: Production-Ready in 100 Lines
When you need explicit control with ergonomic APIs:
```rust
use shdrlib::{
core::ShaderStage,
ex::{RuntimeManager, RuntimeConfig, ShaderManager, PipelineBuilder},
};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Setup - replaces 80+ lines of CORE tier code
let mut runtime = RuntimeManager::new(RuntimeConfig::default())?;
let device = runtime.device();
// Compile shaders - replaces 30+ lines
let mut shaders = ShaderManager::new(device)?;
let vert_id = shaders.add_shader(
VERTEX_SHADER,
ShaderStage::Vertex,
"main_vert"
)?;
let frag_id = shaders.add_shader(
FRAGMENT_SHADER,
ShaderStage::Fragment,
"main_frag"
)?;
// Build pipeline - replaces 50+ lines
let pipeline_id = shaders.build_pipeline(
PipelineBuilder::new()
.vertex_shader(shaders.get_shader(vert_id)?.handle(), "main")
.fragment_shader(shaders.get_shader(frag_id)?.handle(), "main")
.color_attachment_formats(vec![ash::vk::Format::R8G8B8A8_UNORM])
.viewport(0.0, 0.0, 800.0, 600.0)
.scissor(0, 0, 800, 600),
"triangle_pipeline"
)?;
// Render loop
loop {
let frame = runtime.begin_frame()?;
// Record commands
let cmd = frame.command_buffer;
// ... use pipeline ...
runtime.end_frame(&Default::default())?;
}
Ok(())
}
```
**What's different from EZ?**
- **Explicit configuration** - You control every detail
- **Type-safe IDs** - ShaderId, PipelineId prevent mistakes
- **Zero-cost** - Compiles to same code as CORE tier
- **Production-ready** - Used in real applications
### Next Steps with EX Tier
**Create buffers with helpers:**
```rust
use shdrlib::ex::helpers::*;
let vertex_buffer = create_vertex_buffer(&device, &vertices, "vertices")?;
let uniform_buffer = create_uniform_buffer::<CameraData>(&device, "camera")?;
```
**Load textures:**
```rust
let texture = create_texture(
&device,
256, 256,
Format::R8G8B8A8_UNORM,
"my_texture"
)?;
```
**Configure descriptors:**
```rust
use shdrlib::ex::helpers::descriptor::*;
let layout = DescriptorLayoutBuilder::new()
.add_binding(0, DescriptorType::UNIFORM_BUFFER, ShaderStageFlags::VERTEX)
.add_binding(1, DescriptorType::COMBINED_IMAGE_SAMPLER, ShaderStageFlags::FRAGMENT)
.build(&device)?;
```
📚 **See:** `demos/ex/` for complete examples and `docs/guides/ex-tier-guide.md`
---
## 🔧 CORE Tier: Maximum Control
When you need direct Vulkan access:
```rust
use shdrlib::core::*;
use ash::vk;
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Manual instance creation
let entry = ash::Entry::linked();
let instance = Instance::new(
&entry,
&InstanceCreateInfo {
app_name: "My App",
app_version: vk::make_api_version(0, 1, 0, 0),
api_version: vk::API_VERSION_1_3,
..Default::default()
}
)?;
// Manual device selection and creation
let physical_device = /* ... select physical device ... */;
let device = Device::new(
&instance,
physical_device,
&DeviceCreateInfo {
// ... explicit configuration ...
}
)?;
// Manual shader compilation
let shader = Shader::from_glsl(
&device,
VERTEX_SHADER,
ShaderStage::Vertex
)?;
// Manual pipeline creation
let pipeline = Pipeline::new(
&device,
&PipelineCreateInfo {
// ... 50+ lines of configuration ...
}
)?;
// ... 400+ lines total ...
}
```
**Why use CORE?**
- **Building your own framework** on top of shdrlib
- **Learning Vulkan** in depth
- **Need control** over every detail
- **Integrating** with existing code
📚 **See:** `demos/core/` for complete examples and `docs/guides/core-tier-guide.md`
---
## Next Steps
### 📖 Read the Guides
- **New to Vulkan?** Start with `docs/getting-started/vulkan-basics.md`
- **Coming from OpenGL?** Read `docs/getting-started/opengl-migration.md`
- **Building an app?** Follow `docs/guides/ex-tier-guide.md`
### 🎨 Explore Examples
```bash
# EZ tier examples (learning)
cargo run --bin ez_01_hello_triangle
cargo run --bin ez_02_compute_multiply
# EX tier examples (production)
cargo run --bin ex_01_triangle_100_lines
cargo run --bin ex_03_textured_quad
# CORE tier examples (advanced)
cargo run --bin 01_triangle_raw
```
### 📚 API Documentation
```bash
cargo doc --open
```
### 🤝 Get Help
- Check the [FAQ](docs/getting-started/faq.md)
- Read the [Troubleshooting Guide](docs/getting-started/troubleshooting.md)
- Open a [GitHub Discussion](https://github.com/paulburnettjones-wq/shdrlib/discussions)
---
## Tier Comparison Quick Reference
| **Setup Code** | 1 line | 5-10 lines | 80+ lines |
| **Triangle Code** | ~30 lines | ~100 lines | ~400 lines |
| **Learning Curve** | Gentle | Moderate | Steep |
| **Flexibility** | Limited | High | Maximum |
| **Performance** | Fast | Fast | Fast |
| **Safety** | Foolproof | Safe | Manual |
| **Use Case** | Learning, prototypes | Production apps | Frameworks, engines |
**Remember:** You can mix tiers! Start with EZ, drop to EX for more control, and use CORE when you need it.
---
**Ready to dive deeper?** Continue to the [User Guide](docs/guides/README.md)