XR_EXT_spatial_container_self_rendering

Name String

XR_EXT_spatial_container_self_rendering

ประเภทส่วนขยาย

ส่วนขยายอินสแตนซ์

หมายเลขต่อที่ลงทะเบียนไว้

814

การแก้ไข

1

สถานะการให้สัตยาบัน

ไม่ได้รับการให้สัตยาบัน

ทรัพยากร Dependency ของส่วนขยายและเวอร์ชัน

XR_EXT_spatial_container

วันที่แก้ไขล่าสุด

2026-08-06

สถานะ IP

ไม่มีการอ้างสิทธิ์ IP ที่ทราบ

ผู้เขียน

Lachlan Ford, Google
Andreas Loeve Selvik, Meta Platforms
Adam Gousetis, Meta Platforms
Bjorn Swenson, LÖVR
Cass Everitt, Meta Platforms
Christian Kruse, Meta Platforms
Denny Rönngren, Varjo Technologies
Fredia Huya-Kouadio, Godot Engine
Jakob Bornecrantz, NVIDIA
Jared Finder, Google
Jonathan Wright, Meta Platforms
Jian Zhang, ByteDance
Kurtis Eveleigh, Qualcomm
Mauricio Narvaez, Meta Platforms
Nick Klingensmith, Qualcomm
Nikita Lutsenko, Meta Platforms
Praveen Babu J D, ByteDance
Rylie Pavlik, Collabora
Salar Khan, Google
Shuai Liu, ByteDance
Walter Luh, Meta Platforms
Yin Li, Microsoft

ภาพรวม

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

ส่วนขยายนี้เมื่อใช้ร่วมกับ XR_EXT_spatial_container มีไว้เพื่อนำเสนอความสามารถที่เหนือกว่าของการแสดงผลเลเยอร์องค์ประกอบหลัก OpenXR 1.x แบบเดิม รันไทม์ OpenXR 1.x ที่รองรับการแสดงผลกราฟิกและส่วนขยายนี้ต้องตั้งค่า XrSystemSpatialContainerPropertiesEXT :: supportsImmersive เป็น "จริง" เพื่อระบุว่ารองรับคอนเทนเนอร์เชิงพื้นที่ที่สมจริง

วงจรการแสดงผลคอนเทนเนอร์เชิงพื้นที่

หากต้องการใช้การแสดงผลด้วยตนเองสำหรับคอนเทนเนอร์เชิงมิติพื้นที่ แอปจะตั้งค่า XrSpatialContainerCreateInfoEXT :: graphicsPresentation เป็น XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT เมื่อเรียกใช้ xrCreateSpatialContainerEXT จากนั้นแอปดังกล่าวจะสามารถจัดการได้ว่าคอนเทนเนอร์เชิงพื้นที่จะแสดงผลอยู่หรือไม่โดยเรียกใช้ฟังก์ชัน xrBeginSpatialContainerRenderingEXT และ xrEndSpatialContainerRenderingEXT ฟังก์ชันเหล่านี้จะแทนที่ xrBeginSession และ xrEndSession ซึ่งไม่ใช่การดำเนินการต่อเฟรม เช่น xrBeginFrame และ xrEndFrame

ทุกเฟรม แอปจะทำตามขั้นตอนต่อไปนี้

  • เรียกใช้ xrWaitFrame และ xrBeginFrame ฟังก์ชันเหล่านี้ไม่มีโครงสร้างเฉพาะคอนเทนเนอร์และทำงานเหมือนกับในข้อกำหนดหลัก
  • ดึงข้อมูลท่าทางการมอง พารามิเตอร์การฉายภาพ และคำแนะนำในการแสดงผลสำหรับคอนเทนเนอร์เชิงพื้นที่ทั้งหมดที่แสดงผลอยู่ด้วย xrLocateSpatialContainerViewsEXT สำหรับคอนเทนเนอร์เชิงพื้นที่แต่ละรายการ รันไทม์จะรายงานว่าเลเยอร์องค์ประกอบควรแสดงผลหรือไม่ และวิธีที่แนะนำในการแสดงผลเลเยอร์โดยการกรอก XrSpatialContainerViewStateEXT
  • แสดงผลพิกเซลเป็นเลเยอร์องค์ประกอบตามปกติ การดำเนินการเหล่านี้ไม่มีโครงสร้างเฉพาะคอนเทนเนอร์
  • ส่งเลเยอร์องค์ประกอบสำหรับคอนเทนเนอร์เชิงพื้นที่ทั้งหมดที่แสดงผลอยู่โดยเรียกใช้ xrEndFrame และเชื่อมโยง XrSpatialContainerLayerFrameEndInfoEXT

การทำลายแฮนเดิล XrSpatialContainerEXT จะนำแฮนเดิลออกจากชุดการแสดงผลที่ใช้งานอยู่โดยนัย แอปอาจทำลายคอนเทนเนอร์เชิงพื้นที่แม้ว่าจะเรียกใช้ xrBeginSpatialContainerRenderingEXT สำเร็จแล้วก็ตาม โดยไม่เชื่อมโยงกับการเรียกใช้ xrEndSpatialContainerRenderingEXT ที่เกี่ยวข้อง รันไทม์ต้องทำงานราวกับว่ามีการเรียกใช้ xrEndSpatialContainerRenderingEXT โดยนัยหากจำเป็นในช่วงต้นของการติดตั้งใช้งาน xrDestroySpatialContainerEXT หากแสดงผลสำเร็จ

เมื่อแอปได้รับเหตุการณ์ XrEventDataSpatialContainerClosedEXT สำหรับคอนเทนเนอร์ในชุดการแสดงผลที่ใช้งานอยู่ แอปนั้นควรเรียกใช้ xrEndSpatialContainerRenderingEXT และทำลายแฮนเดิล XrSpatialContainerEXT

ฟังก์ชัน xrBeginSpatialContainerRenderingEXT จะเพิ่มคอนเทนเนอร์เชิงพื้นที่ลงในชุดการแสดงผลที่ใช้งานอยู่ต่อเซสชัน ซึ่งช่วยให้แอปส่งเลเยอร์องค์ประกอบสำหรับคอนเทนเนอร์เชิงพื้นที่ไปยัง xrEndFrame ได้

XrResult xrBeginSpatialContainerRenderingEXT(
    XrSession                                   session,
    const XrSpatialContainerBeginInfoEXT*       beginInfo);

คำอธิบายพารามิเตอร์

โดยปกติแล้ว แอปจะเรียกใช้เมธอดนี้เพื่อตอบสนองต่อเหตุการณ์ visible-changed โดยตั้งค่า XrEventDataSpatialContainerVisibleChangedEXT :: visible เป็น "จริง"

หากไม่ได้สร้างคอนเทนเนอร์เชิงพื้นที่ด้วย XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT เมื่อเรียกใช้ xrCreateSpatialContainerEXT รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT

หากคอนเทนเนอร์เชิงพื้นที่อยู่ในชุดการแสดงผลที่ใช้งานอยู่แล้ว รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT

หากมีการเรียกใช้ xrBeginSpatialContainerRenderingEXT ในเวลาที่แอปไม่สามารถเรียกใช้ xrWaitFrame (เช่น ภายในหน้าต่าง xrBeginFrame และ xrEndFrame) รันไทม์ต้องแสดงผล XR_ERROR_CALL_ORDER_INVALID

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_container_self_rendering ก่อนเรียกใช้ xrBeginSpatialContainerRenderingEXT
  • session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
  • beginInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialContainerBeginInfoEXT ที่ถูกต้อง

ความปลอดภัยของชุดข้อความ

รหัสการคืนสินค้า

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT
  • XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

โครงสร้าง XrSpatialContainerBeginInfoEXT ใช้เพื่อระบุพารามิเตอร์สำหรับการเริ่มแสดงผลคอนเทนเนอร์เชิงมิติพื้นที่

typedef struct XrSpatialContainerBeginInfoEXT {
    XrStructureType            type;
    const void*                next;
    XrSpatialContainerEXT      spatialContainer;
    XrViewConfigurationType    primaryViewConfigurationType;
} XrSpatialContainerBeginInfoEXT;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • spatialContainer คือ XrSpatialContainerEXT เพื่อเริ่มการแสดงผล
  • primaryViewConfigurationType คือ XrViewConfigurationType หลักที่จะใช้สำหรับคอนเทนเนอร์เชิงมิติพื้นที่

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

การใช้งานที่ถูกต้อง (โดยนัย)

ฟังก์ชัน xrEndSpatialContainerRenderingEXT จะนำคอนเทนเนอร์เชิงพื้นที่ออกจากชุดการแสดงผลที่ใช้งานอยู่

XrResult xrEndSpatialContainerRenderingEXT(
    XrSession                                   session,
    const XrSpatialContainerEndInfoEXT*         endInfo);

คำอธิบายพารามิเตอร์

โดยทั่วไปแล้ว แอปจะเรียกใช้ฟังก์ชันนี้เพื่อตอบสนองต่อเหตุการณ์ visible-changed โดยตั้งค่า XrEventDataSpatialContainerVisibleChangedEXT :: visible เป็นเท็จ

หากคอนเทนเนอร์เชิงพื้นที่ไม่อยู่ในชุดการแสดงผลที่ใช้งานอยู่ รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT

หากมีการเรียกใช้ xrEndSpatialContainerRenderingEXT ในเวลาที่แอปไม่สามารถเรียกใช้ xrWaitFrame (เช่น ในช่วงเวลาระหว่างการเรียกใช้ xrBeginFrame และ xrEndFrame) รันไทม์ต้องแสดงผล XR_ERROR_CALL_ORDER_INVALID

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_container_self_rendering ก่อนเรียกใช้ xrEndSpatialContainerRenderingEXT
  • session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
  • endInfo ต้องเป็นพอยเตอร์ไปยังโครงสร้าง XrSpatialContainerEndInfoEXT ที่ถูกต้อง

ความปลอดภัยของชุดข้อความ

รหัสการคืนสินค้า

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT
  • XR_ERROR_VALIDATION_FAILURE

โครงสร้าง XrSpatialContainerEndInfoEXT ใช้เพื่อระบุพารามิเตอร์สำหรับการสิ้นสุดการแสดงผลคอนเทนเนอร์เชิงพื้นที่

typedef struct XrSpatialContainerEndInfoEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrSpatialContainerEndInfoEXT;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • spatialContainer คือ XrSpatialContainerEXT เพื่อสิ้นสุดการแสดงผล

การใช้งานที่ถูกต้อง (โดยนัย)

การค้นหามุมมองผ่าน xrLocateSpatialContainerViewsEXT

ฟังก์ชัน xrLocateSpatialContainerViewsEXT จะค้นหามุมมองสำหรับชุดคอนเทนเนอร์เชิงพื้นที่

XrResult xrLocateSpatialContainerViewsEXT(
    XrSession                                   session,
    const XrSpatialContainerViewsLocateInfoEXT* locateInfo,
    uint32_t                                    viewStateCount,
    XrSpatialContainerViewStateEXT*             viewStates,
    uint32_t                                    viewCount,
    XrView*                                     views);

คำอธิบายพารามิเตอร์

  • session คือ XrSession
  • locateInfo เป็นตัวชี้ไปยังโครงสร้าง XrSpatialContainerViewsLocateInfoEXT
  • viewStateCount คือจำนวนของอาร์เรย์ viewStates
  • viewStates คือตัวชี้ไปยังอาร์เรย์ของโครงสร้าง XrSpatialContainerViewStateEXT ที่รันไทม์จะสร้างขึ้น
  • viewCount คือจำนวนของอาร์เรย์ views
  • views เป็นตัวชี้ไปยังอาร์เรย์ของโครงสร้าง XrView

ฟังก์ชันนี้จะแทนที่ xrLocateViews ซึ่งช่วยให้แอปค้นหามุมมองสำหรับคอนเทนเนอร์เชิงพื้นที่หลายรายการพร้อมกันได้

ระบบจะแสดงผลมุมมองสำหรับคอนเทนเนอร์เชิงพื้นที่ทั้งหมดในอาร์เรย์ views เดียว มุมมองจะเรียงลำดับตามดัชนีของคอนเทนเนอร์เชิงพื้นที่ในอาร์เรย์ XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfos จากนั้นจึงเป็นดัชนีมุมมองสำหรับคอนเทนเนอร์นั้น

ตัวอย่างเช่น หากแอปมีคอนเทนเนอร์เชิงพื้นที่ 3 รายการใน XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfos :

  • ดัชนี 0: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO (1 ยอดดู)
  • ดัชนี 1: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO (ยอดดู 2 ครั้ง)
  • ดัชนี 2: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO_WITH_FOVEATED_INSET (ยอดดู 4 ครั้ง)

จากนั้นรันไทม์ต้องกรอกอาร์เรย์ views ด้วยมุมมอง 7 รายการ ดังนี้

  • views [0] คือมุมมองสำหรับคอนเทนเนอร์ 0
  • views [1] คือมุมมองตาซ้ายสำหรับคอนเทนเนอร์ 1
  • views [2] คือมุมมองตาขวาสำหรับคอนเทนเนอร์ 1
  • views [3] คือมุมมองตาซ้ายสำหรับคอนเทนเนอร์ 2
  • views [4] คือมุมมองตาขวาสำหรับคอนเทนเนอร์ 2
  • views [5] คือมุมมองแทรกของตาซ้ายสำหรับคอนเทนเนอร์ 2
  • views [6] คือมุมมองแทรกของตาขวาสำหรับคอนเทนเนอร์ 2

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

รันไทม์อาจลดการกำหนดค่ามุมมองเป็นประเภทที่มีมุมมองน้อยลงเพื่อวัตถุประสงค์ในการเพิ่มประสิทธิภาพ (เช่น คอนเทนเนอร์อยู่ไกลมากและมีขนาดเล็กจนมองไม่เห็นสเตอริโอ) หากรันไทม์ลดจำนวนการกำหนดค่ามุมมอง รันไทม์ต้องยังคงแสดงผลจำนวนมุมมองเดิมสำหรับคอนเทนเนอร์นั้น โดยสร้างมุมมองเพิ่มเติมด้วยมุมมองที่ลดจำนวนลงที่ซ้ำกัน ตัวอย่างเช่น หาก XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO ลดลงเป็น XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO ทั้งดัชนี 0 และดัชนี 1 จะมีมุมมองโมโนเดียว ด้วยเหตุนี้ จำนวนยอดดูทั้งหมดที่แสดงผลในอาร์เรย์ views จึงไม่ขึ้นอยู่กับว่ารันไทม์ตัดสินใจที่จะลดการกำหนดค่ามุมมองหรือไม่

รันไทม์ควรปรับ XrView :: fov แต่ละรายการที่แสดงผลเพื่อให้ฟรัสตัมมีขนาดเล็กที่สุดเท่าที่จะเป็นไปได้ แต่ยังคงมีขอบเขตทั้งหมดของคอนเทนเนอร์เชิงพื้นที่ที่เกี่ยวข้อง รันไทม์อาจแสดง FOV ที่ไม่สมมาตร เช่น หากคอนเทนเนอร์เชิงพื้นที่อยู่ในมุมเอียงกับมุมมองของผู้ใช้ หรือถูกวัตถุอื่นบดบังบางส่วน รันไทม์อาจจัดตำแหน่งพื้นผิวการแสดงผลเป้าหมายสำหรับคอนเทนเนอร์เชิงพื้นที่ได้อย่างอิสระ เนื่องจากลักษณะของการแสดงผลหลายแอป ซึ่งคอนเทนเนอร์เชิงพื้นที่แยกออกจากผู้ใช้ รันไทม์อาจแสดงผลค่า XrView ที่ไม่เหมาะสำหรับการแสดงผลพิกเซล เช่น หากคอนเทนเนอร์เชิงพื้นที่ไม่ปรากฏบนหน้าจอ ก็จะไม่มีค่าที่ถูกต้องสำหรับตั้งค่า XrView :: fov ในกรณีเช่นนี้ รันไทม์ต้องตั้งค่า XrSpatialContainerViewStateEXT :: shouldSubmitLayers เป็นเท็จ

รันไทม์จะแสดงข้อมูลสถานะการแสดงผลคอนเทนเนอร์เชิงพื้นที่เพิ่มเติมในอาร์เรย์ viewStates หาก viewStateCount ไม่เท่ากับ XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfoCount รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE

หลังจากรันไทม์จัดคิวเหตุการณ์ XrEventDataSpatialContainerClosedEXT สำหรับคอนเทนเนอร์เชิงมิติพื้นที่ ฟังก์ชันนี้ต้องแสดงผล XR_FALSE ใน XrSpatialContainerViewStateEXT :: shouldSubmitLayers และ 0 ใน XrSpatialContainerViewStateEXT :: viewStateFlags สำหรับคอนเทนเนอร์เชิงมิติพื้นที่ที่เกี่ยวข้อง

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

หากมีการเรียกใช้ xrLocateSpatialContainerViewsEXT สำหรับคอนเทนเนอร์เชิงพื้นที่อย่างน้อย 1 รายการที่ไม่ได้อยู่ในชุดการแสดงผลที่ใช้งานอยู่ในปัจจุบัน รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_container_self_rendering ก่อนเรียกใช้ xrLocateSpatialContainerViewsEXT
  • session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
  • locateInfo ต้องเป็นพอยเตอร์ไปยังโครงสร้าง XrSpatialContainerViewsLocateInfoEXT ที่ถูกต้อง
  • viewStates ต้องเป็นตัวชี้ไปยังอาร์เรย์ของโครงสร้าง viewStateCount XrSpatialContainerViewStateEXT
  • views ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของโครงสร้าง viewCount XrView
  • พารามิเตอร์ viewStateCount ต้องมากกว่า 0
  • พารามิเตอร์ viewCount ต้องมากกว่า 0

รหัสการคืนสินค้า

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

โครงสร้าง XrSpatialContainerViewsLocateInfoEXT มีพารามิเตอร์สำหรับค้นหามุมมองในคอลเล็กชันคอนเทนเนอร์เชิงพื้นที่

typedef struct XrSpatialContainerViewsLocateInfoEXT {
    XrStructureType                               type;
    const void*                                   next;
    XrTime                                        displayTime;
    uint32_t                                      viewLocateInfoCount;
    const XrSpatialContainerViewLocateInfoEXT*    viewLocateInfos;
} XrSpatialContainerViewsLocateInfoEXT;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • displayTime คือ XrTime ที่ใช้ค้นหามุมมอง
  • viewLocateInfoCount คือจำนวนรายการในอาร์เรย์ viewLocateInfos
  • viewLocateInfos เป็นตัวชี้ไปยังอาร์เรย์ของโครงสร้าง XrSpatialContainerViewLocateInfoEXT

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_container_self_rendering ก่อนใช้ XrSpatialContainerViewsLocateInfoEXT
  • type ต้องเป็น XR_TYPE_SPATIAL_CONTAINER_VIEWS_LOCATE_INFO_EXT
  • next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • viewLocateInfos ต้องเป็นพอยเตอร์ไปยังอาร์เรย์ของโครงสร้าง XrSpatialContainerViewLocateInfoEXT ที่ถูกต้อง viewLocateInfoCount รายการ
  • พารามิเตอร์ viewLocateInfoCount ต้องมากกว่า 0

โครงสร้าง XrSpatialContainerViewLocateInfoEXT มีพารามิเตอร์สำหรับคอนเทนเนอร์เชิงพื้นที่แต่ละรายการเพื่อค้นหามุมมอง

typedef struct XrSpatialContainerViewLocateInfoEXT {
    XrStructureType            type;
    const void*                next;
    XrViewConfigurationType    viewConfigurationType;
    XrSpace                    space;
    XrSpatialContainerEXT      spatialContainer;
} XrSpatialContainerViewLocateInfoEXT;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • viewConfigurationType คือ XrViewConfigurationType ที่จะใช้สำหรับคอนเทนเนอร์เชิงมิติพื้นที่
  • space คือ XrSpace ที่มุมมองของคอนเทนเนอร์เชิงมิติตั้งอยู่
  • spatialContainer คือแฮนเดิล XrSpatialContainerEXT

แอปสามารถระบุ XrSpace ที่ถูกต้องใน space อย่างไรก็ตาม ขอแนะนำให้ระบุพื้นที่คอนเทนเนอร์เชิงมิติพื้นที่สำหรับ XrSpatialContainerEXT ที่เกี่ยวข้องซึ่งระบุไว้ภายในโครงสร้าง XrSpatialContainerViewLocateInfoEXT

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_container_self_rendering ก่อนใช้ XrSpatialContainerViewLocateInfoEXT
  • type ต้องเป็น XR_TYPE_SPATIAL_CONTAINER_VIEW_LOCATE_INFO_EXT
  • next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • viewConfigurationType ต้องเป็นค่า XrViewConfigurationType ที่ถูกต้อง
  • space ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง
  • spatialContainer ต้องเป็นแฮนเดิล XrSpatialContainerEXT ที่ถูกต้อง
  • ทั้ง space และ spatialContainer ต้องสร้าง จัดสรร หรือดึงข้อมูลจาก XrSession เดียวกัน

โครงสร้าง XrSpatialContainerViewStateEXT จะสร้างขึ้นโดยการเรียกใช้ xrLocateSpatialContainerViewsEXT พร้อมข้อมูลความเหมาะสมในการแสดงผลคอนเทนเนอร์เชิงพื้นที่ต่อรายการ

typedef struct XrSpatialContainerViewStateEXT {
    XrStructureType            type;
    void*                      next;
    XrViewStateFlags           viewStateFlags;
    XrViewConfigurationType    viewConfigurationType;
    XrBool32                   shouldSubmitLayers;
    XrExtent2Di                recommendedImageExtent;
} XrSpatialContainerViewStateEXT;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • viewStateFlags คือบิตมาสก์ของ XrViewStateFlags แฟล็กเหล่านี้มีวัตถุประสงค์เดียวกับ viewStateFlags ในโครงสร้าง XrViewState หลัก
  • viewConfigurationType คือ XrViewConfigurationType ซึ่งระบุประเภทการกำหนดค่ามุมมองที่รันไทม์ใช้สำหรับคอนเทนเนอร์เชิงพื้นที่ ซึ่งรันไทม์อาจลดลงเป็นการกำหนดค่ามุมมองที่มีจำนวนมุมมองต่ำกว่าที่ขอ
  • shouldSubmitLayers คือ XrBool32 ที่รันไทม์แสดงผล หาก XR_FALSE แอปควรหลีกเลี่ยงการส่งองค์ประกอบสำหรับคอนเทนเนอร์เชิงพื้นที่นี้ เนื่องจากปัจจุบันมองไม่เห็นหรืออยู่ในสถานะที่ไม่จำเป็นต้องแสดงผล
  • recommendedImageExtent คือโครงสร้าง XrExtent2Di ที่แสดงความละเอียดที่แนะนำสำหรับคอนเทนเนอร์เชิงพื้นที่

เช่นเดียวกับตำแหน่งมุมมอง OpenXR หลัก แอปต้องตรวจสอบ XrSpatialContainerViewStateEXT :: viewStateFlags เพื่อให้แน่ใจว่าตำแหน่งและการวางแนวถูกต้องและได้รับการติดตามก่อนที่จะใช้ข้อมูลมุมมองสำหรับการแสดงผล

แอปควรตรวจสอบ shouldSubmitLayers และ viewConfigurationType เพื่อหลีกเลี่ยงการแสดงผลเกินกว่าที่รันไทม์แนะนำ เมื่อ shouldSubmitLayers เป็นเท็จ แอปจะเปลี่ยนลักษณะการแสดงผลดังนี้

  • แอปต้องไม่อ่าน XrView :: fov ที่เกี่ยวข้อง
  • แอปต้องไม่อ่าน recommendedImageExtent
  • แอปควรหลีกเลี่ยงการแสดงผลไปยัง Swapchain และการส่งเลเยอร์องค์ประกอบสำหรับคอนเทนเนอร์เชิงพื้นที่ที่เกี่ยวข้อง
  • แอปควรตั้งค่า XrSpatialContainerLayerEXT :: retainPreviousSubmission เป็น "จริง" หากแอปเลือกที่จะส่งเลเยอร์อยู่ดี รันไทม์จะเป็นผู้กำหนดว่าจะทำอย่างไรกับเลเยอร์เหล่านั้น (เช่น รันไทม์อาจเลือกที่จะทิ้งเลเยอร์เหล่านั้น)

recommendedImageExtent มีไว้สำหรับเลเยอร์ที่จะอัปเดตตามตำแหน่งคอนเทนเนอร์หรือมุมมองของผู้ใช้โดยเฉพาะ เมื่ออัปเดตเลเยอร์ด้วยเนื้อหาที่ขึ้นอยู่กับตำแหน่งของคอนเทนเนอร์เชิงพื้นที่หรือมุมมองของผู้ใช้ (เช่น เนื้อหา 3 มิติทั่วไป) แอปควรแสดงผลไปยังวิวพอร์ตที่เล็กลงนี้แทนขนาดมุมมองที่แนะนำโดยค่าเริ่มต้น เมื่ออัปเดตเลเยอร์ด้วยเนื้อหาที่ไม่ได้ขึ้นอยู่กับตำแหน่งของคอนเทนเนอร์เชิงพื้นที่หรือมุมมองของผู้ใช้ (เช่น เลเยอร์สี่เหลี่ยมจัตุรัสแบบคงที่) แอปอาจละเว้นค่าเหล่านี้ได้อย่างปลอดภัย สำหรับเลเยอร์ที่ขึ้นอยู่กับมุมมอง recommendedImageExtent คือคำแนะนำสำหรับแอปจากรันไทม์ที่มีไว้เพื่อลดการเกิดภาพซ้อนและปรับปรุงประสิทธิภาพการแสดงผล แอปสามารถส่งภาพที่มีความละเอียดเต็มได้หากต้องการ

XrExtent2Di :: width และ XrExtent2Di :: height ของ recommendedImageExtent ต้องเป็นจำนวนเต็มบวกที่น้อยกว่าหรือเท่ากับ XrViewConfigurationView :: recommendedImageRectWidth และ XrViewConfigurationView :: recommendedImageRectHeight ของ XrViewConfigurationView สำหรับการกำหนดค่ามุมมองหลักของคอนเทนเนอร์เชิงมิติพื้นที่เสมอ แอปไม่ควรสร้าง Swapchain ใหม่เพียงเพราะ recommendedImageExtent มีการเปลี่ยนแปลง เนื่องจากเป็นคำแนะนำแบบไดนามิกสำหรับแอปที่ระบุ XrSwapchainSubImage :: imageRect เพื่อใช้ใน XrSwapchainSubImage ของเลเยอร์องค์ประกอบความละเอียดเต็มที่ส่ง และสามารถเปลี่ยนทุกเฟรมได้

การใช้งานที่ถูกต้อง (โดยนัย)

ดูพื้นที่อ้างอิง

พื้นที่อ้างอิงมุมมองจะยังคงเหมือนเดิมเนื่องจากอยู่ในแกนหลักของ OpenXR เช่นเดียวกับใน Core, ไม่ได้มีไว้สำหรับการใช้งานการแสดงผล

การส่งเลเยอร์ผ่าน xrEndFrame

ในการแสดงผลคอนเทนเนอร์เชิงพื้นที่ แอปต้องระบุรายการเลเยอร์ที่เชื่อมโยงกับคอนเทนเนอร์เชิงพื้นที่ที่เกี่ยวข้องให้กับ xrEndFrame ซึ่งทำได้ผ่านโครงสร้าง XrSpatialContainerLayerFrameEndInfoEXT

typedef struct XrSpatialContainerLayerFrameEndInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             containerLayerCount;
    const XrSpatialContainerLayerEXT*    containerLayers;
} XrSpatialContainerLayerFrameEndInfoEXT;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • containerLayerCount คือจำนวนองค์ประกอบในอาร์เรย์ containerLayers
  • containerLayers เป็นตัวชี้ไปยังอาร์เรย์ของโครงสร้าง XrSpatialContainerLayerEXT

อาร์เรย์ containerLayers มี XrSpatialContainerLayerEXT สำหรับคอนเทนเนอร์เชิงพื้นที่แต่ละรายการในชุดการแสดงผลที่ใช้งานอยู่ (คอนเทนเนอร์ที่จัดการต่อเซสชันโดย xrBeginSpatialContainerRenderingEXT และ xrEndSpatialContainerRenderingEXT) XrSpatialContainerLayerEXT แต่ละรายการมีรายการพอยน์เตอร์ XrCompositionLayerBaseHeader ที่เชื่อมโยงกับคอนเทนเนอร์เชิงพื้นที่ที่ระบุ รันไทม์อาจจัดองค์ประกอบคอนเทนเนอร์ตามลำดับที่เลือก โดยไม่ขึ้นอยู่กับลำดับของ containerLayers ตัวอย่างเช่น รันไทม์อาจรวมคอนเทนเนอร์ตามความลึกที่สัมพันธ์กับผู้ใช้ มีคอนเทนเนอร์เชิงพื้นที่ทำหน้าที่เป็นเลเยอร์พื้นหลัง หรือ "ปักหมุด" คอนเทนเนอร์เชิงพื้นที่ให้อยู่ด้านบนเสมอไม่ว่าจะมีความลึกเท่าใดก็ตาม รันไทม์อาจรวมเลเยอร์โดยใช้กลยุทธ์ที่แตกต่างกันสำหรับคอนเทนเนอร์เชิงพื้นที่ในโหมดที่มีขอบเขตหรือโหมดใหญ่พิเศษ ตัวอย่างเช่น รันไทม์อาจจัดองค์ประกอบเลเยอร์องค์ประกอบของคอนเทนเนอร์เชิงพื้นที่ที่มีขอบเขตแต่ละรายการไว้ล่วงหน้าเป็นเลเยอร์สเตอริโอควอดเดียวที่รวมกับคอนเทนเนอร์อื่นๆ ทั้งหมดในขั้นตอนการจัดองค์ประกอบที่ 2

XrFrameEndInfo :: displayTime และ XrFrameEndInfo :: environmentBlendMode จะใช้กับคอนเทนเนอร์เชิงพื้นที่ทั้งหมดที่ระบุใน XrSpatialContainerLayerFrameEndInfoEXT

เมื่อส่งโครงสร้างนี้ไปยัง xrEndFrame โดยเชื่อมโยงกับ XrFrameEndInfo ระบบจะเพิ่มกรณีข้อผิดพลาดเพิ่มเติมต่อไปนี้ตามชุดการแสดงผลที่ใช้งานอยู่

  • หากคอนเทนเนอร์เชิงพื้นที่ได้รับการอ้างอิงโดยองค์ประกอบมากกว่า 1 รายการของ containerLayers รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CONTAINER_DUPLICATE_EXT
  • หากคอนเทนเนอร์เชิงพื้นที่ในชุดการแสดงผลที่ใช้งานอยู่ไม่มีการอ้างอิงโดยองค์ประกอบของ containerLayers รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT
  • หากคอนเทนเนอร์เชิงพื้นที่ที่ containerLayers อ้างอิงไม่ได้เป็นสมาชิกของชุดการแสดงผลที่ใช้งานอยู่ รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT

นอกจากนี้ หากมีคอนเทนเนอร์เชิงพื้นที่ในชุดการแสดงผลที่ใช้งานอยู่และโครงสร้างนี้ไม่ได้เชื่อมโยงกับ XrFrameEndInfo รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT

ในกรณีที่เกิดข้อผิดพลาดข้างต้น รันไทม์ต้องไม่แสดงผลเนื้อหาใดๆ สำหรับคอนเทนเนอร์เชิงพื้นที่

หากไม่มีคอนเทนเนอร์เชิงพื้นที่อยู่ในชุดการแสดงผลที่ใช้งานอยู่ แอปจะเรียกใช้ xrEndFrame ได้ตราบใดที่ไม่ได้ส่งเลเยอร์องค์ประกอบใดๆ

โปรดทราบว่าคุณอาจส่ง Swapchain แต่ละรายการสำหรับคอนเทนเนอร์หลายรายการผ่านเลเยอร์ในโครงสร้างที่ถูกต้องได้ เช่น เลเยอร์สี่เหลี่ยมที่แสดงผลผ่าน Swapchain รายการเดียวที่ส่งไปยังคอนเทนเนอร์เชิงพื้นที่หลายรายการ กรณีนี้จะได้รับการจัดการในลักษณะเดียวกับการแสดงผลอื่นๆ กล่าวคือ รันไทม์ต้องแสดงผล Quad ในคอนเทนเนอร์เชิงพื้นที่ทั้งหมดดังกล่าว

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_container_self_rendering ก่อนใช้ XrSpatialContainerLayerFrameEndInfoEXT
  • type ต้องเป็น XR_TYPE_SPATIAL_CONTAINER_LAYER_FRAME_END_INFO_EXT
  • next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • containerLayers ต้องเป็นตัวชี้ไปยังอาร์เรย์ของโครงสร้าง XrSpatialContainerLayerEXT ที่ถูกต้อง containerLayerCount รายการ
  • พารามิเตอร์ containerLayerCount ต้องมากกว่า 0

โครงสร้าง XrSpatialContainerLayerEXT จะจัดกลุ่มเลเยอร์องค์ประกอบมาตรฐานและเชื่อมโยงกับคอนเทนเนอร์เชิงพื้นที่ที่เฉพาะเจาะจง

typedef struct XrSpatialContainerLayerEXT {
    XrStructureType                               type;
    const void*                                   next;
    XrSpatialContainerEXT                         spatialContainer;
    XrBool32                                      retainPreviousSubmission;
    uint32_t                                      layerCount;
    const XrCompositionLayerBaseHeader* const*    layers;
} XrSpatialContainerLayerEXT;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • spatialContainer คือ XrSpatialContainerEXT ที่ระบุคอนเทนเนอร์เป้าหมาย
  • retainPreviousSubmission เป็นXrBool32 หากเป็น XR_TRUE รันไทม์จะเก็บเฟรมที่ส่งล่าสุดสำหรับคอนเทนเนอร์เชิงพื้นที่นี้ไว้
  • layerCount คือจำนวนเลเยอร์องค์ประกอบในอาร์เรย์ layers
  • layers เป็นตัวชี้ไปยังอาร์เรย์ของตัวชี้ XrCompositionLayerBaseHeader

เมื่อ retainPreviousSubmission เป็น XR_TRUE รันไทม์ต้องนำเลเยอร์องค์ประกอบและเนื้อหารูปภาพ Swapchain มาใช้ซ้ำตามที่ล็อกไว้ระหว่างการเรียก xrEndFrame ครั้งล่าสุดที่ retainPreviousSubmission เป็น XR_FALSE การแก้ไข Swapchain ที่ใช้โดยเลเยอร์ที่เก็บไว้ ต้องไม่แสดงในเอาต์พุตที่แสดงผล

สำหรับเลเยอร์ที่ส่งสำหรับคอนเทนเนอร์เชิงพื้นที่แต่ละรายการ (การแสดงผลภายในคอนเทนเนอร์) รันไทม์ต้องเป็นไปตามกฎที่ระบุไว้แล้วสำหรับการจัดลำดับการจัดองค์ประกอบเลเยอร์ ซึ่งหมายความว่าเลเยอร์ภายในคอนเทนเนอร์ต้องวาดตามลำดับเดียวกับที่ระบุไว้ โดยประกอบผ่านอัลกอริทึมของ Painter

"การล้าง" คอนเทนเนอร์เชิงพื้นที่หมายถึงการนำเนื้อหาทั้งหมดออกจากคอนเทนเนอร์เชิงพื้นที่ ซึ่งส่งผลให้ไม่มีการแสดงผลใดๆ สำหรับคอนเทนเนอร์นั้นในเฟรมปัจจุบัน รันไทม์ต้องถือว่าค่านี้เทียบเท่ากับแอปที่ส่งสีดำโปร่งใส (บิตทั้งหมดเป็น 0) สำหรับทุกพิกเซลภายในคอนเทนเนอร์ "การคงไว้" คอนเทนเนอร์เชิงพื้นที่หมายถึงรันไทม์ที่แสดงชุดเลเยอร์ที่ส่งล่าสุดสำหรับคอนเทนเนอร์นั้นต่อไป

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

  • หากต้องการส่งเลเยอร์ใหม่ แอปจะระบุ layerCount ที่ไม่ใช่ 0 และพอยน์เตอร์ layers ที่ถูกต้อง
  • หากต้องการล้างคอนเทนเนอร์เชิงพื้นที่ layerCount สำหรับรายการนั้นต้องเป็น 0 และ retainPreviousSubmission ต้องเป็น XR_FALSE
  • หากต้องการเก็บเลเยอร์และรูปภาพ Swapchain ที่ส่งล่าสุดไว้ (การเก็บรักษา) layerCount สำหรับรายการต้องเป็น 0 และ retainPreviousSubmission ต้องเป็น XR_TRUE

การควบคุมต่อคอนเทนเนอร์ที่ชัดเจนนี้ช่วยให้มั่นใจได้ว่าระบบจะสื่อสาร Intent ของแอปอย่างชัดเจนในทุกเฟรม

หาก retainPreviousSubmission เป็น XR_TRUE และ layerCount ไม่ใช่ 0 รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE

หาก XrSpatialContainerCompositionLayerViewConfigurationEXT ไม่ได้เชื่อมโยงกับ XrCompositionLayerProjection ที่เป็นส่วนหนึ่งของคอนเทนเนอร์เชิงมิติพื้นที่ รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE โครงสร้างนี้ใช้ได้กับเลเยอร์ XrCompositionLayerProjection เท่านั้น หากเชื่อมโยงกับเลเยอร์ประเภทอื่นๆ (เช่น เลเยอร์สี่เหลี่ยมหรือทรงกระบอก) รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE

การใช้งานที่ถูกต้อง (โดยนัย)

การระบุการกำหนดค่ามุมมองสำหรับเลเยอร์การฉายภาพ

โครงสร้าง XrSpatialContainerCompositionLayerViewConfigurationEXT ใช้เพื่อระบุการกำหนดค่ามุมมองที่ใช้แสดงผลเลเยอร์การฉายภาพสำหรับคอนเทนเนอร์เชิงมิติพื้นที่

typedef struct XrSpatialContainerCompositionLayerViewConfigurationEXT {
    XrStructureType            type;
    const void*                next;
    XrViewConfigurationType    viewConfigurationType;
} XrSpatialContainerCompositionLayerViewConfigurationEXT;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • viewConfigurationType คือ XrViewConfigurationType ที่ใช้แสดงผล XrCompositionLayerProjection

เมื่อส่ง XrCompositionLayerProjection สำหรับคอนเทนเนอร์เชิงมิติพื้นที่ แอปต้องระบุการกำหนดค่ามุมมองที่ใช้แสดงผลเลเยอร์ ซึ่งจำเป็นเนื่องจากแอปสามารถเลือกแต่ละเฟรมได้ว่าจะแสดงผลด้วยการกำหนดค่ามุมมองหลักของคอนเทนเนอร์เชิงพื้นที่หรือการกำหนดค่ามุมมองที่ลดลงที่รันไทม์แนะนำ (หากมี)

เมื่อเชื่อมโยง XrSpatialContainerCompositionLayerViewConfigurationEXT แล้ว แอปต้องตรวจสอบว่า XrCompositionLayerProjection :: viewCount เป็นจำนวนมุมมองที่ถูกต้องสำหรับ XrViewConfigurationType ที่ระบุในโครงสร้างที่เชื่อมโยง viewConfigurationType ที่ระบุในโครงสร้างแบบลูกโซ่ต้องเป็น XrSpatialContainerBeginInfoEXT :: primaryViewConfigurationType ที่ระบุเมื่อเริ่มคอนเทนเนอร์ หรือประเภทการกำหนดค่ามุมมองที่ลดลงซึ่งรันไทม์แสดงผลใน XrSpatialContainerViewStateEXT หรือค่าเพิ่มเติมที่เปิดใช้ผ่านส่วนขยาย

การใช้งานที่ถูกต้อง (โดยนัย)

ลักษณะการคลิปพิกเซล

แอปควรแจ้งรันไทม์ว่าแอปแสดงผลพิกเซลนอกขอบเขตของคอนเทนเนอร์เชิงพื้นที่หรือไม่โดยเชื่อมโยง XrSpatialContainerLayerVolumeClippingEXT เมื่อส่งเลเยอร์องค์ประกอบ

typedef struct XrSpatialContainerLayerVolumeClippingEXT {
    XrStructureType                        type;
    const void*                            next;
    XrSpatialContainerVolumeClippingEXT    volumeClipping;
} XrSpatialContainerLayerVolumeClippingEXT;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • volumeClipping คือ XrSpatialContainerVolumeClippingEXT ที่แอปใช้

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

สำหรับคอนเทนเนอร์เชิงพื้นที่ที่มีขอบเขตซึ่งใช้การแสดงผลด้วยตนเอง รันไทม์ต้องพิจารณาทั้งขอบเขตปริมาตร 3 มิติและขอบเขตพิกเซล 2 มิติ ขอบเขตปริมาตร 3 มิติจะแสดงผลจาก xrGetSpatialContainerBoundsEXT ขอบเขตพิกเซล 2 มิติคือการฉายภาพขอบเขตปริมาตร 3 มิติลงบนจอแสดงผลแต่ละจอสำหรับระบบ

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

รันไทม์อาจใช้ volumeClipping เพื่อปรับวิธีแสดงคอนเทนเนอร์เชิงพื้นที่หนึ่งๆ ตัวอย่างเช่น เมื่อตั้งค่าเป็น XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT รันไทม์อาจแสดงผลด้านหลังของขอบเขตปริมาตร 3 มิติ ซึ่งจะทำให้เกิดความขัดแย้งด้านความลึกหากคอนเทนเนอร์เชิงพื้นที่วาดพิกเซลด้านหลังขอบเขตปริมาตร 3 มิติของคอนเทนเนอร์

ส่วนขยายในอนาคตอาจอนุญาตให้ทำการคลิปตามขอบเขตปริมาตร 3 มิติหากมีการส่งข้อมูลความลึก

การใช้งานที่ถูกต้อง (โดยนัย)

คำสั่งใหม่

โครงสร้างใหม่

ค่าคงที่ Enum ใหม่

  • XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME
  • XR_EXT_spatial_container_self_rendering_SPEC_VERSION

  • การขยาย XrResult :

    • XR_ERROR_SPATIAL_CONTAINER_DUPLICATE_EXT
    • XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT

  • การขยาย XrSpatialContainerGraphicsPresentationEXT :

    • XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

  • การขยาย XrStructureType :

    • XR_TYPE_SPATIAL_CONTAINER_BEGIN_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_COMPOSITION_LAYER_VIEW_CONFIGURATION_EXT
    • XR_TYPE_SPATIAL_CONTAINER_END_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_LAYER_EXT
    • XR_TYPE_SPATIAL_CONTAINER_LAYER_FRAME_END_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_LAYER_VOLUME_CLIPPING_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VIEWS_LOCATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VIEW_LOCATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VIEW_STATE_EXT

ตัวอย่างโค้ด

// Example: Complete lifecycle, view location, and frame submission for spatial containers
PFN_xrBeginSpatialContainerRenderingEXT xrBeginSpatialContainerRenderingEXT; // previously initialized
PFN_xrEndSpatialContainerRenderingEXT xrEndSpatialContainerRenderingEXT; // previously initialized
PFN_xrLocateSpatialContainerViewsEXT xrLocateSpatialContainerViewsEXT; // previously initialized

XrSession session; // previously initialized

// We want to update this container
XrSpatialContainerEXT containerA; // previously initialized with XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT
XrSpace containerASpace; // previously initialized

// We want to retain this container
XrSpatialContainerEXT containerB; // previously initialized with XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT
XrSpace containerBSpace; // previously initialized

// 1. Add to active render set when the app is ready to start submitting layers
XrSpatialContainerBeginInfoEXT beginInfoA {
  .type = XR_TYPE_SPATIAL_CONTAINER_BEGIN_INFO_EXT,
  .spatialContainer = containerA,
  .primaryViewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
};
CHK_XR(xrBeginSpatialContainerRenderingEXT(session, &beginInfoA));

XrSpatialContainerBeginInfoEXT beginInfoB {
  .type = XR_TYPE_SPATIAL_CONTAINER_BEGIN_INFO_EXT,
  .spatialContainer = containerB,
  .primaryViewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
};
CHK_XR(xrBeginSpatialContainerRenderingEXT(session, &beginInfoB));

// ... Frame Loop ...


XrTime displayTime; // returned from xrWaitFrame

const std::vector<XrSpatialContainerEXT> containers = {containerA, containerB};
const std::vector<XrSpace> containerSpaces = {containerASpace, containerBSpace};
uint32_t containerCount = static_cast<uint32_t>(containers.size());

// 2. Setup individual locate info for each container
std::vector<XrSpatialContainerViewLocateInfoEXT> containerLocateInfos(containerCount, {
  .type = XR_TYPE_SPATIAL_CONTAINER_VIEW_LOCATE_INFO_EXT,
});

for (uint32_t i = 0; i < containerCount; ++i) {
    containerLocateInfos[i].viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO;
    containerLocateInfos[i].space = containerSpaces[i]; // Recommended to use container's own space
    containerLocateInfos[i].spatialContainer = containers[i];
}

// Setup bulk locate info
XrSpatialContainerViewsLocateInfoEXT locateInfo {
  .type = XR_TYPE_SPATIAL_CONTAINER_VIEWS_LOCATE_INFO_EXT,
  .displayTime = displayTime,
  .viewLocateInfoCount = containerCount,
  .viewLocateInfos = containerLocateInfos.data(),
};

// Prepare states to be populated by the runtime
std::vector<XrSpatialContainerViewStateEXT> viewStates(containerCount, {
  .type = XR_TYPE_SPATIAL_CONTAINER_VIEW_STATE_EXT,
});

// Call the dedicated locate views function
// We know the required view count is 2 per container for STEREO
const uint32_t viewsPerConfig = 2;
uint32_t totalViewCount = containerCount * viewsPerConfig;
std::vector<XrView> views(totalViewCount, {.type = XR_TYPE_VIEW});

CHK_XR(xrLocateSpatialContainerViewsEXT(session, &locateInfo, containerCount, viewStates.data(), totalViewCount, views.data()));

// Process results
for (uint32_t i = 0; i < containerCount; ++i) {
    XrBool32 shouldSubmitLayers = viewStates[i].shouldSubmitLayers;
    XrExtent2Di recommendedImageExtent = viewStates[i].recommendedImageExtent;
    XrViewConfigurationType viewConfigurationType = viewStates[i].viewConfigurationType;
    bool isDecayedToMono = (viewConfigurationType == XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO);
    if (shouldSubmitLayers) {
        // App is expected to also verify viewStates[i].viewStateFlags has valid orientation/position bits before rendering
        XrView& leftView = views[i * viewsPerConfig];
        XrView& rightView = views[i * viewsPerConfig + 1];
        // If isDecayedToMono is true, left and right will be identical.
    } else {
        // Skip layer submission but retain previous submission when calling
        // xrEndFrame.
    }
}

// 3. Setup projection layer for container A
XrCompositionLayerProjection projectionLayer = {.type = XR_TYPE_COMPOSITION_LAYER_PROJECTION};
// ... standard projection layer setup (space, viewCount, views, etc.) ...

// Specify which view configuration was used to render this specific layer
XrSpatialContainerCompositionLayerViewConfigurationEXT containerViewConfig {
  .type = XR_TYPE_SPATIAL_CONTAINER_COMPOSITION_LAYER_VIEW_CONFIGURATION_EXT,
  // Even if the runtime decayed to MONO, we indicate what we actually rendered
  .viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
};

// Chain it to the projection layer
projectionLayer.next = &containerViewConfig;
const XrCompositionLayerBaseHeader* layersA[1] = {reinterpret_cast<const XrCompositionLayerBaseHeader*>(&projectionLayer)};

// Note: In a real app, you are required to submit ALL active containers in the render set.

XrSpatialContainerLayerVolumeClippingEXT containerClippingA = {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_VOLUME_CLIPPING_EXT,
  // Set volumeClipping appropriately for the rendering done.
  .volumeClipping = XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT,
};

// Setup container A (Update with new pixels)
XrSpatialContainerLayerEXT containerLayerA {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_EXT,
  .next = &containerClippingA,
  .spatialContainer = containerA,
  .retainPreviousSubmission = XR_FALSE,
  .layerCount = 1,
  .layers = layersA,
};

XrSpatialContainerLayerVolumeClippingEXT containerClippingB {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_VOLUME_CLIPPING_EXT,
  // Set volumeClipping appropriately for the rendering done.
  .volumeClipping = XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT,
};

// Setup container B (Explicitly retain previous frame)
XrSpatialContainerLayerEXT containerLayerB {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_EXT,
  .next = &containerClippingB,
  .spatialContainer = containerB,
  .retainPreviousSubmission = XR_TRUE,
  .layerCount = 0, // Required to be 0 when retaining
  .layers = nullptr,
};

// Aggregate all container layers
XrSpatialContainerLayerEXT containerLayers[] = { containerLayerA, containerLayerB };

XrSpatialContainerLayerFrameEndInfoEXT spatialEndInfo {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_FRAME_END_INFO_EXT,
  .containerLayerCount = 2, // Must equal the number of active containers
  .containerLayers = containerLayers,
};

XrFrameEndInfo frameEndInfo {
  .type = XR_TYPE_FRAME_END_INFO,
  .next = &spatialEndInfo,
  .displayTime = displayTime,
  .environmentBlendMode = XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND,
  .layerCount = 0, // MANDATORY: Must be 0 for self rendering extension
};

CHK_XR(xrEndFrame(session, &frameEndInfo));

// ... End Frame Loop ...

// 4. Remove from active render set when the container is destroyed or no longer needs rendering
XrSpatialContainerEndInfoEXT endInfoA {
  .type = XR_TYPE_SPATIAL_CONTAINER_END_INFO_EXT,
  .spatialContainer = containerA,
};
CHK_XR(xrEndSpatialContainerRenderingEXT(session, &endInfoA));

XrSpatialContainerEndInfoEXT endInfoB {
  .type = XR_TYPE_SPATIAL_CONTAINER_END_INFO_EXT,
  .spatialContainer = containerB,
};
CHK_XR(xrEndSpatialContainerRenderingEXT(session, &endInfoB));

ประวัติเวอร์ชัน

  • การแก้ไข 1, 06-08-2026 (Lachlan Ford)

    • คำอธิบายส่วนขยายเริ่มต้น