objc2_avf_audio/generated/AVAudioNode.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5use objc2::__framework_prelude::*;
6#[cfg(feature = "objc2-audio-toolbox")]
7#[cfg(not(target_os = "watchos"))]
8use objc2_audio_toolbox::*;
9use objc2_foundation::*;
10
11use crate::*;
12
13/// A block that receives copies of the output of an AVAudioNode.
14///
15/// Parameter `buffer`: a buffer of audio captured from the output of an AVAudioNode
16///
17/// Parameter `when`: the time at which the buffer was captured
18///
19/// CAUTION: This callback may be invoked on a thread other than the main thread.
20///
21/// See also [Apple's documentation](https://developer.apple.com/documentation/avfaudio/avaudionodetapblock?language=objc)
22#[cfg(all(feature = "AVAudioBuffer", feature = "AVAudioTime", feature = "block2"))]
23pub type AVAudioNodeTapBlock =
24 *mut block2::Block<dyn Fn(NonNull<AVAudioPCMBuffer>, NonNull<AVAudioTime>)>;
25
26extern_class!(
27 /// Base class for an audio generation, processing, or I/O block.
28 ///
29 /// `AVAudioEngine` objects contain instances of various AVAudioNode subclasses. This
30 /// base class provides certain common functionality.
31 ///
32 /// Nodes have input and output busses, which can be thought of as connection points.
33 /// For example, an effect typically has one input bus and one output bus. A mixer
34 /// typically has multiple input busses and one output bus.
35 ///
36 /// Busses have formats, expressed in terms of sample rate and channel count. When making
37 /// connections between nodes, often the format must match exactly. There are exceptions
38 /// (e.g. `AVAudioMixerNode` and `AVAudioOutputNode`).
39 ///
40 /// Nodes do not currently provide useful functionality until attached to an engine.
41 ///
42 /// See also [Apple's documentation](https://developer.apple.com/documentation/avfaudio/avaudionode?language=objc)
43 #[unsafe(super(NSObject))]
44 #[derive(Debug, PartialEq, Eq, Hash)]
45 pub struct AVAudioNode;
46);
47
48unsafe impl NSObjectProtocol for AVAudioNode {}
49
50impl AVAudioNode {
51 extern_methods!(
52 /// Clear a unit's previous processing state.
53 #[unsafe(method(reset))]
54 #[unsafe(method_family = none)]
55 pub unsafe fn reset(&self);
56
57 #[cfg(all(feature = "AVAudioFormat", feature = "AVAudioTypes"))]
58 /// Obtain an input bus's format.
59 #[unsafe(method(inputFormatForBus:))]
60 #[unsafe(method_family = none)]
61 pub unsafe fn inputFormatForBus(&self, bus: AVAudioNodeBus) -> Retained<AVAudioFormat>;
62
63 #[cfg(all(feature = "AVAudioFormat", feature = "AVAudioTypes"))]
64 /// Obtain an output bus's format.
65 #[unsafe(method(outputFormatForBus:))]
66 #[unsafe(method_family = none)]
67 pub unsafe fn outputFormatForBus(&self, bus: AVAudioNodeBus) -> Retained<AVAudioFormat>;
68
69 #[cfg(feature = "AVAudioTypes")]
70 /// Return the name of an input bus.
71 #[unsafe(method(nameForInputBus:))]
72 #[unsafe(method_family = none)]
73 pub unsafe fn nameForInputBus(&self, bus: AVAudioNodeBus) -> Option<Retained<NSString>>;
74
75 #[cfg(feature = "AVAudioTypes")]
76 /// Return the name of an output bus.
77 #[unsafe(method(nameForOutputBus:))]
78 #[unsafe(method_family = none)]
79 pub unsafe fn nameForOutputBus(&self, bus: AVAudioNodeBus) -> Option<Retained<NSString>>;
80
81 #[cfg(all(
82 feature = "AVAudioBuffer",
83 feature = "AVAudioFormat",
84 feature = "AVAudioTime",
85 feature = "AVAudioTypes",
86 feature = "block2"
87 ))]
88 /// Create a "tap" to record/monitor/observe the output of the node.
89 ///
90 /// Parameter `bus`: the node output bus to which to attach the tap
91 ///
92 /// Parameter `bufferSize`: the requested size of the incoming buffers in sample frames. Supported range is [100, 400] ms.
93 ///
94 /// Parameter `format`: If non-nil, attempts to apply this as the format of the specified output bus. This should
95 /// only be done when attaching to an output bus which is not connected to another node; an
96 /// error will result otherwise.
97 /// The tap and connection formats (if non-nil) on the specified bus should be identical.
98 /// Otherwise, the latter operation will override any previously set format.
99 ///
100 /// Parameter `tapBlock`: a block to be called with audio buffers
101 ///
102 ///
103 /// Only one tap may be installed on any bus. Taps may be safely installed and removed while
104 /// the engine is running.
105 ///
106 /// Note that if you have a tap installed on AVAudioOutputNode, there could be a mismatch
107 /// between the tap buffer format and AVAudioOutputNode's output format, depending on the
108 /// underlying physical device. Hence, instead of tapping the AVAudioOutputNode, it is
109 /// advised to tap the node connected to it.
110 ///
111 /// E.g. to capture audio from input node:
112 /// <pre>
113 /// AVAudioEngine *engine = [[AVAudioEngine alloc] init];
114 /// AVAudioInputNode *input = [engine inputNode];
115 /// AVAudioFormat *format = [input outputFormatForBus: 0];
116 /// [input installTapOnBus: 0 bufferSize: 8192 format: format block: ^(AVAudioPCMBuffer *buf, AVAudioTime *when) {
117 /// // ‘buf' contains audio captured from input node at time 'when'
118 /// }];
119 /// ....
120 /// // start engine
121 /// </pre>
122 #[unsafe(method(installTapOnBus:bufferSize:format:block:))]
123 #[unsafe(method_family = none)]
124 pub unsafe fn installTapOnBus_bufferSize_format_block(
125 &self,
126 bus: AVAudioNodeBus,
127 buffer_size: AVAudioFrameCount,
128 format: Option<&AVAudioFormat>,
129 tap_block: AVAudioNodeTapBlock,
130 );
131
132 #[cfg(feature = "AVAudioTypes")]
133 /// Destroy a tap.
134 ///
135 /// Parameter `bus`: the node output bus whose tap is to be destroyed
136 #[unsafe(method(removeTapOnBus:))]
137 #[unsafe(method_family = none)]
138 pub unsafe fn removeTapOnBus(&self, bus: AVAudioNodeBus);
139
140 #[cfg(feature = "AVAudioEngine")]
141 /// The engine to which the node is attached (or nil).
142 #[unsafe(method(engine))]
143 #[unsafe(method_family = none)]
144 pub unsafe fn engine(&self) -> Option<Retained<AVAudioEngine>>;
145
146 /// The node's number of input busses.
147 #[unsafe(method(numberOfInputs))]
148 #[unsafe(method_family = none)]
149 pub unsafe fn numberOfInputs(&self) -> NSUInteger;
150
151 /// The node's number of output busses.
152 #[unsafe(method(numberOfOutputs))]
153 #[unsafe(method_family = none)]
154 pub unsafe fn numberOfOutputs(&self) -> NSUInteger;
155
156 #[cfg(feature = "AVAudioTime")]
157 /// Obtain the time for which the node most recently rendered.
158 ///
159 /// Will return nil if the engine is not running or if the node is not connected to an input or
160 /// output node.
161 #[unsafe(method(lastRenderTime))]
162 #[unsafe(method_family = none)]
163 pub unsafe fn lastRenderTime(&self) -> Option<Retained<AVAudioTime>>;
164
165 #[cfg(feature = "objc2-audio-toolbox")]
166 #[cfg(not(target_os = "watchos"))]
167 /// An AUAudioUnit wrapping or underlying the implementation's AudioUnit.
168 ///
169 /// This provides an AUAudioUnit which either wraps or underlies the implementation's
170 /// AudioUnit, depending on how that audio unit is packaged. Applications can interact with this
171 /// AUAudioUnit to control custom properties, select presets, change parameters, etc.
172 ///
173 /// No operations that may conflict with state maintained by the engine should be performed
174 /// directly on the audio unit. These include changing initialization state, stream formats,
175 /// channel layouts or connections to other audio units.
176 #[unsafe(method(AUAudioUnit))]
177 #[unsafe(method_family = none)]
178 pub unsafe fn AUAudioUnit(&self) -> Retained<AUAudioUnit>;
179
180 /// The processing latency of the node, in seconds.
181 ///
182 /// This property reflects the delay between when an impulse in the audio stream arrives at the
183 /// input vs. output of the node. This should reflect the delay due to signal processing
184 /// (e.g. filters, FFT's, etc.), not delay or reverberation which is being applied as an effect.
185 /// A value of zero indicates either no latency or an unknown latency.
186 #[unsafe(method(latency))]
187 #[unsafe(method_family = none)]
188 pub unsafe fn latency(&self) -> NSTimeInterval;
189
190 /// The maximum render pipeline latency downstream of the node, in seconds.
191 ///
192 /// This describes the maximum time it will take for the audio at the output of a node to be
193 /// presented.
194 /// For instance, the output presentation latency of the output node in the engine is:
195 /// - zero in manual rendering mode
196 /// - the presentation latency of the device itself when rendering to an audio device
197 /// (see `AVAudioIONode(presentationLatency)`)
198 /// The output presentation latency of a node connected directly to the output node is the
199 /// output node's presentation latency plus the output node's processing latency (see `latency`).
200 ///
201 /// For a node which is exclusively in the input node chain (i.e. not connected to engine's
202 /// output node), this property reflects the latency for the output of this node to be
203 /// presented at the output of the terminating node in the input chain.
204 ///
205 /// A value of zero indicates either an unknown or no latency.
206 ///
207 /// Note that this latency value can change as the engine is reconfigured (started/stopped,
208 /// connections made/altered downstream of this node etc.). So it is recommended not to cache
209 /// this value and fetch it whenever it's needed.
210 #[unsafe(method(outputPresentationLatency))]
211 #[unsafe(method_family = none)]
212 pub unsafe fn outputPresentationLatency(&self) -> NSTimeInterval;
213 );
214}
215
216/// Methods declared on superclass `NSObject`.
217impl AVAudioNode {
218 extern_methods!(
219 #[unsafe(method(init))]
220 #[unsafe(method_family = init)]
221 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
222
223 #[unsafe(method(new))]
224 #[unsafe(method_family = new)]
225 pub unsafe fn new() -> Retained<Self>;
226 );
227}