XR_ANDROID_spatial_component_subsumed_by

Name String

XR_ANDROID_spatial_component_subsumed_by

Tipo de extensión

Extensión de instancia

Número de extensión registrado

792

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

XR_EXT_spatial_entity
y
XR_EXT_spatial_plane_tracking

Fecha de la última modificación

19/8/2025

Estado de la IP

No hay reclamos de IP conocidos.

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 componente nuevo para que XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT exponga el XrSpatialEntityIdEXT que subsume la entidad actual.

Cuando el entorno de ejecución haya adquirido suficiente información del entorno para detectar que 2 planos con seguimiento son, en realidad, el mismo, el componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID con el ID de uno de los planos se adjuntará 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 presenta un filtro nuevo, que la aplicación puede encadenar a XrSpatialDiscoverySnapshotCreateInfoEXT para filtrar las entidades que tienen el componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Permisos

Las aplicaciones para Android deben tener el permiso android.permission.SCENE_UNDERSTANDING_COARSE en su manifiesto, ya que esta extensión hace un seguimiento de los planos del 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 entorno de ejecución es capaz de 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 los componentes de la entidad adjunta XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID deben ser idénticos a los de la entidad que la subsume.

Subsumed By Component

Datos de componentes

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

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
  • 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 entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE de 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 se incluye en XrSpatialComponentDataQueryConditionEXT :: componentTypes .

El entorno de ejecución debe devolver XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT si subsumedUniqueIdCount es menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

  • La extensión XR_ANDROID_spatial_component_subsumed_by debe estar habilitada 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 estructuras
  • 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 los miembros

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

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 entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

Si la aplicación encadena XrSpatialDiscoveryUniqueEntitiesFilterANDROID a XrSpatialDiscoverySnapshotCreateInfoEXT, pero no enumera ningún componente en XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, el entorno de ejecución debe incluir todas las entidades espaciales en la instantánea que tengan el conjunto de componentes que se enumeran en XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents para las capacidades configuradas para spatialContext, excepto las entidades que tengan 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 código de ejemplo, 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))

Datos de componentes de consulta

En el siguiente ejemplo de código, se muestra cómo consultar los datos del componente 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);

Cómo filtrar entidades subsumidas

En el siguiente código de ejemplo, se muestra cómo filtrar las 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);

Estructuras nuevas

Nuevas constantes de enum

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION

  • Extiende XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

  • Extiende 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 de noviembre de 2025 (Brian Chen)

    • Descripción inicial de la extensión.