Criando um MFT do driver de câmera para um aplicativo 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 MFT do driver de câmera (transformação de base de mídia). This article introduces driver MFTs and uses the Driver MFT sample to show how to create one. Para saber mais sobre aplicativos de dispositivo UWP em geral, consulte Conheça os aplicativos de dispositivo UWP.

O MFT do 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. Essa transformação é como você fornece efeitos de cor, modos de esquema e efeitos de rastreamento facial que realmente distinguem sua câmera de outras pessoas. Esse MFT, conhecido como MFT do 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.

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

Como um MFT de driver é usado

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

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 a 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 do aplicativo de dispositivo da Microsoft Store associada à câmera (por metadados do dispositivo)

5. Se nenhum aplicativo de dispositivo UWP for encontrado, o submenu padrão interagirá 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. O aplicativo de dispositivo UWP controla o MFT do driver usando a interface exposta por meio 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 o Guia de Design de Minidrivers do AVStream.

Como o MFT do driver é exposto a aplicativos

Um MFT de driver é registrado com o Windows como uma interface COM para que a transformação que ele implementa 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 Leitor de Origem da Media Foundation é 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 do driver for encontrado no valor do Registro, o leitor de origem instancia o MFT do driver e insere-o 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:

• Marcas de vídeo> HTML5 <em um aplicativo UWP usando HTML. As transformações que o MFT do driver habilita afetam o vídeo que está sendo reproduzido usando o <elemento de vídeo> , 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. For more info on how this API is used, see the Media Capture sample.

• Leitor de Origem da Media Foundation, para aplicativos que processam dados de mídia. O MFT do driver será exposto a aplicativos 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 de vários pinos, consulte Considerações sobre MFTs de driver em câmeras com vários pinos.

Implementação do MFT do driver

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

Development tools

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

Características do MFT do driver

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

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

Para habilitar a comunicação bidirecional entre a fonte de mídia e o MFT do driver, o ponteiro para o repositório de atributos do fluxo de origem é definido no repositório de atributos de fluxo de entrada do MFT do 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 do 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 repositório de atributos do MFT do driver é definido para apontar para o repositório de atributos do fluxo de origem do dispositivo. Consulte a Sequência de Handshake de Hardware para obter mais detalhes sobre como a comunicação entre a câmera e o MFT está configurada.

Como acessar informações de origem do dispositivo

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

Arquivos de cabeçalho a serem incluídos

Você precisará incluir arquivos de cabeçalho para os métodos e IMFTransform os IInspectable métodos que o 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

Um MFT de driver destinado ao uso do aplicativo de dispositivo UWP de uma câmera deve implementar os métodos dos quais o aplicativo de IInspectable dispositivo da Microsoft Store pode acessar um ponteiro para o driver MFT quando iniciado. O MFT do driver deve implementar os métodos da IInspectable seguinte maneira:

• 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 MFT do driver de exemplo. 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 seu driver MFT implementa deve implementar e derivar de IUnknown, para ser marshaled corretamente 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 MFT do driver é um servidor fora de processo. Para usá-lo em um aplicativo de dispositivo UWP, você deve fornecer suporte de marshaling em um proxy para que a interface MFT do driver possa ser usada entre os limites do 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.

Expondo o MFT do driver a aplicativos

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

O subprojeto Wrapper no aplicativo de dispositivo UWP para exemplo de câmera fornece um exemplo de como expor o MFT do driver para o Windows Runtime para que você possa usá-lo de um aplicativo de dispositivo UWP implementado em C# ou JavaScript. It's designed to work together with the Driver MFT sample. See the Driver MFT sample page for a step-by-step guide to installing, running, and testing the samples.

Instalando e registrando o MFT do driver

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

1. A DLL MFT do driver deve ser instalada 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 do Registro para sua câmera. Seu arquivo INF deve especificar o CLSID do Driver MFT na chave do registro da classe de dispositivo para o dispositivo, definindo o CameraPostProcessingPluginCLSID valor como o GUID CLSID da classe MFT do driver. Veja a seguir 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}"

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 diretamente 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 integradas automaticamente à experiência de captura da câmera. No entanto, as atualizações não são baixadas automaticamente. The user must download more app updates from the Microsoft Store, because the app is automatically installed only on first connect. 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.

Multiple cameras

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 inserida 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 obter mais informações sobre como personalizar essa experiência, consulte Como personalizar as opções de câmera.

Internal cameras

UWP device apps for internal cameras are eligible for Automatic installation from the Microsoft Store, but it's recommended that they be preinstalled for the most seamless user experience. 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 Identificar o local das 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 sua 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 de aplicativos
• Nome do pacote do aplicativo
• Identificador de 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 seu dispositivo, consulte Como criar aplicativos de dispositivo UWP.

Related articles

• Criando aplicativos de dispositivo UWP
• instalação automática de aplicativos de dispositivo UWP
• Sequência de handshake de hardware (MFTs de hardware)
• Guia de design de minidrivers do AVStream
• Aplicativo de dispositivo UWP para exemplo de câmera
• Exemplo de MFT do driver