XR_ANDROID_scene_meshing
名稱字串
XR_ANDROID_scene_meshing
擴充功能類型
執行個體擴充功能
擴充功能註冊編號
719
修訂版本
3
批准狀態
未批准
擴充功能和版本依附元件
上次修改日期
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)
總覽
這項擴充功能旨在提供網格,大約代表使用者環境中的實體物件。
應用程式可以使用這項擴充功能,將場景視覺化,並讓虛擬物件與實體物件互動,例如發生碰撞。
場景網格資料是由執行階段產生,並透過 XrSceneMeshingTrackerANDROID 和 XrSceneMeshSnapshotANDROID 與應用程式共用。應用程式可以透過 xrGetAllSubmeshStatesANDROID 傳回的 XrSceneSubmeshStateANDROID 存取場景子網格資訊中的值。應用程式可以透過 xrGetSubmeshDataANDROID 傳回的 XrSceneSubmeshDataANDROID,存取場景子網格資料中的值。
場景網格資料屬於私密個人資訊,與個人隱私權和完整性息息相關。強烈建議應用程式在儲存或轉移場景網格資料時,一律要求使用者主動明確接受。
權限
Android 應用程式必須在資訊清單中列出 android.permission.SCENE_UNDERSTANDING_FINE 權限。android.permission.SCENE_UNDERSTANDING_FINE 權限可讓執行階段研究使用者環境,因此視為私密資訊權限。
應用程式必須在執行階段要求權限,才能使用下列函式:
- xrCreateSceneMeshingTrackerANDROID
- xrDestroySceneMeshingTrackerANDROID
- xrCreateSceneMeshSnapshotANDROID
- xrDestroySceneMeshSnapshotANDROID
- xrGetAllSubmeshStatesANDROID
- xrGetSubmeshDataANDROID
(防護等級:危險)
檢查系統功能
XrSystemSceneMeshingPropertiesANDROID 結構體的定義如下:
typedef struct XrSystemSceneMeshingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。supportsSceneMeshing是XrBool32,表示系統是否支援場景網格化。
應用程式可以在呼叫 xrGetSystemProperties 時,將 XrSystemSceneMeshingPropertiesANDROID 結構體鏈結至 XrSystemProperties,藉此檢查系統是否支援場景網格化。
如果執行階段為 supportsSceneMeshing 回傳 XR_FALSE,表示系統不支援場景網格化,因此必須從 xrCreateSceneMeshingTrackerANDROID 回傳 XR_ERROR_FEATURE_UNSUPPORTED。應用程式應避免在 supportsSceneMeshing 為 XR_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是從XrSystemIdxrGetSystem 重新嘗試。supportedSemanticLabelSetsInputCapacity是supportedSemanticLabelSets的容量,或 0 (擷取所需容量)。supportedSemanticLabelSetsOutputCount是寫入的supportedSemanticLabelSets數量指標,或在supportedSemanticLabelSetsInputCapacity不足時,是所需容量的指標。supportedSemanticLabelSets是 XrSceneMeshSemanticLabelSetANDROID 陣列的指標。如果supportedSemanticLabelSetsInputCapacity為 0,則 可以是NULL。- 如要詳細瞭解如何擷取所需
supportedSemanticLabelSets大小,請參閱「緩衝區大小參數」一章。
應用程式可以使用 xrEnumerateSupportedSemanticLabelSetsANDROID 函式,列舉系統支援的語意標籤集。
每個系統必須至少支援 XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID,因為這個列舉值代表沒有語意標籤集,且可以在應用程式不需要頂點語意時使用。
有效使用 (隱含)
- 必須先啟用
XR_ANDROID_scene_meshing擴充功能,才能呼叫 xrEnumerateSupportedSemanticLabelSetsANDROID -
instance必須是有效的 XrInstance 控制代碼 -
supportedSemanticLabelSetsOutputCount必須是指向uint32_t值的指標 - 如果
supportedSemanticLabelSetsInputCapacity不是0,supportedSemanticLabelSets必須是指向supportedSemanticLabelSetsInputCapacityXrSceneMeshSemanticLabelSetANDROID 值陣列的指標
傳回代碼
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SYSTEM_INVALIDXR_ERROR_VALIDATION_FAILURE
建立場景網格追蹤器控制代碼
XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)
XrSceneMeshingTrackerANDROID 控制代碼代表場景網格追蹤器,用於場景網格化及管理相關資源。
這個控制代碼可用於使用這個擴充功能中的 xrCreateSceneMeshSnapshotANDROID,建立場景網格快照。
xrCreateSceneMeshingTrackerANDROID 函式定義如下:
XrResult xrCreateSceneMeshingTrackerANDROID(
XrSession session,
const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
XrSceneMeshingTrackerANDROID* tracker);
參數說明
session是場景網格追蹤器將啟用的 XrSession。createInfo是 XrSceneMeshingTrackerCreateInfoANDROID 結構體的指標,用於說明要建立的場景網格追蹤器。tracker是傳回的 XrSceneMeshingTrackerANDROID 控制代碼。
應用程式可以使用 xrCreateSceneMeshingTrackerANDROID 函式建立 XrSceneMeshingTrackerANDROID 控制代碼。
如果系統不支援場景網格化,執行階段必須從 xrCreateSceneMeshingTrackerANDROID 傳回 XR_ERROR_FEATURE_UNSUPPORTED。在這種情況下,執行階段必須為 XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing 傳回 XR_FALSE,以便在呼叫 xrGetSystemProperties 函式時,應用程式可以避免建立場景網格追蹤器。
建立場景網格追蹤器時,應用程式必須僅使用系統在 XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet 中支援的語意標籤集。如果應用程式使用的場景網格頂點語意標籤集不受支援,執行階段「必須」從 xrCreateSceneMeshingTrackerANDROID 傳回 XR_ERROR_FEATURE_UNSUPPORTED。
應用程式可以使用 xrEnumerateSupportedSemanticLabelSetsANDROID 函式列舉支援的語意標籤集清單。
xrCreateSceneMeshingTrackerANDROID 控制代碼擁有場景網格的所有資源。完成場景網格化體驗後,應用程式必須透過 xrDestroySceneMeshingTrackerANDROID 函式終止控制代碼。
有效使用 (隱含)
- 呼叫 xrCreateSceneMeshingTrackerANDROID 前,
XR_ANDROID_scene_meshing擴充功能必須啟用 -
sessionmust be a valid XrSession handle -
createInfo必須是指向有效 XrSceneMeshingTrackerCreateInfoANDROID 結構體的指標 -
tracker必須是指向 XrSceneMeshingTrackerANDROID 控制代碼的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
XrSceneMeshingTrackerCreateInfoANDROID 結構體的定義如下:
typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
XrStructureType type;
const void* next;
XrSceneMeshSemanticLabelSetANDROID semanticLabelSet;
XrBool32 enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。semanticLabelSet是 XrSceneMeshSemanticLabelSetANDROID,用於指定場景網格化要使用的語意標籤集。如果設為XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID,執行階段會忽略 XrSceneSubmeshDataANDROID ::vertexSemantics緩衝區欄位。enableNormals:XrBool32,用於指定在取得場景網格資料時,是否要在場景網格緩衝區中加入網格頂點的頂點法線。
XrSceneMeshingTrackerCreateInfoANDROID 結構體會說明建立 XrSceneMeshingTrackerANDROID 控制代碼的資訊。
有效使用 (隱含)
- 使用 XrSceneMeshingTrackerCreateInfoANDROID 前,
XR_ANDROID_scene_meshing擴充功能必須啟用 -
type必須為XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID -
next必須是NULL,或是結構體鏈結中下一個結構體的有效指標 -
semanticLabelSet必須是有效的 XrSceneMeshSemanticLabelSetANDROID 值
xrDestroySceneMeshingTrackerANDROID 函式定義如下:
XrResult xrDestroySceneMeshingTrackerANDROID(
XrSceneMeshingTrackerANDROID tracker);
參數說明
tracker是先前由 xrCreateSceneMeshingTrackerANDROID 建立的 XrSceneMeshingTrackerANDROID。
完成場景網格化體驗後,xrDestroySceneMeshingTrackerANDROID 函式會釋出 tracker 和基礎資源。
有效使用 (隱含)
- 呼叫 xrDestroySceneMeshingTrackerANDROID 前,
XR_ANDROID_scene_meshing擴充功能必須啟用 -
trackermust be a valid XrSceneMeshingTrackerANDROID handle
執行緒安全
- 對
tracker和任何子項控制代碼的存取權必須從外部同步處理
傳回代碼
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
建立場景網格快照控制代碼
XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)
XrSceneMeshSnapshotANDROID 控制代碼代表場景網格快照。這個快照是使用 xrCreateSceneMeshSnapshotANDROID 建立,可擷取函式呼叫時的場景網格資料快照。
這個控制代碼可用於使用 xrGetAllSubmeshStatesANDROID 和 xrGetSubmeshDataANDROID 擷取子網格資訊和資料。
xrCreateSceneMeshSnapshotANDROID 函式定義如下:
XrResult xrCreateSceneMeshSnapshotANDROID(
XrSceneMeshingTrackerANDROID tracker,
const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
XrSceneMeshSnapshotCreationResultANDROID* outSnapshotCreationResult);
參數說明
tracker是先前使用 xrCreateSceneMeshingTrackerANDROID 建立的 XrSceneMeshingTrackerANDROID 控制代碼。createInfo是 XrSceneMeshSnapshotCreateInfoANDROID 結構的指標,其中包含建立場景網格快照所需的必要資訊。outSnapshotCreationResult是 XrSceneMeshSnapshotCreationResultANDROID 物件的指標,執行階段會填入快照建立結果。
應用程式可以使用 xrCreateSceneMeshSnapshotANDROID 函式,從場景網格追蹤器建立場景網格快照。這個函式會傳回 XrSceneMeshSnapshotANDROID 控制代碼,以及封裝在 XrSceneMeshSnapshotCreationResultANDROID 結構體中的 XrSceneMeshTrackingStateANDROID。從技術上來說,控制代碼是建立時的場景網格資料快照。這個控制代碼可以分別使用 xrGetAllSubmeshStatesANDROID 和 xrGetSubmeshDataANDROID 查詢場景網格資訊和資料。
有效使用 (隱含)
- 呼叫 xrCreateSceneMeshSnapshotANDROID 前,
XR_ANDROID_scene_meshing擴充功能必須啟用 -
trackermust be a valid XrSceneMeshingTrackerANDROID handle -
createInfo必須是指向有效 XrSceneMeshSnapshotCreateInfoANDROID 結構體的指標 -
outSnapshotCreationResult必須是指向 XrSceneMeshSnapshotCreationResultANDROID 結構體的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_POSE_INVALIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALID
XrSceneMeshSnapshotCreateInfoANDROID 結構定義如下:
typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
XrStructureType type;
const void* next;
XrSpace baseSpace;
XrTime time;
XrBoxf boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。baseSpace是 XrSpace,用於表示場景子網格姿勢資訊。time是XrTime,說明處理或顯示場景網格的時間,通常為 XrFrameState ::predictedDisplayTime。boundingBox是 XrBoxf,用於描述要擷取場景網格的定界框。
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;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。snapshot是執行階段建立的 XrSceneMeshSnapshotANDROID 控制代碼。trackingState是 XrSceneMeshTrackingStateANDROID,說明建立快照時場景網格追蹤器的狀態。
XrSceneMeshSnapshotCreationResultANDROID 結構會儲存從 xrCreateSceneMeshSnapshotANDROID 傳回的場景網格快照建立結果。
有效使用 (隱含)
- 必須先啟用
XR_ANDROID_scene_meshing擴充功能,才能使用 XrSceneMeshSnapshotCreationResultANDROID -
type必須為XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID -
next必須是NULL,或是結構體鏈結中下一個結構體的有效指標 -
snapshot必須是有效的 XrSceneMeshSnapshotANDROID 控制代碼 -
trackingState必須是有效的 XrSceneMeshTrackingStateANDROID 值
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 控制代碼。submeshStateCapacityInput是submeshStates的容量,或 0 (擷取所需容量)。submeshStateCountOutput是寫入的submeshStates數量指標,或在submeshStateCapacityInput不足時,是所需容量的指標。submeshStates是 XrSceneSubmeshStateANDROID 結構體陣列的指標,執行階段會將場景網格中所有子網格的狀態輸出至該指標。如果submeshStateCapacityInput為 0,則 可以是NULL。- 如要詳細瞭解如何擷取所需
submeshStates大小,請參閱「緩衝區大小參數」一章。
應用程式可以使用 xrGetAllSubmeshStatesANDROID 函式,取得場景網格中所有子網格的狀態。這包含基本資訊,可讓應用程式選取要取得資料的子網格。
有效使用 (隱含)
- 呼叫 xrGetAllSubmeshStatesANDROID 前,
XR_ANDROID_scene_meshing擴充功能必須啟用。 -
snapshot必須是有效的 XrSceneMeshSnapshotANDROID 控制代碼 -
submeshStateCountOutput必須是指向uint32_t值的指標 - 如果
submeshStateCapacityInput不是0,submeshStates必須是指向submeshStateCapacityInput個 XrSceneSubmeshStateANDROID 結構體的陣列指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_VALIDATION_FAILURE
XrSceneSubmeshStateANDROID 結構定義如下:
typedef struct XrSceneSubmeshStateANDROID {
XrStructureType type;
void* next;
XrUuid submeshId;
XrTime lastUpdatedTime;
XrPosef submeshPoseInBaseSpace;
XrExtent3Df bounds;
} XrSceneSubmeshStateANDROID;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。submeshId是用來識別子網格的 XrUuid。lastUpdatedTime是XrTime,代表子網格上次更新的時間。submeshPoseInBaseSpace是 XrPosef,代表用於建立場景網格快照的基本空間中,子網格的姿勢。姿勢也是子網格定界框的中心。bounds是 XrExtent3Df,用於說明封閉子網格的定界框尺寸。這個界線是在用於建立場景網格控點的基礎空間中定義。
執行階段會盡量將 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);
參數說明
snapshot是先前使用 xrCreateSceneMeshSnapshotANDROID 建立的 XrSceneMeshSnapshotANDROID 控制代碼。submeshDataCount是inoutSubmeshData的長度。inoutSubmeshData是應用程式分配的 XrSceneSubmeshDataANDROID 陣列,執行階段會將每個元素填入與 XrSceneSubmeshDataANDROID ::submeshId中傳遞的子網格 ID 相關聯的網格資料。
應用程式可以使用 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_ANDROID_scene_meshing擴充功能,才能呼叫 xrGetSubmeshDataANDROID -
snapshot必須是有效的 XrSceneMeshSnapshotANDROID 控制代碼 -
inoutSubmeshData必須是指向submeshDataCountXrSceneSubmeshDataANDROID 結構體陣列的指標 -
submeshDataCount參數必須大於0
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SIZE_INSUFFICIENTXR_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。next是NULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。submeshId是用來識別子網格的 XrUuid。vertexCapacityInput是vertexPositions、vertexNormals和vertexSemantics的容量,或是 0 來擷取所需容量。vertexCountOutput是指向所寫vertexPositions、vertexNormals和vertexSemantics數量的指標,或指向所需容量的指標 (如果vertexCapacityInput不足)。vertexPositions是 XrVector3f 的陣列,執行階段會將子網格的頂點位置輸出至這個陣列。vertexNormals是 XrVector3f 的陣列,執行階段會將子網格的頂點法線輸出至該陣列。如果應用程式建立追蹤器時停用了正常模式,這個欄位可以留空NULL。vertexSemantics是uint8_t的陣列,執行階段會將子網格的頂點語意輸出至該陣列。如果應用程式使用XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID語意標籤集建立追蹤器,則可以將此欄位留空NULL。indexCapacityInput是indices的容量,或 0 (擷取所需容量)。indexCountOutput是寫入的indices數量指標,或在vertexCapacityInput不足時,是所需容量的指標。indices是uint32_t的陣列,執行階段會將子網格的索引輸出至該陣列。- 如要詳細瞭解如何擷取必要的
vertexPositions、vertexNormals、vertexSemantics和indices大小,請參閱「緩衝區大小參數」一章。
有效使用 (隱含)
- 使用 XrSceneSubmeshDataANDROID 前,
XR_ANDROID_scene_meshing擴充功能必須啟用 -
type必須為XR_TYPE_SCENE_SUBMESH_DATA_ANDROID -
next必須是NULL,或是結構體鏈結中下一個結構體的有效指標 - 如果
vertexCapacityInput不是0,vertexPositions必須是指向vertexCapacityInput個 XrVector3f 結構體的陣列指標 - 如果
vertexCapacityInput不是0,vertexNormals必須是指向vertexCapacityInput個 XrVector3f 結構體的陣列指標 - 如果
vertexCapacityInput不是0,vertexSemantics必須是指向vertexCapacityInputuint8_t值陣列的指標 - 如果
indexCapacityInput不是0,indices必須是指向indexCapacityInputuint32_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);
參數說明
snapshot是先前使用 xrCreateSceneMeshSnapshotANDROID 建立的 XrSceneMeshSnapshotANDROID 控制代碼,將由這個函式銷毀。
應用程式可以使用 xrDestroySceneMeshSnapshotANDROID 函式,銷毀場景網格快照。控制代碼毀損後,應用程式就無法再使用該控制代碼取得子網格資訊或資料。由於追蹤器控制代碼是場景網格快照控制代碼的父項,因此追蹤器遭到刪除時,控制代碼也會自動刪除。
有效使用 (隱含)
- 呼叫 xrDestroySceneMeshSnapshotANDROID 前,
XR_ANDROID_scene_meshing擴充功能必須啟用 -
snapshot必須是有效的 XrSceneMeshSnapshotANDROID 控制代碼
執行緒安全
- 對
snapshot和任何子項控制代碼的存取權必須從外部同步處理
傳回代碼
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_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));
新物件類型
新指令
- xrCreateSceneMeshSnapshotANDROID
- xrCreateSceneMeshingTrackerANDROID
- xrDestroySceneMeshSnapshotANDROID
- xrDestroySceneMeshingTrackerANDROID
- xrEnumerateSupportedSemanticLabelSetsANDROID
- xrGetAllSubmeshStatesANDROID
- xrGetSubmeshDataANDROID
新結構
- XrSceneMeshSnapshotCreateInfoANDROID
- XrSceneMeshSnapshotCreationResultANDROID
- XrSceneMeshingTrackerCreateInfoANDROID
- XrSceneSubmeshDataANDROID
- XrSceneSubmeshStateANDROID
新列舉
新增列舉常數
XR_ANDROID_SCENE_MESHING_EXTENSION_NAMEXR_ANDROID_scene_meshing_SPEC_VERSION擴充 XrObjectType:
XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROIDXR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID
擴充 XrStructureType:
XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROIDXR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROIDXR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROIDXR_TYPE_SCENE_SUBMESH_DATA_ANDROIDXR_TYPE_SCENE_SUBMESH_STATE_ANDROIDXR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID
問題
版本記錄
修訂版本 3,2025-05-15 (Salar Khan)
- 擴充功能初始說明