AkSoundEngine.h 303 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481
  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. Commercial License Usage
  5. Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
  6. may use this file in accordance with the end user license agreement provided
  7. with the software or, alternatively, in accordance with the terms contained in a
  8. written agreement between you and Audiokinetic Inc.
  9. Apache License Usage
  10. Alternatively, this file may be used under the Apache License, Version 2.0 (the
  11. "Apache License"); you may not use this file except in compliance with the
  12. Apache License. You may obtain a copy of the Apache License at
  13. http://www.apache.org/licenses/LICENSE-2.0.
  14. Unless required by applicable law or agreed to in writing, software distributed
  15. under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
  16. OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
  17. the specific language governing permissions and limitations under the License.
  18. Copyright (c) 2023 Audiokinetic Inc.
  19. *******************************************************************************/
  20. // AkSoundEngine.h
  21. /// \file
  22. /// The main sound engine interface.
  23. #ifndef _AK_SOUNDENGINE_H_
  24. #define _AK_SOUNDENGINE_H_
  25. #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
  26. #include <AK/SoundEngine/Common/AkTypes.h>
  27. #include <AK/SoundEngine/Common/IAkPlugin.h>
  28. #include <AK/SoundEngine/Common/AkCallback.h>
  29. #ifdef AK_WIN
  30. #include <AK/SoundEngine/Platforms/Windows/AkWinSoundEngine.h>
  31. #include <AK/SoundEngine/Platforms/Windows/AkPlatformContext.h>
  32. #elif defined (AK_MAC_OS_X)
  33. #include <AK/SoundEngine/Platforms/Mac/AkMacSoundEngine.h>
  34. #include <AK/SoundEngine/Platforms/Mac/AkPlatformContext.h>
  35. #elif defined (AK_IOS)
  36. #include <AK/SoundEngine/Platforms/iOS/AkiOSSoundEngine.h>
  37. #include <AK/SoundEngine/Platforms/iOS/AkPlatformContext.h>
  38. #elif defined(AK_XBOXGC) // Gaming.Xbox platform
  39. #include <AK/SoundEngine/Platforms/XboxGC/AkXboxGCSoundEngine.h>
  40. #include <AK/SoundEngine/Platforms/XboxGC/AkPlatformContext.h>
  41. #elif defined( AK_ANDROID )
  42. #include <AK/SoundEngine/Platforms/Android/AkAndroidSoundEngine.h>
  43. #include <AK/SoundEngine/Platforms/Android/AkPlatformContext.h>
  44. #elif defined (AK_PS4)
  45. #include <AK/SoundEngine/Platforms/PS4/AkPS4SoundEngine.h>
  46. #include <AK/SoundEngine/Platforms/PS4/AkPlatformContext.h>
  47. #elif defined (AK_PS5)
  48. #include <AK/SoundEngine/Platforms/PS5/AkPS5SoundEngine.h>
  49. #include <AK/SoundEngine/Platforms/PS5/AkPlatformContext.h>
  50. #elif defined( AK_LINUX_DESKTOP )
  51. #include <AK/SoundEngine/Platforms/Linux/AkLinuxSoundEngine.h>
  52. #include <AK/SoundEngine/Platforms/Linux/AkPlatformContext.h>
  53. #elif defined( AK_EMSCRIPTEN )
  54. #include <AK/SoundEngine/Platforms/Emscripten/AkEmscriptenSoundEngine.h>
  55. #include <AK/SoundEngine/Platforms/Emscripten/AkPlatformContext.h>
  56. #elif defined( AK_QNX )
  57. #include <AK/SoundEngine/Platforms/QNX/AkQNXSoundEngine.h>
  58. #include <AK/SoundEngine/Platforms/QNX/AkPlatformContext.h>
  59. #elif defined( AK_NX )
  60. #include <AK/SoundEngine/Platforms/NX/AkNXSoundEngine.h>
  61. #include <AK/SoundEngine/Platforms/NX/AkPlatformContext.h>
  62. #else
  63. #error AkSoundEngine.h: Undefined platform
  64. #endif
  65. #ifndef AK_ASSERT_HOOK
  66. /// Function called on assert handling, optional
  67. /// \sa
  68. /// - AkInitSettings
  69. AK_CALLBACK( void, AkAssertHook)(
  70. const char * in_pszExpression, ///< Expression
  71. const char * in_pszFileName, ///< File Name
  72. int in_lineNumber ///< Line Number
  73. );
  74. #define AK_ASSERT_HOOK
  75. #endif
  76. /// Callback function prototype for User Music notifications
  77. /// It is useful for reacting to user music playback.
  78. ///
  79. /// \sa
  80. /// - \ref AkGlobalCallbackFunc
  81. /// - \ref AkPlatformInitSettings
  82. /// - \ref background_music_and_dvr
  83. ///
  84. typedef AKRESULT ( * AkBackgroundMusicChangeCallbackFunc )(
  85. bool in_bBackgroundMusicMuted, ///< Flag indicating whether the busses tagged as "background music" in the project are muted or not.
  86. void* in_pCookie ///< User-provided data, e.g. a user structure.
  87. );
  88. /// Platform-independent initialization settings of output devices.
  89. struct AkOutputSettings
  90. {
  91. AkOutputSettings() :
  92. audioDeviceShareset(AK_INVALID_UNIQUE_ID),
  93. idDevice(0),
  94. ePanningRule(AkPanningRule_Speakers),
  95. channelConfig(){};
  96. AkOutputSettings(const char* in_szDeviceShareSet, AkUniqueID in_idDevice = AK_INVALID_UNIQUE_ID, AkChannelConfig in_channelConfig = AkChannelConfig(), AkPanningRule in_ePanning = AkPanningRule_Speakers);
  97. #ifdef AK_SUPPORT_WCHAR
  98. AkOutputSettings(const wchar_t* in_szDeviceShareSet, AkUniqueID in_idDevice = AK_INVALID_UNIQUE_ID, AkChannelConfig in_channelConfig = AkChannelConfig(), AkPanningRule in_ePanning = AkPanningRule_Speakers);
  99. #endif
  100. AkUniqueID audioDeviceShareset; ///< Unique ID of a custom audio device to be used. Custom audio devices are defined in the Audio Device Shareset section of the Wwise project.
  101. ///< If you want to output normally through the output device defined on the Master Bus in your project, leave this field to its default value (AK_INVALID_UNIQUE_ID, or value 0).
  102. ///< Typical usage: AkInitSettings.eOutputSettings.audioDeviceShareset = AK::SoundEngine::GetIDFromString("InsertYourAudioDeviceSharesetNameHere");
  103. /// \sa <tt>\ref AK::SoundEngine::GetIDFromString()</tt>
  104. /// \sa \ref soundengine_plugins_audiodevices
  105. /// \sa \ref integrating_secondary_outputs
  106. /// \sa \ref default_audio_devices
  107. AkUInt32 idDevice; ///< Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
  108. /// \sa \ref obtaining_device_id
  109. AkPanningRule ePanningRule; ///< Rule for 3D panning of signals routed to a stereo bus. In AkPanningRule_Speakers mode, the angle of the front loudspeakers
  110. ///< (uSpeakerAngles[0]) is used. In AkPanningRule_Headphones mode, the speaker angles are superseded by constant power panning
  111. ///< between two virtual microphones spaced 180 degrees apart.
  112. AkChannelConfig channelConfig; ///< Channel configuration for this output. Call AkChannelConfig::Clear() to let the engine use the default output configuration.
  113. ///< Hardware might not support the selected configuration.
  114. };
  115. /// Define the orientation of the the floor plane with respect to the X,Y,Z axes, and which axes represent the side, front and up vectors as a basis for rotations in Wwise.
  116. /// AkFloorPlane is used in to orient the Game Object 3D Viewer in Wwise, and in the transformation of geometry instances in Wwise Spatial Audio.
  117. enum AkFloorPlane
  118. {
  119. AkFloorPlane_XZ = 0, ///< The floor is oriented along the ZX-plane. The front vector points towards +Z, the up vector towards +Y, and the side vector towards +X.
  120. AkFloorPlane_XY, ///< The floor is oriented along the XY-plane. The front vector points towards +X, the up vector towards +Z, and the side vector towards +Y.
  121. AkFloorPlane_YZ, ///< The floor is oriented along the YZ-plane. The front vector points towards +Y, the up vector towards +X, and the side vector towards +Z.
  122. AkFloorPlane_Default = AkFloorPlane_XZ ///< The Wwise default floor plane is ZX.
  123. };
  124. // Function that the host runtime must call to allow for jobs to execute.
  125. // in_jobType is the type originally provided by AkJobMgrSettings::FuncRequestJobWorker.
  126. // in_uExecutionTimeUsec is the number of microseconds that the function should execute for before terminating.
  127. // Note that the deadline is only checked after each individual job completes execution, so the function may run slightly
  128. // longer than intended. The "in_uExecutionTimeUsec" should be considered a suggestion or guideline, not a strict rule.
  129. // A value of 0 means that the function will run until there are no more jobs ready to be immediately executed.
  130. AK_CALLBACK(void, AkJobWorkerFunc)(
  131. AkJobType in_jobType,
  132. AkUInt32 in_uExecutionTimeUsec
  133. );
  134. /// Settings for the Sound Engine's internal job manager
  135. struct AkJobMgrSettings
  136. {
  137. /// Callback function prototype definition used for handling requests from JobMgr for new workers to perform work.
  138. AK_CALLBACK(void, FuncRequestJobWorker)(
  139. AkJobWorkerFunc in_fnJobWorker, ///< Function passed to host runtime that should be executed. Note that the function provided will exist for as long as the soundengine code is loaded, and will always be the same.
  140. AkJobType in_jobType, ///< The type of job worker that has been requested. This should be passed forward to in_fnJobWorker
  141. AkUInt32 in_uNumWorkers, ///< Number of workers requested
  142. void * in_pClientData ///< Data provided by client in AkJobMgrSettings
  143. );
  144. FuncRequestJobWorker fnRequestJobWorker; ///< Function called by the job manager when a new worker needs to be requested. When null, all jobs will be executed on the same thread that calls RenderAudio().
  145. AkUInt32 uMaxActiveWorkers[AK_NUM_JOB_TYPES]; ///< The maximum number of concurrent workers that will be requested. Must be >= 1 for each jobType.
  146. AkUInt32 uNumMemorySlabs; ///< Number of memory slabs to pre-allocate for job manager memory. At least one slab per worker thread should be pre-allocated. Default is 1.
  147. AkUInt32 uMemorySlabSize; ///< Size of each memory slab used for job manager memory. Must be a power of two. Default is 8K.
  148. void* pClientData; ///< Arbitrary data that will be passed back to the client when calling FuncRequestJobWorker
  149. };
  150. /// External (optional) callback for tracking performance of the sound engine that is called when a timer starts. (only called in Debug and Profile binaries; this is not called in Release)
  151. /// in_uPluginID may be non-zero when this function is called, to provide extra data about what context this Timer was started in.
  152. /// in_pszZoneName will point to a static string, so the pointer can be stored for later use, not just the contents of the string itself.
  153. AK_CALLBACK(void, AkProfilerPushTimerFunc)(
  154. AkPluginID in_uPluginID,
  155. const char* in_pszZoneName
  156. );
  157. /// External (optional) function for tracking performance of the sound engine that is called when a timer stops. (only called in Debug and Profile binaries; this is not called in Release)
  158. AK_CALLBACK(void, AkProfilerPopTimerFunc)();
  159. ///< External (optional) function for tracking notable events in the sound engine, to act as a marker or bookmark. (only called in Debug and Profile binaries; this is not called in Release)
  160. /// in_uPluginID may be non-zero when this function is called, to provide extra data about what context this Marker was posted in.
  161. /// in_pszMarkerName will point to a static string, so the pointer can be stored for later use, not just the contents of the string itself.
  162. AK_CALLBACK(void, AkProfilerPostMarkerFunc)(
  163. AkPluginID in_uPluginID,
  164. const char* in_pszMarkerName
  165. );
  166. /// Platform-independent initialization settings of the sound engine
  167. /// \sa
  168. /// - <tt>AK::SoundEngine::Init()</tt>
  169. /// - <tt>AK::SoundEngine::GetDefaultInitSettings()</tt>
  170. /// - \ref soundengine_integration_init_advanced
  171. struct AkInitSettings
  172. {
  173. AkAssertHook pfnAssertHook; ///< External assertion handling function (optional)
  174. AkUInt32 uMaxNumPaths; ///< Maximum number of paths for positioning
  175. AkUInt32 uCommandQueueSize; ///< Size of the command queue, in bytes
  176. bool bEnableGameSyncPreparation; ///< Sets to true to enable AK::SoundEngine::PrepareGameSync usage.
  177. AkUInt32 uContinuousPlaybackLookAhead; ///< Number of quanta ahead when continuous containers should instantiate a new voice before which next sounds should start playing. This look-ahead time allows I/O to occur, and is especially useful to reduce the latency of continuous containers with trigger rate or sample-accurate transitions.
  178. ///< Default is 1 audio quantum, also known as an audio frame. Its size is equal to AkInitSettings::uNumSamplesPerFrame / AkPlatformInitSettings::uSampleRate. For many platforms the default values - which can be overridden - are respectively 1,024 samples and 48 kHz. This gives a default 21.3 ms for an audio quantum, which is adequate if you have a RAM-based streaming device that completes transfers within 20 ms. With 1 look-ahead quantum, voices spawned by continuous containers are more likely to be ready when they are required to play, thereby improving the overall precision of sound scheduling. If your device completes transfers in 30 ms instead, you might consider increasing this value to 2 because it will grant new voices 2 audio quanta (~43 ms) to fetch data.
  179. AkUInt32 uNumSamplesPerFrame; ///< Number of samples per audio frame (256, 512, 1024, or 2048).
  180. AkUInt32 uMonitorQueuePoolSize; ///< Size of the monitoring queue, in bytes. This parameter is not used in Release build.
  181. AkUInt32 uCpuMonitorQueueMaxSize; ///< Maximum size of the CPU monitoring queue, per thread, in bytes. This parameter is not used in Release build.
  182. AkOutputSettings settingsMainOutput; ///< Main output device settings.
  183. AkJobMgrSettings settingsJobManager; ///< Settings to configure the behavior of the Sound Engine's internal job manager
  184. AkUInt32 uMaxHardwareTimeoutMs; ///< Amount of time to wait for HW devices to trigger an audio interrupt. If there is no interrupt after that time, the sound engine will revert to silent mode and continue operating until the HW finally comes back. Default value: 2000 (2 seconds)
  185. bool bUseSoundBankMgrThread; ///< Use a separate thread for loading sound banks. Allows asynchronous operations.
  186. bool bUseLEngineThread; ///< Use a separate thread for processing audio. If set to false, audio processing will occur in RenderAudio(). \ref goingfurther_eventmgrthread
  187. AkBackgroundMusicChangeCallbackFunc BGMCallback; ///< Application-defined audio source change event callback function.
  188. void* BGMCallbackCookie; ///< Application-defined user data for the audio source change event callback function.
  189. const AkOSChar * szPluginDLLPath; ///< When using DLLs for plugins, specify their path. Leave NULL if DLLs are in the same folder as the game executable.
  190. AkFloorPlane eFloorPlane; ///< Define the orientation of the the floor plane with respect to the X,Y,Z axes, and which axes represent the side, front and up vectors as a basis for rotations in Wwise.
  191. ///< AkFloorPlane is used in to orient the Game Object 3D Viewer in Wwise, and in the transformation of geometry instances in Wwise Spatial Audio.
  192. AkReal32 fGameUnitsToMeters; ///< The number of game units in a meter.
  193. ///< This setting is used to adapt the size of elements in the Authoring's Game Object 3D Viewer and Audio Object 3D Viewer to meters.
  194. ///< This setting is also used to simulate real-world positioning of System Audio Objects, to improve the HRTF in some cases.
  195. AkUInt32 uBankReadBufferSize; ///< The number of bytes read by the BankReader when new data needs to be loaded from disk during serialization. Increasing this trades memory usage for larger, but fewer, file-read events during bank loading.
  196. AkReal32 fDebugOutOfRangeLimit; ///< Debug setting: Only used when bDebugOutOfRangeCheckEnabled is true. This defines the maximum values samples can have. Normal audio must be contained within +1/-1. This limit should be set higher to allow temporary or short excursions out of range. Default is 16.
  197. bool bDebugOutOfRangeCheckEnabled; ///< Debug setting: Enable checks for out-of-range (and NAN) floats in the processing code. This incurs a small performance hit, but can be enabled in most scenarios. Will print error messages in the log if invalid values are found at various point in the pipeline. Contact AK Support with the new error messages for more information.
  198. AkProfilerPushTimerFunc fnProfilerPushTimer; ///< External (optional) function for tracking performance of the sound engine that is called when a timer starts. (only called in Debug and Profile binaries; this is not called in Release)
  199. AkProfilerPopTimerFunc fnProfilerPopTimer; ///< External (optional) function for tracking performance of the sound engine that is called when a timer stops. (only called in Debug and Profile binaries; this is not called in Release)
  200. AkProfilerPostMarkerFunc fnProfilerPostMarker; ///< External (optional) function for tracking significant events in the sound engine, to act as a marker or bookmark. (only called in Debug and Profile binaries; this is not called in Release)
  201. };
  202. /// Necessary settings for setting externally-loaded sources
  203. struct AkSourceSettings
  204. {
  205. AkUniqueID sourceID; ///< Source ID (available in the SoundBank content files)
  206. AkUInt8* pMediaMemory; ///< Pointer to the data to be set for the source
  207. AkUInt32 uMediaSize; ///< Size, in bytes, of the data to be set for the source
  208. };
  209. /// Return values for GetSourcePlayPositions.
  210. struct AkSourcePosition
  211. {
  212. AkUniqueID audioNodeID; ///< Audio Node ID of playing item
  213. AkUniqueID mediaID; ///< Media ID of playing item. (corresponds to 'ID' attribute of 'File' element in SoundBank metadata file)
  214. AkTimeMs msTime; ///< Position of the source (in ms) associated with that playing item
  215. AkUInt32 samplePosition; ///< Position of the source (in samples) associated with that playing item
  216. AkUInt32 updateBufferTick; ///< Value of GetBufferTick() at the time the position was updated
  217. };
  218. /// Audiokinetic namespace
  219. namespace AK
  220. {
  221. class IReadBytes;
  222. class IWriteBytes;
  223. /// Audiokinetic sound engine namespace
  224. /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
  225. namespace SoundEngine
  226. {
  227. ///////////////////////////////////////////////////////////////////////
  228. /// @name Initialization
  229. //@{
  230. /// Query whether or not the sound engine has been successfully initialized.
  231. /// \warning This function is not thread-safe. It should not be called at the same time as \c SoundEngine::Init() or \c SoundEngine::Term().
  232. /// \return \c True if the sound engine has been initialized, \c False otherwise.
  233. /// \sa
  234. /// - \ref soundengine_integration_init_advanced
  235. /// - <tt>AK::SoundEngine::Init()</tt>
  236. /// - <tt>AK::SoundEngine::Term()</tt>
  237. AK_EXTERNAPIFUNC( bool, IsInitialized )();
  238. /// Initialize the sound engine.
  239. /// \warning This function is not thread-safe.
  240. /// \remark The initial settings should be initialized using <tt>AK::SoundEngine::GetDefaultInitSettings()</tt>
  241. /// and <tt>AK::SoundEngine::GetDefaultPlatformInitSettings()</tt> to fill the structures with their
  242. /// default settings. This is not mandatory, but it helps avoid backward compatibility problems.
  243. ///
  244. /// \return
  245. /// - \c AK_Success if the initialization was successful
  246. /// - \c AK_MemManagerNotInitialized if the memory manager is not available or not properly initialized
  247. /// - \c AK_StreamMgrNotInitialized if the stream manager is not available or not properly initialized
  248. /// - \c AK_SSEInstructionsNotSupported if the machine does not support SSE instruction (only on the PC)
  249. /// - \c AK_InsufficientMemory if there is not enough memory available to initialize the sound engine properly
  250. /// - \c AK_InvalidParameter if some parameters are invalid
  251. /// - \c AK_AlreadyInitialized if the sound engine is already initialized, or if the provided settings result in insufficient
  252. /// - \c AK_Fail for unknown errors, check with AK Support.
  253. /// resources for the initialization.
  254. /// \sa
  255. /// - \ref soundengine_integration_init_advanced
  256. /// - \ref workingwithsdks_initialization
  257. /// - <tt>AK::SoundEngine::Term()</tt>
  258. /// - <tt>AK::SoundEngine::GetDefaultInitSettings()</tt>
  259. /// - <tt>AK::SoundEngine::GetDefaultPlatformInitSettings()</tt>
  260. AK_EXTERNAPIFUNC( AKRESULT, Init )(
  261. AkInitSettings * in_pSettings, ///< Initialization settings (can be NULL, to use the default values)
  262. AkPlatformInitSettings * in_pPlatformSettings ///< Platform-specific settings (can be NULL, to use the default values)
  263. );
  264. /// Gets the default values of the platform-independent initialization settings.
  265. /// \warning This function is not thread-safe.
  266. /// \sa
  267. /// - \ref soundengine_integration_init_advanced
  268. /// - <tt>AK::SoundEngine::Init()</tt>
  269. /// - <tt>AK::SoundEngine::GetDefaultPlatformInitSettings()</tt>
  270. AK_EXTERNAPIFUNC( void, GetDefaultInitSettings )(
  271. AkInitSettings & out_settings ///< Returned default platform-independent sound engine settings
  272. );
  273. /// Gets the default values of the platform-specific initialization settings.
  274. ///
  275. /// Windows Specific:
  276. /// HWND is the handle of the window associated with the audio.
  277. /// Each game must specify the HWND of the application for device detection purposes.
  278. /// The value returned by GetDefaultPlatformInitSettings is the foreground HWND at
  279. /// the moment of the initialization of the sound engine and might not be the correct one for your game.
  280. /// Each game must provide the correct HWND to use.
  281. ///
  282. /// \warning This function is not thread-safe.
  283. /// \sa
  284. /// - \ref soundengine_integration_init_advanced
  285. /// - <tt>AK::SoundEngine::Init()</tt>
  286. /// - <tt>AK::SoundEngine::GetDefaultInitSettings()</tt>
  287. AK_EXTERNAPIFUNC( void, GetDefaultPlatformInitSettings )(
  288. AkPlatformInitSettings & out_platformSettings ///< Returned default platform-specific sound engine settings
  289. );
  290. /// Terminates the sound engine.
  291. /// If some sounds are still playing or events are still being processed when this function is
  292. /// called, they will be stopped.
  293. /// \warning This function is not thread-safe.
  294. /// \warning Before calling Term, you must ensure that no other thread is accessing the sound engine.
  295. /// \sa
  296. /// - \ref soundengine_integration_init_advanced
  297. /// - <tt>AK::SoundEngine::Init()</tt>
  298. AK_EXTERNAPIFUNC( void, Term )();
  299. /// Gets the configured audio settings.
  300. /// Call this function to get the configured audio settings.
  301. ///
  302. /// \warning This function is not thread-safe.
  303. /// \warning Call this function only after the sound engine has been properly initialized.
  304. /// \return
  305. /// - \c AK_NotInitialized if <tt>AK::SoundEngine::Init()</tt> was not called
  306. /// - \c AK_Success otherwise.
  307. AK_EXTERNAPIFUNC( AKRESULT, GetAudioSettings )(
  308. AkAudioSettings & out_audioSettings ///< Returned audio settings
  309. );
  310. /// Gets the output speaker configuration of the specified output.
  311. /// Call this function to get the speaker configuration of the output (which may not correspond
  312. /// to the physical output format of the platform, in the case of downmixing provided by the platform itself).
  313. /// You may initialize the sound engine with a user-specified configuration, but the resulting
  314. /// configuration is determined by the sound engine, based on the platform, output type and
  315. /// platform settings (for e.g. system menu or control panel option).
  316. /// If the speaker configuration of the output is object-based, the speaker configuration of the
  317. /// main mix is returned. To query more information on object-based output devices, see AK::SoundEngine::GetOutputDeviceConfiguration.
  318. ///
  319. /// It is recommended to call GetSpeakerConfiguration anytime after receiving a callback from RegisterAudioDeviceStatusCallback to know if the channel configuration has changed.
  320. ///
  321. /// \warning Call this function only after the sound engine has been properly initialized.
  322. /// If you are initializing the sound engine with AkInitSettings::bUseLEngineThread to false, it is required to call RenderAudio() at least once before calling this function to complete the sound engine initialization.
  323. /// The Init.bnk must be loaded prior to this call.
  324. /// \return The output configuration. An empty AkChannelConfig not AkChannelConfig::IsValid() if device does not exist or if the Init.bnk was not loaded yet.
  325. /// \sa
  326. /// - AkSpeakerConfig.h
  327. /// - AkOutputSettings
  328. /// - <tt>AK::SoundEngine::GetOutputDeviceConfiguration()</tt>
  329. AK_EXTERNAPIFUNC( AkChannelConfig, GetSpeakerConfiguration )(
  330. AkOutputDeviceID in_idOutput = 0 ///< Output ID to set the bus on. As returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
  331. );
  332. /// Gets the configuration of the specified output device.
  333. /// Call this function to get the channel configuration of the output device as well as its 3D audio capabilities.
  334. /// If the configuration of the output device is object-based (io_channelConfig.eConfigType == AK_ChannelConfigType_Objects),
  335. /// io_capabilities can be inspected to determine the channel configuration of the main mix (Ak3DAudioSinkCapabilities::channelConfig),
  336. /// whether or not the output device uses a passthrough mix (Ak3DAudioSinkCapabilities::bPassthrough) and the maximum number of objects
  337. /// that can play simultaneously on this output device (Ak3DAudioSinkCapabilities::uMax3DAudioObjects). Note that if
  338. /// Ak3DAudioSinkCapabilities::bMultiChannelObjects is false, multi-channel objects will be split into multiple mono objects
  339. /// before being sent to the output device.
  340. ///
  341. /// \warning Call this function only after the sound engine has been properly initialized. If you are initializing the sound engine with AkInitSettings::bUseLEngineThread to false, it is required to call RenderAudio() at least once before calling this function to complete the sound engine initialization.
  342. /// \return
  343. /// - \c AK_Success if successful
  344. /// - \c AK_IDNotFound is the output was not found in the system.
  345. /// - \c AK_NotInitialized if the sound engine is not initialized
  346. /// \sa
  347. /// - AkSpeakerConfig.h
  348. /// - AkOutputSettings
  349. /// - <tt>AK::SoundEngine::GetSpeakerConfiguration()</tt>
  350. AK_EXTERNAPIFUNC(AKRESULT, GetOutputDeviceConfiguration)(
  351. AkOutputDeviceID in_idOutput,
  352. AkChannelConfig& io_channelConfig,
  353. Ak3DAudioSinkCapabilities& io_capabilities
  354. );
  355. /// Gets the panning rule of the specified output.
  356. /// \warning Call this function only after the sound engine has been properly initialized.
  357. /// Returns the supported configuration in out_ePanningRule:
  358. /// - AkPanningRule_Speakers
  359. /// - AkPanningRule_Headphone
  360. /// \return
  361. /// - \c AK_Success if successful
  362. /// - \c AK_IDNotFound is the output was not found in the system.
  363. /// - \c AK_NotInitialized if the sound engine is not initialized
  364. /// \sa
  365. /// - AkSpeakerConfig.h
  366. AK_EXTERNAPIFUNC( AKRESULT, GetPanningRule )(
  367. AkPanningRule & out_ePanningRule, ///< Returned panning rule (AkPanningRule_Speakers or AkPanningRule_Headphone) for given output.
  368. AkOutputDeviceID in_idOutput = 0 ///< Output ID to set the bus on. As returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
  369. );
  370. /// Sets the panning rule of the specified output.
  371. /// This may be changed anytime once the sound engine is initialized.
  372. /// \warning This function posts a message through the sound engine's internal message queue, whereas GetPanningRule() queries the current panning rule directly.
  373. /// \aknote
  374. /// The specified panning rule will only impact the sound if the processing format is downmixing to Stereo in the mixing process. It
  375. /// will not impact the output if the audio stays in 5.1 until the end, for example.
  376. /// \endaknote
  377. AK_EXTERNAPIFUNC( AKRESULT, SetPanningRule )(
  378. AkPanningRule in_ePanningRule, ///< Panning rule.
  379. AkOutputDeviceID in_idOutput = 0 ///< Output ID to set the bus on. As returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
  380. );
  381. /// Gets speaker angles of the specified device. Speaker angles are used for 3D positioning of sounds over standard configurations.
  382. /// Note that the current version of Wwise only supports positioning on the plane.
  383. /// The speaker angles are expressed as an array of loudspeaker pairs, in degrees, relative to azimuth ]0,180].
  384. /// Supported loudspeaker setups are always symmetric; the center speaker is always in the middle and thus not specified by angles.
  385. /// Angles must be set in ascending order.
  386. /// You may call this function with io_pfSpeakerAngles set to NULL to get the expected number of angle values in io_uNumAngles,
  387. /// in order to allocate your array correctly. You may also obtain this number by calling
  388. /// AK::GetNumberOfAnglesForConfig( AK_SPEAKER_SETUP_DEFAULT_PLANE ).
  389. /// If io_pfSpeakerAngles is not NULL, the array is filled with up to io_uNumAngles.
  390. /// Typical usage:
  391. /// - AkUInt32 uNumAngles;
  392. /// - GetSpeakerAngles( NULL, uNumAngles, AkOutput_Main );
  393. /// - AkReal32 * pfSpeakerAngles = AkAlloca( uNumAngles * sizeof(AkReal32) );
  394. /// - GetSpeakerAngles( pfSpeakerAngles, uNumAngles, AkOutput_Main );
  395. /// \aknote
  396. /// On most platforms, the angle set on the plane consists of 3 angles, to account for 7.1.
  397. /// - When panning to stereo (speaker mode, see <tt>AK::SoundEngine::SetPanningRule()</tt>), only angle[0] is used, and 3D sounds in the back of the listener are mirrored to the front.
  398. /// - When panning to 5.1, the front speakers use angle[0], and the surround speakers use (angle[2] + angle[1]) / 2.
  399. /// \endaknote
  400. /// \warning Call this function only after the sound engine has been properly initialized.
  401. /// \return AK_Success if device exists.
  402. /// \sa SetSpeakerAngles()
  403. AK_EXTERNAPIFUNC( AKRESULT, GetSpeakerAngles )(
  404. AkReal32 * io_pfSpeakerAngles, ///< Returned array of loudspeaker pair angles, in degrees relative to azimuth [0,180]. Pass NULL to get the required size of the array.
  405. AkUInt32 & io_uNumAngles, ///< Returned number of angles in io_pfSpeakerAngles, which is the minimum between the value that you pass in, and the number of angles corresponding to AK::GetNumberOfAnglesForConfig( AK_SPEAKER_SETUP_DEFAULT_PLANE ), or just the latter if io_pfSpeakerAngles is NULL.
  406. AkReal32 & out_fHeightAngle, ///< Elevation of the height layer, in degrees relative to the plane [-90,90].
  407. AkOutputDeviceID in_idOutput = 0 ///< Output ID to set the bus on. As returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
  408. );
  409. /// Sets speaker angles of the specified device. Speaker angles are used for 3D positioning of sounds over standard configurations.
  410. /// Note that the current version of Wwise only supports positioning on the plane.
  411. /// The speaker angles are expressed as an array of loudspeaker pairs, in degrees, relative to azimuth ]0,180], for a 7.1 speaker configuration.
  412. /// Supported loudspeaker setups are always symmetric; the center speaker is always in the middle and thus not specified by angles.
  413. /// Angles must be set in ascending order.
  414. /// Note:
  415. /// - This function requires the minimum speaker angle between any pair of speakers to be at least 5 degrees.
  416. /// - When setting angles for a 5.1 speaker layout, we recommend that you select an angle for the SL and SR channels, then subtract 15 degrees for in_pfSpeakerAngles[1] and add 15 degrees for in_pfSpeakerAngles[2] to set the arc appropriately.
  417. ///
  418. /// Typical usage:
  419. /// - Initialize the sound engine and/or add secondary output(s).
  420. /// - Get number of speaker angles and their value into an array using GetSpeakerAngles().
  421. /// - Modify the angles and call SetSpeakerAngles().
  422. /// This function posts a message to the audio thread through the command queue, so it is thread safe. However the result may not be immediately read with GetSpeakerAngles().
  423. /// \warning This function only applies to configurations (or subset of these configurations) that are standard and whose speakers are on the plane (2D).
  424. /// \return
  425. /// - \c AK_Success if successful.
  426. /// - \c AK_InvalidFloatValue if the value specified was NaN or Inf
  427. /// - \c AK_InsufficientMemory if there wasn't enough memory in the message queue
  428. /// - \c AK_InvalidParameter one of the parameter is invalid, check the debug log.
  429. /// \sa GetSpeakerAngles()
  430. AK_EXTERNAPIFUNC( AKRESULT, SetSpeakerAngles )(
  431. const AkReal32 * in_pfSpeakerAngles, ///< Array of loudspeaker pair angles, in degrees relative to azimuth [0,180].
  432. AkUInt32 in_uNumAngles, ///< Number of elements in in_pfSpeakerAngles. It must correspond to AK::GetNumberOfAnglesForConfig( AK_SPEAKER_SETUP_DEFAULT_PLANE ) (the value returned by GetSpeakerAngles()).
  433. AkReal32 in_fHeightAngle, ///< Elevation of the height layer, in degrees relative to the plane [-90,90].
  434. AkOutputDeviceID in_idOutput = 0 ///< Output ID to set the bus on. As returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
  435. );
  436. /// Allows the game to set the volume threshold to be used by the sound engine to determine if a voice must go virtual.
  437. /// This may be changed anytime once the sound engine was initialized.
  438. /// If this function is not called, the used value will be the value specified in the platform specific project settings.
  439. /// \return
  440. /// - \c AK_Success if successful
  441. /// - \c AK_InvalidParameter if the threshold was not between 0 and -96.3 dB.
  442. /// - \c AK_InvalidFloatValue if the value specified was NaN or Inf
  443. AK_EXTERNAPIFUNC( AKRESULT, SetVolumeThreshold )(
  444. AkReal32 in_fVolumeThresholdDB ///< Volume Threshold, must be a value between 0 and -96.3 dB
  445. );
  446. /// Allows the game to set the maximum number of non virtual voices to be played simultaneously.
  447. /// This may be changed anytime once the sound engine was initialized.
  448. /// If this function is not called, the used value will be the value specified in the platform specific project settings.
  449. /// \return
  450. /// - \c AK_InvalidParameter if the threshold was not between 1 and MaxUInt16.
  451. /// - \c AK_Success if successful
  452. AK_EXTERNAPIFUNC( AKRESULT, SetMaxNumVoicesLimit )(
  453. AkUInt16 in_maxNumberVoices ///< Maximum number of non-virtual voices.
  454. );
  455. /// Allows the game to set new values for the maximum active workers for the job manager
  456. /// This may be changed anytime once the sound engine was initialized.
  457. /// This function may only be used if a worker function has been set via \ref AkJobMgrSettings.
  458. /// \return
  459. /// - \c AK_InvalidParameter in_jobType is not a valid jobtype, or in_uNewMaxActiveWorkers is not greater than 0
  460. /// - \c AK_NotInitialized JobMgr system was not already initialized with a function to request for workers
  461. /// - \c AK_Success if successful
  462. AK_EXTERNAPIFUNC( AKRESULT, SetJobMgrMaxActiveWorkers )(
  463. AkJobType in_jobType, ///< JobType to set new uMaxActiveWorkers for
  464. AkUInt32 in_uNewMaxActiveWorkers ///< New maximum number of active workers will request
  465. );
  466. //@}
  467. ////////////////////////////////////////////////////////////////////////
  468. /// @name Rendering Audio
  469. //@{
  470. /// Processes all commands in the sound engine's command queue.
  471. /// This method has to be called periodically (usually once per game frame).
  472. /// \sa
  473. /// - \ref concept_events
  474. /// - \ref soundengine_events
  475. /// - <tt>AK::SoundEngine::PostEvent()</tt>
  476. /// \return Always returns AK_Success
  477. AK_EXTERNAPIFUNC( AKRESULT, RenderAudio )(
  478. bool in_bAllowSyncRender = true ///< When AkInitSettings::bUseLEngineThread is false, RenderAudio may generate an audio buffer -- unless in_bAllowSyncRender is set to false. Use in_bAllowSyncRender=false when calling RenderAudio from a Sound Engine callback.
  479. );
  480. //@}
  481. ////////////////////////////////////////////////////////////////////////
  482. /// @name Component Registration
  483. //@{
  484. /// Query interface to global plug-in context used for plug-in registration/initialization.
  485. /// \return Global plug-in context.
  486. AK_EXTERNAPIFUNC(AK::IAkGlobalPluginContext *, GetGlobalPluginContext)();
  487. /// Registers a plug-in with the sound engine and sets the callback functions to create the
  488. /// plug-in and its parameter node.
  489. /// \aknote
  490. /// This function is deprecated. Registration is now automatic if you link plug-ins statically. If plug-ins are dynamic libraries (such as DLLs or SOs), use \c RegisterPluginDLL.
  491. /// \endaknote
  492. /// \sa
  493. /// - \ref register_effects
  494. /// - \ref plugin_xml
  495. /// \return
  496. /// - \c AK_Success if successful
  497. /// - \c AK_InvalidParameter if invalid parameters were provided
  498. /// - \c AK_InsufficientMemory if there isn't enough memory to register the plug-in
  499. /// \remarks
  500. /// Codecs and plug-ins must be registered before loading banks that use them.\n
  501. /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  502. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  503. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  504. /// posting the event will fail.
  505. AK_EXTERNAPIFUNC( AKRESULT, RegisterPlugin )(
  506. AkPluginType in_eType, ///< Plug-in type (for example, source or effect)
  507. AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in the plug-in description XML file)
  508. AkUInt32 in_ulPluginID, ///< Plug-in identifier (as declared in the plug-in description XML file)
  509. AkCreatePluginCallback in_pCreateFunc, ///< Pointer to the plug-in's creation function
  510. AkCreateParamCallback in_pCreateParamFunc, ///< Pointer to the plug-in's parameter node creation function
  511. AkGetDeviceListCallback in_pGetDeviceList = NULL ///< Optional pointer to the plug-in's device enumeration function. Specify for a sink plug-in to support \ref AK::SoundEngine::GetDeviceList.
  512. );
  513. /// Loads a plug-in dynamic library and registers it with the sound engine.
  514. /// With dynamic linking, all plugins are automatically registered.
  515. /// The plug-in DLL must be in the OS-specific library path or in the same location as the executable. If not, set AkInitSettings.szPluginDLLPath.
  516. /// \return
  517. /// - \c AK_Success if successful.
  518. /// - \c AK_FileNotFound if the DLL is not found in the OS path or if it has extraneous dependencies not found.
  519. /// - \c AK_InsufficientMemory if the system ran out of resources while loading the dynamic library
  520. /// - \c AK_NotCompatible if the file was found but is not binary-compatible with the system's expected executable format
  521. /// - \c AK_InvalidFile if the symbol g_pAKPluginList is not exported by the dynamic library
  522. /// - \c AK_Fail if an unexpected system error was encountered
  523. AK_EXTERNAPIFUNC( AKRESULT, RegisterPluginDLL ) (
  524. const AkOSChar* in_DllName, ///< Name of the DLL to load, without "lib" prefix or extension.
  525. const AkOSChar* in_DllPath = NULL ///< Optional path to the DLL. Will override szPLuginDLLPath that was set in AkInitSettings.
  526. );
  527. /// Query whether plug-in is registered with the sound engine.
  528. /// \return true when plug-in is registered, false otherwise.
  529. AK_EXTERNAPIFUNC( bool, IsPluginRegistered )(
  530. AkPluginType in_eType, ///< Plug-in type (for example, source or effect)
  531. AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in the plug-in description XML file)
  532. AkUInt32 in_ulPluginID ///< Plug-in identifier (as declared in the plug-in description XML file)
  533. );
  534. /// Registers a codec type with the sound engine and set the callback functions to create the
  535. /// codec's file source and bank source nodes.
  536. /// \aknote
  537. /// This function is deprecated. Registration is now automatic if you link plugins statically. If plugins are dynamic libraries (such as DLLs or SOs), use RegisterPluginDLL.
  538. /// \endaknote
  539. /// \sa
  540. /// - \ref register_effects
  541. /// \return
  542. /// - \c AK_Success if successful
  543. /// - \c AK_InvalidParameter if invalid parameters were provided
  544. /// - \c AK_InsufficientMemory if there isn't enough memory to register the plug-in
  545. /// \remarks
  546. /// Codecs and plug-ins must be registered before loading banks that use them.\n
  547. /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  548. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  549. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  550. /// posting the Event will fail.
  551. AK_EXTERNAPIFUNC( AKRESULT, RegisterCodec )(
  552. AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in the plug-in description XML file)
  553. AkUInt32 in_ulCodecID, ///< Codec identifier (as declared in the plug-in description XML file)
  554. AkCreateFileSourceCallback in_pFileCreateFunc, ///< Pointer to the codec's file source node creation function
  555. AkCreateBankSourceCallback in_pBankCreateFunc ///< Pointer to the codec's bank source node creation function
  556. );
  557. /// Registers a global callback function. This function will be called from the audio rendering thread, at the
  558. /// location specified by in_eLocation. This function will also be called from the thread calling
  559. /// AK::SoundEngine::Term with in_eLocation set to AkGlobalCallbackLocation_Term.
  560. /// For example, in order to be called at every audio rendering pass, and once during teardown for releasing resources, you would call
  561. /// RegisterGlobalCallback(myCallback, AkGlobalCallbackLocation_BeginRender | AkGlobalCallbackLocation_Term, myCookie, AkPluginTypeNone, 0, 0);
  562. /// \remarks
  563. /// A Plugin Type, Company ID and Plugin ID can be provided to this function to enable timing in the performance monitor.
  564. /// If the callback is being timed, it will contribute to the Total Plug-in CPU measurement, and also appear in the Plug-ins tab of the Advanced Profiler by plug-in type and ID.
  565. /// It is illegal to call this function while already inside of a global callback.
  566. /// This function might stall for several milliseconds before returning.
  567. /// \return
  568. /// - \c AK_Success if successful
  569. /// - \c AK_InvalidParameter if parameters are out of range (check debug console or Wwise Profiler)
  570. /// \sa
  571. /// - <tt>AK::SoundEngine::UnregisterGlobalCallback()</tt>
  572. /// - AkGlobalCallbackFunc
  573. /// - AkGlobalCallbackLocation
  574. AK_EXTERNAPIFUNC(AKRESULT, RegisterGlobalCallback)(
  575. AkGlobalCallbackFunc in_pCallback, ///< Function to register as a global callback.
  576. AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender, ///< Callback location defined in AkGlobalCallbackLocation. Bitwise OR multiple locations if needed.
  577. void * in_pCookie = NULL, ///< User cookie.
  578. AkPluginType in_eType = AkPluginTypeNone, ///< Plug-in type (for example, source or effect). AkPluginTypeNone for no timing.
  579. AkUInt32 in_ulCompanyID = 0, ///< Company identifier (as declared in the plug-in description XML file). 0 for no timing.
  580. AkUInt32 in_ulPluginID = 0 ///< Plug-in identifier (as declared in the plug-in description XML file). 0 for no timing.
  581. );
  582. /// Unregisters a global callback function, previously registered using RegisterGlobalCallback.
  583. /// \remarks
  584. /// It is legal to call this function while already inside of a global callback, If it is unregistering itself and not
  585. /// another callback.
  586. /// This function might stall for several milliseconds before returning.
  587. /// \return
  588. /// - \c AK_Success if successful
  589. /// - \c AK_InvalidParameter if parameters are out of range (check debug console or Wwise Profiler)
  590. /// \sa
  591. /// - <tt>AK::SoundEngine::RegisterGlobalCallback()</tt>
  592. /// - AkGlobalCallbackFunc
  593. /// - AkGlobalCallbackLocation
  594. AK_EXTERNAPIFUNC(AKRESULT, UnregisterGlobalCallback)(
  595. AkGlobalCallbackFunc in_pCallback, ///< Function to unregister as a global callback.
  596. AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender ///< Must match in_eLocation as passed to RegisterGlobalCallback for this callback.
  597. );
  598. /// Registers a resource monitor callback function that gets all of the resource usage data contained in the
  599. /// AkResourceMonitorDataSummary structure. This includes general information about the system, such as CPU usage,
  600. /// active Voices, and Events. This function will be called from the audio rendering thread at the end of each frame.
  601. /// \remarks
  602. /// If the callback is being timed, it will contribute to the Total Plug-in CPU measurement, and also appear in the Plug-ins tab of the Advanced Profiler by plug-in type and ID.
  603. /// It is illegal to call this function while already inside of a resource callback.
  604. /// This function might stall for several milliseconds before returning.
  605. /// This function will return AK_Fail in Release
  606. /// \sa
  607. /// - <tt>AK::SoundEngine::UnregisterResourceMonitorCallback()</tt>
  608. /// - AkResourceMonitorCallbackFunc
  609. AK_EXTERNAPIFUNC(AKRESULT, RegisterResourceMonitorCallback)(
  610. AkResourceMonitorCallbackFunc in_pCallback ///< Function to register as a resource monitor callback.
  611. );
  612. /// Unregisters a resource monitor callback function, previously registered using RegisterResourceMonitorCallback.
  613. /// \remarks
  614. /// It is legal to call this function while already inside of a resource monitor callback, If it is unregistering itself and not
  615. /// another callback.
  616. /// This function might stall for several milliseconds before returning.
  617. /// \sa
  618. /// - <tt>AK::SoundEngine::RegisterResourceMonitorCallback()</tt>
  619. /// - AkResourceMonitorCallbackFunc
  620. AK_EXTERNAPIFUNC(AKRESULT, UnregisterResourceMonitorCallback)(
  621. AkResourceMonitorCallbackFunc in_pCallback ///< Function to unregister as a resource monitor callback.
  622. );
  623. /// Registers a callback for the Audio Device status changes.
  624. /// The callback will be called from the audio thread
  625. /// Can be called prior to AK::SoundEngine::Init
  626. /// \sa AK::SoundEngine::AddOutput
  627. AK_EXTERNAPIFUNC(AKRESULT, RegisterAudioDeviceStatusCallback)(
  628. AK::AkDeviceStatusCallbackFunc in_pCallback ///< Function to register as a status callback.
  629. );
  630. /// Unregisters the callback for the Audio Device status changes, registered by RegisterAudioDeviceStatusCallback
  631. AK_EXTERNAPIFUNC(AKRESULT, UnregisterAudioDeviceStatusCallback)();
  632. //@}
  633. #ifdef AK_SUPPORT_WCHAR
  634. ////////////////////////////////////////////////////////////////////////
  635. /// @name Getting ID from strings
  636. //@{
  637. /// Universal converter from Unicode string to ID for the sound engine.
  638. /// This function will hash the name based on a algorithm ( provided at : /AK/Tools/Common/AkFNVHash.h )
  639. /// Note:
  640. /// This function does return a AkUInt32, which is totally compatible with:
  641. /// AkUniqueID, AkStateGroupID, AkStateID, AkSwitchGroupID, AkSwitchStateID, AkRtpcID, and so on...
  642. /// \sa
  643. /// - <tt>AK::SoundEngine::PostEvent</tt>
  644. /// - <tt>AK::SoundEngine::SetRTPCValue</tt>
  645. /// - <tt>AK::SoundEngine::SetSwitch</tt>
  646. /// - <tt>AK::SoundEngine::SetState</tt>
  647. /// - <tt>AK::SoundEngine::PostTrigger</tt>
  648. /// - <tt>AK::SoundEngine::SetGameObjectAuxSendValues</tt>
  649. /// - <tt>AK::SoundEngine::LoadBank</tt>
  650. /// - <tt>AK::SoundEngine::UnloadBank</tt>
  651. /// - <tt>AK::SoundEngine::PrepareEvent</tt>
  652. /// - <tt>AK::SoundEngine::PrepareGameSyncs</tt>
  653. AK_EXTERNAPIFUNC( AkUInt32, GetIDFromString )( const wchar_t* in_pszString );
  654. #endif //AK_SUPPORT_WCHAR
  655. /// Universal converter from string to ID for the sound engine.
  656. /// This function will hash the name based on a algorithm ( provided at : /AK/Tools/Common/AkFNVHash.h )
  657. /// Note:
  658. /// This function does return a AkUInt32, which is totally compatible with:
  659. /// AkUniqueID, AkStateGroupID, AkStateID, AkSwitchGroupID, AkSwitchStateID, AkRtpcID, and so on...
  660. /// \sa
  661. /// - <tt>AK::SoundEngine::PostEvent</tt>
  662. /// - <tt>AK::SoundEngine::SetRTPCValue</tt>
  663. /// - <tt>AK::SoundEngine::SetSwitch</tt>
  664. /// - <tt>AK::SoundEngine::SetState</tt>
  665. /// - <tt>AK::SoundEngine::PostTrigger</tt>
  666. /// - <tt>AK::SoundEngine::SetGameObjectAuxSendValues</tt>
  667. /// - <tt>AK::SoundEngine::LoadBank</tt>
  668. /// - <tt>AK::SoundEngine::UnloadBank</tt>
  669. /// - <tt>AK::SoundEngine::PrepareEvent</tt>
  670. /// - <tt>AK::SoundEngine::PrepareGameSyncs</tt>
  671. AK_EXTERNAPIFUNC( AkUInt32, GetIDFromString )( const char* in_pszString );
  672. //@}
  673. ////////////////////////////////////////////////////////////////////////
  674. /// @name Event Management
  675. //@{
  676. /// Asynchronously posts an Event to the sound engine (by event ID).
  677. /// The callback function can be used to be noticed when markers are reached or when the event is finished.
  678. /// An array of wave file sources can be provided to resolve External Sources triggered by the event.
  679. /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed and an error will be displayed in the debug console and the Wwise Profiler.
  680. /// \remarks
  681. /// If used, the array of external sources should contain the information for each external source triggered by the
  682. /// event. When triggering an event with multiple external sources, you need to differentiate each source
  683. /// by using the cookie property in the External Source in the Wwise project and in AkExternalSourceInfo.
  684. /// \aknote If an event triggers the playback of more than one external source, they must be named uniquely in the project
  685. /// (therefore have a unique cookie) in order to tell them apart when filling the AkExternalSourceInfo structures.
  686. /// \endaknote
  687. /// \sa
  688. /// - \ref concept_events
  689. /// - \ref integrating_external_sources
  690. /// - <tt>AK::SoundEngine::RenderAudio()</tt>
  691. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  692. /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
  693. AK_EXTERNAPIFUNC( AkPlayingID, PostEvent )(
  694. AkUniqueID in_eventID, ///< Unique ID of the event
  695. AkGameObjectID in_gameObjectID, ///< Associated game object ID
  696. AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType
  697. AkCallbackFunc in_pfnCallback = NULL, ///< Callback function
  698. void * in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information
  699. AkUInt32 in_cExternals = 0, ///< Optional count of external source structures
  700. AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
  701. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID///< Optional (advanced users only) Specify the playing ID to target with the event. Will Cause active actions in this event to target an existing Playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any for normal playback.
  702. );
  703. #ifdef AK_SUPPORT_WCHAR
  704. /// Posts an Event to the sound engine (by Event name), using callbacks.
  705. /// The callback function can be used to be noticed when markers are reached or when the event is finished.
  706. /// An array of wave file sources can be provided to resolve External Sources triggered by the event.
  707. /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed and an error will be displayed in the debug console and the Wwise Profiler.
  708. /// \remarks
  709. /// If used, the array of external sources should contain the information for each external source triggered by the
  710. /// event. When triggering an event with multiple external sources, you need to differentiate each source
  711. /// by using the cookie property in the External Source in the Wwise project and in AkExternalSourceInfo.
  712. /// \aknote If an event triggers the playback of more than one external source, they must be named uniquely in the project
  713. /// (therefore have a unique cookie) in order to tell them appart when filling the AkExternalSourceInfo structures.
  714. /// \endaknote
  715. /// \sa
  716. /// - \ref concept_events
  717. /// - \ref integrating_external_sources
  718. /// - <tt>AK::SoundEngine::RenderAudio()</tt>
  719. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  720. /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
  721. AK_EXTERNAPIFUNC( AkPlayingID, PostEvent )(
  722. const wchar_t* in_pszEventName, ///< Name of the event
  723. AkGameObjectID in_gameObjectID, ///< Associated game object ID
  724. AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType
  725. AkCallbackFunc in_pfnCallback = NULL, ///< Callback function
  726. void * in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information.
  727. AkUInt32 in_cExternals = 0, ///< Optional count of external source structures
  728. AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
  729. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID///< Optional (advanced users only) Specify the playing ID to target with the event. Will Cause active actions in this event to target an existing Playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any for normal playback.
  730. );
  731. #endif //AK_SUPPORT_WCHAR
  732. /// Posts an Event to the sound engine (by Event name), using callbacks.
  733. /// The callback function can be used to be noticed when markers are reached or when the event is finished.
  734. /// An array of Wave file sources can be provided to resolve External Sources triggered by the event. P
  735. /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed and an error will be displayed in the debug console and the Wwise Profiler.
  736. /// \remarks
  737. /// If used, the array of external sources should contain the information for each external source triggered by the
  738. /// event. When triggering an Event with multiple external sources, you need to differentiate each source
  739. /// by using the cookie property in the External Source in the Wwise project and in AkExternalSourceInfo.
  740. /// \aknote If an event triggers the playback of more than one external source, they must be named uniquely in the project
  741. /// (therefore have a unique cookie) in order to tell them apart when filling the AkExternalSourceInfo structures.
  742. /// \endaknote
  743. /// \sa
  744. /// - \ref concept_events
  745. /// - \ref integrating_external_sources
  746. /// - <tt>AK::SoundEngine::RenderAudio()</tt>
  747. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  748. /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
  749. AK_EXTERNAPIFUNC( AkPlayingID, PostEvent )(
  750. const char* in_pszEventName, ///< Name of the event
  751. AkGameObjectID in_gameObjectID, ///< Associated game object ID
  752. AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType
  753. AkCallbackFunc in_pfnCallback = NULL, ///< Callback function
  754. void * in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information.
  755. AkUInt32 in_cExternals = 0, ///< Optional count of external source structures
  756. AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
  757. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID///< Optional (advanced users only) Specify the playing ID to target with the event. Will Cause active actions in this event to target an existing Playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any for normal playback.
  758. );
  759. // If you modify AkActionOnEventType, don't forget to modify the WAAPI validation schema accordingly.
  760. /// AkActionOnEventType
  761. /// \sa
  762. /// - <tt>AK::SoundEngine::ExecuteActionOnEvent()</tt>
  763. enum AkActionOnEventType
  764. {
  765. AkActionOnEventType_Stop = 0, ///< Stop
  766. AkActionOnEventType_Pause = 1, ///< Pause
  767. AkActionOnEventType_Resume = 2, ///< Resume
  768. AkActionOnEventType_Break = 3, ///< Break
  769. AkActionOnEventType_ReleaseEnvelope = 4 ///< Release envelope
  770. };
  771. /// Executes an action on all nodes that are referenced in the specified event in an action of type play.
  772. /// \return
  773. /// - \c AK_Success if the action was successfully queued.
  774. /// - \c AK_IDNotFound if the Event was not found (not loaded or there is a typo in the ID)
  775. /// \sa
  776. /// - <tt>AK::SoundEngine::AkActionOnEventType</tt>
  777. AK_EXTERNAPIFUNC( AKRESULT, ExecuteActionOnEvent )(
  778. AkUniqueID in_eventID, ///< Unique ID of the event
  779. AkActionOnEventType in_ActionType, ///< Action to execute on all the elements that were played using the specified event.
  780. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT, ///< Associated game object ID
  781. AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
  782. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the transition
  783. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Associated PlayingID
  784. );
  785. #ifdef AK_SUPPORT_WCHAR
  786. /// Executes an action on all nodes that are referenced in the specified event in an action of type play.
  787. /// \return
  788. /// - \c AK_Success if the action was successfully queued.
  789. /// - \c AK_IDNotFound if the Event was not found (not loaded or there is a typo in the ID)
  790. /// \sa
  791. /// - <tt>AK::SoundEngine::AkActionOnEventType</tt>
  792. AK_EXTERNAPIFUNC( AKRESULT, ExecuteActionOnEvent )(
  793. const wchar_t* in_pszEventName, ///< Name of the event
  794. AkActionOnEventType in_ActionType, ///< Action to execute on all the elements that were played using the specified event.
  795. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT, ///< Associated game object ID
  796. AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
  797. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the transition
  798. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Associated PlayingID
  799. );
  800. #endif //AK_SUPPORT_WCHAR
  801. /// Executes an Action on all nodes that are referenced in the specified Event in an Action of type Play.
  802. /// \return
  803. /// - \c AK_Success if the action was successfully queued.
  804. /// - \c AK_IDNotFound if the Event was not found (not loaded or there is a typo in the ID)
  805. /// \sa
  806. /// - <tt>AK::SoundEngine::AkActionOnEventType</tt>
  807. AK_EXTERNAPIFUNC( AKRESULT, ExecuteActionOnEvent )(
  808. const char* in_pszEventName, ///< Name of the event
  809. AkActionOnEventType in_ActionType, ///< Action to execute on all the elements that were played using the specified event.
  810. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT, ///< Associated game object ID
  811. AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
  812. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the transition
  813. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Associated PlayingID
  814. );
  815. /// Executes a number of MIDI Events on all nodes that are referenced in the specified Event in an Action of type Play.
  816. /// The time at which a MIDI Event is posted is determined by in_bAbsoluteOffsets. If false, each MIDI event will be
  817. /// posted in AkMIDIPost::uOffset samples from the start of the current frame. If true, each MIDI event will be posted
  818. /// at the absolute time AkMIDIPost::uOffset samples.
  819. /// To obtain the current absolute time, see AK::SoundEngine::GetSampleTick.
  820. /// The duration of a sample can be determined from the sound engine's audio settings, via a call to AK::SoundEngine::GetAudioSettings.
  821. /// If a playing ID is specified then that playing ID must be active. Otherwise a new playing ID will be assigned.
  822. /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed and an error will be displayed in the debug console and the Wwise Profiler.
  823. /// \sa
  824. /// - <tt>AK::SoundEngine::GetAudioSettings</tt>
  825. /// - <tt>AK::SoundEngine::GetSampleTick</tt>
  826. /// - <tt>AK::SoundEngine::StopMIDIOnEvent</tt>
  827. /// - \ref soundengine_midi_event_playing_id
  828. AK_EXTERNAPIFUNC( AkPlayingID, PostMIDIOnEvent )(
  829. AkUniqueID in_eventID, ///< Unique ID of the Event
  830. AkGameObjectID in_gameObjectID, ///< Associated game object ID
  831. AkMIDIPost* in_pPosts, ///< MIDI Events to post
  832. AkUInt16 in_uNumPosts, ///< Number of MIDI Events to post
  833. bool in_bAbsoluteOffsets = false, ///< Set to true when AkMIDIPost::uOffset are absolute, false when relative to current frame
  834. AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType
  835. AkCallbackFunc in_pfnCallback = NULL, ///< Callback function
  836. void * in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information
  837. AkPlayingID in_playingID = AK_INVALID_PLAYING_ID ///< Target playing ID
  838. );
  839. /// Stops MIDI notes on all nodes that are referenced in the specified event in an action of type play,
  840. /// with the specified Game Object. Invalid parameters are interpreted as wildcards. For example, calling
  841. /// this function with in_eventID set to AK_INVALID_UNIQUE_ID will stop all MIDI notes for Game Object
  842. /// in_gameObjectID.
  843. /// \return
  844. /// - \c AK_Success if the stop command was queued
  845. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  846. /// \sa
  847. /// - <tt>AK::SoundEngine::PostMIDIOnEvent</tt>
  848. /// - \ref soundengine_midi_event_playing_id
  849. AK_EXTERNAPIFUNC( AKRESULT, StopMIDIOnEvent )(
  850. AkUniqueID in_eventID = AK_INVALID_UNIQUE_ID, ///< Unique ID of the Event
  851. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT, ///< Associated game object ID
  852. AkPlayingID in_playingID = AK_INVALID_PLAYING_ID ///< Target playing ID
  853. );
  854. /// Starts streaming the first part of all streamed files referenced by an Event into a cache buffer. Caching streams are serviced when no other streams require the
  855. /// available bandwidth. The files will remain cached until UnpinEventInStreamCache is called, or a higher priority pinned file needs the space and the limit set by
  856. /// uMaxCachePinnedBytes is exceeded.
  857. /// \remarks The amount of data from the start of the file that will be pinned to cache is determined by the prefetch size. The prefetch size is set via the authoring tool and stored in the sound banks.
  858. /// \remarks It is possible to override the prefetch size stored in the sound bank via the low level IO. For more information see <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt> and AkFileSystemFlags.
  859. /// \remarks If this function is called additional times with the same event, then the priority of the caching streams are updated. Note however that priority is passed down to the stream manager
  860. /// on a file-by-file basis, and if another event is pinned to cache that references the same file but with a different priority, then the first priority will be updated with the most recent value.
  861. /// \remarks If the event references files that are chosen based on a State Group (via a switch container), all files in all states will be cached. Those in the current active state
  862. /// will get cached with active priority, while all other files will get cached with inactive priority.
  863. /// \remarks in_uInactivePriority is only relevant for events that reference switch containers that are assigned to State Groups. This parameter is ignored for all other events, including events that only reference
  864. /// switch containers that are assigned to Switch Groups. Files that are chosen based on a Switch Group have a different switch value per game object, and are all effectively considered active by the pin-to-cache system.
  865. /// \return
  866. /// - \c AK_Success if command was queued
  867. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  868. /// \sa
  869. /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
  870. /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
  871. /// - <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen</tt>
  872. /// - AkFileSystemFlags
  873. AK_EXTERNAPIFUNC( AKRESULT, PinEventInStreamCache )(
  874. AkUniqueID in_eventID, ///< Unique ID of the event
  875. AkPriority in_uActivePriority, ///< Priority of active stream caching I/O
  876. AkPriority in_uInactivePriority ///< Priority of inactive stream caching I/O
  877. );
  878. #ifdef AK_SUPPORT_WCHAR
  879. /// Starts streaming the first part of all streamed files referenced by an event into a cache buffer. Caching streams are serviced when no other streams require the
  880. /// available bandwidth. The files will remain cached until UnpinEventInStreamCache is called, or a higher priority pinned file needs the space and the limit set by
  881. /// uMaxCachePinnedBytes is exceeded.
  882. /// \remarks The amount of data from the start of the file that will be pinned to cache is determined by the prefetch size. The prefetch size is set via the authoring tool and stored in the sound banks.
  883. /// \remarks It is possible to override the prefetch size stored in the sound bank via the low level IO. For more information see <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt> and AkFileSystemFlags.
  884. /// \remarks If this function is called additional times with the same event, then the priority of the caching streams are updated. Note however that priority is passed down to the stream manager
  885. /// on a file-by-file basis, and if another event is pinned to cache that references the same file but with a different priority, then the first priority will be updated with the most recent value.
  886. /// \remarks If the event references files that are chosen based on a State Group (via a Switch Container), all files in all states will be cached. Those in the current active state
  887. /// will get cached with active priority, while all other files will get cached with inactive priority.
  888. /// \remarks in_uInactivePriority is only relevant for events that reference switch containers that are assigned to State Groups. This parameter is ignored for all other events, including events that only reference
  889. /// switch containers that are assigned to Switch Groups. Files that are chosen based on a Switch Group have a different switch value per game object, and are all effectively considered active by the pin-to-cache system.
  890. /// \return
  891. /// - \c AK_Success if command was queued
  892. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  893. /// \sa
  894. /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
  895. /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
  896. /// - <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen</tt>
  897. /// - AkFileSystemFlags
  898. AK_EXTERNAPIFUNC( AKRESULT, PinEventInStreamCache )(
  899. const wchar_t* in_pszEventName, ///< Name of the event
  900. AkPriority in_uActivePriority, ///< Priority of active stream caching I/O
  901. AkPriority in_uInactivePriority ///< Priority of inactive stream caching I/O
  902. );
  903. #endif //AK_SUPPORT_WCHAR
  904. /// Starts streaming the first part of all streamed files referenced by an event into a cache buffer. Caching streams are serviced when no other streams require the
  905. /// available bandwidth. The files will remain cached until UnpinEventInStreamCache is called, or a higher priority pinned file needs the space and the limit set by
  906. /// uMaxCachePinnedBytes is exceeded.
  907. /// \remarks The amount of data from the start of the file that will be pinned to cache is determined by the prefetch size. The prefetch size is set via the authoring tool and stored in the sound banks.
  908. /// \remarks It is possible to override the prefetch size stored in the sound bank via the low level IO. For more information see <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt> and AkFileSystemFlags.
  909. /// \remarks If this function is called additional times with the same event, then the priority of the caching streams are updated. Note however that priority is passed down to the stream manager
  910. /// on a file-by-file basis, and if another event is pinned to cache that references the same file but with a different priority, then the first priority will be updated with the most recent value.
  911. /// \remarks If the event references files that are chosen based on a State Group (via a switch container), all files in all states will be cached. Those in the current active state
  912. /// will get cached with active priority, while all other files will get cached with inactive priority.
  913. /// \remarks in_uInactivePriority is only relevant for events that reference switch containers that are assigned to State Groups. This parameter is ignored for all other events, including events that only reference
  914. /// switch containers that are assigned to Switch Groups. Files that are chosen based on a Switch Group have a different switch value per game object, and are all effectively considered active by the pin-to-cache system.
  915. /// \return
  916. /// - \c AK_Success if command was queued
  917. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  918. /// \sa
  919. /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
  920. /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
  921. /// - <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen</tt>
  922. /// - AkFileSystemFlags
  923. AK_EXTERNAPIFUNC( AKRESULT, PinEventInStreamCache )(
  924. const char* in_pszEventName, ///< Name of the event
  925. AkPriority in_uActivePriority, ///< Priority of active stream caching I/O
  926. AkPriority in_uInactivePriority ///< Priority of inactive stream caching I/O
  927. );
  928. /// Releases the set of files that were previously requested to be pinned into cache via <tt>AK::SoundEngine::PinEventInStreamCache()</tt>. The file may still remain in stream cache
  929. /// after <tt>AK::SoundEngine::UnpinEventInStreamCache()</tt> is called, until the memory is reused by the streaming memory manager in accordance with to its cache management algorithm.
  930. /// \return
  931. /// - \c AK_Success if command was queued
  932. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  933. /// \sa
  934. /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
  935. /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
  936. AK_EXTERNAPIFUNC( AKRESULT, UnpinEventInStreamCache )(
  937. AkUniqueID in_eventID ///< Unique ID of the event
  938. );
  939. #ifdef AK_SUPPORT_WCHAR
  940. /// Releases the set of files that were previously requested to be pinned into cache via <tt>AK::SoundEngine::PinEventInStreamCache()</tt>. The file may still remain in stream cache
  941. /// after <tt>AK::SoundEngine::UnpinEventInStreamCache()</tt> is called, until the memory is reused by the streaming memory manager in accordance with to its cache management algorithm.
  942. /// \return
  943. /// - \c AK_Success if command was queued
  944. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  945. /// \sa
  946. /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
  947. /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
  948. AK_EXTERNAPIFUNC( AKRESULT, UnpinEventInStreamCache )(
  949. const wchar_t* in_pszEventName ///< Name of the event
  950. );
  951. #endif //AK_SUPPORT_WCHAR
  952. /// Releases the set of files that were previously requested to be pinned into cache via <tt>AK::SoundEngine::PinEventInStreamCache()</tt>. The file may still remain in stream cache
  953. /// after <tt>AK::SoundEngine::UnpinEventInStreamCache()</tt> is called, until the memory is reused by the streaming memory manager in accordance with to its cache management algorithm.
  954. /// \return
  955. /// - \c AK_Success if command was queued
  956. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  957. /// \sa
  958. /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
  959. /// - <tt>AK::SoundEngine::GetBufferStatusForPinnedEvent</tt>
  960. AK_EXTERNAPIFUNC( AKRESULT, UnpinEventInStreamCache )(
  961. const char* in_pszEventName ///< Name of the event
  962. );
  963. /// Returns information about an Event that was requested to be pinned into cache via <tt>AK::SoundEngine::PinEventInStreamCache()</tt>.
  964. /// Retrieves the smallest buffer fill-percentage for each file referenced by the event, and whether
  965. /// the cache-pinned memory limit is preventing any of the files from filling up their buffer.
  966. /// \remarks To set the limit for the maximum number of bytes that can be pinned to cache, see \c AkDeviceSettings
  967. /// \return
  968. /// - \c AK_Success if command was queued
  969. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  970. /// \sa
  971. /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
  972. /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
  973. /// - AkDeviceSettings
  974. AK_EXTERNAPIFUNC( AKRESULT, GetBufferStatusForPinnedEvent )(
  975. AkUniqueID in_eventID, ///< Unique ID of the event
  976. AkReal32& out_fPercentBuffered, ///< Fill-percentage (out of 100) of requested buffer size for least buffered file in the event.
  977. bool& out_bCachePinnedMemoryFull ///< True if at least one file can not complete buffering because the cache-pinned memory limit would be exceeded.
  978. );
  979. /// Returns information about an Event that was requested to be pinned into cache via \c <tt>AK::SoundEngine::PinEventInStreamCache()</tt>.
  980. /// Retrieves the smallest buffer fill-percentage for each file referenced by the event, and whether
  981. /// the cache-pinned memory limit is preventing any of the files from filling up their buffer.
  982. /// \remarks To set the limit for the maximum number of bytes that can be pinned to cache, see AkDeviceSettings
  983. /// \return
  984. /// - \c AK_Success if command was queued
  985. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  986. /// \sa
  987. /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
  988. /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
  989. /// - AkDeviceSettings
  990. AK_EXTERNAPIFUNC( AKRESULT, GetBufferStatusForPinnedEvent )(
  991. const char* in_pszEventName, ///< Name of the event
  992. AkReal32& out_fPercentBuffered, ///< Fill-percentage (out of 100) of requested buffer size for least buffered file in the event.
  993. bool& out_bCachePinnedMemoryFull ///< True if at least one file can not complete buffering because the cache-pinned memory limit would be exceeded.
  994. );
  995. #ifdef AK_SUPPORT_WCHAR
  996. /// Returns information about an Event that was requested to be pinned into cache via \c <tt>AK::SoundEngine::PinEventInStreamCache()</tt>.
  997. /// Retrieves the smallest buffer fill-percentage for each file referenced by the event, and whether
  998. /// the cache-pinned memory limit is preventing any of the files from filling up their buffer.
  999. /// \remarks To set the limit for the maximum number of bytes that can be pinned to cache, see AkDeviceSettings
  1000. /// \return
  1001. /// - \c AK_Success if command was queued
  1002. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  1003. /// \sa
  1004. /// - <tt>AK::SoundEngine::PinEventInStreamCache</tt>
  1005. /// - <tt>AK::SoundEngine::UnpinEventInStreamCache</tt>
  1006. /// - AkDeviceSettings
  1007. AK_EXTERNAPIFUNC( AKRESULT, GetBufferStatusForPinnedEvent )(
  1008. const wchar_t* in_pszEventName, ///< Name of the event
  1009. AkReal32& out_fPercentBuffered, ///< Fill-percentage (out of 100) of requested buffer size for least buffered file in the event.
  1010. bool& out_bCachePinnedMemoryFull ///< True if at least one file can not complete buffering because the cache-pinned memory limit would be exceeded.
  1011. );
  1012. #endif
  1013. /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
  1014. ///
  1015. /// Notes:
  1016. /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
  1017. /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
  1018. /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
  1019. /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
  1020. /// the sound that is currently playing is the first sound of the sequence.
  1021. /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
  1022. /// - Sounds/segments are stopped if in_iPosition is greater than their duration.
  1023. /// - in_iPosition is clamped internally to the beginning of the sound/segment.
  1024. /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
  1025. /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
  1026. /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
  1027. /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
  1028. /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
  1029. /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
  1030. /// - This method posts a command in the sound engine queue, thus seeking will not occur before
  1031. /// the audio thread consumes it (after a call to RenderAudio()).
  1032. ///
  1033. /// Notes specific to Music Segments:
  1034. /// - With Music Segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
  1035. /// value to seek within the Pre-Entry.
  1036. /// - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification
  1037. /// in order to restart them if required.
  1038. /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
  1039. /// take the "look-ahead time" property of their streamed tracks into account for seeking.
  1040. /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
  1041. /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
  1042. /// the exact position of a segment. Also, the segment will be silent during that time
  1043. /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1044. /// also informs you about the remaining look-ahead time.
  1045. ///
  1046. /// Notes specific to Music Switch Containers:
  1047. /// - Seeking triggers a music transition towards the current (or target) segment.
  1048. /// This transition is subject to the container's transition rule that matches the current and defined in the container,
  1049. /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
  1050. /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
  1051. /// - If the specified time is greater than the destination segment's length, the modulo is taken.
  1052. ///
  1053. /// \return
  1054. /// - \c AK_Success if command was queued
  1055. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  1056. /// \sa
  1057. /// - <tt>AK::SoundEngine::RenderAudio()</tt>
  1058. /// - <tt>AK::SoundEngine::PostEvent()</tt>
  1059. /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
  1060. /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1061. AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
  1062. AkUniqueID in_eventID, ///< Unique ID of the event
  1063. AkGameObjectID in_gameObjectID, ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
  1064. AkTimeMs in_iPosition, ///< Desired position where playback should restart, in milliseconds
  1065. bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
  1066. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
  1067. );
  1068. #ifdef AK_SUPPORT_WCHAR
  1069. /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
  1070. ///
  1071. /// Notes:
  1072. /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
  1073. /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
  1074. /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
  1075. /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
  1076. /// the sound that is currently playing is the first sound of the sequence.
  1077. /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
  1078. /// - With Music Segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
  1079. /// value to seek within the Pre-Entry.
  1080. /// - Sounds/segments are stopped if in_iPosition is greater than their duration.
  1081. /// - in_iPosition is clamped internally to the beginning of the sound/segment.
  1082. /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
  1083. /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
  1084. /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
  1085. /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
  1086. /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
  1087. /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
  1088. /// - This method posts a command in the sound engine queue, thus seeking will not occur before
  1089. /// the audio thread consumes it (after a call to RenderAudio()).
  1090. ///
  1091. /// Notes specific to Music Segments:
  1092. /// - With Music Segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
  1093. /// value to seek within the Pre-Entry.
  1094. /// - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification
  1095. /// in order to restart them if required.
  1096. /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
  1097. /// take the "look-ahead time" property of their streamed tracks into account for seeking.
  1098. /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
  1099. /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
  1100. /// the exact position of a segment. Also, the segment will be silent during that time
  1101. /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1102. /// also informs you about the remaining look-ahead time.
  1103. ///
  1104. /// Notes specific to Music Switch Containers:
  1105. /// - Seeking triggers a music transition towards the current (or target) segment.
  1106. /// This transition is subject to the container's transition rule that matches the current and defined in the container,
  1107. /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
  1108. /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
  1109. /// - If the specified time is greater than the destination segment's length, the modulo is taken.
  1110. /// \return
  1111. /// - \c AK_Success if command was queued
  1112. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  1113. /// \sa
  1114. /// - <tt>AK::SoundEngine::RenderAudio()</tt>
  1115. /// - <tt>AK::SoundEngine::PostEvent()</tt>
  1116. /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
  1117. /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1118. AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
  1119. const wchar_t* in_pszEventName, ///< Name of the event
  1120. AkGameObjectID in_gameObjectID, ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
  1121. AkTimeMs in_iPosition, ///< Desired position where playback should restart, in milliseconds
  1122. bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
  1123. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
  1124. );
  1125. #endif //AK_SUPPORT_WCHAR
  1126. /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
  1127. ///
  1128. /// Notes:
  1129. /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
  1130. /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
  1131. /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
  1132. /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
  1133. /// the sound that is currently playing is the first sound of the sequence.
  1134. /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
  1135. /// - With Music Segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
  1136. /// value to seek within the Pre-Entry.
  1137. /// - Sounds/segments are stopped if in_iPosition is greater than their duration.
  1138. /// - in_iPosition is clamped internally to the beginning of the sound/segment.
  1139. /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
  1140. /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
  1141. /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
  1142. /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
  1143. /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
  1144. /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
  1145. /// - This method posts a command in the sound engine queue, thus seeking will not occur before
  1146. /// the audio thread consumes it (after a call to RenderAudio()).
  1147. ///
  1148. /// Notes specific to Music Segments:
  1149. /// - With Music Segments, in_iPosition is relative to the Entry Cue, in milliseconds. Use a negative
  1150. /// value to seek within the Pre-Entry.
  1151. /// - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification
  1152. /// in order to restart them if required.
  1153. /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
  1154. /// take the "look-ahead time" property of their streamed tracks into account for seeking.
  1155. /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
  1156. /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
  1157. /// the exact position of a segment. Also, the segment will be silent during that time
  1158. /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1159. /// also informs you about the remaining look-ahead time.
  1160. ///
  1161. /// Notes specific to Music Switch Containers:
  1162. /// - Seeking triggers a music transition towards the current (or target) segment.
  1163. /// This transition is subject to the container's transition rule that matches the current and defined in the container,
  1164. /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
  1165. /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
  1166. /// - If the specified time is greater than the destination segment's length, the modulo is taken.
  1167. ///
  1168. /// \return
  1169. /// - \c AK_Success if command was queued
  1170. /// - \c AK_IDNotFound if the Event ID is unknown (not loaded or typo in the ID)
  1171. /// \sa
  1172. /// - <tt>AK::SoundEngine::RenderAudio()</tt>
  1173. /// - <tt>AK::SoundEngine::PostEvent()</tt>
  1174. /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
  1175. /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1176. AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
  1177. const char* in_pszEventName, ///< Name of the event
  1178. AkGameObjectID in_gameObjectID, ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
  1179. AkTimeMs in_iPosition, ///< Desired position where playback should restart, in milliseconds
  1180. bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
  1181. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
  1182. );
  1183. /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
  1184. /// Seek position is specified as a percentage of the sound's total duration, and takes looping into account.
  1185. ///
  1186. /// Notes:
  1187. /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
  1188. /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
  1189. /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
  1190. /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
  1191. /// the sound that is currently playing is the first sound of the sequence.
  1192. /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
  1193. /// - in_iPosition is clamped internally to the beginning of the sound/segment.
  1194. /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
  1195. /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
  1196. /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
  1197. /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
  1198. /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
  1199. /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
  1200. /// - This method posts a command in the sound engine queue, thus seeking will not occur before
  1201. /// the audio thread consumes it (after a call to RenderAudio()).
  1202. ///
  1203. /// Notes specific to Music Segments:
  1204. /// - With Music Segments, \c in_fPercent is relative to the Entry Cue, and the segment's duration is the
  1205. /// duration between its entry and exit cues. Consequently, you cannot seek within the pre-entry or
  1206. /// post-exit of a segment using this method. Use absolute values instead.
  1207. /// - Music Segments cannot be looped. You may want to listen to the \c AK_EndOfEvent notification
  1208. /// in order to restart them if required.
  1209. /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
  1210. /// take the "look-ahead time" property of their streamed tracks into account for seeking.
  1211. /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
  1212. /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
  1213. /// the exact position of a segment. Also, the segment will be silent during the time that period
  1214. /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1215. /// also informs you about the remaining look-ahead time.
  1216. ///
  1217. /// Notes specific to Music Switch Containers:
  1218. /// - Seeking triggers a music transition towards the current (or target) segment.
  1219. /// This transition is subject to the container's transition rule that matches the current and defined in the container,
  1220. /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
  1221. /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
  1222. /// - If the specified time is greater than the destination segment's length, the modulo is taken.
  1223. ///
  1224. /// \sa
  1225. /// - <tt>AK::SoundEngine::RenderAudio()</tt>
  1226. /// - <tt>AK::SoundEngine::PostEvent()</tt>
  1227. /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
  1228. /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1229. AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
  1230. AkUniqueID in_eventID, ///< Unique ID of the event
  1231. AkGameObjectID in_gameObjectID , ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
  1232. AkReal32 in_fPercent, ///< Desired position where playback should restart, expressed in a percentage of the file's total duration, between 0 and 1.f (see note above about infinite looping sounds)
  1233. bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
  1234. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
  1235. );
  1236. #ifdef AK_SUPPORT_WCHAR
  1237. /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
  1238. /// Seek position is specified as a percentage of the sound's total duration, and takes looping into account.
  1239. ///
  1240. /// Notes:
  1241. /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
  1242. /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
  1243. /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
  1244. /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
  1245. /// the sound that is currently playing is the first sound of the sequence.
  1246. /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
  1247. /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
  1248. /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
  1249. /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
  1250. /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
  1251. /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
  1252. /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
  1253. /// - This method posts a command in the sound engine queue, thus seeking will not occur before
  1254. /// the audio thread consumes it (after a call to RenderAudio()).
  1255. ///
  1256. /// Notes specific to Music Segments:
  1257. /// - With Music Segments, \c in_fPercent is relative to the Entry Cue, and the segment's duration is the
  1258. /// duration between its entry and exit cues. Consequently, you cannot seek within the pre-entry or
  1259. /// post-exit of a segment using this method. Use absolute values instead.
  1260. /// - Music Segments cannot be looped. You may want to listen to the \c AK_EndOfEvent notification
  1261. /// in order to restart them if required.
  1262. /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
  1263. /// take the "look-ahead time" property of their streamed tracks into account for seeking.
  1264. /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
  1265. /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
  1266. /// the exact position of a segment. Also, the segment will be silent during the time that period
  1267. /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1268. /// also informs you about the remaining look-ahead time.
  1269. ///
  1270. /// Notes specific to Music Switch Containers:
  1271. /// - Seeking triggers a music transition towards the current (or target) segment.
  1272. /// This transition is subject to the container's transition rule that matches the current and defined in the container,
  1273. /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
  1274. /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
  1275. /// - If the specified time is greater than the destination segment's length, the modulo is taken.
  1276. ///
  1277. /// \sa
  1278. /// - <tt>AK::SoundEngine::RenderAudio()</tt>
  1279. /// - <tt>AK::SoundEngine::PostEvent()</tt>
  1280. /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
  1281. /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1282. AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
  1283. const wchar_t* in_pszEventName, ///< Name of the event
  1284. AkGameObjectID in_gameObjectID , ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
  1285. AkReal32 in_fPercent , ///< Desired position where playback should restart, expressed in a percentage of the file's total duration, between 0 and 1.f (see note above about infinite looping sounds)
  1286. bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see note above)
  1287. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
  1288. );
  1289. #endif //AK_SUPPORT_WCHAR
  1290. /// Seeks inside all playing objects that are referenced in Play Actions of the specified Event.
  1291. /// Seek position is specified as a percentage of the sound's total duration, and takes looping into account.
  1292. ///
  1293. /// Notes:
  1294. /// - This works with all objects of the actor-mixer hierarchy, and also with Music Segments and Music Switch Containers.
  1295. /// - There is a restriction with sounds that play within a continuous sequence. Seeking is ignored
  1296. /// if one of their ancestors is a continuous (random or sequence) container with crossfade or
  1297. /// trigger rate transitions. Seeking is also ignored with sample-accurate transitions, unless
  1298. /// the sound that is currently playing is the first sound of the sequence.
  1299. /// - Seeking is also ignored with voices that can go virtual with "From Beginning" behavior.
  1300. /// - If the option "Seek to nearest marker" is used, the seeking position snaps to the nearest marker.
  1301. /// With objects of the actor-mixer hierarchy, markers are embedded in wave files by an external wave editor.
  1302. /// Note that looping regions ("sampler loop") are not considered as markers. Also, the "add file name marker" of the
  1303. /// conversion settings dialog adds a marker at the beginning of the file, which is considered when seeking
  1304. /// to nearest marker. In the case of objects of the interactive music hierarchy, user (wave) markers are ignored:
  1305. /// seeking occurs to the nearest segment cue (authored in the segment editor), including the Entry Cue, but excluding the Exit Cue.
  1306. /// - This method posts a command in the sound engine queue, thus seeking will not occur before
  1307. /// the audio thread consumes it (after a call to RenderAudio()).
  1308. ///
  1309. /// Notes specific to Music Segments:
  1310. /// - With Music Segments, in_fPercent is relative to the Entry Cue, and the segment's duration is the
  1311. /// duration between its entry and exit cues. Consequently, you cannot seek within the pre-entry or
  1312. /// post-exit of a segment using this method. Use absolute values instead.
  1313. /// - Music segments cannot be looped. You may want to listen to the AK_EndOfEvent notification
  1314. /// in order to restart them if required.
  1315. /// - In order to restart at the correct location, with all their tracks synchronized, Music Segments
  1316. /// take the "look-ahead time" property of their streamed tracks into account for seeking.
  1317. /// Consequently, the resulting position after a call to SeekOnEvent() might be earlier than the
  1318. /// value that was passed to the method. Use <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt> to query
  1319. /// the exact position of a segment. Also, the segment will be silent during the time that period
  1320. /// (so that it restarts precisely at the position that you specified). <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1321. /// also informs you about the remaining look-ahead time.
  1322. ///
  1323. /// Notes specific to Music Switch Containers:
  1324. /// - Seeking triggers a music transition towards the current (or target) segment.
  1325. /// This transition is subject to the container's transition rule that matches the current and defined in the container,
  1326. /// so the moment when seeking occurs depends on the rule's "Exit At" property. On the other hand, the starting position
  1327. /// in the target segment depends on both the desired seeking position and the rule's "Sync To" property.
  1328. /// - If the specified time is greater than the destination segment's length, the modulo is taken.
  1329. ///
  1330. /// \sa
  1331. /// - <tt>AK::SoundEngine::RenderAudio()</tt>
  1332. /// - <tt>AK::SoundEngine::PostEvent()</tt>
  1333. /// - <tt>AK::SoundEngine::GetSourcePlayPosition()</tt>
  1334. /// - <tt>AK::MusicEngine::GetPlayingSegmentInfo()</tt>
  1335. AK_EXTERNAPIFUNC( AKRESULT, SeekOnEvent )(
  1336. const char* in_pszEventName, ///< Name of the event
  1337. AkGameObjectID in_gameObjectID, ///< Associated game object ID; use AK_INVALID_GAME_OBJECT to affect all game objects
  1338. AkReal32 in_fPercent, ///< Desired position where playback should restart, expressed in a percentage of the file's total duration, between 0 and 1.f (see note above about infinite looping sounds)
  1339. bool in_bSeekToNearestMarker = false, ///< If true, the final seeking position will be made equal to the nearest marker (see notes above).
  1340. AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID ///< Specify the playing ID for the seek to be applied to. Will result in the seek happening only on active actions of the playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any, to seek on all active actions of this event ID.
  1341. );
  1342. /// Cancels all Event callbacks associated with a specific callback cookie.\n
  1343. /// \sa
  1344. /// - \c <tt>AK::SoundEngine::PostEvent()</tt>
  1345. AK_EXTERNAPIFUNC( void, CancelEventCallbackCookie )(
  1346. void * in_pCookie ///< Callback cookie to be cancelled
  1347. );
  1348. /// Cancels all Event callbacks associated with a specific game object.\n
  1349. /// \sa
  1350. /// - \c <tt>AK::SoundEngine::PostEvent()</tt>
  1351. AK_EXTERNAPIFUNC( void, CancelEventCallbackGameObject )(
  1352. AkGameObjectID in_gameObjectID ///< ID of the game object to be cancelled
  1353. );
  1354. /// Cancels all Event callbacks for a specific playing ID.
  1355. /// \sa
  1356. /// - \c <tt>AK::SoundEngine::PostEvent()</tt>
  1357. AK_EXTERNAPIFUNC( void, CancelEventCallback )(
  1358. AkPlayingID in_playingID ///< Playing ID of the event that must not use callbacks
  1359. );
  1360. /// Gets the current position of the source associated with this playing ID, obtained from PostEvent(). If more than one source is playing,
  1361. /// the first to play is returned.
  1362. /// Notes:
  1363. /// - You need to pass AK_EnableGetSourcePlayPosition to PostEvent() in order to use this function, otherwise
  1364. /// it returns AK_Fail, even if the playing ID is valid.
  1365. /// - The source's position is updated at every audio frame, and the time at which this occurs is stored.
  1366. /// When you call this function from your thread, you therefore query the position that was updated in the previous audio frame.
  1367. /// If in_bExtrapolate is true (default), the returned position is extrapolated using the elapsed time since last
  1368. /// sound engine update and the source's playback rate.
  1369. /// \return
  1370. /// - \c AK_Success if successful.
  1371. /// - \c AK_InvalidParameter if the provided pointer is not valid.
  1372. /// - \c AK_PlayingIDNotFound if the playing ID is invalid (not playing yet, or finished playing).
  1373. /// \sa
  1374. /// - \ref soundengine_query_pos
  1375. /// - \ref concept_events
  1376. AK_EXTERNAPIFUNC( AKRESULT, GetSourcePlayPosition )(
  1377. AkPlayingID in_PlayingID, ///< Playing ID returned by <tt>AK::SoundEngine::PostEvent()</tt>
  1378. AkTimeMs* out_puPosition, ///< Position of the source (in ms) associated with the specified playing ID
  1379. bool in_bExtrapolate = true ///< Position is extrapolated based on time elapsed since last sound engine update.
  1380. );
  1381. /// Gets the current position of the sources associated with this playing ID, obtained from PostEvent().
  1382. /// Notes:
  1383. /// - You need to pass AK_EnableGetSourcePlayPosition to PostEvent() in order to use this function, otherwise
  1384. /// it returns AK_Fail, even if the playing ID is valid.
  1385. /// - The source's position is updated at every audio frame, and the time at which this occurs is stored.
  1386. /// When you call this function from your thread, you therefore query the position that was updated in the previous audio frame.
  1387. /// If in_bExtrapolate is true (default), the returned position is extrapolated using the elapsed time since last
  1388. /// sound engine update and the source's playback rate.
  1389. /// - If 0 is passed in for the number of entries (*in_pcPositions == 0) then only the number of positions will be returned and the
  1390. /// position array (out_puPositions) will not be updated.
  1391. /// - The io_pcPositions pointer must be non-NULL.
  1392. /// out_puPositions may be NULL if *io_pcPositions == 0, otherwise it must be non-NULL.
  1393. /// \return
  1394. /// - \c AK_Success if successful.
  1395. /// - \c AK_InvalidParameter if the provided pointer is not valid.
  1396. /// - \c AK_PlayingIDNotFound if the playing ID is invalid (not playing yet, or finished playing).
  1397. /// \sa
  1398. /// - \ref soundengine_query_pos
  1399. /// - \ref concept_events
  1400. AK_EXTERNAPIFUNC(AKRESULT, GetSourcePlayPositions)(
  1401. AkPlayingID in_PlayingID, ///< Playing ID returned by <tt>AK::SoundEngine::PostEvent()</tt>
  1402. AkSourcePosition* out_puPositions, ///< Audio Node IDs and positions of sources associated with the specified playing ID
  1403. AkUInt32 * io_pcPositions, ///< Number of entries in out_puPositions. Needs to be set to the size of the array: it is adjusted to the actual number of returned entries
  1404. bool in_bExtrapolate = true ///< Position is extrapolated based on time elapsed since last sound engine update
  1405. );
  1406. /// Gets the stream buffering of the sources associated with this playing ID, obtained from PostEvent().
  1407. /// Notes:
  1408. /// - You need to pass AK_EnableGetSourceStreamBuffering to PostEvent() in order to use this function, otherwise
  1409. /// it returns AK_Fail, even if the playing ID is valid.
  1410. /// - The sources stream buffering is updated at every audio frame. If there are multiple sources associated with this playing ID,
  1411. /// the value returned corresponds to the least buffered source.
  1412. /// - The returned buffering status out_bIsBuffering will be true If any of the sources associated with the playing ID are actively being buffered.
  1413. /// It will be false if all of them have reached the end of file, or have reached a state where they are buffered enough and streaming is temporarily idle.
  1414. /// - Purely in-memory sources are excluded from this database. If all sources are in-memory, GetSourceStreamBuffering() will return AK_Fail.
  1415. /// - The returned buffering amount and state is not completely accurate with some hardware-accelerated codecs. In such cases, the amount of stream buffering is generally underestimated.
  1416. /// On the other hand, it is not guaranteed that the source will be ready to produce data at the next audio frame even if out_bIsBuffering has turned to false.
  1417. /// \return
  1418. /// - \c AK_Success if successful.
  1419. /// - \c AK_PlayingIDNotFound if the source data associated with this playing ID is not found, for example if PostEvent() was not called with AK_EnableGetSourceStreamBuffering, or if the header was not parsed.
  1420. /// \sa
  1421. /// - \ref concept_events
  1422. AK_EXTERNAPIFUNC( AKRESULT, GetSourceStreamBuffering )(
  1423. AkPlayingID in_PlayingID, ///< Playing ID returned by <tt>AK::SoundEngine::PostEvent()</tt>
  1424. AkTimeMs & out_buffering, ///< Returned amount of buffering (in ms) of the source (or one of the sources) associated with that playing ID
  1425. bool & out_bIsBuffering ///< Returned buffering status of the source(s) associated with that playing ID
  1426. );
  1427. /// Stops the current content playing associated to the specified game object ID.
  1428. /// If no game object is specified, all sounds will be stopped.
  1429. AK_EXTERNAPIFUNC( void, StopAll )(
  1430. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT ///< (Optional)Specify a game object to stop only playback associated to the provided game object ID.
  1431. );
  1432. /// Stop the current content playing associated to the specified playing ID.
  1433. /// \aknote
  1434. /// This function is deprecated. Please use ExecuteActionOnPlayingID() in its place.
  1435. /// \endaknote
  1436. /// \sa
  1437. /// - <tt>AK::SoundEngine::ExecuteActionOnPlayingID()</tt>
  1438. AK_EXTERNAPIFUNC( void, StopPlayingID )(
  1439. AkPlayingID in_playingID, ///< Playing ID to be stopped.
  1440. AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
  1441. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
  1442. );
  1443. /// Executes an Action on the content associated to the specified playing ID.
  1444. /// \sa
  1445. /// - <tt>AK::SoundEngine::AkActionOnEventType</tt>
  1446. AK_EXTERNAPIFUNC(void, ExecuteActionOnPlayingID)(
  1447. AkActionOnEventType in_ActionType, ///< Action to execute on the specified playing ID.
  1448. AkPlayingID in_playingID, ///< Playing ID on which to execute the action.
  1449. AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
  1450. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
  1451. );
  1452. /// Sets the random seed value. Can be used to synchronize randomness
  1453. /// across instances of the Sound Engine.
  1454. /// \remark This seeds the number generator used for all container randomizations
  1455. /// and the plug-in RNG; since it acts globally, this should be called right
  1456. /// before any PostEvent call where randomness synchronization is required,
  1457. /// and cannot guarantee similar results for continuous containers.
  1458. /// \sa
  1459. /// - <tt>AK::IAkPluginServiceRNG</tt>
  1460. AK_EXTERNAPIFUNC( void, SetRandomSeed )(
  1461. AkUInt32 in_uSeed ///< Random seed.
  1462. );
  1463. /// Mutes/Unmutes the busses tagged as background music.
  1464. /// This is automatically called for platforms that have user-music support.
  1465. /// This function is provided to give the same behavior on platforms that don't have user-music support.
  1466. AK_EXTERNAPIFUNC( void, MuteBackgroundMusic ) (
  1467. bool in_bMute ///< Sets true to mute, false to unmute.
  1468. );
  1469. //@}
  1470. /// Gets the state of the Background Music busses. This state is either set directly
  1471. /// with \c AK::SoundEngine::MuteBackgroundMusic or by the OS, if it has User Music services.
  1472. /// \return true if the background music busses are muted, false if not.
  1473. AK_EXTERNAPIFUNC(bool, GetBackgroundMusicMute) ();
  1474. //@}
  1475. /// Sends custom game data to a plug-in that resides on a bus (insert Effect or mixer plug-in).
  1476. /// Data will be copied and stored into a separate list.
  1477. /// Previous entry is deleted when a new one is sent.
  1478. /// Sets the data pointer to NULL to clear item from the list.
  1479. /// \aknote The plug-in type and ID is passed and matched with plugins set on the desired bus.
  1480. /// This means that you cannot send different data to various instances of the plug-in on a same bus.\endaknote
  1481. /// \return AK_Success if data was sent successfully.
  1482. AK_EXTERNAPIFUNC( AKRESULT, SendPluginCustomGameData ) (
  1483. AkUniqueID in_busID, ///< Bus ID
  1484. AkGameObjectID in_busObjectID, ///< Bus Object ID. Pass AK_INVALID_GAME_OBJECT to send custom data with global scope. Game object scope supersedes global scope, as with RTPCs.
  1485. AkPluginType in_eType, ///< Plug-in type (for example, source or effect)
  1486. AkUInt32 in_uCompanyID, ///< Company identifier (as declared in the plug-in description XML file)
  1487. AkUInt32 in_uPluginID, ///< Plug-in identifier (as declared in the plug-in description XML file)
  1488. const void* in_pData, ///< The data blob
  1489. AkUInt32 in_uSizeInBytes ///< Size of data
  1490. );
  1491. //@}
  1492. ////////////////////////////////////////////////////////////////////////
  1493. /// @name Game Objects
  1494. //@{
  1495. /// Registers a game object.
  1496. /// \return
  1497. /// - \c AK_Success if successful
  1498. /// - \c AK_InvalidParameter if the specified AkGameObjectID is invalid. Range 0xFFFFFFFFFFFFFFE0 (-32) to 0xFFFFFFFFFFFFFFFF (-1) are invalid inclusively.
  1499. /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no
  1500. /// matter how many times it has been registered.
  1501. /// \sa
  1502. /// - <tt>AK::SoundEngine::UnregisterGameObj()</tt>
  1503. /// - <tt>AK::SoundEngine::UnregisterAllGameObj()</tt>
  1504. /// - \ref concept_gameobjects
  1505. AK_EXTERNAPIFUNC(AKRESULT, RegisterGameObj)(
  1506. AkGameObjectID in_gameObjectID ///< ID of the game object to be registered. Valid range is [0 to 0xFFFFFFFFFFFFFFDF].
  1507. );
  1508. /// Registers a game object.
  1509. /// \return
  1510. /// - \c AK_Success if successful
  1511. /// - \c AK_InvalidParameter if the specified AkGameObjectID is invalid. Range 0xFFFFFFFFFFFFFFE0 (-32) to 0xFFFFFFFFFFFFFFFF (-1) are invalid inclusively.
  1512. /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no
  1513. /// matter how many times it has been registered.
  1514. /// \sa
  1515. /// - <tt>AK::SoundEngine::UnregisterGameObj()</tt>
  1516. /// - <tt>AK::SoundEngine::UnregisterAllGameObj()</tt>
  1517. /// - \ref concept_gameobjects
  1518. AK_EXTERNAPIFUNC( AKRESULT, RegisterGameObj )(
  1519. AkGameObjectID in_gameObjectID, ///< ID of the game object to be registered. Valid range is [0 to 0xFFFFFFFFFFFFFFDF].
  1520. const char * in_pszObjName ///< Name of the game object (for monitoring purpose)
  1521. );
  1522. /// Unregisters a game object.
  1523. /// \return
  1524. /// - \c AK_Success if successful
  1525. /// - \c AK_InvalidParameter if the specified AkGameObjectID is invalid. Range 0xFFFFFFFFFFFFFFE0 (-32) to 0xFFFFFFFFFFFFFFFF (-1) are invalid inclusively.
  1526. /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no
  1527. /// matter how many times it has been registered. Unregistering a game object while it is
  1528. /// in use is allowed, but the control over the parameters of this game object is lost.
  1529. /// For example, say a sound associated with this game object is a 3D moving sound. This sound will
  1530. /// stop moving when the game object is unregistered, and there will be no way to regain control over the game object.
  1531. /// \sa
  1532. /// - <tt>AK::SoundEngine::RegisterGameObj()</tt>
  1533. /// - <tt>AK::SoundEngine::UnregisterAllGameObj()</tt>
  1534. /// - \ref concept_gameobjects
  1535. AK_EXTERNAPIFUNC( AKRESULT, UnregisterGameObj )(
  1536. AkGameObjectID in_gameObjectID ///< ID of the game object to be unregistered. Valid range is [0 to 0xFFFFFFFFFFFFFFDF]. Use
  1537. /// AK_INVALID_GAME_OBJECT to unregister all game objects.
  1538. );
  1539. /// Unregister all game objects, or all game objects with a particular matching set of property flags.
  1540. /// This function to can be used to unregister all game objects.
  1541. /// \return
  1542. /// - \c AK_Success if successful
  1543. /// \remark Registering a game object twice does nothing. Unregistering it once unregisters it no
  1544. /// matter how many times it has been registered. Unregistering a game object while it is
  1545. /// in use is allowed, but the control over the parameters of this game object is lost.
  1546. /// For example, if a sound associated with this game object is a 3D moving sound, it will
  1547. /// stop moving once the game object is unregistered, and there will be no way to recover
  1548. /// the control over this game object.
  1549. /// \sa
  1550. /// - <tt>AK::SoundEngine::RegisterGameObj()</tt>
  1551. /// - <tt>AK::SoundEngine::UnregisterGameObj()</tt>
  1552. /// - \ref concept_gameobjects
  1553. AK_EXTERNAPIFUNC( AKRESULT, UnregisterAllGameObj )(
  1554. );
  1555. /// Sets the position of a game object.
  1556. /// \warning The object's orientation vector (in_Position.Orientation) must be normalized.
  1557. /// \return
  1558. /// - \c AK_Success when successful
  1559. /// - \c AK_InvalidParameter if parameters are not valid, for example:
  1560. /// + in_Position makes an invalid transform
  1561. /// + in_eFlags is not one of the valid enum values
  1562. /// + the game object ID is in the reserved ID range.
  1563. /// \sa
  1564. /// - \ref soundengine_3dpositions
  1565. AK_EXTERNAPIFUNC( AKRESULT, SetPosition )(
  1566. AkGameObjectID in_GameObjectID, ///< Game Object identifier
  1567. const AkSoundPosition & in_Position,///< Position to set; in_Position.Orientation must be normalized.
  1568. AkSetPositionFlags in_eFlags = AkSetPositionFlags_Default ///< Optional flags to independently set the position of the emitter or listener component.
  1569. );
  1570. /// Sets multiple positions to a single game object.
  1571. /// Setting multiple positions on a single game object is a way to simulate multiple emission sources while using the resources of only one voice.
  1572. /// This can be used to simulate wall openings, area sounds, or multiple objects emitting the same sound in the same area.
  1573. /// \aknote
  1574. /// - Calling <tt>AK::SoundEngine::SetMultiplePositions()</tt> with only one position is the same as calling <tt>AK::SoundEngine::SetPosition()</tt>
  1575. /// - If a sound has diffraction enabled, it is treated as <tt>MultiPositionType_MultiDirections</tt>. <tt>MultiPositionType_MultiSources</tt> is not supported in this case.
  1576. /// \endaknote
  1577. /// \return
  1578. /// - \c AK_Success when successful
  1579. /// - \c AK_CommandTooLarge if the number of positions is too large for the command queue. Reduce the number of positions.
  1580. /// - \c AK_InvalidParameter if parameters are not valid, for example:
  1581. /// + in_Position makes an invalid transform
  1582. /// + in_eFlags is not one of the valid enum values
  1583. /// + the game object ID is in the reserved ID range.
  1584. /// \sa
  1585. /// - \ref soundengine_3dpositions
  1586. /// - \ref soundengine_3dpositions_multiplepos
  1587. /// - \ref AK::SoundEngine::MultiPositionType
  1588. AK_EXTERNAPIFUNC( AKRESULT, SetMultiplePositions )(
  1589. AkGameObjectID in_GameObjectID, ///< Game Object identifier.
  1590. const AkSoundPosition * in_pPositions, ///< Array of positions to apply.
  1591. AkUInt16 in_NumPositions, ///< Number of positions specified in the provided array.
  1592. MultiPositionType in_eMultiPositionType = MultiPositionType_MultiDirections, ///< \ref AK::SoundEngine::MultiPositionType
  1593. AkSetPositionFlags in_eFlags = AkSetPositionFlags_Default ///< Optional flags to independently set the position of the emitter or listener component.
  1594. );
  1595. /// Sets multiple positions to a single game object, with flexible assignment of input channels.
  1596. /// Setting multiple positions on a single game object is a way to simulate multiple emission sources while using the resources of only one voice.
  1597. /// This can be used to simulate wall openings, area sounds, or multiple objects emitting the same sound in the same area.
  1598. /// \aknote Calling <tt>AK::SoundEngine::SetMultiplePositions()</tt> with only one position is the same as calling <tt>AK::SoundEngine::SetPosition()</tt> \endaknote
  1599. /// \return
  1600. /// - \c AK_Success when successful
  1601. /// - \c AK_CommandTooLarge if the number of positions is too large for the command queue. Reduce the number of positions.
  1602. /// - \c AK_InvalidParameter if parameters are not valid.
  1603. /// \sa
  1604. /// - \ref soundengine_3dpositions
  1605. /// - \ref soundengine_3dpositions_multiplepos
  1606. /// - \ref AK::SoundEngine::MultiPositionType
  1607. AK_EXTERNAPIFUNC( AKRESULT, SetMultiplePositions )(
  1608. AkGameObjectID in_GameObjectID, ///< Game Object identifier.
  1609. const AkChannelEmitter * in_pPositions, ///< Array of positions to apply, each using its own channel mask.
  1610. AkUInt16 in_NumPositions, ///< Number of positions specified in the provided array.
  1611. MultiPositionType in_eMultiPositionType = MultiPositionType_MultiDirections, ///< \ref AK::SoundEngine::MultiPositionType
  1612. AkSetPositionFlags in_eFlags = AkSetPositionFlags_Default ///< Optional flags to independently set the position of the emitter or listener component.
  1613. );
  1614. /// Sets the scaling factor of a Game Object.
  1615. /// Modify the attenuation computations on this Game Object to simulate sounds with a larger or smaller area of effect.
  1616. /// \return
  1617. /// - \c AK_Success when successful
  1618. /// - \c AK_InvalidParameter if the scaling factor specified was 0 or negative.
  1619. /// - \c AK_InvalidFloatValue if the value specified was NaN or Inf
  1620. AK_EXTERNAPIFUNC( AKRESULT, SetScalingFactor )(
  1621. AkGameObjectID in_GameObjectID, ///< Game object identifier
  1622. AkReal32 in_fAttenuationScalingFactor ///< Scaling Factor, 1 means 100%, 0.5 means 50%, 2 means 200%, and so on.
  1623. );
  1624. /// Use the position of a separate game object for distance calculations for a specified listener.
  1625. /// When <tt>AK::SoundEngine::SetDistanceProbe()</tt> is called, Wwise calculates distance attenuation and filtering
  1626. /// based on the distance between the distance probe Game Object (\c in_distanceProbeGameObjectID) and the emitter Game Object's position.
  1627. /// In third-person perspective applications, the distance probe Game Object may be set to the player character's position,
  1628. /// and the listener Game Object's position to that of the camera. In this scenario, attenuation is based on
  1629. /// the distance between the character and the sound, whereas panning, spatialization, and spread and focus calculations are base on the camera.
  1630. /// Both Game Objects, \c in_listenerGameObjectID and \c in_distanceProbeGameObjectID must have been previously registered using <tt>AK::SoundEngine::RegisterGameObj</tt>.
  1631. /// This funciton is optional. if <tt>AK::SoundEngine::SetDistanceProbe()</tt> is never called, distance calculations are based on the listener Game Object position.
  1632. /// To clear the distance probe, and revert to using the listener position for distance calculations, pass \c AK_INVALID_GAME_OBJECT to \c in_distanceProbeGameObjectID.
  1633. /// \aknote If the distance probe Game Object is assigned multiple positions, then the first position is used for distance calculations by the listener. \endaknote
  1634. /// \return
  1635. /// - \c AK_Success when successful
  1636. /// \sa
  1637. /// - <tt>AK::SoundEngine::SetPosition()</tt>
  1638. AK_EXTERNAPIFUNC(AKRESULT, SetDistanceProbe)(
  1639. AkGameObjectID in_listenerGameObjectID, ///< Game object identifier for the listener. Must have been previously registered via RegisterGameObj.
  1640. AkGameObjectID in_distanceProbeGameObjectID ///< Game object identifier for the distance probe, or \c AK_INVALID_GAME_OBJECT to reset distance probe. If valid, must have been previously registered via RegisterGameObj.
  1641. );
  1642. //@}
  1643. ////////////////////////////////////////////////////////////////////////
  1644. /// @name Bank Management
  1645. //@{
  1646. /// Unload all currently loaded banks.
  1647. /// It also internally calls ClearPreparedEvents() since at least one bank must have been loaded to allow preparing events.
  1648. /// \return
  1649. /// - \c AK_Success if successful
  1650. /// - \c AK_NotInitialized if the sound engine was not correctly initialized or if there is not enough memory to handle the command
  1651. /// \sa
  1652. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  1653. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  1654. /// - \ref soundengine_banks
  1655. AK_EXTERNAPIFUNC( AKRESULT, ClearBanks )();
  1656. /// Sets the I/O settings of the bank load and prepare event processes.
  1657. /// The sound engine uses default values unless explicitly set by calling this method.
  1658. /// \warning This function must be called before loading banks.
  1659. /// \return
  1660. /// - \c AK_Success if successful
  1661. /// - \c AK_NotInitialized if the sound engine was not correctly initialized
  1662. /// - \c AK_InvalidParameter if some parameters are invalid, check the debug console
  1663. /// \sa
  1664. /// - \ref soundengine_banks
  1665. /// - \ref streamingdevicemanager
  1666. AK_EXTERNAPIFUNC( AKRESULT, SetBankLoadIOSettings )(
  1667. AkReal32 in_fThroughput, ///< Average throughput of bank data streaming (bytes/ms) (the default value is AK_DEFAULT_BANK_THROUGHPUT)
  1668. AkPriority in_priority ///< Priority of bank streaming (the default value is AK_DEFAULT_PRIORITY)
  1669. );
  1670. #ifdef AK_SUPPORT_WCHAR
  1671. /// Load a bank synchronously (by Unicode string).\n
  1672. /// The bank name and type are passed to the Stream Manager.
  1673. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  1674. /// A bank load request will be posted, and consumed by the Bank Manager thread.
  1675. /// The function returns when the request has been completely processed.
  1676. /// \return
  1677. /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
  1678. /// You may use this ID with UnloadBank().
  1679. /// - \c AK_Success: Load or unload successful.
  1680. /// - \c AK_BankAlreadyLoaded: This bank is already loaded, nothing done.
  1681. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  1682. /// - \c AK_BankReadError: I/O error.
  1683. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that you used to generate the SoundBanks matches that of the SDK you are currently using.
  1684. /// - \c AK_InvalidFile: File specified could not be opened.
  1685. /// - \c AK_InvalidParameter: Invalid parameter, invalid memory alignment.
  1686. /// - \c AK_NotInitialized if the sound engine was not correctly initialized
  1687. /// - \c AK_InvalidParameter if some parameters are invalid, check the debug console
  1688. /// - \c AK_InvalidBankType if the bank type parameter is out of range.
  1689. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure, check the debug console)
  1690. /// \remarks
  1691. /// - The initialization bank must be loaded first.
  1692. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  1693. /// initialization bank. If you need to load SoundBanks from a different project, you
  1694. /// must first unload ALL banks, including the initialization bank, then load the
  1695. /// initialization bank from the other project, and finally load banks from that project.
  1696. /// - Codecs and plug-ins must be registered before loading banks that use them.
  1697. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  1698. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  1699. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  1700. /// posting the event will fail.
  1701. /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
  1702. /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
  1703. /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in
  1704. /// your implementation of the Stream Manager, or in the Low-Level I/O module if you use the default Stream Manager's implementation.
  1705. /// \sa
  1706. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  1707. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  1708. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  1709. /// - \ref soundengine_banks
  1710. /// - \ref integrating_elements_plugins
  1711. /// - \ref streamingdevicemanager
  1712. /// - \ref streamingmanager_lowlevel
  1713. /// - \ref sdk_bank_training
  1714. AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
  1715. const wchar_t* in_pszString, ///< Name of the bank to load
  1716. AkBankID & out_bankID, ///< Returned bank ID
  1717. AkBankType in_bankType = AkBankType_User ///< Type of the bank to load
  1718. );
  1719. #endif //AK_SUPPORT_WCHAR
  1720. /// Loads a bank synchronously.\n
  1721. /// The bank name and type are passed to the Stream Manager.
  1722. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  1723. /// A bank load request will be posted, and consumed by the Bank Manager thread.
  1724. /// The function returns when the request has been completely processed.
  1725. /// \return
  1726. /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
  1727. /// You may use this ID with UnloadBank().
  1728. /// - \c AK_Success: Load or unload successful.
  1729. /// - \c AK_BankAlreadyLoaded: This bank is already loaded, nothing done.
  1730. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  1731. /// - \c AK_BankReadError: I/O error.
  1732. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  1733. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  1734. /// - \c AK_InvalidFile: File specified could not be opened.
  1735. /// - \c AK_NotInitialized if the sound engine was not correctly initialized
  1736. /// - \c AK_InvalidParameter if some parameters are invalid, check the debug console
  1737. /// - \c AK_InvalidBankType if the bank type parameter is out of range.
  1738. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  1739. /// \remarks
  1740. /// - The initialization bank must be loaded first.
  1741. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  1742. /// initialization bank. If you need to load SoundBanks from a different project, you
  1743. /// must first unload ALL banks, including the initialization bank, then load the
  1744. /// initialization bank from the other project, and finally load banks from that project.
  1745. /// - Codecs and plug-ins must be registered before loading banks that use them.
  1746. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  1747. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  1748. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  1749. /// posting the event will fail.
  1750. /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
  1751. /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
  1752. /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in
  1753. /// your implementation of the Stream Manager, or in the Low-Level I/O module if you use the default Stream Manager's implementation.
  1754. /// \sa
  1755. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  1756. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  1757. /// - <tt>AK::SoundEngine::GetIDFromString</tt>
  1758. /// - \ref soundengine_banks
  1759. /// - \ref integrating_elements_plugins
  1760. /// - \ref streamingdevicemanager
  1761. /// - \ref streamingmanager_lowlevel
  1762. /// - \ref sdk_bank_training
  1763. AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
  1764. const char* in_pszString, ///< Name of the bank to load
  1765. AkBankID & out_bankID, ///< Returned bank ID
  1766. AkBankType in_bankType = AkBankType_User ///< Type of the bank to load
  1767. );
  1768. /// Loads a bank synchronously (by ID).\n
  1769. /// \aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
  1770. /// The bank ID is passed to the Stream Manager.
  1771. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  1772. /// A bank load request will be posted, and consumed by the Bank Manager thread.
  1773. /// The function returns when the request has been completely processed.
  1774. /// \return
  1775. /// - \c AK_Success: Load or unload successful.
  1776. /// - \c AK_BankAlreadyLoaded: This bank is already loaded, nothing done.
  1777. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  1778. /// - \c AK_BankReadError: I/O error. The bank is either shorter than expected or its data corrupted.
  1779. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  1780. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  1781. /// - \c AK_InvalidFile: File specified could not be opened.
  1782. /// - \c AK_NotInitialized if the sound engine was not correctly initialized
  1783. /// - \c AK_InvalidParameter if some parameters are invalid, check the debug console or Wwise Profiler
  1784. /// - \c AK_InvalidBankType if the bank type parameter is out of range.
  1785. /// - \c AK_FileNotFound if the bank file was not found on disk.
  1786. /// - \c AK_FilePermissionError if the file permissions are wrong for the file
  1787. /// - \c AK_Fail: Load or unload failed for any other reason. , check the debug console or Wwise Profiler
  1788. /// \remarks
  1789. /// - The initialization bank must be loaded first.
  1790. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  1791. /// initialization bank. If you need to load SoundBanks from a different project, you
  1792. /// must first unload ALL banks, including the initialization bank, then load the
  1793. /// initialization bank from the other project, and finally load banks from that project.
  1794. /// - Codecs and plug-ins must be registered before loading banks that use them.
  1795. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  1796. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  1797. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  1798. /// posting the event will fail.
  1799. /// \sa
  1800. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  1801. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  1802. /// - \ref soundengine_banks
  1803. /// - \ref integrating_elements_plugins
  1804. /// - \ref sdk_bank_training
  1805. AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
  1806. AkBankID in_bankID, ///< Bank ID of the bank to load
  1807. AkBankType in_bankType = AkBankType_User ///< Type of the bank to load
  1808. );
  1809. /// Loads a bank synchronously (from in-memory data, in-place, user bank only).\n
  1810. ///
  1811. /// IMPORTANT: Banks loaded from memory with in-place data MUST be unloaded using the UnloadBank function
  1812. /// providing the same memory pointer. Make sure you are using the correct UnloadBank(...) overload
  1813. ///
  1814. /// Use LoadBankMemoryView when you want to manage I/O on your side. Load the bank file
  1815. /// in a buffer and pass its address to the sound engine.
  1816. /// In-memory loading is in-place: *** the memory must be valid until the bank is unloaded. ***
  1817. /// A bank load request will be posted, and consumed by the Bank Manager thread.
  1818. /// The function returns when the request has been completely processed.
  1819. /// \return
  1820. /// The bank ID, which is stored in the first few bytes of the bank file. You may use this
  1821. /// ID with UnloadBank().
  1822. /// - \c AK_Success: Load or unload successful.
  1823. /// - \c AK_BankAlreadyLoaded: This bank is already loaded, nothing done.
  1824. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  1825. /// - \c AK_BankReadError: I/O error.
  1826. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  1827. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  1828. /// - \c AK_InvalidFile: File specified could not be opened.
  1829. /// - \c AK_NotInitialized if the sound engine was not correctly initialized
  1830. /// - \c AK_InvalidParameter if some parameters are invalid, check the debug console
  1831. /// - \c AK_InvalidBankType if the bank is not a user-defined bank.
  1832. /// - \c AK_DataAlignmentError if the data pointer is not aligned properly
  1833. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  1834. /// \remarks
  1835. /// - The initialization bank must be loaded first.
  1836. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  1837. /// initialization bank. If you need to load SoundBanks from a different project, you
  1838. /// must first unload ALL banks, including the initialization bank, then load the
  1839. /// initialization bank from the other project, and finally load banks from that project.
  1840. /// - Codecs and plug-ins must be registered before loading banks that use them.
  1841. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  1842. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  1843. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  1844. /// posting the event will fail.
  1845. /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
  1846. /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Device memory allocator.
  1847. /// - Avoid using this function for banks containing a lot of events or structure data: this data will be unpacked into the sound engine heap,
  1848. /// making the supplied bank memory redundant. For event/structure-only banks, prefer LoadBankMemoryCopy().
  1849. /// \sa
  1850. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  1851. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  1852. /// - \ref soundengine_banks
  1853. /// - \ref integrating_elements_plugins
  1854. /// - \ref sdk_bank_training
  1855. AK_EXTERNAPIFUNC( AKRESULT, LoadBankMemoryView )(
  1856. const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is stored in sound engine, memory must remain valid)
  1857. AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
  1858. AkBankID & out_bankID ///< Returned bank ID
  1859. );
  1860. /// Loads a bank synchronously (from in-memory data, in-place, any bank type).\n
  1861. ///
  1862. /// IMPORTANT: Banks loaded from memory with in-place data MUST be unloaded using the UnloadBank function
  1863. /// providing the same memory pointer. Make sure you are using the correct UnloadBank(...) overload
  1864. ///
  1865. /// Use LoadBankMemoryView when you want to manage I/O on your side. Load the bank file
  1866. /// in a buffer and pass its address to the sound engine.
  1867. /// In-memory loading is in-place: *** the memory must be valid until the bank is unloaded. ***
  1868. /// A bank load request will be posted, and consumed by the Bank Manager thread.
  1869. /// The function returns when the request has been completely processed.
  1870. /// \return
  1871. /// The bank ID, which is stored in the first few bytes of the bank file. You may use this
  1872. /// ID with UnloadBank().
  1873. /// - \c AK_Success: Load or unload successful.
  1874. /// - \c AK_BankAlreadyLoaded: This bank is already loaded, nothing done.
  1875. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  1876. /// - \c AK_BankReadError: I/O error.
  1877. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  1878. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  1879. /// - \c AK_InvalidFile: File specified could not be opened.
  1880. /// - \c AK_NotInitialized if the sound engine was not correctly initialized
  1881. /// - \c AK_InvalidParameter if some parameters are invalid, check the debug console
  1882. /// - \c AK_DataAlignmentError if the data pointer is not aligned properly
  1883. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  1884. /// \remarks
  1885. /// - The initialization bank must be loaded first.
  1886. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  1887. /// initialization bank. If you need to load SoundBanks from a different project, you
  1888. /// must first unload ALL banks, including the initialization bank, then load the
  1889. /// initialization bank from the other project, and finally load banks from that project.
  1890. /// - Codecs and plug-ins must be registered before loading banks that use them.
  1891. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  1892. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  1893. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  1894. /// posting the event will fail.
  1895. /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
  1896. /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Device memory allocator.
  1897. /// - Avoid using this function for banks containing a lot of events or structure data: this data will be unpacked into the sound engine heap,
  1898. /// making the supplied bank memory redundant. For event/structure-only banks, prefer LoadBankMemoryCopy().
  1899. /// \sa
  1900. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  1901. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  1902. /// - \ref soundengine_banks
  1903. /// - \ref integrating_elements_plugins
  1904. /// - \ref sdk_bank_training
  1905. AK_EXTERNAPIFUNC( AKRESULT, LoadBankMemoryView )(
  1906. const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is stored in sound engine, memory must remain valid)
  1907. AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
  1908. AkBankID & out_bankID, ///< Returned bank ID
  1909. AkBankType & out_bankType ///< Returned bank type
  1910. );
  1911. /// Loads a bank synchronously (from in-memory data, out-of-place, user bank only).\n
  1912. ///
  1913. /// NOTE: Banks loaded from in-memory with out-of-place data must be unloaded using the standard UnloadBank function
  1914. /// (with no memory pointer). Make sure you are using the correct UnloadBank(...) overload
  1915. ///
  1916. /// Use LoadBankMemoryCopy when you want to manage I/O on your side. Load the bank file
  1917. /// in a buffer and pass its address to the sound engine, the media section of the bank will be copied into newly
  1918. /// allocated memory.
  1919. /// In-memory loading is out-of-place: the buffer can be release as soon as the function returns. The advantage of using this
  1920. /// over the in-place version is that there is no duplication of bank structures.
  1921. /// A bank load request will be posted, and consumed by the Bank Manager thread.
  1922. /// The function returns when the request has been completely processed.
  1923. /// \return
  1924. /// The bank ID, which is stored in the first few bytes of the bank file. You may use this
  1925. /// ID with UnloadBank().
  1926. /// - \c AK_Success: Load or unload successful.
  1927. /// - \c AK_BankAlreadyLoaded: This bank is already loaded, nothing done.
  1928. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  1929. /// - \c AK_BankReadError: I/O error.
  1930. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  1931. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  1932. /// - \c AK_InvalidFile: File specified could not be opened.
  1933. /// - \c AK_NotInitialized if the sound engine was not correctly initialized
  1934. /// - \c AK_InvalidParameter if some parameters are invalid, check the debug console
  1935. /// - \c AK_InvalidBankType if the bank is not a user-defined bank.
  1936. /// - \c AK_DataAlignmentError if the data pointer is not aligned properly
  1937. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  1938. /// \remarks
  1939. /// - The initialization bank must be loaded first.
  1940. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  1941. /// initialization bank. If you need to load SoundBanks from a different project, you
  1942. /// must first unload ALL banks, including the initialization bank, then load the
  1943. /// initialization bank from the other project, and finally load banks from that project.
  1944. /// - Codecs and plug-ins must be registered before loading banks that use them.
  1945. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  1946. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  1947. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  1948. /// posting the event will fail.
  1949. /// \sa
  1950. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  1951. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  1952. /// - \ref soundengine_banks
  1953. /// - \ref integrating_elements_plugins
  1954. /// - \ref sdk_bank_training
  1955. AK_EXTERNAPIFUNC( AKRESULT, LoadBankMemoryCopy )(
  1956. const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is not stored in sound engine, memory can be released after return)
  1957. AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
  1958. AkBankID & out_bankID ///< Returned bank ID
  1959. );
  1960. /// Loads a bank synchronously (from in-memory data, out-of-place, any bank type).\n
  1961. ///
  1962. /// NOTE: Banks loaded from in-memory with out-of-place data must be unloaded using the standard UnloadBank function
  1963. /// (with no memory pointer). Make sure you are using the correct UnloadBank(...) overload
  1964. ///
  1965. /// Use LoadBankMemoryCopy when you want to manage I/O on your side. Load the bank file
  1966. /// in a buffer and pass its address to the sound engine, the media section of the bank will be copied into newly
  1967. /// allocated memory.
  1968. /// In-memory loading is out-of-place: the buffer can be release as soon as the function returns. The advantage of using this
  1969. /// over the in-place version is that there is no duplication of bank structures.
  1970. /// A bank load request will be posted, and consumed by the Bank Manager thread.
  1971. /// The function returns when the request has been completely processed.
  1972. /// \return
  1973. /// The bank ID, which is stored in the first few bytes of the bank file. You may use this
  1974. /// ID with UnloadBank().
  1975. /// - \c AK_Success: Load or unload successful.
  1976. /// - \c AK_BankAlreadyLoaded: This bank is already loaded, nothing done.
  1977. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  1978. /// - \c AK_BankReadError: I/O error.
  1979. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  1980. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  1981. /// - \c AK_InvalidFile: File specified could not be opened.
  1982. /// - \c AK_NotInitialized if the sound engine was not correctly initialized
  1983. /// - \c AK_InvalidParameter if some parameters are invalid, check the debug console
  1984. /// - \c AK_DataAlignmentError if the data pointer is not aligned properly
  1985. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  1986. /// \remarks
  1987. /// - The initialization bank must be loaded first.
  1988. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  1989. /// initialization bank. If you need to load SoundBanks from a different project, you
  1990. /// must first unload ALL banks, including the initialization bank, then load the
  1991. /// initialization bank from the other project, and finally load banks from that project.
  1992. /// - Codecs and plug-ins must be registered before loading banks that use them.
  1993. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  1994. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  1995. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  1996. /// posting the event will fail.
  1997. /// \sa
  1998. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  1999. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2000. /// - \ref soundengine_banks
  2001. /// - \ref integrating_elements_plugins
  2002. /// - \ref sdk_bank_training
  2003. AK_EXTERNAPIFUNC( AKRESULT, LoadBankMemoryCopy )(
  2004. const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is not stored in sound engine, memory can be released after return)
  2005. AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
  2006. AkBankID & out_bankID, ///< Returned bank ID
  2007. AkBankType & out_bankType ///< Returned bank type
  2008. );
  2009. /// Synchronously decodes Vorbis-encoded and Opus-encoded (Software version) media in a SoundBank. The file should already be read in memory before the decode operation. The out_pDecodedBankPtr can then be used with variants of LoadBank that load from in-memory data.
  2010. /// \n
  2011. /// CPU usage, RAM size, storage size and Internet bandwidth must be accounted for when developing a game, especially when it is aimed at mobile platforms. The DecodeBank function makes it possible to decode media at load time instead of decoding them every time they are played.
  2012. AK_EXTERNAPIFUNC( AKRESULT, DecodeBank )(
  2013. const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to decode (pointer is not stored in sound engine, memory can be released after return)
  2014. AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to decode
  2015. AkMemPoolId in_uPoolForDecodedBank, ///< Memory pool to allocate decoded bank into. Specify AK_INVALID_POOL_ID and out_pDecodedBankPtr=NULL to obtain decoded bank size without performing the decode operation. Pass AK_INVALID_POOL_ID and out_pDecodedBankPtr!=NULL to decode bank into specified pointer.
  2016. void * & out_pDecodedBankPtr, ///< Decoded bank memory location.
  2017. AkUInt32 & out_uDecodedBankSize ///< Decoded bank memory size.
  2018. );
  2019. #ifdef AK_SUPPORT_WCHAR
  2020. /// Loads a bank asynchronously (by Unicode string).\n
  2021. /// The bank name is passed to the Stream Manager.
  2022. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  2023. /// A bank load request will be posted to the Bank Manager consumer thread.
  2024. /// The function returns immediately.
  2025. /// \return
  2026. /// AK_Success if the scheduling was successful, AK_Fail otherwise.
  2027. /// Use a callback to be notified when completed, and get the status of the request.
  2028. /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
  2029. /// You may use this ID with UnloadBank().
  2030. /// \remarks
  2031. /// - The initialization bank must be loaded first.
  2032. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  2033. /// initialization bank. If you need to load SoundBanks from a different project, you
  2034. /// must first unload ALL banks, including the initialization bank, then load the
  2035. /// initialization bank from the other project, and finally load banks from that project.
  2036. /// - Codecs and plug-ins must be registered before loading banks that use them.
  2037. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  2038. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  2039. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  2040. /// posting the event will fail.
  2041. /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
  2042. /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
  2043. /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in
  2044. /// your implementation of the Stream Manager (<tt>AK::IAkStreamMgr::CreateStd()</tt>), or in the Low-Level I/O module
  2045. /// (<tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt>) if you use the default Stream Manager's implementation.
  2046. /// - The cookie (in_pCookie) is passed to the Low-Level I/O module for your convenience, in <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt>
  2047. // as AkFileSystemFlags::pCustomParam.
  2048. /// \sa
  2049. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  2050. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2051. /// - AkBankCallbackFunc
  2052. /// - \ref soundengine_banks
  2053. /// - \ref integrating_elements_plugins
  2054. /// - \ref streamingdevicemanager
  2055. /// - \ref streamingmanager_lowlevel
  2056. /// - \ref sdk_bank_training
  2057. AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
  2058. const wchar_t* in_pszString, ///< Name/path of the bank to load
  2059. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2060. void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function, and also to <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt> as AkFileSystemFlags::pCustomParam)
  2061. AkBankID & out_bankID, ///< Returned bank ID
  2062. AkBankType in_bankType = AkBankType_User ///< Type of the bank to load
  2063. );
  2064. #endif //AK_SUPPORT_WCHAR
  2065. /// Loads a bank asynchronously.\n
  2066. /// The bank name is passed to the Stream Manager.
  2067. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  2068. /// A bank load request will be posted to the Bank Manager consumer thread.
  2069. /// The function returns immediately.
  2070. /// \return
  2071. /// - \c AK_Success if the scheduling was successful,
  2072. /// - \c AK_InvalidBankType if in_bankType was invalid
  2073. /// Use a callback to be notified when completed, and get the status of the request.
  2074. /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
  2075. /// You may use this ID with UnloadBank().
  2076. /// \remarks
  2077. /// - The initialization bank must be loaded first.
  2078. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  2079. /// initialization bank. If you need to load SoundBanks from a different project, you
  2080. /// must first unload ALL banks, including the initialization bank, then load the
  2081. /// initialization bank from the other project, and finally load banks from that project.
  2082. /// - Codecs and plug-ins must be registered before loading banks that use them.
  2083. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  2084. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  2085. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  2086. /// posting the Event will fail.
  2087. /// - The sound engine internally calls GetIDFromString(in_pszString) to return the correct bank ID.
  2088. /// Therefore, \c in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
  2089. /// not the name of the file (if you changed it), nor the full path of the file. The path should be resolved in
  2090. /// your implementation of the Stream Manager (<tt>AK::IAkStreamMgr::CreateStd()</tt>), or in the Low-Level I/O module
  2091. /// (<tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt>) if you use the default Stream Manager's implementation.
  2092. /// - The cookie (in_pCookie) is passed to the Low-Level I/O module for your convenience, in <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt>
  2093. // as <tt>AkFileSystemFlags::pCustomParam</tt>.
  2094. /// \sa
  2095. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  2096. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2097. /// - AkBankCallbackFunc
  2098. /// - \ref soundengine_banks
  2099. /// - \ref integrating_elements_plugins
  2100. /// - \ref streamingdevicemanager
  2101. /// - \ref streamingmanager_lowlevel
  2102. /// - \ref sdk_bank_training
  2103. AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
  2104. const char* in_pszString, ///< Name/path of the bank to load
  2105. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2106. void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function, and also to <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt> as AkFileSystemFlags::pCustomParam)
  2107. AkBankID & out_bankID, ///< Returned bank ID
  2108. AkBankType in_bankType = AkBankType_User ///< Type of the bank to load
  2109. );
  2110. /// Loads a bank asynchronously (by ID).\n
  2111. /// \aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
  2112. /// The bank ID is passed to the Stream Manager.
  2113. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  2114. /// A bank load request will be posted to the Bank Manager consumer thread.
  2115. /// The function returns immediately.
  2116. /// \return
  2117. /// - \c AK_Success if the scheduling was successful,
  2118. /// - \c AK_InvalidBankType if in_bankType was invalid
  2119. /// Use a callback to be notified when completed, and get the status of the request.
  2120. /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
  2121. /// You may use this ID with \c UnloadBank().
  2122. /// \remarks
  2123. /// - The initialization bank must be loaded first.
  2124. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  2125. /// initialization bank. If you need to load SoundBanks from a different project, you
  2126. /// must first unload ALL banks, including the initialization bank, then load the
  2127. /// initialization bank from the other project, and finally load banks from that project.
  2128. /// - Codecs and plug-ins must be registered before loading banks that use them.
  2129. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  2130. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  2131. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  2132. /// posting the event will fail.
  2133. /// - The file path should be resolved in your implementation of the Stream Manager, or in the Low-Level I/O module if
  2134. /// you use the default Stream Manager's implementation. The ID overload of <tt>AK::IAkStreamMgr::CreateStd()</tt> and <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt> are called.
  2135. /// - The cookie (in_pCookie) is passed to the Low-Level I/O module for your convenience, in <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt>
  2136. // as AkFileSystemFlags::pCustomParam.
  2137. /// \sa
  2138. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  2139. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2140. /// - AkBankCallbackFunc
  2141. /// - \ref soundengine_banks
  2142. /// - \ref integrating_elements_plugins
  2143. /// - \ref sdk_bank_training
  2144. AK_EXTERNAPIFUNC( AKRESULT, LoadBank )(
  2145. AkBankID in_bankID, ///< Bank ID of the bank to load
  2146. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2147. void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function, and also to <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt> as AkFileSystemFlags::pCustomParam)
  2148. AkBankType in_bankType = AkBankType_User ///< Type of the bank to load
  2149. );
  2150. /// Loads a bank asynchronously (from in-memory data, in-place, user bank only).\n
  2151. ///
  2152. /// IMPORTANT: Banks loaded from memory with in-place data MUST be unloaded using the UnloadBank function
  2153. /// providing the same memory pointer. Make sure you are using the correct UnloadBank(...) overload
  2154. ///
  2155. /// Use LoadBankMemoryView when you want to manage I/O on your side. Load the bank file
  2156. /// in a buffer and pass its address to the sound engine.
  2157. /// In-memory loading is in-place: *** the memory must be valid until the bank is unloaded. ***
  2158. /// A bank load request will be posted to the Bank Manager consumer thread.
  2159. /// The function returns immediately.
  2160. /// \return
  2161. /// - \c AK_Success if the scheduling was successful,
  2162. /// - \c AK_InvalidBankType if the bank is not a user-defined bank.
  2163. /// - \c AK_DataAlignmentError if the data pointer is not aligned properly
  2164. /// Use a callback to be notified when completed, and get the status of the request.
  2165. /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
  2166. /// You may use this ID with UnloadBank().
  2167. /// \remarks
  2168. /// - The initialization bank must be loaded first.
  2169. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  2170. /// initialization bank. If you need to load SoundBanks from a different project, you
  2171. /// must first unload ALL banks, including the initialization bank, then load the
  2172. /// initialization bank from the other project, and finally load banks from that project.
  2173. /// - Codecs and plug-ins must be registered before loading banks that use them.
  2174. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  2175. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  2176. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  2177. /// posting the event will fail.
  2178. /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
  2179. /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Device memory allocator.
  2180. /// - Avoid using this function for banks containing a lot of events or structure data: this data will be unpacked into the sound engine heap,
  2181. /// making the supplied bank memory redundant. For event/structure-only banks, prefer LoadBankMemoryCopy().
  2182. /// \sa
  2183. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  2184. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2185. /// - AkBankCallbackFunc
  2186. /// - \ref soundengine_banks
  2187. /// - \ref integrating_elements_plugins
  2188. /// - \ref sdk_bank_training
  2189. AK_EXTERNAPIFUNC( AKRESULT, LoadBankMemoryView )(
  2190. const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is stored in sound engine, memory must remain valid)
  2191. AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
  2192. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2193. void * in_pCookie, ///< Callback cookie
  2194. AkBankID & out_bankID ///< Returned bank ID
  2195. );
  2196. /// Loads a bank asynchronously (from in-memory data, in-place, any bank type).\n
  2197. ///
  2198. /// IMPORTANT: Banks loaded from memory with in-place data MUST be unloaded using the UnloadBank function
  2199. /// providing the same memory pointer. Make sure you are using the correct UnloadBank(...) overload
  2200. ///
  2201. /// Use LoadBankMemoryView when you want to manage I/O on your side. Load the bank file
  2202. /// in a buffer and pass its address to the sound engine.
  2203. /// In-memory loading is in-place: *** the memory must be valid until the bank is unloaded. ***
  2204. /// A bank load request will be posted to the Bank Manager consumer thread.
  2205. /// The function returns immediately.
  2206. /// \return
  2207. /// - \c AK_Success if the scheduling was successful,
  2208. /// - \c AK_DataAlignmentError if the data pointer is not aligned properly
  2209. /// Use a callback to be notified when completed, and get the status of the request.
  2210. /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
  2211. /// You may use this ID with UnloadBank().
  2212. /// \remarks
  2213. /// - The initialization bank must be loaded first.
  2214. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  2215. /// initialization bank. If you need to load SoundBanks from a different project, you
  2216. /// must first unload ALL banks, including the initialization bank, then load the
  2217. /// initialization bank from the other project, and finally load banks from that project.
  2218. /// - Codecs and plug-ins must be registered before loading banks that use them.
  2219. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  2220. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  2221. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  2222. /// posting the event will fail.
  2223. /// - The memory must be aligned on platform-specific AK_BANK_PLATFORM_DATA_ALIGNMENT bytes (see AkTypes.h).
  2224. /// - (XboxOne only): If the bank may contain XMA in memory data, the memory must be allocated using the Device memory allocator.
  2225. /// - Avoid using this function for banks containing a lot of events or structure data: this data will be unpacked into the sound engine heap,
  2226. /// making the supplied bank memory redundant. For event/structure-only banks, prefer LoadBankMemoryCopy().
  2227. /// \sa
  2228. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  2229. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2230. /// - AkBankCallbackFunc
  2231. /// - \ref soundengine_banks
  2232. /// - \ref integrating_elements_plugins
  2233. /// - \ref sdk_bank_training
  2234. AK_EXTERNAPIFUNC( AKRESULT, LoadBankMemoryView )(
  2235. const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is stored in sound engine, memory must remain valid)
  2236. AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
  2237. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2238. void * in_pCookie, ///< Callback cookie
  2239. AkBankID & out_bankID, ///< Returned bank ID
  2240. AkBankType & out_bankType ///< Returned bank type
  2241. );
  2242. /// Loads a bank asynchronously (from in-memory data, out-of-place, user bank only).\n
  2243. ///
  2244. /// NOTE: Banks loaded from in-memory with out-of-place data must be unloaded using the standard UnloadBank function
  2245. /// (with no memory pointer). Make sure you are using the correct UnloadBank(...) overload
  2246. ///
  2247. /// Use LoadBankMemoryCopy when you want to manage I/O on your side. Load the bank file
  2248. /// in a buffer and pass its address to the sound engine, the media section of the bank will be copied into newly allocated
  2249. /// memory.
  2250. /// In-memory loading is out-of-place: the buffer can be released after the callback function is called. The advantage of using this
  2251. /// over the in-place version is that there is no duplication of bank structures.
  2252. /// A bank load request will be posted to the Bank Manager consumer thread.
  2253. /// The function returns immediately.
  2254. /// \return
  2255. /// - \c AK_Success if the scheduling was successful,
  2256. /// - \c AK_InvalidBankType if the bank is not a user-defined bank.
  2257. /// - \c AK_DataAlignmentError if the data pointer is not aligned properly
  2258. /// Use a callback to be notified when completed, and get the status of the request.
  2259. /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
  2260. /// You may use this ID with UnloadBank().
  2261. /// \remarks
  2262. /// - The initialization bank must be loaded first.
  2263. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  2264. /// initialization bank. If you need to load SoundBanks from a different project, you
  2265. /// must first unload ALL banks, including the initialization bank, then load the
  2266. /// initialization bank from the other project, and finally load banks from that project.
  2267. /// - Codecs and plug-ins must be registered before loading banks that use them.
  2268. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  2269. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  2270. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  2271. /// posting the event will fail.
  2272. /// \sa
  2273. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  2274. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2275. /// - AkBankCallbackFunc
  2276. /// - \ref soundengine_banks
  2277. /// - \ref integrating_elements_plugins
  2278. /// - \ref sdk_bank_training
  2279. AK_EXTERNAPIFUNC(AKRESULT, LoadBankMemoryCopy)(
  2280. const void* in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is not stored in sound engine, memory can be released after callback)
  2281. AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
  2282. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2283. void* in_pCookie, ///< Callback cookie
  2284. AkBankID& out_bankID, ///< Returned bank ID
  2285. AkBankType& out_bankType ///< Returned bank type
  2286. );
  2287. /// Loads a bank asynchronously (from in-memory data, out-of-place, any bank type).\n
  2288. ///
  2289. /// NOTE: Banks loaded from in-memory with out-of-place data must be unloaded using the standard UnloadBank function
  2290. /// (with no memory pointer). Make sure you are using the correct UnloadBank(...) overload
  2291. ///
  2292. /// Use LoadBankMemoryCopy when you want to manage I/O on your side. Load the bank file
  2293. /// in a buffer and pass its address to the sound engine, the media section of the bank will be copied into newly allocated
  2294. /// memory.
  2295. /// In-memory loading is out-of-place: the buffer can be released after the callback function is called. The advantage of using this
  2296. /// over the in-place version is that there is no duplication of bank structures.
  2297. /// A bank load request will be posted to the Bank Manager consumer thread.
  2298. /// The function returns immediately.
  2299. /// \return
  2300. /// - \c AK_Success if the scheduling was successful,
  2301. /// - \c AK_InvalidBankType if in_bankType was invalid
  2302. /// - \c AK_DataAlignmentError if the data pointer is not aligned properly
  2303. /// Use a callback to be notified when completed, and get the status of the request.
  2304. /// The bank ID, which is obtained by hashing the bank name (see GetIDFromString()).
  2305. /// You may use this ID with UnloadBank().
  2306. /// \remarks
  2307. /// - The initialization bank must be loaded first.
  2308. /// - All SoundBanks subsequently loaded must come from the same Wwise project as the
  2309. /// initialization bank. If you need to load SoundBanks from a different project, you
  2310. /// must first unload ALL banks, including the initialization bank, then load the
  2311. /// initialization bank from the other project, and finally load banks from that project.
  2312. /// - Codecs and plug-ins must be registered before loading banks that use them.
  2313. /// - Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
  2314. /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
  2315. /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
  2316. /// posting the event will fail.
  2317. /// \sa
  2318. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  2319. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2320. /// - AkBankCallbackFunc
  2321. /// - \ref soundengine_banks
  2322. /// - \ref integrating_elements_plugins
  2323. /// - \ref sdk_bank_training
  2324. AK_EXTERNAPIFUNC( AKRESULT, LoadBankMemoryCopy )(
  2325. const void * in_pInMemoryBankPtr, ///< Pointer to the in-memory bank to load (pointer is not stored in sound engine, memory can be released after callback)
  2326. AkUInt32 in_uInMemoryBankSize, ///< Size of the in-memory bank to load
  2327. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2328. void * in_pCookie, ///< Callback cookie
  2329. AkBankID & out_bankID, ///< Returned bank ID
  2330. AkBankType & out_bankType ///< Returned bank type
  2331. );
  2332. #ifdef AK_SUPPORT_WCHAR
  2333. /// Unloads a bank synchronously (by Unicode string).\n
  2334. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  2335. /// \return AK_Success if successful, AK_Fail otherwise. AK_Success is returned when the bank was not loaded.
  2336. /// \remarks
  2337. /// - The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID,
  2338. /// then it calls the synchronous version of UnloadBank() by ID.
  2339. /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
  2340. /// not the name of the file (if you changed it), nor the full path of the file.
  2341. /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
  2342. /// This means that streamed sounds or generated sounds will not be stopped.
  2343. /// \sa
  2344. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2345. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2346. /// - \ref soundengine_banks
  2347. AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
  2348. const wchar_t* in_pszString, ///< Name of the bank to unload
  2349. const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL if NULL was passed when loading the bank or if LoadBankMemoryCopy was used to load the bank.
  2350. AkBankType in_bankType = AkBankType_User ///< Type of the bank to unload
  2351. );
  2352. #endif //AK_SUPPORT_WCHAR
  2353. /// Unloads a bank synchronously.\n
  2354. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  2355. /// \return AK_Success if successful, AK_Fail otherwise. AK_Success is returned when the bank was not loaded.
  2356. /// \remarks
  2357. /// - The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID,
  2358. /// then it calls the synchronous version of UnloadBank() by ID.
  2359. /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
  2360. /// not the name of the file (if you changed it), nor the full path of the file.
  2361. /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
  2362. /// This means that streamed sounds or generated sounds will not be stopped.
  2363. /// \sa
  2364. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2365. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2366. /// - \ref soundengine_banks
  2367. AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
  2368. const char* in_pszString, ///< Name of the bank to unload
  2369. const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL if NULL was passed when loading the bank or if LoadBankMemoryCopy was used to load the bank.
  2370. AkBankType in_bankType = AkBankType_User ///< Type of the bank to unload
  2371. );
  2372. /// Unloads a bank synchronously (by ID and memory pointer).\n
  2373. /// \return AK_Success if successful, AK_Fail otherwise. AK_Success is returned when the bank was not loaded.
  2374. /// \remarks
  2375. /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
  2376. /// This means that streamed sounds or generated sounds will not be stopped.
  2377. /// \sa
  2378. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2379. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2380. /// - \ref soundengine_banks
  2381. AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
  2382. AkBankID in_bankID, ///< ID of the bank to unload
  2383. const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL if NULL was passed when loading the bank or if LoadBankMemoryCopy was used to load the bank.
  2384. AkBankType in_bankType = AkBankType_User ///< Type of the bank to unload
  2385. );
  2386. #ifdef AK_SUPPORT_WCHAR
  2387. /// Unloads a bank asynchronously (by Unicode string).\n
  2388. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  2389. /// \return AK_Success if scheduling successful (use a callback to be notified when completed)
  2390. /// \remarks
  2391. /// The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID,
  2392. /// then it calls the synchronous version of UnloadBank() by ID.
  2393. /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
  2394. /// not the name of the file (if you changed it), nor the full path of the file.
  2395. /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
  2396. /// This means that streamed sounds or generated sounds will not be stopped.
  2397. /// \sa
  2398. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2399. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2400. /// - AkBankCallbackFunc
  2401. /// - \ref soundengine_banks
  2402. AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
  2403. const wchar_t* in_pszString, ///< Name of the bank to unload
  2404. const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL if NULL was passed when loading the bank or if LoadBankMemoryCopy was used to load the bank.
  2405. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2406. void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function)
  2407. AkBankType in_bankType = AkBankType_User ///< Type of the bank to unload
  2408. );
  2409. #endif //AK_SUPPORT_WCHAR
  2410. /// Unloads a bank asynchronously.\n
  2411. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  2412. /// \return AK_Success if scheduling successful (use a callback to be notified when completed)
  2413. /// \remarks
  2414. /// The sound engine internally calls GetIDFromString(in_pszString) to retrieve the bank ID,
  2415. /// then it calls the synchronous version of UnloadBank() by ID.
  2416. /// Therefore, in_pszString should be the real name of the SoundBank (with or without the BNK extension - it is trimmed internally),
  2417. /// not the name of the file (if you changed it), nor the full path of the file.
  2418. /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
  2419. /// This means that streamed sounds or generated sounds will not be stopped.
  2420. /// \sa
  2421. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2422. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2423. /// - AkBankCallbackFunc
  2424. /// - \ref soundengine_banks
  2425. AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
  2426. const char* in_pszString, ///< Name of the bank to unload
  2427. const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL if NULL was passed when loading the bank or if LoadBankMemoryCopy was used to load the bank.
  2428. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2429. void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function)
  2430. AkBankType in_bankType = AkBankType_User ///< Type of the bank to unload
  2431. );
  2432. /// Unloads a bank asynchronously (by ID and memory pointer).\n
  2433. /// Refer to \ref soundengine_banks_general for a discussion on using strings and IDs.
  2434. /// \return AK_Success if scheduling successful (use a callback to be notified when completed)
  2435. /// \remarks
  2436. /// - In order to force the memory deallocation of the bank, sounds that use media from this bank will be stopped.
  2437. /// This means that streamed sounds or generated sounds will not be stopped.
  2438. /// \sa
  2439. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2440. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2441. /// - AkBankCallbackFunc
  2442. /// - \ref soundengine_banks
  2443. AK_EXTERNAPIFUNC( AKRESULT, UnloadBank )(
  2444. AkBankID in_bankID, ///< ID of the bank to unload
  2445. const void * in_pInMemoryBankPtr, ///< Memory pointer from where the bank was initially loaded from. (REQUIRED to determine which bank associated to a memory pointer must be unloaded). Pass NULL if NULL was passed when loading the bank or if LoadBankMemoryCopy was used to load the bank.
  2446. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2447. void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function)
  2448. AkBankType in_bankType = AkBankType_User ///< Type of the bank to unload
  2449. );
  2450. /// Cancels all Event callbacks associated with a specific callback cookie specified while loading Banks of preparing Events.\n
  2451. /// \sa
  2452. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2453. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  2454. /// - <tt>AK::SoundEngine::UnloadBank()</tt>
  2455. /// - <tt>AK::SoundEngine::ClearBanks()</tt>
  2456. /// - AkBankCallbackFunc
  2457. AK_EXTERNAPIFUNC( void, CancelBankCallbackCookie )(
  2458. void * in_pCookie ///< Callback cookie to be canceled
  2459. );
  2460. /// Preparation type.
  2461. /// \sa
  2462. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  2463. /// - <tt>AK::SoundEngine::PrepareGameSyncs()</tt>
  2464. /// - <tt>AK::SoundEngine::PrepareBank()</tt>
  2465. enum PreparationType
  2466. {
  2467. Preparation_Load, ///< \c PrepareEvent() will load required information to play the specified event.
  2468. Preparation_Unload, ///< \c PrepareEvent() will unload required information to play the specified event.
  2469. Preparation_LoadAndDecode ///< Vorbis media is decoded when loading, and an uncompressed PCM version is used for playback.
  2470. };
  2471. /// Parameter to be passed to <tt>AK::SoundEngine::PrepareBank()</tt>.
  2472. /// Use AkBankContent_All to load both the media and structural content from the bank.
  2473. /// Use AkBankContent_StructureOnly to load only the structural content, including events, from the bank and then later use the PrepareEvent() functions to load media on demand from loose files on the disk.
  2474. /// \sa
  2475. /// - <tt>AK::SoundEngine::PrepareBank()</tt>
  2476. /// - \ref soundengine_banks_preparingbanks
  2477. enum AkBankContent
  2478. {
  2479. AkBankContent_StructureOnly, ///< Use AkBankContent_StructureOnly to load only the structural content, including Events, and then later use the PrepareEvent() functions to load media on demand from loose files on the disk.
  2480. AkBankContent_All ///< Use AkBankContent_All to load both the media and structural content.
  2481. };
  2482. #ifdef AK_SUPPORT_WCHAR
  2483. /// This function will load the Events, structural content, and optionally, the media content from the SoundBank. If the flag AkBankContent_All is specified, PrepareBank() will load the media content from
  2484. /// the bank; but, as opposed to LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using PrepareBank(), alone or in combination with PrepareEvent(),
  2485. /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
  2486. /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
  2487. /// allowing using PrepareEvent() to load media on demand.
  2488. /// \sa
  2489. /// - \ref soundengine_banks_preparingbanks
  2490. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2491. /// - <tt>AK::SoundEngine::PreparationType</tt>
  2492. /// \remarks
  2493. /// PrepareBank(), when called with the flag AkBankContent_StructureOnly, requires additional calls to PrepareEvent() to load the media for each event. PrepareEvent(), however, is unable to
  2494. /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
  2495. /// for example, a game may have a tool mode that uses PrepareEvent() to load loose files on-demand and, also, a game mode that uses LoadBank() to load the bank in entirety.
  2496. AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
  2497. AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2498. const wchar_t* in_pszString, ///< Name of the bank to Prepare/Unprepare.
  2499. AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All, ///< Structures only (including events) or all content.
  2500. AkBankType in_bankType = AkBankType_User ///< Type of the bank to Prepare/Unprepare.
  2501. );
  2502. #endif //AK_SUPPORT_WCHAR
  2503. /// This function will load the Events, structural content, and optionally, the media content from the SoundBank. If the flag AkBankContent_All is specified, PrepareBank() will load the media content from
  2504. /// the bank; but, as opposed to LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using PrepareBank(), alone or in combination with PrepareEvent(),
  2505. /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
  2506. /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
  2507. /// allowing using PrepareEvent() to load media on demand.
  2508. /// \sa
  2509. /// - \ref soundengine_banks_preparingbanks
  2510. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2511. /// - <tt>AK::SoundEngine::PreparationType</tt>
  2512. /// \remarks
  2513. /// \c PrepareBank(), when called with the flag \c AkBankContent_StructureOnly, requires additional calls to \c PrepareEvent() to load the media for each event. \c PrepareEvent(), however, is unable to
  2514. /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
  2515. /// for example, a game may have a tool mode that uses PrepareEvent() to load loose files on-demand and, also, a game mode that uses \c LoadBank() to load the bank in entirety.
  2516. AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
  2517. AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2518. const char* in_pszString, ///< Name of the bank to Prepare/Unprepare.
  2519. AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All, ///< Structures only (including events) or all content.
  2520. AkBankType in_bankType = AkBankType_User ///< Type of the bank to Prepare/Unprepare.
  2521. );
  2522. /// \n\aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
  2523. /// This function will load the events, structural content, and optionally, the media content from the SoundBank. If the flag AkBankContent_All is specified, PrepareBank() will load the media content from
  2524. /// the bank, but as opposed to LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using PrepareBank(), alone or in combination with PrepareEvent(),
  2525. /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
  2526. /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
  2527. /// allowing using PrepareEvent() to load media on demand.
  2528. /// \sa
  2529. /// - \ref soundengine_banks_preparingbanks
  2530. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2531. /// - <tt>AK::SoundEngine::PreparationType</tt>
  2532. /// \remarks
  2533. /// \c PrepareBank(), when called with the flag AkBankContent_StructureOnly, requires additional calls to PrepareEvent() to load the media for each event. PrepareEvent(), however, is unable to
  2534. /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
  2535. /// for example, a game may have a tool mode that uses PrepareEvent() to load loose files on-demand and, also, a game mode that uses LoadBank() to load the bank in entirety.
  2536. AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
  2537. AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2538. AkBankID in_bankID, ///< ID of the bank to Prepare/Unprepare.
  2539. AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All, ///< Structures only (including events) or all content.
  2540. AkBankType in_bankType = AkBankType_User ///< Type of the bank to Prepare/Unprepare.
  2541. );
  2542. #ifdef AK_SUPPORT_WCHAR
  2543. /// This function will load the Events, structural content, and optionally, the media content from the SoundBank. If the flag AkBankContent_All is specified, PrepareBank() will load the media content from
  2544. /// the bank, but as opposed to LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using PrepareBank(), alone or in combination with PrepareEvent(),
  2545. /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
  2546. /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
  2547. /// allowing using PrepareEvent() to load media on demand.
  2548. /// \sa
  2549. /// - \ref soundengine_banks_preparingbanks
  2550. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2551. /// - <tt>AK::SoundEngine::PreparationType</tt>
  2552. /// \remarks
  2553. /// PrepareBank(), when called with the flag AkBankContent_StructureOnly, requires additional calls to PrepareEvent() to load the media for each event. PrepareEvent(), however, is unable to
  2554. /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
  2555. /// for example, a game may have a tool mode that uses PrepareEvent() to load loose files on-demand and, also, a game mode that uses LoadBank() to load the bank in entirety.
  2556. AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
  2557. AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2558. const wchar_t* in_pszString, ///< Name of the bank to Prepare/Unprepare.
  2559. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2560. void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function)
  2561. AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All, ///< Structures only (including events) or all content.
  2562. AkBankType in_bankType = AkBankType_User ///< Type of the bank to Prepare/Unprepare.
  2563. );
  2564. #endif //AK_SUPPORT_WCHAR
  2565. /// This function will load the events, structural content, and optionally, the media content from the SoundBank. If the flag \c AkBankContent_All is specified, \c PrepareBank() will load the media content from
  2566. /// the bank, but as opposed to \c LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using \c PrepareBank(), alone or in combination with PrepareEvent(),
  2567. /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
  2568. /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
  2569. /// allowing using PrepareEvent() to load media on demand.
  2570. /// \sa
  2571. /// - \ref soundengine_banks_preparingbanks
  2572. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2573. /// - <tt>AK::SoundEngine::PreparationType()</tt>
  2574. /// \remarks
  2575. /// PrepareBank(), when called with the flag AkBankContent_StructureOnly, requires additional calls to PrepareEvent() to load the media for each event. PrepareEvent(), however, is unable to
  2576. /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
  2577. /// for example, a game may have a tool mode that uses PrepareEvent() to load loose files on-demand and, also, a game mode that uses LoadBank() to load the bank in entirety.
  2578. AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
  2579. AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2580. const char* in_pszString, ///< Name of the bank to Prepare/Unprepare.
  2581. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2582. void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function)
  2583. AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All, ///< Structures only (including events) or all content.
  2584. AkBankType in_bankType = AkBankType_User ///< Type of the bank to Prepare/Unprepare.
  2585. );
  2586. /// \n\aknote Requires that the "Use SoundBank names" option be unchecked in the Wwise Project Settings. \endaknote
  2587. /// This function will load the events, structural content, and optionally, the media content from the SoundBank. If the flag AkBankContent_All is specified, \c PrepareBank() will load the media content from
  2588. /// the bank, but as opposed to \c LoadBank(), the media will be loaded one media item at a time instead of in one contiguous memory block. Using \c PrepareBank(), alone or in combination with \c PrepareEvent(),
  2589. /// will prevent in-memory duplication of media at the cost of some memory fragmentation.
  2590. /// Calling this function specifying the flag AkBankContent_StructureOnly will load only the structural part (including events) of this bank,
  2591. /// allowing using PrepareEvent() to load media on demand.
  2592. /// \sa
  2593. /// - \ref soundengine_banks_preparingbanks
  2594. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2595. /// - <tt>AK::SoundEngine::PreparationType()</tt>
  2596. /// \remarks
  2597. /// \c PrepareBank(), when called with the flag AkBankContent_StructureOnly, requires additional calls to PrepareEvent() to load the media for each event. \c PrepareEvent(), however, is unable to
  2598. /// access media content contained within SoundBanks and requires that the media be available as loose files in the file system. This flag may be useful to implement multiple loading configurations;
  2599. /// for example, a game may have a tool mode that uses \c PrepareEvent() to load loose files on-demand and, also, a game mode that uses \c LoadBank() to load the bank in entirety.
  2600. AK_EXTERNAPIFUNC( AKRESULT, PrepareBank )(
  2601. AK::SoundEngine::PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2602. AkBankID in_bankID, ///< ID of the bank to Prepare/Unprepare.
  2603. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2604. void * in_pCookie, ///< Callback cookie (reserved to user, passed to the callback function)
  2605. AK::SoundEngine::AkBankContent in_uFlags = AkBankContent_All, ///< Structures only (including events) or all content.
  2606. AkBankType in_bankType = AkBankType_User ///< Type of the bank to Prepare/Unprepare.
  2607. );
  2608. /// Clear all previously prepared events.\n
  2609. /// \return
  2610. /// - \c AK_Success if successful.
  2611. /// - \c AK_Fail if the sound engine was not correctly initialized or if there is not enough memory to handle the command.
  2612. /// \remarks
  2613. /// The function \c ClearBanks() also clears all prepared events.
  2614. /// \sa
  2615. /// - \c <tt>AK::SoundEngine::PrepareEvent()</tt>
  2616. /// - \c <tt>AK::SoundEngine::ClearBanks()</tt>
  2617. AK_EXTERNAPIFUNC( AKRESULT, ClearPreparedEvents )();
  2618. #ifdef AK_SUPPORT_WCHAR
  2619. /// Prepares or unprepares Events synchronously (by Unicode string).\n
  2620. /// The Events are identified by strings, and converted to IDs internally
  2621. /// (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2622. /// Before invoking \c PrepareEvent(), use \c LoadBank() to explicitly load the SoundBank(s)
  2623. /// that contain the Events and structures. When a request is posted to the
  2624. /// Bank Manager consumer thread, it will resolve all dependencies needed to
  2625. /// successfully post the specified Events and load the required loose media files.
  2626. /// \aknote Before version 2015.1, the required media files could be included
  2627. /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
  2628. /// however,\c PrepareEvent() now only looks for loose media files.
  2629. /// \endaknote
  2630. /// The function returns when the request is completely processed.
  2631. /// \return
  2632. /// - \c AK_Success: Prepare/un-prepare successful.
  2633. /// - \c AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() does not exist.
  2634. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  2635. /// - \c AK_BankReadError: I/O error.
  2636. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  2637. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  2638. /// - \c AK_InvalidFile: File specified could not be opened.
  2639. /// - \c AK_InvalidParameter: Invalid parameter, invalid memory alignment.
  2640. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  2641. /// \remarks
  2642. /// Whenever at least one event fails to be resolved, the actions performed for all
  2643. /// other events are cancelled.
  2644. /// \sa
  2645. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  2646. /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
  2647. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  2648. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2649. /// - \ref soundengine_banks
  2650. /// - \ref sdk_bank_training
  2651. AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
  2652. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2653. const wchar_t** in_ppszString, ///< Array of event names
  2654. AkUInt32 in_uNumEvent ///< Number of events in the array
  2655. );
  2656. #endif //AK_SUPPORT_WCHAR
  2657. /// Prepares or unprepares events synchronously.\n
  2658. /// The Events are identified by strings and converted to IDs internally
  2659. /// (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2660. /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s)
  2661. /// that contain the Events and structures. When a request is posted to the
  2662. /// Bank Manager consumer thread, it will resolve all dependencies needed to
  2663. /// successfully post the specified Events and load the required loose media files.
  2664. /// \aknote Before version 2015.1, the required media files could be included
  2665. /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
  2666. /// however, PrepareEvent() now only looks for loose media files.
  2667. /// \endaknote
  2668. /// The function returns when the request is completely processed.
  2669. /// \return
  2670. /// - \c AK_Success: Prepare/un-prepare successful.
  2671. /// - \c AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() does not exist.
  2672. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  2673. /// - \c AK_BankReadError: I/O error.
  2674. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  2675. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  2676. /// - \c AK_InvalidFile: File specified could not be opened.
  2677. /// - \c AK_InvalidParameter: Invalid parameter, invalid memory alignment.
  2678. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  2679. /// \remarks
  2680. /// Whenever at least one event fails to be resolved, the actions performed for all
  2681. /// other events are cancelled.
  2682. /// \aknote The use of PrepareEvent is incompatible with LoadBank, using in-memory data.
  2683. /// \endaknote
  2684. /// \sa
  2685. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  2686. /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
  2687. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  2688. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2689. /// - \ref soundengine_banks
  2690. /// - \ref sdk_bank_training
  2691. AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
  2692. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2693. const char** in_ppszString, ///< Array of event names
  2694. AkUInt32 in_uNumEvent ///< Number of events in the array
  2695. );
  2696. /// Prepares or unprepares events synchronously (by ID).
  2697. /// The Events are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2698. /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s)
  2699. /// that contain the Events and structures. When a request is posted to the
  2700. /// Bank Manager consumer thread, it will resolve all dependencies needed to
  2701. /// successfully post the specified Events and load the required loose media files.
  2702. /// \aknote Before version 2015.1, the required media files could be included
  2703. /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
  2704. /// however, PrepareEvent() now only looks for loose media files.
  2705. /// \endaknote
  2706. /// The function returns when the request is completely processed.
  2707. /// \return
  2708. /// - \c AK_Success: Prepare/un-prepare successful.
  2709. /// - \c AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() does not exist.
  2710. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  2711. /// - \c AK_BankReadError: I/O error.
  2712. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  2713. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  2714. /// - \c AK_InvalidFile: File specified could not be opened.
  2715. /// - \c AK_InvalidParameter: Invalid parameter, invalid memory alignment.
  2716. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  2717. /// \remarks
  2718. /// Whenever at least one event fails to be resolved, the actions performed for all
  2719. /// other events are cancelled.
  2720. /// \sa
  2721. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  2722. /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
  2723. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  2724. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2725. /// - \ref soundengine_banks
  2726. /// - \ref sdk_bank_training
  2727. AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
  2728. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2729. AkUniqueID* in_pEventID, ///< Array of event IDs
  2730. AkUInt32 in_uNumEvent ///< Number of event IDs in the array
  2731. );
  2732. #ifdef AK_SUPPORT_WCHAR
  2733. /// Prepares or unprepares an event asynchronously (by Unicode string).
  2734. /// The Events are identified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2735. /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s)
  2736. /// that contain the Events and structures. When a request is posted to the
  2737. /// Bank Manager consumer thread, it will resolve all dependencies needed to
  2738. /// successfully post the specified Events and load the required loose media files.
  2739. /// \aknote Before version 2015.1, the required media files could be included
  2740. /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
  2741. /// however, \c PrepareEvent() now only looks for loose media files.
  2742. /// \endaknote
  2743. /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
  2744. /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
  2745. /// \remarks
  2746. /// Whenever at least one Event fails to be resolved, the actions performed for all
  2747. /// other Events are cancelled.
  2748. /// \sa
  2749. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  2750. /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
  2751. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  2752. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2753. /// - AkBankCallbackFunc
  2754. /// - \ref soundengine_banks
  2755. /// - \ref sdk_bank_training
  2756. AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
  2757. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2758. const wchar_t** in_ppszString, ///< Array of event names
  2759. AkUInt32 in_uNumEvent, ///< Number of events in the array
  2760. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2761. void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
  2762. );
  2763. #endif //AK_SUPPORT_WCHAR
  2764. /// Prepares or unprepares an event asynchronously.
  2765. /// The Events are identified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2766. /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s)
  2767. /// that contain the Events and structures. When a request is posted to the
  2768. /// Bank Manager consumer thread, it will resolve all dependencies needed to
  2769. /// successfully post the specified Events and load the required loose media files.
  2770. /// \aknote Before version 2015.1, the required media files could be included
  2771. /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
  2772. /// however, PrepareEvent() now only looks for loose media files.
  2773. /// \endaknote
  2774. /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
  2775. /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
  2776. /// \remarks
  2777. /// Whenever at least one event fails to be resolved, the actions performed for all
  2778. /// other events are cancelled.
  2779. /// \sa
  2780. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  2781. /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
  2782. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  2783. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2784. /// - AkBankCallbackFunc
  2785. /// - \ref soundengine_banks
  2786. /// - \ref sdk_bank_training
  2787. AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
  2788. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2789. const char** in_ppszString, ///< Array of event names
  2790. AkUInt32 in_uNumEvent, ///< Number of events in the array
  2791. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2792. void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
  2793. );
  2794. /// Prepares or unprepares events asynchronously (by ID).\n
  2795. /// The Events are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2796. /// Before invoking PrepareEvent(), use LoadBank() to explicitly load the SoundBank(s)
  2797. /// that contain the Events and structures. When a request is posted to the
  2798. /// Bank Manager consumer thread, it will resolve all dependencies needed to
  2799. /// successfully post the specified Events and load the required loose media files.
  2800. /// \aknote Before version 2015.1, the required media files could be included
  2801. /// in a separate media SoundBank. As described in \ref whatsnew_2015_1_migration,
  2802. /// however, PrepareEvent() now only looks for loose media files.
  2803. /// \endaknote
  2804. /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
  2805. /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
  2806. /// \remarks
  2807. /// Whenever at least one event fails to be resolved, the actions performed for all
  2808. /// other events are cancelled.
  2809. /// \sa
  2810. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  2811. /// - <tt>AK::SoundEngine::ClearPreparedEvents()</tt>
  2812. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  2813. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2814. /// - AkBankCallbackFunc
  2815. /// - \ref soundengine_banks
  2816. /// - \ref sdk_bank_training
  2817. AK_EXTERNAPIFUNC( AKRESULT, PrepareEvent )(
  2818. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2819. AkUniqueID* in_pEventID, ///< Array of event IDs
  2820. AkUInt32 in_uNumEvent, ///< Number of event IDs in the array
  2821. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  2822. void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
  2823. );
  2824. /// Indicates the location of a specific Media ID in memory
  2825. /// The sources are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2826. /// \return AK_Success if operation was successful, AK_InvalidParameter if in_pSourceSettings is invalid or media sizes are 0.
  2827. AK_EXTERNAPIFUNC( AKRESULT, SetMedia )(
  2828. AkSourceSettings * in_pSourceSettings, ///< Array of Source Settings
  2829. AkUInt32 in_uNumSourceSettings ///< Number of Source Settings in the array
  2830. );
  2831. /// Removes the specified source from the list of loaded media, even if this media is already in use.
  2832. /// The sources are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2833. /// \aknote This function is unsafe and deprecated. Use TryUnsetMedia() in its place.
  2834. /// Media that is still in use by the sound engine should not be unset by this function.
  2835. /// If the media is still in use, this function will attempt to forcibly kill all sounds and effects referencing this media,
  2836. /// and then return AK_ResourceInUse. The client should NOT presume that the memory can be safely released at this point.
  2837. /// The moment at which the memory can be safely released is unknown, and the only safe course of action is to keep the memory
  2838. /// alive until the sound engine is terminated.
  2839. /// \endaknote
  2840. /// \return
  2841. /// - \c AK_Success: Operation was successful, and the memory can be released on the client side.
  2842. /// - \c AK_ResourceInUse: Specified media is still in use by the sound engine, the client should not release the memory.
  2843. /// - \c AK_InvalidParameter: in_pSourceSettings is invalid
  2844. AK_EXTERNAPIFUNC( AKRESULT, UnsetMedia )(
  2845. AkSourceSettings * in_pSourceSettings, ///< Array of Source Settings
  2846. AkUInt32 in_uNumSourceSettings ///< Number of Source Settings in the array
  2847. );
  2848. /// Removes the specified source from the list of loaded media, only if this media is not already in use.
  2849. /// The sources are identified by their ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2850. /// \aknote Media that is still in use by the sound engine should not be unset. It is marked for removal to prevent additional use.
  2851. /// If this function returns AK_ResourceInUse, then the client must not release memory for this media.
  2852. /// Instead, the client should retry the TryUnsetMedia operation later with the same parameters and check for AK_Success.
  2853. /// \endaknote
  2854. /// If out_pUnsetResults is not null, then it is assumed to point to an array of result codes of the same length as in_pSourceSettings.
  2855. /// out_pUnsetResults will be filled with either AK_Success or AK_ResourceInUse, indicating which media was still in use and not unset.
  2856. /// \return
  2857. /// - \c AK_Success: Operation was successful, and the memory can be released on the client side.
  2858. /// - \c AK_ResourceInUse: Specified media is still in use by the sound engine, and the media was not unset. Do not release memory, and try again later.
  2859. /// - \c AK_InvalidParameter: in_pSourceSettings is invalid
  2860. AK_EXTERNAPIFUNC(AKRESULT, TryUnsetMedia)(
  2861. AkSourceSettings* in_pSourceSettings, ///< Array of Source Settings
  2862. AkUInt32 in_uNumSourceSettings, ///< Number of Source Settings in the array
  2863. AKRESULT* out_pUnsetResults ///< (optional, can be null) Array of result codes
  2864. );
  2865. #ifdef AK_SUPPORT_WCHAR
  2866. /// Prepares or unprepares game syncs synchronously (by Unicode string).\n
  2867. /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2868. /// The game syncs definitions must already exist in the sound engine by having
  2869. /// explicitly loaded the bank(s) that contain them (with LoadBank()).
  2870. /// A request is posted to the Bank Manager consumer thread. It will resolve all
  2871. /// dependencies needed to successfully set this game sync group to one of the
  2872. /// game sync values specified, and load the required banks, if applicable.
  2873. /// The function returns when the request has been completely processed.
  2874. /// \return
  2875. /// - \c AK_Success: Prepare/un-prepare successful.
  2876. /// - \c AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareGameSyncs() does not exist.
  2877. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  2878. /// - \c AK_BankReadError: I/O error.
  2879. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  2880. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  2881. /// - \c AK_InvalidFile: File specified could not be opened.
  2882. /// - \c AK_InvalidParameter: Invalid parameter, invalid memory alignment.
  2883. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  2884. /// \remarks
  2885. /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation
  2886. /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
  2887. /// so you never need to call this function.
  2888. /// \sa
  2889. /// - \c <tt>AK::SoundEngine::GetIDFromString()</tt>
  2890. /// - \c <tt>AK::SoundEngine::PrepareEvent()</tt>
  2891. /// - \c <tt>AK::SoundEngine::LoadBank()</tt>
  2892. /// - \c AkInitSettings
  2893. /// - \ref soundengine_banks
  2894. /// - \ref sdk_bank_training
  2895. AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
  2896. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2897. AkGroupType in_eGameSyncType, ///< The type of game sync.
  2898. const wchar_t* in_pszGroupName, ///< The State Group Name or the Switch Group Name.
  2899. const wchar_t** in_ppszGameSyncName, ///< The specific ID of the state to either support or not support.
  2900. AkUInt32 in_uNumGameSyncs ///< The number of game sync in the string array.
  2901. );
  2902. #endif //AK_SUPPORT_WCHAR
  2903. /// Prepares or unprepares game syncs synchronously.\n
  2904. /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2905. /// The game syncs definitions must already exist in the sound engine by having
  2906. /// explicitly loaded the bank(s) that contain them (with LoadBank()).
  2907. /// A request is posted to the Bank Manager consumer thread. It will resolve all
  2908. /// dependencies needed to successfully set this game sync group to one of the
  2909. /// game sync values specified, and load the required banks, if applicable.
  2910. /// The function returns when the request has been completely processed.
  2911. /// \return
  2912. /// - \c AK_Success: Prepare/un-prepare successful.
  2913. /// - \c AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareGameSyncs() does not exist.
  2914. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  2915. /// - \c AK_BankReadError: I/O error.
  2916. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  2917. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  2918. /// - \c AK_InvalidFile: File specified could not be opened.
  2919. /// - \c AK_InvalidParameter: Invalid parameter, invalid memory alignment.
  2920. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  2921. /// \remarks
  2922. /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation
  2923. /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
  2924. /// so you never need to call this function.
  2925. /// \sa
  2926. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  2927. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  2928. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2929. /// - AkInitSettings
  2930. /// - \ref soundengine_banks
  2931. /// - \ref sdk_bank_training
  2932. AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
  2933. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2934. AkGroupType in_eGameSyncType, ///< The type of game sync.
  2935. const char* in_pszGroupName, ///< The State Group Name or the Switch Group Name.
  2936. const char** in_ppszGameSyncName, ///< The specific ID of the state to either support or not support.
  2937. AkUInt32 in_uNumGameSyncs ///< The number of game sync in the string array.
  2938. );
  2939. /// Prepares or unprepares game syncs synchronously (by ID).\n
  2940. /// The group and game syncs are specified by ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2941. /// The game syncs definitions must already exist in the sound engine by having
  2942. /// explicitly loaded the bank(s) that contain them (with LoadBank()).
  2943. /// A request is posted to the Bank Manager consumer thread. It will resolve all
  2944. /// dependencies needed to successfully set this game sync group to one of the
  2945. /// game sync values specified, and load the required banks, if applicable.
  2946. /// The function returns when the request has been completely processed.
  2947. /// \return
  2948. /// - \c AK_Success: Prepare/un-prepare successful.
  2949. /// - \c AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareGameSyncs() does not exist.
  2950. /// - \c AK_InsufficientMemory: Insufficient memory to store bank data.
  2951. /// - \c AK_BankReadError: I/O error.
  2952. /// - \c AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
  2953. /// you used to generate the SoundBanks matches that of the SDK you are currently using.
  2954. /// - \c AK_InvalidFile: File specified could not be opened.
  2955. /// - \c AK_InvalidParameter: Invalid parameter, invalid memory alignment.
  2956. /// - \c AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
  2957. /// \remarks
  2958. /// You need to call \c PrepareGameSyncs() if the sound engine was initialized with \c AkInitSettings::bEnableGameSyncPreparation
  2959. /// set to \c true. When set to \c false, the sound engine automatically prepares all game syncs when preparing Events,
  2960. /// so you never need to call this function.
  2961. /// \sa
  2962. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  2963. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  2964. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  2965. /// - AkInitSettings
  2966. /// - \ref soundengine_banks
  2967. /// - \ref sdk_bank_training
  2968. AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
  2969. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2970. AkGroupType in_eGameSyncType, ///< The type of game sync.
  2971. AkUInt32 in_GroupID, ///< The State Group ID or the Switch Group ID.
  2972. AkUInt32* in_paGameSyncID, ///< Array of ID of the game syncs to either support or not support.
  2973. AkUInt32 in_uNumGameSyncs ///< The number of game sync ID in the array.
  2974. );
  2975. #ifdef AK_SUPPORT_WCHAR
  2976. /// Prepares or unprepares game syncs asynchronously (by Unicode string).\n
  2977. /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  2978. /// The game syncs definitions must already exist in the sound engine by having
  2979. /// explicitly loaded the bank(s) that contain them (with <tt>LoadBank()</tt>).
  2980. /// A request is posted to the Bank Manager consumer thread. It will resolve all
  2981. /// dependencies needed to successfully set this game sync group to one of the
  2982. /// game sync values specified, and load the required banks, if applicable.
  2983. /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
  2984. /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
  2985. /// \remarks
  2986. /// You need to call \c PrepareGameSyncs() if the sound engine was initialized with \c AkInitSettings::bEnableGameSyncPreparation
  2987. /// set to \c true. When set to \c false, the sound engine automatically prepares all game syncs when preparing Events,
  2988. /// so you never need to call this function.
  2989. /// \sa
  2990. /// - \c <tt>AK::SoundEngine::GetIDFromString()</tt>
  2991. /// - \c <tt>AK::SoundEngine::PrepareEvent()</tt>
  2992. /// - \c <tt>AK::SoundEngine::LoadBank()</tt>
  2993. /// - \c AkInitSettings
  2994. /// - \c AkBankCallbackFunc
  2995. /// - \ref soundengine_banks
  2996. /// - \ref sdk_bank_training
  2997. AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
  2998. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  2999. AkGroupType in_eGameSyncType, ///< The type of game sync.
  3000. const wchar_t* in_pszGroupName, ///< The State Group Name or the Switch Group Name.
  3001. const wchar_t** in_ppszGameSyncName, ///< The specific ID of the state to either support or not support.
  3002. AkUInt32 in_uNumGameSyncs, ///< The number of game sync in the string array.
  3003. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  3004. void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
  3005. );
  3006. #endif //AK_SUPPORT_WCHAR
  3007. /// Prepares or unprepares game syncs asynchronously.\n
  3008. /// The group and game syncs are specified by string (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  3009. /// The game syncs definitions must already exist in the sound engine by having
  3010. /// explicitly loaded the bank(s) that contain them (with LoadBank()).
  3011. /// A request is posted to the Bank Manager consumer thread. It will resolve all
  3012. /// dependencies needed to successfully set this game sync group to one of the
  3013. /// game sync values specified, and load the required banks, if applicable.
  3014. /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
  3015. /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
  3016. /// \remarks
  3017. /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation
  3018. /// set to true. When set to false, the sound engine automatically prepares all game syncs when preparing events,
  3019. /// so you never need to call this function.
  3020. /// \sa
  3021. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3022. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  3023. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  3024. /// - AkInitSettings
  3025. /// - AkBankCallbackFunc
  3026. /// - \ref soundengine_banks
  3027. /// - \ref sdk_bank_training
  3028. AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
  3029. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  3030. AkGroupType in_eGameSyncType, ///< The type of game sync.
  3031. const char* in_pszGroupName, ///< The State Group Name or the Switch Group Name.
  3032. const char** in_ppszGameSyncName, ///< The specific ID of the state to either support or not support.
  3033. AkUInt32 in_uNumGameSyncs, ///< The number of game sync in the string array.
  3034. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  3035. void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
  3036. );
  3037. /// Prepares or un-prepare game syncs asynchronously (by ID).\n
  3038. /// The group and game syncs are specified by ID (refer to \ref soundengine_banks_general for a discussion on using strings and IDs).
  3039. /// The game syncs definitions must already exist in the sound engine by having
  3040. /// explicitly loaded the bank(s) that contain them (with LoadBank()).
  3041. /// A request is posted to the Bank Manager consumer thread. It will resolve all
  3042. /// dependencies needed to successfully set this game sync group to one of the
  3043. /// game sync values specified, and load the required banks, if applicable.
  3044. /// The function returns immediately. Use a callback to be notified when the request has finished being processed.
  3045. /// \return AK_Success if scheduling is was successful, AK_Fail otherwise.
  3046. /// \remarks
  3047. /// You need to call PrepareGameSyncs() if the sound engine was initialized with AkInitSettings::bEnableGameSyncPreparation
  3048. /// set to true. When set to false, the sound engine automatically prepares all Game Syncs when preparing Events,
  3049. /// so you never need to call this function.
  3050. /// \sa
  3051. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3052. /// - <tt>AK::SoundEngine::PrepareEvent()</tt>
  3053. /// - <tt>AK::SoundEngine::LoadBank()</tt>
  3054. /// - AkInitSettings
  3055. /// - AkBankCallbackFunc
  3056. /// - \ref soundengine_banks
  3057. /// - \ref sdk_bank_training
  3058. AK_EXTERNAPIFUNC( AKRESULT, PrepareGameSyncs )(
  3059. PreparationType in_PreparationType, ///< Preparation type ( Preparation_Load or Preparation_Unload )
  3060. AkGroupType in_eGameSyncType, ///< The type of game sync.
  3061. AkUInt32 in_GroupID, ///< The State Group ID or the Switch Group ID.
  3062. AkUInt32* in_paGameSyncID, ///< Array of ID of the Game Syncs to either support or not support.
  3063. AkUInt32 in_uNumGameSyncs, ///< The number of game sync ID in the array.
  3064. AkBankCallbackFunc in_pfnBankCallback, ///< Callback function
  3065. void * in_pCookie ///< Callback cookie (reserved to user, passed to the callback function)
  3066. );
  3067. //@}
  3068. ////////////////////////////////////////////////////////////////////////
  3069. /// @name Listeners
  3070. //@{
  3071. /// Sets a game object's associated listeners.
  3072. /// All listeners that have previously been added via AddListener or set via SetListeners will be removed and replaced with the listeners in the array in_pListenerGameObjs.
  3073. /// Calling this function will override the default set of listeners and in_emitterGameObj will now reference its own, unique set of listeners.
  3074. /// \return
  3075. /// - \c AK_Success if successful
  3076. /// - \c AK_CommandTooLarge if the number of positions is too large for the command queue. Reduce the number of positions.
  3077. /// \sa
  3078. /// - <tt>AK::SoundEngine::AddListener</tt>
  3079. /// - <tt>AK::SoundEngine::RemoveListener</tt>
  3080. /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
  3081. /// - \ref soundengine_listeners
  3082. AK_EXTERNAPIFUNC( AKRESULT, SetListeners )(
  3083. AkGameObjectID in_emitterGameObj, ///< Emitter game object. Must have been previously registered via RegisterGameObj.
  3084. const AkGameObjectID* in_pListenerGameObjs, ///< Array of listener game object IDs that will be activated for in_emitterGameObj.
  3085. AkUInt32 in_uNumListeners ///< Length of array
  3086. );
  3087. /// Add a single listener to a game object's set of associated listeners.
  3088. /// Any listeners that have previously been added or set via AddListener or SetListeners will remain as listeners and in_listenerGameObj will be added as an additional listener.
  3089. /// Calling this function will override the default set of listeners and in_emitterGameObj will now reference its own, unique set of listeners.
  3090. /// \sa
  3091. /// - <tt>AK::SoundEngine::SetListeners</tt>
  3092. /// - <tt>AK::SoundEngine::RemoveListener</tt>
  3093. /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
  3094. /// - \ref soundengine_listeners
  3095. AK_EXTERNAPIFUNC(AKRESULT, AddListener)(
  3096. AkGameObjectID in_emitterGameObj, ///< Emitter game object. Must have been previously registered via RegisterGameObj.
  3097. AkGameObjectID in_listenerGameObj ///< Listener game object IDs that will be activated for in_emitterGameObj.
  3098. );
  3099. /// Remove a single listener from a game object's set of active listeners.
  3100. /// Calling this function will override the default set of listeners and in_emitterGameObj will now reference its own, unique set of listeners.
  3101. /// \sa
  3102. /// - <tt>AK::SoundEngine::SetListeners</tt>
  3103. /// - <tt>AK::SoundEngine::AddListener</tt>
  3104. /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
  3105. /// - \ref soundengine_listeners
  3106. AK_EXTERNAPIFUNC(AKRESULT, RemoveListener)(
  3107. AkGameObjectID in_emitterGameObj, ///< Emitter game object.
  3108. AkGameObjectID in_listenerGameObj ///< Listener game object IDs that will be deactivated for in_emitterGameObj. Game objects must have been previously registered.
  3109. );
  3110. /// Sets the default set of associated listeners for game objects that have not explicitly overridden their listener sets. Upon registration, all game objects reference the default listener set, until
  3111. /// a call to AddListener, RemoveListener, SetListeners or SetGameObjectOutputBusVolume is made on that game object.
  3112. /// All default listeners that have previously been added via AddDefaultListener or set via SetDefaultListeners will be removed and replaced with the listeners in the array in_pListenerGameObjs.
  3113. /// \return Always returns AK_Success
  3114. /// \sa
  3115. /// - \ref soundengine_listeners
  3116. AK_EXTERNAPIFUNC(AKRESULT, SetDefaultListeners)(
  3117. const AkGameObjectID* in_pListenerObjs, ///< Array of listener game object IDs that will be activated for subsequent registrations. Game objects must have been previously registered.
  3118. AkUInt32 in_uNumListeners ///< Length of array
  3119. );
  3120. /// Add a single listener to the default set of listeners. Upon registration, all game objects reference the default listener set, until
  3121. /// a call to AddListener, RemoveListener, SetListeners or SetGameObjectOutputBusVolume is made on that game object.
  3122. /// \sa
  3123. /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
  3124. /// - <tt>AK::SoundEngine::RemoveDefaultListener</tt>
  3125. /// - \ref soundengine_listeners
  3126. AK_EXTERNAPIFUNC(AKRESULT, AddDefaultListener)(
  3127. AkGameObjectID in_listenerGameObj ///< Listener game object IDs that will be added to the default set of listeners.
  3128. );
  3129. /// Remove a single listener from the default set of listeners. Upon registration, all game objects reference the default listener set, until
  3130. /// a call to AddListener, RemoveListener, SetListeners or SetGameObjectOutputBusVolume is made on that game object.
  3131. /// \sa
  3132. /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
  3133. /// - <tt>AK::SoundEngine::AddDefaultListener</tt>
  3134. /// - \ref soundengine_listeners
  3135. AK_EXTERNAPIFUNC(AKRESULT, RemoveDefaultListener)(
  3136. AkGameObjectID in_listenerGameObj ///< Listener game object IDs that will be removed from the default set of listeners.
  3137. );
  3138. /// Resets the listener associations to the default listener(s), as set by <tt>SetDefaultListeners</tt>. This will also reset per-listener gains that have been set using <tt>SetGameObjectOutputBusVolume</tt>.
  3139. /// \return Always returns AK_Success
  3140. /// \sa
  3141. /// - <tt>AK::SoundEngine::SetListeners</tt>
  3142. /// - <tt>AK::SoundEngine::SetDefaultListeners</tt>
  3143. /// - <tt>AK::SoundEngine::SetGameObjectOutputBusVolume</tt>
  3144. /// - \ref soundengine_listeners
  3145. AK_EXTERNAPIFUNC(AKRESULT, ResetListenersToDefault)(
  3146. AkGameObjectID in_emitterGameObj ///< Emitter game object.
  3147. );
  3148. /// Sets a listener's spatialization parameters. This lets you define listener-specific
  3149. /// volume offsets for each audio channel.
  3150. /// If \c in_bSpatialized is false, only \c in_pVolumeOffsets is used for this listener (3D positions
  3151. /// have no effect on the speaker distribution). Otherwise, \c in_pVolumeOffsets is added to the speaker
  3152. /// distribution computed for this listener.
  3153. /// Use helper functions of \c AK::SpeakerVolumes to manipulate the vector of volume offsets in_pVolumeOffsets.
  3154. ///
  3155. /// \remarks
  3156. /// - If a sound is mixed into a bus that has a different speaker configuration than in_channelConfig,
  3157. /// standard up/downmix rules apply.
  3158. /// - Sounds with 3D Spatialization set to None will not be affected by these parameters.
  3159. /// \return
  3160. /// - \c AK_Success if message was successfully posted to sound engine queue
  3161. /// - \c AK_InvalidFloatValue if the value specified was NaN or Inf
  3162. /// - \c AK_InsufficientMemory if there wasn't enough memory in the message queue
  3163. /// \sa
  3164. /// - \ref soundengine_listeners_spatial
  3165. AK_EXTERNAPIFUNC( AKRESULT, SetListenerSpatialization )(
  3166. AkGameObjectID in_uListenerID, ///< Listener game object ID
  3167. bool in_bSpatialized, ///< Spatialization toggle (True : enable spatialization, False : disable spatialization)
  3168. AkChannelConfig in_channelConfig, ///< Channel configuration associated with volumes in_pVolumeOffsets. Ignored if in_pVolumeOffsets is NULL.
  3169. AK::SpeakerVolumes::VectorPtr in_pVolumeOffsets = NULL ///< Per-speaker volume offset, in dB. See AkSpeakerVolumes.h for how to manipulate this vector.
  3170. );
  3171. //@}
  3172. ////////////////////////////////////////////////////////////////////////
  3173. /// @name Game Syncs
  3174. //@{
  3175. /// Sets the value of a real-time parameter control (by ID).
  3176. /// With this function, you may set a game parameter value with global scope or with game object scope.
  3177. /// Game object scope supersedes global scope. (Once a value is set for the game object scope, it will not be affected by changes to the global scope value.) Game parameter values set with a global scope are applied to all
  3178. /// game objects that not yet registered, or already registered but not overridden with a value with game object scope.
  3179. /// To set a game parameter value with global scope, pass \c AK_INVALID_GAME_OBJECT as the game object.
  3180. /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
  3181. /// value for \c in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
  3182. /// according to the interpolation curve. If you call \c <tt><tt>SetRTPCValue()</tt></tt> with <tt>in_uValueChangeDuration = 0</tt> in the
  3183. /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
  3184. /// function at every game frame, you should not use \c in_uValueChangeDuration, as it would have no effect and it is less efficient.
  3185. /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
  3186. /// \ref soundengine_rtpc_effects for more details on RTPC scope.
  3187. /// \return
  3188. /// - \c AK_Success if the value was successfully set
  3189. /// - \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
  3190. /// - \c AK_InvalidID if in_rtpcID is AK_INVALID_UNIQUE_ID (0)
  3191. /// \sa
  3192. /// - \ref soundengine_rtpc
  3193. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3194. AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValue )(
  3195. AkRtpcID in_rtpcID, ///< ID of the game parameter
  3196. AkRtpcValue in_value, ///< Value to set
  3197. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
  3198. AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
  3199. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
  3200. bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
  3201. );
  3202. #ifdef AK_SUPPORT_WCHAR
  3203. /// Sets the value of a real-time parameter control (by Unicode string name).
  3204. /// With this function, you may set a game parameter value to global scope or to game object scope.
  3205. /// Game object scope supersedes global scope. (Once a value is set for the game object scope, it will not be affected by changes to the global scope value.) Game parameter values set with global scope are applied to all
  3206. /// game objects that not yet registered, or already registered but not overridden with a value with game object scope.
  3207. /// To set a game parameter value with global scope, pass AK_INVALID_GAME_OBJECT as the game object.
  3208. /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
  3209. /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
  3210. /// according to the interpolation curve. If you call SetRTPCValue() with in_uValueChangeDuration = 0 in the
  3211. /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
  3212. /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
  3213. /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
  3214. /// \ref soundengine_rtpc_effects for more details on RTPC scope.
  3215. /// \return
  3216. /// - \c AK_Success if the value was successfully set
  3217. /// - \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
  3218. /// - \c AK_InvalidID if in_pszRtpcName is NULL.
  3219. /// \aknote Strings are case-insensitive. \endaknote
  3220. /// \sa
  3221. /// - \ref soundengine_rtpc
  3222. AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValue )(
  3223. const wchar_t* in_pszRtpcName, ///< Name of the game parameter
  3224. AkRtpcValue in_value, ///< Value to set
  3225. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
  3226. AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
  3227. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
  3228. bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
  3229. );
  3230. #endif //AK_SUPPORT_WCHAR
  3231. /// Sets the value of a real-time parameter control.
  3232. /// With this function, you may set a game parameter value with global scope or with game object scope.
  3233. /// Game object scope supersedes global scope. (Once a value is set for the game object scope, it will not be affected by changes to the global scope value.) Game parameter values set with global scope are applied to all
  3234. /// game objects that not yet registered, or already registered but not overridden with a value with game object scope.
  3235. /// To set a game parameter value with global scope, pass AK_INVALID_GAME_OBJECT as the game object.
  3236. /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
  3237. /// value for \c in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
  3238. /// according to the interpolation curve. If you call SetRTPCValue() with in_uValueChangeDuration = 0 in the
  3239. /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
  3240. /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
  3241. /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
  3242. /// \ref soundengine_rtpc_effects for more details on RTPC scope.
  3243. /// \return
  3244. /// - \c AK_Success if the value was successfully set
  3245. /// - \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
  3246. /// - \c AK_InvalidID if in_pszRtpcName is NULL.
  3247. /// \aknote Strings are case-insensitive. \endaknote
  3248. /// \sa
  3249. /// - \ref soundengine_rtpc
  3250. AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValue )(
  3251. const char* in_pszRtpcName, ///< Name of the game parameter
  3252. AkRtpcValue in_value, ///< Value to set
  3253. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
  3254. AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
  3255. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
  3256. bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
  3257. );
  3258. /// Sets the value of a real-time parameter control (by ID).
  3259. /// With this function, you may set a game parameter value on playing id scope.
  3260. /// Playing id scope supersedes both game object scope and global scope.
  3261. /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
  3262. /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
  3263. /// according to the interpolation curve. If you call SetRTPCValueByPlayingID() with in_uValueChangeDuration = 0 in the
  3264. /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
  3265. /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
  3266. /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
  3267. /// \ref soundengine_rtpc_effects for more details on RTPC scope.
  3268. /// - \c AK_Success if successful
  3269. /// - \c AK_PlayingIDNotFound if in_playingID is not found.
  3270. /// - \c AK_InvalidID if in_pszRtpcName is NULL.
  3271. /// - \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
  3272. /// \sa
  3273. /// - \ref soundengine_rtpc
  3274. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3275. AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValueByPlayingID )(
  3276. AkRtpcID in_rtpcID, ///< ID of the game parameter
  3277. AkRtpcValue in_value, ///< Value to set
  3278. AkPlayingID in_playingID, ///< Associated playing ID
  3279. AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
  3280. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
  3281. bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when, for example, loading a level and you don't want the values to interpolate.
  3282. );
  3283. #ifdef AK_SUPPORT_WCHAR
  3284. /// Sets the value of a real-time parameter control (by Unicode string name).
  3285. /// With this function, you may set a game parameter value on playing ID scope.
  3286. /// Playing id scope supersedes both game object scope and global scope.
  3287. /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
  3288. /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
  3289. /// according to the interpolation curve. If you call SetRTPCValueByPlayingID() with in_uValueChangeDuration = 0 in the
  3290. /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
  3291. /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
  3292. /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
  3293. /// \ref soundengine_rtpc_effects for more details on RTPC scope.
  3294. /// - \c AK_Success if successful
  3295. /// - \c AK_PlayingIDNotFound if in_playingID is not found.
  3296. /// - \c AK_InvalidID if in_pszRtpcName is NULL.
  3297. /// - \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
  3298. /// \sa
  3299. /// - \ref soundengine_rtpc
  3300. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3301. AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValueByPlayingID )(
  3302. const wchar_t* in_pszRtpcName, ///< Name of the game parameter
  3303. AkRtpcValue in_value, ///< Value to set
  3304. AkPlayingID in_playingID, ///< Associated playing ID
  3305. AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
  3306. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
  3307. bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when, for example, loading a level and you don't want the values to interpolate.
  3308. );
  3309. #endif //AK_SUPPORT_WCHAR
  3310. /// Sets the value of a real-time parameter control (by string name).
  3311. /// With this function, you may set a game parameter value on playing id scope.
  3312. /// Playing id scope supersedes both game object scope and global scope.
  3313. /// With this function, you may also change the value of a game parameter over time. To do so, specify a non-zero
  3314. /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
  3315. /// according to the interpolation curve. If you call SetRTPCValueByPlayingID() with in_uValueChangeDuration = 0 in the
  3316. /// middle of an interpolation, the interpolation stops and the new value is set directly. Thus, if you call this
  3317. /// function at every game frame, you should not use in_uValueChangeDuration, as it would have no effect and it is less efficient.
  3318. /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
  3319. /// \ref soundengine_rtpc_effects for more details on RTPC scope.
  3320. /// - \c AK_Success if successful
  3321. /// - \c AK_PlayingIDNotFound if in_playingID is not found.
  3322. /// - \c AK_InvalidID if in_pszRtpcName is NULL.
  3323. /// - \c AK_InvalidFloatValue if the value specified was NaN, Inf or FLT_MAX (3.402823e+38)
  3324. /// \sa
  3325. /// - \ref soundengine_rtpc
  3326. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3327. AK_EXTERNAPIFUNC( AKRESULT, SetRTPCValueByPlayingID )(
  3328. const char* in_pszRtpcName, ///< Name of the game parameter
  3329. AkRtpcValue in_value, ///< Value to set
  3330. AkPlayingID in_playingID, ///< Associated playing ID
  3331. AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
  3332. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
  3333. bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
  3334. );
  3335. /// Resets the value of the game parameter to its default value, as specified in the Wwise project.
  3336. /// With this function, you may reset a game parameter to its default value with global scope or with game object scope.
  3337. /// Game object scope supersedes global scope. Game parameter values reset with global scope are applied to all
  3338. /// game objects that were not overridden with a value with game object scope.
  3339. /// To reset a game parameter value with global scope, pass AK_INVALID_GAME_OBJECT as the game object.
  3340. /// With this function, you may also reset the value of a game parameter over time. To do so, specify a non-zero
  3341. /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
  3342. /// according to the interpolation curve. If you call SetRTPCValue() or ResetRTPCValue() with in_uValueChangeDuration = 0 in the
  3343. /// middle of an interpolation, the interpolation stops and the new value is set directly.
  3344. /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
  3345. /// \ref soundengine_rtpc_effects for more details on RTPC scope.
  3346. /// \return
  3347. /// - \c AK_Success when successful
  3348. /// - \c AK_InvalidID if in_rtpcID is AK_INVALID_UNIQUE_ID (0)
  3349. /// \sa
  3350. /// - \ref soundengine_rtpc
  3351. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3352. /// - <tt>AK::SoundEngine::SetRTPCValue()</tt>
  3353. AK_EXTERNAPIFUNC( AKRESULT, ResetRTPCValue )(
  3354. AkRtpcID in_rtpcID, ///< ID of the game parameter
  3355. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
  3356. AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards its default value
  3357. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
  3358. bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
  3359. );
  3360. #ifdef AK_SUPPORT_WCHAR
  3361. /// Resets the value of the game parameter to its default value, as specified in the Wwise project.
  3362. /// With this function, you may reset a game parameter to its default value with global scope or with game object scope.
  3363. /// Game object scope supersedes global scope. Game parameter values reset with global scope are applied to all
  3364. /// game objects that were not overridden with a value with game object scope.
  3365. /// To reset a game parameter value with global scope, pass AK_INVALID_GAME_OBJECT as the game object.
  3366. /// With this function, you may also reset the value of a game parameter over time. To do so, specify a non-zero
  3367. /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
  3368. /// according to the interpolation curve. If you call SetRTPCValue() or ResetRTPCValue() with in_uValueChangeDuration = 0 in the
  3369. /// middle of an interpolation, the interpolation stops and the new value is set directly.
  3370. /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
  3371. /// \ref soundengine_rtpc_effects for more details on RTPC scope.
  3372. /// \return
  3373. /// - \c AK_Success if successful
  3374. /// - \c AK_InvalidID if in_pszParamName is NULL.
  3375. /// \aknote Strings are case-insensitive. \endaknote
  3376. /// \sa
  3377. /// - \ref soundengine_rtpc
  3378. /// - <tt>AK::SoundEngine::SetRTPCValue()</tt>
  3379. AK_EXTERNAPIFUNC( AKRESULT, ResetRTPCValue )(
  3380. const wchar_t* in_pszRtpcName, ///< Name of the game parameter
  3381. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
  3382. AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards its default value
  3383. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
  3384. bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
  3385. );
  3386. #endif //AK_SUPPORT_WCHAR
  3387. /// Resets the value of the game parameter to its default value, as specified in the Wwise project.
  3388. /// With this function, you may reset a game parameter to its default value with global scope or with game object scope.
  3389. /// Game object scope supersedes global scope. Game parameter values reset with global scope are applied to all
  3390. /// game objects that were not overridden with a value with game object scope.
  3391. /// To reset a game parameter value with global scope, pass AK_INVALID_GAME_OBJECT as the game object.
  3392. /// With this function, you may also reset the value of a game parameter over time. To do so, specify a non-zero
  3393. /// value for in_uValueChangeDuration. At each audio frame, the game parameter value will be updated internally
  3394. /// according to the interpolation curve. If you call SetRTPCValue() or ResetRTPCValue() with in_uValueChangeDuration = 0 in the
  3395. /// middle of an interpolation, the interpolation stops and the new value is set directly.
  3396. /// Refer to \ref soundengine_rtpc_pergameobject, \ref soundengine_rtpc_buses and
  3397. /// \ref soundengine_rtpc_effects for more details on RTPC scope.
  3398. /// \return
  3399. /// - \c AK_Success if successful
  3400. /// - \c AK_InvalidID if in_pszParamName is NULL.
  3401. /// \aknote Strings are case-insensitive. \endaknote
  3402. /// \sa
  3403. /// - \ref soundengine_rtpc
  3404. /// - <tt>AK::SoundEngine::SetRTPCValue()</tt>
  3405. AK_EXTERNAPIFUNC( AKRESULT, ResetRTPCValue )(
  3406. const char* in_pszRtpcName, ///< Name of the game parameter
  3407. AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
  3408. AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards its default value
  3409. AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
  3410. bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
  3411. );
  3412. /// Sets the State of a Switch Group (by IDs).
  3413. /// \return Always returns AK_Success
  3414. /// \sa
  3415. /// - \ref soundengine_switch
  3416. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3417. AK_EXTERNAPIFUNC( AKRESULT, SetSwitch )(
  3418. AkSwitchGroupID in_switchGroup, ///< ID of the Switch Group
  3419. AkSwitchStateID in_switchState, ///< ID of the Switch
  3420. AkGameObjectID in_gameObjectID ///< Associated game object ID
  3421. );
  3422. #ifdef AK_SUPPORT_WCHAR
  3423. /// Sets the State of a Switch Group (by Unicode string names).
  3424. /// \return
  3425. /// - \c AK_Success if successful
  3426. /// - \c AK_InvalidID if the switch or Switch Group name was not resolved to an existing ID\n
  3427. /// Make sure that the banks were generated with the "include string" option.
  3428. /// \aknote Strings are case-insensitive. \endaknote
  3429. /// \sa
  3430. /// - \ref soundengine_switch
  3431. AK_EXTERNAPIFUNC( AKRESULT, SetSwitch )(
  3432. const wchar_t* in_pszSwitchGroup, ///< Name of the Switch Group
  3433. const wchar_t* in_pszSwitchState, ///< Name of the Switch
  3434. AkGameObjectID in_gameObjectID ///< Associated game object ID
  3435. );
  3436. #endif //AK_SUPPORT_WCHAR
  3437. /// Sets the state of a Switch Group.
  3438. /// \return
  3439. /// - \c AK_Success if successful
  3440. /// - \c AK_InvalidID if the switch or Switch Group name was not resolved to an existing ID\n
  3441. /// Make sure that the banks were generated with the "include string" option.
  3442. /// \aknote Strings are case-insensitive. \endaknote
  3443. /// \sa
  3444. /// - \ref soundengine_switch
  3445. AK_EXTERNAPIFUNC( AKRESULT, SetSwitch )(
  3446. const char* in_pszSwitchGroup, ///< Name of the Switch Group
  3447. const char* in_pszSwitchState, ///< Name of the Switch
  3448. AkGameObjectID in_gameObjectID ///< Associated game object ID
  3449. );
  3450. /// Post the specified trigger (by IDs).
  3451. /// \return Always returns AK_Success
  3452. /// \sa
  3453. /// - \ref soundengine_triggers
  3454. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3455. AK_EXTERNAPIFUNC( AKRESULT, PostTrigger )(
  3456. AkTriggerID in_triggerID, ///< ID of the trigger
  3457. AkGameObjectID in_gameObjectID ///< Associated game object ID
  3458. );
  3459. #ifdef AK_SUPPORT_WCHAR
  3460. /// Posts the specified trigger (by Unicode string name).
  3461. /// \return
  3462. /// - \c AK_Success if successful
  3463. /// - \c AK_InvalidID if the trigger name was null
  3464. /// Make sure that the banks were generated with the "include string" option.
  3465. /// \aknote Strings are case-insensitive. \endaknote
  3466. /// \sa
  3467. /// - \ref soundengine_triggers
  3468. AK_EXTERNAPIFUNC( AKRESULT, PostTrigger )(
  3469. const wchar_t* in_pszTrigger, ///< Name of the trigger
  3470. AkGameObjectID in_gameObjectID ///< Associated game object ID
  3471. );
  3472. #endif //AK_SUPPORT_WCHAR
  3473. /// Posts the specified trigger.
  3474. /// \return
  3475. /// - \c AK_Success if successful
  3476. /// - \c AK_InvalidID if the trigger name was null
  3477. /// Make sure that the banks were generated with the "include string" option.
  3478. /// \aknote Strings are case-insensitive. \endaknote
  3479. /// \sa
  3480. /// - \ref soundengine_triggers
  3481. AK_EXTERNAPIFUNC( AKRESULT, PostTrigger )(
  3482. const char* in_pszTrigger, ///< Name of the trigger
  3483. AkGameObjectID in_gameObjectID ///< Associated game object ID
  3484. );
  3485. /// Sets the state of a State Group (by IDs).
  3486. /// \return Always returns AK_Success
  3487. /// \sa
  3488. /// - \ref soundengine_states
  3489. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3490. AK_EXTERNAPIFUNC( AKRESULT, SetState )(
  3491. AkStateGroupID in_stateGroup, ///< ID of the State Group
  3492. AkStateID in_state ///< ID of the state
  3493. );
  3494. #ifdef AK_SUPPORT_WCHAR
  3495. /// Sets the state of a State Group (by Unicode string names).
  3496. /// \return
  3497. /// - \c AK_Success if successful
  3498. /// - \c AK_InvalidID if the state or State Group name was null
  3499. /// Make sure that the banks were generated with the "include string" option.
  3500. /// \aknote Strings are case-insensitive. \endaknote
  3501. /// \sa
  3502. /// - \ref soundengine_states
  3503. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3504. AK_EXTERNAPIFUNC( AKRESULT, SetState )(
  3505. const wchar_t* in_pszStateGroup, ///< Name of the State Group
  3506. const wchar_t* in_pszState ///< Name of the state
  3507. );
  3508. #endif //AK_SUPPORT_WCHAR
  3509. /// Sets the state of a State Group.
  3510. /// \return
  3511. /// - \c AK_Success if successful
  3512. /// - \c AK_InvalidID if the state or State Group name was null
  3513. /// Make sure that the banks were generated with the "include string" option.
  3514. /// \aknote Strings are case-insensitive. \endaknote
  3515. /// \sa
  3516. /// - \ref soundengine_states
  3517. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3518. AK_EXTERNAPIFUNC( AKRESULT, SetState )(
  3519. const char* in_pszStateGroup, ///< Name of the State Group
  3520. const char* in_pszState ///< Name of the state
  3521. );
  3522. //@}
  3523. ////////////////////////////////////////////////////////////////////////
  3524. /// @name Environments
  3525. //@{
  3526. /// Sets the Auxiliary Busses to route the specified game object
  3527. /// To clear the game object's auxiliary sends, \c in_uNumSendValues must be 0.
  3528. /// \sa
  3529. /// - \ref soundengine_environments
  3530. /// - \ref soundengine_environments_dynamic_aux_bus_routing
  3531. /// - \ref soundengine_environments_id_vs_string
  3532. /// - <tt>AK::SoundEngine::GetIDFromString()</tt>
  3533. /// \return
  3534. /// - \c AK_Success if successful
  3535. /// - \c AK_InvalidParameter if a duplicated environment is found in the array
  3536. /// - \c AK_InvalidFloatValue if the value specified was NaN or Inf
  3537. AK_EXTERNAPIFUNC( AKRESULT, SetGameObjectAuxSendValues )(
  3538. AkGameObjectID in_gameObjectID, ///< Associated game object ID
  3539. AkAuxSendValue* in_aAuxSendValues, ///< Variable-size array of AkAuxSendValue structures
  3540. ///< (it may be NULL if no environment must be set)
  3541. AkUInt32 in_uNumSendValues ///< The number of auxiliary busses at the pointer's address
  3542. ///< (it must be 0 if no environment is set)
  3543. );
  3544. /// Registers a callback to allow the game to modify or override the volume to be applied at the output of an audio bus.
  3545. /// The callback must be registered once per bus ID.
  3546. /// Call with <tt>in_pfnCallback = NULL</tt> to unregister.
  3547. /// \aknote The bus in_busID needs to be a mixing bus.\endaknote
  3548. /// \aknote The callback function will not be called for the Master Audio Bus, since the output of this bus is not a bus, but is instead an Audio Device.\endaknote
  3549. /// \sa
  3550. /// - \ref goingfurther_speakermatrixcallback
  3551. /// - \ref soundengine_environments
  3552. /// - AkSpeakerVolumeMatrixCallbackInfo
  3553. /// - <tt>AK::IAkMixerInputContext</tt>
  3554. /// - <tt>AK::IAkMixerPluginContext</tt>
  3555. /// \return
  3556. /// - \c AK_Success if successful
  3557. /// - \c AK_IDNotFound if the bus is not found
  3558. /// - \c AK_NotInitialized if the sound engine is not initialized
  3559. /// - \c AK_InsufficientMemory if there is not enough memory to complete the operation
  3560. AK_EXTERNAPIFUNC( AKRESULT, RegisterBusVolumeCallback )(
  3561. AkUniqueID in_busID, ///< Bus ID, as obtained by GetIDFromString( bus_name ).
  3562. AkBusCallbackFunc in_pfnCallback, ///< Callback function.
  3563. void* in_pCookie = NULL ///< User cookie.
  3564. );
  3565. /// Registers a callback to be called to allow the game to access metering data from any mixing bus. You may use this to monitor loudness at any point of the mixing hierarchy
  3566. /// by accessing the peak, RMS, True Peak and K-weighted power (according to loudness standard ITU BS.1770). See \ref goingfurther_speakermatrixcallback for an example.
  3567. /// The callback must be registered once per bus ID.
  3568. /// Call with in_pfnCallback = NULL to unregister.
  3569. /// \aknote The bus in_busID needs to be a mixing bus.\endaknote
  3570. /// \sa
  3571. /// - \ref goingfurther_speakermatrixcallback
  3572. /// - AkBusMeteringCallbackFunc
  3573. /// - <tt>AK::AkMetering</tt>
  3574. /// \return
  3575. /// - \c AK_Success if successful
  3576. /// - \c AK_IDNotFound if the bus is not found
  3577. /// - \c AK_NotInitialized if the sound engine is not initialized
  3578. /// - \c AK_InsufficientMemory if there is not enough memory to complete the operation
  3579. AK_EXTERNAPIFUNC( AKRESULT, RegisterBusMeteringCallback )(
  3580. AkUniqueID in_busID, ///< Bus ID, as obtained by GetIDFromString( bus_name ).
  3581. AkBusMeteringCallbackFunc in_pfnCallback, ///< Callback function.
  3582. AkMeteringFlags in_eMeteringFlags, ///< Metering flags.
  3583. void* in_pCookie = NULL ///< User cookie.
  3584. );
  3585. /// Registers a callback to be called to allow the game to access metering data from any output device. You may use this to monitor loudness as sound leaves the Wwise sound engine
  3586. /// by accessing the peak, RMS, True Peak and K-weighted power (according to loudness standard ITU BS.1770). See \ref goingfurther_speakermatrixcallback for an example.
  3587. /// The callback must be registered once per device shareset ID.
  3588. /// Call with in_pfnCallback = NULL to unregister.
  3589. /// \sa
  3590. /// - \ref goingfurther_speakermatrixcallback
  3591. /// - AkOutputDeviceMeteringCallbackFunc
  3592. /// - <tt>AK::AkMetering</tt>
  3593. /// \return
  3594. /// - \c AK_Success if successful
  3595. /// - \c AK_DeviceNotFound if the device is not found
  3596. /// - \c AK_NotInitialized if the sound engine is not initialized
  3597. /// - \c AK_InsufficientMemory if there is not enough memory to complete the operation
  3598. AK_EXTERNAPIFUNC( AKRESULT, RegisterOutputDeviceMeteringCallback )(
  3599. AkOutputDeviceID in_idOutput, ///< Output ID, as returned from AddOutput or GetOutputID. You can pass 0 for the main (default) output
  3600. AkOutputDeviceMeteringCallbackFunc in_pfnCallback, ///< Callback function.
  3601. AkMeteringFlags in_eMeteringFlags, ///< Metering flags.
  3602. void* in_pCookie = NULL ///< User cookie.
  3603. );
  3604. /// Sets the Output Bus Volume (direct) to be used for the specified game object.
  3605. /// The control value is a number ranging from 0.0f to 1.0f.
  3606. /// Output Bus Volumes are stored per listener association, so calling this function will override the default set of listeners. The game object in_emitterObjID will now reference its own set of listeners which will
  3607. /// be the same as the old set of listeners, but with the new associated gain. Future changes to the default listener set will not be picked up by this game object unless ResetListenersToDefault() is called.
  3608. /// \sa
  3609. /// - \ref AK::SoundEngine::ResetListenersToDefault
  3610. /// - \ref soundengine_environments
  3611. /// - \ref soundengine_environments_setting_dry_environment
  3612. /// - \ref soundengine_environments_id_vs_string
  3613. /// \return
  3614. /// - \c AK_Success when successful
  3615. /// - \c AK_InvalidFloatValue if the value specified was NaN or Inf
  3616. AK_EXTERNAPIFUNC( AKRESULT, SetGameObjectOutputBusVolume )(
  3617. AkGameObjectID in_emitterObjID, ///< Associated emitter game object ID
  3618. AkGameObjectID in_listenerObjID, ///< Associated listener game object ID. Pass AK_INVALID_GAME_OBJECT to set the Output Bus Volume for all connected listeners.
  3619. AkReal32 in_fControlValue ///< A multiplier in the range [0.0f:16.0f] ( -∞ dB to +24 dB).
  3620. ///< A value greater than 1.0f will amplify the sound.
  3621. );
  3622. /// Sets an Effect ShareSet at the specified audio node and Effect slot index.
  3623. /// \aknote
  3624. /// Replacing effects is preferably done through a Set Effect Event Action.
  3625. /// \endaknote
  3626. /// The target node cannot be a Bus, to set effects on a bus, use SetBusEffect() instead.
  3627. /// \aknote The option "Override Parent" in
  3628. /// the Effect section in Wwise must be enabled for this node, otherwise the parent's effect will
  3629. /// still be the one in use and the call to SetActorMixerEffect will have no impact.
  3630. /// \endaknote
  3631. /// \return Always returns AK_Success
  3632. AK_EXTERNAPIFUNC( AKRESULT, SetActorMixerEffect )(
  3633. AkUniqueID in_audioNodeID, ///< Can be a member of the Actor-Mixer or Interactive Music Hierarchy (not a bus).
  3634. AkUInt32 in_uFXIndex, ///< Effect slot index (0-3)
  3635. AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to clear the effect slot
  3636. );
  3637. /// Sets an Effect ShareSet at the specified bus and Effect slot index.
  3638. /// \aknote
  3639. /// Replacing effects is preferably done through a Set Effect Event Action.
  3640. /// \endaknote
  3641. /// The Bus can either be an Audio Bus or an Auxiliary Bus.
  3642. /// This adds a reference on the audio node to an existing ShareSet.
  3643. /// \aknote This function has unspecified behavior when adding an Effect to a currently playing
  3644. /// Bus which does not have any Effects, or removing the last Effect on a currently playing bus.
  3645. /// \endaknote
  3646. /// \aknote This function will replace existing Effects on the node. If the target node is not at
  3647. /// the top of the hierarchy and is in the actor-mixer hierarchy, the option "Override Parent" in
  3648. /// the Effect section in Wwise must be enabled for this node, otherwise the parent's Effect will
  3649. /// still be the one in use and the call to SetBusEffect will have no impact.
  3650. /// \endaknote
  3651. /// \return
  3652. /// - \c AK_Success when successfully posted.
  3653. /// - \c AK_IDNotFound if the Bus isn't found by in_audioNodeID
  3654. /// - \c AK_InvalidParameter if in_uFXIndex isn't in range
  3655. AK_EXTERNAPIFUNC( AKRESULT, SetBusEffect )(
  3656. AkUniqueID in_audioNodeID, ///< Bus Short ID.
  3657. AkUInt32 in_uFXIndex, ///< Effect slot index (0-3)
  3658. AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to clear the Effect slot
  3659. );
  3660. #ifdef AK_SUPPORT_WCHAR
  3661. /// Sets an Effect ShareSet at the specified Bus and Effect slot index.
  3662. /// \aknote
  3663. /// Replacing effects is preferably done through a Set Effect Event Action.
  3664. /// \endaknote
  3665. /// The Bus can either be an Audio Bus or an Auxiliary Bus.
  3666. /// This adds a reference on the audio node to an existing ShareSet.
  3667. /// \aknote This function has unspecified behavior when adding an Effect to a currently playing
  3668. /// bus which does not have any Effects, or removing the last Effect on a currently playing Bus.
  3669. /// \endaknote
  3670. /// \aknote This function will replace existing Effects on the node. If the target node is not at
  3671. /// the top of the hierarchy and is in the Actor-Mixer Hierarchy, the option "Override Parent" in
  3672. /// the Effect section in Wwise must be enabled for this node, otherwise the parent's Effect will
  3673. /// still be the one in use and the call to \c SetBusEffect will have no impact.
  3674. /// \endaknote
  3675. /// \returns
  3676. /// - \c AK_Success when successfully posted.
  3677. /// - \c AK_IDNotFound if the Bus name doesn't point to a valid bus.
  3678. /// - \c AK_InvalidID if in_pszBusName is null
  3679. /// - \c AK_InvalidParameter if in_uFXIndex isn't in range or in_pszBusName is null
  3680. AK_EXTERNAPIFUNC( AKRESULT, SetBusEffect )(
  3681. const wchar_t* in_pszBusName, ///< Bus name
  3682. AkUInt32 in_uFXIndex, ///< Effect slot index (0-3)
  3683. AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to clear the effect slot
  3684. );
  3685. #endif //AK_SUPPORT_WCHAR
  3686. /// Sets an Effect ShareSet at the specified Bus and Effect slot index.
  3687. /// \aknote
  3688. /// Replacing effects is preferably done through a Set Effect Event Action.
  3689. /// \endaknote
  3690. /// The Bus can either be an Audio Bus or an Auxiliary Bus.
  3691. /// This adds a reference on the audio node to an existing ShareSet.
  3692. /// \aknote This function has unspecified behavior when adding an Effect to a currently playing
  3693. /// Bus which does not have any effects, or removing the last Effect on a currently playing bus.
  3694. /// \endaknote
  3695. /// \aknote Make sure the new effect shareset is included in a soundbank, and that sound bank is loaded. Otherwise you will see errors in the Capture Log.\endaknote
  3696. /// \aknote This function will replace existing Effects on the node. If the target node is not at
  3697. /// the top of the hierarchy and is in the Actor-Mixer Hierarchy, the option "Override Parent" in
  3698. /// the Effect section in Wwise must be enabled for this node, otherwise the parent's Effect will
  3699. /// still be the one in use and the call to SetBusEffect will have no impact.
  3700. /// \endaknote
  3701. /// \returns
  3702. /// - \c AK_Success when successfully posted.
  3703. /// - \c AK_IDNotFound if the Bus name doesn't point to a valid bus.
  3704. /// - \c AK_InvalidParameter if in_uFXIndex isn't in range
  3705. /// - \c AK_InvalidID if in_pszBusName is null
  3706. AK_EXTERNAPIFUNC( AKRESULT, SetBusEffect )(
  3707. const char* in_pszBusName, ///< Bus name
  3708. AkUInt32 in_uFXIndex, ///< Effect slot index (0-3)
  3709. AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to clear the effect slot
  3710. );
  3711. /// Sets an audio device effect shareset on the specified output device and effect slot index.
  3712. /// \aknote
  3713. /// Replacing effects is preferably done through a Set Effect Event Action.
  3714. /// \endaknote
  3715. /// \aknote Make sure the new effect shareset is included in a soundbank, and that sound bank is loaded. Otherwise you will see errors in the Capture Log.\endaknote
  3716. /// \aknote This function will replace existing effects of the audio device shareset. \endaknote
  3717. /// \aknote Audio device effects support is limited to one shareset per plug-in type at any time. \endaknote
  3718. /// \aknote Errors are reported in the Wwise Capture Log if the effect cannot be set on the output device. \endaknote
  3719. /// \returns Always returns AK_Success
  3720. AK_EXTERNAPIFUNC(AKRESULT, SetOutputDeviceEffect)(
  3721. AkOutputDeviceID in_outputDeviceID, ///< Output ID, as returned from AddOutput or GetOutputID. Most of the time this should be 0 to designate the main (default) output
  3722. AkUInt32 in_uFXIndex, ///< Effect slot index (0-3)
  3723. AkUniqueID in_FXShareSetID ///< Effect ShareSet ID
  3724. );
  3725. /// Sets a Mixer ShareSet at the specified bus.
  3726. /// \aknote This function has unspecified behavior when adding a mixer to a currently playing
  3727. /// Bus which does not have any Effects or mixer, or removing the last mixer on a currently playing Bus.
  3728. /// \endaknote
  3729. /// \aknote Make sure the new mixer shareset is included in a soundbank, and that sound bank is loaded. Otherwise you will see errors in the Capture Log.\endaknote
  3730. /// \aknote This function will replace existing mixers on the node.
  3731. /// \endaknote
  3732. /// \return Always returns AK_Success
  3733. AK_EXTERNAPIFUNC( AKRESULT, SetMixer )(
  3734. AkUniqueID in_audioNodeID, ///< Bus Short ID.
  3735. AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to remove.
  3736. );
  3737. #ifdef AK_SUPPORT_WCHAR
  3738. /// Sets a Mixer ShareSet at the specified bus.
  3739. /// \aknote This function has unspecified behavior when adding a mixer to a currently playing
  3740. /// bus which does not have any effects nor mixer, or removing the last mixer on a currently playing bus.
  3741. /// \endaknote
  3742. /// \aknote Make sure the new mixer shareset is included in a soundbank, and that sound bank is loaded. Otherwise you will see errors in the Capture Log.\endaknote
  3743. /// \aknote This function will replace existing mixers on the node.
  3744. /// \endaknote
  3745. /// \returns
  3746. /// - \c AK_Success when successful
  3747. /// - \c AK_InvalidID if in_pszBusName is null
  3748. AK_EXTERNAPIFUNC( AKRESULT, SetMixer )(
  3749. const wchar_t* in_pszBusName, ///< Bus name
  3750. AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to remove.
  3751. );
  3752. #endif //AK_SUPPORT_WCHAR
  3753. /// Sets a Mixer ShareSet at the specified bus.
  3754. /// \aknote This function has unspecified behavior when adding a mixer to a currently playing
  3755. /// bus which does not have any effects nor mixer, or removing the last mixer on a currently playing bus.
  3756. /// \endaknote
  3757. /// \aknote Make sure the new mixer shareset is included in a soundbank, and that sound bank is loaded. Otherwise you will see errors in the Capture Log.\endaknote
  3758. /// \aknote This function will replace existing mixers on the node.
  3759. /// \endaknote
  3760. /// \returns
  3761. /// - \c AK_Success when successful
  3762. /// - \c AK_InvalidID if in_pszBusName is null
  3763. AK_EXTERNAPIFUNC( AKRESULT, SetMixer )(
  3764. const char* in_pszBusName, ///< Bus name
  3765. AkUniqueID in_shareSetID ///< ShareSets ID; pass AK_INVALID_UNIQUE_ID to remove.
  3766. );
  3767. /// Forces channel configuration for the specified bus.
  3768. /// \aknote You cannot change the configuration of the master bus.\endaknote
  3769. ///
  3770. /// \return Always returns AK_Success
  3771. AK_EXTERNAPIFUNC(AKRESULT, SetBusConfig)(
  3772. AkUniqueID in_audioNodeID, ///< Bus Short ID.
  3773. AkChannelConfig in_channelConfig ///< Desired channel configuration. An invalid configuration (from default constructor) means "as parent".
  3774. );
  3775. #ifdef AK_SUPPORT_WCHAR
  3776. /// Forces channel configuration for the specified bus.
  3777. /// \aknote You cannot change the configuration of the master bus.\endaknote
  3778. ///
  3779. /// \returns
  3780. /// - \c AK_Success when successful
  3781. /// - \c AK_InvalidID if in_pszBusName is null
  3782. AK_EXTERNAPIFUNC(AKRESULT, SetBusConfig)(
  3783. const wchar_t* in_pszBusName, ///< Bus name
  3784. AkChannelConfig in_channelConfig ///< Desired channel configuration. An invalid configuration (from default constructor) means "as parent".
  3785. );
  3786. #endif //AK_SUPPORT_WCHAR
  3787. /// Forces channel configuration for the specified bus.
  3788. /// \aknote You cannot change the configuration of the master bus.\endaknote
  3789. ///
  3790. /// \returns
  3791. /// - \c AK_Success when successful
  3792. /// - \c AK_InvalidID if in_pszBusName is null
  3793. AK_EXTERNAPIFUNC(AKRESULT, SetBusConfig)(
  3794. const char* in_pszBusName, ///< Bus name
  3795. AkChannelConfig in_channelConfig ///< Desired channel configuration. An invalid configuration (from default constructor) means "as parent".
  3796. );
  3797. /// Sets a game object's obstruction and occlusion levels. If SetMultiplePositions were used, values are set for all positions.
  3798. /// This function is used to affect how an object should be heard by a specific listener.
  3799. /// \sa
  3800. /// - \ref soundengine_obsocc
  3801. /// - \ref soundengine_environments
  3802. /// \return Always returns AK_Success
  3803. AK_EXTERNAPIFUNC( AKRESULT, SetObjectObstructionAndOcclusion )(
  3804. AkGameObjectID in_EmitterID, ///< Emitter game object ID
  3805. AkGameObjectID in_ListenerID, ///< Listener game object ID
  3806. AkReal32 in_fObstructionLevel, ///< ObstructionLevel: [0.0f..1.0f]
  3807. AkReal32 in_fOcclusionLevel ///< OcclusionLevel: [0.0f..1.0f]
  3808. );
  3809. /// Sets a game object's obstruction and occlusion level for each positions defined by SetMultiplePositions.
  3810. /// This function differs from SetObjectObstructionAndOcclusion as a list of obstruction/occlusion pair is provided
  3811. /// and each obstruction/occlusion pair will affect the corresponding position defined at the same index.
  3812. /// \aknote In the case the number of obstruction/occlusion pairs is smaller than the number of positions, remaining positions'
  3813. /// obstrucion/occlusion values are set to 0.0. \endaknote
  3814. /// \return
  3815. /// - \c AK_Success if successful
  3816. /// - \c AK_CommandTooLarge if the number of obstruction values is too large for the command queue.
  3817. /// - \c AK_InvalidParameter if one of the parameter is out of range (check the debug console)
  3818. /// - \c AK_InvalidFloatValue if one of the occlusion/obstruction values is NaN or Inf.
  3819. /// \sa
  3820. /// - \ref soundengine_obsocc
  3821. /// - \ref soundengine_environments
  3822. /// \return AK_Success if occlusion/obstruction values are successfully stored for this emitter
  3823. AK_EXTERNAPIFUNC( AKRESULT, SetMultipleObstructionAndOcclusion )(
  3824. AkGameObjectID in_EmitterID, ///< Emitter game object ID
  3825. AkGameObjectID in_uListenerID, ///< Listener game object ID
  3826. AkObstructionOcclusionValues* in_fObstructionOcclusionValues, ///< Array of obstruction/occlusion pairs to apply
  3827. ///< ObstructionLevel: [0.0f..1.0f]
  3828. ///< OcclusionLevel: [0.0f..1.0f]
  3829. AkUInt32 in_uNumOcclusionObstruction ///< Number of obstruction/occlusion pairs specified in the provided array
  3830. );
  3831. /// Saves the playback history of container structures.
  3832. /// This function will write history data for all currently loaded containers and instantiated game
  3833. /// objects (for example, current position in Sequence Containers and previously played elements in
  3834. /// Random Containers).
  3835. /// \remarks
  3836. /// This function acquires the main audio lock, and may block the caller for several milliseconds.
  3837. /// \return
  3838. /// - \c AK_Success when successful
  3839. /// - \c AK_Fail is in_pBytes could not be parsed (corruption or data is truncated)
  3840. /// \sa
  3841. /// - <tt>AK::SoundEngine::SetContainerHistory()</tt>
  3842. AK_EXTERNAPIFUNC( AKRESULT, GetContainerHistory)(
  3843. AK::IWriteBytes * in_pBytes ///< Pointer to IWriteBytes interface used to save the history.
  3844. );
  3845. /// Restores the playback history of container structures.
  3846. /// This function will read history data from the passed-in stream reader interface, and apply it to all
  3847. /// currently loaded containers and instantiated game objects. Game objects are matched by
  3848. /// ID. History for unloaded structures and unknown game objects will be skipped.
  3849. /// \remarks
  3850. /// This function acquires the main audio lock, and may block the caller for several milliseconds.
  3851. /// \return
  3852. /// - \c AK_Success if successful
  3853. /// - \c AK_InsufficientMemory if not enough memory is available for IReadBytes operation
  3854. /// \sa
  3855. /// - <tt>AK::SoundEngine::GetContainerHistory()</tt>
  3856. AK_EXTERNAPIFUNC(AKRESULT, SetContainerHistory)(
  3857. AK::IReadBytes * in_pBytes ///< Pointer to IReadBytes interface used to load the history.
  3858. );
  3859. //@}
  3860. ////////////////////////////////////////////////////////////////////////
  3861. /// @name Capture
  3862. //@{
  3863. /// Starts recording the sound engine audio output.
  3864. /// StartOutputCapture outputs a wav file per current output device of the sound engine.
  3865. /// If more than one device is active, the system will create multiple files in the same output
  3866. /// directory and will append numbers at the end of the provided filename.
  3867. ///
  3868. /// If no device is running yet, the system will return success AK_Success despite doing nothing.
  3869. /// Use RegisterAudioDeviceStatusCallback to get notified when devices are created/destructed.
  3870. ///
  3871. /// \return AK_Success if successful, AK_Fail if there was a problem starting the output capture.
  3872. /// \remark
  3873. /// - The sound engine opens a stream for writing using <tt>AK::IAkStreamMgr::CreateStd()</tt>. If you are using the
  3874. /// default implementation of the Stream Manager, file opening is executed in your implementation of
  3875. /// the Low-Level IO interface <tt>AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()</tt>. The following
  3876. /// AkFileSystemFlags are passed: uCompanyID = AKCOMPANYID_AUDIOKINETIC and uCodecID = AKCODECID_PCM,
  3877. /// and the AkOpenMode is AK_OpenModeWriteOvrwr. Refer to \ref streamingmanager_lowlevel_location for
  3878. /// more details on managing the deployment of your Wwise generated data.
  3879. /// \return
  3880. /// - \c AK_Success when successful
  3881. /// - \c AK_InvalidParameter if in_CaptureFileName is null.
  3882. /// - \c AK_InsufficientMemory if not enough memory is available.
  3883. /// \sa
  3884. /// - <tt>AK::SoundEngine::StopOutputCapture()</tt>
  3885. /// - <tt>AK::StreamMgr::SetFileLocationResolver()</tt>
  3886. /// - \ref streamingdevicemanager
  3887. /// - \ref streamingmanager_lowlevel_location
  3888. /// - RegisterAudioDeviceStatusCallback
  3889. AK_EXTERNAPIFUNC( AKRESULT, StartOutputCapture )(
  3890. const AkOSChar* in_CaptureFileName ///< Name of the output capture file
  3891. );
  3892. /// Stops recording the sound engine audio output.
  3893. /// \return AK_Success if successful, AK_Fail if there was a problem stopping the output capture.
  3894. /// \sa
  3895. /// - <tt>AK::SoundEngine::StartOutputCapture()</tt>
  3896. AK_EXTERNAPIFUNC( AKRESULT, StopOutputCapture )();
  3897. /// Adds text marker in audio output file.
  3898. /// \return
  3899. /// - \c AK_Success when successful
  3900. /// - \c AK_InvalidParameter if in_MarkerText is null.
  3901. /// - \c AK_InsufficientMemory if not enough memory is available.
  3902. /// \sa
  3903. /// - <tt>AK::SoundEngine::StartOutputCapture()</tt>
  3904. AK_EXTERNAPIFUNC( AKRESULT, AddOutputCaptureMarker )(
  3905. const char* in_MarkerText ///< Text of the marker
  3906. );
  3907. /// Adds binary data to a marker in audio output file.
  3908. /// \return
  3909. /// - \c AK_Success when successful
  3910. /// - \c AK_InvalidParameter if in_pMarkerData is null or in_uMarkerDataSize is zero.
  3911. /// - \c AK_InsufficientMemory if not enough memory is available.
  3912. /// \sa
  3913. /// - <tt>AK::SoundEngine::StartOutputCapture()</tt>
  3914. AK_EXTERNAPIFUNC(AKRESULT, AddOutputCaptureBinaryMarker)(
  3915. void* in_pMarkerData, ///< Marker data
  3916. AkUInt32 in_uMarkerDataSize ///< Size of the marker data
  3917. );
  3918. /// Gets the system sample rate.
  3919. /// \return The sample rate.
  3920. AK_EXTERNAPIFUNC(AkUInt32, GetSampleRate)();
  3921. /// Registers a callback used for retrieving audio samples.
  3922. /// The callback will be called from the audio thread during real-time rendering and from the main thread during offline rendering.
  3923. /// \return
  3924. /// - \c AK_Success when successful
  3925. /// - \c AK_DeviceNotFound if the audio device ID doesn't match to a device in use.
  3926. /// - \c AK_InvalidParameter when in_pfnCallback is null
  3927. /// - \c AK_NotInitialized if the sound engine is not initialized at this time
  3928. /// \sa
  3929. /// - <tt>AK::SoundEngine::AddOutput()</tt>
  3930. /// - <tt>AK::SoundEngine::GetOutputID()</tt>
  3931. /// - <tt>AK::SoundEngine::UnregisterCaptureCallback()</tt>
  3932. AK_EXTERNAPIFUNC(AKRESULT, RegisterCaptureCallback)(
  3933. AkCaptureCallbackFunc in_pfnCallback, ///< Capture callback function to register.
  3934. AkOutputDeviceID in_idOutput = AK_INVALID_OUTPUT_DEVICE_ID, ///< The audio device specific id, return by AK::SoundEngine::AddOutput or AK::SoundEngine::GetOutputID
  3935. void* in_pCookie = NULL ///< Callback cookie that will be sent to the callback function along with additional information
  3936. );
  3937. /// Unregisters a callback used for retrieving audio samples.
  3938. /// \return
  3939. /// - \c AK_Success when successful
  3940. /// - \c AK_DeviceNotFound if the audio device ID doesn't match to a device in use.
  3941. /// - \c AK_InvalidParameter when in_pfnCallback is null
  3942. /// - \c AK_NotInitialized if the sound engine is not initialized at this time
  3943. /// \sa
  3944. /// - <tt>AK::SoundEngine::AddOutput()</tt>
  3945. /// - <tt>AK::SoundEngine::GetOutputID()</tt>
  3946. /// - <tt>AK::SoundEngine::RegisterCaptureCallback()</tt>
  3947. AK_EXTERNAPIFUNC(AKRESULT, UnregisterCaptureCallback)(
  3948. AkCaptureCallbackFunc in_pfnCallback, ///< Capture callback function to unregister.
  3949. AkOutputDeviceID in_idOutput = AK_INVALID_OUTPUT_DEVICE_ID, ///< The audio device specific id, return by AK::SoundEngine::AddOutput or AK::SoundEngine::GetOutputID
  3950. void* in_pCookie = NULL ///< Callback cookie that will be sent to the callback function along with additional information
  3951. );
  3952. /// Starts recording the sound engine profiling information into a file. This file can be read
  3953. /// by Wwise Authoring. The file is created at the base path. If you have integrated Wwise I/O,
  3954. /// you can use <tt>CAkDefaultIOHookDeferred::SetBasePath()</tt> (or <tt>CAkDefaultIOHookDeferred::AddBasePath()</tt>)
  3955. /// to change the location where the file is saved. The profiling session records all data types possible.
  3956. /// Note that this call captures peak metering for all the busses loaded and mixing
  3957. /// while this call is invoked.
  3958. /// \remark This function is provided as a utility tool only. It does nothing if it is
  3959. /// called in the release configuration and returns AK_NotCompatible.
  3960. AK_EXTERNAPIFUNC( AKRESULT, StartProfilerCapture )(
  3961. const AkOSChar* in_CaptureFileName ///< Name of the output profiler file (.prof extension recommended)
  3962. );
  3963. /// Stops recording the sound engine profiling information.
  3964. /// \remark This function is provided as a utility tool only. It does nothing if it is
  3965. /// called in the release configuration and returns AK_NotCompatible.
  3966. AK_EXTERNAPIFUNC( AKRESULT, StopProfilerCapture )();
  3967. //@}
  3968. ////////////////////////////////////////////////////////////////////////
  3969. /// @name Offline Rendering
  3970. //@{
  3971. /// Sets the offline rendering frame time in seconds.
  3972. /// When offline rendering is enabled, every call to \ref RenderAudio() will generate sample data as if this much time has elapsed. If the frame time argument is less than or equal to zero, every call to RenderAudio() will generate one audio buffer.
  3973. /// \return Always returns AK_Success
  3974. AK_EXTERNAPIFUNC(AKRESULT, SetOfflineRenderingFrameTime)(
  3975. AkReal32 in_fFrameTimeInSeconds ///< frame time in seconds used during offline rendering
  3976. );
  3977. /// Enables/disables offline rendering.
  3978. /// \return Always returns AK_Success
  3979. AK_EXTERNAPIFUNC(AKRESULT, SetOfflineRendering)(
  3980. bool in_bEnableOfflineRendering ///< enables/disables offline rendering
  3981. );
  3982. //@}
  3983. ////////////////////////////////////////////////////////////////////////
  3984. /// @name Secondary Outputs
  3985. //@{
  3986. /// Adds an output to the sound engine. Use this to add controller-attached headphones, controller speakers, DVR output, etc.
  3987. /// The in_Settings parameter contains an Audio Device shareset to specify the output plugin to use and a device ID to specify the instance, if necessary (e.g. which game controller).
  3988. ///
  3989. /// Like most functions of AK::SoundEngine, AddOutput is asynchronous. A successful return code merely indicates that the request is properly queued.
  3990. /// Error codes returned by this function indicate various invalid parameters. To know if this function succeeds or not, and the failure code,
  3991. /// register an AkDeviceStatusCallbackFunc callback with RegisterAudioDeviceStatusCallback.
  3992. ///
  3993. /// \sa AkOutputSettings for more details.
  3994. /// \sa \ref integrating_secondary_outputs
  3995. /// \sa \ref default_audio_devices
  3996. /// \sa AK::SoundEngine::RegisterAudioDeviceStatusCallback
  3997. /// \sa AK::AkDeviceStatusCallbackFunc
  3998. /// \return
  3999. /// The following codes are returned directly from the function, as opposed to the AkDeviceStatusCallback
  4000. /// - \c AK_NotImplemented: Feature not supported, some platforms don't have other outputs.
  4001. /// - \c AK_InvalidParameter: Out of range parameters or unsupported parameter combinations (see parameter list below).
  4002. /// - \c AK_IDNotFound: The audioDeviceShareset on in_settings doesn't exist. Possibly, the Init bank isn't loaded yet or was not updated with latest changes.
  4003. /// - \c AK_DeviceNotReady: The idDevice on in_settings doesn't match with a valid hardware device. Either the device doesn't exist or is disabled. Disconnected devices (headphones) are not considered "not ready" therefore won't cause this error.
  4004. /// - \c AK_NotInitialized: If AK::SoundEngine::Init was not called or if the Init.bnk was not loaded before the call.
  4005. /// - \c AK_Success: Parameters are valid.
  4006. ///
  4007. /// The following codes are returned from the callback.
  4008. /// - \c AK_InsufficientMemory : Not enough memory to complete the operation.
  4009. /// - \c AK_IDNotFound: The audioDeviceShareset on in_settings doesn't exist. Possibly, the Init bank isn't loaded yet or was not updated with latest changes.
  4010. /// - \c AK_PluginNotRegistered: The audioDeviceShareset exists but the plug-in it refers to is not installed or statically linked with the game.
  4011. /// - \c AK_NotCompatible: The hardware does not support this type of output. Wwise will try to use the System output instead, and a separate callback will fire when that completes.
  4012. /// - \c AK_DeviceNotCompatible: The hardware does not support this type of output. Wwise will NOT fallback to any other type of output.
  4013. /// - \c AK_Fail: Generic code for any non-permanent conditions (e.g. disconnection) that prevent the use of the output. Wwise has created the output and sounds will be routed to it, but this output is currently silent until the temporary condition resolves.
  4014. /// - \c AK_NoDistinctListener: Outputs of the same type (same ShareSet, like controller speakers) must have distinct Listeners to make a proper routing. This doesn't happen if there is only one output of that type.
  4015. AK_EXTERNAPIFUNC(AKRESULT, AddOutput)(
  4016. const AkOutputSettings & in_Settings, ///< Creation parameters for this output. \ref AkOutputSettings
  4017. AkOutputDeviceID *out_pDeviceID = NULL, ///< (Optional) Output ID to use with all other Output management functions. Leave to NULL if not required. \ref AK::SoundEngine::GetOutputID
  4018. const AkGameObjectID* in_pListenerIDs = NULL, ///< Specific listener(s) to attach to this device.
  4019. ///< If specified, only the sounds routed to game objects linked to those listeners will play in this device.
  4020. ///< It is necessary to have separate listeners if multiple devices of the same type can coexist (e.g. controller speakers)
  4021. ///< If not specified, sound routing simply obey the associations between Master Busses and Audio Devices setup in the Wwise Project.
  4022. AkUInt32 in_uNumListeners = 0 ///< The number of elements in the in_pListenerIDs array.
  4023. );
  4024. /// Removes one output added through AK::SoundEngine::AddOutput
  4025. /// If a listener was associated with the device, you should consider unregistering the listener prior to call RemoveOutput
  4026. /// so that Game Object/Listener routing is properly updated according to your game scenario.
  4027. /// \sa \ref integrating_secondary_outputs
  4028. /// \sa AK::SoundEngine::AddOutput
  4029. /// \return AK_Success: Parameters are valid.
  4030. AK_EXTERNAPIFUNC(AKRESULT, RemoveOutput)(
  4031. AkOutputDeviceID in_idOutput ///< ID of the output to remove. Use the returned ID from AddOutput, GetOutputID, or ReplaceOutput
  4032. );
  4033. /// Replaces an output device previously created during engine initialization or from AddOutput, with a new output device.
  4034. /// In addition to simply removing one output device and adding a new one, the new output device will also be used on all of the master buses
  4035. /// that the old output device was associated with, and preserve all listeners that were attached to the old output device.
  4036. ///
  4037. /// Like most functions of AK::SoundEngine, AddOutput is asynchronous. A successful return code merely indicates that the request is properly queued.
  4038. /// Error codes returned by this function indicate various invalid parameters. To know if this function succeeds or not, and the failure code,
  4039. /// register an AkDeviceStatusCallbackFunc callback with RegisterAudioDeviceStatusCallback.
  4040. ///
  4041. /// \sa AK::SoundEngine::AddOutput
  4042. /// \sa AK::SoundEngine::RegisterAudioDeviceStatusCallback
  4043. /// \sa AK::AkDeviceStatusCallbackFunc
  4044. /// \return
  4045. /// - \c AK_InvalidID: The audioDeviceShareset on in_settings was not valid.
  4046. /// - \c AK_IDNotFound: The audioDeviceShareset on in_settings doesn't exist. Possibly, the Init bank isn't loaded yet or was not updated with latest changes.
  4047. /// - \c AK_DeviceNotReady: The idDevice on in_settings doesn't match with a valid hardware device. Either the device doesn't exist or is disabled. Disconnected devices (headphones) are not considered "not ready" therefore won't cause this error.
  4048. /// - \c AK_DeviceNotFound: The in_outputDeviceId provided does not match with any of the output devices that the sound engine is currently using.
  4049. /// - \c AK_InvalidParameter: Out of range parameters or unsupported parameter combinations on in_settings
  4050. /// - \c AK_Success: parameters were valid, and the remove and add will occur.
  4051. AK_EXTERNAPIFUNC(AKRESULT, ReplaceOutput)(
  4052. const AkOutputSettings & in_Settings, ///< Creation parameters for this output. \ref AkOutputSettings
  4053. AkOutputDeviceID in_outputDeviceId, ///< AkOutputDeviceID of the output to replace. Use 0 to target the current main output, regardless of its id. Otherwise, use the AkOuptutDeviceID returned from AddOutput() or ReplaceOutput(), or generated by GetOutputID()
  4054. AkOutputDeviceID *out_pOutputDeviceId = NULL ///< (Optional) Pointer into which the method writes the AkOutputDeviceID of the new output device. If the call fails, the value pointed to will not be modified.
  4055. );
  4056. /// Gets the compounded output ID from shareset and device id.
  4057. /// Outputs are defined by their type (Audio Device shareset) and their specific system ID. A system ID could be reused for other device types on some OS or platforms, hence the compounded ID.
  4058. /// Use 0 for in_idShareset & in_idDevice to get the Main Output ID (the one usually initialized during AK::SoundEngine::Init)
  4059. /// \return The id of the output
  4060. AK_EXTERNAPIFUNC(AkOutputDeviceID, GetOutputID)(
  4061. AkUniqueID in_idShareset, ///< Audio Device ShareSet ID, as defined in the Wwise Project. If needed, use AK::SoundEngine::GetIDFromString() to convert from a string. Set to AK_INVALID_UNIQUE_ID to use the default.
  4062. AkUInt32 in_idDevice ///< Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
  4063. /// \sa \ref obtaining_device_id
  4064. );
  4065. AK_EXTERNAPIFUNC(AkOutputDeviceID, GetOutputID)(
  4066. const char* in_szShareSet, ///< Audio Device ShareSet Name, as defined in the Wwise Project. If Null, will select the Default Output shareset (always available)
  4067. AkUInt32 in_idDevice ///< Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
  4068. /// \sa \ref obtaining_device_id
  4069. );
  4070. #ifdef AK_SUPPORT_WCHAR
  4071. AK_EXTERNAPIFUNC(AkOutputDeviceID, GetOutputID)(
  4072. const wchar_t* in_szShareSet, ///< Audio Device ShareSet Name, as defined in the Wwise Project. If Null, will select the Default Output shareset (always available)
  4073. AkUInt32 in_idDevice ///< Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
  4074. /// \sa \ref obtaining_device_id
  4075. );
  4076. #endif
  4077. /// Sets the Audio Device to which a master bus outputs. This overrides the setting in the Wwise project.
  4078. /// Can only be set on top-level busses. The Init bank should be successfully loaded prior to this call.
  4079. /// \aknote This function is useful only if used before the creation of an output, at the beginning of the sound engine setup.
  4080. /// Once active outputs using this Bus have been created, it is imperative to use AK::SoundEngine:ReplaceOutput instead to change the type of output.
  4081. /// \return
  4082. /// AK_IDNotFound when either the Bus ID or the Device ID are not present in the Init bank or the bank was not loaded
  4083. /// AK_InvalidParameter when the specified bus is not a Master Bus. This function can be called only on busses that have no parent bus.
  4084. AK_EXTERNAPIFUNC(AKRESULT, SetBusDevice)(
  4085. AkUniqueID in_idBus, ///< Id of the master bus
  4086. AkUniqueID in_idNewDevice ///< New device shareset to replace with.
  4087. );
  4088. /// Sets the Audio Device to which a master bus outputs. This overrides the setting in the Wwise project.
  4089. /// Can only be set on top-level busses. The Init bank should be successfully loaded prior to this call.
  4090. /// \aknote This function is useful only if used before the creation of an output, at the beginning of the sound engine setup.
  4091. /// Once active outputs using this Bus have been created, it is imperative to use AK::SoundEngine:ReplaceOutput instead to change the type of output.
  4092. /// \return
  4093. /// AK_IDNotFound when either the Bus ID or the Device ID are not present in the Init bank or the bank was not loaded
  4094. /// AK_InvalidParameter when the specified bus is not a Master Bus. This function can be called only on busses that have no parent bus.
  4095. AK_EXTERNAPIFUNC(AKRESULT, SetBusDevice)(
  4096. const char* in_BusName, ///< Name of the master bus
  4097. const char* in_DeviceName ///< New device shareset to replace with.
  4098. );
  4099. #ifdef AK_SUPPORT_WCHAR
  4100. /// Sets the Audio Device to which a master bus outputs. This overrides the setting in the Wwise project.
  4101. /// Can only be set on top-level busses. The Init bank should be successfully loaded prior to this call.
  4102. /// SetBusDevice must be preceded by a call to AddOutput for the new device shareset to be registered as an output.
  4103. /// \return
  4104. /// AK_IDNotFound when either the Bus ID or the Device ID are not present in the Init bank or the bank was not loaded
  4105. /// AK_InvalidParameter when the specified bus is not a Master Bus. This function can be called only on busses that have no parent bus.
  4106. AK_EXTERNAPIFUNC(AKRESULT, SetBusDevice)(
  4107. const wchar_t* in_BusName, ///< Name of the master bus
  4108. const wchar_t* in_DeviceName ///< New device shareset to replace with.
  4109. );
  4110. #endif
  4111. /// Returns a listing of the current devices for a given sink plug-in, including Device ID, friendly name, and state.
  4112. /// This call is only valid for sink plug-ins that support device enumeration.
  4113. /// Prerequisites: the plug-in must have been initialized by loading the init bank or by calling \ref AK::SoundEngine::RegisterPlugin.
  4114. /// \return
  4115. /// - \c AK_NotImplemented if the sink plug-in does not implement device enumeration
  4116. /// - \c AK_PluginNotRegistered if the plug-in has not been registered yet either by loading the init bank or by calling RegisterPluginDLL.
  4117. /// - \c AK_NotCompatible if no device of this type are supported on the current platform
  4118. /// - \c AK_Fail in case of system device manager failure (OS related)
  4119. ///
  4120. AK_EXTERNAPIFUNC(AKRESULT, GetDeviceList) (
  4121. AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in the plug-in description XML file)
  4122. AkUInt32 in_ulPluginID, ///< Plug-in identifier (as declared in the plug-in description XML file)
  4123. AkUInt32& io_maxNumDevices, ///< In: The length of the out_deviceDescriptions array. Out: If out_deviceDescriptions is not-null, this will be set to the number of entries in out_deviceDescriptions that was populated. If out_deviceDescriptions is null, this will be set to the number of devices that may be available.
  4124. AkDeviceDescription* out_deviceDescriptions ///< The output array of device descriptions.
  4125. );
  4126. /// Returns a listing of the current devices for a given sink plug-in, including Device ID, friendly name, and state.
  4127. /// This call is only valid for sink plug-ins that support device enumeration.
  4128. /// Prerequisites:
  4129. /// * The plug-in must have been initialized by loading the init bank or by calling \ref AK::SoundEngine::RegisterPlugin.
  4130. /// * The audio device shareset must have been loaded from a soundbank and a device with this shareset must exist in the pipeline.
  4131. /// \return
  4132. /// AK_NotImplemented if the sink plug-in does not implement device enumeration
  4133. /// AK_PluginNotRegistered if the plug-in has not been registered yet either by loading the init bank or by calling RegisterPluginDLL.
  4134. AK_EXTERNAPIFUNC(AKRESULT, GetDeviceList) (
  4135. AkUniqueID in_audioDeviceShareSetID, ///< In: The audio device shareset ID for which to list the sink plug-in devices.
  4136. AkUInt32& io_maxNumDevices, ///< In: The length of the out_deviceDescriptions array. Out: If out_deviceDescriptions is not-null, this will be set to the number of entries in out_deviceDescriptions that was populated. If out_deviceDescriptions is null, this will be set to the number of devices that may be available.
  4137. AkDeviceDescription* out_deviceDescriptions ///< The output array of device descriptions.
  4138. );
  4139. /// Sets the volume of a output device.
  4140. /// \return
  4141. /// - \c AK_Success if successful
  4142. /// - \c AK_InvalidFloatValue if the value specified was NaN or Inf
  4143. AK_EXTERNAPIFUNC( AKRESULT, SetOutputVolume )(
  4144. AkOutputDeviceID in_idOutput, ///< Output ID to set the volume on. As returned from AddOutput or GetOutputID
  4145. AkReal32 in_fVolume ///< Volume (0.0 = Muted, 1.0 = Volume max)
  4146. );
  4147. /// Returns whether or not the audio device matching the device ID provided supports spatial audio (i.e. the functionality is enabled, and more than 0 dynamic objects are supported).
  4148. /// If Spatial Audio is supported, then you can call Init, AddOutput, or ReplaceOutput with an Audio Device Shareset corresponding to the respective platform-specific plug-in that
  4149. /// provides spatial audio, such as the Microsoft Spatial Sound Platform for Windows. Note that on Xbox One, you need to call EnableSpatialAudio() before the sound engine is
  4150. /// initialized, or initialize the sound engine with AkPlatformInitSettings::bEnableSpatialAudio set to true if you want spatial audio support; otherwise this will always return AK_NotCompatible.
  4151. /// \return
  4152. /// AK_NotCompatible when the device ID provided does not support spatial audio, or the platform does not support spatial audio
  4153. /// AK_Fail when there is some other miscellaneous failure, or the device ID provided does not match a device that the system knows about
  4154. /// AK_Success when the device ID provided does support spatial audio
  4155. AK_EXTERNAPIFUNC( AKRESULT, GetDeviceSpatialAudioSupport ) (
  4156. AkUInt32 in_idDevice ///< Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
  4157. /// \sa \ref obtaining_device_id
  4158. );
  4159. //@}
  4160. /// This function should be called to put the sound engine in background mode, where audio isn't processed anymore. This needs to be called if the console has a background mode or some suspended state.
  4161. /// Call \c WakeupFromSuspend when your application receives the message from the OS that the process is back in foreground.
  4162. /// When suspended, the sound engine will process API messages (like PostEvent and SetSwitch) only when \ref RenderAudio() is called.
  4163. /// It is recommended to match the <b>in_bRenderAnyway</b> parameter with the behavior of the rest of your game:
  4164. /// if your game still runs in background and you must keep some kind of coherent state between the audio engine and game, then allow rendering.
  4165. /// If you want to minimize CPU when in background, then don't allow rendering and never call RenderAudio from the game.
  4166. ///
  4167. /// Consult \ref workingwithsdks_system_calls to learn when it is appropriate to call this function for each platform.
  4168. /// \sa WakeupFromSuspend
  4169. /// \sa \ref workingwithsdks_system_calls
  4170. AK_EXTERNAPIFUNC( AKRESULT, Suspend )(
  4171. bool in_bRenderAnyway = false, ///< If set to true, audio processing will still occur, but not outputted. When set to false, no audio will be processed at all, even upon reception of RenderAudio().
  4172. bool in_bFadeOut = true ///< Delay the suspend by one audio frame in order to fade-out. When false, the suspend takes effect immediately but audio may glitch.
  4173. );
  4174. /// This function should be called to wake up the sound engine and start processing audio again. This needs to be called if the console has a background mode or some suspended state.
  4175. ///
  4176. /// Consult \ref workingwithsdks_system_calls to learn when it is appropriate to call this function for each platform.
  4177. /// \sa Suspend
  4178. /// \sa \ref workingwithsdks_system_calls
  4179. AK_EXTERNAPIFUNC( AKRESULT, WakeupFromSuspend )(
  4180. AkUInt32 in_uDelayMs = 0 /// Delay (in milliseconds) before the wake up occurs. Rounded up to audio frame granularity. Adding a delay is useful if there is a possibility that another OS event may override the wake-up in the near future.
  4181. );
  4182. /// Obtains the current audio output buffer tick. This corresponds to the number of buffers produced by
  4183. /// the sound engine since initialization.
  4184. /// \return Tick count.
  4185. AK_EXTERNAPIFUNC(AkUInt32, GetBufferTick)();
  4186. /// Obtains the current audio output sample tick. This corresponds to the number of sapmles produced by
  4187. /// the sound engine since initialization.
  4188. /// \return Sample count.
  4189. AK_EXTERNAPIFUNC(AkUInt64, GetSampleTick)();
  4190. }
  4191. }
  4192. #endif // _AK_SOUNDENGINE_H_