Especificação de extensões da Microsoft para a Classe de Vídeo USB 1.5

1 Visão geral

1.1 Resumo

As extensões da Microsoft para a especificação classe de vídeo USB permitem novos controles, bem como 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 da Classe de Vídeo USB (UVC) estará disponível para pontos de extremidade ISOCH e BULK. No entanto, no caso do ponto de extremidade BULK, o tamanho dos metadados será limitado a 240 bytes (devido ao fato de que 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ó estará disponível para cargas baseadas em quadros.

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

Os metadados do UVC serão aceitos. Cada IHV/OEM que precisa de suporte a metadados deve habilitá-lo por meio de um arquivo INF personalizado.

Os metadados do UVC só darão suporte à memória alocada pelo sistema. Não haverá suporte para superfícies VRAM ou DX.

2 Visão geral da arquitetura

2.1 Descrição

2.2.1 Descoberta de funcionalidade por meio do INF

2.2.1.1 Captura de Imagem Ainda – Método 2

Alguns dispositivos UVC existentes podem não dar suporte ao Método 2 descrito na seção 2.4.2.4 (Captura de Imagem Ainda) da classe UVC 1.5 specification.pdf que podem ser baixadas no site de especificação da Classe de Vídeo USB .

No Windows 10, versão 1607 e anteriores, o pipeline de captura não aproveitava 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 utilizam esse método devem usar um arquivo INF personalizado para o driver da câmera, mas um INF personalizado é necessário para que o hardware especificado habilite a captura de imagem ainda do Método 2).

Observação: o driver da câmera pode ser baseado no windows USBVIDEO.SYS ou pode ser baseado 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 for definida como Habilitada (0x1), o pipeline de captura aproveitará o Método 2 para Captura de Imagem Ainda (supondo que o firmware também anuncie suporte para o Método 2, conforme especificado 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 MS_CAMERA_CONTROL_XU GUID (conhecida 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 abrigará 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 specification.pdfde classe UVC 1.5 para obter definições de D3, D4, GET_INFO e assim por diante.

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

GET_LEN solicitação deve relatar o comprimento máximo da carga para esse controle (wLength).

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

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

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

GET_DEF e GET_CUR solicitações 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 depois de definir todos os campos.

A tabela a seguir mapeia os seletores de controle para Microsoft-XU para seus respectivos valores e a posição de bit para o campo bmControls no Descritor de Unidade de Extensão:

2.2.2.1 Controles canceláveis

Um controle Cancelável é definido aqui aproveitando a funcionalidade Desatualizar automaticamente.

GET_INFO solicitação deve relatar tal controle como um Controle de Autenticação Automática (por exemplo, d3 bit deve ser definido como 1), mas não como um controle assíncrono (por exemplo, D4 bits deve ser definido como 0).

Para esse controle, uma solicitação SET_CUR pode ser emitida para definir um novo valor (uma solicitação SET_CUR(NORMAL) em que bmOperationFlags:D0 bit está definido como 0) ou cancelar uma solicitação de SET_CUR(NORMAL) anterior (uma solicitação SET_CUR(CANCEL) em que bmOperationFlags:D0 bit está 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 ou 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 gerado quando as novas configurações são aplicadas ou quando uma solicitação SET_CUR(CANCEL) chega; até que essa interrupção chegue, a solicitação SET_CUR(NORMAL) será considerada em andamento. Quando uma solicitação SET_CUR(NORMAL) estiver em andamento, solicitações adicionais de SET_CUR(NORMAL) para esse controle específico resultarão em uma falha. Uma solicitação SET_CUR(CANCEL) sempre terá êxito. Se não houver nada para cancelar, o dispositivo simplesmente não fará nada.

A carga 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, convergência aconteceu) e definidas como 1 se as configurações não foram aplicadas devido a uma solicitação SET_CUR(CANCEL) que veio após a solicitação SET_CUR(NORMAL) (por exemplo, a convergência ainda não aconteceu).

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.

Esse controle deve funcionar como um Controle Cancelável (consulte a seção 2.2.2.1 para GET_INFO requisitos de solicitação e comportamento funcional de SET_CUR solicitação).

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

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

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

• Entre os bits D0, D1 e D8, somente um bit pode ser definido; nenhum deles sendo definido também será válido se d2 bit estiver definido.

• Entre D16, D17, D18, D19 e D20, somente um bit pode ser definido; nenhum deles sendo definido também é válido.

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

• D2 é incompatível com D1 e D8.

• D2 é 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.

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

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

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

Para solicitações de 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 de EV

Esse controle permite que o software host especifique as configurações de compensação de 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.

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

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

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

GET_DEF, GET_CUR, SET_CUR solicitações devem seguir as definições na 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, GET_DEF solicitação deve ter dwValue definido como 0.

2.2.2.5 Controle de equilíbrio branco

Esse controle permite que o software host especifique as configurações de equilíbrio 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.

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

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

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

GET_DEF requisito: o padrão para bmControlFlags deve ser D0 definido como 1 e dwValueFormat , bem como dwValue definido como 0.

Para solicitações de 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 dá suporte a modos de streaming que são usados para autenticação facial. O suporte para esse controle implica que a câmera é capaz de autenticação facial. Caso contrário, não haverá suporte para esse controle.

Esse controle só é aplicável a câmeras que podem produzir dados Infra-Red (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).

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

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

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

Exemplo:

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

A saída para GET_MAX solicitação deve ser a seguinte:

A saída para GET_DEF solicitação deve ser a seguinte:

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

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

2.2.2.7 Controle de Extrínsecos 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. Assim, os dados obtidos para cada ponto de extremidade aparecerão como atributo MFStreamExtension_CameraExtrinsics no repositório de atributos para o fluxo correspondente (obtidos usando a chamada IMFDeviceTransform::GetOutputStreamAttributes).

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

GET_DEF solicitação deve listar todos os pontos de extremidade que têm as informações extrínsecas disponíveis.

Exemplo:

Vamos supor que uma câmera tenha três interfaces de streaming de vídeo com números 0x03, 0x05 e 0x08 respectivamente, em que a interface de streaming de vídeo 0x05 dá suporte à captura de imagem ainda usando o método 2, além da captura de vídeo compatível com todas as interfaces de streaming de vídeo. Entre essas interfaces de streaming, vamos supor que interfaces de streaming 0x05 e 0x08 tenham informações de extrínsecos disponíveis enquanto a interface de streaming 0x03 não tem as informações de extrínsecos disponíveis.

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

2.2.2.8 Controle de Intrínsecos 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. Assim, os dados obtidos para cada ponto de extremidade aparecerão como atributo MFStreamExtension_PinholeCameraIntrinsics no repositório de atributos para o fluxo correspondente (obtidos usando a chamada IMFDeviceTransform::GetOutputStreamAttributes).

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

GET_DEF solicitação deve listar todos os pontos de extremidade que têm as informações intrínsecas disponíveis.

Exemplo:

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

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

2.2.2.9 Controle de metadados

Esse controle permite que o software host consulte e controle 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 é mapeado para KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA pelo driver da câmera.

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

• GET_MIN, GET_DEF solicitações devem relatar o campo dwValue definido como 0.
• GET_RES solicitação deve relatar o campo dwValue para ser o mesmo valor relatado por GET_MAX solicitação.
• Quando uma solicitação de SET_CUR é recebida com dwValue definido como 0, a câmera não deve produzir metadados. Quando uma solicitação de SET_CUR é recebida com dwValue definido como o mesmo valor relatado por GET_MAX solicitação, a câmera pode produzir metadados e o tamanho desses metadados não pode exceder dwValue para qualquer quadro.

Se SET_CUR solicitação não tiver suporte do firmware, o seguinte se aplicará:

• GET_MIN, GET_DEF solicitações deverão relatar o campo dwValue para ser o mesmo valor relatado por GET_MAX solicitação.
• GET_RES solicitação 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 por GET_MAX solicitação , vezes 1024 bytes menos do tamanho de uma carga de metadados UsbVideoHeader , para qualquer quadro.
• Um conteúdo de metadados UsbVideoHeader é o sizeof(KSCAMERA_METADATA_ITEMHEADER) + sizeof(KSTREAM_UVC_METADATA) ou 24 bytes.

Os metadados produzidos devem estar em conformidade com os metadados de formato padrão da Microsoft descritos na seção 2.2.3.

2.2.2.10 Controle de tocha DE IR

Esse controle fornece um meio flexível para o hardware de LED do IR relatar até que ponto ele pode ser controlado e fornece a capacidade de controlá-lo. 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 ajustando a energia para uma lâmpada IR conectada à câmera.

Esse controle é mapeado para KSPROPERTY_CAMERACONTROL_EXTENDED_IRTORCHMODE pelo driver da câmera.

O seguinte se aplica:

• GET_LEN solicitação deve relatar um valor de 8.
• GET_INFO solicitação deve relatar um 3. Esse valor indica um controle síncrono que dá suporte a GET_CUR e SET_CUR.
• GET_MIN solicitação deve relatar o campo dwMode definido como 0 e dwValue definido como um valor que indica potência mínima. Um nível de energia de 0 pode indicar OFF, mas o nível mínimo de energia operacional não precisa ser 0.
• GET_RES solicitação deve relatar o campo dwMode definido como 0 e dwValue definir um como um número menor ou igual a GET_MAX(dwValue) – GET_MIN(dwValue) e de modo que GET_MAX(dwValue) – GET_MIN(dwValue) é uniformemente divisível por esse valor. dwValue pode não ser zero (0).
• GET_MAX solicitação 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 tem suporte e deve ter pelo menos um outro bit definido, dando suporte a um estado ativo. dwValue deve ser definido como um valor que indica a potência normal.
• GET_DEF solicitação 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 (ALTERNANDO). dwValue deve ser definido como o nível de energia normalmente usado para o controle FaceAuth. dwValue é definido pelo fabricante.
• GET_CUR solicitação 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 de SET_CUR for recebida, a Tocha do IR definirá a iluminação como uma intensidade de taxa de prora usando o modo de operação solicitado.

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

A única finalidade dos metadados é indicar se um quadro está iluminado ou não. Esses são os mesmos metadados exigidos pelo KSPROPERTY_CAMERACONTROL_EXTENDED_FACEAUTH_MODE DDI e o MSXU_FACE_AUTHENTICATION_CONTROL definidos na seção 2.2.2.6.

2.2.2.11 Controle de Janela Digital

Janela Digital especifica o campo de exibição e zoom da câmera enquanto a câmera está transmitindo. Esse controle é um substituto potencial para Pan, Tilt e Zoom. Esse controle só se aplica enquanto a câmera está transmitindo ativamente.

Esse controle está disponível para todos os tipos de câmeras 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 origem dos dados de pixel usados pelo ISP. Isso inclui os pinos de captura do Método 2 e do Método 3.

Esse controle é mapeado para KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW pelo driver da câmera de caixa de entrada.

O seguinte se aplica:

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

• GET_INFO solicitação deve relatar um 3. Esse valor indica um controle síncrono que dá suporte a GET_CUR e SET_CUR.

• GET_MIN solicitação deve relatar o campo dwMode definido como 0, OriginX e OriginY definidos como 0.0 e WindowSize definido como 1.0. No momento, essa solicitação não é utilizado.

• GET_RES solicitação deve relatar o campo dwMode definido como 0, OriginX e OriginY definidos como 0.0 e WindowSize definido como 1.0. No momento, essa solicitação não é utilizado.

• GET_MAX solicitação deve relatar o campo dwMode definido com o bit D0 definido para identificar os recursos desse controle. Um valor 0 indica que há suporte apenas para o modo manual. Um valor de 1 indica que há suporte para o modo de enquadramento facial automático. No entanto, o restante desses campos não são utilizados, recomendamos que OriginX e OriginY sejam definidos como 0.0 e WindowSize definido como 1.0.

• GET_DEF solicitação 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.

• GET_CUR solicitação 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 de SET_CUR é recebida, a câmera ajustará seu campo de exibiçã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 abrange totalmente o rosto dominante na cena e o OriginX, OriginY e WindowSize passados são ignorados. Se nenhum rosto for encontrado, a janela padrão será usada.

• Todas as alterações na janela digital devem ser refletidas no conteúdo de metadados de cada amostra.

• As alterações na janela digital não precisam ser imediatamente efetivas, mas o controle deve responder imediatamente. As alterações na janela digital devem ser relatadas na carga de metadados do quadro assim que entrarem em vigor.

2.2.2.12 Controle de Configuração de Janela Digital

O controle Tampas 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 uma funcionalidade.

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

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

Esse controle é mapeado para KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW_CONFIGCAPS pelo driver da câmera de caixa de entrada.

O seguinte se aplica:

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

• GET_INFO solicitação deve relatar um 1. Esse valor indica um controle síncrono que dá suporte apenas a GET_CUR.

• GET_CUR solicitação deve relatar uma matriz de recursos. Os campos da estrutura de funcionalidade são definidos acima.

• GET_MIN, GET_MAX, solicitações de GET_RES e GET_DEF não são usadas, mas devem retornar os mesmos valores que GET_CUR.

• não há suporte para solicitações SET_CUR.

2.2.2.13 Controle hdr de vídeo

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

Esse controle é mapeado para KSPROPERTY_CAMERACONTROL_EXTENDED_VIDEOHDR pelo driver da câmera.

O seguinte se aplica:

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

• GET_INFO solicitação deve relatar um valor 3. Esse valor indica um controle síncrono que dá suporte a GET_CUR, SET_CUR.

• GET_CUR solicitação deve relatar o campo dwMode definido como o modo operacional atual.

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

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

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

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

2.2.3 Metadados

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

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

StandardFormatMetadata<PinIndex>: REG_DWORD: 0x0 (sem suporte) para 0x1 (com suporte)

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

2.2.3.1 Metadados de formato Standard da Microsoft

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

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 definição de enumeração a seguir que contém identificadores bem definidos, bem como 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(Carga de Metadados).

2.2.3.2 Metadados de formato padrão gerados por firmware de pacotes de quadro de vídeo USB

Durante uma transferência por 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 UVC. Cada Cabeçalho de Carga do UVC é definido pela especificação de carga baseada em quadro do driver de classe de vídeo USB:

Cabeçalho de carga

Veja a seguir uma descrição do formato de cabeçalho de conteúdo para formatos baseados em quadro.

Campo HLE (comprimento do cabeçalho)

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

Campo de cabeçalho do campo de bits

FID: identificador de quadro

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

EOF: fim do quadro

• Esse bit indica o fim de um quadro de vídeo e é definido no último exemplo 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 quadro e é opcional.

PTS: carimbo de data/hora da apresentação

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

SCR: Referência do relógio de origem

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

RES: Reservado.

• Defina como 0.

STI: Imagem Parada

• Esse bit, quando definido, identifica um exemplo de vídeo como pertencente a uma imagem parada.

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/Hora da Apresentação, Tamanho: 4 bytes, Valor: Número

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

SCR: Referência do 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 conteúdo de imagem parada e vídeo na especificação definição de classe de dispositivo USB para dispositivos de vídeo .

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

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

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/hora do UVC (gerados pelo driver UVC) seguidos por itens de metadados gerados por firmware e eles são dispostos da seguinte maneira:

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 estarão presentes em todos os quadros emitidos pelo firmware.

2.2.3.4.1 MetadataId_CaptureStats

O formato de metadados para esse 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 são preenchidos e têm dados válidos. O campo Sinalizadores não deve variar de quadro para quadro. Atualmente, os seguintes sinalizadores sã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 100ns, aplicado ao sensor quando o quadro foi capturado. Isso aparecerá como MF_CAPTURE_METADATA_EXPOSURE_TIME de atributo 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. Eles aparecerão como MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION de atributo no exemplo de MF correspondente.

O campo IsoSpeed contém o valor de velocidade ISO aplicado ao sensor quando o quadro foi capturado. Isso é sem unidade. Isso aparecerá como MF_CAPTURE_METADATA_ISO_SPEED de atributo no exemplo de MF correspondente.

O campo FocusState contém o estado de foco atual que pode obter um dos valores definidos na enumeração KSCAMERA_EXTENDEDPROP_FOCUSSTATE. Isso aparecerá como MF_CAPTURE_METADATA_FOCUSSTATE de atributo 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. Esse é o mesmo valor que pode ser consultado de KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS em uma chamada GET. Isso aparecerá como MF_CAPTURE_METADATA_LENS_POSITION de atributo no exemplo de MF correspondente.

O campo WhiteBalance contém o saldo em branco aplicado ao sensor quando o quadro foi capturado, que é um valor em Kelvin. Isso aparecerá como MF_CAPTURE_METADATA_WHITEBALANCE de atributo no exemplo de MF correspondente.

O campo Flash contém um valor booliano com 1 que significa flash ativado e 0 significa flash off, quando o quadro foi capturado. Isso aparecerá como MF_CAPTURE_METADATA_FLASH de atributo no exemplo de MF correspondente.

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

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

O campo SceneMode contém o modo de cena aplicado ao quadro capturado, que é um sinalizador de KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX de 64 bits. Isso aparecerá como MF_CAPTURE_METADATA_SCENE_MODE de atributo 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 numerador no 32 bits superior e um valor de denominador no 32 bits inferior. Isso aparecerá como MF_CAPTURE_METADATA_SENSORFRAMERATE de atributo no exemplo de MF correspondente.

2.2.3.4.2 MetadataId_CameraExtrinsics

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

2.2.3.4.3 MetadataId_CameraIntrinsics

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

2.2.3.4.4 MetadataId_FrameIllumination

O formato de metadados para esse 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 são definidos:

#define KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON 0x00000001

Se um quadro foi capturado quando a iluminação estava ativada, o sinalizador KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON deve ser definido. Caso contrário, esse sinalizador não deverá 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 ativada 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 no primeiro e no último conteúdo UVC emitidos pela câmera para construir esse quadro.

Esse conteúdo não deve ser enviado por um dispositivo.

Esse conteúdo de metadados é exclusivo porque é o único conteúdo de metadados gerado diretamente pelo driver de classe de vídeo USB a partir de informações obtidas de cabeçalhos de conteúdo compatíveis com UVC.

Esse conteúdo é anexado ao buffer de metadados de cada quadro.

Se o dispositivo der suporte a metadados padronizados, ele deverá incluir o espaço necessário para armazenar essa carga em seus requisitos de buffer, conforme relatado pelo controle de metadados definido na seção 2.2.2.9.