XR_ANDROID_scene_meshing

名稱字串

XR_ANDROID_scene_meshing

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

719

修訂版本

3

批准狀態

未批准

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2025-05-15

IP 狀態

沒有已知的智慧財產權聲明。

著作人

Spencer Quin (Google)
Jared Finder (Google)
Antonio Fontan (Google)
Cairn Overturf (Google)
Nihav Jain (Google)
Salar Khan (Google)
Sebastian Klose (Google)
Jürgen Sturm (Google)
Vinny DaSilva (Google)
Ricardo Campbell (Google)

總覽

這項擴充功能旨在提供網格,大約代表使用者環境中的實體物件。

應用程式可以使用這項擴充功能,將場景視覺化,並讓虛擬物件與實體物件互動,例如發生碰撞。

場景網格資料是由執行階段產生,並透過 XrSceneMeshingTrackerANDROIDXrSceneMeshSnapshotANDROID 與應用程式共用。應用程式可以透過 xrGetAllSubmeshStatesANDROID 傳回的 XrSceneSubmeshStateANDROID 存取場景子網格資訊中的值。應用程式可以透過 xrGetSubmeshDataANDROID 傳回的 XrSceneSubmeshDataANDROID,存取場景子網格資料中的值。

場景網格資料屬於私密個人資訊,與個人隱私權和完整性息息相關。強烈建議應用程式在儲存或轉移場景網格資料時,一律要求使用者主動明確接受。

權限

Android 應用程式必須在資訊清單中列出 android.permission.SCENE_UNDERSTANDING_FINE 權限。android.permission.SCENE_UNDERSTANDING_FINE 權限可讓執行階段研究使用者環境,因此視為私密資訊權限。

應用程式必須在執行階段要求權限,才能使用下列函式:

(防護等級:危險)

檢查系統功能

XrSystemSceneMeshingPropertiesANDROID 結構體的定義如下:

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • supportsSceneMeshingXrBool32,表示系統是否支援場景網格化。

應用程式可以在呼叫 xrGetSystemProperties 時,將 XrSystemSceneMeshingPropertiesANDROID 結構體鏈結至 XrSystemProperties,藉此檢查系統是否支援場景網格化。

如果執行階段為 supportsSceneMeshing 回傳 XR_FALSE,表示系統不支援場景網格化,因此必須xrCreateSceneMeshingTrackerANDROID 回傳 XR_ERROR_FEATURE_UNSUPPORTED。應用程式避免在 supportsSceneMeshingXR_FALSE 時使用場景網格功能。

如果執行階段為 supportsSceneMeshing 傳回 XR_TRUE,表示系統支援場景網格。

有效使用 (隱含)

  • XR_ANDROID_scene_meshing 擴充功能必須先啟用,才能使用 XrSystemSceneMeshingPropertiesANDROID
  • type 必須XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標

XrSceneMeshSemanticLabelSetANDROID 列舉會說明場景網格的語意標籤集。這個列舉中的每個值都代表另一個包含語意標籤的列舉。舉例來說,XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID 值代表 XrSceneMeshSemanticLabelANDROID 集。

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

列舉值具有下列意義:

列舉說明

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

這個語意標籤組合代表沒有語意標籤。

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

這個語意標籤集代表 XrSceneMeshSemanticLabelANDROID。

xrEnumerateSupportedSemanticLabelSetsANDROID 函式定義如下:

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

參數說明

  • instance 是由應用程式建立的 XrInstance
  • systemId 是從 XrSystemId xrGetSystem 重新嘗試。
  • supportedSemanticLabelSetsInputCapacitysupportedSemanticLabelSets 的容量,或 0 (擷取所需容量)。
  • supportedSemanticLabelSetsOutputCount 是寫入的 supportedSemanticLabelSets 數量指標,或在 supportedSemanticLabelSetsInputCapacity 不足時,是所需容量的指標。
  • supportedSemanticLabelSetsXrSceneMeshSemanticLabelSetANDROID 陣列的指標。如果 supportedSemanticLabelSetsInputCapacity 為 0,則 可以NULL
  • 如要詳細瞭解如何擷取所需 supportedSemanticLabelSets 大小,請參閱「緩衝區大小參數」一章。

應用程式可以使用 xrEnumerateSupportedSemanticLabelSetsANDROID 函式,列舉系統支援的語意標籤集。

每個系統必須至少支援 XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID,因為這個列舉值代表沒有語意標籤集,且可以在應用程式不需要頂點語意時使用。

有效使用 (隱含)

傳回代碼

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

建立場景網格追蹤器控制代碼

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

XrSceneMeshingTrackerANDROID 控制代碼代表場景網格追蹤器,用於場景網格化及管理相關資源。

這個控制代碼可用於使用這個擴充功能中的 xrCreateSceneMeshSnapshotANDROID,建立場景網格快照。

xrCreateSceneMeshingTrackerANDROID 函式定義如下:

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

參數說明

應用程式可以使用 xrCreateSceneMeshingTrackerANDROID 函式建立 XrSceneMeshingTrackerANDROID 控制代碼。

如果系統不支援場景網格化,執行階段必須xrCreateSceneMeshingTrackerANDROID 傳回 XR_ERROR_FEATURE_UNSUPPORTED。在這種情況下,執行階段必須XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing 傳回 XR_FALSE,以便在呼叫 xrGetSystemProperties 函式時,應用程式可以避免建立場景網格追蹤器。

建立場景網格追蹤器時,應用程式必須僅使用系統在 XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet 中支援的語意標籤集。如果應用程式使用的場景網格頂點語意標籤集不受支援,執行階段「必須」xrCreateSceneMeshingTrackerANDROID 傳回 XR_ERROR_FEATURE_UNSUPPORTED

應用程式可以使用 xrEnumerateSupportedSemanticLabelSetsANDROID 函式列舉支援的語意標籤集清單。

xrCreateSceneMeshingTrackerANDROID 控制代碼擁有場景網格的所有資源。完成場景網格化體驗後,應用程式必須透過 xrDestroySceneMeshingTrackerANDROID 函式終止控制代碼。

有效使用 (隱含)

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

XrSceneMeshingTrackerCreateInfoANDROID 結構體的定義如下:

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • semanticLabelSetXrSceneMeshSemanticLabelSetANDROID,用於指定場景網格化要使用的語意標籤集。如果設為 XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID,執行階段會忽略 XrSceneSubmeshDataANDROID :: vertexSemantics 緩衝區欄位。
  • enableNormalsXrBool32,用於指定在取得場景網格資料時,是否要在場景網格緩衝區中加入網格頂點的頂點法線。

XrSceneMeshingTrackerCreateInfoANDROID 結構體會說明建立 XrSceneMeshingTrackerANDROID 控制代碼的資訊。

有效使用 (隱含)

xrDestroySceneMeshingTrackerANDROID 函式定義如下:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

參數說明

完成場景網格化體驗後,xrDestroySceneMeshingTrackerANDROID 函式會釋出 tracker 和基礎資源。

有效使用 (隱含)

執行緒安全

  • tracker 和任何子項控制代碼的存取權必須從外部同步處理

傳回代碼

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

建立場景網格快照控制代碼

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

XrSceneMeshSnapshotANDROID 控制代碼代表場景網格快照。這個快照是使用 xrCreateSceneMeshSnapshotANDROID 建立,可擷取函式呼叫時的場景網格資料快照。

這個控制代碼用於使用 xrGetAllSubmeshStatesANDROIDxrGetSubmeshDataANDROID 擷取子網格資訊和資料。

xrCreateSceneMeshSnapshotANDROID 函式定義如下:

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

參數說明

應用程式可以使用 xrCreateSceneMeshSnapshotANDROID 函式,從場景網格追蹤器建立場景網格快照。這個函式會傳回 XrSceneMeshSnapshotANDROID 控制代碼,以及封裝在 XrSceneMeshSnapshotCreationResultANDROID 結構體中的 XrSceneMeshTrackingStateANDROID。從技術上來說,控制代碼是建立時的場景網格資料快照。這個控制代碼可以分別使用 xrGetAllSubmeshStatesANDROIDxrGetSubmeshDataANDROID 查詢場景網格資訊和資料。

有效使用 (隱含)

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID

XrSceneMeshSnapshotCreateInfoANDROID 結構定義如下:

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • baseSpaceXrSpace,用於表示場景子網格姿勢資訊。
  • timeXrTime,說明處理或顯示場景網格的時間,通常為 XrFrameState :: predictedDisplayTime
  • boundingBoxXrBoxf,用於描述要擷取場景網格的定界框。

XrSceneMeshSnapshotCreateInfoANDROID 結構會說明建立 XrSceneMeshSnapshotANDROID 控制代碼的資訊

有效使用 (隱含)

  • 使用 XrSceneMeshSnapshotCreateInfoANDROID 前,XR_ANDROID_scene_meshing 擴充功能必須啟用
  • type 必須XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • baseSpace 必須是有效的 XrSpace 控制代碼

XrSceneMeshSnapshotCreationResultANDROID 結構體的定義如下:

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

成員說明

XrSceneMeshSnapshotCreationResultANDROID 結構會儲存從 xrCreateSceneMeshSnapshotANDROID 傳回的場景網格快照建立結果。

有效使用 (隱含)

XrSceneMeshTrackingStateANDROID 列舉會說明場景網格追蹤器的追蹤狀態。這個列舉中的每個值都代表場景網格追蹤器的狀態。

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

列舉值具有下列意義:

列舉說明

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

追蹤器尚未準備好提供網狀網路資料。

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

追蹤器正在追蹤。

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

追蹤器正在等待整合自上次網狀網路更新以來有效的測量結果。

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

追蹤器已連續多個週期未收到有效測量結果,因此處於錯誤狀態。

這個狀態僅做為應用程式的額外資訊。如果沒有其他錯誤來源,無論追蹤器的目前 XrSceneMeshTrackingStateANDROID 為何,執行階段必須繼續允許應用程式建立快照並從中擷取資料。如果狀態不是 XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID,快照可能不是最新狀態或空白。

從場景網格快照取得場景網格資料

xrGetAllSubmeshStatesANDROID 函式定義如下:

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

參數說明

  • snapshot 是先前使用 xrCreateSceneMeshSnapshotANDROID 建立的 XrSceneMeshSnapshotANDROID 控制代碼。
  • submeshStateCapacityInputsubmeshStates 的容量,或 0 (擷取所需容量)。
  • submeshStateCountOutput 是寫入的 submeshStates 數量指標,或在 submeshStateCapacityInput 不足時,是所需容量的指標。
  • submeshStatesXrSceneSubmeshStateANDROID 結構體陣列的指標,執行階段會將場景網格中所有子網格的狀態輸出至該指標。如果 submeshStateCapacityInput 為 0,則 可以NULL
  • 如要詳細瞭解如何擷取所需 submeshStates 大小,請參閱「緩衝區大小參數」一章。

應用程式可以使用 xrGetAllSubmeshStatesANDROID 函式,取得場景網格中所有子網格的狀態。這包含基本資訊,可讓應用程式選取要取得資料的子網格。

有效使用 (隱含)

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

XrSceneSubmeshStateANDROID 結構定義如下:

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • submeshId 是用來識別子網格的 XrUuid
  • lastUpdatedTimeXrTime,代表子網格上次更新的時間。
  • submeshPoseInBaseSpaceXrPosef,代表用於建立場景網格快照的基本空間中,子網格的姿勢。姿勢也是子網格定界框的中心。
  • boundsXrExtent3Df,用於說明封閉子網格的定界框尺寸。這個界線是在用於建立場景網格控點的基礎空間中定義。

執行階段會盡量將 submeshId 對應至子網格所占用的實體空間區域。Runtimes 可能隨時會失去這項對應關係,並將新的 UUID 指派給偵測到的任何子網格子集。特別是,後續應用程式例項中相同網格不需要重複使用相同的 UUID。

有效使用 (隱含)

  • 使用 XrSceneSubmeshStateANDROID 前,XR_ANDROID_scene_meshing 擴充功能必須啟用
  • type 必須XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標

xrGetSubmeshDataANDROID 函式定義如下:

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

參數說明

應用程式可以使用 xrGetSubmeshDataANDROID 函式,傳遞 XrSceneSubmeshDataANDROID 清單,並將每個 XrSceneSubmeshDataANDROID :: submeshId 設為要擷取的子網格相應 ID,一次取得一批子網格或所有子網格。

XrSceneSubmeshDataANDROID :: submeshId must be unique for every element in inoutSubmeshData and retrievable by xrGetAllSubmeshStatesANDROID for the same snapshot . 如果子網格 ID 無效,或 inoutSubmeshData 中有多個元素具有相同的子網格 ID,則執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE

submeshDataCount 必須小於或等於 xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput 傳回的值,否則執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE

這個 可以在 2 次呼叫的慣用語中使用,查詢所有選取子網格的頂點和索引計數。

有效使用 (隱含)

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

XrSceneSubmeshDataANDROID 結構定義如下:

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • submeshId 是用來識別子網格的 XrUuid
  • vertexCapacityInputvertexPositionsvertexNormalsvertexSemantics 的容量,或是 0 來擷取所需容量。
  • vertexCountOutput 是指向所寫 vertexPositionsvertexNormalsvertexSemantics 數量的指標,或指向所需容量的指標 (如果 vertexCapacityInput 不足)。
  • vertexPositionsXrVector3f 的陣列,執行階段會將子網格的頂點位置輸出至這個陣列。
  • vertexNormalsXrVector3f 的陣列,執行階段會將子網格的頂點法線輸出至該陣列。如果應用程式建立追蹤器時停用了正常模式,這個欄位可以留空NULL
  • vertexSemanticsuint8_t 的陣列,執行階段會將子網格的頂點語意輸出至該陣列。如果應用程式使用 XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID 語意標籤集建立追蹤器,則可以將此欄位留空 NULL
  • indexCapacityInputindices 的容量,或 0 (擷取所需容量)。
  • indexCountOutput 是寫入的 indices 數量指標,或在 vertexCapacityInput 不足時,是所需容量的指標。
  • indicesuint32_t 的陣列,執行階段會將子網格的索引輸出至該陣列。
  • 如要詳細瞭解如何擷取必要的 vertexPositionsvertexNormalsvertexSemanticsindices 大小,請參閱「緩衝區大小參數」一章。

有效使用 (隱含)

  • 使用 XrSceneSubmeshDataANDROID 前,XR_ANDROID_scene_meshing 擴充功能必須啟用
  • type 必須XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • 如果 vertexCapacityInput 不是 0vertexPositions 必須是指向 vertexCapacityInputXrVector3f 結構體的陣列指標
  • 如果 vertexCapacityInput 不是 0vertexNormals 必須是指向 vertexCapacityInputXrVector3f 結構體的陣列指標
  • 如果 vertexCapacityInput 不是 0vertexSemantics 必須是指向 vertexCapacityInput uint8_t 值陣列的指標
  • 如果 indexCapacityInput 不是 0indices 必須是指向 indexCapacityInput uint32_t 值陣列的指標

XrSceneMeshSemanticLabelANDROID 列舉是預設的語意標籤集,可用於標記網格頂點,說明網格頂點所在的實體環境表面。這個列舉集由 XrSceneMeshSemanticLabelSetANDROID 中的 XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID 值表示。

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

列舉的意義如下:

列舉說明

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

這個語意標籤表示對應的網格元素代表不明物件。

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

這個語意標籤表示對應的網格元素代表地板。

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

這個語意標籤表示對應的網格元素代表天花板。

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

這個語意標籤表示對應的網格元素代表牆壁。

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

這個語意標籤表示對應的網格元素代表表格。

銷毀場景網格快照

xrDestroySceneMeshSnapshotANDROID 函式定義如下:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

參數說明

應用程式可以使用 xrDestroySceneMeshSnapshotANDROID 函式,銷毀場景網格快照。控制代碼毀損後,應用程式就無法再使用該控制代碼取得子網格資訊或資料。由於追蹤器控制代碼是場景網格快照控制代碼的父項,因此追蹤器遭到刪除時,控制代碼也會自動刪除。

有效使用 (隱含)

執行緒安全

  • snapshot 和任何子項控制代碼的存取權必須從外部同步處理

傳回代碼

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

場景網格範例程式碼

以下程式碼範例示範如何存取場景網格資料以進行算繪。

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup
XrSpace appPlaySpace; // Created at app startup

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

新物件類型

新指令

新結構

新列舉

新增列舉常數

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION
  • 擴充 XrObjectType

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID
  • 擴充 XrStructureType

    • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
    • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
    • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
    • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

問題

版本記錄

  • 修訂版本 3,2025-05-15 (Salar Khan)

    • 擴充功能初始說明