Aplicações complementares da câmara

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

Introdução

O Windows 11 fornece uma estrutura de aplicativo complementar à câmera que permite que os fabricantes desenvolvam aplicativos com os seguintes recursos:

Capacidade de exibir e/ou modificar as mesmas configurações de valor padrão que a página de configurações da câmera suporta (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 que são conhecidos do Windows, mas não são expostos através 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 on/off para o efeito de ajuste de iluminação personalizado do fabricante da 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 pode ser iniciado a partir da página de configurações da câmera, caso contrário, um link para a Microsoft Store será exibido para baixá-lo.

As aplicações complementares têm acesso especial a uma API que lhes permite registar, atualizar ou eliminar valores predefinidos, como a página de definições da câmara.

Terminologia e pré-requisitos

Período	Definição
Aplicação complementar	Um aplicativo personalizado desenvolvido pelo fabricante da câmera que permite a configuração e 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á atualmente ativo no ISP da câmera e mantido na memória temporária da câmera.
Valor predefinido	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	Hardware Support App, uma estrutura suportada pela Microsoft para transferir e instalar automaticamente aplicações associadas ao hardware a partir da Microsoft Store quando o dispositivo está ligado.
NPU (Unidade de Processamento Neural)	Unidade de Processamento Neural, hardware dedicado projetado 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	USB Video Class, a interface padronizada para controlar e transmitir a partir 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, o que permite 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.

Os aplicativos de desktop 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 também como um aplicativo de suporte de hardware, mas é altamente recomendado. HSAs são aplicativos especiais na Microsoft Store que estão associados a um dispositivo de hardware específico. Quando esse dispositivo está conectado a um PC, o HSA é baixado e instalado automaticamente da Microsoft Store quando disponível.

Associar uma aplicação complementar a uma câmara

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

Nome	Tipo	Dados
SCSVCamPfn	REG_SZ	<PFN>

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

Get-AppxPackage -Name CompanionAppName

Para associar a aplicação complementar a uma câmera, use um descritor MSOS numa câmera UVC ou a diretiva AddReg no INF do controlador 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 no 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.

Inicie uma aplicação complementar a partir da página de definições da câmara

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 .

Argumento	Tipo	Dados
cameraId	Cordão	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 suporta várias câmeras em um único sistema (por exemplo, um aplicativo fornecido pelo OEM suporta as câmeras frontal e traseira em um tablet).
Um cliente tem duas câmeras da mesma (ou da mesma marca) conectadas ao seu sistema que são gerenciadas pelo mesmo aplicativo complementar.

Inicie 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 deeplink. Para obter mais informações, consulte página Iniciar as configurações da câmera.

Configurar valores padrão de aplicativos complementares

Um aplicativo complementar pode usar a API IMFCameraConfigurationManager para configurar a configuração de valor padrão do usuário atual. Essa API permite que o aplicativo complementar leia quaisquer 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 quaisquer valores padrão, registre novos valores padrão ou remova valores padrão salvos.

Os valores padrão são registados na base de dados do sistema como um par de um GUID de propriedade KS e valor correspondente. Isso permite que a arquitetura seja independente da definição da propriedade KS. Essa flexibilidade permite que um aplicativo complementar defina, edite ou exclua valores padrão para qualquer uma das seguintes configurações:

Configurações que também são configuráveis 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 que são conhecidos do Windows, mas não são expostos através 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 on/off para o efeito de ajuste de iluminação personalizado do fabricante da câmera)

Configurar o brilho a partir de um aplicativo complementar

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

O Windows suporta um antigo controle de brilho (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) projetado para comandar um viés 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 é utilizado por uma câmara, ele deve ser implementado na câmara de modo que, quando "centralizado", o brilho seja neutro, permitindo que o cliente aplique um deslocamento ao aumentar ou diminuir o valor. Para obter a melhor qualidade de imagem, é altamente recomendável que as câmeras suportem o controle de compensação de exposição, de modo 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 viés positivo ou negativo fixo à exposição, independentemente das condições de iluminação a qualquer momento.

Para obter mais informações, consulte a página de configurações da câmera para o comportamento do controle de brilho na página de configurações da câmera com base em qual controle a câmera implementa. Se um aplicativo complementar também oferecer um controle deslizante de brilho, é fundamental 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 abaixo inclui uma implementação de referência dessa lógica.

Monitoramento de alterações de valor atual em tempo real

Se um aplicativo complementar estiver sendo executado ao mesmo tempo que a página de configurações da câmera, é possível que o cliente altere um valor padrão usando a página de configurações da câmera enquanto o aplicativo complementar estiver sendo executado simultaneamente no modo compartilhado para exibir uma visualização. Nesse caso, é desejável que o aplicativo complementar monitore as alterações no valor padrão dos controles para que ele possa permanecer sincronizado.

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

Um aplicativo de câmera (por exemplo, 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).

Essa API pode ser usada como um gatilho para reler o valor padrão para um controle de interesse usando a API IMFCameraConfigurationManager e atualizar a interface do usuário se algum valor padrão tiver sido alterado.

Exemplos de aplicativos complementares

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

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