Aufgrund eines Versionsupdates wird GitLab am 01.04. zwischen 9:00 und 9:30 Uhr kurzzeitig nicht zur Verfügung stehen. / Due to a version upgrade, GitLab won't be accessible at 01.04. between 9:00 and 9:30 a.m.

VAInterface.h 64.8 KB
Newer Older
Jonas Stienen's avatar
Jonas Stienen committed
1
/*
2
 *  --------------------------------------------------------------------------------------------
Jonas Stienen's avatar
Jonas Stienen committed
3
 *
4 5 6 7 8 9
 *    VVV        VVV A           Virtual Acoustics (VA) | http://www.virtualacoustics.org
 *     VVV      VVV AAA          Licensed under the Apache License, Version 2.0
 *      VVV    VVV   AAA
 *       VVV  VVV     AAA        Copyright 2015-2017
 *        VVVVVV       AAA       Institute of Technical Acoustics (ITA)
 *         VVVV         AAA      RWTH Aachen University
Jonas Stienen's avatar
Jonas Stienen committed
10
 *
11
 *  --------------------------------------------------------------------------------------------
Jonas Stienen's avatar
Jonas Stienen committed
12 13
 */

14 15
#ifndef IW_VABASE_INTERFACE
#define IW_VABASE_INTERFACE
Jonas Stienen's avatar
Jonas Stienen committed
16

17
// VA includes
Jonas Stienen's avatar
Jonas Stienen committed
18
#include <VABaseDefinitions.h>
19
#include <VABase.h>
20
#include <VASamples.h>
Jonas Stienen's avatar
Jonas Stienen committed
21

22
// STL includes
Jonas Stienen's avatar
Jonas Stienen committed
23
#include <string>
24
#include <vector>
Jonas Stienen's avatar
Jonas Stienen committed
25

26
// Forward declarations
27
class VABASE_API CVAVersionInfo;
Jonas Stienen's avatar
Jonas Stienen committed
28 29
class VABASE_API CVAProgress;
class VABASE_API CVAStruct;
30
class VABASE_API IVAEventHandler;
Jonas Stienen's avatar
Jonas Stienen committed
31 32
class VABASE_API IVAAudioSignalSource;

33
//! Interface of Virtual Acoustics (VA)
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
/**
  * 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.
  *
  * The VACore will implement all these methods. The VANet library will wrap and transmit
  * methods and data classes to make the VA interface completely transparent through a network
  * connection using TCP/IP. All binding classes provide similar named methods in the script
  * language fashion and can use the networked connection or an internal core.
  *
  * There are a lot of prototyping methods using CVAStruct, an associative container for any
  * kind of value.
  *
  * Events can be propagated to event handlers (including network clients) and help to detect
  * core changes and updates.
  *
  */
50
class VABASE_API IVAInterface
Jonas Stienen's avatar
Jonas Stienen committed
51 52 53
{
public:
	//! Core states
54
	enum CoreState
Jonas Stienen's avatar
Jonas Stienen committed
55
	{
56 57 58
		VA_CORESTATE_CREATED = 0,	//!< Core was created, but is not yet initialized
		VA_CORESTATE_READY = 1,	//!< Core is successfully initialized and ready for use
		VA_CORESTATE_FAIL = -1,	//!< Core is corrupted and can not be recovered (trash state)
Jonas Stienen's avatar
Jonas Stienen committed
59 60 61
	};

	//! Core error levels
62
	enum ErrorLevel
Jonas Stienen's avatar
Jonas Stienen committed
63
	{
64 65 66 67 68 69
		VA_LOG_LEVEL_QUIET = 0, //!< Quiet log level (no outputs)
		VA_LOG_LEVEL_ERROR = 1, //!< Show errors ...
		VA_LOG_LEVEL_WARNING = 2, //!< ... and warnings ...
		VA_LOG_LEVEL_INFO = 3, //!< ... and infos ...
		VA_LOG_LEVEL_VERBOSE = 4, //!< ... and verbose messages ...
		VA_LOG_LEVEL_TRACE = 5, //!< ... and tracing outputs.
Jonas Stienen's avatar
Jonas Stienen committed
70 71 72
	};

	//! Playback states of audiofile signal sources
73
	enum PlaybackState
74 75 76 77 78 79
	{
		VA_PLAYBACK_STATE_INVALID = -1,	//!< Playback is stopped
		VA_PLAYBACK_STATE_STOPPED = 0,	//!< Playback is stopped
		VA_PLAYBACK_STATE_PAUSED = 1,	//!< Playback is paused
		VA_PLAYBACK_STATE_PLAYING = 2,	//!< Playback active
	};
Jonas Stienen's avatar
Jonas Stienen committed
80 81

	//! Playback actions (transitions) of audiofile signal sources
82
	enum PlaybackAction
83
	{
84 85
		VA_PLAYBACK_ACTION_NONE = -1,	//!< No action
		VA_PLAYBACK_ACTION_STOP = 0,	//!< Stop playback
86
		VA_PLAYBACK_ACTION_PAUSE = 1,	//!< Pause playback
87
		VA_PLAYBACK_ACTION_PLAY = 2,	//!< Start/resume playback	
88
	};
Jonas Stienen's avatar
Jonas Stienen committed
89 90

	//! Auralization modes (bit-vector flags)
91 92 93 94
	static const int VA_AURAMODE_NOTHING = 0;		//!< No auralization
	static const int VA_AURAMODE_DIRECT_SOUND = ( 1 << 0 );	//!< Direct sound
	static const int VA_AURAMODE_EARLY_REFLECTIONS = ( 1 << 1 );	//!< Early reflections
	static const int VA_AURAMODE_DIFFUSE_DECAY = ( 1 << 2 );	//!< Diffuse decay
95 96 97
	static const int VA_AURAMODE_SOURCE_DIRECTIVITY = ( 1 << 3 );	//!< Source directivity
	static const int VA_AURAMODE_MEDIUM_ABSORPTION = ( 1 << 4 );	//!< Absorption in air
	static const int VA_AURAMODE_TEMP_VAR = ( 1 << 5 );	//!< Atmospheric temporal variations
98 99 100 101 102
	static const int VA_AURAMODE_SCATTERING = ( 1 << 6 );	//!< Scattering 
	static const int VA_AURAMODE_DIFFRACTION = ( 1 << 7 );	//!< Diffraction
	static const int VA_AURAMODE_NEARFIELD = ( 1 << 8 );	//!< Near-field effects
	static const int VA_AURAMODE_DOPPLER = ( 1 << 9 );	//!< Doppler effects
	static const int VA_AURAMODE_SPREADING_LOSS = ( 1 << 10 );	//!< Spherical spreading loss
103
	static const int VA_AURAMODE_TRANSMISSION = ( 1 << 11 );	//!< Sound transmission
104
	static const int VA_AURAMODE_ABSORPTION = ( 1 << 12 );	//!< Sound absorption
Jonas Stienen's avatar
Jonas Stienen committed
105 106 107

	//! Default auralization mode (alias)
	static const int VA_AURAMODE_DEFAULT = VA_AURAMODE_DIRECT_SOUND |
108 109
		VA_AURAMODE_SOURCE_DIRECTIVITY |
		VA_AURAMODE_MEDIUM_ABSORPTION |
110
		VA_AURAMODE_DOPPLER |
111
		VA_AURAMODE_SPREADING_LOSS |
112 113
		VA_AURAMODE_TRANSMISSION |
		VA_AURAMODE_ABSORPTION;
Jonas Stienen's avatar
Jonas Stienen committed
114 115 116

	//! All auralization modes (mask)
	static const int VA_AURAMODE_ALL = VA_AURAMODE_DIRECT_SOUND |
117 118
		VA_AURAMODE_EARLY_REFLECTIONS |
		VA_AURAMODE_DIFFUSE_DECAY |
119 120 121
		VA_AURAMODE_SOURCE_DIRECTIVITY |
		VA_AURAMODE_MEDIUM_ABSORPTION |
		VA_AURAMODE_TEMP_VAR |
122 123 124 125
		VA_AURAMODE_SCATTERING |
		VA_AURAMODE_DIFFRACTION |
		VA_AURAMODE_NEARFIELD |
		VA_AURAMODE_DOPPLER |
126
		VA_AURAMODE_SPREADING_LOSS |
127 128
		VA_AURAMODE_TRANSMISSION |
		VA_AURAMODE_ABSORPTION;
Jonas Stienen's avatar
Jonas Stienen committed
129

130

Jonas Stienen's avatar
Jonas Stienen committed
131 132
	//! Destructor
	/**
133
	 * @note If the core was not finialized until the time of its destruction,
Jonas Stienen's avatar
Jonas Stienen committed
134 135 136 137
	 *       the destructor will attempt to implicitly finalize it here.
	 *       Remember that you should always finialize a core, so that you can
	 *       track errors.
	 */
138
	virtual ~IVAInterface();
Jonas Stienen's avatar
Jonas Stienen committed
139

140

Jonas Stienen's avatar
Jonas Stienen committed
141
	//! Returns the core version
142 143 144
	/**
	  * @param [out] pVersionInfo Core version information
	  */
145
	virtual void GetVersionInfo( CVAVersionInfo* pVersionInfo ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
146 147

	//! Set the output stream for debug messages
148 149 150
	/**
	  * @param [in] posDebug Debug output stream
	  */
151
	virtual void SetDebugStream( std::ostream* posDebug ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
152 153


154
	//! Returns the state of the core
155 156 157
	/**
	  * @return Core state
	  */
158
	virtual int GetState() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
159 160 161 162 163 164 165 166

	//! Initializes the core
	/**
	 * This method initializes the core, making it ready for use.
	 *
	 * If the method succeeds, the core is ready to use and within
	 * the state VA_CORESTATE_READY. Otherwise a CVAException is thrown,
	 * describing the cause for that the initialization failed. In this
167
	 * case the core remains in the state VA_CORESTATE_CREATED.
Jonas Stienen's avatar
Jonas Stienen committed
168 169 170 171 172 173 174
	 * If the initialized failed, the instance remains tidy.
	 * It is not necessary to clean it up by calling Finalize.
	 *
	 * Since the initialization can take a longer time, involving many operations,
	 * progress events are send to all attached event handlers, informing about
	 * the current status. This happens during the call to the method.
	 *
175
	 * @note Initialization does not detach event handlers
Jonas Stienen's avatar
Jonas Stienen committed
176
	 */
177
	virtual void Initialize() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
178 179 180 181 182 183 184 185 186 187 188 189 190

	//! Finalizes the core and frees allocated resources
	/**
	 * This method finalizes an initialized core.
	 * Thereby all its allocated resources are freed.
	 * Afterwards the core is in the state VA_CORESTATE_CREATED.
	 * It can then be reinitialized again.
	 *
	 * Finalization should not fail in general.
	 * If for some reason it does, the core cannot be
	 * used anymore and is within the VA_CORESTATE_FAIL.
	 * It shall be destroyed in this case.
	 *
191
	 * @note Finalization does not detach event handlers
Jonas Stienen's avatar
Jonas Stienen committed
192
	 */
193
	virtual void Finalize() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
194 195 196

	//! Full reset of the core. Clears all scene objects, resources, etc.
	/**
197
	 * Clear all scenes, removes sound entities, resets states and medium values
Jonas Stienen's avatar
Jonas Stienen committed
198
	 */
199
	virtual void Reset() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
200

201

202 203
	//! Attaches a handler for core events to the core instance
	/**
204
	* @param[in] pEventHandler Event handler pointer
205 206 207 208 209
	 * @note Attaching event handlers it always possible,
	 *            regardless of the state of the core.
	 *            This method can therefore be called anytime,
	 *            also before initialization and after finalization.
	 */
210
	virtual void AttachEventHandler( IVAEventHandler* pEventHandler ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
211 212 213

	//! Detaches a handler for core events from the core instance
	/**
214
	 * @param[in] pEventHandler Event handler pointer
215
	 * @note Detaching event handlers it always possible,
Jonas Stienen's avatar
Jonas Stienen committed
216 217 218 219
	 *            regardless of the state of the core.
	 *            This method can therefore be called anytime,
	 *            also before initialization and after finalization.
	 *
220
	 * @note When the method returns, it is guaranteed that the handler will not
Jonas Stienen's avatar
Jonas Stienen committed
221 222
	 *       receive any further core events and may safely be destroyed.
	 */
223
	virtual void DetachEventHandler( IVAEventHandler* pEventHandler ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
224

225

226
	//! Get all registered modules of the core
227 228 229
	/**
	  * @param[out] voModuleInfos Vector with module infos
	  */
230
	virtual void GetModules( std::vector< CVAModuleInfo >& voModuleInfos ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
231

232
	//! Calls a module and returns the answer
233 234 235 236 237 238 239 240 241 242
	/**
	  * This method is useful for prototyping. There is no general documentation possible. Special calls have to be extracted from C++ code
	  * in core. It is recommended to implement at least a help text that will be returned if the 'help' or 'info' key is set to any value.
	  * Also, a true-valued 'verbose' key flag should activate verbose return or output on debug stream.
	  *
	  * @param[in] sModuleName Full qualifier of module identifier (may include ':' separator)
	  * @param[in] oArgs Magic struct that is interpreted by module
	  *
	  * @return Magic return struct
	  */
243
	virtual CVAStruct CallModule( const std::string& sModuleName, const CVAStruct& oArgs ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
244

245

Jonas Stienen's avatar
Jonas Stienen committed
246 247
	//! Adds a search path to the core instance
	/**
248 249
	  * @param[in]	sPath	Local relative or absolute path
	  * @return	True, if path is valid at core side
Jonas Stienen's avatar
Jonas Stienen committed
250 251 252
	  */
	virtual bool AddSearchPath( const std::string& sPath );

253
	//! Returns a struct with entries for each search paths
254 255 256
	/**
	  * @return	Encapsulated search paths
	  */
257
	virtual CVAStruct GetSearchPaths() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
258

259 260 261 262 263 264 265
	//! Returns files that are accessible through search paths
	/**
	  * @param[in]	bRecursive	Search recursively in paths
	  * @param[in]	sFileSuffixFilter	File suffix / type filtering, i.e. "wav" or "daff". "*" or empty string will list all.
	  *
	  * @return	Encapsulated file paths
	  *
266
	  * @warning This call may take a while and can result in a lot of return data.
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281
	  */
	virtual CVAStruct GetFileList( const bool bRecursive = true, const std::string& sFileSuffixFilter = "*" ) const = 0;

	//! Returns a struct with the core configuration
	/**
	* @param[in] bFilterEnabled If true, only include enabled sections.
	*
	* @return	Encapsulated core configuration (as used to load/store and work in core)
	*/
	virtual CVAStruct GetCoreConfiguration( const bool bFilterEnabled = true ) const = 0;
	
	//! Returns a struct with the hardware configuration
	/**
	  * @return	Encapsulated hardware configuration
	  */
282
	virtual CVAStruct GetHardwareConfiguration() const = 0;
283

284 285 286 287 288 289 290
	//! Create a directivity from a set of parameters	
	/**
	  * @param[in] oParams Parameters
	  * @param[in] sName Versatile name
	  *
	  * @return	Directivity identifier
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
291
	virtual int CreateDirectivityFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
292

293
	//! Create a directivity from a file path
294 295 296 297 298 299
	/**
	  * @param[in] sFilePath File path (relative or absolute or macro)
	  * @param[in] sName Versatile name
	  *
	  * @return	Directivity identifier
	  */
300
	inline int CreateDirectivityFromFile( const std::string& sFilePath, const std::string& sName = "" )
301
	{
302 303
		CVAStruct oParams;
		oParams[ "filepath" ] = sFilePath;
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
304
		return CreateDirectivityFromParameters( oParams, sName );
305
	};
306 307 308 309 310 311 312

	//! Delete a directivity
	/**
	  * @param[in] iID  Identifier
	  *
	  * @return True, if directivity was found and could be released (was not in use)
	  */
313
	virtual bool DeleteDirectivity( const int iID ) = 0;
314 315 316 317 318 319 320

	//! Directivity info getter
	/**
	  * @param[in] iID  Identifier
  	  *
	  * @return Directivity information
	  */
321
	virtual CVADirectivityInfo GetDirectivityInfo( const int iID ) const = 0;
322 323 324 325 326
	
	//! Directivity info getter
	/**
	  * @param[out] voDest  Directivity information vector
	  */
327
	virtual void GetDirectivityInfos( std::vector< CVADirectivityInfo >& voDest ) const = 0;
328 329 330 331 332 333

	//! Directivity name setter
	/**
	  * @param[in] iID  Identifier
	  * @param[in] sName  Versatile name
	  */
334
	virtual void SetDirectivityName( const int iID, const std::string& sName ) = 0;
335 336 337 338 339 340
	
	//! Directivity name getter
	/**
	  * @param[in] iID  Identifier
	  * @return Versatile name
	  */
341
	virtual std::string GetDirectivityName( const int iID ) const = 0;
342 343 344 345 346 347 348
	

	//! Directivity parameter setter
	/**
	  * @param[in] iID  Identifier
	  * @param[in] oParams  Parameters
	  */
349
	virtual void SetDirectivityParameters( const int iID, const CVAStruct& oParams ) = 0;
350 351 352 353
	
	//! Directivity parameter getter
	/**
	  * @param[in] iID  Identifier
354
	  * @param[in] oParams  Parameters
355 356
	  * @return Parameters
	  */
357 358
	virtual CVAStruct GetDirectivityParameters( const int iID, const CVAStruct& oParams ) const = 0;

359 360 361 362 363 364 365
	
	//! Create acoustic material by passing material data
	/**
	  * @param[in] oMaterial  Material data
	  * @param[in] sName  Verbatim name
	  * @return Identifier
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
366
	virtual int CreateAcousticMaterial( const CVAAcousticMaterial& oMaterial, const std::string& sName = "" ) = 0;
367 368 369 370 371 372 373
	
	//! Create acoustic material based on magic parameter set (for prototyping)
	/**
	  * @param[in] oParams  Material parameters
	  * @param[in] sName  Verbatim name
	  * @return Identifier
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
374
	virtual int CreateAcousticMaterialFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
375 376 377 378 379 380 381
	
	//! Create acoustic material from file path (e.g. 'mat' file)
	/**
	  * @param[in] sFilePath  Material file path
	  * @param[in] sName  Verbatim name
	  * @return Identifier
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
382 383 384 385 386 387
	inline int CreateAcousticMaterialFromFile( const std::string& sFilePath, const std::string& sName = "" )
	{
		CVAStruct oParams;
		oParams[ "filepath" ] = sFilePath;
		return CreateAcousticMaterialFromParameters( oParams, sName );
	};
388 389 390 391 392 393 394 395 396 397 398 399 400
	
	//! Create acoustic material based on magic parameter set (for prototyping)
	/**
	  * @param[in] iID  Material identifier
	  * @return True, if material could be removed
	  */
	virtual bool DeleteAcousticMaterial( const int iID ) = 0;	
	
	//! Acoustic material info getter
	/**
	  * @param[in] iID  Material identifier
	  * @return Info on material
	  */
401
	virtual CVAAcousticMaterial GetAcousticMaterialInfo( const int iID ) const = 0;
402 403 404 405 406 407 408 409 410 411 412 413
		
	//! Acoustic material info getter for entire database
	/**
	  * @param[out] voDest  Vector with material infos
	  */
	virtual void GetAcousticMaterialInfos( std::vector< CVAAcousticMaterial >& voDest ) const = 0;	

	//! Acoustic material name getter
	/**
	  * @param[in] iID  Material identifier
	  * @return  Verbatim name
	  */
414
	virtual std::string GetAcousticMaterialName( const int iID ) const = 0;
415 416 417 418 419 420 421 422 423 424 425 426 427 428

	//! Acoustic material name setter
	/**
	  * @param[in] iID  Material identifier
	  * @param[in] sName  Verbatim name
	  */
	virtual void SetAcousticMaterialName( const int iID, const std::string& sName ) = 0;
	
	//! Acoustic material name getter
	/**
	  * @param[in] iID  Material identifier
	  * @param[in] oParams Material parameter request arguments
	  * @return  Material parameters
	  */
429
	virtual CVAStruct GetAcousticMaterialParameters( const int iID, const CVAStruct& oParams ) const = 0;
430 431 432 433 434 435 436 437
	
	//! Acoustic material parameter setter
	/**
	  * @param[in] iID  Material identifier
	  * @param[in] oParams Material parameters
	  */
	virtual void SetAcousticMaterialParameters( const int iID, const CVAStruct& oParams ) = 0;

438

439 440 441 442 443 444 445
	//! Create a geometry mesh with mesh infos
	/**
	  * @param[in] oMesh Geometry mesh information
	  * @param[in] sName Versatile name
	  *
	  * @return Geometry mesh identifier
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
446
	virtual int CreateGeometryMesh( const CVAGeometryMesh& oMesh, const std::string& sName = "" ) = 0;
447 448 449 450 451 452 453 454
	
	//! Create a geometry mesh from parameters
	/**
	  * @param[in] oParams Geometry mesh parameters
	  * @param[in] sName Versatile name
	  *
	  * @return Geometry mesh identifier
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
455
	virtual int CreateGeometryMeshFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
456 457 458 459 460 461 462 463
	
	//! Create a geometry mesh from file
	/**
	  * @param[in] sFilePath Geometry mesh file path (relative or absolute or macro)
	  * @param[in] sName Versatile name
	  *
	  * @return Geometry mesh identifier
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
464 465 466 467 468 469
	inline int CreateGeometryMeshFromFile( const std::string& sFilePath, const std::string& sName = "" )
	{
		CVAStruct oParams;
		oParams[ "filepath" ] = sFilePath;
		return CreateGeometryMeshFromParameters( oParams, sName );
	};
470 471 472 473 474 475 476
	
	//! Delete a geometry mesh
	/**
	  * @param[in] iID Geometry mesh identifier
	  *
	  * @return True if mesh could be removed
	  */
477
	virtual bool DeleteGeometryMesh( const int iID ) = 0;
478 479 480 481 482 483 484
	
	//! Get a geometry mesh from identifeir
	/**
	  * @param[in] iID Geometry mesh identifier
	  *
	  * @return Geometry mesh
	  */
485
	virtual CVAGeometryMesh GetGeometryMesh( const int iID ) const = 0;
486 487 488
	
	//! Get geometry mesh ids
	/**
489
	  * @param[out] viIDs All available geometry mesh identifiers
490 491
	  *
	  */
492
	virtual void GetGeometryMeshIDs( std::vector< int >& viIDs ) const = 0;
493 494 495 496 497 498 499 500
	
	//! Delete a geometry mesh
	/**
	  * @param[in] iID Geometry mesh identifier
	  * @param[in] sName Geometry mesh verbatim name
	  *
	  * @return True if mesh could be removed
	  */
501
	virtual void SetGeometryMeshName( const int iID, const std::string& sName ) = 0;
502 503 504 505 506 507 508
	
	//! Geometry mesh name getter
	/**
	  * @param[in] iID Geometry mesh identifier
	  *
	  * @return Verbatim name
	  */
509
	virtual std::string GetGeometryMeshName( const int iID ) const = 0;
510 511 512 513 514 515 516 517
	
	//! Geometry mesh parameter setter
	/**
	  * @param[in] iID Geometry mesh identifier
	  * @param[in] oParams Geometry mesh magic parameters
	  *
	  * @return True if mesh could be removed
	  */
518
	virtual void SetGeometryMeshParameters( const int iID, const CVAStruct& oParams ) = 0;
519 520 521 522 523 524 525 526
	
	//! Geometry mesh parameter getter
	/**
	  * @param[in] iID Geometry mesh identifier
	  * @param[in] oParams Geometry mesh magic parameter request
	  *
	  * @return Magic parameters
	  */
527
	virtual CVAStruct GetGeometryMeshParameters( const int iID, const CVAStruct& oParams ) const = 0;
528 529 530 531 532 533
	
	//! Geometry mesh enabled setter
	/**
	  * @param[in] iID Geometry mesh identifier
	  * @param[in] bEnabled If true, sets enabled, if false geo mesh is disabled
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
534
	virtual void SetGeometryMeshEnabled( const int iID, const bool bEnabled = true ) = 0;
535 536 537 538 539 540 541
	
	//! Geometry mesh enabled getter
	/**
	  * @param[in] iID Geometry mesh identifier
	  *
	  * @return True if mesh is enabled, false otherwise
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
542
	virtual bool GetGeometryMeshEnabled( const int iID ) const = 0;
543 544


545
	//! Creates a buffer signal source from an audio file
546
	/**
547 548 549 550 551 552 553
	  * 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
	  */
554
	inline std::string CreateSignalSourceBufferFromFile( const std::string& sFilePath, const std::string& sName = "" )
555 556
	{
		CVAStruct oParams;
557 558
		oParams[ "filepath" ] = sFilePath;
		return CreateSignalSourceBufferFromParameters( oParams, sName );
559 560
	};

561
	//! Creates a mono buffer signal source from sample buffer
562
	/**
563 564
	  * Creates a signal source which streams the samples of a buffer.
	  *
565
	  * @param[in] oSamples Buffer samples
566 567 568 569
	  * @param[in] sName		Name (optional, e.g. "Trumpet")
	  *
	  * @return Signal source ID
	  */
570
	virtual std::string CreateSignalSourceBufferFromSamples( const CVASampleBuffer& oSamples, const std::string& sName = "" )
571 572
	{
		CVAStruct oParams;
573 574
		oParams[ "samples" ][ "ch1" ] = oSamples;
		return CreateSignalSourceBufferFromParameters( oParams, sName );
575
	};
576

577 578 579 580 581
	//! 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.
	  *
582
	  * @param[in] voSamples Buffer sample vector
583 584 585 586
	  * @param[in] sName		Name (optional, e.g. "Trumpet")
  	  *
	  * @return Signal source ID
	  */
587
	inline std::string CreateSignalSourceBufferMultichannelFromSamples( const std::vector< CVASampleBuffer >& voSamples, const std::string& sName = "" )
588 589
	{
		CVAStruct oParams;
590 591 592
		for( size_t i = 0; i < voSamples.size(); i++ )
			oParams[ "samples" ][ "ch" + std::to_string( long( i + 1 ) ) ] = voSamples[ i ];
		return CreateSignalSourceBufferFromParameters( oParams, sName );
593
	};
594

595 596 597 598 599 600 601 602 603 604
	//! 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
	  */
605
	virtual std::string CreateSignalSourceBufferFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
606 607 608 609 610

	//! Creates a text-to-speech (TTS) signal source
	/**
	  * Creates a signal source which streams generated samples from a text input.
	  *
611
	  * @param[in] sName		Name (optional, e.g. "Penny")
612 613 614
	  *
	  * @return Signal source ID
	  */
615
	virtual std::string CreateSignalSourceTextToSpeech( const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
616 617 618 619 620

	//! Creates a sequencer signal source
	/**
	 * Creates a sequencer signal source.
	 *
621
	 * @param[in] sName	Name (optional, e.g. "Sequencer 1")
622
	 *
623
	 * @return Signal source ID
Jonas Stienen's avatar
Jonas Stienen committed
624
	 */
625
	virtual std::string CreateSignalSourceSequencer( const std::string& sName = "" ) = 0;
626

Jonas Stienen's avatar
Jonas Stienen committed
627 628
	//! Creates a network-based signal source
	/**
Dipl.-Ing. Jonas Stienen's avatar
style  
Dipl.-Ing. Jonas Stienen committed
629 630
	  * Creates a signal source which receives audio samples via network.
	  * Therefore an IP socket is set up with the given parameters.
631
	  *
632
	  * @param[in] sInterface  IP address of the socket
Dipl.-Ing. Jonas Stienen's avatar
style  
Dipl.-Ing. Jonas Stienen committed
633 634 635 636 637 638
	  * @param[in] iPort       Destination port on which samples are received
	  * @param[in] sName	Optional name
	  *
	  * @note Usual port range is 12480 to 12500
	  *
	  * @return ID of signal source
639
	  */
640
	virtual std::string CreateSignalSourceNetworkStream( const std::string& sInterface, const int iPort, const std::string& sName = "" ) = 0;
641

Jonas Stienen's avatar
Jonas Stienen committed
642 643
	//! Creates a rotating engine source
	/**
644
	  * @param[in] oParams  Parameters
645 646
	  * @param[in] sName Name of the engine
	  * @return ID of signal source
Jonas Stienen's avatar
Jonas Stienen committed
647
	  */
648
	virtual std::string CreateSignalSourceEngine( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
649 650 651

	//! Creates a machine signal source
	/**
652
	  * @param[in] oParams  Parameters
653
	  * @param[in] sName Name of the machine
654
	  *@return Signal source identifier
Jonas Stienen's avatar
Jonas Stienen committed
655
	  */
656
	virtual std::string CreateSignalSourceMachine( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
657 658 659

	//! Deletes a signal source
	/**
660 661
	  * Deletes a signal source. This is only possible if it is not in use.
	  *
662
	  * @return True, if the signal source has been deleted, false otherwise
663
	  */
664
	virtual bool DeleteSignalSource( const std::string& sID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
665 666 667

	//! Registers an (external) signal source with the core
	/**
668 669 670 671
	  * 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.
	  *
672
	  * @param[in] pSignalSource	Signal source instance
673 674 675 676 677 678
	  * @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
	  */
679
	virtual std::string RegisterSignalSource( IVAAudioSignalSource* pSignalSource, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
680 681 682

	//! Unregisters an (external) signal source from the core
	/**
683 684 685
	  * Unregisters an (external) signal source from the core.
	  * This is only possible, if the signal source is not in use.
	  *
686
	  * @param[in] pSignalSource	Signal source instance
687
	  *
688
	  * @return true, if the signal source has been unregistered, false otherwise
689 690 691
	  *
	  * @note This function is only locally available, but not remote
	  */
692
	virtual bool UnregisterSignalSource( IVAAudioSignalSource* pSignalSource ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
693 694

	//! Retrieves information of a signal source
695 696 697 698
	/**
	  * @param[in] sSignalSourceID Signal source identifier
	  * @return Signal source information
	  */
699
	virtual CVASignalSourceInfo GetSignalSourceInfo( const std::string& sSignalSourceID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
700 701

	//! Retrieves information of all signal sources
702 703 704
	/**
	  * @param[in] voInfos Signal source info vector
	  */
705
	virtual void GetSignalSourceInfos( std::vector< CVASignalSourceInfo >& voInfos ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
706 707

	//! Returns the playback state flag (bit-vector) of an audiofile signal source
708 709 710 711
	/**
	  * @param[in] sSignalSourceID Signal source identifier
	  * @return Playback state integer
	  */
712
	virtual int GetSignalSourceBufferPlaybackState( const std::string& sSignalSourceID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
713 714 715 716

	//! 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).
717 718
	  *
	  * @param[in] sSignalSourceID Signal source identifier
719
	  * @param[in] iPlaybackAction Playback action integer
Jonas Stienen's avatar
Jonas Stienen committed
720
	  */
721
	virtual void SetSignalSourceBufferPlaybackAction( const std::string& sSignalSourceID, const int iPlaybackAction ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
722 723 724

	//! Set the playback position of an audiofile signal source
	/**
725 726 727
	  * @param[in] sSignalSourceID		Signal source ID
	  * @param[in] dPlaybackPosition		Playback position [s]
	  */
728
	virtual void SetSignalSourceBufferPlaybackPosition( const std::string& sSignalSourceID, const double dPlaybackPosition ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
729 730 731

	//! Set playback looping mode (true = looping)
	/**
732 733 734
	  * @param[in] sSignalSourceID		Signal source ID
	  * @param[in] bLooping				Playback is looping, if set true
	  */
735
	virtual void SetSignalSourceBufferLooping( const std::string& sSignalSourceID, const bool bLooping = true ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
736 737 738

	//! Get playback looping mode (true = looping)
	/**
739 740 741
	  * @param[in] sSignalSourceID		Signal source ID
	  * @return True, if looping is enabled
	  */
742
	virtual bool GetSignalSourceBufferLooping( const std::string& sSignalSourceID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
743 744 745

	//! Starts the signal of a machine source
	/**
746 747
	  * @param[in] sSignalSourceID		Signal source ID
	  */
748
	inline void SetSignalSourceMachineStartMachine( const std::string& sSignalSourceID )
749 750
	{
		CVAStruct oParams;
751 752 753
		oParams[ "set" ] = "action";
		oParams[ "value" ] = "start";
		SetSignalSourceParameters( sSignalSourceID, oParams );
754
	};
Jonas Stienen's avatar
Jonas Stienen committed
755 756 757

	//! Halts the signal of a machine source
	/**
758 759
	  * @param[in] sSignalSourceID		Signal source ID
	  */
760
	inline void SetSignalSourceMachineHaltMachine( const std::string& sSignalSourceID )
761 762
	{
		CVAStruct oParams;
763 764 765
		oParams[ "set" ] = "action";
		oParams[ "value" ] = "stop";
		SetSignalSourceParameters( sSignalSourceID, oParams );
766
	};
Jonas Stienen's avatar
Jonas Stienen committed
767 768 769

	//! Returns the state of a machine signal source
	/**
770 771 772
	  * @param[in] sSignalSourceID		Signal source ID
	  * @return						Machine state as string
	  */
773
	inline std::string GetSignalSourceMachineStateStr( const std::string& sSignalSourceID ) const
774 775
	{
		CVAStruct oParams, oRet;
776 777 778 779 780
		oParams[ "get" ] = "state";
		oRet = GetSignalSourceParameters( sSignalSourceID, oParams );
		if( oRet.HasKey( "state" ) )
			if( oRet[ "state" ].IsString() )
				return oRet[ "state" ].ToString();
781 782 783 784 785
			else
				return "error";
		else
			return "unkown";
	};
Jonas Stienen's avatar
Jonas Stienen committed
786 787 788

	//! Sets the speed of a machine signal source
	/**
789 790 791
	  * @param[in] sSignalSourceID		Signal source ID
	  * @param[in] dSpeed				Machine speed (0 .. not-too-large)
	  */
792
	inline void SetSignalSourceMachineSpeed( const std::string& sSignalSourceID, double dSpeed )
793 794
	{
		CVAStruct oParams;
795 796 797
		oParams[ "set" ] = "S";
		oParams[ "value" ] = dSpeed;
		SetSignalSourceParameters( sSignalSourceID, oParams );
798
	};
Jonas Stienen's avatar
Jonas Stienen committed
799 800 801

	//! Sets the speed of a machine signal source
	/**
802 803 804
	  * @param[in] sSignalSourceID		Signal source ID
	  * @return						Machine speed
	  */
805
	inline double GetSignalSourceMachineSpeed( const std::string& sSignalSourceID ) const
806 807
	{
		CVAStruct oParams, oRet;
808 809 810 811 812
		oParams[ "get" ] = "speed";
		oRet = GetSignalSourceParameters( sSignalSourceID, oParams );
		if( oRet.HasKey( "speed" ) )
			if( oRet[ "speed" ].IsNumeric() )
				return double( oRet[ "speed" ] );
813 814 815

		return 1.0f;
	};
Jonas Stienen's avatar
Jonas Stienen committed
816 817 818

	//! Set start file sample of machine signal source
	/**
819 820 821
	  * @param[in] sSignalSourceID		Signal source ID
	  * @param[in] sFilePath				Path to audio file
	  */
822
	inline void SetSignalSourceMachineStartFile( const std::string& sSignalSourceID, const std::string& sFilePath )
823 824
	{
		CVAStruct oParams;
825 826 827
		oParams[ "set" ] = "StartSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
828
	};
Jonas Stienen's avatar
Jonas Stienen committed
829 830 831

	//! Set idle file sample of machine signal source
	/**
832 833 834
	  * @param[in] sSignalSourceID		Signal source ID
	  * @param[in] sFilePath				Path to audio file
	  */
835 836 837
	inline void SetSignalSourceMachineIdleFile( const std::string& sSignalSourceID, const std::string& sFilePath )
	{
		CVAStruct oParams;
838 839 840
		oParams[ "set" ] = "IdleSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
841
	};
Jonas Stienen's avatar
Jonas Stienen committed
842 843 844

	//! Set stop file sample of machine signal source
	/**
845 846 847
	  * @param[in] sSignalSourceID		Signal source ID
	  * @param[in] sFilePath				Path to audio file
	  */
848
	inline void SetSignalSourceMachineStopFile( const std::string& sSignalSourceID, const std::string& sFilePath )
849 850
	{
		CVAStruct oParams;
851 852 853
		oParams[ "set" ] = "StopSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
854
	};
855
	
Jonas Stienen's avatar
Jonas Stienen committed
856 857
	//! Set parameters for a signal source
	/**
858 859 860 861 862 863
	  * This method sets parameters of a signal source. Behavior depends on type and
	  * implementation of the referred instance.
	  *
	  * @param[in] sSignalSourceID	ID of signal source
	  * @param[in] oParams	Parameter structure
	  */
864
	virtual void SetSignalSourceParameters( const std::string& sSignalSourceID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
865 866 867

	//! Get parameters from a signal source
	/**
868 869 870 871 872 873 874
	  * This method returns parameters of a signal source. Behavior depends on type and
	  * implementation of the referred instance.
	  *
	  * @param[in] sSignalSourceID	ID of signal source
	  * @param[in] oParams	Parameter request structure
	  * @return	Parameter structure
	  */
875
	virtual CVAStruct GetSignalSourceParameters( const std::string& sSignalSourceID, const CVAStruct& oParams ) const = 0;
876

877
	//! Add sequencer sample from file path
878 879 880 881 882
	/**
	  * @param[in] sSignalSourceID Signal source identifier
	  * @param[in] sFilePath Sample audio file path
	  * @return Sample identifier
	  */
883 884 885 886 887 888 889 890
	inline int AddSignalSourceSequencerSample( const std::string& sSignalSourceID, const std::string sFilePath )
	{
		CVAStruct oArgs;
		oArgs[ "filepath" ] = sFilePath;
		return AddSignalSourceSequencerSample( sSignalSourceID, oArgs );
	};

	//! Add sequencer sample
891 892 893 894 895
	/**
	  * @param[in] sSignalSourceID Signal source identifier
	  * @param[in] oArgs Sample audio file parameters
	  * @return Sample identifier
	  */
896 897 898
	virtual int AddSignalSourceSequencerSample( const std::string& sSignalSourceID, const CVAStruct& oArgs ) = 0;

	//! Add sequencer sound playback
899 900 901 902 903 904 905
	/**
	  * @param[in] sSignalSourceID Signal source identifier
	  * @param[in] iSoundID Sound sampler identifier
	  * @param[in] iFlags Sampler playback start flags
	  * @param[in] dTimeCode Time code
	  * @return Sample playback identifier
	  */
906
	virtual int AddSignalSourceSequencerPlayback( const std::string& sSignalSourceID, const int iSoundID, const int iFlags, const double dTimeCode ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
907

908
	//! Remove sound sample (a sample added for playback can not be reverted)
909 910 911 912
	/**
	  * @param[in] sSignalSourceID Signal source identifier
	  * @param[in] iSoundID Sound sample identifier
	  */
913 914
	virtual void RemoveSignalSourceSequencerSample( const std::string& sSignalSourceID, const int iSoundID ) = 0;

915

916
	//! Returns wheather a synchronized scene modification is in progress
917 918 919
	/**
	  * @return True, if scene update is locked
	  */
920
	virtual bool GetUpdateLocked() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
921 922 923

	//! Begins a synchronized scene modification
	/**
924 925 926
	  * Receives for the calling thread the exclusive scene modification tocken.
	  * Stays in possesion until UnlockUpdate is called.
	  */
927
	virtual void LockUpdate() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
928 929 930

	//! Ends a synchronized scene modification and applies all changes
	/**
931 932 933 934
	  * Releases update token. Triggers scene lock and creates identifier.
	  *
	  * @return State identifier of current scene on success, -1 otherwiese
	  */
935
	virtual int UnlockUpdate() = 0;
936

937

Jonas Stienen's avatar
Jonas Stienen committed
938 939
	//! Create a sound source
	/**
940 941 942 943 944 945 946
	  * This method creates a new sound source and returns its ID.
	  * A signal source is not created and assigned to the sound source.
	  *
	  * @param[in] sName					Name (optional)
	  *
	  * @return ID of the new sound source, if the method succeeded, -1, otherwise
	  */
947 948 949
	virtual int CreateSoundSource( const std::string& sName = "" ) = 0;

	//! Return all sound source IDs
950 951 952
	/**
	  * @param[out] viSoundSourceIDs Sound source identifiers
	  */
953
	virtual void GetSoundSourceIDs( std::vector< int >& viSoundSourceIDs ) = 0;
954 955 956 957 958 959
	
	//! Return sound source info
	/**
	  * @param[in] iID Sound source identifier
	  * @return Sound source information
	  */
960
	virtual CVASoundSourceInfo GetSoundSourceInfo( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
961 962 963

	//! Create a sound source explicitly for a certain renderer
	/**
964 965
	  * This method creates a new sound source and returns its ID.
	  * This sound source will be skipped for rendering from any other
966
	  * but the given renderer. See GetRenderingModules() to get a list
967 968 969 970 971 972 973 974 975
	  * of available renderers and their name identifier.
	  *
	  * @param[in]	sRendererID		Identifier of target renderer
	  * @param[in]	sName			Name
	  *
	  * @return	Numerical identifier of the new sound source on success, -1 otherwise
	  *
	  * @note	Throws VA exception
	  */
976
	virtual int CreateSoundSourceExplicitRenderer( const std::string& sRendererID, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
977

978
	//! Removes a sound source
Jonas Stienen's avatar
Jonas Stienen committed
979
	/**
980 981 982
	  * @param[in] iID Sound source identifier
	  * @return 0 on success, -1 otherwise
	  */
983
	virtual int DeleteSoundSource( const int iID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
984 985 986

	//! Enables or disables a sound source (removes the sound source from processing within renderers)
	/**
987
	  * @param[in] iID	Sound source identifier
Jonas Stienen's avatar
Jonas Stienen committed
988 989 990 991
	  * @param[in] bEnabled			Enable (true) or disable (false) sound source
	  *
	  * @sa GetSoundSourceEnabled()
	  */
992
	virtual void SetSoundSourceEnabled( const int iID, const bool bEnabled = true ) = 0;
993

Jonas Stienen's avatar
Jonas Stienen committed
994 995
	//! Returns sound source enabled/disabled status
	/**
996
	  * @param[in] iID	Sound source identifier
Jonas Stienen's avatar
Jonas Stienen committed
997 998 999 1000
	  * @return					Enabled (true) or disabled (false)
	  *
	  * @sa SetSoundSourceEnabled()
	  */
1001
	virtual bool GetSoundSourceEnabled( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1002

1003 1004 1005 1006 1007 1008
	//! Returns name of a sound source
	/**
	  * @param[in] iID	Sound source identifier
	  * @return Verbatim name
 	  *
	  */
1009
	virtual std::string GetSoundSourceName( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1010

1011 1012 1013 1014 1015 1016
	//! Sound source name setter
	/**
	  * @param[in] iID	Sound source identifier
	  * @param[in] sName Verbatim name
	  *
	  */
1017
	virtual void SetSoundSourceName( const int iID, const std::string& sName ) = 0;
1018 1019 1020 1021 1022 1023 1024
	
	//! Returns signal source identifier of a sound source
	/**
	  * @param[in] iID	Sound source identifier
	  * @return Signal source identifier, or -1 if not set
 	  *
	  */
1025
	virtual std::string GetSoundSourceSignalSource( const int iID ) const = 0;
1026 1027 1028 1029 1030 1031 1032
	
	//! Sound source geo mesh identifier getter
	/**
	  * @param[in] iID	Sound source identifier
	  * @return Geo mesh identifier
	  *
	  */
1033
	virtual int GetSoundSourceGeometryMesh( const int iID ) const = 0;
1034 1035 1036 1037 1038 1039 1040 1041
	
	//! Sound source geo mesh identifier getter
	/**
	  * Sound sources can have geometrical meshes assigned, i.e. to identify which geometry is part
	  * of a sound source that should not be considered for direct path occlusion - or if the
	  * moving source geometry is relevant for occlusion of other source-receivere-paths, like
	  * cars, trains, etc.
	  *
1042
	  * @param[in] iSoundReceiverID	Sound source identifier
1043 1044 1045
	  * @param[in] iGeometryMeshID Geo mesh identifier
	  *
	  */
1046
	virtual void SetSoundSourceGeometryMesh( const int iSoundReceiverID, const int iGeometryMeshID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1047 1048 1049

	//! Attach a signal source to sound source
	/**
1050
	  * Let a sound source play back samples from the given signal source.
Jonas Stienen's avatar
Jonas Stienen committed
1051 1052
	  * An empty string removes the signal source from sound source (silence).
	  *
1053
	  * @sa RemoveSoundSourceSignalSource
Jonas Stienen's avatar
Jonas Stienen committed
1054
	  *
1055 1056
	  * @param[in] iID	Sound source identifier
	  * @param[in] sSignalSourceID	Signal source identifier
Jonas Stienen's avatar
Jonas Stienen committed
1057 1058
	  *
	  */
1059
	virtual void SetSoundSourceSignalSource( const int iID, const std::string& sSignalSourceID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1060 1061 1062 1063 1064

	//! Detach signal source from a sound sourve
	/**
	  * Detaches a connected signal source from a sound source. Signal source will not be removed.
	  *
1065
	  * @param[in] iID	Sound source identifier
Jonas Stienen's avatar
Jonas Stienen committed
1066
	  */
1067
	inline void RemoveSoundSourceSignalSource( const int iID )
1068
	{
1069
		SetSoundSourceSignalSource( iID, "" );
1070
	};
Jonas Stienen's avatar
Jonas Stienen committed
1071 1072

	//! Auralisierungsmodus einer Schallquelle zurückgeben (Bitvektor)
1073
	virtual int GetSoundSourceAuralizationMode( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1074 1075 1076

	//! Auralisierungsmodus einer Schallquelle setzen (Bitvektor)
	/**
1077 1078 1079 1080 1081 1082
	  * Mit dieser Methode wird der Auralisierungsmodus für eine Schallquelle festgelegt.
	  *
	  * @param[in] iID Sound source identifier
	  * @param[in] iAuralizationMode Auralizaion mode bit-vector
	  */
	virtual void SetSoundSourceAuralizationMode( const int iID, const int iAuralizationMode ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1083 1084 1085 1086 1087 1088

	//! Set sound source parameters
	/**
	  * This general parameter setter can be used for quick solutions changing
	  * sound source parameters without introducing new methods to the main interface.
	  *
1089
	  * @param[in] iID Sound source identifier
1090
	  * @param[in] oParams Magic struct with the parameters
Jonas Stienen's avatar
Jonas Stienen committed
1091
	  */
1092
	virtual void SetSoundSourceParameters( const int iID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1093 1094 1095 1096

	//! Get sound source parameters
	/**
	  * This general parameter getter can be used for quick solutions retrieving
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1097
	  * sound receiver parameters without introducing new methods to the main interface.
Jonas Stienen's avatar
Jonas Stienen committed
1098
	  *
1099
	  * @param[in] iID Sound source identifier
1100 1101
	  * @param[in] oParams Magic struct with the parameters that are requested
	  * @return Magic struct with the parameter values requested
Jonas Stienen's avatar
Jonas Stienen committed
1102
	  */
1103
	virtual CVAStruct GetSoundSourceParameters( const int iID, const CVAStruct& oParams ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1104 1105 1106

	//! Returns the directivity of a sound source
	/**
1107 1108 1109
	  * If the sound source is not assigned a directivity, the methods returns -1.
	  * @param[in] iID Sound source identifier
	  */
1110
	virtual int GetSoundSourceDirectivity( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1111 1112 1113

	//! Sets the directivity of a sound source
	/**
1114 1115
	  * In order to remove an assigned directivity, you can pass -1 to the method.
	  * @param[in] iID Sound source identifier
1116
	  * @param[in] iDirectivityID Directivity identifier
1117 1118
	  */
	virtual void SetSoundSourceDirectivity( const int iID, const int iDirectivityID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1119

1120
	//! Sound receiver sound power getter
Jonas Stienen's avatar
Jonas Stienen committed
1121
	/**
1122 1123 1124
	  * @param[in] iID Sound source identifier
	  * @return Sound power in Watts [W]
	  */
1125
	virtual double GetSoundSourceSoundPower( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1126

1127
	//! Sound receiver sound power setter
Jonas Stienen's avatar
Jonas Stienen committed
1128
	/**
1129 1130
	 * @param[in] iID Sound source identifier
	 * @param[in] dSoundPower Sound power in Watts [W]
Jonas Stienen's avatar
Jonas Stienen committed
1131
	 */
1132
	virtual void SetSoundSourceSoundPower( const int iID, const double dSoundPower ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1133

1134
	//! Sound source enabled getter
Jonas Stienen's avatar
Jonas Stienen committed
1135
	/**
1136 1137 1138
	  * @param[in] iID Sound source identifier
	  * @return True, if muted
	  */
1139
	virtual bool GetSoundSourceMuted( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1140

1141 1142 1143 1144 1145
	//! Sound source enabled setter
	/**
	  * @param[in] iID Sound source identifier
	  * @param[in] bMuted Mutes sound source, if true
	  */
1146
	virtual void SetSoundSourceMuted( const int iID, const bool bMuted = true ) = 0;
1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168
	
	//! Sound source pose getter
	/**
	  * @param[in] iID Sound source identifier
	  * @param[out] v3Pos Position vector
	  * @param[out] qOrient Orientation quaternion
	  */
	virtual void GetSoundSourcePose( 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 SetSoundSourcePose( const int iID, const VAVec3& v3Pos, const VAQuat& qOrient ) = 0;
	
	//! Sound source position getter
	/**
	  * @param[in] iID Sound source identifier
	  * @return Position vector
	  */
1169
	virtual VAVec3 GetSoundSourcePosition( const int iID ) const = 0;
1170 1171 1172 1173 1174 1175
	
	//! Sound source position setter
	/**
	  * @param[in] iID Sound source identifier
	  * @param[in] v3Pos Position vector
	  */
1176
	virtual void SetSoundSourcePosition( const int iID, const VAVec3& v3Pos ) = 0;
1177 1178 1179 1180 1181 1182
	
	//! Sound source orientation getter
	/**
	  * @param[in] iID Sound source identifier
	  * @return Orientation quaternion
	  */
1183
	virtual VAQuat GetSoundSourceOrientation( const int iID ) const = 0;
1184 1185 1186 1187 1188 1189
	
	//! Sound source orientation setter
	/**
	  * @param[in] iID Sound source identifier
	  * @param[in] qOrient Orientation quaternion
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1190
	virtual void SetSoundSourceOrientation( const int iID, const VAQuat& qOrient ) = 0;
1191 1192 1193 1194 1195 1196 1197 1198 1199
	
	//! 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
	  */
1200
	virtual void GetSoundSourceOrientationVU( const int iID, VAVec3& v3View, VAVec3& v3Up ) const = 0;
1201 1202 1203 1204 1205 1206 1207 1208 1209
	
	//! 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
	  */
1210
	virtual void SetSoundSourceOrientationVU( const int iID, const VAVec3& v3View, const VAVec3& v3Up ) = 0;