XR_EXT_spatial_entity

名稱字串

XR_EXT_spatial_entity

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

741

修訂版本

1

批准狀態

批准

擴充功能和版本依附元件

XR_EXT_future

著作人

Nihav Jain (Google)
Jared Finder (Google)
Natalie Fleury (Meta)
田口雄一 (Meta)
Ron Bessems (Meta)
Yin Li (Microsoft)
Karthik Kadappan (Magic Leap)
Jimmy Alamparambil (ByteDance)
Zhipeng Liu (ByteDance)
Jun Yan (ByteDance)

總覽

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

這項擴充功能大致可分為以下幾部分：

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

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

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

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

空間實體

空間實體是指存在於某個空間的實體，這類實體具有各種相關聯的資料，並以元件的形式整理。可能是下列任一值：

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

透過動作系統公開的項目 (例如控制器或眼球注視) 不應模擬為空間實體。

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_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 擴充功能新增)

空間功能和設定

空間功能可定義執行階段的能力，以探索具有一組保證元件的實體。應用程式會在建立 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 建立 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 大小，請參閱「緩衝區大小參數」一節。

有效使用 (隱含)

  • 使用 XrSpatialCapabilityComponentTypesEXT 前，XR_EXT_spatial_entity 擴充功能必須啟用
  • type 必須為 XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
  • next 必須是 NULL，或是結構體鏈結中下一個結構體的有效指標
  • 如果 componentTypeCapacityInput 不是 0，componentTypes 必須是指向 componentTypeCapacityInput XrSpatialComponentTypeEXT 值陣列的指標

空間功能

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。空間脈絡控制代碼至少需要一項功能。

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

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

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

如果下一個 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，當這個函式的未來狀態為 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

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 為止 (以先到者為準)。

有效使用 (隱含)

  • XR_EXT_spatial_entity 擴充功能必須先啟用，才能使用 XrCreateSpatialContextCompletionEXT
  • type 必須為 XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
  • next 必須是 NULL，或是結構體鏈結中下一個結構體的有效指標
  • futureResult 必須是有效的 XrResult 值
  • 如果 spatialContext 不是 XR_NULL_HANDLE，spatialContext 必須是有效的 XrSpatialContextEXT 控制代碼

刪除空間背景資訊

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 對於發現該 XrSpatialEntityIdEXT 的 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。

有效使用 (隱含)

  • 使用 XrSpatialEntityFromIdCreateInfoEXT 前，XR_EXT_spatial_entity 擴充功能必須啟用
  • type 必須為 XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
  • next 必須是 NULL，或是結構體鏈結中下一個結構體的有效指標

銷毀空間實體控制代碼

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 中提供。此外，執行階段必須只在快照中納入這些元件的資料。

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

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

如果在 future 完成前將 XrEventDataReferenceSpaceChangePending 加入佇列，且 XrEventDataReferenceSpaceChangePending :: poseValid 為 false，則執行階段可能會建立不含任何實體的 XrSpatialSnapshotEXT，或將 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace 中不再可定位的實體 XrSpatialEntityTrackingStateEXT 設為 XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT 或 XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT。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。

有效使用 (隱含)

  • 使用 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT 前，XR_EXT_spatial_entity 擴充功能必須啟用
  • type 必須為 XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
  • next 必須是 NULL，或是結構體鏈結中下一個結構體的有效指標
  • baseSpace 必須是有效的 XrSpace 控制代碼

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 為該環境傳回任何這類事件。

有效使用 (隱含)

  • 必須先啟用 XR_EXT_spatial_entity 擴充功能，才能使用 XrEventDataSpatialDiscoveryRecommendedEXT。
  • type 必須為 XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
  • next 必須是 NULL，或是結構體鏈結中下一個結構體的有效指標

查詢元件資料

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 已過，應用程式可能會使用事件資料相應調整姿勢。

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

如果實體的追蹤狀態不是 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

否

否

否

否

是

是

是

是

否

沒有「文字不是 SVG - 無法顯示」

圖 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

實體 ID #1 的資料

實體資料...

實體 ID #2 的資料

實體資料...

實體 ID #5 的資料

實體資料...

entityIds

entityIds

下一個

下一個

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

界限

界限

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

實體 ID #3 的資料

實體資料...

實體 ID #4 的資料

實體資料...

Mesh3D

Mesh3D

實體 ID #3 的資料

實體資料...

實體 ID #4 的資料

實體資料...

entityIds

entityIds

下一個

下一個

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

界限

界限

下一個

下一個

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

網格

網格 文字不是 SVG，無法顯示

圖 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 是 XrSpatialEntityIdEXT 中的 entityIds 數量，或在 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 生命週期結束為止。為了傳回相同的 ID，做為應用程式稍後建立的快照一部分，執行階段可能會將 XrSpatialBufferIdEXT 及其資料保留在記憶體中，時間長度超出 XrSpatialSnapshotEXT 的生命週期。對於相同的 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);

參數說明

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

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

如果 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 char 值陣列的指標

傳回代碼

成功

  • 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);

參數說明

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

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

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

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

有效使用 (隱含)

  • 呼叫 xrGetSpatialBufferUint8EXT 前，XR_EXT_spatial_entity 擴充功能必須啟用。
  • 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);

參數說明

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

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

如果 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);

參數說明

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

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

如果 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 大小，請參閱「緩衝區大小參數」一節。

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

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

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

有效使用 (隱含)

  • 呼叫 xrGetSpatialBufferFloatEXT 前，XR_EXT_spatial_entity 擴充功能必須啟用
  • 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);

參數說明

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

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

如果 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);

參數說明

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

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

如果 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，用於擷取資料。

有效使用 (隱含)

  • 使用 XrSpatialBufferGetInfoEXT 前，XR_EXT_spatial_entity 擴充功能必須啟用
  • type 必須為 XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
  • next 必須是 NULL，或是結構體鏈結中下一個結構體的有效指標

#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 中提供。此外，執行階段「必須」只在快照中納入這些元件的資料。

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

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

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

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

有效使用 (隱含)

傳回代碼

成功

  • 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 是更新 XrSpatialSnapshotEXT 所有位置的 XrTime。

有效使用 (隱含)

  • 使用 XrSpatialUpdateSnapshotCreateInfoEXT 前，XR_EXT_spatial_entity 擴充功能必須啟用
  • 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 是沿著 x 軸 (extents.width)、y 軸 (extents.height) 的有界 2D 元件範圍，以 center 為中心。

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

X X Y Y Z Z Height Height Y Y Z Z X X Vertical plane Vertical plane Horizontal Plane Horizontal Plane Width Width Width Width Height Height

圖 24. Bounded2D 元件座標系統

注意事項

OpenXR 使用 X-Y 平面，+Z 為平面法線，但其他 API 可能使用 X-Z 平面，+Y 為平面法線。X-Y 平面可以透過繞 +X 軸旋轉 -π/2 弧度，轉換為 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 陣列中的元素數量。
  • 是 XrSpatialBounded2DDataEXT 的陣列。bounds

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

如果 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。

有效使用 (隱含)

  • 使用 XrSpatialComponentBounded2DListEXT 前，XR_EXT_spatial_entity 擴充功能必須啟用。
  • type 必須為 XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
  • next 必須是 NULL，或是結構體鏈結中下一個結構體的有效指標
  • bounds 必須是指向 boundCount XrSpatialBounded2DDataEXT 結構體陣列的指標
  • boundCount 參數必須大於 0
設定

如果 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 :: baseSpace 的 XrSpatialUpdateSnapshotCreateInfoEXT :: time 中提供 XrBoxf :: center。

有效使用 (隱含)

  • 使用 XrSpatialComponentBounded3DListEXT 前，XR_EXT_spatial_entity 擴充功能必須啟用
  • 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 的下一個鏈結中，但 XrSpatialComponentDataQueryConditionEXT ::componentTypeCount 不為零，且 XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT 未納入 XrSpatialComponentDataQueryConditionEXT :: componentTypes，則執行階段「必須」從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE。next

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

在 meshes 陣列中，由執行階段填入的 XrSpatialMeshDataEXT，XrSpatialBufferEXT :: bufferType (適用於 XrSpatialMeshDataEXT :: vertexBuffer) 必須為 XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT，而 XrSpatialBufferEXT :: bufferType (適用於 XrSpatialMeshDataEXT :: indexBuffer) 必須為 XR_SPATIAL_BUFFER_TYPE_UINT32_EXT。

有效使用 (隱含)

  • 使用 XrSpatialComponentMesh3DListEXT 前，XR_EXT_spatial_entity 擴充功能必須啟用。
  • type 必須為 XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
  • next 必須是 NULL，或是結構體鏈結中下一個結構體的有效指標
  • meshes 必須是指向 meshCount XrSpatialMeshDataEXT 結構體陣列的指標
  • meshCount 參數必須大於 0
設定

如果 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，表示執行階段支援與該元件類型對應的語意標籤集 (以及該集合中定義的標籤)。
  • 應用程式會在元件類型列舉的元件功能設定結構體中，加入對應的 XrSpatialComponentTypeEXT，藉此表示希望探索具有屬於這個語意標籤集的標籤的實體。XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 陣列。
  • 單一空間實體可能有多個元件，每個元件都會從自己的語意標籤集提供標籤。請參考以下範例，其中包含一些假設的語意標籤集 - 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 (Google 的 Nihav Jain)

    • 擴充功能初始說明