Suporte ao driver para orientação da câmera

À medida que diferentes fatores de forma dos dispositivos de computação são introduzidos, algumas das restrições físicas resultam em os sensores de câmera sendo montados em uma orientação não tradicional. Por isso, é necessário descrever corretamente para o sistema operacional e o aplicativo, como os sensores são montados para que o vídeo resultante possa ser renderizado/gravado corretamente.

A partir do Windows 10, versão 1607, todos os drivers de câmera devem especificar explicitamente a orientação da câmera, independentemente de a câmera estar instalada de acordo com os requisitos mínimos de hardware. Especificamente, um driver de câmera deve definir um campo recém-introduzido, Rotation, na estrutura de _PLD ACPI associada a uma interface do dispositivo de captura:

typedef struct _ACPI_PLD_V2_BUFFER {

    UINT32 Revision:7;
    UINT32 IgnoreColor:1;
    UINT32 Color:24;
    // …
    UINT32 Panel:3;         // Already supported by camera.
    // …
    UINT32 CardCageNumber:8;
    UINT32 Reference:1;
    UINT32 Rotation:4;      // 0 – Rotate by 0° clockwise
                            // 1 – Rotate by 45° clockwise (N/A to camera)
                            // 2 – Rotate by 90° clockwise
                            // 3 – Rotate by 135° clockwise (N/A to camera)
                            // 4 – Rotate by 180° clockwise
                            // 5 – Rotate by 225° clockwise (N/A to camera)
                            // 6 – Rotate by 270° clockwise
    UINT32 Order:5;
    UINT32 Reserved:4;

    //
    // _PLD v2 definition fields.
    //

    USHORT VerticalOffset;
    USHORT HorizontalOffset;
} ACPI_PLD_V2_BUFFER, *PACPI_PLD_V2_BUFFER;

Para a câmera, o campo Rotação em uma estrutura de _PLD ACPI especifica o número de graus ('0' para 0°, '2' para 90°, '4' para 180° e '6' para 270°) um quadro capturado é girado em relação à tela enquanto o display está em sua orientação nativa.

Com base no valor no campo Rotação , um aplicativo pode executar rotação adicional, se necessário, para renderizar os quadros capturados corretamente.

Valores de rotação

Para esses dispositivos cujas câmeras e telas compartilham o mesmo compartimento (ou invólucro), é possível que esses periféricos sejam montados em superfícies diferentes, com cada um deles girado por um grau fixo, mas arbitrário, em seu respectivo plano. Consequentemente, um aplicativo precisa de um mecanismo para descrever a relação espacial entre os dois periféricos, de modo que um quadro capturado possa ser transposto para a superfície de renderização na orientação correta.

Uma maneira de resolver o problema é usar a estrutura de _PLD ACPI que já tem os conceitos de superfície e graus de rotação definidos . Por exemplo, a estrutura _PLD já tem um campo de painel que especifica a superfície na qual um periférico reside:

Definição do campo de painel _PLD do ACPI (Rev. 5.0a)

Os dois diagramas a seguir ilustram a definição de cada painel visualmente:

Definições de painel para computadores desktop e a maioria dos dispositivos

Definições de painel para dispositivos dobráveis

Na verdade, o conceito de um "painel" de ACPI já é adotado pelo Windows em que:

• Uma interface do dispositivo de câmera é associada a uma estrutura de _PLD, e o campo Painel é configurado adequadamente quando um dispositivo de captura está montado estaticamente em um local fixo.

• Um aplicativo pode recuperar o painel no qual um dispositivo de captura reside chamando a propriedade Windows.Devices.Enumeration.DeviceInformation.EnclosureLocation.Panel .

A estrutura de _PLD ACPI também tem um campo de rotação definido da seguinte maneira:

Definição do campo de rotação _PLD do ACPI (Rev 5.0a)

Em vez de usar a definição acima como está, a refinamos ainda mais para evitar ambiguidade:

• Para a câmera, o campo Rotação em uma estrutura de _PLD ACPI especifica o número de graus ('0' para 0°, '2' para 90°, '4' para 180° e '6' para 270°) um quadro capturado é girado em relação à tela enquanto o display está em sua orientação nativa.

Paisagem Primária versus Retrato Primário

No Windows, é possível consultar a orientação de exibição nativa chamando a propriedade , Windows.Graphics.Display.DisplayInformation.NativeOrientation, que retorna Paisagem ou Retrato:

Não importa qual valor NativeOrientation retorna, o padrão de verificação de exibição lógica começa no canto superior esquerdo da exibição movendo-se da esquerda para a direita para baixo (consulte a Figura 5). Para aqueles dispositivos cuja orientação física padrão não é explicitamente definida, essa propriedade não apenas indica a localização do painel Top do ACPI, mas também fornece a relação espacial entre o buffer de saída da câmera e a superfície de renderização.

Observe que, ao contrário da câmera, a propriedade NativeOrientation não é baseada em ACPI e, portanto, não tem uma estrutura _PLD. Isso é verdadeiro mesmo se uma exibição for montada estaticamente em um dispositivo.

Ao montar em um dispositivo Portrait Primary, os drivers de câmera devem estar cientes de que a maioria dos aplicativos considerará que o dispositivo está fornecendo um buffer de saída de câmera em paisagem, independentemente da orientação real do buffer de saída da câmera. Por isso, recomendamos que os drivers de câmera gerem um buffer de câmera que tenha um deslocamento de orientação de 90 graus da NativeOrientation Portrait quando estiver em um dispositivo Portrait Primary. Isso permitirá que os aplicativos que estão executando essa rotação adicional em dispositivos no modo retrato corrijam a rotação para a orientação esperada. Isso pode ser verificado usando o Aplicativo de Câmera com Amostra de Rotação.

Montagem Offset

Os IHV/OEMs são altamente incentivados a evitar a montagem do sensor em um deslocamento de não 0 grau para manter a compatibilidade do aplicativo. Muitos aplicativos existentes e legados não sabem procurar a tabela PLD da ACPI, nem tentarão corrigir o desvio de graus não zero. Consequentemente, para esses aplicativos, o vídeo resultante será renderizado incorretamente.

Nos casos em que os IHV/OEMs não conseguem montar o sensor na orientação de 0 grau, conforme descrito acima, as seguintes etapas de mitigação são recomendadas na ordem de preferência:

1. Corrija automaticamente a orientação de não 0 grau dentro do Driver da Câmera (no modo kernel com o driver de miniporto de fluxo AV ou no modo de usuário usando um plug-in como o Dispositivo MFT ou MFT0) para que os quadros de saída resultantes estejam na orientação de 0 grau.

2. Declare uma orientação diferente de 0 graus por meio da tag FSSensorOrientation, para que o pipeline de processamento da câmera possa corrigir a imagem capturada.

3. Declare a orientação diferente de 0 grau na tabela PLD da ACPI, conforme descrito anteriormente.

Tipos de mídia compactados/codificados

Para tipos de mídia compactados e/ou codificados (como MJPG, JPEG, H264, HEVC), o pipeline correto não pode ser usado. Por isso, tipos de mídia compactados/codificados serão filtrados se o FSSensorOrientation estiver definido como um valor diferente de zero.

No caso de tipos de mídia MJPG (como aqueles de uma câmera UVC), o pipeline do Frame Server fornece um tipo de mídia decodificado automaticamente (NV12 ou YUY2 para aplicativos baseados em DShow). O tipo de mídia autocodificado e corrigido será apresentado, mas o formato MJPG original não será.

[! OBSERVAÇÃO!] Se tipos de mídia compactados/codificados precisarem ser expostos a aplicativos, os IHV/ODMs não deverão utilizar a correção FSSensorOrientation. Em vez disso, a correção deve ser feita pelo driver da câmera (no modo kernel por meio do driver do AV Stream ou no modo de usuário via DMFT/MFT0).

Correção automática através do Miniport/Device MFT/MFT0 do AV Stream

O cenário recomendado, caso os sensores não possam ser montados em um ângulo de 0 grau, é que o driver de miniporta do AV Stream (ou os plug-ins do modo usuário na forma de DMFT ou MFT0) corrija o quadro capturado resultante, para que ele seja exposto ao pipeline em um ângulo de 0 grau.

Ao corrigir o quadro de vídeo do AV Stream Miniport e/ou do plug-in MFT/MFT0 do dispositivo, a declaração de tipo de mídia resultante deve ser baseada no quadro corrigido. Se o sensor estiver montado com um deslocamento de 90 graus, de modo que o vídeo resultante tenha uma relação de aspecto de 9:16 a partir do sensor, mas o vídeo corrigido fique com 16:9, o tipo de mídia deve declarar a relação de aspecto de 16:9.

Isso inclui as informações de passo resultantes. Isso é necessário, pois o componente responsável por fazer a correção é controlado pelo IHV/OEM e o pipeline da câmera não tem visibilidade do quadro de vídeo, exceto depois que ele foi corrigido.

É altamente recomendável que a correção seja feita no modo de usuário e o contrato de API entre o pipeline e o plug-in de modo de usuário deve ser seguido. Especificamente, ao usar o DMFT ou o MFT0, quando o IMFDeviceTransform::P rocessMessage ou IMFTransform::P rocessMessage é invocado com uma mensagem MFT_MESSAGE_SET_D3D_MANAGER, o plug-in de modo de usuário deve seguir a seguinte diretriz:

• Se nenhum gerenciador D3D for fornecido (o ulParam da mensagem é 0), o plug-in de modo de usuário NÃO deverá invocar nenhuma operação de GPU para lidar com a correção de rotação. E o quadro resultante deve ser fornecido na memória do sistema.
• Se o gerenciador D3D for fornecido (o ulParam da mensagem é o IUnknown de um Gerenciador DXGI), esse Gerenciador DXGI deverá ser usado para correção de rotação e o quadro resultante deve ser memória GPU.
• O plug-in de modo de usuário também deve lidar com a mensagem do gerenciador D3D durante o runtime. Quando a mensagem MFT_MESSAGE_SET_D3D_MANAGER for emitida, o próximo quadro produzido pelo plug-in deverá corresponder ao tipo de memória solicitado (ou seja, GPU se o Gerenciador DXGI tiver sido fornecido, ou CPU se não).
• Quando o driver de fluxo de AV (ou o plugin de modo usuário) manipula a correção de rotação, o campo de Rotação da estrutura PLD da ACPI deve ser configurado para 0.

Declarar por FSSensorOrientation

; Defines the sensor mounting orientation offset angle in
; degrees clockwise.
FSSensorOrientation: REG_DWORD: 90, 180, 270

Declarando a orientação não grau 0 do sensor por meio da tag de registro FSSensorOrientation, o pipeline da câmera pode corrigir o quadro capturado antes de o apresentar ao aplicativo.

O pipeline otimizará a lógica de rotação aproveitando os recursos de GPU ou CPU com base no caso de uso e na solicitação/cenário do aplicativo.

Rotação de PLD do ACPI

O campo Rotação da estrutura DE PLD do ACPI deve ser 0. Isso é para evitar aplicativos confusos que podem usar as informações de PLD para corrigir o quadro.

Informações de tipo de mídia

O tipo de mídia apresentado pelo driver deve ser o tipo de mídia não corrigido. Ao informar o pipeline da câmera do deslocamento de não 0 graus usando a entrada FSSensorOrientation, as informações de tipo de mídia apresentadas pelo sensor devem ser o tipo de mídia não corrigido. Por exemplo, se o sensor for montado no sentido horário de 90 graus, com isso, em vez da proporção de aspecto 16:9, o vídeo resultante é 9:16, o tipo de mídia de proporção 9:16 deve ser apresentado ao pipeline da câmera.

Isso é necessário para garantir que o pipeline possa configurar corretamente o processo de contra-rotação: o pipeline precisa do tipo de mídia de entrada e do tipo de mídia de saída desejado do aplicativo.

Isso inclui as informações passo a passo. As informações de stride devem ser apresentadas para o tipo de mídia não corrigido no pipeline da câmera.

Subchave do registro

A entrada do registro FSSensorOrientation deve ser publicada no nó da Interface de Dispositivo. A abordagem recomendada é declarar isso como uma diretiva "AddReg" durante a declaração da diretiva "AddInterface" dentro do INF do driver de câmera.

Os dados apresentados no FSSensorOrientation devem ser um REG_DWORD e os únicos valores válidos aceitos serão 90, 180 e 270. Qualquer outro valor será tratado como deslocamento de 0 graus (ou seja, ignorado).

Cada valor representa a orientação do sensor em graus no sentido horário. O pipeline da câmera corrigirá o quadro de vídeo resultante ao girar o vídeo pela mesma quantidade no sentido horário: ou seja, uma declaração no sentido horário de 90 graus resultará em uma rotação no sentido horário de 90 graus para levar o quadro de vídeo resultante de volta ao deslocamento de 0 grau.

Descritor do SISTEMA OPERACIONAL MS 1.0

Para câmeras baseadas em USB, o FSSensorOrientation também pode ser divulgado por meio de descritores MSOS.

O Ms OS Descriptor 1.0 tem dois componentes:

• Uma seção de cabeçalho de comprimento fixo
• Uma ou mais seções de propriedades personalizadas de comprimento variável, que segue a seção de cabeçalho

Seção de cabeçalho MS OS DESCRIPTOR 1.0

A Seção Cabeçalho descreve uma única propriedade personalizada (Perfil de Autenticação Facial).

Seção da Propriedade do Descritor MS OS Personalizado 1.0

Descritor do SISTEMA OPERACIONAL MS 2.0

O Descritor Estendido MSOS 2.0 pode ser usado para definir os valores do Registro para adicionar suporte a FSSensorOrientation. Isso é feito usando o Descritor de Propriedade do Registro do Microsoft OS 2.0.

Para a entrada do registro UVC-FSSensorOrientation, o seguinte mostra um conjunto de descritores MSOS 2.0 de exemplo:

UCHAR Example2_MSOS20DescriptorSet_UVCFSSensorOrientationForFutureWindows[0x3C] =
{
    //
    // Microsoft OS 2.0 Descriptor Set Header
    //
    0x0A, 0x00,                 // wLength - 10 bytes
    0x00, 0x00,                 // MSOS20_SET_HEADER_DESCRIPTOR
    0x00, 0x00, 0x0?, 0x06,     // dwWindowsVersion – 0x060?0000 for future Windows version
    0x4A, 0x00,                 // wTotalLength – 74 bytes

    //
    // Microsoft OS 2.0 Registry Value Feature Descriptor
    //
    0x40, 0x00,                 // wLength - 64 bytes
    0x04, 0x00,                 // wDescriptorType – 4 for Registry Property
    0x04, 0x00,                 // wPropertyDataType - 4 for REG_DWORD_LITTLE_ENDIAN
    0x32, 0x00,                 // wPropertyNameLength – 50 bytes
    0x55, 0x00, 0x56, 0x00,     // Property Name - "UVC-FSSensorOrientation"
    0x43, 0x00, 0x2D, 0x00,
    0x46, 0x00, 0x53, 0x00,
    0x53, 0x00, 0x65, 0x00,
    0x6E, 0x00, 0x73, 0x00,
    0x6F, 0x00, 0x72, 0x00,
    0x4F, 0x00, 0x72, 0x00,
    0x69, 0x00, 0x65, 0x00,
    0x6E, 0x00, 0x74, 0x00,
    0x61, 0x00, 0x74, 0x00,
    0x69, 0x00, 0x6F, 0x00,
    0x6E, 0x00, 0x00, 0x00,
    0x00, 0x00,
    0x04, 0x00,                 // wPropertyDataLength – 4 bytes
    0x5A, 0x00, 0x00, 0x00      // PropertyData – 0x0000005A (90 degrees offset)
}

Declarar por meio de informações de PLD do ACPI

Como uma opção de último recurso, as informações de PLD podem ser aproveitadas conforme descrito acima para indicar ao aplicativo que o quadro de vídeo deve ser corrigido antes de ser renderizado/codificado. No entanto, conforme indicado, muitos aplicativos existentes não usam as informações de PLD nem lidam com a rotação de quadros, portanto, haverá cenários em que os aplicativos podem não ser capazes de renderizar o vídeo resultante corretamente.

As seguintes figuras ilustram os valores do campo rotação de _PLD para cada configuração de hardware:

Rotação: 0 grau no sentido horário

Na figura acima:

• A imagem à esquerda ilustra a cena a ser capturada.

• A imagem no meio ilustra como uma cena é exibida por um sensor CMOS cuja ordem de leitura física começa do canto inferior esquerdo movendo-se da esquerda para a direita para cima.

• A imagem à direita representa a saída do driver da câmera. Neste exemplo, o conteúdo do buffer de mídia pode ser renderizado diretamente quando a exibição está em sua orientação nativa, sem rotação adicional. Consequentemente, o campo ACPI _PLD Rotação tem um valor de 0.

Rotação: 90 graus no sentido horário

Nesse caso, o conteúdo do buffer de mídia é girado em 90 graus no sentido horário em comparação com a cena original. Como resultado, o campo de rotação de _PLD ACPI tem um valor de 2.

Rotação: 180 graus no sentido horário

Nesse caso, o conteúdo do buffer de mídia é girado em 180 graus no sentido horário em comparação com a cena original. Como resultado, o campo de Rotação _PLD do ACPI tem um valor de 4.

Rotação: 270 graus no sentido horário

Nesse caso, o conteúdo do buffer de mídia é girado em 270 graus no sentido horário em comparação com a cena original. Como resultado, o campo ACPI _PLD Rotação tem um valor de 6.