History: MogreFreeSL

• «
• »

            !Introduction
MogreFreeSL is a MOGRE wrapper for [http://www.lukasheise.com/projects.html|the 3D FreeSL sound engine]. FreeSL (Free Sound Library) is a OpenAL wrapper. It includes the EAX 2.0 library for realistic audio environment simulations plus occlusion and obstruction.

MogreFreeSL allows you to use 3D sound with your MOGRE application. It is a port of the original OgreFreeSl wrapper. Not all of the FreeSL functions are wrapped.

%help% For questions, bug reports, etc. use this [http://www.ogre3d.org/addonforums/viewtopic.php?f=8&t=13035|forum topic]

{maketoc}

!Features 
*Based on OpenAL
*Supports EAX 2.0 (can simulate complex sound environments like underwater or caves)
*Contains a SoundObject memory manager
*Can play WAV and Ogg
*Can stream Ogg and AVI(PCM)
*Supports Zip Files (can load static sounds and EAX scripts from *.zip packages)
*Can be used with any .NET language

!Getting the source
The version of MogreFreeSL used in this wiki article is available [http://bitbucket.org/mogre/mogreaddons/changeset/eafcdfaf2263|here]. ([http://bitbucket.org/mogre/mogreaddons/get/eafcdfaf2263.zip|direct .zip download])

You can get the latest MogreFreeSL source from [http://bitbucket.org/mogre/mogreaddons|here].

Click "get source" in the top-right corner, then choose the compression method of your choice.

!Compiling
Compiling MogreFreeSL is very simple. Load the project file under MogreFreeSL\FSLOgreCS in Visual Studio. Replace the broken reference to Mogre with a reference to the version of Mogre you would like to use, either from the SDK or from your own source code compilation. Build the project in whatever configuration you want. You should now be able to reference MogreFreeSL and use it in your project.

!!Compiling Documentation
If you wish to use MogreFreeSL's built in code documentation, click "Project" in the toolbar and then select "FSLOgreCS Properties..." Select the "Build" tab, and check the box next to "XML Documentation File:" When you next build the project, a file called "FSLOgreCS.XML" will be created along with FSLOgreCS.dll in the build directory. Be sure that you copy this file wherever you copy the library, so that you may use the dynamic documentation.

!Using MogreFreeSL
!!Requirements
If you are using MogreFreeSL, please do not forget to copy & paste these dlls from the MogreFreeSL folder to your build folder first; failing to do so will cause your application to crash:
*alut.dll
*eax.dll
*EaxAc3.dll
*FreeSL.dll
*ogg.dll
*OpenAL32.dll
*vorbis.dll
*wrap_oal.dll

!!Initialization
The first step in using MogreFreeSL in your own application is to add a frame listener:

{CODE(wrap="1", colors="c#")}myRoot.FrameStarted += new Mogre.FrameListener.FrameStartedHandler(FSLSoundManager.Instance.FrameStarted);{CODE}

Now initialize the sound manager. You need to pass the sound manager the sound system enumeration and the camera you would like to use. Choose any FreeSL.FSL_SOUND_SYSTEM that you wish. This example uses FSL_SS_EAX2:

{CODE(wrap="1", colors="c#")}FSLSoundManager.Instance.smgr.InitializeSound(FreeSL.FSL_SOUND_SYSTEM.FSL_SS_EAX2, camera);
FSLSoundManager.Instance.GetListener().ZFlipped = true;
FreeSL.fslSetAutoUpdate(true);{CODE}

The second and third line fix issues with channel reversal and streaming, respectively.

!!Usage
You are now free to create Ambient and Object sounds. To create an ambient sound (a sound that will remain the same no matter where you go, like level music) do this:

{CODE(wrap="1", colors="c#")}FSLSoundObject sound = FSLSoundManager.Instance.CreateAmbientSound("file.ogg", "sound name", true, false);{CODE}

You can now play, pause, and stop the sound.

{CODE(wrap="1", colors="c#")}sound.Play();{CODE}

To create an object sound (a sound that can move), do this:

{CODE(wrap="1", colors="c#")}FSLSoundObject soundobject = FSLSoundManager.Instance.CreateSoundEntity("file.ogg", node, node.Name, true, false);{CODE}

__Make sure that your sound file is in mono. If it is not in mono, the 3D effect will not work.__
You can now play, pause, and stop the sound.

{CODE(wrap="1", colors="c#")}soundobject.Play();{CODE}

To change the rate at which a SoundObject's playback volume decreases as it moves away from the camera, you must set the Reference Distance and Maximum Distance.

The Reference Distance is the distance away from the camera at which the SoundObject's volume starts decreasing, and the Maximum Distance is the distance from the camera at which the SoundObject will be at its quietest. Set them thusly:

{CODE(wrap="1", colors="c#")}((FSLSoundEntity)soundobject).SetReferenceDistance(5);
((FSLSoundEntity)soundobject).SetMaxDistance(10);{CODE}

!!!Advanced Usage

Not sure what else to do with MogreFreeSL? Try one of these:

{CODE(wrap="1", colors="c#")}FreeSL.fslSetListenerEnvironmentPreset(FreeSL.FSL_LISTENER_ENVIRONMENT.FSL_ENVIRONMENT_UNDERWATER);

soundobject.SetSpeed(.5f);

FreeSL.fslSoundSetSpeedAllSounds(.5f);{CODE}

!Links
[http://www.ogre3d.org/addonforums/viewtopic.php?f=8&t=13035&start=15|MogreFreeSL thread]
[http://www.ogre3d.org/phpBB2addons/viewtopic.php?t=2799|Old MogreFreeSL thread]
[http://www.ogre3d.org/phpBB2/viewtopic.php?t=22679|Original OgreFreeSL]
[http://www.lukasheise.com/projects.html|FreeSL website]