Agrega entornos espaciales a tu app

Dispositivos de realidad extendida correspondientes
Esta guía te ayuda a crear experiencias para estos tipos de dispositivos de realidad extendida.
Más información sobre los tipos de dispositivos de realidad extendida →
Visores de realidad extendida
Lentes de realidad extendida con cable
Más información sobre los tipos de dispositivos de realidad extendida →

En el SDK de XR de Jetpack, 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 el espacio completo.

Descripción general de los entornos espaciales

Un SpatialEnvironment administra las preferencias de entorno espacial de una app. Es una composición de una imagen de skybox independiente y una geometría especificada por glTF. Solo se puede configurar una imagen de skybox y un solo archivo de geometría glTF a la vez.

Un skybox 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 skybox ni acercarse a él. El SDK de XR de Jetpack admite skyboxes esféricos en el estándar OpenEXR. Además de proporcionar un fondo envolvente para tu app, un skybox 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 glTF estándar. 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 excelente manera de agregar realismo a tu entorno a través de elementos de primer plano y de plano medio que se combinan con el skybox 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 configuraciones:

  • Una combinación de una imagen de skybox y una geometría glTF
  • Una superficie de transferencia, en la que el entorno que se muestra es una transmisión en vivo de las cámaras orientadas hacia afuera del dispositivo Con opacidad total, esta superficie de transferencia ocluye por completo el skybox y la geometría.
  • Una configuración mixta, en la que la superficie de transferencia no está en opacidad total ni en opacidad cero En este caso, la superficie de transferencia se vuelve semitransparente y se combina con el skybox y la geometría que se encuentran detrás.

Funciones espaciales para entornos espaciales

Importa y carga recursos de entorno espacial

Los recursos glTF y EXR para entornos espaciales se cargan de forma asíncrona con la Session clase.

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.

val environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))

Crea un recurso de iluminación basada en imágenes

Se puede crear un recurso de iluminación basada en imágenes como un ImageBasedLightingAsset, en el que la iluminación se carga desde un archivo local. Se puede usar un ImageBasedLightingAsset con cmgen para crear un archivo ZIP del IBL para tus skyboxes. Consulta nuestra guía para optimizar los recursos del entorno para obtener más detalles.

val lightingForSkybox = ImageBasedLightingAsset.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))

Configura el SpatialEnvironmentPreference para tu app

La propiedad preferredSpatialEnvironment controla el entorno espacial preferido para una app. Cuando se usa esta propiedad para establecer una preferencia, no causa un cambio inmediato, a menos que isPreferredSpatialEnvironmentActive ya sea true. Una vez que el dispositivo ingresa a un estado en el que se puede cambiar el fondo de XR y la SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT capacidad está disponible, se mostrará automáticamente el entorno espacial preferido para la aplicación.

Si se establece la preferencia en null, se inhabilitará el entorno espacial preferido para la app, lo que significa que se mostrará el entorno predeterminado del sistema.

Si el SpatialEnvironmentPreference determinado no es nulo, pero todas sus propiedades son nulas, el entorno espacial consistirá en un skybox negro y sin 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 de skybox, y luego establece la preferencia de entorno espacial. Esta preferencia se recordará y se aplicará cuando la app tenga la capacidad de establecer su propio entorno.

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
session.scene.spatialEnvironment.preferredSpatialEnvironment = spatialEnvironmentPreference
if (session.scene.spatialEnvironment.isPreferredSpatialEnvironmentActive) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the SPATIAL_CAPABILITY_APP_ENVIRONMENT capability.
    // Then, 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 preciso sobre el entorno, puedes incorporar verificaciones de SpatialCapabilities y, luego, implementar un addOnSpatialEnvironmentChangedListener para determinar cuándo deseas establecer la preferencia de entorno espacial.

Configura el 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 una transmisión 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 capacidad 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 capacidad 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 que admite valores nulos. Si se establece el valor en nulo, se indica que la app no tiene preferencia de opacidad de transferencia y devolverá 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.

session.scene.spatialEnvironment.preferredPassthroughOpacity = 1.0f
if (session.scene.spatialEnvironment.currentPassthroughOpacity == 1.0f) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified.
} else {
    // 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 de SpatialCapabilities y agregar un objeto de escucha con 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, asegúrate de que estos alcancen una resolución de alta calidad y, al mismo tiempo, mantengan un tamaño de archivo razonable. Para obtener más información, consulta nuestra guía para optimizar los recursos del entorno.

Determina la opacidad de transferencia actual

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

Consulta también