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

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

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

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

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

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

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

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

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

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

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

  • 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"))
Environments.kt

สร้างแหล่งข้อมูลรูปภาพ EXR

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

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

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

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

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

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

หากต้องการรับการแจ้งเตือนเกี่ยวกับการเปลี่ยนแปลงสถานะของ 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.
}
Environments.kt

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

สำหรับกรณีการใช้งานขั้นสูงที่ต้องการควบคุมสภาพแวดล้อมอย่างละเอียดยิ่งขึ้น คุณสามารถรวมการตรวจสอบ 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.
}
Environments.kt

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

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

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

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

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

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

ดูเพิ่มเติม