Microsoft DirectX 8.0 |
システム リソースの競合を解決する。
フィルタ グラフ マネージャがこのインターフェイスを公開する。フィルタでは、このインターフェイスを使用して、ほかのオブジェクトが使用する可能性があるリソースを要求できる。たとえば、オーディオ レンダリング フィルタでは、このインターフェイスを使用して、ウェーブ出力デバイスの競合を解決し、サウンドとフォーカスを一致させる。
通常、アプリケーションでこのインターフェイスを使用することはない。
オブジェクトでは、既存のリソース間で起きる可能性がある競合を、このインターフェイスを使用して解決できる。まず、オブジェクトは、インターフェイスにリソースを登録し、必要なときにそのリソースを要求する。オブジェクトは、ユーザーのフォーカスが変化するたびに、フィルタ グラフ マネージャに通知しなければならない。これによって、フィルタ グラフ マネージャは、競合するデバイスをユーザーのフォーカスがあるオブジェクトに切り替えることができる。
このインターフェイスを使用するオブジェクトは、IResourceConsumer インターフェイスを実装する必要がある。IResourceConsumer は、リソースが利用可能になったとき、または取得したリソースをオブジェクトが解放すべきときに、フィルタ グラフ マネージャがオブジェクトに通知するためのコールバック メカニズムを提供する。
vtable 順のメソッド
IUnknown メソッド 説明 QueryInterface サポートされているインターフェイスへのポインタを取得する。 AddRef 参照カウントをインクリメントする。 Release 参照カウントをデクリメントする。 IResourceManager メソッド 説明 Register 単独の名前付きリソースをリソース マネージャに登録する。 RegisterGroup 名前付きリソース グループをリソース マネージャに登録する。 RequestResource 所定の登録済みリソースの使用を要求する。 NotifyAcquire リソース取得の試みが完了したことをリソース マネージャに通知する。 NotifyRelease リソース コンシューマがリソースを解放したことをリソース マネージャに通知する。 CancelRequest リソース要求を取り消す。 SetFocus 特定のオブジェクトにユーザーのフォーカスが与えられたことをリソース マネージャに通知する。 ReleaseFocus 現在のフォーカス オブジェクトが指定された場合に、リソース マネージャ内のフォーカス オブジェクトを NULL に設定する。
リソース要求を取り消す。
構文
HRESULT CancelRequest( LONG idResource, IResourceConsumer *pConsumer );
パラメータ
- idResource
- [in] 待機中の要求のリソース識別子。
- pConsumer
- [in] 要求元の IResourceConsumer インターフェイスへのポインタ。
戻り値
実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL 失敗。 E_POINTER Null ポインタ引数。 E_INVALIDARG 無効な引数。 E_NOTIMPL メソッドがサポートされていない。 S_OK または NOERROR 成功。
注意
要求したリソースが受け取り前に不要になった場合、要求元の IResourceConsumer オブジェクトはこのメソッドを呼び出す必要がある。また、リソースを既に受け取った場合には、IResourceManager::NotifyRelease メソッドを使用する必要がある。
リソース取得の試みが完了したことをリソース マネージャに通知する。
構文
HRESULT NotifyAcquire( LONG idResource, IResourceConsumer *pConsumer, HRESULT hr );
パラメータ
- idResource
- [in] 登録済みリソースに対応するトークン。
- pConsumer
- [in] リソースを要求しているオブジェクトの IResourceConsumer インターフェイスへのポインタ。
- hr
- [in] 取得の成功を示す値。リソースが取得された場合は S_OK、それ以外の場合はエラー値。
戻り値
実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL 失敗。 E_POINTER Null ポインタ引数。 E_INVALIDARG 無効な引数。 E_NOTIMPL メソッドがサポートされていない。 S_OK または NOERROR 成功。
注意
このメソッドは、IResourceConsumer::AcquireResource メソッドが S_FALSE 値を返した後に使用する。S_FALSE 値は、取得が非同期に行われる (つまり、コールバック メカニズムで処理される) ことを示す。hr パラメータが S_OK の場合、リソース マネージャは、そのリソースが呼び出し元に保持されているものと見なす。hr パラメータが S_OK でない場合、リソース マネージャは、リソース取得の試みが失敗し、そのリソースが別の機会にまた割り当てられるものと見なす。
IResourceConsumer がリソースを解放したことをリソース マネージャに通知する。
構文
HRESULT NotifyRelease LONG idResource, IResourceConsumer *pConsumer, BOOL bStillWant );
パラメータ
- idResource
- [in] リソースのトークン。
- pConsumer
- [in] リソースを解放しようとしているオブジェクトへのポインタ。
- bStillWant
- [in] リソースがまだ必要かどうかを指定するフラグ。次に利用可能になったときにまだリソースが必要な場合は、TRUE を設定する。リソースが必要でない場合は、FALSE を設定する。
戻り値
実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL 失敗。 E_POINTER Null ポインタ引数。 E_INVALIDARG 無効な引数。 E_NOTIMPL メソッドがサポートされていない。 S_OK または NOERROR 成功。
注意
このメソッドは、IResourceConsumer::ReleaseResource メソッドへの応答として使用するか、またはリソースを使い終わったときに使用する。
単独の名前付きリソースをリソース マネージャに登録する。
構文
HRESULT Register( LPCWSTR pName, LONG cResource, LONG *plToken );
パラメータ
- pName
- [in] 名前付きリソース。
- cResource
- [in] リソース数。
- plToken
- [out] 返されたトークンへのポインタ。このトークンが識別するリソースを、これ以降の呼び出しで使用する。
戻り値
実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL 失敗。 E_POINTER Null ポインタ引数。 E_INVALIDARG 無効な引数。 E_NOTIMPL メソッドがサポートされていない。 S_OK または NOERROR 成功。
注意
このメソッドは、複数のリソースを格納できる名前付きリソースを登録し、このリソースを要求するときに使用するトークンを返す。リソースが既に登録されていてもエラーにはならない。登録済みの数より少ない数を cResource パラメータに渡すと、リソースの割り当てがが新しい数に変更される。リソースの登録を解除するには、cResource に 0 を渡す。
名前付きリソース グループをリソース マネージャに登録する。
構文
HRESULT RegisterGroup( LPCWSTR pName, LONG cResource, LONG *palTokens, LONG *plToken );
パラメータ
- pName
- [in] 名前付きリソース グループ。
- cResource
- [in] グループに含まれるリソースの数。
- palTokens
- [in, size_is(cResource)] グループに含まれるリソースの配列へのポインタ。
- plToken
- [out] 返されたグループ リソース識別子へのポインタ。
戻り値
実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL 失敗。 E_POINTER Null ポインタ引数。 E_INVALIDARG 無効な引数。 E_NOTIMPL メソッドがサポートされていない。 S_OK または NOERROR 成功。
現在のフォーカス オブジェクトが指定された場合に、リソース マネージャ内のフォーカス オブジェクトを NULL に設定する。
構文
HRESULT ReleaseFocus( IUnknown *pFocusObject );
パラメータ
- pFocusObject
- [in] フォーカス オブジェクトへのポインタ。
戻り値
実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL 失敗。 E_POINTER Null ポインタ引数。 E_INVALIDARG 無効な引数。 E_NOTIMPL メソッドがサポートされていない。 S_OK または NOERROR 成功。
注意
このメソッドは、フォーカス オブジェクトを破棄しようとしているとき、フォーカスがもう参照されないようにするために使用する。
所定の登録済みリソースの使用を要求する。
構文
HRESULT RequestResource( LONG idResource, IUnknown *pFocusObject, IResourceConsumer *pConsumer );
パラメータ
- idResource
- [in] リソース登録時に取得されたリソースのトークン。
- pFocusObject
- [in] 要求に関連付けられたフォーカス オブジェクトの IUnknown インターフェイス (通常はフィルタの IUnknown インターフェイス) へのポインタ。
- pConsumer
- [in] リソースを要求しているオブジェクトの IResourceConsumer インターフェイスへのポインタ。
戻り値
HRESULT 値を返す。要求したリソースが返された場合は、S_OK を返す。リソースが利用できない場合は、S_FALSE を返す。この場合、リソース マネージャは、リソースが利用可能になった時点で、要求元オブジェクトをコールバックする。それ以外の戻り値はすべてエラーである。
注意
そのリソースへの要求が複数ある場合、リソース マネージャは、個々の要求で渡されたフォーカス オブジェクトを、最新の IResourceManager::SetFocus メソッドで渡されたフォーカス オブジェクトと比較することによって、優先順位を決定する。
要求は次の優先順位で処理される。
- 最新の SetFocus メソッドとまったく同じフォーカス オブジェクトに関する要求。
- フォーカス オブジェクトとソース フィルタを共有する要求。
- フォーカス オブジェクトとフィルタ グラフを共有する要求。
- フォーカスと同じ処理からの要求。
この優先順位を調べるとき、リソース マネージャは、フォーカス オブジェクトの QueryInterface を使用して IID_IFilter を照会する。見つかった場合、リソース マネージャは、IBaseFilter メソッドを使用して、フィルタ グラフを調べ、現在のフォーカス オブジェクトと共通のソース フィルタを探す。
フィルタでは、そのフィルタの IUnknown インターフェイスを pFocusObject パラメータに渡さなければならない。フィルタ グラフ マネージャは、フォーカス オブジェクトを調べるとき、フィルタをフィルタ グラフと比較して、共通のソース フィルタまでフィルタをたどろうとする。
フォーカス オブジェクトは、要求の有効期間全体を通して有効である必要がある。要求の有効期間とは、IResourceManager::CancelRequest メソッドが呼び出されるか、または bStillWant パラメータに FALSE を設定して IResourceManager::NotifyRelease メソッドが呼び出されるまでの期間である。
特定のオブジェクトにユーザー フォーカスが与えられたことをリソース マネージャに通知する。
構文
HRESULT SetFocus( IUnknown *pFocusObject );
パラメータ
- pFocusObject
- [in] ユーザー フォーカスを与えられたオブジェクトへのポインタ。
戻り値
実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL 失敗。 E_POINTER Null ポインタ引数。 E_INVALIDARG 無効な引数。 E_NOTIMPL メソッドがサポートされていない。 S_OK または NOERROR 成功。
注意
DirectShow では、通常、フォーカスを受け取ったウィンドウを所有するビデオ レンダラが、ユーザー フォーカスを与えられるオブジェクトである。リソース マネージャは、リソース要求に次の順序で優先順位を与える。
- pFocusObject パラメータで指定されたフォーカス オブジェクトに関する要求。
- フォーカス オブジェクトとソース フィルタを共有する要求。
- フォーカス オブジェクトとフィルタ グラフを共有する要求。
- フォーカスと同じ処理からの要求。
リソース マネージャは、フォーカスが設定されてから ReleaseFocus が呼び出されるまで、フォーカス オブジェクトを維持しなければならない。つまり、このメソッドを呼び出したら、フォーカス オブジェクトの IUnknown インターフェイスが無効になる前に、ReleaseFocus を使用する必要がある。ただし、別のオブジェクトからそれまでに確実に SetFocus が呼び出される場合はこの限りではない。フォーカス オブジェクト上には参照カウントが保持されない。
リソース マネージャは、置き換えられるか取り消されるまでこのポインタを保持し、リソース競合の解決に使用する。リソース マネージャは、少なくとも QueryInterface を使用して IBaseFilter インターフェイスを照会し、見つかった場合はこのインターフェイスのメソッドを使用する。IBaseFilter のメソッドは、オーディオ レンダラが 2 つある場合に、どちらを使用するか決定する (フォーカス オブジェクトとソース フィルタを共有するものを選ぶ) ために呼び出され、さらに、2 つのオブジェクトが同じフィルタ グラフに含まれるかどうかを判断するために呼び出される。