Add pausing, seeking, and dynamic volume to Torque audio code

Download Code File

Description

This resource explains how to add pause, unpause, seek, and dynamic per-audio file volume changing to the audio classes in TGE, TGB, and TSE, controllable from within TorqueScript. Pausing/unpausing works on any streaming or non-streaming audio file TGE supports, seeking works on all seekable OGG files, and dynamic volume changes works on any audio file.

Note that this resource supports TGE 1.5, TGE 1.3, TGE 1.4, TSE, and TGB.


Installation Instructions

Integrating these changes requires modifying 11 source/header files in Torque. There are two ways of implementing these changes: via replacing the affected files on your system with the versions included in the zip file attached to this resource, or by manually merging in the changes yourself. I describe both procedures below:

File replacement for TGE 1.5, TGE 1.4, TGE 1.3, and TGB.
1) Simply place the following files located in the zip file into the engine\audio folder:
* audio.cc
* audioBuffer.cc
* audioFunctions.cc
* audioStreamSource.h
* oggMixedStreamSource.cc
* oggMixedStreamSource.h
* vorbisStreamSource.cc
* vorbisStreamSource.h
* wavStreamSource.cc
* wavStreamSource.h

2) Simply place the following files located in the TGE 1.4 directory of the zip file into the engine\platform folder:
* platformAudio.h

3) Recompile Torque and that's it!


File replacement for TSE
1) Simply place the following files located in the TGE 1.3 directory of the zip file into the engine\audio folder:
* audio.cc
* audioBuffer.cc
* audioFunctions.cc
* audioStreamSource.h
* vorbisStreamSource.cc
* vorbisStreamSource.h
* wavStreamSource.cc
* wavStreamSource.h

2) Rename each .cc file to .cpp, replacing any previous existing .cpp files!

3) Simply place the following files located in the zip file into the engine\platform folder:
* platformAudio.h

4) Recompile Torque and that's it!

Manual integration for TGE 1.5 and TGE 1.4
1) Modify engine\audio\audio.cc and insert the following code after the definition of the alxStopAll() function:

bool alxIsPaused(AUDIOHANDLE handle)
{
   if(handle == NULL_AUDIOHANDLE)
      return(false);

   U32 idx = alxFindIndex(handle);
   if(idx == MAX_AUDIOSOURCES)
      return(false);

   ALint state = 0;
   alGetSourcei(mSource[idx], AL_SOURCE_STATE, &state);
   return(state == AL_PAUSED);
}

void alxPauseAll()
{
   S32 i;

   for(i = mNumSources - 1; i >= 0; i--)
      if(mHandle[i] != NULL_AUDIOHANDLE)
         alxPause(mHandle[i]);
}

void alxPause(AUDIOHANDLE handle)
{
   if (handle == NULL_AUDIOHANDLE)
      return;
      
   ALuint source = alxFindSource(handle);
   alSourcePause(source);
}

void alxUnpauseAll()
{
   S32 i;

   for(i = mNumSources - 1; i >= 0; i--)
      if(mHandle[i] != NULL_AUDIOHANDLE)      
         alxUnpause(mHandle[i]);
}

void alxUnpause(AUDIOHANDLE handle)
{
   if (handle == NULL_AUDIOHANDLE)
      return;
      
   ALuint source = alxFindSource(handle);
   alSourcePlay(source);
}

bool alxSetVolume(AUDIOHANDLE handle, F32 volume)
{
   if (handle == NULL_AUDIOHANDLE)
      return false;

   U32 idx = alxFindIndex(handle);
   if (idx == MAX_AUDIOSOURCES)
      return false;

   mSourceVolume[idx] = volume;

   F32 new_volume = mClampF(mSourceVolume[idx] * mAudioTypeVolume[mType[idx]] * mMasterVolume, 0.f, 1.f);
   alSourcef(mSource[idx], AL_GAIN, Audio::linearToDB(new_volume));

   return true;
}

F32 alxGetVolume(AUDIOHANDLE handle)
{
   if (handle == NULL_AUDIOHANDLE)
      return 0.0f;

   U32 idx = alxFindIndex(handle);
   if (idx == MAX_AUDIOSOURCES)
      return 0.0f;

   return mSourceVolume[idx];
}

F32 alxGetStreamPosition( AUDIOHANDLE handle )
{
   if(handle == NULL_AUDIOHANDLE)
      return -1.f;

   StreamingList::iterator itr = mStreamingList.findImage(handle);
   if( !itr )
      return -1.f;

   return (*itr)->getElapsedTime();
}

F32 alxGetStreamDuration( AUDIOHANDLE handle )
{
   if(handle == NULL_AUDIOHANDLE)
      return -1.f;

   StreamingList::iterator itr = mStreamingList.findImage(handle);
   if( !itr )
      return -1.f;

   return (*itr)->getTotalTime();
}

bool alxSeekToStreamPosition( AUDIOHANDLE handle, F32 seconds)
{
   if(handle == NULL_AUDIOHANDLE)
      return false;
      
   StreamingList::iterator itr = mStreamingList.findImage(handle);
   if( !itr )
      return false;
   
   return (*itr)->seekToTime(seconds);
}

Search for the function alxIsValidHandle(AUDIOHANDLE handle) and replace this line:

return(state == AL_PLAYING);

with this:

return(state == AL_PLAYING || state == AL_PAUSED);

Search for the function alxUpdateTypeGain(U32 type) and replace this line:

if(state == AL_PLAYING)

with this:

if(state == AL_PLAYING || state == AL_PAUSED)

Search for the function alxGatherMetrics() and replace this line:

if(state == AL_PLAYING)

with this:

if(state == AL_PLAYING || state == AL_PAUSED)

Search for the function alxCloseHandles() and replace this line:

if(state == AL_PLAYING)

with this:

if(state == AL_PLAYING || state == AL_PAUSED)

2) Modify engine\audio\audioFunctions.cc and insert the following code after the definition of the alxStopAll() console function:

//-----------------------------------------------
ConsoleFunction(alxGetStreamPosition, F32, 2, 2, "alxGetStreamPosition(handle)" )
{
   AUDIOHANDLE handle = dAtoi(argv[1]);

   if(handle == NULL_AUDIOHANDLE)
      return -1;

   return alxGetStreamPosition( handle );
}

//-----------------------------------------------
ConsoleFunction(alxGetStreamDuration, F32, 2, 2, "alxGetStreamDuration(handle)" )
{
   AUDIOHANDLE handle = dAtoi(argv[1]);

   if(handle == NULL_AUDIOHANDLE)
      return -1;

   return alxGetStreamDuration( handle );
}

//-----------------------------------------------
ConsoleFunction(alxSeekToStreamPosition, bool, 3, 3, "alxSeekToStreamPosition(handle)" )
{
   AUDIOHANDLE handle = dAtoi(argv[1]);
   F32 seconds = dAtof(argv[2]);

   if(handle == NULL_AUDIOHANDLE)
      return false;

   return alxSeekToStreamPosition( handle, seconds );
}

//-----------------------------------------------
ConsoleFunction(alxIsPaused, bool, 2, 5, "alxIsPaused(handle)")
{
   AUDIOHANDLE handle = dAtoi(argv[1]);
   if(handle == NULL_AUDIOHANDLE)
      return false;
   return alxIsPaused(handle);
}

//-----------------------------------------------
ConsoleFunction(alxPauseAll, void, 1, 1, "()")
{
   alxPauseAll();
}

//-----------------------------------------------
ConsoleFunction(alxPause, void, 2, 2, "alxPause(handle)" )
{
   AUDIOHANDLE handle = dAtoi(argv[1]);

   if(handle == NULL_AUDIOHANDLE)
      return;

   alxPause( handle );
}

//-----------------------------------------------
ConsoleFunction(alxUnpauseAll, void, 1, 1, "()")
{
   alxUnpauseAll();
}

//-----------------------------------------------
ConsoleFunction(alxUnpause, void, 2, 2, "alxUnpause(handle)" )
{
   AUDIOHANDLE handle = dAtoi(argv[1]);

   if(handle == NULL_AUDIOHANDLE)
      return;

   alxUnpause( handle );
}

//-----------------------------------------------
ConsoleFunction(alxSetVolume, bool, 3, 3, "alxSetVolume(handle, float volume)\n\n"
				"@param handle      Handle of audio.\n"
                "@param volume      New volume of audio, from 0.0f - 1.0f"
                )
{
   AUDIOHANDLE handle = dAtoi(argv[1]);
   F32 volume = mClampF(dAtof(argv[2]), 0.f, 1.f);

   return alxSetVolume(handle, volume);
}

//-----------------------------------------------
ConsoleFunction(alxGetVolume, F32, 2, 2, "alxGetVolume(handle)" )
{
   AUDIOHANDLE handle = dAtoi(argv[1]);

   return alxGetVolume(handle);
}

3) Modify engine\audio\audioStreamSource.h and insert the following code after the declaraction of the freeStream() function:

virtual F32 getElapsedTime() = 0;
virtual F32 getTotalTime() = 0;
virtual bool seekToTime(F32 seconds) = 0;
virtual void pause() = 0;
virtual void unpause() = 0;

4) Modify engine\audio\oggMixedStreamSource.cc and insert the following code at the very end of the file:

void OggMixedStreamSource::pause()
{
   alSourcePause(mSource);
}

void OggMixedStreamSource::unpause()
{
   alSourcePlay(mSource);
}

5) Modify engine\audio\oggMixedStreamSource.h and insert the following code after the declaration of the freeStream() function:

virtual F32 getElapsedTime()
{
   return 0.0;
}

virtual F32 getTotalTime()
{
   return 1.0f;
}
      
virtual bool seekToTime(F32 seconds)
{
   return false;
}

virtual void pause();
virtual void unpause();

6) Modify engine\audio\vorbisStreamSource.cc and insert the following code at the very end of the file:

F32 VorbisStreamSource::getElapsedTime()
{
   return vf.ov_time_tell();
}

F32 VorbisStreamSource::getTotalTime()
{
   return vf.ov_time_total(-1);
}

bool VorbisStreamSource::seekToTime(F32 seconds)
{
   static char data[BUFFERSIZE*2];
   ALint error;

   bFinished = false;

   // Verify we were currently playing or paused
   ALint state = 0;
   alGetSourcei(mSource, AL_SOURCE_STATE, &state);
   if (state != AL_PLAYING && state != AL_PAUSED)
      return false;

   // Don't bother if this file isn't seekable
   if (vf.ov_seekable() == false)
      return false;

   alSourceStop(mSource);
   alSourcei(mSource, AL_BUFFER, 0);

   alSourcePlay(mSource);

   // Don't try to seek past the end of the song or before the begining
   seconds = getMin(seconds, (F32)vf.ov_time_total(-1) - 0.001f);
   seconds = getMax(seconds, 0.0f);

   // Seek to specified time position
   vf.ov_time_seek(seconds);

   long samples = (long)vf.ov_pcm_tell();
   if(format == AL_FORMAT_MONO16)
      DataLeft = DataSize - (2 * samples);
   else
      DataLeft = DataSize - (4 * samples);

   bBuffersAllocated = true;
   int numBuffers = 0;

   for(int loop = 0; loop < NUMBUFFERS; loop++)
   {
      ALuint DataToRead = (DataLeft > BUFFERSIZE) ? BUFFERSIZE : DataLeft;
      if (DataToRead == DataLeft)
         bFinished = AL_TRUE;

      long ret = oggRead(data, BUFFERSIZE, ENDIAN, &current_section);
      if(ret <= 0) {
         bFinished = AL_TRUE;
         break;
      }

      DataLeft -= ret;
      alBufferData(mBufferList[loop], format, data, ret, freq);
      ++numBuffers;

      if ((error = alGetError()) != AL_NO_ERROR)
         return false;
      if(bFinished)
         break;
   }

   // Queue the buffers on the source
   alSourceQueueBuffers(mSource, numBuffers, mBufferList);
   if ((error = alGetError()) != AL_NO_ERROR)
      return false;

   alSourcei(mSource, AL_LOOPING, AL_FALSE);

   // We have to update the buffers here, otherwise alxCloseHandles
   // thinks we aren't valid (ie, we aren't in a playing or paused
   // state).
   updateBuffers();

   // We don't really want to start playing if we were previously
   // paused.
   if (state == AL_PAUSED)
      alSourcePause(mSource);

   return true;
}

void VorbisStreamSource::pause()
{
   alSourcePause(mSource);
}

void VorbisStreamSource::unpause()
{
   alSourcePlay(mSource);
}

7) Modify engine\audio\vorbisStreamSource.cc and replace the following code that appears twice in this file:

if(mBufferList[0] != 0)
   alDeleteBuffers(NUMBUFFERS, mBufferList);
for(int i = 0; i < NUMBUFFERS; i++)
   mBufferList[i] = 0;

with the code below:

// Ensure that the refCount on the buffers is zero:
alSourceUnqueueBuffers (mSource, NUMBUFFERS, mBufferList);

if(mBufferList[0] != 0)
   alDeleteBuffers(NUMBUFFERS, mBufferList);
for(int i = 0; i < NUMBUFFERS; i++)
   mBufferList[i] = 0;

8) Modify engine\audio\vorbisStreamSouce.h and insert the following code after the declaration of the freeStream() function:

virtual F32 getElapsedTime();
virtual F32 getTotalTime();
virtual bool seekToTime(F32 seconds);
virtual void pause();
virtual void unpause();

9) Modify engine\audio\wavStreamSource.cc and insert the following code:

#include "console/console.h"

directly after this line:

#include "audio/wavStreamSource.h"

Insert the following code at the very end of the file:

F32 WavStreamSource::getElapsedTime()
{
   Con::warnf( "GetElapsedTime not implemented in WaveStreams yet" );
   return -1.f;
}

F32 WavStreamSource::getTotalTime()
{
   Con::warnf( "GetTotalTime not implemented in WaveStreams yet" );
   return -1.f;
}

bool WavStreamSource::seekToTime(F32 seconds)
{
   Con::warnf( "seekToTime not implemented in WaveStreams yet" );
   return false;
}

void WavStreamSource::pause()
{
   alSourcePause(mSource);
}

void WavStreamSource::unpause()
{
   alSourcePlay(mSource);
}

10) Modify engine\audio\wavStreamSource.h and insert the following code after the declaration of the freeStream() function:

virtual F32 getElapsedTime();
virtual F32 getTotalTime();
virtual bool seekToTime(F32 seconds);
virtual void pause();
virtual void unpause();

11) Modify engine\platform\platformAudio.h and insert the following code after the declaration of the alxStopAll() function:

F32 alxGetStreamDuration(AUDIOHANDLE handle);
F32 alxGetStreamPosition(AUDIOHANDLE handle);
bool alxSeekToStreamPosition(AUDIOHANDLE handle, F32 seconds);
bool alxIsPaused(AUDIOHANDLE handle);
void alxPauseAll();
void alxPause(AUDIOHANDLE handle);
void alxUnpauseAll();
void alxUnpause(AUDIOHANDLE handle);
F32 alxGetVolume(AUDIOHANDLE handle);
bool alxSetVolume(AUDIOHANDLE handle, F32 volume);

12) Modify engine\audio\audioBuffer.cpp and find the AudioBuffer::getALBuffer() function, and replace the two lines just before the call to alGenBuffers with:

// Intangir> fix for newest openAL from creative (it returns true, yea right 0 is not a valid buffer)
// it MIGHT not work at all for all i know.
if (malBuffer && alIsBuffer(malBuffer))
   return malBuffer;

13) Recompile Torque and you're done!


Manual integration for TGE 1.3
1) Follow the steps outlined in Manual integration for TGE 1.4, except skip steps 4 and 5. Note that the actual TGE 1.3 files included in this resource contain a few more fixes that are NOT described above so even though the implementing the changes manually will successfully add pausing and seeking, it's highly recommended that you instead use the files included in this resource.


Features

* Ability to pause/unpause playing of one or all audio files
* Ability to skip ahead/back to any specified time position while playing an OGG file
* Ability to modify the volume of any single playing audio file dynamically


Supported TorqueScript Functions

bool alxIsPaused(handle);
void alxPause(handle);
void alxPauseAll();
void alxUnpause(handle);
void alxUnpauseAll();
void alxSeekToStreamPosition(handle, seconds);
bool alxSetVolume(handle, volume);
F32 alxGetVolume(handle);


Updates

12/24/2005 - Added bug fix to seekToTime function. The zip file attached has the fix, or you can simply replace this function with the version posted in this resource under the Manual integration for TGE 1.4 section.

03/09/2006 - Merged both TGE 1.3 audio files and TGE 1.4 audio files into one set, so you can now use the same audio files to update TGE 1.3 as you do to update TGE 1.4. Note that this update has also added add some extra functionality to TGE 1.3 audio that is needed for my VMPlayer resource.

7/01/2006 - Added instructions for adding adding this resouce to TSE Milestone 3.5. Also added support for pausing/unpausing of non-streaming audio files (many thanks goes out to Gary Preston for taking the time to post all the changes necessary to add support of non-streaming audio file). Lastly added another fix by Gary Preston where in some rare circumstances unpausing sounds did not work. The fix is included in the latest release but you must also download OpenAl 1.1 for this fix to take effect.

1/07/2007 - Added fix for memory leak when playing streaming OGG files (many thanks goes out to Richard McKinney for this fix!). Also added support to dynamically change the volume on any playing audio file. Previously the Torque audio code only supported volume changes on a per-channel level.

1/07/2007 - Just added some fixes to the Manual Install section of this resource.

Enjoy!