XR_EXT_spatial_container

Name String

XR_EXT_spatial_container

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

811

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2026-08-06

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 中，應用程式可完全控制使用者看到的所有內容，以及這些內容與使用者真實或虛擬環境的融合方式。執行階段只會稍微修改顯示內容，確保使用者安全。這種應用程式模型適合讓使用者沉浸在單一體驗中，但不適用於同時進行多項體驗。尤其是在 AR 和混合實境環境中，使用者通常會想同時體驗多個不同的應用程式。

空間容器就像是延伸至 3D 的視窗。使用者可以同時看到多個空間容器，並對其中一部分提供輸入內容。可見的空間容器可以屬於不同的應用程式，而執行階段會代表使用者管理其大小和位置。

除了現有的沉浸式 OpenXR 體驗外，這項擴充功能也支援這些新的空間受限體驗。受限 OpenXR 體驗可包含少量 3D 內容 (深度偏移較小的平面面板)，或包含完整 3D 內容的體積。沉浸式 OpenXR 體驗是現有的全螢幕沉浸式應用程式，自 OpenXR 1.0 起就支援。應用程式可視需要切換這兩種內容。

這個擴充功能未定義任何方法，讓應用程式轉譯其內容。內容繪製方式定義於其他擴充功能：XR_EXT_spatial_container_self_rendering。

使用空間容器

XrSpatialContainerEXT 是代表空間容器的控制代碼。

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

應用程式會透過空間容器開始算繪，步驟如下：

  1. 使用 xrCreateSpatialContainerEXT 建立空間容器。
  2. 修改容器的任何狀態，以便進行初始呈現，例如容器的邊界模式。
  3. 使用 xrRequestSpatialContainerVisibleEXT 要求執行階段顯示容器。
  4. 等待執行階段準備就緒，即可顯示容器。執行階段準備就緒後，會將 XrEventDataSpatialContainerVisibleChangedEXT 事件排入佇列，並將 visible 設為 XR_TRUE。
  5. 開始轉譯空間容器。

如要拆除空間容器，請按照下列步驟操作：

  1. 使用 xrRequestSpatialContainerVisibleEXT 要求執行階段隱藏容器。
  2. 等待執行階段完成隱藏容器。執行階段完全隱藏容器後，會將 XrEventDataSpatialContainerVisibleChangedEXT 事件排入佇列，並將 visible 設為 XR_FALSE。
  3. 結束空間容器的算繪作業。
  4. 使用 xrDestroySpatialContainerEXT 刪除容器。

注意事項

這項擴充功能會將瀏覽權限和焦點管理委派給個別空間容器。由於工作階段整體不再代表單一可見或聚焦的物件，因此工作階段不會透過標準 OpenXR 狀態機器 (READY、SYNCHRONIZED、VISIBLE、FOCUSED) 轉換。相反地，工作階段在有效生命週期內會維持在 XR_SESSION_STATE_IDLE 狀態，而「工作階段狀態變更」中的規則會指定核心 OpenXR 作業如何對應至這個模式。

建立空間容器

xrCreateSpatialContainerEXT 函式會建立新的空間容器。

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

參數說明

新建立的 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);

參數說明

任何指定空間容器的「空間容器空間」都是座標系統，原點位於該空間容器邊界的中心。這個空間通常會做為 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 擴充功能新增)

空間容器狀態

執行階段會根據應用程式要求和使用者需求，管理空間容器狀態。因此，空間容器狀態的每個面向都會記錄下列事項：

  • 允許執行階段變更空間容器狀態。對於大多數空間容器狀態，執行階段可能隨時變更狀態。
  • 應用程式如何要求變更狀態。執行階段可能會延遲任何要求，直到認為要求合適為止。要求延遲時，執行階段不會將事件排入佇列，因此應用程式不應等待這類事件，以免影響不相關的邏輯。
  • 空間容器狀態變更時，事件執行階段會排入哪些佇列。執行階段會將所有變更的事件排入佇列，包括應用程式要求的變更和執行階段啟動的變更。執行階段不得將未指出變更的狀態變更事件排入佇列，例如應用程式在短時間內連續兩次要求隱藏容器。
  • 拒絕應用程式變更要求時，事件執行階段會排入哪些佇列。執行階段可能會基於任何原因拒絕要求，通常是基於維護優質使用者體驗的系統政策。

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

有效用途 (隱含)

瀏覽權限

應用程式會使用 xrRequestSpatialContainerVisibleEXT 要求顯示或隱藏空間容器。

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

參數說明

顯示或隱藏空間容器是非同步作業。

應用程式應先要求隱藏空間容器，再將其刪除，讓執行階段顯示流暢的轉場效果。執行階段應遵循隱藏空間容器的要求。

執行階段「可以」拒絕顯示空間容器的要求，此時執行階段「必須」將 XrEventDataSpatialContainerVisibleRequestDeniedEXT 事件排入佇列。舉例來說，如果使用者透過系統提供的「最小化」按鈕隱藏空間容器，部分執行階段會拒絕顯示該容器的要求。

在應用程式至少要求顯示空間容器一次之前，執行階段不得顯示空間容器。應用程式首次要求顯示空間容器後，執行階段可能會變更該空間容器的瀏覽權限，不受應用程式要求影響。這樣一來，應用程式就能控制空間容器的初始狀態和內容，執行階段也能提供工作列等系統 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，讓每個容器的值不同。所有變更 (包括執行階段啟動的變更) 都會排入事件佇列。

執行階段可能隨時啟用或停用與空間容器的互動。如果執行階段一次最多只支援一個可互動的空間容器，當執行階段變更可互動的空間容器時，必須先將停止互動的空間容器事件 ( 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);

參數說明

變更空間容器的邊界模式是非同步作業，執行階段「可能」會在應用程式要求變更後，將變更或拒絕事件排入佇列。這樣一來，執行階段就能彈出必要的使用者介面，讓使用者安全進入沉浸模式。

執行階段必須接受要求，變更不可見空間容器的邊界模式。如果執行階段會拒絕不可見容器的邊界模式要求，則可能會拒絕或延遲顯示這類空間容器的要求。這樣一來，應用程式就能以沉浸式容器的形式啟動容器。執行階段可以拒絕變更可見空間容器邊界模式的要求，此時執行階段必須將 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。

系統會將所有變更 (包括應用程式要求的變更和執行階段啟動的變更) 排入佇列。

當使用者以互動方式調整空間容器的大小時，執行階段必須採取下列其中一種行為：

  • 使用者調整空間容器大小時，系統會排入許多事件 (可能以影格速率)
  • 在調整大小結束時將單一事件排入佇列

如果執行階段在調整大小結束時只排入單一事件，則該執行階段必須繼續從 xrGetSpatialContainerBoundsEXT 回報舊邊界，直到執行階段排入調整大小事件為止。執行階段必須合併多個未輪詢的邊界變更事件。換句話說，如果邊界或邊界模式變更時，XrEventDataSpatialContainerBoundsChangedEXT 事件仍在佇列中，執行階段必須只回報一個事件，其中包含上次發生的邊界變更。由於應用程式也可以直接使用 xrGetSpatialContainerBoundsEXT 輪詢空間容器的邊界，因此事件的邊界變更次數可能與輪詢的變更次數不同，具體取決於執行階段產生的邊界變更時間、應用程式對 xrPollEvent 的呼叫，以及應用程式對 xrGetSpatialContainerBoundsEXT 的呼叫。

當空間容器的邊界變更時，空間容器的本機原點可能也會變更。舉例來說，如果執行階段允許使用者拖曳容器邊緣，調整空間容器邊界的大小，則使用者拖曳單一邊緣時，該容器的邊界和本機原點會隨之變更。在這種情況下，執行階段必須同時變更邊界和本機原點。

執行階段必須將 infiniteBounds 設為 XR_TRUE，並將寬度、高度和深度設為 0.0，代表無限邊界。執行階段必須將 infiniteBounds 設為 XR_FALSE，並將寬度、高度和深度設為有限正數，以設定有限邊界。

執行階段必須設定 bounds 和 infiniteBounds，並遵循與 XrSpatialContainerBoundsEXT 相同的規則。

有效用途 (隱含)

每當執行階段拒絕變更容器邊界模式的要求時，必須將 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。

支援這項擴充功能的執行階段應支援應用程式建立多個空間容器，僅受記憶體配置限制。執行階段可能會對同時顯示的空間容器數量設有不同限制。這個擴充功能無法查詢同時顯示的容器數量，因為執行階段「可能」會根據所有執行中應用程式的狀態，限制個別應用程式。假設限制較多的裝置和限制較少的裝置，在同時顯示的容器數量上會有不同的限制；限制較多的裝置可能一次只能顯示一個空間容器，而限制較少的裝置可能支援同時顯示大量空間容器，但受限於算繪運算限制。

支援這項擴充功能的執行階段必須支援至少一種空間容器，包括有界空間容器或沉浸式空間容器。

有效用途 (隱含)

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，則「可以」為空值。
  • 如要進一步瞭解如何擷取必要的 graphicsPresentations 大小，請參閱「緩衝區大小參數」一節。

執行階段必須一律從這個列舉傳回相同的緩衝區內容，用於指定的 systemId 和執行個體的生命週期。

有效用途 (隱含)

傳回代碼

成功

  • 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

閒置
(執行中)

閒置...

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 狀態，且至少有一個可互動的空間容器時，執行階段必須將工作階段視為焦點。
  • 不再需要 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 狀態也會關閉所有空間容器。執行階段必須先為每個使用中的空間容器排入 XrEventDataSpatialContainerClosedEXT 事件，才能為 XR_SESSION_STATE_LOSS_PENDING 排入工作階段狀態變更。
  • xrCreateSession 函式不再需要圖形 API 繫結結構。其他擴充功能可能需要圖形繫結，例如空間容器使用圖形 API 算繪。

上述行為與 XR_MND_headless 中的行為略有不同。如果工作階段已啟用空間容器支援，執行階段不得啟用 XR_MND_headless 的無頭工作階段行為。

注意事項

啟用空間容器後，工作階段只會在 XR_SESSION_STATE_IDLE (執行中) 和 XR_SESSION_STATE_LOSS_PENDING (未執行) 兩種狀態之間轉換。因此，執行階段不再傳回 XR_ERROR_SESSION_RUNNING 或 XR_ERROR_SESSION_NOT_RUNNING。相反地，當工作階段未執行時，執行階段會根據 OpenXR 核心中的規則傳回 XR_ERROR_SESSION_LOST 或 XR_SESSION_LOSS_PENDING。此外，xrBeginSession 是唯一會傳回 XR_ERROR_SESSION_RUNNING 的函式，現在一律會傳回 XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT。

有效用途 (隱含)

Android 資訊清單項目

根據在執行任何應用程式程式碼前啟動的初始空間容器狀態，以 AOSP 為基礎的執行階段可能會有自訂行為。舉例來說，執行階段可能會變更為活動、啟動動畫或啟動畫面顯示分配的資源。下列屬性可用於此目的。這些標記會取代 <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> 標記，除非是為了與舊版 AOSP 執行階段相容，否則以空間容器為基礎的應用程式不應指定 <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> 標記。

<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

問題

  • 如何處理多項未完成的可見要求？應用程式應收到一次變更/拒絕，還是多次？如果呼叫跨越多個影格，答案可能不同。如果多個要求導致無作業 (例如要求顯示空間容器，然後不顯示一開始就不顯示的容器)，答案也可能不同。

    • 已解決。變更事件和拒絕事件有不同的選項。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)。

    • 已解決。在正中央。在大多數情況下，空間容器調整大小使用者體驗 (移動邊緣) 預期不會有任何位置不移動。Center 通常用於 OpenXR 的其他部分。我們並未與 2D 運算中的視窗對齊，因為 3D 模型檢視器通常不遵循這項慣例。

  • 執行階段預計何時建立空間容器底層的資源？有時會涉及與系統服務的 IPC。

    • 已解決。在 xrCreateSpatialContainerEXT 期間同步進行。雖然可能涉及 IPC，但一般來說，建立容器的成本應該很低。部分供應商在管理容器時會使用全域互斥鎖，但通常不會等待太久。互斥鎖爭用問題是供應商專屬錯誤，應由各供應商解決。

  • 我們是否需要信號，指出 XrSession 會建立空間容器，因此不支援舊版算繪路徑？

    • 已解決。是。我們從根本上改變了工作階段狀態機器。

版本記錄

  • 修訂版本 1，2026-08-06 (Jared Finder，Google)

    • 初始擴充功能說明