Aufgrund einer Störung des s3 Storage, könnten in nächster Zeit folgende GitLab Funktionen nicht zur Verfügung stehen: Container Registry, Job Artifacs,. Wir bitten um Verständnis. Es wird mit Hochdruck an der Behebung des Problems gearbeitet. Weitere Informationen zur Störung des Object Storage finden Sie hier: https://maintenance.itc.rwth-aachen.de/ticket/status/messages/59-object-storage-pilot

Commit 97ef3d5f authored by Dipl.-Ing. Jonas Stienen's avatar Dipl.-Ing. Jonas Stienen
Browse files

A lot of doxy style comments

parent 059bf547
......@@ -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() {};
};
......
......@@ -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
......@@ -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;
......
......@@ -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;
};
......
......@@ -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.