shdrlib 0.1.5

A three-tiered Vulkan shader compilation and rendering framework built in pure Rust
Documentation 
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

//! # EX Tier (Tier 1) - Explicit Control with Ergonomic Managers
//!
//! The EX (Explicit) tier provides memory-safe, ergonomic managers built on CORE tier
//! primitives. This tier achieves significant code reduction while maintaining explicit
//! configuration control and zero-cost abstractions.
//!
//! ## Philosophy
//!
//! - **Safe**: Automatic resource cleanup through Rust's ownership system
//! - **Explicit**: All configuration is visible with no hidden behavior
//! - **Flexible**: Access CORE tier directly when needed
//! - **Ergonomic**: Fluent APIs and helper functions reduce boilerplate
//! - **Zero-cost**: Abstractions compile to direct Vulkan calls
//!
//! ## Key Components
//!
//! The EX tier provides three core managers and helper modules:
//!
//! ### Core Managers
//!
//! | Component | Purpose |
//! |-----------|---------|
//! | `RuntimeManager` | Instance, device, queue, sync, and command management |
//! | `ShaderManager` | Shader compilation, reflection, and pipeline creation |
//! | `PipelineBuilder` | Fluent graphics pipeline configuration |
//!
//! ### Helper Modules
//!
//! | Module | Purpose |
//! |--------|---------|
//! | `helpers::buffer` | Buffer creation with automatic cleanup |
//! | `helpers::image` | Image and texture creation with automatic cleanup |
//! | `helpers::descriptor` | Descriptor layouts, pools, and updates |
//!
//! ### Resource Wrappers
//!
//! | Type | Purpose |
//! |------|---------|
//! | `ExBuffer` | Buffer with automatic cleanup |
//! | `ExImage` | Image with automatic cleanup |
//! | `ExDescriptorSetLayout` | Descriptor set layout with automatic cleanup |
//! | `ExDescriptorPool` | Descriptor pool with automatic cleanup |
//!
//! ## Code Reduction
//!
//! EX tier provides significant code reduction compared to CORE tier:
//!
//! - **Triangle**: 400 lines to 100 lines (4x reduction)
//! - **Textured Quad**: 450 lines to 55 lines (8x reduction)
//! - **Buffer Creation**: 30 lines to 1 line (30x reduction)
//! - **Descriptor Sets**: 150 lines to 20 lines (7.5x reduction)
//!
//! ## Usage Example
//!
//! ```rust,no_run
//! use shdrlib::ex::*;
//! use shdrlib::core::ShaderStage;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Setup
//! let mut runtime = RuntimeManager::new(RuntimeConfig::default())?;
//! let device = runtime.device();
//! let mut shaders = ShaderManager::new(device)?;
//!
//! // Load shaders
//! let vert_id = shaders.add_shader(VERTEX_SHADER, ShaderStage::Vertex, "triangle_vert")?;
//! let frag_id = shaders.add_shader(FRAGMENT_SHADER, ShaderStage::Fragment, "triangle_frag")?;
//!
//! // Build pipeline
//! 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]),
//!     "triangle_pipeline"
//! )?;
//!
//! // Resources are automatically cleaned up
//! # Ok(())
//! # }
//! # const VERTEX_SHADER: &str = "#version 450\nvoid main() {}";
//! # const FRAGMENT_SHADER: &str = "#version 450\nvoid main() {}";
//! ```
//!
//! ## When to Use EX
//!
//! **Use EX tier when:**
//! - Building production applications, games, or rendering tools
//! - You need explicit configuration control with safety guarantees
//! - You want significant code reduction while maintaining flexibility
//! - You require automatic resource management
//! - You need zero-cost abstractions
//!
//! **Use a different tier when:**
//! - You need complete low-level control (use CORE tier)
//! - You want the simplest possible API (use EZ tier)
//! - You're building a custom framework with different patterns (use CORE tier)

mod errors;
pub mod helpers;
mod pipeline_builder;
mod resources;
mod runtime_manager;
mod shader_manager;

pub use errors::{PipelineError, PipelineId, RuntimeError, ShaderId, ShaderManagerError};
pub use helpers::*;
pub use pipeline_builder::PipelineBuilder;
pub use resources::{ExBuffer, ExDescriptorPool, ExDescriptorSetLayout, ExImage};
pub use runtime_manager::{FrameContext, RuntimeConfig, RuntimeManager, SubmitInfo};
pub use shader_manager::ShaderManager;

// Re-export CORE for dropping down when needed
pub use crate::core;