Jetpack SceneCore
최근 업데이트 | 안정화 버전 | 출시 후보 버전 | 베타 버전 | 알파 버전 |
---|---|---|---|---|
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 ScenecoreProGuard
규칙이 업데이트되었습니다. (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를 사용 설정하는 방법에 관한 자세한 내용은 이 가이드를 참고하세요.