앱에 공간 환경 추가

적용 가능한 XR 기기
이 가이드는 이러한 유형의 XR 기기를 위한 환경을 빌드하는 데 도움이 됩니다.
XR 기기 유형 알아보기 →
XR 헤드셋
유선 XR 글라스
XR 기기 유형 알아보기 →

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"))

이미지 기반 조명 리소스 만들기

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

val lightingForSkybox = ImageBasedLightingAsset.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))

앱의 SpatialEnvironmentPreference 설정

preferredSpatialEnvironment 속성은 앱의 기본 공간 환경을 제어합니다. 이 속성을 사용하여 환경설정을 지정하면 isPreferredSpatialEnvironmentActive가 이미 true가 아닌 한 즉시 변경되지 않습니다. 기기가 XR 배경을 변경할 수 있는 상태가 되고 SpatialCapability.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.
}

고급 사용법

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

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

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

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

패스 스루 불투명도 환경설정 값의 범위는 0.0f(불투명도 0, 패스 스루 표면이 보이지 않음)에서 1.0f(완전 불투명, 패스 스루 표면이 공간 환경을 숨김)까지입니다. 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.
}

고급 사용법

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

애셋 최적화

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

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

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

참고 항목