XR_ANDROID_geospatial

رشته نام

XR_ANDROID_geospatial

نوع افزونه

افزونه نمونه

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

۷۹۰

بازنگری

۱

وضعیت تصویب

تصویب نشده

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

XR_EXT_future

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

۲۰۲۵-۱۲-۱۸

وضعیت آی‌پی

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

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

جان اولمن، گوگل
بن کینگ، گوگل
نیهاو جین، گوگل
جارد فایندر، گوگل

نمای کلی

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

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

مجوزها

برنامه‌های اندروید برای استفاده از این افزونه باید مجوز 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 ، بررسی کند که آیا سیستم از ویژگی‌های مکانی پشتیبانی می‌کند یا خیر.

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

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

یک دسته ردیاب جغرافیایی ایجاد کنید 

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

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

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

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

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

یک برنامه می‌تواند با فراخوانی xrCreateGeospatialTrackerANDROID یک دسته XrGeospatialTrackerANDROID ایجاد کند. دسته XrGeospatialTrackerANDROID برگردانده شده می‌تواند متعاقباً در فراخوانی‌های API استفاده شود. اگر برنامه مجوزهای لازم را کسب نکرده باشد، زمان اجرا باید 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

ردیاب موقعیت مکانی ایالت

شمارش 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 جدید است.
  • اگر state XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID باشد، initializationResult نتیجه خطا است، در غیر این صورت 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، موقعیت و جهت‌گیری را نسبت به زمین نشان می‌دهد.

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

  • قبل از استفاده از XrGeospatialPoseANDROID، افزونه‌ی XR_ANDROID_geospatial باید فعال باشد.
  • 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 - نشان می‌دهد که عضو orientation حاوی داده‌های معتبر است.
  • 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 یک bitmask از XrGeospatialPoseFlagsANDROID است که اعتبار اجزای pose را نشان می‌دهد.
  • 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 را برگرداند، location XrSpaceLocation :: locationFlags تعیین می‌کند که کدام فیلدهای خروجی معتبر هستند.

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

کدهای بازگشت

موفقیت

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

VPS در نزدیکی محل مورد نظر در دسترس نیست.

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

فراخوانی APIهای موقعیت مکانی 

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.
}

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

دستورات جدید

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

Enum های جدید

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

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

  • 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

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۵-۱۲-۱۸ (بن کینگ)

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