Extension OpenXR XR_ANDROID_trackables_object

Chaîne de nom

XR_ANDROID_trackables_object

Type d'extension

Extension d'instance

Numéro d'extension enregistré

467

Révision

1

Dépendances d'extension et de version

XR_ANDROID_trackables

Date de dernière modification

2024-11-01

État de l'adresse IP

Aucune revendication d'adresse IP connue.

Contributeurs

Diego Tipaldi, Google

David Joseph Tan, Google

Christopher Doer, Google

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Présentation

Cette extension permet de suivre des objets physiques. Par exemple, claviers, souris et autres objets de l'environnement.

Suivre des objets

Cette extension ajoute XR_TRACKABLE_TYPE_OBJECT_ANDROID à XrTrackableTypeANDROID.

L'application peut créer un XrTrackableTrackerANDROID en appelant xrCreateTrackableTrackerANDROID et en spécifiant XR_TRACKABLE_TYPE_OBJECT_ANDROID comme type de suivi dans XrTrackableTrackerCreateInfoANDROID::trackableType pour suivre les objets.

La structure XrTrackableObjectConfigurationANDROID est définie comme suit :

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
• labelCount correspond au nombre de activeLabels.
• activeLabels est un pointeur vers le tableau de XRObjectLabelANDROID indiquant les objets actifs dans le suivi.

L'application peut définir une configuration supplémentaire en ajoutant un XrTrackableObjectConfigurationANDROID à la chaîne suivante de XrTrackableTrackerCreateInfoANDROID. La sortie de xrGetAllTrackablesANDROID sera filtrée pour correspondre à activeLabels.

Si l'application ne définit pas XrTrackableObjectConfigurationANDROID, tous les objets identifiés par le système seront suivis.

Utilisation valide (implicite)

• L'extension XR_ANDROID_trackables_object doit être activée avant d'utiliser XrTrackableObjectANDROID.
• type doit être XR_TYPE_TRACKABLE_OBJECT_ANDROID.
• next doit être NULL ou un pointeur valide vers la structure suivante d'une chaîne de structures.
• activeLabels doit être un pointeur vers un tableau de valeurs XrObjectLabelANDROID labelCount valides.
• Le paramètre labelCount doit être supérieur à 0.

L'énumération XrObjectLabelANDROID est un libellé pour un objet 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;

Obtenir un objet traçable

La fonction xrGetTrackableObjectANDROID est définie comme suit :

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

Descriptions des paramètres

• tracker est l'XrTrackableTrackerANDROID à interroger.
• getInfo est le XrTrackableGetInfoANDROID avec les informations utilisées pour obtenir l'objet traçable.
• objectOutput est un pointeur vers la structure XrTrackableObjectANDROID dans laquelle l'objet traçable est renvoyé.

XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID est renvoyé si le type de suivi de XrTrackableANDROID n'est pas XR_TRACKABLE_TYPE_OBJECT_ANDROID ou si le type de suivi de XrTrackableTrackerANDROID n'est pas XR_TRACKABLE_TYPE_OBJECT_ANDROID.

Utilisation valide (implicite)

• L'extension doit être activée avant d'appeler xrGetTrackableObjectANDROID.XR_ANDROID_trackables_object
• tracker doit être un identifiant XrTrackableTrackerANDROID valide.
• getInfo doit être un pointeur vers une structure XrTrackableGetInfoANDROID valide.
• objectOutput doit être un pointeur vers une structure XrTrackableObjectANDROID.

Codes de retour

Réussite

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Échec

• 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 structure XrTrackableObjectANDROID est définie comme suit :

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
• trackingState correspond au XrTrackingStateANDROID de l'objet.
• centerPose correspond au XrPosef de l'objet situé dans XrTrackableGetInfoANDROID::baseSpace.
• extents correspond à la dimension XrExtent3DfEXT de l'objet.
• objectLabel correspond à l'XrObjectLabelANDROID que l'environnement d'exécution a déterminé pour cet objet.
• lastUpdatedTime correspond à l'XrTime de la dernière mise à jour de l'objet.

Utilisation valide (implicite)

• L'extension XR_ANDROID_trackables_object doit être activée avant d'utiliser XrTrackableObjectANDROID.
• type doit être XR_TYPE_TRACKABLE_OBJECT_ANDROID.
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
• trackingState doit être une valeur XrTrackingStateANDROID valide
• objectLabel doit être une valeur XrObjectLabelANDROID valide.

Exemple de code permettant d'obtenir des objets traçables

L'exemple de code suivant montre comment obtenir des objets traçables.

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);

Nouvelles constantes d'énumération

L'énumération XrStructureType est étendue avec :

• XR_TYPE_TRACKABLE_OBJECT_ANDROID
• XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

L'énumération XrTrackableTypeANDROID est étendue avec :

• XR_TRACKABLE_TYPE_OBJECT_ANDROID

Nouvelles énumérations

• XrObjectLabelANDROID

Nouvelles structures

• XrTrackableObjectANDROID
• XrTrackableObjectConfigurationANDROID

Nouvelles fonctions

• xrGetTrackableObjectANDROID

Problèmes

Historique des versions

• Révision 1, 03/10/2024 (Kenny Vercaemer)
  • Description initiale de l'extension.

OpenXR™ et le logo OpenXR sont des marques appartenant à The Khronos Group Inc. et sont enregistrés en tant que marques en Chine, dans l'Union européenne, au Japon et au Royaume-Uni.