Microsoft DirectX 8.0

IOverlay インターフェイス

IOverlay インターフェイスは、ビデオを正しいウィンドウ位置に配置した状態で、フィルタからビデオ メモリに直接書き込むために必要な情報を提供する。このインターフェイスは、ビデオ レンダラ入力ピン上に実装され、アップストリーム フィルタ (主にビデオ デコンプレッサ フィルタ) の IOverlayNotify メソッドを呼び出して、ビデオ ウィンドウへの変更を通知することにより、そのフィルタと通信する。

このインターフェイスは、DirectDraw® のオーバーレイ能力とは無関係である。Microsoft のビデオ レンダラは、IMemInputPin インターフェイスを通じて受け取ったデータを、DirectDraw オーバレイを使用して描画する (ただし利用可能な場合)。このインターフェイスは、IMemInputPin の代わりに使用され、レンダラの描画能力をバイパスするが、ディスプレイのその他プロパティの通知を受ける必要がある、すべてのアップストリーム フィルタに、通知のサポートを提供することを目的としている。

IOverlay インターフェイスと IOverlayNotify インターフェイスの連携の詳細については、「IOverlayNotify インターフェイス」を参照すること。

レンダリング ウィンドウへの変更の非同期通知の詳細については、「IOverlayNotify2 インターフェイス」を参照すること。

このインターフェイスは、Microsoft® DirectShow® ビデオ レンダリング フィルタに実装される。また、必要に応じて、代替ビデオ レンダリング フィルタに実装することもできる。その場合には、このインターフェイスを実装して、フレーム バッファに直接書き込むフィルタ、またはオーバーレイを配置しようとするフィルタに、ビデオをどこに表示すればよいかを知らせる。このインターフェイスを実装するには、ビデオ プロパティの変更の通知も含め、描画を行っているフィルタの IOverlayNotify インターフェイスまたは IOverlayNotify2 インターフェイスのメソッドを使用する準備が、レンダラにできている必要がある。

DirectShow のウィンドウ ベースのレンダラは、IMemInputPin インターフェイスと IOverlay インターフェイスの両方をサポートする。これら 2 つのインターフェイスは互いに排他である。フィルタでは、サブタイプが MEDIASUBTYPE_Overlay のメディア タイプを接続中に提供することにより、IOverlay 転送 インターフェイスの方を使用する。接続後、フィルタは問題なく IOverlay インターフェイスを取得および使用できる。フィルタがほかのビデオ フォーマット (MEDIASUBTYPE_RGB8 など) で接続する場合、IOverlay を通じて呼び出そうとすると、VFW_E_NOT_OVERLAY_CONNECTION が返される。

ビデオ オーバーレイのプロパティを制御する必要があり、ビデオ データ自体の表示を処理しようとするアップストリーム フィルタからは、このインターフェイスのメソッドを使用すること。このインターフェイスは、通常、ビデオ ハードウェアへの代替接続を持つハードウェア ビデオ デコーダで使用される。

vtable 順のメソッド

IUnknown メソッド説明
QueryInterface サポートされているインターフェイスへのポインタを返す。
AddRef 参照カウントをインクリメントする。
Release 参照カウントをデクリメントする。
IOverlay メソッド説明
GetPalette 現在のパレットを取得する。
SetPalette パレットを設定する。
GetDefaultColorKey デフォルトのカラー キーを取得する。
GetColorKey 現在アクティブなカラー キーの識別子を取得する。
SetColorKey カラー キーを変更する。
GetWindowHandle ウィンドウ ハンドルを返す。
GetClipList クリップ リストを取得する。
GetVideoPosition 現在のビデオの転送元矩形および転送先矩形を取得する。
Advise オーバーレイ イベント用のアドバイズ リンクを設定する。
Unadvise アドバイズ リンクを終了する。

IOverlay::Advise

IOverlay インターフェイス

dwInterests パラメータで指定されたオーバーレイ イベント用のアドバイズ リンクを設定する。

構文

HRESULT Advise(

  IOverlayNotify *pOverlayNotify,
  DWORD dwInterests
  );

パラメータ

pOverlayNotify
[in] 通知インターフェイスへのポインタ。
dwInterests
[in] 目的のコールバック。以下のイベントから成る任意のサブセットを指定する。
ADVISE_NONE 変更なし。
ADVISE_CLIPPING クリッピング リージョンの変更 (ウィンドウと同期する)。
ADVISE_PALETTE パレットの変更。
ADVISE_COLORKEY クロマ キー値の変更。
ADVISE_POSITION ビデオ ウィンドウの位置の変更 (ウィンドウと同期しない)。
ADVISE_DISPLAY_CHANGE WM_DISPLAYCHANGE に関する呼び出し。ディスプレイ解像度を変更すると、すべてのウィンドウに WM_DISPLAYCHANGE メッセージが送られる。
ADVISE_ALL2 上のすべてのイベント。

戻り値

戻り値なし。

注意

このメソッドは、IOverlayNotify インターフェイスが通知を受け取るためのアドバイズ リンクを設定する。これらのイベントのいずれかが発生すると、pOverlayNotify パラメータに渡された適切なエントリ ポイントが呼び出される (IOverlayNotify::OnClipChangeIOverlayNotify::OnColorKeyChangeIOverlayNotify::OnPaletteChange、または IOverlayNotify::OnPositionChange)。

1 つの IOverlay インターフェイスに設定できるアドバイズ リンクは 1 つだけである。2 度目以降の呼び出しで別の通知インターフェイスを設定しようとすると、VFW_E_ADVISE_ALREADY_SET が返される。アドバイズ リンクを取り消すには、IOverlay::Unadvise を使用する。

IOverlay::GetClipList

IOverlay インターフェイス

クリップ リストを取得する。

構文

HRESULT GetClipList(

  RECT *pSourceRect,
  RECT *pDestinationRect,
  RGNDATA **ppRgnData
  );

パラメータ

pSourceRect
[out] クライアントの境界矩形へのポインタ。
pDestinationRect
[in] 転送先矩形へのポインタ。
ppRgnData
[out] クリッピングが記述されたヘッダーおよびデータへのポインタのアドレス。成功した場合は、Microsoft® Win32® CoTaskMemFree 関数でメモリを解放しなければならない。

戻り値

戻り値なし。

注意

クリッピング矩形のメモリは、サイズが可変なため IOverlay の実装によって割り当てられる。このメソッドの呼び出し元フィルタでは、使い終わったら (CoTaskMemFree を使用して) メモリを解放しなければならない。

IOverlay::GetColorKey

IOverlay インターフェイス

クロマ キー処理に使用する現在のカラー キーを取得する。

構文

HRESULT GetColorKey(

  COLORKEY *pColorKey
  );

パラメータ

pColorKey
[out] クロマ キー処理に使用する現在のカラー キーのコピー先へのポインタ。

戻り値

戻り値なし。

注意

IOverlay::SetColorKey メソッドを使用してカラー キーを変更すると、すべてのアドバイズ リンクが、新しい色が指定された IOverlayNotify::OnColorKeyChange コールバック メソッドを受け取る。

現在使用されているカラー キーがない場合、このメソッドは VFW_E_NO_COLOR_KEY_SET を返す。

IOverlay::GetDefaultColorKey

IOverlay インターフェイス

クロマ キー オーバーレイに使用するデフォルトのカラー キーを取得する。

構文

HRESULT GetDefaultColorKey(

  COLORKEY *pColorKey
  );

パラメータ

pColorKey
[out] デフォルトのカラー キーのコピー先へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL失敗。
E_POINTERNull ポインタ引数。
E_INVALIDARG無効な引数。
E_NOTIMPLメソッドがサポートされていない。
S_OK または NOERROR成功。

注意

カラー キーを使用するフィルタは、ビデオ レンダラからデフォルトの色を取得できる。そのうえで IOverlay::SetColorKey を使用して、ウィンドウにデフォルトのカラー キーを組み込める。このメソッドで返される色は、現在のディスプレイ モードによって異なる。8 ビットのパレット化モードの場合は、明るいシステム カラーが返される (マゼンタなど)。トゥルーカラー モードの場合は、黒の濃淡が返される。

IOverlay インターフェイスでは、同じコンピュータにあるそのレンダラの各インスタンスに、それぞれ異なったカラー キーが渡されるようになっているため、オーバーレイの競合は発生しない。

IOverlay::GetPalette

IOverlay インターフェイス

現在のシステム パレットを取得する。

構文

HRESULT GetPalette(

  DWORD *pdwColors,
  PALETTEENTRY **ppPalette
  );

パラメータ

pdwColors
[out] 存在する色の数へのポインタ。
ppPalette
[out] 取得されたパレット構造体へのポインタのアドレス。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL失敗。
E_POINTERNull ポインタ引数。
E_INVALIDARG無効な引数。
E_NOTIMPLメソッドがサポートされていない。
S_OK または NOERROR成功。

IOverlay::GetVideoPosition

IOverlay インターフェイス

現在のビデオの転送元矩形および転送先矩形を取得する。

構文

HRESULT GetVideoPosition(
  [out] RECT *pSourceRect,
  [out] RECT *pDestinationRect
  );

パラメータ

pSourceRect
[out] ビデオ クライアントの境界矩形へのポインタ。
pDestinationRect
[in] ビデオの転送先矩形へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL失敗。
E_POINTERNull ポインタ引数。
E_INVALIDARG無効な引数。
E_NOTIMPLメソッドがサポートされていない。
S_OK または NOERROR成功。

IOverlay::GetWindowHandle

IOverlay インターフェイス

現在のウィンドウ ハンドルを取得する。

構文

HRESULT GetWindowHandle(
  HWND *pHwnd
  );

パラメータ

pHwnd
[out] ウィンドウ ハンドルへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL失敗。
E_POINTERNull ポインタ引数。
E_INVALIDARG無効な引数。
E_NOTIMPLメソッドがサポートされていない。
S_OK または NOERROR成功。

IOverlay::SetColorKey

IOverlay インターフェイス

カラー キーを変更する。

構文

HRESULT SetColorKey(

  COLORKEY *pColorKey
  );

パラメータ

pColorKey
[out] 設定するカラー キー値へのポインタ。成功した場合は、実際に選択されたカラー キー値が、このパラメータにコピーされる。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL失敗。
E_POINTERNull ポインタ引数。
E_INVALIDARG無効な引数。
E_NOTIMPLメソッドがサポートされていない。
S_OK または NOERROR成功。

注意

IOverlay::SetColorKey メソッドを使用してカラー キーを変更すると、すべてのアドバイズ リンクが、新しい色が指定された IOverlayNotify::OnColorKeyChange コールバック メソッドを受け取る。

パレット化されているディスプレイ上の IOverlay を使用するとき、フィルタは、カラー キーを組み込む (IOverlay::SetColorKey を使用) ことも、パレットを組み込む (IOverlay::SetPalette を使用する) こともできるが、両方を組み込むことはできない。これは、このモードのカラー キーではパレットが認識される必要があり、これが SetPalette と矛盾するからである。カラー キーを削除するには、CK_NOCOLORKEY フラグを指定してカラー キーを要求する。同様に、SetPalette で組み込んだパレットを削除するには、SetPalette を呼び出して NULL パラメータを渡す (つまり SetPalette(0,NULL))。

カラー キーが組み込まれているときに、パレットを設定しようとすると、VFW_E_PALETTE_SET エラーが返される。パレットが組み込まれているときに、カラー キーを設定しようとすると、VFW_E_COLOR_KEY_SET が返される。

IOverlay::SetPalette

IOverlay インターフェイス

パレットを設定する。

構文

HRESULT SetPalette(

  DWORD dwColors,
  PALETTEENTRY *pPalette
  );

パラメータ

dwColors
[in] 存在する色の数。
pPalette
[in] パレットに使用する色へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL失敗。
E_POINTERNull ポインタ引数。
E_INVALIDARG無効な引数。
E_NOTIMPLメソッドがサポートされていない。
S_OK または NOERROR成功。

注意

このメソッドは、ウィンドウの論理パレットを設定する。実際のシステム デバイス パレットで要求された色を、ウィンドウが常に持っているとは限らない。Microsoft® Windows® オペレーティング システムでは、フォアグラウンドのアクティブ ウィンドウにのみ、それらの色が保証される。現在のデバイス パレットを取得するには、IOverlay::GetPalette を呼び出す。

デバイスにパレットがない場合、VFW_E_NO_DISPLAY_PALETTE が返される。

オーバーレイ ミキサー フィルタは、E_NOTIMPL を返す。

IOverlay::Unadvise

IOverlay インターフェイス

IOverlayNotify インターフェイスで確立したアドバイズ リンクを終了する。

構文

HRESULT Unadvise(void);

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL失敗。
E_POINTERNull ポインタ引数。
E_INVALIDARG無効な引数。
E_NOTIMPLメソッドがサポートされていない。
S_OK または NOERROR成功。

注意

このメソッドは、IOverlay::Advise メソッドを使用して確立したアドバイズ リンクを終了する。同時に保持できるアドバイズ リンクは 1 つだけである。