diff --git a/include/VAEventHandlerGlobalLock.h b/include/VAEventHandlerGlobalLock.h index 46cb8837df3d41c0e090f612db5677763a471d25..846cfaab479e2a20c58d4aa06a531803911f6175 100644 --- a/include/VAEventHandlerGlobalLock.h +++ b/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() {}; }; diff --git a/include/VAException.h b/include/VAException.h index d50d5b69bb29c6c8a4300e6de385c8942078410a..02696f455dc89eb10a8f319c16ad7dacdfffc274 100644 --- a/include/VAException.h +++ b/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 diff --git a/include/VAInterface.h b/include/VAInterface.h index adf12789dd008da199f0e870048bcdbd713cd8d8..fb4c859b9d468e1d4365f03be84266470941de22 100644 --- a/include/VAInterface.h +++ b/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; diff --git a/include/VAObject.h b/include/VAObject.h index c99aec7a710beb24eddfaab327db577c73f81643..18f237020fe901ce2aca50bf2ae24103adbc1313 100644 --- a/include/VAObject.h +++ b/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; }; diff --git a/include/VAObjectRegistry.h b/include/VAObjectRegistry.h index e4d42fbf52202c09822b09cd911ab98999b6571d..0820a42903e76235167e68ac4dc1cef6332ce53b 100644 --- a/include/VAObjectRegistry.h +++ b/include/VAObjectRegistry.h @@ -22,12 +22,13 @@ #include #include +// 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; }; diff --git a/include/VASamples.h b/include/VASamples.h index e152b054b70c876c1f26694bdae051a4a5553638..481db0332a3ef1d310a6f19d153db5e003e99e23 100644 --- a/include/VASamples.h +++ b/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 diff --git a/include/VAStruct.h b/include/VAStruct.h index 097522dc6a265c978bab905a74fe45d9f13189d4..204064e8bb41113b91be8ca28b1986fe2abc9dc6 100644 --- a/include/VAStruct.h +++ b/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 = '/'; + const static char DEFAULT_PATH_SEPARATOR = '/'; //!< Literals //! Default constructor CVAStruct(); //! Copy constructor - CVAStruct( const CVAStruct& ); + /** + * @param[in] oOther Other struct + */ + CVAStruct( const CVAStruct& oOther ); //! Destructor virtual ~CVAStruct(); //! Returns the number of keys (elements) + /** + * @return Number of keys / elements + */ int Size() const; //! Returns if the container is empty + /** + * @return True, if there are no keys + */ bool IsEmpty() const; //! Returns if the given key exists + /** + * @param[in] sKey Key as string + * @return True, if key is present + */ bool HasKey( const std::string& sKey ) const; //! Deletes all keys void Clear(); + //! Removes a key and its value (supports paths) + /** + * @param[in] sKey Key as string + * @return True, if key could be removed + */ bool RemoveKey( const std::string& sKey ); //! Return the pointer to a key (read-only) /** - * The key can be specified either by a name or a path. - * In the latter case the method traverses through the structure. - * - * \note This functions never creates a non-existent key - * \note This functions is more complex than GetKey(const std::string&) - * - * \return Valid pointer, if the given key exists, - * nullptr, otherwise - */ + * The key can be specified either by a name or a path. + * In the latter case the method traverses through the structure. + * + * @note This functions never creates a non-existent key + * @note This functions is more complex than GetKey(const std::string&) + * + * @param[in] sPath Path + * @param[in] cPathSeparator Path seperator, either "/" (default) or "\" + * + * @return Valid pointer, if the given key exists, nullptr otherwise + */ const CVAStructValue* GetValue( const std::string& sPath, const char cPathSeparator = DEFAULT_PATH_SEPARATOR ) const; //! Return the pointer to a key (read-write) /** - * The key can be specified either by a name or a path. - * In the latter case the method traverses through the structure. - * - * \note This functions never creates a non-existent key - * \note This functions is more complex than GetKey(const std::string&) - * - * \return Valid pointer, if the given key exists, - * nullptr, otherwise - */ + * The key can be specified either by a name or a path. + * In the latter case the method traverses through the structure. + * + * @param[in] sPath Path + * @param[in] cPathSeparator Path seperator, either "/" (default) or "\" + * @note This functions never creates a non-existent key + * @note This functions is more complex than GetKey(const std::string&) + * + * @return Valid pointer, if the given key exists, nullptr otherwise + */ CVAStructValue* GetValue( const std::string& sPath, const char cPathSeparator = DEFAULT_PATH_SEPARATOR ); //! Read-only data access + /** + * @param[in] pcKey Key as character pointer + * @return Struct value of this key + * @note Will raise CVAEception on error + */ const CVAStructValue& operator[]( const char* pcKey ) const; + + //! Read-only data access + /** + * @param[in] sKey Key as string + * @return Struct value of this key + * @note Will raise CVAEception on error + */ inline const CVAStructValue& operator[]( const std::string& sKey ) const { - return ( *this )[ sKey.c_str() ]; + return ( *this )[ sKey.c_str() ]; }; //! Read/write data access + /** + * @param[in] pcKey Key as character pointer + * @return Struct value of this key + * @note Will raise CVAEception on error + */ CVAStructValue& operator[]( const char* pcKey ); + + //! Read/write data access + /** + * @param[in] sKey Key as string + * @return Struct value of this key + * @note Will raise CVAEception on error + */ inline CVAStructValue& operator[]( const std::string& sKey ) { return ( *this )[ sKey.c_str() ]; }; //! Assignment + /** + * @param[in] rhs Right hand side struct + * @return Assigned struct + */ CVAStruct& operator=( const CVAStruct& rhs ); - //! Iterator pattern + //! Iterator pattern begin + /** + * @return Iterator beginning + */ CVAStruct::iterator Begin(); + + //! Const iterator pattern begin + /** + * @return Const iterator beginning + */ CVAStruct::const_iterator Begin() const; + + //! Iterator pattern end + /** + * @return Const iterator end + */ CVAStruct::iterator End(); + + //! Const iterator pattern end + /** + * @return Const iterator end + */ CVAStruct::const_iterator End() const; //! Merge struct with another one + /** + * @param[in] rhs Right hand side struct where to merge from + * @param[in] bUnique Raise exception in case uniqueness is violated + */ void Merge( const CVAStruct& rhs, const bool bUnique = true ); //! Return a string representation of the container + /** + * @param[in] iIndent Indentation for printing + * @return Formatted string + */ std::string ToString( const int iIndent = 0 ) const; private: - typedef std::map Map; - typedef Map::const_iterator MapCit; - typedef Map::iterator MapIt; - Map m_mData; + typedef std::map Map; //!< Key-value map typedef + typedef Map::const_iterator MapCit; //!< Map const iterator typedef + typedef Map::iterator MapIt; //!< Map iterator typedef + + Map m_mData; //!< Internal key-value data map - // Traversal methods + //! Traversal methods for read-only access + /** + * @param[in] sPath Path + * @param[in] iPathCursor Path cursor + * @param[in] cPathSeparator Path separator + * @return Pointer to struct value + */ const CVAStructValue* Traverse( const std::string& sPath, size_t iPathCursor = 0, const char cPathSeparator = DEFAULT_PATH_SEPARATOR ) const; + + //! Traversal methods + /** + * @param[in] sPath Path + * @param[in] iPathCursor Path cursor + * @param[in] cPathSeparator Path separator + * @return Pointer to struct value + */ CVAStructValue* Traverse( const std::string& sPath, size_t iPathCursor = 0, const char cPathSeparator = DEFAULT_PATH_SEPARATOR ); }; //! Associative array value class /** - * This class realized keys is the associative array CVAStruct - */ - + * This class realized keys is the associative array CVAStruct + */ class VABASE_API CVAStructValue { public: @@ -177,65 +271,232 @@ public: CVAStructValue(); //! Initialization constructors + /** + * @param[in] value Value as bool + */ CVAStructValue( const bool value ); + + //! Initialization constructors + /** + * @param[in] value Value as int + */ CVAStructValue( const int value ); + + //! Initialization constructors + /** + * @param[in] value Value as double + */ CVAStructValue( const double value ); + + //! Initialization constructors + /** + * @param[in] value Value as character pointer + */ CVAStructValue( const char* value ); + + //! Initialization constructors + /** + * @param[in] value Value as string + */ CVAStructValue( const std::string& value ); + + //! Initialization constructors + /** + * @param[in] value Value as another struct (nested object) + */ CVAStructValue( const CVAStruct& value ); + + //! Initialization constructors + /** + * @param[in] pData Value as byte array (data pointer) + * @param[in] iBytes Value byte count + */ CVAStructValue( void* pData, const int iBytes ); - CVAStructValue( const CVASampleBuffer& ); + + //! Initialization constructors + /** + * @param[in] value Value + */ + CVAStructValue( const CVASampleBuffer& value ); //! Copy constructor - CVAStructValue( const CVAStructValue& ); + /** + * @param[in] oOther Copy from struct value + */ + CVAStructValue( const CVAStructValue& oOther ); //! Destructor virtual ~CVAStructValue(); //! Returns the datatype of the key + /** + * @return Data type identifier + */ int GetDatatype() const; //! Returns the data size in bytes (only for datatype DATA) + /** + * @return Data size number (bytes) + */ int GetDataSize() const; //! Returns a pointer to the data (only for datatype DATA) + /** + * @return Generic pointer in data (read-only) + */ const void* GetData() const; + + //! Returns a pointer to the data (only for datatype DATA) + /** + * @return Generic pointer in data + */ void* GetData(); //! Sets the data (only for datatype DATA) + /** + * @param[in] pData Data pointer + * @param[in] iBytes Number of bytes + */ void SetData( void* pData, const int iBytes ); //! Returns a pointer to the struct value (only for datatype STRUCT) + /** + * @return Struct value read-only + */ const CVAStruct& GetStruct() const; + + //! Returns a const pointer to the struct value (only for datatype STRUCT) + /** + * @return Struct value + */ CVAStruct& GetStruct(); //! Test functions for datatypes - bool IsAssigned() const; // Datatype has been assigned + /** + * @return True, if data type has been assigned + */ + bool IsAssigned() const; + + //! Data type is boolean + /** + * @return True, if type matches + */ bool IsBool() const; + + //! Data type is integer + /** + * @return True, if type matches + */ bool IsInt() const; + + //! Data type is double + /** + * @return True, if type matches + */ bool IsDouble() const; + + //! Data type is string + /** + * @return True, if type matches + */ bool IsString() const; + + //! Data type is struct + /** + * @return True, if type matches + */ bool IsStruct() const; - bool IsNumeric() const; // Int | Double + + //! Data type is integer or double + /** + * @return True, if type matches + */ + bool IsNumeric() const; + + //! Data type is data + /** + * @return True, if type matches + */ bool IsData() const; + + //! Data type is sample buffer + /** + * @return True, if type matches + */ bool IsSampleBuffer() const; - //! Assignment operators - CVAStructValue& operator=( const CVAStructValue& ); - CVAStructValue& operator=( const bool ); - CVAStructValue& operator=( const int ); - CVAStructValue& operator=( const double ); - CVAStructValue& operator=( const char* ); - CVAStructValue& operator=( const std::string& ); - CVAStructValue& operator=( const CVASampleBuffer& ); + //! Assignment operators for type struct value + /** + * @param[in] v Value as struct + * @return Struct value + */ + CVAStructValue& operator=( const CVAStructValue& v ); + + //! Assignment operators for type bool value + /** + * @param[in] v Value as bool + * @return Struct value + */ + CVAStructValue& operator=( const bool v ); + + //! Assignment operators for type int value + /** + * @param[in] v Value as int + * @return Struct value + */ + CVAStructValue& operator=( const int v ); + + //! Assignment operators for type double value + /** + * @param[in] v Value as double + * @return Struct value + */ + CVAStructValue& operator=( const double v ); + + //! Assignment operators for type character pointer value + /** + * @param[in] v Value as character pointer + * @return Struct value + */ + CVAStructValue& operator=( const char* v ); + + //! Assignment operators for type string value + /** + * @param[in] v Value as string + * @return Struct value + */ + CVAStructValue& operator=( const std::string& v ); + + //! Assignment operators for type sample buffer value + /** + * @param[in] v Value as sample buffer + * @return Struct value + */ + CVAStructValue& operator=( const CVASampleBuffer& v ); //! Read-only data access - // Note: Is applicable only for struct keys + /** + * @note Is applicable only for struct keys. Also raises CVAException on error. + * @param[in] pcKey Key as char pointer + * @return Struct value + */ const CVAStructValue& operator[]( const char* pcKey ) const; //! Read/write data access - // Note: Is applicable only for struct keys + /** + * @note Is applicable only for struct keys. Also raises CVAException on error. + * @param[in] pcKey Key as char pointer + * @return Struct value + */ CVAStructValue& operator[]( const char* pcKey ); + + //! Read/write data access via string key + /** + * @note Is applicable only for struct keys. Also raises CVAException on error. + } + * @param[in] sKey Key as string + * @return Struct value + */ inline CVAStructValue& operator[]( const std::string& sKey ) { return ( *this )[ sKey.c_str() ]; @@ -262,33 +523,48 @@ public: //! Cast to sample buffer operator CVASampleBuffer&( ); - //! Cast to CVAStruct (required for assignments of the form 'CVAStruct = CVAStructKey') + //! Cast to const CVAStruct (required for assignments of the form 'CVAStruct = CVAStructKey') operator const CVAStruct&( ) const; + + //! Cast to CVAStruct (required for assignments of the form 'CVAStruct = CVAStructKey') operator CVAStruct&( ); //! Return a string representation of the key + /** + * @return Formatted string + */ std::string ToString() const; private: - int iDatatype; - const std::string* psKey; // Back-reference to the keys name - - bool bValue; - int iValue; - double dValue; - std::string sValue; - CVAStruct* xValue; - void* pData; - int iDataSize; - CVASampleBuffer sbValue; + int iDatatype; //!< Data type + const std::string* psKey; //!< Back-reference to the keys name + + bool bValue; //!< Value if type is bool + int iValue; //!< Value if type is int + double dValue; //!< Value if type is double + std::string sValue; //!< Value if type is string + CVAStruct* xValue; //!< Value if type is struct + void* pData; //!< Value if type is data + int iDataSize; //!< Value byte number if type is data + CVASampleBuffer sbValue; //!< Value if type is sample buffer friend class CVAStruct; }; //! STL stream output operator +/** + * @param[in] os Outstream object + * @param[in] s Struct value + * @return Outstream with info attached + */ VABASE_API std::ostream& operator<<( std::ostream& os, const CVAStruct& s ); //! STL stream output operator +/** + * @param[in] os Outstream object + * @param[in] key Struct value read-only + * @return Outstream with info attached + */ VABASE_API std::ostream& operator<<( std::ostream& os, const CVAStructValue& key ); #endif // IW_VABASE_STRUCT diff --git a/include/VAVersion.h b/include/VAVersion.h index 0775bc545feaffe516bc964c736660920bdd6d72..3a2108e7ba45247e3ad3360ec2bf077e08dec6fc 100644 --- a/include/VAVersion.h +++ b/include/VAVersion.h @@ -17,18 +17,22 @@ #include #include +//! Version info data class /** - * Diese Datenklasse beschreibt Versionsinformationen über den VA-Kern - */ + * Class describing version info of VA components + */ class VABASE_API CVAVersionInfo { public: - std::string sVersion; // Version als Zeichenkette (z.B. "1.02") - std::string sDate; // Datum der Erstellung bzw. Veröffentlichung - std::string sFlags; // Liste der Eigenschaften (flags) (z.B. "Debug", "SSE2") - std::string sComments; // Zusätzliche Kommentate (z.B. "Special Pentium-H build"); + std::string sVersion; //!< Version as string (e.g. "1.02") + std::string sDate; //!< Date of creation / publiching date + std::string sFlags; //!< List of properties (flags) (e.g. "debug", "SSE2") + std::string sComments; //!< Additional comments //! Als Zeichenkette zurückgeben + /** + * @return Version info as formatted string + */ std::string ToString() const; }; diff --git a/src/VAException.cpp b/src/VAException.cpp index afa753cbd2e78ecc459f06360f7320096750c23d..6a290c0f64fa7a35131287f80bd2b3bc7d8bae2b 100644 --- a/src/VAException.cpp +++ b/src/VAException.cpp @@ -16,10 +16,15 @@ #include CVAException::CVAException() -: m_iErrorCode(UNSPECIFIED) {} + : m_iErrorCode( UNSPECIFIED ) +{ +} -CVAException::CVAException(int iErrorCode, const std::string& sErrorMessage) -: m_iErrorCode(iErrorCode), m_sErrorMessage(sErrorMessage) {} +CVAException::CVAException( const int iErrorCode, const std::string& sErrorMessage ) + : m_iErrorCode( iErrorCode ) + , m_sErrorMessage( sErrorMessage ) +{ +} CVAException::~CVAException() {} @@ -29,49 +34,50 @@ std::string CVAException::GetErrorMessage() const { return m_sErrorMessage; } std::string CVAException::ToString() const { std::stringstream ss; - - switch (m_iErrorCode) { + + switch( m_iErrorCode ) { case MODAL_ERROR: - if (m_iErrorCode != 0) + if( m_iErrorCode != 0 ) ss << "Modal error: " << m_sErrorMessage << " (error code " << m_iErrorCode << ")"; else ss << "Modal error: " << m_sErrorMessage; break; case NETWORK_ERROR: - if (m_iErrorCode != 0) + if( m_iErrorCode != 0 ) ss << "Network error: " << m_sErrorMessage << " (error code " << m_iErrorCode << ")"; else ss << "Network error: " << m_sErrorMessage; break; case PROTOCOL_ERROR: - if (m_iErrorCode != 0) + if( m_iErrorCode != 0 ) ss << "Network protocol error: " << m_sErrorMessage << " (error code " << m_iErrorCode << ")"; else ss << "Network protocol error: " << m_sErrorMessage; break; - // Alle anderen bekannten Fehler + // Alle anderen bekannten Fehler case NOT_IMPLEMENTED: case INVALID_PARAMETER: case INVALID_ID: case RESOURCE_IN_USE: case FILE_NOT_FOUND: - if (m_iErrorCode != 0) + if( m_iErrorCode != 0 ) ss << m_sErrorMessage << " (error code " << m_iErrorCode << ")"; else ss << m_sErrorMessage; break; default: - if (m_sErrorMessage.empty()) { - if (m_iErrorCode != 0) + if( m_sErrorMessage.empty() ) { + if( m_iErrorCode != 0 ) ss << "An unspecified error occured (error code " << m_iErrorCode << ")"; else ss << "An unspecified error occured"; - } else { - if (m_iErrorCode != 0) + } + else { + if( m_iErrorCode != 0 ) ss << m_sErrorMessage << " (error code " << m_iErrorCode << ")"; else ss << m_sErrorMessage; @@ -82,6 +88,6 @@ std::string CVAException::ToString() const { return ss.str(); } -std::ostream& operator<<(std::ostream& os, const CVAException& ex) { +std::ostream& operator<<( std::ostream& os, const CVAException& ex ) { return os << ex.ToString(); }