Thank you for downloading FMOD music and sound effects ... · Thank you for downloading FMOD music and sound effects system. ... You need to have uses FMOD in your source code somewhere

ThankyoufordownloadingFMODmusicandsoundeffectssystem.

Withinthispackageyouwillfindthemeanstoproducethemostuptodateandefficient

audioinyourgamesandapplications.

Tofindoutmoregotohttp://www.fmod.org

http://www.fmod.org

THEBASICSIntroduction

ThisisthefirstplacetolookifyouhavenoideawhattodowhendownloadingFMOD,orthosewithsomeideabutneedalittlebitofhelp.Itwillgiveyouastepbystepintroductionandtutorialonwhattocall,whattolinkandwheretocallstuffsoyoucaneasilygetonyourwaytogreatsoundingaudio!

Thepackage

Thefirstthingyouwilldoisunzipfmodandfindthefollowingdirectorystructure.

/api

ThefilesyouareinterestedinforyourownprojectsareheldhereThisholds

FMOD.DLL,Theimportlibrary(fmodvc.lib,fmodbc.libetc)youneedtolink(forCusers),andTheheader(fmod.h,fmod.pas,fmod.basdependingonlanguage)youneedtoinclude.

CUsersMSVC-#include"fmod.h"intoyoursourcecodeandlinkfmodvc.libbyputtingitintoyourlinksection/makefile/project.Codewarrior-#include"fmod.h"intoyoursourcecodeandlinkfmodvc.libbyputtingitintoyourlinksection/makefile/project.Watcom-#include"fmod.h"intoyoursourcecodeandlinkfmodwc.libbyputtingitintoyourlinksection/makefile/project.Borland-#include"fmod.h"intoyoursourcecodeandlinkfmodbc.libbyputtingitintoyourlinksection/makefile/project.LCC-WIN32-#include"fmod.h"intoyoursourcecodeandlinkfmodlcc.libbyputtingitintoyourlinksection/makefile/project.MingwandCygWin-#include"fmod.h"intoyoursourcecodeandlinklibfmod.abyputtingitintoyourlinksection/makefile/project.Linux/GCC-#include"fmod.h"intoyoursourcecodeandlinkwithlibfmod-X-Y.so(i.egccfile.c-lfmod-3.5)

NotethereisnoDJGPPsupport.Ifyouaskforthisyouarelookinginthewrongplace.DJGPPisDOSonlyandtofindasimilarfreeWIN32compilertryLCC-WIN32orCygWin.

DelphiUsersYouneedtohaveusesFMODinyoursourcecodesomewhere.IfdelphicannotfindtheFMODheaderyouneedtohavethepathtofmod.pasinyourlibrarypath.GotoTools\EnvironmentOptions\Library.Addthepath,eg.C:\fmodapi340\api\delphi(ofcourse,usethepaththatyouhaveonyoursystem),toLibraryPathanditshouldbehappy.

VisualBasicUsersAddfmod.bastoyourproject.

/documentation

Youmustknowaboutthisalreadyifyouarereadingthis!

/media

Thisdirectoryholdssomewavfilesandsongsthattheexamplesuse.Forexamplejbtennis.wavwhichcontainslooppointsandwavsyncmarkersthatfmodcanread

/samples

ThisfolderisforCprogrammersandcontainsavarietyofsamplestodemonstrate3Dsound,dspeffects,recording,streamsandmoreToruntheprecompiledexecutables,firstcopytheFMOD.DLLfilefrom/apiintotherelevantsampledirectorytomakeitaccessablefortheprogram.

/samplesdelphi

ThisfolderisforDelphiprogrammersandcontainsavarietyofsamplestodemonstrateusingFMODwithDelphi.WrittenbySteveWilliamsToruntheprecompiledexecutables,firstcopytheFMOD.DLLfilefrom/apiintotherelevantsampledirectorytomakeitaccessablefortheprogram.

/samplesvb

ThisfolderisforVisualBasicprogrammersandcontainsexamplesofusingFMODwithVisualBasic.Toruntheprecompiledexecutables,firstcopytheFMOD.DLLfilefrom/apiintotherelevantsampledirectorytomakeitaccessablefortheprogram.

/tools

Thisfoldercontainsasioconfig.exe.Thisprogramsimplyconfiguresanyasiodevicesyouhaveonyoursystembybringingupthedriver'snativeconfigurationscreen.Ifyourunitandnoentriesareinthelist,yourasiodriversarenotinstalledproperly.Ifyouselectordoubleclickanentrythatdoesexistandnoconfigscreenappearsthenyourasiodriversarenotinstalledcorrectlyoryouhaveselectedthewrongdrivertoconfigure.TakenoteofthiswhenselectingthedevicefromtheFMODapi.

Gettingstarted

ThefirstthingyouneedtodoismakesureFMOD.DLLisaccessablefromyourprogram.Otherwiseyouwillgetanerrorsomethingliketheonebelowwhenyoutryandrunyourexecutable.

CopytheFMOD.DLLfileoutofthe/apidirectoryandintothedirectorywhereyourexecutablewillbe.Iftheyareinthesamedirectorythenitwillworkasexpected.Nowyouarereadytostartcoding,youneedtoinitializeFMODfirst!Youdothisonceatthestartofyourprogram.

DothiswithFSOUND_Init.ThesimplestwaytodothisistotellFMODtomixat44100hz,anduse32softwarechannels.Thisisdonelikeso.

FSOUND_Init(44100,32,0);

Togetmoredetailedcontrolpleaseseethefmod.hfiletoseewhatpre-FSOUND_Initfunctionscanbecalledtocontrolthingslikemixertype,outputdeviceetc.AlsoFSOUND_Inititselfhasflagswhichyoucanfindoutmoreaboutintherelevantdocumentation.Notethatyoudon'thavetoactuallyusethepre-initfunctionsasFMODautomaticallydetectsthebestsettingsforyou.Ifthisfunctionsucceeds,(seeerrorcodeifitdoesnt),thenFMODisnowrunningandsomemoreinterestingthingscanbedone.

Samples,StreamsandSongs

Youhaveamusicfileorasoundyouwanttoplay.WhatFMODAPIshouldyouusetoloadandplayit?Here'saguide.

Ifitisasequencedmusicfilesuchas.MOD,.S3M,.XM,.ITor.MID,thenusetheFMUSICAPI.YouwillwanttouseFMUSIC_LoadSongtoloaditintomemory.Whenthisgivesyouavalidreturnhandle,usethathandlewithFMUSIC_PlaySongtoplayit!ThehandletypeforthistypeoffilewhenloadedisFMUSIC_MODULE.IfitisaPCMbasedorcompressedfilesuchas.WAV,.MP2,.MP3,.OGGor.RAWthenyouhaveachoicetomake.Willitusetoomuchmemoryifyouloaditinanddecompressitintomemory?orisitsmallenoughtofit?-Forsmallsoundssuchassoundeffectsthatyouwanttotriggermultipletimesatonce(forexampleagunshot),thenyouwillwanttouseFSOUND_Sample_Load.Whenitgivesyouavalidreturnhandle,usethathandlewithFSOUND_PlaySoundorFSOUND_PlaySoundEx.Thisisthefastestwaytoreplaysounds,astheyaredecompressedintomemory(atloadtime)firstbeforebeingplayed.ThehandletypeforthistypeoffilewhenloadedisFSOUND_SAMPLE.-Ifthefileisgoingtobebig,anddoesntneedtobeplayedmultipletimesatonce(notethenextoptioncannotbeplayedmultipletimesatonce),thentheotherchoiceistouseFSOUND_Stream_Open.Thisopensafile,andpreparesitforplaying.Whenitgivesyouavalidreturnhandle,usethathandlewithFSOUND_Stream_PlayorFSOUND_Stream_PlayEx.Thisstreamsthefilefromthediskinrealtimeanddecompressesthefileonthefly.Thisoptionuseslessmemorythansampleswhenthefileispastacertainsize.Notethatthisoptionusesalotmorecputimethanasampleasithastoaccessthedisk,andifnescessary,decompressthedataonthefly.

FMODdecompressionroutinesareusuallyfairlyefficientbutitcanbesignificantonslowmachines(especiallyCEdevices),orifmultiplestreamsareplayedtogetheratonce.YoucanofcoursemeasurethiswithFSOUND_GetCPUUsageorjustseehowitaffectsyourframerate.ThehandletypeforthistypeoffilewhenloadedisFSOUND_STREAM.

Note:UseFSOUND_FREEwhenchoosingachanneltoplayasampleorstreamon.Itmakesthebestchoiceforyou.Ifyoumustuseavaluesuchas0-31etc,thencarefullyreadthechannelmapping/indexinformatiomnintheremarkssectionofFSOUND_PlaySound.

Manipulation

Finallythelastmostbasicthingsyoumightwanttodoarechangethesong'svolumeorspeedoranyothervarietyofattributes

ForFMUSIC_MODULEhandlesyoucanusetheFMUSICAPIforcommandslikeFMUSIC_SetPausedandFMUSIC_SetMasterVolume.Seefmod.h(orequivalent)orthedocumentationforalistofthesecommandsyoucanuse.ForFSOUND_SAMPLEhandlesyoucanuseavarietyofcommandsonaplayingsoundfromthechannelhandlereturnedfromFSOUND_PlaySoundorFSOUND_PlaySoundEx.TheseincludesuchcommandsasFSOUND_SetVolumeorFSOUND_SetFrequencyorawholehostofcommands.ForFSOUND_STREAMhandlesyoucanuseavarietyofcommandsonaplayingstream,alsofromthechannelhandlereturnedfromFSOUND_Stream_PlayorFSOUND_Stream_PlayEx.Becausethesealsousechannelstoplayon,theycanusethechannelfunctionsjustasasamplewould.YoucanpauseastreamwithFSOUND_SetPausedforexample.

3DSOUNDANDGAMECODINGIntroduction

3DSoundinFMODisaccomplishedthroughavariousdifferentAPI'swhicharehandledtransparentlytoyouthroughoneunifiedinterface.TheseareDirectSound3DwithEAX2.0andEAD3.0/HDsupport,orFMODfallbacksoftware3Dstereoengine.

ItisrecommendedwhenyouseeanAPIfunctionhighlightedasalink,thatyouchecktheAPIreferenceformoredetail.

HardwareSupport

AllocatingsampleswithFSOUND_HW3Disthekeytogettingyoursoundstouse3Dhardwareacceleration.Youdothiswhenloadingwav,raw,mp3,etcsamples,throughthefollowingfunction.

FSOUND_Sample_Load(intindex,constchar*name_or_data,unsignedintinputmode,intoffset,intlength);BitwiseORintheFSOUND_HW3Dflagintothemodeparameteroftheloadingfunction.

Ifyouhavethecorrecthardware,thesoundwillbeloadedintohardwaremode.Ifnot,thesamplewillbeloadedinsoftwaremode,transparentlytotheprogrammer,butitwillnotbeacceleratedortakeadvantageofadvanced3dalgorithmsandEAX.

Hereisanexampleofawavfileattemptingtobeloadedasa3DHardwarebuffer.FSOUND_Sample_Load(FSOUND_FREE,"engine.wav",FSOUND_HW3D|FSOUND_LOOP_NORMAL,0,0);

OryoucanforceitintosoftwarebynotspecifyingtheFSOUND_HW3DflagFSOUND_Sample_Load(FSOUND_FREE,"engine.wav",FSOUND_LOOP_NORMAL,0,0);

Oryoucanhaveitasa2Dsound(2dsoundsarenotaffectedby3dfunctions,andarerenderedinsoftware),usingtheFSOUND_2Dflag.FSOUND_Sample_Load(FSOUND_FREE,"engine.wav",FSOUND_2D|FSOUND_LOOP_NORMAL,0,0);

Typicalgameloop

Thiswouldbeatypicalexampleofagameaudioloop.

do{

UpdateGame();//herethegameisupdatedandthesourceswouldbemovedwithFSOUND_SetAttributes

FSOUND_3D_Listener_SetAttributes(listenerpos,listenervel,fx,fy,fz,tx,ty,tz);//update'ears'FSOUND_Update();//neededtoupdate3dengine,onceperframe

}while(gamerunning);

Mostgamesusuallytaketheposition,velocityandorientationfromthecamera'svectorsandmatrix.

Velocityparameter

Velocityisonlyrequiredifyouwantdopplereffects.OtherwiseyoucanpassNULLtobothFSOUND_3D_Listener_SetAttributesandFSOUND_3D_SetAttributesforthevelocityparameter,andnodopplereffectwillbeheard

Thisisstressedoverandoveragain,butcan'tbestressedenough.ItisimportantthatthevelocitypassedtoFMODisMETERSPERSECONDandNOTmetersperFRAME.

Whatdoesthismean?Usepropervelocityvectorsfromphysicscodeetc,anddon'tjustsubtractlastframespositionfromthecurrentposition,asthisisaffectedbyframerate.(iethehighertheframeratethesmallerthepositiondeltas,andthereforesmallerdopplereffects,whichisincorrect)

Iftheonlywayyoucangetthevelocityistosubtractthisandlastframe'spositionvectors,thenremembertotimeadjustthemfrommetersperframebackuptometerspersecond.Thisisdonesimplybyscalingthedifferencevectorobtainedbysubtractingthe2positionvectors,byoneovertheframetimedelta.

Hereisanexamplevelx=(posx-lastposx)*1000/timedelta;velz=(posy-lastposy)*1000/timedelta;velz=(posz-lastposz)*1000/timedelta;timedeltaisthetimesincethelastframeinmilliseconds.ThiscanbeobtainedwithfunctionssuchastimeGetTime().Soat60fps,thetimedeltawouldbe16.67ms.ifthesourcemoved0.1metersinthistime,theactualvelocityinmeterspersecondwouldbevel=0.1*1000/16.67=6meterspersecond.Similarly,ifweonlyhavehalftheframerateof30fps,thensubtractingpositiondeltaswillgivesustwicethedistancethatitwouldat60fps(soitwouldhavemoved0.2metersthistime)vel=0.2*1000/33.33=6meterspersecondstill!phew!.

Orientationandcoordinatesystems

Gettingthecorrectorientationsetupisessentialifyouwantthesourcetomovearoundyouin3dspace.FMODUsesalefthandedcoordinatesystem,(x=right,y=up,z=forwards),whichisthesameasDirectSound3DandA3D

Ifyouuseadifferentcoordinatesystem,thenyouwillneedtoflipcertainaxisorevenswapthemaroundinsidethecalltoFSOUND_3D_Listener_SetAttributes.Taketherighthandedcoordinatesystem,whereZpointsbackwards,orcomesoutofthescreenatyou.ToconvertthistoFMODcoordinatesystemsimplynegatetheZcoordinateofthelistenerupandforwardvector.

JustthinkRIGHT,UP,FORWARDSforeachelementofavector(iex,y,z),andmapwhateveraxisfityourmodelintothis,togeneratethe2vectorsthatpointsforwardsandup.

Channelresourcemanagementandlowendcards

Somesoundcardsonlysupport4or83Dhardwarechannels,whereasothersoundcardssupport32and96hardware3Dchannels.Whatdoyoudoinyourgame?onlyplay43Dhardwarebasedsoundsatoncetomeetthebasespec?Notlikely.Itwouldberidiculoustolimityourselftothese4channelswhenyouhavethepotentialofotherhighendcardsthatcandonearly100hardwarechannelsatonce.

ThesolutionistouseFSOUND_SetMinHardwareChannels.ThisfunctioniscalledoncebeforecallingFSOUND_Init.WhatthisallowsyoutodoisassumeanumberofchannelswilleitherALLbeplayedinhardware,orNONEinhardware(thereforeinsoftware).Itbasicallysays'ifthecarddoesn'thavennumberofchannels,thenmixallsoundsinsoftware'.Thisallowsyoutoassumethatyouhavesay16soundstobeplayingatonce,andifthehardwarehasatleastthatmanychannelsavailable,itwillplaythemallinhardware.Ifyoucomeacrossacardthatonlysupports4hardwarechannelsatonce,thenitfailsthecriteriaandyoursoundsareplayedallinsoftware.

ThebestthingaboutthisisNOPlaySound'sfailbecauseofrunningoutofchannelsonunexpectedcards!Youcanguaranteeacertainnumberofchannelsavailable,andifthehardwareisthere,thenallthebetter!

Usepriorities!

FMOD'sprioritysystemistheretobeused.Ifyoutriggerlotsofsoundsonalimitednumberofchannels,somemightbemoreimportantthanothers.Ifyouweredoingafirstpersonshooter,theplayer'sgunshotsoundwouldbeoneofthemostimportantsounds.SoitshouldhaveahighprioritysetwithFSOUND_SetPriority.Otherlessimportantsoundswouldberejectedifthenumberofallocatedchannelsbecamefull,andthatgunshotneededtobeheard!

MUSICSYNCRHONIZATIONIntroduction

ThissectionwilldescribehowtosynchronizegraphicswithsoundeffectivelyusingFMODfunctions.Itusuallyinvolveseitherpollingagainstamusicvaluetotriggeryoureffect,orgettingacallbackfromFMOD.

Streams

Thebestwaytosynchronizeastream,suchasawavormp3isbyusingFSOUND_Stream_SetSyncCallback.Allyouhavetodoisdrop'markers'intoawaveditingprogramlikeSoundForge,andFMODwillautomaticallygeneratecallbacksasthestreamplayswhentheplaycursorrunsoverthemarkers!.Thestringsthatyoulabelmarkerswithareevenpassedintothecallback.NotethatonlyWAVfilesandMP3withRIFFwrapperswillworkhere.ThemarkersaresavedinaRIFFchunk.

Ifyoudon'thavethisluxuryorwanttouseaformatthatdoesn'tsupportthisfeature,thenthenextbestwaytosynchronizeastreamisbyusingcustomsyncpoints.Thiswayyoucanaddandremoveyourownpointsthatwavmarkerswouldnormallygenerate.SeeFSOUND_Stream_AddSyncPoint.AddyourmarkersmanuallywiththisandsetyoursyncpointcallbackwithFSOUND_Stream_SetSyncCallbackYourcallbackcouldthenlooksomethinglikethisbutyoucanputwhatyoulikeinthecallbackfunction.

signedcharendcallback(FSOUND_STREAM*stream,void*buff,intlen,intparam){

//endofstreamcallbackdoesn'thavea'buff'value,ifitdoesn'titcouldbeasyncpoint.if(buff){

printf("\nSYNCPOINT:\"%s\"\n",buff);}

returnTRUE;}

RememberFMODisareal-timesystemandtheamountoftimespentinacallbackhastobelow,oryoucouldcausebufferunderrunorstuttering.

MODs

Tosynchronizegraphicswithmodmusic,trythesefunctions.FMUSIC_SetZxxCallbackFMUSIC_SetRowCallback

FMUSIC_SetOrderCallbackFMUSIC_SetInstCallbackThisallowsyoutosetcallbacksonrow,order,instrumentorZxxmodeffectevents.ThereisalsoatimebasedfunctionFMUSIC_GetTime.

CUSTOMSAMPLESANDSTREAMS

Introduction

Thisanswerssomeofthequestionsregardinghowtocreateacustom/userstream,andacustom/usersample.

CustomSamples

1.Declareandallocateacustomsample...FSOUND_SAMPLE*mysamp=FSOUND_Sample_Alloc(FSOUND_FREE,length,mode,deffreq,defvol,defpan,defpri);

Remember'length'ismeasuredin*samples*notbytes,andmodeisabitfieldusingFSOUND_MODES(seethehelpforadescriptionofmodestodescribethesampleyouareallocating)Thiswillcreateyouanemptysampletouploaddatainto.

2.Uploadyourdatatothesample.UseFSOUND_Sample_Lock()/FSOUND_Sample_Unlock()orFSOUND_Sample_Upload()togetyourdataintothesample.WithFSOUND_Sample_Lock()/FSOUND_Sample_Unlock(),thedatayoucopyinMUSTbeinsignedformat.FSOUND_Sample_Upload()isthefavouredchoicethough,asyoucandescribetheformat,anditwillconvertitforyou,butyouhavetopre-readthedataintoyourownbufferfirstbeforepassingittoFSOUND_Sample_Upload(),whichtemporarilyusesmorememory.Thisconvertsfromalltypesofsources..unsigned,deltasamples,evenITcompressed.moretypeswillcomeinthefuture.

3.Playit!:)

CustomStreams

SeeFSOUND_Stream_Create.Youcanpassacallbackfunctionpointerandalengthtothisfunction.WhenyoustartthestreamwithFSOUND_Stream_Play(asyouwouldwithanyotherstream),youstartgettingcallbacks.

DSPENGINEIntroduction

ThiswillbrieflycoversomeoftheessentialstousingtheFMODDSPengine.TheDSPengineallowsyoutoread-andprocessthemixedsounddataasittravelstothesoundcardinitsvariousphases.Thiswillbedescribedinmoredetailbelow.Whywouldyouwanttodothis?Itallowsyoutofilterthedataifyoulike.Youcouldaddyourownreverb,distortion,EQtotheglobalFMODsoundstreamoranythingthatyoucanthinkofthatinvolvessounddata.Anotherreasonistoreaditandmaybedoanalysisorevenjustplotitasanoscilloscopeforeffect!

Whatisit?

TheDSPsystemdrivesFMOD'ssoftwareengine.Roughlyevery25milliseconds(platformdependant),FMODmixesabatchofdatatobesendtothesounddevice.Todothisitexecutesachainofalgorithmstoproducethesound.Thischainisexecutedeverytimeandperformsthevariousjobssuchasmixing,clippingandcallingusercallbackstoprocessthesounddata.Atthelowlevel,itissimplyalinkedlistofcallbacks.Eachtimeoneofthesecallbacksiscalleditispassedinthemixerbuffer.YoucanseethecallbackofaDSPunitdescribedhereasFSOUND_DSPCALLBACK.

Internally,FMODusestheseDSPcallbackstoperformvariousstagesofitsownmixingroutines.Itisalwaysworkingwiththemixbuffer.Thisissimplyastereobufferofintegersorfloats(dependingonthemixertypesetwithFSOUND_SetOutputordeterminedwithFSOUND_GetOutput.Itisjustlongenoughtomix25msworthofdata,soyoucouldprobablycalculatehowmanysamplesitwouldcontainbasedonthesamplerate,and25ms,butthereisafunctionsuppliedtoworkthisoutforyouFSOUND_DSP_GetBufferLength

The"System"DSPUnits

ThediagramaboveshowsthesystemDSPunitsthatarealwayspresent.ClearUnit-AllthisDSPunitdoesissilencethemixbufferbysettingitallto0's.ThenextDSPunitswillgenerallyfillinthisdatawithaudiobyadding/accumulatingtoit(mixing).YoucangetahandletothisunitsimplybycallingFSOUND_DSP_GetClearUnitMixSFXUnit-ThisunitcallsFMOD'sinternaloptimizedmixingroutinesandmixesanysoundeffectsspawnedbytheuserwithFSOUND_PlaySoundorFSOUND_PlaySoundEx.YoucangetahandletothisunitsimplybycallingFSOUND_DSP_GetSFXUnitMixMusicUnit-ThisunitexecutestheFMUSICmusicsequencingengine,andmixestheresultingchannelsusedbytheFMUSICengine.YoucangetahandletothisunitsimplybycallingFSOUND_DSP_GetMusicUnitFFTUnit-ThisunitperformsanFFTonthemixedoutputsothatFSOUND_DSP_GetSpectrumcanbeused.ItisturnedoffbydefaultduetotheCPUexpenseincurred,soifyouwanttousetheFSOUND_DSP_GetSpectrumfunctionthisneedstobeturnedonwithFSOUND_DSP_SetActivefirst.YoucangetahandletothisunitsimplybycallingFSOUND_DSP_GetFFTUnitClipandCopyUnit-ThisisthefinalsystemunitintheFSOUNDchain.YoucangetahandletothisunitsimplybycallingFSOUND_DSP_GetClipAndCopyUnit

Thesystemunitscanbedisabled,enabledandshiftedaroundinthislist!YoucouldeventhrowouttheFSOUNDsoftwareenginealltogetherandreplaceitwithyourown!

Priorities

NoticehowinthediagramaboveeachDSPunithada'priority'.ThisissimplyanumericvaluedeterminingitsorderintheDSPchain.Thelowertheprioritytheearlieritgetsexecuted.NoticehowtheClearUnithasapriorityof0,asitwantstobetheveryfirstunitexecuted.

Thisisbecauseitwouldn'tmakemuchsensetodoanythingbeforeit,astheClearUnitwilljustwipeitoutwithzero'sanyway!Youmaydisagreewiththis,wellok!(youmaywanttoexecutesomenonbufferalteringlogiclikeatimerthatcallsPlaySoundeverynowandthenforexample),soyoucansimplymoveitwithFSOUND_DSP_SetPriority.

Nowitsyourturn

Youmaybethinking,wellthissoundslikeagoodplaceifIwantedtocreatemyowneffectssuchasreverboralowpassfilterforexample,ormaybeyoujustwanttoreadthedatathatcomesinsoyoucangraphicallyplotit!Wellyou'rerightthisistheplacetodoit.JustcallFSOUND_DSP_Create,andgiveitacallback,andapriority.SetitactivewithFSOUND_DSP_SetActiveandimmediatelyyourDSPunitwillbeticking.Nowthedatapassedinwillbeeither16bitstereointeger(-32768to+32767)or32bitstereofloatingpoint(-32768.0fto+32767.0f,not0to1).Thiscanbedeterminedbywhatmixerisbeingusedatthetime,withFSOUND_GetMixer.It'suptoyounowwhatyoudowiththisdata.OneimportantthingtonoteisthatFMODmixesthedataaheadoftime,andthedatayouareprocessingisnotthedatathatisimmediatelyaudible.Ifyouarethinkingofplottingthedatatosyncwiththeaudibleoutput,itiswisetobufferthedatainacircularbuffer,forthenumberofsamplesspecifiedbyFSOUND_DSP_GetBufferLengthTotal.ThislengthisdivisiblebytheDSPcallbacklength(alwaysamultipleof25ms).Fromthispointthenyouwouldplottheblockofdataprecedingtheoneyouarefilling,whichistheoneplayingatthatpointintime!SeetheFMODexampleinthe/samples/fmoddirectoryforsourcecodethatdoesthis,andmanyotherexamplesofDSPprocessing.

FSOUND_PlaySoundExandthe'FSOUND_DSPUNIT*dsp'parameter

The'dsp'parameterinthisnewPlaySoundcommand,allowsyoutoassignor'group'achanneltoaspecificDSPunit.Thedspunityouassignhastobeanewoneandnotanexistingsystemunit,withnocallback.ADSPunitwithsoundeffectsattachedtoitdoesnothingbutexecutechannelmixing,asitreplacestheDSPcallbackwithitsowninternalmixercallback.Onereasonfordoingthisishavingawet/drymixforaneffect.Thisisdemonstratedinthe/samples/dspdirectory.Youmaywanttohavesomeeffectsaffectedbyreverbforexample,butnotothers.ThisispartofthereasontheMusicUnitisseparatefromtheSFXunit,asyoulikelydon'twantmusicaffectedbyDSPeffectsbutdowantthein-gamesoundeffectstobeaffected.

SPECTRUMANALYSIS

Introduction

ThisshortsectionrevealshoweasyitistoobtaintherealtimespectrumgraphforFMOD'sDSPoutputasyouhearit,forgraphicaldisplayorevenadvancedsignalprocessing!

Usingit

ThespectrumanalysisunitisanFMODSystemDSPUnit.IfyouareunsureoftheFMODDSPsystemthenseetheDSPtutorial.Bydefaultitisturnedoffbecauseitcanconsumeareasonableamountofcputimeanditdoesn'twanttobedoingFastFourierTransformcodewhenthespectrumisn'tevenbeingqueried!Toturnitonisquitesimple.Justcall.

FSOUND_DSP_SetActive(FSOUND_DSP_GetFFTUnit,TRUE);

Toturnitoffagainisjustassimple.Justcall.

FSOUND_DSP_SetActive(FSOUND_DSP_GetFFTUnit(),FALSE);

Whenyouraudioisplaying,thisDSPunitwillevery25ms,ortherateoftheDSPengine,updateasnapshotofthecurrentaudiblespectrum.

TherangeforthisFFTproducesaspectrumarraybetween1hzandNyquist,orinotherwords,1hzandthesamplerategiventoFSOUND_Initdividedby2.Ifyouhada44khzoutputitwouldproduceresultsupto22khz.

Togetthespectrum,useFSOUND_DSP_GetSpectrum.Asthedocumentationforthisfunctionsays,itreturnsapointertoanarrayof512floatingpointvaluesbetween0.0and1.0.Simplyplotthesevalues,scalingthe0to1valuetotheheightofyourspectrumdisplay,orprocessthemforthingslikebeatdetectionetc.Valuesabove11khz(wheninitializedwith44khz)becomeverysmallandaresometimesgraphicallynotveryinteresting.TheFMODmediaplayeronlyplotsthefirst256entriesbecauseofthis.Itisuptoyouhowyouinterpretthedata.Ifyouwantadifferentsizewindowbeside512thensimplyinterpolate,disregardorskipentriesandaveragethemtoyourdesiredrange.DifferentwindowsizesforthecurrentFFTarenotplannedfor

futurereleasesofFMOD.

NOTE:YoucanchangethepositionofthesystemFFTDSPunit.ItiscurrentlypositionedlastinthechainofDSPunitsbydefaultsothatthespectrumresultsinfeedbackfromeverythingplayedthroughtheFMODsoftwareengine.SeeFSOUND_DSP_PRIORITIESfortherelativesystemDSPunitpriorities.YoucouldmoveittobeforethemusicunitandaftertheSFXunitforexample,whichwouldexcludemodsfromhavingitsinputintothespectrumgraph.ItwouldbeachievedlikethisFSOUND_DSP_SetPriority(FSOUND_DSP_GetFFTUnit(),150);

WhathappensifIwanttogetaSpectrumbutuseFSOUND_FX?Aren'tthe2incompatible?.

Itispossiblebutwithsomelimitations,Seethissectionformoreinformation

FSOUNDFXAPIIntroduction

TheFSOUND_FXapiallowsyoutodospecialeffectsprocessingperchannelthroughDirectX8only.Youcandosucheffectsaschorus,compression,distortion,echo,flange,gargle,reverb,andEQthroughasimpleAPI.

Limitations

BeforeusingtheFSOUND_FXapi,thereareafewlimitationsthatmustbeknownaboutbecauseoftheDirectXAPI.

FXenabledsamplescanonlybeplayedonceatatime,notmultipletimesatonce.SamplesorstreamshavetobecreatedwithFSOUND_HW2DorFSOUND_HW3D,andFSOUND_ENABLEFXforthistowork.IfyouareusingDirectX8,FSOUND_SetFrequencywillnotworkanymoreforthatsound,youcannotchangethepitchofaFXenabledsound.ThisisaDirectXlimitation.DirectX9doesnothavethislimitation.FSOUND_FX_Enablecannotbecalledifthesoundisplayingorlocked.IfFSOUND_FX_DisableisnotcalledeffectswillbuildupontopofeachothereverytimeFSOUND_FX_Enableiscalled.Oncethesearetakenintoaccount,youcangoforit!

Usingit

YouhavetousethepausefeatureofFSOUND_PlaySoundExforthisAPItowork.ThereasonforthisisDirectXneedsachannelresourceinhardwaretobeallocated,andsoactuallyPLAYED(butpaused)beforetheFXfunctionscansucceed.

Onceyouhaveitplayedbutpaused,youcanenablemultipleeffectsononechannel,andeventhesameeffectmultipletimesonthesamechannel,thenunpauseittohearwhathappens,butatthispointyoucannotenablemoreeffects.Ithastobepausedorrestarted.Youcanupdatetheparametersofeffectswhiletheyareplayingorwhileitispaused.

Hereisanexample

intchannel,echoid,echoid2;channel=FSOUND_PlaySoundEx(FSOUND_FREE,samp2,DrySFXUnit,TRUE);

echoid=FSOUND_FX_Enable(channel,FSOUND_FX_ECHO);//enableechoandgetthefirstechohandleechoid2=FSOUND_FX_Enable(channel,FSOUND_FX_ECHO);//enableechoagainandgetthesecondechohandleFSOUND_FX_Enable(channel,FSOUND_FX_FLANGER);//enabletheflangeeffect,

don'tbotherwiththehandle,we'lljustusethedefaultparameters<

FSOUND_SetPaused(channel,FALSE);//nowstartthesoundplaying

FSOUND_FX_SetEcho(echoid,80.0f,70.0f,100.0f,100.0f,TRUE);//Altertheparametersofthefirstechoforthechannelitwasenabledon.Thishandleisuniquetothiseffectandthischannel.The2ndechoweenabledwillbeunaffected

Thisprocessmustberepeatedaswhenasoundisrestarted,allFXinformationisreset,soeffectsmustbeenabledeachtime.

FXonthe'output'channel.

Thisisaspecialfeaturewhichallowsyoutoenableeffectsontheoutputresultofthesoftwaremixedchannels!IfyouspecifyFSOUND_INIT_ENABLESYSTEMCHANNELFXXintheflagsfieldofFSOUND_Init.ThechannelIDtouseforalteringtheoutputresultisFSOUND_SYSTEMCHANNEL.CallFSOUND_SetPausedonthistoenableeffects.Thiswillstopallsoftwaremixedsoundeffects.

FSOUND_FX+SpectrumandDSP?.

TousetheFSOUND_FXapitodofxonchannelsrequiresFSOUND_HW2DorFSOUND_HW3D(andFSOUND_ENABLEFX)flagstowork.Youmaynoticeifyoudothis,youwilllosetheabilitytodoFSOUND_DSP_GetSpectrumoranyDSPunitwillnotregister,becauseFSOUND_FXchannelsplayinhardware,anddon'trunthroughtheFMODDSPEngine.

Thereisawaytodothisthough.InsteadofperformingEQonachannelbychannelbasis,performitontheglobalsoftwaremixoutput.

Thismeansyoucan'thaveperchannelcontrol,butifyouarejustlookingforawaytodoEQonyouraudioforexample,thenusethefollowingmethod.

CallFSOUND_SetBufferSize(100);WhenyoucallFSOUND_InitwithFSOUND_INIT_ENABLESYSTEMCHANNELFX(seestep2)youwillneedabigenoughsoftwareenginebuffertoallowFXtobeprocessed.FMODdefaultsto50whichistoosmall.ThisisalimitationofDirectSoundandneedstobetakencareof.UseFSOUND_INIT_ENABLESYSTEMCHANNELFXinFSOUND_Init.ThiswillreadythesoftwareengineoutputtohavetheFXapiusedonit.Pausethesoftwareengine.YoualwaysneedtopausethesourcewhenusingFSOUND_FX_Enable(seestep3),socallFSOUND_SetPaused(FSOUND_SYSTEMCHANNEL,TRUE);CallFSOUND_FX_EnabletocreateallyourFXhandles(EQ,distortionwhatever).Unpausethesoftwareengine.FSOUND_SetPaused(FSOUND_SYSTEMCHANNEL,FALSE);Nowyouareready!Createstreamsandsoundsinsoftwaremode(FSOUND_NORMAL-don'tuseFSOUND_HW2DorFSOUND_HW3D)

Nowthatallyoursoundsandstreamsareinsoftware,yougetspectrumanalysisback,andalsoyoucanusetheDSPengineforyourownsoftwareprocessingoroscilliscopeplotting-withtheaddedbenefitofFSOUND_FXprocessing!

THEFSBFORMAT,BANKS,STREAMSANDSENTENCING

Introduction

FMODIntroducesanewformatcalled.FSB,ortheFMODSampleBankformat.Thisformatisgeneratedbythesuppliedtool.FSBank(fsbank.exe).Itismainlyrecommendedforconsoleformats,butcanbeusedonanyplatform.ItisespeciallyrecommendedforPlayStation2,XBoxandGameCubeasitisamoreoptimalmethodofloadingsounddataintosoundramratherthanusingindividualsoundfileswhichisslowandinefficientwhencomingoffCD.

CompilingtheFSBfile

CreatinganFSBfile(ormultiplefsbfiles!)iseasy.Justopenthetoolcalledfsbank.exeprovidedinthetoolsdirectory.Currentlythisisonlyprovidedasawin32application.Youwillfindaninterfacelookingsomethinglikethis.

FSBankisveryeasytouse.YouhavetofirstdecidewhattypeofFSBfileoutputyouwanttogenerate.Themostcommonisa

single.FSBfilecontainingmultiplesounds.Thisisthedefaultandaccessiblebychoosing'GenerateSingleFSBFile'fromthepull-down'Build'menuasshowninthediagram.

SingleFSBfileYousimplytakeadirectoryofanysoundfiles,andspecifyasthe'SourceDirectory'field.Thentellthecompilerwheretobuildthefiletobychoosinga'DestinationFile'.Nowchooseaplatformtobuildto('ChooseTarget'fieldatthebottomofthescreen),andhitthebig'Build'button.Thisgeneratesasingle.FSBfile,andontopofthisitalsogivesyouaCheaderfiletoincludeintoyourprogramtoallowindexedaccesstothesounddatawithintheFSBfile.

MultipleFSBfilesThisissimilartobefore,butnowyoucangeneratemultiplefsbfilesinsteadof1file.Thisisonlyusefulforgeneratingmultiple.FSBfilestobeusedforstreaming(Thinkofitasabatchbuildforindividualstreams).NotethatyoucanuseasingleFSBfileasdescribedaboveforstreaming,butitislimitedduringplaybacktoonlyoneofthesoundsinthebankatatime.Yousimplytakeadirectoryofanysoundfiles,andspecifyasthe'SourceDirectory'field.Thentellthecompilerwheretobuildthefiletobychoosinga'DestinationDirectory'.Nowchooseatheplatformtobuildtoo('ChooseTarget'fieldatthebottomofthescreen),andhitthebig'Build'button.Thisgeneratesmultiple.FSBfiles,oneforeachsourcefile,andontopofthisitalsogivesyouaCheaderfileforeachoutputfile.

SingleInterleavedFSBFileThismodeallowsmultiplesoundfilestobeinterleavedinto1stream.Itonlygenerates1FSBentry,butasmonohas1channel,stereohas2channels,thesefilescanhaveupto16channelsofinterleavedaudio.Thedataismultiplexedinunitssuitabletothehardware(iePlayStation2willinterleavedataevery16bytes,36bytesonXBoxWhyisthisuseful?Wellwiththisfeature,youcouldget16channelsofplaybackwithnoseeking.Ifyouloadedandplayed16streamsindividuallyyouwouldnoticeaLOTofseekingwhichisinneficient,andcausesstutteringortheneedforhugebuffersizes,usinguplotsofRAM.Usinginterleavedstreamswillremoveseeking,andreducestreambuffersizes.Whywouldyouwanttohave16tracksofsoundgoingatonce?Wellthisisuptotheuser,butthemainbenefitsforthisare

Interactivemusic.Becausethesestreamsareinterleaved,italsomeanstheyareperfectlysynchronized.Youcanhavemultiplelayersofsoundtrackinterleaved,andforthedurationofthesong,themajorityofthechannelscanbesettovolume0,sotheyaremuted.Whenaneventorsituationarisesinthegameyoucanfadeupanddowndifferenttrackstobringinanewdrumbeatoroverlayforexample,addingmood.Multichannelambience.Thiswouldbepurelybeneficialforthetechnicalsideofstreaming,reducingtheamountofseekingandmemoryneededtoplaymultipleindividualstreams.Youcanhavemanytracksofhugeambiencedatastreamingatonce,and3dpositioneachsubchannelifyoulike,sostreamdatacomesinandoutdependingonlocationinthegameworldforexample.

Note:TheseinterleavedfilescanalsobestaticallyloadedusingtheFMUSICapi,andplayedbackas'samples'aswellasstreams,aslongasyouhaveenoughsoundram.

PlayStation2StreamsbenefitimmenselyfromFSBcompilingonPlayStation2.As.VAG(thenativeps2format)doesnotsupportstereodatanatively,.FSBovercomesthisbyinterleavingstereovagblocksintoeachother,thendeinterleavingitatruntimewhenstreaming.Thishasabenefitofnothavingtoplay2monostreamsatonce(panningoneleftandoneright),likeyoumighthavetowithotherplaybacksystems.

AccessingFSBfilesfromwithinyourprogram

Loadingan.FSBfileasastaticsoundbankintosoundramTodothis,youusetheFMUSIC_LoadSongorFMUSIC_LoadSongEx,andFMUSIC_GetSamplefunctions.BecausethesefunctionsalreadyexistedintheFMODapiformod,s3m,xm,it,midiitseemedappropriatetousethisAPIforFSBfiles,eventhoughtheyarestrictlynot'songs'.TheCheadergeneratedbytheFSBanktoolcontains#definesorindicestoreferenceeachindividualsoundfromyourcode,usingFMUSIC_GetSample.YoucansimplycallFSOUND_PlaySoundoneachofthesesamplehandlesyouretrievethroughtheFMUSICapiandmanipulatethemasyouwouldwithnormalsamples.

UseFMUSIC_GetNumSamplestodeterminethenumberofsamplesintheFSBformat.

YoucanmodifythewayallsoundsareloadedbyusingthemodeparameteroftheFMUSIC_LoadSongExfunction.Forexampleifyouwanttomakeallsoundshardware3dyoujustspecifytheFSOUND_HW3Dflag.Youcouldalsomakethemall2d,ormaybemakethemallloopwithFSOUND_LOOP_NORMAL.

OpeningamultisoundFSBfileasastreamThisisthesameasopeninganyotherstream.UseFSOUND_Stream_Open.Toaccessthesubsoundswithinthebankisdifferentthanwithsamples.Becauseitisastream,youcanonlyseekfromonesubsoundtoanother.ThisisachievedwithFSOUND_Stream_SetSubStream.Becausethisisaseekingaction,itwillstopthecurrentlyplayingstream,andperformtheseektothenewsound.YouwillhavetocallFSOUND_Stream_Playtogetittostartplayingagain.

Streamstitching,orsentencing

WhenplayinganFSBfileasastream,didyouknowyoucanstitchthemtogetheratruntimeusingFMOD'ssentencingengine.Thisallowsforabsolutelygapless,efficientstitchingofsounds,withnoneedforslowstoppingorstartingnewstreams,andtheorderofplaybackisdeterminedatruntime.Thisisgreatforvoiceovers,whereyoucanstringtogetherabunchofsoundstomakeasinglecoherentsentence.

Howisthisdoneincode?Thatiseasy.YoujustcallFSOUND_Stream_SetSubStreamSentencebeforeyoucallFSOUND_Stream_PlayorFSOUND_Stream_PlayEx.ie,sayyouhaveabankwithmultiplesoundsinit,withsoundsnippetslike"Brett","Andrew","Scored","Missed","OnePoint","TwoPoints!","ThreePoints!"

intlist[3]={SOUND_BRETT,SOUND_SCORED,SOUND_THREEPOINTS};FSOUND_Stream_SetSubStreamSentence(stream,list,3);FSOUND_Stream_Play(FSOUND_FREE,stream);

Thiswouldresultinaverysmooth"Brettscoredthreepoints!".

Didyouknow?

IfyouhaveloadedyourFSBfileasastaticsamplebank,youcancallFMUSIC_PlaySongtolistentothecontentsofthefile?Itwillplayeachsubsoundonebyone,whichisgreatforpreviews.

TROUBLESHOOTINGIntroduction

ThiswillcoversomeofthemostcommonproblemspeoplecomeacrosswhenusingFMOD.Rememberifyouhaveanyproblemsjustsendamailtosupport@fmod.org

FSOUND_InitfailsonCEdevices

Thissometimeshappensifthesounddeviceisalreadybusy,andthesoundhardwarewillnotreleaseitselftoFMODuntilitfinishesplayingasound.ThiscanhappenwhenactivesyncstartsupandplaystheconnectionnoisejustasFMODistryingtoinitialize.Toremedythisjustinitializefmodinaloopuntilitsucceeds,sleepingevery10or100msorhoweverlongyouprefer.Itisagoodideatotimeoutifitneversucceedsthenresolvetheissuethroughcheckingtheerrorcodeorstoppingtheprogramthatisstealingtheresource.ie.

intretrycount=0;while(!FSOUND_Init(22050,32,FSOUND_INIT_GLOBALFOCUS)&&retrycount<10){

Sleep(100);retrycount++;

}

if(retrycount==10){

/*Printerror*/}

Inthisexampleitwillkeepretryingforabout1seconduntilitexitsandprintsanerrormessage.

Stuttering/Skippingsound

Morecommonlyknownasbufferunderrun/overrun,thiscanbe1oracombinationoffactors

BadsoundcarddriversThismaybesolvedbyupgradingyoursoundcarddrivers.(Noteitisrecommendedyougetthelatestdriversanyway)

CPUissuesMachinetoslow,orwhateveryouraretryingtodowithFMODistoocpuintensive!(ieplaying100mp3'satoncewillmostlikelybringFMODtoitsknees,ormaybeauserstreamcallbackorDSPcallbackisspendingtoomuchtimeexecuting).

mailto:[email protected]

MixerbuffersizeissettoosmallYoucanincreasestabilitytocombattheseissues,byincreasingFMOD'sinternalmixingbuffersize.Thiswillleadtogreaterstabilitybutalsolargerlatencyonissuingcommandstohearingtheresult.CallFSOUND_SetBufferSizetoalterthisvalue(inmilliseconds).ItmustonlybecalledbeforecallingFSOUND_Init,itwillfailotherwise.Pleasedon'tsetthisvaluetohugenumberslike2000or10000.Itwon'thelpincreasestabilityandwillconsumelargeramountsofCPUtimeandRAM.Firsttryavalueof100,then150,then200,andnomore.

StreambuffersizeissettoosmallIfyouareusingthestreamAPI,youmightbestreamingoffaslowmedia,suchasCDROMorovernetwork,orevenafragmentedharddisk,andfmodneedsmoretimetofillitsstreamingbackbuffer.Forstreamingbuffers,fmoddefaultstoa400msstreambuffersize.Thisisseperatetothemixerbuffersizedescribedaboveandnotrelated.Changingthisvaluedoesnotalterlatency.Streamsarepre-bufferedandalwaysstartinstantlynomatterwhatthebuffersize.CallFSOUND_Stream_SetBufferSizetoalterthisvalue(inmilliseconds).Itmustonlybebeforeopeningastreamtotakeeffect.Settingthisvaluetolargevalueswillcauselargercpuspikes(ifacompressedformat)andmorememoryusage.Valuesaround1000to2000maxarerecommended.Largervaluesarenot.

VideoCardDriversYesvideocarddriverscanaffectsoundoutput.Alwaysmakesureyouhavethelatest3d/videocarddrivers,andthatyourusersareawareofthisaswell.IthasbeennotedthatabadVIDEOcarddrivercancausebreakupsandinstabilityinsoundoutput,astheyarebadlywrittenandcausethebustobetakenoverbythevideocard,notlettinganysounddatatobetransferredtothesoundcard.ThishasbeennotedonS3VirgeandVoodoo1driverssofar,soalwaysrememberfirsttohavetheLATESTvideodriver,andmakesureyounotethisinyourdocumentationaswellupondistribution.

Frame-rateistoohigh!Yesthiscanalsoaffectthesoundoutput,forthesamereasonsasdescribedabove.Excessivecallsofthevideodrivercanforcethesounddrivertonotbeserviced.Ithasbeenfoundthatintroducingaframe-ratelimiterwillsolvethisproblem.

OutputtypeFSOUND_OUTPUT_DSOUNDwillprovidemoresolidoutputthanFSOUND_OUTPUT_WINMMinanythingexceptNT.ThisisaproblemwithWindowsMultimediaServicesnotbeingasrealtimeasitshouldbe.UnderNTFSOUND_OUTPUT_WINMMismorestable,asDirectSoundinNTisjustemulatedbyusingWINMMitselfandisactuallyslowerandhaslongerlatency!.NOTE:Pleasedon'tfeeltheneedtouseFSOUND_SetOutputifyoudon'tneedto.FMODautodetectsthebestoutputmodebasedontheoperatingsystem.

USINGTHEFSOUND_NONBLOCKINGFLAG

Introduction

TheFSOUND_NONBLOCKINGflagstopscertainstreamormusiccommandsblockingthecallerwhenbeingexecuted,byperformingtheminaseperatethread.Mainlymeantforopeningstreamsandmusic,toavoidtheslownessofdiskaccessgeneratinghugepauses,thisflagmakesthesecommandsreturnimmediatelywithoutaffectingtheframe-rateatall!TheflagmustbespecifiedinFSOUND_Stream_OpenorFMUSIC_LoadSongExusingthemodeparameterforittowork.YoucannotuseSetModetypefunctionstomakeitwork,itmustbecalledatthetimeofopening.

Thisraisesnewissuesthough.YoucannotjustaccessastreamormusicfilethathasbeenopenedwiththeFSOUND_NONBLOCKINGflagimmediately!Youhavetowaitforittoopen!FMODdoesnot'queue'commandstononblockingstreams/musics.Thiscouldleadtomis-useandoverflows,orevenconfusionaboutthestateofthestreambehaviouratthetime,soapollingmethodispreferredsothattheusercancontrolexactlywhatoccursinwhatorder.

Pollingforsuccess

Thekeytoworkingwithnonblockingstreamsandmusicfilesistowaitforthemtoopenbeforeplayingthem.OnemethodtodothisistopollthestateofastreamusingFSOUND_Stream_GetOpenStateorFMUSIC_GetOpenState.Anothermethodistotryandplaythestreamoraccessthesubsoundscontinuouslyinagameloopuntilitsucceeds.

Whileanonblockingstreamisopening,nearlyallfunctionswillreturnanerrorcodetosignifythatthestreamisnotready.ThismeanssomethinglikeFSOUND_Stream_Playwillreturn-1whileitistryingtoopenthefileinthebackground.Whenitreturnsavalidchannelhandle,youknowitisreadyandhassucceeded!

Anexampleforplayinganonblockingstreamisprovidedbelow.Thisisatypicalloopthatshouldbeusedwhentryingtoplayanonblockingstream.Youwillnotice,onceitsucceeds,itwon'ttryandplayagainbecausechannelisnot-1anymore.

FSOUND_STREAM*stream;intchannel=-1;

stream=FSOUND_Stream_Open("mystream.fsb",FSOUND_NONBLOCKING,0,0);

do{

if(channel<0)

{channel=FSOUND_Stream_Play(FSOUND_FREE,stream);

}

GameCode();

}while(1)

AlternativelyyoucouldusetheFSOUND_Stream_GetOpenStatemethod.Thisisshownbelow.



do{

if(channel<0&&FSOUND_Stream_GetOpenState(stream)<0){

channel=FSOUND_Stream_Play(FSOUND_FREE,stream);}

GameCode();

}while(1)

Itisbasicallythesamethingandslightlyredundant.

FSBformat,substreamsandsentences.

SettingSubStreamsFSBhasmultiplesoundspackedwithinit,soyoumightwanttouseFSOUND_Stream_SetSubStreamYoudon'tneedtopolltogetFSOUND_Stream_SetSubStreamtowork.Ithasbeenoptimizedsothatitwillimmediatelyseektothecorrectsubstreamoncetheopenhasfinished.Thisisaspecialcaseforthisfunction,andnootherfunctionsallowthis.Thismeansyoucancallitstraightaway,evenafteranonblockingstreamopen.Hereisaversionoftheaboveloop,thatsetsasubstream.


stream=FSOUND_Stream_Open("mystream.fsb",FSOUND_NONBLOCKING,0,0);FSOUND_Stream_SetSubStream(stream,SOUND_4);

do{

if(channel<0){

channel=FSOUND_Stream_Play(FSOUND_FREE,stream);}

GameCode();

}while(1)

NotethatonceyoucallFSOUND_Stream_SetSubStream,thestreamis'notready'again.ThismaynotseemtoberelevantifyoucallitafterFSOUND_Stream_Open,becausewealreadyknewitwasnotgoingtobeready,butifyoucallitwhenthestreamhasactuallyfinishedopeningandisready(forexample,youmaywanttosetthesubstreamlongafterthestreamhasopened,ie30secondslater),thenyouwillneedtorememberthis,buttheabovelogicalwaystakescareofit.Youjustneedtosetchannelto-1intheaboveexamplewheneveryoucallFSOUND_Stream_SetSubStreamanditwillwork.

SettingSubStreamSentencesSettingasub-stream-sentenceisnext,andisslightlytrickier.FSOUND_Stream_SetSubStreamSentencedoesnotsucceedimmediatelylikeFSOUND_Stream_SetSubStream,andwillactuallyfailiftheopenisstillinprogress,soyoucannotcallitstraightafterFSOUND_Stream_Openlikewedidinthepreviousexample.Whatyouhavetodoispollforthestreamtobeinareadystate,thenexecuteFSOUND_Stream_SetSubStreamSentence.AlternativelyyoucancontinuallycallFSOUND_Stream_SetSubStreamSentenceuntilitsucceeds,abitlikewedidwiththecalltoFSOUND_Stream_Playinthepreviousexample.Notethefollowingcode

FSOUND_STREAM*stream;intchannel=-1;intsetsentence=0;


do{

if(!setsentence){

intsentence[2]={SOUND_4,SOUND_5};

setsentence=FSOUND_Stream_SetSubStreamSentence(stream,sentence,2);}elseif(channel<0){

channel=FSOUND_Stream_Play(FSOUND_FREE,stream);if(channel!=-1){

FSOUND_Stream_SetMode(stream,FSOUND_LOOP_NORMAL);//Thisisjusthereasanexample.

}}

GameCode();

}while(1)

Rememberatalltimes,youcanuseFSOUND_Stream_GetOpenStatejustaseffectivelyascontinuouslypollingthecommandyouwanttosucceed.Itisjustslightlylesscodeusingtheabovemethod.

Thingstolookoutfor

Ifyoususpectafilehasnotopened,orfailedtoopen,pollFSOUND_Stream_GetOpenState.Thiswillreturnthestateofthestream,andifithasfailed,itwillreturn-3.Notethateventhoughthestreamhasfailedtoopen,thestreamhandleisstillvalidwhenopeninginnon-blockingmode.Youwillneedtocloseit.

ThepointofFSOUND_NONBLOCKINGisthatittakesnocputimeawayfromthecaller.Thismeansitcannotcheckthevalidityofafile,asthatwouldconstitutediskaccess,whichcouldblockandcauseframestodropfromtheapplication.AlldiskaccessisdonefromtheFMODasynchronousloadingthread,soifitfails,theusercannotgetimmediatefeedback,theyhavetocheckthestatusseperately.Don'ttryandcloseastreambeforeitisready!Thiswillcauseamemoryleak,asFSOUND_Stream_ClosewillreturnFALSEbecauseitisnotready.Checkthedocumentationforeachstreamfunctiontoseeifitwillfailornotduetonotbeingreadyinanonblockingstate.

FMODANDMOVIEPLAYERSIntroduction

ThissectiondescribeshowtohaveFMODhappilycoexistwithvariousmovieplaybacksystemsavailable.

PlayStation2

ThemaincausesonconflictsbetweenothermiddlewarethatusesaudioortheIOP,andFMODare:

ConflictbetweentheSPU2DMAchannels.Thereare2ofthese.DMAchannel0andDMAchannel1.BydefaultFMODusesSPU2DMAchannel0forsoftwaremixing,andDMAcore1foruploadingsampledataandforstreamingto.ThismeansDMAcore1isusedwhenFMUSIC_LoadSong/FMUSIC_LoadSongExisbeingexecutedtoloadaPS2FSBfile,orstreamingusingFSOUND_Stream_Open/FSOUND_Stream_Play.Toworkaroundthisissueseethefollowingtips.

TurnofftheFMODsoftwaremixer.ThiswillfreeupDMAChannel0.Mostofthetimeyouarenotgoingtoneedthis.YoucandothisbyusingFSOUND_Initwithsoftwarechannelssetto0.SwapFMOD'smixer/uploadchannelusagearound.Ifthe3rdpartysoftwarestillusesDMAChannel1(thechannelFMODusesforbankuploadsandstreaming),youcaneitherchangeyour3rdpartysoftwaretouseDMAChannel0insteadofDMAChannel1,ortellFMODtoswapitsusagearoundbyspecifyingFMOD_INIT_PS2_SWAPDMACORES.Ifyoudidn'tturnthesoftwaremixeroff,thiswouldmakeFMODuseDMAChannel0forstreamsandsamplebankuploads,andDMAChannel1forthesoftwaremixer.

ConflictontheSIFCMDports.IfyourmiddlewareoryourowncodeisusingtheSIFCMDsonylibrarytocommunicatewiththeIOP,thenifyoudonttakecaretosharetheSIFCMDbuffersandportswithFMOD,messageswillgetlostandunexpectedbehaviourwilloccurinFMODandyour3rdpartysoftware.

Ifyouwanttoinitializeyour3rdpartysoftwareafterFMOD.UsethisinformationifthecodehasawaytosetupitsSIFCMDusage.NotethatFMODusesSIFCMDport0and1,andhasabuffersizeof16.Ifyouwanttoinitializeyour3rdpartysoftwarebeforeFMOD.IfFMODisinitializedfirst,callFSOUND_SetSifCommandInfofromfmodps2.h.AlsoloadyourFMOD.IRXorFMODSMALL.IRXwithcommandlineparameterstoallowtheIOPsidetogetthesameinformation.Formoredetailedinformationonthisseethecommentabovethefunctionprototypeinfmodps2.h.

SPU2ramusageandSPU2hardwarevoiceusage.BecauseFMODandthemiddlewaremightnotknowabouteachother,theymightallocatememoryoruseSPU2voiceswithoutanyregardfortheother.

UseFSOUND_SPU2_Alloc/FSOUND_SPU2_GetRawAddress/FSOUND_SPU2_Free.UsethesefunctionstoallocateSPU2memoryforyour3rdpartyapplication.ThiswayitwilluseFMOD'smemorymanager.UseFSOUND_SetReserved.Ifthe3rdpartysoftwareusesSPU2voices,youcanmarkthe

literalSPU2voiceindexasnottobeusedwithinFMOD.Ifthe3rdpartysoftwareusedSPU2voice0forexampleFMODwoulduseFSOUND_SetReserved(number_of_software_channels+0,TRUE);Notethatthesoftwarechannelsvalueismentionedbecauserawchannelindiciesare0to(maxnumsoftwarechannels-1)=softwarevoices,andafterthisarehardwarevoices.Ifyouhavethesoftwaremixerturnedoff,then0wouldbeSPU2voice0and47wouldbeSPU2voice47.

XBOX

ThemaincausesonconflictsbetweenothermiddlewarethatusesaudioontheXBox,andFMODare:

"DSOUND:CMcpxAPU::AllocateVoices:Error:Notenoughfreehardwarevoices".BydefaultFMODassumesitisintotalcontroloftheaudio,soitallocateseveryXBoxaudiovoice.Ifanother3rdpartysoftwareapplicationtriestoallocateahardwarevoiceitwillfail.

UseFSOUND_SetMaxHardwareChannels.TogetaroundthisissuejustcallFSOUND_SetMaxHardwareChannelstoreducethecount.XBoxhasaround192HW2Dvoicessoyoucouldreducethisandstillhaveplentyofvoicesfree.

DSPImageincorrect.FMODhasaninternalMCPDSPimagethatitloads.Itisstrippeddowntosavememory,(hundredsofkilobytes)byremovingunnescessaryfeatures.Thismayconflictwithother3rdpartysoftwarethatreliesonastandardDSPimagesuchasMicrosoft'sdsstdfx.bin.

UseFSOUND_SpecifyEffectsImage.Ifthe3rdpartymiddlewarehasadspimagefilethatitreliesonyoucanuseFSOUND_SpecifyEffectsImage(foundinfmodxbox.h)tomakeFMODusethatimage.MaketheothersoftwareuseFMOD'simage.YoucangetahandletoFMOD'sinternaldspimagestructurebycallingFSOUND_GetEffectImageDesc(foundinfmodxbox.h)ifthe3rdpartyhassuchafacilitytoallowthissortofexternalimagetobeused.

NeedsaccesstotheXBoxLPDIRECTSOUNDhandle.Ifthe3rdpartysoftwareisinitializedsecond,itmaywanttousetheXBoxLPDIRECTSOUNDhandle.

UseFSOUND_GetOutputHandle.IfyouneedtogetahandletoFMOD'sinternalDirectSoundpointer,youcanshareitbycallingFSOUND_GetOutputHandleandcastingittotheappropriatepointertype.

Win32

IfyouneedtogetahandletoFMOD'sinternalDirectSoundpointer,youcanshareitbycallingFSOUND_GetOutputHandleandcastingittotheappropriatepointertype.ThisalsogoesforXBoxandotherplatforms,anddependsonth

BinkonPS2

HereisaquickwaytogetFMODPS2andBinktoco-exist.

InitializeFMODfirst.

FSOUND_Init(48000,0,FSOUND_INIT_PS2_SWAPDMACORES);

FSOUND_SetReserved(0,TRUE);

InitializeBink

MovieBuffer=sceSifAllocIopHeap(RAD_IOPMemoryAmount(RAD_IOP_NEED_CORE1));RAD_IOPMemoryAmount(RAD_IOP_NEED_CORE1)));if(!RAD_IOPStartUp(1,2,MovieBuffer,RAD_IOP_NEED_CORE1|RAD_IOP_NO_INIT_LIBSD)){

sceSifFreeIopHeap(MovieBuffer);//error

}RAD_IOPHardwareVolumes(1,0x3fff,0x3fff,0x3fff,0x3fff);BinkSoundUseRAD_IOP(1);

PLAYSTATION2SPECIFICISSUES/FEATURES

Introduction

ThissectiondescribeshowtogetstartedwithFMODforPS2,andalsosomeofthePS2specificfeaturesavailable.

GettingStarted

Thissectiondescribeswhatyouwillneedtolink,andwhatyouneedtocalltogetupandrunningforPS2specifically.

Whattolinkandloadingmodules.

Link/api/lib/fmod.aintoyourproject.Put/api/fmod.irxintoyourmodulesdirectory.YouhavetoloadtheIRXyourselfusingsceSifLoadModule.Moreaboutthisfollows.

AsimplePlayStation2applicationhastodothefollowingtouseFMOD.

1.Loadfmod.irxandsony'slibsd.irx.Thisisdonefromhost0orcdrom0orwhateverfiledeviceyoustoreyourfileson.Loadlibsdfirst,thenfmod.

eg.while(sceSifLoadModule(host0:modules/libsd.irx",0,NULL)<0){

printf("loadinglibsd.irxfailed\n");}while(sceSifLoadModule("host0:modules/fmod.irx",0,NULL)<0){

printf("loadingfmod.irxfailed\n");}

Notethatthedefaultpositionforlibsd.irxisat/usr/local/sce/iop/modules/butitmaydifferonyourmachine.

Whatdoeseachmoduledo?libsd.irx-Thisisasonyirxthatcontainsthelowlevelhardwareroutinesneededbyfmod.irx.fmod.irx-Thisisthefmodlibraryandcontainsthemajorityofthefunctionality.

2.RemembertoInitializetheIOPheapwithsceSifInitIopHeap().ThisistobecalledafterthecalltosceSifInitRpc(0)andbeforeloadinganymodules.

eg.sceSifInitRpc(0);sceSifInitIopHeap();

WARNING!IfyoureboottheIOPyouhavetocalltheaboveagain!!!OtherwiseFMODwillfailtoinitialize.

3.CallFSOUND_InitandproceedprogrammingwiththeFMODAPIasyouwouldonanyotherplatform.OnPS2,youmustcallFSOUND_Updatetogetcommandstoissue.

Mismatchingfmod.aandfmod.irxversionsarenottolerated.FMODwillfailtoinitializeiftheyarefromdifferentreleasesofFMOD.

Release/Debug.

fmod.irxandfmodD.irxhavebeensupplied.fmodD.irxisdebug,andslower,andprintsoutalogofFMODprogress,alongwithenglishexplanationsonerrorsiftheyoccur.

Stripped/Nonstripped.

Youmaynoticethereisalsofmod_small.irxandfmodD_small.irx.TheseversionsuselessIOPramthanthefullversions,butonlybecausetheyhavefeaturesremoved.Thesefeaturesareremovedinthe_smallversions.

.MOD,.S3M,.XM,.IT,.WAVand.VAGsupport.Notefor.VAGsupport,thisistalkingaboutthefileformat,soFSB"VAG"supportstillexists.

Normalstreaming(withFSBfiles),3dsoundandsamplemanagementremains.

EEThreadPriority.

NotethatiftheEEmainthreadpriorityisnotchangedfromthedefaultof1,FMODwillchangeitto32.Nothreadcanstartwhenthedefaultpriorityis1sothisisnescessary.FMODuses1threadtoreceivemessagesfromtheIOP.

Formatssupported-hardware/software

FMODPS2supports.VAGand.WAV,althoughFSBisthehighlyrecommendedformat,seethenextsectiononFSBfilesformoreinformationaboutthis..VAGismixedinhardwareand.WAVismixedinsoftware..WAVmixinginsoftwareusesIOPprocessingtime.Atthemoment,dependingonqualitysettings,FMODcanonlymixaround12-20channelsofPCMdataatonce.

.MOD.S3M.XMand.ITmusicformatsaresupported,andaremixedinsoftware.Againcurrentlyonlymodswith12-20channelsorlessarerecommendedduetotheCPUstrainon

the33mhzIOPprocessor.32channelmodsshouldbesupportedaftermoreoptimizations.

SoftwaremixingspeedontheIOP.

UsingFSOUND_Mixerwithoneofthefollowingcontrolsthenumberofchannelsavailableinsoftware.Rememberhardwaremixingispreferredsoyoumaynothavetoencounterthisissue.

-FSOUND_MIXER_AUTODETECT(noninterpolatingstereooutput-fast)-FSOUND_MIXER_QUALITY_AUTODETECT(highqualityinterpolatingstereooutput-slowest)-FSOUND_MIXER_MONO(noninterpolatingmonooutput-fastest)-FSOUND_MIXER_QUALITY_MONO(highqualityinterpolatingmonooutput-slow)

FSOUND_InitonthePS2accepts24000or48000.24000islowerqualitybutincreasesthepossiblechannelcountsignificantly.FMODwillnotsupportotheroutputrates!Donottryandusethem!(erroneousratesjustcasetheoutputratetogoto48000)

TheFSBformat-Therecommendedformatforsamplesandstreams.

Although.WAVand.VAGformatsaresupported,forloadingspeed,andstreamingspeeditishighlyrecommendedtouse.FSBfiles.FSBishardwareaccelerated,WAVisnot.

ThesearecompiledbatchesofnativePlayStation2SPU2sounddata,arrangedsowhenloaded,itisonereadtoloadtheheadersfirst,thentherawvagdata(whichiscontinuous),whichisstreamedintoSPU2ram.Thisisthefastestwaytoloadsounddata.

Memorymanagment.

IOPMemory.

UponcallingFSOUND_Init,FMODallocatesALLremainingmemoryontheIOP.ThisissoFMODcanstoresoundsinIOPramifneeded.IfyouwanttolimitFMOD'sIOPmemoryusage,simplycallFSOUND_SetMemorySystem.

ie.FSOUND_SetMemorySystem(NULL,128*1024,NULL,NULL,NULL);

ThiswillforceFMODtoonlyuse128kbofIOPmemory.NotethatsettingtoolowavaluewillcauseFMODtofailinitsinternalsystemmemoryallocationsandFSOUND_Initcouldevenfail.

EEMemory.

TheEEmemoryfootprintisminimal.ThereisnodynamicmemoryallocationontheEE.TheEElibraryissimplyacommandlayerwrappingallFMODapifunctions,andusesnothingbutstaticstructuresandmemorytoavoidmalloc/free/new/deleteissuesontheEEside.ItusesthislibrarytopasscommandstotheIOPforprocessingonthatCPU.

Reverb.

YouhaveaccesstothehardwarePlayStation2SPU2reverbthroughFMOD'sFSOUND_Reverb_xxxAPI.NotethattheSPU2ReverbisalotmoreprimitivethanI3DL2reverbandEAX3.IntheFSOUND_REVERB_PROPERTIESstructure,onlyEnvironment,RoomandFlagsaresupported.

'Environment'Thisisavaluebetween0and9mappingtothesonyreverbmodes.Youwillfind9specialpresetsforthePlayStation2withthisenvironmentvaluesetaccordingly.ieFSOUND_PRESET_PS2_ROOMFSOUND_PRESET_PS2_STUDIO_AFSOUND_PRESET_PS2_STUDIO_BFSOUND_PRESET_PS2_STUDIO_CFSOUND_PRESET_PS2_HALLFSOUND_PRESET_PS2_SPACEFSOUND_PRESET_PS2_ECHOFSOUND_PRESET_PS2_DELAYFSOUND_PRESET_PS2_PIPETheotherpresetswillnotwork,exceptforFSOUND_PRESET_OFF.

'Room'Thisstillcontrolstheamountofreverbmixedintotheoutput.Normallyitisindecibels,between-10000(silent)and0(fullvolume),anditisthesamerangeonthePlayStation2,butitisalinearscalebetween-10000and0,notalogarithmicone.

'Flags'ThisonlyutilizesthefollowingfieldsonPlayStation2.FSOUND_REVERB_FLAGS_CORE0(hardwarevoices0to23)FSOUND_REVERB_FLAGS_CORE1(hardwarevoices24to47)ThistellstheFMODenginewhichcore,orsetofhardwarevoicestoapplythereverbsettingsto.Bydefault(inthepresets)itissettoapplytobothcores,butyoucanremovetheseflagstocontroleachcoreseperately.

NotethatFSOUND_Reverb_SetChannelPropertiesissupportedthroughthe'Room'parameteronly,andthatthisvalueisbinary,ie-10000is'reverboff'forthechannel,andanythingelseis'reverbon'.

FSOUND_SetDiskBusy

Thisfunctionisusuallynotoptionalandisessentialforsmoothrunningdiskcooperationbetweenfmodandthegame.Thisfunctioncausesmutualexclusionforthecdromorhost0sothatyoudon'tgetreaderrorswhentryingtoaccessthediskwhilefmodisplayingastreamoraccessingthediskinsomemanner(ieopeningabankorstreaminFSOUND_NONBLOCKINGmode)Inyourgamecodeyouwoulddosomethinglikethis:

FSOUND_SetDiskBusy(TRUE);sceRead(...);

FSOUND_SetDiskBusy(FALSE);

ThiswillblockonasemaphoreinFSOUND_SetDiskBusy(TRUE)iffmodisusingthedisk,andifitentersandexecutesthesceRead/sceCdRead,fmodwillnotaccessthedisk,andinsteadwaituntilitisavailabletouseagain.Note-ifyousetthisfortoolong,audiostreamsmaystarttoskip/stutter,becauseFMODdidntgetenoughtimetofillitsaudiobuffer.Makesureyoueithersplitupyourownreadsintosmallerchunks,ormakeabiggerbuffersizeforFMODtousewithFSOUND_Stream_SetBufferSize.

DolbyPrologic2output

UseFSOUND_SetSpeakerMode(FSOUND_SPEAKERMODE_PROLOGIC2)orFSOUND_SetSpeakerMode(FSOUND_SPEAKERMODE_PROLOGIC2_INTERIOR)toenable5.1surroundsoundonps2.Theinteriormodeusestwiceasmanyhardwarevoices(meaningyoueffectivelyonlyget24voicesinsteadof48),butallowssoundstosmoothlymovefromlefttorightandviceversa,wherethenormalmodewill'jump'fromonespeakertotheotherifrunningstraightalongtheXaxis.Itisatradeoffbetweenvoicesandquality,ifyouneedto,youshouldevaluatebothmethodstoseewhichworksbetter.Noteonastereosoundsystem,theinterior2voicemethodwillcauseaphasingeffect,whichcansoundoddorbad,itisreallymeantforaprologic2system.

Volumeramping

Mostgamesreleasedontheps2(notusingFMOD)makeclickandpopnoisesbecausethehardwaredoesn'tsupportsmoothvolumeorpanchanges.FMODhasimplementedanadvancedrampingsystemthatnotmanypeopleknowaboutoraretooputoffbythedifficultyofthemethod.YoucanenablethisasaflaginFSOUND_InitusingtheFSOUND_INIT_PS2_USEVOLUMERAMPINGflag.Turningthisonwillreducehardwareclicksorremovethem,producingcleansoundingaudio,givingyouanadvantageoveryourcompetitors!

XBOXSPECIFICISSUES/FEATURES

Introduction

ThissectiondescribeshowtogetstartedwithFMODforXBox,andalsosomeoftheXBoxspecificfeaturesavailable.

GettingStarted

Thissectiondescribeswhatyouwillneedtolink,andwhatyouneedtocalltogetupandrunningforXBoxspecifically.

FMODcomeswith2libraries.Oneisreleaseandoneisdebug.Themaindifferenceisthatthedebugversionoutputsdebuginformationtothedebugwindowofyourdebugger.ThisisusefulfortracingwhatfmodisdoingifsomethingeverwentwrongandyouwantedtoknowwhereFMODwasatthetime.

/api/lib/fmodxbox.lib-Thisisthelibraryyouwilllinktomostofthetime.Usethisforshipping./api/lib/fmodxboxD.lib-ThisisdebugversionofFMOD.Itisslower,andprintsoutalogofFMODprogressthroughthedebugwindow,alongwithenglishexplanationsonerrorsiftheyoccur.

MemoryManagement

OnFMODXBox,youmustcallFSOUND_SetMemorySystem,andsupplyapoolofmemorywithalength.

forexample.

#defineAUDIO_MEMLENGTH(4*1024*1024)char*mem=malloc(AUDIO_MEMLENGTH);FSOUND_SetMemorySystem(mem,AUDIO_MEMLENGTH,NULL,NULL,NULL);

then,

FSOUND_Init(....);etc.

Thereasoningforthisisforperformanceissues.FMODmustbeabletoaccesssampledatawithinitsownmemoryblocktoavoidaslowdownissueinDirectSoundXBox.

Thememoryprovidedmustbeenoughtostoreallsamplesandextrasystemmemoryoverheadfor

FMOD.

YoucancallFSOUND_GetMemoryStatstodeterminewhatFMODneedsasagameruns.YoucouldrunFMODandsupplyitwithanunrealisticallyhighmemorypool(say8megabytes),andthencallFSOUND_GetMemoryStatstodeterminethemaximumamountofRAMfmodneedstostoresoundsandforFMODsystemoverhead.

8mbMemoryLimitation.

Currentlyforhardwaresoundeffects,thereisan8mblimitforsoundeffects.ThisisduetotheXBoxDirectSoundarchitecture.

FromtheXDKDocumentation:"DirectSoundbuffersaremanagedinascattergatherentry(SGE)list.Thereisamaximumof2,047SGEs,whicheachpointtoa4-KBpage.Thismeansthatamaximumof8MBareavailableforallocatingorplayingDirectSoundbufferssimultaneously"

Futureversionsmayhavemultiple8mbpoolsifitisrequiredbydevelopers.

SpecialfeaturesforFMODXBox

FMODisfullyfunctionalontheXBox,includingwma,mp3andoggvorbisstreamingsupport,andwithsomeextrafunctionalitytotakeadvantageofthe5.1DolbyDigitalsurroundsoundsupport.

FSOUND_SetLevels.(Seefmodxbox.h).Thisfunctionallowsyouputpositionasoundinanyofthe5.1speakerarrayindolbydigital.Thiscanbeveryuseful,andyoucanevendocoolthingslike5.1musicwithit.Forexample,useFSBanktoproducea6channel,multichannelinterleavedstream,thenuseFSOUND_GetSubChanneltopositionall5channelsintotheirownspeaker.ie

channel=FSOUND_Stream_PlayEx(FSOUND_FREE,stream,0,TRUE);FSOUND_SetLevels(FSOUND_GetSubChannel(channel,0),255,0,0,0,0,0);FSOUND_SetLevels(FSOUND_GetSubChannel(channel,1),0,255,0,0,0,0);FSOUND_SetLevels(FSOUND_GetSubChannel(channel,2),0,0,255,0,0,0);FSOUND_SetLevels(FSOUND_GetSubChannel(channel,3),0,0,0,255,0,0);FSOUND_SetLevels(FSOUND_GetSubChannel(channel,4),0,0,0,0,255,0);FSOUND_SetLevels(FSOUND_GetSubChannel(channel,5),0,0,0,0,0,255);FSOUND_SetPaused(channel,FALSE);

Amusicianwouldhavetoproduct6wavfilesforeachspeakerinthiscasebeforeitisinterleavedwithFSBankintoonestream.

Evenifyoudontgotothisextent,youcandosomethingsimplelikespatializenormalstereomusic.Normallymusicisjustplayedthroughthefront2channels,soyoucanimprovethiswithsomethinglike

FSOUND_SetLevels(musicchannel,255,255,255,128,128,255);

whichputsitinallspeakersandhalfvolumeintherears.

GAMECUBESPECIFICISSUES/FEATURES

Introduction

ThissectiondescribeshowtogetstartedwithFMODforGamecube

Compilingandlinking

Includefmod.hinyourproject,thisisfoundinapi/inc.

TolinkFMODtoyourproject,therearethefollowingfiles./api/lib/fmodgc.lib-LinktothisfileifyouareusingSNSystemscompiler./api/lib/fmodgcD.lib-Thisisthedebugversionoffmodgc.libandoutputsalogofFMOD'sprogressandanyerrormessages(inplainenglish)totheTTY./api/lib/fmodgc_cw.a-LinktothisfileifyouareusingtheMetrowerksCodewarriorcompiler./api/lib/fmodgc_cwD.a-Thisisthedebugversionoffmodgc_cw.libandoutputsalogofFMOD'sprogressandanyerrormessages(inplainenglish)totheTTY.

Runningtheexamples

Simplyloadtheir.dspfilesintoDevStudioandhitF7.

NOTE:Youwillneedtocopyallfilesinthemediadirectoryto$DVDROOT/fmod.Forexample:

copymedia\*.*c:\DolphinSDK1.0\dvddata\fmod

Conversiontools

dspadpcm.exe

FMODsupportstheNintendoDSPADPCMformatasoutputbytheNintendotool"dspadpcm.exe".FMODexpectsthefileextension".dsp"onthesefiles.Forclarityandconsistency,FMODreferstothisformatasFSOUND_GCADPCM.NOTE:dspadpcm.execanonlyconvertMONOsamples!

fsbank.exe

ThisisaWindowsappthatcreates.fsbfiles-FMOD'snativesamplebankformat.UseittocreatesamplebanksofeitherMONOorSTEREOADPCMsamplessuitableforplayingorstreamingusingtheGameCubeADPCMhardware.

PerformanceissuesandGamecubespecificFMODfeatures.

Hardwarevoicedropping

DuetoadesignissuewiththeGamecubehardware,theprocessorwilldrophardwarevoicesifit'sDSPchipgetsoverloaded.CallFSOUND_UpdateeachgamecycleandFMODwillautomaticallyreacquirevoicesthatgetdropped.FMOD'sprioritysystemhasbeenlinkedintothis,soitislikelytodroplowerprioritysoundsthathavetheirprioritysetwithFSOUND_Sample_Defaults.

DirectDVDstreamingUseFMOD'sstreamAPItoplaystreamsusingtheGameCube'sDVDaudiostreamingcapability.Whenopeningastream,simplyspecifyafilewitha.adpextensionandFMODwillstreamitusingtheGameCube'shardwarestraightfromtheDVDtotheAI,completelybypassingbothARAMandMRAM.

Gamecubeextras

Lookinfmodgc.hforGameCube-specificfunctionsrelatingtosuchthingsasDVDstatuscallbacks,AUXeffects,specifyingablockofARAMforFMODtouseandaccessingIPLsoundsettings.

PLAYSTATIONPORTABLESPECIFICISSUES/FEATURES

Introduction

ThissectiondescribeshowtogetstartedwithFMODforPSP,andalsosomeofthePSPspecificfeaturesavailable.

GettingStarted

Thissectiondescribeswhatyouwillneedtolink,andwhatyouneedtocalltogetupandrunningforPSPspecifically.

Whattolinkandloadingmodules.

AsimplePlayStationPortableapplicationneedsthefollowingstepstobetakentouseFMOD.

Link/api/lib/fmod.aintoyourproject.

FMODrequiresthefollowingsonylibrariesandmodulestobeusedaswelltogetaudiosupport.Theyarelinkedandloadedbytheuser.

Linklibrarylibsas.aintoyourproject.Linkweakimportstublibraryfilelibatrac3plus_stub_weak.aintoyourproject.Loadmodulefilesc_sascore.prxatruntime.

IfyourequireAT3playbacksupport,loadthefollowingsonyrun-timemodules.

Loadmodulefilelibatrac3plus.prxLoadmodulefilelibaudiocodec.prx

Notethatthedefaultpositionforsc_sascore.prxandaudiocodec.prxisat/usr/local/devkit/kmodulebutitmaydifferonyourmachine.libatrac3plus.prxcanbefoundnormallyat/usr/local/devkit/module.

Loadingthemodules.

Forexamplesonhowtoloadsonymodules,seetheFMODexamples.Loadsony'ssc_sascore.prx.IfAT3supportisdesiredalsoloadaudiocodec.prxandlibatrac3plus.prx.Thisisdonefromhost0ordisc0orwhateverfiledeviceyoustoreyourfileson.

eg./*loadmodule*/

staticSceUIDload_module(constchar*filename,SceKernelLMOption*lm_opt,SceKernelSMOption*sm_opt){

SceUIDmid;intret;

/*loadmodule*/mid=sceKernelLoadModule((char*)filename,0,lm_opt);if(mid<0){

printf("fatalerror:cannotload%s0x%08x\n",filename,mid);returnmid;

}

/*startmodule*/if((ret=sceKernelStartModule(mid,0,NULL,NULL,sm_opt))<0){

printf("fatalerror:cannotstart%s0x%08x\n",filename,ret);returnret;

}

returnmid;}

...

SceKernelLMOptionkMode;SceUIDsasMid;

sasMid=0;

kMode.size=sizeof(kMode);kMode.mpidtext=SCE_KERNEL_PRIMARY_KERNEL_PARTITION;kMode.mpiddata=SCE_KERNEL_PRIMARY_KERNEL_PARTITION;kMode.position=SCE_KERNEL_LMWO_POS_Low;kMode.access=SCE_KERNEL_LMWO_ACCESS_Noseek;

sasMid=load_module("host0:/usr/local/devkit/kmodule/sc_sascore.prx",&kMode;,NULL);if(sasMid<0){

printf("fatalerror:loadSASmodule\n");return-1;

}

InitializeFMOD.

CallFSOUND_InitandproceedprogrammingwiththeFMODAPIasyouwouldonanyotherplatform.

Release/Debug.

fmod.aandfmodD.ahavebeensupplied.fmodDisdebug,andslower,andprintsoutalogofFMODprogress,alongwithenglishexplanationsonerrorsiftheyoccur.

Stripped/Nonstripped.

Youmaynoticethereisalsofmod_small.aandfmodD_small.a.Theseversionsuselessramthanthefullversions,butonlybecausetheyhavefeaturesremoved.Thesefeaturesareremovedinthe_smallversions.

.MOD,.S3M,.XM,.IT,.WAVand.VAGsupport.Notefor.VAGsupport,thisistalkingaboutthefileformat,soFSB"VAG"supportstillexists.

Normalstreaming(withFSBfiles),3dsoundandsamplemanagementremains.

Formatssupported-hardware/software

FMODPSPsupports.VAGand.WAV,althoughFSBisthehighlyrecommendedformat,seethenextsectiononFSBfilesformoreinformationaboutthis..VAGismixedinhardwareand.WAVismixedinsoftware..WAVmixinginsoftwareusesprocessingtime.Atthemoment,dependingonqualitysettings,FMODcanonlymixaround12-20channelsofPCMdataatonce.

.MOD.S3M.XMand.ITmusicformatsaresupported,andaremixedinsoftware.

Softwaremixingspeed.

UsingFSOUND_Mixerwithoneofthefollowingcontrolsthenumberofchannelsavailableinsoftware.Rememberhardwaremixingispreferredsoyoumaynothavetoencounterthisissue.

-FSOUND_MIXER_AUTODETECT(noninterpolatingstereooutput-fast)-FSOUND_MIXER_QUALITY_AUTODETECT(highqualityinterpolatingstereooutput-slowest)-FSOUND_MIXER_MONO(noninterpolatingmonooutput-fastest)-FSOUND_MIXER_QUALITY_MONO(highqualityinterpolatingmonooutput-slow)

FSOUND_InitonthePSPaccepts24000or48000.24000islowerqualitybutincreasesthepossiblechannelcountsignificantly.FMODwillnotsupportotheroutputrates!Donottryandusethem!(erroneousratesjustcasetheoutputratetogoto48000)

TheFSBformat-Therecommendedformatforsamplesandstreams.

Although.WAVand.VAGformatsaresupported,forloadingspeed,andstreamingspeeditishighlyrecommendedtouse.FSBfiles.FSBishardwareaccelerated,WAVisnot.

ThesearecompiledbatchesofnativePlayStationPortablesounddata,arrangedsowhenloaded,itisonereadtoloadtheheadersfirst,thentherawvagdata(whichiscontinuous),whichisstreamedintoRAM.ThisisthefastestwaytoloadsounddatafromUMD.

Memorymanagment.

Ifsodesired,theusercanlimitfmod'sRAMusagetoasingleblockofpre-allocatedmemory.IfyouwanttolimitFMOD'smemoryusageinthisway,simplycallFSOUND_SetMemorySystem.

ie.FSOUND_SetMemorySystem(NULL,128*1024,NULL,NULL,NULL);

ThiswillforceFMODtoonlyuse128kbofIOPmemory.NotethatsettingtoolowavaluewillcauseFMODtofailinitsinternalsystemmemoryallocationsandFSOUND_Initcouldevenfail.

StreamingATRACmusic

FMODsupportstheplaybackof.at3files.Alltheuserhastodoisplayitfromdisc0,oriftheylike,theycanloadthefileintomemory,thenuseFSOUND_OPENMEMORYtostreamthefilefrommemory.

NotethattheusercanuseFSOUND_Stream_SetBufferSizetoadjusttheamountofmemoryFMODuseswhenstreamingafile,andifitisfrommemory,thenitwillrequireonlyaverysmallstreambuffer.IfstreamingfromUMD,thebuffersizeneedtobealotlarger.Itshouldbethenumberofmillisecondsbetweeneachread,whichcouldbeanywhereupto5000ms.

Batteryconsiderations

Note,thateventhoughFMODsupportsstreamingmultiplestreamsfromUMDatonce,thisisnotrecommended.OnthePlayStationPortableseekingshouldbeavoidedatalltimestopreservemovementoftheumdreadheadandthereforebatterylife.Thisalsogoesfordatastreaming.Donotstreamdataandmusicatthesametimeifthereisseekinginvolved.Continuousseekingwilldegradebatterylifebecauseithastomechanicallymovetheseekhead.

Itmaybepreferabletoplay'inmemory'musicsuchassequencedformatslike.MOD/.S3M/.XMor.IT.AnotherideaistoloadanAT3fileintomemoryfirst,thenstreamthefilefrommemoryashasbeenmentionedpreviouslyinthisdocumentation.Asatraccanstoreaminuteofaudiopermbat128kbsstereo,thenyouwouldneed3mbofmemoryfor3minutesofmusic.

The"15-20%cpuproblem"

Someusersmaynoticeaframerateimpactwhenimplementingaudio.ThisisaknownissuewithSony,anditiscommonknowledgeamongPSPdevelopersthatsimplyplayingonesoundin'hardware'willcauseupto15-20%ofthePSP'sCPUtobeusedbyaudio.

TheproblemliesinSony'slibwave,andthereisnothingthatcanbedoneaboutitfromFMOD'ssideuntiltheissueisresolvedwithsony.FMODoffersasoftwaremixerthatcanbypassSony'sVAGroutines,butitwillstillrequirelibwaveaccesswhichistheproblem.

FSOUNDAPIReferenceFSOUNDApi.Usethistoplaysounds,streams,cd'setc

Functions,Structures,Defines,Enums

-Functions

FSOUND_3D_GetAttributesFSOUND_3D_GetMinMaxDistanceFSOUND_3D_Listener_GetAttributesFSOUND_3D_Listener_SetAttributesFSOUND_3D_Listener_SetCurrentFSOUND_3D_SetAttributesFSOUND_3D_SetDistanceFactorFSOUND_3D_SetDopplerFactorFSOUND_3D_SetMinMaxDistanceFSOUND_3D_SetRolloffFactorFSOUND_ALLOCCALLBACKFSOUND_CD_GetNumTracksFSOUND_CD_GetPausedFSOUND_CD_GetTrackFSOUND_CD_GetTrackLengthFSOUND_CD_GetTrackTimeFSOUND_CD_GetVolumeFSOUND_CD_OpenTrayFSOUND_CD_PlayFSOUND_CD_SetPausedFSOUND_CD_SetPlayModeFSOUND_CD_SetTrackTimeFSOUND_CD_SetVolumeFSOUND_CD_StopFSOUND_CloseFSOUND_CLOSECALLBACKFSOUND_DSP_ClearMixBufferFSOUND_DSP_CreateFSOUND_DSP_FreeFSOUND_DSP_GetActiveFSOUND_DSP_GetBufferLengthFSOUND_DSP_GetBufferLengthTotalFSOUND_DSP_GetClearUnitFSOUND_DSP_GetClipAndCopyUnitFSOUND_DSP_GetFFTUnit

FSOUND_DSP_GetMusicUnitFSOUND_DSP_GetPriorityFSOUND_DSP_GetSFXUnitFSOUND_DSP_GetSpectrumFSOUND_DSP_MixBuffersFSOUND_DSP_SetActiveFSOUND_DSP_SetPriorityFSOUND_DSPCALLBACKFSOUND_File_SetCallbacksFSOUND_FREECALLBACKFSOUND_FX_DisableFSOUND_FX_EnableFSOUND_FX_SetChorusFSOUND_FX_SetCompressorFSOUND_FX_SetDistortionFSOUND_FX_SetEchoFSOUND_FX_SetFlangerFSOUND_FX_SetGargleFSOUND_FX_SetI3DL2ReverbFSOUND_FX_SetParamEQFSOUND_FX_SetWavesReverbFSOUND_GetAmplitudeFSOUND_GetChannelsPlayingFSOUND_GetCPUUsageFSOUND_GetCurrentLevelsFSOUND_GetCurrentPositionFSOUND_GetCurrentSampleFSOUND_GetDriverFSOUND_GetDriverCapsFSOUND_GetDriverNameFSOUND_GetErrorFSOUND_GetFreeHWRamFSOUND_GetFrequencyFSOUND_GetLoopModeFSOUND_GetMaxChannelsFSOUND_GetMaxSamplesFSOUND_GetMemoryStatsFSOUND_GetMixerFSOUND_GetMute

FSOUND_GetNumDriversFSOUND_GetNumHWChannelsFSOUND_GetNumSubChannelsFSOUND_GetOutputFSOUND_GetOutputHandleFSOUND_GetOutputRateFSOUND_GetPanFSOUND_GetPausedFSOUND_GetPriorityFSOUND_GetReservedFSOUND_GetSFXMasterVolumeFSOUND_GetSpeakerModeFSOUND_GetSubChannelFSOUND_GetSurroundFSOUND_GetVersionFSOUND_GetVolumeFSOUND_InitFSOUND_IOP_AllocFSOUND_IOP_FreeFSOUND_IsPlayingFSOUND_METADATACALLBACKFSOUND_OPENCALLBACKFSOUND_PlaySoundFSOUND_PlaySoundExFSOUND_READCALLBACKFSOUND_REALLOCCALLBACKFSOUND_Record_GetDriverFSOUND_Record_GetDriverNameFSOUND_Record_GetNumDriversFSOUND_Record_GetPositionFSOUND_Record_SetDriverFSOUND_Record_StartSampleFSOUND_Record_StopFSOUND_Reverb_GetChannelPropertiesFSOUND_Reverb_GetPropertiesFSOUND_Reverb_SetChannelPropertiesFSOUND_Reverb_SetPropertiesFSOUND_Sample_AllocFSOUND_Sample_Free

FSOUND_Sample_GetFSOUND_Sample_GetDefaultsFSOUND_Sample_GetDefaultsExFSOUND_Sample_GetLengthFSOUND_Sample_GetLoopPointsFSOUND_Sample_GetMinMaxDistanceFSOUND_Sample_GetModeFSOUND_Sample_GetNameFSOUND_Sample_LoadFSOUND_Sample_LockFSOUND_Sample_SetDefaultsFSOUND_Sample_SetDefaultsExFSOUND_Sample_SetLoopPointsFSOUND_Sample_SetMaxPlaybacksFSOUND_Sample_SetMinMaxDistanceFSOUND_Sample_SetModeFSOUND_Sample_UnlockFSOUND_Sample_UploadFSOUND_SEEKCALLBACKFSOUND_SendDataFSOUND_SetBufferSizeFSOUND_SetCurrentPositionFSOUND_SetDiskBusyFSOUND_SetDriverFSOUND_SetFrequencyFSOUND_SetHWNDFSOUND_SetLevelsFSOUND_SetLoopModeFSOUND_SetMaxHardwareChannelsFSOUND_SetMemorySystemFSOUND_SetMinHardwareChannelsFSOUND_SetMixerFSOUND_SetMuteFSOUND_SetOutputFSOUND_SetPanFSOUND_SetPanSeperationFSOUND_SetPausedFSOUND_SetPriorityFSOUND_SetReserved

FSOUND_SetSFXMasterVolumeFSOUND_SetSpeakerModeFSOUND_SetSurroundFSOUND_SetVolumeFSOUND_SetVolumeAbsoluteFSOUND_SPU2_AllocFSOUND_SPU2_FreeFSOUND_SPU2_GetRawAddressFSOUND_StopSoundFSOUND_Stream_AddSyncPointFSOUND_Stream_CloseFSOUND_Stream_CreateFSOUND_Stream_CreateDSPFSOUND_Stream_DeleteSyncPointFSOUND_Stream_FindTagFieldFSOUND_Stream_GetLengthFSOUND_Stream_GetLengthMsFSOUND_Stream_GetModeFSOUND_Stream_GetNumSubStreamsFSOUND_Stream_GetNumSyncPointsFSOUND_Stream_GetNumTagFieldsFSOUND_Stream_GetOpenStateFSOUND_Stream_GetPositionFSOUND_Stream_GetSampleFSOUND_Stream_GetSyncPointFSOUND_Stream_GetSyncPointInfoFSOUND_Stream_GetTagFieldFSOUND_Stream_GetTimeFSOUND_Stream_Net_GetBufferPropertiesFSOUND_Stream_Net_GetLastServerStatusFSOUND_Stream_Net_GetStatusFSOUND_Stream_Net_SetBufferPropertiesFSOUND_Stream_Net_SetMetadataCallbackFSOUND_Stream_Net_SetProxyFSOUND_Stream_Net_SetTimeoutFSOUND_Stream_OpenFSOUND_Stream_OpenFromHandleFSOUND_Stream_PlayFSOUND_Stream_PlayEx

FSOUND_Stream_SetBufferSizeFSOUND_Stream_SetEndCallbackFSOUND_Stream_SetLoopCountFSOUND_Stream_SetLoopPointsFSOUND_Stream_SetModeFSOUND_Stream_SetPositionFSOUND_Stream_SetSubStreamFSOUND_Stream_SetSubStreamSentenceFSOUND_Stream_SetSyncCallbackFSOUND_Stream_SetTimeFSOUND_Stream_StopFSOUND_STREAMCALLBACKFSOUND_TELLCALLBACKFSOUND_UpdatesceSifAddCmdHandler

-Structures

FSOUND_REVERB_CHANNELPROPERTIESFSOUND_REVERB_PROPERTIESFSOUND_TOC_TAG

-Defines

FSOUND_CAPSFSOUND_CDPLAYMODESFSOUND_DSP_PRIORITIESFSOUND_INIT_FLAGSFSOUND_MISC_VALUESFSOUND_MODESFSOUND_REVERB_CHANNELFLAGSFSOUND_REVERB_FLAGSFSOUND_REVERB_PRESETSFSOUND_STATUS_FLAGS

-Enums

Thisdocumentcopyright©FirelightTechnologies,Pty,Ltd,1999-2002.Allrightsreserved.GeneratedFriNov1800:31:542005bySourceDocv0.10,theautomatedsourcecodedocumenter.

FMOD_ERRORSFMUSIC_TYPESFSOUND_FX_MODESFSOUND_MIXERTYPESFSOUND_OUTPUTTYPESFSOUND_SPEAKERMODESFSOUND_STREAM_NET_STATUSFSOUND_TAGFIELD_TYPE

[APIfunction]

FSOUND_DSPCALLBACK

CallbackdefinitionforDSPunits.

void*F_CALLBACKAPIFSOUND_DSPCALLBACK(void*originalbuffer,void*newbuffer,intlength,void*userdata);

Parameters

originalbuffer

ThisisthepointertotheoriginalbufferpassedintothefirstDSPunit.Thisisusefulifyouwanttheclean,originaldata,andyouhavebeenreturningnewmodifiedbuffersfortheDSPchaintouse.

newbufferThisisapointertothepreviousDSPbufferthat*it*returned.ThisbufferthatthisDSPreturnswillbepassedintothenewbufferparameteroftheNEXTunitintheDSPchain.

length ThelengthofthebufferprovidedinSAMPLES,notbytes.param AuserdatavaluespecifiedinFSOUND_DSP_Create.

ReturnValue

PointertoasamplebufferforthenextDSPunittouse.

Remarks

Youmustreturnthebufferyouworkon,oritwillnotbefedthroughtothenextDSPunit,andeventuallythethesystemclipandcopyunit,whichmakesthesoundaudible.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_DSP_Create,FSOUND_Stream_CreateDSP


[APIfunction]

FSOUND_STREAMCALLBACK

Callbackusedwithuserstreams.

signedcharF_CALLBACKAPIFSOUND_STREAMCALLBACK(FSOUND_STREAM*stream,void*buff,intlen,void*userdata);

Parameters

stream Pointertothestreaminquestion.

buff

fromFSOUND_Stream_Create-PointertothestreamdatabuffertowritetofromFSOUND_Stream_SetEndCallback-NULLfromFSOUND_Stream_SetSyncCallback-Pointertoastring

lenfromFSOUND_Stream_Create-LengthofbufferspecifiedinBYTES.fromFSOUND_Stream_SetEndCallback-0fromFSOUND_Stream_SetSyncCallback-0

param AuserdatavaluespecifiedfromFSOUND_Stream_Create,

ReturnValue

IfcreatedbyFSOUND_Stream_Create-Toallowthestreamtocontinue,TRUEisreturned.Tostopthestream,FALSEisreturned.ThereturnvalueisignoredifcreatedbyFSOUND_Stream_SetEndCallbackorFSOUND_Stream_SetSyncCallback--------------PlayStation2IMPORTANT!Forusercreatedstreamsonly.Theaddressfor'buff'isanIOPbasedaddress,youcannotdirectlyaccessit.YouhavetouseFSOUND_SendDatatoDMAyourdatafromtheEEtotheIOP.ifFSOUND_SendDataisNOTcalledfromthiscallbacktheIOPwillhangbecauseitiswaitingforthiscommandtobeexecutedbeforeitcanunlockits

bufferandsendittotheSPU.

Remarks

___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_SendData,FSOUND_Stream_Create,FSOUND_Stream_SetEndCallback,FSOUND_Stream_SetSyncCallback


[APIfunction]

FSOUND_ALLOCCALLBACK

Callbacktoallocateablockofmemory.

void*F_CALLBACKAPIFSOUND_ALLOCCALLBACK(unsignedintsize);

Parameters

size Sizeinbytesofthememoryblocktobeallocatedandreturned.

ReturnValue

Onsuccess,apointertothenewlyallocatedblockofmemoryisreturned.Onfailure,NULLisreturned.

Remarks

Returninganalignedpointer,of16bytealignmentisrecommendedforspeedpurposes.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_FREECALLBACK,FSOUND_GetMemoryStats,FSOUND_REALLOCCALLBACK,FSOUND_SetMemorySystem


[APIfunction]

FSOUND_REALLOCCALLBACK

Callbacktore-allocateablockofmemorytoadifferentsize.

void*F_CALLBACKAPIFSOUND_REALLOCCALLBACK(void*ptr,unsignedintsize);

Parameters

ptr Pointertoablockofmemorytoberesized.IfthisisNULLthenanewblockofmemoryissimplyallocated.

size Sizeofthememorytobereallocated.Theoriginalmemorymustbepreserved.

ReturnValue

Onsuccess,apointertothenewlyre-allocatedblockofmemoryisreturned.Onfailure,NULLisreturned.

Remarks

Returninganalignedpointer,of16bytealignmentisrecommendedforspeedpurposes.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_ALLOCCALLBACK,FSOUND_FREECALLBACK,FSOUND_GetMemoryStats,FSOUND_SetMemorySystem


[APIfunction]

FSOUND_FREECALLBACK

Callbacktofreeablockofmemory.

voidF_CALLBACKAPIFSOUND_FREECALLBACK(void*ptr);

Parameters

ptr Pointertoapre-existingblockofmemorytobefreed.

ReturnValue

void

Remarks

___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_ALLOCCALLBACK,FSOUND_GetMemoryStats,FSOUND_REALLOCCALLBACK,FSOUND_SetMemorySystem


[APIfunction]

FSOUND_OPENCALLBACK

Callbackforopeningafile.

void*F_CALLBACKAPIFSOUND_OPENCALLBACK(constchar*name);

Parameters

name Thisisthefilename.Youmaytreatthisasyoulike.

ReturnValue

Onsuccess,returnanon0number.Onfailure,return0.

Remarks

YouMUSTopenthefileandreturnahandleforfuturefilefunctioncalls.Castthehandletoanunsignedintwhenreturningit,theninothercallbacks,castitbackfromtheunsignedintbacktoyourownhandletype.Return0signifiesanopenerror.Thisisveryimportant.Itisagoodideaifyouareusingmemorybasedfileroutines,tostorethesizeofthefilehere,asitisneededtosupportSEEK_ENDintheseekfunction,describedbelow.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_CLOSECALLBACK,FSOUND_File_SetCallbacks,FSOUND_READCALLBACK,FSOUND_SEEKCALLBACK,FSOUND_TELLCALLBACK


[APIfunction]

FSOUND_CLOSECALLBACK

Calbackforclosingafile.

voidF_CALLBACKAPIFSOUND_CLOSECALLBACK(void*handle);

Parameters

handle Thisisthehandleyoureturnedfromtheopencallbacktouseforyourownfileroutines.

ReturnValue

void

Remarks

Closeyourfilehandleanddoanycleanuphere.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_File_SetCallbacks,FSOUND_OPENCALLBACK,FSOUND_READCALLBACK,FSOUND_SEEKCALLBACK,FSOUND_TELLCALLBACK


[APIfunction]

FSOUND_METADATACALLBACK

Callbacktoreceiveanewpieceofmetadatafromaninternetstream

signedcharF_CALLBACKAPIFSOUND_METADATACALLBACK(char*name,char*value,void*userdata);

Parameters

name Pointertothenameofthepieceofmetadata(null-terminatedASCIIstring)

value Pointertothemetadata(null-terminatedASCIIstring)

userdata UserdatathatwasspecifiedinFSOUND_Stream_Net_SetMetadataCallback

ReturnValue

Currentlyignored

Remarks

___________________Supportedonthefollowingplatforms:Win32,Macintosh,Linux

SeeAlso

FSOUND_Stream_Net_SetMetadataCallback


[APIfunction]

FSOUND_READCALLBACK

Callbackforreadingfromafile.

intF_CALLBACKAPIFSOUND_READCALLBACK(void*buffer,intsize,void*handle);

Parameters

buffer Youmustreadandcopyyourfiledataintothispointer.length Youmustreadthismanybytesfromyourfiledata.


ReturnValue

Returnthenumberofbytesthatwere*successfully*readhere.Normallythisisjustthesameas'length',butifyouareattheendofthefile,youwillprobablyonlyreadsuccessfullythenumberofbytesuptotheendofthefile(ifyoutriedtoreadmorethanthat).

Remarks

Youmustread'length'numberofbytesintothe'buffer'provided,thenifyouneedto,incrementyourfilepointer.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_CLOSECALLBACK,FSOUND_File_SetCallbacks,FSOUND_OPENCALLBACK,FSOUND_SEEKCALLBACK,

FSOUND_TELLCALLBACK


[APIfunction]

FSOUND_SEEKCALLBACK

Callbackforseekingwithinafile.

intF_CALLBACKAPIFSOUND_SEEKCALLBACK(void*handle,intpos,signedcharmode);

Parameters

handle Thisisthehandleyoureturnedfromtheopencallbacktouseforyourownfileroutines.pos Thisisthepositionoroffsettoseekbydependingonthemode.

mode Thisistheseekcommand.ItusesandiscompatiblewithSEEK_SET,SEEK_CURandSEEK_ENDfromstdio.h,sousethem.

ReturnValue

Ifsuccessful,theseekcallbackreturns0.Otherwise,itreturnsanonzerovalue.Ondevicesincapableofseeking,thereturnvalueisundefined.

Remarks

SEEK_ENDmustrepositionyourfilepointerattheENDofthefile,plusanynegativeoffset.Todothisyoumustknowthesizeofthefile,itissuggestedyoufindandstorethisintheopenfunction.RememberthataSEEK_ENDpositionvalueof-1isthelastbyte.Youmustresetyourfilepointerbasedonthecommandsgivenabove.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_CLOSECALLBACK,FSOUND_File_SetCallbacks,FSOUND_OPENCALLBACK,FSOUND_READCALLBACK,FSOUND_TELLCALLBACK


[APIfunction]

FSOUND_TELLCALLBACK

Callbackforreturningthecurrentfilepointerpositionwithinthefile.

intF_CALLBACKAPIFSOUND_TELLCALLBACK(void*handle);

Parameters


ReturnValue

Onsuccess,theoffsetwithinthefileinbytesisreturned.Onfailure,-1isreturned.

Remarks

Youmustreturntheoffsetfromthebaseofthefile,usingthisroutine.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_CLOSECALLBACK,FSOUND_File_SetCallbacks,FSOUND_OPENCALLBACK,FSOUND_READCALLBACK,FSOUND_SEEKCALLBACK


[APIfunction]

FSOUND_Close

ShutsdowntheWHOLEFMODSoundSystem.

voidF_APIFSOUND_Close();

ReturnValue

void

Remarks

Thisalsoclosesdownthesamplemanagementsystem,freeingallMANAGEDsamplesloaded(unlesstheywereallocatedwiththeFSOUND_UNMANAGEDflag).Streamsarenotfreed.Youmustclosethemyourself.CDTracksarestopped.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_CD_GetVolume,FSOUND_CD_SetVolume,FSOUND_Init,FSOUND_Sample_Alloc,FSOUND_Sample_Get,FSOUND_Sample_Load,FSOUND_SetBufferSize,FSOUND_SetDriver,FSOUND_SetHWND,FSOUND_SetMaxHardwareChannels,FSOUND_SetMemorySystem,FSOUND_SetMinHardwareChannels,FSOUND_SetMixer,FSOUND_SetOutput,FSOUND_SetSpeakerMode


[APIfunction]

FSOUND_File_SetCallbacks

SpecifyusercallbacksforFMOD'sinternalfilemanipulationfunctions.IfANYoftheseparametersareNULL,thenFMODwillswitchbacktoitsownfileroutines.Youcanreplacethiswithmemoryroutines(ienamecanbecasttoamemoryaddressforexample,thenopensetsupahandlebasedonthisinformation),oralternatefileroutines,ieaWADfilereader.

DLL_APIvoidF_APIFSOUND_File_SetCallbacks(FSOUND_OPENCALLBACKuseropen,FSOUND_CLOSECALLBACKuserclose,FSOUND_READCALLBACKuserread,FSOUND_SEEKCALLBACKuserseek,FSOUND_TELLCALLBACKusertell);

Parameters

OpenCallback Callbackforopeningafile.CloseCallback Callbackforclosingafile.ReadCallback Callbackforreadingfromafile.SeekCallback Callbackforseekingwithinafile..

TellCallback Callbackforreturningtheoffsetfromthebaseoftheopenfileinbytes.

ReturnValue

void

Remarks

MemoryloaderFMODfunctionsarenotaffected,suchasFMUSIC_LoadSongMemoryetc.WARNING:Thisfunctionisdangerousinthewronghands.Youmustreturnthe

rightvalues,andeachcommandmustworkproperly,orFMODwillnotfunction,oritmayevencrashifyougiveitinvaliddata.YoumustsupportSEEK_SET,SEEK_CURandSEEK_ENDproperly,orFMODwillnotworkproperly.SeestandardI/Ohelpfilesonhowtheseworkunderfseek().ReadthedocumentationinREMARKSanddoexactlywhatitsays.Seethe"simple"exampleforhowitisusedproperly.TheMIDIloaderdoesnotsupportuserfilecallbacks.ForWADtypedatastructureswithembeddedMIDIfilesFMUSIC_LoadSongMemorywillhavetobeused.--------------PlayStation2NOTE!ThisfunctiontakesIOPfunctionpointers,notEEpointers!ItisforcustomIOPfilesystemsnotEEbasedones.ThisfunctioncanonlybecalledafterFSOUND_InitonPlayStation2,notbefore.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,PlayStation2,XBox,GameCube

SeeAlso

FMUSIC_LoadSong,FSOUND_CLOSECALLBACK,FSOUND_Init,FSOUND_OPENCALLBACK,FSOUND_READCALLBACK,FSOUND_SEEKCALLBACK,FSOUND_TELLCALLBACK


[APIfunction]

FSOUND_Init

InitializestheFMODSoundSystem.

signedcharF_APIFSOUND_Init(intmixrate,intmaxsoftwarechannels,unsignedintflags);

Parameters

mixrate

Outputrateinhzbetween4000and65535.AnythingoutsidethiswillcausethefunctiontofailandreturnFALSE.PS2Note.Onlyratesof24000and48000aresupported.PSPNote.Onlyratesof22050and44100aresupported.SmartPhoneNote.Use22050ortheoperatingsystemmaycrashoutsideofthecontroloffmod.

maxchannels

MaximumnumberofSOFTWAREchannelsavailable.ThenumberofHARDWAREchannelsisautodetected.Thetotalnumberofchannelsavailable(hardwareandsoftware)afterinitializationcanbefoundwithFSOUND_GetMaxChannels.Havingalargenumberofmaxchannelsdoesnotadverselyaffectcpuusage,butitmeansithasthePOTENTIALtomixalargenumberofchannels,whichcanhaveanadverseeffectoncpuusage.1024isthehighestnumberthatcanbeset.Anythinghigherwillreturnanerror.

flags SeeFSOUND_INIT_FLAGS.Controlssomeglobalorinitializationtimeaspectsofplayback.

ReturnValue

Onsuccess,TRUEisreturned.Onfailure,FALSEisreturned.

Remarks

Youdonothavecontroloverhowmanyhardwarechannelsareavailabletoyou.Inalotofcasesitmaybe0(thesoundcarddoesnothavetheabilitytosupplyhardwarechannels).ThisiswhyitisusuallyagoodideatosupplyFSOUND_Initwithagoodnumberofsoftwarechannelstofallbackonto,forexample32.Hardwarechannelsare3Dhardwarechannelsonly.Thereisnobenefitinsupportinghardwarefor2dplaybackofsoundeffects.WithtodaysmachinesandFMOD'ssuperiormixingroutines,FMOD'ssoftwareenginecansometimesbefasterthanthedriver'shardwaresupport!___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Close,FSOUND_File_SetCallbacks,FSOUND_GetCurrentLevels,FSOUND_GetDriverCaps,FSOUND_GetFreeHWRam,FSOUND_GetMaxChannels,FSOUND_GetMemoryStats,FSOUND_GetOutputHandle,FSOUND_GetOutputRate,FSOUND_Init,FSOUND_INIT_FLAGS,FSOUND_PlaySound,FSOUND_PlaySoundEx,FSOUND_SetBufferSize,FSOUND_SetDriver,FSOUND_SetHWND,FSOUND_SetMaxHardwareChannels,FSOUND_SetMemorySystem,FSOUND_SetMinHardwareChannels,FSOUND_SetMixer,FSOUND_SetOutput,FSOUND_SetSpeakerMode,FSOUND_SPU2_Alloc,FSOUND_Stream_Play,sceSifAddCmdHandler


[APIfunction]

FSOUND_SetBufferSize

SetstheFMODinternalmixingbuffersize.Itisconfigurablebecauselowbuffersizesuselessmemory,butaremoreinstable.Moreimportantly,increasingbuffersizewillincreasesoundoutputstability,butontheotherhandincreaseslatency,andtosomeextent,CPUusage.*FMODchoosesthemostoptimalsizebydefaultforbeststability,dependingontheoutputtype-andifthedriversareemulatedornot(NT).Itisnotrecommendedchangingthisvalueunlessyoureallyneedto.YoumaygetworseperformancethanthedefaultsettingschosenbyFMOD.

signedcharF_APIFSOUND_SetBufferSize(intlen_ms);

Parameters

len_ms Thebuffersizeinmilliseconds.

ReturnValue

Onsuccess,TRUEisreturned.Onfailure,(ieifFMODisalreadyactive)FALSEisreturned.

Remarks

ThisfunctioncannotbecalledafterFMODisalreadyactivatedwithFSOUND_Init.ItmustbecalledbeforeFSOUND_Init,orafterFSOUND_Close.---------Thebuffersizesetingdefaultsto50msifitisnotcalledforDSOUND.Itdefaultsto200msforWindowsMultimediawave-outorforemulatedDirectSounddrivers(suchasNTdrivers).WhentheoutputisFSOUND_OUTPUT_ASIOthebuffersizeisignored.The

buffersizeshouldbeconfiguredusingtheASIOdriverwhichcanbedonewiththesuppliedasioconfig.exeintheFMODSDK.---------Buffersizeslowerthan50areclampedat50.BuffersizesarealsoroundedDOWNtothenearestmultipleof25.ThisisbecauseFMODmixesinblocksof25ms.Duetothisbuffersizecommandlatencyonsoftwarechannelswillbebetween25and50msonaverage(37.5ms)whenthebuffersizeissetto50.---------Macintosh,PlayStation2andGameCubedonotsupportthisastheyalreadyachieveminimallatencyandareforcedto25ms.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,XBox

SeeAlso

FSOUND_Close,FSOUND_DSP_GetBufferLengthTotal,FSOUND_Init


[APIfunction]

FSOUND_SetDriver

Selectsasoundcarddriver.Itisusedwhenanoutputmodehasenumeratedmorethanoneoutputdevice,andyouneedtoselectbetweenthem.

signedcharF_APIFSOUND_SetDriver(intdriver);

Parameters

driverno

Drivernumbertoselect.0willselecttheDEFAULTsounddriver.<0willselectanINVALIDdriverwhichwillcasetheDEVICEtobesettoanull(nosound)driver.>0SelectsothervaliddriversthatcanbelistedwithFSOUND_GetDriverName.

ReturnValue


Remarks

ThisfunctioncannotbecalledafterFMODisalreadyactivatedwithFSOUND_Init.ItmustbecalledbeforeFSOUND_Init,orafterFSOUND_Close.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Close,FSOUND_GetDriver,FSOUND_GetDriverName,FSOUND_GetNumDrivers,FSOUND_Init,FSOUND_SetOutput


[APIfunction]

FSOUND_SetHWND

Thisisanoptionalfunctiontosetthewindowhandleoftheapplicationyouarewriting,soDirectsoundcantellifitisinfocusornot.

signedcharF_APIFSOUND_SetHWND(void*hwnd);

Parameters

hwnd PointertoaHWNDwindowshandleofyourapplication.NULLmeansitwillpicktheforegroundapplicationwindow.

ReturnValue


Remarks

ThisfunctioncannotbecalledafterFMODisalreadyactivatedwithFSOUND_Init.ItmustbecalledbeforeFSOUND_Init,orafterFSOUND_Close.---------FMODusesGetForegroundWindowifthisfunctionisnotcalled.___________________Supportedonthefollowingplatforms:Win32,WinCE

SeeAlso

FSOUND_Close,FSOUND_Init


[APIfunction]

FSOUND_SetMaxHardwareChannels

Thissetsthemaximumallocatablechannelsonahardwarecard.FMODautomaticallydetectsandallocatesthemaximumnumberof3dhardwarechannels,socallingthiswilllimitthatnumberifitbecomestoomuch.

DLL_APIsignedcharF_APIFSOUND_SetMaxHardwareChannels(intmax);

Parameters

max Themaximumnumberofhardwarechannelstoallocate,evenifthesoundcardsupportsmore.

ReturnValue


Remarks

ThisfunctioncannotbecalledafterFMODisalreadyactivatedwithFSOUND_Init.ItmustbecalledbeforeFSOUND_Init,orafterFSOUND_Close.---------ThisfunctionhasnothingtodowithFSOUND_SetMinHardwareChannels,inthatthisisnotafunctionthatforcesFMODintosoftwaremixingifacardhasacertainnumberofchannels.Thisfunctiononlysetsalimitonhardwarechannels,soifyourcardhas96hardwarechannels,andyousetFSOUND_SetMaxHardwareChannels(10),thenyouwillonlyhave10hardwarechannelstouse.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Close,FSOUND_Init,FSOUND_SetMaxHardwareChannels,FSOUND_SetMinHardwareChannels


[APIfunction]

FSOUND_SetMemorySystem

SpecifiesamethodforFMODtoallocatememory,eitherthroughcallbacksoritsowninternalmemorymanagement.YoucanalsosupplyapoolofmemoryforFMODtoworkwithanditwilldosowithnoextracallstomallocorfree.ThisisusefulforsystemsthatwantFMODtousetheirownmemorymanagement,orfixedmemorydevicessuchasPocketPC,XBox,PS2andGameCubethatdontwantanyallocationsoccuringoutoftheircontrolcausingfragmentationorunpredictableoverflowsinatightmemoryspace.Seeremarksformoreusefulinformation.

DLL_APIsignedcharF_APIFSOUND_SetMemorySystem(void*poolmem,intpoollen,FSOUND_ALLOCCALLBACKuseralloc,FSOUND_REALLOCCALLBACKuserrealloc,FSOUND_FREECALLBACKuserfree);

Parameters

poolIfyouwantafixedblockofmemoryforFMODtouse,passitinhere.Specifythelengthinpoollen.SpecifyingNULLdoesntuseinternalmanagementanditreliesoncallbacks.

poollenLengthinbytesofthepoolofmemoryforFMODtousespecifiedin.Specifying0turnsoffinternalmemorymanagementandreliespurelyoncallbacks.Lengthmustbeamultipleof512.

useralloc OnlysupportedifpoolisNULL.OtherwiseitoverridestheFMODinternalcallstoalloc.Compatiblewithansimalloc().

userrealloc OnlysupportedifpoolisNULL.OtherwiseitoverridestheFMODinternalcallstorealloc.Compatiblewithansirealloc().

userfree OnlysupportedifpoolisNULL.OtherwiseitoverridestheFMODinternalcallstofree.Compatiblewithansifree().

ReturnValue

void

Remarks

FMODhasbeentestedtostayinalimitandfailgracefullyifthefixedpoolsizeisnotlargeenoughwithFMOD_ERR_MEMORYerrors.FMODonlydoesallocationwhencreatingstreams,musicorsamplesandtheFSOUND_Initstage.Itneverallocatesordeallocatesmemoryduringthecourseofruntimeprocessing.TofindouttherequiredfixedsizetheusercancallFSOUND_GetMemoryStatswithalargerthannescessarypoolsize(ornopool),andfindoutthemaximumramusageatanyonetimewithinFMOD.-------------------------------------FMODbehavesdifferentlybasedonwhatyoupassintothisfunctionin3differentcombinations.Herearetheexamples.NULL,0,NULL,NULL,NULL:FallsbackpurelytoansiCmalloc,reallocandfree.NULL,0,myalloc,myrealloc,myfree:Callsusersuppliedcallbackseverytimefmoddoesamemoryallocationordeallocation.ptr,len,NULL,NULL,NULL:Uses"ptr"andmanagesmemoryinternally.NOextramallocsorfreesareperformedfromthispoint.-------------------------------------Callbacksandmemorypoolscannotbecombined,asifapoolisspecifiedFMOD,manipulatesthepoolofmemoryinternallywithitsownallocateandfreescheme.ThememorymanagementalgorithmtoworkwithinafixedsizeoframisextremelyefficientandfasterthanthestandardCmallocorfree.-------------------------------------OnXBoxyouMUSTspecifyapointerandlength.Thememoryprovidedmustbeenoughtostoreallsampledata.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_ALLOCCALLBACK,FSOUND_Close,

FSOUND_FREECALLBACK,FSOUND_GetFreeHWRam,FSOUND_GetMemoryStats,FSOUND_Init,FSOUND_IOP_Alloc,FSOUND_REALLOCCALLBACK


[APIfunction]

FSOUND_SetMinHardwareChannels

ThissetstheminimumallowablehardwarechannelsbeforeFMODdropsbackto100percentsoftware.Thisishelpfulforminimumspeccards,andnothavingtoguesshowmanyhardwarechannelstheymighthave.ThiswayyoucanguaranteeandassumeacertainnumberofchannelsforyourapplicationandplacethemallinFSOUND_HW3Dwithoutfearoftheplaysoundfailingbecauseitrunsoutofchannelsonalowspeccard.

DLL_APIsignedcharF_APIFSOUND_SetMinHardwareChannels(intmin);

Parameters

min Theminimumnumberofhardwarechannelsallowableonacardbeforeitusesthesoftwareengine1004562604fthetime.

ReturnValue


Remarks

ThisfunctioncannotbecalledafterFMODisalreadyactivatedwithFSOUND_Init.ItmustbecalledbeforeFSOUND_Init,orafterFSOUND_Close.---------Asanexample,ifyousetyourminimumto16,youcannowsafelyguaranteethat16soundscanbeplayedatoncethatarecreatedwithFSOUND_HW3D.Thiswayifyoudocomeacrossacardthatonlysupports4channels,itwilljustdropbacktoplayingALLsoundsinsoftwaremode.Itmaysoundworse,butatleastitdoesntfailontheplaysound.(whichcould

soundevenworse!)___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Close,FSOUND_Init,FSOUND_SetMaxHardwareChannels


[APIfunction]

FSOUND_SetMixer

Setsadigitalmixertype.

signedcharF_APIFSOUND_SetMixer(intmixer);

Parameters

mixermixertype,seeFSOUND_MIXERTYPESforvalidparametersanddescriptions.

ReturnValue


Remarks

ThisfunctioncannotbecalledafterFMODisalreadyactivatedwithFSOUND_Init.ItmustbecalledbeforeFSOUND_Init,orafterFSOUND_Close.Thisfunctiondoesnotnescessarilyneedtobecalled,autodetectionwillselectthefastestmixerforyourmachine.Itishereifyouneedtotestallmixertypesfordebuggingpurposes,oramixerhasafeaturethattheautodetectedonedoesnt.(ielowqualitymixersorvolumeramping)___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Close,FSOUND_GetMixer,FSOUND_Init,FSOUND_MIXERTYPES


[APIfunction]

FSOUND_SetOutput

Setsupthesoundsystemoutputmode.

signedcharF_APIFSOUND_SetOutput(intoutputtype);

Parameters

outputtypeTheoutputsystemtobeused.SeeFSOUND_OUTPUTTYPESforvalidparametersanddescriptions.-1Isautodetectbasedonoperatingsystem.

ReturnValue


Remarks

ThisfunctioncannotbecalledafterFMODisalreadyactivatedwithFSOUND_Init.ItmustbecalledbeforeFSOUND_Init,orafterFSOUND_Close.-------UnderWindowsNT-WaveoutisFASTERthanDirectSound,achievesLOWERlatency,ANDisLESSbuggy.DirectSoundunderNTisachievedbyemulatingwaveout,andthereforeisinferiortowaveout.UseWAVEOUTunderNT.UnderWindows9xandW2K-DirectSoundisfasterthanwaveoutandcanachievelowerlatency.UseDIRECTSOUNDunderWin9xandW2K.-------IfyoudontcallFSOUND_SetOutput,FMODwillnowautodetectDSOUNDorWINMMbasedontheoperatingsystem.___________________

Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Close,FSOUND_GetDriverCaps,FSOUND_GetOutput,FSOUND_GetOutputHandle,FSOUND_Init,FSOUND_OUTPUTTYPES,FSOUND_SetDriver,FSOUND_SetOutput


[APIfunction]

FSOUND_SetPanSeperation

Setsthemasterpanseperationfor2dsoundeffects.

DLL_APIvoidF_APIFSOUND_SetPanSeperation(F_FLOAT_APIpansep);

Parameters

pansep Thepanscalar.1.0meansfullpanseperation,0meansmono.

ReturnValue


Remarks

Thisissetto1.0bydefault.Musicisnotaffectedbythis.Tochangepanseperationformusicfilesindividually,seeFMUSIC_SetPanSeperation___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_SetPanSeperation,FSOUND_GetSpeakerMode,FSOUND_SetSpeakerMode


[APIfunction]

FSOUND_SetSFXMasterVolume

Setsthemastervolumeforanysoundeffectsplayed.DoesnotaffectmusicorCDoutput.

DLL_APIvoidF_APIFSOUND_SetSFXMasterVolume(intvolume);

Parameters

volume Thevolumetoset.Validrangesarefrom0(silent)to255(fullvolume)

ReturnValue


Remarks


SeeAlso

FMUSIC_SetMasterVolume,FSOUND_SetVolume,FSOUND_SetVolumeAbsolute


[APIfunction]

FSOUND_SetSpeakerMode

Setsthemodefortheusersspeakersetup.

voidF_APIFSOUND_SetSpeakerMode(unsignedintspeakermode);

Parameters

speakermode Thisisanenumdescribingtheusersspeakersetup.

ReturnValue

void

Remarks

Note-OnlyreliablyworkswithFSOUND_OUTPUT_DSOUNDonwindows,orconsolessuchasPlayStation2,GameCubeandXBox.ForotheroutputtypesspeakermodeonlyinterpretsFSOUND_SPEAKERMODE_MONO,everythingelseisinterpretedasstere.----------------------------------Togettrue5.1dolbydigitalorDTSoutputyouwillneedasoundcardthatcanencodeit,andareceiverthatcandecodeit.----------------------------------Callingthiswillresetthepanseparationsetting.Itsetsitto0ifFSOUND_SPEAKERMODE_MONOischosen,and1otherwise.Youwillneedtoresetthepanseparationifrequiredafterwards.----------------------------------XBOXThisfunctionmustbecalledbeforeFSOUND_Inittochangethedefaultspeakermode.Tochangeonthefly,youmustclosedownFMODwithFSOUND_Closethenre-initializeitwithFSOUND_Init.IfitiscalledafterFSOUND_Init,onlyheadphonespeakermodeisinterpretedtoswitchheadphonemodeonandoff.Bydefaultthedashboardsettingisusedforthespeakermode.Itisnot

recommendyouchangethismodeunlessyoulettheuserchangeitin-game.----------------------------------PlayStation2.Onlymono/stereoandprologic2modesareinterpreted.DolbydigitalorDTSarenotsupported.Thisfunctionmustbecalledbeforeplayingsounds.CallingthisafterplayingasoundwillnotmakethatexistingsoundworkinPrologic2.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Close,FSOUND_GetSpeakerMode,FSOUND_Init,FSOUND_SetPanSeperation,FSOUND_SPEAKERMODES


[APIfunction]

FSOUND_Update

Thisupdatesthe3dsoundengineandDMAengine(onlyonsomeplatforms),andshouldbecalledonceagameframe.ThisfunctionwillalsoupdatethesoftwaremixerifyouhaveselectedFSOUND_OUTPUT_NOSOUND_NONREALTIMEasyouroutputmode.

voidF_APIFSOUND_Update();

ReturnValue

void

Remarks


SeeAlso

FSOUND_3D_Listener_SetAttributes,FSOUND_3D_Listener_SetCurrent,FSOUND_3D_SetAttributes,FSOUND_3D_SetDopplerFactor


[APIfunction]

FSOUND_GetCPUUsage

ReturnsinpercentofcputimetheamountofcpuusagethatFSOUND/FMUSICmixingistaking.

F_FLOAT_APIF_APIFSOUND_GetCPUUsage();

ReturnValue

floatingpointvaluebetween0.0and100.0.

Remarks

Thisvaluerepresentsthecpuusageusedbystreams,thesoftwaremixer,andsubsequentcallstodsoundwaveoutetc.MIDIplaybackisnotcountedasitisperformedbydirectx.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_Create


[APIfunction]

FSOUND_GetChannelsPlaying

ReturnsthenumberofactivechannelsinFSOUND,oronesthatareplaying.

intF_APIFSOUND_GetChannelsPlaying();

ReturnValue

Numberofactivechannels.

Remarks


SeeAlso

FMUSIC_OptimizeChannels


[APIfunction]

FSOUND_GetDriver

Returnsthecurrentlyselecteddrivernumber.DriversareenumeratedwhenselectingadriverwithFSOUND_SetDriverorotherdriverrelatedfunctionssuchasFSOUND_GetNumDriversorFSOUND_GetDriverName

intF_APIFSOUND_GetDriver();

ReturnValue

Currentlyselecteddriverid.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2

Remarks

Ifnodriverismanuallyselected,0isreturned,orthedefaultdriver.

SeeAlso

FSOUND_GetDriver,FSOUND_GetDriverName,FSOUND_GetNumDrivers,FSOUND_SetDriver


[APIfunction]

FSOUND_GetDriverCaps

Returnsinformationoncapabilitiesofthecurrentoutputmode.

signedcharF_APIFSOUND_GetDriverCaps(intid,unsignedint*caps);

Parameters

id EnumerateddriverID.ThismustbeinavalidrangedelimitedbyFSOUND_GetNumDrivers,

caps Pointertoanunsignedinttohavethecapsbitsstored.

ReturnValue


Remarks

ThisfunctioncannotbecalledafterFMODisalreadyactivatedwithFSOUND_Init.ItmustbecalledbeforeFSOUND_Init.FSOUND_SetOutputmustbecalledtotellFMODwhichoutputmodeyouaretalkingabout.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_CAPS,FSOUND_GetNumDrivers,FSOUND_Init,FSOUND_SetOutput


[APIfunction]

FSOUND_GetDriverName

Returnsthenameoftheselecteddriver.DriversareenumeratedwhenselectingadriverwithFSOUND_SetDriverorotherdriverrelatedfunctionssuchasFSOUND_GetNumDriversorFSOUND_GetDriver

constchar*F_APIFSOUND_GetDriverName(intid);

Parameters

id EnumerateddriverID.ThismustbeinavalidrangedelimitedbyFSOUND_GetNumDrivers,

ReturnValue

Onsuccess,apointertoaNULLterminatedstringcontainingthenameofthespecifieddeviceisreturned.ThenumberofdriversenumeratedcanbefoundwithFSOUND_GetNumDrivers.Onfailure,NULLisreturned.

Remarks

Ifnodriverisselected,thedefaultdriverisused.

SeeAlso

FSOUND_GetDriver,FSOUND_GetNumDrivers,FSOUND_SetDriver


[APIfunction]

FSOUND_GetError

ReturnsanerrorcodesetbyFMOD.

intF_APIFSOUND_GetError();

ReturnValue

errorcode,seeFMOD_ERRORS

Remarks


SeeAlso

FMOD_ERRORS,FSOUND_GetAmplitude,FSOUND_GetFrequency,FSOUND_GetPan,FSOUND_GetPriority,FSOUND_GetVolume


[APIfunction]

FSOUND_GetMaxSamples

Returnsthecurrentmaximumindexforasample.Thisfiguregrowsasyouallocatemoresamples(inblocks)

intF_APIFSOUND_GetMaxSamples();

ReturnValue

Maximumsampleindex

Remarks



[APIfunction]

FSOUND_GetMaxChannels

Returnsthetotalnumberofchannelsallocated.

intF_APIFSOUND_GetMaxChannels();

ReturnValue

Numberofchannelsallocated

Remarks


SeeAlso

FSOUND_Init


[APIfunction]

FSOUND_GetMemoryStats

Returnsinformationonthememoryusageoffmod.ThisisusefulfordeterminingafixedmemorysizetomakeFMODworkwithinforfixedmemorymachinessuchaspocketpcandconsoles.

DLL_APIvoidF_APIFSOUND_GetMemoryStats(unsignedint*currentalloced,unsignedint*maxalloced);

Parameters

currentalloced Currentlyallocatedmemoryattimeofcall.

maxalloced MaximumallocatedmemorysinceFSOUND_InitorFSOUND_SetMemorySystem

ReturnValue

void

Remarks

NotethatifusingFSOUND_SetMemorySystem,thememoryusagewillbeslightlyhigherthanwithoutit,asfmodhastohaveasmallamountofmemoryoverheadtomanagetheavailablememory.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_ALLOCCALLBACK,FSOUND_FREECALLBACK,FSOUND_GetFreeHWRam,FSOUND_Init,FSOUND_REALLOCCALLBACK,FSOUND_SetMemorySystem


[APIfunction]

FSOUND_GetNumDrivers

Returnsthenumberofsoundcardsordevicesenumeratedforthecurrentoutputtype.(DirectSound,WaveOutetc.)

intF_APIFSOUND_GetNumDrivers();

ReturnValue

Totalnumberofenumeratedsounddevices.

Remarks


SeeAlso

FSOUND_GetDriver,FSOUND_GetDriverCaps,FSOUND_GetDriverName,FSOUND_SetDriver


[APIfunction]

FSOUND_GetNumHWChannels

Returnsthenumberofavailablehardwaremixed2dand3dchannels.

signedcharF_APIFSOUND_GetNumHWChannels(int*num2d,int*num3d,int*total);

Parameters

num2d Pointertointegertostorethenumberofavailablehardwaremixed2dchannels.

num3d Pointertointegertostorethenumberofavailablehardwaremixed3dchannels.

totalUsuallynum2d+num3d,butonsomeplatformslikePS2andGameCube,thiswillbethesameasnum2dandnum3d(andnotthesum)because2dand3dvoicessharethesamepool.

ReturnValue


Remarks



[APIfunction]

FSOUND_GetOutput

Returnsthecurrentidtotheoutputtype.SeeFSOUND_OUTPUTTYPESforvalidparametersanddescriptions.

intF_APIFSOUND_GetOutput();

ReturnValue

idtooutputtype

Remarks


SeeAlso

FSOUND_GetOutputHandle,FSOUND_OUTPUTTYPES,FSOUND_SetFrequency,FSOUND_SetOutput


[APIfunction]

FSOUND_GetOutputHandle

Returnsapointertothesystemleveloutputdevicemodule.ThismeansapointertoaDIRECTSOUND,WINMMhandle,orwithNOSOUNDoutput,NULL

void*F_APIFSOUND_GetOutputHandle();

ReturnValue

Pointertooutputhandlespecifictothedevice.

Remarks

MustbecalledafterFSOUND_Initorelseitwillfail,Casttheresultingpointerdependingonwhatoutputsystempointeryouareafter.FSOUND_OUTPUT_NOSOUND,NULLisreturned.FSOUND_OUTPUT_WINMM,HWAVEOUTisreturned.FSOUND_OUTPUT_DSOUND,LPDIRECTSOUNDisreturned.FSOUND_OUTPUT_OSS,Filehandleisreturned,(casttoint)FSOUND_OUTPUT_ESD,Handlereturnedbyso_esd_open_sound(casttoint).FSOUND_OUTPUT_ALSAsnd_pcm_t*isreturned.FSOUND_OUTPUT_ASIOAsioDriverListpointerisreturned.FSOUND_OUTPUT_XBOXLPDIRECTSOUNDisreturned.FSOUND_OUTPUT_PS2NULLisreturned.FSOUND_OUTPUT_MACSndChannelPtrisreturned.FSOUND_OUTPUT_GCNULLisreturned.FSOUND_OUTPUT_PSPNULLisreturned.FSOUND_OUTPUT_NOSOUND_NONREALTIMENULLisreturned.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox

SeeAlso

FSOUND_GetOutput,FSOUND_Init,FSOUND_OUTPUTTYPES,FSOUND_SetFrequency,FSOUND_SetOutput


[APIfunction]

FSOUND_GetOutputRate

Returnsthecurrentmixingrate

intF_APIFSOUND_GetOutputRate();

ReturnValue

CurrentlysetoutputrateinHZ.

Remarks


SeeAlso

FSOUND_Init


[APIfunction]

FSOUND_GetSFXMasterVolume

Returnsthemastervolumeforanysoundeffectsplayed.ItspecificallyhasSFXinthefunctionname,asitdoesnotaffectmusicorCDvolume.ThismustalsobealteredwithFMUSIC_SetMasterVolume.

DLL_APIintF_APIFSOUND_GetSFXMasterVolume();

ReturnValue

Onsuccess,theSFXmastervolumeisreturned.Validrangesarefrom0(silent)to255(fullvolume)

Remarks


SeeAlso

FMUSIC_SetMasterVolume


[APIfunction]

FSOUND_GetVersion

ReturnstheFMODversionnumber.

floatF_APIFSOUND_GetVersion();

ReturnValue

FMODversionnumber.

Remarks

UsethistocomparetheheaderyouareusingagainstthecompiledDLLversiontomakesureyourDLLisuptodate.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube


[APIfunction]

FSOUND_Sample_Alloc

Allocatesanewemptysample.Usedifyouwanttocreateasamplefromscratchandfillthedatabufferwithyourowndata(usingFSOUND_Sample_LockorFSOUND_Sample_Upload),insteadofjustloadingafilewithFSOUND_Sample_Load.

FSOUND_SAMPLE*F_APIFSOUND_Sample_Alloc(intindex,intlength,unsignedintmode,intdeffreq,intdefvol,intdefpan,intdefpri);

Parameters

index

Samplepoolindex.Seeremarksformoreonthesamplepool.0orabove-Theabsoluteindexintofsoundssamplepool.Thepoolwillgrowastheindexgetslarger.Ifaslotisalreadyuseditwillbereplaced.FSOUND_FREE-LetFSOUNDselectanarbitrarysampleslot.FSOUND_UNMANAGED-DonthavefsoundfreethissampleuponFSOUND_Close

length ThelengthinofthesamplebufferinSAMPLES.

modeBitfielddescribingvariouscharacteristicsofthesample.ValidparametersaredescribedinFSOUND_MODES.

deffreqDefaultfrequencyforthissample.defvol Defaultvolumeforthissample.defpan Defaultpanforthissample.defpri Defaultpriorityforthissample.

ReturnValue

Onsuccess,apointertoanallocatedsampleisreturned.Onfailure,NULLisreturned.

Remarks

FMODhasasamplemanagementsystemthatholdsontoanysamplesloadedorallocated,andfreesthemallwhenyoucallFSOUND_Close.Ittakesthehassleoutofhavingtokeepholdofalotofsamplehandlesandremembertofreethemallattheendofyourapplication.ItisbasicallyanexpandlearrayofhandlesthatholdseachsampleuntilFMODclosesdownwhereitdoesacleanup.FSOUND_UNMANAGEDcanbeusedNOTtousethesamplemanagementsystem.------------FSOUND_Sample_Allocisonlynescessaryforlowerleveloperationswithsampledata.UsuallyFSOUND_Loaddoestheworkforyou.lowerleveloperationsmeansuchthingsasuploadingdatafrommemoryoryourowncompresseddataforexample.Youcancreateanewsamplefromscratchbydoingthefollowingoperations1.AllocateanewsamplewithFSOUND_Sample_Alloc2.WritedatatothesamplebufferwithFSOUND_Sample_LockandFSOUND_Sample_Unlock,orFSOUND_Sample_Upload.NoteFSOUND_Sample_Lockonlyreturnsapointertothesampledata,whereasFSOUND_Sample_Uploaddoesacopyfromdatayougiveit,withformatconversiontothecorrectformat.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Close,FSOUND_MODES,FSOUND_Sample_Alloc,FSOUND_Sample_Free,FSOUND_Sample_Load,FSOUND_Sample_Lock,

FSOUND_Sample_SetDefaults,FSOUND_Sample_SetLoopPoints,FSOUND_Sample_Unlock,FSOUND_Sample_Upload


[APIfunction]

FSOUND_Sample_Free

Removesasamplefrommemoryandmakesitsslotavailableagain.

voidF_APIFSOUND_Sample_Free(FSOUND_SAMPLE*sptr);

Parameters

sptr Pointertothesampledefinitiontobefreed.

ReturnValue

void

Remarks


SeeAlso

FSOUND_Sample_Alloc,FSOUND_Sample_Load


[APIfunction]

FSOUND_Sample_Get

Returnsapointertoamanagedsamplebasedontheindexpassed.

FSOUND_SAMPLE*F_APIFSOUND_Sample_Get(intsampno);

Parameters

sampno Theindexinthesamplemanagementpooloftherequestedsample.

ReturnValue

Pointertoasample.

Remarks

SamplesthatarenotcreatedwithFSOUND_UNMANAGEDarestoredinatableinsideFMOD.ThiswaywhenFMODcanfreeallsampleswhenFSOUND_Closeiscalledandtheuserdoesnthavetoworryaboutcleaningupmemory.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Close


[APIfunction]

FSOUND_Sample_GetDefaults

Returnsthedefaultvolume,frequency,panandpriorityvaluesforthespecifiedsample.

signedcharF_APIFSOUND_Sample_GetDefaults(FSOUND_SAMPLE*sptr,int*deffreq,int*defvol,int*defpan,int*defpri);

Parameters

sptr Pointertothesampletogetthedefaultinformationfrom.

deffreq Pointertovaluetobefilledwiththesampledefaultfrequency.CanbeNULL.

defvol Pointertovaluetobefilledwiththesampledefaultvolume.CanbeNULL.defpan Pointertovaluetobefilledwiththesampledefaultpan.CanbeNULL.

defpri Pointertovaluetobefilledwiththesampledefaultpriority.CanbeNULL.

ReturnValue


Remarks

PassingNULLinanyoftheseparameterswillresultinthevaluebeingignored.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Sample_GetDefaultsEx,FSOUND_Sample_SetDefaults,FSOUND_Sample_SetDefaultsEx


[APIfunction]

FSOUND_Sample_GetDefaultsEx

Returnsthedefaultvolume,frequency,pan,priorityandrandomplaybackvariationsforthespecifiedsample.

signedcharF_APIFSOUND_Sample_GetDefaultsEx(FSOUND_SAMPLE*sptr,int*deffreq,int*defvol,int*defpan,int*defpri,int*varfreq,int*varvol,int*varpan);

Parameters

sptr Pointertothesampletogetthedefaultinformationfrom.

deffreq Pointertovaluetobefilledwiththesampledefaultfrequency.CanbeNULL.

defvol Pointertovaluetobefilledwiththesampledefaultvolume.CanbeNULL.

defpan Pointertovaluetobefilledwiththesampledefaultpan.CanbeNULL.

defpri Pointertovaluetobefilledwiththesampledefaultpriority.CanbeNULL.

varfreq Pointertovaluetobefilledwiththesamplerandomfrequencyvariance.CanbeNULL.

varvol Pointertovaluetobefilledwiththesamplerandomvolumevariance.CanbeNULL.

varpan Pointertovaluetobefilledwiththesamplerandompanvariance.CanbeNULL.

ReturnValue

Onsuccess,TRUEisreturned.

Onfailure,FALSEisreturned.

Remarks


SeeAlso

FSOUND_Sample_GetDefaults,FSOUND_Sample_SetDefaults,FSOUND_Sample_SetDefaultsEx


[APIfunction]

FSOUND_Sample_GetLength

ReturnsthelengthofthesampleinSAMPLES

unsignedintF_APIFSOUND_Sample_GetLength(FSOUND_SAMPLE*sptr);

Parameters

sptr Pointertothesampletogetthelengthfrom.

ReturnValue

Onsuccess,thelengthofsampleinSAMPLESisreturned.Onfailure,0isreturned.

Remarks



[APIfunction]

FSOUND_Sample_GetLoopPoints

ReturnsthestartandendpositionsofthespecifiedsampleloopinSAMPLES(notbytes)

DLL_APIsignedcharF_APIFSOUND_Sample_GetLoopPoints(FSOUND_SAMPLE*sptr,int*loopstart,int*loopend);

Parameters

sptr Pointertothesampletogetthelooppointinformationfrom.

loopstart Pointertovaluetobefilledwiththesampleloopstartpoint.CanbeNULL.

loopend Pointertovaluetobefilledwiththesampleloopendpoint.CanbeNULL.

ReturnValue


Remarks


SeeAlso

FSOUND_Sample_SetDefaults,FSOUND_Sample_SetDefaultsEx,FSOUND_Sample_SetLoopPoints,FSOUND_Sample_SetMode


[APIfunction]

FSOUND_Sample_GetMinMaxDistance

Gettheminimumandmaximumaudibledistanceforasample.

signedcharF_APIFSOUND_Sample_GetMinMaxDistance(FSOUND_SAMPLE*sptr,F_FLOAT_API*min,F_FLOAT_API*max);

Parameters

sptr Thesampletogetminimumandmaximumaudibledistanceinformationfrom.

min Pointertovaluetobefilledwiththeminimumvolumedistanceforthesample.Seeremarksformoreonunits.

max Pointertovaluetobefilledwiththemaximumvolumedistanceforthesample.Seeremarksformoreonunits.

ReturnValue


Remarks

A'distanceunit'isspecifiedbyFSOUND_3D_SetDistanceFactor.Bydefaultthisissettometerswhichisadistancescaleof1.0.SeeFSOUND_3D_SetDistanceFactorformoreonthis.Thedefaultunitsforminimumandmaximumdistancesare1.0and1000000000.0f.Volumedropsoffatmindistance/distance.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_SetDistanceFactor,FSOUND_Sample_SetMinMaxDistance


[APIfunction]

FSOUND_Sample_GetMode

Returnsabitfieldcontaininginformationaboutthespecifiedsample.ThevaluescanbebitwiseAND'edwiththevaluescontainedinFSOUND_MODEStoseeifcertaincriteriaaretrueornot.Informationthatcanberetrievedfromthesameinthisfieldarelooptype,bitdepthandstereo/mono.

unsignedintF_APIFSOUND_Sample_GetMode(FSOUND_SAMPLE*sptr);

Parameters

sptr Pointertothesampletogetthemodeinformationon

ReturnValue

Onsuccess,thesamplemodeisreturned.Onfailure,0isreturned.

Remarks


SeeAlso

FSOUND_MODES,FSOUND_Sample_SetDefaults,FSOUND_Sample_SetDefaultsEx,FSOUND_Sample_SetMode,FSOUND_SetLoopMode


[APIfunction]

FSOUND_Sample_GetName

ReturnsapointertoaNULLterminatedstringcontainingthesample'sname.

constchar*F_APIFSOUND_Sample_GetName(FSOUND_SAMPLE*sptr);

Parameters

sptr Pointertothesampletogetthenamefrom.

ReturnValue

Onsuccess,thenameofthesampleisreturned.Onfailure,NULLisreturned.

Remarks

Thenamemaynotalwaysmakesense.FromaMODfileitcontainsthesampletextenteredbythemusician.Fornondescriptivefileformatsitjustcontainsthefilename.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube


[APIfunction]

FSOUND_Sample_Load

Loadsanddecodesastaticsoundfileintomemory.Thisincludessuchfilesas.WAV,.MP2,.MP3,.OGG,.RAWandothers.

FSOUND_SAMPLE*F_APIFSOUND_Sample_Load(intindex,constchar*name_or_data,unsignedintinputmode,intoffset,intlength);

Parameters

index

Samplepoolindex.Seeremarksformoreonthesamplepool.0orabove-Theabsoluteindexintothesamplepool.Thepoolwillgrowastheindexgetslarger.Ifaslotisalreadyuseditwillbereplaced.FSOUND_FREE-LetFSOUNDselectanarbitrarysampleslot.FSOUND_UNMANAGED-Donthavethissamplemanagedwithinfsoundssamplemanagementsystem

name_or_data Nameofsoundfileorpointertomemoryimagetoload.

mode Descriptionofthedataformat,ORinthebitsdefinedinFSOUND_MODEStodescribethedatabeingloaded.

offsetOptional.0bydefault.If>0,thisvalueisusedtospecifyanoffsetinafile,sofmodwillseekbeforeopening.lengthmustalsobespecifiedifthisvalueisused.

length

Optional.0bydefault.If>0,thisvalueisusedtospecifythelengthofamemoryblockwhenusingFSOUND_LOADMEMORY,oritisthelengthofafileorfilesegmentiftheoffsetparameterisused.OnPlayStation2thismustbe16bytealignedformemoryloading.

ReturnValue

Onsuccess,asamplepointerisreturned.Onfailure,NULLisreturned.

Remarks

FMODhasasamplemanagementsystemthatholdsontoanysamplesloadedorallocated,andfreesthemallwhenyoucallFSOUND_Close.Ittakesthehassleoutofhavingtokeepholdofalotofsamplehandlesandremembertofreethemallattheendofyourapplication.ItisbasicallyanexpandlearrayofhandlesthatholdseachsampleuntilFMODclosesdownwhereitdoesacleanup.FSOUND_UNMANAGEDcanbeusedsoFMODdoesNOTusethesamplemanagementsystem.Youhavetomakesuretheyarefreedyourself.--------SpecifyFSOUND_LOADMEMORYtoloadafilefromamemoryimage.Thepointeryoupasstonamemustbetheactualimageofthedatayouwanttoload.ThelengthparameteristobefilledoutifFSOUND_LOADMEMORYisspecified,otherwiseifyoudonotspecifymemoryloading,canbesafelyignoredandshouldbesetto0.--------Compressedformatsareexpandedintomemory.Ifthefileisquitelarge,itcouldtakeawhiletoload.--------IfFSOUND_8BITSisspecifiedandthefiledecodesto16bitnormally,FMODwilldowngradethesampleto8bit.--------OnPlayStation2,thename_or_datapointerandlengthvariablesmustbe16bytealigned,forDMAreasons.--------NotethatFSOUND_NONBLOCKINGisNOTsupportedwiththisfunction.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Close,FSOUND_MODES,FSOUND_Sample_Alloc,

FSOUND_Sample_Free


[APIfunction]

FSOUND_Sample_Lock

Returnsapointertothebeginningofthesampledataforasample.Datawrittentothesepointersmustbesigned.

signedcharF_APIFSOUND_Sample_Lock(FSOUND_SAMPLE*sptr,intoffset,intlength,void**ptr1,void**ptr2,unsignedint*len1,unsignedint*len2);

Parameters

sptr Pointertothesampledefinition.offset OffsetinBYTEStothepositionyouwanttolockinthesamplebuffer.lengthNumberofBYTESyouwanttolockinthesamplebuffer.ptr1 Addressofapointerthatwillpointtothefirstpartofthelockeddata.

ptr2Addressofapointerthatwillpointtothesecondpartofthelockeddata.ThiswillbeNULLifthedatalockedhasntwrappedattheendofthebuffer.

len1 LengthofdatainBYTESthatwaslockedforptr1

len2 LengthofdatainBYTESthatwaslockedforptr2.Thiswillbe0ifthedatalockedhasntwrappedattheendofthebuffer.

ReturnValue


Remarks

Youmustalwaysunlockthedataagainafteryouhavefinishedwithit,using

FSOUND_Sample_Unlock.ForPCMbasedsamples,datamustbesigned8or16bit.ForcompressedsamplessuchasthosecreatedwithFSOUND_IMAADPCM,FSOUND_VAG,FSOUND_GCADPCM,thedatamustbeinitsoriginalcompressedformat.OnPlayStation2,withFSOUND_HW2DorFSOUND_HW3Dbasedsamples,thisfunctiondoesnotreturnareadableorwritablebuffer,itreturnstheSPU2addressofthesample.TosenddatatoityoumustcallFSOUND_SendData.OnGameCube,withFSOUND_HW2DorFSOUND_HW3Dbasedsamples,thisfunctionwillnotreturnthedatacontainedwithinthesample.Itisforuploadpurposesonly.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Sample_Alloc,FSOUND_Sample_Unlock,FSOUND_Sample_Upload,FSOUND_SendData


[APIfunction]

FSOUND_Sample_SetDefaults

Setsasample'sdefaultattributes,sowhenitisplayeditusesthesevalueswithouthavingtospecifythemlater.

signedcharF_APIFSOUND_Sample_SetDefaults(FSOUND_SAMPLE*sptr,intdeffreq,intdefvol,intdefpan,intdefpri);

Parameters

sptr Pointertothesampletohaveitsattributesset.deffreqDefaultsamplefrequency.Thevaluehereisspecifiedinhz.-1toignore.defvol Defaultsamplevolume.Thisisavaluefrom0to255.-1toignore.

defpan Defaultsamplepanposition.Thisisavaluefrom0to255orFSOUND_STEREOPAN.defpri Defaultsamplepriority.Thisisavaluefrom0to255.-1toignore.

ReturnValue


Remarks


SeeAlso

FSOUND_Sample_Alloc,FSOUND_Sample_GetDefaults,

FSOUND_Sample_GetDefaultsEx,FSOUND_Sample_GetLoopPoints,FSOUND_Sample_GetMode,FSOUND_Sample_SetDefaultsEx,FSOUND_Sample_SetMode,FSOUND_SetFrequency,FSOUND_SetPan,FSOUND_SetPriority,FSOUND_SetVolume


[APIfunction]

FSOUND_Sample_SetDefaultsEx

Setsasample'sdefaultattributes,sowhenitisplayeditusesthesevalueswithouthavingtospecifythemlater.

signedcharF_APIFSOUND_Sample_SetDefaultsEx(FSOUND_SAMPLE*sptr,intdeffreq,intdefvol,intdefpan,intdefpri,intvarfreq,intvarvol,intvarpan);

Parameters

sptr Pointertothesampletohaveitsattributesset.

deffreq Defaultsamplefrequency.Thevaluehereisspecifiedinhz.-1toignore.defvol Defaultsamplevolume.Thisisavaluefrom0to255.-1toignore.

defpan Defaultsamplepanposition.Thisisavaluefrom0to255orFSOUND_STEREOPAN.

defpri Defaultsamplepriority.Thisisavaluefrom0to255.-1toignore.

varfreq Frequencyvariationinhztoapplytodeffreqeachtimethissampleisplayed.-1toignore.

varvol Volumevariationtoapplytodefvoleachtimethissampleisplayed.-1toignore.

varpan Panvariationtoapplytodefpaneachtimethissampleisplayed.-1toignore.

ReturnValue


Remarks

Frequency,volumeandpanvariationvaluesspecifya+/-variationtothespecifieddefaultfrequency,volumeandpanvaluesi.e.withdeffreq=44100,varfreq=2000theactualfrequencyvalueusedwillbeintherange42100->46100.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Sample_GetDefaults,FSOUND_Sample_GetDefaultsEx,FSOUND_Sample_GetLoopPoints,FSOUND_Sample_GetMode,FSOUND_Sample_SetDefaults,FSOUND_SetFrequency,FSOUND_SetPan,FSOUND_SetPriority,FSOUND_SetVolume


[APIfunction]

FSOUND_Sample_SetMaxPlaybacks

Setsthemaximumnumberoftimesasamplecanplaybackatonce.

signedcharF_APIFSOUND_Sample_SetMaxPlaybacks(FSOUND_SAMPLE*sptr,intmax);

Parameters

sptr Pointertothesampletohaveitsplaybackbehaviourchanged.

ReturnValue


Remarks


SeeAlso

FSOUND_PlaySound


[APIfunction]

FSOUND_Sample_SetMinMaxDistance

Setstheminimumandmaximumaudibledistanceforasample.MinDistanceistheminimumdistancethatthesoundemitterwillceasetocontinuegrowinglouderat(asitapproachesthelistener).Withinthemindistanceitstaysattheconstantloudestvolumepossible.Outsideofthismindistanceitbeginstoattenuate.MaxDistanceisthedistanceasoundstopsattenuatingat.Beyondthispointitwillstayatthevolumeitwouldbeatmaxdistanceunitsfromthelistenerandwillnotattenuateanymore.MinDistanceisusefultogivetheimpressionthatthesoundisloudorsoftin3dspace.Anexampleofthisisasmallquietobject,suchasabumblebee,whichyoucouldsetamindistanceofto0.1forexample,whichwouldcauseittoattenuatequicklyanddissapearwhenonlyafewmetersawayfromthelistener.Anotherexampleisajumbojet,whichyoucouldsettoamindistanceof100.0,whichwouldkeepthesoundvolumeatmaxuntilthelistenerwas100metersaway,thenitwouldbehundredsofmetersmorebeforeitwouldfadeout.-------Insummary,increasethemindistanceofasoundtomakeit'louder'ina3dworld,anddecreaseittomakeit'quieter'ina3dworld.maxdistanceiseffectivelyobsoleteunlessyouneedthesoundtostopfadingoutatacertainpoint.Donotadjustthisfromthedefaultifyoudontneedto.Somepeoplehavetheconfusionthatmaxdistanceisthepointthesoundwillfadeoutto,thisisnotthecase.

signedcharF_APIFSOUND_Sample_SetMinMaxDistance(FSOUND_SAMPLE*sptr,F_FLOAT_APImin,F_FLOAT_APImax);

Parameters

sptr Thesampletohaveitsminimumandmaximumdistanceset.min Thesamplesminimumvolumedistancein"units".Seeremarksformore

onunits.

max Thesamplesmaximumvolumedistancein"units".Seeremarksformoreonunits.

ReturnValue


Remarks

A'distanceunit'isspecifiedbyFSOUND_3D_SetDistanceFactor.Bydefaultthisissettometerswhichisadistancescaleof1.0.SeeFSOUND_3D_SetDistanceFactorformoreonthis.Thedefaultunitsforminimumandmaximumdistancesare1.0and1000000000.0f.Volumedropsoffatmindistance/distance.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_GetAttributes,FSOUND_3D_GetMinMaxDistance,FSOUND_3D_SetAttributes,FSOUND_3D_SetDistanceFactor,FSOUND_3D_SetMinMaxDistance,FSOUND_Sample_GetMinMaxDistance


[APIfunction]

FSOUND_Sample_SetMode

Setsasample'smode.ThiscanonlybeFSOUND_LOOP_OFF,FSOUND_LOOP_NORMAL,FSOUND_LOOP_BIDIorFSOUND_2D.Youcannotchangethedescriptionofthecontentsofasampleoritslocation.FSOUND_2DwillbeignoredontheWin32platformifFSOUND_HW3Dwasusedtocreatethesample.

signedcharF_APIFSOUND_Sample_SetMode(FSOUND_SAMPLE*sptr,unsignedintmode);

Parameters

sptr Pointertothesampletohavethemodeset.mode ThemodebitstosetfromFSOUND_MODES.

ReturnValue


Remarks

Onlythefollowingmodesareaccepted,otherswillbefilteredout.FSOUND_LOOP_BIDI,FSOUND_LOOP_NORMAL,FSOUND_LOOP_OFF,FSOUND_2D.NormallyFSOUND_2Disacceptedonlyifthesoundissoftwaremixed.Ifthisisnotset,themodeissetforthesampletobe3Dprocessed.-------------------OnPlaystation2,XBoxandGameCube,FSOUND_HW2DandFSOUND_HW3Daresupported,soyoucanchangebetweenthematruntime.-------------------OnWindows,samplescreatedwithFSOUND_HW3DorFSOUND_HW2Ddo

notsupportFSOUND_LOOP_BIDI.ThisisalimitationofDirectX.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetLoopMode,FSOUND_MODES,FSOUND_Sample_GetLoopPoints,FSOUND_Sample_GetMode,FSOUND_Sample_SetDefaults,FSOUND_Sample_SetLoopPoints


[APIfunction]

FSOUND_Sample_SetLoopPoints

Setsasample'slooppoints,specifiedinSAMPLES,notbytes.

signedcharF_APIFSOUND_Sample_SetLoopPoints(FSOUND_SAMPLE*sptr,intloopstart,intloopend);

Parameters

sptr Pointertothesampletohaveitslooppointsset.loopstart Thestartingpositionofthesamplelooploopend Theendpositionofthesampleloop

ReturnValue


Remarks

SamplescreatedwithFSOUND_HW3DandFSOUND_HW2DundertheFSOUND_OUTPUT_DSOUNDoutputmodedonotsupportthisfunction.Looppointssetonsuchasamplewithbeignored,andthesamplewillloopinitsentirety.ThisisalimitationofDirectSound.OnXBOX,GameCubeandPlaystation2hardwarevoicesusingcompresseddata(ieXADPCM,VAGorGCADPCM),thesevalueswillnotbesampleaccurate,butwillberoundedtothenearestcompressionblocksize.OnPlayStation2,theloopendisignored.Thehardwarecannotchangetheendaddress,sotheloopendisalwaysequivalenttolength-1nomatterwhatyouset.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Sample_Alloc,FSOUND_Sample_GetLoopPoints,FSOUND_Sample_SetMode


[APIfunction]

FSOUND_Sample_Unlock

ReleasesprevioussampledatalockfromFSOUND_Sample_Lock

signedcharF_APIFSOUND_Sample_Unlock(FSOUND_SAMPLE*sptr,void*ptr1,void*ptr2,unsignedintlen1,unsignedintlen2);

Parameters

sptr Pointertothesampledefinition.

ptr1 Pointertothe1stlockedportionofsampledata,fromFSOUND_Sample_Lock.

ptr2 Pointertothe2ndlockedportionofsampledata,fromFSOUND_Sample_Lock.len1 LengthofdatainBYTESthatwaslockedforptr1

len2 LengthofdatainBYTESthatwaslockedforptr2.Thiswillbe0ifthedatalockedhasntwrappedattheendofthebuffer.

ReturnValue


Remarks


SeeAlso

FSOUND_Sample_Alloc,FSOUND_Sample_Lock,FSOUND_Sample_Upload


[APIfunction]

FSOUND_Sample_Upload

Thisfunctionuploadsnewsounddatafrommemorytoapreallocated/existingsampleanddoesconversionbasedonthespecifiedsourcemode.Ifsampledataalreadyexistsatthishandlethenitisreplacedwiththenewdatabeinguploaded.

signedcharF_APIFSOUND_Sample_Upload(FSOUND_SAMPLE*sptr,void*srcdata,unsignedintmode_in);

Parameters

sptr Pointertothedestinationsample

srcdata Pointertothesourcedatatobeuploaded.OnPlayStation2thisisanIOPaddressnotanEEaddress.

mode

Descriptionofthesourcedataformat.BitwiseORinthesebitstodescribethedatabeingpassedin.SeeFSOUND_MODESforvalidparametersanddescriptions.FSOUND_HW3D,FSOUND_HW2DandFSOUND_LOOPmodesareignored,themodedescribesthesourceformat,notthedestinationformat.

ReturnValue


Remarks

NotethatonPlayStation2thesourcedataaddressisanIOPaddressnotanEEaddress.TogetdatafromEERAMtothesampleyoumustallocatesomeIOPmemory,dmaittoIOPmemorythencallupload.Therearehelperfunctionsinfmodps2.h

toachievethis.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_MODES,FSOUND_Sample_Alloc,FSOUND_Sample_Lock,FSOUND_Sample_Unlock


[APIfunction]

FSOUND_PlaySound

Playsasampleinaspecifiedchannel,usingthesample'sdefaultfrequency,volumeandpansettings.

intF_APIFSOUND_PlaySound(intchannel,FSOUND_SAMPLE*sptr);

Parameters

channel

0+Theabsolutechannelnumberinthechannelpool.Remembersoftwarechannelscomefirst,followedbyhardwarechannels.Youcannotplayasoftwaresampleonahardwarechannelandviceversa.FSOUND_FREEChoosesafreechanneltoplayin.IfallchannelsareusedthenitselectsachannelwithasampleplayingthathasanEQUALorLOWERprioritythanthesampletobeplayed.FSOUND_ALLPassingthiswillcauseALLchannelstoplay.(notethiswillmakethingsVERYnoisy!)IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.

sptr Pointertothesampletobeplayed.

ReturnValue

Onsuccess,thechannelhandlethatwasselectedisreturned.Onfailure,-1isreturned.

Remarks

IfyouplayaFSOUND_HW3Ddeclaredsamplewiththisfunction,thenthepositionandvelocityaresettothoseofthelistener.Otherattributessuchasvolume,frequencyandpanaretakenfromthesample'sdefaultvolume,frequency,panetc.----------Thechannelhandle:Thereturnvalueisreferencecounted.Thisstopstheuserfromupdatingastolenchannel.Basicallyitmeanstheonlysoundyoucanchangetheattributes(ievolume/pan/frequency/3dposition)foraretheoneyouspecificallycalledplaysoundfor.Ifanothersoundstealsthatchannel,andyoukeeptryingtochangeitsattributes(ievolume/pan/frequency/3dposition),itwilldonothing.Thisisgreatifyouhavesoundsbeingupdatedfromtasksandyoujustforgetaboutit.Youcankeepupdatingthesoundattributesandifanothertaskstealsthatchannel,youroriginaltaskwontchangetheattributesofthenewsound!!!Thelower12bitscontainthechannelnumber.(yesthismeansa4096channellimitforFMOD:)Theupper19bitscontainthereferencecount.Thetop1bitisthesignbit.ieSRRRRRRRRRRRRRRRRRRRCCCCCCCCCCCC----------RememberifnotusingFSOUND_FREE,thenthechannelpoolissplitupintosoftwareandhardwarechannels.SoftwarechannelsoccupythefirstnindiciesspecifiedbythevaluepassedintoFSOUND_Init.Hardwarechannelsoccupythenextnindiciesafterthis,andcanbeavariableamount,dependingonthehardware.UseFSOUND_GetNumHardwareChannelstoqueryhowmanychannelsareavailableinhardware.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_FX_Enable,FSOUND_GetNumHardwareChannels,FSOUND_GetNumSubChannels,FSOUND_GetSubChannel,FSOUND_Init,FSOUND_PlaySoundEx,FSOUND_Sample_SetMaxPlaybacks,FSOUND_StopSound


[APIfunction]

FSOUND_PlaySoundEx

ExtendedfeaturedversionofFSOUND_PlaySound.Newfunctionalityincludestheabilitytostartthesoundpaused.Thisallowsattributesofachanneltobesetfreelybeforethesoundactuallystartsplaying,untilFSOUND_SetPaused(FALSE)isused.AlsoaddedistheabilitytoassociatethechanneltoaspecifiedDSPunit.Thisallowstheuserto'group'channelsintoseperateDSPunits,whichallowseffectstobeinsertedbetweenthese'groups',andallowvariousthingslikehavingonegroupaffectedbyreverb(wetmix)andanothergroupofchannelsunaffected(dry).ThisisusefultoseperatethingslikemusicfrombeingaffectedbyDSPeffects,whileothersoundeffectsare.

intF_APIFSOUND_PlaySoundEx(intchannel,FSOUND_SAMPLE*sptr,FSOUND_DSPUNIT*dspunit,signedcharstartpaused);

Parameters

channel

0+Theabsolutechannelnumberinthechannelpool.Remembersoftwarechannelscomefirst,followedbyhardwarechannels.Youcannotplayasoftwaresampleonahardwarechannelandviceversa.FSOUND_FREEChoosesafreechanneltoplayin.IfallchannelsareusedthenitselectsachannelwithasampleplayingthathasanEQUALorLOWERprioritythanthesampletobeplayed.FSOUND_ALLPlaysthesoundonallchannels.

sptr Pointertothesampletobeplayed.

dspunitOptional.NULLbydefault.Pointertoadspunittoattachthechanneltoforchannelgrouping.OnlyattachasoundtoausercreatedDSPunit,andnotasystemDSPunit.

paused Startthesoundpausedornot.Pausingthesoundallowsattributestobesetbeforethesoundstarts.

ReturnValue

Onsuccess,thechannelhandlethatwasselectedisreturned.Onfailure,-1isreturned.

Remarks

FSOUND_ALLissupported.PassingthiswillcauseALLchannelstoplay.(notethiscouldmakethingsVERYnoisy!)IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.----------Thechannelhandle:Thereturnvalueisreferencecounted.Thisstopstheuserfromupdatingastolenchannel.Thismeanstheonlysoundyoucanchangetheattributes(ievolume/pan/frequency/3dposition)foraretheoneyouspecificallycalledplaysoundfor.Ifanothersoundstealsthatchannel,andyoukeeptryingtochangeitsattributes(ievolume/pan/frequency/3dposition),itwilldonothing.Thisisgreatifyouhavesoundsbeingupdatedfromtasksandyoujustforgetaboutit.Youcankeepupdatingthesoundattributesandifanothertaskstealsthatchannel,youroriginaltaskwontchangetheattributesofthenewsound!!!Thelower12bitscontainthechannelnumber.(yesthismeansa4096channellimitforFMOD:)Theupper19bitscontainthereferencecount.Thetop1bitisthesignbit.ieSRRRRRRRRRRRRRRRRRRRCCCCCCCCCCCC----------

RememberifnotusingFSOUND_FREE,thenthechannelpoolissplitupintosoftwareandhardwarechannels.SoftwarechannelsoccupythefirstnindiciesspecifiedbythevaluepassedintoFSOUND_Init.Hardwarechannelsoccupythenextnindiciesafterthis,andcanbeavariableamount,dependingonthehardware.UseFSOUND_GetNumHardwareChannelstoqueryhowmanychannelsareavailableinhardware.----------IfyouattachasoundtoaDSPunit(forgroupingpurposes),thecallbackfortheDSPunitwillbeoverwrittenwithfmod'sinternalmixercallback,sothecallbacktheusersuppliedisrenderedobsoleteandisnotcalled.Also,donotattachsoundstosystemDSPunits,theassignmentwillbeignoredifyoudo.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_Create,FSOUND_FX_Enable,FSOUND_GetNumSubChannels,FSOUND_GetSubChannel,FSOUND_Init,FSOUND_PlaySound,FSOUND_SetPaused,FSOUND_StopSound


[APIfunction]

FSOUND_StopSound

Stopsaspecifiedsoundchannelfromplaying,andfreesitupforre-use.

signedcharF_APIFSOUND_StopSound(intchannel);

Parameters

channel Thechannelnumber/handletostop.FSOUND_ALLcanalsobeused(seeremarks)

ReturnValue


Remarks

FSOUND_ALLissupported.PassingthiswillcauseALLchannelstostop.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_PlaySound,FSOUND_PlaySoundEx


[APIfunction]

FSOUND_SetFrequency

Setsachannelsfrequencyorplaybackrate,inHZ.

signedcharF_APIFSOUND_SetFrequency(intchannel,intfreq);

Parameters

channel Thechannelnumber/handletochangethefrequencyfor.FSOUND_ALLcanalsobeused(seeremarks).

freq Thefrequencytoset.Validrangesarefrom100to705600,and-100to-705600.

ReturnValue


Remarks

FSOUND_ALLissupportedhere.PassingthiswillsetALLchannelstospecifiedfrequency.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.Negativefrequenciesmakethesoundplaybackwards,soFSOUND_SetCurrentPositionwouldbeneededtosetthesoundtotherightposition.---------NOTE:FSOUND_HW3DlimitationsinDirectSound.Everyhardwaredevicehasaminimumandmaximumfrequency.YoucandeterminethesebylookingattheDirectSoundcapsandviewingthemembersdwMaxSecondarySampleRateanddwMaxSecondarySampleRate.FMODclampsfrequenciestothesevalueswhenplayingbackonhardware,soif

youaresettingthefrequencyoutsideofthisrange,thefrequencywillstayateitherdwMinSecondarySampleRateordwMaxSecondarySampleRate.Tofindoutthesetwovaluesinfmod(maybewhethertodecidetodropbacktosoftwaremixingornot),youcanusethefollowingcode.---------include<dsound.h>intminhwfreq,maxhwfreq;if(FSOUND_GetNumHardwareChannels()&&FSOUND_GetOutput()==FSOUND_OUTPUT_DSOUND){HRESULThr;DSCAPSdscaps;memset(&dscaps;,0,sizeof(DSCAPS));dscaps.dwSize=sizeof(DSCAPS);hr=IDirectSound_GetCaps((LPDIRECTSOUND)FSOUND_GetOutputHandle(),&dscaps;);minhwfreq=dscaps.dwMinSecondarySampleRate;maxhwfreq=dscaps.dwMaxSecondarySampleRate;}___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_MixBuffers,FSOUND_GetFrequency,FSOUND_GetOutput,FSOUND_GetOutputHandle,FSOUND_Sample_SetDefaults,FSOUND_Sample_SetDefaultsEx,FSOUND_SetCurrentPosition


[APIfunction]

FSOUND_SetLevels

XBoxOnly-Forsurroundsoundsystems,thisfunctionallowseachsurroundspeakerleveltobesetindividuallyforthischannel.

signedcharF_APIFSOUND_SetLevels(intchannel,intfrontleft,intcenter,intfrontright,intbackleft,intbackright,intlfe);

Parameters

channelThechannelnumber/handletochangetheoutputlevelsfor.FSOUND_ALLandFSOUND_SYSTEMCHANNELcanalsobeused(seeremarks)

frontleft Valuefrom0to255inclusive,specifyingalinearlevelforthefrontleftspeaker.

center Valuefrom0to255inclusive,specifyingalinearlevelforthecenter.

frontright Valuefrom0to255inclusive,specifyingalinearlevelforthefrontrightspeaker.

backleft Valuefrom0to255inclusive,specifyingalinearlevelforthebackleftspeaker.

backright Valuefrom0to255inclusive,specifyingalinearlevelforthebackrightspeaker.

lfe Valuefrom0to255inclusive,specifyingalinearlevelforthesubwooferspeaker.

ReturnValue


Remarks

FSOUND_ALLissupported.PassingthiswillsetthepanofALLchannelsavailable.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.----------FSOUND_SYSTEMCHANNELissupported.YoucansetthemixlevelsfortheFMODsoftwareengine,andALLsoftwaremixedsoundswillbeaffected.___________________Supportedonthefollowingplatforms:XBox

SeeAlso

FSOUND_GetPan,FSOUND_Reverb_SetChannelProperties


[APIfunction]

FSOUND_SetLoopMode

SetstheloopmodeforaparticularCHANNEL,notsample.

signedcharF_APIFSOUND_SetLoopMode(intchannel,unsignedintloopmode);

Parameters

channel Thechannelnumber/handletohaveitsloopmodeset.

loopmode Theloopmodetoset.ThiscanbeFSOUND_LOOP_NORMAL,FSOUND_LOOP_BIDIorFSOUND_LOOP_OFF.

ReturnValue


Remarks

FSOUND_ALLissupported.Passingthiswillsetloopmodesforallchannelsavailable.Note,thisdoesnotworkforhardwaresoundsplayedonhardwarechannelswhiletheyareplaying.Thefunctionhastobecalledwhenthechannelispaused.Softwarebasedsoundsdonothavethislimitation,andcanhavetheirloopmodechangedduringplayback,butforcompatibilityitisbesttousethepausemethod,elseyoumaygetdifferentbehaviourifhardwarevoicesdonotexist.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Sample_GetMode


[APIfunction]

FSOUND_SetMute

Mutesandun-mutesachannel.

signedcharF_APIFSOUND_SetMute(intchannel,signedcharmute);

Parameters

channel Thechannelnumber/handletomute/unmute.FSOUND_ALLcanalsobeused(seeremarks).mute Togglevalue-TRUEmutesoutthechannel,FALSEreenablesit.

ReturnValue


Remarks

FSOUND_ALLissupported.Passingthiswillmute/unmuteALLchannelsavailable.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetMute


[APIfunction]

FSOUND_SetPan

Setsachannelspanpositionlinearly

signedcharF_APIFSOUND_SetPan(intchannel,intpan);

Parameters

channel Thechannelnumber/handletochangethepanfor.FSOUND_ALLcanalsobeused(seeremarks)

pan

Thepanningpositionforthischanneltoset.parametersare:-from0(fullleft)to255(fullright)-FSOUND_STEREOPAN.Thisismeantforstereosamples,butwillworkonmonosamplesaswell.ItmakesbothleftandrightFULLvolumeinsteadof50/50asmiddlepanningdoes.Seeremarkssectionformoreinformationonthis.

ReturnValue


Remarks

FSOUND_ALLissupported.PassingthiswillsetthepanofALLchannelsavailable.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.----------Important:IfyouareplayingaSTEREOsample,andusingnormalmiddle

panning,itwillonlycomeoutathalfthevolumetheyaresupposedto.ToavoidthisuseFSOUND_STEREOpan.Panningworksinthefollowingmanner:fullleft:100toleft,0torightfullright:0toleft,100torightmiddle:71toleft,71torightFMODUses'constantpower'panning.Thecenterpositionis714749664neachchannelasitkeepsanevenRMSoutputlevelwhenmovingthesoundfromlefttoright.Placing504749664neachchannelforamiddlepositionisincorrect.Thepangraphforconstantpowerpanningresemblesacurveinsteadofstraightlines.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_MixBuffers,FSOUND_GetPan,FSOUND_Sample_SetDefaults,FSOUND_Sample_SetDefaultsEx,FSOUND_Stream_Play,FSOUND_Stream_PlayEx


[APIfunction]

FSOUND_SetPaused

Pausesorunpausesasoundchannel.

signedcharF_APIFSOUND_SetPaused(intchannel,signedcharpaused);

Parameters

channel Thechannelnumber/handletopauseorunpause.FSOUND_ALLcanalsobeused(seeremarks).paused TRUEpausesthischannel,FALSEunpausesit.

ReturnValue


Remarks

FSOUND_ALLissupported.Passingthiswillpause/unpauseALLchannelsavailable.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_FX_Enable,FSOUND_GetPaused,FSOUND_PlaySoundEx,FSOUND_Stream_PlayEx

Thisdocumentcopyright©FirelightTechnologies,Pty,Ltd,1999-2002.Allrightsreserved.

GeneratedFriNov1800:31:542005bySourceDocv0.10,theautomatedsourcecodedocumenter.

[APIfunction]

FSOUND_SetPriority

Setsachannelspriority.HigherprioritymeansitislesslikelytogetdiscardedwhenFSOUND_FREEisusedtoselectachannel,whenallchannelsarebeingused,andonehastoberejected.Ifachannelhasanequalprioritythenitwillbereplaced.

signedcharF_APIFSOUND_SetPriority(intchannel,intpriority);

Parameters

channel Thechannelnumber/handletochangethepriorityfor.FSOUND_ALLcanalsobeused(seeremarks).priority Theprioritytoset.Validrangesarefrom0(lowest)to255(highest)

ReturnValue


Remarks

FSOUND_ALLissupported.PassingthiswillsetthepriorityofALLchannelsavailable.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetPriority,FSOUND_GetReserved,FSOUND_Sample_SetDefaults,FSOUND_Sample_SetDefaultsEx,FSOUND_SetReserved


[APIfunction]

FSOUND_SetReserved

Thissetsthereservedstatusofachannel.Reservingachannelisrelatedtosettingitspriority,butreservingachannelmeansitcanNEVERbestolenbyachannelrequest.Itcouldbethoughtofasanextrahighpriority,butisdifferentinthatreservedchannelsdonotstealfromeachother,whereaschannelswithequalprioritiesdo(unlesstherearechannelswithlowerprioritiesthatitcanstealfrom).Ifallchannelswerereservedandanotherrequestforcameinforachannel,itwouldsimplyfailandthesoundwouldnotbeplayed.

signedcharF_APIFSOUND_SetReserved(intchannel,signedcharreserved);

Parameters

channelThechannelnumber/handletochangethepriorityfor.FSOUND_ALLcanalsobeused(seeremarks).FSOUND_FREEisNOTaccepted.

reservedReservedflag.ValuesacceptedareTRUE,toreserveachannel,andFALSEtoun-reserveachannel.

ReturnValue


Remarks

FSOUND_ALLissupported.PassingthiswillsetALLchannelstobereserved/unreserved.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetPriority,FSOUND_GetReserved,FSOUND_SetPriority


[APIfunction]

FSOUND_SetSurround

Setsachannelssurroundsoundstatus.Thissurroundsoundisafakedolbytrickthateffectivelypansthechanneltothecenter,butinvertsthewaveforminonespeakertomakeitsoundfullerorspacier,orlikeitiscomingoutofspacebetweenthe2speakers.Panningisignoredwhilesurroundisineffect.

signedcharF_APIFSOUND_SetSurround(intchannel,signedcharsurround);

Parameters

channel Thechannelnumber/handletochangethesurroundfor.FSOUND_ALLcanalsobeused(seeremarks).

surround Togglevalue-TRUEenablessurroundsoundonthechannel,FALSEdisablesit.

ReturnValue


Remarks

FSOUND_ALLissupported.PassingthiswillsetthesurroundsoundmodeofALLchannelsavailable.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.---------Notethisonlyworksonsoftwarechannels.___________________


SeeAlso

FSOUND_GetSurround


[APIfunction]

FSOUND_SetVolume

Setsachannelsvolumelinearly.ThisfunctionISaffectedbyFSOUND_SetSFXMasterVolume.

signedcharF_APIFSOUND_SetVolume(intchannel,intvol);

Parameters

channel Thechannelnumber/handletochangethevolumefor.FSOUND_ALLcanalsobeused(seeremarks)vol Thevolumetoset.Validrangesarefrom0(silent)to255(fullvolume)

ReturnValue


Remarks

FSOUND_ALLissupported.PassingthiswillsetthevolumeofALLchannelsavailable.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_MixBuffers,FSOUND_GetAmplitude,FSOUND_GetSubChannel,FSOUND_GetVolume,FSOUND_Sample_SetDefaults,FSOUND_Sample_SetDefaultsEx,

FSOUND_SetSFXMasterVolume,FSOUND_SetVolumeAbsolute,FSOUND_Stream_Play,FSOUND_Stream_PlayEx


[APIfunction]

FSOUND_SetVolumeAbsolute

Setsachannelsvolumelinearly.ThisfunctionisNOTaffectedbymastervolume.ThisfunctionisusedwhenyouwanttoquieteverythingdownusingFSOUND_SetSFXMasterVolume,butmakeachannelprominent.

signedcharF_APIFSOUND_SetVolumeAbsolute(intchannel,intvol);

Parameters

channel Thechannelnumber/handletochangethevolumefor.FSOUND_ALLcanalsobeused(seeremarks)vol Thevolumetoset.Validrangesarefrom0(silent)to255(fullvolume)

ReturnValue


Remarks

FSOUND_ALLissupported.PassingthiswillsettheabsolutevolumeofALLchannelsavailable.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvalueisnotusefulinmostcircumstances.-------------Agoodexampleofthisfunctionbeingusedforagameneedingavoiceover.Ifallthebackgroundsoundsweretooloudanddrownedoutthevoiceover,thereisnowaytofeasiblygothroughallthesfxchannelsandlowerthebackgroundnoisevolumes(somemightbeallocatedbymusic).

SimplylowerthebackgroundnoisewithFSOUND_SetSFXMasterVolume,anduseFSOUND_SetVolumeAbsolutetobringupthevolumeofthevoiceovertofull,andyouwillgetonechannelstandingoutamongsttherest.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetVolume,FSOUND_SetSFXMasterVolume,FSOUND_SetVolume,FSOUND_SetVolumeAbsolute


[APIfunction]

FSOUND_GetVolume

Returnsthelinearvolumeofthespecifiedchannelbetween0and255

intF_APIFSOUND_GetVolume(intchannel);

Parameters

channel Thechannelnumber/handletogetthevolumefrom.

ReturnValue

Onsuccess,thefollowingvaluesarereturned:0=silentto255=fullvolume.Onfailure,0isreturned.Toquailfyifthisisarealerror,callFSOUND_GetError.

Remarks


SeeAlso

FSOUND_GetError,FSOUND_SetVolume,FSOUND_SetVolumeAbsolute


[APIfunction]

FSOUND_GetAmplitude

Returnsthevolumeofthechannelbasedonallcombinationsofsetvolume,mastervolumeand3dposition.Worksonsoftwareandhardwarevoices.

intF_APIFSOUND_GetAmplitude(intchannel);

Parameters

channel Thechannelnumber/handletogettheamplitudefrom.

ReturnValue

Onsuccess,thefollowingvaluesarereturned:0=silentto255=fullvolume.Onfailure,0isreturned.Toquailfyifthisisarealerror,callFSOUND_GetError.

Remarks

ThisisnotthesameasFSOUND_GetCurrentLevels,asthatfunctiontakestheactualwaveformdataintoaccount.Thisfunctionsimplygivesafinalvolumebasedon3dpositionandvolumesettings.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetCurrentLevels,FSOUND_GetError,FSOUND_SetVolume


[APIfunction]

FSOUND_3D_SetAttributes

Thisupdatesthepositionandvelocityofa3dsoundplayingonachannel.

signedcharF_APIFSOUND_3D_SetAttributes(intchannel,constF_FLOAT_API*pos,constF_FLOAT_API*vel);

Parameters

channel Channelyouwanttoapply3dpositioningto.

posPointertoapositionvector(xyzfloattriplet)oftheemitterinworldspace,measuredindistanceunits.ThiscanbeNULLtoignoreit.

velPointertoavelocityvector(xyzfloattriplet),oftheemittermeasuredindistanceunitsPERSECOND.ThiscanbeNULLtoignoreit.

ReturnValue


Remarks

FSOUNDtreats+Xasright,+Yasup,and+Zasforwards.---------A'distanceunit'isspecifiedbyFSOUND_3D_SetDistanceFactor.Bydefaultthisissettometerswhichisadistancescaleof1.0.SeeFSOUND_3D_SetDistanceFactorformoreonthis.---------FSOUNDvectorsexpect3floatsrepresentingxyandzinthatorder.I.e.atypicaldefinitionofavectoris

typedefstruct{floatx;floaty;floatz;}VECTOR;orsimplyanarrayof3floats.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_GetAttributes,FSOUND_3D_GetMinMaxDistance,FSOUND_3D_Listener_GetAttributes,FSOUND_3D_Listener_SetAttributes,FSOUND_3D_Listener_SetCurrent,FSOUND_3D_SetAttributes,FSOUND_3D_SetDistanceFactor,FSOUND_3D_SetMinMaxDistance,FSOUND_3D_SetRolloffFactor,FSOUND_Sample_SetMinMaxDistance,FSOUND_Update


[APIfunction]

FSOUND_3D_SetMinMaxDistance

Setstheminimumandmaximumaudibledistanceforachannel.MinDistanceistheminimumdistancethatthesoundemitterwillceasetocontinuegrowinglouderat(asitapproachesthelistener).Withinthemindistanceitstaysattheconstantloudestvolumepossible.Outsideofthismindistanceitbeginstoattenuate.MaxDistanceisthedistanceasoundstopsattenuatingat.Beyondthispointitwillstayatthevolumeitwouldbeatmaxdistanceunitsfromthelistenerandwillnotattenuateanymore.MinDistanceisusefultogivetheimpressionthatthesoundisloudorsoftin3dspace.Anexampleofthisisasmallquietobject,suchasabumblebee,whichyoucouldsetamindistanceofto0.1forexample,whichwouldcauseittoattenuatequicklyanddissapearwhenonlyafewmetersawayfromthelistener.Anotherexampleisajumbojet,whichyoucouldsettoamindistanceof100.0,whichwouldkeepthesoundvolumeatmaxuntilthelistenerwas100metersaway,thenitwouldbehundredsofmetersmorebeforeitwouldfadeout.-------Insummary,increasethemindistanceofasoundtomakeit'louder'ina3dworld,anddecreaseittomakeit'quieter'ina3dworld.maxdistanceiseffectivelyobsoleteunlessyouneedthesoundtostopfadingoutatacertainpoint.Donotadjustthisfromthedefaultifyoudontneedto.Somepeoplehavetheconfusionthatmaxdistanceisthepointthesoundwillfadeoutto,thisisnotthecase.

signedcharF_APIFSOUND_3D_SetMinMaxDistance(intchannel,F_FLOAT_APImin,F_FLOAT_APImax);

Parameters

sptr Thechanneltohaveitsminimumandmaximumdistanceset.min Thechannelsminimumvolumedistancein"units".Seeremarksformore

onunits.

max Thechannelsmaximumvolumedistancein"units".Seeremarksformoreonunits.

ReturnValue


Remarks

FSOUND_ALLissupported.Passingthiswillsetthemin/maxdistanceonALLchannelsavailable.A'distanceunit'isspecifiedbyFSOUND_3D_SetDistanceFactor.Bydefaultthisissettometerswhichisadistancescaleof1.0.SeeFSOUND_3D_SetDistanceFactorformoreonthis.Thedefaultunitsforminimumandmaximumdistancesare1.0and1000000000.0f.Volumedropsoffatmindistance/distance.TodefinetheminandmaxdistancepersoundandnotperchanneluseFSOUND_Sample_SetMinMaxDistance.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_GetMinMaxDistance,FSOUND_3D_SetAttributes,FSOUND_3D_SetDistanceFactor,FSOUND_Sample_SetMinMaxDistance


[APIfunction]

FSOUND_SetCurrentPosition

SetsthecurrentpositionofthesoundinSAMPLESnotbytes.

signedcharF_APIFSOUND_SetCurrentPosition(intchannel,unsignedintpos);

Parameters

channel Thechannelnumber/handletohaveitsoffsetorpositionset.

offset TheoffsetinSAMPLESfromthestartofthesoundforthepositiontobesetto.

ReturnValue


Remarks

FSOUND_ALLissupported.PassingthissetthecurrentpositionforthesoundonALLchannelsavailable.OnXBOX,GameCubeandPlaystation2hardwarevoicesusingcompresseddata(ieXADPCM,VAGorGCADPCM),thisvaluewillnotbesampleaccurate,butwillberoundedtothenearestcompressionblocksize.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetCurrentPosition,FSOUND_SetFrequency


[APIfunction]

FSOUND_GetCurrentPosition

Returnsthecurrentplaycursorpositionofthespecifiedchannel.

unsignedintF_APIFSOUND_GetCurrentPosition(intchannel);

Parameters

channel Channelnumber/handletogetthecurrentpositionfrom.

ReturnValue

Onsuccess,theplaycursorpositioninSAMPLESisreturnedforthespecifiedchannel.Onfailure,0isreturned.

Remarks


SeeAlso

FSOUND_Record_StartSample,FSOUND_SetCurrentPosition


[APIfunction]

FSOUND_GetCurrentSample

Returnsthecurrentsamplebeingplayedonthespecifiedchannel.

FSOUND_SAMPLE*F_APIFSOUND_GetCurrentSample(intchannel);

Parameters

channel Channelnumber/handletogetthecurrentlyplayingsamplefrom.

ReturnValue

Onsuccess,apointertoasamplehandleisreturnedforthespecifiedchannel.Onfailure,NULLisreturned.

Remarks

NotethatcurrentsampledoesnotreturntoNULLwhenasoundhasended.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube


[APIfunction]

FSOUND_GetCurrentLevels

ReturnsaleftandrightVU/Levelreadingatthecurrentpositionofthespecifiedchannel.Levelsareareonlysupportedforsoftwarechannels.

DLL_APIsignedcharF_APIFSOUND_GetCurrentLevels(intchannel,F_FLOAT_API*l,F_FLOAT_API*r);

Parameters

channel Channelnumber/handletoretrieveleftandrightlevelfrom.l Pointertoafloatingpointvaluetostoreleftlevel,between0and1.r Pointertoafloatingpointvaluetostorerightlevel,between0and1.

ReturnValue


Remarks

Bydefaultthisfunctionisonlypointsampledandnotlatencyadjusted(itwillappeartotriggeraheadofwhenyouhearthesound).Tofixthisandgeta'perfect'setoflevelsinrealtime,useFSOUND_INIT_ACCURATEVULEVELSwithFSOUND_Init.-------------------TogetanoverallVUreadingforallsounds,addallVUvaluesforeachchanneltogether,andthenclipat1.0.Another(harder)wayistowriteadspunitthatreadsfromthemixbufferbeingpassedintoit.Note:Atrue'VU'shouldbesmoothed,butincasepeoplewereaftermoreaccuracythanasmoothedvalue,itwasdecidedtoreturntherawamplitude,and

lettheusersmooththeresultintheirownway.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetAmplitude,FSOUND_Init


[APIfunction]

FSOUND_GetFrequency

ReturnsthefrequencyinHZofthespecifiedchannel.

intF_APIFSOUND_GetFrequency(intchannel);

Parameters

channel Thenumber/handletogetthefrequencyfrom.

ReturnValue

Onsuccess,thefrequencyinHZofthespecifiedchannelisreturned.Onfailure,0isreturned.Toquailfyifthisisarealerror,callFSOUND_GetError.

Remarks


SeeAlso

FSOUND_GetError,FSOUND_SetFrequency


[APIfunction]

FSOUND_GetLoopMode

Getstheloopmodeforaparticularchannel.

unsignedintF_APIFSOUND_GetLoopMode(intchannel);

Parameters

channel Thechannelnumber/handletogettheloopmodefrom.

ReturnValue

Onsuccess,theloopmodeisreturned.Onfailure,0isreturned.

Remarks

Thisworksforallchanneltypes,whereassettingitwillnotwork.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Sample_SetMode


[APIfunction]

FSOUND_GetMixer

Returnsthecurrentlyusedmixertype.

intF_APIFSOUND_GetMixer();

ReturnValue

FSOUND_GetMixerreturnsadefenitionfromFSOUND_MIXERTYPES.SeeFSOUND_MIXERTYPESforvalidparametersanddescriptions.

Remarks


SeeAlso

FSOUND_DSP_Create,FSOUND_DSP_MixBuffers,FSOUND_GetMixer,FSOUND_MIXERTYPES,FSOUND_SetMixer


[APIfunction]

FSOUND_GetMute

Returnsifthechannelspecifiedismutedornot

signedcharF_APIFSOUND_GetMute(intchannel);

Parameters

channel Thechannelnumber/handletogetthemutestatusfrom

ReturnValue

TRUE-ThechannelhasmuteturnedONFALSE-ThechannelhasmuteturnedOFF

Remarks


SeeAlso

FSOUND_SetMute


[APIfunction]

FSOUND_GetNumSubChannels

Thisfunctionreturnsthenumberofsub-channelsstoredinamulti-channelchannelhandle,whichisonlypossiblewhenplayingbackamultichannel.FSBfile.

intF_APIFSOUND_GetNumSubChannels(intchannel);

Parameters

channelThevaluereturnedbyFSOUND_Stream_Play,FSOUND_Stream_PlayEx,FSOUND_PlaySound,FSOUND_PlaySoundEx.

ReturnValue

Onsuccess,thenumberofsubchannelsisreturnedOnfailure,0isreturned.

Remarks

Amultichannelsound,onlypossiblewiththe.FSBformat,cancontainmultiplesubchannels.Whenamultichannelsoundisplayed,multiplechannelsareallocatedatthesametime.Forexample,a8sounds/streamscanbeinterleavedintoamultichannelFSB.Thisfunctionwouldreturn8,as8realhardware/softwarevoicesareusedduringplayback.FSOUND_GetSubChannelcanbeusedtogetaccesstothesecondarychannels.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetSubChannel,FSOUND_PlaySound,FSOUND_PlaySoundEx,FSOUND_Stream_Play,FSOUND_Stream_PlayEx


[APIfunction]

FSOUND_GetPan

Returnsthelinearpanpositionofthespecifiedchannelbetween0and255

intF_APIFSOUND_GetPan(intchannel);

Parameters

channel Thechannelnumber/handletogetthepanfrom.

ReturnValue

Onsuccess,thefollowingvaluesarereturned:0=fullleftto128=middleto255=fullright,FSOUND_STEREOPANOnfailure,0isreturned.Toquailfyifthisisarealerror,callFSOUND_GetError.

Remarks


SeeAlso

FSOUND_GetError,FSOUND_SetLevels,FSOUND_SetPan


[APIfunction]

FSOUND_GetPaused

Getscurrentpausestatusofthechannel.

signedcharF_APIFSOUND_GetPaused(intchannel);

Parameters

channel Thechannelnumber/handletogetthepausedstatusfrom.

ReturnValue

TRUE-Thechanneliscurrentlypaused.FALSE-Thechannelisrunning.

Remarks

Thisfunctionisusefulforgamesthathaveapausemode,andyoudontwantthesoundstocontinueplaying,butyouwouldlikethemtocontinueonfromwheretheyleftoffwhenyouunpause.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_SetPaused


[APIfunction]

FSOUND_GetPriority

Getsasoundchannelspriority.Priorityisusedtodetermineifsoundeffectsshouldreplaceothersoundeffectswhenthechannellimithasbeenreached.SeeFSOUND_SetPriorityformoreinformation.

intF_APIFSOUND_GetPriority(intchannel);

Parameters

channel Thechannelnumber/handletogetthepriorityfrom.

ReturnValue

Onsuccess,thepriorityofthechannelisreturned.Rangesbetween0and255.Onfailure,0isreturned.Toquailfyifthisisarealerror,callFSOUND_GetError.

Remarks


SeeAlso

FSOUND_GetError,FSOUND_SetPriority,FSOUND_SetReserved


[APIfunction]

FSOUND_GetReserved

Getsasoundchannelsreservedstatus.priorityisusedtodetermineifsoundeffectsshouldmuscleoutothersoundeffectswhenthechannellimithasbeenreached.

signedcharF_APIFSOUND_GetReserved(intchannel);

Parameters

channel Thechannelnumber/handletogetthereservedstatusfrom.

ReturnValue

TRUEChannelisreservedandcannotbeselected.FALSEChannelisreservedandcanbeselected.

Remarks


SeeAlso

FSOUND_SetPriority,FSOUND_SetReserved


[APIfunction]

FSOUND_GetSubChannel

ThisfunctionreturnsachannelhandlefromasubchannelwithinamultichannelFSBfile,sothatitcanbemaniuplatedseperately,insteadofcontrollingthewholemultichannelarraywiththeparentchannelthattheuserretrievesfromFSOUND_PlaySoundetc.

intF_APIFSOUND_GetSubChannel(intchannel,intsubchannel);

Parameters

channelThevaluereturnedbyFSOUND_Stream_Play,FSOUND_Stream_PlayEx,FSOUND_PlaySound,FSOUND_PlaySoundEx.

subchannel Offsetfromtheparentchannelintothemultichannelarray.

ReturnValue

Onsuccess,arawchannelhandleisreturned.Onfailure,-1isreturned.

Remarks

Amultichannelsound,onlypossiblewiththe.FSBformat,cancontainmultiplesubchannels.Whenamultichannelsoundisplayed,multiplechannelsareallocatedatthesametime.Normallyyoucanjustusetheparenthandle,andthingslikeFSOUND_SetVolumewillaffectallsubchannelsatthesametime.Withthisfunction,youcangetaccesstotherawsubchannelstoallowmanipulationofeachvoiceseperatelywithinthemultichannelarray.Forexample,a8sounds/streamscanbeinterleavedintoamultichannelFSB.Ifyouspecifiedasubchannelof7,itwouldreturnachannelhandletothelastchannelinthemultichannelarray.

Asubchannelindexof0istheparentchannel,andthesameasthevoicepassedinisaparameter.ThenumberofsubchannelswithinamultichannelvoicecanbedeterminedwithFSOUND_GetNumSubChannels.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetNumSubChannels,FSOUND_PlaySound,FSOUND_PlaySoundEx,FSOUND_SetVolume,FSOUND_Stream_Play,FSOUND_Stream_PlayEx


[APIfunction]

FSOUND_GetSurround

Returnsthesurroundsoundstatusofthespecifiedchannel.

signedcharF_APIFSOUND_GetSurround(intchannel);

Parameters

channel Thechannelnumber/handletogetthesurroundsoundstatusfrom.

ReturnValue

Onsuccess,TRUEisreturnedmeaningthechannelhassurroundsoundturnedONOnfailure,FALSEisreturnedmeaningthechannelhassurroundsoundturnedOFF

Remarks

Surroundsoundonlyworksonsoftwarechannels.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_SetSurround


[APIfunction]

FSOUND_IsPlaying

Returnsifthechanneliscurrentlyplayingornot.

signedcharF_APIFSOUND_IsPlaying(intchannel);

Parameters

channel Channelnumber/handletogettheplayingstatusfrom.

ReturnValue

TRUEchanneliscurrentlyactiveandplayingFALSEchanneliscurrentlyidle.

Remarks



[APIfunction]

FSOUND_3D_GetAttributes

signedcharF_APIFSOUND_3D_GetAttributes(intchannel,F_FLOAT_API*pos,F_FLOAT_API*vel);

Parameters

channel Channelyouwanttoget3dinformationfrom

posPointertoapositionvector(xyzfloattriplet)oftheemitterinworldspace,measuredindistanceunits.ThiscanbeNULLtoignoreit.

velPointertoavelocityvector(xyzfloattriplet),oftheemittermeasuredindistanceunitsPERSECOND.ThiscanbeNULLtoignoreit.

ReturnValue


Remarks

A'distanceunit'isspecifiedbyFSOUND_3D_SetDistanceFactor.Bydefaultthisissettometerswhichisadistancescaleof1.0.SeeFSOUND_3D_SetDistanceFactorformoreonthis.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_Listener_SetAttributes,FSOUND_3D_SetAttributes,FSOUND_3D_SetDistanceFactor,FSOUND_Sample_SetMinMaxDistance


[APIfunction]

FSOUND_3D_GetMinMaxDistance

Returnsthecurrentminandmaxdistanceforachannel.

DLL_APIsignedcharF_APIFSOUND_3D_GetMinMaxDistance(intchannel,F_FLOAT_API*mindistance,F_FLOAT_API*maxdistance);

Parameters

channel Channelnumber/handletoretrieveminandmaxdistancefrom.mindistance Pointertoafloatingpointvaluetostoremindistance.maxdistance Pointertoafloatingpointvaluetostoremaxdistance.

ReturnValue


Remarks


SeeAlso

FSOUND_3D_SetAttributes,FSOUND_3D_SetMinMaxDistance,FSOUND_Sample_SetMinMaxDistance


[APIfunction]

FSOUND_3D_Listener_GetAttributes

Thisretrievestheposition,velocityandorientationofa3dsoundlistener.

voidF_APIFSOUND_3D_Listener_GetAttributes(F_FLOAT_API*pos,F_FLOAT_API*vel,F_FLOAT_API*fx,F_FLOAT_API*fy,F_FLOAT_API*fz,F_FLOAT_API*tx,F_FLOAT_API*ty,F_FLOAT_API*tz);

Parameters

posPointertoapositionvector(xyzfloattriplet),ofthelistenerinworldspace,measuredindistanceunits.ThiscanbeNULLtoignoreit.

velPointertoavelocityvector(xyzfloattriplet),ofthelistenermeasuredindistanceunitsPERSECOND.ThiscanbeNULLtoignoreit.

fx pointertoxcomponentofaFORWARDunitlengthorientationvectorThiscanbeNULLtoignoreit.

fy pointertoycomponentofaFORWARDunitlengthorientationvectorThiscanbeNULLtoignoreit.

fz pointertozcomponentofaFORWARDunitlengthorientationvectorThiscanbeNULLtoignoreit.

txpointertoxcomponentofaTOPorupwardsfacingunitlengthorientationvectorThiscanbeNULLtoignoreit.

typointertoycomponentofaTOPorupwardsfacingunitlengthorientationvectorThiscanbeNULLtoignoreit.pointertozcomponentofaTOPorupwardsfacingunitlengthorientation

tz vectorThiscanbeNULLtoignoreit.

ReturnValue


Remarks

FSOUNDtreats+Xasright,+Yasup,and+Zasforwards.(lefthanded)Tomaptoyourowncoordinatesystem,flipandexchangethesevalues.Forexampleifyouwantedtouserighthandedcoordinates,youwouldnegatetheZvalueofyourowndirectionvector.OrientationvectorsareexpectedtobeofUNITlength.Thismeansthemagnitudeofthevectorshouldbe1.0f.---------A'distanceunit'isspecifiedbyFSOUND_3D_SetDistanceFactor.Bydefaultthisissettometerswhichisadistancescaleof1.0.SeeFSOUND_3D_SetDistanceFactorformoreonthis.---------PleaseremembertouseunitsPERSECOND,NOTPERFRAMEasthisisacommonmistake.Donotjustuse(pos-lastpos)fromthelastframe'sdataforvelocity,asthisisnotcorrect.YouneedtotimecompensateitsoitisgiveninunitsperSECOND.Youcouldalteryourpos-lastposcalculationtosomethinglikethis.vel=(pos-lastpos)/(timetakensincelastframeinseconds).I.e.at60fpstheformulawouldlooklikethisvel=(pos-lastpos)/0.0166667.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_Listener_SetCurrent,FSOUND_3D_SetAttributes,FSOUND_3D_SetDistanceFactor,FSOUND_3D_SetDopplerFactor


[APIfunction]

FSOUND_3D_Listener_SetAttributes

Thisupdatestheposition,velocityandorientationofa3dsoundlistener.

voidF_APIFSOUND_3D_Listener_SetAttributes(constF_FLOAT_API*pos,constF_FLOAT_API*vel,F_FLOAT_APIfx,F_FLOAT_APIfy,F_FLOAT_APIfz,F_FLOAT_APItx,F_FLOAT_APIty,F_FLOAT_APItz);

Parameters

posPointertoapositionvector(xyzfloattriplet),ofthelistenerinworldspace,measuredindistanceunits.ThiscanbeNULLtoignoreit.

velPointertoavelocityvector(xyzfloattriplet),ofthelistenermeasuredindistanceunitsPERSECOND.ThiscanbeNULLtoignoreit.

fx xcomponentofaFORWARDunitlengthorientationvectorfy ycomponentofaFORWARDunitlengthorientationvectorfz zcomponentofaFORWARDunitlengthorientationvectortx xcomponentofaTOPorupwardsfacingunitlengthorientationvectorty ycomponentofaTOPorupwardsfacingunitlengthorientationvectortz zcomponentofaTOPorupwardsfacingunitlengthorientationvector

ReturnValue


Remarks

FSOUNDtreats+Xasright,+Yasup,and+Zasforwards.(lefthanded)Tomaptoyourowncoordinatesystem,flipandexchangethesevalues.Forexampleifyouwantedtouserighthandedcoordinates,youwouldnegatetheZvalueofyourowndirectionvector.OrientationvectorsareexpectedtobeofUNITlength.Thismeansthemagnitudeofthevectorshouldbe1.0f.---------A'distanceunit'isspecifiedbyFSOUND_3D_SetDistanceFactor.Bydefaultthisissettometerswhichisadistancescaleof1.0.SeeFSOUND_3D_SetDistanceFactorformoreonthis.---------PleaseremembertouseunitsPERSECOND,NOTPERFRAMEasthisisacommonmistake.Donotjustuse(pos-lastpos)fromthelastframe'sdataforvelocity,asthisisnotcorrect.YouneedtotimecompensateitsoitisgiveninunitsperSECOND.Youcouldalteryourpos-lastposcalculationtosomethinglikethis.vel=(pos-lastpos)/(timetakensincelastframeinseconds).Ieat60fpstheformulawouldlooklikethisvel=(pos-lastpos)/0.0166667.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_GetAttributes,FSOUND_3D_Listener_SetCurrent,FSOUND_3D_SetAttributes,FSOUND_3D_SetDistanceFactor,FSOUND_3D_SetDopplerFactor,FSOUND_3D_SetRolloffFactor,FSOUND_Update


[APIfunction]

FSOUND_3D_Listener_SetCurrent

Setsthecurrentlistenernumberandnumberoflisteners,iftheuserwantstosimulatemultiplelistenersatonce.Thisisusuallyforthecaseinagamewherethereisasplitscreenandmultipleplayersplayingthegameatonce.

voidF_APIFSOUND_3D_Listener_SetCurrent(intcurrent,intnumlisteners);

Parameters

current Currentlistenernumber.Listenercommandsfollowingthisfunctioncallwillaffectthislistenernumber.(default:0)

numlisteners Numberoflistenersactive.(default:1)

ReturnValue

void

Remarks

OnlyaffectsFSOUND_3D_Listener_SetAttributesandFSOUND_3D_Listener_GetAttributes.Settingmorethan1listenerwillturnoffdopplerandcauseallpanningtobeignoredand3dsoundwillcomefromthecenter(mono).-------------ForWIN32FSOUND_HW3Dbasedsounds,channelsmusthavetheirattributessetafterthisfunctioniscalled,otherwiseunexpectedaudibleresultsmayoccur.ForexampleyoucannotupdateyourchannelswithFSOUND_3D_SetAttributes,callFSOUND_3D_Listener_SetCurrent,andthencallFSOUND_Updateandexpectallthevoicestoupdatecorrectly.ThecorrectorderistocallFSOUND_3D_Listener_SetCurrentfirst,thenupdateallchannelswithFSOUND_3D_SetAttributes,thencallFSOUND_Update.

ThisisduetoDirectSoundnotsupportingmultiplelisteners,soFMODhastodoinversetransformsonthepositionstosimulateitwithonelistener,atthetimeFSOUND_3D_SetAttributesiscalled.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_Listener_GetAttributes,FSOUND_3D_Listener_SetAttributes,FSOUND_3D_Listener_SetCurrent,FSOUND_3D_SetAttributes,FSOUND_Update


[APIfunction]

FSOUND_3D_SetDistanceFactor

SetsFMOD's3denginerelativedistancefactor,comparedto1.0meters.Itequatesto'howmanyunitspermeter'doesyourenginehave.

voidF_APIFSOUND_3D_SetDistanceFactor(F_FLOAT_APIfactor);

Parameters

scale 1.0=1meterunits.Ifyouareusingfeetthenscalewouldequal3.28.

ReturnValue

void

Remarks

Bydefaultthisvalueissetat1.0,ormeters.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_GetAttributes,FSOUND_3D_Listener_GetAttributes,FSOUND_3D_Listener_SetAttributes,FSOUND_3D_SetAttributes,FSOUND_3D_SetMinMaxDistance,FSOUND_3D_SetRolloffFactor,FSOUND_Sample_GetMinMaxDistance,FSOUND_Sample_SetMinMaxDistance


[APIfunction]

FSOUND_3D_SetDopplerFactor

Setsthedopplershiftscalefactor.

voidF_APIFSOUND_3D_SetDopplerFactor(F_FLOAT_APIscale);

Parameters

scale Dopplershiftscale.DefaultvalueforFSOUNDis1.0f

ReturnValue

void

Remarks

Thisisageneralscalingfactorforhowmuchthepitchvariesduetodopplershifting.Increasingthevalueabove1.0exaggeratestheeffect,whereasloweringitreducestheeffect.0removestheeffectalltogether.FMOD'sspeedofsoundataDopplerFactorof1.0is340m/s.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_Listener_GetAttributes,FSOUND_3D_Listener_SetAttributes,FSOUND_Update


[APIfunction]

FSOUND_3D_SetRolloffFactor

Setstheglobalattenuationrollofffactor.Normallyvolumeforasamplewillscaleat1/distance.Thisgivesalogarithmicattenuationofvolumeasthesourcegetsfurtheraway(orcloser).Settingthisvaluemakesthesounddropofffasterorslower.Thehigherthevalue,thefastervolumewillfalloff.Thelowerthevalue,thesloweritwillfalloff.Forexamplearollofffactorof1willsimulatetherealworld,whereasavalueof2willmakesoundsattenuate2timesquicker.

voidF_APIFSOUND_3D_SetRolloffFactor(F_FLOAT_APIfactor);

Parameters

rolloff Therollofffactortosetforthissample.Validrangesare0to10.

ReturnValue

void

Remarks

---------A'distanceunit'isspecifiedbyFSOUND_3D_SetDistanceFactor.Bydefaultthisissettometerswhichisadistancescaleof1.0.SeeFSOUND_3D_SetDistanceFactorformoreonthis.---------Thedefaultrollofffactoris1.0.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_3D_Listener_SetAttributes,FSOUND_3D_SetAttributes,FSOUND_3D_SetDistanceFactor


[APIfunction]

FSOUND_Stream_AddSyncPoint

Addsausersynchronizationcallbackpointintoastream.

DLL_APIFSOUND_SYNCPOINT*F_APIFSOUND_Stream_AddSyncPoint(FSOUND_STREAM*stream,unsignedintpcmoffset,constchar*name);

Parameters

stream Thestreamtoaddasyncpointto.pcmoffset OffsetinSAMPLES(notbytes).

name Thenameofthesyncpoint,whichwillbepassedintothesynccallbackwhenitistriggered.

ReturnValue

Onsuccess,asyncpointhandleisreturned.Onfailure,NULLisreturned.

Remarks

IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillnotsucceeduntilthestreamisready.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_DeleteSyncPoint,FSOUND_Stream_GetNumSyncPoints,FSOUND_Stream_GetSyncPoint,FSOUND_Stream_GetSyncPointInfo,FSOUND_Stream_SetSyncCallback


[APIfunction]

FSOUND_Stream_Close

ShutsdownandreleasesanFSOUNDstream.

signedcharF_APIFSOUND_Stream_Close(FSOUND_STREAM*stream);

Parameters

stream Pointertothestreamtobecloseddown.

ReturnValue


Remarks

IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillnotsucceeduntilthestreamisready.Theonlyexceptiontothisruleisforinternetstreams-thisfunctionwillsuccessfullycloseaninternetstreamthathasbeenopenedwithFSOUND_NONBLOCKINGbeforethatstreamisready.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_Create,FSOUND_Stream_Net_GetBufferProperties,FSOUND_Stream_Net_GetLastServerStatus,FSOUND_Stream_Net_GetStatus,FSOUND_Stream_Net_SetBufferProperties,FSOUND_Stream_Net_SetMetadataCallback,FSOUND_Stream_Net_SetProxy,FSOUND_Stream_Net_SetTimeout,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_PlayEx,

FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_Create

Createsauserdefinablestreamfilereadyforplaying.Thestreamisservicedthroughacallback.

DLL_APIFSOUND_STREAM*F_APIFSOUND_Stream_Create(FSOUND_STREAMCALLBACKcallback,intlenbytes,unsignedintmode,intsamplerate,void*userdata);

Parameters

callback Apointertoauserdefinedstreamcallbackfunction.

lenbytes SizeofthedatainBYTESthecallbackwillrequiretobewrittentothebuffer.

mode Descriptionoftherawsampledatabeingopened.seeFSOUND_MODESforadescriptionofthesemodes.

samplerate Rateofplayback.Becarefulyoudontsetthesampleratetoohighsothatthestreamservicer(ietheharddisk)maynotkeepup.

userdata Userdatathatispassedbackintothestreamcallbackwhentriggered.

ReturnValue

Onsuccess,apointertoanopenedstreamisreturned.Onfailure,NULLisreturned.

Remarks

ThismethodonlysupportsSIGNEDRAWstreamstobewrittentothebuffersuppliedbythecallback.Theycanbe8or16bit,monoorstereo.'lenbytes'mayberoundeddowntothenearestsamplealignmentinbytes.Ieif

youspecified1001bytesfora16bitstereosamplestream,lenwouldreturn1000inthecallback.(250samples*4bytespersample)PlayStation2IMPORTANT!:ifFSOUND_SendDataisNOTcalledfromthestreamcallbacktheIOPwillhangbecauseitiswaitingforthiscommandtobeexecutedbeforeitcanunlockitsbuffer.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_MODES,FSOUND_SendData,FSOUND_Stream_Close,FSOUND_Stream_Play,FSOUND_Stream_PlayEx,FSOUND_Stream_SetBufferSize,FSOUND_Stream_Stop,FSOUND_STREAMCALLBACK


[APIfunction]

FSOUND_Stream_CreateDSP

AllowstheusertoaddacustomDSPunittoastream.

FSOUND_DSPUNIT*F_APIFSOUND_Stream_CreateDSP(FSOUND_STREAM*stream,FSOUND_DSPCALLBACKcallback,intpriority,void*userdata);

Parameters

stream ThestreampointertohaveaDSPattachedto.callbackAstandardFSOUND_DSPCALLBACKfunctioncallbackpointer.priority Thepriority,orpositionwithinthestreamsDSPchaintoplacetheunit.param AuserparameterthatgetspassedbackintotheDSPcallback.

ReturnValue

Onsuccess,ahandletotheFSOUND_DSPUNITisreturned.AllDSPfunctionsareperformableonthis.Onfailure,0isreturned.

Remarks

ThepriorityforastreamDSPunitisnotrelatedtotheprioritiesspecifiedinfmod.h.Theprioritiesareanythingfom0onwards,andALWAYScomeafterdataisread/decodedforthestream.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_DSP_Create,FSOUND_DSPCALLBACK


[APIfunction]

FSOUND_Stream_DeleteSyncPoint

Removesausersynchronizationcallbackpointfromastream.

DLL_APIsignedcharF_APIFSOUND_Stream_DeleteSyncPoint(FSOUND_SYNCPOINT*point);

Parameters

point Thesyncpointtoremove

ReturnValue


Remarks


SeeAlso

FSOUND_Stream_AddSyncPoint,FSOUND_Stream_GetNumSyncPoints,FSOUND_Stream_GetSyncPoint,FSOUND_Stream_GetSyncPoints,FSOUND_Stream_SetSyncCallback


[APIfunction]

FSOUND_Stream_FindTagField

Findatagfieldassociatedwithanopenstreambynameandtype.

signedcharF_APIFSOUND_Stream_FindTagField(FSOUND_STREAM*stream,inttype,constchar*name,void**value,int*length);

Parameters

stream Thestreamtogetthetagfieldfrom.type Thetypeofthetagfieldtoretrieve.SeeFSOUND_TAGFIELD_TYPE.name Thenameofthetagfieldtoretrieve.value Pointertoavariablethatwillreceiveapointertothetagfielddata.length Pointertoavariablethatwillreceivethelengthofthetagfielddata.

ReturnValue


Remarks

___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh

SeeAlso

FSOUND_Stream_GetNumTagFields,FSOUND_Stream_GetTagField,FSOUND_TAGFIELD_TYPE


[APIfunction]

FSOUND_Stream_GetLength

ReturnsthesizeofthestreaminBYTES.

intF_APIFSOUND_Stream_GetLength(FSOUND_STREAM*stream);

Parameters

streamApointertothestreamtohaveitslengthreturned.

ReturnValue

Onsuccess,thesizeofthestreaminBYTESisreturned.Onfailure,0isreturned.

Remarks

Positionfunctionsforstreamsworkinbytesnotsamples.-----ThisfunctionisnotsupportedforURLbasedstreamsovertheinternet.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_GetLengthMs,FSOUND_Stream_GetPosition,FSOUND_Stream_Open,FSOUND_Stream_SetPosition,FSOUND_Stream_SetTime


[APIfunction]

FSOUND_Stream_GetLengthMs

ReturnsthesizeofthestreaminMILLISECONDS.

intF_APIFSOUND_Stream_GetLengthMs(FSOUND_STREAM*stream);

Parameters

streamApointertothestreamtohaveitstotaldurationreturned.

ReturnValue

Onsuccess,thesizeofthestreaminMILLISECONDSisreturned.Onfailure,0isreturned.

Remarks

FSOUND_MPEGACCURATEwillneedtobeusedwithmp3filesthatuseVBRencodingformoreaccuracy.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_GetLength,FSOUND_Stream_Open


[APIfunction]

FSOUND_Stream_GetMode

Retrievesthemodeofthestream.

unsignedintF_APIFSOUND_Stream_GetMode(FSOUND_STREAM*stream);

Parameters

stream Pointertothestreamtogetthemodefrom.

ReturnValue

Remarks

IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillnotsucceeduntilthestreamisready.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_MODES,FSOUND_Stream_SetMode


[APIfunction]

FSOUND_Stream_GetNumSubStreams

Returnsthenumberofsubstreamsinsideamulti-streamFSBbankfile.

intF_APIFSOUND_Stream_GetNumSubStreams(FSOUND_STREAM*stream);

Parameters

stream Pointertothestreamtoquery.

ReturnValue

Onsuccess,thenumberofFSBsubstreamsisreturned.Onfailure,0isreturned.

Remarks


SeeAlso

FSOUND_Stream_SetSubStream,FSOUND_Stream_SetSubStreamSentence


[APIfunction]

FSOUND_Stream_GetNumSyncPoints

Returnsthenumberofsyncpointswithinastream.

DLL_APIintF_APIFSOUND_Stream_GetNumSyncPoints(FSOUND_STREAM*stream);

Parameters

stream Thestreamtorequestthenumberofsyncpointsfrom.

ReturnValue

Onsuccess,Thenumberofsyncpointsinastreamarereturned.Onfailure,-1isreturned.

Remarks


SeeAlso

FSOUND_Stream_AddSyncPoint,FSOUND_Stream_DeleteSyncPoint,FSOUND_Stream_GetSyncPointInfo,FSOUND_Stream_SetSyncCallback


[APIfunction]

FSOUND_Stream_GetNumTagFields

Getthenumberoftagfieldsassociatedwiththespecifiedstream.

signedcharF_APIFSOUND_Stream_GetNumTagFields(FSOUND_STREAM*stream,int*num);

Parameters

stream Thestreamtogetthenumberoftagfieldsfor.

num Pointertoavariablethatwillreceivethenubmeroftagfieldsassociatedwiththespecifiedstream.

ReturnValue


Remarks


SeeAlso

FSOUND_Stream_FindTagField,FSOUND_Stream_GetTagField


[APIfunction]

FSOUND_Stream_GetOpenState

IfastreamisopenedwithFSOUND_NONBLOCKING,thisfunctionreturnsthestateoftheopeningstream.

intF_APIFSOUND_Stream_GetOpenState(FSOUND_STREAM*stream);

Parameters

stream Pointertothestreamtogettheopenstatefrom.

ReturnValue

0=streamisopenedandready.-1=streamhandlepassedinisinvalid.-2=streamisstillopeningorperformingaSetSubStreamcommand.-3=streamfailedtoopen.(filenotfound,outofmemoryorothererror).-4=connectingtoremotehost(internetstreamsonly)-5=streamisbufferingdata(internetstreamsonly)

Remarks

AblockingstreamwillreturnNULLfromFSOUND_Stream_Opensoareturnvalueof-3isredundantinthiscase.Ablockingstreamwillalwaysreturn0ifitisnotNULL.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_Open,FSOUND_Stream_SetSubStream,FSOUND_Stream_SetSubStreamSentence


[APIfunction]

FSOUND_Stream_GetPosition

ReturnsthecurrentFILEpositionofthestreamofthestreaminBYTES.

unsignedintF_APIFSOUND_Stream_GetPosition(FSOUND_STREAM*stream);

Parameters

stream Pointertothestreamtohaveitspositionreturned.

ReturnValue

Onsuccess,thecurrentstream'spositioninBYTESisreturned.Onfailure,0isreturned.

Remarks

Positionfunctionsforstreamsworkinbytesnotsamples.Positioninformationisalsobasedonthecurrentfileposition,nottheactualplayingposition,soifthestreamisonlyupdatedevery100ms,thenthepositionwillonlybeupdatedevery100ms.-----ThisfunctionisnotsupportedforURLbasedstreamsovertheinternetorCDDAstreams___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_GetLength,FSOUND_Stream_SetPosition,FSOUND_Stream_SetTime


[APIfunction]

FSOUND_Stream_GetSample

ReturnstheFSOUND_SAMPLEdefinitionthatthestreamusesinternally.Youcanusethistogetavarietyofinformationlikethesongsname,defaultspeedandmore.

FSOUND_SAMPLE*F_APIFSOUND_Stream_GetSample(FSOUND_STREAM*stream);

Parameters

streamApointertothestreamtohaveitsinternalsamplepointerreturned.

ReturnValue

Onsuccess,ahandletotheFSOUND_SAMPLEdefinitionisreturned.Onfailure,0isreturned.

Remarks



[APIfunction]

FSOUND_Stream_GetSyncPoint

Obtainsasyncpointbyindex.Thisisusefulwhenyouhaventcreatedyourown,ieitcamefromawavfile.

DLL_APIFSOUND_SYNCPOINT*F_APIFSOUND_Stream_GetSyncPoint(FSOUND_STREAM*stream,intindex);

Parameters

stream Thestreamtorequestthesyncpointfrom.index Thesyncpointoffsetintothestream.

ReturnValue

Onsuccess,ahandletoasyncpointisreturned.Onfailure,NULLisreturned.

Remarks

Pointsareloadedinorderofoffset,sotheindexwillrepresentthesmallestpointtothelargest.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_AddSyncPoint,FSOUND_Stream_DeleteSyncPoint,FSOUND_Stream_GetSyncPointInfo,FSOUND_Stream_SetSyncCallback


[APIfunction]

FSOUND_Stream_GetSyncPointInfo

Retrievesthenameandpcmoffsetinsamplesforaspecifiedsyncpoint.

char*F_APIFSOUND_Stream_GetSyncPointInfo(FSOUND_SYNCPOINT*point,unsignedint*pcmoffset);

Parameters

point Thehandletothesyncpointtoretrieveinformationfrom.

pcmoffset ApointertoanintegerthatwillreceivethesyncpointoffsetinpcmSAMPLES.AvalueofNULLwillbeignored.

ReturnValue

Onsuccess,thenameofthesyncpointisreturnedasastring.Onfailure,NULLisreturned.

Remarks

ConvertsamplestotimebydividingthePCMvaluebythedefaultsamplerate.Thiswouldgiveyouthevalueinseconds.Multiplyby1000togetmilliseconds.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_AddSyncPoint,FSOUND_Stream_GetNumSyncPoints,FSOUND_Stream_GetSyncPoint,FSOUND_Stream_SetSyncCallback


[APIfunction]

FSOUND_Stream_GetTagField

Getatagfieldassociatedwithanopenstream.

signedcharF_APIFSOUND_Stream_GetTagField(FSOUND_STREAM*stream,intnum,int*type,char**name,void**value,int*length);

Parameters

stream Thestreamtogetthetagfieldfrom.num Thenumberofthetagfieldtoretrieve.

type Pointertoavariablethatwillreceivethetypeofthetagfieldthatwasretrieved.SeeFSOUND_TAGFIELD_TYPE.

name Pointertoavariablethatwillreceivethenameofthetagfieldasanull-terminatedASCIIstring.

value Pointertoavariablethatwillreceiveapointertothetagfielddata.length Pointertoavariablethatwillreceivethelengthofthetagfielddata.

ReturnValue


Remarks

Donotattempttomodifyorfreeanypointersreturnedbythisfunction.Ifthisfunctionreturnssuccessfully,"value"willcontainapointertoapieceoftag-field-specificdata-donotassumeitwillalwayspointtoanull-terminatedASCIIstring.___________________

Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh

SeeAlso

FSOUND_Stream_FindTagField,FSOUND_Stream_GetNumTagFields,FSOUND_TAGFIELD_TYPE


[APIfunction]

FSOUND_Stream_GetTime

Returnsthecurrenttimeoffsetinstreaminmilliseconds.

intF_APIFSOUND_Stream_GetTime(FSOUND_STREAM*stream);

Parameters

stream Pointertothestreamtogetthecurrentlyplayingtimeoffset.

ReturnValue

Onsuccess,thecurrentstream'spositioninmillisecondsisreturned.Onfailure,0isreturned.

Remarks

FSOUND_MPEGACCURATEwillneedtobeusedwithmp3filesthatuseVBRencodingformoreaccuracy.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_SetTime


[APIfunction]

FSOUND_Stream_Net_GetBufferProperties

Getsbuffersizeandthresholdsthatwillbeusedwhenopeningnewinternetstreams.

signedcharF_APIFSOUND_Stream_Net_GetBufferProperties(int*buffersize,int*prebuffer_percent,int*rebuffer_percent);

Parameters

buffersize Pointertosizeinbytesofthestreamingbuffer.

prebuffer_percent Pointertohowmuchtoprebufferwhenastreamisfirstopened.Valuesareexpressedasapercentagefrom1to99.

rebuffer_percentPointertohowmuchtorebufferafterastreamhassufferedabufferunderrun.Valuesareexpressedasapercentagefrom1to99.

ReturnValue


Remarks

Thisfunctionreturnsthevaluesthatwillbeusedforsubsequentinternetstreamopens.Internetstreamsthatalreadyexistmayhavedifferentvalues.AnyoftheparameterscanbeNULL,inwhichcase,theywillbeignored.___________________Supportedonthefollowingplatforms:Win32,Macintosh,Linux

SeeAlso

FSOUND_Stream_Close,FSOUND_Stream_Net_GetLastServerStatus,

FSOUND_Stream_Net_GetStatus,FSOUND_Stream_Net_SetBufferProperties,FSOUND_Stream_Net_SetMetadataCallback,FSOUND_Stream_Net_SetProxy,FSOUND_Stream_Net_SetTimeout,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_Net_GetLastServerStatus

ThisfunctionreturnsapointertothelastHTTPstatuslinethatwasreceivedwhenconnectingtoaninternetstream.

char*F_APIFSOUND_Stream_Net_GetLastServerStatus();

ReturnValue

PointertothelastHTTPstatusline(null-terminatedASCIIstring)thatwasreceived.

Remarks

Theresultofthisfunctionshouldbeusedforinformationalpurposesonly.ThisfunctionprovidesnofacilitytodiscoverwhichinternetstreamthelastHTTPstatuspertainstowhentherearemultipleinternetstreamsopen.___________________Supportedonthefollowingplatforms:Win32,Macintosh,Linux

SeeAlso

FSOUND_Stream_Close,FSOUND_Stream_Net_GetBufferProperties,FSOUND_Stream_Net_GetStatus,FSOUND_Stream_Net_SetBufferProperties,FSOUND_Stream_Net_SetMetadataCallback,FSOUND_Stream_Net_SetProxy,FSOUND_Stream_Net_SetTimeout,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_Net_GetStatus

Getvariousstatusinformationforaninternetstream.

signedcharF_APIFSOUND_Stream_Net_GetStatus(FSOUND_STREAM*stream,int*status,int*bufferused,int*bitrate,unsignedint*flags);

Parameters

stream Thestreamtogetstatusinformationon.

status Pointertoavariablethatwillreceiveastatusvalue.SeeFSOUND_STREAM_NET_STATUS.

bufferused Pointertoavariablethatwillreceivethepercentageofthereadbufferthatiscurrentlyinuse.

bitrate Pointertoavariablethatwillreceivethecurrentbitrateofthestream.

flags Pointertoavariablethatwillreceiveaflagsfielddescribingprotocolandformatinformation.SeeFSOUND_STATUS_FLAGS.

ReturnValue


Remarks


SeeAlso

FSOUND_STATUS_FLAGS,FSOUND_Stream_Close,FSOUND_Stream_Net_GetBufferProperties,FSOUND_Stream_Net_GetLastServerStatus,FSOUND_Stream_Net_SetBufferProperties,FSOUND_Stream_Net_SetMetadataCallback,FSOUND_Stream_Net_SetProxy,FSOUND_Stream_Net_SetTimeout,FSOUND_STREAM_NET_STATUS,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_Net_SetBufferProperties

Setsbuffersizeandthresholdstousewhenopeningnewinternetstreams.

signedcharF_APIFSOUND_Stream_Net_SetBufferProperties(intbuffersize,intprebuffer_percent,intrebuffer_percent);

Parameters

buffersize Sizeinbytesofthestreamingbuffer.Makeitbiggertoavoidbufferunderruns.(Default=64000)

prebuffer_percentHowmuchtoprebufferwhenastreamisfirstopened.Valuesareexpressedasapercentagefrom1to99.(Default=95)

rebuffer_percentHowmuchtorebufferafterastreamhassufferedabufferunderrun.Valuesareexpressedasapercentagefrom1to99.(Default=95)

ReturnValue


Remarks

CallthisfunctionbeforeFSOUND_Stream_Open.Thisfunctionhasnoeffectoninternetstreamsthatarealreadyopen.___________________Supportedonthefollowingplatforms:Win32,Macintosh,Linux

SeeAlso

FSOUND_Stream_Close,FSOUND_Stream_Net_GetBufferProperties,FSOUND_Stream_Net_GetLastServerStatus,FSOUND_Stream_Net_GetStatus

,FSOUND_Stream_Net_SetMetadataCallback,FSOUND_Stream_Net_SetProxy,FSOUND_Stream_Net_SetTimeout,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_Net_SetMetadataCallback

Setametadatacallbackforaninternetstream.

signedcharF_APIFSOUND_Stream_Net_SetMetadataCallback(FSOUND_STREAM*stream,FSOUND_METADATACALLBACKcallback,void*userdata);

Parameters

stream Thestreamtosetthemetadatacallbackfor.callback Pointertothemetadatacallbackfunctiontoattachtothisstream.

userdata User-definedvaluethatwillbepassedtothesuppliedmetadatacallbackfunctionintheuserdataparameter.

ReturnValue


Remarks

Thesuppliedmetadatacallbackfunctionwillbecalledeachtimethespecifiedinternetstreamreceivesachunkofmetadata.Donotdoanytime-consumingprocessinginametadatacallbackfunctionornetworksubsystemperformancemaydegrade.Donotattempttomodifyorfreeanymemorypassedtoametadatacallbackfunction.___________________Supportedonthefollowingplatforms:Win32,Macintosh,Linux

SeeAlso

FSOUND_METADATACALLBACK,FSOUND_Stream_Close,

FSOUND_Stream_Net_GetBufferProperties,FSOUND_Stream_Net_GetLastServerStatus,FSOUND_Stream_Net_GetStatus,FSOUND_Stream_Net_SetBufferProperties,FSOUND_Stream_Net_SetProxy,FSOUND_Stream_Net_SetTimeout,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_Net_SetProxy

Setaproxyservertouseforallsubsequentinternetconnections.

signedcharF_APIFSOUND_Stream_Net_SetProxy(constchar*proxy);

Parameters

proxy

Thenameofaproxyserverinhost:portformate.g.www.fmod.org:8888(defaultstoport80ifnoportisspecified).Basicauthenticationissupported.Touseit,thisparametermustbeinuser:password@host:portformate.g.bob:[email protected]:8888SetthisparametertoNULLifnoproxyisrequired.

ReturnValue


Remarks


SeeAlso

FSOUND_Stream_Close,FSOUND_Stream_Net_GetBufferProperties,FSOUND_Stream_Net_GetLastServerStatus,FSOUND_Stream_Net_GetStatus,FSOUND_Stream_Net_SetBufferProperties,FSOUND_Stream_Net_SetMetadataCallback,FSOUND_Stream_Net_SetTimeout,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_Open

Opensanaudiofile/url/cdreadyforstreaming.Thisopensthefileinpreparationforplaybackinreal-time,withoutneedingtodecodethewholefileintomemoryfirst.

FSOUND_STREAM*F_APIFSOUND_Stream_Open(constchar*name_or_data,unsignedintmode,intoffset,intlength);

Parameters

name_or_data Nameofthefiletoopen,orpointertodataifFSOUND_LOADMEMORYisused.

mode

Simpledescriptionofhowtoplaythefile.ForallformatsexceptrawPCM,FSOUND_LOOP*,FSOUND_HW3D,FSOUND_HW2D,FSOUND_2D,FSOUND_LOADMEMORY,FSOUND_LOADRAW,FSOUND_MPEGACCURATE,FSOUND_NONBLOCKINGflagsaretheonlyonessupported.

offsetOptional.0bydefault.If>0,thisvalueisusedtospecifyanoffsetinafile,sofmodwillseekbeforeopening.lengthmustalsobespecifiedifthisvalueisused.

length


ReturnValue

Onsuccess,apointertoanopenedstreamisreturned.Onfailure,NULLisreturned.

Remarks

WAVsupportsupportswindowscodeccompressedWAVfiles.--------------FSOUND_MPEGACCURATEistobeusedcautiously.Toopenafilewiththismodeturnedon,ithastoscanthewholeMP3first.Thiscantakeseveralsecondsifthefileisbig,ortheharddisk/cpuisslow.Awaytospeedupthisprocesswouldbetoloadthecompressedmp3intomemoryfirst,andusetheFSOUND_LOADMEMORYflagwiththisfunction.--------------NOTE:Internetstreamlimitations-URLsmuststartwith"http://".-TheonlysupportedformatsforHTTPstreamsareMP3(musthave.mp3extension)andOggVorbis(musthave.oggextension).--------------FSBstreamingisnotsupportediftheformatfromFSBankis'Retainoriginalformat'.OnPCplatforms,onlyPCMandADPCMFSBfilesareallowed.--------------Note,onPlayStation2youcannotuseFSOUND_LOADMEMORY,youmayuseFSOUND_LOADMEMORYIOPthough.--------------WhenopeningwiththeFSOUND_NONBLOCKINGflag,thisfunctionalwayssucceedsatthepointofbeingcalled.Itwillalwaysreturnavalidchannelhandle,eventhoughthefilemightfailtoopen.TodetermineanyerrorinnonblockingmodeuseFSOUND_Stream_GetOpenState.--------------NOTE:CDDAStreaming(Win32only!)ToopenaCDforCDDAstreaming,specifythedriveletterofaCDdrivee.g.FSOUND_Stream_Open("d:",0,0,0);FSOUND_Stream_Openwillcreateastreamwithmultiplesubstreams,oneforeachCDtrack.UseFSOUND_Stream_SetSubStreamtoselectwhichCDtracktoplay.AnumberofoptionscanbepassedtoFSOUND_Stream_Openalongwiththedriveletter.Theyare:*?e.g.FSOUND_Stream_Open("d:*?",0,0,0);Thisoptionwillcauseatagfieldcalled"CD_DEVICE_INFO"tobeattachedtothestream.ThistagfieldcontainsinformationonthespecifiedCDdevice.*!e.g.FSOUND_Stream_Open("d:*!",0,0,0);Thisoptionwillcausethe

streamtobeopenedin"quickopen"mode.Whenastreamisopenedinthismode,callstoFSOUND_Stream_SetSubStreamwillreturnimmediatelymakingitquicktoselecteachsubstreaminturnandgetthelengthofeachCDtrack.Notethatastreaminquickopenmodecannotbeplayed!Usequickopenmodetogettracklengthsandthenre-openthestreamwithoutquickopenmodetoactuallyplayit.*je.g.FSOUND_Stream_Open("d:*j",0,0,0);ThisoptionturnsjittercorrectionOFF.*ae.g.FSOUND_Stream_Open("d:*a",0,0,0);ThisoptionwillforceFMODtouseASPItoaccessthespecifiedCDdriveasopposedtoNTSCSI.ItshouldgenerallyonlybeusedasalastresortifFMODisunabletoaccessdrivesthatareknowntobeworkingwithotherprograms.Optionscanbecombinedlikeso:FSOUND_Stream_Open("d:*?!j",0,0,0);IfanonblockingCDDAstreamfailstoopen,atagfieldcalled"CD_ERROR"willbeattachedtothestream.Thistagfieldcontainsatextualdescriptionofwhythestreamfailedtoopen.NOTE:FMODwillalwaystrytousenativeNTSCSIsupporttocommunicatewithCDdevicesbeforetryingtouseASPI,unlessthe"*a"optionisspecified,inwhichcaseFMODwillonlytrytouseASPI.Unlikeinpre-3.73versions,FMODcannowaccessallCDdriveswhenusingASPI.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_MODES,FSOUND_Stream_Close,FSOUND_Stream_GetLength,FSOUND_Stream_GetLengthMs,FSOUND_Stream_GetOpenState,FSOUND_Stream_Net_GetBufferProperties,FSOUND_Stream_Net_GetInfo,FSOUND_Stream_Net_GetLastServerStatus,FSOUND_Stream_Net_GetStatus,FSOUND_Stream_Net_SetBufferProperties,FSOUND_Stream_Net_SetMetadataCallback,FSOUND_Stream_Net_SetProxy,FSOUND_Stream_Net_SetTimeout,FSOUND_Stream_Open,FSOUND_Stream_OpenFromHandle,FSOUND_Stream_Play,FSOUND_Stream_PlayEx,FSOUND_Stream_SetBufferSize,FSOUND_Stream_SetSubStream,FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_Play

Startsapre-openedstreamplaying.

intF_APIFSOUND_Stream_Play(intchannel,FSOUND_STREAM*stream);

Parameters

channel

0+Thechannelindexinthechannelpool.ThismustnotexceedthemaximumnumberofchannelsallocatedwithFSOUND_InitFSOUND_FREEChoosesafreechanneltoplayin.Ifallchannelsareusedthenitselectsachannelwithasampleplayingthathasalowerprioritythanthesampletobeplayed.

stream Pointertothealreadyopenedstreamtobeplayed.

ReturnValue

Onsuccess,thechannelhandlethestreamisplayinginisreturned.Onfailure,-1isreturned.

Remarks

Whenastreamstartstoplay,itinheritsaspecialhighpriority(256).Itcannotberejectedbyothersoundeffectchannelsinthenormalfashionastheusercanneversetapriorityabove255normally.--------------IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillnotsucceeduntilthestreamisready.--------------FSBstreamingisnotsupportediftheformatfromFSBankis'Retainoriginalformat'.OnPCplatforms,onlyPCMandADPCMFSBfilesareallowed.

--------------FSOUND_STEREOPANisrecommendedforstereostreamsifyoucallFSOUND_SetPan.Thisputstheleftandrightchanneltofullvolume.Otherwiseanormalpanwillgivehalfvolumeforleftandright.SeeFSOUND_SetPanformoreinformationonthis.--------------Youcanusenormalchannelbasedcommands(suchasFSOUND_SetVolumeetc)onthereturnhandle,asitisachannelhandle.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetNumSubChannels,FSOUND_GetSubChannel,FSOUND_Init,FSOUND_SetPan,FSOUND_SetVolume,FSOUND_Stream_Close,FSOUND_Stream_Create,FSOUND_Stream_Net_GetBufferProperties,FSOUND_Stream_Net_GetLastServerStatus,FSOUND_Stream_Net_GetStatus,FSOUND_Stream_Net_SetBufferProperties,FSOUND_Stream_Net_SetMetadataCallback,FSOUND_Stream_Net_SetProxy,FSOUND_Stream_Net_SetTimeout,FSOUND_Stream_Open,FSOUND_Stream_PlayEx,FSOUND_Stream_SetEndCallback,FSOUND_Stream_SetLoopCount,FSOUND_Stream_SetSubStream,FSOUND_Stream_SetSubStreamSentence,FSOUND_Stream_SetSyncCallback,FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_PlayEx

ExtendedfeaturedversionofFSOUND_Stream_Play.Addedfunctionalityincludestheabilitytostartthestreampaused.Thisallowsattributesofastreamchanneltobesetfreelybeforethestreamactuallystartsplaying,untilFSOUND_SetPaused(FALSE)isused.AlsoaddedistheabilitytoassociatethestreamchanneltoaspecifiedDSPunit.Thisallowstheuserto'group'channelsintoseperateDSPunits,whichallowseffectstobeinsertedbetweenthese'groups',andallowvariousthingslikehavingonegroupaffectedbyreverb(wetmix)andanothergroupofchannelsunaffected(dry).ThisisusefultoseperatethingslikemusicfrombeingaffectedbyDSPeffects,whileothersoundeffectsare.

intF_APIFSOUND_Stream_PlayEx(intchannel,FSOUND_STREAM*stream,FSOUND_DSPUNIT*dspunit,signedcharpaused);

Parameters

channel

0+Theabsolutechannelnumberinthechannelpool.Remembersoftwarechannelscomefirst,followedbyhardwarechannels.Youcannotplayasoftwaresampleonahardwarechannelandviceversa.FSOUND_FREEChoosesafreechanneltoplayin.IfallchannelsareusedthenitselectsachannelwithasampleplayingthathasanEQUALorLOWERprioritythanthesampletobeplayed.

stream Pointertothealreadyopenedstreamtobeplayed.dspunit Pointertoadspunittoattachthechannelto.

paused Startthestreampausedornot.Pausingthestreamchannelallowsattributestobesetbeforeitisunpaused.

ReturnValue

Onsuccess,achannelhandlethestreamisplayinginisreturned.Onfailure,-1isreturned.

Remarks

Whenastreamstartstoplay,itinheritsaspecialhighpriority(256).Itcannotberejectedbyothersoundeffectchannelsinthenormalfashionastheusercanneversetapriorityabove255normally.--------FSOUND_STEREOPANisrecommendedforstereostreamsifyoucallFSOUND_SetPan.Thisputstheleftandrightchanneltofullvolume.Otherwiseanormalpanwillgivehalfvolumeforleftandright.SeeFSOUND_SetPanformoreinformationonthis.--------Youcanusenormalchannelbasedcommands(suchasFSOUND_SetVolumeetc)onthereturnhandle,asitisachannelhandle.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetNumSubChannels,FSOUND_GetSubChannel,FSOUND_SetPan,FSOUND_SetPaused,FSOUND_SetVolume,FSOUND_Stream_Close,FSOUND_Stream_Create,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_SetBufferSize

SetstheinternalfilebuffersizeforaudiostreamingofdatafortheNEXTstreamopenedwithFSOUND_Stream_Open.Largervalueswillconsumemorememory(seeremarks),whereassmallervaluesmaybeaffectedbylargedelaysindiskaccess,especiallyfromCDROM.

signedcharF_APIFSOUND_Stream_SetBufferSize(intms);

Parameters

msTimeinmillisecondsbetweenstreamupdates.FMODtriestoaccessthediskanddecompressdataeveryperiodspecified.Valueslessthan50resultinanerror.

ReturnValue


Remarks

Thedefaultsettingis400ms.Tocalculatememoryusageforastreambuffer,itisasimplematterofcalculatingsizebytes=streambuffersize*samplerate/1000*(bitdepth/8)*numchannels*2,wherenumchannelsis1formono,or2forstereofiles.Itismultipliedby2becauseFSOUNDstreambuffersaredoublebuffers.Notethisfunctiondoesnotaffectusercreatedstreams,asthebuffersizeisspecifiedinFSOUND_Stream_Create.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_SetDiskBusy,FSOUND_Stream_Create,FSOUND_Stream_Open


[APIfunction]

FSOUND_Stream_SetEndCallback

Setsacallbackfunctionforwhenastreamhasended.

signedcharF_APIFSOUND_Stream_SetEndCallback(FSOUND_STREAM*stream,FSOUND_STREAMCALLBACKcallback,void*userdata);

Parameters

stream Pointertothestreamtocallbackonwhenitisfinished.callback Functiontobecalledwhenstreamends.userdata datathatispassedintothecallbackattheendofthestream.

ReturnValue


Remarks

Onlycallsbackwhenastreamstops.(notwhenaloopingstreamreachesitsendpoint)NoteitusesaFSOUND_STREAMCALLBACKfunctioncallback.Thisisnormallyforuserstreamsbutforthesakeofre-usabilitythisprototypeisused.'buff'and'length'areNULLand0inthiscasewhenthecallbackoccurs.ThereturnvaluecanbeTRUEorFALSEitisignored.-----------IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillnotsucceeduntilthestreamisready.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_MODES,FSOUND_Stream_Play,FSOUND_STREAMCALLBACK


[APIfunction]

FSOUND_Stream_SetLoopCount

Setsthestreamtoloopthenumberoftimesspecifiedbytheuser.Ifnotcalleditloopsforever.

signedcharF_APIFSOUND_Stream_SetLoopCount(FSOUND_STREAM*stream,intcount);

Parameters

stream Pointertothestreamtosetloopcounton.

count Numberoftimestoloop.0wouldbesimilartohavingFSOUND_LOOP_OFFset.<0isinfinity.

ReturnValue


Remarks

Thisspecifieshowmanyloops,nothowmanytimestoplaythesoundback.Thereforewhenyouspecify0,youwillhearthesoundonce,ifyouspecify1,youwillhearthesoundtwice,andsoon.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_MODES,FSOUND_Stream_Play


[APIfunction]

FSOUND_Stream_SetLoopPoints

Setsthelooppointsforastream.

DLL_APIsignedcharF_APIFSOUND_Stream_SetLoopPoints(FSOUND_STREAM*stream,unsignedintloopstart,unsignedintloopend);

Parameters

stream Thestreamtosetthelooppointson.loopstart Thestartoftheloop,specifiedinPCMSAMPLES.loopend Theendoftheloop,specifiedinPCMSAMPLES.

ReturnValue


Remarks

Forstreams,settinglooppointsisreasonablyaccuratebutshouldnotbeassumedtobeperfectlysampleaccurateinallcases.Itdependsonthecompressionformatinsomecasesasseekpositionsneedtoberoundedtothenearestcompressionblockoffset.FSOUND_MPEGACCURATEwillneedtobeusedwithmp3filesthatuseVBRencodingformoreaccuracy.Youcannotcallthisfunctionwilethestreamisplaying,ithastobestopped.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube


[APIfunction]

FSOUND_Stream_SetMode

Setastreamsmode.

signedcharF_APIFSOUND_Stream_SetMode(FSOUND_STREAM*stream,unsignedintmode);

Parameters

stream Pointertothestreamtohavethemodeset.mode ThemodebitstosetfromFSOUND_MODES.

ReturnValue


Remarks

IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillnotsucceeduntilthestreamisready.Onlythefollowingmodesareaccepted,otherswillbefilteredout.FSOUND_LOOP_BIDI,FSOUND_LOOP_NORMAL,FSOUND_LOOP_OFF,FSOUND_2D.FSOUND_LOOP_BIDIistreatedasFSOUND_LOOP_NORMAL.FSOUND_2Disacceptedonlyifthesoundisnothardware.OnPlaystation2,XBoxandGameCube,FSOUND_HW2DandFSOUND_HW3Daresupported,soyoucanchangebetweenthematruntime.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_MODES,FSOUND_Stream_GetMode


[APIfunction]

FSOUND_Stream_SetPosition

Setsthecurrentstream'sFILEpositioninBYTES.

signedcharF_APIFSOUND_Stream_SetPosition(FSOUND_STREAM*stream,unsignedintposition);

Parameters

stream Pointertothestreamtohaveitspositionset.

position Offsetinbytesfromstartofactualsounddata(notincludinganyheader)

ReturnValue


Remarks

PositionfunctionsforstreamstalkinbytesandNOTsamples.Thereasonfornottakingtheheaderintoaccountispeopleusuallywanttoknowtheoffsettoseektorelativetothestartoftheirdata(ieastheyseeitinsoundforgeorwhatever),notfromoffset0whichisalmostmeaninglessifyoudontknowtheformat.--------------IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillnotsucceeduntilthestreamisready.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_GetLength,FSOUND_Stream_GetPosition,FSOUND_Stream_SetTime


[APIfunction]

FSOUND_Stream_SetSubStream

Seeksastreamtothesubstreaminsideamulti-streamFSBbankfile,specifiedbyitsindex.

signedcharF_APIFSOUND_Stream_SetSubStream(FSOUND_STREAM*stream,intindex);

Parameters

streamHandletothestreamtohaveitspositionset.index TheindexofthestreamwithintheFSBfile.

ReturnValue


Remarks

Astreamwillstopifthisfunctioniscalled,asitneedstoseekandflushthebuffer.IndiciesforthisfunctionaregeneratedasuserfriendlyconstantswhencompilingtheFSBbank,andareavailableintherelevantgeneratedheaderfile.--------------IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillALWAYSsucceed,butputsthestreambackintoanon-readystate.Youthenhavetopollaftercallingthistomakesurethestreamisready.YoucaneitherdothisbycallingFSOUND_Stream_Playrepeatedly/onceaframeuntilitissucceeds,orFSOUND_Stream_GetOpenState.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_GetNumSubStreams,FSOUND_Stream_GetOpenState,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_SetSubStreamSentence


[APIfunction]

FSOUND_Stream_SetSubStreamSentence

Thisfunctionallowstheusertodescribetheplaybackorderofalistofsubstreams.Thesubstreamswillbeplayedbackinorderseamlessly.

signedcharF_APIFSOUND_Stream_SetSubStreamSentence(FSOUND_STREAM*stream,constint*sentencelist,intnumitems);

Parameters

stream Pointertothestreamtohaveitspositionreturned.

sentencelist Thisisapointertoanarrayof32bitintegers,describingalistofsubstreamindiciestoplayback.numitems Thenumberofentriesinthesentencelist.

ReturnValue


Remarks

ThisfeatureonlyworkswithFSBfilesthathavemultiplestreamsstoredwithinit.Toremoveanysentence,simplycallthisfunctionwithNULLand0.FMODcopiesthelistfromthesuppliedpointer.Oncethepointerisused,thecallercandiscardtheoriginalarray.Thisfunctionwillfailifthestreamisplaying.Thestreammustbestoppedforittowork.------------IfthestreamisopenedwithFSOUND_NONBLOCKING,andthestreamisnotready(itisstillopening),thenthisfunctionwillreturnFALSE.Whenitisready,itwillreturnTRUE,butafterthiscallthestreamisputback

intoanon-readystate,becauseitisasynchronouslyseekingagain.Youthenhavetopollaftercallingthistomakesurethestreamisready.YoucaneitherdothisbycallingFSOUND_Stream_Playrepeatedly/onceaframeuntilitissucceeds,orFSOUND_Stream_GetOpenState.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_GetNumSubStreams,FSOUND_Stream_GetOpenState,FSOUND_Stream_Play,FSOUND_Stream_SetSubStream


[APIfunction]

FSOUND_Stream_SetSyncCallback

SetsacallbackfunctionforwhenastreampassesoveraWAVtag/marker.ThesearemarkersthatasoundeditingprogramsuchasSoundForgecandropintotheactualwavedata.FMODwilltriggercallbackswiththesemarkerswhenthestreamplays,andpassinthestringthroughthecallbackthatthemarkercontains.

signedcharF_APIFSOUND_Stream_SetSyncCallback(FSOUND_STREAM*stream,FSOUND_STREAMCALLBACKcallback,void*userdata);

Parameters

stream Pointertothestreamtocallbackwhenasyncpointisreached.callback Functiontocallwhensyncpointisreached.userdata userdatathatispassedintothecallback.

ReturnValue


Remarks

NoteitusesaFSOUND_STREAMCALLBACKfunctioncallback.Thisisnormallyforuserstreamsbutforthesakeofre-usabilitythisprototypeisused.'buff'isanullterminatedstringprovidedbythemarker.'len'istheoffsetinsamplesthatthemarkerwassetat.ThereturnvaluecanbeTRUEorFALSE,itisignored.-----------NoteyoucansaveaWAVoutusinganMP3wavcodec(andthenjustrename

theWAVtoMP3ifyoulike)togetsyncmarkersupportforcompressedMP3files.FMODwillpickuponthisandreadthemarkersout.--------------IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillnotsucceeduntilthestreamisready.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_MODES,FSOUND_Stream_AddSyncPoint,FSOUND_Stream_DeleteSyncPoint,FSOUND_Stream_GetNumSyncPoints,FSOUND_Stream_GetSyncPoint,FSOUND_Stream_GetSyncPointInfo,FSOUND_Stream_Play,FSOUND_STREAMCALLBACK


[APIfunction]

FSOUND_Stream_SetTime

Setsthecurrentstream'sFILEpositioninMILLISECONDS.

signedcharF_APIFSOUND_Stream_SetTime(FSOUND_STREAM*stream,intms);

Parameters

stream Pointertothestreamtohaveitspositionset.ms Timeinmillisecondstoseekto.

ReturnValue


Remarks

IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillnotsucceeduntilthestreamisready.FSOUND_MPEGACCURATEwillneedtobeusedwithmp3filesthatuseVBRencodingformoreaccuracy.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_GetLength,FSOUND_Stream_GetPosition,FSOUND_Stream_GetTime,FSOUND_Stream_SetPosition


[APIfunction]

FSOUND_Stream_Stop

Stopsastreamfromplaying.

signedcharF_APIFSOUND_Stream_Stop(FSOUND_STREAM*stream);

Parameters

stream Pointertoastreamtostop.

ReturnValue


Remarks

Thestreamisstillpreparedandsittinginmemoryreadytogo.UseFSOUND_Stream_Closeonthestreamtocompletelyremoveit.IfthestreamhasbeenopenedwithFSOUND_NONBLOCKING,thisfunctionwillnotsucceeduntilthestreamisready.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_Stream_Close,FSOUND_Stream_Create,FSOUND_Stream_Net_GetBufferProperties,FSOUND_Stream_Net_GetLastServerStatus,FSOUND_Stream_Net_GetStatus,FSOUND_Stream_Net_SetBufferProperties,FSOUND_Stream_Net_SetMetadataCallback,FSOUND_Stream_Net_SetProxy,FSOUND_Stream_Net_SetTimeout,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_PlayEx


[APIfunction]

FSOUND_CD_GetNumTracks

ReturnsthenumberoftracksonthecurrentlyinsertedCD.

intF_APIFSOUND_CD_GetNumTracks(chardrive);

Parameters

drive thedriveIDtouse.0isthedefaultCDdrive.UsingDorEinsinglequoteswouldbeD:orE:forexample.

ReturnValue

Onsuccess,thenumberofCDtracksonthecurrentlyinsertedisreturned.Onfailure,0isreturned.

Remarks

___________________Supportedonthefollowingplatforms:Win32,Linux

SeeAlso

FSOUND_CD_GetTrack


[APIfunction]

FSOUND_CD_GetPaused

GetsthepausestatusofthecurrentCDaudiotrack.

signedcharF_APIFSOUND_CD_GetPaused(chardrive);

Parameters


ReturnValue

Ifthetrackiscurrentlypaused,TRUEisreturned.Ifthetrackiscurrentlynotpaused,FALSEisreturned.

Remarks

___________________Supportedonthefollowingplatforms:Win32,Linux,Macintosh(OSXCFMOnly)


[APIfunction]

FSOUND_CD_GetTrack

ReturnsthecurrentlyplayingCDtracknumber.

intF_APIFSOUND_CD_GetTrack(chardrive);

Parameters


ReturnValue

Onsuccess,theCDtracknumbercurrentlyplayingisreturned.(startsfrom1)Onfailure,0isreturned.

Remarks


SeeAlso

FSOUND_CD_GetNumTracks


[APIfunction]

FSOUND_CD_GetTrackLength

GetsthetracklengthofaCD.

intF_APIFSOUND_CD_GetTrackLength(chardrive,inttrack);

Parameters

drive thedriveIDtouse.0isthedefaultCDdrive.UsingDorEinsinglequoteswouldbeD:orE:forexample.track TheCDtracknumbertoquerythelengthof.(startsfrom1)

ReturnValue

Onsuccess,thelengthofthecurrenttrackinmillisecondsisreturned.Onfailure,0isreturned.

Remarks


SeeAlso

FSOUND_CD_GetTrackTime,FSOUND_CD_SetTrackTime


[APIfunction]

FSOUND_CD_GetTrackTime

ReturnsthecurrenttracktimeplayingonaCD.

intF_APIFSOUND_CD_GetTrackTime(chardrive);

Parameters


ReturnValue

Onsuccess,thepositionofthecurrentplayingtrackinmillisecondsisreturned.Onfailure,0isreturned.

Remarks

ThisiseasilyoneoftheslowestfunctionsintheFMODAPI.Pleaseuseitsparingly.Itseemslikeitshouldnttakelong,butbecauseofwindowsMCIAPIitdoes,andnotjustalittlebitoftime,ittakesaLOT.ItseemstopolltheCDdriverandcausealargedelayuponcompletionofthecommand.Differentalgorithmswereusedtotryandemulatethisfunctionsuchassimplyusingatimer,butthiswasveryinaccurate,especiallywhenpausing/unpausingalot.___________________Supportedonthefollowingplatforms:Win32,Linux,Macintosh(OSXCFMOnly)

SeeAlso

FSOUND_CD_GetTrackLength,FSOUND_CD_SetTrackTime


[APIfunction]

FSOUND_CD_GetVolume

ReturnsthevolumeoftheplayingCDaudio.

intF_APIFSOUND_CD_GetVolume(chardrive);

Parameters


ReturnValue

Onsuccess,avaluebetween0and255isreturned,0beingthelowestvolumeand255beingthehighest.Onfailure,-1isreturned.

Remarks


SeeAlso

FSOUND_CD_Play,FSOUND_CD_SetVolume,FSOUND_Close


[APIfunction]

FSOUND_CD_OpenTray

Opens/ClosestheCDtray.

signedcharF_APIFSOUND_CD_OpenTray(chardrive,signedcharopen);

Parameters

drive ThedriveIDtouse.0isthedefaultCDdrive.UsingDorEinsinglequoteswouldbeD:orE:forexample.

open Ifopenissetto1,theCDtraywillbeopened.Ifopenissetto0,theCDtraywillbeclosed.

ReturnValue


Remarks

___________________Supportedonthefollowingplatforms:Win32,Linux


[APIfunction]

FSOUND_CD_Play

PlaysaCDAudiotrack.

signedcharF_APIFSOUND_CD_Play(chardrive,inttrack);

Parameters

drive thedriveIDtouse.0isthedefaultCDdrive.UsingDorEinsinglequoteswouldbeD:orE:forexample.track theCDtracknumbertoplay.Thefirsttrackstartsat1.

ReturnValue


Remarks

SeeFSOUND_CD_SetPlayModeforinformationonhowtocontrolplaybackofaCDtrack.FSOUND'sCDPlaybacksystem,isanonintrusive,nonpollingsystem.Thismaynotmeanmuchtoalotofpeople,butapollingplayer(takethewindowsdefaultCDplayer)willconsistantlypolltheCDdevicetoupdateitsstatus,whichcausesotherapplicationstojerk,orpauseconsistantly.Thiswouldbeinexcusableinagame,tohavethegamehaltorjerkeverysecondtofewsecondsorso.FSOUNDusestimingandpredictiontolooptracksandupdatethestatusoftheCD,andnevertouchestheCDdeviceduringplayback,forTRUE0puusage.___________________Supportedonthefollowingplatforms:Win32,Linux,Macintosh(OSXCFMonly)

SeeAlso

FSOUND_CD_GetVolume,FSOUND_CD_SetPlayMode,FSOUND_CD_SetVolume,FSOUND_CD_Stop


[APIfunction]

FSOUND_CD_SetPaused

SetsthepausestatusofthecurrentlyplayingCDaudiotrack.

signedcharF_APIFSOUND_CD_SetPaused(chardrive,signedcharpaused);

Parameters


paused TRUEtopausetrack,FALSEtounpausetrack.

ReturnValue


Remarks



[APIfunction]

FSOUND_CD_SetPlayMode

SetstheplaybackmodeoftheCD.

voidF_APIFSOUND_CD_SetPlayMode(chardrive,signedcharmode);

Parameters


mode SeeFSOUND_CDPLAYMODESforalistofvalidparameterstosendtothisfunction.

ReturnValue

void

Remarks


SeeAlso

FSOUND_CD_Play,FSOUND_CDPLAYMODES


[APIfunction]

FSOUND_CD_SetTrackTime

Performsaseekwithinatrackspecifiedbymilliseconds.

signedcharF_APIFSOUND_CD_SetTrackTime(chardrive,unsignedintms);

Parameters

drive ThedriveIDtouse.0isthedefaultCDdrive.UsingDorEinsinglequoteswouldbeD:orE:forexample.ms Timetoseekintothecurrenttrackinmilliseconds.

ReturnValue


Remarks

Thisfunctionwillstartthetrackifitisnotplaying.___________________Supportedonthefollowingplatforms:Win32,Linux,Macintosh(OSXCFMOnly)

SeeAlso

FSOUND_CD_GetTrackLength,FSOUND_CD_GetTrackTime


[APIfunction]

FSOUND_CD_SetVolume

SetsthevolumeoftheplayingCDaudio.

signedcharF_APIFSOUND_CD_SetVolume(chardrive,intvolume);

Parameters


volumeAnintegervaluefrom0-255.0beingthelowestvolume,255beingthehighest(full).

ReturnValue


Remarks


SeeAlso

FSOUND_CD_GetVolume,FSOUND_CD_Play,FSOUND_Close


[APIfunction]

FSOUND_CD_Stop

StopsthecurrentlyplayingCDaudiotrack.

signedcharF_APIFSOUND_CD_Stop(chardrive);

Parameters


ReturnValue


Remarks


SeeAlso

FSOUND_CD_Play


[APIfunction]

FSOUND_DSP_ClearMixBuffer

Clearsthemixbuffer,especiallyhandyifyouaredoingalargefileoperationwhichhaltsthesystem.Youmighttryandstopallthesounds,butifyoudoyourfileoperationstraightafterthis,itwillnothaveachancetoflushthemixbuffernormally,sothisfunctioniscalled.Itstopstheeffectofstutteringloopingsoundwhileyourfileoperationhappens.

voidF_APIFSOUND_DSP_ClearMixBuffer();

ReturnValue

Remarks

Thebestwaytodoitislikethis.TurnoffthesfxandmusicDSPunits,clearthemixbuffer,thenwhentheoperationthathaltsthemachineisdone,justre-enablethesfxandmusicDSPunits.Disablingtheseunitsstopsthetimertryingtoget1or2moremixesinduringthefileoperation,whichwillcausemorestuttering.ie.FSOUND_DSP_SetActive(FSOUND_DSP_GetSFXUnit(),FALSE);FSOUND_DSP_SetActive(FSOUND_DSP_GetMusicUnit(),FALSE);FSOUND_DSP_ClearMixBuffer();////machinghaltingoperationhere//FSOUND_DSP_SetActive(FSOUND_DSP_GetSFXUnit(),TRUE);FSOUND_DSP_SetActive(FSOUND_DSP_GetMusicUnit(),TRUE);___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_ClearMixBuffer,FSOUND_DSP_GetMusicUnit,FSOUND_DSP_GetSFXUnit,FSOUND_DSP_SetActive


[APIfunction]

FSOUND_DSP_Create

CreatesaDSPunit,andplacesitintheDSPchainpositionspecifiedbythepriorityparameter.ReadtheremarkssectioncarefullyforissuesregardingDSPunits.DSPunitsarefreedwithFSOUND_DSP_Free.

FSOUND_DSPUNIT*F_APIFSOUND_DSP_Create(FSOUND_DSPCALLBACKcallback,intpriority,void*userdata);

Parameters

callback

ThisisapointertoyourDSPUnitcallback,oftypeFSOUND_DSPCALLBACK.Theprototypeforacallbackisdeclaredinthefollowingfashion.Callbacksmustreturnapointertothebufferyouworkon,sothatthenextdspunitcanworkonit.Hereisthesimplestcase:void*callback(void*originalbuffer,void*newbuffer,intlength,void*userdata){//originalbuffer=fsoundsoriginalmixbuffer.//newbuffer=thebufferpassedfromthepreviousDSPunit.//length=lengthinsamplesatthismixtime.//param=userparameterpassedthroughinFSOUND_DSP_Create.////modifythebufferinsomefashionreturnnewbuffer;}SeethedefinitionofFSOUND_DSPCALLBACKformore.

priority

Orderintheprioritychain.Validnumbersare0to1000,0beinghighestpriority(first),with1000beinglowestpriority(last).NotethatFSOUNDssoundeffectsmixersandcopyroutinesareconsidered

partofthisDSPunitchainwhichyoucanplaywith.

param Userdefinedparameter,thisgetspassedintothecallbackwhenitiscalled.Itissafetoleavethisvalue0.

ReturnValue

Onsuccess,apointertoanewvalidDSPunitisreturned.Onfailure,NULLisreturned.

Remarks

AdspunitisNOTACTIVEbydefault.YouhavetoactivateitwithFSOUND_DSP_SetActive---------------------------------------------------------------------------------------Prioritiesanddefaultsystemunits.---------------------------------------------------------------------------------------Anoteonpriorities.FSOUNDprocessesDSPunitsinorderofpriority.A0priorityunitgetsprocessedfirst,a1priorityunitgetsprocessednext,andsoon.FSOUNDactuallyusestheseDSPunitstomixitssoundeffectsandmusic!Yes,youhaveaccesstothem(becareful!).Itispossibletototallyremove,replaceordeactivateallofFSOUND'ssystemunitssothatitdoesnothingatall!FSOUNDhaspreinstalleddefaultsystemunitsatthefollowingprioritylocations:FSOUND_DSP_DEFAULTPRIORITY_CLEARUNIT(priority0)-ClearUnit.Thisunitclearsoutthemixbufferforthenextunitstomixinto.Youcandisablethisunitandreplaceitwithsomethingotherthanaclearer,suchasascaler,whichfadesdownthemixbufferinsteadofclearingit,toproduceaveryroughechoeffect.FSOUND_DSP_DEFAULTPRIORITY_SFXUNIT(priority100)-SFXUnit.Thisunitmixessoundeffectchannelsintothemixbuffer,whichwaspreviouslyclearedwiththeClearUnit.FSOUND_DSP_DEFAULTPRIORITY_MUSICUNIT(priority200)-MusicUnit.Thisunitmixesallmusicchannelsintothemixbuffer,whichwaspreviouslymixedintowiththe

SFXUnit.FSOUND_DSP_DEFAULTPRIORITY_CLIPANDCOPYUNIT(priority1000)-ClipandCopyUnit.Thisunittakesthefinallymixedbuffer,andclipsittotheoutputstreamsize(ifitneedsto),andthensendsitofftothesounddevice.Itisdonelast.Ifthisisdisabledyouwillhearnosound.---------------------------------------------------------------------------------------BufferLengths.---------------------------------------------------------------------------------------The'length'valueoftheDSPcallbackisroughly20msworthofdata.UseFSOUND_DSP_GetBufferLengthtogettheexactcallbacklength.---------------------------------------------------------------------------------------BufferWidths---------------------------------------------------------------------------------------RememberthatFSOUNDusesdifferentbuffertypesdependingonwhattypeofmixeritis.Youwillhavetocompensateforthisbywritingdifferentroutinesdependingonthemixertype(iemmxornonmmx),justlikeFSOUNDdoes.Currentlytherearethe3typesofmixersandtheirbuffersizes.YoucangetthetypeofmixerbeingusedbycallingtheFSOUND_GetMixerfunction.Youmaywanttocheckonthisinsideyourcallback,orsetupafunctionpointersystem,whateveryouthinkissuitable(itcostsnothingtodoaFSOUND_GetMixereverytime).-FSOUND_MIXER_BLENDMODE:Thisbufferisastereo,signed32bitbuffer(8bytespersample).Thedataisinintegerformat.Datawrittentothisbufferisnotclippedandpassedtotheoutputstreamuntiltheveryendofthechain(theclipandcopyunit).Forthistypeofmixer,youdonthavetoworryaboutclippingbecuaseFSOUNDdoesthisforyou.-FSOUND_MIXER_QUALITY_FPU/FSOUND_MIXER_QUALITY_FPU_VOLUMERAMP:Thisbufferisalsoastereo,signed32bitbuffer(8bytespersample).Thisdataisinfloatingpointformat.Thesameclipandcopyrulesapplyhereasfortheabovemixer.-AnyMMXbasedmixer:Thisbufferisastereo,signed16bitbuffer(4bytes

persample).Whenwritingtothisbuffer,youmustmakesuretheresultdoesnotoverflowthissigned16bitrange.Ifyouadddataintotothisbuffer,makesureitisclippedtoasigned16bitrangebeforewritingitback.FSOUNDonlycopiesthisdatatotheoutputstream,itdoesnotclipit.---------------------------------------------------------------------------------------Speed---------------------------------------------------------------------------------------DSPUnitsareprocessedthenandthere,insidethemixingroutine.RemembertomakeyourprocessasFASTaspossible,ortheoutputdevice'splaycursorwillcatchuptoFSOUND'swritecursorwhileyourroutinetakesitstimetocomplete,andmakeitstarttobreakup.Sobasically,ifitisntfast,thenFSOUNDwillnotbeabletosendthedatatotheoutputdeviceintimeforthenextmixerupdate,andtheresultwillbecorruptedsound.FSOUND_DSP_MixBuffersisavailablenow,soifyouneedtomixsomerawdataintotheoutputbufferquickly,youcanuseFSOUND'sownoptimizedmixerdirectlytodoit!Finally,youcanseehowyourroutineaffectscpuusage,byusingFSOUND_GetCPUUsage.ThecpuusagereturnedbythisfunctionincludesanytimespentinDSPunitsaswell.(thisfunctiontimeseverything).Ifyouarereallybored,youcanseehowmuchFSOUND'ssystemunitstakecpu-wise,byturningthemonandoffandseeinghowtheyaffectperformance.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_DSP_Create,FSOUND_DSP_Free,FSOUND_DSP_GetBufferLength,FSOUND_DSP_GetBufferLengthTotal,FSOUND_DSP_MixBuffers,FSOUND_DSP_PRIORITIES,FSOUND_DSP_SetActive,FSOUND_DSP_SetPriority,FSOUND_DSPCALLBACK,FSOUND_GetCPUUsage,FSOUND_GetMixer,FSOUND_MIXERTYPES,FSOUND_PlaySoundEx,FSOUND_Stream_CreateDSP


[APIfunction]

FSOUND_DSP_Free

FreesandremovesaDSPunitfromtheDSPchain.

voidF_APIFSOUND_DSP_Free(FSOUND_DSPUNIT*unit);

Parameters

unit PointertoDSPunittobefreed.

ReturnValue

void

Remarks


SeeAlso

FSOUND_DSP_Create


[APIfunction]

FSOUND_DSP_SetActive

AllowstheusertotoggleaDSPunitonoroff.

voidF_APIFSOUND_DSP_SetActive(FSOUND_DSPUNIT*unit,signedcharactive);

Parameters

unit PointertoDSPunittohaveitsactiveflagchanged.

active FlagtosaywhetherDSPunitshouldberenderedactiveorinactive.validvaluesareTRUEorFALSE.

ReturnValue

void

Remarks

ItispossibletotoggleonandoffFSOUNDsinternalDSPunits,thoughnotrecommended.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_ClearMixBuffer,FSOUND_DSP_Create,FSOUND_DSP_GetActive,FSOUND_DSP_GetSpectrum


[APIfunction]

FSOUND_DSP_GetActive

ReturnsifaDSPunitisactiveornot.

signedcharF_APIFSOUND_DSP_GetActive(FSOUND_DSPUNIT*unit);

Parameters

unit PointertoDSPunittohaveitsactiveflagreturned.

ReturnValue


Remarks


SeeAlso

FSOUND_DSP_SetActive


[APIfunction]

FSOUND_DSP_GetBufferLength

ReturnsthebufferlenthpassedbytheDSPsystemtoDSPunitcallbacks,soyoucanallocatememoryetcusingthisdata.

intF_APIFSOUND_DSP_GetBufferLength();

ReturnValue

ThesizeoftheDSPunitbufferinSAMPLES(notbytes).

Remarks

Rememberthisissamplesnotbytes.Toconverttobytesyouwillhavetomultiplyby4formmxmixers,8forothermixers.(astereo16bitsample=4bytes,andastereo32bitsample(iefpu)=8bytes)___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_Create,FSOUND_DSP_GetBufferLengthTotal


[APIfunction]

FSOUND_DSP_GetBufferLengthTotal

Thisisthetotalsizeinsamples(notbytes)oftheFSOUNDmixbuffer.ThisisaffectedbyFSOUND_SetBufferSize.

intF_APIFSOUND_DSP_GetBufferLengthTotal();

ReturnValue

ThesizeoftheFSOUNDmixingbufferinSAMPLES(notbytes).

Remarks

Rememberthisissamplesnotbytes.Toconverttobytesyouwillhavetomultiplyby4formmxmixers,8forothermixers.(astereo16bitsample=4bytes,andastereo32bitsample(iefpu)=8bytes)___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_Create,FSOUND_DSP_GetBufferLength,FSOUND_SetBufferSize


[APIfunction]

FSOUND_DSP_SetPriority

ChangesaDSPUnit'sprioritypositionintheDSPchain.

voidF_APIFSOUND_DSP_SetPriority(FSOUND_DSPUNIT*unit,intpriority);

Parameters

unit PointertoDSPunittohaveitsprioritychanged.

priority Orderintheprioritychain.Validnumbersare0to1000,0beinghighestpriority(first),with1000beinglowestpriority(last).

ReturnValue

Remarks

DSPunitswiththesamepriorityasapreviousunitalreadyinthechainwillbeplacedAFTERalllikepriorityunits.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_Create,FSOUND_DSP_GetPriority


[APIfunction]

FSOUND_DSP_GetPriority

ReturnstheprioritystatusintheDSPchain,ofaspecifiedunit.

intF_APIFSOUND_DSP_GetPriority(FSOUND_DSPUNIT*unit);

Parameters

unit PointertoDSPunittogetpriorityvaluefrom.

ReturnValue

Onsuccess,thepriorityoftheunit,from0to1000.Onfailure,-1isreturned.

Remarks


SeeAlso

FSOUND_DSP_SetPriority


[APIfunction]

FSOUND_DSP_GetClearUnit

ReturnsapointertoFSOUND'ssystemDSPclearunit.

FSOUND_DSPUNIT*F_APIFSOUND_DSP_GetClearUnit();

ReturnValue

PointertotheDSPunit.

Remarks

TheFSOUNDclearDSPunitsimplysetsthemixbufferto0,silencingit.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_GetClipAndCopyUnit,FSOUND_DSP_GetFFTUnit,FSOUND_DSP_GetMusicUnit,FSOUND_DSP_GetSFXUnit


[APIfunction]

FSOUND_DSP_GetClipAndCopyUnit

ReturnsapointertoFSOUND'ssystemClipandCopyDSPunit.

FSOUND_DSPUNIT*F_APIFSOUND_DSP_GetClipAndCopyUnit();

ReturnValue


Remarks

TheFSOUNDClipAndCopyDSPunitclipsthe32bitbufferdowntofitthesoundcard's16bitstereooutput,andsendsitofftothehardware.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_GetClearUnit,FSOUND_DSP_GetFFTUnit,FSOUND_DSP_GetMusicUnit,FSOUND_DSP_GetSFXUnit


[APIfunction]

FSOUND_DSP_GetMusicUnit

ReturnsapointertoFSOUND'ssystemDSPMusicmixerunit.

FSOUND_DSPUNIT*F_APIFSOUND_DSP_GetMusicUnit();

ReturnValue


Remarks

TheFSOUNDMusicDSPexecutestheFMUSICengineandmixesthesoundsspawnedbythemusicplayer.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_ClearMixBuffer,FSOUND_DSP_GetClearUnit,FSOUND_DSP_GetClipAndCopyUnit,FSOUND_DSP_GetFFTUnit,FSOUND_DSP_GetSFXUnit


[APIfunction]

FSOUND_DSP_GetSFXUnit

ReturnsapointertoFSOUND'ssystemDSPSFXmixerunit.

FSOUND_DSPUNIT*F_APIFSOUND_DSP_GetSFXUnit();

ReturnValue


Remarks

TheFSOUNDSFXDSPunitmixessoundeffectstogetherspawnedbytheuser.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_ClearMixBuffer,FSOUND_DSP_GetClearUnit,FSOUND_DSP_GetClipAndCopyUnit,FSOUND_DSP_GetFFTUnit,FSOUND_DSP_GetMusicUnit


[APIfunction]

FSOUND_DSP_GetFFTUnit

ReturnsapointertoFSOUND'ssystemDSPFFTprocessingunit.

DLL_APIFSOUND_DSPUNIT*F_APIFSOUND_DSP_GetFFTUnit();

ReturnValue


Remarks

TheFSOUNDFFTDSPexecutestheFFTenginetoallowFSOUND_DSP_GetSpectrumtobeused.TheFFTunitisoffbydefault,duetothecpuexpenseincurredinrunning.TurnitontouseFSOUND_DSP_GetSpectrum.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_DSP_GetClearUnit,FSOUND_DSP_GetClipAndCopyUnit,FSOUND_DSP_GetMusicUnit,FSOUND_DSP_GetSFXUnit,FSOUND_DSP_GetSpectrum


[APIfunction]

FSOUND_DSP_GetSpectrum

Functiontoreturnapointertothecurrentspectrumbuffer.Thebuffercontains512floatingpointvaluesthatrepresenteachfrequencyband'samplitudeforthecurrentFMODSoundSystemmixingbuffer.Therangeoffrequenciescoveredbythespectrumis1tothenyquistfrequencyorhalfoftheoutputrate.Soiftheoutputrateis44100,thenfrequenciesprovidedareupto22050.(entry511)

F_FLOAT_API*F_APIFSOUND_DSP_GetSpectrum();

ReturnValue

Apointertoabuffercontaining512floats.

Remarks

Notethathardwaresounds,MIDI,filesdonotregisteronthespectrumgraphastheyarenotrunthroughFMODsDSPsystem.NotethattousethisyouhavetoturnontheFSOUNDFFTDSPunit.ThisisachievedbycallingFSOUND_DSP_GetFFTUnit,thenusingFSOUND_DSP_SetActivetoturniton.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_DSP_GetFFTUnit,FSOUND_DSP_SetActive


[APIfunction]

FSOUND_DSP_MixBuffers

Allowstheusertomixtheirowndatafromonebuffertoanother,usingFSOUNDsoptimizedmixerroutines.ThiswasmainlyprovidedforDSProutines,thoughitcanbeusedforanything.

signedcharF_APIFSOUND_DSP_MixBuffers(void*destbuffer,void*srcbuffer,intlen,intfreq,intvol,intpan,unsignedintmode);

Parameters

destbuffer Pointertoabuffertohavethedatamixedinto.srcbuffer Pointertothesourcebuffertobemixedin.len AmounttomixinSAMPLES.

freq

Speedtomixdatatooutputbuffer.Rememberifyoumixataratedifferentthantheoutputrate,thebufferlengthswillhavetobedifferenttocompensate.Ieiftheoutputrateis44100andyousupplyavalueof88200toFSOUND_DSP_MixBuffers,youwillonlyneedadestbufferthatishalfthesizeofsrcbuffer.Ifyousupplyavalueof22050thenyouwillneedadestbufferthatistwiceasbigassrcbuffer.Iftheyareboththesamesizethenitwillonlymixhalfofthedata.

vol volumescalarvalueofmix.Validvaluesare0(silence)to255(fullvolume).SeeFSOUND_SetVolumeformoreinformation.

pan

panvaluefordatabeingmixed.Validvaluesare0(fullleft),128(middle),255(fullright)andFSOUND_STEREOPAN.SeeFSOUND_SetPanfor

moreinformation.

mode

Bitsettingstodescribethesourcebuffer.ValidvaluesarefoundinFSOUND_MODES,butonly8/16bitandstereo/monoflagsareinterpreted,otherflagsareignored.

ReturnValue


Remarks

'destbuffer'shouldalwaystheformatofthemixingoutputbuffer,asitwillusethemixercurrentlyrunningtodothemixing.ForMMXitis16bitstereo,soitis4bytesperoutputsample(wordleft,wordright)ForStandardBlendmodeitis32bitstereo,soitis8bytesperoutputsample(leftdword,rightdword)ForFPUmixeritis32bitfloatstereo,soitis8bytesperoutputsample(leftfloat,rightfloat)FSOUND_GetMixercanbeusedtodeterminewhichmixerisbeingused.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,GameCube

SeeAlso

FSOUND_DSP_Create,FSOUND_DSP_MixBuffers,FSOUND_GetMixer,FSOUND_MODES,FSOUND_SetFrequency,FSOUND_SetPan,FSOUND_SetVolume


[APIfunction]

FSOUND_FX_Disable

DisableseffectprocessingforALLeffectsonthespecifiedchannel.

signedcharF_APIFSOUND_FX_Disable(intchannel);

Parameters

channel Channelnumber/handletodisableallfxfor.

ReturnValue


Remarks

FSOUND_ALLissupported.PassingthiswilldisablefxonALLchannelsavailable.Thiscommandcanonlybeissuedwhilethechannelispausedorstopped.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Enable,FSOUND_FX_SetChorus,FSOUND_FX_SetCompressor,FSOUND_FX_SetDistortion,FSOUND_FX_SetEcho,FSOUND_FX_SetFlanger,FSOUND_FX_SetGargle,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetParamEQ,FSOUND_FX_SetWavesReverb


[APIfunction]

FSOUND_FX_Enable

Enableseffectprocessingforthespecifiedchannel.Thiscommandcontinuestoaddeffectstoachannel(upto16)untilFSOUND_FX_Disableiscalled.

intF_APIFSOUND_FX_Enable(intchannel,unsignedintfxtype);

Parameters

channel Channelnumber/handletoenablefxfor.fx Asinglefxenumvaluetoenablecertaineffects.

ReturnValue

Onsuccess,anFXidisreturned.Onfailure,-1isreturned.

Remarks

FSOUND_ALLissupported.PassingthiswillenablefxonALLchannelsavailable.Thiscommandcanonlybeissuedwhilethechannelispaused.Ifaneffectisnotenabled,thenitwillnotbeaffectedbyitscorrespondingFSOUND_FX_Setfunctions.ThisfunctionmustbeplayedafterapausedPlaySoundEx(ieFSOUND_PlaySoundEx(FSOUND_FREE,sound,NULL,TRUE)),andbeforetheFSOUND_SetPaused(FALSE)sothatthehardwarecangettheresourcebeforeitstartsplaying.Atotalof16FXperchannelisallowed,anymorewillresultinanerror.FXareresetto0afterasoundisstoppedorplayed.(butasabove,beforetheunpausingofaplay-pausedsound).Warning:Thisfunctionisexpensivetocallasithastosetupfxbuffersetc.Itisbesttocallitonce,reservethechannelthenreusethechannelindexwhen

callingplaysoundwithoutcallingitagain.Note:UnderDirectX8,channelswithFXenabledsoundscannothavetheirfrequencychanged.DirectX9andabovedonothavethislimitation.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_MODES,FSOUND_FX_SetChorus,FSOUND_FX_SetCompressor,FSOUND_FX_SetDistortion,FSOUND_FX_SetEcho,FSOUND_FX_SetFlanger,FSOUND_FX_SetGargle,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetParamEQ,FSOUND_FX_SetWavesReverb,FSOUND_PlaySound,FSOUND_PlaySoundEx,FSOUND_SetPaused


[APIfunction]

FSOUND_FX_SetChorus

Setstheparametersforthechoruseffectonaparticularchannel

signedcharF_APIFSOUND_FX_SetChorus(intfxid,floatWetDryMix,floatDepth,floatFeedback,floatFrequency,intWaveform,floatDelay,intPhase);

Parameters

fxid fxhandlegeneratedbyFSOUND_FX_Enable,tosetchorusparametersfor.

WetDryMix Ratioofwet(processed)signaltodry(unprocessed)signal.Mustbeintherangefrom0through100(allwet).

DepthPercentagebywhichthedelaytimeismodulatedbythelow-frequencyoscillator,inhundredthsofapercentagepoint.Mustbeintherangefrom0through100.Thedefaultvalueis25.

Feedback Percentageofoutputsignaltofeedbackintotheeffectsinput,intherangefrom-99to99.Thedefaultvalueis0.

Frequency FrequencyoftheLFO,intherangefrom0to10.Thedefaultvalueis0.

Waveform

WaveformoftheLFO.Definedvaluesare0triangle.1sine.Bydefault,thewaveformisasine.

Delay Numberofmillisecondstheinputisdelayedbeforeitisplayedback,intherangefrom0to20.Thedefaultvalueis0ms.PhasedifferentialbetweenleftandrightLFOs,intherangefrom0through4.Possiblevaluesaredefinedasfollows:

Phase0-180degrees1-90degrees20degrees390degrees4180degrees

ReturnValue


Remarks

MakesureyouhaveenabledthiseffectwithFSOUND_FX_CHORUSbeforeusingthisfunction.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_Enable,FSOUND_FX_MODES,FSOUND_FX_SetCompressor,FSOUND_FX_SetDistortion,FSOUND_FX_SetEcho,FSOUND_FX_SetFlanger,FSOUND_FX_SetGargle,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetParamEQ,FSOUND_FX_SetWavesReverb


[APIfunction]

FSOUND_FX_SetCompressor

Setstheparametersforthecompressoreffectonaparticularchannel

signedcharF_APIFSOUND_FX_SetCompressor(intfxid,floatGain,floatAttack,floatRelease,floatThreshold,floatRatio,floatPredelay);

Parameters

fxid fxhandlegeneratedbyFSOUND_FX_Enable,tosetcompressorparametersfor.

Gain Outputgainofsignalaftercompression,intherangefrom-60to60.Thedefaultvalueis0dB.

Attack Timebeforecompressionreachesitsfullvalue,intherangefrom0.01to500.Thedefaultvalueis0.01ms.

Release SpeedatwhichcompressionisstoppedafterinputdropsbelowfThreshold,intherangefrom50to3000.Thedefaultvalueis50ms.

Threshold Pointatwhichcompressionbegins,indecibels,intherangefrom-60to0.Thedefaultvalueis-10dB.

Ratio Compressionratio,intherangefrom1to100.Thedefaultvalueis10,whichmeans10:1compression.

Predelay TimeafterlThresholdisreachedbeforeattackphaseisstarted,inmilliseconds,intherangefrom0to4.Thedefaultvalueis0ms.

ReturnValue


Remarks

MakesureyouhaveenabledthiseffectwithFSOUND_FX_COMPRESSORbeforeusingthisfunction.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_Enable,FSOUND_FX_MODES,FSOUND_FX_SetChorus,FSOUND_FX_SetDistortion,FSOUND_FX_SetEcho,FSOUND_FX_SetFlanger,FSOUND_FX_SetGargle,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetParamEQ,FSOUND_FX_SetWavesReverb


[APIfunction]

FSOUND_FX_SetDistortion

Setstheparametersforthedistortioneffectonaparticularchannel

signedcharF_APIFSOUND_FX_SetDistortion(intfxid,floatGain,floatEdge,floatPostEQCenterFrequency,floatPostEQBandwidth,floatPreLowpassCutoff);

Parameters

fxid fxhandlegeneratedbyFSOUND_FX_Enable,tosetdistortionparametersfor.

Gain Amountofsignalchangeafterdistortion,intherangefrom-60through0.Thedefaultvalueis0dB.

EdgePercentageofdistortionintensity,intherangeintherangefrom0through100.Thedefaultvalueis50percent.

PostEQCenterFrequencyCenterfrequencyofharmoniccontentaddition,intherangefrom100through8000.Thedefaultvalueis4000Hz.

PostEQBandwidthWidthoffrequencybandthatdeterminesrangeofharmoniccontentaddition,intherangefrom100through8000.Thedefaultvalueis4000Hz.

PreLowpassCutoffFiltercutoffforhigh-frequencyharmonicsattenuation,intherangefrom100through8000.Thedefaultvalueis4000Hz.

ReturnValue


Remarks

MakesureyouhaveenabledthiseffectwithFSOUND_FX_DISTORTIONbeforeusingthisfunction.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_Enable,FSOUND_FX_MODES,FSOUND_FX_SetChorus,FSOUND_FX_SetCompressor,FSOUND_FX_SetEcho,FSOUND_FX_SetFlanger,FSOUND_FX_SetGargle,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetParamEQ,FSOUND_FX_SetWavesReverb


[APIfunction]

FSOUND_FX_SetEcho

Setstheparametersfortheechoeffectonaparticularchannel

signedcharF_APIFSOUND_FX_SetEcho(intfxid,floatWetDryMix,floatFeedback,floatLeftDelay,floatRightDelay,intPanDelay);

Parameters

fxid fxhandlegeneratedbyFSOUND_FX_Enable,tosetechoparametersfor.


Feedback Percentageofoutputfedbackintoinput,intherangefrom0through100.Thedefaultvalueis0.

LeftDelay Delayforleftchannel,inmilliseconds,intherangefrom1through2000.Thedefaultvalueis333ms.

RightDelay Delayforrightchannel,inmilliseconds,intherangefrom1through2000.Thedefaultvalueis333ms.

PanDelayValuethatspecifieswhethertoswapleftandrightdelayswitheachsuccessiveecho.ThedefaultvalueisFALSE,meaningnoswap.PossiblevaluesaredefinedasTRUEorFALSE.

ReturnValue


Remarks

MakesureyouhaveenabledthiseffectwithFSOUND_FX_EnableandFSOUND_FX_ECHObeforeusingthisfunction.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_Enable,FSOUND_FX_MODES,FSOUND_FX_SetChorus,FSOUND_FX_SetCompressor,FSOUND_FX_SetDistortion,FSOUND_FX_SetFlanger,FSOUND_FX_SetGargle,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetParamEQ,FSOUND_FX_SetWavesReverb


[APIfunction]

FSOUND_FX_SetFlanger

Setstheparametersfortheflangereffectonaparticularchannel

signedcharF_APIFSOUND_FX_SetFlanger(intfxid,floatWetDryMix,floatDepth,floatFeedback,floatFrequency,intWaveform,floatDelay,intPhase);

Parameters

fxid fxhandlegeneratedbyFSOUND_FX_Enable,tosetflangerparametersfor.


DepthPercentagebywhichthedelaytimeismodulatedbythelow-frequencyoscillator(LFO),inhundredthsofapercentagepoint.Mustbeintherangefrom0through100.Thedefaultvalueis25.

Feedback Percentageofoutputsignaltofeedbackintotheeffectsinput,intherangefrom-99to99.Thedefaultvalueis0.

Frequency FrequencyoftheLFO,intherangefrom0to10.Thedefaultvalueis0.

Waveform

WaveformoftheLFO.Bydefault,thewaveformisasine.Possiblevaluesaredefinedasfollows:0-Triangle.1-Sine.

Delay Numberofmillisecondstheinputisdelayedbeforeitisplayedback,intherangefrom0to4.Thedefaultvalueis0ms.PhasedifferentialbetweenleftandrightLFOs,intherangefrom0through4.Possiblevaluesaredefinedasfollows:

Phase0-180degrees1-90degrees20degrees390degrees4180degrees

ReturnValue


Remarks

MakesureyouhaveenabledthiseffectwithFSOUND_FX_EnableandFSOUND_FX_FLANGERbeforeusingthisfunction.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_Enable,FSOUND_FX_MODES,FSOUND_FX_SetChorus,FSOUND_FX_SetCompressor,FSOUND_FX_SetDistortion,FSOUND_FX_SetEcho,FSOUND_FX_SetGargle,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetParamEQ,FSOUND_FX_SetWavesReverb


[APIfunction]

FSOUND_FX_SetGargle

Setstheparametersforthegargleeffectonaparticularchannel

signedcharF_APIFSOUND_FX_SetGargle(intfxid,intRateHz,intWaveShape);

Parameters

fxid fxhandlegeneratedbyFSOUND_FX_Enable,tosetgargleparametersfor.

RateHz Rateofmodulation,inHertz.Mustbeintherangefrom1through1000.

WaveShapeShapeofthemodulationwave.Thefollowingvaluesaredefined.0-Triangularwave.1-Squarewave.

ReturnValue


Remarks

MakesureyouhaveenabledthiseffectwithFSOUND_FX_EnableandFSOUND_FX_GARGLEbeforeusingthisfunction.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_Enable,FSOUND_FX_MODES,FSOUND_FX_SetChorus,FSOUND_FX_SetCompressor,

FSOUND_FX_SetDistortion,FSOUND_FX_SetEcho,FSOUND_FX_SetFlanger,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetParamEQ,FSOUND_FX_SetWavesReverb


[APIfunction]

FSOUND_FX_SetI3DL2Reverb

SetstheparametersfortheI3DL2Reverbeffectonaparticularchannel

signedcharF_APIFSOUND_FX_SetI3DL2Reverb(intfxid,intRoom,intRoomHF,floatRoomRolloffFactor,floatDecayTime,floatDecayHFRatio,intReflections,floatReflectionsDelay,intReverb,floatReverbDelay,floatDiffusion,floatDensity,floatHFReference);

Parameters

fxid fxhandlegeneratedbyFSOUND_FX_Enable,tosetI3DL2Reverbparametersfor.

Room Attenuationoftheroomeffect,inmillibels(mB),intherangefrom-10000to0.Thedefaultvalueis-1000mB.

RoomHF Attenuationoftheroomhigh-frequencyeffect,inmB,intherangefrom-10000to0.Thedefaultvalueis0mB.

RoomRolloffFactorRollofffactorforthereflectedsignals,intherangefrom0to10.Thedefaultvalueis0.0.Therollofffactorforthedirectpathiscontrolledbythelistener.

DecayTime Decaytime,inseconds,intherangefrom.1to20.Thedefaultvalueis1.49seconds.

DecayHFRatioRatioofthedecaytimeathighfrequenciestothedecaytimeatlowfrequencies,intherangefrom0.1to2.Thedefaultvalueis0.83.

ReflectionsAttenuationofearlyreflectionsrelativetolRoom,inmB,intherangefrom-10000to1000.Thedefaultvalueis-2602mB.

ReflectionsDelayDelaytimeofthefirstreflectionrelativetothedirectpath,inseconds,intherangefrom0to0.3.Thedefaultvalueis0.007seconds.

ReverbAttenuationoflatereverberationrelativetolRoom,inmB,intherangefrom-10000to2000.Thedefaultvalueis200mB.

ReverbDelay

Timelimitbetweentheearlyreflectionsandthelatereverberationrelativetothetimeofthefirstreflection,inseconds,intherangefrom0to0.1.Thedefaultvalueis0.011seconds.

Diffusion Echodensityinthelatereverberationdecay,inpercent,intherangefrom0to100.Thedefaultvalueis100.0percent.

Density Modaldensityinthelatereverberationdecay,inpercent,intherangefrom0to100.Thedefaultvalueis100.0percent.

HFReference Referencehighfrequency,inhertz,intherangefrom20to20000.Thedefaultvalueis5000.0Hz.

ReturnValue


Remarks

MakesureyouhaveenabledthiseffectwithFSOUND_FX_EnableandFSOUND_FX_I3DL2REVERBbeforeusingthisfunction.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_Enable,FSOUND_FX_MODES,FSOUND_FX_SetChorus,FSOUND_FX_SetCompressor,FSOUND_FX_SetDistortion,FSOUND_FX_SetEcho,

FSOUND_FX_SetFlanger,FSOUND_FX_SetGargle,FSOUND_FX_SetParamEQ,FSOUND_FX_SetWavesReverb


[APIfunction]

FSOUND_FX_SetParamEQ

SetstheparametersfortheParamEQeffectonaparticularchannel

signedcharF_APIFSOUND_FX_SetParamEQ(intfxid,floatCenter,floatBandwidth,floatGain);

Parameters

fxid fxhandlegeneratedbyFSOUND_FX_Enable,tosetParamEQparametersfor.

CenterCenterfrequency,inhertz,intherangefrom80to16000.Thisvaluecannotexceedone-thirdofthefrequencyofthebuffer.Defaultis8000.

Bandwidth Bandwidth,insemitones,intherangefrom1to36.Defaultis12.Gain Gain,intherangefrom-15to15.Defaultis0.

ReturnValue


Remarks

MakesureyouhaveenabledthiseffectwithFSOUND_FX_EnableandFSOUND_FX_PARAMEQbeforeusingthisfunction.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_Enable,FSOUND_FX_MODES,

FSOUND_FX_SetChorus,FSOUND_FX_SetCompressor,FSOUND_FX_SetDistortion,FSOUND_FX_SetEcho,FSOUND_FX_SetFlanger,FSOUND_FX_SetGargle,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetWavesReverb


[APIfunction]

FSOUND_FX_SetWavesReverb

SetstheparametersfortheWavesReverbeffectonaparticularchannel

signedcharF_APIFSOUND_FX_SetWavesReverb(intfxid,floatInGain,floatReverbMix,floatReverbTime,floatHighFreqRTRatio);

Parameters

fxid fxhandlegeneratedbyFSOUND_FX_Enable,number/handletosetWavesReverbparametersfor.

InGain Inputgainofsignal,indecibels(dB),intherangefrom-96through0.Thedefaultvalueis0dB.

ReverbMix Reverbmix,indB,intherangefrom-96through0.Thedefaultvalueis0dB.

ReverbTime Reverbtime,inmilliseconds,intherangefrom.001through3000.Thedefaultvalueis1000.

HighFreqRTRatio Intherangefrom.001through.999.Thedefaultvalueis0.001.

ReturnValue


Remarks

MakesureyouhaveenabledthiseffectwithFSOUND_FX_WAVES_REVERBbeforeusingthisfunction.___________________Supportedonthefollowingplatforms:Win32

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_Enable,FSOUND_FX_MODES,FSOUND_FX_SetChorus,FSOUND_FX_SetCompressor,FSOUND_FX_SetDistortion,FSOUND_FX_SetEcho,FSOUND_FX_SetFlanger,FSOUND_FX_SetGargle,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetParamEQ


[APIfunction]

FSOUND_Record_GetDriver

Returnsthecurrentlyselectedrecordingdrivernumber.DriversareenumeratedwhenselectingadriverwithFSOUND_Record_SetDriverorotherdriverrelatedfunctionssuchasFSOUND_Record_GetNumDriversorFSOUND_Record_GetDriverName

intF_APIFSOUND_Record_GetDriver();

ReturnValue

Currentlyselecteddriverid.

Remarks


SeeAlso

FSOUND_Record_GetDriver,FSOUND_Record_GetDriverName,FSOUND_Record_GetNumDrivers,FSOUND_Record_SetDriver


[APIfunction]

FSOUND_Record_GetDriverName

Returnsthenameoftheselectedrecordingdriver.DriversareenumeratedwhenselectingadriverwithFSOUND_Record_SetDriverorotherdriverrelatedfunctionssuchasFSOUND_Record_GetNumDriversorFSOUND_Record_GetDriver

constchar*F_APIFSOUND_Record_GetDriverName(intid);

Parameters

id EnumerateddriverID.ThismustbeinavalidrangedelimitedbyFSOUND_Record_GetNumDrivers,

ReturnValue

Onsuccess,apointertoaNULLterminatedstringcontainingthenameofthespecifieddeviceisreturned.ThenumberofdriversenumeratedcanbefoundwithFSOUND_Record_GetNumDrivers.Onfailure,NULLisreturned.

Remarks


SeeAlso

FSOUND_Record_GetDriver,FSOUND_Record_GetNumDrivers,FSOUND_Record_SetDriver


[APIfunction]

FSOUND_Record_GetNumDrivers

Returnsthenumberofsoundcardsordevicesenumeratedforthecurrentinputtype.(DirectSound,WaveOutetc.)

intF_APIFSOUND_Record_GetNumDrivers();

ReturnValue

Totalnumberofenumeratedsounddevices.

Remarks


SeeAlso

FSOUND_Record_GetDriver,FSOUND_Record_GetDriverName,FSOUND_Record_SetDriver


[APIfunction]

FSOUND_Record_GetPosition

Getsthepositioninthesamplebufferthathasbeenrecordedto.

intF_APIFSOUND_Record_GetPosition();

ReturnValue

Onsuccess,theoffsetinSAMPLES,fortherecordbufferthattheinputdevicehasjustwrittenuptoisreturned.Onfailure(recordingdevicehasntbeenstarted),-1isreturned.

Remarks

Note.Thisisnotthe'recordingcursor',butratherthelatestpointthattheinputhasbeencopiedtoyoursample___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh

SeeAlso

FSOUND_Record_StartSample


[APIfunction]

FSOUND_Record_SetDriver

Selectsasoundcardrecordingdriver.Itisusedwhenanoutputmodehasenumeratedmorethanonerecordingdeviceandyouneedtoselectbetweenthem.

signedcharF_APIFSOUND_Record_SetDriver(intdriver);

Parameters

driverno

Recordingdrivernumbertoselect.<=0willselecttheDEFAULTrecordingsounddriver.>0SelectsothervaliddriversthatcanbelistedwithFSOUND_Record_GetDriverName.

ReturnValue


Remarks


SeeAlso

FSOUND_Record_GetDriver,FSOUND_Record_GetDriverName,FSOUND_Record_GetNumDrivers


[APIfunction]


Startsrecordingintoapredefinedsampleusingthesample'sdefaultplaybackrateastherecordingrate.

signedcharF_APIFSOUND_Record_StartSample(FSOUND_SAMPLE*sptr,signedcharloop);

Parameters

sptr Thesampletorecordinto.

loop

TRUEorFALSEflagwhethertherecordershouldkeeprecordingonceithashittheend,andstartfromthestartagain,thereforecreatingacontinuousrecordingsessionintothatsamplebuffer.Loopingtherecordingbufferisgoodforrealtimeprocessingofrecordedinformation,asyoucanrecordandplaybackthesampleatthesametime.

ReturnValue


Remarks

Ifyouwanttoplaybackthesampleatthesametimeisisrecording,youwillhavetoplaythesoundandtryandkeepitjustbehindtherecordingcursor.UnderFSOUND_OUTPUT_OSSmode,itissingleduplex,soplaybackwillstopwhenrecordingisinprogress!TryFSOUND_OUTPUT_ALSAforfullduplexastheyhavebetterdriversinthisrespect.-------------Therecording/playbackratesareslightlyinnacurateandarenotidentical(ie44100.0forplayback,44100.1forrecording),soonecouldpossiblybefasteror

slowerthantheother.Inthiscasetherecordingandtheplaybackcursorcouldoverlap,andtheoutputwillsoundcorrupted.Tocounterthisyoumightadjusttheplaybackfrequencyofthechannelyouareplayingtherecordsampleonwhileitplays,usingFSOUND_GetCurrentPositionandFSOUND_Record_GetPositionascalibrationpoints.Intherecordingsamplethereisanexampleoftryingtoplaybacksoundasitrecords,andthemechanismtotryandkeepthe2cursorsasafedistancefromeachotherisemployed.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh

SeeAlso

FSOUND_GetCurrentPosition,FSOUND_Record_GetPosition,FSOUND_Record_Stop


[APIfunction]

FSOUND_Record_Stop

Haltsrecordingtothespecifiedsample.

signedcharF_APIFSOUND_Record_Stop();

ReturnValue


Remarks


SeeAlso



[APIfunction]

FSOUND_Reverb_SetProperties

Setshardwarereverbparametersforadvancedtuning.Thebestwaytomodifytheseistoseteverythingtousepre-definedpresetsgivenintheheader,andthenstartmodifyingvalues.

signedcharF_APIFSOUND_Reverb_SetProperties(constFSOUND_REVERB_PROPERTIES*props);

Parameters

prop ApointertoaFSOUND_REVERB_PROPERTIESstruct.Thedefinitionforthisstructureisgiveninthelinkbelow.

ReturnValue


Remarks

YoumustbeusingFSOUND_OUTPUT_DSOUNDastheoutputmodeforthistowork.Indsound,thereverbwillonlyworkifyouhaveanEAXcompatiblesoundcardsuchastheSBLive,andyoursample/streamwascreatedwiththeFSOUND_HW3Dflag.ForGameCube,useFSOUND_AUXFX_xxxapi.___________________Supportedonthefollowingplatforms:Win32,XBox,PlayStation2

SeeAlso

FSOUND_Reverb_GetChannelProperties,FSOUND_Reverb_GetProperties,FSOUND_REVERB_PROPERTIES,FSOUND_Reverb_SetChannelProperties


[APIfunction]

FSOUND_Reverb_GetProperties

Returnsthecurrenthardwarereverbenvironment.

signedcharF_APIFSOUND_Reverb_GetProperties(FSOUND_REVERB_PROPERTIES*props);

Parameters

props PointertoaFSOUND_REVERB_PROPERTIESstructuredefinition.Thedefiniotionforthisstructureisgiveninthelinkbelow.

ReturnValue


Remarks

ThesevaluesareonlyrelevantifyouareinDSOUNDmodewithanEAX3compatiblesoundcard,orXBOXandPS2.___________________Supportedonthefollowingplatforms:Win32,XBox,PlayStation2

SeeAlso

FSOUND_Reverb_GetChannelProperties,FSOUND_REVERB_PROPERTIES,FSOUND_Reverb_SetChannelProperties,FSOUND_Reverb_SetProperties


[APIfunction]

FSOUND_Reverb_SetChannelProperties

Setsthechannelspecificreverbpropertiesforhardware,includingwet/drymix(roomsize),andthingslikeobstructionandocclusionproperties.

signedcharF_APIFSOUND_Reverb_SetChannelProperties(intchannel,constFSOUND_REVERB_CHANNELPROPERTIES*prop);

Parameters

channel Thechanneltohaveitsreverbpropertieschanged.FSOUND_ALLcanalsobeused(seeremarks)

prop PointertoaFSOUND_REVERB_CHANNELPROPERTIESstructuredefinition.Thedefinitionforthisstructureisgiveninthelinkbelow.

ReturnValue


Remarks

FSOUND_ALLissupportedhere.PassingthiswillsetALLchannelstospecifiedreverbproperties.IfFSOUND_ALLisusedthelastchannelsuccessflagwillbereturned.Thisreturnvaluenotusefulinmostcircumstances.-----------------UnderWin32,youmustbeusingFSOUND_OUTPUT_DSOUNDastheoutputmodeforthistowork.InDSound,thereverbwillonlyworkifyouhaveanEAXcompatiblesoundcardsuchastheSBLive,andyoursample/streamwascreatedwiththeFSOUND_HW3Dflag.-----------------OnPlayStation2,the'Room'parameteristheonlyparametersupported.The

hardwareonlyallows'on'or'off',sothereverbwillbeoffwhen'Room'is-10000andonforeveryothervalue.-----------------OnXBox,itispossibletoapplyreverbto2dvoicesusingthisfunction.Bydefaultreverbisturnedofffor2dvoices.Ifthis2dvoicewasbeingpositionedina5.1arraywiththexboxonlyfunctionFSOUND_SetLevels,thencallingthisfunctionwilldisablethatcapabilityinfavourofenablingreverbforthe2dvoice.Itisalimitationofthexboxhardwarethatonlyoneoftheotherofthesefeaturescanbeexecutedatonetime.___________________Supportedonthefollowingplatforms:Win32,XBox,PlayStation2.

SeeAlso

FSOUND_REVERB_CHANNELPROPERTIES,FSOUND_Reverb_GetChannelProperties,FSOUND_Reverb_GetProperties,FSOUND_Reverb_SetProperties,FSOUND_SetLevels


[APIfunction]

FSOUND_Reverb_GetChannelProperties

Thisfunctiongetsthecurrentreverbpropertiesforthischannel.

signedcharF_APIFSOUND_Reverb_GetChannelProperties(intchannel,FSOUND_REVERB_CHANNELPROPERTIES*prop);

Parameters

channel Thechanneltohaveitsreverbmixreturned.

prop PointertoaFSOUND_REVERB_CHANNELPROPERTIESstructuredefinition.Thedefinitionforthisstructureisgiveninthelinkbelow.

ReturnValue


Remarks

___________________Supportedonthefollowingplatforms:Win32,XBox

SeeAlso

FSOUND_REVERB_CHANNELPROPERTIES,FSOUND_Reverb_GetProperties,FSOUND_Reverb_SetChannelProperties,FSOUND_Reverb_SetProperties


[Define]

FSOUND_CAPS

Driverdescriptionbitfields.UseFSOUND_Driver_GetCapstodetermineifadriverenumeratedhasthesettingsyouareafter.Theenumerateddriverdependsontheoutputmode,seeFSOUND_OUTPUTTYPES

FSOUND_CAPS_HARDWARE 0x1/*Thisdriversupportshardwareaccelerated3dsound.*/FSOUND_CAPS_EAX2 0x2/*ThisdriversupportsEAX2reverb*/FSOUND_CAPS_EAX3 0x10/*ThisdriversupportsEAX3reverb*/

SeeAlso

FSOUND_GetDriverCaps,FSOUND_OUTPUTTYPES


[Define]

FSOUND_CDPLAYMODES

PlaybackmethodforaCDAudiotrack,withFSOUND_CD_SetPlayMode

FSOUND_CD_PLAYCONTINUOUS 0/*StartsfromthecurrenttrackandplaystoendofCD.*/

FSOUND_CD_PLAYONCE 1/*Playsthespecifiedtrackthenstops.*/

FSOUND_CD_PLAYLOOPED 2/*Playsthespecifiedtracklooped,foreveruntilstoppedmanually.*/

FSOUND_CD_PLAYRANDOM 3/*Playstracksinrandomorder*/

SeeAlso

FSOUND_CD_Play,FSOUND_CD_SetPlayMode


[Define]

FSOUND_DSP_PRIORITIES

ThesedefaultprioritiesareusedbyFMODinternalsystemDSPunits.TheydescribethepositionoftheDSPchain,andtheorderofhowaudioprocessingisexecuted.YoucanactuallythroughtheuseofFSOUND_DSP_GetxxxUnit(wherexxxisthenameoftheDSPunit),disableorevenchangethepriorityofaDSPunit.

FSOUND_DSP_DEFAULTPRIORITY_CLEARUNIT 0/*DSPCLEARunit-donefirst*/

FSOUND_DSP_DEFAULTPRIORITY_SFXUNIT 100/*DSPSFXunit-donesecond*/

FSOUND_DSP_DEFAULTPRIORITY_MUSICUNIT 200/*DSPMUSICunit-donethird*/

FSOUND_DSP_DEFAULTPRIORITY_USER300/*Userpriority,usethisasreferenceforyourownDSPunits*/

FSOUND_DSP_DEFAULTPRIORITY_FFTUNIT900/*ThisreadsdataforFSOUND_DSP_GetSpectrum,soitcomesafteruserunits*/

FSOUND_DSP_DEFAULTPRIORITY_CLIPANDCOPYUNIT 1000/*DSPCLIPANDCOPYunit-last*/

SeeAlso

FSOUND_DSP_Create,FSOUND_DSP_GetSpectrum,FSOUND_DSP_SetPriority


[Define]

FSOUND_MODES

Sampledescriptionbitfields,ORthemtogetherforloadinganddescribingsamples.NOTE.Ifthefileformatbeingloadedalreadyhasadefinedformat,suchasWAVorMP3,thentryingtooverridethepre-definedformatwithanewsetofformatflagswillnotwork.Forexample,an8bitWAVfilewillnotloadas16bitifyouspecifyFSOUND_16BITS.Itwilljustignoretheflagandgoaheadloadingitas8bits.Forthesetypeofformatstheonlyflagsyoucanspecifythatwillreallyalterthebehaviourofhowitisloaded,arethefollowing.---------Loopingbehaviour-FSOUND_LOOP_OFF,FSOUND_LOOP_NORMAL,FSOUND_LOOP_BIDILoaddestination-FSOUND_HW3D,FSOUND_HW2D,FSOUND_2DLoadingbehaviour-FSOUND_NONBLOCKING,FSOUND_LOADMEMORY,FSOUND_LOADRAW,FSOUND_MPEGACCURATE,FSOUND_MPEGHALFRATE,FSOUND_FORCEMONOPlaybackbehaviour-FSOUND_STREAMABLE,FSOUND_ENABLEFXPlayStation2only-FSOUND_USECORE0,FSOUND_USECORE1,FSOUND_LOADMEMORYIOP---------Seeflagdescriptionsforwhatthesedo.

FSOUND_LOOP_OFF 0x00000001/*Fornonloopingsamples.*/FSOUND_LOOP_NORMAL 0x00000002/*Forforwardloopingsamples.*/

FSOUND_LOOP_BIDI 0x00000004/*Forbidirectionalloopingsamples.ifinhardware).*/

FSOUND_8BITS 0x00000008/*For8bitsamples.*/FSOUND_16BITS 0x00000010/*For16bitsamples.*/FSOUND_MONO 0x00000020/*Formonosamples.*/FSOUND_STEREO 0x00000040/*Forstereosamples.*/

FSOUND_UNSIGNED 0x00000080/*Forusercreatedsourcedatacontainingunsignedsamples.*/

FSOUND_SIGNED 0x00000100/*Forusercreatedsourcedatacontainingsigneddata.*/

FSOUND_DELTA 0x00000200/*Forusercreatedsourcedatastoredasdeltavalues.*/

FSOUND_IT214 0x00000400/*ForusercreatedsourcedatastoredusingIT214compression.*/

FSOUND_IT215 0x00000800/*ForusercreatedsourcedatastoredusingIT215compression.*/

FSOUND_HW3D 0x00001000/*Attemptstomakesamplesuse3dhardwareacceleration.(ifthecardsupportsit)*/

FSOUND_2D 0x00002000/*Tellssoftware(nothardware)basedsamplenottobeincludedin3dprocessing.*/

FSOUND_STREAMABLE 0x00004000/*Forastreamimgsoundwhereyoufeedthedatatoit.*/

FSOUND_LOADMEMORY 0x00008000/*"name"willbeinterpretedasapointertodataforstreamingandsamples.*/

FSOUND_LOADRAW 0x00010000/*Willignorefileformatandtreatasrawpcm.*/

FSOUND_MPEGACCURATE

0x00020000/*ForFSOUND_Stream_Open-foraccurateFSOUND_Stream_GetLengthMs/FSOUND_Stream_SetTime.WARNING,seeFSOUND_Stream_Openforinitalopeningtimeperformanceissues.*/

FSOUND_FORCEMONO0x00040000/*Forforcingstereostreamsandsamplestobemono-neededifusingFSOUND_HW3Dandstereodata-incursasmallspeedhitforstreams*/

FSOUND_HW2D 0x00080000/*2Dhardwaresounds.allowshardwarespecificeffects*/

FSOUND_ENABLEFX

0x00100000/*AllowsDX8FXtobeplayedbackonasound.RequiresDirectX8-Notethesesoundscannotbeplayedmorethanonce,be8bit,belessthanacertainsize,orhaveachangingfrequency*/

FSOUND_MPEGHALFRATE 0x00200000/*ForFMODCEonly-decodesmpegstreamsusingalowerqualitydecode,butfasterexecution*/

FSOUND_IMAADPCM 0x00400000/*ContentsarestoredcompressedasIMA

ADPCM*/

FSOUND_VAG 0x00800000/*ForPS2only-ContentsarecompressedasSonyVAGformat*/

FSOUND_NONBLOCKING

0x01000000/*ForFSOUND_Stream_Open/FMUSIC_LoadSong-Causesstreamormusictoopeninthebackgroundandnotblocktheforegroundapp.SeeFSOUND_Stream_GetOpenStateorFMUSIC_GetOpenStatetodeterminewhenitISready.*/

FSOUND_GCADPCM 0x02000000/*ForGamecubeonly-ContentsarecompressedasGamecubeDSP-ADPCMformat*/

FSOUND_MULTICHANNEL 0x04000000/*ForPS2andGamecubeonly-Contentsareinterleavedintoamulti-channel(morethanstereo)format*/

FSOUND_USECORE0 0x08000000/*ForPS2only-Sample/Streamisforcedtousehardwarevoices00-23*/

FSOUND_USECORE1 0x10000000/*ForPS2only-Sample/Streamisforcedtousehardwarevoices24-47*/

FSOUND_LOADMEMORYIOP0x20000000/*ForPS2only-"name"willbeinterpretedasapointertodataforstreamingandsamples.TheaddressprovidedwillbeanIOPaddress*/

FSOUND_IGNORETAGS0x40000000/*Skipsid3v2etctagcheckswhenopeningastream,toreduceseek/readoverheadwhenopeningfiles(helpswithCDperformance)*/

FSOUND_STREAM_NET 0x80000000/*Specifiesaninternetstream*/

FSOUND_NORMAL (FSOUND_16BITS|FSOUND_SIGNED|FSOUND_MONO)

SeeAlso

FMUSIC_GetOpenState,FMUSIC_LoadSong,FSOUND_Stream_GetLength,FSOUND_Stream_GetLengthMs,FSOUND_Stream_GetOpenState,FSOUND_Stream_Open,FSOUND_Stream_SetTime


[Define]

FSOUND_REVERB_PRESETS

AsetofpredefinedenvironmentPARAMETERS,createdbyCreativeLabsTheseareusedtoinitializeanFSOUND_REVERB_PROPERTIESstructurestatically.ieFSOUND_REVERB_PROPERTIESprop=FSOUND_PRESET_GENERIC;

FSOUND_PRESET_OFF

{0,7.5f,1.00f,-10000,-10000,0,1.00f,1.00f,1.0f,-2602,0.007f,{0.0f,0.0f,0.0f},200,0.011f,{0.0f,0.0f,0.0f},0.250f,0.00f,0.25f,0.000f,-5.0f,5000.0f,250.0f,0.0f,0.0f,0.0f,0x33f}

FSOUND_PRESET_GENERIC


FSOUND_PRESET_PADDEDCELL


FSOUND_PRESET_ROOM


FSOUND_PRESET_BATHROOM


FSOUND_PRESET_LIVINGROOM

{4,2.5f,1.00f,-1000,-6000,0,0.50f,0.10f,1.0f,-1376,0.003f,{0.0f,0.0f,0.0f},-1104,0.004f,{0.0f,0.0f,0.0f},0.250f,0.00f,0.25f,0.000f,-5.0f,5000.0f,250.0f,0.0f,100.0f,100.0f,0x3f}

FSOUND_PRESET_STONEROOM


FSOUND_PRESET_AUDITORIUM


FSOUND_PRESET_CONCERTHALL


{8,14.6f,1.00f,-1000,0,0,2.91f,1.30f,1.0f,-602,

FSOUND_PRESET_CAVE 0.015f,{0.0f,0.0f,0.0f},-302,0.022f,{0.0f,0.0f,0.0f},0.250f,0.00f,0.25f,0.000f,-5.0f,5000.0f,250.0f,0.0f,100.0f,100.0f,0x1f}

FSOUND_PRESET_ARENA


FSOUND_PRESET_HANGAR


FSOUND_PRESET_CARPETTEDHALLWAY


FSOUND_PRESET_HALLWAY


FSOUND_PRESET_STONECORRIDOR

{13,13.5f,1.00f,-1000,-237,0,2.70f,0.79f,1.0f,-1214,0.013f,{0.0f,0.0f,0.0f},395,0.020f,{0.0f,0.0f,0.0f

},0.250f,0.00f,0.25f,0.000f,-5.0f,5000.0f,250.0f,0.0f,100.0f,100.0f,0x3f}

FSOUND_PRESET_ALLEY


FSOUND_PRESET_FOREST


FSOUND_PRESET_CITY


FSOUND_PRESET_MOUNTAINS


FSOUND_PRESET_QUARRY

{18,17.5f,1.00f,-1000,-1000,0,1.49f,0.83f,1.0f,-10000,0.061f,{0.0f,0.0f,0.0f},500,0.025f,{0.0f,0.0f,0.0f},0.125f,0.70f,

0.25f,0.000f,-5.0f,5000.0f,250.0f,0.0f,100.0f,100.0f,0x3f}

FSOUND_PRESET_PLAIN


FSOUND_PRESET_PARKINGLOT

{20,8.3f,1.00f,-1000,0,0,1.65f,1.50f,1.0f,-1363,0.008f,{0.0f,0.0f,0.0f},-1153,0.012f,{0.0f,0.0f,0.0f},0.250f,0.00f,0.25f,0.000f,-5.0f,5000.0f,250.0f,0.0f,100.0f,100.0f,0x1f}

FSOUND_PRESET_SEWERPIPE

{21,1.7f,0.80f,-1000,-1000,0,2.81f,0.14f,1.0f,429,0.014f,{0.0f,0.0f,0.0f},1023,0.021f,{0.0f,0.0f,0.0f},0.250f,0.00f,0.25f,0.000f,-5.0f,5000.0f,250.0f,0.0f,80.0f,60.0f,0x3f}

FSOUND_PRESET_UNDERWATER


FSOUND_PRESET_DRUGGED

{23,1.9f,0.50f,-1000,0,0,8.39f,1.39f,1.0f,-115,0.002f,{0.0f,0.0f,0.0f},985,0.030f,{0.0f,0.0f,0.0f},

0.250f,0.00f,0.25f,1.000f,-5.0f,5000.0f,250.0f,0.0f,100.0f,100.0f,0x1f}

FSOUND_PRESET_DIZZY


FSOUND_PRESET_PSYCHOTIC


FSOUND_PRESET_PS2_ROOM

{1,0,0,0,0,0,0.0f,0.0f,0.0f,0,0.000f,{0.0f,0.0f,0.0f},0,0.000f,{0.0f,0.0f,0.0f},0.000f,0.00f,0.00f,0.000f,0.0f,0000.0f,0.0f,0.0f,0.0f,0.0f,0x31f}

FSOUND_PRESET_PS2_STUDIO_A


FSOUND_PRESET_PS2_STUDIO_B

{3,0,0,0,0,0,0.0f,0.0f,0.0f,0,0.000f,{0.0f,0.0f,0.0f},0,0.000f,{0.0f,0.0f,0.0f},0.000f,0.00f,0.00f,0.000f,0.0f,0000.0f,0.0f,0.0f,0.0f,0.0f,0x31f}{4,0,0,0,0,0,0.0f,0.0f,0.0f,0,0.000f,{0.0f,0.0f,0.0f

FSOUND_PRESET_PS2_STUDIO_C },0,0.000f,{0.0f,0.0f,0.0f},0.000f,0.00f,0.00f,0.000f,0.0f,0000.0f,0.0f,0.0f,0.0f,0.0f,0x31f}

FSOUND_PRESET_PS2_HALL


FSOUND_PRESET_PS2_SPACE


FSOUND_PRESET_PS2_ECHO


FSOUND_PRESET_PS2_DELAY


FSOUND_PRESET_PS2_PIPE


SeeAlso

FSOUND_REVERB_PROPERTIES,FSOUND_Reverb_SetProperties


[Define]

FSOUND_MISC_VALUES

MiscellaneousvaluesforFMODfunctions.

FSOUND_FREE -1/*valuetoplayonanyfreechannel,ortoallocateasampleinafreesampleslot.*/

FSOUND_UNMANAGED-2/*valuetoallocateasamplethatisNOTmanagedbyFSOUNDorplacedinasampleslot.*/

FSOUND_ALL-3/*forachannelindex,thisflagwillaffectALLchannelsavailable!Notsupportedbyeveryfunction.*/

FSOUND_STEREOPAN-1/*valueforFSOUND_SetPansothatstereosoundsarenotplayedathalfvolume.SeeFSOUND_SetPanformoreonthis.*/

FSOUND_SYSTEMCHANNEL-1000/*special'channel'IDforallchannelbasedfunctionsthatwanttoaltertheglobalFSOUNDsoftwaremixingoutputchannel*/

FSOUND_SYSTEMSAMPLE-1000/*special'sample'IDforallsamplebasedfunctionsthatwanttoaltertheglobalFSOUNDsoftwaremixingoutputsample*/

SeeAlso

FSOUND_PlaySound,FSOUND_PlaySoundEx,FSOUND_Sample_Alloc,FSOUND_Sample_Load,FSOUND_SetPan


[Enum]

FMOD_ERRORS

OnfailureofcommandsinFMOD,useFSOUND_GetErrortoattainwhathappened.

Enumerators

FMOD_ERR_NONE /*Noerrors*/

FMOD_ERR_BUSY/*CannotcallthiscommandafterFSOUND_Init.CallFSOUND_Closefirst.*/

FMOD_ERR_UNINITIALIZED/*ThiscommandfailedbecauseFSOUND_InitorFSOUND_SetOutputwasnotcalled*/

FMOD_ERR_INIT /*Errorinitializingoutputdevice.*/

FMOD_ERR_ALLOCATED/*Errorinitializingoutputdevice,butmorespecifically,theoutputdeviceisalreadyinuseandcannotbereused.*/

FMOD_ERR_PLAY /*Playingthesoundfailed.*/

FMOD_ERR_OUTPUT_FORMAT/*Soundcarddoesnotsupportthefeaturesneededforthissoundsystem(16bitstereooutput)*/

FMOD_ERR_COOPERATIVELEVEL /*Errorsettingcooperativelevelforhardware.*/

FMOD_ERR_CREATEBUFFER /*Errorcreatinghardwaresoundbuffer.*/

FMOD_ERR_FILE_NOTFOUND /*Filenotfound*/FMOD_ERR_FILE_FORMAT /*Unknownfileformat*/FMOD_ERR_FILE_BAD /*Errorloadingfile*/FMOD_ERR_MEMORY /*Notenoughmemoryorresources*/

FMOD_ERR_VERSION /*Theversionnumberofthisfileformatisnotsupported*/

FMOD_ERR_INVALID_PARAM /*Aninvalidparameterwaspassedtothisfunction*/

FMOD_ERR_NO_EAX /*TriedtouseanEAXcommandonanonEAXenabledchanneloroutput.*/

FMOD_ERR_CHANNEL_ALLOC /*Failedtoallocateanewchannel*/

FMOD_ERR_RECORD /*Recordingisnotsupportedonthismachine*/

FMOD_ERR_MEDIAPLAYER/*WindowsMediaPlayernotinstalledsocannotplaywmaoruseinternetstreaming.*/

FMOD_ERR_CDDEVICE /*AnerroroccuredtryingtoopenthespecifiedCDdevice*/

SeeAlso

FSOUND_Close,FSOUND_GetError,FSOUND_Init,FSOUND_SetOutput


[Enum]

FSOUND_MIXERTYPES

ThesemixertypesareusedwithFSOUND_SetMixer,tochoosewhichmixertouse,ortoactuponforotherreasonsusingFSOUND_GetMixer.Itisnotnescessarytosetthemixer.FMODwillautodetectthebestmixerforyou.

Enumerators

FSOUND_MIXER_AUTODETECT/*CE/PS2/GCOnly-Noninterpolating/lowqualitymixer.*/

FSOUND_MIXER_BLENDMODE /*Removed/obsolete.*/FSOUND_MIXER_MMXP5 /*Removed/obsolete.*/FSOUND_MIXER_MMXP6 /*Removed/obsolete.*/FSOUND_MIXER_QUALITY_AUTODETECT,/*

FSOUND_MIXER_QUALITY_FPU/*Win32/Linuxonly-Interpolating/volumerampingFPUmixer.*/

FSOUND_MIXER_QUALITY_MMXP5/*Win32/Linuxonly-Interpolating/volumerampingP5MMXmixer.*/

FSOUND_MIXER_QUALITY_MMXP6/*Win32/Linuxonly-Interpolating/volumerampingppro+MMXmixer.*/

FSOUND_MIXER_MONO/*CE/PS2/GConly-MONOnoninterpolating/lowqualitymixer.Forspeed*/

FSOUND_MIXER_QUALITY_MONO/*CE/PS2/GConly-MONOInterpolatingmixer.Forspeed*/

FSOUND_MIXER_MAX

SeeAlso

FSOUND_GetMixer,FSOUND_SetMixer


[Enum]

FSOUND_OUTPUTTYPES

TheseoutputtypesareusedwithFSOUND_SetOutput,tochoosewhichoutputdrivertouse.FSOUND_OUTPUT_DSOUNDwillnotsupporthardware3daccelerationifthesoundcarddriverdoesnotsupportDirectX6VoiceManagerExtensions.FSOUND_OUTPUT_WINMMisrecommendedforNTandCE.

Enumerators

FSOUND_OUTPUT_NOSOUND/*NoSounddriver,allcallstothissucceedbutdonothing.*/

FSOUND_OUTPUT_WINMM /*WindowsMultimediadriver.*/

FSOUND_OUTPUT_DSOUND

/*DirectSounddriver.YouneedthistogetEAX2orEAX3support,orFXapisupport.*/

FSOUND_OUTPUT_A3D /*A3Ddriver.*/

FSOUND_OUTPUT_OSS/*Linux/UnixOSS(OpenSoundSystem)driver,i.e.thekernelsounddrivers.*/

FSOUND_OUTPUT_ESD/*Linux/UnixESD(EnlightmentSoundDaemon)driver.*/

FSOUND_OUTPUT_ALSA /*LinuxAlsadriver.*/

FSOUND_OUTPUT_ASIO /*LowlatencyASIOdriver*/

FSOUND_OUTPUT_XBOX /*Xboxdriver*/FSOUND_OUTPUT_PS2 /*PlayStation2driver*/

FSOUND_OUTPUT_MAC /*MacSoundManagerdriver*/

FSOUND_OUTPUT_GC /*Gamecubedriver*/

FSOUND_OUTPUT_PSP /*PlayStationPortabledriver*/

FSOUND_OUTPUT_NOSOUND_NONREALTIME

/*Thisisthesameasnosound,butthesoundgenerationisdrivenbyFSOUND_Update*/

SeeAlso

FSOUND_GetOutput,FSOUND_SetOutput,FSOUND_Update


[Structure]

FSOUND_REVERB_PROPERTIES

Structuredefiningareverbenvironment.Formoreindepthdescriptionsofthereverbpropertiesunderwin32,pleaseseetheEAX2andEAX3documentationathttp://developer.creative.com/underthe'downloads'section.IftheydonothavetheEAX3documentation,thenmostinformationcanbeattainedfromtheEAX2documentation,asEAX3onlyaddssomemoreparametersandfunctionalityontopofEAX2.NotethedefaultreverbpropertiesarethesameastheFSOUND_PRESET_GENERICpreset.Notethatintegervaluesthattypicallyrangefrom-10,000to1000arerepresentedindecibels,andareofalogarithmicscale,notlinear,wherasfloatvaluesaretypicallylinear.PORTABILITY:Eachmemberhastheplatformitsupportsinbracesie(win32/xbox).Somereverbparametersareonlysupportedinwin32andsomeonlyonxbox.Ifallparametersaresetthenthereverbshouldproductasimilareffectoneitherplatform.Thenumericalvalueslistedbelowarethemaximum,minimumanddefaultvaluesforeachvariablerespectively.

Members

unsignedint Environment /*0,25,0,setsalllistenerproperties

(WIN32/PS2only)*/

float EnvSize /*1.0,100.0,7.5,environmentsizeinmeters(WIN32only)*/

float EnvDiffusion /*0.0,1.0,1.0,environmentdiffusion(WIN32/XBOX)*/

int Room /*-10000,0,-1000,roomeffectlevel(atmidfrequencies)(WIN32/XBOX/PS2)*/

int RoomHF /*-10000,0,-100,relativeroomeffectlevelathighfrequencies(WIN32/XBOX)*//*-10000,0,0,relativeroomeffectlevelatlow

int RoomLF frequencies(WIN32only)*/

float DecayTime /*0.1,20.0,1.49,reverberationdecaytimeatmidfrequencies(WIN32/XBOX)*/

float DecayHFRatio /*0.1,2.0,0.83,high-frequencytomid-frequencydecaytimeratio(WIN32/XBOX)*/

float DecayLFRatio /*0.1,2.0,1.0,low-frequencytomid-frequencydecaytimeratio(WIN32only)*/

int Reflections /*-10000,1000,-2602,earlyreflectionslevelrelativetoroomeffect(WIN32/XBOX)*/

float ReflectionsDelay /*0.0,0.3,0.007,initialreflectiondelaytime(WIN32/XBOX)*/

float ReflectionsPan[3] /*,,[0,0,0],earlyreflectionspanningvector(WIN32only)*/

int Reverb /*-10000,2000,200,latereverberationlevelrelativetoroomeffect(WIN32/XBOX)*/

float ReverbDelay /*0.0,0.1,0.011,latereverberationdelaytimerelativetoinitialreflection(WIN32/XBOX)*/

float ReverbPan[3] /*,,[0,0,0],latereverberationpanningvector(WIN32only)*/

float EchoTime/*.075,0.25,0.25,echotime(WIN32/PS2only.PS2=DelaytimeforECHO/DELAYmodesonly)*/

float EchoDepth /*0.0,1.0,0.0,echodepth(WIN32/PS2only.PS2=FeedbacklevelforECHOmodeonly)*/

float ModulationTime /*0.04,4.0,0.25,modulationtime(WIN32only)*/

float ModulationDepth /*0.0,1.0,0.0,modulationdepth(WIN32only)*/

float AirAbsorptionHF /*-100,0.0,-5.0,changeinlevelpermeterathighfrequencies(WIN32only)*/

float HFReference /*1000.0,20000,5000.0,referencehighfrequency(hz)(WIN32/XBOX)*/

float LFReference /*20.0,1000.0,250.0,referencelowfrequency(hz)(WIN32only)*//*0.0,10.0,0.0,like

float RoomRolloffFactor FSOUND_3D_SetRolloffFactorbutforroomeffect(WIN32/XBOX)*/

float Diffusion/*0.0,100.0,100.0,Valuethatcontrolstheechodensityinthelatereverberationdecay.(XBOXonly)*/

float Density/*0.0,100.0,100.0,Valuethatcontrolsthemodaldensityinthelatereverberationdecay(XBOXonly)*/

unsignedint Flags

/*FSOUND_REVERB_FLAGS-modifiesthebehaviorofaboveproperties(WIN32/PS2only)*/

SeeAlso

FSOUND_3D_SetRolloffFactor,FSOUND_REVERB_FLAGS,FSOUND_Reverb_GetProperties,FSOUND_REVERB_PRESETS,FSOUND_Reverb_SetProperties


[Structure]

FSOUND_REVERB_CHANNELPROPERTIES

Structuredefiningthepropertiesforareverbsource,relatedtoaFSOUNDchannel.Formoreindepthdescriptionsofthereverbpropertiesunderwin32,pleaseseetheEAX3documentationathttp://developer.creative.com/underthe'downloads'section.IftheydonothavetheEAX3documentation,thenmostinformationcanbeattainedfromtheEAX2documentation,asEAX3onlyaddssomemoreparametersandfunctionalityontopofEAX2.NotethedefaultreverbpropertiesarethesameastheFSOUND_PRESET_GENERICpreset.Notethatintegervaluesthattypicallyrangefrom-10,000to1000arerepresentedindecibels,andareofalogarithmicscale,notlinear,wherasfloatvaluesaretypicallylinear.PORTABILITY:Eachmemberhastheplatformitsupportsinbracesie(win32/xbox).Somereverbparametersareonlysupportedinwin32andsomeonlyonxbox.Ifallparametersaresetthenthereverbshouldproductasimilareffectoneitherplatform.LinuxandFMODCEdonotsupportthereverbapi.Thenumericalvalueslistedbelowarethemaximum,minimumanddefaultvaluesforeachvariablerespectively.

Members

int Direct /*-10000,1000,0,directpathlevel(atlowandmidfrequencies)(WIN32/XBOX)*/

int DirectHF /*-10000,0,0,relativedirectpathlevelathighfrequencies(WIN32/XBOX)*/

int Room /*-10000,1000,0,roomeffectlevel(atlowandmidfrequencies)(WIN32/XBOX/PS2)*//*-10000,0,0,relativeroomeffectlevelathigh

int RoomHF frequencies(WIN32/XBOX)*/

int Obstruction /*-10000,0,0,mainobstructioncontrol(attenuationathighfrequencies)(WIN32/XBOX)*/

floatObstructionLFRatio /*0.0,1.0,0.0,obstructionlow-frequencylevelre.maincontrol(WIN32/XBOX)*/

int Occlusion /*-10000,0,0,mainocclusioncontrol(attenuationathighfrequencies)(WIN32/XBOX)*/

floatOcclusionLFRatio /*0.0,1.0,0.25,occlusionlow-frequencylevelre.maincontrol(WIN32/XBOX)*/

floatOcclusionRoomRatio /*0.0,10.0,1.5,relativeocclusioncontrolforroomeffect(WIN32)*/

floatOcclusionDirectRatio /*0.0,10.0,1.0,relativeocclusioncontrolfordirectpath(WIN32)*/

int Exclusion /*-10000,0,0,mainexlusioncontrol(attenuationathighfrequencies)(WIN32)*/

float ExclusionLFRatio /*0.0,1.0,1.0,exclusionlow-frequencylevelre.maincontrol(WIN32)*/

int OutsideVolumeHF /*-10000,0,0,outsidesoundconelevelathighfrequencies(WIN32)*/

floatDopplerFactor /*0.0,10.0,0.0,likeDS3DflDopplerFactorbutpersource(WIN32)*/

float RolloffFactor /*0.0,10.0,0.0,likeDS3DflRolloffFactorbutpersource(WIN32)*/

float RoomRolloffFactor /*0.0,10.0,0.0,likeDS3DflRolloffFactorbutforroomeffect(WIN32/XBOX)*/

float AirAbsorptionFactor/*0.0,10.0,1.0,multipliesAirAbsorptionHFmemberofFSOUND_REVERB_PROPERTIES(WIN32)*/

int Flags /*FSOUND_REVERB_CHANNELFLAGS-modifiesthebehaviorofproperties(WIN32)*/

SeeAlso

FSOUND_REVERB_CHANNELFLAGS,FSOUND_Reverb_GetChannelProperties,FSOUND_REVERB_PROPERTIES

,FSOUND_Reverb_SetChannelProperties


[Structure]

FSOUND_TOC_TAG

StructuredefiningaCDtableofcontents.ThisstructureisreturnedasatagfromFSOUND_Stream_FindTagFieldwhenthetagname"CD_TOC"isspecified.Note:AlltracksontheCD-includingdatatracks-willberepresentedinthisstructuresoit'suseforanythingotherthangeneratingdiscidinformationisnotrecommended.Seethecddaexampleprogramforinfoonretrievingandusingthisstructure.

Members

char name[4] /*Thestring"TOC",justincasethisstructureisaccidentallytreatedasastring*/

int numtracks /*ThenumberoftracksontheCD*/int min[100] /*Thestartoffsetofeachtrackinminutes*/int sec[100] /*Thestartoffsetofeachtrackinseconds*/int frame[100] /*Thestartoffsetofeachtrackinframes*/

SeeAlso

FSOUND_Stream_FindTagField,FSOUND_Stream_Open


FMUSICAPIReferenceFMODApi.Usethistomodulefilesetc

Functions,Structures,Defines,Enums

-Functions

FMUSIC_CALLBACKFMUSIC_FreeSongFMUSIC_GetBPMFMUSIC_GetGlobalVolumeFMUSIC_GetMasterVolumeFMUSIC_GetNameFMUSIC_GetNumChannelsFMUSIC_GetNumInstrumentsFMUSIC_GetNumOrdersFMUSIC_GetNumPatternsFMUSIC_GetNumSamplesFMUSIC_GetOpenStateFMUSIC_GetOrderFMUSIC_GetPatternFMUSIC_GetPatternLengthFMUSIC_GetPausedFMUSIC_GetRealChannelFMUSIC_GetRowFMUSIC_GetSampleFMUSIC_GetSpeedFMUSIC_GetTimeFMUSIC_GetTypeFMUSIC_GetUserDataFMUSIC_IsFinishedFMUSIC_IsPlayingFMUSIC_LoadSongFMUSIC_LoadSongExFMUSIC_OptimizeChannelsFMUSIC_PlaySongFMUSIC_SetInstCallbackFMUSIC_SetLoopingFMUSIC_SetMasterSpeedFMUSIC_SetMasterVolumeFMUSIC_SetOrderFMUSIC_SetOrderCallback

FMUSIC_SetPanSeperationFMUSIC_SetPausedFMUSIC_SetReverbFMUSIC_SetRowCallbackFMUSIC_SetSampleFMUSIC_SetUserDataFMUSIC_SetZxxCallbackFMUSIC_StopAllSongsFMUSIC_StopSong

-Structures

FSOUND_REVERB_CHANNELPROPERTIESFSOUND_REVERB_PROPERTIESFSOUND_TOC_TAG

-Defines

FSOUND_CAPSFSOUND_CDPLAYMODESFSOUND_DSP_PRIORITIESFSOUND_INIT_FLAGSFSOUND_MISC_VALUESFSOUND_MODESFSOUND_REVERB_CHANNELFLAGSFSOUND_REVERB_FLAGSFSOUND_REVERB_PRESETSFSOUND_STATUS_FLAGS

-Enums


FMOD_ERRORSFMUSIC_TYPESFSOUND_FX_MODESFSOUND_MIXERTYPESFSOUND_OUTPUTTYPESFSOUND_SPEAKERMODESFSOUND_STREAM_NET_STATUSFSOUND_TAGFIELD_TYPE

[APIfunction]

FMUSIC_CALLBACK

CallbackdefinitionforFMUSICcallbacks(mod/s3m/xm/it).

voidF_CALLBACKAPIFMUSIC_CALLBACK(FMUSIC_MODULE*mod,unsignedcharparam);

Parameters

mod Themusicfiletohavecallbacksperformedon.

paramTheargumentrelatingspecificallytothecallbackmade,whetheritisarow/orderorZxxcallback.Forexampleontherowcallback,therownumberwouldbereturned.

ReturnValue

void

Remarks

Thecallbacksaremadefromwithinthemixersystem,soitisbesttokeepthecodetoanabsoluteminimumtopreventsoundbreakup.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_SetInstCallback,FMUSIC_SetOrderCallback,FMUSIC_SetRowCallback,FMUSIC_SetZxxCallback


[APIfunction]

FMUSIC_FreeSong

FreesmemoryallocatedforasongandremovesitfromtheFMUSICsystem.

signedcharF_APIFMUSIC_FreeSong(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtobefreed.

ReturnValue


Remarks

SeeAlso

FMUSIC_LoadSong,FMUSIC_LoadSongEx


[APIfunction]

FMUSIC_LoadSong

Toloadamoduleorbankwithagivenfilename.FMUSICSupportsloadingof-.MOD(protracker/fasttrackermodules)-.S3M(screamtracker3modules)-.XM(fasttracker2modules)-.IT(impulsetrackermodules)-.MID(MIDIfiles)-.RMI(MIDIfiles)-.SGT(DirectMusicsegmentfiles)-.FSB(FMODSampleBankfiles)

FMUSIC_MODULE*F_APIFMUSIC_LoadSong(constchar*name);

Parameters

name Filenameofmoduletoload.

ReturnValue

Onsuccess,apointertoaFMUSIC_MODULEhandleisreturned.Onfailure,NULLisreturned.

Remarks

Thisfunctionautodetectstheformattype,regardlessoffilename.TheMIDIloaderdoesnotsupportuserfilecallbacks.ForWADtypedatastructureswithembeddedMIDIfilesFMUSIC_LoadSongExwillhavetobeusedwithmemoryloading.VariousotherfunctionalityisnotprovidedinMIDI.SeerelevantFMUSICfunctionstoseeifafeatureissupportedornot.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_FreeSong,FMUSIC_LoadSong,FMUSIC_LoadSongEx,FSOUND_File_SetCallbacks


[APIfunction]

FMUSIC_LoadSongEx

Toloadamoduleorbankwithagivenfilename.FMUSICSupportsloadingof-.MOD(protracker/fasttrackermodules)-.S3M(screamtracker3modules)-.XM(fasttracker2modules)-.IT(impulsetrackermodules)-.MID(MIDIfiles)-.RMI(MIDIfiles)-.SGT(DirectMusicsegmentfiles)-.FSB(FMODSampleBankfiles)

FMUSIC_MODULE*F_APIFMUSIC_LoadSongEx(constchar*name_or_data,intoffset,intlength,unsignedintmode,constint*samplelist,intsamplelistnum);

Parameters

name_or_dataNameofsongorpointertodatacontainingsongtoload(ifloadingfrommemoryandnotfile).OnPlayStation2datamustbe16bytealignedifloadingfrommemory.

offset Optional.0bydefault.If>0,thisvalueisusedtospecifyanoffsetinafile,sofmodwillseekbeforeopening.

length


mode

Modeforopeningsong.Withmodulefiles,onlyFSOUND_LOADMEMORY,FSOUND_NONBLOCKING,FSOUND_LOOP_NORMAL,orFSOUND_LOOP_OFFare

supported.ForFSBfiles,FSOUND_2D,FSOUND_HW3D,FSOUND_FORCEMONOalsowork.

samplelistOptional.Pointertoarrayofsampleindiciestoload.LeaveasNULLifyouwantallsamplestobeloaded(defaultbehaviour).SeeRemarksformoreonthis.

samplelistnum Optional.Numberofentriesinthesamplelistarray.

ReturnValue

Onsuccess,aFMUSIC_MODULEhandleisreturned.Onfailure,NULLisreturned.

Remarks

Loadingasongfromamemoryhandleisdangerousinonerespect,ifthedataiscorruptedortruncated,thenFMUSICcouldcrashinternallytryingtoloadit.OnPlayStation2thedataandlengthpointermustbe16bytealignedforDMApurposes.Thesamplelistandsamplelistnumparametersareusefulforlimitingtheamountofdatafmodloads.ThisfeatureisfortheFSBformatonly.Itisespeciallyusefulifyouhaveabankofsoundsandwanttorandomizetheloadingabitbytellingwhichsoundstoloadwithrandomvalues,andconsequentlywhichnottoload.OnPlayStation2,samplelistnumhasalimitof1536entries.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_FreeSong,FMUSIC_LoadSong


[APIfunction]

FMUSIC_OptimizeChannels

Thisfunctionhelpswithchannelusage.Ifyouaredesperateforchannels,andyouarepreparedtoletthemusicroutinesdropafewchannels,thencallingthisfunctioncanhelp.Itbasicallydoesnttrytoplayanynewsoundsifacertainchannellimitisbeingplayed(includingsoundeffects),andthenewsoundisbelowacertainspecifiedvolume.ie.Yousetittomaxchannels=16,andminvolume=0x10.Inthiscase,themodwillplaynormallyaslongasthetotalnumberofchannelsbeingplayedinclusingsoundeffefctsisbelow16(seeFSOUND_GetChannelsPlaying).Ifthenumberofchannelsplayingexceeds16(throughachangeinthemusic,orextrasoundeffectsarespawned,thensoundswithamusicianspecifiedvolumeoflessthan0x10willbeignored.Thevolumeisbasedonvolumecolumn/defaultvolume/volumesetcommandsinthemod.mastervolume,envelopevolumesetcarenottakenintoaccount(thisgivesmorecontroloverhowitwillworkfromthetracker).

DLL_APIsignedcharF_APIFMUSIC_OptimizeChannels(FMUSIC_MODULE*mod,intmaxchannels,intminvolume);

Parameters

mod Pointertothesongtosetchannel/volumeoptimizationsettings.

maxchannels Channelcounttobemixedbeforefmusicstartstodropchannelsfromthesong.

minvolume

Ifmaxchannelsisexceeded,thenmusicchannelswithvolumesbelowthisvaluewillnotbeplayed.Rangeis0-64.Thisisthevaluethetrackerdisplays.All

trackersuse0-64.

ReturnValue


Remarks

maxchannelswilldefaulttothenumberofchannelsallocatedbyFSOUND,sothiswillneverhappenbydefault.minvolumewilldefaultto0,soitwillalwayssucceedbydefault.ToseehowmanychannelsarecurrentlybeingMIXED,useFSOUND_GetChannelsPlaying.Asamusicianmentionedtomeonce,mostofhisdefaultvolumesaresetfairlyhigh,andanylowendvolumesareusuallyechoesetc,andcanaffordtobedropped.------------Note:ThisfunctionisnotsupportedwiththeMIDIformat.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_GetChannelsPlaying


[APIfunction]

FMUSIC_PlaySong

Startsasongplaying.

signedcharF_APIFMUSIC_PlaySong(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtobeplayed.

ReturnValue

TRUEsongsucceededplayingFALSEsongfailedplaying

Remarks


SeeAlso

FMUSIC_IsPlaying,FMUSIC_SetLooping,FMUSIC_StopAllSongs,FMUSIC_StopSong


[APIfunction]

FMUSIC_SetInstCallback

Setsausercallbacktooccureverytimeainstrumentisplayed,triggeredfromaMOD,S3M,XMorITfile.

signedcharF_APIFMUSIC_SetInstCallback(FMUSIC_MODULE*mod,FMUSIC_CALLBACKcallback,intinstrument);

Parameters

mod Themoduleorsongtosetthecallbackfor.callback Thecallbackfunctionyousupplytogetcalled.instrument Callthecallbackwhenthisinstrumentnumberistriggered.

ReturnValue


Remarks

ItisimportanttonotethatthiscallbackwillbecalledfromdirectlyWITHINthemixer/musicupdatethread,thereforeitisimperativethatwhateveryoudofromthiscallbackbeextremelyefficient.Iftheroutinetakestoolongthenbreakupsinthesoundwilloccur,oritwillbasicallystopmixinguntilyoureturnfromthefunction.Thissortoffunctionisusuallybestforjustsettingaflag,ordosomesimplevariablemanipulation,andthenexiting,lettingyourmainthreaddowhatitneedstobasedontheseflagsorvariables.------------

ThiscallbackisLATENCYadjusted,sothatthecallbackhappenswhenyouHEARthesound,notwhenitismixed,foraccuratesynchronization.UseFSOUND_INIT_DONTLATENCYADJUSTifyouwantittobecalledbackatmixtime,whichisusefulifyouwanttocontrolthemusicinteractively.------------Note:ThisfunctionisnotsupportedwiththeMIDIformat.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_CALLBACK,FMUSIC_SetOrderCallback,FMUSIC_SetRowCallback,FMUSIC_SetZxxCallback


[APIfunction]

FMUSIC_SetLooping

Setsloopingmodeformidiandmodfiles.

signedcharF_APIFMUSIC_SetLooping(FMUSIC_MODULE*mod,signedcharlooping);

Parameters

mod Pointertothesong.

looping SettoTRUEtomakeitloopforever,orFALSEtoonlyhaveitplayonce.

ReturnValue


Remarks

DefaultstoTRUE.TodisableloopingyoumustcallthisfunctionusingFALSEastheparameter.FormidifilesthisonlytakeseffectbeforeFMUSIC_PlaySongiscalled.Formodfilesthiscanbecalledatanytimeincludingduringplayback.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_PlaySong

Thisdocumentcopyright©FirelightTechnologies,Pty,Ltd,1999-2002.Allrightsreserved.

GeneratedFriNov1800:31:542005bySourceDocv0.10,theautomatedsourcecodedocumenter.

[APIfunction]

FMUSIC_SetMasterSpeed

Setsasongsmasterspeedscale,sothatthesongcanbespeduporsloweddown.

signedcharF_APIFMUSIC_SetMasterSpeed(FMUSIC_MODULE*mod,F_FLOAT_APIspeed);

Parameters

mod Pointertothesongtohaveitsspeedscaleset.

speed Speedscaleforsong.1.0isdefault.Minimumis0(stopped),maximumis10.0.

ReturnValue


Remarks



[APIfunction]

FMUSIC_SetMasterVolume

Setsasongsmastervolume.

signedcharF_APIFMUSIC_SetMasterVolume(FMUSIC_MODULE*mod,intvolume);

Parameters

mod Pointertothesongtohaveitsmastervolumeset.volume valuefrom0-256.0=silence,256=fullvolume.

ReturnValue


Remarks

Noteifthehardwaremidisynthisselected,youcannotsetthemastervolume.ThiscommandwillonlyworkreliablyifFSOUND_INIT_USEDEFAULTMIDISYNTHisselected.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_GetGlobalVolume,FMUSIC_GetMasterVolume,FSOUND_GetSFXMasterVolume,FSOUND_SetSFXMasterVolume


[APIfunction]

FMUSIC_SetOrder

Setsasongsorderposition/currentplayingposition.

signedcharF_APIFMUSIC_SetOrder(FMUSIC_MODULE*mod,intorder);

Parameters

mod Pointertothesongtohaveitsorderchanged.orderOrdernumbertojumpto.

ReturnValue


Remarks

Note:ThisfunctionisnotsupportedwiththeMIDIformat.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_GetOrder


[APIfunction]

FMUSIC_SetOrderCallback

Setsausercallbacktooccuroneveryorderdivisiblebytheorderstepparameter,playedfromaMOD,S3M,XMorITfile.

signedcharF_APIFMUSIC_SetOrderCallback(FMUSIC_MODULE*mod,FMUSIC_CALLBACKcallback,intorderstep);

Parameters

mod Themoduleorsongtosetthecallbackfor.callback Thecallbackfunctionyousupplytogetcalled.orderstep Callthecallbackeverymultipleofthisnumberoforders.

ReturnValue


Remarks



SeeAlso

FMUSIC_CALLBACK,FMUSIC_SetInstCallback,FMUSIC_SetRowCallback,FMUSIC_SetZxxCallback


[APIfunction]

FMUSIC_SetPanSeperation

Setsthemasterpanseperationforamodule.

signedcharF_APIFMUSIC_SetPanSeperation(FMUSIC_MODULE*mod,F_FLOAT_APIpansep);

Parameters

pansep Thepanscale.1.0meansfullpanseperation,0meansmono.

ReturnValue


Remarks

Thisissetto1.0bydefault.------------Note:ThisfunctionisnotsupportedwiththeMIDIformat.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FSOUND_SetPanSeperation


[APIfunction]

FMUSIC_SetPaused

Pausesasong

signedcharF_APIFMUSIC_SetPaused(FMUSIC_MODULE*mod,signedcharpause);

Parameters

mod Pointertothesongtobepaused/unpaused.pause TRUE-songshouldbePAUSED,FALSE-songshouldbeUNPAUSED

ReturnValue


Remarks


SeeAlso

FMUSIC_GetPaused


[APIfunction]

FMUSIC_SetReverb

TurnsonreverbforMIDI/RMIfiles.

signedcharF_APIFMUSIC_SetReverb(signedcharreverb);

Parameters

reverb SettoTRUEtoturnMIDIreverbon,FALSEtoturnMIDIreverboff.

ReturnValue


Remarks

ReverbmaybeenabledthroughsoftwareemulationinthefutureforMODbasedformats.___________________Supportedonthefollowingplatforms:Win32


[APIfunction]

FMUSIC_SetRowCallback

Setsausercallbacktooccuroneveryrowdivisiblebytherowstepparameter,playedfromaMOD,S3M,XMorITfile.

signedcharF_APIFMUSIC_SetRowCallback(FMUSIC_MODULE*mod,FMUSIC_CALLBACKcallback,introwstep);

Parameters

mod Themoduleorsongtosetthecallbackfor.callback Thecallbackfunctionyousupplytogetcalled.rowstep Callthecallbackeverymultipleofthisnumberofrows.

ReturnValue


Remarks



SeeAlso

FMUSIC_CALLBACK,FMUSIC_SetInstCallback,FMUSIC_SetOrderCallback,FMUSIC_SetZxxCallback


[APIfunction]

FMUSIC_SetSample

Replacesamod'ssamplewithasampledefinitionspecified.

signedcharF_APIFMUSIC_SetSample(FMUSIC_MODULE*mod,intsampno,FSOUND_SAMPLE*sptr);

Parameters

mod Pointertothesongtosetthesamplefor.sampno indextosampleinsidemodule.sptr Pointertothesampledefinitiontoreplacemodsample

ReturnValue


Remarks

BecauseoftheinstrumentnatureofsomeformatslikeXM,thisfunctionlistsallthesamplesinorderofinstrumentsandtheirsubsamples.ieifinstrument1has2samplesandinstrument2contains3samples,thensampnointhiscasewouldbe0and1forinstrument1'ssamples,and2,3&4forinstrument2'ssamples.------------FMODdoesnotfreetheexistingmodsamplethatyoumaybeoverwriting.Ifyoudooverwriteanexistinghandle,itmaybelost,andyoumayincuramemoryleak.Itisagoodideatofreetheexistingsamplefirstbeforeoverwritingit.------------Important:ForPlayStation2,thisfunctionhastodoablockingquerytotheIOP,andcantakesignificantlymoretimethanastandardnonblockingfmod

function.Thismeansitisbesttocachethepointersforsampleswhileloading,andnotcallthisfunctioninrealtime.------------ThisfunctionisnotsupportedwiththeMIDIformat.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_GetSample


[APIfunction]

FMUSIC_SetUserData

Setsauserdefinedvaluetostorewiththemusicfiletoberetrievedlater.

signedcharF_APIFMUSIC_SetUserData(FMUSIC_MODULE*mod,void*userdata);

Parameters

mod Pointertothesong.userdata Valuetostorewithmusicobject.

ReturnValue


Remarks


SeeAlso

FMUSIC_GetUserData


[APIfunction]

FMUSIC_SetZxxCallback

SetsausercallbackforanyZxxcommandsencounteredinanS3M,XMorITfile.

signedcharF_APIFMUSIC_SetZxxCallback(FMUSIC_MODULE*mod,FMUSIC_CALLBACKcallback);

Parameters

mod Themoduleorsongtosetthecallbackfor.

callback ThecallbackfunctionyousupplytogetcalleduponexecutionofaZxxcommand.

ReturnValue


Remarks

ThevaluepassedintotheparamparameterofthecallbackisthexxvaluespecifiedintheZxxcommandbythemusician.------------ItisimportanttonotethatthiscallbackwillbecalledfromdirectlyWITHINthemixer/musicupdatethread,thereforeitisimperativethatwhateveryoudofromthiscallbackbeextremelyefficient.Iftheroutinetakestoolongthenbreakupsinthesoundwilloccur,oritwillbasicallystopmixinguntilyoureturnfromthefunction.Thissortoffunctionisusuallybestforjustsettingaflag,ordosomesimplevariablemanipulation,andthenexiting,lettingyourmainthreaddowhatitneedsto

basedontheseflagsorvariables.------------ThiscallbackisLATENCYadjustedbydefault,sothatthecallbackhappenswhenyouHEARthesound,notwhenitismixed,foraccuratesynchronization.UseFSOUND_INIT_DONTLATENCYADJUSTifyouwantittobecalledbackatmixtime,whichisusefulifyouwanttocontrolthemusicinteractively.------------Note:ThisfunctionisnotsupportedwiththeMIDIformat.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_CALLBACK,FMUSIC_SetInstCallback,FMUSIC_SetOrderCallback,FMUSIC_SetRowCallback


[APIfunction]

FMUSIC_StopAllSongs

Stopsallsongsfromplaying.Thisisusefulifyouhavemultiplesongsplayingatonceandwantaquickwaytostopthem

voidF_APIFMUSIC_StopAllSongs();

ReturnValue

void

Remarks


SeeAlso

FMUSIC_PlaySong,FMUSIC_StopSong


[APIfunction]

FMUSIC_StopSong

Stopsasongfromplaying.

signedcharF_APIFMUSIC_StopSong(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtobestopped.

ReturnValue


Remarks


SeeAlso

FMUSIC_PlaySong,FMUSIC_StopAllSongs


[APIfunction]

FMUSIC_GetBPM

Returnsthesong'scurrentBPM.

intF_APIFMUSIC_GetBPM(FMUSIC_MODULE*mod);

Parameters

mod PointertothesongtoretrievecurrentsongBPMfrom.

ReturnValue

Onsuccess,song'scurrentBPMisreturned.Onfailure,-1isreturned.

Remarks


SeeAlso

FMUSIC_GetSpeed


[APIfunction]

FMUSIC_GetGlobalVolume

Returnsthesong'scurrentglobalvolume

intF_APIFMUSIC_GetGlobalVolume(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievesongglobalvolumefrom.

ReturnValue

Songscurrentglobalvolume,from0(silence)tothemaximumvaluedeterminedbythemusicformat.Globalvolumemaximumsaredifferentinrespecttoeachformat,theyrangefrom64to256.Onfailure,-1isreturned.

Remarks

GLOBALvolumeisnotthesameasMASTERvolume.GLOBALvolumeisaninternaloverallvolumewhichcanbealteredbythesongitself(ietheremightbecommandstofadeinaparticularpartofthesongbyscalingallthevolumesinthesongupslowlyfromnothing).GLOBALvolumeisdifferenttoMASTERvolumeinthatthesongcanmodifywithoutyourpermission,whereasMASTERvolumeisanoverallscalarthatyoucancontrol.Forgeneraluse,MASTERvolumeismoreuseful,butyoumaywanttoresetasong'sGLOBALvolumeatcertaintimesinthesong.(forexamplethesongmighthavefadedoutbyusingGLOBALvolumeandyouwanttoresetit)___________________


SeeAlso

FMUSIC_GetMasterVolume,FMUSIC_SetMasterVolume


[APIfunction]

FMUSIC_GetMasterVolume

Returnsthesong'scurrentmastervolume

intF_APIFMUSIC_GetMasterVolume(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievesongmastervolumefrom.

ReturnValue

Onsuccess,thesong'scurrentmastervolume,from0(silence)to256(fullvolume)isreturnedOnfailure,-1isreturned.

Remarks


SeeAlso

FMUSIC_GetGlobalVolume,FMUSIC_SetMasterVolume


[APIfunction]

FMUSIC_GetName

Returnsthenameofthesongsetbythecomposer.WithMIDIformat,thefilenameisreturned.

constchar*F_APIFMUSIC_GetName(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievenamefrom.

ReturnValue

Onsuccess,thenameofthesongasaNULLterminatedstringisreturned.Onfailure,NULLisreturned.

Remarks



[APIfunction]

FMUSIC_GetNumChannels

Returnsthenumberofchannelswithinthissongspatterndata

intF_APIFMUSIC_GetNumChannels(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievenumberofchannelsfrom.

ReturnValue

NumberofchannelswithinthissongspatterndataOnfailure,0isreturned.

Remarks



[APIfunction]

FMUSIC_GetNumInstruments

Returnsthenumberofinstrumentscontainedinthissong.

intF_APIFMUSIC_GetNumInstruments(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievenumberofinstrumentsfrom.

ReturnValue

Onsuccess,thenumberofinstrumentscontainedinthissongisreturned.Onfailure,0isreturned.

Remarks



[APIfunction]

FMUSIC_GetNumOrders

Returnsthenumberofordersinthissong.

intF_APIFMUSIC_GetNumOrders(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievenumberofordersfrom.

ReturnValue

Onsuccess,thenumberofordersinthissongisreturned.Onfailure,0isreturned.

Remarks



[APIfunction]

FMUSIC_GetNumPatterns

Returnsthenumberofpatternscontainedinthissong.

intF_APIFMUSIC_GetNumPatterns(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievenumberofpatterns.

ReturnValue

Onsuccess,thenumberofpatternscontainedinthissongisreturned.Onfailure,0isreturned.

Remarks



[APIfunction]

FMUSIC_GetNumSamples

Returnsthenumberofsamplescontainedinthissong.

intF_APIFMUSIC_GetNumSamples(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievenumberofsamples.

ReturnValue

Numberofsamplescontainedinthissong.Onfailure,0isreturned.

Remarks



[APIfunction]

FMUSIC_GetOpenState

IfamodisopenedwithFSOUND_NONBLOCKING,thisfunctionreturnsthestateoftheopeningmod.

intF_APIFMUSIC_GetOpenState(FMUSIC_MODULE*mod);

Parameters

mod Pointertothemodtogettheopenstatefrom.

ReturnValue

0=modisopenedandready.-1=modhandlepassedinisinvalid.-2=modisstillopening-3=modfailedtoopen.(filenotfound,outofmemoryorothererror).

Remarks



[APIfunction]

FMUSIC_GetOrder

Returnsthesong'scurrentordernumber

intF_APIFMUSIC_GetOrder(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievecurrentordernumberfrom.

ReturnValue

Onsuccess,thesong'scurrentordernumberisreturned.Onfailure,-1isreturned.

Remarks

Thisvalueislatencyadjustedbydefault,andreturnsthenumberyouarehearing,notthe'mix-time'value.UseFSOUND_INIT_DONTLATENCYADJUSTifyouwantthevalueatmixtime,whichisusefulifyouwanttocontrolthemusicinteractively,orfromaDSPcallback.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_GetPattern,FMUSIC_GetPatternLength,FMUSIC_SetOrder


[APIfunction]

FMUSIC_GetPattern

Returnsthesong'scurrentpatternnumber

intF_APIFMUSIC_GetPattern(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievecurrentpatternnumberfrom.

ReturnValue

Onsuccess,Thesong'scurrentpatternnumberisreturned.Onfailure,-1isreturned.

Remarks


SeeAlso

FMUSIC_GetOrder


[APIfunction]

FMUSIC_GetPatternLength

Returnsthethelengthinrowsofthepatternforthespecifiedordernumber.

intF_APIFMUSIC_GetPatternLength(FMUSIC_MODULE*mod,intorderno);

Parameters

mod Pointertothesongto.

ReturnValue

Onsuccess,thesongspatternlengthatthespecifiedorderisreturned.Onfailure,0isreturned.

Remarks


SeeAlso

FMUSIC_GetOrder


[APIfunction]

FMUSIC_GetPaused

Returnswhethersongiscurrentlypausedornot.

signedcharF_APIFMUSIC_GetPaused(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtogetpausedflagfrom.

ReturnValue

Onsuccess,TRUEisreturnedtosaythesongiscurrentlypausedOnfailure,FALSEisreturnedtosaythesongisNOTcurrentlypaused

Remarks


SeeAlso

FMUSIC_SetPaused


[APIfunction]

FMUSIC_GetRealChannel

ReturnstherealFSOUNDchannelplayingbasedonthemod'sFMUSICchannel.

intF_APIFMUSIC_GetRealChannel(FMUSIC_MODULE*mod,intmodchannel);

Parameters

mod Pointertothesong.modchannel Themodchannelindex,toquerytherealchannelfrom.

ReturnValue

Onsuccess,thechannelindexfortherespectivemodchannelisreturned.Onfailure,-1isreturned.

Remarks

NoteFMUSICmodplaybackonlyallocatesarealchannelonamodchannelthefirsttimeaninstrumentisplayed.NNA'swillnotregister.Thisfunctiononlyreturnstheprimaryrealchannelforthemodchannel.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube


[APIfunction]

FMUSIC_GetRow

Returnsthesong'scurrentrownumber.

intF_APIFMUSIC_GetRow(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievecurrentrowfrom.

ReturnValue

Onsuccess,thesong'scurrentrownumberisreturned.Onfailure,-1isreturned.

Remarks



[APIfunction]

FMUSIC_GetSample

Returnsapointertoasampleinsideamodule.Onceyouhaveaccesstothemodule'ssample,youcandoalotofthingstoit,includinglockingandmodifyingthedatawithin;usingtheFSOUND_Sample_functionality.

FSOUND_SAMPLE*F_APIFMUSIC_GetSample(FMUSIC_MODULE*mod,intsampno);

Parameters

mod Pointertothesongtoretrieveasamplehandlefromsampno indextosampleinsidemodule.

ReturnValue

Onsuccess,avalidsamplehandleisreturned.Onfailure,NULLisreturned.

Remarks

BecauseoftheinstrumentnatureofsomeformatslikeXM,thisfunctionlistsallthesamplesinorderofinstrumentsandtheirsubsamples.ieifinstrument1has2samplesandinstrument2contains3samples,thensampnointhiscasewouldbe0and1forinstrument1'ssamples,and2,3&4forinstrument2'ssamples.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube

SeeAlso

FMUSIC_SetSample


[APIfunction]

FMUSIC_GetSpeed

Returnsthesong'scurrentspeed.

intF_APIFMUSIC_GetSpeed(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtoretrievecurrentsongspeedfrom.

ReturnValue

Onsuccess,Thesong'scurrentspeedisreturnedOnfailure,-1isreturned.

Remarks


SeeAlso

FMUSIC_GetBPM


[APIfunction]

FMUSIC_GetTime

Returnsthetimeinmillisecondssincethesongwasstarted.Thisisusefulforsynchronizingpurposesbecuaseitwillbeexactlythesameeverytime,anditisreliablyretriggereduponstartingthesong.Tryingtosynchronizeusingotherwindowstimerscanleadtovaryingresults,andinexactperformance.Thisfixesthatproblembyactuallyusingthenumberofsamplessenttothesoundcardasareference.

intF_APIFMUSIC_GetTime(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongtogettimefrom.

ReturnValue

Onsuccess,thetimeplayedinmillisecondsisreturned.Onfailure,-1isreturned.

Remarks



[APIfunction]

FMUSIC_GetType

Returnstheformattypeasong.

intF_APIFMUSIC_GetType(FMUSIC_MODULE*mod);

Parameters


ReturnValue

Onsuccess,thefollowingvaluesarereturned:FMUSIC_TYPE_NONEFMUSIC_TYPE_MODFMUSIC_TYPE_S3MFMUSIC_TYPE_XMFMUSIC_TYPE_ITFMUSIC_TYPE_MIDIOnfailure,FMUSIC_TYPE_NONEisreturned.

Remarks


SeeAlso

FMUSIC_TYPES


[APIfunction]

FMUSIC_GetUserData

RetrievesthedatasetbyFMUSIC_SetUserData

void*F_APIFMUSIC_GetUserData(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesong.

ReturnValue

Onsuccess,userdatasetbyFMUSIC_SetUserDataisreturned.Onfailure,0isreturned.

Remarks


SeeAlso

FMUSIC_SetUserData


[APIfunction]

FMUSIC_IsFinished

Returnswhetherthesonghascompletedplaying,orwhenthelastorderhasfinishedplaying.Thisstayssetevenifthesongloops.

signedcharF_APIFMUSIC_IsFinished(FMUSIC_MODULE*mod);

Parameters

mod Pointertothesongthatyouwantcheckiffinishedornot.

ReturnValue

TRUESonghasfinishedplaying.FALSESonghasnotfinishedplaying.

Remarks

Somesongsmayuseapatternbreakorpatternjumpandneverreachthelastpattern.___________________Supportedonthefollowingplatforms:Win32,WinCE,Linux,Macintosh,XBox,PlayStation2,GameCube


[APIfunction]

FMUSIC_IsPlaying

Returnswhetherthesongiscurrentlyplayingornot.

signedcharF_APIFMUSIC_IsPlaying(FMUSIC_MODULE*mod);

Parameters


ReturnValue

TRUESongisplaying.FALSESongisstopped.

Remarks


SeeAlso

FMUSIC_PlaySong


[Enum]

FMUSIC_TYPES

Thesedefinitionsdescribethetypeofsongbeingplayed.

Enumerators

FMUSIC_TYPE_NONEFMUSIC_TYPE_MOD /*Protracker/Fasttracker*/FMUSIC_TYPE_S3M /*ScreamTracker3*/FMUSIC_TYPE_XM /*FastTracker2*/FMUSIC_TYPE_IT /*ImpulseTracker.*/FMUSIC_TYPE_MIDI /*MIDIfile*/FMUSIC_TYPE_FSB /*FMODSampleBankfile*/

SeeAlso

FMUSIC_GetType


[Define]

FSOUND_INIT_FLAGS

Initializationflags.UsethemwithFSOUND_Initintheflagsparametertochangevariousbehaviour.FSOUND_INIT_ENABLESYSTEMCHANNELFXIsaninitmodewhichenablestheFSOUNDmixerbuffertobeaffectedbyDirectX8effects.NotethatduetolimitationsofDirectSound,FSOUND_Initmayfailifthisisenabledbecausethebuffersizeistoosmall.ThiscanbefixedwithFSOUND_SetBufferSize.IncreasetheBufferSizeuntilitworks.WhenitisenabledyoucanusetheFSOUND_FXapi,anduseFSOUND_SYSTEMCHANNELasthechannelidwhensettingparameters.

FSOUND_INIT_USEDEFAULTMIDISYNTH0x0001/*Win32only-CausesMIDIplaybacktoforcesoftwaredecoding.*/

FSOUND_INIT_GLOBALFOCUS

0x0002/*Win32only-ForDirectSoundoutput-soundisnotmutedwhenwindowisoutoffocus.*/

FSOUND_INIT_ENABLESYSTEMCHANNELFX

0x0004/*Win32only-ForDirectSoundoutput-AllowsFSOUND_FXapitobeusedonglobalsoftwaremixeroutput!(useFSOUND_SYSTEMCHANNELaschannelid)*/

FSOUND_INIT_ACCURATEVULEVELS

0x0008/*ThislatencyadjustsFSOUND_GetCurrentLevels,butincursasmallcpuandmemoryhit*/

FSOUND_INIT_PS2_DISABLECORE0REVERB

0x0010/*PS2only-DisablereverbonCORE0(SPU2voices00-23)toregainSRAM*/0x0020/*PS2only-Disable

FSOUND_INIT_PS2_DISABLECORE1REVERB reverbonCORE1(SPU2voices24-47)toregainSRAM*/

FSOUND_INIT_PS2_SWAPDMACORES

0x0040/*PS2only-BydefaultFMODusesDMACH0formixing,CH1foruploads,thisflagswapsthemaround*/

FSOUND_INIT_DONTLATENCYADJUST

0x0080/*Callbacksarenotlatencyadjusted,andarecalledatmixtime.Alsoinformationfunctionsareimmediate*/

FSOUND_INIT_GC_INITLIBS 0x0100/*GConly-InitializesGCaudiolibraries*/

FSOUND_INIT_STREAM_FROM_MAIN_THREAD

0x0200/*Turnsofffmodstreamerthread,andmakesstreamingupdatefromFSOUND_Updatecalledbytheuser*/

FSOUND_INIT_PS2_USEVOLUMERAMPING0x0400/*PS2only-Turnsonvolumerampingsystemtoremovehardwareclicks.*/

FSOUND_INIT_DSOUND_DEFERRED

0x0800/*Win32only-ForDirectSoundoutput.3DcommandsarebatchedtogetherandexecutedatFSOUND_Update.*/

FSOUND_INIT_DSOUND_HRTF_LIGHT

0x1000/*Win32only-ForDirectSoundoutput.FSOUND_HW3Dbuffersuseaslightlyhigherqualityalgorithmwhen3dhardwareaccelerationisnotpresent.*/

FSOUND_INIT_DSOUND_HRTF_FULL

0x2000/*Win32only-ForDirectSoundoutput.FSOUND_HW3Dbuffersusefullquality3dplaybackwhen

3dhardwareaccelerationisnotpresent.*/

FSOUND_INIT_XBOX_REMOVEHEADROOM

0x4000/*XBoxonly-Bydefaultdirectsoundattenuatesallsoundby6dbtoavoidclipping/distortion.CAUTION.Ifyouusethisflagyouareresponsibleforthefinalmixtomakesureclipping/distortiondoesn'thappen.*/

FSOUND_INIT_PSP_SILENCEONUNDERRUN

0x8000/*PSPonly-Ifstreamsskip/stutterwhendeviceispoweredon,eitherincreasestreambuffersize,orusethisflaginsteadtoplaysilencewhiletheUMDisrecovering.*/

SeeAlso

FSOUND_GetCurrentLevels,FSOUND_Init,FSOUND_SetBufferSize,FSOUND_Update


[APIfunction]

FSOUND_GetFreeHWRam

ReturnfreeSRAMandIOPramafterorbeforeFMODisinitialized.

signedcharF_APIFSOUND_GetFreeHWRam(int*spu2ram,int*iopram);

Parameters

spu2ram PointertovariabletocontainfreeSPU2ram.iopram PointertovariabletocontainfreeIOPram.

ReturnValue


Remarks

FreeIOPrammeansIOPmemoryfreebeforeinitializingFMOD,orafterFMODmemorypoolsizeisspecifiedwithFSOUND_SetMemorySystemandFSOUND_Init.Forexampleona2mbIOPsystem,beforeFSOUND_Inititmightreturn2mb,andafter,ifyoucallFSOUND_Initwithamemorypoolsizeof1.5mb,thisfunctionwouldreturn.5mb.ThisisdifferenttothevaluesreturnedbyFSOUND_GetMemoryStats,whichisthememoryinformationwithinthat1.5mbpool.------------------NoteusingFSOUND_INIT_DISABLE_CORE0_REVERBor/andFSOUND_INIT_DISABLE_CORE1_REVERBwillregainSPU2ram,butdisableshardwarereverb.Usethisifyouwanttofitmoresoundsinandarenotworriedaboutreverb.------------------

ThisfunctioncanbecalledbeforeorafterFSOUND_Init.___________________Supportedonthefollowingplatforms:PlayStation2

SeeAlso

FSOUND_GetMemoryStats,FSOUND_Init,FSOUND_SetMemorySystem


[APIfunction]

FSOUND_GetSpeakerMode

Getsthemodeforcurrentlysetspeakermode.

unsignedintF_APIFSOUND_GetSpeakerMode();

ReturnValue

void

Remarks


SeeAlso

FSOUND_SetPanSeperation,FSOUND_SetSpeakerMode,FSOUND_SPEAKERMODES


[APIfunction]

FSOUND_IOP_Alloc

AllocatesIOPRam

void*F_APIFSOUND_IOP_Alloc(intlength);

Parameters

length LengthinbytesofIOPRAMtobeallocated.

ReturnValue

TheIOPaddressofthedataallocated.Thisisnotdirectlyaddressable.TheonlywaytogetdatatothisvalueistoDMAit.FSOUND_SendDatawillDMAdatafromtheEEtotheIOP.

Remarks

ThememoryallocatedistakenfromFMOD'smemorypoolusingFMOD'sinternalmemorymanager.ThepoolofmemorythisistakenfromisspecifiedwithFSOUND_SetMemorySystem.___________________Supportedonthefollowingplatforms:PlayStation2

SeeAlso

FSOUND_IOP_Free,FSOUND_SendData,FSOUND_SetMemorySystem


[APIfunction]

FSOUND_IOP_Free

FreesablockofIOPram.

voidF_APIFSOUND_IOP_Free(void*iopptr);

Parameters

data IOPpointertobefreed.MusthavebeenallocatedwithFSOUND_IOP_Alloc

ReturnValue

void

Remarks

___________________Supportedonthefollowingplatforms:PlayStation2

SeeAlso

FSOUND_IOP_Alloc


[APIfunction]

FSOUND_SendData

DMA'sdatafromEEtoIOP.ForDSPandstreamcallbacksusethisfunctiontogetdatatotheIOP.

signedcharF_APIFSOUND_SendData(void*iopaddr,void*eeaddr,intlenbytes,signedcharwait,void(*callback)(void*param),void*param);

Parameters

iopaddr destinationIOPAddress.eeaddr sourceEEAddress.lenbytes Lengthofdatablockinbytes.

wait TRUEorFALSEvaluetodeterminewethertowaitonthecompletionofDMAornot.Setto0fromcallbacks.

callback CallbackforcompletionofDMA.param UserdatathatwillgetpassedbacktotheendofDMAcallback.

ReturnValue

srcandlenbytesmustbe16bytealigned.

Remarks

Usuallyonlyusedwithauserstreamcallback,togetyouruserdatatotheIOPaddressthatFMODprovided.YoucanalsoallocatesomeIOPmemorywithFSOUND_IOP_Allocifsodesired.___________________Supportedonthefollowingplatforms:PlayStation2

SeeAlso

FSOUND_IOP_Alloc,FSOUND_Sample_Lock,FSOUND_Stream_Create,FSOUND_STREAMCALLBACK


[APIfunction]

FSOUND_SetDiskBusy

TellsFMODthattheuserisaccessingthedisk,sothatFMODwillwaituntilitisfinishedwithit.ThisisessentialforoptimalgamefileaccessincooperationwithFMOD.

voidF_APIFSOUND_SetDiskBusy(signedchardiskbusy);

Parameters

diskbusy TRUEtotellFMODthecallerisabouttoaccessthedisk.FALSEtotellFMODithasfinishedwiththedisk.

ReturnValue

Remarks

ItisrecommendedtowrapFSOUND_SetDiskBusy(TRUE)andFSOUND_SetDiskBusy(FALSE)aroundallgamefileaccessfunctions.--------------------NoteiftheuserhaltsthediskaccessforlongerthanthebuffersizesetbyFSOUND_Stream_SetBufferSize.Evenlessthanthiscancauseskippingorcorruptedsound,duetoseekingandtheactualtimeittakestodotheaudiostreamreadinthestreamsubsystem.Toavoidthisitisrecommendedtosplitgamereadsupintochunks,toallowFMODaccesstothediskperiodically.--------------------ThisfunctionwillblockuntilFMODisnotusingthediskanymore.___________________Supportedonthefollowingplatforms:PlayStation2

SeeAlso

FSOUND_IsDiskBusy,FSOUND_SetDiskBusy,FSOUND_Stream_SetBufferSize


[APIfunction]

FSOUND_SPU2_Alloc

AllocatesSPU2Ram

void*F_APIFSOUND_SPU2_Alloc(intlength);

Parameters

length LengthinbytesofSPU2soundRAMtobeallocated.

ReturnValue

AnIOPbasedhandlefortheSPU2ramblock.

Remarks

Thisfunctionismainlyusedtoreservememoryforpurposessuchas3rdpartylibrariesneedingmemoryfortheirownspu2use.DONOTusethisastheoffsetintospu2ram!UseFSOUND_SPU2_GetRawAddresstogetthespu2offsetintosoundramfromthishandle.-----------TheSPU2has2mboframavailable,unlessreverbisactivatedonbothcores,thenitisless.YoucandisablereverbusingFSOUND_INIT_PS2_DISABLECORE0REVERBandFSOUND_INIT_PS2_DISABLECORE1REVERBwithFSOUND_Init.___________________Supportedonthefollowingplatforms:PlayStation2

SeeAlso

FSOUND_Init,FSOUND_SPU2_Free,FSOUND_SPU2_GetRawAddress


[APIfunction]

FSOUND_SPU2_Free

FreesSPU2Ram

voidF_APIFSOUND_SPU2_Free(void*iopptr);

Parameters

iopptrHandletofreegeneratedbyFSOUND_SPU2_Alloc.

ReturnValue

void

Remarks

PassthevaluefromFSOUND_SPU2_Alloc,NOTthevaluefromFSOUND_SPU2_GetRawAddress.___________________Supportedonthefollowingplatforms:PlayStation2

SeeAlso

FSOUND_SPU2_Alloc,FSOUND_SPU2_GetRawAddress


[APIfunction]

FSOUND_SPU2_GetRawAddress

GetstherawSPU2offsetinsidetheSPU2memoryspacefromthehandlereturnedfromFSOUND_SPU2_Alloc

unsignedintF_APIFSOUND_SPU2_GetRawAddress(void*iopptr);

Parameters

iopptr PointertotheIOPbasedsoundramhandle.

ReturnValue

TheSPU2addressofthedataallocated.Thisisnotdirectlyaddressable.TheonlywaytogetdatatothisaddressistoDMAitfromtheEEtotheIOPfirst,thenfromtheIOPtoSRAM.

Remarks

___________________Supportedonthefollowingplatforms:PlayStation2

SeeAlso

FSOUND_SPU2_Alloc,FSOUND_SPU2_Free


[APIfunction]

FSOUND_Stream_Net_SetTimeout

Setsthetimeoutforinternetstreams.

signedcharF_APIFSOUND_Stream_Net_SetTimeout(inttimeout);

Parameters

timeout Thetimeoutvalueinms

ReturnValue


Remarks


SeeAlso

FSOUND_Stream_Close,FSOUND_Stream_Net_GetBufferProperties,FSOUND_Stream_Net_GetLastServerStatus,FSOUND_Stream_Net_GetStatus,FSOUND_Stream_Net_SetBufferProperties,FSOUND_Stream_Net_SetMetadataCallback,FSOUND_Stream_Net_SetProxy,FSOUND_Stream_Open,FSOUND_Stream_Play,FSOUND_Stream_Stop


[APIfunction]

FSOUND_Stream_OpenFromHandle

FSOUND_STREAM*F_APIFSOUND_Stream_OpenFromHandle(HANDLEhandle,unsignedintmode);

Parameters

handle ApointertoafileHANDLEtypethatwasretrievedfromXOpenSoundtrackSong.

ReturnValue

Onsuccess,avalidstreamhandleisreturned.Onfailure,NULLisreturned.

Remarks

UsetheXDKfunctionsXFindFirstSoundtrack,XFindNextSoundtrack,XGetSoundtrackSongInfoandXOpenSoundtrackSongtoenumerateandopenWMAfilessavedontothedashboardbyusers.___________________Supportedonthefollowingplatforms:XBox

SeeAlso

FSOUND_Stream_Close.,FSOUND_Stream_Open


[APIfunction]

sceSifAddCmdHandler

Foradvancedusersonly.OnlyusedifusersaregettingconflictswithFMOD'scommandhandlerwhenwritingIOPmodulesoftheirownorusingothermiddlewarethatusesSIFCMD.ThisfunctiontellsFMODabouttheuser'sSIFCMDbufferthathasbeensetwithsceSifSetCmdBuffer,andtheindiciesintothatsceSifCmdDataarraythatFMODcanuse.TheusermayhavespecifiedaSIFcommandhandleroftheirownbeforecallingFSOUND_InitandloadingFMOD.IRXwhensettinguptheirownIOP<->EEcommunication.ItsimplyenablesFMODtoknowthesize,andwhatindiciesintothesceSifCmdDataarraytheuserhassetthatFMODcanuse.Itallowstheuser'sappandFMODtosharethebufferthattheuserhascreated.FMODuses2sifhandlers.Amainoneandsecondaryone.

sceSifAddCmdHandler(YOURHANDLERINDEX,yourhandler,NULL);

Parameters

buffersize ThesizeofthesceSifCmdDataarraythattheuserhasset.

bufferindexmain TheindexintotheusercreatedsceSifCmdDataarrayfortheprimaryFMODsifcmdhandler.

bufferindexsecondary TheindexintotheusercreatedsceSifCmdDataarrayforthesecondaryFMODsifcmdhandler.

ReturnValue

void

Remarks

FMODwillautomaticallyusethepreviouslysetcommandbuffer,assceSifSetCmdBufferreturnsthepreviouslysetbufferwhichFMODuses.Thisiswhyyoudonthavetopassintheactualbufferitself.-----------IMPORTANT!FMOD.IRXmustalsobenotifiedwhenitisinitialized!TheIOPsideofthecommandhandler,whichisinitializedwhenFMOD.IRXisloaded,mustalsobenotifiedoftheuser'sIOPsidebuffersizeandindicies.BypassingitascommandlineparameterwithsceSifLoadModule,youcandothis.Ifthisisnotdone,unexpectedresultsmayoccur.TheFMOD.IRXtakes3parameters.Theyaresimply3integersseperatedbyaspace.Parameter1isequalto'buffersize'Parameter2isequalto'bufferindexmain'Parameter3isequalto'bufferindexsecondary'------------HereisanexampleofusingsceSifLoadModuletonotifyFMOD.IRXofyourIOPsidesifCmdbuffersizeandcommandhandlerindex.sprintf(s,"49894721238404205",CMDBUFSIZE,FMODINDEXMAIN,FMODINDEXSECONDARY);//NOTE:mustbeformattedas3integersseperatedbyaspace.sceSifLoadModule("host0:api/fmod.irx",strlen(s),s);ThenlaterontheEEside,beforecallingFSOUND_Init,youwillcallthisfunction,ieFSOUND_SetSifCommandInfo(CMDBUFSIZE,FMODINDEXMAIN,FMODINDEXSECONDARY);Andbeforeanyofthis,youwouldhavesetupyourowncommandhandlerwithsomethinglikethis.sceSifInitCmd();sceSifSetCmdBuffer(&yourcommandbuffer;

SeeAlso

FSOUND_Init


[Define]

FSOUND_REVERB_CHANNELFLAGS

ValuesfortheFlagsmemberoftheFSOUND_REVERB_CHANNELPROPERTIESstructure.

FSOUND_REVERB_CHANNELFLAGS_DIRECTHFAUTO 0x00000001/*Automaticsettingof'Direct'fromlistener*/

FSOUND_REVERB_CHANNELFLAGS_ROOMAUTO 0x00000002/*Automaticsettingof'Room'fromlistener*/

FSOUND_REVERB_CHANNELFLAGS_ROOMHFAUTO 0x00000004/*Automaticsettingof'RoomHF'duetodistancefromlistener*/

FSOUND_REVERB_CHANNELFLAGS_DEFAULT (FSOUND_REVERB_CHANNELFLAGS_DIRECTHFAUTO|FSOUND_REVERB_CHANNELFLAGS_ROOMAUTO|FSOUND_REVERB_CHANNELFLAGS_ROOMHFAUTO)

SeeAlso

FSOUND_REVERB_CHANNELFLAGS,FSOUND_REVERB_CHANNELPROPERTIES


[Define]

FSOUND_REVERB_FLAGS

ValuesfortheFlagsmemberoftheFSOUND_REVERB_PROPERTIESstructure.

FSOUND_REVERB_FLAGS_DECAYTIMESCALE 0x00000001/*'EnvSize'affectsreverberationdecaytime*/FSOUND_REVERB_FLAGS_REFLECTIONSSCALE 0x00000002/*'EnvSize'affectsreflectionlevel*/

FSOUND_REVERB_FLAGS_REFLECTIONSDELAYSCALE 0x00000004/*'EnvSize'affectsinitialreflectiondelaytime*/FSOUND_REVERB_FLAGS_REVERBSCALE 0x00000008/*'EnvSize'affectsreflectionslevel*/

FSOUND_REVERB_FLAGS_REVERBDELAYSCALE 0x00000010/*'EnvSize'affectslatereverberationdelaytime*/

FSOUND_REVERB_FLAGS_DECAYHFLIMIT 0x00000020/*AirAbsorptionHFaffectsDecayHFRatio*/FSOUND_REVERB_FLAGS_ECHOTIMESCALE 0x00000040/*'EnvSize'affectsechotime*/FSOUND_REVERB_FLAGS_MODULATIONTIMESCALE 0x00000080/*'EnvSize'affectsmodulationtime*/

FSOUND_REVERB_FLAGS_CORE0 0x00000100/*PS2Only-ReverbisappliedtoCORE0(hwvoices0-23)*/

FSOUND_REVERB_FLAGS_CORE1 0x00000200/*PS2Only-ReverbisappliedtoCORE1(hwvoices24-47)*/

FSOUND_REVERB_FLAGS_DEFAULT (FSOUND_REVERB_FLAGS_DECAYTIMESCALE|FSOUND_REVERB_FLAGS_REFLECTIONSSCALE|FSOUND_REVERB_FLAGS_REFLECTIONSDELAYSCALE|FSOUND_REVERB_FLAGS_REVERBSCALE|FSOUND_REVERB_FLAGS_REVERBDELAYSCALE|FSOUND_REVERB_FLAGS_DECAYHFLIMIT|FSOUND_REVERB_FLAGS_CORE0|FSOUND_REVERB_FLAGS_CORE1)

SeeAlso

FSOUND_REVERB_FLAGS,FSOUND_REVERB_PROPERTIES


[Define]

FSOUND_STATUS_FLAGS

Thesevaluesdescribetheprotocolandformatofaninternetstream.UseFSOUND_Stream_Net_GetStatustoretrievethisinformationforanopeninternetstream.

FSOUND_PROTOCOL_SHOUTCAST 0x00000001FSOUND_PROTOCOL_ICECAST 0x00000002FSOUND_PROTOCOL_HTTP 0x00000004FSOUND_FORMAT_MPEG 0x00010000FSOUND_FORMAT_OGGVORBIS 0x00020000

SeeAlso



[Enum]

FSOUND_FX_MODES

ThesevaluesareusedwithFSOUND_FX_EnabletoenableDirectX8FXforachannel.

Enumerators

FSOUND_FX_CHORUSFSOUND_FX_COMPRESSORFSOUND_FX_DISTORTIONFSOUND_FX_ECHOFSOUND_FX_FLANGERFSOUND_FX_GARGLEFSOUND_FX_I3DL2REVERBFSOUND_FX_PARAMEQFSOUND_FX_WAVES_REVERBFSOUND_FX_MAX

SeeAlso

FSOUND_FX_Disable,FSOUND_FX_Enable,FSOUND_FX_SetChorus,FSOUND_FX_SetCompressor,FSOUND_FX_SetDistortion,FSOUND_FX_SetEcho,FSOUND_FX_SetFlanger,FSOUND_FX_SetGargle,FSOUND_FX_SetI3DL2Reverb,FSOUND_FX_SetParamEQ,FSOUND_FX_SetWavesReverb


[Enum]

FSOUND_SPEAKERMODES

ThesearespeakertypesdefinedforusewiththeFSOUND_SetSpeakerModecommand.Note-OnlyreliablyworkswithFSOUND_OUTPUT_DSOUNDorFSOUND_OUTPUT_XBOXoutputmodes.OtheroutputmodeswillonlyinterpretFSOUND_SPEAKERMODE_MONOandseteverythingelsetobestereo.UsingeitherDolbyDigitalorDTSwillusewhatever5.1digitalmodeisavailableifdestinationhardwareisunsure.

Enumerators

FSOUND_SPEAKERMODE_DOLBYDIGITAL/*DolbyDigitalOutput(XBOXorPConly).*/

FSOUND_SPEAKERMODE_HEADPHONES /*Thespeakersareheadphones.*/

FSOUND_SPEAKERMODE_MONO /*Thespeakersaremonaural.*/

FSOUND_SPEAKERMODE_QUAD /*Thespeakersarequadraphonic.*/

FSOUND_SPEAKERMODE_STEREO/*Thespeakersarestereo(defaultvalue).*/

FSOUND_SPEAKERMODE_SURROUND /*Thespeakersaresurroundsound.*/

FSOUND_SPEAKERMODE_DTS /*DTSoutput(XBOXonly).*/

FSOUND_SPEAKERMODE_PROLOGIC2

/*DolbyPrologic2.Playstation2andGamecubeonly.PlayStation2doesntsupportinteriorpanning,butsupports48voices

simultaneously.*/

FSOUND_SPEAKERMODE_PROLOGIC2_INTERIOR

/*DolbyPrologic2.Playstation2andGamecubeonly.PlayStation2doessupportinteriorpanning,butonlysupports24voicessimultaneously.*/

SeeAlso

FSOUND_SetSpeakerMode


[Enum]

FSOUND_STREAM_NET_STATUS

Statusvaluesforinternetstreams.UseFSOUND_Stream_Net_GetStatustogetthecurrentstatusofaninternetstream.

Enumerators

FSOUND_STREAM_NET_NOTCONNECTED /*Streamhasn'tconnectedyet*/

FSOUND_STREAM_NET_CONNECTING /*Streamisconnectingtoremotehost*/

FSOUND_STREAM_NET_BUFFERING /*Streamisbufferingdata*/FSOUND_STREAM_NET_READY /*Streamisreadytoplay*/

FSOUND_STREAM_NET_ERROR /*Streamhassufferedafatalerror*/

SeeAlso



[Enum]

FSOUND_TAGFIELD_TYPE

Describesthetypeofaparticulartagfield.

Enumerators

FSOUND_TAGFIELD_VORBISCOMMENT /*Avorbiscomment*/FSOUND_TAGFIELD_ID3V1 /*PartofanID3v1tag*/FSOUND_TAGFIELD_ID3V2 /*AnID3v2frame*/FSOUND_TAGFIELD_SHOUTCAST /*ASHOUTcastheaderline*/FSOUND_TAGFIELD_ICECAST /*AnIcecastheaderline*/

FSOUND_TAGFIELD_ASF /*AnAdvancedStreamingFormatheaderline*/

SeeAlso

FSOUND_Stream_FindTagField,FSOUND_Stream_GetNumTagFields,FSOUND_Stream_GetTagField


Documents

Thank you for downloading FMOD music and sound effects ... · Thank you for downloading FMOD music and sound effects system. ... You need to have uses FMOD in your source code somewhere