vst/
buffer.rs

1//! Buffers to safely work with audio samples.
2
3use num_traits::Float;
4
5use std::slice;
6
7/// `AudioBuffer` contains references to the audio buffers for all input and output channels.
8///
9/// To create an `AudioBuffer` in a host, use a [`HostBuffer`](../host/struct.HostBuffer.html).
10pub struct AudioBuffer<'a, T: 'a + Float> {
11    inputs: &'a [*const T],
12    outputs: &'a mut [*mut T],
13    samples: usize,
14}
15
16impl<'a, T: 'a + Float> AudioBuffer<'a, T> {
17    /// Create an `AudioBuffer` from raw pointers.
18    /// Only really useful for interacting with the VST API.
19    #[inline]
20    pub unsafe fn from_raw(
21        input_count: usize,
22        output_count: usize,
23        inputs_raw: *const *const T,
24        outputs_raw: *mut *mut T,
25        samples: usize,
26    ) -> Self {
27        Self {
28            inputs: slice::from_raw_parts(inputs_raw, input_count),
29            outputs: slice::from_raw_parts_mut(outputs_raw, output_count),
30            samples,
31        }
32    }
33
34    /// The number of input channels that this buffer was created for
35    #[inline]
36    pub fn input_count(&self) -> usize {
37        self.inputs.len()
38    }
39
40    /// The number of output channels that this buffer was created for
41    #[inline]
42    pub fn output_count(&self) -> usize {
43        self.outputs.len()
44    }
45
46    /// The number of samples in this buffer (same for all channels)
47    #[inline]
48    pub fn samples(&self) -> usize {
49        self.samples
50    }
51
52    /// The raw inputs to pass to processReplacing
53    #[inline]
54    pub(crate) fn raw_inputs(&self) -> &[*const T] {
55        self.inputs
56    }
57
58    /// The raw outputs to pass to processReplacing
59    #[inline]
60    pub(crate) fn raw_outputs(&mut self) -> &mut [*mut T] {
61        &mut self.outputs
62    }
63
64    /// Split this buffer into separate inputs and outputs.
65    #[inline]
66    pub fn split<'b>(&'b mut self) -> (Inputs<'b, T>, Outputs<'b, T>)
67    where
68        'a: 'b,
69    {
70        (
71            Inputs {
72                bufs: self.inputs,
73                samples: self.samples,
74            },
75            Outputs {
76                bufs: self.outputs,
77                samples: self.samples,
78            },
79        )
80    }
81
82    /// Create an iterator over pairs of input buffers and output buffers.
83    #[inline]
84    pub fn zip<'b>(&'b mut self) -> AudioBufferIterator<'a, 'b, T> {
85        AudioBufferIterator {
86            audio_buffer: self,
87            index: 0,
88        }
89    }
90}
91
92/// Iterator over pairs of buffers of input channels and output channels.
93pub struct AudioBufferIterator<'a, 'b, T>
94where
95    T: 'a + Float,
96    'a: 'b,
97{
98    audio_buffer: &'b mut AudioBuffer<'a, T>,
99    index: usize,
100}
101
102impl<'a, 'b, T> Iterator for AudioBufferIterator<'a, 'b, T>
103where
104    T: 'b + Float,
105{
106    type Item = (&'b [T], &'b mut [T]);
107
108    fn next(&mut self) -> Option<Self::Item> {
109        if self.index < self.audio_buffer.inputs.len() && self.index < self.audio_buffer.outputs.len() {
110            let input =
111                unsafe { slice::from_raw_parts(self.audio_buffer.inputs[self.index], self.audio_buffer.samples) };
112            let output =
113                unsafe { slice::from_raw_parts_mut(self.audio_buffer.outputs[self.index], self.audio_buffer.samples) };
114            let val = (input, output);
115            self.index += 1;
116            Some(val)
117        } else {
118            None
119        }
120    }
121}
122
123use std::ops::{Index, IndexMut};
124
125/// Wrapper type to access the buffers for the input channels of an `AudioBuffer` in a safe way.
126/// Behaves like a slice.
127#[derive(Copy, Clone)]
128pub struct Inputs<'a, T: 'a> {
129    bufs: &'a [*const T],
130    samples: usize,
131}
132
133impl<'a, T> Inputs<'a, T> {
134    /// Number of channels
135    pub fn len(&self) -> usize {
136        self.bufs.len()
137    }
138
139    /// Returns true if the buffer is empty
140    pub fn is_empty(&self) -> bool {
141        self.len() == 0
142    }
143
144    /// Access channel at the given index
145    pub fn get(&self, i: usize) -> &'a [T] {
146        unsafe { slice::from_raw_parts(self.bufs[i], self.samples) }
147    }
148
149    /// Split borrowing at the given index, like for slices
150    pub fn split_at(&self, i: usize) -> (Inputs<'a, T>, Inputs<'a, T>) {
151        let (l, r) = self.bufs.split_at(i);
152        (
153            Inputs {
154                bufs: l,
155                samples: self.samples,
156            },
157            Inputs {
158                bufs: r,
159                samples: self.samples,
160            },
161        )
162    }
163}
164
165impl<'a, T> Index<usize> for Inputs<'a, T> {
166    type Output = [T];
167
168    fn index(&self, i: usize) -> &Self::Output {
169        self.get(i)
170    }
171}
172
173/// Iterator over buffers for input channels of an `AudioBuffer`.
174pub struct InputIterator<'a, T: 'a> {
175    data: Inputs<'a, T>,
176    i: usize,
177}
178
179impl<'a, T> Iterator for InputIterator<'a, T> {
180    type Item = &'a [T];
181
182    fn next(&mut self) -> Option<Self::Item> {
183        if self.i < self.data.len() {
184            let val = self.data.get(self.i);
185            self.i += 1;
186            Some(val)
187        } else {
188            None
189        }
190    }
191}
192
193impl<'a, T: Sized> IntoIterator for Inputs<'a, T> {
194    type Item = &'a [T];
195    type IntoIter = InputIterator<'a, T>;
196
197    fn into_iter(self) -> Self::IntoIter {
198        InputIterator { data: self, i: 0 }
199    }
200}
201
202/// Wrapper type to access the buffers for the output channels of an `AudioBuffer` in a safe way.
203/// Behaves like a slice.
204pub struct Outputs<'a, T: 'a> {
205    bufs: &'a [*mut T],
206    samples: usize,
207}
208
209impl<'a, T> Outputs<'a, T> {
210    /// Number of channels
211    pub fn len(&self) -> usize {
212        self.bufs.len()
213    }
214
215    /// Returns true if the buffer is empty
216    pub fn is_empty(&self) -> bool {
217        self.len() == 0
218    }
219
220    /// Access channel at the given index
221    pub fn get(&self, i: usize) -> &'a [T] {
222        unsafe { slice::from_raw_parts(self.bufs[i], self.samples) }
223    }
224
225    /// Mutably access channel at the given index
226    pub fn get_mut(&mut self, i: usize) -> &'a mut [T] {
227        unsafe { slice::from_raw_parts_mut(self.bufs[i], self.samples) }
228    }
229
230    /// Split borrowing at the given index, like for slices
231    pub fn split_at_mut(self, i: usize) -> (Outputs<'a, T>, Outputs<'a, T>) {
232        let (l, r) = self.bufs.split_at(i);
233        (
234            Outputs {
235                bufs: l,
236                samples: self.samples,
237            },
238            Outputs {
239                bufs: r,
240                samples: self.samples,
241            },
242        )
243    }
244}
245
246impl<'a, T> Index<usize> for Outputs<'a, T> {
247    type Output = [T];
248
249    fn index(&self, i: usize) -> &Self::Output {
250        self.get(i)
251    }
252}
253
254impl<'a, T> IndexMut<usize> for Outputs<'a, T> {
255    fn index_mut(&mut self, i: usize) -> &mut Self::Output {
256        self.get_mut(i)
257    }
258}
259
260/// Iterator over buffers for output channels of an `AudioBuffer`.
261pub struct OutputIterator<'a, 'b, T>
262where
263    T: 'a,
264    'a: 'b,
265{
266    data: &'b mut Outputs<'a, T>,
267    i: usize,
268}
269
270impl<'a, 'b, T> Iterator for OutputIterator<'a, 'b, T>
271where
272    T: 'b,
273{
274    type Item = &'b mut [T];
275
276    fn next(&mut self) -> Option<Self::Item> {
277        if self.i < self.data.len() {
278            let val = self.data.get_mut(self.i);
279            self.i += 1;
280            Some(val)
281        } else {
282            None
283        }
284    }
285}
286
287impl<'a, 'b, T: Sized> IntoIterator for &'b mut Outputs<'a, T> {
288    type Item = &'b mut [T];
289    type IntoIter = OutputIterator<'a, 'b, T>;
290
291    fn into_iter(self) -> Self::IntoIter {
292        OutputIterator { data: self, i: 0 }
293    }
294}
295
296use crate::event::{Event, MidiEvent, SysExEvent};
297
298/// This is used as a placeholder to pre-allocate space for a fixed number of
299/// midi events in the re-useable `SendEventBuffer`, because `SysExEvent` is
300/// larger than `MidiEvent`, so either one can be stored in a `SysExEvent`.
301pub type PlaceholderEvent = api::SysExEvent;
302
303/// This trait is used by `SendEventBuffer::send_events` to accept iterators over midi events
304pub trait WriteIntoPlaceholder {
305    /// writes an event into the given placeholder memory location
306    fn write_into(&self, out: &mut PlaceholderEvent);
307}
308
309impl<'a, T: WriteIntoPlaceholder> WriteIntoPlaceholder for &'a T {
310    fn write_into(&self, out: &mut PlaceholderEvent) {
311        (*self).write_into(out);
312    }
313}
314
315impl WriteIntoPlaceholder for MidiEvent {
316    fn write_into(&self, out: &mut PlaceholderEvent) {
317        let out = unsafe { &mut *(out as *mut _ as *mut _) };
318        *out = api::MidiEvent {
319            event_type: api::EventType::Midi,
320            byte_size: mem::size_of::<api::MidiEvent>() as i32,
321            delta_frames: self.delta_frames,
322            flags: if self.live {
323                api::MidiEventFlags::REALTIME_EVENT.bits()
324            } else {
325                0
326            },
327            note_length: self.note_length.unwrap_or(0),
328            note_offset: self.note_offset.unwrap_or(0),
329            midi_data: self.data,
330            _midi_reserved: 0,
331            detune: self.detune,
332            note_off_velocity: self.note_off_velocity,
333            _reserved1: 0,
334            _reserved2: 0,
335        };
336    }
337}
338
339impl<'a> WriteIntoPlaceholder for SysExEvent<'a> {
340    fn write_into(&self, out: &mut PlaceholderEvent) {
341        *out = PlaceholderEvent {
342            event_type: api::EventType::SysEx,
343            byte_size: mem::size_of::<PlaceholderEvent>() as i32,
344            delta_frames: self.delta_frames,
345            _flags: 0,
346            data_size: self.payload.len() as i32,
347            _reserved1: 0,
348            system_data: self.payload.as_ptr() as *const u8 as *mut u8,
349            _reserved2: 0,
350        };
351    }
352}
353
354impl<'a> WriteIntoPlaceholder for Event<'a> {
355    fn write_into(&self, out: &mut PlaceholderEvent) {
356        match *self {
357            Event::Midi(ref ev) => {
358                ev.write_into(out);
359            }
360            Event::SysEx(ref ev) => {
361                ev.write_into(out);
362            }
363            Event::Deprecated(e) => {
364                let out = unsafe { &mut *(out as *mut _ as *mut _) };
365                *out = e;
366            }
367        };
368    }
369}
370
371use crate::{api, host::Host};
372use std::mem;
373
374/// This buffer is used for sending midi events through the VST interface.
375/// The purpose of this is to convert outgoing midi events from `event::Event` to `api::Events`.
376/// It only allocates memory in new() and reuses the memory between calls.
377pub struct SendEventBuffer {
378    buf: Vec<u8>,
379    api_events: Vec<PlaceholderEvent>, // using SysExEvent to store both because it's larger than MidiEvent
380}
381
382impl Default for SendEventBuffer {
383    fn default() -> Self {
384        SendEventBuffer::new(1024)
385    }
386}
387
388impl SendEventBuffer {
389    /// Creates a buffer for sending up to the given number of midi events per frame
390    #[inline(always)]
391    pub fn new(capacity: usize) -> Self {
392        let header_size = mem::size_of::<api::Events>() - (mem::size_of::<*mut api::Event>() * 2);
393        let body_size = mem::size_of::<*mut api::Event>() * capacity;
394        let mut buf = vec![0u8; header_size + body_size];
395        let api_events = vec![unsafe { mem::zeroed::<PlaceholderEvent>() }; capacity];
396        {
397            let ptrs = {
398                let e = Self::buf_as_api_events(&mut buf);
399                e.num_events = capacity as i32;
400                e.events_raw_mut()
401            };
402            for (ptr, event) in ptrs.iter_mut().zip(&api_events) {
403                let (ptr, event): (&mut *const PlaceholderEvent, &PlaceholderEvent) = (ptr, event);
404                *ptr = event;
405            }
406        }
407        Self { buf, api_events }
408    }
409
410    /// Sends events to the host. See the `fwd_midi` example.
411    ///
412    /// # Example
413    /// ```no_run
414    /// # use vst::plugin::{Info, Plugin, HostCallback};
415    /// # use vst::buffer::{AudioBuffer, SendEventBuffer};
416    /// # use vst::host::Host;
417    /// # use vst::event::*;
418    /// # struct ExamplePlugin { host: HostCallback, send_buffer: SendEventBuffer }
419    /// # impl Plugin for ExamplePlugin {
420    /// #     fn new(host: HostCallback) -> Self { Self { host, send_buffer: Default::default() } }
421    /// #
422    /// #     fn get_info(&self) -> Info { Default::default() }
423    /// #
424    /// fn process(&mut self, buffer: &mut AudioBuffer<f32>){
425    ///     let events: Vec<MidiEvent> = vec![
426    ///         // ...
427    ///     ];
428    ///     self.send_buffer.send_events(&events, &mut self.host);
429    /// }
430    /// # }
431    /// ```
432    #[inline(always)]
433    pub fn send_events<T: IntoIterator<Item = U>, U: WriteIntoPlaceholder>(&mut self, events: T, host: &mut dyn Host) {
434        self.store_events(events);
435        host.process_events(self.events());
436    }
437
438    /// Stores events in the buffer, replacing the buffer's current content.
439    /// Use this in [`process_events`](crate::Plugin::process_events) to store received input events, then read them in [`process`](crate::Plugin::process) using [`events`](SendEventBuffer::events).
440    #[inline(always)]
441    pub fn store_events<T: IntoIterator<Item = U>, U: WriteIntoPlaceholder>(&mut self, events: T) {
442        #[allow(clippy::suspicious_map)]
443        let count = events
444            .into_iter()
445            .zip(self.api_events.iter_mut())
446            .map(|(ev, out)| ev.write_into(out))
447            .count();
448        self.set_num_events(count);
449    }
450
451    /// Returns a reference to the stored events
452    #[inline(always)]
453    pub fn events(&self) -> &api::Events {
454        #[allow(clippy::cast_ptr_alignment)]
455        unsafe {
456            &*(self.buf.as_ptr() as *const api::Events)
457        }
458    }
459
460    /// Clears the buffer
461    #[inline(always)]
462    pub fn clear(&mut self) {
463        self.set_num_events(0);
464    }
465
466    #[inline(always)]
467    fn buf_as_api_events(buf: &mut [u8]) -> &mut api::Events {
468        #[allow(clippy::cast_ptr_alignment)]
469        unsafe {
470            &mut *(buf.as_mut_ptr() as *mut api::Events)
471        }
472    }
473
474    #[inline(always)]
475    fn set_num_events(&mut self, events_len: usize) {
476        use std::cmp::min;
477        let e = Self::buf_as_api_events(&mut self.buf);
478        e.num_events = min(self.api_events.len(), events_len) as i32;
479    }
480}
481
482#[cfg(test)]
483mod tests {
484    use crate::buffer::AudioBuffer;
485
486    /// Size of buffers used in tests.
487    const SIZE: usize = 1024;
488
489    /// Test that creating and zipping buffers works.
490    ///
491    /// This test creates a channel for 2 inputs and 2 outputs.
492    /// The input channels are simply values
493    /// from 0 to `SIZE-1` (e.g. [0, 1, 2, 3, 4, .. , SIZE - 1])
494    /// and the output channels are just 0.
495    /// This test assures that when the buffers are zipped together,
496    /// the input values do not change.
497    #[test]
498    fn buffer_zip() {
499        let in1: Vec<f32> = (0..SIZE).map(|x| x as f32).collect();
500        let in2 = in1.clone();
501
502        let mut out1 = vec![0.0; SIZE];
503        let mut out2 = out1.clone();
504
505        let inputs = vec![in1.as_ptr(), in2.as_ptr()];
506        let mut outputs = vec![out1.as_mut_ptr(), out2.as_mut_ptr()];
507        let mut buffer = unsafe { AudioBuffer::from_raw(2, 2, inputs.as_ptr(), outputs.as_mut_ptr(), SIZE) };
508
509        for (input, output) in buffer.zip() {
510            input.iter().zip(output.iter_mut()).fold(0, |acc, (input, output)| {
511                assert_eq!(*input, acc as f32);
512                assert_eq!(*output, 0.0);
513                acc + 1
514            });
515        }
516    }
517
518    // Test that the `zip()` method returns an iterator that gives `n` elements
519    // where n is the number of inputs when this is lower than the number of outputs.
520    #[test]
521    fn buffer_zip_fewer_inputs_than_outputs() {
522        let in1 = vec![1.0; SIZE];
523        let in2 = vec![2.0; SIZE];
524
525        let mut out1 = vec![3.0; SIZE];
526        let mut out2 = vec![4.0; SIZE];
527        let mut out3 = vec![5.0; SIZE];
528
529        let inputs = vec![in1.as_ptr(), in2.as_ptr()];
530        let mut outputs = vec![out1.as_mut_ptr(), out2.as_mut_ptr(), out3.as_mut_ptr()];
531        let mut buffer = unsafe { AudioBuffer::from_raw(2, 3, inputs.as_ptr(), outputs.as_mut_ptr(), SIZE) };
532
533        let mut iter = buffer.zip();
534        if let Some((observed_in1, observed_out1)) = iter.next() {
535            assert_eq!(1.0, observed_in1[0]);
536            assert_eq!(3.0, observed_out1[0]);
537        } else {
538            unreachable!();
539        }
540
541        if let Some((observed_in2, observed_out2)) = iter.next() {
542            assert_eq!(2.0, observed_in2[0]);
543            assert_eq!(4.0, observed_out2[0]);
544        } else {
545            unreachable!();
546        }
547
548        assert_eq!(None, iter.next());
549    }
550
551    // Test that the `zip()` method returns an iterator that gives `n` elements
552    // where n is the number of outputs when this is lower than the number of inputs.
553    #[test]
554    fn buffer_zip_more_inputs_than_outputs() {
555        let in1 = vec![1.0; SIZE];
556        let in2 = vec![2.0; SIZE];
557        let in3 = vec![3.0; SIZE];
558
559        let mut out1 = vec![4.0; SIZE];
560        let mut out2 = vec![5.0; SIZE];
561
562        let inputs = vec![in1.as_ptr(), in2.as_ptr(), in3.as_ptr()];
563        let mut outputs = vec![out1.as_mut_ptr(), out2.as_mut_ptr()];
564        let mut buffer = unsafe { AudioBuffer::from_raw(3, 2, inputs.as_ptr(), outputs.as_mut_ptr(), SIZE) };
565
566        let mut iter = buffer.zip();
567
568        if let Some((observed_in1, observed_out1)) = iter.next() {
569            assert_eq!(1.0, observed_in1[0]);
570            assert_eq!(4.0, observed_out1[0]);
571        } else {
572            unreachable!();
573        }
574
575        if let Some((observed_in2, observed_out2)) = iter.next() {
576            assert_eq!(2.0, observed_in2[0]);
577            assert_eq!(5.0, observed_out2[0]);
578        } else {
579            unreachable!();
580        }
581
582        assert_eq!(None, iter.next());
583    }
584
585    /// Test that creating buffers from raw pointers works.
586    #[test]
587    fn from_raw() {
588        let in1: Vec<f32> = (0..SIZE).map(|x| x as f32).collect();
589        let in2 = in1.clone();
590
591        let mut out1 = vec![0.0; SIZE];
592        let mut out2 = out1.clone();
593
594        let inputs = vec![in1.as_ptr(), in2.as_ptr()];
595        let mut outputs = vec![out1.as_mut_ptr(), out2.as_mut_ptr()];
596        let mut buffer = unsafe { AudioBuffer::from_raw(2, 2, inputs.as_ptr(), outputs.as_mut_ptr(), SIZE) };
597
598        for (input, output) in buffer.zip() {
599            input.iter().zip(output.iter_mut()).fold(0, |acc, (input, output)| {
600                assert_eq!(*input, acc as f32);
601                assert_eq!(*output, 0.0);
602                acc + 1
603            });
604        }
605    }
606}
vst/buffer.rs

vst/
buffer.rs
