Extension OpenXR XR_ANDROID_trackables

Chaîne de nom

XR_ANDROID_trackables

Type d'extension

Extension d'instance

Numéro d'extension enregistré

456

Révision

1

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2024-09-30

État de l'adresse IP

Aucune revendication d'adresse IP connue.

Contributeurs

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Présentation

Cette extension permet à l'application d'accéder aux balises de l'environnement physique et de créer des ancrages associés à une balise.

Cette extension définit les objets de suivi d'avion. D'autres extensions peuvent ajouter des types de suivi supplémentaires. Par exemple, XR_ANDROID_trackables_object ajoute des objets traçables, et XR_ANDROID_depth_texture ajoute des tampons de profondeur qui permettent de lancer des rayons vers des points arbitraires de l'environnement.

Un élément traçable est un élément qui est suivi dans l'environnement physique (voir XrTrackableTypeANDROID):

  • un plan (par exemple, un mur, un sol, un plafond ou une table)
  • un objet (par exemple, un clavier, une souris ou un ordinateur portable) ;

Créer un traceur traçable

Un XrTrackableTrackerANDROID est un handle qui représente les ressources requises pour découvrir et mettre à jour les éléments de suivi d'un XrTrackableTypeANDROID donné dans l'environnement.

XR_DEFINE_HANDLE(XrTrackableTrackerANDROID)

La fonction xrCreateTrackableTrackerANDROID est définie comme suit: 

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

Descriptions des paramètres

L'application peut utiliser la fonction xrCreateTrackableTrackerANDROID pour créer un traceur traçable.

  • XR_ERROR_FEATURE_UNSUPPORTED est renvoyé si le système n'est pas compatible avec les objets connectés du type spécifié.
  • XR_ERROR_PERMISSION_INSUFFICIENT est renvoyé si les autorisations requises n'ont pas été accordées à l'application appelante.

L'application peut utiliser le handle du traceur renvoyé dans les appels d'API ultérieurs. Le doit être libéré à terme à l'aide de la fonction xrDestroyTrackableTrackerANDROID.

Utilisation valide (implicite)

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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_FEATURE_UNSUPPORTED

La structure XrTrackableTrackerCreateInfoANDROID est définie comme suit: 

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

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.
  • trackableType est le XrTrackableTypeANDROID que le traceur suivra.

La structure XrTrackableTrackerCreateInfoANDROID fournit des options de création pour le XrTrackableTrackerANDROID lorsqu'elle est transmise à xrCreateTrackableTrackerANDROID.

Les extensions peuvent définir des structures pouvant être associées à next pour permettre une configuration supplémentaire des outils de suivi.

Utilisation valide (implicite)

L'énumération XrTrackableTypeANDROID est définie comme suit: 

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 fonction xrDestroyTrackableTrackerANDROID est définie comme suit: 

XrResult xrDestroyTrackableTrackerANDROID(
    XrTrackableTrackerANDROID                   trackableTracker);

Descriptions des paramètres

La fonction xrDestroyTrackableTrackerANDROID détruit le traceur traçable.

Si aucun autre XrTrackableTrackerANDROID valide n'a été créé avec le même XrTrackableTypeANDROID, le système peut désactiver les services de suivi requis pour ce type de traceur afin d'économiser des ressources système.

Utilisation valide (implicite)

Sécurité des threads

  • L'accès à trackableTracker et à tous les gestionnaires enfants doit être synchronisé en externe.

Codes de retour

Réussite

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Obtenir tous les objets connectés

L'atome XrTrackableANDROID est défini comme suit:

XR_DEFINE_ATOM(XrTrackableANDROID)

XrTrackableANDROID permet de représenter un seul élément traçable et n'est valide que pendant le cycle de vie de son XrTrackableTrackerANDROID associé.

La fonction xrGetAllTrackablesANDROID est définie comme suit: 

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

Descriptions des paramètres

  • trackableTracker est l'XrTrackableTrackerANDROID à interroger.

  • trackableCapacityInput correspond à la capacité du tableau trackables, ou à 0 pour indiquer une requête visant à récupérer la capacité requise.

  • trackableCountOutput est un pointeur vers le nombre d'trackables écrits ou un pointeur vers la capacité requise si trackables est insuffisant.

  • trackables est un pointeur vers un tableau de XrTrackableANDROID. Il peut être NULL si trackableCapacityInput est défini sur 0.

  • Pour obtenir une description détaillée de la récupération de la taille trackables requise, consultez la section Paramètres de taille de la mémoire tampon.

xrGetAllTrackablesANDROID remplit un tableau de XrTrackableANDROID représentant les éléments détectables trouvés dans l'environnement. Le XrTrackableTypeANDROID de l'trackables renvoyée doit correspondre au XrTrackableTypeANDROID de l'trackableTracker.

Obtenir un avion à suivre

La fonction xrGetTrackablePlaneANDROID est définie comme suit:

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

Descriptions des paramètres

La fonction xrGetTrackablePlaneANDROID renvoie des informations sur le plan traçable, telles que sa géométrie, son orientation et son état de suivi.

Les informations sur le plan sont résolues et relatives à l'espace de base au moment de l'appel de xrGetTrackablePlaneANDROID à l'aide de XrTrackableGetInfoANDROID::time, XrTrackableGetInfoANDROID::baseSpace.

Utilisation valide (implicite)

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_LIMIT_REACHED
  • XR_ERROR_TIME_INVALID

La structure XrTrackableGetInfoANDROID est définie comme suit: 

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

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.
  • trackable est le plan XrTrackableANDROID à interroger.
  • baseSpace La position de l'avion sera relative à cet espace XR à time.
  • time est l'XrTime à partir duquel évaluer les coordonnées par rapport à baseSpace.

La structure XrTrackableGetInfoANDROID fournit des options de requête lorsqu'elle est transmise à xrGetTrackablePlaneANDROID. trackable doit correspondre à trackableTracker utilisé dans xrGetTrackablePlaneANDROID.

XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID est renvoyé si le type de suivi de trackable n'est pas XR_TRACKABLE_TYPE_PLANE_ANDROID.

Utilisation valide (implicite)

La structure XrTrackablePlaneANDROID est définie comme suit: 

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;

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 est l'XrTrackingStateANDROID de l'avion.
  • centerPose est un XrPosef qui définit la position et l'orientation du plan dans le cadre de référence de l'XrTrackableGetInfoANDROID::baseSpace correspondant. Ici, une orientation d'identité représente un axe de coordonnées avec +Y parallèle à la normale du plan.
  • extents correspond à la dimension XrExtent2Df de l'avion.
  • planeType est le XrPlaneTypeANDROID que l'environnement d'exécution a déterminé pour ce plan.
  • planeLabel est le XrPlaneLabelANDROID que l'environnement d'exécution a déterminé pour cet avion.
  • subsumedByPlane est le XrTrackableANDROID du plan qui subsume ce plan (XR_NULL_TRACKABLE_ANDROID s'il n'existe pas).
  • lastUpdatedTime est l'XrTime de la dernière mise à jour du plan.
  • vertexCapacityInput correspond à la capacité du tableau vertices, ou à 0 pour indiquer une requête visant à récupérer la capacité requise.
  • vertexCountOutput est un pointeur vers le nombre d'vertices écrits ou un pointeur vers la capacité requise si vertices est insuffisant.
  • vertices est un pointeur vers un tableau de XrVector2f. Il peut être NULL si vertexCapacityInput est défini sur 0. Les sommets sont présentés dans l'ordre inverse des aiguilles d'une montre. Le polygone peut être concave et ne doit pas se croiser.
  • Pour obtenir une description détaillée de la récupération de la taille vertices requise, consultez la section Paramètres de taille de la mémoire tampon.

Utilisation valide (implicite)

L'énumération XrTrackingStateANDROID décrit l'état de suivi d'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

Description

XR_TRACKING_STATE_PAUSED_ANDROID

Indique que le suivi des éléments de suivi ou des repères est mis en veille, mais qu'il peut être repris ultérieurement.

XR_TRACKING_STATE_STOPPED_ANDROID

Le suivi de cet élément traçable a été arrêté et ne sera jamais repris.

XR_TRACKING_STATE_TRACKING_ANDROID

L'objet est suivi et sa position est à jour.

L'énumération XrPlaneTypeANDROID correspond au type d'avion 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;

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

Créer un espace d'ancrage

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

Descriptions des paramètres

  • session est l'XrSession qui crée l'espace d'ancrage.
  • createInfo est un pointeur vers une structure XrAnchorSpaceCreateInfoANDROID contenant des paramètres à utiliser pour créer l'espace d'ancrage.
  • anchorOutput est un pointeur vers un gestionnaire dans lequel l'XrSpace créé est renvoyé.

À tout moment, la position et la direction de l'ancre sont suivies ou non. Cela signifie que XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT doivent être définis ou effacés lorsque l'application appelle xrLocateSpace ou xrLocateSpaces pour anchorOutput.

L'application doit libérer l'XrSpace renvoyé à l'aide de xrDestroySpace.

  • XR_ERROR_FEATURE_UNSUPPORTED doit être renvoyé si le système n'est pas compatible avec les ancres.
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID doit être renvoyé si l'attachement d'ancrage spécifique n'est pas accepté.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

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

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

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.
  • space est l'espace XR sur lequel l'ancrage sera créé.
  • time est l'XrTime de la création de l'ancre.
  • pose correspond au XrPosef de l'ancre.
  • trackable est l'XrTrackableANDROID sur lequel l'ancre sera fixée. Il peut s'agir de XR_NULL_TRACKABLE_ANDROID pour créer un ancrage spatial.

Utilisation valide (implicite)

Exemple de code pour obtenir tous les éléments de suivi

L'exemple de code suivant montre comment obtenir tous les éléments de suivi d'un type donné.

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

Exemple de code pour obtenir un plan traçable

L'exemple de code suivant montre comment obtenir un plan traçable à partir d'un XrTrackableANDROID existant, obtenu à partir d'un résultat de détection XR_ANDROID_raycast ou 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.
}

Exemple de code pour créer un espace d'ancrage

L'exemple de code suivant montre comment créer un espace d'ancrage associé à un élément de suivi.

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

Nouveaux types de base

Nouveaux types d'objets

Nouvelles constantes d'énumération

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

  • 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

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

  • XR_OBJECT_TYPE_TRACKABLE_TRACKER_ANDROID

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

  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID

Nouvelles énumérations

Nouvelles structures

Nouvelles fonctions

Problèmes

Historique des versions

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