# Quick Start
Get rendering in 5 minutes.
## Installation
```toml
[dependencies]
shdrlib = "0.1"
ash = "0.38"
```
## Choose Your Tier
| **EZ** | Learning, prototypes | ~30 | 5 min |
| **EX** (recommended) | Production apps | ~100 | 15 min |
| **CORE** | Frameworks, engines | ~400 | 60+ min |
---
## 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, FRAGMENT)?;
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: &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: &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
```
You have now rendered a triangle with Vulkan.
### Add Buffers
```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 Compute
```rust
let compute = renderer.quick_compute(COMPUTE_GLSL)?;
renderer.dispatch_compute(compute, 256, 1, 1)?;
```
**More:** See `demos/ez/`
---
## EX Tier: Production-Ready
```rust
use shdrlib::{core::ShaderStage, ex::*};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Setup (replaces 80+ lines of CORE code)
let mut runtime = RuntimeManager::new(RuntimeConfig::default())?;
let device = runtime.device();
// Compile shaders
let mut shaders = ShaderManager::new(device)?;
let vert = shaders.add_shader(VERTEX, ShaderStage::Vertex, "vert")?;
let frag = shaders.add_shader(FRAGMENT, ShaderStage::Fragment, "frag")?;
// Build pipeline
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![Format::R8G8B8A8_UNORM])
.viewport(0.0, 0.0, 800.0, 600.0)
.scissor(0, 0, 800, 600),
"triangle"
)?;
// Render loop
loop {
let frame = runtime.begin_frame()?;
let cmd = frame.command_buffer;
// Record commands
cmd.begin(device.handle(), CommandBufferUsageFlags::ONE_TIME_SUBMIT)?;
cmd.bind_pipeline(device.handle(), PipelineBindPoint::GRAPHICS,
shaders.get_pipeline(pipeline)?.handle());
cmd.draw(device.handle(), 3, 1, 0, 0);
cmd.end(device.handle())?;
runtime.end_frame(&SubmitInfo {
command_buffers: vec![cmd.handle()],
..Default::default()
})?;
}
}
```
### With Helpers
```rust
use shdrlib::ex::helpers::*;
// Buffers
let vbuf = create_vertex_buffer(&device, &vertices)?;
let ubuf = create_uniform_buffer::<CameraData>(&device)?;
// Textures
let tex = create_texture(&device, 256, 256, Format::R8G8B8A8_UNORM)?;
// Descriptors
let layout = DescriptorLayoutBuilder::new()
.add_binding(0, DescriptorType::UNIFORM_BUFFER, ShaderStageFlags::VERTEX)
.add_binding(1, DescriptorType::COMBINED_IMAGE_SAMPLER, ShaderStageFlags::FRAGMENT)
.build(&device)?;
```
**More:** See `demos/ex/` and `docs/guides/ex-tier-guide.md`
---
## CORE Tier: Maximum Control
```rust
use shdrlib::core::*;
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Manual instance
let entry = ash::Entry::linked();
let instance = Instance::new(&entry, &InstanceCreateInfo {
app_name: "My App",
api_version: vk::API_VERSION_1_3,
..Default::default()
})?;
// Manual device selection
let physical_devices = instance.enumerate_physical_devices()?;
let device = Device::new(&instance, physical_devices[0], &DeviceCreateInfo {
queue_families: vec![QueueCreateInfo { /* ... */ }],
extensions: vec!["VK_KHR_swapchain".into()],
..Default::default()
})?;
// Manual shader compilation
let shader = Shader::from_glsl(&device, VERTEX, ShaderStage::Vertex)?;
// Manual pipeline (50+ lines of config)
let pipeline = Pipeline::new(&device, &PipelineCreateInfo {
// ... explicit configuration ...
})?;
// ... 400+ total lines ...
}
```
**Why CORE?**
- Building your own framework
- Learning Vulkan internals
- Need absolute control
- Integrating with existing code
**More:** See `demos/core/` and `docs/guides/core-tier-guide.md`
---
## Next Steps
### Run Examples
```bash
# EZ tier
cargo run --bin ez_01_hello_triangle
cargo run --bin ez_02_compute_multiply
# EX tier (recommended)
cargo run --bin ex_01_triangle_100_lines
cargo run --bin ex_03_textured_quad
# CORE tier
cargo run --bin 01_triangle_raw
cargo run --bin 02_compute_shader
```
### Read Guides
- **New to Vulkan?** → [Vulkan Basics](docs/getting-started/vulkan-basics.md)
- **Building an app?** → [EX Tier Guide](docs/guides/ex-tier-guide.md)
- **Learning?** → [EZ Tier Guide](docs/guides/ez-tier-guide.md)
### API Docs
```bash
cargo doc --open
```
### Get Help
- [FAQ](docs/getting-started/faq.md)
- [Troubleshooting](docs/getting-started/troubleshooting.md)
- [GitHub Discussions](https://github.com/paulburnettjones-wq/shdrlib/discussions)
---
## Tier Comparison
| 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 |
Note: You can mix tiers freely. Start with EZ, then drop to EX/CORE when more control is needed.
---
**Continue to:** [Full User Guide](docs/README.md)