En el SDK de Jetpack XR, los entornos espaciales son entornos envolventes que puedes agregar a tu app para personalizar el fondo de la escena virtual. Los entornos espaciales solo son visibles cuando una app está en Full Space.
Descripción general de los entornos espaciales
Se usa un SpatialEnvironment para administrar las preferencias de entorno espacial de una app. Es un compuesto de una imagen de cielo independiente y una geometría especificada por glTF. Solo se puede configurar una sola imagen de cielo y un solo archivo de geometría glTF a la vez.
Un cielo virtual representa la imagen que un usuario ve a su alrededor en la escena virtual, lo que crea la ilusión de un entorno de fondo distante, como un cielo, montañas o un paisaje urbano. El usuario no puede interactuar con el cielo ni acercarse a él. El SDK de Jetpack XR admite fondos de cielo esféricos en el estándar OpenEXR. Además de proporcionar un fondo envolvente para tu app, un cielo virtual EXR también proporciona iluminación basada en imágenes (IBL) a los modelos 3D que carga tu app. Para obtener más información, consulta la guía para trabajar con modelos 3D.
Los entornos espaciales también pueden incluir contenido de geometría 3D en el estándar glTF. La geometría del entorno cargada de esta manera se alineará automáticamente con el piso del mundo real. La geometría del entorno es una gran manera de agregar realismo a tu entorno a través de elementos en primer y segundo plano que se mezclan en el cielo con el efecto de paralaje.
En la guía de diseño para entornos espaciales, puedes obtener información sobre los diferentes tipos de recursos que puedes usar para crear entornos espaciales y cómo crear entornos espaciales seguros y agradables.
Puedes configurar el entorno espacial de tu app en una de estas tres opciones:
- Es una combinación de una imagen de cielo y una geometría glTF.
- Una superficie de transferencia, en la que el entorno que se muestra es un feed en vivo de las cámaras orientadas hacia afuera del dispositivo Con opacidad completa, esta superficie de transferencia ocluye por completo el cielo y la geometría.
- Una configuración mixta, en la que la superficie de transferencia no tiene opacidad completa ni cero opacidad En este caso, la superficie de transferencia se vuelve semitransparente y la alfa se mezcla con el cielo y la geometría detrás de ella.
Funciones espaciales para entornos espaciales
SpatialCapabilities: Representa las capacidades espaciales de la sesión actual. Algunas capacidades espaciales son relevantes para los entornos espaciales.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL: Indica si la actividad puede habilitar o inhabilitar el pase en el momento actual.SPATIAL_CAPABILITY_APP_ENVIRONMENT: Indica si la actividad puede establecer su propio entorno espacial en el momento actual.
Importa y carga recursos de entorno espacial
Los recursos glTF y EXR para entornos espaciales se cargan de forma asíncrona en la clase Session. Estos archivos deben almacenarse en la carpeta de recursos.
Crea un recurso glTF
Se puede crear un recurso glTF como un GltfModel, en el que el glTF se carga desde un archivo local. Se puede usar un GltfModel como parte de un entorno de app espacial.
// assume that session is a Session that has been previously created
val environmentGeometryFuture = session.createGltfResourceAsync("DayGeometry.glb")
val environmentGeometry = environmentGeometryFuture.await()
Crea un recurso de imagen EXR
Se puede crear un recurso de imagen EXR como un ExrImage, en el que se carga el EXR desde un archivo local. Se puede usar un ExrImage como parte de un entorno de app espacial para dibujar cielorraso.
// assume that session is a Session that has been previously created
val skyboxExrFuture = session.createExrImageResourceAsync("BlueSkybox.exr")
val skyboxExr = skyboxExrFuture.await()
Configura SpatialEnvironmentPreference para tu app
setSpatialEnvironmentPreference se usa para establecer el entorno espacial preferido para una app. Este método solo establece una preferencia y no causa un cambio inmediato, a menos que isSpatialEnvironmentPreferenceActive ya sea verdadero. Una vez que el dispositivo entra en un estado en el que se puede cambiar el fondo de XR y la función SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT está disponible, se mostrará automáticamente el entorno espacial preferido para la aplicación.
Si estableces la preferencia en nulo, se inhabilitará el entorno espacial preferido para la app, lo que significa que se mostrará el entorno del sistema predeterminado.
Si el SpatialEnvironmentPreference determinado no es nulo, pero
todas sus propiedades son nulas, el entorno espacial consistirá en un
firmamento negro y no tendrá geometría.
Para recibir notificaciones sobre los cambios en el estado de SpatialEnvironment, usa addOnSpatialEnvironmentChangedListener.
Uso básico
Este fragmento de código crea la geometría del entorno y los recursos del cielo y, luego, establece la preferencia del entorno espacial. Esta preferencia se recordará y se aplicará cuando la app tenga la capacidad de establecer su propio entorno.
// Assume that session is a Session that has been previously created
// Create a GLTFResource
val environmentGeometry = session.createGltfResourceAsync("DayGeometry.glb").await()
// Create an ExrImage for the skybox
val skyboxExr = session.createExrImageResourceAsync("BlueSkybox.exr").await()
val spatialEnvironmentPreference = SpatialEnvironmentPreference(skyboxExr, environmentGeometry)
val preferenceResult = session.spatialEnvironment.setSpatialEnvironmentPreference(spatialEnvironmentPreference)
if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangeApplied()) {
// The environment was successfully updated and is now visible, and any listeners
// specified using addOnSpatialEnvironmentChangedListener will be notified.
} else if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangePending()) {
// The environment is in the process of being updated. Once visible, any listeners
// specified using addOnSpatialEnvironmentChangedListener will be notified.
}
Uso avanzado
Para casos de uso más avanzados en los que necesitas un control más detallado sobre el entorno, puedes incorporar verificaciones de SpatialCapabilities e implementar un addOnSpatialEnvironmentChangedListener para determinar cuándo deseas establecer la preferencia de entorno espacial.
Configura PassthroughOpacityPreference para el entorno espacial de tu app
Uno de los componentes del fondo virtual envolvente de una app es una superficie de transferencia. En este caso, el fondo que se muestra es un feed en vivo de las cámaras orientadas hacia afuera del dispositivo.
setPassthroughOpacityPreference se usa para establecer la opacidad de transferencia preferida para una app. Este método solo establece una preferencia y no causa un cambio inmediato, a menos que la función SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL esté disponible. Una vez que el dispositivo ingresa a un estado en el que se puede cambiar la opacidad de transferencia y la función SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL está disponible, se aplicará automáticamente la opacidad de transferencia preferida para la aplicación.
Los valores de la preferencia de opacidad de transferencia varían de 0.0f (opacidad cero, en la que la superficie de transferencia no es visible) a 1.0f (opacidad total, en la que la superficie de transferencia oculta el entorno espacial). El parámetro setPassthroughOpacityPreference es un número de punto flotante anulable. Si estableces el valor en nulo, se indica que la app no tiene una preferencia de opacidad de transferencia y mostrará el control de transferencia al sistema.
Uso básico
Este fragmento de código establece la preferencia de opacidad de transferencia. Esta preferencia se recordará y se aplicará cuando la app tenga la capacidad de establecer la opacidad de transferencia.
// Assume that session is a Session that has been previously created
val preferenceResult = session.spatialEnvironment.setPassthroughOpacityPreference(1.0f)
if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangeApplied()) {
// The passthrough opacity request succeeded and should be visible now, and any listeners specified using addOnPassthroughOpacityChangedListener
// will be notified
} else if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangePending()) {
// The passthrough opacity preference was successfully set, but not
// immediately visible. The passthrough opacity change will be applied
// when the activity has the
// SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability.
// Then, any listeners specified using addOnPassthroughOpacityChangedListener
// will be notified
}
Uso avanzado
Para casos de uso más avanzados en los que necesitas un control más preciso sobre la opacidad de transferencia, puedes incorporar verificaciones SpatialCapabilities e implementar un addOnPassthroughOpacityChangedListener para determinar cuándo deseas establecer la preferencia de opacidad de transferencia.
Optimización de recursos
Cuando crees recursos para configurar el SpatialEnvironment de tus usuarios, te recomendamos que te asegures de que tus recursos alcancen una resolución de alta calidad y, al mismo tiempo, mantengan un tamaño de archivo razonable. Asegúrate de que tu glb use mipmaps y texturas ktx2. También debes tener en cuenta la cantidad de polígonos en tus archivos glb, ya que una cantidad alta puede generar un consumo de energía innecesario. La mayor parte del tamaño del archivo de la mayoría de las instancias de SpatialEnvironment proviene de la imagen que se usa para el cielo. Para asegurarte de que tus imágenes estén optimizadas, ejecuta los recursos a través de una herramienta de optimización (por ejemplo, ktx).
Cómo determinar la opacidad de transferencia actual
val currentPassthroughOpacity = session.spatialEnvironment.getCurrentPassthroughOpacity()