デバイス ドライバのライブラリ ファイルを作成する場合は、以下の点について考慮する必要があります。
Softimage 内でデバイスに何らかの処理を実行させるには、接続したデバイスから情報を取得する必要があります。 情報を取得するには、ニーズやスタイルに応じて以下のいずれかの方法を使用できます。
デバイス ドライバには、データが連続的に更新される多くのチャンネルを含めることができます。 このため、デバイス情報をキャッシュして、ドライバのパフォーマンスを最大化する必要があります。
たとえば、ドライバがアクティブになった場合にチャンネル オブジェクトをキャッシュできます。 この手順の詳細については、SDK のサンプル用ディレクトリ内の mousedriver フォルダに格納されている Mouse ドライバのサンプルを参照してください。
Softimage で確実に動作させるには、次の表に示すデバイス コールバックを使用します。
Mouse ドライバのプラグインは、マウスの位置を使用して、X と Y の位置を操作します。 この例では、上記のツールを使用してデバイス ドライバを作成する方法について説明します。
<factory_path>¥XSISDK¥examples¥drivers¥MouseDriverMouse ドライバのソース コードでは、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);
Softimage でドライバをサポートする際に役立つ、以下のような追加のファイルを作成できます。
デバイス プリセット: プリセットの値を指定して、既定でロードされるようにできます。 たとえば、[アクション]フィールドにコマンド、[ターゲット]フィールドにコマンド名やプロシージャ名がそれぞれ指定されたチャンネルを持つプリセットを作成できます。
オプション のカスタム プロパティ セット: デバイスの特別なオプションのリストを含むカスタム プロパティ セットを作成できます。 これらのオプションは、使用できる場合にデバイスのオプションのウィンドウに表示され、デバイス マネージャ ウィンドウで[オプション]ボタンをクリックして開くことができます。
詳細については、「デバイス ドライバにオプションを追加するには」を参照してください。
ヘルプ ファイル: デバイス ドライバの機能について説明する Web ページやヘルプ ファイルを作成する場合があります。 この場合は、デバイスを配布する際に、ライブラリ ファイル、.xsidevice ファイル、プリセット ファイル、および SPDL ファイルとともに HTML ファイルまたは WinHelp ファイルを含める必要があります。
Softimage は、.xsidevice ファイルで提供された情報に基づいてデバイス ドライバのセットを作成します。Softimage の起動時に、.xsidevice ファイルを読み取り、指定された各デバイスのデバイス ドライバを作成します。
使用するデバイスに関する情報を 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 は、これらのタグを使用して使用できるデバイス ドライバのリストを作成します。デバイス マネージャ ウィンドウからこのリストにアクセスできます。
次の表に、デバイスの各 XML タグの一覧とその使い方を示します。
以下の表に、チャンネルの各 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 '"
.xsidevice ファイルの有効性を検証する場合は、以下の手順で [deviceparser] ツールを使用できます。
コマンド プロンプトを開き、インストール フォルダの bin フォルダ(たとえば、C:¥Softimage¥Softimage_2013¥Application¥bin)に移動します。
ファイルが有効な場合は、デバイスおよびすべての有効なチャンネルに関する情報の要約に続いて、以下のメッセージが表示されます。
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 *