VAInterface.h 48.1 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
32
//! Interface of the VA
class VABASE_API IVAInterface
Jonas Stienen's avatar
Jonas Stienen committed
33
34
35
{
public:
	//! Core states
36
	enum CoreState
Jonas Stienen's avatar
Jonas Stienen committed
37
	{
38
39
40
		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
41
42
43
	};

	//! Core error levels
44
	enum ErrorLevel
Jonas Stienen's avatar
Jonas Stienen committed
45
	{
46
47
48
49
50
51
		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
52
53
54
	};

	//! Playback states of audiofile signal sources
55
	enum PlaybackState
56
57
58
59
60
61
	{
		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
62
63

	//! Playback actions (transitions) of audiofile signal sources
64
	enum PlaybackAction
65
	{
66
67
		VA_PLAYBACK_ACTION_NONE = -1,	//!< No action
		VA_PLAYBACK_ACTION_STOP = 0,	//!< Stop playback
68
		VA_PLAYBACK_ACTION_PAUSE = 1,	//!< Pause playback
69
		VA_PLAYBACK_ACTION_PLAY = 2,	//!< Start/resume playback	
70
	};
Jonas Stienen's avatar
Jonas Stienen committed
71
72

	//! Auralization modes (bit-vector flags)
73
74
75
76
	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
77
78
79
	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
80
81
82
83
84
	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
85
	static const int VA_AURAMODE_TRANSMISSION = ( 1 << 11 );	//!< Sound transmission
86
	static const int VA_AURAMODE_ABSORPTION = ( 1 << 12 );	//!< Sound absorption
Jonas Stienen's avatar
Jonas Stienen committed
87
88
89

	//! Default auralization mode (alias)
	static const int VA_AURAMODE_DEFAULT = VA_AURAMODE_DIRECT_SOUND |
90
91
		VA_AURAMODE_SOURCE_DIRECTIVITY |
		VA_AURAMODE_MEDIUM_ABSORPTION |
92
		VA_AURAMODE_DOPPLER |
93
		VA_AURAMODE_SPREADING_LOSS |
94
95
		VA_AURAMODE_TRANSMISSION |
		VA_AURAMODE_ABSORPTION;
Jonas Stienen's avatar
Jonas Stienen committed
96
97
98

	//! All auralization modes (mask)
	static const int VA_AURAMODE_ALL = VA_AURAMODE_DIRECT_SOUND |
99
100
		VA_AURAMODE_EARLY_REFLECTIONS |
		VA_AURAMODE_DIFFUSE_DECAY |
101
102
103
		VA_AURAMODE_SOURCE_DIRECTIVITY |
		VA_AURAMODE_MEDIUM_ABSORPTION |
		VA_AURAMODE_TEMP_VAR |
104
105
106
107
		VA_AURAMODE_SCATTERING |
		VA_AURAMODE_DIFFRACTION |
		VA_AURAMODE_NEARFIELD |
		VA_AURAMODE_DOPPLER |
108
		VA_AURAMODE_SPREADING_LOSS |
109
110
		VA_AURAMODE_TRANSMISSION |
		VA_AURAMODE_ABSORPTION;
Jonas Stienen's avatar
Jonas Stienen committed
111

112

Jonas Stienen's avatar
Jonas Stienen committed
113
114
115
116
117
118
119
	//! 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.
	 */
120
	virtual ~IVAInterface();
Jonas Stienen's avatar
Jonas Stienen committed
121

122

Jonas Stienen's avatar
Jonas Stienen committed
123
	//! Returns the core version
124
	virtual void GetVersionInfo( CVAVersionInfo* pVersionInfo ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
125
126

	//! Set the output stream for debug messages
127
	virtual void SetDebugStream( std::ostream* posDebug ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
128
129


130
	//! Returns the state of the core
131
	virtual int GetState() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
132
133
134
135
136
137
138
139

	//! 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
140
	 * case the core remains in the state VA_CORESTATE_CREATED.
Jonas Stienen's avatar
Jonas Stienen committed
141
142
143
144
145
146
147
	 * 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.
	 *
148
	 * @note Initialization does not detach event handlers
Jonas Stienen's avatar
Jonas Stienen committed
149
	 */
150
	virtual void Initialize() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
151
152
153
154
155
156
157
158
159
160
161
162
163

	//! 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.
	 *
164
	 * @note Finalization does not detach event handlers
Jonas Stienen's avatar
Jonas Stienen committed
165
	 */
166
	virtual void Finalize() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
167
168
169
170
171

	//! Full reset of the core. Clears all scene objects, resources, etc.
	/**
	 * TODO Detailled documentation
	 */
172
	virtual void Reset() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
173

174

175
176
177
178
179
180
181
	//! Attaches a handler for core events to the core instance
	/**
	 * @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.
	 */
182
	virtual void AttachEventHandler( IVAEventHandler* pCoreEventHandler ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
183
184
185

	//! Detaches a handler for core events from the core instance
	/**
186
	 * @note Detaching event handlers it always possible,
Jonas Stienen's avatar
Jonas Stienen committed
187
188
189
190
191
192
193
	 *            regardless of the state of the core.
	 *            This method can therefore be called anytime,
	 *            also before initialization and after finalization.
	 *
	 * \note When the method returns, it is guaranteed that the handler will not
	 *       receive any further core events and may safely be destroyed.
	 */
194
	virtual void DetachEventHandler( IVAEventHandler* pCoreEventHandler ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
195

196

197
198
	//! Get all registered modules of the core
	virtual void GetModules( std::vector< CVAModuleInfo >& voModuleInfos ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
199

200
201
	//! Calls a module and returns the answer
	virtual CVAStruct CallModule( const std::string& sModuleName, const CVAStruct& oArgs ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
202

203

Jonas Stienen's avatar
Jonas Stienen committed
204
205
206
207
208
209
210
	//! Adds a search path to the core instance
	/**
	  * \param	sPath	Local relative or absolute path
	  * \return	True, if path is valid at core side
	  */
	virtual bool AddSearchPath( const std::string& sPath );

211
	//! Returns a struct with entries for each search paths
212
	virtual CVAStruct GetSearchPaths() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
213

214

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
215
	virtual int CreateDirectivityFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
216
217
	//! Create a directivity from a file path
	inline int CreateDirectivityFromFile( const std::string& sFilePath, const std::string& sName = "" )
218
	{
219
220
		CVAStruct oParams;
		oParams[ "filepath" ] = sFilePath;
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
221
		return CreateDirectivityFromParameters( oParams, sName );
222
	};
223
	virtual bool DeleteDirectivity( const int iID ) = 0;
224
	virtual CVADirectivityInfo GetDirectivityInfo( const int iID ) const = 0;
225
	virtual void GetDirectivityInfos( std::vector< CVADirectivityInfo >& voDest ) const = 0;
226
227
	virtual void SetDirectivityName( const int iID, const std::string& sName ) = 0;
	virtual std::string GetDirectivityName( const int iID ) const = 0;
228
229
230
231
	virtual void SetDirectivityParameters( const int iID, const CVAStruct& oParams ) = 0;
	virtual CVAStruct GetDirectivityParameters( const int iID, const CVAStruct& oParams ) const = 0;


Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
232
233
234
235
236
237
238
239
	virtual int CreateAcousticMaterial( const CVAAcousticMaterial& oMaterial, const std::string& sName = "" ) = 0;
	virtual int CreateAcousticMaterialFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
	inline int CreateAcousticMaterialFromFile( const std::string& sFilePath, const std::string& sName = "" )
	{
		CVAStruct oParams;
		oParams[ "filepath" ] = sFilePath;
		return CreateAcousticMaterialFromParameters( oParams, sName );
	};
240
241
242
	virtual bool DeleteAcousticMaterial( const int iID ) = 0;
	virtual CVAAcousticMaterial GetAcousticMaterialInfo( const int iID ) const = 0;
	virtual void GetAcousticMaterialInfos( std::vector< CVAAcousticMaterial >& voDest ) const = 0;
243
244
	virtual void SetAcousticMaterialName( const int iID, const std::string& sName ) = 0;
	virtual std::string GetAcousticMaterialName( const int iID ) const = 0;
245
246
247
248
	virtual void SetAcousticMaterialParameters( const int iID, const CVAStruct& oParams ) = 0;
	virtual CVAStruct GetAcousticMaterialParameters( const int iID, const CVAStruct& oParams ) const = 0;


Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
249
250
251
252
253
254
255
256
	virtual int CreateGeometryMesh( const CVAGeometryMesh& oMesh, const std::string& sName = "" ) = 0;
	virtual int CreateGeometryMeshFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
	inline int CreateGeometryMeshFromFile( const std::string& sFilePath, const std::string& sName = "" )
	{
		CVAStruct oParams;
		oParams[ "filepath" ] = sFilePath;
		return CreateGeometryMeshFromParameters( oParams, sName );
	};
257
258
	virtual bool DeleteGeometryMesh( const int iID ) = 0;
	virtual CVAGeometryMesh GetGeometryMeshInfo( const int iID ) const = 0;
259
260
261
	virtual void GetGeometryMeshIDs( std::vector< int >& viIDs ) const = 0;
	virtual void SetGeometryMeshName( const int iID, const std::string& sName ) = 0;
	virtual std::string GetGeometryMeshName( const int iID ) const = 0;
262
263
	virtual void SetGeometryMeshParameters( const int iID, const CVAStruct& oParams ) = 0;
	virtual CVAStruct GetGeometryMeshParameters( const int iID, const CVAStruct& oParams ) const = 0;
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
264
265
	virtual void SetGeometryMeshEnabled( const int iID, const bool bEnabled = true ) = 0;
	virtual bool GetGeometryMeshEnabled( const int iID ) const = 0;
266
267


268
269
270
271
272
273
274
275
276
277
278
	//! 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
	*/
279
	inline std::string CreateSignalSourceBufferFromFile( const std::string& sFilePath, const std::string& sName = "" )
280
281
	{
		CVAStruct oParams;
282
283
		oParams[ "filepath" ] = sFilePath;
		return CreateSignalSourceBufferFromParameters( oParams, sName );
284
285
286
287
288
289
290
291
292
293
294
295
296
	};

	//! 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
	*/
297
	virtual std::string CreateSignalSourceBufferFromSamples( const CVASampleBuffer& oSamples, const std::string& sName = "" )
298
299
	{
		CVAStruct oParams;
300
301
		oParams[ "samples" ][ "ch1" ] = oSamples;
		return CreateSignalSourceBufferFromParameters( oParams, sName );
302
	};
303
	virtual std::string CreateSignalSourceBufferMultichannelFromSamples( const std::vector< CVASampleBuffer >& voSamples, const std::string& sName = "" )
304
305
	{
		CVAStruct oParams;
306
307
308
		for( size_t i = 0; i < voSamples.size(); i++ )
			oParams[ "samples" ][ "ch" + std::to_string( long( i + 1 ) ) ] = voSamples[ i ];
		return CreateSignalSourceBufferFromParameters( oParams, sName );
309
	};
310
	virtual std::string CreateSignalSourceBufferFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
311
312
313
314
315

	//! Creates a text-to-speech (TTS) signal source
	/**
	  * Creates a signal source which streams generated samples from a text input.
	  *
316
	  * @param[in] sName		Name (optional, e.g. "Penny")
317
318
319
	  *
	  * @return Signal source ID
	  */
320
	virtual std::string CreateSignalSourceTextToSpeech( const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
321
322
323
324
325
326

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

Jonas Stienen's avatar
Jonas Stienen committed
332
333
	//! Creates a network-based signal source
	/**
Dipl.-Ing. Jonas Stienen's avatar
style    
Dipl.-Ing. Jonas Stienen committed
334
335
	  * Creates a signal source which receives audio samples via network.
	  * Therefore an IP socket is set up with the given parameters.
336
	  *
Dipl.-Ing. Jonas Stienen's avatar
style    
Dipl.-Ing. Jonas Stienen committed
337
338
339
340
341
342
343
	  * @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
344
	  */
345
	virtual std::string CreateSignalSourceNetworkStream( const std::string& sInterface, const int iPort, const std::string& sName = "" ) = 0;
346

Jonas Stienen's avatar
Jonas Stienen committed
347
348
349
350
351
	//! Creates a rotating engine source
	/**
	  * \param sName Name of the engine
	  * \return ID of signal source
	  */
352
	virtual std::string CreateSignalSourceEngine( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
353
354
355
356
357

	//! Creates a machine signal source
	/**
	  * \param sName Name of the machine
	  */
358
	virtual std::string CreateSignalSourceMachine( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
359
360
361
362

	//! Deletes a signal source
	/**
	 * Deletes a signal source. This is only possible if it is not in use.
363
	 *
Jonas Stienen's avatar
Jonas Stienen committed
364
365
366
	 * \return true, if the signal source has been deleted
	 *         false, otherwise
	 */
367
	virtual bool DeleteSignalSource( const std::string& sID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
368
369
370
371
372
373

	//! 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.
374
	 *
Jonas Stienen's avatar
Jonas Stienen committed
375
376
377
378
379
380
	 * \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
381
382
	 */
	virtual std::string RegisterSignalSource( IVAAudioSignalSource* pSignalSource, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
383
384
385
386
387

	//! 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.
388
	 *
Jonas Stienen's avatar
Jonas Stienen committed
389
390
391
392
393
394
395
	 * \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
	 */
396
	virtual bool UnregisterSignalSource( IVAAudioSignalSource* pSignalSource ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
397
398

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

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

	//! Returns the playback state flag (bit-vector) of an audiofile signal source
405
	virtual int GetSignalSourceBufferPlaybackState( const std::string& sSignalSourceID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
406
407
408
409
410

	//! 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).
	  */
411
	virtual void SetSignalSourceBufferPlaybackAction( const std::string& sSignalSourceID, int iPlaybackAction ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
412
413
414
415
416
417

	//! Set the playback position of an audiofile signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param dPlaybackPosition		Playback position [s]
	 */
418
	virtual void SetSignalSourceBufferPlaybackPosition( const std::string& sSignalSourceID, double dPlaybackPosition ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
419
420
421
422
423
424

	//! Set playback looping mode (true = looping)
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param bLooping				Playback is looping
	 */
425
	virtual void SetSignalSourceBufferIsLooping( const std::string& sSignalSourceID, bool bLooping ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
426
427
428
429
430

	//! Get playback looping mode (true = looping)
	/**
	 * \param sSignalSourceID		Signal source ID
	 */
431
	virtual bool GetSignalSourceBufferIsLooping( const std::string& sSignalSourceID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
432
433
434
435
436

	//! Starts the signal of a machine source
	/**
	 * \param sSignalSourceID		Signal source ID
	 */
437
	inline void SetSignalSourceMachineStartMachine( const std::string& sSignalSourceID )
438
439
	{
		CVAStruct oParams;
440
441
442
		oParams[ "set" ] = "action";
		oParams[ "value" ] = "start";
		SetSignalSourceParameters( sSignalSourceID, oParams );
443
	};
Jonas Stienen's avatar
Jonas Stienen committed
444
445
446
447
448

	//! Halts the signal of a machine source
	/**
	 * \param sSignalSourceID		Signal source ID
	 */
449
	inline void SetSignalSourceMachineHaltMachine( const std::string& sSignalSourceID )
450
451
	{
		CVAStruct oParams;
452
453
454
		oParams[ "set" ] = "action";
		oParams[ "value" ] = "stop";
		SetSignalSourceParameters( sSignalSourceID, oParams );
455
	};
Jonas Stienen's avatar
Jonas Stienen committed
456
457
458
459
460
461

	//! Returns the state of a machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \return						Machine state
	 */
462
	inline std::string GetSignalSourceMachineStateStr( const std::string& sSignalSourceID ) const
463
464
	{
		CVAStruct oParams, oRet;
465
466
467
468
469
		oParams[ "get" ] = "state";
		oRet = GetSignalSourceParameters( sSignalSourceID, oParams );
		if( oRet.HasKey( "state" ) )
			if( oRet[ "state" ].IsString() )
				return oRet[ "state" ].ToString();
470
471
472
473
474
			else
				return "error";
		else
			return "unkown";
	};
Jonas Stienen's avatar
Jonas Stienen committed
475
476
477
478
479
480

	//! Sets the speed of a machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param dSpeed				Machine speed (0 .. not-too-large)
	 */
481
	inline void SetSignalSourceMachineSpeed( const std::string& sSignalSourceID, double dSpeed )
482
483
	{
		CVAStruct oParams;
484
485
486
		oParams[ "set" ] = "S";
		oParams[ "value" ] = dSpeed;
		SetSignalSourceParameters( sSignalSourceID, oParams );
487
	};
Jonas Stienen's avatar
Jonas Stienen committed
488
489
490
491
492
493

	//! Sets the speed of a machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \return						Machine speed
	 */
494
	inline double GetSignalSourceMachineSpeed( const std::string& sSignalSourceID ) const
495
496
	{
		CVAStruct oParams, oRet;
497
498
499
500
501
		oParams[ "get" ] = "speed";
		oRet = GetSignalSourceParameters( sSignalSourceID, oParams );
		if( oRet.HasKey( "speed" ) )
			if( oRet[ "speed" ].IsNumeric() )
				return double( oRet[ "speed" ] );
502
503
504

		return 1.0f;
	};
Jonas Stienen's avatar
Jonas Stienen committed
505
506
507
508
509
510

	//! Set start file sample of machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param sFilePath				Path to audio file
	 */
511
	inline void SetSignalSourceMachineStartFile( const std::string& sSignalSourceID, const std::string& sFilePath )
512
513
	{
		CVAStruct oParams;
514
515
516
		oParams[ "set" ] = "StartSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
517
	};
Jonas Stienen's avatar
Jonas Stienen committed
518
519
520
521
522
523

	//! Set idle file sample of machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param sFilePath				Path to audio file
	 */
524
525
526
	inline void SetSignalSourceMachineIdleFile( const std::string& sSignalSourceID, const std::string& sFilePath )
	{
		CVAStruct oParams;
527
528
529
		oParams[ "set" ] = "IdleSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
530
	};
Jonas Stienen's avatar
Jonas Stienen committed
531
532
533
534
535
536

	//! Set stop file sample of machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param sFilePath				Path to audio file
	 */
537
	inline void SetSignalSourceMachineStopFile( const std::string& sSignalSourceID, const std::string& sFilePath )
538
539
	{
		CVAStruct oParams;
540
541
542
		oParams[ "set" ] = "StopSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
543
	};
Jonas Stienen's avatar
Jonas Stienen committed
544
545
546
547

	//! Adds a sound playback for a sequencer signal source
	/**
	 * This method adds the playback of a sound for a sequencer signal source.
548
	 *
Jonas Stienen's avatar
Jonas Stienen committed
549
550
551
552
553
554
555
	 * \param sSignalSourceID	ID of the sequencer signal source
	 * \param iSound			ID of the sound
	 * \param iFlags			Playback flags
	 * \param dTimecode			Playback time (0 => instant playback)
	 *
	 * \return Playback ID
	 */
556
	virtual int AddSignalSourceSequencerSoundPlayback( const std::string& sSignalSourceID, const int iSoundID, const int iFlags, const double dTimecode = 0 ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
557
558
559
560
561
562

	//! Removes an existing sound playback from a sequencer signal source
	/**
	 * \return true, if the playback has been removed
	 *         false, otherwise
	 */
563
	virtual bool RemoveSignalSourceSequencerSoundPlayback( const int iID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
564
565
566
567
568
569
570

	// TODO: AlterSoundPlayback?

	//! Set parameters for a signal source
	/**
	 * This method sets parameters of a signal source. Behavior depends on type and
	 * implementation of the referred instance.
571
	 *
Jonas Stienen's avatar
Jonas Stienen committed
572
573
574
	 * \param sSignalSourceID	ID of signal source
	 * \param oParams	Parameter structure
	 */
575
	virtual void SetSignalSourceParameters( const std::string& sSignalSourceID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
576
577
578
579
580

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

587

588
589
	//! Returns wheather a synchronized scene modification is in progress
	virtual bool IsUpdateLocked() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
590
591
592
593
594
595
596

	//! 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.
	 */
597
	virtual void LockUpdate() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
598
599
600
601
602
603
604
605
606
607

	//! 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
	 */
608
	virtual int UnlockUpdate() = 0;
609

610

Jonas Stienen's avatar
Jonas Stienen committed
611
612
613
614
	//! 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.
615
	 *
Jonas Stienen's avatar
Jonas Stienen committed
616
617
618
619
620
621
622
	 * \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
	 */
623
624
625
626
627
628
	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
629
630
631
632
633
634
635

	//! 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.
636
	 *
Jonas Stienen's avatar
Jonas Stienen committed
637
638
639
640
641
642
643
	 * \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
	 */
644
	virtual int CreateSoundSourceExplicitRenderer( const std::string& sRendererID, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
645
646
647
648
649
650
651
652

	//! Schallquelle entfernen
	/**
	 * Diese Methode entfernt eine Schallquelle aus der Szene
	 *
	 * \return 0 falls die Schallquelle entfernt wurde,
	 *         -1 im Fehlerfall
	 */
653
	virtual int DeleteSoundSource( const int iID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
654
655
656
657
658
659
660
661

	//! 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()
	  */
662
	virtual void SetSoundSourceEnabled( const int iID, const bool bEnabled = true ) = 0;
663

Jonas Stienen's avatar
Jonas Stienen committed
664
665
666
667
668
669
670
	//! Returns sound source enabled/disabled status
	/**
	  * @param[in] iSoundSourceID	Sound source identifier
	  * @return					Enabled (true) or disabled (false)
	  *
	  * @sa SetSoundSourceEnabled()
	  */
671
	virtual bool GetSoundSourceEnabled( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
672
673

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

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

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

682
683
	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
684
685
686

	//! Attach a signal source to sound source
	/**
687
	  * Let a sound source play back samples from the given signal source.
Jonas Stienen's avatar
Jonas Stienen committed
688
689
690
691
692
693
694
695
	  * An empty string removes the signal source from sound source (silence).
	  *
	  * \see RemoveSoundSourceSignalSource
	  *
	  * \param iID	Sound source identifier
	  * \param sSignalSourceID	Signal source identifier
	  *
	  */
696
	virtual void SetSoundSourceSignalSource( const int iSoundSourceID, const std::string& sSignalSourceID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
697
698
699
700
701
702
703

	//! 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
	  */
704
	inline void RemoveSoundSourceSignalSource( const int iID )
705
	{
706
		SetSoundSourceSignalSource( iID, "" );
707
	};
Jonas Stienen's avatar
Jonas Stienen committed
708
709

	//! Auralisierungsmodus einer Schallquelle zurückgeben (Bitvektor)
710
	virtual int GetSoundSourceAuralizationMode( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
711
712
713
714
715

	//! Auralisierungsmodus einer Schallquelle setzen (Bitvektor)
	/**
	 * Mit dieser Methode wird der Auralisierungsmodus für eine Schallquelle festgelegt.
	 */
716
	virtual void SetSoundSourceAuralizationMode( const int iSoundSourceID, int iAuralizationMode ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
717
718
719
720
721
722
723
724
725

	//! 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
	  */
726
	virtual void SetSoundSourceParameters( const int iID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
727
728
729
730
731
732
733
734
735
736

	//! Get sound source parameters
	/**
	  * This general parameter getter can be used for quick solutions retrieving
	  * listener parameters without introducing new methods to the main interface.
	  *
	  * \param iSoundSourceID Sound source identifier
	  * \param oParams Magic struct with the parameters that are requested
	  * \return Magic struct with the parameter values requested
	  */
737
	virtual CVAStruct GetSoundSourceParameters( const int iID, const CVAStruct& oParams ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
738
739
740
741
742

	//! Returns the directivity of a sound source
	/**
	 * If the sound source is not assigned a directivity, the methods returns -1.
	 */
743
	virtual int GetSoundSourceDirectivity( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
744
745
746
747
748

	//! Sets the directivity of a sound source
	/**
	 * In order to remove an assigned directivity, you can pass -1 to the method.
	 */
749
	virtual void SetSoundSourceDirectivity( int iSoundSourceID, int iDirectivityID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
750
751
752
753
754

	//! Lautstärke einer Schallquelle zurückgeben
	/**
	 * Gibt den Verstärkungsfaktor zurück (nicht Dezibel)
	 */
755
	virtual double GetSoundSourceSoundPower( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
756
757
758
759
760

	//! Lautstärke einer Schallquelle setzen
	/**
	 * Setzt die Lautstärke einer Schallquelle als Verstärkungsfaktor (nicht Dezibel).
	 */
761
	virtual void SetSoundSourceSoundPower( const int iSoundSourceID, const double dSoundPower ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
762
763
764
765
766

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

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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
772
773
774
775
776
777
	//! Sound source pose getter (pose = position & orientation)
	virtual void GetSoundSourcePose( const int iID, VAVec3& vPos, VAQuat& qOrient ) const = 0;

	//! Sound source pose setter (pose = position & orientation)
	virtual void SetSoundSourcePose( const int iID, const VAVec3& vPos, const VAQuat& qOrient ) = 0;

Jonas Stienen's avatar
Jonas Stienen committed
778
	//! Position einer Schallquelle zurückgeben (Positionsvektor) 
779
	virtual VAVec3 GetSoundSourcePosition( const int iID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
780
781

	//! Orientierung einer Schallquelle zurückgeben (View- und Up-Vektor) 
782
	virtual VAQuat GetSoundSourceOrientation( const int iID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
783

784
785
	//! Orientierung einer Schallquelle zurückgeben (View- und Up-Vektor) 
	virtual void GetSoundSourceOrientationVU( const int iID, VAVec3& v3View, VAVec3& v3Up ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
786
787
788
789
790

	//! Position einer Schallquelle setzen (Positionsvektor) 
	/**
	 * - Sets the velocity of the sound source to zero
	 */
791
	virtual void SetSoundSourcePosition( const int iID, const VAVec3& v3Pos ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
792
793

	//! Orientierung einer Schallquelle setzen (View- und Up-Vektor) 
794
	virtual void SetSoundSourceOrientationVU( const int iID, const VAVec3& v3View, const VAVec3& v3Up ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
795

796
797
	//! Return all sound receiver IDs
	virtual void GetSoundReceiverIDs( std::vector< int >& viIDs ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
798

799
	//! Creates a sound receiver
Jonas Stienen's avatar
Jonas Stienen committed
800
	/**
801
	 * This method creates a new sound receiver (listener).
802
	 *
803
	 * @param[in] sName		Name (optional)
Jonas Stienen's avatar
Jonas Stienen committed
804
	 *
805
	 * \return ID of the new listener, if the method succeeded, -1, otherwise
Jonas Stienen's avatar
Jonas Stienen committed
806
	 */
807
	virtual int CreateSoundReceiver( const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
808
809
810
811
812
813

	//! Creates a listener explicitly for a given renderer
	/**
	 * This method creates a new listener for a special renderer, only.
	 * the listener will be skipped by all other renderers. See
	 * GetRendererLister() for a list of all available renderer identifier.
814
	 *
Jonas Stienen's avatar
Jonas Stienen committed
815
816
817
818
819
	 * \param	sName			Name
	 * \param	sRendererID		Renderer identifier
	 *
	 * \return ID of the new listener, if the method succeeded and -1, otherwise
	 */
820
	virtual int CreateSoundReceiverExplicitRenderer( const std::string& sRendererID, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
821
822
823
824
825
826
827
828
829

	//! 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
	 */
830
	virtual int DeleteSoundReceiver( const int iID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
831
832
833
834
835
836
837
838

	//! Enables or disables a virtual listener (removes the listener from audio processing)
	/**
	  * @param[in] iListenerID	Listener identifier
	  * @param[in] bEnabled		Enable (true) or disable (false) sound source
	  *
	  * @sa GetListenerEnabled()
	  */
839
	virtual void SetSoundReceiverEnabled( const int iID, const bool bEnabled = true ) = 0;
840

841
	//! Returns sound receiver enabled/disabled status
Jonas Stienen's avatar
Jonas Stienen committed
842
843
844
845
846
847
	/**
	  * @param[in] iListenerID	Listener identifier
	  * @return				Enabled (true) or disabled (false)
	  *
	  * @sa SetListenerEnabled()
	  */
848
	virtual bool GetSoundReceiverEnabled( const int iID ) const = 0;
849

Jonas Stienen's avatar
Jonas Stienen committed
850
	//! Name eines Hörers zurückgeben
851
	virtual std::string GetSoundReceiverName( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
852
853

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

	//! Auralisierungsmodus eines Hörers zurückgeben (Bitvektor)
857
	virtual int GetSoundReceiverAuralizationMode( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
858
859
860
861
862

	//! Auralisierungsmodus eines Hörers setzen (Bitvektor)
	/**
	 * Mit dieser Methode wird der Auralisierungsmodus für eines Hörers festgelegt.
	 */
863
	virtual void SetSoundReceiverAuralizationMode( const int iSoundReceiverID, const int iAuralizationMode ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
864
865
866
867
868
869
870
871
872

	//! Set listener parameters
	/**
	  * This general parameter setter can be used for quick solutions changing
	  * listener parameters without introducing new methods to the main interface.
	  *
	  * \param iListenerID Listener identifier
	  * \param oParams Magic struct with the parameters
	  */
873
	virtual void SetSoundReceiverParameters( const int iID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
874
875
876
877
878
879
880
881
882
883

	//! Get listener parameters
	/**
	  * This general parameter getter can be used for quick solutions retrieving
	  * listener parameters without introducing new methods to the main interface.
	  *
	  * \param iListenerID Listener identifier
	  * \param oParams Magic struct with the parameters that are requested
	  * \return Magic struct with the parameter values requested
	  */
884
	virtual CVAStruct GetSoundReceiverParameters( const int iID, const CVAStruct& oArgs ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
885
886

	//! Returns for a listener the ID of the assigned HRIR dataset
887
	virtual int GetSoundReceiverDirectivity( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
888
889
890

	//! Set the HRIR dataset for a listener
	/**
891
892
	* \note In order to set no HRIR dataset, you can pass -1 to the method.
	*/
893
	virtual void SetSoundReceiverDirectivity( const int iSoundReceiverID, const int iDirectivityID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
894

895
896
897
	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
898

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
899
900
901
902
903
904
	//! 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;

905
906
	//! Position eines Hörers zurückgeben (Positionsvektor) 
	virtual VAVec3 GetSoundReceiverPosition( const int iID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
907
908
909

	//! Position eines Hörers setzen (Positionsvektor) 
	/**
910
	 * - Sets the velocity of the listener to zero
Jonas Stienen's avatar
Jonas Stienen committed
911
	 */
912
	virtual void SetSoundReceiverPosition( const int iID, const VAVec3& v3Pos ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
913

914
915
	//! 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
916

917
918
	//! 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
919

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

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

926
	virtual VAQuat GetSoundReceiverHeadAboveTorsoOrientation( const int iID ) const = 0;
927
	virtual void SetSoundReceiverHeadAboveTorsoOrientation( const int iID, const VAQuat& qOrient ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
928
929
930

	//! Returns the position and orientation of the real-world listener's head
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
931
932
933
934
935
936
937
	* \note The parameter iListenerID has been added for future versions and is
	*       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
938
939
940

	//! Updates the position and orientation of the real-world listener's head
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
941
942
943
944
945
946
947
948
949
950
951
952
	* This function is used to provide the crosstalk-cancellation module
	* with the current position of the listeners head in the real-world.
	*
	* \note The parameter iListenerID has been added for future versions and is
	*       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;
	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
953

954
955
956
	virtual VAQuat GetSoundReceiverRealWorldHeadAboveTorsoOrientation( const int iID ) const = 0;
	virtual void SetSoundReceiverRealWorldHeadAboveTorsoOrientation( const int iID, const VAQuat& qOrient ) const = 0;

Jonas Stienen's avatar
Jonas Stienen committed
957

958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
	//! 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;

	//! Get homogeneous medium special parameters
	virtual CVAStruct GetHomogeneousMediumParameters() = 0;


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

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

1001
1002
1003
1004
1005
	//! Get scene info
	virtual CVASceneInfo GetSceneInfo( const std::string& sID ) const = 0;
	
	//! Returns the name of a portal
	virtual std::string GetSceneName( const std::string& sID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1006

1007
1008
1009
1010
	//! Sets the name of a portal
	virtual void SetSceneName( const std::string& sID, const std::string& sName ) = 0;

	//! Set scene enabled or disabled
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1011
	virtual void SetSceneEnabled( const std::string& sID, const bool bEnabled = true ) = 0;
1012
1013

	//! Scene enabled status (true, if enabled)
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1014
1015
	virtual bool GetSceneEnabled( const std::string& sID ) const = 0;

1016
1017

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

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

1023
	virtual CVASoundPortalInfo GetSoundPortalInfo( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1024
1025

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

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

1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
	//! 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;

1055
	virtual CVAStruct GetSoundPortalParameters( const int iID ) const = 0;
1056

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

1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
	//! Sound portal position setter
	virtual void SetSoundPortalPosition( const int iSoundPortalID, const VAVec3& vPos ) = 0;

	//! Sound portal position getter
	virtual VAVec3 SetSoundPortalPosition( const int iSoundPortalID ) const = 0;

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

	//! Sound portal orientation getter
	virtual VAQuat GetSoundPortalOrientation( const int iSoundPortalID ) const = 0;

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1071
1072
1073
1074
1075
1076
1077
1078
1079
	//! Sound portal enabled setter
	virtual void SetSoundPortalEnabled( const int iSoundPortalID, const bool bEnabled = true ) = 0;

	//! Sound portal orientation getter
	virtual bool GetSoundPortalEnabled( const int iSoundPortalID ) const = 0;




1080
1081
1082
1083
1084
1085
	//! Returns all available renderers (default: only those that are enabled)
	/**
	* @param [out]	voRenderer	List of renderers modules
	* @param [in]	bFilterEnabled	If true, only enabled renderers are returned (via configuration, during runtime)
	*/
	virtual void GetRenderingModules( std::vector< CVAAudioRendererInfo >& voRenderer, const bool bFilterEnabled = true ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1086
1087

	//! Mutes a rendering module audio output
1088
	virtual void SetRenderingModuleMuted( const std::string& sModuleID, const bool bMuted = true ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1089
1090

	//! Returns if rendering module audio output is muted or not
1091
	virtual bool GetRenderingModuleMuted( const std::string& sModuleID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1092
1093

	//! Sets the rendering module audio output gain
1094
	virtual void SetRenderingModuleGain( const std::string& sModuleID, const double dGain ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1095
1096

	//! Returns the rendering module audio output gain
1097
1098
	virtual double GetRenderingModuleGain( const std::string& sModuleID ) const = 0;

Jonas Stienen's avatar
Jonas Stienen committed
1099

1100
1101
1102
1103
1104
1105
	//! Returns all available reproductions (default: only those that are enabled)
	/**
	 * @param [out]	voReproductions	List of reproduction modules
	 * @param [in]	bFilterEnabled	If true, only enabled renderers are returned (via configuration, during runtime)
	 */
	virtual void GetReproductionModules( std::vector< CVAAudioReproductionInfo >& voReproductions, const bool bFilterEnabled = true ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1106
1107

	//! Mutes a rendering module audio output
1108
	virtual void SetReproductionModuleMuted( const std::string& sModuleID, const bool bMuted = true ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1109
1110

	//! Returns if rendering module audio output is muted or not
1111
	virtual bool IsReproductionModuleMuted( const std::string& sModuleID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1112
1113

	//! Sets the rendering module audio output gain
1114
	virtual void SetReproductionModuleGain( const std::string& sModuleID, const double dGain ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1115
1116

	//! Returns the rendering module audio output gain
1117
	virtual double GetReproductionModuleGain( const std::string& sModuleID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1118
1119


1120
	//! Verstärkung der Eingangkanäle (Geräteeingang) zurückgeben [Faktor] 
1121
	virtual double GetInputGain() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1122
1123

	//! Verstärkung der Eingangkanäle (Geräteeingang) setzen [Faktor] 
1124
	virtual void SetInputGain( const double dGain ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1125
1126

	//! Status der Stummschaltung der Audioeingänge zurückgeben
1127
	virtual bool GetInputMuted() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1128
1129

	//! Stummschaltung der Audioeingänge ein-/ausschalten
1130
	virtual void SetInputMuted( const bool bMuted = true ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1131
1132

	//! Globale Ausgabeverstärkung [Faktor] zurückgeben
1133
	virtual double GetOutputGain() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1134
1135

	//! Globale Ausgabeverstärkung [Faktor] setzen
1136
	virtual void SetOutputGain( const double dGain ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1137
1138

	//! Status der globalen Stummschaltung zurückgeben
1139
	virtual bool GetOutputMuted() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1140
1141

	//! Globale Stummschaltung ein-/ausschalten
1142
	virtual void SetOutputMuted( const bool bMuted = true ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1143
1144

	//! Globalen Auralisierungmodus zurückgeben
1145
	virtual int GetGlobalAuralizationMode() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1146
1147
1148
1149
1150
1151
1152

	//! Globalen Auralisierungmodus setzen
	/**
	 * Dieser Modus fungiert wie ein Filter. Wenn hier eine Komponente
	 * deaktiviert wird, gilt dies für alle Schallquellen und Hörer.
	 * Umgekehrt aber nicht.
	 */
1153
	virtual void SetGlobalAuralizationMode( const int iAuralizationMode ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
1154
1155
1156
1157