Microsoft-Erweiterungen für die USB Video Class 1.5-Spezifikation

1 Übersicht

1.1 Zusammenfassung

Die Microsoft-Erweiterungen der USB Video Class-Spezifikation ermöglichen neue Steuerelemente und die Funktionalität, wohldefinierte Frame-Metadaten in einem Standardformat zu übertragen.

1.2 Architektur-Entscheidungen

Die Unterstützung von Frame-Metadaten der USB Video Class (UVC) ist für ISOCH- und BULK-Endpunkte verfügbar. Bei BULK-Endpunkten ist die Größe der Metadaten jedoch auf 240 Byte begrenzt (da alle Video-Frame-Daten bei BULK-Endpunkten in einem einzigen Video-Frame-Paket übertragen werden).

Die Unterstützung von UVC-Metadaten ist nur für Frame-basierte Payloads verfügbar.

Die Unterstützung von UVC-Metadaten ist nur über die Media Foundation (MF) Capture Pipeline verfügbar.

UVC-Metadaten sind opt-in. Jedes IHV/OEM, das Metadaten-Support benötigt, muss über eine angepasste INF-Datei aktiviert werden.

UVC-Metadaten unterstützen nur den dem System zugewiesenen Speicher. VRAM oder DX-Oberflächen werden nicht unterstützt.

2 Architekturübersicht

2.1 Beschreibung

2.2.1 Erkennung von Funktionalitäten per INF

2.2.1.1 Standbildaufnahme – Methode 2

Einige vorhandene UVC-Geräte unterstützen möglicherweise nicht die Methode 2, die in Abschnitt 2.4.2.4 ("Still Image Capture") in UVC 1.5 Class specification.pdf beschrieben wird, das Sie von der USB Video Class-Spezifikation Website herunterladen können.

In Windows 10, Version 1607 und früher, verwendete die Pipeline für die Erfassung nicht die Methode 2, selbst wenn ein Gerät die Unterstützung dafür gemäß der UVC 1.5 Spezifikation anbot.

In Windows 10, Version 1703, müssen Geräte, die diese Methode verwenden, eine angepasste INF-Datei für den Kameratreiber verwenden, aber eine angepasste INF ist für die gegebene Hardware erforderlich, um die Erfassung von Bildern nach Methode 2 zu ermöglichen.

Hinweis: Der Kameratreiber kann auf Windows USBVIDEO.SYS basieren oder auf einer angepassten Binärdatei für den Treiber beruhen.

Die angepasste INF-Datei, die entweder auf einem angepassten UVC-Treiber oder einem Inbox-UVC-Treiber basiert, sollte den folgenden AddReg-Eintrag enthalten:

EnableDependentStillPinCapture: REG_DWORD: 0x0 (deaktiviert) bis 0x1 (aktiviert)

Wenn dieser Eintrag auf Aktiviert (0x1) festgelegt ist, verwendet die Pipeline Methode 2 für die Standbildaufnahme (vorausgesetzt, die Firmware bietet auch Unterstützung für Methode 2, wie in der UVC 1.5-Spezifikation festgelegt).

Ein Beispiel für den angepassten INF-Abschnitt wäre wie folgt:

[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 Extension Unit Steuerelemente

Microsofts Erweiterung der USB Video Class-Spezifikation zur Aktivierung neuer Steuerelemente erfolgt über eine Einheit, die durch GUID MS_CAMERA_CONTROL_XU identifiziert wird (als Microsoft-XU bezeichnet).

// {0F3F95DC-2632-4C4E-92C9-A04782F43BC8}
DEFINE_GUID(MS_CAMERA_CONTROL_XU,
    0xf3f95dc, 0x2632, 0x4c4e, 0x92, 0xc9, 0xa0, 0x47, 0x82, 0xf4, 0x3b, 0xc8);

Eine Microsoft-XU, die von der Firmware des Geräts implementiert wird, enthält die neuen Steuerelemente, die in den folgenden Unterabschnitten definiert sind. Die folgenden Anfrage-Definitionen gelten für alle diese Steuerelemente, es sei denn, für das jeweilige Steuerelement ist ausdrücklich eine übergeordnete Definition angegeben. Die Definitionen von D3, D4, GET_INFO usw. finden Sie in UVC 1.5 Class specification.pdf.

Die GET_INFO-Anfrage liefert das Steuerelement ohne AutoUpdate und asynchrone Funktionalitäten (z. B . werden die Bits D3 und D4 auf 0 festgelegt).

Die GET_LEN-Abfrage liefert die maximale Länge des Payloads für dieses Steuerelement (wLength).

Die GET_RES-Anfrage liefert die Auflösung (Schrittweite) für qwValue/dwValue. Alle anderen Felder müssen auf 0 festgelegt werden.

Die Anfrage GET_MIN liefert den kleinsten unterstützten Wert für qwValue/dwValue. Alle anderen Felder müssen auf 0 festgelegt werden.

Die GET_MAX-Anfrage liefert den maximal unterstützten Wert für qwValue/dwValue. Außerdem müssen alle unterstützten Flags in bmControlFlags auf 1 festgelegt werden. Alle anderen Felder müssen auf 0 festgelegt werden.

Die Anfragen GET_DEF und GET_CUR liefern die Standard- bzw. aktuellen Einstellungen für die Felder qwValue/dwValue und bmControlFlags. Alle anderen Felder müssen auf 0 festgelegt werden.

Eine SET_CUR-Anfrage wird vom Host ausgeführt, nachdem er alle Felder festgelegt hat.

Die folgende Tabelle ordnet die Steuerelement-Selektoren für Microsoft-XU ihren jeweiligen Werten und der Bitposition für das Feld bmControls im Deskriptor der Erweiterungseinheit zu:

Steuerelement-Selektor	Wert	Bit-Position (Feld bmControls)
MSXU_CONTROL_UNDEFINED	0x00	Nicht verfügbar
MSXU_CONTROL_FOCUS	0x01	D0
MSXU_CONTROL_EXPOSURE	0x02	D1
MSXU_CONTROL_EVCOMPENSATION	0x03	D2
MSXU_CONTROL_WHITEBALANCE	0x04	D3
Für die spätere Verwendung reserviert	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	T10
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 Cancelable Steuerelemente

Ein Cancelable Steuerelement wird hier unter Verwendung der Autoupdate-Funktionalität definiert.

Die GET_INFO-Anfrage liefert ein solches Steuerelement als Autoupdate-Steuerelement (z. B. wird das D3-Bit auf 1 festgelegt), aber nicht als asynchrones Steuerelement (z. B. wird das D4-Bit auf 0 festgelegt).

Für ein solches Steuerelement kann eine SET_CUR- Anfrage gestellt werden, um einen neuen Wert festzulegen (eine SET_CUR(NORMAL)-Anfrage, bei der bmOperationFlags:D0 Bit auf 0 gesetzt wird) oder eine vorherige SET_CUR(NORMAL)-Anfrage zu löschen (eine SET_CUR(CANCEL)-Anfrage, bei der bmOperationFlags:D0 Bit auf 1 gesetzt wird). Eine SET_CUR-Anfrage sollte vom Gerät sofort abgeschlossen werden, sobald die Anfrage empfangen wird (auch wenn die Hardware noch nicht konfiguriert oder auf die angeforderten neuen Einstellungen eingestellt ist). Für jede SET_CUR(NORMAL)-Anfrage erzeugt das Gerät einen entsprechenden Control Change Interrupt für dieses Steuerelement, der ausgelöst wird, wenn die neuen Einstellungen festgelegt wurden oder wenn eine SET_CUR(CANCEL)-Anfrage eintrifft; bis zum Eintreffen dieses Interrupts wird die SET_CUR(NORMAL)-Anfrage als in Bearbeitung betrachtet. Wenn eine SET_CUR(NORMAL)-Anfrage in Bearbeitung ist, führen weitere SET_CUR(NORMAL)-Anfragen für dieses bestimmte Steuerelement zu einem Fehlschlag. Eine SET_CUR(CANCEL)-Anfrage ist immer erfolgreich. Wenn es nichts abzubrechen gibt, dann tut das Gerät einfach nichts.

In der Payload des Control Change Interrupts wird das Bit bmOperationFlags:D0 auf 0 festgelegt, wenn die durch SET_CUR(NORMAL) festgelegten Einstellungen angewendet wurden (z. B. Konvergenz ist eingetreten), und auf 1 festgelegt, wenn die Einstellungen aufgrund einer SET_CUR(CANCEL)-Anfrage, die nach der SET_CUR(NORMAL)-Anfrage kam, nicht angewendet wurden (z. B. Konvergenz ist noch nicht eingetreten).

2.2.2.2 Focus Steuerelement

Dieses Steuerelement bietet der Host-Software die Möglichkeit, die Fokuseinstellungen für die Kamera festzulegen. Es handelt sich um ein globales Steuerelement, das sich auf alle Endpunkte auf allen Video-Streaming-Schnittstellen auswirkt, die mit der Video-Steuerelement-Schnittstelle verbunden sind.

Dieses Steuerelement muss als abbrechbares Steuerelement funktionieren (siehe Abschnitt 2.2.2.1 für die Anforderungen an die GET_INFO-Anfrage und das Funktionsverhalten der SET_CUR-Anfrage).

GET_MAX-Anforderung: Dieses Steuerelement muss die Unterstützung für die Bits D0, D1, D2, D8 und D18 in bmControlFlags bekannt geben.

GET_DEF-Anforderung: Die Vorgabe für bmControlFlags ist, dass D0 und D18 auf 1 und dwValue auf 0 festgelegt werden.

Für GET_CUR/SET_CUR-Anfragen gelten die folgenden Einschränkungen für das Feld bmControlFlags:

• Von den Bits D0, D1 und D8 kann nur ein Bit festgelegt werden. Keines der Bits darf festgelegt werden, auch wenn das Bit D2 festgelegt ist.

• Von den Bits D16, D17, D18, D19 und D20 kann nur ein Bit festgelegt werden, keines davon ist gültig.

• D1 ist inkompatibel mit allen anderen derzeit definierten Bits (D0, D2, D8, D16, D17, D18, D19 und D20).

• D2 ist inkompatibel mit D1 und D8.

• D2 ist nicht kompatibel mit D16, D17, D18, D19 und D20, wenn D0 nicht festgelegt ist.

2.2.2.3 Exposure Steuerelement

Dieses Steuerelement bietet der Host-Software die Möglichkeit, die Belichtungseinstellungen für die Kamera festzulegen. Es handelt sich um ein globales Steuerelement, das sich auf alle Endpunkte auf allen Video-Streaming-Schnittstellen auswirkt, die mit der Video-Steuerelement-Schnittstelle verbunden sind.

Die GET_INFO-Anfrage meldet dieses Steuerelement als asynchrones Steuerelement (z. B. muss das Bit D4 auf 1 festgelegt werden), aber nicht als AutoUpdate-Steuerelement (z. B. muss das Bit D3 auf 0 festgelegt werden).

GET_MAX-Anforderung: Dieses Steuerelement muss die Unterstützung für die Bits D0, D1 und D2 in bmControlFlags bekannt geben.

GET_DEF-Anforderung: Die Vorgabe für bmControlFlags ist, dass D0 auf 1 und qwValue auf 0 festgelegt wird.

Für GET_CUR/SET_CUR-Anfragen gelten die folgenden Einschränkungen für das Feld bmControlFlags:

• Von den Bits D0, D1 und D2 muss mindestens ein Bit festgelegt sein.
• D1 ist mit D0 und D2 nicht kompatibel.

2.2.2.4 EV Compensation Steuerelement

Dieses Steuerelement bietet der Host-Software die Möglichkeit, die Einstellungen für die Belichtungskompensation der Kamera festzulegen. Es handelt sich um ein globales Steuerelement, das sich auf alle Endpunkte auf allen Video-Streaming-Schnittstellen auswirkt, die mit der Video-Steuerelement-Schnittstelle verbunden sind.

Die GET_INFO-Anfrage meldet dieses Steuerelement als asynchrones Steuerelement (z. B. muss das Bit D4 auf 1 festgelegt werden), aber nicht als AutoUpdate-Steuerelement (z. B. muss das Bit D3 auf 0 festgelegt werden).

Die GET_RES-Anfrage liefert alle unterstützten Auflösungen (Schrittweite), indem die entsprechenden Bits in bmControlFlags festgelegt werden. Alle anderen Felder müssen auf 0 festgelegt werden.

Die Anfragen GET_MIN und GET_MAX liefern den minimalen und maximalen unterstützten Wert für dwValue. Das Bit D4 (das die Schrittweite von 1 angibt) ist das einzige Bit, das in bmControlFlags festgelegt wird. Alle anderen Felder müssen auf 0 festgelegt werden.

Die Anfragen GET_DEF, GET_CUR und SET_CUR entsprechen den Definitionen in Abschnitt 2.2.2.1, wobei jedoch nur ein einziges Bit unter den Bits D0, D1, D2, D3 und D4 für das Feld bmControlFlags festgelegt wird. Außerdem muss bei der Anfrage GET_DEF dwValue auf 0 festgelegt sein.

2.2.2.5 White BalanceSteuerelement

Dieses Steuerelement bietet der Host-Software die Möglichkeit, die Einstellungen für den Weißabgleich der Kamera festzulegen. Es handelt sich um ein globales Steuerelement, das sich auf alle Endpunkte auf allen Video-Streaming-Schnittstellen auswirkt, die mit der Video-Steuerelement-Schnittstelle verbunden sind.

Die GET_INFO-Anfrage meldet dieses Steuerelement als asynchrones Steuerelement (z. B. muss das Bit D4 auf 1 festgelegt werden), aber nicht als AutoUpdate-Steuerelement (z. B. muss das Bit D3 auf 0 festgelegt werden).

Die Anfragen GET_RES, GET_MIN, GET_MAX müssen den Definitionen in Abschnitt 2.2.2.1 entsprechen, aber dwValueFormat muss auf 1 festgelegt sein.

GET_MAX-Anforderung: Dieses Steuerelement muss die Unterstützung für die Bits D0, D1 und D2 in bmControlFlags bekannt geben.

GET_DEF-Anforderung: Die Vorgabe für bmControlFlags ist D0 auf 1 und dwValueFormat und dwValue auf 0 festgelegt.

Für GET_CUR/SET_CUR-Anfragen gelten die folgenden Einschränkungen für das Feld bmControlFlags:

• Von den Bits D0, D1 und D2 muss mindestens ein Bit festgelegt sein.
• D1 ist mit D0 und D2 nicht kompatibel.

2.2.2.6 Face Authentication Steuerelement

Dieses Steuerelement bietet der Host-Software die Möglichkeit, festzulegen, ob die Kamera Streaming-Modi unterstützt, die für die Gesichtsauthentifizierung verwendet werden. Die Unterstützung dieses Steuerelements setzt voraus, dass die Kamera in der Lage ist, eine Gesichtsauthentifizierung durchzuführen. Andernfalls darf dieses Steuerelement nicht unterstützt werden.

Dieses Steuerelement gilt nur für Kameras, die Infrarotdaten (IR) erzeugen können, und nur für die angegebenen Streaming-Schnittstellen (die eine Untermenge aller Video-Streaming-Schnittstellen sind, die mit der Videosteuerungsschnittstelle verbunden sind).

Bei GET_RES- und GET_MIN-Anfragen wird das Feld bNumEntries auf 0 festgelegt und enthält daher keine zusätzlichen Felder.

Bei einer GET_MAX-Anfrage zeigt ein auf 1 festgelegtes Bit im Feld bmControlFlags an, dass der entsprechende Modus für diese Streaming-Schnittstelle unterstützt wird. Die Ausgabe einer GET_MAX-Anfrage listet und nur die Streaming-Schnittstellen auf, die entweder D1 oder D2 unterstützen (wenn eine Streaming-Schnittstelle also entweder D1 oder D2 unterstützt, wird sie aufgelistet, andernfalls nicht). Außerdem darf für keine Streaming-Schnittstelle angegeben werden, dass sie sowohl D1 als auch D2 kann. Wenn eine Streaming-Schnittstelle auch für den allgemeinen Gebrauch bestimmt ist (z. B. außerhalb des Zwecks der Gesichtsauthentifizierung), muss D0 für diese Streaming-Schnittstelle auf 1 festgelegt werden (zusätzlich zu D1/D2).

Bei GET_DEF / GET_CUR / SET_CUR-Anfragen zeigt ein auf 1 festgelegtes Bit im Feld bmControlFlags an, dass der entsprechende Modus für diese Streaming-Schnittstelle gewählt wurde. In diesen Anfragen muss ein und nur ein Bit (unter D0, D1 & D2) für eine bestimmte Streaming-Schnittstelle festgelegt werden. Wenn bei der Anfrage GET_DEF, die die Standardauswahl zurückgibt (die implementierungsspezifisch ist), eine Streaming-Schnittstelle auch für die allgemeine Verwendung vorgesehen ist (z. B. außerhalb der Gesichtsauthentifizierung), dann wird D0 für diese Streaming-Schnittstelle standardmäßig auf 1 festgelegt; andernfalls wird entweder D1 oder D2 (aber nicht beide) standardmäßig auf 1 festgelegt. Eine GET_DEF/GET_CUR-Anfrage enthält Informationen über alle in der GET_MAX-Anfrage aufgeführten Streaming-Schnittstellen. Eine SET_CUR-Anfrage kann jedoch nur eine Untermenge der in der GET_MAX-Anfrage aufgeführten Streaming-Schnittstellen enthalten.

Beispiel:

Nehmen wir an, dass eine Kamera über vier Video-Streaming-Schnittstellen mit den Nummern 0x03, 0x05, 0x08 und 0x0b verfügt, wobei die Video-Streaming-Schnittstelle 0x05 RGB-Daten produziert und die übrigen drei Video-Streaming-Schnittstellen IR-Daten produzieren. Unter den Streaming-Schnittstellen, die IR-Daten produzieren, nehmen wir an, dass die Streaming-Schnittstellen 0x03 und 0x0b beide D1 können, aber die Streaming-Schnittstelle 0x03 kann auch D0. In diesem Beispiel ist das Steuerelement für die Gesichtsauthentifizierung nur auf die Streaming-Schnittstellen mit den Nummern 0x03 und 0x0b anwendbar, und daher erscheinen nur diese Schnittstellen in den Anfragen.

Die Ausgabe für die GET_MAX-Anfrage lautet wie folgt

Die Ausgabe für die Anfrage GET_DEF lautet wie folgt:

Eine SET_CUR-Anfrage, um die Einstellung der Streaming-Schnittstelle 0x03 auf D1 zu ändern, würde wie folgt aussehen:

Die Ausgabe für eine GET_CUR-Anfrage nach der obigen SET_CUR-Anfrage lautet wie folgt:

2.2.2.7 Camera Extrinsics Steuerelement

Dieses Steuerelement bietet der Host-Software die Möglichkeit, die Kamera-Extrinsik-Daten für Endpunkte auf Video-Streaming-Schnittstellen abzurufen, die mit der Video-Steuerschnittstelle verbunden sind. Die so für jeden Endpunkt abgerufenen Daten erscheinen als Attribut MFStreamExtension_CameraExtrinsics im Attributespeicher für den entsprechenden Stream (abgerufen über den Aufruf IMFDeviceTransform::GetOutputStreamAttributes).

Die Anfragen GET_RES, GET_MIN, GET_MAX, GET_CUR liefern das Feld bNumEntries, das auf 0 festgelegt ist und daher keine zusätzlichen Felder enthält.

Die Anfrage GET_DEF listet alle Endpunkte auf, für die die extrinsischen Informationen verfügbar sind.

Beispiel:

Nehmen wir an, dass eine Kamera über drei Video-Streaming-Schnittstellen mit den Nummern 0x03, 0x05 und 0x08 verfügt, wobei die Video-Streaming-Schnittstelle 0x05 neben der von allen Video-Streaming-Schnittstellen unterstützten Videoaufnahme auch die Aufnahme von Standbildern mit Methode 2 unterstützt. Unter diesen Streaming-Schnittstellen nehmen wir an, dass die Streaming-Schnittstellen 0x05 und 0x08 über Extrinsik-Informationen verfügen, während die Streaming-Schnittstelle 0x03 keine Extrinsik-Informationen zur Verfügung hat.

In diesem Beispiel sieht die Ausgabe für die Anfrage GET_DEF wie folgt aus:

2.2.2.8 Camera Intrinsics Steuerelement

Dieses Steuerelement bietet der Host-Software die Möglichkeit, die Kamera-Intrinsik-Daten für Endpunkte auf Video-Streaming-Schnittstellen abzurufen, die mit der Video-Steuerschnittstelle verbunden sind. Die so für jeden Endpunkt abgerufenen Daten werden als Attribut MFStreamExtension_PinholeCameraIntrinsics im Attributespeicher für den entsprechenden Stream angezeigt (abgerufen mit dem Aufruf IMFDeviceTransform::GetOutputStreamAttributes).

Die Anfragen GET_RES, GET_MIN, GET_MAX, GET_CUR liefern das Feld bNumEntries, das auf 0 festgelegt ist und daher keine zusätzlichen Felder enthält.

Die Anfrage GET_DEF listet alle Endpunkte auf, für die die Intrinsics-Informationen verfügbar sind.

Beispiel:

Nehmen wir an, dass eine Kamera über drei Video-Streaming-Schnittstellen mit den Nummern 0x03, 0x05 und 0x08 verfügt, wobei die Video-Streaming-Schnittstelle 0x05 neben der von allen Video-Streaming-Schnittstellen unterstützten Videoaufnahme auch die Aufnahme von Standbildern mit Methode 2 unterstützt. Unter diesen Streaming-Schnittstellen nehmen wir an, dass die Streaming-Schnittstellen 0x05 und 0x08 über Intrinsics-Informationen verfügen, während für die Streaming-Schnittstelle 0x03 keine Intrinsics-Informationen verfügbar sind.

In diesem Beispiel sieht die Ausgabe für die Anfrage GET_DEF wie folgt aus:

2.2.2.9 Metadata Steuerelement

Dieses Steuerelement bietet der Host-Software die Möglichkeit, die von der Kamera erzeugten Metadaten abzufragen und zu steuern. Es handelt sich um ein globales Steuerelement, das sich auf alle Endpunkte auf allen Video-Streaming-Schnittstellen auswirkt, die mit der Video-Steuerelement-Schnittstelle verbunden sind.

Dieses Steuerelement wird vom Kameratreiber KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA zugeordnet.

Wenn die SET_CUR-Anfrage von der Firmware unterstützt wird, gilt Folgendes:

• GET_MIN-, GET_DEF-Anfragen liefern das Feld dwValue, das auf 0 festgelegt ist.

• Die Anfrage GET_RES liefert für das Feld dwValue den gleichen Wert wie die Anfrage GET_MAX.

• Wenn eine SET_CUR-Anfrage empfangen wird, bei der dwValue auf 0 festgelegt ist, gibt die Kamera keine Metadaten aus. Wenn eine SET_CUR-Anfrage empfangen wird, bei der dwValue auf denselben Wert festgelegt ist wie bei der GET_MAX-Anfrage, kann die Kamera Metadaten produzieren, wobei die Größe dieser Metadaten dwValue für jedes Bild nicht überschreiten darf.

Wenn die Anfrage SET_CUR nicht von der Firmware unterstützt wird, gilt Folgendes:

• GET_MIN- und GET_DEF-Anfragen liefern für das Feld dwValue den gleichen Wert wie die GET_MAX-Anfrage.

• Die Anfrage GET_RES liefert das Feld dwValue, das auf 0 festgelegt ist.

• Die Kamera kann Metadaten erzeugen, und die Gesamtgröße dieser Metadaten darf den dwValue – wie von der GET_MAX-Anfrage mitgeteilt – mal 1024 Bytes abzüglich der Größe eines UsbVideoHeader-Metadaten-Payloads für ein beliebiges Bild nicht überschreiten.

• Ein UsbVideoHeader Metadaten-Payload ist die Größe von sizeof(KSCAMERA_METADATA_ITEMHEADER) + sizeof(KSTREAM_UVC_METADATA) oder 24 Bytes.

Die erzeugten Metadaten müssen den in Abschnitt 2.2.3 beschriebenen Metadaten im Microsoft-Standardformat entsprechen.

2.2.2.10 IR Torch Steuerelement

Dieses Steuerelement bietet ein flexibles Mittel für die IR-LED-Hardware, um zu melden, inwieweit sie gesteuert werden kann, und bietet die Möglichkeit, sie zu steuern. Es handelt sich um ein globales Steuerelement, das sich auf alle Endpunkte aller mit der Videosteuerungsschnittstelle verbundenen Video-Streaming-Schnittstellen auswirkt, indem es die Leistung einer an die Kamera angeschlossenen IR-Lampe einstellt.

Dieses Steuerelement wird vom Kameratreiber KSPROPERTY_CAMERACONTROL_EXTENDED_IRTORCHMODE zugeordnet.

Es gilt Folgendes:

• Die Anfrage GET_LEN muss einen Wert von 8 liefern.

• Die Anfrage GET_INFO liefert den Wert 3. Dieser Wert weist auf ein synchrones Steuerelement hin, das GET_CUR und SET_CUR unterstützt.

• Die Anfrage GET_MIN liefert das Feld dwMode, das auf 0 gesetzt ist, und dwValue, das auf einen Wert festgelegt ist, der die Mindestleistung angibt. Eine Leistungsstufe von 0 kann OFF anzeigen, aber die minimale Betriebsleistungsstufe muss nicht 0 sein.

• In der Anfrage GET_RES wird das Feld dwMode auf 0 und dwValue auf eine Zahl festgelegt, die kleiner oder gleich GET_MAX(dwValue) - GET_MIN(dwValue) ist, und so, dass GET_MAX(dwValue) - GET_MIN(dwValue) gerade durch diesen Wert teilbar ist. dwValue darf nicht Null (0) sein.

• In der Anfrage GET_MAX wird das Feld dwMode mit den Bits D[0-2] festgelegt, um die Funktionalitäten dieses Steuerelements zu identifizieren. Bei dwMode muss das Bit D0 gesetzt sein, was anzeigt, dass OFF unterstützt wird, und es muss mindestens ein weiteres Bit gesetzt sein, das einen aktiven Status unterstützt. dwValue muss auf einen Wert festgelegt sein, der normale Leistung anzeigt.

• Die Anfrage GET_DEF liefert das Feld dwMode, das auf den Standardmodus festgelegt ist, in dem sich das System befinden sollte, bevor das Streaming beginnt. dwMode muss auf 2 (ON) oder 4 (ALTERNATING) festgelegt sein. dwValue sollte auf die Leistungsstufe festgelegt werden, die normalerweise für das FaceAuth-Steuerelement verwendet wird. dwValue wird vom Hersteller definiert.

• Die Anfrage GET_CUR meldet, dass das Feld dwMode auf den aktuellen Betriebsmodus und dwValue auf die aktuelle Beleuchtungsstärke festgelegt wurde.

• Wenn eine SET_CUR-Anfrage empfangen wird, legt die IR-Taschenlampe die Beleuchtungsstärke auf eine anteilige Intensität unter Verwendung des angeforderten Betriebsmodus fest.

Die IR-Taschenlampe muss das Attribut MF_CAPTURE_METADATA_FRAME_ILLUMINATION für jedes Bild ausgeben. Sie kann dies über eine Geräte-MFT oder durch Aufnahme eines MetadataId_FrameIllumination-Attributs in den Payload der Metadaten von der Kamera bereitstellen. Siehe Abschnitt 2.2.3.4.4.

Der einzige Zweck dieser Metadaten besteht darin, anzugeben, ob ein Bild beleuchtet ist oder nicht. Dies sind dieselben Metadaten, die von der KSPROPERTY_CAMERACONTROL_EXTENDED_FACEAUTH_MODE DDI und der MSXU_FACE_AUTHENTICATION_CONTROL, die in Abschnitt 2.2.2.6 definiert sind, benötigt werden.

2.2.2.11 Digital Window Steuerelement

Das Digitalfenster legt das Sichtfeld und den Zoom der Kamera fest, während die Kamera streamt. Dieses Steuerelement ist ein möglicher Ersatz für Schwenken, Neigen und Zoomen. Dieses Steuerelement gilt nur, wenn die Kamera aktiv streamt.

Dieses Steuerelement steht für alle Kameratypen zur Verfügung und ist unabhängig vom Medientyp, der gestreamt wird.

Dieses Steuerelement bietet der Host-Software die Möglichkeit, das mit einer Kamera verbundene Digitalfenster abzufragen und zu steuern.

Es handelt sich um ein globales Steuerelement, das sich auf alle Endpunkte auf allen Video-Streaming-Schnittstellen auswirkt, die mit der Video-Steuerelement-Schnittstelle verbunden sind. Sie passt die Quelle der vom ISP verwendeten Pixeldaten an. Dazu gehören Method 2 und Method 3 Still Capture Pins.

Dieses Steuerelement wird vom Inbox-Kameratreiber KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW zugeordnet.

Es gilt Folgendes:

• Die Anfrage GET_LEN liefert einen Wert von 16.

• Die Anfrage GET_INFO liefert den Wert 3. Dieser Wert weist auf ein synchrones Steuerelement hin, das GET_CUR und SET_CUR unterstützt.

• Die Anfrage GET_MIN liefert das Feld dwMode auf 0 festgelegt, OriginX und OriginY auf 0,0 festgelegt und WindowSize auf 1,0 festgelegt. Diese Anfrage wird derzeit nicht verwendet.

• Die Anfrage GET_RES liefert das Feld dwMode auf 0 festgelegt, OriginX und OriginY auf 0,0 festgelegt und WindowSize auf 1,0 festgelegt. Diese Anfrage wird derzeit nicht verwendet.

• In der GET_MAX-Anfrage wird das Feld dwMode mit dem Bit D0 festgelegt, um die Funktionalitäten dieses Steuerelements zu identifizieren. Ein Wert von 0 bedeutet, dass nur der manuelle Modus unterstützt wird. Ein Wert von 1 zeigt an, dass der Auto-Face-Framing-Modus unterstützt wird. Die übrigen Felder sind unbenutzt, wir empfehlen jedoch, OriginX und OriginY auf 0,0 und WindowSize auf 1,0 festzulegen.

• Bei der Anfrage GET_DEF wird das Feld dwMode auf 0, OriginX und OriginY auf 0,0 und WindowSize auf 1,0 festgelegt. Dies ist immer das Standardfenster.

• Bei der Anfrage GET_CUR wird das Feld dwMode auf den aktuellen Betriebsmodus festgelegt, und OriginX, OriginY und WindowSize beschreiben das aktuelle Digitalfenster.

• Wenn eine SET_CUR-Anfrage empfangen wird, passt die Kamera ihr Sichtfeld an den gewählten Betriebsmodus und das Digitalfenster an.

• Wenn der Modus Auto-Face-Framing ausgewählt ist, wählt die Kamera ein Fenster, das das dominante Gesicht in der Szene vollständig umschließt, und die übergebenen OriginX, OriginY und WindowSize werden ignoriert. Wenn kein Gesicht gefunden wird, wird das Standardfenster verwendet.

• Alle Änderungen am Digitalfenster müssen in den Payload der Metadaten der einzelnen Samples übernommen werden.

• Änderungen am Digitalfenster sind möglicherweise nicht sofort wirksam, aber das Steuerelement sollte sofort reagieren. Änderungen am Digitalfenster müssen im Metadaten-Payload des Frames gemeldet werden, sobald sie in Kraft treten.

2.2.2.12 Digital Window Config Steuerelement

Das Digital Window Config Steuerelement legt die Skalierungsgrenzen der Kamera für alle verfügbaren Auflösungen fest. Die Auflösungen sind unabhängig vom Medientyp, sodass zwei Medientypen, die für dieselbe Anzeigeauflösung verfügbar sind, zu einer Funktionalität zusammengefasst werden.

Aufgrund der Größenbeschränkungen eines Endpunkts kann dieses Steuerelement höchstens 1820 eindeutige Auflösungen beschreiben.

Dieses Steuerelement muss immer verfügbar sein, um die Funktionalitäten des Digitalfenster-Steuerelements zu melden, wenn dieses Steuerelement ebenfalls vorhanden ist.

Dieses Steuerelement wird vom Inbox-Kameratreiber KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW_CONFIGCAPS zugeordnet.

Es gilt Folgendes:

• Die Anfrage GET_LEN liefert die gesamte Größe des Payloads. Die Größe der Payloads muss ein Vielfaches von 36 sein, da jede Auflösungsdefinition 36 Bytes lang ist.

• Die GET_INFO-Anfrage liefert eine 1. Dieser Wert weist auf ein synchrones Steuerelement hin, das nur GET_CUR unterstützt.

• Die Anfrage GET_CUR muss ein Array mit Funktionalitäten liefern. Die Felder der Funktionalitäten-Struktur sind oben definiert.

• Die Anfragen GET_MIN, GET_MAX, GET_RES und GET_DEF werden nicht verwendet, sollten aber die gleichen Werte wie GET_CUR zurückgeben.

• SET_CUR-Anfragen werden nicht unterstützt.

2.2.2.13 Video HDR Steuerelement

Dieses Steuerelement bietet der Host-Software die Möglichkeit, anzugeben, ob die Kamera Video HDR unterstützt. Die Unterstützung dieses Steuerelements impliziert, dass die Kamera in der Lage ist, Video HDR bestmöglich durchzuführen. Wenn die Kamera Video HDR nicht unterstützt, darf sie dieses Steuerelement nicht implementieren.

Dieses Steuerelement wird vom Kameratreiber KSPROPERTY_CAMERACONTROL_EXTENDED_VIDEOHDR zugeordnet.

Es gilt Folgendes:

• Die Anfrage GET_LEN liefert die gesamte Größe des Payloads (z. B. 4 Byte).

• Die Anfrage GET_INFO liefert einen Wert von 3. Dieser Wert weist auf ein synchrones Steuerelement hin, das GET_CUR, SET_CUR unterstützt.

• Die Anfrage GET_CUR liefert das Feld dwMode, das auf den aktuellen Betriebsmodus festgelegt ist.

• Bei GET_DEF muss dwMode auf OFF (0) festgelegt sein.

• In der Anfrage GET_MAX wird die Unterstützung der verfügbaren Modi für den Betrieb angekündigt: [1 (ON/OFF), 3 (ON/OFF/Auto)]. Die Unterstützung von ON (1) ist für dieses Steuerelement obligatorisch.

• GET_MIN- und GET_RES-Anfragen müssen 0 liefern.

• Die Anfrage SET_CUR sollte den Modus entweder auf OFF (0), ON (1) oder AUTO (2) festlegen.

2.2.2.14 Framerate Throttle Steuerelement

Dieses Steuerelement bietet der Host-Software die Möglichkeit, festzulegen, ob die Kamera die Bildratendrosselung unterstützt.

Dieses Steuerelement gilt nur, wenn die Kamera aktiv streamt. Aktives Streaming bedeutet, dass sich ein Vorschau- oder Aufzeichnungs-Pin in KSSTATE_RUN befinden muss, also bereit und in der Lage sein muss, Bilder zu liefern. Wenn Sie festlegen, dass ein Stream nicht aktiv ist, sollte dieses Steuerelement STATUS_INVALID_DEVICE_STATE zurückgeben.

Auch wenn es sich um ein Steuerelement für den Filter-Bereich handelt, sollte sich das Steuerelement für die Bildrate nicht auf den Foto-Pin oder Nicht-RGB-Streams wie IR/Tiefe auswirken. Wenn die Drosselung der Bildrate in Kraft ist, sollte auch die Sample-Dauer entsprechend angepasst werden.

Dieses Steuerelement wird vom Kameratreiber KSPROPERTY_CAMERACONTROL_EXTENDED_FRAMERATE_THROTTLE zugeordnet.

Steuerelement-Selektor	MSXU_CONTROL_FRAMERATE_THROTTLE
Obligatorische Anfragen	GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR, SET_CUR
Optionale Anfragen
wLength	20

Abweichung	Feld	Size	Wert	Beschreibung
0	dwMode	4	Flags	D0: 0 (OFF) oder 1 (ON) D1-D31: reserviert und auf 0 festgelegt
4	scaleFactorPercentage	4	Anzahl	Dieser Wert sollte innerhalb des Bereichs von Min und Max liegen und auf ein Vielfaches von Step festgelegt werden. Beispiel: Wenn Min = 5, Max = 100 und Step = 5 und wenn eine Anwendung beschlossen hat, die Bildrate auf 80 % des ursprünglichen Wertes zu reduzieren, dann sollte dieser Mitgliedswert auf 80 festgelegt werden. Durch das Festlegen dieses Wertes kann eine App sicherstellen, dass die neue Bildrate niemals den ursprünglichen Wert übersteigt und auch nicht auf Null geht, sondern die ursprüngliche Bildrate möglich ist.
8	min	4	Anzahl	Min sollte mindestens einer Schrittgröße entsprechen oder ein Vielfaches der Schrittgröße sein (Beispiel: Step1, Step2 usw.). Der Wert Min kann nicht auf 0 festgelegt werden.
12	max	4	Anzahl	Max muss auf 100 festgelegt werden, was bedeutet, dass sich die Bildrate nicht ändert.
16	step	4	Anzahl	Step sollte ein absoluter Faktor von Max sein, zum Beispiel {Max % Step == 0}. Example: 1, 2, 4, 5 etc.

Es gilt Folgendes:

• Die Anfrage GET_LEN liefert die gesamte Größe des Payloads (z. B. 20 Bytes). 

• Die Anfrage GET_INFO liefert einen Wert von 3. Dieser Wert weist auf ein synchrones Steuerelement hin, das GET_CUR, SET_CUR unterstützt. 

• Die Anfrage GET_CUR liefert das Feld dwMode, das auf den aktuellen Betriebsmodus festgelegt ist, und scaleFactorPercentage, das auf den aktuellen scaleFactor-Wert festgelegt ist. Min, Max und Step sollten die Werte wie in der obigen Tabelle beschrieben liefern.

• Bei GET_DEF ist dwMode auf OFF(0), scaleFactorPercentage=100, Min auf den Standard-Minimalwert, max auf 100 und step auf den Standard-Schrittwert festgelegt. Die Werte für min und step sollten vom Hersteller festgelegt werden, sollten aber den in der obigen Tabelle genannten Richtlinien entsprechen.

• Die Anfrage GET_ MAX muss die Unterstützung für die verfügbaren Betriebsmodi ankündigen und den Wert 1 [ ON | OFF ] liefern. Die Unterstützung für ON und OFF ist für dieses Steuerelement obligatorisch. Min, Max, Step und scaleFactorPercentage können auf die Standardwerte festgelegt werden.

• GET_MIN- und GET_RES-Anfragen müssen 0 liefern. 

• Die Anfrage SET_CUR sollte den Modus entweder auf OFF(0), ON(1) festlegen. Wenn dwMode auf ON festgelegt ist, dann wird scaleFactorPercentage wirksam. Sowohl bei OFF als auch bei ON muss scaleFactorPercentage wie in der obigen Tabelle beschrieben gültig sein.

2.2.2.15 Field of View 2 Config Steuerelement

Das Steuerelement Field of View 2 Config gibt die unterstützten Werte für den diagonalen Bildausschnitt in Grad als Array mit Werten an. Alle unterstützten Werte müssen im Bereich der theoretischen Minimal- und Maximalwerte liegen, 1 Grad - 360 Grad.

Wenn das Gerät kontinuierliche Bildausschnitt-Werte unterstützen möchte, muss es alle unterstützten Werte melden. Wenn das Gerät beispielsweise einen diagonalen Bildausschnitt von 85 Grad - 60 Grad mit einer Schrittweite von 1 unterstützen möchte, muss dieses Steuerelement eine Reihe von Werten melden [85, 84, 83, 82, ..., 62, 61, 60].

Dieses Steuerelement muss verfügbar sein, um die Funktionalitäten zu liefern, wenn das Field of View 2 Steuerelement vorhanden ist.

Dies ist ein synchrones Steuerelement für die Filterebene.

Dieses Steuerelement wird vom Kameratreiber KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2_CONFIGCAPS zugeordnet.

Steuerelement-Selektor	MSXU_CONTROL_FIELDOFVIEW2_CONFIG
Obligatorische Anfragen	GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR
Optionale Anfragen
wLength	4 Bytes + Anzahl mal 4 Bytes, wobei Anzahl die Anzahl der eindeutigen Sichtfeldwerte ist.

Abweichung	Feld	Size	Wert	Beschreibung
0	dwDefaultFieldOfView	4	Anzahl	Der Standardwert für das diagonale Sichtfeld muss einer der Werte sein, die im Array FieldOfViewValues angegeben sind.
4	FieldOfViewValues[0]	4	Anzahl	Erster Sichtfeld-Wert, dies muss der breiteste Sichtfeld-Wert sein.
…	…	…	…	…
4 + 4*(Count-1)	FieldOfViewValues [Anzahl -1]	4	Anzahl	Letzter Sichtfeld-Wert, dies muss der schmalste Sichtfeld-Wert sein.

Es gilt Folgendes:

• Die Anfrage GET_LEN liefert die gesamte Größe des Payloads.

• Die GET_INFO-Anfrage liefert eine 1. Dieser Wert weist auf ein synchrones Steuerelement hin, das nur GET_CUR unterstützt.

• Die Anfrage GET_CUR liefert Daten, die den Sichtfeld-Standardwert und das Array der unterstützten Sichtfeldwerte in absteigender Reihenfolge enthalten. Die Felder der Struktur sind oben definiert.

• Die Anfrage GET_DEF muss dasselbe liefern wie GET_CUR.

• Die Anfragen GET_MIN, GET_MAX und GET_RES sind unbenutzt, sollten aber die gleichen Werte wie GET_CUR zurückgeben.

• SET_CUR-Anfragen werden nicht unterstützt.

Die Sichtfeld-Werte müssen in absteigender Reihenfolge angegeben werden, d. h. das breiteste Sichtfeld steht an erster und das schmalste an letzter Stelle.

2.2.2.16 Field of View 2 Steuerelement

Dieses Steuerelement legt das Basis-Sichtfeld fest, das die Kamera beim Streaming verwendet. Dieses Steuerelement kann vor oder während des Streamings angewendet werden.

Dieses Steuerelement steht für alle Kameratypen zur Verfügung und ist unabhängig vom Medientyp, der gestreamt wird.

Dieses Steuerelement bietet der Host-Software die Möglichkeit, das mit einer Kamera zusammenhängende Sichtfeld abzufragen und zu steuern.

Es handelt sich um ein globales Steuerelement, das sich auf alle Endpunkte auf allen Video-Streaming-Schnittstellen auswirkt, die mit der Video-Steuerelement-Schnittstelle verbunden sind. Es passt die Quelle der vom ISP (Image Signal Processor) verwendeten Pixeldaten (oder Sensordaten) an. Dazu gehören Method 2 und Method 3 Still Capture Pins.

Dies ist ein synchrones Steuerelement für die Filterebene.

Dieses Steuerelement wird vom Kameratreiber KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2 zugeordnet.

Steuerelement-Selektor	MSXU_CONTROL_FIELDOFVIEW2
Obligatorische Anfragen	GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR, SET_CUR
Optionale Anfragen
wLength	4

Abweichung	Feld	Size	Wert	Beschreibung
0	dwValue	4	Anzahl	Wert für das diagonale Sichtfeld in Grad.

Es gilt Folgendes:

• Die Anfrage GET_LEN liefert einen Wert von 4.

• Die Anfrage GET_INFO liefert einen Wert von 3. Dieser Wert weist auf ein synchrones Steuerelement hin, das GET_CUR und SET_CUR unterstützt.

• Die Anfrage GET_MIN liefert das Feld dwValue, das auf den kleinsten unterstützten Wert für das Sichtfeld festgelegt ist.

• Die Anfrage GET_RES liefert das Feld dwValue auf 0 festgelegt. Diese Anfrage wird derzeit nicht verwendet.

• Die Anfrage GET_MAX liefert das Feld dwValue, das auf den maximal unterstützten Wert des Sichtfeldes festgelegt ist.

• Die Anfrage GET_DEF liefert das Feld dwValue, das auf den Standardwert für das Sichtfeld festgelegt ist.

• Die Anfrage GET_CUR liefert das Feld dwValue, das auf den aktuellen Wert für das Sichtfeld festgelegt ist.

• Wenn eine SET_CUR-Anfrage empfangen wird, legt die Kamera ihr Sichtfeld so fest, dass es dem angegebenen dwValue-Wert entspricht.

• Wenn die Kamera CT_ZOOM_RELATIVE_CONTROL und/oder CT_ZOOM_ABSOLUTE_CONTROL implementiert, werden diese Steuerelemente auf ihre Standardwerte zurückgesetzt, wenn MSXU_CONTROL_FIELDOFVIEW2 SET_CUR aufgerufen wird.

Wenn die Kamera MSXU_CONTROL_DIGITALWINDOW implementiert, muss sie die Änderung des Fensters wiedergeben, wenn ein neuer Wert für das Sichtfeld festgelegt wird. Umgekehrt muss das Sichtfeld die über Digitalfenster vorgenommenen Änderungen widerspiegeln. Siehe KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2 für Details.

2.2.3 Metadaten

Das Design für Frame-Metadaten im Standardformat baut auf dem Design der angepassten UVC-Metadaten von Windows 10 auf. In Windows 10 werden angepasste Metadaten für UVC unterstützt, indem eine angepasste INF für den Kameratreiber verwendet wird (Hinweis: Der Kameratreiber kann auf der Windows USBVIDEO.SYS basieren, aber eine angepasste INF ist für die gegebene Hardware erforderlich, damit die Metadaten übermittelt werden können). Wenn ein MetadataBufferSizeInKB<PinIndex> Registrierungseintrag vorhanden und ungleich Null ist, werden angepasste Metadaten für diesen Pin unterstützt und der Wert gibt die für die Metadaten verwendete Puffergröße an. Das Feld <PinIndex> zeigt einen 0-basierten Index des Video-Pin-Index an.

In Windows 10, Version 1703, kann ein Kameratreiber die Unterstützung für Microsoft-Metadaten im Standardformat signalisieren, indem er den folgenden AddReg-Eintrag enthält:

StandardFormatMetadata<PinIndex>: REG_DWORD: 0x0 (NotSupported) bis 0x1 (Supported)

Dieser Registrierungsschlüssel wird von DevProxy gelesen und teilt dem UVC-Treiber mit, dass die Metadaten im Standardformat vorliegen, indem das Flag KSSTREAM_METADATA_INFO_FLAG_STANDARDFORMAT im Feld Flags der Struktur KSSTREAM_METADATA_INFO festgelegt wird.

2.2.3.1 Microsoft-Metadaten im Standardformat

Die Microsoft Standardformat-Metadaten sind eine oder mehrere Instanzen der folgenden Struktur:

typedef struct tagKSCAMERA_METADATA_ITEMHEADER {
    ULONG MetadataId;
    ULONG Size; // Size of this header + metadata payload following
} KSCAMERA_METADATA_ITEMHEADER, *PKSCAMERA_METADATA_ITEMHEADER;

Das Feld MetadataId wird durch einen Bezeichner aus der folgenden Enum-Definition gefüllt, die wohldefinierte Bezeichner und angepasste Bezeichner enthält (Bezeichner >= 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;

Das Feld Size wird auf sizeof(KSCAMERA_METADATA_ITEMHEADER) + sizeof(Metadata Payload) festgelegt.

2.2.3.2 Von der Firmware generierte Metadaten im Standardformat aus USB-Video-Frame-Paketen

Bei einer Übertragung über UVC für bildbasierte Videos wird das Videobild in eine Reihe von Paketen aufgeteilt, denen jeweils ein UVC-Payload-Header vorausgeht. Jeder UVC-Payload-Header wird durch die USB Video Class Driver Frame Based Payload Spezifikation definiert:

Payload-Header

Im Folgenden finden Sie eine Beschreibung des Payload-Header-Formats für Frame-Based-Formate.

HLE ( Header length) Feld

Das Header-Längenfeld gibt die Länge des Headers in Bytes an.

Bitfeld-Header-Feld

FID: Frame Identifier

• Dieses Bit schaltet an jeder Frame-Startgrenze um und bleibt für den Rest des Frames konstant.

EOF: End of Frame

• Dieses Bit zeigt das Ende eines Videobildes an und wird im letzten zu einem Bild gehörenden Videosample festgelegt. Die Verwendung dieses Bits ist eine Optimierung, um die Latenzzeit bei der Übertragung eines Bildes zu verringern, und ist optional.

PTS: Presentation Time Stamp

• Dieses Bit zeigt, wenn es festgelegt ist, das Vorhandensein eines PTS-Feldes an.

SCR: Source Clock Reference

• Dieses Bit zeigt, wenn es festgelegt ist, das Vorhandensein eines SCR-Feldes an.

RES: Reserved

• Legen Sie auf 0 fest.

STI: Still Image

• Dieses Bit kennzeichnet, wenn es festgelegt ist, ein Video-Sample als zu einem Standbild gehörig.

ERR: Error Bit

• Dieses Bit zeigt, wenn es festgelegt ist, einen Fehler im Streaming des Geräts an.

EOH: End of Header

• Dieses Bit zeigt, wenn es festgelegt ist, das Ende der BFH-Felder an.

PTS: Presentation Time Stamp, Größe: 4 Bytes, Wert: Zahl

• Das PTS-Feld ist vorhanden, wenn das PTS-Bit im BFH[0]-Feld festgelegt ist. Siehe Abschnitt 2.4.3.3 Video and Still Image Payload Headers in der USB Device Class Definition for Video Devices-Spezifikation.

SCR: Source Clock Reference, Größe: 6 Bytes, Wert: Zahl

• Das Feld SCR ist vorhanden, wenn das SCR-Bit im Feld BFH[0] festgelegt ist. Siehe Abschnitt 2.4.3.3 Video and Still Image Payload Headers in der USB Device Class Definition for Video Devices-Spezifikation.

Das HLE-Feld im bestehenden UVC-Treiber ist entweder auf 2 Bytes (kein PTS/SCR vorhanden) oder auf bis zu 12 Bytes (PTS/SCR vorhanden) festgelegt. Da es sich bei dem HLE-Feld jedoch um ein bytegroßes Feld handelt, können potenziell bis zu 255 Bytes an Header-Daten angegeben werden. Wenn beide PTS/SCR vorhanden sind und das HLE-Feld größer als 12 Bytes ist, werden alle zusätzlichen Daten, die den ersten 12 Bytes des Payload-Headers folgen, als Standard-Metadaten speziell für das Videobild übernommen, wenn der INF-Eintrag StandardFormatMetadata<PinIndex> festgelegt wird.

Die (von der Firmware generierten) Standard-Metadaten für ein Bild werden durch Verkettung der partiellen Blobs in den Paketen für dieses Bild abgerufen.

2.2.3.3 Metadatenpuffer für die Benutzermoduskomponente

Der Metadatenpuffer, der der Benutzermodus-Komponente zur Verfügung gestellt wird, enthält ein Metadatenelement für die UVC-Zeitstempel (vom UVC-Treiber generiert), gefolgt von Firmware-generierten Metadatenelementen, die wie folgt angeordnet sind:

2.2.3.4 Metadatenformat für Standard-Metadatenbezeichner

Die Firmware kann wählen, ob sie Metadaten zu einem Bezeichner generiert oder nicht. Wenn die Firmware sich dafür entscheidet, Metadaten zu einem Bezeichner zu generieren, müssen die Metadaten dieses Bezeichners in allen von der Firmware ausgegebenen Frames vorhanden sein.

2.2.3.4.1 MetadataId_CaptureStats

Das Format der Metadaten für diesen Bezeichner ist durch die folgende Struktur definiert:

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;

Das Feld Flags zeigt an, welche der späteren Felder in der Struktur gefüllt sind und gültige Daten enthalten. Das Feld Flags darf sich nicht von Frame zu Frame ändern. Derzeit sind die folgenden Flags definiert:

#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

Das Feld Reserved ist für die Zukunft reserviert und muss auf 0 festgelegt werden.

Das Feld ExposureTime enthält die Belichtungszeit in 100 ns, die auf den Sensor angewendet wurde, als das Bild aufgenommen wurde. Dies wird als Attribut MF_CAPTURE_METADATA_EXPOSURE_TIME auf dem entsprechenden MF-Sample angezeigt.

Das Feld ExposureCompensationFlags enthält die Stufe der Belichtungskompensation (genau eines der KSCAMERA_EXTENDEDPROP_EVCOMP_XXX Step-Flags muss festgelegt sein), die zur Übermittlung des Wertes der Belichtungskompensation verwendet wird. Das Feld ExposureCompensationValue enthält den Wert der Belichtungskompensation in Einheiten der Stufe, die bei der Aufnahme des Bildes auf den Sensor angewendet wurde. Diese Werte werden als Attribut MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION auf dem entsprechenden MF-Sample angezeigt.

Das Feld IsoSpeed enthält den Wert der ISO-Geschwindigkeit, die bei der Aufnahme auf den Sensor angewendet wurde. Dieser Wert ist einheitenlos. Dies wird als Attribut MF_CAPTURE_METADATA_ISO_SPEED im entsprechenden MF-Sample angezeigt.

Das Feld FocusState enthält den aktuellen Fokus-Status, der einen der in enum KSCAMERA_EXTENDEDPROP_FOCUSSTATE definierten Werte annehmen kann. Dies wird als Attribut MF_CAPTURE_METADATA_FOCUSSTATE im entsprechenden MF-Sample angezeigt.

Das Feld LensPosition enthält die logische Objektivposition bei der Aufnahme des Bildes, die ohne Einheit ist. Dies ist derselbe Wert, der über KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS in einem GET-Aufruf abgefragt werden kann. Er wird als Attribut MF_CAPTURE_METADATA_LENS_POSITION im entsprechenden MF-Sample angezeigt.

Das Feld WhiteBalance enthält den Weißabgleich, der bei der Aufnahme des Bildes auf den Sensor angewendet wurde, d. h. einen Wert in Kelvin. Dies wird als Attribut MF_CAPTURE_METADATA_WHITEBALANCE im entsprechenden MF-Sample angezeigt.

Das Feld Flash enthält einen booleschen Wert, wobei 1 bedeutet, dass der Blitz eingeschaltet war, und 0, dass der Blitz ausgeschaltet war, als das Bild aufgenommen wurde. Dies wird als Attribut MF_CAPTURE_METADATA_FLASH im entsprechenden MF-Sample angezeigt.

Das Feld FlashPower enthält die Blitzleistung, die auf das aufgenommene Bild angewendet wurde. Es ist ein Wert im Bereich von [0, 100]. Dieses Feld sollte weggelassen werden, wenn der Treiber keine einstellbare Leistung für den Blitz unterstützt. Dies wird im entsprechenden MF-Sample als Attribut MF_CAPTURE_METADATA_FLASH_POWER angezeigt.

Das Feld ZoomFactor enthält den Zoomwert im Q16-Format, der auf das aufgenommene Bild angewendet wird. Dieser wird im entsprechenden MF-Sample als Attribut MF_CAPTURE_METADATA_ZOOMFACTOR angezeigt.

Das Feld SceneMode enthält den auf das aufgenommene Bild angewendeten Szenenmodus. Es handelt sich dabei um ein 64 Bit KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX-Flag. Dies wird im entsprechenden MF-Sample als Attribut MF_CAPTURE_METADATA_SCENE_MODE angezeigt.

Das Feld SensorFramerate enthält die gemessene Sensor-Ausleserate in Hertz bei der Aufnahme des Bildes, die aus einem Zählerwert in den oberen 32 Bit und einem Nennerwert in den unteren 32 Bit besteht. Dies wird im entsprechenden MF-Sample als Attribut MF_CAPTURE_METADATA_SENSORFRAMERATE angezeigt.

2.2.3.4.2 MetadataId_CameraExtrinsics

Das Metadatenformat für diese Kennung umfasst den Standard KSCAMERA_METADATA_ITEMHEADER, gefolgt von einem Payload in Form eines Byte-Arrays. Der Payload sollte einer MFCameraExtrinsics-Struktur entsprechen, gefolgt von null oder mehr MFCameraExtrinsic_CalibratedTransform-Strukturen. Der Payload muss auf 8 Bytes ausgerichtet sein, und alle ungenutzten Bytes müssen am Ende der Payload stehen und auf 0 festgelegt sein.

2.2.3.4.3 MetadataId_CameraIntrinsics

Das Metadatenformat für diese Kennung umfasst den Standard KSCAMERA_METADATA_ITEMHEADER, gefolgt von einem Payload in Form eines Byte-Arrays. Der Payload sollte sich an einer MFPinholeCameraIntrinsics-Struktur orientieren. Der Payload muss auf 8 Bytes ausgerichtet sein, und alle ungenutzten Bytes müssen am Ende der Payload stehen und auf 0 festgelegt sein.

2.2.3.4.4 MetadataId_FrameIllumination

Das Format der Metadaten für diesen Bezeichner ist durch die folgende Struktur definiert:

typedef struct tagKSCAMERA_METADATA_FRAMEILLUMINATION {
    KSCAMERA_METADATA_ITEMHEADER Header;
    ULONG Flags;
    ULONG Reserved;
} KSCAMERA_METADATA_FRAMEILLUMINATION, *PKSCAMERA_METADATA_FRAMEILLUMINATION;

Das Feld Flags gibt Informationen über das aufgenommene Bild an. Derzeit sind die folgenden Flags definiert:

#define KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON 0x00000001

Wenn ein Bild bei eingeschalteter Beleuchtung aufgenommen wurde, muss das Flag KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON festgelegt werden. Andernfalls darf dieses Flag nicht festgelegt werden.

Das Feld Reserved ist für die zukünftige Verwendung reserviert und wird auf 0 festgelegt.

Beispiel:

Ein Beispiel für eine KSCAMERA_METADATA_FRAMEILLUMINATION-Struktur, die anzeigt, dass die Beleuchtung eingeschaltet ist, sieht wie folgt aus:

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

Das Metadatenformat für diese Kennung wird durch einen allgemeinen KSCAMERA_METADATA_ITEMHEADER definiert, gefolgt von einer KSSTREAM_UVC_METADATA-Struktur:

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;

Die Felder StartOfFrameTimestamp und EndOfFrameTimestamp sind die Zeitstempel, die in den UVC-Headern der ersten und letzten UVC-Payloads enthalten sind, die von der Kamera ausgegeben wurden, um dieses Bild zu erstellen.

Diese Payload sollte nicht von einem Gerät gesendet werden.

Diese Metadaten-Payload ist insofern einzigartig, als sie die einzige Metadaten-Payload ist, die direkt vom Treiber der USB-Videoklasse aus den von UVC-konformen Payload-Headern abgerufenen Informationen generiert wird.

Diese Payload wird dem Metadatenpuffer eines jeden Frames vorangestellt.

Wenn das Gerät standardisierte Metadaten unterstützt, muss es den zum Speichern dieser Payload benötigten Platz in seinen Pufferbedarf aufnehmen, wie vom Steuerelement für Metadaten in Abschnitt 2.2.2.9 geliefert.