XR_ANDROID_spatial_component_subsumed_by

String Nama

XR_ANDROID_spatial_component_subsumed_by

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

792

Revisi

1

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_spatial_entity
dan
XR_EXT_spatial_plane_tracking

Tanggal Terakhir Diubah

2025-08-19

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

Brian Chen, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Ringkasan

Ekstensi ini dibuat berdasarkan XR_EXT_spatial_entity dan menyediakan komponen baru untuk XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT guna mengekspos XrSpatialEntityIdEXT yang mencakup entitas saat ini.

Saat runtime telah memperoleh informasi lingkungan yang cukup untuk mendeteksi bahwa 2 bidang yang dilacak sebenarnya sama, komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID dengan ID salah satu bidang dilampirkan ke bidang lainnya. Mulai saat itu, aplikasi hanya perlu memproses entitas yang tidak memiliki komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Ekstensi ini juga memperkenalkan filter baru, yang dapat dirangkai aplikasi ke XrSpatialDiscoverySnapshotCreateInfoEXT untuk memfilter semua entity yang memiliki komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Izin

Aplikasi Android harus mencantumkan izin android.permission.SCENE_UNDERSTANDING_COARSE dalam manifesnya karena ekstensi ini melacak bidang di lingkungan. Izin android.permission.SCENE_UNDERSTANDING_COARSE dianggap sebagai izin berbahaya.

(tingkat perlindungan: berbahaya)

Dukungan Runtime

Jika runtime dapat menyertakan satu bidang ke bidang lain, runtime harus menunjukkannya dengan mencantumkan XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID sebagai komponen yang didukung untuk kemampuan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT di xrEnumerateSpatialCapabilityComponentTypesEXT .

Semua data komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROIDentitas terlampir harus identik dengan entitas yang mencakupnya.

Dicakup Oleh Komponen

Data komponen

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID menggunakan struktur XrSpatialEntityIdEXT untuk datanya, yang merepresentasikan ID entity yang mencakup.

Struktur daftar komponen untuk mengkueri data

Struktur XrSpatialComponentSubsumedByListANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • subsumedUniqueIdCount adalah uint32_t yang menjelaskan jumlah elemen dalam array subsumedUniqueIds.
  • subsumedUniqueIds adalah array XrSpatialEntityIdEXT .

Aplikasi dapat mengkueri komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID entitas spasial dalam XrSpatialSnapshotEXT dengan menambahkan XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID ke rantai berikutnya dari XrSpatialComponentDataQueryResultEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID berada di rantai XrSpatialComponentDataQueryResultEXT berikutnya :: next, tetapi XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID tidak disertakan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Runtime harus menampilkan XR_ERROR_SIZE_INSUFFICIENT dari xrQuerySpatialComponentDataEXT jika subsumedUniqueIdCount kurang dari XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_spatial_component_subsumed_by harus diaktifkan sebelum menggunakan XrSpatialComponentSubsumedByListANDROID
  • type harus berupa XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
  • next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
  • subsumedUniqueIds harus berupa pointer ke array nilai subsumedUniqueIdCount XrSpatialEntityIdEXT
  • Parameter subsumedUniqueIdCount harus lebih besar dari 0

Konfigurasi

Jika XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID tercantum dalam XrSpatialCapabilityComponentTypesEXT :: componentTypes untuk kemampuan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, aplikasi dapat mengaktifkannya dengan menyertakan enum dalam daftar XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents dari struktur turunan XrSpatialCapabilityConfigurationBaseHeaderEXT dari kemampuan yang mendukung komponen ini.

Memfilter Entitas yang Tercakup

Struktur XrSpatialDiscoveryUniqueEntitiesFilterANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.

Aplikasi dapat menyertakan XrSpatialDiscoveryUniqueEntitiesFilterANDROID dalam rantai next dari XrSpatialDiscoverySnapshotCreateInfoEXT untuk mendapatkan snapshot dengan entity yang tidak termasuk dalam entity lain.

Jika aplikasi merangkai XrSpatialDiscoveryUniqueEntitiesFilterANDROID ke XrSpatialDiscoverySnapshotCreateInfoEXT sambil menyertakan komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID di XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .

Jika rantai aplikasi XrSpatialDiscoveryUniqueEntitiesFilterANDROID ke XrSpatialDiscoverySnapshotCreateInfoEXT, tetapi tidak mencantumkan komponen apa pun di XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, runtime harus menyertakan semua entitas spasial dalam snapshot yang memiliki kumpulan komponen yang tercantum di XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents untuk kemampuan yang dikonfigurasi untuk spatialContext, kecuali entitas yang memiliki komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Penggunaan yang Valid (Implisit)

Kode contoh

Mengonfigurasi Kemampuan Pelacakan Bidang

Contoh kode berikut menunjukkan cara membuat konteks spasial dengan kemampuan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT yang mendukung 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))

Membuat Kueri Data Komponen

Contoh kode berikut menunjukkan cara membuat kueri data komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID dari konteks yang dikonfigurasi dengan 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);

Memfilter Entitas yang Tercakup

Contoh kode berikut menunjukkan cara memfilter entity dengan komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID yang terlampir dari snapshot penemuan menggunakan filter, serta mengkueri ID entity dari entity yang mencakup.

// 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);

Struktur Baru

Konstanta Enum Baru

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION
  • Memperluas XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
  • Memperluas XrStructureType :

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

Masalah

Riwayat Versi

  • Revisi 1, 19-11-2025 (Brian Chen)

    • Deskripsi ekstensi awal.