VAInterface.h 60.3 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

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

#include <string>
22
#include <vector>
Jonas Stienen's avatar
Jonas Stienen committed
23

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

31
//! Interface of the VA
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
/**
  * 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.
  *
  */
48
class VABASE_API IVAInterface
Jonas Stienen's avatar
Jonas Stienen committed
49 50 51
{
public:
	//! Core states
52
	enum CoreState
Jonas Stienen's avatar
Jonas Stienen committed
53
	{
54 55 56
		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
57 58 59
	};

	//! Core error levels
60
	enum ErrorLevel
Jonas Stienen's avatar
Jonas Stienen committed
61
	{
62 63 64 65 66 67
		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
68 69 70
	};

	//! Playback states of audiofile signal sources
71
	enum PlaybackState
72 73 74 75 76 77
	{
		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
78 79

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

	//! Auralization modes (bit-vector flags)
89 90 91 92
	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
93 94 95
	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
96 97 98 99 100
	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
101
	static const int VA_AURAMODE_TRANSMISSION = ( 1 << 11 );	//!< Sound transmission
102
	static const int VA_AURAMODE_ABSORPTION = ( 1 << 12 );	//!< Sound absorption
Jonas Stienen's avatar
Jonas Stienen committed
103 104 105

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

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

128

Jonas Stienen's avatar
Jonas Stienen committed
129 130 131 132 133 134 135
	//! Destructor
	/**
	 * \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.
	 */
136
	virtual ~IVAInterface();
Jonas Stienen's avatar
Jonas Stienen committed
137

138

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

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


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

	//! 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
165
	 * case the core remains in the state VA_CORESTATE_CREATED.
Jonas Stienen's avatar
Jonas Stienen committed
166 167 168 169 170 171 172
	 * 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.
	 *
173
	 * @note Initialization does not detach event handlers
Jonas Stienen's avatar
Jonas Stienen committed
174
	 */
175
	virtual void Initialize() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
176 177 178 179 180 181 182 183 184 185 186 187 188

	//! 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.
	 *
189
	 * @note Finalization does not detach event handlers
Jonas Stienen's avatar
Jonas Stienen committed
190
	 */
191
	virtual void Finalize() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
192 193 194

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

199

200 201
	//! Attaches a handler for core events to the core instance
	/**
202
	* @oaram[in] pEventHandler Event handler pointer
203 204 205 206 207
	 * @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.
	 */
208
	virtual void AttachEventHandler( IVAEventHandler* pEventHandler ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
209 210 211

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

223

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

230
	//! Calls a module and returns the answer
231 232 233 234 235 236 237 238 239 240
	/**
	  * 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
	  */
241
	virtual CVAStruct CallModule( const std::string& sModuleName, const CVAStruct& oArgs ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
242

243

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

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

257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279
	//! 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
	  *
	  * @warn 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;

	//! 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
	  */
280
	virtual CVAStruct GetHardwareConfiguration() const = 0;
281

282 283 284 285 286 287 288
	//! Create a directivity from a set of parameters	
	/**
	  * @param[in] oParams Parameters
	  * @param[in] sName Versatile name
	  *
	  * @return	Directivity identifier
	  */
289
	virtual int CreateDirectivityFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
290

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

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

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

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

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

356 357 358 359 360 361 362
	
	//! Create acoustic material by passing material data
	/**
	  * @param[in] oMaterial  Material data
	  * @param[in] sName  Verbatim name
	  * @return Identifier
	  */
363
	virtual int CreateAcousticMaterial( const CVAAcousticMaterial& oMaterial, const std::string& sName = "" ) = 0;
364 365 366 367 368 369 370
	
	//! Create acoustic material based on magic parameter set (for prototyping)
	/**
	  * @param[in] oParams  Material parameters
	  * @param[in] sName  Verbatim name
	  * @return Identifier
	  */
371
	virtual int CreateAcousticMaterialFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
372 373 374 375 376 377 378
	
	//! Create acoustic material from file path (e.g. 'mat' file)
	/**
	  * @param[in] sFilePath  Material file path
	  * @param[in] sName  Verbatim name
	  * @return Identifier
	  */
379 380 381 382 383 384
	inline int CreateAcousticMaterialFromFile( const std::string& sFilePath, const std::string& sName = "" )
	{
		CVAStruct oParams;
		oParams[ "filepath" ] = sFilePath;
		return CreateAcousticMaterialFromParameters( oParams, sName );
	};
385 386 387 388 389 390 391 392 393 394 395 396 397
	
	//! 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
	  */
398
	virtual CVAAcousticMaterial GetAcousticMaterialInfo( const int iID ) const = 0;
399 400 401 402 403 404 405 406 407 408 409 410
		
	//! 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
	  */
411
	virtual std::string GetAcousticMaterialName( const int iID ) const = 0;
412 413 414 415 416 417 418 419 420 421 422 423 424 425

	//! 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
	  */
426
	virtual CVAStruct GetAcousticMaterialParameters( const int iID, const CVAStruct& oParams ) const = 0;
427 428 429 430 431 432 433 434
	
	//! Acoustic material parameter setter
	/**
	  * @param[in] iID  Material identifier
	  * @param[in] oParams Material parameters
	  */
	virtual void SetAcousticMaterialParameters( const int iID, const CVAStruct& oParams ) = 0;

435

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


542 543 544 545 546 547 548 549 550 551 552
	//! Creates an audiofile signal source
	/**
	* 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
	*/
553
	inline std::string CreateSignalSourceBufferFromFile( const std::string& sFilePath, const std::string& sName = "" )
554 555
	{
		CVAStruct oParams;
556 557
		oParams[ "filepath" ] = sFilePath;
		return CreateSignalSourceBufferFromParameters( oParams, sName );
558 559 560 561 562 563 564 565 566 567 568 569 570
	};

	//! Creates an audiofile signal source
	/**
	* 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
	*/
571
	virtual std::string CreateSignalSourceBufferFromSamples( const CVASampleBuffer& oSamples, const std::string& sName = "" )
572 573
	{
		CVAStruct oParams;
574 575
		oParams[ "samples" ][ "ch1" ] = oSamples;
		return CreateSignalSourceBufferFromParameters( oParams, sName );
576
	};
577 578

	inline std::string CreateSignalSourceBufferMultichannelFromSamples( const std::vector< CVASampleBuffer >& voSamples, const std::string& sName = "" )
579 580
	{
		CVAStruct oParams;
581 582 583
		for( size_t i = 0; i < voSamples.size(); i++ )
			oParams[ "samples" ][ "ch" + std::to_string( long( i + 1 ) ) ] = voSamples[ i ];
		return CreateSignalSourceBufferFromParameters( oParams, sName );
584
	};
585

586
	virtual std::string CreateSignalSourceBufferFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
587 588 589 590 591

	//! Creates a text-to-speech (TTS) signal source
	/**
	  * Creates a signal source which streams generated samples from a text input.
	  *
592
	  * @param[in] sName		Name (optional, e.g. "Penny")
593 594 595
	  *
	  * @return Signal source ID
	  */
596
	virtual std::string CreateSignalSourceTextToSpeech( const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
597 598 599 600 601 602

	//! Creates a sequencer signal source
	/**
	 * Creates a sequencer signal source.
	 *
	 * \param sName	Name (optional, e.g. "Sequencer 1")
603
	 *
Jonas Stienen's avatar
Jonas Stienen committed
604 605
	 * \return Signal source ID
	 */
606
	virtual std::string CreateSignalSourceSequencer( const std::string& sName = "" ) = 0;
607

Jonas Stienen's avatar
Jonas Stienen committed
608 609
	//! Creates a network-based signal source
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
610 611
	  * Creates a signal source which receives audio samples via network.
	  * Therefore an IP socket is set up with the given parameters.
612
	  *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
613 614 615 616 617 618 619
	  * @param[in] sInterface  IP address of the socket (e.g. 127.0.0.1, no hostnames!)
	  * @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
620
	  */
621
	virtual std::string CreateSignalSourceNetworkStream( const std::string& sInterface, const int iPort, const std::string& sName = "" ) = 0;
622

Jonas Stienen's avatar
Jonas Stienen committed
623 624 625 626 627
	//! Creates a rotating engine source
	/**
	  * \param sName Name of the engine
	  * \return ID of signal source
	  */
628
	virtual std::string CreateSignalSourceEngine( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
629 630 631 632 633

	//! Creates a machine signal source
	/**
	  * \param sName Name of the machine
	  */
634
	virtual std::string CreateSignalSourceMachine( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
635 636 637 638

	//! Deletes a signal source
	/**
	 * Deletes a signal source. This is only possible if it is not in use.
639
	 *
Jonas Stienen's avatar
Jonas Stienen committed
640 641 642
	 * \return true, if the signal source has been deleted
	 *         false, otherwise
	 */
643
	virtual bool DeleteSignalSource( const std::string& sID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
644 645 646 647 648 649

	//! 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.
650
	 *
Jonas Stienen's avatar
Jonas Stienen committed
651 652 653 654 655 656
	 * \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
657 658
	 */
	virtual std::string RegisterSignalSource( IVAAudioSignalSource* pSignalSource, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
659 660 661 662 663

	//! 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.
664
	 *
Jonas Stienen's avatar
Jonas Stienen committed
665 666 667 668 669 670 671
	 * \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
	 */
672
	virtual bool UnregisterSignalSource( IVAAudioSignalSource* pSignalSource ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
673 674

	//! Retrieves information of a signal source
675
	virtual CVASignalSourceInfo GetSignalSourceInfo( const std::string& sSignalSourceID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
676 677

	//! Retrieves information of all signal sources
678
	virtual void GetSignalSourceInfos( std::vector< CVASignalSourceInfo >& voInfos ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
679 680

	//! Returns the playback state flag (bit-vector) of an audiofile signal source
681
	virtual int GetSignalSourceBufferPlaybackState( const std::string& sSignalSourceID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
682 683 684 685 686

	//! 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).
	  */
687
	virtual void SetSignalSourceBufferPlaybackAction( const std::string& sSignalSourceID, const int iPlaybackAction ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
688 689 690 691 692 693

	//! Set the playback position of an audiofile signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param dPlaybackPosition		Playback position [s]
	 */
694
	virtual void SetSignalSourceBufferPlaybackPosition( const std::string& sSignalSourceID, const double dPlaybackPosition ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
695 696 697 698 699 700

	//! Set playback looping mode (true = looping)
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param bLooping				Playback is looping
	 */
701
	virtual void SetSignalSourceBufferLooping( const std::string& sSignalSourceID, const bool bLooping = true ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
702 703 704 705 706

	//! Get playback looping mode (true = looping)
	/**
	 * \param sSignalSourceID		Signal source ID
	 */
707
	virtual bool GetSignalSourceBufferLooping( const std::string& sSignalSourceID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
708 709 710 711 712

	//! Starts the signal of a machine source
	/**
	 * \param sSignalSourceID		Signal source ID
	 */
713
	inline void SetSignalSourceMachineStartMachine( const std::string& sSignalSourceID )
714 715
	{
		CVAStruct oParams;
716 717 718
		oParams[ "set" ] = "action";
		oParams[ "value" ] = "start";
		SetSignalSourceParameters( sSignalSourceID, oParams );
719
	};
Jonas Stienen's avatar
Jonas Stienen committed
720 721 722 723 724

	//! Halts the signal of a machine source
	/**
	 * \param sSignalSourceID		Signal source ID
	 */
725
	inline void SetSignalSourceMachineHaltMachine( const std::string& sSignalSourceID )
726 727
	{
		CVAStruct oParams;
728 729 730
		oParams[ "set" ] = "action";
		oParams[ "value" ] = "stop";
		SetSignalSourceParameters( sSignalSourceID, oParams );
731
	};
Jonas Stienen's avatar
Jonas Stienen committed
732 733 734 735 736 737

	//! Returns the state of a machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \return						Machine state
	 */
738
	inline std::string GetSignalSourceMachineStateStr( const std::string& sSignalSourceID ) const
739 740
	{
		CVAStruct oParams, oRet;
741 742 743 744 745
		oParams[ "get" ] = "state";
		oRet = GetSignalSourceParameters( sSignalSourceID, oParams );
		if( oRet.HasKey( "state" ) )
			if( oRet[ "state" ].IsString() )
				return oRet[ "state" ].ToString();
746 747 748 749 750
			else
				return "error";
		else
			return "unkown";
	};
Jonas Stienen's avatar
Jonas Stienen committed
751 752 753 754 755 756

	//! Sets the speed of a machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param dSpeed				Machine speed (0 .. not-too-large)
	 */
757
	inline void SetSignalSourceMachineSpeed( const std::string& sSignalSourceID, double dSpeed )
758 759
	{
		CVAStruct oParams;
760 761 762
		oParams[ "set" ] = "S";
		oParams[ "value" ] = dSpeed;
		SetSignalSourceParameters( sSignalSourceID, oParams );
763
	};
Jonas Stienen's avatar
Jonas Stienen committed
764 765 766 767 768 769

	//! Sets the speed of a machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \return						Machine speed
	 */
770
	inline double GetSignalSourceMachineSpeed( const std::string& sSignalSourceID ) const
771 772
	{
		CVAStruct oParams, oRet;
773 774 775 776 777
		oParams[ "get" ] = "speed";
		oRet = GetSignalSourceParameters( sSignalSourceID, oParams );
		if( oRet.HasKey( "speed" ) )
			if( oRet[ "speed" ].IsNumeric() )
				return double( oRet[ "speed" ] );
778 779 780

		return 1.0f;
	};
Jonas Stienen's avatar
Jonas Stienen committed
781 782 783 784 785 786

	//! Set start file sample of machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param sFilePath				Path to audio file
	 */
787
	inline void SetSignalSourceMachineStartFile( const std::string& sSignalSourceID, const std::string& sFilePath )
788 789
	{
		CVAStruct oParams;
790 791 792
		oParams[ "set" ] = "StartSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
793
	};
Jonas Stienen's avatar
Jonas Stienen committed
794 795 796 797 798 799

	//! Set idle file sample of machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param sFilePath				Path to audio file
	 */
800 801 802
	inline void SetSignalSourceMachineIdleFile( const std::string& sSignalSourceID, const std::string& sFilePath )
	{
		CVAStruct oParams;
803 804 805
		oParams[ "set" ] = "IdleSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
806
	};
Jonas Stienen's avatar
Jonas Stienen committed
807 808 809 810 811 812

	//! Set stop file sample of machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param sFilePath				Path to audio file
	 */
813
	inline void SetSignalSourceMachineStopFile( const std::string& sSignalSourceID, const std::string& sFilePath )
814 815
	{
		CVAStruct oParams;
816 817 818
		oParams[ "set" ] = "StopSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
819
	};
820
	
Jonas Stienen's avatar
Jonas Stienen committed
821 822 823 824
	//! Set parameters for a signal source
	/**
	 * This method sets parameters of a signal source. Behavior depends on type and
	 * implementation of the referred instance.
825
	 *
Jonas Stienen's avatar
Jonas Stienen committed
826 827 828
	 * \param sSignalSourceID	ID of signal source
	 * \param oParams	Parameter structure
	 */
829
	virtual void SetSignalSourceParameters( const std::string& sSignalSourceID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
830 831 832 833 834

	//! Get parameters from a signal source
	/**
	 * This method returns parameters of a signal source. Behavior depends on type and
	 * implementation of the referred instance.
835
	 *
Jonas Stienen's avatar
Jonas Stienen committed
836 837 838
	 * \param sSignalSourceID	ID of signal source
	 * \return	Parameter structure
	 */
839
	virtual CVAStruct GetSignalSourceParameters( const std::string& sSignalSourceID, const CVAStruct& oParams ) const = 0;
840

841 842 843 844 845 846 847 848 849 850 851 852
	//! Add sequencer sample from file path
	inline int AddSignalSourceSequencerSample( const std::string& sSignalSourceID, const std::string sFilePath )
	{
		CVAStruct oArgs;
		oArgs[ "filepath" ] = sFilePath;
		return AddSignalSourceSequencerSample( sSignalSourceID, oArgs );
	};

	//! Add sequencer sample
	virtual int AddSignalSourceSequencerSample( const std::string& sSignalSourceID, const CVAStruct& oArgs ) = 0;

	//! Add sequencer sound playback
853
	virtual int AddSignalSourceSequencerPlayback( const std::string& sSignalSourceID, const int iSoundID, const int iFlags, const double dTimeCode ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
854

855
	//! Remove sound sample (a sample added for playback can not be reverted)
856 857
	virtual void RemoveSignalSourceSequencerSample( const std::string& sSignalSourceID, const int iSoundID ) = 0;

858

859
	//! Returns wheather a synchronized scene modification is in progress
860
	virtual bool GetUpdateLocked() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
861 862 863 864 865 866 867

	//! Begins a synchronized scene modification
	/**
	 * Erwirbt für den aufrufenden Thread das Recht der exklusiven Szenemodifikation.
	 * Dieses Recht bleibt ihm erhalten, bis er es wieder durch Aufruf der Methode
	 * UnlockScene freigibt.
	 */
868
	virtual void LockUpdate() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
869 870 871 872 873 874 875 876 877 878

	//! Ends a synchronized scene modification and applies all changes
	/**
	 * Gibt das Recht für exklusive Szenemodifikation wieder frei und
	 * publiziert die Änderungen an der Szene. Dies triggert dann
	 * auch die Neuberechnung der Auralisierung.
	 *
	 * \return Zustands-ID der Szene, falls erfolgreich
	 *         -1 sonst
	 */
879
	virtual int UnlockUpdate() = 0;
880

881

Jonas Stienen's avatar
Jonas Stienen committed
882 883 884 885
	//! Create a sound source
	/**
	 * This method creates a new sound source and returns its ID.
	 * A signal source is not created and assigned to the sound source.
886
	 *
Jonas Stienen's avatar
Jonas Stienen committed
887 888 889 890 891 892 893
	 * \param sName					Name (optional)
	 * \param iAuralizationMode		Auralization mode (optional, default: VA_AURAMODE_ALL)
	 * \param dVolume               Volume [factor] (optional, default: 1.0)
	 *
	 * \return ID of the new sound source, if the method succeeded
	 *         -1, otherwise
	 */
894 895 896 897 898 899
	virtual int CreateSoundSource( const std::string& sName = "" ) = 0;

	//! Return all sound source IDs
	virtual void GetSoundSourceIDs( std::vector< int >& viSoundSourceIDs ) = 0;

	virtual CVASoundSourceInfo GetSoundSourceInfo( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
900 901 902 903 904 905 906

	//! Create a sound source explicitly for a certain renderer
	/**
	 * This method creates a new sound source and returns its ID.
	 * This sound source will be skipped for rendering from any other
	 * but the given renderer. See \GetRenderingModules to get a list
	 * of available renderers and their name identifier.
907
	 *
Jonas Stienen's avatar
Jonas Stienen committed
908 909 910 911 912 913 914
	 * \param	sName			Name
	 * \param	sRendererID		Identifier of target renderer
	 *
	 * \return	Numerical identifier of the new sound source on success, -1 otherwise
	 *
	 * \note	Throws VA exception
	 */
915
	virtual int CreateSoundSourceExplicitRenderer( const std::string& sRendererID, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
916 917 918 919 920 921 922 923

	//! Schallquelle entfernen
	/**
	 * Diese Methode entfernt eine Schallquelle aus der Szene
	 *
	 * \return 0 falls die Schallquelle entfernt wurde,
	 *         -1 im Fehlerfall
	 */
924
	virtual int DeleteSoundSource( const int iID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
925 926 927 928 929 930 931 932

	//! Enables or disables a sound source (removes the sound source from processing within renderers)
	/**
	  * @param[in] iSoundSourceID	Sound source identifier
	  * @param[in] bEnabled			Enable (true) or disable (false) sound source
	  *
	  * @sa GetSoundSourceEnabled()
	  */
933
	virtual void SetSoundSourceEnabled( const int iID, const bool bEnabled = true ) = 0;
934

Jonas Stienen's avatar
Jonas Stienen committed
935 936 937 938 939 940 941
	//! Returns sound source enabled/disabled status
	/**
	  * @param[in] iSoundSourceID	Sound source identifier
	  * @return					Enabled (true) or disabled (false)
	  *
	  * @sa SetSoundSourceEnabled()
	  */
942
	virtual bool GetSoundSourceEnabled( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
943 944

	//! Name einer Schallquelle zurückgeben
945
	virtual std::string GetSoundSourceName( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
946 947

	//! Name einer Schallquelle setzen
948
	virtual void SetSoundSourceName( const int iID, const std::string& sName ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
949 950

	//! Signalquelle einer Schallquelle zurückgeben
951
	virtual std::string GetSoundSourceSignalSource( const int iID ) const = 0;
952

953 954
	virtual int GetSoundSourceGeometryMesh( const int iID ) const = 0;
	virtual void SetSoundSourceGeometryMesh( const int iSoundReceiverID, const int iGeometryMeshID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
955 956 957

	//! Attach a signal source to sound source
	/**
958
	  * Let a sound source play back samples from the given signal source.
Jonas Stienen's avatar
Jonas Stienen committed
959 960 961 962 963 964 965 966
	  * An empty string removes the signal source from sound source (silence).
	  *
	  * \see RemoveSoundSourceSignalSource
	  *
	  * \param iID	Sound source identifier
	  * \param sSignalSourceID	Signal source identifier
	  *
	  */
967
	virtual void SetSoundSourceSignalSource( const int iSoundSourceID, const std::string& sSignalSourceID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
968 969 970 971 972 973 974

	//! Detach signal source from a sound sourve
	/**
	  * Detaches a connected signal source from a sound source. Signal source will not be removed.
	  *
	  * \param	Sound source identifier
	  */
975
	inline void RemoveSoundSourceSignalSource( const int iID )
976
	{
977
		SetSoundSourceSignalSource( iID, "" );
978
	};
Jonas Stienen's avatar
Jonas Stienen committed
979 980

	//! Auralisierungsmodus einer Schallquelle zurückgeben (Bitvektor)
981
	virtual int GetSoundSourceAuralizationMode( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
982 983 984 985 986

	//! Auralisierungsmodus einer Schallquelle setzen (Bitvektor)
	/**
	 * Mit dieser Methode wird der Auralisierungsmodus für eine Schallquelle festgelegt.
	 */
987
	virtual void SetSoundSourceAuralizationMode( const int iSoundSourceID, const int iAuralizationMode ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
988 989 990 991 992 993 994 995 996

	//! 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.
	  *
	  * \param iSoundSourceID Sound source identifier
	  * \param oParams Magic struct with the parameters
	  */
997
	virtual void SetSoundSourceParameters( const int iID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
998 999 1000 1001

	//! Get sound source parameters
	/**
	  * This general parameter getter can be used for quick solutions retrieving
1002
	  * sound receiver parameters without introducing new methods to the main interface.
Jonas Stienen's avatar
Jonas Stienen committed
1003 1004 1005 1006 1007
	  *
	  * \param iSoundSourceID Sound source identifier
	  * \param oParams Magic struct with the parameters that are requested
	  * \return Magic struct with the parameter values requested
	  */
1008
	virtual CVAStruct GetSoundSourceParameters( const int iID, const CVAStruct& oParams ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1009 1010 1011 1012 1013

	//! Returns the directivity of a sound source
	/**
	 * If the sound source is not assigned a directivity, the methods returns -1.
	 */
1014
	virtual int GetSoundSourceDirectivity( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1015 1016 1017 1018 1019

	//! Sets the directivity of a sound source
	/**
	 * In order to remove an assigned directivity, you can pass -1 to the method.
	 */
1020
	virtual void SetSoundSourceDirectivity( const int iSoundSourceID, const int iDirectivityID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1021 1022 1023 1024 1025

	//! Lautstärke einer Schallquelle zurückgeben
	/**
	 * Gibt den Verstärkungsfaktor zurück (nicht Dezibel)
	 */
1026
	virtual double GetSoundSourceSoundPower( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1027 1028 1029 1030 1031

	//! Lautstärke einer Schallquelle setzen
	/**
	 * Setzt die Lautstärke einer Schallquelle als Verstärkungsfaktor (nicht Dezibel).
	 */
1032
	virtual void SetSoundSourceSoundPower( const int iSoundSourceID, const double dSoundPower ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1033 1034 1035 1036 1037

	//! Stummschaltung einer Schallquelle ein-/ausschalten
	/**
	 * Gibt den Verstärkungsfaktor zurück (nicht Dezibel)
	 */
1038
	virtual bool GetSoundSourceMuted( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1039 1040

	//! Stummschaltung einer Schallquelle ein-/ausschalten
1041
	virtual void SetSoundSourceMuted( const int iID, const bool bMuted = true ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1042

1043 1044 1045
	virtual void GetSoundSourcePose( const int iID, VAVec3& vPos, VAQuat& qOrient ) const = 0;
	virtual void SetSoundSourcePose( const int iID, const VAVec3& vPos, const VAQuat& qOrient ) = 0;

1046
	virtual VAVec3 GetSoundSourcePosition( const int iID ) const = 0;
1047
	virtual void SetSoundSourcePosition( const int iID, const VAVec3& v3Pos ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1048

1049
	virtual VAQuat GetSoundSourceOrientation( const int iID ) const = 0;
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1050
	virtual void SetSoundSourceOrientation( const int iID, const VAQuat& qOrient ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1051

1052
	virtual void GetSoundSourceOrientationVU( const int iID, VAVec3& v3View, VAVec3& v3Up ) const = 0;
1053
	virtual void SetSoundSourceOrientationVU( const int iID, const VAVec3& v3View, const VAVec3& v3Up ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1054

1055

1056
	//! Returns all sound receiver IDs
1057
	virtual void GetSoundReceiverIDs( std::vector< int >& viIDs ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1058

1059
	//! Creates a sound receiver
Jonas Stienen's avatar
Jonas Stienen committed
1060
	/**
1061
	 * This method creates a new sound receiver (sound receiver).
1062
	 *
1063
	 * @param[in] sName		Name (optional)
Jonas Stienen's avatar
Jonas Stienen committed
1064
	 *
1065
	 * \return ID of the new sound receiver, if the method succeeded, -1, otherwise
Jonas Stienen's avatar
Jonas Stienen committed
1066
	 */
1067
	virtual int CreateSoundReceiver( const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1068

1069
	//! Creates a sound receiver explicitly for a given renderer
Jonas Stienen's avatar
Jonas Stienen committed
1070
	/**
1071 1072
	 * This method creates a new sound receiver for a special renderer, only.
	 * the sound receiver will be skipped by all other renderers. See
Jonas Stienen's avatar
Jonas Stienen committed
1073
	 * GetRendererLister() for a list of all available renderer identifier.
1074
	 *
Jonas Stienen's avatar
Jonas Stienen committed
1075 1076 1077
	 * \param	sName			Name
	 * \param	sRendererID		Renderer identifier
	 *
1078
	 * \return ID of the new sound receiver, if the method succeeded and -1, otherwise
Jonas Stienen's avatar
Jonas Stienen committed
1079
	 */
1080
	virtual int CreateSoundReceiverExplicitRenderer( const std::string& sRendererID, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1081 1082 1083 1084 1085 1086 1087 1088 1089

	//! Hörer entfernen
	/**
	 * Diese Methode entfernt einen Hörer aus der Szene.
	 * Wichtig: Der aktive Hörer kann nicht gelöscht werden.
	 *
	 * \return 0 falls der Hörer entfernt wurde,
	 *         -1 im Fehlerfall
	 */
1090
	virtual int DeleteSoundReceiver( const int iID ) = 0;
1091 1092

	virtual CVASoundReceiverInfo GetSoundReceiverInfo( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1093

1094
	//! Enables or disables a virtual sound receiver (removes the sound receiver from audio processing)
Jonas Stienen's avatar
Jonas Stienen committed
1095
	/**
1096
	  * @param[in] iSoundReceiverID	SoundReceiver identifier
Jonas Stienen's avatar
Jonas Stienen committed
1097 1098
	  * @param[in] bEnabled		Enable (true) or disable (false) sound source
	  *
1099
	  * @sa GetSoundReceiverEnabled()
Jonas Stienen's avatar
Jonas Stienen committed
1100
	  */
1101
	virtual void SetSoundReceiverEnabled( const int iID, const bool bEnabled = true ) = 0;
1102

1103
	//! Returns sound receiver enabled/disabled status
Jonas Stienen's avatar
Jonas Stienen committed
1104
	/**
1105
	  * @param[in] iSoundReceiverID	SoundReceiver identifier
Jonas Stienen's avatar
Jonas Stienen committed
1106 1107
	  * @return				Enabled (true) or disabled (false)
	  *
1108
	  * @sa SetSoundReceiverEnabled()
Jonas Stienen's avatar
Jonas Stienen committed
1109
	  */
1110
	virtual bool GetSoundReceiverEnabled( const int iID ) const = 0;
1111

Jonas Stienen's avatar
Jonas Stienen committed
1112
	//! Name eines Hörers zurückgeben
1113
	virtual std::string GetSoundReceiverName( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1114 1115

	//! Name eines Hörers setzen
1116
	virtual void SetSoundReceiverName( const int iID, const std::string& sName ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1117 1118

	//! Auralisierungsmodus eines Hörers zurückgeben (Bitvektor)
1119
	virtual int GetSoundReceiverAuralizationMode( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1120 1121 1122 1123 1124

	//! Auralisierungsmodus eines Hörers setzen (Bitvektor)
	/**
	 * Mit dieser Methode wird der Auralisierungsmodus für eines Hörers festgelegt.
	 */
1125
	virtual void SetSoundReceiverAuralizationMode( const int iSoundReceiverID, const int iAuralizationMode ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1126

1127
	//! Set sound receiver parameters
Jonas Stienen's avatar
Jonas Stienen committed
1128 1129
	/**
	  * This general parameter setter can be used for quick solutions changing
1130
	  * sound receiver parameters without introducing new methods to the main interface.
Jonas Stienen's avatar
Jonas Stienen committed
1131
	  *
1132
	  * \param iSoundReceiverID SoundReceiver identifier
Jonas Stienen's avatar
Jonas Stienen committed
1133 1134
	  * \param oParams Magic struct with the parameters
	  */
1135
	virtual void SetSoundReceiverParameters( const int iID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1136

1137
	//! Get sound receiver parameters
Jonas Stienen's avatar
Jonas Stienen committed
1138 1139
	/**
	  * This general parameter getter can be used for quick solutions retrieving
1140
	  * sound receiver parameters without introducing new methods to the main interface.
Jonas Stienen's avatar
Jonas Stienen committed
1141
	  *
1142
	  * \param iSoundReceiverID SoundReceiver identifier
Jonas Stienen's avatar
Jonas Stienen committed
1143 1144 1145
	  * \param oParams Magic struct with the parameters that are requested
	  * \return Magic struct with the parameter values requested
	  */
1146
	virtual CVAStruct GetSoundReceiverParameters( const int iID, const CVAStruct& oArgs ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1147

1148
	//! Returns for a sound receiver the ID of the assigned HRIR dataset
1149
	virtual int GetSoundReceiverDirectivity( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1150

1151
	//! Set the HRIR dataset for a sound receiver
Jonas Stienen's avatar
Jonas Stienen committed
1152
	/**
1153 1154
	* \note In order to set no HRIR dataset, you can pass -1 to the method.
	*/
1155
	virtual void SetSoundReceiverDirectivity( const int iSoundReceiverID, const int iDirectivityID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1156

1157 1158 1159
	virtual int GetSoundReceiverGeometryMesh( const int iID ) const = 0;
	virtual void SetSoundReceiverGeometryMesh( const int iSoundReceiverID, const int iGeometryMeshID ) = 0;

Jonas Stienen's avatar
Jonas Stienen committed
1160

1161 1162 1163 1164 1165 1166
	//! 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;

1167
	//! Position eines Hörers zurückgeben (Positionsvektor) 
1168
	virtual VAVec3 GetSoundReceiverPosition( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1169 1170 1171

	//! Position eines Hörers setzen (Positionsvektor) 
	/**
1172
	 * - Sets the velocity of the sound receiver to zero
Jonas Stienen's avatar
Jonas Stienen committed
1173
	 */
1174
	virtual void SetSoundReceiverPosition( const int iID, const VAVec3& v3Pos ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1175

1176 1177
	//! Orientierung eines Hörers zurückgeben (view and up vector) 
	virtual void GetSoundReceiverOrientationVU( const int iID, VAVec3& vView, VAVec3& vUp ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1178

1179 1180
	//! Orientierung eines Hörers setzen (view and up vector) 
	virtual void SetSoundReceiverOrientationVU( const int iID, const VAVec3& vView, const VAVec3& vUp ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1181

1182 1183
	//! Orientierung getter for sound receiver (quaternion) 
	virtual VAQuat GetSoundReceiverOrientation( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1184

1185 1186
	//! OOrientierung setter for sound receiver (quaternion) 
	virtual void SetSoundReceiverOrientation( const int iID, const VAQuat& qOrient ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1187

1188
	virtual VAQuat GetSoundReceiverHeadAboveTorsoOrientation( const int iID ) const = 0;
1189
	virtual void SetSoundReceiverHeadAboveTorsoOrientation( const int iID, const VAQuat& qOrient ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1190

1191
	//! Returns the position and orientation of the real-world sound receiver's head
Jonas Stienen's avatar
Jonas Stienen committed
1192
	/**
1193
	* \note The parameter iSoundReceiverID has been added for future versions and is
1194 1195 1196 1197 1198 1199
	*       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.
	*/
	virtual void GetSoundReceiverRealWorldPositionOrientationVU( const int iID, VAVec3& v3Pos, VAVec3& v3View, VAVec3& v3Up ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1200

1201
	//! Updates the position and orientation of the real-world sound receiver's head
Jonas Stienen's avatar
Jonas Stienen committed
1202
	/**
1203
	* This function is used to provide the crosstalk-cancellation module
1204
	* with the current position of the sound receivers head in the real-world.
1205
	*
1206
	* \note The parameter iSoundReceiverID has been added for future versions and is
1207 1208 1209 1210 1211 1212
	*       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.
	*/
	virtual void SetSoundReceiverRealWorldPositionOrientationVU( const int iID, const VAVec3& v3Pos, const VAVec3& v3View, const VAVec3& v3Up ) = 0;
1213

1214 1215
	virtual void GetSoundReceiverRealWorldPose( const int iID, VAVec3& v3Pos, VAQuat& qOrient ) const = 0;
	virtual void SetSoundReceiverRealWorldPose( const int iID, const VAVec3& v3Pos, const VAQuat& qOrient ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1216

1217
	virtual VAQuat GetSoundReceiverRealWorldHeadAboveTorsoOrientation( const int iID ) const = 0;
1218
	virtual void SetSoundReceiverRealWorldHeadAboveTorsoOrientation( const int iID, const VAQuat& qOrient ) = 0;
1219

Jonas Stienen's avatar
Jonas Stienen committed
1220

1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253
	//! Set homogeneous medium sound speed in m/s
	virtual void SetHomogeneousMediumSoundSpeed( const double dSoundSpeed ) = 0;

	//! Get homogeneous medium sound speed in m/s
	virtual double GetHomogeneousMediumSoundSpeed() const = 0;

	//! Set homogeneous medium temperature in degree Celsius (0 is freezing point of water)
	virtual void SetHomogeneousMediumTemperature( const double dDegreesCentigrade ) = 0;

	//! Get homogeneous medium temperature in degree Celsius (0 is freezing point of water)
	virtual double GetHomogeneousMediumTemperature() const = 0;

	//! Set homogeneous medium static pressure in Pascal
	virtual void SetHomogeneousMediumStaticPressure( const double dPressurePascal ) = 0;

	//! Get homogeneous medium static pressure in Pascal
	virtual double GetHomogeneousMediumStaticPressure() const = 0;

	//! Set homogeneous medium relative humidity in percent (0.0 = no vapor, 50.0 = 50%, ... )
	virtual void SetHomogeneousMediumRelativeHumidity( const double dRelativeHumidityPercent ) = 0;

	//! Get homogeneous medium relative humidity in percent (0.0 = no vapor, 50.0 = 50%, ... )
	virtual double GetHomogeneousMediumRelativeHumidity() = 0;

	//! Set homogeneous medium shift speed as 3-dim direction vector in m/s
	virtual void SetHomogeneousMediumShiftSpeed( const VAVec3& v3TranslationSpeed ) = 0;

	//! Get homogeneous medium shift speed as 3-dim direction vector in m/s
	virtual VAVec3 GetHomogeneousMediumShiftSpeed() const = 0;

	//! Set homogeneous medium special parameters
	virtual void SetHomogeneousMediumParameters( const CVAStruct& oParams ) = 0;

1254 1255
	//! Get homogeneous medium special parameters with optional arguments
	virtual CVAStruct GetHomogeneousMediumParameters( const CVAStruct& oArgs ) = 0;
1256 1257


1258
	//! Creates a virtual scene
1259
	virtual std::string CreateScene( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1260

1261 1262
	//! IDs of created scenes
	virtual void GetSceneIDs( std::vector< std::string >& vsIDs ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1263

1264 1265
	//! Get scene info
	virtual CVASceneInfo GetSceneInfo( const std::string& sID ) const = 0;
1266

1267 1268
	//! Returns the name of a portal
	virtual std::string GetSceneName( const std::string& sID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1269

1270 1271 1272 1273
	//! Sets the name of a portal
	virtual void SetSceneName( const std::string& sID, const std::string& sName ) = 0;

	//! Set scene enabled or disabled
1274
	virtual void SetSceneEnabled( const std::string& sID, const bool bEnabled = true ) = 0;
1275 1276

	//! Scene enabled status (true, if enabled)
1277 1278
	virtual bool GetSceneEnabled( const std::string& sID ) const = 0;

1279 1280

	//! Create a sound portal
1281
	virtual int CreateSoundPortal( const std::string& sName = "" ) = 0;
1282

Jonas Stienen's avatar
Jonas Stienen committed
1283
	//! Return all portal IDs
1284 1285
	virtual void GetSoundPortalIDs( std::vector< int >& viIDs ) = 0;

1286
	virtual CVASoundPortalInfo GetSoundPortalInfo( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1287 1288

	//! Returns the name of a portal
1289
	virtual std::string GetSoundPortalName( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1290 1291

	//! Sets the name of a portal
1292
	virtual void SetSoundPortalName( const int iID, const std::string& sName ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1293

1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317
	//! Sound portal material setter
	virtual void SetSoundPortalMaterial( const int iSoundPortalID, const int iMaterialID ) = 0;

	//! Sound portal material getter
	virtual int GetSoundPortalMaterial( const int iSoundPortalID ) const = 0;

	//! Sound portal next portal setter
	virtual void SetSoundPortalNextPortal( const int iSoundPortalID, const int iNextSoundPortalID ) = 0;

	//! Sound portal next portal getter
	virtual int GetSoundPortalNextPortal( const int iSoundPortalID ) const = 0;

	//! Sound portal target sound receiver setter
	virtual void SetSoundPortalSoundReceiver( const int iSoundPortalID, const int iSoundReceiverID ) = 0;

	//! Sound portal target sound receiver getter
	virtual int GetSoundPortalSoundReceiver( const int iSoundPortalID ) const = 0;

	//! Sound portal sound source setter
	virtual void SetSoundPortalSoundSource( const int iSoundPortalID, const int iSoundSourceID ) = 0;

	//! Sound portal sound source getter
	virtual int GetSoundPortalSoundSource( const int iSoundPortalID ) const = 0;

1318
	virtual CVAStruct GetSoundPortalParameters( const int iID ) const = 0;
1319

1320
	virtual void SetSoundPortalParameters( const int iID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1321

1322 1323 1324 1325
	//! Sound portal position setter
	virtual void SetSoundPortalPosition( const int iSoundPortalID, const VAVec3& vPos ) = 0;

	//! Sound portal position getter
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1326
	virtual VAVec3 GetSoundPortalPosition( const int iSoundPortalID ) const = 0;
1327 1328 1329 1330 1331 1332 1333

	//! Sound portal orientation setter
	virtual void SetSoundPortalOrientation( const int iSoundPortalID, const VAQuat& qOrient )