إضافة XR_ANDROID_raycast OpenXR

سلسلة الاسم

XR_ANDROID_raycast

نوع الإضافة

إضافة مثيل

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

464

المراجعة

1

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

XR_ANDROID_trackables

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

2024-10-02

حالة عنوان IP

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

المساهمون

سبنسر كوين، Google

نيهاف جاين، Google

جون بورسي، Google

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

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

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

نظرة عامة

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

• لتحديد المكان الذي سيقع فيه جسم عائم عند إسقاطه، باستخدام شعاع عمودي
• لتحديد ما ينظر إليه المستخدم، باستخدام شعاع ضوء موجَّه للأمام

قدرات شعاع البحث المتاحة لطلبات البحث

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

XrResult xrEnumerateRaycastSupportedTrackableTypesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    trackableTypeCapacityInput,
    uint32_t*                                   trackableTypeCountOutput,
    XrTrackableTypeANDROID*                     trackableTypes);

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

• instance هو XrInstance الذي تم استرداد systemId منه.
• systemId هو XrSystemId الذي يتمّ سرد أنواعه القابلة للتتبّع والمتوافقة مع تصوير الأشعة.
• ‫trackableTypeCapacityInput هي سعة trackableTypes، أو 0 لاسترداد السعة المطلوبة.
• trackableTypeCountOutput هو مؤشر إلى عدد عناصر المصفوفة، أو مؤشر إلى السعة المطلوبة في حال كانت trackableTypeCapacityInput غير كافية.
  • trackableTypes هو مؤشر إلى صفيف من XrTrackableTypeANDROID، ولكن يمكن أن يكون NULL إذا كان trackableTypeCapacityInput هو 0.
• راجِع قسم مَعلمات حجم المخزن المؤقت للحصول على وصف تفصيلي ل retrieving the required trackableTypes size.

يُدرِج xrEnumerateRaycastSupportedTrackableTypesANDROID الأنواع التي يمكن تتبُّعها والتي تتيح ميزة "تتبُّع الأشعة" من خلال الجلسة الحالية.

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

• يجب تفعيل امتداد XR_ANDROID_raycast قبل استدعاء xrEnumerateRaycastSupportedTrackableTypesANDROID.
• instance يجب أن يكون اسم معرِّف XrInstance صالحًا
• trackableTypeCountOutput يجب أن يكون مؤشرًا إلى قيمة uint32_t
• إذا لم يكن trackableTypeCapacityInput هو 0، يجب أن يكون trackableTypes مُشيرًا إلى صفيف من قيم trackableTypeCapacityInput XrTrackableTypeANDROID.

رموز الإرجاع

تم بنجاح

• XR_SUCCESS

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

• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SYSTEM_INVALID
• XR_ERROR_FUNCTION_UNSUPPORTED

تنفيذ شعاع ضوء

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

XrResult xrRaycastANDROID(
    XrSession                                   session,
    const XrRaycastInfoANDROID*                 rayInfo,
    XrRaycastHitResultsANDROID*                 results);

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

• session هو XrSession الذي ينفّذ تقنية "إلقاء شعاع".
• ‫rayInfo هو XrRaycastInfoANDROID الذي يصف الشعاع المطلوب بثّه.
• results هو مؤشر إلى XrRaycastHitResultsANDROID الذي يتلقّى نتائج شعاع الاختبار.

يمكن للتطبيق تنفيذ عمليات بث أشعة من خلال استدعاء xrRaycastANDROID.

• إذا تقاطعت شعاع مسح ضوئي مع عدد أكبر من الأجسام التي يمكن تتبُّعها مقارنةً بقيمة XrRaycastHitResultsANDROID::maxResults، يجب أن يعرض وقت التشغيل نتائج الاصطدام الأقرب إلى XrRaycastHitResultsANDROID::origin للشعاع.
• إذا تقاطعت شعاع اختبار مع كائن قابل للتتبُّع من النوع XR_TRACKABLE_TYPE_ANDROID_PLANE، والذي تم تضمينه في مستوى آخر، يجب أن يعرض وقت التشغيل نتيجة الاصطدام للمستوى الذي يتضمّن الكائن فقط.
• يجب أن يعرض وقت التشغيل نتائج العناصر التي تم رصدها بترتيب بدءًا من الأقرب إلى الأبعد من XrRaycastInfoANDROID::origin على طول متجه XrRaycastInfoANDROID::trajectory.
• يجب أن يعرض وقت التشغيل القيمة XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID إذا لم يتم سرد النوع القابل للتتبُّع المرتبط بعناصر التحكم XrTrackableTrackerANDROID في XrRaycastInfoANDROID::trackers باستخدام الإجراء xrEnumerateRaycastSupportedTrackableTypesANDROID.

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

• يجب تفعيل امتداد XR_ANDROID_raycast قبل استدعاء xrRaycastANDROID.
• session يجب أن يكون معرّف XrSession صالحًا
• rayInfo يجب أن يكون مؤشرًا إلى بنية XrRaycastInfoANDROID صالحة.
• results يجب أن يكون مؤشرًا إلى بنية XrRaycastHitResultsANDROID

رموز الإرجاع

تم بنجاح

• 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_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_POSE_INVALID
• XR_ERROR_TIME_INVALID
• XR_ERROR_FEATURE_UNSUPPORTED

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

typedef struct XrRaycastInfoANDROID {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            maxResults;
    uint32_t                            trackerCount;
    const XrTrackableTrackerANDROID*    trackers;
    XrVector3f                          origin;
    XrVector3f                          trajectory;
    XrSpace                             space;
    XrTime                              time;
} XrRaycastInfoANDROID;

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

• type هو XrStructureType لهذه البنية.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
• maxResults هو الحدّ الأقصى uint32_t لعدد النتائج التي سيتم عرضها.
• trackerCount هو عدد uint32_t في صفيف trackers.
• trackers هو صفيف XrTrackableTrackerANDROID الذي يجب اختبار شعاع البث عليه.
• origin هو XrVector3f الذي يتم بث الشعاع منه.
• trajectory هو XrVector3f الذي يتم استهداف الشعاع به.
• space هو XrSpace الذي يتم بث الشعاع فيه.
• time هو XrTime الذي يتم رمي الشعاع عليه.

تصف بنية XrRaycastInfoANDROID الشعاع الذي سيتم بثّه.

• قد تحتوي مصفوفة XrRaycastInfoANDROID::trackers على أجهزة تتبُّع من أنواع مختلفة.
• يجب ألا تحتوي مصفوفة XrRaycastInfoANDROID::trackers على عدة أجهزة تتبُّع من النوع نفسه، وإلا يجب أن يعرض وقت التشغيلXR_ERROR_VALIDATION_FAILURE.

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

• يجب تفعيل إضافة XR_ANDROID_raycast قبل استخدام XrRaycastInfoANDROID.
• type يجب أن يكون XR_TYPE_RAYCAST_INFO_ANDROID
• next يجب أن يكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية.
• trackers يجب أن يكون مؤشرًا إلى مصفوفة من trackerCount معالِمات trackerCount XrTrackableTrackerANDROID صالحة
• space يجب أن يكون معرّف XrSpace صالحًا
• يجب أن تكون المَعلمة trackerCount أكبر من 0.
• يجب أن يكون كلّ من space وعناصر trackers قد تم إنشاؤها أو تخصيصها أو استرجاعها من XrSession نفسها.

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

typedef struct XrRaycastHitResultsANDROID {
    XrStructureType               type;
    void*                         next;
    uint32_t                      resultsCapacityInput;
    uint32_t                      resultsCountOutput;
    XrRaycastHitResultANDROID*    results;
} XrRaycastHitResultsANDROID;

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

• type هو XrStructureType لهذه البنية.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
• resultsCapacityInput هي سعة صفيف results، أو 0 لتحديد طلب لاسترداد السعة المطلوبة.
• resultsCountOutput هو مؤشر إلى عدد results التي تمّت كتابتها، أو مؤشر إلى السعة المطلوبة في حال كانت resultsCapacityInput غير كافية.
• results هو مؤشر إلى صفيف من XrRaycastHitResultANDROID البنى. يمكن أن تكون NULL إذا كانت resultsCapacityInput تساوي 0.
• راجِع قسم مَعلمات حجم المخزن المؤقت للحصول على وصف تفصيلي ل retrieving the required results size.

يحتوي XrRaycastHitResultsANDROID على صفيف النتائج لشعاع اختبار.

يجب أن يضبط وقت التشغيل القيمة resultsCountOutput لتكون أقل من أو مساوية لقيمة XrRaycastInfoANDROID::maxResults.

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

• يجب تفعيل إضافة XR_ANDROID_raycast قبل استخدام XrRaycastHitResultsANDROID.
• type يجب أن يكون XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID
• next يجب أن يكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية.
• results يجب أن يكون مؤشرًا إلى صفيف من هياكل resultsCapacityInput XrRaycastHitResultANDROID-based
• يجب أن تكون المَعلمة resultsCapacityInput أكبر من 0.

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

typedef struct XrRaycastHitResultANDROID {
    XrTrackableTypeANDROID    type;
    XrTrackableANDROID        trackable;
    XrPosef                   pose;
} XrRaycastHitResultANDROID;

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

• type هو XrTrackableTypeANDROID للعنصر القابل للتتبُّع الذي اصطدمت به شعاع الاختبار.
• trackable هو XrTrackableANDROID الذي اصطدم به شعاع الضوء، أو XR_NULL_TRACKABLE_ANDROID إذا كان type الذي يمكن تتبُّعه XR_TRACKABLE_TYPE_DEPTH_ANDROID.
• pose هو XrPosef الذي اصطدم به شعاع الضوء.

يحتوي XrRaycastHitResultANDROID على تفاصيل ناتجة عن اصطدام شعاع.

يجب أن يكون XrRaycastHitResultANDROID::pose لنقطة اصطدام بسطح مستوٍ بحيث يكون محورا X وZ موازيين للسطح المستوٍ، ويكون محور Y عموديًا على السطح المستوٍ.

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

• يجب تفعيل إضافة XR_ANDROID_raycast قبل استخدام XrRaycastHitResultANDROID.
• type يجب أن تكون قيمة XrTrackableTypeANDROID صالحة

مثال على رمز برمجي لإطلاق أشعة

يوضّح مثال الرمز البرمجي التالي كيفية تنفيذ عمليات بث الأشعة.

XrSession session; // previously initialized
XrTime updateTime; // previously initialized
XrSpace appSpace;  // space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrPosef headPose;  // latest pose of the HMD.
XrTrackableTrackerANDROID planeTracker; // tracker for plane trackables.
XrTrackableTrackerANDROID depthTracker; // tracker for depth trackables.

// Perform a raycast against multiple trackers.
XrTrackableTrackerANDROID trackers[] = {
  &planeTracker,
  &depthTracker,
};
XrRaycastInfoANDROID rayInfo = {XR_TYPE_RAYCAST_INFO_ANDROID};
rayInfo.trackerCount = sizeof(trackers) / sizeof(XrTrackableTrackerANDROID);
rayInfo.trackers = trackers;
rayInfo.origin = headPose.position;
rayInfo.trajectory = CalculateForwardDirectionFromHeadPose(headPose);
rayInfo.space = appSpace;
rayInfo.time = updateTime;

uint32_t totalHitResults = 0;
constexpr uint32 NUM_DESIRED_RESULTS = 2;
XrRaycastHitResultANDROID hitResult[NUM_DESIRED_RESULTS];
XrRaycastHitResultsANDROID hitResults = {XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID};
hitResults.maxResults = NUM_DESIRED_RESULTS;
hitResults.resultsCapacityInput = NUM_DESIRED_RESULTS;
hitResults.results = hitResult;
XrResult result = xrRaycastANDROID(session, &rayInfo, &hitResults);

if (result == XR_SUCCESS && hitResults.resultsCountOutput >= 1) {
  // Hit results are returned in closest-to-farthest order in
  // hitResults.results[0] .. hitResults.results[hitResults.resultsCountOutput - 1]
}

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

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

• XR_TYPE_RAYCAST_INFO_ANDROID
• XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

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

• XrRaycastInfoANDROID
• XrRaycastHitResultANDROID
• XrRaycastHitResultsANDROID

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

• xrEnumerateRaycastSupportedTrackableTypesANDROID
• xrRaycastANDROID

المشاكل

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

• المراجعة 1، ‎2024-10-02 (كيني فيركمير)
  • الوصف الأوّلي للإضافة

‫OpenXR™ وشعار OpenXR هما علامتان تجاريتان مملوكتان لشركة The Khronos Group Inc. ومسجَّلتان كعلامتَين تجاريتَين في الصين والاتحاد الأوروبي واليابان والمملكة المتحدة.