XR_ANDROID_trackables_marker

String de nome

XR_ANDROID_trackables_marker

Tipo de extensão

Extensão de instância

Número de ramal registrado

708

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_ANDROID_trackables

Estado de descontinuação

  • Descontinuado pela extensão XR_EXT_spatial_marker_tracking

Data da última modificação

23/07/2025

Status do IP

Nenhuma reivindicação de PI conhecida.

Colaboradores

Christopher Doer, Google
Diego Tipaldi, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Ken Mackay, Google
Daniel Guttenberg, Qualcomm

Visão geral

Essa extensão permite o rastreamento de marcadores físicos e permite que os aplicativos anexem conteúdo de XR a marcadores físicos de maneira eficiente.

A extensão é compatível com tipos de marcadores conhecidos, especificamente ArUco e AprilTags. Ele permite que os ambientes de execução ofereçam suporte opcional à estimativa de tamanho do marcador.

Permissões

Os apps Android precisam ter a permissão android.permission.SCENE_UNDERSTANDING_COARSE listada no manifesto, já que essa extensão depende de XR_ANDROID_trackables e expõe a geometria do ambiente. A permissão android.permission.SCENE_UNDERSTANDING_COARSE é considerada perigosa, ou seja, os aplicativos precisam solicitá-la explicitamente.

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

Inspecionar a capacidade do sistema

A estrutura XrSystemMarkerTrackingPropertiesANDROID é definida como:

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

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. Para mais detalhes sobre a cadeia de estrutura, consulte a estrutura que está sendo estendida ( XrSystemProperties).
  • supportsMarkerTracking é um XrBool32 que indica se o sistema atual oferece o recurso de rastreamento de marcadores.
  • supportsMarkerSizeEstimation é um XrBool32 que indica se o sistema atual fornece estimativa de tamanho do marcador.
  • maxMarkerCount é o número máximo de marcadores que o ambiente de execução pode rastrear ao mesmo tempo.

Um aplicativo pode inspecionar se o sistema é capaz de rastrear marcadores estendendo as XrSystemProperties com a estrutura XrSystemMarkerTrackingPropertiesANDROID ao chamar xrGetSystemProperties . O ambiente de execução precisa retornar XR_ERROR_FEATURE_UNSUPPORTED para a criação do rastreador de marcadores se e somente se supportsMarkerTracking for XR_FALSE .

Se um ambiente de execução for compatível com o rastreamento de marcadores, maxMarkerCount precisa ser pelo menos 1.

Uso válido (implícito)

Marcadores de rastreamento

Essa extensão adiciona XR_TRACKABLE_TYPE_MARKER_ANDROID a XrTrackableTypeANDROID .

O aplicativo cria um XrTrackableTrackerANDROID chamando xrCreateTrackableTrackerANDROID e especificando XR_TRACKABLE_TYPE_MARKER_ANDROID como o tipo rastreável em XrTrackableTrackerCreateInfoANDROID :: trackableType, além de definir uma configuração válida adicionando um XrTrackableMarkerConfigurationANDROID à próxima cadeia de XrTrackableTrackerCreateInfoANDROID .

O ambiente de execução precisa retornar XR_ERROR_FEATURE_UNSUPPORTED se XrTrackableTrackerCreateInfoANDROID :: trackableType for XR_TRACKABLE_TYPE_MARKER_ANDROID e XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking retornar XR_FALSE via xrGetSystemProperties .

A estrutura XrTrackableMarkerConfigurationANDROID é definida como:

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • trackingMode é um XrTrackableMarkerTrackingModeANDROID que indica o modo de rastreamento desejado.
  • databaseCount é um uint32_t que descreve a contagem de elementos na matriz databases.
  • databases é um ponteiro para uma matriz de XrTrackableMarkerDatabaseANDROID , cada um contendo os marcadores desejados de um determinado dicionário para rastreamento.

O aplicativo precisa definir uma configuração válida adicionando um XrTrackableMarkerConfigurationANDROID à cadeia XrTrackableTrackerCreateInfoANDROID :: next ao chamar xrCreateTrackableTrackerANDROID com XrTrackableTrackerCreateInfoANDROID :: trackableType definido como XR_TRACKABLE_TYPE_MARKER_ANDROID . Caso contrário, se o tipo de rastreador estiver definido como acima, mas a estrutura de configuração não estiver presente ou não for válida, o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE .

Se um ambiente de execução for compatível com a estimativa de tamanho do marcador, o aplicativo poderá definir XrTrackableMarkerDatabaseEntryANDROID :: edgeSize como 0 em XrTrackableMarkerDatabaseANDROID :: entries para indicar o uso da estimativa de tamanho. Caso contrário, o aplicativo precisa definir XrTrackableMarkerDatabaseEntryANDROID :: edgeSize como um valor positivo ou o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE .

O ambiente de execução precisa filtrar a saída de xrGetAllTrackablesANDROID para corresponder a trackingMode e XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

Uso válido (implícito)

O tipo enumerado XrTrackableMarkerTrackingModeANDROID descreve os modos de rastreamento de marcadores compatíveis.

typedef enum XrTrackableMarkerTrackingModeANDROID {
    XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;

Descrições de enumerantes

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID: rastreamento de marcadores dinâmicos. Esse modo tem a maior precisão e funciona em marcadores estáticos e em movimento, mas também tem o maior consumo de energia.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID: rastreamento de marcadores estáticos. Esse modo é útil principalmente para marcadores que são estáticos, o que leva a um menor consumo de energia em comparação com o modo dinâmico.

A estrutura XrTrackableMarkerDatabaseANDROID define um dicionário e os IDs de marcador correspondentes a serem rastreados.

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

Descrições dos membros

  • dictionary é o XrTrackableMarkerDictionaryANDROID ao qual todos os entries pertencem.
  • entryCount é um uint32_t que descreve a contagem de elementos na matriz entries. O aplicativo pode definir entryCount 0 para rastrear todos os marcadores no dictionary .
  • entries é um ponteiro para uma matriz de XrTrackableMarkerDatabaseEntryANDROID , cada uma contendo a configuração de um marcador a ser rastreado.

Uso válido (implícito)

O tipo enumerado XrTrackableMarkerDictionaryANDROID descreve os dicionários de marcadores compatíveis.

typedef enum XrTrackableMarkerDictionaryANDROID {
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
    XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;

A estrutura XrTrackableMarkerDatabaseEntryANDROID configura um único ID de marcador de um dicionário.

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

Descrições dos membros

  • id é o ID do marcador, conforme fornecido no dicionário.
  • edgeSize representa o tamanho da borda do marcador em metros. Se o ambiente de execução for compatível com a estimativa de tamanho do marcador, o aplicativo poderá definir esse valor como zero, e o tamanho do marcador será estimado on-line. Se esse valor for definido como zero, mas o ambiente de execução não for compatível com a estimativa de tamanho do marcador, o ambiente de execução precisará retornar XR_ERROR_VALIDATION_FAILURE .

Uso válido (implícito)

Receber marcadores

A função xrGetTrackableMarkerANDROID é definida como:

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

Descrições dos parâmetros

O ambiente de execução precisa retornar XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID se o tipo rastreável do XrTrackableANDROID não for XR_TRACKABLE_TYPE_MARKER_ANDROID ou se o tipo rastreável do XrTrackableTrackerANDROID não for XR_TRACKABLE_TYPE_MARKER_ANDROID .

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

A estrutura XrTrackableMarkerANDROID é definida como:

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

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.
  • trackingState é o XrTrackingStateANDROID do marcador.
  • lastUpdatedTime é o XrTime da última atualização do marcador.
  • dictionary é o XrTrackableMarkerDictionaryANDROID do marcador.
  • markerId é o ID do marcador, conforme fornecido no dicionário.
  • centerPose é o XrPosef do marcador localizado em XrTrackableGetInfoANDROID :: baseSpace . O marcador fica no plano XZ, com X apontando para a direita do marcador, Z apontando para a parte de baixo e Y saindo do marcador como o normal.
  • extents são as dimensões XrExtent2Df do marcador. O limite da caixa delimitadora está nos pontos: centerPose +/- ( extents / 2).

Uso válido (implícito)

Exemplo de código para receber marcadores rastreáveis

O exemplo de código a seguir demonstra como receber marcadores rastreáveis.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session;   // previously initialized

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

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace;  // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

// Inspect system capability
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
  .type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
    // Marker tracking is not supported.
    return;
}

// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
  .id = 0,
  .edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
  .dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
  .entryCount = 1,
  .entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
  .databaseCount = 1,
  .databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
  .type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
  .next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
                                 trackables.data()));
for (int i = 0; i < markerSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables[i],
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
    // Handle markers.
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de tipo enumerado

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • Estendendo XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • Estendendo XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Problemas

Histórico de versões

  • Revisão 1, 23/07/2025 (Levana Chen)

    • Descrição inicial da extensão.