XR_ANDROID_geospatial

String de nome

XR_ANDROID_geospatial

Tipo de extensão

Extensão de instância

Número de ramal registrado

790

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_EXT_future

Data da última modificação

2025-12-18

Status do IP

Nenhuma reivindicação de PI conhecida.

Colaboradores

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

Visão geral

Essa extensão fornece o rastreamento geoespacial para a API Geospatial do Google, que oferece geolocalização e orientação precisas e permite que o aplicativo posicione o conteúdo em relação à Terra. Para isso, ele usa uma combinação de rastreamento de movimento, GPS e outros sensores, além do Sistema de Posicionamento Visual (VPS, na sigla em inglês) do Google. O VPS compara as imagens da câmera de um dispositivo com as imagens do Street View para determinar um local exato e uma orientação precisos. A API Geospatial geralmente oferece precisão de posição submétrica (ordens de magnitude melhores que o GPS) e precisão de orientação subgrau.

Para usar as APIs nessa extensão (além de verificar se há suporte para ela), o aplicativo precisa ter definido as credenciais de autenticação por algum mecanismo, como XR_ANDROID_google_cloud_auth . Consulte a documentação da extensão de autenticação para mais detalhes sobre a configuração e os resultados de erro.

Permissões

Os apps Android precisam ter a permissão android.permission.ACCESS_FINE_LOCATION listada no manifesto para usar essa extensão. A permissão android.permission.ACCESS_FINE_LOCATION é considerada perigosa. O aplicativo precisa solicitar a permissão no momento da execução para usar estas funções:

(nível de proteção: perigoso)

Inspecionar a capacidade do sistema

A estrutura XrSystemGeospatialPropertiesANDROID é definida como:

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • supportsGeospatial é um XrBool32 que indica se o sistema atual é compatível com recursos geoespaciais.

Um aplicativo pode verificar se o sistema oferece suporte a recursos geoespaciais encadeando uma estrutura XrSystemGeospatialPropertiesANDROID ao XrSystemProperties ao chamar xrGetSystemProperties .

Se um ambiente de execução retornar XR_FALSE para supportsGeospatial, o sistema não será compatível com recursos geoespaciais e, portanto, precisará retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateGeospatialTrackerANDROID . O aplicativo precisa evitar o uso da funcionalidade geoespacial quando supportsGeospatial for XR_FALSE .

Uso válido (implícito)

Criar um identificador do Rastreador geoespacial

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

A função xrCreateGeospatialTrackerANDROID é definida como:

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

Descrições dos parâmetros

Um aplicativo pode criar um identificador XrGeospatialTrackerANDROID chamando xrCreateGeospatialTrackerANDROID . O identificador XrGeospatialTrackerANDROID retornado pode ser usado em chamadas de API. Se o aplicativo não tiver as permissões necessárias, o ambiente de execução precisará retornar XR_ERROR_PERMISSION_INSUFFICIENT . Só pode existir um XrGeospatialTrackerANDROID por vez para uma XrSession específica. O aplicativo precisa garantir que todos os objetos XrGeospatialTrackerANDROID anteriores tenham sido destruídos antes de chamar essa função novamente. Caso contrário, o ambiente de execução precisa retornar XR_ERROR_LIMIT_REACHED. Se o rastreador for criado, ele vai entrar inicialmente no estado XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , e o aplicativo precisa esperar até que o estado mude para XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID antes de usar o rastreador. Consulte XrEventDataGeospatialTrackerStateChangedANDROID . Se o aplicativo transmitir um XrGeospatialTrackerANDROID que não esteja no estado XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID para uma função que o exija, o ambiente de execução precisará retornar XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

O identificador XrGeospatialTrackerANDROID precisa ser liberado pela função xrDestroyGeospatialTrackerANDROID.

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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrGeospatialTrackerCreateInfoANDROID é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.

Uso válido (implícito)

A função xrDestroyGeospatialTrackerANDROID é definida como:

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Descrições dos parâmetros

Um aplicativo pode usar a função xrDestroyGeospatialTrackerANDROID para liberar o rastreador geoespacial e os recursos relacionados.

Uso válido (implícito)

Concorrência segura

  • O acesso a geospatialTracker e a qualquer identificador filho precisa ser sincronizado externamente.

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Estado do rastreador geoespacial

A enumeração XrGeospatialTrackerStateANDROID é definida como:

typedef enum XrGeospatialTrackerStateANDROID {
    XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID = 0,
    XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID = 1,
    XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID = 2,
    XR_GEOSPATIAL_TRACKER_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGeospatialTrackerStateANDROID;

A enumeração XrGeospatialTrackerStateANDROID identifica os diferentes estados de um rastreador geoespacial.

Os enumeradores têm os seguintes valores:

Descrição do tipo enumerado

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

O Rastreador geoespacial não está em execução.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

O rastreador geoespacial está em execução e pode ser usado.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Falha ao inicializar o Rastreador Geoespacial, que não poderá ser usado.

A estrutura XrEventDataGeospatialTrackerStateChangedANDROID é definida como:

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • geospatialTracker é o XrGeospatialTrackerANDROID cujo estado mudou.
  • state é o novo XrGeospatialTrackerStateANDROID .
  • initializationResult é o resultado do erro se state for XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID. Caso contrário, é XR_SUCCESS.
  • time é o XrTime em que a mudança de estado ocorreu.

A estrutura XrEventDataGeospatialTrackerStateChangedANDROID é enviada quando o estado do rastreador geoespacial muda. Se o aplicativo tiver um XrGeospatialTrackerANDROID válido, ele precisa consultar esse evento. O primeiro evento recebido por um rastreador terá state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Após um período determinado pelo ambiente de execução, o estado precisa mudar para XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID ou XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . Essa transição vai levar um tempo indefinido. Se state mudar para XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , ele precisa ser o último evento recebido para esse rastreador, e o campo initializationResult vai conter o código do erro. Pode levar vários segundos para que um erro ocorra. Nesse caso, o aplicativo precisa destruir o rastreador. Se state mudar para XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , todas as âncoras geoespaciais criadas anteriormente precisam parar de rastrear permanentemente e devem ser destruídas pelo aplicativo. O estado pode alternar entre XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID e XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID um número arbitrário de vezes.

Uso válido (implícito)

Pose geoespacial

A estrutura XrGeospatialPoseANDROID é definida como:

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

Descrições dos membros

  • eastUpSouthOrientation é um XrQuaternionf que define 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 -90 e +90.
  • longitude é a longitude em graus, entre -180 e +180.
  • altitude é a altitude em metros acima do elipsoide WGS84.

A estrutura XrGeospatialPoseANDROID representa uma posição e orientação em relação à Terra usando o elipsoide WGS84.

Uso válido (implícito)

  • A extensão XR_ANDROID_geospatial precisa ser ativada antes de usar XrGeospatialPoseANDROID.
  • latitude precisa ser um valor de double válido
  • longitude precisa ser um valor de double válido
  • altitude precisa ser um valor de double válido

A enumeração XrGeospatialPoseFlagBitsANDROID é definida como:

// Flag bits for XrGeospatialPoseFlagsANDROID
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID = 0x00000001;
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID = 0x00000002;

A enumeração XrGeospatialPoseFlagBitsANDROID especifica flags para poses geoespaciais.

Os bits de flag têm os seguintes significados:

Descrições de flags

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID: indica que o membro de orientação contém dados válidos.
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID: indica que o membro da posição contém dados válidos.

O tipo XrGeospatialPoseFlagsANDROID é uma máscara de bits de XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

Como converter XrPosef em pose geoespacial

A função xrLocateGeospatialPoseFromPoseANDROID é definida como:

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

Descrições dos parâmetros

A função xrLocateGeospatialPoseFromPoseANDROID converte uma pose em XrGeospatialPoseFromPoseLocateInfoANDROID :: space em uma pose geoespacial. Se o estado de geospatialTracker não for XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , o ambiente de execução precisará retornar XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Se a função retornar XR_SUCCESS , o campo poseFlags de geospatialPoseResult em XrGeospatialPoseResultANDROID vai determinar quais campos de saída são válidos. Se XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID não estiver definido em XrGeospatialPoseResultANDROID :: poseFlags , o aplicativo não pode ler os campos XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy ou XrGeospatialPoseResultANDROID :: verticalAccuracy em XrGeospatialPoseResultANDROID . Se XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID não estiver definido em XrGeospatialPoseResultANDROID :: poseFlags , o aplicativo não poderá ler XrGeospatialPoseANDROID :: eastUpSouthOrientation ou XrGeospatialPoseResultANDROID :: orientationYawAccuracy . Se XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID não estiver definido, XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID também não poderá ser definido.

Se a precisão for menor do que o esperado, isso pode indicar que o dispositivo não está usando a localização do VPS. O aplicativo pode instruir o usuário a apontar o dispositivo para placas e edifícios para melhorar a localização.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrGeospatialPoseFromPoseLocateInfoANDROID é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • space é o XrSpace em que pose é definido.
  • time é o XrTime em que pose será avaliado.
  • pose é o XrPosef em space para converter em uma pose geoespacial.

Uso válido (implícito)

A estrutura XrGeospatialPoseResultANDROID é definida como:

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • poseFlags é uma máscara de bits de XrGeospatialPoseFlagsANDROID que indica a validade dos componentes de pose.
  • geospatialPose é o XrGeospatialPoseANDROID resultante.
  • horizontalAccuracy é a precisão horizontal estimada da posição da pose geoespacial, definida como o raio em metros do círculo de 68% de nível de confiança em torno da latitude e longitude fornecidas.
  • verticalAccuracy é a precisão vertical estimada da posição da pose geoespacial, definida como a distância em metros do nível de confiança de 68% em torno da altitude fornecida. Em outras palavras, há 68% de chance de que a altitude real esteja no intervalo [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
  • orientationYawAccuracy é a precisão estimada de guinada da orientação da pose geoespacial, definida como o raio em graus de 68% de nível de confiança em torno da orientação fornecida.

Uso válido (implícito)

Como converter uma pose geoespacial em um XrPosef

A função xrLocateGeospatialPoseANDROID é definida como:

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

Descrições dos parâmetros

A função xrLocateGeospatialPoseANDROID converte uma pose geoespacial em um XrSpaceLocation . Se o XrGeospatialTrackerANDROID não estiver em execução, o ambiente de execução precisa retornar XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Se a função retornar XR_SUCCESS , o campo locationFlags de location em XrSpaceLocation vai determinar quais campos de saída são válidos.

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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrGeospatialPoseLocateInfoANDROID é definida como:

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • space é o XrSpace em que a pose resultante será representada.
  • time é o XrTime em que a pose será localizada.
  • geospatialPose é o XrGeospatialPoseANDROID a ser convertido.

Uso válido (implícito)

Disponibilidade do VPS

A enumeração XrVPSAvailabilityANDROID é definida como:

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

A enumeração XrVPSAvailabilityANDROID indica a disponibilidade do VPS.

Os enumeradores têm os seguintes valores:

Descrição do tipo enumerado

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

O VPS não está disponível perto do local informado.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

O VPS está disponível perto do local informado.

A função xrCheckVpsAvailabilityAsyncANDROID é definida como:

XrResult xrCheckVpsAvailabilityAsyncANDROID(
    XrSession                                   session,
    double                                      latitude,
    double                                      longitude,
    XrFutureEXT*                                future);

Descrições dos parâmetros

  • session é a XrSession a ser usada para a verificação.
  • latitude é a latitude em graus.
  • longitude é a longitude em graus.
  • future é um ponteiro para XrFutureEXT que vai conter o resultado da operação assíncrona.

A disponibilidade do Serviço de Posicionamento Visual (VPS, na sigla em inglês) indica se ele pode ser usado para melhorar a precisão geoespacial em um determinado local.

A função xrCheckVpsAvailabilityAsyncANDROID inicia uma verificação assíncrona da disponibilidade do VPS em um determinado local. O aplicativo não precisa de um XrGeospatialTrackerANDROID para chamar essa função e pode usar o resultado dessa operação para decidir se vai criar um. Se o aplicativo não tiver as permissões necessárias, o ambiente de execução precisará retornar XR_ERROR_PERMISSION_INSUFFICIENT .

Uso válido (implícito)

  • A extensão XR_ANDROID_geospatial precisa ser ativada antes de chamar xrCheckVpsAvailabilityAsyncANDROID.
  • session precisa ser um identificador XrSession válido
  • latitude precisa ser um valor de double válido
  • longitude precisa ser um valor de double válido
  • future precisa ser um ponteiro para um valor XrFutureEXT

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

A função xrCheckVpsAvailabilityCompleteANDROID é definida como:

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrVPSAvailabilityCheckCompletionANDROID é definida como:

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

Descrições dos 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 verificação. Se futureResult for XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , uma estrutura na cadeia next pode fornecer mais informações sobre a falha.
  • availability é o XrVPSAvailabilityANDROID resultante. O aplicativo não pode ler esse campo, a menos que futureResult seja 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_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Uso válido (implícito)

Exemplo

Configurar o rastreador geoespacial

PFN_xrCheckVpsAvailabilityAsyncANDROID xrCheckVpsAvailabilityAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCheckVpsAvailabilityCompleteANDROID xrCheckVpsAvailabilityCompleteANDROID;
PFN_xrCreateGeospatialTrackerANDROID xrCreateGeospatialTrackerANDROID;
XrInstance instance = XR_NULL_HANDLE;
XrSystemId systemId = XR_NULL_SYSTEM_ID;
XrSession session = XR_NULL_HANDLE;
double lat = 37.422, lng = -122.084;

// Check for support.
XrSystemGeospatialPropertiesANDROID geospatialSystemProperties{
    XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{XR_TYPE_SYSTEM_PROPERTIES,
                                    &geospatialSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!geospatialSystemProperties.supportsGeospatial) {
  return;
}

// Check VPS Availability.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCheckVpsAvailabilityAsyncANDROID(session, lat, lng, &future));

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

XrVPSAvailabilityCheckCompletionANDROID vpsCompletion{
    XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID};
CHK_XR(xrCheckVpsAvailabilityCompleteANDROID(session, future, &vpsCompletion));
if (vpsCompletion.futureResult == XR_SUCCESS) {
  if (vpsCompletion.availability == XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID) {
    // Visual Positioning Service is not available. Accuracy of positions and
    // orientations from Geospatial APIs are expected to be lower at this location.
  } else {
    // Visual Positioning Service is available. Higher accuracy of position and
    // orientation is achievable at this location.
  }
}

// Create Geospatial Tracker.
XrGeospatialTrackerCreateInfoANDROID createInfo{
    XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID};
XrGeospatialTrackerANDROID geospatialTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateGeospatialTrackerANDROID(session, &createInfo, &geospatialTracker));

// In application main event loop:
while (true) {
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  if (xrPollEvent(instance, &event) != XR_SUCCESS) {
    continue;
  }
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID:
      const XrEventDataGeospatialTrackerStateChangedANDROID& eventData =
          *reinterpret_cast<XrEventDataGeospatialTrackerStateChangedANDROID*>(&event);
      switch (eventData.state) {
        case XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID:
          // Destroy existing anchors, if any.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID:
          // Start adding content.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID:
          // Handle eventData.initializationResult error result.
          break;
      }
  }
}

Chamar APIs Geospatial Pose

PFN_xrLocateGeospatialPoseFromPoseANDROID xrLocateGeospatialPoseFromPoseANDROID;
PFN_xrLocateGeospatialPoseANDROID xrLocateGeospatialPoseANDROID;

XrGeospatialTrackerANDROID geospatialTracker;

// Get pose from view space.
XrSpace viewSpace;
XrPosef identityPose = {{0,0,0,1},{0,0,0}};
XrGeospatialPoseFromPoseLocateInfoANDROID poseGetInfo{
    XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID};
XrGeospatialPoseResultANDROID poseResult{
    XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID};
poseGetInfo.space = viewSpace;
poseGetInfo.pose = identityPose;
poseGetInfo.time = 0;  // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseFromPoseANDROID(geospatialTracker, &poseGetInfo, &poseResult));
if ((poseResult.poseFlags & XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID) &&
    (poseResult.poseFlags & XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID)) {
  // poseResult.geospatialPose is valid.
}

// Convert Geospatial pose to an XrSpaceLocation.
XrGeospatialPoseLocateInfoANDROID poseLocateInfo{
    XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID};
XrSpaceLocation location{XR_TYPE_SPACE_LOCATION};
poseLocateInfo.space = viewSpace;
poseLocateInfo.geospatialPose = poseResult.geospatialPose;
poseLocateInfo.time = 0; // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseANDROID(geospatialTracker, &poseLocateInfo, &location));
if ((location.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT) &&
    (location.locationFlags & XR_SPACE_LOCATION_POSITION_VALID_BIT)) {
  // location.pose is valid.
}

Novos tipos de objeto

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas máscaras de bits

Novas constantes de tipo enumerado

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • Estendendo XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • Estendendo XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • Estendendo XrStructureType :

    • XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
    • XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID

Problemas

Histórico de versões

  • Revisão 1, 18/12/2025 (Ben King)

    • Descrição inicial da extensão.