Android XR for OpenXR | Android Developers

«نشست توسعه‌دهندگان Android» با یک بخش اختصاصی برای Android XR بازگشته است. با ما همراه باشید، چیزهای جدید را امتحان کنید، و بازخوردتان را برای ما ارسال کنید!

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

XR_ANDROID_spatial_component_subsumed_by

رشته نام

XR_ANDROID_spatial_component_subsumed_by

نوع افزونه

افزونه نمونه

شماره داخلی ثبت‌شده

792

بازبینی

وضعیت تصویب

تصویب‌نشده

وابستگی‌های افزونه و نسخه

XR_EXT_spatial_entity
و
XR_EXT_spatial_plane_tracking

تاریخ آخرین تغییر

2025-08-19

وضعیت IP

هیچ ادعای مالکیت فکری شناخته‌شده‌ای وجود ندارد.

همیاران

Brian Chen،‏ Google
Kyle Chen،‏ Google
Levana Chen،‏ Google
Nihav Jain،‏ Google
Spencer Quin،‏ 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_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID به زنجیره بعدی XrSpatialComponentDataQueryResultEXT، مؤلفه XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID نهادهای فضایی را در XrSpatialSnapshotEXT جستجو کند.

اگر XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID در زنجیره بعدی XrSpatialComponentDataQueryResultEXT :: next باشد اما XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID در XrSpatialComponentDataQueryConditionEXT :: componentTypes گنجانده نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را از xrQuerySpatialComponentDataEXT برگرداند.

اگر subsumedUniqueIdCount کمتر از XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput باشد، زمان اجرا باید XR_ERROR_SIZE_INSUFFICIENT را از xrQuerySpatialComponentDataEXT برگرداند.

استفاده معتبر (ضمنی)

افزونه 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 شمارش شده باشد، برنامه می‌تواند آن را با گنجاندن enum در فهرست 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 فعال شود
type باید XR_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);

سازه‌های جدید

درحال گسترش دادن XrSpatialComponentDataQueryResultEXT :
- XrSpatialComponentSubsumedByListANDROID
درحال گسترش دادن XrSpatialDiscoverySnapshotCreateInfoEXT :
- XrSpatialDiscoveryUniqueEntitiesFilterANDROID

ثابت‌های شمارشی جدید

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

مشکلات

سابقه نسخه

بازبینی ۱،‏ ۲۰۲۵/۱۱/۱۹ (Brian Chen)
- توضیحات اولیه افزونه.