Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
À partir de Windows Threshold, nous allons exposer une nouvelle API Lamp WinRT qui permet de programmer un flash de caméra sans avoir à créer une instance Windows.Media.Capture.MediaCapture. En procédant ainsi, un développeur peut écrire une application flashlight (à des fins d’éclairage uniquement) en dessinant la quantité minimale de ressources, y compris la puissance, afin qu’un appareil informatique puisse être optimisé pour la durée de vie et les performances de la batterie.
Pour ce faire, un IHV/OEM implémente un pilote WDM qui prend en charge les fonctions suivantes :
Autoriser le système à énumérer tous les appareils flash.
Activez/désactivez la lampe de poche par appareil.
Le cas échéant, ajustez l’intensité de la lumière (similaire à PowerPercent) par appareil.
Le cas échéant, spécifiez la couleur claire par appareil.
En termes de fonctionnalités, la liste ci-dessus chevauche considérablement celle de MediaCapture (par exemple, FlashControl et TorchControl). En outre, le même matériel flash est utilisé à la fois pour la lampe et pour le flash lors de la capture. Par conséquent, il est recommandé qu'un IHV/OEM prenne en charge les deux types d'opérations en utilisant un seul pilote WDM pour contrôler exclusivement le flash. La figure ci-dessous illustre le concept :
Dans l’exemple ci-dessus, il n’existe qu’une seule instance matérielle flash (indiquée comme) et elle est gérée par un seul pilote flash KMDF. Le pilote flash expose deux interfaces d’appareil, chacune ciblant un type spécifique de client (ou l’API WinRT). Par exemple, étant donné la figure ci-dessus :
L’API WinRTCapture multimédia et le minidriver AVStream communiquent toujours avec le pilote flash via l’interface GUID_DEVINTERFACE_CAMERA_FLASH.
L’API Lamp WinRT communique toujours avec le pilote flash via l’interface GUID_DEVINTERFACE_LAMP.
Étant donné que l’interface GUID_DEVINTERFACE_CAMERA_FLASH est utilisée par un minidriver AVStream spécifique au fournisseur, un IHV/OEM est libre de définir son fonctionnement à leur guise : aucune restriction ne sera imposée par Windows.
Toutefois, Microsoft normalisera l’interface, GUID_DEVINTERFACE_LAMP, car elle sera utilisée par l’API Lamp WinRT. Pour plus d’informations sur GUID_DEVINTERFACE_LAMP, reportez-vous au GUID de la classe d’interface d’appareil
Cas d’utilisation de la concurrence
Partage de flash entre les applications caméra et flashlight
Un flash de caméra est généralement considéré comme un périphérique subordonné à un appareil de capture. Il n’est pas destiné à être partagé avec des scénarios sans caméra lorsque la capture est en cours. Pour compliquer davantage, le nombre d’appareils flash sur un châssis est extrêmement limité, de sorte que, dans la pratique, il n’y aura pas de flash de rechange dédié à la lampe de poche uniquement.
Du point de vue logiciel, le ci-dessus impose un défi où une application caméra et une application de lampe de poche peuvent coexister et accéder au flash en même temps. Par exemple, en théorie, un utilisateur peut changer l'état de la LED à l'aide d'une application de lampe de poche tandis qu'un viseur de caméra fonctionne.
Étant donné que l’appareil photo nécessite des contrôles précis sur le flash pour prendre en charge le focus et la capture, il peut être difficile pour le conducteur de résoudre les demandes flash d’intérêts en conflit tout en garantissant la qualité de l’image. Pour résoudre ce problème, la stratégie suivante est appliquée au niveau du système en tant que contrat :
Si une session de capture démarre en premier, une application flashlight ne peut pas manipuler le flash jusqu’à ce qu’elle s’arrête.
Une application de lampe torche peut toujours acquérir un accès au pilote du flash, mais toute opération modifiant l'état du flash génère une erreur immédiate.
Lorsque la capture s’arrête de telle sorte que le minidriver AVStream libère le flash, le pilote flash est nécessaire pour publier une notification PnP (voir GUID_LAMP_RESOURCES_AVAILABLE dans notifications asynchrones) indiquant que le matériel sous-jacent est désormais disponible. Lors de la réception d’une telle notification, une application de lampe de flash est autorisée à programmer le flash en conséquence.
Si une application de lampe de poche démarre en premier, une session de capture est gratuite pour détourner le matériel flash sans consentement explicite.
Par « détournement », nous entendons par là qu'un IHV/OEM peut implémenter un protocole arbitraire (éventuellement via l'interface GUID_DEVINTERFACE_CAMERA_FLASH) de sorte que le minidriver AVStream soit autorisé à accéder au flash comme si le matériel n'était pas du tout en cours d'utilisation.
Lorsqu’un détournement se produit, le pilote flash est requis pour publier une autre notification PnP (voir GUID_LAMP_RESOURCES_LOST dans les notifications asynchrones) indiquant que le flash a été réaffecté de manière involontaire afin que l’application de lampe de flash puisse agir en conséquence (en mettant à jour l’interface utilisateur par exemple)
Partage de flash entre plusieurs applications de lampe de flash
Si la caméra n’est pas impliquée et que deux applications de lampe de poche s’exécutent en succession, le pilote doit maintenir la maintenance du premier client qui a déjà acquis l’interface GUID_DEVINTERFACE_LAMP et rejeter tous les clients supplémentaires jusqu’à ce que le premier libère l’interface finalement.
En d’autres termes, l’interface GUID_DEVINTERFACE_LAMP autorise uniquement un client de lampe de poche à la fois et le premier client qui acquiert l’interface empêche d’autres utilisateurs de s’exécuter (appareil photo/AVStream exclu).
GUID de la classe d’interface de dispositif
Un pilote de flash IHV/OEM capable de prendre en charge une lampe indépendante de MediaCapture doit être enregistré avec le GUID de la classe d’interface de périphérique, GUID_DEVINTERFACE_LAMP.
| Caractéristique | Réglage |
|---|---|
| Identificateur | GUID_DEVINTERFACE_LAMP |
| GUID de classe | {6C11E9E3-8232-4F0A-AD19-AAEC26CA5E98} |
Le GUID de la classe d’interface d’appareil de GUID_DEVINTERFACE_CAMERA_FLASH peut être personnalisé par les IHV et OEM. Toutefois, le GUID de la classe d’interface de périphérique de GUID_DEVINTERFACE_LAMP est défini par Windows.
Par contrat, un pilote exposant l’interface de l’appareil, GUID_DEVINTERFACE_LAMP, est nécessaire pour prendre en charge les fonctions suivantes (consultez les sections ultérieures pour plus d’informations) :
IOCTL_LAMP_GET_CAPABILITIES_{WHITE|COLOR} : obtient tous les modes (par exemple, blanc uniquement et couleur) pris en charge par le matériel sous-jacent
IOCTL_LAMP_{GET|SET}_MODE : obtient ou définit le mode actuel
IOCTL_LAMP_{GET|SET}_INTENSITY_{WHITE|COLOR} : obtient ou définit l’intensité de la lumière
IOCTL_LAMP_{GET|SET}_EMITTING_LIGHT : obtient ou définit l’état flash (par exemple, ON/OFF)
Si un appareil a plusieurs matériels flash de différents types (par exemple, une LED blanche et un flash Xenon) et que ce matériel est contrôlé par différents pilotes flash, chaque pilote expose la même interface GUID_DEVINTERFACE_LAMP avec un ID d’instance unique.
Propriété de l'interface du périphérique
Étant donné qu’un appareil informatique peut avoir zéro ou plusieurs périphériques flash sur différents panneaux, l’API Lamp WinRT a besoin d’un mécanisme pour énumérer tout le matériel flash afin qu’une application puisse programmer une instance spécifique.
Pour prendre en charge l’énumération de l’appareil, similaire au pilote de caméra, le pilote flash est nécessaire pour associer une structure ACPI _PLD v2 à chaque interface GUID_DEVINTERFACE_LAMP comme données de propriété de l’interface.
IOCTL_LAMP_GET_CAPABILITIES_WHITE
La requête d’E/S IOCTL_LAMP_GET_CAPABILITIES_WHITE interroge les fonctionnalités du flash lorsque l’appareil est configuré pour émettre une lumière blanche.
Définition
#define IOCTL_LAMP_BASE FILE_DEVICE_UNKNOWN
#define IOCTL_LAMP_GET_CAPABILITIES_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0000, METHOD_BUFFERED, FILE_ANY_ACCESS)
Paramètres d’entrée
Irp-AssociatedIrp.SystemBuffer> référence une mémoire tampon de type LAMP_CAPABILITIES_WHITE. Pour plus d’informations, consultez Remarques.
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength correspond à la longueur de la mémoire tampon (en octets) transmise dans le champ Irp->AssociatedIrp.SystemBuffer.
Paramètres de sortie
Irp-AssociatedIrp.SystemBuffer> est rempli de toutes les fonctionnalités prises en charge par le matériel flash.
Bloc d’état d’E/S
Le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou l’état d’erreur approprié. Il définit Irp-IoStatus.Information> sur le nombre d’octets requis pour contenir la mémoire tampon.
Remarques
Par exigence, un flash dont le pilote prend en charge l’interface GUID_DEVINTERFACE_LAMP est nécessaire pour prendre en charge l’émission de lumière blanche. La charge utile de ce IOCTL est définie comme suit :
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_WHITE.
typedef struct LAMP_CAPABILITIES_WHITE
{
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_WHITE;
Le champ IsLightIntensityAdjustable indique si le niveau de luminance peut être programmé. Si ce champ évalue false, cela signifie que l’appareil sous-jacent prend uniquement en charge le commutateur activé/désactivé et que l’intensité de la lumière ne peut pas être ajustée.
IOCTL_LAMP_GET_CAPABILITIES_COLOR
La requête d’E/S IOCTL_LAMP_GET_CAPABILITIES_COLOR interroge les fonctionnalités du flash lorsque l’appareil est configuré pour émettre une lumière de couleur.
Définition
#define IOCTL_LAMP_GET_CAPABILITIES_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0001, METHOD_BUFFERED, FILE_ANY_ACCESS)
Paramètres d’entrée
Irp->AssociatedIrp.SystemBuffer pointe vers une mémoire tampon de type LAMP_CAPABILITIES_COLOR. Pour plus d’informations, consultez Remarques.
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength est la longueur de la mémoire tampon (en octets) passée dans le champ Irp->AssociatedIrp.SystemBuffer.
Paramètres de sortie
Irp-AssociatedIrp.SystemBuffer> est rempli de toutes les fonctionnalités prises en charge par le matériel flash.
Bloc d’état d’E/S
Le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou l’état d’erreur approprié. Il définit Irp-IoStatus.Information> sur le nombre d’octets requis pour contenir la mémoire tampon.
Remarques
La charge utile de ce IOCTL est définie comme suit :
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_COLOR.
typedef struct LAMP_CAPABILITIES_COLOR
{
BOOLEAN IsSupported;
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_COLOR;
Le premier champ, IsSupported, indique si le flash peut émettre une lumière de couleur. Si le matériel ne prend pas en charge la lumière de couleur, le pilote doit définir ce champ sur false.
Le deuxième champ, IsLightIntensityAdjustable, indique si le niveau de luminance peut être programmé. Si le flash ne prend pas en charge la lumière de couleur (par exemple, IsSupported évalue false), un client doit ignorer la valeur de IsLightIntensityAdjustable.
IOCTL_LAMP_GET_MODE
La requête d’E/S IOCTL_LAMP_GET_MODE interroge le mode avec lequel le flash est actuellement configuré.
Définition
#define IOCTL_LAMP_GET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0002, METHOD_BUFFERED, FILE_ANY_ACCESS)
Paramètres d’entrée
Irp-AssociatedIrp.SystemBuffer> pointe vers une mémoire tampon de type LAMP_MODE, qui est définie comme suit :
typedef enum LAMP_MODE
{
LAMP_MODE_WHITE = 0,
LAMP_MODE_COLOR
} LAMP_MODE;
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength est la longueur de la mémoire tampon (en octets) passée dans le champ Irp->AssociatedIrp.SystemBuffer.
Paramètres de sortie
Irp->AssociatedIrp.SystemBuffer est rempli d’une valeur LAMP_MODE.
Bloc d’état d’E/S
Le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou l’état d’erreur approprié. Il définit Irp-IoStatus.Information> sur le nombre d’octets requis pour contenir une valeur DWORD.
Si une session MediaCapture diffuse des données au moment où cette requête est effectuée, le pilote doit retourner une erreur (STATUS_RESOURCE_IN_USE) via Irp->IoStatus.Status.
IOCTL_LAMP_SET_MODE
La requête d’E/S IOCTL_LAMP_SET_MODE définit le mode dans lequel le flash fonctionne.
Définition
#define IOCTL_LAMP_SET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0003, METHOD_BUFFERED, FILE_ANY_ACCESS)
Paramètres d’entrée
Irp-AssociatedIrp.SystemBuffer> pointe vers une mémoire tampon de type LAMP_MODE.
Paramètres de sortie
Aucun.
Bloc d’état d’E/S
Le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou l’état d’erreur approprié.
Si une session MediaCapture diffuse des données au moment où cette requête est effectuée, le pilote doit retourner une erreur (STATUS_RESOURCE_IN_USE) via Irp->IoStatus.Status.
IOCTL_LAMP_GET_INTENSITY_WHITE
La requête d’E/S IOCTL_LAMP_GET_INTENSITY_WHITE interroge l’intensité de la lumière lorsque le flash est configuré pour émettre une lumière blanche.
Définition
#define IOCTL_LAMP_GET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0004, METHOD_BUFFERED, FILE_ANY_ACCESS)
Paramètres d’entrée
Irp->AssociatedIrp.SystemBuffer pointe vers une structure LAMP_INTENSITY_WHITE. Pour plus d’informations, consultez Remarques.
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength est la longueur de la mémoire tampon (en octets) passée dans le champ Irp->AssociatedIrp.SystemBuffer.
Paramètres de sortie
Irp-AssociatedIrp.SystemBuffer> est rempli d’informations sur l’intensité de la lumière.
Bloc d’état d’E/S
Le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou l’état d’erreur approprié.
Si une session MediaCapture diffuse des données au moment où cette requête est effectuée, le pilote doit renvoyer une erreur (STATUS_RESOURCE_IN_USE) via Irp->IoStatus.Status.
Remarques
Le type de charge utile de ce IOCTL est défini comme suit :
// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_WHITE.
typedef struct LAMP_INTENSITY_WHITE
{
BYTE Value;
} LAMP_INTENSITY_WHITE;
Le champ Valeur est l’intensité de lumière blanche en pourcentage compris entre 0 et 100 inclus.
IOCTL_LAMP_SET_INTENSITY_WHITE
La requête d’E/S IOCTL_LAMP_SET_INTENSITY_WHITE définit le flash sur l’intensité de lumière spécifiée.
Définition
#define IOCTL_LAMP_SET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0005, METHOD_BUFFERED, FILE_ANY_ACCESS)
Paramètres d’entrée
Irp->AssociatedIrp.SystemBuffer pointe vers une structure LAMP_INTENSITY_WHITE (voir IOCTL_LAMP_GET_INTENSITY_WHITE pour plus d'informations).
Paramètres de sortie
Aucun.
Bloc d’état d’E/S
Le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou l’état d’erreur approprié.
Si une session MediaCapture diffuse des données au moment où la requête est effectuée, le pilote doit retourner une erreur (STATUS_RESOURCE_IN_USE) via Irp->IoStatus.Status.
IOCTL_LAMP_OBTENIR_INTENSITÉ_COULEUR
La requête d’E/S IOCTL_LAMP_GET_INTENSITY_COLOR interroge l’intensité de la lumière lorsque le flash est configuré pour émettre une lumière de couleur.
Définition
#define IOCTL_LAMP_GET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0006, METHOD_BUFFERED, FILE_ANY_ACCESS)
Paramètres d’entrée
Irp->AssociatedIrp.SystemBuffer pointe vers une structure LAMP_INTENSITY_COLOR. Pour plus d’informations, consultez Remarques.
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength est la longueur de la mémoire tampon (en octets) passée dans le champ Irp->AssociatedIrp.SystemBuffer.
Paramètres de sortie
Irp-AssociatedIrp.SystemBuffer> est rempli d’informations sur l’intensité de la lumière.
Bloc d’état d’E/S
Le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou l’état d’erreur approprié.
Si une session MediaCapture diffuse des données au moment où cette requête est effectuée, le pilote doit retourner une erreur (STATUS_RESOURCE_IN_USE) via Irp->IoStatus.Status.
Remarques
Le type de charge utile de ce IOCTL est défini comme suit :
// 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 requête d’E/S IOCTL_LAMP_SET_INTENSITY_COLOR définit le flash sur l’intensité de lumière spécifiée.
Définition
#define IOCTL_LAMP_SET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0007, METHOD_BUFFERED, FILE_ANY_ACCESS)
Paramètres d’entrée
Irp-AssociatedIrp.SystemBuffer> pointe vers une structure LAMP_INTENSITY_COLOR (voir IOCTL_LAMP_GET_INTENSITY_COLOR pour plus d’informations).
Paramètres de sortie
Aucun.
Bloc d’état d’E/S
Le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou l’état d’erreur approprié.
Si une session MediaCapture diffuse des données au moment où cette requête est effectuée, le pilote doit retourner une erreur (STATUS_RESOURCE_IN_USE) via Irp-IoStatus.Status>.
IOCTL_LAMP_GET_EMITTING_LIGHT
La requête d’E/S IOCTL_LAMP_GET_EMITTING_LIGHT vérifie si la lumière (flash) est activée.
Définition
#define IOCTL_LAMP_GET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0008, METHOD_BUFFERED, FILE_ANY_ACCESS)
Paramètres d’entrée
Irp->AssociatedIrp.SystemBuffer pointe vers un tampon de type BOOLEAN.
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength est la longueur, en octets, de la mémoire tampon passée dans le champ Irp-AssociatedIrp.SystemBuffer>.
Paramètres de sortie
Irp-AssociatedIrp.SystemBuffer> est rempli avec l’état flash avec TRUE, ce qui signifie que le flash est activé (par exemple, en émettant de la lumière) ; FALSE dans le cas contraire.
Bloc d’état d’E/S
Le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou l’état d’erreur approprié. Il définit Irp-IoStatus.Information> sur le nombre d’octets requis pour contenir une valeur DWORD.
Si une session MediaCapture diffuse des données au moment où cette requête est effectuée, le pilote doit renvoyer une erreur (STATUS_RESOURCE_IN_USE) via Irp->IoStatus.Status.
IOCTL_LAMP_SET_EMITTING_LIGHT
La demande d’E/S IOCTL_LAMP_SET_EMITTING_LIGHT active/désactive la lumière (flash).
Définition
#define IOCTL_LAMP_SET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0009, METHOD_BUFFERED, FILE_ANY_ACCESS)
Paramètres d’entrée
Irp-AssociatedIrp.SystemBuffer> pointe vers une mémoire tampon de type BOOLEAN avec TRUE indiquant ON ; FALSE dans le cas contraire.
Paramètres de sortie
Aucun.
Bloc d’état d’E/S
Le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou l’état d’erreur approprié.
Si une session MediaCapture diffuse des données au moment où cette requête est effectuée, le pilote doit retourner une erreur (STATUS_RESOURCE_IN_USE) via Irp->IoStatus.Status.
Notifications asynchrones
Comme décrit dans les cas d’utilisation concurrentiels, le pilote flash est requis pour envoyer des notifications PnP pour signaler la disponibilité des ressources. Pour ce faire, appelez IoReportTargetDeviceChange (ou IoReportTargetDeviceChangeAsynchronous) avec les GUID suivants en fonction du scénario :
La ressource flash a été supprimée, car une session de capture (ou une autre application de lampe flash) démarre :
Caractéristique Réglage Identificateur GUID_LAMP_RESOURCES_LOST GUID de classe {F770E98C-4403-48C9-B1D2-4EEC3302E41F} La ressource flash est désormais disponible :
Caractéristique Réglage Identificateur GUID_LAMP_RESOURCES_AVAILABLE GUID de classe {185FE7CE-2616-481B-9094-20BB893ACD81}