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::DynBlock<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
48extern_conformance!(
49 unsafe impl NSObjectProtocol for AVAudioNode {}
50);
51
52impl AVAudioNode {
53 extern_methods!(
54 /// Clear a unit's previous processing state.
55 #[unsafe(method(reset))]
56 #[unsafe(method_family = none)]
57 pub unsafe fn reset(&self);
58
59 #[cfg(all(feature = "AVAudioFormat", feature = "AVAudioTypes"))]
60 /// Obtain an input bus's format.
61 #[unsafe(method(inputFormatForBus:))]
62 #[unsafe(method_family = none)]
63 pub unsafe fn inputFormatForBus(&self, bus: AVAudioNodeBus) -> Retained<AVAudioFormat>;
64
65 #[cfg(all(feature = "AVAudioFormat", feature = "AVAudioTypes"))]
66 /// Obtain an output bus's format.
67 #[unsafe(method(outputFormatForBus:))]
68 #[unsafe(method_family = none)]
69 pub unsafe fn outputFormatForBus(&self, bus: AVAudioNodeBus) -> Retained<AVAudioFormat>;
70
71 #[cfg(feature = "AVAudioTypes")]
72 /// Return the name of an input bus.
73 #[unsafe(method(nameForInputBus:))]
74 #[unsafe(method_family = none)]
75 pub unsafe fn nameForInputBus(&self, bus: AVAudioNodeBus) -> Option<Retained<NSString>>;
76
77 #[cfg(feature = "AVAudioTypes")]
78 /// Return the name of an output bus.
79 #[unsafe(method(nameForOutputBus:))]
80 #[unsafe(method_family = none)]
81 pub unsafe fn nameForOutputBus(&self, bus: AVAudioNodeBus) -> Option<Retained<NSString>>;
82
83 #[cfg(all(
84 feature = "AVAudioBuffer",
85 feature = "AVAudioFormat",
86 feature = "AVAudioTime",
87 feature = "AVAudioTypes",
88 feature = "block2"
89 ))]
90 /// Create a "tap" to record/monitor/observe the output of the node.
91 ///
92 /// Parameter `bus`: the node output bus to which to attach the tap
93 ///
94 /// Parameter `bufferSize`: the requested size of the incoming buffers in sample frames. Supported range is [100, 400] ms.
95 ///
96 /// Parameter `format`: If non-nil, attempts to apply this as the format of the specified output bus. This should
97 /// only be done when attaching to an output bus which is not connected to another node; an
98 /// error will result otherwise.
99 /// The tap and connection formats (if non-nil) on the specified bus should be identical.
100 /// Otherwise, the latter operation will override any previously set format.
101 ///
102 /// Parameter `tapBlock`: a block to be called with audio buffers
103 ///
104 ///
105 /// Only one tap may be installed on any bus. Taps may be safely installed and removed while
106 /// the engine is running.
107 ///
108 /// Note that if you have a tap installed on AVAudioOutputNode, there could be a mismatch
109 /// between the tap buffer format and AVAudioOutputNode's output format, depending on the
110 /// underlying physical device. Hence, instead of tapping the AVAudioOutputNode, it is
111 /// advised to tap the node connected to it.
112 ///
113 /// E.g. to capture audio from input node:
114 /// <pre>
115 /// AVAudioEngine *engine = [[AVAudioEngine alloc] init];
116 /// AVAudioInputNode *input = [engine inputNode];
117 /// AVAudioFormat *format = [input outputFormatForBus: 0];
118 /// [input installTapOnBus: 0 bufferSize: 8192 format: format block: ^(AVAudioPCMBuffer *buf, AVAudioTime *when) {
119 /// // ‘buf' contains audio captured from input node at time 'when'
120 /// }];
121 /// ....
122 /// // start engine
123 /// </pre>
124 #[unsafe(method(installTapOnBus:bufferSize:format:block:))]
125 #[unsafe(method_family = none)]
126 pub unsafe fn installTapOnBus_bufferSize_format_block(
127 &self,
128 bus: AVAudioNodeBus,
129 buffer_size: AVAudioFrameCount,
130 format: Option<&AVAudioFormat>,
131 tap_block: AVAudioNodeTapBlock,
132 );
133
134 #[cfg(feature = "AVAudioTypes")]
135 /// Destroy a tap.
136 ///
137 /// Parameter `bus`: the node output bus whose tap is to be destroyed
138 #[unsafe(method(removeTapOnBus:))]
139 #[unsafe(method_family = none)]
140 pub unsafe fn removeTapOnBus(&self, bus: AVAudioNodeBus);
141
142 #[cfg(feature = "AVAudioEngine")]
143 /// The engine to which the node is attached (or nil).
144 #[unsafe(method(engine))]
145 #[unsafe(method_family = none)]
146 pub unsafe fn engine(&self) -> Option<Retained<AVAudioEngine>>;
147
148 /// The node's number of input busses.
149 #[unsafe(method(numberOfInputs))]
150 #[unsafe(method_family = none)]
151 pub unsafe fn numberOfInputs(&self) -> NSUInteger;
152
153 /// The node's number of output busses.
154 #[unsafe(method(numberOfOutputs))]
155 #[unsafe(method_family = none)]
156 pub unsafe fn numberOfOutputs(&self) -> NSUInteger;
157
158 #[cfg(feature = "AVAudioTime")]
159 /// Obtain the time for which the node most recently rendered.
160 ///
161 /// Will return nil if the engine is not running or if the node is not connected to an input or
162 /// output node.
163 #[unsafe(method(lastRenderTime))]
164 #[unsafe(method_family = none)]
165 pub unsafe fn lastRenderTime(&self) -> Option<Retained<AVAudioTime>>;
166
167 #[cfg(feature = "objc2-audio-toolbox")]
168 #[cfg(not(target_os = "watchos"))]
169 /// An AUAudioUnit wrapping or underlying the implementation's AudioUnit.
170 ///
171 /// This provides an AUAudioUnit which either wraps or underlies the implementation's
172 /// AudioUnit, depending on how that audio unit is packaged. Applications can interact with this
173 /// AUAudioUnit to control custom properties, select presets, change parameters, etc.
174 ///
175 /// No operations that may conflict with state maintained by the engine should be performed
176 /// directly on the audio unit. These include changing initialization state, stream formats,
177 /// channel layouts or connections to other audio units.
178 #[unsafe(method(AUAudioUnit))]
179 #[unsafe(method_family = none)]
180 pub unsafe fn AUAudioUnit(&self) -> Retained<AUAudioUnit>;
181
182 /// The processing latency of the node, in seconds.
183 ///
184 /// This property reflects the delay between when an impulse in the audio stream arrives at the
185 /// input vs. output of the node. This should reflect the delay due to signal processing
186 /// (e.g. filters, FFT's, etc.), not delay or reverberation which is being applied as an effect.
187 /// A value of zero indicates either no latency or an unknown latency.
188 #[unsafe(method(latency))]
189 #[unsafe(method_family = none)]
190 pub unsafe fn latency(&self) -> NSTimeInterval;
191
192 /// The maximum render pipeline latency downstream of the node, in seconds.
193 ///
194 /// This describes the maximum time it will take for the audio at the output of a node to be
195 /// presented.
196 /// For instance, the output presentation latency of the output node in the engine is:
197 /// - zero in manual rendering mode
198 /// - the presentation latency of the device itself when rendering to an audio device
199 /// (see `AVAudioIONode(presentationLatency)`)
200 /// The output presentation latency of a node connected directly to the output node is the
201 /// output node's presentation latency plus the output node's processing latency (see `latency`).
202 ///
203 /// For a node which is exclusively in the input node chain (i.e. not connected to engine's
204 /// output node), this property reflects the latency for the output of this node to be
205 /// presented at the output of the terminating node in the input chain.
206 ///
207 /// A value of zero indicates either an unknown or no latency.
208 ///
209 /// Note that this latency value can change as the engine is reconfigured (started/stopped,
210 /// connections made/altered downstream of this node etc.). So it is recommended not to cache
211 /// this value and fetch it whenever it's needed.
212 #[unsafe(method(outputPresentationLatency))]
213 #[unsafe(method_family = none)]
214 pub unsafe fn outputPresentationLatency(&self) -> NSTimeInterval;
215 );
216}
217
218/// Methods declared on superclass `NSObject`.
219impl AVAudioNode {
220 extern_methods!(
221 #[unsafe(method(init))]
222 #[unsafe(method_family = init)]
223 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
224
225 #[unsafe(method(new))]
226 #[unsafe(method_family = new)]
227 pub unsafe fn new() -> Retained<Self>;
228 );
229}