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
typeist der XrStructureType dieser Struktur.nextistNULLoder 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 ).supportsImageTrackingist einXrBool32, der angibt, ob das aktuelle System die Funktion zur Bildverfolgung bietet.supportsPhysicalSizeEstimationist einXrBool32, das angibt, ob das aktuelle System eine Schätzung der Bildgröße ermöglicht.maxTrackedImageCountist die maximale Gesamtzahl der Bilder, die gleichzeitig getrackt werden können.maxLoadedImageCountist 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)
- Die
XR_ANDROID_trackables_image-Erweiterung muss aktiviert werden, bevor XrSystemImageTrackingPropertiesANDROID verwendet wird. -
typemussXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
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
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.trackingModeist ein XrTrackableImageTrackingModeANDROID, der den gewünschten Modus für das Tracking angibt.physicalWidthgibt die Breite des Bildes in Metern an. Bei null wird die Bildgröße online geschätzt.imageWidthgibt die Breite des Bildes in Pixeln an.imageHeightgibt die Höhe des Bildes in Pixeln an.formatist ein XrTrackableImageFormatANDROID, das das Format der Bilddaten inbufferangibt .bufferSizegibt die Bytelänge vonbufferan .bufferist deruint8_t-Puffer, der die Pixeldaten des Referenzbilds enthält. Der Inhalt vonbuffermuss 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
XR_ANDROID_trackables_image-Erweiterung muss aktiviert werden, bevor XrTrackableImageDatabaseEntryANDROID verwendet werden kann. -
typemussXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
trackingModemuss ein gültiger XrTrackableImageTrackingModeANDROID-Wert sein. -
formatmuss ein gültiger XrTrackableImageFormatANDROID-Wert sein. -
buffermuss ein Zeiger auf ein Array vonbufferSizeuint8_t-Werten sein. - Der Parameter
bufferSizemuss größer als0sein.
Die Struktur XrTrackableImageDatabaseCreateInfoANDROID ist so definiert:
typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t entryCount;
const XrTrackableImageDatabaseEntryANDROID* entries;
} XrTrackableImageDatabaseCreateInfoANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.entryCountist einuint32_t, das die Anzahl der Elemente imentries-Array angibt.entriesist ein Array von XrTrackableImageDatabaseEntryANDROID-Strukturen.
Gültige Nutzung (implizit)
- Die
XR_ANDROID_trackables_image-Erweiterung muss aktiviert werden, bevor XrTrackableImageDatabaseCreateInfoANDROID verwendet wird. -
typemussXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
entriesmuss ein Zeiger auf ein Array vonentryCountgültigen XrTrackableImageDatabaseEntryANDROID-Strukturen sein. - Der Parameter
entryCountmuss größer als0sein.
Die Struktur XrCreateTrackableImageDatabaseCompletionANDROID ist so definiert:
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.futureResultist das XrResult des asynchronen Vorgangs.databaseist das erstellte XrTrackableImageDatabaseANDROID-Handle.
Zukünftige Rückgabecodes
futureResult-Werte:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Gültige Nutzung (implizit)
- Die
XR_ANDROID_trackables_image-Erweiterung muss aktiviert werden, bevor XrCreateTrackableImageDatabaseCompletionANDROID verwendet wird. -
typemussXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
futureResultmuss ein gültiger XrResult-Wert sein. -
databasemuss ein gültiger XrTrackableImageDatabaseANDROID-Handle sein
Die Funktion xrCreateTrackableImageDatabaseAsyncANDROID ist so definiert:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Parameterbeschreibungen
sessionist ein Handle für eine XrSession, die zuvor mit xrCreateSession erstellt wurde .createInfoist ein Zeiger auf eine XrTrackableImageDatabaseCreateInfoANDROID-Struktur.futureist ein Zeiger auf das erstellteXrFutureEXT.
Gültige Nutzung (implizit)
- Die
XR_ANDROID_trackables_image-Erweiterung muss aktiviert werden, bevor xrCreateTrackableImageDatabaseAsyncANDROID aufgerufen wird. -
sessionmuss ein gültiger XrSession-Handle sein -
createInfomuss ein Zeiger auf eine gültige XrTrackableImageDatabaseCreateInfoANDROID-Struktur sein. -
futuremuss ein Zeiger auf einenXrFutureEXT-Wert sein.
Rückgabecodes
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Die Funktion xrCreateTrackableImageDatabaseCompleteANDROID ist so definiert:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
Parameterbeschreibungen
sessionist ein Handle für eine XrSession, die zuvor mit xrCreateSession erstellt wurde .futureist dieXrFutureEXTder Zukunft, die abgeschlossen werden soll.completionist ein Zeiger auf eine XrCreateTrackableImageDatabaseCompletionANDROID-Struktur, die das Ergebnis des Vorgangs enthält.
Gültige Nutzung (implizit)
- Die
XR_ANDROID_trackables_image-Erweiterung muss aktiviert werden, bevor xrCreateTrackableImageDatabaseCompleteANDROID aufgerufen wird. -
sessionmuss ein gültiger XrSession-Handle sein -
completionmuss ein Zeiger auf eine XrCreateTrackableImageDatabaseCompletionANDROID-Struktur sein.
Rückgabecodes
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Die Funktion xrDestroyTrackableImageDatabaseANDROID ist so definiert:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Parameterbeschreibungen
databaseist das XrTrackableImageDatabaseANDROID-Handle, das gelöscht werden soll.
Gültige Nutzung (implizit)
- Die
XR_ANDROID_trackables_image-Erweiterung muss aktiviert werden, bevor xrDestroyTrackableImageDatabaseANDROID aufgerufen wird. -
databasemuss ein gültiger XrTrackableImageDatabaseANDROID-Handle sein
Threadsicherheit
- Der Zugriff auf
databaseund alle untergeordneten Handles muss extern synchronisiert werden.
Rückgabecodes
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_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
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.databaseCountist einuint32_t, das die Anzahl der Elemente indatabasesangibt.databasesist 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)
- Die
XR_ANDROID_trackables_image-Erweiterung muss aktiviert werden, bevor XrTrackableImageConfigurationANDROID verwendet wird. -
typemussXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
databasesmuss ein Zeiger auf ein Array mitdatabaseCountgültigen XrTrackableImageDatabaseANDROID-Handles sein. - Der Parameter
databaseCountmuss größer als0sein.
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
trackerist das XrTrackableTrackerANDROID-Handle, demdatabasehinzugefügt werden soll.databaseist das XrTrackableImageDatabaseANDROID-Handle, das dertrackerhinzugefügt werden soll .
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)
- Die
XR_ANDROID_trackables_image-Erweiterung muss aktiviert werden, bevor xrAddTrackableImageDatabaseANDROID aufgerufen wird. -
trackermuss ein gültiger XrTrackableTrackerANDROID-Handle sein. -
databasemuss ein gültiger XrTrackableImageDatabaseANDROID-Handle sein - Sowohl
databaseals auchtrackermüssen aus derselben XrSession erstellt, zugewiesen oder abgerufen worden sein.
Rückgabecodes
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Die Funktion xrRemoveTrackableImageDatabaseANDROID ist so definiert:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Parameterbeschreibungen
trackerist das XrTrackableTrackerANDROID-Handle, aus dem dasdatabaseentfernt werden soll.databaseist das XrTrackableImageDatabaseANDROID-Handle, das austrackerentfernt werden soll .
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)
- Die
XR_ANDROID_trackables_image-Erweiterung muss aktiviert sein, bevor xrRemoveTrackableImageDatabaseANDROID aufgerufen wird. -
trackermuss ein gültiger XrTrackableTrackerANDROID-Handle sein. -
databasemuss ein gültiger XrTrackableImageDatabaseANDROID-Handle sein - Sowohl
databaseals auchtrackermüssen aus derselben XrSession erstellt, zugewiesen oder abgerufen worden sein.
Rückgabecodes
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Bilder abrufen
Die Funktion xrGetTrackableImageANDROID ist so definiert:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
Parameterbeschreibungen
trackerist der XrTrackableTrackerANDROID, der abgefragt werden soll.getInfoist XrTrackableGetInfoANDROID mit den Informationen, die zum Abrufen des verfolgbaren QR-Codes verwendet werden.trackableist ein Zeiger auf die XrTrackableImageANDROID-Struktur, in der das verfolgbare Bild zurückgegeben wird.
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)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert werden, bevor xrGetTrackableImageANDROID aufgerufen wird. -
trackermuss ein gültiger XrTrackableTrackerANDROID-Handle sein. -
getInfomuss ein Zeiger auf eine gültige XrTrackableGetInfoANDROID-Struktur sein. -
trackablemuss ein Zeiger auf eine XrTrackableImageANDROID-Struktur sein.
Rückgabecodes
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_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
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.trackingStateist der XrTrackingStateANDROID des Bildes.lastUpdatedTimeist derXrTimeder letzten Aktualisierung des Bildes.databaseist das XrTrackableImageDatabaseANDROID-Handle, aus dem dieses Bild verfolgt wurde.databaseEntryIndexist der Index, der dem XrTrackableImageDatabaseCreateInfoANDROID-Array ::entriesvondatabasezugeordnet wird .centerPoseist die XrPosef des Bildes, das sich in XrTrackableGetInfoANDROID ::baseSpacebefindet . Das Bild liegt in der XZ-Ebene, wobei X nach rechts und Z nach unten zeigt.extentssind die XrExtent2Df-Dimensionen des Bildes. Die Grenze des Begrenzungsrahmens liegt bei den Punkten:centerPose+/- (extents/ 2).
Gültige Nutzung (implizit)
- Die
XR_ANDROID_trackables_image-Erweiterung muss aktiviert werden, bevor XrTrackableImageANDROID verwendet werden kann. -
typemussXR_TYPE_TRACKABLE_IMAGE_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
trackingStatemuss ein gültiger XrTrackingStateANDROID-Wert sein -
databasemuss ein gültiger XrTrackableImageDatabaseANDROID-Handle sein
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
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.timeXrTime
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)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert werden, bevor XrEventDataImageTrackingLostANDROID verwendet wird. -
typemussXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
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
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
Neue Strukturen
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
XrSystemProperties erweitern :
Neue Enums
Neue Enum-Konstanten
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONXrObjectType 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_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_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.