XR_ANDROID_spatial_component_subsumed_by
سلسلة الاسم
XR_ANDROID_spatial_component_subsumed_by
نوع الإضافة
إضافة مثيل
رقم الإضافة المسجَّل
792
المراجعة
1
حالة التصديق
لم تتم المصادقة
الاعتماديات على الإضافات والإصدارات
XR_EXT_spatial_entity
و
XR_EXT_spatial_plane_tracking
تاريخ آخر تعديل
2025-08-19
حالة عنوان IP
ما مِن مطالبات معروفة بملكية الملكية الفكرية.
المساهمون
براين تشين، 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متطابقة مع الكيان الذي يندرج تحته.
Subsumed By Component
بيانات المكوّن
تستخدم 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 - يجب أن يكون
typeXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID - يجب أن تكون قيمة
nextهيNULLأو مؤشرًا صالحًا إلى البنية التالية في سلسلة البِنى - يجب أن يكون
subsumedUniqueIdsمؤشرًا إلى مصفوفة من قيمsubsumedUniqueIdCountXrSpatialEntityIdEXT - يجب أن تكون قيمة المَعلمة
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_ANDROID_spatial_component_subsumed_byقبل استخدام XrSpatialDiscoveryUniqueEntitiesFilterANDROID. - يجب أن يكون
typeXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID - يجب أن تكون قيمة
nextهيNULLأو مؤشرًا صالحًا إلى البنية التالية في سلسلة البِنى
مثال على الشفرة
ضبط إمكانية تتبُّع الطائرات
يوضّح نموذج الرمز البرمجي التالي كيفية إنشاء سياق مكاني يتضمّن إمكانية 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_NAMEXR_ANDROID_spatial_component_subsumed_by_SPEC_VERSIONتمديد XrSpatialComponentTypeEXT :
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
تمديد XrStructureType :
XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID
المشاكل
سجلّ الإصدارات
المراجعة 1، 19-11-2025 (براين تشين)
- الوصف الأوّلي للإضافة