XR_ANDROID_spatial_component_subsumed_by
Name String
XR_ANDROID_spatial_component_subsumed_by
Uzantı Türü
Örnek uzantısı
Kayıtlı Uzantı Numarası
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 IP 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 kurulmuştur ve subsumed_by özelliğini kullanıma sunmak için XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT ile ilgili 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 subsumed_by bileşeni diğerine eklenir.
Bu uzantı, uygulamaların XrSpatialDiscoverySnapshotCreateInfoEXT'ye zincirleyebileceği yeni bir filtre de sunar. Bu filtre, subsumed_by bileşeni eklenmiş tüm öğeleri filtrelemek için kullanılır.
İzinler
Bu uzantı, ortamdaki düzlemleri takip ettiğinden Android uygulamalarının manifestlerinde android.permission.SCENE_UNDERSTANDING_COARSE izninin listelenmesi gerekir. android.permission.SCENE_UNDERSTANDING_COARSE izni tehlikeli bir izin olarak kabul edilir.
(Koruma düzeyi: tehlikeli)
Çalışma Zamanı Desteği
Çalışma zamanı subumed_by'ı destekliyorsa düzlem takibi özelliğini desteklemeli ve xrEnumerateSpatialCapabilitiesEXT içinde XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT numaralandırarak bunu belirtmelidir.
Çalışma zamanı subsumed_by sağlıyorsa 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'ı numaralandırarak belirtmelidir .
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID Eklenen öğenin tüm bileşen verileri, onu kapsayan öğeyle aynı olmalıdır.
Subsumed By Component
Bileşen verileri
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID, verileri için XrSpatialEntityIdEXT yapısını kullanır. Bu yapı, kapsayan öğenin kimliğini temsil eder.
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'ıdır.next,NULLveya bir yapı zincirindeki sonraki yapının işaretçisidir.subsumedUniqueIdCount,subsumedUniqueIdsdizisindeki öğelerin sayısını açıklayan biruint32_t'dir.subsumedUniqueIds,XrSpatialEntityIdEXTdizisidir .
Uygulama, XrSpatialSnapshotEXT içindeki uzamsal öğelerin subsumed_by bileşenini, XrSpatialComponentDataQueryResultEXT'nin sonraki zincirine XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID ekleyerek sorgulayabilir.
Çalışma zamanı, XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID, XrSpatialComponentDataQueryResultEXT :: next zincirinde bir sonraki öğe ise ancak XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID, XrSpatialComponentDataQueryConditionEXT :: componentTypes içinde yer almıyorsa xrQuerySpatialComponentDataEXT'den XR_ERROR_VALIDATION_FAILURE döndürmelidir.
Çalışma zamanı, subsumedUniqueIdCount değeri XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput değerinden küçükse xrQuerySpatialComponentDataEXT işlevinden XR_ERROR_SIZE_INSUFFICIENT değerini döndürmelidir .
Geçerli Kullanım (Dolaylı)
-
XR_ANDROID_spatial_component_subsumed_byuzantısı, XrSpatialComponentSubsumedByListANDROID kullanılmadan önce etkinleştirilmelidir. -
typeXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDolmalıdır. -
nextmust beNULLor a valid pointer to the next structure in a structure chain -
subsumedUniqueIdsmust be a pointer to an array ofsubsumedUniqueIdCountXrSpatialEntityIdEXTvalues -
subsumedUniqueIdCountparametresi0değ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 numaralandırılmışsa uygulama, numaralandırmayı bu bileşeni destekleyen özelliğin XrSpatialCapabilityConfigurationBaseHeaderEXT türetilmiş yapısının XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents listesine dahil ederek 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'ıdır.next,NULLveya bir yapı zincirindeki sonraki yapının işaretçisidir.
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 sonraki zincirine XrSpatialDiscoveryUniqueEntitiesFilterANDROID ekleyebilir.
Uygulamalar , XrSpatialDiscoveryUniqueEntitiesFilterANDROID'i XrSpatialDiscoverySnapshotCreateInfoEXT'e zincirleyip XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID bileşenini XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes içine dahil ederse çalışma zamanı kesinlikle XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir .
Uygulama, XrSpatialDiscoveryUniqueEntitiesFilterANDROID'i XrSpatialDiscoverySnapshotCreateInfoEXT'e zincirliyorsa ancak XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes içinde herhangi bir bileşen listelemiyorsa çalışma zamanı, XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID bileşenine sahip olanlar hariç, uzamsal bağlam için yapılandırılan özellikler için XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents içinde numaralandırılan bileşen kümesine sahip olan tüm uzamsal öğeleri anlık görüntüye dahil etmelidir.
Geçerli Kullanım (Dolaylı)
- XrSpatialDiscoveryUniqueEntitiesFilterANDROID kullanılmadan önce
XR_ANDROID_spatial_component_subsumed_byuzantısı etkinleştirilmelidir. -
typeXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROIDolmalıdır. -
nextmust beNULLor a valid pointer to the next structure in a structure chain
Örnek kod
Düzlem İzleme Özelliğini Yapılandırma
Aşağıdaki örnek kodda, subsumed_by'ı destekleyen XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT özelliğiyle uzamsal bağlamın nasıl oluşturulacağı gösterilmektedir.
// 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))
Sorgu Bileşeni Verileri
Aşağıdaki örnek kodda, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT ile yapılandırılmış bağlamdan subsumed_by bileşen verilerinin nasıl sorgulanacağı gösterilmektedir .
// 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);
Kapsanan Varlıkları Filtreleme
Aşağıdaki örnek kodda, bileşeni eklenmiş olan varlıkların, filtre kullanılarak keşif anlık görüntüsünden nasıl filtreleneceği ve kapsayan 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: 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);
Yeni Yapılar
XrSpatialComponentDataQueryResultEXT'yi genişletme :
XrSpatialDiscoverySnapshotCreateInfoEXT'yi genişletme :
Yeni Numaralandırılmış Değer Sabitleri
XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAMEXR_ANDROID_spatial_component_subsumed_by_SPEC_VERSIONXrSpatialComponentTypeEXT'yi genişletme :
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
XrStructureType'ı genişletme :
XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID
Sayılar
Sürüm Geçmişi
1. düzeltme, 19.11.2025 (Brian Chen)
- İlk uzantı açıklaması.