/****************************************************************************

 Package:		Device3
 
 File:			ImmDevice3.h

 Version:		3.2

 Description:	Provides abstrations for programming 3DOF haptic devices.

 Copyright:		(c)1997-1999 Immersion Corporation.  All Rights Reserved.

 History:
	Feb.26.1999	evan@immersion.com	Adapted from Device3 v2.0.
	Aug.8.2000 sozenne@immersion.com -- added access to _GraspMin, _GraspMax,
										and _ToolLength, needed for LapIE only
****************************************************************************/

#ifndef IMMERSION_DEVICE3_IMMDEVICE3_H
#define IMMERSION_DEVICE3_IMMDEVICE3_H



#if defined SIMULATOR_DLL_EXPORTS

#define DLL_SYMBOL __declspec(dllexport)

#else

#define DLL_SYMBOL __declspec(dllimport)

#endif



/***************************************************************************/
//
//  Constants
//
/***************************************************************************/

// Represents the value of IE_DEVICE_N.
//
// This constant is copied from the impulse.h header file.  It is provided
// for convenience, so that one does not need the Impulse SDK installed to
// build software with Device3.
//
// Be warned: if the value IE_DEVICE_N in impulse.h is changed, so must this.
const unsigned int kImm_IE_DEVICE_N	= 3;



/***************************************************************************/
//
//  Structure Definitions
//
/***************************************************************************/

// Cartesian Coordinates
typedef struct {
	double x;
	double y;
	double z;
} ImmCoord3;	// inches


/**
 * ImmRot3 represents a rotation matrix.
 */
typedef double	ImmRot3[3][3];


// Device Type flags
typedef enum
{
	DEVICE_IE2000				= 0x0200,	// The Impulse Engine 2000
	DEVICE_FORCEPAD				= 0x0202,	// The ForcePad
	
	DEVICE_3GM					= 0x0300,	// Brushed Motor 3GM Mechanism w/o IR
	DEVICE_3GM_BRUSHLESS		= 0x0301,	// Brushless Motor 3GM Mechanism w/o IR
	DEVICE_3GM_IR				= 0x0302,	// Brushed Motor 3GM Mechanism w/ IR
	DEVICE_3GM_BRUSHLESS_IR		= 0x0303,	// Brushless Motor 3GM Mechanism w/ IR

	DEVICE_LAPIE				= 0x0400	// The Laproscopic Impulse Engine
} ImmDeviceType;


// Return Values
typedef enum
{
// Success
	RESULT_OK					= 0,

// Failure (<0)
	RESULT_FAILURE				= -1,
	RESULT_NOT_IMPLEMENTED		= -3,

// Abnormal operation (>0)
	RESULT_OVERFLOW				= 1,
} ImmResult;



/**
 * The ImmDevice3 class is an abstraction of a haptic interface device 
 * operating in a three-dimensional Cartesian coordinate frame. To instantiate 
 * an ImmDevice3 object, you cannot use an ordinary constructor. Instead, you 
 * must acquire an ImmSurgicalWorkstation through the 
 * ImmSurgicalWorkstationFactory class.
 *
 * The ImmDevice3 class is not thread-safe.  You must perform locking and synchronization 
 * on your own.
 *
 * The following describes the general implementation philosophy of the 
 * ImmDevice3 class.   The Get methods and the Set methods are very lightweight.  
 * They basically read are write to state variables. On the other hand, the 
 * Update method performs significant computation and resource management.  
 * Thus, you should not worry about calling the Get and Set methods often, but 
 * only call Update once per servo loop.
 *
 */

class DLL_SYMBOL ImmDevice3
{
	public:
		/**
		 * Get the device's name.
		 * 
		 * \return 
		 *
		 * A pointer to a string containing the device's name.
		 *
		 * The method returns a NULL pointer if the method fails.
		 *
		 */
		
		virtual  char * GetDeviceName( void )    const     = 0;

		/**
		 * Get the Interface name
		 *
		 * \return 
		 *
		 * A pointer to a string containing the interface name.
		 *
		 * The method returns a NULL pointer if the method fails.
		 *
		 */
		
		virtual  char * GetInterfaceName( void ) const     = 0;

		/**
		 * Get the Unique ID of the device, if applicable.
		 * 
		 * \return 
		 * 
		 * A pointer to a string containing the device's unique ID.
		 *
		 * A null string indicates that the device does not have a unique 
		 * identifier.
		 *
		 * The method returns a NULL pointer if the method fails.
		 *
		 */
		
		virtual  char * GetUniqueID( void )	     const     = 0;

		/**
		 * Initiates a calibration procedure for the haptic interface device 
		 * that sets the encoders to zero at the current location.  This must 
		 * be performed before you can use the device.   
		 *
		 * \return 
		 *
		 * 0 if successful 
		 *
		 * -3 if the device isn't supported.
		 *
		 */

		virtual  int Calibrate( void ) = 0;

		/**
		 * Update the device's internal states, such as the current position 
		 * & force output.
		 * 
		 * \return 
		 *
		 * 0 if successful, 
		 *
		 * -3 if the device is not supported.
		 *
		 */

		virtual  int Update( void )    = 0;


		/**
		 * Retrieve the position of the tip of the device in the world frame, 
		 * with distance measured in mm in each dimension. Note that in 
		 * implementations the virtual tool length will be different from the 
		 * mechanical tool length, and it is the position of the virtual tool 
		 * tip which the interface will return. See ImmSWTool::GetTipParameters 
		 * for access to the virtual tool length and offset.
		 *
		 * \param thePosition points to memory for an ImmCoord3 three vector,
		 * where the device's current postion will be copied.
		 *
		 * \return 
		 *
		 * 0 if successful.
		 *
		 * -1 if the device needs to be updated before calling this method.
		 *
		 * -2 if thePosition is a NULL pointer.
		 *
		 */

		virtual  int		GetPosition( ImmCoord3 *thePosition )		= 0;

		/**
		 * Retrieve the device's tip velocity, in mm per second in each dimension.
		 * Note that in implementations the virtual tool length will be 
		 * different from the mechanical tool length, and it is the velocity
		 * of the virtual tool tip which the interface will return. See 
		 * ImmSWTool::GetTipParameters for access to the virtual tool length 
		 * and offset.
		 * 
		 * \param theVelocity points to memory for an ImmCoord3 three vector,
		 * where the tool's current velocity will be copied.
		 *
		 * \return 
		 *
		 * 0 if successful.
		 *
		 * -1 if the device needs to be updated before calling this method.
		 *
		 * -2 if theVelocity is a NULL pointer.
		 *
		 */

		virtual  int		GetVelocity( ImmCoord3 *theVelocity )		= 0;
		
		/**
		 * Get the device's orientation in the world frame.
		 *
		 * \param theOrientation points to memory for an ImmRot3 (a 3x3 
		 * orthogonal rotation matrix), where the tool's current orientation 
		 * will be copied.
		 *
		 * \return 
		 * 
		 * 0 if successful.
		 *
		 * -1 if the device needs to be updated before calling this method
		 *
		 * -2 if theOrientation is a NULL pointer. 
		 *
		 * In some devices, orientation makes no sense, so in this case, 
		 * the method will return 1 and set the theOrientation to the identity 
		 * matrix.
		 *
		 */

		virtual  int		GetOrientation( ImmRot3 *theOrientation )	= 0;
	
		/**
		 * Set the device force output, in Newtons. The force output will not 
		 * be reflected in the device until the next Update call.
		 *
		 * \param theForce specifies the force which the device should output.
		 *
		 * \return 
		 * 
		 * 0 if successful.
		 * 
		 * -1 if the device needs to be updated before calling this method.
		 *
		 * -2 if theForce is a NULL pointer.
		 *
		 */
		
		virtual  int		SetForce( const ImmCoord3 *theForce )		= 0;

		
		/**
		 * Get the device's digital input state.
		 *
		 * \param inputs points to a long int where the digital inputs from
		 * the class will be copied.
		 *
		 * \return 
		 *
		 * 0 if successful.
		 *
		 * -1 if the device needs to be updated before calling this method.
		 *
		 * -2 if inputs is a NULL pointer.
		 *
		 */
		
		virtual  int		GetDigitalInputs( long* inputs )            = 0;

		/**
		 * Set the device digital output state.
		 *
		 * \param output points to a long int, into which the device's 
		 * digital output state will be copied.
		 *
		 * \return 
		 *
		 * 0 if successful. 
		 *
		 * No error return values have been chosen yet.
		 *
		 */
		
		virtual  int		SetDigitalOutputs( long outputs )           = 0;

		/**
		 * Retrieve the device's gripper state.
		 * 
		 * \param grippers points to memory for a scalar double value,
		 * into which the current gripper state will be copied.
		 *
		 * \return 
		 * 
		 * 0 if successfull.
		 *
		 * -1 if the device needs to be updated before calling this method.
		 *
		 * -2 if grippers is a NULL pointer.
		 *
		 */
		
		virtual  int		GetGrippers( double* grippers )             = 0;

		/**
		 * Override the default _GraspMin and _GraspMax to calibrate graspers 
		 * 
		 * \param min specifies the minimum gripper extension, in radians.
		 *
		 * \param max specifies the maximim gripper extention, in radians.
		 *
		 * \return 
		 * 
		 * 0 if successful. 
		 * 
		 * No error return values have been defined.
		 *
		 */

		virtual  int		SetGraspMinMax( int min, int max)           = 0;

		/**
		 * Override the default _ToolLength, in mm. 
		 *
		 * \param length specifies the new tool length.
		 * 
		 * \return 
		 *
		 * 0 if successful. 
		 *
		 * No error return valiues have been defined.
		 *
		 */

		virtual  int		SetToolLength( double length)               = 0;
		/**
		 * Retrieve the device status.
		 * 
		 * \param status points to a long int, into which the current
		 * device status will be copied.
		 *
		 * \return 
		 *
		 * 0 if successful. 
		 *
		 * No error return values have been defined.
		 *
		 */
		virtual  int		GetStatus( long* status )                   = 0;

		/**
		 * Determine if the device's is in suspend mode.
		 *
		 * \return 
		 * 
		 * The method returns true if the device has been
		 * suspended.
		 *
		 */

		virtual  bool       GetIsSuspended( void )                      = 0;

	protected:

		// The constructor/destructor/initializer are protected because you have
		// to create IDevice3's with a IDevice3Factory
		ImmDevice3();

		virtual      ~ImmDevice3();

		virtual bool _Initialized( void )	= 0;	

};

#endif	// IMMERSION_DEVICE3_IMMDEVICE3_H