XR_ANDROID_raycast OpenXR एक्सटेंशन

Name String

XR_ANDROID_raycast

एक्सटेंशन टाइप

इंस्टेंस एक्सटेंशन

रजिस्टर किया गया एक्सटेंशन नंबर

464

बदलाव

1

एक्सटेंशन और वर्शन की डिपेंडेंसी

XR_ANDROID_trackables

पिछली बार बदलाव करने की तारीख

2024-10-02

आईपी स्टेटस

आईपी पर कोई दावा नहीं किया गया है.

योगदान देने वाले

स्पेंसर क्विन, Google

निहाव जैन, Google

जॉन पर्सी, Google

जेरेड फ़ाइंडर, Google

लेवाना चेन, Google

केनी वर्कमेयर, Google

खास जानकारी

इस एक्सटेंशन की मदद से, ऐप्लिकेशन आस-पास मौजूद ट्रैक किए जा सकने वाले आइटम के लिए रेकास्ट कर सकता है. रेकास्ट, ऐसे ऑब्जेक्ट का पता लगाने में मददगार हो सकते हैं जिनसे किरणें टकराती हैं. उदाहरण के लिए:

  • यह तय करने के लिए कि किसी तैरते हुए ऑब्जेक्ट को छोड़ने पर वह कहां गिरेगा, वर्टिकल रेकास्ट का इस्तेमाल करें.
  • फ़ोरवर्ड-फ़ेसिंग रेकास्ट का इस्तेमाल करके, यह पता लगाने के लिए कि उपयोगकर्ता कहां देख रहा है.

रेकास्ट की सुविधाओं के बारे में क्वेरी

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 है, तो trackableTypes NULL हो सकता है.
  • ज़रूरी trackableTypes साइज़ को वापस पाने के बारे में पूरी जानकारी के लिए, बफ़र साइज़ पैरामीटर सेक्शन देखें.

xrEnumerateRaycastSupportedTrackableTypesANDROID, ट्रैक किए जा सकने वाले उन टाइप की सूची बनाता है जो मौजूदा सेशन के हिसाब से रेकास्टिंग की सुविधा के साथ काम करते हैं.

मान्य इस्तेमाल (इंप्लिसिट)

  • xrEnumerateRaycastSupportedTrackableTypesANDROID को कॉल करने से पहले, XR_ANDROID_raycast एक्सटेंशन चालू होना चाहिए
  • instance यह एक मान्य XrInstance हैंडल होना चाहिए
  • trackableTypeCountOutput, uint32_t वैल्यू का पॉइंटर होना चाहिए
  • अगर trackableTypeCapacityInput, 0 नहीं है, तो trackableTypes trackableTypeCapacityInputXrTrackableTypeANDROID वैल्यू के ऐरे का पॉइंटर होना चाहिए

रिटर्न कोड

सफलता

  • 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 वेक्टर के साथ, सबसे नज़दीक से सबसे दूर के क्रम में दिखाना चाहिए.
  • अगर XrRaycastInfoANDROID::trackers में मौजूद XrTrackableTrackerANDROID हैंडल से जुड़े ट्रैक किए जा सकने वाले टाइप की जानकारी, xrEnumerateRaycastSupportedTrackableTypesANDROID से नहीं दी जाती है, तो रनटाइम को XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID देना चाहिए.

मान्य इस्तेमाल (इंप्लिसिट)

  • xrRaycastANDROID को कॉल करने से पहले, XR_ANDROID_raycast एक्सटेंशन चालू होना चाहिए
  • 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, trackers कलेक्शन में मौजूद uint32_t की संख्या है.
  • trackers, XrTrackableTrackerANDROID का कलेक्शन है. इस कलेक्शन के आधार पर, कैस्ट की गई रे का जांच की जानी चाहिए.
  • origin वह XrVector3f है जिससे किरण को कास्ट किया जाता है.
  • trajectory वह XrVector3f है जिस पर किरण को टारगेट किया गया है.
  • space वह XrSpace है जिसमें किरण को डाला जाता है.
  • time वह XrTime है जिस पर किरण डाली जाती है.

XrRaycastInfoANDROID स्ट्रक्चर से, रे को कास्ट करने के बारे में पता चलता है.

  • XrRaycastInfoANDROID::trackers कलेक्शन में, अलग-अलग तरह के ट्रैकर हो सकते हैं.
  • XrRaycastInfoANDROID::trackers कलेक्शन में, एक ही तरह के कई ट्रैकर न होने चाहिए. ऐसा न होने पर, रनटाइम XR_ERROR_VALIDATION_FAILURE दिखाएगा.

मान्य इस्तेमाल (इंप्लिसिट)

  • XrRaycastInfoANDROID का इस्तेमाल करने से पहले, XR_ANDROID_raycast एक्सटेंशन को चालू करना ज़रूरी है
  • 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 की संख्या काफ़ी नहीं है, तो resultsCountOutput ज़रूरी क्षमता का पॉइंटर है.
  • results, XrRaycastHitResultANDROID स्ट्रक्चर के ऐरे का पॉइंटर है. अगर resultsCapacityInput 0 है, तो यह NULL हो सकता है.
  • ज़रूरी 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 है जिस पर रेकास्ट हिट हुआ.

XrRaycastHitResultANDROID में, रेकास्ट हिट की जानकारी होती है.

प्लेन से टकराने पर, XrRaycastHitResultANDROID::pose का ऐसा होना ज़रूरी है कि X और Z, प्लेन के समानांतर हों और Y ऐक्सिस, प्लेन के लिए सामान्य हो.

ट्रैक किए जा सकने वाले हिट का टाइप

ब्यौरा

XR_TRACKABLE_TYPE_PLANE_ANDROID

किसी पॉइंट की सही गहराई और ओरिएंटेशन का पता लगाने के लिए, हॉरिज़ॉन्टल और/या वर्टिकल सतहों को हिट करता है.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

किसी पॉइंट की सही गहराई और ओरिएंटेशन का पता लगाने के लिए, पूरे सीन की डेप्थ की जानकारी का इस्तेमाल करता है.

मान्य इस्तेमाल (इंप्लिसिट)

  • XrRaycastHitResultANDROID का इस्तेमाल करने से पहले, XR_ANDROID_raycast एक्सटेंशन को चालू करना ज़रूरी है
  • 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]
}

नई Enum Constant

XrStructureType एनोटेशन को इनके साथ जोड़ा गया है:

  • XR_TYPE_RAYCAST_INFO_ANDROID
  • XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

नए स्ट्रक्चर

नए फ़ंक्शन

समस्याएं

वर्शन का इतिहास

  • पहला बदलाव, 02-10-2024 (केनी वर्कमेयर)
    • एक्सटेंशन के बारे में शुरुआती जानकारी