XR_ANDROID_geospatial

رشته نام

XR_ANDROID_geospatial

نوع افزونه

افزونه نمونه

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

790

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

XR_EXT_future

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

2025-12-18

وضعیت IP

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

همیاران

John Ullman،‏ Google
Ben King،‏ Google
Nihav Jain،‏ Google
Jared Finder،‏ Google

نمای کلی

این افزونه ردیابی زمین‌مکانی را برای Geospatial API (میانای برنامه‌سازی کاربردی زمین‌مکانی) Google ارائه می‌دهد که جهت‌یابی و مکان جغرافیایی دقیقی را ارائه می‌دهد و به برنامه اجازه می‌دهد محتوا را نسبت به زمین قرار دهد. این کار را بااستفاده از ترکیبی از ردیابی حرکت، GPS و حسگرهای دیگر، و «سیستم موقعیت‌یابی بصری» (VPS) Google انجام می‌دهد. VPS تصاویر دوربین دستگاه را با تصاویر «نمای خیابان» مقایسه می‌کند تا مکان و جهت دقیق را تعیین کند. Geospatial API اغلب دقت موقعیتی زیر متر (چندین برابر بهتر از GPS) و دقت جهت‌یابی زیر درجه ارائه می‌دهد.

برای استفاده موفقیت‌آمیز از میاناهای برنامه‌سازی کاربردی در این افزونه (به‌جز بررسی پشتیبانی افزونه)، برنامه باید اعتبارنامه‌های اصالت‌سنجی را ازطریق مکانیزمی مانند XR_ANDROID_google_cloud_auth با موفقیت تنظیم کرده باشد. برای جزئیات بیشتر درباره راه‌اندازی و نتایج خطا، به مستندات افزونه احراز هویت مراجعه کنید.

اجازه‌ها

برنامه‌های Android باید اجازه android.permission.ACCESS_FINE_LOCATION را در مانیفست خود فهرست کنند تا بتوانند از این افزونه استفاده کنند. اجازه android.permission.ACCESS_FINE_LOCATION اجازه خطرناکی محسوب می‌شود. برنامه باید برای استفاده از این عملکردها، در زمان اجرا درخواست اجازه کند:

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

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

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

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
  • ‫supportsGeospatial یک XrBool32 است که نشان می‌دهد آیا سیستم فعلی از ویژگی‌های جغرافیایی پشتیبانی می‌کند یا نه.

برنامه می‌تواند با زنجیر کردن ساختار XrSystemGeospatialPropertiesANDROID به XrSystemProperties هنگام فراخوانی xrGetSystemProperties، بررسی کند که آیا سیستم از ویژگی‌های جغرافیایی پشتیبانی می‌کند یا نه.

اگر زمان اجرا XR_FALSE را برای supportsGeospatial برگرداند، سیستم از ویژگی‌های جغرافیایی-فضایی پشتیبانی نمی‌کند و بنابراین باید XR_ERROR_FEATURE_UNSUPPORTED را از xrCreateGeospatialTrackerANDROID برگرداند. برنامه باید از عملکرد جغرافیایی زمانی که supportsGeospatial XR_FALSE است، اجتناب کند.

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

ایجاد دسته Geospatial Tracker

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

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

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

شرح پارامترها

  • ‫session یک XrSession است که ردیاب جغرافیایی در آن فعال خواهد بود.
  • ‫createInfo اشاره‌گری به ساختار XrGeospatialTrackerCreateInfoANDROID است که پارامترهای اولیه ردیاب زمین‌مکانی را مشخص می‌کند.
  • ‫geospatialTrackerOutput اشاره‌گری به دستگیره‌ای است که XrGeospatialTrackerANDROID ایجادشده در آن برگردانده می‌شود.

برنامه می‌تواند با فراخوانی xrCreateGeospatialTrackerANDROID، یک دسته XrGeospatialTrackerANDROID ایجاد کند. از دسته XrGeospatialTrackerANDROID برگردانده‌شده می‌توان متعاقباً در فراخوانی‌های میانای برنامه‌سازی کاربردی استفاده کرد. اگر برنامه اجازه‌های لازم را دریافت نکرده باشد، زمان اجرا باید XR_ERROR_PERMISSION_INSUFFICIENT را برگرداند. در هر زمان، فقط یک XrGeospatialTrackerANDROID می‌تواند برای یک XrSession خاص وجود داشته باشد. برنامه باید اطمینان حاصل کند که هرگونه شیء XrGeospatialTrackerANDROID قبلی قبل‌از فراخوانی مجدد این تابع ازبین رفته است، درغیراین‌صورت زمان اجرا باید XR_ERROR_LIMIT_REACHED را برگرداند. اگر ردیاب با موفقیت ایجاد شود، ابتدا وارد وضعیت XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID می‌شود و برنامه باید منتظر بماند تا وضعیت به XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID تغییر کند و سپس از ردیاب استفاده کند. XrEventDataGeospatialTrackerStateChangedANDROID را ببینید. اگر برنامه XrGeospatialTrackerANDROID را که در وضعیت XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID نیست به تابعی که به آن نیاز دارد ارسال کند، زمان اجرا باید XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID را برگرداند.

دستگیره XrGeospatialTrackerANDROID باید درنهایت ازطریق تابع xrDestroyGeospatialTrackerANDROID آزاد شود.

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

کدهای برگشتی

موفقیت‌آمیز بود

  • 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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrGeospatialTrackerCreateInfoANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.

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

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

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

شرح پارامترها

برنامه می‌تواند از تابع xrDestroyGeospatialTrackerANDROID برای رها کردن ردیاب جغرافیایی و منابع اساسی استفاده کند.

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

ایمنی رشته‌ای

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

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS

ناموفق

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

وضعیت ردیاب زمین‌مکانی

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

typedef enum XrGeospatialTrackerStateANDROID {
    XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID = 0,
    XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID = 1,
    XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID = 2,
    XR_GEOSPATIAL_TRACKER_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGeospatialTrackerStateANDROID;

شمارش XrGeospatialTrackerStateANDROID حالت‌های مختلف ردیاب جغرافیایی را شناسایی می‌کند.

مقادیر شمارشی دارای مقادیر زیر هستند:

شرح شمارشی

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

«ردیاب جغرافیایی» درحال اجرا نیست.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

ردیاب جغرافیایی درحال اجرا و قابل‌استفاده است.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

راه‌اندازی «ردیاب جغرافیایی» ناموفق بود و هرگز قابل‌استفاده نخواهد بود.

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

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫geospatialTracker همان XrGeospatialTrackerANDROID است که وضعیت آن تغییر کرده است.
  • state XrGeospatialTrackerStateANDROID جدید است.
  • initializationResult نتیجه خطا است اگر state برابر با XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID باشد، درغیراین‌صورت XR_SUCCESS است.
  • time XrTime است که در آن تغییر وضعیت رخ داده است.

ساختار XrEventDataGeospatialTrackerStateChangedANDROID زمانی ارسال می‌شود که وضعیت ردیاب جغرافیایی تغییر کند. اگر برنامه XrGeospatialTrackerANDROID معتبری داشته باشد، باید برای این رویداد نظرسنجی کند. اولین رویداد دریافتی برای ردیاب state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID خواهد داشت. پس‌از مدت زمان تعیین‌شده در زمان اجرا، وضعیت باید به XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID یا XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID تغییر کند. این انتقال مدت زمان دلخواهی طول خواهد کشید. اگر state به XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID تغییر کند، باید آخرین رویداد دریافتی برای این ردیاب باشد و فیلد initializationResult کد خطا را نگه می‌دارد. ممکن است چند ثانیه طول بکشد تا خطا رخ دهد. در این حالت، برنامه باید ردیاب را ازبین ببرد. اگر state به XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID تغییر کند، همه لنگرهای جغرافیایی-فضایی که قبلاً ایجاد شده‌اند باید ردیابی را برای همیشه متوقف کنند و باید توسط برنامه ازبین بروند. وضعیت ممکن است به‌طور دلخواه چندین‌بار بین XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID و XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID تغییر کند.

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

ژست زمین‌مکانی

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

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

توضیحات عضو

  • eastUpSouthOrientation یک XrQuaternionf است که جهت را نسبت به سیستم مختصاتی تعریف می‌کند که در آن +X=شرق، +Y=بالا، و +Z=جنوب است.
  • latitude عرض جغرافیایی به درجه است، بین ۹۰- و ۹۰+.
  • longitude طول جغرافیایی به درجه است، بین ۱۸۰- و ۱۸۰+.
  • altitude ارتفاع به متر از بیضی‌گون WGS84 است.

ساختار XrGeospatialPoseANDROID نشان‌دهنده موقعیت و جهت نسبت به زمین بااستفاده از بیضی‌گون WGS84 است.

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

  • افزونه XR_ANDROID_geospatial باید قبل‌از استفاده از XrGeospatialPoseANDROID فعال شود
  • latitude باید مقدار double معتبری باشد
  • longitude باید مقدار double معتبری باشد
  • altitude باید مقدار double معتبری باشد

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

// Flag bits for XrGeospatialPoseFlagsANDROID
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID = 0x00000001;
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID = 0x00000002;

شمارش XrGeospatialPoseFlagBitsANDROID پرچم‌های مربوط به وضعیت‌های زمین‌مکانی را مشخص می‌کند.

بیت‌های پرچم معانی زیر را دارند:

توضیحات پرچم

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID — نشان می‌دهد که عضو جهت‌یابی حاوی داده‌های معتبر است
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID — نشان می‌دهد که عضو موقعیت حاوی داده‌های معتبر است

نوع XrGeospatialPoseFlagsANDROID یک ماسک بیتی از XrGeospatialPoseFlagBitsANDROID است.

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

درحال تبدیل XrPosef به «وضعیت مکانی-فضایی»

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

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

شرح پارامترها

تابع xrLocateGeospatialPoseFromPoseANDROID یک حالت را در XrGeospatialPoseFromPoseLocateInfoANDROID :: space به حالت جغرافیایی تبدیل می‌کند. اگر وضعیت geospatialTracker XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID نباشد، زمان اجرا باید XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID را برگرداند. اگر تابع XR_SUCCESS را برگرداند، فیلد XrGeospatialPoseResultANDROID :: poseFlags از geospatialPoseResult تعیین می‌کند کدام فیلدهای خروجی معتبر هستند. اگر XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID در XrGeospatialPoseResultANDROID :: poseFlags تنظیم نشده باشد، برنامه نباید فیلدهای XrGeospatialPoseANDROID :: latitude، XrGeospatialPoseANDROID :: longitude، XrGeospatialPoseANDROID :: altitude، XrGeospatialPoseResultANDROID :: horizontalAccuracy، یا XrGeospatialPoseResultANDROID :: verticalAccuracy را در XrGeospatialPoseResultANDROID بخواند. اگر XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID در XrGeospatialPoseResultANDROID :: poseFlags تنظیم نشده باشد، برنامه نباید XrGeospatialPoseANDROID :: eastUpSouthOrientation یا XrGeospatialPoseResultANDROID :: orientationYawAccuracy را بخواند. اگر XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID تنظیم نشده باشد، XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID نیز نباید تنظیم شود.

اگر دقت کمتر از حد انتظار باشد، این می‌تواند نشان‌دهنده این باشد که دستگاه از بومی‌سازی VPS استفاده نمی‌کند. برنامه می‌تواند به کاربر دستور دهد دستگاهش را به‌سمت تابلوها و ساختمان‌ها بگیرد تا محلی‌سازی بهبود یابد.

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

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ناموفق

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialPoseFromPoseLocateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrPosef            pose;
} XrGeospatialPoseFromPoseLocateInfoANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫space همان XrSpace است که pose در آن تعریف شده است.
  • time عبارت است از XrTime که pose در آن ارزیابی می‌شود.
  • ‫pose همان XrPosef در space است که باید به وضعیت زمین‌مکانی تبدیل شود.

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

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

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫poseFlags یک ماسک بیتی از XrGeospatialPoseFlagsANDROID است که اعتبار مؤلفه‌های حالت را نشان می‌دهد.
  • geospatialPose نتیجه XrGeospatialPoseANDROID است.
  • ‫horizontalAccuracy دقت افقی تخمینی موقعیت ژست «فضایی جغرافیایی» است که به‌صورت شعاع (به متر) دایره‌ای با سطح اطمینان ۶۸٪ در اطراف عرض و طول جغرافیایی داده‌شده تعریف می‌شود.
  • verticalAccuracy دقت عمودی تخمینی موقعیت حالت «فضای جغرافیایی» است که به‌عنوان فاصله برحسب متر با سطح اطمینان ۶۸٪ در اطراف ارتفاع داده‌شده تعریف می‌شود. به عبارت دیگر، ۶۸٪ احتمال دارد که ارتفاع واقعی در محدوده [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ] باشد.
  • ‫orientationYawAccuracy دقت تخمینی انحراف جهت ژست «فضای جغرافیایی» است که به‌عنوان شعاع برحسب درجه سطح اطمینان ۶۸٪ در اطراف جهت داده‌شده تعریف می‌شود.

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

تبدیل کردن «وضعیت زمین‌مکانی» به XrPosef

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

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

شرح پارامترها

  • ‫geospatialTracker همان XrGeospatialTrackerANDROID است که برای تبدیل استفاده می‌شود.
  • ‫locateInfo اشاره‌گری به XrGeospatialPoseLocateInfoANDROID است که حاوی پارامترهای پُرسمان است.
  • ‫location اشاره‌گری به XrSpaceLocation است که حالت حاصل را دریافت می‌کند.

تابع xrLocateGeospatialPoseANDROID یک وضعیت جغرافیایی-فضایی را به XrSpaceLocation تبدیل می‌کند. اگر XrGeospatialTrackerANDROID درحال اجرا نباشد، زمان اجرا باید XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID را برگرداند. اگر تابع XR_SUCCESS را برگرداند، فیلد XrSpaceLocation :: locationFlags از location تعیین می‌کند کدام فیلدهای خروجی معتبر هستند.

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

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ناموفق

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫space همان XrSpace است که حالت نهایی در آن نمایش داده خواهد شد.
  • time XrTime است که در آن حالت قرار دارد.
  • geospatialPose همان XrGeospatialPoseANDROID برای تبدیل است.

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

دردسترس بودن VPS

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

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

شمارش XrVPSAvailabilityANDROID نشان‌دهنده دردسترس بودن VPS است.

مقادیر شمارشی دارای مقادیر زیر هستند:

شرح شمارشی

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

«سرویس موقعیت‌یابی بصری» در نزدیکی مکان ارائه‌شده دردسترس نیست.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

VPS در نزدیکی مکان ارائه‌شده دردسترس است.

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

XrResult xrCheckVpsAvailabilityAsyncANDROID(
    XrSession                                   session,
    double                                      latitude,
    double                                      longitude,
    XrFutureEXT*                                future);

شرح پارامترها

  • session XrSession است که برای بررسی استفاده می‌شود.
  • latitude عرض جغرافیایی به درجه است.
  • ‫longitude طول جغرافیایی به درجه است.
  • ‫future اشاره‌گری به XrFutureEXT است که نتیجه عملیات ناهمگام را نگه می‌دارد.

دردسترس بودن «سرویس موقعیت‌یابی بصری» (VPS) نشان می‌دهد که آیا می‌توان از VPS برای بهبود دقت جغرافیایی در مکان مشخصی استفاده کرد یا نه.

تابع xrCheckVpsAvailabilityAsyncANDROID بررسی ناهمگام برای دردسترس بودن VPS در مکان مشخص‌شده را آغاز می‌کند. برنامه برای فراخوانی این تابع به XrGeospatialTrackerANDROID نیاز ندارد و می‌تواند از نتیجه این عملیات برای تصمیم‌گیری درباره ایجاد آن استفاده کند. اگر برنامه اجازه‌های لازم را دریافت نکرده باشد، زمان اجرا باید XR_ERROR_PERMISSION_INSUFFICIENT را برگرداند.

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

  • افزونه XR_ANDROID_geospatial باید قبل‌از فراخوانی xrCheckVpsAvailabilityAsyncANDROID فعال شود
  • session باید یک دسته XrSession معتبر باشد
  • latitude باید مقدار double معتبری باشد
  • longitude باید مقدار double معتبری باشد
  • future باید اشاره‌گری به مقدار XrFutureEXT باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ناموفق

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

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

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

توضیحات عضو

  • type XrStructureType این ساختار است.
  • ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است.
  • ‫futureResult XrResult عملیات بررسی است. اگر futureResult برابر با XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID باشد، ساختاری در زنجیره next ممکن است اطلاعات بیشتری درباره این عملیات ناموفق ارائه دهد.
  • availability نتیجه XrVPSAvailabilityANDROID است. برنامه نباید این فیلد را بخواند مگراینکه futureResult XR_SUCCESS باشد.

کدهای برگشتی آتی

مقادیر futureResult:

موفقیت‌آمیز بود

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ناموفق

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

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

مثال

راه‌اندازی ردیاب زمین‌مکانی

PFN_xrCheckVpsAvailabilityAsyncANDROID xrCheckVpsAvailabilityAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCheckVpsAvailabilityCompleteANDROID xrCheckVpsAvailabilityCompleteANDROID;
PFN_xrCreateGeospatialTrackerANDROID xrCreateGeospatialTrackerANDROID;
XrInstance instance = XR_NULL_HANDLE;
XrSystemId systemId = XR_NULL_SYSTEM_ID;
XrSession session = XR_NULL_HANDLE;
double lat = 37.422, lng = -122.084;

// Check for support.
XrSystemGeospatialPropertiesANDROID geospatialSystemProperties{
    XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{XR_TYPE_SYSTEM_PROPERTIES,
                                    &geospatialSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!geospatialSystemProperties.supportsGeospatial) {
  return;
}

// Check VPS Availability.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCheckVpsAvailabilityAsyncANDROID(session, lat, lng, &future));

XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
pollInfo.future = future;
pollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (pollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
}

XrVPSAvailabilityCheckCompletionANDROID vpsCompletion{
    XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID};
CHK_XR(xrCheckVpsAvailabilityCompleteANDROID(session, future, &vpsCompletion));
if (vpsCompletion.futureResult == XR_SUCCESS) {
  if (vpsCompletion.availability == XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID) {
    // Visual Positioning Service is not available. Accuracy of positions and
    // orientations from Geospatial APIs are expected to be lower at this location.
  } else {
    // Visual Positioning Service is available. Higher accuracy of position and
    // orientation is achievable at this location.
  }
}

// Create Geospatial Tracker.
XrGeospatialTrackerCreateInfoANDROID createInfo{
    XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID};
XrGeospatialTrackerANDROID geospatialTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateGeospatialTrackerANDROID(session, &createInfo, &geospatialTracker));

// In application main event loop:
while (true) {
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  if (xrPollEvent(instance, &event) != XR_SUCCESS) {
    continue;
  }
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID:
      const XrEventDataGeospatialTrackerStateChangedANDROID& eventData =
          *reinterpret_cast<XrEventDataGeospatialTrackerStateChangedANDROID*>(&event);
      switch (eventData.state) {
        case XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID:
          // Destroy existing anchors, if any.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID:
          // Start adding content.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID:
          // Handle eventData.initializationResult error result.
          break;
      }
  }
}

فراخوانی میاناهای برنامه‌سازی کاربردی Geospatial Pose

PFN_xrLocateGeospatialPoseFromPoseANDROID xrLocateGeospatialPoseFromPoseANDROID;
PFN_xrLocateGeospatialPoseANDROID xrLocateGeospatialPoseANDROID;

XrGeospatialTrackerANDROID geospatialTracker;

// Get pose from view space.
XrSpace viewSpace;
XrPosef identityPose = {{0,0,0,1},{0,0,0}};
XrGeospatialPoseFromPoseLocateInfoANDROID poseGetInfo{
    XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID};
XrGeospatialPoseResultANDROID poseResult{
    XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID};
poseGetInfo.space = viewSpace;
poseGetInfo.pose = identityPose;
poseGetInfo.time = 0;  // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseFromPoseANDROID(geospatialTracker, &poseGetInfo, &poseResult));
if ((poseResult.poseFlags & XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID) &&
    (poseResult.poseFlags & XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID)) {
  // poseResult.geospatialPose is valid.
}

// Convert Geospatial pose to an XrSpaceLocation.
XrGeospatialPoseLocateInfoANDROID poseLocateInfo{
    XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID};
XrSpaceLocation location{XR_TYPE_SPACE_LOCATION};
poseLocateInfo.space = viewSpace;
poseLocateInfo.geospatialPose = poseResult.geospatialPose;
poseLocateInfo.time = 0; // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseANDROID(geospatialTracker, &poseLocateInfo, &location));
if ((location.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT) &&
    (location.locationFlags & XR_SPACE_LOCATION_POSITION_VALID_BIT)) {
  // location.pose is valid.
}

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

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

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

Enums جدید

ماسک‌های بیتی جدید

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

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • درحال گسترش دادن XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • درحال گسترش دادن XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • درحال گسترش دادن XrStructureType :

    • XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
    • XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID

مشکلات

سابقه نسخه

  • بازبینی ۱، ‎۲۰۲۵-۱۲-۱۸ (بن کینگ)

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