إضافة XR_ANDROID_trackables OpenXR

سلسلة الاسم

XR_ANDROID_trackables

نوع الإضافة

إضافة مثيل

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

456

المراجعة

1

التبعيات المتعلّقة بالإصدارات والإضافات

OpenXR 1.0

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

2024-09-30

حالة عنوان IP

ما مِن مطالبات معروفة بعناوين IP.

المساهمون

سبنسر كوين، Google

نيهاف جاين، Google

جون بورسي، Google

جاريد فايندر، Google

ليفانا تشين، Google

"كيني فيركامر"، Google

نظرة عامة

تسمح هذه الإضافة للتطبيق بالوصول إلى الأجهزة القابلة للتتبُّع من الناحية المكانية، وإنشاء نقاط تثبيت مرتبطة بجهاز قابل للتتبُّع.

تحدِّد هذه الإضافة الأجسام القابلة للتتبُّع على متن الطائرة. قد تضيف الإضافات الأخرى أنواعًا إضافية قابلة للتتبّع. على سبيل المثال، يضيف XR_ANDROID_trackables_object عناصر قابلة للتتبُّع، ويضيف XR_ANDROID_depth_texture وحدات تخزين عمق تسمح بإلقاء أشعة على نقاط عشوائية في البيئة.

العنصر القابل للتتبّع هو عنصر يتم تتبّعه في البيئة المادية (راجِع XrTrackableTypeANDROID):

• سطح مستوٍ (مثل الحائط أو الأرضية أو السقف أو الطاولة)
• جسم (مثل لوحة مفاتيح أو ماوس أو كمبيوتر محمول)

تحذير:

الأذونات

يجب أن تتضمّن تطبيقات Android الإذن android.permission.SCENE_UNDERSTANDING في ملف البيان، لأنّ هذه الإضافة تُظهر الهندسة للبيئة. يُعدّ إذن android.permission.SCENE_UNDERSTANDING خطيرًا. يجب أن يطلب التطبيق الإذن أثناء التشغيل لاستخدام الدوالّ التالية:
xrCreateTrackableTrackerANDROID
(مستوى الحماية: خطير)

إنشاء جهاز تتبُّع

XrTrackableTrackerANDROID هو اسم معرِّف يمثّل الموارد المطلوبة لاكتشاف العناصر القابلة للتتبُّع وتعديلها من نوع XrTrackableTypeANDROID معيّن في البيئة.

XR_DEFINE_HANDLE(XrTrackableTrackerANDROID)

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

XrResult xrCreateTrackableTrackerANDROID(
    XrSession                                   session,
    const XrTrackableTrackerCreateInfoANDROID*  createInfo,
    XrTrackableTrackerANDROID*                  trackableTracker);

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

• session هو XrSession الذي ينشئ جهاز التتبُّع.
• createInfo هو مؤشر إلى بنية XrTrackableTrackerCreateInfoANDROID التي تحتوي على مَعلمات ستُستخدَم لإنشاء أداة التتبُّع.
• trackableTracker هو مؤشر إلى اسم معرِّف يتم من خلاله عرض القيمة التي تم إنشاؤها XrTrackableTrackerANDROID.

يمكن للتطبيق استخدام الدالة xrCreateTrackableTrackerANDROID ل إنشاء أداة تتبُّع قابلة للتتبُّع.

• سيتم عرض XR_ERROR_FEATURE_UNSUPPORTED إذا كان النظام لا يتوافق مع الأجهزة القابلة للتتبُّع من النوع المحدّد.
• سيتم عرض القيمة XR_ERROR_PERMISSION_INSUFFICIENT إذا لم يتم منح الأذونات المطلوبة للتطبيق المُتصل.

يمكن للتطبيق استخدام الاسم المعرِّف للعايق الذي تم إرجاعه في طلبات البيانات اللاحقة من واجهة برمجة التطبيقات. يجب أخيرًا تحرير معرّف XrTrackableTrackerANDROID باستخدام الدالة xrDestroyTrackableTrackerANDROID.

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

• يجب تفعيل إضافة XR_ANDROID_trackables قبل استدعاء xrCreateTrackableTrackerANDROID.
• session يجب أن يكون معرّف XrSession صالحًا
• createInfo يجب أن يكون مؤشرًا إلى بنية XrTrackableTrackerCreateInfoANDROID صالحة.
• trackableTracker يجب أن يكون مؤشرًا إلى اسم معرِّف XrTrackableTrackerANDROID

رموز الإرجاع

تم بنجاح

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

تعذُّر الإجراء

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_FEATURE_UNSUPPORTED

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

typedef struct XrTrackableTrackerCreateInfoANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackableTypeANDROID    trackableType;
} XrTrackableTrackerCreateInfoANDROID;

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

• type هو XrStructureType لهذه البنية.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
• trackableType هو XrTrackableTypeANDROID الذي سيتتبّعه المتتبّع.

توفّر بنية XrTrackableTrackerCreateInfoANDROID خيارات إنشاء XrTrackableTrackerANDROID عند تمريرها إلى xrCreateTrackableTrackerANDROID.

يمكن للإضافة تحديد البنى التي يمكن إرفاقها بـ next للسماح بإعداد إضافي للمتتبّعين الذين يمكن تتبُّعهم.

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

• يجب تفعيل إضافة XR_ANDROID_trackables قبل استخدام XrTrackableTrackerCreateInfoANDROID.
• type يجب أن يكون XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID
• next يجب أن يكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية. راجِع أيضًا: XrTrackableObjectConfigurationANDROID
• trackableType يجب أن تكون قيمة XrTrackableTypeANDROID صالحة

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

typedef enum XrTrackableTypeANDROID {
    XR_TRACKABLE_TYPE_NOT_VALID_ANDROID = 0,
    XR_TRACKABLE_TYPE_PLANE_ANDROID = 1,
    XR_TRACKABLE_TYPE_DEPTH_ANDROID = 1000463000,
    XR_TRACKABLE_TYPE_OBJECT_ANDROID = 1000466000
} XrTrackableTypeANDROID;

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

XrResult xrDestroyTrackableTrackerANDROID(
    XrTrackableTrackerANDROID                   trackableTracker);

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

• trackableTracker هو معرّف XrTrackableTrackerANDROID تم إنشاؤه سابقًا باستخدام xrCreateTrackableTrackerANDROID.

تؤدي الدالة xrDestroyTrackableTrackerANDROID إلى تدمير جهاز التتبُّع القابل للتتبُّع.

إذا لم يكن هناك عنصر XrTrackableTrackerANDROID صالح آخر تم إنشاؤه باستخدام XrTrackableTypeANDROID نفسه، قد يوقف النظام خدمات التتبّع المطلوبة لهذا النوع من العناصر القابلة للتتبّع للحفاظ على موارد النظام.

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

• يجب تفعيل إضافة XR_ANDROID_trackables قبل استدعاء xrDestroyTrackableTrackerANDROID
• trackableTracker يجب أن يكون مقبض XrTrackableTrackerANDROID صالحًا

أمان سلسلة المحادثات

• يجب أن تتم معالجة الوصول إلى trackableTracker وأيّ أسماء معرِّفة فرعية خارجيًا.

رموز الإرجاع

تم بنجاح

• XR_SUCCESS

تعذُّر الإجراء

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

الحصول على جميع الأجهزة القابلة للتتبُّع

يتم تعريف ذرة XrTrackableANDROID على النحو التالي:

XR_DEFINE_ATOM(XrTrackableANDROID)

يتم استخدام XrTrackableANDROID لتمثيل عنصر واحد قابل للتتبّع ولا يكون صالحًا إلا خلال دورة حياة XrTrackableTrackerANDROID المرتبط به.

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

XrResult xrGetAllTrackablesANDROID(
    XrTrackableTrackerANDROID                   trackableTracker,
    uint32_t                                    trackableCapacityInput,
    uint32_t*                                   trackableCountOutput,
    XrTrackableANDROID*                         trackables);

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

• trackableTracker هو XrTrackableTrackerANDROID المطلوب إجراء طلب بحث عنه.

• trackableCapacityInput هي سعة صفيف trackables، أو 0 لتحديد طلب لاسترداد السعة المطلوبة.

• trackableCountOutput هو مؤشر إلى عدد trackables التي تمّت كتابتها، أو هو مؤشر إلى السعة المطلوبة في حال كانت trackables غير كافية.

• trackables هو مؤشر إلى مصفوفة من XrTrackableANDROID. يمكن أن تكون القيمة NULL إذا كانت قيمة trackableCapacityInput هي 0.

• اطّلِع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم trackables المطلوب.

تملأ xrGetAllTrackablesANDROID صفيفًا من XrTrackableANDROID يمثّل الأجهزة القابلة للتتبّع التي تم العثور عليها في البيئة. يجب أن تتطابق قيمة XrTrackableTypeANDROID للعنصر trackables المعروضة مع قيمة XrTrackableTypeANDROID للعنصر trackableTracker.

الحصول على طائرة يمكن تتبُّعها

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

XrResult xrGetTrackablePlaneANDROID(
    XrTrackableTrackerANDROID                   trackableTracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackablePlaneANDROID*                    planeOutput);

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

• trackableTracker هو XrTrackableTrackerANDROID المطلوب إجراء طلب بحث عنه.

• getInfo هو XrTrackableGetInfoANDROID مع المعلومات المستخدَمة للحصول على الطائرة القابلة للتتبُّع.

• planeOutput هو مؤشر إلى XrTrackablePlaneANDROID الهيكل الذي يتم فيه عرض الطائرة القابلة للتتبّع.

تعرض الدالة xrGetTrackablePlaneANDROID تفاصيل عن سطح التتبُّع، مثل الشكل الهندسي والاتجاه وحالة التتبُّع.

يتم حلّ معلومات الطائرة وربطها بالمساحة الأساسية في وقت طلب xrGetTrackablePlaneANDROID باستخدام XrTrackableGetInfoANDROID::time، XrTrackableGetInfoANDROID::baseSpace.

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

• يجب تفعيل إضافة XR_ANDROID_trackables قبل استدعاء xrGetTrackablePlaneANDROID
• trackableTracker يجب أن يكون مقبض XrTrackableTrackerANDROID صالحًا
• getInfo يجب أن يكون مؤشرًا إلى بنية XrTrackableGetInfoANDROID صالحة
• planeOutput يجب أن يكون مؤشرًا إلى بنية XrTrackablePlaneANDROID

رموز الإرجاع

تم بنجاح

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

تعذّر الإجراء

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_TIME_INVALID

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

typedef struct XrTrackableGetInfoANDROID {
    XrStructureType       type;
    void*                 next;
    XrTrackableANDROID    trackable;
    XrSpace               baseSpace;
    XrTime                time;
} XrTrackableGetInfoANDROID;

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

• type هو XrStructureType لهذه البنية.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
• trackable هي طائرة XrTrackableANDROID المطلوب الاستعلام عنها.
• baseSpace ستكون وضعية الطائرة نسبية إلى XrSpace في time.
• time هو XrTime الذي يتم تقييم الإحداثيات عنده بالنسبة إلى baseSpace.

توفّر بنية XrTrackableGetInfoANDROID خيارات طلب البحث عند تمريرها إلى xrGetTrackablePlaneANDROID. trackable يجب أن تتطابق مع trackableTracker المستخدَمة في xrGetTrackablePlaneANDROID.

سيتم عرض XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID إذا كان نوع الtrackable الذي يمكن تتبُّعه ليس XR_TRACKABLE_TYPE_PLANE_ANDROID.

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

• يجب تفعيل إضافة XR_ANDROID_trackables قبل استخدام XrTrackableGetInfoANDROID.
• type يجب أن يكون XR_TYPE_TRACKABLE_GET_INFO_ANDROID
• next يجب أن يكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية.
• baseSpace يجب أن يكون معرّف XrSpace صالحًا

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

typedef struct XrTrackablePlaneANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    XrPlaneTypeANDROID        planeType;
    XrPlaneLabelANDROID       planeLabel;
    XrTrackableANDROID        subsumedByPlane;
    XrTime                    lastUpdatedTime;
    uint32_t                  vertexCapacityInput;
    uint32_t*                 vertexCountOutput;
    XrVector2f*               vertices;
} XrTrackablePlaneANDROID;

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

• type هو XrStructureType لهذه البنية.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
• ‫trackingState هو XrTrackingStateANDROID للطائرة.
• centerPose هو XrPosef يحدِّد موضع الطائرة ومقدار اتجاهها ضمن الإطار المرجعي لXrTrackableGetInfoANDROID::baseSpace المقابل. يمثّل اتجاه هوية هنا محاور إحداثيات مع +Y موازية لاتجاه المستوى.
• extents هي سمة XrExtent2Df للمستوى.
• planeType هو XrPlaneTypeANDROID الذي حدّده وقت التشغيل لهذه الطائرة.
• planeLabel هو XrPlaneLabelANDROID الذي حدّده وقت التشغيل لهذه الطائرة.
• subsumedByPlane هو XrTrackableANDROID للمستوى الذي يضم هذا المستوى (XR_NULL_TRACKABLE_ANDROID إذا لم يكن هناك مستوى).
• lastUpdatedTime هو XrTime آخر تحديث لملف الخطة.
• vertexCapacityInput هي سعة صفيف vertices، أو 0 لتحديد طلب لاسترداد السعة المطلوبة.
• vertexCountOutput هو مؤشر إلى عدد vertices التي تمّت كتابتها، أو مؤشر إلى السعة المطلوبة في حال عدم كفاية vertices.
• vertices هو مؤشر إلى مصفوفة من XrVector2f. ويُمكن أن يكون NULL إذا كانت قيمة vertexCapacityInput هي 0. تكون الرؤوس مرتبة في اتجاه عقارب الساعة. يمكن أن يكون المضلع مقعرًا ويجب ألّا يكون متقاطعًا ذاتيًا.
• اطّلِع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم vertices المطلوب.

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

• يجب تفعيل إضافة XR_ANDROID_trackables قبل استخدام XrTrackablePlaneANDROID.
• type يجب أن يكون XR_TYPE_TRACKABLE_PLANE_ANDROID
• next يجب أن يكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية.
• trackingState يجب أن تكون قيمة XrTrackingStateANDROID صالحة
• planeType يجب أن تكون قيمة XrPlaneTypeANDROID صالحة
• planeLabel يجب أن تكون قيمة XrPlaneLabelANDROID صالحة
• vertexCountOutput يجب أن يكون مؤشرًا إلى قيمة uint32_t
• vertices يجب أن يكون مؤشرًا إلى مصفوفة من vertexCapacityInput هياكل XrVector2f.
• يجب أن تكون المَعلمة vertexCapacityInput أكبر من 0.

يصف التعداد XrTrackingStateANDROID حالة التتبّع XrTrackableANDROID.

typedef enum XrTrackingStateANDROID {
    XR_TRACKING_STATE_PAUSED_ANDROID = 0,
    XR_TRACKING_STATE_STOPPED_ANDROID = 1,
    XR_TRACKING_STATE_TRACKING_ANDROID = 2
} XrTrackingStateANDROID;

‫XrTrackingStateANDROID	الوصف
XR_TRACKING_STATE_PAUSED_ANDROID	يشير إلى أنّه تم إيقاف تتبُّع العنصر القابل للتتبُّع أو العنصر الأساسي مؤقتًا، ولكن قد تتم استئنافه في المستقبل.
XR_TRACKING_STATE_STOPPED_ANDROID	توقّف التتبّع لهذا الجهاز القابل للتتبّع ولن تتم استئنافه أبدًا.
XR_TRACKING_STATE_TRACKING_ANDROID	يتم تتبُّع الجسم ووضعه الحالي.

يمثّل التعداد XrPlaneTypeANDROID نوع سطح XrTrackableANDROID.

typedef enum XrPlaneTypeANDROID {
    XR_PLANE_TYPE_HORIZONTAL_DOWNWARD_FACING_ANDROID = 0,
    XR_PLANE_TYPE_HORIZONTAL_UPWARD_FACING_ANDROID = 1,
    XR_PLANE_TYPE_VERTICAL_ANDROID = 2,
    XR_PLANE_TYPE_ARBITRARY_ANDROID = 3
} XrPlaneTypeANDROID;

XrPlaneLabelANDROID هو تصنيف لطائرة XrTrackableANDROID.

typedef enum XrPlaneLabelANDROID {
    XR_PLANE_LABEL_UNKNOWN_ANDROID = 0,
    XR_PLANE_LABEL_WALL_ANDROID = 1,
    XR_PLANE_LABEL_FLOOR_ANDROID = 2,
    XR_PLANE_LABEL_CEILING_ANDROID = 3,
    XR_PLANE_LABEL_TABLE_ANDROID = 4
} XrPlaneLabelANDROID;

إنشاء مساحة مرساة

XrResult xrCreateAnchorSpaceANDROID(
    XrSession                                   session,
    const XrAnchorSpaceCreateInfoANDROID*       createInfo,
    XrSpace*                                    anchorOutput);

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

• session هو XrSession الذي ينشئ مساحة الربط.
• createInfo هو مؤشر إلى بنية XrAnchorSpaceCreateInfoANDROID التي تحتوي على مَعلمات ستُستخدَم لإنشاء مساحة الربط.
• anchorOutput هو مؤشر إلى اسم معرِّف يتم من خلاله عرض القيمة التي تم إنشاؤها XrSpace.

في أي وقت، يتم تتبُّع موضع النقطة المرجعية واتجاهها أو إيقاف تتبُّعها. وهذا يعني أنّه يجب ضبط كل من XR_SPACE_LOCATION_POSITION_TRACKED_BIT و XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT أو محو كليهما عندما يستدعي التطبيق xrLocateSpace أو xrLocateSpaces لملف anchorOutput.

يجب أن يُفرِّغ التطبيق في النهاية XrSpace المُعاد باستخدام xrDestroySpace.

• يجب عرض XR_ERROR_FEATURE_UNSUPPORTED إذا كان النظام لا يتيح استخدام نقاط الربط.
• يجب عرض القيمة XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID إذا لم يكن مرفق العنصر المحدد غير متوافق.

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

• يجب تفعيل إضافة XR_ANDROID_trackables قبل استدعاء xrCreateAnchorSpaceANDROID
• session يجب أن يكون معرّف XrSession صالحًا
• createInfo يجب أن يكون مؤشرًا إلى بنية XrAnchorSpaceCreateInfoANDROID صالحة
• anchorOutput يجب أن يكون مؤشرًا إلى اسم حساب على XrSpace.

رموز الإرجاع

تم بنجاح

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

تعذّر الإجراء

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_POSE_INVALID
• XR_ERROR_TIME_INVALID
• XR_ERROR_OUT_OF_MEMORY

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

typedef struct XrAnchorSpaceCreateInfoANDROID {
    XrStructureType       type;
    void*                 next;
    XrSpace               space;
    XrTime                time;
    XrPosef               pose;
    XrTrackableANDROID    trackable;
} XrAnchorSpaceCreateInfoANDROID;

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

• type هو XrStructureType لهذه البنية.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
• space هو XrSpace الذي سيتم إنشاء العنصر الثابت عليه.
• time هو XrTime لإنشاء العنصر الأساسي.
• pose هو XrPosef للعنصر الثابت.
• trackable هو XrTrackableANDROID الذي سيتم إرفاق العنصر المرجعي به. قد يكون XR_NULL_TRACKABLE_ANDROID لإنشاء مرساه مكاني.

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

• يجب تفعيل إضافة XR_ANDROID_trackables قبل استخدام XrAnchorSpaceCreateInfoANDROID.
• type يجب أن يكون XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID
• next يجب أن يكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية.
• space يجب أن يكون معرّف XrSpace صالحًا

مثال على رمز للحصول على جميع الأجهزة القابلة للتتبُّع

يوضّح المثال التالي على الرمز البرمجي كيفية الحصول على كل الأجهزة التي يمكن تتبُّعها من نوع معيّن.

XrSession session; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTrackableTrackerCreateInfoANDROID createInfo{XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID};
createInfo.trackableType = XR_TRACKABLE_TYPE_PLANE_ANDROID;
XrTrackableTrackerANDROID planeTrackableTracker;
XrResult result = xrCreateTrackableTrackerANDROID(
  session,
  &createInfo,
  &planeTrackableTracker);
if (result != XR_SUCCESS) { /* Handle failures. */ }

uint32_t trackableCountOutput = 0;
std::vector<XrTrackableANDROID> allPlaneTrackables;

// Query the number of trackables available.
result = xrGetAllTrackablesANDROID(
  planeTrackableTracker,
  0,
  &trackableCountOutput,
  nullptr
);

if (result == XR_SUCCESS) {
  allPlaneTrackables.resize(trackableCountOutput, XR_NULL_HANDLE);

  // Fetch the actual trackable handles in the appropriately resized array.
  result = xrGetAllTrackablesANDROID(
    planeTrackableTracker,
    trackableCountOutput,
    &trackableCountOutput,
    allPlaneTrackables.data());

  if (result == XR_SUCCESS) {
    for (XrTrackableANDROID trackable : allPlaneTrackables) {
      // You now have all trackables of the specified type.
    }
  }
}

// Release trackable tracker.
result = xrDestroyTrackableTrackerANDROID(planeTrackableTracker);

مثال على رمز للحصول على مستوى الطائرة القابل للتتبّع

يوضّح المثال التالي للرمز البرمجي كيفية الحصول على مستوى طيران قابل للتتبّع من XrTrackableANDROID حالي، تم الحصول عليه من نتيجة مطابقة XR_ANDROID_raycast أو xrGetTrackablesANDROID.

XrTrackableTrackerANDROID planeTracker; // previously created

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetTrackablePlaneANDROID xrGetTrackablePlaneANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

XrTrackableGetInfoANDROID planeGetInfo;
planeGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;
planeGetInfo.next = nullptr;
planeGetInfo.trackable = planeTrackable;
planeGetInfo.space = appSpace;
planeGetInfo.time = updateTime;

XrTrackablePlaneANDROID plane = { XR_TYPE_TRACKABLE_PLANE_ANDROID };
result = xrGetTrackablePlaneANDROID(
  planeTracker,
  &planeGetInfo,
  &plane
);

if (result == XR_SUCCESS) {
  // Plane tracking state, center pose, extents, type now available in plane.
}

مثال على رمز لإنشاء مساحة للعنصر الأساسي

يوضّح مثال الرمز البرمجي التالي كيفية إنشاء مساحة ربط مرتبطة بعنصر قابل للتتبّع.

XrSession session; // Created at app startup.
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

// Create an anchor at (2, 2, 2) world-coordinates.
XrAnchorSpaceCreateInfoANDROID spatialAnchorCreateInfo;
spatialAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
spatialAnchorCreateInfo.next = nullptr;
spatialAnchorCreateInfo.space = appSpace;
spatialAnchorCreateInfo.time = updateTime;
spatialAnchorCreateInfo.pose = { { 0, 0, 0, 1 }, { 2, 2, 2 } };

XrSpace spatialAnchor = XR_NULL_HANDLE;
XrResult result = xrCreateAnchorSpaceANDROID(
  session,
  &spatialAnchorCreateInfo,
  &spatialAnchor
);

// Create an anchor attached to a trackable.
XrTrackablePlane plane = ...;
XrAnchorSpaceCreateInfoANDROID trackableAnchorCreateInfo;
trackableAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
trackableAnchorCreateInfo.next = nullptr;
trackableAnchorCreateInfo.space = appState;
trackableAnchorCreateInfo.pose = plane.centerPose;
trackableAnchorCreateInfo.trackable = planeTrackable;

XrSpace trackableAnchor = XR_NULL_HANDLE;
XrResult result = xrCreateAnchorSpaceANDROID(
  session,
  &trackableAnchorCreateInfo,
  &trackableAnchor
);
while (true) {
  // app update loop
  // ...

  // Get the current location of the anchor's space w.r.t the world.
  XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
  result = xrLocateSpace(trackableAnchor, appSpace, updateTime, &anchorLocation);

  if (anchor.trackingState == XR_TRACKING_STATE_TRACKING_ANDROID) {
    // Update anchor pose.
    doDrawingForAnchor(anchorLocation.pose);
  } else {
    // ...
  }
}

// Cleanup - destroy the space, detatch the anchor so its no longer tracked by the
// runtime and then release all resources held by it.
xrDestroySpace(spatialAnchor);
xrDestroySpace(trackableAnchor);

أنواع أساسية جديدة

• XrTrackableANDROID

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

• XrTrackableTrackerANDROID

ثوابت قائمة التعداد الجديدة

تمّت إضافة ما يلي إلى التعداد XrStructureType:

• XR_TYPE_TRACKABLE_GET_INFO_ANDROID
• XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID
• XR_TYPE_TRACKABLE_PLANE_ANDROID
• XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID

تم توسيع قائمة XrObjectType بإضافة ما يلي:

• XR_OBJECT_TYPE_TRACKABLE_TRACKER_ANDROID

تمّت إضافة ما يلي إلى التعداد XrResult:

• XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
• XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID

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

• XrTrackingStateANDROID
• XrTrackableTypeANDROID
• XrPlaneTypeANDROID
• XrPlaneLabelANDROID

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

• XrTrackableTrackerCreateInfoANDROID
• XrTrackableGetInfoANDROID
• XrTrackablePlaneANDROID
• XrAnchorSpaceCreateInfoANDROID

الدوالّ الجديدة

• xrCreateTrackableTrackerANDROID
• xrDestroyTrackableTrackerANDROID
• xrGetAllTrackablesANDROID
• xrGetTrackablePlaneANDROID
• xrCreateAnchorSpaceANDROID

المشاكل

سجلّ الإصدارات

• النسخة 1، بتاريخ 27‏/09‏/2024 (كيني فيركمير)
  • الوصف الأولي للإضافة