XR_EXT_spatial_container

Name String

XR_EXT_spatial_container

拡張機能の種類

インスタンス拡張

登録済みの内線番号

811

リビジョン

1

承認ステータス

未批准

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

OpenXR 1.0

最終更新日

2026-08-06

IP ステータス

既知の IP 申し立てはありません。

寄与者

Jared Finder、Google
Andreas Loeve Selvik、Meta Platforms
Lachlan Ford、Google
Cass Everitt、Meta Platforms
Adam Gousetis、Meta Platforms
Ankur Agrawal、Unity Technologies
Bjorn Swenson、LÖVR
Denny Rönngren、Varjo Technologies
Fredia Huya-Kouadio、Godot Engine
Guodong Rong、Meta Platforms
Jakob Bornecrantz、NVIDIA
Jian Zhang、ByteDance
John Kearney、Meta Platforms
Jonathan Wright、Meta Platforms
Junfeng She、ByteDance
Kenny Vercaemer、Google
Kurtis Eveleigh、Qualcomm
Mauricio Narvaez、Meta Platforms
Nathan Nuber、Valve Corporation
Nihav Jain、Google
Nikita Lutsenko、Meta Platforms
Praveen Babu J D、ByteDance
Rylie Pavlik、Collabora
Salar Khan、Google
Shuai Liu、ByteDance
Walter Luh、Meta Platforms
Yin Li、Microsoft
Zhipeng Liu、ByteDance

概要

この拡張機能は、「空間コンテナ」と呼ばれる表示可能なエンティティの新しいクラスを定義します。これは、デスクトップ 2D ウィンドウ システムの「ウィンドウ」のコンセプトに似ています。

OpenXR 1.x では、ユーザーに表示されるすべての要素と、それらの要素がユーザーの現実環境または仮想環境にどのようにブレンドされるかを、アプリが排他的に制御します。ランタイムは、ユーザーの安全を確保するために、表示内容にわずかな変更を加えるだけです。このアプリモデルは、ユーザーを 1 つのエクスペリエンスに没入させるのに適していますが、複数のエクスペリエンスを同時に提供することはできません。特に、AR や複合現実の環境では、ユーザーは複数の異なるアプリを同時に体験したいと考えることがよくあります。

空間コンテナは、3D に拡張されたウィンドウのようなものです。ユーザーは複数の空間コンテナを同時に表示し、その一部にインプットを提供できます。表示される空間コンテナは、異なるアプリに属することができ、ランタイムはユーザーに代わってサイズと配置を管理します。

この拡張機能は、既存の没入型 OpenXR エクスペリエンスに加えて、空間的に制限された新しいタイプのエクスペリエンスをサポートします。境界付き OpenXR エクスペリエンスでは、わずかに 3D のコンテンツ（奥行きオフセットが小さいフラットパネル）や、完全に 3D のコンテンツをホストするボリュームを使用できます。没入型 OpenXR エクスペリエンスは、OpenXR 1.0 以降でサポートされている既存の全画面没入型アプリです。アプリは、必要に応じて 2 種類のコンテンツを切り替えることができます。

この拡張機能では、アプリがコンテンツをレンダリングするためのメソッドは定義されていません。コンテンツの描画方法は、他の拡張機能（XR_EXT_spatial_container_self_rendering）で定義されています。

空間コンテナの使用

XrSpatialContainerEXT は、空間コンテナを表すハンドルです。

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

アプリは、次の手順で空間コンテナを介してレンダリングを開始します。

  1. xrCreateSpatialContainerEXT を使用して空間コンテナを作成します。
  2. 境界モードなど、初期表示のためにコンテナの状態を変更します。
  3. xrRequestSpatialContainerVisibleEXT を使用して、ランタイムにコンテナを表示するようリクエストします。
  4. ランタイムがコンテナを表示できるようになるまで待ちます。ランタイムの準備が整うと、visible が XR_TRUE に設定された XrEventDataSpatialContainerVisibleChangedEXT イベントがキューに追加されます。
  5. 空間コンテナのレンダリングを開始します。

空間コンテナの破棄は次のとおりです。

  1. xrRequestSpatialContainerVisibleEXT を使用して、ランタイムにコンテナを非表示にするようリクエストします。
  2. ランタイムがコンテナを非表示にするまで待ちます。ランタイムがコンテナを完全に非表示にすると、visible が XR_FALSE に設定された XrEventDataSpatialContainerVisibleChangedEXT イベントがキューに追加されます。
  3. 空間コンテナのレンダリングを終了します。
  4. xrDestroySpatialContainerEXT を使用してコンテナを破棄します。

注

この拡張機能は、可視性とフォーカス管理を個々の空間コンテナに委任するように設計されています。セッション全体が、表示されている単一のオブジェクトやフォーカスされている単一のオブジェクトを表さなくなるため、セッションは標準の OpenXR ステートマシン（READY、SYNCHRONIZED、VISIBLE、FOCUSED）を遷移しません。代わりに、セッションはアクティブなライフタイムの間 XR_SESSION_STATE_IDLE のままになり、セッション状態の変更のルールで、コア OpenXR オペレーションがこのモードにどのようにマッピングされるかが指定されます。

空間コンテナを作成する

xrCreateSpatialContainerEXT 関数は、新しい空間コンテナを作成します。

XrResult xrCreateSpatialContainerEXT(
    XrSession                                   session,
    const XrSpatialContainerCreateInfoEXT*      createInfo,
    XrSpatialContainerEXT*                      spatialContainer);

パラメータの説明

  • session は、空間コンテナを作成する XrSession です。
  • createInfo は、空間コンテナを作成するためのパラメータを含む XrSpatialContainerCreateInfoEXT へのポインタです。
  • spatialContainer は、作成された XrSpatialContainerEXT が返されるハンドルへのポインタです。

新しく作成された XrSpatialContainerEXT は、表示されず、操作できず、境界モード XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT でなければなりません。空間コンテナを没入モードで起動したいアプリは、空間コンテナの表示をリクエストする前に、XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT の境界モードをリクエストできます。

XrSpatialContainerCreateInfoEXT :: suggestedBounds のいずれかのディメンションが負、無限、または数値でない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。アプリが XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount で指定されている数よりも多くの空間コンテナを作成しようとした場合、ランタイムは XR_ERROR_LIMIT_REACHED を返さなければなりません。このセッションで空間コンテナが有効になっていない場合、ランタイムは XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_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_CONTAINERS_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerCreateInfoEXT が xrCreateSpatialContainerEXT に渡され、空間コンテナが作成されます。

typedef struct XrSpatialContainerCreateInfoEXT {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialContainerGraphicsPresentationEXT    graphicsPresentation;
    XrExtent3Df                                  suggestedBounds;
} XrSpatialContainerCreateInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • graphicsPresentation は、この空間コンテナがグラフィックをどのように表示するかを記述する XrSpatialContainerGraphicsPresentationEXT です。
  • suggestedBounds は、リクエストされた空間コンテナの寸法をメートル単位で記述する XrExtent3Df です。

サイズに優先設定がないアプリは、suggestedBounds を {0, 0, 0} に設定できます。ランタイムは、リクエストされた suggestedBounds を無視する場合があります。

空間コンテナを方向付きボックス以外の形状で囲むことができるランタイムは、他の形状を囲む境界ボックスとして suggestedBounds を使用しなければなりません。方向付きボックスは、最も一般的な境界形状となるように設計されています。

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

空間コンテナが使用できなくなった場合、ランタイムは XrEventDataSpatialContainerClosedEXT イベントをキューに登録しなければなりません。

typedef struct XrEventDataSpatialContainerClosedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerClosedEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • spatialContainer は、このイベントの対象となる XrSpatialContainerEXT です。

XrEventDataSpatialContainerClosedEXT イベントを受信すると、ランタイムが空間コンテナを表示できなくなったことを示します。たとえば、ユーザーが [閉じる] ボタンをクリックしたか、セッションが XR_SESSION_STATE_LOSS_PENDING 状態になったことが原因です。

XrEventDataSpatialContainerClosedEXT イベントを受信した後、アプリは、その空間コンテナの使用を停止し、レンダリング ループなどの関連する状態を破棄して、コンテナを破棄すべきです。ランタイムは、xrDestroySpatialContainerEXT 以外のコンテナで動作するすべての関数から XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT を返さなければなりません。

ランタイムがクローズ イベントをキューに登録したときに空間コンテナが表示されている場合、ランタイムはまずコンテナを非表示に変更し、XrEventDataSpatialContainerVisibleChangedEXT イベントをキューに登録しなければなりません。

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

xrDestroySpatialContainerEXT 関数は、既存の空間コンテナを破棄します。

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

パラメータの説明

空間コンテナが破棄された後、ランタイムはコンテナのコンテンツを表示してはならず、コンテナに関する追加のイベントをキューに格納してはなりません。

アプリは、表示されている空間コンテナを破棄すべきではありません。破棄すると、グラフィック アーティファクトが発生する可能性があります。代わりに、アプリは xrRequestSpatialContainerVisibleEXT を使用して空間コンテナを非表示にするようリクエストし、XrEventDataSpatialContainerVisibleChangedEXT イベントを待ってから、コンテナを破棄すべきです。

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

スレッドセーフ

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

戻りコード

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

空間コンテナ空間

xrCreateSpatialContainerSpaceEXT 関数は、特定の空間コンテナの空間コンテナ空間の XrSpace ハンドルを作成します。

XrResult xrCreateSpatialContainerSpaceEXT(
    XrSession                                   session,
    const XrSpatialContainerSpaceCreateInfoEXT* createInfo,
    XrSpace*                                    space);

パラメータの説明

  • session は、スペースを作成する XrSession です。
  • createInfo は、空間を作成するためのパラメータを含む XrSpatialContainerSpaceCreateInfoEXT へのポインタです。
  • space は、作成された XrSpace が返されるハンドルへのポインタです。

任意の空間コンテナの「空間コンテナ空間」は、その空間コンテナの境界の中心を原点とする座標系です。この空間は通常、xrLocateSpace などの関数のベース空間として使用されます。

+X はコンテナの右面、+Y はコンテナの上面、+Z はコンテナの前面を指します。たとえば、コンテナが重力に沿って配置され、ビューアの前にあり、ビューアが LOCAL 空間に対してアイデンティティ ポーズにある場合、ランタイムは、LOCAL 空間に対してアイデンティティの向きでコンテナ空間を配置しなければなりません。ランタイムは、コンテナが表示されるときに、コンテナ空間のポーズを LOCAL 空間を基準とした任意のポーズに設定しても構いません。

ext 空間コンテナ空間規則

図 18. 空間コンテナ空間の軸規則

空間コンテナ空間は、ワールドロックされていない原点です。没入モード中にワールドロックされた原点を必要とするアプリは、XR_REFERENCE_SPACE_TYPE_LOCAL などのワールドロックされた空間を使用できます。

ランタイムは、空間コンテナのスペースのポーズをいつでも変更できます。これは通常、ユーザーが空間コンテナを別の位置や回転に移動できるようにするためです。ランタイムは、XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT 境界モードと XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT 境界モードの間で移行するときに、ポーズを変更することもできます。

空間コンテナ空間は、対象の空間コンテナが xrDestroySpatialContainerEXT で破棄された場合でも、引き続き有効なハンドルでなければなりません。空間コンテナが表示されていないか、破棄されている場合、空間コンテナ空間は他の空間に対して特定不能でなければなりません。XrSpaceLocation :: locationFlags と XrViewState ::viewStateFlags は 0 になります。

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

戻りコード

成功

  • 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_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerSpaceCreateInfoEXT は、xrCreateSpatialContainerSpaceEXT とともに使用して XrSpace ハンドルを作成します。

typedef struct XrSpatialContainerSpaceCreateInfoEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrSpatialContainerSpaceCreateInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • spatialContainer は、スペースを作成する XrSpatialContainerEXT です。

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

空間コンテナの表示

空間コンテナのコンテンツを OpenXR に送信して表示する処理は、他の拡張機能（XR_EXT_spatial_container_self_rendering）によって処理されます。

他の拡張機能が空間コンテナのグラフィック表示方法を指定できるように、この拡張機能は XrSpatialContainerGraphicsPresentationEXT 列挙型を定義します。

typedef enum XrSpatialContainerGraphicsPresentationEXT {
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT = 1000813000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT = 1000814000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1 = 1000815000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerGraphicsPresentationEXT;

列挙型の説明

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

空間コンテナは OpenXR コンポジション レイヤを使用します（XR_EXT_spatial_container_self_rendering 拡張機能によって追加）。

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

空間コンテナは適合性テスト用に作成され、レンダリング パスがありません（XR_EXT_spatial_container_conformance_automation 拡張機能によって追加）。

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

空間コンテナは OpenXR システム レンダリングを使用します（XR_EXTX1_system_renderer 拡張機能によって追加）

空間コンテナの状態

空間コンテナの状態は、アプリのリクエストとユーザーのニーズの両方に基づいて、ランタイムによって管理されます。このため、空間コンテナの状態の各側面には、次のことが記載されています。

  • ランタイムが空間コンテナの状態を変更できる場合。ほとんどの空間コンテナの状態について、ランタイムはいつでも状態を変更できます。
  • アプリが状態の変更をリクエストする方法。ランタイムは、リクエストが適切であると判断するまで、リクエストを延期しても構いません。リクエストが延期された場合、ランタイムはイベントをキューに入れません。そのため、アプリは、無関係なロジックでそのようなイベントを待機すべきではありません。
  • 空間コンテナの状態が変化したときにイベント ランタイムがキューに入れるもの。ランタイムは、アプリがリクエストした変更やランタイムが開始した変更など、すべての変更のイベントをキューに入れます。ランタイムは、変化を示さない状態変化イベントをキューに追加してはなりません。たとえば、アプリがコンテナを非表示にするリクエストを 2 回連続して行った場合などです。
  • アプリ変更リクエストを拒否したときにイベント ランタイムがキューに入れるもの。ランタイムは、何らかの理由でリクエストを拒否する可能性があります。通常は、高品質のユーザー エクスペリエンスの維持に関連するシステム ポリシーが理由です。

xrGetSpatialContainerStateEXT 関数は、空間コンテナの現在の状態をクエリします。

XrResult xrGetSpatialContainerStateEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerStateGetInfoEXT*    getInfo,
    XrSpatialContainerStateEXT*                 state);

パラメータの説明

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerStateGetInfoEXT は、xrGetSpatialContainerStateEXT とともに使用して XrSpatialContainerStateEXT をクエリします。

typedef struct XrSpatialContainerStateGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerStateGetInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。

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

typedef struct XrSpatialContainerStateEXT {
    XrStructureType                    type;
    void*                              next;
    XrBool32                           visible;
    XrBool32                           interactable;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerStateEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • visible は、空間コンテナが表示されるかどうかを表します。
  • interactable は、空間コンテナが現在、あらゆる種類の入力を受け取れるかどうかを表します。これは、デスクトップ 2D ウィンドウ システムの「フォーカス」に似ていますが、複数の空間コンテナを同時に操作できる点が異なります。
  • boundsMode は、空間コンテナの現在の XrSpatialContainerBoundsModeEXT です。

空間コンテナの状態の変更は、イベントを介して通知されます。

フィールド変更イベント

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

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

  • XR_EXT_spatial_container 拡張機能は、XrSpatialContainerStateEXT を使用する前に有効にしなければなりません。
  • type は XR_TYPE_SPATIAL_CONTAINER_STATE_EXT にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。

公開設定

アプリは、xrRequestSpatialContainerVisibleEXT を使用して、空間コンテナの表示または非表示をリクエストします。

XrResult xrRequestSpatialContainerVisibleEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerVisibleRequestInfoEXT* info);

パラメータの説明

空間コンテナの表示と非表示の切り替えは非同期オペレーションです。

アプリは、空間コンテナを破棄する前に非表示にするようリクエストすべきです。これにより、ランタイムはスムーズな遷移を表示できます。ランタイムは、空間コンテナを非表示にするリクエストを尊重すべきです。

ランタイムは、空間コンテナを表示するリクエストを拒否しても構いません。その場合、ランタイムは XrEventDataSpatialContainerVisibleRequestDeniedEXT イベントをキューに追加しなければなりません。たとえば、一部のランタイムでは、ユーザーがシステム提供の「最小化」ボタンを操作して非表示にした空間コンテナを表示するリクエストが拒否されます。

ランタイムは、アプリが空間コンテナの表示を少なくとも 1 回リクエストするまで、空間コンテナを表示してはなりません。アプリが空間コンテナの表示を最初にリクエストした後、ランタイムは、アプリのリクエストとは無関係に、その空間コンテナの可視性を変更しても構いません。これにより、アプリは空間コンテナの初期状態とコンテンツを制御できるようになり、ランタイムはタスクバーなどのシステム UI を提供して、ユーザーが表示する空間コンテナを選択できるようになります。

ランタイムは、XrSystemSpatialContainerPropertiesEXT :: supportsBounded と XrSystemSpatialContainerPropertiesEXT :: supportsImmersive に基づいてサポートされていない境界モードで空間コンテナを表示するリクエストを拒否しなければなりません。これは、デフォルトの境界モード XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT が特定のシステムでサポートされていない場合に発生する可能性があります。

注

一部の実装では、空間コンテナの表示または非表示にシステム サービスとの通信が必要であり、ユーザーがシステム ダイアログを操作するまで延期される可能性があります。可視性状態の変更をリクエストする非同期設計は、ランタイムがこれら両方のオペレーションを完了する時間を確保することを目的としています。

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerVisibleRequestInfoEXT は、xrRequestSpatialContainerVisibleEXT とともに使用して、空間コンテナの可視性を変更します。

typedef struct XrSpatialContainerVisibleRequestInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           visible;
} XrSpatialContainerVisibleRequestInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • visible は、空間コンテナの表示または非表示がリクエストされているかどうかを表します。

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

ランタイムが空間コンテナの可視性を変更するたびに、ランタイムは新しい状態の XrEventDataSpatialContainerVisibleChangedEXT イベントをキューに追加しなければなりません。

typedef struct XrEventDataSpatialContainerVisibleChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 visible;
} XrEventDataSpatialContainerVisibleChangedEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • spatialContainer は、このイベントの対象となる XrSpatialContainerEXT です。
  • visible は、空間コンテナの新しい表示状態です。

このイベントは XR_SESSION_STATE_VISIBLE に代わるもので、コンテナごとに異なる値を設定できます。アプリがリクエストした変更やランタイムが開始した変更など、すべての変更について、イベントをキューに追加する必要があります。

ランタイムは、visible を XR_TRUE に設定してこのイベントをキューに登録した後、コンテナのレンダリングを数フレーム遅らせる可能性があります。これは、空のコンテナが表示されるのを回避し、アプリが初期コンテンツを送信する時間を確保するためです。この間、XrSpatialContainerStateEXT ::visible は XR_TRUE になります。ランタイムは、コンテナのレンダリングを 0.5 秒以上遅延すべきではありません。

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

ランタイムは、コンテナを表示するリクエストを拒否するたびに、XrEventDataSpatialContainerVisibleRequestDeniedEXT イベントをキューに登録しなければなりません。

typedef struct XrEventDataSpatialContainerVisibleRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerVisibleRequestDeniedEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • spatialContainer は、このイベントの対象となる XrSpatialContainerEXT です。

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

操作可能

アプリは、空間コンテナを操作可能にするようリクエストすることはできません。操作可能な空間コンテナは、ランタイムによって完全に制御されます。インタラクティブな空間コンテナは、表示する必要もあります。

ランタイムが空間コンテナの操作可能な状態を変更するたびに、ランタイムは新しい状態の XrEventDataSpatialContainerInteractableChangedEXT イベントをキューに追加しなければなりません。

typedef struct XrEventDataSpatialContainerInteractableChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 interactable;
} XrEventDataSpatialContainerInteractableChangedEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • spatialContainer は、このイベントの対象となる XrSpatialContainerEXT です。
  • interactable は、空間コンテナの新しいインタラクティブな状態です。

このイベントは XR_SESSION_STATE_FOCUSED に代わるもので、コンテナごとに異なる値を設定できます。このイベントは、ランタイムによって開始された変更を含むすべての変更に対してキューに入れられます。

ランタイムは、いつでも空間コンテナとのインタラクションを有効または無効にできます。ランタイムが一度に 1 つの空間コンテナのみを操作可能にすることをサポートしている場合、ランタイムが操作可能な空間コンテナを変更するときに、ランタイムは、操作可能でなくなるコンテナ（interactable が false に設定されている）のイベントを、操作可能になるコンテナ（interactable が true に設定されている）のイベントの前にキューに追加しなければなりません。

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

境界

空間コンテナには、境界モードと境界ボックスがあります。空間コンテナの境界モードは、境界の動作を記述します。その境界ボックスは、空間コンテナが内部に描画するものです。

XrSpatialContainerBoundsModeEXT 列挙型は、空間コンテナの境界が取り得るさまざまなモードを識別します。

typedef enum XrSpatialContainerBoundsModeEXT {
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT = 1,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT = 2,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerBoundsModeEXT;

列挙型の説明

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

空間コンテナは境界付きです。境界は有限のボックスです。空間コンテナはこのリージョンにのみ表示されます。

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

空間コンテナは没入型で、境界がありません。空間コンテナが画面全体に表示されます。

境界モード XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT の空間コンテナには、追加の要件があります。

  • ランタイムは、セッション状態の変更で説明されている動作の変更を除き、これらの空間コンテナを、空間コンテナを使用せずに作成された全画面表示の没入型アプリと同じように扱う必要があります。
  • ランタイムは、没入型空間コンテナが、この拡張機能なしで作成された全画面アプリや没入型アプリとは異なる動作をするように、追加の拡張機能を提供する場合があります。
  • ランタイムは、これらの空間コンテナに対して無限の境界を報告しなければなりません。
  • ランタイムは、没入型空間コンテナが表示されている間、他の空間コンテナを非表示にしても構いません。これはランタイムごとに異なる可能性があるため、アプリは、没入型空間コンテナの可視性に基づいて空間コンテナが自動的に表示または非表示になることに依存すべきではありません。他のすべての可視状態の遷移と同様に、ランタイムは、没入型コンテナが表示されているために空間コンテナが非表示になっている場合、XrEventDataSpatialContainerVisibleChangedEXT イベントをキューに追加しなければなりません。

注

上記の要件は、すべてのランタイムが、この拡張機能を使用せずに OpenXR 1.x パスを実装できることを意味します。これは、空間コンテナを暗黙的に作成し、コンテナの境界モードを没入型に設定して、表示可能にするようリクエストすることで実現されます。

アプリは、xrRequestSpatialContainerBoundsModeEXT を使用して、空間コンテナの境界モードの変更をリクエストします。

XrResult xrRequestSpatialContainerBoundsModeEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsModeRequestInfoEXT* info);

パラメータの説明

空間コンテナの境界モードの変更は非同期オペレーションであり、ランタイムは、アプリが変更をリクエストしてから数秒後に、変更または拒否されたイベントをキューに入れる可能性があります。これにより、ランタイムは、ユーザーが安全に没入モードに移行するために必要な UI をポップアップ表示できます。

ランタイムは、表示されていない空間コンテナの境界モードを変更するリクエストを尊重しなければなりません。ランタイムが、表示されていないコンテナに対する境界モードのリクエストを拒否する場合、代わりに、そのような空間コンテナを表示するリクエストを拒否または延期してもかまいません。これにより、アプリはコンテナを没入型コンテナとして起動できます。ランタイムは、表示されている空間コンテナの境界モードを変更するリクエストを拒否しても構いません。その場合、ランタイムは XrEventDataSpatialContainerBoundsModeRequestDeniedEXT イベントをキューに格納しなければなりません。たとえば、一部のランタイムでは、ユーザーがアクティブに操作していない表示可能な空間コンテナの境界モードを変更するリクエストが拒否されます。

ランタイムは、アプリが XrSystemSpatialContainerPropertiesEXT :: supportsBounded と XrSystemSpatialContainerPropertiesEXT :: supportsImmersive に基づいてサポートされていない境界モードをリクエストした場合、XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerBoundsModeRequestInfoEXT は、xrRequestSpatialContainerBoundsModeEXT とともに使用して、空間コンテナの境界モードを変更します。

typedef struct XrSpatialContainerBoundsModeRequestInfoEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerBoundsModeRequestInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • boundsMode は、空間コンテナに必要な XrSpatialContainerBoundsModeEXT です。

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

ランタイムが空間コンテナの境界または境界モードを変更するたびに、ランタイムは新しい境界情報を含む XrEventDataSpatialContainerBoundsChangedEXT イベントをキューに追加しなければなりません。

typedef struct XrEventDataSpatialContainerBoundsChangedEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerEXT              spatialContainer;
    XrExtent3Df                        bounds;
    XrBool32                           infiniteBounds;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrEventDataSpatialContainerBoundsChangedEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • spatialContainer は、このイベントの対象となる XrSpatialContainerEXT です。
  • bounds は、空間コンテナの境界の新しい幅、高さ、奥行きです。
  • コンテナの境界が無限の場合、infiniteBounds は true になります。
  • boundsMode は、空間コンテナの新しい XrSpatialContainerBoundsModeEXT です。

このイベントは、アプリがリクエストした変更やランタイムが開始した変更など、すべての変更に対してキューに入れられます。

ユーザーが空間コンテナのサイズをインタラクティブに変更している間、ランタイムは次のいずれかの方法で動作しなければなりません。

  • ユーザーが空間コンテナのサイズを変更しているときに、多くのイベントをキューに入れる（フレームレートで発生する可能性が高い）
  • サイズ変更の最後に 1 つのイベントをキューに入れる

ランタイムがサイズ変更の終了時に 1 つのイベントのみをキューに入れる場合、そのランタイムは、サイズ変更イベントをキューに入れるまで、xrGetSpatialContainerBoundsEXT から古い境界をレポートし続けなければなりません。ランタイムは、ポーリングされていない複数の境界変更イベントを統合しなければなりません。つまり、XrEventDataSpatialContainerBoundsChangedEXT イベントがキューに登録されている間に境界または境界モードが変更された場合、ランタイムは、最後に発生した境界変更を含む単一のイベントのみをレポートしなければなりません。アプリは xrGetSpatialContainerBoundsEXT を使用して空間コンテナの境界を直接ポーリングすることもできるため、イベントによる境界の変更回数は、ランタイムが生成した境界の変更のタイミング、アプリによる xrPollEvent の呼び出し、アプリによる xrGetSpatialContainerBoundsEXT の呼び出しに基づいて、ポーリングによる変更回数と異なる場合があります。

空間コンテナの境界が変更されると、空間コンテナのローカル原点も変更される可能性があります。たとえば、ランタイムでユーザーがコンテナの端をドラッグして空間コンテナの境界のサイズを変更できる場合、ユーザーが 1 つの端をドラッグすると、そのコンテナの境界とローカル原点が変更されます。このような状況では、ランタイムは境界とローカル原点を同時に変更する必要があります。

ランタイムは、infiniteBounds を XR_TRUE に設定し、幅、高さ、奥行きを 0.0 に設定して、無限の境界を表す必要があります。ランタイムは、infiniteBounds を XR_FALSE に設定し、幅、高さ、奥行きを有限の正の数に設定して、有限の境界を設定しなければなりません。

ランタイムは、XrSpatialContainerBoundsEXT と同じルールに従って bounds と infiniteBounds を設定しなければなりません。

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

ランタイムは、コンテナの境界モードを変更するリクエストを拒否するたびに、XrEventDataSpatialContainerBoundsModeRequestDeniedEXT イベントをキューに追加しなければなりません。

typedef struct XrEventDataSpatialContainerBoundsModeRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerBoundsModeRequestDeniedEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • spatialContainer は、このイベントの対象となる XrSpatialContainerEXT です。

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

XrSpatialContainerBoundsEXT 構造体は、空間コンテナの境界ボックスを記述します。

typedef struct XrSpatialContainerBoundsEXT {
    XrStructureType    type;
    void*              next;
    XrExtent3Df        bounds;
    XrBool32           infiniteBounds;
} XrSpatialContainerBoundsEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • bounds は、空間コンテナの境界の幅、高さ、奥行きです。境界はメートル単位です。
  • コンテナの境界が無限の場合、infiniteBounds は true になります。

ランタイムは、infiniteBounds を XR_TRUE に設定し、幅、高さ、奥行きを 0.0 に設定して、無限の境界を表す必要があります。ランタイムは、infiniteBounds を XR_FALSE に設定し、幅、高さ、奥行きを有限の正の数に設定して、有限の境界を設定しなければなりません。

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

xrGetSpatialContainerBoundsEXT 関数は、空間コンテナの現在の境界をクエリします。

XrResult xrGetSpatialContainerBoundsEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsGetInfoEXT*   getInfo,
    XrSpatialContainerBoundsEXT*                bounds);

パラメータの説明

空間コンテナが境界付きの場合、無限の境界を持ってはなりません。空間コンテナが没入型の場合、無限の境界を持たなければなりません。

ランタイムは、空間コンテナが境界付けられている間、いつでも空間コンテナの境界を任意の正の有限値に変更できます。空間コンテナの境界の変更は、XrEventDataSpatialContainerBoundsChangedEXT を介して通知されます。

この拡張機能を使用すると、アプリは xrRequestSpatialContainerBoundsModeEXT を使用して境界と没入型を切り替える以外の境界の変更をリクエストできません。今後、他の拡張機能でそのような方法が提供される可能性があります。

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerBoundsGetInfoEXT 構造体は、将来の拡張を目的として存在する入力構造体です。

typedef struct XrSpatialContainerBoundsGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerBoundsGetInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。

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

XrSpatialContainerVolumeClippingEXT 列挙型は、空間コンテナのさまざまなボリューム クリッピング動作を識別します。

typedef enum XrSpatialContainerVolumeClippingEXT {
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT = 0,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT = 1,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerVolumeClippingEXT;

列挙型の説明

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

空間コンテナの境界ボリュームにクリップされるコンテンツはありません。コンテンツは、空間コンテナの境界外に描画できます。

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

コンテンツは、空間コンテナの境界ボリュームに厳密にクリップされます。

この拡張機能では、この列挙型は使用されません。これは、他の拡張機能が目的のボリューム クリッピング動作を指定できるように定義されています。たとえば、アプリは、境界のある空間コンテナの背景を描画したい場合があります。単眼キューブマップは背景を指定する便利な方法ですが、概念的にはコンテナの外側の無限遠に配置されます。

システム機能

アプリは、xrGetSystemProperties を呼び出すときに XrSystemSpatialContainerPropertiesEXT 構造体を XrSystemProperties にチェーンすることで、システム機能を検査できます。

typedef struct XrSystemSpatialContainerPropertiesEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSpatialContainerCount;
    XrBool32           supportsBounded;
    XrBool32           supportsImmersive;
} XrSystemSpatialContainerPropertiesEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • maxSpatialContainerCount は、作成できる空間コンテナの最大数です。
  • 空間コンテナを境界にできる場合、supportsBounded は true です。
  • 空間コンテナを没入型にできる場合は、supportsImmersive が true になります。

この拡張機能をサポートするランタイムは、メモリ割り当てによってのみ制限される、多くの空間コンテナを作成するアプリをサポートすべきです。ランタイムは、同時に表示される空間コンテナの数に異なる上限を設ける場合があります。ランタイムは、実行中のすべてのアプリの状態に基づいて個々のアプリを制限する可能性があるため、この拡張機能で同時に表示されるコンテナの数をクエリする方法はありません。制約の厳しいデバイスと制約の少ないデバイスでは、同時に表示されるコンテナの数に異なる制限があると想定されます。制約の厳しいデバイスは、一度に 1 つの空間コンテナのみを表示することをサポートしてもよく、制約の少ないデバイスは、レンダリングの計算制限に応じて、多数の空間コンテナを同時に表示することをサポートしてもよいです。

この拡張機能をサポートするランタイムは、境界付き空間コンテナまたは没入型空間コンテナの少なくとも 1 つをサポートしなければなりません。

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

xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT 関数は、システムでサポートされているグラフィック プレゼンテーション メソッドを返します。

XrResult xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    graphicsPresentationCapacityInput,
    uint32_t*                                   graphicsPresentationCountOutput,
    XrSpatialContainerGraphicsPresentationEXT*  graphicsPresentations);

パラメータの説明

  • instance は、systemId の取得元である XrInstance です。
  • systemId は、クエリ対象の XrSystemId です。
  • graphicsPresentationCapacityInput は graphicsPresentations 配列の容量です。0 の場合は、必要な容量を取得するリクエストであることを示します。
  • graphicsPresentationCountOutput は、書き込まれたグラフィック プレゼンテーションの数へのポインタ、または graphicsPresentationCapacityInput が 0 の場合は必要な容量へのポインタです。
  • graphicsPresentations は XrSpatialContainerGraphicsPresentationEXT 値の配列へのポインタですが、graphicsPresentationCapacityInput が 0 の場合は null になる可能性があります。
  • 必要な graphicsPresentations サイズの取得の詳細については、バッファサイズ パラメータのセクションをご覧ください。

ランタイムは、指定された systemId とインスタンスの存続期間について、この列挙から常に同じバッファ コンテンツを返さなければなりません。

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

  • XR_EXT_spatial_container 拡張機能は、xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT を呼び出す前に有効にする必要があります。
  • instance は、有効な XrInstance ハンドルでなければなりません。
  • graphicsPresentationCountOutput は uint32_t 値へのポインタでなければなりません
  • graphicsPresentationCapacityInput が 0 でない場合、graphicsPresentations は graphicsPresentationCapacityInput XrSpatialContainerGraphicsPresentationEXT 値の配列へのポインタでなければなりません。

戻りコード

成功

  • 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

セッション状態の変更

セッションの空間コンテナのサポートを有効にするには、xrCreateSession を呼び出すときに XrSessionCreateInfoSpatialContainersEXT をチェーンします。

typedef struct XrSessionCreateInfoSpatialContainersEXT {
    XrStructureType    type;
    const void*        next;
} XrSessionCreateInfoSpatialContainersEXT;

空間コンテナのサポートが有効になっている場合、XrSession の動作は異なります。これは、空間コンテナを使用すると、セッションがディスプレイに画像コンテンツを表示しなくなり、代わりに空間コンテナが画像コンテンツを表示するためです。したがって、この拡張機能を有効にすると、セッションは実質的に「ヘッドレス」になります。他のヘッドレス拡張機能とは異なり、アプリは空間コンテナを介して画像データを送信できます。

空間コンテナのサポートを有効にすると、コア OpenXR API が次のように変更されます。

ランタイム: システムまたはデバイスの損失

ランタイム: システムまたはデバイスの喪失

xrDestroySession

xrDestroySession

IDLE
（実行中）

アイドル状態...

xrGetSystem
xrCreateSession

xrGetSystem...

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
（実行されていない）

LOSS_PENDING...

xrDestroyInstance

xrDestroyInstance

アプリ: 必要に応じて
XR を再起動

app: 必要に応じて...

図 19: 新しいセッション状態マシン

  • セッションが XR_SESSION_STATE_VISIBLE、XR_SESSION_STATE_FOCUSED、XR_SESSION_STATE_EXITING の状態になることはありません。ランタイムは、これらの状態のイベントをキューに追加してはなりません。これらの状態は、空間コンテナごとのイベント XrEventDataSpatialContainerVisibleChangedEXT、XrEventDataSpatialContainerInteractableChangedEXT、XrEventDataSpatialContainerClosedEXT にそれぞれ置き換えられます。
  • また、セッションが XR_SESSION_STATE_READY、XR_SESSION_STATE_SYNCHRONIZED、XR_SESSION_STATE_STOPPING の状態になることはありません。ランタイムは、これらの状態のイベントをキューに追加してはなりません。これらの状態に代わるものはありません。
  • ランタイムは、セッションが XR_SESSION_STATE_IDLE 状態のときに、セッションが実行中であると扱う必要があります。
  • ランタイムは、状態が XR_SESSION_STATE_IDLE で、操作可能な空間コンテナが少なくとも 1 つ存在する場合、セッションをフォーカスされているものとして扱う必要があります。
  • xrBeginSession 関数と xrEndSession 関数は不要になりました。ランタイムは、これらの関数が呼び出されたときに XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT を返す必要があります。他の拡張機能がこれらの関数の代替機能を提供する場合があります。
  • xrRequestExitSession 関数も不要になりました。この関数が呼び出されたとき、ランタイムは XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT を返す必要があります。実行中のセッションを終了するアプリは、xrRequestSpatialContainerVisibleEXT を呼び出してコンテナを非表示にし、すべてのコンテナが表示されなくなったらセッションを破棄できます。

  • セッションの実行開始時に追加のイベントをキューに登録する拡張機能は、セッションの作成後に追加のイベントをキューに登録する必要があります。このような拡張機能については、以下で説明します。

    拡張機能イベント

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

  • xrLocateViews 関数は、セッションに対して呼び出すことができません。ランタイムは、xrLocateViews から XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT を返す必要があります。他の拡張機能では、特定の空間コンテナのビューを特定する方法が提供される場合があります。
  • xrWaitFrame 関数は、XrFrameState :: shouldRender を常に false に設定しなければなりません。他の拡張機能では、特定の空間コンテナがコンポジション レイヤを更新する必要があるかどうかを判断する方法が提供される場合があります。
  • xrEndFrame 関数は、コンポジション レイヤを送信する有効な方法ではありません。アプリが XrFrameEndInfo :: layerCount をゼロ以外の値に設定すると、ランタイム は XR_ERROR_VALIDATION_FAILURE を返さなければなりません。他の拡張機能では、特定の空間コンテナにコンポジション レイヤを送信する方法が提供される場合があります。
  • XR_SESSION_STATE_LOSS_PENDING 状態になると、すべての空間コンテナも閉じられます。ランタイムは、XR_SESSION_STATE_LOSS_PENDING のセッション状態の変更をキューに入れる前に、アクティブな空間コンテナごとに XrEventDataSpatialContainerClosedEXT イベントをキューに入れる必要があります。
  • xrCreateSession 関数に、グラフィック API バインディング構造が不要になりました。他の拡張機能では、グラフィック バインディングが必要になる場合があります。たとえば、グラフィック API を使用してレンダリングする空間コンテナなどです。

上記の動作は、XR_MND_headless の動作とは若干異なります。ランタイムは、セッションで空間コンテナのサポートが有効になっている場合、XR_MND_headless からヘッドレス セッションの動作を有効にしてはなりません。

注

空間コンテナが有効になっている場合、セッションは XR_SESSION_STATE_IDLE（実行中）と XR_SESSION_STATE_LOSS_PENDING（実行されていない）の 2 つの状態間でのみ遷移します。その結果、ランタイムは XR_ERROR_SESSION_RUNNING または XR_ERROR_SESSION_NOT_RUNNING を返さなくなりました。代わりに、セッションが実行されていない場合、ランタイムは OpenXR コアのルールに従って XR_ERROR_SESSION_LOST または XR_SESSION_LOSS_PENDING を返します。さらに、XR_ERROR_SESSION_RUNNING を返す唯一の関数である xrBeginSession は、常に XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT を返すようになります。

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

Android マニフェスト エントリ

AOSP ベースのランタイムは、アプリコードを実行する前に開始される初期の空間コンテナの状態に基づいて、カスタム動作を行う場合があります。たとえば、ランタイムは、アクティビティ、起動アニメーション、スプラッシュ画面の表示に割り当てられたリソースを変更する場合があります。この目的のために、次のプロパティが用意されています。<category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> タグは、以前の AOSP ベースのランタイムとの互換性を確保する場合を除き、空間コンテナ ベースのアプリで指定すべきではありません。

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
          android:value="list of modes" />

このプロパティは、アクティビティで使用される境界モードをランタイムにヒントとして提供します。デフォルトでは空のリストです。これはヒントがないことを意味します。

次の文字列は、この属性に有効です。複数の値がある場合は、"bounded|immersive" のように | で区切られます。

値

説明

"2d_panel"

アクティビティは、Android の 2D ビュー フレームワークを使用して表示されます。

"bounded"

このアクティビティでは XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT を使用します。

"immersive"

このアクティビティでは XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT を使用します。

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
          android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED" />

このプロパティは、アクティビティが最初に作成されたときに、アクティビティの初期 XrSpatialContainerBoundsModeEXT を実行するようランタイムに指示します。デフォルトは文字列 XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED で、ヒントがないことを意味します。

ランタイムは、この仕様に従って動作するために、アプリにこれらのプロパティを要求してはなりません。ランタイムは、これらのプロパティに基づいてアプリの可視動作を変更してはなりません。このようなメタデータはすべて、<activity> レベルまたは <application> レベルで指定しなければなりません。<application> レベルで指定した場合、この属性は、独自の値が指定されていないアプリ内のすべてのアクティビティに適用されます。

コード例

次のコードは、レンダリングなしで認識のみのユースケースにこの拡張機能を使用する方法を示しています。

XrInstance instance;    // Already initialized


// Create the session with spatial containers enabled
XrSession session;

XrSessionCreateInfoSpatialContainersEXT spatialContainerCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT,
};
XrSessionCreateInfo sessionCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO,
  .next = &spatialContainerCreateInfo,   // Enable spatial containers
};
(void)sessionCreateInfo.systemId;                             // Other create fields set in usual way

CHK_XR(xrCreateSession(instance, &sessionCreateInfo, &session));


// Because spatial containers are enabled, the session is considered
// running. App is able to query perception data such as head poses and hand
// poses.


// Based on app logic or when a system lost event happens, destroy the
// session
CHK_XR(xrDestroySession(session));

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

新しいコマンド

新しい構造

新しい列挙型

新しい列挙型定数

  • XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
  • XR_EXT_spatial_container_SPEC_VERSION

  • XrObjectType の拡張:

    • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

  • XrResult の拡張:

    • XR_ERROR_COMPATIBLE_SPATIAL_CONTAINER_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT

  • XrStructureType の拡張:

    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_DENIED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_CLOSED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_INTERACTABLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_REQUEST_DENIED_EXT
    • XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_SPACE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VISIBLE_REQUEST_INFO_EXT
    • XR_TYPE_SYSTEM_SPATIAL_CONTAINER_PROPERTIES_EXT

問題

  • 複数の未処理の表示リクエストを処理するにはどうすればよいですか？アプリは 1 つの変更 / 拒否を受け取るべきか、それとも複数受け取るべきか。呼び出しが複数のフレームにまたがっている場合、答えが異なる可能性があります。また、複数のリクエストが noop になる場合（たとえば、空間コンテナを表示するようにリクエストした後、最初は表示されていなかったコンテナを表示しないようにリクエストした場合）も、回答が異なる可能性があります。

    • 解決済み。変更イベントと拒否イベントの選択肢が異なります。Noop リクエストは変更イベントをキューに入れません。これはアプリ デベロッパーにとってノイズを発生させるだけで、ランタイムで簡単に除外できます。複数の表示可能なリクエストが拒否された場合、ランタイムはそれぞれに対応する拒否イベントを生成しなければなりません。

  • ポリシー動作に関するすべてのオプションの仕様テキストを CTS でテストできるように、適合性自動化拡張機能を定義するにはどうすればよいですか？

    • 解決済み。別のテスト拡張機能。CTS 専用のテスト拡張機能ランタイムが実装され、CTS がすべてのシステム ポリシーを制御できるようになります。

  • 空間コンテナの位置が変更されたときにイベントが必要ですか？

    • 解決済み。いいえ。空間コンテナ空間はワールドロックされておらず、XR_REFERENCE_SPACE_TYPE_VIEW などの他の空間には、変更時にイベントがありません。

  • 複数の空間コンテナがある場合、xrSyncActions はどのように機能しますか？

    • 解決済み。変更は必要ありません。 xrSyncActions は、セッション内のすべての空間コンテナに適用されます。アプリが入力アクションを特定の空間コンテナに転送する場合は、コンテナごとの操作可能な状態を調べて、有効なターゲットとなるコンテナを選択できます。アプリが単一の空間コンテナの入力アクション状態のみを同期する場合は、追加の拡張機能が必要になります。ただし、代わりに、アプリを完全にイベントベースにして、フレームループで xrSyncActions 呼び出しを必要としない拡張機能に注力する予定です。

  • 更新頻度の低いアプリは入力をどのように処理するか

    • 解決済み。変更は不要です。EXT_spatial_container にとって有用であるだけでなく、空間コンテナの外部でも有用です。これは、イベント チャネル拡張機能を使用して処理でき、どちらの場合でも機能します。空間コンテナについては、単一の空間コンテナのイベントをフィルタする追加の方法を追加する予定です。

  • 入力ループとレンダリング ループが分離されているアプリの場合、入力ループのタイミングをスロットル / 制御するために待機する必要がありますか？

    • 解決済み。変更は不要です。これは、イベント チャネルと現在のリクエスト拡張機能で処理されることが想定されています。Present リクエスト拡張機能を使用すると、レンダリングをイベントベースにして、フレームループから切り離すことができます。

  • 空間コンテナは、他の空間コンテナを基準としたポーズを取得できますか？重要なポイントは、これに該当するユースケースがあるかどうかです。その場合、空間コンテナ空間は LOCAL にどのように接続されますか？

    • 解決済み。はい。これは、XR_REFERENCE_SPACE_TYPE_VIEW を使用することで、同じセッション内の空間コンテナですでに可能であり、ビュー依存のコンテンツをサポートすることが望ましいです。セッション間で空間コンテナのポーズを共有する場合（別のプロセスなど）、想定されるパスは、XR_EXT_spatial_anchor とその既存の永続化パターンおよび共有パターンを利用することです。

  • 空間コンテナの空間が表示されていない場合、その空間を特定できますか？

    • 解決済み。いいえ。空間コンテナが表示されていない場合、空間コンテナのスペースは特定できません。つまり、空間オーディオはなく、spatial_container が表示されていないときに、アプリがビューに依存するコンテンツを「ウォームアップ」することもできません。空間コンテナが表示されていない場合、アプリはその空間コンテナに使用されている CPU / GPU 負荷を停止することが想定されているため、どちらも問題ありません。

  • 空間コンテナ スペースは、空間コンテナのどこに配置されることが想定されていますか？候補は、中心または最小点（minX、minY、minZ）です。

    • 解決済み。中央にあります。空間コンテナのサイズ変更 UX で想定されるほとんどの方法（エッジの移動）で移動しない場所はありません。Center は、OpenXR の他の部分で一般的に使用されます。3D モデル ビューアは、最小座標を使用する 2D コンピューティングのウィンドウの規則に従わないことが多いため、この規則は採用しませんでした。

  • ランタイムが空間コンテナの基盤となるリソースを作成するのはいつですか？これには、システム サービスとの IPC が含まれることがあります。

    • 解決済み。xrCreateSpatialContainerEXT の一部として同期的に。IPC が関与する可能性はありますが、コンテナの実際の作成は一般的に低コストであると想定されます。一部のベンダーには、コンテナの管理に関するグローバル ミューテックスがありますが、通常、これらは長時間待機することはありません。ミューテックスの競合に関する問題はベンダー固有のバグであり、各ベンダーが対処する必要があります。

  • XrSession が空間コンテナを作成し、以前のレンダリング パスをサポートしないことを示すシグナルが必要かどうか。

    • 解決済み。はい。セッション ステート マシンを根本的に変更します。

変更履歴

  • リビジョン 1、2026 年 8 月 6 日（Jared Finder、Google）

    • 拡張機能の初期説明