Jetpack SceneCore

3D 콘텐츠로 Android XR 장면 그래프를 빌드하고 조작합니다.
최근 업데이트 안정화 버전 출시 후보 버전 베타 버전 알파 버전
2025년 5월 7일 - - - 1.0.0-alpha04

종속 항목 선언

XR SceneCore의 종속 항목을 추가하려면 프로젝트에 Google Maven 저장소를 추가해야 합니다. 자세한 내용은 Google Maven 저장소를 읽어보세요.

다음과 같이 앱 또는 모듈의 build.gradle 파일에 필요한 아티팩트의 종속 항목을 추가합니다.

Groovy

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

Kotlin

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을 개선하는 데 도움이 됩니다. 새로운 문제를 발견하거나 라이브러리 개선을 위한 아이디어가 있다면 Google에 알려 주세요. 새 문제를 제출하기 전에 이 라이브러리의 기존 문제를 살펴보시기 바랍니다. 별표 버튼을 클릭하여 기존 문제에 투표할 수 있습니다.

새로운 문제 제출하기

자세한 내용은 Issue Tracker 문서를 참고하세요.

버전 1.0

버전 1.0.0-alpha04

2025년 5월 7일

androidx.xr.scenecore:scenecore:1.0.0-alpha04 및 androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04이 출시되었습니다. 버전 1.0.0-alpha04에는 이러한 커밋이 포함되어 있습니다.

새로운 기능

  • 이제 백핸들링이 활동이 삽입되지 않은 패널 항목에서 작동합니다. 뒤로 처리가 작동하려면 Android 매니페스트에 android:enableOnBackInvokedCallback= "true"를 지정해야 합니다.
  • 이제 StereoSurfaceEntity는 MULTIVIEW_LEFT_PRIMARY 및 MULTIVIEW_RIGHT_PRIMARY라는 두 개의 새로운 StereoMode 값을 통해 MV-HEVC 재생을 지원합니다.
  • 이제 PanelEntity.setSize 및 PanelEntity.getSize는 상위 공간의 크기를 반환합니다.
  • 이제 Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha, Entity.getAlpha가 새로운 매개변수 relativeTo를 사용하므로 다양한 공간과 관련된 값을 가져오거나 설정할 수 있습니다. 지원되는 값은 Parent, Activity, Real World 스페이스이며 이 매개변수의 기본값은 Parent입니다.
  • 사용자의 시야 내 또는 외부로 장면 콘텐츠가 이동하는 시점을 모니터링하기 위해 SessionExt.kt에 공간 가시성 콜백 확장 프로그램 메서드가 추가되었습니다.
  • setPointSourceParams이 SpatialAudioTrack에 추가되어 트랙이 빌드된 후 매개변수를 업데이트할 수 있습니다.
  • Scenecore API를 참조하는 새로운 클래스인 Scene이 추가되었습니다. 장면은 세션의 확장 프로그램 속성으로 액세스할 수 있습니다. SessionExt 내부의 함수가 장면으로 이동되었으므로 가져오기를 조정해야 합니다(예: SessionExt.getScene(session)).addSpatialCapababilitiesChangedListener 및 SessionExt.addSpatialCapabilitiesChangedListener 비교
  • ActivityPose.hitTestAsync가 추가되어 가상 콘텐츠에 대한 hitTest가 사용 설정되었습니다.
  • 클라이언트가 포인터에 렌더링된 아이콘을 지정하거나 아이콘을 사용 중지할 수 있는 새로운 구성요소 유형 SpatialPointerComponent이 추가되었습니다. 이 구성요소는 현재 PanelEntity 인스턴스에만 연결할 수 있습니다.
  • 패널 크기를 미터 또는 픽셀로 사용하는 새로운 PanelEntity 팩토리 도입 패널에 두 개의 Dimension 유형 매개변수를 사용하는 이전 PanelEntity 팩토리가 삭제되었습니다.

API 변경사항

  • 모든 Jetpack XR 패키지에서 RequiresApi(34) 제한을 삭제했습니다. 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)로 대체할 수 있습니다.
  • SceneCore의 세션 클래스가 XR 런타임의 세션을 위해 삭제되었습니다.
  • StereoSurfaceEntity에서 SurfaceEntity로 이름을 바꿨습니다.
  • Entity.setSize 및 Entity.getSize가 삭제되고 동일한 메서드가 PanelEntity에 추가되었습니다.
  • PointSourceAttributes에서 PointSourceParams로 이름을 바꿨습니다.
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS에서 SpatializerConstants.SOURCE\_TYPE\_DEFAULT로 이름을 바꿨습니다.
  • PointSourceParams 항목이 공개 액세스에서 내부 액세스로 수정되었습니다.
  • 이제 AnchorEntity.create에는 Session.configure()에서 PlaneTrackingMode가 구성되어야 합니다.
  • 이제 SpatialUser API에는 Session.configure()에서 HeadTrackingMode을 구성해야 합니다.
  • ResizableComponent가 연결되지 않으면 ERROR 수준 로그 대신 INFO 수준 로그가 제공됩니다.
  • Fov 클래스가 이제 일반 Kotlin 클래스입니다.
  • 각 구체적인 항목 유형을 자체 파일에 배치하도록 Entity.kt를 분할합니다.
  • 새 PanelEntity를 만들면 대부분의 뷰가 FrameLayout로 리페어런트됩니다. 이렇게 하면 공간 패널에서 LayoutInspector를 쉽게 사용할 수 있습니다.
  • 현재 사용 중인 XrExtensions 인스턴스가 앱 디버깅을 지원하기 위해 최선의 방식으로 플랫폼에 등록됩니다.

버그 수정

  • MovableComponent 및 AnchorPlacement이 있는 PanelEntity가 이동될 때 발생할 수 있는 비정상 종료를 방지하는 수정사항이 추가되었습니다.
  • ResizableComponent가 onResizeStart 콜백에서 오래된 크기를 제공하는 문제가 해결되었습니다.
  • JxrPlatformAdapterAxr의 dispose()이 여러 번 호출될 때 발생하는 비정상 종료 문제가 수정되었습니다.

버전 1.0.0-alpha03

2025년 2월 26일

androidx.xr.scenecore:scenecore:1.0.0-alpha03 및 androidx.xr.scenecore:scenecore-testing:1.0.0-alpha03이 출시되었습니다. 버전 1.0.0-alpha03에는 이 커밋이 포함되어 있습니다.

새로운 기능

  • 이제 Jetpack XR 코드에 Proguard 축소가 지원됩니다.

버그 수정

  • Jetpack XR SceneCore의 Proguard 축소를 지원하기 위한 추가 수정사항 (I4f47e)
  • 축소된 클라이언트의 AbstractMethodError를 방지하도록 Jetpack XR Scenecore ProGuard 규칙이 업데이트되었습니다. (I91a01)

버전 1.0.0-alpha02

2025년 2월 12일

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()는 SpatialCapabilities 객체를 반환하므로 공간 기능을 확인하는 더 세분화된 방법으로 getSpatialCapabilities().hasCapability()를 사용하는 것이 좋습니다.
    • 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()는 패널이 다음에 이동될 때까지 적용되지 않을 수 있습니다. 패널을 현재 위치로 이동하면 이 문제를 완화할 수 있습니다.
  • ActivitySpace에서 BoundsChanged가 호출되면 일부 ActivityPose가 올바르게 업데이트되지 않았을 수 있습니다. ActivitySpace의 다음 OnSpaceUpdated 통화에서 업데이트될 예정입니다.

브레이킹 및 동작 변경사항

  • 패널의 너비 또는 높이가 32dp보다 작은 경우 PanelEntity 및 ActivityPanelEntity의 기본 모서리 반경은 32dp 이하입니다.

새 API 및 기능

  • 몰입형 미디어를 렌더링하기 위한 Spherical 및 Hemispherical 캔버스를 만들 수 있는 StereoSurface.CanvasShape를 도입합니다.
  • 이제 StereoSurfaceEntity.create()는 CanvasShape 매개변수를 허용합니다. (이 매개변수는 현재 무시되지만 향후 출시에서 사용될 예정입니다.)
  • StereoSurfaceEntity.create()가 더 이상 Dimensions 매개변수를 사용하지 않습니다. 애플리케이션은 CanvasShape를 설정하여 캔버스 크기를 제어해야 합니다.
  • StereoSurfaceEntity에는 동적으로 설정할 수 있는 CanvasShape 멤버가 있습니다.
  • 이제 StereoSurfaceEntity.dimensions은 읽기 전용 속성입니다. 애플리케이션은 CanvasShape을 설정하여 크기를 변경해야 합니다.
  • 이제 StereoSurfaceEntity를 사용하면 생성 후 StereoMode을 다시 설정할 수 있습니다.

기타 변경사항

  • 컴파일 시간 minSDK를 24로 줄였습니다. 모든 Jetpack XR API는 런타임에 API 34가 계속 필요합니다.
  • SceneCore의 세션 팩토리 (Session.create)는 더 이상 SCENE_UNDERSTANDING 권한을 획득하기 위한 인텐트를 실행하지 않습니다. 대신 클라이언트 애플리케이션은 앵커를 생성하기 전에 사용자에게 권한을 명시적으로 요청해야 합니다. 사용자가 권한을 부여하지 않으면 앵커 생성이 실패합니다.

버그 수정

  • getActivitySpacePose()는 항상 스케일링되지 않은 미터를 반환하는 대신 스케일링된 미터로 변환 값을 반환하여 ActivitySpace 스케일을 고려하도록 수정되었습니다. 이제 transformPoseTo는 소스 또는 대상에 ActivitySpace가 포함된 경우 올바른 단위를 사용하여 좌표 변경사항을 계산합니다.
  • 이제 setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom))를 사용하여 null 스카이박스 환경설정이 전달되면 스카이박스가 완전한 검은색 스카이박스로 설정됩니다. 시스템 기본 스카이박스와 지오메트리로 되돌리려면 setSpatialEnvironmentPreference(null).를 사용하세요.

버전 1.0.0-alpha01

2024년 12월 12일

androidx.xr.scenecore:scenecore-* 1.0.0-alpha01이 출시되었습니다.

초기 출시 기능 몰입형 장면과 환경을 만들고 조작하기 위한 3D 장면 그래프 라이브러리인 Jetpack SceneCore의 초기 개발자 출시입니다. 이 라이브러리를 사용하면 3D 모델과 콘텐츠 패널을 서로 및 가상 또는 실제 환경에 상대적으로 배치하고 정렬할 수 있습니다.

  • SpatialEnvironment: 스카이박스 이미지 또는 3D 모델 지오메트리를 환경의 XR 장면 배경으로 사용하여 완전한 몰입형 환경을 만듭니다. 또는 패스스루를 사용 설정하여 가상 장면을 사용자의 실제 환경과 통합할 수 있습니다.
  • PanelEntity: 실제 표면에 고정되거나 떠다닐 수 있는 공간화된 패널에 표준 Android 레이아웃과 활동을 삽입하여 3D 장면에 2D 콘텐츠를 추가합니다.
  • GltfModelEntity: 장면에서 3D 모델을 배치하고, 애니메이션을 적용하고, 상호작용합니다. SceneCore는 기존 모델과의 손쉬운 통합을 위해 glTF 파일 형식을 지원합니다.
  • SpatialAudio: 완전히 몰입감 있는 공간화된 사운드를 위해 3D 장면에 주변 및 포인트 오디오 소스를 추가합니다.
  • StereoSurfaceEntity: SceneCore는 Android Surface에 렌더링된 콘텐츠의 왼쪽/오른쪽 눈 라우팅을 지원합니다. 이를 사용하여 스테레오 사진, 3D 동영상, 기타 동적으로 렌더링된 UI와 같은 스테레오 콘텐츠를 나란히 또는 위아래 형식으로 렌더링할 수 있습니다. 애플리케이션은 동영상 디코딩에 MediaPlayer 또는 ExoPlayer를 사용해야 합니다.
  • 구성요소 시스템: SceneCore는 사용자가 모델 및 패널을 이동하고 크기를 조절하고 상호작용할 수 있는 어포던스를 비롯하여 XR 콘텐츠에 기능을 추가할 수 있는 강력하고 유연한 구성요소 시스템을 제공합니다.
  • 앵커: 패스스루를 사용 설정하면 패널과 모델을 실제 표면에 연결하여 사용자가 실제 환경에 가상 콘텐츠를 원활하게 통합할 수 있습니다.
  • 사용자 포즈: 가상 장면에서 사용자의 위치에 액세스하여 콘텐츠를 사용자의 위치에 맞게 방향을 지정합니다.
  • SpatialCapabilities: UI 콘텐츠의 3D 위치 지정과 같이 공간화된 기능을 사용할 수 있는 경우 이를 활용하는 완전한 적응형 앱을 빌드합니다. 뿐만 아니라 앱이 실행되는 동안 기능을 변경하는지 모니터링하여 사용자가 Android XR 기기를 사용하는 방식에 따라 환경을 수정할 수 있습니다.

알려진 문제

  • 현재 Jetpack SceneCore를 사용하려면 minSDK 30이 필요합니다. 이 문제를 해결하려면 minSDK가 23인 상태로 빌드하고 실행할 수 있도록 다음 매니페스트 항목 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>를 추가하세요.
  • 기본 패널 크기 조절, 주변기기 연결, 라이트 모드와 다크 모드 간 전환 등 활동을 자동으로 다시 만드는 다양한 상황에서 세션이 무효화될 수 있습니다. 세션 무효화 문제가 발생하는 경우 해결 방법으로는 기본 패널의 크기를 조절할 수 없도록 설정하거나, 동적 패널 엔티티를 사용하거나, 특정 구성 변경에 대해 활동 재생성을 사용 중지하거나, 밝은/어두운 모드 테마 변경을 사용 중지하는 방법이 있습니다.
  • 이동 가능하고 크기 조절 가능한 구성요소는 GltfEntity에서 지원되지 않습니다.
  • GltfEntity에서는 Entity.getSize()가 지원되지 않습니다.
  • Jetpack XR 앱은 AndroidManifest에서 android.permission.SCENE_UNDERSTANDING 권한을 요청해야 합니다.
  • 세션 생성은 Android XR 기기에서만 지원됩니다. 이때 세션을 만들고 Android XR이 아닌 기기에서 사용하려고 하면 RuntimeException이 발생합니다.
  • `SpatialEnvironment.setSpatialEnvironmentPreference()`를 통해 스카이박스를 null로 설정하면 문서화된 대로 검은색 스카이박스가 생성되지 않습니다. 시스템 기본 스카이박스가 표시되거나 현재 스카이박스가 변경되지 않을 수 있습니다.
  • SceneCore 클라이언트는 앱 종속 항목의 Gradle 구성에 implementation(“com.google.guava:listenablefuture-1.0”)를 추가해야 합니다. 향후 출시에서는 scenecore가 이 라이브러리를 api 종속 항목으로 포함하므로 클라이언트가 명시적으로 선언할 필요가 없습니다.
  • SceneCore에 com.google.guava:guava-31.1-android 및 com.google.protobuf:protobuf-javalite이 전이적 종속 항목으로 잘못 포함되어 있습니다. 이로 인해 빌드에 중복 클래스 오류가 발생하는 경우 이 두 종속 항목을 안전하게 제외할 수 있습니다.
  • 앱이 SceneCore를 사용하고 ProGuard를 사용 설정하면 세션을 만들 때 비정상 종료됩니다. 해결 방법으로 ProGuard를 사용 중지하세요. ProGuard를 사용 설정하는 방법에 관한 자세한 내용은 이 가이드를 참고하세요.