デバイス ドライバの作成

 
 
 

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

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

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

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

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

  1. デバイス ドライバで使用可能にするオプションのセットが含まれる、カスタム パラメータ セットを作成します。カスタム パラメータ セットの作成方法に関する詳細については、「アニメーション」を参照してください。

  2. .xsidevice ファイルで、<OptionsPreset>タグ内にオプションのカスタム パラメータ セットのファイル名(パスを含む)を指定します。

    デバイス ドライバがインスタンス化されると、新しいカスタム パラメータ セットが作成され、デバイス ドライバの下にネストされます。

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

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

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 に伝える

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] ツールを使用できます。

  1. コマンド プロンプトを開き、インストール フォルダの bin フォルダ(たとえば、C:¥Softimage¥Softimage_2013¥Application¥bin)に移動します。

  2. 以下の行を入力します。

    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 *