IrrKlang for MOGRE         Embedding sound
Page actions
Print

What is IrrKlang?

IrrKlang is a Sound library developed by Ambiera.

It has a stable .NET wrapper provided by the original developers. So it's usable with Mogre.

Examples and documentations are on the project website.

Forum quote:
There are a couple of references around on the forums and on the wiki that mention it can be used in C# which is basically the same thing as saying it can be used with Mogre.



License

IrrKlang is free for non-commercial use. For commercial use the license fee will be between 65€ (~$85) for low budged projects and up to 490€ (~$640).

Usage

Since IrrKlang has a C# binding written by the original developers, integrating it with Mogre is very simple.

Installation

There is no particular installation required for IrrKlang. Simply go to the download page and download the library. In the downloaded zip file under the bin folder you will find versions of the library for .NET 1.0, .NET 2.0, and .NET 4.0. Simply pick the version you wish to use and copy the .dll files to your project. Add a reference to your project to the .dll file called something like irrKlang.NET*.dll.

Initialization

Initializing IrrKlang is very simple, all that is required is creating an instance of the ISoundEngine class: 

ISoundEngine engine = new ISoundEngine();


Playing a Simple Sound


Playing a simple sound, i.e not a surround sound, or a sound coming equally from all direcions - is very simple. All we need to do is call the Play2D method of the engine and point it to the sound file to play: 

engine.Play2D("ophelia.mp3");

  • Play2D() is actually badly named, it isn't really doing any 2D or any kind of dimensional sound effects. It is just a simple way of playing a sound file using IrrKlang.
  • "ophelia.mp3" is found in the media folder of the irrKlang zip file. You will need to copy it to your bin folder.


Here is a complete example of both initializing the engine and playing a 2D sound: 

using System;
using IrrKlang;

namespace HelloWorld
{
    class Example
    {
        [STAThread]
        static void Main(string[] args)
        {
            // start up the engine
            ISoundEngine engine = new ISoundEngine();

            // play a sound file
            engine.Play2D("ophelia.mp3");

            // wait until user presses OK to end application
            System.Windows.Forms.MessageBox.Show("Playing, press ok.");

        } // end main()
    } // end class
} // end namespace

  • For this example to work correctly you will need to reference System.Windows.Forms in your project.


A Word About 3D Vectors

The IrrKlang library provides its own Vector3D class which is used for surround sounds. Alternatively the methods that accept a Vector3D instance as parameters will have overloaded versions that accept x, y and z coordinates as plain float values.

This means that you have two choices when using IrrKlang from Mogre:

  1. Using the x/y/z falvours of those methods taking take X, Y and Z values from the Mogre Vector3 objects.
  2. Translating Mogre.Vector3 to IrrKlang.Vector3D.


If you choose to use the latter, you might find the following extension method useful: 

namespace Example
{
    static class Extensions
    {
        public static Vector3D ToIrrKlangVector3D(this Mogre.Vector3 v)
        {
            return new Vector3D(v.x, v.y, v.z);
        }
    }
}


Playing a Surround Sound

Playing a surround sound requires a bit more work than playing a simple sound but still is very simple to do. This is performed by using the IrrKlang Play3D() method instead of the Play2D() method. The Play3D() accepts the coordinates of the origin of the sound. This, coupled with telling the IrrKlang engine the position and direction of the listener (usually those of the camera in Mogre), allows the IrrKlang library to compute the direction and distance of the sound.

Let's look at an example. In this example we will use the Mogre Wiki Tutorial Framework. To get started do the following:

  1. Start a new clean project of the tutorials framework
  2. Add the IrrKlang library to it using the instructions above.
  3. Copy the sample sound files from the IrrKlang zip file to a sub-folder called "sounds" under your Media folder.


We'll create a simple scene with an Ogre head that the sound will originate from to provide ourselves with some orientation. Then we will see how the sound changes direction as we move the camera around.

NOTE: This example assumes that your sound hardware supports surround sound. You can still run it without such hardware, but you will not get the sound direction and distance effects.

Add a using directive for the IrrKlang library at the top of the Tutorial.cs file under the other using directives. 

using IrrKlang;


We will be using the extension method shown above to make the code cleaner and easier to use. Add the following code to your code file before or after the Tutorial class. 

static class Extensions
{
    public static Vector3D ToIrrKlangVector3D(this Mogre.Vector3 v)
    {
        return new Vector3D(v.x, v.y, v.z);
    }
}


Add the following code to your CreateScene method so that it creates a simple scene with a small Ogre head inside it: 

protected override void CreateScene()
{
    var ent = mSceneMgr.CreateEntity("ogreHead.mesh");
    var node = mSceneMgr.RootSceneNode.CreateChildSceneNode(new Vector3(0, 50, 0));
    node.AttachObject(ent);
    node.SetScale(0.3f, 0.3f, 0.3f);
}


Now we need to initialize the IrrKlang library. Add the following code to the CreateScene method to initialize the IrrKlang sound engine and to set a sound originating from the Ogre head: 

mSoundEngine = new ISoundEngine();
mSoundEngine.SetListenerPosition(mCamera.Position.ToIrrKlangVector3D(), mCamera.Direction.ToIrrKlangVector3D());

ISound sound = mSoundEngine.Play3D("../../Media/sounds/bell.wav", node.Position.ToIrrKlangVector3D(), true, false, StreamMode.AutoDetect);
sound.MinDistance = 5;


Note that the code above also sets the position of the listener to that of the camera when the scene starts. However, to get a realistic effect we must update the sound engine all the time telling it where the listener is (the camera) as it moves. Add the following code to your UpdateScene method: 

protected override void UpdateScene(FrameEvent evt)
{
    mSoundEngine.SetListenerPosition(mCamera.Position.ToIrrKlangVector3D(), mCamera.Direction.ToIrrKlangVector3D());
}


That's it. If you compile and run this code now, you should see a little Ogre head in the middle of the scene which appears to be the source of the song. Move around the scene and notice how the sound appears to originate from different directions as you rotate the camera and appears to come from far away or close by depending on how close your are to the Ogre head.

References

See Also

Alternative Sound Libraries:

History Source