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 का रनटाइम रेफ़रंस कैप्चर करता है. साथ ही, रेफ़रंस कैश मेमोरी की समयावधि के दौरान, रेफ़रंस में अपनी पसंद के मुताबिक एनोटेशन तय करता है.
  • इसके बाद, ऐप्लिकेशन XrSpatialContextEXT हैंडल बनाता है. यह हैंडल, XrSpatialCapabilityConfigurationAnnotationTrackingANDROID से मिले XrSpatialReferenceImageEXT पर आधारित होता है.
  • ऐप्लिकेशन, 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 में से कम से कम एक के साथ काम करे. इसके लिए, xrEnumerateSpatialAnnotationReferenceSourcesANDROID के ज़रिए, काम करने वाले रेफ़रंस सोर्स की सूची बनाएं. साथ ही, capability को XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID पर सेट करें.

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 के लिए चालू नहीं है.

सही इस्तेमाल (इंप्लिसिट)

  • xrEnumerateSpatialAnnotationReferenceSourcesANDROID को कॉल करने से पहले, XR_ANDROID_spatial_annotation_tracking एक्सटेंशन को चालू करना ज़रूरी है
  • 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 का मतलब यह है:

Enum की जानकारी

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

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

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 से जोड़ना होगा.

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

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

अगर 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 को बार-बार कॉल कर सकता है, ताकि यह पता लगाया जा सके कि एसिंक्रोनस ऑपरेशन पूरा हुआ है या नहीं.

अगर XrSpatialReferenceCacheCreateInfoANDROID :: capability को xrEnumerateSpatialCapabilitiesEXT ने लिस्ट नहीं किया है, तो रनटाइम को 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);

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

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

सही इस्तेमाल (इंप्लिसिट)

Thread की सुरक्षा

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

रिटर्न कोड

सफलता

  • XR_SUCCESS

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

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

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 है. इसमें एनोटेशन, इसके अगले पॉइंटर से जुड़े होते हैं.

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

अगर 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 दिखाना चाहिए.

सही इस्तेमाल (इंप्लिसिट)

  • XrSpatialCapabilityConfigurationAnnotationTrackingANDROID का इस्तेमाल करने से पहले, XR_ANDROID_spatial_annotation_tracking एक्सटेंशन चालू करना ज़रूरी है
  • type की वैल्यू XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID होनी चाहिए
  • next NULL या स्ट्रक्चर चेन में अगले स्ट्रक्चर का मान्य पॉइंटर होना चाहिए
  • capability की वैल्यू, XrSpatialCapabilityEXT की मान्य वैल्यू होनी चाहिए
  • enabledComponents को enabledComponentCount मान्य XrSpatialComponentTypeEXT वैल्यू के कलेक्शन का पॉइंटर होना चाहिए
  • cache एक मान्य XrSpatialReferenceCacheANDROID हैंडल होना ज़रूरी है
  • reference को मान्य XrSpatialReferenceImageEXT स्ट्रक्चर होना चाहिए
  • enabledComponentCount पैरामीटर की वैल्यू, 0 से ज़्यादा होनी चाहिए

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

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 दिखाना चाहिए.

सही इस्तेमाल (इंप्लिसिट)

  • XrSpatialAnnotationQuadReferenceANDROID का इस्तेमाल करने से पहले, XR_ANDROID_spatial_annotation_tracking एक्सटेंशन को चालू करना ज़रूरी है
  • type की वैल्यू XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID होनी चाहिए
  • next NULL या स्ट्रक्चर चेन में अगले स्ट्रक्चर का मान्य पॉइंटर होना चाहिए
  • quads को quadCount मान्य XrSpatialAnnotationQuadANDROID स्ट्रक्चर के कलेक्शन का पॉइंटर होना चाहिए
  • quadCount पैरामीटर की वैल्यू, 0 से ज़्यादा होनी चाहिए

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_SURFACE_ANDROID = 2,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;

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

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

Enum की जानकारी

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID

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

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID

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

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SURFACE_ANDROID

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

Quad Components

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 की अगली चेन में है, तो रनटाइम को xrQuerySpatialComponentDataEXT से XR_ERROR_VALIDATION_FAILURE ज़रूर दिखाना चाहिए. हालांकि, XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID को XrSpatialComponentDataQueryConditionEXT :: componentTypes में शामिल नहीं किया गया है.

अगर 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

नए 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 (लेवाना चेन)

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