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

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

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

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

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

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

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

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

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

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

ความสามารถเชิงพื้นที่สำหรับสภาพแวดล้อมเชิงพื้นที่

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

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

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

นำเข้าและโหลดทรัพยากรสภาพแวดล้อมเชิงพื้นที่

ระบบจะโหลดทรัพยากร glTF และ EXR สำหรับสภาพแวดล้อมเชิงพื้นที่แบบอะซิงโครนัสโดยใช้คลาส Session

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

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

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

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

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

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

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

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

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 ได้ การตั้งค่า เป็น 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 และเพิ่ม Listener โดยใช้ addOnPassthroughOpacityChangedListener เพื่อกำหนดเวลาที่ต้องการตั้งค่ากำหนดความทึบแสงของฟีเจอร์ส่งผ่าน

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

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

กำหนดความทึบแสงของการส่งผ่านปัจจุบัน

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

ดูเพิ่มเติม