1use super::tf_surface::TfSurface;
20
21#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum SurfaceEditError {
27 BufferTooSmall { needed: usize, have: usize },
28 InvalidRegion,
29}
30
31impl core::fmt::Display for SurfaceEditError {
32 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
33 match self {
34 Self::BufferTooSmall { needed, have } => {
35 write!(
36 f,
37 "surface edit: buffer too small, need {needed}, have {have}"
38 )
39 }
40 Self::InvalidRegion => write!(f, "surface edit: invalid region"),
41 }
42 }
43}
44
45impl std::error::Error for SurfaceEditError {}
46
47#[derive(Debug, Clone, Copy, PartialEq, Eq)]
53pub struct Region {
54 pub frame_start: usize,
56 pub frame_end: usize,
58 pub bin_start: usize,
60 pub bin_end: usize,
62}
63
64impl Region {
65 #[inline]
68 pub fn new(frame_start: usize, frame_end: usize, bin_start: usize, bin_end: usize) -> Self {
69 Self {
70 frame_start,
71 frame_end,
72 bin_start,
73 bin_end,
74 }
75 }
76
77 #[inline]
79 pub fn full(frame_count: usize, bin_count: usize) -> Self {
80 Self::new(0, frame_count, 0, bin_count)
81 }
82
83 #[inline]
85 pub fn frame_span(&self) -> usize {
86 self.frame_end.saturating_sub(self.frame_start)
87 }
88
89 #[inline]
91 pub fn bin_span(&self) -> usize {
92 self.bin_end.saturating_sub(self.bin_start)
93 }
94
95 #[inline]
97 pub fn is_valid(&self) -> bool {
98 self.frame_end > self.frame_start && self.bin_end > self.bin_start
99 }
100}
101
102pub fn apply_gain(
109 surface: &TfSurface,
110 region: &Region,
111 gain: f32,
112 out: &mut [f32],
113) -> Result<usize, SurfaceEditError> {
114 let needed = surface.frame_count * surface.bin_count;
115 if out.len() < needed {
116 return Err(SurfaceEditError::BufferTooSmall {
117 needed,
118 have: out.len(),
119 });
120 }
121
122 out[..needed].copy_from_slice(surface.raster);
124
125 let f_end = region.frame_end.min(surface.frame_count);
126 let b_end = region.bin_end.min(surface.bin_count);
127 for f in region.frame_start..f_end {
128 for b in region.bin_start..b_end {
129 out[f * surface.bin_count + b] *= gain;
130 }
131 }
132
133 Ok(needed)
134}
135
136pub fn spectral_gate(
138 surface: &TfSurface,
139 region: &Region,
140 threshold: f32,
141 out: &mut [f32],
142) -> Result<usize, SurfaceEditError> {
143 let needed = surface.frame_count * surface.bin_count;
144 if out.len() < needed {
145 return Err(SurfaceEditError::BufferTooSmall {
146 needed,
147 have: out.len(),
148 });
149 }
150
151 out[..needed].copy_from_slice(surface.raster);
152
153 let f_end = region.frame_end.min(surface.frame_count);
154 let b_end = region.bin_end.min(surface.bin_count);
155 for f in region.frame_start..f_end {
156 for b in region.bin_start..b_end {
157 let idx = f * surface.bin_count + b;
158 if out[idx] < threshold {
159 out[idx] = 0.0;
160 }
161 }
162 }
163
164 Ok(needed)
165}
166
167pub fn copy_patch(
170 surface: &TfSurface,
171 src_region: &Region,
172 dst_frame: usize,
173 dst_bin: usize,
174 out: &mut [f32],
175) -> Result<usize, SurfaceEditError> {
176 let needed = surface.frame_count * surface.bin_count;
177 if out.len() < needed {
178 return Err(SurfaceEditError::BufferTooSmall {
179 needed,
180 have: out.len(),
181 });
182 }
183
184 out[..needed].copy_from_slice(surface.raster);
185
186 let f_span = src_region.frame_span();
187 let b_span = src_region.bin_span();
188
189 for df in 0..f_span {
190 let src_f = src_region.frame_start + df;
191 let dst_f = dst_frame + df;
192 if src_f >= surface.frame_count || dst_f >= surface.frame_count {
193 break;
194 }
195 for db in 0..b_span {
196 let src_b = src_region.bin_start + db;
197 let dst_b = dst_bin + db;
198 if src_b >= surface.bin_count || dst_b >= surface.bin_count {
199 break;
200 }
201 out[dst_f * surface.bin_count + dst_b] =
202 surface.raster[src_f * surface.bin_count + src_b];
203 }
204 }
205
206 Ok(needed)
207}
208
209pub fn time_stretch(
214 surface: &TfSurface,
215 factor: f32,
216 out: &mut [f32],
217) -> Result<(usize, usize), SurfaceEditError> {
218 let new_frames = (surface.frame_count as f32 * factor).round() as usize;
219 let new_frames = new_frames.max(1);
220 let needed = new_frames * surface.bin_count;
221 if out.len() < needed {
222 return Err(SurfaceEditError::BufferTooSmall {
223 needed,
224 have: out.len(),
225 });
226 }
227
228 for f in 0..new_frames {
229 let src_f = f as f32 / factor;
230 for b in 0..surface.bin_count {
231 out[f * surface.bin_count + b] = surface.sample_bilinear(src_f, b as f32);
232 }
233 }
234
235 Ok((new_frames, surface.bin_count))
236}
237
238pub fn pitch_shift(
242 surface: &TfSurface,
243 factor: f32,
244 out: &mut [f32],
245) -> Result<usize, SurfaceEditError> {
246 let needed = surface.frame_count * surface.bin_count;
247 if out.len() < needed {
248 return Err(SurfaceEditError::BufferTooSmall {
249 needed,
250 have: out.len(),
251 });
252 }
253
254 for f in 0..surface.frame_count {
255 for b in 0..surface.bin_count {
256 let src_b = b as f32 / factor;
257 out[f * surface.bin_count + b] = surface.sample_bilinear(f as f32, src_b);
258 }
259 }
260
261 Ok(needed)
262}
263
264pub fn crossfade(
267 surface_a: &TfSurface,
268 surface_b: &TfSurface,
269 t: f32,
270 out: &mut [f32],
271) -> Result<usize, SurfaceEditError> {
272 if surface_a.frame_count != surface_b.frame_count || surface_a.bin_count != surface_b.bin_count
273 {
274 return Err(SurfaceEditError::InvalidRegion);
275 }
276
277 let needed = surface_a.frame_count * surface_a.bin_count;
278 if out.len() < needed {
279 return Err(SurfaceEditError::BufferTooSmall {
280 needed,
281 have: out.len(),
282 });
283 }
284
285 for i in 0..needed {
286 out[i] = surface_a.raster[i] * (1.0 - t) + surface_b.raster[i] * t;
287 }
288
289 Ok(needed)
290}
291
292pub fn fade_in(
294 surface: &TfSurface,
295 fade_frames: usize,
296 out: &mut [f32],
297) -> Result<usize, SurfaceEditError> {
298 let needed = surface.frame_count * surface.bin_count;
299 if out.len() < needed {
300 return Err(SurfaceEditError::BufferTooSmall {
301 needed,
302 have: out.len(),
303 });
304 }
305
306 out[..needed].copy_from_slice(surface.raster);
307
308 let fade = fade_frames.min(surface.frame_count);
309 for f in 0..fade {
310 let gain = f as f32 / fade as f32;
311 for b in 0..surface.bin_count {
312 out[f * surface.bin_count + b] *= gain;
313 }
314 }
315
316 Ok(needed)
317}
318
319pub fn fade_out(
321 surface: &TfSurface,
322 fade_frames: usize,
323 out: &mut [f32],
324) -> Result<usize, SurfaceEditError> {
325 let needed = surface.frame_count * surface.bin_count;
326 if out.len() < needed {
327 return Err(SurfaceEditError::BufferTooSmall {
328 needed,
329 have: out.len(),
330 });
331 }
332
333 out[..needed].copy_from_slice(surface.raster);
334
335 let fade = fade_frames.min(surface.frame_count);
336 let start = surface.frame_count - fade;
337 for f in 0..fade {
338 let gain = 1.0 - (f + 1) as f32 / fade as f32;
339 for b in 0..surface.bin_count {
340 out[(start + f) * surface.bin_count + b] *= gain;
341 }
342 }
343
344 Ok(needed)
345}
346
347#[cfg(test)]
352mod tests {
353 use super::*;
354 use crate::audio::audio_spectral_sheet::SPECTRAL_PREVIEW_BINS;
355
356 fn make_surface() -> (Vec<f32>, usize, usize) {
357 let frames = 4;
358 let bins = SPECTRAL_PREVIEW_BINS;
359 let mut raster = vec![0.5f32; frames * bins];
360 raster[1 * bins + 16] = 1.0;
362 raster[2 * bins + 32] = 0.8;
363 (raster, frames, bins)
364 }
365
366 #[test]
367 fn gain_scales_region() {
368 let (raster, frames, bins) = make_surface();
369 let s = TfSurface::new(&raster, frames, bins, 44100, 512);
370 let region = Region::new(1, 3, 10, 20);
371 let mut out = vec![0.0f32; frames * bins];
372 apply_gain(&s, ®ion, 2.0, &mut out).unwrap();
373 assert!(
375 (out[1 * bins + 16] - 2.0).abs() < 1e-6,
376 "peak should be doubled"
377 );
378 assert!(
380 (out[0 * bins + 0] - 0.5).abs() < 1e-6,
381 "outside should be unchanged"
382 );
383 }
384
385 #[test]
386 fn spectral_gate_zeros_below_threshold() {
387 let (raster, frames, bins) = make_surface();
388 let s = TfSurface::new(&raster, frames, bins, 44100, 512);
389 let region = Region::full(frames, bins);
390 let mut out = vec![0.0f32; frames * bins];
391 spectral_gate(&s, ®ion, 0.6, &mut out).unwrap();
392 assert_eq!(out[0 * bins + 0], 0.0, "0.5 should be gated");
394 assert!((out[1 * bins + 16] - 1.0).abs() < 1e-6, "1.0 should remain");
396 assert!((out[2 * bins + 32] - 0.8).abs() < 1e-6, "0.8 should remain");
397 }
398
399 #[test]
400 fn copy_patch_translates_region() {
401 let (raster, frames, bins) = make_surface();
402 let s = TfSurface::new(&raster, frames, bins, 44100, 512);
403 let src = Region::new(1, 2, 16, 17); let mut out = vec![0.0f32; frames * bins];
405 copy_patch(&s, &src, 3, 40, &mut out).unwrap();
406 assert!(
408 (out[3 * bins + 40] - 1.0).abs() < 1e-6,
409 "patch should be copied"
410 );
411 }
412
413 #[test]
414 fn time_stretch_doubles_frames() {
415 let (raster, frames, bins) = make_surface();
416 let s = TfSurface::new(&raster, frames, bins, 44100, 512);
417 let mut out = vec![0.0f32; frames * 2 * bins];
418 let (new_frames, _) = time_stretch(&s, 2.0, &mut out).unwrap();
419 assert_eq!(new_frames, 8, "should double frame count");
420 }
421
422 #[test]
423 fn time_stretch_preserves_energy_pattern() {
424 let (raster, frames, bins) = make_surface();
425 let s = TfSurface::new(&raster, frames, bins, 44100, 512);
426 let mut out = vec![0.0f32; frames * 2 * bins];
427 let (new_frames, _) = time_stretch(&s, 2.0, &mut out).unwrap();
428 let peak_frame = (0..new_frames)
430 .map(|f| (f, out[f * bins + 16]))
431 .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap())
432 .unwrap()
433 .0;
434 assert!(
435 peak_frame >= 1 && peak_frame <= 3,
436 "peak should be near frame 2"
437 );
438 }
439
440 #[test]
441 fn pitch_shift_preserves_frame_count() {
442 let (raster, frames, bins) = make_surface();
443 let s = TfSurface::new(&raster, frames, bins, 44100, 512);
444 let mut out = vec![0.0f32; frames * bins];
445 pitch_shift(&s, 2.0, &mut out).unwrap();
446 assert!(
449 out.iter().any(|&v| v > 0.0),
450 "pitch shift should preserve energy"
451 );
452 }
453
454 #[test]
455 fn crossfade_blends_surfaces() {
456 let (raster_a, frames, bins) = make_surface();
457 let raster_b = vec![1.0f32; frames * bins];
458 let sa = TfSurface::new(&raster_a, frames, bins, 44100, 512);
459 let sb = TfSurface::new(&raster_b, frames, bins, 44100, 512);
460 let mut out = vec![0.0f32; frames * bins];
461 crossfade(&sa, &sb, 0.5, &mut out).unwrap();
462 let expected = (raster_a[0] + raster_b[0]) * 0.5;
464 assert!((out[0] - expected).abs() < 1e-6, "crossfade should blend");
465 }
466
467 #[test]
468 fn crossfade_at_t0_returns_a() {
469 let (raster_a, frames, bins) = make_surface();
470 let raster_b = vec![1.0f32; frames * bins];
471 let sa = TfSurface::new(&raster_a, frames, bins, 44100, 512);
472 let sb = TfSurface::new(&raster_b, frames, bins, 44100, 512);
473 let mut out = vec![0.0f32; frames * bins];
474 crossfade(&sa, &sb, 0.0, &mut out).unwrap();
475 for i in 0..frames * bins {
476 assert!(
477 (out[i] - raster_a[i]).abs() < 1e-6,
478 "t=0 should return surface A"
479 );
480 }
481 }
482
483 #[test]
484 fn crossfade_at_t1_returns_b() {
485 let (raster_a, frames, bins) = make_surface();
486 let raster_b = vec![1.0f32; frames * bins];
487 let sa = TfSurface::new(&raster_a, frames, bins, 44100, 512);
488 let sb = TfSurface::new(&raster_b, frames, bins, 44100, 512);
489 let mut out = vec![0.0f32; frames * bins];
490 crossfade(&sa, &sb, 1.0, &mut out).unwrap();
491 for i in 0..frames * bins {
492 assert!(
493 (out[i] - raster_b[i]).abs() < 1e-6,
494 "t=1 should return surface B"
495 );
496 }
497 }
498
499 #[test]
500 fn fade_in_ramps_from_zero() {
501 let (raster, frames, bins) = make_surface();
502 let s = TfSurface::new(&raster, frames, bins, 44100, 512);
503 let mut out = vec![0.0f32; frames * bins];
504 fade_in(&s, 2, &mut out).unwrap();
505 assert_eq!(out[0], 0.0, "frame 0 should be zeroed by fade-in");
507 assert!(
509 (out[1 * bins] - 0.25).abs() < 1e-6,
510 "frame 1 should be halved"
511 );
512 assert!(
514 (out[2 * bins] - 0.5).abs() < 1e-6,
515 "frame 2 should be unchanged"
516 );
517 }
518
519 #[test]
520 fn fade_out_ramps_to_zero() {
521 let (raster, frames, bins) = make_surface();
522 let s = TfSurface::new(&raster, frames, bins, 44100, 512);
523 let mut out = vec![0.0f32; frames * bins];
524 fade_out(&s, 2, &mut out).unwrap();
525 assert_eq!(out[(frames - 1) * bins], 0.0, "last frame should be zeroed");
527 assert!(
529 (out[(frames - 2) * bins] - 0.25).abs() < 1e-6,
530 "second-to-last should be halved"
531 );
532 }
533
534 #[test]
535 fn all_edits_deterministic() {
536 let (raster, frames, bins) = make_surface();
537 let s = TfSurface::new(&raster, frames, bins, 44100, 512);
538 let region = Region::new(0, 2, 0, 32);
539
540 let mut out1 = vec![0.0f32; frames * bins];
541 let mut out2 = vec![0.0f32; frames * bins];
542 apply_gain(&s, ®ion, 1.5, &mut out1).unwrap();
543 apply_gain(&s, ®ion, 1.5, &mut out2).unwrap();
544 assert_eq!(out1, out2, "gain must be deterministic");
545
546 let mut out3 = vec![0.0f32; frames * bins];
547 let mut out4 = vec![0.0f32; frames * bins];
548 spectral_gate(&s, ®ion, 0.3, &mut out3).unwrap();
549 spectral_gate(&s, ®ion, 0.3, &mut out4).unwrap();
550 assert_eq!(out3, out4, "gate must be deterministic");
551 }
552
553 #[test]
554 fn buffer_too_small_errors() {
555 let (raster, frames, bins) = make_surface();
556 let s = TfSurface::new(&raster, frames, bins, 44100, 512);
557 let mut out = vec![0.0f32; 10]; let region = Region::full(frames, bins);
559 let err = apply_gain(&s, ®ion, 2.0, &mut out).unwrap_err();
560 assert_eq!(
561 err,
562 SurfaceEditError::BufferTooSmall {
563 needed: frames * bins,
564 have: 10,
565 }
566 );
567 }
568}