Método IMFPMediaPlayer::InsertEffect (mfplay.h)

Artigo
08/24/2023

Importante Preterido. Essa API pode ser removida de versões futuras do Windows. Os aplicativos devem usar a Sessão de Mídia para reprodução.

Aplica um efeito de áudio ou vídeo à reprodução.

Sintaxe

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

Parâmetros

[in] pEffect

Ponteiro para a interface IUnknown para um dos seguintes:

Uma transformação do Media Foundation (MFT) que implementa o efeito. Os MFTs expõem a interface IMFTransform .
Um objeto de ativação que cria um MFT. Objetos de ativação expõem a interface IMFActivate .

[in] fOptional

Especifica se o efeito é opcional.

Valor	Significado
VERDADE	O efeito é opcional. Se o objeto do player MFPlay não puder adicionar o efeito, ele ignorará o efeito e continuará a reprodução.
FALSE	Se o objeto do player MFPlay não puder adicionar o efeito, ocorrerá um erro de reprodução.

Retornar valor

O método retorna um HRESULT. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir.

Código de retorno	Descrição
S_OK	O método foi bem-sucedido.
MF_E_INVALIDINDEX	Esse efeito já foi adicionado.

Comentários

O objeto especificado no parâmetro pEffect pode implementar um efeito de vídeo ou um efeito de áudio. O efeito é aplicado a todos os itens de mídia definidos depois que o método é chamado. Ele não é aplicado ao item de mídia atual.

Para cada item de mídia, o efeito é aplicado ao primeiro fluxo selecionado do tipo correspondente (áudio ou vídeo). Se um item de mídia tiver dois fluxos selecionados do mesmo tipo, o segundo fluxo não receberá o efeito . O efeito será ignorado se o item de mídia não contiver um fluxo que corresponda ao tipo de efeito. Por exemplo, se você definir um efeito de vídeo e reproduzir um arquivo que contenha apenas áudio, o efeito de vídeo será ignorado, embora nenhum erro seja gerado.

O efeito é aplicado a todos os itens de mídia subsequentes, até que o aplicativo remova o efeito. Para remover um efeito, chame IMFPMediaPlayer::RemoveEffect ou IMFPMediaPlayer::RemoveAllEffects.

Se você definir vários efeitos do mesmo tipo (áudio ou vídeo), eles serão aplicados na mesma ordem em que você chama InsertEffect.

Otimizações de Reprodução Remota

Efeitos de áudio e vídeo podem ser incompatíveis com otimizações usadas para reprodução remota. As seguintes observações se aplicam somente a efeitos de áudio ou vídeo que são realmente usados durante a reprodução:

Se você marcar um efeito de áudio ou vídeo conforme necessário, definindo fOptional como FALSE, o MFPlay desabilita otimizações de reprodução remotas.
Caso contrário, se todos os efeitos de áudio/vídeo forem marcados como opcionais, o MFPlay poderá descartar os efeitos, a fim de habilitar otimizações de reprodução remota.

Em outras palavras, os efeitos necessários têm prioridade sobre otimizações remotas, mas efeitos opcionais não.

As otimizações remotas podem estar desabilitadas por outros motivos. Por exemplo, eles serão desabilitados se você definir a opção MFP_OPTION_NO_REMOTE_DESKTOP_OPTIMIZATION ao criar o objeto player. Nesse caso, o MFPlay tentará inserir quaisquer efeitos opcionais.

Efeitos não áudio e não vídeo não afetam otimizações remotas. Além disso, se você inserir um efeito necessário, mas a origem não contiver nenhum fluxo desse tipo, as otimizações remotas não serão desabilitadas.

Exemplos

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;
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	mfplay.h