XR_ANDROID_trackables_marker

String de nome

XR_ANDROID_trackables_marker

Tipo de extensão

Extensão de instância

Número de extensão registrada

708

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_ANDROID_trackables

Estado de suspensão de uso

  • Suspenso pela extensão XR_EXT_spatial_marker_tracking

Data da última modificação

23/07/2025

Status de IP

Nenhuma reivindicação de IP 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 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 April Tags. Ela permite que os ambientes de execução ofereçam suporte opcional à estimativa de tamanho do marcador.

Permissões

Os aplicativos 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 solicitar a permissão 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 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 nessa extensão. Para mais detalhes sobre a cadeia de estruturas, consulte a estrutura que está sendo estendida ( XrSystemProperties ).
  • supportsMarkerTracking é um XrBool32 que indica se o sistema atual oferece capacidade de rastreamento de marcadores.
  • supportsMarkerSizeEstimation é um XrBool32 que indica se o sistema atual oferece 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 o 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 oferecer suporte ao rastreamento de marcadores, maxMarkerCount precisa ser pelo menos 1.

Uso válido (implícito)

Rastrear marcadores

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 de 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 desejado para rastreamento.
  • 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 rastrear.

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 for 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 oferecer suporte à 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 ao trackingMode e XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

Uso válido (implícito)

A enumeração XrTrackableMarkerTrackingModeANDROID descreve os modos de rastreamento de marcadores com suporte.

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 enumeradores

  • 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 conhecidos como 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 de membros

  • dictionary é o XrTrackableMarkerDictionaryANDROID a que 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 um contendo a configuração de um marcador a ser rastreado.

Uso válido (implícito)

A enumeração XrTrackableMarkerDictionaryANDROID descreve os dicionários de marcadores com suporte.

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 de 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 oferecer suporte à 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 oferecer suporte à estimativa de tamanho do marcador, o ambiente de execução precisa 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 de 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 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 nessa 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 e Z apontando para a parte inferior, 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

Novas enumerações

Novas constantes de enumeração

  • 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.