XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Tipo de extensión

Extensión de instancia

Número de extensión registrado

709

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

5/2/2025

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

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

Descripción general

Esta extensión permite el seguimiento de códigos QR físicos y la decodificación de datos de códigos QR.

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.

(nivel de protección: peligroso)

Inspecciona la capacidad del sistema

La estructura XrSystemQrCodeTrackingPropertiesANDROID se define de la siguiente manera:

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint16_t           maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;

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.
  • supportsQrCodeTracking es un XrBool32 que indica si el sistema actual proporciona la capacidad de seguimiento de códigos QR.
  • supportsQrCodeSizeEstimation es un XrBool32 que indica si el sistema actual proporciona una estimación del tamaño del código QR.
  • maxQrCodeCount es la cantidad máxima total de códigos QR de los que se puede hacer un seguimiento al mismo tiempo.

Una aplicación puede inspeccionar si el sistema es capaz de realizar un seguimiento de códigos QR extendiendo XrSystemProperties con la estructura XrSystemQrCodeTrackingPropertiesANDROID cuando se llama a xrGetSystemProperties . El entorno de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED para la creación del seguimiento de códigos QR si, y solo si, supportsQrCodeTracking es XR_FALSE .

Si un entorno de ejecución admite el seguimiento de códigos QR, maxQrCodeCount debe ser al menos 1. Si un entorno de ejecución no admite el seguimiento de códigos QR, maxQrCodeCount debe ser 0.

Uso válido (implícito)

Códigos QR de seguimiento

Esta extensión agrega XR_TRACKABLE_TYPE_QR_CODE_ANDROID a XrTrackableTypeANDROID .

La aplicación puede crear un XrTrackableTrackerANDROID llamando a xrCreateTrackableTrackerANDROID y especificando XR_TRACKABLE_TYPE_QR_CODE_ANDROID como el tipo de elemento rastreable en XrTrackableTrackerCreateInfoANDROID :: trackableType para hacer un seguimiento de los códigos QR.

El entorno de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED si XrTrackableTrackerCreateInfoANDROID :: trackableType es XR_TRACKABLE_TYPE_QR_CODE_ANDROID y XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking devuelve XR_FALSE a través de xrGetSystemProperties .

La estructura XrTrackableQrCodeConfigurationANDROID se define de la siguiente manera:

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType                type;
    void*                          next;
    XrQrCodeTrackingModeANDROID    trackingMode;
    float                          qrCodeEdgeSize;
} XrTrackableQrCodeConfigurationANDROID;

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.
  • trackingMode es un XrQrCodeTrackingModeANDROID que indica el modo deseado para el seguimiento.
  • qrCodeEdgeSize indica el tamaño del borde del código QR en metros. Si es cero, el entorno de ejecución estima el tamaño del código QR en línea.

La aplicación debe establecer una configuración válida agregando un XrTrackableQrCodeConfigurationANDROID a la siguiente cadena de XrTrackableTrackerCreateInfoANDROID . De lo contrario, el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

Si el entorno de ejecución admite la estimación del tamaño del código QR, la aplicación puede establecer XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize en 0.0 para indicar el uso de la estimación del tamaño.

Si el entorno de ejecución no admite la estimación del tamaño del código QR, la aplicación debe establecer XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize en un valor positivo; de lo contrario, 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 . Si XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize no se establece en 0.0, el entorno de ejecución debe mostrar solo los códigos QR que coincidan con este tamaño. Si XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize se establece en 0.0, el entorno de ejecución debe devolver todos los códigos QR con el tamaño estimado.

Uso válido (implícito)

La enumeración XrQrCodeTrackingModeANDROID describe los modos de seguimiento admitidos de los códigos QR.

typedef enum XrQrCodeTrackingModeANDROID {
    XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM = 1000314000,
    XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;

Descripciones de enumerantes

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID: Seguimiento de códigos QR dinámicos. Este modo tiene la mayor precisión y funciona con códigos QR estáticos y en movimiento, pero también tiene el mayor consumo de energía.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID: Seguimiento de códigos QR estáticos. Este modo es útil principalmente para los códigos QR que se sabe que son estáticos, lo que genera un menor consumo de energía en comparación con el modo dinámico.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM: Este modo se debe usar para los códigos QR estáticos. A diferencia del modo estático, este modo hará un seguimiento del código QR solo una vez y, luego, actualizará las posiciones de las instancias de las que se hace un seguimiento únicamente en función de la posición del dispositivo. Como resultado, el seguimiento continúa incluso si el código QR sale de la vista del marco de referencia. Esto genera un consumo de energía mínimo una vez que se hace un seguimiento del código QR. (Agregado por la extensión XR_QCOM_trackables_qr_code_operations)

Obtén códigos QR

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

XrResult xrGetTrackableQrCodeANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableQrCodeANDROID*                   qrCodeOutput);

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_QR_CODE_ANDROID o si el tipo de elemento rastreable de XrTrackableTrackerANDROID no es XR_TRACKABLE_TYPE_QR_CODE_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_SIZE_INSUFFICIENT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La estructura XrTrackableQrCodeANDROID se define de la siguiente manera:

typedef struct XrTrackableQrCodeANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrTime                    lastUpdatedTime;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    uint32_t                  bufferCapacityInput;
    uint32_t                  bufferCountOutput;
    char*                     buffer;
} XrTrackableQrCodeANDROID;

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 código QR.
  • lastUpdatedTime es la XrTime de la última actualización del código QR. Si lastUpdatedTime cambia desde la última llamada, es posible que todos los demás campos hayan cambiado.
  • centerPose es el XrPosef del código QR ubicado en XrTrackableGetInfoANDROID :: baseSpace . El código QR se encuentra en el plano XZ, con X apuntando a la derecha del código QR, Z apuntando a su parte inferior e Y saliendo del código QR como la normal.
  • extents son las dimensiones XrExtent2Df del código QR. El límite del cuadro delimitador se encuentra en los puntos: centerPose +/- ( extents / 2).
  • bufferCapacityInput es la capacidad de buffer o 0 para recuperar la capacidad requerida.
  • bufferCountOutput Si el bufferCapacityInput es 0 , el entorno de ejecución escribirá el tamaño de búfer requerido en bufferCountOutput . De lo contrario, contiene el total de elementos escritos en buffer . Si aún no se decodificaron los datos del código QR, el entorno de ejecución debe establecer bufferCountOutput en 0.
  • buffer es un puntero a un array de char para escribir los datos decodificados del código QR. Si a la aplicación no le importan los datos del código QR decodificado, puede pasar nullptr y omitir la segunda llamada de dos llamadas. Los datos del código QR se devuelven como una cadena UTF-8 terminada en nulo.
  • Consulta la sección Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño de buffer requerido.

Uso válido (implícito)

Código de ejemplo para obtener códigos QR con seguimiento

En el siguiente código de ejemplo, se muestra cómo obtener códigos QR 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_xrGetTrackableQrCodeANDROID xrGetTrackableQrCodeANDROID;           // 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
XrSystemQrCodeTrackingPropertiesANDROID qrCodeProperty {
  .type = XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &qrCodeProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!qrCodeProperty.supportsQrCodeTracking) {
    // QR code tracking is not supported.
    return;
}

// Create a trackable tracker for QR code tracking.
// If the runtime does not support size estimation, configures QR code edge size of 0.1m.
XrTrackableQrCodeConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID,
  .qrCodeEdgeSize = qrCodeProperty.supportsQrCodeSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_QR_CODE_ANDROID
};
XrTrackableTrackerANDROID qrCodeTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &qrCodeTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get QR codes.
std::vector<XrTrackableANDROID> trackables(qrCodeProperty.maxQrCodeCount);
std::vector<XrTrackableQrCodeANDROID> qrCodes(qrCodeProperty.maxQrCodeCount, {
  .type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID,
  .next = nullptr,
  .bufferCountOutput = 0,
});
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables.at(i),
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
    if (qrCodes[i].bufferCountOutput > 0) {
        // Allocate the buffer if it is not already allocated.
        if (qrCodes[i].bufferCapacityInput == 0) {
            qrCodes[i].buffer = new char[qrCodes[i].bufferCountOutput];
            qrCodes[i].bufferCapacityInput = qrCodes[i].bufferCountOutput;
            CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
        }
    }
}

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

Comandos nuevos

Estructuras nuevas

Enums nuevas

Nuevas constantes de enum

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • Extiende XrStructureType :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • Extiende XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Problemas

Historial de versiones

  • Revisión 1, 5 de febrero de 2025 (Levana Chen)

    • Descripción inicial de la extensión.