XR_EXT_spatial_image_tracking

Name String

XR_EXT_spatial_image_tracking

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

783

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

XR_EXT_spatial_entity

Mitwirkende

Daniel Guttenberg, Qualcomm
Nihav Jain, Google
Jared Finder, Google
Zhipeng Liu, ByteDance

Übersicht

Diese Erweiterung bietet die Funktion zum Bild-Tracking für die Erweiterung XR_EXT_spatial_entity. Damit können Anwendungen bestimmte ebene Bilder erkennen und verfolgen, die durch Sätze von Eingabe-Referenzbildern angegeben werden.

Ein getracktes Bild wird als räumliche Entität mit den folgenden Komponenten dargestellt:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Anwendungen verwenden die Erweiterung für das räumliche Bild-Tracking in der Regel nach dem folgenden Muster:

  • Eine Anwendung erstellt zuerst ein oder mehrere XrSpatialImageTrackingDatabaseEXT-Handles basierend auf Sätzen vorab geladener Referenzbilddaten.
  • Die Anwendung erstellt dann ein XrSpatialContextEXT-Handle basierend auf den zuvor erstellten XrSpatialImageTrackingDatabaseEXT-Handles.
  • Die Anwendung gibt dann die Referenzbilddaten frei, um den Arbeitsspeicherverbrauch zu reduzieren.
  • Die Anwendung sucht und fragt Bilder gemäß den Zugriffsmustern für räumliche Entitäten ab.
  • Die Anwendung kann zusätzliche Sätze von Referenzbildern laden und daraus zusätzliche XrSpatialImageTrackingDatabaseEXT und anschließend XrSpatialContextEXT erstellen, um den Satz erkennbarer und verfolgbarer Bilder zur Laufzeit dynamisch zu erweitern.
  • Die Anwendung kann XrSpatialImageTrackingDatabaseEXT-Handles zerstören, um die Anzahl der erkennbaren und verfolgbaren Bilder zur Laufzeit dynamisch zu reduzieren.
  • Die Anwendung kann XrSpatialContextEXT-Handles zerstören, um die Anzahl der erkennbaren und verfolgbaren Bilder zur Laufzeit dynamisch zu reduzieren.

Laufzeitunterstützung

Eine Laufzeit muss die Unterstützung für die Bild-Tracking-Funktion mit xrEnumerateSpatialCapabilitiesEXT angeben, indem sie die folgende Funktion auflistet:

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Konfiguration

Um die Erkennung und das Tracking von planaren Bildern zu aktivieren, kann die Anwendung XrSpatialCapabilityConfigurationImageTrackingEXT-Strukturen in XrSpatialContextCreateInfoEXT :: capabilityConfigs übergeben, wenn die Funktion xrCreateSpatialContextAsyncEXT aufgerufen wird, und Arrays von XrSpatialImageTrackingDatabaseEXT-Strukturen in jedem XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases übergeben.

Eingabebildsatz erstellen

Um die zu erkennenden und zu verfolgenden Referenzbilder anzugeben, muss die Anwendung mindestens einen Satz von Eingabereferenzbildern erstellen. Ein Satz von Eingabe-Referenzbildern wird durch ein XrSpatialImageTrackingDatabaseEXT-Handle dargestellt und enthält mindestens ein Bild.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

Das XrSpatialImageTrackingDatabaseEXT-Handle stellt die Ressourcen zum Erkennen und Aktualisieren einer bestimmten Anzahl von räumlichen Bildern in der Umgebung des Nutzers dar. Anwendungen können dieses Handle verwenden, um räumliche Bilder mithilfe anderer Funktionen in dieser Erweiterung zu finden und zu aktualisieren.

Datenbank für räumliches Bild-Tracking erstellen

Die Funktion xrCreateSpatialImageTrackingDatabaseAsyncEXT ist so definiert:

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Parameterbeschreibungen

  • session ist eine XrSession, in der die Datenbank für das räumliche Bild-Tracking aktiv ist.
  • createInfo ist die XrSpatialImageTrackingDatabaseCreateInfoEXT, mit der die Parameter der Datenbank für das räumliche Bild-Tracking angegeben werden.
  • future ist ein Zeiger auf ein XrFutureEXT .

Eine Anwendung kann ein XrSpatialImageTrackingDatabaseEXT-Handle mit der Funktion xrCreateSpatialImageTrackingDatabaseAsyncEXT erstellen und die Sätze von Eingabe-Referenzbildern der Bildtracking-Datenbank mit createInfo konfigurieren.

Die Laufzeit muss XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT zurückgeben, wenn die XrSpatialReferenceImageEXT :: format eines der Eingabe-Referenzbilder nicht von xrEnumerateSpatialReferenceImageFormatsEXT aufgezählt wird.

Die Laufzeit muss XR_ERROR_SPATIAL_IMAGE_INVALID_EXT zurückgeben, wenn das XrSpatialReferenceImageEXT :: planes-Array eines der Eingabereferenzbilder nicht gemäß den Referenzbildmetadaten von XrSpatialReferenceImageEXT ausgewertet werden kann.

Die Laufzeit muss XR_ERROR_SPATIAL_IMAGE_INVALID_EXT zurückgeben, wenn das Array XrSpatialReferenceImageEXT :: planes eines der Eingabe-Referenzbilder nicht genau so viele Ebenen wie XrSpatialReferenceImageEXT :: format Farbkanäle hat.

Wenn eine Laufzeit ein Berechtigungssystem erzwingt, um den Zugriff der Anwendung auf die Bild-Tracking-Funktion zu steuern, muss die Laufzeit XR_ERROR_PERMISSION_INSUFFICIENT zurückgeben, wenn diese Berechtigungen der Anwendung nicht gewährt wurden.

Diese Funktion startet einen asynchronen Vorgang und erstellt ein entsprechendes XrFutureEXT , das mit xrPollFutureEXT und zugehörigen Funktionen verwendet werden kann. Der Rückgabewert dieser Funktion gibt nur an, ob die Parameter für die Planung des asynchronen Vorgangs akzeptabel waren. Die entsprechende Abschlussfunktion ist xrCreateSpatialImageTrackingDatabaseCompleteEXT. Sie kann verwendet werden, wenn sich ein Future aus dieser Funktion im Status READY befindet. Die Ausgaben werden von dieser Funktion in der Abschlussstruktur XrCreateSpatialImageTrackingDatabaseCompletionEXT ausgefüllt.

Gültige Verwendung (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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrSpatialImageTrackingDatabaseCreateInfoEXT ist so definiert:

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • spatialReferenceImageCount ist die Anzahl der Elemente im Array spatialReferenceImages.
  • spatialReferenceImages ist ein Array von XrSpatialReferenceImageEXT .

Die Struktur XrSpatialImageTrackingDatabaseCreateInfoEXT beschreibt die Informationen zum Erstellen eines XrSpatialImageTrackingDatabaseEXT-Handles.

Jede XrSpatialImageTrackingDatabaseEXT muss mit mindestens einem XrSpatialReferenceImageEXT im Array XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages erstellt werden.

Gültige Verwendung (implizit)

Die Funktion xrCreateSpatialImageTrackingDatabaseCompleteEXT ist so definiert:

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

Parameterbeschreibungen

xrCreateSpatialImageTrackingDatabaseCompleteEXT schließt den asynchronen Vorgang ab, der von xrCreateSpatialImageTrackingDatabaseAsyncEXT gestartet wurde.

Die Laufzeit darf nach Abschluss des Aufrufs von xrCreateSpatialImageTrackingDatabaseAsyncEXT nicht auf XrSpatialReferenceImagePlaneEXT :: buffer-Zeiger zugreifen, die vom Eingabearray XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages für diesen Aufruf bereitgestellt wurden. Die Anwendung kann alle XrSpatialReferenceImagePlaneEXT :: buffer-Daten freigeben, nachdem xrCreateSpatialImageTrackingDatabaseAsyncEXT abgeschlossen wurde, um den Speicherbedarf zu reduzieren.

Die Laufzeit muss XR_ERROR_FUTURE_PENDING_EXT zurückgeben, wenn future nicht im Status „Bereit“ ist. Die Laufzeit muss XR_ERROR_FUTURE_INVALID_EXT zurückgeben, wenn future bereits abgeschlossen oder abgebrochen wurde.

Gültige Verwendung (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 Struktur XrCreateSpatialImageTrackingDatabaseCompletionEXT ist so definiert:

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

Mitgliederbeschreibungen

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
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

Wenn futureResult ein Erfolgscode ist, muss database ein gültiges Handle sein. Wenn database gültig ist, bleibt es nur innerhalb des Lebenszyklus von xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session oder bis die Anwendung database mit xrDestroySpatialImageTrackingDatabaseEXT zerstört, je nachdem, was zuerst eintritt.

Gültige Verwendung (implizit)

Datenbank für räumliches Bild-Tracking löschen

Die Funktion xrDestroySpatialImageTrackingDatabaseEXT ist so definiert:

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

Parameterbeschreibungen

Die Anwendung kann die Funktion xrDestroySpatialImageTrackingDatabaseEXT aufrufen, um das Handle database und die zugrunde liegenden Ressourcen freizugeben, wenn die Aufgaben zur Erkennung und Aktualisierung von räumlichen Bildern abgeschlossen sind.

Die Anwendung kann die Funktion xrDestroySpatialImageTrackingDatabaseEXT aufrufen, bevor sie xrDestroySpatialContextEXT aufruft. Die Laufzeit darf keine Bilder mehr melden, die von dieser zerstörten XrSpatialImageTrackingDatabaseEXT verwaltet werden. Die Laufzeit muss weiterhin Images melden, die von anderen Datenbanken verwaltet werden.

Die Laufzeit muss dafür sorgen, dass von xrCreateSpatialDiscoverySnapshotCompleteEXT zurückgegebene Erkennungs-Snapshots keine Bilder enthalten, die zu zerstörten oder anderweitig ungültigen XrSpatialImageTrackingDatabaseEXT-Handles gehören, auch wenn das Handle zerstört wurde, nachdem die Anwendung xrCreateSpatialDiscoverySnapshotAsyncEXT aufgerufen hat. Da die Daten in einem räumlichen Snapshot unveränderlich sind, sollte die Anwendung alle vor der Zerstörung von database erstellten XrSpatialSnapshotEXT-Handles zerstören. Andernfalls kann die Anwendung bei Verwendung von xrQuerySpatialComponentDataEXT ungültige XrSpatialImageTrackingDatabaseEXT-Handles erhalten.

Die Anwendung kann die Funktion xrDestroySpatialContextEXT aufrufen, um das XrSpatialContextEXT-Handle freizugeben, bevor die XrSpatialImageTrackingDatabaseEXT-Handles gelöscht werden, mit denen XrSpatialContextEXT erstellt wurde. Die Laufzeit darf diese XrSpatialImageTrackingDatabaseEXT-Handles nicht implizit löschen, wenn der XrSpatialContextEXT gelöscht wird.

Wenn die Lebensdauer von XrSpatialContextEXT und XrSpatialImageTrackingDatabaseEXT unabhängig voneinander verwaltet wird, können Anwendungen zuvor erstellte XrSpatialImageTrackingDatabaseEXT-Handles wiederverwenden, ohne dass der aufwendige Erstellungsvorgang wiederholt werden muss.

Wenn Sie beispielsweise einen XrSpatialContextEXT löschen und anschließend einen anderen XrSpatialContextEXT mit derselben XrSpatialImageTrackingDatabaseEXT neu erstellen, können Sie das Bild-Tracking pausieren und fortsetzen, ohne ein weiteres Initialisierungsverfahren durchführen zu müssen.

Gültige Verwendung (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

Unterstützte Eingabebildformate

Anwendungen sollten xrEnumerateSpatialReferenceImageFormatsEXT aufrufen, um die Liste der unterstützten Eingabe-Referenzbildformate abzurufen.

Die Funktion xrEnumerateSpatialReferenceImageFormatsEXT ist so definiert:

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

Parameterbeschreibungen

  • instance ist ein Handle für eine XrInstance .
  • systemId ist die XrSystemId, deren Eingabereferenzbildformate aufgezählt werden.
  • capability ist die XrSpatialCapabilityEXT, für die die Eingabereferenzbildformate aufgezählt werden.
  • formatCapacityInput ist die Kapazität des formats-Arrays oder 0, um eine Anfrage zum Abrufen der erforderlichen Kapazität anzugeben.
  • formatCountOutput ist die Anzahl der Formate oder die erforderliche Kapazität, falls formatCapacityInput nicht ausreicht.
  • formats ist ein Array von XrSpatialReferenceImageFormatEXT . Er kann NULL sein, wenn formatCapacityInput 0 ist.
  • Eine detaillierte Beschreibung zum Abrufen der erforderlichen formats-Größe finden Sie im Abschnitt Parameter für die Puffergröße.

Die Anwendung kann die Liste der Eingabereferenzbildformate, die von einem bestimmten XrSystemId für eine bestimmte XrSpatialCapabilityEXT unterstützt werden, mit xrEnumerateSpatialReferenceImageFormatsEXT auflisten.

Die Laufzeit darf die Formate von Erweiterungen, die nicht für instance aktiviert sind, nicht auflisten.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Eine vollständige Liste aller Referenzbildformate, die von Erweiterungen unterstützt werden, finden Sie unter XrSpatialReferenceImageFormatEXT.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

Die Aufzählung XrSpatialReferenceImageFormatEXT gibt die Eingabeformate für Referenzbilder an, die die Laufzeit möglicherweise unterstützt.

Mindestens der Wert XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT und der Wert XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT müssen unterstützt werden.

Die Enumeranten haben die folgende Bedeutung:

Beschreibungen der Enumeranten

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT: Ein RGBA-Zwischenspeicher. Das Format gibt keine Garantien hinsichtlich des Layouts der Pixeldaten im Arbeitsspeicher. Auf die Pixel muss über die Metadaten der entsprechenden XrSpatialReferenceImagePlaneEXT-Strukturen zugegriffen werden. Jeder Pixel-Farbkanal hat eine Größe von 8 Bit, sodass jedes Pixel 32 Bit groß ist.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT: Ein RGB-Zwischenspeicher. Das Format gibt keine Garantien hinsichtlich des Layouts der Pixeldaten im Arbeitsspeicher. Auf die Pixel muss über die Metadaten der entsprechenden XrSpatialReferenceImagePlaneEXT-Strukturen zugegriffen werden. Jeder Pixel-Farbkanal hat eine Größe von 8 Bit, sodass jedes Pixel 24 Bit groß ist.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT: Ein YUV-Zwischenspeicher, der mit dem 4:2:0-Muster-Chroma-Subsampling abgetastet wird. Das Format gibt keine Garantien hinsichtlich des Layouts der Pixeldaten im Arbeitsspeicher. Auf die Pixel muss über die Metadaten der entsprechenden XrSpatialReferenceImagePlaneEXT-Strukturen zugegriffen werden. Jeder decodierte RGB-Pixel-Farbkanal hat eine Größe von 8 Bit, sodass jedes Pixel 24 Bit groß ist.

Einstellungen für das Tracking von räumlichen Bildern

Diese Erweiterung bietet optionale Strukturen, mit denen die Anwendung die Bild-Tracking-Funktion konfigurieren kann.

Optimierung statischer Bilder

Die Struktur XrSpatialImageStaticOptimizationEXT ist so definiert:

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • optimizeForStaticImage ist ein XrBool32, der angibt, ob sich Bilder bewegen oder nicht. Der Wert XR_TRUE gibt an, dass sich Bilder nicht bewegen.

Wenn XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT von xrEnumerateSpatialCapabilityFeaturesEXT für die Funktion XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT aufgezählt wird, kann die Anwendung XrSpatialImageStaticOptimizationEXT mit der Kette XrSpatialImageTrackingDatabaseCreateInfoEXT :: next oder XrSpatialReferenceImageEXT :: next verketten.

Wenn die Anwendung XrSpatialImageStaticOptimizationEXT mit der Struktur XrSpatialImageTrackingDatabaseCreateInfoEXT verknüpft, muss die Laufzeit davon ausgehen, dass alle Bilder dieser XrSpatialImageTrackingDatabaseEXT statisch sind, wenn optimizeForStaticImage auf XR_TRUE gesetzt ist. Dementsprechend muss die Laufzeit davon ausgehen, dass alle Bilder dieser XrSpatialImageTrackingDatabaseEXT nicht statisch sind, wenn optimizeForStaticImage auf XR_FALSE festgelegt ist.

Wenn die Anwendung XrSpatialImageStaticOptimizationEXT mit der Struktur XrSpatialReferenceImageEXT verkettet, muss die Laufzeit davon ausgehen, dass dieses Referenzbild statisch ist, wenn optimizeForStaticImage auf XR_TRUE gesetzt ist. Entsprechend muss die Laufzeit davon ausgehen, dass dieses Referenzbild nicht statisch ist, wenn optimizeForStaticImage auf XR_FALSE gesetzt ist. Wenn die Struktur XrSpatialImageStaticOptimizationEXT mit der Struktur XrSpatialReferenceImageEXT verkettet wird, hat dies Vorrang vor der Verkettung mit der Struktur XrSpatialImageTrackingDatabaseCreateInfoEXT.

Wenn XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT nicht von xrEnumerateSpatialCapabilityFeaturesEXT für die Funktion XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT aufgezählt wird und die Anwendung eine XrSpatialImageStaticOptimizationEXT-Struktur mit einer der anwendbaren nächsten Ketten verknüpft, muss die Laufzeit XR_ERROR_VALIDATION_FAILURE von xrCreateSpatialImageTrackingDatabaseAsyncEXT zurückgeben.

Dadurch kann die Laufzeit möglicherweise eine genauere Pose und Größe generieren.

Dadurch kann die Laufzeit den Stromverbrauch senken.

Gültige Verwendung (implizit)

Breite des Referenzbilds

Die Struktur XrSpatialImageSizeEXT ist so definiert:

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • physicalWidth ist ein float-Wert, der die festzulegende physische Breite in Metern darstellt.

Wenn XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT von xrEnumerateSpatialCapabilityFeaturesEXT für die Funktion XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT aufgezählt wird, kann die Anwendung XrSpatialImageSizeEXT mit XrSpatialImageTrackingDatabaseCreateInfoEXT :: next oder XrSpatialReferenceImageEXT :: next verknüpfen.

Wenn die Anwendung XrSpatialImageSizeEXT mit der Struktur XrSpatialImageTrackingDatabaseCreateInfoEXT verknüpft, muss die Laufzeit davon ausgehen, dass alle Bilder dieser XrSpatialImageTrackingDatabaseEXT eine Breite von physicalWidth Metern und eine Höhe gemäß dem Seitenverhältnis haben, das implizit über XrSpatialReferenceImageEXT :: width und XrSpatialReferenceImageEXT :: height bereitgestellt wird.

Wenn die Anwendung XrSpatialImageSizeEXT mit der Struktur XrSpatialReferenceImageEXT verknüpft, muss die Laufzeit davon ausgehen, dass dieses Referenzbild eine Breite von physicalWidth Metern und eine Höhe gemäß dem Seitenverhältnis hat, das implizit durch XrSpatialReferenceImageEXT :: width und XrSpatialReferenceImageEXT :: height angegeben wird. Wenn die Struktur XrSpatialImageSizeEXT mit der Struktur XrSpatialReferenceImageEXT verkettet wird, hat dies Vorrang vor der Verkettung mit der Struktur XrSpatialImageTrackingDatabaseCreateInfoEXT.

Dadurch kann die Laufzeit eine genauere Pose und Größe zurückgeben.

Die Laufzeit muss entweder XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT oder XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT oder beides aufzählen.

Wenn XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT von xrEnumerateSpatialCapabilityFeaturesEXT aufgezählt wird, muss die Laufzeit automatisch Bildgrößen für Bilder bereitstellen, für die die Anwendung keine XrSpatialImageSizeEXT-Strukturen als Teil einer der anwendbaren nächsten Ketten bereitgestellt hat.

Damit die Laufzeitumgebung Bildgrößen automatisch und genau generieren kann, sind möglicherweise bestimmte Gerätefunktionen und Voraussetzungen erforderlich, z.B. Stereokameras und genau kalibrierte extrinsische und intrinsische Kameraparameter.

Wenn XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT nicht von xrEnumerateSpatialCapabilityFeaturesEXT aufgezählt wird, muss die Anwendung XrSpatialImageSizeEXT-Strukturen in die entsprechenden nächsten Ketten einbinden, sodass für alle Bilder eine explizite Größe angegeben wird. Andernfalls muss die Laufzeit XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT von xrCreateSpatialImageTrackingDatabaseAsyncEXT zurückgeben.

Gültige Verwendung (implizit)

Die Struktur XrSpatialCapabilityConfigurationImageTrackingEXT ist so definiert:

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • capability ist ein XrSpatialCapabilityEXT und muss XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT sein.
  • enabledComponentCount ist ein uint32_t, der die Anzahl der Elemente in enabledComponents angibt.
  • enabledComponents ist ein Array von XrSpatialComponentTypeEXT, das die Komponenten angibt, die für diese Funktion aktiviert werden sollen.
  • imageTrackingDatabaseCount ist ein unint32_t, der die Anzahl der Elemente in imageTrackingDatabases angibt.
  • imageTrackingDatabases ist ein Array von XrSpatialImageTrackingDatabaseEXT-Handles, die die Bild-Tracking-Datenbanken angeben, die für den räumlichen Kontext aktiviert werden sollen.

Wenn das Bild-Tracking unterstützt wird, muss die Laufzeit das Bild-Tracking aktivieren, wenn eine XrSpatialCapabilityConfigurationImageTrackingEXT-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs beim Aufruf von xrCreateSpatialContextAsyncEXT übergeben wird.

Mit der Struktur XrSpatialCapabilityConfigurationImageTrackingEXT kann die Anwendung die Referenzbilder erkennen, die durch die XrSpatialImageTrackingDatabaseEXT-Handles in imageTrackingDatabases dargestellt werden.

Die Laufzeit muss XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT zurückgeben, wenn XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT nicht von xrEnumerateSpatialCapabilitiesEXT aufgezählt wird.

Gültige Verwendung (implizit)

Referenzbild für die räumliche Struktur

Die Struktur XrSpatialReferenceImagePlaneEXT ist so definiert:

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

Parameterbeschreibungen

  • bufferSize ist die Größe des buffer-Arrays.
  • buffer ist ein Array von uint8_t-Daten, die die Ebenendaten darstellen.
  • rowStride ist der Byte-Abstand zwischen zwei Startpositionen aufeinanderfolgender Pixeldaten-Zeilen.
  • pixelStride ist der Byte-Abstand zwischen zwei aufeinanderfolgenden Pixeln.

Die Laufzeit muss gemäß den Mustern, die die Parameter rowStride und pixelStride bereitstellen, auf buffer zugreifen.

Die Anwendung muss rowStride und pixelStride so festlegen, dass nur relevante Pixel dieser XrSpatialReferenceImagePlaneEXT von der Laufzeit extrahiert werden.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_EXT_spatial_image_tracking muss aktiviert sein, bevor XrSpatialReferenceImagePlaneEXT verwendet werden kann.
  • buffer muss ein Zeiger auf ein Array von bufferSize uint8_t-Werten sein.
  • Der Parameter bufferSize muss größer als 0 sein.

Die Struktur XrSpatialReferenceImageEXT ist so definiert:

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

Parameterbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • width ist die Pixelbreite des Referenzbilds.
  • height ist die Pixelhöhe des Referenzbilds.
  • format ist ein XrSpatialReferenceImageFormatEXT, das das Format des Bildes darstellt.
  • planeCount ist die Anzahl der Elemente im Array planes.
  • planes ist ein Array von XrSpatialReferenceImagePlaneEXT-Strukturen, die die Ebenen der Bilddaten darstellen.

Die Anwendung kann eine oder mehrere XrSpatialReferenceImageEXT-Strukturen erstellen, die jeweils ein einzelnes Eingabe-Referenzbild darstellen, das über XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages an die Funktion xrCreateSpatialImageTrackingDatabaseAsyncEXT übergeben wird, wenn ein XrSpatialImageTrackingDatabaseEXT-Handle erstellt wird.

Die XrSpatialReferenceImagePlaneEXT :: buffer-Daten müssen von der Anwendung in einer Pixelreihenfolge von links nach rechts und von oben nach unten bereitgestellt werden.

Die Anwendung muss für jeden Farbkanal des XrSpatialReferenceImageEXT :: format eine XrSpatialReferenceImagePlaneEXT-Struktur im XrSpatialReferenceImageEXT :: planes-Array bereitstellen.

Gültige Verwendung (implizit)

Garantierte Komponenten

Eine Laufzeit, die XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT unterstützt, muss die folgenden räumlichen Komponenten als garantierte Komponenten aller Entitäten bereitstellen, die von diesen Funktionen erkannt werden, und sie in xrEnumerateSpatialCapabilityComponentTypesEXT auflisten:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

2D-Bildkomponente

Komponentenlistenstruktur zum Abfragen von Daten

Die Struktur XrSpatialComponentImage2DListEXT ist so definiert:

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

Parameterbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • imageCount ist die Anzahl der Elemente im Array images.
  • images ist ein Array von XrSpatialImage2DDataEXT .

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrQuerySpatialComponentDataEXT zurückgeben, wenn XrSpatialComponentImage2DListEXT in der XrSpatialComponentDataQueryResultEXT :: next-Kette enthalten ist, aber XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT nicht in XrSpatialComponentDataQueryConditionEXT :: componentTypes enthalten ist.

Die Laufzeit muss XR_ERROR_SIZE_INSUFFICIENT von xrQuerySpatialComponentDataEXT zurückgeben, wenn imageCount kleiner als XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput ist.

Gültige Verwendung (implizit)

Komponentendaten

Die Struktur XrSpatialImage2DDataEXT ist so definiert:

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

Parameterbeschreibungen

Die Anwendung kann imageTrackingDatabase verwenden, um zu ermitteln, welche zuvor erstellte XrSpatialImageTrackingDatabaseEXT das Referenzbild dieser XrSpatialImage2DDataEXT-Struktur enthält. Für diese XrSpatialImageTrackingDatabaseEXT kann die Anwendung referenceImageIndex verwenden, um das XrSpatialReferenceImageEXT dieser XrSpatialImage2DDataEXT-Struktur zu identifizieren, indem sie es mit der Eingabereihenfolge des Arrays XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages abgleicht.

Die Gruppe von Referenzbildern, die durch die Gruppe aller aktiven Datenbanken definiert wird, sollte keine doppelten Bilder enthalten. Wenn Sie doppelte Bilder einfügen, kann dies zu Problemen bei der Erkennung oder beim Tracking führen, d.h., es werden inkonsistente oder mehrere Indexe zurückgegeben.

Gültige Verwendung (implizit)

Konfiguration

Wenn XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT in XrSpatialCapabilityComponentTypesEXT :: componentTypes für eine bestimmte Funktion aufgeführt ist, kann die Anwendung sie aktivieren, indem sie den Enum-Wert in die Liste XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents aufnimmt. Für diese Komponente ist keine spezielle Konfiguration erforderlich, um in die nächste Kette von XrSpatialCapabilityConfigurationBaseHeaderEXT aufgenommen zu werden.

Begrenzte 2D-Komponente

Die begrenzte 2D-Komponente liefert den Mittelpunkt und die Ausdehnung des räumlichen Bildes, das durch die Entität dargestellt wird, auf der sie sich befindet. Weitere Informationen zur Komponente „Bounded 2D“ finden Sie unter Bounded 2D.

Beispiel-Code

Räumliche Bilder entdecken und Komponentendaten abfragen

Im folgenden Beispielcode wird gezeigt, wie Sie räumliche Entitäten für die Bild-Tracking-Funktion erkennen und die zugehörigen Komponentendaten abfragen.

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

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrFrameState frameState;  // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

Neue Objekttypen

Neue Befehle

Neue Gebäude

Neue Enums

Neue Enum-Konstanten

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • Erweiterung von XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • Erweiterung von XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • Erweiterung von XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • Erweiterung von XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • Erweiterung von XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • Erweiterung von XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

Probleme

Versionsverlauf

  • Version 1, 22.04.2025 (Daniel Guttenberg, Qualcomm)

    • Anfängliche Beschreibung der Erweiterung