rill_core_dsp/generators/
mod.rs

1//! # Генераторы сигналов
2//!
3//! Этот модуль предоставляет различные генераторы для синтеза звука:
4//! - Базовые осцилляторы (Sine, Saw, Square, Triangle, Pulse)
5//! - Шумовые генераторы (White, Pink, Brown, Blue, Violet)
6//! - Огибающие (ADSR, AR, ASR)
7//! - LFO для модуляции
8//! - FM синтез
9//!
10//! Все генераторы реализуют общий трейт [`Generator`] и параметризованы
11//! типом `T: Transcendental` (f32 или f64).
12
13// Импортируем необходимые типы и трейты
14use crate::algorithm::{Algorithm, AlgorithmCategory, AlgorithmMetadata};
15use rill_core::Transcendental;
16
17// Объявляем подмодули
18mod basic;
19mod envelope;
20mod fm;
21mod lfo;
22mod noise;
23mod reader;
24mod sample_player;
25mod wavetable;
26
27// Реэкспортируем всё из подмодулей
28pub use basic::*;
29pub use envelope::*;
30pub use fm::*;
31pub use lfo::*;
32pub use noise::*;
33pub use reader::*;
34pub use sample_player::*;
35pub use wavetable::*;
36
37/// Базовый трейт для всех генераторов
38///
39/// Предоставляет основные методы управления генератором:
40/// - управление фазой
41/// - изменение частоты
42/// - изменение амплитуды
43pub trait Generator<T: Transcendental>: Algorithm<T> {
44    /// Получить текущую фазу (0.0 - 1.0)
45    fn phase(&self) -> T;
46
47    /// Установить фазу
48    fn set_phase(&mut self, phase: T);
49
50    /// Сбросить фазу в 0
51    fn reset_phase(&mut self) {
52        self.set_phase(T::ZERO);
53    }
54
55    /// Получить частоту в Hz
56    fn frequency(&self) -> f32;
57
58    /// Установить частоту
59    fn set_frequency(&mut self, freq: f32);
60
61    /// Получить амплитуду
62    fn amplitude(&self) -> T;
63
64    /// Установить амплитуду
65    fn set_amplitude(&mut self, amp: T);
66}
67
68/// Генератор с синхронизацией
69///
70/// Позволяет синхронизировать несколько генераторов
71/// по фазе или тактовому сигналу.
72pub trait SyncableGenerator<T: Transcendental>: Generator<T> {
73    /// Синхронизировать с внешним тактовым сигналом
74    ///
75    /// # Arguments
76    /// * `reset` - если true, сбросить фазу в 0
77    fn sync(&mut self, reset: bool);
78
79    /// Получить количество периодов с последнего сброса
80    fn periods(&self) -> u32;
81}
82
83/// Генератор с модуляцией частоты
84///
85/// Поддерживает частотную модуляцию (FM) для создания
86/// сложных тембров.
87pub trait ModulatableGenerator<T: Transcendental>: Generator<T> {
88    /// Применить модуляцию частоты
89    ///
90    /// # Arguments
91    /// * `amount` - величина модуляции
92    fn modulate_frequency(&mut self, amount: T);
93
94    /// Индекс модуляции (текущая величина FM)
95    fn modulation_index(&self) -> T;
96
97    /// Установить индекс модуляции
98    fn set_modulation_index(&mut self, index: T);
99}
100
101// =============================================================================
102// Сравнение генераторов
103// =============================================================================
104
105/// Сводка характеристик генераторов
106#[derive(Debug)]
107pub struct GeneratorComparison;
108
109impl GeneratorComparison {
110    /// Гармонический состав разных генераторов
111    pub fn harmonic_content() -> &'static str {
112        "Гармонический состав:\n\
113         ┌────────────┬─────────────────────────────────┐\n\
114         │ Генератор  │ Спектр                          │\n\
115         ├────────────┼─────────────────────────────────┤\n\
116         │ Sine       │ Одна гармоника (чистый тон)     │\n\
117         │ Triangle   │ Нечётные, быстрое затухание     │\n\
118         │ Saw        │ Все гармоники (1/n)             │\n\
119         │ Square     │ Нечётные гармоники (1/n)        │\n\
120         │ Pulse      │ Зависит от ширины импульса      │\n\
121         │ White      │ Равномерный по всем частотам    │\n\
122         │ Pink       │ Спад 3dB/октаву (1/f)           │\n\
123         │ Brown      │ Спад 6dB/октаву (1/f²)          │\n\
124         └────────────┴─────────────────────────────────┘"
125    }
126
127    /// Рекомендации по применению
128    pub fn usage_guide() -> &'static str {
129        "Как выбрать генератор:\n\n\
130         🎵 **Субтрактивный синтез**:\n\
131         → Saw, Square, Pulse - богатый спектр для фильтрации\n\n\
132         🎵 **FM синтез**:\n\
133         → Sine - чистый тон для модуляции\n\n\
134         🎵 **Аддитивный синтез**:\n\
135         → Sine (множество) - построение сложных тембров\n\n\
136         🎵 **Шумовые эффекты**:\n\
137         → White - ветер, snare drum\n\
138         → Pink - естественные явления\n\
139         → Brown - гром, рокот\n\n\
140         🎵 **Огибающие**:\n\
141         → ADSR - амплитудные огибающие\n\
142         → AR - перкуссия\n\
143         → ASR - орга́нные звуки\n\n\
144         🎵 **Модуляция**:\n\
145         → LFO - вибрато, тремоло, фильтр-свип"
146    }
147
148    /// Характеристики производительности
149    pub fn performance_guide() -> &'static str {
150        "Производительность (относительная):\n\
151         ⚡ **Sine** - 1x (самый быстрый)\n\
152         ⚡⚡ **Triangle, Square** - 1.5x\n\
153         ⚡⚡⚡ **Saw** - 2x (с анти-алиасингом)\n\
154         ⚡⚡⚡ **Noise** - 2x\n\
155         ⚡⚡⚡⚡ **Envelope** - 3x\n\
156         ⚡⚡⚡⚡ **FM Synth** - зависит от числа операторов"
157    }
158}
159
160// =============================================================================
161// Тесты
162// =============================================================================
163
164#[cfg(test)]
165mod tests {
166    use super::*;
167
168    #[test]
169    fn test_generator_trait_bounds() {
170        // Проверяем, что все генераторы реализуют нужные трейты
171        fn assert_generator<T: Transcendental, G: Generator<T>>() {}
172        fn assert_syncable<T: Transcendental, G: SyncableGenerator<T>>() {}
173        fn assert_modulatable<T: Transcendental, G: ModulatableGenerator<T>>() {}
174
175        assert_generator::<f32, BasicOscillator<f32>>();
176        assert_generator::<f32, NoiseGenerator<f32>>();
177        assert_generator::<f32, EnvelopeGenerator<f32>>();
178        assert_generator::<f32, LFO<f32>>();
179        assert_generator::<f32, SimpleFmSynth<f32>>();
180
181        assert_syncable::<f32, BasicOscillator<f32>>();
182        assert_modulatable::<f32, BasicOscillator<f32>>();
183    }
184
185    #[test]
186    fn test_comparison_guides() {
187        assert!(!GeneratorComparison::harmonic_content().is_empty());
188        assert!(!GeneratorComparison::usage_guide().is_empty());
189        assert!(!GeneratorComparison::performance_guide().is_empty());
190    }
191}
rill_core_dsp/generators/mod.rs

rill_core_dsp/generators/
mod.rs
