Android XR for OpenXR | Android Developers

งาน Android Dev Summit กลับมาอีกครั้งพร้อม เซสชันสำหรับ Android XR โดยเฉพาะ ลองฟัง ลองใช้ และส่งความคิดเห็นถึงเรา

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

XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

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

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

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

741

การแก้ไข

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

ให้สัตยาบัน

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

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

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

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

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

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

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

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

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

เอนทิตีเชิงพื้นที่ใน 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_GEOMETRY_POINT_ANDROID = 1000803000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1 = 1000808000,
    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

คอมโพเนนต์ที่ระบุ enum การจัดแนวระนาบสำหรับเอนทิตีเชิงพื้นที่ โครงสร้างรายการที่เกี่ยวข้องคือ 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

คอมโพเนนต์ที่ระบุท่าทางของการชนแบบ Raycast ในเอนทิตี โครงสร้างรายการที่เกี่ยวข้องคือ 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

คอมโพเนนต์ที่ระบุมิติข้อมูลและประเภทห้องของ Shoebox โดยโครงสร้างรายการที่เกี่ยวข้องคือ 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

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

XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID

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

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1

คอมโพเนนต์ที่อธิบายขอบเขตความคงอยู่ซึ่งเอนทิตีจะคงอยู่ หากรันไทม์รองรับ XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT รันไทม์ต้องรองรับคอมโพเนนต์นี้ด้วย โครงสร้างข้อมูลที่เกี่ยวข้องคือ XrSpatialBufferEXT โครงสร้างรายการที่เกี่ยวข้องคือ XrSpatialComponentPersistenceScopeDataListANDROIDX1 (เพิ่มโดยส่วนขยาย XR_ANDROIDX1_spatial_anchor_cloud_sharing)

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

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

ความสามารถในการตรวจจับและติดตาม Micro คิวอาร์โค้ด (เพิ่มโดยส่วนขยาย 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

ความสามารถในการสร้าง 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

เรขาคณิตของ Streetscape (เพิ่มโดยส่วนขยาย 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 สามารถเป็น NULL ได้หาก capabilityCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด capabilities ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

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

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

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนเรียกใช้ xrEnumerateSpatialCapabilitiesEXT
instance ต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง
capabilityCountOutput ต้องเป็นตัวชี้ไปยังค่า 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 สำหรับแอปพลิเคชันนั้น

รันไทม์ต้องแสดงผล 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 สามารถเป็น NULL ได้หาก componentTypeCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด componentTypes ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนใช้ XrSpatialCapabilityComponentTypesEXT
type ต้องเป็น XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
หาก componentTypeCapacityInput ไม่ใช่ 0 componentTypes ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า 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 สามารถเป็น NULL ได้หาก capabilityFeatureCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด capabilityFeatures ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

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

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

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

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

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนเรียกใช้ xrEnumerateSpatialCapabilityFeaturesEXT
instance ต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง
capability ต้องเป็นค่า XrSpatialCapabilityEXT ที่ถูกต้อง
capabilityFeatureCountOutput ต้องเป็นตัวชี้ไปยังค่า uint32_t
หาก capabilityFeatureCapacityInput ไม่ใช่ 0 capabilityFeatures ต้องเป็นพอยเตอร์ไปยังอาร์เรย์ของค่า 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 เป็นตัวชี้ไปยัง XrFutureEXT

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

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

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

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

รันไทม์ต้องแสดงผล 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 ซึ่งใช้ได้เมื่อ Future จากฟังก์ชันนี้อยู่ในสถานะ 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
XR_ERROR_TIME_INVALID (หากเปิดใช้ XR_ANDROID_spatial_annotation_tracking)

โครงสร้าง 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 ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของโครงสร้างที่อิงตาม XrSpatialCapabilityConfigurationBaseHeaderEXT ที่ถูกต้อง capabilityConfigCount รายการ ดูเพิ่มเติม: XrSpatialCapabilityConfigurationAnchorEXT , XrSpatialCapabilityConfigurationAnnotationTrackingANDROID , 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 ต้องเป็นตัวชี้ไปยังอาร์เรย์ของค่า XrSpatialComponentTypeEXT ที่ถูกต้อง enabledComponentCount ค่า
พารามิเตอร์ enabledComponentCount ต้องมากกว่า 0

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

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

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

session คือ XrSession ที่ส่งไปยัง xrCreateSpatialContextAsyncEXT :: session ก่อนหน้านี้
future คือ XrFutureEXT ที่ได้รับจาก xrCreateSpatialContextAsyncEXT
completion เป็นตัวชี้ไปยัง 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 เป็นตัวชี้ไปยังโครงสร้าง 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 ต้องเป็นตัวชี้ไปยังแฮนเดิล 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 เป็นตัวชี้ไปยัง XrSpatialDiscoverySnapshotCreateInfoEXT
future เป็นตัวชี้ไปยัง XrFutureEXT

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

ฟังก์ชันนี้จะเริ่มการดำเนินการแบบอะซิงโครนัสและสร้าง XrFutureEXT ที่เกี่ยวข้อง ซึ่งใช้ได้กับ xrPollFutureEXT และฟังก์ชันที่เกี่ยวข้อง ค่าที่แสดงผลของฟังก์ชันนี้จะระบุเฉพาะว่าพารามิเตอร์ยอมรับได้หรือไม่ในการกำหนดเวลาการดำเนินการแบบอะซิงโครนัส ฟังก์ชันการดำเนินการให้เสร็จสมบูรณ์ที่เกี่ยวข้องคือ xrCreateSpatialDiscoverySnapshotCompleteEXT ซึ่งใช้ได้เมื่อ Future จากฟังก์ชันนี้อยู่ในสถานะ 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 ต้องเป็นตัวชี้ไปยังโครงสร้าง 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 , XrSpatialDiscoveryPersistenceContextFilterANDROIDX1 , XrSpatialDiscoveryPersistenceUuidFilterEXT , XrSpatialDiscoveryRoomBoundaryFilterANDROIDSYS , XrSpatialDiscoveryUniqueEntitiesFilterANDROID , XrSpatialFilterTrackingStateEXT , XrSpatialRaycastInfoANDROID
หาก componentTypeCount ไม่ใช่ 0 componentTypes ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า XrSpatialComponentTypeEXT ที่ถูกต้อง componentTypeCount ค่า

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

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

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

spatialContext คือ XrSpatialContextEXT ที่ส่งไปยัง xrCreateSpatialDiscoverySnapshotAsyncEXT :: spatialContext ก่อนหน้านี้
createSnapshotCompletionInfo เป็นตัวชี้ไปยัง XrCreateSpatialDiscoverySnapshotCompletionInfoEXT ซึ่งให้ข้อมูลเกี่ยวกับความสมบูรณ์ของคำขอสร้างสแนปชอตการค้นพบ
completion เป็นตัวชี้ไปยัง 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 ต้องเป็นตัวชี้ไปยังโครงสร้าง 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 เป็นตัวชี้ไปยังโครงสร้าง XrSpatialComponentDataQueryConditionEXT
queryResult เป็นตัวชี้ไปยังโครงสร้าง XrSpatialComponentDataQueryResultEXT

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

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

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

หาก XrEventDataReferenceSpaceChangePending อยู่ในคิวและ XrEventDataReferenceSpaceChangePending :: changeTime ผ่านไปขณะที่แอปพลิเคชันกำลังค้นหาข้อมูลคอมโพเนนต์จาก 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 Text is not SVG - cannot display

รูปที่ 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 ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า 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 สามารถเป็น NULL ได้หาก entityIdCapacityInput เป็น 0
entityStateCapacityInput คือความจุของอาร์เรย์ entityStates หรือ 0 เพื่อระบุคำขอให้ดึงข้อมูลความจุที่จำเป็น
entityStateCountOutput คือจำนวนของ XrSpatialEntityTrackingStateEXT ใน entityStates หรือความจุที่จำเป็นในกรณีที่ entityStateCapacityInput ไม่เพียงพอ ต้องเหมือนกับ entityIdCountOutput เสมอ
entityStates คืออาร์เรย์ของ XrSpatialEntityTrackingStateEXT สามารถเป็น NULL ได้หาก entityStateCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด 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 , XrSpatialComponentPersistenceScopesListANDROIDX1 , XrSpatialComponentPlaneAlignmentListEXT , XrSpatialComponentPlaneSemanticLabelListEXT , XrSpatialComponentPolygon2DListEXT , XrSpatialComponentRaycastResultListANDROID , XrSpatialComponentRoomEmptinessListANDROIDSYS , XrSpatialComponentRoomListANDROIDSYS , XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 , XrSpatialComponentSubsumedByListANDROID
หาก entityIdCapacityInput ไม่ใช่ 0 entityIds ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า entityIdCapacityInput XrSpatialEntityIdEXT
หาก entityStateCapacityInput ไม่ใช่ 0 , entityStates ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า 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

คำอธิบาย Enumerant

XR_SPATIAL_BUFFER_TYPE_STRING_EXT XrSpatialBufferIdEXT สามารถส่งไปยัง xrGetSpatialBufferStringEXT เพื่อดึงบัฟเฟอร์สตริงได้
XR_SPATIAL_BUFFER_TYPE_UINT8_EXT คุณสามารถส่ง XrSpatialBufferIdEXT ไปยัง xrGetSpatialBufferUint8EXT เพื่อดึงข้อมูลบัฟเฟอร์ uint8_t ได้
XR_SPATIAL_BUFFER_TYPE_UINT16_EXT XrSpatialBufferIdEXT สามารถส่งไปยัง xrGetSpatialBufferUint16EXT เพื่อดึงข้อมูลบัฟเฟอร์ uint16_t ได้
XR_SPATIAL_BUFFER_TYPE_UINT32_EXT คุณสามารถส่ง XrSpatialBufferIdEXT ไปยัง xrGetSpatialBufferUint32EXT เพื่อดึงข้อมูลบัฟเฟอร์ uint32_t ได้
XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT XrSpatialBufferIdEXT สามารถส่งไปยัง 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 เป็นแฮนเดิลของ XrSpatialSnapshotEXT
info เก็บข้อมูลในบัฟเฟอร์เพื่อค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอให้ดึงข้อมูลความจุที่จำเป็น
bufferCountOutput คือจำนวนอักขระหรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ char สามารถเป็น NULL ได้หาก bufferCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด 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 ที่สิ้นสุดด้วยค่า Null

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

ต้องเปิดใช้ส่วนขยาย XR_EXT_spatial_entity ก่อนเรียกใช้ xrGetSpatialBufferStringEXT
snapshot ต้องเป็นแฮนเดิล XrSpatialSnapshotEXT ที่ถูกต้อง
info ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSpatialBufferGetInfoEXT ที่ถูกต้อง
bufferCountOutput ต้องเป็นตัวชี้ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่าอักขระ 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

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

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

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

snapshot เป็นแฮนเดิลของ XrSpatialSnapshotEXT
info เก็บข้อมูลในบัฟเฟอร์เพื่อค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอให้ดึงข้อมูลความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ uint8_t สามารถเป็น NULL ได้หาก bufferCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด 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 ต้องเป็นตัวชี้ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า 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 เป็นแฮนเดิลของ XrSpatialSnapshotEXT
info เก็บข้อมูลในบัฟเฟอร์เพื่อค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอให้ดึงข้อมูลความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ uint16_t สามารถเป็น NULL ได้หาก bufferCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด 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 ต้องเป็นตัวชี้ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า 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 เป็นแฮนเดิลของ XrSpatialSnapshotEXT
info เก็บข้อมูลในบัฟเฟอร์เพื่อค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอให้ดึงข้อมูลความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ uint32_t สามารถเป็น NULL ได้หาก bufferCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด 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 ต้องเป็นตัวชี้ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า 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 เป็นแฮนเดิลของ XrSpatialSnapshotEXT
info เก็บข้อมูลในบัฟเฟอร์เพื่อค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอให้ดึงข้อมูลความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer เป็นอาร์เรย์ของ float สามารถเป็น NULL ได้หาก bufferCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด 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 ต้องเป็นตัวชี้ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า 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 เป็นแฮนเดิลของ XrSpatialSnapshotEXT
info เก็บข้อมูลในบัฟเฟอร์เพื่อค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอให้ดึงข้อมูลความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer คืออาร์เรย์ของ XrVector2f สามารถเป็น NULL ได้หาก bufferCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด 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 ต้องเป็นตัวชี้ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็นพอยเตอร์ไปยังอาร์เรย์ของโครงสร้าง bufferCapacityInput XrVector2f

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

สำเร็จ

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 เป็นแฮนเดิลของ XrSpatialSnapshotEXT
info เก็บข้อมูลในบัฟเฟอร์เพื่อค้นหา
bufferCapacityInput คือความจุของอาร์เรย์ หรือ 0 เพื่อระบุคำขอให้ดึงข้อมูลความจุที่จำเป็น
bufferCountOutput คือจำนวนองค์ประกอบในอาร์เรย์ buffer หรือความจุที่จำเป็นในกรณีที่ bufferCapacityInput ไม่เพียงพอ
buffer คืออาร์เรย์ของ XrVector3f สามารถเป็น NULL ได้หาก bufferCapacityInput เป็น 0
ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด 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 ต้องเป็นตัวชี้ไปยังค่า uint32_t
หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็นพอยเตอร์ไปยังอาร์เรย์ของโครงสร้าง bufferCapacityInput XrVector3f

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

สำเร็จ

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 เป็นตัวชี้ไปยัง 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 ต้องเป็นตัวชี้ไปยังโครงสร้าง 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 ต้องเป็นตัวชี้ไปยังอาร์เรย์ของแฮนเดิล XrSpatialEntityEXT ที่ถูกต้อง entityCount รายการ
หาก componentTypeCount ไม่ใช่ 0 componentTypes ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า 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 ความสูง ความสูง Y Y Z Z X X ระนาบแนวตั้ง ระนาบแนวตั้ง ระนาบแนวนอน ระนาบแนวนอน ความกว้าง ความกว้าง ความกว้าง ความกว้าง ความสูง ความสูง

รูปที่ 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

การกำหนดค่า

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

Mesh 3D

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

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

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

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

origin คือ XrPosef ที่กำหนดจุดเริ่มต้นของ Mesh จุดยอดทั้งหมดของ Mesh ต้องสัมพันธ์กับจุดเริ่มต้นนี้
vertexBuffer คือ XrSpatialBufferEXT ที่ระบุรหัสสำหรับบัฟเฟอร์ซึ่งแสดงถึงบัฟเฟอร์จุดยอดของเอนทิตีที่คอมโพเนนต์นี้อยู่ ตำแหน่งของจุดยอดต้องสัมพันธ์กับ origin
indexBuffer คือ XrSpatialBufferEXT ที่ระบุรหัสสำหรับบัฟเฟอร์ซึ่งแสดงอาร์เรย์ของดัชนีสามเหลี่ยม โดยระบุดัชนีของจุดยอดของ Mesh ใน 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 ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของโครงสร้าง meshCount XrSpatialMeshDataEXT
พารามิเตอร์ meshCount ต้องมากกว่า 0

การกำหนดค่า

หาก XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT มีการแจกแจงใน XrSpatialCapabilityComponentTypesEXT :: componentTypes สำหรับความสามารถบางอย่าง แอปพลิเคชันสามารถเปิดใช้ได้โดยรวม enum ไว้ในรายการ 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 แก่แอปพลิเคชัน ต้องมี 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)
- คำอธิบายส่วนขยายเริ่มต้น