XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

741

修訂版本

1

批准狀態

已批准

擴充功能和版本依附元件

XR_EXT_future

著作人

Nihav Jain，Google
Jared Finder，Google
Natalie Fleury，Meta
Yuichi Taguchi，Meta
Ron Bessems，Meta
Yin Li，Microsoft
Karthik Kadappan，Magic Leap
Jimmy Alamparambil，ByteDance
Zhipeng Liu，ByteDance
Jun Yan，ByteDance

總覽

這項擴充功能介紹 OpenXR 中場景理解和空間推理的概念和基礎。這項擴充功能會整合多個相關但不同的功能領域，並以大致統一的方式列舉、設定及互動。由於這項擴充功能缺乏任何一個功能領域的具體定義，因此正式規格文字往往有些抽象。本擴充功能規格文字中的範例有時會提及即將推出或假設相關擴充功能中定義的功能，僅供說明之用，並未固有地限制或指定這類額外功能。

這項擴充功能的主要部分如下：

  • 空間實體：功能以實體為中心，本身提供的功能很少。
  • 空間元件：這些實體具有相關聯的元件，可提供資料和行為。
  • 空間元件類型：每個空間元件都有特定的元件類型，且任何指定的實體最多只有一個指定元件類型的元件。
  • 空間情境：所有空間實體互動都會在初始化和設定階段後，於情境中發生。
  • 空間功能：空間實體操控功能通常由功能提供。「功能」是指某個功能單元，例如 (但不限於) 應用程式定義的錨點、平面偵測或圖片追蹤。每項功能通常會在個別擴充功能中定義 (照常在建立執行個體時啟用)，並在建立時為特定情境啟用。
  • 每項功能都與一組元件類型相關聯，而元件則存在於該功能公開的每個實體上。定義功能的擴充功能會指定該功能必須具備哪些元件類型 (「保證」)，而相同或其他擴充功能可能會指定某些潛在實作提供的選用 元件類型。任意數量的功能可能會為實體提供特定元件類型的元件，無論產生該元件的功能為何，這些元件都可統一使用。
  • 空間功能特徵：此外，部分功能需要設定，因此會由功能特徵參數化。

這項擴充功能提供一種機制，可列舉目前系統支援的每項功能提供的元件，包括必要和任何選用 元件。

由於某些實作可能需要不同程度的功能參數化，因此這項擴充功能提供了一種機制，可列舉與目前系統中指定功能相關聯的支援功能特性。

這項擴充功能也定義了多個常見元件，預期會用於各種功能。

空間實體

空間實體是存在於某個空間中的實體，具有各種相關聯的資料，並組織成元件。可能是下列任一項：

  • 實體 (例如牆壁和地板等平面、椅子和書櫃等物體)
  • 虛擬 (例如由其他應用程式或使用者放置及分享的內容)
  • 應用程式定義 (例如應用程式將某個區域標示為「Living Room」或「廚房」，或將某個點標示為放置電視的位置等)

透過動作系統公開的事物 (例如控制器或視線) 不應模擬為空間實體。

OpenXR 中的空間實體會模擬為實體元件系統。每個空間實體都有一組元件，每個元件都會為該實體提供一組專屬的資料和行為。

空間實體會以 XrSpatialEntityIdEXT 原子或 XrSpatialEntityEXT 控制代碼表示，詳情請參閱「空間實體表示法」一節。

空間元件類型

空間實體有一或多個元件，可為該實體提供資料或行為。如要瞭解這個擴充功能定義的部分常見元件，請參閱「常見元件」。

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID = 1000803000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1 = 1000808000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

XrSpatialComponentTypeEXT 列舉會識別執行階段「可能」支援的不同元件類型。

這項擴充功能本身並未提供列出的所有元件類型：部分元件需要額外的擴充功能，才能在建立執行個體時啟用，詳情請參閱說明文件。

列舉值如下：

列舉說明

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

為空間實體提供 2D 邊界的元件。對應的清單結構為 XrSpatialComponentBounded2DListEXT；對應的資料結構為 XrSpatialBounded2DDataEXT

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

為空間實體提供 3D 邊界的元件。對應的清單結構為 XrSpatialComponentBounded3DListEXT；對應的資料結構為 XrBoxf

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

提供空間實體父項 XrSpatialEntityIdEXT 的元件。對應的清單結構為 XrSpatialComponentParentListEXT；對應的資料結構為 XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

為空間實體提供 3D 網格的元件。對應的清單結構為 XrSpatialComponentMesh3DListEXT；對應的資料結構為 XrSpatialMeshDataEXT

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

為空間實體提供平面對齊列舉的元件。對應的清單結構為 XrSpatialComponentPlaneAlignmentListEXT；對應的資料結構為 XrSpatialPlaneAlignmentEXT (由 XR_EXT_spatial_plane_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

為空間實體提供 2D 網格的元件。對應的清單結構為 XrSpatialComponentMesh2DListEXT；對應的資料結構為 XrSpatialMeshDataEXT (由 XR_EXT_spatial_plane_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

為空間實體提供 2D 邊界多邊形的元件。對應的清單結構為 XrSpatialComponentPolygon2DListEXT；對應的資料結構為 XrSpatialPolygon2DDataEXT (由 XR_EXT_spatial_plane_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

為平面提供語意標籤的元件。對應的清單結構為 XrSpatialComponentPlaneSemanticLabelListEXT；對應的資料結構為 XrSpatialPlaneSemanticLabelEXT (由 XR_EXT_spatial_plane_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

描述標記類型、ID 和位置的元件。對應的清單結構為 XrSpatialComponentMarkerListEXT；對應的資料結構為 XrSpatialMarkerDataEXT (由 XR_EXT_spatial_marker_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

為場景提供語意標籤的元件；對應的清單結構為 XrSpatialComponentObjectSemanticLabelListEXT。對應的資料結構為 XrSpatialObjectSemanticLabelEXT。(由 XR_EXT_spatial_object_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

為鍵盤提供語意標籤的元件；對應的清單結構為 XrSpatialComponentKeyboardSemanticLabelListEXT。對應的資料結構為 XrSpatialKeyboardSemanticLabelEXT (由 XR_EXT_spatial_object_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

為滑鼠提供語意標籤的元件；對應的清單結構為 XrSpatialComponentMouseSemanticLabelListEXT。對應的資料結構為 XrSpatialMouseSemanticLabelEXT (由 XR_EXT_spatial_object_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

提供錨點位置的元件。對應的清單結構為 XrSpatialComponentAnchorListEXT；對應的資料結構為 XrPosef (由 XR_EXT_spatial_anchor 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

為空間實體提供永久 UUID 的元件。對應的清單結構為 XrSpatialComponentPersistenceListEXT；對應的資料結構為 XrSpatialPersistenceDataEXT (由 XR_EXT_spatial_persistence 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

描述平面圖片類型的元件。對應的清單結構為 XrSpatialComponentImage2DListEXT；對應的資料結構為 XrSpatialImageSizeEXT。(由 XR_EXT_spatial_image_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

這個元件可提供空間實體 3D 網格的法線。對應的清單結構為 XrSpatialComponentMesh3DNormalsListEXT；對應的資料結構為 XrSpatialBufferEXT (由 XR_EXT_spatial_mesh_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

這個元件可為空間實體的 3D 網格提供每個頂點的語意標籤。對應的清單結構為 XrSpatialComponentMesh3DVertexSemanticLabelsListEXT；對應的資料結構為 XrSpatialBufferEXT；緩衝區內的資料會對應至 XrSpatialMeshSemanticLabelEXT (由 XR_EXT_spatial_mesh_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

這個元件可為空間實體的 3D 網格，提供每個三角形面的語意標籤。對應的清單結構為 XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT；對應的資料結構為 XrSpatialBufferEXT；緩衝區內的資料會對應至 XrSpatialMeshSemanticLabelEXT (由 XR_EXT_spatial_mesh_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

為物件提供語意標籤的元件；對應的清單結構為 XrSpatialComponentObjectSemanticLabelListANDROID；對應的資料結構為 XrSpatialObjectSemanticLabelANDROID (由 XR_ANDROID_spatial_object_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

這個元件會提供實體上光線投射命中的姿勢。對應的清單結構為 XrSpatialComponentRaycastResultListANDROID；對應的資料結構為 XrSpatialRaycastResultDataANDROID (由 XR_ANDROID_spatial_discovery_raycast 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

這個元件會提供實體的實體 ID，該實體包含附加的實體。對應的清單結構為 XrSpatialComponentSubsumedByListANDROID；對應的資料結構為 XrSpatialEntityIdEXT (由 XR_ANDROID_spatial_component_subsumed_by 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

提供鞋盒尺寸和房間類型的元件；對應的清單結構為 XrSpatialComponentRoomListANDROIDSYS；對應的資料結構為 XrSpatialRoomDataANDROIDSYS (由 XR_ANDROIDSYS_spatial_room_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

提供邊界表面材質類型的元件；對應的清單結構為 XrSpatialComponentMaterialTypeListANDROIDSYS；對應的資料結構為 XrSpatialMaterialTypeANDROIDSYS (由 XR_ANDROIDSYS_spatial_room_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

提供可追蹤項目信賴度的元件；對應的清單結構為 XrSpatialComponentConfidenceListANDROIDSYS；對應的資料結構為 float (由 XR_ANDROIDSYS_spatial_room_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

提供房間空曠程度的元件；對應的清單結構為 XrSpatialComponentRoomEmptinessListANDROIDSYS；對應的資料結構為 float (由 XR_ANDROIDSYS_spatial_room_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

這個元件會提供所附實體的占用格線資訊。對應的清單結構為 XrSpatialComponentOccupancyGridListANDROIDX1；對應的資料結構為 XrSpatialOccupancyGridDataANDROIDX1 (由 XR_ANDROIDX1_spatial_occupancy_grid 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

說明四邊形註解的元件。對應的清單結構為 XrSpatialComponentAnnotationQuadListANDROID；對應的資料結構為 XrSpatialAnnotationQuadDataANDROID (由 XR_ANDROID_spatial_annotation_tracking 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

提供街景幾何圖形中繼資料的元件；對應的清單結構為 XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2；對應的資料結構為 XrSpatialStreetscapeGeometryMetadataANDROIDX2 (由 XR_ANDROIDX2_geospatial_streetscape 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID

將實體識別為幾何圖形點的元件。這個元件類型沒有對應的清單或資料結構。這個元件的存在僅表示實體可以附加至錨點。(由 XR_ANDROID_spatial_geometry_point 擴充功能新增)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1

說明實體保存範圍的元件。如果執行階段支援 XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT，則必須支援這個元件。對應的資料結構為 XrSpatialBufferEXT。對應的清單結構為 XrSpatialComponentPersistenceScopeDataListANDROIDX1。(由 XR_ANDROIDX1_spatial_anchor_cloud_sharing 擴充功能新增)

空間功能和設定

空間功能定義了執行階段探索實體的能力，這些實體具有一組保證的元件。應用程式在建立 XrSpatialContextEXT 時，會啟用空間功能的元件，而執行階段則必須僅在偵測到的實體上提供已啟用的元件。舉例來說，如果執行階段回報某項功能的其中一個元件是「語意標籤」，表示應用程式可以透過該功能的設定啟用語意標籤，而執行階段必須僅在設定後提供語意標籤元件。

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

XrSpatialCapabilityEXT 列舉會識別執行階段「可能」支援的不同功能類型。

列舉值如下：

列舉說明

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

平面追蹤 (由 XR_EXT_spatial_plane_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

可偵測及追蹤 QR code。(由 XR_EXT_spatial_marker_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

偵測及追蹤微型 QR code 的功能。(由 XR_EXT_spatial_marker_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

偵測及追蹤 Aruco 標記的能力。(由 XR_EXT_spatial_marker_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

偵測及追蹤 AprilTag 的功能。(由 XR_EXT_spatial_marker_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

物件軌 (由 XR_EXT_spatial_object_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

可建立空間錨點 (由 XR_EXT_spatial_anchor 擴充功能新增)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

可偵測及追蹤平面參考圖像。(由 XR_EXT_spatial_image_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

可追蹤環境的網格。(由 XR_EXT_spatial_mesh_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

物件軌 (由 XR_ANDROID_spatial_object_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

對深度緩衝區進行光線投射 (由 XR_ANDROID_spatial_discovery_raycast 擴充功能新增)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

追蹤房間的功能 (由 XR_ANDROIDSYS_spatial_room_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

追蹤房間邊界的功能 (由 XR_ANDROIDSYS_spatial_room_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

備註追蹤 (由 XR_ANDROID_spatial_annotation_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

街景幾何圖形 (由 XR_ANDROIDX2_geospatial_streetscape 擴充功能新增)

xrEnumerateSpatialCapabilitiesEXT 函式的定義如下：

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

參數說明

  • instance 是 XrInstance 的控制代碼。
  • systemId 是要列舉空間功能的 XrSystemId。
  • capabilityCapacityInput 是 capabilities 陣列的容量，或 0 表示要求擷取所需容量。
  • capabilityCountOutput 是指功能數量，或 capabilityCapacityInput 不足時所需的容量。
  • capabilities 是 XrSpatialCapabilityEXT 的陣列。如果 capabilityCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 capabilities 大小，請參閱「緩衝區大小參數」一節。

應用程式可以使用 xrEnumerateSpatialCapabilitiesEXT 列舉特定 XrSystemId 支援的空間功能清單。

執行階段不得列舉未啟用 instance 擴充功能的空間功能。

有效用途 (隱含)

  • 呼叫 xrEnumerateSpatialCapabilitiesEXT 前，必須啟用 XR_EXT_spatial_entity 擴充功能
  • instance「必須」是有效的 XrInstance 控制代碼
  • capabilityCountOutput「必須」是指向 uint32_t 值的指標
  • 如果 capabilityCapacityInput 不是 0，capabilities 必須是指向 capabilityCapacityInput XrSpatialCapabilityEXT 值陣列的指標

傳回代碼

成功

  • 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

xrEnumerateSpatialCapabilityComponentTypesEXT 函式的定義如下：

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

參數說明

這個函式會列舉指定功能在系統中實體上提供的元件類型 (依設定)。

應用程式可以使用 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中列舉的元件類型，瞭解 systemId 支援 capability 的完整元件組合，並可以使用這份清單，在為 capability 建立 XrSpatialContextEXT 時，判斷 capability 的有效設定。

如果 xrEnumerateSpatialCapabilitiesEXT 未列舉 capability，執行階段「必須」傳回 XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT。

執行階段「不得」列舉未為 instance 啟用擴充功能的空間元件類型。

有效用途 (隱含)

傳回代碼

成功

  • XR_SUCCESS

失敗

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

XrSpatialCapabilityComponentTypesEXT 結構定義如下：

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • componentTypeCapacityInput 是陣列的容量，或 0 表示要求擷取所需容量。
  • componentTypeCountOutput 是元件類型數量，或 componentTypeCapacityInput 不足時所需的容量。
  • componentTypes 是 XrSpatialComponentTypeEXT 的陣列。如果 componentTypeCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 componentTypes 大小，請參閱「緩衝區大小參數」一節。

有效用途 (隱含)

空間能力功能

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

部分功能會向應用程式公開參數，以便設定執行階段如何計算元件資料。這些參數化/可設定性維度稱為功能。舉例來說，如果是圖片追蹤功能，執行階段可能支援應用程式功能，指定追蹤的圖片是否為靜態。

透過設定結構將這項資訊提供給執行階段時，不得變更相關聯實體 (例如追蹤的圖片) 上的元件類型組合。不過，執行階段可能會最佳化圖片追蹤功能等，為應用程式提供更優質的體驗。

這類功能會以 XrSpatialCapabilityFeatureEXT 表示，應用程式會使用 xrEnumerateSpatialCapabilityFeaturesEXT 列舉這些功能。

每項功能都有對應的設定結構，可用於啟用功能。這類設定結構必須鏈結至對應功能的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: next。

列舉值如下：

列舉說明

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

這項功能可讓應用程式指定標記大小。對應的設定結構為 XrSpatialMarkerSizeEXT (由 XR_EXT_spatial_marker_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

這項功能可讓應用程式指定標記是否為靜態。對應的設定結構為 XrSpatialMarkerStaticOptimizationEXT (由 XR_EXT_spatial_marker_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

空間功能，可讓應用程式從 XrSpatialObjectSemanticLabelEXT 指定標籤子集，供執行階段追蹤。對應的設定結構為 XrSpatialFeatureObjectSemanticLabelSubsetEXT。(由 XR_EXT_spatial_object_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

執行階段支援 XrSpatialDiscoverySnapshotCreateInfoEXT 的 XrSpatialBoundsSpherefANDROID 篩選器；建立空間情境時，不需要加入任何設定結構。(由 XR_ANDROID_spatial_discovery_bounds 擴充功能新增)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

執行階段支援 XrSpatialDiscoverySnapshotCreateInfoEXT 的 XrSpatialBoundsBoxfANDROID 篩選器，建立空間情境時不需加入任何設定結構。(由 XR_ANDROID_spatial_discovery_bounds 擴充功能新增)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

執行階段支援 XrSpatialDiscoverySnapshotCreateInfoEXT 的 XrSpatialBoundsFrustumfANDROID 篩選器；建立空間情境時，不需要加入任何設定結構。(由 XR_ANDROID_spatial_discovery_bounds 擴充功能新增)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

執行階段支援自動推論偵測和追蹤圖片的實際大小。對應的設定結構為 XrSpatialImageSizeEXT (由 XR_EXT_spatial_image_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

執行階段支援 XrSpatialImageStaticOptimizationEXT。對應的設定結構為 XrSpatialImageStaticOptimizationEXT。(由 XR_EXT_spatial_image_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

執行階段支援 XrSpatialImageSizeEXT。對應的設定結構為 XrSpatialImageSizeEXT (由 XR_EXT_spatial_image_tracking 擴充功能新增)

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

可追蹤環境中不透水網格的功能。對應的設定結構為 XrSpatialFeatureTrackWatertightMeshEXT。(由 XR_EXT_spatial_mesh_tracking 擴充功能新增)

xrEnumerateSpatialCapabilityFeaturesEXT 函式的定義如下：

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

參數說明

  • instance 是 XrInstance 的控制代碼。
  • systemId 是 XrSystemId，系統會列舉其空間功能。
  • capability 是要列舉功能的 XrSpatialCapabilityEXT。
  • capabilityFeatureCapacityInput 是陣列的容量，或 0 表示要求擷取所需容量。
  • capabilityFeatureCountOutput 是特徵數量，或 capabilityFeatureCapacityInput 不足時所需的容量。
  • capabilityFeatures 是 XrSpatialCapabilityFeatureEXT 的陣列。如果 capabilityFeatureCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 capabilityFeatures 大小，請參閱「緩衝區大小參數」一節。

應用程式會使用 xrEnumerateSpatialCapabilityFeaturesEXT，探索特定系統支援的 XrSpatialCapabilityEXT 功能。

如果功能有公開的功能，應用程式會選取要啟用的功能，並在 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的功能設定結構下一個鏈結中，提供對應的設定結構。

如果 capability 不是 xrEnumerateSpatialCapabilitiesEXT 列舉的功能，執行階段「必須」傳回 XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT。

執行階段不得列舉未為 instance 啟用擴充功能的空間功能。

有效用途 (隱含)

傳回代碼

成功

  • XR_SUCCESS

失敗

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

空間背景資訊

建立空間情境

XR_DEFINE_HANDLE(XrSpatialContextEXT)

XrSpatialContextEXT 控制代碼代表用於探索及更新使用者環境中部分空間實體的資源。應用程式可以使用這個控制代碼，透過這個擴充功能中的其他函式，探索及更新空間實體。

xrCreateSpatialContextAsyncEXT 函式的定義如下：

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

參數說明

  • session 是 XrSession，空間情境會在這個工作階段中啟用。
  • createInfo 是 XrSpatialContextCreateInfoEXT，用於指定空間情境參數。
  • future 是指向 XrFutureEXT 的指標。

應用程式可以透過下列方式建立 XrSpatialContextEXT 控制代碼：

如果 XrSpatialContextCreateInfoEXT ::capabilityConfigCount 為 0，執行階段必須傳回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。空間情境控制代碼至少需要一項功能。

如果 XrSpatialContextCreateInfoEXT :: capabilityConfigs 陣列中的任何功能未由 xrEnumerateSpatialCapabilitiesEXT 列舉，執行階段必須傳回 XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT。

如果 XrSpatialContextCreateInfoEXT :: capabilityConfigs 中的任何 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount 為 0，執行階段必須傳回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。功能設定不完整，因為未列出要為該功能啟用的元件類型。

如果 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 中列出的任何元件類型，未在 xrEnumerateSpatialCapabilityComponentTypesEXT 的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability 中列舉，執行階段必須傳回 XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT。

如果 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的下一個鏈結中有任何結構對應至 XrSpatialCapabilityFeatureEXT，但該功能未在 xrEnumerateSpatialCapabilityFeaturesEXT 中列舉，則執行階段必須忽略該 XrSpatialCapabilityFeatureEXT 結構。

如果 XrSpatialContextCreateInfoEXT :: capabilityConfigs 包含多個具有相同 XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability 的結構，執行階段必須傳回 XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT。

為確保系統資源獲得最佳運用，執行階段可能會使用 XrSpatialContextCreateInfoEXT 陣列中提供的設定，為即將傳入的空間要求做好準備。舉例來說，如果應用程式建立包含平面追蹤功能的空間情境控制代碼，支援平面追蹤功能的執行階段可能只會啟動平面追蹤管道。如果設定的功能需要較長的暖機時間，呼叫 xrCreateSpatialDiscoverySnapshotAsyncEXT 可能會產生空白快照。應用程式可以先等待 XrEventDataSpatialDiscoveryRecommendedEXT，再使用 xrCreateSpatialDiscoverySnapshotAsyncEXT，確保基礎追蹤服務已準備就緒。

如果執行階段強制執行權限系統，控制應用程式對 XrSpatialContextEXT 設定的空間功能存取權，則在未授予應用程式這些權限時，執行階段必須傳回 XR_ERROR_PERMISSION_INSUFFICIENT。

這個函式會啟動非同步作業，並建立對應的 XrFutureEXT，可與 xrPollFutureEXT 和相關函式搭配使用。這個函式的傳回值只會指出參數是否可接受排定非同步作業。對應的完成函式為 xrCreateSpatialContextCompleteEXT，當這個函式的 Future 處於 READY 狀態時，即可使用該函式，並由該函式在完成結構 XrCreateSpatialContextCompletionEXT 中填入輸出內容。

有效用途 (隱含)

傳回代碼

成功

  • 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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_TIME_INVALID (如果已啟用 XR_ANDROID_spatial_annotation_tracking)

XrSpatialContextCreateInfoEXT 結構定義如下：

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

成員說明

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

XrSpatialContextCreateInfoEXT 結構說明建立 XrSpatialContextEXT 控制代碼的資訊。

有效用途 (隱含)

XrSpatialCapabilityConfigurationBaseHeaderEXT 結構定義如下：

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

這個結構不會直接用於 API，但其子結構可以與 XrSpatialContextCreateInfoEXT 搭配使用，設定空間功能。

成員說明

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

如果 xrEnumerateSpatialCapabilitiesEXT 未列舉 capability，執行階段「必須」傳回 XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT。如果 enabledComponents 中列出的任何元件類型未在 xrEnumerateSpatialCapabilityComponentTypesEXT 中列舉 capability，執行階段必須傳回 XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT。

有效用途 (隱含)

xrCreateSpatialContextCompleteEXT 函式的定義如下：

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

參數說明

xrCreateSpatialContextCompleteEXT 會完成由 xrCreateSpatialContextAsyncEXT 啟動的非同步作業。如果 future 未處於就緒狀態，執行階段必須傳回 XR_ERROR_FUTURE_PENDING_EXT。如果 future 已完成或取消，執行階段必須傳回 XR_ERROR_FUTURE_INVALID_EXT。

有效用途 (隱含)

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • 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

XrCreateSpatialContextCompletionEXT 結構定義如下：

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

成員說明

未來退貨代碼

futureResult 值：

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

如果 futureResult 是成功代碼，spatialContext 必須有效。如果 spatialContext 有效，則只會在 xrCreateSpatialContextAsyncEXT :: session 的生命週期內保持有效，或直到應用程式使用 xrDestroySpatialContextEXT 刪除 spatialContext 為止，以先發生者為準。

有效用途 (隱含)

刪除空間背景資訊

xrDestroySpatialContextEXT 函式的定義如下：

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

參數說明

應用程式可以呼叫 xrDestroySpatialContextEXT 函式，在完成空間實體探索和更新工作後，釋出 spatialContext 控制代碼和基礎資源。如果沒有其他有效的 XrSpatialContextEXT 是以與 spatialContext 相同的空間功能建立，這項呼叫會建議執行階段停用這些功能所需的追蹤服務，以節省系統資源。

有效用途 (隱含)

執行緒安全

  • 存取 spatialContext 和任何子項控制代碼時，必須從外部同步

傳回代碼

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

空間實體表示法

空間實體 ID

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT 用於代表執行階段在使用者空間環境中偵測到的任何實體。XrSpatialEntityIdEXT 適用於偵測到該 ID 的 XrSpatialContextEXT，且執行階段不得在同一個 XrSpatialContextEXT 中，為不同實體重複使用相同的 XrSpatialEntityIdEXT。此外，無論是否代表相同實體，執行階段不得在同一個 XrSession 的多個 XrSpatialContextEXT 中重複使用相同的 XrSpatialEntityIdEXT。

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT 是保留值，代表無效的 XrSpatialEntityIdEXT。只有在明確允許的情況下，才能傳遞至 API 函式，並從 API 函式傳回。

空間實體控制代碼

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

XrSpatialEntityEXT 控制代碼代表空間實體。應用程式可以建立這類控制代碼，向執行階段表示對特定實體感興趣。

從 ID 建立空間實體控制代碼

xrCreateSpatialEntityFromIdEXT 函式的定義如下：

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

參數說明

應用程式可以使用 xrCreateSpatialEntityFromIdEXT 建立 XrSpatialEntityEXT 控制代碼，參照使用者環境中的實體。

如果 XrSpatialEntityFromIdCreateInfoEXT :: entityId 不是 spatialContext 的有效 ID，執行階段必須傳回 XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT。

有效用途 (隱含)

傳回代碼

成功

  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialEntityFromIdCreateInfoEXT 結構定義如下：

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • entityId 是應用程式要建立控制代碼的實體 XrSpatialEntityIdEXT。

有效用途 (隱含)

刪除空間實體控制代碼

xrDestroySpatialEntityEXT 函式的定義如下：

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

參數說明

如果應用程式不再需要這個控制代碼參照的實體，可以使用 xrDestroySpatialEntityEXT 釋出 spatialEntity 控制代碼。

有效用途 (隱含)

執行緒安全

  • 存取 spatialEntity 和任何子項控制代碼時，必須從外部同步

傳回代碼

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

空間快照

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

應用程式可以建立空間快照，以便探索空間實體，或更新已知空間實體的資訊。XrSpatialSnapshotEXT 控制代碼代表已偵測或更新的空間實體，以及應用程式所選元件子集的不可變資料。空間快照代表實體及其元件資料的一致檢視畫面。快照建立後，快照的資料在快照有效期間必須保持不變。

應用程式「可以」建立任意數量的快照，但「必須」注意為每個新快照分配的記憶體，且在不再需要快照時「必須」將其刪除。

建立探索快照

xrCreateSpatialDiscoverySnapshotAsyncEXT 函式的定義如下：

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

參數說明

應用程式可以使用 xrCreateSpatialDiscoverySnapshotAsyncEXT 建立探索快照，藉此探索空間實體。

這個函式會啟動非同步作業，並建立對應的 XrFutureEXT，可與 xrPollFutureEXT 和相關函式搭配使用。這個函式的傳回值只會指出參數是否可接受排定非同步作業。對應的完成函式為 xrCreateSpatialDiscoverySnapshotCompleteEXT，當這個函式的 Future 處於 READY 狀態時，即可使用這個函式，並由該函式在完成結構 XrCreateSpatialDiscoverySnapshotCompletionEXT 中填入輸出內容。

應用程式可以提交多個探索快照建立要求，不必等待前一個要求完成。執行階段「可能」會以任何順序處理及完成快照建立作業。如果執行階段因裝置的電力、溫度或其他政策而需要減少系統資源用量，則可能會延遲完成探索快照建立作業，以限制應用程式。

應用程式可以使用 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes，篩選實體清單和元件，執行階段必須將這些元件的資料納入快照。如果應用程式在 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中提供有效的空間元件類型清單，則執行階段必須只在快照中包含至少具有 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中提供的其中一個元件的空間實體。此外，執行階段必須只包含快照中這些元件的資料。

建立 spatialContext 時，如果 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中的任何 XrSpatialComponentTypeEXT 未針對傳遞至 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的空間功能啟用，執行階段必須傳回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT。

如果應用程式未在 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中提供空間元件類型清單，執行階段必須在快照中納入所有空間實體，這些實體具有 XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents 中列舉的元件組合，適用於為 spatialContext 設定的功能。執行階段必須包含為 spatialContext 設定的功能中，所有已啟用元件的資料。

如果 XrEventDataReferenceSpaceChangePending 在 future 完成前排入佇列，且 XrEventDataReferenceSpaceChangePending :: poseValid 為 false，則執行階段可能會建立不含實體的 XrSpatialSnapshotEXT，或將無法再定位的實體 XrSpatialEntityTrackingStateEXT 設為 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT 或 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT，位置在 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace 的 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time。執行階段「不得」因 XrEventDataReferenceSpaceChangePending 而將 XrCreateSpatialContextCompletionEXT :: futureResult 設為錯誤代碼。

有效用途 (隱含)

傳回代碼

成功

  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialDiscoverySnapshotCreateInfoEXT 結構定義如下：

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

成員說明

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

XrSpatialDiscoverySnapshotCreateInfoEXT 結構描述了在探索空間實體時，建立 XrSpatialSnapshotEXT 控制代碼的資訊。

有效用途 (隱含)

xrCreateSpatialDiscoverySnapshotCompleteEXT 函式的定義如下：

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

參數說明

xrCreateSpatialDiscoverySnapshotCompleteEXT 會完成由 xrCreateSpatialDiscoverySnapshotAsyncEXT 啟動的非同步作業。如果 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future 未處於就緒狀態，執行階段必須傳回 XR_ERROR_FUTURE_PENDING_EXT。如果 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future 已完成或取消，執行階段必須傳回 XR_ERROR_FUTURE_INVALID_EXT。

有效用途 (隱含)

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • 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_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrCreateSpatialDiscoverySnapshotCompletionInfoEXT 結構定義如下：

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

成員說明

建立的快照中，各種元件資料的位置會以 baseSpace 表示，位於 time。

有效用途 (隱含)

XrCreateSpatialDiscoverySnapshotCompletionEXT 結構定義如下：

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。
  • futureResult 是空間探索快照建立作業的 XrResult。
  • snapshot 是 XrSpatialSnapshotEXT，可用於查詢偵測到的空間實體元件資料。

未來退貨代碼

futureResult 值：

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

有效用途 (隱含)

探索推薦事件

XrEventDataSpatialDiscoveryRecommendedEXT 結構定義如下：

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。
  • spatialContext 是執行階段建議探索的 XrSpatialContextEXT。

應用程式「可以」使用 xrPollEvent 擷取這個事件。應用程式可以等待這個事件，避免過度呼叫 xrCreateSpatialDiscoverySnapshotAsyncEXT 來探索空間實體。如果應用程式在兩個 XrEventDataSpatialDiscoveryRecommendedEXT 事件之間，使用相同的 XrSpatialDiscoverySnapshotCreateInfoEXT 建立多個探索快照，產生的快照可能包含相同的實體，因此建立快照和查詢資料會浪費資源。

等待這個事件建立新的探索快照，可確保應用程式不會向系統傳送過多探索要求，因為執行階段可能不會傳回任何新資料，而且有助於避免過度使用系統資源，以及因裝置的電源或散熱政策而受到節流。這也有助於讓執行階段保持一致，無論是透過即時追蹤動態探索空間實體，還是根據先前記錄的狀態提供空間實體 (執行階段可能只會為每個 XrSpatialContextEXT 佇列一次探索建議事件)。

執行階段「不得」將此事件排入佇列，通知應用程式現有空間實體的元件資料有所變更或調整。應用程式可以使用 xrCreateSpatialUpdateSnapshotEXT，追蹤感興趣空間實體的元件資料更新。

執行階段可以將探索建議事件排入佇列，不必等待應用程式先呼叫 xrCreateSpatialDiscoverySnapshotAsyncEXT。舉例來說，執行階段可能會根據 XrSpatialContextEXT 的設定、對使用者周遭環境的瞭解 (發現新實體或失去現有實體)，或向應用程式提示適當的探索要求頻率，以免系統資源超載，決定是否將探索建議事件排入佇列。如果 XrSpatialContextEXT 的整個生命週期內，在使用者環境中找不到任何實體，執行階段可能會選擇不將此事件排入 XrSpatialContextEXT 的佇列。

在應用程式使用 xrCreateSpatialContextCompleteEXT 完成建立作業前，執行階段不得將指定 spatialContext 的事件排入佇列。

應用程式呼叫 xrDestroySpatialContextEXT 後，執行階段不得再為該空間情境排入任何探索建議事件，也不得從 xrPollEvent 傳回該情境的任何這類事件。

有效用途 (隱含)

查詢元件資料

xrQuerySpatialComponentDataEXT 函式的定義如下：

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

參數說明

應用程式可以使用 xrQuerySpatialComponentDataEXT 查詢快照中實體的元件資料，方法是將清單結構附加至 XrSpatialComponentDataQueryResultEXT :: next，對應至 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中的每個 XrSpatialComponentTypeEXT。

如果應用程式將清單結構附加至 XrSpatialComponentDataQueryResultEXT :: next，但該結構不對應 XrSpatialComponentDataQueryConditionEXT :: componentTypes 列出的任何元件，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

應用程式可以選擇只附加 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中列出的部分元件對應的清單結構。如果應用程式只想知道符合 queryCondition 的空間實體 ID 和追蹤狀態，可以選擇完全省略清單結構。執行階段「不得」將 XrSpatialComponentDataQueryResultEXT :: next 鏈結中缺少清單結構視為失敗。

如果 XrEventDataReferenceSpaceChangePending 已排入佇列，且應用程式從 XrSpatialSnapshotEXT 查詢元件資料時，XrEventDataReferenceSpaceChangePending :: changeTime 已過，則應用程式可能會使用事件資料相應調整姿勢。

執行階段必須填入 XrSpatialComponentDataQueryResultEXT :: entityIds，且只能包含具有 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中指定的所有元件的實體。如果 XrSpatialComponentDataQueryConditionEXT :: componentTypeCount 為 0，執行階段必須在 queryResult 中填入快照中的所有實體 (及其追蹤狀態)。如果將其他查詢條件新增至 XrSpatialComponentDataQueryConditionEXT :: next，執行階段必須將這些條件視為「AND」與元件類型可用性，也就是說，執行階段必須僅使用符合所有提供條件的實體填入 XrSpatialComponentDataQueryResultEXT ::entityIds。執行階段必須按照 XrSpatialComponentDataQueryResultEXT :: entityIds 中實體的順序，在清單結構中填入元件資料，也就是說，清單結構陣列中特定索引處的元件資料，必須對應至相同索引處的實體。

如果實體的追蹤狀態不是 XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT，執行階段「不得」變更陣列中該實體對應索引的資料，該陣列位於附加至 XrSpatialComponentDataQueryResultEXT 的清單結構中。

有效用途 (隱含)

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

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

舉例來說，應用程式會建立包含 5 個實體的 XrSpatialSnapshotEXT，其中：

  • 實體 1 和 2 包含元件 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 和 XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • 實體 3 和 4 包含元件 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT 和 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
  • 實體 5 包含 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 和 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件。

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

是

是

是

是

否

否

否

否

是

是

父項

父項

是

是

是

是

否

否

否

否

否

否

Mesh3D

Mesh3D

否

否

否

否

是

是

是

是

是

是

Bounded3D

Bounded3D

否

否

否

否

是

是

是

是

否

否 Text is not SVG - cannot display

圖 20. 範例快照

在上述快照上使用 xrQuerySpatialComponentDataEXT，並在查詢條件中列出 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT，系統會將實體 #1、#2 和 #5 傳回應用程式，應用程式可以將 XrSpatialBounded2DDataEXT 陣列附加為 XrSpatialComponentBounded2DListEXT 結構的一部分，附加至 XrSpatialComponentDataQueryResultEXT 的下一個鏈結，以取得 bounded2D 資料。

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

entityId #1 的資料

實體資料...

entityId #2 的資料

實體資料...

entityId #5 的資料

實體資料...

entityIds

entityIds

下一個

下一個

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

bounds

bounds

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... 文字並非 SVG，無法顯示

圖 21. 查詢結果範例

在上述快照上使用 xrQuerySpatialComponentDataEXT，並在查詢條件中列出 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT 和 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 元件，系統會將實體 #3 和 #4 傳回應用程式，應用程式可以將 XrBoxf 和 XrSpatialMeshDataEXT 陣列分別附加為 XrSpatialComponentBounded3DListEXT 和 XrSpatialComponentMesh3DListEXT 結構的一部分，附加至 XrSpatialComponentDataQueryResultEXT 的下一個鏈結，以取得元件資料。

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

entityId #3 的資料

實體資料...

entityId #4 的資料

實體資料...

Mesh3D

Mesh3D

entityId #3 的資料

實體資料...

entityId #4 的資料

實體資料...

entityIds

entityIds

下一個

下一個

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

bounds

bounds

下一個

下一個

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

網格

網格 Text is not SVG - cannot display

圖 22. 查詢結果範例

XrSpatialComponentDataQueryConditionEXT 結構定義如下：

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。
  • componentTypeCount 是 uint32_t，用於描述 componentTypes 陣列中的元素數量。
  • componentTypes 是 XrSpatialComponentTypeEXT 陣列，用於從快照取得資料。

有效用途 (隱含)

XrSpatialComponentDataQueryResultEXT 結構定義如下：

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。
  • entityIdCapacityInput 是 entityIds 陣列的容量，或 0 表示要求擷取所需容量。
  • entityIdCountOutput 是 entityIds 中的 XrSpatialEntityIdEXT 數量，或 entityIdCapacityInput 不足時所需的容量。
  • entityIds 是 XrSpatialEntityIdEXT 的陣列。如果 entityIdCapacityInput 為 0，則可以是 NULL。
  • entityStateCapacityInput 是 entityStates 陣列的容量，或 0 表示要求擷取所需容量。
  • entityStateCountOutput 是 entityStates 中 XrSpatialEntityTrackingStateEXT 的數量，或 entityStateCapacityInput 不足時所需的容量。這個值必須一律與 entityIdCountOutput 相同。
  • entityStates 是 XrSpatialEntityTrackingStateEXT 的陣列。如果 entityStateCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 entityIds 大小，請參閱「緩衝區大小參數」一節。

應用程式可以搭配 xrCreateSpatialEntityFromIdEXT 使用 entityIds，為要定期更新的實體建立 XrSpatialEntityEXT 控制代碼。應用程式可以將這些 XrSpatialEntityEXT 控制代碼與 xrCreateSpatialUpdateSnapshotEXT 搭配使用，建立更新快照，其中包含執行階段最新已知的實體元件資料。

有效用途 (隱含)

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

XrSpatialEntityTrackingStateEXT 會列舉可能的空間實體追蹤狀態：

列舉的意義如下：

列舉說明

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

執行階段已停止追蹤這個實體，且不會再繼續追蹤。

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

執行階段已暫停追蹤這個實體，但日後可能會繼續追蹤。

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

執行階段目前正在追蹤這個實體，且其元件資料有效。

追蹤

已暫停

STOPPED

圖 23. XrSpatialEntityTrackingStateEXT

  • 如果執行階段暫停追蹤空間實體，但日後可能恢復追蹤，則可能會將空間實體的狀態從 XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT 變更為 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT。執行階段「可能」執行這項操作的情況包括 (但不限於)：應用程式失去輸入焦點；指定的空間實體距離使用者太遠，無法準確追蹤；或追蹤的實體過多，執行階段想要降低追蹤成本。XrSpatialEntityTrackingStateEXT 可協助應用程式不受各執行階段的不同追蹤政策影響。
  • 執行階段可能會將實體狀態從 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT 變更為 XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT 或 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT。
  • 如果空間實體遺失，且追蹤功能無法復原或恢復，執行階段必須將空間實體的狀態從 XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT 或 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT 變更為 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT。舉例來說，如果裝置失去追蹤、重新啟動追蹤工作階段，但無法在環境中重新定位，就會將這個追蹤工作階段中發現的實體視為新實體。
  • 實體的追蹤狀態設為 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT 後，執行階段「絕對不得」變更為任何其他狀態。
  • 使用 xrQuerySpatialComponentDataEXT 查詢空間實體的元件資料時，如果實體狀態為 XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT，執行階段必須在 XrSpatialComponentDataQueryResultEXT 的下一個鏈結中，於應用程式提供的緩衝區內容中設定有效資料。如果實體狀態為 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT 或 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT，執行階段「不得」變更緩衝區內容。

元件資料的雙重呼叫慣用語

XrSpatialBufferEXT 結構定義如下：

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

成員說明

  • bufferId緩衝區資料的XrSpatialBufferIdEXT。
  • bufferType 是 XrSpatialBufferTypeEXT，用於指出 bufferId 中的資料類型。應用程式可以使用 bufferType 判斷要使用哪個函式擷取緩衝區的實際資料。

部分空間元件具有可變大小的資料，因此需要使用雙呼叫慣用語來擷取資料。在這種情況下，空間元件資料結構會為該元件資料中所需的每個可變大小緩衝區，提供 XrSpatialBufferEXT。

對於相同的 bufferId，執行階段「必須」在不同元件資料查詢之間提供相同的資料，即使在不同快照之間也是如此。如果元件資料查詢呼叫之間的 bufferId 不同，應用程式就會知道該元件的資料「可能」已變更。

有效用途 (隱含)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT 用於表示空間元件的任何可變大小資料。

執行階段必須將 XrSpatialBufferIdEXT 及其資料保留在記憶體中，至少要保留到包含該資料的 XrSpatialSnapshotEXT 生命週期結束。執行階段可能會將 XrSpatialBufferIdEXT 及其資料保留在記憶體中，時間長度超過 XrSpatialSnapshotEXT 的生命週期，以便在應用程式稍後建立的快照中傳回相同的 ID。對於相同的 XrSpatialBufferIdEXT，執行階段「必須」一律透過適當的 xrGetSpatialBuffer* 函式傳回相同的資料。

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

XrSpatialBufferTypeEXT 列舉會識別 XrSpatialBufferIdEXT 代表的緩衝區資料類型。

列舉說明

xrGetSpatialBufferStringEXT 函式的定義如下：

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

參數說明

  • snapshot 是 XrSpatialSnapshotEXT 的控制代碼。
  • info 包含要查詢的緩衝區資訊。
  • bufferCapacityInput 是陣列的容量，或 0 表示要求擷取所需容量。
  • bufferCountOutput 是字元數，或 bufferCapacityInput 不足時所需的容量。
  • buffer 是 char 的陣列。如果 bufferCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 buffer 大小，請參閱「緩衝區大小參數」一節。

應用程式可以使用 xrGetSpatialBufferStringEXT，取得元件提供的 XrSpatialBufferEXT 資料，其中 XrSpatialBufferEXT :: bufferType 為 XR_SPATIAL_BUFFER_TYPE_STRING_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_STRING_EXT，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不屬於 snapshot，執行階段必須傳回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

由執行階段填入的 buffer「必須」是以空值結尾的 UTF-8 字串。

有效用途 (隱含)

  • 必須先啟用 XR_EXT_spatial_entity 擴充功能，才能呼叫 xrGetSpatialBufferStringEXT
  • snapshot「必須」是有效的 XrSpatialSnapshotEXT 控制代碼
  • info「必須」是指向有效 XrSpatialBufferGetInfoEXT 結構的指標
  • bufferCountOutput「必須」是指向 uint32_t 值的指標
  • 如果 bufferCapacityInput 不是 0，buffer「必須」是指向 bufferCapacityInput 個字元值陣列的指標

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

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

xrGetSpatialBufferUint8EXT 函式的定義如下：

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

參數說明

  • snapshot 是 XrSpatialSnapshotEXT 的控制代碼。
  • info 包含要查詢的緩衝區資訊。
  • bufferCapacityInput 是陣列的容量，或 0 表示要求擷取所需容量。
  • bufferCountOutput 是 buffer 陣列中的元素數量，或 bufferCapacityInput 不足時所需的容量。
  • buffer 是 uint8_t 的陣列。如果 bufferCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 buffer 大小，請參閱「緩衝區大小參數」一節。

應用程式可以使用 xrGetSpatialBufferUint8EXT，取得元件提供的 XrSpatialBufferEXT 資料，其中 XrSpatialBufferEXT :: bufferType 為 XR_SPATIAL_BUFFER_TYPE_UINT8_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_UINT8_EXT，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不屬於 snapshot，執行階段必須傳回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用途 (隱含)

  • 必須先啟用 XR_EXT_spatial_entity 擴充功能，才能呼叫 xrGetSpatialBufferUint8EXT
  • snapshot「必須」是有效的 XrSpatialSnapshotEXT 控制代碼
  • info「必須」是指向有效 XrSpatialBufferGetInfoEXT 結構的指標
  • bufferCountOutput「必須」是指向 uint32_t 值的指標
  • 如果 bufferCapacityInput 不是 0，buffer「必須」是指向 bufferCapacityInput uint8_t 值陣列的指標

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

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

xrGetSpatialBufferUint16EXT 函式的定義如下：

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

參數說明

  • snapshot 是 XrSpatialSnapshotEXT 的控制代碼。
  • info 包含要查詢的緩衝區資訊。
  • bufferCapacityInput 是陣列的容量，或 0 表示要求擷取所需容量。
  • bufferCountOutput 是 buffer 陣列中的元素數量，或 bufferCapacityInput 不足時所需的容量。
  • buffer 是 uint16_t 的陣列。如果 bufferCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 buffer 大小，請參閱「緩衝區大小參數」一節。

應用程式可以使用 xrGetSpatialBufferUint16EXT，取得元件提供的 XrSpatialBufferEXT 資料，其中 XrSpatialBufferEXT :: bufferType 為 XR_SPATIAL_BUFFER_TYPE_UINT16_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_UINT16_EXT，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不屬於 snapshot，執行階段必須傳回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用途 (隱含)

  • 呼叫 xrGetSpatialBufferUint16EXT 之前，必須啟用 XR_EXT_spatial_entity 擴充功能
  • snapshot「必須」是有效的 XrSpatialSnapshotEXT 控制代碼
  • info「必須」是指向有效 XrSpatialBufferGetInfoEXT 結構的指標
  • bufferCountOutput「必須」是指向 uint32_t 值的指標
  • 如果 bufferCapacityInput 不是 0，buffer「必須」是指向 bufferCapacityInput uint16_t 值陣列的指標

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

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

xrGetSpatialBufferUint32EXT 函式的定義如下：

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

參數說明

  • snapshot 是 XrSpatialSnapshotEXT 的控制代碼。
  • info 包含要查詢的緩衝區資訊。
  • bufferCapacityInput 是陣列的容量，或 0 表示要求擷取所需容量。
  • bufferCountOutput 是 buffer 陣列中的元素數量，或 bufferCapacityInput 不足時所需的容量。
  • buffer 是 uint32_t 的陣列。如果 bufferCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 buffer 大小，請參閱「緩衝區大小參數」一節。

應用程式可以使用 xrGetSpatialBufferUint32EXT，取得元件提供的 XrSpatialBufferEXT 資料，其中 XrSpatialBufferEXT :: bufferType 為 XR_SPATIAL_BUFFER_TYPE_UINT32_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_UINT32_EXT，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不屬於 snapshot，執行階段必須傳回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用途 (隱含)

  • 呼叫 xrGetSpatialBufferUint32EXT 之前，必須啟用 XR_EXT_spatial_entity 擴充功能
  • snapshot「必須」是有效的 XrSpatialSnapshotEXT 控制代碼
  • info「必須」是指向有效 XrSpatialBufferGetInfoEXT 結構的指標
  • bufferCountOutput「必須」是指向 uint32_t 值的指標
  • 如果 bufferCapacityInput 不是 0，buffer「必須」是指向 bufferCapacityInput uint32_t 值陣列的指標

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

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

xrGetSpatialBufferFloatEXT 函式的定義如下：

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

參數說明

  • snapshot 是 XrSpatialSnapshotEXT 的控制代碼。
  • info 包含要查詢的緩衝區資訊。
  • bufferCapacityInput 是陣列的容量，或 0 表示要求擷取所需容量。
  • bufferCountOutput 是 buffer 陣列中的元素數量，或 bufferCapacityInput 不足時所需的容量。
  • buffer 是 float 的陣列。如果 bufferCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 buffer 大小，請參閱「緩衝區大小參數」一節。

應用程式可以使用 xrGetSpatialBufferFloatEXT，取得元件提供的 XrSpatialBufferEXT 資料，其中 XrSpatialBufferEXT :: bufferType 為 XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不屬於 snapshot，執行階段必須傳回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用途 (隱含)

  • 必須先啟用 XR_EXT_spatial_entity 擴充功能，才能呼叫 xrGetSpatialBufferFloatEXT
  • snapshot「必須」是有效的 XrSpatialSnapshotEXT 控制代碼
  • info「必須」是指向有效 XrSpatialBufferGetInfoEXT 結構的指標
  • bufferCountOutput「必須」是指向 uint32_t 值的指標
  • 如果 bufferCapacityInput 不是 0，buffer「必須」是指向 bufferCapacityInput float 值陣列的指標

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

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

xrGetSpatialBufferVector2fEXT 函式的定義如下：

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

參數說明

  • snapshot 是 XrSpatialSnapshotEXT 的控制代碼。
  • info 包含要查詢的緩衝區資訊。
  • bufferCapacityInput 是陣列的容量，或 0 表示要求擷取所需容量。
  • bufferCountOutput 是 buffer 陣列中的元素數量，或 bufferCapacityInput 不足時所需的容量。
  • buffer 是 XrVector2f 陣列。如果 bufferCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 buffer 大小，請參閱「緩衝區大小參數」一節。

應用程式「可以」使用 xrGetSpatialBufferVector2fEXT，取得元件提供的 XrSpatialBufferEXT 資料，其中 XrSpatialBufferEXT :: bufferType 為 XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不屬於 snapshot，執行階段必須傳回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用途 (隱含)

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

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

xrGetSpatialBufferVector3fEXT 函式的定義如下：

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

參數說明

  • snapshot 是 XrSpatialSnapshotEXT 的控制代碼。
  • info 包含要查詢的緩衝區資訊。
  • bufferCapacityInput 是陣列的容量，或 0 表示要求擷取所需容量。
  • bufferCountOutput 是 buffer 陣列中的元素數量，或 bufferCapacityInput 不足時所需的容量。
  • buffer 是 XrVector3f 陣列。如果 bufferCapacityInput 為 0，則可以是 NULL。
  • 如要進一步瞭解如何擷取必要的 buffer 大小，請參閱「緩衝區大小參數」一節。

應用程式可以使用 xrGetSpatialBufferVector3fEXT，取得元件提供的 XrSpatialBufferEXT 資料，其中 XrSpatialBufferEXT :: bufferType 為 XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT。

如果 XrSpatialBufferGetInfoEXT :: bufferId 的 XrSpatialBufferTypeEXT 不是 XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

如果 XrSpatialBufferGetInfoEXT :: bufferId 不屬於 snapshot，執行階段必須傳回 XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT。

有效用途 (隱含)

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

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

XrSpatialBufferGetInfoEXT 結構定義如下：

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。
  • bufferId：要擷取資料的緩衝區 XrSpatialBufferIdEXT。

有效用途 (隱含)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT 是保留值，代表無效的 XrSpatialBufferIdEXT。只有在明確允許的情況下，才能傳遞至 API 函式，並從 API 函式傳回。

建立更新快照

xrCreateSpatialUpdateSnapshotEXT 函式的定義如下：

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

參數說明

應用程式可以使用 xrCreateSpatialUpdateSnapshotEXT 建立快照，並取得執行階段已知的特定實體最新元件資料。應用程式可以在建立快照時，提供 XrSpatialEntityEXT 控制代碼和感興趣的元件類型。

應用程式可以使用 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes，篩選資料必須包含在快照中的元件清單。如果應用程式在 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中提供有效的空間元件類型清單，則執行階段必須在快照中只包含至少具有 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中提供的其中一個元件的空間實體。此外，執行階段必須只包含快照中這些元件的資料。

如果 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中的任何 XrSpatialComponentTypeEXT，未針對建立 spatialContext 時傳遞至 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的空間功能啟用，執行階段必須傳回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT。

如果應用程式未在 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中提供空間元件類型清單，執行階段必須在快照中納入 XrSpatialUpdateSnapshotCreateInfoEXT :: entities 列出的所有空間實體，且必須納入為 spatialContext 設定的功能中，所有已啟用元件的資料。

執行階段「不得」包含 snapshot 中 XrSpatialUpdateSnapshotCreateInfoEXT :: entities 未列出的空間實體。

應用程式「可以」建立任意數量的快照，但「必須」注意為每個新快照分配的記憶體，且在不再需要快照時「必須」將其刪除。

有效用途 (隱含)

傳回代碼

成功

  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialUpdateSnapshotCreateInfoEXT 結構定義如下：

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • entityCount 是 uint32_t，用於描述 entities 陣列中的元素數量。
  • entities 是 XrSpatialEntityEXT 陣列，執行階段必須在快照中加入元件資料。
  • componentTypeCount 是 uint32_t，用於描述 componentTypes 陣列中的元素數量。
  • componentTypes 是 XrSpatialComponentTypeEXT 陣列，執行階段「必須」在快照中加入該陣列的資料。
  • baseSpace 是 XrSpace，更新後的 XrSpatialSnapshotEXT 所有位置都會相對於此空間。
  • time 是 XrTime，更新 XrSpatialSnapshotEXT 的所有位置都會位於此處。

有效用途 (隱含)

  • 必須先啟用 XR_EXT_spatial_entity 擴充功能，才能使用 XrSpatialUpdateSnapshotCreateInfoEXT
  • type「必須」為 XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
  • next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標
  • entities「必須」是指向 entityCount 個有效 XrSpatialEntityEXT 控制代碼陣列的指標
  • 如果 componentTypeCount 不是 0，componentTypes 必須是指向 componentTypeCount 個有效 XrSpatialComponentTypeEXT 值陣列的指標
  • baseSpace「必須」是有效的 XrSpace 帳號代碼
  • entityCount 參數必須大於 0
  • baseSpace 和 entities 的元素必須已建立、分配或從同一個 XrSession 擷取

刪除快照

xrDestroySpatialSnapshotEXT 函式的定義如下：

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

參數說明

應用程式可以呼叫 xrDestroySpatialSnapshotEXT，刪除 XrSpatialSnapshotEXT 控制代碼和相關聯的資源。

有效用途 (隱含)

執行緒安全

  • 存取 snapshot 和任何子項控制代碼時，必須從外部同步

傳回代碼

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

常見元件

有界 2D

元件資料

XrSpatialBounded2DDataEXT 結構定義如下：

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

成員說明

  • center 是 XrPosef，用於定義有界限 2D 元件的幾何中心。
  • extents 是有界限 2D 元件沿著 X 軸 (extents.width) 和 Y 軸 (extents.height) 的範圍，以 center 為中心。

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 的 extents 是指實體在平面座標系統的 x-y 平面中的大小。如果平面的位置為 {0, 0, 0}、旋轉角度為 {0, 0, 0, 1} (無旋轉)，且範圍為 {1, 1}，則表示該平面為 1 公尺 x 1 公尺，中心點為 {0, 0, 0}，且其正面法向量指向元件空間中的 +Z 方向。

X X Y Y Z Z 高度 高度 Y Y Z Z X X 垂直平面 垂直平面 水平平面 水平平面 寬度 寬度 寬度 寬度 高度 高度

圖 24. Bounded2D 元件座標系統

注意事項

OpenXR 使用 X-Y 平面，+Z 為平面法線，但其他 API 可能使用 X-Z 平面，+Y 為平面法線。只要繞著 +X 軸旋轉 -π/2 弧度，即可將 X-Y 平面轉換為 X-Z 平面。

有效用途 (隱含)

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

XrSpatialComponentBounded2DListEXT 結構定義如下：

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

成員說明

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

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

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

如果 xrQuerySpatialComponentDataEXT :: snapshot 是透過 xrCreateSpatialDiscoverySnapshotCompleteEXT 建立，則執行階段必須在 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace 和 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time 中提供 XrSpatialBounded2DDataEXT :: center。

如果 xrQuerySpatialComponentDataEXT :: snapshot 是透過 xrCreateSpatialUpdateSnapshotEXT 建立，則執行階段必須在 XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace 和 XrSpatialUpdateSnapshotCreateInfoEXT :: time 中提供 XrSpatialBounded2DDataEXT :: center。

有效用途 (隱含)

設定

如果 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 列舉在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中，代表某項功能，應用程式可以在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉值，啟用該功能。這個元件不需要任何特殊設定，即可納入 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一個鏈結。

有邊界的 3D

元件資料

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT 使用 XrBoxf 儲存資料。

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

XrSpatialComponentBounded3DListEXT 結構定義如下：

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

成員說明

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

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

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

如果 xrQuerySpatialComponentDataEXT :: snapshot 是透過 xrCreateSpatialDiscoverySnapshotCompleteEXT 建立，則執行階段必須在 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace 的 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time 提供 XrBoxf :: center。

如果 xrQuerySpatialComponentDataEXT :: snapshot 是透過 xrCreateSpatialUpdateSnapshotEXT 建立，則執行階段必須在 XrSpatialUpdateSnapshotCreateInfoEXT :: time 的 XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace 中提供 XrBoxf :: center。

有效用途 (隱含)

  • 必須先啟用 XR_EXT_spatial_entity 擴充功能，才能使用 XrSpatialComponentBounded3DListEXT
  • type「必須」為 XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
  • next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標
  • bounds「必須」是指向 boundCount XrBoxf 結構陣列的指標
  • boundCount 參數必須大於 0
設定

如果 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中列舉，應用程式可以在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉，啟用該功能。這個元件不需要任何特殊設定，即可納入 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一個鏈結。

父項

元件資料

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT 使用 XrSpatialEntityIdEXT 儲存資料。

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

XrSpatialComponentParentListEXT 結構定義如下：

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

成員說明

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

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

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

有效用途 (隱含)

  • 必須先啟用 XR_EXT_spatial_entity 擴充功能，才能使用 XrSpatialComponentParentListEXT
  • type「必須」為 XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
  • next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標
  • parents「必須」是指向 parentCount XrSpatialEntityIdEXT 值陣列的指標
  • parentCount 參數必須大於 0
設定

如果 XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中列舉，應用程式可以在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉，啟用該功能。這個元件不需要任何特殊設定，即可納入 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一個鏈結。

網格 3D

元件資料

XrSpatialMeshDataEXT 結構定義如下：

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

成員說明

  • origin 是定義網格原點的 XrPosef。網格的所有頂點都必須相對於這個原點。
  • vertexBuffer 是 XrSpatialBufferEXT，提供緩衝區 ID，代表這個元件所在實體的頂點緩衝區。頂點的位置必須相對於 origin。
  • indexBuffer 是 XrSpatialBufferEXT，提供緩衝區的 ID，代表三角形索引陣列，指定 vertexBuffer 中網格頂點的索引。三角形索引必須以逆時針順序傳回，且三個索引代表一個三角形。

使用 XrSpatialMeshDataEXT 的元件類型必須指定 vertexBuffer 和 indexBuffer 的 XrSpatialBufferTypeEXT。

有效用途 (隱含)

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

XrSpatialComponentMesh3DListEXT 結構定義如下：

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

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。
  • meshCount 是 uint32_t，用於描述 meshes 陣列中的元素數量。
  • meshes 是 XrSpatialMeshDataEXT 的陣列。

應用程式可以查詢 XrSpatialSnapshotEXT 中空間實體的網格 3D 元件，方法是在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中新增 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT，並將 XrSpatialComponentMesh3DListEXT 新增至 XrSpatialComponentDataQueryResultEXT 的下一個指標鏈結。

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

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

對於執行階段在 meshes 陣列中填入的 XrSpatialMeshDataEXT，XrSpatialMeshDataEXT :: vertexBuffer 的 XrSpatialBufferEXT :: bufferType「必須」為 XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT，XrSpatialMeshDataEXT :: indexBuffer 的 XrSpatialBufferEXT :: bufferType「必須」為 XR_SPATIAL_BUFFER_TYPE_UINT32_EXT。

有效用途 (隱含)

設定

如果 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中列舉，則應用程式可以啟用該功能，方法是在支援此元件的功能的 XrSpatialCapabilityConfigurationBaseHeaderEXT 衍生結構的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入該列舉。

這個元件不需要任何特殊設定，即可納入 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一個鏈結。

追蹤狀態篩選器

XrSpatialFilterTrackingStateEXT 結構定義如下：

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

成員說明

應用程式可以在 XrSpatialDiscoverySnapshotCreateInfoEXT 的下一個鏈結中使用 XrSpatialFilterTrackingStateEXT，將探索範圍限定在追蹤狀態為 trackingState 的實體。

應用程式可以在 XrSpatialComponentDataQueryConditionEXT 的下一個鏈結中使用 XrSpatialFilterTrackingStateEXT，將快照中的元件資料查詢範圍，限定為追蹤狀態為 trackingState 的實體。

有效用途 (隱含)

範例程式碼

應用程式使用情形

應用程式通常會以下列模式使用空間實體擴充功能：

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

以下程式碼範例說明如何探索「Foo」功能的空間實體，並查詢其元件資料。

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

auto waitUntilReady = [](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&fooConfig));

  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;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components.
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT future = XR_NULL_FUTURE_EXT;
  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 bounded2d component data
    XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT;
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = &componentToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    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) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

    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
  // ...
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

查詢緩衝區資料

下列程式碼範例說明如何取得提供 XrSpatialBufferEXT 的元件資料。

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

擴充功能規範

語意標籤設計和擴充功能指南

雖然這項擴充功能並未定義任何用於傳達實體語意標籤資訊的元件，但它為定義這類元件的任何擴充功能制定了設計規則和指南。在以下文字中，「應」和「必須」會限制這類功能的作者，而非限制執行階段實作或使用 API 的應用程式。

  • 如果擴充功能為任何 XrSpatialCapabilityEXT 定義語意標籤，則應定義新的 XrSpatialComponentTypeEXT，以及含有標籤組合 (「語意標籤組合」) 的新列舉，做為該元件的資料。
  • 代表語意標籤集的列舉必須有值，表示實體未歸類到這個集合的任何標籤。這個列舉值的名稱必須包含「UNCATEGORIZED」，例如 XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT。這個值會向應用程式指出，執行階段確實能辨識這個實體，但這個實體已歸類到其他語意標籤組合。
  • 在 xrEnumerateSpatialCapabilityComponentTypesEXT 中列舉這個新定義的 XrSpatialComponentTypeEXT，表示執行階段支援與該元件類型對應的語意標籤集 (以及該集合中定義的標籤)。
  • 應用程式如要探索具有此語意標籤集標籤的實體，可在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 陣列中加入對應的 XrSpatialComponentTypeEXT，該陣列位於列舉元件類型的功能設定結構中。
  • 單一空間實體可能有多個元件，每個元件都會從自己的語意標籤集提供標籤。請參考以下範例，其中包含一些假設的語意標籤集 XrSpatialObjectSemanticLabel，其值可能包括椅子、沙發、桌子等，XrSpatialSofaBrand (值可能為 IKEA、Wayfair 等) 和 XrSpatialIkeaSofa (值可能為 IKEA 沙發的特定型號名稱)。在這個情境中，同一個沙發實體具有全部 3 個元件 (來自所有 3 個語意標籤集的標籤)，每個元件都會提供不同精細程度的實體資訊。
  • 如果擴充功能定義了新的 XrSpatialComponentTypeEXT，提供新的語意標籤集，其中包含多個標籤和 UNCATEGORIZED 標籤，則擴充功能應考慮定義 XrSpatialCapabilityFeatureEXT，讓應用程式只啟用該元件類型對應的語意標籤集中定義的部分標籤。這個子集在功能設定的下一個鏈結中提供，可做為執行階段的最佳化提示，讓執行階段只追蹤提供的子集。這類特徵結構的範例如下所示。
  • 擴充功能不得為現有的語意標籤集列舉新增標籤。他們必須定義新的列舉，其中包含具有相同語義的等效列舉，以及與其他集合中的值相等的值，以及新加入的列舉。新定義的語意標籤組合規格必須建立新舊標籤組合之間的對應關係。請參閱下方範例。
語意標籤子集的空間特徵定義範例
// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;
空間語意標籤擴充功能範例
typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

以上述範例來說，擴充功能定義了列舉 XrSpatialExamplePlaneSemanticLabelExtensionEXT，以便使用代表門窗的值擴充現有的 XrSpatialPlaneSemanticLabelEXT。新列舉的規格必須包含下列格式的文字：

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====

新巨集

新底座類型

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

新物件類型

新指令

新結構

新列舉

新列舉常數

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • 擴充 XrObjectType：

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • 擴充 XrResult：

    • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
    • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

  • 擴充 XrStructureType：

    • XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
    • XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
    • XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT

問題

  • 單一實體是否一律只衍生自單一功能？

    • 已解決
    • 答案：否。這完全取決於執行階段，取決於其追蹤功能以及如何呈現偵測到的實體。規格並未規定空間實體的任何特定表示法，但保證特定功能元件會設定最低預期。執行階段「可能」可以合併不同功能偵測到的實體，並將其表示為單一實體，並保證所有有助於識別該實體的功能元件。舉例來說，平面追蹤和物件追蹤功能都能偵測到桌子，平面追蹤功能會提供實體的 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 元件，物件追蹤功能則會提供 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT。某些執行階段可能會將表格提供為 2 個獨立實體，每個實體都有各自的一組保證元件，而某些執行階段可能只會提供 1 個實體來代表表格，並在同一個實體上同時提供 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT 和 XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT。請注意，指定的空間實體最多只能有一個指定元件類型的元件。因此，如果不同功能產生的元件資料與特定實體衝突，執行階段必須將其表示為 2 個獨立實體。

版本記錄

  • 修訂版本 1，2024-04-12 (Nihav Jain，Google)

    • 初始擴充功能說明