デバイスドライバの作成

デバイスドライバの記述とデバイスドライバの作成

デバイスドライバのライブラリファイルを作成する場合は、以下の点について考慮する必要があります。

Softimage 内でデバイスに何らかの処理を実行させるには、接続したデバイスから情報を取得する必要があります。情報を取得するには、ニーズやスタイルに応じて以下のいずれかの方法を使用できます。
- 数ミリ秒ごとにデバイスの状態をチェックするタイマプロシージャをセットアップする。
- デバイスの状態が変化するとコードを実行するイベントプロシージャを記述する。
デバイスドライバには、データが連続的に更新される多くのチャンネルを含めることができます。このため、デバイス情報をキャッシュして、ドライバのパフォーマンスを最大化する必要があります。

たとえば、ドライバがアクティブになった場合にチャンネルオブジェクトをキャッシュできます。この手順の詳細については、SDK のサンプル用ディレクトリ内の mousedriver フォルダに格納されている Mouse ドライバのサンプルを参照してください。

Softimage で確実に動作させるには、次の表に示すデバイスコールバックを使用します。

コールバック	説明
XSIDeviceOnInitialize	Softimage がデバイスをロードすると実行されます。デバイスマネージャがオン(アクティブ)になると、Softimage は各 XML デバイス記述ファイルを読み取り、検出した各ファイルに対応するデバイスのリストを作成します。
XSIDeviceOnUnInitialize	Softimage が終了時にデバイスをアンロードするか、またはデバイスマネージャがオフ(非アクティブ)になると実行されます。
XSIDeviceOnActivate	ユーザがドライバを接続する(デバイスマネージャで[アクティブ]オプションにチェックを入れるか、または[アニメート]ツールバーやメニューから[デバイス](Devices)[すべてのデバイスを有効](Enable All Devices)を選択する)と実行されます。
XSIDeviceOnDeActivate	ユーザがドライバを切断する(デバイスマネージャで[アクティブ]のチェックを外すか、または[アニメート]ツールバーやメニューから[デバイス](Devices)[すべてのデバイスを無効](Disable All Devices)を選択する)と実行されます。

Mouse ドライバのプラグインは、マウスの位置を使用して、X と Y の位置を操作します。この例では、上記のツールを使用してデバイスドライバを作成する方法について説明します。

ヒント:

Mouse プラグインのソースコードと .xsidevice ファイルは、SDK のサンプル用ディレクトリ内の mousedriver フォルダに格納されています。例:

<factory_path>¥XSISDK¥examples¥drivers¥MouseDriver

例: XSIDeviceOnActivate コールバックの使用

Mouse ドライバのソースコードでは、XSIDeviceOnActivate コールバックを使用して、マウスの位置の座標を設定しています。

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 );
}

例: イベントの使用(タイマループの代わり)

Mouse ドライバの例では、情報を更新するためのイベントプロシージャの使い方についても説明します。

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;

デバイスドライバにオプションを追加するには

デバイスドライバのウィンドウ上の[オプション]ボタンをクリックして、設定したオプションにアクセスできます。デバイスドライバプラグインにオプションを追加するには、以下の手順を実行します。

デバイスドライバで使用可能にするオプションのセットが含まれる、カスタムパラメータセットを作成します。カスタムパラメータセットの作成方法に関する詳細については、「アニメーション」を参照してください。
.xsidevice ファイルで、<OptionsPreset>タグ内にオプションのカスタムパラメータセットのファイル名(パスを含む)を指定します。

デバイスドライバがインスタンス化されると、新しいカスタムパラメータセットが作成され、デバイスドライバの下にネストされます。
デバイスドライバプラグインを記述する場合は、オブジェクトモデルを使用してオプションの値にアクセスできます。オブジェクトモデルを使用してカスタムパラメータセットにアクセスする方法の詳細については、「パラメータを操作する」を参照してください。

オブジェクトモデルからデバイスドライバにアクセスする

Softimage オブジェクトモデルには、以下のオブジェクトが含まれます。

Device オブジェクトは、Softimage のデバイスドライバを表します。ユーザインターフェイスで、デバイスドライバにアクセスするには、デバイスマネージャを使用します。デバイスマネージャを開くには、[アニメート]ツールバーで[ツール](Tools)[デバイス](Devices)を選択してください。
DeviceCollection を使用すれば、Softimage 内のすべてのデバイスドライバにアクセスできます。このオブジェクトは、デバイスマネージャのスクリプト機能に相当し、デバイスの有効化/無効化や追加/削除などを実行できます。
Channel オブジェクトは、デバイスとその Softimage への入力を結ぶワイヤを表します。各デバイスドライバには、チャンネルのセットが含まれているため、チャンネルごとにシーン内で異なる処理を実行できます。
ChannelCollection を使用すれば、デバイス内のすべてのチャンネルにアクセスできます。

注:
各デバイスドライバオブジェクトとその関数の詳細については、「コマンドおよびスクリプトリファレンス」を参照してください。

COM API の使い方に関する説明は、Mouse ドライバのサンプルを参照してください。

例: デバイスドライバ情報の取得

Application オブジェクト、ChannelCollection オブジェクト、および Device オブジェクトへのポインタを取得する必要があります。

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);

例: 特定のチャンネル情報の取得

Channel ID を使用してチャンネルを取得できます。この方法はコレクション全体で処理を繰り返す方法より高速です。

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);

補助ファイルを追加する

Softimage でドライバをサポートする際に役立つ、以下のような追加のファイルを作成できます。

デバイス プリセット: プリセットの値を指定して、既定でロードされるようにできます。たとえば、[アクション]フィールドにコマンド、[ターゲット]フィールドにコマンド名やプロシージャ名がそれぞれ指定されたチャンネルを持つプリセットを作成できます。

プリセットを保存およびロードする方法の詳細については、『Softimage ユーザガイド』を参照してください。
オプション のカスタムプロパティセット: デバイスの特別なオプションのリストを含むカスタムプロパティセットを作成できます。これらのオプションは、使用できる場合にデバイスのオプションのウィンドウに表示され、デバイスマネージャウィンドウで[オプション]ボタンをクリックして開くことができます。

詳細については、「デバイスドライバにオプションを追加するには」を参照してください。
ヘルプ ファイル: デバイスドライバの機能について説明する Web ページやヘルプファイルを作成する場合があります。この場合は、デバイスを配布する際に、ライブラリファイル、.xsidevice ファイル、プリセットファイル、および SPDL ファイルとともに HTML ファイルまたは WinHelp ファイルを含める必要があります。

デバイス情報を Softimage に伝える

Softimage は、.xsidevice ファイルで提供された情報に基づいてデバイスドライバのセットを作成します。Softimage の起動時に、.xsidevice ファイルを読み取り、指定された各デバイスのデバイスドライバを作成します。

XML デバイス記述ファイルについて

使用するデバイスに関する情報を Softimage に伝える場合は、デバイス記述ファイル(.xsidevice)内にすべての情報を入力する必要があります。 .xsidevice ファイルでは、以下の XML タグ構造が使用されます。

ヒント:

以下のサンプルで、タグ名をクリックすると、説明や設定可能な値が確認できます。

<?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>

Softimage は、これらのタグを使用して使用できるデバイスドライバのリストを作成します。デバイスマネージャウィンドウからこのリストにアクセスできます。

注:

Softimage で使用可能にするデバイスごとに、独立した .xsidevice ファイルを使用する必要があります。

XML デバイス記述タグのリファレンス

次の表に、デバイスの各 XML タグの一覧とその使い方を示します。

タグ名	説明
Device	デバイス記述の開始タグです。
FileVersion	ファイルのバージョンです。
DeviceName	使用するデバイスの名前です。この名前はデバイスをインスタンス化する際に使用されます。
DeviceType	デバイスのタイプです。取り得る値は以下のとおりです。 MIDI: Musical Instrument Digital Interface SOCK: Softimage\|3D 用のソケットドライバ Controller: Softimage を制御する入力デバイス Other: その他の種類のデバイス
DefaultPresetFilename	(オプション)デバイスのデフォルトプリセットのファイル名です。ドライバのインスタンスを作成する際に使用されます。
PluginFilename	組み込みドライバ(MIDI や SOCK)でない場合、PluginFilename はプラグインライブラリのファイル名になります。拡張子は、複数のプラットフォームでサポートされるためオプションです。
SupportMultiInstance	同じセッション内でデバイスのインスタンスを作成できる回数を制御します。取り得る値は以下のとおりです。 false: 作成できるインスタンスは 1 つだけです(既定)。 true: 複数のインスタンスを作成できます。
OtherInfo	(オプション)SOCK ドライバが使用するその他の情報です。内部情報や予約データを含めることもできます。
OptionsPreset	(オプション)デバイスオプションを含むカスタムパラメータセットのプリセットのファイル名です。オプションを使用すれば、キーパッドボタンのモードを作成することもできます。たとえば、キーダウンとキーアップまたはキーダウンのみでキャプチャセッションを起動するかどうかを切り替えるオプションを指定できます。
説明	(オプション)デバイスの説明です。

XML チャンネル記述タグのリファレンス

以下の表に、チャンネルの各 XML タグの一覧とその使い方を示します。

タグ名	説明
チャンネル	チャンネル記述の開始タグです。
ChannelName	チャンネルの名前です。
ChannelDescription	(オプション)チャンネルの説明です。
ChannelID	チャンネルの識別子です。負以外の数を設定する必要があります。注: 2 つのチャンネルで同じ ID を使用することはできません。
ChannelDirectionType	チャンネルの方向タイプです。取り得る値は以下のとおりです。 input: チャンネルは Softimage の入力です。 output: チャンネルは Softimage の出力です。 io: チャンネルは入力と出力です。
ChannelType	チャンネルのタイプです。取り得る値は以下のとおりです。 slider: オーディオ電子機器で一般的に使用されているスライダです。 button: 2 ステートボタンです(たとえば、ON または OFF)。 3states: 3 ステートボタンです(たとえば、LEFT、MIDDLE、RIGHT)。 jog: オーディオ機器で一般的に使用されているジョグ(またはダイアル)コントロールです。 unknown: その他のタイプ
ChannelMin	チャンネルのハードウェア最小値です。
ChannelMax	チャンネルのハードウェア最大値です。
SaveKeyOnSameValue	このタグは、スライダタイプのチャンネルに対してだけ使用されます。取り得る値は以下のとおりです。 true: モーションキャプチャの場合は、値が前の値と同じ(つまり、変更されなかった)場合であってもキーが保存されます。 false: 値が同じ場合、新しいキーは保存されません。これでパフォーマンスが向上します。 (既定)

XML デバイス記述ファイルを検証する

Softimage を起動すると、各 XML デバイス記述ファイルが読み取られ、そのファイルの有効性がチェックされます。すべての .xsidevice ファイルが有効な場合は、デバイスマネージャから[追加](Add)ボタンをクリックすると、[デバイスドライバの選択](Select a Device Driver)ダイアログボックスに各ドライバのリストが表示されます。

しかし、1 つ以上の .xsidevice ファイルが有効でない場合は、デバイスマネージャをアクティブにすると、ファイルの問題点を特定できるメッセージが Script Editor ウィンドウの履歴ログに表示されます。たとえば、閉じるタグを使用しなかった場合は、次のメッセージが表示されます。

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

デバイスのタイプを省略する(タグの<DeviceType>セットを設定しない)と、このメッセージが表示されます。

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

'Error parsing the device:

	'- Device plugin filename is empty

'"

Softimage を使わずに XML デバイス記述ファイルを検証するには

.xsidevice ファイルの有効性を検証する場合は、以下の手順で [deviceparser] ツールを使用できます。

コマンドプロンプトを開き、インストールフォルダの bin フォルダ(たとえば、C:¥Softimage¥Softimage_2013¥Application¥bin)に移動します。
以下の行を入力します。
deviceparser.exe -list <ファイル名>
注:
このツールは、一度に 1 つのファイルに対してしか使用できません。

ファイルが有効な場合は、デバイスおよびすべての有効なチャンネルに関する情報の要約に続いて、以下のメッセージが表示されます。
```
Parsing device desription file: [$factory]\Data\Devices\[filename].xsidevice

	-- Succeeded
```
ファイルが無効な場合は、次のようなメッセージが表示されます。
```
Parsing device desription file: [$factory]\Data\Devices\[filename].xsidevice
Error Parsing the DeviceInfo: mismatched tag at line ** col *
```

デバイス ドライバの作成

デバイスドライバの作成