itaVA.m 69.8 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 
       
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
140
        function [connected] = get_connected(this)
141
            % Returns if a connection to a server is established
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
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
        function connect_tracker( this, remote_ip, local_ip )
208
209
            % Connects to a local NatNet tracking server
            % 
210
211
            % The server will update a virtual sound receiver for real-time 
            % sound synthesis and the real world sound receiver position for
212
213
214
            % those sound reproductions that need this information, like  
            % Crosstalk-Cancellation.
            %
215
            % See also set_tracked_sound_receiver.
216
217
218
219
220
221
222
223
224
225
226
227
            %
            % 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

228
            VAMatlab( 'connect_tracker', this.handle, remote_ip, local_ip );
229
230
        end
        
231
        function [connected] = get_tracker_connected( this )
232
            % Returns true, if tracker is connected
233
            connected = VAMatlab( 'get_tracker_connected', this.handle );
234
235
        end
        
236
        function disconnect_tracker( this )
237
            % Disconnects from the NatNet tracking server
238
            VAMatlab( 'disconnect_tracker', this.handle )
239
240
        end
        
241
		% -- Tracked sound receiver -- %
242
		
243
244
        function set_tracked_sound_receiver( this, sound_receiver_id )
            % Connects a VA sound receiver with the tracked sound receiver rigid body
245
246
247
            %
            % Parameters:
            %
248
            % 	sound_receiver_id  [integer-1x1]   VA sound receiver id
249
            %
250
            VAMatlab( 'set_tracked_sound_receiver', this.handle, sound_receiver_id );
251
        end
252
        
253
254
255
        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 )
256
257
        end
        
258
259
260
261
262
263
264
        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
265
266
267
268
269
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
270
            VAMatlab( 'set_tracked_sound_receiver_head_rigid_body_translation', this.handle, translation )
271
272
        end
        
273
274
        function set_tracked_sound_receiver_head_rigid_body_rotation( this, rotation )
            % Sets the rotation of orientation for the tracked sound receiver rigid body
275
276
277
278
279
280
281
			%
			% Given rotation has to be a Matlab quaternion type (order: w(real), i, j, k)
			%
			% Parameters:
			%
			%	rotation [quaternion]	Rotation of rigid body
			%
282
            VAMatlab( 'set_tracked_sound_receiver_head_rigid_body_rotation', this.handle, rotation )
283
284
        end
		
285
		% -- Tracked real-world sound receiver -- %
286
		
287
288
        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
289
290
291
            %
            % Parameters:
            %
292
            % 	sound_receiver_id  [integer-1x1]   VA real-world sound receiver id
293
            %
294
295
296
297
298
            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)
299
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_index', this.handle, index )
300
301
        end
		
302
303
304
        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 )
305
306
        end
        
307
        function set_tracked_real_world_sound_receiver_head_rb_trans( this, translation )
308
            % Sets the pivot point translation for the tracked real-world sound receiver rigid body
309
310
311
312
313
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
314
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_translation', this.handle, translation )
315
        end
316
        
317
        function set_tracked_real_world_sound_receiver_head_rb_rotation( this, rotation )
318
            % Sets the rotation of orientation for the tracked real-world sound receiver rigid body
319
320
321
322
323
324
325
			%
			% Given rotation has to be a Matlab quaternion type (order: w(real), i, j, k)
			%
			% Parameters:
			%
			%	rotation [quaternion]	Rotation of rigid body
			%
326
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_rotation', this.handle, rotation )
327
328
        end
		        
329
330
		% -- Tracked source -- %
		
331
        function set_tracked_sound_source( this, source_id )
332
333
334
335
            % Connects a VA source with the tracked source rigid body
            %
            % Parameters:
            %
336
            % 	source_id  [integer-1x1]   VA source id
337
            %
338
            VAMatlab( 'set_tracked_sound_source', this.handle, source_id );
339
        end
340
		
341
        function set_tracked_sound_source_rigid_body_index( this, index )
342
            % Sets the index of the rigid body to be tracked for source (default is 1)
343
            VAMatlab( 'set_tracked_sound_source_rigid_body_index', this.handle, index )
344
345
        end
        
346
        function set_tracked_sound_source_rigid_body_translation( this, translation )
347
348
349
350
351
352
            % Sets the pivot point translation for the tracked source rigid body
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
353
            VAMatlab( 'set_tracked_sound_source_rigid_body_translation', this.handle, translation )
354
355
        end
        
356
        function set_tracked_sound_source_rigid_body_rotation( this, rotation )
357
358
359
360
361
362
363
364
            % 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
			%
365
366
367
368
369
370
371
            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 )
372
373
        end
		
374
375
376
377
378
379
380
381
382
		%% --= 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
		
383
384
385
        
        %% --= Functions =--
        
386
        	function [valid] = add_search_path(this, path)
387
388
389
390
391
392
393
394
395
396
397
398
399
		% 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;

400
		[valid] = VAMatlab('add_search_path', this.handle, path);
401
402
	end

403
404
	function [ret] = call_module(this, module,mstruct)
		% Calls an internal module of the VA server
405
406
407
		%
		% Parameters:
		%
408
409
		% 	module [string] Module name
		% 	mstruct [struct] Matlab structure with key-value content
410
411
412
		%
		% Return values:
		%
413
		% 	ret [struct-1x1] Struct containing the return values
414
415
416
417
		%

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

418
		[ret] = VAMatlab('call_module', this.handle, module,mstruct);
419
420
	end

421
422
	function [material_id] = create_acoustic_material_from_file(this, file_path,material_name)
		% Create acoustic material
423
424
425
		%
		% Parameters:
		%
426
427
		% 	file_path [string] Material file path
		% 	material_name [string] Material name (optional, default: '')
428
429
430
		%
		% Return values:
		%
431
		% 	material_id [double-1x1] Material identifier
432
433
434
435
		%

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

436
437
		if ~exist('material_name','var'), material_name = ''; end
		[material_id] = VAMatlab('create_acoustic_material_from_file', this.handle, file_path,material_name);
438
439
	end

440
	function [directivityID] = create_directivity_from_file(this, filename,name)
441
		% Loads a directivity from a file
442
443
444
445
446
447
448
449
		%
		% Parameters:
		%
		% 	filename [string] Filename
		% 	name [string] Displayed name (optional, default: '')
		%
		% Return values:
		%
450
		% 	directivityID [integer-1x1] Directivity ID
451
452
453
454
455
		%

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

		if ~exist('name','var'), name = ''; end
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
		[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);
476
477
	end

478
479
	function [geo_mesh_id] = create_geometry_mesh_from_file(this, file_path,geo_mesh_name)
		% Create geometry mesh from file
480
481
482
		%
		% Parameters:
		%
483
484
		% 	file_path [string] Geometry mesh file path
		% 	geo_mesh_name [string] Geometry mesh name (optional, default: '')
485
486
487
		%
		% Return values:
		%
488
		% 	geo_mesh_id [double-1x1] Geometry mesh identifier
489
490
491
492
		%

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

493
494
		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);
495
496
	end

497
498
	function [signalSourceID] = create_signal_source_buffer_from_file(this, filename,name)
		% Creates a signal source which plays an audiofile
499
500
501
		%
		% Parameters:
		%
502
		% 	filename [string] Filename
503
504
505
506
		% 	name [string] Displayed name (optional, default: '')
		%
		% Return values:
		%
507
		% 	signalSourceID [string] Signal source ID
508
509
510
511
512
		%

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

		if ~exist('name','var'), name = ''; end
513
		[signalSourceID] = VAMatlab('create_signal_source_buffer_from_file', this.handle, filename,name);
514
515
	end

516
517
	function [signalSourceID] = create_signal_source_buffer_from_parameters(this, params,name)
		% Creates an buffer signal source
518
519
520
		%
		% Parameters:
		%
521
		% 	params [struct] Parameters
522
523
524
525
526
527
528
529
530
531
		% 	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
532
		[signalSourceID] = VAMatlab('create_signal_source_buffer_from_parameters', this.handle, params,name);
533
534
	end

535
536
	function [signalSourceID] = create_signal_source_engine(this, params,name)
		% Creates an engine signal source
537
538
539
		%
		% Parameters:
		%
540
		% 	params [struct] Parameters
541
542
543
544
545
546
547
548
549
550
		% 	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
551
		[signalSourceID] = VAMatlab('create_signal_source_engine', this.handle, params,name);
552
553
	end

554
555
	function [signalSourceID] = create_signal_source_network_stream(this, address,port,name)
		% Creates a signal source which receives audio samples via network
556
557
558
		%
		% Parameters:
		%
559
560
		% 	address [string] Hostname or IP address of the audio streaming server
		% 	port [integer-1x1] Server port
561
562
563
564
		% 	name [string] Displayed name (optional, default: '')
		%
		% Return values:
		%
565
		% 	signalSourceID [string] Signal source ID
566
567
568
569
570
		%

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

		if ~exist('name','var'), name = ''; end
571
		[signalSourceID] = VAMatlab('create_signal_source_network_stream', this.handle, address,port,name);
572
573
	end

574
575
	function [signalSourceID] = create_signal_source_sequencer(this, name)
		% Creates a sequencer signal source
576
577
578
		%
		% Parameters:
		%
579
		% 	name [string] Displayed name (optional, default: '')
580
581
582
		%
		% Return values:
		%
583
		% 	signalSourceID [string] Signal source ID
584
585
586
587
		%

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

588
589
		if ~exist('name','var'), name = ''; end
		[signalSourceID] = VAMatlab('create_signal_source_sequencer', this.handle, name);
590
591
	end

592
	function [signalSourceID] = create_signal_source_text_to_speech(this, name)
593
594
595
596
597
598
599
600
601
602
603
604
605
606
		% 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
607
		[signalSourceID] = VAMatlab('create_signal_source_text_to_speech', this.handle, name);
608
609
	end

610
611
	function [id] = create_sound_receiver(this, name)
		% Creates a sound receiver
612
613
614
		%
		% Parameters:
		%
615
		% 	name [string] Displayed name (optional, default: '')
616
617
618
		%
		% Return values:
		%
619
		% 	id [integer-1x1] Sound receiver ID
620
621
622
623
		%

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

624
625
		if ~exist('name','var'), name = ''; end
		[id] = VAMatlab('create_sound_receiver', this.handle, name);
626
627
	end

628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
	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

646
647
	function [id] = create_sound_source(this, name)
		% Creates a sound source
648
649
650
		%
		% Parameters:
		%
651
		% 	name [string] Displayed name (optional, default: '')
652
653
654
		%
		% Return values:
		%
655
		% 	id [integer-1x1] Sound source ID
656
657
658
659
		%

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

660
661
		if ~exist('name','var'), name = ''; end
		[id] = VAMatlab('create_sound_source', this.handle, name);
662
663
	end

664
665
	function [id] = create_sound_source_explicit_renderer(this, renderer,name)
		% Creates a sound source explicitly for a certain renderer
666
667
668
		%
		% Parameters:
		%
669
670
		% 	renderer [string] Renderer identifier
		% 	name [string] Name
671
672
673
		%
		% Return values:
		%
674
		% 	id [integer-1x1] Sound source ID
675
676
677
678
		%

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

679
		[id] = VAMatlab('create_sound_source_explicit_renderer', this.handle, renderer,name);
680
681
	end

682
683
	function [success_flag] = delete_acoustic_material(this, material_id)
		% Delete acoustic material
684
685
686
		%
		% Parameters:
		%
687
		% 	material_id [double-1x1] Material identifier
688
689
690
		%
		% Return values:
		%
691
		% 	success_flag [logical-1x1] Removal success
692
693
694
695
		%

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

696
		[success_flag] = VAMatlab('delete_acoustic_material', this.handle, material_id);
697
698
	end

699
	function [result] = delete_directivity(this, directivityID)
700
701
702
703
704
705
706
707
708
709
710
711
712
		% 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;

713
		[result] = VAMatlab('delete_directivity', this.handle, directivityID);
714
715
	end

716
717
	function [success_flag] = delete_geometry_mesh(this, geo_mesh_id)
		% Delete geometry mesh
718
719
720
		%
		% Parameters:
		%
721
		% 	geo_mesh_id [double-1x1] Geometry mesh identifier
722
723
724
		%
		% Return values:
		%
725
		% 	success_flag [logical-1x1] Removal success
726
727
728
729
		%

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

730
		[success_flag] = VAMatlab('delete_geometry_mesh', this.handle, geo_mesh_id);
731
732
	end

733
734
	function [result] = delete_signal_source(this, signalSourceID)
		% Deletes a signal source
735
736
737
		%
		% Parameters:
		%
738
		% 	signalSourceID [string] Signal source ID
739
740
741
		%
		% Return values:
		%
742
		% 	result [logical-1x1] Signal source deleted?
743
744
745
746
		%

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

747
		[result] = VAMatlab('delete_signal_source', this.handle, signalSourceID);
748
749
	end

750
751
	function [] = delete_sound_receiver(this, soundreceiverID)
		% Deletes a sound receiver from the scene
752
753
754
		%
		% Parameters:
		%
755
		% 	soundreceiverID [integer-1x1] Sound receiver ID
756
757
758
		%
		% Return values:
		%
759
		% 	None
760
761
762
763
		%

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

764
		VAMatlab('delete_sound_receiver', this.handle, soundreceiverID);
765
766
	end

767
768
	function [] = delete_sound_source(this, soundSourceID)
		% Deletes an existing sound source in the scene
769
770
771
		%
		% Parameters:
		%
772
		% 	soundSourceID [integer-1x1] Sound source ID
773
774
775
		%
		% Return values:
		%
776
		% 	None
777
778
779
780
		%

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

781
		VAMatlab('delete_sound_source', this.handle, soundSourceID);
782
783
	end

784
785
	function [params] = get_acoustic_magerial_parameters(this, material_id,args)
		% Acoustic material parameter getter
786
787
788
		%
		% Parameters:
		%
789
790
		% 	material_id [integer-1x1] Acoustic material identifier
		% 	args [mstruct] Requested parameters
791
792
793
		%
		% Return values:
		%
794
		% 	params [mstruct] Parameters
795
796
797
798
		%

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

799
		[params] = VAMatlab('get_acoustic_magerial_parameters', this.handle, material_id,args);
800
801
	end

802
803
	function [soundreceiverID] = get_active_sound_receiver(this)
		% Returns the active sound receiver
804
805
806
807
808
809
810
		%
		% Parameters:
		%
		% 	None
		%
		% Return values:
		%
811
		% 	soundreceiverID [integer-1x1] Sound receiver ID
812
813
814
815
		%

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

816
		[soundreceiverID] = VAMatlab('get_active_sound_receiver', this.handle);
817
818
	end

819
820
	function [clk] = get_core_clock(this)
		% Returns the current core time
821
822
823
		%
		% Parameters:
		%
824
		% 	None
825
826
827
		%
		% Return values:
		%
828
		% 	clk [double-1x1] Core clock time (unit: seconds)
829
830
831
832
		%

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

833
		[clk] = VAMatlab('get_core_clock', this.handle);
834
835
	end

836
837
	function [info] = get_directivity_info(this, directivityID)
		% Returns information on a loaded directivity
838
839
840
		%
		% Parameters:
		%
841
		% 	directivityID [integer-1x1] Directivity ID
842
843
844
		%
		% Return values:
		%
845
		% 	info [struct-1x1] Information struct (name, filename, resolution, etc.)
846
847
848
849
		%

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

850
		[info] = VAMatlab('get_directivity_info', this.handle, directivityID);
851
852
	end

853
854
	function [info] = get_directivity_infos(this)
		% Returns information on all loaded directivities
855
856
857
858
859
860
861
		%
		% Parameters:
		%
		% 	None
		%
		% Return values:
		%
862
		% 	info [cell-array of struct-1x1] Information structs (name, filename, resolution, etc.)
863
864
865
866
		%

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

867
		[info] = VAMatlab('get_directivity_infos', this.handle);
868
869
	end

870
871
	function [result] = get_geometry_mesh_enabled(this, geo_mesh_id)
		% Geometry mesh enabled getter
872
873
874
		%
		% Parameters:
		%
875
		% 	geo_mesh_id [integer-1x1] Geometry mesh identifier
876
877
878
		%
		% Return values:
		%
879
		% 	result [logical-1x1] Enabled flag
880
881
882
883
		%

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

884
		[result] = VAMatlab('get_geometry_mesh_enabled', this.handle, geo_mesh_id);
885
886
	end

887
888
	function [params] = get_geometry_mesh_parameters(this, geo_mesh_id,args)
		% Geometry mesh parameter getter
889
890
891
		%
		% Parameters:
		%
892
893
		% 	geo_mesh_id [integer-1x1] Geometry mesh identifier
		% 	args [mstruct] Requested parameters
894
895
896
		%
		% Return values:
		%
897
		% 	params [mstruct] Parameters
898
899
900
901
		%

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

902
		[params] = VAMatlab('get_geometry_mesh_parameters', this.handle, geo_mesh_id,args);
903
904
	end

905
906
	function [auralizationMode] = get_global_auralization_mode(this)
		% Returns the global auralization mode
907
908
909
910
911
912
913
		%
		% Parameters:
		%
		% 	None
		%
		% Return values:
		%
914
		% 	auralizationMode [string] Auralization mode
915
916
917
918
		%

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

919
		[auralizationMode] = VAMatlab('get_global_auralization_mode', this.handle);
920
921
	end

922
923
	function [shift_speed] = get_homogeneous_medium_relative_humidity(this)
		% Get homogeneous medium relative humidity
924
925
926
		%
		% Parameters:
		%
927
		% 	None
928
929
930
		%
		% Return values:
		%
931
		% 	shift_speed [double-1x1] Relative humidity [Percent]
932
933
934
935
		%

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

936
		[shift_speed] = VAMatlab('get_homogeneous_medium_relative_humidity', this.handle);
937
938
	end

939
940
	function [params] = get_homogeneous_medium_shift_parameters(this, args)
		% Returns homogeneous medium parameters
941
942
943
		%
		% Parameters:
		%
944
		% 	args [mstruct] Requested parameters
945
946
947
		%
		% Return values:
		%
948
		% 	params [mstruct] Parameters
949
950
951
952
		%

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

953
		[params] = VAMatlab('get_homogeneous_medium_shift_parameters', this.handle, args);
954
955
	end

956
957
	function [shift_speed] = get_homogeneous_medium_shift_speed(this)
		% Get homogeneous medium shift speed
958
959
960
961
962
963
964
		%
		% Parameters:
		%
		% 	None
		%
		% Return values:
		%
965
		% 	shift_speed [double-3x1] Shift speed vector [m/s]
966
967
968
969
		%

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

970
		[shift_speed] = VAMatlab('get_homogeneous_medium_shift_speed', this.handle);
971
972
	end

973
974
	function [sound_speed] = get_homogeneous_medium_sound_speed(this)
		% Get homogeneous medium sound speed
975
976
977
		%
		% Parameters:
		%
978
		% 	None
979
980
981
		%
		% Return values:
		%
982
		% 	sound_speed [double-1x1] Sound speed [m/s]
983
984
985
986
		%

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

987
		[sound_speed] = VAMatlab('get_homogeneous_medium_sound_speed', this.handle);
988
989
	end

990
991
	function [static_pressure] = get_homogeneous_medium_static_pressure(this)
		% Get homogeneous medium static pressure
992
993
994
		%
		% Parameters:
		%
995
		% 	None
996
997
998
		%
		% Return values:
		%
999
		% 	static_pressure [double-1x1] Static pressure [Pa]
1000
1001
1002
1003
		%

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

1004
		[static_pressure] = VAMatlab('get_homogeneous_medium_static_pressure', this.handle);
1005
1006
	end

1007
1008
	function [temperature] = get_homogeneous_medium_temperature(this)
		% Get homogeneous medium temperature
1009
1010
1011
		%
		% Parameters:
		%
1012
		% 	None
1013
1014
1015
		%
		% Return values:
		%
1016
		% 	temperature [double-1x1] Temperature [degree Celsius]
1017
1018
1019
1020
		%

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

1021
		[temperature] = VAMatlab('get_homogeneous_medium_temperature', this.handle);
1022
1023
	end

1024
1025
	function [gain] = get_input_gain(this)
		% Returns the gain the audio device input channels
1026
1027
1028
		%
		% Parameters:
		%
1029
		% 	None
1030
1031
1032
		%
		% Return values:
		%
1033
		% 	gain [double-1x1] Input gain (amplification factor >=0)
1034
1035
1036
1037
		%

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

1038
		[gain] = VAMatlab('get_input_gain', this.handle);
1039
1040
	end

1041
1042
	function [result] = get_input_muted(this)
		% Returns if the audio device inputs are muted
1043
1044
1045
		%
		% Parameters:
		%
1046
		% 	None
1047
1048
1049
		%
		% Return values:
		%
1050
		% 	result [logical-1x1] Inputs muted?
1051
1052
1053
1054
		%

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

1055
		[result] = VAMatlab('get_input_muted', this.handle);
1056
1057
	end

1058
1059
	function [modules] = get_modules(this)
		% Enumerates internal modules of the VA server
1060
1061
1062
		%
		% Parameters:
		%
1063
		% 	None
1064
1065
1066
		%
		% Return values:
		%
1067
		% 	modules [cell-array of struct-1x1] Module informations (names, descriptions, etc.)
1068
1069
1070
1071
		%

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

1072
		[modules] = VAMatlab('get_modules', this.handle);
1073
1074
	end

1075
1076
	function [gain] = get_output_gain(this)
		% Returns the global output gain
1077
1078
1079
		%
		% Parameters:
		%
1080
		% 	None
1081
1082
1083
		%
		% Return values:
		%
1084
		% 	gain [double-1x1] Output gain (amplification factor >=0)
1085
1086
1087
1088
		%

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

1089
		[gain] = VAMatlab('get_output_gain', this.handle);
1090
1091
	end

1092
1093
	function [result] = get_output_muted(this)
		% Returns if the global output is muted
1094
1095
1096
		%
		% Parameters:
		%
1097
		% 	None
1098
1099
1100
		%
		% Return values:
		%
1101
		% 	result [logical-1x1] Output muted?
1102
1103
1104
1105
		%

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

1106
		[result] = VAMatlab('get_output_muted', this.handle);
1107
1108
	end

1109
1110
	function [renderers] = get_rendering_modules(this, bFilterEnabled)
		% Get list of rendering modules
1111
1112
1113
		%
		% Parameters:
		%
1114
		% 	bFilterEnabled [boolean-1x1] Filter activated (true) (optional, default: 1)
1115
1116
1117
		%
		% Return values:
		%
1118
		% 	renderers [cell-array of struct-1x1] Renderer infos (names, descriptions, etc.)
1119
1120
1121
1122
		%

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

1123
1124
		if ~exist('bFilterEnabled','var'), bFilterEnabled = 1; end
		[renderers] = VAMatlab('get_rendering_modules', this.handle, bFilterEnabled);
1125
1126
	end

1127
1128
	function [auralization_mode] = get_rendering_module_auralization_mode(this, sModuleID)
		% Returns the current rendering module parameters
1129
1130
1131
		%
		% Parameters:
		%
1132
		% 	sModuleID [string] Module identifier
1133
1134
1135
		%
		% Return values:
		%
1136
		% 	auralization_mode [string] Auralization mode as string
1137
1138
1139
1140
		%

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

1141
		[auralization_mode] = VAMatlab('get_rendering_module_auralization_mode', this.handle, sModuleID);
1142
1143
	end

1144
1145
	function [dGain] = get_rendering_module_gain(this, sModuleID)
		% Get rendering module output gain
1146
1147
1148
		%
		% Parameters:
		%
1149
		% 	sModuleID [string] Module identifier
1150
1151
1152
		%
		% Return values:
		%
1153
		% 	dGain [double-1x1] Gain (scalar)
1154
1155
1156
1157
		%

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

1158
		[dGain] = VAMatlab('get_rendering_module_gain', this.handle, sModuleID);
Jan-Gerrit Richter's avatar