XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

741

リビジョン

1

Ratification Status（批准ステータス）

批准

拡張機能とバージョンの依存関係

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_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

XrSpatialComponentTypeEXT 列挙型は、ランタイムがサポートする可能性のあるさまざまなタイプのコンポーネントを識別します。

ここに記載されているすべてのコンポーネント タイプがこの拡張機能だけで提供されるわけではありません。一部のコンポーネント タイプでは、ドキュメントに記載されているように、インスタンスの作成時に追加の拡張機能を有効にする必要があります。

列挙子の値は次のとおりです。

列挙型の説明

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

空間エンティティの 2D 境界を提供するコンポーネント。対応するリスト構造は XrSpatialComponentBounded2DListEXT です。対応するデータ構造は XrSpatialBounded2DDataEXT です。

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

空間エンティティの 3D 境界を提供するコンポーネント。対応するリスト構造は XrSpatialComponentBounded3DListEXT です。対応するデータ構造は XrBoxf です。

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

空間エンティティの親の XrSpatialEntityIdEXT を提供するコンポーネント。対応するリスト構造は XrSpatialComponentParentListEXT です。対応するデータ構造は XrSpatialEntityIdEXT です。

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

空間エンティティの 3D メッシュを提供するコンポーネント。対応するリスト構造は XrSpatialComponentMesh3DListEXT です。対応するデータ構造は XrSpatialMeshDataEXT です。

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

空間エンティティの平面配置列挙型を提供するコンポーネント。対応するリスト構造は XrSpatialComponentPlaneAlignmentListEXT です。対応するデータ構造は XrSpatialPlaneAlignmentEXT です（XR_EXT_spatial_plane_tracking 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

空間エンティティの 2D メッシュを提供するコンポーネント。対応するリスト構造は XrSpatialComponentMesh2DListEXT です。対応するデータ構造は XrSpatialMeshDataEXT です（XR_EXT_spatial_plane_tracking 拡張機能によって追加）。

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

空間エンティティの 2D 境界ポリゴンを提供するコンポーネント。対応するリスト構造は XrSpatialComponentPolygon2DListEXT です。対応するデータ構造は XrSpatialPolygon2DDataEXT です（XR_EXT_spatial_plane_tracking 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

平面のセマンティック ラベルを提供するコンポーネント。対応するリスト構造は XrSpatialComponentPlaneSemanticLabelListEXT です。対応するデータ構造は XrSpatialPlaneSemanticLabelEXT です（XR_EXT_spatial_plane_tracking 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

マーカーのタイプ、ID、場所を記述するコンポーネント。対応するリスト構造は XrSpatialComponentMarkerListEXT です。対応するデータ構造は XrSpatialMarkerDataEXT です（XR_EXT_spatial_marker_tracking 拡張機能によって追加）。

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

シーンのセマンティック ラベルを提供するコンポーネント。対応するリスト構造は XrSpatialComponentObjectSemanticLabelListEXT です。対応するデータ構造は XrSpatialObjectSemanticLabelEXT です。（XR_EXT_spatial_object_tracking 拡張機能によって追加されました）

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

キーボードのセマンティック ラベルを提供するコンポーネント。対応するリスト構造は XrSpatialComponentKeyboardSemanticLabelListEXT です。対応するデータ構造は XrSpatialKeyboardSemanticLabelEXT です（XR_EXT_spatial_object_tracking 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

マウスのセマンティック ラベルを提供するコンポーネント。対応するリスト構造は XrSpatialComponentMouseSemanticLabelListEXT です。対応するデータ構造は XrSpatialMouseSemanticLabelEXT です（XR_EXT_spatial_object_tracking 拡張機能によって追加されます）。

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

アンカーの位置を提供するコンポーネント。対応するリスト構造は XrSpatialComponentAnchorListEXT です。対応するデータ構造は XrPosef です（XR_EXT_spatial_anchor 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

空間エンティティの永続 UUID を提供するコンポーネント。対応するリスト構造は XrSpatialComponentPersistenceListEXT です。対応するデータ構造は XrSpatialPersistenceDataEXT です（XR_EXT_spatial_persistence 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

平面画像タイプを記述するコンポーネント。対応するリスト構造は XrSpatialComponentImage2DListEXT です。対応するデータ構造は XrSpatialImageSizeEXT です。（XR_EXT_spatial_image_tracking 拡張機能によって追加されました）

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

空間エンティティの 3D メッシュの法線を提供するコンポーネント。対応するリスト構造は XrSpatialComponentMesh3DNormalsListEXT です。対応するデータ構造は XrSpatialBufferEXT です（XR_EXT_spatial_mesh_tracking 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

空間エンティティの 3D メッシュの頂点ごとのセマンティック ラベルを提供するコンポーネント。対応するリスト構造は XrSpatialComponentMesh3DVertexSemanticLabelsListEXT です。対応するデータ構造は XrSpatialBufferEXT です。バッファ内のデータは XrSpatialMeshSemanticLabelEXT にマッピングされます（XR_EXT_spatial_mesh_tracking 拡張機能によって追加）。

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

空間エンティティの 3D メッシュの三角形の面ごとのセマンティック ラベルを提供するコンポーネント。対応するリスト構造は XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT です。対応するデータ構造は XrSpatialBufferEXT です。バッファ内のデータは XrSpatialMeshSemanticLabelEXT にマッピングされます（XR_EXT_spatial_mesh_tracking 拡張機能によって追加）。

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

オブジェクトのセマンティック ラベルを提供するコンポーネント。対応するリスト構造は XrSpatialComponentObjectSemanticLabelListANDROID です。対応するデータ構造は XrSpatialObjectSemanticLabelANDROID です（XR_ANDROID_spatial_object_tracking 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

エンティティに対するレイキャスト ヒットのポーズを提供するコンポーネント。対応するリスト構造は XrSpatialComponentRaycastResultListANDROID です。対応するデータ構造は XrSpatialRaycastResultDataANDROID です（XR_ANDROID_spatial_discovery_raycast 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

アタッチされたエンティティを包含するエンティティのエンティティ ID を提供するコンポーネント。対応するリスト構造は XrSpatialComponentSubsumedByListANDROID です。対応するデータ構造は XrSpatialEntityIdEXT です（XR_ANDROID_spatial_component_subsumed_by 拡張機能によって追加）。

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

靴箱の寸法と客室タイプを提供するコンポーネント。対応するリスト構造は XrSpatialComponentRoomListANDROIDSYS、対応するデータ構造は XrSpatialRoomDataANDROIDSYS です（XR_ANDROIDSYS_spatial_room_tracking 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

境界サーフェスのマテリアル タイプを提供するコンポーネント。対応するリスト構造は XrSpatialComponentMaterialTypeListANDROIDSYS、対応するデータ構造は XrSpatialMaterialTypeANDROIDSYS です（XR_ANDROIDSYS_spatial_room_tracking 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

追跡可能なものの信頼度を提供するコンポーネント。対応するリスト構造は XrSpatialComponentConfidenceListANDROIDSYS。対応するデータ構造は float（XR_ANDROIDSYS_spatial_room_tracking 拡張機能により追加）

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

部屋の空き状況を提供するコンポーネント。対応するリスト構造は XrSpatialComponentRoomEmptinessListANDROIDSYS。対応するデータ構造は float（XR_ANDROIDSYS_spatial_room_tracking 拡張機能によって追加）

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

アタッチされたエンティティの占有グリッドに関する情報を提供するコンポーネント。対応するリスト構造は XrSpatialComponentOccupancyGridListANDROIDX1 です。対応するデータ構造は XrSpatialOccupancyGridDataANDROIDX1 です（XR_ANDROIDX1_spatial_occupancy_grid 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

四角形のアノテーションを記述するコンポーネント。対応するリスト構造は XrSpatialComponentAnnotationQuadListANDROID です。対応するデータ構造は XrSpatialAnnotationQuadDataANDROID です（XR_ANDROID_spatial_annotation_tracking 拡張機能により追加）。

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

ストリートスケープ ジオメトリのメタデータを提供するコンポーネント。対応するリスト構造は XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2、対応するデータ構造は XrSpatialStreetscapeGeometryMetadataANDROIDX2 です（XR_ANDROIDX2_geospatial_streetscape 拡張機能により追加）。

空間機能とセットアップ

空間機能は、保証されたコンポーネントのセットを持つエンティティを検出するランタイムの機能を定義します。アプリは XrSpatialContextEXT の作成時に空間機能のコンポーネントを有効にします。ランタイムは、検出されたエンティティで有効なコンポーネントのみを提供しなければなりません。たとえば、ランタイムが特定の機能のコンポーネントの 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 で拡張機能が有効になっていない空間機能を列挙してはなりません。

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

  • xrEnumerateSpatialCapabilitiesEXT を呼び出す前に、XR_EXT_spatial_entity 拡張機能を有効にしなければなりません。
  • instance は、有効な XrInstance ハンドルでなければなりません。
  • capabilityCountOutput は uint32_t 値へのポインタでなければなりません。
  • capabilityCapacityInput が 0 でない場合、capabilities は capabilityCapacityInput XrSpatialCapabilityEXT 値の配列へのポインタでなければなりません。

戻りコード

成功

  • XR_SUCCESS

失敗

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

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

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

パラメータの説明

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

この関数は、システムで構成されているとおりに、指定されたケーパビリティがエンティティで提供するコンポーネント タイプを列挙します。

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

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

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

空間機能の特長

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 でサポートされている機能を検出します。

機能が公開されている機能の場合、アプリケーションは有効にする 1 つまたは複数の機能を選択し、XrSpatialContextCreateInfoEXT :: capabilityConfigs の機能構成構造の次のチェーンで対応する構成構造を提供します。

capability が xrEnumerateSpatialCapabilitiesEXT で列挙された機能でない場合、ランタイムは XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT を返さなければなりません。

ランタイムは、拡張機能が instance で有効になっていない空間機能の列挙を行ってはなりません。

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

  • xrEnumerateSpatialCapabilityFeaturesEXT を呼び出す前に、XR_EXT_spatial_entity 拡張機能を有効にしなければなりません。
  • 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 を返さなければなりません。機能構成は、その機能で有効にするコンポーネント タイプのリストがないと完了しません。

xrEnumerateSpatialCapabilityComponentTypesEXT の XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability で XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents にリストされているコンポーネント タイプが列挙されていない場合、ランタイムは 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 の出力がその関数によって入力されます。

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

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

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 ハンドルを解放できます。

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

  • xrDestroySpatialEntityEXT を呼び出す前に XR_EXT_spatial_entity 拡張機能を有効にする必要があります。
  • 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 で位置特定できなくなったエンティティの XrSpatialEntityTrackingStateEXT を XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time で 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

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

Discovery の推奨イベント

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

いいえ

いいえ

いいえ

いいえ

○

○

○

はい

いいえ

Text is not SVG - cannot display（テキストは 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（テキストが SVG ではないため表示できません）

図 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 ハンドルを作成できます。アプリケーションは、xrCreateSpatialUpdateSnapshotEXT でこれらの XrSpatialEntityEXT ハンドルを使用して、指定されたエンティティのコンポーネントのランタイムの最新の既知のデータを含む更新スナップショットを作成できます。

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

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 は XrSpatialBufferTypeEXT で、bufferId のデータの型を示します。アプリケーションは bufferType を使用して、バッファの実際のデータを取得するために使用する関数を決定できます。

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

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

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

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

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

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

ランタイムは、XrSpatialBufferIdEXT とそのデータを、少なくともそれを含む XrSpatialSnapshotEXT のライフサイクル中はメモリに保持しなければなりません。ランタイムは、アプリケーションによって後で作成されるスナップショットの一部として同じ ID を返すために、XrSpatialBufferIdEXT とそのデータを XrSpatialSnapshotEXT のライフサイクルよりも長くメモリに保持する場合があります。同じ XrSpatialBufferIdEXT に対して、ランタイムは適切な xrGetSpatialBuffer* 関数を介して常に同じデータを返す必要があります。

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

XrSpatialBufferTypeEXT 列挙型は、XrSpatialBufferIdEXT で表されるバッファのさまざまなデータ型を識別します。

列挙体の説明

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

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

パラメータの説明

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

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

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

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

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

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

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

パラメータの説明

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

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

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

XrSpatialBufferGetInfoEXT :: bufferId の XrSpatialBufferTypeEXT が XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT でない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

ランタイムは、XrSpatialBufferGetInfoEXT :: bufferId が snapshot に属していない場合、XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT を返さなければなりません。

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

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

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

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

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

パラメータの説明

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

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

アプリケーションは、コンポーネントによって提供される XrSpatialBufferEXT のデータを取得できます。ここで、XrSpatialBufferEXT :: bufferType は XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT であり、xrGetSpatialBufferVector3fEXT を使用します。

XrSpatialBufferGetInfoEXT :: bufferId の XrSpatialBufferTypeEXT が XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT でない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

ランタイムは、XrSpatialBufferGetInfoEXT :: bufferId が snapshot に属していない場合、XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT を返さなければなりません。

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

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

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

#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 です。

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

  • XrSpatialUpdateSnapshotCreateInfoEXT を使用する前に、XR_EXT_spatial_entity 拡張機能を有効にしなければなりません。
  • type は XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT でなければなりません。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • entities entityCount 有効な XrSpatialEntityEXT ハンドルの配列へのポインタでなければなりません。
  • componentTypeCount が 0 でない場合、componentTypes は componentTypeCount 個の有効な XrSpatialComponentTypeEXT 値の配列へのポインタでなければなりません。
  • baseSpace は、有効な XrSpace ハンドルでなければなりません。
  • entityCount パラメータは 0 より大きい値にする必要があります
  • baseSpace と entities の要素の両方が、同じ XrSession から作成、割り当て、取得されている必要があります。

スナップショットを破棄

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

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

パラメータの説明

アプリは xrDestroySpatialSnapshotEXT を呼び出して、XrSpatialSnapshotEXT ハンドルとそれに関連付けられたリソースを破棄できます。

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

スレッドセーフ

  • snapshot とその子ハンドルのアクセスは、外部で同期しなければなりません

戻りコード

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

共通コンポーネント

境界付き 2D

コンポーネント データ

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

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

メンバーの説明

  • center は、境界のある 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} の平面は、コンポーネントの空間で、前面の法線ベクトルが +Z 方向を向いている、{0, 0, 0} を中心とする 1 メートル x 1 メートルの平面を指します。

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 から作成された場合、ランタイムは XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace と XrSpatialUpdateSnapshotCreateInfoEXT :: time で XrSpatialBounded2DDataEXT :: center を提供しなければなりません。

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

構成

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT が XrSpatialCapabilityComponentTypesEXT :: componentTypes で列挙されている場合、アプリは XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents リストに列挙値を含めることで、その機能を有効にできます。このコンポーネントを次の XrSpatialCapabilityConfigurationBaseHeaderEXT チェーンに含めるために、特別な構成は必要ありません。

境界のある 3D

コンポーネント データ

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT はデータに XrBoxf を使用します。

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

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

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

メンバーの説明

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

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

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

構成

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 チェーンに含めるために、特別な構成は必要ありません。

Mesh 3D

コンポーネント データ

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

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

メンバーの説明

  • origin は、メッシュの原点を定義する XrPosef です。メッシュのすべての頂点は、この原点を基準とする必要があります。
  • vertexBuffer は、このコンポーネントが配置されているエンティティの頂点バッファを表すバッファの ID を提供する XrSpatialBufferEXT です。頂点の位置は origin を基準とする必要があります。
  • indexBuffer は、三角形インデックスの配列を表すバッファの ID を提供する XrSpatialBufferEXT で、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 でなければなりません。

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

構成

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 と、そのコンポーネントのデータとなるラベルのセット（「セマンティック ラベルセット」）を含む新しい列挙型を定義して、セマンティック ラベルを定義すべきです。
  • 意味ラベルのセットを表す列挙型には、エンティティがこのセットのどのラベルにも分類されないことを示す値が必要です。この列挙子の名前には「UNCATEGORIZED」を含める必要があります（例: XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT）。この値は、ランタイムがこのエンティティを認識しているが、このエンティティが分類されている他のセマンティック ラベル セットがあることをアプリに示します。
  • 新しく定義された XrSpatialComponentTypeEXT の xrEnumerateSpatialCapabilityComponentTypesEXT での列挙は、ランタイムがそのコンポーネント タイプに対応するセマンティック ラベルセット（およびセットで定義されたラベル）をサポートしていることを意味します。
  • アプリは、このセマンティック ラベルセットに属するラベルを持つエンティティを検出したいという意向を、コンポーネント タイプが列挙されるケーパビリティの構成構造体の XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 配列に、対応する XrSpatialComponentTypeEXT を含めることで表明します。
  • 1 つの空間エンティティに複数のコンポーネントがあり、それぞれが独自のセマンティック ラベルセットからラベルを提供している可能性があります。架空のセマンティック ラベルセット XrSpatialObjectSemanticLabel を含む次の例について考えてみましょう。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;

上記の例では、拡張機能が既存の XrSpatialPlaneSemanticLabelEXT をドアや窓を表す値で拡張するために、列挙型 XrSpatialExamplePlaneSemanticLabelExtensionEXT を定義しています。新しい列挙型の仕様には、次の形式のテキストを含める必要があります。

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

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

新しいマクロ

新しいベースタイプ

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

新しいオブジェクト タイプ

新しいコマンド

新しい構造体

新しい列挙型

新しい列挙型定数

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • XrObjectType の拡張 :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • XrResult の拡張 :

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

  • XrStructureType を拡張する :

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

問題

  • 単一のエンティティは常に単一のケイパビリティからのみ派生しますか？

    • 解決済み
    • 回答: いいえ。検出されたエンティティをどのように表現するかは、ランタイムの独自のトラッキング機能と表現方法に基づいて、ランタイムが完全に決定します。この仕様では、特定の空間エンティティの表現は規定されていません。ただし、最小限の期待値を設定するための特定の機能の保証されたコンポーネントは除きます。ランタイムは、個別の機能で検出されたエンティティを統合し、それらを単一のエンティティとして表現できる場合があります。この場合、エンティティの識別に役立ったすべての機能の保証付きコンポーネントがエンティティに付与されます。たとえば、平面トラッキング機能とオブジェクト トラッキング機能の両方でテーブルを検出でき、平面トラッキングではエンティティに XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT コンポーネントが提供され、オブジェクト トラッキングでは XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT が提供される場合があります。特定のランタイムでは、テーブルが 2 つの別々のエンティティとして提供され、それぞれに保証されたコンポーネントの独自のセットが用意されている場合があります。また、特定のランタイムでは、テーブルを表す 1 つのエンティティのみが提供され、同じエンティティに XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT と XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT の両方が含まれている場合があります。ここで重要なのは、特定の空間エンティティには、特定のコンポーネント タイプのコンポーネントを 1 つだけ含めることができるということです。したがって、異なる機能によって生成されたコンポーネント データが特定のエンティティで競合する場合は、ランタイムで 2 つの別々のエンティティとして表す必要があります。

変更履歴

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

    • 拡張機能の最初の説明