IMFSourceReader
COM公式ドキュメント
Microsoft Media Foundation のソースリーダーオブジェクトによって実装されます。
解説(Remarks)
ソースリーダーを作成するには、次のいずれかの関数を呼び出します。
あるいは、IMFReadWriteClassFactory インターフェイスを使用します。このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
Windows 8 では、このインターフェイスは IMFSourceReaderEx によって拡張されています。
メソッド 10
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
ストリームが選択されているかどうかを照会します。
| dwStreamIndex | DWORD | in | 照会するストリーム。値には次のいずれかを指定できます。
| ||||||||
| pfSelected | BOOL* | out | ストリームが選択されておりデータを生成する場合は TRUE を受け取ります。ストリームが選択されておらずデータを生成しない場合は FALSE を受け取ります。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
1 つ以上のストリームを選択または選択解除します。
| dwStreamIndex | DWORD | in | 設定するストリーム。値には次のいずれかを指定できます。
| ||||||||||
| fSelected | BOOL | in | ストリームを選択するには TRUE を、選択解除するには FALSE を指定します。ストリームが選択解除されると、そのストリームはデータを生成しません。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
このメソッドには一般的に 2 つの用途があります。
- 既定のストリーム選択を変更する場合。一部のメディアファイルには、同じ種類のストリームが複数含まれています。たとえば、ファイルに複数の言語のオーディオストリームが含まれている場合があります。このメソッドを使用して、どのストリームを選択するかを変更できます。各ストリームの情報を取得するには、IMFSourceReader::GetPresentationAttribute または IMFSourceReader::GetNativeMediaType を呼び出します。
- いずれかのストリームのデータが不要な場合は、そのストリームを選択解除するとよいでしょう。ストリームが選択されていると、メディアソースが未読データのキューを保持し続け、そのキューが際限なく増大してメモリを消費する可能性があります。
ストリームが選択解除されている場合、そのストリームに対して IMFSourceReader::ReadSample メソッドは MF_E_INVALIDREQUEST を返します。その他の IMFSourceReader メソッドは、選択解除されたストリームに対しても有効です。
ストリームの選択は、ソースリーダーがデコーダーをメモリにロードまたはアンロードする方法には影響しません。特に、ストリームを選択解除しても、ソースリーダーがそのストリームのデコーダーをアンロードするよう強制されることはありません。
このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
メディアソースがネイティブにサポートするフォーマットを取得します。
| dwStreamIndex | DWORD | in | 照会するストリームを指定します。値には次のいずれかを指定できます。
| ||||||||
| dwMediaTypeIndex | DWORD | in | 照会するメディアタイプを指定します。値には次のいずれかを指定できます。
| ||||||||
| ppMediaType | IMFMediaType** | out | IMFMediaType インターフェイスへのポインターを受け取ります。呼び出し元はこのインターフェイスを解放する必要があります。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| メソッドが成功しました。 | |
| dwStreamIndex パラメーターが無効です。 | |
| dwMediaTypeIndex パラメーターが範囲外です。 |
解説(Remarks)
このメソッドは、基盤となるメディアソースにそのネイティブ出力フォーマットを照会します。各ソースストリームは、複数の出力フォーマットを生成できる場合があります。dwMediaTypeIndex パラメーターを使用して、利用可能なフォーマットをループ処理してください。一般に、ファイルソースはストリームごとに 1 つのフォーマットのみを提供しますが、キャプチャデバイスは複数のフォーマットを提供する場合があります。
このメソッドはメディアタイプのコピーを返すため、 ppMediaType パラメーターで受け取ったオブジェクトを変更しても安全です。
ストリームの出力タイプを設定するには、IMFSourceReader::SetCurrentMediaType メソッドを呼び出します。
このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
ストリームの現在のメディアタイプを取得します。
| dwStreamIndex | DWORD | in | 照会するストリーム。値には次のいずれかを指定できます。
| ||||||||
| ppMediaType | IMFMediaType** | out | IMFMediaType インターフェイスへのポインターを受け取ります。呼び出し元はこのインターフェイスを解放する必要があります。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| メソッドが成功しました。 | |
| dwStreamIndex パラメーターが無効です。 |
解説(Remarks)
このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
ストリームのメディアタイプを設定します。
| dwStreamIndex | DWORD | in | 構成するストリーム。値には次のいずれかを指定できます。
| ||||||||
| pdwReserved | DWORD* | optional | 予約済み。NULL に設定します。 | ||||||||
| pMediaType | IMFMediaType* | in | メディアタイプの IMFMediaType インターフェイスへのポインター。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| メソッドが成功しました。 | |
| ネイティブストリームタイプに対して少なくとも 1 つのデコーダーが見つかりましたが、pMediaType で指定されたタイプは拒否されました。 | |
| 1 つ以上のサンプル要求がまだ保留中です。 | |
| dwStreamIndex パラメーターが無効です。 | |
| ネイティブストリームタイプに対応するデコーダーが見つかりませんでした。 |
解説(Remarks)
各ストリームについて、メディアタイプを次のいずれかに設定できます。
- メディアソースが提供するネイティブタイプの 1 つ。ネイティブタイプを列挙するには、IMFSourceReader::GetNativeMediaType を呼び出します。
- ネイティブメディアタイプが圧縮されている場合は、対応する非圧縮フォーマットを指定できます。Source Reader は、ネイティブフォーマットから指定された非圧縮フォーマットへデコードできるデコーダーを検索します。
Source Reader の作成時に MF_SOURCE_READER_ENABLE_VIDEO_PROCESSING 属性を TRUE に設定すると、Source Reader は YUV ビデオを RGB-32 に変換します。この変換は、リアルタイムのビデオ再生向けに最適化されていません。
このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
メディアソース内の新しい位置にシークします。
| guidTimeFormat | GUID* | in | 時間フォーマットを指定する GUID。時間フォーマットは、varPosition パラメーターの単位を定義します。すべてのメディアソースに対して、次の値が定義されています。
一部のメディアソースは、追加の値をサポートする場合があります。 | ||||
| varPosition | PROPVARIANT* | in | 再生を開始する位置。単位は guidTimeFormat パラメーターで指定されます。guidTimeFormat パラメーターが GUID_NULL の場合は、バリアント型を VT_I8 に設定します。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| メソッドが成功しました。 | |
| 1 つ以上のサンプル要求がまだ保留中です。 |
解説(Remarks)
SetCurrentPosition メソッドは正確なシークを保証しません。シークの精度はメディアコンテンツに依存します。メディアコンテンツにビデオストリームが含まれている場合、SetCurrentPosition メソッドは通常、目的の位置の直前にある最も近いキーフレームにシークします。キーフレーム間の間隔は、エンコーダーの実装、ビデオコンテンツ、およびコンテンツのエンコードに使用された特定のエンコード設定など、いくつかの要因に依存します。キーフレーム間の間隔は、単一のビデオファイル内でも変動する可能性があります(たとえば、シーンの複雑さに応じて)。
シーク後、アプリケーションは IMFSourceReader::ReadSample を呼び出して、目的の位置まで進める必要があります。
このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
メディアソースから次のサンプルを読み取ります。
| dwStreamIndex | DWORD | in | データを取得するストリーム。値には次のいずれかを指定できます。
| ||||||||||
| dwControlFlags | DWORD | in | MF_SOURCE_READER_CONTROL_FLAG 列挙型のフラグ 0 個以上のビットごとの OR。 | ||||||||||
| pdwActualStreamIndex | DWORD* | outoptional | ストリームの 0 から始まるインデックスを受け取ります。 | ||||||||||
| pdwStreamFlags | DWORD* | outoptional | MF_SOURCE_READER_FLAG 列挙型のフラグ 0 個以上のビットごとの OR を受け取ります。 | ||||||||||
| pllTimestamp | LONGLONG* | outoptional | サンプルのタイムスタンプ、または pdwStreamFlags で示されるストリームイベントの時刻を受け取ります。時刻は 100 ナノ秒単位で指定されます。 | ||||||||||
| ppSample | IMFSample** | outoptional | IMFSample インターフェイスへのポインター、または値 NULL を受け取ります(「解説」を参照)。このパラメーターが非 NULL のポインターを受け取った場合、呼び出し元はこのインターフェイスを解放する必要があります。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| メソッドが成功しました。 | |
| 無効な要求です。 | |
| dwStreamIndex パラメーターが無効です。 | |
| フラッシュ操作が保留中です。IMFSourceReader::Flush を参照してください。 | |
| 無効な引数です。「解説」を参照してください。 |
解説(Remarks)
要求されたストリームが選択されていない場合、戻り値は MF_E_INVALIDREQUEST です。IMFSourceReader::SetStreamSelection を参照してください。
このメソッドは同期的にも非同期的にも完了できます。ソースリーダーの作成時にコールバックポインターを指定した場合、このメソッドは非同期です。それ以外の場合、このメソッドは同期です。コールバックポインターの設定の詳細については、MF_SOURCE_READER_ASYNC_CALLBACK を参照してください。
非同期モード
非同期モードでは、- すべての
[out]パラメーターは NULL でなければなりません。そうでない場合、このメソッドは E_INVALIDARG を返します。 - このメソッドはただちに戻ります。
- 操作が完了すると、アプリケーションの IMFSourceReaderCallback::OnReadSample メソッドが呼び出されます。
- エラーが発生した場合、このメソッドは同期的にも非同期的にも失敗する可能性があります。ReadSample の戻り値を確認し、さらに IMFSourceReaderCallback::OnReadSample の hrStatus パラメーターも確認してください。
同期モード
同期モードでは、- pdwStreamFlags および ppSample パラメーターを NULL にすることはできません。そうでない場合、このメソッドは E_POINTER を返します。
- pdwActualStreamIndex および pllTimestamp パラメーターは NULL にできます。
- このメソッドは、次のサンプルが利用可能になるまでブロックします。
このメソッドは、ppSample にメディアサンプルを返さずに pdwStreamFlags パラメーターにフラグを返すことがあります。したがって、メソッドが成功した場合でも、ppSample パラメーターは NULL ポインターを受け取ることがあります。たとえば、ソースリーダーがストリームの末尾に達すると、pdwStreamFlags に MF_SOURCE_READERF_ENDOFSTREAM フラグを返し、ppSample を NULL に設定します。
ストリームにギャップがある場合、pdwStreamFlags は MF_SOURCE_READERF_STREAMTICK フラグを受け取り、ppSample は NULL となり、pllTimestamp はギャップが発生した時刻を示します。
このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
1 つ以上のストリームをフラッシュします。(IMFSourceReader.Flush)
| dwStreamIndex | DWORD | in | フラッシュするストリーム。値には次のいずれかを指定できます。
|
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
Flush メソッドは、キューに入っているすべてのサンプルを破棄し、保留中のすべてのサンプル要求をキャンセルします。
このメソッドは同期的にも非同期的にも完了できます。
ソースリーダーの作成時にコールバックポインターを指定した場合、このメソッドは非同期です。それ以外の場合、このメソッドは同期です。コールバックポインターの設定の詳細については、MF_SOURCE_READER_ASYNC_CALLBACK を参照してください。
同期モードでは、このメソッドは操作が完了するまでブロックします。
非同期モードでは、フラッシュ操作が完了すると、アプリケーションの IMFSourceReaderCallback::OnFlush メソッドが呼び出されます。フラッシュ操作が保留中の間、IMFSourceReader::ReadSample メソッドは MF_E_NOTACCEPTING を返します。
基盤となるメディアソースまたはデコーダーにインターフェイスを照会します。
| dwStreamIndex | DWORD | in | 照会するストリームまたはオブジェクト。値が MF_SOURCE_READER_MEDIASOURCE の場合、このメソッドはメディアソースを照会します。それ以外の場合は、指定されたストリームに関連付けられたデコーダーを照会します。指定できる値は次のとおりです。
| ||||||||||
| guidService | GUID* | in | サービス識別子 GUID。値が GUID_NULL の場合、このメソッドは QueryInterface を呼び出して、要求されたインターフェイスを取得します。それ以外の場合は、IMFGetService::GetService メソッドを呼び出します。サービス識別子の一覧については、Service Interfaces を参照してください。 | ||||||||||
| riid | GUID* | in | 要求されるインターフェイスのインターフェイス識別子(IID)。 | ||||||||||
| ppvObject | void** | out | 要求されたインターフェイスへのポインターを受け取ります。呼び出し元はこのインターフェイスを解放する必要があります。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
基盤となるメディアソースから属性を取得します。
| dwStreamIndex | DWORD | in | 照会するストリームまたはオブジェクト。値には次のいずれかを指定できます。
| ||||||||||
| guidAttribute | GUID* | in | 取得する属性を識別する GUID。dwStreamIndex パラメーターが MF_SOURCE_READER_MEDIASOURCE に等しい場合、guidAttribute には次のいずれかを指定できます。
| ||||||||||
| pvarAttribute | PROPVARIANT* | out | 属性の値を受け取る PROPVARIANT へのポインター。PROPVARIANT を解放するには、PropVariantClear 関数を呼び出します。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IMFSourceReader "{70AE66F2-C809-4E4F-8915-BDCB406B7993}" #usecom global IMFSourceReader IID_IMFSourceReader "{}" #comfunc global IMFSourceReader_GetStreamSelection 3 int,var #comfunc global IMFSourceReader_SetStreamSelection 4 int,int #comfunc global IMFSourceReader_GetNativeMediaType 5 int,int,sptr #comfunc global IMFSourceReader_GetCurrentMediaType 6 int,sptr #comfunc global IMFSourceReader_SetCurrentMediaType 7 int,var,sptr #comfunc global IMFSourceReader_SetCurrentPosition 8 var,var #comfunc global IMFSourceReader_ReadSample 9 int,int,var,var,var,sptr #comfunc global IMFSourceReader_Flush 10 int #comfunc global IMFSourceReader_GetServiceForStream 11 int,var,var,sptr #comfunc global IMFSourceReader_GetPresentationAttribute 12 int,var,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IMFSourceReader "{70AE66F2-C809-4E4F-8915-BDCB406B7993}" #usecom global IMFSourceReader IID_IMFSourceReader "{}" #comfunc global IMFSourceReader_GetStreamSelection 3 int,sptr #comfunc global IMFSourceReader_SetStreamSelection 4 int,int #comfunc global IMFSourceReader_GetNativeMediaType 5 int,int,sptr #comfunc global IMFSourceReader_GetCurrentMediaType 6 int,sptr #comfunc global IMFSourceReader_SetCurrentMediaType 7 int,sptr,sptr #comfunc global IMFSourceReader_SetCurrentPosition 8 sptr,sptr #comfunc global IMFSourceReader_ReadSample 9 int,int,sptr,sptr,sptr,sptr #comfunc global IMFSourceReader_Flush 10 int #comfunc global IMFSourceReader_GetServiceForStream 11 int,sptr,sptr,sptr #comfunc global IMFSourceReader_GetPresentationAttribute 12 int,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。