Mergin conflict ready

include/VA.h

@@ -36,7 +36,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 
-You should also have received a [copy of the License](LICENSE.md) with the VA software package.
+You should also have received acopy of the License with the VA software package.
 
 @section getting_started Getting started
 

include/VAAudioSignalSource.h

@@ -57,13 +57,13 @@ public:
 
 	//! Type ID getter
 	/**
-	  * @return Returns the ID (one out of #SoundSourceTypes)
+	  * @return Returns the ID (one out of AudioSignalSourceType)
 	  */
 	virtual int GetType() const = 0;
 
 	//! Type getter (human readable string)
 	/**
-	  * @return Returns the type (one out of #SoundSourceTypes as a human readable string)
+	  * @return Returns the type (one out of AudioSignalSourceType as a human readable string)
 	  */
 	virtual std::string GetTypeString() const = 0;
 
@@ -101,19 +101,18 @@ public:
 	/**
 	  * Returns the data pointer to the next audio block of the sound source.
 	  *
-	  * @param[in] oStreamState Information on stream state
+	  * @param[in] pStreamInfo Information on stream state
 	  *
 	  * @return Pointer to the audio data array containing data for next block (NULL if no data available)
 	  *
-	  * @note This method is called by the core to fetch data. If the core
-	  *       receives a NULL pointer it will be interpreted as silence.
+	  * @note This method is called by the core to fetch data. If the core receives a NULL pointer it will be interpreted as silence.
 	  */
 	virtual const float* GetStreamBlock( const CVAAudiostreamState* pStreamInfo ) = 0;
 
 	//! Parameter getter interaction hook
 	/**
 	  * @param[in] oIn Parameter request set
-	  * @param[out] Parameters
+	  * @return Parameters
 	  */
 	virtual CVAStruct GetParameters( const CVAStruct& oIn ) const = 0;
 

include/VABase.h

@@ -198,12 +198,12 @@ inline VABASE_API VAVec3 operator-( const VAVec3& oSummand1, const VAVec3& oSumm
 
 //!< Scalar multiply operator for vectors
 /**
-  * @param[in] oVec VEctor
+  * @param[in] oVec Vector
   * @param[in] dScalar Scalar
   *
-  * @param Scaled vector
+  * @return Scaled vector
   */
-inline VABASE_API VAVec3 operator*( const VAVec3& oVec, double dScalar )
+inline VABASE_API VAVec3 operator*( const VAVec3& oVec, const double dScalar )
 {
 	VAVec3 vScaledVector = oVec;
 	vScaledVector.x *= dScalar;
@@ -535,16 +535,25 @@ public:
 		, iType( UNSPECIFIED )
 	{};
 
+	// Signal source destructor
 	virtual inline ~CVASignalSourceInfo() {};
 
 	//! Initializing constructor
 	/**
 	  * @param[in] sID Identifier string
+<<<<<<< HEAD
 	  * @param[in] iType Signal source type
 	  * @param[in] sName Name of signal source info
 	  * @param[in] sDesc Brief description of signal source info
 	  * @param[in] sState State description of signal source info
 	  * @param[in] iReference Usage reference counter
+=======
+	  * @param[in] iType Type
+	  * @param[in] sName Name of signal source info
+	  * @param[in] sDesc Brief description of signal source info
+	  * @param[in] sState State description of signal source info
+	  * @param[in] iReferences Usage reference counter
+>>>>>>> 97ef3d5f8f255a5f334144c02fd00c96b099f8bf
 	  */
 	inline CVASignalSourceInfo( const std::string& sID, const int iType, const std::string& sName, const std::string& sDesc, const std::string& sState, const int iReferences )
 		: sID( sID )
@@ -568,7 +577,6 @@ public:
 	std::string sID;	//!< Scene identifier
 	std::string sName;	//!< Scene name
 	bool bEnabled; //!< Enabled/disabled flag
-
 	CVAStruct oParams; //!< Scene parameters
 
 	//! Constructor settng scene info as enabled
@@ -577,7 +585,7 @@ public:
 	{
 	};
 
-	//! Destructor
+	//! Scene info destructor
 	inline virtual ~CVASceneInfo()
 	{
 	};
@@ -634,6 +642,7 @@ public:
 
 	CVAStruct oParams;		//!< Special parameters
 
+	//! Constructor for sound source info
 	inline CVASoundSourceInfo()
 		: iID( -1 )
 		, bMuted( false )
@@ -643,6 +652,7 @@ public:
 		, iAuraMode( -1 )
 	{};
 
+	//! Destructor
 	virtual inline ~CVASoundSourceInfo() {};
 };
 
@@ -675,6 +685,7 @@ public:
 
 	CVAStruct oParams; 	//!< Special parameters
 
+	//! Constructor for sound receiver info
 	inline CVASoundReceiverInfo()
 		: iID( -1 )
 		, iDirectivityID( -1 )
@@ -683,6 +694,7 @@ public:
 		, bEnabled( true )
 	{};
 
+	//! Destructor
 	virtual inline ~CVASoundReceiverInfo() {};
 };
 
@@ -693,12 +705,12 @@ class VABASE_API CVASoundPortalInfo
 public:
 	int iID;			//!< ID
 	std::string sName;	//!< Displayed name (optional)
-	bool bEnabled;
+	bool bEnabled; //!< Enabled flag
 
 	int iMaterialID; //!< Material ID with transmission data
-	int iNextPortalID;
-	int iSoundReceiverID;
-	int iSoundSourceID;
+	int iNextPortalID; //!< Next sound portal identifier, if existing
+	int iSoundReceiverID; //!< Source receiver identifier, if existing
+	int iSoundSourceID; //!< Source sound identifier, if existing
 
 	VAVec3 v3Pos;		//!< Position vector [m]
 	VAVec3 v3View, v3Up;	//!< View-/Up-vector
@@ -706,6 +718,7 @@ public:
 
 	CVAStruct oParams; 	//!< Special parameters
 
+	//! Default constructor for sound portal
 	inline CVASoundPortalInfo()
 		: iID( -1 )
 		, iNextPortalID( -1 )
@@ -714,6 +727,7 @@ public:
 		, iMaterialID( -1 )
 	{};
 
+	//! Destructor
 	virtual inline ~CVASoundPortalInfo() {};
 };
 
@@ -748,6 +762,9 @@ public:
 	inline CVAAcousticMaterial()
 		: iID( -1 )
 	{};
+
+	//! Destructor
+	virtual inline ~CVAAcousticMaterial() {};
 };
 
 
@@ -763,29 +780,36 @@ public:
 class VABASE_API CVAGeometryMesh
 {
 public:
+	//! Vertex representation
 	class CVAVertex
 	{
 	public:
-		int iID;
-		VAVec3 v3Point;
+		int iID; //!< Vertex identifier
+		VAVec3 v3Point; //!< Vertext point / position
+
+		//! Constructor initializing defaults
 		inline CVAVertex() : iID( -1 ) {};
 	};
 
+	//! Face representation
 	class CVAFace
 	{
 	public:
-		int iID;
+		int iID; //!< Face identifier
 		int iMaterialID; //!< Assigned material
-		std::vector< int > viVertexList;
+		std::vector< int > viVertexList; //!< Face vertices
+		
+		//! Constructor initializing defaults
 		inline CVAFace() : iID( -1 ), iMaterialID( -1 ) {};
 	};
 
-	int iID;
-	bool bEnabled;
+	int iID; //!< Geometry mesh identifier
+	bool bEnabled; //!< Enabled flag
 	std::vector< CVAVertex > voVertices; //!< List of available vertices
 	std::vector< CVAFace > voFaces; //!< List of faces defined by vertices
 	CVAStruct oParams; //!< Additional parameters
 
+	//! Constructor initializing members
 	inline CVAGeometryMesh()
 		: iID( -1 )
 		, bEnabled( true )

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/VAObject.h

@@ -29,38 +29,64 @@ public:
 	//! Default constructor
 	CVAObject();
 
-	//! Initialization constructors
+	//! Initialization constructor
+	/**
+	  * @param[in] pszName Character type name initialization
+	  */
 	CVAObject( const char* pszName );
+	
+	//! Initialization constructor
+	/**
+	  * @param[in] sName String type name initialization
+	  */
 	CVAObject( const std::string& sName );
 
 	//! Destructor
 	virtual ~CVAObject();
 
 	//! Returns the ID of the object
+	/**
+	  * @return Object identifier integer
+	  */
 	int GetObjectID() const;
 
 	//! Returns the name of the object
+	/**
+	  * @return Object name
+	  */
 	std::string GetObjectName() const;
 
 	//! Returns information on the object
+	/**
+	  * @return Object info
+	  */
 	virtual CVAObjectInfo GetObjectInfo() const;
 
 	//! Call the object with a message and capture return message
 	/**
-	  *
+	  * @param[in] oArgs Object call arguments as CVAStruct
+	  * @return Object call return value as CVAStruct
 	  */
 	virtual CVAStruct CallObject( const CVAStruct& oArgs ) = 0;
 
 protected:
 	// Important: An object may not change its name after it is registered
+	/**
+	  * @param[in] sName Name of new object
+	  * @note This may only be called from an object registry
+	  */
 	void SetObjectName( const std::string& sName );
 
 private:
-	int m_iObjectID;
-	std::string m_sObjectName;
+	int m_iObjectID; //!< Object identifier
+	std::string m_sObjectName; //!< Object name (should not be changed during runtime)
 
-	// Note: This may only be called from an object registry
-	void SetObjectID( const int iID );
+	//! Object identifier (integer) setter 
+	/**
+	  * @param[in] iID Object identifier number
+	  * @note This may only be called from an object registry
+	  */
+ 	void SetObjectID( const int iID );
 
 	friend class CVAObjectRegistry;
 };

include/VAObjectRegistry.h

@@ -22,12 +22,13 @@
 #include <string>
 #include <vector>
 
+// Forwards
 class CVAObject;
 
 //! Registry class for objects
 /**
- *
- */
+  * Handles VA object registration. Objects will be callable via object / module interface.
+  */
 class VABASE_API CVAObjectRegistry
 {
 public:
@@ -37,66 +38,84 @@ public:
 	//! Destructor
 	~CVAObjectRegistry();
 
-	//! Clear up. Deregisters all modules.
+	//! Clear objects. Deregisters all modules.
 	void Clear();
 
 	//! Registers an object with the registry and returns its ID
+	/**
+	  * @param[in] pObject Object pointer
+	  * @return Object identifier
+	  */
 	int RegisterObject( CVAObject* pObject );
 
 	//! Deregisters an object from the registry
+	/**
+	  * @param[in] pObject Object pointer
+	  */
 	void UnregisterObject( CVAObject* pObject );
 
 	//! Query the IDs of all objects
 	void GetObjectIDs( std::vector< int >& viIDs ) const;
 
 	//! Query information on all objects
+	/**
+	  * @param[in] viInfos Object infos
+	  */
 	void GetObjectInfos( std::vector< CVAObjectInfo >& viInfos ) const;
 
 	//! Finds an object by its ID
 	/**
-	 * \return Pointer to the object, NULL if not found
-	 */
+	  * @param[in] iID Object identifier
+	  * @return Pointer to the object, NULL if not found
+	  */
 	CVAObject* FindObjectByID( const int iID ) const;
 
 	//! Finds the object with the given name
 	/**
-	 * \return Pointer to the object, NULL if not found
-	 * \note Object names are case-sensitive
-	 */
+	  * @param[in] sName Object name
+	  * @return Pointer to the object, NULL if not found
+	  * @note Object names are case-sensitive
+	  */
 	CVAObject* FindObjectByName( const std::string& sName ) const;
 
 	//! Returns an object by its ID
 	/**
-	 * \return Pointer to the object
-	 * \note Throws an exception "invalid object ID" in case the object does not exist
-	 */
+	  * @param[in] iID Object identifier
+	  * @return Pointer to the object
+	  * @note Throws an exception "invalid object ID" in case the object does not exist
+	  */
 	CVAObject* GetObjectByID( const int iID ) const;
 
 	//! Returns the object with the given name
 	/**
-	 * \return Pointer to the object, if existing,
-	 * \note Throws an exception "unknown object" in case the object does not exist
-	 * \note Object names are case-sensitive
-	 */
+	  * @param[in] sName Object name
+	  * @return Pointer to the object, if existing,
+	  * @note Throws an exception "unknown object" in case the object does not exist
+	  * @note Object names are case-sensitive
+	  */
 	CVAObject* GetObjectByName( const std::string& sName ) const;
 
 	//! Calls an object determined by its ID
 	/**
-	 * \returns Throws an "invalid object ID" exception, if the object does not exist
-	 */
+	  * @param[in] iID Object identifier
+	  * @param[in] oArgs Object call arguments
+	  * @returns Throws an "invalid object ID" exception, if the object does not exist
+	  */
 	CVAStruct CallObjectByID( const int iID, const CVAStruct& oArgs ) const;
 
 	//! Calls an object determined by its name
 	/**
-	 * \returns Throws an "unknown object" exception, if the object does not exist
+	  * @param[in] sName Object name
+	  * @param[in] oArgs Object call arguments
+	 * @returns Throws an "unknown object" exception, if the object does not exist
 	 */
 	CVAStruct CallObjectByName( const std::string& sName, const CVAStruct& oArgs ) const;
 
 private:
-	std::vector< CVAObject* > m_vpObjects;				// Object table (O(1) lookups!)
-	std::map< std::string, CVAObject* > m_mpObjects;	// Fast name search structure (O(log N) queries!)
-	size_t m_nObjects;									// Number of registered objects
-	int m_iIDLast;										// ID counter
+	std::vector< CVAObject* > m_vpObjects;				//!< Object table (O(1) lookups!)
+	std::map< std::string, CVAObject* > m_mpObjects;	//!< Fast name search structure (O(log N) queries!)
+	size_t m_nObjects;									//!< Number of registered objects
+	int m_iIDLast;										//!< ID counter
 
 	friend class CVAObject;
 };

include/VASamples.h

@@ -31,18 +31,39 @@
 class VABASE_API CVASampleBuffer
 {
 public:
+	//! Constructor with empty samples
 	CVASampleBuffer();
+
+	//! Constructor for given number of samples
+	/**
+	  * @param[in] iNumSamples Number of samples
+	  * @param[in] bZeroInit Will init all samples to zero if true (default)
+	  */
 	CVASampleBuffer( const int iNumSamples, const bool bZeroInit = true );
-	CVASampleBuffer( const CVASampleBuffer& );
+
+	//! Copy constructor
+	/**
+	  * @param[in] oCopyFrom Copy data from this sample buffer
+	  */
+	CVASampleBuffer( const CVASampleBuffer& oCopyFrom );
 	virtual ~CVASampleBuffer();
 
 	//! Number of samples, zero if buffer is uninitialized
+	/**
+	  * @return Number of samples
+	  */
 	int GetNumSamples() const;
 
 	//! Pointer to first sample of buffer in memory
+	/**
+	  * @return Data pointer as float
+	  */
 	float* GetData();
 
 	//! Pointer to first sample of buffer in memory
+	/**
+	  * @return Read-only data pointer as float
+	  */
 	const float* GetDataReadOnly() const;
 
 	//! Sets all samples to zero
@@ -50,7 +71,12 @@ public:
 
 	std::vector< float > vfSamples; //!< Vector of audio samples, 32-bit floating point precision
 
-	CVASampleBuffer& operator=( const CVASampleBuffer& );
+	//! Assignment operator
+	/**
+	  * @param[in] oOther Other sample buffer
+	  * @return Sample buffer with assigned data from other sample buffer
+	  */
+	CVASampleBuffer& operator=( const CVASampleBuffer& oOther );
 };
 
 #endif // IW_VABASE_SAMPLES

include/VAStruct.h

@@ -30,133 +30,227 @@ class VABASE_API CVAStruct;
 class VABASE_API CVAStructValue;
 
 //! Case insensitive string comparison
-class VABASE_API compareStringCaseInsensitive
+class VABASE_API CompareStringCaseInsensitive
 {
 public:
+	//! Compare operator
+	/**
+	  * @param[in] a Left-hand string
+	  * @param[in] b Left-hand string
+	  * @return True, if strings are equal (ignoring case)
+	  */
 	inline bool operator()( const std::string& a, const std::string& b ) const
 	{
 		std::string la( a ), lb( b );
 		std::transform( la.begin(), la.end(), la.begin(), ::tolower );
 		std::transform( lb.begin(), lb.end(), lb.begin(), ::tolower );
 		return la < lb;
-	}
+	};
 };
 
 //! Associative array container
 /**
- * Associative array container, mapping a unique collection of
- * string keys to values. A variety of key values is supported,
- * for instance primitive types (bool, int, double, string).
- * Nesting is also supported by assigning keys another
- * associative array. Keys names are case-insensitive.
- * The class features simple and effective use by defining
- * data access and cast operators.
- * It can be efficiently serialized/deserialized,
- * making it a suitable container for message mechanisms.
- */
+  * Associative array container, mapping a unique collection of
+  * string keys to values. A variety of key values is supported,
+  * for instance primitive types (bool, int, double, string).
+  * Nesting is also supported by assigning keys another
+  * associative array. Keys names are case-insensitive.
+  * The class features simple and effective use by defining
+  * data access and cast operators.
+  * It can be efficiently serialized/deserialized,
+  * making it a suitable container for message mechanisms.
+  */
 class VABASE_API CVAStruct
 {
 public:
 	// Type aliases
-	typedef std::map< std::string, CVAStructValue, compareStringCaseInsensitive >::iterator iterator;
-	typedef std::map< std::string, CVAStructValue, compareStringCaseInsensitive >::const_iterator const_iterator;
+	typedef std::map< std::string, CVAStructValue, CompareStringCaseInsensitive >::iterator iterator;
+	typedef std::map< std::string, CVAStructValue, CompareStringCaseInsensitive >::const_iterator const_iterator;
 
-	// Literals
-	const static char DEFAULT_PATH_SEPARATOR = '/';