XR_ANDROID_spatial_component_subsumed_by
Ciąg znaków nazwy
XR_ANDROID_spatial_component_subsumed_by
Typ rozszerzenia
Rozszerzenie instancji
Zarejestrowany numer wewnętrzny
792
Wersja
1
Stan ratyfikacji
Nie ratyfikowano
Zależności rozszerzeń i wersji
XR_EXT_spatial_entity
oraz
XR_EXT_spatial_plane_tracking
Data ostatniej modyfikacji
2025-08-19
Stan adresu IP
Brak znanych roszczeń dotyczących własności intelektualnej.
Twórcy
Brian Chen, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google
Omówienie
To rozszerzenie jest oparte na XR_EXT_spatial_entity i zawiera nowy komponent dla XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , który udostępnia właściwość subsumed_by.
Gdy środowisko wykonawcze uzyska wystarczającą ilość informacji o środowisku, aby wykryć, że 2 śledzone płaszczyzny są w rzeczywistości tą samą płaszczyzną, do jednej z nich zostanie dołączony komponent subsumed_by z identyfikatorem drugiej płaszczyzny.
To rozszerzenie wprowadza też nowy filtr, który aplikacja może połączyć z parametrem XrSpatialDiscoverySnapshotCreateInfoEXT, aby odfiltrować wszystkie jednostki, do których jest dołączony komponent subsumed_by.
Uprawnienia
Aplikacje na Androida muszą mieć w pliku manifestu uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE, ponieważ to rozszerzenie śledzi płaszczyzny w środowisku. Uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE jest uznawane za niebezpieczne.
(poziom ochrony: niebezpieczny)
Obsługa środowiska wykonawczego
Jeśli środowisko wykonawcze obsługuje subumed_by, musi obsługiwać śledzenie płaszczyzny i wskazywać to przez wyliczenie XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT w funkcji xrEnumerateSpatialCapabilitiesEXT .
Jeśli środowisko wykonawcze udostępnia subsumed_by, musi to wskazać, wymieniając XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID jako obsługiwany komponent dla możliwości XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT w funkcji xrEnumerateSpatialCapabilityComponentTypesEXT .
Wszystkie dane komponentu XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID dołączonej encji muszą być identyczne z encją, która ją obejmuje.
Subsumed By Component
Dane komponentu
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID używa struktury XrSpatialEntityIdEXT dla swoich danych, która reprezentuje identyfikator podmiotu nadrzędnego.
Struktura listy komponentów do odpytywania danych
Struktura XrSpatialComponentSubsumedByListANDROID jest zdefiniowana w ten sposób:
typedef struct XrSpatialComponentSubsumedByListANDROID {
XrStructureType type;
void* next;
uint32_t subsumedUniqueIdCount;
XrSpatialEntityIdEXT* subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;
Opisy członków
typeto XrStructureType tej struktury.nexttoNULLlub wskaźnik do następnej struktury w łańcuchu struktur.subsumedUniqueIdCounttouint32_topisujący liczbę elementów w tablicysubsumedUniqueIds.subsumedUniqueIdsto tablica elementówXrSpatialEntityIdEXT.
Aplikacja może wysyłać zapytania do komponentu subsumed_by encji przestrzennych w obiekcie XrSpatialSnapshotEXT, dodając XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID do następnego łańcucha obiektu XrSpatialComponentDataQueryResultEXT .
Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE z funkcji xrQuerySpatialComponentDataEXT, jeśli XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID znajduje się w następnym łańcuchu XrSpatialComponentDataQueryResultEXT :: next, ale XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID nie jest uwzględniony w XrSpatialComponentDataQueryConditionEXT :: componentTypes .
Środowisko wykonawcze musi zwracać XR_ERROR_SIZE_INSUFFICIENT z funkcji xrQuerySpatialComponentDataEXT, jeśli wartość subsumedUniqueIdCount jest mniejsza niż XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_spatial_component_subsumed_bymusi być włączone przed użyciem funkcji XrSpatialComponentSubsumedByListANDROID. -
typemusi mieć wartośćXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID -
nextmusi mieć wartośćNULLlub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur. -
subsumedUniqueIdsmusi być wskaźnikiem tablicy wartościsubsumedUniqueIdCountXrSpatialEntityIdEXT. - Parametr
subsumedUniqueIdCountmusi być większy niż0.
Konfiguracja
Jeśli XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID jest wymieniony w XrSpatialCapabilityComponentTypesEXT :: componentTypes dla funkcji XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, aplikacja może ją włączyć, dodając wyliczenie do listy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents w strukturze pochodnej XrSpatialCapabilityConfigurationBaseHeaderEXT funkcji, która obsługuje ten komponent.
Filtrowanie elementów podrzędnych
Struktura XrSpatialDiscoveryUniqueEntitiesFilterANDROID jest zdefiniowana w ten sposób:
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
Opisy członków
typeto XrStructureType tej struktury.nexttoNULLlub wskaźnik do następnej struktury w łańcuchu struktur.
Aplikacja może uwzględnić XrSpatialDiscoveryUniqueEntitiesFilterANDROID w następnym łańcuchu XrSpatialDiscoverySnapshotCreateInfoEXT, aby uzyskać migawkę z encjami, które nie są objęte inną encją.
Jeśli aplikacje łączą XrSpatialDiscoveryUniqueEntitiesFilterANDROID z XrSpatialDiscoverySnapshotCreateInfoEXT, w tym komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID w XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE .
Jeśli aplikacja łączy łańcuch XrSpatialDiscoveryUniqueEntitiesFilterANDROID z łańcuchem XrSpatialDiscoverySnapshotCreateInfoEXT, ale nie zawiera żadnych komponentów w łańcuchu XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, środowisko wykonawcze musi uwzględnić w migawce wszystkie obiekty przestrzenne, które mają zestaw komponentów wymienionych w łańcuchu XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents dla funkcji skonfigurowanych dla parametru spatialContext, z wyjątkiem obiektów, które mają komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_spatial_component_subsumed_bymusi być włączone przed użyciem funkcji XrSpatialDiscoveryUniqueEntitiesFilterANDROID. -
typemusi mieć wartośćXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID -
nextmusi mieć wartośćNULLlub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.
Przykładowy kod
Konfigurowanie funkcji śledzenia samolotów
Poniższy przykładowy kod pokazuje, jak utworzyć kontekst przestrzenny z możliwością XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, która obsługuje 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))
Wykonywanie zapytań o dane komponentu
Poniższy przykładowy kod pokazuje, jak wysyłać zapytania o dane komponentu subsumed_by z kontekstu skonfigurowanego za pomocą 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);
Filtrowanie elementów podrzędnych
Poniższy przykładowy kod pokazuje, jak odfiltrować z migawki wykrywania encje z dołączonym komponentem subsumed_by za pomocą filtra, a także jak wysłać zapytanie o identyfikator encji subsuming.
// 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);
Nowe struktury
Rozszerzanie XrSpatialComponentDataQueryResultEXT :
Rozszerzenie XrSpatialDiscoverySnapshotCreateInfoEXT :
Nowe stałe wyliczeniowe
XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAMEXR_ANDROID_spatial_component_subsumed_by_SPEC_VERSIONRozszerzanie XrSpatialComponentTypeEXT :
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
Rozszerzanie XrStructureType :
XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID
Problemy
Historia zmian
Wersja 1, 19.11.2025 (Brian Chen)
- Początkowy opis rozszerzenia.