תוסף OpenXR‏ XR_ANDROID_raycast

מחרוזת שם

XR_ANDROID_raycast

סוג התוסף

תוסף למכונה

מספר תוסף רשום

464

גרסה

1

תלות בתוספים ובגרסאות

XR_ANDROID_trackables

תאריך השינוי האחרון

2024-10-02

סטטוס כתובת ה-IP

לא ידוע על תלונות על הפרת זכויות יוצרים בנושא כתובת IP.

שותפים ביצירת התוכן

ספנסר קווין (Spencer Quin), Google

Nihav Jain, ‏ Google

ג'ון פורסי (John Pursey), Google

Jared Finder, ‏ Google

לבנה צ'ן, Google

Kenny Vercaemer, ‏ Google

סקירה כללית

התוסף הזה מאפשר לאפליקציה לבצע הקרנות של קרניים על סמך פריטים שניתנים למעקב בסביבה. אפשר להשתמש ב-Raycasts כדי לזהות אובייקטים בסביבה שרקר יעבור דרכם. לדוגמה:

  • כדי לקבוע לאן יפול אובייקט צף כשמשחררים אותו, באמצעות יצירת קרן אנכית.
  • כדי לקבוע לאן המשתמש מביט, באמצעות קרן קדימה.

יכולות של 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.
  • בקטע פרמטרים של גודל מאגר מפורט תיאור של אחזור הגודל הנדרש של trackableTypes.

הפונקציה xrEnumerateRaycastSupportedTrackableTypesANDROID מפרטת את סוגי העצמים שניתן לעקוב אחריהם שתומכים ב-raycasting בסשן הנוכחי.

שימוש תקין (מרומז)

קודי החזרה

הצלחה

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

תיאורי פרמטרים

האפליקציה יכולה לבצע הקרנות קרן על ידי קריאה ל-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 הוא המערך של XrTrackableTrackerANDROID שאליו צריך לבדוק את קרן האור שהוטמנה.
  • origin הוא XrVector3f שממנו מוקרן הקרן.
  • trajectory הוא XrVector3f שאליו מכוון הקרן.
  • space הוא מרחב XR שבו קרן האור מושלכת.
  • 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 כינויים חוקיים של 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.
  • בקטע פרמטרים של גודל מאגר מפורט תיאור של אחזור הגודל הנדרש של results.

המאפיין XrRaycastHitResultsANDROID מכיל את מערך ההיטים של קרן לייזר.

סביבת זמן הריצה חייבת להגדיר את resultsCountOutput כך שיהיה קטן מ-XrRaycastInfoANDROID::maxResults או שווה לו.

שימוש תקין (מרומז)

המבנה 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 שאליו פגע קרן ה-raycast.

המאפיין XrRaycastHitResultANDROID מכיל את הפרטים של היטים של raycast.

הערך של XrRaycastHitResultANDROID::pose עבור פגיעה במישור חייב להיות כזה ש-X ו-Z מקבילים למישור, וציר Y ניצב למישור.

סוג ההיט שניתן לעקוב אחריו

תיאור

XR_TRACKABLE_TYPE_PLANE_ANDROID

מכה במשטחים אופקיים ו/או אנכיים כדי לקבוע את העומק והכיוון הנכונים של נקודה.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

המערכת משתמשת בנתוני עומק מכל הסצנה כדי לקבוע את העומק והכיוון הנכונים של נקודה.

שימוש תקין (מרומז)

קוד לדוגמה ל-raycasting

קוד הדוגמה הבא מראה איך לבצע הקרנות קרן.

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, 2024-10-02 (Kenny Vercaemer)
    • תיאור ראשוני של התוסף

OpenXR™‎ והלוגו של OpenXR הם סימנים מסחריים בבעלות The Khronos Group Inc., והם רשומים כסימנים מסחריים בסין, באיחוד האירופי, ביפן ובבריטניה.