Positional Audio Update

Greetings, true believers!

What have I done?!? I've updated T2D's audio system, that's what.

The Audio Listener

With this update, you may choose which SceneWindow will act as the AudioListener (the ears of the audio system).

MySceneWindow.setAudioListener(true);

This simply raises a flag which updates the AudioListener position with the camera position. It does not handle camera zooming as this behavior requires many case-by-case tweaks depending on the effect you want to achieve.

WARNING
Users have to manually enable this functionality through script. Having more than one SceneWindow act as the listener will cause all kinds of weird behaviors so make sure to manage this thoroughly if you use multiple SceneWindows in your project.

SceneObject.playSound()

If you remember a few months back, Mike Lilligreen had implemented Audio Emitters; a good idea but I found it a bit too complicated to use.

My solution? Simply call the following Console function.

MySceneObject.playSound("ToyAssets:SuperCoolSoundAssetID", My_AudioDescription);

This will play the sound directly at the sceneobject's position. What's more, the sound will move along with the object. You don't even need to specify an AudioDescription, it will default to a basic 3d sound.

If the sound is not looping (a one-shot sound), it will be automagically deleted when done playing. If the sound is looping (an engine sound, for instance) it will be deleted when the sceneobject is deleted.

In order to manually stop a looping sound, users must call the following function, which takes the index of the sound as an argument :

MySceneObject.stopSound(2);

If your sceneobject is playing only one sound, its index will be 0. If you choose to play multiple sounds at once on a single object, you will use getSoundsCount to retrieve how many sounds are currently playing on this object :

%count = MySceneObject.getSoundsCount();

and then access individual sound handles via getSoundatIndex

%handle = MySceneObject.getSoundatIndex(2);

Once you have the handle for a sound, you can perform any OpenAL operation on it.

Added Bonus : Doppler Effect!
When an object moves past the camera at a high enough velocity, you will hear its pitch change accordingly.

But...what about audio emitters?

In order to have an Audio Emitter, you simply need to create a SceneObject(without an Image/animation) and call the above-mentioned PlaySound function on it with a Looping AudioDescription (see below).

Audio Debug Mode

Taking another page from Mike Lilligreen's legacy, I have added a simple visualization mode for audio sources played using the above-mentioned system.

MyScene.setDebugOn("audio");

The debug only illustrates the MaxDistance and ReferenceDistance as circles. While OpenAL (and thus T2D) supports Directional sounds (sounds emitted in a cone rather than in a circle), the visualization does not illustrate this.

Audio Descriptions

Going back to TGB's way of doing things, I've reintroduced AudioDescriptions to the engine.
An AudioDescription object can be created anywhere in script and will define the various characteristics of a sound, especially when it comes to 3d audio properties.

new AudioDescription(MY_ADESC){
   is3D = true;
   isLooping = true;
   ReferenceDistance = 25.0;
   MaxDistance = 100.0;
   };

Easiest way to use these is to create a separate script file which defines all required AudioDescriptions and is executed via exec

Notes on usage

Off screen one-shots
Bear in mind that OpenAL performs automatic culling of sounds which should not be heard.
If a non-looping sound is started outside of the listener's range, it will not be created.
You can easily circumvent this by having an AudioDescription with a larger Maximum Range.

Mutliple sounds
By default, the OpenAL implementation will detect how many audio sources can be played at the same time. The default is 16. Bear in mind that this depends on your audio hardware.

Also, loading all sounds at once will cause framerate stutters, even if they are preloaded.
One way to solve this is by spreading out the creation code for your objects by 20-50 milliseconds using scheduling functions.

Having multiple sounds at maximum volume (1.0) directly in front of the Listener will cause distortion.

-Stereo or Mono?-
If you plan to use sounds in 3d space, make sure that these sounds are monophonic. Trying to pan stereo sounds will cause glitches and might damage your audio equipment.

3d sounds = mono

Music & UI SFX = stereo.
--------------------------------------------------

Your move!

Now, I ask you to test this out in your projects to iron out bugs and special cases.
Have a good idea about extending the system? The next step is yours to take!

What? You need suggestions? Sheesh, do I have to do everything for you? :)

OpenAL1.1

For YEARS, OpenAL developer support has been close to nonexistant. In Late 2015, OpenAL.org got a full revamp along with easier-to-find documentation and the new OpenAL 1.1 spec.

If any of you are up for a challenge, check into updating the OpenAL implementation. It won't change much for users but will allow the use of real-time filters and Reverb effects and other DSP without requiring the EAX extension. Now that would make for a sick update!

AudioMixer Toy

How about a simple module, similar to how the Console works, where users could visualize each VolumeChannel and adjust the volume of each one with sliders? How about VU meters? How about real-time waveform visualizations?

BPM Detection

How about implementing Beat-detection algorithms? Wouldn't it be awesome if Torque2D had easy-to-use features like this to make for musical games or just to add music-driven elements? (Answer : Yes it would be)

If you'd like to test it out, you can download the branch directly from my Git.

The pull request can be found here