Compartilhar via

Extensões da Microsoft para especificação da classe de vídeo USB 1.5

  • Artigo

1 Visão geral

1.1 Resumo

As extensões da Microsoft para a especificação de classe de vídeo USB permitem novos controles e a capacidade de transportar metadados de quadro bem definidos em um formato padrão.

1.2 Decisões de arquitetura

O suporte a metadados de quadro UVC (classe de vídeo USB) está disponível para pontos de extremidade ISOCH e BULK. No entanto, no caso do ponto de extremidade BULK, o tamanho dos metadados é limitado a 240 bytes (porque todos os dados de quadro de vídeo são transferidos em um único pacote de quadro de vídeo em pontos de extremidade BULK).

O suporte a metadados UVC só está disponível para cargas úteis baseadas em quadros.

O suporte a metadados UVC está disponível somente por meio do pipeline de captura do MF (Media Foundation).

Os metadados UVC estão sujeitos a aceitação. Todo IHV/OEM que precisa de suporte a metadados deve ser habilitado por meio de um arquivo INF personalizado.

Os metadados UVC são compatíveis apenas com memória alocada pelo sistema. As superfícies VRAM ou DX não serão compatíveis.

2. Visão geral da arquitetura

2.1 Descrição

2.2.1 Descoberta de capacidade por meio de INF

2.2.1.1 Captura de Imagem Estática – Método 2

Alguns dispositivos UVC existentes podem não aceitar o Método 2 descrito na seção 2.4.2.4 (Captura de Imagem Estática) do arquivo UVC 1.5 Class specification.pdf que pode ser baixado pelo site Especificação da classe de vídeo USB.

No Windows 10, versão 1607 e anteriores, o pipeline de captura não usava o Método 2, mesmo que um dispositivo anunciasse suporte para ele de acordo com a especificação UVC 1.5.

No Windows 10, versão 1703, os dispositivos que usam esse método devem usar um arquivo INF personalizado para o driver da câmera, mas um INF personalizado é necessário para o hardware fornecido para habilitar a captura de imagem estática do Método 2).

Observação: o driver da câmera pode ser baseado no Windows USBVIDEO.SYS ou em um binário de driver personalizado.

O arquivo INF personalizado, com base no driver UVC personalizado ou no driver UVC da caixa de entrada, deve incluir a seguinte entrada AddReg:

EnableDependentStillPinCapture: REG_DWORD: 0x0 (Desabilitado) para 0x1 (Habilitado)

Quando essa entrada é definida como Habilitado (0x1), o pipeline de captura usa o Método 2 para Captura de Imagem Estática (supondo-se que o firmware também anuncie o suporte para o Método 2, conforme determinado pela especificação UVC 1.5).

Um exemplo para a seção INF personalizada seria o seguinte:

[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 Controles de unidade de extensão

A extensão da Microsoft para a especificação de classe de vídeo USB para habilitar novos controles é feita por meio de uma unidade de extensão identificada por GUID MS_CAMERA_CONTROL_XU (conhecido como Microsoft-XU).

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

Um Microsoft-XU implementado pelo firmware do dispositivo abriga os novos controles definidos nas subseções a seguir. As definições de solicitação a seguir se aplicam a todos esses controles, a menos que uma definição de substituição seja especificada explicitamente para esse controle. Consulte o arquivo 1.5 Classe specification.pdf para saber as definições de D3, D4, GET_INFO, etc.

A solicitação GET_INFO deve relatar o controle sem recursos AutoUpdate e Assíncrono (por exemplo, os bits D3 e D4 devem ser definidos como 0).

A solicitação GET_LEN deve comunicar o comprimento máximo da carga útil para esse controlo (wLength).

A solicitação GET_RES deve relatar a resolução (tamanho de etapa) para qwValue/dwValue. Todos os outros campos devem ser definidos como 0.

A solicitação GET_MIN deve relatar o valor mínimo aceito para qwValue/dwValue. Todos os outros campos devem ser definidos como 0.

A solicitação GET_MAX deve relatar o valor máximo aceito para qwValue/dwValue. Além disso, todos os sinalizadores aceitos devem ser definidos como 1 em bmControlFlags. Todos os outros campos devem ser definidos como 0.

As solicitações GET_DEF e GET_CUR devem relatar as configurações padrão e atual, respectivamente, para os campos qwValue/dwValue e bmControlFlags. Todos os outros campos devem ser definidos como 0.

Uma solicitação SET_CUR é emitida pelo host após a configuração de todos os campos.

A tabela a seguir associa os seletores de controle do Microsoft-XU aos respectivos valores e à posição de bits do campo bmControls no descritor de unidade de extensão:

Seletor de controle Valor Posição dos bits
(Campo 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
Reservado para uso futuro 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 D10
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 Controles canceláveis

Um controle cancelável é definido aqui com o recurso Autoupdate.

A solicitação GET_INFO deve relatar esse controle como um Controle Autoupdate (por exemplo, o bit D3 deve ser definido como 1), mas não como um controle Assíncrono (por exemplo, o bit D4 deve ser definido como 0).

Para esse controle, uma solicitação SET_CUR pode ser emitida para definir uma nova solicitação de valor (SET_CUR(NORMAL) em que o bit bmOperationFlags:D0 é definido como 0) ou cancelar uma solicitação SET_CUR(NORMAL) anterior (SET_CUR(CANCEL) em que o bit bmOperationFlags:D0 é definido como 1). Uma solicitação SET_CUR deve ser concluída pelo dispositivo imediatamente assim que a solicitação for recebida (mesmo que o hardware não esteja configurado nem convergido para as novas configurações solicitadas). Para cada solicitação SET_CUR(NORMAL), o dispositivo produz uma interrupção de Alteração de Controle correspondente para esse controle gerada quando as novas configurações foram aplicadas ou quando uma solicitação SET_CUR(CANCEL) é recebida; até que essa interrupção seja recebida, a solicitação SET_CUR(NORMAL) é considerada em andamento. Quando uma solicitação SET_CUR(NORMAL) estiver em andamento, solicitações SET_CUR(NORMAL) adicionais para esse controle específico gerarão uma falha. Uma solicitação SET_CUR(CANCELAR) sempre será bem-sucedida. Se não houver nada para cancelar, o dispositivo simplesmente não fará nada.

A carga útil de interrupção de Alteração de Controle deverá ter o bit bmOperationFlags:D0 definido como 0 se as configurações especificadas por SET_CUR(NORMAL) foram aplicadas (por exemplo, ocorreu a convergência) e definido como 1 se as configurações não foram aplicadas devido a uma solicitação SET_CUR(CANCEL) recebida após a solicitação SET_CUR(NORMAL) (por exemplo, a convergência ainda não ocorreu).

2.2.2.2 Controle de Foco

Esse controle permite que o software host especifique as configurações de foco para a câmera. Esse é um controle global que afeta todos os pontos de extremidade em todas as interfaces de streaming de vídeo associadas à interface de controle de vídeo.

controle de foco.

Esse controlo deve funcionar como um Controle Cancelável (consulte a secção 2.2.2.1 para saber os requisitos da solicitação GET_INFO e o comportamento funcional da solicitação SET_CUR).

Requisito GET_MAX: esse controle deve anunciar suporte para os bits D0, D1, D2, D8 e D18 em bmControlFlags.

Requisito GET_DEF: o padrão para bmControlFlags deve ser D0 e D18 definidos como 1 e dwValue definido como 0.

Para solicitações GET_CUR/SET_CUR, as seguintes restrições se aplicam ao campo bmControlFlags:

  • Entre os bits D0, D1 e D8, apenas um bit pode ser definido; nenhum deles que for também for definido será válido se o bit D2 estiver definido.

  • Entre D16, D17, D18, D19 e D20, apenas um bit pode ser definido, nenhum deles se for definido será válido também.

  • D1 é incompatível com todos os outros bits atualmente definidos (D0, D2, D8, D16, D17, D18, D19 e D20).

  • D2 é incompatível com D1 e D8.

  • D2 será incompatível com D16, D17, D18, D19 e D20 se D0 não estiver definido.

2.2.2.3 Controle de Exposição

Esse controle permite que o software host especifique as configurações de exposição para a câmera. Esse é um controle global que afeta todos os pontos de extremidade em todas as interfaces de streaming de vídeo associadas à interface de controle de vídeo.

controle de exposição.

A solicitação GET_INFO deve relatar esse controle como um controle Assíncrono (por exemplo, o bit D4 deve ser definido como 1), mas não como um controle AutoUpdate (por exemplo, o bit D3 deve ser definido como 0).

Requisito GET_MAX: esse controle deve anunciar suporte para os bits D0, D1 e D2 em bmControlFlags.

Requisito GET_DEF: o padrão para bmControlFlags deve ser D0 definido como 1 e qwValue definido como 0.

Para solicitações GET_CUR/SET_CUR, as seguintes restrições se aplicam ao campo bmControlFlags:

  • Entre os bits D0, D1 e D2, pelo menos um bit deve ser definido.
  • D1 é incompatível com D0 e D2.
2.2.2.4 Controle de Compensação EV

Esse controle permite que o software host especifique as configurações de compensação EV para a câmera. Esse é um controle global que afeta todos os pontos de extremidade em todas as interfaces de streaming de vídeo associadas à interface de controle de vídeo.

Controle de compensação E V

A solicitação GET_INFO deve relatar esse controle como um controle Assíncrono (por exemplo, o bit D4 deve ser definido como 1), mas não como um controle AutoUpdate (por exemplo, o bit D3 deve ser definido como 0).

A solicitação GET_RES deve relatar todas as resoluções aceitas (tamanho de etapa) definindo os bits correspondentes em bmControlFlags. Todos os outros campos devem ser definidos como 0.

As solicitações GET_MIN e GET_MAX devem relatar os valores mínimo e máximo aceitos para dwValue. O bit D4 (indicando o tamanho de etapa de 1) deve ser o único bit definido em bmControlFlags. Todos os outros campos devem ser definidos como 0.

As solicitações GET_DEF, GET_CUR e SET_CUR devem seguir as definições da seção 2.2.2.1, mas devem ter um e apenas um bit definido entre os bits D0, D1, D2, D3 e D4 para o campo bmControlFlags. Além disso, a solicitação GET_DEF deve ter dwValue definido como 0.

2.2.2.5 Controle de Equilíbrio de Branco

Esse controle permite que o software host especifique as configurações de equilíbrio de branco para a câmera. Esse é um controle global que afeta todos os pontos de extremidade em todas as interfaces de streaming de vídeo associadas à interface de controle de vídeo.

controle de equilíbrio de branco

A solicitação GET_INFO deve relatar esse controle como um controle Assíncrono (por exemplo, o bit D4 deve ser definido como 1), mas não como um controle AutoUpdate (por exemplo, o bit D3 deve ser definido como 0).

As solicitações GET_RES, GET_MIN GET_MAX devem seguir as definições da seção 2.2.2.1, mas devem ter dwValueFormat definido como 1.

Requisito GET_MAX: esse controle deve anunciar suporte para os bits D0, D1 e D2 em bmControlFlags.

Requisito GET_DEF: o padrão para bmControlFlags deve ser D0 definido como 1 e dwValueFormat e dwValue definidos como 0.

Para solicitações GET_CUR/SET_CUR, as seguintes restrições se aplicam ao campo bmControlFlags:

  • Entre os bits D0, D1 e D2, pelo menos um bit deve ser definido.
  • D1 é incompatível com D0 e D2.
2.2.2.6 Controle de Autenticação Facial

Esse controle permite que o software host especifique se a câmera aceita modos de streaming usados para autenticação facial. O suporte para esse controle implica que a câmera é habilitada para autenticação facial. Esse controle não deve ser compatível de outra forma.

Esse controle só é aplicável a câmeras que possam produzir dados de infravermelho (IR) e só é aplicável às interfaces de streaming especificadas (que é um subconjunto de todas as interfaces de streaming de vídeo associadas à interface de controle de vídeo).

controle de autenticação facial.

As solicitações GET_RES e GET_MIN devem relatar o campo bNumEntries definido como 0 e, portanto, não têm campos adicionais.

Para uma solicitação GET_MAX, um bit definido como 1 no campo bmControlFlags indica que o modo correspondente é aceito para essa interface de streaming. Uma saída da solicitação GET_MAX deve listar todas e somente as interfaces de streaming habilitadas para D1 ou D2 (por exemplo, se uma interface de streaming for habilitada para D1 ou D2, ela será listada; caso contrário, não será). Além disso, nenhuma interface de streaming deve ser anunciada como habilitada para D1 e D2. Se uma interface de streaming também se destinar ao uso geral (por exemplo, fora da finalidade de autenticação facial), D0 deverá ser definido como 1 para essa interface de streaming (além de D1/D2).

Para solicitações GET_DEF/GET_CUR/SET_CUR, um bit definido como 1 no campo bmControlFlags indica que o modo correspondente foi escolhido para essa interface de streaming. Nessas solicitações, um e apenas um bit (entre D0, D1 e D2) deve ser definido para uma interface de streaming específica. Para a solicitação GET_DEF que exibe a opção padrão (que é específica da implementação), se uma interface de streaming também for destinada ao uso geral (por exemplo, fora da finalidade de autenticação facial), D0 deverá ser definido como 1 por padrão nessa interface de streaming; caso contrário, D1 ou D2 (mas não ambos) deverá ser definido como 1 por padrão. Uma saída da solicitação GET_DEF/GET_CUR deve conter informações sobre todas as interfaces de streaming listadas na saída da solicitação GET_MAX, no entanto, uma solicitação SET_CUR pode incluir apenas um subconjunto das interfaces de streaming listadas na saída da solicitação GET_MAX.

Exemplo:

Vamos supor que uma câmera tenha quatro interfaces de streaming de vídeo com os números 0x03, 0x05, 0x08 e 0x0b respectivamente, em que a interface de streaming de vídeo 0x05 produza dados RGB e as três interfaces de streaming de vídeo restantes produzam dados IR. Entre as interfaces de streaming que produzem dados IR, vamos supor que as interfaces de streaming 0x03 e 0x0b sejam habilitadas para D1, mas a interface de streaming 0x03 também seja habilitada para D0. Neste exemplo, o controle de autenticação facial só é aplicável às interfaces de streaming 0x03 e 0x0b e, portanto, somente essas interfaces aparecem nas solicitações.

A saída da solicitação GET_MAX é a seguinte:

autenticação facial GET_MAX.

A saída da solicitação GET_DEF é a seguinte:

autenticação facial GET_DEF.

Uma solicitação SET_CUR para alterar a configuração na interface de streaming 0x03 para D1 seria a seguinte:

autenticação facial SET_CUR.

A saída de uma solicitação GET_CUR após a solicitação SET_CUR acima é a seguinte:

autenticação facial GET_CUR.

2.2.2.7 Controle Extrínseco da Câmera

Esse controle permite que o software host obtenha os dados extrínsecos da câmera para pontos de extremidade em interfaces de streaming de vídeo associadas à interface de controle de vídeo. Os dados obtidos para cada ponto de extremidade são exibidos como o atributo MFStreamExtension_CameraExtrinsics no armazenamento de atributos para o fluxo correspondente (obtidos usando a chamada IMFDeviceTransform::GetOutputStreamAttributes).

controle extrínseco da câmera.

As solicitações GET_RES, GET_MIN e GET_MAX, GET_CUR devem relatar o campo bNumEntries definido como 0 e, portanto, não têm campos adicionais.

A solicitação GET_DEF deve listar todos os parâmetros que têm informações extrínsecas.

Exemplo:

Vamos supor que uma câmera tenha três interfaces de streaming de vídeo com os números 0x03, 0x05 e 0x08 respectivamente, em que a interface de streaming de vídeo 0x05 aceita captura de imagem estática usando o método 2, além da captura de vídeo aceita por todas as interfaces de streaming de vídeo. Entre essas interfaces de streaming, vamos supor que as interfaces de streaming 0x05 e 0x08 tenham informações extrínsecas disponíveis e a interface de streaming 0x03 não as tenha.

Neste exemplo, a saída da solicitação GET_DEF será a seguinte:

extrínsecos da câmera GET_DEF.

2.2.2.8 Controle Intrínseco da Câmera

Esse controle permite que o software host obtenha os dados intrínsecos da câmera para pontos de extremidade em interfaces de streaming de vídeo associadas à interface de controle de vídeo. Os dados obtidos para cada ponto de extremidade são exibidos como o atributo MFStreamExtension_PinholeCameraIntrinsics no armazenamento de atributos para o fluxo correspondente (obtidos usando a chamada IMFDeviceTransform::GetOutputStreamAttributes).

controle intrínseco da câmera

As solicitações GET_RES, GET_MIN e GET_MAX, GET_CUR devem relatar o campo bNumEntries definido como 0 e, portanto, não têm campos adicionais.

A solicitação GET_DEF deve listar todos os parâmetros que têm informações intrínsecas.

Exemplo:

Vamos supor que uma câmera tenha três interfaces de streaming de vídeo com os números 0x03, 0x05 e 0x08 respectivamente, em que a interface de streaming de vídeo 0x05 aceita captura de imagem estática usando o método 2, além da captura de vídeo aceita por todas as interfaces de streaming de vídeo. Entre essas interfaces de streaming, vamos supor que as interfaces de streaming 0x05 e 0x08 tenham informações intrínsecas disponíveis e a interface de streaming 0x03 não as tenha.

Neste exemplo, a saída da solicitação GET_DEF será a seguinte:

intrínsecos da câmera GET_DEF.

2.2.2.9 Controle de Metadados

Esse controle permite que o software host consulte e controle os metadados produzidos pela câmera. Esse é um controle global que afeta todos os pontos de extremidade em todas as interfaces de streaming de vídeo associadas à interface de controle de vídeo.

Esse controle é associado a KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA pelo driver da câmera.

controle de metadados

Se a solicitação SET_CUR for compatível com o firmware, o seguinte se aplicará:

  • As solicitações GET_MIN, GET_DEF devem relatar o campo dwValue definido como 0.

  • A solicitação GET_RES deve relatar o campo dwValue como o mesmo valor relatado pela solicitação GET_MAX.

  • Quando uma solicitação SET_CUR é recebida com dwValue definido como 0, a câmera não deve produzir metadados. Quando uma solicitação SET_CUR é recebida com dwValue definido como sendo o mesmo valor relatado pela solicitação GET_MAX, a câmera pode produzir metadados e o tamanho desses metadados não pode exceder dwValue para qualquer quadro.

Se a solicitação SET_CUR não for compatível com o firmware, o seguinte se aplicará:

  • As solicitações GET_MIN, GET_DEF devem relatar o campo dwValue como o mesmo valor relatado pela solicitação GET_MAX.

  • A solicitação GET_RES deve relatar o campo dwValue definido como 0.

  • A câmera pode produzir metadados, e o tamanho total desses metadados não pode exceder o dwValue - conforme relatado pela solicitação GET_MAX - vezes 1.024 bytes menos o tamanho de uma carga útil de metadados UsbVideoHeader, para qualquer quadro.

  • Uma carga útil de metadados UsbVideoHeader corresponde ao sizeof(KSCAMERA_METADATA_ITEMHEADER) + sizeof(KSTREAM_UVC_METADATA) ou 24 bytes.

Os metadados produzidos devem estar em conformidade com os metadados em formato padrão da Microsoft descrito na secção 2.2.3.

2.2.2.10 Controle de Lanterna IR

Este controle oferece um meio flexível para o hardware LED IR relatar a extensão em que ele pode ser controlado e fornece a capacidade de controlá-lo. Trata-se de um controle global que afeta todos os pontos de extremidade em todas as interfaces de streaming de vídeo associadas à interface de controle de vídeo, ajustando a energia para uma lâmpada IR conectada à câmera.

Esse controle é associado a KSPROPERTY_CAMERACONTROL_EXTENDED_IRTORCHMODE pelo driver da câmera.

Controle da lanterna I R.

O seguinte se aplica:

  • A solicitação GET_LEN deve relatar um valor de 8.

  • A solicitação GET_INFO deve relatar um valor de 3. Esse valor indica um controle síncrono que aceita GET_CUR e SET_CUR.

  • A solicitação GET_MIN deve relatar o campo dwMode definido como 0 e dwValue definido como um valor que indique potência mínima. Um nível de potência de 0 pode indicar OFF, mas o nível mínimo de potência operacional não precisa ser 0.

  • A solicitação GET_RES deve relatar o campo dwMode definido como 0 e dwValue definido como um número menor ou igual a GET_MAX(dwValue) – GET_MIN(dwValue) e de forma que GET_MAX(dwValue) – GET_MIN(dwValue) seja uniformemente divisível por esse valor. dwValue não pode ser zero (0).

  • A solicitação GET_MAX deve relatar o campo dwMode definido com os bits D[0-2] definidos para identificar os recursos desse controle. dwMode deve ter o bit D0 definido, indicando que OFF é aceito e deve ter pelo menos outro bit definido, oferecendo suporte a um estado ativo. dwValue deve ser definido como um valor que indique potência normal.

  • A solicitação GET_DEF deve relatar o campo dwMode definido como o modo padrão em que o sistema deve estar antes do início do streaming. dwMode deve ser definido como 2 (ON) ou 4 (ALTERNATING). dwValue deve ser definido para o nível de potência normalmente usado para o controle FaceAuth. dwValue é definido pelo fabricante.

  • A solicitação GET_CUR deve relatar o campo dwMode definido como o modo de operação atual e dwValue definido como a iluminação atual.

  • Quando uma solicitação SET_CUR é recebida, a Lanterna IR define a iluminação como uma intensidade proporcional usando o modo de operação solicitado.

A Lanterna IR deve emitir o atributo MF_CAPTURE_METADATA_FRAME_ILLUMINATION para cada quadro. Ele pode fornecer isso por meio de um MFT de dispositivo ou incluindo um atributo MetadataId_FrameIllumination na carga útil de metadados da câmera. Consulte a seção 2.2.3.4.4.

O único objetivo desses metadados é indicar se um quadro está iluminado ou não. Esses são os mesmos metadados exigidos pelo DDI KSPROPERTY_CAMERACONTROL_EXTENDED_FACEAUTH_MODE e pelo MSXU_FACE_AUTHENTICATION_CONTROL definido na seção 2.2.2.6.

2.2.2.11 Controle de Janela Digital

A Janela Digital especifica o campo de visão e o zoom da câmera enquanto a câmera está transmitindo. Esse controle é um possível substituto de Panorâmica, Inclinação e Zoom. Esse controle só se aplicará enquanto a câmera estiver transmitindo ativamente.

Esse controle está disponível para todos os tipos de câmera e é independente do tipo de mídia que está sendo transmitido.

Esse controle permite que o software host consulte e controle a janela digital associada a uma câmera.

Esse é um controle global que afeta todos os pontos de extremidade em todas as interfaces de streaming de vídeo associadas à interface de controle de vídeo. Ele ajusta a fonte de dados de pixel usada pelo ISP. Isso inclui os pinos de captura do Método 2 e do Método 3.

Esse controle é associado a KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW pelo driver da câmera da caixa de entrada.

controle de janela digital

O seguinte se aplica:

  • A solicitação GET_LEN deve relatar um valor de 16.

  • A solicitação GET_INFO deve relatar um valor de 3. Esse valor indica um controle síncrono que aceita GET_CUR e SET_CUR.

  • A solicitação GET_MIN deve relatar o campo dwMode definido como 0, OriginX e OriginY definidos como 0.0 e WindowSize definido como 1.0. Esta solicitação não é usada no momento.

  • A solicitação GET_RES deve relatar o campo dwMode definido como 0, OriginX e OriginY definidos como 0.0 e WindowSize definido como 1.0. Esta solicitação não é usada no momento.

  • A solicitação GET_MAX deve relatar o campo dwMode definido com o bit D0 definido para identificar os recursos desse controle. Um valor 0 indica que somente o modo manual é aceito. Um valor de 1 indica que o modo de enquadramento facial automático é aceito. O restante desses campos não é usado, no entanto, recomendamos que OriginX e OriginY sejam definidos como 0.0 e WindowSize definido como 1.0.

  • A solicitação GET_DEF deve relatar o campo dwMode definido como 0, OriginX e OriginY definidos como 0.0 e WindowSize definido como 1.0. Essa é sempre a janela padrão.

  • A solicitação GET_CUR deve relatar o campo dwMode definido como o modo operacional atual e OriginX, OriginY e WindowSize descrevem a janela digital atual.

  • Quando uma solicitação SET_CUR é recebida, a câmera ajusta seu campo de visão para corresponder ao modo de operação selecionado e à janela digital.

  • Se o modo de enquadramento facial automático estiver selecionado, a câmera selecionará uma janela que engloba totalmente a face dominante na cena e OriginX, OriginY e WindowSize transmitidos serão ignorados. Se nenhuma face for encontrada, a janela padrão será usada.

  • Todas as alterações na janela digital devem ser refletidas na carga útil de metadados de cada amostra.

  • As alterações na janela digital podem não entrar em vigor imediatamente, mas o controle deve responder imediatamente. As alterações na janela digital deverão ser relatadas na carga útil de metadados do quadro assim que entrarem em vigor.

2.2.2.12 Controle de Configuração de Janela Digital

O controle Limites de Configuração de Janela Digital especifica os limites de dimensionamento da câmera, considerando todas as resoluções disponíveis. As resoluções são independentes do tipo de mídia, portanto, dois tipos de mídia que anunciam a mesma resolução de exibição são combinados em um recurso.

Devido às limitações de tamanho de um ponto de extremidade de controle, esse controle pode descrever no máximo 1.820 resoluções exclusivas.

Esse controle deverá estar sempre disponível para relatar os recursos do controle Janela Digital se esse controle também estiver presente.

Esse controle é associado a KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW_CONFIGCAPS pelo driver da câmera da caixa de entrada.

controle de configuração de janela digital.

O seguinte se aplica:

  • A solicitação GET_LEN deve relatar todo o tamanho da carga útil. O tamanho da carga útil deve ser um múltiplo de 36, pois cada definição de resolução tem 36 bytes de tamanho.

  • A solicitação GET_INFO deve relatar 1. Esse valor indica um controle síncrono que aceita apenas GET_CUR.

  • A solicitação GET_CUR deve relatar uma série de recursos. Os campos da estrutura de recursos são definidos acima.

  • As solicitações GET_MIN, GET_MAX, GET_RES e GET_DEF não são utilizadas, mas devem exibir os mesmos valores que GET_CUR.

  • As solicitações SET_CUR não são compatíveis.

2.2.2.13 Controle de HDR de Vídeo

Esse controle permite que o software host especifique se a câmera aceita HDR de Vídeo. O suporte para esse controle implica que a câmera seja capaz de executar HDR de vídeo como o melhor esforço. Se a câmera não comportar HDR de Vídeo, ela não deverá implementar esse controle.

Esse controle é associado a KSPROPERTY_CAMERACONTROL_EXTENDED_VIDEOHDR pelo driver da câmera.

controle H D R de vídeo.

O seguinte se aplica:

  • A solicitação GET_LEN deve relatar todo o tamanho da carga útil (por exemplo, 4 bytes).

  • A solicitação GET_INFO deve relatar um valor de 3. Esse valor indica um controle síncrono que aceita GET_CUR e SET_CUR.

  • A solicitação GET_CUR deve relatar o campo dwMode definido como o modo de operação atual.

  • GET_DEF deve ter um dwMode definido como OFF (0).

  • A solicitação GET_MAX deve anunciar o suporte para os modos de operações disponíveis: [1 (ON/OFF), 3 (ON/OFF/Auto)]. O suporte para ON (1) é obrigatório para esse controle.

  • As solicitações GET_MIN e GET_RES devem relatar 0.

  • A solicitação SET_CUR deve definir o modo como OFF (0), ON (1) ou AUTO (2).

2.2.2.14 Controle de Restrição de Taxa de Quadros

Esse controle permite que o software host especifique se a câmera é compatível com a restrição de Taxa de Quadros.

Esse controle só se aplicará enquanto a câmera estiver transmitindo ativamente. Estar transmitindo ativamente significa que um pino de visualização ou gravação deve estar em KSSTATE_RUN, pronto e capaz de entregar quadros. Em um conjunto, se um fluxo não estiver ativo, esse controle deverá exibir STATUS_INVALID_DEVICE_STATE.

Mesmo que esse seja um controle de escopo de filtro, o controle de taxa de quadros não deverá afetar o pino de foto ou fluxos sem RGB, como IR/profundidade. Além disso, quando a restrição de taxa de quadros estiver em vigor, a duração da amostra também deverá ser ajustada corretamente.

Esse controle é associado a KSPROPERTY_CAMERACONTROL_EXTENDED_FRAMERATE_THROTTLE pelo driver da câmera.

Seletor de controle MSXU_CONTROL_FRAMERATE_THROTTLE
Solicitações obrigatórias GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR, SET_CUR
Solicitações opcionais
wLength 20
Deslocamento Campo Tamanho Valor Descrição
0 dwMode 4 Sinalizadores D0: 0 (OFF) ou 1 (ON)
D1-D31: reservado e definido como 0
4 scaleFactorPercentage 4 Número Esse valor deve estar dentro do intervalo de Mín e Máx e deve ser definido como um múltiplo do valor de Etapa. Por exemplo: se Mín = 5, Máx = 100 e Etapa = 5 e se um aplicativo decidiu reduzir a taxa de quadros para 80% do valor original, esse valor de membro deverá ser definido como 80. Ao definir esse valor adequadamente, um aplicativo pode garantir que a nova taxa de quadros nunca exceda o valor original, nem chegue a zero, mas a taxa de quadros original seja possível.
8 min 4 Número O mínimo deve ser igual ao tamanho de uma etapa ou deve ser um múltiplo de tamanho de etapa (Por exemplo: etapa1, Etapa2, etc.). O valor mínimo não pode ser definido como 0.
12 max 4 Número Máx deve ser definido como 100, o que significa que não há alteração na taxa de quadros.
16 step 4 Número Etapa deve ser um fator estrito de Máx, por exemplo, {Max % Step == 0}. Exemplo: 1, 2, 4, 5, etc.

O seguinte se aplica:

  • A solicitação GET_LEN deve relatar todo o tamanho da carga útil (por exemplo, 20 bytes). 

  • A solicitação GET_INFO deve relatar um valor de 3. Esse valor indica um controle síncrono que aceita GET_CUR e SET_CUR. 

  • A solicitação GET_CUR deve relatar o campo dwMode definido como o modo de operação atual e scaleFactorPercentage definido como o valor scaleFactor atual. Mín, máx e etapa devem relatar os valores conforme descrito na tabela acima.

  • GET_DEF deve ter um dwMode definido como OFF(0), scaleFactorPercentage=100, Mín definido como valor mínimo padrão, máx definido como 100 e etapa definida como valor de etapa padrão. Os valores de mín e etapa devem ser definidos pelo fabricante, mas devem seguir as orientações mencionadas na tabela acima.

  • A solicitação GET_MAX anunciará o suporte para os modos de operações disponíveis e relatará o valor 1 [ ON | OFF ]. O suporte para ON e OFF é obrigatório para esse controle. Mín, máx, etapa e scaleFactorPercentage podem ser definidos como os valores padrão.

  • As solicitações GET_MIN e GET_RES devem relatar 0. 

  • A solicitação SET_CUR deve definir o modo como OFF(0), ON(1). Se dwMode estiver definido como ON, scaleFactorPercentage entrará em vigor. Para os casos OFF e ON, o scaleFactorPercentage deve ser válido conforme descrito na tabela acima.

2.2.2.15 Controle de Configuração de Campo de Visão 2

O Controle de Configuração de Campo de Visão 2 especifica os valores de grau de Campo de Visão diagonal com suporte como uma matriz de valores. Todos os valores aceitos devem estar na faixa de teórico mín e máx, 1 grau - 360 graus.

Se o dispositivo quiser oferecer aceitar valores contínuos de Campo de Visão, ele precisará relatar todos os valores compatíveis. Por exemplo, se o dispositivo quiser comportar o Campo de Visão diagonal de 85 graus a 60 graus com tamanho de etapa de 1, esse controle precisará relatar a matriz de valores [85, 84, 83, 82, ..., 62, 61, 60].

Esse controle deve estar disponível para relatar os recursos quando o controle de Campo de Visão 2 estiver presente.

Este é o controle de nível de filtro síncrono.

Esse controle é associado a KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2_CONFIGCAPS pelo driver da câmera.

Seletor de controle MSXU_CONTROL_FIELDOFVIEW2_CONFIG
Solicitações obrigatórias GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR
Solicitações opcionais
wLength 4 bytes + Contagem vezes 4 bytes, em que Contagem é o número de valores exclusivos do Campo de Visão.
Deslocamento Campo Tamanho Valor Descrição
0 dwDefaultFieldOfView 4 Número O Campo de Visão diagonal padrão deve ser um dos valores relatados na matriz FieldOfViewValues.
4 FieldOfViewValues[0] 4 Número Primeiro valor de Campo de Visão, esse deve ser o valor FoV (Campo de Visão) mais amplo.
… … … … …
4 + 4*(Contagem-1) FieldOfViewValues [Contagem -1] 4 Número Último valor de Campo de Visão, esse deve ser o valor de FoV mais estreito.

O seguinte se aplica:

  • A solicitação GET_LEN deve relatar todo o tamanho da carga útil.

  • A solicitação GET_INFO deve relatar 1. Esse valor indica um controle síncrono que aceita apenas GET_CUR.

  • A solicitação GET_CUR deve relatar dados que contenham FoV padrão e matriz de valores de FoV compatíveis em ordem decrescente. Os campos da estrutura são definidos acima.

  • A solicitação GET_DEF deve relatar o mesmo que GET_CUR.

  • As solicitações GET_MIN, GET_MAX e GET_RES não são utilizadas, mas devem exibir os mesmos valores que GET_CUR.

  • As solicitações SET_CUR não são compatíveis.

Os valores de Campo de Visão devem estar em ordem decrescente, por exemplo, o Campo de Visão mais largo é o primeiro e o mais estreito é o último.

2.2.2.16 Controle de Campo de Visão 2

Esse controle especifica o campo de visão base que a câmera está usando durante o streaming. Esse controle pode ser aplicado antes ou durante o streaming.

Esse controle está disponível para todos os tipos de câmera e é independente do tipo de mídia que está sendo transmitido.

Esse controle permite que o software host consulte e controle o campo de visão associado a uma câmera.

Esse é um controle global que afeta todos os pontos de extremidade em todas as interfaces de streaming de vídeo associadas à interface de controle de vídeo. Ele ajusta a fonte de dados de pixel (ou sensor) usada pelo ISP (Image Signal Processor). Isso inclui os pinos de captura do Método 2 e do Método 3.

Este é o controle de nível de filtro síncrono.

Esse controle é associado a KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2 pelo driver da câmera.

Seletor de controle MSXU_CONTROL_FIELDOFVIEW2
Solicitações obrigatórias GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR, SET_CUR
Solicitações opcionais
wLength 4
Deslocamento Campo Tamanho Valor Descrição
0 dwValue 4 Número Valor do Campo de Visão Diagonal em graus.

O seguinte se aplica:

  • A solicitação GET_LEN deve relatar um valor de 4.

  • A solicitação GET_INFO deve relatar 3. Esse valor indica um controle síncrono que aceita GET_CUR e SET_CUR.

  • A solicitação GET_MIN deve relatar o campo dwValue definido como valor mínimo de Campo de Visão compatível.

  • A solicitação GET_RES deve relatar o campo dwValue definido como 0. Esta solicitação não é usada no momento.

  • A solicitação GET_MAX deve relatar o campo dwValue definido como valor máximo de Campo de Visão compatível.

  • A solicitação GET_DEF deve relatar o campo dwValue definido como o valor padrão de Campo de Visão.

  • A solicitação GET_CUR deve relatar o campo dwValue definido como o valor atual de Campo de Visão.

  • Quando uma solicitação SET_CUR é recebida, a câmera define seu campo de visão para corresponder ao dwValue fornecido.

  • Se a câmara implementar CT_ZOOM_RELATIVE_CONTROL e/ou CT_ZOOM_ABSOLUTE_CONTROL, esses controles deverão ser redefinidos como os seus valores padrão quando MSXU_CONTROL_FIELDOFVIEW2 SET_CUR for chamado.

Se a câmera implementar MSXU_CONTROL_DIGITALWINDOW, refletirá a mudança de janela quando um novo valor de Campo de Visão for definido. E vice-versa, o Campo de Visão deve refletir as alterações feitas via Janela Digital. Consulte KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2 para obter detalhes.

2.2.3 Metadados

O design para metadados de quadro em formato padrão baseia-se no design de metadados personalizados UVC do Windows 10. No Windows 10, metadados personalizados são compatíveis com UVC usando um INF personalizado para o driver da câmera (observação: o driver da câmera pode ser baseado no Windows USBVIDEO.SYS, mas é necessário um INF personalizado para que o hardware fornecido permita a transmissão dos metadados). Se a entrada do Registro MetadataBufferSizeInKB<PinIndex> estiver presente e for diferente de zero, os metadados personalizados serão compatíveis com esse pino e o valor indicará o tamanho do buffer usado para os metadados. O campo <PinIndex> indica um índice baseado em 0 do índice de pinos de vídeo.

No Windows 10, versão 1703, um driver de câmera pode sinalizar suporte para metadados em formato padrão da Microsoft incluindo a seguinte entrada AddReg:

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

Essa chave do Registro será lida pelo DevProxy e informará ao driver UVC que os metadados estão no formato padrão, definindo o sinalizador KSSTREAM_METADATA_INFO_FLAG_STANDARDFORMAT no campo Sinalizadores para a estrutura KSSTREAM_METADATA_INFO.

2.2.3.1 Metadados em formato padrão da Microsoft

Os metadados em formato padrão da Microsoft são uma ou mais instâncias da seguinte estrutura:

metadados em formato padrão.

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

O campo MetadataId é preenchido por um identificador da seguinte definição de enum que contém identificadores bem definidos e identificadores personalizados (identificadores >= 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;

O campo Tamanho é definido como sizeof(KSCAMERA_METADATA_ITEMHEADER) + sizeof(Metadata Payload).

2.2.3.2 Metadados em formato padrão gerados por firmware a partir de pacotes de quadros de vídeo USB

Durante uma transferência sobre UVC para vídeo baseado em quadro, o quadro de vídeo é empacotado em uma série de pacotes, cada um precedido por um cabeçalho de carga útil UVC. Cada conector de carga útil UVC é definido pela especificação de carga útil baseada em quadro de driver de classe de vídeo USB:

Cabeçalho de carga útil

Veja uma descrição do formato de cabeçalho de carga útil para formatos baseados em quadro.

cabeçalho de carga útil.

Campo HLE (tamanho do cabeçalho)

O campo de tamanho do cabeçalho especifica o tamanho do cabeçalho, em bytes.

Campo de cabeçalho do campo de bits

FID: Identificador do Quadro

  • Esse bit alterna em cada limite inicial do quadro e permanece constante para o resto do quadro.

EOF: Fim do Quadro

  • Esse bit indica o final de um quadro de vídeo e é definido na última amostra de vídeo pertencente a um quadro. O uso desse bit é uma otimização para reduzir a latência na conclusão de uma transferência de quadros, e é opcional.

PTS: Carimbo de Data e Hora da Apresentação

  • Esse bit, quando definido, indica a presença de um campo PTS.

SCR: Referência de Relógio de Origem

  • Esse bit, quando definido, indica a presença de um campo SCR.

RES: Reservado.

  • Defina como 0.

IST: Imagem Estática

  • Este bit, quando definido, identifica uma amostra de vídeo como pertencente a uma imagem estática.

ERR: Bit de Erro

  • Esse bit, quando definido, indica um erro no streaming do dispositivo.

EOH: Fim do Cabeçalho

  • Esse bit, quando definido, indica o final dos campos BFH.

PTS: Carimbo de Data e Hora da Apresentação, Tamanho: 4 bytes, Valor: Número

  • O campo PTS está presente quando o bit PTS é definido no campo BFH[0]. Consulte a Seção 2.4.3.3 "Cabeçalhos de carga útil de vídeo e de imagem estática" na especificação Definição de classe de dispositivo USB para dispositivos de vídeo.

SCR: Referência de Relógio de Origem, Tamanho: 6 bytes, Valor: Número

  • O campo SCR está presente quando o bit SCR é definido no campo BFH[0]. Consulte a Seção 2.4.3.3 Cabeçalhos de carga útil de vídeo e de imagem estática na especificação Definição de classe de dispositivo USB para dispositivos de vídeo.

O campo HLE no driver UVC existente é fixado em 2 bytes (sem PTS/SCR presente) ou até 12 bytes (PTS/SCR presente). No entanto, o campo HLE, sendo um campo com tamanho de bytes, pode especificar até 255 bytes de dados de cabeçalho. Se PTS/SCR estiverem presentes e o HLE tiver mais que 12 bytes, todos os dados adicionais após os primeiros 12 bytes do cabeçalho de carga útil serão captados como metadados padrão específicos do quadro de vídeo quando a entrada INF StandardFormatMetadata<PinIndex> for definida.

Os metadados em formato padrão (gerados pelo firmware) para um quadro são obtidos concatenando os blobs parciais encontrados nos pacotes de quadros de vídeo que representam esse quadro.

pacotes de quadros de metadados.

2.2.3.3 Buffer de metadados fornecido ao componente de modo de usuário

O buffer de metadados fornecido ao componente de modo de usuário teria um item de metadados para os carimbos de data e hora UVC (gerados pelo driver UVC) seguido por itens de metadados gerados por firmware e eles são dispostos da seguinte maneira:

buffer de metadados.

2.2.3.4 Formato de metadados para identificadores de metadados padrão

O firmware pode escolher se deseja ou não produzir metadados correspondentes a um identificador. Se o firmware optar por produzir metadados correspondentes a um identificador, os metadados desse identificador deverão estar presentes em todos os quadros emitidos pelo firmware.

2.2.3.4.1 MetadataId_CaptureStats

O formato de metadados desse identificador é definido pela seguinte estrutura:

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;

O campo Sinalizadores indica quais dos campos posteriores na estrutura estão preenchidos e têm dados válidos. O campo Sinalizadores não deve variar de quadro para quadro. Atualmente, os seguintes sinalizadores estão definidos:

#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

O campo Reservado é reservado para o futuro e deve ser definido como 0.

O campo ExposureTime contém o tempo de exposição, em 100 ns, aplicado ao sensor quando o quadro foi capturado. Isso é exibido como o atributo MF_CAPTURE_METADATA_EXPOSURE_TIME no exemplo de MF correspondente.

O campo ExposureCompensationFlags contém a etapa de compensação de EV (exatamente um dos sinalizadores de etapa KSCAMERA_EXTENDEDPROP_EVCOMP_XXX deve ser definido) usada para transmitir o valor de Compensação de EV. O campo ExposureCompensationValue contém o valor de Compensação de EV em unidades da etapa aplicada ao sensor quando o quadro foi capturado. Elas aparecem como o atributo MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION no exemplo de MF correspondente.

O campo IsoSpeed contém o valor de velocidade ISO aplicado ao sensor quando o quadro foi capturado. Não tem unidade. É exibido como o atributo MF_CAPTURE_METADATA_ISO_SPEED no exemplo de MF correspondente.

O campo FocusState contém o estado de foco atual que pode assumir um dos valores definidos em enum KSCAMERA_EXTENDEDPROP_FOCUSSTATE. É exibido como o atributo MF_CAPTURE_METADATA_FOCUSSTATE no exemplo de MF correspondente.

O campo LensPosition contém a posição lógica da lente quando o quadro foi capturado, que é sem unidade. É o mesmo valor que pode ser consultado a partir de KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS em uma chamada GET. É exibido como o atributo MF_CAPTURE_METADATA_LENS_POSITION no exemplo de MF correspondente.

O campo WhiteBalance contém o equilíbrio de branco aplicado ao sensor quando o quadro foi capturado, que é um valor em Kelvin. É exibido como o atributo MF_CAPTURE_METADATA_WHITEBALANCE no exemplo de MF correspondente.

O campo Flash contém um valor booliano com 1 significando flash ativado e 0 significando flash desativado, quando o quadro foi capturado. É exibido como o atributo MF_CAPTURE_METADATA_FLASH no exemplo de MF correspondente.

O campo FlashPower contém a potência flash aplicada ao quadro capturado, que é um valor no intervalo de [0, 100]. Esse campo deverá ser omitido se o driver não comportar energia ajustável para flash. É exibido como o atributo MF_CAPTURE_METADATA_FLASH_POWER no exemplo de MF correspondente.

O campo ZoomFactor contém o valor de zoom no formato Q16 aplicado ao quadro capturado. É exibido como o atributo MF_CAPTURE_METADATA_ZOOMFACTOR no exemplo de MF correspondente.

O campo SceneMode contém o modo de cena aplicado ao quadro capturado, que é um sinalizador KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX de 64 bits. É exibido como o atributo MF_CAPTURE_METADATA_SCENE_MODE no exemplo de MF correspondente.

O campo SensorFramerate contém a taxa de leitura do sensor medida em hertz quando o quadro é capturado, que consiste em um valor de numerador no bit 32 superior e um valor de denominador no bit 32 inferior. É exibido como o atributo MF_CAPTURE_METADATA_SENSORFRAMERATE no exemplo de MF correspondente.

2.2.3.4.2 MetadataId_CameraExtrinsics

O formato de metadados para esse identificador envolve o KSCAMERA_METADATA_ITEMHEADER padrão seguido por uma carga útil de matriz de bytes. A carga útil deve se alinhar a uma estrutura MFCameraExtrinsics seguida por zero ou mais estruturas MFCameraExtrinsic_CalibratedTransform. A carga útil deve estar alinhada com 8 bytes e todos os bytes não utilizados devem ocorrer no final da carga útil e ser definidos como 0.

2.2.3.4.3 MetadataId_CameraIntrinsics

O formato de metadados para esse identificador envolve o KSCAMERA_METADATA_ITEMHEADER padrão seguido por uma carga útil de matriz de bytes. A carga útil deve se alinhar a uma estrutura MFPinholeCameraIntrinsics. A carga útil deve estar alinhada com 8 bytes e todos os bytes não utilizados devem ocorrer no final da carga útil e ser definidos como 0.

2.2.3.4.4 MetadataId_FrameIllumination

O formato de metadados desse identificador é definido pela seguinte estrutura:

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

O campo Sinalizadores indica informações sobre o quadro capturado. Atualmente, os seguintes sinalizadores estão definidos:

#define KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON 0x00000001

Se um quadro foi capturado quando a iluminação estava acesa, o sinalizador KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON deverá ser definido. Caso contrário, esse sinalizador não será definido.

O campo Reservado é reservado para uso futuro e deve ser definido como 0.

Exemplo:

Por exemplo, uma estrutura KSCAMERA_METADATA_FRAMEILLUMINATION indicando que a iluminação estava ligada seria a seguinte:

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

O formato de metadados para esse identificador é definido por um KSCAMERA_METADATA_ITEMHEADER comum seguido por uma estrutura 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;

Os campos StartOfFrameTimestamp e EndOfFrameTimestamp são os carimbos de data/hora contidos nos cabeçalhos UVC na primeira e na última carga útil UVC emitidas pela câmera para construir esse quadro.

Essa carga não deve ser enviada por um dispositivo.

Essa carga útil de metadados é única, pois é a única carga útil de metadados gerada diretamente pelo driver de classe de Vídeo USB com base nas informações obtidas de cabeçalhos de carga útil compatíveis com UVC.

Essa carga útil é anexada ao buffer de metadados de cada quadro.

Se o dispositivo comportar metadados padronizados, ele deverá incluir o espaço necessário para armazenar essa carga útil em seus requisitos de buffer, conforme relatado pelo Controle de Metadados definido na seção 2.2.2.9.