pub struct InputEvents<'a> { /* private fields */ }Expand description
An input list of timestamped events.
InputEventss are always ordered: an event at index i will always have a timestamp smaller than
or equal to the timestamp of the next event at index i + 1.
InputEventss do not own the event data, they are only lightweight wrappers around a compatible
event buffer (i.e. InputEventBuffer), see InputEvents::from_buffer as the default implementation.
Unlike Vecs or slices, InputEvents only support retrieving an event from
its index (get). It also implements a few extra features for convenience,
such as Iterator.
§Example
use clack_common::events::{Event, EventHeader, Pckn};
use clack_common::events::event_types::NoteOnEvent;
use clack_common::events::io::{EventBuffer, InputEvents};
let event = NoteOnEvent::new(0, Pckn::new(0u16, 0u16, 12u16, 60u32), 4.2);
let buf = [event];
let mut input_events = InputEvents::from_buffer(&buf);
assert_eq!(1, input_events.len());
assert_eq!(&event, input_events[0].as_event().unwrap());Implementations§
Source§impl<'a> InputEvents<'a>
impl<'a> InputEvents<'a>
Sourcepub const unsafe fn from_raw(raw: &'a clap_input_events) -> &'a InputEvents<'a>
pub const unsafe fn from_raw(raw: &'a clap_input_events) -> &'a InputEvents<'a>
Creates a shared reference to an InputEvents list from a given C FFI-compatible pointer.
§Safety
The caller must ensure the given pointer is valid for the lifetime 'a.
Sourcepub const fn as_raw(&self) -> &clap_input_events
pub const fn as_raw(&self) -> &clap_input_events
Returns a C FFI-compatible pointer to this event list.
This pointer is only valid until the list is dropped.
Sourcepub const fn from_buffer<I>(buffer: &'a I) -> InputEvents<'a>where
I: InputEventBuffer,
pub const fn from_buffer<I>(buffer: &'a I) -> InputEvents<'a>where
I: InputEventBuffer,
Returns an InputEvents from a reference InputEventBuffer implementation.
The most common InputEventBuffer implementors are the
EventBuffer, and arrays or slices of either any
Event type, or of UnknownEvent references.
See the InputEventBuffer implementation docs for a list of all types that can be used
by default.
Sourcepub const fn empty() -> InputEvents<'static>
pub const fn empty() -> InputEvents<'static>
Returns an InputEvents that is always empty.
§Example
use clack_common::events::io::InputEvents;
let no_events = InputEvents::empty();
assert_eq!(0, no_events.len());
assert!(no_events.get(0).is_none());Sourcepub fn get(&self, index: u32) -> Option<&UnknownEvent>
pub fn get(&self, index: u32) -> Option<&UnknownEvent>
Attempts to retrieve an event from the list using its index.
If no event is found at the given index, None is returned.
Implementors of this method SHOULD always return an event if the index is in bounds
(0..len), and SOULD NOT return one if the index is out of bounds. However, this isn’t
a guarantee.
Because incorrect implementations can be found in the wild, users of this method should
always check the returned Option, and skip if None is returned while
getting an expected event using an index that is in bounds.
This also means that users should not rely on this method returning None to stop an
iteration, or Some to continue it. Always rely on the value of len
first if you wish to iterate manually.
§Panics
While this method itself does not panic, some hosts (e.g. Bitwig) may elect to crash the
the plugin if the given index is out of bounds.
Therefore, users should be careful while calling this method. Always check the value of
len before attempting to call this method, to ensure that index is
always in bounds.
§See also
Use the iter method to iterate on all input events, which handles
all of the above edge-cases.
Sourcepub fn iter(&self) -> InputEventsIter<'_> ⓘ
pub fn iter(&self) -> InputEventsIter<'_> ⓘ
Returns an iterator over all the events in this InputEvents.
Sourcepub fn iter_range(&self, range: Range<u32>) -> Option<InputEventsIter<'_>>
pub fn iter_range(&self, range: Range<u32>) -> Option<InputEventsIter<'_>>
Returns an iterator over a specific sub-range of the events in this InputEvents.
If the given range is out of bounds, then None is returned.
Sourcepub fn batch(&self) -> EventBatcher<'_> ⓘ
pub fn batch(&self) -> EventBatcher<'_> ⓘ
Returns an iterator that batches all events for easier processing alongside sample buffers.
This iterator will split the stream of events into multiple
EventBatches, so that:
- Each batch will only have events on its very first sample.
- All events that happen on the same sample are batched together.
This makes batch processing of audio samples easier, while still being able to handle incoming events that may happen on each sample.
See the EventBatch documentation for more information.
§Visual example
In this example, a plugin will receive a buffer of audio samples (represented with .s),
alongside multiple input events (represented by Es), which happen at precise,
sample-accurate times.
The timeline of a processing chunk might look like something like this:
E E E E
E E
E
. . . . . . . . . . . . . . . . . . . . . . . . .While some events are happening at the same time, there are some parts of the sample buffer where no event is occurring, which could be processed efficiently all at once.
The EventBatcher finds these, and splits the stream into multiple
EventBatches where events only happen at the beginning of
each batch.
| |E |E |E |E |
| | |E | |E |
| | | | |E |
|. . . .|. . . . . .|. . . . .|. . . . .|. . . . .|
| batch | batch | batch | batch | batch |§Example
This example shows how to efficiently process the event batches alongside an audio buffer.
use clack_common::events::io::InputEvents;
let input_events: InputEvents = /* ... */
let audio_buffer: &[f32] = /* ... */
for event_bach in input_events.batch() {
// First, handle all events that could affect audio processing.
// (e.g. note on/off, parameter changes, etc.)
for event in event_bach.events() {
// (Handle the event...)
}
// Now, we can process the whole audio batch
let audio_batch: &[f32] = &audio_buffer[event_bach.sample_bounds()];
// (Process the audio samples...)
}