A lot of doxy style comments

include/VAEventHandlerGlobalLock.h

@@ -18,25 +18,31 @@
 
 //! Global synchronization token for event handler operations
 /**
- * This singleton class realizes a global synchronization token
- * that can be used to realize mutual exclusive operations regarding
- * event handlers, like attaching/detaching event handlers to
- * event handler registrys and destruction of event handlers.
- */
+  * This singleton class realizes a global synchronization token
+  * that can be used to realize mutual exclusive operations regarding
+  * event handlers, like attaching/detaching event handlers to
+  * event handler registrys and destruction of event handlers.
+  */
 class VABASE_API IVAEventHandlerGlobalLock
 {
 public:
 	//! Returns the singleton instance
+	/**
+	  * @return Global lock for event handling
+	  */
 	static IVAEventHandlerGlobalLock& GetInstance();
 
-	// Lock (blocking wait, no try)
+	//! Lock (blocking wait, no try)
 	virtual void Lock() const = 0;
 
-	// Unlock
+	//! Unlock
 	virtual void Unlock() const = 0;
 
 protected:
+	//! Protected default constructor
 	inline IVAEventHandlerGlobalLock() {};
+
+	//! Protected destructor
 	virtual inline ~IVAEventHandlerGlobalLock() {};
 };
 

include/VAException.h

@@ -20,10 +20,9 @@
 
 //! Base class for exceptions
 /**
- * This is the exception base class for all VA software components.
- * Exceptions are defined by an error code and an error message.
- */
-
+  * This is the exception base class for all VA software components.
+  * Exceptions are defined by an error code and an error message.
+  */
 class VABASE_API CVAException
 {
 public:
@@ -45,23 +44,36 @@ public:
 	CVAException();
 
 	//! Initialization constructor
-	CVAException( int iErrorCode, const std::string& sErrorMessage = "" );
+	/**
+	  * @param[in] iErrorCode Error code
+	  * @param[in] sErrorMessage Error text
+	  */
+	CVAException( const int iErrorCode, const std::string& sErrorMessage = "" );
 
 	//! Destructor
 	virtual ~CVAException();
 
 	//! Returns the error code
+	/**
+	  * @return Error code, one of ErrorCode
+	  */
 	int GetErrorCode() const;
 
 	//! Returns the error message
+	/**
+	  * @return Error text message
+	  */
 	std::string GetErrorMessage() const;
 
 	//! Return a string representation of the exception
+	/**
+	  * @return Formatted text of exception
+	  */
 	std::string ToString() const;
 
 protected:
-	int m_iErrorCode;
-	std::string m_sErrorMessage;
+	int m_iErrorCode; //!< Error code, one of ErrorCode
+	std::string m_sErrorMessage; //!< Error text message
 };
 
 //! Macro for throwing exceptions
@@ -71,6 +83,11 @@ protected:
 #define VA_EXCEPT_NOT_IMPLEMENTED { throw CVAException( (CVAException::NOT_IMPLEMENTED) , "Not implemented" ); }
 
 //! STL stream output operator
+/**
+  * @param[in] os Outstream object
+  * @param[in] ex VA exception
+  * @return Outstream object including exception text
+  */
 VABASE_API std::ostream& operator<<( std::ostream& os, const CVAException& ex );
 
 #endif // IW_VABASE_EXCEPTION

include/VAInterface.h

@@ -1106,16 +1106,17 @@ public:
 	/**
 	  * If the sound source is not assigned a directivity, the methods returns -1.
 	  * @param[in] iID Sound source identifier
+	  * @return Directivity identifier
 	  */
 	virtual int GetSoundSourceDirectivity( const int iID ) const = 0;
 
 	//! Sets the directivity of a sound source
 	/**
 	  * In order to remove an assigned directivity, you can pass -1 to the method.
-	  * @param[in] iID Sound source identifier
+	  * @param[in] iSoundReceiverID Sound source identifier
 	  * @param[in] iDirectivityID Directivity identifier
 	  */
-	virtual void SetSoundSourceDirectivity( const int iID, const int iDirectivityID ) = 0;
+	virtual void SetSoundSourceDirectivity( const int iSoundReceiverID, const int iDirectivityID ) = 0;
 
 	//! Sound receiver sound power getter
 	/**
@@ -1248,8 +1249,8 @@ public:
 
 	//! Sound receiver info getter
 	/**
-	  * @param[in] Sound receiver identifier
-	  *@return Sound receiver info
+	  * @param[in] iID Sound receiver identifier
+	  * @return Sound receiver info
 	  */
  	virtual CVASoundReceiverInfo GetSoundReceiverInfo( const int iID ) const = 0;
 
@@ -1294,7 +1295,7 @@ public:
 	
 	//! Sound receiver auralization mode setter
 	/**
-	  * @param[in] iID Sound receiver identifier
+	  * @param[in] iSoundReceiverID Sound receiver identifier
 	  * @param[in] iAuralizationMode Auralization mode bit-vector
 	  */
 	virtual void SetSoundReceiverAuralizationMode( const int iSoundReceiverID, const int iAuralizationMode ) = 0;
@@ -1319,136 +1320,342 @@ public:
 	  * @return Magic struct with the parameter values requested
 	  */
 	virtual CVAStruct GetSoundReceiverParameters( const int iID, const CVAStruct& oArgs ) const = 0;
-
-	//! Returns for a sound receiver the ID of the assigned HRIR dataset
+	
+	//! Returns the directivity of a sound source
+	/**
+	  * If the sound receiver is not assigned a directivity, the methods returns -1.
+	  * @param[in] iID Sound receiver identifier
+	  * @return Directivity identifier
+	  */
 	virtual int GetSoundReceiverDirectivity( const int iID ) const = 0;
-
-	//! Set the HRIR dataset for a sound receiver
+	
+	//! Sets the directivity of a sound receiver
 	/**
-	* @note In order to set no HRIR dataset, you can pass -1 to the method.
-	*/
+	  * In order to remove an assigned directivity, you can pass -1 to the method.
+	  * @param[in] iSoundReceiverID Sound receiver identifier
+	  * @param[in] iDirectivityID Directivity identifier
+	  */
 	virtual void SetSoundReceiverDirectivity( const int iSoundReceiverID, const int iDirectivityID ) = 0;
-
+	
+	//! Sound receiver geo mesh identifier getter
+	/**
+	  * @param[in] iID	Sound receiver identifier
+	  * @return Geo mesh identifier
+	  *
+	  */
 	virtual int GetSoundReceiverGeometryMesh( const int iID ) const = 0;
+	
+	//! Sound receiver geo mesh identifier getter
+	/**
+	  * Sound receivers can have geometrical meshes assigned, i.e. to identify which geometry is part
+	  * of a sound receiver that should not be considered for direct path occlusion - or if the
+	  * moving receiver geometry is relevant for occlusion of other source-receivere-paths, like
+	  * cars, trains, etc.
+	  *
+	  * @param[in] iSoundReceiverID	Sound source identifier
+	  * @param[in] iGeometryMeshID Geo mesh identifier
+	  *
+	  */
 	virtual void SetSoundReceiverGeometryMesh( const int iSoundReceiverID, const int iGeometryMeshID ) = 0;
-
-
-	//! Sound receiver pose getter (pose = position & orientation)
-	virtual void GetSoundReceiverPose( const int iID, VAVec3& vPos, VAQuat& qOrient ) const = 0;
-
-	//! Sound receiver pose setter (pose = position & orientation)
-	virtual void SetSoundReceiverPose( const int iID, const VAVec3& vPos, const VAQuat& qOrient ) = 0;
-
-	//! Position eines Hörers zurückgeben (Positionsvektor) 
+	
+	//! Sound source pose getter
+	/**
+	  * @param[in] iID Sound source identifier
+	  * @param[out] v3Pos Position vector
+	  * @param[out] qOrient Orientation quaternion
+	  */
+	virtual void GetSoundReceiverPose( const int iID, VAVec3& v3Pos, VAQuat& qOrient ) const = 0;
+	
+	//! Sound source pose setter
+	/**
+	  * @param[in] iID Sound source identifier
+	  * @param[in] v3Pos Position vector
+	  * @param[in] qOrient Orientation quaternion
+	  */
+	virtual void SetSoundReceiverPose( const int iID, const VAVec3& v3Pos, const VAQuat& qOrient ) = 0;
+	
+	//! Sound source position getter
+	/**
+	  * @param[in] iID Sound source identifier
+	  * @return Position vector
+	  */
 	virtual VAVec3 GetSoundReceiverPosition( const int iID ) const = 0;
-
-	//! Position eines Hörers setzen (Positionsvektor) 
+	
+	//! Sound source position setter
 	/**
-	 * - Sets the velocity of the sound receiver to zero
-	 */
+	  * @param[in] iID Sound source identifier
+	  * @param[in] v3Pos Position vector
+	  */
 	virtual void SetSoundReceiverPosition( const int iID, const VAVec3& v3Pos ) = 0;
-
-	//! Orientierung eines Hörers zurückgeben (view and up vector) 
-	virtual void GetSoundReceiverOrientationVU( const int iID, VAVec3& vView, VAVec3& vUp ) const = 0;
-
-	//! Orientierung eines Hörers setzen (view and up vector) 
-	virtual void SetSoundReceiverOrientationVU( const int iID, const VAVec3& vView, const VAVec3& vUp ) = 0;
-
-	//! Orientierung getter for sound receiver (quaternion) 
+	
+	//! Sound source orientation getter for view and up vectors
+	/**
+	  * Uses OpenGL view and up convention.
+	  *
+	  * @param[in] iID Sound source identifier
+	  * @param[out] v3View View vector
+	  * @param[out] v3Up Up vector
+	  */
+	virtual void GetSoundReceiverOrientationVU( const int iID, VAVec3& v3View, VAVec3& v3Up ) const = 0;
+	
+	//! Sound source orientation setter using view and up vector
+	/**
+	  * Uses OpenGL view and up convention.
+	  *
+	  * @param[in] iID Sound source identifier
+	  * @param[in] v3View View vector
+	  * @param[in] v3Up Up vector
+	  */
+	virtual void SetSoundReceiverOrientationVU( const int iID, const VAVec3& v3View, const VAVec3& v3Up ) = 0;
+	
+	//! Sound source orientation getter
+	/**
+	  * @param[in] iID Sound source identifier
+	  * @return Orientation quaternion
+	  */
 	virtual VAQuat GetSoundReceiverOrientation( const int iID ) const = 0;
-
-	//! OOrientierung setter for sound receiver (quaternion) 
+	
+	//! Sound source orientation setter
+	/**
+	  * @param[in] iID Sound source identifier
+	  * @param[in] qOrient Orientation quaternion
+	  */
 	virtual void SetSoundReceiverOrientation( const int iID, const VAQuat& qOrient ) = 0;
 
+	//! Sound receiver head-above-torso orientation getter
+	/**
+	  * @param[in] iID Sound source identifier
+	  * @return Orientation of head-above-torso as quaternion
+	  */
 	virtual VAQuat GetSoundReceiverHeadAboveTorsoOrientation( const int iID ) const = 0;
+	
+	//! Sound receiver head-above-torso orientation setter
+	/**
+	  * @param[in] iID Sound source identifier
+	  * @param[in] qOrient Orientation quaternion of head-above-torso
+	  */
 	virtual void SetSoundReceiverHeadAboveTorsoOrientation( const int iID, const VAQuat& qOrient ) = 0;
 
 	//! Returns the position and orientation of the real-world sound receiver's head
 	/**
-	* @note The parameter iSoundReceiverID has been added for future versions and is
-	*       currently unsupported. You can set it any value you like.
-	*
-	* @note Coordinates refer the to center of the head on the axis
-	*            which goes through both ears.
-	*/
+	  * @note Coordinates refer the to center of the head on the axis which goes through both ears.
+	  *
+	  * @param[in] iID Sound receiver identifier
+	  * @param[out] v3Pos Real world position of sound receiver
+	  * @param[out] v3View Real world view vector of sound receiver
+	  * @param[out] v3Up Real world up vector of sound receiver
+	  */
 	virtual void GetSoundReceiverRealWorldPositionOrientationVU( const int iID, VAVec3& v3Pos, VAVec3& v3View, VAVec3& v3Up ) const = 0;
 
 	//! Updates the position and orientation of the real-world sound receiver's head
 	/**
-	* This function is used to provide the crosstalk-cancellation module
-	* with the current position of the sound receivers head in the real-world.
-	*
-	* @note The parameter iSoundReceiverID has been added for future versions and is
-	*       currently unsupported. You can set it any value you like.
-	*
-	* @note Coordinates refer the to center of the head on the axis
-	*            which goes through both ears.
-	*/
+	  * This function is used to provide the crosstalk-cancellation module
+	  * with the current position of the sound receivers head in the real-world.
+  	  *
+	  * @note Coordinates refer the to center of the head on the axis which goes through both ears.
+	  *
+	  * @param[in] iID Sound receiver identifier
+	  * @param[in] v3Pos Real world position of sound receiver
+	  * @param[in] v3View Real world view vector of sound receiver
+	  * @param[in] v3Up Real world up vector of sound receiver
+	  *
+	  */
 	virtual void SetSoundReceiverRealWorldPositionOrientationVU( const int iID, const VAVec3& v3Pos, const VAVec3& v3View, const VAVec3& v3Up ) = 0;
-
+	
+	//! Returns the pose of the real-world sound receiver's head
+	/**
+	  * @note Coordinates refer the to center of the head on the axis which goes through both ears.
+	  *
+	  * @param[in] iID Sound receiver identifier
+	  * @param[out] v3Pos Real world position of sound receiver
+	  * @param[out] qOrient Real world orientation as quaternion of sound receiver
+	  *
+	  */
 	virtual void GetSoundReceiverRealWorldPose( const int iID, VAVec3& v3Pos, VAQuat& qOrient ) const = 0;
+	
+	//! Updates the pose of the real-world sound receiver's head
+	/**
+	  * This function is used to provide the crosstalk-cancellation module
+	  * with the current position of the sound receivers head in the real-world.
+  	  *
+	  * @note Coordinates refer the to center of the head on the axis which goes through both ears.
+	  *
+	  * @param[in] iID Sound receiver identifier
+	  * @param[in] v3Pos Real world position of sound receiver
+	  * @param[in] qOrient Real world orientation as quaternion of sound receiver
+	  *
+	  */
 	virtual void SetSoundReceiverRealWorldPose( const int iID, const VAVec3& v3Pos, const VAQuat& qOrient ) = 0;
-
+	
+	//! Sound receiver real-world head-above-torso orientation getter
+	/**
+	  * @param[in] iID Sound source identifier
+	  * @return Orientation of head-above-torso as quaternion
+	  */
 	virtual VAQuat GetSoundReceiverRealWorldHeadAboveTorsoOrientation( const int iID ) const = 0;
+	
+	//! Sound receiver real-world head-above-torso orientation setter
+	/**
+	  * @param[in] iID Sound source identifier
+	  * @param[in] qOrient Orientation quaternion of head-above-torso
+	  */
 	virtual void SetSoundReceiverRealWorldHeadAboveTorsoOrientation( const int iID, const VAQuat& qOrient ) = 0;
 
 
 	//! Set homogeneous medium sound speed in m/s
+	/**
+	  * Sets the speed of sound of the homogeneous medium. Significant changes to this parameter
+	  * might cause audible artifacts due to its unphysical background.
+	  *
+	  * @param[in] dSoundSpeed Speed of sound [m/s]
+	  */
 	virtual void SetHomogeneousMediumSoundSpeed( const double dSoundSpeed ) = 0;
 
 	//! Get homogeneous medium sound speed in m/s
+	/**
+	  * @return Speed of sound [m/s]
+	  */
 	virtual double GetHomogeneousMediumSoundSpeed() const = 0;
 
 	//! Set homogeneous medium temperature in degree Celsius (0 is freezing point of water)
+	/**
+	  * Sets the temperature of the homogeneous medium. Significant changes to this parameter
+	  * might cause audible artifacts due to its unphysical background.
+	  *
+	  * @param[in] dDegreesCentigrade Degrees Centigrade [°]
+	  */
 	virtual void SetHomogeneousMediumTemperature( const double dDegreesCentigrade ) = 0;
 
 	//! Get homogeneous medium temperature in degree Celsius (0 is freezing point of water)
+	/**
+	  * @return Temperature in Degrees Centigrade [°]
+	  */
 	virtual double GetHomogeneousMediumTemperature() const = 0;
 
 	//! Set homogeneous medium static pressure in Pascal
+	/**
+	  * Sets the static pressure of the homogeneous medium. Significant changes to this parameter
+	  * might cause audible artifacts due to its unphysical background.
+	  *
+	  * @param[in] dPressurePascal Static pressure [Pa]
+	  */
 	virtual void SetHomogeneousMediumStaticPressure( const double dPressurePascal ) = 0;
 
 	//! Get homogeneous medium static pressure in Pascal
+	/**
+	  * @return Static pressure [Pa]
+	  */
 	virtual double GetHomogeneousMediumStaticPressure() const = 0;
 
 	//! Set homogeneous medium relative humidity in percent (0.0 = no vapor, 50.0 = 50%, ... )
+	/**
+	  * Sets the relative humidity of the homogeneous medium. Significant changes to this parameter
+	  * might cause audible artifacts due to its unphysical background.
+	  *
+	  * @param[in] dRelativeHumidityPercent Relative humidity [%] ( 0.0f .. 50.0f ... 100.0f ... )
+	  */
 	virtual void SetHomogeneousMediumRelativeHumidity( const double dRelativeHumidityPercent ) = 0;
 
 	//! Get homogeneous medium relative humidity in percent (0.0 = no vapor, 50.0 = 50%, ... )
+	/**
+	  * @return Relative humidity [%] ( 0.0f .. 50.0f ... 100.0f ... )
+	  */
 	virtual double GetHomogeneousMediumRelativeHumidity() = 0;
 
-	//! Set homogeneous medium shift speed as 3-dim direction vector in m/s
+	//! Set homogeneous medium shift speed as 3-dim direction vector in m/s ("wind" speed with direction)
+	/**
+	  * Sets the shift speed of the homogeneous medium ("wind" speed). Significant changes to this parameter
+	  * might cause audible artifacts due to its unphysical background.
+	  *
+	  * @param[in] v3TranslationSpeed Translatory speed [m/s]
+	  */
 	virtual void SetHomogeneousMediumShiftSpeed( const VAVec3& v3TranslationSpeed ) = 0;
 
-	//! Get homogeneous medium shift speed as 3-dim direction vector in m/s
+	//! Get homogeneous medium shift speed as 3-dim direction vector in m/s ("wind" speed with direction)
+	/**
+	  * @return Translatory speed [m/s]
+	  */
 	virtual VAVec3 GetHomogeneousMediumShiftSpeed() const = 0;
 
 	//! Set homogeneous medium special parameters
+	/**
+	  * Sets any further parameter of the medium, like Chemical constellation, particle density ...
+	  * Intended to be used for prototyping. Can also be used to define non-homogeneous media by
+	  * a proprietary definition that is used by a specialized rendering module, e.g. for air traffic
+	  * noise.
+	  *
+	  * @param[in] oParams Magic medium parameters
+	  */
 	virtual void SetHomogeneousMediumParameters( const CVAStruct& oParams ) = 0;
 
 	//! Get homogeneous medium special parameters with optional arguments
+	/**
+	  * Sets any further parameter of the medium, like Chemical constellation, particle density ...
+	  * Intended to be used for prototyping. Can also be used to define non-homogeneous media by
+	  * a proprietary definition that is used by a specialized rendering module, e.g. for air traffic
+	  * noise.
+	  *
+	  * @param[in] oArgs Magic medium parameter request arguments
+	  * @return Magic medium parameters
+	  */
 	virtual CVAStruct GetHomogeneousMediumParameters( const CVAStruct& oArgs ) = 0;
 
 
 	//! Creates a virtual scene
+	/**
+	  * Scenes is a relatively loose description for a virtual environment. It may
+	  * contain information of arbitrary form that can be intepreted by a rendering module.
+	  * The scene methods are for prototyping in order to pass scene information to a 
+	  * rendering module or an associated simulation backend that requires e.g. geometry input
+	  * files.
+	  *
+	  * Scenes may be enabled and disabled for rapid scene switching.
+	  *
+	  * @param[in] oParams Scene parameters
+	  * @param[in] sName Verbatin scene name
+	  * @return Scene identifier string
+	  */
 	virtual std::string CreateScene( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
 
 	//! IDs of created scenes
+	/**
+	  * @param[out] vsIDs Scene identifier vector
+	  */
 	virtual void GetSceneIDs( std::vector< std::string >& vsIDs ) const = 0;
 
 	//! Get scene info
+	/**
+	  * @param[in] sID Scene identifier
+	  * @return Scene information
+	  */
 	virtual CVASceneInfo GetSceneInfo( const std::string& sID ) const = 0;
 
-	//! Returns the name of a portal
+	//! Returns the name of given scene
+	/**
+	  * @param[in] sID Scene identifier
+	  * @return Scene verbatim name
+	  */
 	virtual std::string GetSceneName( const std::string& sID ) const = 0;
 
-	//! Sets the name of a portal
+	//! Set the name of given scene
+	/**
+	  * @param[in] sID Scene identifier
+	  * @param[in] sName Scene verbatim name
+	  */
 	virtual void SetSceneName( const std::string& sID, const std::string& sName ) = 0;
 
 	//! Set scene enabled or disabled
+	/**
+	  * @param[in] sID Scene identifier
+	  * @param[in] bEnabled Enabled/disabled flag
+	  */
 	virtual void SetSceneEnabled( const std::string& sID, const bool bEnabled = true ) = 0;
 
 	//! Scene enabled status (true, if enabled)
+	/**
+	  * @param[in] sID Scene identifier
+	  * @return True, if scene is enabled
+	  */
 	virtual bool GetSceneEnabled( const std::string& sID ) const = 0;