Extensión XR_ANDROID_trackables_qr_code de OpenXR

Cadena de nombre

XR_ANDROID_trackables_qr_code

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

460

Revisión

1

Dependencias de extensiones y versiones

XR_ANDROID_trackables

Fecha de la última modificación

5/2/2025

Estado de la IP

No hay reclamos conocidos por IP.

Colaboradores

Christopher Doer, de Google

Levana Chen, de Google

Jared Finder, Google

Spencer Quin, de Google

Nihav Jain, de Google

Diego Tipaldi, Google

Ken Mackay, de Google

Daniel Guttenberg, Qualcomm

Descripción general

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

Inspecciona la capacidad del sistema

XrSystemQrCodeTrackingPropertiesANDROID

La estructura XrSystemQrCodeTrackingPropertiesANDROID se define de la siguiente manera:

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint32_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 que se pueden hacer un seguimiento al mismo tiempo.

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

Si un entorno de ejecución admite el seguimiento de códigos QR, debe admitir códigos QR rastreados en cualquier momento.maxQrCodeCount

Si un tiempo de ejecución admite la estimación del tamaño del código QR, la aplicación puede establecer XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 para indicar el uso de la estimación del tamaño. De lo contrario, la aplicación debe establecer XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize en un valor positivo o se devolverá XR_ERROR_VALIDATION_FAILURE.

Uso válido (implícito)

  • La extensión XR_ANDROID_trackables_qr_code debe habilitarse antes de usar XrSystemQrCodeTrackingPropertiesANDROID.
  • type debe ser XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructuras.

Seguimiento de códigos QR

Esta extensión agrega XR_TRACKABLE_TYPE_QR_CODE_ANDROID a XrTrackableTypeANDROID.

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

El tiempo 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.

XrTrackableQrCodeConfigurationANDROID

La estructura XrTrackableQrCodeConfigurationANDROID se define de la siguiente manera:

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType               type;
    const 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 de seguimiento deseado.
  • qrCodeEdgeSize indica el tamaño del borde del código QR en metros. Si es cero, el tamaño del código QR se estimará 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 tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE.

Si el tiempo de ejecución admite la estimación del tamaño del código QR, la aplicación puede establecer XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize en 0 para indicar el uso de la estimación del tamaño. De lo contrario, la aplicación debe establecer XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize en un valor positivo o se devolverá XR_ERROR_VALIDATION_FAILURE.

El tiempo de ejecución debe filtrar el resultado de xrGetAllTrackablesANDROID para que coincida con trackingMode y qrCodeEdgeSize.

Uso válido (implícito)

  • La extensión XR_ANDROID_trackables_qr_code debe habilitarse antes de usar XrTrackableQrCodeConfigurationANDROID.
  • type debe ser XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructuras.
  • trackingMode debe ser un valor de XrQrCodeTrackingModeANDROID válido

XrQrCodeTrackingModeANDROID

El enum XrQrCodeTrackingModeANDROID describe los modos de seguimiento admitidos de los códigos QR.

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

| Enum | Description XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | El código QR es dinámico y puede moverse. |

Cómo obtener códigos QR

xrGetTrackableQrCodeANDROID

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

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

Descripciones de parámetros

  • tracker es el XrTrackableTrackerANDROID que se consultará.
  • getInfo es el XrTrackableGetInfoANDROID con la información que se usa para obtener el código QR rastreable.
  • qrCodeOutput es un puntero a la estructura XrTrackableQrCodeANDROID en la que se devuelve el código QR rastreable.

El tiempo de ejecución debe devolver XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si el tipo de objeto de seguimiento de XrTrackableANDROID no es XR_TRACKABLE_TYPE_QR_CODE_ANDROID o si el tipo de objeto de seguimiento de XrTrackableTrackerANDROID no es XR_TRACKABLE_TYPE_QR_CODE_ANDROID.

Uso válido (implícito)

  • La extensión XR_ANDROID_trackables_qr_code debe habilitarse antes de llamar a xrGetTrackableQrCodeANDROID.
  • tracker debe ser un identificador de XrTrackableTrackerANDROID válido
  • getInfo debe ser un puntero a una estructura XrTrackableGetInfoANDROID válida
  • qrCodeOutput debe ser un puntero a una estructura XrTrackableQrCodeANDROID

XrTrackableQrCodeANDROID

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 el XrTime de la última actualización del código QR.
  • 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 hacia la derecha del código QR y Z apuntando hacia su parte inferior.
  • 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 del buffer o 0 para recuperar la capacidad requerida.
  • bufferCountOutput Si bufferCapacityInput es 0, el tiempo de ejecución escribirá el tamaño de búfer requerido en bufferCountOutput. De lo contrario, contiene la cantidad total de elementos escritos en buffer.
  • buffer es un puntero a un array de char para escribir los datos del código QR decodificado. La aplicación puede pasar un nullptr para determinar el tamaño del búfer requerido o si no solicita los datos de decodificación del código QR. 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 buffer requerido.

Uso válido (implícito)

  • La extensión XR_ANDROID_trackables_qr_code debe habilitarse antes de usar XrTrackableQrCodeANDROID.
  • type debe ser XR_TYPE_TRACKABLE_QR_CODE_ANDROID
  • next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructuras.
  • trackingState debe ser un valor de XrTrackingStateANDROID válido
  • Si bufferCapacityInput no es 0, buffer debe ser un puntero a un array de valores char de bufferCapacityInput.

Código de ejemplo para obtener códigos QR rastreables

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);
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    qrCodes[i].type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID;
    qrCodes[i].next = nullptr;
    qrCodes[i].bufferCountOutput = 0;
    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));

Nuevas constantes de enumeración

Se extendió la enumeración XrStructureType con lo siguiente:

  • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

Se extendió la enumeración XrTrackableTypeANDROID con lo siguiente:

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Nuevas enumeraciones

  • XrQrCodeTrackingModeANDROID

Nuevas estructuras

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

Nuevas funciones

  • xrGetTrackableQrCodeANDROID

Problemas

Historial de versiones

  • Revisión 1, 2025-02-05 (Levana Chen)
    • Es la descripción inicial de la extensión.

OpenXR™ y el logotipo de OpenXR son marcas comerciales propiedad de The Khronos Group Inc. y están registradas como marcas comerciales en China, la Unión Europea, Japón y el Reino Unido.