XR_EXT_spatial_object_tracking

Name String

XR_EXT_spatial_object_tracking

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

745

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa được phê chuẩn

Phần phụ thuộc của tiện ích và phiên bản

XR_EXT_spatial_entity

Trạng thái IP

Không có tuyên bố nào về tài sản trí tuệ.

Cộng tác viên

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

Tổng quan

Tiện ích này được xây dựng dựa trên XR_EXT_spatial_entity và xác định một chức năng không gian để theo dõi một tập hợp các đối tượng được xác định trước mà không cần tập dữ liệu đầu vào từ ứng dụng.

Hỗ trợ thời gian chạy

Nếu môi trường thời gian chạy hỗ trợ tính năng theo dõi đối tượng, thì môi trường này phải cho biết điều này bằng cách liệt kê XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT trong xrEnumerateSpatialCapabilitiesEXT .

Cấu hình

Cấu trúc XrSpatialCapabilityConfigurationObjectTrackingEXT được định nghĩa như sau:

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

Nội dung mô tả về thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• capability là một XrSpatialCapabilityEXT và phải là XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT .
• enabledComponentCount là một uint32_t mô tả số lượng phần tử trong mảng enabledComponents.
• enabledComponents là con trỏ đến một mảng XrSpatialComponentTypeEXT .

Ứng dụng có thể bật chức năng không gian XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT bằng cách thêm một con trỏ vào cấu trúc XrSpatialCapabilityConfigurationObjectTrackingEXT trong XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE nếu capability không phải là XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT .

Cách sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_EXT_spatial_object_tracking trước khi sử dụng XrSpatialCapabilityConfigurationObjectTrackingEXT
• type phải là XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc . Xem thêm: XrSpatialFeatureObjectSemanticLabelSubsetEXT
• capability phải là một giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là một con trỏ đến một mảng gồm enabledComponentCount giá trị XrSpatialComponentTypeEXT hợp lệ
• Tham số enabledComponentCount phải lớn hơn 0

Thành phần được đảm bảo

Một môi trường thời gian chạy hỗ trợ XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT phải hỗ trợ các thành phần không gian sau đây dưới dạng thành phần được đảm bảo của các thực thể mà chức năng này phát hiện được và phải liệt kê các thành phần đó trong xrEnumerateSpatialCapabilityComponentTypesEXT :

• XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT
• Ít nhất một loại thành phần cung cấp một tập hợp nhãn ngữ nghĩa cho các đối tượng được theo dõi. Khả năng theo dõi đối tượng sẽ không có ý nghĩa nếu không có thành phần nhãn ngữ nghĩa. Mặc dù tiện ích này xác định XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT và XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT là các thành phần nhãn ngữ nghĩa có thể có để thời gian chạy hỗ trợ, nhưng các tiện ích khác có thể xác định các loại thành phần mới để cung cấp các lớp nhãn ngữ nghĩa khác nhau mô tả một đối tượng được theo dõi. Hãy xem [ext_spatial_semantic_labels_guidelines] để biết thông tin chi tiết về các nhóm nhãn ngữ nghĩa và thiết kế loại thành phần. Môi trường thời gian chạy có thể không hỗ trợ XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT hoặc XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT cho chức năng theo dõi đối tượng, nhưng phải hỗ trợ ít nhất một loại thành phần cung cấp nhãn ngữ nghĩa.

Thành phần 3D có giới hạn

Thành phần 3D có giới hạn cung cấp tâm và phạm vi của đối tượng được biểu thị bằng thực thể chứa thành phần đó. Hãy xem phần 3D có giới hạn để biết thêm thông tin chi tiết.

Thành phần không bắt buộc

Một môi trường thời gian chạy hỗ trợ XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT có thể hỗ trợ các thành phần không gian ngoài những thành phần được liệt kê trong phần Thành phần được đảm bảo. Ứng dụng có thể sử dụng xrEnumerateSpatialCapabilityComponentTypesEXT để lấy danh sách đầy đủ các thành phần mà một thời gian chạy hỗ trợ, sau đó có thể định cấu hình các thành phần mà ứng dụng quan tâm khi tạo bối cảnh không gian.

Nhãn ngữ nghĩa của đối tượng

Dữ liệu thành phần

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;

Bảng liệt kê XrSpatialObjectSemanticLabelEXT mô tả một tập hợp nhãn ngữ nghĩa cho các đối tượng.

Đối với các thực thể có nhãn XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT, trục +Z của thành phần Bounded 3D (3D có giới hạn) phải gần khớp với pháp tuyến bề mặt của màn hình.

Đối với các thực thể có nhãn XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT, trục +Z của thành phần 3D có giới hạn phải khớp với pháp tuyến bề mặt của bức tường nơi phát hiện tác phẩm nghệ thuật.

Đối với các thực thể có nhãn XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT, trục +Z của thành phần Bounded 3D (3D có giới hạn) phải khớp với pháp tuyến bề mặt của bảng.

Đối với tất cả các nhãn khác trong XrSpatialObjectSemanticLabelEXT , ứng dụng không được đưa ra bất kỳ giả định nào về cách XrBoxf :: center :: orientation do thành phần Bounded 3D cung cấp trên thực thể phù hợp với các thuộc tính vật lý của đối tượng đó.

Các giá trị enum có ý nghĩa như sau:

Nội dung mô tả enum

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT

Thời gian chạy không thể phân loại thực thể này.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT

Thực thể là một chiếc ghế sofa.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_BED_EXT

Thực thể là một chiếc giường.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CHAIR_EXT

Thực thể là một chiếc ghế.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT

Thực thể là một bảng.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAMP_EXT

Thực thể là một chiếc đèn.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_PLANT_EXT

Thực thể là một loại cây.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT

Thực thể này là một màn hình, chẳng hạn như màn hình máy tính hoặc TV.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT

Thực thể là một bức tranh treo tường.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CABINET_EXT

Thực thể là một chiếc tủ.

Cấu trúc danh sách thành phần để truy vấn dữ liệu

Cấu trúc XrSpatialComponentObjectSemanticLabelListEXT được định nghĩa như sau:

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

Nội dung mô tả về thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
• semanticLabelCount là một uint32_t mô tả số lượng phần tử trong mảng semanticLabels.
• semanticLabels là một mảng XrSpatialObjectSemanticLabelEXT .

Để truy vấn thành phần nhãn ngữ nghĩa của đối tượng của các thực thể không gian trong XrSpatialSnapshotEXT , hãy thêm XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và thêm XrSpatialComponentObjectSemanticLabelListEXT vào chuỗi XrSpatialComponentDataQueryResultEXT :: next.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XrSpatialComponentObjectSemanticLabelListEXT nằm trong chuỗi XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu semanticLabelCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Cách sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_EXT_spatial_object_tracking trước khi sử dụng XrSpatialComponentObjectSemanticLabelListEXT
• type phải là XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• semanticLabels phải là một con trỏ đến một mảng gồm semanticLabelCount giá trị XrSpatialObjectSemanticLabelEXT
• Tham số semanticLabelCount phải lớn hơn 0

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số chức năng, thì ứng dụng có thể bật chức năng đó bằng cách đưa giá trị liệt kê vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc phái sinh XrSpatialCapabilityConfigurationBaseHeaderEXT của chức năng hỗ trợ thành phần này.

Thành phần này không yêu cầu bất kỳ cấu hình đặc biệt nào để đưa vào chuỗi XrSpatialCapabilityConfigurationBaseHeaderEXT :: next, nhưng cung cấp một cấu hình không bắt buộc để các ứng dụng cung cấp.

Cấu trúc XrSpatialFeatureObjectSemanticLabelSubsetEXT được định nghĩa như sau:

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

Nội dung mô tả về thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• semanticLabelCount là một uint32_t mô tả số lượng phần tử trong mảng semanticLabels.
• semanticLabels là một mảng XrSpatialObjectSemanticLabelEXT .

Nếu thời gian chạy liệt kê XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT từ xrEnumerateSpatialCapabilityComponentTypesEXT cho một chức năng nhất định, thì thời gian chạy đó cũng phải liệt kê XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT từ xrEnumerateSpatialCapabilityFeaturesEXT cho cùng một chức năng. Nếu bật XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT khi định cấu hình chức năng đó, thì ứng dụng có thể liên kết XrSpatialFeatureObjectSemanticLabelSubsetEXT với cấu trúc cấu hình tương ứng của chức năng đó để cung cấp cho thời gian chạy một tập hợp con nhãn được xác định trong XrSpatialObjectSemanticLabelEXT . Thời gian chạy có thể sử dụng một nhóm nhỏ nhãn này để tối ưu hoá quy trình theo dõi.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrCreateSpatialContextAsyncEXT nếu semanticLabels chứa bất kỳ nhãn nào không được xác định trong XrSpatialObjectSemanticLabelEXT hoặc nếu semanticLabels chứa XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT .

Thời gian chạy phải trả về XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT từ xrCreateSpatialContextAsyncEXT nếu ứng dụng cung cấp danh sách nhãn hợp lệ trong semanticLabels nhưng XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT không có trong mảng XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc cấu hình mà XrSpatialFeatureObjectSemanticLabelSubsetEXT được liên kết.

Nếu ứng dụng định cấu hình một chức năng có XrSpatialFeatureObjectSemanticLabelSubsetEXT hợp lệ, thì thời gian chạy không được bao gồm các thực thể có nhãn ngữ nghĩa không được liệt kê trong semanticLabels trong bất kỳ ảnh chụp nhanh khám phá nào được tạo cho bối cảnh không gian đã định cấu hình.

Cách sử dụng hợp lệ (Ngầm ẩn)

• Tiện ích XR_EXT_spatial_object_tracking phải được bật trước khi sử dụng XrSpatialFeatureObjectSemanticLabelSubsetEXT
• type phải là XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• semanticLabels phải là một con trỏ đến một mảng gồm semanticLabelCount giá trị XrSpatialObjectSemanticLabelEXT hợp lệ
• Tham số semanticLabelCount phải lớn hơn 0

Nhãn ngữ nghĩa của bàn phím

Dữ liệu thành phần

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;

Bảng liệt kê XrSpatialKeyboardSemanticLabelEXT mô tả nhãn ngữ nghĩa cho bàn phím.

Phạm vi và hướng của XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT được biểu thị bằng thành phần 3D có giới hạn trên cùng một thực thể được thể hiện trong hình ảnh sau (với xyz = rgb) bắt nguồn từ tâm của đối tượng.

Hình 30. Hướng bàn phím.

Nội dung mô tả enum

XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_UNCATEGORIZED_EXT

Thời gian chạy không thể phân loại thực thể này.

XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT

Thực thể là bàn phím.

Cấu trúc danh sách thành phần để truy vấn dữ liệu

Cấu trúc XrSpatialComponentKeyboardSemanticLabelListEXT được định nghĩa như sau:

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

Nội dung mô tả về thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
• semanticLabelCount là một uint32_t mô tả số lượng phần tử trong mảng semanticLabels.
• semanticLabels là một mảng XrSpatialKeyboardSemanticLabelEXT .

Để truy vấn thành phần nhãn ngữ nghĩa của bàn phím của các thực thể không gian trong XrSpatialSnapshotEXT , hãy thêm XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và thêm XrSpatialComponentKeyboardSemanticLabelListEXT vào chuỗi XrSpatialComponentDataQueryResultEXT :: next.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XrSpatialComponentKeyboardSemanticLabelListEXT nằm trong chuỗi XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu semanticLabelCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Cách sử dụng hợp lệ (Ngầm ẩn)

• Tiện ích XR_EXT_spatial_object_tracking phải được bật trước khi sử dụng XrSpatialComponentKeyboardSemanticLabelListEXT
• type phải là XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• semanticLabels phải là một con trỏ đến một mảng gồm các giá trị semanticLabelCount XrSpatialKeyboardSemanticLabelEXT
• Tham số semanticLabelCount phải lớn hơn 0

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số chức năng, thì ứng dụng có thể bật chức năng đó bằng cách đưa giá trị liệt kê vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc phái sinh XrSpatialCapabilityConfigurationBaseHeaderEXT của chức năng hỗ trợ thành phần này.

Thành phần này không yêu cầu bất kỳ cấu hình đặc biệt nào để được đưa vào chuỗi XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Nhãn ngữ nghĩa của chuột

Dữ liệu thành phần

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;

Bảng liệt kê XrSpatialMouseSemanticLabelEXT mô tả nhãn ngữ nghĩa cho chuột.

Nội dung mô tả enum

XR_SPATIAL_MOUSE_SEMANTIC_LABEL_UNCATEGORIZED_EXT

Thời gian chạy không thể phân loại thực thể này.

XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MOUSE_EXT

Thực thể là chuột.

Cấu trúc danh sách thành phần để truy vấn dữ liệu

Cấu trúc XrSpatialComponentMouseSemanticLabelListEXT được định nghĩa như sau:

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

Nội dung mô tả về thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
• semanticLabelCount là một uint32_t mô tả số lượng phần tử trong mảng semanticLabels.
• semanticLabels là một mảng XrSpatialMouseSemanticLabelEXT .

Để truy vấn thành phần nhãn ngữ nghĩa của chuột của các thực thể không gian trong XrSpatialSnapshotEXT , hãy thêm XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và thêm XrSpatialComponentMouseSemanticLabelListEXT vào chuỗi XrSpatialComponentDataQueryResultEXT :: next.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XrSpatialComponentMouseSemanticLabelListEXT nằm trong chuỗi XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu semanticLabelCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Cách sử dụng hợp lệ (Ngầm ẩn)

• Phải bật tiện ích XR_EXT_spatial_object_tracking trước khi sử dụng XrSpatialComponentMouseSemanticLabelListEXT
• type phải là XR_TYPE_SPATIAL_COMPONENT_MOUSE_SEMANTIC_LABEL_LIST_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• semanticLabels phải là con trỏ đến một mảng gồm các giá trị semanticLabelCount XrSpatialMouseSemanticLabelEXT
• Tham số semanticLabelCount phải lớn hơn 0

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số chức năng, thì ứng dụng có thể bật chức năng đó bằng cách đưa giá trị liệt kê vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc phái sinh XrSpatialCapabilityConfigurationBaseHeaderEXT của chức năng hỗ trợ thành phần này.

Thành phần này không yêu cầu bất kỳ cấu hình đặc biệt nào để được đưa vào chuỗi XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Mã ví dụ

Định cấu hình chức năng theo dõi đối tượng

Mã ví dụ sau đây minh hoạ cách định cấu hình tính năng theo dõi đối tượng khi tạo bối cảnh không gian.

// 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));

Khám phá thực thể không gian và dữ liệu thành phần truy vấn

Mã ví dụ sau đây minh hoạ cách khám phá các thực thể không gian cho một bối cảnh được định cấu hình bằng XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT và truy vấn dữ liệu thành phần của bối cảnh đó.

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

Cấu trúc mới

• XrSpatialCapabilityConfigurationObjectTrackingEXT

• Mở rộng XrSpatialCapabilityConfigurationObjectTrackingEXT :

  • XrSpatialFeatureObjectSemanticLabelSubsetEXT

• Mở rộng XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentKeyboardSemanticLabelListEXT
  • XrSpatialComponentMouseSemanticLabelListEXT
  • XrSpatialComponentObjectSemanticLabelListEXT

Enum mới

• XrSpatialKeyboardSemanticLabelEXT
• XrSpatialMouseSemanticLabelEXT
• XrSpatialObjectSemanticLabelEXT

Hằng số enum mới

• XR_EXT_SPATIAL_OBJECT_TRACKING_EXTENSION_NAME
• XR_EXT_spatial_object_tracking_SPEC_VERSION

• Mở rộng XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

• Mở rộng XrSpatialCapabilityFeatureEXT :

  • XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

• Mở rộng 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

• Mở rộng 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

Vấn đề

Danh sách phiên bản

• Bản sửa đổi 1, ngày 3 tháng 6 năm 2025 (Nihav Jain, Google)

  • Nội dung mô tả ban đầu về tiện ích