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
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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.
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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.
	 */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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.
	 */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
221
	virtual void DetachEventHandler( IVAEventHandler* pEventHandler ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
222

223

224
	//! Get all registered modules of the core
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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;
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	  */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
style  
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
style  
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
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	 *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1069
	//! Creates a sound receiver explicitly for a given renderer
Jonas Stienen's avatar
Jonas Stienen committed
1070
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	 *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1094
	//! Enables or disables a virtual sound receiver (removes the sound receiver from audio processing)
Jonas Stienen's avatar
Jonas Stienen committed
1095
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	  *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1105
	  * @param[in] iSoundReceiverID	SoundReceiver identifier
Jonas Stienen's avatar
Jonas Stienen committed
1106 1107
	  * @return				Enabled (true) or disabled (false)
	  *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1130
	  * sound receiver parameters without introducing new methods to the main interface.
Jonas Stienen's avatar
Jonas Stienen committed
1131
	  *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1140
	  * sound receiver parameters without introducing new methods to the main interface.
Jonas Stienen's avatar
Jonas Stienen committed
1141
	  *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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) 
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1191
	//! Returns the position and orientation of the real-world sound receiver's head
Jonas Stienen's avatar
Jonas Stienen committed
1192
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1193
	* \note The parameter iSoundReceiverID has been added for future versions and is
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1201
	//! Updates the position and orientation of the real-world sound receiver's head
Jonas Stienen's avatar
Jonas Stienen committed
1202
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1203
	* This function is used to provide the crosstalk-cancellation module
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1204
	* with the current position of the sound receivers head in the real-world.
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1205
	*
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1206
	* \note The parameter iSoundReceiverID has been added for future versions and is
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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

Dipl.-Ing. Jonas Stienen's avatar