OpenXR-Erweiterung „XR_ANDROID_trackables_object“

Namensstring

XR_ANDROID_trackables_object

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

467

Revision

1

Erweiterungs- und Versionsabhängigkeiten

XR_ANDROID_trackables

Datum der letzten Änderung

2024-11-01

IP-Status

Es sind keine Ansprüche aufgrund von Urheberrechten bekannt.

Mitwirkende

Diego Tipaldi, Google

David Joseph Tan, Google

Christopher Doer, Google

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Übersicht

Mit dieser Erweiterung wird das Tracking physischer Objekte ermöglicht. Dazu gehören beispielsweise Tastaturen, Mäuse und andere Objekte in der Umgebung.

Objekte verfolgen

Mit dieser Erweiterung wird XR_TRACKABLE_TYPE_OBJECT_ANDROID zu XrTrackableTypeANDROID hinzugefügt.

Die Anwendung kann ein XrTrackableTrackerANDROID erstellen, indem sie xrCreateTrackableTrackerANDROID aufruft und XR_TRACKABLE_TYPE_OBJECT_ANDROID als trackbaren Typ in XrTrackableTrackerCreateInfoANDROID::trackableType angibt, um Objekte zu verfolgen.

Die Struktur XrTrackableObjectConfigurationANDROID ist so definiert: 

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

Beschreibungen von Mitgliedern

  • type ist die XrStructureType dieses Elements.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • labelCount ist die Anzahl von activeLabels.
  • activeLabels ist ein Verweis auf das Array von XRObjectLabelANDROID, das die aktiven Objekte im Tracking angibt.

Die Anwendung kann eine zusätzliche Konfiguration festlegen, indem der nächsten Kette von XrTrackableTrackerCreateInfoANDROID ein XrTrackableObjectConfigurationANDROID hinzugefügt wird. Die Ausgabe von xrGetAllTrackablesANDROID wird so gefiltert, dass sie mit activeLabels übereinstimmt.

Wenn die Anwendung XrTrackableObjectConfigurationANDROID nicht festlegt, werden alle vom System erkannten Objekte erfasst.

Gültige Nutzung (implizit)

Die XrObjectLabelANDROID-Enumeration ist ein Label für ein XrTrackableANDROID-Objekt. 

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;

Objekt mit Tracking-Funktion abrufen

Die Funktion xrGetTrackableObjectANDROID ist so definiert:

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

Parameterbeschreibungen

XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID wird zurückgegeben, wenn der trackbare Typ von XrTrackableANDROID nicht XR_TRACKABLE_TYPE_OBJECT_ANDROID ist oder der trackbare Typ von XrTrackableTrackerANDROID nicht XR_TRACKABLE_TYPE_OBJECT_ANDROID ist.

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur XrTrackableObjectANDROID ist so definiert: 

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

Beschreibungen von Mitgliedern

Gültige Nutzung (implizit)

Beispielcode zum Abrufen von trackbaren Objekten

Im folgenden Beispielcode wird veranschaulicht, wie sich trackbare Objekte abrufen lassen.

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

Neue Enum-Konstanten

Die Aufzählung XrStructureType wird um Folgendes erweitert:

  • XR_TYPE_TRACKABLE_OBJECT_ANDROID
  • XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

Die Aufzählung XrTrackableTypeANDROID wurde um Folgendes erweitert:

  • XR_TRACKABLE_TYPE_OBJECT_ANDROID

Neue Enums

Neue Strukturen

Neue Funktionen

Probleme

Versionsverlauf

  • Revision 1, 03.10.2024 (Kenny Vercaemer)
    • Erste Beschreibung der Erweiterung.

OpenXR™ und das OpenXR-Logo sind Marken der Khronos Group Inc. und sind als Marke in China, der Europäischen Union, Japan und dem Vereinigten Königreich eingetragen.