Add rustdoc links in most of the documentation (#682)
* Add rustdoc links in most of the documentation Additionally, fix a couple of references to old renamed types still lingering in the docs :) Fixes #650 * Rustfmt on documentation changes * Make docs for impl_platform_host not build example
This commit is contained in:
parent
29999e6857
commit
7e17373e31
4 changed files with 124 additions and 100 deletions
24
src/error.rs
24
src/error.rs
|
|
@ -26,7 +26,7 @@ pub struct BackendSpecificError {
|
||||||
/// An error that might occur while attempting to enumerate the available devices on a system.
|
/// An error that might occur while attempting to enumerate the available devices on a system.
|
||||||
#[derive(Debug, Error)]
|
#[derive(Debug, Error)]
|
||||||
pub enum DevicesError {
|
pub enum DevicesError {
|
||||||
/// See the `BackendSpecificError` docs for more information about this error variant.
|
/// See the [`BackendSpecificError`] docs for more information about this error variant.
|
||||||
#[error("{err}")]
|
#[error("{err}")]
|
||||||
BackendSpecific {
|
BackendSpecific {
|
||||||
#[from]
|
#[from]
|
||||||
|
|
@ -37,7 +37,7 @@ pub enum DevicesError {
|
||||||
/// An error that may occur while attempting to retrieve a device name.
|
/// An error that may occur while attempting to retrieve a device name.
|
||||||
#[derive(Debug, Error)]
|
#[derive(Debug, Error)]
|
||||||
pub enum DeviceNameError {
|
pub enum DeviceNameError {
|
||||||
/// See the `BackendSpecificError` docs for more information about this error variant.
|
/// See the [`BackendSpecificError`] docs for more information about this error variant.
|
||||||
#[error("{err}")]
|
#[error("{err}")]
|
||||||
BackendSpecific {
|
BackendSpecific {
|
||||||
#[from]
|
#[from]
|
||||||
|
|
@ -57,7 +57,7 @@ pub enum SupportedStreamConfigsError {
|
||||||
"Invalid argument passed to the backend. For example, this happens when trying to read capture capabilities when the device does not support it."
|
"Invalid argument passed to the backend. For example, this happens when trying to read capture capabilities when the device does not support it."
|
||||||
)]
|
)]
|
||||||
InvalidArgument,
|
InvalidArgument,
|
||||||
/// See the `BackendSpecificError` docs for more information about this error variant.
|
/// See the [`BackendSpecificError`] docs for more information about this error variant.
|
||||||
#[error("{err}")]
|
#[error("{err}")]
|
||||||
BackendSpecific {
|
BackendSpecific {
|
||||||
#[from]
|
#[from]
|
||||||
|
|
@ -65,7 +65,7 @@ pub enum SupportedStreamConfigsError {
|
||||||
},
|
},
|
||||||
}
|
}
|
||||||
|
|
||||||
/// May occur when attempting to request the default input or output stream format from a `Device`.
|
/// May occur when attempting to request the default input or output stream format from a [`Device`](crate::Device).
|
||||||
#[derive(Debug, Error)]
|
#[derive(Debug, Error)]
|
||||||
pub enum DefaultStreamConfigError {
|
pub enum DefaultStreamConfigError {
|
||||||
/// The device no longer exists. This can happen if the device is disconnected while the
|
/// The device no longer exists. This can happen if the device is disconnected while the
|
||||||
|
|
@ -75,7 +75,7 @@ pub enum DefaultStreamConfigError {
|
||||||
/// Returned if e.g. the default input format was requested on an output-only audio device.
|
/// Returned if e.g. the default input format was requested on an output-only audio device.
|
||||||
#[error("The requested stream type is not supported by the device.")]
|
#[error("The requested stream type is not supported by the device.")]
|
||||||
StreamTypeNotSupported,
|
StreamTypeNotSupported,
|
||||||
/// See the `BackendSpecificError` docs for more information about this error variant.
|
/// See the [`BackendSpecificError`] docs for more information about this error variant.
|
||||||
#[error("{err}")]
|
#[error("{err}")]
|
||||||
BackendSpecific {
|
BackendSpecific {
|
||||||
#[from]
|
#[from]
|
||||||
|
|
@ -83,7 +83,7 @@ pub enum DefaultStreamConfigError {
|
||||||
},
|
},
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Error that can happen when creating a `Stream`.
|
/// Error that can happen when creating a [`Stream`](crate::Stream).
|
||||||
#[derive(Debug, Error)]
|
#[derive(Debug, Error)]
|
||||||
pub enum BuildStreamError {
|
pub enum BuildStreamError {
|
||||||
/// The device no longer exists. This can happen if the device is disconnected while the
|
/// The device no longer exists. This can happen if the device is disconnected while the
|
||||||
|
|
@ -102,7 +102,7 @@ pub enum BuildStreamError {
|
||||||
/// Occurs if adding a new Stream ID would cause an integer overflow.
|
/// Occurs if adding a new Stream ID would cause an integer overflow.
|
||||||
#[error("Adding a new stream ID would cause an overflow")]
|
#[error("Adding a new stream ID would cause an overflow")]
|
||||||
StreamIdOverflow,
|
StreamIdOverflow,
|
||||||
/// See the `BackendSpecificError` docs for more information about this error variant.
|
/// See the [`BackendSpecificError`] docs for more information about this error variant.
|
||||||
#[error("{err}")]
|
#[error("{err}")]
|
||||||
BackendSpecific {
|
BackendSpecific {
|
||||||
#[from]
|
#[from]
|
||||||
|
|
@ -110,7 +110,7 @@ pub enum BuildStreamError {
|
||||||
},
|
},
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Errors that might occur when calling `play_stream`.
|
/// Errors that might occur when calling [`Stream::play()`](crate::traits::StreamTrait::play).
|
||||||
///
|
///
|
||||||
/// As of writing this, only macOS may immediately return an error while calling this method. This
|
/// As of writing this, only macOS may immediately return an error while calling this method. This
|
||||||
/// is because both the alsa and wasapi backends only enqueue these commands and do not process
|
/// is because both the alsa and wasapi backends only enqueue these commands and do not process
|
||||||
|
|
@ -120,7 +120,7 @@ pub enum PlayStreamError {
|
||||||
/// The device associated with the stream is no longer available.
|
/// The device associated with the stream is no longer available.
|
||||||
#[error("the device associated with the stream is no longer available")]
|
#[error("the device associated with the stream is no longer available")]
|
||||||
DeviceNotAvailable,
|
DeviceNotAvailable,
|
||||||
/// See the `BackendSpecificError` docs for more information about this error variant.
|
/// See the [`BackendSpecificError`] docs for more information about this error variant.
|
||||||
#[error("{err}")]
|
#[error("{err}")]
|
||||||
BackendSpecific {
|
BackendSpecific {
|
||||||
#[from]
|
#[from]
|
||||||
|
|
@ -128,7 +128,7 @@ pub enum PlayStreamError {
|
||||||
},
|
},
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Errors that might occur when calling `pause_stream`.
|
/// Errors that might occur when calling [`Stream::pause()`](crate::traits::StreamTrait::pause).
|
||||||
///
|
///
|
||||||
/// As of writing this, only macOS may immediately return an error while calling this method. This
|
/// As of writing this, only macOS may immediately return an error while calling this method. This
|
||||||
/// is because both the alsa and wasapi backends only enqueue these commands and do not process
|
/// is because both the alsa and wasapi backends only enqueue these commands and do not process
|
||||||
|
|
@ -138,7 +138,7 @@ pub enum PauseStreamError {
|
||||||
/// The device associated with the stream is no longer available.
|
/// The device associated with the stream is no longer available.
|
||||||
#[error("the device associated with the stream is no longer available")]
|
#[error("the device associated with the stream is no longer available")]
|
||||||
DeviceNotAvailable,
|
DeviceNotAvailable,
|
||||||
/// See the `BackendSpecificError` docs for more information about this error variant.
|
/// See the [`BackendSpecificError`] docs for more information about this error variant.
|
||||||
#[error("{err}")]
|
#[error("{err}")]
|
||||||
BackendSpecific {
|
BackendSpecific {
|
||||||
#[from]
|
#[from]
|
||||||
|
|
@ -153,7 +153,7 @@ pub enum StreamError {
|
||||||
/// program is running.
|
/// program is running.
|
||||||
#[error("The requested device is no longer available. For example, it has been unplugged.")]
|
#[error("The requested device is no longer available. For example, it has been unplugged.")]
|
||||||
DeviceNotAvailable,
|
DeviceNotAvailable,
|
||||||
/// See the `BackendSpecificError` docs for more information about this error variant.
|
/// See the [`BackendSpecificError`] docs for more information about this error variant.
|
||||||
#[error("{err}")]
|
#[error("{err}")]
|
||||||
BackendSpecific {
|
BackendSpecific {
|
||||||
#[from]
|
#[from]
|
||||||
|
|
|
||||||
99
src/lib.rs
99
src/lib.rs
|
|
@ -2,28 +2,29 @@
|
||||||
//!
|
//!
|
||||||
//! Here are some concepts cpal exposes:
|
//! Here are some concepts cpal exposes:
|
||||||
//!
|
//!
|
||||||
//! - A [**Host**](./struct.Host.html) provides access to the available audio devices on the system.
|
//! - A [`Host`] provides access to the available audio devices on the system.
|
||||||
//! Some platforms have more than one host available, but every platform supported by CPAL has at
|
//! Some platforms have more than one host available, but every platform supported by CPAL has at
|
||||||
//! least one [**DefaultHost**](./struct.Host.html) that is guaranteed to be available.
|
//! least one [default_host] that is guaranteed to be available.
|
||||||
//! - A [**Device**](./struct.Device.html) is an audio device that may have any number of input and
|
//! - A [`Device`] is an audio device that may have any number of input and
|
||||||
//! output streams.
|
//! output streams.
|
||||||
//! - A [**Stream**](./struct.Stream.html) is an open flow of audio data. Input streams allow you to
|
//! - A [`Stream`] is an open flow of audio data. Input streams allow you to
|
||||||
//! receive audio data, output streams allow you to play audio data. You must choose which
|
//! receive audio data, output streams allow you to play audio data. You must choose which
|
||||||
//! **Device** will run your stream before you can create one. Often, a default device can be
|
//! [Device] will run your stream before you can create one. Often, a default device can be
|
||||||
//! retrieved via the **Host**.
|
//! retrieved via the [Host].
|
||||||
//!
|
//!
|
||||||
//! The first step is to initialise the `Host`:
|
//! The first step is to initialise the [`Host`]:
|
||||||
//!
|
//!
|
||||||
//! ```
|
//! ```
|
||||||
//! use cpal::traits::HostTrait;
|
//! use cpal::traits::HostTrait;
|
||||||
//! let host = cpal::default_host();
|
//! let host = cpal::default_host();
|
||||||
//! ```
|
//! ```
|
||||||
//!
|
//!
|
||||||
//! Then choose an available `Device`. The easiest way is to use the default input or output
|
//! Then choose an available [`Device`]. The easiest way is to use the default input or output
|
||||||
//! `Device` via the `default_input_device()` or `default_output_device()` functions. Alternatively
|
//! `Device` via the [`default_input_device()`] or [`default_output_device()`] methods on `host`.
|
||||||
//! you can enumerate all the available devices with the `devices()` function. Beware that the
|
//!
|
||||||
//! `default_*_device()` functions return an `Option` in case no device is available for that
|
//! Alternatively, you can enumerate all the available devices with the [`devices()`] method.
|
||||||
//! stream type on the system.
|
//! Beware that the `default_*_device()` functions return an `Option<Device>` in case no device
|
||||||
|
//! is available for that stream type on the system.
|
||||||
//!
|
//!
|
||||||
//! ```no_run
|
//! ```no_run
|
||||||
//! # use cpal::traits::HostTrait;
|
//! # use cpal::traits::HostTrait;
|
||||||
|
|
@ -32,15 +33,18 @@
|
||||||
//! ```
|
//! ```
|
||||||
//!
|
//!
|
||||||
//! Before we can create a stream, we must decide what the configuration of the audio stream is
|
//! Before we can create a stream, we must decide what the configuration of the audio stream is
|
||||||
//! going to be. You can query all the supported configurations with the
|
//! going to be.
|
||||||
//! `supported_input_configs()` and `supported_output_configs()` methods. These produce a list of
|
//! You can query all the supported configurations with the
|
||||||
//! `SupportedStreamConfigRange` structs which can later be turned into actual
|
//! [`supported_input_configs()`] and [`supported_output_configs()`] methods.
|
||||||
//! `SupportedStreamConfig` structs. If you don't want to query the list of configs, you can also
|
//! These produce a list of [`SupportedStreamConfigRange`] structs which can later be turned into
|
||||||
//! build your own `StreamConfig` manually, but doing so could lead to an error when building the
|
//! actual [`SupportedStreamConfig`] structs.
|
||||||
//! stream if the config is not supported by the device.
|
|
||||||
//!
|
//!
|
||||||
//! > **Note**: the `supported_input/output_configs()` methods could return an error for example if
|
//! If you don't want to query the list of configs,
|
||||||
//! > the device has been disconnected.
|
//! you can also build your own [`StreamConfig`] manually, but doing so could lead to an error when
|
||||||
|
//! building the stream if the config is not supported by the device.
|
||||||
|
//!
|
||||||
|
//! > **Note**: the `supported_input/output_configs()` methods
|
||||||
|
//! > could return an error for example if the device has been disconnected.
|
||||||
//!
|
//!
|
||||||
//! ```no_run
|
//! ```no_run
|
||||||
//! use cpal::traits::{DeviceTrait, HostTrait};
|
//! use cpal::traits::{DeviceTrait, HostTrait};
|
||||||
|
|
@ -74,8 +78,8 @@
|
||||||
//! ```
|
//! ```
|
||||||
//!
|
//!
|
||||||
//! While the stream is running, the selected audio device will periodically call the data callback
|
//! While the stream is running, the selected audio device will periodically call the data callback
|
||||||
//! that was passed to the function. The callback is passed an instance of either `&Data` or
|
//! that was passed to the function. The callback is passed an instance of either [`&Data` or
|
||||||
//! `&mut Data` depending on whether the stream is an input stream or output stream respectively.
|
//! `&mut Data`](Data) depending on whether the stream is an input stream or output stream respectively.
|
||||||
//!
|
//!
|
||||||
//! > **Note**: Creating and running a stream will *not* block the thread. On modern platforms, the
|
//! > **Note**: Creating and running a stream will *not* block the thread. On modern platforms, the
|
||||||
//! > given callback is called by a dedicated, high-priority thread responsible for delivering
|
//! > given callback is called by a dedicated, high-priority thread responsible for delivering
|
||||||
|
|
@ -112,7 +116,7 @@
|
||||||
//! ```
|
//! ```
|
||||||
//!
|
//!
|
||||||
//! Not all platforms automatically run the stream upon creation. To ensure the stream has started,
|
//! Not all platforms automatically run the stream upon creation. To ensure the stream has started,
|
||||||
//! we can use `Stream::play`.
|
//! we can use [`Stream::play`](traits::StreamTrait::play).
|
||||||
//!
|
//!
|
||||||
//! ```no_run
|
//! ```no_run
|
||||||
//! # use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
|
//! # use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
|
||||||
|
|
@ -142,6 +146,12 @@
|
||||||
//! # let stream = device.build_output_stream_raw(&config, sample_format, data_fn, err_fn, None).unwrap();
|
//! # let stream = device.build_output_stream_raw(&config, sample_format, data_fn, err_fn, None).unwrap();
|
||||||
//! stream.pause().unwrap();
|
//! stream.pause().unwrap();
|
||||||
//! ```
|
//! ```
|
||||||
|
//!
|
||||||
|
//! [`default_input_device()`]: traits::HostTrait::default_input_device
|
||||||
|
//! [`default_output_device()`]: traits::HostTrait::default_output_device
|
||||||
|
//! [`devices()`]: traits::HostTrait::devices
|
||||||
|
//! [`supported_input_configs()`]: traits::DeviceTrait::supported_input_configs
|
||||||
|
//! [`supported_output_configs()`]: traits::DeviceTrait::supported_output_configs
|
||||||
|
|
||||||
#![recursion_limit = "2048"]
|
#![recursion_limit = "2048"]
|
||||||
|
|
||||||
|
|
@ -212,11 +222,15 @@ pub type FrameCount = u32;
|
||||||
|
|
||||||
/// The buffer size used by the device.
|
/// The buffer size used by the device.
|
||||||
///
|
///
|
||||||
/// Default is used when no specific buffer size is set and uses the default
|
/// [`Default`] is used when no specific buffer size is set and uses the default
|
||||||
/// behavior of the given host. Note, the default buffer size may be surprisingly
|
/// behavior of the given host. Note, the default buffer size may be surprisingly
|
||||||
/// large, leading to latency issues. If low latency is desired, Fixed(BufferSize)
|
/// large, leading to latency issues. If low latency is desired, [`Fixed(FrameCount)`]
|
||||||
/// should be used in accordance with the SupportedBufferSize range produced by
|
/// should be used in accordance with the [`SupportedBufferSize`] range produced by
|
||||||
/// the SupportedStreamConfig API.
|
/// the [`SupportedStreamConfig`] API.
|
||||||
|
///
|
||||||
|
/// [`Default`]: BufferSize::Default
|
||||||
|
/// [`Fixed(FrameCount)`]: BufferSize::Fixed
|
||||||
|
/// [`SupportedStreamConfig`]: SupportedStreamConfig::buffer_size
|
||||||
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
|
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
|
||||||
pub enum BufferSize {
|
pub enum BufferSize {
|
||||||
Default,
|
Default,
|
||||||
|
|
@ -264,7 +278,7 @@ pub enum SupportedBufferSize {
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Describes a range of supported stream configurations, retrieved via the
|
/// Describes a range of supported stream configurations, retrieved via the
|
||||||
/// `Device::supported_input/output_configs` method.
|
/// [`Device::supported_input/output_configs`](traits::DeviceTrait#required-methods) method.
|
||||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||||
pub struct SupportedStreamConfigRange {
|
pub struct SupportedStreamConfigRange {
|
||||||
pub(crate) channels: ChannelCount,
|
pub(crate) channels: ChannelCount,
|
||||||
|
|
@ -279,7 +293,8 @@ pub struct SupportedStreamConfigRange {
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Describes a single supported stream configuration, retrieved via either a
|
/// Describes a single supported stream configuration, retrieved via either a
|
||||||
/// `SupportedStreamConfigRange` instance or one of the `Device::default_input/output_config` methods.
|
/// [`SupportedStreamConfigRange`] instance or one of the
|
||||||
|
/// [`Device::default_input/output_config`](traits::DeviceTrait#required-methods) methods.
|
||||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||||
pub struct SupportedStreamConfig {
|
pub struct SupportedStreamConfig {
|
||||||
channels: ChannelCount,
|
channels: ChannelCount,
|
||||||
|
|
@ -306,7 +321,7 @@ pub struct Data {
|
||||||
/// 2. The same time source used to generate timestamps for a stream's underlying audio data
|
/// 2. The same time source used to generate timestamps for a stream's underlying audio data
|
||||||
/// callback.
|
/// callback.
|
||||||
///
|
///
|
||||||
/// **StreamInstant** represents a duration since some unspecified origin occurring either before
|
/// `StreamInstant` represents a duration since some unspecified origin occurring either before
|
||||||
/// or equal to the moment the stream from which it was created begins.
|
/// or equal to the moment the stream from which it was created begins.
|
||||||
///
|
///
|
||||||
/// ## Host `StreamInstant` Sources
|
/// ## Host `StreamInstant` Sources
|
||||||
|
|
@ -427,7 +442,7 @@ impl StreamInstant {
|
||||||
/// Returns the instant in time one `duration` ago.
|
/// Returns the instant in time one `duration` ago.
|
||||||
///
|
///
|
||||||
/// Returns `None` if the resulting instant would underflow. As a result, it is important to
|
/// Returns `None` if the resulting instant would underflow. As a result, it is important to
|
||||||
/// consider that on some platforms the `StreamInstant` may begin at `0` from the moment the
|
/// consider that on some platforms the [`StreamInstant`] may begin at `0` from the moment the
|
||||||
/// source stream is created.
|
/// source stream is created.
|
||||||
pub fn sub(&self, duration: Duration) -> Option<Self> {
|
pub fn sub(&self, duration: Duration) -> Option<Self> {
|
||||||
self.as_nanos()
|
self.as_nanos()
|
||||||
|
|
@ -515,24 +530,24 @@ impl Data {
|
||||||
/// The full length of the buffer in samples.
|
/// The full length of the buffer in samples.
|
||||||
///
|
///
|
||||||
/// The returned length is the same length as the slice of type `T` that would be returned via
|
/// The returned length is the same length as the slice of type `T` that would be returned via
|
||||||
/// `as_slice` given a sample type that matches the inner sample format.
|
/// [`as_slice`](Self::as_slice) given a sample type that matches the inner sample format.
|
||||||
pub fn len(&self) -> usize {
|
pub fn len(&self) -> usize {
|
||||||
self.len
|
self.len
|
||||||
}
|
}
|
||||||
|
|
||||||
/// The raw slice of memory representing the underlying audio data as a slice of bytes.
|
/// The raw slice of memory representing the underlying audio data as a slice of bytes.
|
||||||
///
|
///
|
||||||
/// It is up to the user to interpret the slice of memory based on `Data::sample_format`.
|
/// It is up to the user to interpret the slice of memory based on [`Data::sample_format`].
|
||||||
pub fn bytes(&self) -> &[u8] {
|
pub fn bytes(&self) -> &[u8] {
|
||||||
let len = self.len * self.sample_format.sample_size();
|
let len = self.len * self.sample_format.sample_size();
|
||||||
// The safety of this block relies on correct construction of the `Data` instance. See
|
// The safety of this block relies on correct construction of the `Data` instance.
|
||||||
// the unsafe `from_parts` constructor for these requirements.
|
// See the unsafe `from_parts` constructor for these requirements.
|
||||||
unsafe { std::slice::from_raw_parts(self.data as *const u8, len) }
|
unsafe { std::slice::from_raw_parts(self.data as *const u8, len) }
|
||||||
}
|
}
|
||||||
|
|
||||||
/// The raw slice of memory representing the underlying audio data as a slice of bytes.
|
/// The raw slice of memory representing the underlying audio data as a slice of bytes.
|
||||||
///
|
///
|
||||||
/// It is up to the user to interpret the slice of memory based on `Data::sample_format`.
|
/// It is up to the user to interpret the slice of memory based on [`Data::sample_format`].
|
||||||
pub fn bytes_mut(&mut self) -> &mut [u8] {
|
pub fn bytes_mut(&mut self) -> &mut [u8] {
|
||||||
let len = self.len * self.sample_format.sample_size();
|
let len = self.len * self.sample_format.sample_size();
|
||||||
// The safety of this block relies on correct construction of the `Data` instance. See
|
// The safety of this block relies on correct construction of the `Data` instance. See
|
||||||
|
|
@ -615,10 +630,12 @@ impl SupportedStreamConfigRange {
|
||||||
self.sample_format
|
self.sample_format
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Retrieve a `SupportedStreamConfig` with the given sample rate and buffer size.
|
/// Retrieve a [`SupportedStreamConfig`] with the given sample rate and buffer size.
|
||||||
///
|
///
|
||||||
/// **panic!**s if the given `sample_rate` is outside the range specified within this
|
/// # Panics
|
||||||
/// `SupportedStreamConfigRange` instance.
|
///
|
||||||
|
/// Panics if the given `sample_rate` is outside the range specified within this
|
||||||
|
/// [`SupportedStreamConfigRange`] instance.
|
||||||
pub fn with_sample_rate(self, sample_rate: SampleRate) -> SupportedStreamConfig {
|
pub fn with_sample_rate(self, sample_rate: SampleRate) -> SupportedStreamConfig {
|
||||||
assert!(self.min_sample_rate <= sample_rate && sample_rate <= self.max_sample_rate);
|
assert!(self.min_sample_rate <= sample_rate && sample_rate <= self.max_sample_rate);
|
||||||
SupportedStreamConfig {
|
SupportedStreamConfig {
|
||||||
|
|
@ -629,7 +646,7 @@ impl SupportedStreamConfigRange {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Turns this `SupportedStreamConfigRange` into a `SupportedStreamConfig` corresponding to the maximum samples rate.
|
/// Turns this [`SupportedStreamConfigRange`] into a [`SupportedStreamConfig`] corresponding to the maximum samples rate.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn with_max_sample_rate(self) -> SupportedStreamConfig {
|
pub fn with_max_sample_rate(self) -> SupportedStreamConfig {
|
||||||
SupportedStreamConfig {
|
SupportedStreamConfig {
|
||||||
|
|
@ -640,7 +657,7 @@ impl SupportedStreamConfigRange {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// A comparison function which compares two `SupportedStreamConfigRange`s in terms of their priority of
|
/// A comparison function which compares two [`SupportedStreamConfigRange`]s in terms of their priority of
|
||||||
/// use as a default stream format.
|
/// use as a default stream format.
|
||||||
///
|
///
|
||||||
/// Some backends do not provide a default stream format for their audio devices. In these
|
/// Some backends do not provide a default stream format for their audio devices. In these
|
||||||
|
|
|
||||||
|
|
@ -1,35 +1,37 @@
|
||||||
//! Platform-specific items.
|
//! Platform-specific items.
|
||||||
//!
|
//!
|
||||||
//! This module also contains the implementation of the platform's dynamically dispatched `Host`
|
//! This module also contains the implementation of the platform's dynamically dispatched [`Host`]
|
||||||
//! type and its associated `Device`, `StreamId` and other associated types. These
|
//! type and its associated [`Device`], [`Stream`] and other associated types. These
|
||||||
//! types are useful in the case that users require switching between audio host APIs at runtime.
|
//! types are useful in the case that users require switching between audio host APIs at runtime.
|
||||||
|
|
||||||
#[doc(inline)]
|
#[doc(inline)]
|
||||||
pub use self::platform_impl::*;
|
pub use self::platform_impl::*;
|
||||||
|
|
||||||
// A macro to assist with implementing a platform's dynamically dispatched `Host` type.
|
/// A macro to assist with implementing a platform's dynamically dispatched [`Host`] type.
|
||||||
//
|
///
|
||||||
// These dynamically dispatched types are necessary to allow for users to switch between hosts at
|
/// These dynamically dispatched types are necessary to allow for users to switch between hosts at
|
||||||
// runtime.
|
/// runtime.
|
||||||
//
|
///
|
||||||
// For example the invocation `impl_platform_host(Wasapi wasapi "WASAPI", Asio asio "ASIO")`,
|
/// For example the invocation `impl_platform_host(Wasapi wasapi "WASAPI", Asio asio "ASIO")`,
|
||||||
// this macro should expand to:
|
/// this macro should expand to:
|
||||||
//
|
///
|
||||||
// ```
|
// This sample code block is marked as text because it's not a valid test,
|
||||||
// pub enum HostId {
|
// it's just illustrative. (see rust issue #96573)
|
||||||
// Wasapi,
|
/// ```text
|
||||||
// Asio,
|
/// pub enum HostId {
|
||||||
// }
|
/// Wasapi,
|
||||||
//
|
/// Asio,
|
||||||
// pub enum Host {
|
/// }
|
||||||
// Wasapi(crate::host::wasapi::Host),
|
///
|
||||||
// Asio(crate::host::asio::Host),
|
/// pub enum Host {
|
||||||
// }
|
/// Wasapi(crate::host::wasapi::Host),
|
||||||
// ```
|
/// Asio(crate::host::asio::Host),
|
||||||
//
|
/// }
|
||||||
// And so on for Device, Devices, Host, StreamId, SupportedInputConfigs,
|
/// ```
|
||||||
// SupportedOutputConfigs and all their necessary trait implementations.
|
///
|
||||||
// ```
|
/// And so on for Device, Devices, Host, Stream, SupportedInputConfigs,
|
||||||
|
/// SupportedOutputConfigs and all their necessary trait implementations.
|
||||||
|
///
|
||||||
macro_rules! impl_platform_host {
|
macro_rules! impl_platform_host {
|
||||||
($($(#[cfg($feat: meta)])? $HostVariant:ident $host_mod:ident $host_name:literal),*) => {
|
($($(#[cfg($feat: meta)])? $HostVariant:ident $host_mod:ident $host_name:literal),*) => {
|
||||||
/// All hosts supported by CPAL on this platform.
|
/// All hosts supported by CPAL on this platform.
|
||||||
|
|
@ -40,27 +42,27 @@ macro_rules! impl_platform_host {
|
||||||
)*
|
)*
|
||||||
];
|
];
|
||||||
|
|
||||||
/// The platform's dynamically dispatched **Host** type.
|
/// The platform's dynamically dispatched `Host` type.
|
||||||
///
|
///
|
||||||
/// An instance of this **Host** type may represent one of the **Host**s available
|
/// An instance of this `Host` type may represent one of the `Host`s available
|
||||||
/// on the platform.
|
/// on the platform.
|
||||||
///
|
///
|
||||||
/// Use this type if you require switching between available hosts at runtime.
|
/// Use this type if you require switching between available hosts at runtime.
|
||||||
///
|
///
|
||||||
/// This type may be constructed via the **host_from_id** function. **HostId**s may
|
/// This type may be constructed via the [`host_from_id`] function. [`HostId`]s may
|
||||||
/// be acquired via the **ALL_HOSTS** const, and the **available_hosts** function.
|
/// be acquired via the [`ALL_HOSTS`] const, and the [`available_hosts`] function.
|
||||||
pub struct Host(HostInner);
|
pub struct Host(HostInner);
|
||||||
|
|
||||||
/// The **Device** implementation associated with the platform's dynamically dispatched
|
/// The `Device` implementation associated with the platform's dynamically dispatched
|
||||||
/// **Host** type.
|
/// [`Host`] type.
|
||||||
pub struct Device(DeviceInner);
|
pub struct Device(DeviceInner);
|
||||||
|
|
||||||
/// The **Devices** iterator associated with the platform's dynamically dispatched **Host**
|
/// The `Devices` iterator associated with the platform's dynamically dispatched [`Host`]
|
||||||
/// type.
|
/// type.
|
||||||
pub struct Devices(DevicesInner);
|
pub struct Devices(DevicesInner);
|
||||||
|
|
||||||
/// The **Stream** implementation associated with the platform's dynamically dispatched
|
/// The `Stream` implementation associated with the platform's dynamically dispatched
|
||||||
/// **Host** type.
|
/// [`Host`] type.
|
||||||
// Streams cannot be `Send` or `Sync` if we plan to support Android's AAudio API. This is
|
// Streams cannot be `Send` or `Sync` if we plan to support Android's AAudio API. This is
|
||||||
// because the stream API is not thread-safe, and the API prohibits calling certain
|
// because the stream API is not thread-safe, and the API prohibits calling certain
|
||||||
// functions within the callback.
|
// functions within the callback.
|
||||||
|
|
@ -68,12 +70,12 @@ macro_rules! impl_platform_host {
|
||||||
// TODO: Confirm this and add more specific detail and references.
|
// TODO: Confirm this and add more specific detail and references.
|
||||||
pub struct Stream(StreamInner, crate::platform::NotSendSyncAcrossAllPlatforms);
|
pub struct Stream(StreamInner, crate::platform::NotSendSyncAcrossAllPlatforms);
|
||||||
|
|
||||||
/// The **SupportedInputConfigs** iterator associated with the platform's dynamically
|
/// The `SupportedInputConfigs` iterator associated with the platform's dynamically
|
||||||
/// dispatched **Host** type.
|
/// dispatched [`Host`] type.
|
||||||
pub struct SupportedInputConfigs(SupportedInputConfigsInner);
|
pub struct SupportedInputConfigs(SupportedInputConfigsInner);
|
||||||
|
|
||||||
/// The **SupportedOutputConfigs** iterator associated with the platform's dynamically
|
/// The `SupportedOutputConfigs` iterator associated with the platform's dynamically
|
||||||
/// dispatched **Host** type.
|
/// dispatched [`Host`] type.
|
||||||
pub struct SupportedOutputConfigs(SupportedOutputConfigsInner);
|
pub struct SupportedOutputConfigs(SupportedOutputConfigsInner);
|
||||||
|
|
||||||
/// Unique identifier for available hosts on the platform.
|
/// Unique identifier for available hosts on the platform.
|
||||||
|
|
@ -85,7 +87,7 @@ macro_rules! impl_platform_host {
|
||||||
)*
|
)*
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Contains a platform specific `Device` implementation.
|
/// Contains a platform specific [`Device`] implementation.
|
||||||
pub enum DeviceInner {
|
pub enum DeviceInner {
|
||||||
$(
|
$(
|
||||||
$(#[cfg($feat)])?
|
$(#[cfg($feat)])?
|
||||||
|
|
@ -93,7 +95,7 @@ macro_rules! impl_platform_host {
|
||||||
)*
|
)*
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Contains a platform specific `Devices` implementation.
|
/// Contains a platform specific [`Devices`] implementation.
|
||||||
pub enum DevicesInner {
|
pub enum DevicesInner {
|
||||||
$(
|
$(
|
||||||
$(#[cfg($feat)])?
|
$(#[cfg($feat)])?
|
||||||
|
|
@ -101,7 +103,7 @@ macro_rules! impl_platform_host {
|
||||||
)*
|
)*
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Contains a platform specific `Host` implementation.
|
/// Contains a platform specific [`Host`] implementation.
|
||||||
pub enum HostInner {
|
pub enum HostInner {
|
||||||
$(
|
$(
|
||||||
$(#[cfg($feat)])?
|
$(#[cfg($feat)])?
|
||||||
|
|
@ -109,7 +111,7 @@ macro_rules! impl_platform_host {
|
||||||
)*
|
)*
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Contains a platform specific `Stream` implementation.
|
/// Contains a platform specific [`Stream`] implementation.
|
||||||
pub enum StreamInner {
|
pub enum StreamInner {
|
||||||
$(
|
$(
|
||||||
$(#[cfg($feat)])?
|
$(#[cfg($feat)])?
|
||||||
|
|
@ -181,7 +183,7 @@ macro_rules! impl_platform_host {
|
||||||
}
|
}
|
||||||
|
|
||||||
impl Host {
|
impl Host {
|
||||||
/// The unique identifier associated with this host.
|
/// The unique identifier associated with this `Host`.
|
||||||
pub fn id(&self) -> HostId {
|
pub fn id(&self) -> HostId {
|
||||||
match self.0 {
|
match self.0 {
|
||||||
$(
|
$(
|
||||||
|
|
|
||||||
|
|
@ -9,7 +9,7 @@ use crate::{
|
||||||
SupportedStreamConfigRange, SupportedStreamConfigsError,
|
SupportedStreamConfigRange, SupportedStreamConfigsError,
|
||||||
};
|
};
|
||||||
|
|
||||||
/// A **Host** provides access to the available audio devices on the system.
|
/// A [`Host`] provides access to the available audio devices on the system.
|
||||||
///
|
///
|
||||||
/// Each platform may have a number of available hosts depending on the system, each with their own
|
/// Each platform may have a number of available hosts depending on the system, each with their own
|
||||||
/// pros and cons.
|
/// pros and cons.
|
||||||
|
|
@ -28,6 +28,8 @@ use crate::{
|
||||||
/// JACK is yet another host API that is more suitable to pro-audio applications, however it is
|
/// JACK is yet another host API that is more suitable to pro-audio applications, however it is
|
||||||
/// less readily available by default in many Linux distributions and is known to be tricky to
|
/// less readily available by default in many Linux distributions and is known to be tricky to
|
||||||
/// set up.
|
/// set up.
|
||||||
|
///
|
||||||
|
/// [`Host`]: crate::Host
|
||||||
pub trait HostTrait {
|
pub trait HostTrait {
|
||||||
/// The type used for enumerating available devices by the host.
|
/// The type used for enumerating available devices by the host.
|
||||||
type Devices: Iterator<Item = Self::Device>;
|
type Devices: Iterator<Item = Self::Device>;
|
||||||
|
|
@ -37,7 +39,7 @@ pub trait HostTrait {
|
||||||
/// Whether or not the host is available on the system.
|
/// Whether or not the host is available on the system.
|
||||||
fn is_available() -> bool;
|
fn is_available() -> bool;
|
||||||
|
|
||||||
/// An iterator yielding all `Device`s currently available to the host on the system.
|
/// An iterator yielding all [`Device`](DeviceTrait)s currently available to the host on the system.
|
||||||
///
|
///
|
||||||
/// Can be empty if the system does not support audio in general.
|
/// Can be empty if the system does not support audio in general.
|
||||||
fn devices(&self) -> Result<Self::Devices, DevicesError>;
|
fn devices(&self) -> Result<Self::Devices, DevicesError>;
|
||||||
|
|
@ -90,7 +92,10 @@ pub trait DeviceTrait {
|
||||||
type SupportedInputConfigs: Iterator<Item = SupportedStreamConfigRange>;
|
type SupportedInputConfigs: Iterator<Item = SupportedStreamConfigRange>;
|
||||||
/// The iterator type yielding supported output stream formats.
|
/// The iterator type yielding supported output stream formats.
|
||||||
type SupportedOutputConfigs: Iterator<Item = SupportedStreamConfigRange>;
|
type SupportedOutputConfigs: Iterator<Item = SupportedStreamConfigRange>;
|
||||||
/// The stream type created by `build_input_stream_raw` and `build_output_stream_raw`.
|
/// The stream type created by [`build_input_stream_raw`] and [`build_output_stream_raw`].
|
||||||
|
///
|
||||||
|
/// [`build_input_stream_raw`]: Self::build_input_stream_raw
|
||||||
|
/// [`build_output_stream_raw`]: Self::build_output_stream_raw
|
||||||
type Stream: StreamTrait;
|
type Stream: StreamTrait;
|
||||||
|
|
||||||
/// The human-readable name of the device.
|
/// The human-readable name of the device.
|
||||||
|
|
@ -199,7 +204,7 @@ pub trait DeviceTrait {
|
||||||
E: FnMut(StreamError) + Send + 'static;
|
E: FnMut(StreamError) + Send + 'static;
|
||||||
}
|
}
|
||||||
|
|
||||||
/// A stream created from `Device`, with methods to control playback.
|
/// A stream created from [`Device`](DeviceTrait), with methods to control playback.
|
||||||
pub trait StreamTrait {
|
pub trait StreamTrait {
|
||||||
/// Run the stream.
|
/// Run the stream.
|
||||||
///
|
///
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue