XR_ANDROID_spatial_component_subsumed_by

Name String

XR_ANDROID_spatial_component_subsumed_by

Uzantı Türü

Örnek uzantısı

Kayıtlı Dahili Numara

792

Düzeltme

1

Onay Durumu

Onaylanmadı

Uzantı ve Sürüm Bağımlılıkları

XR_EXT_spatial_entity
ve
XR_EXT_spatial_plane_tracking

Son Değiştirilme Tarihi

2025-08-19

IP Durumu

Bilinen bir fikri mülkiyet hak talebi yok.

Katkıda bulunanlar

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

Genel Bakış

Bu uzantı, XR_EXT_spatial_entity üzerine kuruludur ve XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT için mevcut varlığı kapsayan XrSpatialEntityIdEXT öğesini gösteren yeni bir bileşen sağlar.

Çalışma zamanı, izlenen 2 düzlemin aslında aynı olduğunu algılamak için yeterli ortam bilgisi edindiğinde, düzlemlerden birinin kimliğine sahip XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID bileşeni diğerine eklenir. Bu noktadan sonra uygulamanın yalnızca XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID bileşeni olmayan varlığı işlemesi gerekir.

Bu uzantı, uygulamanın XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID bileşenine sahip tüm varlıkları filtrelemek için XrSpatialDiscoverySnapshotCreateInfoEXT'ye zincirleyebileceği yeni bir filtre de sunar.

İzinler

Bu uzantı, ortamdaki düzlemleri izlediğinden Android uygulamalarının manifest dosyasında android.permission.SCENE_UNDERSTANDING_COARSE izni bulunmalıdır. android.permission.SCENE_UNDERSTANDING_COARSE izni tehlikeli bir izin olarak kabul edilir.

(koruma düzeyi: tehlikeli)

Çalışma Zamanı Desteği

Çalışma zamanı bir düzlemi diğerine dahil edebiliyorsa bunu xrEnumerateSpatialCapabilityComponentTypesEXT içinde XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT özelliği için desteklenen bir bileşen olarak XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID değerini numaralandırarak belirtmesi gerekir.

Ekli XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID varlığının tüm bileşen verileri, onu kapsayan varlıkla aynı olmalıdır.

Bileşen Tarafından Kapsanıyor

Bileşen verileri

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID, verileri için kapsayıcı varlığın kimliğini temsil eden XrSpatialEntityIdEXT yapısını kullanır.

Verileri sorgulamak için bileşen listesi yapısı

XrSpatialComponentSubsumedByListANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir.
  • subsumedUniqueIdCount, subsumedUniqueIds dizisindeki öğe sayısını açıklayan bir uint32_t değeridir.
  • subsumedUniqueIds, XrSpatialEntityIdEXT dizisidir.

Uygulama, XrSpatialComponentDataQueryResultEXT'in sonraki zincirine XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID ekleyerek XrSpatialSnapshotEXT içindeki uzamsal varlıkların XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID bileşenini sorgulayabilir.

XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID, XrSpatialComponentDataQueryResultEXT :: next öğesinin sonraki zincirindeyse ancak XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID, XrSpatialComponentDataQueryConditionEXT :: componentTypes öğesine dahil değilse çalışma zamanı, xrQuerySpatialComponentDataEXT öğesinden XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.

subsumedUniqueIdCount, XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput değerinden küçükse çalışma zamanı, xrQuerySpatialComponentDataEXT'ten XR_ERROR_SIZE_INSUFFICIENT değerini döndürmelidir.

Geçerli Kullanım (Dolaylı)

  • XrSpatialComponentSubsumedByListANDROID kullanılmadan önce XR_ANDROID_spatial_component_subsumed_by uzantısı etkinleştirilmelidir.
  • type XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID olmalıdır
  • next, NULL veya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır.
  • subsumedUniqueIds, subsumedUniqueIdCount XrSpatialEntityIdEXT değerlerinden oluşan bir dizinin işaretçisi olmalıdır
  • subsumedUniqueIdCount parametresi 0 değerinden büyük olmalıdır.

Yapılandırma

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT özelliği için XrSpatialCapabilityComponentTypesEXT :: componentTypes içinde listeleniyorsa uygulama, bu bileşeni destekleyen özelliğin XrSpatialCapabilityConfigurationBaseHeaderEXT türetilmiş yapısının XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents listesine enum'u ekleyerek bu özelliği etkinleştirebilir.

Kapsanan varlıkları filtreleme

XrSpatialDiscoveryUniqueEntitiesFilterANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir.

Uygulama, başka bir varlık tarafından kapsanmayan varlıkların bulunduğu bir anlık görüntü almak için XrSpatialDiscoverySnapshotCreateInfoEXT'nin next zincirine XrSpatialDiscoveryUniqueEntitiesFilterANDROID'i ekleyebilir.

Uygulamalar, XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes içine XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID bileşenini eklerken XrSpatialDiscoveryUniqueEntitiesFilterANDROID'i XrSpatialDiscoverySnapshotCreateInfoEXT'e zincirlerse çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.

Uygulama, XrSpatialDiscoveryUniqueEntitiesFilterANDROID'i XrSpatialDiscoverySnapshotCreateInfoEXT'e zincirler ancak XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes içinde herhangi bir bileşen listelemezse çalışma zamanı, spatialContext için yapılandırılmış özellikler için XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents içinde listelenen bileşen grubuna sahip olan anlık görüntüdeki tüm uzamsal varlıkları dahil etmelidir (XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID bileşenine sahip varlıklar hariç).

Geçerli Kullanım (Dolaylı)

Örnek kod

Düzlem İzleme Özelliğini Yapılandırma

Aşağıdaki örnek kodda, XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID destekleyen XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT özelliğine sahip bir uzamsal bağlamın nasıl oluşturulacağı gösterilmektedir.

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

Sorgu Bileşeni Verileri

Aşağıdaki örnek kodda, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT ile yapılandırılmış bağlamdan XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID bileşen verilerinin nasıl sorgulanacağı gösterilmektedir.

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

Kapsanan varlıkları filtreleme

Aşağıdaki örnek kodda, filtre kullanılarak XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID bileşeni eklenmiş varlıkların keşif anlık görüntüsünden nasıl filtreleneceği ve kapsayıcı varlıkların varlık kimliğinin nasıl sorgulanacağı gösterilmektedir.

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

Yeni Yapılar

Yeni Enum Sabitleri

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION

  • XrSpatialComponentTypeEXT'yi genişletme:

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

  • XrStructureType'ı genişletme:

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

Sayılar

Sürüm Geçmişi

  • Düzeltme 1, 19.11.2025 (Brian Chen)

    • İlk uzantı açıklaması.