# Trait bevy::audio::CpalSample

```
pub trait CpalSample: Copy + Clone + PartialOrd + PartialEq {
type Signed: SignedSample + Duplex<Self>;
type Float: FloatSample + Duplex<Self>;
const EQUILIBRIUM: Self;
const IDENTITY: Self::Float = <Self::Float as FloatSample>::IDENTITY;
// Provided methods
fn to_sample<S>(self) -> S
where Self: ToSample<S> { ... }
fn from_sample<S>(s: S) -> Self
where Self: FromSample<S> { ... }
fn to_signed_sample(self) -> Self::Signed { ... }
fn to_float_sample(self) -> Self::Float { ... }
fn add_amp(self, amp: Self::Signed) -> Self { ... }
fn mul_amp(self, amp: Self::Float) -> Self { ... }
}
```

## Expand description

A trait for working generically across different **Sample** format types.

Provides methods for converting to and from any type that implements the
`FromSample`

trait and provides methods for performing signal
amplitude addition and multiplication.

## §Example

```
use dasp_sample::{I24, Sample};
fn main() {
assert_eq!((-1.0).to_sample::<u8>(), 0);
assert_eq!(0.0.to_sample::<u8>(), 128);
assert_eq!(0i32.to_sample::<u32>(), 2_147_483_648);
assert_eq!(I24::new(0).unwrap(), Sample::from_sample(0.0));
assert_eq!(0.0, Sample::EQUILIBRIUM);
}
```

## Required Associated Types§

#### type Signed: SignedSample + Duplex<Self>

#### type Signed: SignedSample + Duplex<Self>

When summing two samples of a signal together, it is necessary for both samples to be
represented in some signed format. This associated `Addition`

type represents the format to
which `Self`

should be converted for optimal `Addition`

performance.

For example, u32’s optimal `Addition`

type would be i32, u8’s would be i8, f32’s would be
f32, etc.

Specifying this as an associated type allows us to automatically determine the optimal,
lossless Addition format type for summing any two unique `Sample`

types together.

As a user of the `sample`

crate, you will never need to be concerned with this type unless
you are defining your own unique `Sample`

type(s).

#### type Float: FloatSample + Duplex<Self>

#### type Float: FloatSample + Duplex<Self>

When multiplying two samples of a signal together, it is necessary for both samples to be
represented in some signed, floating-point format. This associated `Multiplication`

type
represents the format to which `Self`

should be converted for optimal `Multiplication`

performance.

For example, u32’s optimal `Multiplication`

type would be f32, u64’s would be f64, i8’s
would be f32, etc.

Specifying this as an associated type allows us to automatically determine the optimal,
lossless Multiplication format type for multiplying any two unique `Sample`

types together.

As a user of the `sample`

crate, you will never need to be concerned with this type unless
you are defining your own unique `Sample`

type(s).

## Required Associated Constants§

#### const EQUILIBRIUM: Self

#### const EQUILIBRIUM: Self

The equilibrium value for the wave that this `Sample`

type represents. This is normally the
value that is equal distance from both the min and max ranges of the sample.

##### §Example

```
use dasp_sample::Sample;
fn main() {
assert_eq!(0.0, f32::EQUILIBRIUM);
assert_eq!(0, i32::EQUILIBRIUM);
assert_eq!(128, u8::EQUILIBRIUM);
assert_eq!(32_768_u16, Sample::EQUILIBRIUM);
}
```

**Note:** This will likely be changed to an “associated const” if the feature lands.

## Provided Associated Constants§

#### const IDENTITY: Self::Float = <Self::Float as FloatSample>::IDENTITY

#### const IDENTITY: Self::Float = <Self::Float as FloatSample>::IDENTITY

The multiplicative identity of the signal.

In other words: A value which when used to scale/multiply the amplitude or frequency of a signal, returns the same signal.

This is useful as a default, non-affecting amplitude or frequency multiplier.

##### §Example

```
use dasp_sample::{Sample, U48};
fn main() {
assert_eq!(1.0, f32::IDENTITY);
assert_eq!(1.0, i8::IDENTITY);
assert_eq!(1.0, u8::IDENTITY);
assert_eq!(1.0, U48::IDENTITY);
}
```

## Provided Methods§

#### fn to_sample<S>(self) -> Swhere
Self: ToSample<S>,

#### fn to_sample<S>(self) -> Swhere
Self: ToSample<S>,

Convert `self`

to any type that implements `FromSample<Self>`

.

Find more details on type-specific conversion ranges and caveats in the `conv`

module.

##### §Example

```
use dasp_sample::Sample;
fn main() {
assert_eq!(0.0.to_sample::<i32>(), 0);
assert_eq!(0.0.to_sample::<u8>(), 128);
assert_eq!((-1.0).to_sample::<u8>(), 0);
}
```

#### fn from_sample<S>(s: S) -> Selfwhere
Self: FromSample<S>,

#### fn from_sample<S>(s: S) -> Selfwhere
Self: FromSample<S>,

Create a `Self`

from any type that implements `ToSample<Self>`

.

Find more details on type-specific conversion ranges and caveats in the `conv`

module.

##### §Example

```
use dasp_sample::{Sample, I24};
fn main() {
assert_eq!(f32::from_sample(128_u8), 0.0);
assert_eq!(i8::from_sample(-1.0), -128);
assert_eq!(I24::from_sample(0.0), I24::new(0).unwrap());
}
```

#### fn to_signed_sample(self) -> Self::Signed

#### fn to_signed_sample(self) -> Self::Signed

Converts `self`

to the equivalent `Sample`

in the associated `Signed`

format.

This is a simple wrapper around `Sample::to_sample`

which may provide extra convenience in
some cases, particularly for assisting type inference.

##### §Example

```
use dasp_sample::Sample;
fn main() {
assert_eq!(128_u8.to_signed_sample(), 0i8);
}
```

#### fn to_float_sample(self) -> Self::Float

#### fn to_float_sample(self) -> Self::Float

Converts `self`

to the equivalent `Sample`

in the associated `Float`

format.

This is a simple wrapper around `Sample::to_sample`

which may provide extra convenience in
some cases, particularly for assisting type inference.

##### §Example

```
use dasp_sample::Sample;
fn main() {
assert_eq!(128_u8.to_float_sample(), 0.0);
}
```

#### fn add_amp(self, amp: Self::Signed) -> Self

#### fn add_amp(self, amp: Self::Signed) -> Self

Adds (or “offsets”) the amplitude of the `Sample`

by the given signed amplitude.

`Self`

will be converted to `Self::Signed`

, the addition will occur and then the result
will be converted back to `Self`

. These conversions allow us to correctly handle the
addition of unsigned signal formats.

##### §Example

```
use dasp_sample::Sample;
fn main() {
assert_eq!(0.25.add_amp(0.5), 0.75);
assert_eq!(192u8.add_amp(-128), 64);
}
```

#### fn mul_amp(self, amp: Self::Float) -> Self

#### fn mul_amp(self, amp: Self::Float) -> Self

Multiplies (or “scales”) the amplitude of the `Sample`

by the given float amplitude.

`amp`

> 1.0 amplifies the sample.`amp`

< 1.0 attenuates the sample.`amp`

== 1.0 yields the same sample.`amp`

== 0.0 yields the`Sample::EQUILIBRIUM`

.

`Self`

will be converted to `Self::Float`

, the multiplication will occur and then the
result will be converted back to `Self`

. These conversions allow us to correctly handle the
multiplication of integral signal formats.

##### §Example

```
use dasp_sample::Sample;
fn main() {
assert_eq!(64_i8.mul_amp(0.5), 32);
assert_eq!(0.5.mul_amp(-2.0), -1.0);
assert_eq!(64_u8.mul_amp(0.0), 128);
}
```

## Object Safety§

**not**object safe.