XR_ANDROID_trackables_marker

Cadena de nombre

XR_ANDROID_trackables_marker

Tipo de extensión

Extensión de instancia

Número de extensión registrada

708

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensión y versión

XR_ANDROID_trackables

Estado de obsolescencia

  • Obsoleto por la extensión XR_EXT_spatial_marker_tracking

Fecha de última modificación

23/7/2025

Estado de IP

No se conocen reclamos de IP.

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

Descripción general

Esta extensión permite el seguimiento de marcadores físicos y permite que las aplicaciones adjunten contenido de XR a marcadores físicos de manera eficiente.

La extensión admite tipos de marcadores conocidos, específicamente ArUco y April Tags. Permite que los entornos de ejecución admitan de forma opcional la estimación del tamaño del marcador.

Permisos

Las aplicaciones para Android deben tener el permiso android.permission.SCENE_UNDERSTANDING_COARSE en su manifiesto, ya que esta extensión depende de XR_ANDROID_trackables y expone la geometría del entorno. El permiso android.permission.SCENE_UNDERSTANDING_COARSE se considera un permiso peligroso, es decir, las aplicaciones deben solicitar el permiso de forma explícita.

(nivel de protección: peligroso)

Inspecciona la capacidad del sistema

La estructura XrSystemMarkerTrackingPropertiesANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructura. No se definen esas estructuras en OpenXR principal ni en esta extensión. Para obtener más detalles sobre la cadena de estructura, consulta la estructura que se extiende ( XrSystemProperties).
  • supportsMarkerTracking es un XrBool32 que indica si el sistema actual proporciona capacidad de seguimiento de marcadores.
  • supportsMarkerSizeEstimation es un XrBool32 que indica si el sistema actual proporciona estimación del tamaño del marcador.
  • maxMarkerCount es la cantidad máxima de marcadores que el entorno de ejecución puede rastrear al mismo tiempo.

Una aplicación puede inspeccionar si el sistema es capaz de realizar el seguimiento de marcadores extendiendo XrSystemProperties con la estructura XrSystemMarkerTrackingPropertiesANDROID cuando se llama a xrGetSystemProperties . El entorno de ejecución debe mostrar XR_ERROR_FEATURE_UNSUPPORTED para la creación del rastreador de marcadores si y solo si supportsMarkerTracking es XR_FALSE .

Si un entorno de ejecución admite el seguimiento de marcadores, maxMarkerCount debe ser al menos 1.

Uso válido (implícito)

Seguimiento de marcadores

Esta extensión agrega XR_TRACKABLE_TYPE_MARKER_ANDROID a XrTrackableTypeANDROID .

La aplicación crea un XrTrackableTrackerANDROID llamando a xrCreateTrackableTrackerANDROID y especificando XR_TRACKABLE_TYPE_MARKER_ANDROID como el tipo de seguimiento en XrTrackableTrackerCreateInfoANDROID :: trackableType, además de establecer una configuración válida agregando un XrTrackableMarkerConfigurationANDROID a la siguiente cadena de XrTrackableTrackerCreateInfoANDROID .

El entorno de ejecución debe mostrar XR_ERROR_FEATURE_UNSUPPORTED si XrTrackableTrackerCreateInfoANDROID :: trackableType es XR_TRACKABLE_TYPE_MARKER_ANDROID y XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking muestra XR_FALSE a través de xrGetSystemProperties .

La estructura XrTrackableMarkerConfigurationANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructura.
  • trackingMode es un XrTrackableMarkerTrackingModeANDROID que indica el modo deseado para el seguimiento.
  • databaseCount es un uint32_t que describe el recuento de elementos en el array databases.
  • databases es un puntero a un array de XrTrackableMarkerDatabaseANDROID , cada uno de los cuales contiene los marcadores deseados de un diccionario determinado para realizar el seguimiento.

La aplicación debe establecer una configuración válida agregando un XrTrackableMarkerConfigurationANDROID a la cadena XrTrackableTrackerCreateInfoANDROID :: next cuando se llama a xrCreateTrackableTrackerANDROID con XrTrackableTrackerCreateInfoANDROID :: trackableType establecido en XR_TRACKABLE_TYPE_MARKER_ANDROID . De lo contrario, si el tipo de rastreador se establece como se indicó anteriormente, pero la estructura de configuración no está presente o no es válida, el entorno de ejecución debe mostrar XR_ERROR_VALIDATION_FAILURE .

Si un entorno de ejecución admite la estimación del tamaño del marcador, la aplicación puede establecer XrTrackableMarkerDatabaseEntryANDROID :: edgeSize en 0 en XrTrackableMarkerDatabaseANDROID :: entries para indicar el uso de la estimación del tamaño. De lo contrario, la aplicación debe establecer XrTrackableMarkerDatabaseEntryANDROID :: edgeSize en un valor positivo o el entorno de ejecución debe mostrar XR_ERROR_VALIDATION_FAILURE .

El entorno de ejecución debe filtrar el resultado de xrGetAllTrackablesANDROID para que coincida con trackingMode y XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

Uso válido (implícito)

La enumeración XrTrackableMarkerTrackingModeANDROID describe los modos de seguimiento admitidos de los marcadores.

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;

Descripciones de enumeradores

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID: Seguimiento de marcadores dinámicos. Este modo tiene la mayor precisión y funciona en marcadores estáticos y en movimiento, pero también tiene el mayor consumo de energía.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID: Seguimiento de marcadores estáticos. Este modo es útil principalmente para los marcadores que se sabe que son estáticos, lo que genera un menor consumo de energía en comparación con el modo dinámico.

La estructura XrTrackableMarkerDatabaseANDROID define un diccionario y los IDs de marcadores correspondientes para realizar el seguimiento.

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

Descripciones de los miembros

  • dictionary es el XrTrackableMarkerDictionaryANDROID al que pertenecen todas las entries.
  • entryCount es un uint32_t que describe el recuento de elementos en el array entries. La aplicación puede establecer entryCount 0 para realizar el seguimiento de todos los marcadores en el dictionary .
  • entries es un puntero a un array de XrTrackableMarkerDatabaseEntryANDROID , cada uno de los cuales contiene la configuración de un marcador para realizar el seguimiento.

Uso válido (implícito)

La enumeración XrTrackableMarkerDictionaryANDROID describe los diccionarios de marcadores admitidos.

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;

La estructura XrTrackableMarkerDatabaseEntryANDROID configura un solo ID de marcador de un diccionario.

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

Descripciones de los miembros

  • id es el ID del marcador que se indica en el diccionario.
  • edgeSize representa el tamaño del borde del marcador en metros. Si el entorno de ejecución admite la estimación del tamaño del marcador, la aplicación puede establecerlo en cero y el tamaño del marcador se estimará en línea. Si se establece en cero, pero el entorno de ejecución no admite la estimación del tamaño del marcador, el entorno de ejecución debe mostrar XR_ERROR_VALIDATION_FAILURE .

Uso válido (implícito)

Obtener marcadores

La función xrGetTrackableMarkerANDROID se define de la siguiente manera:

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

Descripciones de parámetros

El entorno de ejecución debe mostrar XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si el tipo de seguimiento del XrTrackableANDROID no es XR_TRACKABLE_TYPE_MARKER_ANDROID o si el tipo de seguimiento del XrTrackableTrackerANDROID no es XR_TRACKABLE_TYPE_MARKER_ANDROID .

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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

La estructura XrTrackableMarkerANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructura. No se definen esas estructuras en OpenXR principal ni en esta extensión.
  • trackingState es el XrTrackingStateANDROID del marcador.
  • lastUpdatedTime es el XrTime de la última actualización del marcador.
  • dictionary es el XrTrackableMarkerDictionaryANDROID del marcador.
  • markerId es el ID del marcador que se indica en el diccionario.
  • centerPose es el XrPosef del marcador ubicado en XrTrackableGetInfoANDROID :: baseSpace . El marcador se encuentra en el plano XZ con X apuntando a la derecha del marcador y Z apuntando a su parte inferior, y Y saliendo del marcador como la normal.
  • extents son las dimensiones XrExtent2Df del marcador. El límite del cuadro delimitador está en los puntos: centerPose +/- ( extents / 2).

Uso válido (implícito)

Código de ejemplo para obtener marcadores de seguimiento

En el siguiente código de ejemplo, se muestra cómo obtener marcadores de seguimiento.

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));

Comandos nuevos

Estructuras nuevas

Enums nuevos

Constantes de enum nuevas

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • Extensión de XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • Extensión de XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Problemas

Historial de versiones

  • Revisión 1, 23/7/2025 (Levana Chen)

    • Descripción inicial de la extensión