XR_ANDROID_spatial_anchor_space

Name String

XR_ANDROID_spatial_anchor_space

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

796

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

XR_EXT_spatial_anchor

上次修改日期

2025-09-15

IP 狀態

沒有已知的智慧財產權聲明。

著作人

YuSheng Chang, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

總覽

XR_EXT_spatial_anchor 擴充功能中定義的 xrCreateSpatialAnchorEXT 函式，可讓應用程式使用 XrSpatialEntityEXT 控制代碼建立空間錨點。相較之下，這項擴充功能會建立由 XrSpace 控制代碼表示的空間錨點。如果應用程式想執行下列操作，這項功能就非常實用：

  • 使用 xrLocateSpaces 取得錨點的位置。
  • 找出相對於錨點的其他空間。
  • 使用 XR_ANDROID_anchor_sharing_export 匯出錨點。
  • 應用程式已放置錨點，現在只關心錨點的位置 (用於附加虛擬內容)，不關心透過用於建立錨點的 XrSpatialContextEXT 發現的任何其他實體的任何其他元件，因此允許應用程式刪除空間情境。

使用這個擴充功能建立的錨點無法透過 XR_ANDROID_device_anchor_persistence 擴充功能保存，應用程式必須改用 XR_EXT_spatial_persistence_operations。如果 XrPersistedAnchorSpaceInfoANDROID :: anchor 是使用 xrCreateSpatialAnchorSpaceANDROID 或 xrCreateSpatialAnchorSpaceFromIdANDROID 建立，執行階段必須從 xrPersistAnchorANDROID 傳回 XR_ERROR_VALIDATION_FAILURE。

為空間錨點建立 XrSpace

建立空間錨點和空間

xrCreateSpatialAnchorSpaceANDROID 函式的定義如下：

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

參數說明

xrCreateSpatialAnchorSpaceANDROID 函式會建立錨點，輸出 XrSpatialEntityIdEXT 和 XrSpace 控制代碼。xrCreateSpatialAnchorSpaceANDROID 的驗證需求與 xrCreateSpatialAnchorEXT 相同。

如果傳遞至 xrCreateSpatialAnchorSpaceANDROID 的 XrSpatialContextEXT 未設定 XR_SPATIAL_CAPABILITY_ANCHOR_EXT，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

關於 xrCreateSpatialAnchorSpaceANDROID 建立的錨點可偵測性，適用 xrCreateSpatialAnchorEXT 規格的最後一段。

有效用途 (隱含)

  • 呼叫 xrCreateSpatialAnchorSpaceANDROID 之前，必須啟用 XR_ANDROID_spatial_anchor_space 擴充功能
  • session「必須」是有效的 XrSession 控制代碼
  • spatialContext「必須」是有效的 XrSpatialContextEXT 控制代碼
  • createInfo「必須」指向有效的 XrSpatialAnchorCreateInfoEXT 結構
  • anchorEntityId「必須」是指向 XrSpatialEntityIdEXT 值的指標
  • anchorSpace「必須」是指向 XrSpace 控制代碼的指標
  • spatialContext「必須」已建立、分配或從 session 擷取

傳回代碼

成功

  • 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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

從現有空間錨點建立 XrSpace

xrCreateSpatialAnchorSpaceFromIdANDROID 函式的定義如下：

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

參數說明

如果空間錨點實體已存在 (例如因持續性)，應用程式可以提供空間實體 ID，從這些空間錨點建立 XrSpace。

xrCreateSpatialAnchorSpaceFromIdANDROID 函式會在 XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId 欄位中提供 XrSpatialEntityIdEXT，建立 XrSpace 控制代碼。

如果傳遞至 xrCreateSpatialAnchorSpaceFromIdANDROID 的 XrSpatialContextEXT 未設定 XR_SPATIAL_CAPABILITY_ANCHOR_EXT，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。

有效用途 (隱含)

傳回代碼

成功

  • 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_ANCHOR_ENTITY_ID_INVALID_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialAnchorSpaceFromIdCreateInfoANDROID 結構定義如下：

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL，或指向結構鏈中下一個結構的指標。
  • anchorEntityId 是現有空間錨點的 XrSpatialEntityIdEXT，用於建立 XrSpace。

如果 XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId 不是 spatialContext 的有效 ID，執行階段必須傳回 XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT。

如果 XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId 不是錨點的有效實體 ID，執行階段必須傳回 XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID。

有效用途 (隱含)

錨定廣告生命週期

XrSpace 控制代碼的父項是 XrSession。這表示即使 xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext 或 xrCreateSpatialAnchorSpaceANDROID :: spatialContext 遭到刪除，代表錨點的 XrSpace 控制代碼仍會有效。建立 XrSpace 來代表空間實體錨點，可讓應用程式刪除以 XR_SPATIAL_CAPABILITY_ANCHOR_EXT 設定的 XrSpatialContextEXT，同時繼續使用 XrSpace 搭配 xrLocateSpaces 取得錨點的最新姿勢，也就是說，執行階段必須繼續追蹤錨點，直到代表錨點的所有 XrSpace 控制代碼都刪除為止。

範例程式碼

建立空間錨點做為 XrSpace

以下程式碼範例說明如何建立空間錨點，並以 XrSpace 形式傳回。

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

從錨定實體 ID 建立 XrSpace

以下程式碼範例示範如何從現有的錨點實體 ID 建立 XrSpace。

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

新指令

新結構

新列舉常數

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • 擴充 XrResult：

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • 擴充 XrStructureType：

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

問題

版本記錄

  • 修訂版本 1，2025 年 9 月 15 日 (YuSheng Chang、Kyle Chen)

    • 初始擴充功能說明。