XR_ANDROID_spatial_component_subsumed_by

Name String

XR_ANDROID_spatial_component_subsumed_by

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

792

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

XR_EXT_spatial_entity
und
XR_EXT_spatial_plane_tracking

Datum der letzten Änderung

2025-08-19

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

Mitwirkende

Brian Chen, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Übersicht

Diese Erweiterung baut auf XR_EXT_spatial_entity auf und bietet eine neue Komponente für XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, um die XrSpatialEntityIdEXT offenzulegen, die die aktuelle Entität umfasst.

Wenn die Laufzeitumgebung genügend Umgebungsinformationen erfasst hat, um zu erkennen, dass zwei verfolgte Ebenen tatsächlich identisch sind, wird die XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID-Komponente mit der ID einer der Ebenen an die andere angehängt. Ab diesem Zeitpunkt muss die Anwendung nur noch die Entität verarbeiten, die die Komponente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID nicht hat.

Mit dieser Erweiterung wird auch ein neuer Filter eingeführt, den die Anwendung mit XrSpatialDiscoverySnapshotCreateInfoEXT verketten kann, um alle Entitäten mit der Komponente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID herauszufiltern.

Berechtigungen

Android-Apps müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ in ihrem Manifest enthalten, 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 in der Lage ist, eine Ebene in eine andere zu subsumieren, 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-Entität müssen mit der Entität identisch sein, die sie enthält.

In Komponente enthalten

Komponentendaten

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID verwendet die Struktur XrSpatialEntityIdEXT für seine Daten, die die ID der übergeordneten Entität 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, der die Anzahl der Elemente im Array subsumedUniqueIds beschreibt.
  • subsumedUniqueIds ist ein Array von XrSpatialEntityIdEXT .

Die Anwendung kann die XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID-Komponente der räumlichen Entitäten in einem XrSpatialSnapshotEXT abfragen, indem sie XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID zur nächsten Kette des XrSpatialComponentDataQueryResultEXT hinzufügt.

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrQuerySpatialComponentDataEXT zurückgeben, wenn sich XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID in der nächsten Kette von XrSpatialComponentDataQueryResultEXT :: next befindet, aber XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID nicht in XrSpatialComponentDataQueryConditionEXT :: componentTypes enthalten ist.

Die Laufzeit muss XR_ERROR_SIZE_INSUFFICIENT von xrQuerySpatialComponentDataEXT zurückgeben, wenn subsumedUniqueIdCount kleiner als XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput ist.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_spatial_component_subsumed_by muss aktiviert sein, bevor XrSpatialComponentSubsumedByListANDROID verwendet werden kann.
  • 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 Funktion XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT aufgeführt ist, kann die Anwendung sie aktivieren, indem sie das Enum in die Liste XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents der von 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 next-Kette von XrSpatialDiscoverySnapshotCreateInfoEXT aufnehmen, um einen Snapshot mit Entitäten zu erhalten, die nicht von einer anderen Entität subsumiert werden.

Wenn Anwendungen XrSpatialDiscoveryUniqueEntitiesFilterANDROID mit XrSpatialDiscoverySnapshotCreateInfoEXT verketten und dabei die Komponente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes enthalten ist, muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.

Wenn die Anwendung XrSpatialDiscoveryUniqueEntitiesFilterANDROID mit XrSpatialDiscoverySnapshotCreateInfoEXT verkettet, aber keine Komponenten in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes auflistet, muss die Laufzeit alle räumlichen Entitäten in den Snapshot aufnehmen, die die in XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents aufgeführten Komponenten für die für spatialContext konfigurierten Funktionen enthalten, mit Ausnahme von Entitäten, die die Komponente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID enthalten.

Gültige Verwendung (implizit)

Beispielcode

Funktion zur Ebenenerkennung konfigurieren

Im folgenden Beispielcode wird gezeigt, wie Sie einen räumlichen Kontext mit der XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT-Funktion erstellen, die XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID unterstützt.

// 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))

Komponentendaten abfragen

Im folgenden Beispielcode wird gezeigt, wie Sie XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID-Komponentendaten aus einem mit XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT konfigurierten Kontext abfragen.

// 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);

Untergeordnete Entitäten herausfiltern

Im folgenden Beispielcode wird gezeigt, wie Sie Entitäten mit der angehängten Komponente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID mithilfe des Filters aus dem Erkennungs-Snapshot herausfiltern und die Entitäts-ID der übergeordneten Entitäten abfragen.

// 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);

Neue Gebäude

Neue Enum-Konstanten

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION

  • Erweiterung von XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

  • Erweiterung 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.