1
2/*
3Copyright 2018 Google Inc. All Rights Reserved.
4
5Licensed under the Apache License, Version 2.0 (the "License");
6you may not use this file except in compliance with the License.
7You may obtain a copy of the License at
8
9 http://www.apache.org/licenses/LICENSE-2.0
10
11Unless required by applicable law or agreed to in writing, software
12distributed under the License is distributed on an "AS-IS" BASIS,
13WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14See the License for the specific language governing permissions and
15limitations under the License.
16*/
17
18#ifndef RESONANCE_AUDIO_API_RESONANCE_AUDIO_API_H_
19#define RESONANCE_AUDIO_API_RESONANCE_AUDIO_API_H_
20
21// EXPORT_API can be used to define the dllimport storage-class attribute.
22#if !defined(EXPORT_API)
23#define EXPORT_API
24#endif
25
26#include <cstddef> // size_t declaration.
27#include <cstdint> // int16_t declaration.
28
29
30typedef int16_t int16;
31
32namespace vraudio {
33
34// Rendering modes define CPU load / rendering quality balances.
35// Note that this struct is C-compatible by design to be used across external
36// C/C++ and C# implementations.
37enum RenderingMode {
38 // Stereo panning, i.e., this disables HRTF-based rendering.
39 kStereoPanning = 0,
40 // HRTF-based rendering using First Order Ambisonics, over a virtual array of
41 // 8 loudspeakers arranged in a cube configuration around the listener's head.
42 kBinauralLowQuality,
43 // HRTF-based rendering using Second Order Ambisonics, over a virtual array of
44 // 12 loudspeakers arranged in a dodecahedral configuration (using faces of
45 // the dodecahedron).
46 kBinauralMediumQuality,
47 // HRTF-based rendering using Third Order Ambisonics, over a virtual array of
48 // 26 loudspeakers arranged in a Lebedev grid: https://goo.gl/DX1wh3.
49 kBinauralHighQuality,
50 // Room effects only rendering. This disables HRTF-based rendering and direct
51 // (dry) output of a sound object. Note that this rendering mode should *not*
52 // be used for general-purpose sound object spatialization, as it will only
53 // render the corresponding room effects of given sound objects without the
54 // direct spatialization.
55 kRoomEffectsOnly,
56};
57
58// Distance rolloff models used for distance attenuation.
59// Note that this enum is C-compatible by design to be used across external
60// C/C++ and C# implementations.
61enum DistanceRolloffModel {
62 // Logarithmic distance rolloff model.
63 kLogarithmic = 0,
64 // Linear distance rolloff model.
65 kLinear,
66 // Distance attenuation value will be explicitly set by the user.
67 kNone,
68};
69
70// Early reflection properties of an acoustic environment.
71// Note that this struct is C-compatible by design to be used across external
72// C/C++ and C# implementations.
73struct ReflectionProperties {
74 // Default constructor initializing all data members to 0.
75 ReflectionProperties()
76 : room_position{0.0f, 0.0f, 0.0f},
77 room_rotation{0.0f, 0.0f, 0.0f, 1.0f},
78 room_dimensions{0.0f, 0.0f, 0.0f},
79 cutoff_frequency(0.0f),
80 coefficients{0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f},
81 gain(0.0f) {}
82
83 // Center position of the shoebox room in world space.
84 float room_position[3];
85
86 // Rotation (quaternion) of the shoebox room in world space.
87 float room_rotation[4];
88
89 // Size of the shoebox shoebox room in world space.
90 float room_dimensions[3];
91
92 // Frequency threshold for low pass filtering (-3dB cuttoff).
93 float cutoff_frequency;
94
95 // Reflection coefficients that are stored in world space as follows:
96 // [0] (-)ive x-axis wall (left)
97 // [1] (+)ive x-axis wall (right)
98 // [2] (-)ive y-axis wall (bottom)
99 // [3] (+)ive y-axis wall (top)
100 // [4] (-)ive z-axis wall (front)
101 // [5] (+)ive z-axis wall (back)
102 float coefficients[6];
103
104 // Uniform reflections gain which is applied to all reflections.
105 float gain;
106};
107
108// Late reverberation properties of an acoustic environment.
109// Note that this struct is C-compatible by design to be used across external
110// C/C++ and C# implementations.
111struct ReverbProperties {
112 // Default constructor initializing all data members to 0.
113 ReverbProperties()
114 : rt60_values{0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f},
115 gain(0.0f) {}
116
117 // RT60's of the reverberation tail at different octave band centre
118 // frequencies in seconds.
119 float rt60_values[9];
120
121 // Reverb gain.
122 float gain;
123};
124
125class ResonanceAudioApi;
126
127// Factory method to create a |ResonanceAudioApi| instance. Caller must
128// take ownership of returned instance and destroy it via operator delete.
129//
130// @param num_channels Number of channels of audio output.
131// @param frames_per_buffer Number of frames per buffer.
132// @param sample_rate_hz System sample rate.
133extern "C" EXPORT_API ResonanceAudioApi* CreateResonanceAudioApi(
134 size_t num_channels, size_t frames_per_buffer, int sample_rate_hz);
135
136// The ResonanceAudioApi library renders high-quality spatial audio. It provides
137// methods to binaurally render virtual sound sources with simulated room
138// acoustics. In addition, it supports decoding and binaural rendering of
139// ambisonic soundfields. Its implementation is single-threaded, thread-safe
140// and non-blocking to be able to process raw PCM audio buffers directly on the
141// audio thread while receiving parameter updates from the main/render thread.
142class ResonanceAudioApi {
143 public:
144 // Sound object / ambisonic source identifier.
145 typedef int SourceId;
146
147 // Invalid source id that can be used to initialize handler variables during
148 // class construction.
149 static const SourceId kInvalidSourceId = -1;
150
151 virtual ~ResonanceAudioApi() {}
152
153 // Renders and outputs an interleaved output buffer in float format.
154 //
155 // @param num_frames Size of output buffer in frames.
156 // @param num_channels Number of channels in output buffer.
157 // @param buffer_ptr Raw float pointer to audio buffer.
158 // @return True if a valid output was successfully rendered, false otherwise.
159 virtual bool FillInterleavedOutputBuffer(size_t num_channels,
160 size_t num_frames,
161 float* buffer_ptr) = 0;
162
163 // Renders and outputs an interleaved output buffer in int16 format.
164 //
165 // @param num_channels Number of channels in output buffer.
166 // @param num_frames Size of output buffer in frames.
167 // @param buffer_ptr Raw int16 pointer to audio buffer.
168 // @return True if a valid output was successfully rendered, false otherwise.
169 virtual bool FillInterleavedOutputBuffer(size_t num_channels,
170 size_t num_frames,
171 int16* buffer_ptr) = 0;
172
173 // Renders and outputs a planar output buffer in float format.
174 //
175 // @param num_frames Size of output buffer in frames.
176 // @param num_channels Number of channels in output buffer.
177 // @param buffer_ptr Pointer to array of raw float pointers to each channel of
178 // the audio buffer.
179 // @return True if a valid output was successfully rendered, false otherwise.
180 virtual bool FillPlanarOutputBuffer(size_t num_channels, size_t num_frames,
181 float* const* buffer_ptr) = 0;
182
183 // Renders and outputs a planar output buffer in int16 format.
184 //
185 // @param num_channels Number of channels in output buffer.
186 // @param num_frames Size of output buffer in frames.
187 // @param buffer_ptr Pointer to array of raw int16 pointers to each channel of
188 // the audio buffer.
189 // @return True if a valid output was successfully rendered, false otherwise.
190 virtual bool FillPlanarOutputBuffer(size_t num_channels, size_t num_frames,
191 int16* const* buffer_ptr) = 0;
192
193 // Sets listener's head position.
194 //
195 // @param x X coordinate of head position in world space.
196 // @param y Y coordinate of head position in world space.
197 // @param z Z coordinate of head position in world space.
198 virtual void SetHeadPosition(float x, float y, float z) = 0;
199
200 // Sets listener's head rotation.
201 //
202 // @param x X component of quaternion.
203 // @param y Y component of quaternion.
204 // @param z Z component of quaternion.
205 // @param w W component of quaternion.
206 virtual void SetHeadRotation(float x, float y, float z, float w) = 0;
207
208 // Sets the master volume of the main audio output.
209 //
210 // @param volume Master volume (linear) in amplitude in range [0, 1] for
211 // attenuation, range [1, inf) for gain boost.
212 virtual void SetMasterVolume(float volume) = 0;
213
214 // Enables the stereo speaker mode. When activated, it disables HRTF-based
215 // filtering and switches to computationally cheaper stereo-panning. This
216 // helps to avoid HRTF-based coloring effects when stereo speakers are used
217 // and reduces computational complexity when headphone-based HRTF filtering is
218 // not needed. By default the stereo speaker mode is disabled. Note that
219 // stereo speaker mode overrides the |enable_hrtf| flag in
220 // |CreateSoundObjectSource|.
221 //
222 // @param enabled Flag to enable stereo speaker mode.
223 virtual void SetStereoSpeakerMode(bool enabled) = 0;
224
225 // Creates an ambisonic source instance.
226 //
227 // @param num_channels Number of input channels.
228 // @return Id of new ambisonic source.
229 virtual SourceId CreateAmbisonicSource(size_t num_channels) = 0;
230
231 // Creates a stereo non-spatialized source instance, which directly plays back
232 // mono or stereo audio.
233 //
234 // @param num_channels Number of input channels.
235 // @return Id of new non-spatialized source.
236 virtual SourceId CreateStereoSource(size_t num_channels) = 0;
237
238 // Creates a sound object source instance.
239 //
240 // @param rendering_mode Rendering mode which governs quality and performance.
241 // @return Id of new sound object source.
242 virtual SourceId CreateSoundObjectSource(RenderingMode rendering_mode) = 0;
243
244 // Destroys source instance.
245 //
246 // @param source_id Id of source to be destroyed.
247 virtual void DestroySource(SourceId id) = 0;
248
249 // Sets the next audio buffer in interleaved float format to a sound source.
250 //
251 // @param source_id Id of sound source.
252 // @param audio_buffer_ptr Pointer to interleaved float audio buffer.
253 // @param num_channels Number of channels in interleaved audio buffer.
254 // @param num_frames Number of frames per channel in interleaved audio buffer.
255 virtual void SetInterleavedBuffer(SourceId source_id,
256 const float* audio_buffer_ptr,
257 size_t num_channels, size_t num_frames) = 0;
258
259 // Sets the next audio buffer in interleaved int16 format to a sound source.
260 //
261 // @param source_id Id of sound source.
262 // @param audio_buffer_ptr Pointer to interleaved int16 audio buffer.
263 // @param num_channels Number of channels in interleaved audio buffer.
264 // @param num_frames Number of frames per channel in interleaved audio buffer.
265 virtual void SetInterleavedBuffer(SourceId source_id,
266 const int16* audio_buffer_ptr,
267 size_t num_channels, size_t num_frames) = 0;
268
269 // Sets the next audio buffer in planar float format to a sound source.
270 //
271 // @param source_id Id of sound source.
272 // @param audio_buffer_ptr Pointer to array of pointers referring to planar
273 // audio buffers for each channel.
274 // @param num_channels Number of planar input audio buffers.
275 // @param num_frames Number of frames per channel.
276 virtual void SetPlanarBuffer(SourceId source_id,
277 const float* const* audio_buffer_ptr,
278 size_t num_channels, size_t num_frames) = 0;
279
280 // Sets the next audio buffer in planar int16 format to a sound source.
281 //
282 // @param source_id Id of sound source.
283 // @param audio_buffer_ptr Pointer to array of pointers referring to planar
284 // audio buffers for each channel.
285 // @param num_channels Number of planar input audio buffers.
286 // @param num_frames Number of frames per channel.
287 virtual void SetPlanarBuffer(SourceId source_id,
288 const int16* const* audio_buffer_ptr,
289 size_t num_channels, size_t num_frames) = 0;
290
291 // Sets the given source's distance attenuation value explicitly. The distance
292 // rolloff model of the source must be set to |DistanceRolloffModel::kNone|
293 // for the set value to take effect.
294 //
295 // @param source_id Id of source.
296 // @param distance_attenuation Distance attenuation value.
297 virtual void SetSourceDistanceAttenuation(SourceId source_id,
298 float distance_attenuation) = 0;
299
300 // Sets the given source's distance attenuation method with minimum and
301 // maximum distances. Maximum distance must be greater than the minimum
302 // distance for the method to be set.
303 //
304 // @param source_id Id of source.
305 // @param rolloff Linear or logarithmic distance rolloff models.
306 // @param min_distance Minimum distance to apply distance attenuation method.
307 // @param max_distance Maximum distance to apply distance attenuation method.
308 virtual void SetSourceDistanceModel(SourceId source_id,
309 DistanceRolloffModel rolloff,
310 float min_distance,
311 float max_distance) = 0;
312
313 // Sets the given source's position. Note that, the given position for an
314 // ambisonic source is only used to determine the corresponding room effects
315 // to be applied.
316 //
317 // @param source_id Id of source.
318 // @param x X coordinate of source position in world space.
319 // @param y Y coordinate of source position in world space.
320 // @param z Z coordinate of source position in world space.
321 virtual void SetSourcePosition(SourceId source_id, float x, float y,
322 float z) = 0;
323
324 // Sets the room effects contribution for the given source.
325 //
326 // @param source_id Id of source.
327 // @param room_effects_gain Linear room effects volume in amplitude in range
328 // [0, 1] for attenuation, range [1, inf) for gain boost.
329 virtual void SetSourceRoomEffectsGain(SourceId source_id,
330 float room_effects_gain) = 0;
331
332 // Sets the given source's rotation.
333 //
334 // @param source_id Id of source.
335 // @param x X component of quaternion.
336 // @param y Y component of quaternion.
337 // @param z Z component of quaternion.
338 // @param w W component of quaternion.
339 virtual void SetSourceRotation(SourceId source_id, float x, float y, float z,
340 float w) = 0;
341
342 // Sets the given source's volume.
343 //
344 // @param source_id Id of source.
345 // @param volume Linear source volume in amplitude in range [0, 1] for
346 // attenuation, range [1, inf) for gain boost.
347 virtual void SetSourceVolume(SourceId source_id, float volume) = 0;
348
349 // Sets the given sound object source's directivity.
350 //
351 // @param sound_object_source_id Id of sound object source.
352 // @param alpha Weighting balance between figure of eight pattern and circular
353 // pattern for source emission in range [0, 1]. A value of 0.5 results in
354 // a cardioid pattern.
355 // @param order Order applied to computed directivity. Higher values will
356 // result in narrower and sharper directivity patterns. Range [1, inf).
357 virtual void SetSoundObjectDirectivity(SourceId sound_object_source_id,
358 float alpha, float order) = 0;
359
360 // Sets the listener's directivity with respect to the given sound object.
361 // This method could be used to simulate an angular rolloff in terms of the
362 // listener's orientation, given the polar pickup pattern with |alpha| and
363 // |order|.
364 //
365 // @param sound_object_source_id Id of sound object source.
366 // @param alpha Weighting balance between figure of eight pattern and circular
367 // pattern for listener's pickup in range [0, 1]. A value of 0.5 results
368 // in a cardioid pattern.
369 // @param order Order applied to computed pickup pattern. Higher values will
370 // result in narrower and sharper pickup patterns. Range [1, inf).
371 virtual void SetSoundObjectListenerDirectivity(
372 SourceId sound_object_source_id, float alpha, float order) = 0;
373
374 // Sets the gain (linear) of the near field effect.
375 //
376 // @param sound_object_source_id Id of sound object source.
377 // @param gain Gain of the near field effect. Range [0, 9] (corresponding to
378 // approx. (-Inf, +20dB]).
379 virtual void SetSoundObjectNearFieldEffectGain(
380 SourceId sound_object_source_id, float gain) = 0;
381
382 // Sets the given sound object source's occlusion intensity.
383 //
384 // @param sound_object_source_id Id of sound object source.
385 // @param intensity Number of occlusions occurred for the object. The value
386 // can be set to fractional for partial occlusions. Range [0, inf).
387 virtual void SetSoundObjectOcclusionIntensity(SourceId sound_object_source_id,
388 float intensity) = 0;
389
390 // Sets the given sound object source's spread.
391 //
392 // @param sound_object_source_id Id of sound object source.
393 // @param spread_deg Spread in degrees.
394 virtual void SetSoundObjectSpread(SourceId sound_object_source_id,
395 float spread_deg) = 0;
396
397 // Turns on/off the reflections and reverberation.
398 virtual void EnableRoomEffects(bool enable) = 0;
399
400 // Sets the early reflection properties of the environment.
401 //
402 // @param reflection_properties Reflection properties.
403 virtual void SetReflectionProperties(
404 const ReflectionProperties& reflection_properties) = 0;
405
406 // Sets the late reverberation properties of the environment.
407 //
408 // @param reverb_properties Reverb properties.
409 virtual void SetReverbProperties(
410 const ReverbProperties& reverb_properties) = 0;
411};
412
413} // namespace vraudio
414
415#endif // RESONANCE_AUDIO_API_RESONANCE_AUDIO_API_H_
416
417

source code of qtmultimedia/src/3rdparty/resonance-audio/resonance_audio/api/resonance_audio_api.h