Agrega entornos espaciales a tu app

En el SDK de Jetpack XR, los entornos espaciales son entornos inmersivos 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 modo de espacio completo.

Descripción general de los entornos espaciales

Se usa un SpatialEnvironment para administrar las preferencias del entorno espacial de una app. Es una composición de una imagen de skybox independiente y una geometría especificada en glTF. Solo se pueden establecer una imagen de skybox y un 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 cielo cúbico ni acercarse a él. El SDK de Jetpack XR admite skyboxes esféricos en el estándar OpenEXR. Además de proporcionar un fondo envolvente para tu app, un cielo cúbico 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 excelente manera de agregar realismo a tu entorno a través de elementos de primer plano y segundo plano que se combinan con el cielo cúbico 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 establecer el entorno espacial de tu app en una de estas tres configuraciones:

• Es 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 externas del dispositivo. Con opacidad total, esta superficie de transferencia ocluye por completo el cielo cúbico y la geometría.
• Una configuración mixta, en la que la superficie de transferencia no está en opacidad completa ni en opacidad cero. En este caso, la superficie de transferencia se vuelve semitransparente y se combina con el cielo y la geometría que se encuentran detrás.

Nota: Cuando configuras preferencias para SpatialEnvironment, los métodos no necesariamente se aplican de inmediato. En cambio, estos métodos establecen una preferencia que se aplicará cuando el dispositivo entre en un estado en el que se pueda cambiar el entorno de la app. En los fragmentos de código, verás los objetos de escucha para controlar estos cambios de estado.

Capacidades 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 modo de transferencia 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 con la clase Session.

Crea un recurso glTF

Un recurso glTF se puede crear 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"))
Environments.kt

Crea un recurso de imagen EXR

Se puede crear un recurso de imagen EXR como un ExrImage, en el que el EXR se carga desde un archivo local. Se puede usar un ExrImage con cmgen para crear un archivo ZIP del IBL para tus skyboxes. Consulta nuestra guía para optimizar los recursos del entorno y obtener más detalles.

val lightingForSkybox = ExrImage.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))
Environments.kt

Establece el SpatialEnvironmentPreference para tu app

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

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

Si el SpatialEnvironmentPreference proporcionado 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 los recursos de geometría y cielo esférico del entorno 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.

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.
}
Environments.kt

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 y, luego, implementar un addOnSpatialEnvironmentChangedListener para determinar cuándo deseas establecer la preferencia del entorno espacial.

Establece el valor de 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 provoca un cambio inmediato, a menos que la capacidad de SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL esté disponible. Una vez que el dispositivo entra en un estado en el que se puede cambiar la opacidad de la visualización a través de la cámara y la capacidad de SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL está disponible, se aplicará automáticamente la opacidad de la visualización a través de la cámara preferida para la aplicación.

Los valores de preferencia de opacidad de transferencia varían de 0.0f (opacidad cero, en la que no se ve la superficie de transferencia) 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 se establece el valor como 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.
}
Environments.kt

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.

Cómo determinar la opacidad actual del modo de transferencia

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity
Environments.kt

Consulta también

• Orientación para el diseño de entornos espaciales