shdrlib 0.1.5

//! # CORE Tier (Tier 0) - Low-Level Vulkan Wrappers
//!
//! The CORE tier provides thin, ergonomic wrappers around `ash` (Vulkan bindings) and shader
//! compilation with minimal abstraction overhead. This tier is designed for maximum control
//! and zero-cost abstractions.
//!
//! ## Philosophy
//!
//! - **Sterile**: No hidden state or side effects
//! - **Persistent**: Consistent behavior with compile-time guarantees
//! - **Contained**: Clear boundaries and well-defined responsibilities
//! - **Explicit**: Manual lifetime management for maximum control
//! - **Zero-cost**: Compiles to identical machine code as raw Vulkan
//!
//! ## Key Components
//!
//! The CORE tier consists of 12 modules covering all Vulkan fundamentals:
//!
//! | Module | Purpose |
//! |--------|---------|
//! | `instance` | Vulkan instance creation and management |
//! | `device` | Logical and physical device management |
//! | `queue` | Command queue operations |
//! | `command` | Command buffer allocation and recording |
//! | `shader` | GLSL→SPIR-V compilation via naga (pure Rust!) |
//! | `pipeline` | Graphics and compute pipeline creation |
//! | `memory` | Buffer and image allocation |
//! | `descriptor` | Descriptor sets, pools, and layouts |
//! | `sync` | Fences and semaphores |
//! | `surface` | Window surface management (headless support) |
//! | `swapchain` | Swapchain creation and presentation |
//! | `utils` | Helper utilities |
//!
//! ## Safety Considerations
//!
//! **⚠️ WARNING**: CORE objects do NOT enforce lifetime dependencies or resource ordering.
//!
//! While this tier uses safe Rust, it can still cause undefined behavior if misused:
//! - Creating a `Pipeline` after dropping the `Device` → UB
//! - Using a `CommandBuffer` after dropping the `CommandPool` → UB
//! - Recording commands after dropping referenced resources → UB
//!
//! **Users must manually ensure correct drop order**. For automatic safety guarantees,
//! use the EX tier (`RuntimeManager` and `ShaderManager`).
//!
//! ## Usage Example
//!
//! ```rust,no_run
//! use shdrlib::core::*;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Direct Vulkan control - you manage everything
//! let instance = Instance::new(InstanceCreateInfo::default())?;
//! let physical_devices = instance.enumerate_physical_devices()?;
//! let device = Device::new(&instance, physical_devices[0], DeviceCreateInfo::default())?;
//! let shader = Shader::from_glsl(&device, VERTEX_SRC, ShaderStage::Vertex, "main")?;
//!
//! // You must ensure correct drop order:
//! // shader drops before device, device before instance
//! # const VERTEX_SRC: &str = "#version 450\nvoid main() {}";
//! # Ok(())
//! # }
//! ```
//!
//! ## When to Use CORE
//!
//! **Use CORE when:**
//! - Building your own rendering framework or engine
//! - Need absolute control over every Vulkan object
//! - Implementing custom resource management strategies
//! - Performance profiling requires minimal abstraction
//! - Integrating with existing Vulkan codebases
//!
//! **Don't use CORE when:**
//! - Building applications or games (most of the time use EX tier instead)
//! - Want automatic lifetime management (use EX tier)
//! - Learning Vulkan basics (use EZ tier when available)
//! - Safety guarantees are a priority (use EX tier)

pub mod command;
pub mod descriptor;
pub mod device;
pub mod instance;
pub mod memory;
pub mod pipeline;
pub mod queue;
pub mod shader;
pub mod surface;
pub mod swapchain;
pub mod sync;
pub mod utils;

// Re-export commonly used types
pub use command::{CommandBuffer, CommandBufferError, CommandPool, CommandPoolError};
pub use descriptor::{
    update_descriptor_sets, DescriptorError, DescriptorPool, DescriptorPoolError,
    DescriptorResource, DescriptorSet, DescriptorSetLayout, DescriptorWrite,
};
pub use device::{Device, DeviceCreateInfo, DeviceError, PhysicalDeviceInfo, QueueCreateInfo};
pub use instance::{Instance, InstanceCreateInfo, InstanceError};
pub use memory::{Buffer, Image, MemoryError};
pub use pipeline::{Pipeline, PipelineBuilder, PipelineError, PipelineLayout};
pub use queue::{Queue, QueueError};
pub use shader::{Shader, ShaderCompiler, ShaderError, ShaderReflection, ShaderStage};
pub use surface::{Surface, SurfaceError};
pub use swapchain::{Swapchain, SwapchainError};
pub use sync::{Fence, FenceError, Semaphore, SemaphoreError};