shdrlib

Three-tier Vulkan rendering in pure Rust. Choose your abstraction.

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

[dependencies]

shdrlib = "0.1.2"

ash = "0.38"

EZ Tier - 30 Lines

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

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)

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

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

# EZ tier (learning)

cargo run --bin ez_01_hello_triangle


# 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 - Rust ownership prevents use-after-free
• Flexible - Drop to lower tiers anytime for more control

Documentation

• Quick Start - Triangle in 5 minutes
• User Guide - Full documentation
• API Docs - Or run cargo doc --open
• Examples - Working code for all tiers

Requirements

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

Status

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 for guidelines.

Getting Started: cargo add shdrlib ash and see QUICKSTART.md