Iluminación dinámica
En este tema se describe cómo las aplicaciones de Windows pueden proporcionar efectos de iluminación dinámicos en dispositivos conectados que implementan el estándar de iluminación e iluminación abiertos de dispositivos de interfaz humana (HID). En concreto, la especificación LampArray para dispositivos que tienen una lámpara o más (luces, LED, bombillas, etc.).
API importantes
Información general
La iluminación dinámica permite a los desarrolladores de aplicaciones de Windows y a los usuarios finales controlar y sincronizar los efectos de iluminación entre periféricos compatibles y otros dispositivos conectados. Estas características se pueden usar para ofrecer experiencias cohesivas que entretengan a los usuarios, les hacen más productivos e incluso hacen que sus experiencias en Windows sean más accesibles.
Plataformas y tipos de aplicaciones compatibles
- Win10 versión 1809 (octubre de 2018) y versiones posteriores.
- Se aplica a las aplicaciones UWP y Win32 en primer plano.
- Windows 11 Build 23466 (versión preliminar) y versiones posteriores.
- Se aplica a las aplicaciones UWP y Win32 en primer plano y en segundo plano (ambiente).
- Xbox GDK Update 1 de marzo de 2023 y versiones posteriores.
- Consulta la API de iluminación en el Kit de desarrollo de juegos (GDK).
Dispositivos y tipos de dispositivos admitidos
- Teclado o teclado numérico
- Mouse
- Dispositivo de juego (controlador para juegos, palanca de mandos, volante, etc.).
- Periférico (dispositivos generales, como altavoces, alfombrilla del mouse, micrófonos, cámaras web, etc.).
- Escena (dispositivos de sala, escenario o área, como bombillas, focos de luz, luces estroboscópicas, carteles, flashes de cámara, etc.).
- Notificación (dispositivos de atención del usuario, como alarmas, asistentes de voz, etc.).
- Chasis (componentes internos de PC como RAM, placa base, ventilador, etc.).
- Transportable (accesorios como auriculares, relojes, rastreadores de fitness, zapatos, etc.).
- Muebles (como sillas, escritorios, librerías, etc.).
- Arte (como una pintura o escultura).
- Casco (accesorios diseñados específicamente para la cabeza, como auriculares o micrófonos).
Una aplicación de Windows puede controlar dispositivos HID LampArray cuando la aplicación está en primer plano (desde Windows 10) y cuando está en segundo plano (también conocida como iluminación de ambiente, desde Windows 11).
Priorización de dispositivos
Windows da prioridad a la iluminación dinámica en función del estado de la aplicación. De forma predeterminada, a una aplicación en primer plano siempre se le asigna el control de un dispositivo LampArray a menos que el usuario haya especificado lo contrario en la configuración. En los casos en que dos o más aplicaciones de ambiente en segundo plano intenten controlar un dispositivo LampArray, el sistema asignará el control a la aplicación priorizada en la configuración.
Iluminación en segundo plano (ambiente)
Las API "de ambiente" de Windows.Devices.Lights permiten a las aplicaciones en segundo plano controlar dispositivos LampArray mientras el usuario interactúa con una aplicación en primer plano que no tiene relación con las otras aplicaciones (como aplicaciones de música que controlan efectos de iluminación sincronizados).
Las aplicaciones pueden recibir eventos LampArray.AvailabilityChanged, en función de la configuración del usuario. Junto con la clase DeviceWatcher, las aplicaciones pueden realizar un seguimiento y administrar todos los dispositivos LampArray conectados o desconectados y ver cuál de ellos espera el usuario que controle la aplicación. Un ejemplo de uso es una interfaz de usuario que muestra un icono para cada dispositivo conectado, mientras que los no disponibles aparecen atenuados, y vínculos a la página de configuración de iluminación dinámica , donde el usuario puede realizar cambios en las preferencias de aplicaciones en primer plano o en segundo plano.
Configuración de usuario
Los usuarios pueden personalizar su experiencia de dispositivo LampArray (tanto en primer plano como en segundo plano) a través de la pantalla Configuración -> Personalización -> Iluminación dinámica.
Cuando esté conectado, los dispositivos compatibles aparecerán en las tarjetas de dispositivo en la parte superior de la página donde los usuarios pueden cambiar la configuración de dispositivo individual.
La configuración global de Iluminación dinámica se encuentra debajo de las tarjetas de dispositivo (los cambios en esta configuración afectan a todos los dispositivos conectados).
- El botón de alternancia Usar Iluminación dinámica en mis dispositivos permite a los usuarios activar o desactivar la Iluminación dinámica. Cuando la Iluminación dinámica está desactivada, los dispositivos deben funcionar con su comportamiento de iluminación no dinámica predeterminado. La iluminación dinámica incluye un conjunto integrado de efectos básicos.
- La opción Las aplicaciones compatibles en primer plano siempre controlan la iluminación permite a los usuarios activar o desactivar el comportamiento predeterminado de la aplicación Iluminación dinámica. Cuando esta característica está desactivada, una aplicación en segundo plano puede controlar los dispositivos asociados incluso cuando una aplicación en primer plano que desea tener el control está activa.
- La sección Control de luz en segundo plano permite a los usuarios priorizar las aplicaciones instaladas que se han registrado como controladores en segundo plano de ambiente. Al arrastrar una aplicación a la parte superior de la lista, se le dará prioridad y se asegurará de que pueda controlar los dispositivos sobre otras aplicaciones de la lista. La configuración de segundo plano está vinculada a un dispositivo y al puerto al que está conectado. Si desconecta y vuelve a conectar LampArray en un puerto diferente (USB), aparecerá como un dispositivo diferente.
- El control deslizante Brillo permite a los usuarios establecer el brillo LED en sus dispositivos.
- La lista desplegable Efectos permite a los usuarios seleccionar colores y efectos para sus dispositivos.
Nota:
Cuando un dispositivo no está seleccionado para el control de la luz de fondo, funciona en modo "autónomo".
Esto se define en la especificación HID como un modo en el que el hardware vuelve al comportamiento predeterminado tal como se define en su firmware. Por ejemplo, un dispositivo podría tener un efecto visual programado previamente que es el valor predeterminado cuando el sistema operativo no controla activamente el dispositivo o si el usuario ha optado por no participar en el sistema operativo para el dispositivo. El dispositivo debe responder al comando HID para volver del modo autónomo para garantizar una interacción fluida con las expectativas del usuario.
Empaquetado e identidad de aplicación
Las aplicaciones en segundo plano de ambiente deben declarar la AppExtension "com.microsoft.windows.lighting" en el manifiesto de la aplicación (para obtener más información sobre cómo hacerlo, consulta Crear y hospedar una extensión de aplicación). El AmbientLightingServer aplica este requisito, que solo acepta conexiones de AmbientLightingClient en un proceso con identidad de paquete (aplicación empaquetada) que admite la extensión. Este requisito es necesario para permitir que el usuario defina la directiva para las aplicaciones instaladas y, a continuación, correlacione esa directiva en tiempo de ejecución.
La identidad de la aplicación es necesaria para las aplicaciones de ambiente, de modo que las preferencias del usuario se pueden determinar en tiempo de ejecución. Una vez instalada una aplicación, si usa las API de ambiente, el sistema debe correlacionar la instancia en ejecución de una aplicación con las preferencias del usuario. Además, hacer que la aplicación esté disponible para el usuario en la configuración requiere un artefacto posterior a la instalación que indica al sistema que la aplicación es un usuario legítimo de las API de iluminación de ambiente.
Este requisito de identidad se logra a través de empaquetado MSIX (una tecnología de implementación y empaquetado de Microsoft anteriormente conocida como APPX).
Si ya usa el empaquetado MSIX para empaquetar e instalar, no hay más requisitos.
Si tiene una aplicación sin empaquetar, se requieren pasos adicionales para obtener la identidad de la aplicación. Puede migrar la instalación a MSIX completamente o puede usar la característica simplificada Empaquetado disperso y ubicación externa de MSIX. El empaquetado disperso con ubicación externa se diseñó para permitir que las instalaciones de aplicaciones existentes obtuvieran la ventaja de la identidad de la aplicación sin necesidad de una conversión completa de la configuración e instalación en MSIX. Se trata de un nuevo paso en la configuración e instalación que usa herramientas para crear un paquete MSIX para representar la aplicación que va a instalar.
Debe definir un manifiesto de empaquetado AppXManifest.xml que describa la instalación. El paquete MSIX se crea con la herramienta MakeAppXPackage. En el momento de la instalación, se instala el paquete MSIX mediante una API de Administrador de paquetes que especifica la ubicación del ejecutable instalado. Para mayor comodidad, el script de PowerShell add-appxpackage también encapsula este comportamiento de API. Como alternativa, AddPackageByUriAsync se puede usar en el momento de la instalación para instalar el paquete MSIX.
En el caso de las instalaciones de aplicaciones sin empaquetar, también hay un requisito de manifiesto de aplicación en paralelo para el archivo ejecutable.
Consulte Introducción a la implementación para obtener una explicación más detallada de las aplicaciones empaquetadas y desempaquetadas.
Ejemplos
Muestra cómo controlar la iluminación RGB de los dispositivos periféricos mediante las API Windows.Devices.Lights y Windows.Devices.Lights.Effects.
Muestra cómo extraer un único color representativo de una pantalla de escritorio y usarlo para iluminar lámparas LED en un dispositivo RGB conectado.