Remove the conversion system
This commit is contained in:
parent
e641ac93d8
commit
ca72d1d67e
8 changed files with 82 additions and 525 deletions
214
src/lib.rs
214
src/lib.rs
|
|
@ -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();
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue