XR_ANDROID_spatial_component_subsumed_by

Name String

XR_ANDROID_spatial_component_subsumed_by

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

792

المراجعة

1

حالة التصديق

لم تتم المصادقة عليها

الاعتماد على الإضافات والإصدارات

XR_EXT_spatial_entity
و
XR_EXT_spatial_plane_tracking

تاريخ آخر تعديل

2025-08-19

حالة الملكية الفكرية

ما مِن مطالبات معروفة بشأن الملكية الفكرية.

المساهمون

براين تشن، Google
كايل تشن، Google
ليفانا تشن، Google
نيهاف جاين، Google
سبنسر كوين، Google

نظرة عامة

تستند هذه الإضافة إلى XR_EXT_spatial_entity وتوفّر مكوّنًا جديدًا لـ XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT من أجل عرض XrSpatialEntityIdEXT الذي يتضمّن الكيان الحالي.

عندما يحصل وقت التشغيل على معلومات كافية عن البيئة لرصد أنّ مستويَين يتم تتبّعهما هما في الواقع المستوى نفسه، يتم إرفاق مكوّن XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID الذي يحمل رقم تعريف أحد المستويَين بالمستوى الآخر. من ذلك الحين فصاعدًا، يحتاج التطبيق فقط إلى معالجة الكيان الذي لا يحتوي على المكوّن XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

توفّر هذه الإضافة أيضًا فلترًا جديدًا يمكن للتطبيق ربطه بـ XrSpatialDiscoverySnapshotCreateInfoEXT لاستبعاد أي كيانات تحتوي على المكوّن XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

الأذونات

يجب أن تتضمّن تطبيقات Android الإذن android.permission.SCENE_UNDERSTANDING_COARSE في ملف البيان الخاص بها لأنّ هذه الإضافة تتتبّع الأسطح المستوية في البيئة. يُعدّ الإذن android.permission.SCENE_UNDERSTANDING_COARSE إذنًا خطيرًا.

(مستوى الحماية: خطير)

دعم بيئة التشغيل

إذا كان وقت التشغيل قادرًا على دمج مستوى في آخر، يجب أن يشير إلى ذلك من خلال تعداد XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID كمكوّن متوافق لإمكانية XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT في xrEnumerateSpatialCapabilityComponentTypesEXT .

يجب أن تكون جميع بيانات المكوّنات الخاصة بالكيان المرفق XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID مطابقة للكيان الذي يضمّها.

مشمول في المكوّن

بيانات المكوّنات

يستخدم XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID بنية XrSpatialEntityIdEXT لبياناته، والتي تمثّل معرّف الكيان الفرعي.

بنية قائمة المكوّنات لطلب البيانات

يتم تحديد بنية XrSpatialComponentSubsumedByListANDROID على النحو التالي:

typedef struct XrSpatialComponentSubsumedByListANDROID {
    XrStructureType          type;
    void*                    next;
    uint32_t                 subsumedUniqueIdCount;
    XrSpatialEntityIdEXT*    subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • ‫subsumedUniqueIdCount هو uint32_t يصف عدد العناصر في مصفوفة subsumedUniqueIds.
  • ‫subsumedUniqueIds هو مصفوفة من XrSpatialEntityIdEXT .

يمكن للتطبيق الاستعلام عن المكوّن XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID للكيانات المكانية في XrSpatialSnapshotEXT من خلال إضافة XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID إلى السلسلة التالية من XrSpatialComponentDataQueryResultEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE من xrQuerySpatialComponentDataEXT إذا كان XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID في السلسلة التالية من XrSpatialComponentDataQueryResultEXT :: next ولكن لم يتم تضمين XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID في XrSpatialComponentDataQueryConditionEXT :: componentTypes .

يجب أن يعرض وقت التشغيل XR_ERROR_SIZE_INSUFFICIENT من xrQuerySpatialComponentDataEXT إذا كان subsumedUniqueIdCount أقل من XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

الاستخدام الصالح (ضمني)

  • يجب تفعيل الإضافة XR_ANDROID_spatial_component_subsumed_by قبل استخدام XrSpatialComponentSubsumedByListANDROID
  • يجب أن يكون type XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
  • next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
  • subsumedUniqueIds يجب أن يكون مؤشرًا إلى مصفوفة من قيم subsumedUniqueIdCount XrSpatialEntityIdEXT
  • يجب أن تكون المَعلمة subsumedUniqueIdCount أكبر من 0

الإعداد

إذا تم تعداد XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID في XrSpatialCapabilityComponentTypesEXT :: componentTypes لإمكانية XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT، يمكن للتطبيق تفعيلها من خلال تضمين التعداد في قائمة XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents للبنية المشتقة XrSpatialCapabilityConfigurationBaseHeaderEXT للإمكانية التي تتيح هذا المكوّن.

فلترة الكيانات المشمولة

يتم تعريف بنية XrSpatialDiscoveryUniqueEntitiesFilterANDROID على النحو التالي:

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

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.

يمكن أن يتضمّن التطبيق XrSpatialDiscoveryUniqueEntitiesFilterANDROID في سلسلة next من XrSpatialDiscoverySnapshotCreateInfoEXT للحصول على لقطة تتضمّن كيانات لا تندرج ضمن كيان آخر.

إذا ربطت التطبيقات XrSpatialDiscoveryUniqueEntitiesFilterANDROID بـ XrSpatialDiscoverySnapshotCreateInfoEXT مع تضمين المكوّن XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID في XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes ، يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE .

إذا ربط التطبيق XrSpatialDiscoveryUniqueEntitiesFilterANDROID بـ XrSpatialDiscoverySnapshotCreateInfoEXT ولكنّه لم يُدرج أي مكوّنات في XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes ، يجب أن يتضمّن وقت التشغيل جميع الكيانات المكانية في اللقطة التي تحتوي على مجموعة المكوّنات التي تم تعدادها في XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents للإمكانات التي تم ضبطها لـ spatialContext ، باستثناء الكيانات التي تحتوي على المكوّن XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID .

الاستخدام الصالح (ضمني)

مثال على الشفرة

ضبط إمكانية تتبُّع السطح

يوضّح المثال التالي كيفية إنشاء سياق مكاني باستخدام إمكانية XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT التي تتيح استخدام XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID .

// Check runtime supported capabilities
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()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT) == capabilities.end()) {
  return;
}

// 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.componentTypeCapacityInput = planeCapabilityComponents.size();
planeComponents.componentTypes = planeCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &planeComponents));

const auto supportsComponent = [&planeCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(planeCapabilityComponents.begin(), planeCapabilityComponents.end(), component) != planeCapabilityComponents.end();
};


std::vector<XrSpatialComponentTypeEXT> planeTrackingComponents {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};

if (supportsComponent(XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID)) {
  planeTrackingComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID);
}

// Create capability config for plane tracking
XrSpatialCapabilityConfigurationPlaneTrackingEXT planeTrackingConfig {
  .type = XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT,
  .enabledComponentCount = (uint32_t)planeTrackingComponents.size(),
  .enabledComponents = planeTrackingComponents.data(),
};

// Create spatial context
std::vector<const XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
capabilityConfigs.push_back(reinterpret_cast<const XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&planeTrackingConfig));

XrSpatialContextCreateInfoEXT contextCreateInfo {
  .type = XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT,
  .next = nullptr,
  .capabilityConfigCount = (uint32_t)capabilityConfigs.size(),
  .capabilityConfigs = capabilityConfigs.data(),
};

CHK_XR(xrCreateSpatialContextAsyncEXT(session, &contextCreateInfo, &future))

// Completes creating spatial context
XrCreateSpatialContextCompletionEXT contextCompletion{
XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};

CHK_XR(xrCreateSpatialContextCompleteEXT(session, future, &contextCompletion))

بيانات مكوّن طلب البحث

يوضّح الرمز البرمجي في المثال التالي كيفية طلب بيانات مكوّنات XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID من السياق الذي تم ضبطه باستخدام XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .

// previously created
XrSpatialSnapshotEXT snapshot;

// Query subsumed_by components
std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
};

XrSpatialComponentDataQueryConditionEXT queryCond {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
  .componentTypeCount = 1,
  .componentTypes     = enabledComponents.data(),
};

XrSpatialComponentDataQueryResultEXT queryResult {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
};

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

// Query again with allocated memory
std::vector<XrSpatialEntityIdEXT> subsumedUniqueIds;
subsumedUniqueIds.resize(queryResult.entityIdCountOutput);
XrSpatialComponentSubsumedByListANDROID subsumedByList {
  .type = XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID,
  .subsumedUniqueIdCount = static_cast<uint32_t>(subsumedUniqueIds.size()),
  .subsumedUniqueIds = subsumedUniqueIds.data(),
};

queryResult.next = &subsumedByList;
CHK_XR(xrQuerySpatialComponentDataEXT(
           snapshot, &queryCond, &queryResult));

for (uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // Plane was subsumed, remove it from processing logic
  // removeEntityFromProcessingLogic(queryResult.entityIds[i], /*replaceWith=*/ subsumedByList.subsumedUniqueIds[i]);
}

// Cleanup
xrDestroySpatialSnapshotEXT(snapshot);

استبعاد الكيانات المشمولة

يوضّح الرمز البرمجي في المثال التالي كيفية فلترة الكيانات التي تحتوي على مكوّن XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID من لقطة الاكتشاف باستخدام الفلتر، بالإضافة إلى الاستعلام عن رقم تعريف الكيانات المشمولة.

// Init filter
XrSpatialDiscoveryUniqueEntitiesFilterANDROID filter {
  .type = XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID,
};

// Chain filter to the snapshot create info
// WARNING: Chaining the filter while include subsumed_by component in the
// componentTypes is invalid
XrSpatialDiscoverySnapshotCreateInfoEXT discoverySnapshotCreateInfo {
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
  .next = &filter
};

XrFutureEXT future {XR_NULL_FUTURE_EXT};
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &discoverySnapshotCreateInfo, &future))

waitUntilReady(future);

// Complete async operation.
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
  createSnapshotCompletionInfo {
    .type   = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT,
    .baseSpace = space,
    .time      = updateTime,
    .future    = future,
  };

XrCreateSpatialDiscoverySnapshotCompletionEXT completion {
  .type = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT,
};

CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
           spatialContext, &createSnapshotCompletionInfo,
           &completion));

if(completion.futureResult != XR_SUCCESS) return;

// Subsumed entities has already been filtered out in this snapshot,
// now query the various components of the entities.

// Cleanup
xrDestroySpatialSnapshotEXT(completion.snapshot);

منشآت جديدة

ثوابت تعداد جديدة

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION

  • توسيع XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

  • توسيع XrStructureType :

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

المشاكل

سجلّ الإصدارات

  • المراجعة 1، ‏19-11-2025 (براين تشن)

    • وصف الإضافة الأوّلي