XR_EXT_spatial_object_tracking

Name String

XR_EXT_spatial_object_tracking

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

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

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

745

การแก้ไข

1

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

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

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

XR_EXT_spatial_entity

สถานะ IP

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

ผู้เขียน

Nihav Jain, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance
Andy Biar, Unity Technologies
Rebecca Nordhauser, Unity Technologies

ภาพรวม

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

การสนับสนุนรันไทม์

หากรันไทม์รองรับการติดตามวัตถุ รันไทม์ต้องระบุการรองรับนี้โดยแจกแจง XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT ใน xrEnumerateSpatialCapabilitiesEXT

การกำหนดค่า

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

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

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

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

แอปพลิเคชันสามารถเปิดใช้ความสามารถเชิงพื้นที่ XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT โดยเพิ่มพอยน์เตอร์ไปยังโครงสร้าง XrSpatialCapabilityConfigurationObjectTrackingEXT ใน XrSpatialContextCreateInfoEXT :: capabilityConfigs

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE หาก capability ไม่ใช่ XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

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

องค์ประกอบที่รับประกัน

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

  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT
  • ประเภทคอมโพเนนต์อย่างน้อย 1 ประเภทที่ให้ชุดป้ายกำกับความหมายสำหรับออบเจ็กต์ที่ติดตาม ความสามารถในการติดตามวัตถุจะไม่มีความหมายหากไม่มีคอมโพเนนต์ป้ายกำกับเชิงความหมาย แม้ว่าส่วนขยายนี้จะกำหนด XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT และ XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT เป็นคอมโพเนนต์ป้ายกำกับเชิงความหมายที่เป็นไปได้สำหรับรันไทม์ที่จะรองรับ แต่ส่วนขยายอื่นๆ อาจกำหนดคอมโพเนนต์ประเภทใหม่เพื่อระบุคลาสต่างๆ ของป้ายกำกับเชิงความหมายที่อธิบายออบเจ็กต์ที่ติดตาม ดูรายละเอียดเกี่ยวกับชุดป้ายกำกับเชิงความหมายและการออกแบบประเภทคอมโพเนนต์ได้ที่ [ext_spatial_semantic_labels_guidelines] รันไทม์อาจไม่รองรับ XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT หรือ XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT สำหรับความสามารถในการติดตามวัตถุ แต่ต้องรองรับคอมโพเนนต์อย่างน้อย 1 ประเภทที่ให้ป้ายกำกับเชิงความหมาย

องค์ประกอบ 3 มิติที่มีขอบเขต

คอมโพเนนต์ 3 มิติที่มีขอบเขตจะระบุจุดศูนย์กลางและขอบเขตของวัตถุที่แสดงโดยเอนทิตีที่อยู่บนวัตถุนั้น ดูรายละเอียดเพิ่มเติมได้ที่โมเดล 3 มิติแบบมีขอบเขต

คอมโพเนนต์ที่ไม่บังคับ

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

ป้ายกำกับความหมายของออบเจ็กต์

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

typedef enum XrSpatialObjectSemanticLabelEXT {
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT = 2,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_BED_EXT = 3,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CHAIR_EXT = 4,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT = 5,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAMP_EXT = 6,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_PLANT_EXT = 7,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT = 8,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT = 9,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CABINET_EXT = 10,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialObjectSemanticLabelEXT;

การแจงนับ XrSpatialObjectSemanticLabelEXT อธิบายชุดป้ายกำกับความหมายสำหรับออบเจ็กต์

สำหรับเอนทิตีที่มีป้ายกำกับ XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT แกน +Z ของคอมโพเนนต์ Bounded 3D ต้องตรงกับเวกเตอร์แนวฉากของหน้าจอโดยประมาณ

สำหรับเอนทิตีที่มีป้ายกำกับ XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT แกน +Z ของคอมโพเนนต์ Bounded 3D ต้องตรงกับเวกเตอร์แนวฉากของผนังที่พบงานศิลปะ

สำหรับเอนทิตีที่มีป้ายกำกับ XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT แกน +Z ของคอมโพเนนต์ Bounded 3D ต้องตรงกับเวกเตอร์แนวฉากของพื้นผิวโต๊ะ

สำหรับป้ายกำกับอื่นๆ ทั้งหมดใน XrSpatialObjectSemanticLabelEXT แอปพลิเคชันต้องไม่ตั้งสมมติฐานใดๆ เกี่ยวกับวิธีที่ XrBoxf :: center :: orientation ที่คอมโพเนนต์ Bounded 3D ในเอนทิตีจัดเตรียมไว้สอดคล้องกับแอตทริบิวต์ทางกายภาพของออบเจ็กต์นั้น

ค่าการแจงนับมีความหมายดังต่อไปนี้

คำอธิบาย Enum

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT

รันไทม์ไม่สามารถแยกประเภทเอนทิตีนี้ได้

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT

เอนทิตีคือโซฟา

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_BED_EXT

เอนทิตีคือเตียง

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CHAIR_EXT

เอนทิตีคือเก้าอี้

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT

เอนทิตีเป็นตาราง

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAMP_EXT

เอนทิตีคือโคมไฟ

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_PLANT_EXT

เอนทิตีเป็นพืช

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT

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

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT

เอนทิตีนี้เป็นภาพติดผนัง

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CABINET_EXT

เอนทิตีเป็นตู้

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

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

typedef struct XrSpatialComponentObjectSemanticLabelListEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            semanticLabelCount;
    XrSpatialObjectSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentObjectSemanticLabelListEXT;

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

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

หากต้องการค้นหาคอมโพเนนต์ป้ายกำกับความหมายของออบเจ็กต์ของเอนทิตีเชิงพื้นที่ใน XrSpatialSnapshotEXT ให้รวม XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT ไว้ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes และเพิ่ม XrSpatialComponentObjectSemanticLabelListEXT ลงในเชน XrSpatialComponentDataQueryResultEXT :: next

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrQuerySpatialComponentDataEXT หาก XrSpatialComponentObjectSemanticLabelListEXT อยู่ในเชน XrSpatialComponentDataQueryResultEXT :: next แต่ XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT ไม่ได้รวมอยู่ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes

รันไทม์ต้องแสดงผล XR_ERROR_SIZE_INSUFFICIENT จาก xrQuerySpatialComponentDataEXT หาก semanticLabelCount น้อยกว่า XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput

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

การกำหนดค่า

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

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

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

typedef struct XrSpatialFeatureObjectSemanticLabelSubsetEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  semanticLabelCount;
    const XrSpatialObjectSemanticLabelEXT*    semanticLabels;
} XrSpatialFeatureObjectSemanticLabelSubsetEXT;

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

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

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

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrCreateSpatialContextAsyncEXT หาก semanticLabels มีป้ายกำกับที่ไม่ได้กำหนดไว้ใน XrSpatialObjectSemanticLabelEXT หรือหาก semanticLabels มี XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT

รันไทม์ต้องแสดงผล XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT จาก xrCreateSpatialContextAsyncEXT หากแอปพลิเคชันระบุรายการป้ายกำกับที่ถูกต้องใน semanticLabels แต่ XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT ไม่ได้รวมอยู่ในอาร์เรย์ XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents ของโครงสร้างการกำหนดค่าที่ XrSpatialFeatureObjectSemanticLabelSubsetEXT เชื่อมโยงอยู่

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

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

ป้ายกำกับความหมายของแป้นพิมพ์

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

typedef enum XrSpatialKeyboardSemanticLabelEXT {
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT = 2,
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialKeyboardSemanticLabelEXT;

การแจงนับ XrSpatialKeyboardSemanticLabelEXT อธิบายป้ายกำกับความหมายสำหรับแป้นพิมพ์

ขอบเขตและการวางแนวของ XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT ที่แสดงโดยคอมโพเนนต์ Bounded 3D ในเอนทิตีเดียวกันจะแสดงในรูปภาพต่อไปนี้ (โดยมี xyz = rgb) ซึ่งเริ่มต้นที่จุดศูนย์กลางของวัตถุ

ext spatial object tracking keyboard orientation

รูปที่ 30 การวางแนวแป้นพิมพ์

คำอธิบาย Enum

XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_UNCATEGORIZED_EXT

รันไทม์ไม่สามารถแยกประเภทเอนทิตีนี้ได้

XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT

เอนทิตีเป็นแป้นพิมพ์

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

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

typedef struct XrSpatialComponentKeyboardSemanticLabelListEXT {
    XrStructureType                       type;
    void*                                 next;
    uint32_t                              semanticLabelCount;
    XrSpatialKeyboardSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentKeyboardSemanticLabelListEXT;

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

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

หากต้องการค้นหาคอมโพเนนต์ป้ายกำกับความหมายของแป้นพิมพ์ของเอนทิตีเชิงพื้นที่ใน XrSpatialSnapshotEXT ให้รวม XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT ไว้ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes และเพิ่ม XrSpatialComponentKeyboardSemanticLabelListEXT ลงในเชน XrSpatialComponentDataQueryResultEXT :: next

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrQuerySpatialComponentDataEXT หาก XrSpatialComponentKeyboardSemanticLabelListEXT อยู่ในเชน XrSpatialComponentDataQueryResultEXT :: next แต่ XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT ไม่ได้รวมอยู่ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes

รันไทม์ต้องแสดงผล XR_ERROR_SIZE_INSUFFICIENT จาก xrQuerySpatialComponentDataEXT หาก semanticLabelCount น้อยกว่า XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput

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

การกำหนดค่า

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

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

ป้ายกำกับความหมายของเมาส์

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

typedef enum XrSpatialMouseSemanticLabelEXT {
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MOUSE_EXT = 2,
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMouseSemanticLabelEXT;

การแจงนับ XrSpatialMouseSemanticLabelEXT อธิบายป้ายกำกับเชิงความหมายสำหรับเมาส์

คำอธิบาย Enum

XR_SPATIAL_MOUSE_SEMANTIC_LABEL_UNCATEGORIZED_EXT

รันไทม์ไม่สามารถแยกประเภทเอนทิตีนี้ได้

XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MOUSE_EXT

เอนทิตีเป็นเมาส์

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

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

typedef struct XrSpatialComponentMouseSemanticLabelListEXT {
    XrStructureType                    type;
    void*                              next;
    uint32_t                           semanticLabelCount;
    XrSpatialMouseSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentMouseSemanticLabelListEXT;

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

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

หากต้องการค้นหาคอมโพเนนต์ป้ายกำกับความหมายของเมาส์ของเอนทิตีเชิงพื้นที่ใน XrSpatialSnapshotEXT ให้รวม XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT ไว้ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes และเพิ่ม XrSpatialComponentMouseSemanticLabelListEXT ลงในเชน XrSpatialComponentDataQueryResultEXT :: next

รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrQuerySpatialComponentDataEXT หาก XrSpatialComponentMouseSemanticLabelListEXT อยู่ในเชน XrSpatialComponentDataQueryResultEXT :: next แต่ XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT ไม่ได้รวมอยู่ใน XrSpatialComponentDataQueryConditionEXT :: componentTypes

รันไทม์ต้องแสดงผล XR_ERROR_SIZE_INSUFFICIENT จาก xrQuerySpatialComponentDataEXT หาก semanticLabelCount น้อยกว่า XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput

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

การกำหนดค่า

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

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

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

กำหนดค่าความสามารถในการติดตามออบเจ็กต์

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

// Check if object tracking capability is supported
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT) == capabilities.end()) {
  return;
}

// Enumerate supported components for object tracking capability
XrSpatialCapabilityComponentTypesEXT objectComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, &objectComponents));
std::vector<XrSpatialComponentTypeEXT> objectCapabilityComponents(objectComponents.componentTypeCountOutput);
objectComponents.componentTypeCapacityInput = objectCapabilityComponents.size();
objectComponents.componentTypes = objectCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, &objectComponents));

// Check if the object & keyboard semantic labels component is supported
const auto supportsComponent = [&objectCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(objectCapabilityComponents.begin(), objectCapabilityComponents.end(), component) != objectCapabilityComponents.end();
};

const bool supportsObjectSemanticLabel = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT);
const bool supportsKeyboardSemanticLabel = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);

// Enumerate supported features for object tracking capability
uint32_t featureCount;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, 0, &featureCount, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> features(featureCount);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, featureCount, &featureCount, features.data()));

const bool supportsObjectSemanticLabelSubsetFeature = std::find(features.begin(), features.end(), XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT) != features.end();

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the guaranteed components of the object tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT,
};
// Optionally enable the supported semantic labels
if (supportsObjectSemanticLabel) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT);
}
if (supportsKeyboardSemanticLabel) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);
}

// We only want to track sofa and table.
std::vector<XrSpatialObjectSemanticLabelEXT> objectSemanticLabelSubset = {
  XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT,
  XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT
};
XrSpatialFeatureObjectSemanticLabelSubsetEXT subsetFeature{XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT};
subsetFeature.semanticLabelCount = objectSemanticLabelSubset.size();
subsetFeature.semanticLabels = objectSemanticLabelSubset.data();

XrSpatialCapabilityConfigurationObjectTrackingEXT objectTrackingConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT};
objectTrackingConfig.capability = XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT;
objectTrackingConfig.enabledComponentCount = enabledComponents.size();
objectTrackingConfig.enabledComponents = enabledComponents.data();
if (supportsObjectSemanticLabelSubsetFeature) {
  objectTrackingConfig.next = &subsetFeature;
}

std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
  reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&objectTrackingConfig),
};

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;

// ...
// Discovery entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

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

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

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT,
};
if (supportsKeyboardSemanticLabel) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  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 semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

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

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

    std::vector<XrBoxf> bounded3D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded3DListEXT bounded3DList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT};
    bounded3DList.boundCount = bounded3D.size();
    bounded3DList.bounds = bounded3D.data();
    queryResult.next = &bounded3DList;

    std::vector<XrSpatialKeyboardSemanticLabelEXT> semanticLabels;
    XrSpatialComponentKeyboardSemanticLabelListEXT semanticLabelsList{XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT};
    if (supportsKeyboardSemanticLabel) {
      semanticLabels.resize(queryResult.entityIdCountOutput);
      semanticLabelsList.semanticLabelCount = semanticLabels.size();
      semanticLabelsList.semanticLabels = semanticLabels.data();
      semanticLabelsList.next = queryResult.next;
      queryResult.next = &semanticLabelsList;
    }

    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) {
        continue;
      }

      // 3D bounds for entity entityIds[i] is bounded3D[i].extents centered on bounded3D[i].center.

      if (supportsKeyboardSemanticLabel) {
        // semantic label for entity entityIds[i] is semanticLabels[i].
      }
    }

    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
  // ...
}

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

Enum ใหม่

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

  • XR_EXT_SPATIAL_OBJECT_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_object_tracking_SPEC_VERSION

  • การขยาย XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

  • การขยาย XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

  • การขยาย XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT
    • XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT
    • XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

  • การขยาย XrStructureType :

    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MOUSE_SEMANTIC_LABEL_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_EXT
    • XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

ปัญหา

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

  • ฉบับแก้ไข 1, 03-06-2025 (Nihav Jain, Google)

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