ホーム › Media.MediaFoundation › IMFMediaSink

IMFMediaSink

COM

📘 Microsoft Learn (日本語) · English

IID6ef2a660-47c0-4666-b13d-cbb717f2fa2c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

メディアシンクオブジェクトによって実装されます。

メソッド 9

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetCharacteristics(DWORD* pdwCharacteristics)

メディアシンクの特性を取得します。

pdwCharacteristics

DWORD*

out

0個以上のフラグのビットごとの OR を受け取ります。次のフラグが定義されています。

値	意味
MEDIASINK_FIXED_STREAMS 0x00000001	メディアシンクは固定数のストリームを持ちます。IMFMediaSink::AddStreamSink および IMFMediaSink::RemoveStreamSink メソッドはサポートされません。このフラグはアプリケーションへのヒントです。
MEDIASINK_CANNOT_MATCH_CLOCK 0x00000002	メディアシンクは外部クロックとレートを一致させることができません。最良の結果を得るには、このメディアシンクをプレゼンテーションクロックのタイムソースとして使用してください。他のタイムソースを使用すると、メディアシンクはクロックとレートを一致させることができず、結果が不良になります (たとえばグリッチが発生します)。このフラグはパイプラインの構成方法を制限するため、控えめに使用してください。プレゼンテーションクロックの詳細については、Presentation Clock を参照してください。
MEDIASINK_RATELESS 0x00000004	メディアシンクはレートレスです。可能な限り速くサンプルを消費し、プレゼンテーションクロックに同期しません。ほとんどのアーカイブ用シンクはレートレスです。
MEDIASINK_CLOCK_REQUIRED 0x00000008	メディアシンクはプレゼンテーションクロックを必要とします。プレゼンテーションクロックは、メディアシンクの IMFMediaSink::SetPresentationClock メソッドを呼び出して設定します。このフラグは廃止されています。なぜなら、すべてのメディアシンクは、(レートレスなメディアシンクのように) クロックを無視する場合であっても、SetPresentationClock メソッドをサポートしなければならないためです。
MEDIASINK_CAN_PREROLL 0x00000010	メディアシンクは、プレゼンテーションクロックが開始する前にプリロールサンプルを受け入れることができます。メディアシンクは IMFMediaSinkPreroll インターフェイスを公開します。
MEDIASINK_REQUIRE_REFERENCE_MEDIATYPE 0x00000020	最初のストリームシンク (インデックス 0) は参照ストリームです。他のストリームシンクにメディアタイプを設定する前に、参照ストリームがメディアタイプを持っていなければなりません。

戻り値

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

戻り値コード	説明
S_OK	メソッドは成功しました。
MF_E_SHUTDOWN	メディアシンクの Shutdown メソッドが呼び出されています。

解説(Remarks)

メディアシンクの特性は、シンクの存続期間中を通じて固定されています。

vtbl 4 HRESULT AddStreamSink(DWORD dwStreamSinkIdentifier, IMFMediaType* pMediaType, IMFStreamSink** ppStreamSink)

新しいストリームシンクをメディアシンクに追加します。

dwStreamSinkIdentifier	DWORD	in	新しいストリームの識別子。値は任意ですが、一意でなければなりません。
pMediaType	IMFMediaType*	in	IMFMediaType インターフェイスへのポインター。ストリームのメディアタイプを指定します。このパラメーターは NULL にすることができます。
ppStreamSink	IMFStreamSink**	out	新しいストリームシンクの IMFStreamSink インターフェイスへのポインターを受け取ります。呼び出し元はインターフェイスを解放しなければなりません。

戻り値

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

戻り値コード	説明
S_OK	メソッドは成功しました。
MF_E_INVALIDSTREAMNUMBER	指定されたストリーム識別子は有効ではありません。
MF_E_SHUTDOWN	メディアシンクの Shutdown メソッドが呼び出されています。
MF_E_STREAMSINK_EXISTS	同じストリーム識別子を持つストリームシンクが既に存在します。
MF_E_STREAMSINKS_FIXED	このメディアシンクは固定されたストリームシンクのセットを持っています。新しいストリームシンクを追加することはできません。

解説(Remarks)

すべてのメディアシンクがこのメソッドをサポートするわけではありません。メディアシンクがこのメソッドをサポートしない場合、IMFMediaSink::GetCharacteristics メソッドは MEDIASINK_FIXED_STREAMS フラグを返します。

pMediaType が NULL の場合は、IMFMediaTypeHandler インターフェイスを使用してメディアタイプを設定します。IMFStreamSink::GetMediaTypeHandler を呼び出して、このインターフェイスへのポインターを取得してください。

vtbl 5 HRESULT RemoveStreamSink(DWORD dwStreamSinkIdentifier)

ストリームシンクをメディアシンクから削除します。

dwStreamSinkIdentifier

DWORD

削除するストリームの識別子。ストリーム識別子は、ストリームシンクを追加するために IMFMediaSink::AddStreamSink を呼び出すときに定義されます。

戻り値

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

戻り値コード	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	この特定のストリームシンクは削除できません。
MF_E_INVALIDSTREAMNUMBER	ストリーム番号が有効ではありません。
MF_E_NOT_INITIALIZED	メディアシンクが初期化されていません。
MF_E_SHUTDOWN	メディアシンクの Shutdown メソッドが呼び出されています。
MF_E_STREAMSINKS_FIXED	このメディアシンクは固定されたストリームシンクのセットを持っています。ストリームシンクを削除することはできません。

解説(Remarks)

このメソッドが呼び出された後、対応するストリームシンクオブジェクトはもはや有効ではありません。IMFMediaSink::GetStreamSinkByIndex および IMFMediaSink::GetStreamSinkById メソッドは、そのストリームシンクをもはや返しません。別のストリームを追加する場合 (AddStreamSink を呼び出す場合)、そのストリーム識別子を再利用できます。

場合によっては、メディアシンクはこのメソッドをサポートしていても、すべてのストリームシンクの削除を許可しないことがあります。(たとえば、ストリーム 0 の削除を許可しない場合があります。)

vtbl 6 HRESULT GetStreamSinkCount(DWORD* pcStreamSinkCount)

このメディアシンク上のストリームシンクの数を取得します。

pcStreamSinkCount

DWORD*

out

ストリームシンクの数を受け取ります。

戻り値

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

戻り値コード	説明
S_OK	メソッドは成功しました。
MF_E_SHUTDOWN	メディアシンクの Shutdown メソッドが呼び出されています。

vtbl 7 HRESULT GetStreamSinkByIndex(DWORD dwIndex, IMFStreamSink** ppStreamSink)

インデックスで指定したストリームシンクを取得します。

dwIndex	DWORD	in	ストリームの 0 から始まるインデックス。ストリームの数を取得するには、IMFMediaSink::GetStreamSinkCount を呼び出します。
ppStreamSink	IMFStreamSink**	out	ストリームの IMFStreamSink インターフェイスへのポインターを受け取ります。呼び出し元はインターフェイスを解放しなければなりません。

戻り値

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

戻り値コード	説明
S_OK	メソッドは成功しました。
MF_E_INVALIDINDEX	無効なインデックスです。
MF_E_SHUTDOWN	メディアシンクの Shutdown メソッドが呼び出されています。

解説(Remarks)

ストリームシンクの列挙はスレッドセーフな操作ではありません。なぜなら、このメソッドの呼び出しの間にストリームシンクが追加または削除される可能性があるためです。

vtbl 8 HRESULT GetStreamSinkById(DWORD dwStreamSinkIdentifier, IMFStreamSink** ppStreamSink)

ストリーム識別子で指定したストリームシンクを取得します。

dwStreamSinkIdentifier	DWORD	in	ストリームシンクのストリーム識別子。
ppStreamSink	IMFStreamSink**	out	ストリームの IMFStreamSink インターフェイスへのポインターを受け取ります。呼び出し元はインターフェイスを解放しなければなりません。

戻り値

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

戻り値コード	説明
S_OK	メソッドは成功しました。
MF_E_INVALIDSTREAMNUMBER	ストリーム識別子が有効ではありません。
MF_E_SHUTDOWN	メディアシンクの Shutdown メソッドが呼び出されています。

解説(Remarks)

IMFMediaSink::AddStreamSink メソッドを呼び出してストリームシンクを追加した場合、ストリーム識別子はそのメソッドの dwStreamSinkIdentifier パラメーターで指定されます。メディアシンクが固定されたストリームのセットを持つ場合、メディアシンクがストリーム識別子を割り当てます。

ストリーム識別子ではなくインデックス番号でストリームを列挙するには、IMFMediaSink::GetStreamSinkByIndex を呼び出します。

vtbl 9 HRESULT SetPresentationClock(IMFPresentationClock* pPresentationClock)

メディアシンクにプレゼンテーションクロックを設定します。

pPresentationClock

IMFPresentationClock*

プレゼンテーションクロックの IMFPresentationClock インターフェイスへのポインター、または NULL。値が NULL の場合、メディアシンクは、以前に設定されていたプレゼンテーションクロックがあれば、そのリッスンを停止します。

戻り値

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

戻り値コード	説明
S_OK	メソッドは成功しました。
MF_E_CLOCK_NO_TIME_SOURCE	プレゼンテーションクロックにタイムソースがありません。プレゼンテーションクロックに対して SetTimeSource を呼び出してください。
MF_E_SHUTDOWN	メディアシンクの Shutdown メソッドが呼び出されています。

解説(Remarks)

ストリーミング中、メディアシンクはプレゼンテーションクロックとレートを一致させようとします。理想的には、メディアシンクはプレゼンテーションクロックに従って正しいタイミングでサンプルを提示し、遅れをとりません。レートレスなメディアシンクはこの規則の例外であり、可能な限り速くサンプルを消費してクロックを無視します。シンクがレートレスの場合、IMFMediaSink::GetCharacteristics メソッドは MEDIASINK_RATELESS フラグを返します。

プレゼンテーションクロックにはタイムソースが必要です。このメソッドを呼び出す前に、プレゼンテーションクロックに対して IMFPresentationClock::SetTimeSource を呼び出して、プレゼンテーションのタイムソースを設定してください。一部のメディアシンクはタイムソースを提供します。したがって、メディアシンクが自身のプレゼンテーションクロックのタイムソースになる場合があります。ただし、どのオブジェクトがタイムソースを提供する場合であっても、メディアシンクは pPresentationClock で指定されたクロックとレートを一致させようとしなければなりません。メディアシンクが外部タイムソースとレートを一致させることができない場合、メディアシンクの IMFMediaSink::GetCharacteristics メソッドは MEDIASINK_CANNOT_MATCH_CLOCK フラグを取得します。この場合、SetPresentationClock は成功しますが、結果は最適にはなりません。シンクは、プレゼンテーションクロックとレートを一致させるのに十分な速さでサンプルをレンダリングできない可能性があります。

pPresentationClock が非 NULL の場合、メディアシンクは、プレゼンテーションクロックに対して IMFPresentationClock::AddClockStateSink を呼び出して、クロック状態通知を登録しなければなりません。新しいプレゼンテーションクロックでこのメソッドが再度呼び出された場合、または pPresentationClock が NULL の場合、メディアシンクは IMFPresentationClock::RemoveClockStateSink を呼び出して、以前のクロックから自身の登録を解除しなければなりません。

すべてのメディアシンクはこのメソッドをサポートしなければなりません。

vtbl 10 HRESULT GetPresentationClock(IMFPresentationClock** ppPresentationClock)

メディアシンクに設定されたプレゼンテーションクロックを取得します。

ppPresentationClock

IMFPresentationClock**

out

プレゼンテーションクロックの IMFPresentationClock インターフェイスへのポインターを受け取ります。呼び出し元はインターフェイスを解放しなければなりません。

戻り値

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

戻り値コード	説明
S_OK	メソッドは成功しました。
MF_E_NO_CLOCK	クロックが設定されていません。プレゼンテーションクロックを設定するには、IMFMediaSink::SetPresentationClock を呼び出します。
MF_E_SHUTDOWN	メディアシンクの Shutdown メソッドが呼び出されています。

vtbl 11 HRESULT Shutdown()

メディアシンクをシャットダウンし、使用しているリソースを解放します。

戻り値

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

戻り値コード	説明
S_OK	メソッドは成功しました。
MF_E_SHUTDOWN	メディアシンクはシャットダウンされました。

解説(Remarks)

アプリケーションがメディアシンクを作成する場合、メモリまたはリソースのリークを回避するために Shutdown を呼び出す責任があります。ただし、ほとんどのアプリケーションでは、アプリケーションはメディアシンク用のアクティベーションオブジェクトを作成し、Media Session がそのオブジェクトを使用してメディアシンクを作成します。その場合、メディアシンクをシャットダウンするのは、アプリケーションではなく Media Session です。(詳細については、Activation Objects を参照してください。)

このメソッドが返された後、メディアシンク上のすべてのメソッドは MF_E_SHUTDOWN を返します。ただし、IUnknown メソッドおよび IMFMediaEventGenerator メソッドは除きます。このメソッドが呼び出された後、シンクはイベントを発生させません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMFMediaSink "{6EF2A660-47C0-4666-B13D-CBB717F2FA2C}"
#usecom global IMFMediaSink IID_IMFMediaSink "{}"
#comfunc global IMFMediaSink_GetCharacteristics    3 var
#comfunc global IMFMediaSink_AddStreamSink         4 int,sptr,sptr
#comfunc global IMFMediaSink_RemoveStreamSink      5 int
#comfunc global IMFMediaSink_GetStreamSinkCount    6 var
#comfunc global IMFMediaSink_GetStreamSinkByIndex  7 int,sptr
#comfunc global IMFMediaSink_GetStreamSinkById     8 int,sptr
#comfunc global IMFMediaSink_SetPresentationClock  9 sptr
#comfunc global IMFMediaSink_GetPresentationClock  10 sptr
#comfunc global IMFMediaSink_Shutdown              11
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IMFMediaSink "{6EF2A660-47C0-4666-B13D-CBB717F2FA2C}"
#usecom global IMFMediaSink IID_IMFMediaSink "{}"
#comfunc global IMFMediaSink_GetCharacteristics    3 sptr
#comfunc global IMFMediaSink_AddStreamSink         4 int,sptr,sptr
#comfunc global IMFMediaSink_RemoveStreamSink      5 int
#comfunc global IMFMediaSink_GetStreamSinkCount    6 sptr
#comfunc global IMFMediaSink_GetStreamSinkByIndex  7 int,sptr
#comfunc global IMFMediaSink_GetStreamSinkById     8 int,sptr
#comfunc global IMFMediaSink_SetPresentationClock  9 sptr
#comfunc global IMFMediaSink_GetPresentationClock  10 sptr
#comfunc global IMFMediaSink_Shutdown              11
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。