XR_ANDROID_hand_mesh OpenXR एक्सटेंशन

Name String

XR_ANDROID_hand_mesh

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

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

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

704

बदलाव

1

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

OpenXR 1.0

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

2024-09-10

आईपी स्टेटस

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

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

निहाव जैन, Google

केर्न ओवरटर्फ़, Google

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

लेवाना चेन, Google

खास जानकारी

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

इस एक्सटेंशन का मकसद, उपयोगकर्ता के हाथों को उपयोगकर्ता के हिसाब से दिखाने के लिए, मेश के वर्टिक्स और इंडेक्स बफ़र उपलब्ध कराना है. इसका इस्तेमाल, ऑब्स्क्यूरेशन और विज़ुअलाइज़ेशन के लिए किया जा सकता है.

इस एक्सटेंशन का इस्तेमाल, हाथ की गति को ट्रैक करने के अन्य कामों के लिए नहीं किया जाना चाहिए.

  • इंटरैक्शन के लिए, XR_EXT_hand_interaction का इस्तेमाल किया जा सकता है.
  • कंकाल के जोड़ों के लिए, XR_EXT_hand_tracking का इस्तेमाल किया जा सकता है.

हाथ की गतिविधियों को ट्रैक करने से जुड़ा डेटा, संवेदनशील निजी जानकारी हो सकती है. साथ ही, यह निजी निजता और सुरक्षा से जुड़ा होता है. हमारा सुझाव है कि हाथ की गतिविधियों को ट्रैक करने से जुड़ा डेटा इकट्ठा करने या ट्रांसफ़र करने वाले ऐप्लिकेशन, उपयोगकर्ता से इसकी अनुमति हमेशा साफ़ तौर पर लें.

सिस्टम की क्षमता की जांच करना

कोई ऐप्लिकेशन, xrGetSystemProperties को कॉल करते समय, XrSystemHandMeshTrackingPropertiesANDROID स्ट्रक्चर को XrSystemProperties से जोड़कर, यह जांच कर सकता है कि सिस्टम, हाथ की मेश को ट्रैक कर सकता है या नहीं.

typedef struct XrSystemHandMeshTrackingPropertiesANDROID {
  XrStructureType    type;
  void*              next;
  XrBool32           supportsHandMeshTracking;
  XrBool32           supportsTextureUV;
  XrBool32           supportsVertexNormal;
} XrSystemHandMeshTrackingPropertiesANDROID;

पैसे चुकाकर बने सदस्यों के ब्यौरे

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर है. OpenXR के मुख्य वर्शन या इस एक्सटेंशन में, इस तरह के स्ट्रक्चर तय नहीं किए गए हैं.
  • supportsHandMeshTracking एक XrBool32 है, जिससे पता चलता है कि चुना गया XrSystemId, हाथ की मेश ट्रैकिंग की सुविधा के साथ काम करता है या नहीं.
  • supportsTextureUV एक XrBool32 है, जो यह बताता है कि चुना गया XrSystemId, मेश वर्टिसेस के लिए टेक्सचर यूवी के साथ काम करता है या नहीं.
  • supportsVertexNormal एक XrBool32 है, जो यह दिखाता है कि चुना गया XrSystemId, मेश वर्टिक्स के लिए वर्टिक्स नॉर्मल के साथ काम करता है या नहीं.

supportsHandMeshTracking के XR_FALSE होने पर, ऐप्लिकेशन को हाथ की मेश की सुविधाओं का इस्तेमाल करने से बचना चाहिए. इसकी वजह यह है कि इसका मतलब है कि सिस्टम, हाथ की मेश ट्रैकिंग की सुविधा के साथ काम नहीं करता. इस मामले में, xrCreateHandMeshTrackerANDROID XR_ERROR_FEATURE_UNSUPPORTED दिखाएगा.

अगर supportsHandMeshTracking XR_TRUE दिखाता है, तो इसका मतलब है कि सिस्टम में हाथ की मेश ट्रैकिंग की सुविधा काम करती है. ऐप्लिकेशन को हैंडल मेश बफ़र ऐक्सेस करने के लिए, XrHandMeshANDROID::indexCount और XrHandMeshANDROID::vertexCount का इस्तेमाल करना चाहिए. साथ ही, हर फ़्रेम में xrGetHandMeshANDROID को कॉल करते समय, उन्हें अपने रेंडर लूप में फिर से इस्तेमाल करना चाहिए.

अगर supportsTextureUV XR_FALSE दिखाता है, तो इसका मतलब है कि सिस्टम, मेश वर्टिसेस के लिए टेक्सचर यूवी के साथ काम नहीं करता. इसलिए, xrGetHandMeshANDROID को कॉल करने पर, ऐप्लिकेशन को XrHandMeshANDROID::textureUVs NULL मिलेगा.

अगर supportsVertexNormal XR_FALSE दिखाता है, तो इसका मतलब है कि सिस्टम, मेश वर्टिक्स के लिए वर्टिक्स नॉर्मल के साथ काम नहीं करता. इसलिए, xrGetHandMeshANDROID को कॉल करने पर, ऐप्लिकेशन को XrHandMeshANDROID::normals NULL मिलेगा.

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

हाथ के मेश ट्रैकर का हैंडल बनाना

XR_DEFINE_HANDLE(XrHandMeshTrackerANDROID)

XrHandMeshTrackerANDROID हैंडल, हाथ की मेश ट्रैकिंग और उससे जुड़े संसाधनों को मैनेज करने के लिए, हाथ का मेश ट्रैकर दिखाता है.

इस हैंडल का इस्तेमाल, इस एक्सटेंशन के अन्य फ़ंक्शन का इस्तेमाल करके, हाथ के मेश बफ़र को ऐक्सेस करने के लिए किया जा सकता है.

कोई ऐप्लिकेशन, xrCreateHandMeshTrackerANDROID फ़ंक्शन का इस्तेमाल करके, XrHandMeshTrackerANDROID हैंडल बना सकता है. 

XrResult xrCreateHandMeshTrackerANDROID(
    XrSession                                   session,
    const XrHandMeshTrackerCreateInfoANDROID*   createInfo,
    XrHandMeshTrackerANDROID*                   handMeshTracker);

पैरामीटर की जानकारी

  • session एक XrSession है, जिसमें हाथ का मेश ट्रैकर चालू होगा.
  • createInfo, XrHandMeshTrackerCreateInfoANDROID है. इसका इस्तेमाल, हाथ के मेश ट्रैकर की जानकारी देने के लिए किया जाता है.
  • handMeshTracker, XrHandMeshTrackerANDROID हैंडल है.

अगर सिस्टम में हाथ की मेश ट्रैकिंग की सुविधा काम नहीं करती है, तो xrCreateHandMeshTrackerANDROID XR_ERROR_FEATURE_UNSUPPORTED दिखाएगा.

XrHandMeshTrackerANDROID हैंडल के पास, हाथ के मेश ट्रैकिंग के सभी संसाधन होते हैं. हाथ की मेश ट्रैकिंग की सुविधाओं का इस्तेमाल करने के बाद, ऐप्लिकेशन को xrDestroyHandMeshTrackerANDROID फ़ंक्शन का इस्तेमाल करके, हैंडल को नष्ट करना ज़रूरी है.

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

रिटर्न कोड

सफलता

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

प्रोसेस पूरी नहीं हो सकी

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_LIMIT_REACHED

XrHandMeshTrackerCreateInfoANDROID स्ट्रक्चर में, XrHandMeshTrackerANDROID हैंडल बनाने के लिए जानकारी दी गई है. 

typedef struct XrHandMeshTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrHandMeshTrackerCreateInfoANDROID;

पैसे चुकाकर बने सदस्यों के ब्यौरे

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर है. OpenXR के मुख्य वर्शन या इस एक्सटेंशन में, इस तरह के स्ट्रक्चर तय नहीं किए गए हैं.

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

xrDestroyHandMeshTrackerANDROID फ़ंक्शन, हाथ की मेश ट्रैकिंग की सुविधाओं का इस्तेमाल करने के बाद, handMeshTracker और उससे जुड़े संसाधनों को रिलीज़ कर देता है. 

XrResult xrDestroyHandMeshTrackerANDROID(
    XrHandMeshTrackerANDROID handMeshTracker);

पैरामीटर की जानकारी

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

थ्रेड की सुरक्षा

  • handMeshTracker और किसी भी चाइल्ड हैंडल का ऐक्सेस, बाहरी तौर पर सिंक होना ज़रूरी है

रिटर्न कोड

सफलता

  • XR_SUCCESS

प्रोसेस पूरी नहीं हो सकी

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

हाथ के मेश ढूंढना

ऐप्लिकेशन, किसी तय टाइमस्टैंप पर हाथ का मेश पाने के लिए, xrGetHandMeshANDROID फ़ंक्शन का इस्तेमाल कर सकता है. xrGetHandMeshANDROID को कॉल करते समय, हाथ के मेश के वर्टिसेस की पोज़िशन और नॉर्मल को XrHandMeshGetInfoANDROID::baseSpace से तय किए गए स्पेस में दिखाया जाता है.

XrResult xrGetHandMeshANDROID(
    XrHandMeshTrackerANDROID                    handMeshTracker,
    const XrHandMeshGetInfoANDROID*             getInfo,
    XrHandTrackingMeshesANDROID*                handMeshes);

पैरामीटर की जानकारी

  • handMeshTracker, XrHandMeshTrackerANDROID हैंडल है, जिसे पहले xrCreateHandMeshTrackerANDROID की मदद से बनाया गया था.
  • getInfo एक XrHandMeshGetInfoANDROID स्ट्रक्चर है. इसमें, हाथ के मेश डेटा के बारे में क्वेरी करने के लिए जानकारी होती है.
  • handMeshes, XrHandTrackingMeshesANDROID स्ट्रक्चर का पॉइंटर है. इसमें हाथ के मेश डेटा को पॉप्युलेट किया जाएगा.

ऐप्लिकेशन, xrGetHandMeshANDROID फ़ंक्शन का इस्तेमाल करके, रनटाइम से जनरेट किए गए हाथ के मेश बफ़र को ऐक्सेस कर सकता है.

xrGetHandMeshANDROID को पहली बार कॉल करने से पहले, ऐप्लिकेशन को सेशन के दौरान कम से कम एक बार xrBeginFrame को कॉल करना चाहिए.

ऐप्लिकेशन को हाथ के मेश बफ़र को ऐक्सेस करने के लिए, XrHandMeshANDROID::indexCount और XrHandMeshANDROID::vertexCount का इस्तेमाल करना चाहिए. साथ ही, हर फ़्रेम में xrGetHandMeshANDROID को कॉल करते समय, अपने रेंडर लूप में उनका फिर से इस्तेमाल करना चाहिए.

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

रिटर्न कोड

सफलता

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

प्रोसेस पूरी नहीं हो सकी

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_TIME_INVALID

XrHandMeshGetInfoANDROID, हैंडमैश डेटा पाने के लिए ज़रूरी जानकारी के बारे में बताता है. 

typedef struct XrHandMeshGetInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
} XrHandMeshGetInfoANDROID;

पैसे चुकाकर बने सदस्यों के ब्यौरे

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर है. OpenXR के मुख्य वर्शन या इस एक्सटेंशन में, इस तरह के स्ट्रक्चर तय नहीं किए गए हैं.
  • baseSpace एक XrSpace है, जो रेफ़रंस स्पेस तय करता है. इसमें time पर मौजूद वर्टिसेस के लिए ट्रांसफ़ॉर्म की जगह तय की जाती है.
  • time, XrTime है. इससे उस समय के बारे में पता चलता है जब ऐप्लिकेशन को हाथ के मेश से क्वेरी करनी है.

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

XrHandTrackingMeshesANDROID स्ट्रक्चर में, दोनों हाथों का मेश डेटा होता है. 

typedef struct XrHandTrackingMeshesANDROID {
    XrStructureType      type;
    void*                next;
    XrHandMeshANDROID    leftHandMesh;
    XrHandMeshANDROID    rightHandMesh;
} XrHandTrackingMeshesANDROID;

पैसे चुकाकर बने सदस्यों के ब्यौरे

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर है. OpenXR के मुख्य वर्शन या इस एक्सटेंशन में, इस तरह के स्ट्रक्चर तय नहीं किए गए हैं.
  • leftHandMesh, बाएं हाथ के लिए XrHandMeshANDROID है.
  • rightHandMesh, दाएं हाथ के लिए XrHandMeshANDROID है.

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

XrHandMeshANDROID स्ट्रक्चर में डेटा और बफ़र होते हैं. इनकी मदद से, एक हाथ के लिए xrGetHandMeshANDROID फ़ंक्शन से, हाथ के मेश ट्रैकिंग डेटा को रिसीव किया जा सकता है.

typedef struct XrHandMeshANDROID {
    XrBool32             isActive;
    XrTime               dynamicLastUpdateTime;
    uint32_t             indexCount;
    uint32_t             vertexCount;
    const uint32_t*      indices;
    const XrVector2f*    textureUVs;
    const XrVector3f*    positions;
    const XrVector3f*    normals;
    XrPosef              baseSpaceFromVertexSpace;
} XrHandMeshANDROID;

पैसे चुकाकर बने सदस्यों के ब्यौरे

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर है. OpenXR के मुख्य वर्शन या इस एक्सटेंशन में, इस तरह के स्ट्रक्चर तय नहीं किए गए हैं.
  • isActive एक XrBool32 है, जो यह बताता है कि मौजूदा हाथ का मेश ट्रैकर चालू है या नहीं और मेश डेटा मान्य है या नहीं.
  • dynamicLastUpdateTime वह XrTime है जिसमें वह समय बताया गया है जब डाइनैमिक बफ़र को आखिरी बार अपडेट किया गया था.
  • indexCount एक uint32_t है, जो हैंडमैश के indices की संख्या के तौर पर काम करता है.
  • vertexCount एक uint32_t है, जो हाथ के मेश के positions की संख्या के तौर पर काम करता है. अगर सिस्टम में textureUVs या normals काम करते हैं, तो इनके लिए भी इसका इस्तेमाल किया जा सकता है.
  • indices, uint32_t का एक कलेक्शन है. इसमें घड़ी की विपरीत दिशा में घुमाने पर, त्रिभुजों के लिए मेश इंडेक्स दिखते हैं. चुनी गई वैल्यू की संख्या indexCount है.
  • textureUVs, NULL या XrVector2f का ऐरे होता है, जो वर्टिक्स टेक्सचर निर्देशांक दिखाता है. पॉइंट की गई वैल्यू की संख्या vertexCount है.
  • positions, XrVector3f का एक कलेक्शन है, जो baseSpaceFromVertexSpace में वर्टिक्स की पोज़िशन दिखाता है. पॉइंट की गई वैल्यू की संख्या vertexCount है.
  • normals, NULL या XrVector3f का एक कलेक्शन है, जो baseSpaceFromVertexSpace में वर्टिकस के सामान्य वैल्यू दिखाता है. पॉइंट की गई वैल्यू की संख्या vertexCount है.
  • baseSpaceFromVertexSpace, xrGetHandMeshANDROID को कॉल करते समय, XrHandMeshGetInfoANDROID::baseSpace में मौजूद वर्टिक्स XrSpace है. ऐप्लिकेशन, रेंडरिंग के दौरान मेश वर्टिसेस और नॉर्मल के कोऑर्डिनेट स्पेस को बदलने के लिए, इसका इस्तेमाल कर सकते हैं.

हाथ के मेश को ट्रैंगल की सूचियों में दिखाया जाता है. साथ ही, हाथ के बाहर से देखने पर, हर ट्रैंगल के वर्टिसेस, घड़ी की सुई के उलट दिशा में होते हैं.

अगर isActive की वैल्यू XR_FALSE है, तो इसका मतलब है कि हाथ को सक्रिय रूप से ट्रैक नहीं किया जा रहा है. उदाहरण के लिए, हाथ सेंसर की रेंज से बाहर है, इनपुट फ़ोकस को ऐप्लिकेशन से हटा दिया गया है या ऐप्लिकेशन के पास हाथ की ट्रैकिंग का डेटा ऐक्सेस करने की अनुमतियां नहीं हैं.

अगर isActive की वैल्यू XR_TRUE है, तो indices और positions में दिखाए गए हाथ की ट्रैकिंग मेश को XrHandMeshGetInfoANDROID::time के नए डेटा पर अपडेट किया जाता है. इसमें textureUVs और normals भी शामिल हैं, बशर्ते सिस्टम में इनका इस्तेमाल किया जा सकता हो. XrHandMeshGetInfoANDROID::time का डेटा, xrGetHandMeshANDROID फ़ंक्शन को दिया जाता है.

XrHandMeshANDROID में लौटाई गई हैंड मेश बफ़र से मेमोरी का ऐक्सेस, रनटाइम के पास होता है और उसे ऐप्लिकेशन के साथ शेयर किया जाता है. XrHandMeshTrackerANDROID हैंडल मान्य होने पर, xrBeginFrame को अगले कॉल करने तक, मेमोरी को किसी भी थ्रेड से ऐक्सेस किया जा सकता है.

  • indices और textureUVs से मिली वैल्यू डाइनैमिक नहीं होतीं
  • positions और normals से दिखाए गए पॉइंटर और वैल्यू, डाइनैमिक होती हैं. ये दोनों xrBeginFrame को कॉल करने के बीच बदल सकती हैं. ऐप्लिकेशन, dynamicLastUpdateTime का इस्तेमाल करके यह जांच सकता है कि पिछले फ़्रेम से वैल्यू में बदलाव हुआ है या नहीं. साथ ही, अगर कोई बदलाव नहीं हुआ है, तो डेटा को बार-बार प्रोसेस करने से बचाया जा सकता है.

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

  • XrHandMeshANDROID का इस्तेमाल करने से पहले, XR_ANDROID_hand_mesh एक्सटेंशन को चालू करना ज़रूरी है
  • indices, मान्य uint32_t वैल्यू का पॉइंटर होना चाहिए
  • textureUVs यह किसी मान्य XrVector2f स्ट्रक्चर का पॉइंटर होना चाहिए
  • positions यह किसी मान्य XrVector3f स्ट्रक्चर का पॉइंटर होना चाहिए
  • normals यह किसी मान्य XrVector3f स्ट्रक्चर का पॉइंटर होना चाहिए

हाथ की मेश ट्रैकिंग के लिए कोड का उदाहरण

यहां दिए गए उदाहरण में, रेंडर करने के लिए हाथ के मेश बफ़र को ऐक्सेस करने का तरीका बताया गया है.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup.
XrSpace appPlaySpace; // Created at app startup.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateHandMeshTrackerANDROID xrCreateHandMeshTrackerANDROID; // previously initialized
PFN_xrDestroyHandMeshTrackerANDROID xrDestroyHandMeshTrackerANDROID; // previously initialized
PFN_xrGetHandMeshANDROID xrGetHandMeshANDROID; // previously initialized

// Inspect system capability
XrSystemHandMeshTrackingPropertiesANDROID handMeshTrackingProps = {
  .type = XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &handMeshTrackingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!handMeshTrackingProps.supportsHandMeshTracking) {
  // hand mesh tracking is not supported.
  return;
}

XrHandMeshTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
};
XrHandMeshTrackerANDROID handMeshTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateHandMeshTrackerANDROID(
    session, &trackerCreateInfo, &handMeshTracker));
// app update loop
while (true) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;

    // ...
    XrHandMeshGetInfoANDROID getInfo = {
        .type = XR_TYPE_HAND_MESH_GET_INFO_ANDROID,
        .baseSpace = appPlaySpace,
        .time = time,
    };
    XrHandTrackingMeshesANDROID handMeshes = {
        .type = XR_TYPE_HAND_TRACKING_MESHES_ANDROID
    };
    CHK_XR(xrGetHandMeshANDROID(handMeshTracker, &getInfo, &handMeshes));

    if (handMeshes.leftHandMesh.isActive) {
        // access vertex/index buffers for rendering.
    }

    // ...
    // Finish frame loop
    // ...
}

CHECK_XR(xrDestroyHandMeshTracker(handMeshTracker));

नए ऑब्जेक्ट टाइप

नई Enum Constant

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

  • XR_OBJECT_TYPE_HAND_MESH_TRACKER_ANDROID

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

  • XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_HAND_MESH_GET_INFO_ANDROID
  • XR_TYPE_HAND_TRACKING_MESHES_ANDROID

नए Enums

नए स्ट्रक्चर

नए फ़ंक्शन

समस्याएं

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

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