XR_ANDROID_spatial_component_subsumed_by

Name String

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

Przegląd

To rozszerzenie bazuje na XR_EXT_spatial_entity i zapewnia nowy komponent dla XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, który ujawnia XrSpatialEntityIdEXT obejmujący bieżący element.

Gdy środowisko wykonawcze zbierze wystarczającą ilość informacji o otoczeniu, aby wykryć, że 2 śledzone płaszczyzny są w rzeczywistości takie same, komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID z identyfikatorem jednej z płaszczyzn zostanie dołączony do drugiej. Od tego momentu aplikacja musi przetwarzać tylko encję, która 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 zawierające komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Uprawnienia

Aplikacje na Androida muszą mieć w pliku manifestu uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE, ponieważ to rozszerzenie śledzi płaszczyzny w otoczeniu. Uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE jest uznawane za niebezpieczne.

(poziom ochrony: niebezpieczne)

Obsługa środowiska wykonawczego

Jeśli środowisko wykonawcze jest w stanie połączyć jedną płaszczyznę z drugą, musi to wskazać, wymieniając XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID jako obsługiwany komponent funkcji XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT w xrEnumerateSpatialCapabilityComponentTypesEXT .

Wszystkie dane komponentu dołączonego elementu XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID muszą być identyczne z danymi elementu, który go zawiera.

Zastąpiony przez komponent

Dane komponentu

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID używa struktury XrSpatialEntityIdEXT dla swoich danych, która reprezentuje identyfikator elementu nadrzędnego.

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 członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • subsumedUniqueIdCount to uint32_t opisujący liczbę elementów w tablicy subsumedUniqueIds.
  • subsumedUniqueIds to tablica obiektów XrSpatialEntityIdEXT .

Aplikacja może wysyłać zapytania do komponentu 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 mniejsze niż XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_ANDROID_spatial_component_subsumed_by musi być włączone przed użyciem XrSpatialComponentSubsumedByListANDROID.
  • type musi mieć wartość XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
  • next musi mieć wartość NULL lub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur
  • subsumedUniqueIds musi być wskaźnikiem do tablicy wartości subsumedUniqueIdCount XrSpatialEntityIdEXT
  • Parametr subsumedUniqueIdCount musi 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 enum do listy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents struktury 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

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.

Aplikacja może zawierać XrSpatialDiscoveryUniqueEntitiesFilterANDROID w łańcuchu next XrSpatialDiscoverySnapshotCreateInfoEXT, aby uzyskać zrzut z encjami, które nie są podrzędne względem innej encji.

Jeśli aplikacje łą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 łączy XrSpatialDiscoveryUniqueEntitiesFilterANDROID z XrSpatialDiscoverySnapshotCreateInfoEXT, ale nie zawiera żadnych komponentów w XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, środowisko wykonawcze musi uwzględnić w podsumowaniu 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 (pośrednie)

Przykładowy kod

Konfigurowanie funkcji śledzenia płaszczyzn

Poniższy przykładowy kod pokazuje, jak utworzyć kontekst przestrzenny z możliwością 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))

Dane komponentu zapytania

Poniższy przykładowy kod pokazuje, jak wysłać zapytanie 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);

Odfiltrowywanie elementów podrzędnych

Poniższy przykładowy kod pokazuje, jak za pomocą filtra odfiltrować encje z dołączonym komponentem XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID z migawki wykrywania, a także jak wysłać zapytanie o identyfikator encji nadrzędnych.

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

Nowe stałe typu wyliczeniowego

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION

  • Rozszerzenie XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

  • Rozszerzanie XrStructureType :

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

Problemy

Historia zmian

  • Wersja 1, 19.11.2025 (Brian Chen)

    • Początkowy opis rozszerzenia.