Android XR for OpenXR | Android Developers

Android XR SDK มาถึงเวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ 4 แล้ว และเราต้องการความคิดเห็นของคุณ ลองใช้ฟีเจอร์ต่างๆ และไปที่หน้าการสนับสนุนเพื่อติดต่อเรา

Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

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

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

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

741

การแก้ไข

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

อนุมัติ

การขึ้นต่อกันของส่วนขยายและเวอร์ชัน

XR_EXT_future

ผู้เขียน

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Karthik Kadappan, Magic Leap
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

ภาพรวม

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

ส่วนสำคัญของส่วนขยายนี้มีดังนี้

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

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

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

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

เอนทิตีเชิงพื้นที่

เอนทิตีเชิงพื้นที่คือเอนทิตีที่อยู่ในพื้นที่หนึ่งๆ ซึ่งมีข้อมูลที่เชื่อมโยงต่างๆ ที่จัดระเบียบเป็นคอมโพเนนต์ โดยอาจเป็นอย่างใดอย่างหนึ่งต่อไปนี้

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

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

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

เอนทิตีเชิงพื้นที่แสดงด้วยแฮนเดิล XrSpatialEntityIdEXT หรือ XrSpatialEntityEXT ซึ่งมีรายละเอียดอยู่ในส่วนการแสดงเอนทิตีเชิงพื้นที่

ประเภทคอมโพเนนต์เชิงพื้นที่

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

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

การแจงนับ XrSpatialComponentTypeEXT จะระบุประเภทต่างๆ ของคอมโพเนนต์ที่รันไทม์อาจรองรับ

ส่วนประกอบบางประเภทที่แสดงไว้ไม่ได้มาจากส่วนขยายนี้เพียงอย่างเดียว แต่บางประเภทต้องเปิดใช้ส่วนขยายเพิ่มเติมเมื่อสร้างอินสแตนซ์ตามที่ระบุไว้ในเอกสาร

ตัวแจงนับมีค่าดังนี้

คำอธิบาย Enum

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

คอมโพเนนต์ที่ระบุขอบเขต 2 มิติสำหรับเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentBounded2DListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialBounded2DDataEXT

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

คอมโพเนนต์ที่ระบุขอบเขต 3 มิติสำหรับเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentBounded3DListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrBoxf

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

คอมโพเนนต์ที่ให้ XrSpatialEntityIdEXT ขององค์ประกอบหลักสำหรับเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentParentListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

คอมโพเนนต์ที่ให้ตาข่าย 3 มิติสำหรับเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentMesh3DListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialMeshDataEXT

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

คอมโพเนนต์ที่ระบุการแจงนับการจัดแนวระนาบสำหรับเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentPlaneAlignmentListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialPlaneAlignmentEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

คอมโพเนนต์ที่ให้ตาข่าย 2 มิติสำหรับเอนทิตีเชิงพื้นที่ โครงสร้างลิสต์ที่เกี่ยวข้องคือ XrSpatialComponentMesh2DListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialMeshDataEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

คอมโพเนนต์ที่ให้รูปหลายเหลี่ยมขอบเขต 2 มิติสำหรับเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentPolygon2DListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialPolygon2DDataEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

คอมโพเนนต์ที่ระบุป้ายกำกับเชิงความหมายสำหรับระนาบ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentPlaneSemanticLabelListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialPlaneSemanticLabelEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

คอมโพเนนต์ที่อธิบายประเภท เครื่องหมาย รหัส และตำแหน่ง โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentMarkerListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialMarkerDataEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_marker_tracking)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

คอมโพเนนต์ที่ระบุป้ายกำกับเชิงความหมายสำหรับฉาก โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentObjectSemanticLabelListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialObjectSemanticLabelEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

คอมโพเนนต์ที่ระบุป้ายกำกับเชิงความหมายสำหรับคีย์บอร์ด โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentKeyboardSemanticLabelListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialKeyboardSemanticLabelEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

คอมโพเนนต์ที่ระบุป้ายกำกับเชิงความหมายสำหรับเมาส์ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentMouseSemanticLabelListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialMouseSemanticLabelEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

คอมโพเนนต์ที่ระบุตำแหน่งสำหรับ Anchor โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentAnchorListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrPosef (เพิ่มโดยส่วนขยาย XR_EXT_spatial_anchor)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

คอมโพเนนต์ที่ให้ UUID ที่คงอยู่สำหรับเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentPersistenceListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialPersistenceDataEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_persistence)

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

คอมโพเนนต์ที่อธิบายประเภทรูปภาพระนาบ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentImage2DListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialImageSizeEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_image_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

คอมโพเนนต์ที่ให้ค่าปกติสำหรับตาข่าย 3 มิติของเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentMesh3DNormalsListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialBufferEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

คอมโพเนนต์ที่ระบุป้ายกำกับเชิงความหมายต่อจุดยอดสำหรับตาข่าย 3 มิติของเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentMesh3DVertexSemanticLabelsListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialBufferEXT ข้อมูลภายในบัฟเฟอร์จะแมปกับ XrSpatialMeshSemanticLabelEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

คอมโพเนนต์ที่ให้ป้ายกำกับเชิงความหมายต่อใบหน้าสามเหลี่ยมสำหรับตาข่าย 3 มิติของเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialBufferEXT ข้อมูลภายในบัฟเฟอร์จะแมปกับ XrSpatialMeshSemanticLabelEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

คอมโพเนนต์ที่ระบุป้ายกำกับเชิงความหมายสำหรับออบเจ็กต์ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentObjectSemanticLabelListANDROID โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialObjectSemanticLabelANDROID (เพิ่มโดยส่วนขยาย XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

คอมโพเนนต์ที่ให้ท่าทางของการตรวจหาด้วยรังสีที่กระทบกับเอนทิตี โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentRaycastResultListANDROID โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialRaycastResultDataANDROID (เพิ่มโดยส่วนขยาย XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

คอมโพเนนต์ที่ระบุรหัสเอนทิตีของเอนทิตีที่ครอบคลุมเอนทิตีที่แนบมา โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentSubsumedByListANDROID โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialEntityIdEXT (เพิ่มโดยส่วนขยาย XR_ANDROID_spatial_component_subsumed_by)

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

คอมโพเนนต์ที่ระบุขนาดและประเภทห้องของกล่องรองเท้า โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentRoomListANDROIDSYS โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialRoomDataANDROIDSYS (เพิ่มโดยส่วนขยาย XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

คอมโพเนนต์ที่ระบุประเภทวัสดุของพื้นผิวขอบเขต โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentMaterialTypeListANDROIDSYS โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialMaterialTypeANDROIDSYS (เพิ่มโดยส่วนขยาย XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

คอมโพเนนต์ที่ให้ความเชื่อมั่นของวัตถุที่ติดตามได้ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentConfidenceListANDROIDSYS โครงสร้างข้อมูลที่เกี่ยวข้องคือ float (เพิ่มโดยส่วนขยาย XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

คอมโพเนนต์ที่ระบุว่าห้องว่างหรือไม่ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentRoomEmptinessListANDROIDSYS โครงสร้างข้อมูลที่เกี่ยวข้องคือ float (เพิ่มโดยส่วนขยาย XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

คอมโพเนนต์ที่ให้ข้อมูลของตารางการครอบครองในเอนทิตีที่แนบ โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentOccupancyGridListANDROIDX1 โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialOccupancyGridDataANDROIDX1 (เพิ่มโดยส่วนขยาย XR_ANDROIDX1_spatial_occupancy_grid)

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

คอมโพเนนต์ที่อธิบายคำอธิบายประกอบสี่เหลี่ยม โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentAnnotationQuadListANDROID โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialAnnotationQuadDataANDROID (เพิ่มโดยส่วนขยาย XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

คอมโพเนนต์ที่ให้ข้อมูลเมตาสำหรับรูปทรงเรขาคณิตของภาพถนน โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialStreetscapeGeometryMetadataANDROIDX2 (เพิ่มโดยส่วนขยาย XR_ANDROIDX2_geospatial_streetscape)

ความสามารถและการตั้งค่าเชิงพื้นที่

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

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

การแจงนับ XrSpatialCapabilityEXT จะระบุความสามารถประเภทต่างๆ ที่รันไทม์อาจรองรับ

ตัวแจงนับมีค่าดังนี้

คำอธิบาย Enum

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

การติดตามเครื่องบิน (เพิ่มโดยส่วนขยาย XR_EXT_spatial_plane_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

ความสามารถในการตรวจหาและติดตามคิวอาร์โค้ด (เพิ่มโดยส่วนขยาย XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

ความสามารถในการตรวจหาและติดตามคิวอาร์โค้ดขนาดเล็ก (เพิ่มโดยส่วนขยาย XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

ความสามารถในการตรวจหาและติดตามเครื่องหมาย Aruco (เพิ่มโดยส่วนขยาย XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

ความสามารถในการตรวจหาและติดตาม AprilTag (เพิ่มโดยส่วนขยาย XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

การติดตามออบเจ็กต์ (เพิ่มโดยส่วนขยาย XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

ความสามารถในการสร้าง Spatial Anchor (เพิ่มโดยส่วนขยาย XR_EXT_spatial_anchor)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

ความสามารถในการตรวจจับและติดตามรูปภาพอ้างอิงระนาบ (เพิ่มโดยส่วนขยาย XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

ความสามารถในการติดตามตาข่ายของสภาพแวดล้อม (เพิ่มโดยส่วนขยาย XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

การติดตามออบเจ็กต์ (เพิ่มโดยส่วนขยาย XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Raycast เทียบกับบัฟเฟอร์ความลึก (เพิ่มโดยส่วนขยาย XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

ความสามารถในการติดตามห้องแชท (เพิ่มโดยส่วนขยาย XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

ความสามารถในการติดตามขอบเขตของห้อง (เพิ่มโดยส่วนขยาย XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

การติดตามคำอธิบายประกอบ (เพิ่มโดยส่วนขยาย XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

รูปทรงของสตรีทสเคป (เพิ่มโดยส่วนขยาย XR_ANDROIDX2_geospatial_streetscape)

ฟังก์ชัน xrEnumerateSpatialCapabilitiesEXT มีคำจำกัดความดังนี้

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

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

instance เป็นแฮนเดิลของ XrInstance
systemId คือ XrSystemId ที่จะมีการแจงนับความสามารถเชิงพื้นที่
capabilityCapacityInput คือความจุของอาร์เรย์ capabilities หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
capabilityCountOutput คือจำนวนความสามารถ หรือความจุที่จำเป็นในกรณีที่ capabilityCapacityInput ไม่เพียงพอ
capabilities คืออาร์เรย์ของ XrSpatialCapabilityEXT ทำได้หาก capabilityCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด capabilities ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถแสดงรายการความสามารถเชิงพื้นที่ที่ XrSystemId รองรับโดยใช้ xrEnumerateSpatialCapabilitiesEXT

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

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrEnumerateSpatialCapabilitiesEXT
instance ต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง
capabilityCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
หาก capabilityCapacityInput ไม่ใช่ 0 , capabilities ต้องเป็นตัวชี้ไปยังอาร์เรย์ของค่า capabilityCapacityInput XrSpatialCapabilityEXT

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

สำเร็จ

XR_SUCCESS

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SYSTEM_INVALID
XR_ERROR_VALIDATION_FAILURE

ฟังก์ชัน xrEnumerateSpatialCapabilityComponentTypesEXT มีการกำหนดไว้ดังนี้

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

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

instance เป็นแฮนเดิลของ XrInstance
systemId คือ XrSystemId ที่จะมีการแจงนับคอมโพเนนต์ความสามารถเชิงพื้นที่
capability คือ XrSpatialCapabilityEXT ที่จะมีการแจงนับคอมโพเนนต์
capabilityComponents เป็นตัวชี้ไปยัง XrSpatialCapabilityComponentTypesEXT ซึ่งเป็นโครงสร้างอินพุต/เอาต์พุตที่อาร์เรย์ที่แอปพลิเคชันจัดสรรจะได้รับการป้อนข้อมูล

ฟังก์ชันนี้จะแสดงประเภทคอมโพเนนต์ที่ความสามารถที่ระบุมีให้ในเอนทิตีในระบบตามที่กำหนดค่าไว้

แอปพลิเคชันสามารถใช้ประเภทคอมโพเนนต์ที่แสดงใน XrSpatialCapabilityComponentTypesEXT :: componentTypes เพื่อทำความเข้าใจชุดคอมโพเนนต์ทั้งหมดที่ systemId รองรับสำหรับ capability และสามารถใช้รายการนี้เพื่อพิจารณาว่าการกำหนดค่าที่ถูกต้องสำหรับ capability คืออะไรเมื่อสร้าง XrSpatialContextEXT สำหรับ capability

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT หาก capability ไม่ได้ระบุโดย xrEnumerateSpatialCapabilitiesEXT

รันไทม์ต้องไม่แจงนับประเภทคอมโพเนนต์เชิงพื้นที่ที่ไม่ได้เปิดใช้ส่วนขยายสำหรับ instance

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrEnumerateSpatialCapabilityComponentTypesEXT
instance ต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง
capability ต้องเป็นค่า XrSpatialCapabilityEXT ที่ถูกต้อง
capabilityComponents ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialCapabilityComponentTypesEXT

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

สำเร็จ

XR_SUCCESS

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
XR_ERROR_SYSTEM_INVALID
XR_ERROR_VALIDATION_FAILURE

โครงสร้าง XrSpatialCapabilityComponentTypesEXT มีการกำหนดไว้ดังนี้

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
componentTypeCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
componentTypeCountOutput คือจำนวนประเภทคอมโพเนนต์ หรือความจุที่จำเป็นในกรณีที่ componentTypeCapacityInput ไม่เพียงพอ
componentTypes คืออาร์เรย์ของ XrSpatialComponentTypeEXT ทำได้หาก componentTypeCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด componentTypes ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialCapabilityComponentTypesEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
หาก componentTypeCapacityInput ไม่ใช่ 0 componentTypes ต้องเป็น Pointer ไปยังอาร์เรย์ของค่า componentTypeCapacityInput XrSpatialComponentTypeEXT

ฟีเจอร์ความสามารถเชิงพื้นที่

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

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

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

ฟีเจอร์ดังกล่าวแสดงโดย XrSpatialCapabilityFeatureEXT และแอปพลิเคชันจะแสดงรายการฟีเจอร์โดยใช้ xrEnumerateSpatialCapabilityFeaturesEXT

ฟีเจอร์ความสามารถแต่ละรายการจะมีโครงสร้างการกำหนดค่าที่สอดคล้องกันเพื่อเปิดใช้ โครงสร้างการกำหนดค่าดังกล่าวต้องเชื่อมโยงกับ XrSpatialCapabilityConfigurationBaseHeaderEXT :: next ของความสามารถที่เกี่ยวข้อง

ตัวแจงนับมีค่าดังนี้

คำอธิบาย Enum

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

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

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

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

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

ฟีเจอร์เชิงพื้นที่ที่ช่วยให้แอปพลิเคชันระบุชุดย่อยของป้ายกำกับจาก XrSpatialObjectSemanticLabelEXT เพื่อให้รันไทม์ติดตามได้ โครงสร้างการกำหนดค่าที่เกี่ยวข้องคือ XrSpatialFeatureObjectSemanticLabelSubsetEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

รันไทม์รองรับตัวกรอง XrSpatialBoundsSpherefANDROID สำหรับ XrSpatialDiscoverySnapshotCreateInfoEXT ซึ่งไม่จำเป็นต้องรวมโครงสร้างการกำหนดค่าใดๆ ในระหว่างการสร้างบริบทเชิงพื้นที่ (เพิ่มโดยส่วนขยาย XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

รันไทม์รองรับตัวกรอง XrSpatialBoundsBoxfANDROID สำหรับ XrSpatialDiscoverySnapshotCreateInfoEXT ซึ่งไม่จำเป็นต้องรวมโครงสร้างการกำหนดค่าใดๆ ในระหว่างการสร้างบริบทเชิงพื้นที่ (เพิ่มโดยส่วนขยาย XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

รันไทม์รองรับตัวกรอง XrSpatialBoundsFrustumfANDROID สำหรับ XrSpatialDiscoverySnapshotCreateInfoEXT ซึ่งไม่จำเป็นต้องรวมโครงสร้างการกำหนดค่าใดๆ ในระหว่างการสร้างบริบทเชิงพื้นที่ (เพิ่มโดยส่วนขยาย XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

รันไทม์รองรับการอนุมานขนาดจริงของรูปภาพที่ตรวจพบและติดตามโดยอัตโนมัติ โครงสร้างการกำหนดค่าที่เกี่ยวข้องคือ XrSpatialImageSizeEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

รันไทม์รองรับ XrSpatialImageStaticOptimizationEXT โครงสร้างการกำหนดค่าที่เกี่ยวข้องคือ XrSpatialImageStaticOptimizationEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

รันไทม์รองรับ XrSpatialImageSizeEXT โครงสร้างการกำหนดค่าที่เกี่ยวข้องคือ XrSpatialImageSizeEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

ฟีเจอร์ความสามารถในการติดตามตาข่ายที่กันน้ำของสภาพแวดล้อม โครงสร้างการกำหนดค่าที่เกี่ยวข้องคือ XrSpatialFeatureTrackWatertightMeshEXT (เพิ่มโดยส่วนขยาย XR_EXT_spatial_mesh_tracking)

ฟังก์ชัน xrEnumerateSpatialCapabilityFeaturesEXT มีคำจำกัดความดังนี้

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

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

instance เป็นแฮนเดิลของ XrInstance
systemId คือ XrSystemId ที่จะแสดงรายการฟีเจอร์ความสามารถเชิงพื้นที่
capability คือ XrSpatialCapabilityEXT ที่จะมีการแจงนับฟีเจอร์
capabilityFeatureCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
capabilityFeatureCountOutput คือจำนวนฟีเจอร์หรือความจุที่จำเป็นในกรณีที่ capabilityFeatureCapacityInput ไม่เพียงพอ
capabilityFeatures คืออาร์เรย์ของ XrSpatialCapabilityFeatureEXT ทำได้หาก capabilityFeatureCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด capabilityFeatures ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันจะค้นหาฟีเจอร์ที่ระบบรองรับสำหรับ XrSpatialCapabilityEXT โดยใช้ xrEnumerateSpatialCapabilityFeaturesEXT

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

หาก capability ไม่ใช่ความสามารถที่ระบุโดย xrEnumerateSpatialCapabilitiesEXT รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT

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

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrEnumerateSpatialCapabilityFeaturesEXT
instance ต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง
capability ต้องเป็นค่า XrSpatialCapabilityEXT ที่ถูกต้อง
capabilityFeatureCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
หาก capabilityFeatureCapacityInput ไม่ใช่ 0 , capabilityFeatures ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า capabilityFeatureCapacityInput XrSpatialCapabilityFeatureEXT

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

สำเร็จ

XR_SUCCESS

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
XR_ERROR_SYSTEM_INVALID
XR_ERROR_VALIDATION_FAILURE

บริบทเชิงพื้นที่

สร้างบริบทเชิงพื้นที่

XR_DEFINE_HANDLE(XrSpatialContextEXT)

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

ฟังก์ชัน xrCreateSpatialContextAsyncEXT มีคำจำกัดความดังนี้

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

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

session คือ XrSession ที่บริบทเชิงพื้นที่จะทำงานอยู่
createInfo คือ XrSpatialContextCreateInfoEXT ที่ใช้เพื่อระบุพารามิเตอร์บริบทเชิงพื้นที่
future เป็น Pointer ไปยัง XrFutureEXT

แอปพลิเคชันสร้างแฮนเดิล XrSpatialContextEXT ได้โดยทำดังนี้

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

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT หาก XrSpatialContextCreateInfoEXT ::capabilityConfigCount เป็น 0 แฮนเดิลบริบทเชิงพื้นที่ต้องมีความสามารถอย่างน้อย 1 อย่าง

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT หาก xrEnumerateSpatialCapabilitiesEXT ไม่ได้แจงนับความสามารถใดๆ ในอาร์เรย์ XrSpatialContextCreateInfoEXT :: capabilityConfigs

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT หาก XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount ใน XrSpatialContextCreateInfoEXT :: capabilityConfigs เป็น 0 การกำหนดค่าความสามารถจะไม่สมบูรณ์หากไม่มีรายการประเภทคอมโพเนนต์ที่จะเปิดใช้สำหรับความสามารถนั้น

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT หากไม่ได้แจงนับประเภทคอมโพเนนต์ใดก็ตามที่ระบุไว้ใน XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents สำหรับ XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability ใน xrEnumerateSpatialCapabilityComponentTypesEXT

หากโครงสร้างใดๆ ในเชนถัดไปของ XrSpatialContextCreateInfoEXT :: capabilityConfigs สอดคล้องกับ XrSpatialCapabilityFeatureEXT ที่ไม่ได้แจงนับสำหรับความสามารถนั้นใน xrEnumerateSpatialCapabilityFeaturesEXT รันไทม์ต้องละเว้นโครงสร้าง XrSpatialCapabilityFeatureEXT นั้น

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT หาก XrSpatialContextCreateInfoEXT :: capabilityConfigs มีโครงสร้างหลายรายการที่มี XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability เดียวกัน

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

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

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

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrCreateSpatialContextAsyncEXT
session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
createInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialContextCreateInfoEXT ที่ถูกต้อง
future ต้องเป็นพอยน์เตอร์ไปยังค่า XrFutureEXT

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_PERMISSION_INSUFFICIENT
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
XR_ERROR_VALIDATION_FAILURE

โครงสร้าง XrSpatialContextCreateInfoEXT มีคำจำกัดความดังนี้

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
capabilityConfigCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ capabilityConfigs
capabilityConfigs เป็นตัวชี้ไปยังอาร์เรย์ของตัวชี้ XrSpatialCapabilityConfigurationBaseHeaderEXT

โครงสร้าง XrSpatialContextCreateInfoEXT อธิบายข้อมูลในการสร้างแฮนเดิล XrSpatialContextEXT

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialContextCreateInfoEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ดูเพิ่มเติม: XrSpatialContextPersistenceConfigEXT
capabilityConfigs ต้องเป็น Pointer ไปยัง อาร์เรย์ ของโครงสร้างที่อิงตาม capabilityConfigCount XrSpatialCapabilityConfigurationBaseHeaderEXT ที่ถูกต้อง ดูเพิ่มเติม: XrSpatialCapabilityConfigurationAnchorEXT , XrSpatialCapabilityConfigurationAprilTagEXT , XrSpatialCapabilityConfigurationArucoMarkerEXT , XrSpatialCapabilityConfigurationDepthRaycastANDROID , XrSpatialCapabilityConfigurationImageTrackingEXT , XrSpatialCapabilityConfigurationMeshTrackingEXT , XrSpatialCapabilityConfigurationMicroQrCodeEXT , XrSpatialCapabilityConfigurationObjectTrackingANDROID , XrSpatialCapabilityConfigurationObjectTrackingEXT , XrSpatialCapabilityConfigurationPlaneTrackingEXT , XrSpatialCapabilityConfigurationQrCodeEXT , XrSpatialCapabilityConfigurationRoomBoundaryTrackingANDROIDSYS , XrSpatialCapabilityConfigurationRoomTrackingANDROIDSYS , XrSpatialCapabilityConfigurationStreetscapeGeometryANDROIDX2
พารามิเตอร์ capabilityConfigCount ต้องมากกว่า 0

โครงสร้าง XrSpatialCapabilityConfigurationBaseHeaderEXT มีคำจำกัดความดังนี้

typedef struct XrSpatialCapabilityConfigurationBaseHeaderEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationBaseHeaderEXT;

โครงสร้างนี้ไม่ได้ใช้ใน API โดยตรง แต่โครงสร้างย่อยของโครงสร้างนี้สามารถใช้กับ XrSpatialContextCreateInfoEXT เพื่อกำหนดค่าความสามารถเชิงพื้นที่ได้

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
capability คือ XrSpatialCapabilityEXT
enabledComponentCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ enabledComponents
enabledComponents เป็นตัวชี้ไปยังอาร์เรย์ของ XrSpatialComponentTypeEXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT หาก capability ไม่ได้ระบุโดย xrEnumerateSpatialCapabilitiesEXT รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT หากไม่ได้แจงนับประเภทคอมโพเนนต์ใดก็ตามที่ระบุไว้ใน enabledComponents สำหรับ capability ใน xrEnumerateSpatialCapabilityComponentTypesEXT

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialCapabilityConfigurationBaseHeaderEXT ได้
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
capability ต้องเป็นค่า XrSpatialCapabilityEXT ที่ถูกต้อง
enabledComponents ต้องเป็นตัวชี้ไปยังอาร์เรย์ของค่า enabledComponentCount XrSpatialComponentTypeEXT ที่ถูกต้อง
พารามิเตอร์ enabledComponentCount ต้องมากกว่า 0

ฟังก์ชัน xrCreateSpatialContextCompleteEXT มีคำจำกัดความดังนี้

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

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

session คือ XrSession ที่ส่งไปยัง xrCreateSpatialContextAsyncEXT :: session ก่อนหน้านี้
future คือ XrFutureEXT ที่ได้รับจาก xrCreateSpatialContextAsyncEXT
completion is a pointer to an XrCreateSpatialContextCompletionEXT .

xrCreateSpatialContextCompleteEXT จะดำเนินการแบบอะซิงโครนัสที่เริ่มโดย xrCreateSpatialContextAsyncEXT ให้เสร็จสมบูรณ์ รันไทม์ต้องแสดงผล XR_ERROR_FUTURE_PENDING_EXT หาก future ไม่อยู่ในสถานะพร้อมใช้งาน รันไทม์ต้องแสดงผล XR_ERROR_FUTURE_INVALID_EXT หาก future เสร็จสมบูรณ์หรือถูกยกเลิกแล้ว

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrCreateSpatialContextCompleteEXT
session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
completion ต้องเป็นตัวชี้ไปยังโครงสร้าง XrCreateSpatialContextCompletionEXT

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_FUTURE_INVALID_EXT
XR_ERROR_FUTURE_PENDING_EXT
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

โครงสร้าง XrCreateSpatialContextCompletionEXT มีการกำหนดไว้ดังนี้

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
futureResult คือ XrResult ของการดำเนินการสร้างบริบทเชิงพื้นที่
spatialContext คือ XrSpatialContextEXT ที่สร้างขึ้นโดยใช้ข้อมูลและการกำหนดค่าใน xrCreateSpatialContextAsyncEXT :: createInfo

รหัสการคืนสินค้าในอนาคต

ค่า futureResult

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_RUNTIME_FAILURE
XR_ERROR_INSTANCE_LOST
XR_ERROR_SESSION_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_LIMIT_REACHED
XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

หาก futureResult เป็นรหัสความสำเร็จ spatialContext ต้องถูกต้อง หาก spatialContext ใช้ได้ ก็จะใช้ได้เฉพาะภายในวงจรของ xrCreateSpatialContextAsyncEXT :: session หรือจนกว่าแอปพลิเคชันจะทำลาย spatialContext ด้วย xrDestroySpatialContextEXT แล้วแต่ว่ากรณีใดจะเกิดขึ้นก่อน

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

ต้องเปิดใช้XR_EXT_spatial_entityส่วนขยายก่อนใช้ XrCreateSpatialContextCompletionEXT
type ต้องเป็น XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
futureResult ต้องเป็นค่า XrResult ที่ถูกต้อง
หาก spatialContext ไม่ใช่ XR_NULL_HANDLE spatialContext ต้องเป็นแฮนเดิล XrSpatialContextEXT ที่ถูกต้อง

ทำลายบริบทเชิงพื้นที่

ฟังก์ชัน xrDestroySpatialContextEXT มีคำจำกัดความดังนี้

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

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

spatialContext คือ XrSpatialContextEXT ที่สร้างขึ้นก่อนหน้านี้โดย xrCreateSpatialContextAsyncEXT

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

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrDestroySpatialContextEXT
spatialContext ต้องเป็นแฮนเดิล XrSpatialContextEXT ที่ถูกต้อง

ความปลอดภัยของเธรด

การเข้าถึง spatialContext และแฮนเดิลย่อยทั้งหมดต้องซิงค์ภายนอก

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

สำเร็จ

XR_SUCCESS

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_RUNTIME_FAILURE

การแสดงเอนทิตีเชิงพื้นที่

รหัสเอนทิตีเชิงพื้นที่

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

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

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT เป็นค่าที่สงวนไว้ซึ่งแสดงถึง XrSpatialEntityIdEXT ที่ไม่ถูกต้อง โดยอาจส่งไปยังและรับจากฟังก์ชัน API ได้เฉพาะในกรณีที่ได้รับอนุญาตอย่างชัดเจนเท่านั้น

แฮนเดิลของเอนทิตีเชิงพื้นที่

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

แฮนเดิล XrSpatialEntityEXT แสดงเอนทิตีเชิงพื้นที่ แอปพลิเคชันสามารถสร้างแฮนเดิลดังกล่าวเพื่อแสดงความสนใจในเอนทิตีที่เฉพาะเจาะจงต่อรันไทม์

สร้างแฮนเดิลเอนทิตีเชิงพื้นที่จากรหัส

ฟังก์ชัน xrCreateSpatialEntityFromIdEXT มีคำจำกัดความดังนี้

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

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

spatialContext คือ XrSpatialContextEXT ที่สร้างไว้ก่อนหน้านี้โดยใช้ xrCreateSpatialContextAsyncEXT
createInfo เป็น Pointer ไปยังโครงสร้าง XrSpatialEntityFromIdCreateInfoEXT
spatialEntity คือแฮนเดิล XrSpatialEntityEXT ที่แสดงผล

แอปพลิเคชันสามารถใช้ xrCreateSpatialEntityFromIdEXT เพื่อสร้างแฮนเดิล XrSpatialEntityEXT ซึ่งเป็นข้อมูลอ้างอิงถึงเอนทิตีที่มีอยู่ในสภาพแวดล้อมของผู้ใช้

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT หาก XrSpatialEntityFromIdCreateInfoEXT :: entityId ไม่ใช่รหัสที่ใช้ได้สำหรับ spatialContext

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrCreateSpatialEntityFromIdEXT
spatialContext ต้องเป็นแฮนเดิล XrSpatialContextEXT ที่ถูกต้อง
createInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialEntityFromIdCreateInfoEXT ที่ถูกต้อง
spatialEntity ต้องเป็น Pointer ไปยังแฮนเดิล XrSpatialEntityEXT

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
XR_ERROR_VALIDATION_FAILURE

โครงสร้าง XrSpatialEntityFromIdCreateInfoEXT มีคำจำกัดความดังนี้

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
entityId คือ XrSpatialEntityIdEXT ของเอนทิตีที่แอปพลิเคชันต้องการสร้างแฮนเดิล

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialEntityFromIdCreateInfoEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง

ทำลายแฮนเดิลเอนทิตีเชิงพื้นที่

ฟังก์ชัน xrDestroySpatialEntityEXT มีคำจำกัดความดังนี้

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

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

spatialEntity คือแฮนเดิลของ XrSpatialEntityEXT ที่สร้างไว้ก่อนหน้านี้โดยฟังก์ชัน เช่น xrCreateSpatialEntityFromIdEXT

แอปพลิเคชันสามารถใช้ xrDestroySpatialEntityEXT เพื่อปล่อยแฮนเดิล spatialEntity เมื่อไม่สนใจเอนทิตีที่แฮนเดิลนี้อ้างอิงถึงอีกต่อไป

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrDestroySpatialEntityEXT
spatialEntity ต้องเป็นแฮนเดิล XrSpatialEntityEXT ที่ถูกต้อง

ความปลอดภัยของเธรด

การเข้าถึง spatialEntity และแฮนเดิลย่อยทั้งหมดต้องซิงค์ภายนอก

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

สำเร็จ

XR_SUCCESS

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_RUNTIME_FAILURE

สแนปชอตเชิงพื้นที่

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

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

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

สร้างสแนปชอตการค้นพบ

ฟังก์ชัน xrCreateSpatialDiscoverySnapshotAsyncEXT มีคำจำกัดความดังนี้

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

spatialContext คือ XrSpatialContextEXT ที่สร้างไว้ก่อนหน้านี้โดยใช้ xrCreateSpatialContextAsyncEXT
createInfo เป็น Pointer ไปยัง XrSpatialDiscoverySnapshotCreateInfoEXT
future เป็น Pointer ไปยัง XrFutureEXT

แอปพลิเคชันสามารถค้นพบเอนทิตีเชิงพื้นที่ได้โดยการสร้างสแนปชอตการค้นพบโดยใช้ xrCreateSpatialDiscoverySnapshotAsyncEXT

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

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

แอปพลิเคชันสามารถใช้ XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes เพื่อกรองรายการเอนทิตีและคอมโพเนนต์ที่มีข้อมูลที่รันไทม์ต้องรวมไว้ในสแนปชอต หากแอปพลิเคชันระบุรายการประเภทคอมโพเนนต์เชิงพื้นที่ที่ถูกต้องใน XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes รันไทม์ต้องรวมเฉพาะเอนทิตีเชิงพื้นที่ในสแนปชอตที่มีคอมโพเนนต์อย่างน้อย 1 รายการที่ระบุใน XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes นอกจากนี้ รันไทม์ต้องมีเฉพาะข้อมูลของคอมโพเนนต์เหล่านั้นในสแนปชอตเท่านั้น

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT หากไม่ได้เปิดใช้ XrSpatialComponentTypeEXT ใดๆ ใน XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes สำหรับความสามารถเชิงพื้นที่ที่ส่งไปยัง XrSpatialContextCreateInfoEXT :: capabilityConfigs เมื่อสร้าง spatialContext

หากแอปพลิเคชันไม่ได้ระบุรายการประเภทคอมโพเนนต์เชิงพื้นที่ใน XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes รันไทม์ต้องรวมเอนทิตีเชิงพื้นที่ทั้งหมดในสแนปชอตที่มีชุดคอมโพเนนต์ซึ่งแสดงใน XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents สำหรับความสามารถที่กำหนดค่าไว้สำหรับ spatialContext รันไทม์ต้องมีข้อมูลสำหรับคอมโพเนนต์ที่เปิดใช้ทั้งหมดของความสามารถที่กำหนดค่าไว้สำหรับ spatialContext

หากมีการจัดคิว XrEventDataReferenceSpaceChangePending ก่อนที่ future จะเสร็จสมบูรณ์ และ XrEventDataReferenceSpaceChangePending :: poseValid เป็นเท็จ รันไทม์อาจสร้าง XrSpatialSnapshotEXT ที่ไม่มีเอนทิตีอยู่ หรือตั้งค่า XrSpatialEntityTrackingStateEXT ของเอนทิตีที่ระบุตำแหน่งไม่ได้อีกต่อไปใน XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace ที่ XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time เป็น XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT หรือ XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT รันไทม์ต้องไม่ตั้งค่า XrCreateSpatialContextCompletionEXT :: futureResult เป็นรหัสข้อผิดพลาดเนื่องจาก XrEventDataReferenceSpaceChangePending

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

ต้องเปิดใช้XR_EXT_spatial_entityส่วนขยายก่อนที่จะเรียกใช้ xrCreateSpatialDiscoverySnapshotAsyncEXT
spatialContext ต้องเป็นแฮนเดิล XrSpatialContextEXT ที่ถูกต้อง
createInfo ต้องเป็น Pointer ไปยังโครงสร้าง XrSpatialDiscoverySnapshotCreateInfoEXT ที่ถูกต้อง
future ต้องเป็นพอยน์เตอร์ไปยังค่า XrFutureEXT

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
XR_ERROR_VALIDATION_FAILURE

โครงสร้าง XrSpatialDiscoverySnapshotCreateInfoEXT มีคำจำกัดความดังนี้

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
componentTypeCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ componentTypes
componentTypes คืออาร์เรย์ของ XrSpatialComponentTypeEXT

โครงสร้าง XrSpatialDiscoverySnapshotCreateInfoEXT อธิบายข้อมูลที่จะใช้สร้างแฮนเดิล XrSpatialSnapshotEXT เมื่อค้นพบเอนทิตีเชิงพื้นที่

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

ต้องเปิดใช้XR_EXT_spatial_entityส่วนขยายก่อนจึงจะใช้ XrSpatialDiscoverySnapshotCreateInfoEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ดูเพิ่มเติม: XrSpatialBoundsBoxfANDROID , XrSpatialBoundsFrustumfANDROID , XrSpatialBoundsSpherefANDROID , XrSpatialDiscoveryPersistenceUuidFilterEXT , XrSpatialDiscoveryRoomBoundaryFilterANDROIDSYS , XrSpatialDiscoveryUniqueEntitiesFilterANDROID , XrSpatialFilterTrackingStateEXT , XrSpatialRaycastInfoANDROID
หาก componentTypeCount ไม่ใช่ 0 componentTypes ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า XrSpatialComponentTypeEXT ที่ถูกต้อง componentTypeCount

ฟังก์ชัน xrCreateSpatialDiscoverySnapshotCompleteEXT มีคำจำกัดความดังนี้

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

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

spatialContext คือ XrSpatialContextEXT ที่ส่งไปยัง xrCreateSpatialDiscoverySnapshotAsyncEXT ก่อนหน้านี้ :: spatialContext
createSnapshotCompletionInfo เป็นตัวชี้ไปยัง XrCreateSpatialDiscoverySnapshotCompletionInfoEXT ซึ่งให้ข้อมูลเกี่ยวกับการดำเนินการตามคำขอสร้างสแนปชอตการค้นพบเสร็จสมบูรณ์
completion เป็น Pointer ไปยัง XrCreateSpatialDiscoverySnapshotCompletionEXT

xrCreateSpatialDiscoverySnapshotCompleteEXT จะดำเนินการแบบไม่พร้อมกันที่เริ่มต้นโดย xrCreateSpatialDiscoverySnapshotAsyncEXT ให้เสร็จสมบูรณ์ รันไทม์ต้องแสดงผล XR_ERROR_FUTURE_PENDING_EXT หาก XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future ไม่อยู่ในสถานะพร้อมใช้งาน รันไทม์ต้องส่งคืน XR_ERROR_FUTURE_INVALID_EXT หาก XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future เสร็จสมบูรณ์หรือถูกยกเลิกแล้ว

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrCreateSpatialDiscoverySnapshotCompleteEXT
spatialContext ต้องเป็นแฮนเดิล XrSpatialContextEXT ที่ถูกต้อง
createSnapshotCompletionInfo ต้องเป็น Pointer ที่ถูกต้องไปยังโครงสร้าง XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
completion ต้องเป็นตัวชี้ไปยังโครงสร้าง XrCreateSpatialDiscoverySnapshotCompletionEXT

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_FUTURE_INVALID_EXT
XR_ERROR_FUTURE_PENDING_EXT
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_TIME_INVALID
XR_ERROR_VALIDATION_FAILURE

โครงสร้าง XrCreateSpatialDiscoverySnapshotCompletionInfoEXT มีการกำหนดไว้ดังนี้

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
baseSpace คือ XrSpace ซึ่งเป็นที่ตั้งของ XrSpatialSnapshotEXT ทั้งหมด
time คือ XrTime ที่ตำแหน่งทั้งหมดของ XrSpatialSnapshotEXT จะอยู่
future คือ XrFutureEXT ที่ได้รับจาก xrCreateSpatialDiscoverySnapshotAsyncEXT

ระบบจะแสดงตำแหน่งในข้อมูลคอมโพเนนต์ต่างๆ ที่รวมอยู่ในสแนปชอตที่สร้างขึ้นใน baseSpace ซึ่งอยู่ที่ time

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrCreateSpatialDiscoverySnapshotCompletionInfoEXT ได้
type ต้องเป็น XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
baseSpace ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง

โครงสร้าง XrCreateSpatialDiscoverySnapshotCompletionEXT มีการกำหนดไว้ดังนี้

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
futureResult คือ XrResult ของการดำเนินการสร้างสแนปชอตการค้นพบเชิงพื้นที่
snapshot คือ XrSpatialSnapshotEXT ซึ่งใช้เพื่อค้นหาข้อมูลคอมโพเนนต์ของเอนทิตีเชิงพื้นที่ที่ค้นพบได้

รหัสการคืนสินค้าในอนาคต

ค่า futureResult

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_RUNTIME_FAILURE
XR_ERROR_INSTANCE_LOST
XR_ERROR_SESSION_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_LIMIT_REACHED

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrCreateSpatialDiscoverySnapshotCompletionEXT ได้
type ต้องเป็น XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
futureResult ต้องเป็นค่า XrResult ที่ถูกต้อง
หาก snapshot ไม่ใช่ XR_NULL_HANDLE snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง

เหตุการณ์การแนะนำการค้นพบ

โครงสร้าง XrEventDataSpatialDiscoveryRecommendedEXT มีคำจำกัดความดังนี้

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
spatialContext คือ XrSpatialContextEXT ที่รันไทม์แนะนำให้ค้นหา

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

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

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

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

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

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

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

ต้องเปิดใช้XR_EXT_spatial_entityส่วนขยายก่อนจึงจะใช้ XrEventDataSpatialDiscoveryRecommendedEXT ได้
type ต้องเป็น XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง

ค้นหาข้อมูลคอมโพเนนต์

ฟังก์ชัน xrQuerySpatialComponentDataEXT มีคำจำกัดความดังนี้

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

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

snapshot คือ XrSpatialSnapshotEXT ที่ได้รับก่อนหน้านี้จาก xrCreateSpatialDiscoverySnapshotCompleteEXT หรือ xrCreateSpatialUpdateSnapshotEXT
queryCondition เป็น Pointer ไปยังโครงสร้าง XrSpatialComponentDataQueryConditionEXT
queryResult คือ Pointer ไปยังโครงสร้าง XrSpatialComponentDataQueryResultEXT

แอปพลิเคชันสามารถใช้ xrQuerySpatialComponentDataEXT เพื่อค้นหาข้อมูลคอมโพเนนต์ของเอนทิตีในสแนปชอตได้โดยการแนบโครงสร้างรายการไปยัง XrSpatialComponentDataQueryResultEXT :: next ที่สอดคล้องกับ XrSpatialComponentTypeEXT แต่ละรายการใน XrSpatialComponentDataQueryConditionEXT :: componentTypes

หากแอปพลิเคชันแนบโครงสร้างรายการกับ XrSpatialComponentDataQueryResultEXT :: next ที่ไม่สอดคล้องกับคอมโพเนนต์ใดๆ ที่ระบุไว้ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE

แอปพลิเคชันสามารถเลือกที่จะแนบโครงสร้างรายการที่สอดคล้องกับเฉพาะชุดย่อยของคอมโพเนนต์ที่แสดงใน XrSpatialComponentDataQueryConditionEXT :: componentTypes แอปพลิเคชันสามารถเลือกที่จะละเว้นโครงสร้างรายการทั้งหมดได้หากต้องการทราบเฉพาะรหัสและสถานะการติดตามของเอนทิตีเชิงพื้นที่ที่ตรงตาม queryCondition รันไทม์ต้องไม่ถือว่าการไม่มีโครงสร้างรายการจากเชน XrSpatialComponentDataQueryResultEXT :: next เป็นความล้มเหลว

หากมีการจัดคิว XrEventDataReferenceSpaceChangePending และ XrEventDataReferenceSpaceChangePending :: changeTime elapsed ขณะที่แอปพลิเคชันกําลังค้นหาข้อมูลคอมโพเนนต์จาก XrSpatialSnapshotEXT แอปพลิเคชันอาจใช้ข้อมูลเหตุการณ์เพื่อปรับท่าทางตามนั้น

รันไทม์ต้องป้อนข้อมูล XrSpatialComponentDataQueryResultEXT :: entityIds ด้วยเอนทิตีที่มีคอมโพเนนต์ทั้งหมดที่ระบุใน XrSpatialComponentDataQueryConditionEXT :: componentTypes เท่านั้น หาก XrSpatialComponentDataQueryConditionEXT :: componentTypeCount เป็น 0 รันไทม์ต้องป้อนข้อมูล queryResult ด้วยเอนทิตีทั้งหมด (และสถานะการติดตามของเอนทิตี) ที่อยู่ในสแนปชอต หากมีการเพิ่มเงื่อนไขการค้นหาเพิ่มเติมใน XrSpatialComponentDataQueryConditionEXT :: next รันไทม์ต้องถือว่าเงื่อนไขเหล่านั้นเป็น "AND" ที่มีประเภทคอมโพเนนต์ที่พร้อมใช้งาน กล่าวคือ รันไทม์ต้องป้อน XrSpatialComponentDataQueryResultEXT ::entityIds เฉพาะกับเอนทิตีที่ตรงตามเงื่อนไขทั้งหมดที่ระบุ รันไทม์ต้องป้อนข้อมูลคอมโพเนนต์ในโครงสร้างรายการตามลำดับเดียวกับเอนทิตีใน XrSpatialComponentDataQueryResultEXT :: entityIds กล่าวคือ ข้อมูลคอมโพเนนต์ที่ดัชนีที่กำหนดในอาร์เรย์โครงสร้างรายการต้องสอดคล้องกับเอนทิตีที่ดัชนีเดียวกัน

หากสถานะการติดตามของเอนทิตีไม่ใช่ XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT รันไทม์ต้องไม่เปลี่ยนแปลงข้อมูลที่ดัชนีซึ่งสอดคล้องกับเอนทิตีนั้นในอาร์เรย์ที่อยู่ในโครงสร้างรายการที่แนบมากับ XrSpatialComponentDataQueryResultEXT

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนเรียกใช้ xrQuerySpatialComponentDataEXT
snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง
queryCondition ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialComponentDataQueryConditionEXT ที่ถูกต้อง
queryResult ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialComponentDataQueryResultEXT

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_VALIDATION_FAILURE

ตัวอย่างเช่น แอปพลิเคชันสร้าง XrSpatialSnapshotEXT ซึ่งมีเอนทิตี 5 รายการ โดยมีรายละเอียดดังนี้

เอนทิตี 1 และ 2 มีคอมโพเนนต์ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT และ XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
เอนทิตี 3 และ 4 มีคอมโพเนนต์ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT และ XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
เอนทิตี 5 มีคอมโพเนนต์ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT และ XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

XrSpatialEntityIdEXT

Bounded2D

ใช่

ได้

ไม่ใช่

ไม่ได้

ใช่

ผู้ปกครอง

ใช่

ได้

ไม่ใช่

ไม่ได้

ไม่

Mesh3D

ไม่

ไม่ได้

ใช่

ได้

ใช่

Bounded3D

ไม่

ไม่ได้

ใช่

ได้

ไม่

ไม่มี ข้อความไม่ใช่ SVG - แสดงไม่ได้

รูปที่ 20 ตัวอย่างภาพรวม

xrQuerySpatialComponentDataEXT ในสแนปชอตด้านบนที่มี XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT แสดงอยู่ในเงื่อนไขการค้นหาจะส่งผลให้ระบบส่งเอนทิตี #1, #2 และ #5 กลับไปยังแอปพลิเคชัน และแอปพลิเคชันสามารถแนบอาร์เรย์ของ XrSpatialBounded2DDataEXT เป็นส่วนหนึ่งของโครงสร้าง XrSpatialComponentBounded2DListEXT ไปยังเชนถัดไปของ XrSpatialComponentDataQueryResultEXT เพื่อรับข้อมูล bounded2D

XrSpatialEntityIdEXT

Bounded2D

ข้อมูลสำหรับ entityId #1

ข้อมูลสำหรับเอนทิตี...

ข้อมูลสำหรับ entityId #2

ข้อมูลสำหรับเอนทิตี...

ข้อมูลสำหรับ entityId #5

ข้อมูลสำหรับเอนทิตี...

entityIds

XrSpatialComponent DataQueryResultEXT

XrSpatialComponent Dat...

ขอบเขต

XrSpatialComponent Bounded2DListEXT

XrSpatialComponent Bou... ข้อความไม่ใช่ SVG - แสดงไม่ได้

รูปที่ 21 ตัวอย่างผลการค้นหา

xrQuerySpatialComponentDataEXT ในสแนปชอตด้านบนที่มีคอมโพเนนต์ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT และ XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT ที่ระบุไว้ในเงื่อนไขการค้นหาจะส่งผลให้ระบบแสดงเอนทิตี #3 และ #4 กลับไปยังแอปพลิเคชัน และแอปพลิเคชันสามารถแนบอาร์เรย์ของ XrBoxf และ XrSpatialMeshDataEXT เป็นส่วนหนึ่งของโครงสร้าง XrSpatialComponentBounded3DListEXT และ XrSpatialComponentMesh3DListEXT ตามลำดับไปยังเชนถัดไปของ XrSpatialComponentDataQueryResultEXT เพื่อรับข้อมูลคอมโพเนนต์

XrSpatialEntityIdEXT

Bounded3D

ข้อมูลสำหรับ entityId #3

ข้อมูลสำหรับเอนทิตี...

ข้อมูลสำหรับ entityId #4

ข้อมูลสำหรับเอนทิตี...

Mesh3D

ข้อมูลสำหรับ entityId #3

ข้อมูลสำหรับเอนทิตี...

ข้อมูลสำหรับ entityId #4

ข้อมูลสำหรับเอนทิตี...

entityIds

XrSpatialComponent DataQueryResultEXT

XrSpatialComponent Da...

ขอบเขต

XrSpatialComponent Bounded3DListEXT

XrSpatialComponent Bo...

XrSpatialComponent Mesh3DListEXT

XrSpatialComponent Me...

meshes

meshes ข้อความไม่ใช่ SVG - แสดงไม่ได้

รูปที่ 22 ตัวอย่างผลการค้นหา

โครงสร้าง XrSpatialComponentDataQueryConditionEXT มีการกำหนดไว้ดังนี้

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
componentTypeCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ componentTypes
componentTypes คืออาร์เรย์ของ XrSpatialComponentTypeEXT ที่จะรับข้อมูลจากสแนปชอต

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialComponentDataQueryConditionEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ดูเพิ่มเติม: XrSpatialDiscoveryPersistenceUuidFilterEXT , XrSpatialFilterArchetypeEXT , XrSpatialFilterTrackingStateEXT
หาก componentTypeCount ไม่ใช่ 0 componentTypes ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า XrSpatialComponentTypeEXT ที่ถูกต้อง componentTypeCount

โครงสร้าง XrSpatialComponentDataQueryResultEXT มีการกำหนดไว้ดังนี้

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
entityIdCapacityInput คือความจุของอาร์เรย์ entityIds หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
entityIdCountOutput คือจำนวน XrSpatialEntityIdEXT ใน entityIds หรือความจุที่จำเป็นในกรณีที่ entityIdCapacityInput ไม่เพียงพอ
entityIds เป็นอาร์เรย์ของ XrSpatialEntityIdEXT ทำได้หาก entityIdCapacityInput เป็น 0NULL
entityStateCapacityInput คือความจุของอาร์เรย์ entityStates หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
entityStateCountOutput คือจำนวน XrSpatialEntityTrackingStateEXT ใน entityStates หรือความจุที่จำเป็นในกรณีที่ entityStateCapacityInput ไม่เพียงพอ ต้องเหมือนกับ entityIdCountOutput เสมอ
entityStates คืออาร์เรย์ของ XrSpatialEntityTrackingStateEXT ทำได้หาก entityStateCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด entityIds ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

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

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialComponentDataQueryResultEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ดูเพิ่มเติม: XrSpatialComponentAnchorListEXT , XrSpatialComponentAnnotationQuadListANDROID , XrSpatialComponentBounded2DListEXT , XrSpatialComponentBounded3DListEXT , XrSpatialComponentConfidenceListANDROIDSYS , XrSpatialComponentImage2DListEXT , XrSpatialComponentKeyboardSemanticLabelListEXT , XrSpatialComponentMarkerListEXT , XrSpatialComponentMaterialTypeListANDROIDSYS , XrSpatialComponentMesh2DListEXT , XrSpatialComponentMesh3DListEXT , XrSpatialComponentMesh3DNormalsListEXT , XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT , XrSpatialComponentMesh3DVertexSemanticLabelsListEXT , XrSpatialComponentMouseSemanticLabelListEXT , XrSpatialComponentObjectSemanticLabelListANDROID , XrSpatialComponentObjectSemanticLabelListEXT , XrSpatialComponentOccupancyGridListANDROIDX1 , XrSpatialComponentParentListEXT , XrSpatialComponentPersistenceListEXT , XrSpatialComponentPlaneAlignmentListEXT , XrSpatialComponentPlaneSemanticLabelListEXT , XrSpatialComponentPolygon2DListEXT , XrSpatialComponentRaycastResultListANDROID , XrSpatialComponentRoomEmptinessListANDROIDSYS , XrSpatialComponentRoomListANDROIDSYS , XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 , XrSpatialComponentSubsumedByListANDROID
หาก entityIdCapacityInput ไม่ใช่ 0 entityIds ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า entityIdCapacityInput XrSpatialEntityIdEXT
หาก entityStateCapacityInput ไม่ใช่ 0 entityStates ต้องเป็น Pointer ไปยังอาร์เรย์ของค่า entityStateCapacityInput XrSpatialEntityTrackingStateEXT

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

XrSpatialEntityTrackingStateEXT จะแจกแจงสถานะการติดตามเอนทิตีเชิงพื้นที่ที่เป็นไปได้ ดังนี้

โดย Enum มีความหมายดังนี้

คำอธิบาย Enum

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

รันไทม์หยุดติดตามเอนทิตีนี้แล้วและจะไม่ติดตามอีก

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

รันไทม์หยุดติดตามเอนทิตีนี้ชั่วคราว แต่อาจกลับมาติดตามอีกครั้งในอนาคต

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

ขณะนี้รันไทม์กำลังติดตามเอนทิตีนี้และข้อมูลคอมโพเนนต์ของเอนทิตีถูกต้อง

การติดตาม

หยุดชั่วคราว

หยุดแล้ว

รูปที่ 23 XrSpatialEntityTrackingStateEXT

รันไทม์อาจเปลี่ยนสถานะของเอนทิตีเชิงพื้นที่จาก XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT เป็น XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT หากระงับการติดตามเอนทิตีเชิงพื้นที่นั้น แต่มีโอกาสที่จะกลับมาติดตามอีกครั้งในอนาคต ตัวอย่างบางส่วนที่รันไทม์อาจดำเนินการนี้ ได้แก่ (แต่ไม่จำกัดเพียง) หากแอปพลิเคชันสูญเสียโฟกัสอินพุต หรือหากเอนทิตีเชิงพื้นที่ที่ระบุอยู่ไกลจากผู้ใช้มากเกินไปจนติดตามได้อย่างไม่ถูกต้อง หรือหากมีการติดตามเอนทิตีมากเกินไปและรันไทม์ต้องการลดต้นทุนในการติดตาม XrSpatialEntityTrackingStateEXT ช่วยให้แอปพลิเคชันแยกตัวเองออกจากนโยบายการติดตามที่แตกต่างกันของแต่ละรันไทม์ได้
รันไทม์อาจเปลี่ยนสถานะของเอนทิตีจาก XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT เป็น XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT หรือ XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT
รันไทม์ต้องเปลี่ยนสถานะของเอนทิตีเชิงพื้นที่จาก XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT หรือ XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT เป็น XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT หากระบบไม่พบเอนทิตีเชิงพื้นที่และจะไม่สามารถกู้คืนหรือกลับมาติดตามได้อีก ตัวอย่างกรณีดังกล่าวคือหากอุปกรณ์สูญเสียการติดตาม รีสตาร์ทเซสชันการติดตาม แต่ไม่สามารถระบุตำแหน่งใหม่ในสภาพแวดล้อมได้ ดังนั้นจึงถือว่าเอนทิตีที่ค้นพบในเซสชันการติดตามนี้เป็นเอนทิตีใหม่
เมื่อตั้งค่าสถานะการติดตามของเอนทิตีเป็น XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT แล้ว รันไทม์ต้องไม่เปลี่ยนสถานะเป็นสถานะอื่น
เมื่อค้นหาข้อมูลคอมโพเนนต์ของเอนทิตีเชิงพื้นที่โดยใช้ xrQuerySpatialComponentDataEXT รันไทม์ต้องตั้งค่าข้อมูลที่ถูกต้องในเนื้อหาของบัฟเฟอร์ที่แอปพลิเคชันระบุไว้ในเชนถัดไปของ XrSpatialComponentDataQueryResultEXT หากสถานะของเอนทิตีเป็น XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT หากสถานะเอนทิตีเป็น XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT หรือ XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT รันไทม์ต้องไม่เปลี่ยนแปลงเนื้อหาของบัฟเฟอร์

รูปแบบการเรียกใช้ 2 ครั้งสำหรับข้อมูลคอมโพเนนต์

โครงสร้าง XrSpatialBufferEXT มีการกำหนดไว้ดังนี้

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

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

bufferId XrSpatialBufferIdEXT ของข้อมูลบัฟเฟอร์
bufferType คือ XrSpatialBufferTypeEXT เพื่อระบุประเภทข้อมูลใน bufferId แอปพลิเคชันสามารถใช้ bufferType เพื่อระบุฟังก์ชันที่จะใช้ในการดึงข้อมูลจริงของบัฟเฟอร์

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

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

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialBufferEXT ได้
bufferType ต้องเป็นค่า XrSpatialBufferTypeEXT ที่ถูกต้อง

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

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

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

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

การแจงนับ XrSpatialBufferTypeEXT จะระบุประเภทข้อมูลต่างๆ ของบัฟเฟอร์ที่แสดง XrSpatialBufferIdEXT

คำอธิบายรายการ

XR_SPATIAL_BUFFER_TYPE_STRING_EXT XrSpatialBufferIdEXT can จะส่งไปยัง xrGetSpatialBufferStringEXT เพื่อเรียกบัฟเฟอร์สตริง
XR_SPATIAL_BUFFER_TYPE_UINT8_EXT XrSpatialBufferIdEXT can จะส่งไปยัง xrGetSpatialBufferUint8EXT เพื่อเรียกบัฟเฟอร์ uint8_t
XR_SPATIAL_BUFFER_TYPE_UINT16_EXT XrSpatialBufferIdEXT can จะส่งไปยัง xrGetSpatialBufferUint16EXT เพื่อเรียกบัฟเฟอร์ uint16_t
XR_SPATIAL_BUFFER_TYPE_UINT32_EXT XrSpatialBufferIdEXT can จะส่งไปยัง xrGetSpatialBufferUint32EXT เพื่อเรียกบัฟเฟอร์ uint32_t
XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT XrSpatialBufferIdEXT can จะส่งไปยัง xrGetSpatialBufferFloatEXT เพื่อเรียกบัฟเฟอร์ float
XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT XrSpatialBufferIdEXT สามารถส่งไปยัง xrGetSpatialBufferVector2fEXT เพื่อเรียกบัฟเฟอร์ XrVector2f
XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT XrSpatialBufferIdEXT สามารถส่งไปยัง xrGetSpatialBufferVector3fEXT เพื่อเรียกบัฟเฟอร์ XrVector3f

ฟังก์ชัน xrGetSpatialBufferStringEXT มีคำจำกัดความดังนี้

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

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

snapshot is a handle to an XrSpatialSnapshotEXT .
info มีข้อมูลเกี่ยวกับบัฟเฟอร์ที่จะค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
bufferCountOutput คือจำนวนอักขระ หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ char ทำได้หาก bufferCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด buffer ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถรับข้อมูลสำหรับ XrSpatialBufferEXT ที่คอมโพเนนต์จัดหาให้ได้ โดยที่ XrSpatialBufferEXT :: bufferType คือ XR_SPATIAL_BUFFER_TYPE_STRING_EXT โดยใช้ xrGetSpatialBufferStringEXT

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE หาก XrSpatialBufferTypeEXT สำหรับ XrSpatialBufferGetInfoEXT :: bufferId ไม่ใช่ XR_SPATIAL_BUFFER_TYPE_STRING_EXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT หาก XrSpatialBufferGetInfoEXT :: bufferId ไม่ได้อยู่ใน snapshot

buffer ที่รันไทม์กรอกต้องเป็นสตริง UTF-8 ที่สิ้นสุดด้วยค่าว่าง

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrGetSpatialBufferStringEXT
snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง
info ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialBufferGetInfoEXT ที่ถูกต้อง
bufferCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า bufferCapacityInput char

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
XR_ERROR_VALIDATION_FAILURE

ฟังก์ชัน xrGetSpatialBufferUint8EXT มีคำจำกัดความดังนี้

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

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

snapshot is a handle to an XrSpatialSnapshotEXT .
info มีข้อมูลเกี่ยวกับบัฟเฟอร์ที่จะค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ uint8_t ทำได้หาก bufferCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด buffer ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถรับข้อมูลสำหรับ XrSpatialBufferEXT ที่คอมโพเนนต์จัดหาให้ได้ โดยที่ XrSpatialBufferEXT :: bufferType คือ XR_SPATIAL_BUFFER_TYPE_UINT8_EXT โดยใช้ xrGetSpatialBufferUint8EXT

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE หาก XrSpatialBufferTypeEXT สำหรับ XrSpatialBufferGetInfoEXT :: bufferId ไม่ใช่ XR_SPATIAL_BUFFER_TYPE_UINT8_EXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT หาก XrSpatialBufferGetInfoEXT :: bufferId ไม่ได้อยู่ใน snapshot

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrGetSpatialBufferUint8EXT
snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง
info ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialBufferGetInfoEXT ที่ถูกต้อง
bufferCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า bufferCapacityInput uint8_t

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
XR_ERROR_VALIDATION_FAILURE

ฟังก์ชัน xrGetSpatialBufferUint16EXT มีคำจำกัดความดังนี้

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

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

snapshot is a handle to an XrSpatialSnapshotEXT .
info มีข้อมูลเกี่ยวกับบัฟเฟอร์ที่จะค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ uint16_t ทำได้หาก bufferCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด buffer ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถรับข้อมูลสำหรับ XrSpatialBufferEXT ที่คอมโพเนนต์จัดหาให้ได้ โดยที่ XrSpatialBufferEXT :: bufferType คือ XR_SPATIAL_BUFFER_TYPE_UINT16_EXT โดยใช้ xrGetSpatialBufferUint16EXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT หาก XrSpatialBufferGetInfoEXT :: bufferId ไม่ได้อยู่ใน snapshot

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrGetSpatialBufferUint16EXT
snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง
info ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialBufferGetInfoEXT ที่ถูกต้อง
bufferCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า bufferCapacityInput uint16_t

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
XR_ERROR_VALIDATION_FAILURE

ฟังก์ชัน xrGetSpatialBufferUint32EXT มีคำจำกัดความดังนี้

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

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

snapshot is a handle to an XrSpatialSnapshotEXT .
info มีข้อมูลเกี่ยวกับบัฟเฟอร์ที่จะค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ uint32_t ทำได้หาก bufferCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด buffer ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถรับข้อมูลสำหรับ XrSpatialBufferEXT ที่คอมโพเนนต์จัดหาให้ได้ โดยที่ XrSpatialBufferEXT :: bufferType คือ XR_SPATIAL_BUFFER_TYPE_UINT32_EXT โดยใช้ xrGetSpatialBufferUint32EXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT หาก XrSpatialBufferGetInfoEXT :: bufferId ไม่ได้อยู่ใน snapshot

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

ต้องเปิดใช้XR_EXT_spatial_entityส่วนขยายก่อนเรียกใช้ xrGetSpatialBufferUint32EXT
snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง
info ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialBufferGetInfoEXT ที่ถูกต้อง
bufferCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า bufferCapacityInput uint32_t

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
XR_ERROR_VALIDATION_FAILURE

ฟังก์ชัน xrGetSpatialBufferFloatEXT มีคำจำกัดความดังนี้

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

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

snapshot is a handle to an XrSpatialSnapshotEXT .
info มีข้อมูลเกี่ยวกับบัฟเฟอร์ที่จะค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ float ทำได้หาก bufferCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด buffer ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถรับข้อมูลสำหรับ XrSpatialBufferEXT ที่คอมโพเนนต์จัดหาให้ได้ โดยที่ XrSpatialBufferEXT :: bufferType คือ XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT โดยใช้ xrGetSpatialBufferFloatEXT

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE หาก XrSpatialBufferTypeEXT สำหรับ XrSpatialBufferGetInfoEXT :: bufferId ไม่ใช่ XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT หาก XrSpatialBufferGetInfoEXT :: bufferId ไม่ได้อยู่ใน snapshot

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrGetSpatialBufferFloatEXT
snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง
info ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialBufferGetInfoEXT ที่ถูกต้อง
bufferCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า bufferCapacityInput float

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
XR_ERROR_VALIDATION_FAILURE

ฟังก์ชัน xrGetSpatialBufferVector2fEXT มีคำจำกัดความดังนี้

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

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

snapshot is a handle to an XrSpatialSnapshotEXT .
info มีข้อมูลเกี่ยวกับบัฟเฟอร์ที่จะค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ XrVector2f ทำได้หาก bufferCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด buffer ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถรับข้อมูลสำหรับ XrSpatialBufferEXT ที่คอมโพเนนต์จัดหาให้ได้ โดยที่ XrSpatialBufferEXT :: bufferType คือ XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT โดยใช้ xrGetSpatialBufferVector2fEXT

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE หาก XrSpatialBufferTypeEXT สำหรับ XrSpatialBufferGetInfoEXT :: bufferId ไม่ใช่ XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT หาก XrSpatialBufferGetInfoEXT :: bufferId ไม่ได้อยู่ใน snapshot

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrGetSpatialBufferVector2fEXT
snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง
info ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialBufferGetInfoEXT ที่ถูกต้อง
bufferCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็น Pointer ไปยังอาร์เรย์ของโครงสร้าง XrVector2f ของ bufferCapacityInput

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
XR_ERROR_VALIDATION_FAILURE

ฟังก์ชัน xrGetSpatialBufferVector3fEXT มีคำจำกัดความดังนี้

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

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

snapshot is a handle to an XrSpatialSnapshotEXT .
info มีข้อมูลเกี่ยวกับบัฟเฟอร์ที่จะค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอเรียกความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer คืออาร์เรย์ของ XrVector3f ทำได้หาก bufferCapacityInput เป็น 0NULL
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด buffer ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถรับข้อมูลสำหรับ XrSpatialBufferEXT ที่คอมโพเนนต์จัดหาให้ได้ โดยที่ XrSpatialBufferEXT :: bufferType คือ XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT โดยใช้ xrGetSpatialBufferVector3fEXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT หาก XrSpatialBufferGetInfoEXT :: bufferId ไม่ได้อยู่ใน snapshot

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrGetSpatialBufferVector3fEXT
snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง
info ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialBufferGetInfoEXT ที่ถูกต้อง
bufferCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็น Pointer ไปยัง อาร์เรย์ ของโครงสร้าง XrVector3f จำนวน bufferCapacityInput

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
XR_ERROR_VALIDATION_FAILURE

โครงสร้าง XrSpatialBufferGetInfoEXT มีคำจำกัดความดังนี้

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
bufferId XrSpatialBufferIdEXTสำหรับบัฟเฟอร์ที่จะดึงข้อมูล

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

ต้องเปิดใช้XR_EXT_spatial_entityส่วนขยายก่อนใช้ XrSpatialBufferGetInfoEXT
type ต้องเป็น XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT เป็นค่าที่สงวนไว้ซึ่งแสดงถึง XrSpatialBufferIdEXT ที่ไม่ถูกต้อง โดยอาจส่งไปยังและรับจากฟังก์ชัน API ได้เฉพาะในกรณีที่ได้รับอนุญาตอย่างชัดเจนเท่านั้น

สร้างสแนปชอตการอัปเดต

ฟังก์ชัน xrCreateSpatialUpdateSnapshotEXT มีคำจำกัดความดังนี้

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

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

spatialContext คือ XrSpatialContextEXT ที่สร้างไว้ก่อนหน้านี้โดยใช้ xrCreateSpatialContextAsyncEXT
createInfo เป็น Pointer ไปยัง XrSpatialUpdateSnapshotCreateInfoEXT
snapshot เป็นตัวชี้ไปยังผลลัพธ์ XrSpatialSnapshotEXT

แอปพลิเคชันสามารถใช้ xrCreateSpatialUpdateSnapshotEXT เพื่อสร้างสแนปชอตและรับข้อมูลคอมโพเนนต์ล่าสุดสำหรับเอนทิตีที่เฉพาะเจาะจงตามที่รันไทม์ทราบ แอปพลิเคชันสามารถระบุแฮนเดิล XrSpatialEntityEXT และประเภทคอมโพเนนต์ที่สนใจเมื่อสร้างสแนปชอต

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

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT หากไม่ได้เปิดใช้ XrSpatialComponentTypeEXT ใดๆ ใน XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes สำหรับความสามารถเชิงพื้นที่ที่ส่งไปยัง XrSpatialContextCreateInfoEXT :: capabilityConfigs เมื่อสร้าง spatialContext

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

รันไทม์ต้องไม่รวมเอนทิตีเชิงพื้นที่ที่ไม่ได้ระบุไว้ใน XrSpatialUpdateSnapshotCreateInfoEXT :: entities ใน snapshot

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrCreateSpatialUpdateSnapshotEXT
spatialContext ต้องเป็นแฮนเดิล XrSpatialContextEXT ที่ถูกต้อง
createInfo ต้องเป็น Pointer ไปยังโครงสร้าง XrSpatialUpdateSnapshotCreateInfoEXT ที่ถูกต้อง
snapshot ต้องเป็นตัวชี้ไปยังแฮนเดิล XrSpatialSnapshotEXT

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

สำเร็จ

XR_SUCCESS
XR_SESSION_LOSS_PENDING

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
XR_ERROR_TIME_INVALID
XR_ERROR_VALIDATION_FAILURE

โครงสร้าง XrSpatialUpdateSnapshotCreateInfoEXT มีคำจำกัดความดังนี้

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
entityCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ entities
entities คืออาร์เรย์ของ XrSpatialEntityEXT ซึ่งรันไทม์ต้องรวมข้อมูลคอมโพเนนต์ไว้ในสแนปชอต
componentTypeCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ componentTypes
componentTypes คืออาร์เรย์ของ XrSpatialComponentTypeEXT ซึ่งรันไทม์ต้องรวมข้อมูลไว้ในสแนปชอต
baseSpace คือ XrSpace ที่ตำแหน่งทั้งหมดของการอัปเดต XrSpatialSnapshotEXT จะอยู่
time คือ XrTime ที่ตำแหน่งทั้งหมดของ XrSpatialSnapshotEXT จะอยู่

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialUpdateSnapshotCreateInfoEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
entities ต้องเป็น Pointer ไปยัง อาร์เรย์ ของ แฮนเดิล XrSpatialEntityEXT ที่ถูกต้อง entityCount
หาก componentTypeCount ไม่ใช่ 0 componentTypes ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า XrSpatialComponentTypeEXT ที่ถูกต้อง componentTypeCount
baseSpace ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง
พารามิเตอร์ entityCount ต้องมากกว่า 0
ทั้ง baseSpace และองค์ประกอบของ entities ต้องสร้าง จัดสรร หรือดึงข้อมูลจาก XrSession เดียวกัน

ทำลายสแนปชอต

ฟังก์ชัน xrDestroySpatialSnapshotEXT มีคำจำกัดความดังนี้

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

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

snapshot คือ XrSpatialSnapshotEXT ที่ได้รับก่อนหน้านี้จาก xrCreateSpatialDiscoverySnapshotCompleteEXT หรือ xrCreateSpatialUpdateSnapshotEXT

แอปพลิเคชันสามารถเรียกใช้ xrDestroySpatialSnapshotEXT เพื่อทำลายแฮนเดิล XrSpatialSnapshotEXT และทรัพยากรที่เชื่อมโยงกับแฮนเดิลดังกล่าว

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนที่จะเรียกใช้ xrDestroySpatialSnapshotEXT
snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง

ความปลอดภัยของเธรด

การเข้าถึง snapshot และแฮนเดิลย่อยทั้งหมดต้องซิงค์ภายนอก

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

สำเร็จ

XR_SUCCESS

ความล้มเหลว

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_RUNTIME_FAILURE

คอมโพเนนต์ทั่วไป

2 มิติที่ล้อมรอบ

ข้อมูลคอมโพเนนต์

โครงสร้าง XrSpatialBounded2DDataEXT มีการกำหนดไว้ดังนี้

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

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

center คือ XrPosef ที่กำหนดศูนย์กลางทางเรขาคณิตของคอมโพเนนต์ 2 มิติที่ล้อมรอบ
extents คือขอบเขตของคอมโพเนนต์ 2 มิติที่ล้อมรอบตามแกน x (extents.width) แกน y (extents.height) โดยมี center เป็นจุดศูนย์กลาง

extents ของ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT หมายถึงขนาดของเอนทิตีในระนาบ x-y ของระบบพิกัดของระนาบ ระนาบที่มีตำแหน่ง {0, 0, 0}, การหมุน {0, 0, 0, 1} (ไม่มีการหมุน) และขอบเขต {1, 1} หมายถึงระนาบขนาด 1 ม. x 1 ม. ที่อยู่ตรงกลางที่ {0, 0, 0} โดยมีเวกเตอร์ปกติของด้านหน้าชี้ไปยังทิศทาง +Z ในพื้นที่ของคอมโพเนนต์

X X Y Y Z Z Height Height Y Y Z Z X X Vertical plane Vertical plane Horizontal Plane Horizontal Plane Width Width Width Width Height Height

รูปที่ 24 ระบบพิกัดของคอมโพเนนต์ Bounded2D

หมายเหตุ

OpenXR ใช้ระนาบ X-Y โดยมี +Z เป็นเวกเตอร์ปกติของระนาบ แต่ API อื่นๆ อาจใช้ระนาบ X-Z โดยมี +Y เป็นเวกเตอร์ปกติของระนาบ ระนาบ X-Y สามารถแปลงเป็นระนาบ X-Z ได้โดยหมุน -π/2 เรเดียนรอบแกน +X

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialBounded2DDataEXT ได้

โครงสร้างรายการคอมโพเนนต์เพื่อค้นหาข้อมูล

โครงสร้าง XrSpatialComponentBounded2DListEXT มีการกำหนดไว้ดังนี้

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
boundCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ bounds
bounds เป็นอาร์เรย์ของ XrSpatialBounded2DDataEXT

รันไทม์ต้องส่งคืน XR_ERROR_VALIDATION_FAILURE จาก xrQuerySpatialComponentDataEXT หาก XrSpatialComponentBounded2DListEXT อยู่ในเชนถัดไปของ XrSpatialComponentDataQueryResultEXT :: next แต่ XrSpatialComponentDataQueryConditionEXT ::componentTypeCount ไม่เป็น 0 และ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT ไม่ได้รวมอยู่ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes

รันไทม์ต้องส่งคืน XR_ERROR_SIZE_INSUFFICIENT จาก xrQuerySpatialComponentDataEXT หาก boundCount น้อยกว่า XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput

หากสร้าง xrQuerySpatialComponentDataEXT :: snapshot จาก xrCreateSpatialDiscoverySnapshotCompleteEXT รันไทม์ต้องระบุ XrSpatialBounded2DDataEXT :: center ใน XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace และ XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time

หากสร้าง xrQuerySpatialComponentDataEXT :: snapshot จาก xrCreateSpatialUpdateSnapshotEXT รันไทม์ต้องระบุ XrSpatialBounded2DDataEXT :: center ใน XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace และ XrSpatialUpdateSnapshotCreateInfoEXT :: time

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

ต้องเปิดใช้XR_EXT_spatial_entityส่วนขยายก่อนใช้ XrSpatialComponentBounded2DListEXT
type ต้องเป็น XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
bounds ต้องเป็นตัวชี้ไปยังอาร์เรย์ของโครงสร้าง boundCount XrSpatialBounded2DDataEXT
พารามิเตอร์ boundCount ต้องมากกว่า 0

การกำหนดค่า

หากมีการแจงนับ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT ใน XrSpatialCapabilityComponentTypesEXT :: componentTypes สำหรับความสามารถบางอย่าง แอปพลิเคชันสามารถเปิดใช้ได้โดยรวมค่าแจงนับไว้ในรายการ XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents คอมโพเนนต์นี้ไม่จำเป็นต้องมีการกำหนดค่าพิเศษใดๆ เพื่อรวมไว้ในเชนถัดไปของ XrSpatialCapabilityConfigurationBaseHeaderEXT

3 มิติที่ล้อมรอบ

ข้อมูลคอมโพเนนต์

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT ใช้ XrBoxf สำหรับข้อมูล

โครงสร้างรายการคอมโพเนนต์เพื่อค้นหาข้อมูล

โครงสร้าง XrSpatialComponentBounded3DListEXT มีการกำหนดไว้ดังนี้

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
boundCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ bounds
boundsคืออาร์เรย์ของ XrBoxf

รันไทม์ต้องส่งคืน XR_ERROR_VALIDATION_FAILURE จาก xrQuerySpatialComponentDataEXT หาก XrSpatialComponentBounded3DListEXT อยู่ในเชนถัดไปของ XrSpatialComponentDataQueryResultEXT :: next แต่ XrSpatialComponentDataQueryConditionEXT ::componentTypeCount ไม่เป็น 0 และ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT ไม่ได้รวมอยู่ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes

หากสร้าง xrQuerySpatialComponentDataEXT :: snapshot จาก xrCreateSpatialDiscoverySnapshotCompleteEXT รันไทม์ต้องระบุ XrBoxf :: center ใน XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace ที่ XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time

หากสร้าง xrQuerySpatialComponentDataEXT :: snapshot จาก xrCreateSpatialUpdateSnapshotEXT รันไทม์ต้องระบุ XrBoxf :: center ใน XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace ที่ XrSpatialUpdateSnapshotCreateInfoEXT :: time

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialComponentBounded3DListEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
bounds ต้องเป็นตัวชี้ไปยังอาร์เรย์ของโครงสร้าง boundCount XrBoxf
พารามิเตอร์ boundCount ต้องมากกว่า 0

การกำหนดค่า

หากมีการแจงนับ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT ใน XrSpatialCapabilityComponentTypesEXT :: componentTypes สำหรับความสามารถบางอย่าง แอปพลิเคชันสามารถเปิดใช้ได้โดยรวมการแจงนับไว้ในรายการ XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents คอมโพเนนต์นี้ไม่จำเป็นต้องมีการกำหนดค่าพิเศษใดๆ เพื่อรวมไว้ในเชนถัดไปของ XrSpatialCapabilityConfigurationBaseHeaderEXT

ผู้ปกครอง

ข้อมูลคอมโพเนนต์

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT ใช้ XrSpatialEntityIdEXT สำหรับข้อมูล

โครงสร้างรายการคอมโพเนนต์เพื่อค้นหาข้อมูล

โครงสร้าง XrSpatialComponentParentListEXT มีการกำหนดไว้ดังนี้

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
parentCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ parents
parents เป็นอาร์เรย์ของ XrSpatialEntityIdEXT

รันไทม์ต้องส่งคืน XR_ERROR_VALIDATION_FAILURE จาก xrQuerySpatialComponentDataEXT หาก XrSpatialComponentParentListEXT อยู่ในเชนถัดไปของ XrSpatialComponentDataQueryResultEXT :: next แต่ XrSpatialComponentDataQueryConditionEXT ::componentTypeCount ไม่เป็น 0 และ XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT ไม่ได้รวมอยู่ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes

รันไทม์ต้องส่งคืน XR_ERROR_SIZE_INSUFFICIENT จาก xrQuerySpatialComponentDataEXT หาก parentCount น้อยกว่า XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialComponentParentListEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
parents ต้องเป็นตัวชี้ไปยังอาร์เรย์ของค่า parentCount XrSpatialEntityIdEXT
พารามิเตอร์ parentCount ต้องมากกว่า 0

การกำหนดค่า

หากมีการแจงนับ XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT ใน XrSpatialCapabilityComponentTypesEXT :: componentTypes สำหรับความสามารถบางอย่าง แอปพลิเคชันสามารถเปิดใช้ได้โดยรวมการแจงนับไว้ในรายการ XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents คอมโพเนนต์นี้ไม่จำเป็นต้องมีการกำหนดค่าพิเศษใดๆ เพื่อรวมไว้ในเชนถัดไปของ XrSpatialCapabilityConfigurationBaseHeaderEXT

Mesh 3 มิติ

ข้อมูลคอมโพเนนต์

โครงสร้าง XrSpatialMeshDataEXT มีคำจำกัดความดังนี้

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

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

origin คือ XrPosef ที่กำหนดต้นทางของตาข่าย จุดยอดทั้งหมดของตาข่ายต้องสัมพันธ์กับจุดเริ่มต้นนี้
vertexBuffer คือ XrSpatialBufferEXT ที่ระบุรหัสสำหรับบัฟเฟอร์ที่แสดงถึงบัฟเฟอร์จุดยอดของเอนทิตีที่คอมโพเนนต์นี้อยู่ ตำแหน่งของจุดยอดต้องสัมพันธ์กับ origin
indexBuffer คือ XrSpatialBufferEXT ที่ให้รหัสสำหรับบัฟเฟอร์ที่แสดงอาร์เรย์ของดัชนีสามเหลี่ยม โดยระบุดัชนีของจุดยอดของตาข่ายใน vertexBuffer ดัชนีสามเหลี่ยมต้องส่งคืนตามลำดับทวนเข็มนาฬิกา และดัชนี 3 รายการจะแสดงถึงสามเหลี่ยม 1 รูป

ประเภทคอมโพเนนต์ที่ใช้ XrSpatialMeshDataEXT ต้องระบุ XrSpatialBufferTypeEXT ของ vertexBuffer และ indexBuffer

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

ต้องเปิดใช้XR_EXT_spatial_entityส่วนขยายก่อนใช้ XrSpatialMeshDataEXT
vertexBuffer ต้องเป็นโครงสร้าง XrSpatialBufferEXT ที่ถูกต้อง
indexBuffer ต้องเป็นโครงสร้าง XrSpatialBufferEXT ที่ถูกต้อง

โครงสร้างรายการคอมโพเนนต์เพื่อค้นหาข้อมูล

โครงสร้าง XrSpatialComponentMesh3DListEXT มีการกำหนดไว้ดังนี้

typedef struct XrSpatialComponentMesh3DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh3DListEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
meshCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ meshes
meshes เป็นอาร์เรย์ของ XrSpatialMeshDataEXT

แอปพลิเคชันสามารถค้นหาคอมโพเนนต์ 3 มิติของเมชของเอนทิตีเชิงพื้นที่ใน XrSpatialSnapshotEXT ได้โดยการเพิ่ม XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes และเพิ่ม XrSpatialComponentMesh3DListEXT ลงในห่วงโซ่พอยน์เตอร์ถัดไปของ XrSpatialComponentDataQueryResultEXT

รันไทม์ต้องส่งคืน XR_ERROR_VALIDATION_FAILURE จาก xrQuerySpatialComponentDataEXT หาก XrSpatialComponentMesh3DListEXT อยู่ในเชนถัดไปของ XrSpatialComponentDataQueryResultEXT :: next แต่ XrSpatialComponentDataQueryConditionEXT ::componentTypeCount ไม่เป็น 0 และ XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT ไม่ได้รวมอยู่ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes

รันไทม์ต้องส่งคืน XR_ERROR_SIZE_INSUFFICIENT จาก xrQuerySpatialComponentDataEXT หาก meshCount น้อยกว่า XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput

สำหรับ XrSpatialMeshDataEXT ที่รันไทม์กรอกในอาร์เรย์ meshes XrSpatialBufferEXT :: bufferType สำหรับ XrSpatialMeshDataEXT :: vertexBuffer ต้องเป็น XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT และ XrSpatialBufferEXT :: bufferType สำหรับ XrSpatialMeshDataEXT :: indexBuffer ต้องเป็น XR_SPATIAL_BUFFER_TYPE_UINT32_EXT

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialComponentMesh3DListEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
meshes must be a pointer to an array of meshCount XrSpatialMeshDataEXT structures
พารามิเตอร์ meshCount ต้องมากกว่า 0

การกำหนดค่า

หากมีการแจงนับ XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT ใน XrSpatialCapabilityComponentTypesEXT :: componentTypes สำหรับความสามารถบางอย่าง แอปพลิเคชันสามารถเปิดใช้ได้โดยรวมการแจงนับไว้ในรายการ XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents ของโครงสร้างที่ได้จาก XrSpatialCapabilityConfigurationBaseHeaderEXT ของความสามารถที่รองรับคอมโพเนนต์นี้

คอมโพเนนต์นี้ไม่จำเป็นต้องมีการกำหนดค่าพิเศษใดๆ เพื่อรวมไว้ในเชนถัดไปของ XrSpatialCapabilityConfigurationBaseHeaderEXT

ตัวกรองสถานะการติดตาม

โครงสร้าง XrSpatialFilterTrackingStateEXT มีคำจำกัดความดังนี้

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

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

type คือ XrStructureType ของโครงสร้างนี้
next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
trackingState คือ XrSpatialEntityTrackingStateEXT ที่แอปพลิเคชันต้องการใช้ตัวกรอง

แอปพลิเคชันสามารถใช้ XrSpatialFilterTrackingStateEXT ในเชนถัดไปของ XrSpatialDiscoverySnapshotCreateInfoEXT เพื่อกำหนดขอบเขตการค้นหาให้เฉพาะเอนทิตีที่มีสถานะการติดตามเป็น trackingState

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

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนจึงจะใช้ XrSpatialFilterTrackingStateEXT ได้
type ต้องเป็น XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
trackingState ต้องเป็นค่า XrSpatialEntityTrackingStateEXT ที่ถูกต้อง

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

การใช้งานแอปพลิเคชัน

โดยทั่วไปแล้ว แอปพลิเคชันจะใช้ส่วนขยายเอนทิตีเชิงพื้นที่ในรูปแบบต่อไปนี้

แอปพลิเคชันจะแจงนับความสามารถเชิงพื้นที่ของระบบก่อนโดยใช้ xrEnumerateSpatialCapabilitiesEXT จากนั้นจะตรวจสอบอาร์เรย์ของ XrSpatialCapabilityEXT ที่ส่งคืน และแจงนับคอมโพเนนต์และฟีเจอร์ที่รองรับสำหรับความสามารถแต่ละอย่างโดยใช้ xrEnumerateSpatialCapabilityComponentTypesEXT และ xrEnumerateSpatialCapabilityFeaturesEXT ตามลำดับ ซึ่งจะช่วยให้แอปพลิเคชันเห็นภาพรวมของคอมโพเนนต์ที่เปิดใช้ได้และการกำหนดค่าที่ความสามารถยอมรับ
จากนั้นแอปพลิเคชันจะสร้างแฮนเดิล XrSpatialContextEXT อย่างน้อย 1 รายการที่มีการกำหนดค่าความสามารถเชิงพื้นที่ที่เฉพาะเจาะจง ซึ่งการกำหนดค่าจะเปิดใช้และกำหนดค่าความสามารถที่เฉพาะเจาะจงในบริบทเชิงพื้นที่ รวมถึงเปิดใช้และกำหนดค่าคอมโพเนนต์สำหรับความสามารถเหล่านั้น
สำหรับ XrSpatialContextEXT แต่ละรายการ แอปพลิเคชันจะรอรับเหตุการณ์ XrEventDataSpatialDiscoveryRecommendedEXT สำหรับ XrSpatialContextEXT นั้นก่อนที่จะใช้ xrCreateSpatialDiscoverySnapshotAsyncEXT เพื่อค้นหาเอนทิตีเชิงพื้นที่ เมื่อการดำเนินการแบบไม่พร้อมกันนี้เสร็จสมบูรณ์แล้ว แอปพลิเคชันจะได้รับแฮนเดิล XrSpatialSnapshotEXT
แอปพลิเคชันจะค้นหาเอนทิตีและข้อมูลคอมโพเนนต์ที่รวมอยู่ใน XrSpatialSnapshotEXT นี้โดยใช้ xrQuerySpatialComponentDataEXT แอปพลิเคชันจะอ่านข้อมูลคอมโพเนนต์ล่าสุดของเอนทิตีที่ค้นหาจากโครงสร้างที่แนบมากับเชนถัดไปของ XrSpatialComponentDataQueryResultEXT หากสถานะของเอนทิตีเป็น XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT
หากมีเอนทิตีที่เฉพาะเจาะจงซึ่งแอปพลิเคชันระบุว่าน่าสนใจและต้องการรับข้อมูลอัปเดตเมื่อเวลาผ่านไป แอปพลิเคชันจะสร้างแฮนเดิล XrSpatialEntityEXT สำหรับเอนทิตีเหล่านั้นโดยใช้ xrCreateSpatialEntityFromIdEXT แอปพลิเคชันจะได้รับการอัปเดตสำหรับเอนทิตีที่น่าสนใจดังกล่าวโดยใช้ xrCreateSpatialUpdateSnapshotEXT และใช้ฟังก์ชัน xrQuerySpatialComponentDataEXT เดียวกันใน XrSpatialSnapshotEXT ที่สร้างขึ้นใหม่เพื่อรับข้อมูลคอมโพเนนต์ล่าสุดสำหรับเอนทิตีเหล่านั้น

ค้นพบเอนทิตีเชิงพื้นที่และค้นหาข้อมูลคอมโพเนนต์

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

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

auto waitUntilReady = [](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&fooConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components.
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT future = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT;
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = &componentToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

ข้อมูลบัฟเฟอร์การค้นหา

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีรับข้อมูลของคอมโพเนนต์ที่ให้ XrSpatialBufferEXT

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

หลักเกณฑ์ของส่วนขยาย

หากส่วนขยายกําลังกําหนด XrSpatialComponentTypeEXT ใหม่ซึ่งให้ข้อมูลเพิ่มเติมเกี่ยวกับเอนทิตีเชิงพื้นที่
- ส่วนขยายต้องกำหนดโครงสร้างรายการสำหรับคอมโพเนนต์นั้นด้วย ซึ่งจะช่วยให้แอปพลิเคชันส่งอาร์เรย์ไปยังรันไทม์เพื่อป้อนข้อมูลสำหรับเอนทิตีเชิงพื้นที่แต่ละรายการที่ตรงตาม xrQuerySpatialComponentDataEXT :: queryCondition ตัวอย่างโครงสร้างรายการดังกล่าว ได้แก่ XrSpatialComponentParentListEXT และ XrSpatialComponentBounded2DListEXT หากขนาดข้อมูลของคอมโพเนนต์เปลี่ยนแปลงได้และต้องใช้แอปพลิเคชันเพื่อใช้รูปแบบการเรียก 2 ครั้งเพื่อค้นหาข้อมูลดังกล่าว ข้อมูลของคอมโพเนนต์ควรระบุ XrSpatialBufferEXT สำหรับข้อมูลแต่ละรายการที่มีขนาดเปลี่ยนแปลงได้ในโครงสร้างรายการ และต้องระบุ XrSpatialBufferTypeEXT สำหรับแต่ละบัฟเฟอร์ จากนั้นแอปพลิเคชันจะค้นหาข้อมูลบัฟเฟอร์ได้โดยใช้ฟังก์ชันที่กำหนดไว้ในรูปแบบการเรียก 2 ครั้งสำหรับข้อมูลคอมโพเนนต์ ตัวอย่างของโครงสร้างดังกล่าวคือ XrSpatialMeshDataEXT ซึ่งรวมอยู่ใน XrSpatialComponentMesh3DListEXT
- ส่วนขยายสามารถให้โครงสร้างที่แอปพลิเคชันสามารถเชื่อมโยงกับ XrSpatialComponentDataQueryConditionEXT :: next เพื่อให้ตัวกรองเพิ่มเติมสำหรับการค้นหาที่เกี่ยวข้องกับข้อมูลของคอมโพเนนต์นี้
ส่วนขยายสามารถกำหนดโครงสร้างที่ขยาย XrSpatialDiscoverySnapshotCreateInfoEXT เพื่อให้ตัวกรองเพิ่มเติมสำหรับการค้นพบ ตัวกรองสำหรับการสร้างสแนปชอตต้องไม่ส่งผลต่อการกำหนดค่าของบริบทเชิงพื้นที่ แต่ควรใช้เพื่อเป็นคำแนะนำแก่รันไทม์เกี่ยวกับเอนทิตีและข้อมูลที่จะรวมไว้ในสแนปชอตตามที่กำหนดค่าปัจจุบันของบริบทเชิงพื้นที่ติดตาม (และด้วยเหตุนี้จึงเป็นการกำหนดค่าปัจจุบันของบริการพื้นฐาน)
หากส่วนขยายกำหนด XrSpatialCapabilityEXT ใหม่
- นอกจากนี้ ควรระบุรายการ XrSpatialComponentTypeEXT ที่รันไทม์ต้องระบุในเอนทิตีสำหรับความสามารถนั้นด้วย
- นอกจากนี้ ต้องมีโครงสร้างที่ได้จาก XrSpatialCapabilityConfigurationBaseHeaderEXT ซึ่งจะช่วยให้กำหนดค่าความสามารถนั้นได้
หากส่วนขยายกำหนด XrSpatialCapabilityFeatureEXT ใหม่ ส่วนขยายนั้นต้องกำหนดโครงสร้างการกำหนดค่าที่สอดคล้องกันซึ่งสามารถเชื่อมโยงกับพอยน์เตอร์ถัดไปของ XrSpatialCapabilityConfigurationBaseHeaderEXT ได้ด้วย เพื่อให้แอปพลิเคชันสามารถใช้เพื่อเปิดใช้ฟีเจอร์เมื่อสร้าง XrSpatialContextEXT
ส่วนขยายที่กำหนด XrSpatialCapabilityEXT ใหม่ควรทำตามเทมเพลตนี้สำหรับข้อกำหนด
- ภาพรวม
- การรองรับรันไทม์
- การกำหนดค่า
- คอมโพเนนต์ที่รับประกัน
- โค้ดตัวอย่าง
ส่วนขยายที่กำหนด XrSpatialComponentTypeEXT ใหม่ควรทำตามเทมเพลตนี้สำหรับข้อกำหนด
- ข้อมูลคอมโพเนนต์
- โครงสร้างรายการคอมโพเนนต์เพื่อค้นหาข้อมูล
- การกำหนดค่า
เมื่อเขียน API ที่ให้ XrSpatialBufferIdEXT แก่แอปพลิเคชัน API นั้นต้องมาพร้อมกับ XrSpatialBufferTypeEXT เพื่อแจ้งให้แอปพลิเคชันทราบว่าบัฟเฟอร์มีประเภทข้อมูลใด และแอปพลิเคชันสามารถใช้ฟังก์ชัน xrGetSpatialBuffer* ที่เหมาะสมเพื่อดึงเนื้อหาจริงของบัฟเฟอร์ได้

หลักเกณฑ์การออกแบบและการขยายป้ายกำกับเชิงความหมาย

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

หากส่วนขยายกําลังกําหนดป้ายกํากับเชิงความหมายสําหรับ XrSpatialCapabilityEXT ใดๆ ส่วนขยายควรทําเช่นนั้นโดยการกําหนด XrSpatialComponentTypeEXT ใหม่ รวมถึงการแจงนับใหม่ที่มีชุดป้ายกํากับ ("ชุดป้ายกํากับเชิงความหมาย") เพื่อให้เป็นข้อมูลสําหรับคอมโพเนนต์นั้น
การแจงนับที่แสดงชุดป้ายกำกับเชิงความหมายต้องมีค่าเพื่อระบุว่าระบบไม่ได้จัดหมวดหมู่เอนทิตีเป็นป้ายกำกับใดๆ ในชุดนี้ ชื่อของรายการนี้ต้องมี "UNCATEGORIZED" เช่น XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT ค่านี้จะระบุให้แอปพลิเคชันทราบว่ารันไทม์รู้จักเอนทิตีนี้ แต่มีชุดป้ายกำกับเชิงความหมายอื่นๆ ที่มีการจัดหมวดหมู่เอนทิตีนี้
การแจงนับ XrSpatialComponentTypeEXT ที่กำหนดขึ้นใหม่นี้ใน xrEnumerateSpatialCapabilityComponentTypesEXT หมายความว่ารันไทม์รองรับชุดป้ายกำกับเชิงความหมาย (และป้ายกำกับที่กำหนดไว้ในชุดนั้น) ที่สอดคล้องกับประเภทคอมโพเนนต์นั้น
แอปพลิเคชันแสดงความต้องการที่จะค้นหาเอนทิตีที่มีป้ายกำกับซึ่งอยู่ในชุดป้ายกำกับเชิงความหมายนี้โดยการรวม XrSpatialComponentTypeEXT ที่เกี่ยวข้องไว้ใน XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents อาร์เรย์ของโครงสร้างการกำหนดค่าสำหรับความสามารถที่ประเภทคอมโพเนนต์มีการแจงนับ
เป็นไปได้ที่เอนทิตีเชิงพื้นที่เดียวจะมีคอมโพเนนต์หลายรายการ โดยแต่ละรายการจะมีป้ายกำกับจากชุดป้ายกำกับเชิงความหมายของตนเอง ลองพิจารณาตัวอย่างต่อไปนี้ที่มีชุดป้ายกำกับเชิงความหมายสมมติบางชุด - XrSpatialObjectSemanticLabel ซึ่งอาจมีค่าต่างๆ เช่น เก้าอี้ โซฟา โต๊ะ ฯลฯ XrSpatialSofaBrand ซึ่งอาจมีค่า เช่น IKEA, Wayfair เป็นต้น และ XrSpatialIkeaSofa ซึ่งอาจมีชื่อรุ่นโซฟาของ IKEA โดยเฉพาะ ในสถานการณ์นี้ เอนทิตีโซฟาเดียวกันมีคอมโพเนนต์ทั้ง 3 รายการ (ป้ายกำกับจากชุดป้ายกำกับเชิงความหมายทั้ง 3 ชุด) โดยแต่ละรายการให้ข้อมูลเกี่ยวกับเอนทิตีที่มีระดับความละเอียดต่างกัน
หากส่วนขยายกําลังกําหนด XrSpatialComponentTypeEXT ใหม่ซึ่งมีชุดป้ายกํากับเชิงความหมายใหม่ที่มีป้ายกํากับหลายรายการนอกเหนือจากป้ายกํากับ UNCATEGORIZED ส่วนขยายควรพิจารณากําหนด XrSpatialCapabilityFeatureEXT ซึ่งอนุญาตให้แอปพลิเคชันเปิดใช้งานเฉพาะชุดย่อยของป้ายกํากับที่กําหนดไว้ในชุดป้ายกํากับเชิงความหมายที่สอดคล้องกับประเภทคอมโพเนนต์นั้น ชุดย่อยนี้ซึ่งระบุไว้ในห่วงโซ่ถัดไปของการกำหนดค่าความสามารถ จะทำหน้าที่เป็นคำแนะนำสำหรับรันไทม์ในการเพิ่มประสิทธิภาพไปป์ไลน์การติดตามและติดตามเฉพาะชุดย่อยที่ระบุ ตัวอย่างโครงสร้างฟีเจอร์ดังกล่าวแสดงอยู่ด้านล่าง
ส่วนขยายต้องไม่เพิ่มป้ายกำกับลงในการแจงนับชุดป้ายกำกับเชิงความหมายที่มีอยู่ แต่ต้องกำหนดการแจงนับใหม่ซึ่งมีการแจงนับที่เทียบเท่ากันโดยมีความหมายเหมือนกันและมีค่าเท่ากับค่าจากการแจงนับชุดอื่น นอกเหนือจากการแจงนับที่เพิ่มใหม่ ข้อมูลจำเพาะของชุดป้ายกำกับความหมายที่กำหนดใหม่ต้องสร้างการแมประหว่างชุดป้ายกำกับเก่ากับชุดป้ายกำกับใหม่ด้วย ดูตัวอย่างด้านล่าง

ตัวอย่างคำจำกัดความของฟีเจอร์เชิงพื้นที่สำหรับชุดย่อยของป้ายกำกับความหมาย

// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;

ตัวอย่างส่วนขยายป้ายกำกับความหมายเชิงพื้นที่

typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

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

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====

ประเภทฐานใหม่

XrSpatialBufferIdEXT
XrSpatialEntityIdEXT

ประเภทออบเจ็กต์ใหม่

XrSpatialContextEXT
XrSpatialEntityEXT
XrSpatialSnapshotEXT

คำสั่งใหม่

xrCreateSpatialContextAsyncEXT
xrCreateSpatialContextCompleteEXT
xrCreateSpatialDiscoverySnapshotAsyncEXT
xrCreateSpatialDiscoverySnapshotCompleteEXT
xrCreateSpatialEntityFromIdEXT
xrCreateSpatialUpdateSnapshotEXT
xrDestroySpatialContextEXT
xrDestroySpatialEntityEXT
xrDestroySpatialSnapshotEXT
xrEnumerateSpatialCapabilitiesEXT
xrEnumerateSpatialCapabilityComponentTypesEXT
xrEnumerateSpatialCapabilityFeaturesEXT
xrGetSpatialBufferFloatEXT
xrGetSpatialBufferStringEXT
xrGetSpatialBufferUint16EXT
xrGetSpatialBufferUint32EXT
xrGetSpatialBufferUint8EXT
xrGetSpatialBufferVector2fEXT
xrGetSpatialBufferVector3fEXT
xrQuerySpatialComponentDataEXT

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

XrCreateSpatialContextCompletionEXT
XrCreateSpatialDiscoverySnapshotCompletionEXT
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
XrEventDataSpatialDiscoveryRecommendedEXT
XrSpatialBounded2DDataEXT
XrSpatialBufferEXT
XrSpatialBufferGetInfoEXT
XrSpatialCapabilityComponentTypesEXT
XrSpatialCapabilityConfigurationBaseHeaderEXT
XrSpatialComponentDataQueryConditionEXT
XrSpatialComponentDataQueryResultEXT
XrSpatialContextCreateInfoEXT
XrSpatialDiscoverySnapshotCreateInfoEXT
XrSpatialEntityFromIdCreateInfoEXT
XrSpatialMeshDataEXT
XrSpatialUpdateSnapshotCreateInfoEXT
การขยาย XrSpatialComponentDataQueryResultEXT :
การขยาย XrSpatialDiscoverySnapshotCreateInfoEXT , XrSpatialComponentDataQueryConditionEXT :
- XrSpatialFilterTrackingStateEXT

Enum ใหม่

XrSpatialBufferTypeEXT
XrSpatialCapabilityEXT
XrSpatialCapabilityFeatureEXT
XrSpatialComponentTypeEXT
XrSpatialEntityTrackingStateEXT

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

XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
XR_EXT_spatial_entity_SPEC_VERSION
การขยาย XrObjectType :
- XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
- XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
- XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT
การขยาย XrResult :
- XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
- XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
- XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
- XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
- XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
- XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
การขยาย XrStructureType :
- XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
- XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
- XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
- XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
- XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
- XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
- XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
- XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
- XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
- XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
- XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
- XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
- XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
- XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
- XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
- XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
- XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT

ปัญหา

เอนทิตีเดียวจะมาจากความสามารถเดียวเสมอไปไหม
- แก้ไขแล้ว
- คำตอบ: ไม่ได้ โดยขึ้นอยู่กับรันไทม์ทั้งหมดตามความสามารถในการติดตามของตัวเองและวิธีที่ต้องการแสดงเอนทิตีที่ตรวจพบ ข้อกำหนดไม่ได้กำหนดการแสดงเอนทิตีเชิงพื้นที่ใดๆ โดยเฉพาะ ยกเว้นคอมโพเนนต์ที่รับประกันของความสามารถที่กำหนดเพื่อตั้งค่าความคาดหวังขั้นต่ำ รันไทม์อาจผสานรวมเอนทิตีที่ตรวจพบโดยความสามารถแยกกัน และแสดงเป็นเอนทิตีเดียวที่มีคอมโพเนนต์ที่รับประกันของความสามารถทั้งหมดที่ช่วยระบุเอนทิตีนั้น ตัวอย่างเช่น ตารางสามารถตรวจจับได้ทั้งความสามารถในการติดตามระนาบและความสามารถในการติดตามออบเจ็กต์ โดยการติดตามระนาบจะให้คอมโพเนนต์ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT ในเอนทิตี และการติดตามออบเจ็กต์จะให้ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT รันไทม์บางรายการอาจแสดงตารางเป็น 2 เอนทิตีแยกกัน โดยแต่ละเอนทิตีจะมีชุดคอมโพเนนต์ที่รับประกันของตัวเอง ในขณะที่รันไทม์บางรายการอาจแสดงเพียง 1 เอนทิตีเพื่อแสดงตาราง และมีทั้ง XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT และ XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT ในเอนทิตีเดียวกัน สิ่งที่ควรทราบในที่นี้คือเอนทิตีเชิงพื้นที่หนึ่งๆ จะมีคอมโพเนนต์ได้สูงสุด 1 รายการของประเภทคอมโพเนนต์ใดก็ได้ ดังนั้น หากข้อมูลคอมโพเนนต์ที่สร้างขึ้นโดยความสามารถต่างๆ ขัดแย้งกันสำหรับเอนทิตีหนึ่งๆ รันไทม์ต้องแสดงข้อมูลเหล่านั้นเป็น 2 เอนทิตีแยกกัน

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

ฉบับแก้ไขที่ 1, 12-04-2024 (Nihav Jain, Google)
- คำอธิบายส่วนขยายเริ่มต้น