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 でのシーン理解と空間推論のコンセプトと基盤が導入されています。これにより、関連するものの異なるいくつかの機能領域が統合されます。これらの機能領域は、この拡張機能で定義されているように、広く統一された方法で列挙、構成、操作されます。この拡張機能には、これらの機能領域のいずれかの具体的な定義がないため、正式な仕様テキストはやや抽象的なものになる傾向があります。この拡張仕様のテキストに含まれる例は、説明を目的として、今後予定されている、または仮定の関連拡張機能で定義されている機能を参照している場合があります。このような追加機能を本質的に制限または指定するものではありません。

この拡張機能の主な構成要素は次のとおりです。

  • 空間エンティティ : 機能はエンティティを中心に構成されています。エンティティ自体が提供する機能はごくわずかです。
  • 空間コンポーネント : これらのエンティティには、データと動作を提供するコンポーネントが関連付けられています。
  • 空間コンポーネント タイプ : 各空間コンポーネントは特定のコンポーネント タイプであり、任意のエンティティは、任意のコンポーネント タイプの単一のコンポーネントを最大で 1 つ持ちます。
  • 空間コンテキスト : すべての空間エンティティのインタラクションは、初期化と構成フェーズの後にコンテキストで行われます。
  • 空間機能 : 空間エンティティの操作は、機能によって広く提供されます。機能とは、アプリ定義のアンカー、平面検出、画像トラッキングなど（これらに限定されない）の機能単位です。各機能は通常、個別の拡張機能（通常どおりインスタンス作成時に有効化）で定義され、作成時に特定のコンテキストに対して有効化されます。
  • 各機能は、一連のコンポーネント タイプに関連付けられています。これらのコンポーネント タイプには、その機能によって公開されるすべてのエンティティにコンポーネントが存在します。機能を定義する拡張機能は、その機能に必須のコンポーネント タイプ（「保証」）を指定します。一方、同じ拡張機能または他の拡張機能は、一部の潜在的な実装によって提供されるオプションのコンポーネント タイプを指定できます。任意の数の機能が、特定のコンポーネント タイプのコンポーネントをエンティティに提供できます。これらのコンポーネントは、それを生成した機能に関係なく、一律に使用できます。
  • 空間機能の特性 : さらに、一部の機能は構成が必要なため、機能の特性によってパラメータ化されます。

この拡張機能は、現在のシステムでサポートされている各機能によって提供されるコンポーネント（必須コンポーネントとオプションのコンポーネントの両方）を列挙するメカニズムを提供します。

実装によっては、機能に対して異なる程度のパラメータ化が必要になる場合があるため、この拡張機能は、現在のシステムで特定の機能に関連付けられている、サポートされている機能の特性を列挙するメカニズムを提供します。

この拡張機能では、幅広い機能で使用されることが想定される、いくつかの一般的なコンポーネントも定義されています。

空間エンティティ

空間エンティティは、ある空間に存在するエンティティであり、コンポーネントに整理されたさまざまな関連データを持っています。次のいずれかである可能性があります。

  • 物理的（壁や床などの平面、椅子や本棚などの物体など）
  • 仮想（別のアプリケーションまたはユーザーによって配置、共有されたコンテンツなど）
  • アプリ定義（例: アプリがエリアを「リビングルーム」や「キッチン」としてマークする、またはポイントをテレビを置く場所としてマークするなど）

コントローラや視線など、アクション システムを介して公開されるものは、空間エンティティとしてモデル化されることを意図していません。

OpenXR の空間エンティティは、エンティティ コンポーネント システムとしてモデル化されます。各空間エンティティには一連のコンポーネントがあり、各コンポーネントは、そのエンティティに固有の一連のデータと動作を提供します。

空間エンティティは、XrSpatialEntityIdEXT アトムまたは XrSpatialEntityEXT ハンドルのいずれかで表されます。詳細については、空間エンティティの表現のセクションをご覧ください。

空間コンポーネント タイプ

空間エンティティには、そのエンティティのデータや動作を提供する 1 つ以上のコンポーネントがあります。この拡張機能で定義されている一般的なコンポーネントについては、一般的なコンポーネントをご覧ください。

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 の作成時に空間機能のコンポーネントを有効にします。ランタイムは、検出されたエンティティで有効なコンポーネントのみを提供しなければなりません。たとえば、ランタイムが特定の機能のコンポーネントの 1 つが「セマンティック ラベル」であると報告した場合、アプリはその機能の構成を介してセマンティック ラベルを有効にでき、ランタイムは構成されている場合にのみセマンティック ラベル コンポーネントを提供しなければなりません。

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 コードを検出して追跡する機能。（XR_EXT_spatial_marker_tracking 拡張機能によって追加）

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

マイクロ QR コードを検出して追跡する機能。（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 で拡張機能が有効になっていない空間機能を列挙してはなりません。

有効な使用方法（暗黙的）

  • XR_EXT_spatial_entity 拡張機能は、xrEnumerateSpatialCapabilitiesEXT を呼び出す前に有効にする必要があります。
  • 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);

パラメータの説明

  • instance は XrInstance のハンドルです。
  • systemId は、空間機能コンポーネントが列挙される XrSystemId です。
  • capability は、コンポーネントが列挙される XrSpatialCapabilityEXT です。
  • capabilityComponents は XrSpatialCapabilityComponentTypesEXT へのポインタです。これは、アプリケーションによって割り当てられた配列が入力される入出力構造です。

この関数は、指定された機能がシステム内のエンティティに提供するコンポーネント タイプを、構成に従って列挙します。

アプリケーションは、XrSpatialCapabilityComponentTypesEXT :: componentTypes に列挙されているコンポーネント タイプを使用して、systemId が capability でサポートするコンポーネントの完全なセットを把握し、このリストを使用して、capability の XrSpatialContextEXT を作成する際に capability の有効な構成を判断できます。

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

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 サイズの取得の詳細については、バッファサイズ パラメータのセクションをご覧ください。

有効な使用方法（暗黙的）

  • XR_EXT_spatial_entity 拡張機能は、XrSpatialCapabilityComponentTypesEXT を使用する前に有効にする必要があります。
  • 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_EXT_spatial_entity 拡張機能は、xrEnumerateSpatialCapabilityFeaturesEXT を呼び出す前に有効にする必要があります。
  • instance は、有効な XrInstance ハンドルでなければなりません。
  • capability は、有効な XrSpatialCapabilityEXT 値でなければなりません
  • capabilityFeatureCountOutput は uint32_t 値へのポインタでなければなりません
  • capabilityFeatureCapacityInput が 0 でない場合、capabilityFeatures は capabilityFeatureCapacityInput XrSpatialCapabilityFeatureEXT 値の配列へのポインタでなければなりません。

戻りコード

成功

  • 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 を返さなければなりません。空間コンテキスト ハンドルには、少なくとも 1 つの機能が必要です。

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 の次のチェーン内の構造のいずれかが、xrEnumerateSpatialCapabilityFeaturesEXT でその機能に対して列挙されていない XrSpatialCapabilityFeatureEXT に対応している場合、ランタイムはその XrSpatialCapabilityFeatureEXT 構造を無視しなければなりません。

XrSpatialContextCreateInfoEXT :: capabilityConfigs に、同じ XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability を持つ複数の構造体が含まれている場合、ランタイムは XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT を返さなければなりません。

システム リソースを最適に使用するために、ランタイムは XrSpatialContextCreateInfoEXT 配列で提供される構成を使用して、空間リクエストの受信に備える場合があります。たとえば、平面トラッキング機能をサポートするランタイムは、平面トラッキング機能を含む空間コンテキスト ハンドルがアプリケーションによって作成された場合にのみ、平面トラッキング パイプラインを開始できます。構成された機能のウォームアップ時間が長い場合、xrCreateSpatialDiscoverySnapshotAsyncEXT の呼び出しにより、空のスナップショットが生成される可能性があります。アプリは、xrCreateSpatialDiscoverySnapshotAsyncEXT を使用する前に XrEventDataSpatialDiscoveryRecommendedEXT を待機して、基盤となるトラッキング サービスがウォームアップされていることを確認できます。

ランタイムが、XrSpatialContextEXT に構成されている空間機能へのアプリケーション アクセスを制御する権限システムを適用する場合、それらの権限がこのアプリケーションに付与されていない場合、ランタイムは XR_ERROR_PERMISSION_INSUFFICIENT を返さなければなりません。

この関数は非同期オペレーションを開始し、対応する XrFutureEXT を作成します。これは xrPollFutureEXT および関連する関数で使用できます。この関数の戻り値は、パラメータが非同期オペレーションのスケジュール設定に許容されるかどうかのみを示します。対応する完了関数は xrCreateSpatialContextCompleteEXT です。この関数からの Future が READY 状態のときに使用でき、その関数によって完了構造 XrCreateSpatialContextCompletionEXT に出力が入力されます。

有効な使用方法（暗黙的）

  • XR_EXT_spatial_entity 拡張機能は、xrCreateSpatialContextAsyncEXT を呼び出す前に有効にする必要があります。
  • session は、有効な XrSession ハンドルでなければなりません。
  • createInfo は、有効な XrSpatialContextCreateInfoEXT 構造体へのポインタでなければなりません。
  • future は XrFutureEXT 値へのポインタでなければなりません。

戻りコード

成功

  • 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 は、capabilityConfigs 配列内の要素の数を表す uint32_t です。
  • 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 は、enabledComponents 配列内の要素の数を表す uint32_t です。
  • enabledComponents は XrSpatialComponentTypeEXT の配列へのポインタです。

capability が xrEnumerateSpatialCapabilitiesEXT によって列挙されていない場合、ランタイムは 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;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • futureResult は、空間コンテキスト作成オペレーションの XrResult です。
  • spatialContext は、xrCreateSpatialContextAsyncEXT :: createInfo のデータと構成を使用して作成された XrSpatialContextEXT です。

今後の返品コード

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 ハンドルと基盤となるリソースを解放できます。spatialContext と同じ空間機能で作成された有効な XrSpatialContextEXT が他にない場合、この呼び出しは、システム リソースを節約するために、それらの機能に必要なトラッキング サービスを無効にするようランタイムに提案する役割を果たします。

有効な使用方法（暗黙的）

スレッドセーフ

  • spatialContext とその子ハンドルへのアクセスは、外部で同期する必要があります。

戻りコード

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

空間エンティティ表現

空間エンティティ ID

XR_DEFINE_ATOM(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 です。

有効な使用方法（暗黙的）

空間エンティティ ハンドルを破棄する

xrDestroySpatialEntityEXT 関数は次のように定義されます。

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

パラメータの説明

アプリは、このハンドルによって参照されるエンティティが不要になったときに、xrDestroySpatialEntityEXT を使用して spatialEntity ハンドルを解放できます。

有効な使用方法（暗黙的）

  • XR_EXT_spatial_entity 拡張機能は、xrDestroySpatialEntityEXT を呼び出す前に有効にする必要があります。
  • spatialEntity は、有効な XrSpatialEntityEXT ハンドルでなければなりません。

スレッドセーフ

  • 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 で提供されるコンポーネントを少なくとも 1 つ持つ空間エンティティのみをスナップショットに含めなければなりません。また、ランタイムには、スナップショット内のコンポーネントのデータのみを含める必要があります。

spatialContext の作成時に XrSpatialContextCreateInfoEXT :: capabilityConfigs に渡された空間機能に対して XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes の XrSpatialComponentTypeEXT のいずれかが有効になっていない場合、ランタイムは XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT を返さなければなりません。

アプリケーションが XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes で空間コンポーネント タイプのリストを提供しない場合、ランタイムは、spatialContext 用に構成された機能の XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents で列挙されたコンポーネントのセットを持つスナップショット内のすべての空間エンティティを含めなければなりません。ランタイムには、spatialContext に構成された機能の有効なすべてのコンポーネントのデータを含める必要があります。

future の完了前に XrEventDataReferenceSpaceChangePending がキューに入れられ、XrEventDataReferenceSpaceChangePending :: poseValid が false の場合、ランタイムは、エンティティのない XrSpatialSnapshotEXT を作成するか、XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace の XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time で、特定できなくなったエンティティの XrSpatialEntityTrackingStateEXT を XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT または XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT に設定しても構いません。ランタイムは、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 は、componentTypes 配列内の要素の数を表す uint32_t です。
  • 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;

メンバーの説明

作成されたスナップショットに含まれるさまざまなコンポーネント データのロケーションは、time にある baseSpace で表されます。

有効な使用方法（暗黙的）

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 の過剰な呼び出しを回避できます。アプリケーションが 2 つの XrEventDataSpatialDiscoveryRecommendedEXT イベント間で同じ XrSpatialDiscoverySnapshotCreateInfoEXT を使用して複数の検出スナップショットを作成すると、結果のスナップショットに同じエンティティが含まれる可能性があり、スナップショットの作成とデータクエリが無駄になります。

このイベントを待ってから新しいディスカバリ スナップショットを作成することで、ランタイムが新しいデータを返さない可能性があるディスカバリ リクエストでアプリケーションがシステムに過負荷をかけることがなくなります。また、システム リソースの過剰使用のリスクを回避し、デバイスの電力ポリシーや温度ポリシーによるスロットリングを回避できます。これにより、ライブ トラッキングで空間エンティティをオンザフライで検出するランタイムと、以前に記録された状態から空間エンティティを提供するランタイム（ランタイムは、XrSpatialContextEXT ごとに 1 回だけ検出推奨イベントをキューに追加する）との間で同等性を確保できます。

ランタイムは、既存の空間エンティティのコンポーネント データに加えられた変更や調整についてアプリケーションに通知するために、このイベントをキューに入れてはなりません。アプリは、xrCreateSpatialUpdateSnapshotEXT を使用して、関心のある空間エンティティのコンポーネント データの更新を追跡できます。

ランタイムは、アプリケーションが最初に xrCreateSpatialDiscoverySnapshotAsyncEXT を呼び出すのを待たずに、検出推奨イベントをキューに追加しても構いません。たとえば、ランタイムは、XrSpatialContextEXT の構成、ユーザーの周囲の環境に関する独自の理解（新しいエンティティの検出や既存のエンティティの喪失）、またはシステム リソースに過負荷をかけないように適切な検出リクエストの頻度をアプリにヒントとして提供することに基づいて、検出推奨イベントをキューに入れるかどうかを決定できます。XrSpatialContextEXT のライフタイム全体を通じてユーザーの環境でエンティティが見つからない場合、ランタイムは XrSpatialContextEXT のこのイベントをキューに入れないことを選択する可能性があります。

ランタイムは、アプリが xrCreateSpatialContextCompleteEXT を使用して作成を完了するまで、特定の spatialContext のこのイベントをキューに入れてはなりません。

アプリケーションが xrDestroySpatialContextEXT を呼び出した後、ランタイムは、その空間コンテキストの検出レコメンデーション イベントをキューに追加してはなりません。また、xrPollEvent からそのコンテキストのイベントを返してはなりません。

有効な使用方法（暗黙的）

クエリ コンポーネント データ

xrQuerySpatialComponentDataEXT 関数は次のように定義されます。

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

パラメータの説明

アプリケーションは、XrSpatialComponentDataQueryConditionEXT :: componentTypes の各 XrSpatialComponentTypeEXT に対応する XrSpatialComponentDataQueryResultEXT :: next にリスト構造をアタッチすることで、xrQuerySpatialComponentDataEXT を使用してスナップショット内のエンティティのコンポーネント データをクエリできます。

アプリケーションが、XrSpatialComponentDataQueryConditionEXT :: componentTypes にリストされているコンポーネントのいずれにも対応しないリスト構造を XrSpatialComponentDataQueryResultEXT :: next にアタッチする場合、ランタイムは 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 のエンティティと同じ順序で、リスト構造のコンポーネント データを入力しなければなりません。つまり、リスト構造配列の特定のインデックスにあるコンポーネント データは、同じインデックスのエンティティに対応しなければなりません。

エンティティのトラッキング状態が 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. スナップショットの例

クエリ条件に XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT を指定して、上記のスナップショットで xrQuerySpatialComponentDataEXT を実行すると、エンティティ #1、#2、#5 がアプリに返されます。アプリは、XrSpatialComponentBounded2DListEXT 構造の一部として XrSpatialBounded2DDataEXT の配列を 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. クエリ結果の例

クエリ条件に XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT コンポーネントと XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT コンポーネントをリストした上記の xrQuerySpatialComponentDataEXT スナップショットでは、エンティティ #3 と #4 がアプリに返されます。アプリは、XrSpatialComponentBounded3DListEXT 構造と XrSpatialComponentMesh3DListEXT 構造の一部として、XrBoxf と XrSpatialMeshDataEXT の配列を 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...

meshes

meshes 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 は、componentTypes 配列内の要素の数を表す uint32_t です。
  • 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

ランタイムは現在このエンティティをトラッキングしており、そのコンポーネント データは有効です。

トラッキング

一時停止

停止

図 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 の場合、ランタイムはバッファの内容を変更してはなりません。

コンポーネント データの 2 回呼び出しイディオム

XrSpatialBufferEXT 構造体は次のように定義されます。

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

メンバーの説明

  • bufferId: バッファデータの XrSpatialBufferIdEXT。
  • bufferType は、bufferId 内のデータの種類を示す XrSpatialBufferTypeEXT です。アプリケーションは、bufferType を使用して、バッファの実際のデータを取得するために使用する関数を決定できます。

一部の空間コンポーネントには可変サイズのデータがあるため、データを取得するには 2 回呼び出しのイディオムを使用する必要があります。このような場合、空間コンポーネントのデータ構造は、そのコンポーネントのデータに必要な可変サイズのバッファごとに XrSpatialBufferEXT を提供します。

同じ bufferId の場合、ランタイムは、1 つのスナップショットから別のスナップショットにわたる場合でも、1 つのコンポーネント データクエリから別のコンポーネント データクエリに同じデータを提供する必要があります。コンポーネント データクエリ呼び出し間で bufferId が異なる場合、そのコンポーネントのデータが変更された可能性があることをアプリに示します。

有効な使用方法（暗黙的）

  • XrSpatialBufferEXT を使用する前に、XR_EXT_spatial_entity 拡張機能を有効にする必要があります。
  • bufferType は、有効な XrSpatialBufferTypeEXT 値でなければなりません。

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT は、空間コンポーネントのあらゆる種類の可変サイズデータを表すために使用されます。

ランタイムは、少なくとも を含む XrSpatialSnapshotEXT のライフサイクル中は、XrSpatialBufferIdEXT とそのデータをメモリに保持しなければなりません。XrSpatialSnapshotEXT のライフサイクルよりも長く、ランタイムが XrSpatialBufferIdEXT とそのデータをメモリに保持する場合があります。これは、後でアプリによって作成されるスナップショットの一部として同じ 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 で表されるバッファのさまざまなデータ型を識別します。

列挙子の説明

  • XR_SPATIAL_BUFFER_TYPE_STRING_EXT . XrSpatialBufferIdEXT は xrGetSpatialBufferStringEXT に渡すことができます。これにより、文字列バッファを取得できます。
  • XR_SPATIAL_BUFFER_TYPE_UINT8_EXT . XrSpatialBufferIdEXT は xrGetSpatialBufferUint8EXT に渡して uint8_t バッファを取得できます。
  • XR_SPATIAL_BUFFER_TYPE_UINT16_EXT . XrSpatialBufferIdEXT は xrGetSpatialBufferUint16EXT に渡して uint16_t バッファを取得できます。
  • XR_SPATIAL_BUFFER_TYPE_UINT32_EXT . XrSpatialBufferIdEXT は xrGetSpatialBufferUint32EXT に渡して uint32_t バッファを取得できます。
  • XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT . XrSpatialBufferIdEXT は、xrGetSpatialBufferFloatEXT に渡して float バッファを取得できます。
  • XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT . XrSpatialBufferIdEXT は xrGetSpatialBufferVector2fEXT に渡して XrVector2f バッファを取得できます。
  • XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT . XrSpatialBufferIdEXT は xrGetSpatialBufferVector3fEXT に渡して XrVector3f バッファを取得できます。

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 は、null で終わる UTF-8 文字列である必要があります。

有効な使用方法（暗黙的）

  • xrGetSpatialBufferStringEXT を呼び出す前に、XR_EXT_spatial_entity 拡張機能を有効にしなければなりません。
  • 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);

パラメータの説明

  • snapshot は XrSpatialSnapshotEXT へのハンドルです。
  • info には、クエリ対象のバッファに関する情報が保持されます。
  • bufferCapacityInput は配列の容量です。0 の場合は、必要な容量を取得するリクエストであることを示します。
  • bufferCountOutput は、buffer 配列内の要素数、または bufferCapacityInput が不十分な場合に必要となる容量です。
  • buffer は uint8_t の配列です。bufferCapacityInput が 0 の場合、NULL になることがあります。
  • 必要な buffer サイズの取得の詳細については、バッファサイズ パラメータのセクションをご覧ください。

アプリケーションは、コンポーネントによって提供される XrSpatialBufferEXT のデータを取得できます。ここで、XrSpatialBufferEXT :: bufferType は、xrGetSpatialBufferUint8EXT を使用して 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 サイズの取得の詳細については、バッファサイズ パラメータのセクションをご覧ください。

アプリケーションは、コンポーネントによって提供される XrSpatialBufferEXT のデータを取得できます。ここで、XrSpatialBufferEXT :: bufferType は、xrGetSpatialBufferFloatEXT を使用して 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 を返さなければなりません。

有効な使用方法（暗黙的）

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

パラメータの説明

  • 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 を返さなければなりません。

有効な使用方法（暗黙的）

  • xrGetSpatialBufferVector2fEXT を呼び出す前に、XR_EXT_spatial_entity 拡張機能を有効にする必要があります。
  • snapshot は有効な XrSpatialSnapshotEXT ハンドルでなければなりません
  • info は、有効な XrSpatialBufferGetInfoEXT 構造体へのポインタでなければなりません
  • bufferCountOutput は uint32_t 値へのポインタでなければなりません
  • bufferCapacityInput が 0 でない場合、buffer は bufferCapacityInput XrVector2f 構造体の配列へのポインタでなければなりません。

戻りコード

成功

  • 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_EXT_spatial_entity 拡張機能は、xrGetSpatialBufferVector3fEXT を呼び出す前に有効にする必要があります。
  • snapshot は有効な XrSpatialSnapshotEXT ハンドルでなければなりません
  • info は、有効な XrSpatialBufferGetInfoEXT 構造体へのポインタでなければなりません
  • bufferCountOutput は uint32_t 値へのポインタでなければなりません
  • bufferCapacityInput が 0 でない場合、buffer は bufferCapacityInput XrVector3f 構造体の配列へのポインタでなければなりません。

戻りコード

成功

  • 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。

有効な使用方法（暗黙的）

  • XR_EXT_spatial_entity 拡張機能は、XrSpatialBufferGetInfoEXT を使用する前に有効にする必要があります。
  • 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 で提供されるコンポーネントを少なくとも 1 つ持つ空間エンティティのみをスナップショットに含める必要があります。また、ランタイムには、スナップショット内のコンポーネントのデータのみを含める必要があります。

spatialContext の作成時に XrSpatialContextCreateInfoEXT :: capabilityConfigs に渡された空間機能に対して XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes の XrSpatialComponentTypeEXT のいずれかが有効になっていない場合、ランタイムは 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 は、entities 配列内の要素の数を表す uint32_t です。
  • entities は XrSpatialEntityEXT の配列です。ランタイムは、スナップショットにコンポーネント データを含める必要があります。
  • componentTypeCount は、componentTypes 配列内の要素の数を表す uint32_t です。
  • componentTypes は XrSpatialComponentTypeEXT の配列です。ランタイムは、この配列のデータをスナップショットに含める必要があります。
  • baseSpace は、更新 XrSpatialSnapshotEXT のすべての位置が配置される XrSpace です。
  • time は、更新 XrSpatialSnapshotEXT のすべての位置が配置される XrTime です。

有効な使用方法（暗黙的）

  • 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 は、境界付き 2D コンポーネントの幾何学的中心を定義する XrPosef です。
  • extents は、center を中心とする、x 軸（extents.width）と y 軸（extents.height）に沿った境界付き 2D コンポーネントの範囲です。

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT の extents は、平面の座標系の x-y 平面におけるエンティティのサイズを指します。位置が {0, 0, 0}、回転が {0, 0, 0, 1}（回転なし）、範囲が {1, 1} の平面は、{0, 0, 0} を中心とする 1 m x 1 m の平面を指し、その前面の法線ベクトルはコンポーネントの空間で +Z 方向を指します。

X X Y Y Z Z 高さ 高さ Y Y Z Z X X 垂直面 垂直面 水平面 水平面 幅 幅 幅 幅 高さ 高さ

図 24. Bounded2D コンポーネントの座標系

注

OpenXR は、+Z を平面法線とする X-Y 平面を使用しますが、他の API は +Y を平面法線とする X-Z 平面を使用する場合があります。X-Y 平面は、+X 軸を中心に -π/2 ラジアン回転させることで、X-Z 平面に変換できます。

有効な使用方法（暗黙的）

  • XrSpatialBounded2DDataEXT を使用する前に、XR_EXT_spatial_entity 拡張機能を有効にしなければなりません。
データをクエリするコンポーネント リストの構造

XrSpatialComponentBounded2DListEXT 構造体は次のように定義されます。

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

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • boundCount は、bounds 配列内の要素の数を表す uint32_t です。
  • 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 から作成された場合、ランタイムは XrSpatialBounded2DDataEXT :: center を XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace と XrSpatialUpdateSnapshotCreateInfoEXT :: time で提供しなければなりません。

有効な使用方法（暗黙的）

  • 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 は、bounds 配列内の要素の数を表す uint32_t です。
  • 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 から作成された場合、ランタイムは XrBoxf :: center を XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace の XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time に提供しなければなりません。

xrQuerySpatialComponentDataEXT :: snapshot が xrCreateSpatialUpdateSnapshotEXT から作成された場合、ランタイムは XrBoxf :: center を XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace の XrSpatialUpdateSnapshotCreateInfoEXT :: time に提供しなければなりません。

有効な使用方法（暗黙的）

  • 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 は、parents 配列内の要素の数を表す uint32_t です。
  • 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 を返さなければなりません。

有効な使用方法（暗黙的）

  • XrSpatialComponentParentListEXT を使用する前に、XR_EXT_spatial_entity 拡張機能を有効にする必要があります。
  • 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 内のメッシュ頂点のインデックスを指定します。三角形のインデックスは反時計回りの順序で返す必要があります。3 つのインデックスが 1 つの三角形を表します。

XrSpatialMeshDataEXT を使用するコンポーネント タイプは、vertexBuffer と indexBuffer の XrSpatialBufferTypeEXT を指定しなければなりません。

有効な使用方法（暗黙的）

  • XrSpatialMeshDataEXT を使用する前に、XR_EXT_spatial_entity 拡張機能を有効にする必要があります。
  • vertexBuffer は、有効な XrSpatialBufferEXT 構造体でなければなりません。
  • indexBuffer は、有効な XrSpatialBufferEXT 構造体でなければなりません。
データをクエリするコンポーネント リストの構造

XrSpatialComponentMesh3DListEXT 構造体は次のように定義されます。

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

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • meshCount は、meshes 配列内の要素の数を表す uint32_t です。
  • meshes は XrSpatialMeshDataEXT の配列です。

アプリは、XrSpatialComponentDataQueryConditionEXT :: componentTypes に XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT を追加し、XrSpatialComponentDataQueryResultEXT の次のポインタ チェーンに XrSpatialComponentMesh3DListEXT を追加することで、XrSpatialSnapshotEXT 内の空間エンティティのメッシュ 3D コンポーネントをクエリできます。

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 でなければなりません。

有効な使用方法（暗黙的）

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

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • trackingState は、アプリがフィルタを適用する XrSpatialEntityTrackingStateEXT です。

アプリは、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.
  }
}

拡張機能のガイドライン

  • 拡張機能が、空間エンティティに関する追加データを提供する新しい XrSpatialComponentTypeEXT を定義している場合、

  • 拡張機能は、XrSpatialDiscoverySnapshotCreateInfoEXT を拡張する構造を定義して、検出用の追加フィルタを提供できます。スナップショットを作成するためのフィルタは、空間コンテキストの構成に影響を与えてはなりません。代わりに、空間コンテキストの現在の構成（したがって、基盤となるサービスの現在の構成）によって追跡されるスナップショットに含めるエンティティとデータに関するヒントをランタイムに提供するために使用されます。

  • 拡張機能が新しい XrSpatialCapabilityEXT を定義する場合、

  • 拡張機能が新しい XrSpatialCapabilityFeatureEXT を定義する場合、XrSpatialCapabilityConfigurationBaseHeaderEXT の次のポインタにチェーンできる対応する構成構造も定義しなければなりません。アプリは、XrSpatialContextEXT の作成時にこの構成構造を使用して機能を有効にできます。

  • 新しい XrSpatialCapabilityEXT を定義する拡張機能は、仕様について次のテンプレートに従うべきです。

    • 概要
    • ランタイム サポート
    • 構成
    • 保証対象のコンポーネント
    • コード例

  • 新しい XrSpatialComponentTypeEXT を定義する拡張機能は、仕様のこのテンプレートに従うべきです。

    • コンポーネント データ
    • データをクエリするコンポーネント リストの構造
    • 構成

  • アプリケーションに XrSpatialBufferIdEXT を提供する API を作成する場合は、XrSpatialBufferTypeEXT を付随させて、バッファのデータ型をアプリケーションに通知しなければなりません。アプリケーションは、適切な xrGetSpatialBuffer* 関数を使用してバッファの実際の内容を取得できます。

セマンティック ラベルのデザインと拡張のガイドライン

この拡張機能は、エンティティのセマンティック ラベル情報を伝達するコンポーネントを定義するものではありませんが、そのようなコンポーネントを定義する拡張機能の設計ルールとガイドラインを定めています。以下のテキストでは、「すべき」と「しなければならない」は、ランタイム実装や API を使用するアプリケーションを制約するのではなく、そのような機能の作成者を制約します。

  • 拡張機能が XrSpatialCapabilityEXT のセマンティック ラベルを定義している場合、新しい XrSpatialComponentTypeEXT と、そのコンポーネントのデータとなるラベルのセット（「セマンティック ラベルセット」）を含む新しい列挙型を定義すべきです。
  • セマンティック ラベルセットを表す列挙型には、エンティティがこのセットのラベルのいずれにも分類されていないことを示す値が必要です。この列挙子の名前には、XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT などの「UNCATEGORIZED」を含める必要があります。この値は、ランタイムがこのエンティティを認識しているものの、このエンティティが分類されている他のセマンティック ラベルセットがあることをアプリケーションに示します。
  • xrEnumerateSpatialCapabilityComponentTypesEXT でこの新しく定義された XrSpatialComponentTypeEXT を列挙することは、ランタイムがそのコンポーネント タイプに対応するセマンティック ラベルセット（したがって、セットで定義されたラベル）をサポートしていることを意味します。
  • アプリケーションは、このセマンティック ラベルセットに属するラベルを持つエンティティを検出したいという意向を、対応する XrSpatialComponentTypeEXT を XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 配列に含めることで表現します。この配列は、コンポーネント タイプが列挙されている機能の構成構造体です。
  • 1 つの空間エンティティに複数のコンポーネントがあり、それぞれが独自のセマンティック ラベルセットからラベルを提供している場合があります。次の例では、いくつかの仮定的なセマンティック ラベルセット（XrSpatialObjectSemanticLabel）を考えてみましょう。これには、椅子、ソファ、テーブルなどの値が含まれる可能性があります。XrSpatialSofaBrand（IKEA、Wayfair などの値）と XrSpatialIkeaSofa（IKEA のソファの特定のモデル名など）です。このシナリオでは、同じソファ エンティティに 3 つのコンポーネント（3 つのセマンティック ラベルセットのラベル）がすべて含まれており、それぞれがエンティティに関する異なる粒度の情報を提供します。
  • 拡張機能が、UNCATEGORIZED ラベルに加えて複数のラベルを含む新しいセマンティック ラベルセットを提供する新しい XrSpatialComponentTypeEXT を定義している場合、拡張機能は、アプリケーションがそのコンポーネント タイプに対応するセマンティック ラベルセットで定義されたラベルのサブセットのみを有効にできるようにする 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

問題

  • 1 つのエンティティは常に 1 つの機能のみから派生しますか？

    • 解決済み
    • 回答: いいえ。これは、独自のトラッキング機能と、検出されたエンティティをどのように表現するかによって、完全にランタイムに依存します。この仕様では、特定の機能の保証されたコンポーネントを除き、空間エンティティの特定の表現を規定していません。ランタイムは、別々の機能によって検出されたエンティティをマージし、そのエンティティの識別に使用されたすべての機能の保証されたコンポーネントを含む単一のエンティティとして表すことができます。たとえば、テーブルは平面トラッキング機能とオブジェクト トラッキング機能の両方で検出できます。平面トラッキングはエンティティに 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 の両方がある場合があります。ここで重要なのは、特定の空間エンティティは、特定のコンポーネント タイプのコンポーネントを最大 1 つしか持てないということです。したがって、異なる機能によって生成されたコンポーネント データが特定のエンティティで競合する場合、ランタイムはそれらを 2 つの別個のエンティティとして表さなければなりません。

変更履歴

  • リビジョン 1、2024-04-12（Nihav Jain、Google）

    • 拡張機能の初期説明