IMediaObject

IMediaObject インターフェイスは、Microsoft DirectX Media Object (DMO) を操作するためのメソッドを提供します。

GetStreamCount メソッドは、入力ストリームと出力ストリームの数を取得します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

DMO の入力ストリーム数または出力ストリーム数は 0 の場合があります。ストリーム数は変化しません。DMO が動的にストリームを追加したり削除したりすることはできません。

GetInputStreamInfo メソッドは、バッファーあたりのサンプル数に関する制約や、ストリームが入力データの先読み (ルックアヘッド) を行うかどうかなど、入力ストリームに関する情報を取得します。この情報が変化することはありません。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

DMO_INPUT_STREAMF_HOLDS_BUFFERS フラグは、DMO が入力データに対して先読みを行うことを示します。

アプリケーションは、DMO が入力を処理できるだけの十分なバッファーを確実に割り当てる必要があります。バッファー要件を調べるには、IMediaObject::GetInputSizeInfo メソッドを呼び出してください。

GetOutputStreamInfo メソッドは、ストリームが破棄可能かどうか、固定サンプルサイズを使用するかどうかなど、出力ストリームに関する情報を取得します。この情報が変化することはありません。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

GetInputType メソッドは、指定した入力ストリームで優先されるメディアタイプを取得します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

入力ストリームで優先されるメディアタイプを列挙するには、このメソッドを呼び出します。DMO は各メディアタイプに優先順にインデックス値を割り当てます。最も優先されるタイプのインデックスは 0 です。すべてのタイプを列挙するには、メソッドが DMO_E_NO_MORE_ITEMS を返すまで、タイプインデックスを増やしながら繰り返し呼び出します。DMO がサポートするすべてのメディアタイプを列挙するとは限りません。

返されるタイプのフォーマットブロックは NULL の場合があります。その場合、フォーマットタイプは GUID_NULL です。フォーマットブロックを参照する前に、フォーマットタイプを確認してください。

メソッドが成功した場合は、MoFreeMediaType を呼び出してフォーマットブロックを解放してください。(この関数はフォーマットブロックが NULL のときに呼び出しても安全です。)

メディアタイプを設定するには、IMediaObject::SetInputType メソッドを呼び出します。あるストリームにメディアタイプを設定すると、別のストリームで優先されるタイプが変化することがあります。実際、あるストリームは別のストリームにタイプが設定されるまで優先タイプを持たない場合があります。たとえば、デコーダーは入力タイプが設定されるまで優先される出力タイプを持たないことがあります。ただし、DMO がこのように優先タイプを動的に更新することは必須ではありません。したがって、このメソッドが返すタイプが有効である保証はなく、SetInputType メソッドで使用すると失敗する可能性があります。

特定のメディアタイプが受け入れられるかどうかをテストするには、DMO_SET_TYPEF_TEST_ONLY フラグを指定して SetInputType を呼び出します。

dwTypeIndex パラメーターが範囲内かどうかをテストするには、pmt に NULL を設定します。インデックスが範囲内であればメソッドは S_OK を返し、範囲外であれば DMO_E_NO_MORE_ITEMS を返します。

GetOutputType メソッドは、指定した出力ストリームで優先されるメディアタイプを取得します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

出力ストリームで優先されるメディアタイプを列挙するには、このメソッドを呼び出します。DMO は各メディアタイプに優先順にインデックス値を割り当てます。最も優先されるタイプのインデックスは 0 です。すべてのタイプを列挙するには、メソッドが DMO_E_NO_MORE_ITEMS を返すまで、タイプインデックスを増やしながら繰り返し呼び出します。DMO がサポートするすべてのメディアタイプを列挙するとは限りません。

返されるタイプのフォーマットブロックは NULL の場合があります。その場合、フォーマットタイプは GUID_NULL です。フォーマットブロックを参照する前に、フォーマットタイプを確認してください。

メソッドが成功した場合は、MoFreeMediaType を呼び出してフォーマットブロックを解放してください。(この関数はフォーマットブロックが NULL のときに呼び出しても安全です。)

メディアタイプを設定するには、IMediaObject::SetOutputType メソッドを呼び出します。あるストリームにメディアタイプを設定すると、別のストリームで優先されるタイプが変化することがあります。実際、あるストリームは別のストリームにタイプが設定されるまで優先タイプを持たない場合があります。たとえば、デコーダーは入力タイプが設定されるまで優先される出力タイプを持たないことがあります。ただし、DMO がこのように優先タイプを動的に更新することは必須ではありません。したがって、このメソッドが返すタイプが有効である保証はなく、SetOutputType メソッドで使用すると失敗する可能性があります。

特定のメディアタイプが受け入れられるかどうかをテストするには、DMO_SET_TYPEF_TEST_ONLY フラグを指定して SetOutputType を呼び出します。

dwTypeIndex パラメーターが範囲内かどうかをテストするには、pmt に NULL を設定します。インデックスが範囲内であればメソッドは S_OK を返し、範囲外であれば DMO_E_NO_MORE_ITEMS を返します。

SetInputType メソッドは、入力ストリームにメディアタイプを設定するか、メディアタイプが受け入れ可能かどうかをテストします。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

入力ストリームのメディアタイプをテスト、設定、またはクリアするには、このメソッドを呼び出します。

• 設定せずにメディアタイプをテストするには、DMO_SET_TYPEF_TEST_ONLY フラグを使用します。メディアタイプが受け入れ可能でない場合、メソッドは S_FALSE を返します。
• メディアタイプを設定するには、dwFlags を 0 に設定します。メディアタイプが受け入れられない場合、メソッドは DMO_E_TYPE_NOT_ACCEPTED を返します。
• 現在のメディアタイプ (設定されている場合) をクリアするには、DMO_SET_TYPEF_CLEAR フラグを使用し、pmt に NULL を設定します。メソッドから復帰すると、そのストリームはメディアタイプを持たなくなります。アプリケーションが新しいメディアタイプを設定するまで、DMO はサンプルを処理できません。

SetOutputType メソッドは、出力ストリームにメディアタイプを設定するか、メディアタイプが受け入れ可能かどうかをテストします。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

出力ストリームのメディアタイプをテスト、設定、またはクリアするには、このメソッドを呼び出します。

• 設定せずにメディアタイプをテストするには、DMO_SET_TYPEF_TEST_ONLY フラグを使用します。メディアタイプが受け入れ可能でない場合、メソッドは S_FALSE を返します。
• メディアタイプを設定するには、dwFlags を 0 に設定します。メディアタイプが受け入れられない場合、メソッドは DMO_E_TYPE_NOT_ACCEPTED を返します。
• 現在のメディアタイプ (設定されている場合) をクリアするには、DMO_SET_TYPEF_CLEAR フラグを使用し、pmt に NULL を設定します。メソッドから復帰すると、そのストリームはメディアタイプを持たなくなります。ストリームが省略可能でない限り、アプリケーションが新しいメディアタイプを設定するまで DMO はサンプルを処理できません。

GetInputCurrentType メソッドは、入力ストリームに設定されているメディアタイプがあれば、それを取得します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

呼び出し元は、このメソッドを呼び出す前にストリームのメディアタイプを設定しておく必要があります。メディアタイプを設定するには、IMediaObject::SetInputType メソッドを呼び出します。

メソッドが成功した場合は、MoFreeMediaType を呼び出してフォーマットブロックを解放してください。

GetOutputCurrentType メソッドは、出力ストリームに設定されているメディアタイプがあれば、それを取得します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

呼び出し元は、このメソッドを呼び出す前にストリームのメディアタイプを設定しておく必要があります。メディアタイプを設定するには、IMediaObject::SetOutputType メソッドを呼び出します。

メソッドが成功した場合は、MoFreeMediaType を呼び出してフォーマットブロックを解放してください。

GetInputSizeInfo メソッドは、指定した入力ストリームのバッファー要件を取得します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

バッファー要件は、各ストリームのメディアタイプに依存する場合があります。このメソッドを呼び出す前に、IMediaObject::SetInputType および IMediaObject::SetOutputType メソッドを呼び出して各ストリームのメディアタイプを設定してください。メディアタイプが設定されていない場合、このメソッドはエラーを返すことがあります。

DMO が入力ストリームで先読みを行う場合、IMediaObject::GetInputStreamInfo メソッドで DMO_INPUT_STREAMF_HOLDS_BUFFERS フラグを返します。処理中、DMO は pcbMaxLookahead パラメーターで示されるバイト数まで保持します。アプリケーションは、DMO がこの量のデータを保持できるだけの十分なバッファーを割り当てる必要があります。

バッファーの開始アドレスが *pcbAlignment の倍数である場合、そのバッファーはアラインされているといいます。アラインメントは 2 のべき乗でなければなりません。マイクロプロセッサによっては、アラインされたバッファーへの読み書きは、アラインされていないバッファーへの読み書きより高速な場合があります。また、アラインされていない読み書きをサポートしないマイクロプロセッサもあります。

GetOutputSizeInfo メソッドは、指定した出力ストリームのバッファー要件を取得します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

バッファー要件は、各ストリームに設定されたメディアタイプに依存する場合があります。

このメソッドを呼び出す前に、IMediaObject::SetInputType および IMediaObject::SetOutputType メソッドを呼び出して各ストリームのメディアタイプを設定してください。メディアタイプが設定されていない場合、このメソッドはエラーを返すことがあります。ただし、ストリームが省略可能で、アプリケーションがそのストリームを使用しない場合は、そのストリームのメディアタイプを設定する必要はありません。

バッファーの開始アドレスが *pcbAlignment の倍数である場合、そのバッファーはアラインされているといいます。マイクロプロセッサのアーキテクチャによっては、アラインされたバッファーへの読み書きの方が、アラインされていないバッファーへの読み書きより高速です。一部のマイクロプロセッサでは、アラインされていないバッファーへの読み書きはサポートされておらず、プログラムがクラッシュする可能性があります。0 は有効なアラインメントではありません。

GetInputMaxLatency メソッドは、指定した入力ストリームの最大レイテンシを取得します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

レイテンシとは、入力ストリーム上のタイムスタンプと、それに対応する出力ストリーム上のタイムスタンプとの差です。最大レイテンシは、タイムスタンプの差として起こりうる最大値です。DMO の最大レイテンシは、次のようにして求めます。

• DMO が出力を生成できるようになるまで入力バッファーを処理します。
• 可能な限り多くの出力バッファーを処理します。
• 最大レイテンシは、入力タイムスタンプと出力タイムスタンプの差 (絶対値) の最大値です。

DMO が一度に 1 サンプルのみを処理する特別なケースでは、最大レイテンシは単にタイムスタンプの差になります。

レイテンシは、サンプルにタイムスタンプがあり、そのタイムスタンプが単調に増加または減少している場合にのみ定義されます。最大レイテンシは、入力ストリームおよび出力ストリームのメディアタイプに依存する場合があります。

SetInputMaxLatency メソッドは、指定した入力ストリームの最大レイテンシを設定します。最大レイテンシの定義については、IMediaObject::GetInputMaxLatency を参照してください。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

Flush メソッドは、内部にバッファリングされているすべてのデータをフラッシュします。

成功した場合は S_OK を返します。それ以外の場合は、エラーの原因を示す HRESULT 値を返します。

このメソッドが呼び出されると、DMO は次の処理を行います。

• 保持しているすべての IMediaBuffer 参照を解放します。
• メディアバッファーのタイムスタンプやサンプル長を指定する値をすべて破棄します。
• メディアサンプルの内容に依存する内部状態を再初期化します。

メソッドから復帰すると、すべての入力ストリームがデータを受け入れる状態になります。アプリケーションが少なくとも 1 つの入力ストリームに対して IMediaObject::ProcessInput メソッドを呼び出すまで、出力ストリームはデータを生成できません。

Discontinuity メソッドは、指定した入力ストリームでの不連続 (ディスコンティニュイティ) を通知します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

不連続とは、入力の途切れを表します。不連続は、これ以上データが見込まれない場合、フォーマットが変更される場合、またはデータに欠落がある場合などに発生します。不連続の後、DMO は保留中のデータをすべて処理し終えるまで、そのストリームでさらなる入力を受け入れません。アプリケーションは、いずれのストリームも DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE フラグを返さなくなるまで、IMediaObject::ProcessOutput メソッドを呼び出してください。

クライアントが DMO に入力タイプと出力タイプを設定する前にこのメソッドを呼び出すと、失敗する場合があります。

AllocateStreamingResources メソッドは、DMO が必要とするリソースを割り当てます。このメソッドの呼び出しは常に省略可能です。

成功した場合は S_OK を返します。それ以外の場合は、エラーの原因を示す HRESULT 値を返します。

アプリケーションは、ストリーミングの最適化としてこのメソッドを呼び出すことができます。これにより、ストリーミング開始前に時間のかかる初期化を行う機会が DMO に与えられます。このメソッドを呼び出す場合は、DMO にメディアタイプを設定した後、かつ ProcessInput または ProcessOutput を最初に呼び出す前に行ってください。

このメソッドは、次の意味で省略可能です。

• DMO がこのメソッドをサポートしていない場合、メソッドは S_OK を返します。
• アプリケーションがこのメソッドを一度も呼び出さない場合、DMO は IMediaObject::ProcessInput または IMediaObject::ProcessOutput の呼び出し内でリソースを割り当てます。

FreeStreamingResources メソッドは、DMO が割り当てたリソースを解放します。このメソッドの呼び出しは常に省略可能です。

成功した場合は S_OK を返します。それ以外の場合は、エラーの原因を示す HRESULT 値を返します。

このメソッドは、IMediaObject::AllocateStreamingResources メソッドが初期化したリソースを解放します。

DMO がこのメソッドをサポートしていない場合、メソッドは S_OK を返します。ストリーミング中にこのメソッドを呼び出した場合、メソッドは失敗し、DMO はリソースを解放しません。

メソッドが失敗しても成功しても、アプリケーションは DMO の他のメソッドを引き続き呼び出すことができます。DMO は、以前に解放したリソースを再初期化する必要が生じる場合があります。

GetInputStatus メソッドは、入力ストリームがさらに入力データを受け入れられるかどうかを問い合わせます。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

入力ストリームがさらにデータを受け入れられる場合、メソッドは dwFlags パラメーターに DMO_INPUT_STATUSF_ACCEPT_DATA フラグを返します。そうでない場合は、このパラメーターを 0 に設定します。ストリームがさらにデータを受け入れられる場合、アプリケーションは IMediaObject::ProcessInput メソッドを呼び出すことができます。

入力ストリームの状態は、次のいずれかのメソッド呼び出しの結果としてのみ変化します。

ProcessInput メソッドは、指定した入力ストリームにバッファーを渡します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

pBuffer パラメーターで指定する入力バッファーは読み取り専用です。DMO がこのバッファー内のデータを変更することはありません。書き込み操作はすべて出力バッファーに対して行われ、出力バッファーは IMediaObject::ProcessOutput メソッドの呼び出しで別途渡されます。

DMO がバッファー内のデータをすべて処理しない場合、DMO はそのバッファーの参照カウントを保持します。データの先読みを行う必要がある場合を除き、すべての出力を生成した時点でバッファーを解放します。(DMO が先読みを行うかどうかを調べるには、IMediaObject::GetInputStreamInfo メソッドを呼び出します。)

このメソッドが DMO_E_NOTACCEPTING を返した場合は、入力ストリームがさらにデータを受け入れられるようになるまで ProcessOutput を呼び出してください。ストリームがさらにデータを受け入れられるかどうかを調べるには、IMediaObject::GetInputStatus メソッドを呼び出します。

メソッドが S_FALSE を返した場合、この入力からは出力が生成されておらず、アプリケーションが ProcessOutput を呼び出す必要はありません。ただし、この状況で DMO が S_FALSE を返すことは必須ではなく、S_OK を返す場合もあります。

ProcessOutput メソッドは、現在の入力データから出力を生成します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

pOutputBuffers パラメーターは、DMO_OUTPUT_DATA_BUFFER 構造体の配列を指します。アプリケーションは出力ストリームごとに 1 つの構造体を割り当てる必要があります。出力ストリームの数を調べるには、IMediaObject::GetStreamCount メソッドを呼び出します。cOutputBufferCount パラメーターにはこの数を設定します。

各 DMO_OUTPUT_DATA_BUFFER 構造体には、バッファーの IMediaBuffer インターフェイスへのポインターが含まれます。これらのバッファーはアプリケーションが割り当てます。構造体の他のメンバーはステータスフィールドです。メソッドが成功した場合、DMO はこれらのフィールドを設定します。メソッドが失敗した場合、これらの値は未定義です。

アプリケーションが ProcessOutput を呼び出すと、DMO は可能な限り多くの入力データを処理します。DMO は各バッファー内のデータの末尾から出力データを書き込みます。(データの末尾を調べるには、IMediaBuffer::GetBufferAndLength メソッドを呼び出します。) DMO が出力バッファーの参照カウントを保持することはありません。

DMO が出力バッファーをすべて埋めてもなお処理すべき入力データが残っている場合、DMO は DMO_OUTPUT_DATA_BUFFER 構造体に DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE フラグを返します。アプリケーションは、各構造体の dwStatus メンバーを調べてこのフラグを確認してください。

メソッドが S_FALSE を返した場合、出力は生成されていません。ただし、この状況で DMO が S_FALSE を返すことは必須ではなく、S_OK を返す場合もあります。

データの破棄:

dwFlags パラメーターに DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER フラグを設定すると、ストリームのデータを破棄できます。破棄したいストリームごとに、DMO_OUTPUT_DATA_BUFFER 構造体の pBuffer メンバーを NULL に設定します。

pBuffer が NULL である各ストリームについて、次のように動作します。

• DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER フラグが設定されていて、そのストリームが破棄可能または省略可能である場合、DMO はデータを破棄します。
• フラグが設定されているが、そのストリームが破棄可能でも省略可能でもない場合、DMO は可能であればデータを破棄します。ただし、破棄されることは保証されません。
• フラグが設定されていない場合、DMO はそのストリームの出力データを生成しませんが、データを破棄することもありません。

Lock メソッドは、DMO のロックを取得または解放します。複数の操作を行う際に DMO の直列化 (シリアル化) を維持するには、このメソッドを呼び出します。

HRESULT 値を返します。指定できる値には次の表の値が含まれます。

このメソッドは、他のスレッドが DMO のメソッドを呼び出すことを防ぎます。他のスレッドが DMO のメソッドを呼び出すと、そのスレッドはロックが解放されるまでブロックされます。

Active Template Library (ATL) を使用して DMO を実装する場合、Lock メソッドの名前が CComObjectRootEx::Lock メソッドと衝突します。この問題を回避するには、ヘッダーファイル Dmo.h をインクルードする前に、プリプロセッサシンボル FIX_LOCK_NAME を定義してください。

#define FIX_LOCK_NAME
#include <dmo.h>

このディレクティブにより、プリプロセッサは IMediaObject のメソッド名を DMOLock に変更します。ご自身の DMO では、このメソッドを DMOLock として実装してください。実装内では、bLock の値に応じて ATL の Lock または Unlock メソッドを呼び出します。vtable の順序は変わらないため、アプリケーションは引き続き Lock という名前でメソッドを呼び出すことができます。