เพิ่มสภาพแวดล้อมเชิงพื้นที่ลงในแอป

อุปกรณ์ XR ที่รองรับ

คำแนะนำนี้จะช่วยคุณสร้างประสบการณ์การใช้งานสำหรับอุปกรณ์ XR ประเภทต่อไปนี้

ดูข้อมูลเกี่ยวกับประเภทอุปกรณ์ XR →

ดูข้อมูลเกี่ยวกับประเภทอุปกรณ์ XR →

ใน Jetpack XR SDK สภาพแวดล้อมแบบ Spatial คือสภาพแวดล้อมเสมือนจริงที่คุณสามารถเพิ่มลงในแอปเพื่อปรับแต่งพื้นหลังของฉากเสมือน สภาพแวดล้อมแบบ Spatial จะมองเห็นได้เมื่อแอปอยู่ในโหมด Full Space เท่านั้น

ภาพรวมของสภาพแวดล้อมแบบ Spatial

SpatialEnvironment จะจัดการการตั้งค่าสภาพแวดล้อมแบบ Spatial ของแอป โดยเป็นส่วนประกอบของรูปภาพ Skybox แบบสแตนด์อโลนและรูปทรงเรขาคณิตที่ระบุด้วย glTF คุณตั้งค่ารูปภาพ Skybox และไฟล์รูปทรงเรขาคณิต glTF ได้ครั้งละ 1 รายการเท่านั้น

Skybox แสดงรูปภาพที่ผู้ใช้เห็นรอบตัวในฉากเสมือน ซึ่งสร้างภาพลวงตาของสภาพแวดล้อมพื้นหลังที่อยู่ไกลออกไป เช่น ท้องฟ้า ภูเขา หรือทิวทัศน์ของเมือง ผู้ใช้ไม่สามารถโต้ตอบหรือเข้าใกล้ Skybox ได้ Jetpack XR SDK รองรับ Skybox ทรงกลมตามมาตรฐาน OpenEXR นอกจากจะให้พื้นหลังเสมือนจริงสำหรับแอปแล้ว Skybox EXR ยังให้แสงตามรูปภาพ (IBL) แก่โมเดล 3 มิติที่แอปโหลดด้วย ดูข้อมูลเพิ่มเติมได้ที่คู่มือการทำงานกับโมเดล 3 มิติ

สภาพแวดล้อมแบบ Spatial ยังมีเนื้อหารูปทรงเรขาคณิต 3 มิติตามมาตรฐาน glTF ได้ด้วย รูปทรงเรขาคณิตของสภาพแวดล้อมที่โหลดด้วยวิธีนี้จะจัดแนวกับพื้นจริงโดยอัตโนมัติ รูปทรงเรขาคณิตของสภาพแวดล้อมเป็นวิธีที่ยอดเยี่ยมในการเพิ่มความสมจริงให้กับสภาพแวดล้อมผ่านองค์ประกอบเบื้องหน้าและตรงกลางที่ผสานรวมเข้ากับ Skybox ด้วยเอฟเฟกต์พารัลแลกซ์

ในคำแนะนำการออกแบบสำหรับสภาพแวดล้อมแบบ Spatial คุณจะได้เรียนรู้เกี่ยวกับ ชิ้นงานประเภทต่างๆ ที่ใช้สร้างสภาพแวดล้อมแบบ Spatial ได้ รวมถึงวิธี สร้างสภาพแวดล้อมแบบ Spatial ที่ปลอดภัยและสนุกสนาน

คุณสามารถตั้งค่าสภาพแวดล้อมแบบ Spatial ของแอปเป็นการกำหนดค่า 1 ใน 3 แบบต่อไปนี้

• การผสมผสานระหว่างรูปภาพ Skybox และรูปทรงเรขาคณิต glTF
• พื้นผิวแบบ Passthrough ซึ่งสภาพแวดล้อมที่แสดงคือฟีดสดจากกล้องที่หันออกด้านนอกของอุปกรณ์ เมื่อมีความทึบแสงเต็มที่ พื้นผิวแบบ Passthrough นี้จะบดบัง Skybox และรูปทรงเรขาคณิตโดยสมบูรณ์
• การกำหนดค่าแบบผสม ซึ่งพื้นผิวแบบ Passthrough ไม่มีความทึบแสงเต็มที่และไม่มีความทึบแสงเป็น 0 ในกรณีนี้ พื้นผิวแบบ Passthrough จะโปร่งแสงและผสานรวมกับ Skybox และรูปทรงเรขาคณิตที่อยู่ด้านหลัง

ความสามารถแบบ Spatial สำหรับสภาพแวดล้อมแบบ Spatial

• SpatialCapabilities: แสดงความสามารถแบบ Spatial ของเซสชันปัจจุบัน ความสามารถแบบ Spatial บางอย่างเกี่ยวข้องกับสภาพแวดล้อมแบบ Spatial

• SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL: บ่งชี้ว่ากิจกรรมสามารถเปิดหรือปิดใช้ Passthrough ได้ในขณะนี้หรือไม่

• SPATIAL_CAPABILITY_APP_ENVIRONMENT: บ่งชี้ว่ากิจกรรมสามารถตั้งค่าสภาพแวดล้อมแบบ Spatial ของตัวเองได้ในขณะนี้หรือไม่

นำเข้าและโหลดทรัพยากรสภาพแวดล้อมแบบ Spatial

ระบบจะโหลดทรัพยากร glTF และ EXR สำหรับสภาพแวดล้อมแบบ Spatial แบบไม่พร้อมกันโดย ใช้คลาส Session

สร้างทรัพยากร glTF

คุณสร้างทรัพยากร glTF เป็น GltfModel ได้ โดยจะโหลด glTF จากไฟล์ในเครื่อง และใช้ GltfModel เป็นส่วนหนึ่งของสภาพแวดล้อมแบบ Spatial ของแอปได้

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

สร้างทรัพยากรแสงตามรูปภาพ

คุณสร้างทรัพยากรแสงตามรูปภาพเป็น ImageBasedLightingAsset ได้ โดยจะโหลดแสงจากไฟล์ในเครื่อง และใช้ ImageBasedLightingAsset กับ cmgen เพื่อสร้างไฟล์ ZIP ของ IBL สำหรับ Skybox ได้ ดูรายละเอียดเพิ่มเติมได้ที่คำแนะนำเกี่ยวกับการเพิ่มประสิทธิภาพชิ้นงานสภาพแวดล้อม

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

ตั้งค่า SpatialEnvironmentPreference สำหรับแอป

พร็อพเพอร์ตี้ preferredSpatialEnvironment จะควบคุมสภาพแวดล้อมแบบ Spatial ที่ต้องการสำหรับแอป เมื่อใช้พร็อพเพอร์ตี้นี้เพื่อตั้งค่าที่ต้องการ การเปลี่ยนแปลงจะไม่เกิดขึ้นในทันที เว้นแต่ว่า isPreferredSpatialEnvironmentActive จะเป็น true อยู่แล้ว เมื่ออุปกรณ์เข้าสู่สถานะที่สามารถเปลี่ยนแปลงพื้นหลัง XR ได้ และ SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT พร้อมใช้งาน ระบบจะแสดงสภาพแวดล้อมแบบ Spatial ที่ต้องการสำหรับแอปพลิเคชัน โดยอัตโนมัติ

การตั้งค่าที่ต้องการเป็น null จะปิดใช้สภาพแวดล้อมแบบ Spatial ที่ต้องการสำหรับแอป ซึ่งหมายความว่าระบบจะแสดงสภาพแวดล้อมเริ่มต้นแทน

หาก SpatialEnvironmentPreference ที่ระบุไม่ใช่ Null แต่พร็อพเพอร์ตี้ทั้งหมด เป็น Null สภาพแวดล้อมแบบ Spatial จะประกอบด้วย Skybox สีดำ และไม่มีรูปทรงเรขาคณิต

หากต้องการรับการแจ้งเตือนเกี่ยวกับการเปลี่ยนแปลงสถานะ SpatialEnvironment ให้ใช้ addOnSpatialEnvironmentChangedListener

การใช้งานพื้นฐาน

ข้อมูลโค้ดนี้จะสร้างทรัพยากรรูปทรงเรขาคณิตของสภาพแวดล้อมและ Skybox แล้วตั้งค่าที่ต้องการสำหรับสภาพแวดล้อมแบบ Spatial ระบบจะจดจำค่าที่ต้องการนี้และนำไปใช้เมื่อแอปมีความสามารถในการตั้งค่าสภาพแวดล้อมของตัวเอง

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 เพื่อกำหนดเวลาที่ต้องการตั้งค่า ที่ต้องการสำหรับสภาพแวดล้อมแบบ Spatial

ตั้งค่า PassthroughOpacityPreference สำหรับสภาพแวดล้อมแบบ Spatial ของแอป

พื้นผิวแบบ Passthrough เป็นหนึ่งในคอมโพเนนต์ของพื้นหลังเสมือนจริงเสมือนจริงของแอป ในกรณีนี้ พื้นหลังที่แสดงคือฟีดสดจากกล้องที่หันออกด้านนอกของอุปกรณ์

setPassthroughOpacityPreference ใช้เพื่อตั้งค่าที่ต้องการสำหรับความทึบแสงแบบ Passthrough ของแอป เมธอดนี้จะตั้งค่าที่ต้องการเท่านั้นและจะไม่ทำให้เกิดการเปลี่ยนแปลงในทันที เว้นแต่ว่าความสามารถ SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL จะพร้อมใช้งาน เมื่ออุปกรณ์เข้าสู่สถานะที่สามารถเปลี่ยนแปลงความทึบแสงแบบ Passthrough ได้ และความสามารถ SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL พร้อมใช้งาน ระบบจะใช้ค่าที่ต้องการสำหรับความทึบแสงแบบ Passthrough ของแอปพลิเคชันโดยอัตโนมัติ

ค่าที่ต้องการสำหรับความทึบแสงแบบ Passthrough มีตั้งแต่ 0.0f (ความทึบแสงเป็น 0 ซึ่งพื้นผิวแบบ Passthrough มองไม่เห็น) ถึง 1.0f (ความทึบแสงเต็มที่ ซึ่งพื้นผิวแบบ Passthrough จะซ่อนสภาพแวดล้อมแบบ Spatial) พารามิเตอร์ setPassthroughOpacityPreference เป็นค่า Float ที่อนุญาตให้เป็น Null ได้ การตั้งค่าเป็น Null บ่งชี้ว่าแอปไม่มีค่าที่ต้องการสำหรับความทึบแสงแบบ Passthrough และจะส่งคืนการควบคุม Passthrough ไปยังระบบ

การใช้งานพื้นฐาน

ข้อมูลโค้ดนี้จะตั้งค่าที่ต้องการสำหรับความทึบแสงแบบ Passthrough ระบบจะจดจำค่าที่ต้องการนี้และนำไปใช้เมื่อแอปมีความสามารถในการตั้งค่าความทึบแสงแบบ Passthrough

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

การใช้งานขั้นสูง

สำหรับกรณีการใช้งานขั้นสูงเพิ่มเติมที่คุณต้องการควบคุมความทึบแสงแบบ Passthrough ได้ละเอียดยิ่งขึ้น คุณสามารถรวมการตรวจสอบ SpatialCapabilities และเพิ่ม Listener โดยใช้ addOnPassthroughOpacityChangedListener เพื่อกำหนดเวลาที่ต้องการ ตั้งค่าที่ต้องการสำหรับความทึบแสงแบบ Passthrough

การเพิ่มประสิทธิภาพชิ้นงาน

เมื่อสร้างชิ้นงานสำหรับการตั้งค่า SpatialEnvironment ของผู้ใช้ ให้ตรวจสอบว่าชิ้นงานมีความละเอียดสูงในขณะที่ยังคงขนาดไฟล์ที่เหมาะสม ดูข้อมูลเพิ่มเติมได้ที่ คำแนะนำเกี่ยวกับการเพิ่มประสิทธิภาพชิ้นงานสภาพแวดล้อม

กำหนดความทึบแสงแบบ Passthrough ปัจจุบัน

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

ดูเพิ่มเติม

• คำแนะนำการออกแบบสภาพแวดล้อมแบบ Spatial