{ } { }

Jetpack SceneCore

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

종속 항목 선언

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

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

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha02"
    // 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-alpha02"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha02")
    // 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-alpha02")
}

종속 항목에 관한 자세한 내용은 빌드 종속 항목 추가를 참고하세요.

의견

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

새로운 문제 제출하기

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

버전 1.0

버전 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이 출시되었습니다.

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

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

알려진 문제

  • 현재 Jetpack SceneCore를 사용하려면 최소 SDK 30이 필요합니다. 해결 방법으로 다음 매니페스트 항목 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>를 추가하여 minSDK 23으로 빌드하고 실행할 수 있습니다.
  • 기본 패널 크기 조절, 주변기기 연결, 밝은 모드와 어두운 모드 간에 전환 등 Activity를 자동으로 다시 만드는 다양한 상황에서 세션이 무효화될 수 있습니다. 세션 무효화 문제가 발생하면 기본 패널의 크기를 조절할 수 없도록 하거나, 동적 패널 항목을 사용하거나, 특정 구성 변경에 대해 활동 재생성을 사용 중지하거나, 밝은/어두운 모드 테마 변경을 사용 중지하는 등의 해결 방법을 사용할 수 있습니다.
  • GltfEntity에서는 Movable 및 Resizable 구성요소가 지원되지 않습니다.
  • GltfEntity에서는 Entity.getSize()가 지원되지 않습니다.
  • AndroidManifest에서 android.permission.SCENE_UNDERSTANDING 권한을 요청해야 하는 Jetpack XR 앱
  • 세션 만들기는 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를 사용 설정하는 방법에 관한 자세한 내용은 이 가이드를 참고하세요.