Extensión OpenXR XR_ANDROID_trackables_object

Cadena de nombre

XR_ANDROID_trackables_object

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

467

Revisión

1

Dependencias de extensiones y versiones

XR_ANDROID_trackables

Fecha de la última modificación

2024-11-01

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

Diego Tipaldi, Google

David Joseph Tan, Google

Christopher Doer, Google

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Descripción general

Esta extensión habilita el seguimiento de objetos físicos. Por ejemplo, teclados, ratones y otros objetos del entorno.

Hacer un seguimiento de los objetos

Esta extensión agrega XR_TRACKABLE_TYPE_OBJECT_ANDROID a XrTrackableTypeANDROID.

La aplicación puede crear un XrTrackableTrackerANDROID llamando a xrCreateTrackableTrackerANDROID y especificando XR_TRACKABLE_TYPE_OBJECT_ANDROID como el tipo rastreable en XrTrackableTrackerCreateInfoANDROID::trackableType para hacer un seguimiento de los objetos.

La estructura XrTrackableObjectConfigurationANDROID se define de la siguiente manera: 

typedef struct XrTrackableObjectConfigurationANDROID {
    XrStructureType                type;
    void*                          next;
    uint32_t                       labelCount;
    const XrObjectLabelANDROID*    activeLabels;
} XrTrackableObjectConfigurationANDROID;

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.
  • labelCount es el recuento de activeLabels.
  • activeLabels es un puntero al array de XRObjectLabelANDROID que indica los objetos activos en el seguimiento.

La aplicación puede establecer una configuración adicional agregando un XrTrackableObjectConfigurationANDROID a la siguiente cadena de XrTrackableTrackerCreateInfoANDROID. El resultado de xrGetAllTrackablesANDROID se filtrará para que coincida con activeLabels.

Si la aplicación no establece XrTrackableObjectConfigurationANDROID, se realizará un seguimiento de todos los objetos que identificó el sistema.

Uso válido (implícito)

La enumeración XrObjectLabelANDROID es una etiqueta para un objeto XrTrackableANDROID. 

typedef enum XrObjectLabelANDROID {
    XR_OBJECT_LABEL_UNKNOWN_ANDROID = 0,
    XR_OBJECT_LABEL_KEYBOARD_ANDROID = 1,
    XR_OBJECT_LABEL_MOUSE_ANDROID = 2,
    XR_OBJECT_LABEL_LAPTOP_ANDROID = 3,
    XR_OBJECT_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrObjectLabelANDROID;

Cómo obtener un objeto rastreable

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

XrResult xrGetTrackableObjectANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableObjectANDROID*                   objectOutput);

Descripciones de los parámetros

Se mostrará XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si el tipo rastreable de XrTrackableANDROID no es XR_TRACKABLE_TYPE_OBJECT_ANDROID o si el tipo rastreable de XrTrackableTrackerANDROID no es XR_TRACKABLE_TYPE_OBJECT_ANDROID.

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_SESSION_NOT_RUNNING
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID

La estructura XrTrackableObjectANDROID se define de la siguiente manera: 

typedef struct XrTrackableObjectANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrPosef                   centerPose;
    XrExtent3DfEXT            extents;
    XrObjectLabelANDROID      objectLabel;
    XrTime                    lastUpdatedTime;
} XrTrackableObjectANDROID;

Descripciones de los miembros

Uso válido (implícito)

Código de ejemplo para obtener objetos rastreables

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

XrSession session; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized
PFN_xrGetTrackableObjectANDROID xrGetTrackableObjectANDROID; // 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.

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

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

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

if (result == XR_SUCCESS) {
  allObjectTrackables.resize(trackableCountOutput, XR_NULL_TRACKABLE_ANDROID);

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

  if (result == XR_SUCCESS) {
    for (XrTrackableANDROID trackable : allObjectTrackables) {

      // Object trackable query information
      XrTrackableGetInfoANDROID objectGetInfo;
      objectGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;
      objectGetInfo.next = nullptr;
      objectGetInfo.trackable = trackable;
      objectGetInfo.baseSpace = appSpace;
      objectGetInfo.time = updateTime;

      // Get the object trackable. Note that the tracker only returns object types.
      XrTrackableObjectANDROID object = { XR_TYPE_TRACKABLE_OBJECT_ANDROID };
      result = xrGetTrackableObjectANDROID(
        objectTrackableTracker,
        &objectGetInfo,
        &object
      );

      if (result == XR_SUCCESS) {
        /** Do Stuff with the object */
      }
    }
  }
}

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

Nuevas constantes de enum

La enumeración XrStructureType se extiende con lo siguiente:

  • XR_TYPE_TRACKABLE_OBJECT_ANDROID
  • XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

La enumeración XrTrackableTypeANDROID se extiende con lo siguiente:

  • XR_TRACKABLE_TYPE_OBJECT_ANDROID

Enumeraciones nuevas

Nuevas estructuras

Funciones nuevas

Problemas

Historial de versiones

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

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