audio_core/channel.rs
1//! A channel buffer as created through [Buf::get_channel][crate::Buf::get_channel] or
2//! [BufMut::get_channel_mut][crate::BufMut::get_channel_mut].
3
4/// One channel of audio samples, usually one of several channels in a
5/// multichannel buffer
6///
7/// This trait provides read-only access.
8///
9/// See [Buf::get_channel][crate::Buf::get_channel].
10pub trait Channel {
11 /// The sample of a channel.
12 type Sample: Copy;
13
14 /// The type the channel assumes when coerced into a reference.
15 type Channel<'this>: Channel<Sample = Self::Sample>
16 where
17 Self: 'this;
18
19 /// A borrowing iterator over the channel.
20 type Iter<'this>: Iterator<Item = Self::Sample>
21 where
22 Self: 'this;
23
24 /// Reborrow the current channel as a reference.
25 fn as_channel(&self) -> Self::Channel<'_>;
26
27 /// Get the length which indicates number of frames in the current channel.
28 ///
29 /// # Examples
30 ///
31 /// ```
32 /// use audio::{Buf, Channel};
33 ///
34 /// fn test(buf: impl Buf<Sample = f32>) {
35 /// for chan in buf.iter_channels() {
36 /// assert_eq!(chan.len(), 16);
37 /// }
38 /// }
39 ///
40 /// test(&audio::dynamic![[0.0; 16]; 2]);
41 /// test(&audio::sequential![[0.0; 16]; 2]);
42 /// test(&audio::interleaved![[0.0; 16]; 2]);
43 /// ```
44 fn len(&self) -> usize;
45
46 /// Test if the current channel is empty.
47 ///
48 /// # Examples
49 ///
50 /// ```
51 /// use audio::{Buf, Channel};
52 ///
53 /// fn test(buf: impl Buf<Sample = f32>) {
54 /// for chan in buf.iter_channels() {
55 /// assert!(!chan.is_empty());
56 /// }
57 /// }
58 ///
59 /// test(&audio::dynamic![[0.0; 16]; 2]);
60 /// test(&audio::sequential![[0.0; 16]; 2]);
61 /// test(&audio::interleaved![[0.0; 16]; 2]);
62 /// ```
63 fn is_empty(&self) -> bool {
64 self.len() == 0
65 }
66
67 /// Get the frame at the given offset in the channel.
68 ///
69 /// # Examples
70 ///
71 /// ```
72 /// use audio::{Buf, Channel};
73 ///
74 /// fn test(buf: impl Buf<Sample = f32>) {
75 /// for chan in buf.iter_channels() {
76 /// assert_eq!(chan.get(15), Some(0.0));
77 /// assert_eq!(chan.get(16), None);
78 /// }
79 /// }
80 ///
81 /// test(&audio::dynamic![[0.0; 16]; 2]);
82 /// test(&audio::sequential![[0.0; 16]; 2]);
83 /// test(&audio::interleaved![[0.0; 16]; 2]);
84 /// ```
85 fn get(&self, n: usize) -> Option<Self::Sample>;
86
87 /// Construct an iterator over the channel.
88 ///
89 /// # Examples
90 ///
91 /// ```
92 /// use audio::{Buf, BufMut, Channel, ChannelMut};
93 ///
94 /// let mut left = audio::interleaved![[0.0f32; 4]; 2];
95 /// let mut right = audio::dynamic![[0.0f32; 4]; 2];
96 ///
97 /// if let (Some(mut left), Some(mut right)) = (left.get_mut(0), right.get_mut(0)) {
98 /// for (l, r) in left.iter_mut().zip(right.iter_mut()) {
99 /// *l = 1.0;
100 /// *r = 1.0;
101 /// }
102 /// }
103 ///
104 /// assert!(left.get_channel(0).unwrap().iter().eq(right.get_channel(0).unwrap().iter()));
105 ///
106 /// assert_eq!(left.as_slice(), &[1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0]);
107 /// assert_eq!(&right[0], &[1.0, 1.0, 1.0, 1.0]);
108 /// assert_eq!(&right[1], &[0.0, 0.0, 0.0, 0.0]);
109 /// ```
110 fn iter(&self) -> Self::Iter<'_>;
111
112 /// Try to access the current channel as a linear buffer.
113 ///
114 /// This is available because it could permit for some optimizations.
115 ///
116 /// # Examples
117 ///
118 /// ```
119 /// use audio::{Buf, Channel};
120 ///
121 /// fn test(buf: &impl Buf<Sample = f32>, expected: Option<&[f32]>) {
122 /// assert_eq!(buf.get_channel(0).unwrap().try_as_linear(), expected);
123 /// }
124 ///
125 /// test(&audio::dynamic![[1.0; 16]; 2], Some(&[1.0; 16]));
126 /// test(&audio::sequential![[1.0; 16]; 2], Some(&[1.0; 16]));
127 /// test(&audio::interleaved![[1.0; 16]; 2], None);
128 /// ```
129 fn try_as_linear(&self) -> Option<&[Self::Sample]>;
130
131 /// Construct a channel buffer where the first `n` frames are skipped.
132 ///
133 /// Skipping to the end of the buffer will result in an empty buffer.
134 ///
135 /// ```
136 /// use audio::{Buf, Channel};
137 ///
138 /// let buf = audio::interleaved![[0; 4]; 2];
139 ///
140 /// for chan in buf.iter_channels() {
141 /// assert_eq!(chan.skip(1).len(), 3);
142 /// assert_eq!(chan.skip(4).len(), 0);
143 /// }
144 /// ```
145 ///
146 /// # Examples
147 ///
148 /// ```
149 /// use audio::{Buf, BufMut, Channel, ChannelMut};
150 ///
151 /// let mut from = audio::interleaved![[0.0f32; 4]; 2];
152 /// *from.sample_mut(0, 2).unwrap() = 1.0;
153 /// *from.sample_mut(0, 3).unwrap() = 1.0;
154 ///
155 /// let mut to = audio::interleaved![[0.0f32; 4]; 2];
156 ///
157 /// if let (Some(from), Some(to)) = (from.get_channel(0), to.get_channel_mut(0)) {
158 /// audio::channel::copy(from.skip(2), to);
159 /// }
160 ///
161 /// assert_eq!(to.as_slice(), &[1.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0]);
162 /// ```
163 fn skip(self, n: usize) -> Self;
164
165 /// Construct a channel buffer where the last `n` frames are included.
166 ///
167 /// # Examples
168 ///
169 /// ```
170 /// use audio::{Buf, BufMut, Channel, ChannelMut};
171 ///
172 /// let from = audio::interleaved![[1.0f32; 4]; 2];
173 /// let mut to = audio::interleaved![[0.0f32; 4]; 2];
174 ///
175 /// if let (Some(from), Some(to)) = (from.get_channel(0), to.get_channel_mut(0)) {
176 /// audio::channel::copy(from, to.tail(2));
177 /// }
178 ///
179 /// assert_eq!(to.as_slice(), &[0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0, 0.0]);
180 /// ```
181 fn tail(self, n: usize) -> Self;
182
183 /// Limit the channel bufferto `limit` number of frames.
184 ///
185 /// # Examples
186 ///
187 /// ```
188 /// use audio::{Buf, BufMut, Channel, ChannelMut};
189 ///
190 /// let from = audio::interleaved![[1.0f32; 4]; 2];
191 /// let mut to = audio::interleaved![[0.0f32; 4]; 2];
192 ///
193 /// if let (Some(from), Some(to)) = (from.get_channel(0), to.get_channel_mut(0)) {
194 /// audio::channel::copy(from.limit(2), to);
195 /// }
196 ///
197 /// assert_eq!(to.as_slice(), &[1.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0]);
198 /// ```
199 fn limit(self, limit: usize) -> Self;
200}