XR_ANDROID_spatial_entity_bound_anchor

Name String

XR_ANDROID_spatial_entity_bound_anchor

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

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

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

791

बदलाव

2

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

मंज़ूरी नहीं मिली

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

XR_EXT_spatial_anchor

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

2025-08-18

आईपी स्टेटस

बौद्धिक संपत्ति से जुड़े किसी दावे की जानकारी नहीं है.

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

युशेंग चांग, Google
काइल चेन, Google
निहाव जैन, Google
लेवाना चेन, Google
स्पेंसर क्विन, Google

खास जानकारी

इस एक्सटेंशन की मदद से, ऐप्लिकेशन स्पेसियल इकाइयों के लिए ऐंकर बना सकते हैं और उन्हें अटैच कर सकते हैं. इस एक्सटेंशन में, इन्हें "इकाई से जुड़े ऐंकर" कहा जाता है.

इकाई से जुड़े ऐंकर को XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT कॉम्पोनेंट और XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT कॉम्पोनेंट वाली (या "जिसमें") स्पेशल इकाई के तौर पर दिखाया जाता है. XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT कॉम्पोनेंट, उस पैरंट इकाई का XrSpatialEntityIdEXT स्टोर करता है जिससे ऐंकर जुड़ा होता है.

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

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

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

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

XrResult xrEnumerateSpatialAnchorAttachableComponentsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    attachableComponentCapacityInput,
    uint32_t*                                   attachableComponentCountOutput,
    XrSpatialComponentTypeEXT*                  attachableComponents);

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

  • instance, XrInstance का हैंडल है.
  • systemId वह XrSystemId है जिसके स्पेशल पर्सिस्टेंस स्टोर की गिनती की जाएगी.
  • attachableComponentCapacityInput, attachableComponents कलेक्शन की क्षमता है. इसके अलावा, ज़रूरी क्षमता को वापस पाने के अनुरोध को दिखाने के लिए, 0 का इस्तेमाल किया जाता है.
  • attachableComponentCountOutput, अटैच किए जा सकने वाले कॉम्पोनेंट की संख्या है या attachableComponentCapacityInput के कम होने पर ज़रूरी क्षमता है.
  • attachableComponents, XrSpatialComponentTypeEXT का कलेक्शन है. अगर attachableComponentCapacityInput की वैल्यू 0 है, तो यह NULL हो सकती है.
  • ज़रूरी attachableComponents साइज़ को वापस पाने के बारे में ज़्यादा जानकारी के लिए, बफ़र साइज़ पैरामीटर चैप्टर देखें.

इंस्टेंस के लाइफ़टाइम के दौरान, रनटाइम को दिए गए systemId के लिए, इस सूची से हमेशा एक जैसे बफ़र कॉन्टेंट को दिखाना चाहिए.

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

  • xrEnumerateSpatialAnchorAttachableComponentsANDROID को कॉल करने से पहले, XR_ANDROID_spatial_entity_bound_anchor एक्सटेंशन को चालू करना ज़रूरी है
  • instance एक मान्य XrInstance हैंडल होना ज़रूरी है
  • attachableComponentCountOutput को uint32_t वैल्यू का पॉइंटर होना चाहिए
  • अगर attachableComponentCapacityInput की वैल्यू 0 नहीं है, तो attachableComponents को attachableComponentCapacityInput XrSpatialComponentTypeEXT वैल्यू के कलेक्शन का पॉइंटर होना चाहिए

रिटर्न कोड

सफलता

  • 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_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

स्पेशल एंटिटी-बाउंड ऐंकर बनाना

ऐप्लिकेशन, ऐंकर बनाने के लिए xrCreateSpatialAnchorEXT फ़ंक्शन का इस्तेमाल करते हैं. अगर किसी ऐप्लिकेशन को स्पेसियल एंटिटी से अटैच किया गया एंटिटी-बाउंड ऐंकर बनाना है, तो वह xrCreateSpatialAnchorEXT फ़ंक्शन को कॉल करते समय, XrSpatialAnchorCreateInfoEXT स्ट्रक्चर के अगले पॉइंटर में XrSpatialAnchorParentANDROID स्ट्रक्चर को चेन कर सकता है.

XrSpatialAnchorParentANDROID स्ट्रक्चर को इस तरह से तय किया गया है:

typedef struct XrSpatialAnchorParentANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    parentId;
} XrSpatialAnchorParentANDROID;

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

  • type, इस स्ट्रक्चर का XrStructureType है.
  • next, NULL है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर है.
  • parentId, उस इकाई का XrSpatialEntityIdEXT है जिससे ऐंकर को अटैच किया जाएगा.

रनटाइम के दौरान यह पक्का किया जाना चाहिए कि पैरंट इकाई और ऐंकर के बीच की दूरी हमेशा एक जैसी हो. यहां दूरी का मतलब, ऐंकर के पोज़ से लेकर पैरंट इकाई की सबसे नज़दीकी सतह तक की दूरी से है. यह दूरी, सतह के नॉर्मल के साथ होती है. ऐंकर की पोज़िशन को पैरंट इकाई की पोज़िशन और पैरंट इकाई की सतह से दूरी के आधार पर अपडेट किया जाता है. इससे कोई फ़र्क़ नहीं पड़ता कि पैरंट इकाई में कितने अटैच किए जा सकने वाले कॉम्पोनेंट हैं.

अगर XrSpatialAnchorParentANDROID ::parentId, xrCreateSpatialAnchorEXT :: spatialContext के लिए मान्य आईडी नहीं है, तो रनटाइम को xrCreateSpatialAnchorEXT से XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT को ज़रूर रिटर्न करना चाहिए.

अगर पैरंट इकाई में xrEnumerateSpatialAnchorAttachableComponentsANDROID से गिनाए गए कॉम्पोनेंट में से कोई भी कॉम्पोनेंट मौजूद नहीं है, तो रनटाइम को xrCreateSpatialAnchorEXT से XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID दिखाना चाहिए.

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

कोड का उदाहरण

स्पेशल एंटिटी से जुड़ा ऐंकर बनाएं

यहां दिए गए उदाहरण में, इकाई से जुड़े ऐंकर को बनाने और उसे स्पेसियल प्लेन ट्रैकिंग इकाई से अटैच करने का तरीका बताया गया है.

XrFutureEXT future {XR_NULL_FUTURE_EXT};

std::vector<XrSpatialEntityEXT> entityBoundAnchorEntities;

// We want to look for entities that have the plane tracking components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
    .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
    .componentTypeCount = static_cast<uint32_t>(snapshotComponents.size()),
    .componentTypes = snapshotComponents.data(),
  };
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{
    .type = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT,
    .baseSpace = localSpace,
    .time = time,
    .future = future,
  };

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{
    .type = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT,
  };
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    XrSpatialComponentDataQueryConditionEXT queryCond{
      .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
      .componentTypeCount = static_cast<uint32_t>(snapshotComponents.size()),
      .componentTypes = snapshotComponents.data(),
    };

    XrSpatialComponentDataQueryResultEXT queryResult{
      .type = 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.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT bounded2DList{
      .type = XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT,
      .boundCount = static_cast<uint32_t>(bounded2D.size()),
      .bounds = bounded2D.data(),
    };
    queryResult.next = &bounded2DList;

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

    entityBoundAnchorEntities.reserve(queryResult.entityIdCountOutput);

    // Create anchors attached to the plane entities
    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] != XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        continue;
      }

      // Parent ID info the chained to spatial anchor create info next
      XrSpatialAnchorParentANDROID parentIdCreateInfo{
        .type = XR_TYPE_SPATIAL_ANCHOR_PARENT_ANDROID,
        .parentId = entityIds[i],
      };

      // spatial anchor create info
      XrSpatialAnchorCreateInfoEXT createInfo{
        .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
        // assign Parent ID to anchor create info next, and the pose to the bounded2D center
        .next = &parentIdCreateInfo,
        .baseSpace = localSpace,
        .time = time,
        .pose = bounded2D[i].center,
      };

      XrSpatialEntityIdEXT entityBoundAnchorEntityId {XR_NULL_SPATIAL_ENTITY_ID_EXT};
      XrSpatialEntityEXT entityBoundAnchorEntity {XR_NULL_HANDLE};
      CHK_XR(xrCreateSpatialAnchorEXT(spatialContext, &createInfo, &entityBoundAnchorEntityId, &entityBoundAnchorEntity));

      entityBoundAnchorEntities.push_back(entityBoundAnchorEntity);
    }

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

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

  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 = {
    .type = XR_TYPE_EVENT_DATA_BUFFER,
  };
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      if (event.type == 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);
              break;
      }
  }

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

इकाई से जुड़े ऐंकर पोज़ और पैरंट इकाई का आईडी पाना

यहां दिए गए उदाहरण में, कोड की मदद से यह दिखाया गया है कि किसी इकाई से जुड़े ऐंकर की पोज़ और उसकी पैरंट इकाई का आईडी कैसे हासिल किया जा सकता है.

std::vector<XrSpatialEntityEXT> entities;

auto updateEntityBoundAnchorInfo = [&](XrSpatialContextEXT spatialContext, XrTime time) {
    // We want to get updated data for all components of the entities, so skip specifying componentTypes.
    XrSpatialUpdateSnapshotCreateInfoEXT snapshotCreateInfo{
      .type = XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT,
      .entityCount = static_cast<uint32_t>(entities.size()),
      .entities = entities.data(),
      .baseSpace = localSpace,
      .time = time,
    };

    XrSpatialSnapshotEXT snapshot {XR_NULL_HANDLE};
    CHK_XR(xrCreateSpatialUpdateSnapshotEXT(spatialContext, &snapshotCreateInfo, &snapshot));

    // Query for the entities that have the anchor component and parent component on them.
    std::array<XrSpatialComponentTypeEXT, 2> componentsToQuery {XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT, XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{
      .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
      .componentTypeCount = componentsToQuery.size(),
      .componentTypes = componentsToQuery.data(),
    };

    XrSpatialComponentDataQueryResultEXT queryResult{
      .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
    };
    CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

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

    // query for the pose data
    std::vector<XrPosef> locations(queryResult.entityIdCountOutput);
    XrSpatialComponentAnchorListEXT locationList{
      .type = XR_TYPE_SPATIAL_COMPONENT_ANCHOR_LIST_EXT,
      .locationCount = static_cast<uint32_t>(locations.size()),
      .locations = locations.data(),
    };
    queryResult.next = &locationList;

    // query for the parent entity ID data
    std::vector<XrSpatialEntityIdEXT> parentIds(queryResult.entityIdCountOutput);
    XrSpatialComponentParentListEXT parentList{
      .type = XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT,
      .parentCount = static_cast<uint32_t>(parentIds.size()),
      .parents = parentIds.data(),
    };
    queryResult.next = &parentList;

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

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        // Pose for entity entityIds[i] is locations[i].
        // Parent entity ID for entity entityIds[i] is parentIds[i].
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(snapshot));
};

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

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

  updateEntityBoundAnchorInfo(spatialContext, time);

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

अटैच किए जा सकने वाले कॉम्पोनेंट की सूची बनाना और इकाई से जुड़े ऐंकर की क्षमता की जांच करना

यहां दिए गए उदाहरण के कोड से पता चलता है कि अटैच किए जा सकने वाले कॉम्पोनेंट की गिनती कैसे की जाती है. साथ ही, यह भी पता चलता है कि रनटाइम, इकाई से जुड़े ऐंकर की सुविधा के साथ काम करता है या नहीं.

// Check spatial capability
uint32_t capabilityCount = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

// Check if anchor capability is supported
if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_ANCHOR_EXT) == capabilities.end()) {
  return;
}

// Check if plane tracking capability is supported
if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT) == capabilities.end()) {
  return;
}

// The supported spatial tracking components
std::vector<XrSpatialComponentTypeEXT> spatialTrackingCapabilityComponents;

// Enumerate supported components for plane tracking capability
XrSpatialCapabilityComponentTypesEXT planeComponents{
  .type = XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT,
};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &planeComponents));
std::vector<XrSpatialComponentTypeEXT> planeCapabilityComponents(planeComponents.componentTypeCountOutput);
planeComponents.componentTypes = planeCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &planeComponents));

// Add plane supported components to spatial tracking supported components
spatialTrackingCapabilityComponents.insert(spatialTrackingCapabilityComponents.end(), planeCapabilityComponents.begin(), planeCapabilityComponents.end());

// Enumerate supported attachable components for anchor
uint32_t attachableComponentCount = 0;
CHK_XR(xrEnumerateSpatialAnchorAttachableComponentsANDROID(instance, systemId, 0, &attachableComponentCount, nullptr));
std::vector<XrSpatialComponentTypeEXT> attachableComponents(attachableComponentCount);
CHK_XR(xrEnumerateSpatialAnchorAttachableComponentsANDROID(instance, systemId, attachableComponentCount, &attachableComponentCount, attachableComponents.data()));

// Check if at least one spatial tracking component is supported
const auto supportsComponent = [&spatialTrackingCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(spatialTrackingCapabilityComponents.begin(), spatialTrackingCapabilityComponents.end(), component) != spatialTrackingCapabilityComponents.end();
};

bool atLeastOneComponentSupported = false;
for (int32_t i = 0; i < attachableComponentCount; ++i) {
  if(supportsComponent(attachableComponents[i])) {
    atLeastOneComponentSupported = true;
    break;
  }
}

// No spatial tracking component supported for anchor attachment
if(!atLeastOneComponentSupported) return;

// ...
// Create spatial entity anchors and get their latest pose in the frame loop.
// ...

नए निर्देश

नए स्ट्रक्चर

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

  • XR_ANDROID_SPATIAL_ENTITY_BOUND_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_spatial_entity_bound_anchor_SPEC_VERSION
  • XrResult को एक्सटेंड करना :

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

    • XR_TYPE_SPATIAL_ANCHOR_PARENT_ANDROID

समस्याएं

वर्शन हिस्ट्री

  • पहला संशोधन, 18-08-2025 (यूशेंग चांग)

    • एक्सटेंशन का शुरुआती ब्यौरा.
  • रिविज़न 2, 16-12-2025 (काइल चेन)

    • एपीआई के कुछ व्यवहारों के लिए, ज़्यादा निर्देशात्मक भाषा जोड़ें.
    • xrEnumerateSpatialAnchorAttachableComponentsANDROID का उदाहरण कोड जोड़ें.