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

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • subsumedUniqueIdCount ist ein uint32_t, das die Anzahl der Elemente im subsumedUniqueIds-Array beschreibt.
  • subsumedUniqueIds ist ein Array von XrSpatialEntityIdEXT .

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.
  • type muss XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID sein
  • next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
  • subsumedUniqueIds muss ein Zeiger auf ein Array von subsumedUniqueIdCount XrSpatialEntityIdEXT-Werten sein.
  •  Der Parameter subsumedUniqueIdCount muss größer als 0 sein.

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

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder 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)

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

Neue Enum-Konstanten

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION
  • Erweitern von XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
  • Erweitern von XrStructureType :

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

Probleme

Versionsverlauf

  • Version 1, 19.11.2025 (Brian Chen)

    • Erste Beschreibung der Erweiterung.