XR_EXT_spatial_anchor

String de nome

XR_EXT_spatial_anchor

Tipo de extensão

Extensão de instância

Número de ramal registrado

763

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 permite que os aplicativos criem âncoras espaciais, que são pontos arbitrários no ambiente físico do usuário que serão rastreados pelo ambiente de execução. O ambiente de execução precisa ajustar a posição e a orientação da origem da âncora ao longo do tempo, conforme necessário, de forma independente de todos os outros espaços e âncoras, para garantir que ela mantenha o mapeamento original para o mundo real.

Uma âncora que rastreia uma determinada posição e orientação em um XrSpatialContextEXT é representada como uma entidade espacial com (ou "que tem") o componente XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT.

Benefício de usar âncoras

À medida que o ambiente de execução entende melhor o ambiente físico do usuário ao longo da vida útil de um XrSpatialContextEXT , os objetos virtuais podem parecer se afastar do local onde foram colocados pelo aplicativo, o que afeta o realismo do aplicativo e a qualidade da experiência do usuário. Ao criar uma âncora perto de onde um objeto virtual é colocado e sempre renderizar esse objeto em relação à âncora, um aplicativo pode garantir que cada objeto virtual permaneça na mesma posição e orientação no ambiente físico. Além disso, ao contrário de certos espaços de referência, as âncoras não são afetadas pela recentralização no nível do sistema.

Suporte ao ambiente de execução

Se o ambiente de execução for compatível com âncoras espaciais, ele precisa indicar isso enumerando XR_SPATIAL_CAPABILITY_ANCHOR_EXT em xrEnumerateSpatialCapabilitiesEXT .

Configuração

A estrutura XrSpatialCapabilityConfigurationAnchorEXT é definida como:

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

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 .
  • 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_ANCHOR_EXT incluindo um ponteiro para uma estrutura XrSpatialCapabilityConfigurationAnchorEXT em XrSpatialContextCreateInfoEXT :: capabilityConfigs .

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

Uso válido (implícito)

Componentes garantidos

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

  • XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Componente de âncora

Dados do componente

O XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT usa XrPosef para os dados, que fornecem a posição e a orientação da âncora.

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentAnchorListEXT é definida como:

typedef struct XrSpatialComponentAnchorListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           locationCount;
    XrPosef*           locations;
} XrSpatialComponentAnchorListEXT;

Descrições dos membros

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

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

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

Uso válido (implícito)

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_ANCHOR_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.

Como criar uma âncora espacial

A função xrCreateSpatialAnchorEXT é definida como:

XrResult xrCreateSpatialAnchorEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpatialEntityEXT*                         anchorEntity);

Descrições dos parâmetros

O aplicativo pode criar uma âncora espacial usando xrCreateSpatialAnchorEXT .

Para receber dados de componentes atualizados de uma âncora, transmita o valor preenchido em anchorEntity para XrSpatialUpdateSnapshotCreateInfoEXT :: entities ao criar um snapshot. O aplicativo pode usar anchorEntityId para identificar exclusivamente essa âncora na matriz XrSpatialComponentDataQueryResultEXT :: entityIds ao usar xrQuerySpatialComponentDataEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrCreateSpatialAnchorEXT se XR_SPATIAL_CAPABILITY_ANCHOR_EXT não tiver sido configurado para spatialContext . Consulte Configuração para saber como configurar um XrSpatialContextEXT para o recurso XR_SPATIAL_CAPABILITY_ANCHOR_EXT.

A âncora representada por anchorEntity só é válida durante o ciclo de vida de spatialContext ou até que o aplicativo chame xrDestroySpatialEntityEXT nela, o que ocorrer primeiro. Outras extensões podem oferecer funções para manter essa âncora recém-criada em várias XrSession ou compartilhá-la entre limites de processo com outros aplicativos.

Uma âncora recém-criada, até ser destruída, precisa ser detectável no contexto espacial pai. Isso significa que o ambiente de execução precisa incluir anchorEntityId no snapshot criado usando xrCreateSpatialDiscoverySnapshotAsyncEXT para spatialContext se a âncora corresponder aos critérios de descoberta definidos em XrSpatialDiscoverySnapshotCreateInfoEXT . A âncora recém-criada também pode ser detectável em outros contextos espaciais configurados com XR_SPATIAL_CAPABILITY_ANCHOR_EXT, mas com um XrSpatialEntityIdEXT diferente, já que um XrSpatialEntityIdEXT específico é exclusivo do XrSpatialContextEXT .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID (se XR_ANDROID_spatial_entity_bound_anchor estiver ativado)
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT (se XR_ANDROID_spatial_entity_bound_anchor estiver ativado)

A estrutura XrSpatialAnchorCreateInfoEXT é definida como:

typedef struct XrSpatialAnchorCreateInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrPosef            pose;
} XrSpatialAnchorCreateInfoEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • baseSpace é o XrSpace em que pose é aplicado.
  • time é o XrTime em que baseSpace está localizado (e pose é aplicado).
  • pose é o local da entidade âncora.

Uso válido (implícito)

Consultar pose de âncora

Depois que a âncora é criada, o ambiente de execução precisa ajustar a posição e a orientação dela ao longo do tempo em relação a outros espaços para manter o melhor alinhamento possível com o local original no mundo real, mesmo que isso mude a relação da âncora com o XrSpatialAnchorCreateInfoEXT :: baseSpace original usado para inicializá-la.

O aplicativo pode usar xrCreateSpatialUpdateSnapshotEXT com o XrSpatialEntityEXT da âncora para criar um novo XrSpatialSnapshotEXT e, em seguida, consultar o componente XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT desse snapshot usando xrQuerySpatialComponentDataEXT . O aplicativo pode adicionar XrSpatialComponentAnchorListEXT a XrSpatialComponentDataQueryResultEXT :: next para recuperar os dados de local mais recentes das âncoras.

O ambiente de execução pode definir o estado de rastreamento de uma âncora recém-criada como XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT . O aplicativo precisa ler apenas o estado da entidade âncora fornecido em XrSpatialComponentDataQueryResultEXT :: entityStates e os dados do componente âncora da entidade se o estado de rastreamento for XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT .

Diretrizes para usar âncoras

  • A pose de cada âncora é ajustada de forma independente de qualquer outra âncora ou espaço. Os objetos virtuais ancorados separadamente podem se deslocar ou girar em relação uns aos outros, quebrando a hierarquia espacial nos casos em que esses objetos virtuais precisam permanecer no lugar em relação uns aos outros. Nesses casos, o aplicativo precisa reutilizar a mesma âncora para todos os objetos virtuais que não se movem em relação uns aos outros.
  • O aplicativo precisa destruir todos os identificadores XrSpatialEntityEXT de âncoras que não estão mais sendo usadas para liberar os recursos que o ambiente de execução pode estar usando para rastrear essas âncoras.

Código de exemplo

Configurar o recurso de âncora

O exemplo a seguir demonstra como configurar o recurso de âncora ao criar um contexto espacial.

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{

  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

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

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

// ...
// Create spatial anchors and get their latest pose in the frame loop.
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Criar uma âncora espacial e ver a localização dela

O exemplo a seguir demonstra como criar uma âncora espacial e receber a pose dela em cada frame.

XrSpatialAnchorCreateInfoEXT createInfo{XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT};
createInfo.baseSpace = localSpace;
createInfo.time = predictedDisplayTime;
createInfo.pose = {{0, 0, 0, 1}, {1, 1, 1}};

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpatialEntityEXT spatialAnchorEntity;
CHK_XR(xrCreateSpatialAnchorEXT(spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorEntity));

auto updateAnchorLocation = [&](XrTime time) {
  // We want to get updated data for all components of the entities, so skip specifying componentTypes.
  XrSpatialUpdateSnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.entityCount = 1;
  snapshotCreateInfo.entities = &spatialAnchorEntity;
  snapshotCreateInfo.baseSpace = localSpace;
  snapshotCreateInfo.time = time;

  XrSpatialSnapshotEXT snapshot;
  CHK_XR(xrCreateSpatialUpdateSnapshotEXT(spatialContext, &snapshotCreateInfo, &snapshot));

  // Query for the entities that have the anchor component on them.
  std::array<XrSpatialComponentTypeEXT, 1> componentsToQuery {XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT};
  XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
  queryCond.componentTypeCount = componentsToQuery.size();
  queryCond.componentTypes = componentsToQuery.data();

  XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
  CHK_XR(xrQuerySpatialComponentDataEXT(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();

  // query for the pose data
  std::vector<XrPosef> locations(queryResult.entityIdCountOutput);
  XrSpatialComponentAnchorListEXT locationList{XR_TYPE_SPATIAL_COMPONENT_ANCHOR_LIST_EXT};
  locationList.locationCount = locations.size();
  locationList.locations = locations.data();
  queryResult.next = &locationList;

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

  for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
    if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
      // Pose for entity entityIds[i] is locations[i].
    }
  }

  CHK_XR(xrDestroySpatialSnapshotEXT(snapshot));
};


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

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

  updateAnchorLocation(time);

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

CHK_XR(xrDestroySpatialEntityEXT(spatialAnchorEntity));

Novos comandos

Novas estruturas

Novas constantes de tipo enumerado

  • XR_EXT_SPATIAL_ANCHOR_EXTENSION_NAME
  • XR_EXT_spatial_anchor_SPEC_VERSION

  • Estendendo XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_ANCHOR_EXT

  • Estendendo XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

  • Estendendo XrStructureType :

    • XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT
    • XR_TYPE_SPATIAL_COMPONENT_ANCHOR_LIST_EXT

Problemas

Histórico de versões

  • Revisão 1, 10/07/2024 (Nihav Jain, Google)

    • Descrição inicial da extensão