Table of Contents

Wwise SDK 2018.1.11
AkiOSSoundEngine.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Version: <VERSION> Build: <BUILDNUMBER>
25  Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
26 *******************************************************************************/
27 
28 // AkiOSSoundEngine.h
29 
30 /// \file
31 /// Main Sound Engine interface, specific iOS.
32 
33 #ifndef _AK_IOS_SOUND_ENGINE_H_
34 #define _AK_IOS_SOUND_ENGINE_H_
35 
38 
39 #include <AudioToolbox/AudioToolbox.h>
40 
41 /// The IDs of the iOS audio session categories, useful for defining app-level audio behaviours such as inter-app audio mixing policies and audio routing behaviours. These IDs are funtionally equivalent to the corresponding constants defined by the iOS audio session service backend (AVAudioSession). Refer to Xcode documentation for details on the audio session categories. The original prefix "AV" is replaced with "Ak" for the ID names.
42 ///
43 /// \remark An audio session category may demand a fixed value for a certain category options (AkAudioSessionCategoryOptions) depending on the underlying audio session services. Ensure that AkPlatformInitSettings.audioSession.eCategory and AkPlatformInitSettings.audioSession.eCategoryOptions be compatible with each other. If conflicts are detected between the user-specified audio sessoin category and category options, the sound engine will try to fix them during the initialization according to the underlying policies defined by the audio services. The policies are:
44 /// - The audio session category AkAudioSessionCategory_AmbientSound forbid the use of the category options: AkAudioSessionCategoryOptionAllowBluetooth and AkAudioSessionCategoryOptionDefaultToSpeaker.
45 /// - AkAudioSessionCategory_SoloAmbientSound forbid the use of the category options: AkAudioSessionCategoryOptionAllowBluetooth and AkAudioSessionCategoryOptionDefaultToSpeaker.
46 ///
47 /// \sa
48 /// - \ref AkPlatformInitSettings
49 /// - \ref AkAudioSessionCategoryOptions
50 /// - \ref AkAudioSessionProperties
52 {
53  AkAudioSessionCategoryAmbient, ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryAmbient constant
54  AkAudioSessionCategorySoloAmbient, ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategorySoloAmbient constant
55  AkAudioSessionCategoryPlayAndRecord ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayAndRecord constant
56 };
57 
58 /// The IDs of the iOS audio session category options, used for customizing the audio session category features. These IDs are funtionally equivalent to the corresponding constants defined by the iOS audio session service backend (AVAudioSession). Refer to Xcode documentation for details on the audio session category options. The original prefix "AV" is replaced with "Ak" for the ID names.
59 ///
60 /// \sa
61 /// - \ref AkPlatformInitSettings
62 /// - \ref AkAudioSessionCategory
63 /// - \ref AkAudioSessionProperties
65 {
66  AkAudioSessionCategoryOptionMixWithOthers = 1, ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionMixWithOthers constant
67  AkAudioSessionCategoryOptionDuckOthers = 2, ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionDuckOthers constant
68  AkAudioSessionCategoryOptionAllowBluetooth = 4, ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionAllowBluetooth constant
69  AkAudioSessionCategoryOptionDefaultToSpeaker = 8 ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionDefaultToSpeaker constant
70 };
71 
72 /// The IDs of the iOS audio session modes, used for customizing the audio session for typical app types. These IDs are funtionally equivalent to the corresponding constants defined by the iOS audio session service backend (AVAudioSession). Refer to Xcode documentation for details on the audio session category options. The original prefix "AV" is replaced with "Ak" for the ID names.
73 ///
74 /// \sa
75 /// - \ref AkPlatformInitSettings
76 /// - \ref AkAudioSessionProperties
78 {
79  AkAudioSessionModeDefault, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeDefault constant
80  AkAudioSessionModeVoiceChat, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVoiceChat constant
81  AkAudioSessionModeGameChat, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeGameChat constant
82  AkAudioSessionModeVideoRecording, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVideoRecording constant
83  AkAudioSessionModeMeasurement, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMeasurement constant
84  AkAudioSessionModeMoviePlayback, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant
85  AkAudioSessionModeVideoChat ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant
86 };
87 
88 /// The behaviour flags for when iOS audio session is activated. These IDs are funtionally equivalent to the corresponding constants defined by the iOS audio session service backend (AVAudioSession). Refer to Xcode documentation for details on the audio session category options. The original prefix "AV" is replaced with "Ak" for the ID names.
89 ///
90 /// \sa
91 /// - \ref AkPlatformInitSettings
92 /// - \ref AkAudioSessionProperties
94 {
95  AkAudioSessionSetActiveOptionNotifyOthersOnDeactivation = 1 ///< Audio session activation option corresponding to the AVAudiosession's AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation constant
96 };
97 
98 /// The API structure used with AkPlatformInitSettings for specifying iOS audio session for the sound engine.
99 ///
100 /// \sa
101 /// - \ref AkPlatformInitSettings
102 /// - \ref AkAudioSessionCategory
103 /// - \ref AkAudioSessionCategoryOptions
104 /// - \ref AkAudioSessionMode
105 /// - \ref AkAudioSessionSetActiveOptions
107 {
108  AkAudioSessionCategory eCategory; ///< \sa AkAudioSessionCategory
109  AkAudioSessionCategoryOptions eCategoryOptions; ///< \sa AkAudioSessionCategoryOptions
110  AkAudioSessionMode eMode; ///< \sa AkAudioSessionMode
111  AkAudioSessionSetActiveOptions eSetActivateOptions; ///< \sa AkAudioSessionSetActiveOptions
112 };
113 
114 namespace AK
115 {
116  namespace SoundEngine
117  {
118  namespace iOS
119  {
120  /// iOS-only callback function prototype used for audio input source plugin. Implement this function to transfer the
121  /// input sample data to the sound engine and perform brief custom processing.
122  /// \remark See the remarks of \ref AkGlobalCallbackFunc.
123  ///
124  /// \sa
125  /// - \ref AkPlatformInitSettings
127  AudioBufferList* io_Data, ///< An exposed CoreAudio structure that holds the input audio samples generated from
128  ///< audio input hardware. The buffer is pre-allocated by the sound engine and the buffer
129  ///< size can be obtained from the structure. Refer to the microphone demo of the IntegrationDemo for an example of usage.
130  void* in_pCookie ///< User-provided data, e.g., a user structure.
131  );
132 
133  /// iOS-only callback function prototype used for handling audio session interruption. It is mandatory to implement
134  /// this callback to respond to audio interruptions such as phone calls or alarms according to the application logic.
135  /// The examples of such responses include calling relevant sound engine API to suspend the device or wake up the
136  /// device from suspend, and enabling certain UI elements when an interruption happens.
137  /// \remark
138  /// - Under interruptible (non-mixable) audio session categories, the app needs to respond to audio interruptions such as phone calls, alarms, or the built-in music player control from various remote control interfaces, according to app's own policy. Such a policy may include pausing and resuming the sound engine pipeline, pausing and resuming the entire game, and updating UI elements either as the feedback to users about the interruption status, or as a means for the users to restore the audio manually if the application requires the user intervention.
139  /// - There is no need to call AK::SoundEngine::Suspend() and AK::SoundEngine::WakeupFromSuspend() in this callback. The sound engine call them internally depending on the interruption status.
140  /// - When in_bEnterInterruption is true, this callback is called before the sound engine calls AK::SoundEngine::Suspend(), where user can take actions to prepare for the suspend, e.g., posting global pause events or switching to a special user interface; when in_bEnterInterruption is false, this callback is called after the sound engine calls AK::SoundEngine::WakeFromSuspend() and only when waking up succeeds, so that user can restore suspended resources, e.g., post global resume events or switching back to default user interface. This is useful for games in which audio is essential to the gameplay.
141  /// - Under the AkAudioSessionCategorySoloAmbient audio session category, to avoid remote-control-related audio loss, any pause event posted in this callback when entering interruption needs to be paired with a resume event in the AudioSourceChangeCallbackFunc's conditional branch for when other app's audio is not playing. This is because by Apple's design, under this category, the end of interruption will trigger the source change callback instead of the interruption callback if the interruption source is the user music.
142  /// - Starting from iOS 7, under the AkAudioSessionCategorySoloAmbient audio session category, this callback will be triggered with an end-of-interruption flag when app returns to the foreground from previous backgrounding, e.g., after a home-screen-and-back cycle, or a locking-unlocking cycle. It is triggered after the applicationDidBecomeActive: call. This means that the background music decisions made within applicationDidBecomeActive: can be overriden by the interruption callback.
143  ///
144  /// \sa
145  /// - \ref AkGlobalCallbackFunc
146  /// - \ref AkPlatformInitSettings
147  /// - \ref Suspend
148  /// - \ref WakeupFromSuspend
150  bool in_bEnterInterruption, ///< Indicating whether or not an interruption is about to start (e.g., an incoming
151  ///< call is received) or end (e.g., the incoming call is dismissed).
152 
153  void* in_pCookie ///< User-provided data, e.g., a user structure.
154  );
155  }
156  }
157 }
158 
159 /// The API structure used for specifying all iOS-specific callback functions and user data from the app side.
160 ///
161 /// \sa
162 /// - \ref AkPlatformInitSettings
164 {
165  AK::SoundEngine::iOS::AudioInputCallbackFunc inputCallback; ///< Application-defined audio input callback function
166  void* inputCallbackCookie; ///< Application-defined user data for the audio input callback function
167  AK::SoundEngine::iOS::AudioInterruptionCallbackFunc interruptionCallback; ///< Application-defined audio interruption callback function
168  void* interruptionCallbackCookie; ///< Application-defined user data for the audio interruption callback function
169 };
170 
171 /// Platform specific initialization settings
172 /// \sa AK::SoundEngine::Init
173 /// \sa AK::SoundEngine::GetDefaultPlatformInitSettings
174 /// - \ref soundengine_initialization_advanced_soundengine_using_memory_threshold
175 /// - \ref AK::SoundEngine::iOS::AkAudioSessionCategory
177 {
178  // Threading model.
179  AkThreadProperties threadLEngine; ///< Lower engine threading properties
180  AkThreadProperties threadOutputMgr; ///< Ouput thread threading properties
181  AkThreadProperties threadBankManager; ///< Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
182  AkThreadProperties threadMonitor; ///< Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL). This parameter is not used in Release build.
183 
184  // Memory.
185  AkReal32 fLEngineDefaultPoolRatioThreshold; ///< 0.0f to 1.0f value: The percentage of occupied memory where the
186  ///< sound engine should enter in Low memory mode. \ref soundengine_initialization_advanced_soundengine_using_memory_threshold
187  AkUInt32 uLEngineDefaultPoolSize;///< Lower Engine default memory pool size
188  AkUInt32 uSampleRate; ///< Sampling Rate. Default 48000 Hz
189  // Voices.
190  AkUInt16 uNumRefillsInVoice; ///< Number of refill buffers in voice buffer. 2 == double-buffered, defaults to 4
191  AkAudioSessionProperties audioSession; ///< iOS audio session properties
192  AkAudioCallbacks audioCallbacks; ///< iOS audio callbacks
193 };
194 
195 
196 #endif //_AK_IOS_SOUND_ENGINE_H_
AkThreadProperties threadBankManager
Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
AKRESULT(* AudioInterruptionCallbackFunc)(bool in_bEnterInterruption, void *in_pCookie)
AkAudioSessionProperties audioSession
iOS audio session properties
AkUInt32 uSampleRate
Sampling Rate. Set to 0 to get the native sample rate. Default value is 0.
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeDefault constant.
Definition: AkiOSSoundEngine.h:79
uint16_t AkUInt16
Unsigned 16-bit integer.
Definition: AkTypes.h:78
void * interruptionCallbackCookie
Application-defined user data for the audio interruption callback function.
AkThreadProperties threadLEngine
Lower engine threading properties.
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVoiceChat constant.
Definition: AkiOSSoundEngine.h:80
AKRESULT
Standard function call result.
Definition: AkTypes.h:126
AkAudioSessionCategory
Definition: AkiOSSoundEngine.h:51
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant.
Definition: AkiOSSoundEngine.h:85
Audiokinetic namespace.
AkAudioSessionMode
Definition: AkiOSSoundEngine.h:77
AK_ID_DECLARE BasePlatformID iOS
Definition: PlatformID.h:115
AkAudioSessionMode eMode
AkAudioSessionSetActiveOptions eSetActivateOptions
AkAudioCallbacks audioCallbacks
iOS audio callbacks
AkUInt32 uLEngineDefaultPoolSize
Lower Engine default memory pool size.
void * inputCallbackCookie
Application-defined user data for the audio input callback function.
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMeasurement constant.
Definition: AkiOSSoundEngine.h:83
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVideoRecording constant.
Definition: AkiOSSoundEngine.h:82
Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionAllow...
Definition: AkiOSSoundEngine.h:68
AkReal32 fLEngineDefaultPoolRatioThreshold
0.0f to 1.0f value: The percentage of occupied memory where the sound engine should enter in Low memo...
AKRESULT(* AudioInputCallbackFunc)(AudioBufferList *io_Data, void *in_pCookie)
AkUInt16 uNumRefillsInVoice
Number of refill buffers in voice buffer. Defaults to 4.
AK::SoundEngine::iOS::AudioInterruptionCallbackFunc interruptionCallback
Application-defined audio interruption callback function.
AkAudioSessionSetActiveOptions
Definition: AkiOSSoundEngine.h:93
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant.
Definition: AkiOSSoundEngine.h:84
AkAudioSessionCategoryOptions
Definition: AkiOSSoundEngine.h:64
AkAudioSessionCategoryOptions eCategoryOptions
Audio session activation option corresponding to the AVAudiosession's AVAudioSessionSetActiveOptionNo...
Definition: AkiOSSoundEngine.h:95
AkThreadProperties threadOutputMgr
Ouput thread threading properties.
Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionMixWi...
Definition: AkiOSSoundEngine.h:66
Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionDuckO...
Definition: AkiOSSoundEngine.h:67
AkThreadProperties threadMonitor
Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL)....
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkTypes.h:79
AkAudioSessionCategory eCategory
Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionDefau...
Definition: AkiOSSoundEngine.h:69
AK::SoundEngine::iOS::AudioInputCallbackFunc inputCallback
Application-defined audio input callback function.
float AkReal32
32-bit floating point
Definition: AkTypes.h:97
Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeGameChat constant.
Definition: AkiOSSoundEngine.h:81
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryAmbient constant.
Definition: AkiOSSoundEngine.h:53
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategorySoloAmbient consta...
Definition: AkiOSSoundEngine.h:54
Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayAndRecord cons...
Definition: AkiOSSoundEngine.h:55