XR_ANDROID_spatial_component_subsumed_by
Name String
XR_ANDROID_spatial_component_subsumed_by
Extension Type
Instance extension
Registered Extension Number
792
Revision
1
Ratification Status
Not ratified
Extension and Version Dependencies
XR_EXT_spatial_entity
and
XR_EXT_spatial_plane_tracking
Last Modified Date
2025-08-19
IP Status
No known IP claims.
Contributors
Brian Chen, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google
Przegląd
To rozszerzenie bazuje na XR_EXT_spatial_entity i udostępnia nowy komponent dla XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, aby udostępnić XrSpatialEntityIdEXT, który obejmuje bieżący element.
Gdy środowisko wykonawcze uzyska wystarczającą ilość informacji o otoczeniu, aby wykryć, że 2 śledzone płaszczyzny są w rzeczywistości takie same, do drugiej płaszczyzny zostanie dołączony komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID z identyfikatorem jednej z płaszczyzn. Od tego momentu aplikacja musi przetwarzać tylko element, który nie ma komponentu XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
To rozszerzenie wprowadza też nowy filtr, który aplikacja może połączyć z XrSpatialDiscoverySnapshotCreateInfoEXT, aby odfiltrować wszystkie elementy, które mają komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
Uprawnienia
Aplikacje na Androida muszą mieć w manifeście uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE, ponieważ to rozszerzenie śledzi płaszczyzny w otoczeniu. Uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE jest uważane za niebezpieczne.
(poziom ochrony: niebezpieczny)
Obsługa środowiska wykonawczego
Jeśli środowisko wykonawcze może obejmować jedną płaszczyznę w drugą, musi wskazać to, wymieniając XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID jako obsługiwany komponent dla XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT funkcji w xrEnumerateSpatialCapabilityComponentTypesEXT .
Wszystkie dane komponentu dołączonego elementu XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID muszą być identyczne z elementem, który go obejmuje.
Komponent obejmujący
Dane komponentu
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID używa struktury XrSpatialEntityIdEXT do przechowywania danych, która reprezentuje identyfikator elementu obejmującego.
Struktura listy komponentów do wysyłania zapytań o dane
Struktura XrSpatialComponentSubsumedByListANDROID jest zdefiniowana w ten sposób:
typedef struct XrSpatialComponentSubsumedByListANDROID {
XrStructureType type;
void* next;
uint32_t subsumedUniqueIdCount;
XrSpatialEntityIdEXT* subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;
Opisy elementó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 tablicaXrSpatialEntityIdEXT.
Aplikacja może wysyłać zapytania o komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID elementów przestrzennych w XrSpatialSnapshotEXT, dodając XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID do następnego łańcucha XrSpatialComponentDataQueryResultEXT .
Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE z 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 xrQuerySpatialComponentDataEXT, jeśli subsumedUniqueIdCount jest mniejszy niż XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .
Prawidłowe użycie (niejawne)
- Przed użyciem XrSpatialComponentSubsumedByListANDROID musisz włączyć rozszerzenie
XR_ANDROID_spatial_component_subsumed_by. -
typemusi mieć wartośćXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID -
nextmusi mieć wartośćNULLlub prawidłowy wskaźnik do następnej struktury w łańcuchu struktur. -
subsumedUniqueIdsmusi być wskaźnikiem do 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 go włączyć, dodając wyliczenie do listy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents struktury pochodnej XrSpatialCapabilityConfigurationBaseHeaderEXT funkcji, która obsługuje ten komponent.
Filtrowanie elementów obejmujących
Struktura XrSpatialDiscoveryUniqueEntitiesFilterANDROID jest zdefiniowana w ten sposób:
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
Opisy elementów
typeto XrStructureType tej struktury.nexttoNULLlub wskaźnik do następnej struktury w łańcuchu struktur.
Aplikacja może uwzględnić XrSpatialDiscoveryUniqueEntitiesFilterANDROID w łańcuchu next XrSpatialDiscoverySnapshotCreateInfoEXT, aby uzyskać migawkę z elementami, które nie są obejmowane przez inny element.
Jeśli aplikacje połączą XrSpatialDiscoveryUniqueEntitiesFilterANDROID z XrSpatialDiscoverySnapshotCreateInfoEXT, uwzględniając komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID w XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE .
Jeśli aplikacja połączy XrSpatialDiscoveryUniqueEntitiesFilterANDROID z XrSpatialDiscoverySnapshotCreateInfoEXT, ale nie wymieni żadnych komponentów w XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, środowisko wykonawcze musi uwzględnić w migawce wszystkie elementy przestrzenne, które mają zestaw komponentów wymienionych w XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents dla funkcji skonfigurowanych dla spatialContext, z wyjątkiem elementów, które mają komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
Prawidłowe użycie (niejawne)
- Przed użyciem XrSpatialDiscoveryUniqueEntitiesFilterANDROID musisz włączyć rozszerzenie
XR_ANDROID_spatial_component_subsumed_by. -
typemusi mieć wartośćXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID -
nextmusi mieć wartośćNULLlub prawidłowy wskaźnik do następnej struktury w łańcuchu struktur.
Przykładowy kod
Konfigurowanie funkcji śledzenia płaszczyzn
Poniższy przykładowy kod pokazuje, jak utworzyć kontekst przestrzenny z funkcją XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, która obsługuje 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))
Wysyłanie zapytań o dane komponentu
Poniższy przykładowy kod pokazuje, jak wysyłać zapytania o dane komponentu XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID z kontekstu skonfigurowanego za pomocą 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);
Filtrowanie elementów obejmujących
Poniższy przykładowy kod pokazuje, jak odfiltrować elementy z dołączonym komponentem XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID z migawki wykrywania za pomocą filtra, a także jak wysyłać zapytania o identyfikator elementu obejmującego.
// 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);
Nowe struktury
Rozszerzanie XrSpatialComponentDataQueryResultEXT :
Rozszerzanie 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 listopada 2025 r. (Brian Chen)
- Wstępny opis rozszerzenia.