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

Mergin conflict ready

parents 76e13fc5 97ef3d5f
......@@ -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
......
......@@ -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;
......
......@@ -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 )
......
......@@ -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
......@@ -14,10 +14,12 @@
#ifndef IW_VABASE_INTERFACE
#define IW_VABASE_INTERFACE
// VA includes
#include <VABaseDefinitions.h>
#include <VABase.h>
#include <VASamples.h>
// STL includes
#include <string>
#include <vector>
......@@ -28,7 +30,7 @@ class VABASE_API CVAStruct;
class VABASE_API IVAEventHandler;
class VABASE_API IVAAudioSignalSource;
//! Interface of the VA
//! Interface of Virtual Acoustics (VA)
/**
* This mostly abstract interface to VA describes all relevant functions and methods
* that have to be implemented to comply with a VA controller instance or core instance.
......@@ -128,7 +130,7 @@ public:
//! Destructor
/**
* \note If the core was not finialized until the time of its destruction,
* @note If the core was not finialized until the time of its destruction,
* the destructor will attempt to implicitly finalize it here.
* Remember that you should always finialize a core, so that you can
* track errors.
......@@ -199,7 +201,7 @@ public:
//! Attaches a handler for core events to the core instance
/**
* @oaram[in] pEventHandler Event handler pointer
* @param[in] pEventHandler Event handler pointer
* @note Attaching event handlers it always possible,
* regardless of the state of the core.
* This method can therefore be called anytime,
......@@ -209,7 +211,7 @@ public:
//! Detaches a handler for core events from the core instance
/**
* @oaram[in] pEventHandler Event handler pointer
* @param[in] pEventHandler Event handler pointer
* @note Detaching event handlers it always possible,
* regardless of the state of the core.
* This method can therefore be called anytime,
......@@ -261,7 +263,7 @@ public:
*
* @return Encapsulated file paths
*
* @warn This call may take a while and can result in a lot of return data.
* @warning This call may take a while and can result in a lot of return data.
*/
virtual CVAStruct GetFileList( const bool bRecursive = true, const std::string& sFileSuffixFilter = "*" ) const = 0;
......@@ -349,6 +351,7 @@ public:
//! Directivity parameter getter
/**
* @param[in] iID Identifier
* @param[in] oParams Parameters
* @return Parameters
*/
virtual CVAStruct GetDirectivityParameters( const int iID, const CVAStruct& oParams ) const = 0;
......@@ -483,7 +486,7 @@ public:
//! Get geometry mesh ids
/**
* @param[out] viID All available geometry mesh identifiers
* @param[out] viIDs All available geometry mesh identifiers
*
*/
virtual void GetGeometryMeshIDs( std::vector< int >& viIDs ) const = 0;
......@@ -539,17 +542,15 @@ public:
virtual bool GetGeometryMeshEnabled( const int iID ) const = 0;
//! Creates an audiofile signal source
//! Creates a buffer signal source from an audio file
/**
* Creates a signal source which streams the samples of an audiofile.
* The audiofile must be mono and its sampling rate must match that
* of the core.
*
* \param sFilePath Filename/path
* \param sName Name (optional, e.g. "Trumpet")
*
* \return Signal source ID
*/
* Creates a signal source which streams the samples of an audiofile.
*
* @param[in] sFilePath Filename, file path, macro, ...
* @param[in] sName Name (optional, e.g. "Trumpet")
*
* @return Signal source ID
*/
inline std::string CreateSignalSourceBufferFromFile( const std::string& sFilePath, const std::string& sName = "" )
{
CVAStruct oParams;
......@@ -557,17 +558,15 @@ public:
return CreateSignalSourceBufferFromParameters( oParams, sName );
};
//! Creates an audiofile signal source
//! Creates a mono buffer signal source from sample buffer
/**
* Creates a signal source which streams the samples of an audiofile.
* The audiofile must be mono and its sampling rate must match that
* of the core.
*
* \param sFilePath Filename/path
* \param sName Name (optional, e.g. "Trumpet")
*
* \return Signal source ID
*/
* Creates a signal source which streams the samples of a buffer.
*
* @param[in] oSamples Buffer samples
* @param[in] sName Name (optional, e.g. "Trumpet")
*
* @return Signal source ID
*/
virtual std::string CreateSignalSourceBufferFromSamples( const CVASampleBuffer& oSamples, const std::string& sName = "" )
{
CVAStruct oParams;
......@@ -575,6 +574,16 @@ public:
return CreateSignalSourceBufferFromParameters( oParams, sName );
};
//! Creates a multi-channel buffer signal source from sample buffer
/**
* Creates a signal source which streams the samples of a buffer with more than one channel.
* Useful for prototyping, i.e. for switching channels during playback or mixing.
*
* @param[in] voSamples Buffer sample vector
* @param[in] sName Name (optional, e.g. "Trumpet")
*
* @return Signal source ID
*/
inline std::string CreateSignalSourceBufferMultichannelFromSamples( const std::vector< CVASampleBuffer >& voSamples, const std::string& sName = "" )
{
CVAStruct oParams;
......@@ -583,6 +592,16 @@ public:
return CreateSignalSourceBufferFromParameters( oParams, sName );
};
//! Creates a buffer signal source from parameters
/**
* Creates a signal source which streams the samples of a buffer that is created based on magic parameters.
* Useful for prototyping, i.e. if a special signal source type is required and no interface change should be performed.
*
* @param[in] oParams Buffer signal source magic parameters
* @param[in] sName Name (optional, e.g. "Prototype Trumpet")
*
* @return Signal source ID
*/
virtual std::string CreateSignalSourceBufferFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
//! Creates a text-to-speech (TTS) signal source
......@@ -599,9 +618,9 @@ public:
/**
* Creates a sequencer signal source.
*
* \param sName Name (optional, e.g. "Sequencer 1")
* @param[in] sName Name (optional, e.g. "Sequencer 1")
*
* \return Signal source ID
* @return Signal source ID
*/
virtual std::string CreateSignalSourceSequencer( const std::string& sName = "" ) = 0;
......@@ -610,7 +629,7 @@ public:
* Creates a signal source which receives audio samples via network.
* Therefore an IP socket is set up with the given parameters.
*
* @param[in] sInterface IP address of the socket (e.g. 127.0.0.1, no hostnames!)
* @param[in] sInterface IP address of the socket
* @param[in] iPort Destination port on which samples are received
* @param[in] sName Optional name
*
......@@ -622,94 +641,110 @@ public:
//! Creates a rotating engine source
/**
* \param sName Name of the engine
* \return ID of signal source
* @param[in] oParams Parameters
* @param[in] sName Name of the engine
* @return ID of signal source
*/
virtual std::string CreateSignalSourceEngine( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
//! Creates a machine signal source
/**
* \param sName Name of the machine
* @param[in] oParams Parameters
* @param[in] sName Name of the machine
*@return Signal source identifier
*/
virtual std::string CreateSignalSourceMachine( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
//! Deletes a signal source
/**
* Deletes a signal source. This is only possible if it is not in use.
*
* \return true, if the signal source has been deleted
* false, otherwise
*/
* Deletes a signal source. This is only possible if it is not in use.
*
* @return True, if the signal source has been deleted, false otherwise
*/
virtual bool DeleteSignalSource( const std::string& sID ) = 0;
//! Registers an (external) signal source with the core
/**
* This method registers a signal source which is not created and managed
* by the core. The core assignes it an ID, which makes it usable for
* auralization.
*
* \param pSource Signal source instance
* \param sName Name (optional, z.B. "My tone generator")
*
* \return Signal source ID
*
* \note This function is only locally available, but not remote
*/
* This method registers a signal source which is not created and managed
* by the core. The core assignes it an ID, which makes it usable for
* auralization.
*
* @param[in] pSignalSource Signal source instance
* @param[in] sName Name (optional, z.B. "My tone generator")
*
* @return Signal source ID
*
* @note This function is only locally available, but not for remote connections
*/
virtual std::string RegisterSignalSource( IVAAudioSignalSource* pSignalSource, const std::string& sName = "" ) = 0;
//! Unregisters an (external) signal source from the core
/**
* Unregisters an (external) signal source from the core.
* This is only possible, if the signal source is not in use.
*
* \param pSource Signal source instance
*
* \return true, if the signal source has been unregistered
* false, otherwise
*
* \note This function is only locally available, but not remote
*/
* Unregisters an (external) signal source from the core.
* This is only possible, if the signal source is not in use.
*
* @param[in] pSignalSource Signal source instance
*
* @return true, if the signal source has been unregistered, false otherwise
*
* @note This function is only locally available, but not remote
*/
virtual bool UnregisterSignalSource( IVAAudioSignalSource* pSignalSource ) = 0;
//! Retrieves information of a signal source
/**
* @param[in] sSignalSourceID Signal source identifier
* @return Signal source information
*/
virtual CVASignalSourceInfo GetSignalSourceInfo( const std::string& sSignalSourceID ) const = 0;
//! Retrieves information of all signal sources
/**
* @param[in] voInfos Signal source info vector
*/
virtual void GetSignalSourceInfos( std::vector< CVASignalSourceInfo >& voInfos ) const = 0;
//! Returns the playback state flag (bit-vector) of an audiofile signal source
/**
* @param[in] sSignalSourceID Signal source identifier
* @return Playback state integer
*/
virtual int GetSignalSourceBufferPlaybackState( const std::string& sSignalSourceID ) const = 0;
//! Set the playback state of an audiofile signal source
/**
* Start, stop or pause the playback of an audiofile using the playback action flags (bit-vector).
*
* @param[in] sSignalSourceID Signal source identifier
* @param[in] iPlaybackAction Playback action integer
*/
virtual void SetSignalSourceBufferPlaybackAction( const std::string& sSignalSourceID, const int iPlaybackAction ) = 0;
//! Set the playback position of an audiofile signal source
/**
* \param sSignalSourceID Signal source ID
* \param dPlaybackPosition Playback position [s]
*/
* @param[in] sSignalSourceID Signal source ID
* @param[in] dPlaybackPosition Playback position [s]
*/
virtual void SetSignalSourceBufferPlaybackPosition( const std::string& sSignalSourceID, const double dPlaybackPosition ) = 0;
//! Set playback looping mode (true = looping)
/**
* \param sSignalSourceID Signal source ID
* \param bLooping Playback is looping
*/
* @param[in] sSignalSourceID Signal source ID
* @param[in] bLooping Playback is looping, if set true
*/
virtual void SetSignalSourceBufferLooping( const std::string& sSignalSourceID, const bool bLooping = true ) = 0;
//! Get playback looping mode (true = looping)
/**
* \param sSignalSourceID Signal source ID
*/
* @param[in] sSignalSourceID Signal source ID
* @return True, if looping is enabled
*/
virtual bool GetSignalSourceBufferLooping( const std::string& sSignalSourceID ) const = 0;
//! Starts the signal of a machine source
/**
* \param sSignalSourceID Signal source ID
*/