Platform SDK: DirectX |
DirectInput は、バッファリング データと直接データの 2 種類のデータを供給する。バッファリング データは、アプリケーションが取得するまで格納されているイベントのレコードである。直接データは、デバイスの現在の状態のスナップショットである。
直接データは、デバイスの現在の状態だけに関心のあるアプリケーションで使用することが考えられる。たとえば、ジョイスティックの現在位置と、1 つ以上のボタンの状態に反応するフライト コンバット シミュレーションなどである。バッファリング データは、状態よりもイベントを重要視する場合に選択するとよい。たとえば、マウスの動きやボタンのクリックに反応するアプリケーションなどである。両方のタイプのデータを使用することもできる。たとえば、ジョイスティック軸では直接データを取得して、ボタンではバッファリング データを取得する場合などである。
DirectX SDK で提供されている DirectInput QuickTest アプリケーションでは、デバイスの直接データとバッファリング データの両方を見ることができる。アプリケーション ウィンドウでデバイスを作成した後、[Mode] ページでそのプロパティを設定する。すると、[Data] ページの左側に直接データ、右側にバッファリング データが表示される。
アプリケーションは、IDirectInputDevice7::GetDeviceState メソッドを呼び出すことで、直接データを取得する。名前が表すとおり、このメソッドはデバイスの現在の状態を返す。たとえば、各ボタンがアップ状態かダウン状態か、などである。このメソッドは、現在の状態と以前の状態を比較して得られる暗黙の情報を除いて、最後の呼び出し以降にデバイスに起きたイベントに関するデータは、まったく提供しない。GetDeviceState に対する最後の呼び出しから現在の呼び出しまでの間に、ユーザーがボタンを押したり離したりしていても、アプリケーションはそのことに関して何も認識しない。他方、ボタンを押したままにしていると、GetDeviceState は、ユーザーがボタンを離すまで「ボタン ダウン」を報告し続ける。
このデバイス状態の報告は、WM_LBUTTONDOWN のような一度限りのメッセージによる Windows のイベント報告とは異なり、Win32 の GetKeyboardState 関数の報告に類似している。GetDeviceState を使用してデバイスをポーリングする場合には、ボタン クリック、ダブルクリック、または単一のキー ストロークの区別をプログラムで判断しなければならず、また、アプリケーションがボタン ダウン状態またはキー ダウン状態に対し、不適切なタイミングで応答し続けることのないように適切に処理しなければならない。
バッファリング データの場合、イベントは、プログラムが処理を開始できる状態になるまで格納されている。ボタンやキーが押されたり、軸が移動されたりするたびに、そのイベントに対する情報がバッファ中の DIDEVICEOBJECTDATA 構造体に置かれる。バッファがオーバーフローすると、新しいデータは失われる。アプリケーションがバッファを読み出すには、IDirectInputDevice7::GetDeviceData を呼び出す。一度に任意の数の項目を読み出すことができる。
項目を読み出すと、通常は、バッファからその項目が消去されるが、消去無しピーキングも選択できる。
バッファリング データを取得するには、まず IDirectInputDevice7::SetProperty メソッドでバッファ サイズを設定する必要がある (「デバイス プロパティ」を参照すること)。バッファ サイズの設定は、デバイスを最初に取得する前に行う。効率上の理由から、デフォルトのバッファ サイズはゼロである。この値を変更しない限り、バッファリング データを取得することはできない。バッファ サイズはバイト単位やワード単位ではなく、デバイスのタイプに対応したデータの項目単位でカウントされる。
GetDeviceData メソッドを呼び出した後は、pdwInOut パラメータ値をチェックする必要がある。バッファから取り出される項目数は、この変数に返される。
注 : アナログ ジョイスティックなど、割り込みを生成しないデバイスの場合、IDirectInputDevice7::Poll メソッドが呼び出されるまで、DirectInput はいかなるデータも取得しない。詳細については、「ポーリングとイベント」を参照すること。
バッファリング データを取得する例については、IDirectInputDevice7::GetDeviceData を参照すること。
アプリケーションは、以下のメソッドのいずれかを呼び出すことで、直接データを取得する。
名前が表すとおり、これらの各メソッドはデバイスの現在の状態を返す。たとえば、各ボタンがアップ状態かダウン状態か、などである。このメソッドは、現在の状態と以前の状態を比較して得られる暗黙の情報を除いて、最後の呼び出し以降にデバイスに起きたイベントに関するデータは、まったく提供しない。各メソッドに対する最後の呼び出しから現在の呼び出しまでの間に、ユーザーがボタンを押したり離したりしていても、アプリケーションはそのことに関して何も認識しない。他方、ボタンを押したままにすると、メソッドは、ユーザーがボタンを離すまで「ボタン ダウン」を報告し続ける。
このデバイス状態の報告は、Click や Keydown のような一度限りのイベントによる Visual Basic のイベント報告とは異なっている。GetDeviceState メソッドのいずれかを使用してデバイスをポーリングする場合には、ボタン クリック、ダブルクリック、または単一のキー ストロークの区別をプログラムで判断しなければならず、また、アプリケーションがボタン ダウン状態またはキー ダウン状態に対し、不適切なタイミングで応答し続けることのないように適切に処理しなければならない。
バッファリング データの場合、イベントは、プログラムが処理を開始できる状態になるまで格納されている。ボタンやキーが押されたり、軸が移動されたりするたびに、そのイベントに対する情報がバッファ中の DIDEVICEOBJECTDATA 型に置かれる。アプリケーションがバッファを読み取るには、DirectInputDevice.GetDeviceData を呼び出す。一度に任意の数の項目を読み出すことができる。
項目を読み出すと、通常は、バッファからその項目が消去されるが、DIGDD_PEEK フラグを設定すると、削除せずに取得することも選択できる。
バッファリング データを取得するには、まず DirectInputDevice.SetProperty メソッドでバッファ サイズを設定する必要がある (「デバイス プロパティ」を参照すること)。バッファ サイズの設定は、デバイスを最初に取得する前に行う。効率上の理由から、デフォルトのバッファ サイズはゼロである。この値を変更しない限り、バッファリング データを取得することはできない。バッファ サイズはバイト単位やワード (WORD) 単位ではなく、デバイスのタイプに対応したデータの項目単位でカウントされる。
GetDeviceData の戻り値は、バッファから取得された項目数を示している。バッファがオーバーフローした場合、データは返されず、GetDeviceData はエラーを発生する。このエラーにより、アプリケーションが捕捉される。
注 : アナログ ジョイスティックなど、割り込みを生成しないデバイスの場合、DirectInputDevice.Poll メソッドを呼び出すまで、DirectInput はいかなるデータも取得しない。詳細については、「ポーリングとイベント」を参照すること。
参照