Creación de una MFT de controlador de cámara para una aplicación de dispositivo para UWP

Artículo
03/11/2024

Importante

Este tema está en desuso. Consulte la Guía de diseño de MFT de dispositivos para obtener instrucciones actualizadas.

Las aplicaciones de dispositivos para UWP permiten a los fabricantes de dispositivos aplicar ajustes personalizados y efectos especiales en la secuencia de vídeo de la cámara con una MFT (Transformación de Media Foundation) de controlador de cámara. En este tema se presentan las MFT del controlador y se usa el ejemplo MFT de controlador para mostrar cómo crear una. Para obtener más información sobre las aplicaciones de dispositivos para UWP en general, consulte Conocer las aplicaciones de dispositivos para UWP.

La MFT de controlador

En esta sección se describe la Transformación de Media Foundation (MFT) que se crea para aplicar efectos a la secuencia de captura multimedia procedente de la cámara. Así es como proporciona transformaciones para efectos de color, modos de esquema y efectos de seguimiento facial que realmente distinguen a la cámara de otros. Esta MFT, conocida como MFT de controlador, se aplica primero a la secuencia de vídeo conectada procedente del controlador de cámara cuando una aplicación para UWP comienza la captura de vídeo. Cuando esa aplicación invoca la interfaz de usuario de Opciones de cámara, Windows proporciona acceso automáticamente a las interfaces que implementa la MFT de controlador para controlar sus efectos personalizados.

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

No se requiere una MFT de controlador para una aplicación de dispositivo para UWP. Un fabricante de dispositivos puede optar por implementar una aplicación de dispositivo para UWP sin una MFT de controlador, simplemente para proporcionar una interfaz de usuario diferenciada que contenga la personalización de marca para su hardware, sin aplicar configuraciones personalizadas ni efectos especiales a la secuencia de vídeo.

Cómo se usa una MFT de controlador

La aplicación de dispositivo para UWP para una cámara se ejecuta en un proceso diferente a la aplicación de Microsoft Store que la invoca desde la API de CameraCaptureUI. Para que la aplicación de dispositivo de Microsoft Store controle una MFT de controlador, debe producirse una secuencia específica de eventos en distintos espacios de proceso.

Una aplicación para UWP quiere capturar una foto, por lo que llama al método CaptureFileAsync
Windows solicita el puntero de MFT del controlador y el identificador de dispositivo de la cámara
El puntero de MFT del controlador se transfiere a un host de configuración.
El host consulta las propiedades del dispositivo para obtener el identificador de aplicación de la aplicación de dispositivo de Microsoft Store asociada a la cámara (por metadatos del dispositivo).
Si no se encuentra ninguna aplicación de dispositivo para UWP, el control flotante predeterminado interactúa con el motor de captura.
Si se encuentra una aplicación de dispositivo para UWP, se activa y el host de configuración le transfiere el puntero de MFT del controlador.
La aplicación de dispositivo para UWP controla la MFT de controlador mediante la interfaz expuesta a través del puntero

the process interaction for invoking a windows store device app.

Requisito del modelo de controlador AvStream

El controlador de la cámara debe usar el modelo de controlador AvStream. Para obtener más información sobre el modelo de controlador AVStream, consulte Guía de diseño de minicontroladores AVStream.

Cómo se expone la MFT de controlador a las aplicaciones

Una MFT de controlador se registra con Windows como una interfaz COM para que la transformación que implementa se pueda aplicar a la secuencia multimedia que sale de un dispositivo específico, como una cámara.

Nota:

Una MFT de controlador no debe registrarse con la función MFTRegister porque es específica del dispositivo y no es una MFT de uso general. Para obtener información sobre la clave de registro, consulte la sección Instalación y registro de la MFT de controlador más adelante en este tema.

Cuando una aplicación inicia una captura de vídeo, se crea una instancia de lector de origen de Media Foundation para proporcionar la secuencia de vídeo. Este origen multimedia lee un valor de registro de la clave del registro del dispositivo. Si el CLSID de la clase COM de la MFT del controlador se encuentra en el valor de registro, el lector de origen crea una instancia de la MFT del controlador y lo inserta en la canalización multimedia.

Además de las aplicaciones de dispositivos para UWP, se puede acceder a la funcionalidad de MFT del controlador cuando se usa el dispositivo asociado para capturar vídeo mediante las siguientes API:

Etiquetas de <vídeo> HTML5 en una aplicación para UWP mediante HTML. Las transformaciones que la MFT del controlador ha habilitado afectarán al vídeo que se reproduce mediante el elemento de <vídeo>, como en el ejemplo de código siguiente:
```
var video = document.getElementById('myvideo');
    video.src = URL.createObjectURL(fileItem);
    video.play();
```
API Windows.Media.MediaCapture en una aplicación para UWP mediante Windows Runtime. Para obtener más información sobre cómo se usa esta API, consulte el ejemplo Captura multimedia.
Lector de origen de Media Foundation, para aplicaciones que procesan datos multimedia. La MFT del controlador se expondrá a las aplicaciones como la primera (0ª) MFT al llamar a IMFSourceReaderEx::GetTransformForStream. La categoría que se devolverá es MFT_CATEGORY_VIDEO_EFFECT.

Cámaras con varios pines

Si tiene una cámara de tres o más pines, consulte Consideraciones sobre las MFT del controlador en cámaras con varios pines.

Implementación de la MFT del controlador

En esta sección se proporciona información sobre cómo implementar la MFT del controlador. Para obtener un ejemplo completo de una MFT del controlador que funciona junto con una aplicación de dispositivo para UWP, consulte el ejemplo MFT del controlador.

Herramientas de desarrollo

Se requiere Microsoft Visual Studio Professional o Microsoft Visual Studio Ultimate.

Características de la MFT del controlador

Se crea una instancia de la MFT del controlador por secuencia. Para cada secuencia que admita la cámara, se crea una instancia de MFT y se conecta a ella. Se espera que la MFT del controlador tenga un único flujo de entrada y un único flujo de salida. La MFT del controlador puede ser una MFT sincrónica o asincrónica.

Comunicación entre la cámara y la MFT del controlador

Para habilitar la comunicación bidireccional entre el origen multimedia y la MFT del controlador, el puntero al almacén de atributos de la secuencia de origen se establece en el almacén de atributos de secuencia de entrada de la MFT del controlador como MFT_CONNECTED_STREAM_ATTRIBUTE. Esto se produce a través de un proceso de protocolo de enlace que se habilita exponiendo MFT_ENUM_HARDWARE_URL_Attribute en la MFT del controlador, como en el ejemplo siguiente:

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

En este ejemplo, el MFT_CONNECTED_STREAM_ATTRIBUTE en almacén de atributos de la MFT del controlador se establece para que apunte al almacén de atributos de la secuencia de origen del dispositivo. Consulte Secuencia de protocolo de enlace de hardware para obtener más información sobre cómo se configura la comunicación entre la cámara y la MFT.

Acceso a la información de origen del dispositivo

En el ejemplo de código siguiente se muestra cómo la MFT del controlador puede obtener el puntero a la transformación de origen desde su almacén de atributos de entrada. A continuación, La MFT del controlador puede usar el puntero de origen para obtener información de origen del 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.         
      }

Cómo implementar el modo de acceso directo

Para colocar la MFT del controlador en modo de acceso directo, especifique el mismo tipo multimedia para la secuencia de entrada y salida. Se seguirán realizando las llamadasProcessInput y ProcessOutput en la MFT. Depende de la implementación de MFT del controlador determinar si se produce o no algún procesamiento en el modo de procesamiento directo.

Archivos de encabezado para incluir

Deberá incluir archivos de encabezado para los métodos IInspectable y IMFTransform que la MFT del controlador debe implementar. Para obtener una lista de los archivos de encabezado que se deben incluir, consulte stdafx.h en el directorio SampleMFT0 del ejemplo Aplicación de dispositivo para UWP para cámara.

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

Cómo implementar IInspectable

Una MFT del controlador que está pensada para su uso desde la aplicación de dispositivo para UWP de una cámara debe implementar los métodos de IInspectable para que la aplicación de dispositivos de Microsoft Store pueda acceder a un puntero a la MFT del controlador cuando se inicia. La MFT del controlador debe implementar los métodos de IInspectable de la siguiente manera:

IInspectable::GetIids debe devolver null en el parámetro de salida iids y devolver 0 en el parámetro de salida iidCount.
IInspectable::GetRuntimeClassName debe devolver null en el parámetro de salida.
IInspectable::GetRuntiGetTrustLevel debe devolver TrustLevel::BaseTrust en el parámetro de salida.

En el ejemplo de código siguiente se muestra cómo se implementan los métodos IInspectable en la MFT del controlador de ejemplo. Este código se puede encontrar en el archivo Mft0.cpp, en el directorio SampleMFT0 del ejemplo.

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

Implementación de COM

Cada interfaz que implemente la MFT del controlador debe implementar y derivar de IUnknown, con el fin de serializarse correctamente en la aplicación de dispositivo para UWP de la cámara. A continuación se muestra un archivo .idl de ejemplo para una MFT del controlador que lo muestra.

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

Nota:

La MFT del controlador es una clase COM normal que se puede crear mediante CoCreateInstance. No debe usar la función MFTRegister para registrarla porque no es una MFT de uso general.

Creación de un proxy

La MFT del controlador es un servidor fuera de proceso. Para usarla en una aplicación de dispositivo para UWP, debe proporcionar compatibilidad con serialización en un proxy para que la interfaz de MFT del controlador pueda usarse a través de los límites del proceso. Puede encontrar un ejemplo de MFT del controlador. En el ejemplo se usa el compilador MIDL para generar un proxy sin código auxiliar.

Exposición de la MFT del controlador a las aplicaciones

Para escribir una aplicación de dispositivo para UWP en C# o JavaScript que interactúe con una MFT de controlador, debe crear un componente adicional en el proyecto de Microsoft Visual Studio de la aplicación de dispositivo de Microsoft Store. Este componente es un contenedor que expone las interfaces MFT del controlador en un componente de Windows Runtime que es visible para la aplicación de dispositivos de Microsoft Store.

El subproyecto Contenedor en el ejemplo Aplicación de dispositivo para UWP para cámara proporciona un ejemplo de cómo exponer la MFT del controlador a Windows Runtime para que pueda usarla desde una aplicación de dispositivo para UWP implementada en C# o JavaScript. Está diseñado para utilizarlo junto con el ejemplo de MFT de controlador. Consulte la página de ejemplo MFT del controlador para obtener una guía paso a paso para instalar, ejecutar y probar los ejemplos.

Instalación y registro de la MFT del controlador

En esta sección se enumeran los pasos para instalar la MFT del controlador:

El archivo DLL de la MFT del controlador debe estar instalado en un subdirectorio en la siguiente ubicación:
- %SystemDrive%\Archivos de programa\
El instalador de la cámara registra la MFT del controlador llamando a regsvr32 en el archivo DLL de la MFT del controlador o proporcionando un archivo de manifiesto de controlador (.man) para el archivo DLL que usa el instalador para el registro.
Establezca el valor CameraPostProcessingPluginCLSID en la clave del registro para la cámara. El archivo INF debe especificar el CLSID de la MFT del controlador en la clave del registro de clase de dispositivo para el dispositivo estableciendo el valor CameraPostProcessingPluginCLSID en el GUID CLSID de la clase MFT del controlador. A continuación se muestra un ejemplo de una entrada de archivo INF que rellena las claves del registro para una cámara:

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

Nota:

KSCATEGORY_VIDEO_CAMERA se recomienda para cámaras. Normalmente solo necesitará una de las claves del registro, en función de cómo se registre el dispositivo.

Asociación de la aplicación con la cámara

Esta sección contiene información sobre los pasos necesarios para identificar la cámara en los metadatos del dispositivo y en el Registro de Windows. Estos metadatos te permiten emparejar su aplicación de dispositivo para UWP e identificarla para que se pueda descargar sin problemas la primera vez que se conecte la cámara.

Actualizaciones

Después de la primera instalación de la aplicación, si el usuario descarga una versión actualizada de la aplicación, las actualizaciones se integran automáticamente en la experiencia de captura de la cámara. Sin embargo, las actualizaciones no se descargan automáticamente. El usuario debe descargar actualizaciones de aplicaciones adicionales desde Microsoft Store, ya que la aplicación solo se instala automáticamente en la primera conexión. La página principal de la aplicación de dispositivo para UWP puede proporcionar notificaciones de que hay actualizaciones disponibles y proporcionar vínculos para descargarlas.

Importante

La aplicación actualizada debe funcionar con los controladores actualizados distribuidos a través de Windows Update.

Varias cámaras

Varios modelos de cámara pueden declarar la misma aplicación de dispositivo para UWP en sus metadatos de dispositivo. Si un sistema tiene más de una cámara insertada internamente, las cámaras deben compartir la misma aplicación de dispositivo para UWP. La aplicación incluye lógica para determinar qué cámara está en uso y puede mostrar una interfaz de usuario diferente para cada cámara en su experiencia de Más opciones. Para obtener más información sobre cómo personalizar esa experiencia, consulte Personalización de las opciones de cámara.

Cámaras internas

Las aplicaciones de dispositivos para UWP para cámaras internas son aptas para la instalación automática desde Microsoft Store, pero se recomienda que estén preinstaladas para obtener la experiencia de usuario más fluida. Se requieren pasos adicionales para admitir cámaras internas y asociar una aplicación de dispositivo para UWP con ellas. Para obtener más información, consulte Identificación de la ubicación de las cámaras internas.

Creación del paquete de metadatos del dispositivo

Para cámaras internas y externas, debe crear un paquete de metadatos de dispositivo. Al enviar la aplicación de dispositivo para UWP de la cámara a Microsoft Store (o preinstalarla mediante la OPK, en el caso de cámaras internas), además de la propia aplicación, deberá proporcionar metadatos que contengan lo siguiente:

Nombre del publicador de la aplicación
Nombre del paquete de aplicación
Identificador del elemento de la aplicación
Identificador de la experiencia del dispositivo

Para obtener más información sobre cómo usar metadatos de dispositivo para asociar la aplicación con el dispositivo, consulte Creación de aplicaciones de dispositivos para UWP.

Creación de aplicaciones de dispositivos para UWP

Instalación automática de aplicaciones de dispositivos para UWP

Secuencia de protocolo de enlace de hardware (MFT de hardware)

Guía de diseño de minicontroladores AVStream

Ejemplo de aplicación de dispositivo para UWP para cámara

Ejemplo de MFT de controlador

Compartir a través de

Creación de una MFT de controlador de cámara para una aplicación de dispositivo para UWP

La MFT de controlador

Cómo se usa una MFT de controlador

Requisito del modelo de controlador AvStream

Cómo se expone la MFT de controlador a las aplicaciones

Cámaras con varios pines

Implementación de la MFT del controlador

Herramientas de desarrollo

Características de la MFT del controlador

Comunicación entre la cámara y la MFT del controlador

Acceso a la información de origen del dispositivo

Cómo implementar el modo de acceso directo

Archivos de encabezado para incluir

Cómo implementar IInspectable

Implementación de COM

Creación de un proxy

Exposición de la MFT del controlador a las aplicaciones

Instalación y registro de la MFT del controlador

Asociación de la aplicación con la cámara

Actualizaciones

Varias cámaras

Cámaras internas

Creación del paquete de metadatos del dispositivo

Comentarios

Recursos adicionales

Compartir a través de

Creación de una MFT de controlador de cámara para una aplicación de dispositivo para UWP

La MFT de controlador

Cómo se usa una MFT de controlador

Requisito del modelo de controlador AvStream

Cómo se expone la MFT de controlador a las aplicaciones

Cámaras con varios pines

Implementación de la MFT del controlador

Herramientas de desarrollo

Características de la MFT del controlador

Comunicación entre la cámara y la MFT del controlador

Acceso a la información de origen del dispositivo

Cómo implementar el modo de acceso directo

Archivos de encabezado para incluir

Cómo implementar IInspectable

Implementación de COM

Creación de un proxy

Exposición de la MFT del controlador a las aplicaciones

Instalación y registro de la MFT del controlador

Asociación de la aplicación con la cámara

Actualizaciones

Varias cámaras

Cámaras internas

Creación del paquete de metadatos del dispositivo

Temas relacionados

Comentarios

Recursos adicionales