Table of Contents

include/AK/SoundEngine/Platforms/iOS/AkiOSSoundEngine.h

Go to the documentation of this file.
00001 /*******************************************************************************
00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
00003 released in source code form as part of the SDK installer package.
00004 
00005 Commercial License Usage
00006 
00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
00008 may use this file in accordance with the end user license agreement provided 
00009 with the software or, alternatively, in accordance with the terms contained in a
00010 written agreement between you and Audiokinetic Inc.
00011 
00012 Apache License Usage
00013 
00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the 
00015 "Apache License"); you may not use this file except in compliance with the 
00016 Apache License. You may obtain a copy of the Apache License at 
00017 http://www.apache.org/licenses/LICENSE-2.0.
00018 
00019 Unless required by applicable law or agreed to in writing, software distributed
00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
00022 the specific language governing permissions and limitations under the License.
00023 
00024   Version: <VERSION>  Build: <BUILDNUMBER>
00025   Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
00026 *******************************************************************************/
00027 
00028 // AkiOSSoundEngine.h
00029 
00030 /// \file 
00031 /// Main Sound Engine interface, specific iOS.
00032 
00033 #ifndef _AK_IOS_SOUND_ENGINE_H_
00034 #define _AK_IOS_SOUND_ENGINE_H_
00035 
00036 #include <AK/SoundEngine/Common/AkTypes.h>
00037 #include <AK/Tools/Common/AkPlatformFuncs.h>
00038 
00039 #include <AudioToolbox/AudioToolbox.h>
00040 
00041 /// 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.
00042 ///
00043 /// \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:
00044 /// - The audio session category AkAudioSessionCategory_AmbientSound forbid the use of the category options: AkAudioSessionCategoryOptionAllowBluetooth and AkAudioSessionCategoryOptionDefaultToSpeaker.
00045 /// - AkAudioSessionCategory_SoloAmbientSound forbid the use of the category options: AkAudioSessionCategoryOptionAllowBluetooth and AkAudioSessionCategoryOptionDefaultToSpeaker.
00046 ///
00047 /// \sa
00048 /// - \ref AkPlatformInitSettings
00049 /// - \ref AkAudioSessionCategoryOptions
00050 /// - \ref AkAudioSessionProperties
00051 enum AkAudioSessionCategory
00052 {
00053     AkAudioSessionCategoryAmbient, ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryAmbient constant
00054     AkAudioSessionCategorySoloAmbient, ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategorySoloAmbient constant
00055     AkAudioSessionCategoryPlayAndRecord ///< Audio session category corresponding to the AVAudiosession's AVAudioSessionCategoryPlayAndRecord constant
00056 };
00057 
00058 /// 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.
00059 ///
00060 /// \sa
00061 /// - \ref AkPlatformInitSettings
00062 /// - \ref AkAudioSessionCategory
00063 /// - \ref AkAudioSessionProperties
00064 enum AkAudioSessionCategoryOptions
00065 {
00066     AkAudioSessionCategoryOptionMixWithOthers  = 1, ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionMixWithOthers constant
00067     AkAudioSessionCategoryOptionDuckOthers  = 2, ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionDuckOthers constant
00068     AkAudioSessionCategoryOptionAllowBluetooth  = 4, ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionAllowBluetooth constant
00069     AkAudioSessionCategoryOptionDefaultToSpeaker  = 8 ///< Audio session category option corresponding to the AVAudiosession's AVAudioSessionCategoryOptionDefaultToSpeaker constant
00070 };
00071 
00072 /// 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.
00073 ///
00074 /// \sa
00075 /// - \ref AkPlatformInitSettings
00076 /// - \ref AkAudioSessionProperties
00077 enum AkAudioSessionMode
00078 {
00079     AkAudioSessionModeDefault, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeDefault constant
00080     AkAudioSessionModeVoiceChat, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVoiceChat constant
00081     AkAudioSessionModeGameChat, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeGameChat constant
00082     AkAudioSessionModeVideoRecording, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeVideoRecording constant
00083     AkAudioSessionModeMeasurement, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMeasurement constant
00084     AkAudioSessionModeMoviePlayback, ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant
00085     AkAudioSessionModeVideoChat ///< Audio session mode corresponding to the AVAudiosession's AVAudioSessionModeMoviePlayback constant
00086 };
00087 
00088 /// 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.
00089 ///
00090 /// \sa
00091 /// - \ref AkPlatformInitSettings
00092 /// - \ref AkAudioSessionProperties
00093 enum AkAudioSessionSetActiveOptions
00094 {
00095      AkAudioSessionSetActiveOptionNotifyOthersOnDeactivation  = 1 ///< Audio session activation option corresponding to the AVAudiosession's AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation constant
00096 };
00097 
00098 /// The API structure used with AkPlatformInitSettings for specifying iOS audio session for the sound engine.
00099 ///
00100 /// \sa
00101 /// - \ref AkPlatformInitSettings
00102 /// - \ref AkAudioSessionCategory
00103 /// - \ref AkAudioSessionCategoryOptions
00104 /// - \ref AkAudioSessionMode
00105 /// - \ref AkAudioSessionSetActiveOptions
00106 struct AkAudioSessionProperties
00107 {
00108     AkAudioSessionCategory eCategory; ///< \sa AkAudioSessionCategory
00109     AkAudioSessionCategoryOptions eCategoryOptions; ///< \sa AkAudioSessionCategoryOptions
00110     AkAudioSessionMode eMode; ///< \sa AkAudioSessionMode
00111     AkAudioSessionSetActiveOptions eSetActivateOptions; ///< \sa AkAudioSessionSetActiveOptions
00112 };
00113 
00114 namespace AK
00115 {
00116     namespace SoundEngine
00117     {
00118         namespace iOS
00119         {
00120             /// iOS-only callback function prototype used for audio input source plugin. Implement this function to transfer the 
00121             /// input sample data to the sound engine and perform brief custom processing.
00122             /// \remark See the remarks of \ref AkGlobalCallbackFunc.
00123             ///
00124             /// \sa
00125             /// - \ref AkPlatformInitSettings
00126             typedef AKRESULT ( * AudioInputCallbackFunc )(
00127                 AudioBufferList* io_Data,   ///< An exposed CoreAudio structure that holds the input audio samples generated from 
00128                                             ///< audio input hardware. The buffer is pre-allocated by the sound engine and the buffer 
00129                                             ///< size can be obtained from the structure. Refer to the microphone demo of the IntegrationDemo for an example of usage.
00130                 void* in_pCookie ///< User-provided data, e.g., a user structure.
00131                 );
00132 
00133             /// iOS-only callback function prototype used for handling audio session interruption. It is mandatory to implement 
00134             /// this callback to respond to audio interruptions such as phone calls or alarms according to the application logic. 
00135             /// The examples of such responses include calling relevant sound engine API to suspend the device or wake up the 
00136             /// device from suspend, and enabling certain UI elements when an interruption happens.
00137             /// \remark 
00138             /// - 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.
00139             /// - 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.
00140             /// - 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.
00141             /// - 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.
00142             /// - 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.
00143             ///
00144             /// \sa
00145             /// - \ref AkGlobalCallbackFunc
00146             /// - \ref AkPlatformInitSettings
00147             /// - \ref Suspend
00148             /// - \ref WakeupFromSuspend
00149             typedef AKRESULT ( * AudioInterruptionCallbackFunc )(
00150                 bool in_bEnterInterruption, ///< Indicating whether or not an interruption is about to start (e.g., an incoming 
00151                                             ///< call is received) or end (e.g., the incoming call is dismissed).
00152 
00153                 void* in_pCookie ///< User-provided data, e.g., a user structure.
00154                 );
00155         }
00156     }
00157 }
00158 
00159 /// The API structure used for specifying all iOS-specific callback functions and user data from the app side.
00160 ///
00161 /// \sa
00162 /// - \ref AkPlatformInitSettings
00163 struct AkAudioCallbacks
00164 {
00165     AK::SoundEngine::iOS::AudioInputCallbackFunc inputCallback;                 ///< Application-defined audio input callback function
00166     void* inputCallbackCookie;                                                  ///< Application-defined user data for the audio input callback function
00167     AK::SoundEngine::iOS::AudioInterruptionCallbackFunc interruptionCallback;   ///< Application-defined audio interruption callback function
00168     void* interruptionCallbackCookie;                                           ///< Application-defined user data for the audio interruption callback function
00169 };
00170 
00171 /// Platform specific initialization settings
00172 /// \sa AK::SoundEngine::Init
00173 /// \sa AK::SoundEngine::GetDefaultPlatformInitSettings
00174 /// - \ref soundengine_initialization_advanced_soundengine_using_memory_threshold
00175 /// - \ref AK::SoundEngine::iOS::AkAudioSessionCategory
00176 struct AkPlatformInitSettings
00177 {
00178     // Threading model.
00179     AkThreadProperties  threadLEngine;          ///< Lower engine threading properties
00180     AkThreadProperties  threadOutputMgr;        ///< Ouput thread threading properties
00181     AkThreadProperties  threadBankManager;      ///< Bank manager threading properties (its default priority is AK_THREAD_PRIORITY_NORMAL)
00182     AkThreadProperties  threadMonitor;          ///< Monitor threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL). This parameter is not used in Release build.
00183     
00184     // Memory.
00185     AkReal32            fLEngineDefaultPoolRatioThreshold;  ///< 0.0f to 1.0f value: The percentage of occupied memory where the 
00186                                                             ///< sound engine should enter in Low memory mode. \ref soundengine_initialization_advanced_soundengine_using_memory_threshold
00187     AkUInt32            uLEngineDefaultPoolSize;///< Lower Engine default memory pool size
00188     AkUInt32            uSampleRate;            ///< Sampling Rate. Default 48000 Hz
00189     // Voices.
00190     AkUInt16            uNumRefillsInVoice;     ///< Number of refill buffers in voice buffer. 2 == double-buffered, defaults to 4
00191     AkAudioSessionProperties audioSession;  ///< iOS audio session properties 
00192     AkAudioCallbacks audioCallbacks; ///< iOS audio callbacks
00193 };
00194 
00195 
00196 #endif //_AK_IOS_SOUND_ENGINE_H_