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.
|
||||
#[derive(Debug, Error)]
|
||||
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}")]
|
||||
BackendSpecific {
|
||||
#[from]
|
||||
|
|
@ -37,7 +37,7 @@ pub enum DevicesError {
|
|||
/// An error that may occur while attempting to retrieve a device name.
|
||||
#[derive(Debug, Error)]
|
||||
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}")]
|
||||
BackendSpecific {
|
||||
#[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."
|
||||
)]
|
||||
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}")]
|
||||
BackendSpecific {
|
||||
#[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)]
|
||||
pub enum DefaultStreamConfigError {
|
||||
/// 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.
|
||||
#[error("The requested stream type is not supported by the device.")]
|
||||
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}")]
|
||||
BackendSpecific {
|
||||
#[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)]
|
||||
pub enum BuildStreamError {
|
||||
/// 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.
|
||||
#[error("Adding a new stream ID would cause an overflow")]
|
||||
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}")]
|
||||
BackendSpecific {
|
||||
#[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
|
||||
/// 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.
|
||||
#[error("the device associated with the stream is no longer available")]
|
||||
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}")]
|
||||
BackendSpecific {
|
||||
#[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
|
||||
/// 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.
|
||||
#[error("the device associated with the stream is no longer available")]
|
||||
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}")]
|
||||
BackendSpecific {
|
||||
#[from]
|
||||
|
|
@ -153,7 +153,7 @@ pub enum StreamError {
|
|||
/// program is running.
|
||||
#[error("The requested device is no longer available. For example, it has been unplugged.")]
|
||||
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}")]
|
||||
BackendSpecific {
|
||||
#[from]
|
||||
|
|
|
|||
99
src/lib.rs
99
src/lib.rs
|
|
@ -2,28 +2,29 @@
|
|||
//!
|
||||
//! 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
|
||||
//! least one [**DefaultHost**](./struct.Host.html) that is guaranteed to be available.
|
||||
//! - A [**Device**](./struct.Device.html) is an audio device that may have any number of input and
|
||||
//! least one [default_host] that is guaranteed to be available.
|
||||
//! - A [`Device`] is an audio device that may have any number of input and
|
||||
//! 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
|
||||
//! **Device** will run your stream before you can create one. Often, a default device can be
|
||||
//! retrieved via the **Host**.
|
||||
//! [Device] will run your stream before you can create one. Often, a default device can be
|
||||
//! retrieved via the [Host].
|
||||
//!
|
||||
//! The first step is to initialise the `Host`:
|
||||
//! The first step is to initialise the [`Host`]:
|
||||
//!
|
||||
//! ```
|
||||
//! use cpal::traits::HostTrait;
|
||||
//! let host = cpal::default_host();
|
||||
//! ```
|
||||
//!
|
||||
//! 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
|
||||
//! 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
|
||||
//! stream type on the system.
|
||||
//! 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()`] methods on `host`.
|
||||
//!
|
||||
//! Alternatively, you can enumerate all the available devices with the [`devices()`] method.
|
||||
//! 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
|
||||
//! # 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
|
||||
//! going to be. You can query all the supported configurations with the
|
||||
//! `supported_input_configs()` and `supported_output_configs()` methods. These produce a list of
|
||||
//! `SupportedStreamConfigRange` structs which can later be turned into actual
|
||||
//! `SupportedStreamConfig` structs. If you don't want to query the list of configs, 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.
|
||||
//! going to be.
|
||||
//! You can query all the supported configurations with the
|
||||
//! [`supported_input_configs()`] and [`supported_output_configs()`] methods.
|
||||
//! These produce a list of [`SupportedStreamConfigRange`] structs which can later be turned into
|
||||
//! actual [`SupportedStreamConfig`] structs.
|
||||
//!
|
||||
//! > **Note**: the `supported_input/output_configs()` methods could return an error for example if
|
||||
//! > the device has been disconnected.
|
||||
//! If you don't want to query the list of configs,
|
||||
//! 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
|
||||
//! use cpal::traits::{DeviceTrait, HostTrait};
|
||||
|
|
@ -74,8 +78,8 @@
|
|||
//! ```
|
||||
//!
|
||||
//! 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
|
||||
//! `&mut Data` depending on whether the stream is an input stream or output stream respectively.
|
||||
//! that was passed to the function. The callback is passed an instance of either [`&Data` or
|
||||
//! `&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
|
||||
//! > 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,
|
||||
//! we can use `Stream::play`.
|
||||
//! we can use [`Stream::play`](traits::StreamTrait::play).
|
||||
//!
|
||||
//! ```no_run
|
||||
//! # 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();
|
||||
//! 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"]
|
||||
|
||||
|
|
@ -212,11 +222,15 @@ pub type FrameCount = u32;
|
|||
|
||||
/// 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
|
||||
/// large, leading to latency issues. If low latency is desired, Fixed(BufferSize)
|
||||
/// should be used in accordance with the SupportedBufferSize range produced by
|
||||
/// the SupportedStreamConfig API.
|
||||
/// large, leading to latency issues. If low latency is desired, [`Fixed(FrameCount)`]
|
||||
/// should be used in accordance with the [`SupportedBufferSize`] range produced by
|
||||
/// the [`SupportedStreamConfig`] API.
|
||||
///
|
||||
/// [`Default`]: BufferSize::Default
|
||||
/// [`Fixed(FrameCount)`]: BufferSize::Fixed
|
||||
/// [`SupportedStreamConfig`]: SupportedStreamConfig::buffer_size
|
||||
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
|
||||
pub enum BufferSize {
|
||||
Default,
|
||||
|
|
@ -264,7 +278,7 @@ pub enum SupportedBufferSize {
|
|||
}
|
||||
|
||||
/// 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)]
|
||||
pub struct SupportedStreamConfigRange {
|
||||
pub(crate) channels: ChannelCount,
|
||||
|
|
@ -279,7 +293,8 @@ pub struct SupportedStreamConfigRange {
|
|||
}
|
||||
|
||||
/// 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)]
|
||||
pub struct SupportedStreamConfig {
|
||||
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
|
||||
/// 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.
|
||||
///
|
||||
/// ## Host `StreamInstant` Sources
|
||||
|
|
@ -427,7 +442,7 @@ impl StreamInstant {
|
|||
/// Returns the instant in time one `duration` ago.
|
||||
///
|
||||
/// 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.
|
||||
pub fn sub(&self, duration: Duration) -> Option<Self> {
|
||||
self.as_nanos()
|
||||
|
|
@ -515,24 +530,24 @@ impl Data {
|
|||
/// 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
|
||||
/// `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 {
|
||||
self.len
|
||||
}
|
||||
|
||||
/// 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] {
|
||||
let len = self.len * self.sample_format.sample_size();
|
||||
// The safety of this block relies on correct construction of the `Data` instance. See
|
||||
// the unsafe `from_parts` constructor for these requirements.
|
||||
// The safety of this block relies on correct construction of the `Data` instance.
|
||||
// See the unsafe `from_parts` constructor for these requirements.
|
||||
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.
|
||||
///
|
||||
/// 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] {
|
||||
let len = self.len * self.sample_format.sample_size();
|
||||
// The safety of this block relies on correct construction of the `Data` instance. See
|
||||
|
|
@ -615,10 +630,12 @@ impl SupportedStreamConfigRange {
|
|||
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
|
||||
/// `SupportedStreamConfigRange` instance.
|
||||
/// # Panics
|
||||
///
|
||||
/// 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 {
|
||||
assert!(self.min_sample_rate <= sample_rate && sample_rate <= self.max_sample_rate);
|
||||
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]
|
||||
pub fn with_max_sample_rate(self) -> 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.
|
||||
///
|
||||
/// Some backends do not provide a default stream format for their audio devices. In these
|
||||
|
|
|
|||
|
|
@ -1,35 +1,37 @@
|
|||
//! Platform-specific items.
|
||||
//!
|
||||
//! This module also contains the implementation of the platform's dynamically dispatched `Host`
|
||||
//! type and its associated `Device`, `StreamId` and other associated types. These
|
||||
//! This module also contains the implementation of the platform's dynamically dispatched [`Host`]
|
||||
//! 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.
|
||||
|
||||
#[doc(inline)]
|
||||
pub use self::platform_impl::*;
|
||||
|
||||
// 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
|
||||
// runtime.
|
||||
//
|
||||
// For example the invocation `impl_platform_host(Wasapi wasapi "WASAPI", Asio asio "ASIO")`,
|
||||
// this macro should expand to:
|
||||
//
|
||||
// ```
|
||||
// pub enum HostId {
|
||||
// Wasapi,
|
||||
// Asio,
|
||||
// }
|
||||
//
|
||||
// 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.
|
||||
// ```
|
||||
/// 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
|
||||
/// runtime.
|
||||
///
|
||||
/// For example the invocation `impl_platform_host(Wasapi wasapi "WASAPI", Asio asio "ASIO")`,
|
||||
/// this macro should expand to:
|
||||
///
|
||||
// This sample code block is marked as text because it's not a valid test,
|
||||
// it's just illustrative. (see rust issue #96573)
|
||||
/// ```text
|
||||
/// pub enum HostId {
|
||||
/// Wasapi,
|
||||
/// Asio,
|
||||
/// }
|
||||
///
|
||||
/// pub enum Host {
|
||||
/// Wasapi(crate::host::wasapi::Host),
|
||||
/// Asio(crate::host::asio::Host),
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// And so on for Device, Devices, Host, Stream, SupportedInputConfigs,
|
||||
/// SupportedOutputConfigs and all their necessary trait implementations.
|
||||
///
|
||||
macro_rules! impl_platform_host {
|
||||
($($(#[cfg($feat: meta)])? $HostVariant:ident $host_mod:ident $host_name:literal),*) => {
|
||||
/// 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.
|
||||
///
|
||||
/// 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
|
||||
/// be acquired via the **ALL_HOSTS** const, and the **available_hosts** function.
|
||||
/// 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.
|
||||
pub struct Host(HostInner);
|
||||
|
||||
/// The **Device** implementation associated with the platform's dynamically dispatched
|
||||
/// **Host** type.
|
||||
/// The `Device` implementation associated with the platform's dynamically dispatched
|
||||
/// [`Host`] type.
|
||||
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.
|
||||
pub struct Devices(DevicesInner);
|
||||
|
||||
/// The **Stream** implementation associated with the platform's dynamically dispatched
|
||||
/// **Host** type.
|
||||
/// The `Stream` implementation associated with the platform's dynamically dispatched
|
||||
/// [`Host`] type.
|
||||
// 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
|
||||
// functions within the callback.
|
||||
|
|
@ -68,12 +70,12 @@ macro_rules! impl_platform_host {
|
|||
// TODO: Confirm this and add more specific detail and references.
|
||||
pub struct Stream(StreamInner, crate::platform::NotSendSyncAcrossAllPlatforms);
|
||||
|
||||
/// The **SupportedInputConfigs** iterator associated with the platform's dynamically
|
||||
/// dispatched **Host** type.
|
||||
/// The `SupportedInputConfigs` iterator associated with the platform's dynamically
|
||||
/// dispatched [`Host`] type.
|
||||
pub struct SupportedInputConfigs(SupportedInputConfigsInner);
|
||||
|
||||
/// The **SupportedOutputConfigs** iterator associated with the platform's dynamically
|
||||
/// dispatched **Host** type.
|
||||
/// The `SupportedOutputConfigs` iterator associated with the platform's dynamically
|
||||
/// dispatched [`Host`] type.
|
||||
pub struct SupportedOutputConfigs(SupportedOutputConfigsInner);
|
||||
|
||||
/// 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 {
|
||||
$(
|
||||
$(#[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 {
|
||||
$(
|
||||
$(#[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 {
|
||||
$(
|
||||
$(#[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 {
|
||||
$(
|
||||
$(#[cfg($feat)])?
|
||||
|
|
@ -181,7 +183,7 @@ macro_rules! impl_platform_host {
|
|||
}
|
||||
|
||||
impl Host {
|
||||
/// The unique identifier associated with this host.
|
||||
/// The unique identifier associated with this `Host`.
|
||||
pub fn id(&self) -> HostId {
|
||||
match self.0 {
|
||||
$(
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ use crate::{
|
|||
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
|
||||
/// 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
|
||||
/// less readily available by default in many Linux distributions and is known to be tricky to
|
||||
/// set up.
|
||||
///
|
||||
/// [`Host`]: crate::Host
|
||||
pub trait HostTrait {
|
||||
/// The type used for enumerating available devices by the host.
|
||||
type Devices: Iterator<Item = Self::Device>;
|
||||
|
|
@ -37,7 +39,7 @@ pub trait HostTrait {
|
|||
/// Whether or not the host is available on the system.
|
||||
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.
|
||||
fn devices(&self) -> Result<Self::Devices, DevicesError>;
|
||||
|
|
@ -90,7 +92,10 @@ pub trait DeviceTrait {
|
|||
type SupportedInputConfigs: Iterator<Item = SupportedStreamConfigRange>;
|
||||
/// The iterator type yielding supported output stream formats.
|
||||
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;
|
||||
|
||||
/// The human-readable name of the device.
|
||||
|
|
@ -199,7 +204,7 @@ pub trait DeviceTrait {
|
|||
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 {
|
||||
/// Run the stream.
|
||||
///
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue