تتوفّر حزمة تطوير البرامج (SDK) لنظام Android XR الآن في "معاينة المطوّر". يهمّنا معرفة ملاحظاتك. يُرجى الانتقال إلى صفحة الدعم للتواصل معنا.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إضافة XR_ANDROID_raycast OpenXR

سلسلة الاسم

XR_ANDROID_raycast

نوع الإضافة

إضافة مثيل

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

464

المراجعة

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

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 الذي يجب اختبار ray المعروض عليه.
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_TRACKABLE_TYPE_PLANE_ANDROID`	تصطدم بالأسطح الأفقية و/أو العمودية لتحديد العمق والاتجاه الصحيحَين للنقطة.
`XR_TRACKABLE_TYPE_DEPTH_ANDROID`	يستخدم هذا الأسلوب معلومات العمق من المشهد بأكمله لتحديد العمق والاتجاه الصحيحَين لنقطة معيّنة.

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

يجب تفعيل إضافة 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 (كيني فيركمير)
- الوصف الأولي للإضافة