audio3d.h

Go to the documentation of this file.
00001 /*
00002  * audio3d.h
00003  *
00004  * Copyright (C) 2009  Thomas A. Vaughan
00005  * All rights reserved.
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  *
00031  * Basic 3D sound support
00032  */
00033 
00034 #ifndef WAVE_AUDIO_AUDIO3D_H__
00035 #define WAVE_AUDIO_AUDIO3D_H__
00036 
00037 // includes --------------------------------------------------------------------
00038 #include "common/common.h"
00039 
00040 #include "audiere/audiere.h"
00041 #include "geometry/geometry_3d.h"
00042 #include "threadsafe/smart_ptr.h"
00043 
00044 
00045 namespace audio3d {
00046 
00047 
00048 ////////////////////////////////////////////////////////////////////////////////
00049 ///
00050 /// \ingroup wave_audio
00051 /// \defgroup audio3d Wavepacket 3D Audio Library
00052 ///
00053 /// A simple 3D audio library.
00054 ///
00055 /// \n
00056 /// This is a simple implementation based on the audiere API.
00057 ///
00058 ////////////////////////////////////////////////////////////////////////////////
00059 /*@{*/
00060 
00061 
00062 ////////////////////////////////////////////////////////////////////////////////
00063 //
00064 //      public API
00065 //
00066 ////////////////////////////////////////////////////////////////////////////////
00067 
00068 typedef dword_t id_t;
00069 
00070 
00071 
00072 /// This class manages all 3D sounds.
00073 /// To use this class:
00074 ///  - create a SoundManager instance.
00075 ///  - add a bunch of listeners (1 per local player, typically)
00076 ///  - add a bunch of sound sources (as many as you want to hear)
00077 ///  - update listener and sound positions as necessary
00078 ///  - call updateSpaces() to actually adjust sound output based on 3D positions
00079 ///
00080 /// This class is <b>NOT</b> threadsafe.  If you need synchronization, add it
00081 ///     in a higher layer.  Make sure only one thread ever accesses this object!
00082 class SoundManager {
00083 public:
00084         // virtual destructor --------------------------------------------------
00085         virtual ~SoundManager(void) throw();
00086 
00087         // audio3d::SoundManager class interface methods -----------------------
00088 
00089         /// creates a listener and provides the ID back.  The listener is
00090         ///     positioned at the origin (0, 0, 0) facing in the z-direction
00091         ///     (facing = [0, 0, 1]) with local up in the y-direction
00092         ///     (up = [0, 1, 0]).  Call updateListener() to change the
00093         ///     position and orientation.
00094         virtual id_t createListener(void) = 0;
00095 
00096         /// caller can move the specified listener to the given position and
00097         ///     orientation.  <b>The facing and up vectors must be
00098         ///     normalized.</b>
00099         virtual void updateListener(IN id_t listenerId,
00100                                 IN const point3d_t& position,
00101                                 IN const point3d_t& facing,
00102                                 IN const point3d_t& up) = 0;
00103 
00104         /// remove the listener with the given ID
00105         virtual bool removeListener(IN id_t listenerId) = 0;
00106 
00107         /// create a sound that can be heard by the given listener
00108         virtual id_t createSound(IN id_t listenerId,
00109                                 IN const char * filename,
00110                                 IN float baseVolume) = 0;
00111 
00112         /// move the specified sound to a new location (cannot change spaces)
00113         virtual void updateSound(IN id_t soundId,
00114                                 IN const point3d_t& position) = 0;
00115 
00116         /// remove the sound with the given ID
00117         virtual bool removeSound(IN id_t soundId) = 0;
00118 
00119         /// update all volume and panning levels based on current positions
00120         virtual void updateSounds(void) = 0;
00121 
00122         // static factory methods ----------------------------------------------
00123         static smart_ptr<SoundManager> create(IN const char * device_name,
00124                                 IN const char * parameters);
00125 };
00126 
00127 
00128 
00129 };      // audio3d namespace
00130 
00131 
00132 #endif  // WAVE_AUDIO_AUDIO3D_H__
00133