VAInterface.h 51.9 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
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
124 125 126
	/**
	  * @param [out] pVersionInfo Core version information
	  */
127
	virtual void GetVersionInfo( CVAVersionInfo* pVersionInfo ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
128 129

	//! Set the output stream for debug messages
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
130 131 132
	/**
	  * @param [in] posDebug Debug output stream
	  */
133
	virtual void SetDebugStream( std::ostream* posDebug ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
134 135


136
	//! Returns the state of the core
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
137 138 139
	/**
	  * @return Core state
	  */
140
	virtual int GetState() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
141 142 143 144 145 146 147 148

	//! 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
149
	 * case the core remains in the state VA_CORESTATE_CREATED.
Jonas Stienen's avatar
Jonas Stienen committed
150 151 152 153 154 155 156
	 * 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.
	 *
157
	 * @note Initialization does not detach event handlers
Jonas Stienen's avatar
Jonas Stienen committed
158
	 */
159
	virtual void Initialize() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
160 161 162 163 164 165 166 167 168 169 170 171 172

	//! 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.
	 *
173
	 * @note Finalization does not detach event handlers
Jonas Stienen's avatar
Jonas Stienen committed
174
	 */
175
	virtual void Finalize() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
176 177 178

	//! Full reset of the core. Clears all scene objects, resources, etc.
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
179
	 * Clear all scenes, removes sound entities, resets states and medium values
Jonas Stienen's avatar
Jonas Stienen committed
180
	 */
181
	virtual void Reset() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
182

183

184 185
	//! Attaches a handler for core events to the core instance
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
186
	* @oaram[in] pEventHandler Event handler pointer
187 188 189 190 191
	 * @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
192
	virtual void AttachEventHandler( IVAEventHandler* pEventHandler ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
193 194 195

	//! Detaches a handler for core events from the core instance
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
196
	* @oaram[in] pEventHandler Event handler pointer
197
	 * @note Detaching event handlers it always possible,
Jonas Stienen's avatar
Jonas Stienen committed
198 199 200 201 202 203 204
	 *            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.
	 */
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
205
	virtual void DetachEventHandler( IVAEventHandler* pEventHandler ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
206

207

208
	//! Get all registered modules of the core
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
209 210 211
	/**
	  * @param[out] voModuleInfos Vector with module infos
	  */
212
	virtual void GetModules( std::vector< CVAModuleInfo >& voModuleInfos ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
213

214
	//! Calls a module and returns the answer
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
215 216 217 218 219 220 221 222 223 224
	/**
	  * 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
	  */
225
	virtual CVAStruct CallModule( const std::string& sModuleName, const CVAStruct& oArgs ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
226

227

Jonas Stienen's avatar
Jonas Stienen committed
228 229
	//! Adds a search path to the core instance
	/**
230 231
	  * @param[in]	sPath	Local relative or absolute path
	  * @return	True, if path is valid at core side
Jonas Stienen's avatar
Jonas Stienen committed
232 233 234
	  */
	virtual bool AddSearchPath( const std::string& sPath );

235
	//! Returns a struct with entries for each search paths
236 237 238
	/**
	  * @return	Encapsulated search paths
	  */
239
	virtual CVAStruct GetSearchPaths() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
240

241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263
	//! 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
	  */
264
	virtual CVAStruct GetHardwareConfiguration() const = 0;
265

266 267 268 269 270 271 272
	//! 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
273
	virtual int CreateDirectivityFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
274

275
	//! Create a directivity from a file path
276 277 278 279 280 281
	/**
	  * @param[in] sFilePath File path (relative or absolute or macro)
	  * @param[in] sName Versatile name
	  *
	  * @return	Directivity identifier
	  */
282
	inline int CreateDirectivityFromFile( const std::string& sFilePath, const std::string& sName = "" )
283
	{
284 285
		CVAStruct oParams;
		oParams[ "filepath" ] = sFilePath;
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
286
		return CreateDirectivityFromParameters( oParams, sName );
287
	};
288 289 290 291 292 293 294

	//! Delete a directivity
	/**
	  * @param[in] iID  Identifier
	  *
	  * @return True, if directivity was found and could be released (was not in use)
	  */
295
	virtual bool DeleteDirectivity( const int iID ) = 0;
296 297 298 299 300 301 302

	//! Directivity info getter
	/**
	  * @param[in] iID  Identifier
  	  *
	  * @return Directivity information
	  */
303
	virtual CVADirectivityInfo GetDirectivityInfo( const int iID ) const = 0;
304 305 306 307 308
	
	//! Directivity info getter
	/**
	  * @param[out] voDest  Directivity information vector
	  */
309
	virtual void GetDirectivityInfos( std::vector< CVADirectivityInfo >& voDest ) const = 0;
310 311 312 313 314 315

	//! Directivity name setter
	/**
	  * @param[in] iID  Identifier
	  * @param[in] sName  Versatile name
	  */
316
	virtual void SetDirectivityName( const int iID, const std::string& sName ) = 0;
317 318 319 320 321 322
	
	//! Directivity name getter
	/**
	  * @param[in] iID  Identifier
	  * @return Versatile name
	  */
323
	virtual std::string GetDirectivityName( const int iID ) const = 0;
324 325 326 327 328 329 330
	

	//! Directivity parameter setter
	/**
	  * @param[in] iID  Identifier
	  * @param[in] oParams  Parameters
	  */
331
	virtual void SetDirectivityParameters( const int iID, const CVAStruct& oParams ) = 0;
332 333 334 335 336 337
	
	//! Directivity parameter getter
	/**
	  * @param[in] iID  Identifier
	  * @return Parameters
	  */
338 339 340
	virtual CVAStruct GetDirectivityParameters( const int iID, const CVAStruct& oParams ) const = 0;


Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
341 342 343 344 345 346 347 348
	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 );
	};
349 350 351
	virtual bool DeleteAcousticMaterial( const int iID ) = 0;
	virtual CVAAcousticMaterial GetAcousticMaterialInfo( const int iID ) const = 0;
	virtual void GetAcousticMaterialInfos( std::vector< CVAAcousticMaterial >& voDest ) const = 0;
352 353
	virtual void SetAcousticMaterialName( const int iID, const std::string& sName ) = 0;
	virtual std::string GetAcousticMaterialName( const int iID ) const = 0;
354 355 356
	virtual void SetAcousticMaterialParameters( const int iID, const CVAStruct& oParams ) = 0;
	virtual CVAStruct GetAcousticMaterialParameters( const int iID, const CVAStruct& oParams ) const = 0;

357 358 359 360 361 362 363
	//! 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
364
	virtual int CreateGeometryMesh( const CVAGeometryMesh& oMesh, const std::string& sName = "" ) = 0;
365 366 367 368 369 370 371 372
	
	//! 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
373
	virtual int CreateGeometryMeshFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
374 375 376 377 378 379 380 381
	
	//! 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
382 383 384 385 386 387
	inline int CreateGeometryMeshFromFile( const std::string& sFilePath, const std::string& sName = "" )
	{
		CVAStruct oParams;
		oParams[ "filepath" ] = sFilePath;
		return CreateGeometryMeshFromParameters( oParams, sName );
	};
388

389
	virtual bool DeleteGeometryMesh( const int iID ) = 0;
390
	virtual CVAGeometryMesh GetGeometryMesh( const int iID ) const = 0;
391 392 393
	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;
394 395
	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
396 397
	virtual void SetGeometryMeshEnabled( const int iID, const bool bEnabled = true ) = 0;
	virtual bool GetGeometryMeshEnabled( const int iID ) const = 0;
398 399


400 401 402 403 404 405 406 407 408 409 410
	//! 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
	*/
411
	inline std::string CreateSignalSourceBufferFromFile( const std::string& sFilePath, const std::string& sName = "" )
412 413
	{
		CVAStruct oParams;
414 415
		oParams[ "filepath" ] = sFilePath;
		return CreateSignalSourceBufferFromParameters( oParams, sName );
416 417 418 419 420 421 422 423 424 425 426 427 428
	};

	//! 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
	*/
429
	virtual std::string CreateSignalSourceBufferFromSamples( const CVASampleBuffer& oSamples, const std::string& sName = "" )
430 431
	{
		CVAStruct oParams;
432 433
		oParams[ "samples" ][ "ch1" ] = oSamples;
		return CreateSignalSourceBufferFromParameters( oParams, sName );
434
	};
435
	virtual std::string CreateSignalSourceBufferMultichannelFromSamples( const std::vector< CVASampleBuffer >& voSamples, const std::string& sName = "" )
436 437
	{
		CVAStruct oParams;
438 439 440
		for( size_t i = 0; i < voSamples.size(); i++ )
			oParams[ "samples" ][ "ch" + std::to_string( long( i + 1 ) ) ] = voSamples[ i ];
		return CreateSignalSourceBufferFromParameters( oParams, sName );
441
	};
442
	virtual std::string CreateSignalSourceBufferFromParameters( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
443 444 445 446 447

	//! Creates a text-to-speech (TTS) signal source
	/**
	  * Creates a signal source which streams generated samples from a text input.
	  *
448
	  * @param[in] sName		Name (optional, e.g. "Penny")
449 450 451
	  *
	  * @return Signal source ID
	  */
452
	virtual std::string CreateSignalSourceTextToSpeech( const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
453 454 455 456 457 458

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

Jonas Stienen's avatar
Jonas Stienen committed
464 465
	//! Creates a network-based signal source
	/**
Dipl.-Ing. Jonas Stienen's avatar
style  
Dipl.-Ing. Jonas Stienen committed
466 467
	  * Creates a signal source which receives audio samples via network.
	  * Therefore an IP socket is set up with the given parameters.
468
	  *
Dipl.-Ing. Jonas Stienen's avatar
style  
Dipl.-Ing. Jonas Stienen committed
469 470 471 472 473 474 475
	  * @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
476
	  */
477
	virtual std::string CreateSignalSourceNetworkStream( const std::string& sInterface, const int iPort, const std::string& sName = "" ) = 0;
478

Jonas Stienen's avatar
Jonas Stienen committed
479 480 481 482 483
	//! Creates a rotating engine source
	/**
	  * \param sName Name of the engine
	  * \return ID of signal source
	  */
484
	virtual std::string CreateSignalSourceEngine( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
485 486 487 488 489

	//! Creates a machine signal source
	/**
	  * \param sName Name of the machine
	  */
490
	virtual std::string CreateSignalSourceMachine( const CVAStruct& oParams, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
491 492 493 494

	//! Deletes a signal source
	/**
	 * Deletes a signal source. This is only possible if it is not in use.
495
	 *
Jonas Stienen's avatar
Jonas Stienen committed
496 497 498
	 * \return true, if the signal source has been deleted
	 *         false, otherwise
	 */
499
	virtual bool DeleteSignalSource( const std::string& sID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
500 501 502 503 504 505

	//! 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.
506
	 *
Jonas Stienen's avatar
Jonas Stienen committed
507 508 509 510 511 512
	 * \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
513 514
	 */
	virtual std::string RegisterSignalSource( IVAAudioSignalSource* pSignalSource, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
515 516 517 518 519

	//! 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.
520
	 *
Jonas Stienen's avatar
Jonas Stienen committed
521 522 523 524 525 526 527
	 * \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
	 */
528
	virtual bool UnregisterSignalSource( IVAAudioSignalSource* pSignalSource ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
529 530

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

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

	//! Returns the playback state flag (bit-vector) of an audiofile signal source
537
	virtual int GetSignalSourceBufferPlaybackState( const std::string& sSignalSourceID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
538 539 540 541 542

	//! 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).
	  */
543
	virtual void SetSignalSourceBufferPlaybackAction( const std::string& sSignalSourceID, const int iPlaybackAction ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
544 545 546 547 548 549

	//! Set the playback position of an audiofile signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param dPlaybackPosition		Playback position [s]
	 */
550
	virtual void SetSignalSourceBufferPlaybackPosition( const std::string& sSignalSourceID, const double dPlaybackPosition ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
551 552 553 554 555 556

	//! Set playback looping mode (true = looping)
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param bLooping				Playback is looping
	 */
557
	virtual void SetSignalSourceBufferLooping( const std::string& sSignalSourceID, const bool bLooping = true ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
558 559 560 561 562

	//! Get playback looping mode (true = looping)
	/**
	 * \param sSignalSourceID		Signal source ID
	 */
563
	virtual bool GetSignalSourceBufferLooping( const std::string& sSignalSourceID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
564 565 566 567 568

	//! Starts the signal of a machine source
	/**
	 * \param sSignalSourceID		Signal source ID
	 */
569
	inline void SetSignalSourceMachineStartMachine( const std::string& sSignalSourceID )
570 571
	{
		CVAStruct oParams;
572 573 574
		oParams[ "set" ] = "action";
		oParams[ "value" ] = "start";
		SetSignalSourceParameters( sSignalSourceID, oParams );
575
	};
Jonas Stienen's avatar
Jonas Stienen committed
576 577 578 579 580

	//! Halts the signal of a machine source
	/**
	 * \param sSignalSourceID		Signal source ID
	 */
581
	inline void SetSignalSourceMachineHaltMachine( const std::string& sSignalSourceID )
582 583
	{
		CVAStruct oParams;
584 585 586
		oParams[ "set" ] = "action";
		oParams[ "value" ] = "stop";
		SetSignalSourceParameters( sSignalSourceID, oParams );
587
	};
Jonas Stienen's avatar
Jonas Stienen committed
588 589 590 591 592 593

	//! Returns the state of a machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \return						Machine state
	 */
594
	inline std::string GetSignalSourceMachineStateStr( const std::string& sSignalSourceID ) const
595 596
	{
		CVAStruct oParams, oRet;
597 598 599 600 601
		oParams[ "get" ] = "state";
		oRet = GetSignalSourceParameters( sSignalSourceID, oParams );
		if( oRet.HasKey( "state" ) )
			if( oRet[ "state" ].IsString() )
				return oRet[ "state" ].ToString();
602 603 604 605 606
			else
				return "error";
		else
			return "unkown";
	};
Jonas Stienen's avatar
Jonas Stienen committed
607 608 609 610 611 612

	//! Sets the speed of a machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param dSpeed				Machine speed (0 .. not-too-large)
	 */
613
	inline void SetSignalSourceMachineSpeed( const std::string& sSignalSourceID, double dSpeed )
614 615
	{
		CVAStruct oParams;
616 617 618
		oParams[ "set" ] = "S";
		oParams[ "value" ] = dSpeed;
		SetSignalSourceParameters( sSignalSourceID, oParams );
619
	};
Jonas Stienen's avatar
Jonas Stienen committed
620 621 622 623 624 625

	//! Sets the speed of a machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \return						Machine speed
	 */
626
	inline double GetSignalSourceMachineSpeed( const std::string& sSignalSourceID ) const
627 628
	{
		CVAStruct oParams, oRet;
629 630 631 632 633
		oParams[ "get" ] = "speed";
		oRet = GetSignalSourceParameters( sSignalSourceID, oParams );
		if( oRet.HasKey( "speed" ) )
			if( oRet[ "speed" ].IsNumeric() )
				return double( oRet[ "speed" ] );
634 635 636

		return 1.0f;
	};
Jonas Stienen's avatar
Jonas Stienen committed
637 638 639 640 641 642

	//! Set start file sample of machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param sFilePath				Path to audio file
	 */
643
	inline void SetSignalSourceMachineStartFile( const std::string& sSignalSourceID, const std::string& sFilePath )
644 645
	{
		CVAStruct oParams;
646 647 648
		oParams[ "set" ] = "StartSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
649
	};
Jonas Stienen's avatar
Jonas Stienen committed
650 651 652 653 654 655

	//! Set idle file sample of machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param sFilePath				Path to audio file
	 */
656 657 658
	inline void SetSignalSourceMachineIdleFile( const std::string& sSignalSourceID, const std::string& sFilePath )
	{
		CVAStruct oParams;
659 660 661
		oParams[ "set" ] = "IdleSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
662
	};
Jonas Stienen's avatar
Jonas Stienen committed
663 664 665 666 667 668

	//! Set stop file sample of machine signal source
	/**
	 * \param sSignalSourceID		Signal source ID
	 * \param sFilePath				Path to audio file
	 */
669
	inline void SetSignalSourceMachineStopFile( const std::string& sSignalSourceID, const std::string& sFilePath )
670 671
	{
		CVAStruct oParams;
672 673 674
		oParams[ "set" ] = "StopSoundFilePath";
		oParams[ "value" ] = sFilePath;
		SetSignalSourceParameters( sSignalSourceID, oParams );
675
	};
676

Jonas Stienen's avatar
Jonas Stienen committed
677 678 679 680 681 682
	// 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.
683
	 *
Jonas Stienen's avatar
Jonas Stienen committed
684 685 686
	 * \param sSignalSourceID	ID of signal source
	 * \param oParams	Parameter structure
	 */
687
	virtual void SetSignalSourceParameters( const std::string& sSignalSourceID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
688 689 690 691 692

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

699 700 701 702 703 704 705 706 707 708 709 710
	//! 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
711
	virtual int AddSignalSourceSequencerPlayback( const std::string& sSignalSourceID, const int iSoundID, const int iFlags, const double dTimeCode ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
712

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

716

717
	//! Returns wheather a synchronized scene modification is in progress
718
	virtual bool GetUpdateLocked() const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
719 720 721 722 723 724 725

	//! 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.
	 */
726
	virtual void LockUpdate() = 0;
Jonas Stienen's avatar
Jonas Stienen committed
727 728 729 730 731 732 733 734 735 736

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

739

Jonas Stienen's avatar
Jonas Stienen committed
740 741 742 743
	//! 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.
744
	 *
Jonas Stienen's avatar
Jonas Stienen committed
745 746 747 748 749 750 751
	 * \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
	 */
752 753 754 755 756 757
	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
758 759 760 761 762 763 764

	//! 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.
765
	 *
Jonas Stienen's avatar
Jonas Stienen committed
766 767 768 769 770 771 772
	 * \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
	 */
773
	virtual int CreateSoundSourceExplicitRenderer( const std::string& sRendererID, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
774 775 776 777 778 779 780 781

	//! Schallquelle entfernen
	/**
	 * Diese Methode entfernt eine Schallquelle aus der Szene
	 *
	 * \return 0 falls die Schallquelle entfernt wurde,
	 *         -1 im Fehlerfall
	 */
782
	virtual int DeleteSoundSource( const int iID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
783 784 785 786 787 788 789 790

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

Jonas Stienen's avatar
Jonas Stienen committed
793 794 795 796 797 798 799
	//! Returns sound source enabled/disabled status
	/**
	  * @param[in] iSoundSourceID	Sound source identifier
	  * @return					Enabled (true) or disabled (false)
	  *
	  * @sa SetSoundSourceEnabled()
	  */
800
	virtual bool GetSoundSourceEnabled( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
801 802

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

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

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

811 812
	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
813 814 815

	//! Attach a signal source to sound source
	/**
816
	  * Let a sound source play back samples from the given signal source.
Jonas Stienen's avatar
Jonas Stienen committed
817 818 819 820 821 822 823 824
	  * An empty string removes the signal source from sound source (silence).
	  *
	  * \see RemoveSoundSourceSignalSource
	  *
	  * \param iID	Sound source identifier
	  * \param sSignalSourceID	Signal source identifier
	  *
	  */
825
	virtual void SetSoundSourceSignalSource( const int iSoundSourceID, const std::string& sSignalSourceID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
826 827 828 829 830 831 832

	//! 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
	  */
833
	inline void RemoveSoundSourceSignalSource( const int iID )
834
	{
835
		SetSoundSourceSignalSource( iID, "" );
836
	};
Jonas Stienen's avatar
Jonas Stienen committed
837 838

	//! Auralisierungsmodus einer Schallquelle zurückgeben (Bitvektor)
839
	virtual int GetSoundSourceAuralizationMode( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
840 841 842 843 844

	//! Auralisierungsmodus einer Schallquelle setzen (Bitvektor)
	/**
	 * Mit dieser Methode wird der Auralisierungsmodus für eine Schallquelle festgelegt.
	 */
845
	virtual void SetSoundSourceAuralizationMode( const int iSoundSourceID, const int iAuralizationMode ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
846 847 848 849 850 851 852 853 854

	//! 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
	  */
855
	virtual void SetSoundSourceParameters( const int iID, const CVAStruct& oParams ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
856 857 858 859

	//! 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
860
	  * sound receiver parameters without introducing new methods to the main interface.
Jonas Stienen's avatar
Jonas Stienen committed
861 862 863 864 865
	  *
	  * \param iSoundSourceID Sound source identifier
	  * \param oParams Magic struct with the parameters that are requested
	  * \return Magic struct with the parameter values requested
	  */
866
	virtual CVAStruct GetSoundSourceParameters( const int iID, const CVAStruct& oParams ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
867 868 869 870 871

	//! Returns the directivity of a sound source
	/**
	 * If the sound source is not assigned a directivity, the methods returns -1.
	 */
872
	virtual int GetSoundSourceDirectivity( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
873 874 875 876 877

	//! Sets the directivity of a sound source
	/**
	 * In order to remove an assigned directivity, you can pass -1 to the method.
	 */
878
	virtual void SetSoundSourceDirectivity( const int iSoundSourceID, const int iDirectivityID ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
879 880 881 882 883

	//! Lautstärke einer Schallquelle zurückgeben
	/**
	 * Gibt den Verstärkungsfaktor zurück (nicht Dezibel)
	 */
884
	virtual double GetSoundSourceSoundPower( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
885 886 887 888 889

	//! Lautstärke einer Schallquelle setzen
	/**
	 * Setzt die Lautstärke einer Schallquelle als Verstärkungsfaktor (nicht Dezibel).
	 */
890
	virtual void SetSoundSourceSoundPower( const int iSoundSourceID, const double dSoundPower ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
891 892 893 894 895

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

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

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

904
	virtual VAVec3 GetSoundSourcePosition( const int iID ) const = 0;
905
	virtual void SetSoundSourcePosition( const int iID, const VAVec3& v3Pos ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
906

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

910
	virtual void GetSoundSourceOrientationVU( const int iID, VAVec3& v3View, VAVec3& v3Up ) const = 0;
911
	virtual void SetSoundSourceOrientationVU( const int iID, const VAVec3& v3View, const VAVec3& v3Up ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
912

913

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

917
	//! Creates a sound receiver
Jonas Stienen's avatar
Jonas Stienen committed
918
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
919
	 * This method creates a new sound receiver (sound receiver).
920
	 *
921
	 * @param[in] sName		Name (optional)
Jonas Stienen's avatar
Jonas Stienen committed
922
	 *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
923
	 * \return ID of the new sound receiver, if the method succeeded, -1, otherwise
Jonas Stienen's avatar
Jonas Stienen committed
924
	 */
925
	virtual int CreateSoundReceiver( const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
926

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
927
	//! Creates a sound receiver explicitly for a given renderer
Jonas Stienen's avatar
Jonas Stienen committed
928
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
929 930
	 * 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
931
	 * GetRendererLister() for a list of all available renderer identifier.
932
	 *
Jonas Stienen's avatar
Jonas Stienen committed
933 934 935
	 * \param	sName			Name
	 * \param	sRendererID		Renderer identifier
	 *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
936
	 * \return ID of the new sound receiver, if the method succeeded and -1, otherwise
Jonas Stienen's avatar
Jonas Stienen committed
937
	 */
938
	virtual int CreateSoundReceiverExplicitRenderer( const std::string& sRendererID, const std::string& sName = "" ) = 0;
Jonas Stienen's avatar
Jonas Stienen committed
939 940 941 942 943 944 945 946 947

	//! 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
	 */
948
	virtual int DeleteSoundReceiver( const int iID ) = 0;
949 950

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

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
952
	//! Enables or disables a virtual sound receiver (removes the sound receiver from audio processing)
Jonas Stienen's avatar
Jonas Stienen committed
953
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
954
	  * @param[in] iSoundReceiverID	SoundReceiver identifier
Jonas Stienen's avatar
Jonas Stienen committed
955 956
	  * @param[in] bEnabled		Enable (true) or disable (false) sound source
	  *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
957
	  * @sa GetSoundReceiverEnabled()
Jonas Stienen's avatar
Jonas Stienen committed
958
	  */
959
	virtual void SetSoundReceiverEnabled( const int iID, const bool bEnabled = true ) = 0;
960

961
	//! Returns sound receiver enabled/disabled status
Jonas Stienen's avatar
Jonas Stienen committed
962
	/**
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
963
	  * @param[in] iSoundReceiverID	SoundReceiver identifier
Jonas Stienen's avatar
Jonas Stienen committed
964 965
	  * @return				Enabled (true) or disabled (false)
	  *
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
966
	  * @sa SetSoundReceiverEnabled()
Jonas Stienen's avatar
Jonas Stienen committed
967
	  */
968
	virtual bool GetSoundReceiverEnabled( const int iID ) const = 0;
969

Jonas Stienen's avatar
Jonas Stienen committed
970
	//! Name eines Hörers zurückgeben
971
	virtual std::string GetSoundReceiverName( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
972 973

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

	//! Auralisierungsmodus eines Hörers zurückgeben (Bitvektor)
977
	virtual int GetSoundReceiverAuralizationMode( const int iID ) const = 0;
Jonas Stienen's avatar
Jonas Stienen committed
978 979 980 981 982

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