XR_ANDROID_trackables_image
Name String
XR_ANDROID_trackables_image
Erweiterungstyp
Instanzerweiterung
Registrierte Durchwahl
710
Revision
1
Ratification Status
Nicht ratifiziert
Erweiterungs- und Versionsabhängigkeiten
XR_EXT_future
und
XR_ANDROID_trackables
Datum der letzten Änderung
2025-04-08
IP-Status
Keine bekannten Ansprüche auf geistiges Eigentum.
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
Diese Erweiterung ermöglicht das Tracking von planaren Bildern, wie in Sätzen von Eingabe-Referenzbildern angegeben.
Berechtigungen
Android-Apps müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ in ihrem Manifest enthalten, da diese Erweiterung von XR_ANDROID_trackables abhängt und die Geometrie der Umgebung offenlegt. Die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ gilt als gefährliche Berechtigung.
(Schutzebene: gefährlich)
Systemkapazität 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 weder in OpenXR noch in dieser Erweiterung definiert. Weitere Informationen zur Strukturkette finden Sie in der erweiterten Struktur ( XrSystemProperties).supportsImageTrackingist einXrBool32, der angibt, ob das aktuelle System die Möglichkeit bietet, Bilder zu tracken.supportsPhysicalSizeEstimationist einXrBool32, der angibt, ob das aktuelle System eine Schätzung der Image-Größe bereitstellt.maxTrackedImageCountist die maximale Anzahl von Bildern, die gleichzeitig getrackt werden können.maxLoadedImageCountist die maximale Gesamtzahl der Referenzbilder, die in allen Datenbanken geladen werden können.
Eine Anwendung kann prüfen, ob das System in der Lage ist, Bilder zu tracken, indem sie XrSystemProperties beim Aufruf von xrGetSystemProperties um die Struktur XrSystemImageTrackingPropertiesANDROID erweitert. Die Laufzeit muss XR_ERROR_FEATURE_UNSUPPORTED für die Erstellung des Bild-Trackers zurückgeben, wenn und nur wenn supportsImageTracking XR_FALSE ist.
Wenn eine Laufzeit das Bild-Tracking unterstützt, muss sie jederzeit maxTrackedImageCount getrackte Bilder unterstützen.
Wenn eine Laufzeitumgebung 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 Größenschätzung anzugeben. Andernfalls muss die Anwendung XrTrackableImageDatabaseEntryANDROID :: physicalWidth auf einen positiven Wert setzen, da sonst XR_ERROR_VALIDATION_FAILURE zurückgegeben wird.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert werden, bevor XrSystemImageTrackingPropertiesANDROID verwendet werden kann. -
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 mindestens einen XrTrackableImageDatabaseEntryANDROID bereitstellen, wenn ein XrTrackableImageDatabaseANDROID-Handle erstellt wird.
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 weder in OpenXR noch in dieser Erweiterung definiert.trackingModeist ein XrTrackableImageTrackingModeANDROID, der den gewünschten Tracking-Modus angibt.physicalWidthgibt die Breite des Bildes in Metern an. Wenn der Wert „0“ ist, wird die Image-Größ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-Zwischenspeicher, der die Pixeldaten des Referenzbilds enthält. Der Inhalt vonbuffermuss für die Dauer des asynchronen Vorgangs zur Datenbankerstellung gültig sein, der von xrCreateTrackableImageDatabaseAsyncANDROID gestartet und von xrCreateTrackableImageDatabaseCompleteANDROID abgeschlossen wird.
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 entspricht, die sich aus imageWidth, imageHeight und format des Eintrags ergibt.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert sein, 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 weder in OpenXR noch in dieser Erweiterung definiert.entryCountist einuint32_t, der die Anzahl der Elemente imentries-Array angibt.entriesist ein Array von XrTrackableImageDatabaseEntryANDROID-Strukturen.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert sein, bevor XrTrackableImageDatabaseCreateInfoANDROID verwendet werden kann. -
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 mitentryCountgü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 weder in OpenXR noch in dieser Erweiterung 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 Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert sein, bevor XrCreateTrackableImageDatabaseCompletionANDROID verwendet werden kann. -
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ültiges 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 Verweis auf die erstellteXrFutureEXT.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert werden, bevor xrCreateTrackableImageDatabaseAsyncANDROID aufgerufen wird. -
sessionmuss ein gültiges 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 es zu vervollständigen gilt.completionist ein Zeiger auf eine XrCreateTrackableImageDatabaseCompletionANDROID-Struktur, die das Ergebnis des Vorgangs enthält.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert sein, bevor xrCreateTrackableImageDatabaseCompleteANDROID aufgerufen wird. -
sessionmuss ein gültiges 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 zu löschende XrTrackableImageDatabaseANDROID-Handle.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert sein, bevor xrDestroyTrackableImageDatabaseANDROID aufgerufen wird. -
databasemuss ein gültiges 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 trackbaren Typ in XrTrackableTrackerCreateInfoANDROID :: trackableType angibt, um Bilder zu tracken.
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 weder in OpenXR noch in dieser Erweiterung definiert.databaseCountist einuint32_t, der 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, um den Tracker zu erstellen.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert werden, bevor XrTrackableImageConfigurationANDROID verwendet werden kann. -
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 vondatabaseCountgültigen XrTrackableImageDatabaseANDROID-Handles sein - Der Parameter
databaseCountmuss größer als0sein.
Das Enum XrTrackableImageTrackingModeANDROID beschreibt die unterstützten Tracking-Modi für Bilder.
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 Enumeranten
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID: Dieser Modus bietet die höchste Genauigkeit und ermöglicht das Tracking von bewegten Bildern mit geringer Latenz. Sie hat auch den höchsten Stromverbrauch.XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID: Dieser Modus sollte für Bilder verwendet werden, die statisch oder semistatisch sind. Dieser Modus verbraucht weniger Strom als der dynamische Modus. Wenn ein statisches Bild bewegt wird, wird es mit einer viel höheren Latenz aktualisiert als im dynamischen Modus.
Das Enum 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 Enumeranten
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID– RGBA-Bildformat mit 8 Bit pro Farbkanal und Transparenzdaten.
Die Funktion xrAddTrackableImageDatabaseANDROID ist so definiert:
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Parameterbeschreibungen
trackerist das XrTrackableTrackerANDROID-Handle, dem derdatabasehinzugefügt werden soll.databaseist das XrTrackableImageDatabaseANDROID-Handle, das demtrackerhinzugefü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 entweder 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 Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert werden, bevor xrAddTrackableImageDatabaseANDROID aufgerufen wird. -
trackermuss ein gültiges XrTrackableTrackerANDROID-Handle sein -
databasemuss ein gültiges 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 aus dertrackerentfernt 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 nicht im Rahmen dieses Vorgangs implizit gelöscht werden.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert sein, bevor xrRemoveTrackableImageDatabaseANDROID aufgerufen wird. -
trackermuss ein gültiges XrTrackableTrackerANDROID-Handle sein -
databasemuss ein gültiges 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 werden abgerufen
Die Funktion xrGetTrackableImageANDROID ist so definiert:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
Parameterbeschreibungen
trackerist der XrTrackableTrackerANDROID, der abgefragt werden soll.getInfoist die XrTrackableGetInfoANDROID mit den Informationen, die zum Abrufen des trackbaren QR-Codes verwendet werden.trackableist ein Zeiger auf die XrTrackableImageANDROID-Struktur, in der das trackbare Bild zurückgegeben wird.
Die Laufzeit muss XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID zurückgeben, wenn der trackbare Typ von XrTrackableANDROID nicht XR_TRACKABLE_TYPE_IMAGE_ANDROID ist oder wenn der trackbare Typ von XrTrackableTrackerANDROID nicht XR_TRACKABLE_TYPE_IMAGE_ANDROID ist.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert sein, bevor xrGetTrackableImageANDROID aufgerufen wird. -
trackermuss ein gültiges 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 weder in OpenXR noch in dieser Erweiterung definiert.trackingStateist der XrTrackingStateANDROID des Bildes.lastUpdatedTimeist derXrTimeder letzten Aktualisierung des Images.databaseist das XrTrackableImageDatabaseANDROID-Handle, von dem dieses Bild erfasst wurde.databaseEntryIndexist der Index, der dementries-Array vondatabasein XrTrackableImageDatabaseCreateInfoANDROID zugeordnet ist.centerPoseist die XrPosef des Bildes in XrTrackableGetInfoANDROID ::baseSpace. Das Bild liegt in der XZ-Ebene, wobei X nach rechts und Z nach unten zeigt.extentssind die XrExtent2Df-Abmessungen des Bildes. Die Grenze des Begrenzungsrahmens liegt bei den Punkten:centerPose+/– (extents/ 2).
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert sein, 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ültiges XrTrackableImageDatabaseANDROID-Handle sein
Fehlerbehandlung
Die Anwendung muss das Ereignis XrEventDataImageTrackingLostANDROID mit xrPollEvent abfragen 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 weder in OpenXR noch in dieser Erweiterung definiert.timeXrTime
Wenn das Ereignis XrEventDataImageTrackingLostANDROID empfangen wird, bedeutet das, dass beim Bild-Tracking ein interner Fehler aufgetreten ist, der dazu führt, dass vorhandene Ressourcen ungültig werden. Die Anwendung muss alle XrTrackableImageDatabaseANDROID-Handles löschen und neu erstellen, wenn das Bild-Tracking fortgesetzt werden soll. Die Anwendung muss außerdem alle XrTrackableTrackerANDROID-Handles im Zusammenhang mit dem Bild-Tracking löschen und neu erstellen, wenn das Bild-Tracking fortgesetzt werden soll.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_trackables_imagemuss aktiviert sein, bevor XrEventDataImageTrackingLostANDROID verwendet werden kann. -
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 trackbaren Bildern
Der folgende Beispielcode zeigt, wie Sie trackbare 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 zum Verwalten von Bilddatenbanken zur Laufzeit
Im folgenden Beispielcode wird gezeigt, wie Sie die Gruppe der erkannten 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
Der folgende Beispielcode zeigt, wie Sie einen Fehler durch Abfragen des Ereignisses XrEventDataImageTrackingLostANDROID beheben können.
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 Gebäude
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
Erweiterung von XrSystemProperties :
Neue Enums
Neue Enum-Konstanten
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONErweiterung von XrObjectType :
XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
Erweiterung von XrResult :
XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
Erweiterung von XrStructureType :
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
Erweiterung von XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_IMAGE_ANDROID
Probleme
Versionsverlauf
Version 1, 08.04.2025 (Daniel Guttenberg)
- Erste Beschreibung der Erweiterung.