itaVA.m 70.5 KB
Newer Older
1
classdef itaVA < handle
2
    %ITAVA Remote network interface to VA (Virtual Acoustics), the real-time 
3 4 5
    %auralization framework.
	%
	% Find the VA applications, documentation and examples here: http://www.virtualacoustics.org
6 7 8
    %
    %   This class realizes a remote connection to a VA real-time
    %   auralization server and implements the full VA core interface
9 10
    %   in Matlab. You can connect to to the server
    %   and control all of its features to perform real-time
11
    %   auralization, including integrated live tracking if an OptiTrack tracker is at hand.
12
    %
13
    %   See also: itaVA_example_simple, itaVA_example_tracked_sound_receiver,
14 15 16
    %   itaVA_example_generic_path_renderer, itaVA_example_random_numbers
    %
    %   Quick usage:
17 18 19 20
    %
    %   - Create an interface and connect to the server running on the
    %     same computer (localhost)
    %
21 22
    %     va = itaVA;
    %     va.connect;
23
    %
24 25
    %     If the connection is established, you can start controlling VA via the interface.
    %	  For instance create an move a sound source:
26
    %
27
    %     sourceID = va.create_sound_source( 'My Matlab virtual sound source' )
28
	%	  va.set_sound_source_position( sourceID, [ 0 0 0 ] );
29 30 31 32 33 34 35 36 37 38
    %
    %     When everything is done, do not forget to close the connection.
    %     You can call disconnect on the instance or simply clear it:
    %
    %     clear va
    %
    %
    
    properties(Hidden = true, Access = private)
        handle = int32(0); % Connection handle
39
                
40 41 42 43 44
        % Connection defaults
        DEFAULT_SERVER_PORT = 12340;
    end
    
    methods(Static)
45 46 47
        
        function [ ok ] = check_for_mex_file()
            % Checks if VAMatlab executable can be found.
48
            if ~exist( 'VAMatlab', 'file' )
49 50 51
                disp( 'Matlab binding for VA not complete (missing VAMatlab executable).' )
                
                % file dialog
52
                itaVA_setup()
53
                
54 55
                % Re-check
                ok = exist( 'VAMatlab', 'file' ) > 0;
56 57 58 59 60
            else
                ok = true;
            end
        end
        
61
        function [version] = get_version()
62 63 64 65 66 67 68 69 70
            % Return the version of the VA Matlab interface
            %
            % Parameters:
            %
            % 	None
            %
            % Return values:
            %
            % 	version  [string]  Version string
71 72 73 74 75
            
            if ~itaVA.check_for_mex_file()
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end

76
            version = VAMatlab('get_version');
77 78
        end
        
79
         function [] = set_verbose_mode(mode)
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
            % Sets the verbose level of the VA Matlab interface
            %
            % Parameters:
            %
            % 	mode  [string]   Verbose mode ('quiet'|'normal')
            %
            % Return values:
            %
            % 	None
            %
            % Remarks:
            %
            % - If you do not want any messages from the extension
            %   set the verbose mode to 'quiet'
            %
95 96 97 98 99
            
            if ~itaVA.check_for_mex_file()
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end

100
            VAMatlab('set_verbose_mode', mode);
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
        end
    end

    methods
        function this = itaVA(addressstring)
            % Initialization constructor. Initiiates a new connection.
            %
            % Parameters:
            %
            % 	addressstring  [string]   Hostname or IP address and port of the
            %                             server string (name:port), optional
            %
            % Return values:
            %
            % 	None
            %
            % Remarks:
            %
            % - You can leave the argument 'address' undefined, in order
            %   to create an clear, unconnected instance and connect to
            %   a server later using the method 'connect'
            % - Example: core = itaVA;
            %            core = itaVA('localhost:12340');
            %
            
126 127 128 129
            if ~itaVA.check_for_mex_file()
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end
        
130 131 132 133 134 135 136 137 138 139
            if (nargin > 0)
                this.connect(addressstring)
            end
        end
        
        function delete(this)
            % Destructor. Automatically disconnects an existing connection.
            this.disconnect
        end 
       
140
        function [connected] = get_connected(this)
141
            % Returns if a connection to a server is established
142
           connected = VAMatlab('get_connected', this.handle);
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182
        end
        
        function connect(this, addressstring)
            % Connects to a server
            %
            % Parameters:
            %
            % 	addressstring  [string]   Hostname or IP address and port of the
            %                             server string (name:port), optional
            %
            % Return values:
            %
            % 	None
            %
            % Remarks:
            %
            % - An error occurs if the instance is already connected
            % - Example: core.connect('localhost:12340')
            %
            if this.handle~=0
				error('Already connected. Close the existing connection first.'); 
			end 
            
			if nargin == 2
				if isempty(addressstring) 
					error('Server address must not be empty.');
				end
			else
				addressstring = 'localhost';
			end
            
            this.handle = VAMatlab('connect', addressstring);
        end
        
        function disconnect(this)
            % Disconnects from a server
            VAMatlab('disconnect', this.handle)
            this.handle = int32(0);
        end
           
183
        function [state] = get_server_state(this)
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
            % Returns the state of the connected server
            %
            % Use this function to check whether the server is
            % running fine and does not have any problems.
            %
            % Parameters:
            %
            % 	None
            %
            % Return values:
            %
            % 	state [integer-1x1] Server stat
            %
            % States:
            % 
            % - 0 = Connected, but server not configured. Failure.
            % - 1 = Connected and ready for usage.
            % - 2 = Connected, but server has failure.
            %
            if this.handle==0, error('Not connected.'); end; 
204
            state = VAMatlab('get_server_state', this.handle);
205 206
        end
        
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
		
		function shutdown_server(this)
            % Attempts to shut down the remote server
            %
            % Server shutdown may be prohibited by the server configuration.
			% Shutting donw the server from client side is meant for cases
			% when the server is called by a script to run e.g. a simulation
			% while the rendering output is recorded. The export is triggered
			% when the core is finalized (or shut down).
            %
            % Parameters:
            %
            % 	None
            %
            % Return values:
            %
            % 	None
            %
			VAMatlab( 'call_module', this.handle, 'VACore', struct( 'shutdown', true ) );
        end
        
228
        function connect_tracker( this, remote_ip, local_ip )
229 230
            % Connects to a local NatNet tracking server
            % 
231 232
            % The server will update a virtual sound receiver for real-time 
            % sound synthesis and the real world sound receiver position for
233 234 235
            % those sound reproductions that need this information, like  
            % Crosstalk-Cancellation.
            %
236
            % See also set_tracked_sound_receiver.
237 238 239 240 241 242 243 244 245 246 247 248
            %
            % Parameters (optional):
            %
            % 	remote_ip [char]	Remote ip address
            % 	local_ip [char]		Local ip address
            %

			if( nargin == 1 )
				remote_ip = '127.0.0.1';
				local_ip = '127.0.0.1';
			end

249
            VAMatlab( 'connect_tracker', this.handle, remote_ip, local_ip );
250 251
        end
        
252
        function [connected] = get_tracker_connected( this )
253
            % Returns true, if tracker is connected
254
            connected = VAMatlab( 'get_tracker_connected', this.handle );
255 256
        end
        
257
        function disconnect_tracker( this )
258
            % Disconnects from the NatNet tracking server
259
            VAMatlab( 'disconnect_tracker', this.handle )
260 261
        end
        
262
		% -- Tracked sound receiver -- %
263
		
264 265
        function set_tracked_sound_receiver( this, sound_receiver_id )
            % Connects a VA sound receiver with the tracked sound receiver rigid body
266 267 268
            %
            % Parameters:
            %
269
            % 	sound_receiver_id  [integer-1x1]   VA sound receiver id
270
            %
271
            VAMatlab( 'set_tracked_sound_receiver', this.handle, sound_receiver_id );
272
        end
273
        
274 275 276
        function set_tracked_sound_receiver_head_rigid_body_index( this, index )
            % Sets the index of the rigid body to be tracked for sound receiver (default is 1)
            VAMatlab( 'set_tracked_sound_receiver_head_rigid_body_index', this.handle, index )
277 278
        end
        
279 280 281 282 283 284 285
        function set_tracked_sound_receiver_torso_rigid_body_index( this, index )
            % Sets the index of the rigid body to be tracked for sound receiver's absolute torso orientation (default is 1)
            VAMatlab( 'set_tracked_sound_receiver_torso_rigid_body_index', this.handle, index )
        end
        
        function set_tracked_sound_receiver_head_rigid_body_translation( this, translation )
            % Sets the pivot point translation for the tracked sound receiver rigid body
286 287 288 289 290
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
291
            VAMatlab( 'set_tracked_sound_receiver_head_rigid_body_translation', this.handle, translation )
292 293
        end
        
294 295
        function set_tracked_sound_receiver_head_rigid_body_rotation( this, rotation )
            % Sets the rotation of orientation for the tracked sound receiver rigid body
296 297 298 299 300 301 302
			%
			% Given rotation has to be a Matlab quaternion type (order: w(real), i, j, k)
			%
			% Parameters:
			%
			%	rotation [quaternion]	Rotation of rigid body
			%
303
            VAMatlab( 'set_tracked_sound_receiver_head_rigid_body_rotation', this.handle, rotation )
304 305
        end
		
306
		% -- Tracked real-world sound receiver -- %
307
		
308 309
        function set_tracked_real_world_sound_receiver( this, sound_receiver_id )
            % Connects a VA real-world sound receiver with the tracked real-world rigid body
310 311 312
            %
            % Parameters:
            %
313
            % 	sound_receiver_id  [integer-1x1]   VA real-world sound receiver id
314
            %
315 316 317 318 319
            VAMatlab( 'set_tracked_real_world_sound_receiver', this.handle, sound_receiver_id );
        end
		
        function set_tracked_real_world_sound_receiver_head_rigid_body_index( this, index )
            % Sets the index of the rigid body to be tracked for real-world sound receiver (default is 1)
320
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_index', this.handle, index )
321 322
        end
		
323 324 325
        function set_tracked_real_world_sound_receiver_torso_rigid_body_index( this, index )
            % Sets the index of the rigid body to be tracked for real-world sound receiver' torso (default is 1)
            VAMatlab( 'set_tracked_real_world_sound_receiver_torso_rigid_body_index', this.handle, index )
326 327
        end
        
328
        function set_tracked_real_world_sound_receiver_head_rb_trans( this, translation )
329
            % Sets the pivot point translation for the tracked real-world sound receiver rigid body
330 331 332 333 334
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
335
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_translation', this.handle, translation )
336
        end
337
        
338
        function set_tracked_real_world_sound_receiver_head_rb_rotation( this, rotation )
339
            % Sets the rotation of orientation for the tracked real-world sound receiver rigid body
340 341 342 343 344 345 346
			%
			% Given rotation has to be a Matlab quaternion type (order: w(real), i, j, k)
			%
			% Parameters:
			%
			%	rotation [quaternion]	Rotation of rigid body
			%
347
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_rotation', this.handle, rotation )
348 349
        end
		        
350 351
		% -- Tracked source -- %
		
352
        function set_tracked_sound_source( this, source_id )
353 354 355 356
            % Connects a VA source with the tracked source rigid body
            %
            % Parameters:
            %
357
            % 	source_id  [integer-1x1]   VA source id
358
            %
359
            VAMatlab( 'set_tracked_sound_source', this.handle, source_id );
360
        end
361
		
362
        function set_tracked_sound_source_rigid_body_index( this, index )
363
            % Sets the index of the rigid body to be tracked for source (default is 1)
364
            VAMatlab( 'set_tracked_sound_source_rigid_body_index', this.handle, index )
365 366
        end
        
367
        function set_tracked_sound_source_rigid_body_translation( this, translation )
368 369 370 371 372 373
            % Sets the pivot point translation for the tracked source rigid body
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
374
            VAMatlab( 'set_tracked_sound_source_rigid_body_translation', this.handle, translation )
375 376
        end
        
377
        function set_tracked_sound_source_rigid_body_rotation( this, rotation )
378 379 380 381 382 383 384 385
            % Sets the rotation of orientation for the tracked source rigid body
			%
			% Given rotation has to be a Matlab quaternion type (order: w(real), i, j, k)
			%
			% Parameters:
			%
			%	rotation [quaternion]	Rotation of rigid body
			%
386 387 388 389 390 391 392
            VAMatlab( 'set_tracked_sound_source_rigid_body_rotation', this.handle, rotation )
        end
		
        function get_tracker_info( this )
            % Returns the tracker configuration state
			%
            VAMatlab( 'get_tracker_info', this.handle )
393 394
        end
		
395 396 397 398 399 400 401 402 403
		%% --= Deprecated methods =--
		
        function id = create_directivity( this, filepath )
            % Creates a directivity from file [DEPRECATED]
			
			warning( 'This method is marked as deprecated and will be removed in a future version. Please use ''create_directivity_from_file'' instead.' )
            id = this.create_directivity_from_file( filepath );
        end
		
404 405 406
        
        %% --= Functions =--
        
407
        	function [valid] = add_search_path(this, path)
408 409 410 411 412 413 414 415 416 417 418 419 420
		% adds a search path at core side
		%
		% Parameters:
		%
		% 	path [string] Relative or absolute path
		%
		% Return values:
		%
		% 	valid [logical scalar] True, if path at core side valid
		%

		if this.handle==0, error('Not connected.'); end;

421
		[valid] = VAMatlab('add_search_path', this.handle, path);
422 423
	end

424 425
	function [ret] = call_module(this, module,mstruct)
		% Calls an internal module of the VA server
426 427 428
		%
		% Parameters:
		%
429 430
		% 	module [string] Module name
		% 	mstruct [struct] Matlab structure with key-value content
431 432 433
		%
		% Return values:
		%
434
		% 	ret [struct-1x1] Struct containing the return values
435 436 437 438
		%

		if this.handle==0, error('Not connected.'); end;

439
		[ret] = VAMatlab('call_module', this.handle, module,mstruct);
440 441
	end

442 443
	function [material_id] = create_acoustic_material_from_file(this, file_path,material_name)
		% Create acoustic material
444 445 446
		%
		% Parameters:
		%
447 448
		% 	file_path [string] Material file path
		% 	material_name [string] Material name (optional, default: '')
449 450 451
		%
		% Return values:
		%
452
		% 	material_id [double-1x1] Material identifier
453 454 455 456
		%

		if this.handle==0, error('Not connected.'); end;

457 458
		if ~exist('material_name','var'), material_name = ''; end
		[material_id] = VAMatlab('create_acoustic_material_from_file', this.handle, file_path,material_name);
459 460
	end

461
	function [directivityID] = create_directivity_from_file(this, filename,name)
462
		% Loads a directivity from a file
463 464 465 466 467 468 469 470
		%
		% Parameters:
		%
		% 	filename [string] Filename
		% 	name [string] Displayed name (optional, default: '')
		%
		% Return values:
		%
471
		% 	directivityID [integer-1x1] Directivity ID
472 473 474 475 476
		%

		if this.handle==0, error('Not connected.'); end;

		if ~exist('name','var'), name = ''; end
477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496
		[directivityID] = VAMatlab('create_directivity_from_file', this.handle, filename,name);
	end

	function [directivityID] = create_directivity_from_parameters(this, directivity_args,name)
		% Creates a directivity based on given parameters
		%
		% Parameters:
		%
		% 	directivity_args [struct] Directivity arguments
		% 	name [string] Displayed name (optional, default: '')
		%
		% Return values:
		%
		% 	directivityID [integer-1x1] Directivity ID
		%

		if this.handle==0, error('Not connected.'); end;

		if ~exist('name','var'), name = ''; end
		[directivityID] = VAMatlab('create_directivity_from_parameters', this.handle, directivity_args,name);
497 498
	end

499 500
	function [geo_mesh_id] = create_geometry_mesh_from_file(this, file_path,geo_mesh_name)
		% Create geometry mesh from file
501 502 503
		%
		% Parameters:
		%
504 505
		% 	file_path [string] Geometry mesh file path
		% 	geo_mesh_name [string] Geometry mesh name (optional, default: '')
506 507 508
		%
		% Return values:
		%
509
		% 	geo_mesh_id [double-1x1] Geometry mesh identifier
510 511 512 513
		%

		if this.handle==0, error('Not connected.'); end;

514 515
		if ~exist('geo_mesh_name','var'), geo_mesh_name = ''; end
		[geo_mesh_id] = VAMatlab('create_geometry_mesh_from_file', this.handle, file_path,geo_mesh_name);
516 517
	end

518 519
	function [signalSourceID] = create_signal_source_buffer_from_file(this, filename,name)
		% Creates a signal source which plays an audiofile
520 521 522
		%
		% Parameters:
		%
523
		% 	filename [string] Filename
524 525 526 527
		% 	name [string] Displayed name (optional, default: '')
		%
		% Return values:
		%
528
		% 	signalSourceID [string] Signal source ID
529 530 531 532 533
		%

		if this.handle==0, error('Not connected.'); end;

		if ~exist('name','var'), name = ''; end
534
		[signalSourceID] = VAMatlab('create_signal_source_buffer_from_file', this.handle, filename,name);
535 536
	end

537 538
	function [signalSourceID] = create_signal_source_buffer_from_parameters(this, params,name)
		% Creates an buffer signal source
539 540 541
		%
		% Parameters:
		%
542
		% 	params [struct] Parameters
543 544 545 546 547 548 549 550 551 552
		% 	name [string] Displayed name (optional, default: '')
		%
		% Return values:
		%
		% 	signalSourceID [string] Signal source ID
		%

		if this.handle==0, error('Not connected.'); end;

		if ~exist('name','var'), name = ''; end
553
		[signalSourceID] = VAMatlab('create_signal_source_buffer_from_parameters', this.handle, params,name);
554 555
	end

556 557
	function [signalSourceID] = create_signal_source_engine(this, params,name)
		% Creates an engine signal source
558 559 560
		%
		% Parameters:
		%
561
		% 	params [struct] Parameters
562 563 564 565 566 567 568 569 570 571
		% 	name [string] Displayed name (optional, default: '')
		%
		% Return values:
		%
		% 	signalSourceID [string] Signal source ID
		%

		if this.handle==0, error('Not connected.'); end;

		if ~exist('name','var'), name = ''; end
572
		[signalSourceID] = VAMatlab('create_signal_source_engine', this.handle, params,name);
573 574
	end

575 576
	function [signalSourceID] = create_signal_source_network_stream(this, address,port,name)
		% Creates a signal source which receives audio samples via network
577 578 579
		%
		% Parameters:
		%
580 581
		% 	address [string] Hostname or IP address of the audio streaming server
		% 	port [integer-1x1] Server port
582 583 584 585
		% 	name [string] Displayed name (optional, default: '')
		%
		% Return values:
		%
586
		% 	signalSourceID [string] Signal source ID
587 588 589 590 591
		%

		if this.handle==0, error('Not connected.'); end;

		if ~exist('name','var'), name = ''; end
592
		[signalSourceID] = VAMatlab('create_signal_source_network_stream', this.handle, address,port,name);
593 594
	end

595 596
	function [signalSourceID] = create_signal_source_sequencer(this, name)
		% Creates a sequencer signal source
597 598 599
		%
		% Parameters:
		%
600
		% 	name [string] Displayed name (optional, default: '')
601 602 603
		%
		% Return values:
		%
604
		% 	signalSourceID [string] Signal source ID
605 606 607 608
		%

		if this.handle==0, error('Not connected.'); end;

609 610
		if ~exist('name','var'), name = ''; end
		[signalSourceID] = VAMatlab('create_signal_source_sequencer', this.handle, name);
611 612
	end

613
	function [signalSourceID] = create_signal_source_text_to_speech(this, name)
614 615 616 617 618 619 620 621 622 623 624 625 626 627
		% Creates a text to speech signal
		%
		% Parameters:
		%
		% 	name [string] Displayed name (optional, default: '')
		%
		% Return values:
		%
		% 	signalSourceID [string] Signal source ID
		%

		if this.handle==0, error('Not connected.'); end;

		if ~exist('name','var'), name = ''; end
628
		[signalSourceID] = VAMatlab('create_signal_source_text_to_speech', this.handle, name);
629 630
	end

631 632
	function [id] = create_sound_receiver(this, name)
		% Creates a sound receiver
633 634 635
		%
		% Parameters:
		%
636
		% 	name [string] Displayed name (optional, default: '')
637 638 639
		%
		% Return values:
		%
640
		% 	id [integer-1x1] Sound receiver ID
641 642 643 644
		%

		if this.handle==0, error('Not connected.'); end;

645 646
		if ~exist('name','var'), name = ''; end
		[id] = VAMatlab('create_sound_receiver', this.handle, name);
647 648
	end

649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666
	function [id] = create_sound_receiver_explicit_renderer(this, renderer,name)
		% Creates a sound receiver explicitly for a certain renderer
		%
		% Parameters:
		%
		% 	renderer [string] Renderer identifier
		% 	name [string] Name
		%
		% Return values:
		%
		% 	id [integer-1x1] Sound receiver ID
		%

		if this.handle==0, error('Not connected.'); end;

		[id] = VAMatlab('create_sound_receiver_explicit_renderer', this.handle, renderer,name);
	end

667 668
	function [id] = create_sound_source(this, name)
		% Creates a sound source
669 670 671
		%
		% Parameters:
		%
672
		% 	name [string] Displayed name (optional, default: '')
673 674 675
		%
		% Return values:
		%
676
		% 	id [integer-1x1] Sound source ID
677 678 679 680
		%

		if this.handle==0, error('Not connected.'); end;

681 682
		if ~exist('name','var'), name = ''; end
		[id] = VAMatlab('create_sound_source', this.handle, name);
683 684
	end

685 686
	function [id] = create_sound_source_explicit_renderer(this, renderer,name)
		% Creates a sound source explicitly for a certain renderer
687 688 689
		%
		% Parameters:
		%
690 691
		% 	renderer [string] Renderer identifier
		% 	name [string] Name
692 693 694
		%
		% Return values:
		%
695
		% 	id [integer-1x1] Sound source ID
696 697 698 699
		%

		if this.handle==0, error('Not connected.'); end;

700
		[id] = VAMatlab('create_sound_source_explicit_renderer', this.handle, renderer,name);
701 702
	end

703 704
	function [success_flag] = delete_acoustic_material(this, material_id)
		% Delete acoustic material
705 706 707
		%
		% Parameters:
		%
708
		% 	material_id [double-1x1] Material identifier
709 710 711
		%
		% Return values:
		%
712
		% 	success_flag [logical-1x1] Removal success
713 714 715 716
		%

		if this.handle==0, error('Not connected.'); end;

717
		[success_flag] = VAMatlab('delete_acoustic_material', this.handle, material_id);
718 719
	end

720
	function [result] = delete_directivity(this, directivityID)
721 722 723 724 725 726 727 728 729 730 731 732 733
		% Frees a directivity and releases its memory
		%
		% Parameters:
		%
		% 	directivityID [integer-1x1] Directivity ID
		%
		% Return values:
		%
		% 	result [logical-1x1] Directivity freed?
		%

		if this.handle==0, error('Not connected.'); end;

734
		[result] = VAMatlab('delete_directivity', this.handle, directivityID);
735 736
	end

737 738
	function [success_flag] = delete_geometry_mesh(this, geo_mesh_id)
		% Delete geometry mesh
739 740 741
		%
		% Parameters:
		%
742
		% 	geo_mesh_id [double-1x1] Geometry mesh identifier
743 744 745
		%
		% Return values:
		%
746
		% 	success_flag [logical-1x1] Removal success
747 748 749 750
		%

		if this.handle==0, error('Not connected.'); end;

751
		[success_flag] = VAMatlab('delete_geometry_mesh', this.handle, geo_mesh_id);
752 753
	end

754 755
	function [result] = delete_signal_source(this, signalSourceID)
		% Deletes a signal source
756 757 758
		%
		% Parameters:
		%
759
		% 	signalSourceID [string] Signal source ID
760 761 762
		%
		% Return values:
		%
763
		% 	result [logical-1x1] Signal source deleted?
764 765 766 767
		%

		if this.handle==0, error('Not connected.'); end;

768
		[result] = VAMatlab('delete_signal_source', this.handle, signalSourceID);
769 770
	end

771 772
	function [] = delete_sound_receiver(this, soundreceiverID)
		% Deletes a sound receiver from the scene
773 774 775
		%
		% Parameters:
		%
776
		% 	soundreceiverID [integer-1x1] Sound receiver ID
777 778 779
		%
		% Return values:
		%
780
		% 	None
781 782 783 784
		%

		if this.handle==0, error('Not connected.'); end;

785
		VAMatlab('delete_sound_receiver', this.handle, soundreceiverID);
786 787
	end

788 789
	function [] = delete_sound_source(this, soundSourceID)
		% Deletes an existing sound source in the scene
790 791 792
		%
		% Parameters:
		%
793
		% 	soundSourceID [integer-1x1] Sound source ID
794 795 796
		%
		% Return values:
		%
797
		% 	None
798 799 800 801
		%

		if this.handle==0, error('Not connected.'); end;

802
		VAMatlab('delete_sound_source', this.handle, soundSourceID);
803 804
	end

805 806
	function [params] = get_acoustic_magerial_parameters(this, material_id,args)
		% Acoustic material parameter getter
807 808 809
		%
		% Parameters:
		%
810 811
		% 	material_id [integer-1x1] Acoustic material identifier
		% 	args [mstruct] Requested parameters
812 813 814
		%
		% Return values:
		%
815
		% 	params [mstruct] Parameters
816 817 818 819
		%

		if this.handle==0, error('Not connected.'); end;

820
		[params] = VAMatlab('get_acoustic_magerial_parameters', this.handle, material_id,args);
821 822
	end

823 824
	function [soundreceiverID] = get_active_sound_receiver(this)
		% Returns the active sound receiver
825 826 827 828 829 830 831
		%
		% Parameters:
		%
		% 	None
		%
		% Return values:
		%
832
		% 	soundreceiverID [integer-1x1] Sound receiver ID
833 834 835 836
		%

		if this.handle==0, error('Not connected.'); end;

837
		[soundreceiverID] = VAMatlab('get_active_sound_receiver', this.handle);
838 839
	end

840 841
	function [clk] = get_core_clock(this)
		% Returns the current core time
842 843 844
		%
		% Parameters:
		%
845
		% 	None
846 847 848
		%
		% Return values:
		%
849
		% 	clk [double-1x1] Core clock time (unit: seconds)
850 851 852 853
		%

		if this.handle==0, error('Not connected.'); end;

854
		[clk] = VAMatlab('get_core_clock', this.handle);
855 856
	end

857 858
	function [info] = get_directivity_info(this, directivityID)
		% Returns information on a loaded directivity
859 860 861
		%
		% Parameters:
		%
862
		% 	directivityID [integer-1x1] Directivity ID
863 864 865
		%
		% Return values:
		%
866
		% 	info [struct-1x1] Information struct (name, filename, resolution, etc.)
867 868 869 870
		%

		if this.handle==0, error('Not connected.'); end;

871
		[info] = VAMatlab('get_directivity_info', this.handle, directivityID);
872 873
	end

874 875
	function [info] = get_directivity_infos(this)
		% Returns information on all loaded directivities
876 877 878 879 880 881 882
		%
		% Parameters:
		%
		% 	None
		%
		% Return values:
		%
883
		% 	info [cell-array of struct-1x1] Information structs (name, filename, resolution, etc.)
884 885 886 887
		%

		if this.handle==0, error('Not connected.'); end;

888
		[info] = VAMatlab('get_directivity_infos', this.handle);
889 890
	end

891 892
	function [result] = get_geometry_mesh_enabled(this, geo_mesh_id)
		% Geometry mesh enabled getter
893 894 895
		%
		% Parameters:
		%
896
		% 	geo_mesh_id [integer-1x1] Geometry mesh identifier
897 898 899
		%
		% Return values:
		%
900
		% 	result [logical-1x1] Enabled flag
901 902 903 904
		%

		if this.handle==0, error('Not connected.'); end;

905
		[result] = VAMatlab('get_geometry_mesh_enabled', this.handle, geo_mesh_id);
906 907
	end

908 909
	function [params] = get_geometry_mesh_parameters(this, geo_mesh_id,args)
		% Geometry mesh parameter getter
910 911 912
		%
		% Parameters:
		%
913 914
		% 	geo_mesh_id [integer-1x1] Geometry mesh identifier
		% 	args [mstruct] Requested parameters
915 916 917
		%
		% Return values:
		%
918
		% 	params [mstruct] Parameters
919 920 921 922
		%

		if this.handle==0, error('Not connected.'); end;

923
		[params] = VAMatlab('get_geometry_mesh_parameters', this.handle, geo_mesh_id,args);
924 925
	end

926 927
	function [auralizationMode] = get_global_auralization_mode(this)
		% Returns the global auralization mode
928 929 930 931 932 933 934
		%
		% Parameters:
		%
		% 	None
		%
		% Return values:
		%
935
		% 	auralizationMode [string] Auralization mode
936 937 938 939
		%

		if this.handle==0, error('Not connected.'); end;

940
		[auralizationMode] = VAMatlab('get_global_auralization_mode', this.handle);
941 942
	end

943 944
	function [shift_speed] = get_homogeneous_medium_relative_humidity(this)
		% Get homogeneous medium relative humidity
945 946 947
		%
		% Parameters:
		%
948
		% 	None
949 950 951
		%
		% Return values:
		%
952
		% 	shift_speed [double-1x1] Relative humidity [Percent]
953 954 955 956
		%

		if this.handle==0, error('Not connected.'); end;

957
		[shift_speed] = VAMatlab('get_homogeneous_medium_relative_humidity', this.handle);
958 959
	end

960 961
	function [params] = get_homogeneous_medium_shift_parameters(this, args)
		% Returns homogeneous medium parameters
962 963 964
		%
		% Parameters:
		%
965
		% 	args [mstruct] Requested parameters
966 967 968
		%
		% Return values:
		%
969
		% 	params [mstruct] Parameters
970 971 972 973
		%

		if this.handle==0, error('Not connected.'); end;

974
		[params] = VAMatlab('get_homogeneous_medium_shift_parameters', this.handle, args);
975 976
	end

977 978
	function [shift_speed] = get_homogeneous_medium_shift_speed(this)
		% Get homogeneous medium shift speed
979 980 981 982 983 984 985
		%
		% Parameters:
		%
		% 	None
		%
		% Return values:
		%
986
		% 	shift_speed [double-3x1] Shift speed vector [m/s]
987 988 989 990
		%

		if this.handle==0, error('Not connected.'); end;

991
		[shift_speed] = VAMatlab('get_homogeneous_medium_shift_speed', this.handle);
992 993
	end

994 995
	function [sound_speed] = get_homogeneous_medium_sound_speed(this)
		% Get homogeneous medium sound speed
996 997 998
		%
		% Parameters:
		%
999
		% 	None
1000 1001 1002
		%
		% Return values:
		%
1003
		% 	sound_speed [double-1x1] Sound speed [m/s]
1004 1005 1006 1007
		%

		if this.handle==0, error('Not connected.'); end;

1008
		[sound_speed] = VAMatlab('get_homogeneous_medium_sound_speed', this.handle);
1009 1010
	end

1011 1012
	function [static_pressure] = get_homogeneous_medium_static_pressure(this)
		% Get homogeneous medium static pressure
1013 1014 1015
		%
		% Parameters:
		%
1016
		% 	None
1017 1018 1019
		%
		% Return values:
		%
1020
		% 	static_pressure [double-1x1] Static pressure [Pa]
1021 1022 1023 1024
		%

		if this.handle==0, error('Not connected.'); end;

1025
		[static_pressure] = VAMatlab('get_homogeneous_medium_static_pressure', this.handle);
1026 1027
	end

1028 1029
	function [temperature] = get_homogeneous_medium_temperature(this)
		% Get homogeneous medium temperature
1030 1031 1032
		%
		% Parameters:
		%
1033
		% 	None
1034 1035 1036
		%
		% Return values:
		%
1037
		% 	temperature [double-1x1] Temperature [degree Celsius]
1038 1039 1040 1041
		%

		if this.handle==0, error('Not connected.'); end;

1042
		[temperature] = VAMatlab('get_homogeneous_medium_temperature', this.handle);
1043 1044
	end

1045 1046
	function [gain] = get_input_gain(this)
		% Returns the gain the audio device input channels
1047 1048 1049
		%
		% Parameters:
		%
1050
		% 	None
1051 1052 1053
		%
		% Return values:
		%
1054
		% 	gain [double-1x1] Input gain (amplification factor >=0)
1055 1056 1057 1058
		%

		if this.handle==0, error('Not connected.'); end;

1059
		[gain] = VAMatlab('get_input_gain', this.handle);
1060 1061
	end

1062 1063
	function [result] = get_input_muted(this)
		% Returns if the audio device inputs are muted
1064 1065 1066
		%
		% Parameters:
		%
1067
		% 	None
1068 1069 1070
		%
		% Return values:
		%
1071
		% 	result [logical-1x1] Inputs muted?
1072 1073 1074 1075
		%

		if this.handle==0, error('Not connected.'); end;

1076
		[result] = VAMatlab('get_input_muted', this.handle);
1077 1078
	end

1079 1080
	function [modules] = get_modules(this)
		% Enumerates internal modules of the VA server
1081 1082 1083
		%
		% Parameters:
		%
1084
		% 	None
1085 1086 1087
		%
		% Return values:
		%
1088
		% 	modules [cell-array of struct-1x1] Module informations (names, descriptions, etc.)
1089 1090 1091 1092
		%

		if this.handle==0, error('Not connected.'); end;

1093
		[modules] = VAMatlab('get_modules', this.handle);
1094 1095
	end

1096 1097
	function [gain] = get_output_gain(this)
		% Returns the global output gain
1098 1099 1100
		%
		% Parameters:
		%
1101
		% 	None
1102 1103 1104
		%
		% Return values:
		%
1105
		% 	gain [double-1x1] Output gain (amplification factor >=0)
1106 1107 1108 1109
		%

		if this.handle==0, error('Not connected.'); end;

1110
		[gain] = VAMatlab('get_output_gain', this.handle);
1111 1112
	end

1113 1114
	function [result] = get_output_muted(this)
		% Returns if the global output is muted
1115 1116 1117
		%
		% Parameters:
		%
1118
		% 	None
1119 1120 1121
		%
		% Return values:
		%
1122
		% 	result [logical-1x1] Output muted?
1123 1124 1125 1126
		%

		if this.handle==0, error('Not connected.'); end;

1127
		[result] = VAMatlab('get_output_muted', this.handle);
1128 1129
	end

1130 1131
	function [renderers] = get_rendering_modules(this, bFilterEnabled)
		% Get list of rendering modules
1132 1133 1134
		%
		% Parameters:
		%
1135
		% 	bFilterEnabled [boolean-1x1] Filter activated (true) (optional, default: 1)
1136 1137 1138
		%
		% Return values:
		%
1139
		% 	renderers [cell-array of struct-1x1] Renderer infos (names, descriptions, etc.)
1140 1141 1142 1143
		%

		if this.handle==0, error('Not connected.'); end;

1144 1145
		if ~exist('bFilterEnabled','var'), bFilterEnabled = 1; end
		[renderers] = VAMatlab('get_rendering_modules', this.handle, bFilterEnabled);
1146 1147
	end

1148 1149
	function [auralization_mode] = get_rendering_module_auralization_mode(this, sModuleID)
		% Returns the current rendering module parameters
1150 1151 1152
		%
		% Parameters:
		%
1153
		% 	sModuleID [string] Module identifier
1154 1155 1156
		%
		% Return values:
		%
1157
		% 	auralization_mode [string] Auralization mode as string
1158 1159 1160 1161
		%

		if this.handle==0, error('Not connected.'); end;

1162
		[auralization_mode] = VAMatlab('get_rendering_module_auralization_mode', this.handle, sModuleID);
1163 1164
	end

1165 1166
	function [dGain] = get_rendering_module_gain(this, sModuleID)
		% Get rendering module output gain
1167 1168 1169
		%
		% Parameters:
		%
1170
		% 	sModuleID [string] Module identifier
1171 1172 1173
		%
		% Return values:
		%
1174
		% 	dGain [double-1x1] Gain (scalar)
1175 1176 1177 1178
		%

		if this.handle==0, error('Not connected.'); end;

1179
		[dGain] = VAMatlab('get_rendering_module_gain', this.handle, sModuleID);
1180 1181
	end

1182 1183
	function [bMuted] = get_rendering_module_muted(this, sModuleID)
		% Is reproduction module muted?
1184 1185 1186
		%
		% Parameters:
		%
1187
		% 	sModuleID [string] Module identifier
1188 1189 1190
		%
		% Return values:
		%
1191
		% 	bMuted [logical-1x1] true if muted, false if unmuted
1192 1193 1194 1195
		%

		if this.handle==0, error('Not connected.'); end;

1196
		[bMuted] = VAMatlab('get_rendering_module_muted', this.handle, sModuleID);
1197 1198
	end

1199 1200
	function [params] = get_rendering_module_parameters(this, sModuleID,args)
		% Returns the current rendering module parameters
1201 1202 1203
		%
		% Parameters:
		%
1204 1205
		% 	sModuleID [string] Module identifier
		% 	args [mstruct] Requested parameters
1206 1207 1208
		%
		% Return values:
		%
1209
		% 	params [mstruct] Parameters
1210 1211 1212 1213
		%

		if this.handle==0, error('Not connected.'); end;

1214
		[params] = VAMatlab('get_rendering_module_parameters', this.handle, sModuleID,args);
1215 1216
	end

1217 1218
	function [reproductionmodules] = get_reproduction_modules(this, bFilterEnabled)
		% Get list of rendering modules
1219 1220 1221
		%
		% Parameters:
		%
1222
		% 	bFilterEnabled [boolean-1x1] Filter activated (true) (optional, default: 1)
1223 1224 1225
		%
		% Return values:
		%
1226
		% 	reproductionmodules [cell-array of struct-1x1] Reproduction module infos (names, descriptions, etc.)
1227 1228 1229 1230
		%

		if this.handle==0, error('Not connected.'); end;

1231 1232
		if ~exist('bFilterEnabled','var'), bFilterEnabled = 1; end
		[reproductionmodules] = VAMatlab('get_reproduction_modules', this.handle, bFilterEnabled);
1233 1234
	end

1235 1236
	function [dGain] = get_reproduction_module_gain(this, sModuleID)
		% Returns the reproduction module output gain
1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248
		%
		% Parameters:
		%
		% 	sModuleID [string] Module identifier
		%
		% Return values:
		%
		% 	dGain [double-1x1] Gain (scalar)
		%

		if this.handle==0, error('Not connected.'); end;

1249
		[dGain] = VAMatlab('get_reproduction_module_gain', this.handle, sModuleID);
1250 1251
	end

1252 1253
	function [bMuted] = get_reproduction_module_muted(this, sModuleID)
		% Is reproduction module muted?
1254 1255 1256
		%
		% Parameters:
		%
1257
		% 	sModuleID [string] Module identifier
1258 1259 1260
		%
		% Return values:
		%
1261
		% 	bMuted [logical-1x1] true if muted, false if unmuted
1262 1263 1264 1265
		%

		if this.handle==0, error('Not connected.'); end;

1266
		[bMuted] = VAMatlab('get_reproduction_module_muted', this.handle, sModuleID);
1267 1268
	end

1269 1270
	function [params] = get_reproduction_module_parameters(this, sModuleID,args)
		% Returns the current reproduction module parameters
1271 1272 1273 1274
		%
		% Parameters:
		%
		% 	sModuleID [string] Module identifier
1275
		% 	args [mstruct] Requested parameters
1276 1277 1278
		%
		% Return values:
		%
1279
		% 	params [mstruct] Parameters
1280 1281 1282 1283
		%

		if this.handle==0, error('Not connected.'); end;

1284
		[params] = VAMatlab('get_reproduction_module_parameters', this.handle, sModuleID,args);
1285 1286
	end

1287 1288
	function [addr] = get_server_address(this)
		% Returns for an opened connection the server it is connected to
1289 1290 1291
		%
		% Parameters:
		%
1292
		% 	None
1293 1294 1295
		%
		% Return values:
		%
1296
		% 	addr [string] Server address
1297 1298 1299 1300
		%

		if this.handle==0, error('Not connected.'); end;

1301
		[addr] = VAMatlab('get_server_address', this.handle);
1302 1303
	end

1304 1305
	function [isLooping] = get_signal_source_buffer_looping(this, signalSourceID)
		% Returns the playback state of an audiofile signal source. Available modes: PLAYING, STOPPED, PAUSED
1306 1307 1308
		%
		% Parameters:
		%
1309
		% 	signalSourceID [string] Signal source ID
1310 1311 1312
		%
		% Return values:
		%
1313
		% 	isLooping [logical-1x1] Looping enabled/disabled
1314 1315 1316 1317
		%

		if this.handle==0, error('Not connected.'); end;

1318
		[isLooping] = VAMatlab('get_signal_source_buffer_looping', this.handle, signalSourceID);
1319 1320
	end

1321 1322
	function [playState] = get_signal_source_buffer_playback_state(this, signalSourceID)
		% Returns the playback state of an audiofile signal source. Available modes: PLAYING, STOPPED, PAUSED
1323 1324 1325
		%
		% Parameters:
		%
1326
		% 	signalSourceID [string] Signal source ID
1327 1328 1329
		%
		% Return values:
		%
1330
		% 	playState [string] Playback state
1331 1332 1333 1334
		%

		if this.handle==0, error('Not connected.'); end;

1335
		[playState] = VAMatlab('get_signal_source_buffer_playback_state', this.handle, signalSourceID);
1336 1337
	end

1338
	function [info] = get_signal_source_info(this, signalSourceID)
1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351
		% Returns information on signal source
		%
		% Parameters:
		%
		% 	signalSourceID [string] Signal source ID
		%
		% Return values:
		%
		% 	info [struct-1x1] Information structs (id, name, type, etc.)
		%

		if this.handle==0, error('Not connected.'); end;

1352
		[info] = VAMatlab('get_signal_source_info', this.handle, signalSourceID);
1353 1354
	end

1355
	function [info] = get_signal_source_infos(this)
1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368
		% Returns information on all existing signal sources
		%
		% Parameters:
		%
		% 	None
		%
		% Return values:
		%
		% 	info [cell-array of struct-1x1] Information structs (id, name, type, etc.)
		%

		if this.handle==0, error('Not connected.'); end;

1369
		[info] = VAMatlab('get_signal_source_infos', this.handle);
1370 1371
	end

1372
	function [params] = get_signal_source_parameters(this, ID,args)
1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386
		% Returns the current signal source parameters
		%
		% Parameters:
		%
		% 	ID [string] Signal source identifier
		% 	args [mstruct] Requested parameters
		%
		% Return values:
		%
		% 	params [mstruct] Parameters
		%

		if this.handle==0, error('Not connected.'); end;

1387
		[params] = VAMatlab('get_signal_source_parameters', this.handle, ID,args);
1388 1389
	end

1390 1391
	function [ids] = get_sound_portal_ids(this)
		% Return the IDs of all portal in the scene
1392 1393 1394
		%
		% Parameters:
		%
1395
		% 	None
1396 1397 1398
		%
		% Return values:
		%
1399
		% 	ids [integer-1xN] Vector containing the IDs
1400 1401 1402 1403
		%

		if this.handle==0, error('Not connected.'); end;

1404
		[ids] = VAMatlab('get_sound_portal_ids', this.handle);
1405 1406
	end

1407 1408
	function [name] = get_sound_portal_name(this, portalID)
		% Returns the name of a portal
1409 1410 1411
		%
		% Parameters:
		%
1412
		% 	portalID [integer-1x1] Portal ID
1413 1414 1415
		%
		% Return values:
		%
1416
		% 	name [string] Displayed name