XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

نوع الإضافة

إضافة مثيل

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

790

المراجعة

1

حالة التصديق

لم تتم المصادقة

الاعتماديات على الإضافات والإصدارات

XR_EXT_future

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

2025-12-18

حالة عنوان IP

ما مِن مطالبات معروفة بشأن الملكية الفكرية.

المساهمون

"جون أولمان"، Google
"بن كينغ"، Google
"نيهاف جاين"، Google
"جاريد فايندر"، Google

نظرة عامة

توفّر هذه الإضافة ميزة "التتبُّع الجغرافي المكاني" لواجهة Geospatial API من Google التي توفّر تحديدًا دقيقًا للموقع الجغرافي والاتجاه، وتسمح للتطبيق بوضع المحتوى بالنسبة إلى الأرض. ويتم ذلك باستخدام مجموعة من أدوات تتبُّع الحركة ونظام تحديد المواقع العالمي (GPS) وأجهزة الاستشعار الأخرى، بالإضافة إلى نظام تحديد المواقع المرئي (VPS) من Google. يقارن نظام تحديد المواقع المرئي (VPS) الصور من كاميرا الجهاز بصور "التجوّل الافتراضي" لتحديد الموقع الجغرافي والاتجاه بدقة. توفّر Geospatial API غالبًا دقة تحديد المواقع الجغرافية أقل من متر واحد (أفضل بكثير من نظام تحديد المواقع العالمي) ودقة تحديد الاتجاه أقل من درجة واحدة.

لاستخدام واجهات برمجة التطبيقات في هذه الإضافة بنجاح (باستثناء التحقّق من توفّر الإضافة)، يجب أن يكون التطبيق قد ضبط بيانات اعتماد المصادقة بنجاح من خلال آلية معيّنة، مثل 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 الذي تم إنشاؤه.

يمكن لأحد التطبيقات إنشاء معرّف XrGeospatialTrackerANDROID من خلال استدعاء xrCreateGeospatialTrackerANDROID . يمكن لاحقًا استخدام معرّف 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

حالة أداة التتبُّع الجغرافية المكانية

يتم تعريف التعداد 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

لا يتم تشغيل أداة Geospatial Tracker.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

يكون جهاز التتبُّع الجغرافي قيد التشغيل وقابلاً للاستخدام.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

تعذّر إعداد Geospatial Tracker، ولن يكون قابلاً للاستخدام أبدًا.

يتم تعريف بنية 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 عددًا كبيرًا من المرات.

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

Geospatial Pose

يتم تعريف بنية XrGeospatialPoseANDROID على النحو التالي:

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

أوصاف الأعضاء

  • ‫eastUpSouthOrientation هو XrQuaternionf يحدّد الاتجاه بالنسبة إلى نظام إحداثيات يكون فيه +X=الشرق و+Y=الأعلى و+Z=الجنوب.
  • latitude هو خط العرض بالدرجات، ويتراوح بين ‎-90 و90+.
  • ‫longitude هو خط الطول بالدرجات، ويتراوح بين ‎-180 و‎+180.
  • 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 ، يحدّد الحقل poseFlags في XrGeospatialPoseResultANDROID :: 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.

إذا كانت الدقة أقل من المتوقّع، قد يشير ذلك إلى أنّ الجهاز لا يستخدم خدمة تحديد الموقع الجغرافي المستندة إلى الموقع المرئي. يمكن للتطبيق أن يطلب من المستخدم توجيه جهازه نحو اللافتات والمباني لتحسين تحديد الموقع الجغرافي.

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

رموز الإرجاع

ناجحة

  • 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 هي الدقة الأفقية المقدَّرة لموضع Geospatial pose، ويتم تعريفها على أنّها نصف قطر الدائرة بمستوى ثقة% 68 حول خطوط الطول والعرض المحدّدة.
  • verticalAccuracy هي الدقة العمودية المقدَّرة لموضع Geospatial pose، ويتم تحديدها على أنّها المسافة بالأمتار عند مستوى ثقة يبلغ% 68 حول الارتفاع المحدّد. بعبارة أخرى، هناك احتمال بنسبة% 68 أن يكون الارتفاع الحقيقي ضمن النطاق [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
  • orientationYawAccuracy هي دقة الانحراف المقدرة لاتجاه الوضع الجغرافي المكاني، ويتم تحديدها على أنّها نصف القطر بالدرجات لمستوى الثقة البالغ% 68 حول الاتجاه المحدّد.

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

تحويل وضعية جغرافية مكانية إلى XrPosef

يتم تعريف الدالة xrLocateGeospatialPoseANDROID على النحو التالي:

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

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

تحوّل الدالة 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_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

تتوفّر خدمة تحديد الموقع المرئي بالقرب من الموقع الجغرافي المحدّد.

يتم تعريف الدالة xrCheckVpsAvailabilityAsyncANDROID على النحو التالي:

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

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

  • ‫session هو XrSession الذي سيتم استخدامه في عملية التحقّق.
  • latitude هو خط العرض بالدرجات.
  • longitude هو خط الطول بالدرجات.
  • future هو مؤشر إلى XrFutureEXT الذي سيحتوي على نتيجة العملية غير المتزامنة.

يشير توفّر "خدمة تحديد المواقع المرئية" (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.
}

أنواع العناصر الجديدة

الأوامر الجديدة

المنشآت الجديدة

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

New Bitmasks

ثوابت التعداد الجديدة

  • 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

المشاكل

سجلّ التعديلات

  • المراجعة 1، 18-12-2025 (Ben King)

    • الوصف الأوّلي للإضافة