إضافة XR_ANDROID_trackables OpenXR

سلسلة الاسم

XR_ANDROID_trackables_object

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

467

المراجعة

1

التبعيات المتعلّقة بالإصدارات والإضافات

XR_ANDROID_trackables

تاريخ آخر تعديل

2024-10-03

حالة عنوان IP

ما مِن مطالبات معروفة بعناوين IP.

المساهمون

سبنسر كوين، Google

نيهاف جاين، Google

جون بورسي، Google

جاريد فايندر، Google

ليفانا تشين، Google

"كيني فيركامر"، Google

نظرة عامة

تتيح هذه الإضافة تتبُّع الأجسام المادية. على سبيل المثال، لوحات المفاتيح والفئران والأشياء الأخرى في البيئة.

تتبُّع الأجسام

تضيف هذه الإضافة XR_TRACKABLE_TYPE_OBJECT_ANDROID إلى XrTrackableTypeANDROID.

يمكن للتطبيق إنشاء XrTrackableTrackerANDROID من خلال استدعاء xrCreateTrackableTrackerANDROID وتحديد XR_TRACKABLE_TYPE_OBJECT_ANDROID كنوع قابل للتتبُّع في XrTrackableTrackerCreateInfoANDROID::trackableType لتتبُّع الأجسام.

الحصول على عنصر قابل للتتبّع

يتم تعريف الدالة xrGetTrackableObjectANDROID على النحو التالي:

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

أوصاف المَعلمات

  • tracker هو XrTrackableTrackerANDROID المطلوب إجراء طلب بحث عنه.
    • getInfo هو XrTrackableGetInfoANDROID مع المعلومات المستخدَمة ل الحصول على العنصر القابل للتتبّع.
    • objectOutput هو مؤشر إلى بنية XrTrackableObjectANDROID التي يتم فيها عرض الكائن القابل للتتبُّع.

سيتم عرض 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

يتم تعريف بنية 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 آخر تعديل على العنصر.

الاستخدام الصالح (ضمني)

قائمة القيم المحدَّدة 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

عمليات التعداد الجديدة

التصاميم الجديدة

الدوالّ الجديدة

المشاكل

سجلّ الإصدارات

  • المراجعة 1، ‎03-10-2024 (كيني فيركمير)
    • الوصف الأولي للإضافة