Estensione OpenXR XR_ANDROID_trackables

Stringa del nome

XR_ANDROID_trackables

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

456

Revisione

1

Dipendenze di estensioni e versioni

OpenXR 1.0

Data ultima modifica

2024-09-30

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Panoramica

Questa estensione consente all'applicazione di accedere ai dispositivi rilevabili dall'ambiente fisico e di creare ancore collegate a un dispositivo rilevabile.

Questa estensione definisce gli elementi tracciabili aerei. Altre estensioni possono aggiungere altri tipi di parametri monitorabili. Ad esempio, XR_ANDROID_trackables_object aggiunge oggetti tracceabili e XR_ANDROID_depth_texture aggiunge buffer di profondità che consentono il raycasting a punti arbitrari nell'ambiente.

Un rilevabile è un elemento che viene rilevato nell'ambiente fisico (vedi XrTrackableTypeANDROID):

  • un piano (ad es. parete, pavimento, soffitto, tavolo)
  • un oggetto (ad es. tastiera, mouse, laptop)

Creare un tracker monitorabile

Un XrTrackableTrackerANDROID è un handle che rappresenta le risorse necessarie per rilevare e aggiornare i rilevabili di un determinato XrTrackableTypeANDROID nell'ambiente.

XR_DEFINE_HANDLE(XrTrackableTrackerANDROID)

La funzione xrCreateTrackableTrackerANDROID è definita come: 

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

Descrizioni dei parametri

L'applicazione può utilizzare la funzione xrCreateTrackableTrackerANDROID per creare un tracker rilevabile.

  • XR_ERROR_FEATURE_UNSUPPORTED viene restituito se il sistema non supporta gli oggetti rilevabili del tipo specificato.
  • XR_ERROR_PERMISSION_INSUFFICIENT viene restituito se le autorizzazioni richieste non sono state concesse all'app chiamante.

L'applicazione può utilizzare l'handle del tracker restituito nelle chiamate API successive. L'handle XrTrackableTrackerANDROID deve essere eventualmente liberato utilizzando la funzione xrDestroyTrackableTrackerANDROID.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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 struttura XrTrackableTrackerCreateInfoANDROID è definita come segue: 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • trackableType è il valore XrTrackableTypeANDROID che verrà monitorato dal tracker.

La struttura XrTrackableTrackerCreateInfoANDROID fornisce opzioni di creazione per XrTrackableTrackerANDROID quando viene passata a xrCreateTrackableTrackerANDROID.

Le estensioni possono definire strutture che possono essere collegate a next per consentire una configurazione aggiuntiva per i tracker monitorabili.

Utilizzo valido (implicito)

L'enum XrTrackableTypeANDROID è definito come: 

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 funzione xrDestroyTrackableTrackerANDROID è definita come: 

XrResult xrDestroyTrackableTrackerANDROID(
    XrTrackableTrackerANDROID                   trackableTracker);

Descrizioni dei parametri

La funzione xrDestroyTrackableTrackerANDROID distrugge il tracker tracciabile.

Se non esiste un altro XrTrackableTrackerANDROID valido creato con lo stesso XrTrackableTypeANDROID, il sistema potrebbe disattivare i servizi di monitoraggio richiesti per quel tipo di rilevamento per risparmiare risorse di sistema.

Utilizzo valido (implicito)

Coerenza di thread

  • L'accesso a trackableTracker e a eventuali handle secondari deve essere sincronizzato esternamente

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Mostra tutti i dispositivi rilevabili

L'atomo XrTrackableANDROID è definito come:

XR_DEFINE_ATOM(XrTrackableANDROID)

XrTrackableANDROID viene utilizzato per rappresentare un singolo rilevabile ed è valido solo nel ciclo di vita del suo associato XrTrackableTrackerANDROID.

La funzione xrGetAllTrackablesANDROID è definita come: 

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

Descrizioni dei parametri

  • trackableTracker è l'XrTrackableTrackerANDROID su cui eseguire la query.

  • trackableCapacityInput è la capacità dell'array trackables o 0 per indicare una richiesta di recupero della capacità richiesta.

  • trackableCountOutput è un puntatore al conteggio di trackables scritto o un puntatore alla capacità richiesta nel caso in cui trackables sia insufficiente.

  • trackables è un puntatore a un array di XrTrackableANDROID. Può essere NULL se trackableCapacityInput è 0.

  • Per una descrizione dettagliata del recupero della dimensione trackables richiesta, consulta la sezione Parametri di dimensione del buffer.

xrGetAllTrackablesANDROID riempie un array di XrTrackableANDROID che rappresenta i rilevabili trovati nell'ambiente. Il valore XrTrackableTypeANDROID del valore trackables restituito deve corrispondere al valore XrTrackableTypeANDROID del valore trackableTracker.

Ottenere un aereo monitorabile

La funzione xrGetTrackablePlaneANDROID è definita come:

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

Descrizioni dei parametri

La funzione xrGetTrackablePlaneANDROID restituisce dettagli sul piano tracciabile, ad esempio la geometria, l'orientamento e lo stato del monitoraggio.

Le informazioni sul piano vengono risolte e sono relative allo spazio di base al momento della chiamata a xrGetTrackablePlaneANDROID utilizzando XrTrackableGetInfoANDROID::time, XrTrackableGetInfoANDROID::baseSpace.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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 struttura XrTrackableGetInfoANDROID è definita come: 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • trackable è il piano XrTrackableANDROID su cui eseguire la query.
  • baseSpace la posa dell'aereo sarà relativa a questo XrSpace in time.
  • time è il XrTime in cui valutare le coordinate rispetto al baseSpace.

La struttura XrTrackableGetInfoANDROID fornisce opzioni di query quando viene passata a xrGetTrackablePlaneANDROID. trackable deve corrispondere a trackableTracker utilizzato in xrGetTrackablePlaneANDROID.

XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID verrà restituito se il tipo monitorabile di trackable non è XR_TRACKABLE_TYPE_PLANE_ANDROID.

Utilizzo valido (implicito)

La struttura XrTrackablePlaneANDROID è definita come: 

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;

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • trackingState è lo stato XrTrackingStateANDROID dell'aereo.
  • centerPose è un XrPosef che definisce la posizione e l'orientamento del piano all'interno del sistema di riferimento del corrispondente XrTrackableGetInfoANDROID::baseSpace. Un orientamento dell'identità qui rappresenta assi di coordinate con +Y parallelo alla normale del piano.
  • extents è la dimensione XrExtent2Df del piano.
  • planeType è il valore XrPlaneTypeANDROID determinato dal runtime per questo piano.
  • planeLabel è il valore XrPlaneLabelANDROID determinato dal runtime per questo piano.
  • subsumedByPlane è il XrTrackableANDROID del piano che lo include (XR_NULL_TRACKABLE_ANDROID se non esiste).
  • lastUpdatedTime è il XrTime dell'ultimo aggiornamento del piano.
  • vertexCapacityInput è la capacità dell'array vertices o 0 per indicare una richiesta di recupero della capacità richiesta.
  • vertexCountOutput è un puntatore al conteggio di vertices scritto o un puntatore alla capacità richiesta nel caso in cui vertices non sia sufficiente.
  • vertices è un puntatore a un array di XrVector2f. Può essere NULL se vertexCapacityInput è 0. I vertici sono in ordine antiorario. Il poligono può essere concavo e non deve autointersecarsi.
  • Per una descrizione dettagliata del recupero della dimensione vertices richiesta, consulta la sezione Parametri di dimensione del buffer.

Utilizzo valido (implicito)

L'enum XrTrackingStateANDROID descrive lo stato del monitoraggio di 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

Descrizione

XR_TRACKING_STATE_PAUSED_ANDROID

Indica che il monitoraggio tracciabile o degli ancoraggi è in pausa, ma potrebbe essere ripreso in futuro.

XR_TRACKING_STATE_STOPPED_ANDROID

Il monitoraggio di questo elemento tracciabile è stato interrotto e non verrà mai ripreso.

XR_TRACKING_STATE_TRACKING_ANDROID

L'oggetto viene monitorato e la sua posa è attuale.

L'enum XrPlaneTypeANDROID indica il tipo di piano 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'enum XrPlaneLabelANDROID è un'etichetta per un piano 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;

Creare uno spazio di ancoraggio

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

Descrizioni dei parametri

  • session è la XrSession che crea lo spazio di ancoraggio.
  • createInfo è un puntatore a una struttura XrAnchorSpaceCreateInfoANDROID contenente i parametri da utilizzare per creare lo spazio di ancoraggio.
  • anchorOutput è un puntatore a un handle in cui viene restituito il XrSpace creato.

In qualsiasi momento, sia la posizione sia la direzione dell'ancora vengono monitorate o non monitorate. Ciò significa che sia XR_SPACE_LOCATION_POSITION_TRACKED_BIT sia XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT devono essere impostati o entrambi devono essere cancellati quando l'applicazione chiama xrLocateSpace o xrLocateSpaces per anchorOutput.

L'applicazione deve liberare l'XrSpace restituito utilizzando xrDestroySpace.

  • XR_ERROR_FEATURE_UNSUPPORTED deve essere restituito se il sistema non supporta le ancore.
  • Deve essere restituito XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID se l'attacco dell'ancora specifico non è supportato.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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 struttura XrAnchorSpaceCreateInfoANDROID è definita come: 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • space è lo XrSpace su cui verrà creata l'ancora.
  • time è l'XrTime della creazione dell'ancora.
  • pose è il XrPosef dell'ancora.
  • trackable è l'XrTrackableANDROID a cui verrà collegata l'ancora. Potrebbe essere XR_NULL_TRACKABLE_ANDROID per creare un ancoraggio spaziale.

Utilizzo valido (implicito)

Codice di esempio per ottenere tutti gli elementi tracciabili

Il seguente codice di esempio mostra come ottenere tutti gli elementi tracciabili di un determinato tipo.

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

Codice di esempio per ottenere il piano tracciabile

Il seguente codice di esempio mostra come ottenere un piano tracciabile da un XrTrackableANDROID esistente, ottenuto da un risultato di 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.
}

Codice di esempio per la creazione di uno spazio di ancoraggio

Il seguente codice di esempio mostra come creare uno spazio di ancoraggio associato a un elemento tracciabile.

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

Nuovi tipi di base

Nuovi tipi di oggetti

Nuove costanti enum

L'enumerazione XrStructureType è stata estesa con:

  • 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'enumerazione XrObjectType è estesa con:

  • XR_OBJECT_TYPE_TRACKABLE_TRACKER_ANDROID

L'enumerazione XrResult è stata estesa con:

  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID

Nuovi enum

Nuove strutture

Nuove funzioni

Problemi

Cronologia delle versioni

  • Revisione 1, 27-09-2024 (Kenny Vercaemer)
    • Descrizione iniziale dell'estensione.