Agrega entornos espaciales a tu app

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

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 el espacio completo.

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 la 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

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 environmentGeometryFuture = GltfModel.create(session, "DayGeometry.glb")
val environmentGeometry = environmentGeometryFuture.await()
Environments.kt

Crea un recurso de imagen EXR

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

val lightingForSkybox = ExrImage.create(session, "BlueSkyboxLighting.zip")
Environments.kt

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 configurar su propio entorno.

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
val preferenceResult =
    session.scene.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.
}
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 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.

val preferenceResult = session.scene.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
}
Environments.kt

Uso avanzado

Para casos de uso más avanzados en los que necesitas un control más detallado 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 tus recursos 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 sobre cómo optimizar los recursos de entorno.

Determina la opacidad de transferencia actual

val currentPassthroughOpacity = session.scene.spatialEnvironment.getCurrentPassthroughOpacity()
Environments.kt

Consulta también

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