Spécification des extensions Microsoft pour la classe vidéo USB 1.5
Vue d’ensemble
1.1 Résumé
Les extensions Microsoft de la Spécification de classe vidéo USB 1.5 permet aux nouveaux contrôles et à la fonctionnalité de transférer des métadonnées d'images bien définies dans un format standard.
1.2 Décisions relatives à l’architecture
La prise en charge des métadonnées d'images de la classe vidéo USB (UVC) est disponible pour les points de terminaison ISOCH et BULK. Toutefois, dans le cas d’un point de terminaison BULK, la taille des métadonnées est limitée à 240 octets (car toutes les données de l'image vidéo sont transférées dans un seul paquet d'images vidéo sur les points de terminaison BULK).
La prise en charge des métadonnées UVC n'est disponible que pour les charges utiles basées sur des images.
La prise en charge des métadonnées UVC n'est disponible qu'à travers le pipeline de capture Media Foundation (MF).
Les métadonnées UVC sont activées. Chaque IHV/OEM ayant besoin de prendre en charge les métadonnées doit être activé via un fichier INF personnalisé.
Les métadonnées UVC ne prennent en charge que la mémoire allouée par le système. Les surfaces VRAM ou DX ne sont pas prises en charge.
2 Vue d’ensemble de l’architecture
2.1 Description
2.2.1 Découverte des capacités via INF
2.2.1.1 Capture d’images fixes – Méthode 2
Certains appareils UVC existants peuvent ne pas prendre en charge la Méthode 2 décrite au point 2.4.2.4 (Capture d’images fixes) du fichier UVC 1.5 Class specification.pdf qui peut être téléchargé sur le site web USB Video Class specification.
Dans Windows 10, version 1607 et antérieures, le pipeline de capture n'utilisait pas la Méthode 2, même si un appareil annonçait sa prise en charge conformément à la spécification UVC 1.5.
Dans Windows 10, version 1703, les appareils qui utilisent cette méthode doivent utiliser un fichier INF personnalisé pour le pilote de caméra, mais un INF personnalisé est également requis pour le matériel concerné pour activer la Méthode 2 de capture d’image fixe.
Remarque : le pilote de caméra peut être basé sur le USBVIDEO.SYS de Windows ou sur un fichier binaire de pilote personnalisé.
Le fichier INF personnalisé, basé sur un pilote UVC personnalisé ou un pilote UVC inbox, doit inclure l’entrée AddReg suivante :
EnableDependentStillPinCapture: REG_DWORD: 0x0 (désactivé) à 0x1 (activé)
Lorsque cette entrée est activée (0x1), le pipeline de capture utilise la Méthode 2 pour la capture d’images fixes (en supposant que le microprogramme annonce également la prise en charge de la Méthode 2, conformément aux indications de la spécification UVC 1.5).
Un exemple possible pour la section INF personnalisée serait :
[USBVideo.NT.Interfaces]
AddInterface=%KSCATEGORY_CAPTURE%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_RENDER%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_VIDEO%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_RENDER_EXT%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_VIDEO_CAMERA%,GLOBAL,USBVideo.Interface
[USBVideo.Interface]
AddReg=USBVideo.Interface.AddReg
[USBVideo.Interface.AddReg]
HKR,,CLSID,,%ProxyVCap.CLSID%
HKR,,FriendlyName,,%USBVideo.DeviceDesc%
HKR,,RTCFlags,0x00010001,0x00000010
HKR,,EnableDependentStillPinCapture,0x00010001,0x00000001
2.2.2 Contrôles de l’unité d’extension
L’extension Microsoft de la Spécification de classe vidéo USB pour l’activation de nouveaux contrôles est assurée par une unité d’extension identifiée par GUID MS_CAMERA_CONTROL_XU (désignée sous le nom de Microsoft-XU).
// {0F3F95DC-2632-4C4E-92C9-A04782F43BC8}
DEFINE_GUID(MS_CAMERA_CONTROL_XU,
0xf3f95dc, 0x2632, 0x4c4e, 0x92, 0xc9, 0xa0, 0x47, 0x82, 0xf4, 0x3b, 0xc8);
Une Microsoft-XU implémentée par le microprogramme de l’appareil héberge les nouveaux contrôles définis dans les sous-sections suivantes. Les définitions de requête suivantes s’appliquent à tous ces contrôles, à moins qu'une définition de substitution ne soit explicitement spécifiée pour l'un d'entre eux. Pour les définitions de D3, D4, GET_INFO, etc., veuillez vous reporter au fichier UVC 1.5 Class specification.pdf.
La requête GET_INFO indique le contrôle sans les fonctionnalités AutoUpdate et Asynchronous (à savoir, les bits D3 et D4 doivent être ajustés sur 0).
La requête GET_LEN indique la longueur maximale de la charge utile pour ce contrôle (wLength).
La requête GET_RES indique la résolution (taille du pas) pour qwValue/dwValue. Tous les autres champs doivent être ajustés sur 0.
La requête GET_MIN indique la valeur minimale prise en charge pour qwValue/dwValue. Tous les autres champs doivent être ajustés sur 0.
La requête GET_MAX indique la valeur maximale prise en charge pour qwValue/dwValue. De plus, tous les indicateurs pris en charge doivent être ajustés sur 1 dans bmControlFlags. Tous les autres champs doivent être ajustés sur 0.
Les requêtes GET_DEF et GET_CUR indiquent respectivement les valeurs par défaut et actuelles des champs qwValue/dwValue et bmControlFlags. Tous les autres champs doivent être ajustés sur 0.
Une requête SET_CUR est émise par l’hôte une fois que tous les champs ont été définis.
Le tableau suivant présente les sélecteurs de contrôle de la Microsoft-XU avec leurs valeurs respectives et la position de bit pour le champ bmControls dans le descripteur d’unité d’extension :
| Sélecteur de contrôle | Valeur | Position de bit (champ bmControls) |
|---|---|---|
| MSXU_CONTROL_UNDEFINED | 0x00 | NA |
| MSXU_CONTROL_FOCUS | 0x01 | D0 |
| MSXU_CONTROL_EXPOSURE | 0x02 | D1 |
| MSXU_CONTROL_EVCOMPENSATION | 0x03 | D2 |
| MSXU_CONTROL_WHITEBALANCE | 0x04 | D3 |
| Paramètres réservés pour un usage ultérieur | 0x05 | D4 |
| MSXU_CONTROL_FACE_AUTHENTICATION | 0x06 | D5 |
| MSXU_CONTROL_CAMERA_EXTRINSICS | 0x07 | D6 |
| MSXU_CONTROL_CAMERA_INTRINSICS | 0x08 | D7 |
| MSXU_CONTROL_METADATA | 0x09 | D8 |
| MSXU_CONTROL_IR_TORCH | 0x0A | D9 |
| MSXU_CONTROL_DIGITALWINDOW | 0X0B | J10 |
| MSXU_CONTROL_DIGITALWINDOW_CONFIG | 0X0C | D11 |
| MSXU_CONTROL_VIDEO_HDR | 0X0D | D12 |
| MSXU_CONTROL_FRAMERATE_THROTTLE | 0x0E | D13 |
| MSXU_CONTROL_FIELDOFVIEW2_CONFIG | 0x0F | D14 |
| MSXU_CONTROL_FIELDOFVIEW2 | 0x10 | D15 |
2.2.2.1 Contrôles annulables
Un contrôle annulable est défini ici à l’aide de la fonctionnalité AutoUpdate.
La requête GET_INFO indique ce contrôle comme AutoUpdate (à savoir, le bit D3 doit être défini sur 1), et non pas comme Asynchronous (à savoir, le bit D4 doit être défini sur 0).
Pour ce type de contrôle, une requête SET_CUR peut être émise pour définir une nouvelle valeur (une requête SET_CUR(NORMAL), où le bit bmOperationFlags :D0 est défini sur 0) ou annuler une requête SET_CUR(NORMAL) antérieure (une requête SET_CUR(CANCEL), où le bit bmOperationFlags :D0 est défini sur 1). Une requête SET_CUR doit être exécutée immédiatement par l’appareil dès sa réception (même si le matériel n’est pas configuré ou n'a pas convergé vers les nouvelles configurations demandées). Pour chaque requête SET_CUR(NORMAL), l’appareil produit une interruption Control Change pour ce contrôle, qui est levée lorsque les nouvelles configurations sont appliquées ou lorsqu’une requête SET_CUR(CANCEL) est reçue. Jusqu’à ce que cette interruption se produise, la requête SET_CUR(NORMAL) est considérée comme étant en cours. Lorsqu’une requête SET_CUR(NORMAL) est en cours, toute requête SET_CUR(NORMAL) supplémentaire pour ce contrôle particulier entraîne un échec. Une requête SET_CUR(CANCEL) réussit toujours. S’il n’y a rien à annuler, simplement, l’appareil ne fait rien.
La charge utile de l’interruption Control Change doit avoir le bit bmOperationFlags :D0 défini sur 0 si les paramètres spécifiés par SET_CUR(NORMAL) ont été appliqués (à savoir, la convergence s’est produite), et sur 1 si les paramètres n’ont pas été appliqués en raison d’une requête SET_CUR(CANCEL) reçue après la requête SET_CUR(NORMAL) (à savoir, la convergence ne s'est pas encore produite).
2.2.2.2 Contrôle de la mise au point
Ce contrôle permet au logiciel hôte de préciser la configuration de la mise au point de la caméra. Il s’agit d’un contrôle global qui affecte tous les points de terminaison sur toutes les interfaces de streaming vidéo associées à l’interface de contrôle vidéo.
Ce contrôle doit fonctionner comme un contrôle annulable (se reporter au point 2.2.2.1 pour les spécifications de la requête GET_INFO et le comportement fonctionnel de la requête SET_CUR).
Spécification GET_MAX : ce contrôle annonce la prise en charge des bits D0, D1, D2, D8 et D18 dans bmControlFlags.
Spécification GET_DEF : la valeur par défaut pour bmControlFlags doit être D0 et D18 définis sur 1 et dwValue définie sur 0.
Pour les requêtes GET_CUR/SET_CUR, les restrictions suivantes s’appliquent pour le champ bmControlFlags :
Un seul des bits D0, D1 et D8 peut être défini ; aucun d’entre eux n’est valide si le bit D2 est défini.
Un seul des bits D16, D17, D18, D19 et D20 peut être défini. Il est également possible de n'en définir aucun.
D1 est incompatible avec tous les autres bits actuellement définis (D0, D2, D8, D16, D17, D18, D19 et D20).
D2 est incompatible avec D1 et D8.
D2 est incompatible avec D16, D17, D18, D19 et D20 si D0 n’est pas défini.
2.2.2.3 Contrôle de l'exposition
Ce contrôle permet au logiciel hôte de préciser la configuration de l'exposition de la caméra. Il s’agit d’un contrôle global qui affecte tous les points de terminaison sur toutes les interfaces de streaming vidéo associées à l’interface de contrôle vidéo.
La requête GET_INFO indique ce contrôle comme Asynchronous (à savoir, le bit D4 doit être défini sur 1), et non pas comme AutoUpdate (à savoir, le bit D3 doit être défini sur 0).
Spécification GET_MAX : ce contrôle annonce la prise en charge des bits D0, D1 et D2 dans bmControlFlags.
Spécification GET_DEF : la valeur par défaut pour bmControlFlags doit être D0 défini sur 1 et qwValue définie sur 0.
Pour les requêtes GET_CUR/SET_CUR, les restrictions suivantes s’appliquent pour le champ bmControlFlags :
- Au moins un des bits D0, D1 et D2 doit être défini.
- D1 est incompatible avec D0 et D2.
2.2.2.4 Contrôle de la compensation de la valeur d'exposition (EV)
Ce contrôle permet au logiciel hôte de préciser la configuration de la compensation de la valeur d'exposition pour la caméra. Il s’agit d’un contrôle global qui affecte tous les points de terminaison sur toutes les interfaces de streaming vidéo associées à l’interface de contrôle vidéo.
La requête GET_INFO indique ce contrôle comme Asynchronous (à savoir, le bit D4 doit être défini sur 1), et non pas comme AutoUpdate (à savoir, le bit D3 doit être défini sur 0).
La requête GET_RES indique toutes les résolutions prises en charge (taille du pas) en définissant les bits correspondants dans bmControlFlags. Tous les autres champs doivent être ajustés sur 0.
Les requêtes GET_MIN et GET_MAX indiquent les valeurs minimale et maximale prises en charge pour dwValue. Le bit D4 (indiquant la taille du pas 1) doit être le seul bit défini dans bmControlFlags. Tous les autres champs doivent être ajustés sur 0.
Les requêtes GET_DEF, GET_CUR, SET_CUR doivent suivre les définitions du point 2.2.2.1, mais un seul des bits D0, D1, D2, D3 et D4 doit être défini pour le champ bmControlFlags. De plus, la requête GET_DEF doit définir dwValue sur 0.
2.2.2.5 Contrôle de la balance des blancs
Ce contrôle permet au logiciel hôte de préciser la configuration de la balance des blancs de la caméra. Il s’agit d’un contrôle global qui affecte tous les points de terminaison sur toutes les interfaces de streaming vidéo associées à l’interface de contrôle vidéo.
La requête GET_INFO indique ce contrôle comme Asynchronous (à savoir, le bit D4 doit être défini sur 1), et non pas comme AutoUpdate (à savoir, le bit D3 doit être défini sur 0).
Les requêtes GET_RES, GET_MIN, GET_MAX doivent suivre les définitions du point 2.2.2.1, mais dwValueFormat doit être définie sur 1.
Spécification GET_MAX : ce contrôle annonce la prise en charge des bits D0, D1 et D2 dans bmControlFlags.
Spécification GET_DEF : la valeur par défaut pour bmControlFlags doit être D0 défini sur 1 et dwValueFormat et dwValue définies sur 0.
Pour les requêtes GET_CUR/SET_CUR, les restrictions suivantes s’appliquent pour le champ bmControlFlags :
- Au moins un des bits D0, D1 et D2 doit être défini.
- D1 est incompatible avec D0 et D2.
2.2.2.6 Contrôle de l’authentification des visages
Ce contrôle permet au logiciel hôte de préciser si la caméra prend en charge les modes de streaming utilisés pour l’authentification des visages. La prise en charge de ce contrôle implique que la caméra est capable d'authentifier les visages. Dans le cas contraire, ce contrôle ne doit pas être pris en charge.
Ce contrôle s’applique uniquement aux caméras capables de produire des données infrarouges (IR) et aux interfaces de streaming spécifiées (à savoir, un sous-ensemble de toutes les interfaces de streaming vidéo associées à l’interface de contrôle vidéo).
Les requêtes GET_RES et GET_MIN indiquent le champ bNumEntries défini sur 0 et n’ont donc pas de champs supplémentaires.
Dans le cas d'une requête GET_MAX, un bit défini sur 1 pour le champ bmControlFlags indique que le mode correspondant est pris en charge pour cette interface de streaming. Une sortie de requête GET_MAX doit répertorier uniquement toutes les interfaces de streaming dont le bit D1 ou D2 est défini sur 1 (à savoir, si le bit D1 ou D2 d'une interface de streaming est défini sur 1, celle-ci est répertoriée ; dans le cas contraire, elle ne l’est pas). De plus, il ne doit y avoir aucune annonce d'interface de streaming dont les bits D1 et D2 sont tous deux définis sur 1. Si une interface de streaming est également destinée à un usage général (en dehors de l’objectif d’authentification des visages), pour celle-ci, D0 doit être défini sur 1 (en plus de D1/D2).
Dans le cas des requêtes GET_DEF / GET_CUR / SET_CUR, un bit défini sur 1 pour le champ bmControlFlags indique que le mode correspondant est choisi pour cette interface de streaming. Dans ces requêtes, pour une interface de streaming donnée, un seul des bits D0, D1 & D2 doit être défini. Pour la requête GET_DEF qui retourne le choix par défaut (qui est spécifique à l’implémentation), si une interface de streaming est également destinée à un usage général (c'est-à-dire en dehors de l’objectif d’authentification des visages), pour celle-ci, D0 doit être défini sur 1 par défaut ; dans le cas contraire, D1 ou D2 (mais pas les deux) doit être défini sur 1 par défaut. Une sortie de requête GET_DEF/GET_CUR doit contenir des informations sur toutes les interfaces de streaming répertoriées dans la sortie de requête GET_MAX, mais une requête SET_CUR ne peut inclure qu'un sous-ensemble des interfaces de streaming répertoriées dans la sortie de requête GET_MAX.
Exemple :
Supposons qu’une caméra est pourvue de quatre interfaces de streaming vidéo numérotées 0x03, 0x05, 0x08 et 0x0b, dont la numéro 0x05 produit des données RVB, tandis que les trois autres produisent des données IR. Parmi les interfaces de streaming qui produisent des données IR, supposons que la 0x03 et la 0x0b sont toutes deux définies sur D1, mais que la 0x03 est également définie sur D0. Dans cet exemple, le contrôle d’authentification des visages s’applique uniquement aux interfaces de streaming 0x03 et 0x0b et, par conséquent, seules celles-ci apparaissent dans les requêtes.
La sortie de la requête GET_MAX doit être la suivante :
La sortie de la requête GET_DEF doit être la suivante :
Une requête SET_CUR pour modifier la configuration de l’interface de streaming 0x03 sur D1 serait la suivante :
La sortie d’une requête GET_CUR après la requête SET_CUR ci-dessus doit être la suivante :
2.2.2.7 Contrôle des informations extrinsèques de la caméra
Ce contrôle permet au logiciel hôte d’obtenir les données extrinsèques de la caméra pour les points de terminaison sur les interfaces de streaming vidéo associées à l’interface de contrôle vidéo. Les données ainsi obtenues pour chaque point de terminaison s’affichent sous forme d’attribut MFStreamExtension_CameraExtrinsics dans le magasin d’attributs du flux correspondant (obtenu via l’appel IMFDeviceTransform ::GetOutputStreamAttributes).
Les requêtes GET_RES, GET_MIN, GET_MAX, GET_CUR indiquent le champ bNumEntries défini sur 0 et n’ont donc pas de champs supplémentaires.
La requête GET_DEF doit répertorier tous les points de terminaison pour lesquels les informations extrinsèques sont disponibles.
Exemple :
Supposons qu’une caméra est pourvue de trois interfaces de streaming vidéo numérotées 0x03, 0x05 et 0x08, dont la numéro 0x05 prend en charge la capture d'images fixes par la méthode 2, en plus de la capture vidéo prise en charge par toutes les interfaces vidéo. Parmi ces interfaces de streaming, supposons que des informations extrinsèques sont disponibles pour la 0x05 et la 0x08, et non pour la 0x03.
Dans cet exemple, la sortie de requête GET_DEF doit être la suivante :
2.2.2.8 Contrôle des informations intrinsèques de la caméra
Ce contrôle permet au logiciel hôte d’obtenir les données intrinsèques de la caméra pour les points de terminaison sur les interfaces de streaming vidéo associées à l’interface de contrôle vidéo. Les données ainsi obtenues pour chaque point de terminaison s’affichent sous forme d’attribut MFStreamExtension_PinholeCameraIntrinsics dans le magasin d’attributs du flux correspondant (obtenu via l’appel IMFDeviceTransform ::GetOutputStreamAttributes).
Les requêtes GET_RES, GET_MIN, GET_MAX, GET_CUR indiquent le champ bNumEntries défini sur 0 et n’ont donc pas de champs supplémentaires.
La requête GET_DEF doit répertorier tous les points de terminaison pour lesquels les informations intrinsèques sont disponibles.
Exemple :
Supposons qu’une caméra est pourvue de trois interfaces de streaming vidéo numérotées 0x03, 0x05 et 0x08, dont la numéro 0x05 prend en charge la capture d'images fixes par la méthode 2, en plus de la capture vidéo prise en charge par toutes les interfaces vidéo. Parmi ces interfaces de streaming, supposons que des informations intrinsèques sont disponibles pour la 0x05 et la 0x08, et non pour la 0x03.
Dans cet exemple, la sortie de requête GET_DEF doit être la suivante :
2.2.2.9 Contrôle des métadonnées
Ce contrôle permet au logiciel hôte d’interroger et de contrôler les métadonnées produites par la caméra. Il s’agit d’un contrôle global qui affecte tous les points de terminaison sur toutes les interfaces de streaming vidéo associées à l’interface de contrôle vidéo.
Ce contrôle est mappé à KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA par le pilote de la caméra.
Si la requête SET_CUR est prise en charge par le microprogramme, les conditions suivantes s’appliquent :
Les requêtes GET_MIN, GET_DEF indiquent que le champ dwValue est défini sur 0.
La requête GET_RES indique que le champ dwValue contient la même valeur que celle signalée dans la requête GET_MAX.
Lorsqu’une requête SET_CUR est reçue avec dwValue définie sur 0, la caméra ne produit aucune métadonnée. Lorsqu’une requête SET_CUR est reçue avec dwValue définie sur la même valeur que celle signalée par GET_MAX demande, la caméra peut produire des métadonnées dont la taille, pour chaque image, ne peut pas dépasser la valeur dwValue.
Si la requête SET_CUR n'est pas prise en charge par le microprogramme, les conditions suivantes s’appliquent :
Les requêtes GET_MIN, GET_DEF indiquent que le champ dwValue contient la même valeur que celle signalée dans la requête GET_MAX.
La requête GET_RES indique que le champ dwValue est défini sur 0.
La caméra peut produire des métadonnées dont la taille, pour chaque image, ne peut pas dépasser la valeur dwValue (indiquée par la requête GET_MAX) multipliée par 1 024 octets, moins la taille de la charge utile des métadonnées d'un UsbVideoHeader.
La charge utile des métadonnées d'un UsbVideoHeader est sizeof(KSCAMERA_METADATA_ITEMHEADER) + sizeof(KSTREAM_UVC_METADATA) ou 24 octets.
Les métadonnées produites sont conformes aux métadonnées au format standard Microsoft décrites au point 2.2.3.
2.2.2.10 Contrôle de la lampe IR
Ce contrôle fournit au matériel LED IR un moyen flexible d'indiquer dans quelle mesure il est susceptible d'être contrôlé et offre la possibilité de le contrôler. Il s’agit d’un contrôle global qui affecte tous les points de terminaison sur toutes les interfaces de streaming vidéo associées à l’interface de contrôle vidéo en ajustant la puissance d'une lampe IR connectée à la caméra.
Ce contrôle est mappé à KSPROPERTY_CAMERACONTROL_EXTENDED_IRTORCHMODE par le pilote de la caméra.
Les conditions suivantes s’appliquent :
La requête GET_LEN indique une valeur de 8.
La requête GET_INFO indique une valeur de 3. Cette valeur indique un contrôle synchrone qui prend en charge GET_CUR et SET_CUR.
La requête GET_MIN indique que le champ dwMode est défini sur 0 et dwValue sur une valeur indiquant la puissance minimale. Un niveau de puissance égal à 0 peut indiquer OFF, mais la puissance opérationnelle minimale n'est pas forcément 0.
La requête GET_RES indique que le champ dwMode est défini sur 0 et dwValue sur un nombre inférieur ou égal à GET_MAX(dwValue) – GET_MIN(dwValue), et tel que GET_MAX(dwValue) – GET_MIN(dwValue) est uniformément divisible par cette valeur. dwValue peut être différente de zéro (0).
La requête GET_MAX indique que le champ dwMode est configuré avec les bits D[0-2] définis de sorte à identifier les fonctionnalités de ce contrôle. dwMode doit avoir son bit D0 défini sur 1, avec indication de prise en charge OFF, et il doit y avoir au moins un autre jeu de bits prenant en charge un état actif. dwValue doit être défini sur une valeur indiquant une puissance normale.
La requête GET_DEF indique que le champ dwMode est défini sur le mode par défaut dans lequel le système doit se trouver avant que ne commence le streaming. dwMode doit être défini sur 2 (ON) ou 4 (ALTERNATING). dwValue doit être défini sur le niveau de puissance normalement utilisé pour le contrôle FaceAuth. dwValue est défini par le fabricant.
La requête GET_CUR indique que le champ dwMode est défini sur le mode d’exploitation actuel et dwValue sur l’éclairage actuel.
Lorsqu’une requête SET_CUR est reçue, la lampe IR définit l’éclairage selon une intensité au prorata à l’aide du mode d’exploitation requis.
La lampe IR doit émettre l’attribut MF_CAPTURE_METADATA_FRAME_ILLUMINATION pour chaque image. Elle peut le fournir via un appareil MFT ou en incluant un attribut MetadataId_FrameIllumination dans la charge utile des métadonnées provenant de la caméra. Consultez la section 2.2.3.4.4.
Le seul objectif de ces métadonnées est d’indiquer si une image est éclairée ou non. Il s’agit des mêmes métadonnées que celles requises par la DDI KSPROPERTY_CAMERACONTROL_EXTENDED_FACEAUTH_MODE et MSXU_FACE_AUTHENTICATION_CONTROL définie au point 2.2.2.6.
2.2.2.11 Contrôle de la fenêtre numérique
La fenêtre numérique précise le champ de vue et le zoom de la caméra lorsque celle-ci est en streaming. Ce contrôle est un substitut potentiel de la vue panoramique, de l’inclinaison et du zoom. Ce contrôle s’applique uniquement lorsque la caméra est en streaming actif.
Ce contrôle est disponible pour tous les types de caméras et est indépendant du type de média en cours de streaming.
Ce contrôle permet au logiciel hôte d’interroger et de contrôler la fenêtre numérique associée à une caméra.
Il s’agit d’un contrôle global qui affecte tous les points de terminaison sur toutes les interfaces de streaming vidéo associées à l’interface de contrôle vidéo. Il ajuste la source des données de type pixel utilisées par l’ISP. Cela inclut les broches de capture d'images fixes de la Méthode 2 et de la Méthode 3.
Ce contrôle est mappé à KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW par le pilote de caméra inbox.
Les conditions suivantes s’appliquent :
La requête GET_LEN indique une valeur de 16.
La requête GET_INFO indique une valeur de 3. Cette valeur indique un contrôle synchrone qui prend en charge GET_CUR et SET_CUR.
La requête GET_MIN indique que le champ dwMode est défini sur 0, OriginX et OriginY sur 0.0 et WindowSize sur 1.0. Cette requête n’est actuellement pas utilisée.
La requête GET_RES indique que le champ dwMode est défini sur 0, OriginX et OriginY sur 0.0 et WindowSize sur 1.0. Cette requête n’est actuellement pas utilisée.
La requête GET_MAX indique que le champ dwMode est configuré avec le bit D0 défini de sorte à identifier les fonctionnalités de ce contrôle. La valeur 0 indique que seul le mode manuel est pris en charge. La valeur 1 indique que le mode de cadrage automatique des visages est pris en charge. Les autres champs ne sont pas utilisés, mais nous vous recommandons toutefois de définir OriginX et OriginY sur 0.0 et WindowSize sur 1.0.
La requête GET_DEF indique que le champ dwMode est défini sur 0, OriginX et OriginY sur 0.0 et WindowSize sur 1.0. Il s’agit toujours de la fenêtre par défaut.
La requête GET_CUR indique que le champ dwMode est défini sur le mode d’exploitation actuel, et OriginX, OriginY et WindowsSize décrivent la fenêtre numérique actuelle.
Lorsqu’une requête SET_CUR est reçue, la caméra ajuste son champ de vue pour qu’il corresponde au mode d’exploitation sélectionné et à la fenêtre numérique.
Si le mode de cadrage automatique des visages est sélectionné, la caméra sélectionne une fenêtre qui englobe entièrement le visage dominant dans la scène, et les champs OriginX, OriginY et WindowSize transmis sont ignorés. Si aucun visage n’est détecté, la fenêtre par défaut est utilisée.
Toute modification apportée à la fenêtre numérique doit être reflétée dans la charge utile des métadonnées de chaque échantillon.
Les modifications apportées à la fenêtre numérique peuvent ne pas être effectives immédiatement, mais le contrôle doit répondre sans délai. Les modifications apportées à la fenêtre numérique doivent être signalées dans la charge utile des métadonnées de l'image dès qu’elles entrent en vigueur.
2.2.2.12 Contrôle de la configuration de la fenêtre numérique
Le contrôle des fonctionnalités de configuration de la fenêtre numérique spécifie les limites de mise à l’échelle de la caméra en fonction de toutes les résolutions disponibles. Les résolutions sont indépendantes du type de média, de sorte que deux types de médias qui annoncent la même résolution d’affichage sont combinés en une seule fonctionnalité.
En raison des limitations de taille s'appliquant à un point de terminaison de contrôle, ce contrôle peut décrire au maximum 1 820 résolutions uniques.
Ce contrôle doit toujours être disponible pour indiquer les fonctionnalités du contrôle de la fenêtre numérique si ce contrôle est également présent.
Ce contrôle est mappé à KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW_CONFIGCAPS par le pilote de caméra inbox.
Les conditions suivantes s’appliquent :
La requête GET_LEN indique la taille entière de la charge utile. La taille de la charge utile doit être un multiple de 36, car la longueur de chaque définition de résolution est de 36 octets.
La requête GET_INFO indique un 1. Cette valeur indique un contrôle synchrone qui prend uniquement en charge GET_CUR.
La requête GET_CUR indique un tableau de fonctionnalités. Les champs de la structure de la fonctionnalité sont définis ci-dessus.
Les requêtes GET_MIN, GET_MAX, GET_RES et GET_DEF sont inutilisées, mais doivent retourner les mêmes valeurs que GET_CUR.
Les requêtes SET_CUR ne sont pas prises en charge.
2.2.2.13 Contrôle de vidéo HDR
Ce contrôle permet au logiciel hôte de préciser si la caméra prend en charge la fonctionnalité Vidéo HDR. La prise en charge de ce contrôle implique que la caméra est capable d’effectuer des vidéos HDR selon le principe du meilleur effort. Si la caméra ne prend pas en charge la vidéo HDR, elle ne doit pas implémenter ce contrôle.
Ce contrôle est mappé à KSPROPERTY_CAMERACONTROL_EXTENDED_VIDEOHDR par le pilote de la caméra.
Les conditions suivantes s’appliquent :
La requête GET_LEN indique la taille entière de la charge utile (par exemple, 4 octets).
La requête GET_INFO indique la valeur 3. Cette valeur indique un contrôle synchrone qui prend en charge GET_CUR, SET_CUR.
La requête GET_CUR indique que le champ dwMode est défini sur le mode d'exploitation actuel.
GET_DEF doit avoir un dwMode défini sur OFF (0).
La requête GET_MAX doit annoncer la prise en charge des modes d’exploitation disponibles : [1 (ON/OFF), 3 (ON/OFF/Auto)]. La prise en charge de ON (1) est obligatoire pour ce contrôle.
Les requêtes GET_MIN et GET_RES indiquent 0.
La requête SET_CUR doit définir le mode sur OFF (0), ON (1) ou AUTO (2).
2.2.2.14 Contrôle de la limitation de la fréquence d'images
Ce contrôle permet au logiciel hôte de préciser si la caméra prend en charge la limitation de la fréquence d'images.
Ce contrôle s’applique uniquement lorsque la caméra est en streaming actif. Pour que la caméra soit considérée en streaming actif, une broche de preview ou d'enregistrement doit se trouver dans KSSTATE_RUN, prête et disposée à fournir des images. Sur un jeu n'ayant pas de streaming actif, ce contrôle doit retourner STATUS_INVALID_DEVICE_STATE.
Même s’il s’agit d’un contrôle d’étendue de filtre, le contrôle de la fréquence d'images ne doit pas avoir d’impact sur la broche photo ou les flux sans RVB tels que l’IR/la profondeur. En outre, lorsque la limitation de la fréquence d'images est activée, la durée de l’échantillon doit également être ajustée en conséquence.
Ce contrôle est mappé à KSPROPERTY_CAMERACONTROL_EXTENDED_FRAMERATE_THROTTLE par le pilote de la caméra.
| Sélecteur de contrôle | MSXU_CONTROL_FRAMERATE_THROTTLE |
|---|---|
| Requêtes obligatoires | GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR, SET_CUR |
| Requêtes facultatives | |
| wLength | 20 |
| Décalage | Champ | Size | Valeur | Description |
|---|---|---|---|---|
| 0 | dwMode | 4 | Indicateurs | D0 : 0 (OFF) ou 1 (ON) D1-D31 : réservés et définis sur 0 |
| 4 | scaleFactorPercentage | 4 | Number | Cette valeur doit être comprise entre Min et Max, et correspondre à un multiple de la valeur de Pas. Par exemple : si Min = 5, Max = 100 et Pas = 5, et si une application a décidé de réduire la fréquence d’images à 80 % de la valeur d’origine, cette valeur membre doit être définie sur 80. Une définition appropriée de cette valeur permet à une application de s'assurer que la nouvelle fréquence d'images ne dépasse jamais sa valeur d’origine, et n'est jamais nulle, mais la fréquence d'origine est possible. |
| 8 | min | 4 | Number | La valeur Min doit être égale à au moins un pas ou à un multiple de la valeur de pas (par exemple : pas1, pas2, etc.).. La valeur minimale ne peut pas être 0. |
| 12 | max | 4 | Number | La valeur Max doit être de 100, ce qui indique qu’aucune modification n’est apportée à la fréquence d'images. |
| 16 | step | 4 | Number | La valeur de Pas doit être un facteur strict de la valeur Max, par exemple, {Max % Pas == 0}. Exemple : 1, 2, 4, 5, etc. |
Les conditions suivantes s’appliquent :
La requête GET_LEN indique la taille entière de la charge utile (par exemple, 20 octets).
La requête GET_INFO indique la valeur 3. Cette valeur indique un contrôle synchrone qui prend en charge GET_CUR, SET_CUR.
La requête GET_CUR indique que le champ dwMode est défini sur le mode d’exploitation actuel et scaleFactorPercentage sur la valeur scaleFactor actuelle. Min, Max et Pas indiquent les valeurs décrites dans le tableau ci-dessus.
GET_DEF doit avoir dwMode défini sur OFF(0), scaleFactorPercentage=100, Min défini sur la valeur minimale par défaut, Max sur 100 et Pas sur la valeur de pas par défaut. Les valeurs de Min et de Pas doivent être définies par le fabricant, tout en respectant les instructions mentionnées dans le tableau ci-dessus.
La requête GET_MAX doit annoncer la prise en charge des modes d’exploitation disponibles et indiquer la valeur 1 [ ON | OFF ]. La prise en charge de ON et OFF est obligatoire pour ce contrôle. Min, Max, Pas et scaleFactorPercentage peuvent être définis sur les valeurs par défaut.
Les requêtes GET_MIN et GET_RES indiquent 0.
La requête SET_CUR doit définir le mode sur OFF(0) ou ON(1). Si dwMode est défini sur ON, scaleFactorPercentage s'active. Aussi bien dans le cas OFF que ON, scaleFactorPercentage doit être valide conformément au tableau ci-dessus.
2.2.2.15 Contrôle de la configuration du champ de vue 2
Le contrôle de la configuration du champ de vue 2 spécifie les valeurs en degrés du champ de vue en diagonale prises en charge sous forme de tableau de valeurs. Toutes les valeurs prises en charge doivent être comprises dans la plage de valeurs théoriques minimales et maximales, de 1 à 360 degrés.
Si l’appareil souhaite prendre en charge des valeurs de champ de vue continues, il doit indiquer toutes les valeurs prises en charge. Par exemple, si l’appareil souhaite prendre en charge le champ de vue en diagonale de 85 à 60 degrés avec une taille de pas de 1, il doit indiquer le tableau de valeurs [85, 84, 83, 82, ..., 62, 61, 60].
Ce contrôle doit être disponible pour indiquer les fonctionnalités lorsque le contrôle du champ de vue 2 est présent.
Il s’agit d’un contrôle de niveau de filtre synchrone.
Ce contrôle est mappé à KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2_CONFIGCAPS par le pilote de caméra.
| Sélecteur de contrôle | MSXU_CONTROL_FIELDOFVIEW2_CONFIG |
|---|---|
| Requêtes obligatoires | GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR |
| Requêtes facultatives | |
| wLength | 4 octets + Count fois 4 octets, où Count est le nombre de valeurs de champ de vue uniques. |
| Décalage | Champ | Size | Valeur | Description |
|---|---|---|---|---|
| 0 | dwDefaultFieldOfView | 4 | Number | Le champ de vue en diagonale par défaut doit être l’une des valeurs signalées dans le tableau FieldOfViewValues. |
| 4 | FieldOfViewValues[0] | 4 | Number | Première valeur du champ de vue. Il doit s'agir de la valeur de champ de vue (FoV, Field of View) la plus large. |
| … | … | … | … | … |
| 4 + 4*(Count-1) | FieldOfViewValues [Count -1] | 4 | Number | Dernière valeur du champ de vue. Il doit s'agir de la valeur de FoV la plus étroite. |
Les conditions suivantes s’appliquent :
La requête GET_LEN indique la taille entière de la charge utile.
La requête GET_INFO indique un 1. Cette valeur indique un contrôle synchrone qui prend uniquement en charge GET_CUR.
La requête GET_CUR indique les données qui contiennent les valeurs FoV et le tableau par défaut des FoV pris en charge dans l’ordre décroissant. Les champs de la structure sont définis ci-dessus.
La requête GET_DEF indique la même chose que GET_CUR.
Les requêtes GET_MIN, GET_MAX et GET_RES sont inutilisées, mais doivent retourner les mêmes valeurs que GET_CUR.
Les requêtes SET_CUR ne sont pas prises en charge.
Les valeurs de champ de vue doivent être dans l’ordre décroissant : à savoir, le champ de vue le plus large en premier, et le plus étroit en dernier.
2.2.2.16 Contrôle du champ de vue 2
Ce contrôle précise le champ de vue de base utilisé par la caméra lorsque celle-ci est en streaming. Ce contrôle peut être appliqué avant ou pendant le streaming.
Ce contrôle est disponible pour tous les types de caméras et est indépendant du type de média en cours de streaming.
Ce contrôle permet au logiciel hôte d’interroger et de contrôler le champ de vue associé à une caméra.
Il s’agit d’un contrôle global qui affecte tous les points de terminaison sur toutes les interfaces de streaming vidéo associées à l’interface de contrôle vidéo. Il ajuste la source des données de type pixel (ou capteur) utilisées par l’ISP (Image Signal Processor). Cela inclut les broches de capture d'images fixes de la Méthode 2 et de la Méthode 3.
Il s’agit d’un contrôle de niveau de filtre synchrone.
Ce contrôle est mappé à KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2 par le pilote de caméra.
| Sélecteur de contrôle | MSXU_CONTROL_FIELDOFVIEW2 |
|---|---|
| Requêtes obligatoires | GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR, SET_CUR |
| Requêtes facultatives | |
| wLength | 4 |
| Décalage | Champ | Size | Valeur | Description |
|---|---|---|---|---|
| 0 | dwValue | 4 | Number | Champ de vue en diagonale (degrés). |
Les conditions suivantes s’appliquent :
La requête GET_LEN indique une valeur de 4.
La requête GET_INFO indique un 3. Cette valeur indique un contrôle synchrone qui prend en charge GET_CUR et SET_CUR.
La requête GET_MIN indique que le champ dwValue est défini sur la valeur minimale prise en charge pour le champ de vue.
La requête GET_RES indique que le champ dwValue est défini sur 0. Cette requête n’est actuellement pas utilisée.
La requête GET_MAX indique que le champ dwValue est défini sur la valeur maximale prise en charge pour le champ de vue.
La requête GET_DEF indique que le champ dwValue est défini sur la valeur par défaut du champ de vue.
La requête GET_CUR indique que le champ dwValue est défini sur la valeur actuelle du champ de vue.
Lorsqu’une requête SET_CUR est reçue, la caméra ajuste son champ de vue pour qu’il corresponde à la valeur donnée de dwValue.
Si la caméra implémente CT_ZOOM_RELATIVE_CONTROL et/ou CT_ZOOM_ABSOLUTE_CONTROL, ces contrôles sont réinitialisés à leurs valeurs par défaut lorsque MSXU_CONTROL_FIELDOFVIEW2 SET_CUR est appelée.
Si la caméra implémente MSXU_CONTROL_DIGITALWINDOW, elle reflète le changement de fenêtre lorsqu’une nouvelle valeur du champ de vue est définie. Et vice versa, le champ de vue reflète les modifications apportées via la fenêtre numérique. Pour en savoir plus, se reporter à KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2.
2.2.3 Métadonnées
La conception des métadonnées d'images de format standard s’appuie sur la conception de métadonnées personnalisées UVC à partir de Windows 10. Dans Windows 10, les métadonnées personnalisées sont prises en charge pour UVC à l’aide d’un INF personnalisé pour le pilote de caméra (remarque : le pilote de caméra peut être basé sur USBVIDEO.SYS de Windows, mais un INF personnalisé est requis pour que le matériel concerné puisse exécuter les métadonnées). Si l’entrée de registre MetadataBufferSizeInKB<PinIndex> est présente et différente de zéro, les métadonnées personnalisées sont prises en charge pour cette broche et la valeur indique la taille du tampon utilisé pour les métadonnées. Le champ <PinIndex> indique un index de base 0 de l’index des broches vidéo.
Dans Windows 10, version 1703, un pilote de caméra peut signaler la prise en charge des métadonnées au format standard de Microsoft en saisissant l’entrée AddReg suivante :
StandardFormatMetadata<PinIndex>: REG_DWORD: 0x0 (non prises en charge) à 0x1 (prises en charge)
Cette clé de registre est lue par DevProxy et informe le pilote UVC que les métadonnées sont au format standard en définissant l’indicateur KSSTREAM_METADATA_INFO_FLAG_STANDARDFORMAT dans le champ Flags de la structure KSSTREAM_METADATA_INFO.
2.2.3.1 Métadonnées au format standard Microsoft
Les métadonnées au format standard de Microsoft constituent une ou plusieurs instances de la structure suivante :
typedef struct tagKSCAMERA_METADATA_ITEMHEADER {
ULONG MetadataId;
ULONG Size; // Size of this header + metadata payload following
} KSCAMERA_METADATA_ITEMHEADER, *PKSCAMERA_METADATA_ITEMHEADER;
Le champ MetadataId est rempli par un identificateur de la définition d’énumération suivante, qui contient des identificateurs bien définis et des identificateurs personnalisés (identificateurs >= MetadataId_Custom_Start).
typedef enum {
MetadataId_Standard_Start = 1,
MetadataId_PhotoConfirmation = MetadataId_Standard_Start,
MetadataId_UsbVideoHeader,
MetadataId_CaptureStats,
MetadataId_CameraExtrinsics,
MetadataId_CameraIntrinsics,
MetadataId_FrameIllumination,
MetadataId_Standard_End = MetadataId_FrameIllumination,
MetadataId_Custom_Start = 0x80000000,
} KSCAMERA_MetadataId;
Le champ Size est défini sur sizeof(KSCAMERA_METADATA_ITEMHEADER) + sizeof(Charge utile des métadonnées).
2.2.3.2 Métadonnées au format standard générées par le microprogramme à partir de paquets d’images vidéo USB
Pendant un transfert sur UVC pour une vidéo à base d'images, les images vidéo sont regroupées en séries de paquets, chacune précédée d’un en-tête de charge utile UVC. Chaque en-tête de charge utile UVC est défini par la spécification de charge utile basée sur les images du pilote de classe vidéo USB :
En-tête de charge utile
Vous trouverez ci-dessous une description du format d’en-tête de charge utile pour les formats à base d'images.
Champ HLE (Header length)
Ce champ spécifie la longueur de l’en-tête, en octets.
Champ d’en-tête du champ de bits
FID : identificateur de l'image
- Ce bit bascule à chaque limite de début d’image et reste constant pendant tout le reste de l’image.
EOF : fin de l'image
- Ce bit indique la fin d’une image vidéo et est défini dans le dernier échantillon vidéo appartenant à une image. L’utilisation de ce bit, qui est facultative, est une optimisation destinée à réduire la latence à la fin du transfert d'une image.
PTS : horodatage de présentation
- Ce bit, quand il est défini, indique la présence d’un champ PTS.
SCR : référence de l’horloge source
- Ce bit, quand il est défini, indique la présence d’un champ SCR.
RES : réservé.
- Définissez sur 0.
STI : image fixe
- Ce bit, lorsqu’il est défini, identifie un échantillon vidéo comme appartenant à une image fixe.
ERR : bit d’erreur
- Ce bit, lorsqu’il est défini, indique une erreur dans le streaming de l’appareil.
EOH : fin de l’en-tête
- Ce bit, quand il est défini, indique la fin des champs BFH.
PTS : horodatage de présentation, Taille : 4 octets, Valeur : nombre
- Le champ PTS est présent lorsque le bit PTS est défini dans le champ BFH[0]. Veuillez vous reporter au point 2.4.3.3 « En-têtes de charge utile de vidéos et images fixes » dans la spécification Définition de classe de périphérique USB pour les appareils vidéo.
SCR : référence de l’horloge source, Taille : 6 octets, Valeur : nombre
- Le champ SCR est présent lorsque le bit SCR est défini dans le champ BFH[0]. Veuillez vous reporter au point 2.4.3.3 En-têtes de charge utile de vidéos et images fixes dans la spécification Définition de classe de périphérique USB pour les appareils vidéo.
Le champ HLE dans le pilote UVC existant est ajusté à 2 octets (aucun PTS/SCR présent) ou jusqu’à 12 octets (PTS/SCR présent). Toutefois, le champ HLE, dont la taille est exprimée en octets, peut éventuellement spécifier jusqu’à 255 octets pour les données d’en-tête. Si PTS/SCR sont tous deux présents et que la HLE est inférieure à 12 octets, toutes les données supplémentaires qui suivent les 12 premiers octets de l’en-tête de charge utile sont récupérées comme des métadonnées standard spécifiques à l’image vidéo lorsque l’entrée INF StandardFormatMetadata<PinIndex> est définie.
Les métadonnées de format standard (générées par microprogramme) pour une image sont obtenues en concaténant les objets blob partiels trouvés dans les paquets d’images vidéo représentant cette image.
2.2.3.3 Tampon de métadonnées fourni au composant en mode utilisateur
Le tampon de métadonnées fourni au composant en mode utilisateur possède un élément de métadonnées pour les horodatages UVC (générés par le pilote UVC) suivi d'éléments de métadonnées générés par le microprogramme, selon la disposition suivante :
2.2.3.4 Format de métadonnées pour les identificateurs de métadonnées standard
Le microprogramme peut choisir s’il faut produire ou non des métadonnées correspondant à un identificateur. Si le microprogramme choisit de produire des métadonnées correspondant à un identificateur, les métadonnées de cet identificateur sont présentes sur toutes les images émises par le microprogramme.
2.2.3.4.1 MetadataId_CaptureStats
Le format de métadonnées de cet identificateur est défini par la structure suivante :
typedef struct tagKSCAMERA_METADATA_CAPTURESTATS {
KSCAMERA_METADATA_ITEMHEADER Header;
ULONG Flags;
ULONG Reserved;
ULONGLONG ExposureTime;
ULONGLONG ExposureCompensationFlags;
LONG ExposureCompensationValue;
ULONG IsoSpeed;
ULONG FocusState;
ULONG LensPosition; // a.k.a Focus
ULONG WhiteBalance;
ULONG Flash;
ULONG FlashPower;
ULONG ZoomFactor;
ULONGLONG SceneMode;
ULONGLONG SensorFramerate;
} KSCAMERA_METADATA_CAPTURESTATS, *PKSCAMERA_METADATA_CAPTURESTATS;
Le champ Flags indique quels champs ultérieurs de la structure sont remplis et ont des données valides. Le champ Flags ne doit pas varier d’une image à l’autre. Les indicateurs suivants sont actuellement définis :
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_EXPOSURETIME 0x00000001
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_EXPOSURECOMPENSATION 0x00000002
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_ISOSPEED 0x00000004
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_FOCUSSTATE 0x00000008
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_LENSPOSITION 0x00000010
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_WHITEBALANCE 0x00000020
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_FLASH 0x00000040
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_FLASHPOWER 0x00000080
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_ZOOMFACTOR 0x00000100
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_SCENEMODE 0x00000200
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_SENSORFRAMERATE 0x00000400
Le champ Reserved est réservé à une utilisation future et doit être défini sur 0.
Le champ ExposureTime contient la durée d’exposition, en 100 ns, appliquée au capteur lorsque l'image a été capturée. Il s’affiche en tant qu’attribut MF_CAPTURE_METADATA_EXPOSURE_TIME sur l’échantillon MF correspondant.
Le champ ExposureCompensationFlags contient le pas de compensation d'exposition (EV) (il faut y définir exactement l’un des indicateurs de pas KSCAMERA_EXTENDEDPROP_EVCOMP_XXX) utilisé pour transmettre la valeur de compensation d'exposition (EV). Le champ ExposureCompensationValue contient la valeur de compensation d’exposition EV en nombre d'unités de pas appliquées au capteur lorsque l'image a été capturée. Ils s’affichent en tant qu’attribut MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION sur l’échantillon MF correspondant.
Le champ IsoSpeed contient la valeur de sensibilité ISO appliquée au capteur lorsque l'image a été capturée. Il n'a aucune unité de mesure. Il s’affiche en tant qu’attribut MF_CAPTURE_METADATA_ISO_SPEED sur l’échantillon MF correspondant.
Le champ FocusState contient l’état actuel de la mise au point, qui peut prendre l’une des valeurs définies dans l’énumération KSCAMERA_EXTENDEDPROP_FOCUSSTATE. Il s’affiche en tant qu’attribut MF_CAPTURE_METADATA_FOCUSSTATE sur l’échantillon MF correspondant.
Le champ LensPosition contient la position logique de l’objectif lorsque l'image a été capturée. Il n'a aucune unité de mesure. Il s’agit de la même valeur que celle qui peut être interrogée à partir de KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS dans un appel GET. Il s’affiche en tant qu’attribut MF_CAPTURE_METADATA_LENS_POSITION sur l’échantillon MF correspondant.
Le champ WhiteBalance contient la balance des blancs appliquée au capteur lorsque l'image a été capturée. Sa valeur s'exprime en degrés Kelvin. Il s’affiche en tant qu’attribut MF_CAPTURE_METADATA_WHITEBALANCE sur l’échantillon MF correspondant.
Le champ Flash contient une valeur booléenne informant sur le flash était activé (1) ou désactivé (0) lorsque l’image a été capturée. Il s’affiche en tant qu’attribut MF_CAPTURE_METADATA_FLASH sur l’échantillon MF correspondant.
Le champ FlashPower contient la puissance de flash appliquée à l'image capturée. Sa valeur est comprise dans la plage [0, 100]. Ce champ doit être omis si le pilote ne prend pas en charge le réglage de la puissance du flash. Il s’affiche en tant qu’attribut MF_CAPTURE_METADATA_FLASH_POWER sur l’échantillon MF correspondant.
Le champ ZoomFactor contient la valeur de zoom au format Q16 appliquée à l'image capturée. Il s’affiche en tant qu’attribut MF_CAPTURE_METADATA_ZOOMFACTOR sur l’échantillon MF correspondant.
Le champ SceneMode contient le mode scène appliqué à l'image capturée, qui est un indicateur 64 bits KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX. Il s’affiche en tant qu’attribut MF_CAPTURE_METADATA_SCENE_MODE sur l’échantillon MF correspondant.
Le champ SensorFramerate contient la fréquence de lecture du capteur mesurée en Hertz lorsque l’image a été capturée, qui se compose d’un numérateur dans les 32 bits supérieurs et d'un dénominateur dans les 32 bits inférieurs. Il s’affiche en tant qu’attribut MF_CAPTURE_METADATA_SENSORFRAMERATE sur l’échantillon MF correspondant.
2.2.3.4.2 MetadataId_CameraExtrinsics
Le format de métadonnées de cet identificateur implique le KSCAMERA_METADATA_ITEMHEADER standard suivi d’une charge utile en tableau d’octets. La charge utile doit s’aligner sur une structure MFCameraExtrinsics suivie d'un zéro ou de plusieurs structures MFCameraExtrinsic_CalibratedTransform. La charge utile doit être alignée sur 8 octets, et tous les octets inutilisés doivent se produire à la fin de la charge utile et être définis sur 0.
2.2.3.4.3 MetadataId_CameraIntrinsics
Le format de métadonnées de cet identificateur implique le KSCAMERA_METADATA_ITEMHEADER standard suivi d’une charge utile en tableau d’octets. La charge utile doit être alignée sur une structure MFPinholeCameraIntrinsics. La charge utile doit être alignée sur 8 octets, et tous les octets inutilisés doivent se produire à la fin de la charge utile et être définis sur 0.
2.2.3.4.4 MetadataId_FrameIllumination
Le format de métadonnées de cet identificateur est défini par la structure suivante :
typedef struct tagKSCAMERA_METADATA_FRAMEILLUMINATION {
KSCAMERA_METADATA_ITEMHEADER Header;
ULONG Flags;
ULONG Reserved;
} KSCAMERA_METADATA_FRAMEILLUMINATION, *PKSCAMERA_METADATA_FRAMEILLUMINATION;
Le champ Flags contient des informations sur l'image capturée. Les indicateurs suivants sont actuellement définis :
#define KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON 0x00000001
Si une image a été capturée lorsque l’éclairage était allumé, l’indicateur KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON doit être défini. Dans le cas contraire, cet indicateur ne doit pas être défini.
Le champ Reserved est réservé à une utilisation future et doit être défini sur 0.
Exemple :
Par exemple, une structure KSCAMERA_METADATA_FRAMEILLUMINATION indiquant que l’éclairage était activé serait la suivante :
KSCAMERA_METADATA_FRAMEILLUMINATION.Header.MetadataId = MetadataId_FrameIllumination;
KSCAMERA_METADATA_FRAMEILLUMINATION.Header.Size = 16; // 4 ULONG variables in total inside the structure
KSCAMERA_METADATA_FRAMEILLUMINATION.Flags = KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON;
KSCAMERA_METADATA_FRAMEILLUMINATION.Reserved = 0;
2.2.3.4.5 MetadataId_USBVideoHeader
Le format de métadonnées de cet identificateur est défini par un KSCAMERA_METADATA_ITEMHEADER commun suivi d’une structure KSSTREAM_UVC_METADATA :
typedef struct
{
ULONG PresentationTimeStamp;
ULONG SourceClockReference;
union
{
struct
{
USHORT Counter : 11;
USHORT Reserved : 5;
};
USHORT SCRToken;
};
USHORT Reserved0;
ULONG Reserved1;
} KSSTREAM_UVC_METADATATYPE_TIMESTAMP, *PKSSTREAM_UVC_METADATATYPE_TIMESTAMP;
typedef struct {
KSSTREAM_UVC_METADATATYPE_TIMESTAMP StartOfFrameTimestamp;
KSSTREAM_UVC_METADATATYPE_TIMESTAMP EndOfFrameTimestamp;
} KSSTREAM_UVC_METADATA, *PKSSTREAM_UVC_METADATA;
Les champs StartOfFrameTimestamp et EndOfFrameTimestamp sont les horodatages contenus dans les en-têtes UVC des premières et dernières charges utiles UVC émises par la caméra pour construire cette image.
Cette charge utile ne doit pas être envoyée par un appareil.
Cette charge utile de métadonnées est unique, dans la mesure où il s’agit de la seule charge utile de métadonnées générée directement par le pilote de classe VIDÉO USB à partir des informations obtenues auprès d'en-têtes de charge utile compatibles UVC.
Cette charge utile est ajoutée au tampon de métadonnées de chaque image.
Si l’appareil prend en charge les métadonnées standardisées, il doit inclure l’espace nécessaire pour stocker cette charge utile dans son tampon conformément aux exigences indiquées par le contrôle de métadonnées défini au point 2.2.2.9.