앱에 공간 환경 추가

Jetpack XR SDK에서 공간 환경은 몰입형 주변 환경으로, 앱에 추가하여 가상 장면의 배경을 맞춤설정할 수 있습니다. 공간 환경은 앱이 전체 공간에 있을 때만 표시됩니다.

공간 환경 개요

SpatialEnvironment는 앱의 공간 환경 환경설정을 관리하는 데 사용됩니다. 독립형 스카이박스 이미지와 glTF 지정 지오메트리의 합성입니다. 한 번에 하나의 스카이박스 이미지와 하나의 glTF 형상 파일만 설정할 수 있습니다.

스카이박스는 사용자가 가상 장면에서 주변에 보는 이미지를 나타내며, 하늘, 산, 도시 풍경과 같은 먼 배경 환경의 환상을 만듭니다. 사용자는 스카이박스와 상호작용하거나 스카이박스에 더 가까이 다가갈 수 없습니다. Jetpack XR SDK는 OpenEXR 표준의 구형 스카이박스를 지원합니다. 앱에 몰입형 배경을 제공하는 것 외에도 EXR 스카이박스는 앱에서 로드한 3D 모델에 이미지 기반 조명 (IBL)을 제공합니다. 자세한 내용은 3D 모델 작업 가이드를 참고하세요.

공간 환경에는 glTF 표준의 3D 형상 콘텐츠도 포함될 수 있습니다. 이 방식으로 로드된 환경 지오메트리는 실제 바닥에 자동으로 정렬됩니다. 환경 지오메트리는 시차 효과를 사용하여 스카이박스에 혼합되는 전경 및 중경 요소를 통해 환경에 사실감을 더하는 좋은 방법입니다.

공간 환경 설계 가이드에서는 공간 환경을 만드는 데 사용할 수 있는 다양한 유형의 애셋과 안전하고 즐거운 공간 환경을 만드는 방법을 알아볼 수 있습니다.

앱의 공간 환경을 다음 세 가지 구성 중 하나로 설정할 수 있습니다.

  • 스카이박스 이미지와 glTF 지오메트리의 조합입니다.
  • 환경이 기기의 바깥쪽 카메라에서 전송되는 실시간 피드인 패스스루 표면 완전한 불투명도에서 이 패스스루 표면은 스카이박스와 지오메트리를 완전히 가립니다.
  • 혼합 구성으로, 패스스루 표면이 완전한 불투명도도 아니고 불투명도가 0도 아닙니다. 이 경우 패스스루 표면이 반투명해지고 뒤에 있는 스카이박스 및 지오메트리와 알파 블렌딩됩니다.

공간 환경의 공간 기능

공간 환경 리소스 가져오기 및 로드

공간 환경의 glTF 및 EXR 리소스는 Session 클래스를 사용하여 비동기식으로 로드됩니다.

glTF 리소스 만들기

glTF 리소스는 GltfModel로 만들 수 있으며, 여기서 glTF는 로컬 파일에서 로드됩니다. GltfModel는 공간 앱 환경의 일부로 사용할 수 있습니다.

val environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))
Environments.kt

EXR 이미지 리소스 만들기

EXR 이미지 리소스는 EXR이 로컬 파일에서 로드되는 ExrImage로 만들 수 있습니다. ExrImage는 cmgen와 함께 사용하여 스카이박스의 IBL ZIP 파일을 만들 수 있습니다. 자세한 내용은 환경 애셋 최적화에 관한 가이드를 참고하세요.

val lightingForSkybox = ExrImage.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))
Environments.kt

앱의 SpatialEnvironmentPreference 설정

preferredSpatialEnvironment 속성은 앱의 기본 공간 환경을 제어합니다. 이 속성을 사용하여 환경설정을 지정하면 isPreferredSpatialEnvironmentActive이 이미 true이 아닌 한 즉시 변경되지 않습니다. 기기가 XR 배경을 변경할 수 있고 SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT 기능을 사용할 수 있는 상태가 되면 애플리케이션의 기본 공간 환경이 자동으로 표시됩니다.

환경설정을 null로 설정하면 앱의 기본 공간 환경이 사용 중지되어 대신 기본 시스템 환경이 표시됩니다.

지정된 SpatialEnvironmentPreference이 null이 아니지만 모든 속성이 null이면 공간 환경은 검은색 스카이박스와 도형 없음으로 구성됩니다.

SpatialEnvironment 상태 변경 알림을 받으려면 addOnSpatialEnvironmentChangedListener를 사용하세요.

기본 사용법

이 코드 스니펫은 환경 지오메트리 및 스카이박스 리소스를 만든 다음 공간 환경 환경설정을 설정합니다. 이 환경설정은 저장되며 앱에서 자체 환경을 설정할 수 있는 기능이 있는 경우 적용됩니다.

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
session.scene.spatialEnvironment.preferredSpatialEnvironment = spatialEnvironmentPreference
if (session.scene.spatialEnvironment.isPreferredSpatialEnvironmentActive) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the SPATIAL_CAPABILITY_APP_ENVIRONMENT capability.
    // Then, any listeners specified using addOnSpatialEnvironmentChangedListener
    // will be notified.
}
Environments.kt

고급 사용법

환경을 더 세밀하게 제어해야 하는 고급 사용 사례의 경우 SpatialCapabilities 검사를 통합하고 addOnSpatialEnvironmentChangedListener을 구현하여 공간 환경 환경설정을 설정할 시점을 결정할 수 있습니다.

앱의 공간 환경에 대한 PassthroughOpacityPreference 설정

앱의 몰입형 가상 배경 구성요소 중 하나는 패스스루 표면입니다. 이 경우 표시되는 배경은 기기의 외부를 향하는 카메라의 실시간 피드입니다.

setPassthroughOpacityPreference는 앱의 기본 패스스루 불투명도를 설정하는 데 사용됩니다. 이 메서드는 환경설정만 설정하며 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL 기능을 사용할 수 있는 경우를 제외하고 즉각적인 변경을 일으키지 않습니다. 기기가 패스스루 불투명도를 변경할 수 있는 상태가 되고 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL 기능을 사용할 수 있게 되면 애플리케이션의 기본 패스스루 불투명도가 자동으로 적용됩니다.

패스스루 불투명도 환경설정의 값은 0.0f (불투명도 0, 패스스루 표면이 표시되지 않음)에서 1.0f (불투명도 1, 패스스루 표면이 공간 환경을 숨김)까지입니다. setPassthroughOpacityPreference 매개변수는 null이 허용되는 부동 소수점입니다. 값을 null로 설정하면 앱에 스루 모드 불투명도 환경설정이 없으며 스루 모드 제어를 시스템에 반환함을 나타냅니다.

기본 사용법

이 코드 스니펫은 패스스루 불투명도 환경설정을 설정합니다. 이 환경설정은 기억되며 앱에 패스스루 불투명도를 설정하는 기능이 있을 때 적용됩니다.

session.scene.spatialEnvironment.preferredPassthroughOpacity = 1.0f
if (session.scene.spatialEnvironment.currentPassthroughOpacity == 1.0f) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the
    // SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability.
    // Then, any listeners specified using addOnPassthroughOpacityChangedListener
    // will be notified.
}
Environments.kt

고급 사용법

더 세밀하게 패스스루 불투명도를 제어해야 하는 고급 사용 사례의 경우 SpatialCapabilities 검사를 통합하고 addOnPassthroughOpacityChangedListener를 사용하여 리스너를 추가하여 패스스루 불투명도 환경설정을 설정할 시점을 결정할 수 있습니다.

애셋 최적화

사용자의 SpatialEnvironment를 설정하기 위한 애셋을 만들 때는 적절한 파일 크기를 유지하면서 고품질 해상도를 달성해야 합니다. 자세한 내용은 환경 확장 소재 최적화에 관한 가이드를 참고하세요.

현재 패스스루 불투명도 확인

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity
Environments.kt

참고 항목