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

IMediaSample

COM
📘 Microsoft Learn (日本語) · English
IID56a8689a-0ad4-11ce-b03a-0020af0ba770継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IMediaSample インターフェイスは、メディアサンプルのプロパティを設定および取得します。

メソッド 16

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

vtbl 3 HRESULT GetPointer(BYTE** ppBuffer)

GetPointer メソッドは、メディアサンプルのバッファへの読み書き可能なポインターを取得します。

ppBufferBYTE**outバッファへのポインターを受け取ります。

戻り値

成功した場合は S_OK を返します。失敗した場合は、エラーの原因を示す HRESULT 値を返します。

解説(Remarks)

バッファメモリはメディアサンプルオブジェクトが所有しており、メディアサンプルが破棄される際に自動的に解放されます。呼び出し元がバッファを解放または再割り当てしてはなりません。

vtbl 4 INT GetSize()

GetSize メソッドは、バッファのサイズを取得します。

戻り値

バッファのサイズをバイト単位で返します。このサイズには、プレフィックスバイト（存在する場合）は含まれません。

vtbl 5 HRESULT GetTime(LONGLONG* pTimeStart, LONGLONG* pTimeEnd)

GetTime メソッドは、このサンプルの再生を開始および終了すべきストリーム時刻を取得します。

pTimeStartLONGLONG*out開始時刻を受け取る変数へのポインター。
pTimeEndLONGLONG*out停止時刻を受け取る変数へのポインター。サンプルに停止時刻がない場合、この値は開始時刻に 1 を加えた値に設定されます。

戻り値

HRESULT 値を返します。設定可能な値には次の表に示すものが含まれます。

戻り値 説明
S_OK
 成功。サンプルには有効な開始時刻と停止時刻があります。
VFW_S_NO_STOP_TIME
 サンプルには有効な開始時刻がありますが、停止時刻はありません。
VFW_E_SAMPLE_TIME_NOT_SET
 サンプルにタイムスタンプが付与されていません。

解説(Remarks)

どちらの時刻値もストリーム時刻を基準としています。詳細については、Time and Clocks in DirectShow を参照してください。

vtbl 6 HRESULT SetTime(LONGLONG* pTimeStart, LONGLONG* pTimeEnd)

SetTime メソッドは、このサンプルの再生を開始および終了すべきストリーム時刻を設定します。

pTimeStartLONGLONG*inoptionalサンプルの開始時刻を格納する変数へのポインター。
pTimeEndLONGLONG*inoptionalサンプルの停止時刻を格納する変数へのポインター。

戻り値

成功した場合は S_OK を返します。失敗した場合は、エラーの原因を示す HRESULT 値を返します。

解説(Remarks)

どちらの時刻値もストリーム時刻を基準としています。詳細については、Time and Clocks in DirectShow を参照してください。

ストリーム時刻を無効化するには、pTimeStart と pTimeEnd を NULL に設定します。これにより、IMediaSample::GetTime メソッドは VFW_E_SAMPLE_TIME_NOT_SET を返すようになります。

ストリーム時刻の詳細については、Time and Clocks in DirectShow を参照してください。

vtbl 7 HRESULT IsSyncPoint()

IsSyncPoint メソッドは、このサンプルの先頭が同期ポイントかどうかを判定します。

戻り値

サンプルが同期ポイントである場合は S_OK を返します。そうでない場合は S_FALSE を返します。

解説(Remarks)

フィルターは任意の同期ポイントからストリームを開始できます。一部の圧縮形式では、ストリーム内の特定のポイント（たとえばキーフレーム）でのみストリーミングを開始できます。AM_MEDIA_TYPE 構造体の bTemporalCompression メンバーが FALSE の場合、すべてのサンプルが同期ポイントになります。

vtbl 8 HRESULT SetSyncPoint(BOOL bIsSyncPoint)

SetSyncPoint メソッドは、このサンプルの先頭が同期ポイントであるかどうかを指定します。

bIsSyncPointBOOLinこれが同期ポイントであるかどうかを指定するブール値。TRUE の場合、これは同期ポイントです。

戻り値

成功した場合は S_OK を返します。失敗した場合は、エラーの原因を示す HRESULT 値を返します。

解説(Remarks)

サンプル内のデータを最初に生成するフィルターは、適切に応じてこのフラグを TRUE または FALSE に設定する必要があります。非圧縮ビデオおよび PCM オーディオの場合は、すべてのサンプルを TRUE に設定します。圧縮ビデオの場合は、キーフレームを TRUE に、差分フレームを FALSE に設定します。

このフラグはあくまで情報提供用です。下流の他のフィルターがこのフラグを確認する場合があります。たとえば、あるフィルターが次のキーフレームまでスキップする必要がある場合などです。

vtbl 9 HRESULT IsPreroll()

IsPreroll メソッドは、このサンプルがプリロールサンプルかどうかを判定します。プリロールサンプルは表示すべきではありません。

戻り値

サンプルがプリロールサンプルである場合は S_OK を返します。そうでない場合は S_FALSE を返します。

解説(Remarks)

プリロールサンプルは処理されますが表示されません。プリロールサンプルは、表示対象のサンプルよりも前のメディアストリーム内に配置されます。

vtbl 10 HRESULT SetPreroll(BOOL bIsPreroll)

SetPreroll メソッドは、このサンプルがプリロールサンプルであるかどうかを指定します。

bIsPrerollBOOLinこれがプリロールサンプルであるかどうかを指定するブール値。TRUE の場合、これはプリロールサンプルです。

戻り値

成功した場合は S_OK を返します。失敗した場合は、エラーの原因を示す HRESULT 値を返します。

vtbl 11 INT GetActualDataLength()

GetActualDataLength メソッドは、バッファ内の有効なデータの長さを取得します。

戻り値

有効なデータの長さをバイト単位で返します。

vtbl 12 HRESULT SetActualDataLength(INT __MIDL__IMediaSample0000)

SetActualDataLength メソッドは、バッファ内の有効なデータの長さを設定します。

__MIDL__IMediaSample0000INTinメディアサンプル内のデータの長さ（バイト単位）。

戻り値

HRESULT 値を返します。設定可能な値には次の表に示すものが含まれます。

戻り値 説明
S_OK
 成功。
VFW_E_BUFFER_OVERFLOW.
 lLen で指定された長さがバッファサイズより大きくなっています。
vtbl 13 HRESULT GetMediaType(AM_MEDIA_TYPE** ppMediaType)

GetMediaType メソッドは、メディアタイプが前のサンプルと異なる場合に、そのメディアタイプを取得します。

ppMediaTypeAM_MEDIA_TYPE**outAM_MEDIA_TYPE 構造体へのポインターを受け取る変数のアドレス。メディアタイプが前のサンプルから変化していない場合、*ppMediaType は NULL に設定されます。

戻り値

HRESULT 値を返します。設定可能な値には次の表に示すものが含まれます。

戻り値 説明
S_FALSE
 メディアタイプは前のサンプルから変化していません。
S_OK
 成功。
E_OUTOFMEMORY
 メモリが不足しています。

解説(Remarks)

このメソッドを使用すると、フィルターはパレットの変更など、メディアタイプに対する限定的な変更を行うことができます。メディアタイプに大きな変更を加えるには、ピンの再接続とメディアタイプの再ネゴシエーションが必要になる場合があります。

メソッドが S_OK を返した場合、呼び出し元はフォーマットブロックを含むメディアタイプのメモリを解放する必要があります。DirectShow 基底クラスライブラリの DeleteMediaType 関数を使用できます。

vtbl 14 HRESULT SetMediaType(AM_MEDIA_TYPE* pMediaType)

SetMediaType メソッドは、サンプルのメディアタイプを設定します。

pMediaTypeAM_MEDIA_TYPE*inメディアタイプを指定する AM_MEDIA_TYPE 構造体へのポインター。

戻り値

HRESULT 値を返します。設定可能な値には次の表に示すものが含まれます。

戻り値 説明
S_OK
 成功
E_OUTOFMEMORY
 メモリが不足しています

解説(Remarks)

既定では、すべてのサンプルは前のサンプルと同じメディアタイプを持ちます。（元のメディアタイプはピンの接続によって決定されます。）パレットの変更など、メディアタイプに対する限定的な変更を行うには、このメソッドを呼び出します。メディアタイプに大きな変更を加えるには、ピンの再接続とメディアタイプの再ネゴシエーションが必要になる場合があります。

vtbl 15 HRESULT IsDiscontinuity()

IsDiscontinuity メソッドは、このサンプルがデータストリームの中断を表しているかどうかを判定します。

戻り値

サンプルがデータストリームの中断である場合は S_OK を返します。そうでない場合は S_FALSE を返します。

解説(Remarks)

不連続（discontinuity）は、フィルターがストリーム内の別の位置へシークした場合や、品質管理のためにサンプルをドロップした場合に発生します。

vtbl 16 HRESULT SetDiscontinuity(BOOL bDiscontinuity)

SetDiscontinuity メソッドは、このサンプルがデータストリームの中断を表しているかどうかを指定します。

bDiscontinuityBOOLinこのサンプルが不連続であるかどうかを指定するブール値。TRUE の場合、メディアサンプルは前のサンプルと不連続です。

戻り値

成功した場合は S_OK を返します。失敗した場合は、エラーの原因を示す HRESULT 値を返します。

vtbl 17 HRESULT GetMediaTime(LONGLONG* pTimeStart, LONGLONG* pTimeEnd)

GetMediaTime メソッドは、このサンプルのメディア時刻を取得します。

pTimeStartLONGLONG*outメディア開始時刻を受け取る変数へのポインター。
pTimeEndLONGLONG*outメディア停止時刻を受け取る変数へのポインター。

戻り値

HRESULT 値を返します。設定可能な値には次の表に示すものが含まれます。

戻り値 説明
S_OK
 成功。
VFW_E_MEDIA_TIME_NOT_SET
 このサンプルにはメディア時刻が設定されていません。

解説(Remarks)

メディア時刻の詳細については、Time and Clocks in DirectShow を参照してください。

vtbl 18 HRESULT SetMediaTime(LONGLONG* pTimeStart, LONGLONG* pTimeEnd)

SetMediaTime メソッドは、このサンプルのメディア時刻を設定します。

pTimeStartLONGLONG*inoptional開始メディア時刻へのポインター。
pTimeEndLONGLONG*inoptional終了メディア時刻へのポインター。

戻り値

成功した場合は S_OK を返します。失敗した場合は、エラーの原因を示す HRESULT 値を返します。

解説(Remarks)

メディア時刻を無効化するには、pTimeStart と pTimeEnd を NULL に設定します。これにより、IMediaSample::GetMediaTime メソッドは VFW_E_MEDIA_TIME_NOT_SET を返すようになります。

メディア時刻の詳細については、Time Stamps を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMediaSample "{56A8689A-0AD4-11CE-B03A-0020AF0BA770}"
#usecom global IMediaSample IID_IMediaSample "{}"
#comfunc global IMediaSample_GetPointer           3 var
#comfunc global IMediaSample_GetSize              4
#comfunc global IMediaSample_GetTime              5 var,var
#comfunc global IMediaSample_SetTime              6 var,var
#comfunc global IMediaSample_IsSyncPoint          7
#comfunc global IMediaSample_SetSyncPoint         8 int
#comfunc global IMediaSample_IsPreroll            9
#comfunc global IMediaSample_SetPreroll           10 int
#comfunc global IMediaSample_GetActualDataLength  11
#comfunc global IMediaSample_SetActualDataLength  12 int
#comfunc global IMediaSample_GetMediaType         13 var
#comfunc global IMediaSample_SetMediaType         14 var
#comfunc global IMediaSample_IsDiscontinuity      15
#comfunc global IMediaSample_SetDiscontinuity     16 int
#comfunc global IMediaSample_GetMediaTime         17 var,var
#comfunc global IMediaSample_SetMediaTime         18 var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。