IMFPMediaPlayer::InsertEffect メソッド (mfplay.h)

  • [アーティクル]
大事な 廃止。 この API は、今後の Windows リリースから削除される可能性があります。 アプリケーションでは、再生に メディア セッション を使用する必要があります。
 

オーディオまたはビデオ効果を再生に適用します。

構文

HRESULT InsertEffect(
  [in] IUnknown *pEffect,
  [in] BOOL     fOptional
);

パラメーター

[in] pEffect

次のいずれかの IUnknown インターフェイスへのポインター。

  • 効果を実装する Media Foundation 変換 (MFT)。 MFT は IMFTransform インターフェイスを公開します。
  • MFT を作成するアクティブ化オブジェクト。 アクティブ化オブジェクトは、 IMFActivate インターフェイスを公開します。

[in] fOptional

効果が省略可能かどうかを指定します。

値 意味
True
 効果は省略可能です。 MFPlay プレーヤー オブジェクトが効果を追加できない場合、その効果は無視され、再生が続行されます。
False
 MFPlay プレーヤー オブジェクトが効果を追加できない場合は、再生エラーが発生します。

戻り値

このメソッドは HRESULT を返します。 有効な値を次の表に示しますが、これ以外にもあります。

リターン コード 説明
S_OK
 メソッドが成功しました。
MF_E_INVALIDINDEX
 この効果は既に追加されています。

注釈

pEffect パラメーターで指定されたオブジェクトは、ビデオ効果またはオーディオ効果を実装できます。 効果は、 メソッドの呼び出し後に設定されたすべてのメディア項目に適用されます。 現在のメディア項目には適用されません。

メディア項目ごとに、一致する種類 (オーディオまたはビデオ) の最初に選択されたストリームに効果が適用されます。 メディア アイテムに同じ種類の 2 つのストリームが選択されている場合、2 番目のストリームは効果を受け取りません。 効果の種類に一致するストリームがメディア項目に含まれていない場合、効果は無視されます。 たとえば、ビデオ効果を設定し、オーディオのみを含むファイルを再生した場合、エラーは発生しませんが、ビデオ効果は無視されます。

この効果は、アプリケーションが効果を削除するまで、後続のすべてのメディア項目に適用されます。 効果を削除するには、 IMFPMediaPlayer::RemoveEffect または IMFPMediaPlayer::RemoveAllEffects を呼び出します。

同じ種類 (オーディオまたはビデオ) の複数の効果を設定すると、 InsertEffect を呼び出すのと同じ順序で適用されます。

リモート再生の最適化

オーディオとビデオの効果は、リモート再生に使用される最適化と互換性がない可能性があります。 次の解説は、再生中に実際に使用されるオーディオまたはビデオの効果にのみ適用されます。
  • 必要に応じてオーディオまたはビデオ効果をマークした場合、 fOptional を FALSE に設定すると、MFPlay はリモート再生の最適化を無効にします。
  • それ以外の場合、すべてのオーディオ/ビデオ効果がオプションとしてマークされている場合、MFPlay はリモート再生の最適化を有効にするために効果をドロップする可能性があります。
つまり、必要な効果はリモート最適化よりも優先されますが、オプションの効果は優先されません。

リモート最適化は、他の理由で無効になっている可能性があります。 たとえば、プレーヤー オブジェクトの作成時に MFP_OPTION_NO_REMOTE_DESKTOP_OPTIMIZATION オプションを設定すると、無効になります。 その場合、MFPlay はオプションの効果を挿入しようとします。

非オーディオ、ビデオ以外の効果は、リモートの最適化には影響しません。 また、必要な効果を挿入しても、ソースにその種類のストリームが含まれていない場合、リモート最適化は無効になりません。

例

HRESULT AddPlaybackEffect(REFGUID clsid, IMFPMediaPlayer *pPlayer)
{
    IMFTransform *pMFT = NULL;

    HRESULT hr = CoCreateInstance(clsid, NULL, CLSCTX_INPROC_SERVER, 
        IID_PPV_ARGS(&pMFT));

    if (SUCCEEDED(hr))
    {
        hr = pPlayer->InsertEffect(pMFT, TRUE); // Set as optional.
    }

    SafeRelease(&pMFT);
    return hr;
}

要件

要件 値
サポートされている最小のクライアント Windows 7 [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 R2 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー mfplay.h

こちらもご覧ください

オーディオまたはビデオ効果を追加する方法

IMFPMediaPlayer

オーディオ/ビデオ再生に MFPlay を使用する