Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
A partir del umbral de Windows, expondremos una nueva API de lámpara winRT que permite programar un flash de cámara sin necesidad de crear una instancia de Windows.Media.Capture.MediaCapture. Al hacerlo, un desarrollador puede escribir una aplicación de linterna (solo para fines de iluminación) dibujando la menor cantidad de recursos, incluida la potencia, de modo que un dispositivo informático se pueda optimizar para la duración y el rendimiento de la batería.
Para ello, un IHV/OEM implementará un controlador WDM que admita las siguientes funciones:
Permitir que el sistema enumere todos los dispositivos flash.
Active o desactive la linterna por dispositivo.
Si procede, ajuste la intensidad de la luz (similar a PowerPercent) por dispositivo.
Si procede, especifique el color claro por dispositivo.
En términos de funcionalidad, la lista anterior se superpone significativamente con la de MediaCapture (por ejemplo, FlashControl y TorchControl). Además, se usa el mismo hardware flash para la lámpara y el flash durante la captura. Por lo tanto, se recomienda un IHV/OEM para admitir ambos tipos de operaciones mediante un único controlador WDM para controlar flash exclusivamente. En la ilustración siguiente se muestra el concepto:
En el ejemplo anterior, solo hay una instancia de hardware flash (que se muestra como) y se administra mediante un único controlador flash KMDF. El controlador flash expone dos interfaces de dispositivo, cada una de las cuales está destinada a un tipo específico de cliente (o API de WinRT). Por ejemplo, dada la ilustración anterior:
La API de captura multimedia de WinRT y el minidriver AVStream siempre se comunican con el controlador flash a través de la interfaz de GUID_DEVINTERFACE_CAMERA_FLASH, mientras que
La API lamp de WinRT siempre se comunica con el controlador flash a través de la interfaz GUID_DEVINTERFACE_LAMP.
Dado que una minidriver AVStream específica del proveedor usa la interfaz GUID_DEVINTERFACE_CAMERA_FLASH, un IHV/OEM es libre de definir su funcionalidad a voluntad, no habrá ninguna restricción impuesta por Windows.
Sin embargo, Microsoft estandarizará la interfaz, GUID_DEVINTERFACE_LAMP, ya que la API De lámpara de WinRT la usará. Para obtener más información sobre GUID_DEVINTERFACE_LAMP, consulte GUID de clase de interfaz de dispositivo.
Casos de uso de simultaneidad
Uso compartido de flash entre aplicaciones de cámara y linterna
Normalmente, un flash de cámara se considera un periférico subordinado a un dispositivo de captura. No está pensado para compartirse con escenarios que no son de cámara mientras se ejecuta la captura. Para complicar aún más, el número de dispositivos flash en un chasis es extremadamente limitado, de modo que, en la práctica, no habrá flash de repuesto dedicado únicamente a la finalidad de la linterna.
Desde la perspectiva del software, lo anterior impone un desafío en el que una aplicación de cámara y una aplicación de linterna pueden coexistir y acceder al flash al mismo tiempo. Por ejemplo, en teoría, un usuario puede alternar el estado LED a través de una aplicación de linterna mientras se ejecuta un visor de cámara.
Dado que la cámara requiere controles precisos sobre flash para admitir el foco y la captura, puede ser difícil que el controlador resuelva las solicitudes flash de intereses conflictivos a la vez que garantiza la calidad de la imagen. Para solucionar este problema, la siguiente directiva se aplica en el nivel del sistema como contrato:
Si una sesión de captura se inicia primero, una aplicación de linterna no puede manipular el flash hasta que se detenga la captura.
Una aplicación de linterna todavía puede adquirir un identificador para el controlador flash, pero cualquier operación que modifique el estado flash produce un error inmediato.
Cuando la captura se detiene de modo que el minidriver AVStream libera la memoria flash, se requiere que el controlador flash publique una notificación PnP (vea GUID_LAMP_RESOURCES_AVAILABLE en notificaciones asincrónicas) que indica que el hardware subyacente ya está disponible. Tras recibir dicha notificación, se permite que una aplicación de linterna programe flash en consecuencia.
Si una aplicación de linterna se inicia primero, una sesión de captura es libre de secuestrar el hardware flash sin consentimiento explícito.
Al "secuestro", significamos que un IHV/OEM puede implementar un protocolo arbitrario (posiblemente a través de la interfaz GUID_DEVINTERFACE_CAMERA_FLASH) de modo que el minidriver AVStream pueda adquirir flash como si el hardware no se utilizase en absoluto.
Cuando se produce un secuestro, se requiere que el controlador flash publique otra notificación PnP (vea GUID_LAMP_RESOURCES_LOST en notificaciones asincrónicas) que indica que el flash se ha reasignado de forma involuntaria para que la aplicación de linterna pueda actuar en consecuencia (actualizando la interfaz de usuario por ejemplo)
Compartir flash entre varias aplicaciones de linterna
Si la cámara no está implicada y dos aplicaciones de linterna se ejecutan sucesivamente, el controlador debe mantener el mantenimiento del primer cliente que ya ha adquirido la interfaz de GUID_DEVINTERFACE_LAMP y rechazar todos los clientes adicionales hasta que el primero libere la interfaz finalmente.
En otras palabras, la interfaz GUID_DEVINTERFACE_LAMP solo permite un cliente de linterna a la vez y el primer cliente que adquiere la interfaz impide que otros se ejecuten (cámara o AVStream excluido).
GUID de clase de interfaz de dispositivo
Un controlador flash IHV/OEM capaz de admitir la linterna independiente de MediaCapture debe registrarse con el GUID de clase de interfaz de dispositivo, GUID_DEVINTERFACE_LAMP.
| Attribute | Configuración |
|---|---|
| Identificador | GUID_DEVINTERFACE_LAMP |
| GUID de clase | {6C11E9E3-8232-4F0A-AD19-AAEC26CA5E98} |
El GUID de clase de interfaz de dispositivo de GUID_DEVINTERFACE_CAMERA_FLASH puede definirse de forma personalizada mediante IHVs/OEM. Sin embargo, Windows define el GUID de clase de interfaz de dispositivo de GUID_DEVINTERFACE_LAMP.
Por contrato, se requiere un controlador que exponga la interfaz del dispositivo, GUID_DEVINTERFACE_LAMP, para admitir las siguientes funciones (consulte las secciones posteriores para obtener más información):
IOCTL_LAMP_GET_CAPABILITIES_{WHITE|COLOR}: obtiene todos los modos (por ejemplo, solo blanco frente a color) admitidos por el hardware subyacente.
IOCTL_LAMP_{GET|SET}_MODE : obtiene o establece el modo actual
IOCTL_LAMP_{GET|SET}_INTENSITY_{WHITE|COLOR}: obtiene o establece la intensidad de la luz
IOCTL_LAMP_{GET|SET}_EMITTING_LIGHT : obtiene o establece el estado flash (por ejemplo, ON/OFF)
Si un dispositivo tiene más de un hardware flash de diferentes tipos (por ejemplo, un LED blanco y un flash Xenon) y estos hardware se controlan mediante controladores flash diferentes, cada controlador expondrá la misma interfaz GUID_DEVINTERFACE_LAMP con un identificador de instancia único.
Device Interface (propiedad)
Dado que un dispositivo informático puede tener cero o más dispositivos flash en diferentes paneles, la API de lámpara de WinRT necesita un mecanismo para enumerar todo el hardware flash de forma que una aplicación pueda programar una instancia específica.
Para admitir la enumeración de dispositivos, similar al controlador de cámara, se requiere que el controlador flash asocie una estructura ACPI _PLD v2 con cada interfaz de GUID_DEVINTERFACE_LAMP como datos de propiedad de interfaz.
IOCTL_LAMP_GET_CAPABILITIES_WHITE
La IOCTL_LAMP_GET_CAPABILITIES_WHITE solicitud de E/S consulta las funciones del flash cuando el dispositivo está configurado para emitir luz blanca.
Definición
#define IOCTL_LAMP_BASE FILE_DEVICE_UNKNOWN
#define IOCTL_LAMP_GET_CAPABILITIES_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0000, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parámetros de entrada
Irp-AssociatedIrp.SystemBuffer> apunta a un búfer de tipo LAMP_CAPABILITIES_WHITE. Consulte Comentarios para obtener más detalles.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength es la longitud del búfer (en bytes) pasado en el campo Irp-AssociatedIrp.SystemBuffer>.
Parámetros de salida
Irp-AssociatedIrp.SystemBuffer> está lleno de todas las funcionalidades compatibles con el hardware flash.
Bloque de estado de E/S
El controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o el estado de error adecuado. Establecerá Irp-IoStatus.Information> en el número de bytes necesarios para contener el búfer.
Comentarios
Por requisito, se requiere un flash cuyo controlador admita la interfaz GUID_DEVINTERFACE_LAMP para admitir la emisión de luz blanca. La carga de este IOCTL se define como sigue:
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_WHITE.
typedef struct LAMP_CAPABILITIES_WHITE
{
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_WHITE;
El campo IsLightIntensityAdjustable indica si se puede programar el nivel de luminancia. Si este campo evalúa false, significa que el dispositivo subyacente solo admite el interruptor de encendido y apagado y la intensidad de la luz no se puede ajustar.
IOCTL_LAMP_GET_CAPABILITIES_COLOR
La IOCTL_LAMP_GET_CAPABILITIES_COLOR solicitud de E/S consulta las funciones del flash cuando el dispositivo está configurado para emitir luz de color.
Definición
#define IOCTL_LAMP_GET_CAPABILITIES_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0001, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parámetros de entrada
Irp-AssociatedIrp.SystemBuffer> apunta a un búfer de tipo LAMP_CAPABILITIES_COLOR. Consulte Comentarios para obtener más detalles.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength es la longitud del búfer (en bytes) pasado en el campo Irp-AssociatedIrp.SystemBuffer>.
Parámetros de salida
Irp-AssociatedIrp.SystemBuffer> está lleno de todas las funcionalidades compatibles con el hardware flash.
Bloque de estado de E/S
El controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o el estado de error adecuado. Establecerá Irp-IoStatus.Information> en el número de bytes necesarios para contener el búfer.
Comentarios
La carga de este IOCTL se define como sigue:
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_COLOR.
typedef struct LAMP_CAPABILITIES_COLOR
{
BOOLEAN IsSupported;
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_COLOR;
El primer campo, IsSupported, indica si el flash puede emitir luz de color. Si el hardware no admite luz de color, el controlador debe establecer este campo en false.
El segundo campo, IsLightIntensityAdjustable, indica si se puede programar el nivel de luminancia. Si el flash no admite la luz de color (por ejemplo, IsSupported evalúa false), un cliente debe descartar el valor de IsLightIntensityAdjustable.
IOCTL_LAMP_GET_MODE
La IOCTL_LAMP_GET_MODE solicitud de E/S consulta el modo con el que está configurada la memoria flash actualmente.
Definición
#define IOCTL_LAMP_GET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0002, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parámetros de entrada
Irp-AssociatedIrp.SystemBuffer> apunta a un búfer de tipo LAMP_MODE, que se define como sigue:
typedef enum LAMP_MODE
{
LAMP_MODE_WHITE = 0,
LAMP_MODE_COLOR
} LAMP_MODE;
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength es la longitud del búfer (en bytes) pasado en el campo Irp-AssociatedIrp.SystemBuffer>.
Parámetros de salida
Irp-AssociatedIrp.SystemBuffer> se rellena con un valor de LAMP_MODE.
Bloque de estado de E/S
El controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o el estado de error adecuado. Establecerá Irp-IoStatus.Information> en el número de bytes necesarios para contener un valor DWORD.
Si una sesión de MediaCapture transmite datos en el momento en que se realiza esta solicitud, el controlador debe devolver un error (STATUS_RESOURCE_IN_USE) a través de Irp-IoStatus.Status>.
IOCTL_LAMP_SET_MODE
La IOCTL_LAMP_SET_MODE solicitud de E/S establece el modo en el que funciona el flash.
Definición
#define IOCTL_LAMP_SET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0003, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parámetros de entrada
Irp-AssociatedIrp.SystemBuffer> apunta a un búfer de tipo LAMP_MODE.
Parámetros de salida
Ninguno.
Bloque de estado de E/S
El controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o el estado de error adecuado.
Si una sesión de MediaCapture transmite datos en el momento en que se realiza esta solicitud, el controlador debe devolver un error (STATUS_RESOURCE_IN_USE) a través de Irp-IoStatus.Status>.
IOCTL_LAMP_GET_INTENSITY_WHITE
La IOCTL_LAMP_GET_INTENSITY_WHITE solicitud de E/S consulta la intensidad de la luz cuando el flash está configurado para emitir luz blanca.
Definición
#define IOCTL_LAMP_GET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0004, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parámetros de entrada
Irp-AssociatedIrp.SystemBuffer> apunta a una estructura LAMP_INTENSITY_WHITE. Consulte Comentarios para obtener más detalles.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength es la longitud del búfer (en bytes) pasado en el campo Irp-AssociatedIrp.SystemBuffer>.
Parámetros de salida
Irp-AssociatedIrp.SystemBuffer> se rellena con la información de intensidad de la luz.
Bloque de estado de E/S
El controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o el estado de error adecuado.
Si una sesión de MediaCapture transmite datos en el momento en que se realiza esta solicitud, el controlador debe devolver un error (STATUS_RESOURCE_IN_USE) a través de Irp-IoStatus.Status>.
Comentarios
El tipo de carga de este IOCTL se define como sigue:
// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_WHITE.
typedef struct LAMP_INTENSITY_WHITE
{
BYTE Value;
} LAMP_INTENSITY_WHITE;
El campo Valor es la intensidad de la luz blanca en porcentaje entre 0 y 100 inclusive.
IOCTL_LAMP_SET_INTENSITY_WHITE
La IOCTL_LAMP_SET_INTENSITY_WHITE solicitud de E/S establece el flash en la intensidad de luz especificada.
Definición
#define IOCTL_LAMP_SET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0005, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parámetros de entrada
Irp-AssociatedIrp.SystemBuffer> apunta a una estructura de LAMP_INTENSITY_WHITE (consulte IOCTL_LAMP_GET_INTENSITY_WHITE para obtener más información).
Parámetros de salida
Ninguno.
Bloque de estado de E/S
El controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o el estado de error adecuado.
Si una sesión de MediaCapture transmite datos en el momento en que se realiza esta solicitud, el controlador debe devolver un error (STATUS_RESOURCE_IN_USE) a través de Irp-IoStatus.Status>.
IOCTL_LAMP_GET_INTENSITY_COLOR
La IOCTL_LAMP_GET_INTENSITY_COLOR solicitud de E/S consulta la intensidad de la luz cuando el flash está configurado para emitir luz de color.
Definición
#define IOCTL_LAMP_GET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0006, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parámetros de entrada
Irp-AssociatedIrp.SystemBuffer> apunta a una estructura de LAMP_INTENSITY_COLOR. Consulte Comentarios para obtener más detalles.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength es la longitud del búfer (en bytes) pasado en el campo Irp-AssociatedIrp.SystemBuffer>.
Parámetros de salida
Irp-AssociatedIrp.SystemBuffer> se rellena con la información de intensidad de la luz.
Bloque de estado de E/S
El controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o el estado de error adecuado.
Si una sesión de MediaCapture transmite datos en el momento en que se realiza esta solicitud, el controlador debe devolver un error (STATUS_RESOURCE_IN_USE) a través de Irp-IoStatus.Status>.
Comentarios
El tipo de carga de este IOCTL se define como sigue:
// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_COLOR.
typedef struct LAMP_INTENSITY_COLOR
{
BYTE Red; // Red light intensity in percentage (0-100)
BYTE Green; // Green light intensity in percentage (0-100)
BYTE Blue; // Blue light intensity in percentage (0-100)
} LAMP_INTENSITY_COLOR;
IOCTL_LAMP_SET_INTENSITY_COLOR
La IOCTL_LAMP_SET_INTENSITY_COLOR solicitud de E/S establece el flash en la intensidad de luz especificada.
Definición
#define IOCTL_LAMP_SET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0007, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parámetros de entrada
Irp-AssociatedIrp.SystemBuffer> apunta a una estructura de LAMP_INTENSITY_COLOR (consulte IOCTL_LAMP_GET_INTENSITY_COLOR para obtener más información).
Parámetros de salida
Ninguno.
Bloque de estado de E/S
El controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o el estado de error adecuado.
Si una sesión de MediaCapture transmite datos en el momento en que se realiza esta solicitud, el controlador debe devolver un error (STATUS_RESOURCE_IN_USE) a través de Irp-IoStatus.Status>.
IOCTL_LAMP_GET_EMITTING_LIGHT
La IOCTL_LAMP_GET_EMITTING_LIGHT solicitud de E/S consulta si la luz (flash) está activada.
Definición
#define IOCTL_LAMP_GET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0008, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parámetros de entrada
Irp-AssociatedIrp.SystemBuffer> apunta a un búfer de tipo BOOLEAN.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength es la longitud del búfer (en bytes) pasado en el campo Irp-AssociatedIrp.SystemBuffer>.
Parámetros de salida
Irp-AssociatedIrp.SystemBuffer> se rellena con el estado flash con TRUE, lo que significa que el flash está activado (por ejemplo, emitir luz); FALSE en caso contrario.
Bloque de estado de E/S
El controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o el estado de error adecuado. Establecerá Irp-IoStatus.Information> en el número de bytes necesarios para contener un valor DWORD.
Si una sesión de MediaCapture transmite datos en el momento en que se realiza esta solicitud, el controlador debe devolver un error (STATUS_RESOURCE_IN_USE) a través de Irp-IoStatus.Status>.
IOCTL_LAMP_SET_EMITTING_LIGHT
La IOCTL_LAMP_SET_EMITTING_LIGHT solicitud de E/S activa o desactiva la luz (flash).
Definición
#define IOCTL_LAMP_SET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0009, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parámetros de entrada
Irp-AssociatedIrp.SystemBuffer> apunta a un búfer de tipo BOOLEAN con TRUE que indica ON; FALSE en caso contrario.
Parámetros de salida
Ninguno.
Bloque de estado de E/S
El controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o el estado de error adecuado.
Si una sesión de MediaCapture transmite datos en el momento en que se realiza esta solicitud, el controlador debe devolver un error (STATUS_RESOURCE_IN_USE) a través de Irp-IoStatus.Status>.
Notificaciones asincrónicas
Como se describe en Casos de uso de simultaneidad, el controlador flash es necesario para enviar notificaciones PnP para notificar la disponibilidad de los recursos. Esto se puede hacer llamando a IoReportTargetDeviceChange (o IoReportTargetDeviceChangeAsynchronous) con los siguientes GUID en función del escenario:
El recurso flash se ha expulsado porque se inicia una sesión de captura (u otra aplicación de linterna):
Attribute Configuración Identificador GUID_LAMP_RESOURCES_LOST GUID de clase {F770E98C-4403-48C9-B1D2-4EEC3302E41F} El recurso flash ya está disponible:
Attribute Configuración Identificador GUID_LAMP_RESOURCES_AVAILABLE GUID de clase {185FE7CE-2616-481B-9094-20BB893ACD81}