XR_EXT_spatial_container_self_rendering

Name String

XR_EXT_spatial_container_self_rendering

拡張機能の種類

インスタンス拡張

登録済みの内線番号

814

リビジョン

1

承認ステータス

未批准

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

XR_EXT_spatial_container

最終更新日

2026-08-06

IP ステータス

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

寄与者

Lachlan Ford、Google
Andreas Loeve Selvik、Meta Platforms
Adam Gousetis、Meta Platforms
Bjorn Swenson、LÖVR
Cass Everitt、Meta Platforms
Christian Kruse、Meta Platforms
Denny Rönngren、Varjo Technologies
Fredia Huya-Kouadio、Godot Engine
Jakob Bornecrantz、NVIDIA
Jared Finder、Google
Jonathan Wright、Meta Platforms
Jian Zhang、ByteDance
Kurtis Eveleigh、Qualcomm
Mauricio Narvaez、Meta Platforms
Nick Klingensmith、Qualcomm
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

概要

この拡張機能は、空間コンテナの「セルフ レンダリング」を定義します。自己レンダリング空間コンテナのピクセルはすべてアプリによって生成され、標準の OpenXR スワップチェーンとコンポジション レイヤを使用してランタイムに送信されます。空間コンテナが画面のすべてのピクセルを占有するとは限らないため、ランタイムは各空間コンテナの推奨解像度とビュー構成をアプリに通知し、アプリがより効率的にレンダリングできるようにします。

この拡張機能は、XR_EXT_spatial_container と組み合わせることで、従来の OpenXR 1.x コア コンポジション レイヤ レンダリングの機能のスーパーセットを提供することを目的としています。グラフィック レンダリングとこの拡張機能をサポートする OpenXR 1.x ランタイムは、XrSystemSpatialContainerPropertiesEXT :: supportsImmersive を true に設定して、没入型空間コンテナをサポートしていることを示す必要があります。

空間コンテナのレンダリング ライフサイクル

空間コンテナにセルフ レンダリングを使用するには、アプリは xrCreateSpatialContainerEXT を呼び出すときに XrSpatialContainerCreateInfoEXT :: graphicsPresentation を XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT に設定します。その後、そのアプリは xrBeginSpatialContainerRenderingEXT 関数と xrEndSpatialContainerRenderingEXT 関数を呼び出すことで、空間コンテナがアクティブにレンダリングされているかどうかを管理できます。これらの関数は、xrBeginSession と xrEndSession に代わるものです。xrBeginFrame や xrEndFrame などのフレームごとのオペレーションではありません。

アプリはフレームごとに次のステップを実行します。

  • xrWaitFrame と xrBeginFrame を呼び出します。これらの関数にはコンテナ固有の構造はなく、コア仕様と同じように機能します。
  • xrLocateSpatialContainerViewsEXT を使用して、アクティブにレンダリングしているすべての空間コンテナのビューポーズ、投影パラメータ、レンダリングの推奨事項を取得します。各空間コンテナについて、ランタイムは、そのコンポジション レイヤをレンダリングすべきかどうかと、レイヤをレンダリングするための推奨される方法を、XrSpatialContainerViewStateEXT に入力して報告します。
  • 通常どおり、ピクセルをコンポジション レイヤにレンダリングします。これらのオペレーションには、コンテナ固有の構造はありません。
  • xrEndFrame を呼び出し、XrSpatialContainerLayerFrameEndInfoEXT をチェーンすることで、アクティブにレンダリングしているすべての空間コンテナの合成レイヤを送信します。

XrSpatialContainerEXT ハンドルを破棄すると、アクティブなレンダリング セットから暗黙的に削除されます。アプリは、xrBeginSpatialContainerRenderingEXT の呼び出しに成功し、対応する xrEndSpatialContainerRenderingEXT の呼び出しに関連付けられていない場合でも、空間コンテナを破棄しても構いません。ランタイムは、xrDestroySpatialContainerEXT の実装の早い段階で必要に応じて xrEndSpatialContainerRenderingEXT が暗黙的に呼び出されたかのように動作しなければなりません。

アプリがアクティブなレンダリング セット内のコンテナの XrEventDataSpatialContainerClosedEXT イベントを受信すると、そのアプリは xrEndSpatialContainerRenderingEXT を呼び出し、XrSpatialContainerEXT ハンドルを破棄すべきです。

xrBeginSpatialContainerRenderingEXT 関数は、空間コンテナをセッションごとのアクティブなレンダリング セットに追加します。これにより、アプリは空間コンテナのコンポジション レイヤを xrEndFrame に送信できるようになります。

XrResult xrBeginSpatialContainerRenderingEXT(
    XrSession                                   session,
    const XrSpatialContainerBeginInfoEXT*       beginInfo);

パラメータの説明

通常、アプリは XrEventDataSpatialContainerVisibleChangedEXT :: visible が true に設定された visible-changed イベントに応じてこれを呼び出します。

xrCreateSpatialContainerEXT の呼び出し時に XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT を使用して空間コンテナが作成されなかった場合、ランタイムは XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT を返さなければなりません。

空間コンテナがすでにアクティブなレンダリング セットに含まれている場合、ランタイムは XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT を返さなければなりません。

アプリが xrWaitFrame を呼び出せないタイミング（xrBeginFrame と xrEndFrame のウィンドウ内など）で xrBeginSpatialContainerRenderingEXT が呼び出された場合、ランタイムは XR_ERROR_CALL_ORDER_INVALID を返さなければなりません。

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

スレッドセーフ

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT
  • XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

XrSpatialContainerBeginInfoEXT 構造体は、空間コンテナのレンダリングを開始するためのパラメータを指定するために使用されます。

typedef struct XrSpatialContainerBeginInfoEXT {
    XrStructureType            type;
    const void*                next;
    XrSpatialContainerEXT      spatialContainer;
    XrViewConfigurationType    primaryViewConfigurationType;
} XrSpatialContainerBeginInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • spatialContainer は、レンダリングを開始する XrSpatialContainerEXT です。
  • primaryViewConfigurationType は、空間コンテナに使用されるプライマリ XrViewConfigurationType です。

primaryViewConfigurationType は、アプリがレンダリング時に使用するビュー構成です。ランタイムは、最適化のために、ビュー構成をビュー数の少ないタイプに減衰させることがあります（たとえば、コンテナが非常に遠く、小さいため、ステレオが認識できない場合）。ランタイムは、xrLocateSpatialContainerViewsEXT の呼び出しから、減衰したビュー構成の詳細を返します。

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

xrEndSpatialContainerRenderingEXT 関数は、アクティブなレンダリング セットから空間コンテナを削除します。

XrResult xrEndSpatialContainerRenderingEXT(
    XrSession                                   session,
    const XrSpatialContainerEndInfoEXT*         endInfo);

パラメータの説明

通常、アプリは XrEventDataSpatialContainerVisibleChangedEXT :: visible が false に設定された visible-changed イベントに応答して、この関数を呼び出します。

空間コンテナがアクティブなレンダリング セットにない場合、ランタイムは XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT を返さなければなりません。

アプリが xrWaitFrame を呼び出せなかったとき（xrBeginFrame 呼び出しと xrEndFrame 呼び出しの間など）に xrEndSpatialContainerRenderingEXT が呼び出された場合、ランタイムは XR_ERROR_CALL_ORDER_INVALID を返さなければなりません。

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

スレッドセーフ

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerEndInfoEXT 構造体は、空間コンテナのレンダリングを終了するためのパラメータを指定するために使用されます。

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

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • spatialContainer は、レンダリングを終了する XrSpatialContainerEXT です。

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

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

xrLocateSpatialContainerViewsEXT を使用してビューを特定する

xrLocateSpatialContainerViewsEXT 関数は、一連の空間コンテナのビューを特定します。

XrResult xrLocateSpatialContainerViewsEXT(
    XrSession                                   session,
    const XrSpatialContainerViewsLocateInfoEXT* locateInfo,
    uint32_t                                    viewStateCount,
    XrSpatialContainerViewStateEXT*             viewStates,
    uint32_t                                    viewCount,
    XrView*                                     views);

パラメータの説明

  • session は XrSession です。
  • locateInfo は、XrSpatialContainerViewsLocateInfoEXT 構造体へのポインタです。
  • viewStateCount は viewStates 配列の数です。
  • viewStates は、ランタイムによって入力される XrSpatialContainerViewStateEXT 構造体の配列へのポインタです。
  • viewCount は views 配列の数です。
  • views は、XrView 構造体の配列へのポインタです。

この関数は xrLocateViews に代わるもので、アプリは複数の空間コンテナのビューを同時にクエリできます。

すべての空間コンテナのビューが、単一の views 配列で返されます。ビューは、XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfos 配列内の空間コンテナのインデックス、そのコンテナのビュー インデックスの順に並べられます。

たとえば、アプリが XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfos で 3 つの空間コンテナを提供する場合:

  • インデックス 0: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO（1 ビュー）
  • インデックス 1: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO（2 ビュー）
  • インデックス 2: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO_WITH_FOVEATED_INSET（4 ビュー）

この場合、ランタイムは views 配列に 7 つのビューを入力する必要があります。

  • views [0] はコンテナ 0 のビューです。
  • views [1] は、コンテナ 1 の左目ビューです。
  • views [2] は、コンテナ 1 の右目ビューです。
  • views [3] は、コンテナ 2 の左目ビューです。
  • views [4] は、コンテナ 2 の右目ビューです。
  • views [5] は、コンテナ 2 の左目のインセット ビューです。
  • views [6] は、コンテナ 2 の右目のインセット ビューです。

viewCount が、各空間コンテナのリクエストされたビュー構成タイプの視聴回数の合計と等しくない場合、ランタイム は XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

ランタイムは、最適化のために、ビュー構成をビュー数の少ないタイプに減衰させることがあります（たとえば、コンテナが非常に遠く、小さいため、ステレオが認識できない場合）。ランタイムがビュー構成を減衰させる場合、ランタイムは、そのコンテナの元のビュー数を返す必要があります。その際、減衰したビューの複製で追加のビューを埋めます。たとえば、XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO が XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO に減衰した場合、インデックス 0 とインデックス 1 の両方に単一のモノラルビューが含まれます。そのため、views 配列で返されるビューの総数は、ランタイムがビュー構成を破棄するかどうかとは無関係です。

ランタイムは、対応する空間コンテナの境界全体を包含しながら、視錐台が可能な限り小さくなるように、返される各 XrView :: fov を適応させるべきです。ランタイムは、非対称の FOV を返す場合があります。たとえば、空間コンテナがユーザーの視点に対して斜めの角度にある場合や、別のオブジェクトによって部分的に遮られている場合などです。ランタイムは、空間コンテナのターゲット レンダリング サーフェスを自由に配置できます。マルチアプリ レンダリングの性質上、空間コンテナはユーザーから切り離されているため、ランタイムはピクセル レンダリングに適さない XrView 値を返す可能性があります。たとえば、空間コンテナが画面に表示されていない場合、XrView :: fov に設定する有効な値はありません。このような場合、ランタイムは XrSpatialContainerViewStateEXT :: shouldSubmitLayers を false に設定しなければなりません。

ランタイムは、空間コンテナごとの追加のレンダリング状態情報を viewStates 配列で返します。viewStateCount が XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfoCount と等しくない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

ランタイムが空間コンテナの XrEventDataSpatialContainerClosedEXT イベントをキューに入れた後、この関数は、対応する空間コンテナの XrSpatialContainerViewStateEXT :: shouldSubmitLayers で XR_FALSE を、XrSpatialContainerViewStateEXT :: viewStateFlags で 0 を返さなければなりません。

現実世界で位置が活発に変化する空間コンテナの場合、ランタイムは、再投影アーティファクトを最小限に抑えるために、views を入力する際にコンテナの動きを考慮すべきです。

現在アクティブなレンダリング セットにない 1 つ以上の空間コンテナに対して xrLocateSpatialContainerViewsEXT が呼び出された場合、ランタイムは XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT を返さなければなりません。

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

  • xrLocateSpatialContainerViewsEXT を呼び出す前に、XR_EXT_spatial_container_self_rendering 拡張機能を有効にする必要があります。
  • session は、有効な XrSession ハンドルでなければなりません。
  • locateInfo は、有効な XrSpatialContainerViewsLocateInfoEXT 構造体へのポインタでなければなりません
  • viewStates は、viewStateCount XrSpatialContainerViewStateEXT 構造体の配列へのポインタでなければなりません。
  • views は、viewCount XrView 構造の配列へのポインタでなければなりません
  • viewStateCount パラメータは 0 より大きい値にする必要があります。
  • viewCount パラメータは 0 より大きい値にする必要があります。

戻りコード

成功

  • 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_NOT_RENDERING_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

XrSpatialContainerViewsLocateInfoEXT 構造体には、空間コンテナのコレクション全体でビューを特定するためのパラメータが含まれています。

typedef struct XrSpatialContainerViewsLocateInfoEXT {
    XrStructureType                               type;
    const void*                                   next;
    XrTime                                        displayTime;
    uint32_t                                      viewLocateInfoCount;
    const XrSpatialContainerViewLocateInfoEXT*    viewLocateInfos;
} XrSpatialContainerViewsLocateInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • displayTime は、ビューを配置する XrTime です。
  • viewLocateInfoCount は、viewLocateInfos 配列内のエントリ数です。
  • viewLocateInfos は、XrSpatialContainerViewLocateInfoEXT 構造体の配列へのポインタです。

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

  • XrSpatialContainerViewsLocateInfoEXT を使用する前に、XR_EXT_spatial_container_self_rendering 拡張機能を有効にしなければなりません。
  • type は XR_TYPE_SPATIAL_CONTAINER_VIEWS_LOCATE_INFO_EXT にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • viewLocateInfos は、viewLocateInfoCount 個の有効な XrSpatialContainerViewLocateInfoEXT 構造体の配列へのポインタでなければなりません。
  • viewLocateInfoCount パラメータは 0 より大きい値にする必要があります。

XrSpatialContainerViewLocateInfoEXT 構造体には、ビューを配置する個々の空間コンテナのパラメータが含まれています。

typedef struct XrSpatialContainerViewLocateInfoEXT {
    XrStructureType            type;
    const void*                next;
    XrViewConfigurationType    viewConfigurationType;
    XrSpace                    space;
    XrSpatialContainerEXT      spatialContainer;
} XrSpatialContainerViewLocateInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • viewConfigurationType は、空間コンテナに使用される XrViewConfigurationType です。
  • space は、空間コンテナのビューが配置されている XrSpace です。
  • spatialContainer は XrSpatialContainerEXT ハンドルです。

アプリは、space で有効な XrSpace を提供できますが、XrSpatialContainerViewLocateInfoEXT 構造内で指定された対応する XrSpatialContainerEXT の空間コンテナ空間を提供することをおすすめします。

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

  • XR_EXT_spatial_container_self_rendering 拡張機能は、XrSpatialContainerViewLocateInfoEXT を使用する前に有効にしなければなりません。
  • type は XR_TYPE_SPATIAL_CONTAINER_VIEW_LOCATE_INFO_EXT にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • viewConfigurationType は、有効な XrViewConfigurationType 値でなければなりません
  • space は有効な XrSpace ハンドルでなければなりません
  • spatialContainer は、有効な XrSpatialContainerEXT ハンドルでなければなりません。
  • space と spatialContainer の両方が、同じ XrSession から作成、割り当て、または取得されている必要があります。

XrSpatialContainerViewStateEXT 構造体は、空間コンテナごとのレンダリング適合性情報を含む xrLocateSpatialContainerViewsEXT の呼び出しによって入力されます。

typedef struct XrSpatialContainerViewStateEXT {
    XrStructureType            type;
    void*                      next;
    XrViewStateFlags           viewStateFlags;
    XrViewConfigurationType    viewConfigurationType;
    XrBool32                   shouldSubmitLayers;
    XrExtent2Di                recommendedImageExtent;
} XrSpatialContainerViewStateEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • viewStateFlags は XrViewStateFlags のビットマスクです。これらのフラグは、コア XrViewState 構造体の viewStateFlags と同じ目的で使用されます。
  • viewConfigurationType は XrViewConfigurationType で、ランタイムが空間コンテナに使用しているビュー構成タイプを示します。ランタイムは、リクエストされたビューよりも少ないビュー構成に低下する可能性があります。
  • shouldSubmitLayers は、ランタイムから返される XrBool32 です。XR_FALSE の場合、アプリは、この空間コンテナのコンポジションの送信を避けるべきです。現在表示されていないか、レンダリングが不要な状態であるためです。
  • recommendedImageExtent は、空間コンテナの推奨解像度を表す XrExtent2Di 構造体です。

コア OpenXR ビューの位置と同様に、アプリは XrSpatialContainerViewStateEXT :: viewStateFlags をチェックして、位置と向きが有効であり、レンダリングにビューデータを使用する前にトラッキングされていることを確認しなければなりません。

アプリは、ランタイムの推奨値を超えてレンダリングしないように、shouldSubmitLayers と viewConfigurationType を確認すべきです。shouldSubmitLayers が false の場合、アプリはレンダリング動作を次のように変更します。

  • アプリは、対応する XrView :: fov を読み取ってはなりません。
  • アプリは recommendedImageExtent を読み取ってはなりません。
  • アプリは、対応する空間コンテナのスワップチェーンへのレンダリングとコンポジション レイヤの送信を避けるべきです。
  • アプリは、XrSpatialContainerLayerEXT :: retainPreviousSubmission を true に設定すべきです。アプリがレイヤを送信することを選択した場合、レイヤをどのように処理するかはランタイムが決定します（たとえば、ランタイムはレイヤをドロップすることを選択できます）。

recommendedImageExtent は、コンテナの位置またはユーザーのビューに基づいて更新されるレイヤに明示的に使用されます。空間コンテナの位置またはユーザーのビューに依存するコンテンツ（通常の 3D コンテンツなど）でレイヤを更新する場合、アプリはデフォルトの推奨ビューサイズではなく、この小さいビューポートにレンダリングすべきです。空間コンテナの位置やユーザーの視点に依存しないコンテンツ（静的なクアッドレイヤなど）でレイヤを更新する場合、アプリはこれらの値を無視しても問題ありません。ビュー依存レイヤの場合、recommendedImageExtent は、エイリアシングを最小限に抑え、レンダリング パフォーマンスを向上させることを目的とした、ランタイムからアプリへの推奨事項です。アプリは、必要に応じてフル解像度で送信できます。

recommendedImageExtent の XrExtent2Di :: width と XrExtent2Di :: height は、常に、空間コンテナのプライマリ ビュー構成の XrViewConfigurationView の XrViewConfigurationView :: recommendedImageRectWidth と XrViewConfigurationView :: recommendedImageRectHeight 以下の正の整数でなければなりません。アプリは、recommendedImageExtent が変更されたという理由だけでスワップチェーンを再作成すべきではありません。これは、アプリが送信するフル解像度のコンポジション レイヤの XrSwapchainSubImage で使用する XrSwapchainSubImage :: imageRect を指定するアプリへの動的なヒントであり、フレームごとに変更できます。

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

  • XrSpatialContainerViewStateEXT を使用する前に、XR_EXT_spatial_container_self_rendering 拡張機能を有効にしなければなりません。
  • type は XR_TYPE_SPATIAL_CONTAINER_VIEW_STATE_EXT にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • viewStateFlags は、XrViewStateFlagBits 値の有効な組み合わせでなければなりません。
  • viewStateFlags は 0 にしないでください
  • viewConfigurationType は、有効な XrViewConfigurationType 値でなければなりません

参照スペースを表示

ビュー参照空間は、OpenXR コアにあるため変更されません。コアと同様に、レンダリングでの使用は想定されていません。

xrEndFrame を介したレイヤの送信

空間コンテナをレンダリングするには、アプリは、それぞれの空間コンテナに関連付けられたレイヤのリストを xrEndFrame に提供しなければなりません。これは、XrSpatialContainerLayerFrameEndInfoEXT 構造体を使用して行われます。

typedef struct XrSpatialContainerLayerFrameEndInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             containerLayerCount;
    const XrSpatialContainerLayerEXT*    containerLayers;
} XrSpatialContainerLayerFrameEndInfoEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • containerLayerCount は、containerLayers 配列内の要素の数です。
  • containerLayers は、XrSpatialContainerLayerEXT 構造体の配列へのポインタです。

containerLayers 配列には、アクティブなレンダリング セット内の各空間コンテナ（xrBeginSpatialContainerRenderingEXT と xrEndSpatialContainerRenderingEXT によってセッションごとに管理されるコンテナ）の XrSpatialContainerLayerEXT が含まれています。各 XrSpatialContainerLayerEXT には、指定された空間コンテナに関連付けられた XrCompositionLayerBaseHeader ポインタのリストが含まれています。ランタイムは、containerLayers の順序に関係なく、任意の順序でコンテナを合成しても構いません。たとえば、ランタイムは、ユーザーに対する奥行きに基づいてコンテナを合成したり、空間コンテナを背景レイヤとして機能させたり、奥行きに関係なく常に最前面に表示されるように空間コンテナを「固定」したりできます。ランタイムは、境界モードまたは没入モードの空間コンテナに異なる戦略を使用して、レイヤを合成しても構いません。たとえば、ランタイムは、各境界付き空間コンテナのコンポジション レイヤを、2 番目のコンポジション ステップですべての他のコンテナと結合される単一のステレオ クアッドレイヤに事前コンポジットしても構いません。

XrFrameEndInfo :: displayTime と XrFrameEndInfo :: environmentBlendMode は、XrSpatialContainerLayerFrameEndInfoEXT で提供されるすべての空間コンテナに適用されます。

この構造体が XrFrameEndInfo にチェーンされて xrEndFrame に渡されると、アクティブなレンダリング セットに基づいて、次のエラーケースが追加されます。

  • 空間コンテナが containerLayers の複数の要素によって参照されている場合、ランタイムは XR_ERROR_SPATIAL_CONTAINER_DUPLICATE_EXT を返さなければなりません。
  • アクティブなレンダリング セット内の空間コンテナが containerLayers の要素によって参照されていない場合、ランタイムは XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT を返さなければなりません。
  • containerLayers が参照する空間コンテナがアクティブなレンダリング セットのメンバーでない場合、ランタイムは XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT を返さなければなりません。

さらに、アクティブなレンダリング セットに空間コンテナがあり、この構造が XrFrameEndInfo にチェーンされていない場合、ランタイムは XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT を返さなければなりません。

上記のエラーケースのいずれにおいても、ランタイムは空間コンテナのコンテンツをレンダリングしなければなりません。

アクティブなレンダリング セットに空間コンテナがない場合、アプリはコンポジション レイヤを送信しない限り、xrEndFrame を呼び出すことができます。

個々のスワップチェーンは、有効な構造のレイヤを介して複数のコンテナに送信される場合があります。たとえば、単一のスワップチェーンを介してレンダリングされたクアッドレイヤが複数の空間コンテナに送信される場合があります。このケースは、他のレンダリングと同様に処理されます。ランタイムは、このようなすべての空間コンテナでクアッドをレンダリングしなければなりません。

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

  • XR_EXT_spatial_container_self_rendering 拡張機能は、XrSpatialContainerLayerFrameEndInfoEXT を使用する前に有効にする必要があります。
  • type は XR_TYPE_SPATIAL_CONTAINER_LAYER_FRAME_END_INFO_EXT にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • containerLayers は、containerLayerCount 個の有効な XrSpatialContainerLayerEXT 構造体の配列へのポインタでなければなりません
  • containerLayerCount パラメータは 0 より大きい値にする必要があります。

XrSpatialContainerLayerEXT 構造体は、標準のコンポジション レイヤをグループ化し、特定の空間コンテナに関連付けます。

typedef struct XrSpatialContainerLayerEXT {
    XrStructureType                               type;
    const void*                                   next;
    XrSpatialContainerEXT                         spatialContainer;
    XrBool32                                      retainPreviousSubmission;
    uint32_t                                      layerCount;
    const XrCompositionLayerBaseHeader* const*    layers;
} XrSpatialContainerLayerEXT;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • spatialContainer は、ターゲット コンテナを識別する XrSpatialContainerEXT です。
  • retainPreviousSubmission は XrBool32 です。XR_TRUE の場合、ランタイムはこの空間コンテナに最後に送信されたフレームを保持します。
  • layerCount は、layers 配列内の合成レイヤの数です。
  • layers は、XrCompositionLayerBaseHeader ポインタの配列へのポインタです。

retainPreviousSubmission が XR_TRUE の場合、ランタイムは、retainPreviousSubmission が XR_FALSE であった直近の xrEndFrame 呼び出し中にラッチされたコンポジション レイヤとスワップチェーン画像コンテンツを再利用しなければなりません。保持されたレイヤで使用されるスワップチェーンに対するその後の変更は、レンダリングされた出力に反映してはなりません。

個々の空間コンテナ（コンテナ内レンダリング）に送信されるレイヤの場合、ランタイムは、レイヤ合成の順序付けに関するすでに指定されているルールに従わなければなりません。つまり、コンテナ内のレイヤは、指定された順序で描画され、ペインター アルゴリズムによって合成される必要があります。

空間コンテナを「クリア」するとは、空間コンテナからすべてのコンテンツを削除することを指します。これにより、現在のフレームでそのコンテナに何もレンダリングされなくなります。ランタイムは、これを、アプリがコンテナ内のすべてのピクセルに対して透明な黒（すべてのビットが 0）を送信することと同等に扱わなければなりません。空間コンテナを「保持」するとは、そのコンテナに対して最後に送信されたレイヤセットをランタイムが継続して表示することを指します。

アプリは、空間コンテナごとに、新しいレイヤを送信するか、以前の送信を保持するか、空間コンテナをクリアするかを指定できます。

  • 新しいレイヤを送信するために、アプリはゼロ以外の layerCount と有効な layers ポインタを提供します。
  • 空間コンテナをクリアするには、そのエントリの layerCount を 0 に、retainPreviousSubmission を XR_FALSE に設定する必要があります。
  • 最後に送信されたレイヤとスワップチェーン イメージを保持（保持）するには、そのエントリの layerCount を 0 に、retainPreviousSubmission を XR_TRUE にする必要があります。

この明示的なコンテナごとの制御により、アプリの意図がすべてのフレームで明確に伝達されます。

retainPreviousSubmission が XR_TRUE で、layerCount が 0 でない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

XrSpatialContainerCompositionLayerViewConfigurationEXT が、空間コンテナの一部である XrCompositionLayerProjection にチェーンされていない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。この構造は、XrCompositionLayerProjection レイヤにのみ適用されます。他のレイヤタイプ（クワッドレイヤやシリンダーレイヤなど）にチェーンされている場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

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

投影レイヤのビュー構成の指定

XrSpatialContainerCompositionLayerViewConfigurationEXT 構造体は、空間コンテナの投影レイヤをレンダリングするために使用されるビュー構成を指定するために使用されます。

typedef struct XrSpatialContainerCompositionLayerViewConfigurationEXT {
    XrStructureType            type;
    const void*                next;
    XrViewConfigurationType    viewConfigurationType;
} XrSpatialContainerCompositionLayerViewConfigurationEXT;

メンバーの説明

空間コンテナに XrCompositionLayerProjection を送信する場合、アプリは、レイヤのレンダリングに使用されたビュー構成を指定しなければなりません。これは、アプリが各フレームで、空間コンテナのプライマリ ビュー構成と、ランタイムが提案する減衰ビュー構成（存在する場合）のどちらでレンダリングするかを選択できるためです。

XrSpatialContainerCompositionLayerViewConfigurationEXT がチェーンされている場合、アプリは、XrCompositionLayerProjection :: viewCount が、チェーンされた構造で指定された XrViewConfigurationType の有効なビュー数であることを確認しなければなりません。チェーン構造で指定された viewConfigurationType は、コンテナの開始時に指定された XrSpatialContainerBeginInfoEXT :: primaryViewConfigurationType、または XrSpatialContainerViewStateEXT でランタイムによって返された減衰ビュー構成タイプ、または拡張機能によって有効にされた追加の値である必要があります。

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

ピクセル クリッピングの動作

アプリは、コンポジション レイヤを送信するときに XrSpatialContainerLayerVolumeClippingEXT をチェーンすることで、空間コンテナの境界外にピクセルをレンダリングするかどうかをランタイムに通知すべきです。

typedef struct XrSpatialContainerLayerVolumeClippingEXT {
    XrStructureType                        type;
    const void*                            next;
    XrSpatialContainerVolumeClippingEXT    volumeClipping;
} XrSpatialContainerLayerVolumeClippingEXT;

メンバーの説明

この構造は、アプリが空間コンテナの境界外にピクセルをレンダリングするかどうかのヒントとして機能します。空間コンテナが没入モードの場合、境界は無限であるため、このヒントは意味を持ちません。

セルフ レンダリングを使用する境界付き空間コンテナの場合、ランタイムは 3D ボリューム境界と 2D ピクセル境界の両方を推論する必要があります。3D ボリューム境界は xrGetSpatialContainerBoundsEXT から返されます。2D ピクセル境界は、システムの各ディスプレイへの 3D ボリューム境界の投影です。

ランタイムは、2D ピクセル境界外のスワップチェーン画像からピクセルを破棄しなければなりません。ただし、2D ピクセル境界内かつ 3D ボリューム境界外のピクセルを破棄してはなりません。コンテンツがコンテナの 3D ボリューム境界を超えて、またはその前に広がっているように見えるステレオ効果が可能です。アプリは、奥行きの矛盾を軽減するために、境界付き空間コンテナの 3D ボリューム境界の外側にあるピクセルを破棄しても構いません。また、その方法に基づいて volumeClipping を設定すべきです。奥行きの矛盾は、多くの場合、眼精疲労やユーザーの不快感を引き起こします。

ランタイムは、volumeClipping を使用して、特定の空間コンテナの表示方法を調整しても構いません。たとえば、XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT に設定すると、ランタイムは 3D ボリューム境界の背面をレンダリングできます。これにより、空間コンテナがコンテナの 3D ボリューム境界の背後にピクセルを描画すると、深度パラドックスが発生します。

将来の拡張機能では、深度情報が送信された場合に、3D ボリューム境界に基づくクリッピングが可能になる可能性があります。

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

新しいコマンド

新しい構造

新しい列挙型定数

  • XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME
  • XR_EXT_spatial_container_self_rendering_SPEC_VERSION

  • XrResult の拡張:

    • XR_ERROR_SPATIAL_CONTAINER_DUPLICATE_EXT
    • XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT

  • XrSpatialContainerGraphicsPresentationEXT を拡張します。

    • XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

  • XrStructureType の拡張:

    • XR_TYPE_SPATIAL_CONTAINER_BEGIN_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_COMPOSITION_LAYER_VIEW_CONFIGURATION_EXT
    • XR_TYPE_SPATIAL_CONTAINER_END_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_LAYER_EXT
    • XR_TYPE_SPATIAL_CONTAINER_LAYER_FRAME_END_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_LAYER_VOLUME_CLIPPING_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VIEWS_LOCATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VIEW_LOCATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VIEW_STATE_EXT

コードサンプル

// Example: Complete lifecycle, view location, and frame submission for spatial containers
PFN_xrBeginSpatialContainerRenderingEXT xrBeginSpatialContainerRenderingEXT; // previously initialized
PFN_xrEndSpatialContainerRenderingEXT xrEndSpatialContainerRenderingEXT; // previously initialized
PFN_xrLocateSpatialContainerViewsEXT xrLocateSpatialContainerViewsEXT; // previously initialized

XrSession session; // previously initialized

// We want to update this container
XrSpatialContainerEXT containerA; // previously initialized with XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT
XrSpace containerASpace; // previously initialized

// We want to retain this container
XrSpatialContainerEXT containerB; // previously initialized with XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT
XrSpace containerBSpace; // previously initialized

// 1. Add to active render set when the app is ready to start submitting layers
XrSpatialContainerBeginInfoEXT beginInfoA {
  .type = XR_TYPE_SPATIAL_CONTAINER_BEGIN_INFO_EXT,
  .spatialContainer = containerA,
  .primaryViewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
};
CHK_XR(xrBeginSpatialContainerRenderingEXT(session, &beginInfoA));

XrSpatialContainerBeginInfoEXT beginInfoB {
  .type = XR_TYPE_SPATIAL_CONTAINER_BEGIN_INFO_EXT,
  .spatialContainer = containerB,
  .primaryViewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
};
CHK_XR(xrBeginSpatialContainerRenderingEXT(session, &beginInfoB));

// ... Frame Loop ...


XrTime displayTime; // returned from xrWaitFrame

const std::vector<XrSpatialContainerEXT> containers = {containerA, containerB};
const std::vector<XrSpace> containerSpaces = {containerASpace, containerBSpace};
uint32_t containerCount = static_cast<uint32_t>(containers.size());

// 2. Setup individual locate info for each container
std::vector<XrSpatialContainerViewLocateInfoEXT> containerLocateInfos(containerCount, {
  .type = XR_TYPE_SPATIAL_CONTAINER_VIEW_LOCATE_INFO_EXT,
});

for (uint32_t i = 0; i < containerCount; ++i) {
    containerLocateInfos[i].viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO;
    containerLocateInfos[i].space = containerSpaces[i]; // Recommended to use container's own space
    containerLocateInfos[i].spatialContainer = containers[i];
}

// Setup bulk locate info
XrSpatialContainerViewsLocateInfoEXT locateInfo {
  .type = XR_TYPE_SPATIAL_CONTAINER_VIEWS_LOCATE_INFO_EXT,
  .displayTime = displayTime,
  .viewLocateInfoCount = containerCount,
  .viewLocateInfos = containerLocateInfos.data(),
};

// Prepare states to be populated by the runtime
std::vector<XrSpatialContainerViewStateEXT> viewStates(containerCount, {
  .type = XR_TYPE_SPATIAL_CONTAINER_VIEW_STATE_EXT,
});

// Call the dedicated locate views function
// We know the required view count is 2 per container for STEREO
const uint32_t viewsPerConfig = 2;
uint32_t totalViewCount = containerCount * viewsPerConfig;
std::vector<XrView> views(totalViewCount, {.type = XR_TYPE_VIEW});

CHK_XR(xrLocateSpatialContainerViewsEXT(session, &locateInfo, containerCount, viewStates.data(), totalViewCount, views.data()));

// Process results
for (uint32_t i = 0; i < containerCount; ++i) {
    XrBool32 shouldSubmitLayers = viewStates[i].shouldSubmitLayers;
    XrExtent2Di recommendedImageExtent = viewStates[i].recommendedImageExtent;
    XrViewConfigurationType viewConfigurationType = viewStates[i].viewConfigurationType;
    bool isDecayedToMono = (viewConfigurationType == XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO);
    if (shouldSubmitLayers) {
        // App is expected to also verify viewStates[i].viewStateFlags has valid orientation/position bits before rendering
        XrView& leftView = views[i * viewsPerConfig];
        XrView& rightView = views[i * viewsPerConfig + 1];
        // If isDecayedToMono is true, left and right will be identical.
    } else {
        // Skip layer submission but retain previous submission when calling
        // xrEndFrame.
    }
}

// 3. Setup projection layer for container A
XrCompositionLayerProjection projectionLayer = {.type = XR_TYPE_COMPOSITION_LAYER_PROJECTION};
// ... standard projection layer setup (space, viewCount, views, etc.) ...

// Specify which view configuration was used to render this specific layer
XrSpatialContainerCompositionLayerViewConfigurationEXT containerViewConfig {
  .type = XR_TYPE_SPATIAL_CONTAINER_COMPOSITION_LAYER_VIEW_CONFIGURATION_EXT,
  // Even if the runtime decayed to MONO, we indicate what we actually rendered
  .viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
};

// Chain it to the projection layer
projectionLayer.next = &containerViewConfig;
const XrCompositionLayerBaseHeader* layersA[1] = {reinterpret_cast<const XrCompositionLayerBaseHeader*>(&projectionLayer)};

// Note: In a real app, you are required to submit ALL active containers in the render set.

XrSpatialContainerLayerVolumeClippingEXT containerClippingA = {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_VOLUME_CLIPPING_EXT,
  // Set volumeClipping appropriately for the rendering done.
  .volumeClipping = XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT,
};

// Setup container A (Update with new pixels)
XrSpatialContainerLayerEXT containerLayerA {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_EXT,
  .next = &containerClippingA,
  .spatialContainer = containerA,
  .retainPreviousSubmission = XR_FALSE,
  .layerCount = 1,
  .layers = layersA,
};

XrSpatialContainerLayerVolumeClippingEXT containerClippingB {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_VOLUME_CLIPPING_EXT,
  // Set volumeClipping appropriately for the rendering done.
  .volumeClipping = XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT,
};

// Setup container B (Explicitly retain previous frame)
XrSpatialContainerLayerEXT containerLayerB {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_EXT,
  .next = &containerClippingB,
  .spatialContainer = containerB,
  .retainPreviousSubmission = XR_TRUE,
  .layerCount = 0, // Required to be 0 when retaining
  .layers = nullptr,
};

// Aggregate all container layers
XrSpatialContainerLayerEXT containerLayers[] = { containerLayerA, containerLayerB };

XrSpatialContainerLayerFrameEndInfoEXT spatialEndInfo {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_FRAME_END_INFO_EXT,
  .containerLayerCount = 2, // Must equal the number of active containers
  .containerLayers = containerLayers,
};

XrFrameEndInfo frameEndInfo {
  .type = XR_TYPE_FRAME_END_INFO,
  .next = &spatialEndInfo,
  .displayTime = displayTime,
  .environmentBlendMode = XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND,
  .layerCount = 0, // MANDATORY: Must be 0 for self rendering extension
};

CHK_XR(xrEndFrame(session, &frameEndInfo));

// ... End Frame Loop ...

// 4. Remove from active render set when the container is destroyed or no longer needs rendering
XrSpatialContainerEndInfoEXT endInfoA {
  .type = XR_TYPE_SPATIAL_CONTAINER_END_INFO_EXT,
  .spatialContainer = containerA,
};
CHK_XR(xrEndSpatialContainerRenderingEXT(session, &endInfoA));

XrSpatialContainerEndInfoEXT endInfoB {
  .type = XR_TYPE_SPATIAL_CONTAINER_END_INFO_EXT,
  .spatialContainer = containerB,
};
CHK_XR(xrEndSpatialContainerRenderingEXT(session, &endInfoB));

変更履歴

  • リビジョン 1、2026-08-06（Lachlan Ford）

    • 拡張機能の初期説明