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_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_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 中的實體。

有效用途 (隱含)

鍵盤語意標籤

元件資料

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 空間物件軌鍵盤方向

圖 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_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_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_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,2025-06-03 (Nihav Jain,Google)

    • 初始擴充功能說明