{ } { }

Jetpack SceneCore

Cómo declarar dependencias

Para agregar una dependencia en XR SceneCore, debes agregar el repositorio de Maven de Google a tu proyecto. Consulta el repositorio de Maven de Google para obtener más información.

Agrega las dependencias de los artefactos que necesites en el archivo build.gradle de tu app o módulo:

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha04"
    // Required for Java
    implementation "com.google.guava:listenablefuture:1.0"
    // Required for Kotlin
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0"

    // Use to write unit tests
    testImplementation "androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04"
}

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha04")
    // Required for Java
    implementation("com.google.guava:listenablefuture:1.0")
    // Required for Kotlin
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0")

    // Use to write unit tests
    testImplementation("androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04")
}

Para obtener más información sobre las dependencias, consulta Cómo agregar dependencias de compilación.

Comentarios

Tus comentarios ayudan a mejorar Jetpack. Avísanos si descubres nuevos errores o tienes ideas para mejorar esta biblioteca. Consulta los errores existentes de esta biblioteca antes de crear uno nuevo. Puedes agregar tu voto a un error existente haciendo clic en el botón de la estrella.

Crear un error nuevo

Consulta la documentación sobre la Herramienta de seguimiento de errores para obtener más información.

Versión 1.0

Versión 1.0.0-alpha04

7 de mayo de 2025

Lanzamiento de androidx.xr.scenecore:scenecore:1.0.0-alpha04 y androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04. La versión 1.0.0-alpha04 contiene estas confirmaciones.

Nuevas funciones

• El manejo de Atrás ahora funcionará en entidades de panel sin actividades incorporadas. Para que funcione el manejo de atrás, debes especificar android:enableOnBackInvokedCallback= "true" en el manifiesto de Android.
• StereoSurfaceEntity ahora admite la reproducción de MV-HEVC a través de dos nuevos valores de StereoMode: MULTIVIEW_LEFT_PRIMARY y MULTIVIEW_RIGHT_PRIMARY.
• PanelEntity.setSize y PanelEntity.getSize ahora muestran tamaños en el espacio superior.
• Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha y Entity.getAlpha ahora toman un nuevo parámetro relativeTo, que permite obtener o establecer valores en relación con diferentes espacios. Los valores admitidos son Parent, Activity y Real World spaces, y el valor predeterminado para este parámetro es Parent.
• Se agregaron métodos de extensión de devolución de llamada de visibilidad espacial a SessionExt.kt para supervisar cuándo el contenido de la escena se mueve dentro o fuera del campo de visión del usuario.
• Se agregó setPointSourceParams a SpatialAudioTrack, lo que permite que los parámetros se actualicen después de que se haya compilado el segmento.
• Se agregó una clase nueva, Scene, con referencias a las APIs de Scenecore. Se podrá acceder a la escena como una propiedad de extensión de la sesión. Las funciones dentro de SessionExt se movieron a Scene, por lo que se deberán ajustar las importaciones, por ejemplo, SessionExt.getScene(session).addSpatialCapababilitiesChangedListener en comparación con SessionExt.addSpatialCapabilitiesChangedListener
• Se agregó ActivityPose.hitTestAsync, lo que habilita un hitTest contra el contenido virtual.
• Se agregó un nuevo tipo de componente SpatialPointerComponent, que permite a los clientes especificar el ícono renderizado para el puntero o inhabilitarlo. Actualmente, este componente solo se puede adjuntar a instancias de PanelEntity.
• Se presentó la nueva fábrica PanelEntity, que toma las dimensiones del panel en metros o píxeles. Se quitó la fábrica PanelEntity anterior que tomaba dos parámetros de tipo de dimensión para el panel.

Cambios en la API

• Se quitó la restricción de RequiresApi(34) en todos los paquetes de Jetpack XR. Esta restricción era redundante, ya que Jetpack XR actualmente solo está disponible en dispositivos con nivel de API 34 y versiones posteriores. (Iae0f8)
• Los proyectos lanzados con Kotlin 2.0 requieren KGP 2.0.0 o una versión posterior para su consumo (Idb6b5).
• Se quitó la clase PermissionHelper.
• PanelEntity.getPixelDensity ya no está disponible.
• Se quitaron PanelEntity.setPixelDimensions y PanelEntity.getPixelDimension, y se reemplazaron por setSizeInPixels y getSizeInPixels.
• Se quitó Entity.getActivitySpaceAlpha. Se puede reemplazar por Entity.getAlpha(Space.Activity).
• Se quitó Entity.getWorldSpaceScale. Se puede reemplazar por Entity.getScale(Space.REAL\_WORLD).
• Se borró la clase Session en SceneCore en favor de la sesión en XR Runtime.
• El nombre de StereoSurfaceEntity cambió por SurfaceEntity.
• Se quitaron Entity.setSize y Entity.getSize, y se agregaron los mismos métodos a PanelEntity.
• El nombre de PointSourceAttributes cambió por PointSourceParams.
• El nombre de SpatializerConstants.SOURCE\_TYPE\_BYPASS cambió por SpatializerConstants.SOURCE\_TYPE\_DEFAULT.
• Se modificó la entidad PointSourceParams de acceso público a acceso interno.
• AnchorEntity.create ahora requiere que PlaneTrackingMode se configure en Session.configure().
• Las APIs de SpatialUser ahora requieren que HeadTrackingMode se configure en Session.configure().
• Cuando no se adjunte ResizableComponent, se mostrará el registro a nivel de INFO en lugar del registro a nivel de ERROR.
• La clase Fov ahora es una clase normal de Kotlin.
• Divide Entity.kt para colocar cada tipo de entidad concreta en su propio archivo.
• Cuando crees un PanelEntity nuevo, la mayoría de las vistas se volverán a asignar a un FrameLayout. Esto facilita el uso de LayoutInspector con paneles espaciales.
• La instancia de XrExtensions que se usa actualmente ahora se registra en la plataforma, de la mejor manera posible, para ayudar con la depuración de la app.

Correcciones de errores

• Se agregó una corrección para evitar una falla que podía ocurrir cuando se movía un PanelEntity con MovableComponent y AnchorPlacement.
• Se solucionó un problema por el que ResizableComponent proporcionaba tamaños inactivos en la devolución de llamada de onResizeStart.
• Se corrigió la falla que se producía cuando se llamaba a dispose() de JxrPlatformAdapterAxr varias veces.

Versión 1.0.0-alpha03

26 de febrero de 2025

Lanzamiento de androidx.xr.scenecore:scenecore:1.0.0-alpha03 y androidx.xr.scenecore:scenecore-testing:1.0.0-alpha03. La versión 1.0.0-alpha03 contiene estas confirmaciones.

Nuevas funciones

• La reducción de Proguard ahora es compatible con el código de Jetpack XR.

Correcciones de errores

• Se realizaron correcciones adicionales para admitir la reducción de Proguard para Jetpack XR SceneCore (I4f47e).
• Se actualizó la regla ProGuard de Scenecore de Jetpack XR para evitar AbstractMethodError para clientes reducidos. (I91a01)

Versión 1.0.0-alpha02

12 de febrero de 2025

Lanzamiento de androidx.xr.scenecore:scenecore:1.0.0-alpha02 y androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02. La versión 1.0.0-alpha02 contiene estas confirmaciones.

Próximo cambio rotundo que afectará a las apps compiladas antes de la versión 1.0.0-alpha02

• Los métodos de fábrica se movieron de la clase Session a un método complementario en cada tipo respectivo:
  • Se borró Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) y se reemplazó por ActivityPanelEntity.create(Session, Dimensions, String, Pose).
  • Se borró Session.createAnchorEntity(Anchor) y se reemplazó por AnchorEntity.create(Session, Anchor).
  • Se borró Session.createAnchorEntity(Dimensions, Int, Int, Duration) y se reemplazó por AnchorEntity.create(Session, Dimensions, Int, Int, Duration).
  • Se borró Session.createEntity(String, Pose) y se reemplazó por ContentlessEntity.create(Session, String, Pose).
  • Se borró Session.createExrImageResource(String) y se reemplazó por ExrImage.create(Session, String).
  • Se borró Session.createGltfEntity(GltfModel, Pose) y se reemplazó por GltfModelEntity.create(Session, GltfModel, Pose).
  • Se borró Session.createGltfModelResource(String) y se reemplazó por GltfModel.create(Session, String).
  • Se borró Session.createInteractableComponent(Executor, InputEventListener) y se reemplazó por InteractableComponent.create(Session, Executor, InputEventListener).
  • Se borró Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) y se reemplazó por MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean).
  • Se borró Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) y se reemplazó por PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose).
  • Se borró Session.createResizableComponent(Dimensions, Dimensions) y se reemplazó por ResizableComponent.create(Session, Dimensions, Dimensions).
  • Se borró Session.createStereoSurfaceEntity(Int, Dimensions, Pose) y se reemplazó por StereoSurface.create(Session, Int, Dimensions, Pose).
• Se quitaron los siguientes métodos obsoletos:
  • Se borró Session.canEmbedActivityPanel(Activity). Usa getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY) en su lugar.
  • Se borró Session.hasSpatialCapability(Int). Se reemplazó por el uso de getSpatialCapabilities().hasCapability() como una forma más compartimentada de verificar la presencia de capacidades espaciales, ya que getSpatialCapabilities() muestra un objeto SpatialCapabilities.
  • Se borró Session.requestFullSpaceMode() y se reemplazó por SpatialEnvironment.requestFullSpaceMode().
  • Se borró Session.requestHomeSpaceMode() y se reemplazó por SpatialEnvironment.requestHomeSpaceMode().
• Session.setFullSpaceMode(Bundle) y Session.setFullSpaceModeWithEnvironmentInherited(Bundle) se movieron a las funciones de extensión. Los archivos del desarrollador deberán agregar las importaciones nuevas para acceder a ellos:
  • import androidx.xr.scenecore.setFullSpaceMode
  • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
• Session.setPreferredAspectRatio(Activity, Float) se trasladó a una función de extensión. Los archivos del desarrollador deberán agregar la nueva importación para acceder a ellos:
  • import androidx.xr.scenecore.setPreferredAspectRatio
• Session.getEntitiesOfType(Class<out T>) y Session.getEntityForRtEntity(RtEntity) se movieron a las funciones de extensión. Los archivos del desarrollador deberán agregar las importaciones nuevas para acceder a ellos:
  • import androidx.xr.scenecore.getEntitiesOfType
  • import androidx.xr.scenecore.getEntityForRtEntity
• Se borró Session.unpersistAnchor(Anchor)
• Se borró Session.createPersistedAnchorEntity(UUID)

Errores conocidos

• Es posible que PanelEntity.setCornerRadius() y ActivityPanelEntity.setCornerRadius() no surtan efecto hasta que se mueva el panel por primera vez. Para mitigar esto, mueve el panel a su posición actual.
• Cuando se llama a BoundsChanged en ActivitySpace, es posible que algunos ActivityPose no se hayan actualizado correctamente. Se actualizará en la siguiente llamada a OnSpaceUpdated el ActivitySpace

Cambios rotundos y de comportamiento

• PanelEntity y ActivityPanelEntity tendrán un radio de esquina predeterminado de 32 dp o menos si el panel tiene un ancho o una altura menores que 32 dp.

Nuevas APIs y funciones

• Se introdujo StereoSurface.CanvasShape, que permite la creación de lienzos Spherical y Hemispherical para renderizar contenido multimedia envolvente.
• StereoSurfaceEntity.create() ahora acepta un parámetro CanvasShape. (Por el momento, este parámetro se ignora, pero se usará en una versión futura).
• StereoSurfaceEntity.create() ya no toma un parámetro Dimensions. Las aplicaciones deben controlar el tamaño del lienzo configurando CanvasShape.
• StereoSurfaceEntity tiene un miembro CanvasShape que se puede configurar de forma dinámica.
• StereoSurfaceEntity.dimensions ahora es una propiedad de solo lectura. Las aplicaciones deben establecer CanvasShape para cambiar las dimensiones.
• StereoSurfaceEntity ahora permite que se vuelva a establecer StereoMode después de la construcción.

Otros cambios

• Se redujo el minSDK del tiempo de compilación a 24. Todas las APIs de Jetpack XR siguen requiriendo la API 34 en el entorno de ejecución.
• La fábrica de sesiones de SceneCore (Session.create) ya no inicia un intent para adquirir el permiso SCENE_UNDERSTANDING. En su lugar, la aplicación cliente debe solicitar los permisos al usuario de forma explícita antes de intentar crear los anclajes. La creación de la ancla fallará si el usuario no otorga el permiso.

Correcciones de errores

• Se corrigió getActivitySpacePose() para tener en cuenta la escala de ActivitySpace, ya que muestra valores de traducción en metros ajustados en lugar de mostrar siempre metros no ajustados. transformPoseTo ahora también usa las unidades correctas para calcular los cambios de coordenadas cuando ActivitySpace está involucrado en la fuente o el destino.
• El cielo ahora se establecerá en negro cuando se pase una preferencia de cielo nula con setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Para volver al cielo y la geometría predeterminados del sistema, usa setSpatialEnvironmentPreference(null)..

Versión 1.0.0-alpha01

12 de diciembre de 2024

Lanzamiento de androidx.xr.scenecore:scenecore-* 1.0.0-alpha01.

Funciones de la versión inicial Versión inicial para desarrolladores de Jetpack SceneCore, una biblioteca de gráficos de escenas en 3D para crear y manipular escenas y entornos envolventes. Esta biblioteca te permite colocar y organizar modelos 3D y paneles de contenido en relación con los demás y tus entornos virtuales o del mundo real.

• SpatialEnvironment: Crea experiencias completamente envolventes con una imagen de cielo o una geometría de modelo 3D como telón de fondo para la escena de XR de tu entorno. O bien habilita la transferencia para que tu escena virtual se pueda integrar en el entorno real del usuario.
• PanelEntity: Agrega contenido 2D a tus escenas 3D incorporando diseños y actividades estándar de Android en paneles espacializados que pueden flotar o anclarse a superficies del mundo real.
• GltfModelEntity: Coloca, anima e interactúa con modelos 3D en tu escena. SceneCore admite el formato de archivo glTF para facilitar la integración con modelos existentes.
• SpatialAudio: Agrega fuentes de audio ambiente y puntuales a tu escena 3D para obtener un sonido espacializado y totalmente envolvente.
• StereoSurfaceEntity: SceneCore admite el enrutamiento de contenido renderizado en una superficie de Android para el ojo izquierdo o derecho. Se puede usar para renderizar contenido estereoscópico en un formato en paralelo o de arriba abajo, como fotos estéreo, videos en 3D y otras IU renderizadas de forma dinámica. Las aplicaciones deben usar MediaPlayer o ExoPlayer para la decodificación de video.
• Sistema de componentes: SceneCore ofrece un sistema de componentes sólido y flexible para agregar capacidades a tu contenido de XR, incluidas indicaciones visuales para que los usuarios muevan, cambien de tamaño e interactúen con modelos y paneles.
• Anclaje: Con la transferencia directa habilitada, puedes conectar paneles y modelos a superficies reales, lo que les brinda a los usuarios una integración perfecta del contenido virtual en su entorno real.
• Posición del usuario: Accede a la ubicación del usuario en la escena virtual para orientar tu contenido en función de su posición.
• SpatialCapabilities: Compila apps totalmente adaptables que aprovechen las capacidades espacializadas cuando estén disponibles, como el posicionamiento 3D del contenido de la IU. Además, tu app puede supervisar los cambios en las funciones mientras se ejecuta para modificar la experiencia según la forma en que el usuario usa su dispositivo Android XR.

Errores conocidos

• Actualmente, se requiere un minSDK de 30 para usar Jetpack SceneCore. Como solución alternativa, agrega la siguiente entrada de manifiesto <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> para poder compilar y ejecutar con un minSDK de 23.
• La sesión puede dejar de ser válida en varias situaciones que recrean automáticamente la actividad, como cambiar el tamaño de un panel principal, conectar periféricos y cambiar entre el modo oscuro y el modo claro. Si tienes problemas de invalidación de la sesión, las soluciones incluyen hacer que el panel principal no se pueda cambiar de tamaño, usar una entidad de panel dinámico, inhabilitar la recreación de actividades para cambios de configuración específicos o inhabilitar los cambios de tema del modo oscuro o claro.
• Los componentes móviles y de tamaño variable no son compatibles con GltfEntity.
• Entity.getSize() no es compatible con GltfEntity.
• Las apps de Jetpack XR deben solicitar el permiso android.permission.SCENE_UNDERSTANDING en AndroidManifest.
• La creación de una sesión solo es compatible con un dispositivo Android XR. En este momento, si creas una sesión y tratas de usarla en un dispositivo que no sea Android XR, obtendrás una RuntimeException.
• Establecer el cielo en nulo a través de "SpatialEnvironment.setSpatialEnvironmentPreference()" no genera un cielo negro sólido como se documenta. Es posible que se muestre el cielo predeterminado del sistema o que no se realice ningún cambio en el cielo actual.
• Los clientes de SceneCore deben agregar implementation(“com.google.guava:listenablefuture-1.0”) a su configuración de Gradle para las dependencias de su app. En una versión futura, scenecore incluirá esta biblioteca como una dependencia de api para que los clientes no tengan que declararla de forma explícita.
• SceneCore incluye erróneamente com.google.guava:guava-31.1-android y com.google.protobuf:protobuf-javalite como dependencias transitivas. Si esto genera errores de clase duplicados en tu compilación, se pueden excluir estas dos dependencias de forma segura.
• Si tu app usa SceneCore y habilita ProGuard, fallará cuando creas una sesión. Como solución alternativa, inhabilita ProGuard. Consulta esta guía para obtener más información sobre cómo habilitar ProGuard.