XR_ANDROID_geospatial_anchor

String de nome

XR_ANDROID_geospatial_anchor

Tipo de extensão

Extensão de instância

Número da extensão registrada

798

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_ANDROID_geospatial
e
XR_EXT_future
e
XR_EXT_spatial_entity
e
XR_EXT_spatial_anchor

Data da última modificação

2025-10-30

Status do IP

Não há reivindicações de IP conhecidas.

Colaboradores

John Ullman, Google
Ben King, Google
Nihav Jain, Google
Jared Finder, Google

Visão geral

Essa extensão oferece âncoras geoespaciais e de superfície que se baseiam na extensão geoespacial básica. As âncoras geoespaciais são posicionadas no espaço em relação à Terra em uma determinada latitude, longitude e altitude. As âncoras de superfície são âncoras relativas à Terra que são colocadas em uma determinada latitude, longitude e altitude em relação a uma superfície, conforme conhecido pelo Serviço de posicionamento visual. À medida que a precisão da posição do tempo de execução em relação à Terra melhora, a postura da âncora se ajusta de acordo.

Capacidade do sistema para âncoras geoespaciais

A estrutura XrSystemGeospatialAnchorPropertiesANDROID é definida da seguinte maneira:

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no OpenXR principal ou nesta extensão.
  • maxSurfaceAnchorCount é um uint32_t que indica o número máximo de âncoras de superfície que podem ser criadas.

Um aplicativo pode inspecionar os recursos de âncora geoespacial do sistema encadeando uma estrutura XrSystemGeospatialAnchorPropertiesANDROID à XrSystemProperties ao chamar xrGetSystemProperties .

Se XrSystemGeospatialPropertiesANDROID :: supportsGeospatial for XR_TRUE , maxSurfaceAnchorCount vai indicar o número máximo de fixações de superfície compatíveis com o tempo de execução. O limite precisa ser maior que 0 nesse caso.

Se XrSystemGeospatialPropertiesANDROID :: supportsGeospatial não for XR_TRUE , então maxSurfaceAnchorCount precisa ser 0.

Uso válido (implícito)

Rastreamento de planos para âncoras

A estrutura XrGeospatialTrackerAnchorTrackingInfoANDROID é definida como:

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • shouldTrackPlanes é um XrBool32 que indica se o rastreador geoespacial vai rastrear planos para melhorar o posicionamento de fixações bloqueadas na superfície.

O rastreamento de planos pode ser ativado para melhorar o posicionamento de âncoras fixadas na superfície.

Se o aplicativo quiser ativar o rastreamento de planos para melhorar as posturas de âncora de superfície, ele poderá encadear uma estrutura XrGeospatialTrackerAnchorTrackingInfoANDROID a XrGeospatialTrackerCreateInfoANDROID ao chamar xrCreateGeospatialTrackerANDROID .

Uso válido (implícito)

Âncoras geoespaciais

A função xrCreateGeospatialAnchorANDROID é definida como:

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

Descrições dos parâmetros

  • spatialContext é o XrSpatialContextEXT em que a âncora será criada. O contexto precisa ser configurado para XR_SPATIAL_CAPABILITY_ANCHOR_EXT. Caso contrário, o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE.
  • createInfo é um ponteiro para XrGeospatialAnchorCreateInfoANDROID que contém parâmetros de criação de âncora.
  • anchorEntityId é um ponteiro para XrSpatialEntityIdEXT em que o ID da entidade âncora é retornado.

Se o XrGeospatialTrackerANDROID especificado em XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker não estiver no estado XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, o tempo de execução deverá retornar XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrGeospatialAnchorCreateInfoANDROID é definida como:

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • geospatialTracker é o XrGeospatialTrackerANDROID a ser usado para criar a âncora.
  • geospatialPose é um ponteiro para XrGeospatialPoseANDROID que define a localização e a orientação da âncora.

Uso válido (implícito)

Anúncios fixos na superfície

As âncoras de superfície são colocadas em relação a uma superfície, como terreno ou telhados.

A enumeração XrSurfaceAnchorTypeANDROID é definida como:

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

A enumeração XrSurfaceAnchorTypeANDROID especifica o tipo de superfície em relação a uma âncora.

Os enumeradores têm os seguintes valores:

Descrição da enumeração

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Tipo de uma âncora colocada em relação ao solo.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Tipo de âncora colocada em relação ao telhado ou ao chão quando não há um edifício.

A função xrCreateSurfaceAnchorAsyncANDROID é definida como:

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

Descrições dos parâmetros

  • spatialContext é o XrSpatialContextEXT em que a âncora será criada.
  • createInfo é um ponteiro para XrSurfaceAnchorCreateInfoANDROID que contém parâmetros de criação de âncora.
  • future é um ponteiro para XrFutureEXT que vai armazenar o resultado da operação assíncrona.

A função xrCreateSurfaceAnchorAsyncANDROID inicia uma operação assíncrona para criar uma âncora de superfície. Ao contrário das âncoras geoespaciais padrão, o tempo de execução pode buscar dados de terreno para determinar a altitude correta. O ambiente de execução precisa retornar XR_ERROR_LIMIT_REACHED se o aplicativo tentar criar mais de XrSystemGeospatialAnchorPropertiesANDROID :: âncoras de superfície maxSurfaceAnchorCount por vez. Se o XrGeospatialTrackerANDROID especificado em XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker não estiver no estado XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, o tempo de execução deverá retornar XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . A operação pode falhar de forma assíncrona com o resultado XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID se não houver dados de superfície para o local especificado. O tempo de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se XR_SPATIAL_CAPABILITY_ANCHOR_EXT não tiver sido configurado para spatialContext .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrSurfaceAnchorCreateInfoANDROID é definida como:

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • geospatialTracker é o XrGeospatialTrackerANDROID a ser usado.
  • surfaceAnchorType é o XrSurfaceAnchorTypeANDROID da âncora.
  • eastUpSouthOrientation é a orientação em relação a um sistema de coordenadas em que +X=Leste, +Y=Cima e +Z=Sul.
  • latitude é a latitude em graus, entre -89,9 e +89,9.
  • longitude é a longitude em graus, entre -180 e +180.
  • altitudeRelativeToSurface é a altitude em metros em relação à superfície especificada por surfaceAnchorType .

Uso válido (implícito)

A função xrCreateSurfaceAnchorCompleteANDROID é definida como:

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     completion);

Descrições dos parâmetros

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrSurfaceAnchorCreateCompletionANDROID contém o resultado da criação assíncrona de uma âncora de superfície.

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • futureResult é o XrResult da operação de criação. Se futureResult for XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , uma estrutura na cadeia next poderá fornecer mais informações sobre a falha.
  • anchorEntityId é o XrSpatialEntityIdEXT da âncora criada ou XR_NULL_SPATIAL_ENTITY_ID_EXT se futureResult não for XR_SUCCESS .

Códigos de retorno futuros

Valores de futureResult:

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Uso válido (implícito)

Exemplo

Criar uma âncora de terreno

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

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

  // ... wait until future is ready ...

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

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

XrFuturePollInfoEXT anchorPollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT anchorPollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
anchorPollInfo.future = anchorFuture;
anchorPollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (anchorPollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &anchorPollInfo, &anchorPollResult));
}

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de enumeração

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION

  • Extensão de XrResult :

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

  • Extensão de XrStructureType :

    • XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

Problemas

Histórico de versões

  • Revisão 1, 30/10/2025 (Ben King)

    • Rascunho inicial.