Libraries  »  Alternative Languages  »  MOGRE  »  Mogre Add-ons  »  MogreFreeSL

Introduction

MogreFreeSL is a MOGRE wrapper for 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.

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

You can get the latest MogreFreeSL source from 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:

myRoot.FrameStarted += new Mogre.FrameListener.FrameStartedHandler(FSLSoundManager.Instance.FrameStarted);

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:

FSLSoundManager.Instance.smgr.InitializeSound(FreeSL.FSL_SOUND_SYSTEM.FSL_SS_EAX2, camera);
FSLSoundManager.Instance.GetListener().ZFlipped = true;
FreeSL.fslSetAutoUpdate(true);

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:

FSLSoundObject sound = FSLSoundManager.Instance.CreateAmbientSound("file.ogg", "sound name", true, false);

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

sound.Play();

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

FSLSoundObject soundobject = FSLSoundManager.Instance.CreateSoundEntity("file.ogg", node, node.Name, true, false);

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.

soundobject.Play();

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:

((FSLSoundEntity)soundobject).SetReferenceDistance(5);
((FSLSoundEntity)soundobject).SetMaxDistance(10);

Advanced Usage

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

FreeSL.fslSetListenerEnvironmentPreset(FreeSL.FSL_LISTENER_ENVIRONMENT.FSL_ENVIRONMENT_UNDERWATER);
 
soundobject.SetSpeed(.5f);
 
FreeSL.fslSoundSetSpeedAllSounds(.5f);

Links

MogreFreeSL thread
Old MogreFreeSL thread
Original OgreFreeSL
FreeSL website