Win32 API 日本語リファレンス
ホームMedia.MediaFoundation › IMFSourceReader

IMFSourceReader

COM
IID70ae66f2-c809-4e4f-8915-bdcb406b7993継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

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。

vtbl 3 HRESULT GetStreamSelection(DWORD dwStreamIndex, BOOL* pfSelected)

ストリームが選択されているかどうかを照会します。

dwStreamIndexDWORDin

照会するストリーム。値には次のいずれかを指定できます。

意味
0–0xFFFFFFFB
ストリームの 0 から始まるインデックス。
MF_SOURCE_READER_FIRST_VIDEO_STREAM
0xFFFFFFFC
最初のビデオストリーム。
MF_SOURCE_READER_FIRST_AUDIO_STREAM
0xFFFFFFFD
最初のオーディオストリーム。
pfSelectedBOOL*outストリームが選択されておりデータを生成する場合は TRUE を受け取ります。ストリームが選択されておらずデータを生成しない場合は FALSE を受け取ります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。

vtbl 4 HRESULT SetStreamSelection(DWORD dwStreamIndex, BOOL fSelected)

1 つ以上のストリームを選択または選択解除します。

dwStreamIndexDWORDin

設定するストリーム。値には次のいずれかを指定できます。

意味
0–0xFFFFFFFB
ストリームの 0 から始まるインデックス。
MF_SOURCE_READER_FIRST_VIDEO_STREAM
0xFFFFFFFC
最初のビデオストリーム。
MF_SOURCE_READER_FIRST_AUDIO_STREAM
0xFFFFFFFD
最初のオーディオストリーム。
MF_SOURCE_READER_ALL_STREAMS
0xFFFFFFFE
すべてのストリーム。
fSelectedBOOLinストリームを選択するには TRUE を、選択解除するには FALSE を指定します。ストリームが選択解除されると、そのストリームはデータを生成しません。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドには一般的に 2 つの用途があります。

ストリームを選択解除する例については、チュートリアル: オーディオのデコードを参照してください。

ストリームが選択解除されている場合、そのストリームに対して IMFSourceReader::ReadSample メソッドは MF_E_INVALIDREQUEST を返します。その他の IMFSourceReader メソッドは、選択解除されたストリームに対しても有効です。

ストリームの選択は、ソースリーダーがデコーダーをメモリにロードまたはアンロードする方法には影響しません。特に、ストリームを選択解除しても、ソースリーダーがそのストリームのデコーダーをアンロードするよう強制されることはありません。

このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。

vtbl 5 HRESULT GetNativeMediaType(DWORD dwStreamIndex, DWORD dwMediaTypeIndex, IMFMediaType** ppMediaType)

メディアソースがネイティブにサポートするフォーマットを取得します。

dwStreamIndexDWORDin

照会するストリームを指定します。値には次のいずれかを指定できます。

意味
0–0xFFFFFFFB
ストリームの 0 から始まるインデックス。
MF_SOURCE_READER_FIRST_VIDEO_STREAM
0xFFFFFFFC
最初のビデオストリーム。
MF_SOURCE_READER_FIRST_AUDIO_STREAM
0xFFFFFFFD
最初のオーディオストリーム。
dwMediaTypeIndexDWORDin

照会するメディアタイプを指定します。値には次のいずれかを指定できます。

意味
0–0xFFFFFFFE
メディアタイプの 0 から始まるインデックス
MF_SOURCE_READER_CURRENT_TYPE_INDEX
0xFFFFFFFF
現在のネイティブメディアタイプ。
ppMediaTypeIMFMediaType**outIMFMediaType インターフェイスへのポインターを受け取ります。呼び出し元はこのインターフェイスを解放する必要があります。

戻り値

このメソッドは HRESULT を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値 説明
S_OK
メソッドが成功しました。
MF_E_INVALIDSTREAMNUMBER
dwStreamIndex パラメーターが無効です。
MF_E_NO_MORE_TYPES
dwMediaTypeIndex パラメーターが範囲外です。

解説(Remarks)

このメソッドは、基盤となるメディアソースにそのネイティブ出力フォーマットを照会します。各ソースストリームは、複数の出力フォーマットを生成できる場合があります。dwMediaTypeIndex パラメーターを使用して、利用可能なフォーマットをループ処理してください。一般に、ファイルソースはストリームごとに 1 つのフォーマットのみを提供しますが、キャプチャデバイスは複数のフォーマットを提供する場合があります。

このメソッドはメディアタイプのコピーを返すため、 ppMediaType パラメーターで受け取ったオブジェクトを変更しても安全です。

ストリームの出力タイプを設定するには、IMFSourceReader::SetCurrentMediaType メソッドを呼び出します。

このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。

vtbl 6 HRESULT GetCurrentMediaType(DWORD dwStreamIndex, IMFMediaType** ppMediaType)

ストリームの現在のメディアタイプを取得します。

dwStreamIndexDWORDin

照会するストリーム。値には次のいずれかを指定できます。

意味
0–0xFFFFFFFB
ストリームの 0 から始まるインデックス。
MF_SOURCE_READER_FIRST_VIDEO_STREAM
0xFFFFFFFC
最初のビデオストリーム。
MF_SOURCE_READER_FIRST_AUDIO_STREAM
0xFFFFFFFD
最初のオーディオストリーム。
ppMediaTypeIMFMediaType**outIMFMediaType インターフェイスへのポインターを受け取ります。呼び出し元はこのインターフェイスを解放する必要があります。

戻り値

このメソッドは HRESULT を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値 説明
S_OK
メソッドが成功しました。
MF_E_INVALIDSTREAMNUMBER
dwStreamIndex パラメーターが無効です。

解説(Remarks)

このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。

vtbl 7 HRESULT SetCurrentMediaType(DWORD dwStreamIndex, DWORD* pdwReserved, IMFMediaType* pMediaType)

ストリームのメディアタイプを設定します。

dwStreamIndexDWORDin

構成するストリーム。値には次のいずれかを指定できます。

意味
0–0xFFFFFFFB
ストリームの 0 から始まるインデックス。
MF_SOURCE_READER_FIRST_VIDEO_STREAM
0xFFFFFFFC
最初のビデオストリーム。
MF_SOURCE_READER_FIRST_AUDIO_STREAM
0xFFFFFFFD
最初のオーディオストリーム。
pdwReservedDWORD*optional予約済み。NULL に設定します。
pMediaTypeIMFMediaType*inメディアタイプの IMFMediaType インターフェイスへのポインター。

戻り値

このメソッドは HRESULT を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値 説明
S_OK
メソッドが成功しました。
MF_E_INVALIDMEDIATYPE
ネイティブストリームタイプに対して少なくとも 1 つのデコーダーが見つかりましたが、pMediaType で指定されたタイプは拒否されました。
MF_E_INVALIDREQUEST
1 つ以上のサンプル要求がまだ保留中です。
MF_E_INVALIDSTREAMNUMBER
dwStreamIndex パラメーターが無効です。
MF_E_TOPO_CODEC_NOT_FOUND
ネイティブストリームタイプに対応するデコーダーが見つかりませんでした。

解説(Remarks)

各ストリームについて、メディアタイプを次のいずれかに設定できます。

オーディオのリサンプリングのサポートは、Windows 8 でソースリーダーに追加されました。Windows 8 より前のバージョンの Windows では、ソースリーダーはオーディオのリサンプリングをサポートしていません。Windows 8 より前のバージョンの Windows でオーディオをリサンプリングする必要がある場合は、Audio Resampler DSP を使用できます。

Source Reader の作成時に MF_SOURCE_READER_ENABLE_VIDEO_PROCESSING 属性を TRUE に設定すると、Source Reader は YUV ビデオを RGB-32 に変換します。この変換は、リアルタイムのビデオ再生向けに最適化されていません。

このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。

vtbl 8 HRESULT SetCurrentPosition(GUID* guidTimeFormat, PROPVARIANT* varPosition)

メディアソース内の新しい位置にシークします。

guidTimeFormatGUID*in

時間フォーマットを指定する GUID。時間フォーマットは、varPosition パラメーターの単位を定義します。すべてのメディアソースに対して、次の値が定義されています。

意味
GUID_NULL
100 ナノ秒単位。

一部のメディアソースは、追加の値をサポートする場合があります。

varPositionPROPVARIANT*in再生を開始する位置。単位は guidTimeFormat パラメーターで指定されます。guidTimeFormat パラメーターが GUID_NULL の場合は、バリアント型を VT_I8 に設定します。

戻り値

このメソッドは HRESULT を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値 説明
S_OK
メソッドが成功しました。
MF_E_INVALIDREQUEST
1 つ以上のサンプル要求がまだ保留中です。

解説(Remarks)

SetCurrentPosition メソッドは正確なシークを保証しません。シークの精度はメディアコンテンツに依存します。メディアコンテンツにビデオストリームが含まれている場合、SetCurrentPosition メソッドは通常、目的の位置の直前にある最も近いキーフレームにシークします。キーフレーム間の間隔は、エンコーダーの実装、ビデオコンテンツ、およびコンテンツのエンコードに使用された特定のエンコード設定など、いくつかの要因に依存します。キーフレーム間の間隔は、単一のビデオファイル内でも変動する可能性があります(たとえば、シーンの複雑さに応じて)。

シーク後、アプリケーションは IMFSourceReader::ReadSample を呼び出して、目的の位置まで進める必要があります。

このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。

vtbl 9 HRESULT ReadSample(DWORD dwStreamIndex, DWORD dwControlFlags, DWORD* pdwActualStreamIndex, DWORD* pdwStreamFlags, LONGLONG* pllTimestamp, IMFSample** ppSample)

メディアソースから次のサンプルを読み取ります。

dwStreamIndexDWORDin

データを取得するストリーム。値には次のいずれかを指定できます。

意味
0–0xFFFFFFFB
ストリームの 0 から始まるインデックス。
MF_SOURCE_READER_FIRST_VIDEO_STREAM
0xFFFFFFFC
最初のビデオストリーム。
MF_SOURCE_READER_FIRST_AUDIO_STREAM
0xFFFFFFFD
最初のオーディオストリーム。
MF_SOURCE_READER_ANY_STREAM
0xFFFFFFFE
ストリームを問わず、次に利用可能なサンプルを取得します。
dwControlFlagsDWORDinMF_SOURCE_READER_CONTROL_FLAG 列挙型のフラグ 0 個以上のビットごとの OR
pdwActualStreamIndexDWORD*outoptionalストリームの 0 から始まるインデックスを受け取ります。
pdwStreamFlagsDWORD*outoptionalMF_SOURCE_READER_FLAG 列挙型のフラグ 0 個以上のビットごとの OR を受け取ります。
pllTimestampLONGLONG*outoptionalサンプルのタイムスタンプ、または pdwStreamFlags で示されるストリームイベントの時刻を受け取ります。時刻は 100 ナノ秒単位で指定されます。
ppSampleIMFSample**outoptionalIMFSample インターフェイスへのポインター、または値 NULL を受け取ります(「解説」を参照)。このパラメーターが非 NULL のポインターを受け取った場合、呼び出し元はこのインターフェイスを解放する必要があります。

戻り値

このメソッドは HRESULT を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値 説明
S_OK
メソッドが成功しました。
MF_E_INVALIDREQUEST
無効な要求です。
MF_E_INVALIDSTREAMNUMBER
dwStreamIndex パラメーターが無効です。
MF_E_NOTACCEPTING
フラッシュ操作が保留中です。IMFSourceReader::Flush を参照してください。
E_INVALIDARG
無効な引数です。「解説」を参照してください。

解説(Remarks)

要求されたストリームが選択されていない場合、戻り値は MF_E_INVALIDREQUEST です。IMFSourceReader::SetStreamSelection を参照してください。

このメソッドは同期的にも非同期的にも完了できます。ソースリーダーの作成時にコールバックポインターを指定した場合、このメソッドは非同期です。それ以外の場合、このメソッドは同期です。コールバックポインターの設定の詳細については、MF_SOURCE_READER_ASYNC_CALLBACK を参照してください。

非同期モード

非同期モードでは、

同期モード

同期モードでは、 同期モードで dwStreamIndex パラメーターが MF_SOURCE_READER_ANY_STREAM の場合、どのストリームがサンプルを提供したかを知るために、pdwActualStreamIndex に非 NULL の値を渡す必要があります。

このメソッドは、ppSample にメディアサンプルを返さずに pdwStreamFlags パラメーターにフラグを返すことがあります。したがって、メソッドが成功した場合でも、ppSample パラメーターは NULL ポインターを受け取ることがあります。たとえば、ソースリーダーがストリームの末尾に達すると、pdwStreamFlagsMF_SOURCE_READERF_ENDOFSTREAM フラグを返し、ppSampleNULL に設定します。

ストリームにギャップがある場合、pdwStreamFlagsMF_SOURCE_READERF_STREAMTICK フラグを受け取り、ppSampleNULL となり、pllTimestamp はギャップが発生した時刻を示します。

このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。

vtbl 10 HRESULT Flush(DWORD dwStreamIndex)

1 つ以上のストリームをフラッシュします。(IMFSourceReader.Flush)

dwStreamIndexDWORDin

フラッシュするストリーム。値には次のいずれかを指定できます。

意味
0–0xFFFFFFFB
ストリームの 0 から始まるインデックス。
MF_SOURCE_READER_FIRST_VIDEO_STREAM
0xFFFFFFFC
最初のビデオストリーム。
MF_SOURCE_READER_FIRST_AUDIO_STREAM
0xFFFFFFFD
最初のオーディオストリーム。
MF_SOURCE_READER_ALL_STREAMS
0xFFFFFFFE
すべてのストリーム。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

Flush メソッドは、キューに入っているすべてのサンプルを破棄し、保留中のすべてのサンプル要求をキャンセルします。

このメソッドは同期的にも非同期的にも完了できます。

ソースリーダーの作成時にコールバックポインターを指定した場合、このメソッドは非同期です。それ以外の場合、このメソッドは同期です。コールバックポインターの設定の詳細については、MF_SOURCE_READER_ASYNC_CALLBACK を参照してください。

同期モードでは、このメソッドは操作が完了するまでブロックします。

非同期モードでは、フラッシュ操作が完了すると、アプリケーションの IMFSourceReaderCallback::OnFlush メソッドが呼び出されます。フラッシュ操作が保留中の間、IMFSourceReader::ReadSample メソッドは MF_E_NOTACCEPTING を返します。

注意 Windows 7 では、このメソッドの実装にバグがあり、フラッシュ操作が完了する前に OnFlush が呼び出されていました。このバグを修正する修正プログラムが以前は提供されていました。
このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。
vtbl 11 HRESULT GetServiceForStream(DWORD dwStreamIndex, GUID* guidService, GUID* riid, void** ppvObject)

基盤となるメディアソースまたはデコーダーにインターフェイスを照会します。

dwStreamIndexDWORDin

照会するストリームまたはオブジェクト。値が MF_SOURCE_READER_MEDIASOURCE の場合、このメソッドはメディアソースを照会します。それ以外の場合は、指定されたストリームに関連付けられたデコーダーを照会します。指定できる値は次のとおりです。

意味
0–0xFFFFFFFB
ストリームの 0 から始まるインデックス。
MF_SOURCE_READER_FIRST_VIDEO_STREAM
0xFFFFFFFC
最初のビデオストリーム。
MF_SOURCE_READER_FIRST_AUDIO_STREAM
0xFFFFFFFD
最初のオーディオストリーム。
MF_SOURCE_READER_MEDIASOURCE
0xFFFFFFFF
メディアソース。
guidServiceGUID*inサービス識別子 GUID。値が GUID_NULL の場合、このメソッドは QueryInterface を呼び出して、要求されたインターフェイスを取得します。それ以外の場合は、IMFGetService::GetService メソッドを呼び出します。サービス識別子の一覧については、Service Interfaces を参照してください。
riidGUID*in要求されるインターフェイスのインターフェイス識別子(IID)。
ppvObjectvoid**out要求されたインターフェイスへのポインターを受け取ります。呼び出し元はこのインターフェイスを解放する必要があります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。

vtbl 12 HRESULT GetPresentationAttribute(DWORD dwStreamIndex, GUID* guidAttribute, PROPVARIANT* pvarAttribute)

基盤となるメディアソースから属性を取得します。

dwStreamIndexDWORDin

照会するストリームまたはオブジェクト。値には次のいずれかを指定できます。

意味
0–0xFFFFFFFB
ストリームの 0 から始まるインデックス。
MF_SOURCE_READER_FIRST_VIDEO_STREAM
0xFFFFFFFC
最初のビデオストリーム。
MF_SOURCE_READER_FIRST_AUDIO_STREAM
0xFFFFFFFD
最初のオーディオストリーム。
MF_SOURCE_READER_MEDIASOURCE
0xFFFFFFFF
メディアソース。
guidAttributeGUID*in

取得する属性を識別する GUID。dwStreamIndex パラメーターが MF_SOURCE_READER_MEDIASOURCE に等しい場合、guidAttribute には次のいずれかを指定できます。

それ以外の場合、dwStreamIndex パラメーターがストリームを指定しているときは、guidAttribute はストリーム記述子属性を指定します。値の一覧については、Stream Descriptor Attributes を参照してください。
pvarAttributePROPVARIANT*out属性の値を受け取る PROPVARIANT へのポインター。PROPVARIANT を解放するには、PropVariantClear 関数を呼び出します。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このインターフェイスは、Platform Update Supplement for Windows Vista がインストールされている場合、Windows Vista で利用できます。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
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 指定が可能。