classdef VA < handle
    %VA Remote network interface to VA (Virtual Acoustics), the real-time 
    %auralization framework.
	%
	% Find the VA applications, documentation and examples here: http://www.virtualacoustics.org
    %
    %   This class realizes a remote connection to a VA real-time
    %   auralization server and implements the full VA core interface
    %   in Matlab. You can connect to to the server
    %   and control all of its features to perform real-time
    %   auralization, including integrated live tracking if an OptiTrack tracker is at hand.
    %
    %   See also: VA_example_simple, VA_example_tracked_sound_receiver,
    %   VA_example_generic_path_renderer, VA_example_random_numbers
    %   VA_example_generic_path_renderer, VA_example_random_numbers
    %
    %   Quick usage:
    %
    %   - Create an interface and connect to the server running on the
    %     same computer (localhost)
    %
    %     va = VA;
    %     va.connect;
    %
    %     If the connection is established, you can start controlling VA via the interface.
    %	  For instance create an move a sound source:
    %
    %     sourceID = va.create_sound_source( 'My Matlab virtual sound source' )
	%	  va.set_sound_source_position( sourceID, [ 0 0 0 ] );
    %
    %     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
                
        % Connection defaults
        DEFAULT_SERVER_PORT = 12340;
    end
    
    methods(Static)
        
        function [ ok ] = check_for_mex_file()
            % Checks if VAMatlab executable can be found.
            if ~exist( 'VAMatlab', 'file' )
                disp( 'Matlab binding for VA not found, starting VA setup routine' )
                
                % file dialog
                VA_setup()
                
                % Re-check
                ok = exist( 'VAMatlab', 'file' ) > 0;
            else
                ok = true;
            end
        end
        
        function [version] = get_version()
            % Return the version of the VA Matlab interface
            %
            % Parameters:
            %
            % 	None
            %
            % Return values:
            %
            % 	version  [string]  Version string
            
            if ~VA.check_for_mex_file()
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end

            version = VAMatlab('get_version');
        end
        
         function [] = set_verbose_mode(mode)
            % 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'
            %
            
            if ~VA.check_for_mex_file()
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end

            VAMatlab('set_verbose_mode', mode);
        end
		
    end

    methods
        function this = VA(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 = VA;
            %            core = VA('localhost:12340');
            %
            
            if ~VA.check_for_mex_file()
                error( 'Matlab binding for VA requires VAMatlab executable.' );
            end
        
            if (nargin > 0)
                this.connect(addressstring)
            end
        end
        
        function delete(this)
            % Destructor. Automatically disconnects an existing connection.
            this.disconnect
        end 
       
        function [connected] = get_connected(this)
            % Returns if a connection to a server is established
           connected = VAMatlab('get_connected', this.handle);
        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
           
        function [state] = get_server_state(this)
            % 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; 
            state = VAMatlab('get_server_state', this.handle);
        end
		
		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
        
        function connect_tracker( this, remote_ip, local_ip )
            % Connects to a local NatNet tracking server
            % 
            % The server will update a virtual sound receiver for real-time 
            % sound synthesis and the real world sound receiver position for
            % those sound reproductions that need this information, like  
            % Crosstalk-Cancellation.
            %
            % See also set_tracked_sound_receiver.
            %
            % 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

            VAMatlab( 'connect_tracker', this.handle, remote_ip, local_ip );
        end
        
        function [connected] = get_tracker_connected( this )
            % Returns true, if tracker is connected
            connected = VAMatlab( 'get_tracker_connected', this.handle );
        end
        
        function disconnect_tracker( this )
            % Disconnects from the NatNet tracking server
            VAMatlab( 'disconnect_tracker', this.handle )
        end
        
		% -- Tracked sound receiver -- %
		
        function set_tracked_sound_receiver( this, sound_receiver_id )
            % Connects a VA sound receiver with the tracked sound receiver rigid body
            %
            % Parameters:
            %
            % 	sound_receiver_id  [integer-1x1]   VA sound receiver id
            %
            VAMatlab( 'set_tracked_sound_receiver', this.handle, sound_receiver_id );
        end
        
        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 )
        end
        
        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
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
            VAMatlab( 'set_tracked_sound_receiver_head_rigid_body_translation', this.handle, translation )
        end
        
        function set_tracked_sound_receiver_head_rigid_body_rotation( this, rotation )
            % Sets the rotation of orientation for the tracked sound receiver rigid body
			%
			% Given rotation has to be a Matlab quaternion type (order: w(real), i, j, k)
			%
			% Parameters:
			%
			%	rotation [quaternion]	Rotation of rigid body
			%
            VAMatlab( 'set_tracked_sound_receiver_head_rigid_body_rotation', this.handle, rotation )
        end
		
		% -- Tracked real-world sound receiver -- %
		
        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
            %
            % Parameters:
            %
            % 	sound_receiver_id  [integer-1x1]   VA real-world sound receiver id
            %
            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)
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_index', this.handle, index )
        end
		
        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 )
        end
        
        function set_tracked_real_world_sound_receiver_head_rb_trans( this, translation )
            % Sets the pivot point translation for the tracked real-world sound receiver rigid body
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_translation', this.handle, translation )
        end
        
        function set_tracked_real_world_sound_receiver_head_rb_rotation( this, rotation )
            % Sets the rotation of orientation for the tracked real-world sound receiver rigid body
			%
			% Given rotation has to be a Matlab quaternion type (order: w(real), i, j, k)
			%
			% Parameters:
			%
			%	rotation [quaternion]	Rotation of rigid body
			%
            VAMatlab( 'set_tracked_real_world_sound_receiver_head_rigid_body_rotation', this.handle, rotation )
        end
		        
		% -- Tracked source -- %
		
        function set_tracked_sound_source( this, source_id )
            % Connects a VA source with the tracked source rigid body
            %
            % Parameters:
            %
            % 	source_id  [integer-1x1]   VA source id
            %
            VAMatlab( 'set_tracked_sound_source', this.handle, source_id );
        end
		
        function set_tracked_sound_source_rigid_body_index( this, index )
            % Sets the index of the rigid body to be tracked for source (default is 1)
            VAMatlab( 'set_tracked_sound_source_rigid_body_index', this.handle, index )
        end
        
        function set_tracked_sound_source_rigid_body_translation( this, translation )
            % Sets the pivot point translation for the tracked source rigid body
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
            VAMatlab( 'set_tracked_sound_source_rigid_body_translation', this.handle, translation )
        end
        
        function set_tracked_sound_source_rigid_body_rotation( this, rotation )
            % 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
			%
            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 )
        end
		
		%% --= 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
		
        
        %% --= Functions =--
        
        ###STUBCODE###
        
        function display(this)
            % TODO: Define nice behaviour
%             if this.handle
%                 fprintf('Connection established to server ''%s''\n', this.get_server_address())
%             else
%                 fprintf('Not connected\n');
%             end
        end
        
    end

end