Реактивный ранец SceneCore

Создавайте и управляйте графом сцены Android XR с 3D-контентом.
Последнее обновление Стабильный релиз Кандидат на релиз Бета-версия Альфа-релиз
7 мая 2025 г. - - - 1.0.0-альфа04

Объявление зависимостей

Чтобы добавить зависимость от XR SceneCore, необходимо добавить репозиторий Google Maven в свой проект. Подробнее см. в репозитории Google Maven .

Добавьте зависимости для необходимых артефактов в файл build.gradle вашего приложения или модуля:

классный 

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")
}

Дополнительные сведения о зависимостях см. в разделе Добавление зависимостей сборки .

Обратная связь

Ваши отзывы помогают улучшить Jetpack. Сообщите нам, если вы обнаружите новые проблемы или у вас есть идеи по улучшению этой библиотеки. Пожалуйста, ознакомьтесь с уже существующими проблемами в этой библиотеке, прежде чем создавать новую. Вы можете проголосовать за существующую проблему, нажав на кнопку со звёздочкой.

Создать новый выпуск

Более подробную информацию см. в документации по системе отслеживания проблем .

Версия 1.0

Версия 1.0.0-альфа04

7 мая 2025 г.

Выпущены androidx.xr.scenecore:scenecore:1.0.0-alpha04 и androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04 . Версия 1.0.0-alpha04 содержит эти коммиты .

Новые функции

  • Обратный доступ теперь будет работать с сущностями панели без встроенных действий. Для этого необходимо указать android:enableOnBackInvokedCallback= "true" в манифесте Android.
  • StereoSurfaceEntity теперь поддерживает воспроизведение MV-HEVC с помощью двух новых значений StereoMode : MULTIVIEW_LEFT_PRIMARY и MULTIVIEW_RIGHT_PRIMARY.
  • PanelEntity.setSize и PanelEntity.getSize теперь возвращают размеры в родительском пространстве.
  • Entity.setPose , Entity.getPose , Entity.setScale , Entity.getScale , Entity.setAlpha и Entity.getAlpha теперь принимают новый параметр relativeTo , который позволяет получать/устанавливать значения относительно различных пространств. Поддерживаются значения Parent, Activity и Real World, а значение по умолчанию для этого параметра — Parent.
  • В SessionExt.kt добавлены методы расширения обратного вызова пространственной видимости для отслеживания того, когда содержимое сцены перемещается внутрь или за пределы поля зрения пользователя.
  • В SpatialAudioTrack добавлен setPointSourceParams , позволяющий обновлять параметры после создания трека.
  • Добавлен новый класс Scene со ссылками на API Scenecore . Scene будет доступен как свойство расширения Session. Функции внутри SessionExt перенесены в Scene, поэтому импорт потребуется скорректировать; например, SessionExt.getScene(session) . addSpatialCapababilitiesChangedListener вместо SessionExt.addSpatialCapabilitiesChangedListener .
  • Добавлен ActivityPose.hitTestAsync , позволяющий проводить hitTest по виртуальному содержимому.
  • Добавлен новый тип компонента SpatialPointerComponent , позволяющий клиентам указывать значок, отображаемый для указателя, или отключать его. В настоящее время этот компонент можно прикрепить только к экземплярам PanelEntity .
  • Представляем новую фабрику PanelEntity , которая принимает размеры панели в метрах или пикселях. Старая фабрика PanelEntity , принимавшая два параметра типа «Размер» для панели, удалена.

Изменения API

  • Убрано ограничение RequiresApi(34) для всех пакетов Jetpack XR. Это ограничение было излишним, поскольку Jetpack XR в настоящее время доступен только на устройствах с API уровня 34 и выше. ( Iae0f8 )
  • Для проектов, выпущенных с использованием Kotlin 2.0, требуется использование KGP 2.0.0 или более поздней версии ( Idb6b5 ).
  • Класс PermissionHelper был удален.
  • PanelEntity.getPixelDensity устарел.
  • PanelEntity.setPixelDimensions и PanelEntity.getPixelDimension удалены и заменены на setSizeInPixels и getSizeInPixels .
  • Entity.getActivitySpaceAlpha удалён. Его можно заменить на Entity.getAlpha(Space.Activity) .
  • Entity.getWorldSpaceScale удалён. Его можно заменить на Entity.getScale(Space.REAL\_WORLD) .
  • Класс Session в SceneCore был удален в пользу Session в XR Runtime.
  • StereoSurfaceEntity переименован в SurfaceEntity .
  • Entity.setSize и Entity.getSize удалены, а те же методы добавлены в PanelEntity .
  • PointSourceAttributes был переименован в PointSourceParams .
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS переименован в SpatializerConstants.SOURCE\_TYPE\_DEFAULT .
  • Доступ к сущности PointSourceParams был изменен с публичного на внутренний.
  • AnchorEntity.create теперь требует настройки PlaneTrackingMode в Session.configure() .
  • Для API SpatialUser теперь требуется настройка HeadTrackingMode в Session.configure() .
  • Если ResizableComponent не подключен, будет выдан журнал уровня INFO вместо журнала уровня ERROR.
  • Класс Fov теперь является обычным классом Kotlin.
  • Разделите Entity.kt , чтобы поместить каждый конкретный тип сущности в отдельный файл.
  • При создании нового PanelEntity большинство представлений будут перенаправлены на FrameLayout . Это упрощает использование LayoutInspector с пространственными панелями.
  • Текущий используемый экземпляр XrExtensions теперь зарегистрирован на платформе, чтобы облегчить отладку приложения.

Исправление ошибок

  • Добавлено исправление для предотвращения сбоя, который мог возникнуть при перемещении PanelEntity с MovableComponent и AnchorPlacement .
  • Исправлена ​​ошибка, из-за которой ResizableComponent предоставлял устаревшие размеры в обратном вызове onResizeStart .
  • Исправлен сбой при многократном вызове метода dispose() JxrPlatformAdapterAxr .

Версия 1.0.0-альфа03

26 февраля 2025 г.

Выпущены androidx.xr.scenecore:scenecore:1.0.0-alpha03 и androidx.xr.scenecore:scenecore-testing:1.0.0-alpha03 . Версия 1.0.0-alpha03 содержит эти коммиты .

Новые функции

  • Минификация Proguard теперь поддерживается для кода Jetpack XR.

Исправление ошибок

  • Дополнительные исправления для поддержки минимизации Proguard для Jetpack XR SceneCore ( I4f47e )
  • Обновлено правило Jetpack XR Scenecore ProGuard для предотвращения AbstractMethodError для минифицированных клиентов. ( I91a01 )

Версия 1.0.0-альфа02

12 февраля 2025 г.

Выпущены androidx.xr.scenecore:scenecore:1.0.0-alpha02 и androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02 . Версия 1.0.0-alpha02 содержит эти коммиты .

Предстоящие критические изменения, затрагивающие приложения, созданные до версии 1.0.0-alpha02

  • Фабричные методы были перенесены из класса Session в сопутствующий метод для каждого соответствующего типа:
    • Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) был удален и заменен на ActivityPanelEntity.create(Session, Dimensions, String, Pose)
    • Session.createAnchorEntity(Anchor) был удален и заменен на AnchorEntity.create(Session, Anchor)
    • Session.createAnchorEntity(Dimensions, Int, Int, Duration) был удален и заменен на AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
    • Session.createEntity(String, Pose) был удален и заменен на ContentlessEntity.create(Session, String, Pose)
    • Session.createExrImageResource(String) был удален и заменен на ExrImage.create(Session, String)
    • Session.createGltfEntity(GltfModel, Pose) был удален и заменен на GltfModelEntity.create(Session, GltfModel, Pose)
    • Session.createGltfModelResource(String) был удален и заменен на GltfModel.create(Session, String)
    • Session.createInteractableComponent(Executor, InputEventListener) был удален и заменен на InteractableComponent.create(Session, Executor, InputEventListener)
    • Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) был удален и заменен на MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) был удален и заменен на PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
    • Session.createResizableComponent(Dimensions, Dimensions) был удален и заменен на ResizableComponent.create(Session, Dimensions, Dimensions)
    • Session.createStereoSurfaceEntity(Int, Dimensions, Pose) был удален и заменен на StereoSurface.create(Session, Int, Dimensions, Pose)
  • Были удалены следующие устаревшие методы:
    • Session.canEmbedActivityPanel(Activity) удалён. Вместо него используйте getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY) .
    • Session.hasSpatialCapability(Int) был удалён. Он был заменён на метод getSpatialCapabilities().hasCapability() как более фрагментированный способ проверки наличия пространственных возможностей, поскольку getSpatialCapabilities() возвращает объект SpatialCapabilities .
    • Session.requestFullSpaceMode() был удален и заменен на SpatialEnvironment.requestFullSpaceMode()
    • Session.requestHomeSpaceMode() был удален и заменен на SpatialEnvironment.requestHomeSpaceMode()
  • Session.setFullSpaceMode(Bundle) и Session.setFullSpaceModeWithEnvironmentInherited(Bundle) перенесены в функции расширения. Для доступа в файлы разработчика необходимо добавить новые импорты:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) перенесен в функцию расширения. Для доступа к файлам разработчика потребуется добавить новый импорт:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) и Session.getEntityForRtEntity(RtEntity) перенесены в функции расширения. Для доступа к ним в файлы разработчика необходимо добавить новые импорты:
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • Session.unpersistAnchor(Anchor) был удален
  • Session.createPersistedAnchorEntity(UUID) был удален

Известные проблемы

  • PanelEntity.setCornerRadius() и ActivityPanelEntity.setCornerRadius() могут не вступить в силу до следующего перемещения панели. Это можно устранить, переместив панель в ее текущее положение.
  • При вызове BoundsChanged в ActivitySpace некоторые ActivityPose могли быть обновлены неправильно. Они будут обновлены при следующем вызове OnSpaceUpdated в ActivitySpace

Нарушения и поведенческие изменения

  • PanelEntity и ActivityPanelEntity будут иметь радиус угла по умолчанию 32dp или меньше, если ширина или высота панели меньше 32dp.

Новые API и возможности

  • Представлен StereoSurface.CanvasShape , который позволяет создавать Spherical и Hemispherical холсты для рендеринга иммерсивных медиа.
  • StereoSurfaceEntity.create() теперь принимает параметр CanvasShape . (Этот параметр в настоящее время игнорируется, но будет использоваться в будущей версии.)
  • StereoSurfaceEntity.create() больше не принимает параметр Dimensions . Приложения должны управлять размером холста, устанавливая CanvasShape
  • StereoSurfaceEntity имеет элемент CanvasShape , который можно задавать динамически.
  • StereoSurfaceEntity.dimensions теперь является свойством только для чтения; для изменения размеров приложениям следует задать CanvasShape .
  • StereoSurfaceEntity теперь позволяет сбрасывать StereoMode после построения.

Другие изменения

  • MinSDK для времени компиляции уменьшен до 24. Все API Jetpack XR по-прежнему требуют API 34 во время выполнения.
  • Фабрика сеансов SceneCore ( Session.create ) больше не запускает намерение получить разрешение SCENE_UNDERSTANDING . Вместо этого клиентское приложение должно явно запросить разрешения у пользователя, прежде чем пытаться создать якоря. Создание якоря завершится ошибкой, если пользователь не предоставит разрешение.

Исправления ошибок

  • getActivitySpacePose() был исправлен для учета масштаба ActivitySpace путем возврата значений перевода в масштабированных метрах, а не всегда в немасштабированных метрах. transformPoseTo теперь также использует правильные единицы для вычисления изменений координат, когда ActivitySpace участвует в исходном или целевом объекте.
  • Теперь при передаче нулевого значения параметра скайбокса с помощью setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) скайбокс будет полностью чёрным. Чтобы вернуться к системному скайбоксу и геометрии по умолчанию, используйте setSpatialEnvironmentPreference(null).

Версия 1.0.0-альфа01

12 декабря 2024 г.

Выпущен androidx.xr.scenecore:scenecore-* 1.0.0-alpha01 .

Возможности первого выпуска: первый релиз Jetpack SceneCore для разработчиков, библиотеки 3D-графов сцен для создания и управления иммерсивными сценами и окружениями. Эта библиотека позволяет размещать и упорядочивать 3D-модели и панели контента относительно друг друга, а также виртуальной или реальной среды.

  • SpatialEnvironment : Создавайте полностью захватывающие впечатления, используя изображение скайбокса и/или геометрию 3D-модели в качестве фона для вашей XR-сцены вашего окружения. Или включите сквозное изображение, чтобы ваша виртуальная сцена интегрировалась с реальным окружением пользователя.
  • PanelEntity : добавляйте 2D-контент в 3D-сцены, встраивая стандартные макеты Android и действия в пространственные панели, которые могут перемещаться или прикрепляться к реальным поверхностям.
  • GltfModelEntity : размещайте, анимируйте и взаимодействуйте с 3D-моделями в вашей сцене. SceneCore поддерживает формат файлов glTF для простой интеграции с существующими моделями.
  • SpatialAudio : добавьте окружающие и точечные источники звука в вашу 3D-сцену для получения полностью иммерсивного, пространственного звука.
  • StereoSurfaceEntity : SceneCore поддерживает маршрутизацию контента, отображаемого на Android Surface, для левого и правого глаза. Это может использоваться для рендеринга стереоскопического контента в формате «бок о бок» или «сверху вниз», например, стереофотографий, 3D-видео или других динамически визуализируемых пользовательских интерфейсов. Приложения должны использовать MediaPlayer или ExoPlayer для декодирования видео.
  • Система компонентов: SceneCore предлагает надежную и гибкую систему компонентов для добавления возможностей к вашему XR-контенту, включая возможности для пользователей перемещать, изменять размер и взаимодействовать с моделями и панелями.
  • Якорь : при включенной функции сквозного пропуска вы можете прикреплять панели и модели к реальным поверхностям, предоставляя пользователям возможность бесшовной интеграции виртуального контента в реальную среду.
  • Поза пользователя: получите доступ к местоположению пользователя на виртуальной сцене, чтобы сориентировать контент относительно его положения.
  • SpatialCapabilities : создавайте полностью адаптивные приложения, использующие пространственные возможности (при их наличии), такие как 3D-позиционирование содержимого пользовательского интерфейса. Более того, ваше приложение может отслеживать изменения возможностей во время выполнения, чтобы адаптировать интерфейс в зависимости от того, как пользователь использует своё устройство Android XR.

Известные проблемы

  • В настоящее время для использования Jetpack SceneCore требуется minSDK 30. В качестве обходного решения добавьте следующую запись в манифест <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> , чтобы сборка и запуск были возможны с minSDK 23.
  • Сеанс может стать недействительным в различных ситуациях, которые автоматически пересоздают Activity, включая изменение размера главной панели, подключение периферийных устройств и переключение между светлым и тёмным режимами. В случае возникновения проблем с недействительностью сеанса можно сделать главную панель неизменяемой, использовать динамическую панель, отключить воссоздание Activity для определённых изменений конфигурации или отключить смену тем оформления в светлом/тёмном режиме.
  • Перемещаемые и изменяемые по размеру компоненты не поддерживаются в GltfEntity.
  • Entity.getSize() не поддерживается в GltfEntity.
  • Приложения Jetpack XR должны запрашивать разрешение android.permission.SCENE_UNDERSTANDING в AndroidManifest.
  • Создание сеанса поддерживается только на устройствах Android XR. В настоящее время при создании сеанса и попытке использовать его на устройстве, отличном от Android XR, возникнет исключение RuntimeException.
  • Установка скайбокса в значение null с помощью `SpatialEnvironment.setSpatialEnvironmentPreference() не приводит к созданию сплошного чёрного скайбокса, как описано в документации. Это может привести к использованию системного скайбокса по умолчанию или отсутствию изменений в текущем скайбоксе.
  • Клиентам SceneCore следует добавить implementation(“com.google.guava:listenablefuture-1.0”) в конфигурацию Gradle для зависимостей своего приложения. В будущем выпуске SceneCore включит эту библиотеку как зависимость api поэтому клиентам не придётся явно её объявлять.
  • SceneCore ошибочно включает com.google.guava:guava-31.1-android и com.google.protobuf:protobuf-javalite как транзитивные зависимости. Если это приводит к ошибкам дублирования классов в вашей сборке, эти две зависимости можно безопасно исключить.
  • Если ваше приложение использует SceneCore и включает ProGuard, оно аварийно завершится при создании сеанса. В качестве временного решения отключите ProGuard. Подробнее о включении ProGuard см. в этом руководстве .