앱에 공간 환경 추가

적용 가능한 XR 기기
이 가이드에서는 이러한 유형의 XR 기기를 위한 환경을 빌드하는 방법을 설명합니다.
XR 기기 유형 알아보기 →
XR 헤드셋
유선 XR 글래스
XR 기기 유형 알아보기 →

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

공간 환경 개요

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

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

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

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

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

  • 스카이박스 이미지와 glTF 도형의 조합
  • 패스스루 표면: 표시되는 환경은 기기의 바깥쪽 카메라에서 가져온 실시간 피드입니다. 완전 불투명도에서 이 패스스루 표면은 스카이박스와 도형을 완전히 가립니다.
  • 혼합 구성: 패스스루 표면이 완전 불투명도도 아니고 불투명도가 0도 아닙니다. 이 경우 패스스루 표면이 반투명해지고 뒤에 있는 스카이박스 및 도형과 알파 혼합됩니다.

공간 환경의 공간 기능

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

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

glTF 리소스 만들기

glTF 리소스는 glTF가 로컬 파일에서 로드되는 GltfModel로 만들 수 있습니다. 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 배경을 변경할 수 있는 상태로 전환되고 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.
}

고급 사용법

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

앱의 공간 환경에 PassthroughOpacityPreference 설정

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

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

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

고급 사용법

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

애셋 최적화

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

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

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

참고 항목