Writing the Device DriverCreating the Device Driver

When you create the library file for your device driver, there are a few things that you need to think about:

• You need to retrieve information from the connected device in order to make the device drive something in Softimage. To do this, you can use one of the following strategies according to your needs and style:

  • Set up a timer procedure that checks the status of the device every few milliseconds .

  • Write event procedures that run code whenever there is a change in the status of the device.

• Device drivers can contain many channels with data that are continuously being refreshed. For this reason, you should cache the device information to maximize your driver's performance.

  For example, you can cache the channel object when the driver is activated. For details on how to do this, see the Mouse Driver example under the mousedriver directory in the SDK example directory.

• To hook into Softimage, use the device callbacks listed in the table below.

  Callback	Description
  XSIDeviceOnInitialize	Fired when Softimage loads the device. When the Device Manager turned on (activated), Softimage reads each XML device description file and builds a list of devices corresponding to each file it finds.
  XSIDeviceOnUnInitialize	Fired when Softimage unloads the device when quitting or when the Device Manager is turned off (deactivated).
  XSIDeviceOnActivate	Fired when the user connects the driver by checking the Active option in the DeviceManager or selecting DevicesEnable All Devices from the Animate toolbar or menu.
  XSIDeviceOnDeActivate	Fired when the user disconnects the driver by unchecking the Active option in the DeviceManager or selecting DevicesDisable All Devices from the Animate toolbar or menu.

The Mouse driver plug-in uses the mouse's position to drive the X and Y position. This example illustrates how to use the tools mentioned above to create your device driver.

extern "C" HRESULT WINAPI XSIDeviceOnActivate()
{
	ApplicationPtr		l_pApp;

	l_pApp.CreateInstance("XSI.Application");

#ifdef DEBUG
	l_pApp->LogMessage(L"Connecting Mouse Device...", siInfo);
#endif 

	//-----------------------------------------------------
	// Get the mouse position 
	//-----------------------------------------------------
	POINT		l_ptClientMousePos;
	::GetCursorPos( &l_ptClientMousePos );

	//-----------------------------------------------------
	//-----------------------------------------------------
	if (g_pDeviceinfo.m_pChannelX == 0 || g_pDeviceinfo.m_pChannelY ==0)
	{
		// here is where the information from the device is initialized
		// (the actual code that goes here appears in below)
	}

	//-----------------------------------------------------
	// Start a timer  using the parameter named :
	// PollingInterval (20 msec by default)
	//-----------------------------------------------------
#ifdef _TIMER_BASED_EXAMPLE	
	ULONG l_ulPollingInterval = 20;
	m_idTimer = ::SetTimer( NULL, 1, l_ulPollingInterval, (TIMERPROC)fnTimerProc ) ;
#endif 

	g_currentHook = SetWindowsHookEx(WH_MOUSE_LL, (HOOKPROC)MyMouseProc, g_hInstance,0);

	return S_OK;
}

VOID CALLBACK fnTimerProc( HWND /*hwnd*/, UINT /*uMsg*/, UINT /*idEvent*/, DWORD /*dwTime*/ )
{
	ApplicationPtr		l_pApp;
	l_pApp.CreateInstance("XSI.Application");

	//-----------------------------------------------------
	// Get the mouse position 
	//-----------------------------------------------------
	POINT		l_ptClientMousePos;
	::GetCursorPos( &l_ptClientMousePos );

	// Set the X channel
	CComVariant l_varX( (DOUBLE)l_ptClientMousePos.x );
	CComVariant l_varY( (DOUBLE)l_ptClientMousePos.y );

	g_pDeviceinfo.m_pChannelX->put_Value( l_varX );
	g_pDeviceinfo.m_pChannelY->put_Value( l_varY );
}

LRESULT CALLBACK MyMouseProc
(
  int nCode,      // hook code
  WPARAM wParam,  // message identifier
  LPARAM lParam   // mouse coordinates
)
{
	if (wParam == WM_MOUSEMOVE)
	{
		MOUSEHOOKSTRUCT *l_sMouseInfo = (MOUSEHOOKSTRUCT *)lParam;

		if (g_pDeviceinfo.m_pChannelX)
		{
			// Set the X an Y channels
			CComVariant l_varX( (DOUBLE)l_sMouseInfo->pt.x );
			CComVariant l_varY( (DOUBLE)l_sMouseInfo->pt.y );

			g_pDeviceinfo.m_pChannelX->put_Value( l_varX );
			g_pDeviceinfo.m_pChannelY->put_Value( l_varY );
		}
	}
	else if (wParam == WM_LBUTTONDOWN)
	{
		if (g_pDeviceinfo.m_pChannelLB)
		{
			// Trigger the command on the Left Button
			g_pDeviceinfo.m_pChannelLB->put_Value( CComVariant(1) );
		}
	}
	else if (wParam == WM_MBUTTONDOWN)
	{
		if (g_pDeviceinfo.m_pChannelMB)
		{
			// Trigger the command on the Middle Button
			g_pDeviceinfo.m_pChannelMB->put_Value( CComVariant(1) );
		}
	}
	else if (wParam == WM_RBUTTONDOWN)
	{
		if (g_pDeviceinfo.m_pChannelRB)
		{
			// Trigger the command on the Right Button
			g_pDeviceinfo.m_pChannelRB->put_Value( CComVariant(1) );
		}
	}

	return CallNextHookEx(g_currentHook,nCode,wParam,lParam);
}

static _DeviceInfo g_pDeviceinfo;

Accessing Device Drivers through the Object Model

The Softimage object model contains these objects:

• The Device object represents a device driver in Softimage. In the User Interface, device drivers are accessible through the Device Manager, which you can open with ToolsDevices on the Animate toolbar.

• The DeviceCollection gives access to all device drivers in Softimage. This is the scripting equivalent of the Device Manager, in which you can activate or deactivate a device, add or remove devices, etc.

• The Channel object represents the wire between a device and its input into Softimage. Each device driver has a set of channels and each channel can drive something different in the scene.

• The ChannelCollection gives access to all channels in the device.

  Note

  For more information on the specifics of each device driver object and their functions, see the Commands and Scripting Reference.

To illustrate how to use the COM API, you can return to the Mouse driver example.

HRESULT					l_hr;
XSIApplicationPtr		l_xsiApp(l_pApp);
ChannelCollectionPtr	l_pChannels; 
DevicePtr				l_pDevice;

// Get the DeviceCollection from the Application
DeviceCollectionPtr		l_pDeviceManager;
l_hr = l_xsiApp->get_Devices(&l_pDeviceManager);
AssertAndReturn(l_hr);

// Get the "Mouse" Device object
l_hr = l_pDeviceManager->get_Item( CComVariant(L"Mouse"), &l_pDevice );
AssertAndReturn(l_hr);

// Get all channels in the Mouse device
l_hr = l_pDevice->get_Channels( &l_pChannels );
AssertAndReturn(l_hr);

// Iterate through all channels in the Mouse device
l_hr = l_pChannels->get_Item( CComVariant(0), &g_pDeviceinfo.m_pChannelX);
AssertAndReturn(l_hr);

l_hr = l_pChannels->get_Item( CComVariant(1), &g_pDeviceinfo.m_pChannelY);
AssertAndReturn(l_hr);

l_hr = l_pChannels->get_Item( CComVariant(2), &g_pDeviceinfo.m_pChannelLB);
AssertAndReturn(l_hr);
l_hr = l_pChannels->get_Item( CComVariant(3), &g_pDeviceinfo.m_pChannelMB);
AssertAndReturn(l_hr);

l_hr = l_pChannels->get_Item( CComVariant(4), &g_pDeviceinfo.m_pChannelRB);
AssertAndReturn(l_hr);

l_hr = l_pDevice->get_Channel( 1, &g_pDeviceinfo.m_pChannelX);
AssertAndReturn(l_hr);

l_hr = l_pDevice->get_Channel( 2, &g_pDeviceinfo.m_pChannelY);
AssertAndReturn(l_hr);

Communicating the Device Information to Softimage

<?xml version="1.0"?>
<Device>
	<FileVersion>...</FileVersion>
	<DeviceName>...</DeviceName>
	<DeviceType>...</DeviceType>
	<DefaultPresetFilename>...</DefaultPresetFilename>
	<PluginFilename>...</PluginFilename>
	<SupportMultiInstance>...</SupportMultiInstance>
	<OtherInfo>...</OtherInfo>
	<OptionsPreset>...</OptionsPreset>
	<Description>
		<![CDATA[ 	...	 ]]>
	</Description>
	<Channel>
		<ChannelName>...</ChannelName>
		<ChannelDescription>
			<![CDATA[ 	...	 ]]>
		</ChannelDescription>
		<ChannelID>...</ChannelID>
		<ChannelDirectionType>...</ChannelDirectionType>
		<ChannelType>...</ChannelType>
		<ChannelMin>...</ChannelMin>
		<ChannelMax>...</ChannelMax>
		<SaveKeyOnSameValue>...</SaveKeyOnSameValue>
	</Channel>
	<Channel>
		...
	</Channel>
	...
</Device>

'ERROR : "2000 - Error Parsing the DeviceInfo: mismatched tag at line ** col *'"

'ERROR : "2000 - Error parsing the Device [device_name], File: [$factory]\Data\Devices\[filename].xsidevice

'Error parsing the device:

	'- Device plugin filename is empty

'"