OpenXR-Erweiterung „XR_ANDROID_trackables“

Namensstring

XR_ANDROID_trackables_object

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

467

Revision

1

Erweiterungs- und Versionsabhängigkeiten

XR_ANDROID_trackables

Datum der letzten Änderung

2024-10-03

IP-Status

Es sind keine Ansprüche aufgrund von Urheberrechten bekannt.

Mitwirkende

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Übersicht

Mit dieser Erweiterung können physische Objekte geortet werden. Dazu gehören beispielsweise Tastaturen, Mäuse und andere Objekte in der Umgebung.

Achtung:

Berechtigungen

Android-Anwendungen müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING“ in ihrem Manifest angeben, da diese Erweiterung davon abhängt und die Geometrie der Umgebung freigibt.XR_ANDROID_trackables Die Berechtigung „android.permission.SCENE_UNDERSTANDING“ gilt als gefährlich.
(Schutzniveau: gefährlich)

Objekte verfolgen

Mit dieser Erweiterung wird XR_TRACKABLE_TYPE_OBJECT_ANDROID zu XrTrackableTypeANDROID hinzugefügt.

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

Objekt mit Tracking-Funktion abrufen

Die Funktion xrGetTrackableObjectANDROID ist so definiert:

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

Parameterbeschreibungen

• tracker ist der XrTrackableTrackerANDROID, der abgefragt werden soll.
  • getInfo ist die XrTrackableGetInfoANDROID mit den Informationen, die zum Abrufen des trackbaren Objekts verwendet wurden.
  • objectOutput ist ein Zeiger auf die Struktur XrTrackableObjectANDROID, in der das trackbare Objekt zurückgegeben wird.

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

Gültige Verwendung (implizit)

• Die Erweiterung XR_ANDROID_trackables_object muss aktiviert sein, bevor xrGetTrackableObjectANDROID aufgerufen wird.
  • tracker muss ein gültiger XrTrackableTrackerANDROID-Handle sein
  • getInfo muss ein Verweis auf eine gültige XrTrackableGetInfoANDROID-Struktur sein.
  • objectOutput muss ein Zeiger auf eine XrTrackableObjectANDROID-Struktur sein

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

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

• type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • trackingState ist der XrTrackingStateANDROID des Objekts.
  • centerPose ist die XrPosef des Objekts in XrTrackableGetInfoANDROID::baseSpace.
  • extents ist die Dimension XrExtent3DfEXT des Objekts.
  • objectLabel ist das XrObjectLabelANDROID, das die Laufzeit für dieses Objekt ermittelt hat.
  • lastUpdatedTime ist die XrTime der letzten Aktualisierung des Objekts.

Gültige Verwendung (implizit)

• Die Erweiterung XR_ANDROID_trackables_object muss aktiviert sein, bevor XrTrackableObjectANDROID verwendet werden kann.
  • type muss XR_TYPE_TRACKABLE_OBJECT_ANDROID sein.
  • next muss NULL oder ein gültiger Verweis auf die nächste Struktur in einer Strukturkette sein
  • trackingState muss ein gültiger Wert für XrTrackingStateANDROID sein
  • objectLabel muss ein gültiger Wert für XrObjectLabelANDROID sein

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;

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;
XrTrackableTracker objectTrackableTracker;
XrResult result = xrCreateTrackableTrackerANDROID(
  session,
  &createInfo,
  &objectrackableTracker);
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.space = 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 wurde um folgende Elemente erweitert:

• XR_TYPE_TRACKABLE_OBJECT_ANDROID
• XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

Die Aufzählung XrTrackableTypeANDROID wurde um folgende Werte erweitert:

• XR_TRACKABLE_TYPE_OBJECT_ANDROID

Neue Enums

• XrObjectLabelANDROID

Neue Strukturen

• XrTrackableObjectANDROID

Neue Funktionen

• xrGetTrackableObjectANDROID

Probleme

Versionsverlauf

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