Merge with trunk r37757.
[blender.git] / intern / audaspace / intern / AUD_I3DDevice.h
index 8e3f2e5958ad82917d23c96e970d8e8fe069d94d..036f7b1fa94c5f40225cced8616bb1a33877ad87 100644 (file)
@@ -1,32 +1,39 @@
 /*
  * $Id$
  *
- * ***** BEGIN LGPL LICENSE BLOCK *****
+ * ***** BEGIN GPL LICENSE BLOCK *****
  *
- * Copyright 2009 Jörg Hermann Müller
+ * Copyright 2009-2011 Jörg Hermann Müller
  *
  * This file is part of AudaSpace.
  *
- * AudaSpace is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
+ * Audaspace is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version.
  *
  * AudaSpace is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
+ * GNU General Public License for more details.
  *
- * You should have received a copy of the GNU Lesser General Public License
- * along with AudaSpace.  If not, see <http://www.gnu.org/licenses/>.
+ * You should have received a copy of the GNU General Public License
+ * along with Audaspace; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  *
- * ***** END LGPL LICENSE BLOCK *****
+ * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file audaspace/intern/AUD_I3DDevice.h
+ *  \ingroup audaspaceintern
+ */
+
+
 #ifndef AUD_I3DDEVICE
 #define AUD_I3DDEVICE
 
 #include "AUD_Space.h"
+#include "AUD_3DMath.h"
 
 /**
  * This class represents an output device for 3D sound.
@@ -35,67 +42,83 @@ class AUD_I3DDevice
 {
 public:
        /**
-        * Plays a 3D sound source.
-        * \param factory The factory to create the reader for the sound source.
-        * \param keep When keep is true the sound source will not be deleted but
-        *             set to paused when its end has been reached.
-        * \return Returns a handle with which the playback can be controlled.
-        *         This is NULL if the sound couldn't be played back.
-        * \exception AUD_Exception Thrown if there's an unexpected (from the
-        *            device side) error during creation of the reader.
-        * \note The factory must provide a mono (single channel) source otherwise
-        *       the sound is played back normally.
+        * Retrieves the listener location.
+        * \return The listener location.
+        */
+       virtual AUD_Vector3 getListenerLocation() const=0;
+
+       /**
+        * Sets the listener location.
+        * \param location The new location.
         */
-       virtual AUD_Handle* play3D(AUD_IFactory* factory, bool keep = false)=0;
+       virtual void setListenerLocation(const AUD_Vector3& location)=0;
+
+       /**
+        * Retrieves the listener velocity.
+        * \return The listener velocity.
+        */
+       virtual AUD_Vector3 getListenerVelocity() const=0;
+
+       /**
+        * Sets the listener velocity.
+        * \param velocity The new velocity.
+        */
+       virtual void setListenerVelocity(const AUD_Vector3& velocity)=0;
+
+       /**
+        * Retrieves the listener orientation.
+        * \return The listener orientation as quaternion.
+        */
+       virtual AUD_Quaternion getListenerOrientation() const=0;
+
+       /**
+        * Sets the listener orientation.
+        * \param orientation The new orientation as quaternion.
+        */
+       virtual void setListenerOrientation(const AUD_Quaternion& orientation)=0;
+
 
        /**
-        * Updates a listeners 3D data.
-        * \param data The 3D data.
-        * \return Whether the action succeeded.
+        * Retrieves the speed of sound.
+        * This value is needed for doppler effect calculation.
+        * \return The speed of sound.
         */
-       virtual bool updateListener(AUD_3DData &data)=0;
+       virtual float getSpeedOfSound() const=0;
 
        /**
-        * Sets a 3D device setting.
-        * \param setting The setting type.
-        * \param value The new setting value.
-        * \return Whether the action succeeded.
+        * Sets the speed of sound.
+        * This value is needed for doppler effect calculation.
+        * \param speed The new speed of sound.
         */
-       virtual bool setSetting(AUD_3DSetting setting, float value)=0;
+       virtual void setSpeedOfSound(float speed)=0;
 
        /**
-        * Retrieves a 3D device setting.
-        * \param setting The setting type.
-        * \return The setting value.
+        * Retrieves the doppler factor.
+        * This value is a scaling factor for the velocity vectors of sources and
+        * listener which is used while calculating the doppler effect.
+        * \return The doppler factor.
         */
-       virtual float getSetting(AUD_3DSetting setting)=0;
+       virtual float getDopplerFactor() const=0;
 
        /**
-        * Updates a listeners 3D data.
-        * \param handle The source handle.
-        * \param data The 3D data.
-        * \return Whether the action succeeded.
+        * Sets the doppler factor.
+        * This value is a scaling factor for the velocity vectors of sources and
+        * listener which is used while calculating the doppler effect.
+        * \param factor The new doppler factor.
         */
-       virtual bool updateSource(AUD_Handle* handle, AUD_3DData &data)=0;
+       virtual void setDopplerFactor(float factor)=0;
 
        /**
-        * Sets a 3D source setting.
-        * \param handle The source handle.
-        * \param setting The setting type.
-        * \param value The new setting value.
-        * \return Whether the action succeeded.
+        * Retrieves the distance model.
+        * \return The distance model.
         */
-       virtual bool setSourceSetting(AUD_Handle* handle,
-                                                                 AUD_3DSourceSetting setting, float value)=0;
+       virtual AUD_DistanceModel getDistanceModel() const=0;
 
        /**
-        * Retrieves a 3D source setting.
-        * \param handle The source handle.
-        * \param setting The setting type.
-        * \return The setting value.
+        * Sets the distance model.
+        * \param model distance model.
         */
-       virtual float getSourceSetting(AUD_Handle* handle,
-                                                                  AUD_3DSourceSetting setting)=0;
+       virtual void setDistanceModel(AUD_DistanceModel model)=0;
 };
 
 #endif //AUD_I3DDEVICE