use crate::canvas::Canvas;
use crate::common::{
DEFAULT_SEED, EffectRng, TerminalEffect, normalize_effect_size, seeded_rng,
};
use crate::render::halfblock::{HalfBlockField, ROWS_PER_CELL};
use crate::render::palette::{Palette, presets as palette_presets};
use crate::runtime::FrameContext;
use rand::RngExt;
use serde::{Deserialize, Serialize};
use std::sync::LazyLock;
const LUT_SIZE: usize = 8192;
const TWO_PI: f32 = std::f32::consts::TAU;
static SINE_LUT: LazyLock<Vec<f32>> = LazyLock::new(|| {
(0..LUT_SIZE)
.map(|i| (i as f32 * TWO_PI / LUT_SIZE as f32).sin())
.collect()
});
const DEFAULT_LEVELS: usize = 16;
const INV_TWO_PI: f32 = 1.0 / TWO_PI;
const RATE_SPREAD_FRACTION: f32 = 0.05;
#[inline]
fn sine(argument: f32) -> f32 {
let turns = argument * INV_TWO_PI;
let fraction = if turns.is_finite() {
turns - turns.floor()
} else {
0.0
};
let index = ((fraction * LUT_SIZE as f32) + 0.5) as usize & (LUT_SIZE - 1);
SINE_LUT[index]
}
#[derive(Debug, Clone, Copy)]
struct Source {
x: f32,
y: f32,
phase: f32,
vx: f32,
vy: f32,
rate: f32,
}
impl Source {
fn advance(&mut self, delta: f32, width: f32, height: f32) {
self.x += self.vx * delta;
self.y += self.vy * delta;
if self.x < 0.0 {
self.x = -self.x;
self.vx = -self.vx;
} else if self.x > width {
self.x = 2.0 * width - self.x;
self.vx = -self.vx;
}
if self.y < 0.0 {
self.y = -self.y;
self.vy = -self.vy;
} else if self.y > height {
self.y = 2.0 * height - self.y;
self.vy = -self.vy;
}
self.x = self.x.clamp(0.0, width);
self.y = self.y.clamp(0.0, height);
self.phase += self.rate * delta;
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct RippleOptions {
pub sources: u16,
pub wave_number: f32,
pub speed: f32,
pub drift: f32,
pub palette: String,
pub levels: usize,
pub seed: u64,
}
impl Default for RippleOptions {
fn default() -> Self {
Self {
sources: 3,
wave_number: 0.22,
speed: 2.4,
drift: 1.0,
palette: "ocean".to_string(),
levels: DEFAULT_LEVELS,
seed: DEFAULT_SEED,
}
}
}
pub struct Ripple {
screen_size: (u16, u16),
options: RippleOptions,
canvas: Canvas,
field: HalfBlockField,
sources: Vec<Source>,
time: f32,
dx_squared: Vec<f32>,
row: Vec<f32>,
rng: EffectRng,
palette: Palette,
}
impl TerminalEffect for Ripple {
fn get_diff(&mut self) -> Vec<(usize, usize, crate::buffer::Cell)> {
self.draw();
self.canvas.commit()
}
fn update(&mut self) {
self.advance(1.0 / 60.0);
}
fn update_with_context(&mut self, context: &FrameContext) {
self.advance(context.delta.as_secs_f32());
}
fn update_size(&mut self, width: u16, height: u16) {
self.screen_size = (width, height);
self.reset();
}
fn reset(&mut self) {
self.canvas.resize(self.screen_size.0, self.screen_size.1);
self.field
.resize(self.screen_size.0 as usize, self.screen_size.1 as usize);
self.time = 0.0;
self.rng = seeded_rng(self.options.seed, "ripple");
self.spawn_sources();
}
}
impl Ripple {
pub fn new(options: RippleOptions, screen_size: (u16, u16)) -> Self {
let screen_size = normalize_effect_size(screen_size);
let levels = options.levels.max(2);
let palette = Palette::new(
Palette::new(
palette_presets::by_name(&options.palette)
.unwrap_or(palette_presets::OCEAN)
.to_vec(),
)
.truncated_at_peak()
.expand(levels),
);
let mut ripple = Self {
screen_size,
canvas: Canvas::new(screen_size.0, screen_size.1),
field: HalfBlockField::new(
screen_size.0 as usize,
screen_size.1 as usize,
),
options,
sources: Vec::new(),
time: 0.0,
dx_squared: Vec::new(),
row: vec![0.0; screen_size.0 as usize],
rng: seeded_rng(DEFAULT_SEED, "ripple"),
palette,
};
ripple.rng = seeded_rng(ripple.options.seed, "ripple");
ripple.spawn_sources();
ripple
}
fn field_width(&self) -> usize {
self.screen_size.0 as usize
}
fn field_height(&self) -> usize {
self.screen_size.1 as usize * ROWS_PER_CELL
}
fn spawn_sources(&mut self) {
let count = self.options.sources.clamp(2, 6);
let (w, h) = (self.field_width() as f32, self.field_height() as f32);
let drift = self.options.drift;
self.sources = (0..count)
.map(|i| {
let spread = i as f32 / count as f32;
Source {
x: self.rng.random_range(0.15..0.85) * w,
y: self.rng.random_range(0.15..0.85) * h,
phase: spread * TWO_PI + self.rng.random_range(0.0..0.5),
vx: (0.06 + 0.05 * spread) * drift,
vy: (0.04 + 0.07 * (1.0 - spread)) * drift,
rate: self.options.speed * RATE_SPREAD_FRACTION * spread,
}
})
.collect();
let wanted = self.sources.len() * self.field_width();
if self.dx_squared.len() != wanted {
self.dx_squared = vec![0.0; wanted];
}
let width = self.field_width();
if self.row.len() != width {
self.row = vec![0.0; width];
}
}
#[cfg(test)]
fn source_ring_speed(&self, index: usize) -> f32 {
let k = self.options.wave_number;
(self.options.speed - self.sources[index].rate) / k
}
fn advance(&mut self, delta: f32) {
let (w, h) = (self.field_width() as f32, self.field_height() as f32);
for source in &mut self.sources {
source.advance(delta, w, h);
}
self.time += delta * self.options.speed;
}
#[inline]
fn wave(source: &Source, dx_squared: f32, dy: f32, k: f32, time: f32) -> f32 {
sine(k * (dx_squared + dy * dy).sqrt() - time + source.phase)
}
#[cfg(test)]
fn sample(&self, x: f32, y: f32, time: f32) -> f32 {
let k = self.options.wave_number;
self.sources
.iter()
.map(|source| {
let dx = x - source.x;
Self::wave(source, dx * dx, y - source.y, k, time)
})
.sum()
}
fn colour_of(&self, value: f32) -> [f32; 3] {
let scale = self.sources.len().max(1) as f32;
let t = (value / scale * 0.5 + 0.5).clamp(0.0, 1.0);
let levels = self.palette.len().max(2);
let index = ((t * (levels - 1) as f32).round() as usize).min(levels - 1);
match self.palette.sample_index(index) {
crossterm::style::Color::Rgb { r, g, b } => {
[r as f32 / 255.0, g as f32 / 255.0, b as f32 / 255.0]
}
_ => [0.0, 0.0, 0.0],
}
}
fn draw(&mut self) {
self.canvas.clear();
let row_height = self.field_height();
let time = self.time;
self.prepare_offsets();
for y in 0..row_height {
self.accumulate_row(y as f32, time);
for x in 0..self.field_width() {
let rgb = self.colour_of(self.row[x]);
self.field.set_row(x, y, rgb);
}
}
self.field
.write_to(&mut self.canvas, crossterm::style::Attribute::Reset);
}
fn prepare_offsets(&mut self) {
let width = self.field_width();
for (i, source) in self.sources.iter().enumerate() {
let base = i * width;
for x in 0..width {
let dx = x as f32 - source.x;
self.dx_squared[base + x] = dx * dx;
}
}
}
fn accumulate_row(&mut self, y: f32, time: f32) {
let width = self.field_width();
let k = self.options.wave_number;
for value in self.row.iter_mut() {
*value = 0.0;
}
for (i, source) in self.sources.iter().enumerate() {
let base = i * width;
let dy = y - source.y;
for x in 0..width {
self.row[x] +=
Self::wave(source, self.dx_squared[base + x], dy, k, time);
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn options(sources: u16, seed: u64) -> RippleOptions {
RippleOptions {
sources,
seed,
..RippleOptions::default()
}
}
#[test]
fn every_source_ring_travels_outwards_at_the_documented_speed() {
for count in [2u16, 3, 4, 6] {
let ripple = Ripple::new(options(count, 1), (80, 24));
let k = ripple.options.wave_number;
let documented = ripple.options.speed / k;
let speeds: Vec<f32> = (0..count as usize)
.map(|i| ripple.source_ring_speed(i))
.collect();
for (i, got) in speeds.iter().enumerate() {
assert!(
*got > 0.0,
"source {i} of {count} travels at {got} rows/s: its rings are \
stationary or running inwards, and the third of three did \
exactly this. Rate drift must be a fraction of `speed`, not a \
multiple of it."
);
assert!(
(*got - documented).abs() < documented * 0.1,
"source {i} of {count} travels at {got} rows/s against a \
documented {documented}; the de-synchronisation drift is large \
enough to be changing the speed rather than de-synchronising it."
);
}
let lo = speeds.iter().cloned().fold(f32::INFINITY, f32::min);
let hi = speeds.iter().cloned().fold(f32::NEG_INFINITY, f32::max);
assert!(
hi - lo > documented * 0.01,
"every one of the {count} sources travels at the same speed, so the \
rates are not de-synchronising anything"
);
}
}
fn still(x: f32, y: f32, phase: f32) -> Source {
Source {
x,
y,
phase,
vx: 0.0,
vy: 0.0,
rate: 0.0,
}
}
fn with_sources(ripple: &mut Ripple, sources: Vec<Source>) {
ripple.sources = sources;
let wanted = ripple.sources.len() * ripple.field_width();
if ripple.dx_squared.len() != wanted {
ripple.dx_squared = vec![0.0; wanted];
}
}
fn first_crest(ripple: &Ripple) -> f32 {
let (cx, cy) = (ripple.sources[0].x, ripple.sources[0].y);
let step = 0.25;
let mut r = 0.0f32;
let mut previous = ripple.sample(cx + r, cy, ripple.time);
while r < 40.0 {
r += step;
let current = ripple.sample(cx + r, cy, ripple.time);
if current > previous && current > 0.9 {
return r;
}
previous = current;
}
f32::NAN
}
#[test]
fn the_rendered_row_matches_the_sampled_field() {
let mut ripple = Ripple::new(options(3, 21), (48, 16));
ripple.advance(0.7);
ripple.prepare_offsets();
for y in [0.0f32, 7.5, 31.0] {
ripple.accumulate_row(y, ripple.time);
for x in 0..ripple.field_width() {
let rendered = ripple.row[x];
let sampled = ripple.sample(x as f32, y, ripple.time);
assert!(
(rendered - sampled).abs() < 1e-4,
"at ({x}, {y}) the row pass gave {rendered} and the sampler \
gave {sampled}"
);
}
}
}
#[test]
fn a_crest_moves_outwards_as_time_passes() {
let mut ripple = Ripple::new(options(2, 1), (80, 24));
with_sources(&mut ripple, vec![still(40.0, 24.0, 0.0)]);
let early = first_crest(&ripple);
ripple.advance(1.0);
let later = first_crest(&ripple);
assert!(
early.is_finite() && later.is_finite(),
"no crest was found to track (early {early}, later {later})"
);
assert!(
later > early + 0.5,
"the first crest sat at {early} and then {later} a second later: the \
pattern is standing still rather than travelling"
);
}
#[test]
fn two_sources_half_a_turn_apart_cancel_everywhere() {
let mut ripple = Ripple::new(options(2, 5), (60, 20));
with_sources(
&mut ripple,
vec![
still(30.0, 20.0, 0.0),
still(30.0, 20.0, std::f32::consts::PI),
],
);
let mut worst = 0.0f32;
for y in 0..40 {
for x in 0..60 {
worst = worst.max(ripple.sample(x as f32, y as f32, 3.0).abs());
}
}
assert!(
worst < 1e-3,
"two opposed sources summed to {worst} at their worst; they should \
cancel to nothing"
);
}
#[test]
fn two_sources_in_step_double_the_amplitude() {
let mut ripple = Ripple::new(options(2, 5), (60, 20));
with_sources(
&mut ripple,
vec![still(30.0, 20.0, 0.0), still(30.0, 20.0, 0.0)],
);
let mut peak = 0.0f32;
for y in 0..40 {
for x in 0..60 {
peak = peak.max(ripple.sample(x as f32, y as f32, 0.0).abs());
}
}
assert!(peak > 1.9, "the doubled peak was only {peak}");
}
#[test]
fn moving_a_source_changes_the_field_far_from_it() {
let mut ripple = Ripple::new(options(2, 6), (80, 24));
with_sources(
&mut ripple,
vec![still(20.0, 20.0, 0.0), still(60.0, 20.0, 0.0)],
);
let far = (4.0, 4.0);
let before = ripple.sample(far.0, far.1, 0.0);
ripple.sources[1].x = 70.0;
let after = ripple.sample(far.0, far.1, 0.0);
assert!(
(before - after).abs() > 1e-3,
"moving a source left a far cell unchanged ({before} -> {after})"
);
}
#[test]
fn the_sine_table_agrees_with_the_real_function() {
for i in 0..LUT_SIZE {
let expected = (i as f32 * TWO_PI / LUT_SIZE as f32).sin();
assert!(
(expected - SINE_LUT[i]).abs() < 1e-6,
"table entry {i} is {}, expected {expected}",
SINE_LUT[i]
);
}
}
#[test]
fn the_table_answers_for_every_argument_the_effect_produces() {
let step = TWO_PI / LUT_SIZE as f32;
for argument in [
0.0f32, 0.001, -0.001, 1.0, -1.0, 7.5, -7.5, 100.0, -100.0, 999.0,
-999.0, 4096.0, -4096.0,
] {
let value = sine(argument);
assert!(
(value - argument.sin()).abs() <= step,
"sine({argument}) was {value}, real function says {}, which is more \
than a table step ({step}) away",
argument.sin()
);
}
}
#[test]
fn a_huge_argument_gives_a_finite_answer_rather_than_a_nan() {
for argument in [1.0e12f32, -1.0e12, f32::MAX, f32::MIN] {
let value = sine(argument);
assert!(
value.is_finite() && (-1.0..=1.0).contains(&value),
"sine({argument}) was {value}"
);
}
}
#[test]
fn a_source_bounced_off_an_edge_stays_inside_the_field() {
let mut source = Source {
vx: -100.0,
vy: -100.0,
..still(5.0, 5.0, 0.0)
};
for _ in 0..500 {
source.advance(0.1, 20.0, 20.0);
assert!(
(0.0..=20.0).contains(&source.x)
&& (0.0..=20.0).contains(&source.y),
"a source escaped to ({}, {})",
source.x,
source.y
);
}
}
#[test]
fn the_whole_ramp_is_used_at_two_sources_and_at_six() {
for count in [2u16, 6] {
let ripple = Ripple::new(options(count, 2), (40, 12));
let mut lowest = f32::INFINITY;
let mut highest = f32::NEG_INFINITY;
for y in 0..24 {
for x in 0..40 {
let value = ripple.sample(x as f32, y as f32, 0.0);
lowest = lowest.min(value);
highest = highest.max(value);
}
}
assert!(
lowest < -0.9 && highest > 0.9,
"with {count} sources the field spans {lowest}..{highest}, so the \
ramp is not being driven end to end"
);
}
}
#[test]
fn a_pinned_palette_actually_changes_the_colours() {
let a = Ripple::new(options(3, 3), (40, 12));
let b = Ripple::new(
RippleOptions {
palette: "magma".to_string(),
..options(3, 3)
},
(40, 12),
);
assert_ne!(a.colour_of(0.5), b.colour_of(0.5));
}
#[test]
fn an_unknown_palette_name_falls_back_rather_than_failing() {
let ripple = Ripple::new(
RippleOptions {
palette: "not-a-palette".to_string(),
..options(3, 4)
},
(40, 12),
);
assert!(
ripple.palette.len() > 1,
"an unknown palette name left the ramp empty"
);
}
#[test]
fn every_emitted_cell_is_inside_the_canvas() {
let mut ripple = Ripple::new(options(3, 8), (64, 20));
for _ in 0..40 {
ripple.advance(1.0 / 60.0);
for (x, y, _) in ripple.get_diff() {
assert!(x < 64 && y < 20, "({x}, {y}) is outside a 64x20 canvas");
}
}
}
}