IOverlay
COM公式ドキュメント
IOverlay インターフェースは、フィルターがビデオメモリに直接書き込みながら、ビデオを正しいウィンドウ位置に配置できるようにするための情報を提供します。
メソッド 10
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
GetPalette メソッドは、現在のシステムパレットを取得します。
| pdwColors | DWORD* | inout | 存在する色数を受け取る変数へのポインター。 |
| ppPalette | PALETTEENTRY** | out | パレットを記述する PALETTEENTRY 構造体へのポインターを受け取ります。 |
戻り値
成功した場合は S_OK を返します。メソッドが失敗した場合は HRESULT エラーコードを返します。
SetPalette メソッドは、パレットを設定します。
| dwColors | DWORD | in | 存在する色数。 |
| pPalette | PALETTEENTRY* | in | パレットに使用する色へのポインター。 |
戻り値
成功した場合は S_OK を返します。メソッドが失敗した場合は HRESULT エラーコードを返します。
解説(Remarks)
このメソッドは、ウィンドウの論理パレットを設定します。ウィンドウが実際のシステムデバイスパレットで、要求した色を常に持つことは保証されません。Microsoft® Windows® オペレーティングシステムがこれらの色を保証するのは、ウィンドウがフォアグラウンドのアクティブウィンドウである場合のみです。現在のデバイスパレットは IOverlay::GetPalette を呼び出すことで取得できます。
デバイスがパレットを持たない場合は VFW_E_NO_DISPLAY_PALETTE を返します。
Overlay Mixer フィルターは E_NOTIMPL を返します。
GetDefaultColorKey メソッドは、クロマキーオーバーレイに使用される既定のカラーキーを取得します。
| pColorKey | COLORKEY* | out | 既定のカラーキーを受け取る変数へのポインター。 |
戻り値
成功した場合は S_OK を返します。メソッドが失敗した場合は HRESULT エラーコードを返します。
解説(Remarks)
カラーキーを使用するフィルターは、ビデオレンダラーから既定の色を取得できます。取得した既定のカラーキーは、IOverlay::SetColorKey を使用してウィンドウに設定できます。このメソッドが返す色は、現在の表示モードによって異なります。色が 8 ビットのパレット方式である場合は、明るいシステムカラー(マゼンタなど)になります。表示がトゥルーカラーモードの場合は、黒の濃淡になります。
IOverlay インターフェースは、同一コンピューター上のレンダラーの個々のインスタンスが異なるカラーキーを取得し、オーバーレイが競合しないようにするために使用されます。
GetColorKey メソッドは、クロマキーに使用されている現在のカラーキーを取得します。
| pColorKey | COLORKEY* | out | クロマキーに使用されている現在のカラーキーを受け取る変数へのポインター。 |
戻り値
成功した場合は S_OK を返します。メソッドが失敗した場合は HRESULT エラーコードを返します。
解説(Remarks)
IOverlay::SetColorKey メソッドを使用してカラーキーを変更すると、すべてのアドバイズリンクは新しい色とともに IOverlayNotify::OnColorKeyChange コールバックメソッドを受け取ります。
カラーキーが現在使用されていない場合、このメソッドは VFW_E_NO_COLOR_KEY_SET を返します。
SetColorKey メソッドは、カラーキーを変更します。
| pColorKey | COLORKEY* | inout | 設定するカラーキー値へのポインター。成功した場合、実際に選択されたカラーキー値がこのパラメーターにコピーされます。 |
戻り値
成功した場合は S_OK を、pColorKey が NULL の場合は E_POINTER を、pColorKey の値が現在のパレットまたはピクセル形式に対して無効な場合は E_INVALIDARG を返します。
解説(Remarks)
SetColorKey メソッドを使用してカラーキーを変更すると、すべてのアドバイズリンクは新しい色とともに IOverlayNotify::OnColorKeyChange コールバックメソッドを受け取ります。
パレット方式の表示で IOverlay::Advise を使用する場合、フィルターはカラーキーを設定する(SetColorKey を使用)か、パレットを設定する(IOverlay::SetPalette を使用)かのいずれかを行えますが、両方は行えません。これは、このモードでのカラーキーは、SetPalette と競合するパレットの実現を必要とするためです。カラーキーは、CK_NOCOLORKEY フラグを指定してカラーキーを要求することでアンインストールできます。同様に、SetPalette を通じて設定されたパレットは、SetPalette を呼び出して NULL パラメーターを渡す(つまり SetPalette(0,NULL))ことでアンインストールできます。
カラーキーが設定されているときにパレットを設定しようとすると、VFW_E_PALETTE_SET エラーが返されます。パレットが設定されているときにカラーキーを設定しようとすると、VFW_E_COLOR_KEY_SET が返されます。
GetWindowHandle メソッドは、現在のウィンドウハンドルを取得します。
| pHwnd | HWND* | out | ウィンドウハンドルを受け取ります。 |
戻り値
成功した場合は S_OK を返します。メソッドが失敗した場合は HRESULT エラーコードを返します。
GetClipList メソッドは、クリッピングリストを取得します。
| pSourceRect | RECT* | out | 境界となるクライアント矩形へのポインター。 |
| pDestinationRect | RECT* | out | 転送先矩形へのポインター。 |
| ppRgnData | RGNDATA** | out | クリッピングを記述するヘッダーとデータへのポインターのアドレス。成功した場合は、CoTaskMemFree を呼び出して、割り当てられたメモリを解放してください。 |
戻り値
成功した場合は S_OK を返します。メソッドが失敗した場合は HRESULT エラーコードを返します。
解説(Remarks)
クリッピング矩形はその長さが変化しうるため、そのメモリは IOverlay の実装が割り当てます。このメソッドを呼び出すフィルターは、使用し終わったらそのメモリを(CoTaskMemFree を使用して)解放する必要があります。
GetVideoPosition メソッドは、現在のビデオの転送元矩形と転送先矩形を取得します。
| pSourceRect | RECT* | out | 転送元矩形を受け取る RECT 構造体へのポインター。 |
| pDestinationRect | RECT* | out | 転送先矩形を受け取る RECT 構造体へのポインター。 |
戻り値
成功した場合は S_OK を返します。メソッドが失敗した場合は HRESULT エラーコードを返します。
Advise メソッドは、dwInterests パラメーターで指定されたオーバーレイイベントに対するアドバイズリンクを設定します。
| pOverlayNotify | IOverlayNotify* | in | 通知インターフェースへのポインター。 | ||||||||||||||||
| dwInterests | DWORD | in | 対象とするコールバック。以下のイベントの任意のサブセットを指定できます。
|
戻り値
成功した場合は S_OK を返します。メソッドが失敗した場合は HRESULT エラーコードを返します。
解説(Remarks)
このメソッドは、通知を受け取るための IOverlayNotify インターフェースへのアドバイズリンクを設定します。これらのイベントのいずれかが発生すると、渡された pOverlayNotify パラメーター内の該当するエントリポイント(IOverlayNotify::OnClipChange、IOverlayNotify::OnColorKeyChange、IOverlayNotify::OnPaletteChange、または IOverlayNotify::OnPositionChange)が呼び出されます。
1 つの IOverlay インターフェースには、1 つのアドバイズリンクしか設定できません。2 回目以降の呼び出しで別の通知インターフェースを設定しようとすると、VFW_E_ADVISE_ALREADY_SET が返されます。アドバイズリンクは IOverlay::Unadvise を使用して取り消すことができます。
Unadvise メソッドは、IOverlayNotify インターフェースとの間で確立されたアドバイズリンクを終了します。
戻り値
成功した場合は S_OK を返します。メソッドが失敗した場合は HRESULT エラーコードを返します。
解説(Remarks)
このメソッドは、IOverlay::Advise メソッドを使用して確立されたアドバイズリンクを終了します。同時に維持できるアドバイズリンクは 1 つだけです。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IOverlay "{56A868A1-0AD4-11CE-B03A-0020AF0BA770}" #usecom global IOverlay IID_IOverlay "{}" #comfunc global IOverlay_GetPalette 3 var,var #comfunc global IOverlay_SetPalette 4 int,var #comfunc global IOverlay_GetDefaultColorKey 5 var #comfunc global IOverlay_GetColorKey 6 var #comfunc global IOverlay_SetColorKey 7 var #comfunc global IOverlay_GetWindowHandle 8 sptr #comfunc global IOverlay_GetClipList 9 var,var,var #comfunc global IOverlay_GetVideoPosition 10 var,var #comfunc global IOverlay_Advise 11 sptr,int #comfunc global IOverlay_Unadvise 12 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IOverlay "{56A868A1-0AD4-11CE-B03A-0020AF0BA770}" #usecom global IOverlay IID_IOverlay "{}" #comfunc global IOverlay_GetPalette 3 sptr,sptr #comfunc global IOverlay_SetPalette 4 int,sptr #comfunc global IOverlay_GetDefaultColorKey 5 sptr #comfunc global IOverlay_GetColorKey 6 sptr #comfunc global IOverlay_SetColorKey 7 sptr #comfunc global IOverlay_GetWindowHandle 8 sptr #comfunc global IOverlay_GetClipList 9 sptr,sptr,sptr #comfunc global IOverlay_GetVideoPosition 10 sptr,sptr #comfunc global IOverlay_Advise 11 sptr,int #comfunc global IOverlay_Unadvise 12 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。