IMFPMediaPlayer：：InsertEffect 方法 (mfplay.h)

项目
08/24/2023

重要废弃。此 API 可能会从 Windows 的未来版本中删除。应用程序应使用媒体会话进行播放。

将音频或视频效果应用于播放。

语法

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

参数

[in] pEffect

指向以下项之一的 IUnknown 接口的指针：

实现效果的媒体基础转换 (MFT) 。 MMFT 公开 IMFTransform 接口。
创建 MFT 的激活对象。激活对象公开 IMFActivate 接口。

[in] fOptional

指定效果是否可选。

值	含义
真	效果是可选的。如果 MFPlay 播放器对象无法添加该效果，它将忽略该效果并继续播放。
假	如果 MFPlay 播放器对象无法添加效果，则会发生播放错误。

返回值

该方法返回 HRESULT。可能的值包括（但并不限于）下表中的项。

返回代码	说明
S_OK	方法成功。
MF_E_INVALIDINDEX	已添加此效果。

注解

pEffect 参数中指定的对象可以实现视频效果或音频效果。该效果将应用于调用方法后设置的任何媒体项。它不适用于当前媒体项。

对于每个媒体项，效果将应用于匹配类型的第一个选择流， (音频或视频) 。如果媒体项具有两个相同类型的选定流，则第二个流不会收到效果。如果媒体项不包含与效果类型匹配的流，则忽略该效果。例如，如果设置视频效果并播放仅包含音频的文件，则会忽略视频效果，但不会引发错误。

该效果将应用于所有后续媒体项，直到应用程序删除该效果为止。若要删除效果，请调用 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