XR_ANDROID_spatial_annotation_tracking

Name String

XR_ANDROID_spatial_annotation_tracking

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

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

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

795

बदलाव

1

पुष्टि की स्थिति

पुष्टि नहीं की गई

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

XR_EXT_spatial_entity
और
XR_EXT_spatial_image_tracking

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

2026-01-12

आईपी स्टेटस

आईपी से जुड़े किसी भी दावे की जानकारी नहीं है.

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

लेवाना चेन, Google
क्रिस्टोफ़र फ़ेल, Google
मार्टिन सुंडरमेयर, Google
डेविड जोसेफ़ टैन, Google
जेरेड फ़ाइंडर, Google
निहाव जैन, Google

खास जानकारी

यह एक्सटेंशन, XR_EXT_spatial_entity एक्सटेंशन के लिए एनोटेशन ट्रैकिंग की सुविधा देता है. इससे सीन में अलग-अलग एनोटेशन को ट्रैक किया जा सकता है. इससे ऐप्लिकेशन, रनटाइम रेफ़रंस के ज़रिए तय की गई फ़िज़िकल या वर्चुअल चीज़ों पर ओवरले डाल पाते हैं.

यह एक्सटेंशन, "क्वाड" नाम का एक बेसिक एनोटेशन टाइप उपलब्ध कराता है. यह एक ऐसा बहुभुज होता है जिसकी चार भुजाएं होती हैं. जैसे, कॉन्वेक्स क्वाड्रीलैटरल. यह रनटाइम रेफ़रंस में सामान्य 2D बाउंडिंग बॉक्स को दिखाता है. ट्रैक किए गए क्वाड एनोटेशन को एक स्पेशल एंटिटी के तौर पर दिखाया जाता है. इसमें ये कॉम्पोनेंट होते हैं:

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

आम तौर पर, ऐप्लिकेशन इन पैटर्न में स्पैटियल एनोटेशन ट्रैकिंग एक्सटेंशन का इस्तेमाल कर सकते हैं:

  • कोई ऐप्लिकेशन सबसे पहले XrSpatialReferenceCacheANDROID का हैंडल बनाता है. यह दिए गए सोर्स से रनटाइम रेफ़रंस रिकॉर्ड करना शुरू करता है.
  • इसके बाद, ऐप्लिकेशन XrSpatialReferenceImageEXT का रनटाइम रेफ़रंस कैप्चर करता है. साथ ही, रेफ़रंस कैश के समय के दौरान रेफ़रंस में मनचाहा एनोटेशन तय करता है.
  • इसके बाद, ऐप्लिकेशन XrSpatialCapabilityConfigurationAnnotationTrackingANDROID से मिले XrSpatialReferenceImageEXT के आधार पर, XrSpatialContextEXT हैंडल बनाता है .
  • ऐप्लिकेशन, XrSpatialReferenceCacheANDROID हैंडल को डिस्ट्रॉय कर सकता है, ताकि मेमोरी के इस्तेमाल को कम करने के लिए, रिकॉर्डिंग रनटाइम रेफ़रंस को रोका जा सके. इसके अलावा, वह XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID इवेंट का इंतज़ार कर सकता है, ताकि पुष्टि की जा सके कि इनिशियलाइज़ेशन का नतीजा सही है.
  • इसके बाद, ऐप्लिकेशन XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID इवेंट को पुल करता है, ताकि एनोटेशन के शुरू होने के नतीजे की पुष्टि की जा सके.
  • अगर शुरू करने की प्रोसेस पूरी हो जाती है, तो ऐप्लिकेशन, एनोटेशन को ट्रैक करने के लिए XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT इवेंट को पुल कर सकता है.
  • अगर शुरू नहीं किया जा सका, तो ऐप्लिकेशन, इवेंट में मिले गड़बड़ी कोड का इस्तेमाल करके, गड़बड़ी की वजह का पता लगा सकता है. साथ ही, नए एनोटेशन को शुरू करने के लिए, मौजूदा XrSpatialContextEXT हैंडल को बंद कर सकता है.
  • शुरू करने के नतीजे से कोई फ़र्क़ नहीं पड़ता. इवेंट मिलने के बाद, ऐप्लिकेशन मेमोरी के इस्तेमाल को कम करने के लिए, इमेज बफ़र को रिलीज़ कर सकता है.
  • यह ऐप्लिकेशन, जगह के हिसाब से मौजूद इकाइयों के ऐक्सेस पैटर्न के मुताबिक एनोटेशन ढूंढता है और उनसे जुड़ी क्वेरी करता है.
  • यह ऐप्लिकेशन, मान्य XrSpatialReferenceCacheANDROID के समयसीमा के दौरान, नए रेफ़रंस में एनोटेशन को ट्रैक करने के लिए, अतिरिक्त XrSpatialContextEXT हैंडल बना सकता है .
  • ऐप्लिकेशन, रनटाइम के दौरान पता लगाए जा सकने वाले और ट्रैक किए जा सकने वाले एनोटेशन के सेट को कम करने के लिए, XrSpatialContextEXT हैंडल को नष्ट कर सकता है.

रनटाइम से जुड़ी सहायता

किसी रनटाइम को एनोटेशन ट्रैकिंग की सुविधा के लिए, xrEnumerateSpatialCapabilitiesEXT का इस्तेमाल करके, यह जानकारी ज़रूर देनी चाहिए:

  • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

जब रनटाइम में एनोटेशन ट्रैकिंग की सुविधा काम करती है, तब:

  • इसमें कम से कम एक एनोटेशन कॉम्पोनेंट होना ज़रूरी है. इसके लिए, xrEnumerateSpatialCapabilityComponentTypesEXT के ज़रिए, इस्तेमाल किए जा सकने वाले एनोटेशन कॉम्पोनेंट की सूची बनाएं.
  • इसमें कम से कम एक XrSpatialReferenceImageFormatEXT का इस्तेमाल किया जाना ज़रूरी है. इसके लिए, xrEnumerateSpatialReferenceImageFormatsEXT के ज़रिए, इस्तेमाल किए जा सकने वाले रेफ़रंस फ़ॉर्मैट की सूची बनाएं और capability को XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID पर सेट करें.
  • इसमें XrSpatialAnnotationReferenceSourceANDROID का कम से कम एक रेफ़रंस सोर्स इस्तेमाल किया जा सकता है. इसके लिए, capability को XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID पर सेट करके, xrEnumerateSpatialAnnotationReferenceSourcesANDROID के ज़रिए इस्तेमाल किए जा सकने वाले रेफ़रंस सोर्स की सूची बनाएं.

xrEnumerateSpatialAnnotationReferenceSourcesANDROID फ़ंक्शन को इस तरह से तय किया गया है:

XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    sourceCapacityInput,
    uint32_t*                                   sourceCountOutput,
    XrSpatialAnnotationReferenceSourceANDROID*  sources);

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

  • instance, XrInstance का हैंडल है .
  • systemId वह XrSystemId है जिसके रेफ़रंस सोर्स की गिनती की जाएगी.
  • capability, XrSpatialCapabilityEXT है. इसके लिए, रेफ़रंस सोर्स की गिनती की जाएगी.
  • sourceCapacityInput, sources ऐरे की क्षमता है. अगर आपको ज़रूरी क्षमता वापस पाने का अनुरोध करना है, तो इसे 0 पर सेट करें.
  • sourceCountOutput, स्रोतों की संख्या है. अगर sourceCapacityInput अपर्याप्त है, तो यह ज़रूरी क्षमता है.
  • sources, XrSpatialAnnotationReferenceSourceANDROID का कलेक्शन है . अगर sourceCapacityInput की वैल्यू 0 है, तो इसकी वैल्यू NULL हो सकती है.
  • ज़रूरी sources का साइज़ वापस पाने के बारे में ज़्यादा जानकारी के लिए, बफ़र साइज़ के पैरामीटर सेक्शन देखें.

ऐप्लिकेशन, xrEnumerateSpatialAnnotationReferenceSourcesANDROID का इस्तेमाल करके, किसी दिए गए XrSystemId के साथ काम करने वाले रेफ़रंस सोर्स की सूची बना सकता है .

रनटाइम को उन रेफ़रंस सोर्स की गिनती नहीं करनी चाहिए जिनके एक्सटेंशन के लिए instance चालू नहीं है .

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

  • XR_ANDROID_spatial_annotation_tracking एक्सटेंशन को xrEnumerateSpatialAnnotationReferenceSourcesANDROID को कॉल करने से पहले चालू करना होगा
  • instance, XrInstance का मान्य हैंडल होना चाहिए
  • capability XrSpatialCapabilityEXT की मान्य वैल्यू होनी चाहिए
  • sourceCountOutput, uint32_t वैल्यू का पॉइंटर होना चाहिए
  • अगर sourceCapacityInput, 0 नहीं है, तो sources, sourceCapacityInput XrSpatialAnnotationReferenceSourceANDROID वैल्यू के ऐरे का पॉइंटर होना चाहिए

रिटर्न कोड

सफल

  • XR_SUCCESS

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

typedef enum XrSpatialAnnotationReferenceSourceANDROID {
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationReferenceSourceANDROID;

XrSpatialAnnotationReferenceSourceANDROID इन्यूमरेशन, रेफ़रंस के सोर्स के बारे में बताता है. यह रेफ़रंस, एनोटेशन के लिए मेटाडेटा उपलब्ध कराता है.

इन एनम का मतलब यह है:

Enum की जानकारी

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

रेफ़रंस इमेज, Android Camera API से मिली ऐसी इमेज होती है जिसे काटा नहीं गया होता. उदाहरण के लिए, Camera2 CameraDevice से जुड़े ImageReader से मिली इमेज या CameraX से जुड़े ImageAnalysis से मिली ImageProxy. आम तौर पर, यह सामने की ओर मौजूद RGB कैमरों में से एक होता है.

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID

रेफ़रंस इमेज, Android MediaProjection API से मिली ऐसी इमेज होती है जिसे काटा नहीं गया होता. उदाहरण के लिए, MediaProjection वर्चुअल डिसप्ले से जुड़े ImageReader से मिली इमेज. इसमें वर्चुअल और असल कॉन्टेंट शामिल हो सकता है.

XrSystemSpatialAnnotationPropertiesANDROID स्ट्रक्चर को इस तरह परिभाषित किया गया है:

typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           referenceCacheTimespan;
    uint32_t           maxReferencePixelWidth;
    uint32_t           maxReferencePixelHeight;
    uint32_t           maxReferenceCount;
    uint32_t           maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;

सदस्यों के बारे में जानकारी

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL होता है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर होता है.
  • referenceCacheTimespan से, मान्य XrSpatialReferenceCacheANDROID हैंडल के लिए, सेकंड में समयसीमा का पता चलता है.
  • maxReferencePixelWidth से, रेफ़रंस इमेज के किनारे की ज़्यादा से ज़्यादा चौड़ाई पिक्सल में दिखती है.
  • maxReferencePixelHeight से, रेफ़रंस इमेज के किनारे की ज़्यादा से ज़्यादा ऊंचाई पिक्सल में दिखती है.
  • maxReferenceCount से पता चलता है कि एक साथ ज़्यादा से ज़्यादा कितनी रेफ़रंस इमेज असाइन की जा सकती हैं.
  • maxAnnotationCount से पता चलता है कि एक साथ ज़्यादा से ज़्यादा कितने एनोटेशन ट्रैक किए जा सकते हैं.

जब रनटाइम में एनोटेशन ट्रैकिंग की सुविधा काम करती है, तब कोई ऐप्लिकेशन xrGetSystemProperties को कॉल करते समय, XrSystemSpatialAnnotationPropertiesANDROID स्ट्रक्चर को XrSystemProperties से जोड़कर, सिस्टम की ज़रूरी प्रॉपर्टी की जांच कर सकता है .

अगर XrSpatialReferenceImageEXT :: width, XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference से ज़्यादा है, तो xrCreateSpatialContextAsyncEXT को कॉल करते समय, रनटाइम को XR_ERROR_VALIDATION_FAILURE ज़रूर लौटाना चाहिए.maxReferencePixelWidth

अगर XrSpatialReferenceImageEXT :: height, XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference से ज़्यादा है, तो xrCreateSpatialContextAsyncEXT को कॉल करते समय, रनटाइम को XR_ERROR_VALIDATION_FAILURE ज़रूर लौटाना चाहिए.maxReferencePixelHeight

अगर XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time, XrSpatialReferenceCacheANDROID :: cache के टाइमस्पैन से बाहर है, तो रनटाइम को xrCreateSpatialContextAsyncEXT को कॉल करते समय XR_ERROR_TIME_INVALID जवाब ज़रूर देना चाहिए . ऐप्लिकेशन, XrSpatialReferenceCacheANDROID के टाइमस्पैन के दौरान, नए रेफ़रंस के साथ XrSpatialContextEXT हैंडल को फिर से बना सकता है .

अगर रेफ़रंस इमेज की संख्या, तय सीमा maxReferenceCount से ज़्यादा है, तो रनटाइम को XR_ERROR_LIMIT_REACHED दिखाना ज़रूरी है. साथ ही, XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult के ज़रिए, यह बताना होगा कि शुरू नहीं किया जा सका. ऐप्लिकेशन, XrSpatialContextEXT हैंडल को डिस्ट्रॉय कर सकता है. साथ ही, शुरू होने की प्रोसेस पूरी होने के बाद, फिर से कोशिश कर सकता है.

अगर चालू एनोटेशन की संख्या maxAnnotationCount से ज़्यादा है, तो xrCreateSpatialContextAsyncEXT को कॉल करते समय, रनटाइम को XR_ERROR_VALIDATION_FAILURE ज़रूर दिखाना चाहिए .

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

रनटाइम रेफ़रंस कैश मेमोरी

XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)

XrSpatialReferenceCacheANDROID हैंडल, किसी दिए गए सोर्स से रिकॉर्ड किए गए रनटाइम रेफ़रंस के कैश मेमोरी को दिखाता है.

xrCreateSpatialReferenceCacheAsyncANDROID फ़ंक्शन को इस तरह से परिभाषित किया गया है:

XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
    XrSession                                   session,
    const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

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

  • session एक XrSession है, जिसमें रेफ़रंस कैश मेमोरी चालू होगी.
  • createInfo, XrSpatialReferenceCacheCreateInfoANDROID का पॉइंटर है. इसका इस्तेमाल, रेफ़रंस कैश मेमोरी के पैरामीटर तय करने के लिए किया जाता है.
  • future, XrFutureEXT के आउटपुट हैंडल का पॉइंटर है .

ऐप्लिकेशन, xrCreateSpatialReferenceCacheAsyncANDROID को कॉल करके, XrSpatialReferenceCacheANDROID हैंडल बना सकता है . ट्रैकिंग सेवाओं को शुरू करने में रनटाइम को कुछ समय लग सकता है. इसके बाद, ऐप्लिकेशन इस एसिंक्रोनस ऑपरेशन के पूरा होने की जांच करने के लिए, xrCreateSpatialReferenceCacheCompleteANDROID को बार-बार कॉल कर सकता है.

अगर xrEnumerateSpatialCapabilitiesEXT में XrSpatialReferenceCacheCreateInfoANDROID :: capability शामिल नहीं है, तो रनटाइम को XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT दिखाना ज़रूरी है .

अगर दी गई सुविधा के लिए, xrEnumerateSpatialAnnotationReferenceSourcesANDROID में XrSpatialReferenceCacheCreateInfoANDROID :: source शामिल नहीं है, तो रनटाइम को XR_ERROR_FEATURE_UNSUPPORTED ज़रूर दिखाना चाहिए.

ऐप्लिकेशन, किसी सुविधा के लिए हर सोर्स से सिर्फ़ एक हैंडल बना सकता है. ऐसा न होने पर, रनटाइम को XR_ERROR_LIMIT_REACHED दिखाना ज़रूरी है .

इसके बाद, ऐप्लिकेशन XrSpatialReferenceCacheANDROID हैंडल के टाइमस्पैन के दौरान, रनटाइम रेफ़रंस कैप्चर कर सकता है, ताकि नया XrSpatialContextEXT हैंडल कॉन्फ़िगर किया जा सके.

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

  • xrCreateSpatialReferenceCacheAsyncANDROID को कॉल करने से पहले, XR_ANDROID_spatial_annotation_tracking एक्सटेंशन को चालू करना ज़रूरी है
  • session, XrSession का एक मान्य हैंडल होना चाहिए
  • createInfo XrSpatialReferenceCacheCreateInfoANDROID स्ट्रक्चर का मान्य पॉइंटर होना चाहिए
  • future, XrFutureEXT वैल्यू का पॉइंटर होना चाहिए

रिटर्न कोड

सफल

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

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

XrSpatialReferenceCacheCreateInfoANDROID स्ट्रक्चर को इस तरह से परिभाषित किया गया है:

typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialCapabilityEXT                       capability;
    XrSpatialAnnotationReferenceSourceANDROID    source;
} XrSpatialReferenceCacheCreateInfoANDROID;

सदस्यों के बारे में जानकारी

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL होता है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर होता है. इस तरह के स्ट्रक्चर, OpenXR के मुख्य स्पेसिफ़िकेशन या इस एक्सटेंशन में तय नहीं किए गए हैं.
  • capability एक XrSpatialCapabilityEXT है. इससे पता चलता है कि रेफ़रंस कैश किस सुविधा के लिए बनाई गई है.
  • source, XrSpatialAnnotationReferenceSourceANDROID है. यह रेफ़रंस कैश मेमोरी के सोर्स के बारे में बताता है.

XrSpatialReferenceCacheCreateInfoANDROID स्ट्रक्चर, XrSpatialReferenceCacheANDROID हैंडल बनाने के लिए ज़रूरी जानकारी के बारे में बताता है.

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

xrCreateSpatialReferenceCacheCompleteANDROID फ़ंक्शन को इस तरह से परिभाषित किया गया है:

XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialReferenceCacheCompletionANDROID* completion);

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

ऐप्लिकेशन, xrCreateSpatialReferenceCacheAsyncANDROID से शुरू किए गए एसिंक्रोनस ऑपरेशन के पूरा होने का इंतज़ार करने के लिए, xrCreateSpatialReferenceCacheCompleteANDROID को कॉल कर सकता है .

अगर future तैयार नहीं है, तो रनटाइम को XR_ERROR_FUTURE_PENDING_EXT दिखाना ज़रूरी है. अगर future पहले ही पूरा हो चुका है या रद्द कर दिया गया है, तो रनटाइम को XR_ERROR_FUTURE_INVALID_EXT वैल्यू ज़रूर दिखानी चाहिए.

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

रिटर्न कोड

सफल

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

XrCreateSpatialReferenceCacheCompletionANDROID स्ट्रक्चर को इस तरह परिभाषित किया गया है:

typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
    XrStructureType                   type;
    void*                             next;
    XrResult                          futureResult;
    XrSpatialReferenceCacheANDROID    referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;

सदस्यों के बारे में जानकारी

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL होता है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर होता है. इस तरह के स्ट्रक्चर, OpenXR के मुख्य स्पेसिफ़िकेशन या इस एक्सटेंशन में तय नहीं किए गए हैं.
  • futureResult, रेफ़रंस कैश मेमोरी बनाने की कार्रवाई का XrResult है.
  • referenceCache, ऑपरेशन पूरा होने पर XrSpatialReferenceCacheANDROID हैंडल होता है.

आने वाले समय में इस्तेमाल किए जाने वाले रिटर्न कोड

futureResult वैल्यू:

सफल

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

अगर futureResult एक सक्सेस कोड है, तो रनटाइम को एक मान्य referenceCache हैंडल ज़रूर लौटाना चाहिए. अगर referenceCache मान्य है, तो यह सिर्फ़ xrCreateSpatialReferenceCacheAsyncANDROID :: session के लाइफ़टाइम के दौरान या ऐप्लिकेशन के xrDestroySpatialReferenceCacheANDROID की मदद से हैंडल को डिस्ट्रॉय करने तक मान्य रहता है. इनमें से जो भी पहले होगा.

referenceCache मान्य होने पर, यह XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan में कैश मेमोरी को रिकॉर्ड करता है .

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

xrDestroySpatialReferenceCacheANDROID फ़ंक्शन को इस तरह से परिभाषित किया गया है:

XrResult xrDestroySpatialReferenceCacheANDROID(
    XrSpatialReferenceCacheANDROID              cacheHandle);

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

स्पेशल कॉन्टेक्स्ट बनाने का काम पूरा होने के बाद, ऐप्लिकेशन cacheHandle हैंडल और उससे जुड़े संसाधनों को रिलीज़ करने के लिए, xrDestroySpatialReferenceCacheANDROID फ़ंक्शन को कॉल कर सकता है.

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

थ्रेड सेफ़्टी

  • cacheHandle और बच्चों के सभी हैंडल को बाहरी तौर पर सिंक किया जाना चाहिए

रिटर्न कोड

सफल

  • XR_SUCCESS

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

कॉन्फ़िगरेशन

XrSpatialCapabilityConfigurationAnnotationTrackingANDROID स्ट्रक्चर को इस तरह परिभाषित किया गया है:

typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialReferenceCacheANDROID      cache;
    XrTime                              time;
    XrSpatialReferenceImageEXT          reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;

सदस्यों के बारे में जानकारी

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL होता है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर होता है.
  • capability एक XrSpatialCapabilityEXT है और ज़रूरी है कि यह XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID हो .
  • enabledComponentCount, uint32_t है. यह enabledComponents कैटगरी में मौजूद एलिमेंट की संख्या के बारे में बताता है.
  • enabledComponents, XrSpatialComponentTypeEXT की एक कैटगरी का पॉइंटर है .
  • cache एक XrSpatialReferenceCacheANDROID है. इसे पहले बनाया गया था, ताकि reference कॉन्फ़िगरेशन के लिए रनटाइम रेफ़रंस रिकॉर्ड किए जा सकें.
  • time वह XrTime है जिस पर reference को कैप्चर किया जाता है.
  • reference एक XrSpatialReferenceImageEXT है. इसके ऐनोटेशन, इसके अगले पॉइंटर से जुड़े होते हैं.

ऐप्लिकेशन, XrSpatialContextCreateInfoEXT :: capabilityConfigs में XrSpatialCapabilityConfigurationAnnotationTrackingANDROID स्ट्रक्चर में एक पॉइंटर जोड़कर, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID स्पेशल कैपेबिलिटी चालू कर सकते हैं .

अगर capability, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID नहीं है, तो रनटाइम को XR_ERROR_VALIDATION_FAILURE दिखाना ज़रूरी है .

अगर reference में कोई एनोटेशन नहीं है, तो रनटाइम को XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT वैल्यू ज़रूर दिखानी चाहिए.

अगर एनोटेशन कॉम्पोनेंट को enabledComponents में लिस्ट किया गया है, लेकिन उससे जुड़े कोई भी एनोटेशन reference से नहीं जुड़े हैं, तो रनटाइम को XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT दिखाना ज़रूरी है .

अगर cache का मालिकाना हक उस XrSession के पास नहीं है जिसे xrCreateSpatialContextAsyncEXT को पास किया जा रहा है, तो रनटाइम को XR_ERROR_VALIDATION_FAILURE दिखाना ज़रूरी है .

अगर time, cache की समयावधि से बाहर है, तो रनटाइम को XR_ERROR_TIME_INVALID वैल्यू ज़रूर दिखानी चाहिए .

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

एनोटेशन ट्रैकिंग इवेंट

XrEventDataSpatialAnnotationTrackingANDROID स्ट्रक्चर को इस तरह से परिभाषित किया गया है:

typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
    uint32_t               annotationIndex;
    XrResult               initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;

सदस्यों के बारे में जानकारी

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL होता है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर होता है.
  • spatialContext, XrSpatialContextEXT है, जिसके लिए एनोटेशन ट्रैकिंग चालू की गई है.
  • annotationIndex XrSpatialCapabilityConfigurationAnnotationTrackingANDROID से जुड़े एनोटेशन ऐरे के इंडेक्स पर मैप करता है :: reference .
  • initializationResult से एनोटेशन के शुरू होने का नतीजा पता चलता है. अगर यह XR_SUCCESS नहीं है, तो ऐप्लिकेशन एनोटेशन को फिर से शुरू करने के लिए, XrSpatialContextEXT हैंडल को मिटाकर फिर से बना सकता है. इसके अलावा, अन्य एनोटेशन को ट्रैक करने के लिए, spatialContext का इस्तेमाल जारी रखा जा सकता है.

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

हर एनोटेशन के लिए, रनटाइम को XrEventDataSpatialAnnotationTrackingANDROID फ़ील्ड में वैल्यू भरनी ज़रूरी है, ताकि यह पता चल सके कि एनोटेशन को शुरू किया जा चुका है. शुरू करने के नतीजे से कोई फ़र्क़ नहीं पड़ता. इवेंट मिलने के बाद, ऐप्लिकेशन मेमोरी के इस्तेमाल को कम करने के लिए, इमेज बफ़र को रिलीज़ कर सकता है.

अगर एनोटेशन को सही तरीके से शुरू किया गया है, तो रनटाइम को initializationResult में XR_SUCCESS की जानकारी भरनी होगी. इसके बाद, ऐप्लिकेशन एनोटेशन को ट्रैक करने के लिए, XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT इवेंट को पुल कर सकता है.

अगर ऐसा नहीं होता है, तो रनटाइम को initializationResult फ़ील्ड में गड़बड़ी का सही कोड डालना ज़रूरी है, ताकि गड़बड़ी की वजह बताई जा सके. ऐप्लिकेशन, नए एनोटेशन को शुरू करने के लिए XrSpatialContextEXT हैंडल को मिटा सकता है. इसके अलावा, अन्य एनोटेशन को ट्रैक करने के लिए spatialContext का इस्तेमाल जारी रख सकता है.

क्वाड एनोटेशन

रंटाइम को, क्वाड एनोटेशन के साथ काम करने की सुविधा का विज्ञापन ज़रूर देना चाहिए. इसके लिए, उसे xrEnumerateSpatialCapabilityComponentTypesEXT का इस्तेमाल करना होगा. साथ ही, उसे कॉम्पोनेंट टाइप की यह सूची देनी होगी:

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

क्वाड रेफ़रंस

XrSpatialAnnotationQuadReferenceANDROID स्ट्रक्चर को इस तरह परिभाषित किया गया है:

typedef struct XrSpatialAnnotationQuadReferenceANDROID {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 quadCount;
    const XrSpatialAnnotationQuadANDROID*    quads;
} XrSpatialAnnotationQuadReferenceANDROID;

सदस्यों के बारे में जानकारी

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL होता है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर होता है.
  • quadCount, uint32_t है. यह quads कैटगरी में मौजूद एलिमेंट की संख्या के बारे में बताता है.
  • quads, XrSpatialAnnotationQuadANDROID के ऐरे का पॉइंटर है .

जब रनटाइम, क्वाड एनोटेशन के साथ काम करता है, तब कोई ऐप्लिकेशन एनोटेशन कॉन्फ़िगर कर सकता है. इसके लिए, उसे XrSpatialAnnotationQuadReferenceANDROID स्ट्रक्चर को XrSpatialReferenceImageEXT :: next से जोड़ना होगा. साथ ही, XrSpatialContextEXT हैंडल बनाते समय, XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference में रेफ़रंस सेट करना होगा.

अगर quadCount की वैल्यू 0 है, तो रनटाइम को xrCreateSpatialContextAsyncEXT से XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT वैल्यू ज़रूर दिखानी चाहिए.

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

XrSpatialAnnotationQuadANDROID स्ट्रक्चर को इस तरह परिभाषित किया गया है:

typedef struct XrSpatialAnnotationQuadANDROID {
    XrSpatialAnnotationQuadAlignmentANDROID    alignment;
    XrVector2f                                 upperLeft;
    XrVector2f                                 upperRight;
    XrVector2f                                 lowerRight;
    XrVector2f                                 lowerLeft;
} XrSpatialAnnotationQuadANDROID;

सदस्यों के बारे में जानकारी

  • alignment, क्वाड का XrSpatialAnnotationQuadAlignmentANDROID है.
  • upperLeft एक XrVector2f है. यह ऑरिजिन से जुड़े क्वाड के ऊपर बाएं कोने के कोऑर्डिनेट के बारे में बताता है.
  • upperRight एक XrVector2f है. यह ऑरिजिन से जुड़े क्वाड के ऊपरी दाएं कोने के कोऑर्डिनेट के बारे में बताता है.
  • lowerRight एक XrVector2f है. यह ऑरिजिन से जुड़े क्वाड के निचले दाएं कोने के निर्देशांक के बारे में बताता है.
  • lowerLeft एक XrVector2f है. यह ऑरिजिन से जुड़े क्वाड के निचले बाएं कोने के कोऑर्डिनेट के बारे में बताता है.

2D स्पेस में क्वाड, घड़ी की सुई की दिशा में क्रम से लगा हुआ कॉन्वेक्स चतुर्भुज होता है. चार कोनों की वैल्यू, ऑरिजिन (0, 0) से जुड़ी होती है. ऑरिजिन वह बिंदु होता है जिससे क्वाड जुड़ा होता है.

  • जब इसे XrSpatialReferenceImageEXT से जोड़ा जाता है, तो ओरिजनल इमेज का ऊपरी बायां कोना, ओरिजनल इमेज का शुरुआती बिंदु होता है. इसमें X, चौड़ाई वाले पिक्सल से और Y, लंबाई वाले पिक्सल से मैप होता है.
  • जब यह XrSpatialAnnotationQuadDataANDROID से जुड़ा होता है , तो ऑरिजिन को XrSpatialAnnotationQuadDataANDROID :: origin के XrSpaceLocationData :: pose से दिखाया जाता है .

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

  • XrSpatialAnnotationQuadANDROID का इस्तेमाल करने से पहले, XR_ANDROID_spatial_annotation_tracking एक्सटेंशन को चालू करना ज़रूरी है
  • alignment, XrSpatialAnnotationQuadAlignmentANDROID की मान्य वैल्यू होनी चाहिए

typedef enum XrSpatialAnnotationQuadAlignmentANDROID {
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;

XrSpatialAnnotationQuadAlignmentANDROID इन्यूमरेशन से, क्वाड एनोटेशन के अलाइनमेंट के बारे में पता चलता है.

इन एनम का मतलब यह है:

Enum की जानकारी

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID

एनोटेशन क्वाड, स्क्रीन प्लेन के समानांतर होता है. वहीं, इसके इन-प्लेन रोटेशन को दुनिया के गुरुत्वाकर्षण के हिसाब से लॉक किया जाता है. आउटपुट, सामान्य और सीधे तौर पर दिखने वाले बाउंडिंग बॉक्स के तौर पर दिखता है.

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID

एनोटेशन क्वाड को सीधे तौर पर ऑब्जेक्ट से जोड़ा जाता है. यह रेफ़रंस इमेज में तय किए गए अलाइनमेंट से मेल खाता है. आउटपुट में एक कॉन्वेक्स चतुर्भुज होता है. यह ऑब्जेक्ट के पर्सपेक्टिव से मेल खाने के लिए, अपने आकार को अडजस्ट करता है.

क्वाड कॉम्पोनेंट

XrSpatialAnnotationQuadDataANDROID स्ट्रक्चर को इस तरह परिभाषित किया गया है:

typedef struct XrSpatialAnnotationQuadDataANDROID {
    uint32_t                          annotationIndex;
    XrSpaceLocationData               origin;
    XrSpatialAnnotationQuadANDROID    quad;
} XrSpatialAnnotationQuadDataANDROID;

सदस्यों के बारे में जानकारी

  • annotationIndex, XrSpatialAnnotationQuadReferenceANDROID :: quads ऐरे का इंडेक्स है. यह ऐरे, XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference से पास किए गए रेफ़रंस से जुड़ा होता है.
  • origin एक XrSpaceLocationData है. यह 2D प्लैन के ऑरिजिन के बारे में बताता है, जहां क्वाड मौजूद है. रनटाइम को XrSpaceLocationData :: locationFlags को सेट करना होगा, ताकि ऑरिजिन पोज़ के मान्य बिट दिखाए जा सकें.
  • quad, लोकल स्पेस में मौजूद क्वाड को दिखाने वाला XrSpatialAnnotationQuadANDROID है. क्वाड को पोज़ स्पेस में बदलने के लिए, origin का इस्तेमाल करें.

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

  • XrSpatialAnnotationQuadDataANDROID का इस्तेमाल करने से पहले, XR_ANDROID_spatial_annotation_tracking एक्सटेंशन को चालू करना ज़रूरी है
  • origin, XrSpaceLocationData स्ट्रक्चर के हिसाब से मान्य होना चाहिए
  • quad ज़रूरी है कि यह XrSpatialAnnotationQuadANDROID का मान्य स्ट्रक्चर हो

XrSpatialComponentAnnotationQuadListANDROID स्ट्रक्चर को इस तरह से परिभाषित किया गया है:

typedef struct XrSpatialComponentAnnotationQuadListANDROID {
    XrStructureType                        type;
    void*                                  next;
    uint32_t                               quadCount;
    XrSpatialAnnotationQuadDataANDROID*    quads;
} XrSpatialComponentAnnotationQuadListANDROID;

सदस्यों के बारे में जानकारी

  • type इस स्ट्रक्चर का XrStructureType है.
  • next, NULL होता है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर होता है.
  • quadCount, uint32_t है. यह quads कैटगरी में मौजूद एलिमेंट की संख्या के बारे में बताता है.
  • quads, XrSpatialAnnotationQuadDataANDROID का कलेक्शन है .

ऐप्लिकेशन, XrSpatialSnapshotEXT में मौजूद स्पेस से जुड़ी इकाइयों के क्वाड एनोटेशन कॉम्पोनेंट के बारे में क्वेरी कर सकता है. इसके लिए, XrSpatialComponentDataQueryConditionEXT :: componentTypes में XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID जोड़ें. साथ ही, XrSpatialComponentDataQueryResultEXT के अगले पॉइंटर चेन में XrSpatialComponentAnnotationQuadListANDROID जोड़ें.

अगर XrSpatialComponentAnnotationQuadListANDROID, XrSpatialComponentDataQueryResultEXT :: next की अगली चेन में है, लेकिन XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID को XrSpatialComponentDataQueryConditionEXT :: componentTypes में शामिल नहीं किया गया है, तो रनटाइम को xrQuerySpatialComponentDataEXT से XR_ERROR_VALIDATION_FAILURE ज़रूर दिखाना चाहिए .

अगर quadCount, XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput से कम है, तो रनटाइम को xrQuerySpatialComponentDataEXT से XR_ERROR_SIZE_INSUFFICIENT वापस लाना ज़रूरी है .

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

कोड का उदाहरण

रनटाइम सपोर्ट की जांच करना

यहां दिए गए उदाहरण कोड में, यह जांच करने का तरीका बताया गया है कि रनटाइम में एनोटेशन ट्रैकिंग की सुविधा काम करती है या नहीं.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrEnumerateSpatialCapabilitiesEXT xrEnumerateSpatialCapabilitiesEXT;
PFN_xrEnumerateSpatialAnnotationReferenceSourcesANDROID xrEnumerateSpatialAnnotationReferenceSourcesANDROID;
PFN_xrEnumerateSpatialReferenceImageFormatsEXT xrEnumerateSpatialReferenceImageFormatsEXT;
PFN_xrEnumerateSpatialCapabilityComponentTypesEXT xrEnumerateSpatialCapabilityComponentTypesEXT;

// Check spatial annotation tracking capability
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0,
                                         &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount,
                                         &capabilityCount,
                                         capabilities.data()));
if (std::find(capabilities.begin(), capabilities.end(),
              XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID) ==
    capabilities.end()) {
  // System does not support spatial annotation tracking.
  return;
}

// Inspect system properties for annotation tracking variables
XrSystemSpatialAnnotationPropertiesANDROID annotationSystemProperties{
    XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{.type = XR_TYPE_SYSTEM_PROPERTIES,
                                    .next = &annotationSystemProperties,
                                    .systemId = systemId};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (annotationSystemProperties.maxAnnotationCount == 0) {
  // System does not support any active annotations.
  return;
}

// Enumerate supported reference sources
uint32_t sourceCountOutput = 0;
XrSpatialAnnotationReferenceSourceANDROID desiredSource =
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID;
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    0, &sourceCountOutput, nullptr));
std::vector<XrSpatialAnnotationReferenceSourceANDROID> sources(sourceCountOutput);
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    sourceCountOutput, &sourceCountOutput, sources.data()));
if (std::find(sources.begin(), sources.end(), desiredSource) == sources.end()) {
  // The desired source is not supported.
  return;
}

// Enumerate supported reference image formats, provided by XR_EXT_spatial_image_tracking.
uint32_t formatCountOutput = 0;
XrSpatialReferenceImageFormatEXT desiredFormat =
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT; // Or XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT for screenshot.
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, 0,
    &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), desiredFormat) == formats.end()) {
  // The desired format is not supported
  return;
}

// Enumerate supported components for annotation tracking capability.
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes{
    XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));
std::vector<XrSpatialComponentTypeEXT>
    annotationTypes(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = annotationTypes.size();
capabilityComponentTypes.componentTypes = annotationTypes.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));

// Check supported annotation components.
XrSpatialComponentTypeEXT desiredComponent =
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID;
const auto supportedComponent = [&annotationTypes](
                                    XrSpatialComponentTypeEXT component) {
  return std::find(annotationTypes.begin(), annotationTypes.end(), component) !=
         annotationTypes.end();
};
if (!supportedComponent(desiredComponent)) {
  // The desired annotation is not supported.
  return;
}

क्वाड एनोटेशन कॉन्फ़िगर करना

यहां दिए गए उदाहरण कोड में, क्वाड एनोटेशन को कॉन्फ़िगर करने का तरीका बताया गया है.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrCreateSpatialReferenceCacheAsyncANDROID xrCreateSpatialReferenceCacheAsyncANDROID;
PFN_xrCreateSpatialReferenceCacheCompleteANDROID xrCreateSpatialReferenceCacheCompleteANDROID;
PFN_xrDestroySpatialReferenceCacheANDROID xrDestroySpatialReferenceCacheANDROID;
PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialReferenceImageFormatEXT desiredFormat;
XrSpatialAnnotationReferenceSourceANDROID desiredSource;
XrSpatialComponentTypeEXT desiredComponent;

// Create and start reference cache to prepare for capturing reference images.
XrSpatialReferenceCacheANDROID referenceCache;
XrSpatialReferenceCacheCreateInfoANDROID cacheCreateInfo{
  .type = XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
  .source = desiredSource,
};
XrFutureEXT cacheFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialReferenceCacheAsyncANDROID(session, &cacheCreateInfo, &cacheFuture));

waitUntilReady(cacheFuture);

XrCreateSpatialReferenceCacheCompletionANDROID cacheCompletion{
    XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID};
CHK_XR(xrCreateSpatialReferenceCacheCompleteANDROID(session, cacheFuture,
                                                     &cacheCompletion));
if (cacheCompletion.futureResult != XR_SUCCESS) {
  // Error, reference cache creation failed
  return;
}

referenceCache = cacheCompletion.referenceCache;

// Create the reference image with quad annotations

//  YUV 4:2:0 Planar:
// ----------------------
// |     Y      |Cb |Cr |
// ----------------------
XrSpatialReferenceImagePlaneEXT cameraImagePlanes[3];
// for each plane (0=Y, 1=U(cb), 2=V(Cr)) return by Image#getPlanes().
for (int i = 0; i < 3; ++i) {
  cameraImagePlanes[i].buffer; // read from Plane#getBuffer().
  cameraImagePlanes[i].bufferSize; // set each buffer size. Y = width * height (bytes); U = Y / 4 (bytes); V = Y / 4 (bytes).
  cameraImagePlanes[i].rowStride; // read from Plane#getRowStride().
  cameraImagePlanes[i].pixelStride; // read from Plane#getPixelStride().
}
XrSpatialReferenceImageEXT referenceImage{
      XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
referenceImage.width = 640;
referenceImage.height = 480;
referenceImage.format = desiredFormat;
referenceImage.planeCount = 3;
referenceImage.planes = cameraImagePlanes;

XrSpatialAnnotationQuadANDROID
    quad; // quad coordinates within the reference image.
quad.alignment = XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID;
// Set unnormalized pixel coordinates of 4 corners.
quad.upperLeft = {0.0, 0.0};
quad.upperRight = {0.0, 100.0};
quad.lowerRight = {100.0, 100.0};
quad.lowerLeft = {0.0, 100.0};

XrSpatialAnnotationQuadReferenceANDROID quadReference{
    XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID};
quadReference.quads = &quad;
quadReference.quadCount = 1;
referenceImage.next = &quadReference;

// Create the spatial context with annotation configuration.
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
      desiredComponent,
  };

  // Configure annotation tracking
  XrSpatialCapabilityConfigurationAnnotationTrackingANDROID annotationConfig{
      XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID};
  annotationConfig.capability =
      XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID;
  annotationConfig.enabledComponentCount = enabledComponents.size();
  annotationConfig.enabledComponents = enabledComponents.data();
  annotationConfig.cache = referenceCache;
  annotationConfig.time; // The time when this reference image is captured.
  annotationConfig.reference = referenceImage;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT *>
      capabilityConfigs;
  capabilityConfigs.push_back(
      reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT *>(
          &annotationConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{
      XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo,
                                        &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{
      XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture,
                                           &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
    return;
  }

  spatialContext = completion.spatialContext;
  CHK_XR(xrDestroySpatialReferenceCacheANDROID(referenceCache));
}

चालू एनोटेशन देखना

यहां दिए गए उदाहरण कोड में, एनोटेशन खोजने और उनसे जुड़ी क्वेरी करने का तरीका बताया गया है.

XrInstance instance;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL
XrSpatialContextEXT spatialContext; // previously created

PFN_xrCreateSpatialDiscoverySnapshotAsyncEXT xrCreateSpatialDiscoverySnapshotAsyncEXT;
PFN_xrCreateSpatialDiscoverySnapshotCompleteEXT xrCreateSpatialDiscoverySnapshotCompleteEXT;
PFN_xrQuerySpatialComponentDataEXT xrQuerySpatialComponentDataEXT;
PFN_xrDestroySpatialSnapshotEXT xrDestroySpatialSnapshotEXT;
PFN_xrPollEvent xrPollEvent;
PFN_xrDestroySpatialContextEXT xrDestroySpatialContextEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialComponentTypeEXT desiredComponent; // e.g. XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

auto discoverAnnotations = [&](XrSpatialContextEXT spatialContext, XrTime time,
                               XrSpace baseSpace) {
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{desiredComponent};
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
      XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(
      spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{
      XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = baseSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{
      XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
      spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for desired annotation data, e.g. quad.
    XrSpatialComponentTypeEXT componentsToQuery[] = {
        XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID};
    XrSpatialComponentDataQueryConditionEXT queryCond{
        XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = 1;
    queryCond.componentTypes = componentsToQuery;
    XrSpatialComponentDataQueryResultEXT queryResult{
        XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond,
                                          &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(
        queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(
        queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialAnnotationQuadDataANDROID> quads(
        queryResult.entityIdCountOutput);
    XrSpatialComponentAnnotationQuadListANDROID quadList{
        XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID};
    quadList.quadCount = quads.size();
    quadList.quads = quads.data();
    queryResult.next = &quadList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond,
                                          &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialAnnotationQuadDataANDROID &currentQuad = quads[i];
        // Rendering quad in the view.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrSpace space;           // Application's play space.
  XrFrameState frameState; // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
    switch (event.type) {
    case XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID: {
      const XrEventDataSpatialAnnotationTrackingANDROID &eventdata =
          *reinterpret_cast<XrEventDataSpatialAnnotationTrackingANDROID *>(
              &event);
      if (eventdata.initializationResult != XR_SUCCESS) {
        // handle initialization failure.
        // e.g. CHK_XR(xrDestroySpatialContextEXT(spatialContext));
      }
      break;
    }
    case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
      const XrEventDataSpatialDiscoveryRecommendedEXT &eventdata =
          *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT *>(
              &event);
      // Discover spatial entities for the context that we received the
      // "discovery recommended" event for.
      //discoverSpatialEntities(eventdata.spatialContext, time, space);
      break;
    }
    }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

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

नए निर्देश

नई संरचनाएं

नए एनम

नए Enum कॉन्स्टेंट

  • XR_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAME
  • XR_ANDROID_spatial_annotation_tracking_SPEC_VERSION

  • XrObjectType को बढ़ाना :

    • XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID

  • XrSpatialCapabilityEXT को बढ़ाना :

    • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

  • XrSpatialComponentTypeEXT को एक्सटेंड करना :

    • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

  • XrStructureType को बढ़ाना :

    • XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
    • XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
    • XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
    • XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID

समस्याएं

वर्शन इतिहास

  • पहला संशोधन, 17-09-2025 (लेवाना चेन)

    • एक्सटेंशन के बारे में शुरुआती जानकारी.