XR_EXT_spatial_plane_tracking

String de nome

XR_EXT_spatial_plane_tracking

Tipo de extensão

Extensão de instância

Número de ramal registrado

742

Revisão

1

Status de ratificação

Ratified

Dependências de extensão e versão

XR_EXT_spatial_entity

Colaboradores

Nihav Jain, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Visão geral

Essa extensão se baseia em XR_EXT_spatial_entity e define o recurso espacial de rastreamento de plano para o framework de entidade espacial.

Suporte ao ambiente de execução

Se o ambiente de execução for compatível com o rastreamento de planos, ele precisa indicar isso enumerando XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT em xrEnumerateSpatialCapabilitiesEXT .

Configuração

A estrutura XrSpatialCapabilityConfigurationPlaneTrackingEXT é definida como:

typedef struct XrSpatialCapabilityConfigurationPlaneTrackingEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationPlaneTrackingEXT;

Descrições dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• capability é um XrSpatialCapabilityEXT e precisa ser XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .
• enabledComponentCount é um uint32_t que descreve a contagem de elementos na matriz enabledComponents.
• enabledComponents é um ponteiro para uma matriz de XrSpatialComponentTypeEXT .

Os aplicativos podem ativar o recurso espacial XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT incluindo um ponteiro para uma estrutura XrSpatialCapabilityConfigurationPlaneTrackingEXT em XrSpatialContextCreateInfoEXT :: capabilityConfigs .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se capability não for XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .

Uso válido (implícito)

• A extensão XR_EXT_spatial_plane_tracking precisa ser ativada antes de usar XrSpatialCapabilityConfigurationPlaneTrackingEXT.
• type precisa ser XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• capability precisa ser um valor XrSpatialCapabilityEXT válido
• enabledComponents precisa ser um ponteiro para uma matriz de valores enabledComponentCount válidos de XrSpatialComponentTypeEXT
• O parâmetro enabledComponentCount precisa ser maior que 0.

Componentes garantidos

Um ambiente de execução compatível com XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT precisa fornecer os seguintes componentes espaciais como componentes garantidos de todas as entidades descobertas por essa capacidade e precisa enumerá-los em xrEnumerateSpatialCapabilityComponentTypesEXT :

• XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
• XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Componente 2D limitado

O componente 2D limitado fornece o centro e as extensões do plano representado pela entidade em que ele está. Consulte Bounded 2D para mais detalhes.

Componente de alinhamento de plano

Dados do componente

typedef enum XrSpatialPlaneAlignmentEXT {
    XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_UPWARD_EXT = 0,
    XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_DOWNWARD_EXT = 1,
    XR_SPATIAL_PLANE_ALIGNMENT_VERTICAL_EXT = 2,
    XR_SPATIAL_PLANE_ALIGNMENT_ARBITRARY_EXT = 3,
    XR_SPATIAL_PLANE_ALIGNMENT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPlaneAlignmentEXT;

A enumeração XrSpatialPlaneAlignmentEXT descreve o alinhamento do plano associado à entidade espacial com um componente XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT.

Os valores de enumeração têm os seguintes significados:

Descrição do tipo enumerado

XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_UPWARD_EXT

A entidade é horizontal e está voltada para cima (por exemplo, o chão).

XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_DOWNWARD_EXT

A entidade é horizontal e está voltada para baixo (por exemplo, teto).

XR_SPATIAL_PLANE_ALIGNMENT_VERTICAL_EXT

A entidade é vertical (por exemplo, parede).

XR_SPATIAL_PLANE_ALIGNMENT_ARBITRARY_EXT

A entidade tem uma orientação arbitrária, não vertical e não horizontal.

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentPlaneAlignmentListEXT é definida como:

typedef struct XrSpatialComponentPlaneAlignmentListEXT {
    XrStructureType                type;
    void*                          next;
    uint32_t                       planeAlignmentCount;
    XrSpatialPlaneAlignmentEXT*    planeAlignments;
} XrSpatialComponentPlaneAlignmentListEXT;

Descrições dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• planeAlignmentCount é um uint32_t que descreve a contagem de elementos na matriz planeAlignments.
• planeAlignments é uma matriz de XrSpatialPlaneAlignmentEXT .

Para consultar o componente de alinhamento de plano das entidades espaciais em um XrSpatialSnapshotEXT , inclua XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT em XrSpatialComponentDataQueryConditionEXT :: componentTypes e adicione XrSpatialComponentPlaneAlignmentListEXT à cadeia XrSpatialComponentDataQueryResultEXT :: next.

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentPlaneAlignmentListEXT estiver na cadeia XrSpatialComponentDataQueryResultEXT :: next, mas XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se planeAlignmentCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

• A extensão XR_EXT_spatial_plane_tracking precisa ser ativada antes de usar XrSpatialComponentPlaneAlignmentListEXT.
• type precisa ser XR_TYPE_SPATIAL_COMPONENT_PLANE_ALIGNMENT_LIST_EXT
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• planeAlignments precisa ser um ponteiro para uma matriz de valores planeAlignmentCount XrSpatialPlaneAlignmentEXT
• O parâmetro planeAlignmentCount precisa ser maior que 0.

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, um aplicativo pode ativá-lo incluindo o enumerador na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura derivada de XrSpatialCapabilityConfigurationBaseHeaderEXT do recurso que oferece suporte a esse componente.

Esse componente não requer nenhuma configuração especial para ser incluído na cadeia XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Componentes opcionais

Um ambiente de execução compatível com XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT pode aceitar outros componentes espaciais além dos listados na seção Componentes garantidos. Um aplicativo usa xrEnumerateSpatialCapabilityComponentTypesEXT para receber a lista completa de componentes compatíveis com um ambiente de execução e, em seguida, configura os que são de interesse ao criar o contexto espacial.

Componente de malha 2D

Dados do componente

O XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT usa a estrutura XrSpatialMeshDataEXT para os dados.

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentMesh2DListEXT é definida como:

typedef struct XrSpatialComponentMesh2DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh2DListEXT;

Descrições dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• meshCount é um uint32_t que descreve a contagem de elementos na matriz meshes.
• meshes é uma matriz de XrSpatialMeshDataEXT .

Para consultar o componente de malha 2D das entidades espaciais em um XrSpatialSnapshotEXT , inclua XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT em XrSpatialComponentDataQueryConditionEXT :: componentTypes e adicione XrSpatialComponentMesh2DListEXT à cadeia XrSpatialComponentDataQueryResultEXT :: next.

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentMesh2DListEXT estiver na cadeia XrSpatialComponentDataQueryResultEXT :: next, mas XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se meshCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Para o XrSpatialMeshDataEXT preenchido pelo ambiente de execução na matriz meshes, o XrSpatialBufferEXT :: bufferType para XrSpatialMeshDataEXT :: vertexBuffer precisa ser XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT e XrSpatialBufferEXT :: bufferType para XrSpatialMeshDataEXT :: indexBuffer precisa ser XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

Uso válido (implícito)

• A extensão XR_EXT_spatial_plane_tracking precisa ser ativada antes de usar XrSpatialComponentMesh2DListEXT
• type precisa ser XR_TYPE_SPATIAL_COMPONENT_MESH_2D_LIST_EXT
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• meshes precisa ser um ponteiro para uma matriz de estruturas meshCount XrSpatialMeshDataEXT
• O parâmetro meshCount precisa ser maior que 0.

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, um aplicativo pode ativá-lo incluindo o enumerador na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura derivada de XrSpatialCapabilityConfigurationBaseHeaderEXT do recurso que oferece suporte a esse componente.

Esse componente não requer nenhuma configuração especial para ser incluído na cadeia XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Componente de polígono 2D

Dados do componente

A estrutura XrSpatialPolygon2DDataEXT é definida como:

typedef struct XrSpatialPolygon2DDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
} XrSpatialPolygon2DDataEXT;

Descrições dos membros

• origin é um XrPosef que define a origem do polígono. Todos os vértices do polígono são relativos a essa origem no plano X-Y.
• vertexBuffer é um XrSpatialBufferEXT que fornece o ID de um buffer do tipo XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT e representa o buffer de vértice da entidade em que esse componente está. Os vértices precisam ser retornados em sentido anti-horário. O polígono representado por esses vértices não pode se cruzar e pode ser côncavo.

XrSpatialBufferEXT :: bufferType para vertexBuffer precisa ser XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

Uso válido (implícito)

• A extensão XR_EXT_spatial_plane_tracking precisa ser ativada antes de usar XrSpatialPolygon2DDataEXT.
• vertexBuffer precisa ser uma estrutura XrSpatialBufferEXT válida

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentPolygon2DListEXT é definida como:

typedef struct XrSpatialComponentPolygon2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      polygonCount;
    XrSpatialPolygon2DDataEXT*    polygons;
} XrSpatialComponentPolygon2DListEXT;

Descrições dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• polygonCount é um uint32_t que descreve a contagem de elementos na matriz polygons.
• polygons é uma matriz de XrSpatialPolygon2DDataEXT .

Para consultar o componente de polígono 2D das entidades espaciais em um XrSpatialSnapshotEXT , inclua XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT em XrSpatialComponentDataQueryConditionEXT :: componentTypes e adicione XrSpatialComponentPolygon2DListEXT à cadeia XrSpatialComponentDataQueryResultEXT :: next.

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentPolygon2DListEXT estiver na cadeia XrSpatialComponentDataQueryResultEXT :: next, mas XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se polygonCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

• A extensão XR_EXT_spatial_plane_tracking precisa ser ativada antes de usar XrSpatialComponentPolygon2DListEXT
• type precisa ser XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• polygons precisa ser um ponteiro para uma matriz de estruturas polygonCount XrSpatialPolygon2DDataEXT
• O parâmetro polygonCount precisa ser maior que 0.

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, um aplicativo pode ativá-lo incluindo o enumerador na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura derivada de XrSpatialCapabilityConfigurationBaseHeaderEXT do recurso que oferece suporte a esse componente.

Esse componente não requer nenhuma configuração especial para ser incluído na cadeia XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Rótulo semântico de plano

Dados do componente

typedef enum XrSpatialPlaneSemanticLabelEXT {
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT = 2,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT = 3,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT = 4,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT = 5,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPlaneSemanticLabelEXT;

A enumeração XrSpatialPlaneSemanticLabelEXT descreve um conjunto de rótulos semânticos para planos.

Descrição do tipo enumerado

XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT

O ambiente de execução não conseguiu classificar essa entidade.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT

A entidade é um piso.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT

A entidade é uma parede.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT

A entidade é um teto.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT

A entidade é uma tabela.

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentPlaneSemanticLabelListEXT é definida como:

typedef struct XrSpatialComponentPlaneSemanticLabelListEXT {
    XrStructureType                    type;
    void*                              next;
    uint32_t                           semanticLabelCount;
    XrSpatialPlaneSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentPlaneSemanticLabelListEXT;

Descrições dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• semanticLabelCount é um uint32_t que descreve a contagem de elementos na matriz semanticLabels.
• semanticLabels é uma matriz de XrSpatialPlaneSemanticLabelEXT .

Para consultar o componente de rótulo semântico do plano das entidades espaciais em um XrSpatialSnapshotEXT , inclua XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT em XrSpatialComponentDataQueryConditionEXT :: componentTypes e adicione XrSpatialComponentPlaneSemanticLabelListEXT à cadeia XrSpatialComponentDataQueryResultEXT :: next.

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentPlaneSemanticLabelListEXT estiver na próxima cadeia de XrSpatialComponentDataQueryResultEXT :: next, mas XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se semanticLabelCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

• A extensão XR_EXT_spatial_plane_tracking precisa ser ativada antes de usar XrSpatialComponentPlaneSemanticLabelListEXT.
• type precisa ser XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• semanticLabels precisa ser um ponteiro para uma matriz de valores semanticLabelCount XrSpatialPlaneSemanticLabelEXT
• O parâmetro semanticLabelCount precisa ser maior que 0.

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, um aplicativo pode ativá-lo incluindo o enumerador na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura derivada de XrSpatialCapabilityConfigurationBaseHeaderEXT do recurso que oferece suporte a esse componente.

Esse componente não requer nenhuma configuração especial para ser incluído na cadeia XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Código de exemplo

Configurar o recurso de rastreamento de plano

O exemplo de código a seguir demonstra como configurar o recurso de rastreamento de plano ao criar um contexto espacial.

// Check if plane tracking capability is supported
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;
}

// Enumerate supported components for plane tracking capability
XrSpatialCapabilityComponentTypesEXT planeComponents{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));

// Check if polygon 2D and plane semantic labels optional components are supported
const auto supportsComponent = [&planeCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(planeCapabilityComponents.begin(), planeCapabilityComponents.end(), component) != planeCapabilityComponents.end();
};

const bool supportsPolygon2DComponent = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
const bool supportsSemanticLabelComponent = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the 2 guaranteed components of the plane tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};
// Optionally enable polygon2D if it is supported
if (supportsPolygon2DComponent) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
}
// Optionally enable semantic labels if it is supported
if (supportsSemanticLabelComponent) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);
}

XrSpatialCapabilityConfigurationPlaneTrackingEXT planeConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT};
planeConfig.capability = XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT;
planeConfig.enabledComponentCount = enabledComponents.size();
planeConfig.enabledComponents = enabledComponents.data();

std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
  reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&planeConfig),
};

XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
XrFutureEXT createContextFuture;
CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

waitUntilReady(createContextFuture);

XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS) {
  return;
}

spatialContext = completion.spatialContext;

// ...
// Discover entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Descobrir entidades espaciais e consultar dados de componentes

O exemplo de código a seguir demonstra como descobrir entidades espaciais para um contexto configurado com XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT e consultar os dados do componente.

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};
if (supportsPolygon2DComponent) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
}
if (supportsSemanticLabelComponent) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT bounded2DList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    bounded2DList.boundCount = bounded2D.size();
    bounded2DList.bounds = bounded2D.data();
    queryResult.next = &bounded2DList;

    std::vector<XrSpatialPolygon2DDataEXT> polygons;
    XrSpatialComponentPolygon2DListEXT polygonList{XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT};
    if (supportsPolygon2DComponent) {
      polygons.resize(queryResult.entityIdCountOutput);
      polygonList.polygonCount = polygons.size();
      polygonList.polygons = polygons.data();
      polygonList.next = queryResult.next;
      queryResult.next = &polygonList;
    }

    std::vector<XrSpatialPlaneSemanticLabelEXT> semanticLabels;
    XrSpatialComponentPlaneSemanticLabelListEXT semanticLabelsList{XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT};
    if (supportsSemanticLabelComponent) {
      semanticLabels.resize(queryResult.entityIdCountOutput);
      semanticLabelsList.semanticLabelCount = semanticLabels.size();
      semanticLabelsList.semanticLabels = semanticLabels.data();
      semanticLabelsList.next = queryResult.next;
      queryResult.next = &semanticLabelsList;
    }

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] != XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        continue;
      }

      // 2D bounds for entity entityIds[i] is bounded2D[i].extents centered on bounded2D[i].center.

      if (supportsPolygon2DComponent) {
        // 2D polygon for entity entityIds[i] is the buffer represented by polygons[i].bufferId.
        // Application uses flink:xrGetSpatialBufferVector2fEXT to get the buffer data.
      }

      if (supportsSemanticLabelComponent) {
        // semantic label for entity entityIds[i] is semanticLabels[i].
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

Novas estruturas

• XrSpatialCapabilityConfigurationPlaneTrackingEXT
• XrSpatialPolygon2DDataEXT

• Estendendo XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentMesh2DListEXT
  • XrSpatialComponentPlaneAlignmentListEXT
  • XrSpatialComponentPlaneSemanticLabelListEXT
  • XrSpatialComponentPolygon2DListEXT

Novos tipos enumerados

• XrSpatialPlaneAlignmentEXT
• XrSpatialPlaneSemanticLabelEXT

Novas constantes de tipo enumerado

• XR_EXT_SPATIAL_PLANE_TRACKING_EXTENSION_NAME
• XR_EXT_spatial_plane_tracking_SPEC_VERSION

• Estendendo XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

• Estendendo XrSpatialComponentTypeEXT :

  • XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT
  • XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT
  • XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

• Estendendo XrStructureType :

  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT
  • XR_TYPE_SPATIAL_COMPONENT_MESH_2D_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_PLANE_ALIGNMENT_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT

Problemas

Histórico de versões

• Revisão 1, 2024-07-02 (Nihav Jain, Google)

  • Descrição inicial da extensão