إضافة OpenXR‏ XR_ANDROID_trackables_object

سلسلة الاسم

XR_ANDROID_trackables_object

نوع الإضافة

إضافة مثيل

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

467

المراجعة

1

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

XR_ANDROID_trackables

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

2024-11-01

حالة عنوان IP

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

المساهمون

دييغو تيبالدي، Google

ديفيد جوزيف تان، Google

كريستوفر دوير، Google

سبنسر كوين، Google

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

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

"كيني فيركامر"، 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);

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

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

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

مثال على رمز للحصول على عناصر قابلة للتتبّع

يوضّح المثال التالي للرمز البرمجي كيفية الحصول على عناصر قابلة للتتبّع.

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);

ثوابت قائمة التعداد الجديدة

تمّت إضافة ما يلي إلى التعداد XrStructureType:

  • XR_TYPE_TRACKABLE_OBJECT_ANDROID
  • XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

تمّت إضافة ما يلي إلى التعداد XrTrackableTypeANDROID:

  • XR_TRACKABLE_TYPE_OBJECT_ANDROID

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

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

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

المشاكل

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

  • النسخة 1،‏ 03-10-2024 (كيني فيركمير)
    • الوصف الأوّلي للإضافة

‫OpenXR™ وشعار OpenXR هما علامتان تجاريتان مملوكتان لشركة The Khronos Group Inc. ومسجَّلتان كعلامتَين تجاريتَين في الصين والاتحاد الأوروبي واليابان والمملكة المتحدة.