RFC: Rework the API [WIP] (#165)

* Rework the API to not use futures anymore

* Add some comments

* Update the MacOS backend

* Restore the null implementation

* Add an emscripten backend

* Remove erroneously added feature

* Fix to_f32 formula

* [WIP] Alsa backend

* Alsa backend compiling

* Working ALSA backend

* Fix tests

* Move WASAPI endpoint to endpoint module

* Fix WASAPI warnings

* Rework the WASAPI backend

* Check overflows for voice ID

* Add comments and minor fixes to WASAPI backend

* Add a changelog
This commit is contained in:
tomaka 2017-10-18 20:24:05 +02:00 • committed by GitHub
parent 4b019243c2
commit 6ae01f437c
13 changed files with 1472 additions and 1447 deletions

View file

@ -10,11 +10,7 @@ use SampleFormat;
use SamplesRate;
use UnknownTypeBuffer;
use futures::Async;
use futures::Poll;
use futures::stream::Stream;
use futures::task;
use futures::task::Task;
use std::mem;
use std::sync::{Arc, Mutex};
use std::thread;
use std::time::Duration;
@ -49,27 +45,170 @@ impl Endpoint {
}
}
pub struct EventLoop;
// The ID of a voice is its index within the `voices` array of the events loop.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct VoiceId(usize);
pub struct EventLoop {
// This `Arc` is shared with all the callbacks of coreaudio.
active_callbacks: Arc<ActiveCallbacks>,
voices: Mutex<Vec<Option<VoiceInner>>>,
}
struct ActiveCallbacks {
// Whenever the `run()` method is called with a callback, this callback is put in this list.
callbacks: Mutex<Vec<&'static mut FnMut(VoiceId, UnknownTypeBuffer)>>,
}
struct VoiceInner {
playing: bool,
audio_unit: AudioUnit,
}
impl EventLoop {
#[inline]
pub fn new() -> EventLoop {
EventLoop
EventLoop {
active_callbacks: Arc::new(ActiveCallbacks {
callbacks: Mutex::new(Vec::new()),
}),
voices: Mutex::new(Vec::new()),
}
}
#[inline]
pub fn run(&self) {
pub fn run<F>(&self, mut callback: F) -> !
where F: FnMut(VoiceId, UnknownTypeBuffer)
{
let callback: &mut FnMut(VoiceId, UnknownTypeBuffer) = &mut callback;
self.active_callbacks.callbacks.lock().unwrap().push(unsafe { mem::transmute(callback) });
loop {
// So the loop does not get optimised out in --release
thread::sleep(Duration::new(1u64, 0u32));
}
// Note: if we ever change this API so that `run` can return, then it is critical that
// we remove the callback from `active_callbacks`.
}
#[inline]
pub fn build_voice(&self, endpoint: &Endpoint, format: &Format)
-> Result<VoiceId, CreationError>
{
fn convert_error(err: coreaudio::Error) -> CreationError {
match err {
coreaudio::Error::RenderCallbackBufferFormatDoesNotMatchAudioUnitStreamFormat |
coreaudio::Error::NoKnownSubtype |
coreaudio::Error::AudioUnit(coreaudio::error::AudioUnitError::FormatNotSupported) |
coreaudio::Error::AudioCodec(_) |
coreaudio::Error::AudioFormat(_) => CreationError::FormatNotSupported,
_ => CreationError::DeviceNotAvailable,
}
}
let mut audio_unit = {
let au_type = if cfg!(target_os = "ios") {
// The DefaultOutput unit isn't available in iOS unfortunately. RemoteIO is a sensible replacement.
// See
// https://developer.apple.com/library/content/documentation/MusicAudio/Conceptual/AudioUnitHostingGuide_iOS/UsingSpecificAudioUnits/UsingSpecificAudioUnits.html
coreaudio::audio_unit::IOType::RemoteIO
} else {
coreaudio::audio_unit::IOType::DefaultOutput
};
AudioUnit::new(au_type).map_err(convert_error)?
};
// Determine the future ID of the voice.
let mut voices_lock = self.voices.lock().unwrap();
let voice_id = voices_lock.iter().position(|n| n.is_none()).unwrap_or(voices_lock.len());
// TODO: iOS uses integer and fixed-point data
// Register the callback that is being called by coreaudio whenever it needs data to be
// fed to the audio buffer.
let active_callbacks = self.active_callbacks.clone();
audio_unit.set_render_callback(move |mut args: render_callback::Args<data::NonInterleaved<f32>>| {
// If `run()` is currently running, then a callback will be available from this list.
// Otherwise, we just fill the buffer with zeroes and return.
let mut callbacks = active_callbacks.callbacks.lock().unwrap();
let callback = if let Some(cb) = callbacks.get_mut(0) {
cb
} else {
for channel in args.data.channels_mut() {
for elem in channel.iter_mut() {
*elem = 0.0;
}
}
return Ok(());
};
let buffer = {
let buffer_len = args.num_frames * args.data.channels().count();
Buffer {
args: &mut args,
buffer: vec![0.0; buffer_len],
}
};
callback(VoiceId(voice_id), UnknownTypeBuffer::F32(::Buffer { target: Some(buffer) }));
Ok(())
}).map_err(convert_error)?;
// TODO: start playing now? is that consistent with the other backends?
audio_unit.start().map_err(convert_error)?;
// Add the voice to the list of voices within `self`.
{
let inner = VoiceInner {
playing: true,
audio_unit: audio_unit,
};
if voice_id == voices_lock.len() {
voices_lock.push(Some(inner));
} else {
voices_lock[voice_id] = Some(inner);
}
}
Ok(VoiceId(voice_id))
}
pub fn destroy_voice(&self, voice_id: VoiceId) {
let mut voices = self.voices.lock().unwrap();
voices[voice_id.0] = None;
}
pub fn play(&self, voice: VoiceId) {
let mut voices = self.voices.lock().unwrap();
let voice = voices[voice.0].as_mut().unwrap();
if !voice.playing {
voice.audio_unit.start().unwrap();
voice.playing = true;
}
}
pub fn pause(&self, voice: VoiceId) {
let mut voices = self.voices.lock().unwrap();
let voice = voices[voice.0].as_mut().unwrap();
if voice.playing {
voice.audio_unit.stop().unwrap();
voice.playing = false;
}
}
}
pub struct Buffer<T> {
args: render_callback::Args<data::NonInterleaved<T>>,
pub struct Buffer<'a, T: 'a> {
args: &'a mut render_callback::Args<data::NonInterleaved<T>>,
buffer: Vec<T>,
}
impl<T> Buffer<T>
impl<'a, T> Buffer<'a, T>
where T: Sample
{
#[inline]
@ -86,158 +225,11 @@ impl<T> Buffer<T>
pub fn finish(self) {
// TODO: At the moment this assumes the Vec<T> is a Vec<f32>.
// Need to add T: Sample and use Sample::to_vec_f32.
let Buffer { mut args, buffer } = self;
let num_channels = args.data.channels().count();
for (i, frame) in buffer.chunks(num_channels).enumerate() {
for (channel, sample) in args.data.channels_mut().zip(frame.iter()) {
let num_channels = self.args.data.channels().count();
for (i, frame) in self.buffer.chunks(num_channels).enumerate() {
for (channel, sample) in self.args.data.channels_mut().zip(frame.iter()) {
channel[i] = *sample;
}
}
}
}
pub struct Voice {
playing: bool,
audio_unit: Arc<Mutex<AudioUnit>>,
}
#[allow(dead_code)] // the audio_unit will be dropped if we don't hold it.
pub struct SamplesStream {
inner: Arc<Mutex<SamplesStreamInner>>,
audio_unit: Arc<Mutex<AudioUnit>>,
}
struct SamplesStreamInner {
scheduled_task: Option<Task>,
current_callback: Option<render_callback::Args<data::NonInterleaved<f32>>>,
}
impl Stream for SamplesStream {
type Item = UnknownTypeBuffer;
type Error = ();
fn poll(&mut self) -> Poll<Option<Self::Item>, Self::Error> {
let mut inner = self.inner.lock().unwrap();
// There are two possibilites: either we're answering a callback of coreaudio and we return
// a buffer, or we're not answering a callback and we return that we're not ready.
let current_callback = match inner.current_callback.take() {
Some(c) => c,
None => {
inner.scheduled_task = Some(task::park());
return Ok(Async::NotReady);
},
};
let buffer_len = current_callback.num_frames * current_callback.data.channels().count();
let buffer = Buffer {
args: current_callback,
buffer: vec![0.0; buffer_len],
};
Ok(Async::Ready(Some(UnknownTypeBuffer::F32(::Buffer { target: Some(buffer) }))))
}
}
impl Voice {
pub fn new(_: &Endpoint, _: &Format, _: &EventLoop)
-> Result<(Voice, SamplesStream), CreationError> {
let inner = Arc::new(Mutex::new(SamplesStreamInner {
scheduled_task: None,
current_callback: None,
}));
fn convert_error(err: coreaudio::Error) -> CreationError {
match err {
coreaudio::Error::RenderCallbackBufferFormatDoesNotMatchAudioUnitStreamFormat |
coreaudio::Error::NoKnownSubtype |
coreaudio::Error::AudioUnit(coreaudio::error::AudioUnitError::FormatNotSupported) |
coreaudio::Error::AudioCodec(_) |
coreaudio::Error::AudioFormat(_) => CreationError::FormatNotSupported,
_ => CreationError::DeviceNotAvailable,
}
}
let au_type = if cfg!(target_os = "ios") {
// The DefaultOutput unit isn't available in iOS unfortunately. RemoteIO is a sensible replacement.
// See
// https://developer.apple.com/library/content/documentation/MusicAudio/Conceptual/AudioUnitHostingGuide_iOS/UsingSpecificAudioUnits/UsingSpecificAudioUnits.html
coreaudio::audio_unit::IOType::RemoteIO
} else {
coreaudio::audio_unit::IOType::DefaultOutput
};
let mut audio_unit = AudioUnit::new(au_type).map_err(convert_error)?;
// TODO: iOS uses integer and fixed-point data
{
let inner = inner.clone();
let result = audio_unit.set_render_callback(move |args| {
// This callback is entered whenever the coreaudio engine needs to be fed data.
// Store the callback argument in the `SamplesStreamInner` and return the task
// that we're supposed to notify.
let scheduled = {
let mut inner = inner.lock().unwrap();
assert!(inner.current_callback.is_none());
inner.current_callback = Some(args);
inner.scheduled_task.take()
};
// It is important that `inner` is unlocked here.
if let Some(scheduled) = scheduled {
// Calling `unpark()` should eventually call `poll()` on the `SamplesStream`,
// which will use the data we stored in `current_callback`.
scheduled.unpark();
}
// TODO: what should happen if the callback wasn't processed? in other word, what
// if the user didn't register any handler or did a stupid thing in the
// handler (like mem::forgetting the buffer)?
Ok(())
});
result.map_err(convert_error)?;
}
audio_unit.start().map_err(convert_error)?;
let au_arc = Arc::new(Mutex::new(audio_unit));
let samples_stream = SamplesStream {
inner: inner,
audio_unit: au_arc.clone(),
};
Ok((Voice {
playing: true,
audio_unit: au_arc.clone(),
},
samples_stream))
}
#[inline]
pub fn play(&mut self) {
if !self.playing {
let mut unit = self.audio_unit.lock().unwrap();
unit.start().unwrap();
self.playing = true;
}
}
#[inline]
pub fn pause(&mut self) {
if self.playing {
let mut unit = self.audio_unit.lock().unwrap();
unit.stop().unwrap();
self.playing = false;
}
}
}