Iluminação dinâmica
Este tópico descreve como seus aplicativos do Windows podem fornecer efeitos de iluminação dinâmicos em dispositivos conectados que implementam o padrão de iluminação e iluminação HID (dispositivos de interface humana) abertos. Em particular, a especificação LampArray para dispositivos que possuem uma ou mais lâmpadas (luzes, LEDs, lâmpadas e assim por diante).
APIs importantes
Visão geral
O suporte à iluminação dinâmica no Windows permite que desenvolvedores de aplicativos e usuários finais controlem e sincronizem efeitos de iluminação entre periféricos e outros dispositivos conectados.
Tipos de aplicativos e plataformas compatíveis
- Win10 versão 1809 (outubro de 2018) e posterior.
- Aplica-se a aplicativos UWP e Win32 em primeiro plano.
- Windows 11 build 23466 (versão prévia) e posterior.
- Aplica-se a aplicativos UWP e Win32 em primeiro e segundo plano (ambiente).
- Atualização 1 de março de 2023 do GDK do Xbox e posterior.
- Confira a API de Iluminação no GDK (Kit de Desenvolvimento de Jogo).
Dispositivos compatíveis e tipos de dispositivos
- Teclado
- Mouse
- Controle de jogo (gamepad, joystick, volante e assim por diante).
- Periféricos (dispositivos gerais, como alto-falantes, mouse pads, microfones, webcams e assim por diante).
- Cena (dispositivos de sala/palco/área, como lâmpadas, holofotes, luzes estroboscópicas, outdoors, flashes de câmera e assim por diante).
- Notificação (dispositivos de atenção do usuário, como alarmes, assistentes de voz e assim por diante).
- Chassis (componentes internos do PC, como RAM, placa-mãe, ventilador e assim por diante).
- Dispositivos acessórios (acessórios como fones de ouvido, relógios, rastreadores fitness, sapatos e assim por diante).
- Móveis (como cadeiras, mesas, estantes e assim por diante).
- Arte (como uma pintura ou escultura).
- Fone de ouvido (acessórios projetados especificamente para a cabeça, como fones de ouvido ou microfones).
Um aplicativo do Windows pode controlar dispositivos LampArray de HID quando está em primeiro plano (a partir do Windows 10) e quando está em segundo plano (também conhecido como iluminação ambiente, a partir do Windows 11).
Os usuários podem personalizar a experiência do dispositivo (primeiro plano e tela de fundo) LampArray por meio da tela Configurações –> Personalização –> Iluminação dinâmica, que permite sincronizar dispositivos de diferentes fabricantes, controlar o brilho e os efeitos em dispositivos e fatores forma selecionados e priorizar o acesso a dispositivos por aplicativos de ambiente em segundo plano. Esses recursos permitem que seus aplicativos entretenham os usuários, os tornem mais produtivos, tornem suas experiências no Windows mais acessíveis e proporcionem experiências coesas em todo o conjunto de dispositivos compatíveis com o Dynamic Lighting.
Priorização de dispositivos
O Windows prioriza a iluminação dinâmica com base no estado do aplicativo. Por padrão, um aplicativo em primeiro plano sempre recebe o controle de um dispositivo LampArray, a menos que o usuário tenha especificado o contrário em “Configurações”. Nos casos em que dois ou mais aplicativos de ambiente em segundo plano estão tentando controlar um dispositivo LampArray, o sistema atribui o controle ao aplicativo priorizado em “Configurações”.
Iluminação em segundo plano (ambiente)
As APIs de "ambiente" em Windows.Devices.Lights permitem que aplicativos em segundo plano controlem dispositivos LampArray enquanto o usuário está interagindo com um aplicativo não relacionado em primeiro plano (como aplicativos de música que geram efeitos de iluminação sincronizados).
Os aplicativos podem receber eventos de LampArray.AvailabilityChanged, dependendo das configurações do usuário. Com a classe DeviceWatcher, os aplicativos podem rastrear e gerenciar todos os dispositivos LampArray conectados/desconectados e ver quais deles o usuário espera que eles controlem. Um exemplo de uso é uma interface do usuário que renderiza um ícone para cada dispositivo conectado, em que os indisponíveis ficam esmaecidos, e links para a página de configurações de iluminação dinâmica, na qual o usuário pode fazer alterações nas preferências do aplicativo em primeiro plano/segundo plano.
Configurações do usuário
Os usuários podem controlar e configurar seus dispositivos LampArray de HID em nível individual e global por meio da página “Iluminação dinâmica” em Configurações –> Personalização –> Iluminação dinâmica. Essa página aparecerá em “Configurações” quando pelo menos um dispositivo compatível estiver conectado ao PC.
Quando conectados, os dispositivos compatíveis aparecerão nos cartões de dispositivo na parte superior da página, onde os usuários podem alterar as configurações individuais do dispositivo.
As configurações de iluminação dinâmica global estão localizadas abaixo dos cartões de dispositivo (alterações nessas configurações afetam todos os dispositivos conectados).
- A opção Usar a iluminação dinâmica em meus dispositivos permite que os usuários ativem ou desativem a iluminação dinâmica. Quando a iluminação dinâmica está desativada, os dispositivos funcionam com o comportamento padrão de iluminação não dinâmica. A iluminação dinâmica inclui um conjunto interno de efeitos básicos.
- Aplicativos compatíveis em primeiro plano sempre controlam a iluminação permite que os usuários ativem ou desativem o comportamento padrão do aplicativo com relação à iluminação dinâmica. Quando esse recurso é desativado, um aplicativo em segundo plano pode controlar dispositivos associados, mesmo quando um aplicativo em primeiro plano que deseja controle está ativo.
- A seção Controle de luz de tela de fundo permite que os usuários priorizem aplicativos instalados que se registraram como controladores de ambiente em segundo plano. Arrastar um aplicativo para o topo da lista prioriza esse aplicativo e garantir que ele possa controlar dispositivos de maneira prioritária com relação a outros aplicativos na lista. As configurações de ambiente em segundo plano estão vinculadas a um dispositivo e à porta à qual ele está conectado. Se você desconectar e reconectar o LampArray em uma porta (USB) diferente, ele aparecerá como um dispositivo diferente.
- O controle deslizante Brilho permite que os usuários definam o brilho do LED nos dispositivos.
- A lista suspensa Efeitos permite que os usuários selecionem cores e efeitos para os dispositivos.
Observação
Quando um dispositivo não é selecionado para Controle de luz da tela de fundo, ele opera em "modo autônomo", o que significa que é revertido para o comportamento padrão do firmware.
Empacotamento e identidade do aplicativo
Os aplicativos de ambiente em segundo plano devem declarar a AppExtension "com.microsoft.windows.lighting" no manifesto do aplicativo (para saber como fazer isso, confira Criar e hospedar uma extensão de aplicativo). Esse requisito é aplicado pelo AmbientLightingServer, que só aceita conexões de um AmbientLightingClient em um processo com identidade de pacote (aplicativo empacotado) compatível com a extensão. Esse requisito é necessário a fim de permitir que o usuário defina a política para aplicativos instalados e a correlacione no runtime.
A identidade do aplicativo é necessária para aplicativos de ambiente, de modo que as preferências do usuário possam ser determinadas no runtime. Depois que um aplicativo é instalado, se estiver usando as APIs de ambiente, o sistema precisará correlacionar a instância em execução dele com as preferências do usuário. Além disso, disponibilizar seu aplicativo para o usuário nas configurações requer um artefato pós-instalação que indique ao sistema que o aplicativo é um usuário legítimo das APIs de iluminação ambiente.
Esse requisito de identidade é atendido por meio do empacotamento MSIX.
Se você já estiver usando o empacotamento MSIX para empacotamento e instalação, não haverá mais requisitos.
Se você tiver um aplicativo desempacotado, haverá etapas adicionais para obter a identidade do aplicativo. É possível migrar sua instalação para o MSIX completo ou usar o recurso simplificado Empacotamento esparso e local externo do MSIX. O empacotamento esparso com local externo foi projetado para permitir que as instalações de aplicativos existentes obtenham o benefício da identidade de aplicativo sem exigir uma conversão completa da configuração/instalação para MSIX. É uma nova etapa na configuração/instalação que usa ferramentas para criar um pacote MSIX a fim de representar o aplicativo que você está instalando.
É necessário definir um manifesto de empacotamento AppXManifest.xml que descreva a instalação. O pacote MSIX é criado com a ferramenta MakeAppXPackage. No momento da instalação, você instala o pacote MSIX usando uma API do Gerenciador de Pacotes que especifica o local do executável instalado. Por conveniência, o script add-appxpackage do PowerShell também encapsula esse comportamento da API. Como alternativa, AddPackageByUriAsync pode ser usado no momento da instalação para instalar o pacote MSIX.
Para instalações de aplicativos não empacotados, também há um requisito de manifesto de aplicativo lado a lado para o executável.
Confira a Visão geral da implantação para obter uma explicação mais detalhada dos aplicativos empacotados e não empacotados.
Glossário
Os termos e conceitos a seguir são usados para descrever diversos componentes do sistema de iluminação ambiente.
Modo autônomo
Definido na especificação de HID como um modo em que o hardware retorna ao comportamento padrão definido pelo firmware. Por exemplo, um dispositivo pode ter um efeito visual pré-programado que é o padrão quando o sistema operacional não está controlando ativamente esse dispositivo ou caso o usuário tenha optado por não participar do sistema operacional do dispositivo. O dispositivo deve responder ao comando de HID para retornar do modo autônomo e garantir uma interação adequada com as expectativas do usuário.
Aplicativos de ambiente
Os consumidores de API do Windows.Devices.Lights que também têm identidade de pacote e dão suporte à extensão de aplicativo necessária. Os aplicativos de ambiente recebem notificações de AmbientLightingClient. Os eventos informam ao aplicativo os dispositivos aos quais eles têm acesso. Dessa forma, um aplicativo pode mostrar a interface do usuário enumerando os dispositivos de iluminação conectados e esmaecer aqueles que estão atualmente inacessíveis devido às configurações de política do usuário. Os aplicativos de ambiente utilizam as APIs de Windows.Devices.Lights para gerar efeitos nos dispositivos disponíveis.
Miniaplicativo de configurações
Armazena as preferências do usuário por dispositivo no HKEY_CURRENT_USER (HKCU) do registro. O usuário pode definir o conjunto priorizado de aplicativos de ambiente para determinado dispositivo por meio da abordagem por dispositivo. Ele também pode desativar a iluminação dinâmica.
Identidade do aplicativo
Um conceito de modelo de aplicativo. Um aplicativo que tem uma identidade de aplicativo pode ser identificado pelo sistema no runtime.
MSIX
Uma tecnologia de implantação e empacotamento da Microsoft anteriormente conhecida como APPX.
Exemplos
Demonstra como controlar a iluminação RGB de dispositivos periféricos usando as APIs Windows.Devices.Lights e Windows.Devices.Lights.Effects.
Demonstra como extrair uma única cor representativa de uma tela de desktop e usá-la para iluminar lâmpadas LED em um dispositivo RGB conectado.