kronos_compute/api/
mod.rs

1//! Unified Safe API for Kronos Compute
2//! 
3//! This module provides a safe, ergonomic Rust API that wraps the low-level
4//! Vulkan-style FFI interface. All Kronos optimizations (persistent descriptors,
5//! smart barriers, timeline batching, and pool allocation) work transparently.
6
7use crate::core::*;
8use crate::sys::*;
9use crate::ffi::VkResult;
10use crate::implementation;
11use thiserror::Error;
12
13pub mod context;
14pub mod buffer;
15pub mod pipeline;
16pub mod command;
17pub mod sync;
18
19#[cfg(test)]
20mod tests;
21
22pub use context::ComputeContext;
23pub use buffer::{Buffer, BufferUsage};
24pub use pipeline::{Pipeline, Shader, PipelineConfig, BufferBinding};
25pub use command::CommandBuilder;
26pub use sync::{Fence, Semaphore};
27
28/// Result type for the unified API
29pub type Result<T> = std::result::Result<T, KronosError>;
30
31/// Unified API errors
32#[derive(Error, Debug)]
33pub enum KronosError {
34    #[error("Initialization failed: {0}")]
35    InitializationFailed(String),
36    
37    #[error("Device not found")]
38    DeviceNotFound,
39    
40    #[error("Shader compilation failed: {0}")]
41    ShaderCompilationFailed(String),
42    
43    #[error("Buffer creation failed: {0}")]
44    BufferCreationFailed(String),
45    
46    #[error("Command execution failed: {0}")]
47    CommandExecutionFailed(String),
48    
49    #[error("Synchronization error: {0}")]
50    SynchronizationError(String),
51    
52    #[error("Vulkan error: {0:?}")]
53    VulkanError(VkResult),
54    
55    #[error("Implementation error: {0}")]
56    ImplementationError(#[from] implementation::error::IcdError),
57}
58
59impl From<VkResult> for KronosError {
60    fn from(result: VkResult) -> Self {
61        KronosError::VulkanError(result)
62    }
63}
64
65/// Configuration for ComputeContext creation
66#[derive(Default)]
67pub struct ContextConfig {
68    /// Application name
69    pub app_name: String,
70    /// Enable validation layers
71    pub enable_validation: bool,
72    /// Preferred GPU vendor (AMD, NVIDIA, Intel)
73    pub preferred_vendor: Option<String>,
74    /// Preferred ICD by path (only works in aggregated mode or before first initialization)
75    pub preferred_icd_path: Option<std::path::PathBuf>,
76    /// Preferred ICD by index (only works in aggregated mode or before first initialization)
77    pub preferred_icd_index: Option<usize>,
78}
79
80/// Builder for ComputeContext
81pub struct ContextBuilder {
82    config: ContextConfig,
83}
84
85impl ContextBuilder {
86    pub fn new() -> Self {
87        Self {
88            config: ContextConfig::default(),
89        }
90    }
91    
92    pub fn app_name(mut self, name: impl Into<String>) -> Self {
93        self.config.app_name = name.into();
94        self
95    }
96    
97    pub fn enable_validation(mut self) -> Self {
98        self.config.enable_validation = true;
99        self
100    }
101    
102    pub fn prefer_vendor(mut self, vendor: impl Into<String>) -> Self {
103        self.config.preferred_vendor = Some(vendor.into());
104        self
105    }
106    
107    /// Prefer a specific ICD by its resolved library path
108    pub fn prefer_icd_path<P: Into<std::path::PathBuf>>(mut self, path: P) -> Self {
109        self.config.preferred_icd_path = Some(path.into());
110        self
111    }
112    
113    /// Prefer a specific ICD by index (from available_icds())
114    pub fn prefer_icd_index(mut self, index: usize) -> Self {
115        self.config.preferred_icd_index = Some(index);
116        self
117    }
118    
119    pub fn build(self) -> Result<ComputeContext> {
120        ComputeContext::new_with_config(self.config)
121    }
122}
123
124/// Entry point for the unified API
125/// 
126/// Example:
127/// ```no_run
128/// use kronos_compute::api;
129/// 
130/// let ctx = api::ComputeContext::builder()
131///     .app_name("My Compute App")
132///     .enable_validation()
133///     .build()?;
134/// ```
135impl ComputeContext {
136    /// Create a new ComputeContext with default settings
137    pub fn new() -> Result<Self> {
138        Self::builder().build()
139    }
140    
141    /// Create a builder for customized context creation
142    pub fn builder() -> ContextBuilder {
143        ContextBuilder::new()
144    }
145}
kronos_compute/api/mod.rs

kronos_compute/api/
mod.rs
