Jetpack SceneCore

API 참조
androidx.xr.scenecore
androidx.xr.scenecore.testing

3D 콘텐츠로 Android XR 장면 그래프를 빌드하고 조작합니다.

최근 업데이트	안정화 버전	출시 후보 버전	베타 버전	알파 버전
2026년 1월 28일	-	-	-	1.0.0-alpha11

종속 항목 선언

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

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

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha11"

    // Optional dependencies for asynchronous conversions
    implementation "androidx.xr.scenecore:scenecore-guava:1.0.0-alpha11"

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

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha11")

    // Optional dependencies for asynchronous conversions
    implementation("androidx.xr.scenecore:scenecore-guava:1.0.0-alpha11")

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

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

의견

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

새로운 문제 제출하기

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

버전 1.0

버전 1.0.0-alpha11

2026년 1월 28일

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

API 변경사항

getPerceivedResolution API가 이제 CameraViewScenePose 대신 ARCore의 RenderViewpoint API를 사용하므로 PerceivedResolutionResult.InvalidCameraView의 이름을 PerceivedResolutionResult.InvalidRenderViewpoint로 변경합니다. 이 이름은 새로운 구현을 더 잘 반영합니다. (I8c967, b/446989745, b/419311998)
이제 PanelEntity/SurfaceEntity.getPerceivedResolution 메서드는 개발자가 제공한 RenderViewpoint를 인수로 사용합니다. 이전에는 런타임에서 인식된 해상도 계산에 사용되는 RenderViewpoint를 임의로 선택했습니다. (I8c967, b/446989745, b/419311998)
SpatialUser, ScenePose.Head, ScenePose.CameraView이 삭제되었습니다. 이러한 API의 기능은 Jetpack XR용 ARCore 내의 ArDevice 및 RenderViewpoint API로 제공됩니다. 사용자의 머리 또는 왼쪽이나 오른쪽 눈에 해당하는 ScenePose를 획득하기 위해 개발자는 ARCore API를 사용하여 획득한 적절한 포즈와 함께 PerceptionSpace.getScenePoseFromPerceptionPose를 사용할 수 있습니다. (I2f69c, b/446989745)

버전 1.0.0-alpha10

2025년 12월 3일

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

API 변경사항

PanelEntity에 transformPixelCoordinatesToPose 및 transformNormalizedCoordinatesToPose를 추가했습니다. (I462b3)
SceneCore의 로직에 따라 SceneCore 런타임에 도우미 클래스 Utils를 추가했습니다. (I570b9)

버그 수정

세션이 삭제되고 SpatialModeChangeEvent이 수신될 때 발생할 수 있는 잠재적인 비정상 종료 문제가 수정되었습니다 (If44e8).
활동을 나가거나 다시 입력할 때 IllegalStateException가 발생할 수 있는 버그를 수정했습니다. (Ibff1c)

버전 1.0.0-alpha09

2025년 11월 19일

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

새로운 기능

지각 공간 원점 포즈와 지각 공간 원점에 관한 포즈의 구성을 나타내는 ScenePose를 가져오는 API를 추가합니다. (I5b50a)
getGravityAlignedPose 함수가 추가되었습니다. 중력 정렬 포즈는 회전의 피치와 롤을 무시합니다. (I5ae21)
AnchorEntity.State 상수 유형이 Int에서 상태 하위 유형으로 변경되었습니다. (Ib0c49)
엔티티 인터페이스에 getChildren()가 추가되었습니다. MainPanelEntity 수명 주기 업데이트 (Ia69d6)

API 변경사항

PointerCaptureComponent.PointerCaptureState 상수 유형이 정수에서 PointerCaptureState 하위 유형으로 변경되었습니다. (Ic888a)
이제 Scene.spatialCapabilities은 Int 필드가 아닌 Set<SpatialCapability> 유형입니다. SpatialCapability 상수의 이름이 변경되었습니다. (I9c109)
SurfaceEntity 상수 유형의 이름이 변경되었으며 Int에서 SurfaceEntity 하위 유형으로 변경되었습니다. (I419ed)
SpatializerConstant 상수 유형의 이름이 변경되었으며 Int에서 SpatializerConstant 하위 유형으로 변경되었습니다. (Ia0e18)
TextureSampler 상수 유형의 이름이 변경되었으며 Int에서 TextureSampler 하위 유형으로 변경되었습니다. (I44078)
SpatialVisibility 상수 유형이 정수에서 SpatialVisibility 하위 유형으로 변경되었습니다. (I70739)
ResizeEvent.ResizeState 상수 유형의 이름이 변경되었으며 Int에서 ResizeState 하위 유형으로 변경되었습니다. (I384d5)
InputEvent 상수 유형의 이름이 변경되었으며, 각각의 닫힌 유형에서 상속받도록 Ints에서 변경되었습니다. (I82817)
GltfModelEntity.AnimationState 상수 유형이 정수에서 AnimationState 하위 유형으로 변경되었습니다. (I24f4e)
AlphaMode 상수 유형의 이름이 변경되었으며 Int에서 AlphaMode 하위 유형으로 변경되었습니다. (I27b56)
Space 상수 유형이 Int에서 Space 하위 유형으로 변경되었습니다. (I9255b)
이제 ScenePose.hitTest 및 관련 메서드는 교차점이 없는 경우 null hitPosition가 있는 HitTestResult 대신 null를 반환합니다. HitTestResult.hitPosition이 더 이상 null이 아닙니다. (I1400a)
ActivityPose에 대한 참조를 ScenePose로 변경했습니다. (I7fe43)

버전 1.0.0-alpha08

2025년 10월 22일

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

API 변경사항

ActivityPanelEntity.moveActivity의 이름을 transferActivity로 바꿨습니다. (I273c5, b/430332856)

버그 수정

:xr:scenecore:scenecore-spatial-rendering 및 :xr:scenecore:scenecore-spatial-core이 :xr:scenecore:scenecore의 구현 종속 항목으로 추가됨 (I6ab65, b/447000520)
세션이 소멸된 후 session.scene에 액세스하면 예외가 발생합니다. (I77e6f)

버전 1.0.0-alpha07

2025년 9월 24일

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

API 변경사항

fixedAspectRatio의 이름을 isFixedAspectRatioEnabled로 변경하고 불리언 속성으로 만들었습니다. (I5c4e8, b/440588971)
이제 Scenecore 가짜가 xr:scenecore:scenecore-testing 모듈에 있습니다. (Idd951)
shouldAutoHideContent의 이름을 isAutoHideContentWhileResizingEnabled로, shouldAlwaysShowOverlay의 이름을 isAlwaysShowOverlayEnabled로 바꿨습니다. (I97c36, b/432335421)
가독성을 위해 SceneCore TextureSampler 상수를 업데이트했습니다. 예를 들어 TextureSampler.MinFilter.LINEAR가 이제 TextureSampler.MIN_FILTER_LINEAR입니다. (Ib159c)
장면의 setKeyEntity 설정자가 keyEntity 변수로 병합되었습니다. keyEntity을 AnchorEntity과 같이 이동할 수 없는 항목으로 설정하면 불리언 false를 반환하는 대신 IllegalArgumentException이 발생합니다. (I62080, b/428721695, b/422215745)
장면의 SpatialModeChangeListener 변수가 setSpatialModeChangedListener으로 대체되었습니다. SpatialModeChangedListener 대신 Consumer<SpatialModeChangeEvent>를 사용합니다. 이제 setSpatialModeChangedListener가 Executor를 선택적으로 사용할 수 있습니다. (I62080, b/428721695, b/422215745)
ActivityPanelEntity.startActivity에서 bundle 매개변수를 삭제했습니다. (I64344, b/430332856, b/430333040)
SpatializerConstants.SOURCE_TYPE_BYPASS에서 SpatializerConstants.SOURCE_TYPE_DEFAULT로 이름이 변경되었습니다. (Ifc7fe, b/422215565)
SpatialSoundPool.PLAY_FAILED 상수를 추가했습니다. (Ifc7fe, b/422215565)
SpatialSoundPool.play 메서드에 기본 인수가 추가되었습니다. (Ifc7fe, b/422215565)
SpatialAudioTrackBuilder에서 setter의 반환 값을 삭제했습니다. (Ifc7fe, b/422215565)
SurfaceEntity 변경사항
- SurfaceEntity.CanvasShape에서 Shape로 이름 변경
- SurfaceEntity.CanvasShape.Vr180Hemisphere에서 Hemisphere로 이름 변경
- SurfaceEntity.CanvasShape.Vr360Sphere에서 Sphere로 이름 변경
- SurfaceEntity.EdgeFeatheringParams.SmoothFeather에서 RectangleFeather로 이름 변경
- SurfaceEntity.EdgeFeathingParams.SolidEdge에서 NoFeathering로 이름 변경
- SurfaceEntity.ContentSecurityLevel에서 SurfaceProtection로 이름 변경
- SurfaceEntity.ContentSecurityLevel.{values}에 SURFACE_PROTECTION_ 접두사가 추가되었습니다.
- SurfaceEntity.SuperSampling.{$values}님이 SUPER_SAMPLING_ 접두사를 추가함
- SurfaceEntity.StereoMode.{values}님이 STEREO_MODE_ 접두사를 추가함
- SurfaceEntity.ContentColorMetadata.maxCLL이 maxContentLightLevel로 이름이 변경됨 (I7eb5f, b/422216050, b/427529950)
launchActivity에서 startActivity으로 이름이 변경되었습니다. (I7db90, b/430332856)
Scene.activitySpaceRoot을 삭제했습니다. 대신 Scene.activitySpace를 사용합니다. (I05ee8, b/378706624, b/422215745)
configureBundleForFullSpaceModeLaunch 및 configureBundleForFullSpaceModeLaunchWithEnvironmentInherited의 이름이 각각 createBundleForFullSpaceModeLaunch 및 createBundleForFullSpaceModeLaunchWithEnvironmentInherited로 변경되고 최상위 메서드로 LaunchUtils.kt 파일로 이동되었으며 세션을 첫 번째 매개변수로 사용합니다 (I64a2c, b/437186050).
이제 GroupEntity 팩토리가 Entity 대신 GroupEntity 유형을 반환합니다. (I66042)

버그 수정

항목 인스턴스가 폐기 후 사용되면 IllegalStateException을 던집니다. (I90990, b/427314036, b/432063442)

버전 1.0.0-alpha06

2025년 8월 13일

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

API 변경사항

SceneCore의 BaseEntity 및 BaseScenePose API 제한 해제 (88c0ff6)

버전 1.0.0-alpha05

2025년 7월 30일

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

새로운 기능

패널 항목 및 SurfaceEntities에 인식된 해상도 API가 추가되었습니다. (I118f6)
HSM에서 활동의 기본 패널의 인식된 해상도를 모니터링하기 위해 Scene.kt에 PerceivedResolution 콜백 메서드가 추가되었습니다. (I58084)
SurfaceEntity - 애플리케이션이 생성 시 슈퍼 샘플링을 요청할 수 있도록 지원이 추가되었습니다. 이를 통해 애플리케이션은 앤티앨리어싱에 슈퍼 샘플링 필터를 사용할 수 있습니다. (I06913)
ActivitySpace에 recommendedContentBoxInFullSpace 속성이 추가되었습니다. 전체 공간 모드에서 배치할 콘텐츠의 추천 상자를 반환합니다. (I4cd6f)
고정할 수 있는 이동 가능한 수정자의 오버로드된 생성자를 제공했습니다. (Ic0c70)

API 변경사항

이번 출시에서는 SceneCore에 광범위한 API 변경사항이 적용되었습니다. 여러 클래스의 이름이 변경되거나 다른 모듈로 이동되었으며 대부분의 getter/setter 메서드가 Kotlin 속성으로 대체되었습니다. 첫 번째 베타 출시까지는 향후 브레이킹 API 변경사항이 있을 것으로 예상되지만, 그 수가 많거나 중대한 변경사항은 아닐 것입니다.

다음 클래스 및 인터페이스의 이름이 변경되거나 이동되었습니다. androidx.xr.scenecore.PixelDimensions에서 androidx.xr.runtime.math.IntSize2d로, androidx.xr.scenecore.Dimensions에서 androidx.xr.runtime.math.FloatSize3d로, androidx.xr.scenecore.ActivityPose에서 ScenePose로, androidx.xr.scenecore.ContentlessEntity에서 GroupEntity로, androidx.xr.scenecore.PlaneType에서 PlaneOrientation로, androidx.xr.scenecore.PlaneSemantic에서 PlaneSemanticType로 (Ifd405)(I3b622) (If534d)
Scene 속성의 setter가 비공개로 설정되었습니다. SceneCore 클라이언트가 변경하도록 의도되지 않았습니다. activitySpace, activitySpaceRoot, mainPanelEntity, perceptionSpace, spatialCapabilities, spatialEnvironment, spatialUser (I2f506)
항목: 다음을 속성으로 변경했습니다. get/setParent(), setContentDescription; Entity.is/setHidden()가 지원 중단되었으며 Entity.is/setEnabled를 대신 사용하세요. (Ibc4c6)
androidx.xr.scenecore.BasePanelEntity 클래스를 삭제했습니다. 대신 PanelEntity를 직접 사용하세요. PanelEntity의 getter 및 setter를 속성으로 대체했습니다. PanelEntity.size 속성이 Float3dSize에서 Float2dSize로 변경되었습니다. 지원 중단된 메서드 androidx.xr.scenecore.PanelEntity.getPixelDimensions가 삭제되었습니다. 대신 getSizeInPixels를 사용하세요. (Icc174)
androidx.xr.scenecore.OnSpaceUpdatedListener를 Runnable로 바꿨습니다 (I19308)
SpatialUser.getCameraViews()을 속성으로 대체했습니다. (Ib0cc5) ExrImage 및 GltfModel:의 경우 create 메서드를 중단 함수로 변경하고, String 대신 Uri 또는 Path를 허용하도록 생성 매개변수를 수정했습니다. (Id8883) (I0d247), (I25706)
SpatialEnvironment.requestFullSpaceMode 및 SpatialEnvironment.requestHomeSpaceMode를 장면으로 이동했습니다. 예를 들어 session.scene.spatialEnvironment.requestFullSpaceMode() 대신 session.scene.requestFullSpaceMode()를 사용합니다. 이제 addOnPassthroughOpacityChangedListener 및 addOnSpatialEnvironmentChangedListener에는 선택적 Executor를 허용하는 재정의가 있습니다. (I12fe0) (I6b21e)
지원 중단된 SpatialEnvironment 메서드 togglePassthrough, setPassthrough, setPassthroughOpacity, getPassthroughMode, getPassthroughOpacity, setSkybox, setGeometry가 삭제되었습니다. 지원 중단된 클래스 SpatialEnvironment.PassthroughMode도 삭제했습니다. (I927bd) (I927bd) (I927bd)
다음 SpatialEnvironment getter 및 setter를 Kotlin 속성으로 대체했습니다. getCurrentPassthroughOpacity(), get/setPassthroughOpacityPreference(), get/setSpatialEnvironmentPreference(), isSpatialEnvironmentPreferenceActive() (I33a7b) (Ie06e2) (Ie06e2)
SpatialEnvironmentPreference.preferredPassthroughOpacity 유형이 Float?에서 Float로 변경되었습니다. 이제 null 값을 허용하지 않습니다. 대신 SpatialEnvironment.NO_PASSTHROUGH_OPACITY_PREFERENCE는 불투명도 환경설정이 없음을 알리는 데 사용됩니다. (I40107)
create 메서드에서 windowBoundsPx 매개변수를 pixelDimensions로, 유형을 Rect에서 IntSize2d로 업데이트했습니다. (I1926e)
이제 SpatialEnvironment 생성자가 내부용입니다. (I75a51)
SpatialPointerIconNone 및 SpatialPointerIconCircle 클래스를 동반 객체 SpatialPointerIcon.NONE 및 SpatialPointerIcon.CIRCLE로 대체했습니다 (I416d2).
SpatialPointerComponent의 SpatialPointerIcon이 더 이상 null이 아닙니다. 시스템 기본 포인터 아이콘을 사용해야 함을 나타내려면 null 대신 SpatialPointerIcon.DEFAULT를 사용하세요. (I416d2)
androidx.xr.scenecore.AnchorEntity.getState()이 읽기 전용 속성으로 대체되었습니다. 명확성을 위해 AnchorEntity.create() 메서드의 매개변수 이름을 변경했습니다. 리스너를 설정하고 추가하는 AnchorEntity의 메서드에서 리스너가 후행 람다를 사용 설정하는 최종 인수로 이동했습니다. AnchorEntity의 androidx.xr.scenecore.OnStateChangedListener을 Consumer<AnchorEntity.State>로 대체했습니다. (I472e0)
이제 GltfModelEntity.getAnimationState()은 속성입니다. (I10b29)
ActivitySpace.getBounds()을 속성으로 대체했습니다. ActivitySpace.addBoundsChangedListener의 이름이 ActivitySpace.addOnBoundsChangedListener로 변경되었습니다. ActivitySpace.setOnSpaceUpdatedListener이 추가/삭제 메서드로 대체되었습니다. (I4c956)
AnchorPlacement: planeTypeFilter의 이름이 anchorablePlaneOrientations로, planeSemanticFilter의 이름이 anchorablePlaneSemanticTypes로 바뀌었습니다. AnchorEntity 또는 ActivitySpace에 MovableComponent를 추가하면 false가 반환됩니다. MoveListener의 이름이 EntityMoveListener shouldDisposeParentAnchor로 변경되었고 disposeParentOnReAnchor systemMovable의 이름이 create 함수에서 creeateCustomMovable, createSystemMovable, createAnchorable로 변경되었습니다 (If11c4).
SurfaceEntity.featherRadiusX/Y가 삭제되고 EdgeFeatheringParams 클래스 개념이 추가되었습니다. (Ic78fc)
PanelEntity.enablePanelDepthTest() 메서드가 panelClippingConfig 속성으로 대체되었습니다. Scene.panelClippingConfig = PanelClippingConfig(isDepthTestEnabled = true)를 설정하여 깊이 테스트를 사용 설정하거나 PanelClippingConfig(isDepthTestEnabled = false)를 설정하여 사용 중지합니다. (I0cbe0)
이제 Scene.mainPanelEntity의 유형이 PanelEntity 대신 MainPanelEntity입니다. (I7125a)
장면의 setFullSpaceMode 메서드 이름을 configureBundleForFullSpaceModeLaunch으로, setFullSpaceModeWithEnvironmentInherited 메서드 이름을 configureBundleForFullSpaceModeLaunchWithEnvironmentInherited으로 변경했습니다. (I0cbe0) (I0cbe0)
SpatialVisibility의 UNKNOWN, OUTSIDE_FOV, PARTIALLY_WITHIN_FOV, WITHIN_FOV 값을 각각 SPATIAL_VISIBILITY_UNKNOWN, SPATIAL_VISIBILITY_OUTSIDE_FIELD_OF_VIEW, SPATIAL_VISIBILITY_PARTIALLY_WITHIN_FIELD_OF_VIEW, SPATIAL_VISIBILITY_WITHIN_FIELD_OF_VIEW로 이름을 바꿈 (Ie7e8c)
SpatialVisibility 클래스가 const Int 값이 있는 공개 객체로 대체되었습니다. 이제 setSpatialVisibilityChangedListener는 Consumer<SpatialVisibility> 대신 Consumer<Int>를 허용합니다 (Ie7e8c).
PointerCaptureComponent 상수의 이름이 변경되고 PointerCaptureComponent.PointerCaptureState 객체로 이동했습니다 (I9c7ac).
PointerCaptureComponents' StateListener를 Consumer<Int>로 바꿨습니다 (I9c7ac)
InputEventListener를 Consumer<InputEvent>로 대체했습니다. (I9c7ac)
setPreferredAspectRatio가 Scene 클래스에서 SpatialWindow 객체로 이동하고 세션을 첫 번째 매개변수로 사용합니다. (I7b717)
Entity.setHidden()이 Entity.setEnabled()로 대체되고 Entity.isHidden()이 Entity.isEnabled()로 대체되었습니다. setHidden(false)은 setEnabled(true) 및 isHidden() == !isEnabled()와 같습니다. (Icf0de)
Entity.contentDescription 유형이 문자열에서 CharSequence로 변경되었습니다. (Ie59be)
이제 Session.create 및 Session.configure은 충분한 권한이 부여되지 않은 경우 SessionCreatePermissionsNotGranted 또는 SessionConfigurePermissionsNotGranted를 반환하는 대신 SecurityException을 발생시킵니다. (I7c488)
ResizableComponent.create에 이제 Consumer<ResizeEvent> ResizeEventListener이 필요합니다. Consumer<ResizeEvent> ResizableComponent.size로 대체되었고, ResizableComponent.affordanceSize ResizableComponent.minimumSize로 이름이 변경되었고, ResizableComponent.minimumEntitySize ResizableComponent.maximumSize로 이름이 변경되었고, ResizableComponent.maximumEntitySize로 이름이 변경되었고, ResizableComponent.autoHideContent로 이름이 변경되었고, ResizableComponent.shouldAutoHideContent로 이름이 변경되었고, ResizableComponent.forceShowResizeOverlay로 이름이 변경되었고, ResizableComponent.shouldAlwaysShowOverlay로 이름이 변경되었습니다. (I97a2d)
androidx.xr.scenecore 및 androidx.xr.compose의 minSDK을 24로 줄였습니다. XR 패키지에는 런타임에 API 34가 필요합니다. (I17224)
모든 Jetpack XR 패키지에서 RequiresApi(34) 제한을 삭제했습니다. Jetpack XR은 현재 API 수준 34 이상의 기기에서만 사용할 수 있으므로 이 제한은 중복되었습니다. (Iae0f8)
기본 SceneCore 아티팩트 (xr:scenecore:scenecore)에는 Kotlin 스타일 비동기 API만 포함됩니다. Java 개발자는 xr:scenecore:scenecore-guava 라이브러리를 사용하여 호환되는 API에 액세스할 수 있습니다. (If221b)
Kotlin 2.0으로 출시된 프로젝트를 사용하려면 KGP 2.0.0 이상이 필요합니다 (Idb6b5).
이제 이 라이브러리는 유형 사용인 JSpecify nullness 주석을 사용합니다. Kotlin 개발자는 다음 컴파일러 인수를 사용하여 올바른 사용을 강제해야 합니다. -Xjspecify-annotations=strict (Kotlin 컴파일러 버전 2.1.0부터 기본값임) (Ia8420)
ListenableFuture를 반환하는 모든 비동기 메서드가 Kotlin 정지 함수로 대체되었습니다. Kotlin 정지 함수 대신 ListenableFuture 기반 비동기 메서드를 사용하려는 Java 개발자는 이제 :xr:scenecore-scenecore-guava에서 확장 함수를 사용해야 합니다. 예를 들어 GuavaExrImage에는 Guava와 동일한 ExrImage 비동기 함수가 포함되고, GuavaScenePose에는 Guava와 동일한 ScenePose 비동기 함수가 포함되고, GuavaGltfModel에는 Guava-equivalent GltfModel 비동기 함수가 포함됩니다. (If7283) (I0af60) (If7283) (Ia8515) (I4efdf) (I54bbf) (I3467a) (I82a33)

버그 수정

최소화된 클라이언트의 AbstractMethodError를 방지하도록 Jetpack XR Scenecore ProGuard 규칙이 업데이트되었습니다. (I91a01)
Jetpack XR SceneCore의 Proguard 축소를 지원하기 위한 추가 수정사항 (I4f47e)
시스템에서 반환된 hitPosition이 null인 경우 HitInfo의 InputEvent에 있는 hitPosition이 비정상 종료될 수 있는 InteractableComponent 버그가 수정되었습니다 (I7a695).
동작을 반영하도록 구성 *Mode 값이 이름이 변경되었습니다. (I6d247)
SceneCore TestApp에서 FOV 및 HitTest 관련 문제를 수정했습니다. (I2c51e)
비트 OR로 전달된 기능 중 하나가 모두 참인 경우에만 참을 반환하는 대신 참인 경우 참을 반환하는 SpatialCapabilities.hasCapability()의 버그가 수정되었습니다. (I2cd40)
SurfaceEntity.StereoMode.TOP_BOTTOM가 왼쪽 눈에 상단 지도를, 오른쪽 눈에 하단 지도를 표시하도록 업데이트되었습니다. (I4ae68)

버전 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가 포함된 경우 올바른 단위를 사용하여 좌표 변경사항을 계산합니다.
이제 null 스카이박스 환경설정이 setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom))를 사용하여 전달되면 스카이박스가 완전한 검은색 스카이박스로 설정됩니다. 시스템 기본 스카이박스와 지오메트리로 되돌리려면 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를 사용하려면 최소 SDK 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를 사용 설정하는 방법에 관한 자세한 내용은 이 가이드를 참고하세요.