History: MogreFreeSL

Source of version: 17 (current)

!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 was originally a port of the OgreFreeSL wrapper.

%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 areas or caves)
*Contains a SoundObject memory manager
*Can play WAV and Ogg files
*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 MogreFreeSL
You can get the latest MogreFreeSL files from [http://bitbucket.org/mogre/mogreaddons|here]. This wiki entry will always use the latest version. Click the "get source" icon in the top-right corner (the piece of paper with the blue arrow just below "forks/queues"), then choose the compression method of your choice.

!Compiling (Optional)
__If you don't need/want to compile MogreFreeSL yourself, a library built against the latest version of MOGRE is available under MogreFreeSL\Libraries.__

Compiling MogreFreeSL is very simple. Load the solution (.sln) file under MogreFreeSL\Source 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. A library will be created in the bin folder. 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 "MogreFreeSL Properties..." Select the "Build" tab, and check the box next to "XML Documentation File:" When you next build the project, a file called "MogreFreeSL.XML" will be created along with MogreFreeSL.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\Libraries 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
To shorten your code a bit, assign SoundManager.Instance to a variable, like so:

{CODE(wrap="1", colors="c#")}SoundManager smgr = SoundManager.Instance;{CODE}

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(smgr.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 FSL_SOUND_SYSTEM that you wish. This example uses FSL_SS_EAX2:

{CODE(wrap="1", colors="c#")}smgr.InitializeSound(FSL_SOUND_SYSTEM.FSL_SS_EAX2, cam);{CODE}

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

{CODE(wrap="1", colors="c#")}AmbientSound sound = smgr.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 a SoundEntity (a sound that can move), do this:

{CODE(wrap="1", colors="c#")}SoundEntity soundEntity = smgr.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#")}soundEntity.Play();{CODE}

To change the rate at which a SoundEntity'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 SoundEntity's volume starts decreasing, and the Maximum Distance is the distance from the camera at which the SoundEntity will be at its quietest. Set them thusly:

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

!!!Advanced Usage

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

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

soundEntity.SetSpeed(.5f);

smgr.SetSpeedAllSounds(.5f);{CODE}

!Links
[http://www.ogre3d.org/addonforums/viewtopic.php?f=8&t=13035|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]
History: MogreFreeSL

Source of version: 17 (current)

Search by Tags

Latest Changes

Search

Online Users
