rill_core/
prelude.rs

1//! # Rill Core Prelude
2//!
3//! This module re-exports the most commonly used types and traits from rill-core.
4//! Import it with `use rill_core::prelude::*;` to get access to all essential
5//! items for working with the Rill ecosystem.
6//!
7//! ## What's included
8//!
9//! - Parameter handling (`ParameterId`, `ParamValue`, `ParamType`)
10//! - Time and clock (`ClockTick`, `ClockSource`, `SystemClock`)
11//! - Error types (`ProcessResult`, `ProcessError`, etc.)
12//! - Buffer types (`PipeBuffer`, `FanOutBuffer`, `DelayLine`, `RingBuffer`)
13//! - Atomic types (`AtomicCell`, `AtomicStats`)
14//! - Math abstractions (`Transcendental`)
15//! - Constants (`DEFAULT_BLOCK_SIZE`, `MAX_SAMPLE_RATE`, etc.)
16//!
17//! ## Example
18//!
19//! ```rust
20//! use rill_core::prelude::*;
21//!
22//! let param = ParameterId::new("gain").unwrap();
23//! let ctx = RenderContext::new(0, 64, 44100.0);
24//! let tick = ClockTick::new(0, 64, 44100.0, "main".to_string());
25//! ```
26
27// ============================================================================
28// Core Traits
29// ============================================================================
30
31pub use crate::traits::{
32    Algorithm, AlgorithmCategory, AlgorithmMetadata, IntoParamValue, ParamMetadata, ParamRange,
33    ParamType, ParamValue, ParameterError, ParameterId, ParameterResult, Params, ProcessError,
34    ProcessResult,
35};
36
37// ============================================================================
38// Time and Clock
39// ============================================================================
40
41pub use crate::time::{ClockSource, ClockTick, RenderContext, SystemClock, TimeError, TimeResult};
42
43// ============================================================================
44// Math Abstractions
45// ============================================================================
46
47pub use crate::interpolate::Interpolate;
48
49pub use crate::math::Transcendental;
50
51// ============================================================================
52// Vector Types (SIMD abstractions)
53// ============================================================================
54
55pub use crate::math::vector::complex::{ComplexSoa, ComplexVector};
56pub use crate::math::vector::math::{
57    abs_slice, clamp_slice, cos_slice, exp_slice, ln_slice, max_slice, min_slice, sin_slice,
58    sqrt_slice, tan_slice,
59};
60pub use crate::math::vector::ops::{
61    add_scalar_slice, add_slices, div_slices, mul_scalar_slice, mul_slices, sub_slices, SliceMut,
62    SlicePair,
63};
64pub use crate::math::vector::scalar::{ScalarVector1, ScalarVector2, ScalarVector4, ScalarVector8};
65#[cfg(feature = "simd")]
66pub use crate::math::vector::simd::*;
67pub use crate::math::vector::traits::{
68    Vector, VectorMask, VectorReduce, VectorScalarOps, VectorTranscendental,
69};
70
71// ============================================================================
72// Matrix & Vector (glam)
73// ============================================================================
74
75pub use glam::{mat2, mat3, mat4, vec2, vec3, vec4, Mat2, Mat3, Mat4, Vec2, Vec3, Vec4};
76
77// ============================================================================
78// Buffer Types
79// ============================================================================
80
81pub use crate::buffer::{
82    // Utility functions
83    utils,
84    // Atomic types
85    AtomicCell,
86    AtomicCellError,
87    AtomicStats,
88
89    // Core buffer trait (unified Buffer replaces old Buffer + SignalBuffer)
90    Buffer,
91
92    // Error types
93    BufferError,
94    BufferResult,
95
96    // Statistics
97    BufferStats,
98
99    DelayLine,
100    FanInBuffer,
101    FanOutBuffer,
102    // Buffer implementations
103    PipeBuffer,
104    RingBuffer,
105};
106
107// ============================================================================
108// Queue Types (from rill-patchbay integration)
109// ============================================================================
110
111pub use crate::queues::{QueueError, QueueResult, TelemetryBlock};
112
113// ============================================================================
114// Constants
115// ============================================================================
116
117pub use crate::{
118    // Cache line alignment
119    CACHE_LINE_SIZE,
120    // Block sizes
121    DEFAULT_BLOCK_SIZE,
122    // Buffer sizes
123    DEFAULT_BUFFER_SIZE,
124    DEFAULT_SAMPLE_RATE,
125
126    MAX_BLOCK_SIZE,
127    MAX_BUFFER_SIZE,
128    // Sample rates
129    MAX_SAMPLE_RATE,
130    MIN_BLOCK_SIZE,
131
132    MIN_BUFFER_SIZE,
133
134    MIN_SAMPLE_RATE,
135    // Version
136    VERSION,
137};
138
139// ============================================================================
140// Common Type Aliases
141// ============================================================================
142
143/// Default sample type (32-bit float)
144pub type Sample = f32;
145
146/// Mono signal block type
147pub type MonoBlock<T, const N: usize> = [T; N];
148
149/// Stereo signal block type (left, right)
150pub type StereoBlock<T, const N: usize> = [MonoBlock<T, N>; 2];
151
152/// Control signal value type
153pub type ControlValue<T> = T;
154
155/// Default pipe buffer with f32 samples
156pub type DefaultPipeBuffer<const N: usize = DEFAULT_BLOCK_SIZE> = PipeBuffer<Sample, N>;
157
158/// Default delay line with f32 samples
159pub type DefaultDelayLine<const MAX_DELAY: usize> = DelayLine<Sample, MAX_DELAY>;
160
161/// Default ring buffer with f32 samples
162pub type DefaultRingBuffer<const N: usize> = RingBuffer<Sample, N>;
163
164/// Default system clock
165pub type DefaultClock = SystemClock;
166
167// ============================================================================
168// Specialized Preludes for Different Use Cases
169// ============================================================================
170
171/// Prelude for working with f32 samples (common case)
172pub mod f32_prelude {
173    use crate::buffer::{DelayLine, FanInBuffer, FanOutBuffer, PipeBuffer, RingBuffer};
174
175    /// Pipe buffer with f32 samples
176    pub type PipeBufferF32<const N: usize> = PipeBuffer<f32, N>;
177
178    /// Fan-out buffer with f32 samples
179    pub type FanOutBufferF32<const N: usize, const CONSUMERS: usize> =
180        FanOutBuffer<f32, N, CONSUMERS>;
181
182    /// Fan-in buffer with f32 samples
183    pub type FanInBufferF32<const N: usize, const PRODUCERS: usize> =
184        FanInBuffer<f32, N, PRODUCERS>;
185
186    /// Delay line with f32 samples
187    pub type DelayLineF32<const MAX_DELAY: usize> = DelayLine<f32, MAX_DELAY>;
188
189    /// Ring buffer with f32 samples
190    pub type RingBufferF32<const N: usize> = RingBuffer<f32, N>;
191
192    /// System clock for f32 (same as default)
193    pub type SystemClockF32 = crate::time::SystemClock;
194
195    pub use crate::math::Transcendental;
196}
197
198/// Prelude for working with f64 samples (high precision)
199pub mod f64_prelude {
200    use crate::buffer::{DelayLine, FanInBuffer, FanOutBuffer, PipeBuffer, RingBuffer};
201
202    /// Pipe buffer with f64 samples
203    pub type PipeBufferF64<const N: usize> = PipeBuffer<f64, N>;
204
205    /// Fan-out buffer with f64 samples
206    pub type FanOutBufferF64<const N: usize, const CONSUMERS: usize> =
207        FanOutBuffer<f64, N, CONSUMERS>;
208
209    /// Fan-in buffer with f64 samples
210    pub type FanInBufferF64<const N: usize, const PRODUCERS: usize> =
211        FanInBuffer<f64, N, PRODUCERS>;
212
213    /// Delay line with f64 samples
214    pub type DelayLineF64<const MAX_DELAY: usize> = DelayLine<f64, MAX_DELAY>;
215
216    /// Ring buffer with f64 samples
217    pub type RingBufferF64<const N: usize> = RingBuffer<f64, N>;
218
219    /// System clock for f64 (same as default)
220    pub type SystemClockF64 = crate::time::SystemClock;
221
222    pub use crate::math::Transcendental;
223}
224
225/// Prelude for working with time
226pub mod time_prelude {
227    pub use crate::time::{
228        ClockSource, ClockTick, RenderContext, SystemClock, TimeError, TimeResult,
229    };
230}
231
232/// Prelude for working with buffers
233pub mod buffer_prelude {
234    pub use crate::buffer::{
235        utils, AtomicCell, AtomicStats, Buffer, BufferError, BufferResult, BufferStats, DelayLine,
236        FanInBuffer, FanOutBuffer, PipeBuffer, RingBuffer,
237    };
238}
239
240/// Prelude for working with queues (automation)
241pub mod queue_prelude {
242    pub use crate::queues::{QueueError, QueueResult};
243}
244
245/// Prelude for working with parameters
246pub mod param_prelude {
247    pub use crate::traits::{
248        IntoParamValue, ParamMetadata, ParamRange, ParamType, ParamValue, ParameterError,
249        ParameterId, ParameterResult,
250    };
251}
252
253// ============================================================================
254// Re-export of commonly used items from other crates
255// ============================================================================
256
257/// Common third-party types that are frequently used with Rill
258pub mod external {
259    pub use std::f32::consts::PI;
260    pub use std::f64::consts::PI as PI_F64;
261}
262
263// ============================================================================
264// Tests
265// ============================================================================
266
267#[cfg(test)]
268mod tests {
269    use super::*;
270
271    #[test]
272    fn test_prelude_imports() {
273        let _param_id = ParameterId::new("test").unwrap();
274        let _clock = SystemClock::with_sample_rate(44100.0);
275        let _tick = ClockTick::new(0, 64, 44100.0, "test".to_string());
276
277        // Test buffer creation
278        let _pipe = PipeBuffer::<f32, 64>::new();
279        let _delay = DelayLine::<f32, 1024>::new(44100.0);
280        let _ring = RingBuffer::<f32, 256>::new();
281
282        // Test atomic cell
283        let _cell = AtomicCell::new(42);
284    }
285
286    #[test]
287    fn test_type_aliases() {
288        let _pipe = DefaultPipeBuffer::<64>::new();
289        let _delay = DefaultDelayLine::<1024>::new(44100.0);
290        let _ring = DefaultRingBuffer::<256>::new();
291        let _clock = DefaultClock::with_sample_rate(44100.0);
292    }
293
294    #[test]
295    fn test_f32_prelude() {
296        use f32_prelude::*;
297
298        let _pipe = PipeBufferF32::<64>::new();
299        let _fan_out = FanOutBufferF32::<64, 4>::new();
300        let _fan_in = FanInBufferF32::<64, 2>::new();
301        let _delay = DelayLineF32::<1024>::new(44100.0);
302        let _ring = RingBufferF32::<256>::new();
303        let _clock = SystemClockF32::with_sample_rate(44100.0);
304    }
305
306    #[test]
307    fn test_f64_prelude() {
308        use f64_prelude::*;
309
310        let _pipe = PipeBufferF64::<64>::new();
311        let _fan_out = FanOutBufferF64::<64, 4>::new();
312        let _fan_in = FanInBufferF64::<64, 2>::new();
313        let _delay = DelayLineF64::<1024>::new(44100.0);
314        let _ring = RingBufferF64::<256>::new();
315        let _clock = SystemClockF64::with_sample_rate(44100.0);
316    }
317
318    #[test]
319    fn test_time_prelude() {
320        use time_prelude::*;
321
322        let mut clock = SystemClock::with_sample_rate(44100.0);
323        let tick = clock.next_tick(64);
324        let _pos = tick.absolute_seconds();
325    }
326
327    #[test]
328    fn test_buffer_prelude() {
329        use buffer_prelude::*;
330
331        let buffer = PipeBuffer::<f32, 64>::new();
332        let stats = buffer.stats();
333        let _fill = stats.fill_level;
334    }
335
336    #[test]
337    fn test_param_prelude() {
338        use param_prelude::*;
339
340        let _id = ParameterId::new("gain").unwrap();
341        let value = ParamValue::Float(0.5);
342        let _type = value.param_type();
343    }
344
345    #[test]
346    fn test_constants() {
347        assert_eq!(DEFAULT_BLOCK_SIZE, 64);
348        assert_eq!(MAX_SAMPLE_RATE, 384_000.0);
349        assert_eq!(MIN_SAMPLE_RATE, 8_000.0);
350        assert_eq!(CACHE_LINE_SIZE, 64);
351    }
352
353    #[test]
354    fn test_into_param_value() {
355        let f: f32 = 42.0;
356        let pv = f.into_param_value();
357        assert_eq!(pv.as_f32(), Some(42.0));
358
359        let i: i32 = 42;
360        let pv = i.into_param_value();
361        assert_eq!(pv.as_i32(), Some(42));
362
363        let b = true;
364        let pv = b.into_param_value();
365        assert_eq!(pv.as_bool(), Some(true));
366    }
367}
rill_core/prelude.rs

rill_core/
prelude.rs
