XR_ANDROID_scene_meshing
Name String
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_DEFAULT2_ANDROID = 1000801000,
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。
XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID
這組語意標籤代表 XrSceneMeshSemanticLabel2ANDROID。(由 XR_ANDROID_scene_meshing_semantic_label2 擴充功能新增)
xrEnumerateSupportedSemanticLabelSetsANDROID 函式的定義如下:
XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
XrInstance instance,
XrSystemId systemId,
uint32_t supportedSemanticLabelSetsInputCapacity,
uint32_t* supportedSemanticLabelSetsOutputCount,
XrSceneMeshSemanticLabelSetANDROID* supportedSemanticLabelSets);
參數說明
instance是應用程式建立的 XrInstance。systemId是從 xrGetSystem 重試的XrSystemId。supportedSemanticLabelSetsInputCapacity是supportedSemanticLabelSets的容量,或 0 以擷取所需容量。supportedSemanticLabelSetsOutputCount是指向寫入supportedSemanticLabelSets數量的指標,或在supportedSemanticLabelSetsInputCapacity不足時指向所需容量的指標。supportedSemanticLabelSets是 XrSceneMeshSemanticLabelSetANDROID 陣列的指標。如果supportedSemanticLabelSetsInputCapacity為 0,則可以是NULL。- 如要進一步瞭解如何擷取必要的
supportedSemanticLabelSets大小,請參閱「緩衝區空間參數」一章。
應用程式可以使用 xrEnumerateSupportedSemanticLabelSetsANDROID 函式,列舉系統支援的語意標籤集。
每個系統都必須至少支援 XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID,因為這個列舉值代表沒有語意標籤集,且可以在應用程式不需要頂點語意的情況下使用。
有效用途 (隱含)
- 呼叫 xrEnumerateSupportedSemanticLabelSetsANDROID 前,必須啟用
XR_ANDROID_scene_meshing擴充功能 -
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。在這種情況下,呼叫 xrGetSystemProperties 函式時,執行階段必須為 XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing 傳回 XR_FALSE,這樣應用程式才能避免建立場景網格追蹤器。
建立場景網格追蹤器時,應用程式只能使用 XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet 中系統支援的語意標籤組合。如果應用程式使用不支援的場景網格頂點語意標籤集,執行階段必須從 xrCreateSceneMeshingTrackerANDROID 傳回 XR_ERROR_FEATURE_UNSUPPORTED。
應用程式可以使用 xrEnumerateSupportedSemanticLabelSetsANDROID 函式,列舉支援的語意標籤組合清單。
xrCreateSceneMeshingTrackerANDROID 控制代碼擁有場景網格的所有資源。完成場景網格體驗後,應用程式必須透過 xrDestroySceneMeshingTrackerANDROID 函式刪除控制代碼。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_scene_meshing擴充功能,才能呼叫 xrCreateSceneMeshingTrackerANDROID -
session「必須」是有效的 XrSession 控制代碼 -
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 控制代碼的資訊。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_scene_meshing擴充功能,才能使用 XrSceneMeshingTrackerCreateInfoANDROID -
type「必須」為XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
semanticLabelSet必須是有效的 XrSceneMeshSemanticLabelSetANDROID 值
xrDestroySceneMeshingTrackerANDROID 函式的定義如下:
XrResult xrDestroySceneMeshingTrackerANDROID(
XrSceneMeshingTrackerANDROID tracker);
參數說明
tracker是先前由 xrCreateSceneMeshingTrackerANDROID 建立的 XrSceneMeshingTrackerANDROID。
xrDestroySceneMeshingTrackerANDROID 函式會在場景網格體驗結束後,釋出 tracker 和基礎資源。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_scene_meshing擴充功能,才能呼叫 xrDestroySceneMeshingTrackerANDROID -
tracker「必須」是有效的 XrSceneMeshingTrackerANDROID 控制代碼
執行緒安全
- 存取
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擴充功能 -
tracker「必須」是有效的 XrSceneMeshingTrackerANDROID 控制代碼 -
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 控制代碼的資訊
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_scene_meshing擴充功能,才能使用 XrSceneMeshSnapshotCreateInfoANDROID -
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「必須」是指向submeshStateCapacityInputXrSceneSubmeshStateANDROID 結構陣列的指標
傳回代碼
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 對應至子網格占據的實體空間區域。執行階段可能隨時會失去這項對應關係,並為偵測到的子網格指派新的 UUID。特別是,執行階段不需要在後續的應用程式執行個體中,為相同的網格重複使用相同的 UUID。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_scene_meshing擴充功能,才能使用 XrSceneSubmeshStateANDROID -
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。
inoutSubmeshData 中每個元素的 XrSceneSubmeshDataANDROID :: submeshId「必須」不重複,且可由 xrGetAllSubmeshStatesANDROID 擷取相同的 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大小,請參閱「緩衝區空間參數」一章。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_scene_meshing擴充功能,才能使用 XrSceneSubmeshDataANDROID -
type「必須」為XR_TYPE_SCENE_SUBMESH_DATA_ANDROID -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 - 如果
vertexCapacityInput不是0,vertexPositions必須是指向vertexCapacityInputXrVector3f 結構陣列的指標 - 如果
vertexCapacityInput不是0,vertexNormals必須是指向vertexCapacityInputXrVector3f 結構陣列的指標 - 如果
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 函式刪除場景網格快照。控制代碼刪除後,應用程式就無法再使用該控制代碼取得子網格資訊或資料。追蹤器控制代碼是場景網格快照控制代碼的父項,因此追蹤器刪除時,控制代碼也會自動刪除。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_scene_meshing擴充功能,才能呼叫 xrDestroySceneMeshSnapshotANDROID -
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)
- 初始擴充功能說明