Aplicativos complementares da câmera

Artigo
12/19/2024

Este artigo descreve aplicativos complementares, um recurso de extensibilidade para fabricantes de câmeras criarem aplicativos personalizados que podem configurar a câmera e ajustar configurações de imagem padrão.

Introdução

O Windows 11 fornece uma estrutura de aplicativos complementares da câmera que permite a fabricantes desenvolver aplicativos com os seguintes recursos:

Capacidade de exibir e/ou modificar as mesmas configurações de valor padrão com suporte da página de configurações da câmera (por exemplo, Brilho, Contraste, Efeitos de plano de fundo e assim por diante).
Capacidade de registrar, atualizar ou excluir configurações de valor padrão para outros controles de câmera conhecidos pelo Windows, mas que não são expostos por meio da página de configurações da câmera (por exemplo, o controle Hue).
Capacidade de registrar, atualizar ou excluir configurações de valor padrão para controles de câmera proprietários do fabricante (por exemplo, o controle liga/desliga para o efeito de ajuste de iluminação personalizado do fabricante de uma câmera).

Quando uma câmera registra um aplicativo complementar associado, uma entrada é adicionada à página de configurações da câmera. Se o aplicativo estiver instalado, ele poderá ser iniciado na página de configurações da câmera; caso contrário, um link para a Microsoft Store será exibido para baixá-lo.

Os aplicativos complementares têm acesso especial a uma API que permite registrar, atualizar ou excluir valores padrão, como a página de configurações da câmera.

Terminologia e pré-requisitos

Termo	Definição
Aplicativo complementar	Um aplicativo personalizado desenvolvido pelo fabricante da câmera que permite a configuração e o gerenciamento de uma câmera, além da página de configurações da câmera.
valor atual	O valor de um controle de câmera que está ativo no momento no ISP da câmera e é mantido na memória temporária da câmera.
Valor padrão	Um valor inicial de um controle de câmera que é armazenado em disco e salvo para uma câmera específica, para uma conta de usuário específica, em um PC específico.
HSA	Aplicativo de Suporte de Hardware, uma estrutura com suporte da Microsoft para baixar e instalar aplicativos associados a hardware da Microsoft Store automaticamente quando o dispositivo está conectado.
NPU	Unidade de Processamento Neural, hardware dedicado criado para processar cargas de trabalho de inteligência artificial com alto rendimento e eficiência.
Efeitos do Windows Studio	Uma coleção de efeitos de vídeo disponíveis em PCs Windows selecionados com NPUs.
UVC	Classe de vídeo USB, a interface padronizada para controle e streaming de câmeras conectadas por USB.

Requisitos do aplicativo complementar

Os aplicativos complementares devem ser aplicativos empacotados com uma identidade de pacote. O aplicativo complementar também deve ser lançado na Microsoft Store, permitindo que a página de configurações da câmera oriente os clientes até a loja para instalar o aplicativo, caso ainda não esteja instalado.

Aplicativos de área de trabalho tradicionais sem uma identidade de pacote não podem ser usados como um aplicativo complementar.

Aplicativos complementares como HSAs

Os aplicativos complementares não precisam ser configurados como um Aplicativo de Suporte de Hardware, mas isso é altamente recomendável. HSAs são aplicativos especiais na Microsoft Store associados a um dispositivo de hardware específico. Quando esse dispositivo está conectado a um computador, o HSA é baixado e instalado automaticamente da Microsoft Store quando disponível.

Associar um aplicativo complementar a uma câmera

O fabricante de uma câmera pode associar um aplicativo complementar preenchendo uma chave de propriedade de dispositivo específica com o nome da família do pacote (PFN) do aplicativo complementar:

Nome	Tipo	Dados
SCSVCamPfn	REG_SZ	<PFN>

Para identificar o PFN do aplicativo complementar, execute Get-AppxPackage do PowerShell, por exemplo:

Get-AppxPackage -Name CompanionAppName

Para associar o aplicativo complementar a uma câmera, use um descritor MSOS em uma câmera UVC ou a diretiva AddReg no INF do driver da câmera. Por exemplo, usando o arquivo INF:

[SocCaptureSim.RearCamera.AddReg]

HKR,,SCSVCamPfn,,%AppPFN%

...

[Strings]

AppPFN="Contoso.CameraCompanion_xxxxxxxx00000"

Quando um aplicativo complementar é associado a uma câmera, a página de configurações da câmera inclui um link para o aplicativo complementar com o título "Configurações relacionadas" da página de configurações específicas da câmera.

Se o aplicativo complementar já estiver instalado, um link será exibido para "Abrir {nome do aplicativo complementar}". Quando clicado, o aplicativo é iniciado.

Se o aplicativo complementar ainda não estiver instalado, será exibido um link para iniciar a Microsoft Store para baixar e instalar o aplicativo.

Uma câmera só pode ter um aplicativo complementar associado a ela.

Iniciar um aplicativo complementar na página de configurações da câmera

Quando a página de configurações da câmera inicia o aplicativo complementar, o link simbólico da câmera é passado como contexto por meio dos argumentos Application.OnLaunched.

Argument	Tipo	Dados
cameraId	String	Link simbólico

Essa funcionalidade permite que o aplicativo complementar exiba as configurações corretas da câmera nos seguintes cenários:

Um único aplicativo complementar oferece suporte a várias câmeras em um único sistema (por exemplo, um aplicativo fornecido por OEM dá suporte às câmeras dianteira e traseira em um tablet).
Um cliente tem duas câmeras iguais (ou da mesma marca) conectadas ao sistema que são gerenciadas pelo mesmo aplicativo complementar.

Iniciar a página de configurações da câmera a partir de um aplicativo complementar

Um aplicativo complementar pode iniciar a página de configurações da câmera do Windows usando um URI de link profundo. Para obter mais informações, consulte Launch the camera settings página.

Configurar valores padrão de aplicativos complementares

Um aplicativo complementar pode usar a API IMFCameraConfigurationManager para definir a configuração de valor padrão do usuário atual. Essa API permite que o aplicativo complementar leia valores padrão configurados (por exemplo, os valores padrão definidos pelo usuário usando a página de configurações da câmera), modifique valores padrão, registre novos valores padrão ou remova valores padrão salvos.

Os valores padrão são registrados no banco de dados do sistema como um par de um GUID de propriedade KS e o valor correspondente. Isso permite que a arquitetura seja agnóstica à definição da Propriedade KS. Essa flexibilidade permite que um aplicativo complementar defina, edite ou exclua valores padrão para uma das seguintes configurações:

Configurações que também podem ser definidas usando a página de configurações da câmera (por exemplo, Brilho, Contraste, Efeitos de plano de fundo e assim por diante)
Configurações para outros controles de câmera conhecidos pelo Windows, mas que não são expostos por meio da página de configurações da câmera (por exemplo, o controle Hue)
Configurações para controles de câmera proprietários do fabricante (por exemplo, o controle liga/desliga para o efeito de ajuste de iluminação personalizado do fabricante de uma câmera)

Configurar o brilho a partir de um aplicativo complementar

Existem maneiras de uma câmera controlar o brilho efetivo da imagem capturada. Por exemplo, pode-se aumentar o brilho aplicando um ganho simples à imagem, ou aumentando o tempo de exposição da câmera.

O Windows oferece suporte a um controle de brilho herdado (KSPROPERTY_VIDEOPROCAMP_BRIGHTNESS) que foi projetado com controles de ganho simples em mente. O Windows também oferece suporte a um controle de compensação de exposição (KSPROPERTY_CAMERACONTROL_EXTENDED_EVCOMPENSATION) criado para comandar um desvio de valor de exposição positivo ou negativo para o algoritmo de Exposição Automática de uma câmera.

Independentemente de qual controle de brilho é usado por uma câmera, ele deve ser implementado na câmera de modo que, quando "centralizado", o brilho seja neutro, e que o cliente possa aplicar um deslocamento aumentando ou diminuindo o valor. Para obter a melhor qualidade de imagem, é altamente recomendável que as câmeras ofereçam suporte ao controle de compensação de exposição para que, se um cliente ajustar o controle de brilho na página de configurações da câmera ou em um aplicativo complementar, a câmera seja comandada a aplicar um desvio positivo ou negativo fixo à exposição, sejam quais forem as condições de iluminação, a qualquer momento.

Para saber mais, confira a página de configurações da câmera para conferir o comportamento do controle de brilho na página de configurações da câmera com base no controle implementado pela câmera. Se um aplicativo complementar também oferecer um controle deslizante de brilho, será essencial replicar a lógica para garantir a sincronização entre o controle deslizante de brilho na página de configurações da câmera e o aplicativo complementar.

O exemplo de aplicativo complementar vinculado a seguir inclui uma implementação de referência dessa lógica.

Monitoramento de alterações de valores atuais em tempo real

Se um aplicativo complementar for executado ao mesmo tempo que a página de configurações da câmera, talvez o cliente altere um valor padrão por meio da página de configurações da câmera durante a execução simultânea do aplicativo complementar no modo compartilhado para exibir uma versão prévia. Nesse caso, é desejável que o aplicativo complementar monitore as alterações no valor padrão dos controles para que ele possa permanecer em sincronia.

Para tanto, o aplicativo complementar pode usar o IMFCameraControlMonitor para monitorar alterações no valor atual de controles (propriedades KS) de interesse. Essas alterações podem ocorrer devido a:

Um aplicativo de câmera (por exemplo, o Microsoft Teams) está usando a câmera e faz uma alteração no valor atual de um controle.
A página de configurações da câmera está usando a câmera e faz uma alteração no valor padrão de um controle (que também atualiza o valor atual).

Será possível usar essa API como um gatilho para reler o valor padrão de um controle de interesse por meio da API IMFCameraConfigurationManager e atualizar a interface do usuário se houver alteração em valores padrão.

Exemplos de aplicativos complementares

Um exemplo de aplicativo complementar está disponível no GitHub: exemplo de CameraSettingsExternalSettingsApp. Este exemplo demonstra como usar a API IMFCameraConfigurationManager para alterar o valor padrão para Contraste, Brilho e Segmentação em Segundo Plano.

Outro aplicativo de exemplo que demonstra como usar a API IMFCameraControlMonitor para monitorar alterações em controles de interesse está disponível no GitHub: exemplo de ControlMonitorApp.