XR_EXT_spatial_plane_tracking

名稱字串

XR_EXT_spatial_plane_tracking

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

742

修訂版本

1

批准狀態

批准

擴充功能和版本依附元件

XR_EXT_spatial_entity

著作人

Nihav Jain (Google)
Natalie Fleury (Meta)
田口雄一 (Meta)
Ron Bessems (Meta)
Yin Li (Microsoft)
Jimmy Alamparambil (ByteDance)
Zhipeng Liu (ByteDance)
Jun Yan (ByteDance)

總覽

這個擴充功能以 XR_EXT_spatial_entity 為基礎,並為空間實體架構定義平面追蹤空間功能。

執行階段支援

如果執行階段支援平面追蹤,則必須透過列舉 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 中的 xrEnumerateSpatialCapabilitiesEXT 指出這點。

設定

XrSpatialCapabilityConfigurationPlaneTrackingEXT 結構體的定義如下:

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

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。
  • capabilityXrSpatialCapabilityEXT,且必須XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT
  • enabledComponentCountuint32_t,說明 enabledComponents 陣列中的元素數量。
  • enabledComponents 是指向 XrSpatialComponentTypeEXT 陣列的指標。

應用程式可以XrSpatialContextCreateInfoEXT :: capabilityConfigs 中加入 XrSpatialCapabilityConfigurationPlaneTrackingEXT 結構的指標,啟用 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 空間功能。

如果 capability 不是 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT,執行階段「必須」傳回 XR_ERROR_VALIDATION_FAILURE

有效使用 (隱含)

  • 使用 XrSpatialCapabilityConfigurationPlaneTrackingEXT 前,XR_EXT_spatial_plane_tracking 擴充功能必須啟用
  • type 必須XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • capability 必須是有效的 XrSpatialCapabilityEXT
  • enabledComponents 必須是指向 enabledComponentCount 有效 XrSpatialComponentTypeEXT 值的陣列指標
  • enabledComponentCount 參數必須大於 0

保證元件

支援 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 的執行階段必須提供下列空間元件,做為這項功能探索到的所有實體的保證元件,並必須xrEnumerateSpatialCapabilityComponentTypesEXT 中列舉這些元件:

  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

有界 2D 元件

有界 2D 元件提供實體所在平面中心的範圍。詳情請參閱「有界 2D」。

平面對齊元件

元件資料

typedef enum XrSpatialPlaneAlignmentEXT {
    XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_UPWARD_EXT = 0,
    XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_DOWNWARD_EXT = 1,
    XR_SPATIAL_PLANE_ALIGNMENT_VERTICAL_EXT = 2,
    XR_SPATIAL_PLANE_ALIGNMENT_ARBITRARY_EXT = 3,
    XR_SPATIAL_PLANE_ALIGNMENT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPlaneAlignmentEXT;

XrSpatialPlaneAlignmentEXT 列舉會說明與 XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT 元件相關聯的平面與空間實體對齊方式。

列舉值具有下列意義:

列舉說明

XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_UPWARD_EXT

實體為水平,且朝上 (例如地板)。

XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_DOWNWARD_EXT

實體為水平,且面向下方 (例如天花板)。

XR_SPATIAL_PLANE_ALIGNMENT_VERTICAL_EXT

實體為垂直 (例如牆壁)。

XR_SPATIAL_PLANE_ALIGNMENT_ARBITRARY_EXT

實體具有任意方向,既非垂直也非水平。

查詢資料的元件清單結構

XrSpatialComponentPlaneAlignmentListEXT 結構定義如下:

typedef struct XrSpatialComponentPlaneAlignmentListEXT {
    XrStructureType                type;
    void*                          next;
    uint32_t                       planeAlignmentCount;
    XrSpatialPlaneAlignmentEXT*    planeAlignments;
} XrSpatialComponentPlaneAlignmentListEXT;

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。
  • planeAlignmentCountuint32_t,說明 planeAlignments 陣列中的元素數量。
  • planeAlignmentsXrSpatialPlaneAlignmentEXT 的陣列。

如要查詢 XrSpatialSnapshotEXT 中空間實體的平面對齊元件,請在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中加入 XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,並將 XrSpatialComponentPlaneAlignmentListEXT 新增至 XrSpatialComponentDataQueryResultEXT :: next 鏈結。

如果 XrSpatialComponentPlaneAlignmentListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 鏈結中,但 XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中,則執行階段「必須」xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE

如果 planeAlignmentCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput,執行階段必須xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT

有效使用 (隱含)

  • 使用 XrSpatialComponentPlaneAlignmentListEXT 前,必須先啟用 XR_EXT_spatial_plane_tracking 擴充功能
  • type 必須XR_TYPE_SPATIAL_COMPONENT_PLANE_ALIGNMENT_LIST_EXT
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • planeAlignments 必須是指向 planeAlignmentCount XrSpatialPlaneAlignmentEXT 值陣列的指標
  • planeAlignmentCount 參數必須大於 0
設定

如果 XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT 列舉於 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中,應用程式可以在支援此元件的功能的 XrSpatialCapabilityConfigurationBaseHeaderEXT 衍生結構的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉值,啟用該功能。

如要將這個元件納入 XrSpatialCapabilityConfigurationBaseHeaderEXT :: next 鏈結,不需要進行任何特殊設定。

選用組件

支援 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 的執行階段可能支援其他空間元件,而不只是「保證元件」一節中列出的元件。應用程式會使用 xrEnumerateSpatialCapabilityComponentTypesEXT 取得執行階段支援的完整元件清單,然後在建立空間環境時設定感興趣的元件。

Mesh 2D 元件

元件資料

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT 使用 XrSpatialMeshDataEXT 結構體做為資料。

查詢資料的元件清單結構

XrSpatialComponentMesh2DListEXT 結構體的定義如下:

typedef struct XrSpatialComponentMesh2DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh2DListEXT;

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。
  • meshCountuint32_t,說明 meshes 陣列中的元素數量。
  • meshesXrSpatialMeshDataEXT 的陣列。

如要查詢 XrSpatialSnapshotEXT 中空間實體的網格 2D 元件,請在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中加入 XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT,並將 XrSpatialComponentMesh2DListEXT 新增至 XrSpatialComponentDataQueryResultEXT :: next 鏈結。

如果 XrSpatialComponentMesh2DListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 鏈結中,但 XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT 未納入 XrSpatialComponentDataQueryConditionEXT :: componentTypes,則執行階段「必須」xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE

如果 meshCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput,執行階段必須xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT

對於執行階段在 meshes 陣列中填入的 XrSpatialMeshDataEXTXrSpatialBufferEXT :: bufferType for XrSpatialMeshDataEXT :: vertexBuffer must be XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT,而 XrSpatialBufferEXT :: bufferType for XrSpatialMeshDataEXT :: indexBuffer must be XR_SPATIAL_BUFFER_TYPE_UINT16_EXT

有效使用 (隱含)

  • 使用 XrSpatialComponentMesh2DListEXT 前,必須啟用 XR_EXT_spatial_plane_tracking 擴充功能
  • type 必須XR_TYPE_SPATIAL_COMPONENT_MESH_2D_LIST_EXT
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • meshes 必須是指向 meshCount XrSpatialMeshDataEXT 結構體陣列的指標
  • meshCount 參數必須大於 0
設定

如果 XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT 列舉於 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中,應用程式可以在支援此元件的功能的 XrSpatialCapabilityConfigurationBaseHeaderEXT 衍生結構的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉值,啟用該功能。

如要將這個元件納入 XrSpatialCapabilityConfigurationBaseHeaderEXT :: next 鏈結,不需要進行任何特殊設定。

多邊形 2D 元件

元件資料

XrSpatialPolygon2DDataEXT 結構定義如下:

typedef struct XrSpatialPolygon2DDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
} XrSpatialPolygon2DDataEXT;

成員說明

  • origin 是定義多邊形原點的 XrPosef。多邊形的所有頂點都與 X-Y 平面中的這個原點相關。
  • vertexBufferXrSpatialBufferEXT,可提供 XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT 類型緩衝區的 ID,並代表這個元件所在實體的頂點緩衝區。頂點必須以逆時針順序傳回。這些頂點代表的多邊形不得自行相交,且可能為凹多邊形。

XrSpatialBufferEXT :: bufferType for vertexBuffer must be XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

有效使用 (隱含)

查詢資料的元件清單結構

XrSpatialComponentPolygon2DListEXT 結構定義如下:

typedef struct XrSpatialComponentPolygon2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      polygonCount;
    XrSpatialPolygon2DDataEXT*    polygons;
} XrSpatialComponentPolygon2DListEXT;

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。
  • polygonCountuint32_t,說明 polygons 陣列中的元素數量。
  • polygonsXrSpatialPolygon2DDataEXT 的陣列。

如要查詢 XrSpatialSnapshotEXT 中空間實體的 2D 多邊形元件,請在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中加入 XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT,並將 XrSpatialComponentPolygon2DListEXT 新增至 XrSpatialComponentDataQueryResultEXT :: next 鏈結。

如果 XrSpatialComponentPolygon2DListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 鏈結中,但 XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中,則執行階段「必須」xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE

如果 polygonCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput,執行階段必須xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT

有效使用 (隱含)

  • 使用 XrSpatialComponentPolygon2DListEXT 前,XR_EXT_spatial_plane_tracking 擴充功能必須啟用
  • type 必須XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • polygons 必須是指向 polygonCount XrSpatialPolygon2DDataEXT 結構陣列的指標
  • polygonCount 參數必須大於 0
設定

如果 XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT 列舉於 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中,應用程式可以在支援此元件的功能的 XrSpatialCapabilityConfigurationBaseHeaderEXT 衍生結構的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉值,啟用該功能。

如要將這個元件納入 XrSpatialCapabilityConfigurationBaseHeaderEXT :: next 鏈結,不需要進行任何特殊設定。

飛機語意標籤

元件資料

typedef enum XrSpatialPlaneSemanticLabelEXT {
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT = 2,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT = 3,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT = 4,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT = 5,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPlaneSemanticLabelEXT;

XrSpatialPlaneSemanticLabelEXT 列舉會說明平面的語意標籤集。

列舉說明

XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT

執行階段無法分類這個實體。

XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT

實體為地板。

XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT

實體是牆壁。

XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT

實體為天花板。

XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT

實體是資料表。

元件清單結構,用於查詢資料

XrSpatialComponentPlaneSemanticLabelListEXT 結構定義如下:

typedef struct XrSpatialComponentPlaneSemanticLabelListEXT {
    XrStructureType                    type;
    void*                              next;
    uint32_t                           semanticLabelCount;
    XrSpatialPlaneSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentPlaneSemanticLabelListEXT;

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是結構鏈中下一個結構的指標。
  • semanticLabelCountuint32_t,說明 semanticLabels 陣列中的元素數量。
  • semanticLabelsXrSpatialPlaneSemanticLabelEXT 的陣列。

如要查詢 XrSpatialSnapshotEXT 中空間實體的平面語意標籤元件,請在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中加入 XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT,並將 XrSpatialComponentPlaneSemanticLabelListEXT 新增至 XrSpatialComponentDataQueryResultEXT :: next 鏈結。

如果 XrSpatialComponentPlaneSemanticLabelListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 的下一個鏈結中,但 XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT 未納入 XrSpatialComponentDataQueryConditionEXT :: componentTypes ,則執行階段「必須」xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE

如果 semanticLabelCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput,執行階段必須xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT

有效使用 (隱含)

  • XR_EXT_spatial_plane_tracking 擴充功能必須先啟用,才能使用 XrSpatialComponentPlaneSemanticLabelListEXT
  • type 必須XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • semanticLabels 必須是指向 semanticLabelCount XrSpatialPlaneSemanticLabelEXT 值陣列的指標
  • semanticLabelCount 參數必須大於 0
設定

如果 XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT 列舉於 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中,應用程式可以在支援此元件的功能的 XrSpatialCapabilityConfigurationBaseHeaderEXT 衍生結構的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉值,啟用該功能。

如要將這個元件納入 XrSpatialCapabilityConfigurationBaseHeaderEXT :: next 鏈結,不需要進行任何特殊設定。

範例程式碼

設定平面追蹤功能

以下程式碼範例說明如何建立空間環境時,設定平面追蹤功能。

// Check if plane 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_PLANE_TRACKING_EXT) == capabilities.end()) {
  return;
}

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

// Check if polygon 2D and plane semantic labels optional components are supported
const auto supportsComponent = [&planeCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(planeCapabilityComponents.begin(), planeCapabilityComponents.end(), component) != planeCapabilityComponents.end();
};

const bool supportsPolygon2DComponent = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
const bool supportsSemanticLabelComponent = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the 2 guaranteed components of the plane tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};
// Optionally enable polygon2D if it is supported
if (supportsPolygon2DComponent) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
}
// Optionally enable semantic labels if it is supported
if (supportsSemanticLabelComponent) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);
}

XrSpatialCapabilityConfigurationPlaneTrackingEXT planeConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT};
planeConfig.capability = XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT;
planeConfig.enabledComponentCount = enabledComponents.size();
planeConfig.enabledComponents = enabledComponents.data();

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

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;

// ...
// Discover entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

探索空間實體和查詢元件資料

下列程式碼範例說明如何探索以 XR_SPATIAL_CAPABILITY_PLANE_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_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};
if (supportsPolygon2DComponent) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
}
if (supportsSemanticLabelComponent) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PLANE_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<XrSpatialBounded2DDataEXT> bounded2D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT bounded2DList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    bounded2DList.boundCount = bounded2D.size();
    bounded2DList.bounds = bounded2D.data();
    queryResult.next = &bounded2DList;

    std::vector<XrSpatialPolygon2DDataEXT> polygons;
    XrSpatialComponentPolygon2DListEXT polygonList{XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT};
    if (supportsPolygon2DComponent) {
      polygons.resize(queryResult.entityIdCountOutput);
      polygonList.polygonCount = polygons.size();
      polygonList.polygons = polygons.data();
      polygonList.next = queryResult.next;
      queryResult.next = &polygonList;
    }

    std::vector<XrSpatialPlaneSemanticLabelEXT> semanticLabels;
    XrSpatialComponentPlaneSemanticLabelListEXT semanticLabelsList{XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT};
    if (supportsSemanticLabelComponent) {
      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;
      }

      // 2D bounds for entity entityIds[i] is bounded2D[i].extents centered on bounded2D[i].center.

      if (supportsPolygon2DComponent) {
        // 2D polygon for entity entityIds[i] is the buffer represented by polygons[i].bufferId.
        // Application uses flink:xrGetSpatialBufferVector2fEXT to get the buffer data.
      }

      if (supportsSemanticLabelComponent) {
        // 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_PLANE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_plane_tracking_SPEC_VERSION
  • 擴充 XrSpatialCapabilityEXT

    • XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT
  • 正在擴充 XrSpatialComponentTypeEXT

    • XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT
    • XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT
    • XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT
    • XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT
  • 擴充 XrStructureType

    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_2D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PLANE_ALIGNMENT_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT

問題

版本記錄

  • 修訂版本 1,2024-07-02 (Google 的 Nihav Jain)

    • 擴充功能初始說明