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 // AkMusicEngine.h
00029 
00030 /// \file 
00031 /// The main music engine interface.
00032 
00033 
00034 #ifndef _AK_MUSICENGINE_H_
00035 #define _AK_MUSICENGINE_H_
00036 
00037 #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
00038 #include <AK/SoundEngine/Common/AkTypes.h>
00039 #include <AK/SoundEngine/Common/AkCallback.h>
00040 
00041 /// Platform-independent initialization settings of the music engine
00042 /// \sa 
00043 /// - AK::MusicEngine::Init()
00044 /// - \ref soundengine_integration_init_advanced
00045 struct AkMusicSettings
00046 {
00047     AkReal32 fStreamingLookAheadRatio;  ///< Multiplication factor for all streaming look-ahead heuristic values.
00048 };
00049 
00050 // Audiokinetic namespace
00051 namespace AK
00052 {
00053     /// Music engine namespace
00054     /// \warning The functions in this namespace are not thread-safe, unless stated otherwise.
00055     namespace MusicEngine
00056     {
00057         ///////////////////////////////////////////////////////////////////////
00058         /// @name Initialization
00059         //@{
00060 
00061         /// Initialize the music engine.
00062         /// \warning This function must be called after the base sound engine has been properly initialized. 
00063         /// There should be no AK API call between AK::SoundEngine::Init() and this call. Any call done in between is potentially unsafe.
00064         /// \return AK_Success if the Init was successful, AK_Fail otherwise.
00065         /// \sa
00066         /// - \ref workingwithsdks_initialization
00067         AK_EXTERNAPIFUNC( AKRESULT, Init )(
00068             AkMusicSettings *   in_pSettings    ///< Initialization settings (can be NULL, to use the default values)
00069             );
00070 
00071         /// Get the music engine's default initialization settings values
00072         /// \sa
00073         /// - \ref soundengine_integration_init_advanced
00074         /// - AK::MusicEngine::Init()
00075         AK_EXTERNAPIFUNC( void, GetDefaultInitSettings )(
00076             AkMusicSettings &   out_settings    ///< Returned default platform-independent music engine settings
00077             );
00078 
00079         /// Terminate the music engine.
00080         /// \warning This function must be called before calling Term() on the base sound engine.
00081         /// \sa
00082         /// - \ref workingwithsdks_termination
00083         AK_EXTERNAPIFUNC( void, Term )(
00084             );
00085         
00086         /// Query information on the active segment of a music object that is playing. Use the playing ID 
00087         /// that was returned from AK::SoundEngine::PostEvent(), provided that the event contained a play
00088         /// action that was targetting a music object. For any configuration of interactive music hierarchy, 
00089         /// there is only one segment that is active at a time. 
00090         /// To be able to query segment information, you must pass the AK_EnableGetMusicPlayPosition flag 
00091         /// to the AK::SoundEngine::PostEvent() method. This informs the sound engine that the source associated 
00092         /// with this event should be given special consideration because GetPlayingSegmentInfo() can be called 
00093         /// at any time for this AkPlayingID.
00094         /// Notes:
00095         /// - If the music object is a single segment, you will get negative values for AkSegmentInfo::iCurrentPosition
00096         ///     during the pre-entry. This will never occur with other types of music objects because the 
00097         ///     pre-entry of a segment always overlaps another active segment.
00098         /// - The active segment during the pre-entry of the first segment of a Playlist Container or a Music Switch 
00099         ///     Container is "nothing", as well as during the post-exit of the last segment of a Playlist (and beyond).
00100         /// - When the active segment is "nothing", out_uSegmentInfo is filled with zeros.
00101         /// - If in_bExtrapolate is true (default), AkSegmentInfo::iCurrentPosition is corrected by the amount of time elapsed
00102         ///     since the beginning of the audio frame. It is thus possible that it slightly overshoots the total segment length.
00103         /// \return AK_Success if there is a playing music structure associated with the specified playing ID.
00104         /// \sa
00105         /// - AK::SoundEngine::PostEvent
00106         /// - AkSegmentInfo
00107         AK_EXTERNAPIFUNC( AKRESULT, GetPlayingSegmentInfo )(
00108             AkPlayingID     in_PlayingID,           ///< Playing ID returned by AK::SoundEngine::PostEvent().
00109             AkSegmentInfo & out_segmentInfo,        ///< Structure containing information about the active segment of the music structure that is playing.
00110             bool            in_bExtrapolate = true  ///< Position is extrapolated based on time elapsed since last sound engine update.
00111             );
00112 
00113         //@}
00114     }
00115 }
00116 
00117 #endif // _AK_MUSICENGINE_H_
00118