Rozszerzenie OpenXR XR_ANDROID_trackables_object

Ciąg znaków nazwy

XR_ANDROID_trackables_object

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

467

Wersja

1

Zależności rozszerzeń i wersji

XR_ANDROID_trackables

Data ostatniej modyfikacji

2024-11-01

Stan adresu IP

Brak znanych roszczeń dotyczących praw autorskich do treści objętych ochroną prawną.

Twórcy

Diego Tipaldi, Google

David Joseph Tan, Google

Christopher Doer, Google

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Omówienie

To rozszerzenie umożliwia śledzenie obiektów fizycznych. Na przykład klawiatury, myszy i inne obiekty w otoczeniu.

Śledzenie obiektów

To rozszerzenie dodaje XR_TRACKABLE_TYPE_OBJECT_ANDROID do XrTrackableTypeANDROID.

Aplikacja może utworzyć XrTrackableTrackerANDROID, wywołując xrCreateTrackableTrackerANDROID i określając XR_TRACKABLE_TYPE_OBJECT_ANDROID jako typ śledzenia w XrTrackableTrackerCreateInfoANDROID::trackableType, aby śledzić obiekty.

Struktura XrTrackableObjectConfigurationANDROID została zdefiniowana w ten sposób: 

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. Nie ma żadnych takich struktur zdefiniowanych w podstawowej wersji OpenXR ani w tym rozszerzeniu.
  • labelCount to liczba wartości activeLabels.
  • activeLabels to wskaźnik do tablicy XRObjectLabelANDROIDwskazującej aktywne obiekty w śledzeniu.

Aplikacja może ustawić dodatkową konfigurację, dodając XrTrackableObjectConfigurationANDROID do następnego łańcucha XrTrackableTrackerCreateInfoANDROID. Dane wyjściowe funkcji xrGetAllTrackablesANDROID zostaną odfiltrowane, aby pasowały do funkcji activeLabels.

Jeśli aplikacja nie ma ustawionego parametru XrTrackableObjectConfigurationANDROID, będą śledzone wszystkie obiekty zidentyfikowane przez system.

Prawidłowe użycie (domyślne)

Wyliczenie XrObjectLabelANDROID to etykieta obiektu 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;

Pobieranie obiektu śledzonego

Funkcja xrGetTrackableObjectANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

Wartość XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID zostanie zwrócona, jeśli typ XrTrackableANDROID nie jest XR_TRACKABLE_TYPE_OBJECT_ANDROID lub jeśli typ XrTrackableTrackerANDROID nie jest XR_TRACKABLE_TYPE_OBJECT_ANDROID.

Prawidłowe użycie (domyślne)

Kody zwrotne

Gotowe

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Struktura XrTrackableObjectANDROID jest zdefiniowana w ten sposób: 

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

Opisy członków

Prawidłowe użycie (domyślne)

Przykładowy kod służący do uzyskiwania śledzonych obiektów

Poniższy przykładowy kod pokazuje, jak pobierać obiekty śledzenia.

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

Nowe stałe typu wyliczeniowego

Wyliczenie XrStructureType zostało rozszerzone o:

  • XR_TYPE_TRACKABLE_OBJECT_ANDROID
  • XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

Wyliczenie XrTrackableTypeANDROID zostało rozszerzone o:

  • XR_TRACKABLE_TYPE_OBJECT_ANDROID

Nowe wartości w polu enum

Nowe struktury

Nowe funkcje

Problemy

Historia wersji

  • Wersja 1, 3.10.2024 (Kenny Vercaemer)
    • Początkowy opis rozszerzenia.

OpenXR™ i logo OpenXR są znakami towarowymi należącymi do The Khronos Group Inc. i zarejestrowanymi jako znak towarowy w Chinach, Unii Europejskiej, Japonii i Wielkiej Brytanii.