itaVA.proto.m 8.63 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 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 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 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 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276
classdef itaVA < handle
    %ITAVA Remote interface for VA real-time auralization servers
    %
    %   This class realizes a remote connection to a VA real-time
    %   auralization server and implements the full VA core interface
    %   in Matlab. This way you connect to an auralization server
    %   and control all of its features to perform a real-time
    %   auralization. In order to get understand to the concepts behind VA
    %   please refer to the VA documentation.
    %
    %   Usage & examples:
    %
    %   - Create an interface and connect to the server running on the
    %     same computer (localhost)
    %
    %     va = itaVA('localhost');
    %
    %     If no error occurs, you can then use the interface to work with
    %     the VA server. Best practice is to reset it first:
    %
    %     va.reset
    %
    %     Then you can call other methods. For instance create a sound
    %     source:
    %
    %     sourceID = va.createSoundSource('Virtual sound source')
    %
    %     When everything is done, do not forget to close the connection.
    %     You can call disconnect on the instance or simply clear it:
    %
    %     clear va
    %
    %   - You can find more examples in the demo files
    %
    %   Questions? Contact the author: Frank.Wefers@akustik.rwth-aachen.de
    %
    %   Otherwise => Enjoy!
    %
    
    properties(Hidden = true, Access = private)
        handle = int32(0); % Connection handle
        
        % Connection defaults
        DEFAULT_SERVER_PORT = 12340;
    end
    
    methods(Static)
        function [version] = getVersion()
            % Return the version of the VA Matlab interface
            %
            % Parameters:
            %
            % 	None
            %
            % Return values:
            %
            % 	version  [string]  Version string
            version = VAMatlab('getVersion');
        end
        
         function [] = setVerboseMode(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'
            %
            VAMatlab('setVerboseMode', mode);
        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');
            %
            
            if (nargin > 0)
                this.connect(addressstring)
            end
        end
        
        function delete(this)
            % Destructor. Automatically disconnects an existing connection.
            this.disconnect
        end 
       
        function [connected] = isConnected(this)
            % Returns if a connection to a server is established
           connected = VAMatlab('isConnected', 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] = getServerState(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('getServerState', this.handle);
        end
        
        function connectTracker( this, remote_ip, local_ip )
            % Connects to a local NatNet tracking server
            % 
            % The server will update a virtual listener for real-time 
            % sound synthesis and the real world listener position for
            % those sound reproductions that need this information, like  
            % Crosstalk-Cancellation.
            %
            % See also setTrackedListener.
            %
            % 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( 'ConnectTracker', this.handle, remote_ip, local_ip );
        end
        
        function [connected] = isTrackerConnected( this )
            % Returns true, if tracker is connected
            connected = VAMatlab( 'IsTrackerConnected', this.handle );
        end
        
        function setTrackedListener( this, listener_id )
            % Connects a VA listener with the tracked rigid body
            %
            % Parameters:
            %
            % 	listener_id  [integer-1x1]   VA listener id
            %
            VAMatlab( 'SetTrackedListener', this.handle, listener_id );
        end
        
        function setTrackedSource( this, source_id )
            % Connects a VA source with the tracked rigid body
            %
            % Parameters:
            %
            % 	source_id  [integer-1x1]   VA listener id
            %
            VAMatlab( 'SetTrackedSource', this.handle, source_id );
        end
        
        function disconnectTracker( this )
            % Disconnects from the NatNet tracking server
            VAMatlab( 'DisconnectTracker', this.handle )
        end
        
        function setRigidBodyIndex( this, index )
            % Sets the index of the rigid body to be tracked (default is 1)
            VAMatlab( 'SetRigidBodyIndex', this.handle, index )
        end
        
        function setRigidBodyTranslation( this, translation )
            % Sets the pivot point translation for the tracked rigid body
			%
			% Parameters:
			%
			%	translation [double-3x1]	Translation in local coordinate system of rigid body [m]
			%
            VAMatlab( 'SetRigidBodyTranslation', this.handle, translation )
        end
        
        function setRigidBodyRotation( this, rotation )
            % Sets the rotation of orientation for the tracked 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( 'SetRigidBodyRotation', this.handle, rotation )
        end
        
        %% --= Functions =--
        
        ###STUBCODE###
        
        function display(this)
            % TODO: Define nice behaviour
%             if this.handle
%                 fprintf('Connection established to server ''%s''\n', this.getServerAddress())
%             else
%                 fprintf('Not connected\n');
%             end
        end
        
    end

end