افزونه XR_ANDROID_raycast OpenXR

رشته نام

XR_ANDROID_raycast

نوع پسوند

پسوند نمونه

شماره برنامه افزودنی ثبت شده

464

تجدید نظر

1

وابستگی های افزونه و نسخه

XR_ANDROID_trackables

آخرین تاریخ اصلاح

02-10-2024

وضعیت IP

هیچ ادعای IP شناخته شده ای وجود ندارد.

مشارکت کنندگان

اسپنسر کوین، گوگل

نیهاو جین، گوگل

جان پورسی، گوگل

جارد فایندر، گوگل

لوانا چن، گوگل

کنی ورکامر، گوگل

نمای کلی

این برنامه افزودنی به برنامه اجازه می‌دهد تا در برابر ردیابی‌های موجود در محیط، پرتوهای ارسالی را انجام دهد. پرتوها می توانند برای تشخیص اشیایی در محیطی که پرتو با آنها تلاقی می کند مفید باشد. به عنوان مثال:

  • برای تعیین محل سقوط یک جسم شناور با استفاده از پرتوهای عمودی.
  • برای تعیین اینکه کاربر به کجا نگاه می کند، با استفاده از پرتوی رو به جلو.

قابلیت‌های raycast پشتیبانی شده توسط Query

تابع 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 است، اما اگر trackableTypeCapacityInput 0 باشد، می تواند NULL باشد.
  • برای توضیح دقیق بازیابی اندازه trackableTypes مورد نیاز، به بخش پارامترهای اندازه بافر مراجعه کنید.

xrEnumerateRaycastSupportedTrackableTypesANDROID انواع قابل ردیابی را که از پخش پرتوی در جلسه جاری پشتیبانی می کنند، برمی شمارد.

استفاده معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • 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

raycast را انجام دهید

تابع xrRaycastANDROID به صورت زیر تعریف می شود:

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

توضیحات پارامترها

  • session XrSession است که raycast را انجام می دهد.
  • rayInfo XrRaycastInfoANDROID است که اشعه را برای ریختن توصیف می کند.
  • results یک اشاره گر به XrRaycastHitResultsANDROID است که نتایج raycast را دریافت می کند.

این برنامه می‌تواند با فراخوانی xrRaycastANDROID ارسال‌های پرتویی را انجام دهد.

استفاده معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • 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 آرایه ای از XrTrackableTracker ANDROID هستند که پرتوهای ریخته شده باید بر روی آن آزمایش شوند.
  • origin XrVector3f است که پرتو از آن پرتاب می شود.
  • trajectory XrVector3f است که پرتو در آن هدف قرار می گیرد.
  • space همان XrSpace است که پرتو در آن ریخته می شود.
  • time XrTime است که پرتو در آن پرتاب می شود.

ساختار XrRaycastInfoANDROID اشعه ای را که باید پخش شود را توصیف می کند.

  • آرایه XrRaycastInfoANDROID::trackers ممکن است دارای ردیاب هایی از انواع مختلف باشد.
  • آرایه XrRaycastInfoANDROID::trackers نباید حاوی چندین ردیاب از یک نوع باشد، در غیر این صورت زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

استفاده معتبر (ضمنی)

ساختار 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 است. اگر resultsCapacityInput 0 باشد می تواند NULL باشد.
  • برای توضیحات دقیق در مورد بازیابی اندازه results مورد نیاز، به بخش پارامترهای اندازه بافر مراجعه کنید.

XrRaycastHitResultsANDROID شامل آرایه ای از بازدیدهای یک raycast است.

زمان اجرا باید resultsCountOutput کمتر یا مساوی با XrRaycastInfoANDROID::maxResults تنظیم کند.

استفاده معتبر (ضمنی)

ساختار XrRaycastHitResultANDROID به صورت زیر تعریف می شود:

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

توضیحات اعضا

  • type XrTrackableTypeANDROID از trackable است که raycast ضربه زده است.
  • trackable XrTrackableANDROID است که raycast به آن ضربه زد، یا XR_NULL_TRACKABLE_ANDROID اگر type قابل پیگیری XR_TRACKABLE_TYPE_DEPTH_ANDROID بود.
  • pose XrPosef است که raycast به آن برخورد کرد.

XrRaycastHitResultANDROID حاوی جزئیات یک ضربه پرتویی است.

XrRaycastHitResultANDROID::pose برای ضربه هواپیما باید به گونه ای باشد که X و Z موازی با هواپیما باشند و محور Y با هواپیما عادی باشد.

نوع ضربه قابل پیگیری

توضیحات

XR_TRACKABLE_TYPE_PLANE_ANDROID

برای تعیین عمق و جهت صحیح نقطه، به سطوح افقی و/یا عمودی برخورد می کند.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

از اطلاعات عمق کل صحنه برای تعیین عمق و جهت صحیح یک نقطه استفاده می کند.

استفاده معتبر (ضمنی)

کد مثال برای raycasting

کد مثال زیر نحوه اجرای raycasts را نشان می دهد.

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]
}

ثابت های جدید Enum

شمارش XrStructureType با:

  • XR_TYPE_RAYCAST_INFO_ANDROID
  • XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

ساختارهای جدید

توابع جدید

مسائل

تاریخچه نسخه

  • بازبینی 1، 02/10/2024 (کنی ورکامر)
    • توضیحات پسوند اولیه

OpenXR™ و لوگوی OpenXR علائم تجاری متعلق به The Khronos Group Inc. هستند و به عنوان یک علامت تجاری در چین، اتحادیه اروپا، ژاپن و بریتانیا ثبت شده اند.