Android XR SDK 現已在開發人員預覽版中推出。敬請提供意見回饋！請前往支援頁面與我們聯絡。

本頁面由 Cloud Translation API 翻譯而成。

XR_ANDROID_trackables OpenXR 擴充功能

名稱字串

XR_ANDROID_trackables_object

擴充功能類型

執行個體擴充功能

已註冊的擴充號碼

467

修訂版本

擴充功能和版本依附元件

XR_ANDROID_trackables

上次修改日期

2024-10-03

IP 狀態

著作人

Spencer Quin，Google

Nihav Jain，Google

Google 的 John Pursey

Jared Finder，Google

Levana Chen，Google

Google 的 Kenny Vercaemer

總覽

這項擴充功能可追蹤實體物件。例如鍵盤、滑鼠和環境中的其他物品。

追蹤物件

這個擴充功能會將 XR_TRACKABLE_TYPE_OBJECT_ANDROID 新增至 XrTrackableTypeANDROID。

應用程式可能會呼叫 xrCreateTrackableTrackerANDROID，並在 XrTrackableTrackerCreateInfoANDROID::trackableType 中將 XR_TRACKABLE_TYPE_OBJECT_ANDROID 指定為可追蹤類型，以便追蹤物件。

取得可追蹤物件

xrGetTrackableObjectANDROID 函式的定義如下：

XrResult xrGetTrackableObjectANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableObjectANDROID*                   objectOutput);

參數說明

tracker 是您要查詢的 XrTrackableTrackerANDROID。
- getInfo 是 XrTrackableGetInfoANDROID，其中包含用於取得可追蹤物件的資訊。
- objectOutput 是指向 XrTrackableObjectANDROID 結構的指標，其中會傳回可追蹤物件。

如果 XrTrackableANDROID 的可追蹤類型不是 XR_TRACKABLE_TYPE_OBJECT_ANDROID，或是 XrTrackableTrackerANDROID 的可追蹤類型不是 XR_TRACKABLE_TYPE_OBJECT_ANDROID，系統會傳回 XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID。

有效用法 (隱含)

您必須先啟用 XR_ANDROID_trackables_object 擴充功能，才能呼叫 xrGetTrackableObjectANDROID
- tracker 必須是有效的 XrTrackableTrackerANDROID 控點
- getInfo 必須是指向有效 XrTrackableGetInfoANDROID 結構體的指標
- objectOutput 必須是 XrTrackableObjectANDROID 結構的指標

傳回代碼

成功

XR_SUCCESS
- XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
- XR_ERROR_VALIDATION_FAILURE
- XR_ERROR_RUNTIME_FAILURE
- XR_ERROR_HANDLE_INVALID
- XR_ERROR_INSTANCE_LOST
- XR_ERROR_SESSION_LOST
- XR_ERROR_SESSION_NOT_RUNNING
- XR_ERROR_TIME_INVALID

XrTrackableObjectANDROID 結構的定義如下：

typedef struct XrTrackableObjectANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrPosef                   centerPose;
    XrExtent3DfEXT            extents;
    XrObjectLabelANDROID      objectLabel;
    XrTime                    lastUpdatedTime;
} XrTrackableObjectANDROID;

成員說明

type 是這個結構的 XrStructureType。
- next 是 NULL 或結構鏈結中下一個結構的指標。核心 OpenXR 或這個擴充功能中並未定義這類結構。
- trackingState 是物件的 XrTrackingStateANDROID。
- centerPose 是 XrTrackableGetInfoANDROID::baseSpace 中物件的 XrPosef。
- extents 是物件的 XrExtent3DfEXT 維度。
- objectLabel 是這個物件在執行階段所判定的 XrObjectLabelANDROID。
- lastUpdatedTime 是物件上次更新的 XrTime。

有效用法 (隱含)

您必須啟用 XR_ANDROID_trackables_object 擴充功能，才能使用 XrTrackableObjectANDROID
- type 必須為 XR_TYPE_TRACKABLE_OBJECT_ANDROID
- next 必須為 NULL，或結構鏈結中指向下一個結構體的有效指標
- trackingState 必須是有效的 XrTrackingStateANDROID 值
- objectLabel 必須為有效的 XrObjectLabelANDROID 值

XrObjectLabelANDROID 列舉是 XrTrackableANDROID 物件的標籤。

typedef enum XrObjectLabelANDROID {
    XR_OBJECT_LABEL_UNKNOWN_ANDROID = 0,
    XR_OBJECT_LABEL_KEYBOARD_ANDROID = 1,
    XR_OBJECT_LABEL_MOUSE_ANDROID = 2,
    XR_OBJECT_LABEL_LAPTOP_ANDROID = 3,
    XR_OBJECT_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrObjectLabelANDROID;

取得可追蹤物件的程式碼範例

以下程式碼範例示範如何取得可追蹤的物件。

XrSession session; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized
PFN_xrGetTrackableObjectANDROID xrGetTrackableObjectANDROID; // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

XrTrackableTrackerCreateInfoANDROID
  createInfo{XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID};
createInfo.trackableType = XR_TRACKABLE_TYPE_OBJECT_ANDROID;
XrTrackableTracker objectTrackableTracker;
XrResult result = xrCreateTrackableTrackerANDROID(
  session,
  &createInfo,
  &objectrackableTracker);
if (result != XR_SUCCESS) { /* Handle failures. */ }

uint32_t trackableCountOutput = 0;
std::vector<XrTrackableANDROID> allObjectTrackables;

// Query the number of trackables available.
result = xrGetAllTrackablesANDROID(
  objectTrackableTracker,
  0,
  &trackableCountOutput,
  nullptr
);

if (result == XR_SUCCESS) {
  allObjectTrackables.resize(trackableCountOutput, XR_NULL_TRACKABLE_ANDROID);

  // Fetch the actual trackable handles in the appropriately resized array.
  result = xrGetAllTrackablesANDROID(
    objectTrackableTracker,
    trackableCountOutput,
    &trackableCountOutput,
    allObjectTrackables.data());

  if (result == XR_SUCCESS) {
    for (XrTrackableANDROID trackable : allObjectTrackables) {

      // Object trackable query information
      XrTrackableGetInfoANDROID objectGetInfo;
      objectGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;
      objectGetInfo.next = nullptr;
      objectGetInfo.trackable = trackable;
      objectGetInfo.space = appSpace;
      objectGetInfo.time = updateTime;

      // Get the object trackable. Note that the tracker only returns object types.
      XrTrackableObjectANDROID object = { XR_TYPE_TRACKABLE_OBJECT_ANDROID };
      result = xrGetTrackableObjectANDROID(
        objectTrackableTracker,
        &objectGetInfo,
        &object
      );

      if (result == XR_SUCCESS) {
        /** Do Stuff with the object */
      }
    }
  }
}

// Release trackable tracker.
result = xrDestroyTrackableTrackerANDROID(objectTrackableTracker);

新列舉常數

XrStructureType 列舉已擴充以下項目：

XR_TYPE_TRACKABLE_OBJECT_ANDROID
XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

XrTrackableTypeANDROID 列舉已擴充以下項目：

XR_TRACKABLE_TYPE_OBJECT_ANDROID

新列舉項目

XrObjectLabelANDROID

新結構體

XrTrackableObjectANDROID

新函式

xrGetTrackableObjectANDROID

問題

版本記錄

修訂版本 1，2024 年 10 月 3 日 (Kenny Vercaemer)
- 初始擴充功能說明。