Criando um MFT de driver de câmera para um aplicativo de dispositivo UWP

Artigo
02/29/2024

Importante

Este tópico foi preterido. Consulte o Guia de design de MFT do dispositivo para obter orientações atualizadas.

Os aplicativos de dispositivo UWP permitem que os fabricantes de dispositivos apliquem configurações personalizadas e efeitos especiais no fluxo de vídeo da câmera com um driver de câmera MFT (media foundation transform). Este tópico apresenta MFTs de driver e usa o exemplo de MFT de driver para mostrar como criar um. Para saber mais sobre aplicativos de dispositivo UWP em geral, consulte Conhecer os aplicativos de dispositivo UWP.

O MFT de driver

Esta seção descreve o MFT (Media Foundation Transform) que você cria para aplicar efeitos ao fluxo de captura de mídia proveniente da câmera. É assim que você fornece transformações para efeitos de cor, modos de esquema e efeitos de rastreamento facial que realmente distinguem sua câmera das outras. Esse MFT, conhecido como MFT de driver, é aplicado pela primeira vez ao fluxo de vídeo conectado proveniente do driver da câmera quando um aplicativo UWP inicia a captura de vídeo. Quando esse aplicativo invoca a interface do usuário de Opções de câmera, o Windows fornece automaticamente todas as interfaces que o MFT de driver implementa para controlar seus efeitos personalizados.

the camera driver mft helps a windows store device app provide custom effects.

Um MFT de driver não é necessário para um aplicativo de dispositivo UWP. Um fabricante de dispositivo pode optar por implementar um aplicativo de dispositivo UWP sem um MFT de driver, simplesmente para fornecer uma interface de usuário diferenciada contendo marca para seu hardware, sem aplicar configurações personalizadas e efeitos especiais ao fluxo de vídeo.

Como um MFT de driver é usado

O aplicativo de dispositivo UWP para uma câmera é executado em um processo diferente do aplicativo da Microsoft Store que o invoca pela API CameraCaptureUI. Para que o aplicativo de dispositivo da Microsoft Store controle um MFT de driver, uma sequência específica de eventos em diferentes espaços de processo deve ocorrer.

Um aplicativo UWP deseja capturar uma foto, por isso chama o método CaptureFileAsync
O Windows solicita o ponteiro MFT do driver e o ID do dispositivo da câmera
O ponteiro MFT do driver é passado para um host de configurações
O host consulta as propriedades do dispositivo para o ID do aplicativo da Microsoft Store associado à câmera (por metadados do dispositivo)
Se nenhum aplicativo de dispositivo UWP for encontrado, o submenu padrão interage com o mecanismo de captura
Se um aplicativo de dispositivo UWP for encontrado, ele será ativado, e o host de configurações passará o ponteiro MFT do driver para ele
O aplicativo de dispositivo UWP controla o MFT do driver usando a interface exposta por meio do ponteiro

the process interaction for invoking a windows store device app.

Requisito do modelo de driver AvStream

O driver da câmera deve usar o modelo de driver AvStream. Para obter mais informações sobre o modelo de driver AVStream, consulte Guia de criação de minidrivers AVStream.

Como o MFT de driver é exposto aos aplicativos

Um MFT de driver é registrado no Windows como uma interface COM para que a transformação implementada possa ser aplicada ao fluxo de mídia que sai de um dispositivo específico, como uma câmera.

Observação

Um MFT de driver não deve ser registrado usando a função MFTRegister porque é específico do dispositivo e não um MFT de propósito geral. Para obter informações sobre a chave do registro, consulte a seção Instalando e registrando o MFT de driver mais adiante neste tópico.

Quando um aplicativo inicia uma captura de vídeo, um Media Foundation Source Reader é instanciado para fornecer o fluxo de vídeo. Essa fonte de mídia lê um valor do registro da chave do registro do dispositivo. Se o CLSID da classe COM do MFT de driver for encontrado no valor do registro, o leitor de origem instanciará o MFT do driver e o inserirá no pipeline de mídia.

Além dos aplicativos de dispositivo UWP, a funcionalidade MFT do driver pode ser acessada quando o dispositivo associado a ele é usado para capturar vídeo usando as seguintes APIs:

Tags HTML5 <video> em um aplicativo UWP usando HTML. As transformações que o driver MFT habilitou afetarão o vídeo que está sendo reproduzido usando o elemebro <video>, como no exemplo de código a seguir:
```
var video = document.getElementById('myvideo');
    video.src = URL.createObjectURL(fileItem);
    video.play();
```
API Windows.Media.MediaCapture em um aplicativo UWP usando o Windows Runtime. Para obter mais informações sobre como essa API é usada, consulte o exemplo de captura de mídia.
Leitor de código-fonte da Media Foundation, para aplicativos que processam dados de mídia. O MFT de driver será exposto aos aplicativos como o primeiro (0º) MFT ao chamar IMFSourceReaderEx::GetTransformForStream. A categoria que será retornada é MFT_CATEGORY_VIDEO_EFFECT.

Câmeras com vários pinos

Se você tiver uma câmera de três pinos ou outra câmera de vários pinos, consulte Considerações sobre MFTs de driver em câmeras de vários pinos.

Implementação do MFT do driver

Esta seção fornece informações sobre como implementar o MFT de driver. Para obter um exemplo completo de um MFT de driver que funciona em conjunto com um aplicativo de dispositivo UWP, consulte o exemplo de MFT de driver.

Ferramentas de desenvolvimento

O Microsoft Visual Studio Professional ou o Microsoft Visual Studio Ultimate é necessário.

Características do MFT de driver

O MFT de driver é instanciado por fluxo. Para cada fluxo suportado pela câmera, uma instância do MFT é instanciada e conectada a ele. Espera-se que o MFT de driver tenha um único fluxo de entrada e um único fluxo de saída. O MFT de driver pode ser um MFT síncrono ou um MFT assíncrono.

Comunicação entre a câmera e o MFT de driver

Para habilitar a comunicação bidirecional entre a fonte de mídia e o MFT de driver, o ponteiro para o repositório de atributos do fluxo de origem é definido no repositório de atributos do fluxo de entrada do MFT de driver como MFT_CONNECTED_STREAM_ATTRIBUTE. Isso ocorre por meio de um processo de handshake que você habilita expondo MFT_ENUM_HARDWARE_URL_Attribute no MFT de driver, como no exemplo a seguir:

HRESULT CDriverMft::GetAttributes(IMFAttributes** ppAttributes)
{
    HRESULT hr = S_OK;
    if (NULL == ppAttributes)
    {
       return E_POINTER; 
    };
        if(!m_pGlobalAttributes) {
           MFCreateAttributes(&m_pGlobalAttributes, 1);
           m_pGlobalAttributes-> 
             SetString(MFT_ENUM_HARDWARE_URL_Attribute, L"driverMFT");
        }
        *ppAttributes = m_pGlobalAttributes;
        (*ppAttributes)->AddRef();
        return S_OK;
}

Neste exemplo, o MFT_CONNECTED_STREAM_ATTRIBUTE no armazenamento de atributos do MFT do driver é definido para apontar para o repositório de atributos do fluxo de origem do dispositivo. Consulte Sequência de handshake de hardware para obter mais detalhes sobre como a comunicação entre a câmera e o MFT é configurada.

Como acessar informações de origem do dispositivo

O exemplo de código a seguir mostra como o MFT de driver pode obter o ponteiro para a transformação de origem de seu repositório de atributos de entrada. O MFT de driver pode então usar o ponteiro de origem para obter informações de origem do dispositivo.

if(!m_pSourceTransform && m_pInputAttributes) {

          m_pInputAttributes->
              GetUnknown( MFT_CONNECTED_STREAM_ATTRIBUTE,
              IID_PPV_ARGS(&pSourceAttributes));
          pSourceAttributes-> 
              GetUnknown(
              MF_DEVICESTREAM_EXTENSION_PLUGIN_CONNECTION_POINT,            
              IID_PPV_ARGS(&pUnk)));
          pUnk->QueryInterface(__uuidof(IMFTransform), 
              (void**)&m_pSourceTransform));
      }
      if (m_pSourceTransform) {
         // Put code to get device source information here.         
      }

Como implementar o modo de passagem

Para colocar o MFT de driver no modo de passagem, especifique o mesmo tipo de mídia para o fluxo de entrada e saída. As chamadas de ProcessInput e ProcessOutput no MFT ainda serão feitas. Cabe à implementação do MFT do driver determinar se ocorre ou não algum processamento no modo de passagem.

Arquivos de cabeçalho a serem incluídos

Você precisará incluir arquivos de cabeçalho para os métodos IInspectable e IMFTransform que o MFT do driver deve implementar. Para obter uma lista de arquivos de cabeçalho a serem incluídos, consulte stdafx.h no diretório SampleMFT0 do exemplo de aplicativo de dispositivo UWP para câmera.

// required for IInspectable
#include <inspectable.h>

Como implementar o IInspectable

Um MFT de driver destinado ao uso do aplicativo de dispositivo UWP de uma câmera deve implementar os métodos de IInspectable para que o aplicativo de dispositivo da Microsoft Store possa acessar um ponteiro para o MFT de driver quando iniciado. Seu MFT de driver deve implementar os seguintes métodos IInspectable:

IInspectable::GetIids deve retornar null no parâmetro iids e retornar 0 no parâmetro iidCount out.
IInspectable::GetRuntimeClassName deve retornar null no parâmetro out.
IInspectable::GetRuntiGetTrustLevel deve retornar TrustLevel::BaseTrust no parâmetro out.

O exemplo de código a seguir mostra como os métodos IInspectable são implementados no MFT de driver de exemplo. Esse código pode ser encontrado no arquivo Mft0.cpp, no diretório SampleMFT0 do exemplo.

// Mft0.cpp
STDMETHODIMP CMft0::GetIids( 
    /* [out] */ __RPC__out ULONG *iidCount,
    /* [size_is][size_is][out] */ __RPC__deref_out_ecount_full_opt(*iidCount) IID **iids)
{
    HRESULT hr = S_OK;
    do {
        CHK_NULL_PTR_BRK(iidCount);
        CHK_NULL_PTR_BRK(iids);
        *iids = NULL;
        *iidCount = 0;
    } while (FALSE);

    return hr;
}

STDMETHODIMP CMft0::GetRuntimeClassName( 
    /* [out] */ __RPC__deref_out_opt HSTRING *className)
{
    HRESULT hr = S_OK;
    do {
        CHK_NULL_PTR_BRK(className);
        *className = NULL;
    } while (FALSE);

    return hr;
}

STDMETHODIMP CMft0::GetTrustLevel( 
    /* [out] */ __RPC__out TrustLevel *trustLevel)
{
    HRESULT hr = S_OK;
    do {
        CHK_NULL_PTR_BRK(trustLevel);
        *trustLevel = TrustLevel::BaseTrust;
    } while (FALSE);

    return hr;
}

Implementação de COM

Cada interface que seu MFT de driver implementa deve ser implementada e derivada de IUnknown, a fim de ser corretamente empacotada para o aplicativo de dispositivo UWP da câmera. A seguir está um arquivo .idl de exemplo para um MFT de driver que demonstra isso.

// SampleMft0.idl : IDL source for SampleMft0
//

// This file will be processed by the MIDL tool to
// produce the type library (SampleMft0.tlb) and marshalling code.

import "oaidl.idl";
import "ocidl.idl";
import "Inspectable.idl";
import "mftransform.idl";
[
    object,
    uuid(F5208B72-A37A-457E-A309-AE3060780E21),
    oleautomation,
    nonextensible,
    pointer_default(unique)
]
interface IMft0 : IUnknown{
    [id(1)] HRESULT UpdateDsp([in] UINT32 uiPercentOfScreen);
    [id(2)] HRESULT Enable(void);
    [id(3)] HRESULT Disable(void);
    [id(4)] HRESULT GetDspSetting([out] UINT* puiPercentOfScreen, [out] BOOL* pIsEnabled);
};
[
    uuid(DE05674A-C564-4C0E-9B7C-E1519F7AA767),
    version(1.0),
]
library SampleMft0Lib
{
    importlib("stdole2.tlb");
    [
        uuid(7BB640D9-33A4-4759-B290-F41A31DCF848)      
    ]
    coclass Mft0
    {
        [default] interface IMft0;
        interface IInspectable;
        interface IMFTransform;
    };
};

Observação

O MFT de driver é uma classe COM regular que pode ser criada usando CoCreateInstance. Você não deve usar a função MFTRegister para registrá-lo porque não é um MFT de uso geral.

Criação de um proxy

O MFT de driver é um servidor fora de processo. Para usá-lo em um aplicativo de dispositivo UWP, você deve fornecer suporte a empacotamento em um proxy para que sua interface de MFT de driver possa ser usada além dos limites do processo. Um exemplo está disponível na amostra de MFT de driver. O exemplo usa o compilador MIDL para gerar um proxy stubless.

Expondo o MFT de driver a aplicativos

Para criar um aplicativo de dispositivo UWP em C# ou JavaScript que interaja com um MFT de driver, você precisa criar um componente adicional no projeto Microsoft Visual Studio do aplicativo de dispositivo da Microsoft Store. Esse componente é um wrapper que expõe as interfaces MFT do driver em um componente do Windows Runtime visível para o aplicativo de dispositivo da Microsoft Store.

O subprojeto Wrapper no exemplo de aplicativo de dispositivo UWP para câmera fornece um exemplo de como expor seu MFT de driver ao Windows Runtime para que você possa usá-lo de um aplicativo de dispositivo UWP implementado em C# ou JavaScript. Ele foi projetado para trabalhar em conjunto com o exemplo de MFT do driver. Consulte a página de exemplo do MFT do driver para obter um guia passo a passo para instalar, executar e testar os exemplos.

Instalando e registrando o MFT do driver

Esta seção lista as etapas para instalar o MFT do driver:

O MFT DLL do driver deve ser instalado em um subdiretório no seguinte local:
- %SystemDrive%\Arquivos de Programas\
O instalador da câmera registra o MFT do driver chamando regsvr32 na DLL MFT do driver ou fornecendo um arquivo de manifesto do driver (.man) para a DLL que o instalador usa para registro.
Defina o valor CameraPostProcessingPluginCLSID na chave do registro para sua câmera. Seu arquivo INF deve especificar o CLSID do MFT do driver na chave do registro de classe de dispositivo para o dispositivo, definindo o valor CameraPostProcessingPluginCLSID para o GUID CLSID da classe MFT do driver. A seguir está um exemplo de uma entrada de arquivo INF que preenche as chaves do registro para uma câmera:

KSCATEGORY_VIDEO_CAMERA:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceClasses\{E5323777-F976-4f5b-9B55-B94699C46E44}\##?#USB#VID_045E&PID_075D&MI_00#8&23C3DB65&0&0000#{E5323777-F976-4f5b-9B55-B94699C46E44}\#GLOBAL\Device Parameters]
"CLSID"="{17CCA71B-ECD7-11D0-B908-00A0C9223196}"
"FriendlyName"="USB Video Device"
"RTCFlags"=dword:00000010
"CameraPostProcessingPluginCLSID"="{3456A71B-ECD7-11D0-B908-00A0C9223196}"

KSCATEGORY_CAPTURE:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceClasses\{ 65E8773D-8F56-11D0-A3B9-00A0C9223196}\##?#USB#VID_045E&PID_075D&MI_00#8&23C3DB65&0&0000#{65E8773D-8F56-11D0-A3B9-00A0C9223196}\#GLOBAL\Device Parameters]
"CLSID"="{17CCA71B-ECD7-11D0-B908-00A0C9223196}"
"FriendlyName"="USB Video Device"
"RTCFlags"=dword:00000010
"CameraPostProcessingPluginCLSID"="{3456A71B-ECD7-11D0-B908-00A0C9223196}"

Observação

KSCATEGORY_VIDEO_CAMERA é recomendado para câmeras. Normalmente, você só precisará de uma das chaves do registro, dependendo de como o dispositivo está registrado.

Associar seu aplicativo à câmera

Esta seção contém informações sobre as etapas necessárias para identificar sua câmera nos metadados do dispositivo e no registro do Windows. Esses metadados permitem que você emparelhe seu aplicativo de dispositivo UWP e identifique seu aplicativo para que ele possa ser baixado perfeitamente na primeira vez que a câmera for conectada.

Atualizações

Após a primeira instalação do aplicativo, se o usuário baixar uma versão atualizada do aplicativo, as atualizações serão automaticamente integradas à experiência de captura da câmera. No entanto, as atualizações não são baixadas automaticamente. O usuário deve baixar atualizações de aplicativos adicionais da Microsoft Store, porque o aplicativo é instalado automaticamente apenas na primeira conexão. A página principal do aplicativo de dispositivo UWP pode fornecer notificações de que as atualizações estão disponíveis e fornecer links para baixar atualizações.

Importante

Seu aplicativo atualizado deve funcionar com todos os drivers atualizados distribuídos pelo Windows Update.

Várias câmeras

Vários modelos de câmera podem declarar o mesmo aplicativo de dispositivo UWP em seus metadados de dispositivo. Se um sistema tiver mais de uma câmera incorporada internamente, as câmeras deverão compartilhar o mesmo aplicativo de dispositivo UWP. O aplicativo inclui lógica para determinar qual câmera está em uso e pode mostrar uma interface do usuário diferente para cada câmera na experiência Mais opções. Para obter mais informações sobre como personalizar essa experiência, consulte Como personalizar as opções da câmera.

Câmeras internas

Os aplicativos de dispositivo UWP para câmeras internas são qualificados para instalação automática na Microsoft Store, mas é recomendável que sejam pré-instalados para proporcionar uma experiência de usuário mais suave. Há etapas adicionais necessárias para oferecer suporte a câmeras internas e associar um aplicativo de dispositivo UWP a elas. Para obter mais informações, consulte Identificando a localização de câmeras internas.

Criando o pacote de metadados do dispositivo

Para câmeras internas e externas, você precisa criar um pacote de metadados do dispositivo. Ao enviar o aplicativo de dispositivo UWP da câmera para a Microsoft Store (ou pré-instalá-lo usando o OPK, no caso de câmeras internas), além do aplicativo em si, você precisará fornecer metadados contendo o seguinte:

Nome do editor do aplicativo
Nome do pacote de aplicativos
Identificador do elemento de aplicativo
Identificador de experiência do dispositivo

Para obter mais informações sobre como usar metadados de dispositivo para associar seu aplicativo ao dispositivo, consulte Criando aplicativos de dispositivo UWP.

Criando aplicativos de dispositivo UWP

Instalação automática para aplicativos de dispositivo UWP

Sequência de handshake de hardware (MFTs de hardware)

Guia de criação de minidrivers AVStream

Exemplo de aplicativo de dispositivo UWP para câmera

Exemplo de MFT de driver

Compartilhar via

Criando um MFT de driver de câmera para um aplicativo de dispositivo UWP

O MFT de driver

Como um MFT de driver é usado

Requisito do modelo de driver AvStream

Como o MFT de driver é exposto aos aplicativos

Câmeras com vários pinos

Implementação do MFT do driver

Ferramentas de desenvolvimento

Características do MFT de driver

Comunicação entre a câmera e o MFT de driver

Como acessar informações de origem do dispositivo

Como implementar o modo de passagem

Arquivos de cabeçalho a serem incluídos

Como implementar o IInspectable

Implementação de COM

Criação de um proxy

Expondo o MFT de driver a aplicativos

Instalando e registrando o MFT do driver

Associar seu aplicativo à câmera

Atualizações

Várias câmeras

Câmeras internas

Criando o pacote de metadados do dispositivo

Comentários

Recursos adicionais

Compartilhar via

Criando um MFT de driver de câmera para um aplicativo de dispositivo UWP

O MFT de driver

Como um MFT de driver é usado

Requisito do modelo de driver AvStream

Como o MFT de driver é exposto aos aplicativos

Câmeras com vários pinos

Implementação do MFT do driver

Ferramentas de desenvolvimento

Características do MFT de driver

Comunicação entre a câmera e o MFT de driver

Como acessar informações de origem do dispositivo

Como implementar o modo de passagem

Arquivos de cabeçalho a serem incluídos

Como implementar o IInspectable

Implementação de COM

Criação de um proxy

Expondo o MFT de driver a aplicativos

Instalando e registrando o MFT do driver

Associar seu aplicativo à câmera

Atualizações

Várias câmeras

Câmeras internas

Criando o pacote de metadados do dispositivo

Tópicos relacionados

Comentários

Recursos adicionais