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 , untuk mengekspos properti subsumed_by.

Saat runtime telah memperoleh informasi lingkungan yang cukup untuk mendeteksi bahwa 2 bidang yang dilacak sebenarnya sama, komponen subsumed_by dengan ID salah satu bidang akan dilampirkan ke bidang lainnya.

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

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 mendukung subumed_by, runtime harus mendukung kemampuan pelacakan bidang dan menunjukkannya dengan mencantumkan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT di xrEnumerateSpatialCapabilitiesEXT .

Jika runtime menyediakan subsumed_by, 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_ANDROID entitas 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 entitas 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 subsumed_by 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 ada 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 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 kemampuan struktur turunan XrSpatialCapabilityConfigurationBaseHeaderEXT 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 XrSpatialDiscoverySnapshotCreateInfoEXT berikutnya untuk mendapatkan snapshot dengan entitas yang tidak termasuk dalam entitas 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 subsumed_by.

// Check runtime supported capabilities
uint32_t capabilityCount;
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;
}

std::vector<XrSpatialComponentTypeEXT> planeTrackingComponents {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
  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 mengkueri data komponen subsumed_by dari konteks yang dikonfigurasi dengan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .

// Create Discovery Snapshot
XrSpatialDiscoverySnapshotCreateInfoEXT discoverySnapshotCreateInfo {
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
};

CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT (
spatialContext, &discoverySnapshotCreateInfo, &future));

// Poll the state till snapshot it's ready.
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 {
  XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};

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

if(completion.futureResult != XR_SUCCESS) return;

// 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(
           completion.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(
           completion.snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityEXT> subsumedEntities;
for(uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
    // access planes[i] for merged plane id
    XrSpatialEntityIdEXT entityId = queryResult.entityIds[i];
    XrSpatialEntityIdEXT subsumedUniqueId = subsumedUniqueIds[i];

    // create handle via entityId
  XrSpatialEntityFromIdCreateInfoEXT entityCreateInfo {
    .type = XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT,
    .entityId = entityId,
  };

  XrSpatialEntityEXT entity = XR_NULL_HANDLE;
  xrCreateSpatialEntityFromIdEXT(spatialContext, &entityCreateInfo, &entity);

  subsumedEntities.push_back(entity);
}

// Cleanup
xrDestroySpatialSnapshotEXT(completion.snapshot);

Memfilter Entitas yang Tercakup

Contoh kode berikut menunjukkan cara memfilter entity dengan komponen subsumed_by yang dilampirkan 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: Chain 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
};

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 {
  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
// Bounded2D to render subsuming planes
std::vector<XrSpatialComponentTypeEXT> queryComponents {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
};

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

XrSpatialComponentDataQueryResultEXT queryResult {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
};

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

// Chain Bounded2D list
std::vector<XrSpatialBounded2DDataEXT> bounded2dData;
bounded2dData.resize(queryResult.entityIdCountOutput);

XrSpatialComponentBounded2DListEXT bounded2dList {
  .type = XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT,
  .boundCount = static_cast<uint32_t>(bounded2dData.size()),
  .bounds = bounded2dData.data(),
};

// Query again
queryResult.next = &bounded2dList;
CHK_XR(xrQuerySpatialComponentDataEXT(
           completion.snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityEXT> subsumingPlanes;
for(uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // access planes[i] for merged plane id
  XrSpatialEntityIdEXT entityId = queryResult.entityIds[i];

  // create handle via entityId.
  XrSpatialEntityFromIdCreateInfoEXT entityCreateInfo {
    .type = XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT,
    .entityId = entityId,
  };

  XrSpatialEntityEXT entity = XR_NULL_HANDLE;
  xrCreateSpatialEntityFromIdEXT(spatialContext, &entityCreateInfo, &entity);

  subsumingPlanes.push_back(entity);
}

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

Histori Versi

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

    • Deskripsi ekstensi awal.