XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

نوع الإضافة

إضافة مثيل

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

790

المراجعة

1

حالة التصديق

لم تتم المصادقة عليها

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

XR_EXT_future

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

2025-12-18

حالة الملكية الفكرية

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

المساهمون

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

نظرة عامة

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

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

رموز الإرجاع

Success

  • 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 لإلغاء تفعيل أداة التتبُّع الجغرافي المكاني والموارد الأساسية.

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

أمان Thread

  • يجب مزامنة الوصول إلى geospatialTracker وأي معرّفات فرعية خارجيًا

رموز الإرجاع

Success

  • 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 عدة مرات بشكل عشوائي.

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

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: يشير إلى أنّ العنصر "position" يحتوي على بيانات صالحة

النوع 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. يمكن للتطبيق أن يطلب من المستخدم توجيه جهازه نحو اللافتات والمباني لتحسين عملية تحديد الموقع الجغرافي.

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

رموز الإرجاع

Success

  • 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، ويتم تحديدها على أنّها نصف قطر الدائرة بمستوى ثقة% 68 حول خط العرض وخط الطول المحدّدَين.
  • ‫verticalAccuracy هي الدقة العمودية المقدَّرة لموضع الوضعية الجغرافية المكانية، ويتم تحديدها على أنّها المسافة بالأمتار لمستوى ثقة يبلغ% 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، يحدّد الحقل locationFlags في location من النوع XrSpaceLocation حقول الإخراج الصالحة.

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

رموز الإرجاع

Success

  • 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

لا تتوفّر خدمة 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) إلى ما إذا كان يمكن استخدام هذه الخدمة لتحسين الدقة الجغرافية المكانية في موقع جغرافي معيّن.

تبدأ الدالة xrCheckVpsAvailabilityAsyncANDROID عملية تحقّق غير متزامنة من توفّر VPS في موقع جغرافي معيّن. لا يحتاج التطبيق إلى XrGeospatialTrackerANDROID لاستدعاء هذه الدالة، ويمكنه استخدام نتيجة هذه العملية لتحديد ما إذا كان سيتم إنشاء دالة أم لا. إذا لم يحصل التطبيق على الأذونات المطلوبة، يجب أن يعرض وقت التشغيل XR_ERROR_PERMISSION_INSUFFICIENT .

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

  • يجب تفعيل الإضافة XR_ANDROID_geospatial قبل استدعاء xrCheckVpsAvailabilityAsyncANDROID
  • يجب أن يكون session اسم معرِّف XrSession صالحًا
  • latitude يجب أن تكون قيمة صالحة لسمة double
  • longitude يجب أن تكون قيمة صالحة لسمة double
  • يجب أن يكون future مؤشرًا إلى قيمة XrFutureEXT

رموز الإرجاع

Success

  • 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);

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

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

رموز الإرجاع

Success

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

Success

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

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

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

منشآت جديدة

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

أقنعة بت جديدة

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

  • 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 ديسمبر 2025 (بن كينغ)

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