Extensión OpenXR XR_ANDROID_trackables

Cadena de nombre

XR_ANDROID_trackables

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

456

Revisión

1

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de última modificación

2024-09-30

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Descripción general

Esta extensión permite que la aplicación acceda a dispositivos rastreables desde el entorno físico y cree anclas conectadas a un dispositivo rastreable.

Esta extensión define los elementos rastreables de aviones. Es posible que otras extensiones agreguen tipos adicionales que se puedan hacer un seguimiento. Por ejemplo, XR_ANDROID_trackables_object agrega objetos rastreables, y XR_ANDROID_depth_texture agrega búferes de profundidad que permiten el raycasting a puntos arbitrarios en el entorno.

Un elemento rastreable es algo a lo que se le hace un seguimiento en el entorno físico (consulta XrTrackableTypeANDROID):

  • un plano (p.ej., pared, piso, techo o mesa)
  • un objeto (p.ej., teclado, mouse o laptop)

Crea un dispositivo de rastreo rastreable

Un XrTrackableTrackerANDROID es un identificador que representa los recursos necesarios para descubrir y actualizar elementos rastreables de un XrTrackableTypeANDROID determinado en el entorno.

XR_DEFINE_HANDLE(XrTrackableTrackerANDROID)

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

XrResult xrCreateTrackableTrackerANDROID(
    XrSession                                   session,
    const XrTrackableTrackerCreateInfoANDROID*  createInfo,
    XrTrackableTrackerANDROID*                  trackableTracker);

Descripciones de los parámetros

La aplicación puede usar la función xrCreateTrackableTrackerANDROID para crear un dispositivo de rastreo rastreable.

  • Se mostrará XR_ERROR_FEATURE_UNSUPPORTED si el sistema no es compatible con los dispositivos rastreables del tipo especificado.
  • Se mostrará XR_ERROR_PERMISSION_INSUFFICIENT si no se otorgaron los permisos necesarios a la app que realiza la llamada.

La aplicación puede usar el identificador del dispositivo de rastreo que se muestra en llamadas posteriores a la API. El controlador XrTrackableTrackerANDROID debe liberarse con la función xrDestroyTrackableTrackerANDROID.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_FEATURE_UNSUPPORTED

La estructura XrTrackableTrackerCreateInfoANDROID se define de la siguiente manera: 

typedef struct XrTrackableTrackerCreateInfoANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackableTypeANDROID    trackableType;
} XrTrackableTrackerCreateInfoANDROID;

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.
  • trackableType es el XrTrackableTypeANDROID del que hará un seguimiento el dispositivo de rastreo.

La estructura XrTrackableTrackerCreateInfoANDROID proporciona opciones de creación para XrTrackableTrackerANDROID cuando se pasa a xrCreateTrackableTrackerANDROID.

Las extensiones pueden definir estructuras que se pueden adjuntar a next para permitir una configuración adicional de los dispositivos de rastreo.

Uso válido (implícito)

La enumeración XrTrackableTypeANDROID se define de la siguiente manera: 

typedef enum XrTrackableTypeANDROID {
    XR_TRACKABLE_TYPE_NOT_VALID_ANDROID = 0,
    XR_TRACKABLE_TYPE_PLANE_ANDROID = 1,
    XR_TRACKABLE_TYPE_DEPTH_ANDROID = 1000463000,
    XR_TRACKABLE_TYPE_OBJECT_ANDROID = 1000466000
} XrTrackableTypeANDROID;

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

XrResult xrDestroyTrackableTrackerANDROID(
    XrTrackableTrackerANDROID                   trackableTracker);

Descripciones de los parámetros

La función xrDestroyTrackableTrackerANDROID destruye el dispositivo de rastreo detectable.

Si no hay otro XrTrackableTrackerANDROID válido que se haya creado con el mismo XrTrackableTypeANDROID, el sistema puede inhabilitar los servicios de seguimiento necesarios para ese tipo de elemento rastreable para ahorrar recursos del sistema.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a trackableTracker y a cualquier controlador secundario debe sincronizarse de forma externa.

Códigos de retorno

Correcto

  • XR_SUCCESS

Error

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Cómo obtener todos los dispositivos rastreables

El átomo XrTrackableANDROID se define de la siguiente manera:

XR_DEFINE_ATOM(XrTrackableANDROID)

XrTrackableANDROID se usa para representar un solo elemento rastreable y solo es válido dentro del ciclo de vida de su XrTrackableTrackerANDROID asociado.

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

XrResult xrGetAllTrackablesANDROID(
    XrTrackableTrackerANDROID                   trackableTracker,
    uint32_t                                    trackableCapacityInput,
    uint32_t*                                   trackableCountOutput,
    XrTrackableANDROID*                         trackables);

Descripciones de los parámetros

  • trackableTracker es el XrTrackableTrackerANDROID que se consulta.

  • trackableCapacityInput es la capacidad del array trackables, o 0 para indicar una solicitud para recuperar la capacidad requerida.

  • trackableCountOutput es un puntero al recuento de trackables escrito o un puntero a la capacidad requerida en caso de que trackables sea insuficiente.

  • trackables es un puntero a un array de XrTrackableANDROID. Puede ser NULL si trackableCapacityInput es 0.

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

xrGetAllTrackablesANDROID completa un array de XrTrackableANDROID que representa los elementos rastreables que se encuentran en el entorno. El XrTrackableTypeANDROID del trackables que se muestra debe coincidir con el XrTrackableTypeANDROID del trackableTracker.

Cómo obtener un avión rastreable

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

XrResult xrGetTrackablePlaneANDROID(
    XrTrackableTrackerANDROID                   trackableTracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackablePlaneANDROID*                    planeOutput);

Descripciones de los parámetros

La función xrGetTrackablePlaneANDROID muestra detalles sobre el plano rastreable, como su geometría, orientación y estado de seguimiento.

La información del plano se resuelve y se relaciona con el espacio base en el momento de la llamada a xrGetTrackablePlaneANDROID con XrTrackableGetInfoANDROID::time, XrTrackableGetInfoANDROID::baseSpace.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_TIME_INVALID

La estructura XrTrackableGetInfoANDROID se define de la siguiente manera: 

typedef struct XrTrackableGetInfoANDROID {
    XrStructureType       type;
    void*                 next;
    XrTrackableANDROID    trackable;
    XrSpace               baseSpace;
    XrTime                time;
} XrTrackableGetInfoANDROID;

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.
  • trackable es el plano XrTrackableANDROID que se consultará.
  • baseSpace La posición del plano será relativa a este XrSpace en time.
  • time es el XrTime en el que se deben evaluar las coordenadas en relación con baseSpace.

La estructura XrTrackableGetInfoANDROID proporciona opciones de consulta cuando se pasa a xrGetTrackablePlaneANDROID. El trackable debe corresponder al trackableTracker que se usa en xrGetTrackablePlaneANDROID.

Se mostrará XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si el tipo rastreable de trackable no es XR_TRACKABLE_TYPE_PLANE_ANDROID.

Uso válido (implícito)

La estructura XrTrackablePlaneANDROID se define de la siguiente manera: 

typedef struct XrTrackablePlaneANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    XrPlaneTypeANDROID        planeType;
    XrPlaneLabelANDROID       planeLabel;
    XrTrackableANDROID        subsumedByPlane;
    XrTime                    lastUpdatedTime;
    uint32_t                  vertexCapacityInput;
    uint32_t*                 vertexCountOutput;
    XrVector2f*               vertices;
} XrTrackablePlaneANDROID;

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 avión.
  • centerPose es un XrPosef que define la posición y orientación del plano dentro del marco de referencia del XrTrackableGetInfoANDROID::baseSpace correspondiente. Una orientación de identidad aquí representa un eje de coordenadas con +Y paralelo a la normal del plano.
  • extents es la dimensión XrExtent2Df del plano.
  • planeType es el XrPlaneTypeANDROID que el entorno de ejecución determinó para este plano.
  • planeLabel es el XrPlaneLabelANDROID que el entorno de ejecución determinó para este plano.
  • subsumedByPlane es el XrTrackableANDROID del plano que lo subsume (XR_NULL_TRACKABLE_ANDROID si no existe ninguno).
  • lastUpdatedTime es el XrTime de la última actualización del plan.
  • vertexCapacityInput es la capacidad del array vertices, o 0 para indicar una solicitud para recuperar la capacidad requerida.
  • vertexCountOutput es un puntero al recuento de vertices escrito o un puntero a la capacidad requerida en caso de que vertices no sea suficiente.
  • vertices es un puntero a un array de XrVector2f. Puede ser NULL si vertexCapacityInput es 0. Los vértices están en orden contrario a las manecillas del reloj. El polígono puede ser cóncavo y no debe cortarse a sí mismo.
  • 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 vertices requerido.

Uso válido (implícito)

La enumeración XrTrackingStateANDROID describe el estado de seguimiento de un XrTrackableANDROID. 

typedef enum XrTrackingStateANDROID {
    XR_TRACKING_STATE_PAUSED_ANDROID = 0,
    XR_TRACKING_STATE_STOPPED_ANDROID = 1,
    XR_TRACKING_STATE_TRACKING_ANDROID = 2
} XrTrackingStateANDROID;

XrTrackingStateANDROID

Descripción

XR_TRACKING_STATE_PAUSED_ANDROID

Indica que el seguimiento de la unidad de rastreo o del ancla está pausado, pero se puede reanudar en el futuro.

XR_TRACKING_STATE_STOPPED_ANDROID

El seguimiento de este dispositivo rastreable se detuvo y nunca se reanudará.

XR_TRACKING_STATE_TRACKING_ANDROID

Se realiza un seguimiento del objeto y su posición es actual.

La enumeración XrPlaneTypeANDROID es el tipo de un plano XrTrackableANDROID. 

typedef enum XrPlaneTypeANDROID {
    XR_PLANE_TYPE_HORIZONTAL_DOWNWARD_FACING_ANDROID = 0,
    XR_PLANE_TYPE_HORIZONTAL_UPWARD_FACING_ANDROID = 1,
    XR_PLANE_TYPE_VERTICAL_ANDROID = 2,
    XR_PLANE_TYPE_ARBITRARY_ANDROID = 3
} XrPlaneTypeANDROID;

La enumeración XrPlaneLabelANDROID es una etiqueta para un plano XrTrackableANDROID. 

typedef enum XrPlaneLabelANDROID {
    XR_PLANE_LABEL_UNKNOWN_ANDROID = 0,
    XR_PLANE_LABEL_WALL_ANDROID = 1,
    XR_PLANE_LABEL_FLOOR_ANDROID = 2,
    XR_PLANE_LABEL_CEILING_ANDROID = 3,
    XR_PLANE_LABEL_TABLE_ANDROID = 4
} XrPlaneLabelANDROID;

Crea un espacio de ancla

XrResult xrCreateAnchorSpaceANDROID(
    XrSession                                   session,
    const XrAnchorSpaceCreateInfoANDROID*       createInfo,
    XrSpace*                                    anchorOutput);

Descripciones de los parámetros

  • session es el XrSession que crea el espacio de anclaje.
  • createInfo es un puntero a una estructura XrAnchorSpaceCreateInfoANDROID que contiene parámetros que se usarán para crear el espacio de anclaje.
  • anchorOutput es un puntero a un identificador en el que se muestra el XrSpace creado.

En cualquier momento, se puede hacer un seguimiento de la posición y la dirección de la ancla, o bien no hacerlo. Esto significa que se deben establecer XR_SPACE_LOCATION_POSITION_TRACKED_BIT y XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT, o bien se deben borrar ambos cuando la aplicación llame a xrLocateSpace o xrLocateSpaces para anchorOutput.

La aplicación debe liberar el XrSpace que se muestra con xrDestroySpace.

  • Se debe mostrar XR_ERROR_FEATURE_UNSUPPORTED si el sistema no admite anclas.
  • Se debe mostrar XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID si no se admite el archivo adjunto de ancla específico.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_OUT_OF_MEMORY

La estructura XrAnchorSpaceCreateInfoANDROID se define de la siguiente manera: 

typedef struct XrAnchorSpaceCreateInfoANDROID {
    XrStructureType       type;
    void*                 next;
    XrSpace               space;
    XrTime                time;
    XrPosef               pose;
    XrTrackableANDROID    trackable;
} XrAnchorSpaceCreateInfoANDROID;

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.
  • space es el XrSpace en el que se creará el ancla.
  • time es el XrTime de la creación de la ancla.
  • pose es el XrPosef del ancla.
  • trackable es el XrTrackableANDROID en el que se adjuntará el ancla. Puede ser XR_NULL_TRACKABLE_ANDROID para crear un ancla espacial.

Uso válido (implícito)

Ejemplo de código para obtener todos los elementos rastreables

En el siguiente código de ejemplo, se muestra cómo obtener todos los elementos rastreables de un tipo determinado.

XrSession session; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTrackableTrackerCreateInfoANDROID createInfo{XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID};
createInfo.trackableType = XR_TRACKABLE_TYPE_PLANE_ANDROID;
XrTrackableTrackerANDROID planeTrackableTracker;
XrResult result = xrCreateTrackableTrackerANDROID(
  session,
  &createInfo,
  &planeTrackableTracker);
if (result != XR_SUCCESS) { /* Handle failures. */ }

uint32_t trackableCountOutput = 0;
std::vector<XrTrackableANDROID> allPlaneTrackables;

// Query the number of trackables available.
result = xrGetAllTrackablesANDROID(
  planeTrackableTracker,
  0,
  &trackableCountOutput,
  nullptr
);

if (result == XR_SUCCESS) {
  allPlaneTrackables.resize(trackableCountOutput, XR_NULL_HANDLE);

  // Fetch the actual trackable handles in the appropriately resized array.
  result = xrGetAllTrackablesANDROID(
    planeTrackableTracker,
    trackableCountOutput,
    &trackableCountOutput,
    allPlaneTrackables.data());

  if (result == XR_SUCCESS) {
    for (XrTrackableANDROID trackable : allPlaneTrackables) {
      // You now have all trackables of the specified type.
    }
  }
}

// Release trackable tracker.
result = xrDestroyTrackableTrackerANDROID(planeTrackableTracker);

Ejemplo de código para obtener un plano rastreable

En el siguiente código de ejemplo, se muestra cómo obtener un plano rastreable a partir de un XrTrackableANDROID existente, obtenido de un resultado de hit XR_ANDROID_raycast o xrGetTrackablesANDROID.

XrTrackableTrackerANDROID planeTracker; // previously created

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetTrackablePlaneANDROID xrGetTrackablePlaneANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

XrTrackableGetInfoANDROID planeGetInfo;
planeGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;
planeGetInfo.next = nullptr;
planeGetInfo.trackable = planeTrackable;
planeGetInfo.space = appSpace;
planeGetInfo.time = updateTime;

XrTrackablePlaneANDROID plane = { XR_TYPE_TRACKABLE_PLANE_ANDROID };
result = xrGetTrackablePlaneANDROID(
  planeTracker,
  &planeGetInfo,
  &plane
);

if (result == XR_SUCCESS) {
  // Plane tracking state, center pose, extents, type now available in plane.
}

Ejemplo de código para crear un espacio de anclaje

En el siguiente ejemplo de código, se muestra cómo crear un espacio de ancla adjunto a un elemento rastreable.

XrSession session; // Created at app startup.
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

// Create an anchor at (2, 2, 2) world-coordinates.
XrAnchorSpaceCreateInfoANDROID spatialAnchorCreateInfo;
spatialAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
spatialAnchorCreateInfo.next = nullptr;
spatialAnchorCreateInfo.space = appSpace;
spatialAnchorCreateInfo.time = updateTime;
spatialAnchorCreateInfo.pose = { { 0, 0, 0, 1 }, { 2, 2, 2 } };

XrSpace spatialAnchor = XR_NULL_HANDLE;
XrResult result = xrCreateAnchorSpaceANDROID(
  session,
  &spatialAnchorCreateInfo,
  &spatialAnchor
);

// Create an anchor attached to a trackable.
XrTrackablePlane plane = ...;
XrAnchorSpaceCreateInfoANDROID trackableAnchorCreateInfo;
trackableAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
trackableAnchorCreateInfo.next = nullptr;
trackableAnchorCreateInfo.space = appState;
trackableAnchorCreateInfo.pose = plane.centerPose;
trackableAnchorCreateInfo.trackable = planeTrackable;

XrSpace trackableAnchor = XR_NULL_HANDLE;
XrResult result = xrCreateAnchorSpaceANDROID(
  session,
  &trackableAnchorCreateInfo,
  &trackableAnchor
);
while (true) {
  // app update loop
  // ...

  // Get the current location of the anchor's space w.r.t the world.
  XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
  result = xrLocateSpace(trackableAnchor, appSpace, updateTime, &anchorLocation);

  if (anchor.trackingState == XR_TRACKING_STATE_TRACKING_ANDROID) {
    // Update anchor pose.
    doDrawingForAnchor(anchorLocation.pose);
  } else {
    // ...
  }
}

// Cleanup - destroy the space, detatch the anchor so its no longer tracked by the
// runtime and then release all resources held by it.
xrDestroySpace(spatialAnchor);
xrDestroySpace(trackableAnchor);

Nuevos tipos de base

Nuevos tipos de objetos

Nuevas constantes de enum

La enumeración XrStructureType se extiende con lo siguiente:

  • XR_TYPE_TRACKABLE_GET_INFO_ANDROID
  • XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID
  • XR_TYPE_TRACKABLE_PLANE_ANDROID
  • XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID

La enumeración XrObjectType se extiende con lo siguiente:

  • XR_OBJECT_TYPE_TRACKABLE_TRACKER_ANDROID

La enumeración XrResult se extiende con lo siguiente:

  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID

Enumeraciones nuevas

Nuevas estructuras

Funciones nuevas

Problemas

Historial de versiones

  • Revisión 1, 27/9/2024 (Kenny Vercaemer)
    • Descripción inicial de la extensión.