이 페이지는 Cloud Translation API를 통해 번역되었습니다.

XR용 Jetpack Compose

API 참조
androidx.xr.compose.platform
androidx.xr.compose.spatial
androidx.xr.compose.subspace
androidx.xr.compose.subspace.layout
androidx.xr.compose.subspace.node
androidx.xr.compose.unit

Android XR의 공간 기능을 활용하는 공간 UI 레이아웃을 선언적으로 빌드합니다.

최근 업데이트	안정화 버전	출시 후보 버전	베타 버전	알파 버전
2025년 5월 7일	-	-	-	1.0.0-alpha04

종속 항목 선언

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

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

Groovy

dependencies {
    implementation "androidx.xr.compose:compose:1.0.0-alpha04"

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

Kotlin

dependencies {
    implementation("androidx.xr.compose:compose:1.0.0-alpha04")

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

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

의견

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

새로운 문제 제출하기

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

버전 1.0

버전 1.0.0-alpha04

2025년 5월 7일

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

새로운 기능

맞춤 SubspaceModifier 유형이 컴포지션 로컬 값에 액세스할 수 있도록 CompositionLocalConsumerSubspaceModifierNode 인터페이스를 추가했습니다.
Compose AndroidView 구현 스타일을 따르고 이전 ViewBased SpatialPanel를 지원 중단하는 새 SpatialPanel API를 추가했습니다.
제한되지 않은 제약 조건을 나타내는 VolumeConstraints.Unbounded 컴패니언 객체를 추가했습니다.
공간화된 오디오 소스를 허용하도록 SubspaceModifier.onPointSourceParams를 추가했습니다.
앱이 공간 콘텐츠를 렌더링할 수 있는 3D 영역을 정의하는 선택적 VolumeConstraints를 제공하는 공개 ApplicationSubspace가 추가되었습니다. 기본적으로 제약 조건이 지정되지 않은 경우 하위 공간은 너비와 높이에서 SpatialUser의 현재 시야로 제한됩니다. 사용자는 시야를 결정할 수 없는 경우 사용할 제약 조건을 제공할 수 있습니다. 그렇지 않으면 기본 시야 너비 및 높이 값이 사용됩니다.
입체 콘텐츠를 렌더링하는 데 사용할 수 있는 SpatialExternalSurface를 추가했습니다. SpatialExternalSurface는 수정자 (알파 제외) 및 가장자리 페더링 효과로 맞춤설정할 수 있습니다.
사용자가 공간 포인터의 아이콘을 설정할 수 있는 새로운 pointerHoverIcon 하위 공간 수정자를 추가했습니다.

API 변경사항

모든 Jetpack XR 패키지에서 RequiresApi(34) 제한을 삭제했습니다. Jetpack XR은 현재 API 수준 34 이상을 실행하는 기기에서만 사용할 수 있으므로 이 제한은 중복되었습니다. (Iae0f8)
Kotlin 2.0으로 출시된 프로젝트를 사용하려면 KGP 2.0.0 이상이 필요합니다. (Idb6b5)
이제 삽입된 활동이 없는 공간 패널에서도 뒤로 처리가 작동합니다. 뒤로 탐색 처리가 작동하려면 Android 매니페스트에 android:enableOnBackInvokedCallback="true"를 지정해야 합니다.
이제 백핸들링이 공간 대화상자에서 작동합니다. 백핸들링이 작동하려면 Android 매니페스트에 android:enableOnBackInvokedCallback="true"를 지정해야 합니다.
이제 Compose 기반 및 뷰 기반 SpatialPanel가 콘텐츠를 기반으로 크기를 조절할 수 있습니다.
이제 개발자는 사전 정의된 수준에 국한되지 않고 자체 맞춤 SpatialElevationLevel 값을 설정할 수 있습니다.
이제 elevation 매개변수를 통해 궤도선 고도 수준을 맞춤설정할 수 있습니다.
이제 하위 공간은 기본적으로 너비와 높이에서 SpatialUser의 시야로 제한될 수 있습니다. 시야를 확인할 수 없는 경우 기본 시야 너비 및 높이 값이 사용됩니다.
Movable 수정자에 새 콜백 onMoveStart 및 onMoveEnd를 추가했습니다. onMoveStart 및 onMoveEnd 콜백은 사용자가 movable 수정자로 컴포저블 하위 공간의 이동을 시작하고 종료할 때 호출됩니다.
SpatialRow 및 SpatialPanel와 같은 공간 API에서 name 매개변수가 삭제되었습니다. 공간 컴포지션 트리를 디버그하려면 대신 SubspaceModifier.testTag를 사용하세요.
spatialElevationLevel 및 content만 있는 지원되지 않는 SpatialPopup 오버로드가 삭제되었습니다. onDimissRequest를 지원하는 인터페이스를 사용하세요.
Movable 수정자의 onPoseChange 콜백이 삭제되었습니다. 대신 onMove를 사용합니다.
SubspaceModifiers는 효과가 분리되었거나 현재 분리되고 있는 경우 더 이상 효과를 적용하지 않습니다.
기존 SpatialRow API가 SpatialRow 및 SpatialCurvedRow로 분할되었습니다. 이전에 SpatialRow의 curveRadius 매개변수를 사용했다면 이제 동일한 동작을 제공하는 SpatialCurvedRow를 대신 사용하세요.
MainPanel 및 ActivityPanel가 유사한 최신 시스템 이미지에서 실행될 때 더 이상 제목 표시줄이 없습니다.
이제 알파 및 크기 수정자를 중첩할 수 있으며 최종적으로 적용된 알파 또는 크기 값에 값을 곱합니다.
Movable 수정자의 onPoseChange 콜백이 더 부드러운 포즈 움직임을 실행하도록 최적화되었습니다.
이제 이동 가능 및 크기 조절 가능 수정자는 상태 변경이 리컴포지션을 트리거하도록 기본 스레드에서 콜백을 실행합니다.
SubspaceLayout의 상태 변경이 레이아웃 재설정을 트리거하도록 레이아웃 및 측정 단계에 상태 관찰을 추가했습니다.
기존 수정자를 더 효과적으로 재사용할 수 있도록 수정자 체인 업데이트를 최적화했습니다.

버그 수정

SpatialDialog가 표시될 때 스리밍이 중지되었습니다. (Ic4594)
이제 수정자 노드가 분리된 동안 이루어진 레이아웃 변경 요청이 무시됩니다.
Movable 및 Resizable 수정자에 의해 트리거되는 재구성 단계를 삭제했습니다.
직접 또는 레이아웃 계산(예: SpatialRow/SpatialColumn 계산) 중에 둘 중 하나의 크기가 0으로 설정될 때 발생하는 MainPanel() 컴포저블의 비정상 종료가 수정되었습니다. 이제 패널이 숨겨집니다. 이 수정사항은 특히 레이아웃 단계에서 발생하는 비정상 종료를 해결합니다. 사용자 상호작용을 통해 패널 크기를 0으로 조절하는 작업은 별도로 처리됩니다. 숨겨진 패널에 UI 어포던스가 없습니다.
크기 조절 가능 수정자의 maintainAspectRatio 관련 문제가 수정되었습니다. 이제 가로세로 비율이 유지됩니다.
중첩된 하위 공간이 단일 프레임에 대해 잘못 배치되는 문제를 수정했습니다.
모서리가 둥글게 처리되어야 할 때 적용되지 않는 문제가 수정되었습니다.
NestedSubspaces가 더 이상 한 프레임에 잘못된 위치에 표시되지 않습니다.

버전 1.0.0-alpha03

2025년 2월 26일

androidx.xr.compose:compose:1.0.0-alpha03 및 androidx.xr.compose:compose-testing:1.0.0-alpha03 버전은 지난 알파 이후 변경사항 없이 출시되었습니다. 버전 1.0.0-alpha03에는 이 커밋이 포함되어 있습니다.

버전 1.0.0-alpha02

2025년 2월 12일

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

새로운 기능

이제 스페이스 대화상자가 활성화되면 활동 패널에서 콘텐츠를 스크림할 수 있습니다.
이제 Orbiter API를 SubspaceComposable 컨텍스트에서 사용할 수 있으며, Orbiter가 가장 가까운 SubspaceLayout 기반 컴포저블 상위 요소에 연결됩니다.
맞춤 위치 기반 수정자를 허용하도록 LayoutCoordinatesAwareModifierNode를 도입했습니다.
SubspaceModifier.Node에 연결/연결 해제 수명 주기 메서드가 추가되었습니다.
이동식 수정자에 scaleWithDistance를 추가했습니다. scaleWithDistance가 사용 설정되면 이동된 하위 공간 요소가 커지거나 작아집니다. 또한 이동하기 전의 명시적 크기도 유지됩니다.

API 변경사항

SessionCallbackProvider가 SpatialCapabilities로 대체되었습니다.

기타 변경사항

minSDK를 24로 줄였습니다. 모든 Jetpack XR API에는 런타임 시 API 34가 계속 필요합니다.
Orbiter EdgeOffset.inner, EdgeOffset.outer, EdgeOffset.overlap 생성자는 더 이상 @Composable 메서드가 아니므로 컴포저블이 아닌 컨텍스트에서 사용할 수 있습니다.
최신 UX 사양에 맞게 공간 고도 수준을 업데이트합니다.
SubspaceSemanticsInfo 인터페이스를 MeasurableLayout에 구현합니다.
SubspaceModifierElement에서 SubspaceModifierNodeElement로 이름이 변경되었습니다.

버그 수정

SubspaceModifier 순서를 안정화하도록 수정했습니다. SubspaceModifier이 더 안정적으로 작동합니다. 이제 오프셋, 회전, 크기 조정, 이동 가능, 크기 조절 가능 수정자를 어떤 순서든 사용할 수 있습니다.

버전 1.0.0-alpha01

2024년 12월 12일

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

초기 출시의 기능

XR용 Jetpack Compose의 초기 개발자 버전입니다. 행 및 열과 같은 익숙한 Compose 개념을 사용하여 기존 2D 앱을 XR로 포팅하거나 새 XR 앱을 처음부터 만드는지와 관계없이 XR에서 공간 UI 레이아웃을 만듭니다. 이 라이브러리는 기존 2D Compose 또는 뷰 기반 UI를 공간 레이아웃에 배치할 수 있는 공간 패널 및 오리터와 같은 하위 공간 및 공간 컴포저블을 제공합니다. Volume 하위 공간 컴포저블을 도입합니다. 이 컴포저블을 사용하면 3D 모델과 같은 SceneCore 항목을 UI를 기준으로 배치할 수 있습니다. 개발자 가이드에서 자세히 알아보세요.
- Subspace: 이 컴포저블은 앱의 UI 계층 구조 내 어디에나 배치할 수 있으므로 파일 간에 컨텍스트를 잃지 않고 2D 및 공간 UI의 레이아웃을 유지할 수 있습니다. 이렇게 하면 전체 UI 트리를 통해 상태를 호이스팅하거나 앱을 재구성하지 않고도 XR과 다른 폼 팩터 간에 기존 앱 아키텍처와 같은 항목을 더 쉽게 공유할 수 있습니다.
- SpatialPanel: 공간 패널은 앱 콘텐츠를 표시할 수 있는 하위 공간 컴포저블입니다. 예를 들어 동영상 재생, 정적 이미지 또는 기타 콘텐츠를 공간 패널에 표시할 수 있습니다.
- Orbiter: Orbiter는 공간 UI 구성요소입니다. 상응하는 공간 패널에 연결되도록 설계되었으며 해당 공간 패널과 관련된 탐색 및 문맥 작업 항목을 포함합니다. 예를 들어 동영상 콘텐츠를 표시하기 위해 공간 패널을 만든 경우 오리터 내부에 동영상 재생 컨트롤을 추가할 수 있습니다.
- 볼륨: 3D 모델과 같은 SceneCore 항목을 UI를 기준으로 배치합니다.
공간 레이아웃: SpatialRow, SpatialColumn, SpatialBox, SpatialLayoutSpacer를 사용하여 여러 공간 패널을 만들고 공간 레이아웃 내에 배치할 수 있습니다. SubspaceModifier를 사용하여 레이아웃을 맞춤설정합니다.
공간 UI 구성요소: 이러한 요소는 2D UI에서 재사용할 수 있으며 공간 속성은 공간 기능이 사용 설정된 경우에만 표시됩니다.
- SpatialDialog: 패널이 z-depth에서 약간 뒤로 밀려 올라간 대화상자를 표시합니다.
- SpatialPopUp: 패널이 z-depth에서 약간 뒤로 밀려 올라간 팝업을 표시합니다.
- SpatialElevation: SpatialElevationLevel를 설정하여 고도를 추가할 수 있습니다.
SpatialCapabilities: 공간 기능은 사용자가 앱 또는 시스템과 상호작용할 때 변경될 수 있으며 앱 자체에서 변경할 수도 있습니다(예: 홈 스페이스 또는 전체 스페이스로 이동). 문제를 방지하려면 앱에서 LocalSpatialCapabilities.current를 확인하여 현재 환경에서 지원되는 API를 결정해야 합니다. isSpatialUiEnabled: 공간 UI 요소 (예: SpatialPanel) isContent3dEnabled: 3D 객체 isAppEnvironmentEnabled: 환경 isPassthroughControlEnabled: 애플리케이션이 패스스루 상태를 제어할 수 있는지 여부 isSpatialAudioEnabled: 서라운드 오디오

알려진 문제

현재 XR용 Jetpack Compose를 사용하려면 최소 SDK가 30이어야 합니다. 해결 방법으로 다음 매니페스트 항목 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>를 추가하여 minSDK 23으로 빌드하고 실행할 수 있습니다.
현재 Jetpack XR 앱은 AndroidManifest에서 android.permission.SCENE_UNDERSTANDING 권한을 요청해야 합니다.
앱이 매니페스트의 PROPERTY_XR_ACTIVITY_START_MODE 속성을 사용하여 전체 공간으로 직접 실행되면 활동/애플리케이션은 처음에 홈 공간에서 열리다가 전체 공간으로 전환됩니다.
볼륨 컴포저블의 glTF가 처음에는 잘못된 위치에서 깜박일 수 있습니다.
크게 이동된 패널에서 SpatialDialog를 사용하면 콘텐츠가 잘못된 방향으로 이동합니다.