XR_ANDROID_trackables_image

رشته نام

XR_ANDROID_trackables_image

نوع افزونه

افزونه نمونه

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

710

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

XR_EXT_future
و
XR_ANDROID_trackables

تاریخ آخرین تغییر

2025-04-08

وضعیت IP

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

همیاران

Christopher Doer،‏ Google
Levana Chen،‏ Google
Jared Finder،‏ Google
Spencer Quin،‏ Google
Nihav Jain،‏ Google
Diego Tipaldi،‏ Google
Daniel Guttenberg،‏ Qualcomm
Mark Vadasi،‏ Qualcomm
Markus Birkner،‏ Qualcomm
Maximilian Mayer،‏ Qualcomm

نمای کلی

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

اجازه‌ها

برنامه‌های Android باید اجازه 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 ایجاد کند.

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

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 را روی ۰ تنظیم کند تا تخمین اندازه آنلاین را درخواست کند.

اگر 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 enum حالت‌های ردیابی پشتیبانی‌شده تصاویر را توصیف می‌کند.

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 است که اطلاعات استفاده‌شده برای دریافت رمزینه پاسخ‌سریع قابل‌ردیابی را دارد.
  • ‫trackable اشاره‌گری به ساختار XrTrackableImageANDROID است که تصویر قابل‌ردیابی در آن برگردانده می‌شود.

اگر نوع قابل‌ردیابی 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) است.

استفاده معتبر (ضمنی)

رسیدگی به موارد ناموفق

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

ساختار 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;
    }
  }
}

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

فرمان‌های جدید

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

Enums جدید

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

  • 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

مشکلات

سابقه نسخه

  • بازبینی ۱،‏ ۲۰۲۵/۰۴/۰۸ (دانیل گوتنبرگ)

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