PistonDevelopers/piston — pull request #345 by mitchmindtree (2014-06-19 13:17:26+00:00)
Title: Added PortAudio backend and SoundStream trait for non-blocking, real-time audio IO.

SoundStream
------------

Firstly, sorry about the single huge commit! This has involved lots of experimenting and I wasn't sure I'd be able to get something working at all for a while there. Alas, she's working smoothly now :-)

Summary
-------
The primary purpose of this PR is to add the ability to implement a non-blocking, real-time audio stream. I've added an example called "soundstream.rs" which demonstrates a couple of the features. An important thing to note is that the SoundStream can run asynchronously to the main Game trait. There is no unsafe code or locking required at all and the back-end is setup so that the SoundStream can easily receive all "interactive" style events (keyboard and mouse) from the main GUI task (you can see this happening in the example). It is also exposed in a way so that setting up your own channels to send other unique data should be trivial. None of these changes should conflict with the sdl2 sound / music traits at all, so we can still use those for basic sample/song loading and playback too.

Main changes
------
- Separated `InteractiveEvents` from `GameEvents` for easily sending across tasks ( let me know what you think of this bvssvni, it didn't impact too much, but we can change it back to `GameEvent<'static>`s if you prefer :-) )
- `SoundStream` trait - see example for demonstration of implementation (it's quite similar to the `Game` trait itself, however it runs in a separate task on it's own loop).
- PortAudio backend `pa_audio_back_end.rs` - this module contains a function `soundstreamer` which takes a mutable reference to a type that implements SoundStream. It will provide the callbacks and event handling using the PortAudio bindings.

@bvssvni: I know that we discussed "Raw" as a name to represent this previously, however I think SoundStream is a lot more descriptive of the real-time audio IO role. Let me know your thoughts :+1:

Dependency
----------
To get this working you'll have to:
- [download and install PortAudio] (http://www.portaudio.com/download.html)
- add [these PortAudio rust bindings by Jeremy Letang] (https://github.com/JeremyLetang/rust-portaudio) to your target.

Note
-----
Let me know your thoughts! I've made it as tight and compact as I could (not easy with safe, threaded audio :ghost: ) and I feel like it has turned out quite user friendly. However it is my first time implementing a non-blocking audio stream - i'm totally open for feedback! Also, it might be a good idea for someone else to test this before merging (I could only test on my own osx 10.9 machine) but it should work fine on anything :-)