תוסף OpenXR‏ XR_ANDROID_trackables_object

מחרוזת שם

XR_ANDROID_trackables_object

סוג התוסף

תוסף למכונה

מספר תוסף רשום

467

גרסה

1

תלות בתוספים ובגרסאות

XR_ANDROID_trackables

תאריך השינוי האחרון

2024-11-01

סטטוס כתובת ה-IP

לא ידוע על תלונות על הפרת זכויות יוצרים בנושא כתובת IP.

שותפים ביצירת התוכן

דייגו טיפאלדי (Diego Tipaldi), Google

דייוויד ג'וזף טאן, Google

Christopher Doer, ‏ Google

ספנסר קווין (Spencer Quin), Google

Jared Finder, ‏ Google

לונן צ'ן, Google

Kenny Vercaemer, ‏ Google

סקירה כללית

התוסף הזה מאפשר מעקב אחר אובייקטים פיזיים. לדוגמה, מקלדות, עכברים ואובייקטים אחרים בסביבה.

מעקב אחר אובייקטים

התוסף הזה מוסיף את XR_TRACKABLE_TYPE_OBJECT_ANDROID אל XrTrackableTypeANDROID.

האפליקציה עשויה ליצור XrTrackableTrackerANDROID על ידי קריאה ל-xrCreateTrackableTrackerANDROID וציון XR_TRACKABLE_TYPE_OBJECT_ANDROID כסוג שניתן למעקב ב-XrTrackableTrackerCreateInfoANDROID::trackableType כדי לעקוב אחרי אובייקטים.

המבנה XrTrackableObjectConfigurationANDROID מוגדר כך:

typedef struct XrTrackableObjectConfigurationANDROID {
    XrStructureType                type;
    void*                          next;
    uint32_t                       labelCount;
    const XrObjectLabelANDROID*    activeLabels;
} XrTrackableObjectConfigurationANDROID;

תיאורי חברים

  • type הוא XrStructureType של המבנה הזה.
  • next הוא NULL או הפניה למבנה הבא בשרשרת המבנים. אין מבנים כאלה מוגדרים ב-OpenXR או בתוסף הזה.
  • labelCount הוא המספר של activeLabels.
  • activeLabels הוא הפניה למערך של XRObjectLabelANDROID שמציין את האובייקטים הפעילים במעקב.

האפליקציה עשויה להגדיר הגדרה נוספת על ידי הוספת XrTrackableObjectConfigurationANDROID לרשת הבאה של XrTrackableTrackerCreateInfoANDROID. הפלט מ-xrGetAllTrackablesANDROID יסונן כך שיתאים ל-activeLabels.

אם לא תגדירו את XrTrackableObjectConfigurationANDROID באפליקציה, המערכת תעקוב אחרי כל האובייקטים שזוהו.

שימוש תקין (מרומז)

המאפיין המסווג 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;

אחזור אובייקט שניתן לעקוב אחריו

הפונקציה xrGetTrackableObjectANDROID מוגדרת כך:

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

תיאורי פרמטרים

הערך XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID יוחזר אם הסוג שניתן למעקב של XrTrackableANDROID הוא לא XR_TRACKABLE_TYPE_OBJECT_ANDROID, או אם הסוג שניתן למעקב של XrTrackableTrackerANDROID הוא לא XR_TRACKABLE_TYPE_OBJECT_ANDROID.

שימוש תקין (מרומז)

קודי החזרה

הצלחה

  • 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
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID

המבנה 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 הוא XrPosef של האובייקט שנמצא ב-XrTrackableGetInfoANDROID::baseSpace.
  • extents הוא המאפיין XrExtent3DfEXT של האובייקט.
  • objectLabel הוא הערך של XrObjectLabelANDROID שהוגדר לאובייקט הזה בסביבת זמן הריצה.
  • lastUpdatedTime הוא XrTime של העדכון האחרון של האובייקט.

שימוש תקין (מרומז)

  • חובה להפעיל את התוסף XR_ANDROID_trackables_object לפני שמשתמשים ב-XrTrackableObjectANDROID
  • הערך של type חייב להיות XR_TYPE_TRACKABLE_OBJECT_ANDROID
  • next חייב להיות NULL או מצביע חוקי למבנה הבא בשרשרת המבנים
  • הערך של trackingState חייב להיות ערך חוקי של XrTrackingStateANDROID
  • הערך של objectLabel חייב להיות ערך חוקי של 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;
XrTrackableTrackerANDROID objectTrackableTracker;
XrResult result = xrCreateTrackableTrackerANDROID(
  session,
  &createInfo,
  &objectTrackableTracker);
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.baseSpace = 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);

קבועים חדשים של Enum

המנייה XrStructureType מורחבת עם:

  • XR_TYPE_TRACKABLE_OBJECT_ANDROID
  • XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

המניין XrTrackableTypeANDROID מורחב עם:

  • XR_TRACKABLE_TYPE_OBJECT_ANDROID

משתני Enum חדשים

מבנים חדשים

פונקציות חדשות

בעיות

היסטוריית הגרסאות

  • גרסה 1, 3 באוקטובר 2024 (Kenny Vercaemer)
    • תיאור ראשוני של התוסף.

OpenXR™‎ והלוגו של OpenXR הם סימנים מסחריים בבעלות The Khronos Group Inc., והם רשומים כסימנים מסחריים בסין, באיחוד האירופי, ביפן ובבריטניה.