XR_ANDROID_spatial_component_subsumed_by

Ciąg znaków nazwy

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

Omówienie

To rozszerzenie jest oparte na XR_EXT_spatial_entity i zawiera nowy komponent dla XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , który udostępnia właściwość subsumed_by.

Gdy środowisko wykonawcze uzyska wystarczającą ilość informacji o środowisku, aby wykryć, że 2 śledzone płaszczyzny są w rzeczywistości tą samą płaszczyzną, do jednej z nich zostanie dołączony komponent subsumed_by z identyfikatorem drugiej płaszczyzny.

To rozszerzenie wprowadza też nowy filtr, który aplikacja może połączyć z parametrem XrSpatialDiscoverySnapshotCreateInfoEXT, aby odfiltrować wszystkie jednostki, do których jest dołączony komponent subsumed_by.

Uprawnienia

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

(poziom ochrony: niebezpieczny)

Obsługa środowiska wykonawczego

Jeśli środowisko wykonawcze obsługuje subumed_by, musi obsługiwać śledzenie płaszczyzny i wskazywać to przez wyliczenie XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT w funkcji xrEnumerateSpatialCapabilitiesEXT .

Jeśli środowisko wykonawcze udostępnia subsumed_by, musi to wskazać, wymieniając XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID jako obsługiwany komponent dla możliwości XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT w funkcji xrEnumerateSpatialCapabilityComponentTypesEXT .

Wszystkie dane komponentu XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID dołączonej encji muszą być identyczne z encją, która ją obejmuje.

Subsumed By Component

Dane komponentu

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

Struktura listy komponentów do odpytywania danych

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 elementów XrSpatialEntityIdEXT .

Aplikacja może wysyłać zapytania do komponentu subsumed_by encji przestrzennych w obiekcie XrSpatialSnapshotEXT, dodając XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID do następnego łańcucha obiektu XrSpatialComponentDataQueryResultEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE z funkcji 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 funkcji xrQuerySpatialComponentDataEXT, jeśli wartość subsumedUniqueIdCount jest mniejsza niż XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Prawidłowe użycie (domyślne)

  •  Rozszerzenie XR_ANDROID_spatial_component_subsumed_by musi być włączone przed użyciem funkcji 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 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 ją włączyć, dodając wyliczenie do listy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents w strukturze 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 uwzględnić XrSpatialDiscoveryUniqueEntitiesFilterANDROID w następnym łańcuchu XrSpatialDiscoverySnapshotCreateInfoEXT, aby uzyskać migawkę z encjami, które nie są objęte inną encją.

Jeśli aplikacje łączą XrSpatialDiscoveryUniqueEntitiesFilterANDROIDXrSpatialDiscoverySnapshotCreateInfoEXT, w tym komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROIDXrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE .

Jeśli aplikacja łączy łańcuch XrSpatialDiscoveryUniqueEntitiesFilterANDROID z łańcuchem XrSpatialDiscoverySnapshotCreateInfoEXT, ale nie zawiera żadnych komponentów w łańcuchu XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, środowisko wykonawcze musi uwzględnić w migawce wszystkie obiekty przestrzenne, które mają zestaw komponentów wymienionych w łańcuchu XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents dla funkcji skonfigurowanych dla parametru spatialContext, z wyjątkiem obiektów, które mają komponent XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Prawidłowe użycie (domyślne)

Przykładowy kod

Konfigurowanie funkcji śledzenia samolotów

Poniższy przykładowy kod pokazuje, jak utworzyć kontekst przestrzenny z możliwością XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, która obsługuje subsumed_by.

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

Wykonywanie zapytań o dane komponentu

Poniższy przykładowy kod pokazuje, jak wysyłać zapytania o dane komponentu subsumed_by z kontekstu skonfigurowanego za pomocą XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .

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

Filtrowanie elementów podrzędnych

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

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

Nowe struktury

Nowe stałe wyliczeniowe

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION
  • Rozszerzanie 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.