Extensão XR_ANDROID_trackables do OpenXR

String de nome

XR_ANDROID_trackables

Tipo de extensão

Extensão de instância

Número de extensão registrado

456

Revisão

1

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

2024-09-30

Status do IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Visão geral

Essa extensão permite que o aplicativo acesse os rastreáveis do ambiente físico e crie âncoras anexadas a um rastreável.

Essa extensão define elementos rastreáveis de avião. Outras extensões podem adicionar outros tipos rastreáveis. Por exemplo, XR_ANDROID_trackables_object adiciona rastreáveis de objeto, e XR_ANDROID_depth_texture adiciona buffers de profundidade que permitem o raycasting para pontos arbitrários no ambiente.

Um rastreável é algo que é rastreado no ambiente físico (consulte XrTrackableTypeANDROID):

  • um plano (por exemplo, parede, piso, teto, mesa)
  • um objeto (por exemplo, teclado, mouse, laptop)

Criar um rastreador rastreável

Um XrTrackableTrackerANDROID é um identificador que representa os recursos necessários para descobrir e atualizar rastreáveis de um determinado XrTrackableTypeANDROID no ambiente.

XR_DEFINE_HANDLE(XrTrackableTrackerANDROID)

A função xrCreateTrackableTrackerANDROID é definida como: 

XrResult xrCreateTrackableTrackerANDROID(
    XrSession                                   session,
    const XrTrackableTrackerCreateInfoANDROID*  createInfo,
    XrTrackableTrackerANDROID*                  trackableTracker);

Descrições dos parâmetros

O aplicativo pode usar a função xrCreateTrackableTrackerANDROID para criar um rastreador rastreável.

  • XR_ERROR_FEATURE_UNSUPPORTED será retornado se o sistema não oferecer suporte a rastreáveis do tipo especificado.
  • XR_ERROR_PERMISSION_INSUFFICIENT será retornado se as permissões necessárias não tiverem sido concedidas ao app que faz a chamada.

O aplicativo pode usar o identificador de rastreador retornado em chamadas de API subsequentes. O gerenciador XrTrackableTrackerANDROID precisa ser liberado usando a função xrDestroyTrackableTrackerANDROID.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_FEATURE_UNSUPPORTED

A estrutura XrTrackableTrackerCreateInfoANDROID é definida como: 

typedef struct XrTrackableTrackerCreateInfoANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackableTypeANDROID    trackableType;
} XrTrackableTrackerCreateInfoANDROID;

Descrições dos participantes

  • 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 núcleo do OpenXR ou nesta extensão.
  • trackableType é o XrTrackableTypeANDROID que o rastreador vai rastrear.

A estrutura XrTrackableTrackerCreateInfoANDROID oferece opções de criação para o XrTrackableTrackerANDROID quando transmitida para xrCreateTrackableTrackerANDROID.

As extensões podem definir estruturas que podem ser anexadas a next para permitir uma configuração adicional dos rastreadores rastreáveis.

Uso válido (implícito)

O tipo enumerado XrTrackableTypeANDROID é definido como: 

typedef enum XrTrackableTypeANDROID {
    XR_TRACKABLE_TYPE_NOT_VALID_ANDROID = 0,
    XR_TRACKABLE_TYPE_PLANE_ANDROID = 1,
    XR_TRACKABLE_TYPE_DEPTH_ANDROID = 1000463000,
    XR_TRACKABLE_TYPE_OBJECT_ANDROID = 1000466000
} XrTrackableTypeANDROID;

A função xrDestroyTrackableTrackerANDROID é definida como: 

XrResult xrDestroyTrackableTrackerANDROID(
    XrTrackableTrackerANDROID                   trackableTracker);

Descrições dos parâmetros

A função xrDestroyTrackableTrackerANDROID destrói o rastreador rastreável.

Se não houver outro XrTrackableTrackerANDROID válido criado com o mesmo XrTrackableTypeANDROID, o sistema pode desativar os serviços de rastreamento necessários para esse tipo de rastreamento para economizar recursos do sistema.

Uso válido (implícito)

Segurança da linha de execução

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

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Receber todos os itens rastreáveis

O átomo XrTrackableANDROID é definido como:

XR_DEFINE_ATOM(XrTrackableANDROID)

XrTrackableANDROID é usado para representar um único rastreável e é válido apenas no ciclo de vida do XrTrackableTrackerANDROID associado.

A função xrGetAllTrackablesANDROID é definida como: 

XrResult xrGetAllTrackablesANDROID(
    XrTrackableTrackerANDROID                   trackableTracker,
    uint32_t                                    trackableCapacityInput,
    uint32_t*                                   trackableCountOutput,
    XrTrackableANDROID*                         trackables);

Descrições dos parâmetros

  • trackableTracker é o XrTrackableTrackerANDROID a ser consultado.

  • trackableCapacityInput é a capacidade da matriz trackables ou 0 para indicar uma solicitação para recuperar a capacidade necessária.

  • trackableCountOutput é um ponteiro para a contagem de trackables gravada ou um ponteiro para a capacidade necessária caso trackables seja insuficiente.

  • trackables é um ponteiro para uma matriz de XrTrackableANDROID. Ele pode ser NULL se trackableCapacityInput for 0.

  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho trackables necessário.

xrGetAllTrackablesANDROID preenche uma matriz de XrTrackableANDROID que representa os elementos rastreáveis encontrados no ambiente. O XrTrackableTypeANDROID do trackables retornado precisa corresponder ao XrTrackableTypeANDROID do trackableTracker.

Receber um avião rastreável

A função xrGetTrackablePlaneANDROID é definida como:

XrResult xrGetTrackablePlaneANDROID(
    XrTrackableTrackerANDROID                   trackableTracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackablePlaneANDROID*                    planeOutput);

Descrições dos parâmetros

A função xrGetTrackablePlaneANDROID retorna detalhes sobre o plano rastreável, como geometria, orientação e estado de rastreamento.

As informações do plano são resolvidas e relativas ao espaço da base no momento da chamada para xrGetTrackablePlaneANDROID usando XrTrackableGetInfoANDROID::time, XrTrackableGetInfoANDROID::baseSpace.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_TIME_INVALID

A estrutura XrTrackableGetInfoANDROID é definida como: 

typedef struct XrTrackableGetInfoANDROID {
    XrStructureType       type;
    void*                 next;
    XrTrackableANDROID    trackable;
    XrSpace               baseSpace;
    XrTime                time;
} XrTrackableGetInfoANDROID;

Descrições dos participantes

  • 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 núcleo do OpenXR ou nesta extensão.
  • trackable é o plano XrTrackableANDROID a ser consultado.
  • baseSpace a pose do avião será relativa a esse XrSpace em time.
  • time é o XrTime em que as coordenadas são avaliadas em relação ao baseSpace.

A estrutura XrTrackableGetInfoANDROID fornece opções de consulta quando transmitida para xrGetTrackablePlaneANDROID. O trackable precisa corresponder ao trackableTracker usado em xrGetTrackablePlaneANDROID.

XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID será retornado se o tipo rastreável da trackable não for XR_TRACKABLE_TYPE_PLANE_ANDROID.

Uso válido (implícito)

A estrutura XrTrackablePlaneANDROID é definida como: 

typedef struct XrTrackablePlaneANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    XrPlaneTypeANDROID        planeType;
    XrPlaneLabelANDROID       planeLabel;
    XrTrackableANDROID        subsumedByPlane;
    XrTime                    lastUpdatedTime;
    uint32_t                  vertexCapacityInput;
    uint32_t*                 vertexCountOutput;
    XrVector2f*               vertices;
} XrTrackablePlaneANDROID;

Descrições dos participantes

  • 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 núcleo do OpenXR ou nesta extensão.
  • trackingState é o XrTrackingStateANDROID do plano.
  • centerPose é um XrPosef que define a posição e a orientação do plano no frame de referência do XrTrackableGetInfoANDROID::baseSpace correspondente. Uma orientação de identidade aqui representa um eixo de coordenadas com +Y paralelo à normal do plano.
  • extents é a dimensão XrExtent2Df do plano.
  • planeType é o XrPlaneTypeANDROID que o ambiente de execução determinou para este plano.
  • planeLabel é o XrPlaneLabelANDROID que o ambiente de execução determinou para este plano.
  • subsumedByPlane é o XrTrackableANDROID do plano que engloba esse plano (XR_NULL_TRACKABLE_ANDROID, se nenhum existir).
  • lastUpdatedTime é o XrTime da última atualização do plano.
  • vertexCapacityInput é a capacidade da matriz vertices ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • vertexCountOutput é um ponteiro para a contagem de vertices gravada ou um ponteiro para a capacidade necessária caso vertices seja insuficiente.
  • vertices é um ponteiro para uma matriz de XrVector2f. Ele pode ser NULL se vertexCapacityInput for 0. Os vértices estão na ordem anti-horária. O polígono pode ser côncavo e não pode se autosseccionar.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho vertices necessário.

Uso válido (implícito)

O tipo enumerado XrTrackingStateANDROID descreve o estado de rastreamento de um XrTrackableANDROID. 

typedef enum XrTrackingStateANDROID {
    XR_TRACKING_STATE_PAUSED_ANDROID = 0,
    XR_TRACKING_STATE_STOPPED_ANDROID = 1,
    XR_TRACKING_STATE_TRACKING_ANDROID = 2
} XrTrackingStateANDROID;

XrTrackingStateANDROID

Descrição

XR_TRACKING_STATE_PAUSED_ANDROID

Indica que o rastreamento rastreável ou de âncora está pausado, mas pode ser retomado no futuro.

XR_TRACKING_STATE_STOPPED_ANDROID

O rastreamento foi interrompido e não será retomado.

XR_TRACKING_STATE_TRACKING_ANDROID

O objeto é rastreado e a pose dele é atual.

O tipo enumerado XrPlaneTypeANDROID é o tipo de um plano XrTrackableANDROID. 

typedef enum XrPlaneTypeANDROID {
    XR_PLANE_TYPE_HORIZONTAL_DOWNWARD_FACING_ANDROID = 0,
    XR_PLANE_TYPE_HORIZONTAL_UPWARD_FACING_ANDROID = 1,
    XR_PLANE_TYPE_VERTICAL_ANDROID = 2,
    XR_PLANE_TYPE_ARBITRARY_ANDROID = 3
} XrPlaneTypeANDROID;

O tipo enumerado XrPlaneLabelANDROID é um rótulo para um plano XrTrackableANDROID. 

typedef enum XrPlaneLabelANDROID {
    XR_PLANE_LABEL_UNKNOWN_ANDROID = 0,
    XR_PLANE_LABEL_WALL_ANDROID = 1,
    XR_PLANE_LABEL_FLOOR_ANDROID = 2,
    XR_PLANE_LABEL_CEILING_ANDROID = 3,
    XR_PLANE_LABEL_TABLE_ANDROID = 4
} XrPlaneLabelANDROID;

Criar espaço de ancoragem

XrResult xrCreateAnchorSpaceANDROID(
    XrSession                                   session,
    const XrAnchorSpaceCreateInfoANDROID*       createInfo,
    XrSpace*                                    anchorOutput);

Descrições dos parâmetros

  • session é a XrSession que cria o espaço de âncora.
  • createInfo é um ponteiro para uma estrutura XrAnchorSpaceCreateInfoANDROID que contém parâmetros a serem usados para criar o espaço de âncora.
  • anchorOutput é um ponteiro para um identificador em que o XrSpace criado é retornado.

Em qualquer momento, a posição e a direção da âncora são rastreadas ou não rastreadas. Isso significa que XR_SPACE_LOCATION_POSITION_TRACKED_BIT e XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT precisam ser definidos ou ambos precisam ser limpos quando o aplicativo chama xrLocateSpace ou xrLocateSpaces para anchorOutput.

O aplicativo precisa liberar o XrSpace retornado usando xrDestroySpace.

  • XR_ERROR_FEATURE_UNSUPPORTED precisa ser retornado se o sistema não oferecer suporte a âncoras.
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID precisa ser retornado se o anexo de âncora específico não tiver suporte.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_OUT_OF_MEMORY

A estrutura XrAnchorSpaceCreateInfoANDROID é definida como: 

typedef struct XrAnchorSpaceCreateInfoANDROID {
    XrStructureType       type;
    void*                 next;
    XrSpace               space;
    XrTime                time;
    XrPosef               pose;
    XrTrackableANDROID    trackable;
} XrAnchorSpaceCreateInfoANDROID;

Descrições dos participantes

  • 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 núcleo do OpenXR ou nesta extensão.
  • space é o XrSpace em que a âncora será criada.
  • time é o XrTime da criação da âncora.
  • pose é o XrPosef da âncora.
  • trackable é o XrTrackableANDROID em que a âncora será anexada. Pode ser XR_NULL_TRACKABLE_ANDROID para criar uma âncora espacial.

Uso válido (implícito)

Exemplo de código para receber todos os itens rastreáveis

O exemplo de código abaixo demonstra como receber todos os rastreáveis de um determinado tipo.

XrSession session; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTrackableTrackerCreateInfoANDROID createInfo{XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID};
createInfo.trackableType = XR_TRACKABLE_TYPE_PLANE_ANDROID;
XrTrackableTrackerANDROID planeTrackableTracker;
XrResult result = xrCreateTrackableTrackerANDROID(
  session,
  &createInfo,
  &planeTrackableTracker);
if (result != XR_SUCCESS) { /* Handle failures. */ }

uint32_t trackableCountOutput = 0;
std::vector<XrTrackableANDROID> allPlaneTrackables;

// Query the number of trackables available.
result = xrGetAllTrackablesANDROID(
  planeTrackableTracker,
  0,
  &trackableCountOutput,
  nullptr
);

if (result == XR_SUCCESS) {
  allPlaneTrackables.resize(trackableCountOutput, XR_NULL_HANDLE);

  // Fetch the actual trackable handles in the appropriately resized array.
  result = xrGetAllTrackablesANDROID(
    planeTrackableTracker,
    trackableCountOutput,
    &trackableCountOutput,
    allPlaneTrackables.data());

  if (result == XR_SUCCESS) {
    for (XrTrackableANDROID trackable : allPlaneTrackables) {
      // You now have all trackables of the specified type.
    }
  }
}

// Release trackable tracker.
result = xrDestroyTrackableTrackerANDROID(planeTrackableTracker);

Exemplo de código para acessar o plano rastreável

O exemplo de código abaixo demonstra como receber um plano rastreável de um XrTrackableANDROID existente, recebido de um resultado de acerto XR_ANDROID_raycast ou xrGetTrackablesANDROID.

XrTrackableTrackerANDROID planeTracker; // previously created

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetTrackablePlaneANDROID xrGetTrackablePlaneANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

XrTrackableGetInfoANDROID planeGetInfo;
planeGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;
planeGetInfo.next = nullptr;
planeGetInfo.trackable = planeTrackable;
planeGetInfo.space = appSpace;
planeGetInfo.time = updateTime;

XrTrackablePlaneANDROID plane = { XR_TYPE_TRACKABLE_PLANE_ANDROID };
result = xrGetTrackablePlaneANDROID(
  planeTracker,
  &planeGetInfo,
  &plane
);

if (result == XR_SUCCESS) {
  // Plane tracking state, center pose, extents, type now available in plane.
}

Exemplo de código para criar espaço de âncora

O exemplo de código abaixo demonstra como criar um espaço de âncora anexado a um rastreável.

XrSession session; // Created at app startup.
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

// Create an anchor at (2, 2, 2) world-coordinates.
XrAnchorSpaceCreateInfoANDROID spatialAnchorCreateInfo;
spatialAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
spatialAnchorCreateInfo.next = nullptr;
spatialAnchorCreateInfo.space = appSpace;
spatialAnchorCreateInfo.time = updateTime;
spatialAnchorCreateInfo.pose = { { 0, 0, 0, 1 }, { 2, 2, 2 } };

XrSpace spatialAnchor = XR_NULL_HANDLE;
XrResult result = xrCreateAnchorSpaceANDROID(
  session,
  &spatialAnchorCreateInfo,
  &spatialAnchor
);

// Create an anchor attached to a trackable.
XrTrackablePlane plane = ...;
XrAnchorSpaceCreateInfoANDROID trackableAnchorCreateInfo;
trackableAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
trackableAnchorCreateInfo.next = nullptr;
trackableAnchorCreateInfo.space = appState;
trackableAnchorCreateInfo.pose = plane.centerPose;
trackableAnchorCreateInfo.trackable = planeTrackable;

XrSpace trackableAnchor = XR_NULL_HANDLE;
XrResult result = xrCreateAnchorSpaceANDROID(
  session,
  &trackableAnchorCreateInfo,
  &trackableAnchor
);
while (true) {
  // app update loop
  // ...

  // Get the current location of the anchor's space w.r.t the world.
  XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
  result = xrLocateSpace(trackableAnchor, appSpace, updateTime, &anchorLocation);

  if (anchor.trackingState == XR_TRACKING_STATE_TRACKING_ANDROID) {
    // Update anchor pose.
    doDrawingForAnchor(anchorLocation.pose);
  } else {
    // ...
  }
}

// Cleanup - destroy the space, detatch the anchor so its no longer tracked by the
// runtime and then release all resources held by it.
xrDestroySpace(spatialAnchor);
xrDestroySpace(trackableAnchor);

Novos tipos de base

Novos tipos de objeto

Novas constantes de tipo enumerado

A enumeração XrStructureType foi ampliada com:

  • XR_TYPE_TRACKABLE_GET_INFO_ANDROID
  • XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID
  • XR_TYPE_TRACKABLE_PLANE_ANDROID
  • XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID

A enumeração XrObjectType é estendida com:

  • XR_OBJECT_TYPE_TRACKABLE_TRACKER_ANDROID

A enumeração XrResult foi ampliada com:

  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID

Novos tipos enumerados

Novas estruturas

Novas funções

Problemas

Histórico de versões

  • Revisão 1, 27-09-2024 (Kenny Vercaemer)
    • Descrição inicial da extensão.