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

rill_core_dsp/generators/
mod.rs
