XR_EXT_spatial_mesh_tracking

Name String

XR_EXT_spatial_mesh_tracking

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

784

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

XR_EXT_spatial_entity

著作人

Nihav Jain，Google
Natalie Fleury，Meta
Yuichi Taguchi，Meta
Ron Bessems，Meta
Yin Li，Microsoft
Jimmy Alamparambil，ByteDance
Zhipeng Liu，ByteDance
Jun Yan，ByteDance

總覽

這項擴充功能以 XR_EXT_spatial_entity 為基礎，定義了追蹤環境三角形網格的空間功能。這個擴充功能定義的功能會提供三角形網格，供應用程式判斷虛擬內容與環境是否發生碰撞。

空間網格追蹤功能

這項擴充功能會將 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 定義為空間功能，用於追蹤環境的三角形網格。這項功能不涵蓋追蹤平面和物件等實體的網格，而必須改為透過 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件的列舉，指出追蹤這些實體的各自功能。

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 會根據執行階段的功能和應用程式選取的設定，為應用程式提供防水和非防水網格。

防水網格是指所有大小的間隙和未掃描區域都已填滿，並在特定體積區塊內形成緊密網格。顧名思義，如果應用程式在防水網格內填滿水，水不應從防水體積中漏出。將掃描的網格變成水密網格通常需要極高的運算能力，但部分執行階段會預先處理網格，藉此抵銷這項成本。

執行階段支援

如果執行階段支援追蹤環境的三角形網格，則必須在 xrEnumerateSpatialCapabilitiesEXT 中列舉 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT，以表示支援。

支援 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 的執行階段可能有 3 種能力：

設定

XrSpatialCapabilityConfigurationMeshTrackingEXT 結構定義如下：

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

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。
  • capability 是 XrSpatialCapabilityEXT，且「必須」為 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT。
  • enabledComponentCount 是 uint32_t，用於描述 enabledComponents 陣列中的元素數量。
  • enabledComponents 是指向 XrSpatialComponentTypeEXT 陣列的指標。

應用程式可以啟用 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 空間功能，方法是在 XrSpatialContextCreateInfoEXT :: capabilityConfigs 中加入指向 XrSpatialCapabilityConfigurationMeshTrackingEXT 結構的指標。

如果 capability 不是 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT，執行階段「必須」傳回 XR_ERROR_VALIDATION_FAILURE。

有效用途 (隱含)

追蹤防水網格

XrSpatialFeatureTrackWatertightMeshEXT 結構定義如下：

typedef struct XrSpatialFeatureTrackWatertightMeshEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           enableWatertightMeshTracking;
} XrSpatialFeatureTrackWatertightMeshEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。
  • enableWatertightMeshTracking 指出執行階段是否必須為掃描環境計算防水網格。

支援防水網格追蹤的執行階段必須列舉 xrEnumerateSpatialCapabilityFeaturesEXT 中的 XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT。XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT 功能可讓應用程式選擇啟用防水網格追蹤，並明確選擇加入防水網格生成可能產生的任何額外運算。

如果 xrEnumerateSpatialCapabilityFeaturesEXT 為特定功能列舉 XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT，應用程式可以將 XrSpatialFeatureTrackWatertightMeshEXT 鏈結至該功能的對應設定結構，指出是否要讓追蹤的網格不透水。如果應用程式將 enableWatertightMeshTracking 設為 XR_TRUE，執行階段必須計算並提供應用程式環境的防水網格。如果應用程式將 enableWatertightMeshTracking 設為 XR_FALSE，且執行階段僅支援不透水網格追蹤，則追蹤的網格「可能」仍為不透水，例如執行階段提供預先掃描環境的處理網格。

有效用途 (隱含)

申請流程

下圖顯示應用程式如何設定空間情境，追蹤環境的封閉網格。

是

是

應用程式需要
封閉網格

應用程式需要...

是

是

否

否

執行階段
支援「網格追蹤」
功能

執行階段...

是

是

否

否

執行階段
支援「追蹤防水網格」
功能

執行階段...

應用程式會使用「網格追蹤功能」和「追蹤防水網格」功能建立空間情境

應用程式建立空間...

應用程式會處理目前執行階段不支援的功能

應用程式處理缺乏...

應用程式會處理追蹤的網格，自行建立防水網格，使用者可能需要協助修補網格中的孔洞

應用程式處理交易... 文字並非 SVG，無法顯示

圖 29. 要求防水網格的應用程式流程

保證元件

支援 XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT 的執行階段「必須」提供下列空間元件，做為這項功能探索到的所有實體的保證元件，且「必須」在 xrEnumerateSpatialCapabilityComponentTypesEXT 中列舉這些元件：

  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
有界限的 3D 元件

有界限的 3D 元件會提供所在實體的中心和範圍。這個元件提供的資料可讓應用程式更輕鬆地剔除檢視平截頭體外的實體。

詳情請參閱「有界 3D」。

網格 3D 元件

網格 3D 元件會提供所在實體的 3D 網格。詳情請參閱「Mesh 3D」。

體積分割 (分塊)

執行階段「可能」會將網格分割成體積區塊 (區塊)，讓應用程式更容易剔除檢視截頭體外的網格區塊。在這種情況下，執行階段「必須」將每個這類體積區塊視為獨立實體，並在每個這類實體 (體積區塊) 上設定一組保證元件。如果執行階段以這種方式提供不透水網格，則每個體積區塊本身並非不透水，但一組區塊會共同形成不透水網格。在這種情況下，執行階段必須在每個實體 (體積區塊) 上新增 XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT 元件，且共同形成防水網格的區塊，其上層實體的值必須相同。這樣一來，應用程式就能識別哪些區塊會共同形成防水網格。

相鄰體積區塊的網格可以共用頂點，但一個體積區塊的三角形不得與相鄰體積的三角形重疊。

選用組件

網格法向量

元件資料

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT 會使用 XrSpatialBufferEXT 處理資料。XrSpatialBufferEXT :: bufferId 代表緩衝區，其中包含這個元件所在實體網格的頂點法線。XrSpatialBufferEXT :: bufferType「必須」為 XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT。具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT 的實體必須同時具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT。這個元件提供的法線必須對應 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件的 XrSpatialMeshDataEXT :: vertexBuffer 中提供的頂點。

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

XrSpatialComponentMesh3DNormalsListEXT 結構定義如下：

typedef struct XrSpatialComponentMesh3DNormalsListEXT {
    XrStructureType        type;
    void*                  next;
    uint32_t               meshNormalsCount;
    XrSpatialBufferEXT*    meshNormals;
} XrSpatialComponentMesh3DNormalsListEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • meshNormalsCount 是 uint32_t，用於描述 meshNormals 陣列中的元素數量。
  • meshNormals 是 XrVector3f 陣列。

如果 XrSpatialComponentMesh3DNormalsListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 的下一個鏈結中，但 XrSpatialComponentDataQueryConditionEXT :: componentTypeCount 不為零，且 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中，則執行階段「必須」從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE。

如果 meshNormalsCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput，執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT。

有效用途 (隱含)

設定

如果 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中列舉，應用程式可以在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉，啟用該功能。這個元件不需要任何特殊設定，即可納入 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一個鏈結。不過，建議應用程式搭配使用這個元件及其資料與 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件。

網格語意標籤

typedef enum XrSpatialMeshSemanticLabelEXT {
    XR_SPATIAL_MESH_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_FLOOR_EXT = 2,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_WALL_EXT = 3,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_CEILING_EXT = 4,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_TABLE_EXT = 5,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_CHAIR_EXT = 6,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_SOFA_EXT = 7,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_BED_EXT = 8,
    XR_SPATIAL_MESH_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMeshSemanticLabelEXT;

XrSpatialMeshSemanticLabelEXT 列舉會描述網格的一組語意標籤。不同的空間元件會使用這個值，為 XrSpatialBufferEXT 的 uint8_t 值賦予意義，用於每個頂點或每個三角形的語意標籤。請參閱網格頂點語意標籤和網格三角形語意標籤

如果擴充功能想要擴充這組語意標籤，或為網格新增自己的標籤組，應遵循語意標籤設計和擴充功能指南中的規範。

列舉說明

XR_SPATIAL_MESH_SEMANTIC_LABEL_UNCATEGORIZED_EXT

執行階段無法分類頂點或三角形。

XR_SPATIAL_MESH_SEMANTIC_LABEL_FLOOR_EXT

頂點或三角形會對應到樓層。

XR_SPATIAL_MESH_SEMANTIC_LABEL_WALL_EXT

頂點或三角形會對應至牆壁。

XR_SPATIAL_MESH_SEMANTIC_LABEL_CEILING_EXT

頂點或三角形對應至天花板。

XR_SPATIAL_MESH_SEMANTIC_LABEL_TABLE_EXT

頂點或三角形會對應至表格。

XR_SPATIAL_MESH_SEMANTIC_LABEL_CHAIR_EXT

頂點或三角形對應到椅子。

XR_SPATIAL_MESH_SEMANTIC_LABEL_SOFA_EXT

頂點或三角形對應到沙發。

XR_SPATIAL_MESH_SEMANTIC_LABEL_BED_EXT

頂點或三角形會對應至苗床。

網格頂點語意標籤

元件總覽

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 會為空間實體網格的每個頂點提供單一語意標籤。

元件資料

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 會使用 XrSpatialBufferEXT 處理資料。XrSpatialBufferEXT :: bufferId 代表緩衝區，其中包含這個元件所在實體網格的頂點語意標籤。XrSpatialBufferEXT :: bufferType「必須」為 XR_SPATIAL_BUFFER_TYPE_UINT8_EXT。緩衝區中的值會對應至 XrSpatialMeshSemanticLabelEXT 列舉的值。具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 的實體也必須具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件。這個元件提供的語意標籤必須對應 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件的 XrSpatialMeshDataEXT :: vertexBuffer 中提供的頂點。這表示此元件提供的空間緩衝區資料中，指定索引處的語意標籤，會對應至 XrSpatialMeshDataEXT :: vertexBuffer 提供的相同索引處頂點。這也表示 xrGetSpatialBufferUint8EXT :: bufferCountOutput「必須」與頂點語意標籤緩衝區和 XrSpatialMeshDataEXT :: vertexBuffer 的值相同。

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

XrSpatialComponentMesh3DVertexSemanticLabelsListEXT 結構定義如下：

typedef struct XrSpatialComponentMesh3DVertexSemanticLabelsListEXT {
    XrStructureType        type;
    void*                  next;
    uint32_t               meshSemanticLabelsCount;
    XrSpatialBufferEXT*    meshSemanticLabels;
} XrSpatialComponentMesh3DVertexSemanticLabelsListEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • meshSemanticLabelsCount 是 uint32_t，用於描述 meshSemanticLabels 陣列中的元素數量。
  • meshSemanticLabels 是 XrSpatialBufferEXT 的陣列。

如果 XrSpatialComponentMesh3DVertexSemanticLabelsListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 的下一個鏈結中，但 XrSpatialComponentDataQueryConditionEXT :: componentTypeCount 不為零，且 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中，則執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE。

如果 meshSemanticLabelsCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput，執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT。

有效用途 (隱含)

設定

如果 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中列舉，應用程式可以在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉，啟用該功能。這個元件不需要任何特殊設定，即可納入 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一個鏈結。不過，我們建議應用程式搭配使用這個元件及其資料與 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件。這個元件無法與 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 一併啟用。如果應用程式將 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 和 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 都新增至 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents，執行階段必須傳回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。如果應用程式嘗試在不同的 XrSpatialContextEXT 中啟用這兩個元件，執行階段也必須傳回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。

網格三角形語意標籤

元件總覽

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 會為空間實體網格的每個三角形提供單一語意標籤。

元件資料

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 會使用 XrSpatialBufferEXT 處理資料。XrSpatialBufferEXT :: bufferId 代表緩衝區，其中包含這個元件所在實體網格的三角形語意標籤。XrSpatialBufferEXT :: bufferType「必須」為 XR_SPATIAL_BUFFER_TYPE_UINT8_EXT。緩衝區中的值會對應至 XrSpatialMeshSemanticLabelEXT 列舉的值。具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 的實體也必須具有 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件。這個元件提供的語意標籤必須對應 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件 XrSpatialMeshDataEXT 中提供的三角形。包含三角形語意標籤的空間緩衝區元素數量，是 XrSpatialMeshDataEXT :: indexBuffer 的元素數量除以 3。這表示此元件提供的空間緩衝區資料中，指定索引處的語意標籤，對應至 XrSpatialMeshDataEXT :: indexBuffer 中由 [index * 3]、[index * 3 + 1]、[index * 3 + 2] 表示的三角形。

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

XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT 結構定義如下：

typedef struct XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT {
    XrStructureType        type;
    void*                  next;
    uint32_t               meshSemanticLabelsCount;
    XrSpatialBufferEXT*    meshSemanticLabels;
} XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • meshSemanticLabelsCount 是 uint32_t，用於描述 meshSemanticLabels 陣列中的元素數量。
  • meshSemanticLabels 是 XrSpatialBufferEXT 的陣列。

如果 XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT 位於 XrSpatialComponentDataQueryResultEXT :: next 的下一個鏈結中，但 XrSpatialComponentDataQueryConditionEXT :: componentTypeCount 不為零，且 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中，則執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE。

如果 meshSemanticLabelsCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput，執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT。

有效用途 (隱含)

設定

如果 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中列舉，應用程式可以在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉，啟用該功能。這個元件不需要任何特殊設定，即可納入 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一個鏈結。不過，我們建議應用程式搭配使用這個元件及其資料與 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件。這個元件無法與 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 一併啟用。如果應用程式將 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT 和 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT 都新增至 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents，執行階段必須傳回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。如果應用程式嘗試在不同的 XrSpatialContextEXT 中啟用這兩個元件，執行階段也必須傳回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。

新結構

新列舉

新列舉常數

  • XR_EXT_SPATIAL_MESH_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_mesh_tracking_SPEC_VERSION

  • 擴充 XrSpatialCapabilityEXT：

    • XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

  • 擴充 XrSpatialCapabilityFeatureEXT：

    • XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

  • 擴充 XrSpatialComponentTypeEXT：

    • XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT
    • XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT
    • XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

  • 擴充 XrStructureType：

    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_MESH_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_NORMALS_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_TRIANGLE_SEMANTIC_LABELS_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_VERTEX_SEMANTIC_LABELS_LIST_EXT
    • XR_TYPE_SPATIAL_FEATURE_TRACK_WATERTIGHT_MESH_EXT

問題

版本記錄

  • 修訂版本 1，2025-11-02 (Nihav Jain，Google)

    • 初始擴充功能說明