XR_EXT_spatial_object_tracking
Name String
XR_EXT_spatial_object_tracking
擴充功能類型
執行個體擴充功能
擴充功能註冊編號
745
修訂版本
1
批准狀態
未批准
擴充功能和版本依附元件
XR_EXT_spatial_entity
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 為基礎,定義了追蹤一組預先定義物件的空間功能,不需要應用程式提供輸入資料集。
執行階段支援
如果執行階段支援物件追蹤,則必須在 xrEnumerateSpatialCapabilitiesEXT 中列舉 XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT,以表示支援。
設定
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 空間功能,方法是在 XrSpatialContextCreateInfoEXT :: capabilityConfigs 中,新增指向 XrSpatialCapabilityConfigurationObjectTrackingEXT 結構的指標。
如果 capability 不是 XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT,執行階段「必須」傳回 XR_ERROR_VALIDATION_FAILURE。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_object_tracking擴充功能,才能使用 XrSpatialCapabilityConfigurationObjectTrackingEXT -
type「必須」為XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標。另請參閱:XrSpatialFeatureObjectSemanticLabelSubsetEXT -
capability「必須」是有效的 XrSpatialCapabilityEXT 值 -
enabledComponents「必須」指向包含enabledComponentCount個有效 XrSpatialComponentTypeEXT 值的陣列 -
enabledComponentCount參數必須大於0
保證元件
支援 XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT 的執行階段必須支援下列空間元件,做為這項功能探索到的實體保證元件,且必須在 xrEnumerateSpatialCapabilityComponentTypesEXT 中列舉這些元件:
XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT- 至少一個元件類型,為追蹤的物件提供一組語意標籤。如果沒有語意標籤元件,物件追蹤功能就沒有意義。雖然這項擴充功能定義了
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的物件追蹤功能,但必須支援至少一個提供語意標籤的元件類型。
有界限的 3D 元件
有界限的 3D 元件會提供物件的中心和範圍,由其所在的實體表示。詳情請參閱「有界 3D」。
選用組件
支援 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 的實體,Bounded 3D 元件的 +Z 軸必須大致符合螢幕的表面法線。
對於具有 XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT 標籤的實體,Bounded 3D 元件的 +Z 軸必須與發現藝術品的牆面法線相符。
對於具有 XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT 標籤的實體,Bounded 3D 元件的 +Z 軸必須與桌面的表面法線相符。
對於 XrSpatialObjectSemanticLabelEXT 中的所有其他標籤,應用程式不得假設實體上 Bounded 3D 元件提供的 XrBoxf :: center :: orientation 如何與該物件的實體屬性對齊。
列舉值的意義如下:
列舉說明
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 中空間實體的物件語意標籤元件,請在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中加入 XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT,並將 XrSpatialComponentObjectSemanticLabelListEXT 新增至 XrSpatialComponentDataQueryResultEXT :: next 鏈結。
如果 XrSpatialComponentObjectSemanticLabelListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 鏈結中,但 XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中,執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE。
如果 semanticLabelCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput,執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT。
有效用途 (隱含)
- 您必須先啟用
XR_EXT_spatial_object_tracking擴充功能,才能使用 XrSpatialComponentObjectSemanticLabelListEXT -
type「必須」為XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
semanticLabels「必須」是指向semanticLabelCountXrSpatialObjectSemanticLabelEXT 值陣列的指標 -
semanticLabelCount參數必須大於0
設定
如果 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 的陣列。
如果執行階段針對特定功能,從 xrEnumerateSpatialCapabilityComponentTypesEXT 列舉 XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT,則必須也針對相同功能,從 xrEnumerateSpatialCapabilityFeaturesEXT 列舉 XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT。如果應用程式在設定該功能時啟用 XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT,則可以將 XrSpatialFeatureObjectSemanticLabelSubsetEXT 鏈結至該功能的對應設定結構,為執行階段提供 XrSpatialObjectSemanticLabelEXT 中定義的標籤子集。執行階段可能會使用這組標籤,最佳化追蹤管道。
如果 semanticLabels 包含任何未在 XrSpatialObjectSemanticLabelEXT 中定義的標籤,或 semanticLabels 包含 XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT,執行階段必須從 xrCreateSpatialContextAsyncEXT 傳回 XR_ERROR_VALIDATION_FAILURE。
如果應用程式在 semanticLabels 中提供有效的標籤清單,但 XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT 未包含在 XrSpatialFeatureObjectSemanticLabelSubsetEXT 鏈結的設定結構 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 陣列中,執行階段必須從 xrCreateSpatialContextAsyncEXT 傳回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT。
如果應用程式設定的功能具有有效的 XrSpatialFeatureObjectSemanticLabelSubsetEXT,則執行階段不得在為設定的空間情境建立的任何探索快照中,包含語意標籤未列在 semanticLabels 中的實體。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_object_tracking擴充功能,才能使用 XrSpatialFeatureObjectSemanticLabelSubsetEXT -
type「必須」為XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
semanticLabels「必須」是指向semanticLabelCount個有效 XrSpatialObjectSemanticLabelEXT 值陣列的指標 -
semanticLabelCount參數必須大於0
鍵盤語意標籤
元件資料
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),原點位於物件中心。
圖 30. 鍵盤方向。
列舉說明
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 中空間實體的鍵盤語意標籤元件,請在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中加入 XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT,並將 XrSpatialComponentKeyboardSemanticLabelListEXT 新增至 XrSpatialComponentDataQueryResultEXT :: next 鏈結。
如果 XrSpatialComponentKeyboardSemanticLabelListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 鏈結中,但 XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中,執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE。
如果 semanticLabelCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput,執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_object_tracking擴充功能,才能使用 XrSpatialComponentKeyboardSemanticLabelListEXT -
type「必須」為XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
semanticLabels「必須」是指向semanticLabelCountXrSpatialKeyboardSemanticLabelEXT 值陣列的指標 -
semanticLabelCount參數必須大於0
設定
如果 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 列舉會說明滑鼠的語意標籤。
列舉說明
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 中空間實體的老鼠語意標籤元件,請在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中加入 XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT,並將 XrSpatialComponentMouseSemanticLabelListEXT 新增至 XrSpatialComponentDataQueryResultEXT :: next 鏈結。
如果 XrSpatialComponentMouseSemanticLabelListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 鏈結中,但 XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中,執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE。
如果 semanticLabelCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput,執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT。
有效用途 (隱含)
- 必須先啟用
XR_EXT_spatial_object_tracking擴充功能,才能使用 XrSpatialComponentMouseSemanticLabelListEXT -
type「必須」為XR_TYPE_SPATIAL_COMPONENT_MOUSE_SEMANTIC_LABEL_LIST_EXT -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
semanticLabels「必須」是指向semanticLabelCountXrSpatialMouseSemanticLabelEXT 值陣列的指標 -
semanticLabelCount參數必須大於0
設定
如果 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
// ...
}
新結構
新列舉
新列舉常數
XR_EXT_SPATIAL_OBJECT_TRACKING_EXTENSION_NAMEXR_EXT_spatial_object_tracking_SPEC_VERSION-
XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT
擴充 XrSpatialCapabilityFeatureEXT:
XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT
-
XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXTXR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXTXR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT
擴充 XrStructureType:
XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXTXR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXTXR_TYPE_SPATIAL_COMPONENT_MOUSE_SEMANTIC_LABEL_LIST_EXTXR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_EXTXR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT
問題
版本記錄
修訂版本 1,2025-06-03 (Nihav Jain,Google)
- 初始擴充功能說明