Estensione OpenXR XR_ANDROID_trackables_object

Stringa del nome

XR_ANDROID_trackables_object

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

467

Revisione

1

Dipendenze di estensioni e versioni

XR_ANDROID_trackables

Data ultima modifica

01/11/2024

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

Diego Tipaldi, Google

David Joseph Tan, Google

Christopher Doer, Google

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Panoramica

Questa estensione consente il monitoraggio di oggetti fisici. Ad esempio, tastiere, mouse e altri oggetti nell'ambiente.

Monitora gli oggetti

Questa estensione aggiunge XR_TRACKABLE_TYPE_OBJECT_ANDROID a XrTrackableTypeANDROID.

L'applicazione potrebbe creare un XrTrackableTrackerANDROID chiamando xrCreateTrackableTrackerANDROID e specificando XR_TRACKABLE_TYPE_OBJECT_ANDROID come tipo tracciabile in XrTrackableTrackerCreateInfoANDROID::trackableType per monitorare gli oggetti.

La struttura XrTrackableObjectConfigurationANDROID è definita come:

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

Descrizioni dei membri

• type è l'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.
• labelCount è il conteggio di activeLabels.
• activeLabels è un puntatore all'array di XRObjectLabelANDROID che indica gli oggetti attivi nel monitoraggio.

L'applicazione potrebbe impostare una configurazione aggiuntiva aggiungendo un XrTrackableObjectConfigurationANDROID alla catena successiva di XrTrackableTrackerCreateInfoANDROID. L'output di xrGetAllTrackablesANDROID verrà filtrato in modo da corrispondere a activeLabels.

Se l'applicazione non imposta XrTrackableObjectConfigurationANDROID, tutti gli oggetti identificati dal sistema verranno monitorati.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_trackables_object deve essere attivata prima di utilizzare XrTrackableObjectANDROID
• type deve essere XR_TYPE_TRACKABLE_OBJECT_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• activeLabels deve essere un puntatore a un array di valori labelCount XrObjectLabelANDROID validi
• Il parametro labelCount deve essere maggiore di 0

L'enum XrObjectLabelANDROID è un'etichetta per un oggetto 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;

Recupera l'oggetto tracciabile

La funzione xrGetTrackableObjectANDROID è definita come:

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

Descrizioni dei parametri

• tracker è l'XrTrackableTrackerANDROID su cui eseguire la query.
• getInfo è l'XrTrackableGetInfoANDROID con le informazioni utilizzate per recuperare l'oggetto tracciabile.
• objectOutput è un puntatore alla struttura XrTrackableObjectANDROID in cui viene restituito l'oggetto tracciabile.

XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID viene restituito se il tipo monitorabile di XrTrackableANDROID non è XR_TRACKABLE_TYPE_OBJECT_ANDROID o se il tipo monitorabile di XrTrackableTrackerANDROID non è XR_TRACKABLE_TYPE_OBJECT_ANDROID.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_trackables_object deve essere attivata prima di chiamare xrGetTrackableObjectANDROID
• tracker deve essere un handle XrTrackableTrackerANDROID valido
• getInfo deve essere un puntatore a una struttura XrTrackableGetInfoANDROID valida
• objectOutput deve essere un puntatore a una struttura XrTrackableObjectANDROID.

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

La struttura XrTrackableObjectANDROID è definita come:

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

Descrizioni dei membri

• type è l'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 è l'XrTrackingStateANDROID dell'oggetto.
• centerPose è l'XrPosef dell'oggetto situato in XrTrackableGetInfoANDROID::baseSpace.
• extents è la dimensione XrExtent3DfEXT dell'oggetto.
• objectLabel è l'XrObjectLabelANDROID determinato dal runtime per questo oggetto.
• lastUpdatedTime è l'XrTime dell'ultimo aggiornamento dell'oggetto.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_trackables_object deve essere attivata prima di utilizzare XrTrackableObjectANDROID
• type deve essere XR_TYPE_TRACKABLE_OBJECT_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• trackingState deve essere un valore XrTrackingStateANDROID valido
• objectLabel deve essere un valore XrObjectLabelANDROID valido

Codice di esempio per ottenere oggetti tracciabili

Il seguente codice di esempio mostra come ottenere oggetti tracciabili.

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

Nuove costanti enum

L'enumerazione XrStructureType è stata estesa con:

• XR_TYPE_TRACKABLE_OBJECT_ANDROID
• XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

L'enumerazione XrTrackableTypeANDROID è stata estesa con:

• XR_TRACKABLE_TYPE_OBJECT_ANDROID

Nuovi enum

• XrObjectLabelANDROID

Nuove strutture

• XrTrackableObjectANDROID
• XrTrackableObjectConfigurationANDROID

Nuove funzioni

• xrGetTrackableObjectANDROID

Problemi

Cronologia delle versioni

• Revisione 1, 03/10/2024 (Kenny Vercaemer)
  • Descrizione iniziale dell'estensione.

OpenXR™ e il logo OpenXR sono marchi di proprietà di The Khronos Group Inc. e sono registrati come marchi in Cina, nell'Unione Europea, in Giappone e nel Regno Unito.