More doxy style comments and some method renaming

include/VAInterface.h

@@ -1263,23 +1263,69 @@ public:
 
 	//! Returns all available renderers (default: only those that are enabled)
 	/**
-	* @param [out]	voRenderer	List of renderers modules
-	* @param [in]	bFilterEnabled	If true, only enabled renderers are returned (via configuration, during runtime)
-	*/
+	  * @param [out]	voRenderer	List of renderers modules
+	  * @param [in]	bFilterEnabled	If true, only enabled renderers are returned (via configuration, during runtime)
+	  */
 	virtual void GetRenderingModules( std::vector< CVAAudioRendererInfo >& voRenderer, const bool bFilterEnabled = true ) const = 0;
 
-	//! Mutes a rendering module audio output
+	//! Mutes/unmutes a rendering module audio output
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @param[in] bMuted Mutes module, if true, unmutes otherwise
+	  */
 	virtual void SetRenderingModuleMuted( const std::string& sModuleID, const bool bMuted = true ) = 0;
 
 	//! Returns if rendering module audio output is muted or not
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @return True, if module muted, false otherwise
+	  */
 	virtual bool GetRenderingModuleMuted( const std::string& sModuleID ) const = 0;
 
 	//! Sets the rendering module audio output gain
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @param[in] dGain Gain
+	  *
+	  * @warn Setting gains will potentially penetrate a calibrated rendering and reproduction chain
+	  */
 	virtual void SetRenderingModuleGain( const std::string& sModuleID, const double dGain ) = 0;
 
 	//! Returns the rendering module audio output gain
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @return Gain
+	  */
 	virtual double GetRenderingModuleGain( const std::string& sModuleID ) const = 0;
 
+	//! Sets the rendering module auralization mode
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @param[in] iAuralizationMode Auralization mode integer
+	  */
+	virtual void SetRenderingModuleAuralizationMode( const std::string& sModuleID, const int iAuralizationMode ) = 0;
+
+	//! Returns the rendering module auralization mode
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @return Auralization mode bit-vector
+	  */
+	virtual int GetRenderingModuleAuralizationMode( const std::string& sModuleID ) const = 0;
+
+	//! Sets the rendering module parameters
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @param[in] oParams Magic parameters
+	  */
+	virtual void SetRenderingModuleParameters( const std::string& sModuleID, const CVAStruct& oParams ) = 0;
+
+	//! Returns the rendering module parameters
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @retirn Magic parameters
+	  */
+	virtual CVAStruct GetRenderingModuleParameters( const std::string& sModuleID ) const = 0;
+
 
 	//! Returns all available reproductions (default: only those that are enabled)
 	/**
@@ -1288,52 +1334,116 @@ public:
 	 */
 	virtual void GetReproductionModules( std::vector< CVAAudioReproductionInfo >& voReproductions, const bool bFilterEnabled = true ) const = 0;
 
-	//! Mutes a rendering module audio output
+	//! Mutes/unmutes a rendering module audio output
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @param[in] bMuted Mutes module, if true, unmutes otherwise
+	  */
 	virtual void SetReproductionModuleMuted( const std::string& sModuleID, const bool bMuted = true ) = 0;
 
 	//! Returns if rendering module audio output is muted or not
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @return True, if module muted, false otherwise
+	  */
 	virtual bool GetReproductionModuleMuted( const std::string& sModuleID ) const = 0;
 
-	//! Sets the rendering module audio output gain
+	//! Sets the reproduction module audio output gain
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @param[in] dGain Gain factor
+	  *
+	  * @warn Setting gains will potentially penetrate a calibrated rendering and reproduction chain
+	  */
 	virtual void SetReproductionModuleGain( const std::string& sModuleID, const double dGain ) = 0;
 
 	//! Returns the rendering module audio output gain
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @return Gain factor
+	  */
 	virtual double GetReproductionModuleGain( const std::string& sModuleID ) const = 0;
+	
+	//! Sets the reproduction module parameters
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @param[in] oParams Magic parameters
+	  */
+	virtual void SetReproductionModuleParameters( const std::string& sModuleID, const CVAStruct& oParams ) = 0;
+	
+	//! Returns the reproduction module parameters
+	/**
+	  * @param[in] sModuleID Module identifier
+	  * @retirn Magic parameters
+	  */
+	virtual CVAStruct GetReproductionModuleParameters( const std::string& sModuleID ) const = 0;
 
-
-	//! Verstärkung der Eingangkanäle (Geräteeingang) zurückgeben [Faktor] 
+	
+	//! Returns the global audio interface input gain
+	/**
+	  * @return Gain factor
+	  */
 	virtual double GetInputGain() const = 0;
-
-	//! Verstärkung der Eingangkanäle (Geräteeingang) setzen [Faktor] 
+	
+	//! Sets the global audio interface input gain
+	/**
+	  * @param[in] dGain Gain factor [0 .. 1]
+	  *
+	  * @warn Setting gains will potentially penetrate a calibrated rendering and reproduction chain
+	  */
 	virtual void SetInputGain( const double dGain ) = 0;
-
-	//! Status der Stummschaltung der Audioeingänge zurückgeben
+	
+	//! Returns if global audio interface input is muted or not
+	/**
+	  * @return True, if muted, false otherwise
+	  */
 	virtual bool GetInputMuted() const = 0;
-
-	//! Stummschaltung der Audioeingänge ein-/ausschalten
+	
+	//! Mutes global audio interface input
+	/**
+	  * @param[in] bMuted Mutes global input if true, unmutes otherwise
+	  */
 	virtual void SetInputMuted( const bool bMuted = true ) = 0;
-
-	//! Globale Ausgabeverstärkung [Faktor] zurückgeben
+	
+	//! Returns the global audio interface output gain
+	/**
+	  * @return Gain factor
+	  */
 	virtual double GetOutputGain() const = 0;
 
-	//! Globale Ausgabeverstärkung [Faktor] setzen
+	//! Sets the global audio interface output gain
+	/**
+	  * @param[in] dGain Gain factor [0 .. 1]
+	  *
+	  * @warn Setting gains will potentially penetrate a calibrated rendering and reproduction chain
+	  */
 	virtual void SetOutputGain( const double dGain ) = 0;
-
-	//! Status der globalen Stummschaltung zurückgeben
+	
+	//! Returns if global audio interface output is muted or not
+	/**
+	  * @return True, if muted, false otherwise
+	  */
 	virtual bool GetOutputMuted() const = 0;
 
-	//! Globale Stummschaltung ein-/ausschalten
+	//! Sets the global audio interface input gain
+	/**
+	  * @param[in] dGain Gain factor [0 .. 1]
+	  *
+	  * @warn Setting gains will potentially penetrate a calibrated rendering and reproduction chain
+	  */
 	virtual void SetOutputMuted( const bool bMuted = true ) = 0;
 
-	//! Globalen Auralisierungmodus zurückgeben
+	
+	//! Returns the global auralization mode
+	/**
+	  * @return Auralization mode bit-vector
+	  */
 	virtual int GetGlobalAuralizationMode() const = 0;
-
-	//! Globalen Auralisierungmodus setzen
+	
+	//! Sets the global auralization mode
 	/**
-	 * Dieser Modus fungiert wie ein Filter. Wenn hier eine Komponente
-	 * deaktiviert wird, gilt dies für alle Schallquellen und Hörer.
-	 * Umgekehrt aber nicht.
-	 */
+	  * @param[in] iAuralizationMode Auralization mode integer (bit-vector)
+	  */
 	virtual void SetGlobalAuralizationMode( const int iAuralizationMode ) = 0;
 
 	//! Returns the (global) active sound receiver
@@ -1385,72 +1495,135 @@ public:
 
 	//! Get current core time
 	/**
-	 * This method returns the current clock of the core instance in seconds.
-	 * This Clock is offset-cleaned from Stream Tracker, which uses the default clock
-	 */
+	  * This method returns the current clock of the core instance in seconds.
+	  * This Clock is offset-cleaned from Stream Tracker, which uses the default clock
+	  *
+	  * @return Clock time in seconds
+	  */
 	virtual double GetCoreClock() const = 0;
 
 	//! Set core time
 	/**
-	 * This methods (re)sets the core time to the given value in seconds.
-	 * The new value must be a number greater or equal zero.
-	 */
+	  * This methods (re)sets the core time to the given value in seconds.
+	  * The new value must be a number greater or equal zero.
+	  *
+	  * @param[in] dSeconds Clock time in seconds
+	  */
 	virtual void SetCoreClock( const double dSeconds ) = 0;
 
 	//! Substitute VA core macro definitions in a string (e.g. a filename)
+	/**
+	  * @param[in] sStr String with macro
+	  * @return String where macros have been substituted, if macro has been set
+	  */
 	virtual std::string SubstituteMacros( const std::string& sStr ) const = 0;
 
 	//! Searches for the file and returns full path (relative or absolute)
 	/**
-	  * \param sFilePath non-empty relative file path
-	  * \return If found, first valid combined file path; empty string otherwise
+	  * @param[in] sFilePath non-empty relative file path
+	  * @return If found, first valid combined file path; empty string otherwise
 	  *
-	  * \note Also substitutes macros
-	  * \note Prints a warning if file not found or ambiguous name
+	  * @note Also substitutes macros
+	  * @note Prints a warning if file not found or ambiguous name
 	  */
 	virtual std::string FindFilePath( const std::string& sFilePath ) const = 0;
 
 
-	static bool IsValidAuralizationMode( const int iAuralizationMode );
-	static bool IsValidVolume( const double dVolume );
-	static bool IsValidAudiofileSignalSourcePlaybackAction( const int iAction );
 
+	//! Auralization mode bit-vector validation
+	/**
+	  * @param[in] iAuralizationMode Auralization bit-vector
+	  * @return True, if auralization bit-vector is valid (positive bits are reflecting a mode)
+	  */
+	static bool GetAuralizationModeValid( const int iAuralizationMode );
+	
+	//! Checks if volume value is positive
+	/**
+	  * @param[in] dVolume Auralization bit-vector
+	  * @return True, if volume is valid (greater zero)
+	  */
+	static bool GetVolumeValid( const double dVolume );
+
+	//! Validates buffer signal source playback action
+	/**
+	  * @param[in] iAction Action integer
+	  * @return True, if action is recognized
+	  */
+	static bool GetSignalSourceBufferPlaybackActionValid( const int iAction );
+
+	//! Log level string getter
+	/**
+	  * @param[in] iLogLevel
+	  * @return Log level string
+	  */
 	static std::string GetLogLevelStr( const int iLogLevel );
 
 	//! Parses an auralization mode from a string (short format only)
 	/**
-	 * This method takes a string with auralization modes in short format
-	 * (e.g. "DS,ER") and interprets it as an auralization mode.
-	 * More over the method allows to compute altered modes
-	 * (e.g. "+DP" for enabling doppler effects) based on a given
-	 * auralization mode.
-	 */
+	  * This method takes a string with auralization modes in short format
+	  * (e.g. "DS,ER") and interprets it as an auralization mode.
+	  * More over the method allows to compute altered modes
+	  * (e.g. "+DP" for enabling doppler effects) based on a given
+	  * auralization mode.
+	  *
+	  * @param[in] sModeStr
+	  * @param[in] iBaseMode Base mode for differential mode setter
+	  * @return Modified auralization mode
+	  */
 	static int ParseAuralizationModeStr( const std::string& sModeStr, const int iBaseMode = VA_AURAMODE_NOTHING );
 
 	//! Returns an auralization mode as formatted string
+	/**
+	  * @param[in] iAuralizationMode Input auralization mode
+	  * @param[in] bShortFormat Flag for short mode
+	  * @return Auralization mode string
+	  */
 	static std::string GetAuralizationModeStr( const int iAuralizationMode, const bool bShortFormat = false );
 
-	// Verstärkung in dB [Pegelmaß 20*log10(X)] in Zeichenkette konvertieren
+	//! Converst a volume to decibel as string (for formatting)
+	/**
+	  * @param[in] dVolume Volume
+	  * @return Volume as decibel string (including dB)
+	  */
 	static std::string GetVolumeStrDecibel( const double dVolume );
 
 	//! Parses an play state from a string
 	/**
-	 * This method takes a string with play state
-	 * (e.g. "STOPPED", "PLAYING", "PAUSED") and converts it into a integer representation.
-	 */
+	  * This method takes a string with play state
+	  * (e.g. "STOPPED", "PLAYING", "PAUSED") and converts it into a integer representation.
+	  *
+	  * @param[in] sStr Playback state string
+	  * @return Playback state integer
+	  */
 	static int ParsePlaybackState( const std::string& sStr );
 
 	//! Returns an play state as formatted string (short format)
+	/**
+	  * @param[in] iPlaybackState Playback state integer
+	  * @return Playback state string
+	  */
 	static std::string GetPlaybackStateStr( const int iPlaybackState );
 
 	//! Returns an play action as formatted string (short format)
+	/**
+	  * @param[in] iPlaybackAction Playback action integer
+	  * @return Playback action string
+	  */
 	static std::string GetPlaybackActionStr( const int iPlaybackAction );
 
 	//! Returns the playback action integer from a string representation (PLAY, STOP, PAUSE)
-	static int ParsePlaybackAction( const std::string& t );
+	/**
+	  * @param[in] sPlaybackAction Playback action string
+	  * @return Playback action integer
+	  */
+	static int ParsePlaybackAction( const std::string& sPlaybackAction );
 
 	//! Returns the table of literals defined by the IVACore interface
-	// (This function is useful, when you implement bindings for other programming languages)
+	/** 
+	  * (This function is useful, when you implement bindings for other programming languages)
+	  *
+	  * @return Integer literal vector
+	  */
 	static const std::vector< CVAIntLiteral >& GetLiterals();
 
 protected: