XR_ANDROID_trackables_image

Name String

XR_ANDROID_trackables_image

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

710

Revision

1

Ratification Status (Status der Ratifizierung)

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

XR_EXT_future
und
XR_ANDROID_trackables

Datum der letzten Änderung

2025-04-08

IP-Status

Es sind keine Ansprüche wegen geistigen Eigentums bekannt.

Mitwirkende

Christopher Doer, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Diego Tipaldi, Google
Daniel Guttenberg, Qualcomm
Mark Vadasi, Qualcomm
Markus Birkner, Qualcomm
Maximilian Mayer, Qualcomm

Übersicht

Mit dieser Erweiterung können planare Bilder anhand von Gruppen von Referenzbildern verfolgt werden.

Berechtigungen

Android-Apps müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ in ihrem Manifest aufführen, da diese Erweiterung von XR_ANDROID_trackables abhängt und die Geometrie der Umgebung verfügbar macht. Die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ gilt als gefährliche Berechtigung.

(Schutzebene: gefährlich)

Systemfunktionen prüfen

Die Struktur XrSystemImageTrackingPropertiesANDROID ist so definiert:

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

Mitgliederbeschreibungen

  • 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. Weitere Informationen zur Strukturkette finden Sie in der Struktur, die erweitert wird ( XrSystemProperties ).
  • supportsImageTracking ist ein XrBool32, der angibt, ob das aktuelle System die Funktion zur Bildverfolgung bietet.
  • supportsPhysicalSizeEstimation ist ein XrBool32, das angibt, ob das aktuelle System eine Schätzung der Bildgröße ermöglicht.
  • maxTrackedImageCount ist die maximale Gesamtzahl der Bilder, die gleichzeitig getrackt werden können.
  • maxLoadedImageCount ist die maximale Gesamtzahl von Referenzbildern, die in allen Datenbanken geladen werden kann.

Eine Anwendung kann prüfen, ob das System Bild-Tracking unterstützt, indem sie die XrSystemProperties mit der Struktur XrSystemImageTrackingPropertiesANDROID erweitert, wenn xrGetSystemProperties aufgerufen wird . Die Laufzeit muss XR_ERROR_FEATURE_UNSUPPORTED für die Erstellung von Image-Trackern zurückgeben, wenn und nur wenn supportsImageTracking XR_FALSE ist .

Wenn eine Laufzeit die Bildverfolgung unterstützt, muss sie jederzeit maxTrackedImageCount verfolgte Bilder unterstützen.

Wenn eine Laufzeit das Bild-Tracking unterstützt, muss sie jederzeit maxLoadedImageCount geladene Bilder unterstützen.

Wenn eine Laufzeit die Schätzung der Bildgröße unterstützt, kann die Anwendung XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 festlegen, um die Verwendung der Schätzung der Bildgröße anzugeben. Andernfalls muss die Anwendung XrTrackableImageDatabaseEntryANDROID :: physicalWidth auf einen positiven Wert setzen. Andernfalls wird XR_ERROR_VALIDATION_FAILURE zurückgegeben.

Gültige Nutzung (implizit)

Datenbanken erstellen

Die Anwendung kann ein XrTrackableImageDatabaseANDROID-Handle erstellen, indem sie eine oder mehrere XrTrackableImageDatabaseEntryANDROID-Strukturen erstellt und sie über eine XrTrackableImageDatabaseCreateInfoANDROID-Struktur an die Funktion xrCreateTrackableImageDatabaseAsyncANDROID übergibt.

Die Anwendung muss beim Erstellen eines XrTrackableImageDatabaseANDROID-Handles mindestens einen XrTrackableImageDatabaseEntryANDROID bereitstellen.

Eine XrTrackableImageDatabaseANDROID ist ein Handle, das eine Reihe verarbeiteter Referenzbilder darstellt, die in der Umgebung erkannt und verfolgt werden können.

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

Die Struktur XrTrackableImageDatabaseEntryANDROID ist so definiert:

typedef struct XrTrackableImageDatabaseEntryANDROID {
    XrStructureType                        type;
    const void*                            next;
    XrTrackableImageTrackingModeANDROID    trackingMode;
    float                                  physicalWidth;
    uint32_t                               imageWidth;
    uint32_t                               imageHeight;
    XrTrackableImageFormatANDROID          format;
    uint32_t                               bufferSize;
    const uint8_t*                         buffer;
} XrTrackableImageDatabaseEntryANDROID;

Mitgliederbeschreibungen

  • 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.
  • trackingMode ist ein XrTrackableImageTrackingModeANDROID, der den gewünschten Modus für das Tracking angibt.
  • physicalWidth gibt die Breite des Bildes in Metern an. Bei null wird die Bildgröße online geschätzt.
  • imageWidth gibt die Breite des Bildes in Pixeln an.
  • imageHeight gibt die Höhe des Bildes in Pixeln an.
  • format ist ein XrTrackableImageFormatANDROID, das das Format der Bilddaten in buffer angibt .
  • bufferSize gibt die Bytelänge von buffer an .
  • buffer ist der uint8_t-Puffer, der die Pixeldaten des Referenzbilds enthält. Der Inhalt von buffer muss für die Dauer des asynchronen Vorgangs zum Erstellen der Datenbank gültig sein. Dieser wird durch xrCreateTrackableImageDatabaseAsyncANDROID gestartet und durch xrCreateTrackableImageDatabaseCompleteANDROID abgeschlossen.

Die Anwendung kann physicalWidth auf 0 setzen, um eine Online-Größenschätzung anzufordern, wenn XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation XR_TRUE ist .

Die Laufzeit kann XR_ERROR_VALIDATION_FAILURE von xrCreateTrackableImageDatabaseAsyncANDROID zurückgeben, wenn bufferSize nicht der erwarteten Größe basierend auf den imageWidth , imageHeight und format des Eintrags entspricht .

Gültige Nutzung (implizit)

Die Struktur XrTrackableImageDatabaseCreateInfoANDROID ist so definiert:

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

Mitgliederbeschreibungen

  • 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.
  • entryCount ist ein uint32_t, das die Anzahl der Elemente im entries-Array angibt.
  • entries ist ein Array von XrTrackableImageDatabaseEntryANDROID-Strukturen.

Gültige Nutzung (implizit)

Die Struktur XrCreateTrackableImageDatabaseCompletionANDROID ist so definiert:

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

Mitgliederbeschreibungen

  • 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.
  • futureResult ist das XrResult des asynchronen Vorgangs.
  • database ist das erstellte XrTrackableImageDatabaseANDROID-Handle.

Zukünftige Rückgabecodes

futureResult-Werte:

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Gültige Nutzung (implizit)

Die Funktion xrCreateTrackableImageDatabaseAsyncANDROID ist so definiert:

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

Parameterbeschreibungen

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Die Funktion xrCreateTrackableImageDatabaseCompleteANDROID ist so definiert:

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

Parameterbeschreibungen

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Die Funktion xrDestroyTrackableImageDatabaseANDROID ist so definiert:

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

Parameterbeschreibungen

Gültige Nutzung (implizit)

Threadsicherheit

  • Der Zugriff auf database und alle untergeordneten Handles muss extern synchronisiert werden.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Tracking-Bilder

Diese Erweiterung fügt XR_TRACKABLE_TYPE_IMAGE_ANDROID zu XrTrackableTypeANDROID hinzu .

Die Anwendung kann einen XrTrackableTrackerANDROID erstellen, indem sie xrCreateTrackableTrackerANDROID aufruft und XR_TRACKABLE_TYPE_IMAGE_ANDROID als verfolgbaren Typ in XrTrackableTrackerCreateInfoANDROID :: trackableType angibt, um Bilder zu verfolgen.

Die Laufzeit muss XR_ERROR_FEATURE_UNSUPPORTED zurückgeben, wenn XrTrackableTrackerCreateInfoANDROID :: trackableType XR_TRACKABLE_TYPE_IMAGE_ANDROID ist und XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking über xrGetSystemProperties XR_FALSE zurückgibt .

Die Struktur XrTrackableImageConfigurationANDROID ist so definiert:

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

Mitgliederbeschreibungen

  • 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.
  • databaseCount ist ein uint32_t, das die Anzahl der Elemente in databases angibt.
  • databases ist ein Array von XrTrackableImageDatabaseANDROID, das die Datenbanken angibt, mit denen der Tracker erstellt werden soll.

Die Anwendung muss eine gültige Konfiguration festlegen, indem sie der next-Kette von XrTrackableTrackerCreateInfoANDROID eine XrTrackableImageConfigurationANDROID hinzufügt . Andernfalls muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben .

Die Anwendung muss mindestens eine XrTrackableImageDatabaseANDROID-Struktur bereitstellen, mit der der Tracker erstellt werden kann.

Gültige Nutzung (implizit)

Das Enum XrTrackableImageTrackingModeANDROID beschreibt die unterstützten Tracking-Modi von Bildern.

typedef enum XrTrackableImageTrackingModeANDROID {
    XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;

Beschreibungen der Aufzählungstypen

  • XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID: Dieser Modus bietet die höchste Genauigkeit und ermöglicht die Verfolgung von bewegten Bildern mit geringer Latenz. Außerdem hat sie den höchsten Stromverbrauch.
  • XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID: Dieser Modus sollte für Bilder verwendet werden, die bekanntermaßen statisch oder semistatisch sind. Dieser Modus führt im Vergleich zum dynamischen Modus zu einem geringeren Stromverbrauch. Wenn ein statisches Bild verschoben wird, wird es mit einer viel höheren Latenz aktualisiert als im dynamischen Modus.

Die Enumeration XrTrackableImageFormatANDROID beschreibt die unterstützten Bildformate.

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

Beschreibungen der Aufzählungstypen

  • XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID – RGBA-Bildformat mit 8 Bit pro Kanal für Farb- und Transparenzdaten.

Die Funktion xrAddTrackableImageDatabaseANDROID ist so definiert:

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

Parameterbeschreibungen

Wenn einem Tracker eine XrTrackableImageDatabaseANDROID hinzugefügt wird, müssen die Referenzbilder dieser Datenbank zusätzlich zu allen anderen Datenbanken, die zuvor mit xrAddTrackableImageDatabaseANDROID oder über die Struktur XrTrackableImageConfigurationANDROID beim Erstellen des Trackers hinzugefügt wurden, für die Erkennung und das Tracking berücksichtigt werden.

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Die Funktion xrRemoveTrackableImageDatabaseANDROID ist so definiert:

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

Parameterbeschreibungen

Wenn eine XrTrackableImageDatabaseANDROID aus einem XrTrackableTrackerANDROID entfernt wird , dürfen die XrTrackableImageDatabaseEntryANDROID-Strukturen dieser Datenbank nicht mehr für die Erkennung und das Tracking berücksichtigt werden. Alle aktiv erfassten Einträge dieser Datenbank dürfen nicht mehr gemeldet werden. Das entfernte XrTrackableImageDatabaseANDROID-Handle darf im Rahmen dieses Vorgangs nicht implizit zerstört werden.

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Bilder abrufen

Die Funktion xrGetTrackableImageANDROID ist so definiert:

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

Parameterbeschreibungen

Die Laufzeit muss XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID zurückgeben , wenn der verfolgbare Typ von XrTrackableANDROID nicht XR_TRACKABLE_TYPE_IMAGE_ANDROID ist oder wenn der verfolgbare Typ von XrTrackableTrackerANDROID nicht XR_TRACKABLE_TYPE_IMAGE_ANDROID ist .

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrTrackableImageANDROID ist so definiert:

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

Mitgliederbeschreibungen

  • 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 Bildes.
  • lastUpdatedTime ist der XrTime der letzten Aktualisierung des Bildes.
  • database ist das XrTrackableImageDatabaseANDROID-Handle, aus dem dieses Bild verfolgt wurde.
  • databaseEntryIndex ist der Index, der dem XrTrackableImageDatabaseCreateInfoANDROID-Array :: entries von database zugeordnet wird .
  • centerPose ist die XrPosef des Bildes, das sich in XrTrackableGetInfoANDROID :: baseSpace befindet . Das Bild liegt in der XZ-Ebene, wobei X nach rechts und Z nach unten zeigt.
  • extents sind die XrExtent2Df-Dimensionen des Bildes. Die Grenze des Begrenzungsrahmens liegt bei den Punkten: centerPose +/- ( extents / 2).

Gültige Nutzung (implizit)

Fehlerbehandlung

Die Anwendung muss das Ereignis XrEventDataImageTrackingLostANDROID mit xrPollEvent abrufen und darf es nicht ignorieren.

Die Struktur XrEventDataImageTrackingLostANDROID ist so definiert:

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

Mitgliederbeschreibungen

  • 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.
  • time XrTime

Wenn das Ereignis XrEventDataImageTrackingLostANDROID empfangen wird, bedeutet das, dass das Image-Tracking beeinträchtigt wurde und ein interner Fehler aufgetreten ist, der dazu führt, dass vorhandene Ressourcen ungültig werden. Die Anwendung muss alle XrTrackableImageDatabaseANDROID-Handles zerstören und neu erstellen, wenn sie die Bildverfolgung fortsetzen möchte. Die Anwendung muss auch alle mit der Bilderkennung verknüpften XrTrackableTrackerANDROID-Handles zerstören und neu erstellen, wenn sie die Bilderkennung fortsetzen möchte.

Gültige Nutzung (implizit)

Beispielcode zum Abrufen von nachverfolgbaren Bildern

Der folgende Beispielcode zeigt, wie Sie nachverfolgbare Bilder abrufen.

XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace;  // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

// Inspect system capability
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
  {
    .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
    .next = nullptr,
    .trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
    .physicalWidth = 0.1f, // The width of the image in meters.
    .imageWidth = 640,
    .imageHeight = 480,
    .format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
    .bufferSize = imageBufferSize, // RGBA buffer size in bytes.
    .buffer = imageBuffer, // RGBA data.
  }
};

XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
  .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .entryCount = 1,
  .entries = imageDatabaseEntries
};

XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
  XrFuturePollInfoEXT pollInfo{
    .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
    .future = imageDatabaseFuture,
  };
  XrFuturePollResultEXT pollResult{
    .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
  };
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

  if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
    futureReady = true;
    keepLooping = false;
  } else {
    // Throttle the loop to not fully expend this CPU core.
    std::this_thread::yield();
  }
}

XrTrackableImageDatabaseANDROID imageDatabase;

if (futureReady) {
  XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
    .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
    .next = nullptr,
  };

  CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
  CHK_XR(imageDatabaseCompletion.futureResult);
  imageDatabase = imageDatabaseCompletion.database;
}

XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &imageDatabase
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.

// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

while (1) {
  uint32_t trackableCountOutput = 0;

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));

  std::vector<XrTrackableANDROID> allImageTrackables;
  allImageTrackables.resize(trackableCountOutput);

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));

  for (XrTrackableANDROID trackable : allImageTrackables) {
    XrTrackableGetInfoANDROID imageGetInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackable,
      .baseSpace = appSpace,
      .time = updateTime
    };

    XrTrackableImageANDROID trackableImage{
      .type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
    };
    CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));

    // Use XrTrackableImageANDROID data.
    (void)trackableImage.trackingState;
    (void)trackableImage.lastUpdatedTime;
    (void)trackableImage.centerPose;
    (void)trackableImage.extents;

    if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
      // Knowing which image the index of 0 maps to, use the specific image database
      // entry (e.g. rendering A for image A).
    }
    // indices 1+N comparisons for another specific image database entry.
  }

  // Throttle the loop to not fully expend this CPU core.
  std::this_thread::yield();
}

// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

Beispielcode für die Verwaltung von Bilddatenbanken zur Laufzeit

Das folgende Beispiel zeigt, wie Sie die Menge der verfolgten Bilder ändern.

XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.

// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 2,
  .databases = imageDatabases
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.

CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.

CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.

CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.

// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &anotherImageDatabase
};

XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &anotherImageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));

// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.

Beispielcode für die Reaktion auf Fehler beim Bild-Tracking

Im folgenden Beispielcode wird gezeigt, wie Fehler durch Abrufen des Ereignisses XrEventDataImageTrackingLostANDROID behandelt werden.

XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.

// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
  .type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
      const XrEventDataImageTrackingLostANDROID& eventdata =
        *reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);

      // All existing databases and trackers need to be destroyed.
      CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
      CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

      // To resume image tracking, the database(s) and the tracker need to be re-created.

      XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
        .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
        .next = nullptr,
        .entryCount = 1,
        .entries = imageDatabaseEntries
      };

      XrFutureEXT imageDatabaseFuture;
      CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

      while (true) {
        XrFuturePollInfoEXT pollInfo{
          .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
          .future = imageDatabaseFuture,
        };
        XrFuturePollResultEXT pollResult{
          .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
        };
        CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

        if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
          break;
        } else {
          // Throttle the loop to not fully expend this CPU core.
          std::this_thread::yield();
        }
      }

      XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
        .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
        .next = nullptr,
      };

      CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
      CHK_XR(imageDatabaseCompletion.futureResult);
      imageDatabase = imageDatabaseCompletion.database;

      XrTrackableImageConfigurationANDROID imageConfig {
       .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
       .next = nullptr,
       .databaseCount = 1,
       .databases = &imageDatabase
      };

      XrTrackableTrackerCreateInfoANDROID createInfo {
        .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
        .next = &imageConfig,
        .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
      };

      XrTrackableTrackerANDROID imageTrackableTracker;
      CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

      break;
    }
  }
}

Neue Objekttypen

Neue Befehle

Neue Strukturen

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • XrObjectType erweitern :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
  • XrResult erweitern :

    • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XrStructureType erweitern :

    • XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
  • XrTrackableTypeANDROID erweitern :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

Probleme

Versionsverlauf

  • Version 1, 08.04.2025 (Daniel Guttenberg)

    • Erste Beschreibung der Erweiterung.