تصویر_قابل_پیگیری_XR_ANDROID

رشته نام

XR_ANDROID_trackables_image

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۷۱۰

بازنگری

۱

وضعیت تصویب

تصویب نشده

وابستگی‌های افزونه و نسخه

XR_EXT_future
و
XR_ANDROID_trackables

آخرین تاریخ اصلاح

۲۰۲۵-۰۴-۰۸

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

کریستوفر دوئر، گوگل
لوانا چن، گوگل
جارد فایندر، گوگل
اسپنسر کوئین، گوگل
نیهاو جین، گوگل
دیه‌گو تیپالدی، گوگل
دنیل گوتنبرگ، کوالکام
مارک واداسی، کوالکام
مارکوس بیرکنر، کوالکام
ماکسیمیلیان مایر، کوالکام

نمای کلی

این افزونه ردیابی تصاویر مسطح را مطابق با مجموعه تصاویر مرجع ورودی مشخص شده، امکان‌پذیر می‌کند.

مجوزها

برنامه‌های اندروید باید مجوز android.permission.SCENE_UNDERSTANDING_COARSE را در مانیفست خود داشته باشند، زیرا این افزونه به XR_ANDROID_trackables وابسته است و هندسه محیط را در معرض نمایش قرار می‌دهد. مجوز android.permission.SCENE_UNDERSTANDING_COARSE یک مجوز خطرناک محسوب می‌شود.

(سطح حفاظت: خطرناک)

بررسی قابلیت سیستم

ساختار XrSystemImageTrackingPropertiesANDROID به صورت زیر تعریف شده است:

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند. برای جزئیات بیشتر در مورد زنجیره ساختار، به ساختار در حال توسعه ( XrSystemProperties ) مراجعه کنید.
  • supportsImageTracking یک XrBool32 است که نشان می‌دهد آیا سیستم فعلی قابلیت ردیابی تصویر را دارد یا خیر.
  • supportsPhysicalSizeEstimation یک XrBool32 است که نشان می‌دهد آیا سیستم فعلی تخمین اندازه تصویر را ارائه می‌دهد یا خیر.
  • maxTrackedImageCount حداکثر تعداد تصاویری است که می‌توان همزمان ردیابی کرد.
  • maxLoadedImageCount حداکثر تعداد کل تصاویر مرجع است که می‌توانند در تمام پایگاه‌های داده بارگذاری شوند.

یک برنامه می‌تواند با بسط دادن XrSystemProperties با ساختار XrSystemImageTrackingPropertiesANDROID هنگام فراخوانی xrGetSystemProperties ، بررسی کند که آیا سیستم قادر به ردیابی تصویر است یا خیر. زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED برای ایجاد ردیاب تصویر برگرداند، اگر و فقط اگر supportsImageTracking XR_FALSE باشد.

اگر یک زمان اجرا از ردیابی تصویر پشتیبانی کند، باید در هر زمان معین از تصاویر ردیابی شده maxTrackedImageCount نیز پشتیبانی کند.

اگر یک زمان اجرا از ردیابی تصویر پشتیبانی کند، باید از تعداد تصاویر بارگذاری شده maxLoadedImageCount در هر زمان معین نیز پشتیبانی کند.

اگر یک زمان اجرا از تخمین اندازه تصویر پشتیبانی کند، برنامه می‌تواند XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 تنظیم کند تا استفاده از تخمین اندازه را نشان دهد. در غیر این صورت، برنامه باید XrTrackableImageDatabaseEntryANDROID :: physicalWidth روی یک مقدار مثبت تنظیم کند یا XR_ERROR_VALIDATION_FAILURE بازگردانده خواهد شد.

کاربرد معتبر (ضمنی)

ایجاد پایگاه‌های داده

برنامه می‌تواند با ایجاد یک یا چند ساختار XrTrackableImageDatabaseEntryANDROID و ارسال آنها به تابع xrCreateTrackableImageDatabaseAsyncANDROID از طریق ساختار XrTrackableImageDatabaseCreateInfoANDROID ، یک هندل XrTrackableImageDatabaseANDROID ایجاد کند.

برنامه هنگام ایجاد یک شناسه XrTrackableImageDatabaseANDROID باید حداقل یک XrTrackableImageDatabaseEntryANDROID ارائه دهد.

یک XrTrackableImageDatabaseANDROID یک هندل است که مجموعه‌ای از تصاویر مرجع پردازش‌شده را نشان می‌دهد که می‌توانند در محیط کشف و ردیابی شوند.

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

ساختار XrTrackableImageDatabaseEntryANDROID به صورت زیر تعریف شده است:

typedef struct XrTrackableImageDatabaseEntryANDROID {
    XrStructureType                        type;
    const void*                            next;
    XrTrackableImageTrackingModeANDROID    trackingMode;
    float                                  physicalWidth;
    uint32_t                               imageWidth;
    uint32_t                               imageHeight;
    XrTrackableImageFormatANDROID          format;
    uint32_t                               bufferSize;
    const uint8_t*                         buffer;
} XrTrackableImageDatabaseEntryANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • trackingMode یک XrTrackableImageTrackingModeANDROID است که حالت مورد نظر برای ردیابی را نشان می‌دهد.
  • physicalWidth عرض تصویر را بر حسب متر نشان می‌دهد. اگر صفر باشد، اندازه تصویر به صورت آنلاین تخمین زده می‌شود.
  • imageWidth عرض تصویر را بر حسب پیکسل نشان می‌دهد.
  • imageHeight ارتفاع تصویر را بر حسب پیکسل نشان می‌دهد.
  • format یک XrTrackableImageFormatANDROID است که فرمت داده‌های تصویر در buffer را نشان می‌دهد.
  • bufferSize طول بایت buffer را نشان می‌دهد.
  • buffer یک بافر uint8_t است که حاوی داده‌های پیکسل تصویر مرجع است. محتویات buffer باید در طول عملیات ایجاد پایگاه داده ناهمگام، که توسط xrCreateTrackableImageDatabaseAsyncANDROID آغاز شده و توسط xrCreateTrackableImageDatabaseCompleteANDROID تکمیل می‌شود، معتبر باشد.

اگر XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation برابر با XR_TRUE باشد، برنامه ممکن است physicalWidth روی 0 تنظیم کند تا تخمین اندازه آنلاین را درخواست کند.

اگر bufferSize با اندازه مورد انتظار بر اساس imageWidth ، imageHeight و format ورودی مطابقت نداشته باشد، ممکن است زمان اجرا XR_ERROR_VALIDATION_FAILURE از xrCreateTrackableImageDatabaseAsyncANDROID برگرداند.

کاربرد معتبر (ضمنی)

ساختار XrTrackableImageDatabaseCreateInfoANDROID به صورت زیر تعریف شده است:

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • entryCount یک uint32_t است که تعداد عناصر موجود در آرایه entries را مشخص می‌کند.
  • entries آرایه‌ای از ساختارهای XrTrackableImageDatabaseEntryANDROID است.

کاربرد معتبر (ضمنی)

ساختار XrCreateTrackableImageDatabaseCompletionANDROID به صورت زیر تعریف شده است:

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • futureResult نتیجه‌ی XrResult عملیات ناهمزمان است.
  • database هندل XrTrackableImageDatabaseANDROID ایجاد شده است.

کدهای بازگشت آینده

مقادیر futureResult :

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

کاربرد معتبر (ضمنی)

تابع xrCreateTrackableImageDatabaseAsyncANDROID به صورت زیر تعریف شده است:

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

توضیحات پارامتر

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

تابع xrCreateTrackableImageDatabaseCompleteANDROID به صورت زیر تعریف شده است:

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

توضیحات پارامتر

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • 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_VALIDATION_FAILURE

تابع xrDestroyTrackableImageDatabaseANDROID به صورت زیر تعریف شده است:

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

توضیحات پارامتر

کاربرد معتبر (ضمنی)

ایمنی نخ

  • دسترسی به database و هر گونه شناسه فرزند باید به صورت خارجی هماهنگ شود.

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

ردیابی تصاویر

این افزونه XR_TRACKABLE_TYPE_IMAGE_ANDROID را به XrTrackableTypeANDROID اضافه می‌کند.

برنامه می‌تواند با فراخوانی xrCreateTrackableTrackerANDROID و تعیین XR_TRACKABLE_TYPE_IMAGE_ANDROID به عنوان نوع قابل ردیابی در XrTrackableTrackerCreateInfoANDROID :: trackableType برای ردیابی تصاویر، یک XrTrackableTrackerANDROID ایجاد کند.

اگر XrTrackableTrackerCreateInfoANDROID :: trackableType با XR_TRACKABLE_TYPE_IMAGE_ANDROID باشد و XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking از طریق xrGetSystemProperties XR_FALSE را برگرداند، زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED برگرداند.

ساختار XrTrackableImageConfigurationANDROID به صورت زیر تعریف شده است:

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • databaseCount یک uint32_t است که تعداد عناصر موجود در databases را مشخص می‌کند.
  • databases آرایه‌ای از XrTrackableImageDatabaseANDROID است که پایگاه‌های داده‌ای را که ردیاب با آنها ایجاد می‌شود، مشخص می‌کند.

برنامه باید با اضافه کردن XrTrackableImageConfigurationANDROID به زنجیره next XrTrackableTrackerCreateInfoANDROID ، یک پیکربندی معتبر تنظیم کند. در غیر این صورت، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

برنامه باید حداقل یک ساختار XrTrackableImageDatabaseANDROID برای ایجاد ردیاب ارائه دهد.

کاربرد معتبر (ضمنی)

متغیر شمارشی XrTrackableImageTrackingModeANDROID حالت‌های ردیابی پشتیبانی‌شده برای تصاویر را توصیف می‌کند.

typedef enum XrTrackableImageTrackingModeANDROID {
    XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;

توضیحات شمارشگر

  • XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID — این حالت بالاترین دقت را دارد و امکان ردیابی تصاویر متحرک با تأخیر کم را فراهم می‌کند. همچنین بالاترین میزان مصرف برق را نیز دارد.
  • XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID — این حالت باید برای تصاویری استفاده شود که به عنوان ایستا یا نیمه‌ایستا شناخته می‌شوند. این حالت در مقایسه با حالت پویا منجر به مصرف انرژی کمتری می‌شود. اگر یک تصویر ایستا در حال جابجایی باشد، با تأخیر بسیار بیشتری نسبت به حالت پویا به‌روزرسانی می‌شود.

متغیر شمارشی XrTrackableImageFormatANDROID فرمت‌های پشتیبانی‌شده‌ی تصاویر را توصیف می‌کند.

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

توضیحات شمارشگر

  • XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID — فرمت تصویر RGBA با ۸ بیت در هر کانال رنگ و داده‌های شفافیت.

تابع xrAddTrackableImageDatabaseANDROID به صورت زیر تعریف شده است:

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

توضیحات پارامتر

وقتی یک XrTrackableImageDatabaseANDROID به یک ردیاب اضافه می‌شود، تصاویر مرجع آن پایگاه داده باید علاوه بر هر پایگاه داده دیگری که قبلاً با xrAddTrackableImageDatabaseANDROID یا از طریق ساختار XrTrackableImageConfigurationANDROID هنگام ایجاد اولیه ردیاب اضافه شده‌اند، برای تشخیص و ردیابی در نظر گرفته شوند.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

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

تابع xrRemoveTrackableImageDatabaseANDROID به صورت زیر تعریف شده است:

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

توضیحات پارامتر

وقتی یک XrTrackableImageDatabaseANDROID از XrTrackableTrackerANDROID حذف می‌شود، ساختارهای XrTrackableImageDatabaseEntryANDROID آن پایگاه داده دیگر نباید برای تشخیص و ردیابی در نظر گرفته شوند. هرگونه ورودی فعال ردیابی شده در آن پایگاه داده دیگر نباید گزارش شود. دسته XrTrackableImageDatabaseANDROID حذف شده نباید به عنوان بخشی از این عملیات به طور ضمنی از بین برود.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

دریافت تصاویر

تابع xrGetTrackableImageANDROID به صورت زیر تعریف می‌شود:

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

توضیحات پارامتر

  • tracker همان XrTrackableTrackerANDROID است که باید از آن کوئری گرفته شود.
  • getInfo همان XrTrackableGetInfoANDROID است که اطلاعات مورد نیاز برای دریافت کد QR قابل ردیابی را در خود جای داده است.
  • trackable یک اشاره‌گر به ساختار XrTrackableImageANDROID است که تصویر trackable در آن بازگردانده می‌شود.

اگر نوع قابل ردیابی XrTrackableANDROID برابر با XR_TRACKABLE_TYPE_IMAGE_ANDROID نباشد، یا اگر نوع قابل ردیابی XrTrackableTrackerANDROID XR_TRACKABLE_TYPE_IMAGE_ANDROID نباشد، زمان اجرا باید XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID را برگرداند.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

ساختار XrTrackableImageANDROID به صورت زیر تعریف می‌شود:

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • trackingState ، XrTrackingStateANDROID مربوط به تصویر است.
  • lastUpdatedTime XrTime آخرین به‌روزرسانی تصویر است.
  • database هندل XrTrackableImageDatabaseANDROID است که این تصویر از آن ردیابی شده است.
  • databaseEntryIndex اندیسی است که به آرایه XrTrackableImageDatabaseCreateInfoANDROID :: entries از database نگاشت می‌شود.
  • centerPose ، XrPosef تصویر واقع در XrTrackableGetInfoANDROID :: baseSpace است. تصویر در صفحه XZ قرار دارد که X به سمت راست تصویر و Z به پایین آن اشاره دارد.
  • extents ابعاد XrExtent2Df تصویر است. مرز کادر محصورکننده در نقاط زیر قرار دارد: centerPose +/- ( extents / 2).

کاربرد معتبر (ضمنی)

مدیریت شکست‌ها

برنامه باید با استفاده از xrPollEvent، رویداد XrEventDataImageTrackingLostANDROID را بررسی کند و نباید آن را نادیده بگیرد.

ساختار XrEventDataImageTrackingLostANDROID به صورت زیر تعریف می‌شود:

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • time XrTime

دریافت رویداد XrEventDataImageTrackingLostANDROID نشان می‌دهد که ردیابی تصویر دچار مشکل شده و خرابی داخلی باعث نامعتبر شدن منابع موجود شده است. برنامه در صورت تمایل به ادامه ردیابی تصویر، باید تمام دستگیره‌های XrTrackableImageDatabaseANDROID را از بین ببرد و دوباره آنها را ایجاد کند. همچنین برنامه در صورت تمایل به ادامه ردیابی تصویر، باید تمام دستگیره‌های XrTrackableTrackerANDROID مربوط به ردیابی تصویر را از بین ببرد و دوباره آنها را ایجاد کند.

کاربرد معتبر (ضمنی)

کد نمونه برای دریافت تصاویر قابل ردیابی

کد مثال زیر نحوه دریافت تصاویر قابل ردیابی را نشان می‌دهد.

XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

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

// Inspect system capability
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
  {
    .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
    .next = nullptr,
    .trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
    .physicalWidth = 0.1f, // The width of the image in meters.
    .imageWidth = 640,
    .imageHeight = 480,
    .format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
    .bufferSize = imageBufferSize, // RGBA buffer size in bytes.
    .buffer = imageBuffer, // RGBA data.
  }
};

XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
  .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .entryCount = 1,
  .entries = imageDatabaseEntries
};

XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
  XrFuturePollInfoEXT pollInfo{
    .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
    .future = imageDatabaseFuture,
  };
  XrFuturePollResultEXT pollResult{
    .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
  };
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

  if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
    futureReady = true;
    keepLooping = false;
  } else {
    // Throttle the loop to not fully expend this CPU core.
    std::this_thread::yield();
  }
}

XrTrackableImageDatabaseANDROID imageDatabase;

if (futureReady) {
  XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
    .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
    .next = nullptr,
  };

  CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
  CHK_XR(imageDatabaseCompletion.futureResult);
  imageDatabase = imageDatabaseCompletion.database;
}

XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &imageDatabase
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.

// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

while (1) {
  uint32_t trackableCountOutput = 0;

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));

  std::vector<XrTrackableANDROID> allImageTrackables;
  allImageTrackables.resize(trackableCountOutput);

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));

  for (XrTrackableANDROID trackable : allImageTrackables) {
    XrTrackableGetInfoANDROID imageGetInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackable,
      .baseSpace = appSpace,
      .time = updateTime
    };

    XrTrackableImageANDROID trackableImage{
      .type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
    };
    CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));

    // Use XrTrackableImageANDROID data.
    (void)trackableImage.trackingState;
    (void)trackableImage.lastUpdatedTime;
    (void)trackableImage.centerPose;
    (void)trackableImage.extents;

    if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
      // Knowing which image the index of 0 maps to, use the specific image database
      // entry (e.g. rendering A for image A).
    }
    // indices 1+N comparisons for another specific image database entry.
  }

  // Throttle the loop to not fully expend this CPU core.
  std::this_thread::yield();
}

// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

کد نمونه برای مدیریت پایگاه‌های داده تصویر در زمان اجرا

کد مثال زیر نحوه تغییر مجموعه تصاویر ردیابی شده را نشان می‌دهد.

XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.

// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 2,
  .databases = imageDatabases
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.

CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.

CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.

CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.

// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &anotherImageDatabase
};

XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &anotherImageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));

// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.

کد نمونه برای واکنش به خطاهای ردیابی تصویر

کد مثال زیر نحوه مدیریت خطا را با نمونه‌برداری برای رویداد XrEventDataImageTrackingLostANDROID نشان می‌دهد.

XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.

// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
  .type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
      const XrEventDataImageTrackingLostANDROID& eventdata =
        *reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);

      // All existing databases and trackers need to be destroyed.
      CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
      CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

      // To resume image tracking, the database(s) and the tracker need to be re-created.

      XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
        .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
        .next = nullptr,
        .entryCount = 1,
        .entries = imageDatabaseEntries
      };

      XrFutureEXT imageDatabaseFuture;
      CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

      while (true) {
        XrFuturePollInfoEXT pollInfo{
          .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
          .future = imageDatabaseFuture,
        };
        XrFuturePollResultEXT pollResult{
          .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
        };
        CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

        if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
          break;
        } else {
          // Throttle the loop to not fully expend this CPU core.
          std::this_thread::yield();
        }
      }

      XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
        .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
        .next = nullptr,
      };

      CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
      CHK_XR(imageDatabaseCompletion.futureResult);
      imageDatabase = imageDatabaseCompletion.database;

      XrTrackableImageConfigurationANDROID imageConfig {
       .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
       .next = nullptr,
       .databaseCount = 1,
       .databases = &imageDatabase
      };

      XrTrackableTrackerCreateInfoANDROID createInfo {
        .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
        .next = &imageConfig,
        .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
      };

      XrTrackableTrackerANDROID imageTrackableTracker;
      CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

      break;
    }
  }
}

انواع شیء جدید

دستورات جدید

سازه‌های جدید

Enum های جدید

ثابت‌های شمارشی جدید

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • بسط XrObjectType :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
  • بسط XrResult :

    • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • گسترش XrStructureType :

    • XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
  • توسعه‌ی XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۵-۰۴-۰۸ (دنیل گوتنبرگ)

    • توضیحات اولیه افزونه