XR_ANDROID_spatial_component_subsumed_by
Name String
XR_ANDROID_spatial_component_subsumed_by
Erweiterungstyp
Instanzerweiterung
Registrierte Durchwahlnummer
792
Revision
1
Ratifikationsstatus
Nicht ratifiziert
Abhängigkeiten von Erweiterungen und Versionen
XR_EXT_spatial_entity
und
XR_EXT_spatial_plane_tracking
Datum der letzten Änderung
2025-08-19
IP-Status
Es sind keine Ansprüche wegen geistigen Eigentums bekannt.
Mitwirkende
Brian Chen, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google
Übersicht
Diese Erweiterung basiert auf XR_EXT_spatial_entity und bietet eine neue Komponente für XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , um das Attribut „subsumed_by“ verfügbar zu machen.
Wenn die Laufzeit genügend Umgebungsinformationen gesammelt hat, um zu erkennen, dass zwei verfolgte Ebenen tatsächlich identisch sind, wird die Komponente „subsumed_by“ mit der ID einer der Ebenen an die andere angehängt.
Diese Erweiterung führt auch einen neuen Filter ein, den die Anwendung mit XrSpatialDiscoverySnapshotCreateInfoEXT verketten kann, um alle Entitäten herauszufiltern, denen die Komponente „subsumed_by“ angehängt ist.
Berechtigungen
Android-Anwendungen müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ in ihrem Manifest aufführen, da diese Erweiterung Ebenen in der Umgebung verfolgt. Die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ gilt als gefährliche Berechtigung.
(Schutzebene: gefährlich)
Laufzeitunterstützung
Wenn die Laufzeit „subumed_by“ unterstützt, muss sie die Funktion zur Ebenenverfolgung unterstützen und dies durch Aufzählen von XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT in xrEnumerateSpatialCapabilitiesEXT angeben .
Wenn die Laufzeit „subsumed_by“ bereitstellt, muss sie dies angeben, indem sie XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID als unterstützte Komponente für die XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT-Funktion in xrEnumerateSpatialCapabilityComponentTypesEXT auflistet .
Alle Komponentendaten der angehängten XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID-Einheit müssen mit der Einheit identisch sein, die sie subsumiert.
Untergeordnete Komponente
Komponentendaten
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID verwendet die XrSpatialEntityIdEXT-Struktur für seine Daten, die die ID der übergeordneten Einheit darstellt.
Komponentenlistenstruktur zum Abfragen von Daten
Die Struktur XrSpatialComponentSubsumedByListANDROID ist so definiert:
typedef struct XrSpatialComponentSubsumedByListANDROID {
XrStructureType type;
void* next;
uint32_t subsumedUniqueIdCount;
XrSpatialEntityIdEXT* subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette.subsumedUniqueIdCountist einuint32_t, das die Anzahl der Elemente imsubsumedUniqueIds-Array beschreibt.subsumedUniqueIdsist ein Array vonXrSpatialEntityIdEXT.
Die Anwendung kann die Komponente „subsumed_by“ der räumlichen Einheiten in einem XrSpatialSnapshotEXT abfragen, indem sie XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID der nächsten Kette des XrSpatialComponentDataQueryResultEXT hinzufügt .
Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrQuerySpatialComponentDataEXT zurückgeben, wenn XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID in der nächsten Kette von XrSpatialComponentDataQueryResultEXT :: next enthalten ist, XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID jedoch nicht in XrSpatialComponentDataQueryConditionEXT :: componentTypes .
Die Laufzeit muss XR_ERROR_SIZE_INSUFFICIENT von xrQuerySpatialComponentDataEXT zurückgeben, wenn subsumedUniqueIdCount kleiner als XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput ist .
Gültige Nutzung (implizit)
- Die
XR_ANDROID_spatial_component_subsumed_by-Erweiterung muss aktiviert werden, bevor XrSpatialComponentSubsumedByListANDROID verwendet wird. -
typemussXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
subsumedUniqueIdsmuss ein Zeiger auf ein Array vonsubsumedUniqueIdCountXrSpatialEntityIdEXT-Werten sein. - Der Parameter
subsumedUniqueIdCountmuss größer als0sein.
Konfiguration
Wenn XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID in XrSpatialCapabilityComponentTypesEXT :: componentTypes für die XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT-Funktion aufgeführt ist, kann die Anwendung sie aktivieren, indem sie die Enumeration in die XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents-Liste der XrSpatialCapabilityConfigurationBaseHeaderEXT-abgeleiteten Struktur der Funktion aufnimmt, die diese Komponente unterstützt.
Untergeordnete Entitäten filtern
Die Struktur XrSpatialDiscoveryUniqueEntitiesFilterANDROID ist so definiert:
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette.
Die Anwendung kann XrSpatialDiscoveryUniqueEntitiesFilterANDROID in die nächste Kette von XrSpatialDiscoverySnapshotCreateInfoEXT aufnehmen, um einen Snapshot mit Entitäten zu erhalten, die nicht von einer anderen Entität subsumiert werden.
Wenn Anwendungen XrSpatialDiscoveryUniqueEntitiesFilterANDROID an XrSpatialDiscoverySnapshotCreateInfoEXT anhängen und dabei die XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID-Komponente in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes einfügen , muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben .
Wenn Anwendungs-Chains XrSpatialDiscoveryUniqueEntitiesFilterANDROID bis XrSpatialDiscoverySnapshotCreateInfoEXT, aber keine Komponenten in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes auflisten, muss die Laufzeit alle räumlichen Einheiten im Snapshot enthalten, die die Gruppe von Komponenten haben, die in XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents für die für spatialContext konfigurierten Funktionen aufgeführt sind, mit Ausnahme von Einheiten mit der Komponente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
Gültige Nutzung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_component_subsumed_bymuss aktiviert werden, bevor XrSpatialDiscoveryUniqueEntitiesFilterANDROID verwendet wird. -
typemussXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
Beispielcode
Ebene-Tracking konfigurieren
Im folgenden Beispielcode wird gezeigt, wie Sie einen räumlichen Kontext mit der Funktion XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT erstellen, der „subsumed_by“ unterstützt.
// 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))
Komponentendaten abfragen
Im folgenden Beispielcode wird gezeigt, wie Sie Daten der Komponente „subsumed_by“ aus einem Kontext abfragen, der mit XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT konfiguriert wurde .
// 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);
Untergeordnete Entitäten herausfiltern
Der folgende Beispielcode zeigt, wie Sie Entitäten mit der Komponente „subsumed_by“ aus dem Discovery-Snapshot herausfiltern und die Entitäts-ID der subsumierenden Entitäten abfragen.
// 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);
Neue Strukturen
XrSpatialComponentDataQueryResultEXT erweitern :
Erweitern von XrSpatialDiscoverySnapshotCreateInfoEXT :
Neue Enum-Konstanten
XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAMEXR_ANDROID_spatial_component_subsumed_by_SPEC_VERSIONErweitern von XrSpatialComponentTypeEXT :
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
Erweitern von XrStructureType :
XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID
Probleme
Versionsverlauf
Version 1, 19.11.2025 (Brian Chen)
- Erste Beschreibung der Erweiterung.