Remove the conversion system

This commit is contained in:
Pierre Krieger 2015-08-20 14:38:25 +02:00
parent e641ac93d8
commit ca72d1d67e
8 changed files with 82 additions and 525 deletions

View file

@ -7,21 +7,10 @@ In order to play a sound, first you need to create a `Voice`.
let mut voice = cpal::Voice::new();
```
Then you must send raw samples to it by calling `append_data`.
This function takes three parameters: the number of channels, the number of samples
that must be played per second, and the number of samples that you have available.
Then you must send raw samples to it by calling `append_data`. You must take the number of channels
and samples rate into account when writing the data.
You can then fill the buffer with the data.
```no_run
# let mut voice = cpal::Voice::new();
let mut buffer: cpal::Buffer<f32> = voice.append_data(2, cpal::SamplesRate(44100), 1024);
// filling the buffer with 0s
for e in buffer.iter_mut() {
*e = 0.0f32;
}
```
TODO: add example
**Important**: the `append_data` function can return a buffer shorter than what you requested.
This is the case if the device doesn't have enough space available. **It happens very often**,
@ -38,21 +27,11 @@ The audio device of the user will read the buffer that you sent, and play it. If
reaches the end of the data, it will stop playing. You must continuously fill the buffer by
calling `append_data` repeatedly if you don't want the audio to stop playing.
# Native format
Each `Voice` is bound to a specific number of channels, samples rate, and samples format.
If you call `append_data` with values different than these, then cpal will automatically perform
a conversion on your data.
If you have the possibility, you should try to match the format of the voice.
*/
pub use samples_formats::{SampleFormat, Sample};
use std::ops::{Deref, DerefMut};
mod conversions;
mod samples_formats;
#[cfg(target_os = "linux")]
@ -71,20 +50,6 @@ mod cpal_impl;
#[path="null/mod.rs"]
mod cpal_impl;
/// Controls a sound output. A typical application has one `Voice` for each sound
/// it wants to output.
///
/// A voice must be periodically filled with new data by calling `append_data`, or the sound
/// will stop playing.
///
/// Each `Voice` is bound to a specific number of channels, samples rate, and samples format,
/// which can be retreived by calling `get_channels`, `get_samples_rate` and `get_samples_format`.
/// If you call `append_data` with values different than these, then cpal will automatically
/// perform a conversion on your data.
///
/// If you have the possibility, you should try to match the format of the voice.
pub struct Voice(cpal_impl::Voice);
/// Number of channels.
pub type ChannelsCount = u16;
@ -100,21 +65,34 @@ pub struct SamplesRate(pub u32);
pub struct Buffer<'a, T: 'a> where T: Sample {
// also contains something, taken by `Drop`
target: Option<cpal_impl::Buffer<'a, T>>,
// if this is non-none, then the data will be written to `conversion.intermediate_buffer`
// instead of `target`, and the conversion will be done in buffer's destructor
conversion: Option<RequiredConversion<T>>,
}
struct RequiredConversion<T> {
intermediate_buffer: Vec<T>,
from_sample_rate: SamplesRate,
to_sample_rate: SamplesRate,
to_format: SampleFormat,
from_channels: ChannelsCount,
to_channels: ChannelsCount,
/// This is the struct that is provided to you by cpal when you want to write samples to a buffer.
///
/// Since the type of data is only known at runtime, you have to fill the right buffer.
pub enum UnknownTypeBuffer<'a> {
/// Samples whose format is `u16`.
U16(Buffer<'a, u16>),
/// Samples whose format is `i16`.
I16(Buffer<'a, i16>),
/// Samples whose format is `f32`.
F32(Buffer<'a, f32>),
}
/// Controls a sound output. A typical application has one `Voice` for each sound
/// it wants to output.
///
/// A voice must be periodically filled with new data by calling `append_data`, or the sound
/// will stop playing.
///
/// Each `Voice` is bound to a specific number of channels, samples rate, and samples format,
/// which can be retreived by calling `get_channels`, `get_samples_rate` and `get_samples_format`.
/// If you call `append_data` with values different than these, then cpal will automatically
/// perform a conversion on your data.
///
/// If you have the possibility, you should try to match the format of the voice.
pub struct Voice(cpal_impl::Voice);
impl Voice {
/// Builds a new channel.
pub fn new() -> Voice {
@ -148,11 +126,11 @@ impl Voice {
/// Adds some PCM data to the voice's buffer.
///
/// This function returns a `Buffer` object that must be filled with the audio data.
/// This function indirectly returns a `Buffer` object that must be filled with the audio data.
/// The size of the buffer being returned depends on the current state of the backend
/// and can't be known in advance. However it is never greater than `max_elements`.
/// and can't be known in advance. However it is never greater than `max_samples`.
///
/// You must fill the buffer *entirely*, so do not set `max_elements` to a value greater
/// You must fill the buffer *entirely*, so do not set `max_samples` to a value greater
/// than the amount of data available to you.
///
/// Channels are interleaved. For example if you have two channels, you must write
@ -160,65 +138,23 @@ impl Voice {
/// then the second sample of the first channel, then the second sample of the second
/// channel, etc.
///
/// ## Parameters
///
/// * `channels`: number of channels (1 for mono, 2 for stereo, etc.)
/// * `samples_rate`: number of samples that must be played by second for each channel
/// * `max_elements`: maximum size of the returned buffer
///
/// ## Panic
///
/// Panics if `max_elements` is 0 or is not a multiple of `channels`.
/// Panics if `max_samples` is 0.
///
pub fn append_data<'a, T>(&'a mut self, channels: ChannelsCount,
samples_rate: SamplesRate, max_elements: usize)
-> Buffer<'a, T> where T: Sample + Clone
{
assert!(max_elements != 0);
assert!(max_elements % channels as usize == 0);
pub fn append_data(&mut self, max_samples: usize) -> UnknownTypeBuffer {
assert!(max_samples != 0);
let target_samples_rate = self.0.get_samples_rate();
let target_channels = self.0.get_channels();
let source_samples_format = Sample::get_format(None::<T>);
let target_samples_format = self.0.get_samples_format();
// if we need to convert the incoming data
if samples_rate != target_samples_rate || channels != target_channels ||
source_samples_format != target_samples_format
{
let max_elements = max_elements * target_channels as usize / channels as usize;
let max_elements = max_elements * target_samples_rate.0 as usize /
samples_rate.0 as usize;
let mut target_buffer = self.0.append_data(max_elements);
// computing the length of the intermediary buffer
let intermediate_buffer_length = target_buffer.get_buffer().len();
let intermediate_buffer_length = intermediate_buffer_length * channels as usize /
target_channels as usize;
let intermediate_buffer_length = intermediate_buffer_length * samples_rate.0 as usize /
target_samples_rate.0 as usize;
let intermediate_buffer = std::iter::repeat(unsafe { std::mem::uninitialized() })
.take(intermediate_buffer_length).collect();
Buffer {
target: Some(target_buffer),
conversion: Some(RequiredConversion {
intermediate_buffer: intermediate_buffer,
from_sample_rate: samples_rate,
to_sample_rate: target_samples_rate,
to_format: target_samples_format,
from_channels: channels,
to_channels: target_channels,
}),
}
} else {
Buffer {
target: Some(self.0.append_data(max_elements)),
conversion: None,
}
match self.get_samples_format() {
SampleFormat::U16 => UnknownTypeBuffer::U16(Buffer {
target: Some(self.0.append_data(max_samples))
}),
SampleFormat::I16 => UnknownTypeBuffer::I16(Buffer {
target: Some(self.0.append_data(max_samples))
}),
SampleFormat::F32 => UnknownTypeBuffer::F32(Buffer {
target: Some(self.0.append_data(max_samples))
}),
}
}
@ -252,74 +188,12 @@ impl<'a, T> Deref for Buffer<'a, T> where T: Sample {
impl<'a, T> DerefMut for Buffer<'a, T> where T: Sample {
fn deref_mut(&mut self) -> &mut [T] {
if let Some(ref mut conversion) = self.conversion {
&mut conversion.intermediate_buffer
} else {
self.target.as_mut().unwrap().get_buffer()
}
self.target.as_mut().unwrap().get_buffer()
}
}
impl<'a, T> Drop for Buffer<'a, T> where T: Sample {
fn drop(&mut self) {
if let Some(conversion) = self.conversion.take() {
let buffer = conversion.intermediate_buffer;
let buffer = if conversion.from_channels != conversion.to_channels {
conversions::convert_channels(&buffer, conversion.from_channels,
conversion.to_channels)
} else {
buffer
};
let buffer = if conversion.from_sample_rate != conversion.to_sample_rate {
conversions::convert_samples_rate(&buffer, conversion.from_sample_rate,
conversion.to_sample_rate,
conversion.to_channels)
} else {
buffer
};
let output = self.target.as_mut().unwrap().get_buffer();
assert!(buffer.len() == output.len(), "Buffers length mismatch: {} vs {}", buffer.len(), output.len());
macro_rules! write_to_buf(
($buf:expr, $output:expr, $ty:ty) => ({
use std::borrow::Cow;
let output: &mut [$ty] = unsafe { std::mem::transmute($output) };
match $buf {
Cow::Borrowed(buf) => {
for (i, o) in buf.iter().zip(output.iter_mut()) {
*o = *i;
}
},
Cow::Owned(buf) => {
for (i, o) in buf.into_iter().zip(output.iter_mut()) {
*o = i;
}
}
}
})
);
match conversion.to_format {
SampleFormat::I16 => {
let buffer = Sample::to_vec_i16(&buffer);
write_to_buf!(buffer, output, i16);
},
SampleFormat::U16 => {
let buffer = Sample::to_vec_u16(&buffer);
write_to_buf!(buffer, output, u16);
},
SampleFormat::F32 => {
let buffer = Sample::to_vec_f32(&buffer);
write_to_buf!(buffer, output, f32);
},
}
}
self.target.take().unwrap().finish();
}
}