XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

Tipo de extensión

Extensión de instancia

Número de extensión registrado

708

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

XR_ANDROID_trackables

Estado de baja

  • Obsoleta por la extensión XR_EXT_spatial_marker_tracking

Fecha de la última modificación

23/7/2025

Estado de la IP

No hay reclamos de IP conocidos.

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 habilita el seguimiento de marcadores físicos y permite que las aplicaciones adjunten contenido de RE a marcadores físicos de manera eficiente.

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

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 peligroso, es decir, las aplicaciones deben solicitarlo 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 estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión. Para obtener más detalles sobre la cadena de estructuras, consulta la estructura que se extiende ( XrSystemProperties).
  • supportsMarkerTracking es un XrBool32 que indica si el sistema actual proporciona la capacidad de seguimiento de marcadores.
  • supportsMarkerSizeEstimation es un XrBool32 que indica si el sistema actual proporciona una estimación del tamaño del marcador.
  • maxMarkerCount es la cantidad máxima de marcadores de los que el entorno de ejecución puede hacer un seguimiento al mismo tiempo.

Una aplicación puede inspeccionar si el sistema es capaz de realizar un seguimiento de marcadores extendiendo XrSystemProperties con la estructura XrSystemMarkerTrackingPropertiesANDROID cuando se llama a xrGetSystemProperties . El entorno de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED para la creación del seguimiento de marcadores 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)

Marcadores de seguimiento

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 elemento rastreable 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 devolver XR_ERROR_FEATURE_UNSUPPORTED si XrTrackableTrackerCreateInfoANDROID :: trackableType es XR_TRACKABLE_TYPE_MARKER_ANDROID y XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking devuelve 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 estructuras.
  • 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 un 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 seguimiento 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 devolver XR_ERROR_VALIDATION_FAILURE .

Si un entorno de ejecución admite la estimación del tamaño de los marcadores, 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 devolver 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 de marcadores admitidos.

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 enumerantes

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID: Realiza un seguimiento de los marcadores dinámicos. Este modo tiene la mayor precisión y funciona con 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 todos los entries.
  • entryCount es un uint32_t que describe el recuento de elementos en el array entries. La aplicación puede establecer entryCount 0 para hacer un seguimiento de todos los marcadores en dictionary .
  • entries es un puntero a un array de XrTrackableMarkerDatabaseEntryANDROID , cada uno de los cuales contiene la configuración de un marcador para hacer un seguimiento.

Uso válido (implícito)

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

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, tal como 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 establecer este valor 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 devolver XR_ERROR_VALIDATION_FAILURE .

Uso válido (implícito)

Obtén marcadores

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

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

Descripciones de los parámetros

El entorno de ejecución debe devolver XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si el tipo de elemento rastreable de XrTrackableANDROID no es XR_TRACKABLE_TYPE_MARKER_ANDROID o si el tipo de elemento rastreable de 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 estructuras. No se definen tales 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, tal como 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, Z apuntando a la parte inferior y Y saliendo del marcador como la normal.
  • extents son las dimensiones XrExtent2Df del marcador. El límite del cuadro delimitador se encuentra en los puntos: centerPose +/- ( extents / 2).

Uso válido (implícito)

Código de ejemplo para obtener marcadores con seguimiento

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

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 nuevas

Nuevas constantes de enum

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • Extiende XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • Extiende XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Problemas

Historial de versiones

  • Revisión 1, 23 de julio de 2025 (Levana Chen)

    • Descripción inicial de la extensión.