XR_ANDROID_spatial_component_subsumed_by

Cadena de nombre

XR_ANDROID_spatial_component_subsumed_by

Tipo de extensión

Extensión de instancia

Número de extensión registrada

792

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensión y versión

XR_EXT_spatial_entity
y
XR_EXT_spatial_plane_tracking

Fecha de modificación más reciente

19/8/2025

Estado de IP

No se conocen reclamos de IP.

Colaboradores

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

Descripción general

Esta extensión se basa en XR_EXT_spatial_entity y proporciona un nuevo componente para XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT para exponer el XrSpatialEntityIdEXT que subsume la entidad actual.

Cuando el tiempo de ejecución adquiere suficiente información del entorno para detectar que 2 planos rastreados son en realidad el mismo, el componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID con el ID de uno de los planos se adjunta al otro. A partir de ese momento, la aplicación solo necesita procesar la entidad que no tiene el componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Esta extensión también introduce un nuevo filtro, que la aplicación puede encadenar a XrSpatialDiscoverySnapshotCreateInfoEXT para filtrar cualquier entidad que tenga el componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Permisos

Las aplicaciones para Android deben tener el permiso android.permission.SCENE_UNDERSTANDING_COARSE que aparece en su manifiesto, ya que esta extensión rastrea planos en el entorno. El permiso android.permission.SCENE_UNDERSTANDING_COARSE se considera un permiso peligroso.

(nivel de protección: peligroso)

Asistencia del entorno de ejecución

Si el tiempo de ejecución puede subsumir un plano en otro, debe indicarlo enumerando XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID como un componente compatible para la capacidad XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT en xrEnumerateSpatialCapabilityComponentTypesEXT .

Todos los datos de componentes de la entidad adjunta XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID deben ser idénticos a la entidad que la subsume.

Componente subsumido por

Datos del componente

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID usa la estructura XrSpatialEntityIdEXT para sus datos, que representa el ID de la entidad subsumida.

Estructura de la lista de componentes para consultar datos

La estructura XrSpatialComponentSubsumedByListANDROID se define de la siguiente manera:

typedef struct XrSpatialComponentSubsumedByListANDROID {
    XrStructureType          type;
    void*                    next;
    uint32_t                 subsumedUniqueIdCount;
    XrSpatialEntityIdEXT*    subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;

Descripciones de miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructura.
  • subsumedUniqueIdCount es un uint32_t que describe el recuento de elementos en el array subsumedUniqueIds.
  • subsumedUniqueIds es un array de XrSpatialEntityIdEXT .

La aplicación puede consultar el componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID de las entidades espaciales en un XrSpatialSnapshotEXT agregando XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID a la siguiente cadena de XrSpatialComponentDataQueryResultEXT .

El tiempo de ejecución debe mostrar XR_ERROR_VALIDATION_FAILURE desde xrQuerySpatialComponentDataEXT si XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID está en la siguiente cadena de XrSpatialComponentDataQueryResultEXT :: next, pero XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID no está incluido en XrSpatialComponentDataQueryConditionEXT :: componentTypes .

El tiempo de ejecución debe mostrar XR_ERROR_SIZE_INSUFFICIENT desde xrQuerySpatialComponentDataEXT si subsumedUniqueIdCount es menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

  • La extensión XR_ANDROID_spatial_component_subsumed_by debe habilitarse antes de usar XrSpatialComponentSubsumedByListANDROID.
  • type debe ser XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
  • next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructura
  • subsumedUniqueIds debe ser un puntero a un array de valores subsumedUniqueIdCount XrSpatialEntityIdEXT.
  • El parámetro subsumedUniqueIdCount debe ser mayor que 0

Configuración

Si XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID se enumera en XrSpatialCapabilityComponentTypesEXT :: componentTypes para la capacidad XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, la aplicación puede habilitarla incluyendo la enumeración en la lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents de la estructura derivada XrSpatialCapabilityConfigurationBaseHeaderEXT de la capacidad que admite este componente.

Filtrar entidades subsumidas

La estructura XrSpatialDiscoveryUniqueEntitiesFilterANDROID se define de la siguiente manera:

typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
    XrStructureType    type;
    const void*        next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;

Descripciones de miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructura.

La aplicación puede incluir XrSpatialDiscoveryUniqueEntitiesFilterANDROID en la cadena next de XrSpatialDiscoverySnapshotCreateInfoEXT para obtener una instantánea con entidades que no están subsumidas por otra entidad.

Si las aplicaciones encadenan XrSpatialDiscoveryUniqueEntitiesFilterANDROID a XrSpatialDiscoverySnapshotCreateInfoEXT mientras incluyen el componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID en XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , el tiempo de ejecución debe mostrar XR_ERROR_VALIDATION_FAILURE .

Si la aplicación encadena XrSpatialDiscoveryUniqueEntitiesFilterANDROID a XrSpatialDiscoverySnapshotCreateInfoEXT, pero no incluye ningún componente en XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, el tiempo de ejecución debe incluir todas las entidades espaciales en la instantánea que tienen el conjunto de componentes que se enumeran en XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents para las capacidades configuradas para spatialContext, excepto las entidades que tienen el componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Uso válido (implícito)

Ejemplo de código

Configura la capacidad de seguimiento de planos

En el siguiente ejemplo de código, se muestra cómo crear un contexto espacial con la capacidad XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT que admite 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))

Consulta datos de componentes

En el siguiente ejemplo de código, se muestra cómo consultar datos de componentes XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID desde el contexto configurado con 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);

Filtrar entidades subsumidas

En el siguiente ejemplo de código, se muestra cómo filtrar entidades con el componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID adjunto de la instantánea de descubrimiento con el filtro, así como consultar el ID de entidad de las entidades subsumidas.

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

Nuevas estructuras

Nuevas constantes de enum

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION

  • Extensión de XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

  • Extensión de XrStructureType :

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

Problemas

Historial de versiones

  • Revisión 1, 19/11/2025 (Brian Chen)

    • Descripción inicial de la extensión