Criar um MFT de driver de câmara para uma aplicação de dispositivo UWP

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). Para saber mais sobre os aplicativos de dispositivo UWP em geral, consulte Meet UWP device apps. To learn more about UWP device apps in general, see Meet UWP device apps.

O driver MFT

Esta seção descreve o Media Foundation Transform (MFT) que você cria para aplicar efeitos ao fluxo de captura de mídia proveniente da câmera. Essa transformação é como você fornece 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. When that app invokes the Camera options UI, Windows automatically provides access to any interfaces the driver MFT implements for controlling its custom effects.

Uma MFT de driver não é necessária para uma aplicação de dispositivo UWP. Um fabricante de dispositivo pode optar por implementar um aplicativo de dispositivo UWP sem um driver MFT, 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 é utilizado um driver MFT

The UWP device app for a camera runs in a different process than the Microsoft Store app that invokes it from the CameraCaptureUI API. Para que a aplicação de dispositivo da Microsoft Store controle uma MFT de driver, uma sequência específica de eventos em diferentes espaços de processo deve ocorrer.

1. A UWP app wants to capture a photo, so it calls the CaptureFileAsync method

2. O Windows solicita o ponteiro MFT do driver e o ID do dispositivo da câmera

3. O ponteiro MFT do driver é passado para um host de configurações

4. O host consulta as propriedades do dispositivo para a ID da aplicação do dispositivo da Microsoft Store associado à câmara (de acordo com os metadados do dispositivo)

5. Se nenhum aplicativo de dispositivo UWP for encontrado, o submenu padrão interage com o mecanismo de captura

6. 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

7. A aplicação de dispositivo UWP controla o MFT do driver usando a interface exposta através do ponteiro.

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 AVStream Minidrivers Design Guide.

Como o driver MFT é exposto aos aplicativos

Um driver MFT é registrado com o 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.

Quando um aplicativo inicia uma captura de vídeo, um Media Foundation Source Reader é instanciado para fornecer o fluxo de vídeo. Esta fonte de mídia lê um valor do registo da chave do dispositivo. Se o CLSID da classe COM do driver MFT for encontrado no valor do registo, o leitor de origem instanciará o MFT do driver e irá inseri-lo na linha de mediação.

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 <vídeo> HTML5 numa aplicação UWP usando HTML. Transformações que o driver MFT habilita afetam o vídeo que está sendo reproduzido usando o <elemento 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 uma aplicação UWP usando o Windows Runtime. For more info on how this API is used, see the Media Capture sample.

• Media Foundation's Source Reader, para aplicações que processam dados multimédia. O driver MFT será exposto às aplicações como o primeiro (0º) MFT ao chamar IMFSourceReaderEx::GetTransformForStream. A categoria retornada é MFT_CATEGORY_VIDEO_EFFECT.

  

Multi-pin cameras

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

Implementação MFT do driver

Esta seção fornece informações sobre como implementar seu driver MFT. For a full example of a driver MFT that works together with a UWP device app, see the Driver MFT sample.

Development tools

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

Características MFT do controlador

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

Comunicação entre a câmara e o condutor MFT

Para habilitar a comunicação bidirecional entre a fonte de mídia e a MFT do driver, o armazenamento de atributos do ponteiro para o fluxo de origem é definido no repositório de atributos do fluxo de entrada da MFT do driver como MFT_CONNECTED_STREAM_ATTRIBUTE. Isso acontece através de um processo de 'handshake' que é ativado ao expor MFT_ENUM_HARDWARE_URL_Attribute no driver MFT, conforme o 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 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 Integração de Hardware para mais detalhes sobre como é configurada a comunicação entre a câmara e o MFT.

Como acessar as informações de origem do dispositivo

O exemplo de código a seguir mostra como o driver MFT pode obter o ponteiro para a transformação de origem a partir do seu repositório de atributos de entrada. O driver MFT pode 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 driver MFT no modo de passagem, especifique o mesmo tipo de mídia para o fluxo de entrada e saída. ProcessInput e ProcessOutput as chamadas à MFT continuarão a ser feitas. Cabe à implementação MFT do driver determinar se algum processamento ocorre ou não no modo de passagem direta.

Arquivos de cabeçalho a serem incluídos

Você precisará incluir ficheiros de cabeçalho para os métodos IInspectable e IMFTransform que a MFT do driver deve implementar. For a list of header files to include, see stdafx.h in the SampleMFT0 directory of the UWP device app for camera sample.

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

Como implementar o IInspectable

Uma MFT de driver destinada ao uso do aplicativo UWP do dispositivo 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 a MFT de driver ao ser iniciado. O seu driver MFT deve implementar os métodos de IInspectable da seguinte forma:

• IInspectable::GetIids should return null in the iids out parameter, and return 0 in the iidCount out parameter.

• IInspectable::GetRuntimeClassName should return null in the out parameter.

• IInspectable::GetRuntiGetTrustLevel should return TrustLevel::BaseTrust in the out parameter.

O exemplo de código a seguir mostra como os IInspectable métodos são implementados no driver de exemplo MFT. This code can be found in the Mft0.cpp file, in the SampleMFT0 directory of the sample.

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

COM implementation

Cada interface que o seu driver MFT implementa deve implementar e derivar de IUnknown, a fim de ser corretamente convertido para o aplicativo de dispositivo UWP da câmera. The following is an example .idl file for a driver MFT that demonstrates this.

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

Criando um proxy

O driver MFT é um servidor fora de processo. Para usá-lo numa aplicação de dispositivo UWP, deve fornecer suporte a marshaling num proxy para que a sua interface MFT do controlador possa ser usada através de limites de processo. You can find an example of this in the Driver MFT sample. O exemplo usa o compilador MIDL para gerar um proxy sem stub (stubless).

Expor o driver MFT a aplicativos

Para escrever um aplicativo de dispositivo UWP em C# ou JavaScript que interaja com um driver MFT, você precisa criar outro componente no projeto Microsoft Visual Studio do aplicativo de dispositivo da Microsoft Store. Este componente é um wrapper que expõe as interfaces MFT do driver em um Componente de Tempo de Execução do Windows que está visível para a aplicação de dispositivos da Microsoft Store.

O subprojeto Wrapper no exemplo de aplicativo de dispositivo UWP para câmera fornece um exemplo de como expor seu driver MFT ao Tempo de Execução do Windows para que você possa usá-lo a partir de um aplicativo de dispositivo UWP implementado em C# ou JavaScript. See the Driver MFT sample page for a step-by-step guide to installing, running, and testing the samples. See the Driver MFT sample page for a step-by-step guide to installing, running, and testing the samples.

Instalando e registrando o driver MFT

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

1. O driver MFT DLL deve ser instalado em um subdiretório no seguinte local:

   • %SystemDrive%\Program Files\

2. Your camera installer registers the driver MFT by calling regsvr32 on your driver MFT DLL, or by providing a driver manifest (.man) file for the DLL that the installer uses for registration.

3. Defina o CameraPostProcessingPluginCLSID valor na chave de registo para a sua câmara. O seu arquivo INF deve especificar o CLSID do Driver MFT na chave de registro da classe do 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}"

Associe 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 sem problemas na primeira vez que a câmera estiver conectada.

Updates

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. A página principal do seu aplicativo de dispositivo UWP pode fornecer notificações de que as atualizações estão disponíveis e fornecer links para baixar atualizações. The main page of your UWP device app can provide notifications that updates are available and provide links to download updates.

Multiple cameras

Vários modelos de câmera podem declarar o mesmo aplicativo de dispositivo UWP nos metadados do dispositivo. Se um sistema tiver mais de uma câmera incorporada internamente, as câmeras deverão compartilhar o mesmo aplicativo de dispositivo UWP. The app includes logic for determining which camera is in use and can show different UI for each camera in its More options experience. Para saber mais sobre como personalizar essa experiência, veja Como personalizar as opções da câmera.

Internal cameras

Há mais etapas necessárias para dar 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. For more info, see Identifying the location of internal cameras.

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 próprio aplicativo, você precisa fornecer metadados contendo:

• Nome do editor do aplicativo
• Nome do pacote do aplicativo
• Identificador do elemento do aplicativo
• Identificador da experiência do dispositivo

Para saber mais sobre como usar metadados de dispositivo para associar seu aplicativo ao dispositivo, veja Criando aplicativos de dispositivo UWP.

Related articles

• Criando aplicativos de dispositivo UWP
• Instalação automática para aplicativos de dispositivo UWP
• Sequência de aperto de mão de hardware (MFTs de hardware)
• Guia de design do AVStream Minidrivers
• Aplicação de dispositivo UWP para exemplo de câmera
• Exemplo de driver MFT