ash_renderer 0.2.5

Production-quality Vulkan renderer in Rust using ASH - ECS-free, pure rendering engine
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# ASH Renderer


[![Crates.io](https://img.shields.io/crates/v/ash_renderer.svg)](https://crates.io/crates/ash_renderer)
[![Documentation](https://docs.rs/ash_renderer/badge.svg)](https://docs.rs/ash_renderer)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![CI](https://github.com/saptak7777/Ash-Renderer/actions/workflows/ci.yml/badge.svg)](https://github.com/saptak7777/Ash-Renderer/actions)

A **production-read Vulkan renderer** built with [ASH](https://github.com/ash-rs/ash) and [VMA](https://github.com/gwihlern-gp/vk-mem-rs).
Designed for high-performance games and graphics applications, featuring ECS-independence and deep GPU optimization.

## ✨ Features (v0.2.5)


> [!IMPORTANT]
> **Release 0.2.5** improves shader loading safety by fixing memory alignment issues that could cause crashes on some platforms. It also includes troubleshooting steps for common runtime errors.

### Check out what's new!

- **🔒 Safer Shader Loading**: Fixed potential undefined behavior when loading embedded SPIR-V shaders.
- **🛠️ Troubleshooting Guide**: Added documentation for resolving common runtime crashes (`0xc000041d`).

### Check out what's new!

- **🔒 Safer Shader Loading**: Fixed potential undefined behavior when loading embedded SPIR-V shaders.
- **🛠️ Troubleshooting Guide**: Added documentation for resolving common runtime crashes (`0xc000041d`).
- **🎨 Bindless Texturing**: Fully dynamic texture access using `descriptor_indexing`. Supports thousands of textures with zero binding overhead.
- **🖥️ Headless Support**: Run heavy rendering workloads or benchmarks on CI without a window (virtual swapchain).
- **🌑 Advanced Shadows**: Cascaded Shadow Maps (CSM) with PCF filtering and light culling.

### Core Capabilities

- **PBR Materials**: Metallic/Roughness workflow with texture mapping.
- **Post-Processing**: Integrated Bloom, Tonemapping (ACES), and TAA.
- **GPU Profiling**: Built-in Diagnostics Overlay and timestamp queries.
- **Hot-Reloading**: Detects shader changes at runtime (experimental).
- **Cross-Platform**: Runs on **Windows** (Win32), **Linux** (X11/Wayland), and **macOS** (Metal) via a unified `SurfaceProvider`.

## 🚀 Quick Start


Add to your `Cargo.toml`:

```toml
[dependencies]
ash_renderer = "0.2.5"
winit = "0.30"
glam = "0.30"
```

### Initialization


```rust
use ash_renderer::{Renderer, WindowSurfaceProvider};
use winit::event_loop::EventLoop;

fn main() -> anyhow::Result<()> {
    let event_loop = EventLoop::new()?;
    let window = winit::window::Window::builder().build(&event_loop)?;
    
    // Create Renderer with cross-platform SurfaceProvider
    let surface_provider = WindowSurfaceProvider::new(&window, 800, 600);
    let mut renderer = Renderer::new(surface_provider)?;

    // Load assets...
    let mesh = Mesh::create_cube();
    renderer.set_mesh(mesh);

    // Render loop
    event_loop.run(move |event, _, control_flow| {
        // ... handling logic ...
        if let Event::MainEventsCleared = event {
            renderer.render_frame(view, projection, camera_pos).unwrap();
        }
    })?;
    Ok(())
}
```

## 🔌 Headless Benchmarking


Run graphics benchmarks in purely headless mode (no window required):

```rust
use ash_renderer::{Renderer, HeadlessSurfaceProvider};

// Initialize without winit/window
let provider = HeadlessSurfaceProvider::new(1920, 1080);
let mut renderer = Renderer::new(provider)?;

// Loop as fast as GPU allows (no VSync)
for _ in 0..1000 {
    renderer.render_frame(view, proj, cam_pos)?;
}
```

## 🛠️ Performance


| Metric | Target | Achieved (v0.2.5) |
|--------|--------|-------------------|
| Draw Calls (Bindless) | 10k+ | ✅ |
| Headless FPS | Unlocked | ✅ |
| Texture Switches | Zero Cost | ✅ |

## 📦 Feature Flags


| Feature | Description | Default |
|---------|-------------|---------|
| `validation` | Enables Vulkan Validation Layers | ✅ |
| `gltf_loading` | Support for loading .gltf/.glb models | ✅ |
| `profiling` | Enables GPU timestamp queries | ❌ |

## 📜 License


Licensed under Apache-2.0.

### Troubleshooting (Windows)

> [!WARNING]
> If you encounter `exit code: 0xc000041d` on Windows, this is a **Fatal User Callback Exception**.
> 
> Possible causes and fixes:
> 1. **Overlay interference**: Disable Discord/Steam/NVIDIA overlays.
> 2. **Driver Hooks**: Update GPU drivers or verify no other software hooks `vulkan-1.dll`.
> 3. **Validation Layers**: The application enables validation layers by default. If the crash persists, use `--no-default-features` (requires `gltf_loading`).