앱에 공간 환경 추가

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

공간 환경 개요

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

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

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

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

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

스카이박스 이미지와 glTF 도형의 조합입니다.
표시되는 환경이 기기의 외부 카메라에서 제공하는 라이브 피드인 패스스루 노출 영역 전체 불투명도에서 이 패스스루 노출 영역은 스카이박스와 도형을 완전히 가립니다.
패스스루 노출 영역이 완전한 불투명도도, 0 불투명도도 아닌 혼합 구성입니다. 이 경우 패스스루 노출 영역이 반투명하게 되고 알파가 그 뒤에 있는 스카이박스 및 도형과 혼합됩니다.

공간 환경을 위한 공간 기능

SpatialCapabilities: 현재 세션의 공간 기능을 나타냅니다. 특정 공간 기능은 공간 환경과 관련이 있습니다.
SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL: 활동이 현재 패스스루를 사용 설정 또는 중지할 수 있는지 여부를 나타냅니다.
SPATIAL_CAPABILITY_APP_ENVIRONMENT: 활동이 현재 시간에 자체 공간 환경을 설정할 수 있는지 여부를 나타냅니다.

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

공간 환경의 glTF 및 EXR 리소스는 Session 클래스에 비동기식으로 로드됩니다. 이러한 파일은 애셋 폴더에 저장해야 합니다.

glTF 리소스 만들기

glTF 리소스는 glTF가 로컬 파일에서 로드되는 GltfModel로 만들 수 있습니다. GltfModel는 공간 앱 환경의 일부로 사용할 수 있습니다.

// assume that session is a Session that has been previously created
val environmentGeometryFuture = session.createGltfResourceAsync("DayGeometry.glb")

val environmentGeometry = environmentGeometryFuture.await()

EXR 이미지 리소스 만들기

EXR 이미지 리소스는 ExrImage로 만들 수 있으며, 여기서 EXR은 로컬 파일에서 로드됩니다. ExrImage는 스카이박스를 그리기 위한 공간 앱 환경의 일부로 사용할 수 있습니다.

// assume that session is a Session that has been previously created
val skyboxExrFuture = session.createExrImageResourceAsync("BlueSkybox.exr")

val skyboxExr = skyboxExrFuture.await()

앱의 SpatialEnvironmentPreference 설정

setSpatialEnvironmentPreference는 앱의 선호하는 공간 환경을 설정하는 데 사용됩니다. 이 메서드는 환경설정만 설정하며 isSpatialEnvironmentPreferenceActive가 이미 true가 아닌 한 즉시 변경되지 않습니다. 기기가 XR 배경을 변경하고 SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT 기능을 사용할 수 있는 상태가 되면 애플리케이션에 선호되는 공간 환경이 자동으로 표시됩니다.

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

주어진 SpatialEnvironmentPreference가 null이 아니지만 모든 속성이 null인 경우 공간 환경은 검은색 스카이박스와 도형으로 구성됩니다.

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

기본 사용법

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

// Assume that session is a Session that has been previously created

// Create a GLTFResource
val environmentGeometry = session.createGltfResourceAsync("DayGeometry.glb").await()

// Create an ExrImage for the skybox
val skyboxExr = session.createExrImageResourceAsync("BlueSkybox.exr").await()

val spatialEnvironmentPreference = SpatialEnvironmentPreference(skyboxExr, environmentGeometry)

val preferenceResult = session.spatialEnvironment.setSpatialEnvironmentPreference(spatialEnvironmentPreference)

if (preferenceResult ==  SpatialEnvironment.SetSpatialEnvironmentPreferenceChangeApplied()) {
   // The environment was successfully updated and is now visible, and any listeners
   // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangePending()) {
    // The environment is in the process of being updated. Once visible, any listeners
   // specified using addOnSpatialEnvironmentChangedListener will be notified.
}

고급 사용법

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

앱의 공간 환경에 PassthroughOpacityPreference 설정

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

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

패스스루 불투명도 환경설정의 값은 0.0f (패스스루 노출 영역이 표시되지 않는 불투명도 0)에서 1.0f (패스스루 노출 영역이 공간 환경을 숨기는 완전 불투명도)까지입니다. setPassthroughOpacityPreference 매개변수는 null이 허용되는 부동 소수점 수입니다. 값을 null로 설정하면 앱에 전달 불투명도 환경설정이 없음을 나타내며 전달 컨트롤을 시스템에 반환합니다.

기본 사용법

이 코드 스니펫은 전달 불투명도 환경설정을 설정합니다. 이 환경설정은 저장되며 앱에 전달 불투명도를 설정하는 기능이 있는 경우 적용됩니다.

// Assume that session is a Session that has been previously created

val preferenceResult = session.spatialEnvironment.setPassthroughOpacityPreference(1.0f)

if (preferenceResult ==  SpatialEnvironment.SetPassthroughOpacityPreferenceChangeApplied()) {
  // The passthrough opacity request succeeded and should be visible now, and any listeners specified using addOnPassthroughOpacityChangedListener
  // will be notified
} else if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangePending()) {
  // 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
}

고급 사용법

패스스루 불투명도를 더 세부적으로 제어해야 하는 고급 사용 사례의 경우 SpatialCapabilities 검사를 통합하고 addOnPassthroughOpacityChangedListener를 구현하여 패스스루 불투명도 환경설정을 설정할 시점을 결정할 수 있습니다.

애셋 최적화

사용자의 SpatialEnvironment 설정을 위한 애셋을 만들 때는 적절한 파일 크기를 유지하면서 애셋의 해상도를 높여야 합니다. glb가 밉맵과 ktx2 텍스처를 사용해야 합니다. 또한 glb 파일의 폴리곤 수를 주의 깊게 살펴봐야 합니다. 폴리곤 수가 많으면 불필요한 전력 소모가 발생할 수 있기 때문입니다. 대부분의 SpatialEnvironment 인스턴스의 파일 크기는 스카이박스에 사용된 이미지에서 비롯됩니다. 이미지가 최적화되었는지 확인하려면 최적화 도구 (예: ktx)를 통해 애셋을 실행합니다.

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

val currentPassthroughOpacity =  session.spatialEnvironment.getCurrentPassthroughOpacity()

참고 항목

공간 환경 설계 가이드