mixed_signals/
lib.rs

1// <FILE>src/lib.rs</FILE> - <DESC>Signal generator library for animations, audio, games, and simulations</DESC>
2// <VERS>VERSION: 1.7.1</VERS>
3// <WCTX>Layer separation improvements</WCTX>
4// <CLOG>Document new decay envelopes and weighted mix</CLOG>
5
6//! # mixed-signals
7//!
8//! Primitives for signals, waveforms, noise, easing, RNG, and shuffling.
9//!
10//! ## Core Philosophy: Bipolar Core, Explicit Normalization
11//!
12//! **All oscillators and noise generators output bipolar `[-1, 1]` by default.**
13//! This matches audio/synthesis conventions and enables mathematically correct composition.
14//!
15//! For TUI animation (opacity, brightness, progress bars), call `.normalized()` to get `[0, 1]`:
16//!
17//! ```rust
18//! use mixed_signals::prelude::*;
19//!
20//! // Core signals are bipolar [-1, 1]
21//! let sine = Sine::default();
22//! assert_eq!(sine.sample(0.25), 1.0);  // Peak at +1
23//! assert_eq!(sine.sample(0.75), -1.0); // Trough at -1
24//!
25//! // For TUI work, normalize to [0, 1]
26//! let opacity = sine.normalized();
27//! assert_eq!(opacity.sample(0.0), 0.5);  // Center maps to 0.5
28//! assert_eq!(opacity.sample(0.25), 1.0); // Peak maps to 1.0
29//! ```
30//!
31//! ## Why "mixed-signals"?
32//!
33//! This library mixes signal generators with utilities commonly needed alongside them:
34//! shuffles, easing functions, physics solvers, and deterministic RNG. Built for terminal
35//! animations, but the primitives have broad application.
36//!
37//! ## Signal Categories
38//!
39//! - **Generators**: Sine, Triangle, Square, Sawtooth, Pulse, Step, Ramp, Constant, Keyframes
40//! - **Noise**: WhiteNoise, PerlinNoise, PinkNoise, CorrelatedNoise, SpatialNoise
41//! - **Random**: GaussianNoise, PoissonNoise, PerCharacterNoise, ImpulseNoise, StudentTNoise
42//! - **Envelopes**: ADSR, Linear, Impact, LinearDecay, ExponentialDecay
43//! - **Physics**: DampedSpring, BouncingDrop, FrictionDecay, Pendulum, Orbit, Projectile, Attractor
44//! - **Composition**: Add, Multiply, Mix, WeightedMix, Scale, Sum, FrequencyMod
45//! - **Processing**: Normalized, Abs, Invert, Clamp, Remap, Quantize
46//! - **Shuffle**: fisher_yates, sattolo, weighted, constrained, riffle, overhand, and more
47//!
48//! ## Quick Start
49//!
50//! ```rust
51//! use mixed_signals::prelude::*;
52//!
53//! // Oscillators output bipolar [-1, 1]
54//! let sine = Sine::new(2.0, 1.0, 0.0, 0.0);
55//! let bipolar_value = sine.sample(0.25);
56//!
57//! // For TUI: normalize to [0, 1]
58//! let opacity = sine.normalized();
59//! let tui_value = opacity.sample(0.25);
60//!
61//! // Compose signals
62//! let noise = PerlinNoise::with_seed(42);
63//! let organic = sine.mix(noise, 0.2).normalized();
64//!
65//! // Physics-based animation
66//! let bounce = BouncingDrop::rubber_ball(0.0, 300.0, 500.0);
67//! let y_position = bounce.sample(0.3);
68//! ```
69//!
70//! ## RNG API
71//!
72//! Use [`rng::Rng`] for traditional random number generation:
73//!
74//! ```rust
75//! use mixed_signals::rng::Rng;
76//!
77//! let mut rng = Rng::with_seed(42);
78//! let dice = rng.uniform(1.0, 7.0).floor() as i32; // 1-6
79//! let hit = rng.chance(0.7); // 70% probability
80//! let color = rng.choose(&["red", "green", "blue"]);
81//! ```
82//!
83//! ## Context-Aware Signals
84//!
85//! Signals can use runtime context for deterministic, reproducible behavior:
86//!
87//! ```rust
88//! use mixed_signals::prelude::*;
89//!
90//! let noise = PerCharacterNoise::with_seed(99);
91//! let ctx = SignalContext::new(100, 42).with_char_index(5);
92//! // Same context always produces same value
93//! let value = noise.sample_with_context(0.5, &ctx);
94//! ```
95pub mod composition;
96pub mod core;
97pub mod easing;
98pub mod envelopes;
99pub mod generators;
100pub mod math;
101pub mod noise;
102pub mod physics;
103pub mod processing;
104pub mod random;
105pub mod rng;
106pub mod shuffle;
107pub mod traits;
108pub mod types;
109#[cfg(feature = "visualization")]
110pub mod visualization;
111pub mod prelude {
112    //! Convenient re-exports for common usage.
113    pub use crate::composition::*;
114    pub use crate::easing::{ease, EasingType};
115    pub use crate::envelopes::*;
116    pub use crate::generators::*;
117    pub use crate::math::{
118        bezier_x, bezier_x_derivative, bezier_y, quadratic_bezier, solve_bezier,
119    };
120    pub use crate::noise::*;
121    pub use crate::physics::*;
122    pub use crate::processing::*;
123    pub use crate::random::*;
124    pub use crate::rng::Rng;
125    pub use crate::traits::{Phase, Signal, SignalContext, SignalExt, SignalRange, SignalTime};
126    pub use crate::types::{SignalOrFloat, SignalSpec};
127    #[cfg(feature = "visualization")]
128    pub use crate::visualization::{RenderMode, SignalView};
129}
130
131// <FILE>src/lib.rs</FILE> - <DESC>Signal generator library for animations, audio, games, and simulations</DESC>
132// <VERS>END OF VERSION: 1.7.1</VERS>
mixed_signals/lib.rs

mixed_signals/
lib.rs
